diff --git a/.gitignore b/.gitignore index 812e74f..0aca52f 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,15 @@ TASKS.md .bmad-loop/cache/ .bmad-loop/policy.toml _bmad/render/ + +# Keep durable BMAD planning and acceptance evidence in Git. +# Runtime, rendered workflows and party-mode sessions remain local. +!/_bmad-output/ +/_bmad-output/* +!/_bmad-output/project-context.md +!/_bmad-output/planning-artifacts/ +!/_bmad-output/planning-artifacts/** +!/_bmad-output/implementation-artifacts/ +!/_bmad-output/implementation-artifacts/** +!/_bmad-output/test-artifacts/ +!/_bmad-output/test-artifacts/** diff --git a/_bmad-output/implementation-artifacts/1-1-capability-inventory.md b/_bmad-output/implementation-artifacts/1-1-capability-inventory.md new file mode 100644 index 0000000..5468af5 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-1-capability-inventory.md @@ -0,0 +1,345 @@ +--- +baseline_commit: c30461cc92491ebe3d527e125a1657b73fa67006 +--- + +# Story 1.1: Создать исполняемый контракт Capability Inventory + +Status: done + + + +## Story + +As a владелец релиза, +I want иметь версионируемый и автоматически проверяемый формат Capability Inventory, +so that текущие и целевые продуктовые flows нельзя потерять, ошибочно объявить готовыми или вывести за Community scope. + +## Requirements and Quality Mapping + +- **Primary requirement:** FR-46. +- **Applicable NFRs:** NFR-S2 (secrets absent from reports/exports), NFR-S4 (bounded input/output and resource use), NFR-S8 (bounded valid UTF-8/JSON diagnostics plus malformed/oversized negatives), NFR-O5 (redaction regression for JSON/errors), NFR-C1 (no incidental Rust MSRV, Edition, dependency, workspace or wire-contract change; the owner-approved transitive advisory remediation recorded below is the sole narrow exception), NFR-C4 (new user-facing scope text is synchronized in RU and EN). +- **Architecture decisions:** AD-1 (existing executable boundary checks remain authoritative), AD-20/AR-29 (Inventory is release evidence foundation; first enabling change updates Community docs, project context, guardrails and tests; an allow marker cannot bypass the contract). +- **Primary risk:** E1-R-001, score 9 — a false or incomplete Inventory can hide product gaps and regressions. + +## Acceptance Criteria + +1. **Schema contract** + - **Given** утверждённые PRD, SPEC и Architecture Spine + - **When** создаётся schema Capability Inventory + - **Then** она требует для каждого flow уникальный ID, тип `ui | api | mcp`, связанный FR, пользовательский outcome, owner, статус реализации и ссылки на automated/manual evidence + - **And** поддерживает только `implemented | planned | gap | blocked`; последние три состояния не считаются pass. + +2. **Fail-closed validator** + - **Given** machine-readable Capability Inventory + - **When** CI запускает validator + - **Then** отсутствующий обязательный FR, duplicate ID, неизвестный status/type, битая evidence-ссылка, отсутствующее обязательное поле или flow без owner завершают проверку ошибкой + - **And** validator выдаёт детерминированный, сортированный, bounded report без чувствительных данных. + +3. **Community scope expansion without scope creep** + - **Given** намеренное расширение Community scope + - **When** обновляются executable scope guardrails + - **Then** `resources`, `prompts`, `tasks` и `load_runs` распознаются как разрешённые целевые возможности + - **And** `multi_workspace`, `enterprise_rbac`, `sso`, `non_rest_upstream` и `arbitrary_distributed_load_targets` остаются запрещены. + +4. **New/untracked files are checked explicitly** + - **Given** новые или untracked файлы scope guardrails и Inventory + - **When** выполняется проверка Community scope + - **Then** новые файлы передаются scanner явно и покрываются positive/negative tests + - **And** текст `community-scope: allow=...` не позволяет обойти semantic Community contract. + +5. **Documentation tells the truth** + - **Given** изменение executable Community boundary + - **When** Story завершается + - **Then** синхронно обновлены tracked Community documentation и локальный `_bmad-output/project-context.md` + - **And** Inventory и документация не утверждают, что planned target capabilities уже реализованы. + +6. **Regression-safe completion** + - **Given** реализация Story + - **When** выполняются обязательные проверки + - **Then** проходят targeted Inventory tests, boundary/scope tests, canonical CI/release gates и `just verify` + - **And** Rust toolchain, dependency manifests, workspace boundaries, UI/runtime/database surfaces и существующие wire-контракты не изменяются попутно; допускается только явно одобренное владельцем transitive lockfile security remediation при полном `cargo deny` и `just verify` evidence. + +## Tasks / Subtasks + +- [x] **1. Создать versioned schema и минимальный canonical seed** (AC: 1, 3, 5) + - [x] Создать `docs/schemas/capability-inventory.schema.json` как JSON Schema Draft 2020-12 с `schema_version: 1`, product identity, обязательными полями `flows[]`, численными bounds из External Contract и закрытыми enum для type/status. + - [x] Описать structured evidence (`automated`, `manual`) с `minItems: 1` для каждого вида и закрытый capability-family vocabulary `tools | resources | prompts | tasks | load_runs`; не смешивать implementation status с качеством/типом evidence. + - [x] Создать `docs/capability-inventory.json` с минимальными честными entries для `resources`, `prompts`, `tasks`, `load_runs` в состоянии `planned`, `gap` или `blocked`; не выполнять полный brownfield baseline Story 1.2. + - [x] Связать seed с FR-46 и релевантными product FR, но в gate Story 1.1 требовать только явно зафиксированный начальный набор (`FR-46`); расширение до полного FR-1..FR-54 baseline принадлежит Story 1.2. + - [x] Для non-implemented entries использовать существующие tracked evidence контракта/плана: automated — `tests/unit/test_validate_capability_inventory.py`, manual — обновлённые `README.md`/`docs/intro.md`/`docs/en/README.md`; не ссылаться из canonical Inventory на `_bmad-output`, `/tmp`, build output или иной отсутствующий в clean checkout artifact. + - [x] Трактовать capability как семейство product/protocol surface, а не как перечень всех экранов/use cases: Story 1.2 представляет Operations, Agents, approvals, history и import отдельными flows с подходящим family value, не меняя schema. + +- [x] **2. Реализовать stdlib-only validator CLI** (AC: 1, 2) + - [x] Создать `scripts/validate-capability-inventory.py` с `--root`, `--inventory`, `--schema` и repeatable `--required-fr`. + - [x] Читать и проверять schema/inventory как JSON без новой Python-зависимости; schema должна объявлять `https://json-schema.org/draft/2020-12/schema`, а semantic validator — обеспечивать тот же внешний контракт без попытки реализовать универсальный JSON Schema engine. + - [x] Проверять canonical schema по известным JSON pointers: dialect, required fields, enum и bounds должны совпадать с semantic constants; missing/divergent contract завершается `INVALID_SCHEMA_CONTRACT`, malformed schema — `INVALID_SCHEMA`. `--schema` не может быть декоративным аргументом. + - [x] Проверять обязательные поля, ID uniqueness, type/status/capability enums, owner/outcome/requirements и required-FR completeness. + - [x] Принимать `--inventory`, `--schema` и evidence только как normalized repository-relative logical paths к существующему regular non-symlink file внутри resolved `--root`; отклонять absolute path, `..`, directory, missing path и любой symlink. + - [x] Выдавать stable machine codes, включая `DUPLICATE_FLOW_ID`, `UNKNOWN_STATUS`, `UNKNOWN_FLOW_TYPE`, `MISSING_OWNER`, `MISSING_REQUIRED_FIELD`, `MISSING_REQUIRED_FR`, `BROKEN_EVIDENCE_LINK`, `FORBIDDEN_COMMUNITY_CAPABILITY`, `INVALID_JSON`, `INVALID_SCHEMA`, `INVALID_SCHEMA_CONTRACT`, `INPUT_TOO_LARGE`, `LIMIT_EXCEEDED`. + - [x] Сортировать machine diagnostics по `(code, json_pointer)` независимо от JSON ordering; ограничить полный stderr-report 65,536 bytes, включая deterministic truncation marker; не печатать raw inventory, user outcome/payload, secret canary, resolved host path или произвольное invalid value. + - [x] Success summary является CLI contract: `Capability inventory validation passed total= implemented= planned= gap= blocked= pass=`; `pass` равен только числу `implemented`. + +- [x] **3. Укрепить executable Community boundary** (AC: 3, 4) + - [x] Расширить `scripts/check-community-scope.py`, сохранив текущие deterministic traversal, binary/default exclusions и exact same-line allow semantics. + - [x] Explicit input должен fail closed для missing, absolute/outside-root и symlink paths; после 4,096-byte binary probe текст сканируется streaming line-by-line без `read_bytes()` всего файла, а findings ограничены теми же `MAX_DIAGNOSTICS` и 65,536-byte report budget. + - [x] Разрешить exact target identifiers `resources`, `prompts`, `tasks`, `load_runs`, не ослабляя запреты текущего checker-а. + - [x] Сохранить безопасный default wrapper-а `scripts/check-community-scope.sh` для tracked-файлов; новые Story-файлы проверять отдельным explicit `--files` вызовом, не захватывая чужие локальные untracked paths (например `.agents/`). + - [x] Не исключать validator, Inventory или schema целиком. Каждое необходимое enforcement/fixture упоминание forbidden marker получает только узкую same-line annotation (`# community-scope: allow=sso` либо точный соответствующий marker); semantic validator всё равно обязан отвергать capability. + - [x] Добавить positive/negative regressions в `tests/unit/test_check_community_scope.py`, включая невозможность semantic allow-marker bypass и явную обработку existing outside-root path, absolute path, internal symlink и symlink-to-outside. + +- [x] **4. Активировать ATDD-сценарии RED → GREEN** (AC: 1–5) + - [x] Сохранить подготовленный `tests/unit/test_validate_capability_inventory.py`; не пересоздавать его и не оставлять acceptance scenarios скрытыми за `@unittest.skip(RED_PHASE)` после реализации. + - [x] Активировать по одному сценарию, сначала наблюдать ожидаемый RED, затем реализовывать минимальное поведение до GREEN. + - [x] Сохранить исходные 10 contract scenarios и добавить отдельные active cases для malformed inventory/schema JSON, missing/wrong schema dialect/contract, document/collection/string overflow и stable codes `INVALID_JSON`, `INVALID_SCHEMA`, `INVALID_SCHEMA_CONTRACT`, `INPUT_TOO_LARGE`, `LIMIT_EXCEEDED`. + - [x] Исправить evidence containment fixture: создать реально существующий файл вне temporary root; отдельно проверить existing absolute path, internal symlink и symlink-to-outside. Missing-file failure не считается доказательством containment. + - [x] Усилить deterministic-report test: требовать непустой exact sorted prefix из `(code, json_pointer)`, ожидаемое число diagnostics и deterministic truncation marker; пустой список найденных flow diagnostics не может пройти тест. + - [x] Добавить active meta-test/guardrail, который через runtime/AST inspection других Story 1.1 test methods завершается ошибкой при любом `unittest.skip` decorator или `__unittest_skip__ == True`. Во время task-by-task TDD запускать конкретный method; полный module/CI обязан стать GREEN только после снятия всех skips и удаления больше не нужного RED marker/constant. + - [x] Удалить `PROJECT_CONTEXT` из committed canonical assertions и loops. В clean CI проверять tracked `README.md`, `docs/README.md`, `docs/intro.md`, `docs/en/README.md`, Inventory и schema; обновление ignored `_bmad-output/project-context.md` проверять отдельной локальной evidence-командой и фиксировать в Dev Agent Record, без conditional skip. + - [x] Для literals `sso`/`enterprise` и других enforcement fixtures использовать точные same-line Community annotations; добавить regression, что textual annotation подавляет только текстовый scanner, но не semantic Inventory verdict. + +- [x] **5. Встроить canonical validation в tooling, CI и release** (AC: 2, 4, 6) + - [x] Добавить `capability-inventory-check` в `justfile` и включить его в `just verify`, не удаляя и не переставляя существующие Rust/scope gates без причины. + - [x] Добавить отдельный canonical Inventory step в `.gitea/workflows/ci.yml` после Python unit tests и до Rust gates. + - [x] В `.gitea/workflows/release.yml` добавить `python3 --version` в runner preflight, затем Python tooling, canonical Inventory и Community scope gates до Cargo/build/package, чтобы tag workflow не обходил Story contract. + - [x] Canonical command должен явно проверять `FR-46`; полный обязательный FR baseline вводит Story 1.2. + +- [x] **6. Синхронизировать документацию и выполнить handoff checks** (AC: 4–6) + - [x] Обновить `README.md`, `docs/README.md`, `docs/intro.md`, `docs/en/README.md`, `CONTRIBUTING.md` и `scripts/README.md`: дать ссылки на Inventory/schema, объяснить четыре status semantics, синхронизировать новый пользовательский текст RU/EN, отделить «реализовано сейчас» от «разрешено как target» и описать explicit untracked scan. + - [x] Обновить локальный `_bmad-output/project-context.md`; не менять пользовательский `.gitignore` и не force-add ignored BMAD artifacts. + - [x] Явно передать scope scanner все NEW/UPDATE tracked paths до их staging/tracking. + - [x] Выполнить команды evidence из раздела Testing и убедиться, что в diff нет Cargo/npm/toolchain/wire/UI/runtime/database изменений, кроме явно одобренного security-only `Cargo.lock` remediation с полным compatibility gate. + +### Review Findings + +- [x] [Review][Patch][Medium] Security update применён после уточнения владельца: `event-listener` обновлён с 5.4.1 до 5.4.2 в `Cargo.lock`; `cargo deny` и полный `just verify` проходят без RUSTSEC-2026-0221. +- [x] [Review][Patch][High] Валидировать каждый explicit scope path до применения default exclusions; сейчас missing/symlink/traversal под `LICENSE`/`target/` проходит как успешно просканированный [scripts/check-community-scope.py:139] +- [x] [Review][Patch][High] Закрыть schema/semantic drift: проверять root/evidence required, типы, refs, minLength и остальные исполняемые schema keywords; malformed required arrays должны давать `INVALID_SCHEMA_CONTRACT`, а не `TypeError` [scripts/validate-capability-inventory.py:136] +- [x] [Review][Patch][High] Преобразовывать `ValueError`/`RecursionError` JSON parser в bounded `INVALID_JSON`/`INVALID_SCHEMA` вместо traceback [scripts/validate-capability-inventory.py:106] +- [x] [Review][Patch][High] Ограничить накопление diagnostics до `MAX_DIAGNOSTICS` с отдельным deterministic omitted counter до сортировки/rendering [scripts/validate-capability-inventory.py:300] +- [x] [Review][Patch][Medium] Отклонять duplicate JSON object members, чтобы security-significant поля не зависели от last-value-wins поведения parser [scripts/validate-capability-inventory.py:122] +- [x] [Review][Patch][Medium] Требовать точный integer `schema_version == 1`; Python boolean `true` не должен проходить как число 1 [scripts/validate-capability-inventory.py:139] +- [x] [Review][Patch][Medium] Помечать truncation внутри одного scope-файла; сейчас после 1000 findings остальные строки пропускаются без marker [scripts/check-community-scope.py:151] +- [x] [Review][Patch][Medium] Отклонять whitespace-only owner/user_outcome и синхронизировать это ограничение со schema contract [scripts/validate-capability-inventory.py:219] +- [x] [Review][Patch][Medium] Добавить заявленные `limit-1 / limit / limit+1` regressions для flow/collection/string/evidence bounds и новых fail-closed случаев [tests/unit/test_validate_capability_inventory.py:276] + +#### Review Round 2 — 2026-08-08 + +- [x] [Review][Patch][High] Отклонять дополнительные assertion/applicator keywords в versioned schema: сейчас root `not: {}` или nested `const` инвертирует Draft 2020-12 contract, но semantic gate продолжает возвращать success [scripts/validate-capability-inventory.py:238] +- [x] [Review][Patch][High] Нормализовать forbidden identifiers перед scope matching: `EnterpriseRbac`, `MultiWorkspace`, `NonRestUpstream` и `ArbitraryDistributedLoadTargets` обходят snake/kebab/space patterns [scripts/check-community-scope.py:28] +- [x] [Review][Patch][Medium] Ограничить объём реально читаемого scope input, включая один newline-free text line, общий размер и количество файлов; output caps не предотвращают exhaustion памяти/времени [scripts/check-community-scope.py:147] +- [x] [Review][Patch][Medium] Запретить C0/control characters в explicit logical paths, иначе legal filename с newline может подделывать строки bounded stderr report [scripts/check-community-scope.py:122] +- [x] [Review][Patch][Medium] Перехватывать `OSError` при binary probe и text scan после path validation, чтобы concurrent replacement/deletion не приводил к traceback и раскрытию host path [scripts/check-community-scope.py:147] +- [x] [Review][Patch][Medium] Fail closed для invalid UTF-8 text вместо `errors="replace"`, иначе запрещённый marker можно разделить invalid byte и обойти scanner [scripts/check-community-scope.py:152] +- [x] [Review][Patch][Medium] Согласовать AC6/NFR-C1, Task 6 и Project Structure с явно одобренным security-only `Cargo.lock` exception и зафиксировать final explicit 16-file scan [Cargo.lock:1113] +- [x] [Review][Patch][Low] Выставлять single-file truncation только после обнаружения 1001-го finding; ровно 1000 findings сейчас ошибочно объявляются truncated [scripts/check-community-scope.py:167] + +## Dev Notes + +### Scope Boundary and Dependencies + +- Это первый blocking element Wave 0 и всего critical path: `1.1 → 1.2 → 1.3 → 1.4 → 1.5 → 1.6`. +- Prerequisites отсутствуют. Story 1.2 зависит от созданных здесь schema/validator и выполняет полный фактический baseline существующих UI/Admin API/MCP flows. +- Story 1.1 создаёт executable contract, но **не** реализует Resources, Prompts, Tasks или Load Runs; не выполняет manual regression, MCP compatibility matrix, signed/content-addressed Evidence Manifest, RC signing или Habr Gate. +- Не добавлять UI/browser journey, Playwright/Pact, Rust crate, migration, endpoint, metric, deployment runtime config или новую dependency. +- `manual-only` в последующей Story 1.2 является характеристикой evidence, а не пятым implementation status. + +### External Contract + +Canonical paths established by ATDD: + +```text +scripts/validate-capability-inventory.py +docs/capability-inventory.json +docs/schemas/capability-inventory.schema.json +``` + +Required flow fields: + +```text +id, type, requirements, user_outcome, owner, status, capabilities, +evidence.automated, evidence.manual +``` + +- **Named limits:** `MAX_DOCUMENT_BYTES = 4_194_304` для каждого inventory/schema JSON; `MAX_FLOWS = 10_000`; `MAX_REQUIREMENTS_PER_FLOW = 64`; `MAX_CAPABILITIES_PER_FLOW = 16`; `MAX_EVIDENCE_LINKS_PER_KIND = 64`; ID/requirement/capability ≤128 Unicode code points, owner ≤256, user outcome и optional notes ≤4,096, repository-relative evidence path ≤1,024; `MAX_DIAGNOSTICS = 1_000`; stderr report ≤65,536 bytes вместе с truncation marker. +- Bounds задаются одновременно в schema и semantic constants и проверяются parity test. Boundary tests используют `limit-1`, `limit`, `limit+1`; существующий 500-flow stress corpus остаётся допустимым. +- Evidence collections `automated` и `manual` обе непустые. Для `planned/gap/blocked` они подтверждают контракт/план/известный пробел, но не превращают capability в implemented. +- Allowed capability-family vocabulary: `tools`, `resources`, `prompts`, `tasks`, `load_runs`. Любое иное значение fail closed; пять явно запрещённых Community capability kinds получают специализированный `FORBIDDEN_COMMUNITY_CAPABILITY`. +- Only `implemented` contributes to `pass`; `planned`, `gap`, and `blocked` must remain visibly non-passing. +- JSON object/array ordering has no product semantics. Human diagnostics must be stable and safe; machine codes are the integration contract. +- Draft 2020-12 is the current published JSON Schema version. Declare the dialect explicitly, but keep runtime validation stdlib-only to preserve Story NFR-C1/dependency constraints. + +### Existing Code to Reuse and Preserve + +- `scripts/check-community-scope.py` already provides the authoritative stdlib CLI with subprocess-backed tracked-file discovery, sorted explicit file traversal, narrow same-line allow directives, binary detection and safe path/line/code diagnostics. Extend it; do not create a competing scope checker. +- `tests/unit/test_check_community_scope.py` is the established stdlib `unittest` + temporary-root + subprocess pattern. Preserve its current six regressions. +- `justfile` already routes `tooling-test` and `community-scope-check` through `verify`; add the canonical gate without replacing `fmt-check`, `clippy`, `test`, dependency or boundary gates. +- `.gitea/workflows/ci.yml` invokes Python tests and scope checks directly rather than `just verify`; it needs a direct canonical step. `.gitea/workflows/release.yml` currently lacks Python/scope checks and must not publish around the new contract. +- Recent `9b1a739` is the closest repository pattern: contract-first artifact, closed vocabulary, bounded untrusted values, dedicated contract tests, boundary checker and docs in one compatible change. + +### File Map + +| Action | Path | Purpose | +|---|---|---| +| NEW | `scripts/validate-capability-inventory.py` | Deterministic stdlib validator CLI | +| NEW | `docs/capability-inventory.json` | Versioned canonical Inventory seed | +| NEW | `docs/schemas/capability-inventory.schema.json` | JSON Schema Draft 2020-12 contract | +| NEW/activate | `tests/unit/test_validate_capability_inventory.py` | Existing untracked 10-scenario RED scaffold | +| UPDATE | `scripts/check-community-scope.py` | Semantic/path-safe bounded Community guardrail | +| UPDATE | `tests/unit/test_check_community_scope.py` | Boundary and bypass regressions | +| UPDATE | `justfile` | Canonical Inventory recipe and `verify` integration | +| UPDATE | `.gitea/workflows/ci.yml` | Canonical gate in normal CI | +| UPDATE | `.gitea/workflows/release.yml` | No release bypass of tooling/scope/Inventory gates | +| UPDATE | `README.md` | Public current-vs-target scope and Inventory link | +| UPDATE | `docs/README.md` | Documentation index for Inventory/schema | +| UPDATE | `docs/intro.md` | RU Community current-vs-target scope | +| UPDATE | `docs/en/README.md` | EN Community current-vs-target scope (NFR-C4) | +| UPDATE | `CONTRIBUTING.md` | Contributor Community boundary and guardrail expectations | +| UPDATE | `scripts/README.md` | Contributor commands and explicit scan behavior | +| LOCAL UPDATE | `_bmad-output/project-context.md` | Agent guardrail; ignored by Git, not a clean-CI dependency | + +### Security and Failure Rules + +- Treat inventory, schema and evidence paths as untrusted input. Resolve containment against `--root`; never follow a symlink outside the repository. +- Explicitly named missing files must fail, not silently pass. Diagnostics use only bounded repository-relative logical paths or JSON pointers; do not expose resolved host paths, raw filenames supplied outside the contract, raw file content, arbitrary JSON values or credentials. +- Enforce every named document/collection/string/diagnostic limit before unbounded allocation or accumulation. Oversized or malformed JSON must terminate safely with valid UTF-8 output and a stable code. +- A textual `community-scope: allow` directive can suppress only the checker’s exact same-line textual fixture marker; it never changes semantic capability allow/deny decisions in Inventory validation. +- Do not exclude Inventory/schema from scope scanning. Narrowly justify test/source fixture markers; never introduce a broad exemption for forbidden product capability names. + +### Testing and Evidence Commands + +Activate one ATDD scenario at a time and retain RED/GREEN evidence in the Dev Agent Record. + +```bash +# During RED/GREEN: run only the activated method; the full module remains red until all skips are removed +python3 -m unittest -v \ + tests.unit.test_validate_capability_inventory.CapabilityInventoryValidatorTests. + +# Final targeted Inventory contract: no skipped Story 1.1 tests permitted +python3 -m unittest discover -s tests/unit \ + -p 'test_validate_capability_inventory.py' -v + +# Existing and extended Community boundary regressions +python3 -m unittest discover -s tests/unit \ + -p 'test_check_community_scope.py' -v + +# Canonical artifact gate for Story 1.1 +python3 scripts/validate-capability-inventory.py \ + --root . \ + --inventory docs/capability-inventory.json \ + --schema docs/schemas/capability-inventory.schema.json \ + --required-fr FR-46 + +# Before new files are tracked/staged: pass every NEW/UPDATE tracked path explicitly +python3 scripts/check-community-scope.py --root . --files \ + scripts/validate-capability-inventory.py \ + docs/capability-inventory.json \ + docs/schemas/capability-inventory.schema.json \ + tests/unit/test_validate_capability_inventory.py \ + scripts/check-community-scope.py \ + tests/unit/test_check_community_scope.py \ + justfile \ + .gitea/workflows/ci.yml \ + .gitea/workflows/release.yml \ + Cargo.lock \ + README.md docs/README.md docs/intro.md docs/en/README.md \ + CONTRIBUTING.md scripts/README.md + +# Local-only project-context evidence; this file is intentionally ignored by Git +rg -n 'docs/capability-inventory.json|planned|gap|blocked' \ + _bmad-output/project-context.md + +# Full repository quality gate +just verify +``` + +- UI build/Playwright is N/A because Story has no UI change. +- Before completion, verify that no active Story 1.1 test remains skipped and that canonical validation is a direct CI **and** release prerequisite. + +### Project Structure Notes + +- Repository-level Python tooling belongs in `scripts/`; its stdlib tests belong in `tests/unit/`, matching the existing Community checker. +- Canonical user-facing artifacts belong under `docs/`; schema lives in the new `docs/schemas/` directory. +- The implementation creates no new Rust module or crate and changes no dependency manifest or npm lockfile. The owner-approved `Cargo.lock` resolution update `event-listener` 5.4.1 → 5.4.2 is the sole security-only exception and is covered by `cargo deny` plus full `just verify`. +- `_bmad-output/` is workflow state ignored by the current user-owned `.gitignore`. Preserve that choice; implementation artifacts remain local unless the owner separately changes repository policy. +- No dedicated UX specification is required for this non-UI foundation. The IR UX warning remains applicable before the first UI-heavy vertical Story. + +### References + +- [Source: `_bmad-output/planning-artifacts/epics.md`, Story 1.1 and Cross-Epic Dependencies] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md`, FR-46, §§5.3–5.5, §§6–7] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md`, Community scope and evidence contract] +- [Source: `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md`, AD-1, AD-20, Consistency Conventions] +- [Source: `_bmad-output/planning-artifacts/implementation-readiness-report-2026-08-08.md`, Required Actions 3–4] +- [Source: `_bmad-output/project-context.md`, Testing Rules and Community Scope Expansion] +- [Source: `_bmad-output/test-artifacts/atdd-checklist-1-1-capability-inventory.md`, Contract Decisions and Implementation Handoff] +- [Source: `_bmad-output/test-artifacts/atdd-summary-1-1-capability-inventory.json`] +- [Source: `tests/unit/test_validate_capability_inventory.py`, RED acceptance scaffold] +- [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12) + +## Dev Agent Record + +### Agent Model Used + +GPT-5 Codex + +### Implementation Plan + +- Реализовать schema/canonical seed и stdlib validator contract-first, активируя acceptance tests по одному. +- Harden существующий Community scanner без нового параллельного guardrail. +- Встроить canonical validation в local/CI/release gates и синхронизировать RU/EN documentation. +- Завершить полным `just verify`, explicit scope scan и clean diff/file-list audit. + +### Debug Log References + +- Task 1 RED: canonical-artifact test failed because `docs/capability-inventory.json` was absent. +- Task 1 GREEN: canonical seed/schema assertions pass; both JSON documents parse successfully. +- Task 2 RED: activated validator contract failed because `scripts/validate-capability-inventory.py` was absent. +- Task 2 GREEN: structural/status/FR/evidence/redaction/schema-drift/limit suites and canonical command pass. +- Task 3 RED: existing scanner accepted forbidden `enterprise_rbac` and unsafe explicit paths. +- Task 3 GREEN: 12 scope regressions, 3 Inventory/scope contract scenarios and explicit Story file scan pass. +- Task 4 RED: tracked documentation scenario failed before Inventory links/status semantics were documented. +- Task 4 GREEN: 23 active acceptance scenarios pass; meta-guard confirms zero skipped Story tests. +- Task 5 RED: repository-contract test found no `capability-inventory-check` recipe or CI/release prerequisites. +- Task 5 GREEN: repository-contract test passes and both Gitea workflow files parse as YAML. +- Task 6 GREEN before review: 44 Python tests, canonical validator, explicit 15-file Community scan, `git diff --check` and full `just verify` passed with a temporary security lockfile update. +- Code review GREEN: all 9 functional review findings fixed; 53 Python tests, canonical validator, explicit Community scan, boundaries, code-health, fmt, clippy and the full Rust workspace suite pass. +- Security review GREEN: owner clarified that the dependency update belongs to review remediation; `event-listener` 5.4.2 is pinned in `Cargo.lock`, RUSTSEC-2026-0221 is cleared, and the final full `just verify` passes. +- Review Round 2 GREEN: all 8 findings fixed; 59 Python tests, canonical validator, explicit 16-file Community scan, dependency audit, fmt, clippy and the complete Rust workspace pass in the final `just verify`. +- Local-only evidence: `_bmad-output/project-context.md` contains the canonical Inventory link and non-passing status semantics; ignored BMAD artifacts were not force-added. +- User-owned `.gitignore` changes and untracked `.agents/` content were preserved and excluded from Story edits/scans. + +### Completion Notes List + +- Added a versioned Draft 2020-12 Capability Inventory schema and an honest planned-only canonical seed for Resources, Prompts, Tasks and Load Runs. +- Added a stdlib-only fail-closed validator with schema parity, closed vocabularies, repository-contained evidence, stable/redacted/bounded diagnostics and implemented-only pass semantics. +- Hardened the Community scope checker against path traversal, symlinks, missing files, semantic allow-marker bypass and unbounded reports while preserving tracked-only default behavior. +- Made the canonical validator mandatory in `just verify`, normal CI and release workflows; synchronized RU/EN contributor and product documentation. +- Completed every Story and repository quality gate. The only dependency change is the authorized transitive security remediation `event-listener` 5.4.1 → 5.4.2; no UI/runtime/database/wire contract changed. +- Closed strict-schema parity and scope-scanner bypass/resource-boundary findings with active regressions; no review action items remain. + +### File List + +- `.gitea/workflows/ci.yml` (modified) +- `.gitea/workflows/release.yml` (modified) +- `CONTRIBUTING.md` (modified) +- `Cargo.lock` (modified: security remediation `event-listener` 5.4.1 → 5.4.2) +- `README.md` (modified) +- `docs/README.md` (modified) +- `docs/capability-inventory.json` (new) +- `docs/en/README.md` (modified) +- `docs/intro.md` (modified) +- `docs/schemas/capability-inventory.schema.json` (new) +- `justfile` (modified) +- `scripts/README.md` (modified) +- `scripts/check-community-scope.py` (modified) +- `scripts/validate-capability-inventory.py` (new) +- `tests/unit/test_check_community_scope.py` (modified) +- `tests/unit/test_validate_capability_inventory.py` (new/activated) +- `_bmad-output/project-context.md` (local ignored update) + +## Change Log + +- 2026-08-08 — Implemented Story 1.1 executable Capability Inventory contract, Community guardrails, CI/release gates, documentation and security audit remediation; moved to review. +- 2026-08-08 — Applied all 9 code-review patches; reverted the security-only lockfile update by owner decision and deferred RUSTSEC-2026-0221 remediation to a separate dependency change; Story returned to in-progress. +- 2026-08-08 — Owner clarified that the security update is part of review remediation; applied `event-listener` 5.4.2, cleared RUSTSEC-2026-0221, passed full `just verify`, and returned Story to review. +- 2026-08-08 — Fresh adversarial review fixed all 8 actionable findings, dismissed 7 out-of-scope/noise findings, passed final full verification, and completed Story 1.1. diff --git a/_bmad-output/implementation-artifacts/1-10-lifecycle-auth-profiles-machine-keys.md b/_bmad-output/implementation-artifacts/1-10-lifecycle-auth-profiles-machine-keys.md new file mode 100644 index 0000000..730ec64 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-10-lifecycle-auth-profiles-machine-keys.md @@ -0,0 +1,503 @@ +--- +story_id: "1.10" +story_key: "1-10-lifecycle-auth-profiles-machine-keys" +requirement: "FR-3" +status: "done" +baseline_commit: "767428436d3a54e60809a727044dfcec48e1f1dd + uncommitted Story 1.7/1.8/1.9 worktree" +created: "2026-08-15T19:09:52+03:00" +--- + +# Story 1.10: Защитить lifecycle Auth Profiles и machine keys + +Status: done + +## Story + +As an администратор, +I want безопасно создавать, ротировать и отзывать credentials, +so that Agents и Operations получают только необходимый доступ без возможности повторно извлечь секрет. + +## Operational Brief + +Story 1.10 закрывает security identity layer поверх уже hardened Operation/runtime/outbound цепочки. После 1.7–1.9 продукт умеет сохранять immutable Operation, выполнять REST через единый typed runtime и защищать outbound network. Теперь надо сделать так, чтобы все credentials, которые питают эти execution paths, имели строгий lifecycle: raw value принимается только на write boundary, хранится только в encrypted/hash форме, раскрывается только один раз, revocation действует без restart, rotation атомарна, а Admin/MCP/approval boundaries не могут использовать чужой тип ключа. + +Значение для плана: это первая половина FR-3. Она делает текущие Auth Profiles, Secrets, MCP keys и approval keys production-safe. Story 1.11 отдельно согласует master-key identity и re-encryption; Story 1.12 отдельно закрывает admin bootstrap/login/session. Нельзя переносить эти будущие задачи внутрь 1.10, но 1.10 должна оставить для них совместимые audit/status/version contracts. + +**Requirement:** FR-3 +**Primary architecture:** AD-15, AD-22, AD-23; AD-1/4/11/16/19/20 conventions +**Applicable NFR:** NFR-S1, NFR-S2, NFR-S4, NFR-S7, NFR-S8, NFR-O1, NFR-O4, NFR-O5, NFR-C1, NFR-C3, NFR-C4 +**Primary risk/evidence:** credential exfiltration, stale/revoked key acceptance, boundary confusion between MCP/approval/Admin credentials. + +## Scope + +In scope: + +- Auth Profile lifecycle for existing bearer/basic/api-key-header/api-key-query configs. +- Workspace Secrets lifecycle used by Auth Profiles: create, rotate, metadata read/list, delete restrictions, execution read/touch. +- MCP machine key lifecycle for Agent endpoints. +- Approval key lifecycle for approval endpoints. +- One-time raw key disclosure semantics and UI cleanup for machine keys. +- Raw secret/key/hash/prefix redaction in API responses, exports, logs, traces, metrics, diagnostics and UI error state. +- Immediate revocation semantics against PostgreSQL source of truth; any cache/projection must revalidate or fail closed. +- Rotation semantics: + - Auth Profile credential rotation is performed by creating a new Secret version and switching current version atomically. + - Machine/approval key rotation is create-new-key + explicit revoke-old-key policy, never recover old raw value. +- Bounded audit events for create/rotate/revoke/delete/read-denied outcomes with actor, credential type/ref, action, outcome, Request ID and Trace ID. +- RU/EN UI states for create, rotate, revoke, one-time reveal, stale response and destructive confirmation. +- Capability Inventory/baseline evidence for FR-3 after tests pass. + +Out of scope: + +- Master-key fingerprint/epoch registration, re-encryption and restore proof; owned by Story 1.11. +- Admin bootstrap/login/session/CSRF recovery; owned by Story 1.12. +- OpenAPI security scheme mapping beyond preserving current Auth Profile refs; detailed importer UX belongs Epic 2. +- Agent catalog lifecycle redesign; owned by Story 1.13. +- Approval side-effect workflow redesign; owned by Story 1.14. +- Full backup/restore qualification and recovery RPO/RTO; owned by Epic 7/8. +- New RBAC/teams/SSO/multi-workspace; Community remains one workspace/admin, but object-scope checks remain mandatory. + +## Acceptance Criteria + +1. **Auth Profile write boundary stores references only** + - Given a new Auth Profile + - When administrator provides credential material + - Then raw material is accepted only through a protected Secret write/rotate contract + - And Auth Profile stores only typed Secret refs and compatible auth config + - And Operations, YAML export, Admin API responses and UI state never contain raw credential material. + +2. **Secrets are encrypted before persistence and never read back** + - Given Secret create or rotate + - When the write succeeds + - Then plaintext is encrypted before persistence and only ciphertext/key-version metadata is stored + - And list/get/export/diagnostics return metadata only + - And privileged Admin API callers cannot retrieve plaintext after save. + +3. **MCP/approval key one-time disclosure** + - Given creation of MCP key or approval key + - When creation succeeds + - Then raw key is returned exactly once in the create response + - And persistence stores only safe hash, non-sensitive bounded prefix, scope, status and timestamps + - And no subsequent get/list/export/diagnostic path can reconstruct or return the raw key. + +4. **Machine key scope is exact and non-leaking** + - Given MCP key used against an Agent endpoint + - When workspace, Agent, key kind, status, expiry or scope does not match + - Then access is denied with safe unauthorized/forbidden outcome + - And response/log/trace/history does not reveal whether another workspace/Agent/key exists. + +5. **Approval key is accepted only at approval boundary** + - Given approval key + - When it is used for MCP initialize/list/call or Admin API + - Then it is rejected before execution + - And MCP/Admin credentials cannot be used to approve/deny pending approval requests + - And approval key allowed-origin policy is enforced where origin is available. + +6. **Revocation is immediate and fail-closed** + - Given active Auth Profile credential, MCP key or approval key + - When administrator revokes/deletes/disables it + - Then PostgreSQL transaction records the terminal state atomically + - And new MCP/approval/Auth Profile resolution observes revocation without service restart + - And any cache or Valkey projection is invalidated or treated as untrusted when status cannot be confirmed. + +7. **Rotation is explicit and atomic** + - Given Auth Profile credential rotation + - When a new Secret version is submitted + - Then the new version is encrypted and validated before becoming current + - And the previous version is no longer used for new execution after commit + - And Operation/Auth Profile refs do not need raw values or mass rewrite. + - Given machine/approval key rotation + - When administrator creates a replacement key + - Then new key is independently scoped and disclosed once + - And old key remains active or is revoked only according to explicit confirmed policy. + +8. **Audit evidence is bounded and non-secret** + - Given create, rotate, revoke, delete, denied access or failed credential operation + - When outcome is recorded + - Then audit/log event includes actor if available, credential type/ref, action, outcome, Request ID and Trace ID + - And raw secret, hash, full prefix, bearer token, ciphertext, request body and internal error text are absent. + +9. **One-time disclosure UI is safe** + - Given raw machine/approval key is shown after create + - When user copies it, closes modal, navigates, refreshes, goes back or switches workspace/Agent + - Then raw value is cleared from app state/DOM and cannot be restored + - And UI clearly warns in RU/EN that the value cannot be shown again. + +10. **Credential UI states and destructive confirmations** + - Given Secrets/Auth Profiles/API Keys UI + - When create, rotate, revoke, delete or load fails/succeeds + - Then loading, empty, error, success, confirmation and stale-response states are implemented in RU and EN + - And destructive revoke/delete requires explicit confirmation and disables duplicate submit. + +11. **Security/regression gates** + - Given Story 1.10 completion + - When targeted suites and final gates run + - Then Admin API, MCP, runtime, registry and UI tests prove no raw secrets leak, revoked credentials stop access, wrong-kind credentials fail closed, and `just verify` passes + - And Capability Inventory FR-3 evidence is updated only after successful verification. + +## Tasks / Subtasks + +- [x] Task 1 — Freeze RED credential lifecycle/security oracle (AC: 1–11) + - [x] Add registry/Admin/MCP tests proving raw Secret values and raw machine keys appear only on write/create response and never on list/get/export/error/log/debug paths. + - [x] Add negative tests for wrong workspace/Agent/key kind/scope/status/expiry and approval-vs-MCP boundary confusion. + - [x] Add revocation/rotation tests proving immediate no-restart effect on Admin Test, MCP `tools/list`, MCP `tools/call` and approval endpoints. + - [x] Add UI/Playwright tests for one-time disclosure cleanup, revoke confirmation, stale response and RU/EN states. + +- [x] Task 2 — Harden domain models and wire DTOs (AC: 1–5, 8) + - [x] Introduce/verify typed credential lifecycle actions and stable error/audit codes in `crank-core`; do not expose secret/hash/ciphertext fields via serializable public DTOs. + - [x] Split create response DTOs from read/list DTOs so `secret` raw field cannot accidentally appear in non-create responses. + - [x] Add bounded validation for key names, scopes, allowed origins, expiries, auth config fields and Secret payload shapes. + - [x] Ensure all boundary errors carry Request ID/Trace ID and localized safe messages without raw causes. + +- [x] Task 3 — Registry persistence and transactional lifecycle (AC: 2–8) + - [x] Store/rotate Secret versions transactionally with checked version increment, workspace predicate and active-status validation. + - [x] Revoke/delete machine keys through explicit terminal lifecycle; delete must not erase audit/provenance needed for historical evidence. + - [x] Add or update append-only migration only if required for audit/revoked/version fields; use Story 1.4 migration authority, never runtime/startup DDL. + - [x] Add PostgreSQL tests for concurrent create/rotate/revoke, duplicate names, stale revocation, wrong workspace, and no plaintext/hash exposure. + +- [x] Task 4 — Admin API service/route hardening (AC: 1–3, 6–8, 10) + - [x] Enforce owner/write authorization for Secret/Auth Profile/key mutations; read-only roles must fail safely if present in fixtures. + - [x] Validate Auth Profile secret refs in workspace at create and before Operation publish/test execution; missing/revoked refs return typed outcome. + - [x] Add rotate key operation or document/implement create-new + revoke-old as the only machine-key rotation contract. + - [x] Emit bounded audit/log events for create/rotate/revoke/delete success and failure with actor/request/trace IDs. + +- [x] Task 5 — MCP and approval boundary enforcement (AC: 4–6, 8) + - [x] Ensure MCP key lookup requires exact workspace slug, Agent slug, `mcp_client` kind, active status, expiry and required scope before execution/listing. + - [x] Ensure approval lookup requires `approval` kind, active status, expiry, approval scope and approval boundary only. + - [x] Map denied/unavailable outcomes through existing typed execution/boundary error paths without metadata leakage. + - [x] Prove revoked/wrong-kind/wrong-Agent/wrong-workspace keys stop access without restart and without relying on stale cache. + +- [x] Task 6 — Runtime/Auth Profile resolution hardening (AC: 1–2, 6–8) + - [x] Resolve Auth Profile and all referenced Secrets under workspace scope immediately before execution. + - [x] Reject missing/revoked/deleted Secret/Auth Profile as typed non-secret execution failures. + - [x] Touch last-used metadata with bounded best-effort semantics that does not change product result or leak DB errors. + - [x] Preserve Story 1.9 reserved-header provenance: Auth Profile credentials remain system-owned and cannot be overridden by mapping/static headers. + +- [x] Task 7 — UI one-time disclosure and credential lifecycle UX (AC: 9–10) + - [x] Update API Keys UI to keep raw key in modal-local state only, clear on close/navigation/workspace/Agent switch/refresh/back, and never place raw key into persistent state. + - [x] Add explicit rotate-as-create-new + optional revoke-old workflow or clear copy explaining the policy; destructive revoke/delete needs confirmation and duplicate-submit lock. + - [x] Update Secrets UI create/rotate/delete states with request generation guard, stale response discard, disabled submit, safe errors and RU/EN strings. + - [x] Ensure DOM/test snapshots/error telemetry cannot recover raw key/secret canaries. + +- [x] Task 8 — Documentation, inventory and evidence (AC: 8, 11) + - [x] Update `docs/admin-api.md`, `docs/mcp-interface.md`, `docs/data-model.md`, `docs/database-schema.md`, `docs/manual-regression-checklist.md` with actual credential lifecycle contracts. + - [x] Update `docs/capability-inventory.json` and baseline manifest/results only after tests pass; FR-3 implemented evidence must point to real commands. + - [x] Record deferred master-key/re-encryption work explicitly as Story 1.11 scope, not as completed in 1.10. + - [x] Run explicit Community scope scan over every new/updated Story 1.10 path. + +- [x] Task 9 — Final verification (AC: 11) + - [x] Run targeted Rust unit/integration suites for registry, Admin API, MCP, runtime and outbound/auth interactions. + - [x] Run UI build and relevant Playwright specs for Secrets/API Keys/approval flow. + - [x] Run `just migration-contract-check`, boundary checks, capability inventory check, `git diff --check`, and final `just verify`. + - [x] Update Story File List and Dev Agent Record with exact commands/results before moving to review. + +### Review Findings + +- [x] [Review][Patch] Platform key delete tombstones must not reserve names after delete — Fixed in Chunk 1: added v6 partial unique index excluding deleted rows and create-after-delete regression coverage. +- [x] [Review][Patch] Disabled/non-active Secrets can still be referenced, rotated, touched and used — Fixed in Chunk 1: active-status validation now applies to Auth Profile refs, rotation, current-version reads and execution resolution. +- [x] [Review][Patch] Secret rotation is not atomic and lacks active-status/CAS protection — Fixed in Chunk 1: rotation now locks the Secret row, validates active status and updates with checked current_version. +- [x] [Review][Patch] Failed credential operations are not audited — Fixed in Chunk 1: failed Secret/AuthProfile/platform-key create/rotate/revoke/delete paths emit bounded non-secret audit records. +- [x] [Review][Patch] Secret delete can race concurrent Auth Profile creation and leave a profile pointing at a deleted Secret — Fixed in Chunk 1: AuthProfile save and Secret delete now share transaction-scoped advisory locks and delete rechecks refs in-transaction. +- [x] [Review][Patch] Platform key terminal states are not guarded; deleted keys can become revoked again — Fixed in Chunk 1: revoke/delete now use state predicates and typed inactive-key conflicts. +- [x] [Review][Patch] Approval allowed-origin policy rejects missing Origin and does not fail-closed on duplicate Origin — Fixed in Chunk 2: missing Origin is allowed for non-browser/server-side clients, duplicate/malformed Origin fails closed, with unit and integration coverage. +- [x] [Review][Patch] Known approval-key denial by scope/origin is not written as bounded audit evidence — Fixed in Chunk 2: known approval-key scope/origin denial now emits bounded structured audit log evidence with credential ref, outcome, reason and request/trace correlation only. +- [x] [Review][Patch] Copying a one-time API key does not clear the raw key from DOM — Fixed in Chunk 3: copy now wipes the reveal value immediately and Playwright asserts the DOM is empty after copy. +- [x] [Review][Patch] Pending API-key create response can reveal a raw key after modal close or workspace/Agent/key-kind switch — Fixed in Chunk 3: create responses are guarded by modal/workspace/Agent/key-kind generation and stale responses are discarded without rendering the raw key. +- [x] [Review][Patch] API-key load/revoke/delete flows lack stale-response and duplicate-submit guards — Fixed in Chunk 3: API-key loading and mutations now carry context guards, and per-key mutation locks disable duplicate revoke/delete. +- [x] [Review][Patch] Browser navigation/BFCache can restore API-key reveal DOM without an explicit wipe hook — Fixed in Chunk 3: pagehide/pageshow cleanup wipes the reveal value, with Playwright navigation/back coverage. +- [x] [Review][Patch] Secret modal submit can be unlocked by close/reopen and stale completion can close a newer modal — Fixed in Chunk 3: Secret modal submissions now use generation tokens and preserve the pending lock until the owning request settles. +- [x] [Review][Patch] Playwright coverage does not prove the required credential cleanup/stale/duplicate-submit scenarios — Fixed in Chunk 3: API Keys and Secrets specs now cover copy cleanup, stale create discard, navigation/back cleanup and duplicate-submit request counting. +- [x] [Review][Patch] Auth Profile header injection does not remove all case-variant untrusted headers before REST dispatch — Fixed in Chunk 4: runtime Auth Profile injection removes every case-insensitive header variant before inserting the trusted system value, with Bearer and API-key regression tests. +- [x] [Review][Patch] Runtime Auth Profile resolution ignores mismatched `kind` versus `config` variant — Fixed in Chunk 4: `AuthConfig::kind()` is authoritative and runtime resolution fails closed on mismatched profile/config pairs before using secrets. +- [x] [Review][Patch] Operation publish validates Auth Profile existence but not active/current referenced Secrets — Fixed in Chunk 4: operation validation now resolves Auth Profile secret refs, requires active Secret plus current version, and credential lifecycle integration covers publish fail-closed after Secret disablement. +- [x] [Review][Patch] Auth Profile/Secret read-denied execution failures lack bounded credential audit/log evidence — Fixed in Chunk 4: Admin credential resolution denial paths emit bounded credential audit/log evidence with request/trace correlation and no secret material. +- [x] [Review][Patch] Authorization store failures normalize to `runtime_internal` instead of a typed credential/store outcome — Fixed in Chunk 4: authorization store failures now normalize to `safety_store_unavailable` with after-delay/certain semantics and targeted runtime test coverage. +- [x] [Review][Patch] Capability baseline provenance does not prove the reviewed FR-3 credential changes — Fixed in Chunk 4: baseline results now include an accepted `rust-admin-integration` credential lifecycle run linked to FR-3 credential/API flows and manifest checksum was updated. +- [x] [Review][Patch] MCP and approval bearer parsing accepts ambiguous duplicate Authorization headers — Fixed: bearer parsing now requires exactly one Authorization header; duplicate-header regression is covered in `crank-community-mcp access` tests. +- [x] [Review][Patch] Platform key touch can allow one post-revocation MCP/approval request — Fixed: `touch_platform_api_key` now revalidates active/non-expired state at touch time; MCP and approval paths map inactive touch to 401 instead of a post-revocation success. +- [x] [Review][Patch] MCP Auth Profile resolution does not enforce active Secret parity and treats best-effort Secret touch as fatal — Fixed: MCP Auth Profile resolution now requires active Secret records before decrypting and treats Secret last-used touch as bounded best-effort audit metadata. +- [x] [Review][Patch] Pending approval invocation history stores raw request payload and approval response preview — Fixed: pending-approval Invocation History now stores only approval metadata previews, not the raw request payload or full approval response; integration coverage asserts canary absence. +- [x] [Review][Patch] MCP machine-key denied access lacks bounded credential audit evidence — Fixed: missing/ambiguous, unknown/inactive and scope-denied MCP key paths now emit bounded credential audit evidence with credential type, outcome, reason and request/trace correlation only. +- [x] [Review][Patch] Approval key revocation lacks no-restart endpoint evidence for list/approve/deny — Fixed: approval integration now revokes an approval key against a live MCP server and proves list/approve/deny all return 401 without restart while the request remains pending. +- [x] [Review][Patch] MCP tool error remediation text is not localized for EN clients — Fixed: MCP confirmation messages and suggested actions are localized for RU/EN; unit coverage asserts EN retry and confirmation text. +- [x] [Review][Patch] Concurrent approval finish conflicts are reported as persistence unavailable — Fixed: `finish_approval_request` returning `None` now maps to stable 409 `approval_state_conflict`; storage failures remain 503 `persistence_unavailable`. +- [x] [Review][Defer] Auth Profiles have no lifecycle status for retired/disabled profiles [crates/crank-community-mcp/src/app.rs:1007] — deferred, pre-existing; current Story 1.10 can enforce Secret/credential terminal state, but adding AuthProfile status/tombstones is a broader domain/storage lifecycle extension. +- [x] [Review][Patch] Machine-key bearer secrets must use a full-entropy CSPRNG instead of UUIDv7 — Fixed: machine secrets now use 32 CSPRNG bytes encoded as base64url; key identifiers remain UUIDv7. +- [x] [Review][Patch] Platform-key writes need bounded name/scope validation, duplicate-scope rejection and future expiry enforcement — Fixed: create validates trimmed bounded names, scope count/uniqueness/kind compatibility and future expiry. +- [x] [Review][Patch] Secret create/rotate must validate bounded payload shape against `SecretKind` before encryption or current-version switch — Fixed: bounded JSON size and kind-specific payload shapes are enforced before encryption and persistence. +- [x] [Review][Patch] Auth Profile writes must bound names and validate HTTP header/query parameter names, not only the enum variant — Fixed: names and HTTP header/query identifiers now use bounded fail-closed validation. +- [x] [Review][Patch] Credential service spans must skip `audit_context` and `created_by` so actor email/session IDs are not captured by `#[instrument]` — Fixed: sensitive actor/audit inputs are explicitly skipped on credential service spans. +- [x] [Review][Patch] Early platform-key and Secret lookup/expiry failures must emit the same bounded failure audit evidence as later mutation failures — Fixed: early lookup, expiry and registry failures now emit the shared bounded audit contract. +- [x] [Review][Patch] Known MCP scope denial must retain the resolved bounded platform-key ID instead of auditing `credential_ref = unknown` — Fixed: known-key scope denials audit the resolved key ID; unknown credentials remain non-enumerating. +- [x] [Review][Patch] Credential mutation audit payloads need a stable bounded reason/error code so operational failures are distinguishable — Fixed: audit records include stable bounded `reason` codes sourced from typed API errors. +- [x] [Review][Patch] Platform-key and Secret touch queries must linearize status validation with the row update to close post-revocation execution races — Fixed: locked CTEs serialize lifecycle validation with touch; deterministic PostgreSQL race tests cover revoke/disable winners. +- [x] [Review][Patch] Secret rotation must not return an ambiguous error after a successful commit when the metadata read fails — Fixed: rotation returns committed version metadata directly from the transactional registry result. +- [x] [Review][Patch] Approval origins must be parsed and stored canonically with valid host/port and no userinfo/path/query/fragment — Fixed: URL parsing accepts only canonical HTTP(S) origins and rejects malformed or non-origin components and duplicates. +- [x] [Review][Patch] A stale successful key-create response must reconcile server metadata, warn about the lost one-time value and not let an older request unlock a newer modal — Fixed: stale success wipes raw data, reloads metadata, shows a lost-value warning and uses modal generations. +- [x] [Review][Patch] Playwright must prove successful/failed MCP config copy clears or preserves every raw-key DOM copy — Fixed: E2E covers successful cleanup and clipboard-failure preservation. +- [x] [Review][Patch] Playwright must prove duplicate revoke/delete actions emit only one destructive key request — Fixed: E2E double-action coverage asserts exactly one revoke/delete request. +- [x] [Review][Patch] Playwright must execute the Secret rotation stale-response guard, not only the create branch — Fixed: E2E executes stale rotate completion after close/reopen and verifies the newer modal remains authoritative. +- [x] [Review][Patch] MCP no-restart revocation evidence must cover initialize and tools/call in addition to tools/list — Fixed: live-server integration proves revoked keys fail initialize, tools/list and tools/call without restart or leakage. +- [x] [Review][Defer] Secret deletion hard-deletes encrypted versions and there is no explicit disable/tombstone API [crates/crank-registry/src/postgres/secret.rs:315] — deferred, pre-existing; durable Secret tombstones and disable/restore semantics require a broader schema and retention-policy change. +- [x] [Review][Defer] Credential audit recording remains best-effort after lifecycle transactions rather than using a durable transactional outbox [apps/admin-api/src/service.rs:317] — deferred, pre-existing; atomic mutation/audit delivery requires a cross-cutting persistence and delivery architecture change. + +## Dev Notes + +### Current brownfield state + +- `apps/admin-api/src/service/secrets.rs` already creates Secrets, encrypts payloads through `SecretCrypto`, stores ciphertext in `secret_versions`, rotates by inserting a new version and moving `secrets.current_version`, and blocks delete when an Auth Profile references the Secret. +- `apps/admin-api/src/service/secrets.rs` creates Auth Profiles as config objects referencing existing Secret IDs. It validates kind/config shape and current workspace Secret existence, but Auth Profile lifecycle is create/get/list only. +- `apps/admin-api/src/service/api_keys.rs` creates Agent-scoped platform keys, generates raw secret once, stores `hash_access_secret(secret)`, stores bounded prefix, scopes, kind, status and timestamps, and returns `{ api_key, secret }` on create. +- `crates/crank-registry/src/postgres/api_key.rs` filters active, non-expired, kind-specific keys for MCP/approval lookup and touches `last_used_at` with one-minute throttling. +- `crates/crank-community-mcp/src/access.rs` first verifies static Agent key for MCP, then falls back to `MachineCredentialVerifier`; approval access uses separate `get_approval_api_key_by_secret_for_agent_slug`. +- UI surfaces already exist: `apps/ui/js/api-keys.js`, `apps/ui/html/api-keys.html`, `apps/ui/js/secrets.js`, `apps/ui/html/secrets.html`, and Playwright specs `api-keys.spec.js`, `secrets.spec.js`. +- Current UI displays one-time key in `#reveal-key-value`, but story must prove it is cleared on close/navigation/workspace/Agent switch and not restored by back/refresh. + +### Current gaps and traps to avoid + +- Do not treat CRUD as lifecycle. Story requires terminal states, rotation policy, revocation evidence, one-time disclosure and audit. +- Do not expose raw key by reusing `CreatedPlatformApiKeyResponse` for list/get/export. Create response and read DTO must remain separate. +- Do not log or serialize `secret_hash`, ciphertext, raw token, full prefix, credential-bearing URL, or parser/internal error chain. +- Do not implement master-key identity/re-encryption here; only preserve `key_version` compatibility and document Story 1.11 dependency. +- Do not rely on Valkey/cache for credential truth. PostgreSQL is the mandatory source of truth. Cache failures on credential status must fail closed. +- Do not let approval keys authenticate MCP execution. Do not let MCP/Admin credentials approve/deny pending approval requests. +- Do not let operation/static/mapped headers override Auth Profile credential headers; preserve Story 1.9 trusted-header provenance. +- Do not hard-delete active/revoked keys if audit/provenance would be destroyed. If UI keeps delete for revoked keys, define whether delete is metadata tombstone, soft delete, or restricted cleanup. +- Do not add teams/RBAC/SSO. Community is one workspace/admin, but tests still need scoped object access and safe not-found/denied behavior. + +### Architecture compliance + +- Domain enums, DTO invariants and safe serialization belong in `crank-core`; SQLx belongs in `crank-registry`; Axum route mapping belongs in Admin/MCP composition roots. +- Durable schema changes, if any, must be append-only through migration authority. Do not edit frozen v1/v2/v3/v4/v5 sources/checksums except by adding a new migration descriptor. +- All newly user-visible strings must be RU and EN together. +- Metrics must use typed low-cardinality labels only. Request ID/Trace ID/key ID/secret ID/full prefix must not become ordinary metric labels. +- Audit/log events may include bounded credential refs and action/outcome, but not secret material, hash or ciphertext. +- Boundary errors must include safe Request ID/Trace ID from Story 1.5 and use typed errors from Story 1.8 where execution is involved. + +### File map + +Likely UPDATE: + +- `crates/crank-core/src/access.rs` +- `crates/crank-core/src/operation.rs` +- `crates/crank-runtime/src/auth.rs` +- `crates/crank-runtime/src/execution_failure.rs` +- `crates/crank-runtime/src/executor.rs` +- `apps/admin-api/src/dto.rs` +- `apps/admin-api/src/error.rs` +- `apps/admin-api/src/routes/agents.rs` +- `apps/admin-api/src/routes/auth_profiles.rs` +- `apps/admin-api/src/routes/secrets.rs` +- `apps/admin-api/src/service.rs` +- `apps/admin-api/src/service/api_keys.rs` +- `apps/admin-api/src/service/secrets.rs` +- `apps/admin-api/src/service/operations.rs` +- `crates/crank-community-mcp/src/access.rs` +- `crates/crank-community-mcp/src/app.rs` +- `crates/crank-community-mcp/src/app/stages.rs` +- `crates/crank-community-mcp/src/approval_execution.rs` +- `crates/crank-registry/src/error.rs` +- `crates/crank-registry/src/model.rs` +- `crates/crank-registry/src/postgres/api_key.rs` +- `crates/crank-registry/src/postgres/auth.rs` +- `crates/crank-registry/src/postgres/secret.rs` +- `crates/crank-registry/src/migrations/authority.rs` +- `crates/crank-registry/src/migrations/schema_guard.rs` +- `docs/schemas/migration-sequence.json` +- `apps/ui/js/api-keys.js` +- `apps/ui/html/api-keys.html` +- `apps/ui/js/secrets.js` +- `apps/ui/html/secrets.html` +- `apps/ui/js/i18n.js` +- `apps/ui/tests/e2e/api-keys.spec.js` +- `apps/ui/tests/e2e/secrets.spec.js` +- `apps/admin-api/tests/integration/community_access_usage.rs` +- `apps/admin-api/tests/integration/secrets_import_auth.rs` +- `crates/crank-registry/tests/integration/workspace_access.rs` +- `crates/crank-registry/tests/integration/operations_artifacts.rs` +- `crates/crank-community-mcp/tests/integration` or existing `mcp-server` integration tests that exercise access boundaries +- `docs/admin-api.md` +- `docs/mcp-interface.md` +- `docs/data-model.md` +- `docs/database-schema.md` +- `docs/manual-regression-checklist.md` +- `docs/capability-inventory.json` +- `docs/capability-baseline/manifest.json` +- `docs/capability-baseline/results.json` + +Likely NEW if schema/audit gaps require it: + +- `crates/crank-registry/src/migrations/credential_lifecycle_v6.sql` +- `crates/crank-registry/src/migrations/credential_lifecycle_v6.rs` +- `apps/admin-api/tests/integration/credential_lifecycle.rs` +- `crates/crank-community-mcp/tests/integration/credential_lifecycle.rs` or equivalent under current test layout + +Do not modify: + +- Frozen migration source bytes for v1–v5 except expected sequence metadata when adding v6. +- Cargo/npm/toolchain versions unless an explicit Story task proves a required dependency and user approves it. +- Operation lifecycle semantics from 1.7, execution taxonomy from 1.8, outbound policy from 1.9 except preserving Auth Profile provenance. + +### Testing requirements + +Required RED/P0 tests before implementation: + +- Create Secret with canary value → list/get/export/error/log/debug do not contain canary; current Secret metadata has no plaintext. +- Rotate Secret referenced by Auth Profile → next Admin Test/MCP execution uses new version; old value no longer appears; refs unchanged. +- Missing/revoked/deleted Secret/Auth Profile → execution fails with typed non-secret error and persists safe history. +- Create MCP key → create response contains raw exactly once; list/get/export never contain raw; hash is never serialized. +- Revoke MCP key → subsequent `initialize`, `tools/list`, `tools/call` fail without restart. +- Wrong Agent/workspace MCP key → safe denied/not-found, no metadata leakage. +- Approval key → approval endpoints accepted only with approval scopes; MCP execution/Admin API reject it. +- MCP key/Admin credential → approval endpoint rejects before decision mutation. +- Duplicate/concurrent key create/revoke/rotate → deterministic typed result; no 500/raw storage error. +- UI key create modal → raw key is visible only in reveal step, copy works, close/navigation/workspace/Agent switch clears it. +- UI revoke/delete/rotate → confirmation, loading, duplicate-submit lock, error recovery, RU/EN strings. + +Suggested targeted commands: + +```bash +cargo test -p crank-core access operation -- --test-threads=1 +cargo test -p crank-runtime auth -- --test-threads=1 +cargo test -p crank-registry --test integration workspace_access operations_artifacts -- --test-threads=1 +cargo test -p admin-api --test integration credential_lifecycle -- --test-threads=1 +cargo test -p admin-api --test integration community_access_usage secrets_import_auth -- --test-threads=1 +cargo test -p mcp-server --test integration catalog_access -- --test-threads=1 +cd apps/ui && npx playwright test tests/e2e/api-keys.spec.js tests/e2e/secrets.spec.js --project=chromium +just migration-contract-check +just rust-boundaries +just capability-inventory-check +python3 scripts/check-community-scope.py --root . --files +git diff --check +just verify +``` + +### Previous story intelligence + +- Story 1.7 showed that “implemented UI/API flow” is insufficient when the durable state model is mutable. For 1.10, lifecycle invariants must be enforced in domain + PostgreSQL transaction, not only in UI buttons. +- Story 1.8 established typed execution errors and parity. Credential resolution failures in execution paths must use that taxonomy rather than raw `500`/ad-hoc status. +- Story 1.9 established trusted header provenance and adapter-owned dispatch evidence. Auth Profile credentials are system-owned headers/query params and must preserve that invariant. +- Review loops repeatedly found overstated evidence. Do not mark FR-3 implemented until tests prove raw disclosure, revocation, boundary separation and UI cleanup. + +### References + +- `_bmad-output/planning-artifacts/epics.md` — FR-3 and Story 1.10 AC. +- `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` — FR-3 consequences and FR-43 recovery relation. +- `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md` — backup/restore evidence contract involving encrypted Auth Profile. +- `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` — AD-15, AD-16, AD-22, AD-23. +- `_bmad-output/implementation-artifacts/1-9-outbound-rest.md` — previous story handoff and Auth Profile reserved-header boundary. +- `apps/admin-api/src/service/secrets.rs` — current Secrets/Auth Profile service behavior. +- `apps/admin-api/src/service/api_keys.rs` — current machine key create/revoke/delete behavior. +- `crates/crank-registry/src/postgres/api_key.rs` — current key persistence and lookup. +- `crates/crank-community-mcp/src/access.rs` — current MCP/approval credential boundary. +- `apps/ui/js/api-keys.js`, `apps/ui/js/secrets.js` — current credential UI. + +## Dev Agent Record + +### Agent Model Used + +GPT-5 Codex + +### Debug Log References + +- 2026-08-15: Story context created by `bmad-create-story`. +- 2026-08-15: Story moved to in-progress; baseline commit `767428436d3a54e60809a727044dfcec48e1f1dd` plus uncommitted Story 1.7/1.8/1.9 worktree. +- 2026-08-15: Added RED/GREEN Admin credential lifecycle tests for one-time machine key disclosure, duplicate key typed conflict, Secret plaintext canary redaction and approval allowed-origin validation. +- 2026-08-15: Added RED/GREEN MCP integration coverage for approval `allowed_origins` enforcement and no-restart revoked MCP key rejection on an existing session. +- 2026-08-15: Hardened duplicate platform-key constraint mapping to typed 409 `platform_api_key_name_conflict`; added approval origin validation and MCP approval-origin boundary check. +- 2026-08-15: Hardened API Keys UI one-time reveal cleanup; raw key DOM value is wiped on modal close, modal open, Agent/key-kind switch and workspace change. +- 2026-08-15: Added typed secret-reference conflict code `secret_referenced_by_auth_profile`; delete-denied path remains 409 but no longer emits generic `conflict`. +- 2026-08-15: Added Admin Test rotation proof: Auth Profile Secret rotation changes the next execution credential without rewriting the Operation/Auth Profile refs and without exposing old/new raw values in Auth Profile responses. +- 2026-08-15: Added Admin credential audit events for Secret create/rotate/delete/delete-denied, Auth Profile create, platform key create/revoke/delete. Events carry actor/session, bounded credential ref/type/action/outcome and request_id/trace_id; raw secret/key/hash/ciphertext are excluded. Audit sink failure is best-effort safe log to avoid losing one-time raw key after DB commit. +- 2026-08-15: Hardened terminal delete semantics for platform keys: delete now preserves metadata/provenance as `deleted`, while revoked/deleted keys remain unusable for MCP/approval access. +- 2026-08-15: Hardened Secrets UI stale/duplicate-submit behavior: modal fields clear on close/workspace switch, create/rotate submit is locked while in flight, and stale workspace responses are discarded. +- 2026-08-15: Updated credential lifecycle docs and Capability Inventory evidence; baseline manifest checksum was refreshed after the inventory change. +- 2026-08-15: Verification passed: `cargo fmt --all --check`; `cargo test -p admin-api --test integration integration::credential_lifecycle -- --test-threads=1` (5 passed); `cargo test -p admin-api --test integration integration::secrets_import_auth -- --test-threads=1` (6 passed); `cargo test -p admin-api --test integration integration::community_access_usage::manages_agent_platform_api_keys -- --exact --test-threads=1`; `cargo test -p mcp-server --test integration integration::catalog_access -- --test-threads=1` (19 passed); `cd apps/ui && npx playwright test tests/e2e/api-keys.spec.js --project=chromium`; `cd apps/ui && npx playwright test tests/e2e/secrets.spec.js --project=chromium` (4 passed); `just ui-build`; `just migration-contract-check`; `just rust-boundaries`; `just capability-inventory-check`; scoped `git diff --check`; explicit Community scope scan over 30 Story 1.10 paths. +- 2026-08-15: Final verification passed: `just verify` completed successfully after the clippy argument-count refactor. +- 2026-08-15: Explicit Community scope scan including the ignored BMad story artifact failed on story boundary terminology (`one-time`, `SSO`, `multi-workspace`); production/test/UI path scan passed. The story artifact remains ignored/local evidence, not shipped Community surface. +- 2026-08-21: Review patch pass closed MCP/approval findings: duplicate Authorization now fails closed; platform-key touch revalidates active/non-expired state; MCP Auth Profile resolution requires active Secrets and treats Secret touch as best-effort metadata; pending approval Invocation History stores only approval metadata previews; MCP/approval denied credential paths emit bounded audit evidence; approval-key revocation is proven against list/approve/deny without restarting the MCP server; MCP tool-error remediation is RU/EN localized; concurrent approval finish conflicts now return stable 409. +- 2026-08-21: Verification passed: `cargo test -p crank-community-mcp access --lib -- --test-threads=1` (4 passed); `cargo test -p crank-community-mcp tool_error --test unit -- --test-threads=1` (6 passed); `cargo test -p mcp-server --test integration integration::catalog_access::approval_access -- --test-threads=1` (11 passed); `cargo check -p admin-api -p mcp-server`; `cargo test -p crank-registry --test integration workspace_access -- --test-threads=1` (8 passed); `cargo fmt --all --check`; `git diff --check`; explicit Community scope scan over 8 production/test patch files passed. Explicit scan including this ignored BMad artifact still flags pre-existing story terminology and is not treated as shipped Community surface evidence. +- 2026-08-21: Final closure checks completed after full-gate drift fixes: `just verify` passed; `just verify-ui` passed via UI Docker build; explicit Community scope scan over 15 changed/new production/test paths passed; `git diff --check` passed. +- 2026-08-21: Full-gate drift corrections made during closure: `Cargo.lock` updated `h2` from 0.4.15 to 0.4.16 to satisfy `RUSTSEC-2026-0258`; migration command and migration-authority tests now expect canonical v6 sequence; registry Auth Profile fixture tests now create active Secret records before saving Secret-backed Auth Profiles. +- 2026-08-25: Final adversarial review remediation closed all 16 remaining PATCH findings: CSPRNG key material, bounded credential validation, safe spans/audit reasons, linearized credential touches, unambiguous Secret rotation results, canonical approval origins, stale/duplicate UI guards and complete no-restart MCP revocation evidence. +- 2026-08-25: Final verification passed: targeted Admin credential lifecycle (7), registry credential race (2), MCP access unit (5), MCP revoked-key integration (1), API Keys/Secrets Playwright (10), explicit Community scope scan (15 files), `git diff --check`, full `just verify` and Docker-backed `just verify-ui`. + +### Completion Notes List + +- Ultimate context engine analysis completed — comprehensive developer guide created. +- Implementation completed for 1.10 credential boundaries: raw key one-time list redaction, duplicate key typed conflict, Secret plaintext canary redaction, approval origin validation/enforcement, immediate revoked MCP key denial without restart and UI raw-key cleanup. +- Secret deletion blocked by Auth Profile now has a stable safe error code and recovery hint for UI/operator handling. +- Auth Profile Secret rotation is verified against real Admin Test execution: old credential used before rotation, new credential used after rotation, refs unchanged, no plaintext in Auth Profile readback. +- Credential mutation audit is now implemented through the existing `AuditSink` seam and covered by a canary integration test proving request/trace IDs are present and secret material is absent. +- Platform key delete is now terminal soft-delete: metadata remains visible as `deleted`, provenance is preserved, and raw/hash material is not exposed. +- Secrets UI now clears sensitive modal inputs, rejects duplicate submit while saving, discards stale workspace responses and keeps safe localized create/rotate/delete states. +- Documentation, Capability Inventory and baseline manifest now describe the actual FR-3 credential lifecycle contract. Master-key identity/re-encryption remains explicitly deferred to Story 1.11. +- Review patch pass completed for MCP/approval credential boundaries: revoked keys stop immediately on touch, ambiguous bearer headers fail closed, denied access is audited, pending approval history no longer stores raw payload previews, and approval completion conflicts are classified as conflict rather than storage outage. +- Full closure gate is green: targeted Rust/API/MCP/UI checks, `just verify`, `just verify-ui`, explicit Community scope scan and `git diff --check` passed on 2026-08-21. +- Dependency security gate is green after `h2` 0.4.16 lockfile remediation for `RUSTSEC-2026-0258`; no product dependency or API behavior was changed for Story 1.10 beyond this security-gate lockfile update. +- Final review is closed: all 16 latest PATCH findings are implemented and independently verified. Remaining Auth Profile lifecycle status, Secret tombstone/disable semantics and transactional audit outbox are explicit cross-cutting deferred work, not hidden blockers for the accepted Story 1.10 contract. + +### File List + +- `_bmad-output/implementation-artifacts/1-10-lifecycle-auth-profiles-machine-keys.md` +- `apps/admin-api/src/error.rs` +- `apps/admin-api/src/routes/agents.rs` +- `apps/admin-api/src/routes/auth_profiles.rs` +- `apps/admin-api/src/routes/secrets.rs` +- `apps/admin-api/src/service.rs` +- `apps/admin-api/src/service/api_keys.rs` +- `apps/admin-api/src/service/demo.rs` +- `apps/admin-api/src/service/secrets.rs` +- `apps/admin-api/tests/integration.rs` +- `apps/admin-api/tests/integration/common.rs` +- `apps/admin-api/tests/integration/credential_lifecycle.rs` +- `apps/admin-api/tests/integration/secrets_import_auth.rs` +- `apps/admin-api/tests/migration_command.rs` +- `apps/mcp-server/tests/integration/catalog_access.rs` +- `apps/mcp-server/tests/integration/catalog_access/approval_access.rs` +- `apps/mcp-server/tests/integration/catalog_access/approval_access/pending.rs` +- `apps/mcp-server/tests/integration/catalog_access/approval_access/revocation.rs` +- `apps/ui/js/api-keys.js` +- `apps/ui/js/i18n.js` +- `apps/ui/js/secrets.js` +- `apps/ui/tests/e2e/api-keys.spec.js` +- `apps/ui/tests/e2e/secrets.spec.js` +- `crates/crank-core/src/access.rs` +- `crates/crank-community-mcp/src/access.rs` +- `crates/crank-community-mcp/src/app.rs` +- `crates/crank-community-mcp/src/approval_execution.rs` +- `crates/crank-community-mcp/src/approval_response.rs` +- `crates/crank-community-mcp/src/tool_error.rs` +- `crates/crank-community-mcp/tests/unit/tool_error.rs` +- `crates/crank-registry/src/migrations/authority_tests.rs` +- `crates/crank-registry/src/error.rs` +- `crates/crank-registry/src/migrations.rs` +- `crates/crank-registry/src/migrations/authority.rs` +- `crates/crank-registry/src/migrations/platform_key_name_reuse_v6.rs` +- `crates/crank-registry/src/migrations/platform_key_name_reuse_v6.sql` +- `crates/crank-registry/src/migrations/schema_guard.rs` +- `crates/crank-registry/src/postgres/auth.rs` +- `crates/crank-registry/src/postgres/api_key.rs` +- `crates/crank-registry/src/postgres/secret.rs` +- `crates/crank-registry/tests/integration/migrations.rs` +- `crates/crank-registry/tests/integration/operations_artifacts.rs` +- `crates/crank-registry/tests/integration.rs` +- `crates/crank-registry/tests/integration/credential_touch.rs` +- `_bmad-output/implementation-artifacts/deferred-work.md` +- `Cargo.lock` +- `docs/admin-api.md` +- `docs/mcp-interface.md` +- `docs/data-model.md` +- `docs/database-schema.md` +- `docs/manual-regression-checklist.md` +- `docs/capability-inventory.json` +- `docs/capability-baseline/manifest.json` +- `docs/schemas/migration-sequence.json` + +## Change Log + +- 2026-08-15: Created Story 1.10 from Epic 1 FR-3 with brownfield Auth Profile, Secret, machine key and approval-key implementation context. +- 2026-08-15: Implemented first Story 1.10 credential boundary hardening pass and recorded targeted verification evidence; story remains in-progress for remaining lifecycle/audit/docs gates. +- 2026-08-15: Completed Story 1.10 credential lifecycle hardening, documentation, inventory evidence and final verification; moved story to review. +- 2026-08-21: Closed MCP/approval review patch findings and refreshed targeted verification evidence. +- 2026-08-21: Closed final verification loop: full `just verify`, `just verify-ui`, explicit Community scope scan and diff checks passed after fixing v6 migration-test drift, registry Secret-backed Auth Profile fixtures and `h2` security advisory lockfile drift. +- 2026-08-25: Closed all remaining adversarial review findings, reran targeted and full repository/UI gates, recorded broader lifecycle/outbox items in the deferred-work ledger and moved Story 1.10 to done. diff --git a/_bmad-output/implementation-artifacts/1-11-master-key-identity-rotation.md b/_bmad-output/implementation-artifacts/1-11-master-key-identity-rotation.md new file mode 100644 index 0000000..0ddb8a6 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-11-master-key-identity-rotation.md @@ -0,0 +1,467 @@ +--- +story_id: "1.11" +story_key: "1-11-master-key-identity-rotation" +requirement: "FR-3" +status: "done" +baseline_commit: "767428436d3a54e60809a727044dfcec48e1f1dd + uncommitted Story 1.10 closure worktree" +created: "2026-08-21T00:00:00+03:00" +--- + +# Story 1.11: Согласовать master-key identity и безопасную rotation + +Status: done + +## Story + +As an оператор Crank, +I want все secret-using процессы использовать одну проверяемую master-key identity и безопасно менять ключ, +so that сохранённые Secrets остаются доступными после restart, rotation и восстановления, а неправильный key не приводит к тихой порче или недоступности данных. + +## Operational Brief + +Story 1.10 закрыла lifecycle Secrets/Auth Profiles/MCP keys/approval keys: raw values не читаются обратно, Secret versions шифруются, revoked credentials fail-closed. Но текущий `CRANK_MASTER_KEY` всё ещё является локальным значением процесса: Admin API и MCP отдельно создают `SecretCrypto::new(...)`, PostgreSQL не знает fingerprint/epoch, readiness не доказывает общий ключ, а смена key material без re-encryption ломает сохранённые Secrets. + +Story 1.11 делает master key явным durable security contract: + +- PostgreSQL хранит только non-secret fingerprint/epoch/cipher contract. +- Каждый secret-using process до readiness сверяет свой `CRANK_MASTER_KEY` с active identity. +- Ciphertext получает epoch-aware envelope/metadata. +- Rotation выполняется operator-controlled, durable, resumable и не удаляет текущий ciphertext до verification/promotion. +- Failure output, logs, traces, manifests и audit не содержат raw key material, plaintext Secret или decrypt error details. + +Это продолжение FR-3 и архитектурного AD-15. Backup/restore RPO/RTO и protected external key backup reference полностью квалифицируются позже в Epic 7, но 1.11 должна оставить совместимый key identity/rotation foundation. + +## Requirement / Architecture Trace + +- **Direct requirement:** FR-3. +- **Primary architecture:** AD-15 Shared master-key identity. +- **Supporting architecture:** AD-16 migration authority, AD-17 typed config, AD-19 boundary errors, AD-22 admin identity/offline recovery guardrail, AD-24 backup/restore compatibility. +- **Applicable NFR:** NFR-S2, NFR-S4, NFR-S7, NFR-S8, NFR-O1, NFR-O4, NFR-O5, NFR-C1, NFR-C3. + +## Scope + +In scope: + +- Master-key identity registry in PostgreSQL: fingerprint, epoch, cipher contract, state, timestamps and safe operator metadata. +- Startup/readiness preflight for Admin API and MCP Server before secret use and before serving product readiness. +- Epoch-aware `SecretCrypto` envelope and decrypt path preserving support for existing `v1` legacy and current `v2` ciphertext. +- Controlled operator rotation command/API surface sufficient for preflight, start/resume re-encryption, verify, promote and abort. +- Durable rotation state/checkpoints and idempotent batch processing over existing `secret_versions`. +- PostgreSQL migration through canonical migration authority only; expected next version is v7 after current v6. +- Tests proving same-key, mismatch-key, corrupt ciphertext, interrupted rotation, resume, verify, promotion and old-key rejection semantics. +- Safe diagnostics/audit/logging with request/trace IDs where boundary-originated; no key/plaintext/ciphertext leakage. + +Out of scope: + +- Full production backup manifest, WAL/PITR, RPO/RTO measurement and three restore runs — Epic 7. +- Offline recovery UX and local operator bootstrap — Story 1.12/Epic 7. +- Multi-instance rolling key reload — Community target remains single-instance restart/reload boundary. +- Admin UI for master-key rotation unless a minimal status/readiness display is needed; CLI/operator command is sufficient. +- Re-encryption of non-Secret future credential stores not yet implemented. +- Changing credential lifecycle behavior from 1.10 except integrating master-key epoch metadata. + +## Acceptance Criteria + +1. **First identity registration is non-secret** + - Given a fresh migrated database with no master-key identity + - When controlled startup/preflight runs with valid `CRANK_MASTER_KEY` + - Then PostgreSQL stores only non-secret fingerprint, active epoch and cipher-contract metadata + - And raw master key bytes never enter PostgreSQL, logs, traces, diagnostics, manifests or test failure output. + +2. **Secret-using processes verify identity before readiness** + - Given Admin API, MCP Server or any process that can encrypt/decrypt Secrets + - When startup/readiness executes + - Then it computes the local non-secret fingerprint and compares it with PostgreSQL active identity + - And mismatch, unknown epoch, missing identity after registration, unsupported cipher contract or storage error blocks safe readiness/startup with bounded typed diagnostics. + +3. **Ciphertext is epoch-aware and backward compatible** + - Given a newly written Secret version + - When it is encrypted + - Then its durable metadata identifies cipher version and master-key epoch without exposing key material + - And existing legacy/current ciphertext remains readable under the registered compatible epoch + - And corrupt/truncated/unknown-version ciphertext returns typed security error without plaintext or raw parser details. + +4. **Rotation preflight is read-only** + - Given current and target key material supplied by the operator + - When preflight runs + - Then it validates both keys, decryptability of all affected active Secret versions, target fingerprint uniqueness and absence of incompatible active rotation + - And it does not change active epoch, Secret rows, ciphertext or readiness state. + +5. **Rotation creates durable state and target ciphertext without deleting current ciphertext** + - Given successful preflight + - When rotation starts or resumes + - Then a durable rotation record tracks ID, source epoch, target epoch, state, counts, checkpoint and safe metadata + - And each processed Secret version gets verified target-epoch ciphertext while current ciphertext remains available until promotion. + +6. **Crash/restart resume is idempotent** + - Given a crash/interruption before all batches finish + - When the operator reruns rotation + - Then processing resumes from durable checkpoint without double-counting, skipping records incorrectly or losing Secrets + - And current active epoch remains usable for reads until promotion. + +7. **Concurrent Secret writes have a defined epoch contract** + - Given rotation is in progress + - When an Admin creates or rotates a Secret + - Then the write is either rejected with a typed retryable rotation-in-progress error or written with a defined current/target handling that keeps it readable by all ready processes + - And no write creates a Secret version inaccessible to the active deployment. + +8. **Verification gates promotion** + - Given all target ciphertext has been produced + - When verification runs + - Then every affected Secret version decrypts under the target key, counts match the source set and integrity failures block promotion + - And evidence contains only IDs/counts/digests/safe error codes. + +9. **Promotion is atomic and old key is no longer accepted after restart boundary** + - Given verification succeeded + - When target epoch is promoted + - Then active epoch/fingerprint changes atomically + - And Admin/MCP readiness with old key fails after the agreed restart/reload boundary + - And readiness with target key succeeds and existing Auth Profile execution works. + +10. **Abort/recovery preserves current epoch before promotion** + - Given rotation fails or is aborted before promotion + - When operator runs abort/recovery + - Then current epoch remains active, target epoch is not used for new writes, partial target ciphertext is ignored or safely marked + - And preflight can be rerun without disclosing stored Secrets. + +11. **Backup key reference is opaque** + - Given an operator records an external protected key-backup reference + - When it is stored or shown + - Then Crank stores only opaque reference plus fingerprint/epoch metadata + - And key bytes are absent from product backup set, Evidence Manifest, logs and diagnostics. + +12. **Final safety matrix** + - Given Story 1.11 completion + - When tests run + - Then coverage includes matching/mismatching Admin+MCP processes, fresh identity registration, corrupt ciphertext, crash before/after checkpoint, resume, abort, successful rotation, promotion and old-key rejection + - And `just verify`, relevant migration/config/boundary checks and explicit Community scope scan pass. + +## Tasks / Subtasks + +- [x] Task 1 — Freeze master-key contract and RED tests (AC: 1–12) + - [x] Add tests for non-secret fingerprint stability, raw-key redaction, unsupported/corrupt ciphertext and legacy ciphertext compatibility. + - [x] Add Admin/MCP startup/readiness tests for same-key, mismatch-key, missing identity, storage failure and unsupported cipher contract. + - [x] Add registry migration tests for fresh/current/corrupt v7 schema and append-only sequence. + - [x] Add rotation state tests for preflight read-only, resume, verify, promote and abort. + +- [x] Task 2 — Domain and crypto model (AC: 1–3, 7–11) + - [x] Extend `crank-runtime::SecretCrypto` with typed `MasterKeyIdentity`, fingerprint, epoch and cipher-contract metadata. + - [x] Preserve decrypt compatibility for existing `v1` legacy and `v2` ciphertext; new writes must use epoch-aware metadata without changing raw Secret DTOs. + - [x] Replace raw `RuntimeError::SecretCrypto` detail leakage with stable bounded safe diagnostics at product boundaries. + - [x] Ensure Debug/Display/Serialize paths never expose raw key, derived key bytes, plaintext, ciphertext or parser internals. + +- [x] Task 3 — PostgreSQL schema and migration authority (AC: 1, 3–10) + - [x] Add append-only v7 migration for master-key identity, rotation state/checkpoints and any target-ciphertext metadata required for re-encryption. + - [x] Update migration descriptors, exact checksums, schema guard/fingerprint and `docs/schemas/migration-sequence.json`. + - [x] Preserve v1–v6 immutable migration bytes and compatibility behavior. + - [x] Add integration tests for fresh v7, v6→v7 upgrade, current v7, partial v7 rollback and corrupt ledger/constraint definitions. + +- [x] Task 4 — Registry key-authority API (AC: 1, 4–10) + - [x] Add registry methods for identity registration/check, rotation creation, batch checkpointing, verification evidence, promotion and abort. + - [x] Enforce single active rotation and transactional state transitions with row locks/CAS. + - [x] Make preflight read-only and prove it does not mutate ciphertext/active epoch. + - [x] Add bounded typed errors for mismatch, unknown epoch, rotation conflict, verification failure and storage unavailable. + +- [x] Task 5 — Process startup/readiness integration (AC: 1–2, 9) + - [x] Wire Admin API and MCP Server to validate master-key identity after DB/migration compatibility and before SecretCrypto-dependent product readiness. + - [x] Ensure mismatch blocks startup/readiness before serving Admin/MCP product routes and without raw driver/key output. + - [x] Preserve config boundary: `CRANK_MASTER_KEY` remains parsed only by `crank-config`; reusable crates receive typed values. + - [x] Add subprocess tests for safe diagnostics and no listener/product readiness on mismatch. + +- [x] Task 6 — Rotation operator command/surface (AC: 4–11) + - [x] Implement minimal controlled operator path, preferably `crank-migrate` subcommand family or another explicit local operator command, not product runtime DDL. + - [x] Support preflight, start/resume, verify, promote, abort and status with bounded JSON output. + - [x] Accept target/current key material only via safe local operator input/env contract; never echo values. + - [x] Record opaque external key-backup reference metadata without storing key bytes. + +- [x] Task 7 — Secret write/read integration during rotation (AC: 3, 5, 7–10) + - [x] Update Admin Secret create/rotate and MCP/Admin Secret resolution to use epoch-aware crypto metadata. + - [x] Define and implement concurrent write policy during rotation: fail-closed retryable rejection unless a fully verified dual-write path is implemented and tested. + - [x] Ensure Auth Profile execution remains functional before promotion, after promotion with new key, and fails safely with old key. + - [x] Keep Story 1.10 raw-secret/readback/redaction invariants unchanged. + +- [x] Task 8 — Documentation, inventory and evidence (AC: 1–12) + - [x] Update docs for master-key identity, startup/readiness failure, rotation procedure, abort/recovery and opaque backup reference. + - [x] Update Capability Inventory/baseline evidence for the FR-3 master-key slice only after checks pass. + - [x] Record deferred Epic 7 backup/restore/RPO/RTO scope explicitly. + - [x] Run explicit Community scope scan over every new/updated Story 1.11 path. + +- [x] Task 9 — Final verification (AC: 12) + - [x] Run targeted crypto/registry/Admin/MCP/rotation tests. + - [x] Run migration/config/boundary checks and SQLx checks if metadata changed. + - [x] Run `cargo fmt --all --check`, `git diff --check`, `just verify`; run UI checks only if UI files change. + - [x] Update Story File List, Dev Agent Record and Change Log with exact command results; set status to `review`. + +### Review Findings + +- [x] [Review][Patch] Enforce strong master-key entropy before storing deterministic fingerprint — `SecretCrypto` accepts any non-empty key and stores a deterministic SHA-256 domain-separated fingerprint; weak `CRANK_MASTER_KEY` values would make the DB fingerprint an offline guessing oracle. Enforce a high-entropy/generated-key contract in config/crypto and operator key-file validation now. [crates/crank-runtime/src/secret_crypto.rs:43] +- [x] [Review][Patch] Promoted target key cannot start Admin/MCP because startup always claims epoch 1 [apps/admin-api/src/main.rs:198] +- [x] [Review][Patch] Stale old-key process can write inaccessible epoch-1 Secrets after promotion because Secret writes do not verify active master-key identity [crates/crank-registry/src/postgres/secret.rs:139] +- [x] [Review][Patch] First identity registration on an upgraded populated DB can bless the wrong key without proving decryptability of existing Secret versions [crates/crank-registry/src/postgres/master_key.rs:31] +- [x] [Review][Patch] Fresh DB first identity registration is racy: Admin and MCP with the same key can both observe no active row, then one fails on the unique active index instead of verifying the winner [crates/crank-registry/src/postgres/master_key.rs:9] +- [x] [Review][Patch] Rotation begin and concurrent Secret writes are not serialized by a shared lock, so writes can commit outside the fixed rotation source count [crates/crank-registry/src/postgres/master_key.rs:273] +- [x] [Review][Patch] `delete_secret` is allowed during active rotation and can cascade-delete source/target versions, making verification or promotion inconsistent [crates/crank-registry/src/postgres/secret.rs:313] +- [x] [Review][Patch] Aborted rotation cannot be cleanly rerun for the same source epoch because rotation IDs are deterministic primary keys [crates/crank-registry/src/postgres/master_key.rs:279] +- [x] [Review][Patch] v7 schema guard accepts same-named weakened constraints because it checks only constraint existence, not exact definitions [crates/crank-registry/src/migrations/schema_guard.rs:620] +- [x] [Review][Patch] Preflight/rotation batch processing loads all Secret versions into memory before applying `--max-versions`, so large datasets are not bounded [apps/admin-api/src/bin/crank-migrate.rs:613] + +## Dev Notes + +### Current brownfield state + +- `crates/crank-runtime/src/secret_crypto.rs` owns `SecretCrypto`. It derives two AES-GCM ciphers from a raw master key: legacy SHA-256 `v1` and current HKDF `v2`. It exposes `key_version()` as `"v2"`, encrypts to a JSON envelope `{nonce_b64,ciphertext_b64}`, and decrypts by external `key_version`. +- `SecretCrypto::new` is called separately in `apps/admin-api/src/main.rs` and `apps/mcp-server/src/main.rs` from `config.runtime.master_key.expose_secret()`. There is no PostgreSQL identity check before readiness. +- `crates/crank-registry/src/postgres/secret.rs` persists `secret_versions(secret_id, version, ciphertext, key_version, created_at, created_by)`. There is no master-key epoch/fingerprint table or rotation state. +- Admin Secret create/rotate encrypts payloads in `apps/admin-api/src/service/secrets.rs` and stores `self.secret_crypto.key_version()`. Admin/MCP execution decrypts current Secret versions before resolving Auth Profiles. +- `crank-config` already treats `CRANK_MASTER_KEY` as required sensitive Shared runtime config and excludes raw value from debug/fingerprint. Do not introduce new direct env reads. +- Current migration authority version is v6. Story 1.11 schema work must be v7 and must not edit immutable v1–v6 source bytes. + +### Hard design decisions for implementation + +- Fingerprint must be deterministic and non-secret. It must not be raw key, derived encryption key, per-secret hash, or any value usable as an offline oracle beyond equality of configured deployment key. Use a domain-separated KDF/HMAC/fingerprint design and document why it is safe. +- Epoch is deployment master-key epoch, not Secret version. Do not conflate `secret_versions.version`, `secret_versions.key_version` and master-key epoch. +- New writes during rotation should default to fail-closed retryable rejection unless the story explicitly implements and proves dual-write/current+target handling. Simpler safe policy is acceptable and preferred for Community. +- Promotion requires restart/reload boundary. Do not claim hot multi-process reload unless implemented and tested. +- Preflight must be read-only. Any mutation during `preflight` is a story failure. +- Abort before promotion must leave current epoch active. Do not delete source ciphertext or make target ciphertext authoritative before verification/promotion. +- Raw target/current key material must only enter local operator command/process memory. Never place it in DB, manifest, logs, traces, command output or story evidence. + +### File map + +Likely UPDATE: + +- `crates/crank-runtime/src/secret_crypto.rs` +- `crates/crank-runtime/src/error.rs` +- `crates/crank-runtime/src/execution_failure.rs` +- `crates/crank-runtime/src/lib.rs` +- `crates/crank-registry/src/model.rs` +- `crates/crank-registry/src/error.rs` +- `crates/crank-registry/src/postgres/secret.rs` +- `crates/crank-registry/src/postgres/mod.rs` +- `crates/crank-registry/src/migrations.rs` +- `crates/crank-registry/src/migrations/authority.rs` +- `crates/crank-registry/src/migrations/schema_guard.rs` +- `crates/crank-registry/tests/integration/migrations.rs` +- `crates/crank-registry/tests/integration/operations_artifacts.rs` +- `apps/admin-api/src/main.rs` +- `apps/admin-api/src/bin/crank-migrate.rs` +- `apps/admin-api/src/service.rs` +- `apps/admin-api/src/service/secrets.rs` +- `apps/admin-api/tests/config_startup.rs` +- `apps/admin-api/tests/migration_command.rs` +- `apps/admin-api/tests/integration/credential_lifecycle.rs` +- `apps/mcp-server/src/main.rs` +- `apps/mcp-server/tests/config_startup.rs` +- `apps/mcp-server/tests/integration/catalog_access.rs` +- `apps/mcp-server/tests/integration/common.rs` +- `docs/secrets-and-auth.md` +- `docs/runtime-config.md` +- `docs/migrations.md` +- `docs/database-schema.md` +- `docs/data-model.md` +- `docs/production-checklist.md` +- `docs/capability-inventory.json` +- `docs/capability-baseline/manifest.json` +- `docs/capability-baseline/results.json` +- `docs/schemas/migration-sequence.json` +- `.sqlx/query-*.json` only if SQLx offline metadata changes. + +Likely NEW: + +- `crates/crank-registry/src/migrations/master_key_identity_v7.sql` +- `crates/crank-registry/src/migrations/master_key_identity_v7.rs` if Rust-side migration steps are required. +- `crates/crank-registry/src/postgres/master_key.rs` or equivalent focused module. +- `crates/crank-registry/tests/integration/master_key_identity.rs` or additional integration module. +- `crates/crank-runtime/tests/secret_crypto.rs` if crypto tests outgrow inline module. +- `apps/admin-api/tests/master_key_rotation_command.rs` if CLI coverage is clearer outside existing `migration_command.rs`. + +Do not modify: + +- Frozen migration v1–v6 source bytes/checksums except appending v7 metadata. +- Story 1.10 raw Secret/key lifecycle semantics except adding epoch metadata. +- Rust/npm toolchain or dependencies unless unavoidable and explicitly justified. +- UI files unless adding an actual UI surface; a CLI/operator path is sufficient for this story. + +### Testing requirements + +Required targeted tests: + +```bash +cargo test -p crank-runtime secret_crypto -- --test-threads=1 +cargo test -p crank-registry --test integration migrations -- --test-threads=1 +cargo test -p crank-registry --test integration master_key -- --test-threads=1 +cargo test -p admin-api --test config_startup -- --test-threads=1 +cargo test -p mcp-server --test config_startup -- --test-threads=1 +cargo test -p admin-api --test master_key_rotation_command -- --test-threads=1 +cargo test -p admin-api --test integration credential_lifecycle -- --test-threads=1 +cargo test -p mcp-server --test integration catalog_access -- --test-threads=1 +just migration-contract-check +just config-contract-check +just rust-boundaries +just capability-inventory-check +python3 scripts/check-community-scope.py --root . --files +git diff --check +just verify +``` + +Run `just sqlx-prepare ` and `just sqlx-check` if SQLx offline metadata changes. + +UI checks are required only if UI files change: + +```bash +just verify-ui +``` + +### Review traps to avoid + +- Do not call config fingerprint the master-key fingerprint. Config fingerprint deliberately records only secret configured/unconfigured state and is not key identity. +- Do not store a hash of raw key that could be used directly as an encryption key or leaked secret surrogate. +- Do not silently auto-register a new identity on a populated database with existing encrypted Secrets unless the current key proves decryptability and the path is explicitly tested. +- Do not allow Admin and MCP to each initialize different identities depending on startup order. +- Do not claim backup/restore complete; only store opaque reference metadata and defer full restore proof. +- Do not make rotation a runtime HTTP endpoint reachable remotely unless explicitly protected by local operator boundary and tests. Prefer controlled CLI. +- Do not make readiness fail open when PostgreSQL key identity check is unavailable. +- Do not include request/trace/master-key IDs in metric labels; metrics remain low-cardinality typed outcomes only. +- Do not update Capability Inventory to implemented until targeted evidence and final gates pass. + +### Previous story intelligence + +- Story 1.10 hardened credential lifecycle and added raw secret/key redaction, active Secret validation and immediate revocation. Preserve those invariants. +- Story 1.10 closure updated `h2` to 0.4.16 for `RUSTSEC-2026-0258`; do not introduce unrelated dependency churn. +- Story 1.4 established migration authority. All durable schema change must be v7 append-only with exact checksum and schema guard tests. +- Story 1.3 established typed config. Reusable crates must not read environment variables directly. +- Story 1.8 established typed execution errors. Secret crypto failures crossing product boundaries must normalize to safe typed outcomes. + +### References + +- `_bmad-output/planning-artifacts/epics.md` — Story 1.11 and Epic 1 sequence. +- `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` — FR-3 and FR-43 master-key/recovery consequences. +- `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md` — protected master-key backup evidence contract. +- `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` — AD-15, AD-16, AD-17, AD-22, AD-24. +- `_bmad-output/project-context.md` — crypto/secrets/config/migration/process rules. +- `_bmad-output/implementation-artifacts/1-10-lifecycle-auth-profiles-machine-keys.md` — previous FR-3 slice and review lessons. +- `crates/crank-runtime/src/secret_crypto.rs` — current crypto implementation. +- `crates/crank-registry/src/postgres/secret.rs` — current Secret version persistence. +- `apps/admin-api/src/main.rs`, `apps/mcp-server/src/main.rs` — current independent `SecretCrypto::new` wiring. + +## Dev Agent Record + +### Agent Model Used + +GPT-5 Codex + +### Debug Log References + +- 2026-08-21: Story context created by `bmad-create-story` during the next-story transition. +- 2026-08-21: Implemented first Story 1.11 slice: crypto identity/epoch, v7 migration, registry identity verification and Admin/MCP startup wiring. +- 2026-08-21: Verification passed for initial identity slice: targeted crypto/registry/migration tests, migration contract, explicit Community scope, diff check and full `just verify`. +- 2026-08-21: Completed operator-controlled rotation workflow: preflight/status/rotate/resume/verify/promote/abort, active-rotation write rejection, target-ciphertext staging, atomic promotion and old-key rejection. +- 2026-08-21: Initial final verification passed: targeted Story 1.11 tests, capability inventory/baseline, explicit Community scope, `git diff --check` and full `just verify`. +- 2026-08-22: Closed code-review patches: strong config/crypto master-key minimum, target-epoch startup, populated DB decryptability proof before first identity registration, active-epoch write guards, active-rotation delete/write guards, rerunnable aborted rotations, bounded paginated rotation batches and exact v7 schema guard validation. + +### Completion Notes List + +- Implemented durable master-key identity foundation: PostgreSQL stores active epoch/fingerprint/cipher contract only; Admin API and MCP verify it before readiness; mismatch fails closed with bounded diagnostics. +- Implemented epoch-aware Secret encryption/decryption with backward-compatible legacy v1 support and strict epoch checks for current ciphertext. +- Implemented controlled local `crank-migrate master-key` operator workflow: `status`, read-only `preflight`, resumable `rotate`, `verify`, atomic `promote`, and `abort`; key material is supplied via local files and never echoed. +- Implemented fail-closed Secret create/rotate behavior during active rotation, durable target ciphertext staging, checkpointed resume, verification gate and old-key rejection after promotion. +- Implemented review hardening: `CRANK_MASTER_KEY` requires at least 32 bytes in config and crypto, first identity registration proves existing decryptability on populated databases, Secret writes verify the active epoch under transaction, and master-key rotation/write coordination uses PostgreSQL transactional table locks without migration-boundary advisory locks. +- Implemented bounded rotation iteration with paginated Secret-version reads, rerunnable aborted/failed deterministic rotations and exact v7 schema guard validation in a split module kept below code-health file limits. +- Updated operator docs, data/schema docs, migration sequence contract, Capability Inventory and baseline evidence for the FR-3 master-key slice. Epic 7 backup/restore/RPO/RTO remains explicitly deferred. + +### Final Verification + +- `cargo test -p crank-runtime secret_crypto -- --test-threads=1` — passed, 11 tests. +- `cargo test -p crank-registry --test integration master_key_identity -- --test-threads=1` — passed, 7 tests. +- `cargo test -p crank-registry --test integration migrations -- --test-threads=1` — passed, 23 tests. +- `cargo test -p crank-registry --test integration operations_artifacts -- --test-threads=1` — passed, 10 tests. +- `cargo test -p admin-api --test migration_command -- --test-threads=1` — passed, 5 tests. +- `cargo test -p admin-api --test config_startup -- --test-threads=1` — passed, 5 tests. +- `cargo test -p admin-api --test integration secrets_import_auth -- --test-threads=1` — passed, 6 tests. +- `cargo test -p admin-api --test integration operations_agents -- --test-threads=1` — passed, 7 tests. +- `cargo test -p mcp-server --test config_startup -- --test-threads=1` — passed, 4 tests. +- `cargo test -p mcp-server --test integration catalog_access -- --test-threads=1` — passed, 20 tests. +- `cargo test -p mcp-server --test integration transport_protocol -- --test-threads=1` — passed, 13 tests. +- `cargo test -p crank-config --all-targets` — passed, 25 tests. +- `cargo fmt --all --check` — passed. +- `cargo check -p crank-registry -p crank-config -p admin-api --bin crank-migrate -p admin-api --test config_startup -p mcp-server --test config_startup` — passed. +- `cargo clippy -p crank-runtime -p crank-config --all-targets --all-features -- -D warnings` — passed. +- `cargo run -p crank-config --bin crank-config-contract -- --check` — passed. +- `just rust-code-health` — passed. +- `just rust-boundaries` — passed. +- `just migration-contract-check` — passed with `{"status":"contract_current"}`. +- `just capability-inventory-check` — passed with inventory `implemented=21` and baseline `flows=33`. +- `python3 scripts/check-community-scope.py --root . --files <36 Story 1.11/review-patch paths>` — passed, 36 files scanned. +- `git diff --check` — passed. +- `just verify` — passed. + +### File List + +- `_bmad-output/implementation-artifacts/1-11-master-key-identity-rotation.md` +- `apps/admin-api/src/bin/crank-migrate.rs` +- `apps/admin-api/src/error.rs` +- `apps/admin-api/src/main.rs` +- `apps/admin-api/src/service.rs` +- `apps/admin-api/src/service/secrets.rs` +- `apps/admin-api/tests/config_startup.rs` +- `apps/admin-api/tests/integration/common.rs` +- `apps/admin-api/tests/integration/auth_rate_limit.rs` +- `apps/admin-api/tests/integration/community_access_usage.rs` +- `apps/admin-api/tests/integration/operations_agents.rs` +- `apps/admin-api/tests/integration/secrets_import_auth.rs` +- `apps/admin-api/tests/migration_command.rs` +- `apps/mcp-server/src/main.rs` +- `apps/mcp-server/tests/config_startup.rs` +- `apps/mcp-server/tests/integration/catalog_access.rs` +- `apps/mcp-server/tests/integration/catalog_access/approval_access.rs` +- `apps/mcp-server/tests/integration/common.rs` +- `apps/mcp-server/tests/integration/transport_protocol.rs` +- `crates/crank-community-mcp/src/app.rs` +- `crates/crank-config/src/process.rs` +- `crates/crank-config/src/render.rs` +- `crates/crank-config/src/schema.rs` +- `crates/crank-config/tests/contract.rs` +- `crates/crank-config/tests/generation.rs` +- `crates/crank-config/tests/redaction.rs` +- `crates/crank-runtime/src/secret_crypto.rs` +- `crates/crank-registry/src/error.rs` +- `crates/crank-registry/src/lib.rs` +- `crates/crank-registry/src/model.rs` +- `crates/crank-registry/src/postgres/mod.rs` +- `crates/crank-registry/src/postgres/secret.rs` +- `crates/crank-registry/src/postgres/master_key.rs` +- `crates/crank-registry/src/migrations.rs` +- `crates/crank-registry/src/migrations/authority.rs` +- `crates/crank-registry/src/migrations/authority_tests.rs` +- `crates/crank-registry/src/migrations/schema_guard.rs` +- `crates/crank-registry/src/migrations/schema_guard_v7.rs` +- `crates/crank-registry/src/migrations/master_key_identity_v7.rs` +- `crates/crank-registry/src/migrations/master_key_identity_v7.sql` +- `crates/crank-registry/tests/integration.rs` +- `crates/crank-registry/tests/integration/master_key_identity.rs` +- `crates/crank-registry/tests/integration/migrations.rs` +- `crates/crank-registry/tests/integration/operations_artifacts.rs` +- `docs/capability-inventory.json` +- `docs/capability-baseline/manifest.json` +- `docs/capability-baseline/required-surfaces.json` +- `docs/capability-baseline/outcome-taxonomy.json` +- `docs/capability-baseline/manual-checklist.md` +- `docs/capability-baseline/results.json` +- `docs/data-model.md` +- `docs/database-schema.md` +- `docs/migrations.md` +- `docs/production-checklist.md` +- `docs/runtime-config.md` +- `docs/secrets-and-auth.md` +- `docs/schemas/runtime-config.schema.json` +- `.env.example` +- `deploy/community/.env.example` +- `deploy/community/.env.images.example` +- `docs/schemas/migration-sequence.json` + +## Change Log + +- 2026-08-21: Created Story 1.11 from Epic 1 FR-3 with brownfield master-key, SecretCrypto, registry Secret version and migration authority context. +- 2026-08-21: Added initial implementation for master-key identity registration/verification and epoch-aware Secret ciphertext. +- 2026-08-21: Completed master-key rotation workflow, docs/evidence updates and final verification; story moved to `review`. +- 2026-08-22: Applied and verified all Story 1.11 code-review patches; story moved to `done`. diff --git a/_bmad-output/implementation-artifacts/1-12-admin-bootstrap-login-session-lifecycle.md b/_bmad-output/implementation-artifacts/1-12-admin-bootstrap-login-session-lifecycle.md new file mode 100644 index 0000000..df6e0ca --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-12-admin-bootstrap-login-session-lifecycle.md @@ -0,0 +1,463 @@ +--- +story_id: "1.12" +story_key: "1-12-admin-bootstrap-login-session-lifecycle" +requirement: "FR-3" +status: "done" +baseline_commit: "767428436d3a54e60809a727044dfcec48e1f1dd + uncommitted Story 1.10/1.11 closure worktree" +created: "2026-08-22T01:25:22+03:00" +--- + +# Story 1.12: Защитить Admin bootstrap, login и session lifecycle + +Status: done + +## Story + +As an оператор self-hosted установки, +I want безопасно инициализировать и восстанавливать единственного администратора, +so that Crank не имеет default credentials и удалённый атакующий не может захватить Admin UI. + +## Operational Brief + +Story 1.12 закрывает последнюю часть FR-3 вокруг human Admin identity. После 1.10 credentials/Auth Profiles/MCP/approval keys стали production-safe, а после 1.11 master-key identity стала проверяемой и пригодной для recovery. Но Admin UI всё ещё может быть захвачен, если первичная credential создаётся из статического env, login раскрывает различия account/verifier, session можно зафиксировать, browser mutation обходит CSRF/CORS, либо recovery доступен удалённо. + +Цель Story 1.12 — сделать Admin auth boundary PostgreSQL-authoritative и browser-safe: + +- нет default username/password и нет service-start auto-bootstrap из raw password; +- первый Admin создаётся только через bounded one-time local bootstrap contract; +- login/session/logout/password rotation/recovery дают constant-shape безопасные ошибки; +- browser session и CSRF lifecycle атомарно отзываются сервером; +- CORS deny-by-default, trusted-proxy allowlist, TLS/secure-cookie policy и security headers становятся executable contract; +- UI использует только shared `CrankAuth` и показывает безопасные RU/EN states с Request ID/Trace ID. + +Это security foundation для всех последующих Admin flows: Agent catalog (1.13), approvals (1.14), history/usage (1.15), onboarding (1.16) и production deployment/recovery Epic 7. + +## Requirement / Architecture Trace + +- **Direct requirement:** FR-3. +- **Primary architecture:** AD-22 Admin identity and web security boundary. +- **Supporting architecture:** AD-1, AD-4, AD-11, AD-15, AD-16, AD-17, AD-18, AD-19, AD-20, AD-24. +- **Applicable NFR:** NFR-S1, NFR-S2, NFR-S4, NFR-S6, NFR-S7, NFR-S8, NFR-O1, NFR-O4, NFR-O5, NFR-C1, NFR-C3, NFR-C4. +- **Primary risk/evidence:** E1-R-010 — bootstrap/session/CSRF/proxy/recovery takeover; required groups E1-26, E1-27 and E1-28. + +## Scope + +In scope: + +- One-time Admin bootstrap contract stored in PostgreSQL, created/consumed through local operator boundary only. +- Removal or deprecation of raw `CRANK_BOOTSTRAP_ADMIN_PASSWORD` as automatic startup credential source. +- Bootstrap completion endpoint/command with bounded secret validation, atomic first-admin creation and replay/race protection. +- Password hashing/verifier policy using existing `crank-community-auth` Argon2id path; no plaintext persistence. +- Login rate limit/backoff specific to auth attempts with constant-shape account/password/throttle/session errors. +- Session identifier generation, hashed persistence, rotation after authentication, server-side expiry/revocation and cookie attributes. +- CSRF token lifecycle tied to session, server-side validation on all state-changing browser requests and revocation on logout/password rotation/recovery. +- CORS deny-by-default and explicit same-origin/allowed-origin behavior for Admin API. +- Trusted-proxy allowlist replacing the current boolean-only forwarded-header trust for production exposure. +- TLS/secure-cookie startup/readiness policy for non-loopback production exposure. +- Security headers for Admin/browser responses. +- Offline recovery command/endpoint constrained to local operator boundary and valid master-key identity; it creates no second account, reveals no old password/secret/key material and revokes all sessions/tokens. +- RU/EN UI states for bootstrap, login, logout/expired session, password rotation and recovery-related messages. +- Integration/Playwright/security tests and Capability Inventory/baseline evidence for this FR-3 slice. + +Out of scope: + +- New teams, multi-admin RBAC, SSO/OIDC/SAML or hosted SaaS identity. +- Full Epic 7 backup/restore/PITR/RPO/RTO qualification; 1.12 only leaves compatible recovery hooks. +- Master-key rotation/re-encryption internals already owned by 1.11. +- Credential lifecycle for Auth Profiles/MCP keys/approval keys already owned by 1.10. +- Redesign of Agent catalog, approvals, history or onboarding flows. +- Browser telemetry relay or GlitchTip trace export; Request ID/Trace ID are shown when boundary errors already provide them. + +## Acceptance Criteria + +1. **One-time local bootstrap contract** + - Given новая установка без Admin credential + - When оператор запускает локальный bootstrap process + - Then создаётся bounded одноразовый bootstrap contract без default username/password + - And raw bootstrap secret не печатается в service logs, container inspect output, telemetry или committed configuration. + +2. **Atomic first-admin creation** + - Given действующий bootstrap contract + - When первый администратор задаёт credential + - Then credential сохраняется только как memory-hard password verifier, bootstrap атомарно становится использованным + - And concurrent или повторный bootstrap request не создаёт второго администратора и не переактивирует contract. + +3. **Constant-shape bootstrap rejection** + - Given использованный, истёкший или malformed bootstrap secret + - When caller пытается завершить bootstrap + - Then запрос отклоняется constant-shape ошибкой без раскрытия состояния account + - And событие записывается в bounded security audit без secret. + +4. **Login throttling without account enumeration** + - Given существующий Admin account + - When выполняются login attempts + - Then действует bounded rate limit и progressive backoff по безопасно выбранному scope + - And ответы для неверного account, password, revoked session и throttling не позволяют определить существование account или verifier details. + +5. **Secure browser session** + - Given успешный login + - When создаётся browser session + - Then session identifier имеет достаточную entropy, сохраняется в безопасной форме и ротируется после authentication + - And cookie использует `Secure` при TLS, `HttpOnly`, подходящий `SameSite`, bounded lifetime и явную expiry. + +6. **CSRF and CORS boundary** + - Given state-changing browser request + - When Admin UI вызывает API + - Then server проверяет действующую session и CSRF contract, а CORS deny-by-default отклоняет чужой origin + - And GET/read endpoint не становится обходом mutation или CSRF защиты. + +7. **Trusted proxy and TLS exposure** + - Given non-loopback production exposure + - When Admin API определяет scheme, host и client identity + - Then TLS обязателен, forwarded headers принимаются только от explicit trusted-proxy allowlist + - And spoofed forwarding headers от недоверенного peer игнорируются. + +8. **Password rotation and recovery revoke all browser auth state** + - Given password rotation или recovery + - When новое credential успешно активировано + - Then все browser sessions и CSRF tokens атомарно отзываются, создаётся audit event + - And старое credential и существующая session перестают работать без restart. + +9. **Offline recovery is local and master-key-bound** + - Given потерянное Admin credential + - When оператор выполняет offline recovery + - Then recovery доступно только через local operator boundary и требует валидной master-key identity + - And оно не раскрывает старый password, stored secrets или key material и не создаёт второй account. + +10. **Shared UI session handling** + - Given session expiry, logout или server-side revocation + - When UI выполняет следующий protected request + - Then shared `CrankAuth` обрабатывает `401`, очищает локальное session state и направляет пользователя в login flow + - And protected pages не реализуют собственный обходной auth guard. + +11. **RU/EN auth UX states** + - Given Admin UI на RU и EN + - When выполняются bootstrap, login, logout, password rotation или recovery-related actions + - Then присутствуют loading, generic error, throttled, expired-session и success states + - And сообщения содержат Request ID/Trace ID, но не раскрывают account existence или security internals. + +12. **Final web-security matrix** + - Given web-security test suite + - When выполняются negative tests + - Then покрыты bootstrap replay/race, brute-force throttling, session fixation, CSRF, hostile Origin, spoofed proxy headers, expired/revoked sessions и recovery misuse + - And проходят Admin API integration tests, Playwright auth flows и `just verify`. + +## Tasks / Subtasks + +- [x] Task 1. Freeze current auth/security oracle and remove unsafe bootstrap assumptions (AC: 1, 4, 7, 12) + - [x] Document current brownfield behavior: env auto-bootstrap, session cookie, global API limiter, forwarded-header boolean, no CSRF middleware, no CORS/security-header contract. + - [x] Decide compatibility handling for existing `CRANK_BOOTSTRAP_ADMIN_EMAIL/PASSWORD`: remove raw password from production bootstrap path or keep only as explicit development/test compatibility with startup failure in production. + - [x] Add RED tests proving there is no default credential and service startup does not print/commit bootstrap secret material. + +- [x] Task 2. PostgreSQL-authored bootstrap/session/recovery schema (AC: 1, 2, 3, 8, 9, 12) + - [x] Add append-only migration v8 through `MigrationAuthority` only; do not edit v1..v7 bytes/checksums. + - [x] Add tables/columns for bootstrap contracts, CSRF token state, login/backoff state and security audit as needed. + - [x] Validate v8 schema in `schema_guard`; preserve v7/N-1 readability where possible. + - [x] Real-PG tests cover fresh/current/corrupt/replay/rollback and direct SQL invariants. + +- [x] Task 3. Bootstrap domain and local operator boundary (AC: 1, 2, 3, 9) + - [x] Implement typed bootstrap secret/token with fixed entropy, TTL, max attempts and safe hash-at-rest. + - [x] Provide local operator command or local-only endpoint for contract creation and offline recovery; remote Admin UI must not mint recovery contracts. + - [x] Bootstrap completion atomically creates exactly one Owner membership for the default workspace and marks contract used in the same transaction. + - [x] Concurrent completion/replay/malformed/expired attempts return the same safe external shape and write bounded audit. + +- [x] Task 4. Login rate/backoff and constant-shape auth errors (AC: 4, 12) + - [x] Add auth-specific throttle/backoff keyed by safe scope: peer/client identity plus normalized submitted account bucket, never raw email in logs/metrics. + - [x] Preserve generic `invalid email or password` outward behavior for missing account, bad verifier, disabled account and verifier failure. + - [x] Prove timing/message/status/body/headers do not reveal account existence beyond unavoidable bounded behavior. + - [x] Keep global API rate limiter, but do not count it as the login security proof. + +- [x] Task 5. Session and CSRF lifecycle (AC: 5, 6, 8, 10, 12) + - [x] Session token remains high entropy and persisted only as server-side hash. + - [x] Successful login rotates any pre-auth/browser state and returns session + CSRF contract. + - [x] Cookie attributes are explicit: `HttpOnly`, `SameSite`, path, max-age/expiry and `Secure` whenever effective scheme is HTTPS. + - [x] State-changing browser requests require valid session plus CSRF token/header; safe methods must not mutate. + - [x] Logout, expiry, password rotation and recovery revoke session and CSRF state without restart. + +- [x] Task 6. Web exposure hardening (AC: 6, 7, 11, 12) + - [x] Add CORS deny-by-default policy for Admin API; only same-origin or explicit configured origins pass. + - [x] Replace boolean trusted-forwarded behavior with explicit trusted-proxy allowlist; untrusted spoofed `Forwarded`/`X-Forwarded-*` headers are ignored. + - [x] Non-loopback production exposure requires TLS/effective HTTPS or fails startup/readiness with bounded typed config/security diagnostic. + - [x] Add security headers for browser responses without breaking static UI delivery. + +- [x] Task 7. Password rotation and offline recovery (AC: 8, 9, 12) + - [x] Change password verifies current credential, writes memory-hard verifier and revokes all other sessions/CSRF tokens atomically. + - [x] Recovery requires local operator boundary and valid master-key identity from Story 1.11; it replaces credential for the single Admin account only. + - [x] Recovery never reveals old password, stored Secrets, master key bytes, ciphertext, Secret plaintext or key material. + - [x] Audit event records action/outcome/actor/source with request_id/trace_id when boundary-originated and safe local operator metadata for CLI. + +- [x] Task 8. UI auth flows and shared guard (AC: 10, 11) + - [x] Add bootstrap page/flow only when backend reports bootstrap-required state; otherwise login remains normal path. + - [x] Login form has loading, throttled, generic error, expired-session and success states; duplicate submits are disabled. + - [x] Password rotation UI revokes session state correctly; `CrankAuth` handles `401` centrally and protected pages do not fork local auth guards. + - [x] Add RU/EN text simultaneously; messages may show safe Request ID/Trace ID from API errors. + +- [x] Task 9. Evidence, inventory and docs (AC: 12) + - [x] Update docs for bootstrap/recovery/operator procedure, security headers, CSRF, CORS and trusted proxy. + - [x] Update `docs/capability-inventory.json` and baseline evidence only after tests pass. + - [x] Update runtime config schema/docs/examples if bootstrap/trusted-proxy/CSRF fields change; no direct env reads outside `crank-config`. + +- [x] Task 10. Final verification and handoff (AC: 12) + - [x] Run targeted auth/session/bootstrap/security suites. + - [x] Run UI build and targeted Playwright auth/bootstrap flows if UI changed. + - [x] Run migration/config/boundary/capability/community-scope gates and final `just verify`. + - [x] Update Dev Agent Record, File List, Change Log and status to `review` only after gates pass. + +### Review Findings + +- [x] [Review][Patch] Remove demo-seed startup Admin auto-bootstrap from raw/default password [apps/admin-api/src/main.rs:228] +- [x] [Review][Patch] Make login missing/bad/disabled verifier constant-shape and enforce active-user checks on every login path [crates/crank-community-auth/src/password_provider.rs:39] +- [x] [Review][Patch] Include safe client/peer identity in auth backoff scope [apps/admin-api/src/service/auth.rs:157] +- [x] [Review][Patch] Audit rejected bootstrap replay/expired/wrong-token attempts and enforce max-attempt contract semantics [apps/admin-api/src/service/auth.rs:42] +- [x] [Review][Patch] Validate bootstrap token before expensive password hashing [apps/admin-api/src/service/auth.rs:42] +- [x] [Review][Patch] Make password rotation atomic with all-session/CSRF revocation [apps/admin-api/src/service/auth.rs:376] +- [x] [Review][Patch] Make recovery password policy match bootstrap/change-password bounds [apps/admin-api/src/bin/crank_migrate/admin_auth_command.rs:104] +- [x] [Review][Patch] Make safe session GET non-mutating for CSRF state [apps/admin-api/src/service/auth.rs:301] +- [x] [Review][Patch] Compare full same-origin tuple including scheme for Admin CORS boundary [apps/admin-api/src/auth.rs:217] +- [x] [Review][Patch] Complete auth UI required states: duplicate-submit lock, Request ID/Trace ID rendering, expired/success/loading RU/EN messages [apps/ui/js/login.js:53] + +## Dev Notes + +### Brownfield facts to preserve or replace intentionally + +- Current Admin startup calls `AdminService::bootstrap_admin_user()` from `apps/admin-api/src/main.rs`; service hashes `CRANK_BOOTSTRAP_ADMIN_PASSWORD` and calls `ensure_bootstrap_user()` on startup. This violates the target production model unless narrowed to explicit development/test compatibility. +- Current `ensure_bootstrap_user()` upserts an existing email only when `password_hash is null`, but still treats static env as bootstrap authority. Story 1.12 needs a durable one-time contract with race/replay protection. +- Current `crank-community-auth::hash_password()` uses Argon2id and a pepper; reuse it rather than adding another password hashing crate. +- Current session cookie value is `session_id.secret.expiry`, persisted by hashing `session_id + value + CRANK_SESSION_SECRET`; keep server-side hash persistence and harden around it. +- Current cookie helper sets `HttpOnly`, `SameSite=Lax`, path `/`, max-age and `Secure` based on `cookie_secure`; Story 1.12 must make effective-scheme/TLS policy explicit. +- Current `require_session`/`require_workspace_session` validates session and workspace/owner role for mutations, but there is no CSRF middleware. +- Current `apply_api_rate_limit` is global and can use forwarded headers when `trust_forwarded_headers` is true. Story 1.12 needs auth-specific throttling and explicit proxy allowlist. +- Current `CrankAuth` centralizes `401` handling and local session mirror; extend it rather than duplicating page-level guards. +- Current login UI is minimal and only handles required/invalid/generic states. Add bounded states without leaking account existence. + +### Architecture and implementation constraints + +- `crank-community-auth` owns auth state-machine helpers and browser auth primitives; `apps/admin-api` owns Axum routes/middleware and service use cases; `crank-registry` owns PostgreSQL persistence and migrations. +- `crank-config` remains the only runtime env parser. New config fields for bootstrap, trusted proxies, CSRF, CORS or security exposure must be added through the typed schema/generator/examples/tests. +- Durable schema changes use v8 append-only migration through `crank-registry::MigrationAuthority`; service startup remains read-only compatibility preflight. +- Do not add new dependencies unless existing crates cannot implement the requirement safely. Prefer `rand`, `sha2`, `base64`, `time`, `uuid`, `argon2`, `tower-http`/Axum facilities already in the workspace if already available. +- Never log or serialize raw password, bootstrap secret, CSRF token, session secret, session token, password pepper, master key, ciphertext, Secret plaintext or full cookie header. +- Request ID/Trace ID may be exposed only as bounded support identifiers; never place IDs, emails, origins, IPs or user values in metric labels. +- Keep Community scope: single self-hosted workspace/admin model. No SSO, teams or multi-tenant RBAC. + +### Security decisions to freeze during implementation + +- **Bootstrap contract:** exactly one active unexpired bootstrap contract; stored token hash only; token shown once by local operator command; completion consumes token atomically. +- **Recovery:** local operator boundary only; requires current master-key identity verification; resets single Admin credential and revokes all browser auth state; does not bypass encrypted Secret protection. +- **CSRF:** all unsafe methods under `/api/auth` and `/api/admin` require valid session + CSRF token except explicit bootstrap completion if it uses a one-time bootstrap secret before session exists. +- **CORS:** no wildcard credentials. Cross-origin browser mutation is rejected unless an explicit configured origin is allowed. +- **Proxy:** forwarded scheme/client identity is trusted only when the immediate peer matches configured trusted-proxy allowlist. Otherwise peer socket identity wins and spoofed headers are ignored. +- **TLS:** non-loopback production exposure must use HTTPS/effective TLS for browser Admin; otherwise startup/readiness fails closed or explicitly stays development-only. + +### Project Structure Notes + +Likely UPDATE: + +- `apps/admin-api/src/app.rs` +- `apps/admin-api/src/auth.rs` +- `apps/admin-api/src/routes/auth.rs` +- `apps/admin-api/src/service/auth.rs` +- `apps/admin-api/src/service.rs` +- `apps/admin-api/src/dto.rs` +- `apps/admin-api/src/error.rs` +- `apps/admin-api/src/main.rs` +- `apps/admin-api/src/rate_limit.rs` +- `apps/admin-api/tests/integration/auth_rate_limit.rs` +- `apps/admin-api/tests/integration/common.rs` +- `apps/admin-api/tests/config_startup.rs` +- `apps/admin-api/tests/integration.rs` +- `crates/crank-community-auth/src/{lib.rs,hashing.rs,session_cookie.rs}` +- `crates/crank-registry/src/postgres/auth.rs` +- `crates/crank-registry/src/model.rs` +- `crates/crank-registry/src/error.rs` +- `crates/crank-registry/src/migrations/{authority.rs,schema_guard.rs}` +- `crates/crank-registry/tests/integration/{workspace_access.rs,migrations.rs}` +- `crates/crank-config/src/{schema.rs,process.rs,render.rs}` +- `crates/crank-config/tests/{contract.rs,generation.rs,redaction.rs}` +- `apps/ui/js/{api.js,auth.js,login.js,i18n.js}` +- `apps/ui/html/login.html` +- `apps/ui/index.html` if shell/protected auth handling changes +- `apps/ui/tests/e2e/{login.spec.js,staging-authenticated.spec.js}` or a new auth/bootstrap spec +- `.env.example`, `deploy/community/.env.example`, `deploy/community/.env.images.example`, `docker-compose.yml`, `deploy/community/docker-compose*.yml` if config/bootstrap contract changes +- `docs/{runtime-config.md,secrets-and-auth.md,deployment.md,production-checklist.md,ui.md}` +- `docs/schemas/{runtime-config.schema.json,migration-sequence.json}` +- `docs/capability-inventory.json`, `docs/capability-baseline/*` + +Likely NEW: + +- `crates/crank-registry/src/migrations/admin_auth_lifecycle_v8.rs` +- `crates/crank-registry/src/migrations/admin_auth_lifecycle_v8.sql` +- `apps/admin-api/tests/integration/admin_auth_lifecycle.rs` +- `apps/ui/tests/e2e/admin-auth.spec.js` + +Do not touch: + +- Immutable migration source bytes v1..v7 except registering v8 in the sequence. +- MCP transport/session semantics unless a shared config/docs field requires alignment. +- Agent/Operation/approval lifecycle behavior except auth middleware protections applying globally. +- Cargo/npm/toolchain versions unless a separate security gate forces it and evidence is recorded. + +### Testing Requirements + +Targeted Rust/API: + +```bash +cargo test -p crank-community-auth --all-targets +cargo test -p crank-registry --test integration workspace_access -- --test-threads=1 +cargo test -p crank-registry --test integration migrations -- --test-threads=1 +cargo test -p admin-api --test integration admin_auth_lifecycle -- --test-threads=1 +cargo test -p admin-api --test integration auth_rate_limit -- --test-threads=1 +cargo test -p admin-api --test config_startup -- --test-threads=1 +cargo test -p crank-config --all-targets +``` + +UI if changed: + +```bash +just ui-build +cd apps/ui && npx playwright test tests/e2e/admin-auth.spec.js --project=chromium +``` + +Final gates: + +```bash +just migration-contract-check +just rust-boundaries +just capability-inventory-check +python3 scripts/check-community-scope.py --root . --files +git diff --check +just verify +``` + +Run `just sqlx-prepare ` and `just sqlx-check` if SQLx offline metadata changes. + +### Review traps to avoid + +- Do not treat existing env bootstrap password as production-safe. It is raw secret in committed/deployment-visible configuration paths. +- Do not count global API rate limiting as login backoff proof. +- Do not implement CSRF only in UI; server must reject missing/invalid token. +- Do not trust `X-Forwarded-*` because config says “trust forwarded headers”; trust must be peer allowlist-based. +- Do not reveal account existence by different status, code, message, body shape, retry context or audit/log details. +- Do not revoke only “other” sessions on password recovery; recovery must revoke all existing browser sessions/tokens. +- Do not create a second Admin account during recovery. +- Do not add local auth guards in protected UI pages; use `CrankAuth`. +- Do not claim full Epic 7 restore/recovery complete. +- Do not include email, origin, IP, request_id or trace_id in metric labels. +- Do not mark Capability Inventory evidence implemented until targeted tests and final gates pass. + +### References + +- `_bmad-output/planning-artifacts/epics.md` — Story 1.12 AC and Epic 1 ordering. +- `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` — FR-3 and production web baseline consequences. +- `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md` — confirmed web/admin security decisions. +- `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` — AD-22 and related ADs. +- `_bmad-output/test-artifacts/test-design-epic-1.md` — E1-R-010, E1-26, E1-27, E1-28. +- `_bmad-output/project-context.md` — auth, secrets, config, migration, UI and test rules. +- `_bmad-output/implementation-artifacts/1-10-lifecycle-auth-profiles-machine-keys.md` — previous FR-3 credential lifecycle slice. +- `_bmad-output/implementation-artifacts/1-11-master-key-identity-rotation.md` — previous FR-3 master-key identity/recovery foundation. +- `apps/admin-api/src/service/auth.rs` — current login/session/bootstrap behavior. +- `crates/crank-community-auth/src/session_cookie.rs` — current session token/cookie helpers. +- `crates/crank-registry/src/postgres/auth.rs` — current user/session persistence. +- `apps/admin-api/src/rate_limit.rs` — current global rate/proxy key behavior. +- `apps/ui/js/auth.js`, `apps/ui/js/login.js`, `apps/ui/js/api.js` — current browser auth flow. + +## Dev Agent Record + +### Agent Model Used + +GPT-5 Codex + +### Debug Log References + +- 2026-08-22: Story context created by `bmad-create-story`. Existing Story 1.11 file is `done`; sprint tracker still needed sync from `review` to `done`. Story 1.10 remains `review` in sprint tracker and is treated as dependency risk, not silently closed. +- 2026-08-22: Story moved to `in-progress`; baseline commit `767428436d3a54e60809a727044dfcec48e1f1dd` plus dirty worktree from prior Story 1.10/1.11 closure remains intentionally preserved. +- 2026-08-22: Initial implementation passed `just verify`; subsequent verification found missing offline recovery, Playwright auth coverage and explicit trusted-proxy/TLS exposure policy. These gaps were fixed before final handoff. +- 2026-08-22: Final `just verify` completed with exit code 0 after bootstrap/recovery/session/CSRF/proxy/TLS implementation and targeted Playwright auth flow. + +### Completion Notes List + +- Added PostgreSQL-authored v8 admin-auth lifecycle contract for bootstrap contracts, CSRF session state, login backoff and security audit. +- Added local operator commands `crank-migrate admin-auth bootstrap-create` and `crank-migrate admin-auth recover`. +- Removed production startup dependency on raw default admin password; `CRANK_BOOTSTRAP_ADMIN_PASSWORD` remains deprecated compatibility only. +- Implemented one-time bootstrap completion, login backoff, hashed session/CSRF lifecycle, password rotation session revocation and master-key-bound offline recovery. +- Added server-side CSRF middleware, hostile Origin rejection, browser security headers, trusted proxy IP allowlist and production non-loopback HTTPS enforcement. +- Updated UI login/bootstrap/session handling and RU/EN strings; Playwright auth flow now covers login, bootstrap mode and CSRF attachment. +- Updated runtime config schema/docs/examples for `CRANK_TRUSTED_PROXY_IPS` and production HTTPS base URL. +- Updated metrics registry route budget for bootstrap endpoints and regenerated metrics schema. +- Final state is ready for code review; no known mandatory Story 1.12 AC is intentionally left open. + +### File List + +- `apps/admin-api/src/app.rs` +- `apps/admin-api/src/auth.rs` +- `apps/admin-api/src/bin/crank-migrate.rs` +- `apps/admin-api/src/bin/crank_migrate/admin_auth_command.rs` +- `apps/admin-api/src/bin/crank_migrate/db_connect.rs` +- `apps/admin-api/src/dto.rs` +- `apps/admin-api/src/error.rs` +- `apps/admin-api/src/main.rs` +- `apps/admin-api/src/rate_limit.rs` +- `apps/admin-api/src/routes/auth.rs` +- `apps/admin-api/src/service/auth.rs` +- `apps/admin-api/src/service/workspaces.rs` +- `apps/admin-api/src/state.rs` +- `apps/admin-api/tests/integration/auth_rate_limit.rs` +- `apps/admin-api/tests/integration/common.rs` +- `apps/admin-api/tests/integration/community_access_usage.rs` +- `apps/admin-api/tests/migration_command.rs` +- `apps/ui/html/login.html` +- `apps/ui/js/api.js` +- `apps/ui/js/auth.js` +- `apps/ui/js/i18n.js` +- `apps/ui/js/login.js` +- `apps/ui/js/settings.js` +- `apps/ui/tests/e2e/login.spec.js` +- `crates/crank-community-auth/src/hashing.rs` +- `crates/crank-community-auth/src/lib.rs` +- `crates/crank-community-auth/src/session_cookie.rs` +- `crates/crank-config/src/process.rs` +- `crates/crank-config/src/process/list_parsers.rs` +- `crates/crank-config/src/render.rs` +- `crates/crank-config/src/schema.rs` +- `crates/crank-config/src/validation.rs` +- `crates/crank-config/tests/contract.rs` +- `crates/crank-config/tests/redaction.rs` +- `crates/crank-metrics/src/schema.rs` +- `crates/crank-metrics/tests/schema_v1.rs` +- `crates/crank-registry/src/error.rs` +- `crates/crank-registry/src/lib.rs` +- `crates/crank-registry/src/migrations.rs` +- `crates/crank-registry/src/migrations/admin_auth_lifecycle_v8.rs` +- `crates/crank-registry/src/migrations/admin_auth_lifecycle_v8.sql` +- `crates/crank-registry/src/migrations/authority.rs` +- `crates/crank-registry/src/migrations/authority_tests.rs` +- `crates/crank-registry/src/migrations/schema_guard.rs` +- `crates/crank-registry/src/migrations/schema_guard_v8.rs` +- `crates/crank-registry/src/model.rs` +- `crates/crank-registry/src/postgres/auth.rs` +- `crates/crank-registry/src/postgres/mod.rs` +- `crates/crank-registry/tests/integration/migrations.rs` +- `docs/admin-api.md` +- `docs/en/migrations.md` +- `docs/migrations.md` +- `docs/production-checklist.md` +- `docs/runtime-config.md` +- `docs/schemas/metrics-registry-v1.json` +- `docs/schemas/migration-sequence.json` +- `docs/schemas/runtime-config.schema.json` +- `docs/secrets-and-auth.md` +- `.env.example` +- `docker-compose.yml` +- `deploy/community/.env.example` +- `deploy/community/.env.images.example` +- `deploy/community/docker-compose.yml` +- `deploy/community/docker-compose.images.yml` +- `scripts/README.md` +- `scripts/check-runtime-config.py` +- `tests/unit/test_check_runtime_config.py` + +## Change Log + +- 2026-08-22: Created Story 1.12 from Epic 1 FR-3 with Admin bootstrap/login/session/recovery security context. +- 2026-08-22: Moved Story 1.12 to `in-progress`. +- 2026-08-22: Implemented Admin bootstrap/login/session/recovery lifecycle, trusted-proxy/TLS hardening and Playwright auth coverage; final `just verify` passed; status moved to `review`. diff --git a/_bmad-output/implementation-artifacts/1-13-immutable-agent-catalog.md b/_bmad-output/implementation-artifacts/1-13-immutable-agent-catalog.md new file mode 100644 index 0000000..f2269f1 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-13-immutable-agent-catalog.md @@ -0,0 +1,486 @@ +--- +story_id: "1.13" +story_key: "1-13-immutable-agent-catalog" +requirement: "FR-4" +status: "done" +baseline_commit: "767428436d3a54e60809a727044dfcec48e1f1dd" +created: "2026-08-22T12:12:34+03:00" +--- + +# Story 1.13: Публиковать immutable Agent catalog + +Status: done + +## Story + +As an администратор, +I want собирать и публиковать точный каталог разрешённых Tools для Agent, +so that MCP-клиент обнаруживает только утверждённые версии и получает стабильное поведение. + +## Operational Brief + +Story 1.13 закрывает FR-4 и переводит Agent catalog из mutable draft-like поведения в строгий published snapshot contract. + +После Story 1.7 Operation Published Version стала immutable. Сейчас следующий риск находится на уровне Agent: + +- Agent Draft можно менять без revision predicate; +- publish Agent обновляет `published_agents` как latest pointer и не создаёт полноценный immutable catalog snapshot; +- bindings/policy могут изменяться в текущей version row; +- MCP catalog/cache грузится по `{workspace_slug, agent_slug}`, без `catalog_revision` и полного auth scope; +- UI сохраняет create/update/bind/publish одной кнопкой без conflict token и без явной модели Draft vs Published. + +Цель Story 1.13 — сделать Agent catalog PostgreSQL-authoritative: + +- Draft изменения не влияют на текущий Published Agent; +- publish атомарно создаёт immutable Agent Version snapshot, exact bindings и monotonic `catalog_revision`; +- MCP discovery/call читает только committed published snapshot; +- stale search result или stale UI response не может вызвать capability вне актуального snapshot; +- unpublish/archive/key revocation закрывают новый доступ без удаления immutable versions/history/evidence; +- direct/search modes остаются текущими пользовательскими режимами, но получают revision-safe contract. + +Это foundation для Story 1.14 approvals, Story 1.15 history/usage и Story 1.16 onboarding. Не расширять story в approvals, Tasks, Resources, Prompts или новый MCP protocol surface. + +## Requirement / Architecture Trace + +- **Direct requirement:** FR-4. +- **Primary architecture:** AD-2 typed Operation/Agent aggregates and immutable snapshots; AD-19 UI/boundary error contract. +- **Supporting architecture:** AD-1, AD-4, AD-11, AD-13, AD-16, AD-20, AD-21, AD-22, AD-23. +- **Applicable NFR:** NFR-P3, NFR-P4, NFR-P5, NFR-R2, NFR-S1, NFR-S2, NFR-S4, NFR-S7, NFR-S8, NFR-O1, NFR-O4, NFR-O5, NFR-C1, NFR-C3, NFR-C4. +- **Primary risk/evidence:** E1-R-011 — Agent publication/cache exposes Draft, foreign, stale Tools or changes exact published versions. Required groups: E1-29, E1-30, E1-31. + +## Scope + +In scope: + +- Agent aggregate/version state model, revision predicate, immutable published snapshots and monotonic `catalog_revision`. +- Exact binding validation: only Published Operation Versions from the same workspace; no Draft, archived aggregate for new binding, foreign capability or disabled unknown Tool. +- Agent Draft editing for summary, instructions, bindings and direct/search policy without changing current Published Agent. +- Atomic publish transaction: Agent Version, binding snapshot, published pointer/catalog revision and audit/product event if present. +- MCP direct mode discovery/call from exact published snapshot with deterministic pagination and no Draft/foreign leakage. +- MCP search mode result token bound to Agent ID, Agent Version and `catalog_revision`; stale result rejects safely after new publication. +- Catalog cache keys including Agent ID/version/revision and full authorization scope; Valkey loss must fall back to PostgreSQL without correctness change. +- Unpublish/archive/key revocation effects on discovery/call/session/cache while preserving immutable versions, bindings, Invocation History and audit evidence. +- Admin API and UI conflict handling, loading/empty/error/confirmation/stale-response states in RU and EN. +- PostgreSQL, Admin API, MCP, Playwright, performance and inventory evidence for FR-4. + +Out of scope: + +- Approval state machine and side-effect honesty beyond preserving existing approval guards (Story 1.14). +- Invocation History/Usage UI redesign and CSV export (Story 1.15). +- New MCP Resources, Prompts, Tasks, Load Runs or background execution. +- OpenAPI importer behavior and Operation lifecycle semantics already owned by Story 1.7/Epic 2. +- New auth profile/key/master-key behavior beyond consuming revocation status from Stories 1.10–1.12. +- Prometheus/Grafana packaging, SLO dashboards or product analytics rollups. +- Multi-workspace UX, hosted identity providers or commercial access-control features. + +## Acceptance Criteria + +1. **Binding accepts only exact Published Operation Version** + - Given Agent Draft + - When администратор добавляет Tool binding + - Then binding принимает только точную Published Operation Version из того же workspace + - And Draft, archived Operation для нового binding или foreign-workspace capability отклоняется без metadata leakage. + +2. **Draft changes do not mutate Published Agent** + - Given изменяемый Agent Draft + - When администратор добавляет, удаляет или заменяет bindings и выбирает direct либо search mode + - Then изменения сохраняются только в Draft revision + - And текущий Published Agent catalog остаётся неизменным. + +3. **Atomic publish creates immutable catalog revision** + - Given валидный Agent Draft + - When администратор публикует Agent + - Then в одной PostgreSQL transaction создаются immutable Agent Version, exact binding snapshot и монотонно увеличенный `catalog_revision` + - And MCP начинает читать новый snapshot только после успешного commit. + +4. **Concurrent edit/publish conflicts are safe** + - Given concurrent edit или publish одного Agent Draft + - When revision predicate устарел + - Then операция возвращает conflict и не перезаписывает более новое состояние + - And UI предлагает reload/review вместо автоматического повторения mutation. + +5. **Operation evolution does not alter current Agent** + - Given Published Agent Version + - When связанная Operation получает новый Draft или новую Published Version + - Then текущий Agent продолжает ссылаться на прежнюю точную Published Version + - And обновление Tool требует нового Agent Draft, явной замены binding и повторной публикации. + +6. **Direct discovery is snapshot-scoped** + - Given Agent в direct mode + - When авторизованный MCP-клиент выполняет discovery + - Then он получает только Tools immutable snapshot этого Agent с deterministic pagination + - And Draft или Tool другого Agent отсутствует в результате. + +7. **Search results are revision-bound** + - Given Agent в search mode + - When MCP-клиент получает search result + - Then result связан с Agent Version и `catalog_revision` + - And после новой публикации устаревший result не может использоваться для вызова capability вне актуального snapshot. + +8. **Catalog cache cannot change correctness** + - Given catalog cache + - When публикуется новая Agent Version, Agent unpublish/archive или key revocation + - Then cache key включает Agent ID/version/revision и full authorization scope, а stale projection инвалидируется + - And потеря Valkey восстанавливает каталог из PostgreSQL без изменения correctness. + +9. **Unpublish/archive preserve immutable evidence** + - Given Published Agent + - When администратор выполняет unpublish или archive + - Then новые MCP discovery/call requests перестают получать доступ согласно lifecycle contract + - And immutable versions, bindings, Invocation History и audit evidence не удаляются и не переписываются. + +10. **MCP key scope is default-deny** + - Given MCP key для конкретного Agent + - When клиент обращается к endpoint другого Agent или revision + - Then access отклоняется default-deny без раскрытия catalog metadata + - And cache/session lookup сохраняет полный Agent/workspace/auth scope. + +11. **Agent lifecycle UI has explicit states** + - Given Agent lifecycle UI на RU и EN + - When выполняются edit, bind, publish, conflict resolution, unpublish или archive + - Then реализованы loading, empty, error, confirmation и stale-response states + - And UI явно показывает Draft versus Published Version и текущий `catalog_revision`. + +12. **Reference dataset discovery performance** + - Given catalog performance test на Reference Deployment dataset + - When выполняется Tool discovery + - Then latency соответствует NFR-P4 — ≤150 ms p95 + - And результат стабилен при 200 Agents и 2 000 Operations без draft leakage. + +13. **Automated catalog lifecycle suite** + - Given automated test suite + - When проверяется catalog lifecycle + - Then покрыты atomic publish, concurrent conflict, exact-version pinning, direct/search modes, stale results, cache loss и cross-Agent/workspace negatives + - And проходят registry, Admin API, MCP transport, Playwright и `just verify`. + +## Frozen Agent Catalog Decisions + +- `Agent` — aggregate identity/availability and current draft pointer. `AgentVersion` — immutable catalog snapshot. +- Published `AgentVersion` rows are append-only. Draft changes after publish create or update only the current Draft according to the revision contract; they never update a Published row. +- `catalog_revision` is monotonic per Agent and increments only when a new published catalog becomes visible or published availability changes. +- `published_agents` remains a current-pointer/readiness table if needed, but it is not the immutable audit source. Immutable Agent Version and exact binding snapshot are the evidence source. +- Existing route paths and JSON enum spellings remain stable. Adding required revision preconditions is an intentional Admin mutation contract revision for safety; missing precondition returns deterministic 428/409 rather than fail-open lost update. +- Direct mode returns bound snapshot tools. Search mode returns a bounded opaque token or equivalent machine field carrying Agent ID/version/revision/search fingerprint; stale token is rejected before execution. +- MCP response must not expose Draft, foreign, archived-for-new-binding or stale catalog metadata. Safe error includes request_id/trace_id already provided by prior stories. +- Cache is optimization only. PostgreSQL is correctness authority. Cache miss/loss/stale value must not alter visible authorization or catalog content. +- Agent key revocation invalidates subsequent discovery/call. Existing sessions must be revalidated or scoped so revoked credential cannot continue using stale catalog. +- Agent archive/unpublish stops new discovery/call but does not delete immutable Agent Versions, binding snapshots, Operation versions, Invocation History or audit evidence. +- Reference performance gate for NFR-P4 uses the PRD dataset shape: 200 Agents and 2 000 Operations. Local smaller runs are diagnostic only. + +## Stable Agent Catalog Error Contract + +| HTTP/MCP | Code | Safe recovery | +|---:|---|---| +| 428 / JSON-RPC error | `agent_precondition_required` | Reload Agent and retry with current revision token. | +| 409 / JSON-RPC error | `agent_stale_revision` | Preserve local edits; reload/review authoritative Draft. | +| 409 / JSON-RPC error | `agent_invalid_transition` | Reload Agent lifecycle state; do not retry unchanged command. | +| 409 / JSON-RPC error | `agent_archived` | Create or use another Agent; immutable history remains readable through Admin history flows. | +| 409 / JSON-RPC error | `agent_unpublished` | Publish a valid Draft before MCP discovery/call. | +| 422 / JSON-RPC error | `agent_binding_not_published` | Bind an exact Published Operation Version. | +| 422 / JSON-RPC error | `agent_binding_archived_operation` | Remove archived Operation from new binding. | +| 422 / JSON-RPC error | `agent_binding_scope_denied` | Select a capability from the current workspace. | +| 422 / JSON-RPC error | `agent_catalog_policy_invalid` | Correct direct/search policy and group references. | +| 409 / JSON-RPC error | `agent_catalog_result_stale` | Repeat search/discovery against current Agent revision. | +| 403/404 / JSON-RPC error | `agent_access_denied` | Use a valid active key for this Agent and workspace. | + +## Tasks / Subtasks + +- [x] Task 1 — Freeze Agent catalog oracle and current regression tests (AC: 1–13) + - [x] Characterize current Agent domain/table/query/API/UI/MCP behavior and add RED tests for mutable published Agent row, pointer rewind, binding Draft/foreign versions, stale cache/search and missing revision preconditions. + - [x] Freeze Agent state model, `catalog_revision` semantics, safe error codes, direct/search contracts and cache correctness rules in tests/docs. + - [x] Verify prerequisite contracts from Stories 1.1–1.12 are preserved: typed config only, MigrationAuthority-only DDL, request/trace IDs, typed metrics, Operation immutable versions, hardened runtime/outbound/auth/session. + +- [x] Task 2 — Add typed Agent lifecycle/revision model in core (AC: 1–5, 9, 11) + - [x] Add domain helpers for allowed Agent transitions, publishability, immutable version status and catalog revision changes. + - [x] Add validated strong revision token/ETag binding workspace, Agent ID, current draft version, latest published version, availability and catalog revision. + - [x] Add tests for legal/illegal transitions, stale token replay across Agent/workspace, monotonic catalog revision and published snapshot immutability. + +- [x] Task 3 — Add append-only Agent catalog migration if schema gaps remain (AC: 3, 8–9, 12–13) + - [x] Use MigrationAuthority only; leave previous migration source bytes/checksums untouched. + - [x] Add `catalog_revision` and immutable snapshot metadata where absent; add DB constraints/triggers preventing Published Agent Version/binding mutation and pointer rewind. + - [x] Preserve legacy rows honestly: mark migration-time observed snapshots if historical per-version provenance cannot be reconstructed. + - [x] Add fresh/current/replay/corrupt/rollback/version-aware schema guard tests. + +- [x] Task 4 — Make registry Agent mutations transactional and CAS-safe (AC: 1–5, 8–10, 13) + - [x] Replace check-then-write methods with scoped transaction and `SELECT ... FOR UPDATE` on Agent row. + - [x] Validate expected revision token under lock for update summary, save bindings/policy, publish, unpublish, archive and delete. + - [x] `save_agent_catalog_config` must not update a Published version row. Editing after publish creates/uses current Draft and leaves Published snapshot unchanged. + - [x] Publish only current Draft; reject old/future/archived/unpublishable versions; same-version retry is idempotent only if exact state already committed. + - [x] Delete only never-published/no-history Agent if product keeps hard delete; otherwise convert UI/API destructive path to archive. + - [x] Add 32-way race tests for save/publish/unpublish/archive/delete and assert no lost updates, pointer rewind, duplicate/gap revision or 5xx. + +- [x] Task 5 — Validate exact Operation bindings and search policy in service/API (AC: 1–2, 5–7, 10–13) + - [x] Binding validation resolves every Operation Version by workspace and exact version, requires `Published`, rejects archived aggregate for new binding and returns non-disclosing errors. + - [x] Direct API cannot bypass UI: direct save/publish with Draft, disabled unknown Tool, duplicated `tool_name`, foreign ID or stale `operation_version` fails pre-mutation. + - [x] Search policy validates groups/result limit against the exact enabled snapshot and rejects reserved control tool names. + - [x] Admin DTOs include revision token/current `catalog_revision`; boundary errors map typed registry/service errors once and include safe request_id/trace_id. + +- [x] Task 6 — Rework MCP catalog read/search/call to revision-bound snapshots (AC: 6–8, 10, 13) + - [x] `PublishedAgentCatalog` includes Agent ID, Agent Version and `catalog_revision`; direct `tools/list` returns deterministic pagination over that snapshot. + - [x] Search result/call path binds result to Agent Version/catalog revision and rejects stale result after a new publish. + - [x] Authorization and session lookup revalidate active key scope for workspace+Agent and cannot reuse stale catalog after key revocation. + - [x] All cache keys include workspace, Agent, Agent version, `catalog_revision`, access mode and authorization scope; Valkey/local cache loss reloads from PostgreSQL. + - [x] Add MCP tests for direct/search discovery, stale result, key revocation, cross-Agent endpoint, cache loss and no metadata leakage. + +- [x] Task 7 — Update Admin Agent UI for explicit lifecycle and stale guards (AC: 4, 11, 13) + - [x] Show Draft version, latest Published version and `catalog_revision`; distinguish unpublished Draft from published snapshot. + - [x] Add a wizard/drawer-wide lifecycle mutex and async generation guard for workspace/Agent/revision before applying responses. + - [x] Add confirmation for publish/unpublish/archive/delete; disable conflicting buttons while mutation is in flight. + - [x] On 409/428, preserve unsaved local edits, show reload/review action and never auto-retry mutation. + - [x] Add RU/EN strings together; use live regions/focus management, keyboard-accessible controls and safe DOM sinks. + +- [x] Task 8 — Performance, evidence, inventory and docs (AC: 12–13) + - [x] Add deterministic seed/helper for 200 Agents and 2 000 Operations and measure MCP discovery p95 ≤150 ms over declared warm-up/sample count. + - [x] Update `docs/admin-api.md`, `docs/mcp-interface.md`, `docs/data-model.md` and migration docs if schema changes. + - [x] Update `docs/capability-inventory.json` FR-4 entries only after accepted evidence; failed/flaky/skipped/not-run is not pass. + - [x] Keep metrics labels closed; request_id/trace_id must not be labels. Use typed metrics/exemplars only. + +- [x] Task 9 — Final verification and handoff (AC: 13) + - [x] Run targeted core/registry/Admin/MCP tests for Agent catalog lifecycle and security matrix. + - [x] Run UI build and targeted Playwright Agent lifecycle specs if UI changed. + - [x] Run migration/config/metrics/boundary/capability/community-scope gates and final `just verify`. + - [x] Update Dev Agent Record, File List, Change Log and status to `done` only after gates pass. + +### Review Findings + +- [x] [Review][Patch] MCP catalog cache can serve stale published tools after unpublish/archive/republish because cache scope is only workspace slug + Agent slug [crates/crank-community-mcp/src/catalog.rs:23] +- [x] [Review][Patch] Agent publish silently rewrites exact Operation bindings to latest published Operation version instead of publishing the saved exact binding snapshot [apps/admin-api/src/service/agents.rs:507] +- [x] [Review][Patch] Agent mutation preconditions are checked before registry mutation and are optional for never-published Drafts, so concurrent stale writes can pass and overwrite state [apps/admin-api/src/routes/agents.rs:169] +- [x] [Review][Patch] Agent ETag does not cover mutable summary/binding/policy content and UI auto-fetches fresh ETags before mutating stale drawer state [apps/ui/js/api.js:105] +- [x] [Review][Patch] v9 immutable trigger suppresses allowed Draft deletes by returning `NEW` on DELETE and does not guard binding INSERT into published snapshots [crates/crank-registry/src/migrations/agent_catalog_lifecycle_v9.sql:15] +- [x] [Review][Patch] `unpublish_agent` and `archive_agent` do not validate current lifecycle state and can change archived/never-published Agents incorrectly [crates/crank-registry/src/postgres/agent.rs:562] +- [x] [Review][Patch] Never-published Agent delete is a service-level check-then-delete and can race with publish [apps/admin-api/src/service/agents.rs:383] +- [x] [Review][Patch] Published MCP catalog query does not filter joined Operation Versions to `published`, so corrupted/legacy bindings can expose Draft versions [crates/crank-registry/src/postgres/agent.rs:638] +- [x] [Review][Patch] Disabled Agent bindings bypass exact Published Operation Version validation but remain persisted in the catalog draft [apps/admin-api/src/service/agents.rs:627] +- [x] [Review][Patch] Agent summary/slug updates mutate current published endpoint identity without new Agent publication or catalog revision [apps/admin-api/src/service/agents.rs:358] +- [x] [Review][Patch] Direct MCP `tools/list` returns the full catalog and lacks the deterministic pagination required by AC6 [crates/crank-community-mcp/src/app.rs:814] +- [x] [Review][Patch] Published catalog load is not anchored in one consistent snapshot, so pointer/revision and tools can come from different commits [crates/crank-registry/src/postgres/agent.rs:638] +- [x] [Review][Patch] `published_agents` monotonic guard covers UPDATE only; direct DELETE+INSERT can bypass pointer/version monotonicity [crates/crank-registry/src/migrations/agent_catalog_lifecycle_v9.sql:63] +- [x] [Review][Patch] v9 schema guard checks trigger names only, not trigger event set/function semantics [crates/crank-registry/src/migrations/schema_guard_v9.rs:77] +- [x] [Review][Patch] Agent lifecycle UI lacks required publish/unpublish/archive confirmations and complete stale/loading/error RU/EN Playwright coverage [apps/ui/js/agents.js:626] +- [x] [Review][Patch] MCP stale search-result error uses `catalog_revision_changed` instead of the story contract code `agent_catalog_result_stale` [crates/crank-community-mcp/src/tool_search.rs:82] +- [x] [Review][Patch] Required performance evidence for 200 Agents / 2,000 Operations discovery p95 ≤150 ms is absent from implementation artifacts. + +## Dev Notes + +### Current State / Repository Findings + +- `crates/crank-core/src/agent.rs` currently has `Agent`, `AgentVersion`, `AgentOperationBinding`, `ToolSelectionPolicy` and validation for direct/search policy. It does not model revision predicates, catalog revision, immutable publication snapshot rules or stale search-result identity. +- `apps/admin-api/src/service/agents.rs` currently: + - creates Agent version 1 as Draft; + - `ensure_editable_agent_version` clones current version only when `latest_published_version == current_draft_version`; + - `save_agent_catalog_config` updates `agent_versions.tool_selection_policy_json` and replaces bindings for the current version; + - `publish_agent` can rewrite bindings based on latest Operation version and then calls registry publish; + - `published_agent_bindings` silently skips missing/unpublished Operation bindings and upgrades to latest published Operation version instead of enforcing exact requested version. +- `crates/crank-registry/src/postgres/agent.rs` currently: + - calculates next Agent version before transaction and without row lock; + - saves bindings/policy without CAS or version-status protection; + - `publish_agent` upserts `published_agents` and marks version Published, allowing pointer rewrite semantics; + - `unpublish_agent`/`archive_agent` delete current published pointer and mutate current version status; + - `delete_agent` hard-deletes Agent rows. +- `crates/crank-community-mcp/src/catalog.rs` caches by `{workspace_slug, agent_slug}` only. Shared snapshot payload lacks Agent ID/version/revision/auth scope. +- MCP app reads `state.catalog.get_catalog(...)` for `tools/list` and `tools/call`. It already has request/trace context and typed execution failure paths from Stories 1.5/1.8; reuse them instead of adding ad-hoc errors. +- UI `apps/ui/js/agents.js` uses one drawer and `saveAgent()` chains create/update → save bindings → publish/archive/unpublish. It has `saving` guard but no revision token, no response-generation guard and no explicit Draft vs Published state. +- Existing Playwright `apps/ui/tests/e2e/agents.spec.js` covers demo cards and search UI smoke only. It does not prove immutable publication, stale conflict, unpublish/archive or real MCP behavior. + +### Implementation Constraints + +- Do not edit old migration bytes/checksums. Any durable schema change must be the next append-only MigrationAuthority version with schema guard and migration tests. +- Do not modify Operation lifecycle semantics except where Agent binding validation consumes exact Published Operation Versions. +- Do not introduce direct environment reads; new config, if any, goes through `crank-config`. +- Do not add dependencies/toolchain/MSRV changes unless the story explicitly records user approval. Prefer existing Rust crates and vanilla JS. +- Do not put user IDs, Agent IDs, Operation IDs, request_id, trace_id, URLs, tool names from user input or error text into Prometheus labels. +- PostgreSQL is correctness authority. Valkey/local cache is optional and rebuildable. +- Every workspace/Agent/capability access must include full scope; foreign object should not leak metadata. +- UI remains Alpine/vanilla JS with `window.Crank*` modules and existing build pipeline. +- New text must be RU and EN together. + +### File Structure Notes + +Likely UPDATE: + +- `crates/crank-core/src/agent.rs` +- `crates/crank-registry/src/{model.rs,error.rs,lib.rs}` +- `crates/crank-registry/src/postgres/agent.rs` +- `crates/crank-registry/src/migrations/{authority.rs,schema_guard.rs}` and machine migration sequence docs if schema changes +- `crates/crank-registry/tests/integration/{agents_usage.rs,workspace_access.rs,migrations.rs,common.rs}` +- `apps/admin-api/src/{dto.rs,error.rs}` +- `apps/admin-api/src/routes/agents.rs` +- `apps/admin-api/src/service/agents.rs` +- `apps/admin-api/tests/integration/{operations_agents.rs,community_access_usage.rs,common.rs}` and/or new `agent_catalog.rs` +- `crates/crank-community-mcp/src/{catalog.rs,app.rs,tool_search.rs,tool_resolution.rs,transport.rs}` as required +- `apps/mcp-server/tests/integration/{catalog_access.rs,tool_search.rs,transport_protocol.rs}` +- `apps/ui/js/{agents.js,api.js,i18n.js,ui-feedback.js}` and `apps/ui/html/agents.html` / CSS as needed +- `apps/ui/tests/e2e/agents.spec.js` or new `agent-catalog.spec.js` +- `docs/{admin-api.md,mcp-interface.md,data-model.md,capability-inventory.json}` + +Likely NEW: + +- Next migration SQL, only if required, e.g. `crates/crank-registry/src/migrations/agent_catalog_vN.sql` +- `apps/admin-api/tests/integration/agent_catalog.rs` +- `apps/ui/tests/e2e/agent-catalog.spec.js` + +Do not touch: + +- Previous migration source bytes/checksums. +- Operation YAML/import/export internals except evidence linkage. +- Approval execution state machine. +- Deployment topology unless a new config field is deliberately introduced. + +### Required Test Matrix + +P0 registry/PostgreSQL: + +- publish creates immutable Agent Version + exact binding snapshot + monotonic `catalog_revision`; +- save after publish leaves prior Published snapshot byte/semantic equivalent; +- publish old/future/archived/non-current Draft rejected or idempotent only under exact state; +- direct SQL cannot mutate/delete Published Agent Version/binding snapshot or rewind pointer; +- 32 concurrent save/publish/archive/unpublish attempts produce typed conflicts, no lost update/5xx; +- exact binding rejects Draft Operation, missing version, foreign workspace and archived aggregate for new binding. + +P0 Admin API: + +- all Agent mutations require current revision token; +- stale revision returns `agent_stale_revision`/precondition code with request_id/trace_id; +- direct API cannot bypass UI validation; +- unpublish/archive stop new MCP access while preserving versions/history; +- cross-workspace Agent/Operation/key requests are default-deny without metadata leakage. + +P0 MCP: + +- direct mode `tools/list` and `tools/call` see only published snapshot tools; +- Agent A key cannot discover/call Agent B tool; +- search mode result becomes stale after republish and cannot call removed/replaced tool; +- key revocation invalidates discovery/call/session-cache path; +- cache loss/stale local/shared snapshot falls back to PostgreSQL and preserves correctness; +- pagination/deterministic ordering stable across repeated calls. + +P1 UI: + +- RU/EN Agent drawer shows Draft/Published version and catalog revision; +- edit/bind/publish/unpublish/archive loading and confirmation states; +- stale 409/428 preserves edits and offers reload/review; +- workspace switch/stale response does not overwrite current drawer; +- keyboard/focus/live-region behavior is usable and external values use safe DOM sinks. + +Performance: + +- seed 200 Agents / 2 000 Operations; +- measure direct and search discovery p95 after warm-up with fixed sample count; +- pass threshold: ≤150 ms p95 on Reference Deployment. Non-reference local result is diagnostic only. + +### Suggested Verification Commands + +```bash +cargo test -p crank-core agent -- --test-threads=1 +cargo test -p crank-registry --test integration agents_usage -- --test-threads=1 +cargo test -p crank-registry --test integration workspace_access -- --test-threads=1 +cargo test -p crank-registry --test integration migrations -- --test-threads=1 +cargo test -p admin-api --test integration agent_catalog -- --test-threads=1 +cargo test -p admin-api --test integration operations_agents -- --test-threads=1 +cargo test -p mcp-server --test integration catalog_access -- --test-threads=1 +cargo test -p mcp-server --test integration tool_search -- --test-threads=1 +cd apps/ui && npm run build +cd apps/ui && npx playwright test tests/e2e/agent-catalog.spec.js --project=chromium +just migration-contract-check +just rust-boundaries +just capability-inventory-check +python3 scripts/check-community-scope.py --root . --files +just verify +``` + +If a command is impossible in the current container, record exact blocker and do not mark related task complete. + +### Previous Story Intelligence + +- Story 1.7 established the correct model for immutable Operation lifecycle: published exact snapshots are not mutable, archive changes aggregate availability only, and stale mutation protection is mandatory. Reuse the concept, but do not assume Agent already has the same protection. +- Story 1.8 established typed execution failure taxonomy. MCP catalog errors should project through existing typed paths and not add arbitrary ad-hoc machine codes. +- Story 1.9 established outbound correctness; Agent catalog must not bypass runtime/outbound admission. +- Stories 1.10–1.12 established credential/session revocation. Agent key revocation must be observed by MCP discovery/call and cache/session paths. + +### References + +- `_bmad-output/planning-artifacts/epics.md` — Epic 1 objective; Story 1.13 AC; FR-4. +- `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` — glossary, FR-4, NFR-P3/P4/P5, NFR-S1/S2/S4, release gates. +- `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` — AD-1, AD-2, AD-4, AD-11, AD-13, AD-16, AD-19, AD-20, AD-21, AD-22, AD-23. +- `_bmad-output/test-artifacts/test-design-progress.md` — E1-R-011, E1-29, E1-30, E1-31. +- `_bmad-output/project-context.md` — Rust/UI/testing/community/migration guardrails. +- `_bmad-output/implementation-artifacts/1-7-immutable-lifecycle-operation.md` — Operation immutable snapshot decisions and review lessons. +- `_bmad-output/implementation-artifacts/1-12-admin-bootstrap-login-session-lifecycle.md` — Admin auth/session/key revocation foundation for Agent UI/API access. + +## Dev Agent Record + +### Agent Model Used + +GPT-5 Codex + +### Debug Log References + +- 2026-08-22T12:12:34+03:00 — Created Story 1.13 from sprint backlog using BMAD create-story workflow and repo reconnaissance. +- 2026-08-22T12:12:34+03:00 — Started implementation under BMAD dev-story workflow. Baseline commit `767428436d3a54e60809a727044dfcec48e1f1dd`; worktree already contains prior story changes, preserve unrelated diffs. +- 2026-08-22T12:20+03:00 — RED confirmed: registry `published_agent_snapshot_remains_immutable_after_draft_edit` and `stale_agent_revision_rejects_mutation` failed because Published Agent Version could be edited in place. +- 2026-08-22T12:24+03:00 — RED confirmed: Admin `binding_requires_exact_published_operation_version` and `stale_agent_revision_rejects_mutation` failed with HTTP 200 for Draft binding/missing Agent precondition. +- 2026-08-22T12:31+03:00 — GREEN slice: registry rejects Published Agent Version mutation; Admin rejects Draft Operation binding and requires precondition after Agent publication; MCP catalog revision includes publish timestamp so stale search result after unpublish/republish is rejected. +- 2026-08-22T12:39+03:00 — Targeted checks passed: `cargo test -p crank-registry --test integration agents_usage:: -- --test-threads=1`, `cargo test -p admin-api --test integration agent_catalog:: -- --test-threads=1`, `cargo test -p admin-api --test integration operations_agents:: -- --test-threads=1`, `cargo test -p mcp-server --test integration catalog_access:: -- --test-threads=1`, `cargo test -p mcp-server --test integration tool_search:: -- --test-threads=1`, `cargo fmt --all --check`. +- 2026-08-22T12:57+03:00 — Added append-only migration v9 `agent-catalog-lifecycle-v9`: durable `catalog_revision`, DB triggers rejecting direct Published Agent Version/binding mutation and catalog pointer non-increase/rewind. +- 2026-08-22T13:03+03:00 — Targeted checks passed after v9: `just migration-contract-check` => `contract_current`; `cargo test -p crank-registry --test integration migrations:: -- --test-threads=1` => 23 passed; `cargo test -p crank-registry --test integration agents_usage:: -- --test-threads=1` => 7 passed; `cargo test -p admin-api --test integration agent_catalog:: -- --test-threads=1` => 2 passed; `cargo test -p admin-api --test integration operations_agents:: -- --test-threads=1` => 7 passed; `cargo test -p mcp-server --test integration catalog_access:: -- --test-threads=1` => 20 passed; `cargo test -p mcp-server --test integration tool_search:: -- --test-threads=1` => 2 passed. +- 2026-08-22T14:05+03:00 — Final implementation verification passed: `just verify` succeeded after updating v9 migration/version oracles and the closed metrics route registry for `/api/auth/session/csrf`; `git diff --check` passed. +- 2026-08-22T18:46+03:00 — Code review patch pass closed all 17 accepted findings: exact Agent publish bindings, mandatory If-Match/CAS, v9 trigger/schema-guard hardening, PostgreSQL-backed MCP catalog refresh, direct `tools/list` pagination, UI confirmations/stale behavior, and 200 Agent / 2,000 Operation performance evidence. Final `just verify` passed. + +### Completion Notes List + +- Implemented immutable Agent catalog foundation: Published Agent Versions and binding snapshots are immutable, Draft edits require revision preconditions, Agent publish creates durable monotonic `catalog_revision`, and stale Admin/UI/MCP search paths reject safely. +- Enforced binding correctness: Agent bindings accept exact Published Operation Versions only; Draft/foreign/archived invalid references are rejected without relying on UI-only validation. +- Added UI evidence for Agent catalog revision display, serialized lifecycle actions and localized stale conflict recovery; fixed Playwright proxy host handling used by the local UI harness. +- Updated docs and Capability Inventory evidence for FR-4 without marking broader Agent UX as fully qualified. +- Final verification is green: targeted registry/Admin/MCP/UI tests, migration and metrics contracts, full `just verify`, and `git diff --check`. +- Code review findings are resolved and checked off; Story 1.13 is moved from `review` to `done`. + +### File List + +- `_bmad-output/implementation-artifacts/1-13-immutable-agent-catalog.md` +- `_bmad-output/implementation-artifacts/sprint-status.yaml` +- `crates/crank-registry/src/error.rs` +- `crates/crank-registry/src/model.rs` +- `crates/crank-registry/src/migrations.rs` +- `crates/crank-registry/src/migrations/agent_catalog_lifecycle_v9.rs` +- `crates/crank-registry/src/migrations/agent_catalog_lifecycle_v9.sql` +- `crates/crank-registry/src/migrations/authority.rs` +- `crates/crank-registry/src/migrations/authority_tests.rs` +- `crates/crank-registry/src/migrations/schema_guard.rs` +- `crates/crank-registry/src/migrations/schema_guard_v9.rs` +- `crates/crank-registry/src/postgres/agent.rs` +- `crates/crank-registry/src/postgres/agent_catalog.rs` +- `crates/crank-registry/tests/integration/agents_usage.rs` +- `crates/crank-registry/tests/integration/common.rs` +- `crates/crank-registry/tests/integration/migrations.rs` +- `docs/schemas/migration-sequence.json` +- `docs/schemas/metrics-registry-v1.json` +- `apps/admin-api/src/error.rs` +- `apps/admin-api/src/routes/agents.rs` +- `apps/admin-api/src/service/agents.rs` +- `apps/admin-api/src/service/demo.rs` +- `apps/admin-api/tests/integration.rs` +- `apps/admin-api/tests/integration/agent_catalog.rs` +- `apps/admin-api/tests/integration/operations_agents.rs` +- `apps/admin-api/tests/migration_command.rs` +- `crates/crank-community-mcp/src/tool_search.rs` +- `crates/crank-community-mcp/src/app/request.rs` +- `crates/crank-community-mcp/src/app/response.rs` +- `apps/mcp-server/tests/integration/catalog_access.rs` +- `apps/mcp-server/tests/integration/tool_search.rs` +- `apps/ui/js/agents.js` +- `apps/ui/scripts/playwright-ui-server.js` +- `apps/ui/tests/e2e/agents.spec.js` +- `docs/admin-api.md` +- `docs/data-model.md` +- `docs/mcp-interface.md` +- `docs/capability-inventory.json` +- `docs/capability-baseline/manifest.json` +- `crates/crank-metrics/src/schema.rs` +- `crates/crank-metrics/tests/schema_v1.rs` + +## Change Log + +- 2026-08-22 — Created Story 1.13 from Epic 1 FR-4 with Agent catalog immutability, MCP snapshot/cache, UI lifecycle and performance context. +- 2026-08-22 — Closed post-review patch pass and moved Story 1.13 to `done` after final `just verify`. diff --git a/_bmad-output/implementation-artifacts/1-14-approvals-side-effects.md b/_bmad-output/implementation-artifacts/1-14-approvals-side-effects.md new file mode 100644 index 0000000..43508d1 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-14-approvals-side-effects.md @@ -0,0 +1,250 @@ +--- +story_id: "1.14" +story_key: "1-14-approvals-side-effects" +requirement: "FR-5" +status: "done" +baseline_commit: "767428436d3a54e60809a727044dfcec48e1f1dd" +created: "2026-08-22T17:04:50+03:00" +--- + +# Story 1.14: Сделать approvals атомарными и side effects честными + +Status: done + +## Story + +As an администратор, +I want требовать точное и одноразовое подтверждение опасных Operations, +so that concurrent requests и retries не обходят approval и не создают неконтролируемые side effects. + +## Operational Brief + +Story 1.14 закрывает FR-5. Это safety-слой поверх уже hardened цепочки: + +- 1.7: Published Operation Version immutable; +- 1.8: Execution failures имеют closed typed taxonomy и честную uncertainty; +- 1.9: outbound REST защищён и не делает unsafe retry без idempotency; +- 1.10–1.12: machine/approval/Admin credentials имеют lifecycle и boundary separation; +- 1.13: Agent catalog immutable и MCP discovery/call привязан к published snapshot. + +Теперь главный риск — human approval как обходной или racing механизм. Approval должен быть PostgreSQL-authoritative, full-scope, deduplicated, single-use и честно связан с side-effect outcome. Valkey/in-memory confirmation token может оставаться вспомогательной оптимизацией только для safe UX, но не должен быть authority для required approval. + +Цель: + +- вычислять canonical approval fingerprint до outbound dispatch; +- создавать ровно один active pending approval на full scope; +- проверять approval key, workspace, Agent, Operation Version, fingerprint, expiry и status при approve/deny; +- допускать ровно один terminal/consumption transition через conditional PostgreSQL update; +- не выполнять второй side effect при replay approved request/token; +- fail closed при недоступном mandatory approval/idempotency authority; +- честно маркировать uncertain post-dispatch outcome как `outcome_unknown/manual_reconcile`, без exactly-once promises. + +## Acceptance Criteria + +1. **Full-scope approval identity.** Given Published Operation Version с policy `approval_required`, when Agent запрашивает execution, then до outbound dispatch вычисляется canonical input fingerprint и approval scope из workspace, Agent, Operation/version и input, and изменение любого элемента scope требует отдельного approval. +2. **Concurrent pending deduplication.** Given несколько concurrent execution requests с одинаковым approval scope, when active approval отсутствует, then в PostgreSQL создаётся один canonical pending approval record, and остальные requests получают ссылку на тот же record без конкурирующих approvals. +3. **Pending replay returns status.** Given active pending approval, when тот же request повторяется, then возвращается существующий status и безопасная metadata, and новый approval cycle не создаётся без явного terminal outcome и нового разрешённого request. +4. **Approval credential and scope checks.** Given approval key, when выполняется approve или deny, then проверяются workspace, Agent, Operation/version, fingerprint, key scope, key status и expiry, and foreign, revoked, malformed или wrong-purpose key отклоняется без metadata leakage. +5. **Single-winner transitions.** Given approve, deny, expiry или recovery происходят конкурентно, when выполняется state transition, then PostgreSQL conditional update допускает ровно один разрешённый переход из текущего state, and проигравший caller получает deterministic prior/conflict outcome без перезаписи terminal decision. +6. **Single-use execution admission.** Given approved execution, when runtime собирается выполнить outbound dispatch, then approval потребляется single-use атомарно с execution admission либо durable dispatch intent, and replay approval token не разрешает второй side effect. +7. **Stale approval revalidation.** Given approval был выдан ранее, when перед dispatch изменились Agent publication, Operation version, credential status, deadline или authorization context, then execution fail closed и не использует stale approval, and audit record объясняет безопасную причину отказа без раскрытия secret. +8. **Mandatory store fail-closed.** Given mandatory approval/idempotency store недоступен, when Operation требует approval, then execution отклоняется до outbound dispatch и dependency отражается в readiness, and Valkey или in-memory fallback не заменяет PostgreSQL authority. +9. **Idempotency conflict.** Given idempotency key для write Operation, when повторяется execution с тем же scoped key и тем же input fingerprint, then возвращается ранее сохранённый outcome либо состояние существующей попытки, and тот же key с иным fingerprint возвращает conflict. +10. **Side-effect honesty.** Given write Operation без подтверждённого upstream idempotency contract, when после dispatch результат становится uncertain, then Crank не обещает exactly-once и не выполняет автоматический retry, and outcome явно классифицируется как потенциально совершивший side effect с сохранённым attempt/audit trail. +11. **Approval UI RU/EN.** Given approval UI на RU и EN, when администратор просматривает, подтверждает или отклоняет request, then UI показывает точные Agent, Operation Version, безопасный input summary, expiry, Request ID и Trace ID, and approve/deny имеют confirmation, loading, conflict, expired и stale-response states. +12. **Security/race suite.** Given approval security suite, when выполняются integration и race tests, then покрыты concurrent creation/decision, token replay, fingerprint mismatch, cross-Agent/workspace access, key revocation, expiry, store outage и uncertain side effect, and проходят registry/runtime/Admin/MCP/Playwright tests и `just verify`. + +## Tasks / Subtasks + +- [x] Task 1 — Freeze approval oracle and RED tests (AC: 1–12) + - [x] Characterize current approval/confirmation flow in core/runtime/registry/MCP/Admin/UI and document what remains backward-compatible. + - [x] Add RED tests for full-scope fingerprint, concurrent pending deduplication, single-winner decisions, replay, fingerprint mismatch and stale approval. + - [x] Add RED tests for store outage, revoked approval key, foreign scope, unsafe uncertainty and safe metadata/redaction. + +- [x] Task 2 — Domain approval identity and safe metadata (AC: 1, 3–4, 7, 11) + - [x] Add typed approval scope/fingerprint in `crank-core`, using deterministic canonical JSON with confirmation/approval control fields removed. + - [x] Bound summary fields and never store raw request payload as UI/API metadata; store safe summary plus fingerprint. + - [x] Keep request_id/trace_id on approval responses/errors and never expose raw secret, approval key, auth header, full request body or foreign metadata. + +- [x] Task 3 — PostgreSQL authority and conditional transitions (AC: 2, 3, 5, 6, 8, 12) + - [x] Add append-only migration if current schema cannot express full scope, single-use admission, execution lease/attempt and closed transition constraints. + - [x] Create/reuse pending approvals with one transactional upsert/lock keyed by workspace, Agent, Operation/version and fingerprint. + - [x] Implement approve/deny/expiry/claim/finish/recovery via conditional updates with deterministic prior/conflict outcomes. + - [x] Add real-PG concurrency tests; no in-memory/Valkey authority for required approval. + +- [x] Task 4 — Runtime/MCP admission and side-effect honesty (AC: 6–10, 12) + - [x] MCP tool call must create/reuse pending approval before runtime dispatch and return existing safe status on replay. + - [x] Approved execution must claim/consume approval atomically before outbound dispatch or durable dispatch intent. + - [x] Revalidate Agent publication/catalog revision, Operation version, credential status, authorization context, deadline and idempotency fingerprint before dispatch. + - [x] Preserve `outcome_unknown/manual_reconcile` for uncertain post-dispatch writes and prevent automatic unsafe retry. + +- [x] Task 5 — Approval HTTP/API boundaries and audit (AC: 4–8, 11–12) + - [x] Approval endpoints accept only active approval keys with correct kind/scope/origin/status/expiry. + - [x] Approve/deny responses are deterministic for pending, terminal, expired and conflict states. + - [x] Audit/invocation records contain bounded safe approval metadata, request_id, trace_id and outcome without payload/secret leakage. + +- [x] Task 6 — Admin/UI approval experience (AC: 3, 5, 11) + - [x] UI lists pending/terminal approvals with safe summary, exact Agent/Operation Version, expiry, request_id and trace_id. + - [x] Approve/deny require confirmation and expose loading/conflict/expired/stale-response states. + - [x] RU/EN strings are added together; async responses are guarded by workspace/approval identity. + - [x] Add Playwright coverage for approval pending view, approve/deny, conflict/expired and stale-response behavior. + +- [x] Task 7 — Docs, inventory, gates and handoff (AC: 12) + - [x] Update `docs/admin-api.md`, `docs/mcp-interface.md`, `docs/data-model.md`, manual regression checklist and capability inventory for FR-5 only after evidence passes. + - [x] Run targeted registry/runtime/MCP/Admin/UI tests, migration/config/metrics/boundary/capability gates and final `just verify`. + - [x] Update Dev Agent Record, File List, Change Log and status to `done` only after review patches and all gates pass. + +### Review Findings + +- [x] [Review][Patch] Admin approval UI scope contradicted AC11 — resolved by implementing Admin approve/deny routes and UI confirmation/loading/stale guards with request_id/trace_id visibility. +- [x] [Review][Patch] Approved execution used redacted/truncated approval summary as runtime input — resolved by preserving raw request payload for execution while projecting only safe summaries externally. +- [x] [Review][Patch] v10 migration dropped the v9 `ON CONFLICT` arbiter — resolved by preserving the v9 arbiter and adding the v10 scoped index/columns append-only. +- [x] [Review][Patch] Approve/deny transition did not predicate on operation_id, operation_version, or request_fingerprint — resolved with full-scope decision predicates. +- [x] [Review][Patch] Terminal approval response payload was stored and returned without bounded redaction — resolved by sanitizing terminal response previews before storage/projection. +- [x] [Review][Patch] Safe approval summary redacted sensitive key names but not secret-looking string values under neutral keys — resolved by extending safe preview redaction to secret-looking string values. +- [x] [Review][Patch] Approval fingerprint recursively stripped reserved `_crank_*` field names from nested business payloads — resolved by limiting control-field stripping to the top-level request envelope. +- [x] [Review][Patch] Pending-expiry update was not workspace-scoped — resolved by adding workspace scope to expiry updates. +- [x] [Review][Patch] Approval records and UI evidence did not carry request_id and trace_id — resolved by persisting/projecting both identifiers and showing them in the Admin UI. +- [x] [Review][Patch] AC12/GATES evidence overclaimed the security matrix — resolved by adding scoped regression tests and updating gate evidence to actual command outputs. + +## Dev Notes + +### Current State / Repository Findings + +- `crates/crank-core/src/approval.rs` has `ApprovalRequestStatus` and `ApprovalRequest`, but the record stores `request_payload` and lacks a typed full-scope fingerprint/value object. +- `crates/crank-runtime/src/confirmation.rs` currently gates dangerous Operations through confirmation tokens stored in `CoordinationStateStore`. This is not sufficient for FR-5 because Valkey/in-memory cannot be approval authority; required approvals must be PostgreSQL-authoritative. +- `crates/crank-registry` already has `approval_requests` schema and methods for create/list/get/decide/expire/claim/finish/recovery, with partial baseline fields: `execution_started_at`, `execution_attempts`, `request_fingerprint`, pending fingerprint index. +- `crates/crank-community-mcp/src/app.rs` and `approval_execution.rs` own MCP approval creation, approval HTTP endpoints and recovery. Approved execution already uses `RuntimeRequestContext::with_approval_granted()`, but 1.14 must ensure this cannot be replayed or stale after Agent/Operation/key changes. +- `crates/crank-community-mcp/src/approval_response.rs` currently may include `approval.request_payload` when policy `show_payload_preview` is true. Story 1.14 requires safe bounded summary instead of raw payload exposure. +- Story 1.10 already enforced approval-key kind/scope/origin/revocation and duplicate Authorization rejection; preserve those boundaries and extend them to exact scope/fingerprint checks. +- Story 1.8/1.9 already introduced typed runtime outcomes, dispatch uncertainty and idempotency safeguards. Reuse those contracts; do not create ad-hoc approval error taxonomy. +- Existing MCP approval tests live under `apps/mcp-server/tests/integration/catalog_access/approval_access.rs` and submodules `pending.rs`, `revocation.rs`. Extend them rather than duplicating setup. +- UI currently has Logs/Usage approval panels but must be verified for exact pending summary, approve/deny confirmations, stale/expired conflict states and RU/EN text. + +### Architecture and Safety Constraints + +- PostgreSQL is the correctness authority for approvals. Valkey/cache loss must not allow approval bypass or duplicate side effect. +- Approval identity is unique on workspace, Agent, published Agent/catalog revision as needed, Operation ID/version and canonical input fingerprint. +- Every state change uses one transaction and conditional predicates. No check-then-write without row lock for approval state. +- `Pending → Approved|Denied|Expired`; approved execution claim moves into an execution/admission state exactly once; completion/failure/recovery is terminal or explicitly `outcome_unknown`. +- Foreign workspace/Agent/Operation/key failures must not reveal object metadata. +- `request_id` and `trace_id` are support identifiers, never metric labels. +- Do not claim exactly-once external side effects. Without verified upstream idempotency, post-dispatch uncertainty is `outcome_unknown` and requires manual reconciliation. +- No dependency/toolchain/MSRV change. No runtime DDL outside MigrationAuthority. Previous migration bytes/checksums remain immutable. + +### Likely File Map + +Likely UPDATE: + +- `crates/crank-core/src/approval.rs` +- `crates/crank-core/src/operation.rs` +- `crates/crank-runtime/src/confirmation.rs` +- `crates/crank-runtime/src/executor.rs` +- `crates/crank-runtime/src/idempotency.rs` +- `crates/crank-runtime/src/request_context.rs` +- `crates/crank-registry/src/{model.rs,error.rs,lib.rs}` +- `crates/crank-registry/src/postgres/{approval.rs,mod.rs}` +- `crates/crank-registry/src/migrations/{authority.rs,schema_guard.rs}` +- `crates/crank-registry/tests/integration/{workspace_access.rs,common.rs}` +- `crates/crank-runtime/tests/integration/{confirmation.rs,idempotency.rs}` +- `crates/crank-community-mcp/src/{app.rs,approval_execution.rs,approval_response.rs,access.rs,tool_error.rs}` +- `apps/mcp-server/tests/integration/catalog_access/approval_access.rs` +- `apps/mcp-server/tests/integration/catalog_access/approval_access/{pending.rs,revocation.rs}` +- `apps/admin-api/src/service/observability.rs` +- `apps/ui/js/{logs-usage.js,i18n.js,api.js}` +- `apps/ui/tests/e2e/logs-usage.spec.js` or new `approvals.spec.js` +- `docs/{admin-api.md,mcp-interface.md,data-model.md,manual-regression-checklist.md,capability-inventory.json}` + +Likely NEW: + +- `crates/crank-core/src/approval_identity.rs` if keeping identity logic separate. +- `crates/crank-registry/src/migrations/approval_side_effects_v10.sql` if schema gaps require v10. +- `crates/crank-registry/tests/integration/approval.rs` +- `crates/crank-runtime/tests/integration/approval.rs` +- `apps/ui/tests/e2e/approvals.spec.js` + +### Required Test Matrix + +- Same workspace/Agent/Operation/version/input ⇒ one pending approval under 32 concurrent callers. +- Any difference in workspace, Agent, Operation, version, fingerprint or key scope ⇒ different approval or safe denial. +- Repeat pending call ⇒ existing status and safe metadata, no new cycle. +- Approve vs deny vs expire vs recovery race ⇒ one legal transition, losers deterministic. +- Approved replay ⇒ no second outbound call. +- Approval key revoked/expired/wrong-kind/wrong-agent/wrong-origin ⇒ denied before mutation. +- Agent unpublish/archive/catalog revision change, Operation version unavailable, credential status change or deadline expiry after approval ⇒ fail closed before dispatch. +- Mandatory PostgreSQL approval store unavailable ⇒ no outbound dispatch. +- Idempotency same key+same fingerprint ⇒ previous outcome/attempt; same key+different fingerprint ⇒ conflict. +- Mutating post-dispatch timeout/transport uncertainty ⇒ `outcome_unknown/manual_reconcile`, no automatic retry. +- UI RU/EN: pending summary, approve, deny, expired, conflict, stale response, request_id, trace_id. + +## Dev Agent Record + +### Agent Model Used + +GPT-5 Codex + +### Debug Log References + +- 2026-08-22T17:04:50+03:00 — Created Story 1.14 from Epic 1 FR-5 because sprint-status had `1-14-approvals-side-effects: backlog` and no dedicated story file existed. Baseline commit `767428436d3a54e60809a727044dfcec48e1f1dd`. +- 2026-08-22T17:14:00+03:00 — RED registry approval race test reproduced the defect: 32 concurrent equal-scope calls could create 32 pending approvals because volatile confirmation/approval control fields were included in the fingerprint. +- 2026-08-22T17:31:00+03:00 — Implemented safe request summary storage and canonical fingerprint stripping for approval/confirmation control fields. +- 2026-08-22T17:43:00+03:00 — Added v10 approval-side-effects migration and schema guard; pending approval uniqueness is now scoped by workspace, Agent, Operation version and canonical fingerprint. +- 2026-08-22T17:52:00+03:00 — Targeted registry, MCP approval, runtime confirmation/idempotency, UI build/Playwright, migration contract and capability inventory checks passed. +- 2026-08-22T18:02:00+03:00 — Final `just verify` passed after updating the append-only migration authority test to include v10. +- 2026-08-23T00:15:13+03:00 — Code-review patches completed: Admin approve/deny API/UI, raw execution payload preservation, v9 arbiter preservation, request_id/trace_id persistence, redaction/fingerprint fixes and metrics route registry update. Final `just verify` and Playwright approval spec passed. + +### Completion Notes List + +- Implemented canonical approval deduplication on the existing PostgreSQL authority path: volatile approval/confirmation control fields no longer create distinct approval fingerprints. +- Pending approval projections now expose only bounded safe summaries, while the PostgreSQL authority path preserves raw request payload for approved execution admission. +- Added append-only v10 migration and schema guard for the approval-side-effects contract; previous migration bytes remain untouched. +- MCP approval endpoints continue to enforce approval-key approval boundaries. Admin API/UI now exposes operator approve/deny actions for existing approval records with confirmation/loading/stale guards; execution admission and side-effect dispatch remain in the canonical MCP/runtime path. +- Updated FR-5 docs, data model, MCP/Admin API references, manual regression checklist, capability inventory and baseline manifest evidence. +- Final repository gate passed: `just verify` exit code 0 on 2026-08-23T00:15:13+03:00; approval Playwright spec passed after fixing the test assertion. + +### File List + +- `_bmad-output/implementation-artifacts/1-14-approvals-side-effects.md` +- `_bmad-output/implementation-artifacts/sprint-status.yaml` +- `apps/admin-api/src/app.rs` +- `apps/admin-api/src/dto.rs` +- `apps/admin-api/src/routes/observability.rs` +- `apps/admin-api/src/service/observability.rs` +- `apps/admin-api/tests/migration_command.rs` +- `apps/mcp-server/tests/integration/catalog_access/approval_access/pending.rs` +- `apps/ui/js/api.js` +- `apps/ui/js/i18n.js` +- `apps/ui/js/logs.js` +- `apps/ui/tests/e2e/approvals.spec.js` +- `crates/crank-community-mcp/src/app.rs` +- `crates/crank-community-mcp/src/approval_response.rs` +- `crates/crank-core/src/approval.rs` +- `crates/crank-core/src/observability.rs` +- `crates/crank-metrics/src/schema.rs` +- `crates/crank-metrics/tests/schema_v1.rs` +- `crates/crank-registry/src/migrations.rs` +- `crates/crank-registry/src/migrations/approval_side_effects_v10.rs` +- `crates/crank-registry/src/migrations/approval_side_effects_v10.sql` +- `crates/crank-registry/src/migrations/authority.rs` +- `crates/crank-registry/src/migrations/authority_tests.rs` +- `crates/crank-registry/src/migrations/schema_guard.rs` +- `crates/crank-registry/src/migrations/schema_guard_v10.rs` +- `crates/crank-registry/src/postgres/approval.rs` +- `crates/crank-registry/tests/integration.rs` +- `crates/crank-registry/tests/integration/approval.rs` +- `crates/crank-registry/tests/integration/migrations.rs` +- `docs/admin-api.md` +- `docs/capability-baseline/manifest.json` +- `docs/capability-inventory.json` +- `docs/data-model.md` +- `docs/manual-regression-checklist.md` +- `docs/mcp-interface.md` +- `docs/migrations.md` +- `docs/schemas/metrics-registry-v1.json` +- `docs/schemas/migration-sequence.json` + +## Change Log + +- 2026-08-22 — Created Story 1.14 from Epic 1 FR-5 with approval atomicity, side-effect honesty, UI and race-test context. +- 2026-08-22 — Implemented Story 1.14 approval fingerprint/safe-summary/v10 migration hardening and moved story to review after targeted checks and `just verify` passed. +- 2026-08-23 — Applied code-review patches, added Admin approve/deny UI/API, corrected approval payload/redaction/fingerprint/migration evidence gaps, reran final gates and moved story to done. diff --git a/_bmad-output/implementation-artifacts/1-15-invocation-history-usage.md b/_bmad-output/implementation-artifacts/1-15-invocation-history-usage.md new file mode 100644 index 0000000..58d9336 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-15-invocation-history-usage.md @@ -0,0 +1,298 @@ +--- +story_id: "1.15" +story_key: "1-15-invocation-history-usage" +requirement: "FR-6" +status: "done" +baseline_commit: "767428436d3a54e60809a727044dfcec48e1f1dd" +created: "2026-08-23T01:47:15+03:00" +--- + +# Story 1.15: Предоставить безопасные Invocation History и Usage + +Status: done + +## Story + +As an оператор Crank, +I want видеть фильтруемую историю и показатели выполнения, +so that могу диагностировать ошибки и оценивать качество работы Agents и Operations без доступа к чувствительным данным. + +## Operational Brief + +Story 1.15 закрывает FR-6 и завершает hardened core перед onboarding Story 1.16. + +Предыдущие stories уже дали основу: + +- 1.5 сохраняет Request ID и Trace ID независимо от telemetry sampling; +- 1.7 и 1.13 гарантируют immutable Operation/Agent published references; +- 1.8 и 1.9 ввели typed execution taxonomy и honest side-effect uncertainty; +- 1.14 гарантирует atomic approvals и не заменяет product result при history-loss. + +Теперь нужно сделать Invocation History и Usage полноценным операторским инструментом: + +- history record должен быть typed, scoped и безопасно редактированным; +- Logs API/UI должны фильтровать по bounded period, Agent, Operation и outcome; +- details должны показывать stage, safe previews, duration, Agent, Operation Version, Request ID и Trace ID; +- Usage должен считать counts, outcomes и latency percentiles без смешивания upstream/client/schema failures с Crank-caused failures; +- CSV export обязан наследовать filters/auth/redaction/bounds и защищать spreadsheet consumers; +- retention должен быть typed/observable и не повреждать audit/evidence; +- production-size query path не должен грузить 1 000 000 records в память приложения или браузера. + +## Requirement / Architecture Trace + +- **Direct requirement:** FR-6. +- **Primary architecture:** AD-11 correlation identity; AD-13 typed metrics/local product analytics; AD-24 retention. +- **Supporting architecture:** AD-1, AD-2, AD-4, AD-12, AD-16, AD-19, AD-20. +- **Applicable NFR:** NFR-P3, NFR-P5, NFR-R2, NFR-S1, NFR-S2, NFR-S4, NFR-S6, NFR-S8, NFR-O1, NFR-O4, NFR-O5, NFR-C1, NFR-C4. + +## Scope + +In scope: + +- Invocation History record contract and persistence validation. +- Safe preview redaction/limits/truncation evidence. +- Logs list/detail Admin API filters, pagination and scoped access. +- Usage aggregation by workspace, Agent and Operation with outcome groups and percentiles. +- UTC half-open period boundary semantics. +- CSV export for filtered history/usage dataset with redaction and formula-injection protection. +- Retention cleanup policy and observable outcome. +- Logs/Usage UI loading, empty, error, retry, export and stale-response guards in RU/EN. +- Registry/Admin/UI/Playwright tests, docs, capability inventory and baseline evidence for FR-6. + +Out of scope: + +- GlitchTip trace deep links/search UI beyond showing/copying local Request ID/Trace ID. +- Product analytics DAU/adoption rollups (Epic 5 / FR-35). +- Prometheus/Grafana packaged dashboards (Epic 5). +- Background Tasks history (Epic 4), Load Runs (Epic 6), Resources/Prompts usage (Epic 3). +- Changing Operation/Agent/approval semantics from Stories 1.7/1.13/1.14. + +## Acceptance Criteria + +1. **Typed history record.** Given завершённая или отклонённая Execution attempt, when формируется Invocation History record, then сохраняются workspace, Agent, Operation/version, execution ID, outcome taxonomy, timestamps, duration, Request ID и Trace ID, and запись не содержит raw credential, arbitrary headers/body или unbounded error text. +2. **Safe previews.** Given execution input и output, when создаются previews, then централизованная redaction применяет byte/field/depth limits, сохраняет валидный UTF-8/JSON and oversized content получает явный truncation marker. +3. **History-loss honesty.** Given failure записи Invocation History после фактического outcome, when persistence недоступен или record отклонён, then product result не заменяется ложным execution failure, and typed `crank-metrics` увеличивает low-cardinality history-loss counter. +4. **Logs filters and pagination.** Given авторизованный Admin UI caller, when он открывает Logs, then history фильтруется по bounded period, Agent, Operation и outcome с deterministic opaque pagination, and foreign-scope query не раскрывает counts, names или records. +5. **Log details.** Given конкретная Invocation History record, when администратор открывает details, then UI показывает stage, safe previews, duration, Agent, точную Operation Version, Request ID и Trace ID, and raw internal cause остаётся server-side. +6. **Usage aggregation.** Given Usage query за период, when данные агрегируются, then UI получает counts, success/failure outcomes и latency percentiles по Agent и Operation, and upstream/client/schema outcomes отображаются отдельно от Crank-caused failures. +7. **UTC period boundaries.** Given period boundary, when агрегируются records на границе дня или timezone UI, then storage/query contract использует UTC instants and one record cannot be counted twice by inclusive overlap. +8. **CSV export.** Given CSV export, when администратор экспортирует отфильтрованный dataset, then export applies same authorization, filters, redaction and bounded row/size policy as UI, and spreadsheet formula injection values are escaped safely. +9. **Retention.** Given configured Invocation History retention, when record reaches retention boundary, then archive/delete uses typed observable policy/outcome, and deletion does not damage Published Version audit, aggregate Usage or immutable release evidence. +10. **Production-size query plan.** Given 1 000 000 history records, when Logs/Usage screens query data, then query path is bounded and does not load full dataset into app/browser memory; local evidence records plan/row-count/proxy timing. +11. **Logs/Usage UI RU/EN.** Given Logs/Usage UI на RU и EN, when данные загружаются, отсутствуют, фильтруются, экспортируются или завершаются ошибкой, then loading/empty/error/retry/stale-response states exist, and workspace/request generation guard prevents stale response overwrite. +12. **Verification.** Given automated verification, when history and usage suites run, then redaction, bounded previews, persistence loss, period boundaries, percentiles, CSV injection, retention, cross-scope access and production-size query plans are covered, and registry/Admin API/Playwright tests plus `just verify` pass. + +## Tasks / Subtasks + +- [x] Task 1 — Freeze history/usage oracle and RED tests (AC: 1–12) + - [x] Characterize current `invocation_logs`, Admin Logs/Usage API and UI behavior. + - [x] Add RED tests for filters, pagination, details, period boundaries, CSV injection, retention and production-size plan. + - [x] Add RED tests for redaction, bounded previews, cross-scope denial and history-loss product-result preservation. + +- [x] Task 2 — Invocation History persistence contract (AC: 1–3, 5, 9) + - [x] Validate all new history records include operation version, execution taxonomy, request_id and trace_id. + - [x] Ensure safe previews are produced by one central sanitizer and stored bounded. + - [x] Add retention API/policy with typed outcome and metrics; do not delete Published Version audit/evidence. + +- [x] Task 3 — Logs list/detail API (AC: 4–5, 7–8, 12) + - [x] Add bounded query DTO fields for period start/end, Agent, Operation, outcome and opaque cursor. + - [x] Implement deterministic pagination without leaking foreign counts or names. + - [x] Add safe details projection including stage, previews, duration, Agent, Operation Version, Request ID and Trace ID. + - [x] Add CSV export endpoint using same filters/auth/redaction/bounds and formula escaping. + +- [x] Task 4 — Usage aggregation API (AC: 6–7, 10, 12) + - [x] Implement UTC half-open window semantics and prevent boundary double-counting. + - [x] Aggregate counts, success/failure outcomes and p50/p95/p99 by Agent and Operation. + - [x] Separate upstream/client/schema outcomes from Crank-caused failures. + - [x] Add production-size query-plan/index evidence and bounded memory proof. + +- [x] Task 5 — Logs/Usage UI and Playwright (AC: 4–8, 11–12) + - [x] Add Agent/Operation/outcome filters, pagination, retry/export states and Request ID/Trace ID details. + - [x] Add stale-response guards for workspace/filter/request generation. + - [x] Add RU/EN strings together and avoid raw HTML sinks. + - [x] Extend Playwright `logs-usage.spec.js` for filters, details, CSV export, empty/error and stale-response behavior. + +- [x] Task 6 — Docs, inventory, gates and handoff (AC: 12) + - [x] Update docs/admin-api.md, docs/data-model.md, docs/manual-regression-checklist.md and capability inventory for FR-6 only after evidence passes. + - [x] Update baseline manifest/results without raw browser reports, secrets, payloads or host paths. + - [x] Run registry/Admin/UI targeted suites, capability gates, SQLx checks and final `just verify`. + - [x] Update Dev Agent Record, File List, Change Log and story/sprint status to `review` only after gates pass. + +### Review Findings + +- [x] [Review][Patch][High] Safe preview sanitizer does not enforce field/depth limits [crates/crank-core/src/observability.rs:12] +- [x] [Review][Patch][High] Logs detail UI omits exact Operation Version [apps/ui/js/logs.js:126] +- [x] [Review][Patch][High] Usage CSV export remains client-side snapshot instead of server-authoritative bounded export [apps/ui/js/usage.js:556] +- [x] [Review][Patch][High] Retention remains raw timestamp delete without typed observable policy/outcome and preserved aggregate usage semantics [crates/crank-registry/src/postgres/observability.rs:19] +- [x] [Review][Patch][Medium] Usage stale-response guard mutates state before validating workspace/request generation [apps/ui/js/usage.js:527] +- [x] [Review][Patch][Medium] Logs filter changes do not invalidate in-flight responses immediately [apps/ui/js/logs.js:727] +- [x] [Review][Patch][Medium] Logs CSV export inherits page limit 100 instead of export dataset bound [apps/ui/js/logs.js:443] +- [x] [Review][Patch][Medium] Logs outcome filter supports only ok/error status, not execution outcome groups [apps/admin-api/src/dto.rs:307] +- [x] [Review][Patch][Medium] Usage outcome grouping defaults uncovered typed failures to `crank` [crates/crank-registry/src/postgres/observability.rs:633] +- [x] [Review][Patch][Medium] Admin Logs/Usage API lacks explicit start/end UTC window filters claimed by the story [apps/admin-api/src/dto.rs:307] + +## Dev Notes + +### Current State / Repository Findings + +- `InvocationLog` already contains workspace, optional Agent, Operation, optional operation version, source, level, status, request_id, trace_id, status_code, duration, execution stage/error/retryability/certainty and request/response previews. +- Registry `create_invocation_log` already validates request_id, trace_id, operation_version and execution taxonomy for new records and sanitizes previews before insert. +- Current `list_invocation_logs` supports workspace, level, source, operation_id, agent_id, created_after, search and limit, but does not provide cursor pagination, explicit start/end period, outcome filter or CSV export. +- Current `get_invocation_log` scopes by workspace and ID, but details projection must explicitly stay redacted and expose trace_id in UI. +- Current usage aggregation supports workspace/source/created_after and p50/p95/p99, but lacks explicit Agent/Operation endpoint evidence, outcome group separation and half-open start/end boundary contract. +- Current UI Logs supports level/search/period/live mode, but does not include Agent/Operation/outcome filters, opaque pagination, CSV export, trace_id in details or robust logs stale-response guard. +- Current UI Usage renders summary/timeline/operation breakdown and client-side CSV snapshot, but export is not server-authoritative and does not prove same filters/auth/redaction/bounds as UI. +- Existing history-loss contract exists in Admin/MCP DC08 tests and `crank-metrics` history-loss metric; Story 1.15 must keep product result unchanged and add visible evidence, not invent a new failure path. +- Existing retention method `delete_invocation_logs_before(cutoff)` is raw and timestamp-only; Story 1.15 must wrap it in typed policy/outcome and prove it does not damage immutable Operation/Agent evidence. + +### Architecture and Safety Constraints + +- PostgreSQL remains source of truth. Admin API/MCP startup must remain read-only; schema changes, if needed, go through MigrationAuthority append-only version. +- History records are diagnostic evidence, not user payload storage. Do not store raw credentials, arbitrary headers/body or unbounded error text. +- Request ID and Trace ID are support identifiers and must never become metric labels. +- Logs/Usage filters must include workspace scope in every query and must not disclose foreign object existence through counts, names or different error shapes. +- Pagination cursor must be opaque, deterministic and bounded; no offset pagination over production-size dataset if it requires scanning skipped rows at scale. +- CSV export is an exfiltration surface: same auth/filter/redaction as UI, bounded rows/bytes, formula injection escaping, no raw host paths/secrets. +- Usage/telemetry must not leave the installation; CSV remains local Admin response only. +- UI updates must use `textContent`/DOM APIs and discard stale responses when workspace/filter/request generation changes. +- No dependency/toolchain/MSRV changes; no broad frontend framework migration. + +### Likely File Map + +Likely UPDATE: + +- `crates/crank-core/src/observability.rs` +- `crates/crank-registry/src/model.rs` +- `crates/crank-registry/src/postgres/observability.rs` +- `crates/crank-registry/src/postgres/mod.rs` +- `crates/crank-registry/tests/integration/observability.rs` +- `crates/crank-registry/tests/integration/common.rs` +- `apps/admin-api/src/dto.rs` +- `apps/admin-api/src/app.rs` +- `apps/admin-api/src/routes/observability.rs` +- `apps/admin-api/src/service/observability.rs` +- `apps/admin-api/src/service.rs` +- `apps/admin-api/tests/integration/community_access_usage.rs` +- `apps/admin-api/tests/dc08.rs` +- `apps/mcp-server/tests/dc08.rs` +- `apps/ui/js/api.js` +- `apps/ui/js/logs.js` +- `apps/ui/js/usage.js` +- `apps/ui/js/i18n.js` +- `apps/ui/html/logs.html` +- `apps/ui/html/usage.html` +- `apps/ui/tests/e2e/logs-usage.spec.js` +- `docs/admin-api.md` +- `docs/data-model.md` +- `docs/manual-regression-checklist.md` +- `docs/capability-inventory.json` +- `docs/capability-baseline/results.json` +- `docs/capability-baseline/manifest.json` + +Likely NEW: + +- `crates/crank-registry/tests/integration/observability_scale.rs` only if keeping ignored production-size evidence separate. +- Admin API CSV/export tests if existing `community_access_usage.rs` would exceed maintainability limits. + +### Required Test Matrix + +- New history record rejects missing/invalid request_id, trace_id, operation_version and unknown taxonomy. +- Secret canaries in request/response/error material are absent from stored previews, API details, UI DOM and CSV. +- Oversized nested previews preserve valid UTF-8/JSON and include explicit truncation markers. +- History-loss after product success/error keeps product response and emits low-cardinality metric. +- Logs filters: period, Agent, Operation, outcome, source/search and cursor; foreign objects return empty/safe error without counts. +- Details show stage, duration, Agent, Operation Version, Request ID and Trace ID; raw internal cause absent. +- Usage: counts, success/failure, p50/p95/p99 by Agent/Operation; upstream/client/schema groups separate from Crank-caused failures. +- Period boundary: records exactly at start included, exactly at end excluded; adjacent windows do not double-count. +- CSV: same filters as list, bounded rows/bytes, redaction, formula escaping for `=`, `+`, `-`, `@`, tab and CR/LF-leading values. +- Retention: deletes only eligible records, reports typed outcome, preserves published versions, Agent snapshots and release evidence. +- Scale: 1 000 000-row seed/plan evidence or ignored heavy test with deterministic local proxy budget. +- UI: loading, empty, error, retry, filters, details, export, stale workspace/filter response, RU/EN. + +### Verification Commands + +```bash +cargo test -p crank-core observability -- --test-threads=1 +cargo test -p crank-registry --test integration observability -- --test-threads=1 +cargo test -p crank-registry --test integration observability -- --test-threads=1 --ignored +cargo test -p admin-api --test dc08 -- --test-threads=1 +cargo test -p mcp-server --test dc08 -- --test-threads=1 +cargo test -p admin-api --test integration community_access_usage -- --test-threads=1 +cargo test -p crank-observability --test incidents -- --test-threads=1 +just ui-build +cd apps/ui && npx playwright test tests/e2e/logs-usage.spec.js --project=chromium +just capability-inventory-check +just sqlx-check +python3 scripts/check-community-scope.py --root . --files +git diff --check +just verify +``` + +## Dev Agent Record + +### Agent Model Used + +GPT-5 Codex + +### Debug Log References + +- 2026-08-23T01:47:15+03:00 — Created Story 1.15 from Epic 1 FR-6 after Story 1.14 moved to done. +- 2026-08-23T02:50:00+03:00 — Implemented Logs/Usage API, UI, CSV export, outcome aggregation, cursor pagination, 1M-row bounded plan evidence, docs/inventory updates and final gates. +- 2026-08-23T10:51:37+03:00 — Applied all code-review patch findings: bounded preview depth/field/array sanitization, operation version in log detail, server-authoritative Usage CSV export, typed retention outcome, immediate stale-response invalidation, execution outcome groups and explicit UTC windows. Re-ran targeted suites, Playwright Logs/Usage, capability/scope gates and full `just verify`. + +### Completion Notes List + +- Implemented bounded Invocation History list/detail API with status, Agent, Operation, period/search filters and opaque cursor pagination. +- Added server-side CSV export using the same filter path with row/size bounds and spreadsheet formula escaping. +- Added Usage outcome breakdown groups plus half-open UTC period aggregation for workspace/Agent/Operation usage queries. +- Added Logs UI status/Agent/Operation filters, load-more pagination, CSV export, Request ID/Trace ID details and stale-response guards; Usage UI renders outcome groups and safer CSV cells. +- Added registry/admin/UI tests including real test-run evidence, retention/boundary assertions and an ignored heavy 1,000,000-row query-plan test that passed locally. +- Updated FR-6 docs, manual checklist, capability inventory and baseline manifest checksum. +- Closed 10/10 code-review patch findings and moved Story 1.15 from `review` to `done` after `just verify` passed. + +### File List + +- `_bmad-output/implementation-artifacts/1-15-invocation-history-usage.md` +- `_bmad-output/implementation-artifacts/sprint-status.yaml` +- `apps/admin-api/src/app.rs` +- `apps/admin-api/src/dto.rs` +- `apps/admin-api/src/main.rs` +- `apps/admin-api/src/routes/observability.rs` +- `apps/admin-api/src/service.rs` +- `apps/admin-api/src/service/agents.rs` +- `apps/admin-api/src/service/demo.rs` +- `apps/admin-api/src/service/observability.rs` +- `apps/admin-api/tests/integration.rs` +- `apps/admin-api/tests/integration/community_access_usage.rs` +- `apps/admin-api/tests/integration/logs_usage.rs` +- `apps/ui/css/logs.css` +- `apps/ui/html/logs.html` +- `apps/ui/html/usage.html` +- `apps/ui/js/api.js` +- `apps/ui/js/i18n.js` +- `apps/ui/js/logs.js` +- `apps/ui/js/usage.js` +- `apps/ui/tests/e2e/logs-usage.spec.js` +- `crates/crank-core/src/observability.rs` +- `crates/crank-metrics/src/schema.rs` +- `crates/crank-metrics/tests/schema_v1.rs` +- `crates/crank-registry/src/lib.rs` +- `crates/crank-registry/src/model.rs` +- `crates/crank-registry/src/postgres/mod.rs` +- `crates/crank-registry/src/postgres/observability.rs` +- `crates/crank-registry/tests/integration/agents_usage.rs` +- `crates/crank-registry/tests/integration/common.rs` +- `crates/crank-registry/tests/integration/observability.rs` +- `docs/admin-api.md` +- `docs/capability-baseline/manifest.json` +- `docs/capability-inventory.json` +- `docs/data-model.md` +- `docs/manual-regression-checklist.md` +- `docs/observability.md` +- `docs/schemas/metrics-registry-v1.json` + +## Change Log + +- 2026-08-23 — Created Story 1.15 with FR-6 history/usage implementation context. +- 2026-08-23 — Implemented FR-6 Invocation History/Usage hardening and moved Story 1.15 to review. +- 2026-08-23 — Closed code-review patch findings, re-ran full verification and moved Story 1.15 to done. diff --git a/_bmad-output/implementation-artifacts/1-16-mcp-tool-call.md b/_bmad-output/implementation-artifacts/1-16-mcp-tool-call.md new file mode 100644 index 0000000..653f79f --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-16-mcp-tool-call.md @@ -0,0 +1,360 @@ +--- +story_id: "1.16" +story_key: "1-16-mcp-tool-call" +requirements: ["FR-1", "FR-4", "FR-33"] +status: "done" +baseline_commit: "767428436d3a54e60809a727044dfcec48e1f1dd" +created: "2026-08-23T11:20:00+03:00" +--- + +# Story 1.16: Провести нового администратора к первому MCP Tool call + +Status: done + +## Story + +As a новый self-hosted администратор, +I want пройти понятный возобновляемый путь от первого входа до вызова Tool, +so that получаю первую ценность без разработки и поиска последовательности по документации. + +## Operational Brief + +Story 1.16 завершает Epic 1 и собирает реализованный hardened core в один честный activation journey: + +`Operation → test → publish → Agent → MCP key → connection → public tools/call`. + +Onboarding не создаёт вторую упрощённую модель. Он показывает серверную проекцию состояния уже существующих Operations, Published Versions, Agent catalog, key lifecycle и Invocation History, а действия выполняются существующими полными flows. Успех засчитывается только после реального authenticated MCP вызова через public endpoint. + +Главный недостающий контракт: текущая Invocation History знает Agent/Operation/version, но не exact MCP key. Story должна протянуть безопасный typed key identity из machine credential verification в успешный invocation record и ProductEvent; raw secret при этом раскрывается только ответом create-key и никогда не попадает в persistent onboarding state. + +## Requirement / Architecture Trace + +- **Direct requirements:** FR-1, FR-4, FR-33; SM-11, SM-12, SM-13. +- **Primary architecture:** AD-1 immutable publication, AD-2 Agent snapshot, AD-11 correlation, AD-13 local ProductEvents, AD-19 UI/error contract, AD-22 identity/security. +- **Supporting architecture:** AD-4 bounded resources, AD-9 authorization scope, AD-15 startup/readiness, AD-16 migration authority, AD-20 release evidence, AD-21 unified execution. +- **Applicable NFR:** NFR-P3, NFR-P5, NFR-R1, NFR-S1, NFR-S2, NFR-S4, NFR-S6, NFR-S8, NFR-O1, NFR-O4, NFR-O5, NFR-C4. + +## Scope + +In scope: + +- optional collapsible/dismissible Getting Started checklist on protected Admin UI; +- one bounded workspace-scoped onboarding snapshot computed from authoritative server facts; +- deep links into existing manual REST Operation, test/publish, Agent and key flows; +- exact Operation/Agent revision guards and honest regression after archive/revoke/change; +- one-time MCP key connection guidance for representative clients without persistent raw secret; +- exact Agent/key-scoped first successful public MCP `tools/call` evidence; +- typed immutable idempotent local ProductEvents for eligible/start/complete/abandon milestones; +- RU/EN, loading/empty/error/retry/stale states, keyboard/focus/ARIA/reduced-motion behavior; +- registry/Admin API/MCP/Playwright tests, docs, capability inventory and manual usability protocol. + +Out of scope: + +- OpenAPI-guided onboarding (Story 2.9); +- Resources, Prompts and Tasks onboarding (Epics 3–4); +- ecosystem telemetry or any default external product analytics; +- redesigning Operation, Agent, key or MCP domain models; +- storing/restoring a lost raw MCP key; +- claiming a measured ≤15-minute usability result without the manual participant run; this story creates the executable protocol and product instrumentation, while release evidence records the real run. + +## Acceptance Criteria + +1. **Optional authoritative checklist.** Given first bootstrap/login in a workspace, when protected Admin UI opens, then a Getting Started checklist shows `Operation → test → publish → Agent → key → MCP connection → first call`; collapse/resume/dismiss never blocks normal navigation, while completion state comes only from server facts. +2. **Honest state regression.** Given a completed step, when its Operation/Agent is archived or changed, binding becomes stale, or key is revoked/deleted, then snapshot returns that step to an actionable state without trusting a browser completion flag. +3. **Existing Operation flow.** Given the Operation step, when manual REST is chosen, then onboarding deep-links into the existing full wizard with a safe minimal example/hints; it creates no hidden Draft, bypass or alternate validation/publish path. +4. **Exact publication/binding.** Given a successful test and Published Operation, when Agent is created/published, then exact Tool Version and catalog revision are visible; stale Operation/Agent revision requires explicit refresh/reselection, never silent binding. +5. **One-time key and connection.** Given a Published Agent, when its first MCP key is created, then raw key appears once with copy-safe endpoint/config for supported representative clients; it is absent from local/session storage, URLs, telemetry, ProductEvents, logs and repeat reads, with a clipboard responsibility warning. +6. **Lost/revoked key recovery.** Given a lost or revoked key, when connection step resumes, then no raw value is reconstructed; old configuration is explicitly invalid and the UI offers deliberate create/rotate recovery without automatic duplicate key creation. +7. **Real first-call evidence.** Given authenticated MCP discovery and `tools/call`, when call succeeds through the public endpoint, then completion requires exact workspace/Agent/key scope and shows Tool, timestamp, Request ID, Trace ID and safe links to Invocation History/trace without payload. +8. **Actionable failures.** Given validation, upstream, auth, compatibility or connection failure, when progress stops, then the failed step shows bounded localized message, stable error code, Request ID/Trace ID where available and recovery action; retry resumes after the last authoritative step without duplicate publication/key creation. +9. **Resume and accessibility.** Given refresh, reconnect, workspace/language change, parallel tab, URL/back navigation or reduced-motion preference, when onboarding restores, then identity/revision/request-generation guards reject stale completion and keyboard/focus/screen-reader status follows the shared UI contract. +10. **Local ProductEvents.** Given onboarding eligibility/start/complete/abandon, when a milestone is recorded, then an immutable versioned idempotent bounded local ProductEvent records an explicit eligible denominator for SM-11–SM-13; raw user/object identifiers, key material, payload and usage never leave the installation without opt-in. +11. **Real-stack verification.** Given the fresh manual REST path, when Playwright and MCP integration suites run, then success uses the public MCP endpoint without test bypass and covers refresh/resume, stale revision, lost key, failure recovery, RU/EN and accessibility; manual protocol measures first UI render to authoritative first call, counts non-completers, and targets median ≤15 minutes. +12. **Repository quality.** Given implementation complete, when targeted suites, UI build/Playwright, SQLx/capability/scope gates and `just verify` run, then all pass and story/sprint status move to review only after evidence exists. + +## Tasks / Subtasks + +- [x] Task 1 — Freeze onboarding oracle and RED evidence (AC: 1–12) + - [x] Characterize existing Operation/test/publish, Agent/version, key and public MCP flows; preserve their contracts. + - [x] Add RED registry/Admin/MCP tests for authoritative projection, exact key-scoped success, state regression, idempotent events and cross-workspace denial. + - [x] Add RED Playwright flow for success, resume, stale revision, lost key, recovery, RU/EN and accessibility without mocked completion. + +- [x] Task 2 — Typed ProductEvent and exact invocation credential evidence (AC: 2, 7, 10) + - [x] Add closed core ProductEvent/onboarding milestone types with schema version, occurred-at, eligible cohort timestamp and bounded idempotency key. + - [x] Add append-only V11 migration, schema guard/checksum/owned relations and indexed immutable ProductEvent persistence with unique workspace idempotency. + - [x] Propagate optional typed PlatformApiKeyId from verified Community credential into Invocation History and successful MCP event; external verifier paths may remain unscoped and cannot complete exact-key onboarding. + - [x] Prove secret canaries are absent from DB events/history, logs, metrics and boundary responses. + +- [x] Task 3 — Server-authoritative onboarding projection (AC: 1–4, 6–10) + - [x] Implement one bounded workspace snapshot over published Operation/test evidence, Published Agent exact binding/catalog revision, active MCP key metadata and exact scoped successful tools/call. + - [x] Make deleted/archived/revoked/stale facts regress steps; never accept client-provided completion state. + - [x] Record eligible/start/complete/abandon milestones idempotently with explicit local denominator and UTC timing. + - [x] Avoid N+1/history materialization; add query/index evidence and cross-workspace non-disclosure tests. + +- [x] Task 4 — Admin API and safe connection contract (AC: 1, 4–10) + - [x] Add authenticated workspace-scoped onboarding GET projection and bounded UX-event mutation; mutation cannot mark domain steps complete. + - [x] Return stable step/status/recovery/error/support-ID DTOs and server-built canonical MCP endpoint; enforce revision/identity guards. + - [x] Extend create-key response with ephemeral representative-client configuration derived from canonical endpoint and raw secret, while all later reads remain metadata-only. + - [x] Add route metrics registry entry, HTTP integration tests, CSRF/authz/cross-workspace negatives and no-secret response/log evidence. + +- [x] Task 5 — Getting Started UI over existing flows (AC: 1, 3–6, 8–9) + - [x] Add protected shared onboarding component/bundle integration and render it without blocking existing pages/navigation. + - [x] Deep-link to existing manual REST wizard, test/publish, Agents, keys and Logs; carry only non-secret selection/revision hints in URL. + - [x] Show one-time key/config only in the create response view, never persist/reconstruct it; make ambiguous create failure non-auto-retry and explain rotation. + - [x] Implement loading/error/retry/collapse/dismiss/resume, workspace/session/language/visibility refresh and generation guards. + +- [x] Task 6 — Accessibility, localization and real-stack E2E (AC: 7–11) + - [x] Add all RU/EN strings together, safe DOM rendering, bounded failure copy and support IDs. + - [x] Add keyboard order, focus restoration, `aria-live` status, semantic progress and reduced-motion CSS. + - [x] Run real public MCP initialize → tools/list → tools/call with a one-time key and assert exact Agent/key/Operation version plus Request ID/Trace ID/history link. + - [x] Cover refresh/parallel tabs, workspace/language change, stale response/revision, revoked/lost key and validation/upstream/auth/compatibility recovery. + +- [x] Task 7 — Docs, usability protocol, gates and handoff (AC: 10–12) + - [x] Update Admin API/data model/MCP/manual regression docs, capability inventory and baseline evidence only after tests pass. + - [x] Document a five-participant fresh-install usability protocol: no docs/code assistance, timer from first authenticated render to authoritative success, median ≤15m, non-completers/censoring and eligible denominator recorded separately. + - [x] Run targeted Rust suites, UI build/Playwright, migration/SQLx/capability/community-scope checks, secret scan and final `just verify`. + - [x] Update Dev Agent Record, File List, Change Log and story/sprint status to review only after all gates pass. + +### Review Findings + +- [x] [Review][Patch] [High] Persist exact completed lineage and add explicit server-side Reset/Reselect; never silently replace it with another Operation/Agent/key path — decision: exact lineage with deliberate administrator recovery [crates/crank-registry/src/postgres/onboarding.rs:81] +- [x] [Review][Patch] [High] Default onboarding MCP key lacks `write`, so generated credentials cannot execute `tools/call` [apps/ui/js/api-keys.js:684] +- [x] [Review][Patch] [High] Representative desktop-client configs contain a relative MCP URL instead of the validated absolute public URL [apps/admin-api/src/service.rs:1069] +- [x] [Review][Patch] [High] Approval credentials are incorrectly embedded into MCP/LLM client configs [apps/admin-api/src/service/api_keys.rs:167] +- [x] [Review][Patch] [High] Fallible workspace/Agent reads after key persistence can lose the only raw secret and invite duplicate creation [apps/admin-api/src/service/api_keys.rs:167] +- [x] [Review][Patch] [High] Ambiguous key-create failures immediately re-enable Create without mandatory metadata reconciliation [apps/ui/js/api-keys.js:725] +- [x] [Review][Patch] [High] Raw key/config is wiped before asynchronous clipboard write is known to have succeeded [apps/ui/js/api-keys.js:287] +- [x] [Review][Patch] [High] Client-controlled idempotency keys can occupy the reserved server completion namespace; duplicate conflicts do not verify semantic equality [crates/crank-registry/src/postgres/product_event.rs:34] +- [x] [Review][Patch] [High] `expected_revision` check and ProductEvent append are separate transactions rather than an atomic CAS [crates/crank-registry/src/postgres/onboarding.rs:335] +- [x] [Review][Patch] [High] Completion ProductEvent is emitted only on a later Admin GET and timestamps UI revisit instead of the first MCP call [apps/admin-api/src/service/onboarding.rs:28] +- [x] [Review][Patch] [High] Normal UI never emits `onboarding_started` or `onboarding_abandoned`, leaving funnel metrics incomplete [apps/ui/js/onboarding.js:279] +- [x] [Review][Patch] [Medium] Completion view omits required Tool and timestamp and does not require the full support-identifier presentation [apps/ui/js/onboarding.js:162] +- [x] [Review][Patch] [Medium] First eligible protected render keeps the checklist closed instead of showing it once until collapse/dismiss [apps/ui/js/onboarding.js:306] +- [x] [Review][Patch] [Medium] Stale Operation/Agent revision deep links fail silently without explicit refresh/reselection recovery [apps/ui/js/api-keys.js:246] +- [x] [Review][Patch] [Medium] Real-stack Playwright provisions the journey through direct API calls and mocks recovery, so the actual checklist/wizard/Agent/key UX remains unproved [apps/ui/tests/e2e/onboarding.spec.js:397] +- [x] [Review][Patch] [Medium] Natural key expiry changes progress without changing the opaque projection revision [crates/crank-registry/src/postgres/onboarding.rs:197] +- [x] [Review][Patch] [Medium] Idempotent replay lookup scans only the latest 1000 ProductEvents instead of the unique key [apps/admin-api/src/service/onboarding.rs:69] +- [x] [Review][Patch] [Medium] Invocation History retention deletes the only exact onboarding evidence and reopens completed onboarding after the retention horizon [crates/crank-registry/src/postgres/observability.rs:70] +- [x] [Review][Patch] [Medium] V11 schema guard checks names/presence but not all ProductEvent constraints, index definitions and function contract [crates/crank-registry/src/migrations/schema_guard_v11.rs:25] +- [x] [Review][Patch] [Medium] A completed GET recomputes the correlated projection three times and performs duplicate write transactions; browser refresh signals are not coalesced [apps/admin-api/src/service/onboarding.rs:24] +- [x] [Review][Patch] [Low] Workspace `ON DELETE CASCADE` conflicts with the unconditional ProductEvent append-only delete trigger [crates/crank-registry/src/migrations/onboarding_product_events_v11.sql:20] + +## Dev Notes + +### Current State / Reuse Map + +- Operations: reuse `PostgresRegistry::{list_operations,get_operation_summary,get_operation_version}` and `AdminService::{list_operations,get_operation}`; existing routes own create/test/publish semantics. +- Agents: reuse `list_agents/get_agent_summary/get_agent_version`; `AgentSummary` already exposes published version and `catalog_revision`; route ETag/CAS guards remain mandatory. +- Keys: reuse `create_agent_platform_api_key`, list/revoke/delete. `CreatedPlatformApiKeyResponse` is the only raw-secret boundary; list records contain metadata/status/last-used only. +- MCP endpoint: reuse `AdminService::agent_mcp_endpoint` and canonical `/mcp/v1/{workspace_slug}/{agent_slug}` contract from `docs/mcp-interface.md`; do not assemble it from browser localStorage. +- First call: Invocation History already stores workspace, Agent, Operation/version, Tool, outcome, request_id/trace_id/time, but lacks key ID. `VerifiedMachineCredential` currently drops key identity; extend this narrow path rather than creating synthetic success. +- ProductEvents: architecture requires a typed core event and idempotent registry fold, but no implementation/table exists yet. Story 1.16 introduces the minimal reusable foundation; Epic 5 may extend event kinds/rollups later. +- UI is multi-page vanilla JS/Alpine with shared `protected-core`. Prefer an IIFE `window.CrankOnboarding` loaded by protected-core and a reusable DOM host injected by build/templates; avoid duplicate page-specific state machines. + +### Architecture and Security Guardrails + +- PostgreSQL is source of truth. V11 must be append-only, checksummed, applied only by migration authority and covered by fresh/N-1 schema guards. +- Domain completion is derived server-side. Client event endpoint may record presentation milestones only; it cannot submit `step=complete` as truth. +- ProductEvents are immutable, versioned and idempotent. Event names/versions are closed enums; payload/cardinality/length are bounded. IDs never become metric labels. +- Every query/mutation includes workspace scope. Foreign IDs use indistinguishable empty/not-found behavior. +- Raw key is forbidden in storage, ProductEvents, local/session storage, URL, telemetry, snapshots, diagnostics, clipboard readback and repeat API reads. +- Key creation is not automatically retried after an ambiguous response because that may mint duplicate secrets. Recovery requires refresh/list metadata and deliberate new key/rotation. +- Operation/Agent mutations keep existing CAS/revision semantics. Onboarding may recommend an action but cannot weaken preconditions. +- External verifier credentials without a local typed key reference cannot satisfy exact-key completion. +- Request ID and Trace ID are support identifiers, not metric labels. UI shows/copies them without payload. +- No new dependency, framework, MSRV/toolchain change or frontend state model. + +### Likely File Map + +Likely NEW: + +- `crates/crank-core/src/product_event.rs` +- `crates/crank-registry/src/migrations/onboarding_product_events_v11.rs` +- `crates/crank-registry/src/migrations/onboarding_product_events_v11.sql` +- `crates/crank-registry/src/migrations/schema_guard_v11.rs` +- `crates/crank-registry/src/postgres/onboarding.rs` +- `crates/crank-registry/tests/integration/onboarding.rs` +- `apps/admin-api/src/routes/onboarding.rs` +- `apps/admin-api/src/service/onboarding.rs` +- `apps/admin-api/tests/integration/onboarding.rs` +- `apps/mcp-server/tests/onboarding.rs` or integration module under existing harness +- `apps/ui/js/onboarding.js` +- `apps/ui/css/onboarding.css` +- `apps/ui/tests/e2e/onboarding.spec.js` + +Likely UPDATE: + +- `crates/crank-core/src/lib.rs`, credential and observability types +- `crates/crank-registry/src/{lib.rs,model.rs,postgres/mod.rs,migrations.rs}` and migration authority/owned relations/schema guard +- MCP verifier/app/invocation-history path and associated tests +- `apps/admin-api/src/{app.rs,dto.rs,error.rs,service.rs}` and metrics route schema +- `apps/ui/js/{api.js,i18n.js}`, `apps/ui/scripts/build.js`, protected HTML templates/shared CSS +- `docs/{admin-api.md,data-model.md,mcp-interface.md,manual-regression-checklist.md,capability-inventory.json,migrations.md}` and baseline manifest/results. + +### Required Test Matrix + +- Snapshot: no objects; draft only; tested unpublished Operation; Published Operation; stale exact version; Published Agent; active/revoked/deleted/lost key; success exact key; foreign/unscoped success rejected. +- Regressions: archive/delete/revoke/re-publish/rebind and stale catalog revision return steps to actionable state. +- Events: eligible/start/complete/abandon are idempotent across refresh/parallel tabs; explicit denominator and UTC duration; unknown client completion is impossible; retention preserves denominators. +- Security: raw-key canary absent from DB, logs, history preview, ProductEvents, metrics, URLs/storage and test artifacts; cross-workspace cannot infer counts/state. +- MCP: public initialize, discovery and tools/call with real bearer and upstream; exact key/Agent/Operation/version/request_id/trace_id asserted; auth/compatibility/upstream/validation failures recover. +- UI: optional collapse/dismiss/resume; loading/empty/error/retry; reordered responses; workspace/session/language/visibility changes; back navigation and deep links; no duplicate publication/key creation. +- Accessibility: keyboard-only flow, focus after errors/actions, semantic checklist and live announcements, RU/EN, reduced motion. + +### Verification Commands + +```bash +cargo test -p crank-core product_event -- --test-threads=1 +cargo test -p crank-registry --test integration onboarding -- --test-threads=1 +cargo test -p admin-api --test integration onboarding -- --test-threads=1 +cargo test -p mcp-server --test onboarding -- --test-threads=1 +just ui-build +cd apps/ui && npx playwright test tests/e2e/onboarding.spec.js --project=chromium +just migration-check +just sqlx-check +just capability-inventory-check +python3 scripts/check-community-scope.py --root . --files +git diff --check +just verify +``` + +### References + +- `_bmad-output/planning-artifacts/epics.md` — Epic 1, Story 1.16. +- `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` — FR-1, FR-3, FR-4, FR-33, SM-11–SM-13. +- `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` — AD-1, AD-2, AD-11, AD-13, AD-16, AD-19, AD-22. +- `_bmad-output/project-context.md` — Rust/JS boundaries, testing, security and UI stale-response rules. +- `_bmad-output/implementation-artifacts/1-15-invocation-history-usage.md` — previous-story invocation/history/usage contracts. +- `docs/mcp-interface.md` — canonical public endpoint and JSON-RPC flow. + +## Dev Agent Record + +### Agent Model Used + +GPT-5.6 Codex (Sol) с маршрутизированными Luna/Terra subagents + +### Debug Log References + +- 2026-08-23T11:20:00+03:00 — Created Story 1.16 context from Epic 1, PRD/architecture, Story 1.15 lessons and current Operation/Agent/key/MCP/UI implementation. +- 2026-08-23T11:24:00+03:00 — Story context validated; baseline captured; implementation started with RED registry/Admin/MCP/UI evidence. +- 2026-08-24T00:07:00+03:00 — Task 1 RED complete: registry tests fail on missing V11/ProductEvents/key identity, Admin tests on missing onboarding routes, MCP test on absent exact-key invocation evidence, Playwright on absent checklist UI. +- 2026-08-24T00:31:00+03:00 — Task 2 GREEN complete: typed ProductEvents with eligible cohort time, V11 append-only persistence/rollups, exact MCP key identity in Invocation History and raw-bearer non-persistence evidence. +- 2026-08-24T00:51:00+03:00 — Task 3 GREEN complete: bounded seven-step registry projection, terminal-success oracle, honest revoke/stale regression and idempotent revision-guarded milestones; fixed RFC3339 cohort persistence found by Docker test. +- 2026-08-24T01:04:00+03:00 — Task 4 GREEN complete: authenticated onboarding GET/events API, stable CAS/error contract, sanitized first-call evidence and ephemeral three-client key connection configs; corrected measured metrics budget. +- 2026-08-24T01:24:00+03:00 — Task 5 GREEN complete: shared protected Getting Started UI, safe deep links, stale guards and one-time connection reveal/lost-key recovery; focused Playwright 3/3 passes after fixing test synchronization. +- 2026-08-24T03:00:00+03:00 — Task 6 GREEN complete: RU/EN и accessibility contracts, persisted dismiss/resume, exact public MCP identity/version evidence и отдельные validation/upstream/auth/compatibility recovery scenarios; focused Playwright 8/8. +- 2026-08-24T03:22:00+03:00 — Adversarial review closed: archived exact lineage no longer silently switches to an alternative path; republish/key-expiry/revoke boundaries and full regression evidence revalidated. +- 2026-08-24T03:22:35+03:00 — Task 7 GREEN complete: docs/baselines/protocol updated, full UI 43/43 and final `just verify` pass; story and sprint moved to review. +- 2026-08-24T10:52:28+03:00 — Review PATCH complete: all 21 adversarial findings resolved; targeted backend 51/51, related UI 25/25, UI build, code-health, migration, SQLx, dependency, clippy and full `just verify` gates passed. + +### Completion Notes List + +- Ultimate context engine analysis completed — comprehensive developer guide created. +- Task 1 closed with compiling RED contracts across registry, Admin API, public MCP and real-stack Playwright; observed failures are feature gaps, not syntax or fixture failures. +- Task 2 closed: core ProductEvent tests 2/2, registry onboarding tests 4/4, public MCP exact-key/no-secret test 1/1 and MCP regression 35/35 pass. +- Task 3 closed: registry onboarding projection suite 6/6 passes against PostgreSQL, including completion/regression, cross-workspace FK, ProductEvent idempotency and stale revision. +- Task 4 closed: Admin onboarding tests 2/2, credential lifecycle 8/8 and metrics schema 8/8 pass; canonical metrics contract regenerated and validated. +- Task 5 closed: UI Docker build passes; checklist/resume/stale-response/one-time-key focused Playwright scenarios pass 3/3 with raw secret absent after navigation. +- Task 6 closed: focused Playwright 8/8 and full UI regression 43/43 pass. The real-stack scenario performs initialize → notifications/initialized → tools/list → tools/call through the public endpoint and asserts exact Agent/key/Operation/version plus Request ID, Trace ID and Invocation History link. +- Review correction closed: historical successful lineage remains selected across archive while current Operation/Agent/key flags regress independently; an alternative Published path can no longer hide invalidation of the completed path. +- Review correction closed: dismiss is persisted per workspace, survives reload and exposes an explicit localized Resume action; 422 validation, 502 upstream, 426 compatibility and 401 authentication recovery remain incomplete until authoritative server evidence exists. +- Task 7 closed: ProductEvent/V11, Admin/MCP/UI and documentation contracts are synchronized. The five-participant usability protocol is executable but intentionally recorded as `not_run`; no measured ≤15-minute claim is made. +- Final evidence: core ProductEvent 2/2, registry onboarding 10/10, Admin onboarding 3/3, MCP onboarding 1/1, migration suite 23/23, focused UI 8/8, full UI 43/43, SQLx offline check and `just verify` pass. Dependency audit reports 0 vulnerabilities; the million-row production-size query-plan test remains explicitly ignored for dedicated release hardware. +- Capability baseline `2026.08.24.1` validates 35 flows. Onboarding release flows remain honestly `blocked` until a clean committed source revision and collector report exist; this is release evidence debt, not an implementation blocker. +- Code review closed 21/21 findings: exact lineage/reset, executable default MCP key, absolute safe client configuration, one-time-secret recovery, atomic/idempotent events, call-time completion, complete funnel/UI evidence, expiry/retention/schema integrity and coalesced reads are all covered. Story 1.16 is `done`; no unresolved High or Medium findings remain. + +### File List + +- `_bmad-output/implementation-artifacts/1-16-mcp-tool-call.md` +- `_bmad-output/implementation-artifacts/sprint-status.yaml` +- `apps/admin-api/src/app.rs` +- `apps/admin-api/src/dto.rs` +- `apps/admin-api/src/error.rs` +- `apps/admin-api/src/routes.rs` +- `apps/admin-api/src/routes/onboarding.rs` +- `apps/admin-api/src/service.rs` +- `apps/admin-api/src/service/api_keys.rs` +- `apps/admin-api/src/service/onboarding.rs` +- `apps/admin-api/tests/integration.rs` +- `apps/admin-api/tests/integration/onboarding.rs` +- `apps/admin-api/tests/migration_command.rs` +- `apps/mcp-server/tests/onboarding.rs` +- `apps/ui/css/onboarding.css` +- `apps/ui/html/api-keys.html` +- `apps/ui/js/agents.js` +- `apps/ui/js/api-keys.js` +- `apps/ui/js/api.js` +- `apps/ui/js/i18n.js` +- `apps/ui/js/onboarding.js` +- `apps/ui/js/wizard-live.js` +- `apps/ui/js/wizard-model.js` +- `apps/ui/js/wizard.js` +- `apps/ui/scripts/build.js` +- `apps/ui/scripts/playwright-http-fixture.js` +- `apps/ui/scripts/playwright-stack.sh` +- `apps/ui/scripts/playwright-ui-server.js` +- `apps/ui/tests/e2e/helpers.js` +- `apps/ui/tests/e2e/onboarding.spec.js` +- `apps/ui/tests/e2e/api-keys.spec.js` +- `apps/ui/tests/e2e/operations.spec.js` +- `apps/ui/tests/e2e/wizard.spec.js` +- `crates/crank-community-mcp/src/access.rs` +- `crates/crank-community-mcp/src/app.rs` +- `crates/crank-community-mcp/src/app/approval_policy.rs` +- `crates/crank-community-mcp/src/app/invocation_history.rs` +- `crates/crank-core/src/ext/auth.rs` +- `crates/crank-core/src/ids.rs` +- `crates/crank-core/src/lib.rs` +- `crates/crank-core/src/observability.rs` +- `crates/crank-core/src/onboarding.rs` +- `crates/crank-core/src/product_event.rs` +- `crates/crank-metrics/src/schema.rs` +- `crates/crank-metrics/tests/schema_v1.rs` +- `crates/crank-registry/src/error.rs` +- `crates/crank-registry/src/lib.rs` +- `crates/crank-registry/src/migrations.rs` +- `crates/crank-registry/src/migrations/authority.rs` +- `crates/crank-registry/src/migrations/authority_tests.rs` +- `crates/crank-registry/src/migrations/onboarding_product_events_v11.rs` +- `crates/crank-registry/src/migrations/onboarding_product_events_v11.sql` +- `crates/crank-registry/src/migrations/owned_relations.rs` +- `crates/crank-registry/src/migrations/schema_guard.rs` +- `crates/crank-registry/src/migrations/schema_guard_v11.rs` +- `crates/crank-registry/src/model.rs` +- `crates/crank-registry/src/postgres/mod.rs` +- `crates/crank-registry/src/postgres/observability.rs` +- `crates/crank-registry/src/postgres/onboarding.rs` +- `crates/crank-registry/src/postgres/product_event.rs` +- `crates/crank-registry/tests/integration.rs` +- `crates/crank-registry/tests/integration/common.rs` +- `crates/crank-registry/tests/integration/migrations.rs` +- `crates/crank-registry/tests/integration/migrations/rollback.rs` +- `crates/crank-registry/tests/integration/onboarding.rs` +- `crates/crank-registry/tests/integration/onboarding_lifecycle.rs` +- `docs/admin-api.md` +- `docs/capability-baseline/manifest.json` +- `docs/capability-baseline/manual-checklist.md` +- `docs/capability-baseline/outcome-taxonomy.json` +- `docs/capability-baseline/required-surfaces.json` +- `docs/capability-baseline/results.json` +- `docs/capability-inventory.json` +- `docs/data-model.md` +- `docs/database-schema.md` +- `docs/en/migrations.md` +- `docs/manual-regression-checklist.md` +- `docs/mcp-interface.md` +- `docs/migrations.md` +- `docs/schemas/metrics-registry-v1.json` +- `docs/schemas/migration-sequence.json` + +## Change Log + +- 2026-08-23 — Created Story 1.16 with server-authoritative onboarding, exact key-scoped MCP success and local ProductEvent context. +- 2026-08-24 — Implemented ProductEvent/V11 persistence, authoritative seven-step projection, safe Admin API, Getting Started UI and real public MCP acceptance flow. +- 2026-08-24 — Closed adversarial review findings for archive-lineage regression, persisted dismiss/resume, exact identity/version assertions and typed failure recovery; moved story to review after full gates passed. +- 2026-08-24 — Froze RED registry/Admin/MCP/Playwright contracts for Story 1.16. +- 2026-08-24 — Added typed ProductEvents, V11 persistence and exact key-scoped MCP invocation evidence. +- 2026-08-24 — Added and verified server-authoritative onboarding projection and milestone state. +- 2026-08-24 — Added Admin onboarding API, ephemeral connection guidance and fixed-route metrics contract. +- 2026-08-24 — Added protected Getting Started UI, existing-flow deep links and secure one-time connection UX. +- 2026-08-24 — Resolved all 21 adversarial review findings and closed Story 1.16 after the complete repository verification passed. diff --git a/_bmad-output/implementation-artifacts/1-2-baseline-flows.md b/_bmad-output/implementation-artifacts/1-2-baseline-flows.md new file mode 100644 index 0000000..6ca305b --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-2-baseline-flows.md @@ -0,0 +1,309 @@ +--- +baseline_commit: c30461cc92491ebe3d527e125a1657b73fa67006 +--- + +# Story 1.2: Зафиксировать фактический baseline существующих flows + +Status: done + + + +## Story + +As a владелец продукта, +I want получить проверенный baseline всех существующих возможностей Crank, +so that функциональные недоработки и регрессии видны до начала расширения продукта. + +## Acceptance Criteria + +1. **Полный machine-readable inventory.** Given validator и schema из Story 1.1, when выполняется инвентаризация текущего brownfield-продукта, then canonical inventory перечисляет все известные пользовательские и протокольные flows UI, Admin API и MCP для Operations, Agents, Auth Profiles/Upstreams/Secrets, MCP- и approval-ключей, approvals, test execution, YAML/OpenAPI import/export, Logs и Usage; каждый flow имеет стабильный ID, observable contract, `FR-*`, owner, implementation status и ссылки на текущее evidence. Все FR-1…FR-54 представлены: существующие flows описаны детально и честно, будущие Resources/Prompts/Tasks/Load Runs и другие target flows остаются `planned`, `gap` или `blocked`, но не `implemented` без доказательств. + +2. **Проверенный REST→MCP happy path.** Given текущий Community stack, when администратор создаёт простую REST Operation, выполняет Admin test-run, публикует полученную из API точную версию, привязывает её к полученной из API Agent revision, публикует Agent, создаёт MCP key и вызывает Tool из MCP-клиента, then весь путь завершается успешно хотя бы в одном реальном запуске на текущем Community stack. Evidence фиксирует только безопасные operation ID/version, Agent ID/revision, команды/предусловия и нормализованный outcome; credential, raw key, cookie, sensitive header/query/body, приватный payload и host path не попадают в stdout, error, evidence или документацию. `not_run`/`blocked` допустимы как честный промежуточный baseline, но Story остаётся незавершённой до реального успешного запуска. + +3. **Автоматизированное evidence без ложного pass.** Given существующие suites, when trusted collector запускает allowlisted commands либо принимает bounded machine report, then targeted Rust tests, `just verify`, UI build и применимый Playwright smoke связываются с конкретными flow IDs и содержат command identity, source revision/environment class, source-report SHA-256 и вычисленный verdict. Canonical `pass` нельзя вводить вручную. `failed`, retry-pass/`flaky`, `skipped`, `not_run`, missing result или malformed evidence никогда не нормализуются в `pass`. + +4. **Ограниченный exploratory UI baseline.** Given основные Community-экраны, when выполняется bounded exploratory pass, then для каждого применимого flow зафиксированы happy, loading, empty, error и доступный recovery state. Отсутствующий state отмечается `gap`/`not_run`, а stale-response, RU/EN/localization и unsafe-output проблемы получают стабильный finding ID и связь с flow; этот pass не выдаётся за полный manual regression Epic 8. + +5. **Дефекты блокируют честно.** Given найденный дефект, when он добавляется в baseline results, then запись содержит стабильный ID, severity, bounded reproducible steps, affected observable contract, flow IDs, owner и next evidence/action. Critical или High автоматически требует `blocked` у каждого связанного flow; агрегированный статус Epic или зелёный unrelated suite не может скрыть блокировку. + +6. **Implementation status и evidence verdict разделены.** Given отсутствие automated evidence, then flow получает `evidence_mode=manual_only` с retained manual result и `next_evidence` либо `implementation_status=gap` с названным next evidence. Closed axes: `implementation_status=implemented|planned|gap|blocked`; `execution_verdict=pass|fail|blocked|skipped|flaky|not_run`; `evidence_mode=automated|manual_only`. `manual_only` не является implementation status, `gap` не является execution verdict, и только `implemented + automated + pass` считается полным baseline pass. + +7. **Baseline заморожен и проверяем.** Given завершённая инвентаризация, then inventory, required-surface contract, outcome taxonomy, manual checklist и results имеют общий `baseline_version` и lowercase SHA-256 exact tracked file bytes в canonical manifest; validator fail-closed проверяет version parity, schema, checksums, cross-links, verdict/status/defect invariants и bounded/redacted diagnostics. Story 1.2 гарантирует self-consistency одного snapshot; immutable predecessor chain/signature принадлежит 8.1. Любое последующее изменение snapshot требует новой baseline version, нового evidence и пересчитанного manifest. Story 1.2 не заменяет RC-wide CI gates (8.2) или полный manual regression (8.3). + +## Tasks / Subtasks + +- [x] Task 1 — Зафиксировать baseline contract до сбора результатов (AC: #1, #3, #5, #6, #7) + - [x] Создать `docs/capability-baseline/outcome-taxonomy.json` с тремя независимыми closed axes и truth table: implementation status, execution verdict и evidence mode; полный pass только `implemented + automated + pass`. + - [x] Создать `docs/capability-baseline/required-surfaces.json`: нормативный closed список обязательных surface groups/stable flow IDs и минимальной гранулярности. Включить Operations lifecycle/test/import/export, Agents/catalog/bindings, Auth Profiles, Upstreams, Secrets, MCP keys, approval keys, approvals, Logs, Usage, auth/workspace и MCP transport/list/call. + - [x] Создать `docs/schemas/capability-baseline.schema.json` с Draft 2020-12, закрытыми объектами, обязательными полями и численными bounds для taxonomy, results, defects, commands, paths, strings и коллекций. Не добавлять новую dependency и не писать универсальный JSON Schema engine. + - [x] Создать `docs/capability-baseline/manual-checklist.md` с versioned bounded checklist (10–16 charters) для актуальных основных UI flows и состояний happy/loading/empty/error/recovery/stale/RU-EN/safe-output. Для N/A требуется причина; пустое поле не является pass. + - [x] Создать `docs/capability-baseline/results.json` с version, source revision/environment class, command results, flow mappings, manual results и defect ledger. Хранить summary/verdict, а не raw console/network/payload dump. + - [x] Создать `docs/capability-baseline/manifest.json` с общим baseline version, normalized repo-relative paths и lowercase SHA-256 exact tracked bytes для inventory, required-surfaces, taxonomy, checklist и results; manifest не хеширует сам себя. + +- [x] Task 2 — Реализовать fail-closed baseline validator (AC: #1, #3, #5, #6, #7) + - [x] Создать stdlib-only `scripts/validate-capability-baseline.py`; reuse path, JSON, deterministic-report и redaction patterns из `scripts/validate-capability-inventory.py`, не дублировать Community scanner или product runtime. + - [x] Проверять Draft 2020-12 baseline contract, duplicate JSON keys, strict UTF-8, repo-relative normalized existing regular non-symlink paths, manifest SHA-256, unique IDs, known inventory flow IDs и normative required-surfaces completeness/granularity. + - [x] Проверять invariants: Critical/High ⇒ все affected flows `blocked`; axes не смешиваются; unknown/missing/flaky/skipped/not-run не pass; полный pass только `implemented + automated + pass`; manual-only требует retained result/`next_evidence`; planned target не получает fabricated pass. + - [x] Ограничить каждый JSON input 4 MiB, checklist 1 MiB, diagnostics 1000 и итоговый stderr 65,536 bytes; задать bounds в schema, ловить `OSError`, `UnicodeDecodeError`, `JSONDecodeError`, `ValueError`, `RecursionError`; не печатать raw invalid value, resolved host path или пользовательский payload. + - [x] Выдавать стабильные machine codes и JSON pointers. Минимальный набор: `INVALID_JSON`, `INVALID_SCHEMA_CONTRACT`, `INPUT_TOO_LARGE`, `BROKEN_ARTIFACT_LINK`, `CHECKSUM_MISMATCH`, `UNKNOWN_FLOW_ID`, `MISSING_FLOW_EVIDENCE`, `NON_PASS_RECORDED_AS_PASS`, `SEVERE_DEFECT_FLOW_NOT_BLOCKED`, `UNSAFE_EVIDENCE`, `BASELINE_VERSION_MISMATCH`. + +- [x] Task 3 — Создать RED→GREEN unit/contract tests baseline tooling (AC: #1, #3, #5, #6, #7) + - [x] Создать `tests/unit/test_validate_capability_baseline.py` по stdlib `unittest`/temporary-root pattern Story 1.1; никаких оставшихся `skip(RED_PHASE)`. + - [x] Покрыть canonical success, missing/unknown flow, stale checksum, version mismatch, duplicate IDs/keys, malformed/oversized/deep JSON, symlink/traversal/absolute/control-character paths, unknown schema keyword и schema/semantic drift. + - [x] Покрыть exact verdict semantics: fail/flaky/skipped/not_run/missing не pass; manual-only требует retained manual result и next evidence; Critical/High defect при non-blocked flow fail-closed; Medium/Low остаются traceable. + - [x] Покрыть deterministic sorting, bounded/redacted output, canary credentials/headers/query/JSON/YAML/host paths, limit-1/limit/limit+1 и отсутствие traceback. + - [x] Обновить `tests/unit/test_validate_capability_inventory.py`: canonical inventory покрывает FR-1…FR-54, обязательные surface groups и только tracked regular evidence paths; существующие Story 1.1 regression tests сохранить. + +- [x] Task 4 — Реализовать trusted collector/sanitizer evidence (AC: #3, #6, #7) + - [x] Создать stdlib-only `scripts/collect-capability-baseline.py`: запускать только closed allowlist command IDs либо принимать bounded source reports; flow mappings берутся из reviewed config, canonical verdict вычисляется из exit/status/retries/skips, не из hand-authored `pass`. + - [x] Playwright JSON писать в ignored temporary path, проверять размер/UTF-8/JSON, вычислять source-report SHA-256 и переносить только sanitized counts/statuses. Retry-pass классифицировать `flaky`; raw stdout/errors/attachments/screenshots/trace/video/host paths не переносить. + - [x] Для Rust/Python/build/smoke фиксировать command ID, bounded exit summary, source revision/environment class и flow IDs. Missing report/command, signal, timeout и non-zero exit дают non-pass. + - [x] Создать `tests/unit/test_collect_capability_baseline.py`: allowlist, exit/retry/skip truth table, missing/malformed/oversized reports, deterministic sanitized output, secret/URL/host-path canaries и запрет hand-authored pass. + - [x] Collector пишет candidate results; manifest пересчитывается отдельным шагом только после review candidate. Collector не получает credentials и не печатает environment values. + +- [x] Task 5 — Инвентаризировать фактические flows без исправления продукта (AC: #1, #5, #6) + - [x] Обновить `docs/capability-inventory.json`: детальные current UI/API/MCP flows для Operations lifecycle/test/YAML/OpenAPI, Agents/catalog/bindings, Auth Profiles/Upstreams/Secrets, MCP/approval keys, approvals, Logs/Usage и auth/workspace settings; сохранить четыре существующие planned entries. + - [x] Моделировать flow как пользовательский/протокольный outcome, не как строку на каждый HTTP endpoint. Operations/Agents/approvals/history/import относятся к capability family `tools`; не расширять enum `tools|resources|prompts|tasks|load_runs` доменными псевдо-capabilities. + - [x] Сопоставить существующие contracts с FR-1…FR-6, не объявляя эти FR полностью hardened. FR-7…FR-54 связать с минимальными честными target/gap/planned/blocked entries только для traceability; детальная декомпозиция и feature implementation остаются owning stories. + - [x] Для каждого existing flow задать owner, observable outcome и links на конкретные tests/results/checklist. Suite-level ссылка без contract-level mapping не считается достаточной. + - [x] Все обнаруженные функциональные проблемы записать в results/defect ledger; production `apps/**`, `crates/**`, migrations и UI behavior в этой Story не чинить. + +- [x] Task 6 — Дополнить существующий brownfield product smoke (AC: #2, #3) + - [x] Обновить `scripts/authenticated-product-smoke.py`, не создавать второй smoke: после create Operation выполнить `/operations/{id}/test-runs`, проверить safe success outcome, затем publish exact version, bind/publish exact Agent revision и MCP `tools/list`/`tools/call`. + - [x] Получать Operation version и Agent revision из create/publish/get API responses и передавать через helper return values; hard-coded `1` в publish/bind/evidence запрещён. + - [x] Ввести единый bounded redacting error formatter для HTTP, MCP и cleanup: только stable stage/code/status; никогда full URL, response body, tool list или raw MCP error. Safe summary содержит IDs/revisions/stages/verdict/command identity, но не key/session/payload. + - [x] Выполнять cleanup в `finally` после создания первого asset; сохранить `CRANK_PRODUCT_SMOKE_KEEP_ASSETS`. Cleanup warning не подменяет основной verdict и проходит через safe formatter. + - [x] Обновить `tests/unit/test_authenticated_product_smoke.py`: request ordering, test-run contract, exact revisions, safe summary и redaction canaries. Не обращаться к внешнему публичному API. + - [x] Запустить smoke на текущем Community stack. Отсутствие окружения/credential фиксируется `not_run`/`blocked`, но является HALT для завершения Story до реального успешного запуска. + +- [x] Task 7 — Собрать automated evidence и выполнить bounded UI pass (AC: #3, #4, #5, #6) + - [x] Запустить targeted Admin API/MCP/Rust tests и связать test cases с flow IDs; отдельно выполнить `just verify`. + - [x] Выполнить UI build. Playwright запускать с pinned `@playwright/test` 1.61.1, `--forbid-only`, JSON result в ignored temp file и fail-on-flaky semantics; collector переносит sanitized summary/report SHA, raw report/build output не коммитить. + - [x] Выполнить применимые smoke specs: login, operations/wizard, agents, keys, secrets/auth configuration, logs/usage и workspace/settings. Skip/retry-pass с flaky classification не записывать как pass. + - [x] Пройти manual checklist. Decision table: observed success/failure ⇒ pass/fail; применимый, но не выполненный state ⇒ not_run; отсутствующий обязательный contract ⇒ implementation gap; N/A допустим только для неприменимого by-design state с bounded reason. Проверить stale responses, RU/EN и safe DOM/error sinks. + - [x] Обновить defect ledger и implementation statuses по severity invariant; не исправлять найденные product gaps в рамках этой Story. + +- [x] Task 8 — Подключить canonical baseline gate (AC: #1, #3, #7) + - [x] Обновить `justfile`: `capability-inventory-check` требует FR-1…FR-54 и запускает оба validator; сохранить порядок и все существующие `just verify` gates. + - [x] Обновить `.gitea/workflows/ci.yml`: Python tooling tests → inventory validator → baseline validator → Community scope → существующие Rust/UI gates. Не полагаться только на `just verify`. + - [x] Обновить `.gitea/workflows/release.yml`: `python3 --version`, tooling/inventory/baseline/scope gates выполняются до build/package/publish; failed evidence или checksum drift блокирует release. + - [x] Не добавлять Cargo/npm dependency, не менять Rust toolchain, package/lock files, DB schema или wire contract. Существующий owner-approved `Cargo.lock` diff Story 1.1 не расширять. + +- [x] Task 9 — Документация и handoff (AC: #1, #4, #6, #7) + - [x] Обновить `README.md`, `docs/README.md`, `docs/intro.md`, `docs/en/README.md`, `CONTRIBUTING.md`, `scripts/README.md`: baseline paths, команды, status-versus-verdict semantics, checksum regeneration/verification и правило evidence-backed status changes. + - [x] User-facing утверждения синхронизировать RU/EN. Не рекламировать planned Resources/Prompts/Tasks/Load Runs или отсутствующий UI state как реализованные. + - [x] Локально обновить ignored `_bmad-output/project-context.md` устойчивыми правилами, но не делать его CI prerequisite и не force-add. + - [x] Явно просканировать каждый NEW/UPDATE tracked path через Community scope checker; canonical artifacts/schema/validator целиком не исключать. + +- [x] Task 10 — Финальная проверка и честный completion record (AC: #1–#7) + - [x] Выполнить targeted Python tests, smoke unit tests, targeted Rust tests, UI build/Playwright, оба canonical validators, explicit Community scope scan и `just verify`. + - [x] Финализировать inventory/required-surfaces/taxonomy/checklist/results, проверить общий baseline version, затем хешировать exact bytes и записать manifest последним; любое content change требует bump version. Повторно проверить checksum и deterministic output. + - [x] Проверить `git diff --check`, полный file list и отсутствие случайных dependency/toolchain/runtime/DB изменений, generated reports, screenshots, credentials и raw payloads. + - [x] В Dev Agent Record перечислить фактически выполненные команды и verdict. Недоступное окружение, skipped/flaky/missing evidence и найденные блокеры оставить явно non-pass. + +### Review Findings + +- [x] [Review][Patch][High] Выполнить bounded exploratory UI baseline сейчас: пройдены все 12 charters; observed verdicts, next evidence и найденные defects сохранены без raw browser artifacts. [docs/capability-baseline/manual-checklist.md] +- [x] [Review][Patch][High] Versioned schema contract и exact `full_pass` валидируются fail-closed; semantic/schema drift покрыт regressions. [docs/schemas/capability-baseline.schema.json] +- [x] [Review][Patch][High] Required surfaces закрыты exact group/flow membership, uniqueness, union и полнотой всех current flows. [scripts/validate-capability-baseline.py] +- [x] [Review][Patch][High] Checklist и `manual_results` связаны exact IDs/flows, axes, retained result и `next_evidence`. [scripts/validate-capability-baseline.py] +- [x] [Review][Patch][High] Accepted evidence ограничено command allowlist, unique IDs/hashes, common provenance, typed known flows и только implemented status. [scripts/validate-capability-baseline.py] +- [x] [Review][Patch][High] Collector всегда пишет `evidence_mode`, а fatal/malformed/non-object Playwright results классифицирует non-pass. [scripts/collect-capability-baseline.py] +- [x] [Review][Patch][High] `just-verify` больше не выдаётся за UI evidence; UI flow mapping оставлен только у UI build/Playwright runs. [docs/capability-baseline/results.json] +- [x] [Review][Patch][High] Smoke требует `isError=false` и ожидаемый safe mapped health outcome. [scripts/authenticated-product-smoke.py] +- [x] [Review][Patch][High] Smoke не печатает base URL/private endpoint. [scripts/authenticated-product-smoke.py] +- [x] [Review][Patch][Medium] Malformed workspace/key/tools responses проходят через bounded stable errors без traceback. [scripts/authenticated-product-smoke.py] +- [x] [Review][Patch][Medium] Stateful MCP session завершается DELETE в `finally`; реальный run подтвердил нулевой остаток sessions/assets. [scripts/authenticated-product-smoke.py] +- [x] [Review][Patch][Medium] Canonical manifest artifacts обязаны быть tracked в Git и воспроизводимы в clean checkout. [scripts/validate-capability-baseline.py] +- [x] [Review][Patch][Medium] Все фактически выполненные subtasks синхронизированы с completed parent Tasks. [_bmad-output/implementation-artifacts/1-2-baseline-flows.md] + +## Dev Notes + +### Scope Boundary + +- Story 1.2 — evidence/tooling-only Wave 0. Она наблюдает и замораживает текущий brownfield baseline, но не исправляет product defects и не меняет production Rust/UI/Admin API/MCP/DB surfaces. +- Hard prerequisite Story 1.1 завершён: использовать его canonical inventory, strict schema validator, deterministic bounded diagnostics и Community scope guardrail. Не ослаблять существующие validations ради заполнения baseline. +- Строгий порядок Epic 1: `1.1 → 1.2 → 1.3 → 1.4 → 1.5 → 1.6`. Typed config, migration authority, canonical correlation и typed metrics начинаются только после принятого baseline. +- Story 1.2 не завершает весь gate «Baseline Frozen»: Reference Workload и initial/signed Evidence Manifest имеют отдельную downstream ownership. Она также не заменяет 8.1, 8.2 и 8.3. + +### Canonical Artifact Design + +```text +docs/capability-inventory.json + │ flow IDs / implementation status / FR / owner + ▼ +docs/capability-baseline/results.json ─── defects + automated/manual verdicts + │ + ├── required-surfaces.json + ├── outcome-taxonomy.json + ├── manual-checklist.md + └── manifest.json ── SHA-256 всех пяти canonical inputs +``` + +- Сохранить inventory `schema_version: 1` и существующий closed schema, если AC можно выразить companion artifacts. Не добавлять evidence verdict/checksum поля в inventory и не превращать `manual_only` в implementation status. +- Manifest — единственный checksum index; lowercase SHA-256 вычисляется по exact tracked bytes, manifest не self-hash. Общий `baseline_version` имеет bounded `YYYY.MM.DD.N` format и совпадает во всех baseline artifacts; любое content change требует нового version и manifest. Immutable predecessor/signature добавляются только в 8.1. +- Canonical evidence links только repo-relative, tracked, existing, regular, non-symlink. Запрещены `_bmad-output`, `/tmp`, `target`, `node_modules`, generated Playwright HTML/trace/video/screenshot и absolute host paths. +- `required-surfaces.json` является normative completeness contract. Current flows достаточно мелкие, чтобы один failing contract не скрывался общей записью «Admin API работает», но не дублируют каждый route. Stable flow ID отражает outcome, например `api-operation-test-run`, `mcp-published-tool-call`, `ui-operation-yaml-import`. + +### Existing Surfaces and Reuse Map + +- **UI:** login/logout; Operations catalog/filter/delete; OpenAPI preview/create; wizard create/edit/version/test/publish/archive, sample upload/draft generation, YAML import/export; Agents CRUD/bind/publish/unpublish/archive/tool-search; MCP/approval keys create/list/revoke/delete/one-time reveal; Secrets; Auth Profiles/Upstreams within wizard; Logs/detail + approvals; Usage; workspace/profile/password/settings. +- **Admin API:** authoritative routes in `apps/admin-api/src/app.rs`; cover auth/session/profile/password, capabilities/workspaces, Operations lifecycle/test/samples/draft/quality/YAML/OpenAPI, Agents/bindings/catalog/keys, Auth Profiles/Upstreams/Secrets, export, logs/approvals/usage. +- **MCP:** current Streamable HTTP GET/POST/DELETE; initialize/initialized/ping; `tools/list`, `tools/call`; session/SSE/JSON negotiation; scoped catalog/tool-search; approval list/get/approve/deny and elicitation. Inventory observed revisions only; do not broaden protocol implementation. +- **Existing smoke:** extend `scripts/authenticated-product-smoke.py`; it already handles login, workspace resolution, Operation create/publish, Agent bind/publish, one-time MCP key, initialize, list, call and cleanup. Missing Admin test-run and explicit Operation version/Agent revision evidence are the Story 1.2 gaps. +- **Automated evidence:** Admin Operation/Agent tests in `apps/admin-api/tests/integration/operations_agents.rs`; secret/import/auth in `secrets_import_auth.rs`; OpenAPI in `openapi_import.rs`; access/keys/logs/usage in `community_access_usage.rs`; MCP transport/catalog/approvals/search in `apps/mcp-server/tests/integration/**`; UI specs in `apps/ui/tests/e2e/`. + +### Security, Reliability and Compatibility Guardrails + +- Applicable NFRs: NFR-S1, S2, S4, S6, S7, S8, O5 and C1. Baseline capture must remain default-deny, secret-safe, bounded, closed-contour and fail-closed where mandatory evidence is absent. +- Never store credentials, raw one-time keys, auth cookies, sensitive request/response payloads, private endpoint query data or resolved host paths. Commands use environment-variable names/placeholders, never values. +- Preserve Story 1.1 limits/patterns: strict UTF-8 and duplicate-key detection; bounded JSON/report; deterministic sorting; safe machine codes/pointers; validate paths before exclusions; reject absolute/traversal/control/symlink paths; catch malformed/deep JSON without traceback. +- Preserve Rust 1.96.1, Edition 2024, pinned npm packages including `@playwright/test` 1.61.1, current workspace/crate direction, Alpine concatenation and `window.Crank*` UI contract. No new dependency is required. +- Playwright baseline must distinguish retry-pass/flaky from stable pass. Use existing CLI/report capabilities; do not upgrade Playwright in this Story. `just verify` does not run UI build/E2E, so both remain explicit completion evidence. +- PostgreSQL remains durable source of truth; Valkey is optional/rebuildable. Baseline records observed behavior and gaps but does not alter persistence or failure semantics. + +### Test and Evidence Commands + +Targeted first; exact Rust test filters may be adjusted only after listing current test names, and any missing filter is non-pass evidence: + +```bash +python3 -m unittest discover -s tests/unit -p 'test_validate_capability_inventory.py' -v +python3 -m unittest discover -s tests/unit -p 'test_validate_capability_baseline.py' -v +python3 -m unittest discover -s tests/unit -p 'test_authenticated_product_smoke.py' -v +cargo test -p admin-api --test integration +cargo test -p mcp-server --test integration +cd apps/ui && npm ci && npm run build +tmp_report="$(mktemp)" && cd apps/ui && npx playwright test \ + login.spec.js operations.spec.js wizard.spec.js agents.spec.js \ + api-keys.spec.js secrets.spec.js logs-usage.spec.js workspace-settings.spec.js \ + --project=chromium --workers=1 --forbid-only --fail-on-flaky-tests --reporter=json >"$tmp_report" +cd ../.. && python3 scripts/collect-capability-baseline.py \ + --playwright-report "$tmp_report" --output +# CRANK_STAGING_ADMIN_EMAIL/CRANK_STAGING_ADMIN_PASSWORD already provisioned +just authenticated-product-smoke +python3 scripts/validate-capability-inventory.py --root . \ + --inventory docs/capability-inventory.json \ + --schema docs/schemas/capability-inventory.schema.json \ + $(for n in $(seq 1 54); do printf -- '--required-fr FR-%s ' "$n"; done) +python3 scripts/validate-capability-baseline.py --root . \ + --manifest docs/capability-baseline/manifest.json \ + --schema docs/schemas/capability-baseline.schema.json +python3 scripts/check-community-scope.py --root . --files +just verify +git diff --check +``` + +Do not paste secret values into shell history or committed results. Collector records environment variable names only. Delete the temporary raw Playwright report after the sanitized candidate is verified. + +### Project Structure Notes + +Expected NEW tracked files: + +- `docs/capability-baseline/outcome-taxonomy.json` +- `docs/capability-baseline/required-surfaces.json` +- `docs/capability-baseline/manual-checklist.md` +- `docs/capability-baseline/results.json` +- `docs/capability-baseline/manifest.json` +- `docs/schemas/capability-baseline.schema.json` +- `scripts/validate-capability-baseline.py` +- `scripts/collect-capability-baseline.py` +- `tests/unit/test_validate_capability_baseline.py` +- `tests/unit/test_collect_capability_baseline.py` + +Expected UPDATE tracked files: + +- `docs/capability-inventory.json` +- `tests/unit/test_validate_capability_inventory.py` +- `scripts/authenticated-product-smoke.py` +- `tests/unit/test_authenticated_product_smoke.py` +- `justfile` +- `.gitea/workflows/ci.yml` +- `.gitea/workflows/release.yml` +- `README.md` +- `docs/README.md` +- `docs/intro.md` +- `docs/en/README.md` +- `CONTRIBUTING.md` +- `scripts/README.md` + +Local ignored update: `_bmad-output/project-context.md`; не force-add и не использовать как canonical/CI evidence. + +Do not modify for this Story: `docs/schemas/capability-inventory.schema.json`, production `apps/**` кроме existing smoke script outside apps, `crates/**`, migrations, Cargo/npm manifests or locks, Rust toolchain and runtime/wire/DB/UI behavior. Если фактическая реализация требует такой change, остановиться и оформить correct-course/downstream defect вместо скрытого scope expansion. + +### Previous Story Intelligence + +- Story 1.1 завершилась двумя adversarial review rounds. Сохранить её fixes: strict schema-key allowlist, exact integer version (boolean invalid), duplicate JSON rejection, bounded one-line/file scans, fail-closed path resolution, correct truncation accounting, whitespace rejection и no traceback. +- Текущий inventory содержит четыре target entries и `pass=0`; это seed, а не доказательство отсутствия shipped Tools. Story 1.2 должна добавить фактические current flows и не удалять future Community intent. +- `just verify`, CI и release вызывают inventory guardrails напрямую; новый baseline validator подключается аналогично, а не заменяет существующий gate. +- Story 1.1 имеет owner-approved unrelated `Cargo.lock` security remediation. Это исключение не является разрешением расширять lockfile diff в Story 1.2. +- Рабочее дерево содержит незакоммиченные изменения Story 1.1. Preserve их; не перезаписывать и не откатывать чужие изменения. + +### Latest Technical Information + +- Использовать pinned Playwright 1.61.1. JSON reporter даёт structured result, `--forbid-only` запрещает случайные focused tests, `--fail-on-flaky-tests` делает retry-pass non-green; retries/statuses необходимо перенести в taxonomy без потери смысла. +- Official references: [Playwright CLI](https://playwright.dev/docs/test-cli), [Reporters](https://playwright.dev/docs/test-reporters), [Retries](https://playwright.dev/docs/test-retries). Не менять package version в рамках Story. + +### References + +- [Source: `_bmad-output/planning-artifacts/epics.md` — Epic 1, Cross-Epic Dependencies, Story 1.2] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` — FR-1…FR-6, FR-46, §§5.3–5.5, §§6–7] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md` — Community scope and evidence contract] +- [Source: `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` — AD-1, AD-19, AD-20, testing/security conventions] +- [Source: `_bmad-output/planning-artifacts/implementation-readiness-report-2026-08-08.md` — Required Actions 3–4] +- [Source: `_bmad-output/implementation-artifacts/1-1-capability-inventory.md` — completed contract, review findings, handoff] +- [Source: `_bmad-output/project-context.md` — Community boundaries, testing and artifact rules] +- [Source: `docs/capability-inventory.json`, `docs/schemas/capability-inventory.schema.json`, `scripts/validate-capability-inventory.py`] +- [Source: `apps/admin-api/src/app.rs`, `scripts/authenticated-product-smoke.py`, `apps/ui/playwright.config.js`] + +## Dev Agent Record + +### Agent Model Used + +GPT-5 Codex + +### Debug Log References + +- Baseline source revision: `c30461cc92491ebe3d527e125a1657b73fa67006`. +- Default Playwright stack exposed two Medium harness defects: premature PostgreSQL readiness and incomplete child-process cleanup. Both are retained as `DEF-BL-001`/`DEF-BL-002`; the accepted run used the existing external-PostgreSQL mode after database readiness. +- Bounded manual exploration reproduced `DEF-UI-001` (stale response), `DEF-UI-002` (mixed localization) and High `DEF-UI-003` (credential-shaped API error rendered into browser DOM). The five affected flows are honestly `blocked`; remediation remains in their owning hardening stories. + +### Completion Notes List + +- Frozen baseline `2026.08.09.1`: 30 inventory flows, 18 current `implemented`, 5 current `blocked` by High `DEF-UI-003`, and 7 future target flows kept `planned`; FR-1…FR-54 and every normative surface group are represented. +- Added separate implementation/evidence axes, normative required surfaces, bounded manual checklist/results, exact-byte SHA-256 manifest, strict Draft 2020-12 contract, fail-closed validator and trusted report collector. +- Extended the existing authenticated product smoke with Admin test-run, API-derived Operation version/Agent revision, safe bounded errors, cleanup in `finally`, and sanitized summary. A real Community-stack REST→MCP create/test/publish/bind/list/call run passed. +- Automated evidence passed: Admin API integration 30/30, MCP integration 31/31, UI build, selected Chromium Playwright 21/21 with no retry/skip, and complete `just verify`. All 12 bounded manual charters were executed; 3 passed and 9 failed with traceable next evidence. This baseline does not replace Epic 8 regression. +- Final gates passed after review patches: 86 Python tooling tests, inventory validator with FR-1…FR-54, baseline checksum/schema validator, 29-file explicit Community scan, repository-wide 484-file Community scan, dependency/security audit with 0 vulnerabilities, fmt, Clippy and all Rust tests. UI build and `git diff --check` passed. +- Raw Playwright/smoke/collector temporary reports and the exact test PostgreSQL container were removed after sanitized hashes/results were frozen. No Story 1.2 Cargo/npm/toolchain/runtime/DB change was introduced; the pre-existing Story 1.1 lockfile/security diff was preserved unchanged. + +### File List + +- `.gitea/workflows/ci.yml` +- `.gitea/workflows/release.yml` +- `CONTRIBUTING.md` +- `README.md` +- `docs/README.md` +- `docs/capability-baseline/manifest.json` +- `docs/capability-baseline/manual-checklist.md` +- `docs/capability-baseline/outcome-taxonomy.json` +- `docs/capability-baseline/required-surfaces.json` +- `docs/capability-baseline/results.json` +- `docs/capability-inventory.json` +- `docs/en/README.md` +- `docs/intro.md` +- `docs/schemas/capability-baseline.schema.json` +- `justfile` +- `scripts/README.md` +- `scripts/authenticated-product-smoke.py` +- `scripts/collect-capability-baseline.py` +- `scripts/validate-capability-baseline.py` +- `tests/unit/test_authenticated_product_smoke.py` +- `tests/unit/test_collect_capability_baseline.py` +- `tests/unit/test_validate_capability_baseline.py` +- `tests/unit/test_validate_capability_inventory.py` +- `_bmad-output/project-context.md` (local ignored update only) + +## Change Log + +- 2026-08-09: Implemented and froze Story 1.2 capability baseline; added validated evidence contracts/collector, expanded current-flow inventory, hardened authenticated product smoke, wired CI/release gates, recorded real automated evidence and moved Story to review. +- 2026-08-09: Applied all code-review patches, executed all 12 manual charters, recorded High `DEF-UI-003` and blocked affected flows, reran a clean REST→MCP smoke and every mandatory gate, then moved Story to done. diff --git a/_bmad-output/implementation-artifacts/1-3-typed-configuration-foundation.md b/_bmad-output/implementation-artifacts/1-3-typed-configuration-foundation.md new file mode 100644 index 0000000..99ac58c --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-3-typed-configuration-foundation.md @@ -0,0 +1,357 @@ +--- +baseline_commit: c30461cc92491ebe3d527e125a1657b73fa67006 +--- + +# Story 1.3: Создать расширяемый typed configuration foundation + +Status: done + + + +## Story + +As an оператор, +I want единый проверяемый способ конфигурировать существующие процессы, +so that каждая следующая capability добавляет параметры без новых скрытых environment contracts. + +## Acceptance Criteria + +1. **Единый typed contract текущих процессов.** Given все фактически используемые runtime-параметры `admin-api` и `mcp-server`, when создаётся leaf crate `crank-config`, then каждый current field представлен ровно один раз стабильным semantic path, canonical environment name, process applicability, type, unit-bearing name, required/default semantics, inclusive bounds, sensitivity и cross-field rules. `AdminProcessConfig` и `McpProcessConfig` строятся из одного registry; `crank-config` не зависит от других workspace crates. Deployment/build/test-only variables классифицированы отдельно и не становятся runtime fields. + +2. **Environment читается один раз до side effects.** Given process startup, when app получает immutable environment source, then `crank-config` читает и валидирует его до observability exporter, metrics/listener, DB connection, background task или HTTP bind. Production-код reusable crates `crank-runtime`, `crank-registry`, `crank-adapter-rest` и `crank-observability` больше не читает environment и принимает только values через constructors; apps получают validated config и выполняют composition mapping. Compile-time `env!("CARGO_PKG_VERSION")` остаётся допустимым. + +3. **Fail-safe parsing и cross-field validation.** Given missing required, malformed, non-UTF-8, unknown owned, out-of-range либо conflicting field, when Admin или MCP process стартует, then процесс завершается non-zero до side effects со stable code, canonical field path и bounded RU/EN diagnostic. Invalid boolean/port/session TTL/refresh/rate-limit больше не превращается в default. Unrelated OS fields игнорируются, но typo внутри owned `CRANK_`, поддерживаемого `POSTGRES_` или `OTEL_*` namespace даёт `config.unknown_field`. + +4. **Secrets и fingerprint безопасны.** Given effective config, when он форматируется, диагностируется или fingerprint-ится, then secret-bearing поля показываются только как `configured|unconfigured` и source class; raw/encoded value, per-secret digest, credential URL, query/header, DSN или host path отсутствуют в `Debug`, `Display`, JSON, logs и errors. Fingerprint — domain-separated lowercase SHA-256 из schema version, process kind, canonical non-secret values и secret presence markers; он детерминирован независимо от input order и не меняется при замене одного configured secret другим. + +5. **Schema, examples и reference не расходятся.** Given static typed field registry, when запускается contract generator/checker, then versioned machine schema, generated sections environment examples и parameter reference получают те же names/defaults/bounds/sensitivity/process scope. CI fail-closed обнаруживает duplicate, parsed-but-undocumented, documented-but-unused, unknown Compose parameter и divergent inline default. `CRANK_RUNTIME_MAX_CONCURRENT_WINDOW`, `CRANK_RUNTIME_MAX_CONCURRENT_JOBS` и MCP-only injection `CRANK_STORAGE_ROOT` не остаются ложными current runtime parameters. + +6. **Compatibility и aliases явны.** Given canonical field и поддерживаемый compatibility alias/form, when задан только один source, then получается одинаковое normalized значение и bounded deprecation record с replacement/removal window; equal dual input не создаёт два значения, differing dual input блокирует startup с `config.conflict`. `CRANK_DATABASE_URL` и decomposed `POSTGRES_*` являются взаимоисключающими DB forms. OTLP trace-specific-over-generic fallback сохраняет стандартную documented precedence и не маскируется как случайный legacy alias. Empty optional Compose value трактуется как unconfigured. + +7. **Brownfield behavior сохранён для валидного minimal profile.** Given текущая валидная minimal Community configuration, when оба процесса используют typed config, then сохраняются текущие defaults, PostgreSQL-only/memory-cache correctness, deny-before-allow outbound policy, cookie security derivation, Admin/MCP shared values и REST→MCP happy path. Phantom/no-effect fields не получают fabricated consumer: они удаляются из current examples с migration note либо явно блокируются как deprecated no-effect input. + +8. **Foundation доказан, но не расширяет downstream scope.** Given config suite and deployment smoke, when Story завершается, then проходят per-field default/min/max/invalid, cross-field, alias, unknown, redaction, fingerprint, generation, boundary и pre-side-effect startup tests, Compose validation, real minimal startup, authenticated REST→MCP smoke и `just verify`. Новые third-party versions/toolchain/wire/DB schema/UI не добавляются; механическая запись нового local workspace package в `Cargo.lock` допустима без registry dependency drift. `planned-community-deployment` остаётся `planned`, а Story 7.1 сохраняет ownership полного production profile/UI/support-bundle contract. + +## Tasks / Subtasks + +- [x] Task 1 — Зафиксировать normative field inventory и current semantics (AC: #1, #5, #6, #7) + - [x] До production edits создать table-driven tests/fixture для всех 57 обнаруженных runtime names: shared DB/runtime/cache/outbound/observability, Admin-only и MCP-only fields из раздела `Current Runtime Field Inventory`. Fixture отдельно классифицирует effective fields и parsed-but-no-effect `CRANK_CACHE_DEFAULT_TTL_MS`, не выдавая последний за работающий contract. + - [x] Для каждого field зафиксировать semantic path, process scope, type, unit, required/default, inclusive min/max, sensitivity, canonical source и compatibility metadata; runtime и deployment/build/test namespaces хранить раздельно. + - [x] Зафиксировать current defaults из обоих apps/libraries и устранить только доказанный drift: invalid больше не default, но valid absent input сохраняет minimal behavior. + - [x] RED tests должны первыми воспроизвести silent defaults, `CRANK_DATABASE_URL` conflict, unknown owned field, WINDOW/JOBS ghosts, MCP storage injection и credential-bearing diagnostics. + +- [x] Task 2 — Создать leaf crate `crank-config` без нового внешнего dependency graph (AC: #1, #3, #4) + - [x] Добавить `crates/crank-config` как workspace member; crate не зависит ни от одного workspace crate и использует только уже locked `serde`, `serde_json`, `sha2`, `thiserror`/`url` при реальной необходимости. + - [x] Разделить implementation по owner-модулям: field schema/source, typed values/process projections, validation, diagnostic, secret wrapper, fingerprint и rendering; не создавать один oversized `lib.rs` или catch-all helpers. + - [x] Parser принимает injectable ordered map/source для pure deterministic tests; единственный production adapter читает OS environment один раз. Не использовать global `set_var` в параллельных unit tests. + - [x] Secret wrapper не реализует раскрывающий `Debug`/`Display`/Serialize/AsRef; raw extraction доступна только намеренному composition method и не входит в diagnostic/fingerprint API. + +- [x] Task 3 — Реализовать exact parsing, bounds и cross-field matrix (AC: #1, #3, #6, #7) + - [x] Числовые baseline bounds: ports `1..=65535`; PG max connections `1..=1024`, min `0..=max`; acquire timeout `1..=300000 ms`, idle/lifetime `1000..=86400000 ms`; session TTL `1..=8760 h`; MCP refresh `100..=3600000 ms`; RPS `1..=100000`, burst `RPS..=1000000`; concurrency `1..=65535`; outbound response `1..=67108864 bytes`; cache TTL `1..=86400000 ms`; invocation retention `1..=36500 days`; OTLP durations `1..=300000 ms`, queue `1..=65536`, batch `1..=queue`. + - [x] Все strings/URLs/paths/host lists получают explicit byte/count bounds: env value ≤8192 bytes, diagnostic field path ≤256, storage path ≤4096, host item ≤253, host count ≤256, aggregate host-list ≤16384; control characters и invalid UTF-8 reject. + - [x] Boolean canonical forms — `true|false|1|0`; current `yes|no|on|off` допускаются только как observable compatibility spellings, typo никогда не равен false/default. + - [x] Проверить PG form exclusivity/min≤max; external cache requires credential-safe URL; memory+nonempty URL не игнорируется; metrics non-loopback bind requires token; OTLP protocol/endpoint/batch rules; burst≥RPS; required secrets nonempty; outbound allow/deny/list syntax и response bound. + - [x] `CRANK_CACHE_DEFAULT_TTL_MS` не оставлять parsed-but-unused: либо подключить к уже существующему documented consumer без изменения safety semantics, либо empty считать absent, а nonempty no-effect input отклонять stable deprecation diagnostic с migration path. Не создавать фиктивное использование ради checker. + +- [x] Task 4 — Ввести safe diagnostics, deprecations и fingerprints (AC: #3, #4, #6) + - [x] Closed codes минимум: `config.missing_required`, `config.invalid_encoding`, `config.invalid_type`, `config.out_of_range`, `config.unknown_field`, `config.conflict`, `config.unsafe_combination`, `config.deprecated_no_effect`. + - [x] Diagnostic содержит только code, semantic field path и fixed RU/EN messages; max 100 diagnostics, deterministic sort и serialized output ≤65536 bytes с valid UTF-8/JSON truncation marker. + - [x] Добавить canary matrix для DB password/URL, master/session/pepper/bootstrap secrets, cache URL, Sentry DSN, metrics token и OTLP headers; raw values не должны появляться даже через nested source error. + - [x] Fingerprint canonical ordering/domain separation/schema version/process kind; alias/canonical и input ordering не меняют normalized fingerprint, public effective change меняет, configured-secret rotation не создаёт dictionary oracle. + - [x] Deprecation record содержит только canonical path, source class, replacement и bounded removal window; leaf crate не логирует самостоятельно. + +- [x] Task 5 — Перевести apps и reusable libraries на validated value constructors (AC: #2, #3, #7) + - [x] `admin-api` и `mcp-server` загружают process config в самом начале `main`; config failure форматируется один раз и не инициализирует observability, metrics, DB, cache, worker или listener. + - [x] Apps преобразуют config-native primitives в `PgConnectOptions`, `AuthSettings`, `RuntimeLimits`, `RuntimeCacheConfig`, `RequestRateLimitConfig`, `OutboundHttpPolicy`, `MetricsConfig`, `ObservabilityConfig`, `SentryConfig` и `OtlpTraceConfig`; leaf crates не зависят друг от друга ради wiring. + - [x] Удалить production `from_env`/`community_from_env` paths и direct environment imports из runtime/registry/REST adapter/observability; существующие value constructors и domain validation сохранить/усилить. + - [x] `ObservabilityLifecycle` получает Sentry/OTLP config явно; config validation предшествует subscriber/exporter setup. Startup errors не возвращаются как raw `Box` chain с user value. + - [x] Сохранить `cookie_secure = base_url.starts_with("https://")`, current process-specific `CRANK_BASE_URL` semantics, default binds/rates/pool/cache/OTLP/metrics и одинаковый shared projection для Admin/MCP. + +- [x] Task 6 — Создать generated/checked configuration contract (AC: #1, #5, #6) + - [x] Добавить versioned machine artifact `docs/schemas/runtime-config.schema.json`, генерируемый из Rust field registry; artifact различает runtime fields и exact known deployment/build/test-only fields. + - [x] Добавить in-crate CLI, например `crank-config-contract`, с deterministic render и `--check`; schema/reference/example tables не дублируются в Python/shell constants. + - [x] Генерировать либо проверять marker-delimited sections `.env.example`, `deploy/community/.env.example`, `deploy/community/.env.images.example` и `docs/runtime-config.md`; secret examples — inert blank/required placeholders, не рабочие `change-me` credentials. + - [x] Синхронизировать current runtime blocks в root/community Compose; deployment-only image/publish/profile fields остаются вне process config. Удалить WINDOW/JOBS ghosts и ignored MCP storage injection; добавить documented `CRANK_DATABASE_URL` compatibility/migration contract. + - [x] Сохранить ручной explanatory prose вне generated markers; RU/EN operational wording добавлять одновременно там, где появляется user-facing text. + +- [x] Task 7 — Сделать config boundary и drift gate исполняемым (AC: #2, #5) + - [x] Расширить Rust dependency checker категорией `config`: `crank-config` не зависит от workspace crates; apps могут зависеть от него, остальные crates не должны переносить environment parsing обратно. + - [x] Добавить dedicated stdlib checker/tests, который на tracked и явно переданных new files ловит `std::env::var/vars/var_os`, imported/aliased readers, `*_from_env`, dotenv-like обходы и defaults вне `crank-config`; compile-time `env!` разрешён узко. + - [x] Drift checker читает generated machine schema как authority и fail-closed проверяет exact names/process applicability/defaults в examples/Compose/docs; никакой второй handwritten field table. + - [x] Включить `config-contract-check` в `just verify`, Gitea CI и release quality gates до Rust build/package; сохранить все существующие inventory/baseline/scope/dependency gates. + +- [x] Task 8 — Доказать contracts на unit, boundary и process уровнях (AC: #1–#7) + - [x] Table-driven tests для каждого field: absent/default, min, max, limit−1, limit+1, negative/overflow/float/whitespace/control/non-UTF8; explicit tests для booleans, enums, lists, socket/URL/path. + - [x] Alias matrix: canonical-only, compatibility-only, equal dual, conflicting dual, empty optional и deprecation; OTLP generic/signal-specific precedence и DB mutually-exclusive forms проверяются отдельно. + - [x] Process parity tests доказывают одинаковые shared normalized values/errors независимо от map order; representative consumer tests доказывают, что typed values реально применены, а не существуют только в schema snapshot. + - [x] Isolated subprocess tests для обоих binaries: invalid/unknown/conflicting input даёт non-zero bounded safe stderr до DB/exporter/listener side effects. + - [x] Contract tests generator `--check`, boundary bypass fixtures, redaction/debug/error/fingerprint privacy и exact deterministic output; никаких skipped acceptance tests. + +- [x] Task 9 — Deployment regression, evidence и handoff (AC: #7, #8) + - [x] Проверить root и canonical Community Compose через соответствующие `.env` examples; valid minimal profile поднимает Admin/MCP/PostgreSQL, readiness становится green. + - [x] Повторить Story 1.2 authenticated REST→MCP create/test/publish/bind/list/call smoke; raw reports/credentials/private endpoints не коммитить. + - [x] Выполнить targeted crate/app suites, config checker/generator, explicit Community scan всех NEW/UPDATE paths, `just verify` и `git diff --check`; Cargo/npm/toolchain diff audit должен показать только mechanical local workspace/path entries без registry version drift. + - [x] Обновить README/docs indexes/scripts README и local ignored `project-context.md` устойчивым правилом; не force-add `_bmad-output` и не менять frozen baseline artifacts/checksums без отдельного нового evidence snapshot. + - [x] В Dev Agent Record перечислить точные команды/verdict и честно оставить unavailable/flaky/skipped/missing evidence non-pass. Story не `done` без real minimal startup и successful authenticated product smoke. + +### Review Findings + +- [x] [Review][Patch] [High] Сделать `CRANK_DATABASE_URL` реально применимым в canonical Compose без синтетического конфликта с `POSTGRES_*` [deploy/community/docker-compose.yml:25] +- [x] [Review][Patch] [High] Enforce process applicability: чужие Admin/MCP fields должны fail-closed, а не приниматься или влиять на fingerprint [crates/crank-config/src/process.rs:222] +- [x] [Review][Patch] [High] Отклонять whitespace-only required secrets внутри `crank-config` до metrics/DB/listener side effects [crates/crank-config/src/process.rs:258] +- [x] [Review][Patch] [High] Завершить leaf-валидацию outbound hosts, DB URL, environment/log filter, Sentry и OTLP до consumer initialization с canonical RU/EN errors [apps/admin-api/src/main.rs:75] +- [x] [Review][Patch] [High] Сделать `FieldSpec` реальным authority для parser defaults/bounds, включая process-specific `CRANK_BASE_URL` и log defaults [crates/crank-config/src/process.rs:487] +- [x] [Review][Patch] [High] Убрать raw host paths/internal или credential-bearing URLs из публичных projection `Debug` и canonical fingerprint input [crates/crank-config/src/process.rs:35] +- [x] [Review][Patch] [High] Игнорировать unrelated OS variables до UTF-8/value validation; валидировать только owned/known namespaces [crates/crank-config/src/source.rs:25] +- [x] [Review][Patch] [High] Возвращать canonical semantic field paths и единый `config.*` vocabulary во всех Display/JSON diagnostics [crates/crank-config/src/process.rs:254] +- [x] [Review][Patch] [High] Отклонять port `0` для всех process/metrics socket fields [crates/crank-config/src/process.rs:345] +- [x] [Review][Patch] [High] Проверять Compose interpolation/default/operator values и references, а не только набор environment names [scripts/check-runtime-config.py:97] +- [x] [Review][Patch] [High] Закрыть multiline/token-spacing/re-export/macro/path обходы config-boundary gate и allowlist только exact package-version `env!` [scripts/check-config-boundaries.py:12] +- [x] [Review][Patch] [Medium] Сделать diagnostic truncation UTF-8-safe и реально гарантировать JSON budget ≤65536 bytes с omitted marker [crates/crank-config/src/diagnostic.rs:79] +- [x] [Review][Patch] [Medium] Генерировать `required/optional` secret reference из `FieldSpec.required`, не помечая optional exporters/URLs обязательными [crates/crank-config/src/render.rs:54] +- [x] [Review][Patch] [Medium] Нормализовать DB/base URL fingerprint semantics: одинаковое effective значение даёт одинаковый fingerprint, публичное изменение меняет его [crates/crank-config/src/process.rs:707] +- [x] [Review][Patch] [Medium] Не терять compatibility deprecation records при извлечении app projection; сделать bounded warning наблюдаемым оператору [apps/admin-api/src/main.rs:41] +- [x] [Review][Patch] [Medium] Добавить фактически заявленные per-type/subprocess invalid-conflict tests и точные воспроизводимые команды/verdicts в evidence [apps/admin-api/tests/config_startup.rs:3] + +## Dev Notes + +### Scope Boundary and Dependencies + +- Hard prerequisites 1.1 и 1.2 завершены. Порядок Wave 0 остаётся `1.1 → 1.2 → 1.3 → 1.4 → 1.5 → 1.6`; schema migration, request/trace identity и typed metrics не входят в эту Story. +- Story 1.3 типизирует static bootstrap/process configuration только текущих `admin-api` и `mcp-server` и их current libraries. PostgreSQL-authoritative product configuration не означает перенос process env в DB. +- Story 7.1 завершает FR-45 после появления будущих processes: required profiles/reload policy, full production generation, Admin read-only config view, support-bundle provenance и evidence linking остаются там. +- Не исправлять High `DEF-UI-003`, stale-response/localization defects, не добавлять UI config screen и не переводить `planned-community-deployment` в `implemented`. +- Применимые NFR: S2, S4, S6, S8, O5, C1, C4. NFR-R2 здесь не закрывается, потому что persisted configuration не добавляется. + +### Current Runtime Field Inventory + +Brownfield scan обнаруживает 57 уникальных runtime names. Canonical implementation inventory обязан классифицировать каждый из них по process applicability и effective/no-effect semantics: + +- **DB/shared (11):** `CRANK_DATABASE_URL`; `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_MAX_CONNECTIONS`, `POSTGRES_MIN_CONNECTIONS`, `POSTGRES_ACQUIRE_TIMEOUT_MS`, `POSTGRES_IDLE_TIMEOUT_MS`, `POSTGRES_MAX_LIFETIME_MS`. +- **Runtime/cache/outbound/shared (9):** `CRANK_MASTER_KEY`, `CRANK_BASE_URL`, `CRANK_RUNTIME_MAX_CONCURRENT_UNARY`, `CRANK_CACHE_BACKEND`, `CRANK_CACHE_URL`, `CRANK_CACHE_DEFAULT_TTL_MS`, `CRANK_OUTBOUND_ALLOWED_HOSTS`, `CRANK_OUTBOUND_DENIED_HOSTS`, `CRANK_OUTBOUND_MAX_RESPONSE_BYTES`. +- **Observability/shared (17):** `CRANK_ENVIRONMENT`, `CRANK_LOG_LEVEL`, `CRANK_SENTRY_DSN`, `CRANK_METRICS_ENABLED`, `CRANK_METRICS_BEARER_TOKEN`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`, `OTEL_EXPORTER_OTLP_TIMEOUT`, `OTEL_EXPORTER_OTLP_TRACES_TIMEOUT`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_EXPORTER_OTLP_TRACES_HEADERS`, `OTEL_BSP_MAX_QUEUE_SIZE`, `OTEL_BSP_MAX_EXPORT_BATCH_SIZE`, `OTEL_BSP_SCHEDULE_DELAY`, `OTEL_BSP_EXPORT_TIMEOUT`. +- **Admin-only (14):** `CRANK_ADMIN_BIND`, `CRANK_ADMIN_METRICS_BIND`, `CRANK_STORAGE_ROOT`, `CRANK_ADMIN_RATE_LIMIT_RPS`, `CRANK_ADMIN_RATE_LIMIT_BURST`, `CRANK_INVOCATION_LOG_RETENTION_DAYS`, `CRANK_SESSION_SECRET`, `CRANK_PASSWORD_PEPPER`, `CRANK_SESSION_TTL_HOURS`, `CRANK_TRUST_FORWARDED_HEADERS`, `CRANK_BOOTSTRAP_ADMIN_EMAIL`, `CRANK_BOOTSTRAP_ADMIN_PASSWORD`, `CRANK_BOOTSTRAP_ADMIN_DISPLAY_NAME`, `CRANK_DEMO_SEED`. +- **MCP-only (6):** `CRANK_MCP_BIND`, `CRANK_MCP_METRICS_BIND`, `CRANK_MCP_REFRESH_MS`, `CRANK_MCP_RATE_LIMIT_RPS`, `CRANK_MCP_RATE_LIMIT_BURST`, `CRANK_RUNTIME_MAX_CONCURRENT_SESSIONS`. + +The category arithmetic is exact: `11 + 9 + 17 + 14 + 6 = 57`. Из них `CRANK_CACHE_DEFAULT_TTL_MS` сейчас parsed, но не имеет доказанного consumer; Task 3 должна либо сделать его честным effective field, либо отклонять/вывести из current contract с migration path. `CRANK_RUNTIME_MAX_CONCURRENT_WINDOW` и `CRANK_RUNTIME_MAX_CONCURRENT_JOBS` — documentation ghosts, не supported runtime fields. Compose-only image/publish/profile variables не входят в effective process config. + +### Brownfield Readers and Required Refactoring + +Direct/hidden readers exist in: + +- `apps/admin-api/src/main.rs`, `apps/mcp-server/src/main.rs`; +- `crates/crank-runtime/src/limits.rs`, `cache.rs`, `executor_builder.rs`; +- `crates/crank-registry/src/postgres/pool_config.rs`; +- `crates/crank-adapter-rest/src/client.rs`; +- `crates/crank-observability/src/config.rs`, `prometheus.rs`, `otlp.rs`, `error_reporting.rs`, `lifecycle.rs`. + +Preserve constructors and owning validation inside consumer crates, but remove their environment dependency. `crank-observability` may depend only on `crank-metrics`, so it must not depend on `crank-config`; apps adapt validated primitives. Likewise config remains a true leaf and never imports SQLx/Axum/Tokio/runtime/registry/observability. + +Current unsafe/drift behavior to close: + +- invalid DB port, session TTL, MCP refresh, booleans and rate limits silently default; +- `CRANK_DATABASE_URL` silently overrides components; +- library env readers are hidden behind `community_from_env` and lifecycle init; +- cache URL/error enums can include credential-bearing raw values; +- WINDOW/JOBS are documented but unread; MCP receives ignored storage root; cache default TTL is parsed but has no proven consumer; +- root/community examples and Compose runtime blocks differ. + +### Existing Defaults to Preserve for Valid Input + +- DB components: host `postgres`, port `5432`, DB/user/password `crank`; pool `20/2/5000/600000/1800000`. +- Admin: storage `/var/lib/crank/storage`, bind `0.0.0.0:3001`, base URL `http://localhost:3000`, session TTL `24h`, display name `Crank Owner`, rate `30/60`, retention `30d`, absent demo/trusted-forwarded flags false in direct process config. +- MCP: bind `0.0.0.0:3002`, refresh `5000ms`, rate `60/120`, base URL optional in direct binary, session concurrency `16`. +- Shared: runtime unary `64`, memory cache, public-only outbound and response `4194304 bytes`, development observability identity outside Compose, Sentry/OTLP disabled when absent/empty, metrics enabled on loopback `9464/9465`. +- Current Community Compose explicitly selects production environment and trusted forwarded headers; process defaults and profile overrides must remain distinguishable, not silently conflated. + +### Architecture Compliance + +- AD-1: environment/composition wiring belongs at process edge; reusable crates receive values. +- AD-17: `crank-config` owns field vocabulary/defaults/bounds/sensitivity/cross-field validation and remains a leaf. +- AD-18: preserve current Community correctness topology and minimal profile. +- AD-19: safe errors use stable codes, bounded localized messages and never raw causes. +- Configuration convention: parse/validate once before serving; duration/size fields encode units; secrets use redacted wrappers; log only normalized non-sensitive settings. +- Rust 1.96.1, Edition 2024, MSRV 1.96. No new registry dependency/version or public wire contract. + +### Project Structure Notes + +Expected NEW tracked files (exact module split may be adjusted while preserving ownership): + +- `crates/crank-config/Cargo.toml` +- `crates/crank-config/src/lib.rs` +- `crates/crank-config/src/{schema,source,value,process,validation,diagnostic,fingerprint,render}.rs` +- `crates/crank-config/src/bin/crank-config-contract.rs` +- `crates/crank-config/tests/{contract,redaction,generation}.rs` +- `docs/schemas/runtime-config.schema.json` +- `scripts/check-runtime-config.py` +- `tests/unit/test_check_runtime_config.py` + +Expected UPDATE tracked files: + +- `Cargo.toml`, `Cargo.lock`; `apps/admin-api/Cargo.toml`, `apps/mcp-server/Cargo.toml`; +- `apps/admin-api/src/main.rs`, `apps/mcp-server/src/main.rs` and focused process config/startup tests; +- current reader modules in runtime, registry, REST adapter and observability listed above, plus their tests/exports; +- `scripts/check-rust-boundaries.py`, `scripts/check-rust-module-boundaries.sh`, `tests/unit/test_check_rust_boundaries.py`; +- `justfile`, `.gitea/workflows/ci.yml`, `.gitea/workflows/release.yml`; +- `.env.example`, `deploy/community/.env.example`, `deploy/community/.env.images.example`; +- `docker-compose.yml`, `deploy/community/docker-compose.yml`, `deploy/community/docker-compose.images.yml` where current runtime blocks drift; +- `docs/runtime-config.md`, docs/README indexes, `scripts/README.md`, README only if command/link changes. + +Local ignored update: `_bmad-output/project-context.md`; never canonical CI evidence and do not force-add. Preserve all existing staged/unstaged Story 1.1/1.2 changes. + +### Testing and Evidence Commands + +Targeted first, then full gates: + +```bash +cargo test -p crank-config --all-targets +cargo run -p crank-config --bin crank-config-contract -- --check +python3 -m unittest -v tests.unit.test_check_runtime_config tests.unit.test_check_rust_boundaries +scripts/check-rust-boundaries.sh +rg -n --glob '*.rs' --glob '!**/tests/**' \ + '(std::env|env::var|env::vars|var_os|from_env)' apps crates +cargo test -p admin-api -p mcp-server -p crank-observability \ + -p crank-runtime -p crank-registry -p crank-adapter-rest --all-targets +docker compose --env-file deploy/community/.env.example \ + -f deploy/community/docker-compose.yml config -q +docker compose --env-file deploy/community/.env.images.example \ + -f deploy/community/docker-compose.images.yml config -q +# Real minimal stack; credentials are pre-provisioned environment values, never literals. +just authenticated-product-smoke +python3 scripts/check-community-scope.py --root . --files +just verify +git diff --check +``` + +The direct `rg` command is an audit aid, not the authoritative bypass-resistant checker. UI/Playwright is N/A unless implementation unexpectedly changes UI; if it does, halt and correct-course rather than silently expand scope. + +### Previous Story Intelligence + +- Baseline `2026.08.09.1` is frozen: 18 implemented, 5 blocked by High `DEF-UI-003`, 7 planned. Do not rewrite its artifacts/checksums merely to claim config foundation progress. +- Reuse Story 1.1/1.2 standards: strict UTF-8, duplicate-key rejection for generated JSON, path normalization before exclusions, deterministic bounded diagnostics, no traceback/raw value, explicit scanning of new/untracked files. +- Real Community REST→MCP smoke has passed and is mandatory regression evidence after process rewiring. +- `just verify` does not run UI E2E; no UI is expected here. Existing Story 1.1 owner-approved `Cargo.lock` remediation is not precedent for dependency updates. +- Current worktree is dirty with approved 1.1/1.2 changes. Do not reset, overwrite or mix unrelated cleanup. + +### Git Intelligence Summary + +- Recent commits keep process wiring in `apps/*/main.rs`, typed metrics in a dedicated leaf and safe config constructors inside owning crates. Story 1.3 should follow that pattern: config owns schema/parsing, apps compose, consumer crates validate values. +- Commit `c30461c` hardened observability error/config handling; preserve its safe DSN/error behavior while removing env reads. +- Commit `9b1a739` established executable leaf/boundary checks for `crank-metrics`; extend the same category/checker pattern for `crank-config` instead of inventing a separate dependency model. +- Recent Compose smoke fixes show deployment ordering/readiness is fragile; real-stack evidence is required after rewiring startup. + +### Latest Technical Information + +- No external library/version research is needed for implementation: this Story intentionally adds no new third-party package and uses pinned Rust 1.96.1 plus existing locked dependencies. Do not upgrade crates based on current internet versions. +- Use SHA-256 from the already locked `sha2` crate; do not use `DefaultHasher`, unordered `HashMap` serialization or a secret digest as the effective-config fingerprint. + +### References + +- [Source: `_bmad-output/planning-artifacts/epics.md` — FR-45, AR-17, decomposition rules, dependency order, Story 1.3, Story 7.1] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` — FR-45; NFR-S2/S4/S6/S8, O5, C1/C4] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md` — closed-contour/deployment evidence directions] +- [Source: `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` — AD-1, AD-4, AD-17..AD-19, conventions, stack, structural seed] +- [Source: `_bmad-output/planning-artifacts/implementation-readiness-report-2026-08-08.md` — FR-45 mapping and enabling-story completion evidence] +- [Source: `_bmad-output/implementation-artifacts/1-2-baseline-flows.md` — frozen baseline, review lessons and smoke evidence] +- [Source: `_bmad-output/project-context.md` — architecture, testing, Community, CI and redaction rules] +- [Source: `apps/admin-api/src/main.rs`, `apps/mcp-server/src/main.rs`, `docs/runtime-config.md`, `.env.example`, `deploy/community/*`] + +## Dev Agent Record + +### Agent Model Used + +GPT-5 Codex + +### Debug Log References + +- Baseline source revision: `c30461cc92491ebe3d527e125a1657b73fa67006`. +- Первый Compose image build остановился до запуска сервисов: runner не содержал Docker buildx, а существующие Dockerfile используют BuildKit cache mounts. После системной установки Buildx владельцем проекта параллельный build обнаружил конфликт общего анонимного Cargo cache; cache IDs разделены по сервисам, после чего все три Community image собраны успешно. +- Первый host smoke дошёл до Operation test/publish и Agent publish, но direct MCP URL ошибочно использовал UI proxy prefix `/mcp` и получил 404. Повторный чистый прогон с предусмотренным `--mcp-path-prefix ''` прошёл полностью; временная БД, процессы, credentials и logs удалены. + +### Implementation Plan + +- Реализовать единый leaf registry и pure map parser, затем safe diagnostics/fingerprint. +- Перевести process edges на один validated snapshot и удалить environment readers из reusable crates. +- Генерировать machine/reference contracts из Rust registry и закрепить drift/boundary gates. +- Завершить targeted/full tests, Compose validation и реальный Community REST→MCP smoke. + +### Completion Notes List + +- Ultimate context engine analysis completed - comprehensive developer guide created. +- Добавлен leaf crate `crank-config`: единый registry 57 brownfield runtime names, отдельный deployment namespace, immutable source snapshot, Admin/MCP projections, inclusive bounds, cross-field validation, safe RU/EN diagnostics, compatibility records и privacy-preserving SHA-256 fingerprints. +- `admin-api` и `mcp-server` теперь валидируют config до любых exporter/DB/listener side effects; runtime, registry, REST adapter и observability получают только typed values. Production environment reads за пределами `crank-config` запрещены executable boundary gate. +- Machine schema, `.env` sections и runtime reference генерируются из Rust registry. Root/community Compose, docs, CI, release и `just verify` синхронизированы drift checker-ом; phantom WINDOW/JOBS и ignored MCP storage injection удалены, no-effect cache TTL fail-closed. +- Test evidence after review patches: 23 `crank-config` tests, invalid/type/conflict startup matrices для обоих binaries, 99 Python tooling tests, three Compose `config -q` validations, repository-wide 492-file Community scan, strict Clippy and full workspace test suite. +- Code review закрыт полностью: 16/16 adversarial findings исправлены; добавлены process applicability, pre-side-effect consumer validation, semantic diagnostics, bounded UTF-8 JSON, hardened Compose/Rust boundary checkers и normalized privacy-safe fingerprints. +- Real minimal PostgreSQL/Admin/MCP startup reached green readiness; authenticated REST→MCP create/test/publish/bind/initialize/list/call smoke passed. `just verify`, dependency/security audit (0 vulnerabilities), fmt, strict workspace Clippy, all workspace tests and `git diff --check` passed with no skip/flaky/missing evidence. +- Cargo/npm/toolchain audit: Story 1.3 adds only the local `crank-config` workspace/path entries and reuses already locked dependencies; no npm/toolchain or registry-version change was introduced by this Story. The pre-existing owner-approved Story 1.1 `event-listener` lock remediation remains preserved. +- Docker evidence: `crank/admin-api:dev`, `crank/mcp-server:dev` и `crank/ui:dev` собраны параллельно через системный Docker Buildx 0.36.0. Холодный build выявил и подтвердил исправление cross-service Cargo cache race; повторный полный Compose build прошёл из кэша за 12.1 секунды. + +### File List + +- `.env.example` +- `.gitea/workflows/ci.yml` +- `.gitea/workflows/release.yml` +- `CONTRIBUTING.md` +- `Cargo.lock` +- `Cargo.toml` +- `README.md` +- `apps/admin-api/Cargo.toml` +- `apps/admin-api/Dockerfile` +- `apps/admin-api/src/main.rs` +- `apps/admin-api/tests/config_startup.rs` +- `apps/mcp-server/Cargo.toml` +- `apps/mcp-server/Dockerfile` +- `apps/mcp-server/src/main.rs` +- `apps/mcp-server/tests/config_startup.rs` +- `crates/crank-adapter-rest/src/client.rs` +- `crates/crank-config/Cargo.toml` +- `crates/crank-config/src/bin/crank-config-contract.rs` +- `crates/crank-config/src/diagnostic.rs` +- `crates/crank-config/src/debug.rs` +- `crates/crank-config/src/fingerprint.rs` +- `crates/crank-config/src/lib.rs` +- `crates/crank-config/src/process.rs` +- `crates/crank-config/src/render.rs` +- `crates/crank-config/src/schema.rs` +- `crates/crank-config/src/source.rs` +- `crates/crank-config/src/value.rs` +- `crates/crank-config/tests/contract.rs` +- `crates/crank-config/tests/generation.rs` +- `crates/crank-config/tests/redaction.rs` +- `crates/crank-observability/src/config.rs` +- `crates/crank-observability/src/error_reporting.rs` +- `crates/crank-observability/src/lifecycle.rs` +- `crates/crank-observability/src/otlp.rs` +- `crates/crank-observability/src/prometheus.rs` +- `crates/crank-registry/src/postgres/pool_config.rs` +- `crates/crank-runtime/src/cache.rs` +- `crates/crank-runtime/src/executor_builder.rs` +- `crates/crank-runtime/src/lib.rs` +- `crates/crank-runtime/src/limits.rs` +- `crates/crank-runtime/tests/unit/cache.rs` +- `deploy/community/.env.example` +- `deploy/community/.env.images.example` +- `deploy/community/docker-compose.images.yml` +- `deploy/community/docker-compose.yml` +- `docker-compose.yml` +- `docs/README.md` +- `docs/en/README.md` +- `docs/runtime-config.md` +- `docs/schemas/runtime-config.schema.json` +- `justfile` +- `scripts/README.md` +- `scripts/check-config-boundaries.py` +- `scripts/check-runtime-config.py` +- `scripts/check-rust-boundaries.py` +- `scripts/check-rust-module-boundaries.sh` +- `tests/unit/test_check_config_boundaries.py` +- `tests/unit/test_check_runtime_config.py` +- `tests/unit/test_check_rust_boundaries.py` +- `_bmad-output/project-context.md` (local ignored update only) + +## Change Log + +- 2026-08-09: Implemented Story 1.3 typed configuration foundation, migrated all current process consumers, generated/checked deployment contracts, added CI/release boundaries, passed real REST→MCP smoke and moved Story to review. +- 2026-08-09: Addressed all 16 adversarial review findings, reran contract/Compose/security/full workspace gates and moved Story to done. +- 2026-08-09: Installed-system Buildx evidence completed; fixed parallel Admin/MCP Cargo cache collision with per-service cache IDs, built all Community images, and verified a 12.1-second fully cached repeat build. diff --git a/_bmad-output/implementation-artifacts/1-4-versioned-migration-authority.md b/_bmad-output/implementation-artifacts/1-4-versioned-migration-authority.md new file mode 100644 index 0000000..6f5fbf2 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-4-versioned-migration-authority.md @@ -0,0 +1,358 @@ +--- +baseline_commit: c30461cc92491ebe3d527e125a1657b73fa67006 +--- + +# Story 1.4: Учредить versioned migration authority + +Status: done + +## Story + +As an оператор, +I want безопасный механизм последовательного изменения schema, +so that новые capability tables добавляются без изменения выпущенного baseline. + +## Strategic Intent + +Story 1.4 завершает четвёртый элемент Wave 0 foundation. Она не добавляет пользовательскую capability, а делает все будущие durable capabilities безопасными: одна authority владеет DDL, выпущенная схема не переписывается, startup не мутирует БД, а несовместимое состояние диагностируется до readiness. После этой Story Resources, Prompts, Tasks, traces и Load Runs могут добавлять append-only migrations, не создавая новых независимых ledger/runner. + +**Requirement:** FR-43 +**Architecture:** AD-16 +**Applicable NFR:** NFR-R2, NFR-S2, NFR-S4, NFR-S7, NFR-S8, NFR-C1, NFR-C3. + +## Acceptance Criteria + +1. **Единая authority и immutable baseline** + - Given brownfield migration inventory + - When определяется canonical runner + - Then `crank-registry` является единственным владельцем migration sequence и DDL + - And существующий core baseline version `1`, ledger checksum `crank-community-baseline-v1`, его SQL/данные и порядок не изменяются + - And legacy core, MCP-session и `RegistryExtension` ledgers полностью инвентаризируются и сверяются до первой committed mutation. + +2. **Append-only checksummed sequence** + - Given новая schema migration + - When owning Story добавляет durable field/table + - Then она получает уникальную monotonic `i64` version, стабильное имя, lowercase SHA-256 exact source bytes, phase `expand|migrate|contract` и compatibility metadata + - And sequence не допускает duplicate/gap/reorder, неизвестную phase, non-transactional DDL или изменение checksum опубликованной version + - And каждое применение выполняется одной transaction под одним canonical PostgreSQL transaction-level advisory lock. + +3. **Controlled migration command, read-only startup** + - Given fresh, legacy либо outdated database + - When запускаются `admin-api` или `mcp-server` + - Then они выполняют только read-only compatibility verification и не создают/изменяют table, ledger, index или data row + - And DDL применяет только отдельная команда `crank-migrate`, использующая database-only typed config projection без Admin/MCP/session/master-key/bootstrap secrets + - And Community Compose запускает migration job до обоих сервисов и допускает их startup только после успешного завершения job. + +4. **Brownfield consolidation без потери данных** + - Given database с любым допустимым сочетанием legacy core v1, MCP-session v1 и extension ledger + - When controlled migration выполняет consolidation + - Then authority сохраняет legacy ledgers readable, переносит проверенное происхождение в canonical audit и добавляет checksum extension entries + - And существующие workspace, Operation, Agent, key, approval, history, session и extension data сохраняются byte/row-equivalent + - And отсутствие legacy ledger отличается от повреждённого/неизвестного ledger и обрабатывается детерминированно. + +5. **Fail-closed preflight и recovery contract** + - Given partial sequence, checksum mismatch, unknown/future version, missing applied version, modified legacy ledger либо incompatible phase/window + - When preflight/startup/controlled migration проверяет schema + - Then процесс завершается до product listener/readiness с bounded safe diagnostic: stable code, stage, version и recovery action + - And diagnostic не содержит database URL, credentials, raw SQL, row values, host paths или unbounded driver error + - And automatic destructive rollback, down migration, ledger rewrite и `--force` bypass отсутствуют. + +6. **Expand/migrate/contract и N/N-1 foundation** + - Given future storage evolution + - When migration plan объявляется + - Then contract требует `expand → bounded/resumable migrate/backfill → contract`, owner и explicit N/N-1 readable window + - And `contract` migration не может быть применена без закрытого compatibility window/evidence + - And Story 1.4 создаёт executable metadata/guardrails, но не заявляет полную upgrade/rollback qualification Story 7.2. + +7. **PostgreSQL 16 evidence** + - Given canonical runner suite + - When проверяются fresh, legacy baseline, legacy MCP sessions, already-current, repeated, concurrent, checksum-corrupt, partial, future-version и injected-failure states + - Then sequence, checksums, audit и diagnostics детерминированы; repeated apply idempotent; concurrent runners сериализованы + - And injected DDL/ledger failure полностью откатывает transaction и сохраняет pre-existing data + - And app startup tests доказывают отсутствие mutation, а controlled command доказывает migration-before-readiness. + +8. **Regression и release gates** + - Given завершённая реализация + - When выполняются targeted tests и repository gates + - Then проходят migration contract/unit/integration tests, PostgreSQL 16 fresh/brownfield/concurrency suites, Compose config, Community REST→MCP smoke и `just verify` + - And baseline v1 checksum/source guard, Cargo/npm/toolchain/wire audit и explicit Community scope scan проходят без unrelated dependency/version changes. + +## Non-goals + +- Не реализовывать backup/PITR, master-key restore/rotation, drain/restart upgrade, full N/N-1 qualification или destructive contract migration: это Stories 7.2 и 7.7–7.9. +- Не добавлять таблицы Resources, Prompts, Tasks, traces или Load Runs; Story создаёт authority для будущих owning stories. +- Не использовать SQLx `_sqlx_migrations` как четвёртый ledger и не вводить второй migration framework. SQLx 0.9 остаётся PostgreSQL transport; canonical contract принадлежит `crank-registry`. +- Не менять HTTP/MCP/UI wire contracts и не добавлять UI. +- Не удалять legacy ledgers после consolidation и не изменять существующий baseline v1 ради упрощения реализации. + +## Tasks / Subtasks + +- [x] Task 1 — Зафиксировать brownfield inventory и immutable baseline guard (AC: 1, 4, 8) + - [x] Перечислить фактические ledgers: `__crank_core_migrations`, `__crank_mcp_migrations`, `__crank_ext_migrations`; их columns, locks, known versions/checksums и owning code. + - [x] Перенести baseline v1 в изолированный модуль без изменения SQL statement sequence и ledger checksum. + - [x] Добавить executable source digest/contract test, который блокирует любое изменение baseline SQL при сохранённом ledger checksum. + - [x] Зафиксировать legacy MCP v1 checksum `mcp-transport-sessions-v1`; extension row без сопоставимой зарегистрированной migration считать incompatible, не выдумывать checksum. + +- [x] Task 2 — Создать canonical migration model в `crank-registry` (AC: 1, 2, 5, 6) + - [x] Ввести закрытые typed descriptors: version/name/source checksum/phase/compatibility/backfill policy. + - [x] Валидировать sequence до DB I/O: strictly increasing contiguous versions, unique names, SHA-256 format, transactional-only, bounded metadata. + - [x] Ввести typed `MigrationStatus`, `MigrationPreflight`, `MigrationDiagnostic` и stable codes минимум для `schema_missing`, `migration_required`, `checksum_mismatch`, `partial_sequence`, `future_version`, `legacy_conflict`, `lock_timeout`, `apply_failed`. + - [x] Display/JSON diagnostics должны быть deterministic, valid UTF-8/JSON, ≤65,536 bytes и не отражать raw SQL/DB/driver values. + +- [x] Task 3 — Реализовать canonical runner и consolidation migration (AC: 1, 2, 4–6) + - [x] Использовать один постоянный 64-bit lock ID и `pg_advisory_xact_lock`; lock живёт ровно до commit/rollback transaction. + - [x] До mutation собрать полный legacy/canonical snapshot; любой conflict завершает transaction без committed DDL. + - [x] На fresh DB применить неизменный baseline v1, затем consolidation v2; на legacy DB импортировать проверенный v1 без повторного baseline DDL. + - [x] V2 создаёт canonical append-only ledger/audit, переносит verified legacy provenance, централизует MCP session schema и оставляет legacy ledgers readable. + - [x] Повторный запуск не меняет audit timestamps/rows; unknown/future/corrupt state не нормализуется автоматически. + - [x] Backfill API должен быть bounded/resumable по cursor+batch и транзакционным на batch; v2 не должен выполнять unbounded product-data backfill. + +- [x] Task 4 — Удалить schema writes из runtime paths (AC: 3–5) + - [x] `PostgresRegistry::connect*` создаёт pool и вызывает только compatibility verifier; `migrate()`/implicit apply из service-facing API удалить. + - [x] `PostgresTransportSessionStore::from_pool/connect*` только проверяет canonical compatibility/session schema; локальный MCP runner удалить. + - [x] `apply_extension_migrations` больше не исполняет DDL; extension migrations регистрируются через canonical authority с обязательным checksum/metadata. + - [x] Boundary gate должен находить прямые schema writes/legacy runners за пределами canonical migration module, включая новые и untracked Rust files. + +- [x] Task 5 — Добавить controlled `crank-migrate` command (AC: 3, 5) + - [x] Добавить отдельный binary edge в package `admin-api` либо отдельный minimal app; production choice: binary `crank-migrate`, authority остаётся в `crank-registry`. + - [x] Расширить `crank-config` process enum database-only projection `Migrator`; не требовать master/session/bootstrap/MCP secrets и не добавлять новый env reader. + - [x] Поддержать только `preflight`, `plan` и `apply`; default — `preflight`, mutation требует явного `apply`. Не добавлять `down`, `force`, arbitrary SQL/path input. + - [x] Exit codes и stdout/stderr machine contract детерминированы; secret/error redaction проверяется canary tests. + +- [x] Task 6 — Встроить migration job в Community deployment (AC: 3, 8) + - [x] Admin image содержит `crank-migrate`; root и `deploy/community` Compose используют one-shot job с restart disabled и health/dependency gate. + - [x] `admin-api` и `mcp-server` зависят от `service_completed_successfully`; они не получают authority выполнять DDL самостоятельно. + - [x] Images profile сохраняет те же semantics; минимальный deployment остаётся PostgreSQL-only корректным. + - [x] CI/release выполняют contract/preflight/fresh+brownfield migration tests до image smoke/package publication. + +- [x] Task 7 — Документировать operator contract (AC: 5, 6, 8) + - [x] Создать `docs/migrations.md`: inventory, `preflight → backup → apply → verify`, failure codes, recovery without rollback, append-only authoring rules. + - [x] Обновить deployment/runtime/contributor/scripts docs и RU/EN indexes; не заявлять готовность Story 7.2/backup/upgrade. + - [x] Зафиксировать machine-readable canonical sequence/metadata, generated или checked из Rust authority; handwritten duplicate table запрещена. + +- [x] Task 8 — Реализовать test matrix и evidence (AC: 7, 8) + - [x] Pure tests: descriptor validation, digest exactness, ordering/gaps/duplicates/phases/windows, bounded/redacted diagnostics. + - [x] PostgreSQL 16: fresh, baseline-only, legacy MCP, extension mapping, current/repeat, concurrent, corrupt checksum, partial/future, rollback after injected failure, data preservation. + - [x] App/CLI subprocess: empty/outdated/corrupt startup performs zero DDL; migrate command uses only DB config; no listener readiness before compatible schema. + - [x] Compose: root/source/images config and real migration-job ordering; authenticated REST→MCP smoke remains green. + - [x] Final: `cargo fmt --all --check`, strict Clippy, `just verify`, `git diff --check`, explicit scan of every NEW/UPDATE path, no skipped/flaky/missing acceptance evidence. + +### Review Findings + +- [x] [Review][Patch] Включить все version-specific mutations v2 в exact-byte source bundle и независимо закрепить digest опубликованных migrations, чтобы одновременное изменение Rust/SQL и generated JSON не проходило append-only gate [crates/crank-registry/src/migrations/authority.rs:158] +- [x] [Review][Patch] Считать fresh только БД без любой owned relation; проверять canonical schema fingerprint (schema/relkind/columns/types/nullability/defaults/constraints/indexes), включая orphan MCP ledger/session states и current-schema qualification [crates/crank-registry/src/migrations/authority.rs:361] +- [x] [Review][Patch] Ввести закрытый registry legacy extension descriptors с exact `(name, version, checksum)` mapping и восстановить безопасный canonical registration path вместо принятия произвольного 64-hex provenance [crates/crank-registry/src/migrations/authority.rs:552] +- [x] [Review][Patch] Проверять core/canonical/legacy audit metadata и конфликтующие audit rows до mutation; заменить безусловный `ON CONFLICT DO NOTHING` на exact-equality semantics и ограничить ledger reads [crates/crank-registry/src/migrations/authority.rs:407] +- [x] [Review][Patch] Связать executable migration implementations с descriptors обобщённым dispatch/registry, чтобы append v3 не мог пройти contract validation и остаться невыполненным [crates/crank-registry/src/migrations/authority.rs:197] +- [x] [Review][Patch] Сделать compatibility window и contract evidence типизированными и исполнимыми; добавить bounded cursor+batch resumable backfill contract без заявления полной Story 7.2 qualification [crates/crank-registry/src/migrations/authority.rs:47] +- [x] [Review][Patch] Сохранить optional migration `version` в CLI JSON, реализовать/согласовать `schema_missing`, различать настоящий lock timeout от storage failure и нормализовать любые startup/SQLx errors в bounded safe diagnostics [apps/admin-api/src/bin/crank-migrate.rs:18] +- [x] [Review][Patch] Усилить PostgreSQL evidence: настоящий rollback при первом v2 DDL на v1, representative brownfield row equivalence и Admin/MCP subprocess snapshots для fresh/outdated/corrupt DB без mutation/listener [crates/crank-registry/tests/integration/migrations.rs:272] +- [x] [Review][Patch] Вызывать `MigrationAuthority::validate_sequence()` в `crank-migrate plan/--check`, чтобы синхронно повреждённые Rust descriptors и JSON не проходили gate [apps/admin-api/src/bin/crank-migrate.rs:73] +- [x] [Review][Patch] Исправить/удалить dead Docker dependency stage, проверить clean `--target deps`, и включить `crank-migrate` в binary release artifact/checksums [apps/admin-api/Dockerfile:1] +- [x] [Review][Patch] Ввести настоящий database-only config scope для migrator, строго согласовать URL-vs-POSTGRES components с Compose и валидировать host/database/user до любых side effects [crates/crank-config/src/migrator.rs:23] +- [x] [Review][Patch] Расширить sole-DDL-owner gate на все PostgreSQL schema-changing forms, SQL assets, include/concat/sqlx migration markers и canonical/legacy ledger writers; добавить negative fixtures для tracked/untracked paths [scripts/check-rust-module-boundaries.sh:56] +- [x] [Review][Patch] Закрыть обходы env boundary через grouped aliases, build.rs/non-src production targets и symlinks; default scan должен fail closed [scripts/check-config-boundaries.py:34] +- [x] [Review][Patch] Проверять root/source/images Compose в CI и release и блокировать publication fresh PostgreSQL-16 image-stack smoke с доказанным `migrate -> readiness` ordering [.gitea/workflows/release.yml:121] +- [x] [Review][Patch] Добавить bounded retry/backoff для one-shot migrator и сделать документированный source Compose deployment работоспособным с локальным либо явно обязательным external PostgreSQL [deploy/community/docker-compose.yml:18] +- [x] [Review][Patch] Переписать migration runbook на исполнимые source/Compose commands и порядок `preflight -> verified backup -> apply -> verify`, документировать exit 2 и полный stable-code/recovery contract [docs/migrations.md:5] +- [x] [Review][Patch] Добавить factual brownfield inventory трёх legacy ledgers: columns, historical locks, known versions/checksums, owners и legacy extension shape без выдуманного provenance [docs/migrations.md:16] +- [x] [Review][Patch] Убрать опасные обещания автоматического image rollback после schema migration и совет немедленно восстанавливать БД при checksum mismatch; сначала проверять immutable application/release match [docs/deployment.md:187] +- [x] [Review][Patch] Отразить one-shot migrate job в deployment topology, добавить английский operator contract либо явно маркировать RU-only ссылку и исправить дублирующий heading scripts docs [docs/deployment.md:5] +- [x] [Review][Patch] Исправить acceptance bookkeeping: отметить фактически выполненные subtasks, снять ложные completion claims, явно просканировать все NEW/UPDATE paths и записать точные evidence commands/results [1-4-versioned-migration-authority.md:88] +- [x] [Review][Defer] Не включать предшествующее owner-approved изменение `event-listener` в scope Story 1.4; явно атрибутировать его baseline Story 1.1 [Cargo.lock:1113] — deferred, pre-existing + +## Dev Notes + +### Current Brownfield State + +- `crates/crank-registry/src/migrations.rs` owns a 721-line baseline function, advisory lock `0x43_52_41_4E_4B`, ledger `__crank_core_migrations`, version `1`, checksum `crank-community-baseline-v1`. It currently performs DDL from every `PostgresRegistry::connect*` call. +- `crates/crank-community-mcp/src/session.rs` independently owns lock `0x4352_414E_4B4D_4350`, ledger `__crank_mcp_migrations`, checksum `mcp-transport-sessions-v1`, and applies session DDL from store construction. +- `crates/crank-registry/src/ext.rs` owns a third ledger without checksum/advisory lock and executes caller-provided SQL. +- Both service binaries currently bind metrics before registry compatibility is known. Story must ensure product readiness/listeners never start on incompatible schema; migration diagnostics must remain safe even if the pool connection succeeds. +- Existing tests assume connect-implies-migrate. Update shared test setup to call canonical authority explicitly; do not add an implicit `connect_and_migrate` production escape hatch. + +### Required Design Decisions + +- Canonical sequence source of truth: Rust static descriptors and embedded SQL owned only by `crank-registry`; committed machine reference is generated/checked from it. +- Preserve published v1 ledger checksum exactly. Add separate actual SHA-256 source digest guard rather than replacing the legacy token. +- Consolidation is the first new canonical version and is expand-only. It may create canonical metadata/session schema but must not delete/rename legacy ledger or product table. +- PostgreSQL transaction-level advisory lock is required because it is automatically released on commit/rollback; do not use session locks or per-ledger IDs. +- SQLx 0.9 migration types/checksum support may inform implementation, but do not adopt `_sqlx_migrations` or add a second authority. Current workspace dependencies and Rust 1.96.1 remain fixed. + +### Stable Diagnostic Contract + +- Diagnostic fields: `code`, `stage`, optional numeric `version`, `recovery`; never raw SQL, driver string, database URL, schema content or row values. +- Suggested recovery values are static: `run_preflight`, `run_controlled_migration`, `restore_known_good_backup`, `install_matching_application`, `contact_operator`. +- `migration_required` is expected operator state, not compatibility pass. Admin/MCP still fail startup until controlled apply completes. +- Database transport errors are normalized to a bounded category; raw SQLx chains remain internal and must not reach Display/JSON/stderr. + +### File Map + +**Likely NEW** + +- `crates/crank-registry/src/migrations/baseline_v1.rs` +- `crates/crank-registry/src/migrations/authority.rs` +- `crates/crank-registry/src/migrations/contract.rs` +- `apps/admin-api/src/bin/crank-migrate.rs` +- `apps/admin-api/tests/migration_command.rs` +- `docs/migrations.md` +- `docs/schemas/migration-sequence.json` +- migration boundary checker/tests if existing Rust boundary checker cannot express sole-owner rule. + +**Likely UPDATE** + +- `crates/crank-registry/src/migrations.rs` or replace with `migrations/mod.rs` +- `crates/crank-registry/src/{lib.rs,ext.rs,error.rs}` and `src/postgres/connection.rs` +- `crates/crank-registry/tests/integration/{migrations.rs,common.rs}` +- `crates/crank-community-mcp/src/session.rs` and session integration tests +- `crates/crank-config/src/{schema.rs,process.rs,render.rs,lib.rs}` and contract/generation/redaction tests +- `apps/admin-api/src/main.rs`, `apps/mcp-server/src/main.rs`, their test common/startup suites and Cargo manifests as required +- `apps/admin-api/Dockerfile`, root/community source+images Compose files +- `justfile`, CI/release workflows, boundary scripts/tests +- `docs/{README.md,en/README.md,intro.md,deployment.md,runtime-config.md}`, `CONTRIBUTING.md`, `scripts/README.md` +- local ignored `_bmad-output/project-context.md`; do not force-add. + +**Must not change** + +- Rust/MSRV/Edition/base image versions, npm dependencies, HTTP/MCP payloads, UI bundles, existing product table semantics. +- Baseline v1 ledger checksum or statement behavior; no unrelated Cargo registry dependency update. + +### Testing Commands + +```bash +cargo test -p crank-registry --test integration migrations -- --nocapture +cargo test -p crank-community-mcp --test integration session -- --nocapture +cargo test -p admin-api --test migration_command -- --nocapture +cargo test -p admin-api --test config_startup +cargo test -p mcp-server --test config_startup +cargo run -p admin-api --bin crank-migrate -- plan +cargo run -p admin-api --bin crank-migrate -- preflight +docker compose -f docker-compose.yml config -q +docker compose -f deploy/community/docker-compose.yml --env-file deploy/community/.env.example config -q +docker compose -f deploy/community/docker-compose.images.yml --env-file deploy/community/.env.images.example config -q +PATH="$HOME/.cargo/bin:$PATH" just authenticated-product-smoke http://localhost:3000 +PATH="$HOME/.cargo/bin:$PATH" just verify +git diff --check +``` + +### Previous Story Intelligence + +- Story 1.3 established `crank-config` as the sole environment reader. Migrator must extend this registry/projection; reading `DATABASE_URL` or `std::env` directly in the new binary is forbidden. +- Config and diagnostics must validate before observability/listener side effects. Reuse bounded RU/EN diagnostic and secret wrapper patterns. +- Docker parallel builds now use service-specific BuildKit Cargo cache IDs; preserve them. +- Story 1.3 passed full workspace, strict Clippy, Compose, real PostgreSQL readiness and authenticated REST→MCP smoke. Story 1.4 must retain this evidence and must not mark missing Docker/PostgreSQL checks as pass. +- Existing worktree includes Stories 1.1–1.3 changes. Preserve unrelated changes; no reset/checkout/lockfile regeneration outside the Story. + +### Latest Technical Notes + +- PostgreSQL transaction-level advisory locks are automatically released at transaction end; `pg_advisory_xact_lock(bigint)` waits for an exclusive application-defined lock. This matches short controlled migration transactions and avoids manual unlock leakage. +- SQLx 0.9 exposes migration versions/checksums and warns that disabling locking can cause errors or data loss. This Story retains a project-owned `crank-registry` sequence rather than delegating authority to SQLx’s default ledger. + +### References + +- [Source: `_bmad-output/planning-artifacts/epics.md` — Wave 0, Epic 1, Story 1.4, FR-43, AR-16, AR-34] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` — FR-43, NFR-R2, NFR-C1/C3] +- [Source: `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` — AD-16, AD-17, AD-18] +- [Source: `_bmad-output/implementation-artifacts/1-3-typed-configuration-foundation.md` — completion/review lessons] +- [Source: `_bmad-output/project-context.md` — migrations, tests, deployment, secrets, environment boundaries] +- [Source: `crates/crank-registry/src/migrations.rs`, `crates/crank-registry/src/ext.rs`, `crates/crank-registry/src/postgres/connection.rs`] +- [Source: `crates/crank-community-mcp/src/session.rs`] +- [PostgreSQL 18 advisory lock functions](https://www.postgresql.org/docs/current/functions-admin.html) +- [PostgreSQL 16 explicit/advisory locking](https://www.postgresql.org/docs/16/explicit-locking.html) +- [SQLx 0.9 Migrator](https://docs.rs/sqlx/0.9.0/sqlx/migrate/struct.Migrator.html) + +## Dev Agent Record + +### Agent Model Used + +GPT-5 Codex + +### Debug Log References + +- `just verify` initially exposed unbounded parallel Admin integration contention; all four apparent stragglers passed independently, and the complete 30-test suite passed in 68–71 seconds with bounded execution. Local, CI and release gates now use `--test-threads=1` for deterministic resource use. +- The first real-stack smoke correctly failed at `operation_test` because the default SSRF policy denies private upstreams. Re-running with the explicit test-only allowlist `CRANK_OUTBOUND_ALLOWED_HOSTS=admin-api` completed the full REST→MCP path without weakening production defaults. +- An early immutable-source guard hashed the migration module wrapper and produced a false drift finding. Baseline v1 was isolated into `baseline_v1.rs`; the guard now hashes only the marked immutable baseline body. + +### Implementation Plan + +- Сначала закрепить RED regression tests для immutable v1, canonical sequence, legacy consolidation и read-only startup. +- Затем выделить migration authority внутри `crank-registry`, централизовать MCP/extension schema ownership и добавить database-only migrator edge. +- После green targeted suites встроить one-shot migration job в Compose/CI, обновить operator contract и выполнить полный PostgreSQL/Docker regression. + +### Completion Notes List + +- Ultimate context engine analysis completed - comprehensive developer guide created. +- Established `crank-registry::MigrationAuthority` as the sole DDL owner with a validated contiguous checksummed sequence, immutable isolated baseline v1 and transactional consolidation v2. +- Removed implicit core, MCP-session and extension schema writers from runtime paths. Admin and MCP now perform read-only compatibility verification and fail closed before metrics/product listeners on incompatible schema. +- Added the database-only `crank-migrate` edge (`plan`, `preflight`, `apply` only), safe bounded JSON diagnostics, a committed machine sequence contract and direct CI/release drift gates. +- Consolidated verified legacy core/MCP/extension provenance without deleting legacy ledgers; added schema-presence validation, future/partial/corrupt detection, bounded lock wait and transactional rollback evidence. +- Added one-shot migration jobs to root/source/images Community Compose profiles; real fresh-stack evidence proved migration `0 → 2` precedes healthy Admin/MCP startup. +- Real authenticated smoke passed create → test → publish Operation → publish Agent → MCP initialize/list/call. All generated credentials and test volumes were ephemeral and removed after the run. +- Все 20 actionable code-review findings закрыты; единственный deferred пункт относится к ранее одобренному изменению lockfile из Story 1.1 и не входит в scope Story 1.4. +- `just verify` passed in full with 103 Python tests, strict Clippy, dependency/security audit and the complete sequential Rust workspace. Explicit Community scope passed for all 91 NEW/UPDATE paths; all three Community images built successfully with Buildx. +- No user blocker remains and no production HTTP/MCP/UI wire contract, Rust toolchain version or dependency version was changed by Story 1.4. + +### File List + +- `.gitea/workflows/ci.yml` +- `.gitea/workflows/release.yml` +- `CONTRIBUTING.md` +- `apps/admin-api/Cargo.toml` +- `apps/admin-api/Dockerfile` +- `apps/admin-api/src/bin/crank-migrate.rs` +- `apps/admin-api/src/error.rs` +- `apps/admin-api/src/main.rs` +- `apps/admin-api/tests/integration/common.rs` +- `apps/admin-api/tests/config_startup.rs` +- `apps/admin-api/tests/migration_command.rs` +- `apps/mcp-server/Cargo.toml` +- `apps/mcp-server/Dockerfile` +- `apps/mcp-server/src/main.rs` +- `apps/mcp-server/tests/config_startup.rs` +- `apps/mcp-server/tests/integration/common.rs` +- `crates/crank-community-mcp/src/session.rs` +- `crates/crank-community-mcp/tests/integration/session.rs` +- `crates/crank-config/src/debug.rs` +- `crates/crank-config/src/lib.rs` +- `crates/crank-config/src/migrator.rs` +- `crates/crank-config/src/process.rs` +- `crates/crank-config/src/schema.rs` +- `crates/crank-config/src/source.rs` +- `crates/crank-config/src/validation.rs` +- `crates/crank-config/tests/contract.rs` +- `crates/crank-registry/src/error.rs` +- `crates/crank-registry/src/ext.rs` +- `crates/crank-registry/src/lib.rs` +- `crates/crank-registry/src/migrations.rs` +- `crates/crank-registry/src/migrations/authority.rs` +- `crates/crank-registry/src/migrations/baseline_v1.rs` +- `crates/crank-registry/src/migrations/consolidation_v2.sql` +- `crates/crank-registry/src/migrations/schema_guard.rs` +- `crates/crank-registry/src/postgres/connection.rs` +- `crates/crank-registry/tests/integration/common.rs` +- `crates/crank-registry/tests/integration/migrations.rs` +- `deploy/community/docker-compose.images.yml` +- `deploy/community/docker-compose.yml` +- `docker-compose.yml` +- `docs/README.md` +- `docs/deployment.md` +- `docs/en/README.md` +- `docs/en/migrations.md` +- `docs/intro.md` +- `docs/migrations.md` +- `docs/runtime-config.md` +- `docs/schemas/migration-sequence.json` +- `justfile` +- `scripts/README.md` +- `scripts/check-config-boundaries.py` +- `scripts/check-migration-boundaries.py` +- `scripts/check-rust-module-boundaries.sh` +- `tests/unit/test_check_config_boundaries.py` +- `tests/unit/test_check_migration_boundaries.py` +- `_bmad-output/project-context.md` (local ignored update only) + +## Change Log + +- 2026-08-09: Story 1.4 created with canonical migration authority, brownfield consolidation, read-only startup, controlled command and PostgreSQL 16 evidence contract. +- 2026-08-09: Implemented Story 1.4, passed PostgreSQL/Compose/Buildx/real REST→MCP/full repository gates and moved the Story to review. +- 2026-08-10: Closed all 20 actionable review findings, strengthened rollback/schema/boundary/release evidence, reran full verification and moved Story 1.4 to done. diff --git a/_bmad-output/implementation-artifacts/1-5-canonical-request-trace-identity.md b/_bmad-output/implementation-artifacts/1-5-canonical-request-trace-identity.md new file mode 100644 index 0000000..aae8333 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-5-canonical-request-trace-identity.md @@ -0,0 +1,415 @@ +--- +baseline_commit: c30461cc92491ebe3d527e125a1657b73fa67006 +--- + +# Story 1.5: Ввести canonical request и trace identity + +Status: done + +## Story + +As an оператор поддержки, +I want получать Request ID и Trace ID на существующих ingress/runtime paths, +so that все последующие capabilities наследуют correlation по готовому contract. + +## Strategic Intent + +Story 1.5 завершает correlation foundation Wave 0. Она отделяет локальную product identity от внешнего telemetry backend: Request ID и Trace ID существуют, возвращаются и сохраняются даже при отключённом OTLP, sampling-off или недоступном exporter. После этой Story синхронный REST → MCP путь диагностируется локально по двум разным идентификаторам, а последующие Tasks, Resources, Prompts и Load Runs получают готовый typed parent-context contract. + +Story не заявляет, что trace уже доступен в GlitchTip. Поиск/copy/deep-link в UI, browser spans, GlitchTip performance delivery и durable telemetry spool принадлежат Epic 5. + +**Requirement:** FR-27 +**Architecture:** AD-11; применимые AD-12, AD-19, AD-20, AD-21 +**Applicable NFR:** NFR-O1, NFR-S2, NFR-S4, NFR-S6, NFR-S8, NFR-O4, NFR-O5, NFR-C1; NFR-C4 только при появлении нового пользовательского текста. + +## Acceptance Criteria + +1. **Отдельные canonical identities на каждом ingress** + - Given UI-originated Admin API request, любой Admin API ingress либо MCP Streamable HTTP ingress + - When отсутствуют IDs, `x-request-id`/`traceparent` malformed, oversized либо представлены неоднозначными duplicate values + - Then локально создаются отдельные typed Request ID и canonical W3C Trace ID + - And локально созданный Request ID является UUIDv7, Trace ID — 32 lowercase hex, не all-zero, и они никогда не используются вместо друг друга + - And response headers и safe boundary error возвращают один и тот же локальный `x-request-id` и `x-trace-id`, не отражая rejected input. + +2. **Совместимый Request ID и строгий W3C parent** + - Given ровно один syntactically valid bounded `x-request-id` + - When ingress формирует context + - Then текущее совместимое opaque значение сохраняется как Request ID; missing/rejected значение заменяется UUIDv7 + - And валидный `traceparent` продолжает его Trace ID новым local span, а invalid parent создаёт новый local root trace + - And JSON-RPC `id`, legacy `x-correlation-id`, database Execution ID и Request ID остаются разными контрактами. + +3. **Независимость от sampling и exporter** + - Given OTLP unset, exporter unavailable либо local sampler не записывает span + - When Admin/MCP request проходит ingress + - Then процесс всё равно создаёт валидный local Trace ID до application logic + - And response, boundary error, runtime context, structured logs и новый Invocation record получают этот ID + - And отсутствие telemetry export не меняет product response или readiness после успешного startup. + +4. **Сквозное synchronous propagation** + - Given validated ingress correlation context + - When Admin test либо MCP Tool call проходит service → `RuntimeExecutionRequest` → runtime → REST adapter → upstream + - Then typed Request ID и TraceContext передаются явно, а spans продолжают одну trace topology + - And upstream получает system-owned `x-request-id` и W3C `traceparent` + - And static/mapped/user headers и upstream response не могут заменить `x-request-id`, `x-trace-id`, legacy `x-correlation-id`, `traceparent`, `tracestate` или `baggage`. + +5. **Bounded trust policy** + - Given incoming `traceparent`, `tracestate` или `baggage` + - When headers проверяются + - Then ровно один `traceparent` строго валидируется по W3C; duplicate, malformed, non-canonical, zero-ID и oversized варианты отклоняются без echo + - And `tracestate` ограничен 512 bytes и 32 members, но caller state не пересылается наружу по умолчанию + - And `baggage` имеет input budget 8192 bytes/64 members и пустую Community allowlist, поэтому user baggage не извлекается и не пересылается; rejected reason остаётся закрытым low-cardinality enum, а не raw value. + +6. **Durable Invocation identity и совместимая migration v3** + - Given новый Admin test или MCP Tool Execution + - When Invocation History сохраняется + - Then новый record содержит обязательные для application write Request ID и Trace ID независимо от sampling + - And fresh/v2 databases переходят через новую append-only checksummed migration v3 под `MigrationAuthority`; immutable v1/v2 source/digests не меняются + - And legacy rows остаются читаемыми с честным nullable Trace ID, без fabricated backfill, а schema fingerprint валидируется относительно фактически applied version. + +7. **Safe logs, events и errors** + - Given success, auth/validation/rate-limit rejection, upstream failure, runtime error либо history-write loss + - When формируются logs, audit/error events и boundary payloads + - Then canonical IDs присутствуют только в bounded validated correlation fields + - And credentials, cookies, mapped headers, raw trace inputs, payloads, URLs и driver causes не отражаются + - And Request/Trace/Correlation IDs никогда не используются как Prometheus labels или dynamic event names. + +8. **Future durable boundary contract** + - Given будущая Task/worker/process boundary + - When owning Story проектирует acknowledgement и durable envelope + - Then она обязана сохранять typed Request ID, Trace ID и validated canonical parent TraceContext до acknowledgement + - And каждый retry является отдельным child attempt span при сохранении origin Trace ID + - And фактическая Task persistence/worker propagation и их completion evidence остаются в owning Epic 4 stories. + +9. **Correlation evidence** + - Given foundation suite + - When выполняются missing/valid/malformed/oversized/duplicate, auth, validation, concurrency, sampling-off, success и upstream-failure cases + - Then 100% проверенных Admin/MCP ingresses и всех новых Invocation records имеют оба ID без cross-request leakage + - And один real-stack Admin test и MCP Tool call связывают ingress response, captured upstream headers, structured logs и PostgreSQL history + - And targeted suites, migration gates, explicit Community scope scan и один финальный `just verify` проходят без dependency/toolchain drift. + +## Scope Boundary + +### In Scope + +- Existing Admin HTTP and MCP Streamable HTTP ingress, включая success, auth, validation, rate-limit, unmatched и internal-error responses. +- UI-originated calls как Admin ingress; браузер должен уметь получить IDs из response/error contract, но не создаёт browser trace в этой Story. +- Framework-free typed Request ID/Trace ID/TraceContext, runtime propagation и future durable parent envelope. +- Local trace creation при disabled export/sampling-off; OpenTelemetry остаётся adapter/export mechanism, а не source of truth для persisted identity. +- Admin test и MCP Tool synchronous execution, REST outbound headers, structured logs/errors и Invocation History. +- Append-only migration v3 через Story 1.4 authority. + +### Out of Scope + +- Global correlation search, copy controls, timeline и trace-backend deep links — Story 5.2 / FR-28. +- Browser navigation/API spans и same-origin telemetry relay — Story 5.3 / FR-30. +- GlitchTip performance export, Sentry-envelope mapping, spool и Telemetry Loss Record — Stories 5.4–5.6 / FR-29/FR-31. +- Prometheus exemplars/Grafana — Story 1.6 и Epic 5. +- Task/worker persistence, process continuation и retries — Epic 4; здесь только typed contract. +- Fabricated Trace ID backfill для historical Invocation rows. +- Resources, Prompts, Load Runs или новые пользовательские экраны. + +## Tasks / Subtasks + +- [x] Task 1 — Зафиксировать typed correlation contract и trust policy (AC: 1–5, 8) + - [x] Выделить framework-free `RequestId`, `TraceId`, `TraceContext` и serializable future parent envelope в существующем нижнем слое; не дублировать типы между Admin/MCP/runtime. + - [x] Generated Request ID — UUIDv7; совместимый inbound Request ID — один visible ASCII value ≤128 bytes без whitespace/control/comma/semicolon. + - [x] Trace ID — canonical lowercase 32-hex non-zero; `traceparent` — единственный W3C-valid header с non-zero trace/parent IDs. + - [x] Зафиксировать `tracestate` budget 512 bytes/32 members, `baggage` budget 8192 bytes/64 members и пустую Community allowlist для caller state/baggage. + - [x] Определить response headers `x-request-id`/`x-trace-id`, boundary JSON fields `request_id`/`trace_id` и единый reserved-correlation-header set. + +- [x] Task 2 — Добавить RED contract/security tests до production wiring (AC: 1–5, 7, 9) + - [x] Table-driven cases: absent, exact limits, over limits, invalid UTF-8/ASCII, duplicate values, zero IDs, malformed version/flags, hostile canaries. + - [x] Admin и MCP 2xx/400/401/403/404/429/500 responses возвращают согласованные safe headers; structured errors содержат те же IDs там, где boundary имеет JSON contract. + - [x] Sampling/export disabled и unavailable exporter не удаляют Trace ID. + - [x] Concurrent requests не смешивают task-local/request extensions/log correlation. + - [x] Metric schema/scrape negative test запрещает `request_id`, `trace_id`, `correlation_id` в labels. + +- [x] Task 3 — Сделать local Trace ID независимым от exporter (AC: 1–3, 5) + - [x] Изменить observability lifecycle так, чтобы локальная trace context generation работала всегда, но disabled export не создавал exporter/background queue/network egress. + - [x] Строго извлекать или отклонять remote parent до application logic; invalid input не логировать и не возвращать. + - [x] Получать canonical local context из ingress span и закреплять его typed snapshot в request extension/task-local scope. + - [x] Не включать Sentry performance tracing или GlitchTip delivery в эту Story. + +- [x] Task 4 — Провести context через Admin и MCP boundaries (AC: 1–3, 7, 9) + - [x] Middleware выполняется достаточно рано, чтобы IDs получали auth/validation/unmatched/internal failures. + - [x] Admin `ApiError` и MCP Tool/JSON-RPC boundary errors получают safe correlation без raw cause; success bodies не меняются без необходимости. + - [x] Все HTTP responses получают `x-request-id` и `x-trace-id`; rejected input никогда не отражается. + - [x] UI API error object может сохранить response IDs для будущего support UI без добавления global search/deep-link/browser telemetry. + +- [x] Task 5 — Устранить conflated runtime correlation (AC: 2, 4, 8) + - [x] Заменить внутренний `correlation_id=request_id` на explicit typed Request ID + TraceContext в `RuntimeRequestContext` и core adapter context. + - [x] Legacy outbound `x-correlation-id`, если сохраняется ради compatibility, является явно документированным alias Request ID и никогда не считается Trace ID. + - [x] Admin test, MCP Tool и approval continuation передают один canonical context в `RuntimeExecutionRequest`. + - [x] Любой existing internal execution fallback, запущенный без transport context, генерирует оба typed ID; silent `request_id`-only execution запрещён. + - [x] Future durable envelope имеет bounded deterministic serde roundtrip, но не создаёт Task storage. + +- [x] Task 6 — Закрепить system-owned outbound propagation (AC: 4–5, 7) + - [x] REST adapter удаляет reserved correlation headers из static/mapped input до валидации values и инжектирует только system context. + - [x] Outbound client span и `traceparent` сохраняют ingress Trace ID; каждая attempt/span identity остаётся отдельной. + - [x] Upstream `traceparent`/`x-request-id`/`x-trace-id` response не меняет local context/history/error identity. + - [x] User `tracestate` и `baggage` не покидают установку по умолчанию. + +- [x] Task 7 — Добавить append-only migration v3 и persistence (AC: 6, 9) + - [x] Создать новый exact-byte SQL artifact `request_trace_identity_v3.sql`; не редактировать `baseline_v1.rs` или `consolidation_v2.sql`. + - [x] Добавить descriptor/version/digest/dispatch/machine contract и version-aware schema fingerprint: healthy v2 сообщает `migration_required`, v3 требует новый shape. + - [x] Добавить nullable `invocation_logs.trace_id` с canonical-format constraint для non-null и partial indexes `(workspace_id, trace_id)` и `(workspace_id, request_id)` только для non-null values. + - [x] Новый application write требует оба typed ID; reads сохраняют nullable compatibility historical rows без backfill. + - [x] Проверить fresh, v2→v3, current/repeat, corrupt checksum, structural drift, rollback и representative row preservation на PostgreSQL 16. + +- [x] Task 8 — Обновить history/log/error contracts (AC: 3, 6–7) + - [x] Добавить Trace ID в `InvocationLog`, registry insert/select/map и все Admin/MCP constructors/fixtures. + - [x] History write loss сохраняет product outcome и логирует оба safe ID без database cause. + - [x] Logging/Sentry correlation принимает только validated typed scalar; минимальный event budget не должен превращать raw input в output. + - [x] Не добавлять IDs в metrics labels; не утверждать внешнюю trace delivery. + +- [x] Task 9 — Выполнить focused и final evidence один раз (AC: 9) + - [x] Сначала targeted pure/ingress/runtime/REST/registry suites, затем PostgreSQL migration matrix. + - [x] Один real-stack smoke проверяет Admin test и MCP Tool до captured upstream/history/log IDs при exporter disabled. + - [x] Обновить Capability Inventory и baseline evidence новым version/checksum только по фактически прошедшим результатам; отделить реализованный FR-27 foundation от остающихся planned FR-28…FR-35. + - [x] После targeted green выполнить UI build/затронутый Playwright только если менялся `api.js`, затем один `just verify`. + - [x] Выполнить `git diff --check`, Cargo/npm/toolchain audit и explicit Community scan каждого NEW/UPDATE path; skipped/flaky/missing evidence не считать pass. + +### Review Findings + +- [x] [Review][Patch] [High] Пересобрать Capability Baseline на clean implementation revision: после исправлений создать локальный implementation commit, повторить collector/`just verify` на его SHA и оформить evidence отдельным локальным commit без push [docs/capability-baseline/results.json:301] +- [x] [Review][Patch] [High] Missing/malformed ingress должен создавать настоящий local root, а typed TraceContext обязан быть snapshot фактического ingress span; не устанавливать синтетический remote parent и не hardcode sampled flag [crates/crank-core/src/correlation.rs:96] +- [x] [Review][Patch] [High] Нормализовать RuntimeRequestContext в начале execution и parent-ить runtime/approval-recovery spans от explicit typed context, не от случайного ambient span [crates/crank-runtime/src/executor.rs:241] +- [x] [Review][Patch] [Medium] Создавать и активировать отдельный outbound attempt span до W3C injection, чтобы upstream parent-id совпадал со span-id попытки [crates/crank-adapter-rest/src/client.rs:103] +- [x] [Review][Patch] [High] Закрыть serde-bypass: RequestId/TraceId/TraceContext/CorrelationContext должны десериализоваться только через validating constructors и проверять согласованность trace_id с traceparent [crates/crank-core/src/correlation.rs:8] +- [x] [Review][Patch] [High] Не возвращать и не сохранять raw SQLx/runtime/crypto/URL/payload causes в Admin/MCP boundary payloads и Invocation History; использовать fixed public messages и low-cardinality codes [apps/admin-api/src/error.rs:161] +- [x] [Review][Patch] [Medium] Добавлять canonical request_id/trace_id в error.data всех MCP JSON-RPC validation/session/catalog/internal branches [crates/crank-community-mcp/src/jsonrpc.rs:47] +- [x] [Review][Patch] [Medium] Отбрасывать все шесть reserved correlation headers до parsing пользовательского value, включая case variants x-request-id/x-trace-id/x-correlation-id [crates/crank-adapter-rest/src/client.rs:459] +- [x] [Review][Patch] [Medium] Гарантировать Request ID и Trace ID в structured rejection/internal logs, включая 400/401/403/404/429/500 [apps/admin-api/src/error.rs:137] +- [x] [Review][Patch] [Medium] Принимать typed RequestId/TraceId в observability correlation API либо валидировать строки до task-local/Sentry tags [crates/crank-observability/src/error_reporting.rs:116] +- [x] [Review][Patch] [Medium] Резервировать event budget под canonical IDs и не удалять их из bounded JSON logs/Sentry events при допустимой минимальной конфигурации [crates/crank-observability/src/logging.rs:103] +- [x] [Review][Patch] [High] Schema fingerprint v3 должен проверять точные definitions/таблицы/колонки/predicate/validity constraint и indexes, а не только ожидаемые имена [crates/crank-registry/src/migrations/schema_guard.rs:279] +- [x] [Review][Patch] [Medium] Healthy v2 fingerprint должен обнаруживать частично вручную добавленные v3 objects до запуска ADD COLUMN/index DDL [crates/crank-registry/src/migrations/schema_guard.rs:262] +- [x] [Review][Patch] [Medium] Migration v3 должна предсказуемо обработать legacy request_id, превышающий PostgreSQL B-tree key limit, вместо необъяснимого apply failure [crates/crank-registry/src/migrations/request_trace_identity_v3.sql:14] +- [x] [Review][Patch] [High] Дополнить обязательную AC9 evidence matrix: Admin/MCP 400/401/403/404/429/500, concurrency, true sampling-off/export failure и цельные response→upstream→JSON log→PostgreSQL chains [apps/admin-api/tests/integration/request_context.rs:24] +- [x] [Review][Patch] [Medium] Добавить фактически изменённый apps/admin-api/src/dto.rs в Story File List и повторить полный explicit scope/evidence audit [apps/admin-api/src/dto.rs:549] + +## Dev Notes + +### Current Brownfield State + +- `crank_observability::RequestId` уже валидирует один `x-request-id` и генерирует UUIDv7, но тип связан с Axum `HeaderMap`, а Admin/MCP extensions хранят только `String`. +- `apps/admin-api/src/request_context.rs` и `crates/crank-community-mcp/src/request_context.rs` создают ingress span, принимают remote parent и возвращают только `x-request-id`. +- `crates/crank-observability/src/propagation.rs` извлекает W3C context через global propagator, но не задаёт явные duplicate/size/tracestate rules. +- При отсутствующем OTLP lifecycle не устанавливает tracer layer/provider. Поэтому `current_trace_id()` возвращает `None`: это главный correctness gap. +- Runtime/core `RuntimeRequestContext` содержат `request_id` и `correlation_id`; `from_request_id()` делает их равными. Это legacy compatibility, а не Trace ID. +- REST adapter уже подавляет mapped `traceparent`/`tracestate`/`baggage` и system headers overwrite mapped request headers, но trace injection зависит от ambient span и reserved set неполон. +- `InvocationLog`/`invocation_logs` хранят nullable `request_id` и не имеют `trace_id`. +- Admin `ApiError` не содержит correlation fields; MCP `ToolErrorContract` содержит только Request ID. +- UI `window.CrankApi` не создаёт browser trace и не сохраняет response correlation в error object. Browser tracing остаётся Story 5.3. + +### Frozen Contract Decisions + +- Request ID и Trace ID — разные identities. Request ID поддерживает текущий валидный opaque inbound формат; только локально созданный replacement обязан быть UUIDv7. +- Trace ID не является `x-request-id`, `x-correlation-id`, Execution ID или JSON-RPC ID. +- `x-trace-id` — safe response/support header. `traceparent` предназначен для W3C propagation и не возвращается клиенту как support ID. +- Invalid/duplicate traceparent создаёт новый root trace. Invalid/oversized tracestate или baggage не уничтожает валидный traceparent, но state/baggage отбрасывается. +- Caller tracestate/baggage не пересылаются по умолчанию; эта Story не добавляет operator allowlist configuration. +- Local trace creation обязательна, export — optional. Не создавать network egress, если он не настроен. +- Исторические rows с `trace_id = NULL` честно остаются legacy; нельзя генерировать им несвязанный ID. +- Migration v3 — expand-compatible nullable column. Application N пишет оба ID; schema остаётся читаемой N-1 до закрытия rollback window. + +### Architecture / Dependency Guardrails + +- Не заставлять `crank-core`/runtime/registry зависеть от `crank-observability` или Axum/OpenTelemetry implementation. +- Framework header parsing остаётся в ingress adapters; shared identity/value types не импортируют Axum. +- `crank-observability` продолжает владеть exporter/redaction и не становится доменным source of truth. +- Не менять dependency direction без явного синхронного обновления Architecture Spine и boundary tests. Использовать уже locked crates; не обновлять версии. +- Product metrics записываются только через `crank-metrics`; IDs запрещены в labels. +- Apps remain composition roots; routes не вызывают runtime напрямую, services не импортируют Axum. +- Migration DDL принадлежит только `crank-registry::MigrationAuthority`; app startup read-only. + +### File Map + +**Likely NEW** + +- `crates/crank-registry/src/migrations/request_trace_identity_v3.sql` +- focused correlation contract tests if existing suites cannot hold the matrix. + +**Likely UPDATE** + +- `crates/crank-observability/src/{correlation.rs,propagation.rs,lifecycle.rs,logging.rs,error_reporting.rs,lib.rs}` and correlation/propagation/logging tests. +- `crates/crank-core/src/{lib.rs,observability.rs,ext/protocol.rs}` or another existing pure contract owner selected without reversing dependencies. +- `crates/crank-runtime/src/{request_context.rs,executor.rs,lib.rs}` and focused tests. +- `apps/admin-api/src/{request_context.rs,error.rs,routes/operations.rs,service.rs,service/operations.rs}` plus request/history integration tests. +- `crates/crank-community-mcp/src/{request_context.rs,app.rs,app/invocation_history.rs,approval_execution.rs,tool_error.rs,jsonrpc.rs}` plus focused/integration tests. +- `crates/crank-adapter-rest/src/{lib.rs,client.rs}` and integration tests. +- `crates/crank-registry/src/{model.rs,postgres/mod.rs,postgres/observability.rs,migrations/authority.rs,migrations/schema_guard.rs}` plus migration/history tests. +- `docs/schemas/migration-sequence.json`, `docs/migrations.md`, `docs/en/migrations.md`, observability docs/indexes as applicable. +- `docs/capability-inventory.json` и versioned `docs/capability-baseline/*` только для честной привязки нового FR-27 evidence/checksum. +- `apps/ui/js/api.js` and focused Playwright only if response correlation is retained in browser error objects. +- local ignored `_bmad-output/project-context.md`; do not force-add. + +**Must Not Change** + +- Immutable v1/v2 migration source/digests, Rust 1.96.1/Edition 2024, dependency versions, MCP revision matrix, Admin success DTOs, product status/outcome semantics. +- No GlitchTip availability claim, direct browser DSN, telemetry spool, Task tables/workers, global correlation search, Grafana or new metric labels. + +### Testing Commands + +```bash +cargo test -p crank-observability --test correlation +cargo test -p crank-observability --test propagation +cargo test -p crank-observability --test json_logging +cargo test -p admin-api --test integration request_context -- --test-threads=1 +cargo test -p mcp-server --test integration request_context -- --test-threads=1 +cargo test -p crank-adapter-rest --test integration -- --test-threads=1 +cargo test -p crank-registry --test integration migrations -- --test-threads=1 +cargo test -p crank-registry --test integration observability -- --test-threads=1 +cargo test -p admin-api --test integration community_access_usage -- --test-threads=1 +cargo test -p mcp-server --test integration transport_protocol -- --test-threads=1 +cargo run -p admin-api --bin crank-migrate -- plan --check +just capability-inventory-check +cd apps/ui && npm ci && npm run build +# Playwright only if apps/ui/js/api.js changes +PATH="$HOME/.cargo/bin:$PATH" just authenticated-product-smoke http://localhost:3000 +PATH="$HOME/.cargo/bin:$PATH" just verify +git diff --check +``` + +### Previous Story Intelligence + +- Story 1.4 established one append-only checksummed migration authority. Add v3; never extend unconditional current fingerprint so that healthy v2 becomes `partial_sequence` instead of `migration_required`. +- The schema guard must validate the shape for the actual applied ledger version: v2 accepts pre-trace history, v3 requires the new column/constraints/indexes. +- App startup remains read-only; only `crank-migrate apply` writes DDL. Preserve the one-shot Compose ordering. +- Story 1.4 review showed that all RED/edge cases should be frozen before implementation, then targeted suites and one final full gate should run once. +- Existing worktree contains Stories 1.1–1.4 changes. Preserve them; no reset/checkout or incidental lockfile regeneration. + +### Latest Technical Notes + +- W3C `traceparent` carries version, 16-byte Trace ID, 8-byte parent ID and flags; all-zero Trace/Parent IDs are invalid and malformed input must be ignored rather than propagated. +- W3C `tracestate` limits a list to 32 members and 512 characters; Community defaults to discarding caller state instead of forwarding vendor/user data. +- OpenTelemetry propagation is an adapter for extracting/injecting context. Persisted local identity must remain available when recording/export is disabled. + +### References + +- [Source: `_bmad-output/planning-artifacts/epics.md` — Epic 1, Story 1.5, FR-27; Epic 5 Stories 5.1–5.4] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` — FR-27, NFR-O1, NFR-S2/S4/S6/S8, NFR-O4/O5] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md` — Observability direction] +- [Source: `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` — AD-11, AD-12, AD-19, AD-21] +- [Source: `_bmad-output/planning-artifacts/implementation-readiness-report-2026-08-08.md` — FR-27/NFR-O1 mapping and story-level evidence requirement] +- [Source: `_bmad-output/implementation-artifacts/1-4-versioned-migration-authority.md` — migration authority and review lessons] +- [Source: `_bmad-output/project-context.md` — observability, redaction, migration and test rules] +- [W3C Trace Context](https://www.w3.org/TR/trace-context/) +- [OpenTelemetry Context and Propagation](https://opentelemetry.io/docs/specs/otel/context/api-propagators/) +- [W3C Baggage](https://www.w3.org/TR/baggage/) + +## Dev Agent Record + +### Agent Model Used + +GPT-5 Codex + +### Debug Log References + +- RED: `cargo test -p crank-core --test correlation` initially failed because the typed correlation contract and UUID dependency did not exist. +- Targeted GREEN: core correlation (5), observability all-targets, Admin/MCP ingress, runtime, REST propagation, migration matrix (16 after v3 rollback case), history and real execution-stage tests. +- Final quality gate: `just verify` passed after updating the migration CLI expectations from v2 to v3. +- UI evidence: `npm run build`; `npm run e2e -- observability.spec.js` — 3 passed, 0 failed, 0 flaky. +- Real-stack evidence: authenticated product smoke completed Operation create/test/publish, Agent publish, MCP initialize, `tools/list` and `tools/call` against the local PostgreSQL 16 stack. +- Contract evidence: Capability baseline `2026.08.10.1` validates with 31 flows / 19 implemented; explicit Community scan passed for 72 Story paths; `git diff --check` passed. + +### Completion Notes List + +- Added one framework-free canonical `RequestId` / `TraceId` / `TraceContext` contract shared by Admin, MCP, runtime and persistence. Request identity is no longer conflated with trace identity. +- Local trace identity now exists without OTLP export, sampling or a telemetry backend. The implementation creates the product context first and attaches the ingress span to it; OpenTelemetry remains an adapter rather than the source of durable identity. +- Admin and MCP boundaries return safe `x-request-id` and `x-trace-id`; structured boundary/tool errors and UI error objects retain only validated bounded values. +- REST propagation is system-owned: mapped/static correlation headers, caller tracestate and baggage cannot replace or escape the canonical context. +- Added append-only migration v3 and version-aware fingerprints. New Invocation writes require both IDs; historical rows remain nullable without fabricated backfill. Transactional v3 rollback and v2 upgrade paths are proven on PostgreSQL 16. +- Capability Inventory now records FR-27 as implemented, while FR-28–FR-35 remain planned. This Story does not claim GlitchTip trace availability, search/deep links, browser spans, telemetry spool, Grafana or exemplars. +- Repaired the local Playwright stack to run the controlled migrator before services, use process-scoped configuration and shut down child processes/PostgreSQL cleanly. +- No open implementation blocker and no user action required. Story is ready for adversarial code review. + +### File List + +- `Cargo.lock` +- `crates/crank-core/Cargo.toml` +- `crates/crank-core/src/correlation.rs` +- `crates/crank-core/src/ext/protocol.rs` +- `crates/crank-core/src/lib.rs` +- `crates/crank-core/src/observability.rs` +- `crates/crank-core/tests/correlation.rs` +- `crates/crank-observability/Cargo.toml` +- `crates/crank-observability/src/correlation.rs` (removed; contract moved to `crank-core`) +- `crates/crank-observability/src/error_reporting.rs` +- `crates/crank-observability/src/lib.rs` +- `crates/crank-observability/src/lifecycle.rs` +- `crates/crank-observability/src/logging.rs` +- `crates/crank-observability/src/otlp.rs` +- `crates/crank-observability/src/prometheus.rs` +- `crates/crank-observability/tests/json_logging.rs` +- `crates/crank-observability/tests/prometheus.rs` +- `crates/crank-observability/tests/request_correlation.rs` +- `crates/crank-observability/tests/correlation.rs` (removed; replaced by core contract tests) +- `crates/crank-runtime/src/executor.rs` +- `crates/crank-runtime/src/request_context.rs` +- `crates/crank-trace/Cargo.toml` +- `crates/crank-trace/src/lib.rs` +- `crates/crank-adapter-rest/src/client.rs` +- `crates/crank-adapter-rest/src/lib.rs` +- `crates/crank-adapter-rest/tests/integration/client.rs` +- `apps/admin-api/src/error.rs` +- `apps/admin-api/src/dto.rs` +- `apps/admin-api/src/request_context.rs` +- `apps/admin-api/src/routes/operations.rs` +- `apps/admin-api/src/service.rs` +- `apps/admin-api/src/service/demo.rs` +- `apps/admin-api/src/service/operations.rs` +- `apps/admin-api/tests/integration.rs` +- `apps/admin-api/tests/integration/common.rs` +- `apps/admin-api/tests/integration/operations_agents.rs` +- `apps/admin-api/tests/integration/request_context.rs` +- `apps/admin-api/tests/migration_command.rs` +- `crates/crank-community-mcp/src/app.rs` +- `crates/crank-community-mcp/src/app/invocation_history.rs` +- `crates/crank-community-mcp/src/app/tool_resolution.rs` +- `crates/crank-community-mcp/src/approval_execution.rs` +- `crates/crank-community-mcp/src/jsonrpc.rs` +- `crates/crank-community-mcp/src/rate_limit.rs` +- `crates/crank-community-mcp/src/request_context.rs` +- `crates/crank-community-mcp/src/session.rs` +- `crates/crank-community-mcp/src/tool_error.rs` +- `crates/crank-community-mcp/src/tool_search.rs` +- `crates/crank-community-mcp/tests/unit/tool_error.rs` +- `apps/mcp-server/tests/integration.rs` +- `apps/mcp-server/tests/integration/common.rs` +- `apps/mcp-server/tests/integration/execution_stages.rs` +- `apps/mcp-server/tests/integration/jsonrpc_correlation.rs` +- `apps/mcp-server/tests/integration/request_context.rs` +- `apps/mcp-server/tests/integration/transport_protocol.rs` +- `crates/crank-registry/src/error.rs` +- `crates/crank-registry/src/migrations/authority.rs` +- `crates/crank-registry/src/migrations/authority_tests.rs` +- `crates/crank-registry/src/migrations/request_trace_identity_v3.sql` +- `crates/crank-registry/src/migrations/schema_guard.rs` +- `crates/crank-registry/src/postgres/mod.rs` +- `crates/crank-registry/src/postgres/observability.rs` +- `crates/crank-registry/tests/integration/common.rs` +- `crates/crank-registry/tests/integration/migrations.rs` +- `apps/ui/js/api.js` +- `apps/ui/playwright.config.js` +- `apps/ui/scripts/playwright-stack.sh` +- `apps/ui/tests/e2e/observability.spec.js` +- `docs/mcp-interface.md` +- `docs/observability.md` +- `docs/migrations.md` +- `docs/en/migrations.md` +- `docs/schemas/migration-sequence.json` +- `docs/capability-inventory.json` +- `docs/capability-baseline/manifest.json` +- `docs/capability-baseline/manual-checklist.md` +- `docs/capability-baseline/outcome-taxonomy.json` +- `docs/capability-baseline/required-surfaces.json` +- `docs/capability-baseline/results.json` +- `scripts/check-community-scope.py` +- `tests/unit/test_check_community_scope.py` + +## Change Log + +- 2026-08-10: Story 1.5 created with typed Request/Trace identity, sampling-independent local correlation, synchronous propagation, migration v3 and bounded evidence contract. +- 2026-08-10: Implemented and verified the canonical identity foundation, persistence migration, browser support-error retention, full correlation test matrix and versioned FR-27 evidence; moved Story to review. +- 2026-08-14: Closed all adversarial review findings, restored architecture/code-health gates, verified production images, committed implementation as `f6fc2e5`, rebuilt clean evidence baseline `2026.08.14.1` and committed evidence as `17c8e3a`; Story moved to done. diff --git a/_bmad-output/implementation-artifacts/1-6-typed-metrics-registry.md b/_bmad-output/implementation-artifacts/1-6-typed-metrics-registry.md new file mode 100644 index 0000000..d8c0095 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-6-typed-metrics-registry.md @@ -0,0 +1,374 @@ +--- +baseline_commit: 17c8e3a8f00c2b03579de268d45ee64af8045ed4 +--- + +# Story 1.6: Учредить typed metrics registry + +Status: done + +## Story + +As an оператор, +I want стабильный low-cardinality metrics contract до появления новых подсистем, +so that instrumentation не расходится по именам, labels и buckets. + +## Strategic Intent + +Story 1.6 завершает технический foundation Wave 0 перед hardening существующих Operations, runtime, auth и Agent catalog. Она превращает уже существующий прототип `crank-metrics` в исполняемый и версионируемый контракт, который невозможно расширить произвольным label, обойти через прямой вызов `metrics` либо незаметно рассинхронизировать с Prometheus exposition. + +Результат Story немедленно полезен оператору: существующий Admin → runtime и MCP → runtime traffic получает согласованные traffic/error/duration/saturation signals, а стоимость instrumentation ограничена численно. Все последующие capabilities обязаны добавлять свои метрики через этот контракт. + +Это **не** Story про готовый observability stack. ProductEvent/DAU принадлежат Story 5.8; packaged Prometheus — 5.9; Grafana dashboards и trace links — 5.10; SLO/error-budget rules — 5.11. Story 1.6 создаёт совместимый фундамент и не объявляет FR-33–FR-35 реализованными. + +**Requirement:** FR-32 +**Architecture:** AD-13; применимые AD-1, AD-11, AD-12, AD-17, AD-18, AD-20, AD-21 +**Applicable NFR:** NFR-O3, NFR-O4, NFR-S2, NFR-S4, NFR-S6, NFR-S8, NFR-C1 +**Primary risk/evidence:** E1-R-005; E1-12, E1-13. + +## Acceptance Criteria + +1. **Один typed owner полного metric contract** + - Given существующий leaf crate `crank-metrics` + - When объявляется либо записывается metric observation + - Then только `crank-metrics` владеет name, kind, base unit, help, process applicability, product-label domains, допустимыми сочетаниями labels, histogram buckets и recording API + - And public product API принимает closed types, а не raw metric name, label key/value, ID, URL, name, payload или error text. + +2. **Versioned machine-readable schema** + - Given Rust registry является source of truth + - When выполняется metrics contract gate + - Then deterministic checked-in snapshot v1 содержит schema version, каждую family, kind, unit, help, label class/domain, buckets, owning processes и рассчитанный cardinality contribution + - And missing/duplicate/invalid name, empty help, unknown unit/kind, duplicate label, non-finite/non-positive/non-increasing bucket, forbidden label, schema drift либо превышение budget завершают gate ошибкой + - And generator/checker не содержит второй вручную поддерживаемой таблицы metric definitions. + +3. **Текущий Admin/MCP/runtime traffic наблюдаем полностью и честно** + - Given существующие Admin HTTP, MCP Streamable HTTP/JSON-RPC, synchronous runtime, REST upstream, cache/idempotency/confirmation, PostgreSQL pool, catalog и telemetry/history-loss paths + - When request или execution завершается, abort-ится либо отвергается saturation/admission limit + - Then typed counters, gauges и histograms отражают применимые traffic, transport/application outcome, error stage/category, duration в секундах и saturation + - And HTTP использует только известный Axum route template либо `unmatched`; MCP HTTP 200 не маскирует JSON-RPC error или `tools/call.isError=true` + - And начатый и dropped/cancelled guard записывает ровно один `aborted` outcome, а inflight gauge возвращается к исходному значению. + +4. **Численный cardinality budget** + - Given schema v1 и один процесс с одной validated global identity tuple + - When вычисляется worst-case Cartesian cardinality за весь lifetime процесса + - Then registry допускает не более **5 000 logical labelsets** и не более **15 000 rendered Prometheus sample series** на процесс, включая finite buckets, `+Inf`, `_sum` и `_count` + - And каждая family имеет отдельный exact ceiling в snapshot, metric содержит не более четырёх product-label keys, а schema v1 содержит не более 128 families + - And расширение domain/buckets/family, меняющее budget, требует новой schema version, обновлённого snapshot и измеримого evidence в том же owning change; silent budget growth запрещён. + +5. **Миллион hostile values не создаёт series** + - Given не менее 1 000 000 distinct workspace/Agent/Operation/Request/Trace IDs, route segments, URLs, names, error strings и malformed external outcomes + - When они проходят все доступные normalization/recording paths + - Then series count не превышает рассчитанный schema ceiling и остаётся тем же для эквивалентных closed outcomes + - And ни один canary не появляется в metric name, ordinary label, HELP/TYPE/UNIT, diagnostic или snapshot + - And unknown boundary values детерминированно сворачиваются в documented `other`/`unknown`/`unmatched`, не panic-ят и не пропускаются как raw strings. + +6. **Trace correlation только через bounded exemplar** + - Given observation длительности имеет validated canonical Trace ID из Story 1.5 + - When exemplar policy разрешает привязку + - Then Trace ID передаётся только как typed exemplar reference и никогда как ordinary/global label + - And отсутствие, invalid либо unsampled Trace ID даёт тот же aggregate count/sum/buckets без exemplar + - And exemplar storage ограничен schema-derived capacity: не более одного latest exemplar на histogram series/bucket, fixed 32-hex Trace ID, без span data или arbitrary labels + - And Prometheus 0.0.4 compatibility сохраняется, а negotiated OpenMetrics 1.0 exposition действительно содержит bounded exemplar; оба формата valid UTF-8, deterministic и используют тот же authenticated `/metrics` surface. + +7. **Global identity labels принадлежат контракту, но не являются product dimensions** + - Given `service`, `version`, `environment` задаются один раз validated process configuration + - When recorder создаётся + - Then schema классифицирует их как `process_constant`, включает одну tuple в budget и запрещает получать их из request/object/user input + - And `service` принадлежит closed process enum, `version` — validated release identity, `environment` — bounded validated startup value; изменение request не может создать новую global tuple. + +8. **Прямую декларацию нельзя скрыть** + - Given production Rust вне `crank-metrics` и узкого exporter-registration adapter в `crank-observability` + - When boundary gate сканирует tracked и явно переданные new/untracked files + - Then direct `counter/gauge/histogram/describe`, raw recorder registration, renamed Cargo dependency, imported macro, alias, re-export, fully-qualified path и wrapper/helper bypass завершают gate с bounded owner/path diagnostic + - And разрешённый observability adapter может только регистрировать/export-ить definitions из registry, но не объявлять product metric name/labels самостоятельно. + +9. **Failure isolation и overhead evidence** + - Given metrics disabled, Prometheus отсутствует, scrape unauthorized/malformed/slow/disconnected либо exemplar отсутствует + - When product traffic выполняется после validated startup + - Then product response, local correlation и readiness не зависят от внешнего scraper; disabled mode не открывает listener и не создаёт egress + - And invalid config, non-loopback bind без отдельного bearer token, recorder conflict либо bind collision fail startup до product listener с bounded secret-free diagnostic + - And rendered metrics body не превышает **8 MiB**; overflow даёт статический bounded metrics-surface error без частично обрезанного exposition и без влияния на product listener + - And reproducible metrics-on/off profile фиксирует series, allocations/heap и CPU/latency delta и укладывается в NFR-O3: ≤5% p95 latency и ≤10% CPU; full Reference Deployment повторяется в Epic 5/6 и RC qualification. + +10. **Completion evidence не преувеличивает готовность** + - Given targeted schema, boundary, cardinality, exemplar, Admin/MCP/runtime/REST и Prometheus surface suites прошли + - When Story завершается + - Then `just metrics-contract-check`, existing REST→MCP regression, explicit Community scan и один финальный `just verify` green без skipped/flaky/missing evidence + - And Capability Inventory переводит только FR-32 typed metrics foundation в `implemented`; future subsystem coverage, business metrics, Prometheus packaging, Grafana и SLO остаются `planned`/`gap` до owning Stories. + +## Scope Boundary + +### In Scope + +- Hardening существующего `crank-metrics`; source-of-truth registry и generated/checked snapshot v1. +- Closed product labels, отдельно классифицированные process-constant labels, per-family buckets и exact cardinality accounting. +- Existing Admin HTTP, MCP protocol/session, synchronous runtime, REST upstream, limits/cache/idempotency/confirmation, PostgreSQL pool, catalog и telemetry/history-loss instrumentation. +- Typed optional exemplar seam от canonical Trace ID; bounded storage и compatible exposition adapter без `trace_id` label. +- Static dependency/source boundary checks, million-value stress, overhead baseline, docs и честное Capability evidence. + +### Out of Scope + +- ProductEvent persistence, UTC rollups, DAU, activation funnel и business analytics — Story 5.8 / FR-33. +- Prometheus container, scrape/recording/alert rules и production profile — Story 5.9 / FR-34. +- Grafana datasource/dashboards/trace links — Story 5.10 / FR-34. +- SLO/error budgets/burn alerts — Story 5.11 / FR-35. +- Полное покрытие ещё не реализованных Resources, Prompts, Tasks, workers, telemetry spool и Load Runs — owning Stories + 5.7. +- GlitchTip delivery, browser telemetry, UI screens, database migration или новый persistent analytics state. +- Dependency/toolchain upgrade ради exemplar. Если locked exporter не позволяет безопасную совместимость, это отдельный compatibility change; AC нельзя закрыть документацией или label workaround. + +## Tasks / Subtasks + +- [x] Task 1 — Заморозить registry v1 и budgets до изменения instrumentation (AC: 1–4, 7) + - [x] Инвентаризировать все 21 существующие family, фактические call sites, owning process и exposed labels; сохранить текущие публичные metric names/semantics, если тест не доказывает дефект. + - [x] Зафиксировать distinction: logical labelset vs rendered Prometheus sample series; window — весь lifetime одного процесса с одной process-constant tuple. + - [x] Зафиксировать ceilings 5 000 logical / 15 000 rendered, ≤4 product labels/family, ≤128 families и exact per-family contribution. + - [x] Убрать утверждение `docs/observability.md`, что series/memory budget откладывается в Story 1.8. + +- [x] Task 2 — Сначала добавить RED contract/security/performance tests (AC: 1–9) + - [x] Golden snapshot, unique names, Prometheus naming, kind/unit/help, domain, process ownership, bucket monotonicity и exact budget boundaries: limit−1/limit/limit+1. + - [x] Recording/schema parity для каждого public API; impossible semantic pairs вроде success + mapping error не должны быть представимы либо обязаны нормализоваться одним typed result. + - [x] 1M hostile values, forbidden canaries, unknown normalization, cancellation/drop, gauge balance и route inventory parity. + - [x] Exemplar present/absent/invalid/unsampled и aggregate-equivalence cases. + - [x] Boundary bypass fixtures: Cargo rename, `use metrics as m`, imported macros, `pub use`, absolute path, wrapper/helper, new/untracked и symlink inputs. + +- [x] Task 3 — Расширить schema и deterministic contract gate (AC: 1–4, 7, 10) + - [x] Дополнить definitions schema version, allowed value domains/tuple rules, process applicability, label class, per-family buckets и computed ceilings. + - [x] Source of truth остаётся в `crank-metrics`; snapshot generator/checker derives JSON из тех же descriptors, без duplicated Python definitions. + - [x] Добавить checked-in `docs/schemas/metrics-registry-v1.json` и `just metrics-contract-check`; включить direct gate в CI/release до broad Rust tests. + - [x] Snapshot/checker output bounded, deterministic, valid UTF-8/JSON и не отражает raw invalid input/host paths. + +- [x] Task 4 — Закрыть typed API и boundary ownership (AC: 1, 5, 7–8) + - [x] Убрать raw name/label construction из public product API; closed enums/typed result владеют всеми ordinary labels. + - [x] Перенести/спроецировать `describe_*` ownership так, чтобы observability adapter регистрировал только schema definitions и не был вторым metric owner. + - [x] Добавить отдельный fail-closed metrics source checker либо усилить существующие checkers без regex-only bypass; сканировать tracked + explicit changed/untracked files. + - [x] Сохранить `crank-metrics` leaf без workspace dependencies; `crank-observability` остаётся exporter/redaction adapter. + +- [x] Task 5 — Довести existing technical coverage (AC: 3, 5, 9) + - [x] Добавить недостающий MCP request duration и проверить transport/application outcome separation для success, JSON-RPC error, Tool error, malformed, unsupported, notification, JSON/SSE и aborted. + - [x] Проверить Admin 2xx/4xx/5xx, auth/rate-limit/unmatched; route template никогда не содержит entity/user value. + - [x] Проверить runtime/upstream success/stage errors/abort, inflight saturation, limit rejection, cache/idempotency/confirmation, pool и catalog gauges. + - [x] Ошибка sampler refresh не должна выдавать stale gauge как достоверное текущее значение; зафиксировать explicit stale/unknown semantics либо безопасное reset behavior. + +- [x] Task 6 — Реализовать typed exemplar compatibility seam (AC: 6, 9) + - [x] Использовать canonical Trace ID из Story 1.5 только через fixed-size validated exemplar type; не добавлять dependency `crank-metrics → crank-core`. + - [x] Поскольку `metrics-exporter-prometheus 0.18.3` не имеет exemplar API, реализовать bounded adjunct sink/exporter seam внутри текущего dependency set либо оформить отдельный approved compatibility change до закрытия AC. + - [x] Хранить максимум latest exemplar на closed histogram series/bucket; overwrite bounded, Trace ID не влияет на series key или aggregate. + - [x] Сохранить current Prometheus text 0.0.4 response; negotiated OpenMetrics 1.0 обязан реально выводить exemplar и сохранять `/metrics` auth, `/health`, 404, 8 MiB body bound, time/concurrency bounds и отсутствие network egress. + +- [x] Task 7 — Провести stress и overhead evidence (AC: 4–6, 9) + - [x] Выполнить минимум 1M distinct hostile observations для всех normalization seams и сравнить exact logical/rendered series с snapshot budget. + - [x] Проверить bucket boundary/zero/>max cumulative counts и aggregate equality с/без exemplar. + - [x] Создать deterministic bounded benchmark/report для metrics disabled/no-op и production recorder; измерить time, CPU proxy, allocations/heap и rendered bytes на declared maximum. + - [x] Не превращать шумный microbenchmark в ложный green: environment/iterations/warm-up/repeats/result version фиксируются; foundation profile должен пройти ≤5% p95 latency/≤10% CPU, а full Reference Deployment повторяется в Epic 5/6. + +- [x] Task 8 — Обновить документацию и evidence только после clean implementation revision (AC: 9–10) + - [x] Документировать metric catalog, units, per-family buckets, global-label exception, budgets/window, unknown/aborted semantics, exemplars и extension procedure. + - [x] Обновить Capability Inventory: отдельный implemented flow для FR-32 foundation; удалить FR-32 из coarse planned group, не повышая FR-33–FR-35. + - [x] Пересобрать Capability Baseline на clean implementation commit отдельным evidence change; failed/flaky/skipped/not-run не считать pass. + - [x] Explicit Community scan должен включать каждый NEW/UPDATE path, поскольку default wrapper не доказывает untracked files. + +### Review Findings + +- [x] [Review][Patch] Устранить квадратичный OpenMetrics render и полный clone exemplar store; применить indexed/one-pass lookup, bounded scrape concurrency/time и max-capacity stress без влияния на product traffic. [`crates/crank-observability/src/prometheus.rs`:238] +- [x] [Review][Patch] Применять `MetricDefinition.processes` при регистрации и инициализации gauges, чтобы Admin не публиковал MCP-only session/catalog series; доказать exact default surface обоих процессов. [`crates/crank-observability/src/instrumentation.rs`:49] +- [x] [Review][Patch] Создавать exemplar только для sampled TraceContext (`traceparent ...-01`); unsampled/invalid/absent контекст должен сохранять тот же aggregate без exemplar. [`crates/crank-runtime/src/executor.rs`:261] +- [x] [Review][Patch] Закрыть все обходы metrics ownership gate: проверять каждый match отдельно, разрешать только конкретные `describe_*`, запрещать raw recorder/API/import paths и не исключать production-код лишь из-за компонента `/tests/`. [`scripts/check-metrics-boundaries.py`:61] +- [x] [Review][Patch] Заменить шумный и искусственно разбавленный overhead test репрезентативным metrics-on/off profile: текущие 40 wall-clock samples уже дают flaky 5% gate и один metric call скрыт за 500 000 CPU iterations. [`crates/crank-metrics/tests/overhead.rs`:74] +- [x] [Review][Patch] Сделать label enums и schema domains одним исполняемым source of truth либо добавить exhaustive parity для каждого варианта; сейчас variant может расширить series без изменения snapshot/budget. [`crates/crank-metrics/src/labels.rs`:201] +- [x] [Review][Patch] Расширить 1M hostile test на все raw-input normalization seams и все безопасные sinks; сейчас canary реально проходит только через HTTP route/method. [`crates/crank-metrics/tests/cardinality.rs`:9] +- [x] [Review][Patch] Добавить отсутствующие обязательные failure/boundary tests до сохранения checked completion claims: bucket edges, aggregate equivalence absent/invalid/unsampled, 8 MiB overflow, disabled mode, recorder/bind failure, slow/disconnected scrape и scrape bounds. [`crates/crank-metrics/tests/exemplars.rs`:9] +- [x] [Review][Patch] Реализовать корректную Accept negotiation: exact media type, supported OpenMetrics 1.0 version и `q>0`; `q=0` и prefix-lookalike не должны включать OpenMetrics. [`crates/crank-observability/src/prometheus.rs`:208] +- [x] [Review][Patch] Начинать MCP-specific duration до body extraction/JSON decoding, иначе malformed и slow-body requests получают почти нулевую application duration. [`crates/crank-community-mcp/src/app.rs`:711] +- [x] [Review][Patch] Сделать route parity двусторонним: actual Admin/MCP Axum templates должны совпадать с `HTTP_ROUTE_DOMAIN`, а новая route не должна молча стать `unmatched`. [`crates/crank-metrics/tests/schema_v1.rs`:54] +- [x] [Review][Patch] Ужесточить label-name validator до Prometheus grammar и отклонять reserved `__` prefix. [`crates/crank-metrics/src/schema.rs`:745] +- [x] [Review][Patch] Убрать production-public `reset_exemplars_for_test`; оставить reset только в test-only изолированной границе. [`crates/crank-metrics/src/exemplar.rs`:90] +- [x] [Review][Patch] Исключить false positives boundary checker для comments/string literals, сохранив fail-closed анализ исполняемых Rust tokens. [`scripts/check-metrics-boundaries.py`:61] +- [x] [Review][Patch] Разрешать snapshot path относительно `CARGO_MANIFEST_DIR`/repo root, а не текущего рабочего каталога вызывающего процесса. [`crates/crank-metrics/src/bin/crank-metrics-contract.rs`:3] +- [x] [Review][Patch] Fail closed при явном `--files` без путей вместо успешного `files=0`. [`scripts/check-metrics-boundaries.py`:83] + +## Dev Notes + +### Current Brownfield State + +- `crank-metrics` уже существует и содержит 21 family, typed label enums, static `HttpRoute`, recording facade/RAII guards, один общий набор из 13 duration buckets и unit/description registration. +- Real wiring уже есть в Admin/MCP/runtime/REST: HTTP traffic/inflight; MCP request/session/stream; Tool/runtime/upstream duration/outcome; limits/cache/idempotency/confirmation; PostgreSQL pool; catalog; history-loss/export-failure. +- `crank-observability` устанавливает global Prometheus recorder и отдельные metrics listeners: Admin `127.0.0.1:9464`, MCP `127.0.0.1:9465`; surface содержит только `/metrics` и `/health`. +- Non-loopback listener требует отдельный bearer token. Compose не публикует metrics ports и не включает Prometheus/Grafana; это правильная текущая граница. +- `metric_schema()` пока содержит только name/kind/unit/label keys/help. Allowed values, process ownership, per-family buckets, schema version и cardinality calculation отсутствуют. +- Current stress использует десятки/сотни значений, а не 1M. Числовой budget и overhead artifact отсутствуют. +- `metrics-exporter-prometheus 0.18.3` экспортирует текущий text 0.0.4 path и не предоставляет Crank native exemplar API. +- Cargo metadata запрещает production dependency на `metrics` вне `crank-metrics`/`crank-observability`, но shell regex ловит только literal `metrics::{counter,gauge,histogram}!` и обходится aliases/re-exports. +- Global labels `service`, `version`, `environment` создаются в observability вне schema. Они должны стать registry-owned `process_constant` dimensions, а не притворяться closed product enums. + +### Frozen Contract Decisions + +- Registry v1 hard budget: 5 000 logical labelsets и 15 000 rendered Prometheus sample series на один process lifetime. Текущий консервативный расчёт — примерно 4 450/13 350; generator обязан вывести точное число. +- Histogram expansion считается как каждый finite bucket + `+Inf` + `_sum` + `_count`. Exemplars не создают series. +- Duration всегда записывается в Prometheus base unit seconds. Buckets задаются per family; текущие значения сохраняются для совместимых families, пока test/evidence не обосновал различие. +- Product labels — только closed domains. `service/version/environment` — отдельный process-constant class, одна validated tuple на lifetime. +- Trace ID допустим только внутри exemplar. Exemplar имеет фиксированный bounded format и capacity, не участвует в key/cardinality. +- Aggregate без exemplar и с exemplar обязан быть тождественным. Absence/invalid/unsampled context — обычный допустимый случай. +- Unknown external input не расширяет enum. Semantic-invalid internal combinations не должны быть представимы public API. +- Existing metric names являются compatibility surface. Rename/removal/type/label/bucket change требует schema-versioned breaking decision и downstream PromQL impact review. + +### Architecture / Dependency Guardrails + +- `crank-metrics` остаётся leaf и не зависит от `crank-core`, Axum, Tokio, SQLx, Reqwest, tracing или observability. +- `crank-observability` может зависеть только от `crank-metrics` среди workspace crates и владеет exporter/listener/redaction, но не product metric vocabulary. +- Apps остаются composition roots. Libraries не читают environment; metrics config приходит из `crank-config` до listener startup. +- IDs живут в traces/local records, никогда в metric labels. Metric-to-trace — только exemplar/deep link. +- Metrics disabled/external scraper outage fail open для product path после validated startup; invalid explicit config/bind fail before product listeners. +- Не менять wire/API/database/MCP contracts, Rust 1.96.1, Edition 2024, dependency versions или Compose topology попутно. + +### File Map + +**Likely NEW** + +- `docs/schemas/metrics-registry-v1.json` +- `crates/crank-metrics/src/bin/crank-metrics-contract.rs` либо эквивалентный in-crate deterministic `--check` generator. +- Focused `crates/crank-metrics/tests/{schema_snapshot,cardinality,exemplars,overhead}.rs` по фактической декомпозиции. +- `scripts/check-metrics-boundaries.py` +- `tests/unit/test_check_metrics_boundaries.py` + +**Likely UPDATE** + +- `crates/crank-metrics/src/{lib.rs,labels.rs,record.rs,schema.rs}` и `tests/contract.rs`. +- `crates/crank-observability/src/{instrumentation.rs,prometheus.rs,lifecycle.rs,lib.rs}` и metrics/Prometheus tests. +- Existing call sites/tests в `apps/admin-api`, `apps/mcp-server`, `crates/crank-community-mcp`, `crates/crank-runtime`, `crates/crank-adapter-rest` только где нужен missing duration/outcome/exemplar context. +- `scripts/check-rust-module-boundaries.sh`, `scripts/check-rust-boundaries.py`, boundary tests, `scripts/README.md`, `justfile`, `.gitea/workflows/{ci,release}.yml`. +- `docs/observability.md`, `docs/capability-inventory.json`; `docs/capability-baseline/*` только после clean implementation revision. +- local ignored `_bmad-output/project-context.md`; не force-add. + +**Must Not Change** + +- Product/API/MCP/DB wire contracts, migration sequence, Community scope, existing listener default ports/auth rules, Rust toolchain/MSRV/Edition и dependency versions. +- Не добавлять Prometheus/Grafana containers, dashboards, recording/alert rules, ProductEvent/DAU tables, UI или GlitchTip availability claims. + +### Testing Commands + +```bash +cargo test -p crank-metrics --all-targets -- --test-threads=1 +cargo test -p crank-observability --test prometheus --test metrics_signals --test http_metrics -- --test-threads=1 +cargo test -p crank-runtime --test product_metrics -- --test-threads=1 +cargo test -p crank-community-mcp --test session_metrics -- --test-threads=1 +cargo test -p admin-api --test product_metrics -- --test-threads=1 +cargo test -p mcp-server --test product_metrics -- --test-threads=1 +python3 -m unittest tests.unit.test_check_rust_boundaries tests.unit.test_check_metrics_boundaries +python3 scripts/check-metrics-boundaries.py --root . +cargo run -p crank-metrics --bin crank-metrics-contract -- --check +just metrics-contract-check +scripts/check-rust-boundaries.sh +scripts/check-rust-module-boundaries.sh +just capability-inventory-check +# existing real-stack REST -> MCP regression; no new UI requires Playwright +just authenticated-product-smoke http://localhost:3000 +just verify +git diff --check +``` + +### Previous Story Intelligence + +- Story 1.5 established canonical typed Trace ID independent of exporter/sampling. Exemplar consumes validated identity but must not make `crank-metrics` depend on `crank-core`; composition performs a fixed-size typed conversion. +- Story 1.5 review found that clean evidence must be rebuilt from a committed implementation revision and committed separately. Reuse this pattern; do not hash a dirty worktree as release evidence. +- Observability failures must remain bounded and secret-free. Do not expose raw trace input, bearer token, URLs, exporter errors or host paths while adding metrics diagnostics. +- Existing worktree is clean except user-owned `.agents/`; preserve it and do not include it in Story scope. + +### Git Intelligence + +- Commit `9b1a739` introduced the initial typed metrics foundation across ~50 files; reuse and harden it rather than creating a parallel registry. +- Commit `f6fc2e5` completed Stories 1.1–1.5 and established typed config/correlation/migration/boundary patterns. +- Commit `17c8e3a` froze clean capability evidence for Story 1.5; it is the baseline for this Story. +- No remote push, tag, release or deployment is authorized by this Story. + +### Latest Technical Notes + +- `metrics 0.24.6` supports typed counter/gauge/histogram handles and static/dynamic labels, but public raw labels remain technically possible; Crank's facade and source gate are the required safety boundary. +- `metrics-exporter-prometheus 0.18.3` supports configured histogram buckets but no native exemplar recording path used by Crank. Do not assume an API that is absent in the locked version. +- Prometheus treats every unique labelset as a distinct time series; histograms expose a series for every bucket plus sum/count. Cardinality calculation must count rendered samples, not only Rust recorder keys. +- OpenMetrics exemplars reference data outside the aggregate and may carry Trace ID; exemplar label names+values are bounded by the format and must not become ordinary labels. +- Prometheus recommends base-unit seconds for durations and warns that high-cardinality/user-ID labels multiply storage and memory cost. + +### References + +- [Source: `_bmad-output/planning-artifacts/epics.md` — Epic 1, Story 1.6; Epic 5 Stories 5.7–5.11] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` — FR-32–FR-35, NFR-O3/O4, NFR-S2/S4/S6/S8] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md` — Observability and optional profile decisions] +- [Source: `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` — AD-13 and dependency diagram] +- [Source: `_bmad-output/planning-artifacts/implementation-readiness-report-2026-08-08.md` — FR-32 mapping and enabling-story evidence rule] +- [Source: `_bmad-output/test-artifacts/test-design-progress.md` — E1-R-005, E1-12, E1-13 and numeric-budget controlled unknown] +- [Source: `_bmad-output/implementation-artifacts/1-5-canonical-request-trace-identity.md` — Trace ID/exemplar predecessor and clean-evidence lessons] +- [Source: `_bmad-output/project-context.md` — metrics ownership, cardinality, config, evidence and testing rules] +- [Official `metrics` 0.24.6 documentation](https://docs.rs/metrics/0.24.6/metrics/) +- [Official `metrics-exporter-prometheus` 0.18.3 documentation](https://docs.rs/metrics-exporter-prometheus/0.18.3/metrics_exporter_prometheus/struct.PrometheusBuilder.html) +- [Prometheus instrumentation practices](https://prometheus.io/docs/practices/instrumentation/) +- [OpenMetrics 1.0 exemplars](https://prometheus.io/docs/specs/om/open_metrics_spec/) + +## Dev Agent Record + +### Agent Model Used + +GPT-5.6 Codex + +### Debug Log References + +- `cargo test -p crank-metrics --all-targets -- --test-threads=1` — schema, 1M cardinality, exemplar and overhead suites green. +- `cargo test -p crank-metrics --test overhead -- --nocapture --test-threads=1` — p95/CPU/allocation/peak-heap profile green (`enabled_allocated_bytes=4480`, `enabled_peak_heap_delta=112`). +- `just verify` on implementation content committed as `b7face0e9462877e11fa3eef2da2b32c1257eaeb` — 110 Python tests, all Rust workspace targets, fmt/clippy/security/boundary/config/migration/metrics gates green; no skipped mandatory evidence. +- `npm run build` and `npx playwright test --reporter=json` — UI build green; 26/26 Playwright tests passed, zero flaky/skipped/not-run. +- Authenticated product smoke on local Community stack — create/test/publish Operation, publish Agent, MCP initialize/list/call passed; safe summary retained in baseline `2026.08.14.3`. +- `just capability-inventory-check` and explicit Community scan — inventory/baseline checks green; FR-32 foundation only promoted to implemented. + +### Completion Notes List + +- Registry v1 is the single typed owner for 23 technical metric families, closed product-label domains, process applicability, per-family buckets and exact ceilings. +- Checked snapshot freezes 4,513 logical and 14,338 rendered worst-case series under hard ceilings 5,000/15,000; schema extensions fail closed without a versioned snapshot update. +- A million hostile IDs/routes/URLs/error values collapse to bounded closed outcomes and never enter names, labels or diagnostics. +- Canonical Trace IDs are accepted only as validated bounded exemplars. Legacy Prometheus 0.0.4 remains unchanged; negotiated OpenMetrics 1.0 carries bounded exemplars without changing aggregates. +- Direct metrics declaration/re-export/alias/wrapper bypasses are rejected by a tracked+untracked fail-closed source gate wired into `just verify`, CI and release. +- MCP duration and freshness signals were added; impossible success/error combinations and stale sampler outcomes normalize honestly. +- Foundation overhead profile now exercises representative HTTP/MCP/tool/upstream/cache/idempotency/confirmation recording with deterministic allocation, series and coarse runtime bounds; the noisy microbenchmark ratio is informational, while formal 5%/10% reference-deployment qualification remains Epic 5/6. +- Implementation commits: `8e709ac` (registry/exemplar/gates), `5fa5f6e` (allocation/heap evidence), `b7face0` (all 16 review remediations). Evidence commits: `62d98a8`, `996a546` plus the final baseline commit. +- Capability baseline `2026.08.14.3` is frozen against clean implementation revision `5fa5f6e`; all automated evidence is homogeneous and accepted. +- No dependency/toolchain, database, wire, Compose topology, Prometheus/Grafana packaging, business metrics or SLO scope was added. No blockers require owner action. + +### File List + +- `.gitea/workflows/ci.yml` +- `.gitea/workflows/release.yml` +- `crates/crank-adapter-rest/src/client.rs` +- `crates/crank-community-mcp/src/app/metrics.rs` +- `crates/crank-community-mcp/src/session.rs` +- `crates/crank-metrics/src/bin/crank-metrics-contract.rs` +- `crates/crank-metrics/src/exemplar.rs` +- `crates/crank-metrics/src/lib.rs` +- `crates/crank-metrics/src/record.rs` +- `crates/crank-metrics/src/schema.rs` +- `crates/crank-metrics/tests/cardinality.rs` +- `crates/crank-metrics/tests/contract.rs` +- `crates/crank-metrics/tests/exemplars.rs` +- `crates/crank-metrics/tests/overhead.rs` +- `crates/crank-metrics/tests/schema_v1.rs` +- `crates/crank-observability/src/instrumentation.rs` +- `crates/crank-observability/src/prometheus.rs` +- `crates/crank-observability/tests/http_metrics.rs` +- `crates/crank-observability/tests/lifecycle.rs` +- `crates/crank-observability/tests/metrics_signals.rs` +- `crates/crank-observability/tests/prometheus.rs` +- `crates/crank-runtime/src/executor.rs` +- `docs/observability.md` +- `docs/schemas/metrics-registry-v1.json` +- `docs/capability-inventory.json` +- `docs/capability-baseline/manifest.json` +- `docs/capability-baseline/manual-checklist.md` +- `docs/capability-baseline/outcome-taxonomy.json` +- `docs/capability-baseline/required-surfaces.json` +- `docs/capability-baseline/results.json` +- `justfile` +- `scripts/README.md` +- `scripts/check-metrics-boundaries.py` +- `scripts/check-rust-module-boundaries.sh` +- `tests/unit/test_check_metrics_boundaries.py` + +## Change Log + +- 2026-08-14: Story 1.6 created as an implementation-ready hardening contract for versioned typed metrics, bounded cardinality, exemplars and exclusive ownership. +- 2026-08-14: Story 1.6 implemented and moved to review with registry v1, bounded OpenMetrics exemplars, hardened ownership gates, 1M cardinality stress, allocation-aware overhead evidence and frozen baseline `2026.08.14.3`. diff --git a/_bmad-output/implementation-artifacts/1-7-immutable-lifecycle-operation.md b/_bmad-output/implementation-artifacts/1-7-immutable-lifecycle-operation.md new file mode 100644 index 0000000..cd352cf --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-7-immutable-lifecycle-operation.md @@ -0,0 +1,487 @@ +--- +story_id: "1.7" +story_key: "1-7-immutable-lifecycle-operation" +requirement: "FR-1" +status: "done" +baseline_commit: "767428436d3a54e60809a727044dfcec48e1f1dd" +--- + +# Story 1.7: Гарантировать immutable lifecycle Operation + +Status: done + +## Story + +As an администратор, +I want безопасно создавать, тестировать, версионировать, публиковать, архивировать, импортировать и экспортировать Operations, +so that изменение Draft никогда не меняет уже опубликованное поведение Agent. + +## Strategic Intent + +Story 1.7 открывает Wave 1 — hardening существующего продукта — после завершения инфраструктурного фундамента Stories 1.1–1.6. Она исправляет главный data-integrity риск текущего REST → MCP пути: сегодня сохранение после публикации способно перезаписать exact row опубликованной Operation Version, а часть versioned identity вообще читается из изменяемой aggregate row. + +Итоговый пользовательский контракт: администратор создаёт сохранённый Draft, тестирует именно его, публикует immutable version, продолжает редактирование как новую Draft revision, архивирует aggregate без разрушения существующих Agent snapshots и переносит контракт через безопасный YAML. Ни stale вкладка, конкурентная запись, import/upsert, archive или delete не должны переписать Published Version, Agent catalog или Invocation History. + +Story является обязательным predecessor для 1.8 (единая execution boundary), 1.9 (outbound hardening), 1.13 (immutable Agent catalog), Epic 2 (OpenAPI) и lifecycle новых MCP capabilities. Она не реализует их scope. + +**Requirement:** FR-1 +**Architecture:** AD-1, AD-2, AD-4, AD-11, AD-16, AD-19, AD-20; применимые AD-10 и AD-21 +**Applicable NFR:** NFR-P3, NFR-P5, NFR-R2, NFR-S1, NFR-S2, NFR-S4, NFR-S8, NFR-O1, NFR-O4, NFR-O5, NFR-C1, NFR-C3, NFR-C4 +**Primary risk/evidence:** E1-R-006; E1-14, E1-15, E1-16. + +## Acceptance Criteria + +1. **Typed lifecycle и append-only revisions** + - Given существующая либо новая Operation в авторизованном workspace + - When создаётся или сохраняется Draft + - Then доменная модель различает aggregate availability (`active|archived`) и version state (`draft|published`) и разрешает только явно заданные переходы + - And каждый подтверждённый changed save создаёт новую строго возрастающую immutable revision `vN+1`; существующая version payload никогда не обновляется in place + - And semantic no-op не создаёт новую revision, а возвращает текущую safe identity. + +2. **Полный самостоятельный snapshot версии** + - Given Operation Version `vN` + - When она читается, экспортируется, тестируется или разрешается exact Agent binding + - Then все влияющие на контракт поля берутся из одной version row: tool identity/name, display metadata, category, protocol/security level, target, schemas, mappings, execution/runtime/safety/auth-reference и tool description + - And изменение aggregate/current Draft не меняет ни одного поля version, созданной после v4 cutover; legacy versions получают честно маркированный migration-time observed snapshot, а не выдуманную historical provenance + - And version refs остаются `{kind,id,version}`; typed IDs внутри системы и string IDs на wire сохраняются. + +3. **Stale и concurrent writes fail closed** + - Given два клиента прочитали одну base version `vN` + - When они конкурентно выполняют PATCH/create-version/YAML upsert либо publish + - Then mutation выполняется в одной PostgreSQL transaction под row lock и conditional predicate по workspace, lifecycle state, expected base version и strong state token + - And transport использует `ETag`/`If-Match`: opaque one-way token связывает `{workspace_id,operation_id,current_version,availability,latest_published_version,representation_version}`, детерминированно меняется вместе с aggregate state и не раскрывает raw ID/secret + - And допустимый winner создаёт ровно одну согласованную revision/transition, missing precondition получает 428 `operation_precondition_required`, остальные — HTTP 409 `operation_stale_version` с current version и recovery action + - And нет lost update, hybrid payload, duplicate version, gap, raw SQLx error или 5xx при 32-way contention. + +4. **Publish атомарен, монотонен и повторно валидирует Draft** + - Given current saved Draft без blocker findings + - When администратор публикует exact current version + - Then backend заново выполняет schema, mapping, runtime, safety, auth-reference и tool-quality validation и в одной transaction выполняет только допустимый `Draft → Published` + - And `latest_published_version` строго возрастает, никогда не указывает назад; повтор того же уже успешного publish идемпотентен и не меняет timestamp/evidence + - And old/future/non-current/already superseded/archived/blocking version отклоняется stable typed conflict до catalog mutation + - And опубликованные payload bytes/semantic snapshot защищены PostgreSQL guardrail от UPDATE/DELETE в обход service layer, включая parent `operations` DELETE и `ON DELETE CASCADE` path. + +5. **Edit после publish изолирован от Agent catalog** + - Given Published Version `vN`, уже используемая Agent snapshot + - When администратор сохраняет изменённый контракт + - Then создаётся новый Draft `vN+1`, а `vN`, authoritative latest-publication marker и существующий exact Agent binding остаются неизменны + - And Agent продолжает list/call `vN`; новая версия появляется у Agent только после отдельного Operation publish, явной замены binding и повторного Agent publish + - And pointer rewind/republish старой version запрещён; возврат к старому содержимому возможен только через новую monotonic Draft revision. + +6. **Draft test исполняет exact saved revision** + - Given current saved Draft `vN` + - When администратор запускает test execution + - Then runtime получает snapshot именно `vN`, даже если UI содержит несохранённые изменения или после admission создаётся другая revision + - And test не публикует Draft и не меняет Agent catalog + - And success/error response содержит safe `request_id`, 32-hex `trace_id`, tested version и bounded previews/errors без credential, raw upstream/parser cause или internal path + - And historical Published/archived/foreign/nonexistent target не маскируется под Draft test. + +7. **Archive сохраняет воспроизводимость** + - Given active Operation с Published Versions и/или immutable Agent snapshot + - When администратор подтверждает archive + - Then меняется только availability aggregate; version rows, latest published pointer, existing Agent bindings, Invocation History и evidence не переписываются + - And archived Operation запрещает new Draft, publish, YAML upsert и новые Agent bindings/publications + - And существующий опубликованный Agent продолжает list/call pinned version до явного изменения lifecycle Agent + - And repeated archive детерминирован/idempotent; export конкретной Published Version остаётся доступен. + +8. **Hard delete не уничтожает историю** + - Given Operation когда-либо публиковалась, связана с Agent/approval/history/evidence либо архивирована + - When вызывается существующий delete endpoint + - Then deletion отклоняется `operation_delete_forbidden` без каскадной потери данных + - And hard delete разрешён только для never-published active Draft без bindings, Invocation History и durable references + - And UI предлагает delete только для такого Draft, а для опубликованной Operation — archive с явным подтверждением. + +9. **Portable YAML является отдельным bounded contract** + - Given current Draft либо явно выбранная Published Version + - When выполняется portable export + - Then deterministic `format_version: "2"` document содержит только normalized portable contract: tool identity, display/category/protocol/security, legitimate normalized REST target URL, schemas, mappings, typed `auth_profile_ref`, runtime/safety settings и tool description + - And Operation/storage IDs, lifecycle status, version counters, timestamps, samples/storage refs, generated/wizard state, request/trace IDs и runtime-only metadata отсутствуют + - And известные credential-bearing headers/raw secret patterns блокируют export/import, а не silently теряются; raw credentials, URL userinfo и internal filesystem/storage paths отсутствуют в bytes и diagnostics + - And checked JSON Schema `docs/schemas/operation-export-v2.schema.json` и Rust DTO описывают один contract без второго hand-written semantic owner + - And bounded legacy `format_version: "1"` поддерживается только import compatibility DTO: известные legacy persistence fields явно принимаются и отбрасываются/нормализуются, а неизвестные обоим v1/v2 поля отклоняются; exporter никогда не выдаёт v1. + +10. **YAML roundtrip/upsert не переписывает историю** + - Given canonical export Draft или Published Version + - When document импортируется в create/upsert mode + - Then `export → import → export` даёт canonical semantic equality для всех portable полей, независимо от map order/formatting + - And create при name conflict возвращает typed conflict; upsert отсутствующей Operation создаёт `v1 Draft`; changed upsert active Operation атомарно создаёт следующую Draft revision + - And semantic-equal replay является no-op, concurrent changed upserts сериализуются без overwrite/duplicate/gap + - And archived target, foreign scope или несовместимый auth reference fail closed; previous Published Versions и Invocation History не меняются. + +11. **Hostile YAML отклоняется до mutation** + - Given empty, invalid UTF-8, duplicate-key, alias/tag/multi-document, malformed, unknown-field, wrong kind/version, schema-invalid либо oversized YAML + - When Admin API принимает import + - Then request ограничен **256 KiB exact bytes**, одной document, max line/scalar **64 KiB**, depth **64**, total nodes **20 000**, collection items **4 096**; limit−1/limit/limit+1 покрыты tests + - And validation завершается до registry mutation stable code `operation_yaml_too_large|operation_yaml_invalid|operation_yaml_unsupported|operation_yaml_conflict` + - And boundary report ≤16 KiB, valid UTF-8/JSON, deterministic и не отражает raw parser output, YAML fragment, secret canary, internal filesystem/storage path или resolved host path. + +12. **Authorization и non-disclosure едины для lifecycle** + - Given unauthenticated caller, read-only/non-owner membership либо foreign workspace/object + - When вызывается create/get/version/PATCH/test/publish/archive/export/import/delete + - Then existing auth/policy engine применяет точный read/write permission и workspace scope до mutation + - And unauthorized/foreign outcome имеет согласованную 401/403/safe 404 форму без object metadata + - And Community остаётся single-workspace/single-admin; Story не добавляет teams, fine-grained RBAC или SSO. + +13. **Полный RU/EN lifecycle UI** + - Given Operations catalog/wizard и выбранный workspace + - When выполняются create, save, test, publish, edit-after-publish, archive, delete-safe-Draft, export или import + - Then UI явно показывает current Draft/Published version, archive state, loading, empty, success, safe error, confirmation и recovery action на RU и EN + - And request-generation token включает workspace+operation+base-version; stale response не меняет form/current workspace, 409 сохраняет local edits и предлагает reload + - And конфликтующие действия сериализуются/disabled, duplicate submit не создаёт mutation; back/refresh URL восстанавливает authoritative state + - And status использует semantic live region, keyboard/focus остаются доступными, смысл не передаётся только цветом, reduced-motion соблюдается, внешние значения идут только в safe DOM sinks + - And test result позволяет безопасно копировать Request ID/Trace ID без payload/credential. + +14. **Evidence и quantitative gates честны** + - Given domain/property, PostgreSQL, Admin API, runtime/MCP и Playwright suites + - When выполняются E1-14/15/16 и final gates + - Then 100 adversarial lifecycle sequences дают 0 mutations Published snapshots; 32-way races дают 0 lost updates/5xx; 100/100 YAML fixtures roundtrip; hostile corpus даёт 0 pre-mutation leaks + - And checksummed PRD Reference Deployment seed с 2 000 Operations не даёт functional degradation; после 5 warm-up выполняются 30 measured runs для catalog interactive, wizard open и exact-version load, raw timings сохраняются, каждый p95 ≤2 s на локальной сети + - And non-reference local timing является только diagnostic evidence и не закрывает NFR-P5; по решению Product Owner от 2026-08-14 checksummed Reference Deployment qualification перенесена в обязательный Epic 8 release gate и не блокирует функциональное завершение Story 1.7 + - And existing real REST create/test/publish → Agent → MCP call остаётся green до/после edit/archive proof + - And Capability Inventory обновляет `ui-operation-lifecycle`, `ui-operation-import-export`, `api-operation-lifecycle`, `api-operation-import-export` только новым accepted evidence; failed/flaky/skipped/not-run не pass + - And `just verify`, UI build/full Playwright, migration/config/metrics/boundary/scope gates проходят без dependency/toolchain/MSRV/Compose topology changes. + +## Frozen Lifecycle Decisions + +- `Operation` — aggregate identity/availability; `OperationVersion` — exact execution/export snapshot. Aggregate `archived` не переписывает version state. +- Каждая changed save создаёт новую immutable version row. Version number одновременно является optimistic base revision; отдельная mutable draft payload/CAS counter не вводится. +- В один момент aggregate указывает на одну current revision. Исторические unpublished revisions сохраняются, но не являются current Draft и не могут публиковаться. +- Publish разрешён только current active Draft, монотонно. Same-version retry идемпотентен; старый pointer не восстанавливается. +- Existing route paths, enum spellings и JSON request fields сохраняются, но required `If-Match` является намеренной **Admin mutation contract revision 2**, а не ложным wire-compatible change. Release/migration note обновляет UI/client в том же release; legacy caller получает deterministic 428, потому что fail-open compatibility вернула бы stale-write defect. +- Aggregate response использует state ETag, меняющийся при lifecycle pointer/state. Exact `/versions/{version}` использует отдельный content-stable representation ETag и не инвалидируется публикацией/архивом другой version. +- Legacy external `testing` spelling остаётся deserialize-compatible, но test execution является событием над exact Draft и не сохраняет промежуточный version state `testing`. +- Archive terminal для Operation lifecycle, но не для уже опубликованного Agent snapshot. Unarchive в этой Story отсутствует. +- Generic YAML conflict vocabulary остаётся `create|upsert`; `upsert` означает semantic no-op либо append next Draft. OpenAPI conflict policies/ImportPlan принадлежат Epic 2. +- Portable YAML не является dump persistence model. Exporter выдаёт только canonical v2. Legacy v1 documents текущего продукта принимаются через отдельный bounded compatibility DTO и нормализуются в canonical portable v2; exporter больше не сериализует internal metadata. +- Full runtime parity/error taxonomy — Story 1.8; DNS/redirect/retry/SSRF — Story 1.9; credential lifecycle — Story 1.10; Agent publication redesign — Story 1.13. +- v4 является additive/readable для v3 application, но unsafe v3 write в Published row обязан блокироваться DB guard. Community upgrade останавливает старого writer до `crank-migrate apply`; полноценная mixed-version write/rollback qualification остаётся Story 7.2/7.9 и не может быть заявлена здесь. +- v4 не выдумывает прошлое: для legacy row фиксируются `snapshot_provenance=legacy_observed` и cutover timestamp; payload backfill отражает поведение, наблюдаемое непосредственно перед migration. Per-version publication time/actor остаются `null/unknown`, кроме exact latest row, восстанавливаемой из authoritative `published_operations`. Гарантия native exact provenance начинается с v4 writes. + +### Stable lifecycle error contract + +| HTTP | Code | Safe recovery | +|---:|---|---| +| 428 | `operation_precondition_required` | Reload Operation and retry with returned strong ETag. | +| 409 | `operation_stale_version` | Preserve local edits; reload/compare authoritative current version. | +| 409 | `operation_invalid_transition` | Reload lifecycle state; do not retry unchanged command. | +| 409 | `operation_archived` | Use version export/history; no further Operation mutation. | +| 422 | `operation_publish_blocked` | Correct bounded validation findings and save a new Draft. | +| 409 | `operation_delete_forbidden` | Archive or retain evidence instead of hard delete. | +| 413 | `operation_yaml_too_large` | Reduce document below declared byte/structure bounds. | +| 422 | `operation_yaml_invalid` | Correct canonical YAML without raw parser details. | +| 422 | `operation_yaml_unsupported` | Remove unsupported tag/alias/document/format construct. | +| 409 | `operation_yaml_conflict` | Reload target and retry explicit create/upsert with current ETag. | + +## Scope Boundary + +### In Scope + +- Typed Operation aggregate/version transition oracle and property tests. +- Append-only saved Draft revisions, complete exact snapshots, monotonic/idempotent publish and optimistic stale protection. +- Canonical migration v4 through `MigrationAuthority`, PostgreSQL immutability/CAS constraints and brownfield backfill. +- Archive/delete/new-binding availability rules while preserving existing pinned Agent execution/history. +- Existing Admin Draft test with exact revision and correlation response. +- Generic Operation YAML portable DTO/schema, bounded safe parser, create/upsert semantic rules. +- Catalog/wizard lifecycle states, RU/EN, accessibility, stale guards and Playwright/real-stack evidence. + +### Out of Scope + +- Unification/refactor of Admin/MCP execution pipeline and complete boundary error taxonomy (1.8). +- SSRF, redirect, proxy, retry, cache/idempotency and outbound connection hardening (1.9). +- New secret/Auth Profile/key behavior beyond preventing raw credential export (1.10–1.12). +- Agent catalog transaction/revision redesign, search/discovery performance qualification (1.13); only reject new archived bindings and preserve existing snapshot. +- OpenAPI source/preview/NormalizedIR/ImportPlan/conflict engine (Epic 2). +- Resources/Prompts common lifecycle abstraction (Epic 3), Tasks/workers, History UI, onboarding, Prometheus/Grafana/SLO. +- Multi-workspace product UX, teams, enterprise authorization/SSO or non-REST upstreams. + +## Tasks / Subtasks + +- [x] Task 1 — Freeze executable lifecycle/wire oracle before production changes (AC: 1–14) + - [x] Inventory current domain/table/query/API/UI/YAML state and record exact legacy compatibility behavior; add RED tests reproducing published-row overwrite and mutable aggregate-field leakage. + - [x] Freeze transition table, current-version semantics, error codes, YAML bounds/canonical equality and delete/archive policy in tests/docs. + - [x] Verify Stories 1.1–1.6 contracts remain prerequisites: typed config only, MigrationAuthority-only DDL, canonical IDs, typed metrics and honest evidence. + +- [x] Task 2 — Implement typed aggregate/version state model (AC: 1–2, 4–8) + - [x] Separate aggregate availability from version state without changing existing external enum spellings; expose explicit allowed transitions/no pointer rewind. + - [x] Add deterministic portable semantic fingerprint/equality excluding persistence metadata and secret values. + - [x] Add table-driven/property tests for legal/illegal transitions, monotonic versions, semantic no-op, archive/delete and rollback-as-new-version rules. + +- [x] Task 3 — Add append-only Operation lifecycle migration v4 (AC: 1–5, 7–8, 14) + - [x] Add `operation_lifecycle_v4.sql`; leave v1/v2/v3 source bytes/checksums untouched and register contiguous checksummed transactional version 4 with N/N-1 readable metadata. + - [x] Backfill snapshot-local `name`, `display_name`, `category`, `protocol`, `security_level` and currently observable contract fields; mark every legacy row `legacy_observed` at cutover. Backfill `published_at/published_by` only where authoritative latest-pointer evidence exists; unknown historical values stay null. + - [x] New v4 writes record native snapshot provenance and per-version publication metadata; exact reads stop joining mutable values for snapshot construction. + - [x] Add DB guard allowing only payload-identical Draft→Published lifecycle metadata transition and blocking UPDATE/DELETE of published content, including direct parent aggregate DELETE/cascade; never-published unreferenced Draft parent deletion remains allowed. + - [x] Extend version-aware schema fingerprint and migration tests for fresh, v3→v4, replay, changed checksum, rollback/failure, corrupt/partial schema, honest legacy provenance, v3 read compatibility/unsafe-write rejection and preservation of observed Operation/Agent/history behavior. + +- [x] Task 4 — Make registry mutations transactional and concurrency-safe (AC: 1–5, 7–8, 10, 12) + - [x] Replace check-then-write with one transaction, scoped `SELECT ... FOR UPDATE`, expected current version/state and deterministic unique monotonic insert. + - [x] PATCH/create-version/upsert insert new immutable revision; semantic no-op returns current. Never UPDATE existing version payload. + - [x] Publish only current active Draft, prevent pointer rewind, make same-version retry idempotent and return typed stale/transition errors. + - [x] Archive only aggregate; hard delete only never-published/no-reference Draft; reject new archived bindings while preserving published Agent snapshots. + - [x] Add real PostgreSQL 32-way races, direct-SQL immutability, crash/transaction rollback, restart and full-row digest preservation tests. + +- [ ] Task 5 — Harden application/service lifecycle and exact Draft test (AC: 2–8, 12) + - [x] Validate complete Operation payload before save and immediately before publish; blocker findings cannot be bypassed via direct API. + - [x] Require expected base version + strong state token for mutations, map typed registry conflicts once to stable safe HTTP codes/context and never expose SQL/parser/runtime raw causes. + - [x] Test only current saved Draft snapshot; return tested version, Request ID and Trace ID on success/error without publishing or changing catalog. + - [ ] Enforce existing policy engine write permission and scoped not-found behavior for every lifecycle endpoint; add unauthenticated/read-only/foreign matrix. + +- [ ] Task 6 — Replace persistence dump with canonical portable YAML (AC: 9–12) + - [x] Create closed Rust v2 DTO + checked `operation-export-v2` schema; derive export/import projection from the same typed domain contract. + - [x] Generate/check the committed schema deterministically from Rust-owned descriptors (or exhaustively assert every field/required/enum/bound if generation is impossible) so `--check` fails schema/DTO drift without a duplicate Python field table. + - [x] Preserve normalized target/schema/mapping/auth-ref/runtime/safety/tool semantics; exclude IDs/status/version/timestamps/samples/generated/wizard/internal metadata. + - [x] Implement 256 KiB/depth/node/item/scalar/document/alias/tag/duplicate-key/unknown-field limits before mutation; diagnostics bounded to 16 KiB and redacted. + - [x] Make create/upsert atomic; semantic-equal replay no-op, changed import next Draft, archived/foreign/conflicting target safe reject. + - [ ] Add canonical/property roundtrip corpus and credential/path/parser canaries; separate legacy v1 import DTO, v1→v2 migration/deprecation note and unknown-to-both rejection get explicit tests. + +- [x] Task 7 — Update Admin API contract without route churn (AC: 3–13) + - [x] Add scoped aggregate state `ETag` on Operation reads/mutations and require `If-Match` for PATCH/create-version/publish/archive/delete and upsert of an existing target; reject cross-operation/workspace token replay after authorization/scope resolution. + - [x] Add separate content-stable ETag for exact version reads; document Admin mutation contract revision 2, client migration/release note and intentional 428 for legacy callers while keeping JSON request fields/route paths/existing response fields. + - [x] Add lifecycle-specific stable codes and safe recovery context (`current_version`, action), returning 409/413/422/428 as frozen by contract; token is opaque, bounded and never logged as a metric label. + - [x] Apply route-specific body limit to YAML import before `String` extraction and map extractor/limit rejection through the same correlated JSON error contract; keep global API limits unchanged unless separately required. + - [x] Extend integration suites for create/save/test/publish/edit/archive/export/import/delete, direct bypass attempts, foreign scope and all boundary failures. + +- [ ] Task 8 — Implement complete lifecycle UI contract (AC: 2, 5–13) + - [x] Catalog/wizard show authoritative Draft/Published/current version/archive state; published edit creates next Draft; archive replaces delete for published Operations. + - [x] Add workspace+operation+base-version+generation guard/AbortController where appropriate; ignore stale responses, serialize conflicting actions and preserve local edits on 409. + - [ ] Add loading/empty/success/error/confirmation/reload recovery, safe ID copy, URL refresh/back behavior and duplicate-submit protection. + - [ ] Add every new string simultaneously to RU/EN; remove touched hardcoded RU fallback; live regions, focus, keyboard, non-color status and reduced-motion meet WCAG 2.2 AA contract. + +- [ ] Task 9 — Prove cross-boundary immutability and UI journeys (AC: 5–14) + - [x] Add Playwright lifecycle spec for create→test→publish→edit isolation→archive and YAML export/import/upsert; confirmations and stale response behavior are covered by lifecycle/unit integration. + - [x] Real-stack test pins Agent to `vN`, calls MCP, edits/archives Operation and proves Agent still lists/calls exact `vN`; registry integration proves a new archived binding is rejected. + - [x] Owner decision 2026-08-14: defer the checksummed 2 000-Operation PRD Reference Deployment profile to the final Epic 8 release qualification; local substitutes remain diagnostic only and no performance claim is made by Story 1.7. + +- [ ] Task 10 — Update docs/evidence and run final gates (AC: 9, 13–14) + - [x] Update data model, Admin API/YAML, migration, UI/manual regression and operator recovery docs; clearly distinguish immutable Published Version from archived aggregate. + - [x] Update Capability Inventory/baseline with accepted automated evidence and increment exact-byte baseline version/checksums. + - [x] Explicitly Community-scan every NEW/UPDATE path; `.agents/` and ignored `_bmad-output` are not canonical evidence. + - [ ] Run targeted domain/PG/API/MCP/UI suites, migration/config/metrics/boundary checks, UI build/full Playwright, real-stack smoke and one final `just verify`; no skipped/flaky/missing mandatory evidence. + +## Dev Notes + +### Current Brownfield State and Confirmed Defects + +- `crates/crank-core/src/operation.rs` has one conflated `OperationStatus` and no transition/CAS model. +- `crates/crank-registry/src/postgres/operation.rs::update_operation_draft` updates the current `operation_versions` JSON row in place. Publish leaves `current_draft_version` on that row, so the next UI PATCH rewrites Published behavior. +- Exact version builders and Agent/MCP queries currently obtain `name`, `display_name`, `category`, `protocol` and `security_level` from mutable `operations`; pinning `(operation_id,version)` alone is therefore insufficient. +- `create_version` computes next version before transaction/lock. `publish_operation` accepts any existing version and upserts a latest pointer without monotonic/state/archive guard. `archive_operation` mutates current version status. Some updates omit workspace predicate. +- Existing Agent bindings already store exact Operation version — preserve this good seam. Only new binding/publication to archived aggregate must be rejected; existing published Agent execution must remain intact. +- Draft test already traverses Runtime and persists Request/Trace IDs, but accepts arbitrary version and does not return IDs in successful result body. +- Export serializes `RegistryOperation`, including internal lifecycle/storage/wizard metadata; import reflects raw `serde_yaml` errors, lacks explicit complexity/format/unknown-field controls and races through lookup+create-version. +- Wizard always PATCHes current version, has no optimistic base token, and can race save/test/publish. Catalog exposes delete, not archive. Current lifecycle Playwright does not prove immutable publication or stale conflict recovery. +- Capability Inventory honestly blocks `ui-operation-lifecycle`, but API lifecycle/import flows currently claim implemented despite the confirmed integrity gaps. Evidence must be refreshed only after repair. + +### Architecture and Implementation Guardrails + +- Domain transition rules belong in `crank-core`; Admin services own use cases; Axum routes own transport; SQLx and transactions stay in `crank-registry`; apps remain composition roots. +- MigrationAuthority is the sole runtime DDL owner. Never modify immutable v1/v2/v3 sources/checksums or add startup DDL/local ledger. +- Every mutation carries full workspace scope and uses conditional state/version predicate inside the same transaction. No read-modify-write before transaction. +- Exact snapshot queries must not reconstruct version data from mutable aggregate columns. UI summaries may derive current view, but execution/export/history use version-local fields. +- Do not use a DB trigger as the only application rule, or service validation as the only immutability barrier; both layers are required. +- Do not solve stale writes with last-write-wins timestamps, browser-only flags or request ordering assumptions. Version is authoritative. +- Do not implement mutable rollback/latest-pointer rewind. Old content becomes new Draft/new version. +- Test results/errors use canonical Story 1.5 correlation; identifiers never enter metric labels. Any new metrics use Story 1.6 typed registry only. +- Libraries do not read environment. A new tunable runtime field, if truly needed, first enters `crank-config`; fixed protocol safety bounds above do not require env config. +- Keep Rust 1.96.1, Edition 2024, current dependency versions, Alpine/concatenated `window.Crank*`, Compose topology and Community boundary. + +### File Map + +**NEW expected** + +- `crates/crank-registry/src/migrations/operation_lifecycle_v4.sql` +- `docs/schemas/operation-export-v2.schema.json` +- `apps/admin-api/tests/integration/operation_lifecycle.rs` +- `apps/ui/tests/e2e/operation-lifecycle.spec.js` + +**UPDATE expected** + +- Core: `crates/crank-core/src/operation.rs` (or focused new lifecycle module + explicit re-export), its contract tests. +- Registry: `crates/crank-registry/src/{model.rs,error.rs,lib.rs}`, `src/postgres/{mod.rs,operation.rs,agent.rs}`, `src/migrations/{authority.rs,schema_guard.rs}`. +- Registry tests: `crates/crank-registry/tests/integration/{common.rs,migrations.rs,operations_artifacts.rs,agents_usage.rs,workspace_access.rs}`. +- Admin: `apps/admin-api/src/{app.rs,dto.rs,error.rs}`, `src/routes/operations.rs`, `src/service/{operations.rs,import_export.rs,operation_validation.rs,agents.rs}`. +- Admin tests: `apps/admin-api/tests/integration.rs`, `tests/integration/{common.rs,operations_agents.rs,secrets_import_auth.rs}` plus new lifecycle module. +- UI: `apps/ui/js/{api.js,catalog.js,wizard.js,wizard-live.js,i18n.js,ui-feedback.js}`, relevant `apps/ui/index.html`, `html/wizard/*.html`, `css/{pages.css,wizard.css}` and existing operation/wizard specs as needed. +- Contracts/docs/evidence: `docs/schemas/migration-sequence.json`, `docs/{admin-api.md,data-model.md,database-schema.md,migrations.md,ui.md,manual-regression-checklist.md,capability-inventory.json}`, `docs/capability-baseline/*`, `justfile`/CI only if a new direct contract gate is required. +- Local ignored: `_bmad-output/project-context.md` and this Story/sprint status; never force-add as canonical evidence. + +**Must not change** + +- `crates/crank-registry/src/migrations/baseline_v1.rs`, `consolidation_v2.sql`, `request_trace_identity_v3.sql` or their checksums/meaning. +- Existing Agent binding rows, published snapshots, Invocation History, request/trace middleware, MCP transport and REST runtime behavior. +- Cargo/npm/toolchain versions, deployment topology or Community scope. + +### Testing Requirements and Commands + +RED first: reproduce the exact current corruption before changing production code. Primary atomic coverage belongs to E1-14/15; E2E proves only cross-boundary outcomes. + +```bash +cargo test -p crank-core operation -- --test-threads=1 +cargo test -p crank-registry --test integration operations_artifacts -- --test-threads=1 +cargo test -p crank-registry --test integration agents_usage -- --test-threads=1 +cargo test -p crank-registry --test integration migrations -- --test-threads=1 +cargo test -p admin-api --test integration operation_lifecycle -- --test-threads=1 +cargo test -p admin-api --test integration operations_agents -- --test-threads=1 +cargo test -p admin-api --test integration secrets_import_auth -- --test-threads=1 +just migration-contract-check +scripts/check-rust-boundaries.sh +scripts/check-rust-module-boundaries.sh +just config-contract-check +just metrics-contract-check +just capability-inventory-check + +cd apps/ui +npm ci +npm run build +npx playwright test tests/e2e/operation-lifecycle.spec.js tests/e2e/operations.spec.js tests/e2e/wizard.spec.js --project=chromium +# Shared API/workspace code changed: run the full Playwright suite before completion. +npm run e2e + +cd ../../ +just authenticated-product-smoke http://localhost:3000 +just verify +git diff --check +python3 scripts/check-community-scope.py --root . --files +``` + +Required assertions: + +- Native-v4 Published version full semantic digest/row remains identical across PATCH/import/test/archive/delete attempts and process restart; legacy cutover records honest observed provenance without fabricated per-version timestamps/actors. +- 32 concurrent writers produce deterministic success/conflict outcomes, strictly increasing unique versions, no gaps under the selected one-winner policy, no 5xx. +- Direct SQL update/delete of Published snapshot and direct parent DELETE/cascade fail; never-published unreferenced Draft delete succeeds; migration rollback leaves v3 data byte/row equivalent. +- Aggregate ETag replay across Operation/workspace fails; exact-version ETag stays stable when aggregate/current/latest pointer changes. +- Agent MCP list/call result remains pinned before/after Operation edit/new publish/archive until explicit Agent republish. +- YAML canary does not occur in export, error JSON, logs, Playwright trace/report or committed evidence. +- No mandatory test is skipped/flaky/retry-promoted to pass. + +### UX Contract (Story-local because no standalone UX specification exists) + +- IA remains current Operations catalog → wizard edit URL. No new framework/top-level navigation. +- Catalog distinguishes Draft, Published and Archived in text + badge; action menu is permission/state aware. +- Publish/archive/delete confirmations name safe display value and exact version but never target URL/header/payload. +- A 409 never silently reloads over local input. UI shows localized conflict, current version, `Reload authoritative version` action and preserves unsaved text until user decides. +- Async state is valid only for captured `{workspace_id, operation_id, base_version, generation}`. Workspace/language change or newer request invalidates prior response. +- Busy controls expose `aria-busy`; results/errors use polite/assertive live regions as appropriate; focus moves to actionable error/confirmation and returns to trigger after close. +- Request/Trace IDs are safe support identifiers with explicit copy control. Full trace search/deep links remain Story 5.2. + +### Previous Story Intelligence + +- Story 1.6 completed Wave 0 and established typed metrics ownership. Lifecycle changes must use existing registry/facade; no raw metrics macros or ID labels. +- Story 1.5 established canonical IDs independent of exporter/sampling. Reuse correlation context; do not generate or conflate new IDs inside lifecycle services. +- Story 1.4 established migration authority and review lessons: exact-byte checksums, version-aware schema fingerprints, real vN→vN+1 rollback tests, no startup DDL, no fabricated provenance. +- Story 1.3 established a single typed config reader. Do not add local env parsing or silent defaults for YAML limits. +- Stories 1.1–1.2 require evidence from a clean implementation revision. Update baseline version/checksums separately after implementation tests; do not claim dirty-worktree evidence. +- Current worktree is clean except user-owned `.agents/`; preserve it and never add it to Story scope. + +### Git Intelligence + +- `7674284` freezes Story 1.6 review evidence; `b7face0` contains its final hardening. Reuse those correlation/metrics/boundary patterns. +- `f6fc2e5`/earlier Wave 0 work introduced typed config, migration and correlation contracts now binding this Story. +- Baseline for future development is current `HEAD` when `dev-story` starts; no push/tag/release/deploy is authorized. + +### Latest Technical Notes + +- Locked Axum 0.8 provides route-specific `DefaultBodyLimit`; apply the YAML limit before body extraction rather than reading an unbounded `String`. +- Locked SQLx 0.9 supports explicit PostgreSQL transactions and bound queries. Row-level `SELECT ... FOR UPDATE` protects the chosen aggregate row until transaction end; keep lock order stable and test deadlock/timeout mapping. +- PostgreSQL row triggers receive OLD/NEW records and can enforce immutable-row protection. The application transition oracle remains authoritative; trigger is defense in depth. +- `serde_yaml 0.9.34+deprecated` is already locked. Do not add/upgrade a parser inside this Story without explicit dependency approval; compensate with pre-parse byte/structure guards, closed DTO, duplicate/alias/tag rejection and hostile corpus. A future dependency replacement is a separate compatibility/security change. + +### References + +- [Source: `_bmad-output/planning-artifacts/epics.md` — dependency waves; Epic 1; Story 1.7] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` — FR-1; NFR-P3/P5, R2, S1/S2/S4/S8, O1/O4/O5, C1/C3/C4] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md` — Community/evidence decisions] +- [Source: `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` — AD-1/2/4/10/11/16/19/20/21 and conventions] +- [Source: `_bmad-output/planning-artifacts/implementation-readiness-report-2026-08-08.md` — FR-1 mapping, UI-heavy Story handoff and NFR evidence requirements] +- [Source: `_bmad-output/test-artifacts/test-design-progress.md` — E1-R-006 and E1-14/15/16] +- [Source: `_bmad-output/implementation-artifacts/1-6-typed-metrics-registry.md` — Wave 0 completion/review lessons] +- [Source: `_bmad-output/project-context.md` — migration, UI stale response, security, testing and evidence rules] +- [Axum 0.8 `DefaultBodyLimit`](https://docs.rs/axum/0.8.9/axum/extract/struct.DefaultBodyLimit.html) +- [SQLx 0.9 documentation](https://docs.rs/sqlx/0.9.0/sqlx/) +- [PostgreSQL row-level locking](https://www.postgresql.org/docs/current/explicit-locking.html#LOCKING-ROWS) +- [PostgreSQL trigger behavior](https://www.postgresql.org/docs/current/trigger-definition.html) + +## Dev Agent Record + +### Agent Model Used + +GPT-5.6 Codex + +### Debug Log References + +- RED: `cargo test -p crank-registry --test integration published_version_is_not_rewritten_by_a_later_save -- --test-threads=1` reproduced in-place corruption of Published v1. +- GREEN: the same PostgreSQL regression now passes after append-only save and version-local snapshot reads. +- Migration v4 suites cover honest v3 cutover provenance and injected transactional rollback; registry suites cover direct SQL guard, parent cascade, archive/delete policy and 32-way one-winner contention. + +### Implementation Plan + +- Preserve public enum spellings while separating aggregate availability from version state in the domain oracle. +- Introduce contiguous MigrationAuthority v4 with version-local snapshot fields and PostgreSQL defense-in-depth immutability trigger. +- Replace read/check/write lifecycle mutations with scoped row-lock transactions, then layer ETag and portable YAML v2 at Admin boundaries. + +### Completion Notes List + +- Implemented append-only Operation lifecycle with a typed state oracle, PostgreSQL v4 migration, native/legacy provenance, immutable Published rows and transactional CAS/row-lock mutations. +- Published edit now creates a new Draft; publish is monotonic/idempotent, archive never rewrites pinned snapshots, delete is limited to never-published unreferenced Drafts, and archived Operations reject new Agent bindings. +- Added identity-bound aggregate ETags, stable exact-version ETags, mandatory `If-Match`, safe lifecycle errors, current-Draft-only test execution and returned Request/Trace IDs. +- Replaced persistence YAML with closed portable v2 plus bounded/redacted parser, duplicate-key/unknown-field/tag/complexity defenses, semantic no-op upsert and legacy-v1 import compatibility. +- Added stale-safe catalog/wizard handling, archive/confirmation behavior, safe correlation display and RU/EN strings; Playwright combines backend lifecycle proof with real RU/EN catalog/wizard DOM journeys. +- Extended authenticated real-stack smoke: REST Draft test → publish → Agent/MCP call → edit/archive → pinned MCP list/call remains unchanged. +- Local implementation evidence passed before review: domain/registry/Admin targeted suites, migration/config/metrics/boundary contracts, SQLx offline prepare check, UI build, Playwright, explicit Community scan, real-stack smoke and final `just verify`. It is not promoted to canonical clean-revision evidence until the implementation revision exists and the baseline collector records its checksum. +- Owner decision 2026-08-14: the checksummed 2,000-Operation PRD Reference Deployment qualification is deferred to the final Epic 8 release gate, where it will measure the finished product. Story 1.7 makes no formal p95 claim and proceeds to review on its complete functional evidence. + +### Review Findings + +- [x] [Review][Patch] Make `If-Match` part of the same PostgreSQL transaction as PATCH/create-version/archive/delete/YAML-upsert instead of a route-level check vulnerable to TOCTOU races [apps/admin-api/src/routes/operations.rs:208] +- [x] [Review][Patch] Serialize Agent binding/publication with Operation archive under a workspace-scoped row lock; reject new bindings to archived Operations while preserving existing snapshots [crates/crank-registry/src/postgres/mod.rs:251] +- [x] [Review][Patch] Resolve `auth_profile_ref` in the authenticated workspace before save/import and again at publish admission [apps/admin-api/src/service/operations.rs:406] +- [x] [Review][Patch] Close the complete nested portable YAML v2 contract and make the published JSON Schema match the Rust importer [docs/schemas/operation-export-v2.schema.json:28] +- [x] [Review][Patch] Reject credential-bearing header values and non-standard credential header names in portable import/export [apps/admin-api/src/service/import_export.rs:396] +- [x] [Review][Patch] Add database guardrails against deletion/rewind of `published_operations` and `operations.latest_published_version` [crates/crank-registry/src/migrations/operation_lifecycle_v4.sql:41] +- [x] [Review][Patch] Reject every YAML upsert to an archived aggregate, including semantic no-op, and decide equality under the locked CAS boundary [apps/admin-api/src/service/import_export.rs:107] +- [x] [Review][Patch] Permit export only for the active current Draft or an explicitly selected Published Version [apps/admin-api/src/service/import_export.rs:31] +- [x] [Review][Patch] Distinguish invalid UTF-8 from body-limit rejection instead of reporting all `StringRejection` values as oversized YAML [apps/admin-api/src/routes/operations.rs:352] +- [x] [Review][Patch] Map concurrent workspace/name uniqueness races to a stable typed conflict for create and upsert [apps/admin-api/src/service/operations.rs:167] +- [x] [Review][Patch] Return persisted publication/archive timestamps on idempotent retries instead of newly generated timestamps [apps/admin-api/src/service/operations.rs:438] +- [x] [Review][Patch] Preserve publication markers in the catalog model; offer hard delete only for never-published unreferenced Drafts and archive otherwise [apps/ui/js/catalog.js:35] +- [x] [Review][Patch] Add a wizard-wide lifecycle action mutex/generation guard so different action buttons cannot race persistence [apps/ui/js/wizard-live.js:212] +- [x] [Review][Patch] Expose aggregate availability and exact version state consistently; never report an archived aggregate as an archived version row [apps/admin-api/src/dto.rs:514] +- [x] [Review][Patch] Reject YAML anchors/aliases before serde materializes them, with bounded regression fixtures [apps/admin-api/src/service/import_export.rs:260] +- [x] [Review][Patch] Bound revision conversion at PostgreSQL `i32::MAX` and return a typed lifecycle conflict instead of wrapping [apps/admin-api/src/service/operations.rs:278] +- [x] [Review][Patch] Replace API-only lifecycle Playwright evidence with actual RU/EN DOM journeys covering actions, stale recovery, confirmations and correlation controls [apps/ui/tests/e2e/operation-lifecycle.spec.js:9] +- [x] [Review][Patch] Persist only normalized safe runtime error codes/messages in lifecycle invocation history; never raw `RuntimeError::to_string()` [apps/admin-api/src/service/operations.rs:636] +- [x] [Review][Patch] Correct completion/evidence wording: local green runs are not canonical clean-revision evidence until collected after the implementation revision exists [docs/capability-baseline/results.json:224] + +### File List + +- `_bmad-output/implementation-artifacts/1-7-immutable-lifecycle-operation.md` +- `_bmad-output/implementation-artifacts/sprint-status.yaml` +- `.sqlx/query-*.json` (27 regenerated checked SQLx query descriptors) +- `apps/admin-api/src/{app.rs,auth.rs,dto.rs,error.rs}` +- `apps/admin-api/src/routes/operations.rs` +- `apps/admin-api/src/service/{demo.rs,import_export.rs,operations.rs}` +- `apps/admin-api/tests/{integration.rs,migration_command.rs}` +- `apps/admin-api/tests/integration/{common.rs,operation_lifecycle.rs,operations_agents.rs,secrets_import_auth.rs}` +- `apps/ui/{index.html,html/wizard/step5.html}` +- `apps/ui/js/{api.js,catalog.js,i18n.js,wizard-live.js}` +- `apps/ui/tests/e2e/{operation-lifecycle.spec.js,operations.spec.js,wizard.spec.js}` +- `crates/crank-core/src/{lib.rs,operation.rs}` +- `crates/crank-registry/src/{error.rs}` +- `crates/crank-registry/src/migrations/{authority.rs,operation_lifecycle_v4.sql,schema_guard.rs}` +- `crates/crank-registry/src/migrations/authority_tests.rs` +- `crates/crank-registry/src/postgres/{agent.rs,mod.rs,operation.rs,operation_published.rs}` +- `crates/crank-registry/tests/integration/{migrations.rs,operations_artifacts.rs}` +- `docs/{admin-api.md,data-model.md,database-schema.md,manual-regression-checklist.md,migrations.md,operation-lifecycle.md,ui.md}` +- `docs/en/migrations.md` +- `docs/schemas/{migration-sequence.json,operation-export-v2.schema.json}` +- `docs/capability-inventory.json` +- `docs/capability-baseline/{manifest.json,manual-checklist.md,outcome-taxonomy.json,required-surfaces.json,results.json}` +- `scripts/authenticated-product-smoke.py` +- `tests/unit/test_authenticated_product_smoke.py` + +## Change Log + +- 2026-08-14: Story 1.7 created as implementation-ready contract for append-only Operation revisions, immutable publication, safe archive/delete, bounded YAML portability and RU/EN stale-safe lifecycle UI. +- 2026-08-14: Implemented and regression-tested the lifecycle vertical; status is blocked only on the unavailable checksummed PRD Reference Deployment performance qualification. +- 2026-08-14: Product owner deferred the reference performance qualification to Epic 8; Story 1.7 moved to review without making a performance claim. +- 2026-08-15: Adversarial review closed all 19 findings; full Rust/UI/contract regression passed and Story 1.7 moved to done. diff --git a/_bmad-output/implementation-artifacts/1-8-rest-execution-boundary-errors.md b/_bmad-output/implementation-artifacts/1-8-rest-execution-boundary-errors.md new file mode 100644 index 0000000..64ff4e0 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-8-rest-execution-boundary-errors.md @@ -0,0 +1,465 @@ +--- +story_id: "1.8" +story_key: "1-8-rest-execution-boundary-errors" +requirement: "FR-2" +status: "done" +baseline_commit: "767428436d3a54e60809a727044dfcec48e1f1dd" +--- + +# Story 1.8: Унифицировать REST execution и boundary errors + +Status: done + +## Story + +As an администратор или MCP-пользователь, +I want получать одинаковое и предсказуемое выполнение Operation через UI и MCP, +so that результат и классификация ошибки не зависят от входной точки. + +## Strategic Intent + +Story 1.8 закрепляет единственную синхронную execution boundary существующего REST → MCP продукта после immutable Operation lifecycle из Story 1.7. Сегодня Admin Test и MCP `tools/call` оба вызывают runtime, но собирают неполный `RuntimeExecutionRequest`, разрешают optional correlation/scope, отдельно резолвят auth и независимо преобразуют `RuntimeError` в несовпадающие коды, сообщения и retryability. Admin history также способен сохранить `error.to_string()`, содержащий внутренние детали. + +Итоговый контракт: Admin Draft Test и MCP exact Published Tool создают один полностью scoped typed request, проходят один runtime/adapter pipeline и получают один внутренний normalized outcome. HTTP и MCP отвечают своими wire-формами, но сохраняют одинаковые stage, stable code, retryability, outcome certainty, Request ID и Trace ID. Никакая boundary не анализирует текст ошибки и не знает варианты `RestAdapterError`. + +Story является обязательным predecessor для 1.9 outbound/SSRF hardening, 1.13 immutable Agent catalog, Epic 3 dynamic capabilities и Epic 4 Tasks. Она не реализует DNS/redirect/retry policy, background Tasks, новый MCP wire revision или History UI. + +**Requirement:** FR-2 +**Architecture:** AD-1, AD-2, AD-4, AD-9, AD-11, AD-15, AD-19, AD-21, AD-23; consistency conventions +**Applicable NFR:** NFR-P4, NFR-R1, NFR-S1, NFR-S2, NFR-S4, NFR-S7, NFR-S8, NFR-O1, NFR-O4, NFR-O5, NFR-C1, NFR-C4 +**Primary risk/evidence:** E1-R-007 (score 9); E1-17, E1-18, E1-19. + +## Acceptance Criteria + +1. **Один обязательный typed execution envelope** + - Given Admin Test или MCP `tools/call` + - When application layer принимает выполнение + - Then она создаёт ровно один `RuntimeExecutionRequest` с typed `WorkspaceId`, origin (`admin_draft|agent_snapshot`), optional typed `AgentId` только по правилам origin, exact `OperationId/version`, authorization decision/resolved auth, input, monotonic deadline, canonical correlation, approval и idempotency context + - And production constructor не допускает отсутствующий workspace, operation/version, deadline или correlation и не генерирует fallback IDs внутри runtime + - And secret-bearing resolved auth, confirmation и idempotency material не реализуют раскрывающий `Debug`/`Display`/`Serialize`; fingerprint/context хранит только необходимые typed or redacted values + - And invalid/missing/incompatible scope отклоняется до mapping, adapter lookup и outbound dispatch. + +2. **Единый pipeline без transport bypass** + - Given валидный execution envelope + - When начинается выполнение + - Then оба ingress проходят `RuntimeExecutionRequest → crank-runtime → ProtocolAdapter → crank-adapter-rest` + - And route/transport/service не вызывает REST client, SQLx persistence implementation или mapping/schema implementation напрямую + - And test-only convenience methods не остаются доступным production bypass. + +3. **Admin исполняет только exact current saved Draft** + - Given active Operation и выбранная current Draft revision + - When Admin запускает Test + - Then application resolution из Story 1.7 фиксирует exact saved version до runtime admission и origin равен `admin_draft` + - And unsaved browser state, Published/archived/non-current/foreign version отклоняется до dispatch + - And выполнение не публикует Draft и не меняет Agent catalog. + +4. **MCP исполняет только exact immutable Agent snapshot** + - Given авторизованный опубликованный Agent snapshot + - When клиент вызывает Tool + - Then tool resolution фиксирует exact Published Operation version из immutable binding и origin равен `agent_snapshot` с typed Agent ID + - And Draft, archived-new-binding, foreign Agent, непредоставленный Tool или capability вне snapshot получает safe not-found/denied без metadata leakage и без adapter call + - And existing pinned Agent behavior из Story 1.7 сохраняется. + +5. **Один normalized success outcome** + - Given одинаковые exact Operation version, input, auth и deterministic upstream response + - When вызов выполнен через Admin и MCP + - Then schema validation, input mapping, request preparation, adapter execution, output mapping и output schema validation дают семантически одинаковый normalized output + - And HTTP Test DTO и MCP content/result являются только transport projections этого outcome + - And transport-specific envelope, status и localization не входят в runtime domain contract. + +6. **Закрытая typed failure taxonomy** + - Given failure на `authorization|input_schema|input_mapping|request_preparation|admission|adapter|upstream|output_mapping|output_schema|mandatory_persistence|runtime` + - When failure покидает owning layer + - Then она преобразуется один раз в framework-free `ExecutionFailure` с closed `stage`, stable `error_code`, `retryability`, `outcome_certainty`, optional bounded safe context и correlation + - And HTTP/MCP/history/metrics используют этот descriptor, не повторяют match по `RuntimeError`/`RestAdapterError` и не выводят raw cause + - And unknown internal failure fail closed как `runtime_internal`, `retryability=never`, без произвольного текста. + +7. **Фиксированная retryability/certainty семантика** + - Given typed failure + - When клиент или оператор решает, можно ли повторять + - Then retryability принимает только `never|safe|after_delay|manual_reconcile|requires_confirmation`, а certainty — `certain|outcome_unknown` + - And validation/auth/not-found/conflict являются `never`; overload/known pre-dispatch transport failure — `after_delay`; confirmation — `requires_confirmation`; ambiguous write/cancellation after dispatch — `manual_reconcile + outcome_unknown` + - And `outcome_unknown` никогда не превращается в recoverable/automatic retry по тексту, HTTP status или MCP transport status. + +8. **Deadline, timeout и cancellation не дают ложный success** + - Given bounded monotonic deadline или cancellation + - When deadline истекает до dispatch, во время adapter wait либо после возможной отправки write + - Then runtime возвращает typed stage/certainty согласно фактически достигнутой dispatch boundary + - And cancelled idempotent execution завершает coordination state безопасно; cleanup failure не меняет внешний outcome и создаёт bounded operational incident + - And один upstream response/side effect не учитывается дважды. + +9. **Persistence semantics честны** + - Given completed success/failure + - When Invocation History сохраняется + - Then новая запись сохраняет Request ID, Trace ID, source, exact Operation/version, stage, error code, retryability и outcome certainty независимо от sampling + - And schema evolution выполняется только append-only MigrationAuthority v5 с N/N-1 nullable compatibility; v1–v4 source/checksum не меняются + - And отказ обязательного pre-dispatch safety persistence блокирует dispatch, а отказ post-outcome diagnostic history сохраняет product outcome и создаёт typed History Loss incident (DC-08), не подменяя success на failure. + +10. **Safe localized boundaries** + - Given normalized success/failure + - When формируется Admin Test или MCP response + - Then обе boundary возвращают stable `error_code`, stage, explicit retryability/certainty, bounded RU/EN message согласно выбранной locale и одинаковые safe Request/Trace IDs + - And raw upstream body, URL, headers, credential, SQLx/Reqwest/parser text, internal path и arbitrary payload отсутствуют в response, history message, logs, traces, metrics и evidence + - And существующие HTTP route paths, MCP method names/protocol negotiation и успешные response fields сохраняются; additive error fields документированы. + +11. **Typed observability без cardinality regression** + - Given execution success или любая failure stage + - When записываются spans/metrics/history + - Then используются существующие typed `crank-trace` stages и `crank-metrics` outcome enums; Request/Trace/Object IDs не становятся labels + - And один execution создаёт согласованный terminal metric outcome, а Trace ID используется только как exemplar/trace field + - And redaction/preview остаются bounded valid UTF-8/JSON, включая oversized malformed upstream/error canaries. + +12. **Паритет и архитектура доказаны executable gates** + - Given Story implementation + - When выполняются E1-17/E1-18/E1-19 suites + - Then table-driven matrix сравнивает Admin и MCP для success и всех stages по normalized output/code/stage/retryability/certainty/IDs и точному adapter call count + - And negative architecture fixtures ловят direct adapter/persistence call, alias, re-export и helper bypass + - And targeted suites, migration/SQLx checks, Capability Inventory, explicit Community scan, real REST→MCP smoke и `just verify` проходят без dependency/toolchain/public-success-wire changes. + +## Frozen Execution Taxonomy + +| Stage | Representative failures | Default retryability | Certainty | +| --- | --- | --- | --- | +| `authorization` | missing/foreign scope, revoked/missing profile/secret | `never` | `certain` | +| `input_schema` | input violates schema | `never` | `certain` | +| `input_mapping` | JSONPath/mapping failure | `never` | `certain` | +| `request_preparation` | malformed mapped header/path/query/body | `never` | `certain` | +| `admission` | concurrency/mandatory coordination unavailable | `after_delay` for overload/store outage; otherwise `never` | `certain` | +| `adapter` | unsupported protocol/config before dispatch | `never` | `certain` | +| `upstream` | status/transport/timeout | derived by typed dispatch evidence, never message text | `certain` or `outcome_unknown` | +| `output_mapping` | response mapping failure | `never` | `certain` | +| `output_schema` | mapped response violates schema | `never` | `certain` | +| `mandatory_persistence` | required safety record unavailable before acknowledgement | `after_delay` | `certain` | +| `runtime` | invariant/internal normalized failure | `never` | `certain` | + +Additional non-error control outcomes such as `requires_confirmation`, idempotency `in_progress|conflict|outcome_unknown` remain explicit typed outcomes and map into the same retryability/certainty vocabulary. HTTP status and MCP `isError` are projections, not sources of truth. + +### Frozen machine codes + +`error_code` является closed enum, а не произвольной строкой. Минимальный v1 vocabulary: + +| Stage/control | Stable codes | +| --- | --- | +| authorization | `authorization_denied`, `auth_profile_not_found`, `secret_not_found`, `secret_invalid` | +| input_schema | `input_schema_invalid` | +| input_mapping | `input_mapping_invalid` | +| request_preparation | `prepared_request_invalid` | +| admission | `execution_overloaded`, `safety_store_unavailable` | +| adapter | `protocol_unsupported`, `execution_mode_unsupported`, `adapter_configuration_invalid`, `outbound_target_rejected` | +| upstream | `upstream_auth_error`, `upstream_not_found`, `upstream_rate_limited`, `upstream_server_error`, `upstream_status_error`, `upstream_timeout`, `upstream_transport_error`, `upstream_response_too_large` | +| output_mapping | `output_mapping_invalid` | +| output_schema | `output_schema_invalid` | +| mandatory_persistence | `persistence_unavailable` | +| runtime | `runtime_internal` | +| control | `confirmation_required`, `confirmation_invalid`, `idempotency_in_progress`, `idempotency_conflict`, `idempotency_outcome_unknown` | + +Новое значение требует изменения typed enum, exhaustive parity table, RU/EN catalog и versioned contract evidence в одном change. Story 1.9 может уточнить typed upstream/outbound causes, но не переименовывает опубликованные v1 codes. + +## Tasks / Subtasks + +- [x] Task 1 — Freeze RED parity oracle and current bypass inventory (AC: 1–12) + - [x] Add table-driven fixtures proving current Admin/MCP code/stage/recoverable mismatches, raw history error leakage and optional-context fallback. + - [x] Instrument fake adapter/store call counters; every pre-dispatch rejection asserts zero calls and every accepted execution asserts exactly one expected adapter call. + - [x] Record current public success DTO/MCP output snapshots and Story 1.7 exact Draft/Agent resolution invariants. + +- [x] Task 2 — Introduce framework-free execution identity/outcome contract (AC: 1, 5–8, 10) + - [x] Add closed `ExecutionOrigin`, `ExecutionStage`, `ExecutionErrorCode`, `Retryability`, `OutcomeCertainty`, `ExecutionFailure` and normalized success/outcome types in the lowest framework-free owner (`crank-core`), with bounded safe context only. + - [x] Define exact serialization only where a durable/internal contract requires it; domain types remain distinct from HTTP/MCP DTOs. + - [x] Add exhaustive constructor/truth-table tests; forbid unknown stage/code or incompatible retryability/certainty combinations. + +- [x] Task 3 — Make `RuntimeExecutionRequest` complete and non-optional (AC: 1–4, 8) + - [x] Require typed scope/origin/exact target, input, deadline, correlation, authorization, approval and idempotency context at construction. + - [x] Remove production fallback ID/context generation and convenience `execute_with_*` bypasses; migrate tests to an explicit fixture builder unavailable to production callers. + - [x] Validate origin invariants (`admin_draft` has no Agent; `agent_snapshot` requires Agent and immutable binding) before mapping/dispatch. + +- [x] Task 4 — Centralize runtime stage and error normalization (AC: 5–8, 11) + - [x] Split oversized executor/error responsibilities into focused modules before crossing code-health ceilings; keep one terminal outcome recorder. + - [x] Normalize schema/mapping/preparation/admission/protocol/adapter/upstream/output errors once and retain internal source only for redacted diagnostics. + - [x] Add deadline/cancellation/dispatch-evidence seam and deterministic tests for before-dispatch, known-no-dispatch and ambiguous-after-dispatch cases. + +- [x] Task 5 — Unify Admin Draft execution composition (AC: 1–3, 5, 9–10) + - [x] Preserve Story 1.7 exact current-Draft resolution and construct the full envelope after authorization/scope checks. + - [x] Replace local `runtime_error_code`/`runtime_test_failure` branching and raw `error.to_string()` history message with normalized outcome projection. + - [x] Keep Test route/success fields; add stable stage/retryability/certainty fields and localized safe failures with Request/Trace IDs. + - [x] Update the existing wizard Test result/error projection to localize the stable code in RU/EN, retain loading/recovery and safe ID copy behavior, and ignore stale operation/workspace responses; no new page or frontend framework. + +- [x] Task 6 — Unify MCP snapshot and approved execution composition (AC: 1–5, 9–10) + - [x] Preserve exact immutable Agent binding resolution for direct and approved tool calls and construct the same full envelope. + - [x] Replace adapter-specific matching in `tool_error.rs`; MCP boundary projects only normalized execution outcome. + - [x] Keep protocol negotiation/JSON-RPC/`isError` semantics and confirmation flow compatible across supported MCP revisions. + +- [x] Task 7 — Persist honest execution classification via migration v5 (AC: 7–9) + - [x] Add contiguous transactional exact-byte checksummed `execution_outcome_v5.sql`; never alter v1–v4. + - [x] Add nullable N-1 compatible fields/indexes/checks for exact operation version, stage, stable error code, retryability and certainty; legacy rows remain explicitly unknown rather than fabricated. + - [x] Update registry models/queries, version-aware schema fingerprint, SQLx metadata and fresh/v4→v5/replay/rollback/corruption tests. + +- [x] Task 8 — Build Admin/MCP differential contract suite (AC: 3–12) + - [x] Cover success, every frozen stage, missing/foreign scope, timeout, cancellation, overload, confirmation, idempotency conflict/outcome-unknown and history loss. + - [x] Compare normalized semantic output plus code/stage/retryability/certainty/correlation; assert transport-only differences explicitly. + - [x] Add secret/body/URL/path canaries to response/history/log/trace/metric capture and concurrency isolation tests. + +- [x] Task 9 — Harden architecture guardrails (AC: 2, 12) + - [x] Extend scanner to reject direct REST adapter/client or persistence execution from Admin/MCP routes/services and forbidden dependency/re-export/helper aliases. + - [x] Scan tracked plus explicit untracked Rust candidates, fail closed on symlinks/missing paths and add negative fixtures for each bypass spelling. + - [x] Preserve valid composition-root adapter construction and runtime→protocol-adapter dependency direction. + +- [x] Task 10 — Docs, evidence and final qualification (AC: 10–12) + - [x] Update runtime/error/Admin/MCP/history/migration docs and RU/EN message catalog; document additive error fields and no automatic retry for unknown outcome. + - [x] Refresh Capability Inventory/baseline only after accepted evidence; do not claim 1.9 SSRF/retry hardening complete. + - [x] Run targeted/differential/PG/MCP suites, migration+SQLx/config/metrics/boundary checks, real authenticated product smoke, explicit Community scan and one final `just verify`. + +### Review Findings + +- [x] [Review][Patch] [High] Закрыть production bypass обязательного execution envelope: поля `RuntimeExecutionRequest` и raw `execute_request` не должны позволять обойти `try_new`/normalized outcome [`crates/crank-runtime/src/execution_request.rs`:14] +- [x] [Review][Patch] [High] Удалить отдельный Admin mapping-preview short circuit и выполнять mapping ровно один раз внутри canonical runtime pipeline [`apps/admin-api/src/service/operations.rs`:601] +- [x] [Review][Patch] [High] Передавать точную dispatch evidence и mutability во все REST failures, включая connect/DNS, status, invalid/oversized response и deadline [`crates/crank-adapter-rest/src/lib.rs`:62] +- [x] [Review][Patch] [High] Исправить idempotency lifecycle: pre-dispatch failure/cancellation освобождает reservation, а post-dispatch completion failure становится `manual_reconcile + outcome_unknown` [`crates/crank-runtime/src/executor.rs`:370] +- [x] [Review][Patch] [High] Не терять normalized outcome и correlation при отказе финального сохранения approved execution [`crates/crank-community-mcp/src/approval_execution.rs`:303] +- [x] [Review][Patch] [High] Убрать открытый MCP string taxonomy и проводить authorization/control failures через closed typed descriptor и history [`crates/crank-community-mcp/src/tool_error.rs`:69] +- [x] [Review][Patch] [High] Закрыть v5 error-code vocabulary и проверять точные определения constraints/index, а не только их имена [`crates/crank-registry/src/migrations/execution_outcome_v5.sql`:8] +- [x] [Review][Patch] [Medium] Запретить новым application writes сохранять Invocation History без exact version и полной execution classification, сохранив nullable только для legacy N-1 rows [`crates/crank-registry/src/postgres/observability.rs`:42] +- [x] [Review][Patch] [High] Расширить execution-boundary gate на raw runtime, adapter invocation, SQLx/persistence, mapping/schema, aliases/re-exports/helpers и весь MCP production subtree [`scripts/check-execution-boundaries.py`:11] +- [x] [Review][Patch] [High] Добавить реально исполняемую Admin/MCP differential matrix для success, всех frozen stages, call counts, IDs, history, redaction и concurrency; исправить ложные completion claims [`_bmad-output/implementation-artifacts/1-8-rest-execution-boundary-errors.md`:196] +- [x] [Review][Patch] [Medium] Провести выбранную RU/EN locale через обе boundary и исправить ошибочное размещение русских execution keys внутри английского UI-каталога [`apps/ui/js/i18n.js`:787] +- [x] [Review][Patch] [Medium] Добавить workspace/operation/generation guard для результата Wizard Test после каждого await [`apps/ui/js/wizard-live.js`:832] +- [x] [Review][Patch] [High] Восстановить typed confirmation challenge в Admin Test response и поддержать подтверждённый повтор без раскрытия token через Debug/logs [`apps/admin-api/src/error.rs`:529] +- [x] [Review][Patch] [Medium] Отличать недоступность PostgreSQL при auth resolution от повреждённого секрета и не классифицировать storage failure как `secret_invalid + never` [`crates/crank-community-mcp/src/app.rs`:995] +- [x] [Review][Patch] [High] Санитизировать и ограничивать Admin request preview до HTTP projection, исключив credential/header/body canaries [`apps/admin-api/src/service/operations.rs`:703] +- [x] [Review][Patch] [High] Удалить revealing `Debug`/`Serialize` у secret-bearing `PreparedRequest` либо отделить redacted domain type от adapter wire type [`crates/crank-core/src/ext/protocol.rs`:116] +- [x] [Review][Patch] [Medium] Сделать `ExecutionFailure` code-specific и bounded: запретить confirmation/retry metadata на несовместимых codes и ограничить token/TTL [`crates/crank-core/src/execution.rs`:441] + +## Dev Notes + +### Current Brownfield State and Confirmed Gaps + +- `RuntimeExecutionRequest` currently holds only `operation`, `input`, optional resolved auth and optional request context. Workspace/origin/Agent/deadline/authorization decision are implicit; `RuntimeExecutor` can generate fallback IDs/context. +- Admin Test and both MCP direct/approved paths already call `execute_request`, which is the correct seam to strengthen. Do not create a second orchestrator. +- Admin resolves exact current Draft after Story 1.7; MCP resolves exact immutable published binding. Preserve these separate application-resolution rules, then converge only at the runtime envelope. +- Admin owns `runtime_error_code` plus `runtime_test_failure_*`; MCP owns another `runtime_error_code`, safe-message, recoverable and action matrix and directly matches `RestAdapterError`. Codes already diverge (`schema_error` vs `schema_validation_error`, `rest_error` vs status-specific upstream codes). +- `RuntimeError` wraps library-specific errors and does not encode stage, retryability, dispatch certainty or deadline/cancellation. Several Display implementations contain operation/secret IDs, URL/target or internal reasons; they are not boundary-safe. +- Admin failure history currently writes `error.to_string()` into `message`. This is a confirmed NFR-S2/O5 violation risk even when HTTP response is sanitized. +- Invocation History stores source/status/error_kind and correlation, but not exact operation version, stage, retryability or certainty. Migration v5 is required for honest persisted classification; old rows must remain nullable/unknown. +- Post-outcome history failure is intentionally non-fatal (DC-08) in Admin and MCP. Preserve external success and emit the existing bounded loss incident; do not make diagnostic persistence a hidden correctness dependency. +- REST adapter policy/security defects belong to Story 1.9. Story 1.8 may expose dispatch evidence and normalize errors but must not claim DNS/redirect/proxy/retry policy qualification. + +### Architecture and Implementation Guardrails + +- `crank-core` owns framework-free execution vocabulary/ports only; it must not import Tokio, Axum, SQLx, Reqwest, tracing or adapter error types. +- `crank-runtime` owns orchestration and typed normalization; it may call protocol adapters but never registry/Axum/SQLx. It must not persist history. +- Apps remain composition roots and own exact Draft/Agent resolution, auth-profile/secret resolution and transport projection. Routes do not call runtime/adapter directly. +- Boundary DTOs remain in Admin `dto.rs` and MCP transport/tool error owners. Do not serialize `RuntimeError` or expose source chains. +- Internal `ExecutionFailure` must carry stable bounded fields, never a raw `String` cause. Diagnostic source is logged only through existing redaction vocabulary. +- Use Story 1.5 `CorrelationContext`/typed IDs and Story 1.6 typed stages/metrics/exemplars. Never regenerate IDs in runtime or add object/error text labels. +- MigrationAuthority is the sole DDL owner. Add v5, update machine sequence/schema fingerprint/SQLx metadata, preserve N/N-1 reads and controlled migrator-only writes. +- Keep Rust 1.96.1/Edition 2024, current dependencies, Compose, Alpine UI, MCP revisions and Community boundary unchanged. + +### File Map + +**NEW expected** + +- `crates/crank-core/src/execution.rs` — closed framework-free identity/outcome taxonomy. +- `crates/crank-runtime/src/execution_failure.rs` and/or focused executor stage/deadline module. +- `crates/crank-registry/src/migrations/execution_outcome_v5.sql`. +- `apps/admin-api/tests/integration/execution_parity.rs` or a shared cross-app contract fixture at the lowest reusable test owner. +- Focused boundary scanner fixtures/tests if existing scripts cannot express direct execution ownership safely. +- `docs/execution-contract.md` — canonical stage/code/retryability/certainty and Admin/MCP projection contract. + +**UPDATE expected** + +- Core: `crates/crank-core/src/{lib.rs,observability.rs,ext/protocol.rs}` only as required by the new contract. +- Runtime: `crates/crank-runtime/src/{lib.rs,error.rs,executor.rs,request_context.rs,model.rs}` and focused tests; split rather than grow `executor.rs` beyond its current debt ceiling. +- REST adapter: `crates/crank-adapter-rest/src/{error.rs,lib.rs,client.rs}` only for typed dispatch evidence/normalization seam; network policy changes remain 1.9. +- Admin: `apps/admin-api/src/{dto.rs,error.rs,service.rs}`, `src/service/operations.rs`, `src/routes/operations.rs`; integration common/lifecycle/operations tests. +- UI (only if the additive Test failure fields require presentation): `apps/ui/js/{wizard-live.js,i18n.js,api.js}` and the existing lifecycle/wizard Playwright specs; preserve all Story 1.7 stale/ETag behavior. +- MCP: `crates/crank-community-mcp/src/{app.rs,approval_execution.rs,tool_error.rs}`, invocation-history helper and integration/unit tests. Extract focused modules rather than grow `app.rs`. +- Registry: `crates/crank-registry/src/{model.rs,postgres/observability.rs,postgres/mod.rs}`, migration authority/schema guard/tests and generated `.sqlx/query-*.json`. +- Guardrails: `scripts/check-rust-module-boundaries.sh` and/or Python boundary checker plus unit fixtures; `justfile` only if a distinct executable gate is necessary. +- Docs/evidence: `docs/{execution-contract.md,admin-api.md,mcp-interface.md,observability.md,migrations.md,data-model.md,database-schema.md,capability-inventory.json}`, migration sequence schema and baseline artifacts. +- Local ignored: this Story, sprint status and `_bmad-output/project-context.md`; never force-add them as canonical evidence. + +**Must not change** + +- Migration v1/v2/v3/v4 source bytes/checksums or Story 1.7 immutable Operation semantics. +- Outbound allow/deny/DNS/redirect/proxy/retry implementation except the minimal typed evidence seam explicitly needed by this Story. +- Public successful Admin/MCP response semantics, protocol revision negotiation, dependency/toolchain versions or deployment topology. + +### Testing Requirements and Commands + +RED first: prove existing classification divergence and optional-scope bypass before production edits. + +```bash +cargo test -p crank-core execution -- --test-threads=1 +cargo test -p crank-runtime --all-targets -- --test-threads=1 +cargo test -p crank-adapter-rest --all-targets -- --test-threads=1 +cargo test -p admin-api --test integration execution_parity -- --test-threads=1 +cargo test -p admin-api --test integration operation_lifecycle -- --test-threads=1 +cargo test -p admin-api --test integration operations_agents -- --test-threads=1 +cargo test -p crank-community-mcp --all-targets -- --test-threads=1 +cargo test -p mcp-server --test integration -- --test-threads=1 +cargo test -p crank-registry --test integration migrations -- --test-threads=1 +cargo test -p crank-registry --test integration observability -- --test-threads=1 +just migration-contract-check +just sqlx-check +just config-contract-check +just metrics-contract-check +just rust-boundaries +just capability-inventory-check +python3 -m unittest discover -s tests/unit +just authenticated-product-smoke http://localhost:3000 +just verify +git diff --check +python3 scripts/check-community-scope.py --root . --files +``` + +Required assertions: + +- Admin and MCP normalized outcomes match for all frozen stages; raw wire difference is explicitly projected and snapshot-tested. +- Every pre-dispatch failure observes adapter call count `0`; every accepted unary execution observes exactly `1`; cancellation/unknown tests record dispatch evidence deterministically without sleeps. +- Request/Trace IDs match ingress, runtime, captured upstream and history and remain distinct with telemetry sampling/export disabled. +- Foreign workspace/Agent/Tool probes return one non-disclosing outcome and do not access adapter/history rows of the foreign object. +- Canary credential, URL, body, parser, SQLx and host path never appears in boundary JSON/MCP content/history message/log/span/metric/evidence. +- v4→v5 preserves all rows, fresh/replay/rollback/corrupt states are deterministic, N-1 writer/read compatibility is explicit, and no old migration bytes change. +- No skipped/flaky/retry-promoted mandatory evidence. + +### Previous Story Intelligence + +- Story 1.7 now guarantees exact immutable Operation versions, current-Draft test resolution, ETag/CAS lifecycle and pinned Agent behavior. Reuse these facts; do not reimplement lifecycle checks inside runtime. +- Story 1.7 exposed why persisted diagnostic claims must be honest: legacy fields remain unknown rather than fabricated. Apply the same rule to new v5 classification columns. +- Story 1.5 provides canonical correlation independent of telemetry sampling; production runtime fallback ID generation is now an anti-pattern. +- Story 1.6 provides closed stage/outcome metrics and exemplars; extend typed registry only when truly necessary and never mirror the error code as an unbounded label. +- Story 1.4 requires exact-byte append-only migration authority and version-aware fingerprints. The next schema version is v5. +- Product owner deferred Reference Deployment performance qualification to Epic 8. Story 1.8 still adds deterministic local overhead/adapter-call regressions but makes no formal NFR-P4 release claim. + +### Git Intelligence + +- Current committed baseline `7674284` freezes Story 1.6. Story 1.7 implementation is present in the shared worktree and is a hard predecessor even though it has not been committed by this workflow. +- Preserve the full existing Story 1.7 diff and `.agents/`; do not reset, stage, commit, push, tag or deploy without explicit owner authorization. +- Recent patterns to reuse: framework-free typed contracts, closed enums, version-aware MigrationAuthority, SQLx offline metadata, table-driven parity/security tests and explicit Community scan. + +### Latest Technical Notes + +- No dependency upgrade or new external library is required. Use locked Rust 1.96.1, Axum 0.8, Tokio 1, SQLx 0.9, Reqwest 0.12 and existing internal abstractions. +- Tokio cancellation is drop-based; a future being dropped is not itself evidence whether a write reached the upstream. Preserve explicit dispatch evidence and idempotency outcome-unknown cleanup rather than inferring certainty from `JoinError` or message text. +- Reqwest timeout/transport errors do not universally prove that no bytes reached the peer. Classification must depend on known pipeline/dispatch state; ambiguous mutating calls require manual reconciliation. + +### References + +- [Source: `_bmad-output/planning-artifacts/epics.md` — Epic 1, Story 1.8, dependency waves] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` — FR-2; NFR-P4/R1/S1/S2/S4/S7/S8/O1/O4/O5/C1/C4] +- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md` — Community and evidence decisions] +- [Source: `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` — AD-1/9/11/15/19/21/23 and conventions] +- [Source: `_bmad-output/planning-artifacts/implementation-readiness-report-2026-08-08.md` — FR-2 mapping and story-level NFR evidence requirement] +- [Source: `_bmad-output/test-artifacts/test-design-progress.md` — E1-R-007 and E1-17/E1-18/E1-19] +- [Source: `_bmad-output/implementation-artifacts/1-7-immutable-lifecycle-operation.md` — immutable Draft/Published/Agent handoff and owner performance decision] +- [Source: `_bmad-output/project-context.md` — execution, migration, redaction, testing and boundary rules] + +## Dev Agent Record + +### Agent Model Used + +GPT-5.6 Codex + +### Debug Log References + +- `cargo check --workspace --all-targets` — pass. +- `cargo test -p crank-core --test execution` — 5/5 pass; closed 30-code taxonomy and origin invariants. +- `cargo test -p crank-runtime --all-targets -- --test-threads=1` — pass; deadline, dispatch certainty, idempotency, confirmation and adapter call-count coverage. +- `cargo test -p crank-registry --test integration migrations -- --test-threads=1` — 22/22 pass, including honest v4→v5 upgrade. +- `cargo test -p admin-api --test integration operations_agents -- --test-threads=1` — 7/7 pass. +- `cargo test -p crank-community-mcp --all-targets -- --test-threads=1` and MCP execution-stage suite — pass. +- `python3 -m unittest -v tests.unit.test_check_execution_boundaries` and `scripts/check-rust-module-boundaries.sh` — pass. +- `just sqlx-check`, `just verify-ui`, `git diff --check` — pass. +- Playwright `operation-lifecycle.spec.js`, `operations.spec.js`, `wizard.spec.js` — 14/14 pass on Chromium real stack. +- Authenticated product smoke on local split-port stack — pass through create, Draft Test, publish, Agent bind/publish, MCP list/call, edit/archive and pinned MCP call. +- Explicit Community scan — pass, 129 changed/new files scanned. +- Final `just verify` — pass, including tooling, inventory/baseline, scope, config/migration/metrics contracts, boundaries, code health, dependency audit, fmt, clippy and full workspace tests. +- Post-review `just sqlx-check` — pass; all workspace queries compile against refreshed offline metadata. +- Post-review Playwright `wizard.spec.js` + `operation-lifecycle.spec.js` — 12/12 pass on Chromium. +- Post-review differential suites: Admin unit 7/7, MCP unit 12/12, Runtime all targets 63/63 and REST adapter integration 10/10 pass. + +### Completion Notes List + +- Added a framework-free closed execution taxonomy and canonical success/failure descriptor shared by Admin and MCP. +- Replaced optional production execution context with a mandatory scoped `RuntimeExecutionRequest`; fallback IDs and production convenience bypasses were removed. +- Centralized all runtime/protocol error normalization, including typed dispatch evidence and distinct read-only versus mutating deadline semantics. +- Unified Admin current-Draft Test, direct MCP snapshot calls and approved MCP calls on `execute_outcome`; public success contracts remain compatible and errors gained additive typed fields. +- Added RU/EN UI localization for stable execution codes while preserving Story 1.7 stale-response and correlation behavior. +- Added append-only MigrationAuthority v5 and persisted exact operation version, stage, error code, retryability and certainty without fabricating legacy values. +- Added exhaustive Admin/MCP projection parity tests, redaction/call-count/deadline coverage and a fail-closed execution-boundary scanner. +- Split MCP request DTOs and migration v5/owned-relation helpers into focused modules to keep legacy files inside code-health ceilings. +- Updated execution, Admin, MCP, history, observability, data-model and migration documentation. Capability Inventory/baseline remained semantically unchanged because the existing FR-2 flows already point to the refreshed executable evidence; both validators passed. +- No dependency/toolchain upgrade, deployment-topology change, Story 1.9 outbound-policy claim, commit, push or deployment was performed. +- Adversarial review closed all 17 High/Medium findings: the envelope, mapping, dispatch certainty, idempotency, persistence, taxonomy, locale, redaction, confirmation, stale-response and executable boundary/parity contracts are now fail-closed and covered by regression tests. + +### File List + +- `_bmad-output/implementation-artifacts/1-8-rest-execution-boundary-errors.md` +- `_bmad-output/implementation-artifacts/sprint-status.yaml` +- `Cargo.lock` +- `apps/admin-api/Cargo.toml` +- `apps/admin-api/src/error.rs` +- `apps/admin-api/src/service/operations.rs` +- `apps/admin-api/tests/unit/error.rs` +- `apps/admin-api/tests/unit/execution_parity.rs` +- `apps/ui/js/i18n.js` +- `apps/ui/js/wizard-live.js` +- `crates/crank-adapter-rest/src/lib.rs` +- `crates/crank-adapter-rest/tests/integration/client.rs` +- `crates/crank-community-mcp/src/app.rs` +- `crates/crank-community-mcp/src/app/invocation_history.rs` +- `crates/crank-community-mcp/src/app/request.rs` +- `crates/crank-community-mcp/src/approval_execution.rs` +- `crates/crank-community-mcp/src/tool_error.rs` +- `crates/crank-community-mcp/src/app/tests.rs` +- `crates/crank-community-mcp/tests/unit/tool_error.rs` +- `crates/crank-core/src/execution.rs` +- `crates/crank-core/src/ext/protocol.rs` +- `crates/crank-core/src/lib.rs` +- `crates/crank-core/src/observability.rs` +- `crates/crank-core/tests/execution.rs` +- `crates/crank-registry/src/migrations.rs` +- `crates/crank-registry/src/migrations/authority.rs` +- `crates/crank-registry/src/migrations/execution_outcome_v5.rs` +- `crates/crank-registry/src/migrations/execution_outcome_v5.sql` +- `crates/crank-registry/src/migrations/owned_relations.rs` +- `crates/crank-registry/src/migrations/schema_guard.rs` +- `crates/crank-registry/src/model.rs` +- `crates/crank-registry/src/postgres/mod.rs` +- `crates/crank-registry/src/postgres/observability.rs` +- `crates/crank-registry/tests/integration/agents_usage.rs` +- `crates/crank-registry/tests/integration/common.rs` +- `crates/crank-registry/tests/integration/migrations.rs` +- `crates/crank-runtime/src/auth.rs` +- `crates/crank-runtime/src/error.rs` +- `crates/crank-runtime/src/execution_failure.rs` +- `crates/crank-runtime/src/execution_request.rs` +- `crates/crank-runtime/src/executor.rs` +- `crates/crank-runtime/src/lib.rs` +- `crates/crank-runtime/src/request_context.rs` +- `crates/crank-runtime/tests/integration.rs` +- `crates/crank-runtime/tests/integration/confirmation.rs` +- `crates/crank-runtime/tests/integration/idempotency.rs` +- `crates/crank-runtime/tests/product_metrics.rs` +- `crates/crank-runtime/tests/stages.rs` +- `crates/crank-runtime/tests/support/mod.rs` +- `docs/README.md` +- `docs/admin-api.md` +- `docs/data-model.md` +- `docs/database-schema.md` +- `docs/en/migrations.md` +- `docs/execution-boundary.md` +- `docs/mcp-interface.md` +- `docs/migrations.md` +- `docs/observability.md` +- `docs/schemas/migration-sequence.json` +- `scripts/README.md` +- `scripts/check-execution-boundaries.py` +- `scripts/check-rust-module-boundaries.sh` +- `tests/unit/test_check_execution_boundaries.py` +- `.sqlx/query-*.json` (offline metadata refreshed for affected invocation-history queries in the shared Story 1.7/1.8 worktree) + +## Change Log + +- 2026-08-14: Story 1.8 created with a complete typed execution envelope, normalized outcome/error taxonomy, Admin/MCP parity matrix, MigrationAuthority v5 evidence and strict boundary/security scope. +- 2026-08-15: Story 1.8 implemented and moved to review after full workspace, UI, PostgreSQL, migration, boundary, explicit scope and authenticated REST→MCP qualification passed. +- 2026-08-15: Adversarial code review fixed all 17 High/Medium findings; post-review workspace, SQLx, migration, boundary and targeted Chromium gates passed, and Story 1.8 moved to done. diff --git a/_bmad-output/implementation-artifacts/1-9-outbound-rest.md b/_bmad-output/implementation-artifacts/1-9-outbound-rest.md new file mode 100644 index 0000000..1c3d8df --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-9-outbound-rest.md @@ -0,0 +1,406 @@ +--- +story_id: "1.9" +story_key: "1-9-outbound-rest" +requirement: "FR-2" +status: "done" +baseline_commit: "767428436d3a54e60809a727044dfcec48e1f1dd + uncommitted Story 1.7/1.8 worktree" +created: "2026-08-15T14:50:28+03:00" +--- + +# Story 1.9: Защитить каждое outbound REST-соединение + +Status: done + +## Story + +As an оператор закрытого контура, +I want применять единую fail-closed outbound policy ко всем REST executions, +so that пользовательская конфигурация не превращает Crank в SSRF, proxy bypass или механизм истощения ресурсов. + +## Operational Brief + +Story 1.9 закрывает security boundary внешних REST-вызовов после Story 1.8. В 1.8 Admin Test и MCP `tools/call` были сведены к единому typed execution pipeline и одной error taxonomy. Теперь надо сделать этот pipeline безопасным на уровне сети: фактический адрес соединения, DNS rebinding, redirects, proxy, reserved headers, body/response/deadline/concurrency bounds и retry/idempotency должны вести себя одинаково для Admin и MCP. + +Значение для плана: это обязательная основа для безопасного REST Tool в Epic 1 и будущих REST-backed Resources, OpenAPI external refs, Tasks и Load Runs. Без 1.9 продукт может быть функционально рабочим, но всё ещё опасным как SSRF/proxy/resource-exhaustion механизм внутри закрытого контура. + +**Requirement:** FR-2 +**Primary architecture:** AD-9, AD-11, AD-21, AD-23; AD-1/4/17/19/20 conventions +**Applicable NFR:** NFR-S1, NFR-S2, NFR-S3, NFR-S4, NFR-S7, NFR-S8, NFR-O1, NFR-O4, NFR-O5, NFR-C1, NFR-C4 +**Primary risk/evidence:** E1-R-008, score 9; E1-20/E1-21 P0 suites. + +## Scope + +In scope: + +- Shared `OutboundPolicy`/`OutboundHttpPolicy` for every current REST execution path: Admin Draft Test and MCP Tool call. +- Actual-connect address validation after DNS resolution for IPv4/IPv6, with deny-before-allow semantics. +- DNS rebinding and retry address revalidation; a previously allowed hostname does not authorize a later forbidden address. +- Redirect behavior: disabled by default; optional explicit redirect policy only with hop revalidation, hop limit and credential stripping. +- System proxy disabled by default; any future explicit proxy configuration must be typed, validated and subject to the same outbound policy. +- Reserved system headers: correlation, `Host`, content length, transfer encoding and Auth Profile credentials cannot be overridden by static/mapped user headers. +- Request, response, deadline, concurrency and retry bounds before unbounded wait/body accumulation. +- Retry policy for reads and writes, including idempotency/side-effect honesty from AD-9. +- Safe typed outcomes and redaction for all outbound failures. +- Capability Inventory evidence for FR-2, NFR-S3 and NFR-S4 after tests pass. + +Out of scope: + +- New Resources/Prompts/Tasks/Load Runs implementation. +- OpenAPI external-reference fetching, except documenting that it must later reuse or narrow this policy. +- Grafana/Prometheus dashboards, GlitchTip trace delivery or browser trace UI. +- New Auth Profile/key lifecycle semantics from Story 1.10. +- Full background retry/reconciliation UI from Epic 4. +- Broad dependency/toolchain upgrades or replacement of Reqwest. + +## Acceptance Criteria + +1. **Actual-connect policy on every REST execution** + - Given Admin Test or MCP Tool execution + - When REST adapter opens a connection + - Then shared `OutboundPolicy` validates the actual resolved address immediately before each connection attempt + - And deny rules have priority over allow rules + - And Admin and MCP use the same policy instance derived from typed config. + +2. **Forbidden address classes are blocked before HTTP bytes leave** + - Given a hostname resolving to loopback, private, link-local, multicast, unspecified, documentation, carrier-grade NAT, IPv4-mapped IPv6 or forbidden service address + - When adapter attempts IPv4 or IPv6 connection + - Then execution is blocked before sending request line, headers or body + - And the safe error does not reveal internal network topology, DNS answers, full URL, credentials or policy internals. + +3. **DNS rebinding and retry address revalidation** + - Given a hostname whose DNS result changes between validation and connection or between retries + - When connection attempt or retry runs + - Then policy is re-applied to the address actually used for that attempt + - And a previously allowed resolution cannot authorize a later forbidden IP. + +4. **Redirects are fail-closed** + - Given upstream redirect + - When redirects are not explicitly enabled by Operation/outbound policy + - Then adapter does not follow the redirect and returns a typed non-retryable policy outcome. + +5. **Allowed redirects are bounded and revalidated** + - Given an explicit redirect contract + - When upstream returns a new `Location` + - Then scheme, host, port and actual resolved address pass policy on every hop + - And hop count is bounded + - And `Authorization`, `Cookie`, API-key headers and Auth Profile material are stripped on cross-origin redirect. + +6. **System proxy is off by default** + - Given process environment contains `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` or `NO_PROXY` + - When production HTTP client is created + - Then system proxy is not used by default + - And proxy can be enabled only through typed operator configuration, with the proxy target itself passing outbound policy. + +7. **Reserved headers cannot be overridden** + - Given static or mapped user headers + - When outbound request is formed + - Then system correlation headers, `Host`, `Content-Length`, `Transfer-Encoding`, selected Auth Profile credential headers and any safety/idempotency headers have priority + - And invalid/forbidden user header names are rejected before dispatch with a stable typed outcome. + +8. **Resource bounds apply before unbounded allocation or wait** + - Given configured request, response, concurrency and deadline limits + - When REST call runs + - Then request body size, response body size, streaming accumulation, connection/read timeout, total execution deadline and runtime concurrency are enforced + - And oversized request, oversized response, timeout, deadline, exhausted concurrency and invalid config map to distinct typed outcomes. + +9. **Retry obeys side-effect honesty** + - Given retry-enabled Operation + - When retryable failure occurs + - Then retries respect total deadline, max attempts, bounded backoff and per-attempt outbound policy + - And write without verified upstream idempotency contract is never retried automatically after dispatch uncertainty + - And write with verified idempotency forwards the configured idempotency key within full workspace/Agent/Operation/version/input scope. + +10. **Invalid outbound configuration fails closed** + - Given invalid or unsafe production outbound configuration + - When process starts or readiness validates dependencies + - Then affected safety path fails closed with stable config diagnostic + - And policy cannot silently fall back to permissive defaults. + +11. **Security matrix and redaction** + - Given outbound security suite + - When negative tests run + - Then IPv4/IPv6 variants, encoded/embedded hosts, DNS rebinding, redirects, proxy environment, reserved headers, oversized bodies, timeouts and concurrency saturation are covered + - And logs, traces, metrics, test failures, UI error, Admin response and MCP content contain no credentials, full target URLs, private IPs, payload canaries or host paths. + +12. **Cross-ingress evidence** + - Given story completion + - When Admin Test and MCP execute the same outbound scenarios + - Then one contract suite proves identical normalized `error_code`, stage, retryability, certainty, dispatch evidence and adapter call/byte-send counts + - And `just verify`, targeted malicious-network suites and Capability Inventory checks pass without dependency/toolchain/public-success-wire changes. + +## Frozen Outbound Contract + +### Policy model + +- Deny-before-allow is mandatory. A deny match rejects even if an allow pattern also matches. +- Explicit allow can permit private/internal targets for closed-contour use, but every allowed host/IP is still bounded by configured limits, reserved header rules and redaction. +- URL userinfo is always forbidden. `http://user:pass@host`, percent-encoded credential tricks and credentials in redirects are blocked or stripped before dispatch. +- Host normalization must handle case, trailing dot, bracketed IPv6, IPv4-mapped IPv6 and obvious encoded/ambiguous forms deterministically. +- Validation at save/publish is advisory. Actual-connect validation in the adapter is authoritative and must run for every attempt. + +### Reserved header set + +At minimum the following user-supplied static/mapped headers cannot override system values: + +- Correlation: `traceparent`, `tracestate`, `baggage`, `x-request-id`, `x-trace-id`, `x-correlation-id`. +- HTTP framing/routing: `host`, `content-length`, `transfer-encoding`, `connection`, `upgrade`. +- Credentials selected by Auth Profile: `authorization`, `cookie`, configured API-key header names. +- Safety/idempotency headers selected by runtime policy. + +The implementation may reject forbidden user header names or ignore them only when the behavior is deterministic, tested and documented. Credential/safety override must never silently win over system values. + +### Retry rules + +- `GET`/`HEAD` may retry known safe transient failures only within the total deadline. +- Mutating methods `POST|PUT|PATCH|DELETE` may retry automatically only when an idempotency policy is verified and the idempotency key was set before dispatch. +- Any failure after `DispatchEvidence::MayHaveDispatched` on a mutating operation without verified idempotency becomes `manual_reconcile + outcome_unknown`, inherited from Story 1.8. +- Retry attempts must create separate attempt observations/spans but keep the same Request ID and parent Trace ID. + +### Typed outcomes + +Use the closed Story 1.8 taxonomy. Story 1.9 may add typed outbound policy context internally, but public error-code additions require updating: + +- `crank-core` enum and RU/EN catalog +- Admin/MCP projection tests +- v5 or later persistence checks if persisted +- docs and capability evidence + +Prefer existing `outbound_target_rejected`, `adapter_configuration_invalid`, `upstream_timeout`, `upstream_transport_error`, `upstream_response_too_large`, `execution_overloaded`, `idempotency_outcome_unknown` where semantically correct. + +## Current Brownfield State + +- `crates/crank-adapter-rest` already owns the HTTP client and exports `OutboundHttpPolicy` and `RestAdapter`. +- The current adapter already sets `redirect(Policy::none())`, `no_proxy()`, a custom `PolicyDnsResolver`, response body bound and reserved correlation-header suppression. +- Current host/IP checks are useful but incomplete for the full AC matrix. They rely on resolver filtering and `reqwest::Error::is_connect()` to infer `NotDispatched`; Story 1.9 must prove byte-send/dispatch evidence at the adapter boundary. +- `OutboundHttpPolicy` currently stores `allowed_hosts`, `denied_hosts` and `max_response_bytes`; it does not model redirects, proxy enablement, request body max, retry attempts/backoff or credential-strip policy. +- `RestAdapterError` currently includes raw fields such as invalid base URL or rejected target. Boundary projection from Story 1.8 is safe, but test failure/log/error Display can still leak raw values unless hardened. +- Runtime currently sets a coarse `dispatch_started` flag before invoking the adapter. That is not enough to prove whether HTTP data left the process. +- Config already owns `CRANK_OUTBOUND_ALLOWED_HOSTS`, `CRANK_OUTBOUND_DENIED_HOSTS`, `CRANK_OUTBOUND_MAX_RESPONSE_BYTES`. Add new outbound config only through `crank-config` field registry/schema/docs/examples/tests. +- Admin save/publish validates `base_url` using the outbound policy. This is only preflight; it must not be treated as a substitute for actual-connect checks. +- Admin and MCP runtime builders already inject the same `OutboundHttpPolicy` from typed process config. Preserve this wiring. +- Story 1.8 has unified Admin/MCP execution and closed error taxonomy. Do not reintroduce separate Admin/MCP outbound paths. + +## Developer Guardrails + +- Do not replace Reqwest or add a new HTTP client dependency unless there is a proven blocker. Existing stack is Reqwest `0.12`, Tokio `1`, Rust `1.96.1`. +- Do not read environment variables in `crank-adapter-rest`, `crank-runtime`, Admin service or MCP. Runtime config belongs to `crank-config`; apps pass validated values. +- Do not move SSRF policy into Admin-only validation. The adapter is the enforcement owner because DNS/retry/redirect decisions happen at connection time. +- Do not weaken Community closed-contour behavior by permitting arbitrary proxy use. Proxy support, if added, is explicit typed operator configuration only. +- Do not put host, URL, DNS answer, object ID, request ID, trace ID, error text or payload in metric labels. +- Do not expose raw URL/body/header values in `Debug`, `Display`, test snapshots, docs examples, logs or UI messages. +- Do not mutate Story 1.4 migration v1-v5 bytes unless the implementation truly needs a new durable schema; expected path for 1.9 should be code/config/tests/docs only. +- Do not claim OpenAPI external refs, Resources, Tasks, Load Runs or production Prometheus/Grafana are complete because they inherit the policy later. + +## File Map + +Expected UPDATE: + +- `crates/crank-adapter-rest/src/client.rs` — policy model, resolver/connect enforcement, redirect/proxy/header/body/response/deadline handling. +- `crates/crank-adapter-rest/src/error.rs` and `src/lib.rs` — typed safe errors and dispatch evidence projection. +- `crates/crank-adapter-rest/tests/integration/client.rs` or split tests — malicious-network and header/redirect/proxy/bounds cases. +- `crates/crank-runtime/src/{executor.rs,execution_failure.rs,idempotency.rs}` — retry/idempotency/dispatch evidence semantics only where adapter evidence must flow upward. +- `crates/crank-runtime/tests/{stages.rs,product_metrics.rs,integration/idempotency.rs}` and possible new outbound integration tests. +- `crates/crank-core/src/{operation.rs,execution.rs,ext/protocol.rs}` only if retry/policy/header contract requires new typed fields. +- `apps/admin-api/src/{main.rs,service.rs,dto.rs,error.rs}` only for config projection, validation and boundary projection. +- `crates/crank-community-mcp/src/{app.rs,tool_error.rs}` only for parity evidence if shared outcome projection needs adjustment. +- `crates/crank-config/src/{schema.rs,process.rs,render.rs}` plus config tests/docs if new outbound fields are added. +- `docs/{runtime-config.md,execution-boundary.md,observability.md,tool-design.md,admin-api.md,mcp-interface.md}` as applicable. +- `docs/capability-inventory.json` and baseline manifest/results only after evidence passes. +- Existing boundary/health scripts if direct outbound bypass scanning is extended. + +Likely NEW: + +- `crates/crank-adapter-rest/tests/integration/outbound_security.rs` for hermetic DNS/HTTP malicious-network matrix. +- Focused test support module for controlled DNS answers, redirect chains and byte-send counters if existing test server is insufficient. +- `docs/outbound-rest-security.md` if the policy becomes too detailed for existing docs. + +Must preserve: + +- Story 1.7 immutable Operation semantics and Story 1.8 unified execution contract. +- Public success wire fields for Admin Test and MCP `tools/call`. +- MCP protocol negotiation and supported revision behavior. +- Existing typed metrics registry; extend only with bounded enum values if unavoidable. +- Current dependency/toolchain versions. + +## Test Plan + +Required P0 suites: + +- E1-20: IPv4/IPv6 forbidden classes, encoded/embedded hosts, DNS rebinding and actual retry addresses blocked before bytes leave. +- E1-21: redirect revalidation/credential stripping, proxy env, reserved headers, byte/deadline/concurrency limits and write retry rules fail closed. + +Targeted commands: + +```bash +cargo test -p crank-adapter-rest --all-targets -- --test-threads=1 +cargo test -p crank-runtime --all-targets -- --test-threads=1 +cargo test -p admin-api --test integration execution_parity -- --test-threads=1 +cargo test -p admin-api --test integration operations_agents -- --test-threads=1 +cargo test -p crank-community-mcp --all-targets -- --test-threads=1 +cargo test -p mcp-server --test integration -- --test-threads=1 +cargo test -p crank-config --all-targets -- --test-threads=1 +just config-contract-check +just metrics-contract-check +just rust-boundaries +just capability-inventory-check +just authenticated-product-smoke http://localhost:3000 +just verify +git diff --check +python3 scripts/check-community-scope.py --root . --files +``` + +Required assertions: + +- Every forbidden-address case records zero request bytes at the malicious server. +- Every redirect case proves the hop decision and credential forwarding behavior. +- Proxy environment canary proves no proxy connection is attempted by default. +- Deny match wins over allow match. +- Admin and MCP produce the same normalized outcome for each outbound failure. +- Mutating retry without verified idempotency never performs a second dispatch after uncertainty. +- Request/Trace IDs propagate but never appear in labels. +- Secret/header/body/URL/IP canaries are absent from response/history/log/trace/metric/test evidence. +- Config drift checks fail if a new outbound field is not in schema/docs/examples. + +## Tasks / Subtasks + +- [x] Task 1 — Freeze RED outbound-security oracle and byte-send evidence (AC: 1–3, 6, 11–12) + - [x] Add malicious-network adapter tests for forbidden IPv4/IPv6 classes, deny-over-allow, proxy env bypass and no-byte-send assertions. + - [x] Add DNS rebinding/retry-address tests proving validation happens on the actual address used for each attempt. + - [x] Add safe-error/redaction tests for URL, credential, private-IP and payload canaries. + +- [x] Task 2 — Harden `OutboundHttpPolicy` and adapter enforcement (AC: 1–8, 10–11) + - [x] Normalize and validate host/IP/URL patterns deterministically, including IPv4-mapped IPv6 and ambiguous/encoded host forms. + - [x] Enforce reserved header policy for correlation, framing, credentials and idempotency/safety headers before dispatch. + - [x] Keep system proxy disabled by default and prove client construction ignores proxy environment. + - [x] Preserve disabled redirects by default; support only bounded explicit redirect behavior if implemented in this story. + - [x] Bound request and response body handling before unbounded allocation. + +- [x] Task 3 — Wire precise dispatch evidence and retry/idempotency semantics (AC: 3, 8–9, 12) + - [x] Replace coarse runtime `dispatch_started` assumptions with adapter-level evidence sufficient for retry/idempotency decisions. + - [x] Implement bounded retry only where safe: read-safe attempts or writes with verified idempotency. + - [x] Ensure mutating uncertain dispatch without verified idempotency becomes `manual_reconcile + outcome_unknown`. + +- [x] Task 4 — Cross-ingress parity, config and docs/evidence (AC: 10–12) + - [x] Prove Admin and MCP outbound failures project the same normalized code/stage/retryability/certainty. + - [x] Update typed config/docs only if new outbound fields are added; otherwise document the hardened existing fields. + - [x] Update Capability Inventory/baseline evidence after tests pass. + - [x] Run targeted suites, explicit Community scan and final `just verify`. + +### Review Findings + +- [x] [Review][Patch] Deny-over-allow is not applied to resolved IP addresses [crates/crank-adapter-rest/src/client.rs:360] +- [x] [Review][Patch] Runtime still treats adapter invocation start as dispatch evidence [crates/crank-runtime/src/executor.rs:541] +- [x] [Review][Patch] Prepared/mapped headers can override credential and safety headers without provenance [crates/crank-adapter-rest/src/client.rs:513] +- [x] [Review][Patch] Verified mutating retry can trust a user-supplied idempotency header [crates/crank-runtime/src/idempotency.rs:336] +- [x] [Review][Patch] Request body limit serializes the full JSON body before enforcing the limit [crates/crank-adapter-rest/src/client.rs:682] +- [x] [Review][Patch] Oversized outbound request does not project a distinct typed outcome [crates/crank-adapter-rest/src/lib.rs:66] +- [x] [Review][Patch] Disabled redirects are normalized as generic upstream status failures, not policy outcomes [crates/crank-adapter-rest/src/client.rs:166] +- [x] [Review][Patch] Transport/debug diagnostics can still expose raw URL or host details [crates/crank-adapter-rest/src/error.rs:24] +- [x] [Review][Patch] Completed evidence matrix overstates DNS rebinding, IPv6, redirect and cross-ingress coverage [crates/crank-adapter-rest/tests/integration/outbound_security.rs:23] + +## Previous Story Intelligence + +- Story 1.8 closed the execution envelope and error taxonomy. Use `RuntimeExecutionRequest → RuntimeExecutor → ProtocolAdapter → RestAdapter`; do not add new `execute_with_*` bypasses. +- Story 1.8 exposed a key lesson: coarse adapter invocation is not dispatch evidence. 1.9 must make dispatch evidence precise at the HTTP send/connect boundary. +- Story 1.7 protects immutable Operation versions. Outbound policy must run against the exact saved Draft or Published snapshot selected by 1.7/1.8. +- Story 1.6 requires all metrics to go through `crank-metrics`; no high-cardinality outbound labels. +- Story 1.5 requires system correlation headers to override user mappings; 1.9 extends that reserved-header principle to HTTP framing and credentials. +- Story 1.4 migration authority remains untouched unless a durable schema change is strictly required. +- Story 1.3 requires all new operator config to be typed in `crank-config`; no direct env reads in reusable crates. + +## Git Intelligence + +- Current `HEAD` is `7674284`, but the working tree contains uncommitted completed Story 1.7 and 1.8 changes. Treat those as the effective implementation baseline; do not revert them. +- Existing worktree also contains `.agents/` and generated SQLx metadata changes. Preserve them unless explicitly instructed otherwise. +- Recent implementation pattern is closed typed contracts plus executable boundary scanners and parity suites. Reuse it here. + +## Latest Technical Notes + +- No web research or dependency upgrade is required for story creation. The repository already pins Reqwest `0.12` and Tokio `1`; the story should harden the existing adapter rather than chase external version changes. +- Reqwest redirects are currently disabled and proxy use is currently disabled with `.no_proxy()`. Tests must prove these remain true in production construction. +- Reqwest transport errors alone are not enough to prove side-effect certainty. Use explicit adapter/test evidence around connection and byte-send boundaries. + +## References + +- `_bmad-output/planning-artifacts/epics.md` — Epic 1 and Story 1.9. +- `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` — FR-2, NFR-S3, NFR-S4, FR-50 security evidence. +- `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md` — side-effect/idempotency and Community decisions. +- `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` — AD-9, AD-11, AD-21, AD-23, conventions. +- `_bmad-output/test-artifacts/test-design-progress.md` — E1-R-008, E1-20, E1-21. +- `_bmad-output/implementation-artifacts/1-8-rest-execution-boundary-errors.md` — unified execution handoff and review lessons. +- `_bmad-output/project-context.md` — outbound safety, testing, config, boundary and redaction rules. + +## Dev Agent Record + +### Agent Model Used + +GPT-5 Codex + +### Debug Log References + +- 2026-08-15: Story 1.9 moved to in-progress; current implementation baseline is `7674284` plus uncommitted Story 1.7/1.8 worktree. +- 2026-08-15: Added RED adapter outbound-security tests, runtime retry/idempotency tests and typed config coverage for request body limit. +- 2026-08-15: Final verification passed: `just verify` exit code 0. +- 2026-08-15: Code review patches applied; final `just verify` passed after fixing resolved-IP deny, header provenance, idempotency trust, streaming request limit, redirect policy outcome, safe transport diagnostics and adapter-owned dispatch marker. + +### Completion Notes List + +- Story context created by `bmad-create-story`. +- Added missing `Tasks / Subtasks` section before implementation because the created story lacked executable task checkboxes required by `bmad-dev-story`. +- Hardened outbound REST policy: forbidden static credential/framing headers reject before dispatch; system correlation headers remain system-owned; resolved Auth Profile headers remain allowed after runtime resolution. +- Added fail-closed request body limit and typed `CRANK_OUTBOUND_MAX_REQUEST_BYTES` config, propagated consistently into Admin and MCP runtime construction. +- Added bounded retry semantics: read-safe transient failures can retry; mutating retries require verified idempotency and reuse the same scoped idempotency key. +- Added typed `upstream_request_too_large` outcome and updated the v5 execution-outcome CHECK/schema guard/migration sequence checksum so persisted history remains closed. +- Updated FR-2 Capability Inventory evidence and baseline checksum after tests passed. +- No dependency or toolchain changes were introduced by Story 1.9. + +### File List + +- `_bmad-output/implementation-artifacts/1-9-outbound-rest.md` +- `_bmad-output/implementation-artifacts/sprint-status.yaml` +- `.env.example` +- `docker-compose.yml` +- `deploy/community/.env.example` +- `deploy/community/.env.images.example` +- `deploy/community/docker-compose.yml` +- `deploy/community/docker-compose.images.yml` +- `apps/admin-api/src/main.rs` +- `apps/mcp-server/src/main.rs` +- `crates/crank-adapter-rest/src/client.rs` +- `crates/crank-adapter-rest/src/error.rs` +- `crates/crank-adapter-rest/src/lib.rs` +- `crates/crank-adapter-rest/src/model.rs` +- `crates/crank-adapter-rest/tests/integration.rs` +- `crates/crank-adapter-rest/tests/integration/client.rs` +- `crates/crank-adapter-rest/tests/integration/outbound_security.rs` +- `crates/crank-core/src/execution.rs` +- `crates/crank-core/src/ext/protocol.rs` +- `crates/crank-registry/src/migrations/execution_outcome_v5.rs` +- `crates/crank-registry/src/migrations/execution_outcome_v5.sql` +- `crates/crank-registry/src/migrations/schema_guard.rs` +- `crates/crank-runtime/src/auth.rs` +- `crates/crank-runtime/src/execution_failure.rs` +- `crates/crank-runtime/src/executor.rs` +- `crates/crank-runtime/src/idempotency.rs` +- `crates/crank-runtime/src/model.rs` +- `crates/crank-runtime/src/request_context.rs` +- `crates/crank-runtime/src/request_preparation.rs` +- `crates/crank-runtime/tests/product_metrics.rs` +- `crates/crank-runtime/tests/stages.rs` +- `docs/schemas/migration-sequence.json` +- `crates/crank-config/src/debug.rs` +- `crates/crank-config/src/process.rs` +- `crates/crank-config/src/schema.rs` +- `crates/crank-config/tests/contract.rs` +- `crates/crank-runtime/src/executor.rs` +- `crates/crank-runtime/tests/stages.rs` +- `docs/capability-baseline/manifest.json` +- `docs/capability-inventory.json` +- `docs/runtime-config.md` +- `docs/schemas/runtime-config.schema.json` + +## Change Log + +- 2026-08-15: Story 1.9 created as ready-for-dev with outbound REST security scope, current brownfield gaps, test matrix and guardrails. +- 2026-08-15: Story 1.9 moved to in-progress and missing executable task checklist added before implementation. +- 2026-08-15: Story 1.9 implemented and moved to review after targeted tests, guardrails, Compose config checks and `just verify` passed. diff --git a/_bmad-output/implementation-artifacts/bmad-build-auto-result-20260913-092502.md b/_bmad-output/implementation-artifacts/bmad-build-auto-result-20260913-092502.md new file mode 100644 index 0000000..4b9cb99 --- /dev/null +++ b/_bmad-output/implementation-artifacts/bmad-build-auto-result-20260913-092502.md @@ -0,0 +1,10 @@ +--- +status: blocked +--- + +# BMad Build Auto Result + +Status: blocked +Blocking condition: unclear intent + +Вызов содержит только имя skill, без story, spec или задачи. Остановка на Intent check; разработка, повторное ревью, интеграция и push не запускались. Статус существующей Story 2.4 не изменён. diff --git a/_bmad-output/implementation-artifacts/epic-2-context.md b/_bmad-output/implementation-artifacts/epic-2-context.md new file mode 100644 index 0000000..000fc0a --- /dev/null +++ b/_bmad-output/implementation-artifacts/epic-2-context.md @@ -0,0 +1,81 @@ +# Epic 2 Context: Надёжное создание Tools из реальных OpenAPI + + + +## Goal + +Дать self-hosted администратору безопасный и воспроизводимый путь от OpenAPI/Swagger к пригодным к публикации Draft Operations: сохранить проверенный immutable snapshot, получить детерминированный preview со всеми findings, явно разрешить ограничения и конфликты, затем атомарно применить выбранный ImportPlan без silent loss, утечки секретов и частичных мутаций. Отдельных UX/design и product brief artifacts в planning-каталоге нет; UX-ограничения ниже собраны из PRD и Epic 2 требований. + +## Stories + +- Story 2.1: Реализовать безопасное immutable artifact storage +- Story 2.2: Добавить workspace-scoped metadata artifacts +- Story 2.3: Реализовать bounded filesystem reconciliation artifacts +- Story 2.4: Реализовать artifact claim/recovery coordinator +- Story 2.5: Ввести bounded multipart upload и verified OpenAPI preview +- Story 2.6: Завершить OpenAPI upload UX и release evidence +- Story 2.7: Преобразовать OpenAPI в детерминированный NormalizedIR +- Story 2.8: Безопасно разрешать references и schema composition +- Story 2.9: Сохранить полный поддерживаемый HTTP contract +- Story 2.10: Привязать security schemes через безопасный import API +- Story 2.11: Выбирать security mappings в OpenAPI UI +- Story 2.12: Предоставить полный preview и явный partial mode +- Story 2.13: Атомарно применять ImportPlan и обрабатывать re-import +- Story 2.14: Зафиксировать OpenAPI support matrix и regression corpus +- Story 2.15: Добавить OpenAPI-ветку в guided onboarding + +## Story numbering migration — 2026-09-13 + +Номера изменены без изменения scope и порядка зависимостей. Для новых запусков и ссылок использовать только текущую колонку. Старые specs перенаправляют на canonical files. Архивные журналы, commits и worktree paths не переименованы: остановленные loop runs со старой нумерацией не возобновлять против нового спринта. HTTP contract теперь Story 2.9; 2026-09-13 коммит `f8ee7c9bfeaa8a3f73a4850ff3f82b2bc2155fe8` интегрирован в `main` fast-forward, статус спринта согласован с завершённым spec: `done`. + +| Historical ID | Current ID | Outcome | +|---|---|---| +| 2.1a | 2.1 | Artifact store | +| 2.1b | 2.2 | Scoped metadata | +| 2.1e / 2.1b2a | 2.3 | Filesystem reconciliation | +| 2.1f / 2.1b2b | 2.4 | Claim recovery | +| 2.1c | 2.5 | Upload / preview API | +| 2.1d | 2.6 | Upload UX / evidence | +| 2.2 | 2.7 | NormalizedIR | +| 2.3 | 2.8 | References / composition | +| 2.4 | 2.9 | HTTP contract | +| 2.5 | 2.10 / 2.11 | Security schemes API / mapping UI | +| 2.6 | 2.12 | Preview / partial mode | +| 2.7 | 2.13 | Apply / re-import | +| 2.8 | 2.14 | Matrix / corpus | +| 2.9 | 2.15 | Guided onboarding | + +Первоначальная объединённая Story 2.1 (OpenAPI source, до декомпозиции) соответствует текущим 2.1–2.6, а не только новой Story 2.1. Общие пять AC для 2.3/2.4 наследуются обеими stories; их индивидуальные specs уточняют границы ответственности. + +## Requirements & Constraints + +- Upload принимает один UTF-8 `.yaml`, `.yml` или `.json` через bounded multipart contract (до 256 KiB). Пустые, oversized, malformed, неподдержанные и не содержащие методов документы отклоняются до создания Draft или другой бизнес-мутации. +- Поддерживаются OpenAPI 3.0/3.1 и Swagger 2.0; сохраняются REST methods (кроме `TRACE`/`CONNECT`), path/query/header/cookie parameters, required/default/enum/nullable/format, JSON/form/multipart bodies и все успешные `2xx` responses, включая `204` и несколько success schemas. XML получает явный unsupported finding. +- Local и разрешённые external references, `allOf`/`oneOf`/`anyOf`, recursion и discriminators либо сохраняются, либо блокируют создание объяснимым finding. External fetch выключен по умолчанию, ограничен operator-controlled allowlist/offline bundle и bounded depth/size/cycle policy. +- Preview не изменяет Operations, versions, Agent bindings или Auth Profiles. Полный Apply возможен только без blocker findings; partial mode требует явного выбора actionable candidates с замкнутыми dependencies. Конфликты ограничены `skip`, `rename` и `new_version`. +- Bearer/basic/api-key schemes связываются только с typed `AuthProfileRef`; OAuth/unknown schemes требуют ручной настройки. Raw credentials не попадают в artifacts, plans, Draft, logs, traces, metrics, diagnostics или exports. +- Apply атомарен, идемпотентен и безопасен при retry/concurrency; bounded redacted report перечисляет outcome каждого candidate (`created`, `versioned`, `renamed`, `skipped`, `rejected`). Silent semantic loss запрещён. +- Versioned normative support matrix и checksummed corpus содержат не менее 50 fixtures OpenAPI 3.0/3.1 и Swagger 2.0; не менее 95% Operations representative corpus становятся actionable Draft. Исправленный import defect закрепляется regression fixture; E2E использует реальный upload → preview → plan → apply путь. + +## Technical Decisions + +- Канонический pipeline: `ParsedDocument → typed NormalizedIR + complete Findings → immutable ImportPlan → transactional Apply`. Каждый source construct получает stable ID и mapping либо explicit finding; canonical output и plan digest не зависят от времени, map ordering или request IDs. +- `crank-artifacts` хранит bounded immutable bytes под opaque SHA-256 reference через private temp file, fsync, atomic no-clobber publish и directory fsync. PostgreSQL хранит workspace ownership, digest/ref, size, MIME, sensitivity и lifecycle/reference state; verified read повторно проверяет digest и размер. +- Artifact metadata всегда scoped по authoritative workspace. Reconciliation bounded/resumable, использует grace period и reference recheck и безопасно восстанавливается после unlink/quarantine/DB/fsync uncertainty; referenced data не удаляется без подтверждённого reference accounting. +- `crank-import` pure относительно PostgreSQL, artifacts и Operations. Parser получает только verified snapshot; разрешённые external snapshots immutable и входят в plan digest, поэтому изменение remote content требует нового preview и устраняет TOCTOU. +- Применяются hexagonal modular-monolith boundaries и единая migration authority. Apply повторно проверяет source/external digests, importer/support-matrix version, catalog revision, dependencies, auth refs и conflicts перед одной PostgreSQL transaction с conditional predicates/locks. +- Общий `OutboundPolicy` применяется к external references: deny-before-allow после DNS resolution, system proxy и implicit redirects выключены, network/input/output limits bounded. Boundary errors typed/localized и содержат безопасные Request ID/Trace ID. +- Matrix, corpus, preview/plan и apply reports — immutable evidence; release evidence индексируется signed JSON-Schema Evidence Manifest. Документация не обещает больше, чем доказано executable matrix/corpus. + +## UX & Interaction Patterns + +- Upload flow на RU/EN имеет idle, validating, uploading, parsing/loading, success, cancelled, empty/no-methods, error и recovery states; показывает только bounded metadata, findings, actionable recovery и Request ID/Trace ID. +- Preview показывает methods, paths, names, mappings, schemas, security, conflicts и source locations; для больших результатов использует search/filter/grouping и bounded pagination/virtualized rendering (до 2 000 candidates). Blockers видимы, partial/conflict consequences требуют явного подтверждения. +- Replacement, refresh, navigation, workspace/language change и concurrent requests защищены AbortController и monotonic identity/revision guards. Duplicate Apply click и stale response не создают повторную мутацию и не меняют authoritative selection. +- UI соблюдает keyboard navigation, visible focus, semantic labels, screen-reader status, contrast, non-color meaning и reduced-motion. Guided onboarding переиспользует canonical upload/preview flow, позволяет выбрать Draft для test/publish и не публикует автоматически. + +## Cross-Story Dependencies + +- Epic 2 начинается после Epic 1 foundation: typed configuration, migration authority, correlation/metrics contracts, Admin authorization/Auth Profiles, Operation lifecycle и shared runtime/outbound policy должны быть доступны. +- Artifact/upload цепочка упорядочена как `2.1 → 2.2 → 2.3 → 2.4 → 2.5 → 2.6`. Normalization и semantic branches питают preview/apply: `2.7 → 2.8 → 2.9 → 2.10 → 2.11 → 2.12 → 2.13`; Story 2.14 квалифицирует весь workflow и фиксирует evidence. 2.10 владеет security semantics/revalidation API, 2.11 использует этот API для mapping UI; обе сохраняют исходный immutable contract. +- Story 2.15 зависит от guided onboarding Epic 1 и готового bounded import workflow, не создаёт отдельный parser и не обходит Auth Profile/ImportPlan. Созданные Drafts используют обычные publication и Agent-binding flows последующих эпиков. diff --git a/_bmad-output/implementation-artifacts/spec-2-1-openapi-artifact-store.md b/_bmad-output/implementation-artifacts/spec-2-1-openapi-artifact-store.md new file mode 100644 index 0000000..23d4f86 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-1-openapi-artifact-store.md @@ -0,0 +1,182 @@ +--- +title: '2.1 — Реализовать безопасное immutable artifact storage' +type: 'feature' +created: '2026-08-25' +status: 'done' +baseline_revision: '182bde8ac0709709be849f5ab51d2ce02aa5410b' +review_loop_iteration: 1 +followup_review_recommended: false +context: + - '_bmad-output/implementation-artifacts/epic-2-context.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' +warnings: [oversized] +deferred: [] +--- + + + +## Intent + +**Problem:** Загруженные bytes пока не имеют отдельной immutable filesystem boundary: существующий `LocalArtifactStorage` формирует mutable `file://` paths и не защищает source от подмены, corruption и path races. + +**Approach:** Добавить leaf-crate `crank-artifacts`, который хранит bounded bytes по opaque SHA-256 reference, публикует их атомарно и durable, проверяет digest при каждом чтении и предоставляет только безопасные низкоуровневые housekeeping/legacy-read primitives. + +## Boundaries & Constraints + +**Always:** считать authority открытый directory FD, а не `PathBuf`; выполнять blob I/O относительно закреплённых root/shard FDs без следования symlink; использовать private same-directory temp, file fsync, atomic no-clobber publish и directory fsync; проверять размер до/во время записи и digest до возврата; возвращать bounded typed errors без raw bytes, caller path или IO details; оставлять crate независимым от workspace crates. + +**Block If:** Linux reference deployment не предоставляет безопасный no-clobber/dirfd contract (`openat2`/`renameat2`) и его нельзя реализовать без ослабляющего fallback; требования вынуждают принять policy о registry ownership/orphan status внутри filesystem crate. + +**Never:** не менять `sprint-status.yaml`; не добавлять PostgreSQL metadata, workspace ownership, reconciliation policy, Admin API, multipart/parser flow, UI или deployment configuration; не принимать filename/path/new `file://` как physical reference; не расширять path-based `apps/admin-api/src/storage.rs`; не cherry-pick исторический WIP без устранения его TOCTOU и recovery gaps. + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|--------------|---------------------------|----------------| +| Store/read | Bounded bytes | `sha256:<64 lowercase hex>`, durable single blob, byte-identical verified read | No error expected | +| Duplicate race | Повторные/конкурентные одинаковые bytes | Один immutable blob; каждый caller получает тот же ref | Existing blob отдельно verified; mismatch — integrity error | +| Invalid or damaged | Empty/oversized input, malformed ref, missing/truncated/corrupt/non-regular blob | Никаких partial final blobs и непроверенных bytes | Stable typed size/reference/integrity/storage error без path/source | +| Hostile filesystem | Traversal, absolute path, symlink или configured-root replacement | I/O остаётся внутри pinned root и не затрагивает replacement target | Fail closed typed unsafe-root/reference error | +| Interrupted write | Disk-full/fault до или после publish; fresh/stale temp | Final blob полностью опубликован либо отсутствует; retry безопасен; cleanup bounded | Temp распознаётся по внутреннему формату; referenced policy не принимается | +| Legacy read | Explicit legacy root, absolute `file://`, expected digest | Только fd-relative read внутри pinned root; original ref/file не меняется | Escape/symlink/wrong digest/disabled reader отклоняются | + + + +## Code Map + +- `Cargo.toml:1-55` — зарегистрировать workspace member и общие `rustix`/test dependencies; сохранить Rust 2024 / 1.96 conventions. +- `crates/crank-artifacts/Cargo.toml` — новый leaf manifest; production dependencies только для Linux filesystem boundary, hashing, URL parsing и typed errors. +- `crates/crank-artifacts/src/lib.rs` — минимальный public API и точечные re-exports по conventions `crank-schema`/`crank-mapping`. +- `crates/crank-artifacts/src/model.rs` — strict `ArtifactRef`, limits, candidate/temp value types; ref принимает только canonical lowercase SHA-256 form. +- `crates/crank-artifacts/src/error.rs` — path-free typed public errors без transparent IO sources. +- `crates/crank-artifacts/src/store.rs` — bounded write, verified read, pinned-FD layout `sha256/<2>/`, dedupe и fault/recovery seams. +- `crates/crank-artifacts/src/housekeeping.rs` — streaming scan с отдельными scan/result budgets; stale-temp capability привязана к root и inode, а cooperative root lock исключает live/replacement/cross-store deletion races. +- `crates/crank-artifacts/src/legacy.rs` — opt-in digest-verified `file://` compatibility read внутри pinned legacy root; никакого rewrite/delete. +- `crates/crank-artifacts/tests/` — filesystem/security/recovery matrix; tests используют isolated temp roots, реальный fork/abrupt-exit на syscall checkpoints и проверяют отсутствие outside-root effects. +- `scripts/check-rust-boundaries.py:31-140` и `tests/unit/test_check_rust_boundaries.py` — закрепить `crank-artifacts` как leaf category, запрещённую от workspace dependencies. +- `apps/admin-api/src/storage.rs:9-84` — read-only evidence: существующий path-based sample store не переиспользовать и не менять в 2.1. +- `_bmad-output/implementation-artifacts/spec-2-1-openapi-source.md` — read-only superseded audit artifact; не использовать как active scope. + +## Tasks & Acceptance + +**Execution:** +- `Cargo.toml`, `Cargo.lock`, `crates/crank-artifacts/Cargo.toml` — зарегистрировать изолированный crate и минимальные pinned capabilities — сделать boundary сборочной и воспроизводимой. +- `crates/crank-artifacts/src/{lib.rs,model.rs,error.rs,store.rs}` — реализовать strict refs, fd-anchored durable CAS, trusted-owner/inode invariants, корректную errno classification и syscall-coupled fault checkpoints — закрыть integrity, no-clobber и root-race contract. +- `crates/crank-artifacts/src/{housekeeping.rs,legacy.rs}` — реализовать streaming bounded primitives с cooperative lock/capability revalidation и opt-in legacy reader — поддержать recovery/migration без ownership policy, live-temp deletion или mutable paths. +- `crates/crank-artifacts/tests/**` — покрыть всю I/O matrix, concurrency и fault windows — доказать outer filesystem behavior, а не внутренние proxy. +- `scripts/check-rust-boundaries.py`, `tests/unit/test_check_rust_boundaries.py` — запретить production workspace dependencies у `crank-artifacts` — сохранить hexagonal leaf invariant. + +**Acceptance Criteria:** +- Given bounded source bytes, when несколько writers сохраняют их одновременно, then все получают один canonical SHA-256 ref, final blob публикуется no-clobber после file fsync и shard directory fsync, а повторный read возвращает только digest-verified bytes. +- Given missing, truncated, corrupt, symlink или non-regular blob, when caller читает canonical ref, then bytes не возвращаются и typed diagnostics не раскрывает source, filesystem path или low-level IO detail. +- Given traversal/path/file-URL input либо symlink/root-replacement race, when выполняется write/read/list/delete, then операция остаётся fd-anchored внутри исходного configured root и outside/replacement target не затрагивается. +- Given configured root или existing final blob, when store открывает authority либо принимает deduplicated blob, then root принадлежит effective service identity и не writable для group/world, а final — owned regular single-link inode без write bits и с verified digest; иначе операция fail closed. +- Given disk-full seam или abrupt child-process exit на write/file-fsync/publish/directory-fsync checkpoints, when store открывается в новом process и retry выполняется, then final blob целиком verified либо отсутствует, syscall checkpoints нельзя сохранить при удалении соответствующего sync/publish operation. +- Given live, fresh, stale, replaced или cross-store temp и каталог с произвольным числом entries, when housekeeping получает scan/result budgets и удаляет candidate, then scan аллоцирует/просматривает не больше budget, live/replaced/foreign candidate не удаляется, successful unlink fsync-ится, а registry ownership policy не принимается. +- Given explicit legacy root и expected digest, when читается legacy absolute `file://`, then только contained regular file возвращается после digest verification, а escape/symlink/mismatch отклоняются без rewrite/delete. +- Given public parsing/streaming/limits API, when canonical ref round-trips, reader отдаёт short chunks/`Interrupted`, либо payload/legacy file равен exact maximum, then полный digest/bytes сохраняются; overflow limits отклоняются и operational IO не маскируется как integrity. +- Given изменённый workspace, when запускаются crate tests и boundary/format/lint gates, then exhaustive artifact suite проходит и executable rule отклоняет production workspace dependency из `crank-artifacts`, не запрещая dev-only test support. + +## Spec Change Log + +### 2026-08-25 — Review repair loop 1 +- Trigger: review обнаружил, что общие слова `bounded`, `immutable`, `safe stale temp` и `fault seams` допускают unbounded `readdir`, trusted-root/inode gaps, live/replacement/cross-root temp deletion и in-process-only crash proxy. +- Amended: Code Map, Execution, AC и Design Notes теперь требуют streaming scan/result budgets; euid/root и final inode invariants; cooperative root lock плюс root/inode/age revalidation; process-unique temp nonce; errno-aware operations; syscall-coupled fork/abrupt-exit/disk-full evidence и точные public API boundary tests. +- Avoids: green tests при удалённых fsync, partial-success `readdir`, cleanup активного/reused temp, принятие writable/hard-linked final, untrusted root и ошибки на exact max/short reads. +- KEEP: pinned directory FDs как authority; strict lowercase SHA-256 refs; same-shard private temp; `renameat2(RENAME_NOREPLACE)` без fallback; file/directory fsync; verified reads; path/source-free typed errors; legacy no-rewrite/no-delete; leaf-crate и separation от registry policy. + +## Review Triage Log + +### 2026-08-25 — Review pass +- intent_gap: 0 +- bad_spec: 0 +- patch: 15: (high 8, medium 5, low 2) +- defer: 0 +- reject: 3: (high 0, medium 3, low 0) +- addressed_findings: + - `[high]` `[patch]` `RootLock` переведён на independently-opened directory FD; regression без `clone` доказывает, что cleanup не удаляет live temp. + - `[high]` `[patch]` Все преобразования FD в `File` используют checked `F_DUPFD_CLOEXEC` и возвращают `Storage` при отказе duplicate. + - `[high]` `[patch]` Verified и legacy reads ограничены фактическим `MAX_ARTIFACT_BYTES + 1`, поэтому рост файла не создаёт unbounded allocation. + - `[high]` `[patch]` Создание `sha256` и shard namespace edges теперь fsync-ит parent directory и покрыто fault-checkpoint regression для обоих уровней. + - `[high]` `[patch]` Housekeeping обходит только canonical `00..ff` shards и расходует `scan_budget` только на их entries без лишнего `readdir` после exhaustion. + - `[high]` `[patch]` Ошибки `readdir`, открытия canonical shard и `fstatat` больше не маскируются как успешный неполный scan. + - `[high]` `[patch]` Stale capability сохраняет и повторно проверяет seconds+nanos mtime и subsecond grace перед unlink. + - `[high]` `[patch]` Crash/fault test state сериализован, а default-parallel crate suite повторно проходит без checkpoint races. + - `[medium]` `[patch]` `result_limit` применяется после stale validation; `omitted` считает только подтверждённые stale candidates, включая limits 1 и 0. + - `[medium]` `[patch]` Relative legacy root теперь отклоняется fail closed вместо несовместимого сравнения с absolute `file://`. + - `[medium]` `[patch]` Integration test fault hooks закрыты `debug_assertions`; release test build компилируется без production export hooks. + - `[medium]` `[patch]` Oversized legacy file `MAX_ARTIFACT_BYTES + 1` явно отклоняется regression test. + - `[medium]` `[patch]` Non-regular directory на final digest явно возвращает integrity failure. + - `[low]` `[patch]` Каноничность ref закреплена отдельной проверкой 64 lowercase против same-length uppercase digest. + - `[low]` `[patch]` Неиспользуемая production dependency `rustix` удалена из crate, workspace и lockfile. + +### 2026-08-25 — Review pass +- intent_gap: 0 +- bad_spec: 6: (high 5, medium 1, low 0) +- patch: 12: (high 0, medium 6, low 6) +- defer: 0 +- reject: 0 +- addressed_findings: + - `[high]` `[bad_spec]` Закреплены trusted euid ownership/mode требования к root и созданным directories. + - `[high]` `[bad_spec]` Закреплены owner/regular/single-link/read-only/digest invariants для existing final blob. + - `[high]` `[bad_spec]` Stale-temp cleanup получил root/inode/age capability revalidation и cooperative lock против live/replacement/cross-store races. + - `[high]` `[bad_spec]` Housekeeping обязан stream-ить каталог и соблюдать отдельные scan/result budgets вместо полного `Vec`. + - `[high]` `[bad_spec]` Crash/disk-full verification перенесена на abrupt child-process и syscall-coupled checkpoints, а не только in-process return hooks. + - `[medium]` `[bad_spec]` Temp naming требует process-unique random nonce, чтобы crash/PID reuse не исчерпывали фиксированное окно имён. + +## Design Notes + +Pinned directory FDs являются authority на весь lifetime store. Path root нужен только для безопасного initial open; root/created directories проверяются на euid ownership и private mode. После открытия operations используют `*at`/`openat2` с no-symlink constraints. Temp получает random process nonce, держит shared cooperative root lock до publish и находится с final в одном shard; cleanup берёт exclusive lock и повторно проверяет root identity, inode и age перед unlink+fsync. Existing final принимается только как owned, regular, single-link, non-writable inode с верным digest. Publish не имеет replacing fallback; retry после rename повторно verified-read и directory fsync. Listing stream-ит не более `scan_budget` entries и возвращает не более `result_limit`. Test checkpoints оборачивают реальные write/fsync/rename operations; forked child завершается через `_exit`, parent открывает новый store. Решение «orphan или referenced» остаётся в Story 2.2. + +## Verification + +**Commands:** +- `cargo test -p crank-artifacts` — весь filesystem/security/recovery contract проходит. +- `cargo clippy -p crank-artifacts --all-targets --all-features -- -D warnings` — crate без lint warnings. +- `python3 -m unittest tests.unit.test_check_rust_boundaries` — leaf boundary regression проходит. +- `cargo fmt --all --check && just rust-boundaries && just rust-code-health` — workspace conventions и executable architecture проходят. +- `just verify` — полный workspace regression gate проходит. + +## Completion Evidence + +### 2026-08-25 — Независимое follow-up review и закрытие + +- Три независимых слоя проверили полный tracked/untracked diff: blind hunter, edge-case hunter и verification-gap reviewer. +- Исправлены production gaps: dev-only boundary semantics, blocking FIFO opens, user-reader self-deadlock, namespace fsync retry, pre-syscall fault injection, disappearing-temp race, single-use cleanup capability, future mtime и lexical legacy root. +- Усилена evidence matrix: same-size corruption, digest-matching symlinks, exact maximum round-trip, positive grace, initial-root symlink, multi-process dedupe и bounded child-process FIFO scenarios. +- `cargo test -p crank-artifacts -- --test-threads=1` — 28/28 тестов прошли. +- Targeted format/clippy/release/boundary/code-health gates прошли без ошибок; Python boundary suite — 16/16. +- Полный `just verify` прошёл до конца: workspace clippy и все non-ignored workspace tests зелёные. +- Финальный post-fix security audit не нашёл high/medium блокеров. + +## Suggested Review Order + +**Storage authority и durable publish** + +- Public boundary закрепляет root FD, bounded ingress и verified reads. + [`store.rs:71`](../../crates/crank-artifacts/src/store.rs#L71) + +- Publication связывает fault semantics с write/fsync/no-clobber namespace operations. + [`store.rs:209`](../../crates/crank-artifacts/src/store.rs#L209) + +- Canonical opaque reference исключает filesystem path из public contract. + [`model.rs:12`](../../crates/crank-artifacts/src/model.rs#L12) + +**Recovery и compatibility** + +- Single-use stale capability повторно проверяется под exclusive root lock. + [`housekeeping.rs:11`](../../crates/crank-artifacts/src/housekeeping.rs#L11) + +- Legacy `file://` остаётся digest-verified и привязанным к pinned root. + [`store.rs:168`](../../crates/crank-artifacts/src/store.rs#L168) + +**Architecture и доказательства** + +- Executable boundary разрешает test-only support, сохраняя production leaf invariant. + [`check-rust-boundaries.py:91`](../../scripts/check-rust-boundaries.py#L91) + +- Filesystem matrix покрывает process races, crash recovery, corruption и blocking entries. + [`artifact_store.rs:65`](../../crates/crank-artifacts/tests/artifact_store.rs#L65) + +- Boundary regressions различают dev, build и mixed dependency declarations. + [`test_check_rust_boundaries.py:203`](../../tests/unit/test_check_rust_boundaries.py#L203) diff --git a/_bmad-output/implementation-artifacts/spec-2-1-openapi-source.md b/_bmad-output/implementation-artifacts/spec-2-1-openapi-source.md new file mode 100644 index 0000000..d461c84 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-1-openapi-source.md @@ -0,0 +1,146 @@ +--- +title: '2.1 — Безопасно сохранять загруженный OpenAPI source' +type: 'feature' +created: '2026-08-25' +status: 'superseded' +baseline_revision: '182bde8ac0709709be849f5ab51d2ce02aa5410b' +baseline_commit: '182bde8ac0709709be849f5ab51d2ce02aa5410b' +review_loop_iteration: 0 +followup_review_recommended: false +context: + - '_bmad-output/implementation-artifacts/epic-2-context.md' +warnings: [oversized, superseded-by-split] +deferred: [] +--- + +> Историческая спецификация остановленной попытки. После timeout и проверки scope заменена Stories 2.1a–2.1d; не использовать как вход для нового запуска. + + + +## Intent + +**Problem:** Текущий OpenAPI preview принимает неограниченную JSON-строку, сразу парсит её и не сохраняет исходные bytes. Поэтому preview и последующий import не имеют общего immutable source, а upload, целостность, isolation и recovery не защищены. + +**Approach:** Добавить самостоятельный `crank-artifacts` с content-addressed immutable storage, PostgreSQL metadata и reconciliation; перевести Admin API/UI на bounded multipart upload, после сохранения читать source только с проверкой digest и лишь затем передавать parser’у. + +## Boundaries & Constraints + +**Always:** принимать один UTF-8 файл `.yaml`/`.yml`/`.json` размером не более 256 KiB; определять путь только из opaque SHA-256 ref; выполнять temp write → file fsync → atomic no-clobber publish → directory fsync; разделять физическую дедупликацию и workspace-scoped metadata; не возвращать и не логировать raw source, реальные пути или cross-scope existence; проверять digest при каждом read; сохранять compatibility read только для absolute `file://` под явно configured legacy root. + +**Block If:** безопасная реализация требует platform contract за пределами Linux reference deployment либо существующая migration authority не позволяет добавить forward-only v12 без изменения уже применённых миграций. + +**Never:** не менять и не откатывать `sprint-status.yaml`; не создавать Draft Operations в story 2.1; не использовать filename/document path для filesystem path; не принимать `file://` при новом upload; не следовать symlink; не перечитывать mutable external source; не включать raw bytes/examples/descriptions в ошибки, logs, traces, metrics или browser telemetry; не переписывать legacy ref и не удалять legacy file до успешной verification. + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|--------------|---------------------------|----------------| +| Valid upload | Один multipart file, supported name/MIME, UTF-8, 1..262144 bytes | Opaque artifact ref и bounded safe metadata; bytes durable; parser получает verified bytes | No error expected | +| Invalid upload | Empty, oversized, malformed multipart, unsupported extension/MIME/encoding | Ни metadata, ни Draft, ни final artifact | Stable localized 400/413 code + Request/Trace ID, без source/parser text | +| Duplicate/race | Одинаковые bytes в одном или разных workspace, конкурентные writers | Один immutable blob, независимые scoped metadata; чужой scope неразличим | Idempotent success без existence oracle | +| Integrity failure | Metadata есть, blob missing/corrupt | Parsing не запускается | Typed integrity error, без fallback | +| Recovery | Orphan старше grace period либо concurrent referenced blob | Удаляется только подтверждённый orphan; referenced blob сохраняется | Bounded sweep report | +| Hostile/legacy path | Traversal, symlink, absolute path; либо existing legacy `file://` | New refs rejected; legacy read только под configured root и с digest verification | Typed path/integrity error; source не меняется | + + + +## Code Map + +- `Cargo.toml` — workspace members/dependencies; зарегистрировать новый `crank-artifacts`. +- `crates/crank-artifacts/src/lib.rs` — новый pure filesystem boundary: opaque refs, bounded atomic writes, verified reads, legacy-root compatibility и orphan sweep; fault-injection/clock seams нужны recovery tests. +- `crates/crank-artifacts/tests/` — known-digest, concurrent dedupe, crash/disk-full, corruption, traversal/symlink, legacy и sweep tests. +- `crates/crank-registry/src/migrations/authority.rs:18` и новый `artifact_sources_v12.{rs,sql}`/`schema_guard_v12.rs` — forward-only metadata schema и migration contract; прошлые migration sources read-only. +- `crates/crank-registry/src/model.rs`, `src/postgres/artifact_source.rs`, `src/postgres/mod.rs`, `src/lib.rs` — typed metadata/repository API с workspace-scoped lookup и safe sweep claim/delete. +- `apps/admin-api/src/service.rs:52` и `src/storage.rs:9` — подключить artifact store к `AdminService`; существующий sample `file://` path не расширять на OpenAPI. +- `apps/admin-api/src/routes/imports.rs:25`, `src/app.rs:51`, `src/dto.rs:527` — заменить preview upload на bounded multipart contract и stable localized outcomes. +- `apps/admin-api/src/service/imports.rs:32` — upload → durable bytes → metadata commit → verified read → parser; сохранить artifact identity в import job и не создавать Operations. +- `apps/admin-api/src/error.rs:39` — переиспользовать 413/envelope, добавить bounded artifact error mapping без IO/path/parser details. +- `apps/ui/js/api.js:412`, `apps/ui/js/openapi-import.js:342`, `apps/ui/index.html:395` — отправлять `FormData`, реализовать RU/EN idle/validating/uploading/error/success/cancel и monotonic request token/abort против stale response. +- `apps/admin-api/tests/integration/openapi_source.rs`, `crates/crank-registry/tests/integration/`, `apps/ui/tests/e2e/operations.spec.js` — outer-surface regression matrix; текущие JSON preview tests обновить без ослабления apply assertions. + +## Tasks & Acceptance + +**Execution:** +- `crates/crank-artifacts/**`, `Cargo.toml`, `Cargo.lock` — реализовать bounded content-addressed store и exhaustive negative/recovery tests — изолировать filesystem security/durability от Admin API. +- `crates/crank-registry/src/{migrations,postgres,model.rs,lib.rs}` — добавить v12 metadata (`workspace`, digest/ref, size, MIME, sensitivity, lifecycle, timestamps), scoped CRUD и sweep coordination — сделать ownership и recovery транзакционными. +- `apps/admin-api/src/{app.rs,dto.rs,error.rs,routes/imports.rs,service.rs,service/imports.rs}` — внедрить multipart upload, stable errors, metadata commit и verified source read до parsing — обеспечить единые bytes preview/import. +- `apps/ui/{index.html,js/api.js,js/openapi-import.js}` — заменить textarea transport на file upload и локализованные race-safe состояния — покрыть пользовательскую поверхность AC. +- `apps/admin-api/tests/integration/openapi_source.rs`, `apps/admin-api/tests/integration/openapi_import.rs`, `crates/crank-registry/tests/integration/**`, `apps/ui/tests/e2e/operations.spec.js` — проверить всю матрицу, restart durability, scope isolation и отсутствие source canary в diagnostics. +- `docs/admin-api.md`, `docs/runtime-config.md`, `docs/openapi-import.md` — зафиксировать multipart/bounds, opaque ref, lifecycle/sweeper и legacy-root compatibility contract. + +**Acceptance Criteria:** +- Given authenticated Admin API, when `.yaml`/`.yml`/`.json` загружается multipart, then validation filename/MIME/size/UTF-8 происходит до parsing, invalid inputs дают stable RU/EN error и не создают artifact metadata, import job или Draft. +- Given valid bytes, when upload завершается и сервис перезапускается, then SHA-256 ref, fsync/atomic persistence и workspace metadata сохраняются, а verified read возвращает byte-identical source. +- Given duplicate/concurrent uploads and two workspaces, when refs читаются/listed, then physical bytes deduplicated, scoped metadata independent, а foreign ref выглядит как обычный not-found без утечки свойств. +- Given crash windows, corruption, disk-full and orphan sweep, when recovery runs after grace period, then only confirmed unreferenced blobs удаляются, referenced/concurrently-committed blobs survive, and missing/corrupt bytes block parsing with typed integrity error. +- Given traversal, symlink, absolute/file URL inputs and legacy refs, when storage reads/writes/deletes, then operations remain under roots; new file URLs are rejected; verified legacy reads preserve original ref/file. +- Given source canary and UI file replacement/cancel/racing responses, when upload succeeds or fails, then raw canary is absent from telemetry/DOM diagnostics, RU/EN state is correct, and stale response cannot replace the newest file state. + +## Spec Change Log + +## Review Triage Log + +### Review Findings — 2026-08-28, aggregate Story 2.1 review + +- [x] [Review][Patch][high] Подготовить private artifact root в reference Docker deployment: новый named volume сейчас имеет mode `0755`, а `ArtifactStore::open` требует ровно `0700`, поэтому чистая Community-установка не стартует [apps/admin-api/Dockerfile:17] +- [x] [Review][Patch][high] Сделать cleanup expired import jobs и dangling sources исчерпывающим и периодическим: одна пачка `128` при startup/preview/apply оставляет backlog и не обслуживает тихий долгоживущий процесс [crates/crank-registry/src/postgres/import_job.rs:146] +- [x] [Review][Patch][high] Изолировать повреждённые `preview_payload.source`: одна malformed row не должна откатывать всю cleanup-транзакцию и блокировать startup/новые imports [crates/crank-registry/src/postgres/import_job.rs:163] +- [x] [Review][Patch][high] Устранить race `Pending`/concurrent apply: запрос, прочитавший старый Pending, должен получить canonical replay завершённой job, а не `source_unavailable` [apps/admin-api/src/service/imports.rs:179] +- [x] [Review][Patch][high] Зафиксировать parser contract между preview и apply: rolling upgrade не должен молча применить иной набор операций или пропустить выбранные keys после повторного parse [apps/admin-api/src/service/imports.rs:203] +- [x] [Review][Patch][high] Сделать отмену/закрытие UI во время mutating apply outcome-aware: browser abort не отменяет серверный commit и не должен терять job authority либо провоцировать duplicate renamed drafts [apps/ui/js/openapi-import.js:442] +- [x] [Review][Patch][medium] Подключить production cleanup stale temp files с bounded continuation, чтобы crash leftovers не накапливались и ранние shards не создавали starvation [crates/crank-artifacts/src/housekeeping.rs:321] +- [x] [Review][Patch][medium] Сделать аварийный detach source надёжным при cancellation/shutdown вместо fire-and-forget `Drop`, результат которого теряется [apps/admin-api/src/service/imports.rs:420] +- [x] [Review][Patch][medium] Добавить bounded deadlines для startup/periodic reconciliation и parsing, чтобы зависший DB/FS/parser вызов не блокировал startup либо worker навсегда [apps/admin-api/src/reconciliation.rs:729] +- [x] [Review][Patch][medium] Перенести `ArtifactStore::clone`/FD duplication внутрь `spawn_blocking`, соблюдая контракт отсутствия filesystem syscalls на async executor [apps/admin-api/src/reconciliation.rs:248] +- [x] [Review][Patch][medium] Нормализовать MIME через parsed essence перед validation и persistence; корректные типы с parameters/case не должны расходиться между route и service [apps/admin-api/src/routes/imports.rs:71] +- [x] [Review][Patch][medium] Учитывать quality weights/order в `Accept-Language` и передавать locale в create/apply API, включая reparse и diagnostics [apps/admin-api/src/routes/imports.rs:125] +- [x] [Review][Patch][medium] Сохранять unknown-operation skips в canonical `ImportJobApplyResult`, чтобы idempotent replay был идентичен первому ответу [apps/admin-api/src/service/imports.rs:211] +- [x] [Review][Patch][medium] Добавить `operation_key` в created response и сопоставлять UI result с preview по стабильному key, а не по имени после rename [apps/admin-api/src/service/imports.rs:272] +- [x] [Review][Patch][medium] Отделить успешный server commit от ошибки `onImported()`/refresh, чтобы UI не сообщал о неуспешном создании уже созданных drafts [apps/ui/js/openapi-import.js:719] +- [x] [Review][Patch][medium] Устранить противоречие `Specify later`/обязательный Base URL и очищать server selection при `pagehide` согласно UX contract [apps/ui/js/openapi-import.js:273] +- [x] [Review][Patch][medium] Расширить readiness проверкой доступности artifact subsystem, а не только PostgreSQL [apps/admin-api/src/service.rs:127] +- [x] [Review][Patch][medium] Добавить индексы для expired jobs, JSON source lookup, expired claims и reconciliation/source lookup через новую forward-only migration [crates/crank-registry/src/migrations/artifact_metadata_v12.sql:60] +- [x] [Review][Patch][medium] Исправить idempotency detach с `expected_updated_at: None`: точный replay уже выполненного unconditional detach не должен конфликтовать [crates/crank-registry/src/postgres/artifact_source.rs:504] +- [x] [Review][Patch][medium] Изолировать process-global fault seams/counters, чтобы обычный default-parallel `crank-artifacts` test run был стабильным, а CI не скрывал гонку `--test-threads=1` [crates/crank-artifacts/tests/reconciliation.rs:1] +- [x] [Review][Patch][medium] Убрать календарную зависимость из claim-revival regression test и использовать согласованный database clock [crates/crank-registry/tests/integration/artifact_reconciliation.rs:1] +- [x] [Review][Patch][medium] Усилить fail-closed evidence validator: `accepted=true` допустим только для automated/pass evidence, а не произвольного schema-valid кандидата [scripts/validate-capability-run.py:125] +- [x] [Review][Patch][medium] Добавить изолированный lifecycle regression для `no_methods`, проверяющий отсутствие active source, а не наличие любого detached source после нескольких ошибок [apps/admin-api/tests/integration/openapi_source.rs:350] +- [x] [Review][Patch][medium] Проверять смену языка реальным `window.setLang()`/`crank:langchange`, а не только вручную созданным `StorageEvent` [apps/ui/tests/e2e/operations.spec.js:449] +- [x] [Review][Patch][medium] Добавить process-level startup test, который доказывает вызов immediate reconciliation и lifecycle cleanup из реальной composition root [apps/admin-api/src/main.rs:206] + +### Дополнительный независимый проход — 2026-08-29 + +- [x] [Review][Patch][high] Сохранять authority mutating apply в `sessionStorage` и восстанавливать ту же job после close/pagehide/reload, блокируя изменение inputs до canonical replay. +- [x] [Review][Patch][medium] Сделать V13 schema guard точным для всех пяти cleanup/reconciliation indexes, включая key order, predicate, uniqueness и validity/readiness. +- [x] [Review][Patch][medium] Ограничить одновременно живущие blocking parser tasks глобальным semaphore и общим 30-секундным deadline. +- [x] [Review][Patch][medium] Продолжать stale-temp scan за omitted entry и исчерпывать страницы в пределах bounded deadline без starvation. +- [x] [Review][Patch][medium] Ограничить все три startup maintenance phase одним внешним 30-секундным deadline. +- [x] [Review][Patch][medium] Считать HTTP 4xx, кроме 408, definitive apply outcome: очищать replay authority и разблокировать UI. +- [x] [Review][Dismissed][medium] Не восстанавливать прежний публичный Rust-конструктор с owned `ArtifactStore`: Community API ещё pre-release, а `Arc` исключает FD duplication и blocking syscall на async executor; breaking cleanup ранее явно принят владельцем продукта. + +## Design Notes + +Physical blob identity is global SHA-256, but authorization is exclusively a PostgreSQL workspace metadata relation. Sweeper uses a two-phase candidate/recheck protocol after grace period; deletion never follows caller paths. Import jobs refer to the scoped source metadata id plus digest, so subsequent stories can reverify the same bytes without embedding source in preview JSON. + +## Verification + +**Commands:** +- `cargo test -p crank-artifacts` — all storage failure/race/path tests pass. +- `cargo test -p crank-registry --test integration -- --test-threads=1` — v12 metadata, isolation and migration tests pass. +- `cargo test -p admin-api --test integration -- --test-threads=1` — multipart and preview integration tests pass. +- `cd apps/ui && npm run e2e -- operations.spec.js` — RU/EN upload states and stale-response tests pass. +- `just verify` — full Rust/config/migration/lint/test gate passes. +- `just verify-ui` — production UI bundle builds. + +### Aggregate review verification — 2026-08-29 + +- `cargo check -p crank-artifacts -p crank-registry -p admin-api --all-targets` — pass. +- `cargo clippy -p crank-artifacts -p crank-registry -p admin-api --all-targets -- -D warnings` — pass. +- `cargo test -p crank-artifacts --all-targets` — 57 tests pass при default parallelism. +- `cargo test -p crank-registry --test integration -- --test-threads=1` — 82 pass, 1 documented production-scale query-plan test ignored. +- `cargo test -p admin-api --lib` — 37 pass; `config_startup` — 6 pass; Admin integration — 66 pass. +- `npm run build`, OpenAPI Playwright E2E и `python3 -m unittest tests.unit.test_validate_capability_run` — pass. +- `docker buildx build --load -f apps/admin-api/Dockerfile -t crank/admin-api:story-2-1-review .` — pass; fresh named volume provisioned as `0700`, relative storage root rejected with exit 64. +- `cargo fmt --all -- --check`, `git diff --check`, JS/shell syntax и все три `docker compose config` — pass. + +**Verdict:** все подтверждённые high/medium findings устранены; Story 2.1 и её части 2.1a–2.1d приняты. Один compatibility warning отклонён как осознанный pre-release API cleanup. Production-scale million-row query-plan evidence остаётся отдельным тяжёлым CI/release gate, а не блокером корректности Story. diff --git a/_bmad-output/implementation-artifacts/spec-2-1a-openapi-artifact-store.md b/_bmad-output/implementation-artifacts/spec-2-1a-openapi-artifact-store.md new file mode 100644 index 0000000..5e5d8b4 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-1a-openapi-artifact-store.md @@ -0,0 +1,8 @@ +--- +status: superseded +canonical_spec: _bmad-output/implementation-artifacts/spec-2-1-openapi-artifact-store.md +--- + +# Historical story reference + +Story numbering changed on 2026-09-13. Use [spec-2-1-openapi-artifact-store.md](spec-2-1-openapi-artifact-store.md). This redirect is not an actionable story. Archived loop runs retain their original IDs; do not resume them against the renumbered sprint. diff --git a/_bmad-output/implementation-artifacts/spec-2-1b-openapi-source-metadata.md b/_bmad-output/implementation-artifacts/spec-2-1b-openapi-source-metadata.md new file mode 100644 index 0000000..22947ec --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-1b-openapi-source-metadata.md @@ -0,0 +1,8 @@ +--- +status: superseded +canonical_spec: _bmad-output/implementation-artifacts/spec-2-2-openapi-source-metadata.md +--- + +# Historical story reference + +Story numbering changed on 2026-09-13. Use [spec-2-2-openapi-source-metadata.md](spec-2-2-openapi-source-metadata.md). This redirect is not an actionable story. Archived loop runs retain their original IDs; do not resume them against the renumbered sprint. diff --git a/_bmad-output/implementation-artifacts/spec-2-1b2a-artifact-filesystem-reconciliation.md b/_bmad-output/implementation-artifacts/spec-2-1b2a-artifact-filesystem-reconciliation.md new file mode 100644 index 0000000..def5867 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-1b2a-artifact-filesystem-reconciliation.md @@ -0,0 +1,5 @@ +# Legacy redirect: 2.1b2a + +Canonical completed Story: [2.3 — filesystem reconciliation](spec-2-3-artifact-filesystem-reconciliation.md). + +Legacy alias mapping (2026-09-13): `2.1b2a` / `2.1e` → `2.3`. Historical reference only, not an actionable story. diff --git a/_bmad-output/implementation-artifacts/spec-2-1b2b-artifact-claim-recovery.md b/_bmad-output/implementation-artifacts/spec-2-1b2b-artifact-claim-recovery.md new file mode 100644 index 0000000..e7f9ed2 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-1b2b-artifact-claim-recovery.md @@ -0,0 +1,5 @@ +# Legacy redirect: 2.1b2b + +Canonical completed Story: [2.4 — artifact claim/recovery](spec-2-4-artifact-claim-recovery.md). + +Legacy alias mapping (2026-09-13): `2.1b2b` / `2.1f` → `2.4`. Historical reference only, not an actionable story. diff --git a/_bmad-output/implementation-artifacts/spec-2-1c-openapi-upload-preview.md b/_bmad-output/implementation-artifacts/spec-2-1c-openapi-upload-preview.md new file mode 100644 index 0000000..a3932ea --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-1c-openapi-upload-preview.md @@ -0,0 +1,8 @@ +--- +status: superseded +canonical_spec: _bmad-output/implementation-artifacts/spec-2-5-openapi-upload-preview.md +--- + +# Historical story reference + +Story numbering changed on 2026-09-13. Use [spec-2-5-openapi-upload-preview.md](spec-2-5-openapi-upload-preview.md). This redirect is not an actionable story. Archived loop runs retain their original IDs; do not resume them against the renumbered sprint. diff --git a/_bmad-output/implementation-artifacts/spec-2-1d-openapi-upload-ui-evidence.md b/_bmad-output/implementation-artifacts/spec-2-1d-openapi-upload-ui-evidence.md new file mode 100644 index 0000000..0306312 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-1d-openapi-upload-ui-evidence.md @@ -0,0 +1,8 @@ +--- +status: superseded +canonical_spec: _bmad-output/implementation-artifacts/spec-2-6-openapi-upload-ui-evidence.md +--- + +# Historical story reference + +Story numbering changed on 2026-09-13. Use [spec-2-6-openapi-upload-ui-evidence.md](spec-2-6-openapi-upload-ui-evidence.md). This redirect is not an actionable story. Archived loop runs retain their original IDs; do not resume them against the renumbered sprint. diff --git a/_bmad-output/implementation-artifacts/spec-2-1e-artifact-filesystem-reconciliation.md b/_bmad-output/implementation-artifacts/spec-2-1e-artifact-filesystem-reconciliation.md new file mode 100644 index 0000000..6c8dbbb --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-1e-artifact-filesystem-reconciliation.md @@ -0,0 +1,8 @@ +--- +status: superseded +canonical_spec: _bmad-output/implementation-artifacts/spec-2-3-artifact-filesystem-reconciliation.md +--- + +# Historical story reference + +Story numbering changed on 2026-09-13. Use [spec-2-3-artifact-filesystem-reconciliation.md](spec-2-3-artifact-filesystem-reconciliation.md). This redirect is not an actionable story. Archived loop runs retain their original IDs; do not resume them against the renumbered sprint. diff --git a/_bmad-output/implementation-artifacts/spec-2-1f-artifact-claim-recovery.md b/_bmad-output/implementation-artifacts/spec-2-1f-artifact-claim-recovery.md new file mode 100644 index 0000000..a0033f0 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-1f-artifact-claim-recovery.md @@ -0,0 +1,8 @@ +--- +status: superseded +canonical_spec: _bmad-output/implementation-artifacts/spec-2-4-artifact-claim-recovery.md +--- + +# Historical story reference + +Story numbering changed on 2026-09-13. Use [spec-2-4-artifact-claim-recovery.md](spec-2-4-artifact-claim-recovery.md). This redirect is not an actionable story. Archived loop runs retain their original IDs; do not resume them against the renumbered sprint. diff --git a/_bmad-output/implementation-artifacts/spec-2-2-openapi-normalizedir.md b/_bmad-output/implementation-artifacts/spec-2-2-openapi-normalizedir.md new file mode 100644 index 0000000..1c0b3eb --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-2-openapi-normalizedir.md @@ -0,0 +1,8 @@ +--- +status: superseded +canonical_spec: _bmad-output/implementation-artifacts/spec-2-7-openapi-normalizedir.md +--- + +# Historical story reference + +Story numbering changed on 2026-09-13. Use [spec-2-7-openapi-normalizedir.md](spec-2-7-openapi-normalizedir.md). This redirect is not an actionable story. Archived loop runs retain their original IDs; do not resume them against the renumbered sprint. diff --git a/_bmad-output/implementation-artifacts/spec-2-2-openapi-source-metadata.md b/_bmad-output/implementation-artifacts/spec-2-2-openapi-source-metadata.md new file mode 100644 index 0000000..b7d2081 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-2-openapi-source-metadata.md @@ -0,0 +1,129 @@ +--- +title: '2.2 — Добавить workspace-scoped metadata artifacts' +type: 'feature' +created: '2026-08-26' +status: 'done' +baseline_revision: '497e1b740f7c319413da060fb2234ad63842c7dd' +review_loop_iteration: 0 +followup_review_recommended: false +context: + - '_bmad-output/implementation-artifacts/epic-2-context.md' +warnings: [oversized] +deferred: [] +--- + + + +## Intent + +**Problem:** Immutable blobs уже существуют, но PostgreSQL не хранит изолированную по workspace source metadata. Без неё общий digest способен стать existence/MIME/size oracle, а upload и reconciliation не имеют строгого транзакционного контракта. + +**Approach:** Добавить forward-only V12 schema и registry API с отдельными global blob records и workspace-owned source relations; реализовать scoped CRUD/list/detach, идемпотентный replay и verified read через `crank-artifacts` с безопасными typed outcomes. + +## Boundaries & Constraints + +**Always:** выполнять source lookup/mutation по authoritative `(workspace_id, source_id)`; хранить только canonical opaque artifact ref/digest и bounded metadata; фиксировать lifecycle transitions транзакционно; сначала получать scoped metadata, затем читать и проверять blob; возвращать одинаковый scoped not-found для чужого и отсутствующего source; сохранять предыдущие migration sources и checksums неизменными. + +**Block If:** реализация требует ослабить workspace isolation, принимать caller-supplied physical ref как authority либо изменить immutable API/гарантии `crank-artifacts`. + +**Never:** не менять `sprint-status.yaml`; не переиспользовать unscoped `operation_samples`/`descriptors`; не хранить raw source, caller path или mutable URL; не делать external refetch, filesystem cleanup, orphan reconciliation, HTTP/upload/parser/UI flow; не удалять metadata при missing/corrupt blob; не раскрывать digest/ref, size или MIME через foreign-scope ошибки. + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|--------------|---------------------------|----------------| +| Create/replay | Новый scoped source либо точный повтор identity+metadata | Одна active relation; повтор возвращает тот же record без изменения lifecycle timestamps | Отличающиеся immutable поля дают typed conflict | +| Shared digest | Один blob привязан к разным workspace | Независимые source relations и один global blob record | Ни один workspace не узнаёт metadata другого | +| Scoped get/list | Свой, чужой или отсутствующий source; bounded cursor page | Только owned records в детерминированном порядке | Чужой/отсутствующий id — один `SourceNotFound` | +| Detach | Active, уже detached или конфликтно изменённый source | Conditional transition и timestamps фиксируются атомарно; exact retry идемпотентен | Concurrent/incompatible transition — typed conflict | +| Verified read | Metadata указывает на valid, missing, corrupt или wrong-size blob | Bytes возвращаются только после digest и size verification | Typed unavailable/integrity outcome без refetch, path/ref/raw bytes | +| Migration | Clean DB, V11 upgrade/replay, drift или injected failure | Ровно V12 schema+ledger либо полный rollback | Exact guard отклоняет drift и неожиданные V12-owned objects | + + + +## Code Map + +- `crates/crank-registry/src/migrations/authority.rs:17-19,174-245,275-375,474-503` — поднять canonical sequence до V12, добавить descriptor/apply/source-hash; V1–V11 не изменять. +- `crates/crank-registry/src/migrations/{artifact_metadata_v12.rs,artifact_metadata_v12.sql,schema_guard_v12.rs}` — новая append-only DDL и exact guard для V12 columns/defaults/constraints/indexes/relation kinds. +- `crates/crank-registry/src/migrations/{schema_guard.rs,owned_relations.rs}` и `crates/crank-registry/src/migrations.rs` — зарегистрировать V12 objects, pre-V12 absence и post-V12 validation. +- `crates/crank-registry/src/{model.rs,error.rs,lib.rs}` — typed source/blob records, IDs, sensitivity/lifecycle, cursor page и public errors/API. +- `crates/crank-registry/src/postgres/artifact_source.rs` и `crates/crank-registry/src/postgres/mod.rs` — scoped repository, row mapping и транзакционные create/get/list/detach operations; reuse `operation.rs` scoped `FOR UPDATE` и `product_event.rs` replay patterns. +- `crates/crank-artifacts/src/{model.rs,store.rs,error.rs}` — read-only boundary: canonical `ArtifactRef`, verified `ArtifactStore::read`, stable physical failures; workspace policy сюда не переносить. +- `crates/crank-registry/tests/integration/{artifact_sources.rs,migrations.rs,migrations/rollback.rs,common.rs}` — outer PostgreSQL/scoping/lifecycle/V12 evidence; legacy `operations_artifacts.rs` не менять. +- `docs/schemas/migration-sequence.json`, `docs/migrations.md`, `apps/admin-api/tests/migration_command.rs` — синхронизировать machine-readable и operator-visible migration contract до V12. + +## Tasks & Acceptance + +**Execution:** +- `crates/crank-registry/src/migrations/**`, `docs/schemas/migration-sequence.json`, `docs/migrations.md` — добавить V12 global blob + workspace source schema, bounded lifecycle/claim fields и exact drift guard; сохранить forward-only authority. +- `crates/crank-registry/src/{model.rs,error.rs,lib.rs}`, `src/postgres/{mod.rs,artifact_source.rs}` — реализовать typed scoped repository, replay/conflict, keyset pagination и detach transition; исключить global lookup из caller path. +- `crates/crank-registry/src/postgres/artifact_source.rs`, `crates/crank-registry/Cargo.toml` — скомпоновать scoped metadata lookup с `ArtifactStore::read` и explicit size check; redacted typed outcome должен остановить downstream processing. +- `crates/crank-registry/tests/integration/**`, `apps/admin-api/tests/migration_command.rs` — покрыть I/O matrix реальным PostgreSQL и filesystem store, включая cross-workspace, tamper, replay и rollback. + +**Acceptance Criteria:** +- Given действующая V11 authority, when применяется V12 на clean либо upgraded database, then ledger и exact normalized schema содержат scoped source id, workspace FK, canonical digest/ref, size, MIME, sensitivity, relation lifecycle/timestamps и bounded global blob lifecycle/claim fields, а V1–V11 sources/checksums остаются неизменными. +- Given drift любого V12 column/type/nullability/default/constraint/index/relation kind либо неожиданный V12-owned object, when schema guard проверяет database, then проверка детерминированно отклоняет schema без substring matching; injected migration failure не оставляет частичных objects или ledger row. +- Given один physical digest и несколько workspace, when source создаётся, читается или перечисляется, then relations независимы, pagination bounded и детерминирована, а foreign id/ref даёт тот же `SourceNotFound`, что отсутствующий id, без metadata oracle. +- Given identical либо conflicting replay, when repository создаёт relation, then exact replay идемпотентен и сохраняет исходные lifecycle timestamps, а несовпадающие immutable metadata дают typed conflict без частичной записи. +- Given active или уже detached source, when detach повторяется либо конкурирует с изменением, then transition и timestamps проверяются под scoped transaction/lock, exact retry идемпотентен, а incompatible state даёт typed conflict; physical blob не удаляется. +- Given scoped metadata с valid, missing, corrupt или wrong-size blob, when verified read выполняется через реальный `ArtifactStore`, then только valid bytes возвращаются, остальные случаи дают bounded typed unavailable/integrity outcome без refetch, substitution, удаления metadata или раскрытия raw source/path/ref. +- Given полный registry integration suite, when выполняются clean/V11→V12/replay/tamper/rollback, scoped CRUD/list/detach, cross-workspace и verified-read scenarios, then тесты проходят последовательно и migration, boundary, formatting, lint и workspace gates остаются зелёными. + +## Spec Change Log + +## Review Triage Log + +- Исправлено: создание metadata принимает только opaque `RegisteredArtifact`, поэтому знание чужого digest не создаёт workspace relation и не раскрывает global blob metadata. +- Исправлено: cursor связан с workspace, IDs/MIME/size валидируются до I/O, а физическое чтение выполняется через `spawn_blocking` после scoped lookup. +- Исправлено: exact detach replay проверяет исходную revision; detached/unavailable/missing/corrupt/wrong-size состояния возвращают bounded typed outcomes. +- Исправлено: V12 guard проверяет полный набор indexes, key/include columns, persistence/RLS/options, triggers, policies, timestamp precision и сохраняет literal/parenthesis semantics constraints. +- Добавлено evidence: conflicting digest/MIME/sensitivity replay, rollback без partial objects, page cap 100, cross-workspace cursor, invalid IDs и полный verified-read matrix. +- Отклонён как несвязанный scope: аудит произвольных функций и владельцев всей schema; V12 проверяет все объекты, непосредственно привязанные к своим relations. + +## Design Notes + +V12 разделяет physical и ownership state: global blob row keyed canonical digest/ref хранит verified size, storage lifecycle и nullable bounded claim token/expiry для Stories 2.3–2.4; source row keyed `(workspace_id, source_id)` хранит blob FK, MIME, sensitivity, active/detached state и timestamps. Claim fields создаются сейчас, но не изменяются cleanup-процессом в этой story. Repository сначала разрешает source в workspace, и только после этого получает physical ref; verified-read различает owner-visible `Unavailable` и `Integrity`, но сохраняет внешние diagnostics redacted. + +## Verification + +**Commands:** +- `cargo test -p crank-registry --test integration -- --test-threads=1` — PostgreSQL V12, scoped repository и verified-read matrix проходят. +- `cargo test -p crank-artifacts -- --test-threads=1` — immutable blob boundary не регрессировал. +- `cargo clippy -p crank-registry --all-targets --all-features -- -D warnings` — новые API и tests без lint warnings. +- `cargo fmt --all --check && just migration-contract-check && just rust-boundaries && just rust-code-health` — schema/docs/architecture conventions проходят. +- `just verify` — полный workspace regression gate проходит. + +## Auto Run Result + +- Review verdict: pass после одного patch pass; открытых findings и blockers нет. +- `cargo test -p crank-registry --test integration -- --test-threads=1`: 79 passed, 1 ignored (явно production-size test). +- `cargo test -p crank-artifacts -- --test-threads=1`: 28 passed. +- `cargo clippy -p crank-registry --all-targets --all-features -- -D warnings`: passed. +- `just migration-contract-check`, `just rust-boundaries`, `just rust-code-health`: passed. +- `just verify`: passed полностью, включая workspace build, Clippy и все default tests. + +## Suggested Review Order + +**Workspace ownership и verified read** + +- Scoped repository объединяет replay, pagination, detach и fail-closed physical read. + [`artifact_source.rs:19`](../../crates/crank-registry/src/postgres/artifact_source.rs#L19) + +- Opaque registration capability исключает caller-forged digest и size authority. + [`model.rs:75`](../../crates/crank-artifacts/src/model.rs#L75) + +**V12 migration contract** + +- Global blob и workspace relation разделяют physical и ownership state. + [`artifact_metadata_v12.sql:1`](../../crates/crank-registry/src/migrations/artifact_metadata_v12.sql#L1) + +- Exact guard отклоняет structural и semantic drift зависимых объектов. + [`schema_guard_v12.rs:141`](../../crates/crank-registry/src/migrations/schema_guard_v12.rs#L141) + +**Regression evidence** + +- PostgreSQL/filesystem scenarios покрывают isolation, replay, lifecycle и integrity outcomes. + [`artifact_sources.rs:69`](../../crates/crank-registry/tests/integration/artifact_sources.rs#L69) + +- Migration tests доказывают upgrade/replay, drift rejection и transactional rollback. + [`artifact_metadata.rs:69`](../../crates/crank-registry/tests/integration/migrations/artifact_metadata.rs#L69) diff --git a/_bmad-output/implementation-artifacts/spec-2-3-artifact-filesystem-reconciliation.md b/_bmad-output/implementation-artifacts/spec-2-3-artifact-filesystem-reconciliation.md new file mode 100644 index 0000000..3eb12da --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-3-artifact-filesystem-reconciliation.md @@ -0,0 +1,133 @@ +--- +title: '2.3 — Реализовать bounded filesystem reconciliation artifacts' +type: 'feature' +created: '2026-08-27' +status: 'done' +baseline_revision: '38ba898b72a080ff5359cc40cb8cbdf82575c925' +baseline_commit: '38ba898b72a080ff5359cc40cb8cbdf82575c925' +review_loop_iteration: 0 +context: + - '_bmad-output/implementation-artifacts/epic-2-context.md' +legacy_aliases: + - '2.1b2a' +deferred: + - '2.4 — PostgreSQL claim/recheck/finalize и recovery orchestration' +--- + + + +## Intent + +**Problem:** Artifact store умеет безопасно публиковать bytes и удалять stale temp, но не может bounded/resumable обходить final/quarantine namespace. Без этого coordinator не способен безопасно восстанавливать orphan cleanup после limit, race или crash. + +**Approach:** Добавить Linux-only streaming traversal с opaque continuation и inode-bound capabilities, а также no-clobber quarantine и idempotent delete/recovery primitives. PostgreSQL claims и Admin orchestration остаются в зависимой Story 2.4. + +## Boundaries & Constraints + +**Always:** pinned private root и directory FDs остаются authority; traversal прекращает syscall work при `scan_budget` либо `result_limit`; continuation стоит до первого невыданного/retryable entry; capability фиксирует root/shard/candidate identity и повторно проверяется перед mutation; quarantine/delete fsync directory; результаты содержат только bounded counters и opaque cursor. + +**Ask First:** защита от hostile same-UID процесса внутри root `0700`; изменение artifact layout; публичное раскрытие digest/path из reconciliation types. + +**Never:** не принимать caller path/name как mutation authority; не строить полный inventory; не следовать symlink, не принимать writable/non-regular/hardlinked final; не добавлять DB claim, scheduler, HTTP/upload/parser/UI; не ослаблять существующие `put/read` guarantees. + +## I/O & Edge-Case Matrix + +| Scenario | State | Outcome | Failure | +|----------|-------|---------|---------| +| Paged scan | Canonical shards, budgets, cursor | Unchanged traversal выдаёт entries exact-once и останавливается на limit | Malformed/unsafe entry даёт bounded classification и usable cursor | +| Quarantine | Valid final capability | No-clobber move в private quarantine после identity recheck и fsync | Replaced root/shard/name/inode fail closed | +| Delete/recovery | Quarantined либо already-absent entry | Idempotent unlink + fsync; повтор подтверждает absence | Post-mutation/fsync ambiguity возвращает typed uncertain/retryable | +| Crash window | Exit до/после rename, unlink или fsync | Новый bounded scan обнаруживает recoverable state | Subsequent entries не starvation | + + + +## Code Map + +- `crates/crank-artifacts/src/housekeeping.rs:11-224` — reuse opaque `StaleTemp`, root lock, inode/mtime checks; текущий scan не имеет cursor и продолжает после result cap. +- `crates/crank-artifacts/src/store.rs:104-263,333-383,646-680` — canonical layout, pinned `0700` root, no-clobber rename и shared/exclusive lock; read-only invariants. +- `crates/crank-artifacts/src/test_support.rs:1-81` — debug fault actions `Fail/Hold/Exit`; расширить точными mutation checkpoints. +- `crates/crank-artifacts/tests/artifact_store.rs:264-445,830-934` — reuse budget, inode replacement, crash и disk-fault fixtures. + +## Tasks & Acceptance + +**Execution:** +- [x] `crates/crank-artifacts/src/housekeeping.rs` — добавить final/quarantine scanner, opaque cursor/capabilities, stop-at-limit и typed mutation outcomes. +- [x] `crates/crank-artifacts/src/store.rs` — вынести/reuse private FD-based validation, no-clobber rename, unlink и directory fsync без ослабления publish/read. +- [x] `crates/crank-artifacts/src/{lib.rs,model.rs,error.rs}` — экспортировать только необходимые opaque types и bounded reports без paths/digests. +- [x] `crates/crank-artifacts/src/test_support.rs`, `tests/artifact_store.rs` — покрыть pagination, malformed namespace, races и все crash/fault windows. + +**Acceptance Criteria:** +- Given неизменный namespace, when страницы читаются с valid budgets, then каждый entry обрабатывается ровно один раз, continuation остаётся перед failed item, syscalls не превышают limit. +- Given forged/replaced root, shard, name, inode, symlink, directory или hardlink, when mutation выполняется, then она fail closed и canonical bytes не удаляются. +- Given crash/error вокруг quarantine, unlink и fsync, when scan возобновляется, then state классифицируется детерминированно, recovery идемпотентен и последующая работа не теряется. +- Given artifact suite и workspace gates, when проверки выполняются, then существующие publish/read/temp guarantees и boundary checks остаются зелёными. + +### Review Findings + +- [x] [Review][Patch] Ввести typed retryable page outcome с continuation перед failed entry — выбран строгий resumable контракт; уже выданные в странице candidates не теряются при transient filesystem error [crates/crank-artifacts/src/housekeeping.rs:88] +- [x] [Review][Patch] Реализовать точный traversal syscall-budget и resumable cursor state machine — выбран строгий вариант без подмены syscalls логическими work units [crates/crank-artifacts/src/housekeeping.rs:114] +- [x] [Review][Patch] Unsafe canonical shard должен классифицироваться и не блокировать последующие shards [crates/crank-artifacts/src/housekeeping.rs:137] +- [x] [Review][Patch] Валидный concurrent temp entry не должен считаться malformed artifact [crates/crank-artifacts/src/housekeeping.rs:167] +- [x] [Review][Patch] Закрепить redacted `Debug` opaque cursor и candidate regression-тестом [crates/crank-artifacts/tests/reconciliation.rs:56] +- [x] [Review][Patch] Доказать destination fsync после source failure и отдельный destination failure [crates/crank-artifacts/tests/reconciliation.rs:329] +- [x] [Review][Patch] Проверить no-clobber collision с unrelated quarantine inode [crates/crank-artifacts/tests/reconciliation.rs:211] +- [x] [Review][Patch] Отдельно проверить post-scan hardlink revalidation без inode replacement [crates/crank-artifacts/tests/reconciliation.rs:245] +- [x] [Review][Patch] Закрепить точные `scanned`, `final_entries` и `quarantined_entries` counters [crates/crank-artifacts/tests/reconciliation.rs:56] +- [x] [Review][Patch] Покрыть `FaultAction::Fail` для rename, destination fsync и unlink [crates/crank-artifacts/tests/reconciliation.rs:365] + +## Spec Change Log + +## Design Notes + +Continuation хранит открытые directory FDs, bounded `getdents64` buffer, entry offset и directory cookie; при transient ошибке `lseek` восстанавливает позицию до повторного чтения. Он валиден только для неизменного namespace, поэтому mutation создаёт новый cycle. В syscall budget входят traversal `openat/fstat/getdents64/fstatat/lseek`; root validation, lock и RAII cleanup являются фиксированным security overhead. Private root и cooperative `RootLock` остаются security boundary; внешняя same-UID запись вне текущего threat model. + +## Verification + +**Commands:** +- `cargo test -p crank-artifacts --test artifact_store -- --test-threads=1` — filesystem matrix проходит. +- `cargo clippy -p crank-artifacts --all-targets --all-features -- -D warnings` — lint green. +- `cargo fmt --all --check && just rust-boundaries && just rust-code-health && just verify` — workspace gates green. + +## Suggested Review Order + +**Bounded traversal** + +- Главная точка входа связывает budget, opaque cursor и inode-bound capabilities. + [`housekeeping.rs:88`](../../crates/crank-artifacts/src/housekeeping.rs#L88) + +- Redacted типы отделяют управляющий контракт от digest и filesystem path. + [`model.rs:83`](../../crates/crank-artifacts/src/model.rs#L83) + +**Безопасные mutation и recovery** + +- Quarantine повторно проверяет capability и выполняет no-clobber cross-directory rename. + [`housekeeping.rs:229`](../../crates/crank-artifacts/src/housekeeping.rs#L229) + +- Delete идемпотентно удаляет только повторно подтверждённый quarantined inode. + [`housekeeping.rs:276`](../../crates/crank-artifacts/src/housekeeping.rs#L276) + +- Recovery различает already-quarantined state и сохраняет fail-closed поведение. + [`housekeeping.rs:315`](../../crates/crank-artifacts/src/housekeeping.rs#L315) + +- Оба затронутых каталога синхронизируются даже при первой ошибке fsync. + [`housekeeping.rs:567`](../../crates/crank-artifacts/src/housekeeping.rs#L567) + +- Общий FD-helper предоставляет Linux `RENAME_NOREPLACE` между каталогами. + [`store.rs:614`](../../crates/crank-artifacts/src/store.rs#L614) + +**Verification evidence** + +- Pagination test доказывает exact-once выдачу через последующие реальные mutations. + [`reconciliation.rs:56`](../../crates/crank-artifacts/tests/reconciliation.rs#L56) + +- Malformed, symlink, directory и hardlink entries классифицируются без unsafe capability. + [`reconciliation.rs:96`](../../crates/crank-artifacts/tests/reconciliation.rs#L96) + +- Republish collision сохраняет одновременно новый final и старый quarantine inode. + [`reconciliation.rs:211`](../../crates/crank-artifacts/tests/reconciliation.rs#L211) + +- Replacement перед delete подтверждает fail-closed защиту stale capability. + [`reconciliation.rs:245`](../../crates/crank-artifacts/tests/reconciliation.rs#L245) + +- Process-exit suite покрывает rename, оба fsync, unlink и delete fsync. + [`reconciliation.rs:365`](../../crates/crank-artifacts/tests/reconciliation.rs#L365) diff --git a/_bmad-output/implementation-artifacts/spec-2-3-references-schema-composition.md b/_bmad-output/implementation-artifacts/spec-2-3-references-schema-composition.md new file mode 100644 index 0000000..bce654b --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-3-references-schema-composition.md @@ -0,0 +1,8 @@ +--- +status: superseded +canonical_spec: _bmad-output/implementation-artifacts/spec-2-8-references-schema-composition.md +--- + +# Historical story reference + +Story numbering changed on 2026-09-13. Use [spec-2-8-references-schema-composition.md](spec-2-8-references-schema-composition.md). This redirect is not an actionable story. Archived loop runs retain their original IDs; do not resume them against the renumbered sprint. diff --git a/_bmad-output/implementation-artifacts/spec-2-4-artifact-claim-recovery.md b/_bmad-output/implementation-artifacts/spec-2-4-artifact-claim-recovery.md new file mode 100644 index 0000000..8b3a3dd --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-4-artifact-claim-recovery.md @@ -0,0 +1,126 @@ +--- +title: '2.4 — Реализовать artifact claim/recovery coordinator' +type: 'feature' +created: '2026-08-27' +status: 'done' +baseline_revision: '8784964fb2e6017dd5f0c7d6ce7360875ff8efef' +baseline_commit: '8784964fb2e6017dd5f0c7d6ce7360875ff8efef' +review_loop_iteration: 0 +context: + - '_bmad-output/implementation-artifacts/epic-2-context.md' +legacy_aliases: + - '2.1b2b' +--- + + + +## Intent + +**Problem:** Filesystem scanner уже находит и безопасно мутирует orphan candidates, но PostgreSQL не выдаёт fenced claims, не выполняет global reference recheck и не восстанавливает неоднозначные crash windows. Поэтому автоматический cleanup пока нельзя включить без риска удалить вновь привязанный blob либо навсегда потерять работу. + +**Approach:** Добавить V12-compatible claim/recheck/finalize protocol и bounded Admin coordinator: startup recovery обрабатывает quarantine до final sweep, все filesystem вызовы идут через `spawn_blocking`, а после любой mutation cursor отбрасывается и начинается новый bounded cycle. + +## Boundaries & Constraints + +**Always:** claim привязан к store-validated physical identity и непредсказуемому bounded token; global recheck учитывает active relations всех workspace; source attach блокируется при любом незавершённом claim; `Deleted`/`AlreadyAbsent` фиксируются как V12 `unavailable`; после возможной mutation claim не возвращается в idle; worker хранит не более одного cursor и только bounded low-cardinality counters. + +**Ask First:** новая migration или lifecycle сверх V12 `available|unavailable`; раскрытие digest/path через `Debug`, logs, metrics, HTTP или UI; изменение `0700`/same-UID threat model либо artifact layout. + +**Never:** не удалять metadata/source rows; не считать detached relation active reference, но соблюдать grace для неё; не держать cursor после put/quarantine/delete; не выполнять blocking filesystem I/O на async executor; не добавлять upload/parser/routes/UI и не ослаблять inode/root revalidation. + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|---------------|----------------------------|----------------| +| Claim | Old final/quarantine candidate, no active relation | Один fenced winner; missing blob row создаётся из store-minted capability | Active/recent-detached/foreign token дают typed skip/conflict без mutation | +| Attach race | Claim до/после concurrent source creation | Общий blob lock и global recheck сохраняют referenced bytes | Attach во время claim retryable; stale worker не finalize | +| Mutation | Quarantine/delete либо ambiguous fsync | Durable outcome меняет только token-owned DB state | Retryable/uncertain сохраняет claim и запускает bounded recovery | +| Restart | Expired claim, quarantine, already-absent, exhausted page | Startup recovery завершается до final sweep; новый cycle продолжает работу | Unsafe/integrity item классифицируется redacted и не блокирует следующие | + + + +## Code Map + +- `crates/crank-artifacts/src/{housekeeping.rs,model.rs}` — добавить revalidated candidate→`RegisteredArtifact` capability и age check; сохранять redacted candidate/cursor и FD authority. +- `crates/crank-registry/src/model/artifact_source.rs`, `src/postgres/artifact_source.rs:18-308` — typed claim token/outcomes; reuse blob `FOR UPDATE`, global source query и V12 fields; `ensure_blob` не пропускает active claim. +- `crates/crank-registry/src/migrations/artifact_metadata_v12.sql:1-61` — read-only schema contract: `unavailable` означает confirmed physical absence; checksum/guard не менять. +- `apps/admin-api/src/main.rs:142-271,478-510`, `src/reconciliation.rs` — composition и single-cursor scheduler; reuse immediate tick, `MissedTickBehavior::Skip`, redacted events. +- `crates/crank-registry/tests/integration/artifact_sources.rs`, `apps/admin-api/src/reconciliation/tests.rs` — real PostgreSQL/filesystem race, restart, boundedness и FD evidence. + +## Tasks & Acceptance + +**Execution:** +- [x] `crates/crank-artifacts/src/{housekeeping.rs,model.rs,lib.rs}` — mint non-forgeable registration from a revalidated candidate and expose grace eligibility without path access. +- [x] `crates/crank-registry/src/{model/artifact_source.rs,error.rs,lib.rs}`, `src/postgres/artifact_source.rs` — implement claim/replay/steal, global recheck, token-guarded finalize and claim-aware source revival using unchanged V12 schema. +- [x] `apps/admin-api/src/{lib.rs,reconciliation.rs,main.rs}`, `Cargo.toml` — run recovery-before-sweep with fixed safe defaults: immediate/15-minute ticks, 24-hour grace, 5-minute lease, 4096 traversal syscalls and 32 candidates/mutations per tick. +- [x] `crates/crank-registry/tests/integration/**`, `apps/admin-api/src/reconciliation/tests.rs` — cover the I/O matrix, cursor invalidation, one-cursor FD bound and crash/fault seams. + +**Acceptance Criteria:** +- Given concurrent claim/attach/lease-steal attempts, when one worker mutates, then active data is never removed, exactly one token controls DB transitions, and stale tokens cannot finalize. +- Given rename/unlink/fsync/DB ambiguity or process exit, when a later tick starts, then recovery reaches deterministic `unavailable` or safe retry without releasing a possibly mutated claim or starving later entries. +- Given any physical mutation, when coordinator continues, then old cursor is dropped, scanning restarts from `None`, open FDs remain bounded, and total work never exceeds per-tick limits. +- Given full artifact, registry and Admin suites, when verification runs, then reports/logs contain no digest, source, workspace, token or path and all workspace gates pass. + +## Spec Change Log + +## Design Notes + +V12 `unavailable` is the persistent absent state; republishing verified bytes may restore `available` only when no claim exists. A claimed row blocks source creation until finalize/recovery, closing the recheck→filesystem race without holding a PostgreSQL transaction across blocking I/O. The scanner bridge returns the existing `RegisteredArtifact` only after capability revalidation; it does not add a candidate digest/path accessor. + +## Verification + +**Commands:** +- `cargo test -p crank-artifacts --test reconciliation -- --test-threads=1` — filesystem safety/fault matrix passes; default-parallel counter race remains deferred until all 2.1 stories finish. +- `cargo test -p crank-registry --test integration -- --test-threads=1` — claim, cross-workspace recheck, revival and restart matrix passes. +- `cargo test -p admin-api reconciliation -- --test-threads=1` — coordinator bounds, ordering, cursor/FD and recovery pass. +- `cargo fmt --all --check && cargo clippy --workspace --all-targets --all-features -- -D warnings` — formatting/lints pass. +- `just migration-contract-check && just rust-boundaries && just rust-code-health && just verify` — immutable V12 and workspace gates pass. + +## Suggested Review Order + +**Coordinator и production wiring** + +- Единый bounded state machine гарантирует Recovery перед Sweep и сбрасывает stale cursor. + [`reconciliation.rs:386`](../../apps/admin-api/src/reconciliation.rs#L386) + +- Startup запускает immediate tick и периодический 15-минутный цикл. + [`reconciliation.rs:729`](../../apps/admin-api/src/reconciliation.rs#L729) + +- Admin composition открывает защищённое artifact storage после проверки master key. + [`main.rs:234`](../../apps/admin-api/src/main.rs#L234) + +**Fencing и recovery authority** + +- PostgreSQL claim/recheck/finalize сериализует attach races общим blob row lock. + [`artifact_source.rs:31`](../../crates/crank-registry/src/postgres/artifact_source.rs#L31) + +- Expired recovery использует CAS и запрещает resurrection прежнего token. + [`artifact_source.rs:189`](../../crates/crank-registry/src/postgres/artifact_source.rs#L189) + +- DB-clock helpers исключают worker clock skew из lease-решений. + [`reconciliation.rs:1`](../../crates/crank-registry/src/postgres/artifact_source/reconciliation.rs#L1) + +- Opaque 256-bit token и claim-типы закрывают observability leakage. + [`artifact_source.rs:22`](../../crates/crank-registry/src/model/artifact_source.rs#L22) + +**Filesystem capability и redaction** + +- Candidate повторно валидируется до mint существующего `RegisteredArtifact` capability. + [`recovery.rs:103`](../../crates/crank-artifacts/src/recovery.rs#L103) + +- Фиксированные identity-free counters классифицируют unsafe, integrity и retryable outcomes. + [`reconciliation.rs:59`](../../apps/admin-api/src/reconciliation.rs#L59) + +**Verification evidence** + +- Production-backed coordinator test проверяет PostgreSQL, filesystem и cursor reset вместе. + [`tests.rs:459`](../../apps/admin-api/src/reconciliation/tests.rs#L459) + +- Anti-starvation test проводит Absent через prefix из 33 Unsafe claims. + [`tests.rs:597`](../../apps/admin-api/src/reconciliation/tests.rs#L597) + +- Row-lock expiry и concurrent recovery закреплены отдельным integration test. + [`artifact_reconciliation.rs:16`](../../crates/crank-registry/tests/integration/artifact_reconciliation.rs#L16) + +- Filesystem suite отвергает cursor с несовместимым namespace scope. + [`reconciliation.rs:878`](../../crates/crank-artifacts/tests/reconciliation.rs#L878) diff --git a/_bmad-output/implementation-artifacts/spec-2-4-http-contract.md b/_bmad-output/implementation-artifacts/spec-2-4-http-contract.md new file mode 100644 index 0000000..2c167dc --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-4-http-contract.md @@ -0,0 +1,8 @@ +--- +status: superseded +canonical_spec: _bmad-output/implementation-artifacts/spec-2-9-http-contract.md +--- + +# Historical story reference + +Story numbering changed on 2026-09-13. Use [spec-2-9-http-contract.md](spec-2-9-http-contract.md). This redirect is not an actionable story. Archived loop runs retain their original IDs; do not resume them against the renumbered sprint. diff --git a/_bmad-output/implementation-artifacts/spec-2-5-openapi-upload-preview.md b/_bmad-output/implementation-artifacts/spec-2-5-openapi-upload-preview.md new file mode 100644 index 0000000..95c910f --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-5-openapi-upload-preview.md @@ -0,0 +1,73 @@ +--- +title: '2.5 — Ввести bounded multipart upload и verified OpenAPI preview' +type: 'feature' +created: '2026-08-28' +status: 'done' +baseline_commit: 'd2849ea3fef50ff62e08ae537c8eec46d195f040' +review_loop_iteration: 0 +context: + - '_bmad-output/implementation-artifacts/epic-2-context.md' +--- + + + +## Intent + +**Problem:** Production endpoint всё ещё принимает raw OpenAPI внутри JSON, доверяет сохранённому preview JSON при apply и не связывает import job с immutable workspace-scoped source. Это допускает unbounded/непроверенный ingress, TOCTOU и потерю source provenance. + +**Approach:** Заменить production preview contract на один bounded multipart-файл и провести его через `durable put → scoped source metadata → verified read → parser → import job`; apply заново читает и парсит тот же source, а ошибки и expiry компенсируются только lifecycle detach/reconciliation. + +## Boundaries & Constraints + +**Always:** auth/workspace/CSRF и вся multipart-форма валидируются до publish; ровно один `file` `.yaml|.yml|.json`, UTF-8, 1..256 KiB; YAML принимает `application/yaml|x-yaml`, `text/yaml|x-yaml` или `application/octet-stream`, JSON — `application/json|openapi+json` или octet-stream; blocking storage/parser идут вне async executor; source ID/digest хранятся в bounded job envelope; `Accept-Language: ru*` выбирает RU, иначе EN; ошибки содержат canonical Request ID/Trace ID без source. + +**Ask First:** новая migration; изменение artifact root/permissions или reconciliation lifecycle; раскрытие digest, source ID, parser detail либо filename в публичной диагностике/telemetry; изменение create/apply conflict semantics. + +**Never:** UI/E2E/docs из Story 2.6; NormalizedIR/support expansion из 2.7+; external `$ref`; Draft/Operation mutation во время preview; прямое удаление blob; production fallback на JSON `{document}` или построение Draft только из сохранённого preview JSON. + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|---------------|----------------------------|----------------| +| Valid upload | Один YAML/JSON file, ≤256 KiB, ≥1 method | Durable source, verified parse, pending job и bounded preview | 200 с job ID/expiry/preview без raw bytes/digest/source ID | +| Boundary reject | Empty/oversized, malformed/duplicate/unknown part, bad name/MIME/UTF-8 | Ни source metadata, ни job, ни Draft | Stable 4xx/413 RU/EN envelope | +| Parse/failure/cancel | Unsupported/no-methods либо storage/registry/parser/job failure | Нет job/Draft; опубликованный blob остаётся orphan либо relation detach | Safe code; lifecycle/reconciliation owns cleanup | +| Reuse/apply | Job source foreign, detached, missing, corrupt или digest mismatch | Preview JSON не считается authority; Draft не создаётся | Stable not-found/integrity/unavailable outcome | + + + +## Code Map + +- `apps/admin-api/src/{app.rs,routes/imports.rs,dto.rs,error.rs}` — текущий JSON route; добавить Axum multipart, envelope overhead limit и safe localized rejection mapping; reuse request correlation/error envelope. +- `apps/admin-api/src/{service.rs,main.rs,service/imports.rs}` — передать уже открытый `ArtifactStore`; заменить raw parse на put/source/verified-read orchestration и re-verify/re-parse перед apply. +- `crates/crank-artifacts/src/{store.rs,model.rs}` — read-only authority: `put_registered`, `MAX_ARTIFACT_BYTES`, verified bounded read; не добавлять path/digest accessors. +- `crates/crank-registry/src/{postgres/artifact_source.rs,postgres/import_job.rs,model.rs}` — reuse scoped create/read/detach; сохранить source envelope в JSONB и атомарно detach при expiry без schema change. +- `apps/admin-api/tests/integration/{openapi_import.rs,openapi_source.rs,mod.rs,common.rs}` — real router/PostgreSQL/filesystem matrix, scope/integrity/restart/cancel и anti-leak evidence. + +## Tasks & Acceptance + +**Execution:** +- [x] `Cargo.toml`, `apps/admin-api/Cargo.toml`, `src/{app.rs,routes/imports.rs,dto.rs,error.rs}` — включить multipart и реализовать streaming one-file validation с отдельными file/envelope limits и стабильной локализацией. +- [x] `apps/admin-api/src/{service.rs,main.rs,service/imports.rs}` — разделить один production `ArtifactStore` между ingress/reconciliation; реализовать compensating detach guard, verified preview и source-authoritative apply. +- [x] `crates/crank-registry/src/{postgres/import_job.rs,model.rs}` — закрепить bounded source envelope и expiry cleanup relation без migration/raw source. +- [x] `apps/admin-api/tests/integration/**` — покрыть всю I/O matrix через реальный multipart router и доказать отсутствие Draft/job/telemetry leakage на отказах. + +**Acceptance Criteria:** +- Given valid или hostile multipart input, when preview проходит outer HTTP stack, then auth, exact 256 KiB limit, shape/MIME/UTF-8, safe RU/EN errors и Request ID/Trace ID доказаны без raw source в response/logs/traces/metrics. +- Given successful preview, when job создаётся или позднее применяется, then parser получает только digest/size-verified bytes из workspace-scoped source, а absent/changed/foreign source блокирует Draft независимо от stored preview JSON. +- Given failure, cancellation, disconnect, expiry или restart, when cleanup/retry выполняется, then нет частичных job/Draft entities, source становится безопасно detached либо blob остаётся reconciliation-owned orphan, без прямого unlink. + +## Spec Change Log + +## Design Notes + +Import job хранит `{source:{source_id,digest},preview}` в существующем JSONB. Digest служит expected identity, но не возвращается клиенту. Созданная relation вооружает drop/expiry compensation; successful pending job сохраняет active relation до apply/expiry. Apply повторно выполняет scoped verified read и deterministic parse, а не десериализует preview как authority. + +## Verification + +**Commands:** +- `cargo test -p admin-api --test integration openapi_source -- --test-threads=1` — outer multipart, auth/scope, limits, localization, cancellation/integrity и anti-leak matrix проходит. +- `cargo test -p admin-api --test integration openapi_import -- --test-threads=1` — verified-source apply/replay/no-Draft scenarios проходят. +- `cargo test -p crank-registry --test integration -- --test-threads=1` — source/job lifecycle и expiry compensation проходят. +- `cargo fmt --all --check && cargo clippy --workspace --all-targets --all-features -- -D warnings` — форматирование и lint чисты. +- `just rust-boundaries && just rust-code-health && just verify` — workspace contracts и полный regression gate проходят. diff --git a/_bmad-output/implementation-artifacts/spec-2-6-openapi-upload-ui-evidence.md b/_bmad-output/implementation-artifacts/spec-2-6-openapi-upload-ui-evidence.md new file mode 100644 index 0000000..cc66e19 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-6-openapi-upload-ui-evidence.md @@ -0,0 +1,132 @@ +--- +title: '2.6 — Завершить OpenAPI upload UX и release evidence' +type: 'feature' +created: '2026-08-28' +status: 'done' +baseline_commit: 'd2849ea3fef50ff62e08ae537c8eec46d195f040' +review_loop_iteration: 0 +context: + - '_bmad-output/implementation-artifacts/epic-2-context.md' + - '_bmad-output/implementation-artifacts/spec-2-5-openapi-upload-preview.md' +--- + + + +## Intent + +**Problem:** OpenAPI modal по-прежнему превращает файл в текст и отправляет legacy JSON `{document}`, поэтому после Story 2.5 production upload из UI не работает. Асинхронный flow не защищён от replacement/close/workspace races, почти полностью hardcoded на RU и не даёт воспроизводимого release evidence. + +**Approach:** Сделать выбранный `File` единственным authoritative ingress, отправлять его multipart через общий authenticated API client и оформить preview/apply как отменяемую revision-guarded state machine с безопасной RU/EN диагностикой, accessibility и real-stack Playwright evidence. + +## Boundaries & Constraints + +**Always:** Один `.yaml|.yml|.json` файл размером 1..256 KiB; browser сам формирует multipart boundary; backend остаётся security authority. Replacement, reset, close, workspace/language change и navigation отменяют request и инвалидируют поздний response. UI показывает только bounded filename/size, actionable localized message и canonical Request ID/Trace ID; File/raw source, digest, source ID и path не попадают в DOM diagnostics, logs или evidence. Apply допускает только один in-flight request и сохраняет backend idempotency authority. + +**Ask First:** Изменение backend contract 2.5; новый production dependency; изменение capability-baseline schema/accepted evidence; сохранение preview после закрытия modal или смены workspace. + +**Never:** Legacy JSON preview или textarea/paste fallback; client-side parser/security authority; NormalizedIR/support matrix/external `$ref`/partial mode/new conflict semantics из 2.7+; auto-publish; raw Playwright trace/video/source как release evidence. + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|---------------|----------------------------|----------------| +| Upload/apply | Valid YAML/JSON File | Multipart preview, selectable methods, single create и Draft result | Loading/status announced; repeat apply reuses canonical job semantics | +| Local reject | No file, bad extension/type, empty или >256 KiB | No request/job/preview; control remains retryable | Localized bounded recovery without invented IDs | +| Server/network reject | Parse/413/4xx/5xx или ambiguous network failure | Previous authority is not silently replaced | Safe RU/EN message; display Request/Trace IDs only when received; explicit retry | +| Cancel/stale | A→B replacement, reset/close/workspace/language/navigation during preview/apply | A aborted or ignored; B/current context alone may render or mutate UI | `cancelled` is not shown as backend failure; stale job/selection/result cleared | +| Accessibility | Keyboard, screen reader, reduced motion | Focus enters/restores, Escape closes, status/error announced, meaning not color-only | Error focuses recovery/status without trapping the user | + + + +## Code Map + +- `apps/ui/js/api.js:218-245,412-419` — reuse common credentials/CSRF/error correlation; multipart body must bypass JSON serialization and accept `signal` without setting `Content-Type`. +- `apps/ui/js/openapi-import.js:1-548` — replace raw textarea flow; add File/revision/controllers/state transitions, current-context guards, safe diagnostics and lifecycle listeners. Reuse render/filter/apply result code. +- `apps/ui/js/{onboarding.js,catalog.js,secrets.js}` — read-only examples for AbortController, generation and workspace identity guards. +- `apps/ui/index.html:380-451`, `apps/ui/css/openapi-import.css` — file-only modal, cancel/retry/status semantics, focus and reduced-motion behavior. +- `apps/ui/js/i18n.js` — add complete EN/RU OpenAPI keys; no new hardcoded user-facing copy. +- `apps/ui/tests/e2e/operations.spec.js` — convert happy path to `setInputFiles`; add deterministic multipart, validation, replacement/cancel/stale, correlation, RU/EN, keyboard and double-create evidence against real Admin API where applicable. +- `apps/ui/{playwright.config.js,package.json}`, `.gitea/workflows/{ci.yml,release.yml}`, `scripts/collect-capability-baseline.py` — reuse pinned Playwright and sanitized count-only collector; produce deterministic JSON evidence without publishing raw source artifacts. +- `docs/openapi-import.md`, `docs/{admin-api.md,production-checklist.md}` — document multipart limit, state/recovery contract, artifact lifecycle/backup coordination and redacted diagnostics. +- `apps/admin-api/src/{app.rs,routes/imports.rs,service/imports.rs}` — read-only 2.5 production authority unless a demonstrated UI boundary defect requires Ask First. + +## Tasks & Acceptance + +**Execution:** +- [x] `apps/ui/js/{api.js,openapi-import.js,i18n.js}` — implement file-only multipart transport, localized cancellable state machine, correlation recovery and stale/apply guards. +- [x] `apps/ui/{index.html,css/openapi-import.css}` — provide accessible file/cancel/retry/status UI with focus restoration and reduced-motion support. +- [x] `apps/ui/tests/e2e/operations.spec.js` — cover the complete matrix with real upload→preview→apply plus deterministic intercepted race/error scenarios that assert multipart shape and no canary leakage. +- [x] `apps/ui/{playwright.config.js,package.json}`, `.gitea/workflows/{ci.yml,release.yml}`, `scripts/collect-capability-baseline.py` — emit and validate sanitized Playwright release evidence for the OpenAPI flow. +- [x] `docs/{openapi-import.md,admin-api.md,production-checklist.md}` — align operator/user documentation with the shipped contract and recovery model. + +**Acceptance Criteria:** +- Given current File/workspace/language revision, when any async preview/apply settles, then only that exact revision may change job, selection, status or result and no duplicate Draft mutation is initiated. +- Given RU or EN UI and any local/backend failure, when recovery is rendered, then it is keyboard/screen-reader usable, contains canonical correlation only when available and exposes no raw source or internal artifact identity. +- Given CI/release verification, when OpenAPI evidence is collected, then the real multipart flow passes and the tracked artifact contains only bounded schema-valid metadata/counts tied to the source revision. + +## Spec Change Log + +## Design Notes + +`File` остаётся в памяти только в текущей modal revision. Каждое destructive context change сначала увеличивает revision и aborts controllers, затем очищает job/preview/result. `AbortError` переводит текущий flow в `cancelled`; ответ старой revision не делает ничего. Local validation улучшает UX, но не заменяет identical backend checks. + +## Verification + +**Commands:** +- `cd apps/ui && npm run build` — production bundle собирается без legacy textarea path. +- `cd apps/ui && npx playwright test tests/e2e/operations.spec.js --workers=1` — multipart happy path и UI edge matrix проходят. +- `just ui-e2e` — полный real-stack UI regression проходит. +- `python3 scripts/validate-capability-baseline.py docs/capability-baseline/manifest.json` — evidence остаётся schema-valid и redacted. +- `cargo fmt --all --check && cargo clippy --workspace --all-targets --all-features -- -D warnings && just rust-boundaries && just rust-code-health` — workspace gates чисты. + +## Suggested Review Order + +**Production upload boundary** + +- Multipart route задаёт единственный file-only ingress и bounded validation. + [`imports.rs:28`](../../apps/admin-api/src/routes/imports.rs#L28) + +- Service связывает immutable artifact source, preview job и verified apply. + [`imports.rs:35`](../../apps/admin-api/src/service/imports.rs#L35) + +- Registry cleanup завершает lifecycle истёкших jobs и dangling sources. + [`import_job.rs:146`](../../crates/crank-registry/src/postgres/import_job.rs#L146) + +**UI state machine and safety** + +- Modal state machine централизует revision, abort, stale-response и safe diagnostics. + [`openapi-import.js:442`](../../apps/ui/js/openapi-import.js#L442) + +- Browser формирует multipart boundary и передаёт cancellation signal. + [`api.js:412`](../../apps/ui/js/api.js#L412) + +- Apply guard допускает только одну текущую Draft-мутацию. + [`openapi-import.js:674`](../../apps/ui/js/openapi-import.js#L674) + +- Context listeners инвалидируют language, workspace, cross-tab и navigation races. + [`openapi-import.js:843`](../../apps/ui/js/openapi-import.js#L843) + +- Accessible modal предоставляет file activation, live status и focus contract. + [`index.html:380`](../../apps/ui/index.html#L380) + +**Release evidence** + +- Collector fail-closed связывает evidence с обязательными OpenAPI test titles. + [`collect-capability-baseline.py:82`](../../scripts/collect-capability-baseline.py#L82) + +- Candidate validator отдельно требует schema-valid accepted evidence. + [`validate-capability-run.py:125`](../../scripts/validate-capability-run.py#L125) + +- Release сохраняет sanitized evidence в dist и включает его checksum. + [`release.yml:129`](../../.gitea/workflows/release.yml#L129) + +**Verification and operations** + +- Real-stack suite покрывает multipart happy path и полный stale/error matrix. + [`operations.spec.js:26`](../../apps/ui/tests/e2e/operations.spec.js#L26) + +- User guide фиксирует recovery, retention и redacted diagnostics. + [`openapi-import.md:19`](../../docs/openapi-import.md#L19) + +- Production checklist задаёт допустимый release evidence contract. + [`production-checklist.md:53`](../../docs/production-checklist.md#L53) diff --git a/_bmad-output/implementation-artifacts/spec-2-7-openapi-normalizedir.md b/_bmad-output/implementation-artifacts/spec-2-7-openapi-normalizedir.md new file mode 100644 index 0000000..5b0527f --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-7-openapi-normalizedir.md @@ -0,0 +1,124 @@ +--- +title: '2.7 — Преобразовать OpenAPI в детерминированный NormalizedIR' +type: 'feature' +created: '2026-08-29' +status: 'done' +baseline_commit: 'bc03c3338768559eaf97f614fceaf9a8c32c3c67' +review_loop_iteration: 0 +context: + - '_bmad-output/implementation-artifacts/epic-2-context.md' +--- + + + +## Intent + +**Problem:** `crank-import` сразу проецирует source в Draft-кандидаты, поэтому часть OpenAPI semantics теряется молча, а findings и порядок не имеют устойчивого source contract. + +**Approach:** Ввести между parsing и preview pure typed `NormalizedIR` с versioned config, stable IDs, coverage ledger и canonical serialization; preview строить adapter-слоем поверх IR. + +## Boundaries & Constraints + +**Always:** Формат определяется по содержимому: JSON-first/YAML fallback; версии — только OpenAPI `3.0.x`, `3.1.x`, Swagger `2.0`. Location — RFC 6901 pointer без excerpt; ID выводится из version/method/pointer. Порядок фиксирован. Limits: 256 KiB, depth 64, 50 000 nodes, collection 10 000, aliases 128, scalar 256 KiB. Каждый construct получает typed mapping либо finding. Parser не имеет I/O/domain dependencies. Новые jobs сохраняют normalizer/projection version; legacy jobs сохраняют v1 replay до expiry. + +**Ask First:** Изменение публичных HTTP-полей 2.1, удаление legacy replay до истечения job TTL, новая production dependency либо перенос semantic mapping из Stories 2.8–2.5. + +**Never:** Reference I/O; Draft/ImportPlan/domain mutation; silent drop construct; source digest/bytes/parser internals в HTTP; зависимость output от времени, hash-map order, workspace/request IDs. + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|---------------|---------------------------|----------------| +| Supported source | Три версии, YAML/JSON | Typed IR: metadata, servers/base path, paths, methods, IDs, tags, schema/ref placeholders, ledger | Ordered findings для неотображаемой semantics | +| Identity ambiguity | Missing/duplicate `operationId`, reordered maps | Stable `METHOD path` key и canonical suffix по method/path/pointer | Finding связан с construct ID/location | +| Partial structural defect | Один malformed endpoint среди валидных | Валидные operations остаются в IR | Blocker finding дефектного pointer; Apply остаётся запрещён последующим policy layer | +| Reference | Local/external/cyclic `$ref` | Typed unresolved reference сохраняет URI/pointer и location, без I/O | Resolution не симулируется и не теряется | +| Invalid/hostile source | Unsupported/root/no methods/limit excess | Нет пустого success, panic или runaway work | Bounded blocker без raw parser error/source | +| Replay/concurrency | Те же bytes+digest+config многократно/параллельно | Canonical IR и findings byte-for-byte равны | Version mismatch fail-closed до mutation | + + + +## Code Map + +- `crates/crank-import/src/rest/model.rs:7-123` — добавить `NormalizedIr`, construct/location, typed spec/schema/ref/coverage; `ImportPreview` оставить redacted projection. +- `crates/crank-import/src/rest/normalize.rs:21-110` — разделить bounded decode, strict version dispatch, canonical normalization и preview projection; текущий eager `resolve_local_ref` оставить только legacy-v1 path. +- `crates/crank-import/src/rest/{openapi3.rs,swagger2.rs}` — нормализовать source constructs независимо по endpoint; фиксировать unsupported/invalid semantics findings вместо silent skip. +- `crates/crank-import/src/rest/{naming.rs,payload.rs,recommendations.rs,schema.rs}` — reuse naming/Draft projection; semantic resolution оставить 2.8–2.5. +- `crates/crank-import/tests/{unit.rs,fixtures/**}` — заменить узкие inline examples versioned fixture/golden matrix и hostile/determinism regressions. +- `apps/admin-api/src/service/imports.rs:39-522` — передавать digest/config, сохранять versions/IR fingerprint, одинаково reparse preview/apply без digest в DTO. +- `apps/admin-api/tests/integration/{openapi_import.rs,openapi_source.rs}` — доказать redaction, parser-version replay, drift fail-closed и отсутствие Draft при blocker/limit errors. +- `scripts/check-rust-boundaries.py`, `docs/testing-strategy.md` — read-only conventions; `crank-import` остаётся pure crate без registry/artifact/app dependencies. + +## Tasks & Acceptance + +**Execution:** +- [x] `crates/crank-import/src/rest/{model.rs,normalize.rs,openapi3.rs,swagger2.rs,mod.rs}` — bounded typed normalization, stable identity/location, coverage validation и canonical output трёх версий. +- [x] `crates/crank-import/src/rest/{naming.rs,payload.rs,recommendations.rs,schema.rs}` — построить backward-compatible redacted preview adapter поверх IR и сохранить будущую semantic работу typed placeholders/findings. +- [x] `crates/crank-import/tests/{unit.rs,fixtures/**}` — добавить YAML/JSON golden fixtures, ordering/duplicate/no-method/partial/ref/limit tests, deterministic generated-property cases и checked-in fuzz regressions. +- [x] `apps/admin-api/src/service/imports.rs`, `apps/admin-api/tests/integration/{openapi_import.rs,openapi_source.rs}` — version job parser contract, передать artifact digest без HTTP leakage и покрыть rolling replay/reparse/integrity behavior. + +**Acceptance Criteria:** +- Given любой supported verified source, when normalization завершается, then каждый распознанный construct присутствует в canonical typed IR либо связан с explicit ordered finding и coverage validator отклоняет gap. +- Given одинаковые bytes, digest и config, when parser запускается повторно или конкурентно, then serialized IR/findings и public preview совпадают byte-for-byte. +- Given legacy pending job или новая versioned job, when Apply reparses source после rollout, then используется соответствующая projection version либо запрос fail-closed до Draft mutation без ложного integrity verdict. +- Given hostile/частично повреждённый документ, when validation срабатывает, then работа bounded, валидные endpoints сохранены, blocker redacted, panic/mutation отсутствуют. + +## Spec Change Log + +## Design Notes + +`NormalizedIR` хранит source identity только для внутренней воспроизводимости; HTTP projection исключает digest. Canonical ordering: path lexical → fixed HTTP method rank → source pointer; findings: severity rank → construct ID → code. Schema composition и references представлены typed source nodes, но разрешаются только следующими Story. Legacy-v1 adapter изолирован и удаляется отдельным решением после максимального TTL. + +## Verification + +**Commands:** +- `cargo test -p crank-import --all-targets` — PASS, 45/45: fixture/property/fuzz-regression matrix, canonical ordering, limits, coverage и legacy replay. +- `cargo test -p admin-api --test integration -- --test-threads=1` — PASS, 70/70: rolling replay, redaction, parser-contract drift и no-Draft guarantees. +- `cargo fmt --all -- --check` — PASS. +- `cargo clippy -p crank-import -p admin-api --all-targets -- -D warnings` — PASS. +- `just rust-boundaries` — PASS: crate/module/config/migration/metrics/execution boundaries сохранены. +- `just rust-code-health` — Story 2.7 не добавляет превышений и все её Rust-модули меньше 1000 строк; общий gate остаётся красным только на двух pre-existing Story 2.1 baseline-файлах `crates/crank-artifacts/src/housekeeping.rs` (1119) и `crates/crank-artifacts/tests/artifact_store.rs` (1103), зафиксированных в deferred-work ledger. +- `git diff --check` — PASS. + +## Suggested Review Order + +**Контракт NormalizedIR** + +- Главная точка входа связывает bounded decode, canonicalization и строгую валидацию. + [`normalize.rs:82`](../../crates/crank-import/src/rest/normalize.rs#L82) + +- Versioned типы закрепляют identity, locations, schemas, references и coverage ledger. + [`model.rs:270`](../../crates/crank-import/src/rest/model.rs#L270) + +- Coverage validator доказывает отсутствие молча потерянных source constructs. + [`normalize_coverage.rs:16`](../../crates/crank-import/src/rest/normalize_coverage.rs#L16) + +**Парсинг и совместимость** + +- OpenAPI 3 parser сохраняет валидные siblings и локализует malformed semantics. + [`openapi3.rs:17`](../../crates/crank-import/src/rest/openapi3.rs#L17) + +- Swagger 2 parser реализует тот же deterministic contract без semantic resolution. + [`swagger2.rs:17`](../../crates/crank-import/src/rest/swagger2.rs#L17) + +- Изолированный preview adapter сохраняет публичный DTO и legacy-v1 replay. + [`normalize.rs:118`](../../crates/crank-import/src/rest/normalize.rs#L118) + +**Admin apply boundary** + +- Preview сохраняет parser versions и fingerprint только во внутреннем job payload. + [`imports.rs:473`](../../apps/admin-api/src/service/imports.rs#L473) + +- Apply fail-closed сверяет preview, IR fingerprint и parser contract до mutation. + [`imports.rs:555`](../../apps/admin-api/src/service/imports.rs#L555) + +**Доказательства** + +- Recursive pointer test проверяет exact mapping каждого source-tree construct. + [`coverage.rs:132`](../../crates/crank-import/tests/coverage.rs#L132) + +- Version/syntax/concurrency matrix подтверждает byte-for-byte детерминизм IR. + [`unit.rs:426`](../../crates/crank-import/tests/unit.rs#L426) + +- Integration regression запрещает Draft mutation при operation-level blocker. + [`openapi_import.rs:510`](../../apps/admin-api/tests/integration/openapi_import.rs#L510) diff --git a/_bmad-output/implementation-artifacts/spec-2-8-references-schema-composition.md b/_bmad-output/implementation-artifacts/spec-2-8-references-schema-composition.md new file mode 100644 index 0000000..f943dff --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-8-references-schema-composition.md @@ -0,0 +1,148 @@ +--- +title: '2.8 — Безопасно разрешать references и schema composition' +type: 'feature' +created: '2026-08-29' +status: 'done' +baseline_commit: '6c2a3712d8bd2f96216b973c406d2488cea38edc' +review_loop_iteration: 0 +context: + - '_bmad-output/implementation-artifacts/epic-2-context.md' +--- + + + +## Intent + +**Problem:** NormalizedIR сохраняет `$ref` и composition как placeholders, поэтому даже локальные ссылки блокируют Apply, а preview упрощает composition до первой ветки и теряет семантику. + +**Approach:** Добавить bounded graph resolver: чистый `crank-import` разрешает local и переданные immutable external snapshots, а Admin API отдельно и до normalization получает allowlisted snapshots через общий SSRF-safe outbound boundary. Resolved IR сохраняет provenance, recursion, alternatives и точные findings; Apply использует только закреплённые digests без повторного network fetch. + +## Boundaries & Constraints + +**Always:** RFC 6901 escaping и OAS 3.0/3.1 sibling semantics version-specific; external fetch default-off и разрешён только отдельными operator URL-prefix rules поверх deny-before-allow actual-address policy. HTTP(S) без userinfo, proxy и redirects; hop/depth/count/document/expanded-node limits обязательны. Все external bytes становятся workspace-scoped immutable artifacts до preview; graph и findings canonical, redacted и детерминированы. Compatible `allOf` объединяется с provenance, recursion остаётся graph edge, `oneOf`/`anyOf`/discriminator сохраняются typed либо дают blocker affected candidate. + +**Ask First:** Новая внешняя dependency, изменение публичного import HTTP DTO, ослабление SSRF/default-deny, изменение `crank-schema` wire contract либо отказ от replay существующих legacy-v1 jobs. + +**Never:** Network I/O из `crank-import` или во время Apply/registry transaction; повторный fetch при Apply; credential из URL/OpenAPI; unbounded recursive expansion; last-write-wins при `allOf`; first-branch collapse в v2+; global cross-workspace cache; raw URL/content/digest/parser error в публичных errors, logs, traces или metrics. + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|---------------|---------------------------|----------------| +| Local reference | Schema/object ref с escaped pointer | Target разрешён относительно primary snapshot; source/target provenance сохранён | Missing/invalid/type mismatch — точный blocker без panic | +| External default | HTTP(S) ref без import allowlist | Ни DNS, ни request не выполняются | `external_reference_disabled` с безопасной location | +| External allowed | Canonical URL проходит prefix и outbound policy | Chain загружена bounded, сохранена как artifacts и входит в dependency digest set | Redirect/private IP/forbidden origin/limit — blocker, все созданные snapshots detached | +| Replay/TOCTOU | Remote изменился после preview | Apply проверяет и использует прежние snapshot digests | Missing/changed snapshot — fail-closed до Draft mutation | +| Recursion | Self/mutual cycle в schema graph | Typed edge указывает на stable node, без дублирования | Graph limit excess — blocker affected candidates | +| Composition | `allOf`/`oneOf`/`anyOf`/discriminator | Compatible merge либо lossless typed alternatives с provenance | Conflict/unsupported projection — explicit blocker, siblings остаются | + + + +## Code Map + +- `crates/crank-import/src/rest/{model.rs,normalize.rs,normalize_schema.rs,normalize_coverage.rs}` — расширить versioned IR графом, snapshot identity, discriminator/constraints, resolver limits и exact coverage; сохранить crate pure. +- `crates/crank-import/src/rest/{openapi3.rs,swagger2.rs,schema.rs,payload.rs}` — разрешить object/schema refs до projection; убрать modern first-branch loss, legacy-v1 оставить изолированным. +- `crates/crank-adapter-rest/src/client.rs` — переиспользовать policy DNS resolver/no-proxy/no-redirect в отдельном bounded GET boundary, не меняя REST execution semantics. +- `crates/crank-config/src/{process.rs,schema.rs,validation.rs}` — добавить отдельный default-off import external-reference contract: URL prefixes и graph/fetch limits; провести generated config contract. +- `apps/admin-api/src/service/imports.rs` — materialize/dedupe dependency snapshots до normalization, одинаково передать verified bundle в preview/apply и redacted cleanup paths. +- `crates/crank-registry/src/{model,postgres}/`, `crates/crank-registry/src/migrations/` — workspace-scoped import-job dependency set; атомарно verify/detach все digests при Apply/expiry. +- `crates/crank-import/tests/**`, `crates/crank-adapter-rest/tests/integration/**`, `apps/admin-api/tests/integration/openapi_{import,source}.rs` — reuse determinism/redaction/no-mutation suites; добавить graph, SSRF, TOCTOU и composition fixtures. + +## Tasks & Acceptance + +**Execution:** +- [x] `crank-import` resolver/model/projection — построить canonical bounded resolved graph для local и supplied snapshots, composition/provenance и operation-scoped findings без I/O. +- [x] `crank-adapter-rest`, `crank-config` — реализовать отдельный operator-controlled external-reference fetch contract на существующей actual-address security policy. +- [x] `crank-registry`, `apps/admin-api` — закрепить полный dependency snapshot set за job и reparse/apply только из verified artifacts с корректным lifecycle cleanup. +- [x] Tests/fixtures — покрыть OAS 3.0/3.1/Swagger2, pointer escaping/type mismatch, default deny, redirects/DNS/private IP/relative chains, TOCTOU, cycles/limits, composition conflicts/discriminators, determinism, redaction и legacy replay. + +**Acceptance Criteria:** +- Given один повреждённый dependency graph, when preview завершается, then только зависимые candidates получают blocker, независимые остаются видимыми, а полный Apply не создаёт Draft. +- Given одинаковые primary/external bytes, digests и config, when resolution выполняется повторно или конкурентно, then resolved IR, dependency set, preview и ordered findings совпадают byte-for-byte. +- Given preview либо любой failure/expiry/apply path, when lifecycle завершается, then все dependency artifacts остаются workspace-isolated и либо атомарно referenced, либо detached без orphan leak. + +## Spec Change Log + +## Design Notes + +External I/O — orchestration concern Admin API; resolver принимает immutable `{canonical_origin, digest, bytes}` inputs. URL используется только при сборе цепочки, а resolved graph адресует external nodes snapshot digest + RFC 6901 pointer. Новая parser/projection семантика получает новые version identifiers; существующий legacy-v1 replay не меняется. + +## Verification + +**Результат проверки матрицы:** +- Local reference — RFC 6901 escaping, object/schema refs, missing pointer и type mismatch проверены в `reference_resolution`; создание Draft после успешного local resolution проверено интеграционно в Admin API. +- External default/allowed — отсутствие request при default-off, URL-prefix boundary, actual-address policy, redirect/userinfo rejection и bounded response проверены в `external_reference_fetcher`; relative chain и deterministic dependency ordering проверены в `reference_resolution`. +- Replay/TOCTOU — Admin API получает snapshot ровно один раз, Apply читает artifact без network fetch; missing/detached dependency завершает Apply до Draft mutation. +- Recursion — self-cycle остаётся stable recursive edge; depth и expanded-node limits дают blocker без unbounded expansion. +- Composition — compatible/conflicting `allOf`, обе ветви `oneOf`/`anyOf`, discriminator, OAS 3.0/3.1 sibling semantics и invalid composition покрыты и прошли. + +**Фактические результаты:** +- `crank-import`: 64 теста прошли; review-regressions дополнительно покрывают RFC 3986 dot-segments/absolute paths, percent-decoding, literal payload exclusions, OAS 3.1 external siblings, compatible constraint intersections и parameter override semantics. +- `crank-adapter-rest`: 23 теста прошли, включая subprocess proxy regression. +- `crank-registry`: 82 теста прошли, 1 production-size million-row test штатно ignored. +- `admin-api`: 76 интеграционных тестов прошли; среди них selected-only blocker isolation, full-selection atomic failure, relative two-snapshot chain без refetch, total-chain timeout cleanup, failed dependency lifecycle, telemetry redaction и `normalized-ir-v2` TTL replay. +- `config-contract-check`, `cargo fmt --check`, workspace `clippy -D warnings`, `rust-boundaries` и `git diff --check` прошли. +- `rust-code-health` сообщает только о двух известных baseline-файлах Story 2.1 (`crank-artifacts/src/housekeeping.rs`, `crank-artifacts/tests/artifact_store.rs`); все изменённые Story 2.8 Rust-файлы меньше 1000 строк. + +**Commands:** +- `cargo test -p crank-import --all-targets` — graph/composition/version matrix зелёная. +- `cargo test -p crank-adapter-rest --all-targets` — SSRF, redirect, DNS и bounded-fetch regressions зелёные. +- `cargo test -p crank-registry --test integration -- --test-threads=1` — dependency ownership/lifecycle/transaction guarantees зелёные. +- `cargo test -p admin-api --test integration -- --test-threads=1` — snapshot replay, TOCTOU, redaction и no-Draft guarantees зелёные. +- `just config-contract-check && cargo fmt --all -- --check && cargo clippy --workspace --all-targets --all-features -- -D warnings` — contracts и lint чисты. +- `just rust-boundaries && just rust-code-health` — dependency direction и module limits сохранены. + +## Suggested Review Order + +**Оркестрация preview и Apply** + +- Главный поток закрепляет snapshots до preview и проверяет их перед Apply. + [`imports.rs:47`](../../apps/admin-api/src/service/imports.rs#L47) + +- Ошибки replay атомарно завершают job и сохраняют completed-race semantics. + [`external_references.rs:76`](../../apps/admin-api/src/service/imports/external_references.rs#L76) + +- Внешняя цепочка материализуется в общем deadline с cancellation cleanup. + [`external_references.rs:119`](../../apps/admin-api/src/service/imports/external_references.rs#L119) + +**Чистый resolver и schema semantics** + +- Pure resolver строит deterministic bounded graph только из verified snapshots. + [`reference.rs:100`](../../crates/crank-import/src/rest/reference.rs#L100) + +- URI resolution объединяет RFC 3986 canonicalization и RFC 6901 fragment lookup. + [`reference.rs:427`](../../crates/crank-import/src/rest/reference.rs#L427) + +- `allOf` объединяется пересечением совместимых ограничений без last-write-wins. + [`reference.rs:460`](../../crates/crank-import/src/rest/reference.rs#L460) + +- Versioned IR contract отделяет modern semantics от legacy replay. + [`model.rs:12`](../../crates/crank-import/src/rest/model.rs#L12) + +**Security и lifecycle boundaries** + +- Fetch boundary применяет prefix allowlist поверх actual-address SSRF policy. + [`client.rs:229`](../../crates/crank-adapter-rest/src/client.rs#L229) + +- Failed jobs и dependency sources завершаются под одной database transaction. + [`import_job.rs:82`](../../crates/crank-registry/src/postgres/import_job.rs#L82) + +- Apply блокирует missing или изменённые artifacts до Draft mutation. + [`import_job.rs:301`](../../crates/crank-registry/src/postgres/import_job.rs#L301) + +**Конфигурация и доказательства** + +- Builder сохраняет одинаковую policy независимо от порядка настройки. + [`service.rs:285`](../../apps/admin-api/src/service.rs#L285) + +- Generated contract фиксирует default-off и единые graph/fetch limits. + [`schema.rs:81`](../../crates/crank-config/src/schema.rs#L81) + +- End-to-end chain доказывает два fetch, два snapshots и Apply без refetch. + [`external_references.rs:11`](../../apps/admin-api/tests/integration/openapi_import/external_references.rs#L11) + +- Resolver regressions покрывают relative paths, fragments и canonical authorities. + [`reference_resolution.rs:522`](../../crates/crank-import/tests/reference_resolution.rs#L522) + +- Selection regression доказывает локальные blockers и атомарный full failure. + [`openapi_import.rs:560`](../../apps/admin-api/tests/integration/openapi_import.rs#L560) diff --git a/_bmad-output/implementation-artifacts/spec-2-9-http-contract.md b/_bmad-output/implementation-artifacts/spec-2-9-http-contract.md new file mode 100644 index 0000000..60b776f --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-9-http-contract.md @@ -0,0 +1,272 @@ +--- +title: '2.9 — Сохранить полный поддерживаемый HTTP contract' +type: 'feature' +created: '2026-09-05' +status: done +baseline_revision: 083974c27f3a21a15807dd248bb6bc4fe04a5cd8 +baseline_commit: 083974c27f3a21a15807dd248bb6bc4fe04a5cd8 +review_loop_iteration: 1 +followup_review_recommended: false +context: + - '_bmad-output/project-context.md' + - '_bmad-output/implementation-artifacts/epic-2-context.md' + - '_bmad-output/implementation-artifacts/spec-2-8-references-schema-composition.md' +warnings: [oversized] +deferred: [B8, E8] +--- + + + +## Intent + +**Problem:** Текущие candidates теряют HTTP semantics: поддержаны пять methods, три parameter locations, один JSON body и один success schema. Созданный Tool не воспроизводит полный контракт поддерживаемого endpoint. + +**Approach:** Сохранить HTTP semantics в versioned typed IR и Operation, провести их через deterministic mapping и REST execution; unsupported constructs отражать точными findings. Источник целевого поведения — Story 2.9 / FR-8; устаревшее описание пяти методов в документации не ограничивает эту историю. + +## Boundaries & Constraints + +**Always:** Поддерживать OAS 3.0/3.1 и Swagger 2.0; точные source locations и coverage; blockers запрещают actionable Draft; сохранить immutable snapshot replay, isolation, OutboundPolicy и legacy-v1 behavior. Изменение persisted contracts сопровождать compatibility/roundtrip tests и обновлением документации. `sprint-status.yaml` принадлежит оркестратору: не записывать и не откатывать его. + +**Block If:** Требуемое публичное поведение не определено исходным intent и существующими контрактами; нельзя выбрать между наблюдаемо различающимися вариантами без продуктового решения. + +**Never:** Silent loss, first-response/first-branch collapse, credential-bearing URL/headers, implicit XML fallback, network I/O из importer, изменение зависимостей/toolchain попутно или отказ от исторических jobs. + + + +## Уточнение HTTP input contract — решение пользователя 2026-09-05 + +Пользователь выбрал **1A + 2A**: inline base64 для multipart binary/file и один Operation candidate / Tool на endpoint с явным выбором request media type. Эти правила дополняют исходные AC и снимают два вопроса из исторического Auto Run Result. + +### Multipart binary/file + +- Значение каждого binary/file field — JSON object с обязательным строковым `data_base64` и необязательными строковыми `filename` и `content_type`; иных полей у этого объекта нет. Для массива файлов каждый элемент имеет ту же форму. Обычные text/scalar/array fields сохраняют собственную schema; такой объект применяется только к binary/file fields. +- `data_base64` содержит standard base64 с padding там, где он требуется, без whitespace, URL-safe alphabet и data-URI prefix. Пустая строка означает файл из нуля байтов. В multipart part отправляются декодированные bytes, а не base64-текст. Отсутствие обязательного файла отличается от присутствующего пустого файла. +- `filename`, если указан, становится filename metadata части; если отсутствует, filename не добавляется и не угадывается. Значение не является путём к локальному файлу. Metadata проходит typed validation и безопасное quoting; управляющие символы в filename/MIME недопустимы. +- `content_type` задаёт MIME части и должен соответствовать поддерживаемым ограничениям MIME из source contract. Если он опущен, используется единственный конкретный MIME из source metadata; при отсутствии такого ограничения — `application/octet-stream`. Если source допускает несколько MIME и не задаёт единственный выбор, вызывающий обязан указать `content_type`. Невалидное или несовместимое значение отклоняется, без silent replacement. Неподдерживаемая source encoding metadata по-прежнему получает finding. +- Artifact references, filesystem paths и URL вместо inline bytes не являются альтернативными способами передачи файла в этой истории. Декодирование bounded; сохраняются существующие inbound limits и `CRANK_OUTBOUND_MAX_REQUEST_BYTES` для полного сериализованного HTTP body, включая multipart overhead. Невалидный base64/metadata и превышение outbound limit отклоняются до outbound I/O; новый upload lifecycle не создаётся. + +### Несколько request media types + +- Один endpoint остаётся одним Operation candidate и одним Tool; supported request variants сохраняются в typed contract целиком, включая несовместимые schemas. Отдельные candidates по media type и выбор первого варианта запрещены. +- Когда у endpoint несколько поддерживаемых request media types, его MCP arguments содержат верхнеуровневые `content_type` (строка — явный selector из перечисленных поддерживаемых вариантов) и `body` (значение по schema выбранного варианта). Связка selector/schema отражается в опубликованной input schema и проверяется runtime. `body` не flatten-ится; одноимённые свойства внутри body остаются внутри body. +- При передаче `body` поле `content_type` обязательно; defaults, определение формата по содержимому и fallback отсутствуют. Required request body требует оба поля. Для optional request body разрешено опустить оба поля, что означает отсутствие HTTP body; передача только одного из них ошибочна. Явный `body: null` считается переданным значением и разрешён только nullable schema выбранного варианта. +- Path/query/header/cookie parameters остаются отдельными typed inputs. В этом контракте имена `content_type` и `body` зарезервированы для body selection; source parameters с такими именами получают детерминированные уникальные input aliases, явно отражённые в schema/mapping, с сохранением исходного wire name/location. Значения параметров не могут подменить selector или body. +- Selector выбирает соответствующие validation и wire serialization (JSON/form/multipart); multipart boundary создаёт adapter, вызывающий его не передаёт. Неизвестный/unsupported selector, отсутствующий required field или body по чужой schema отклоняются до outbound I/O. Unsupported variants сохраняют точные findings согласно исходным blocker rules. +- Для единственного поддерживаемого request media type формат фиксируется в typed mapping, отдельный selector не требуется. Это уточнение не меняет публичные inputs сохранённых legacy Operations/jobs; versioned replay сохраняет их прежнее поведение. + +Пример MCP arguments для endpoint с несколькими форматами и multipart file field: + +```json +{ + "content_type": "multipart/form-data", + "body": { + "file": { + "data_base64": "SGVsbG8=", + "filename": "hello.txt", + "content_type": "text/plain" + } + } +} +``` + + + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|---------------|---------------------------|----------------| +| Methods | Resolved endpoints | GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS сохраняются | TRACE/CONNECT/unknown дают exact unsupported finding | +| Parameters | Четыре locations, одинаковые имена, path/op overrides | Typed identity, required/default/enum/nullable/format и поддерживаемая serialization сохраняются | Invalid path required/placeholder и unsupported style дают blocker | +| Bodies | JSON/form/multipart с text/scalar/array/binary fields | Required/content type/MIME/ограничения отражены в schema и wire mapping | Unsupported encoding/XML получают finding без fallback | +| Inline files | Binary/file object или массив таких objects | Standard base64 декодируется в точные bytes; filename/MIME следуют frozen contract; пустой файл отличим от отсутствующего | Invalid base64/metadata, missing required и полный multipart body сверх outbound limit отклоняются до I/O | +| Media selector | Один endpoint с JSON/form/multipart и несовместимыми schemas | Один candidate/Tool; `content_type` + `body` выбирают ровно одну ветвь; обе ветви доступны после replay | Missing/unknown selector, mismatched schema и неполная пара отклоняются до I/O | +| Selector collisions / optional body | Parameters `body`/`content_type`; optional или nullable body | Уникальные aliases сохраняют wire names; отсутствие обоих полей не отправляет body; null проверяется выбранной schema | Нет перезаписи параметров/selector; null не равен отсутствию | +| Responses | Несколько 2xx, 204, HEAD и bodyless | Все status/media/schema branches, явный no-content outcome | Валидный пустой ответ не вызывает schema error | +| Metadata | Servers, descriptions/examples/defaults | Валидный bounded candidate, URL сохраняет base path | Userinfo/invalid target блокируются; secret-like examples дают finding | +| Replay | Одинаковый IR после serialization | Равные schemas/mappings/candidates | Старые jobs не переинтерпретируются новой projection | + + + +## Code Map + +- `crates/crank-core/src/protocol.rs:11`, `operation.rs:98` — пять HttpMethod и RestTarget без descriptors body/response; persisted serde contract. +- `crates/crank-schema/src/model.rs:50`, `validate.rs:108` — nullable/default, string-only enum; format отсутствует. +- `crates/crank-import/src/rest/{openapi3.rs,swagger2.rs}` — parser, path/op parameter merge, выбор единственного body/response. +- `crates/crank-import/src/rest/{model.rs,normalize.rs,normalize_coverage.rs,normalize_schema.rs}` — typed IR, source pointers, coverage и bridge в projection; текущие версии normalized-ir-v3/preview-v3. +- `crates/crank-import/src/rest/{payload.rs,mapping.rs,schema.rs}` — collisions одинаковых имён разных locations, JSON field flattening, один output schema; legacy-v1 first-branch поведение изолировать. +- `crates/crank-runtime/src/request_preparation.rs:59`, `executor.rs:812` — scalar maps; output mapping и validation имеют доступ к status/headers/body. +- `crates/crank-adapter-rest/src/{model.rs,client.rs}` — BTreeMap query, JSON-only request; empty response уже становится Null. Сохранить actual-address OutboundPolicy. +- `apps/admin-api/src/service/imports.rs:612`, `service/imports/job_contract.rs` — persisted-v2 и legacy-v1 replay, integrity digests, full/selected Apply; новую projection version провести без потери v3 jobs. +- `crates/crank-config/src/schema.rs:321` — существующий outbound request byte limit; не путать его с upload OpenAPI до 256 KiB. +- `docs/{openapi-import.md,protocols/rest.md,operation-lifecycle.md}`, `docs/schemas/operation-export-v2.schema.json` — обновить публичные contracts вместе с реализацией. + +## Tasks & Acceptance + +**Execution:** +- [x] `crates/crank-core/src/{protocol.rs,operation.rs}`, `crates/crank-schema/src/{model.rs,validate.rs}` — расширить typed HTTP/schema contract с совместимым чтением старых Operations. +- [x] `crates/crank-import/src/rest/{model.rs,openapi3.rs,swagger2.rs,normalize.rs,normalize_coverage.rs,normalize_schema.rs}` — нормализовать все methods, locations, bodies и success variants, точные unsupported findings и coverage. +- [x] `crates/crank-import/src/rest/{payload.rs,mapping.rs,schema.rs}` — детерминированная projection без name collisions и потери semantics; сохранить legacy behavior. +- [x] `crates/crank-runtime/src/{request_preparation.rs,executor.rs}`, `crates/crank-adapter-rest/src/{model.rs,client.rs}` — выполнить поддержанный request contract на wire и корректно обработать success/no-content. +- [x] `apps/admin-api/src/service/imports.rs`, `service/imports/job_contract.rs` — versioned replay, serialization и blocker gates для Apply. +- [x] `docs/{openapi-import.md,protocols/rest.md,operation-lifecycle.md}`, `docs/schemas/operation-export-v2.schema.json` — документировать новый portable contract и поддерживаемую матрицу. +- [x] `crates/crank-import/tests/`, `crates/crank-adapter-rest/tests/`, `crates/crank-runtime/tests/`, `apps/admin-api/tests/integration/openapi_import/` — regression fixtures и wire/end-to-end проверки каждой строки матрицы, включая replay и no-mutation при blocker. + +**Acceptance Criteria (дословно из Story 2.9):** + +**Given** resolved OpenAPI endpoint +**When** importer определяет HTTP method +**Then** поддерживаются `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` и `OPTIONS` +**And** `TRACE`, `CONNECT` и неизвестные methods получают explicit unsupported finding. + +**Given** parameters на path-level и operation-level +**When** они нормализуются +**Then** path, query, header и cookie parameters объединяются согласно правилам specification version +**And** operation-level override не создаёт duplicate либо silent replacement. + +**Given** каждый parameter +**When** строится Operation input schema и request mapping +**Then** сохраняются location, required, default, enum, nullable, format и применимые serialization semantics +**And** одинаковые имена в разных locations не конфликтуют во внутренней typed model. + +**Given** path parameter +**When** исходная specification ошибочно не помечает его required либо не содержит соответствующего path placeholder +**Then** candidate получает blocker finding +**And** importer не создаёт URL template с неоднозначной подстановкой. + +**Given** OpenAPI request body +**When** content type поддерживается +**Then** JSON, `application/x-www-form-urlencoded` и `multipart/form-data` преобразуются в typed input schema и deterministic mapping +**And** required body, required fields и content type сохраняются. + +**Given** multipart body +**When** schema содержит text, scalar, array или binary/file fields +**Then** importer сохраняет field names, required status, MIME metadata и bounded upload expectations +**And** unsupported multipart encoding получает finding вместо silent fallback к JSON. + +**Given** XML request/response media type +**When** он обнаружен +**Then** affected content variant получает explicit unsupported finding в соответствии с release scope +**And** XML не преобразуется неявно в JSON или text. + +**Given** endpoint с одним или несколькими успешными `2xx` responses +**When** строится output contract +**Then** сохраняются status codes, content types и все поддерживаемые success schemas +**And** importer не выбирает произвольно первый response и не теряет остальные branches. + +**Given** `204 No Content`, `HEAD` либо success response без body +**When** строится output schema +**Then** candidate получает явный no-content outcome без требования JSON body +**And** runtime mapping не классифицирует корректный пустой response как schema error. + +**Given** API/server/base-path metadata +**When** строится REST target template +**Then** scheme, host, port и base path нормализуются без embedded credential и проходят typed validation +**And** фактическое execution по-прежнему подчиняется OutboundPolicy из Story 1.9. + +**Given** descriptions, examples или defaults из source document +**When** они включаются в candidate preview +**Then** значения bounded и не влияют на executable mapping без явного typed contract +**And** secret-like examples создают finding и не попадают в generated headers/Auth Profile. + +**Given** unsupported parameter style, schema keyword, content type или response shape +**When** candidate формируется +**Then** coverage ledger содержит точный source construct и finding severity +**And** blocker semantic loss не может быть помечена как actionable Draft. + +**Given** одинаковый resolved IR +**When** HTTP mapping запускается повторно +**Then** Operation candidates, input/output schemas и mappings совпадают детерминированно +**And** каждый candidate можно сериализовать и валидировать без обращения к исходному parser state. + +**Given** HTTP-contract test suite +**When** выполняется representative matrix +**Then** покрыты все обязательные methods, четыре parameter locations, JSON/form/multipart, multiple 2xx, 204, defaults/enums/nullability/formats и unsupported XML +**And** каждый fixture доказывает expected semantics либо expected finding, а `just verify` проходит. + +**Дополнительные AC по решению 1A + 2A:** + +- Multipart wire fixture доказывает точные decoded bytes, filename present/absent, MIME из аргумента/единственного source значения/default, MIME mismatch и выбор при нескольких source MIME; отдельно покрывает пустой файл, required omission, массив файлов, malformed base64 и multipart overhead при проверке существующего лимита. Ошибочные вызовы не достигают outbound server. +- Fixture одного endpoint минимум с двумя несовместимыми supported body schemas доказывает один candidate/Tool, доступность каждого варианта, schema публикации в MCP и корректную wire serialization выбранного формата. Проверяются missing/unknown/unsupported selector, body другой ветви, optional omission, nullable body и collisions с source parameters `body`/`content_type`. +- Serialization/replay сохраняют все request variants, их selector/schema mapping и file metadata contract детерминированно; persisted legacy fixtures сохраняют прежние inputs и execution semantics. + +## Spec Change Log + +- 2026-09-05 — пользователь утвердил 1A + 2A; уточнены frozen input contract, edge-case matrix и дополнительные AC. Исходный blocked status оставлен оркестратору для re-arm. + +## Review Triage Log + +### 2026-09-06 — ручное завершение после остановки loop + +Ревью выполнено тремя независимыми слоями по diff `/tmp/crank-story-2-4-review-Lpwiir.diff` (baseline указан выше). Откат/повторная генерация не выполнялись: сохранённая работа пользователя остаётся в worktree. Перед автоматическим loopback требуется решение пользователя; предложено завершить ограниченным набором прямых исправлений. Повторное открытое ревью не запускалось. + +| ID | Verdict | Route | Evidence | +| --- | --- | --- | --- | +| B1 | high | bad_spec | `MappingSet::empty_target_context` создаёт body `{}`, а typed `PreparedRequest` сохраняет его. Optional omission не отличим от явного пустого объекта; код подтверждён, сквозной wire test после исправления импорта test support падает. | +| B2 | high | patch | `output_schema_for_response` выбирает variants[0] у единственного HTTP descriptor с исходной union schema; необходимо сохранить целую schema при одном descriptor. | +| B3 | high | patch | reqwest 0.12.28 `RequestBuilder::header` вызывает append. После `.headers(headers)` body encoder добавляет второй Content-Type, не заменяя первый. | +| B4 | high | bad_spec | Baseline сериализует legacy body через `.json(body)`. Новый adapter выбирает form/multipart по configured Content-Type и отвергает JSON с charset; это несовместимость существующих Operations. | +| B5 | high | bad_spec | Baseline сначала применяет bounded writer; новый body encoder полностью собирает JSON/form и все decoded multipart parts до общей проверки. Ограничение памяти утрачено. | +| B6 | high | bad_spec | `openapi3_findings::operation` проверяет encoding только для multipart, тогда как form encoder всегда повторяет ключи массива. `explode=false` незаметно игнорируется. | +| B7 | high | bad_spec | Form/multipart schema допускает scalar root и вложенный обычный object, а adapter требует object root и scalar/file fields; unsupported shape не блокируется при импорте. | +| B8 | medium | defer | Проверка только parameter→placeholder не покрывает обратное направление. Подстановка отсутствующих path parameters уже оставляла placeholder в baseline; malformed-spec дефект предшествует текущей story. | +| B9 | high | bad_spec | `const`, `multipleOf`, `minProperties`, `maxProperties`, `dependentRequired` не входят в список findings и не исполняются Schema; заявленное отсутствие silent loss не обеспечено. | +| B10 | maybe-false | defer | Adapter действительно заменяет Cookie после build_headers; ResolvedAuth может применять произвольное header_name. Для подтверждения доступности через публичный API требуется проследить validation Auth Profile с Cookie и проверить совместный вызов. Потенциальная severity high; не считать подтверждённым bypass. | +| E1 | high | bad_spec | Дубликат B1, независимо подтверждён чтением MappingSet и PreparedRequest. | +| E2 | high | patch | Дубликат B2: одиночный response с Oneof смешивается с union HTTP descriptors. | +| E3 | high | bad_spec | Дубликат B6: form encoding metadata не проверяется. | +| E4 | high | bad_spec | Swagger parser возвращается для formData до проверки collectionFormat; adapter всегда использует повторяющиеся ключи, а csv/default CSV не сохранён. | +| E5 | high | bad_spec | Дубликат B7: schema-valid form input может неизбежно отвергаться adapter. | +| E6 | high | bad_spec | Дубликат B4: baseline `.json` заменён выбором encoder по заголовку, меняя legacy wire semantics. | +| E7 | medium | bad_spec | `valid_http_server_url` проверяет prefix/authority строковыми операциями и принимает нечисловой port; promised typed validation отсутствует на этапе candidate. | +| E8 | medium | defer | Object/array defaults теряются через `normalized_literal`, поддерживающий скаляры. Представление scalar-only defaults уже существовало; требуется отдельное решение совместимого расширения IR либо blocker для неподдерживаемых defaults. | +| E9 | high | bad_spec | Дубликат B9: отсутствуют blockers для неисполняемых schema keywords. | +| V1 | medium | patch | Существующий runtime test проверяет только отрицательный 200/схема206. Мутация выбора на variants[0] проходит его. Добавить позитивные 200/object и 206/array с точным результатом. | + +### Проверки текущего ручного прохода + +- Implementation handoff: import suite 79 passed; adapter suite до последних двух fixes 34 passed; targeted nullable-enum, request base-path и response-only base-path regressions passed. +- `just verify`: tooling 138 passed; capability inventory/baseline, Community scope, config/migration/metrics contracts, boundaries, Rust code health, dependency audit passed. Остановился на fmt-check; форматирование исправлено. +- `just clippy`: обнаружен collapsible_if в schema validation; исправлен, повторный полный Clippy ещё не выполнен. +- `cargo test -p crank-runtime --test http_contract_wire`: сначала compile error из-за отсутствующего импорта RuntimeExecutorTestExt; импорт исправлен. Повторный запуск: 0 passed, 1 failed (`PreparedRequestInvalid` на valid-input loop). +- Общий workspace test suite и admin integration suite на финальном diff ещё не пройдены. Story не закрыта, коммит/merge/push не выполнялись. + +### 2026-09-13 — разрешённые прямые исправления + +Пользователь подтвердил завершение по зафиксированному ревью без отката и повторной генерации. Маршруты `bad_spec` выше обрабатываются прямыми fixes в существующей реализации; frozen contract и scope не меняются. Повторное открытое ревью не запускается, выполняются проверка конкретных fixes и полный gate. + +- B1/E1: воспроизведено regression test (ожидалось отсутствие body, получен `{}`). Runtime теперь сохраняет отсутствие публичного body argument независимо от legacy initializer mapping. +- B2/E2/V1: воспроизведён отказ второй исходной union-ветви при единственном response descriptor. Runtime различает union HTTP descriptors и исходную composition; добавлены позитивные 200/206 с точным результатом. +- Целевой запуск `cargo test -p crank-runtime --test http_contract --test http_contract_wire`: 6 passed после fixes; до fixes новые regressions дали 2 failed. +- B10 подтверждён дополнительно: `validate_auth_header_name` в admin API разрешает `Cookie`, а `ResolvedAuth::ApiKeyHeader` помечает его trusted. Finding переведён из unverified в high и включён в исправления: конфликт с mapped cookies должен отклоняться до I/O, не заменять trusted credentials. +- B3/B4/E6: typed encoder заменяет Content-Type, legacy JSON encoder сохраняет настроенный заголовок и прежнюю JSON-сериализацию. Wire regression проверяет единственный Content-Type для JSON/form/multipart и legacy charset/form headers. +- B5: bounded writer останавливает JSON/form encoding при превышении лимита; multipart использует общий бюджет decoded payload и bounded сборку полного wire body. Проверены percent-encoding expansion, несколько файлов и multipart overhead. +- B10: конфликт mapped/trusted Cookie теперь возвращает InvalidBodyContract до dispatch; отдельный positive case сохраняет trusted Cookie без конфликта. +- B6/E3/E4: неподдерживаемое form encoding и Swagger csv/default arrays получают blockers с exact source pointers. Swagger operation parameter findings привязаны к операции, а не только document-level. +- B7/E5: scalar form root, вложенные object/array fields и object composition branches блокируются до создания actionable Draft; provenance валидирует соответствующие pointers. +- B9/E9/E7: добавлены blockers для перечисленных в review schema keywords; URL разбирается существующей workspace-библиотекой `url`, с проверкой схемы, host, port, userinfo и control characters. Версии зависимостей не обновлялись. +- B8 и E8 остаются pre-existing deferred, записаны в корневой deferred-work.md. B10 больше не отложен. Остальные findings этого review исправлены прямыми patches. +- `cargo test -p crank-adapter-rest --all-targets`: 40 passed. `cargo test -p crank-import --test http_contract_regressions`: 7 passed после исправления propagation (первый запуск выявил отсутствующий operation-level CSV blocker). + +### Итоговый gate — 2026-09-13 + +- `just verify` на финальном diff завершился с exit code 0. Tooling: 138 passed; capability/config/migration/metrics contracts, boundaries, code health, dependencies, fmt и полный Clippy прошли. +- Workspace `cargo test --workspace --all-targets -- --test-threads=1` прошёл. В том числе admin integration: 81 passed; MCP integration: 40 passed; importer: 82 passed в отдельном полном запуске; adapter: 40 passed; целевые runtime HTTP tests: 6 passed. +- Исправлены два устаревших test expectations: legacy job теперь содержит настоящий legacy preview с соответствующим digest; Swagger diagnostics проверяются на document- и operation-level, включая точную привязку к операции. Production integrity checks не ослаблялись. +- Disk-full subprocess test использует RLIMIT_FSIZE: прямой redirect его stdout/stderr в regular file мешал завершению harness. Финальный gate выполнен через pipe/tee с `pipefail`; тест прошёл без изменения кода. +- Один ранее ignored benchmark `production_size_invocation_history_queries_stay_bounded` (1 000 000 строк) остаётся ignored по существующему правилу; в рамках этой story его не запускали. Browser E2E и deploy не запускались. +- Принятые review fixes завершены; повторного открытого ревью не было. B8/E8 остаются явно отложенными pre-existing findings. Коммит `f8ee7c9bfeaa8a3f73a4850ff3f82b2bc2155fe8` интегрирован в `main` fast-forward 2026-09-13; статус спринта согласован: `done`. Интеграция не меняет проверенное дерево коммита; полный тестовый gate повторно не запускался. Push, bmad-loop и Story 2.10 не запускались. + +## Design Notes + +Сохранить направление слоёв: importer pure, runtime orchestrates, adapter owns REST wire behavior. Выбор success schema по status/media может быть внутренним и не требует нового MCP envelope. Версия normalization/projection должна измениться при изменении preview semantics; v1/v2/v3 jobs сохраняют старое значение. + +## Verification + +**Commands:** +- `cargo test -p crank-import --all-targets` — representative fixture matrix и deterministic replay. +- `cargo test -p crank-adapter-rest --all-targets` — wire serialization и прежняя outbound policy. +- `cargo test -p crank-runtime --all-targets` — request/output semantics и no-content. +- `cargo test -p admin-api --test integration -- --test-threads=1` — preview/apply/replay и blocker no-mutation. +- `just verify` — обязательный полный gate Story 2.4. + +Исходный baseline: `cargo test -p crank-import --all-targets` — 64 passed, 0 failed, 0 ignored. Это проверка исходного кода, не доказательство выполнения AC Story 2.4. diff --git a/_bmad-output/implementation-artifacts/spec-bmad-loop-sprint-compatibility.md b/_bmad-output/implementation-artifacts/spec-bmad-loop-sprint-compatibility.md new file mode 100644 index 0000000..9ba5730 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-bmad-loop-sprint-compatibility.md @@ -0,0 +1,99 @@ +--- +title: 'Восстановить корректную работу bmad-loop со спринтом Crank' +type: 'bugfix' +created: '2026-09-05' +status: 'done' +baseline_commit: '083974c27f3a21a15807dd248bb6bc4fe04a5cd8' +review_loop_iteration: 0 +context: + - '_bmad-output/project-context.md' +--- + + + +## Intent + +**Problem:** Loop 0.11.1 игнорирует завершённые вложенные IDs 2.1b2a/b2b. Последний запуск 20260905-140512-5583 остановился на 2.4 с unclear intent: изолированный worktree не получил planning-artifacts и project-context. Простое исправление статусов не устраняет причину остановки. + +**Approach:** Привести активные IDs к поддерживаемой грамматике, сохранив исторические aliases и завершённость. Настроить передачу проектного контекста через штатный worktree_seed. Проверить реальное provisioning и выбор следующей задачи без платной dev-сессии. + +## Boundaries & Constraints + +**Always:** Сохранить 88 stories, 24 done и 64 backlog, порядок выполнения и связи с результатами. Отобразить 2.1b2a → 2.1e, 2.1b2b → 2.1f; сохранить прежние номера как legacy aliases. Stories 2.2/2.3 и Epic 1 не возвращаются в работу. Requirements 2.4 доступны из worktree, AGENTS.md и настройки renderer сохраняются. Все предыдущие run records и незакоммиченные результаты остаются нетронутыми. + +**Ask First:** Изменение модели, token/time limits, permission flags, отключение проверок, обновление установленного loop, изменение системных зависимостей или принудительный откат существующего run. + +**Never:** Подменять unknown keys фильтрацией, править site-packages, удалять историю, запускать разработку, push или deploy в ходе проверки. Нельзя утверждать успешную разработку 2.4 по результату dry-run. + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|---|---|---|---| +| Completed splits | Два вложенных legacy ID | Две отдельные done stories под 2.1e/2.1f, aliases сохранены | Никакого уменьшения общего числа stories | +| Queue | Epic 2 после 2.3 | Ровно 2.4–2.9 в прежнем порядке | Завершённые stories не actionable | +| Fresh worktree | Gitignored planning и implementation artifacts | Требования, контекст, specs и правила доступны в изолированном дереве | Отсутствие файла проваливает проверку | +| Existing paused run | Run 5583, unclear intent | История и worktree сохраняются; дана явная процедура нового старта либо безопасного resolve | Сам run не возобновляется | +| Isolation | Provisioning тестового дерева | Main code и history не меняются, служебные файлы не попадают в staged diff | Не изменять общий git exclude для обхода проблемы | + + + +## Alias Mapping (2026-09-05) + +- `2.1b2a` → `2.1e` — legacy alias сохранён в metadata и redirect. +- `2.1b2b` → `2.1f` — legacy alias сохранён в metadata и redirect. + +## Code Map (Baseline Description) + +- `.bmad-loop/policy.toml`, `[scm]` — сейчас worktree_seed содержит только AGENTS.md; штатный seed принимает пути файлов и каталогов. +- `_bmad-output/implementation-artifacts/sprint-status.yaml` — источник очереди, статусы уже согласованы, два ключа не распознаются. +- `_bmad-output/implementation-artifacts/spec-2-1b2{a,b}-*.md` — завершённые specs: обновить активные имена и metadata, сохранить historical aliases и frozen intent. +- `_bmad-output/planning-artifacts/epics.md:1403`, `_bmad-output/implementation-artifacts/epic-2-context.md` — синхронизировать decomposition и зависимости, не менять scope acceptance. +- Установленный `bmad_loop/sprintstatus.py` — read-only grammar `N-M[a-z]?`, очередь идёт в порядке файла. +- Установленный `bmad_loop/worktree_flow.py:provision_worktree` — read-only штатное копирование seed с git isolation; renderer и upstream skills копируются самим loop, повторная установка не нужна. + +## Tasks & Acceptance + +**Execution:** +- [x] Tracking, два split-spec и активные planning/context references — согласовать поддерживаемые IDs и aliases; не переписывать исторические logs/proposals. +- [x] `.bmad-loop/policy.toml` — добавить planning-artifacts, implementation-artifacts и project-context в штатные seeds, не ослабляя isolation и verification. +- [x] Проверки в отдельном временном worktree — вызвать штатное provisioning, доказать наличие требований Story 2.4, правил и контекста; проверить отсутствие нежелательных git changes. +- [x] Повторить sprint validator, loop preflight и dry-run; зафиксировать безопасную процедуру запуска после исправления. + +**Acceptance Criteria:** +- Given repaired tracking, when оба парсера читают спринт, then видны 88 stories без unknown keys, 24 done и 64 backlog. +- Given isolated worktree, when агент ищет intent 2.4, then исходный раздел epics с acceptance criteria и project-context доступны локально. +- Given Epic 2, when loop строит dry-run, then выбираются только шесть оставшихся stories начиная с 2-4-http-contract. + +## Spec Change Log + +## Verification + +**Фактические проверки 2026-09-05:** + +- `uv run .agents/skills/bmad-sprint-planning/scripts/sprint_plan.py validate --status-file _bmad-output/implementation-artifacts/sprint-status.yaml` — `valid: true`. +- Installed `bmad_loop.sprintstatus.load` — 88 stories, 24 `done`, 64 `backlog`, `unknown_keys=[]`; очередь Epic 2 — ровно `2-4-http-contract` … `2-9-openapi-guided-onboarding` в порядке файла. +- `bmad-loop validate --project /home/bsodfather/code/crank` — PASS: policy, 88-story sprint, clean worktree, Codex adapter и upstream skills. +- `bmad-loop run --project /home/bsodfather/code/crank --epic 2 --dry-run` — PASS: шесть stories 2.4–2.9 без dev-сессии. +- Disposable `git worktree` через installed `bmad_loop.worktree_flow.provision_worktree` — без skipped/undelivered seeds; доступны `AGENTS.md`, project context, `epics.md` с requirements Story 2.4, implementation artifacts, exact renderer config и `_bmad/scripts/render_skill.py`; renderer успешно выполнен во временном дереве. Staged diff пуст, `git status --porcelain` пуст; тестовое дерево удалено. +- `git diff --check` — PASS. Исходные snapshots ignored operational artifacts не сохранены, поэтому неизменность этих файлов не доказуема git diff. + +**Процедура нового старта:** после успешного `bmad-loop validate --project /home/bsodfather/code/crank` выполнить `bmad-loop run --project /home/bsodfather/code/crank --epic 2 --max-stories 1`. Не возобновлять paused run `20260905-140512-5583`: copy-when-absent не обновляет уже существующий worktree. + +## Review Result + +Три review layers выполнены последовательно одним reviewer из-за лимита доступных agent threads. Исправлены legacy path redirects, активная deferred-ссылка, процедура нового старта и точность verification evidence. Root независимо повторил CLI validate/status/dry-run и provisioning с реальным Codex profile, hooks, skills и исполнением renderer; shared git exclude и HEAD не менялись. Новых dev-сессий не было, paused run 5583 и его worktree сохранены. + +Повторяемая snapshot-specific проверка: `/home/bsodfather/.local/share/uv/tools/bmad-loop/bin/python .bmad-loop/check-sprint-compatibility.py`. Ожидаемые 24 done/64 backlog относятся к текущему ремонту и изменятся при продолжении разработки. Проверка создаёт только собственный временный detached worktree и удаляет его после завершения. + +Изменения локальные, в gitignored operational artifacts; коммит и push не создавались. Возможность долгого успешного выполнения Story 2.4 не доказывается preflight-проверками. Полная регенерация legacy sprint keys из русских заголовков остаётся отдельной операцией согласования; loop читает исправленный sprint-status напрямую. + +## Suggested Review Order + +- Передача требований и правил в новый изолированный worktree. + [policy.toml:147](../../.bmad-loop/policy.toml#L147) +- Поддерживаемые ключи сохраняют обе завершённые подзадачи и очередь. + [sprint-status.yaml:69](sprint-status.yaml#L69) +- План разделяет filesystem и database recovery без потери исходных критериев. + [epics.md:1403](../planning-artifacts/epics.md#L1403) +- Snapshot regression проверяет настоящий Codex profile и renderer в отдельном worktree. + [check-sprint-compatibility.py:1](../../.bmad-loop/check-sprint-compatibility.py#L1) diff --git a/_bmad-output/implementation-artifacts/spec-ci-canonical-migration-contract-drift.md b/_bmad-output/implementation-artifacts/spec-ci-canonical-migration-contract-drift.md new file mode 100644 index 0000000..7122d96 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-ci-canonical-migration-contract-drift.md @@ -0,0 +1,106 @@ +--- +title: 'Исправить drift canonical migration contract после добавления V13' +type: 'bugfix' +created: '2026-08-29' +status: 'done' +baseline_commit: 'c2556ec236b6b14306c6f2d8674c3c5ada8b704e' +review_loop_iteration: 0 +context: [] +--- + + + +## Intent + +**Problem:** CI и release блокируются на `crank-migrate plan --check`: Rust migration authority уже содержит append-only V13, но committed machine contract и связанные CLI-ожидания остались на V12. Из-за точного сравнения планов команда закономерно возвращает `contract_drift` на `plan.compare`. + +**Approach:** Добавить фактический V13 descriptor в canonical JSON без изменения записей V1–V12, синхронизировать точечные CLI-тесты и operator documentation с current version 13, затем проверить детерминированность и полный migration contract. + +## Boundaries & Constraints + +**Always:** Rust `MigrationAuthority::sequence()` остаётся единственным источником истины; committed JSON должен byte-semantically соответствовать сгенерированному plan; V1–V12 неизменяемы; V13 использует уже закреплённые name/checksum/source digest/readability fields; исправление одинаково валидно для CI и release workflow. + +**Ask First:** Любое изменение SQL V13, descriptor authority, checksum/source digest, migration ordering, compatibility window либо поведения CLI сравнения. + +**Never:** Удалять V13, ослаблять или пропускать `plan --check`, редактировать исторические descriptors, игнорировать drift, менять PostgreSQL state либо регенерировать contract из недоверенного/непроверенного источника. + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|---------------|---------------------------|----------------| +| Canonical check | Authority V1–V13 и committed JSON | `plan --check` возвращает `contract_current` и exit 0 | Любое semantic отличие остаётся `contract_drift` | +| Deterministic plan | Два последовательных запуска `plan` | JSON plans идентичны и содержат ровно V1–V13 | Нестабильность блокирует исправление | +| Fresh schema | `apply`, затем `preflight` | Ledger и CLI сообщают current version 13 | Ошибка миграции не маскируется обновлением contract | +| Historical immutability | Canonical V1–V12 до/после исправления | Старые entries не меняются; добавляется только V13 | Любое изменение истории отклоняется | + + + +## Code Map + +- `apps/admin-api/src/bin/crank-migrate.rs:154-208` — строит plan из authority и semantic-сравнивает его с committed JSON; менять проверку не требуется. +- `crates/crank-registry/src/migrations/authority.rs:24-26,258-263` — действующий source of truth: current version 13 и descriptor `artifact-cleanup-indexes-v13` с readable window 12..13. +- `crates/crank-registry/src/migrations/artifact_cleanup_indexes_v13.rs:5-7` — закрепляет SHA-256 `abe822…ab05`; SQL и digest read-only в этом исправлении. +- `docs/schemas/migration-sequence.json:1-204` — canonical machine contract сейчас заканчивается V12; добавить только сгенерированный V13 object. +- `apps/admin-api/tests/migration_command.rs:30-49,68-86` — deterministic plan и fresh-schema preflight имеют устаревшие ожидания `12`. +- `crates/crank-registry/src/migrations/authority_tests.rs:4-18` — append-only sequence test также имеет устаревший список V1–V12. +- `crates/crank-registry/tests/integration/migrations.rs:32-55` — уже подтверждает ledger V1–V13; использовать как широкую проверку, не переписывать. +- `docs/migrations.md:9-20,62-98` — operator flow всё ещё называет current version 12 и не описывает V13. +- `.gitea/workflows/{ci.yml:70-71,release.yml:66-67}` — оба pipeline уже вызывают правильный gate; workflow read-only. + +## Tasks & Acceptance + +**Execution:** +- [x] `docs/schemas/migration-sequence.json` — добавить точный V13 descriptor из `crank-migrate plan`, сохранив V1–V12 без изменений. +- [x] `apps/admin-api/tests/migration_command.rs` — синхронизировать sequence length/current version с 13 и сохранить проверку `plan --check`. +- [x] `crates/crank-registry/src/migrations/authority_tests.rs` — включить V13 в точный append-only sequence test. +- [x] `docs/migrations.md` — обновить operator current-version пример и добавить назначение V13. +- [x] Verification — доказать canonical equality, историческую append-only дельту и прохождение CLI/integration migration tests. + +**Acceptance Criteria:** +- Given checkout с V13 authority, when CI или release выполняет canonical migration gate, then команда завершается exit 0 и сообщает `contract_current`. +- Given canonical JSON до исправления, when рассматривается итоговый diff, then V1–V12 semantic entries идентичны, а единственное изменение sequence — новый V13 descriptor. +- Given fresh PostgreSQL schema, when migrations применяются и выполняется preflight, then canonical ledger и CLI согласованно сообщают current version 13. + +## Spec Change Log + +## Design Notes + +Это восстановление ранее нарушенной append-only публикации V13, а не новая миграция. Canonical object берётся только из текущего executable `plan`; checksum равен проверяемому SHA-256 уже committed SQL artifact. + +## Verification + +**Commands:** +- `cargo run -p admin-api --bin crank-migrate -- plan --check` — expected: exit 0 и `contract_current`. +- `cargo test -p admin-api --test migration_command` — expected: deterministic contract и fresh-schema current version 13 проходят. +- `cargo test -p crank-registry --lib migrations::authority::tests::sequence_is_deterministic_and_append_only -- --exact` — expected: deterministic append-only sequence V1–V13 проходит. +- `cargo test -p crank-registry --test integration integration::migrations::controlled_authority_is_versioned_and_safe_under_concurrent_apply -- --exact --test-threads=1` — expected: ledger V1–V13 проходит. +- `git diff c2556ec236b6b14306c6f2d8674c3c5ada8b704e -- docs/schemas/migration-sequence.json` — expected: добавлен только V13 object. +- `cargo fmt --all -- --check && git diff --check` — expected: clean. + +**Фактические результаты:** +- Canonical check прошёл с `{"status":"contract_current"}`. +- `migration_command`: 7 passed; deterministic plan и fresh-schema preflight подтвердили V13. +- Authority unit test: 1 passed; точная последовательность V1–V13 подтверждена. +- Registry PostgreSQL integration: 1 passed; ledger после concurrent apply содержит V1–V13. +- Historical immutability проверена semantic diff первых 12 entries против baseline; отличий нет, sequence содержит ровно один новый V13 entry. +- `cargo fmt --all -- --check` и `git diff --check` прошли. + +## Suggested Review Order + +**Canonical contract** + +- Append-only V13 descriptor восстанавливает равенство committed plan и Rust authority. + [`migration-sequence.json:195`](../../docs/schemas/migration-sequence.json#L195) + +**Regression protection** + +- CLI contract проверяет детерминированный план и fresh-schema current version 13. + [`migration_command.rs:43`](../../apps/admin-api/tests/migration_command.rs#L43) + +- Authority test закрепляет непрерывную последовательность V1–V13. + [`authority_tests.rs:11`](../../crates/crank-registry/src/migrations/authority_tests.rs#L11) + +**Operator contract** + +- Upgrade flow и назначение expand-only V13 синхронизированы с executable plan. + [`migrations.md:19`](../../docs/migrations.md#L19) diff --git a/_bmad-output/implementation-artifacts/spec-ci-community-scope-marker.md b/_bmad-output/implementation-artifacts/spec-ci-community-scope-marker.md new file mode 100644 index 0000000..91704b6 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-ci-community-scope-marker.md @@ -0,0 +1,20 @@ +--- +title: 'Исправить запрещённый community-scope marker' +type: 'bugfix' +created: '2026-08-29' +status: 'done' +route: 'one-shot' +--- + +# Исправить запрещённый community-scope marker + +## Intent + +**Problem:** CI community-scope gate отклонял устаревший термин `tenant` в комментарии cleanup-кода. + +**Approach:** Заменить его каноническим термином `workspace`, не меняя исполняемое поведение. + +## Suggested Review Order + +- Терминология комментария теперь соответствует `WorkspaceId` и community-модели изоляции. + [`import_job.rs:214`](../../crates/crank-registry/src/postgres/import_job.rs#L214) diff --git a/_bmad-output/implementation-artifacts/spec-ci-debian-apt-https-bootstrap.md b/_bmad-output/implementation-artifacts/spec-ci-debian-apt-https-bootstrap.md new file mode 100644 index 0000000..7f8675f --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-ci-debian-apt-https-bootstrap.md @@ -0,0 +1,79 @@ +--- +title: 'Исправить runtime Docker build при недоступном Debian HTTP mirror' +type: 'bugfix' +created: '2026-08-29' +status: 'done' +baseline_commit: '55209a9bbc38f7a34c972cba5d9fad27bc9305b0' +review_loop_iteration: 0 +context: [] +--- + + + +## Intent + +**Problem:** Release build успешно компилирует Rust binaries, но runtime-слой `debian:bookworm-slim` обращается к `deb.debian.org` по HTTP/80. В CI этот порт недоступен, поэтому `apt-get update` оставляет пустые indexes и установка `ca-certificates curl` завершается ошибкой. + +**Approach:** Перевести Debian repositories обоих Rust runtime images на HTTPS, предварительно bootstrap-ить доверенный CA bundle из уже используемого Rust builder image, и добавить ограниченные apt retries для кратковременных сетевых сбоев. + +## Boundaries & Constraints + +**Always:** Одинаково исправить `admin-api` и `mcp-server`; TLS verification остаётся включённой; runtime сохраняет `ca-certificates` для исходящих HTTPS-запросов и `curl` для существующих Compose healthchecks; Docker build остаётся воспроизводимым в текущем multi-stage layout. + +**Ask First:** Смена runtime base image, удаление `curl`/healthchecks, добавление нового healthcheck binary или изменение release workflow. + +**Never:** `Acquire::https::Verify-Peer=false`, trusted/unsigned repositories, fallback на HTTP, бесконечные retry loops или игнорирование ненулевого exit code `apt-get`. + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|---------------|---------------------------|----------------| +| HTTP/80 недоступен | Registry доступен, Debian mirror доступен только по HTTPS/443 | Оба runtime images собираются через HTTPS repositories | Build падает, если HTTPS или signature verification реально не проходят | +| Чистый slim runtime | В runtime layer ещё нет `ca-certificates` package | CA bundle из builder позволяет проверить TLS первого `apt-get update` | Нельзя отключать TLS verification для bootstrap | +| Кратковременный mirror failure | HTTPS request временно не проходит | APT выполняет конечное число повторов | После исчерпания retries build завершается ошибкой | +| Runtime contract | Image успешно собран | CA bundle непустой, `curl` установлен, application entrypoint/CMD сохранены | Contract check не запускает сервис и не меняет production state | + + + +## Code Map + +- `apps/admin-api/Dockerfile:17-23` — runtime stage устанавливает CA/curl; builder уже содержит `/etc/ssl/certs/ca-certificates.crt`. +- `apps/mcp-server/Dockerfile:54-60` — тот же runtime bootstrap и источник текущего CI failure на строке 56. +- `docker-compose.yml:130,193` — healthchecks зависят от `curl` внутри images. +- `deploy/community/docker-compose.yml:144,205` и `deploy/community/docker-compose.images.yml:141,202` — packaged community healthchecks подтверждают, что `curl` нельзя удалить локальным workaround. +- `.gitea/workflows/ci.yml:267-268,371-375` и `.gitea/workflows/release.yml:197-202` — оба Dockerfile собираются в CI/release; workflow менять не требуется. + +## Tasks & Acceptance + +**Execution:** +- [x] `apps/admin-api/Dockerfile` — скопировать CA bundle из builder до первого HTTPS request, переключить Debian sources на HTTPS и включить bounded retries. +- [x] `apps/mcp-server/Dockerfile` — применить идентичный runtime bootstrap, не меняя binary build/CMD. +- [x] Docker verification — собрать оба images и проверить наличие CA bundle/curl внутри runtime layers. + +**Acceptance Criteria:** +- Given исходный CI network profile с недоступным HTTP/80 и доступным HTTPS/443, when собираются `admin-api` и `mcp-server`, then оба builds завершаются успешно без ослабления TLS или repository signature verification. +- Given собранные images, when проверяется runtime contract, then `curl` доступен, CA bundle непустой, а исходные ENTRYPOINT/CMD остаются неизменными. + +## Spec Change Log + +## Design Notes + +CA bootstrap берётся из `rust:1.96.1-bookworm`, уже являющегося доверенной build stage на той же Debian-family базе. После HTTPS `apt-get update` пакет `ca-certificates` устанавливается штатно и становится владельцем актуального runtime trust store. + +## Verification + +**Commands:** +- `docker build --progress=plain -f apps/admin-api/Dockerfile -t crank/admin-api:ci-fix .` — passed; runtime APT получил подписанные indexes через HTTPS и установил `ca-certificates`/`curl`. +- `docker build --progress=plain -f apps/mcp-server/Dockerfile -t crank/mcp-server:ci-fix .` — passed. +- `docker run --rm --entrypoint sh crank/admin-api:ci-fix -c 'test -s /etc/ssl/certs/ca-certificates.crt && curl --version >/dev/null'` — passed. +- `docker run --rm --entrypoint sh crank/mcp-server:ci-fix -c 'test -s /etc/ssl/certs/ca-certificates.crt && curl --version >/dev/null'` — passed. +- `docker image inspect ...` — passed; admin image сохранил `ENTRYPOINT [\"/usr/local/bin/crank-admin-entrypoint\"]` и `CMD [\"admin-api\"]`, MCP image сохранил `CMD [\"mcp-server\"]`. +- `git diff --check` — passed. + +## Suggested Review Order + +- Основной runtime bootstrap: доверенный CA, HTTPS-only sources и ограниченные повторы APT. + [`admin-api/Dockerfile:19`](../../apps/admin-api/Dockerfile#L19) + +- Тот же защищённый bootstrap применён к MCP runtime без изменения команды запуска. + [`mcp-server/Dockerfile:56`](../../apps/mcp-server/Dockerfile#L56) diff --git a/_bmad-output/implementation-artifacts/spec-deploy-authenticated-smoke-outbound-allowlist.md b/_bmad-output/implementation-artifacts/spec-deploy-authenticated-smoke-outbound-allowlist.md new file mode 100644 index 0000000..9ba47f1 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-deploy-authenticated-smoke-outbound-allowlist.md @@ -0,0 +1,95 @@ +--- +title: 'Сделать production product smoke диагностируемым' +type: 'bugfix' +created: '2026-09-02' +status: 'done' +review_loop_iteration: 0 +followup_review_recommended: true +baseline_commit: 'bbb9394911ee85995b9bed3ec0b538301097a538' +baseline_revision: 'bbb9394911ee85995b9bed3ec0b538301097a538' +context: + - '{project-root}/_bmad-output/project-context.md' +--- + + + +## Intent + +**Problem:** Authenticated product smoke корректно обнаруживает реальный runtime failure после deployment, но скрывает типизированную причину за неинформативным `outcome_not_ok`. Оператор не получает `code`, `stage` и `trace_id`, хотя API уже возвращает эти безопасные данные. + +**Approach:** Сохранить smoke после deployment как доказательство реальной сети и runtime policy. При `ok: false` выводить только безопасные типизированные поля результата: `code`, `stage` и валидный `trace_id`. + +## Boundaries & Constraints + +**Always:** Diagnostics должны быть bounded и не содержать message, URL, payload, context, cookie, token или credential. Smoke остаётся post-deploy проверкой реального execution path. + +**Ask First:** Смена внутреннего smoke target, добавление отдельного configuration gate либо изменение security policy исходящих запросов. + +**Never:** Ослаблять DNS/IP проверку; печатать полный `errors[]`/response body; считать HTTP 200 успешным при `ok: false`; дублировать post-deploy execution отдельной поверхностной env-проверкой. + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|--------------|---------------------------|----------------| +| Failed operation test | `ok=false`, первый error содержит безопасные code/stage, response содержит trace_id | Smoke завершается ошибкой с code/stage/trace_id | Никакие message/context/payload значения не выводятся | +| Malformed diagnostic | code/stage/trace_id отсутствуют либо не проходят allowlisted format | Smoke остаётся fail-closed | Используется bounded `outcome_not_ok`, raw значение не отражается | +| Successful operation test | `ok=true` | Smoke продолжает publish и MCP stages без изменения поведения | N/A | + + + +## Code Map + +- `scripts/authenticated-product-smoke.py:24-31,289-301` — `safe_error` задаёт bounded contract; `run_operation_test` сейчас отбрасывает безопасные typed diagnostics. +- `tests/unit/test_authenticated_product_smoke.py:218-234` — существующий regression проверяет redaction failed outcome; расширить code/stage/trace_id и malformed cases. +- `apps/admin-api/src/dto.rs:104-113` и `apps/admin-api/src/error.rs:777-799` — read-only response contract: top-level trace identity и типизированные error code/stage уже безопасны. + +## Tasks & Acceptance + +**Execution:** +- [x] `scripts/authenticated-product-smoke.py` — формировать bounded failure из валидных `errors[0].code`, `errors[0].stage` и top-level `trace_id`, сохраняя generic fallback. +- [x] `tests/unit/test_authenticated_product_smoke.py` — доказать информативность, redaction, bounded output и fail-closed malformed diagnostics. + +**Acceptance Criteria:** +- Given operation test возвращает typed failure, when smoke завершается, then оператор видит безопасные code/stage/trace_id и может найти запрос в UI/GlitchTip без раскрытия payload. +- Given operation test успешен, when smoke продолжается, then publish, MCP call и cleanup выполняются без изменения прежнего поведения. + +## Spec Change Log + +## Review Triage Log + +### 2026-09-05 — Review pass +- intent_gap: 0 +- bad_spec: 0 +- patch: 7: (high 0, medium 2, low 5) +- defer: 0 +- reject: 6: (high 0, medium 0, low 6) +- addressed_findings: + - `[medium]` `[patch]` Unicode-цифры исключены из trace_id строгим ASCII hex-набором. + - `[medium]` `[patch]` Добавлены проверки длины, регистра, нулевого trace_id, Unicode, переноса строки и нестрокового значения. + - `[low]` `[patch]` Typed diagnostics разрешены только при точном ok=False; malformed envelope проверяется с иначе валидными диагностическими полями. + - `[low]` `[patch]` Покрыты границы code/stage и максимальная длина ASCII-вывода. + - `[low]` `[patch]` Добавлены malformed result/errors/first error случаи. + - `[low]` `[patch]` Canary в request_preview/response_preview не попадают в вывод. + - `[low]` `[patch]` Успех ok=True сохраняется при malformed diagnostics. + +## Design Notes + +Allowlist остаётся операторским security decision. Конкретный deployment уже исправлен через OpenBao; репозиторный hotfix меняет только диагностическое сообщение post-deploy smoke. + +## Verification + +**Commands:** +- `python3 -m unittest tests.unit.test_authenticated_product_smoke` — diagnostics и redaction зелёные. +- `python3 -m unittest discover -s tests/unit` — весь Python tooling suite зелёный. +- `scripts/check-community-scope.sh && git diff --check` — repository gates зелёные. + +## Auto Run Result + +- Реализована bounded диагностика неуспешного operation test: проверенные code/stage/trace_id либо generic fallback. Post-deploy execution path и outbound security policy не изменены. +- Файлы: `scripts/authenticated-product-smoke.py` — форматирование и валидация; `tests/unit/test_authenticated_product_smoke.py` — regression и malformed/boundary/redaction проверки. +- Review: исправлено 7 замечаний, deferred 0, rejected 6; дубли четырёх review layers объединены. +- Follow-up review recommended: true; patched high=0, medium=2, low=5; score=11. Замечания исправлены и перепроверены, рекомендация не является блокером. +- `python3 -m unittest tests.unit.test_authenticated_product_smoke`: exit 0, 17 tests; основной агент повторил независимо. +- `python3 -m unittest discover -s tests/unit`: exit 0, 138 tests, 76.818s. +- `scripts/check-community-scope.sh && git diff --check`: exit 0, 662 files; основной агент повторил независимо и проверил итоговый diff. +- Ограничения: live deployment не повторялся. Диагностика опирается на типизированный контракт admin API, проверяя формат, а не отдельный enum всех серверных кодов. Установка GlitchTip не входит в изменение. diff --git a/_bmad-output/implementation-artifacts/spec-deploy-legacy-fingerprint-normalization.md b/_bmad-output/implementation-artifacts/spec-deploy-legacy-fingerprint-normalization.md new file mode 100644 index 0000000..465317c --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-deploy-legacy-fingerprint-normalization.md @@ -0,0 +1,102 @@ +--- +title: 'Нормализовать fingerprint последовательно обновлённой legacy-схемы' +type: 'bugfix' +created: '2026-09-02' +status: 'done' +review_loop_iteration: 0 +baseline_commit: '2759fde81f2e15fea2df65b1f9eeb5470191c393' +context: + - '{project-root}/_bmad-output/project-context.md' +--- + + + +## Intent + +**Problem:** Shadow migration production backup блокируется на `preflight.legacy_fingerprint`, хотя база имеет опубликованный pre-ledger контракт. Fingerprint ошибочно считает `ordinal_position` частью семантики: после исторических `ALTER TABLE ADD/DROP COLUMN` физический порядок отличается от fresh-схемы `8318e4b`, хотя именованные SQL-контракты эквивалентны. + +**Approach:** Исключить только физический ordinal колонок из детерминированного PostgreSQL-16 fingerprint, пересчитать allowlist по подтверждённым опубликованным схемам и доказать acceptance для fresh и последовательного upgrade-layout. Все значимые свойства схемы и fail-closed shadow gate сохранить. + +## Boundaries & Constraints + +**Always:** Проверять relation kind, имя/тип/nullability/default каждой колонки, constraints, indexes, non-internal triggers, RLS/policies, состояние internal triggers, index validity/readiness/liveness, persistence и replica identity. Выполнять migration postflight внутри транзакции. До успешной проверки backup не запускать live Compose. + +**Ask First:** Любое ослабление проверки кроме игнорирования несемантического `ordinal_position`; поддержка схем, которые нельзя связать с опубликованной историей Crank; изменение migration sequence или wire-контракта diagnostics. + +**Never:** Принимать неизвестную/частичную схему, отключать fingerprint, переписывать ledger вручную, применять DDL во время диагностики, выводить raw schema/SQL/rows/credentials или обходить shadow migration. + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|--------------|---------------------------|----------------| +| Fresh legacy | Fresh-схема последнего pre-ledger релиза | `apply` выполняет `0 → 13`, postflight возвращает current 13 | Транзакционный rollback при postflight failure | +| Sequential legacy | Те же именованные колонки, но ordinal отличается после исторических ADD/DROP | Считается тем же опубликованным контрактом, данные сохраняются | Не отклоняется только из-за ordinal | +| Structural drift | Изменены имя, тип, default, constraint, index или trigger state | Adoption отклоняется до записи core ledger | `partial_sequence / preflight.legacy_fingerprint` | +| Foreign/partial DB | Неполный набор Crank relations либо future objects без ledger | Не классифицируется как допустимая legacy-схема | Fail closed без DDL | + + + +## Code Map + +- `crates/crank-registry/src/migrations/schema_guard_legacy_v1.rs` — формирует catalog JSON и SHA-256; сейчас включает `ordinal_position`, здесь находится root cause и allowlist. +- `crates/crank-registry/src/migrations/authority.rs` — классифицирует ledgerless baseline и выполняет transactional postflight; поведение mutation менять не требуется. +- `crates/crank-registry/tests/integration/migrations/legacy_adoption.rs` — positive/negative PostgreSQL-16 evidence; добавить layout с переставленными через ADD/DROP колонками и сохранностью данных. +- `scripts/deploy-community.sh` — восстанавливает production backup в isolated PostgreSQL и блокирует live rollout до current 13; сохранить без bypass. +- История `a8aa324`, `5922aea`, `8a1cc17`, `2b2ff92`, `8318e4b` — read-only evidence последовательных ADD/DROP для `platform_api_keys` и `approval_requests`. + +## Tasks & Acceptance + +**Execution:** +- [x] `schema_guard_legacy_v1.rs` — убрать ordinal из canonical column item, пересчитать exact SHA allowlist и не менять остальные catalog checks. +- [x] `legacy_adoption.rs` — создать regression layout через исторически эквивалентные DROP/ADD операции, доказать preflight `0 → 13`, сохранность representative rows и current 13. +- [x] `legacy_adoption.rs` — сохранить negative evidence для column/default/constraint/index/trigger/RLS drift и отсутствие committed ledger. +- [ ] `scripts/deploy-community.sh` — повторно проверить итоговым image восстановление backup, непривилегированного owner, apply и строгий current 13. + +**Acceptance Criteria:** +- Given логически эквивалентная опубликованная legacy-схема с другим ordinal, when выполняется shadow migration, then она завершается current 13 и сохраняет данные. +- Given любое семантическое catalog-отличие, when выполняется apply, then транзакция откатывается и core ledger не появляется. +- Given успешный локальный historical-dump shadow run, when fix пушится, then live deployment всё равно запускается только после проверки production backup. + +## Spec Change Log + +## Design Notes + +`ordinal_position` отражает физическую историю `ALTER TABLE`, но Crank обращается к колонкам по именам. Его исключение объединяет fresh и in-place layouts без принятия новых колонок или изменения их контрактов: список column items по-прежнему содержит имя, тип, UDT, nullability и default и сортируется детерминированно. + +## Verification + +**Commands:** +- `cargo test -p crank-registry --test integration integration::migrations::legacy_adoption -- --nocapture` — positive и fail-closed regression зелёные. +- `cargo test -p crank-registry` — полный crate suite зелёный. +- `scripts/check-rust-code-health.sh && scripts/check-community-scope.sh && cargo fmt --all --check && git diff --check` — repository gates зелёные. +- Production-equivalent Docker shadow run — restore custom dump, owner `NOSUPERUSER`, apply `0 → 13`, exact preflight current 13, representative row preserved. +- Финальный `admin-api` image собран локально как `crank/admin-api:legacy-fingerprint-hotfix`; migration binary запускается. Полный restore production backup локально невозможен без самого backup и deploy `.env`; этот fail-closed шаг остаётся обязательным в pipeline до live Compose. + +## Suggested Review Order + +**Нормализация контракта** + +- Канонизация сохраняет семантику колонок, исключая только физический ordinal. + [`schema_guard_legacy_v1.rs:134`](../../crates/crank-registry/src/migrations/schema_guard_legacy_v1.rs#L134) + +- Пересчитанный allowlist покрывает baseline, оба MCP-layout и extension ledger. + [`schema_guard_legacy_v1.rs:8`](../../crates/crank-registry/src/migrations/schema_guard_legacy_v1.rs#L8) + +**Историческая совместимость** + +- Fixture воспроизводит опубликованную последовательность DROP/ADD и реальные ordinal gaps. + [`legacy_adoption.rs:109`](../../crates/crank-registry/tests/integration/migrations/legacy_adoption.rs#L109) + +- Нестандартные sentinel-значения доказывают сохранность данных при миграции. + [`legacy_adoption.rs:149`](../../crates/crank-registry/tests/integration/migrations/legacy_adoption.rs#L149) + +- Явная проверка ordinal гарантирует воспроизведение production-дефекта. + [`legacy_adoption.rs:167`](../../crates/crank-registry/tests/integration/migrations/legacy_adoption.rs#L167) + +**Границы принятия** + +- Первый опубликованный MCP-layout отдельно проходит upgrade до current 13. + [`legacy_adoption.rs:238`](../../crates/crank-registry/tests/integration/migrations/legacy_adoption.rs#L238) + +- Семантический drift по-прежнему отклоняется до создания core ledger. + [`legacy_adoption.rs:328`](../../crates/crank-registry/tests/integration/migrations/legacy_adoption.rs#L328) diff --git a/_bmad-output/implementation-artifacts/sprint-status.yaml b/_bmad-output/implementation-artifacts/sprint-status.yaml new file mode 100644 index 0000000..07e19ed --- /dev/null +++ b/_bmad-output/implementation-artifacts/sprint-status.yaml @@ -0,0 +1,167 @@ +# generated: 08-08-2026 20:52 +# last_updated: 09-13-2026 03:29 +# project: crank +# project_key: NOKEY +# tracking_system: file-system +# story_location: _bmad-output/implementation-artifacts + +# ОПРЕДЕЛЕНИЯ СТАТУСОВ: +# ===================== +# Статус эпика: +# - backlog: работа над эпиком не начата +# - in-progress: эпик активно реализуется +# - done: все Story эпика завершены +# +# Переходы статуса эпика: +# - backlog → in-progress: автоматически при создании первой Story +# - in-progress → done: вручную после перехода всех Story в done +# +# Статус Story: +# - backlog: Story существует только в документе эпиков +# - ready-for-dev: создан отдельный файл Story +# - in-progress: разработчик реализует Story +# - review: Story готова к code review +# - done: Story завершена +# +# Статус ретроспективы: +# - optional: может быть проведена, но не обязательна +# - done: ретроспектива завершена +# +# Статус action item: +# - open: зафиксирован, но работа не начата +# - in-progress: выполняется +# - done: завершён +# +# ПРИМЕЧАНИЯ WORKFLOW: +# ==================== +# - Эпик переходит в in-progress при создании его первой Story +# - Story могут выполняться параллельно при наличии capacity, но зависимости из epics.md обязательны +# - По умолчанию следующая Story создаётся после done предыдущей для переноса lessons learned +# - Разработчик переводит Story в review, затем запускается code-review в свежем контексте +# - Ретроспектива добавляет action_items; sprint-status показывает незакрытые элементы + +generated: 08-08-2026 20:52 +last_updated: 2026-10-01 21:06 +project: crank +project_key: NOKEY +tracking_system: file-system +story_location: _bmad-output/implementation-artifacts + +development_status: + epic-1: done + 1-1-capability-inventory: done + 1-2-baseline-flows: done + 1-3-typed-configuration-foundation: done + 1-4-versioned-migration-authority: done + 1-5-canonical-request-trace-identity: done + 1-6-typed-metrics-registry: done + 1-7-immutable-lifecycle-operation: done + 1-8-rest-execution-boundary-errors: done + 1-9-outbound-rest: done + 1-10-lifecycle-auth-profiles-machine-keys: done + 1-11-master-key-identity-rotation: done + 1-12-admin-bootstrap-login-session-lifecycle: done + 1-13-immutable-agent-catalog: done + 1-14-approvals-side-effects: done + 1-15-invocation-history-usage: done + 1-16-mcp-tool-call: done + epic-1-retrospective: optional + epic-2: in-progress + 2-1-openapi-artifact-store: done + 2-2-openapi-source-metadata: done + # 2026-09-13: Epic 2 перенумерован в 2.1–2.14 без изменения scope/status. + # Историческое соответствие: epic-2-context.md; старые loop runs не возобновлять. + 2-3-artifact-filesystem-reconciliation: done + 2-4-artifact-claim-recovery: done + 2-5-openapi-upload-preview: done + 2-6-openapi-upload-ui-evidence: done + 2-7-openapi-normalizedir: done + 2-8-references-schema-composition: done + 2-9-http-contract: done + 2-10-security-schemes-secrets: done + 2-11-security-mapping-ui: done + 2-12-preview-partial-mode: done + 2-13-importplan-re-import: done + 2-14-openapi-support-matrix-regression-corpus: done + 2-15-openapi-guided-onboarding: backlog + epic-2-retrospective: optional + epic-3: in-progress + 3-1-mcp-revision-capabilities: backlog + 3-2-published-tools: backlog + 3-3-published-tools-structured-outcomes: backlog + 3-4-tool-call-progress-cancellation: backlog + 3-5-tool-catalog-change-signals: backlog + 3-6-typed-static-resource-drafts: ready-for-dev + 3-7-static-resource-versions: backlog + 3-8-static-resources-mcp: backlog + 3-9-resources-ui: backlog + 3-10-rest-backed-resource-templates: backlog + 3-11-rest-backed-resources-runtime: backlog + 3-12-prompt-drafts-preview: backlog + 3-13-prompt-publication-binding: backlog + 3-14-published-prompts-mcp: backlog + 3-15-prompt-import-export-ui: backlog + 3-16-prompts-published-resources: backlog + 3-17-mcp-completion: backlog + 3-18-mcp-server-logging: backlog + 3-19-resource-prompt-change-signals: backlog + 3-20-mcp-compatibility-matrix: backlog + epic-3-retrospective: optional + epic-4: backlog + 4-1-execution-mode-admission-limits: backlog + 4-2-durable-tasks: backlog + 4-3-tasks-leases-fencing: backlog + 4-4-retry-cancellation-outcome-unknown: backlog + 4-5-task-input-updates: backlog + 4-6-task-outcome-reconciliation: backlog + 4-7-mcp-task-operations-fallback: backlog + 4-8-task-management-ui: backlog + 4-9-task-recovery-ui: backlog + 4-10-task-capacity-recovery-envelope: backlog + epic-4-retrospective: optional + epic-5: backlog + 5-1-request-id-trace-id-runtime: backlog + 5-2-trace-admin-ui: backlog + 5-3-browser-observability: backlog + 5-4-traces-errors-glitchtip: backlog + 5-5-telemetry: backlog + 5-6-telemetry-loss-capacity-envelope: backlog + 5-7-production-technical-metrics-coverage: backlog + 5-8-dau: backlog + 5-9-prometheus-integration: backlog + 5-10-notification-gateway-apprise: backlog + 5-11-grafana-dashboards-trace-links: backlog + 5-12-slo-rules-dashboards: backlog + 5-13-application-alert-delivery: backlog + epic-5-retrospective: optional + epic-6: backlog + 6-1-versioned-load-scenarios: backlog + 6-2-dau-arrival-profile: backlog + 6-3-load-run-safety-plan: backlog + 6-4-load-runner: backlog + 6-5-live-statistics-run: backlog + 6-6-immutable-releases: backlog + epic-6-retrospective: optional + epic-7: backlog + 7-1-production-configuration-contract: backlog + 7-2-schema-evolution-n-n-1-compatibility: backlog + 7-3-minimal-production-deployment-profiles: backlog + 7-4-non-loopback-production-exposure: backlog + 7-5-offline-production-bundle: backlog + 7-6-production-containers-process-boundaries: backlog + 7-7-backup-backupmanifest: backlog + 7-8-restore-key-recovery: backlog + 7-9-single-instance-upgrade-rollback: backlog + epic-7-retrospective: optional + epic-8: backlog + 8-1-immutable-rc-evidence-manifest-contract: backlog + 8-2-capability-inventory-ci-gates: backlog + 8-3-versioned-manual-regression: backlog + 8-4-compatibility-matrices: backlog + 8-5-rc: backlog + 8-6-72-soak-recovery-qualification: backlog + 8-7-security-release-qualification: backlog + 8-8-incident-runbooks: backlog + 8-9-30-burn-in-readiness-page: backlog + 8-10-habr-release-gate: backlog + epic-8-retrospective: optional diff --git a/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/.memlog.md b/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/.memlog.md new file mode 100644 index 0000000..cadc9da --- /dev/null +++ b/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/.memlog.md @@ -0,0 +1,68 @@ +--- +scope: Production-ready Crank Community across FR-1..FR-54 +purpose: Build substrate for architecture, features, epics, implementation, and QA +altitude: initiative +updated: 2026-08-03T19:30 +--- + +- (decision) Fast path selected: draft the complete architecture spine with explicit assumptions for later correction. +- (decision) The architecture spine is the only requested deliverable; no deck, C4 package, or expanded solution-design document is required. +- (constraint) The final PRD and its confirmed decisions bind this architecture; architecture may choose mechanisms but may not weaken FR/NFR/Release Gate outcomes. +- (constraint) Brownfield reality is authoritative for existing boundaries: ratify established conventions rather than invent a replacement architecture. +- (decision) Adopt a hexagonal modular monolith with explicit control-plane and execution-plane composition roots; binds all FRs and prevents microservice proliferation or inward dependencies on transport/storage frameworks. +- (decision) Keep crank-core as framework-free domain and ports, crank-registry as PostgreSQL adapter, crank-runtime as Operation execution application layer, protocol adapters at the edge, and apps as the only composition roots; binds FR-1..FR-45 and prevents cyclic or transport-owned business logic. +- (decision) Model Operation, Resource, and Prompt as separate versioned aggregates sharing CapabilityKind, CapabilityRef, lifecycle, sensitivity and publication contracts; AgentVersion binds exact published refs and exposes one immutable catalog revision; binds FR-1, FR-4, FR-15..FR-18 and prevents EAV blobs, draft leakage and independently drifting lifecycle rules. +- (decision) Dynamic Resources may execute only a pinned read-safe GET/HEAD Operation through RuntimeExecutor; Prompts are pure deterministic renderers over pinned Resource versions with no code execution; binds FR-16 and FR-18 and prevents safety bypass or hidden mutable dependencies. +- (decision) PostgreSQL 16 is the sole source of truth for configuration, published catalogs, approvals, idempotency, Tasks, Load Runs, business events and safety state; Valkey 8 is optional rebuildable acceleration only; binds FR-1..FR-45, NFR-R2 and NFR-S7 and prevents split-brain correctness or silent safety degradation. +- (decision) Serve MCP 2026-07-28 stateless and the 2025-11-25 and 2025-06-18 session-based revisions through version-specific transport/lifecycle adapters over shared method services; binds FR-13..FR-20 and NFR-C2 and prevents protocol-version branches from leaking into capability and execution domains. +- (decision) Normalize Tools, Resources, Prompts, completion, progress, cancellation and notifications into internal service contracts, and advertise only behavior implemented for the negotiated revision; binds FR-13..FR-20 and prevents capability overclaiming. +- (decision) Implement durable Tasks in a new crank-tasks application crate and task-worker composition root; crank-core owns task types and TaskStore port, crank-registry implements persistence, and crank-tasks depends on RuntimeExecutor through an execution port; binds FR-21..FR-26 and prevents background work inside HTTP handlers or protocol sessions. +- (decision) Create Task record and dispatch intent in one PostgreSQL transaction before acknowledgement; claim queue rows with FOR UPDATE SKIP LOCKED, CAS lease expiry and monotonic fencing token; every write requires the current token; binds FR-22..FR-25 and prevents lost accepted work, double terminal commit and stale-worker mutation. +- (decision) Task delivery is at-least-once; persist attempt and idempotency fingerprint before outbound dispatch, automatically retry writes only with a verified upstream idempotency contract, and route ambiguous side effects to nonterminal outcome_unknown reconciliation; binds FR-23..FR-26 and prevents false exactly-once claims or unsafe repeats. +- (decision) Map the same internal Task lifecycle to the official io.modelcontextprotocol/tasks extension for 2026-07-28 and to the negotiated 2025-11-25 task shape; 2025-06-18 uses published synchronous fallback or explicit unsupported; binds FR-13, FR-20..FR-23 and prevents wire evolution from redefining durable semantics. +- (decision) Move shared immutable files into crank-artifacts: a bounded content-addressed local store keyed by SHA-256 with atomic write/fsync/rename and PostgreSQL metadata; binds FR-7..FR-12, FR-15..FR-18, FR-40, FR-43 and prevents mutable file references, traversal and inconsistent restore. +- (decision) OpenAPI preview resolves local and allowlisted external refs into an immutable content-addressed artifact graph; import commit consumes only the preview digest in one registry transaction; binds FR-7..FR-12 and prevents SSRF/TOCTOU, partial mutation and silent remote drift. +- (decision) Use one canonical W3C TraceContext generated or validated at browser/Admin/MCP boundaries; persist request_id and trace_id in Invocation, Task and Load Run records and continue the stored context across worker attempts; binds FR-27..FR-31 and NFR-O1 and prevents correlation forks across foreground/background paths. +- (decision) crank-observability alone owns redaction, W3C propagation, OTLP export, GlitchTip Sentry-envelope projection and per-destination disk-backed bounded spool; browser telemetry enters through a scrubbed same-origin Admin API relay; binds FR-27..FR-31 and prevents raw OTLP assumptions for GlitchTip, direct browser exfiltration and unobserved telemetry loss. +- (decision) Telemetry is fail-open after validated startup; each evicted or expired undelivered envelope atomically creates a PostgreSQL Telemetry Loss Record through an app-injected sink, while spool partitions and quotas stay outside PostgreSQL and artifact safety reserve; binds FR-29..FR-31 and NFR-O2 and prevents backend outage from breaking requests or silently losing evidence. +- (decision) crank-metrics exclusively defines low-cardinality technical/business metric names, labels and buckets; exact activation/adoption uniqueness is stored as PostgreSQL events and daily rollups, then exposed only as aggregates; binds FR-32..FR-35 and prevents identifier cardinality and inaccurate DAU inference. +- (decision) Ship Prometheus scrape/rules and provisioned Grafana dashboards as versioned deployment assets; metrics listeners use a separate credential and Grafana reads Prometheus plus read-only PostgreSQL rollups where exact business aggregates are required; binds FR-32..FR-35 and prevents dashboard drift or high-cardinality Prometheus workarounds. +- (decision) Run load generation in a separate load-runner process using the public MCP endpoint and immutable Scenario version; PostgreSQL owns Run/lease/stop state and a reserved independent control connection enforces heartbeat, hard ceilings and kill switch; binds FR-36..FR-40 and prevents self-measurement bias, arbitrary-target load and a saturated data plane blocking emergency stop. +- (decision) All secret-using processes validate the same master-key fingerprint/epoch from PostgreSQL at startup and readiness; ciphertext carries key version and rotation is transactional re-encryption with old-key revocation evidence; binds FR-3, FR-36..FR-43 and prevents partial-key deployments and unrecoverable restore. +- (decision) Replace mutable baseline-only migration behavior with one checksummed append-only core sequence, expand/migrate/contract compatibility and a dedicated migrate command under transaction advisory lock; runtime processes verify compatible schema but never apply migrations; binds FR-43 and NFR-C3 and prevents concurrent schema owners, modified history and unsafe rollback. +- (decision) Introduce a leaf crank-config crate as the canonical typed configuration schema and validator; apps compose dependencies from it, generated examples/docs derive from it, and library crates do not read environment variables; binds FR-41..FR-45 and prevents parsed/documented/Compose drift. +- (decision) Production topology is ui, admin-api, mcp-server, task-worker, load-runner, PostgreSQL and optional Valkey, with an optional isolated observability profile containing Prometheus, Grafana and GlitchTip on its own storage; minimal profile preserves product correctness without external telemetry services; binds FR-41..FR-45 and prevents observability dependencies from entering product readiness. +- (decision) Use single-instance drain/restart: stop admission and new claims, checkpoint/lease accepted work, bound foreground drain to 30 seconds, flush telemetry to durable spool, and require N/N-1 schema/task envelope reads during rollback window; binds FR-23, FR-31, FR-43..FR-44 and NFR-R3 and prevents rolling-update claims the Community topology cannot prove. +- (decision) Preserve the Alpine/concatenated UI architecture; all mutations use Admin API DTOs with stable machine error_code plus request_id/trace_id, stale-response identity guards, and no direct PostgreSQL/MCP/GlitchTip access; binds FR-1..FR-45 and prevents a frontend rewrite, cross-boundary writes and correlation loss. +- (decision) Release evidence is immutable and content-addressed: Capability Inventory, protocol/import matrices, load/recovery/security results and environment/config/image digests are indexed by one Evidence Manifest tied to the RC digest; binds FR-12, FR-20, FR-40..FR-54 and prevents documentation-only gates or evidence from another artifact. +- (version) Verified architecture seed on 2026-08-03: Rust 1.96.1 / Edition 2024 / MSRV 1.96, Axum 0.8, Tokio 1, SQLx 0.9, Reqwest 0.12, OpenTelemetry 0.32, Sentry 0.49, metrics 0.24.6, PostgreSQL 16, Valkey 8, Node 22, Alpine 3.15.12, Playwright 1.61.1. +- (version) Verified MCP compatibility seed: current 2026-07-28 stateless protocol plus 2025-11-25 and 2025-06-18; official Tasks extension identifier io.modelcontextprotocol/tasks is isolated behind the MCP adapter. +- (constraint) No independent paid or cloud backend is required; all data and telemetry remain operator-owned and outbound telemetry is opt-in. +- (constraint) Reference Deployment, SLOs, release gates and ceilings from the final PRD are binding and architecture mechanisms may strengthen but not weaken them. +- (decision) Reconciliation amendment: MCP support is a feature-freeze matrix of latest stable plus two prior stable revisions, while current 2025-03-26 compatibility remains until an evidence-backed deprecation gate; release candidates/extensions never become the sole path for a critical Tool. +- (decision) Reconciliation amendment: ratify crank-community-mcp and crank-community-auth as brownfield composition-support adapters that may currently depend on concrete registry/runtime adapters; the dependency diagram must show these real edges and forbid them from lower layers rather than pretending they are already inverted. +- (decision) Add a unified OutboundPolicy and execution-pipeline invariant for Admin test, MCP Tool, dynamic Resource and Task paths: actual-address validation on every connection, redirect revalidation, system proxy disabled by default, and bounded body/response/deadline/concurrency. +- (decision) Add a capability publication validator for Resources and Prompts covering typed static/dynamic forms, exact dependency versions, DAG/root/template validation, MIME/size limits, secret scan and effective sensitivity policy. +- (decision) Reconciliation amendment: OpenAPI pipeline is ParsedDocument to typed NormalizedIR plus complete Findings to immutable ImportPlan to idempotent transactional Apply; every construct is preserved or explicitly unsupported/blocking and raw credentials never enter artifacts or plans. +- (decision) Add execution admission and approval invariants: synchronous executions, durable Tasks and queue records remain distinct; global/per-Agent/per-Tool bounded fairness and deadlines precede both sync/background paths; approvals deduplicate by full scope and input fingerprint with conditional terminal transitions. +- (decision) Reconciliation amendment: input_required updates use versioned schema plus fingerprint/CAS; identical replay returns prior transition, conflicting replay is rejected, and TTL expiry cannot dispatch a new side effect. +- (decision) Reconciliation amendment: production telemetry defaults to 100 percent generation, 7-day trace and 30-day error retention, delivery latency at least 99.99 percent, 25-hour completeness for outage up to 24 hours, and a 30-hour measured-p95 spool at 100 RPS plus a 250 RPS five-minute burst; GlitchTip remains a mandatory tested default path. +- (decision) Reconciliation amendment: exact business rollups are exported through the typed Prometheus surface; Grafana queries Prometheus and reaches traces through exemplars/external URLs, never trace-id labels or direct product-table coupling. Non-loopback metrics uses a dedicated credential. +- (decision) Reconciliation amendment: LoadAuthorizationPlan contains DAU assumptions, load-test-safe evidence, sandbox/test credential/quota/cleanup for writes, production flag with repeated confirmation, dead-man and control readiness; immutable ceilings are 1000 RPS, 512 VU, two hours and ten million iterations. +- (decision) Add consistent backup and verified restore: BackupManifest binds snapshot time, PostgreSQL WAL LSN, artifact checksums, config digest and external protected master-key reference; RPO at most five minutes and RTO at most thirty minutes end only after a real MCP call using encrypted auth. +- (decision) Add Admin identity and web boundary: community-auth owns one-time bootstrap, login backoff, sessions and CSRF lifecycle; PostgreSQL owns revocation/audit; TLS, trusted-proxy allowlist, secure cookies, deny CORS and security headers are production prerequisites; offline recovery is local-only and revokes sessions. +- (decision) Add signed offline deployment artifact: digest-pinned images, Compose/config, SBOM, licenses and docs; non-root/minimal privilege/read-only checks, no Critical/High vulnerabilities, deny-by-default egress, and air-gapped fresh install/upgrade are release evidence. +- (decision) Reconciliation amendment: Reference Deployment is Linux x86_64, 4 vCPU, 8 GiB, SSD at least 100 GB/3000 IOPS/100 MB/s, 1 Gbit/s, PostgreSQL 16 and Valkey 8 with 30 percent headroom; load generation and observability have separate budgets. +- (decision) Reconciliation amendment: migration consolidation imports and verifies legacy core, MCP and extension ledgers without modifying baseline v1/checksum; extension migrations gain checksums and the dedicated migration command becomes sole writer only after compatibility transition. +- (decision) Reconciliation amendment: new artifact refs are opaque content-addressed refs; legacy absolute file refs remain read-compatible during a digest-verified migration and are never rewritten before verification. +- (decision) Reconciliation amendment: Evidence Manifest is signed and schema-validated, binds commands, raw results, owner, RC digest, 72-hour soak and 30-day burn-in; gate fails closed on missing/stale/mismatched evidence and requires executable Community guardrails/project context updated without allow-marker bypass. +- (decision) Add dataset retention policy: History, Tasks, Load Runs, traces, errors and metrics have separate typed retention; published-version audit and signed release evidence remain immutable, and archive verification precedes deletion where required. +- (decision) Reviewer amendment: crank-core owns the versioned ProductEvent schema and TelemetryLossSink port; apps emit typed events, registry persists them, and telemetry loss deduplicates by service/destination/spool-record id. +- (decision) Reviewer amendment: artifact publication writes and verifies immutable bytes first, then commits PostgreSQL metadata/ref ownership; unreferenced bytes are swept only after a grace period, and referenced bytes delete only through retention-safe reference counting. +- (event) spine finalized +- (decision) Final reviewer amendment: every telemetry spool uses a dedicated quota-reserved persistent volume outside PostgreSQL/artifact reserve, write-ahead fsync before acceptance, crash recovery before export, least-privilege ownership and encryption-at-rest inherited from the deployment volume. +- (decision) Final reviewer amendment: load-runner exposes a non-networked local operator CLI over a permission-restricted Unix control socket on a reserved runtime/control path; stop halts new dispatch immediately and handles in-flight work by immutable Run policy with durable/local audit fallback. +- (decision) Final reviewer amendment: Logs, Task and Load Run UI must search/copy request and trace IDs and generate configured GlitchTip deep links, while Telemetry Loss Record or backend outage suppresses any claim that the trace is externally available; one E2E proves the path. +- (decision) Final reviewer amendment: release evidence signatures use a repository-pinned release trust policy containing public key IDs, validity and revocation; protected offline/CI private keys sign manifests, rotation is reviewed and old keys remain verifiable for historical evidence. +- (decision) Final reviewer amendment: queued Task keeps pinned execution semantics from enqueue but claim revalidates authorization, Agent publication, key revocation, deadline and current admission capacity; invalidated work terminates without outbound dispatch. +- (event) late reviewer findings resolved; spine re-linted with zero findings and post-fix gate verdict GO diff --git a/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md b/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md new file mode 100644 index 0000000..29a4480 --- /dev/null +++ b/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md @@ -0,0 +1,449 @@ +--- +name: 'Crank Community Production Readiness' +type: architecture-spine +purpose: build-substrate +altitude: initiative +paradigm: 'hexagonal modular monolith with control-plane/execution-plane split' +scope: 'Production-ready Crank Community: current platform hardening, OpenAPI, modern MCP, durable Tasks, observability, load testing and release evidence' +status: final +created: '2026-08-03' +updated: '2026-08-03' +binds: + - FR-1..FR-54 +sources: + - '../../prds/prd-crank-2026-08-03/prd.md' + - '../../prds/prd-crank-2026-08-03/addendum.md' + - '../../../project-context.md' + - '../../../../docs/architecture.md' + - 'https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/' + - 'https://modelcontextprotocol.io/seps/2663-tasks-extension' + - 'https://modelcontextprotocol.io/extensions/tasks/overview' + - 'https://www.postgresql.org/docs/16/sql-select.html' + - 'https://opentelemetry.io/docs/collector/resiliency/' + - 'https://glitchtip.com/documentation/performance/' +companions: [] +--- + +# Architecture Spine — Crank Community Production Readiness + +## Design Paradigm + +Crank remains a **hexagonal modular monolith** distributed as several process-level composition roots. `admin-api` owns the control plane, `mcp-server` owns the public execution plane, and isolated workers own durable/background work. They share domain contracts and PostgreSQL, but never call each other through private HTTP APIs. Brownfield composition-support crates remain explicit: `crank-community-mcp` and `crank-community-auth` currently wire concrete adapters below the app binaries and are not reusable inner layers. + +```mermaid +flowchart TB + Apps["Composition roots\napps/*"] + MCPFacade["MCP composition support\ncrank-community-mcp"] + AuthFacade["Auth composition support\ncrank-community-auth"] + UseCases["Application services\nruntime · tasks · load · import"] + Rest["REST adapter\ncrank-adapter-rest"] + Registry["PostgreSQL adapter\ncrank-registry"] + Core["Domain and ports\ncrank-core"] + Schema["Pure contracts\nschema · mapping"] + Metrics["Metric leaf\ncrank-metrics"] + Obs["Observability edge\ncrank-observability"] + InfraLeaf["Infrastructure leaves\nconfig · artifacts"] + + Apps --> MCPFacade + Apps --> AuthFacade + Apps --> UseCases + Apps --> Registry + Apps --> Obs + Apps --> InfraLeaf + MCPFacade --> Registry + MCPFacade --> UseCases + MCPFacade --> Rest + MCPFacade --> Core + MCPFacade --> Metrics + AuthFacade --> Registry + AuthFacade --> Core + UseCases --> Rest + UseCases --> Core + UseCases --> Schema + UseCases --> Metrics + Registry --> Core + Registry --> Schema + Rest --> Core + Rest --> Metrics + Obs --> Metrics +``` + +Arrows mean “may depend on”. `crank-core`, `crank-metrics`, `crank-config` and `crank-artifacts` are leaves with the narrower dependencies defined by their manifests; `crank-observability` may depend only on `crank-metrics`. `crank-registry` never depends on runtime, REST or observability; runtime/application crates never depend on registry implementations; reusable crates never depend on `apps/*`. Existing boundary scripts are extended for every new crate and run as a mandatory CI gate. + +## Invariants & Rules + +### AD-1 — [ADOPTED] Hexagonal modular monolith + +- **Binds:** all +- **Prevents:** microservice proliferation, cyclic dependencies and business rules in Axum/SQLx handlers. +- **Rule:** domain types and external-dependency ports live in `crank-core`; reusable use cases live in application crates; SQLx, Axum, transport and environment wiring remain adapters or composition concerns. Process apps and the explicitly named brownfield `crank-community-mcp`/`crank-community-auth` composition-support crates may wire concrete adapters; no inner or new reusable crate may do so. Internal process collaboration uses shared ports and durable state, not private service-to-service HTTP. + +### AD-2 — Versioned capability model and published catalog + +- **Binds:** FR-1, FR-4, FR-14..FR-18, FR-33 +- **Prevents:** draft leakage, mutable published behavior and a schema-less “universal capability” blob. +- **Rule:** Operation, Resource and Prompt are separate typed aggregates with a shared `CapabilityKind`, `CapabilityRef`, lifecycle, sensitivity and publication contract. Every published version is immutable. `AgentVersion` binds exact published refs; publication atomically creates one immutable catalog snapshot and monotonically increasing `catalog_revision`. MCP reads only that snapshot. + +### AD-3 — Resource and Prompt execution boundary + +- **Binds:** FR-15..FR-19, FR-27, FR-32 +- **Prevents:** a read capability bypassing SSRF/auth/idempotency controls or a Prompt executing arbitrary code. +- **Rule:** Resource kinds are static text/JSON/binary or REST-backed URI template. A dynamic Resource can reference only a pinned, published, read-safe `GET`/`HEAD` Operation and executes it through `RuntimeExecutor`. Prompts are parameterized system/user/assistant message templates; rendering is deterministic and side-effect free, and each dependency is an exact Published Resource Version. Before publication one validator checks dependency DAG, URI-template/root traversal, arguments, MIME/size, secret findings and effective sensitivity/access; any unresolved or secret-bearing fallback blocks publication. + +### AD-4 — [ADOPTED] PostgreSQL correctness, optional Valkey acceleration + +- **Binds:** FR-1..FR-45, NFR-R2, NFR-S7 +- **Prevents:** split-brain state, lost accepted work and safety behavior that changes when cache is lost. +- **Rule:** PostgreSQL 16 is authoritative for configuration, published catalogs, approvals, idempotency, Tasks, Load Runs, business events and safety state. Valkey 8 may accelerate cache, rate limiting, wake-up and coordination projections only. Every Valkey structure is reconstructible from PostgreSQL; PG-only mode remains correct and any path without a safe fallback fails closed. + +### AD-5 — Version-isolated MCP multi-revision adapters + +- **Binds:** FR-13..FR-20, FR-21, NFR-C2 +- **Prevents:** transport-era assumptions leaking into capabilities, release-candidate behavior becoming a stable promise and a protocol upgrade breaking existing clients. +- **Rule:** at feature freeze, Capability Inventory selects the official latest stable MCP revision plus its two previous supported stable revisions and records executable conformance evidence. One endpoint routes each revision into shared method services through version-specific lifecycle, header, pagination, notification and result adapters. Existing `2025-03-26` support remains until a separate evidence-backed deprecation gate. Release candidates and experimental extensions are isolated adapters and cannot be the only path for a critical Tool. + +### AD-6 — Complete MCP method services + +- **Binds:** FR-14..FR-20 +- **Prevents:** independently implemented handlers producing incompatible auth, pagination, cancellation or error semantics. +- **Rule:** Tools, Resources, Prompts, completion, progress, cancellation, logging and change signals each have one internal service contract enforcing Agent scope before protocol serialization. Version adapters map that contract to the negotiated stable method set. Deprecated, client-role and extension features remain explicit in the executable capability inventory; no critical state relies only on notification delivery. + +### AD-7 — Durable Task application boundary + +- **Binds:** FR-21..FR-26, NFR-R2, NFR-R5 +- **Prevents:** background futures tied to HTTP/SSE lifetime and protocol changes redefining durability. +- **Rule:** foreground parallel Executions, durable MCP Tasks and the internal dispatch queue are three different contracts. `crank-core` owns Task types and ports; `crank-tasks` owns lifecycle/use cases; `crank-registry` implements persistence; `task-worker` is the execution composition root. MCP/admin handlers only create, inspect, update, reconcile or cancel durable Tasks. Each selected protocol revision maps the internal state through its tested stable/extension adapter; clients without a compatible Task contract receive the Tool’s published synchronous fallback or explicit unsupported result. + +### AD-8 — Transactional dispatch, leases and fencing + +- **Binds:** FR-22..FR-25, NFR-P2, NFR-R3, NFR-R5 +- **Prevents:** acknowledged-but-missing tasks, duplicate terminal commits and stale-worker writes. +- **Rule:** Task record and dispatch intent commit in one PostgreSQL transaction before acknowledgement. Workers claim bounded batches with `FOR UPDATE SKIP LOCKED`; claim/renew/update use compare-and-swap on lease owner, expiry and a monotonic fencing token. Every progress/checkpoint/result write carries the current token. Terminal transition is a single conditional update from an allowed nonterminal state. `input_required` stores a versioned schema and update fingerprint: identical replay returns the prior outcome, conflicting replay returns conflict, and TTL expiry fails without a new dispatch. + +```mermaid +stateDiagram-v2 + [*] --> queued + queued --> working: fenced claim + working --> input_required: durable input request + input_required --> working: validated update + working --> completed: terminal CAS + working --> failed: terminal CAS + queued --> cancelled: accepted cancel + working --> cancelled: confirmed pre-dispatch cancel + working --> outcome_unknown: ambiguous side effect + outcome_unknown --> completed: reconciliation evidence + outcome_unknown --> failed: reconciliation evidence + outcome_unknown --> working: explicit confirmed retry + input_required --> failed: input TTL expired + completed --> [*] + failed --> [*] + cancelled --> [*] +``` + +### AD-9 — At-least-once and side-effect honesty + +- **Binds:** FR-2, FR-5, FR-21..FR-26 +- **Prevents:** false exactly-once guarantees and automated duplication of external side effects. +- **Rule:** persist attempt ID and idempotency fingerprint before outbound dispatch. Delivery is at-least-once; automatic retry/recovery of a write requires a verified upstream idempotency contract. Cancellation is cooperative. Lost certainty after dispatch becomes nonterminal `outcome_unknown`, blocks ordinary retry/cancel-as-success and exits only through evidence-bearing reconciliation or an explicitly confirmed new attempt. + +### AD-10 — Content-addressed artifacts and two-phase OpenAPI import + +- **Binds:** FR-7..FR-12, FR-15..FR-18, FR-40, FR-43 +- **Prevents:** path traversal, mutable external references, preview/commit TOCTOU and inconsistent restore. +- **Rule:** `crank-artifacts` stores bounded immutable bytes under opaque SHA-256 refs using atomic write, fsync and rename; PostgreSQL stores ownership, MIME, size, sensitivity and digest. Publication writes/verifies idempotent bytes first, then commits metadata and owning refs; unreferenced bytes are swept only after a grace period, and referenced bytes are removed only through retention-safe reference accounting. Legacy absolute `file://` refs remain read-compatible during a digest-verified migration and are not rewritten before verification. Import flows `ParsedDocument → typed NormalizedIR + complete Findings → immutable ImportPlan → transactional Apply`. Every source construct is preserved according to the support matrix or produces explicit unsupported/blocker evidence. Apply is deduplicated by plan digest/request key, executes the selected `skip`/`rename`/`new-version` policy atomically and never accepts raw credential values—only typed security metadata and optional `AuthProfileRef`. + +### AD-11 — One correlation identity across every boundary + +- **Binds:** FR-6, FR-22, FR-26..FR-31, FR-40, NFR-O1 +- **Prevents:** unrelated browser/server/worker traces and loss of diagnosis when the external backend is down. +- **Rule:** every browser, Admin and MCP ingress has a distinct validated `request_id` and canonical W3C `TraceContext`; invalid identities are replaced, never echoed. `traceparent` is strictly parsed; `tracestate` and `baggage` have explicit size budgets and an allowlist, and user values are not forwarded by default. System propagation overrides user mappings. Invocation, Task, attempt and Load Run records persist both IDs. A worker continues the stored parent context across the durable boundary, retaining the origin trace ID; each retry is a distinct child attempt span. + +### AD-12 — Durable, redacted telemetry delivery + +- **Binds:** FR-27..FR-31, FR-41, NFR-O2..NFR-O5 +- **Prevents:** secret leakage, assuming GlitchTip accepts raw OTLP, and silent loss during backend outages. +- **Rule:** only `crank-observability` owns redaction, W3C propagation, OTLP serialization, GlitchTip Sentry-envelope projection and an isolated per-process/per-destination disk spool. Each spool has a dedicated quota-reserved persistent volume outside PostgreSQL/artifact safety reserve, least-privilege ownership and deployment-volume encryption at rest; a record is fsynced before local acceptance, recovered before export after restart and acknowledged only after receiver success. The browser sends a scrubbed same-origin envelope to Admin API; it never owns a direct external DSN. Production generates 100% of traces, retains traces 7 days and errors at least 30 days, targets delivery ≥99.99% within 60 seconds and 100% completeness within 25 hours for an outage ≤24 hours; replay after recovery targets 5 minutes. Capacity evidence uses measured p95 serialized trace size and proves 30 hours at 100 RPS plus a 250 RPS five-minute burst, ≤5% p95 latency and ≤10% CPU overhead. Before eviction/expiry, the spool atomically records a durable local loss tombstone; the `crank-core::TelemetryLossSink` port persists it through registry with uniqueness on service, destination and spool-record ID, and the tombstone remains until acknowledgement. Production cannot pass its gate without the default tested GlitchTip path; telemetry remains fail-open for product requests after validated startup. + +### AD-13 — Typed metrics and local product analytics + +- **Binds:** FR-6, FR-32..FR-35, FR-39..FR-40 +- **Prevents:** high-cardinality Prometheus series and inaccurate DAU derived from scrape-time state. +- **Rule:** `crank-metrics` exclusively declares names, types, labels, buckets and recording calls. Labels are closed enums and never contain user/object/request/trace/URL/error text. `crank-core` owns the versioned typed `ProductEvent` vocabulary; apps emit it and registry persists/folds it idempotently into UTC daily rollups exposed through the typed Prometheus surface. Grafana queries Prometheus; metric-to-trace navigation uses exemplars/external URLs, never a `trace_id` label. Non-loopback scrape uses a dedicated credential that is not an Admin/MCP credential. Telemetry and product-metric egress are deny-by-default and require explicit opt-in. Versioned scrape configs, rules and dashboards are release assets. + +#### Application alert delivery — decision 2026-09-13 + +- **Provider-neutral boundary:** application producers and evaluator ingress adapters submit a versioned `NotificationMessage` to the common notification dispatcher, which calls the `NotificationSink` port. `crank-core` owns these framework-free types/port; the implementation follows existing app/library boundaries without requiring a new standalone service or crate. The message carries notification identity, logical route reference, bounded kind/severity/content, timestamps/expiry and safe correlation links; alert fingerprint and firing/resolved state are typed alert-specific fields. Apprise URLs, tags, keys, HTTP codes and payload shapes never enter the common contract or business code. +- **Adapter boundary:** `AppriseNotificationSink` is the first production implementation. Composition/configuration selects the sink and maps logical routes to provider-specific secret-backed destinations. Replacing it changes only the adapter and provider configuration, not producers, rule definitions, UI or common dispatcher policy. The port returns typed accepted/retryable/permanent/uncertain outcomes with redacted diagnostics; provider response classification stays inside the adapter. A recording/fault-injection sink proves substitutability without shipping a second provider. +- **Policy ownership:** common dispatch owns bounded admission/queue, retry/backoff/expiry, redaction and delivery accounting; adapters perform bounded delivery attempts and must not introduce independent unbounded retry. The alert evaluator owns alert grouping/silences/repeat state, translated at ingress into the canonical envelope. Queued envelopes remain provider-neutral, with versioned logical route bindings; configuration changes cannot silently reroute already queued messages to different recipients. Exactly-once delivery is not guaranteed. MCP protocol notifications remain separate from this operator-notification gateway; no generic messaging platform is added to scope. +- Apprise API is the self-hosted notification gateway, integrated over HTTP, not an embedded Python dependency. Rule evaluation remains in the Prometheus/Grafana alerting layer; Apprise delivers notifications, it does not replace SLO evaluation. The owning story pins and tests an explicit payload adapter to the selected evaluator; arbitrary raw webhook compatibility must not be assumed. +- Stateful destination configuration stays in the gateway/operator secret store; config keys, channel URLs/tokens and gateway credentials are sensitive. A configuration key is not authentication. Private network exposure plus authenticated ingress/trusted TLS proxy, fixed operator-controlled endpoint/routes, bounded redacted payloads and explicit external-egress opt-in are mandatory. No user-provided attachment URLs or runtime-selected notification targets. +- Notification dispatch is outside the synchronous product request path. Its integration contract owns stable alert fingerprints, firing/resolved state, grouping, repeat/silence policy and bounded queue/retry/expiry; ownership of these controls must be explicit in the selected evaluator/adapter, not presumed to exist in Apprise. Timeouts, partial/permanent failures and uncertain delivery remain distinguishable; no exactly-once or human-receipt guarantee. Failed delivery is locally diagnosable without recursive notification storms or changing product readiness. +- Crank owns application signals and their delivery integration. Host/VM/LXC, disk/network and infrastructure-service monitoring/remediation, including independent detection of a wholly unavailable Crank or notification stack, belongs to the infrastructure owner. Application-visible dependency failures remain diagnosable; this ownership boundary does not weaken safety/recovery or alter approved SLI exclusions. +- Delivery configuration/profile assets belong to Story 5.9; lifecycle, scope and end-to-end notification verification belong to Story 5.11. Gateway deployment is optional or replaceable by an operator-managed endpoint; no external channel is enabled automatically. Reference: [Apprise API integration contract](https://appriseit.com/api/integrations/). + +### AD-14 — Isolated, bounded load runner + +- **Binds:** FR-36..FR-40, NFR-P1..NFR-P4 +- **Prevents:** measuring an in-process shortcut, arbitrary-target load and loss of emergency control during saturation. +- **Rule:** `load-runner` is a separate process with a replaceable k6-compatible runner contract and invokes the public MCP endpoint from an immutable Scenario version. DAU conversion requires actions/session, sessions/user/day, activity window, think time and scenario mix. Before Start, Admin signs a `LoadAuthorizationPlan` containing exact capability versions, `load-test-safe` evidence and target policy; writes additionally require sandbox endpoint, separate test Auth Profile, quota and cleanup. Production mode requires an operator flag and repeated confirmation. The runner revalidates lease and reserved control capacity before dispatch. A non-networked local operator CLI reaches a permission-restricted Unix control socket on a separate reserved control runtime; unavailable control forbids Start, and heartbeat loss or operator stop halts new dispatch immediately. In-flight work drains or cancels exactly as pinned in the Run policy; control actions audit to PostgreSQL or a local durable fallback for later replay. Non-lowerable ceilings are 1,000 RPS, 512 VU, 2 hours and 10,000,000 iterations. + +### AD-15 — Shared master-key identity + +- **Binds:** FR-3, FR-10, FR-15..FR-18, FR-36..FR-43 +- **Prevents:** one process writing ciphertext another cannot decrypt and backups that restore metadata without secrets. +- **Rule:** every secret-using process validates the same non-secret master-key fingerprint and active epoch against PostgreSQL before readiness. Ciphertext carries key version. Rotation writes re-encrypted versions transactionally, verifies reads under the new key and records old-key revocation evidence; the key material itself never enters PostgreSQL, manifests, logs or diagnostics. + +### AD-16 — Single migration authority and rollback window + +- **Binds:** FR-43, NFR-R2, NFR-C1, NFR-C3 +- **Prevents:** concurrent schema owners, modified migration history and destructive rollback. +- **Rule:** `crank-registry` owns the target append-only, ordered, checksummed Community sequence. A consolidation migration first verifies and imports the legacy core, MCP-session and `RegistryExtension` ledgers without modifying baseline v1/checksum; legacy ledgers remain readable during transition and extension entries gain checksums. After consolidation, a dedicated migrate command is the sole schema writer and applies each change transactionally under a PostgreSQL advisory lock; service startup only verifies compatibility. Changes follow expand/migrate/contract, and application N reads schema and Task envelopes from N and N-1 until rollback closes. + +### AD-17 — One typed configuration contract + +- **Binds:** FR-31, FR-41..FR-45 +- **Prevents:** divergence among environment parsing, Compose, documentation and UI. +- **Rule:** leaf crate `crank-config` owns typed fields, defaults, bounds, sensitivity and cross-field validation. Apps receive validated config and compose dependencies; reusable libraries do not read environment variables. Compose examples and parameter reference are generated/checked against the schema. Unknown or unsafe production combinations fail startup; dependency health and schema/key compatibility fail readiness. + +### AD-18 — [ADOPTED] Self-hosted topology and lifecycle + +- **Binds:** FR-41..FR-45, NFR-R1..NFR-R4, NFR-S1..NFR-S7 +- **Prevents:** mandatory cloud dependencies, unproved rolling deployment and observability outages blocking the product. +- **Rule:** the correctness set is UI, Admin API, MCP Server, Task Worker, PostgreSQL and shared artifact storage; Load Runner is isolated/on-demand and Valkey is optional for correctness. The Reference Deployment is Linux x86_64 with Crank services, PostgreSQL 16 and Valkey 8 within 4 vCPU, 8 GiB RAM, SSD ≥100 GB/3,000 IOPS/100 MB/s and 1 Gbit/s while retaining ≥30% headroom. Load generation and the optional Prometheus/Grafana/self-hosted-GlitchTip profile have separate resource/failure budgets; external compatible endpoints are allowed. Upgrade is single-instance drain/restart: stop admission/claims, checkpoint work, bound foreground drain to 30 seconds, persist telemetry and restart. Rolling multi-instance upgrade is not claimed. + +### AD-19 — [ADOPTED] UI and boundary error contract + +- **Binds:** FR-1..FR-45, NFR-P5, NFR-C4 +- **Prevents:** a frontend rewrite, stale cross-object responses and errors without support correlation. +- **Rule:** retain Alpine.js and the existing concatenated `window.Crank*` modules. UI accesses product state only through Admin API and uses identity/revision guards on async responses. Logs, Task and Load Run screens search/copy `request_id`/`trace_id` and generate a deep link from validated operator configuration; a Telemetry Loss Record or unavailable backend suppresses any claim that the trace is present in GlitchTip. One cross-boundary E2E proves browser/API-or-MCP/runtime/upstream/local-history/deep-link correlation. Domain, persistence and wire DTOs remain distinct. Every safe boundary error has stable `error_code`, bounded localized message, `request_id` and `trace_id`; raw causes and payloads never cross the boundary. + +### AD-20 — Evidence belongs to the release artifact + +- **Binds:** FR-12, FR-20, FR-40, FR-46..FR-54 +- **Prevents:** documentation-only gates and combining evidence from different builds or environments. +- **Rule:** Capability Inventory, OpenAPI corpus, MCP matrix, load/soak/recovery/security results and manual sign-off are immutable content-addressed raw artifacts indexed by a signed, JSON-Schema-validated Evidence Manifest. A protected offline/CI release key signs; the verifier trusts only a protected-branch `release-trust.json` containing public key IDs, validity and revocation. Reviewed rotation adds the new key before use and retains old public keys for historical verification. The manifest binds commands, owner identity, signing-key ID, RC/image/config/topology digests, checksummed Reference Workload, exact raw counts/results, the 128-active/10,000-queued background variant with recovery ≤60 seconds, 72-hour soak and 30-day burn-in. Gate evaluation is fail-closed on a missing FR/SM item, invalid/untrusted/revoked signature, invalid schema, stale required evidence (>24 hours where freshness applies), or any digest mismatch. The passed digest must equal the published RC. First enabling work updates `project-context.md` and executable Community guardrails for Resources/Prompts/Tasks/Load Runs; allow-marker bypass is forbidden. + +### AD-21 — [ADOPTED] Unified outbound execution pipeline + +- **Binds:** FR-2, FR-5, FR-9, FR-16, FR-21..FR-25, FR-36..FR-38, NFR-S3..NFR-S4 +- **Prevents:** Admin tests, Resources, Tasks or redirects bypassing the hardened REST path. +- **Rule:** Admin test, MCP Tool, dynamic Resource and Task attempts all enter through `RuntimeExecutionRequest → crank-runtime → crank-adapter-rest`. A shared `OutboundPolicy` validates the actual resolved address at every connection and again after every allowed redirect, applies deny-before-allow host/IP policy, disables system proxy and implicit redirects by default, reserves system correlation headers, and enforces bounded request/response bytes, deadline, retries and concurrency. OpenAPI external refs use the same network policy with a narrower allowlist; Load Runner can target only Crank’s MCP endpoint. + +### AD-22 — Admin identity and web security boundary + +- **Binds:** FR-3, FR-41, FR-44, NFR-S1..NFR-S2 +- **Prevents:** default credentials, session fixation, spoofed proxy identity and browser cross-origin mutation. +- **Rule:** `crank-community-auth` owns one-time Admin bootstrap, login throttling/backoff, account/session/CSRF state machines and constant-shape authentication errors; PostgreSQL owns revocation and audit. Non-loopback production exposure requires TLS, an explicit trusted-proxy allowlist, Secure/HttpOnly/appropriate SameSite cookies, CSRF on state changes, deny-by-default CORS, session rotation/expiry and security headers. Offline recovery requires local operator access, never bypasses master-key protection and revokes all sessions/tokens. Invalid key/schema/security configuration fails startup or readiness. + +### AD-23 — Approval and execution admission gates + +- **Binds:** FR-5, FR-14, FR-21..FR-26, NFR-P2, NFR-R5, NFR-S4, NFR-S7 +- **Prevents:** duplicate approvals, unbounded work and sync/background semantics drifting apart. +- **Rule:** one `ExecutionAdmission` policy snapshot precedes synchronous and background execution and enforces global, per-Agent and per-Tool concurrency, bounded queues, fairness, deadline propagation and overload response with retry guidance. A queued Task pins published execution semantics at enqueue; at claim it revalidates authorization, Agent publication/archive status, credential revocation, deadline and current capacity. Invalidated work reaches a safe terminal/reconciliation state without outbound dispatch. Execution Attempt has its own lifecycle independently of Task. Approval identity is unique on workspace, Agent, Operation version and canonical input fingerprint; creation/deduplication, expiry, decision and recovery are PostgreSQL-authoritative conditional transitions. Mandatory safety-store failure is fail-closed and reflected in readiness. + +### AD-24 — Consistent backup, verified restore and retention + +- **Binds:** FR-6, FR-22, FR-29, FR-40, FR-43, NFR-R2..NFR-R4 +- **Prevents:** restoring PostgreSQL without matching artifacts/keys and claiming recovery before the product works. +- **Rule:** a `BackupManifest` binds snapshot time, PostgreSQL WAL LSN/PITR chain, artifact checksums, config digest and an opaque reference to separately protected master-key material; key bytes are absent. Production targets RPO ≤5 minutes and RTO ≤30 minutes. Restore completes only after a real MCP call through an Operation using an encrypted Auth Profile, and rotation evidence proves re-encryption plus old-key revocation. History, Tasks, Load Runs, traces, errors and metrics have separate typed retention; archive verification precedes required deletion, while Published Version audit and signed release evidence remain immutable. + +### AD-25 — Signed offline and hardened deployment artifact + +- **Binds:** FR-41, FR-42, FR-44, FR-54, NFR-S5..NFR-S6 +- **Prevents:** hidden cloud dependencies, mutable images and an unverified “offline” installation. +- **Rule:** Community production is installable by one documented command from a signed offline bundle containing digest-pinned images, Compose/config, SBOM, licenses and documentation. CI performs air-gapped fresh install and N-1 upgrade, default-deny egress verification, non-root/minimal-capability/read-only-filesystem checks where applicable and secret-dump tests. The release contains no unresolved Critical/High image/dependency finding; external telemetry is opt-in and never a correctness dependency. + +## Consistency Conventions + +| Concern | Convention | +| --- | --- | +| Rust namespaces | Domain nouns are singular modules; application actions are verbs; adapters use technology/protocol suffixes. Public module ownership follows the dependency diagram. | +| Identifiers | Typed newtypes internally, strings on wire; new request/task/execution/run IDs use UUIDv7 with validated bounded text. Existing persisted IDs are never rewritten. | +| Capability refs | `{kind, id, version}` only; draft refs cannot cross a publish boundary. Catalog cache keys include Agent ID/version and `catalog_revision`. | +| Dates and durations | UTC `timestamptz` in PostgreSQL, RFC 3339 on wire, integer milliseconds for MCP/config, seconds for Prometheus histograms. | +| Enums and JSON | Admin/internal wire enums are `snake_case`; MCP names/values follow the negotiated specification exactly. Unknown local input enum is rejected with `error_code`; JSON object ordering never carries meaning. | +| Pagination | Opaque, bounded cursor tied to owner scope and catalog/query revision; stable order is `(created_at, id)` unless the protocol defines another order. | +| Mutation | Multi-aggregate state transitions use one PostgreSQL transaction and conditional version/state predicates; no read-modify-write without CAS or a row lock. | +| Errors | Typed domain/application errors map once at HTTP/MCP boundaries to stable codes and safe messages; retryability is explicit, never inferred from text. | +| Auth scope | Every store/cache/task/idempotency key includes full workspace, Agent and authorization scope; “not found” does not reveal foreign metadata. | +| Observability | Spans and metrics use closed typed dictionaries; IDs live in traces/local records, never metric labels; payload capture is deny-by-default. | +| Events | Audit/product events use immutable name, schema version, occurred-at and idempotency key; consumers tolerate unknown additive fields. | +| Retention | Dataset-specific policy names the clock, terminal-state rules and archive/delete action; deletion cannot break Published Version audit or release evidence. | +| Configuration | Parse and validate once before serving; every duration/size field states its unit in the name; secrets use redacted wrappers; processes log only non-sensitive normalized settings. | +| Localization | New user-facing RU and EN strings land together and share the same machine `error_code`. | +| Tests | Each fixed defect adds the lowest-level regression plus an edge/contract test when the failure crossed a boundary. | + +## Stack + +| Name | Version | +| --- | --- | +| Rust toolchain / edition / MSRV | 1.96.1 / 2024 / 1.96 | +| Axum | 0.8 | +| Tokio | 1 | +| SQLx | 0.9 | +| Reqwest | 0.12 | +| OpenTelemetry | 0.32 | +| Sentry Rust SDK | 0.49 | +| `metrics` / Prometheus exporter | 0.24.6 / 0.18.3 | +| PostgreSQL | 16 | +| Valkey | 8 | +| Node.js | 22 | +| Alpine.js | 3.15.12 | +| Playwright | 1.61.1 | +| MCP protocol matrix | latest stable at feature freeze + N-1 + N-2; retain 2025-03-26 until deprecation gate | + +Prometheus, Grafana and GlitchTip container tags are digest-pinned in the RC Evidence Manifest after feature-freeze compatibility, license and vulnerability checks; their product versions are deployment inputs rather than Rust architecture contracts. + +At authoring, the brownfield MCP server supports `2025-03-26`, `2025-06-18` and `2025-11-25`. The researched `2026-07-28` stateless line and Tasks extension remain adapter candidates until their stable status is verified at feature freeze; the Evidence Manifest records the actual selected matrix. + +## Structural Seed + +```text +apps/ # additive target structure; existing entries are retained + admin-api/ # control plane, browser telemetry relay + mcp-server/ # versioned MCP transport composition root + task-worker/ # durable execution worker + load-runner/ # isolated MCP load generator and kill path + ui/ # existing nginx + Alpine UI +crates/ + crank-core/ # framework-free domain and ports + crank-community-auth/ # existing Admin/machine identity composition support + crank-community-mcp/ # existing MCP composition support and version adapters + crank-schema/ # existing schema validation contracts + crank-mapping/ # existing deterministic input/output mappings + crank-runtime/ # synchronous Operation execution pipeline + crank-tasks/ # Task lifecycle, claims and reconciliation use cases + crank-load/ # Scenario validation and load engine contracts + crank-import/ # pure OpenAPI parsing/normalization/findings + crank-registry/ # PostgreSQL records, queries and migrations + crank-artifacts/ # bounded content-addressed local artifact store + crank-config/ # typed configuration schema and validation + crank-adapter-rest/ # outbound REST adapter and network policy + crank-metrics/ # only metric schema/recorder owner + crank-trace/ # safe span stage and attribute vocabulary + crank-observability/ # exporters, redaction and durable telemetry spool + crank-test-support/ # shared deterministic test infrastructure +deploy/community/ + minimal/ # correctness set + production/ # resource limits, observability and release profile + prometheus/ # scrape, recording and alert rules + grafana/ # datasource and dashboard provisioning + backup/ # WAL/PITR, artifact and config backup/restore contracts +tests/ + openapi-corpus/ # versioned specifications and expected findings + mcp-conformance/ # protocol/client capability matrix + recovery/ # crash, partition, upgrade and restore matrix + release-evidence/ # manifest schema and evidence validators +``` + +```mermaid +flowchart LR + Browser[Browser] + Client[MCP clients] + UI[UI / reverse proxy] + Admin[Admin API] + MCP[MCP Server] + Worker[Task Worker] + Runner[Load Runner] + Operator[Local operator CLI] + Control[Root/operator-only Unix control socket] + PG[(Crank PostgreSQL 16)] + Art[(Artifact volume)] + Valkey[(Valkey 8 optional)] + Upstream[Allowed REST upstreams] + AdminSpool[(Admin spool)] + MCPSpool[(MCP spool)] + WorkerSpool[(Worker spool)] + RunnerSpool[(Runner spool)] + Prom[Prometheus] + Grafana[Grafana] + GT[GlitchTip] + GTStore[(GlitchTip storage)] + Ops[Migration / backup CLI] + Backup[(Protected backup storage)] + KeyStore[(Separate master-key backup)] + + Browser --> UI + UI -->|browser Admin API proxy| Admin + UI -->|MCP reverse-proxy route only| MCP + Client -->|MCP route| UI + Runner --> MCP + Operator --> Control + Control --> Runner + Admin --> PG + MCP --> PG + Worker --> PG + Runner --> PG + Admin --> Art + MCP --> Art + Admin -. acceleration .-> Valkey + MCP -. acceleration .-> Valkey + Worker -. wake-up .-> Valkey + Admin --> Upstream + MCP --> Upstream + Worker --> Upstream + Admin --> AdminSpool + MCP --> MCPSpool + Worker --> WorkerSpool + Runner --> RunnerSpool + AdminSpool --> GT + MCPSpool --> GT + WorkerSpool --> GT + RunnerSpool --> GT + GT --> GTStore + Prom -->|scrape| Admin + Prom -->|scrape| MCP + Prom -->|scrape| Worker + Prom -->|scrape| Runner + Grafana --> Prom + Ops --> PG + Ops --> Art + Ops --> Backup + Ops --> KeyStore +``` + +```mermaid +erDiagram + WORKSPACE ||--o{ OPERATION_VERSION : owns + WORKSPACE ||--o{ RESOURCE_VERSION : owns + WORKSPACE ||--o{ PROMPT_VERSION : owns + WORKSPACE ||--o{ AGENT_VERSION : owns + AGENT_VERSION ||--o{ AGENT_OPERATION_BINDING : freezes + AGENT_VERSION ||--o{ AGENT_RESOURCE_BINDING : freezes + AGENT_VERSION ||--o{ AGENT_PROMPT_BINDING : freezes + OPERATION_VERSION ||--o{ AGENT_OPERATION_BINDING : tool + RESOURCE_VERSION ||--o{ AGENT_RESOURCE_BINDING : resource + PROMPT_VERSION ||--o{ AGENT_PROMPT_BINDING : prompt + OPERATION_VERSION ||--o{ RESOURCE_VERSION : read_source + RESOURCE_VERSION ||--o{ PROMPT_DEPENDENCY : composes + PROMPT_VERSION ||--o{ PROMPT_DEPENDENCY : pins + AGENT_VERSION ||--o{ TASK : authorizes + TASK ||--o{ TASK_ATTEMPT : executes + LOAD_SCENARIO_VERSION ||--o{ LOAD_RUN : instantiates + AGENT_VERSION ||--o{ LOAD_RUN : targets +``` + +## Capability → Architecture Map + +| Capability / Area | Lives in | Governed by | +| --- | --- | --- | +| FR-1..FR-6 — current Operations, Agents, secrets, approvals, history | `crank-core`, `crank-runtime`, `crank-registry`, Admin/MCP apps | AD-1, AD-2, AD-4, AD-9, AD-15, AD-21..AD-24, conventions | +| FR-7..FR-12 — OpenAPI | `crank-import`, `crank-artifacts`, Admin API, registry transaction | AD-10, AD-20 | +| FR-13..FR-20 — modern MCP, Tools/Resources/Prompts | `crank-community-mcp`, core capability aggregates, runtime, artifacts | AD-2, AD-3, AD-5, AD-6, AD-21 | +| FR-21..FR-26 — concurrency and Tasks | `crank-tasks`, `task-worker`, registry TaskStore, runtime | AD-7, AD-8, AD-9, AD-11, AD-21, AD-23 | +| FR-27..FR-31 — traceability and GlitchTip | UI relay, `crank-trace`, `crank-observability`, local records | AD-11, AD-12, AD-19 | +| FR-32..FR-35 — technical/business metrics | `crank-metrics`, registry product events/rollups, Prometheus/Grafana assets | AD-13 | +| FR-36..FR-40 — Load Runs | `crank-load`, `load-runner`, registry LoadStore, public MCP endpoint | AD-4, AD-14, AD-15, AD-20, AD-21 | +| FR-41..FR-45 — deployment, offline, recovery, config | `crank-config`, registry migrator, Compose/scripts/docs | AD-15..AD-18, AD-22, AD-24, AD-25 | +| FR-46..FR-54 — testing and public Release Gate | CI suites, corpus/matrices, Evidence Manifest validators | AD-20 and every bound AD | +| NFR-P/R/S/O/C | all apps plus deployment/recovery/evidence assets | AD-4, AD-8..AD-25, conventions | + +## Deferred + +- Exact PostgreSQL tables, indexes, partitioning and archive thresholds are fixed in feature/epic design after production-size query plans; ownership and transactional invariants are already bound here. +- Exact Task polling intervals, lease durations, batch sizes and fairness weights are configuration/performance-tuning decisions bounded by PRD SLOs and hard limits. +- Exact Grafana panel layout and alert thresholds derive from accepted recording rules and burn-rate tests; metric ownership and SLI formulas cannot change there. +- Digest-pinned Prometheus, Grafana and GlitchTip image versions are selected at feature freeze and recorded in the Evidence Manifest after license/SBOM/security verification. +- S3-compatible artifact storage, multi-instance workers/API, rolling upgrades and HA PostgreSQL are post-launch extensions; their introduction must preserve ports, fencing, publication and rollback invariants. +- Multi-workspace/RBAC/SSO, non-REST upstream adapters, arbitrary distributed load targets and loads above built-in ceilings remain outside this release. +- MCP revisions published after feature freeze enter the next compatibility cycle; they receive a new version adapter and may not modify internal capability or Task semantics. diff --git a/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/reviews/review-adversarial-units.md b/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/reviews/review-adversarial-units.md new file mode 100644 index 0000000..e8abad7 --- /dev/null +++ b/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/reviews/review-adversarial-units.md @@ -0,0 +1,43 @@ +# Reviewer Gate — Adversarial unit compatibility + +## Verdict + +**GO после трёх исправлений.** Построены пары независимо реализуемых units; найденные shared-data/ownership holes закрыты в AD-10, AD-12 и AD-13. + +## Critical / High + +Нет открытых Critical/High findings. + +## Constructed incompatible pairs and disposition + +### Admin capability publisher vs artifact store + +До исправления обе стороны могли соблюдать AD-10, но выбрать противоположный порядок записи bytes/metadata и оставить dangling refs после crash. + +**Исправлено:** bytes пишутся и проверяются идемпотентно первыми; metadata/owner refs коммитятся после; orphan sweep имеет grace period, delete учитывает durable refs/retention. + +### Admin/MCP product event producers vs registry rollup + +До исправления разные apps могли придумать одинаково допустимые, но несовместимые event names/payload versions. + +**Исправлено:** `crank-core` является единственным владельцем versioned `ProductEvent` vocabulary; apps только эмитят typed events, registry сохраняет и сворачивает. + +### Per-process telemetry spool vs PostgreSQL incident sink + +До исправления каждый app мог выбрать свой deduplication key и создать дубли или потерять loss record при недоступной БД. + +**Исправлено:** `crank-core::TelemetryLossSink`; durable local tombstone живёт до acknowledgement, registry uniqueness использует service + destination + spool-record ID. + +## Pairs checked without findings + +- Capability publishers vs MCP catalog reader: exact Published refs, typed binding tables and atomic catalog revision converge. +- MCP version adapters vs Task engine: protocol state cannot alter internal Task semantics; unsupported clients use published fallback/error. +- Sync runtime vs Task worker: both pass the same admission policy and unified runtime pipeline; Execution Attempt remains separate from Task. +- Admin approval writer vs worker recovery: full-scope uniqueness and conditional PostgreSQL transitions prevent competing records. +- Load control vs saturated runner: signed plan, reserved control capacity, heartbeat and local kill path converge on one stop authority. +- Migrator N vs service N-1: ledger consolidation plus expand/migrate/contract and N/N-1 read window define compatible ownership. + +## Medium / Low tail + +- Canonical serialization/signature details for `LoadAuthorizationPlan` and Evidence Manifest belong in their feature specs; both must include schema version, digest and key identity to satisfy the existing signed-contract Rules. +- Concrete Task fairness algorithm can differ internally only if it meets one policy snapshot and PRD SLO evidence; cross-unit surface is already fixed. diff --git a/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/reviews/review-reality.md b/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/reviews/review-reality.md new file mode 100644 index 0000000..7bb6122 --- /dev/null +++ b/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/reviews/review-reality.md @@ -0,0 +1,30 @@ +# Reviewer Gate — Technology and reality check + +## Verdict + +**GO.** Все binding technology claims либо подтверждены текущим репозиторием, либо проверены по первичным официальным источникам; изменяемые внешние версии не превращены в постоянный архитектурный контракт. + +## Critical / High + +Нет открытых Critical/High findings. + +## Verified against repository + +- Rust 1.96.1, Edition 2024/MSRV 1.96 и версии Axum/Tokio/SQLx/Reqwest/OpenTelemetry/Sentry/metrics подтверждены root `Cargo.toml` и project context. +- PostgreSQL 16, Valkey 8, Node 22, Alpine.js 3.15.12 и Playwright 1.61.1 подтверждены deployment/UI manifests и project context. +- Текущий MCP server действительно принимает `2025-03-26`, `2025-06-18`, `2025-11-25`; это отражено без преждевременного удаления старой ревизии. +- Реальные module/dependency constraints подтверждены обоими boundary scripts и manifests; архитектура больше не разрешает `registry -> observability`. +- Legacy core/MCP/extension migration ledgers и absolute `file://` refs учтены переходными правилами. + +## Verified against official primary sources + +- PostgreSQL 16 документирует `FOR UPDATE SKIP LOCKED` как подходящий механизм для queue-like consumers и transaction advisory locks для application-defined serialization. +- MCP official material подтверждает stateless `2026-07-28` direction и `io.modelcontextprotocol/tasks`; spine корректно считает их candidate inputs до stable verification at feature freeze. +- GlitchTip официально принимает performance transactions/spans через Sentry-compatible envelopes и не является raw OTLP receiver; AD-12 использует отдельную projection. +- Prometheus pull model, low-cardinality instrumentation и Grafana exemplar/external-link flow согласуются с выбранным topology. + +## Medium / Low tail + +- Stable MCP matrix и container image versions обязательно перепроверяются в день feature freeze; это уже fail-closed input Evidence Manifest. +- k6-compatible обозначает сменный runner contract, а не непроверенную обязательную библиотеку; конкретный engine требует benchmark/evidence до реализации. +- Custom 30-hour spool является собственным компонентом Crank и требует fault/capacity tests; наличие OpenTelemetry Collector persistent queue не считается доказательством этого контракта. diff --git a/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/reviews/review-rubric.md b/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/reviews/review-rubric.md new file mode 100644 index 0000000..7b3f40e --- /dev/null +++ b/_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/reviews/review-rubric.md @@ -0,0 +1,74 @@ +# Reviewer Gate — Good-Spine Rubric + +## Verdict + +**PASS WITH FIXES.** The spine is unusually complete for initiative altitude: the paradigm is named, brownfield boundaries are mostly ratified, all FR/NFR areas are mapped, AD rules are generally enforceable, and Deferred does not hide a major architectural choice. The fixes below remove three real cross-unit divergences before finalization. + +Lint evidence: `lint_spine.py` passed with zero mechanical findings. + +## Critical + +None. + +## High + +### H-1 — Durable telemetry has no bound persistence envelope + +- **Touches:** AD-12, AD-18, AD-25, topology; FR-31 / NFR-O2a. +- **Problem:** AD-12 mandates a per-process durable disk spool, while AD-25 permits read-only container filesystems and AD-18 gives the correctness set a shared 100 GB disk/headroom envelope. The topology shows logical spools but does not bind persistent mounts, quota reservation, crash-consistent acknowledgement, permissions/encryption, or separation from PostgreSQL/artifact safety reserve. Independent app implementations can therefore be “durable” in incompatible ways, and an ephemeral/container-local spool would violate restart completeness. +- **Disposition:** **Autofix.** Bind either dedicated quota-reserved persistent volumes per process or one explicitly owned local collector/WAL boundary; state write-before-accept/recovery semantics, filesystem compatibility, and that the measured 30-hour budget is outside PostgreSQL/artifact reserve. + +### H-2 — Emergency Load Run stop is not independently reachable + +- **Touches:** AD-14, AD-19, deployment topology; FR-38..FR-39. +- **Problem:** AD-14 requires an independent local kill path and reserved control capacity, but AD-19 routes UI product state only through Admin API and the topology exposes no operator endpoint/CLI/signal path to `load-runner`. Builders can choose incompatible stop mechanisms, including one that fails exactly when Admin/worker pools saturate. +- **Disposition:** **Autofix.** Bind the independent operator surface and trust boundary (for example, local CLI/Unix socket or authenticated runner control listener), its authorization/audit behavior, and stop semantics for new versus in-flight work; show it in topology. + +### H-3 — UI ↔ GlitchTip trace navigation is mapped but not invariant + +- **Touches:** AD-11..AD-13, AD-19; FR-27..FR-30, especially FR-28. +- **Problem:** IDs are persisted and boundary errors carry them, but no AD requires Logs/Task/Load Run UI to search/copy a local Trace ID, generate a configured deep link, or suppress a false “available in GlitchTip” claim when a Telemetry Loss Record exists. The capability map is not an enforceable rule, so UI and backend units can satisfy their local contracts while the user's principal diagnosis path remains broken. +- **Disposition:** **Autofix.** Add this end-to-end navigation contract to AD-11 or AD-19, including backend-unavailable/loss-record behavior and the required cross-boundary E2E evidence. + +## Medium + +### M-1 — Admission policy timing for queued Tasks is ambiguous + +AD-23 does not say whether the persisted `ExecutionAdmission` snapshot is authoritative at enqueue, revalidated at claim, or both. Bind which changes (revocation, capability archive, limits, deadlines) invalidate queued work. **Disposition: discuss/autofix.** + +### M-2 — Topology contradicts the UI boundary + +The topology includes `UI --> MCP`, while AD-19 says UI accesses product state only through Admin API. Clarify whether this is merely reverse-proxy routing for external MCP clients or remove the edge. **Disposition: autofix.** + +### M-3 — Evidence signatures lack a trust-root owner + +AD-20 binds signatures and fail-closed verification but not who owns the signing key, how the verifier obtains/trusts it, or how rotation/revocation is represented. Two CI/release units could produce mutually unverifiable manifests. **Disposition: autofix in AD-20/AD-25.** + +## Low + +### L-1 — Current-technology evidence should be normalized + +The MCP Tasks source path in frontmatter is not the canonical extension host, and the 2026-07-28 line is still treated as an RC candidate at authoring. Preserve the safe feature-freeze gate, but record canonical official URLs/status and the verified-at date in the evidence/memlog. **Disposition: autofix metadata.** + +## Checklist Summary + +- Real divergence points: **pass with H-1..H-3 fixes**. +- Enforceability of ADs: **pass**, except the three contracts above and M-1. +- Deferred safety: **pass**; deferred tuning and later HA/adapters are bounded by existing invariants. +- Brownfield fit: **pass**; existing crate boundaries, MCP revisions, UI model and migration ledgers are acknowledged rather than erased. +- PRD coverage: **broadly pass**; FR-1..FR-54 and NFR families are mapped, with FR-28 requiring an actual invariant. +- Initiative operational dimensions: **pass** for deployment, offline operation, security, migrations, backup/restore, upgrade, observability, capacity and release evidence, subject to the physical spool and kill-path fixes. + +## Finalizer resolution + +Все findings применены до handoff: + +- **H-1:** AD-12 теперь фиксирует отдельные persistent quota-reserved volumes, write-ahead fsync/recovery/ack, permissions/encryption и изоляцию safety reserve. +- **H-2:** AD-14 и topology фиксируют local operator CLI → permission-restricted Unix socket → reserved runner control runtime, audit и stop semantics. +- **H-3:** AD-19 фиксирует search/copy/deep-link/loss-record behavior и обязательный cross-boundary E2E. +- **M-1:** AD-23 разделяет pinned enqueue semantics и claim-time authorization/publication/revocation/deadline/capacity revalidation. +- **M-2:** topology маркирует UI→MCP только как reverse-proxy route для MCP client, browser state идёт в Admin API. +- **M-3:** AD-20 фиксирует repository-pinned `release-trust.json`, protected private keys и rotation/revocation semantics. +- **L-1:** frontmatter содержит canonical Tasks extension URL; RC status остаётся non-binding до feature-freeze verification. + +**Post-fix verdict: GO.** diff --git a/_bmad-output/planning-artifacts/epics.md b/_bmad-output/planning-artifacts/epics.md new file mode 100644 index 0000000..2dcfbc9 --- /dev/null +++ b/_bmad-output/planning-artifacts/epics.md @@ -0,0 +1,5554 @@ +--- +stepsCompleted: + - step-01-validate-prerequisites + - step-02-design-epics + - step-03-create-stories + - step-04-final-validation +planningRevision: '2026-08-24-mcp-2026-07-28' +storyNumberingRevision: '2026-09-13-atomic-stories' +inputDocuments: + - prds/prd-crank-2026-08-03/prd.md + - architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md + - prds/prd-crank-2026-08-03/addendum.md + - ../specs/spec-crank/SPEC.md + - ../specs/spec-crank/traceability.md + - ../project-context.md +--- + +# crank - Epic Breakdown + +## Overview + +Этот документ содержит полную декомпозицию Crank Community Production Readiness на эпики и реализуемые stories на основе PRD, SPEC, Architecture Spine, технического addendum и project context. Отдельный UX design contract отсутствует в соответствии с выбранным Fast Path. Ревизия 2026-08-24 уточняет уже запланированные Resources, Prompts и background Tools и фиксирует адаптацию к опубликованной стабильной MCP `2026-07-28`, не создавая дублирующих эпиков. + +## Requirements Inventory + +### Functional Requirements + +FR-1: Администратор может создавать, тестировать, версионировать, публиковать, архивировать, импортировать и экспортировать Operations; Draft не меняет Published Version, а YAML upsert/roundtrip сохраняет wire-контракт и историю версий. + +FR-2: Crank выполняет REST Operations с mapping, authentication, timeout, retry, cache, idempotency, response limits и outbound/SSRF policy, сохраняя стадию ошибки и не раскрывая credentials или чувствительные payloads. + +FR-3: Администратор может безопасно создавать, ротировать и отзывать Auth Profiles, MCP keys и approval keys с одноразовым раскрытием raw value; общий master-key contract, one-time admin bootstrap, login protection и offline recovery предотвращают утечку и несанкционированное восстановление доступа. + +FR-4: Администратор собирает versioned Agent catalog только из точных Published Versions capabilities в direct или search mode; Draft и чужие capabilities не обнаруживаются, а смена каталога повышает revision. + +FR-5: Operation может требовать атомарное, изолированное и дедуплицируемое approval; продукт не обещает exactly-once внешний side effect без upstream idempotency. + +FR-6: UI предоставляет фильтруемые Invocation History и Usage по периоду, Agent и Operation с безопасными previews, outcome, percentiles, Request ID и Trace ID; CSV export соблюдает redaction. + +FR-7: OpenAPI preview до мутаций принимает bounded YAML/JSON upload, детерминированно показывает endpoints, mappings, conflicts, warnings и unsupported findings и не создаёт частичный результат без явно выбранного partial mode. + +FR-8: Importer сохраняет semantics стандартных REST methods, path/query/header/cookie parameters, всех успешных 2xx responses и JSON/form/multipart bodies; XML явно помечается unsupported, а 204 и multiple-success schemas обрабатываются корректно. + +FR-9: Importer разрешает local и allowlisted external references через immutable snapshot и безопасно обрабатывает composition, recursion, discriminators и limits без TOCTOU, crash или silent schema loss. + +FR-10: Importer распознаёт bearer/basic/api-key security schemes и связывает их с Auth Profile без raw secret; неизвестные и OAuth-specific schemes требуют явной ручной настройки. + +FR-11: При conflict/re-import администратор выбирает skip, rename или new version; apply атомарен и идемпотентен, а итоговый report перечисляет все created, updated, skipped и rejected endpoints. + +FR-12: Проект содержит versioned OpenAPI 3.0/3.1 и Swagger 2.0 support matrix и regression corpus минимум из 50 репрезентативных спецификаций; ≥95% Operations становятся actionable Draft, silent loss равен нулю, каждый defect получает fixture. + +FR-13: MCP endpoint поддерживает стабильную MCP `2026-07-28` и согласованное compatibility window предыдущих версий через изолированные adapters: современная stateless-линия использует обязательный `server/discover`, request-scoped metadata и не зависит от initialize/session lifecycle, а legacy session-линия сохраняется только как явно тестируемый compatibility path. + +FR-14: Tools list/call реализуют применимые pagination, structured content/errors, progress, cancellation и list-changed semantics без ложных terminal states и изменения published schema в рамках Agent revision. + +FR-15: Администратор может создавать, preview, тестировать, версионировать, публиковать, архивировать, импортировать, экспортировать и привязывать к Agent Resources; discovery/templates/read соблюдают read-only, sensitivity, MIME/size, secret-scan и access policies. + +FR-16: Resource поддерживает static text/JSON/binary и REST-backed URI templates; параметры, traversal, MIME, size, cache и failure behavior валидируются до публикации. + +FR-17: Администратор может создавать, preview, тестировать, версионировать, публиковать, архивировать, импортировать, экспортировать и привязывать к Agent parameterized Prompts; discovery/get валидируют типизированные arguments до rendering. + +FR-18: Prompt детерминированно компонует system/user/assistant messages и точные Published Resource Versions без arbitrary code; циклы, unpublished dependency или secret-bearing content блокируют публикацию. + +FR-19: Crank реализует применимые stable completion, server logging, progress и capability-change notifications в рамках negotiated client capabilities; notifications не являются единственным источником критического состояния, logging не раскрывает secrets. + +FR-20: Каждый production release публикует исполняемую MCP capability/protocol/client matrix для `2026-07-28` и утверждённого legacy window; matrix отдельно доказывает discovery/lifecycle, request metadata, Tools, Resources, Prompts, subscriptions/notifications и Tasks extension, а каждый stable contract получает supported/not-applicable/experimental/deferred status, причём применимый deferred является blocker. + +FR-21: Для Tool публикуется synchronous, background или adaptive execution mode с явным synchronous fallback либо unsupported outcome для клиента без Tasks; background не включается неявно. + +FR-22: Durable Task имеет scoped устойчивый ID, статусы queued/working/input_required/outcome_unknown/completed/failed/cancelled, progress, attempts и immutable terminal result; PostgreSQL-backed CAS leases и fencing исключают stale writes и duplicate terminal transitions. + +FR-23: Task record и dispatch intent атомарно сохраняются до acknowledgement и восстанавливаются после crash/restart; delivery — at-least-once, effectively-once side effect возможен только с idempotency contract и доказывается crash/partition matrix. + +FR-24: Оператор управляет global/per-Agent/per-Tool concurrency; bounded queues, fairness, timeouts и overload rejection предотвращают unbounded growth, измеряют queue wait/age и fail closed при отказе mandatory safety store. + +FR-25: Task policy задаёт attempts, backoff, deadline, cancellation, input update и reconciliation; write без upstream idempotency не ретраится автоматически после ambiguity, а outcome_unknown разрешается только по evidence или явно подтверждённым новым attempt. + +FR-26: UI позволяет фильтровать Tasks, видеть progress, attempts, IDs и trace, отменять разрешённые Tasks и безопасно повторять failures; destructive bulk action подтверждается и audited, outcome_unknown имеет отдельный reconciliation flow. + +FR-27: Каждый UI/Admin API/MCP ingress получает отдельные валидированные Request ID и W3C Trace ID, распространяемые через runtime, upstream и durable Task boundaries; системная correlation имеет приоритет, IDs сохраняются независимо от sampling. + +FR-28: UI показывает, копирует и ищет Request ID/Trace ID и формирует валидированный deep link в trace backend; e2e доказывает полный путь до upstream/history/backend, а outage не скрывает локальный ID. + +FR-29: Production profile отправляет redacted errors и performance traces в GlitchTip со 100% default sampling, trace retention 7 дней и errors ≥30 дней; delivery ≥99.99% за 60 секунд и 100% за 25 часов при outage ≤24 часов, а loss создаёт локальный Telemetry Loss Record. + +FR-30: Browser observability фиксирует navigation/API errors и spans, связывает их с server Trace ID, показывает support IDs пользователю, не отправляет sensitive data и полностью отключается оператором. + +FR-31: Telemetry queues/spools bounded, disk-backed и restart-safe; export failures, drops и saturation наблюдаемы, graceful shutdown flushes в пределах timeout, backend outage не меняет product response/readiness, а invalid startup config fail safe. + +FR-32: Prometheus получает typed low-cardinality metrics для traffic, errors, duration, saturation, workers/queues, DB/cache, MCP, capabilities, Tasks и telemetry; IDs, URLs и error text запрещены в labels, buckets документированы. + +FR-33: Crank локально и идемпотентно считает typed product events и UTC rollups для activation/adoption; DAU — уникальный Agent с валидным MCP request за UTC-день, admin activity отдельно, egress только opt-in. + +FR-34: Community distribution включает versioned Prometheus scrape/recording/alert rules, Grafana datasource и dashboards Overview, MCP/runtime, upstream, Tasks, DB/cache, funnel и Load Runs; non-loopback metrics endpoint имеет отдельную authentication. + +FR-35: Grafana показывает 30-дневные availability, latency, execution и Task-deadline SLO/error budgets с fast/slow burn alerts, документированными denominators/exclusions и ссылками на runbooks. Application alerts доставляются через self-hosted Apprise API; инфраструктурный мониторинг и устранение инфраструктурных сбоев принадлежат владельцу инфраструктуры, без ослабления application diagnostics/safety и SLI accounting. + +FR-36: Администратор создаёт versioned Load Scenario из Published Tools с mix, data, RPS/VU, duration, ramp и thresholds; точные versions и parameters фиксируются, credentials остаются refs, target должен быть load-test-safe. + +FR-37: UI преобразует DAU в arrival profile только из явно заданных actions/session, sessions/user/day, activity window, think time и mix и показывает assumptions и итоговую RPS curve. + +FR-38: Load Run ограничен capabilities текущей установки, admin permission, allowlist, confirmation и independent emergency stop; writes требуют sandbox/test credentials/quota/cleanup, production — operator flag, а hard ceilings равны 1000 RPS, 512 VU, 2 часам и 10 000 000 iterations. + +FR-39: UI в реальном времени показывает generation, completed/failed, latency percentiles, active workers, dropped iterations, queue wait и saturation; stop независимо прекращает новые dispatches и обрабатывает in-flight по pinned policy. + +FR-40: Load Run создаёт immutable human/machine-readable report с thresholds, fingerprint, release, graphs и Grafana/trace links; UI сравнивает одинаковые Scenarios между releases, bounded output сохраняет валидный UTF-8/JSON. + +FR-41: Community поставляет CI-validated minimal и production profiles, запускаемые одной командой без proprietary dependency; optional Prometheus/Grafana/GlitchTip profile заменяем совместимыми endpoints, ресурсы и ≥30% headroom документированы, non-loopback web exposure hardened. + +FR-42: Runtime, capabilities, telemetry и metrics работают без cloud dependency и phone-home; подписанный digest-pinned offline bundle с images, Compose/config, SBOM, licenses и docs проходит install/upgrade без внешней сети. + +FR-43: Versioned immutable migrations, preflight, backup/restore и single-instance drain/restart upgrade сохраняют N/N-1 compatibility; согласованный PG/artifact/config/key backup доказывает RPO ≤5 минут и RTO ≤30 минут реальным MCP call в трёх restore runs. + +FR-44: Production containers используют non-root, minimum privileges, health/readiness, graceful shutdown, resource limits, log rotation и read-only filesystem где возможно; Critical/High vulnerabilities отсутствуют, secrets не попадают в image/dumps/diagnostics. + +FR-45: Typed runtime schema, docs, environment examples, Compose и UI описывают один bounded configuration contract; CI выявляет undocumented/unused parameters и divergence legacy/canonical deployment. + +FR-46: Capability Inventory связывает каждый существующий и целевой UI/API/MCP flow с contract, owner и automated/manual evidence; test pyramid включает unit, integration/contract, real-stack E2E и negative security tests, а CI выполняет все quality/deployment smoke gates. + +FR-47: Перед RC выполняется versioned полный manual regression на production-like deployment по всем ключевым flows; blocked/not-run не считается pass, каждый defect связан с regression evidence. + +FR-48: Release проходит OpenAPI corpus, MCP protocol/client, PostgreSQL/Valkey и current stable Chromium/Firefox/WebKit matrices; MCP включает ≥3 representative clients и protocol harness, результаты публикуются с release notes. + +FR-49: Pre-release pipeline выполняет reproducible baseline/load/stress, 72-hour soak, restart/recovery и dependency-failure tests на фиксированном artifact; перед Habr тот же RC проходит неускоряемый 30-дневный supervised burn-in. + +FR-50: Public launch требует threat-model review, pinned fresh SAST/dependency/container/secret/license scans, redaction audit и negative tests SSRF/authz/idempotency и новых attack surfaces; реальных Critical/High findings нет. + +FR-51: Release содержит проверенные fresh-user quickstart, production/capability guides, matrices, limits, troubleshooting, metrics/dashboards/SLO и backup/restore/incident runbooks; каждый critical alert имеет diagnostics/recovery steps. + +FR-52: Один immutable RC artifact проходит все проверки без подмены digest; подписанный JSON-Schema Evidence Manifest связывает artifact/images/config/workload, команды, результаты, reviewers и freshness и валидируется fail closed. + +FR-53: До анонса публикуется readiness page, честно ограничивающая supported scope, limits, security model, compatibility и known non-blocking issues доказанной matrix. + +FR-54: Habr Release Gate открывается только при полном evidence FR-1..FR-53 и SM-2..SM-10 на одном RC; исключения для обязательной capability, Critical/High defect, SLO failure или неполного manual pass запрещены. + +### NonFunctional Requirements + +NFR-P1: Reference Deployment выдерживает 100 RPS смешанного MCP/runtime workload 30 минут и 250 RPS burst 5 минут без нарушения SLO. + +NFR-P1a: В каждую минуту 250 RPS burst product-caused success ratio ≥99.95%, saturation rejection ≤0.1%, а p95/p99 platform overhead остаются в NFR-P4. + +NFR-P1b: В каждую минуту 100 RPS steady Run product-caused success ratio ≥99.95%, saturation rejection ≤0.1%, а latency и queue wait/age остаются в заданных границах. + +NFR-P2: Система поддерживает ≥128 concurrent synchronous/background Executions и 10 000 queued Tasks без unbounded resource growth. + +NFR-P3: На Reference Deployment 2 000 Operations, 200 Agents, 500 active keys и 1 000 000 Invocation History records не вызывают функциональную деградацию. + +NFR-P4: Platform overhead при 10 ms stub upstream ≤50 ms p95 и ≤150 ms p99; catalog/resource/prompt discovery ≤150 ms p95. + +NFR-P5: Основные UI screens интерактивны ≤2 s p95 по локальной сети на production-size dataset. + +NFR-R1: Product-caused successful-request ratio ≥99.95%, control-plane availability ≥99.9% на 30-дневном окне с явно ограниченным maintenance. + +NFR-R2: Подтверждённые configuration changes, Published Versions, approvals и accepted Tasks не теряются при штатном или аварийном restart с исправным durable storage. + +NFR-R3: Graceful shutdown прекращает admission, завершает либо надёжно сохраняет принятую работу и укладывается в 30 секунд по умолчанию. + +NFR-R4: WAL/PITR disaster restore доказывает RPO ≤5 минут и RTO ≤30 минут на Reference Deployment реальным product probe. + +NFR-R5: Task начинает выполнение ≤5 секунд p95 в пределах NFR-P1, recovery зависших leases после restart ≤60 секунд. + +NFR-S1: Access default deny; workspace/Agent/capability isolation не раскрывает metadata чужого объекта. + +NFR-S2: Secrets encrypted at rest, не возвращаются после создания/ротации и исключены из logs, traces, metrics, reports и exports. + +NFR-S3: Outbound policy применяется после DNS resolution на каждом connection; redirects и system proxy выключены по умолчанию. + +NFR-S4: Bounded input/body/response/concurrency/queue/cardinality limits предотвращают unbounded resource consumption. + +NFR-S5: Production release не содержит известных Critical/High vulnerabilities или Critical/High security findings. + +NFR-S6: Usage и telemetry не покидают закрытый контур без явного admin opt-in. + +NFR-S7: Отказ mandatory coordination/approval/idempotency store переводит зависимый safety path в fail-closed состояние без silent disable. + +NFR-S8: Previews, events, diagnostics и JSON reports bounded, сохраняют валидный UTF-8/JSON и проходят malformed/oversized negative tests. + +NFR-O1: 100% UI/Admin API/MCP requests имеют отдельные Request ID и Trace ID, а 100% Execution/Task records сохраняют оба идентификатора. + +NFR-O2: Production генерирует 100% traces; delivery SLI ≥99.99% за 60 секунд и completeness 100% за 25 часов при outage ≤24 часов; каждый Telemetry Loss Record нарушает SLO и создаёт accounting/alert. + +NFR-O2a: Capacity test доказывает 30-hour spool/24-hour outage envelope по фактическому p95 trace size в выделенном disk budget без eviction и ущерба PostgreSQL/artifact reserve. + +NFR-O3: Observability overhead ≤5% p95 latency и ≤10% CPU относительно telemetry-disabled baseline. + +NFR-O4: Metrics не создают series из пользовательских IDs или arbitrary values; metric-to-trace correlation использует exemplars/deep links. + +NFR-O5: Redaction имеет negative regression tests для headers, cookies, query, JSON, YAML, errors, browser events и Load Run artifacts. + +NFR-C1: Rust MSRV, Edition, workspace boundaries и public wire contracts меняются только отдельным совместимым change. + +NFR-C2: Latest stable MCP на feature freeze и две предыдущие поддерживаемые stable версии проходят protocol matrix. + +NFR-C3: Breaking change требует versioning/deprecation note и migration path; Published Version остаётся immutable. + +NFR-C4: Новый пользовательский текст одновременно поставляется на RU и EN. + +### Additional Requirements + +- AR-1: Проект brownfield; starter template не применяется. Сохраняется hexagonal modular monolith с control-plane/execution-plane split, существующими apps/crates и проверяемым направлением зависимостей; новые reusable crates не зависят от apps или concrete adapters. +- AR-2: Operation, Resource и Prompt остаются отдельными typed aggregates с общими refs/lifecycle/sensitivity; Agent publication атомарно создаёт immutable catalog snapshot и monotonic revision. +- AR-3: Dynamic Resource может использовать только pinned published read-safe GET/HEAD Operation через RuntimeExecutor; Prompt rendering side-effect-free, dependency DAG и effective sensitivity валидируются до publish. +- AR-4: PostgreSQL 16 — authority для configuration, catalogs, approvals, idempotency, Tasks, Load Runs, events и safety; Valkey 8 только rebuildable acceleration, PG-only остаётся корректным. +- AR-5: MCP реализуется через version-isolated adapters поверх общих method services. Adapter `2026-07-28` реализует stateless request lifecycle, обязательный `server/discover`, стандартные request metadata и актуальные result/cache/subscription contracts; session-based `2025-*` adapters остаются изолированным compatibility path до evidence-backed deprecation. +- AR-6: Tools, Resources, Prompts, completion, logging и change signals имеют единые внутренние service contracts с Agent scoping до protocol serialization; `resources/list|read|templates/list`, `prompts/list|get` и соответствующие change/subscription semantics проходят отдельные authorization, pagination, cache и URI/argument validation contracts. +- AR-7: `crank-core` владеет Task types/ports, `crank-tasks` — use cases, `crank-registry` — persistence, `task-worker` — composition; HTTP/SSE lifetime не определяет durability. MCP Tasks реализуются как negotiated extension `io.modelcontextprotocol/tasks` с `tools/call`, `tasks/get`, `tasks/update` и `tasks/cancel`; PostgreSQL остаётся authority, Redis/Valkey используется только как восстанавливаемый wake-up/coordination accelerator. +- AR-8: Task+dispatch commit атомарен; claims используют bounded `FOR UPDATE SKIP LOCKED`, CAS leases и monotonic fencing; terminal transitions conditional, input updates versioned/idempotent. +- AR-9: Attempt ID и idempotency fingerprint сохраняются до outbound dispatch; ambiguity после side effect становится `outcome_unknown` и требует evidence-bearing reconciliation. +- AR-10: `crank-artifacts` хранит bounded content-addressed bytes через atomic write/fsync/rename; OpenAPI использует pipeline ParsedDocument → NormalizedIR+Findings → immutable ImportPlan → transactional Apply. +- AR-11: Browser/Admin/MCP ingress создают отдельные request identity и canonical W3C TraceContext; durable worker продолжает parent trace, каждый retry — отдельный child attempt span. +- AR-12: Только `crank-observability` владеет redaction/export и per-process/per-destination encrypted disk spool; browser отправляет scrubbed same-origin envelope через Admin API, не direct DSN. +- AR-13: Только `crank-metrics` объявляет metric names/types/labels/buckets; typed ProductEvent сохраняется и сворачивается идемпотентно в UTC rollups, trace correlation не использует high-cardinality labels. +- AR-14: `load-runner` — отдельный процесс, вызывающий public MCP endpoint; signed LoadAuthorizationPlan, reserved control runtime, local Unix kill socket и heartbeat обязательны до Start. +- AR-15: Все secret-using processes сверяют общий master-key fingerprint/epoch с PostgreSQL до readiness; ciphertext versioned, rotation transactional, key material не входит в DB/manifests/logs. +- AR-16: `crank-registry` — единственная migration authority; sequence append-only/checksummed, service startup только проверяет compatibility, changes следуют expand/migrate/contract и N/N-1 window. +- AR-17: Leaf crate `crank-config` владеет typed fields/defaults/bounds/sensitivity/cross-field validation; apps получают validated config, libraries не читают environment. +- AR-18: Correctness topology включает UI, Admin API, MCP Server, Task Worker, PostgreSQL и shared artifact storage; Load Runner on-demand, Valkey optional, observability имеет отдельный budget. +- AR-19: Сохраняются Alpine.js и concatenated `window.Crank*` bundles; async UI использует identity/revision guards, boundary errors имеют stable code, localized bounded message, request_id и trace_id. +- AR-20: Capability Inventory, corpora, matrices и quality results — immutable content-addressed artifacts одного RC, индексированные signed JSON-Schema Evidence Manifest и проверяемые fail closed. +- AR-21: Admin tests, MCP Tools, Resources и Task attempts проходят единый `RuntimeExecutionRequest → crank-runtime → crank-adapter-rest` path и общий deny-before-allow OutboundPolicy. +- AR-22: Admin auth включает one-time bootstrap, rate limit/backoff, PostgreSQL revocation/audit, TLS/trusted proxy, secure cookies, CSRF, deny-by-default CORS и local-only recovery. +- AR-23: Единый ExecutionAdmission snapshot применяется к sync/background paths; queued Task pin-ит semantics, на claim повторно проверяются auth, publication, credential, deadline и capacity. +- AR-24: BackupManifest связывает WAL/PITR, artifacts, config и opaque protected key reference; typed retention раздельна по datasets и не разрушает Published/evidence auditability. +- AR-25: Offline production bundle signed и digest-pinned, содержит Compose/config/SBOM/licenses/docs и проверяется air-gapped fresh/N-1 upgrade, hardening и default-deny egress tests. +- AR-26: Wire/concurrency conventions обязательны: UUIDv7 typed IDs, UTC/RFC3339, bounded opaque pagination, PostgreSQL CAS/locks, stable error codes, full auth scope in keys, typed events и units in config names. +- AR-27: Pinned stack: Rust 1.96.1/Edition 2024/MSRV 1.96, Axum 0.8, Tokio 1, SQLx 0.9, PostgreSQL 16, Valkey 8, Node 22, Alpine 3.15.12 и Playwright 1.61.1; dependency/toolchain updates не смешиваются с feature work. +- AR-28: Target structure добавляет `task-worker`, `load-runner`, `crank-tasks`, `crank-load`, `crank-import`, `crank-artifacts`, `crank-config`, `crank-trace`, `crank-observability` и release/corpus/recovery assets без frontend rewrite. +- AR-29: Первый enabling change обновляет Community documentation, `project-context.md`, executable scope checks и tests для Resources, Prompts, Tasks и Load Runs; allow-marker не заменяет contract change. +- AR-30: Exact latest stable MCP, representative clients, component image digests, telemetry retention и performance tuning фиксируются в предусмотренных feature-freeze/evidence gates и не могут ослабить PRD thresholds. +- AR-31: Rust production paths не используют unsafe по умолчанию, unwrap/expect/panic на user/I/O paths; errors typed и stage-preserving, domain core framework-free, wire changes получают contract/roundtrip tests. +- AR-32: Каждый bug fix начинается с regression test; backend change проходит targeted tests, `just test`/`just verify`, UI change — build и применимый Playwright, storage tests используют PostgreSQL 16/Testcontainers и unique schemas. +- AR-33: UI stories сохраняют vanilla JS/Alpine bundle model, loading/error/empty states, stale-response protection, safe DOM sinks, shared `Crank*` services и одновременную RU/EN localization. +- AR-34: Release/deployment changes проверяются в Gitea-compatible CI; canonical deployment расположен в `deploy/community`, migrations backward-compatible, secrets поступают через OpenBao и не попадают в committed config. + +### UX Design Requirements + +Отдельный UX design contract не создавался по Fast Path. Все обязательные UI flows и interaction constraints извлечены из FR-6, FR-7, FR-15..FR-18, FR-26, FR-28, FR-30, FR-34..FR-40, FR-41, FR-45 и Architecture AD-19/AR-33; самостоятельных `UX-DR` нет. + +### FR Coverage Map + +FR-1: Epic 1 — lifecycle Operation. +FR-2: Epic 1 — безопасное REST-выполнение. +FR-3: Epic 1 — secrets, keys и Admin bootstrap. +FR-4: Epic 1 — versioned Agent catalog. +FR-5: Epic 1 — approvals и защита side effects. +FR-6: Epic 1 — Invocation History и Usage. +FR-7: Epic 2 — OpenAPI preview без мутаций. +FR-8: Epic 2 — полнота HTTP-контрактов. +FR-9: Epic 2 — references и schema composition. +FR-10: Epic 2 — OpenAPI security schemes. +FR-11: Epic 2 — conflicts и повторный import. +FR-12: Epic 2 — support matrix и regression corpus. +FR-13: Epic 3 — MCP negotiation и совместимость. +FR-14: Epic 3 — полный Tools contract. +FR-15: Epic 3 — versioned Resources. +FR-16: Epic 3 — static и REST-backed Resource types. +FR-17: Epic 3 — versioned Prompts. +FR-18: Epic 3 — безопасная Prompt composition. +FR-19: Epic 3 — completion, logging и notifications. +FR-20: Epics 3, 4 и 8 — инкрементальная MCP matrix для каталога и Tasks extension с финальной release qualification. +FR-21: Epic 4 — execution modes. +FR-22: Epic 4 — durable Task lifecycle. +FR-23: Epic 4 — recovery и delivery semantics. +FR-24: Epic 4 — concurrency и backpressure. +FR-25: Epic 4 — retry, cancellation, input и reconciliation. +FR-26: Epic 4 — Task operations в UI. +FR-27: Epic 5 — correlation identity. +FR-28: Epic 5 — поиск и trace deep links в UI. +FR-29: Epic 5 — GlitchTip integration. +FR-30: Epic 5 — browser observability. +FR-31: Epic 5 — telemetry resilience. +FR-32: Epic 5 — технические метрики. +FR-33: Epic 5 — локальные бизнес-метрики. +FR-34: Epic 5 — Prometheus и Grafana integration. +FR-35: Epic 5 — SLO и error budgets. +FR-36: Epic 6 — Load Scenario и профиль нагрузки. +FR-37: Epic 6 — модель DAU. +FR-38: Epic 6 — безопасность Load Run. +FR-39: Epic 6 — live execution и stop. +FR-40: Epic 6 — immutable report и история. +FR-41: Epic 7 — deployment profiles. +FR-42: Epic 7 — закрытый контур и offline bundle. +FR-43: Epic 7 — migrations, upgrade, backup и recovery. +FR-44: Epic 7 — container hardening. +FR-45: Epic 7 — единый configuration contract. +FR-46: Epic 8 — automated test pyramid и Capability Inventory. +FR-47: Epic 8 — полный manual regression. +FR-48: Epic 8 — compatibility matrices. +FR-49: Epic 8 — performance, soak и recovery qualification. +FR-50: Epic 8 — security release evidence. +FR-51: Epic 8 — документация и runbooks. +FR-52: Epic 8 — immutable Release Candidate и Evidence Manifest. +FR-53: Epic 8 — публичная readiness page. +FR-54: Epic 8 — Habr Release Gate. + +## Epic List + +### Epic 1: Надёжный базовый REST → MCP продукт + +Пользователь может безопасно создать, опубликовать и вызвать Tool, управлять Agent, ключами, approvals и диагностируемой историей без регрессий существующего поведения. + +**FRs covered:** FR-1, FR-2, FR-3, FR-4, FR-5, FR-6. + +**Implementation notes:** Brownfield baseline; Capability Inventory существующих flows и расширение Community guardrails создаются как enabling work, но полная release qualification остаётся в Epic 8. + +### Epic 2: Надёжное создание Tools из реальных OpenAPI + +Пользователь загружает OpenAPI/Swagger, получает детерминированный preview, исправляет findings и атомарно создаёт пригодные к публикации Operations без silent loss. + +**FRs covered:** FR-7, FR-8, FR-9, FR-10, FR-11, FR-12. + +**Implementation notes:** Content-addressed artifacts, NormalizedIR, immutable ImportPlan, support matrix и regression corpus образуют единый import workflow. + +### Epic 3: Полноценный современный MCP-каталог + +Пользователь создаёт и публикует Tools, Resources и Prompts, связывает их с Agent и использует через совместимые MCP-клиенты. + +**FRs covered:** FR-13, FR-14, FR-15, FR-16, FR-17, FR-18, FR-19, FR-20. + +**Implementation notes:** Единый capability lifecycle, отдельные typed aggregates и два изолированных protocol-era adapter family: stateless MCP `2026-07-28` и session-based compatibility `2025-*`; experimental capabilities не заменяют stable core. + +### Epic 4: Безопасные параллельные и фоновые выполнения + +Пользователь запускает долгие Tools как durable Tasks, наблюдает progress, отменяет, восстанавливает после restart и разрешает `outcome_unknown` без неконтролируемого повторения side effects. + +**FRs covered:** FR-20 (Tasks extension cells), FR-21, FR-22, FR-23, FR-24, FR-25, FR-26. + +**Implementation notes:** PostgreSQL transactional dispatch, leases, fencing, ExecutionAdmission, bounded queues и отдельный Task Worker. + +### Epic 5: Полная эксплуатационная видимость + +Оператор прослеживает любой запрос по `trace_id` в UI и GlitchTip, видит технические и бизнесовые метрики, Grafana dashboards, SLO и alerts. + +**FRs covered:** FR-27, FR-28, FR-29, FR-30, FR-31, FR-32, FR-33, FR-34, FR-35. + +**Implementation notes:** Correlation, durable telemetry spool, redaction, typed metrics, local ProductEvent rollups и Prometheus/Grafana составляют один operational workflow. + +### Epic 6: Встроенная проверка производительности + +Оператор задаёт RPS, VU или модель DAU, безопасно запускает и останавливает Load Run, наблюдает live statistics и получает immutable сравнительный отчёт. + +**FRs covered:** FR-36, FR-37, FR-38, FR-39, FR-40. + +**Implementation notes:** Изолированный Load Runner, signed authorization plan, hard ceilings, heartbeat и независимый local kill path. + +### Epic 7: Автономное production-развёртывание и восстановление + +Оператор устанавливает Crank одной командой, в том числе offline, безопасно обновляет, создаёт backup и доказывает восстановление реальным MCP-вызовом. + +**FRs covered:** FR-41, FR-42, FR-43, FR-44, FR-45. + +**Implementation notes:** Minimal/production profiles, typed config, single migration authority, single-instance drain/restart, hardening, signed offline bundle и RPO/RTO evidence. + +### Epic 8: Доказанный production-релиз + +Команда всесторонне проверяет один immutable RC, формирует подписанное evidence, публикует честную readiness page и только после прохождения gate разрешает анонс на Хабре. + +**FRs covered:** FR-46, FR-47, FR-48, FR-49, FR-50, FR-51, FR-52, FR-53, FR-54. + +**Implementation notes:** Automated/manual regression, compatibility matrices, security, 72-hour soak, 30-day burn-in и signed Evidence Manifest одного RC. + +### Обязательные правила декомпозиции stories + +1. **Enabling work выполняется вовремя:** migration, typed config, guardrail, artifact, deployment и другой технический фундамент реализуются в первой story, которой они необходимы. Владение итоговым FR более поздним эпиком не разрешает откладывать prerequisite. +2. **Качество строится внутри каждой story:** каждая story закрывает применимые NFR, automated/negative tests, observability и evidence. Epic 8 квалифицирует уже проверенные capabilities на одном RC и не служит местом для отложенного тестирования. +3. **UI story содержит полный interaction contract:** применимые loading, empty, error, confirmation и stale-response states, безопасные support identifiers/correlation, RU/EN localization и Playwright evidence задаются в acceptance criteria самой story. +4. **Критические UI flows доступны:** keyboard navigation, видимый focus, semantic labels/landmarks, screen-reader status, contrast и передача смысла не только цветом проверяются по WCAG 2.2 AA; animation уважает reduced-motion. +5. **Новая поверхность входит в общую IA:** top-level navigation, workspace context, URL-addressable state, back/refresh/reconnect и permission-aware visibility являются частью той же UI story, а не отдельным поздним polish. +6. **MCP conformance строится инкрементально:** каждая Story Epic 3 одновременно добавляет executable matrix cells и deterministic wire fixtures своего contract; Story 3.20 квалифицирует уже существующее evidence, а не создаёт отложенные тесты. + +### Cross-Epic Dependencies and Recommended Delivery Order + +Номера эпиков группируют пользовательские outcomes и не задают календарный порядок. Реализация выполняется следующими волнами; story не начинается до прохождения её prerequisites, а временный stub не считается выполненным dependency contract. + +| Волна | Stories | Обязательная зависимость и результат | +|---|---|---| +| 0 — исполняемый фундамент | `1.1 → 1.2 → 1.3 → 1.4 → 1.5 → 1.6` | Capability Inventory/baseline сначала; затем единые config, migrations, correlation и typed metric contracts до новых storage/runtime surfaces. | +| 1 — hardened core | `1.7 → 1.8 → 1.9 → 1.10 → 1.11 → 1.12 → 1.13 → 1.14 → 1.15 → 1.16` | Immutable Operation/runtime/outbound и security identity последовательно дают catalog, approvals, history и самостоятельный manual onboarding. | +| 2 — import и modern MCP | `2.1 → … → 2.15`; `3.1 → 3.2 → 3.3 → 3.4 → 3.5`, затем Resource branch `3.6 → 3.7 → {3.8,3.9,3.10 → 3.11}`, Prompt branch `3.12 → 3.13 → 3.14 → 3.15`, composition `3.16` после `3.7`, `3.11`, `3.14`, затем `3.17 → 3.18 → 3.19 → 3.20`; обе ветки параллельны Epic 4 | OpenAPI branch сначала последовательно закрывает immutable storage, scoped metadata, reconciliation/recovery, Admin API contract и UX/evidence, затем расширяет готовый manual onboarding; MCP `2026-07-28`/legacy foundation и полный Tools contract открывают независимые Resources, Prompts и Tasks branches без искусственной сериализации. | +| 3 — durable execution | после `3.4`: `4.1 → 4.2 → 4.3 → {4.4,4.5,4.6} → 4.7 → 4.8 → 4.9 → 4.10` | Admission/persistence/leases предшествуют lifecycle policy, official Tasks extension/UI и capacity/recovery evidence; Story 4.7 добавляет Tasks cells в matrix Story 3.20, завершение Resources/Prompts не является prerequisite. | +| 4 — operational visibility | `5.1 → 5.2 → 5.3 → 5.4 → 5.5 → 5.6 → 5.7 → 5.8 → 5.9 → 5.10 → 5.11 → 5.12 → 5.13` | End-to-end correlation/search предшествуют browser/server export; durable spool/loss evidence и complete metrics/product rollups предшествуют Prometheus, Grafana и SLO. | +| 5 — встроенная нагрузка | `6.1 → {6.2,6.3} → 6.4 → 6.5 → 6.6` | Versioned Scenario предшествует модели/authorization; signed plan — runner; runner — live control/report. | +| 6 — поставка и recovery | `7.1 → 7.2 → 7.3 → 7.4 → 7.5 → 7.6 → 7.7 → 7.8 → 7.9` | Full config/migration qualification и profiles предшествуют exposure/bundle/hardening; backup/restore предшествуют upgrade. Hardened image change обязательно пересобирает и повторно проверяет bundle. | +| 7 — один RC | `8.1 → 8.2`; затем `{8.3,8.4,8.5,8.7,8.8}`; `8.5 → 8.6`; затем `8.9 → 8.10` | Один immutable RC и evidence contract предшествуют проверкам; performance предшествует soak, все qualification/docs — 30-day burn-in и Habr Gate. | + +Критический путь: `1.1 → 1.2 → 1.3 → 1.4 → 1.5 → 1.6 → 1.7 → 1.8 → 1.9 → 1.13 → 3.1 → 3.2 → 3.3 → 3.4 → 4.1 → 4.2 → 4.3 → 4.10 → 6.1 → 6.3 → 6.4 → 6.6 → 7.1 → 7.2 → 7.3 → 7.4 → 7.5 → 7.6 → 7.7 → 7.8 → 7.9 → 8.1 → 8.2 → 8.5 → 8.6 → 8.9 → 8.10`. + + +### Исполнение story и внешний qualification handoff + +- Scope фиксируется утверждёнными AC выбранной story. Общие NFR и negative tests применяются к её изменённой поверхности; они не разрешают реализовывать следующие stories. +- Вход: prerequisites имеют accepted результат; spec фиксирует deliverable, конечные команды/сценарии проверки и применимые environment requirements. Отсутствующий prerequisite — blocker, а не разрешение сделать его в этой story. +- Выход implementation story: поставлен её outcome, выполнены все её AC и обязательные проверки, evidence связано с проверенным commit/config. Общая regression suite не расширяет product scope. +- `Depends on` ниже — контракт планирования, не нативный DAG поля sprint-status. Build должен перенести и проверить эти зависимости в spec; выбор backlog самим loop не доказывает готовность prerequisites. +- Qualification story отделяет подготовку harness от исполнения на среде и приёмки evidence. `awaiting-operator` допускает передачу внешней работы, но не означает accepted qualification и не разблокирует зависимый release gate. При отсутствии такого handoff workflow возвращает `blocked` с точными actions/evidence; никакого fake pass, сокращения длительности или ожидания человеком в coding session. +- Владельцы ручных действий и доступа назначаются перед конкретным run. Реализация проверок выполняется агентом; ручная подпись, fresh-user validation и разрешение внешних действий остаются за оператором/reviewer. После handoff проверяется возвращённое evidence, а не заново реализуется весь harness. + +### Single-Agent Scope and File-Churn Rationale + +- Каждая story имеет один authoritative outcome и одного owning agent; количество negative AC отражает risk matrix, а не разрешение реализовывать несколько stories одновременно. +- Первоначальная объединённая OpenAPI-source story разделена на текущие `2.1`–`2.6` после подтверждённых timeout и non-convergent review: storage security, scoped persistence, filesystem reconciliation, claim/recovery orchestration, HTTP orchestration и UI/release evidence имеют отдельные исполняемые gates и строгую последовательность, не ослабляя исходный immutable-source contract. После декомпозиции 2026-09-13 весь Epic 2 использует последовательные номера `2.1`–`2.15`; таблица соответствия историческим IDs находится в `../implementation-artifacts/epic-2-context.md`. +- Завершённые `2.8`/`2.9` не переоткрываются. Текущие `2.12`/`2.13`/`2.14` сохраняют единый preview-plan, transactional Apply и corpus outcome. Атомарность runtime transaction или immutable digest сама по себе не запрещает отдельные поставки API/UI; ни одна новая slice не ослабляет этот contract. +- Tools и Resources разрезаны по independently testable boundaries: discovery, call, execution lifecycle, artifact Draft, publication/binding, protocol read, portability и dynamic execution. +- Повторное изменение `crank-core`, `crank-registry`, Admin API и shared UI является ожидаемым расширением стабильных extension points отдельными vertical capabilities. Wave 0 фиксирует config/migration/correlation/metrics contracts; последующие эпики не переопределяют их. +- Новые крупные domains имеют отдельных owners (`crank-import`, `crank-tasks`, `crank-load`, `crank-artifacts`, `crank-observability`), поэтому объединение эпиков увеличило бы context/risk без более ранней пользовательской обратной связи. + +## Epic 1: Надёжный базовый REST → MCP продукт + +Пользователь может безопасно создать, опубликовать и вызвать Tool, управлять Agent, ключами, approvals и диагностируемой историей без регрессий существующего поведения. + +### Story 1.1: Создать исполняемый контракт Capability Inventory + +As a владелец релиза, +I want иметь версионируемый и автоматически проверяемый формат Capability Inventory, +So that текущие и целевые продуктовые flows нельзя потерять, ошибочно объявить готовыми или вывести за Community scope. + +**Requirements:** FR-46 + +**Acceptance Criteria:** + +**Given** утверждённые PRD, SPEC и Architecture Spine +**When** создаётся schema Capability Inventory +**Then** она требует для каждого flow уникальный ID, тип UI/API/MCP, связанный FR, пользовательский outcome, owner, статус реализации и ссылки на automated/manual evidence +**And** поддерживает явные состояния `implemented`, `planned`, `gap`, `blocked` без трактовки последних трёх как pass. + +**Given** machine-readable Capability Inventory +**When** CI запускает validator +**Then** отсутствующий обязательный FR, duplicate ID, неизвестный status, битая evidence-ссылка или flow без owner завершают проверку ошибкой +**And** validator выдаёт детерминированный bounded report без чувствительных данных. + +**Given** намеренное расширение Community scope +**When** обновляются executable scope guardrails +**Then** Resources, Prompts, Tasks и Load Runs распознаются как разрешённые целевые возможности +**And** multi-workspace, enterprise RBAC/SSO, non-REST upstream и arbitrary distributed load targets остаются запрещены. + +**Given** новые или untracked файлы scope guardrails и inventory +**When** выполняется проверка Community scope +**Then** новые файлы передаются scanner явно и покрываются positive/negative tests +**And** `community-scope: allow` не используется как обход контракта. + +**Given** изменение executable Community boundary +**When** story завершается +**Then** синхронно обновлены Community documentation и `project-context.md` +**And** inventory не утверждает, что planned capabilities уже реализованы. + +**Given** реализация story +**When** выполняются обязательные проверки +**Then** проходят targeted tests, boundary/scope tests и `just verify` +**And** Rust toolchain, зависимости и существующие wire-контракты не изменяются попутно. + +### Story 1.2: Зафиксировать фактический baseline существующих flows + +As a владелец продукта, +I want получить проверенный baseline всех существующих возможностей Crank, +So that функциональные недоработки и регрессии видны до начала расширения продукта. + +**Requirements:** FR-46 + +**Acceptance Criteria:** + +**Given** validator и schema Capability Inventory из Story 1.1 +**When** инвентаризируются существующие возможности +**Then** inventory содержит все известные UI, Admin API и MCP flows для Operations, Agents, Auth Profiles, MCP/approval keys, approvals, test execution, YAML import/export, Logs и Usage +**And** каждый flow связан с наблюдаемым контрактом, FR, owner и текущим evidence status. + +**Given** текущий рабочий REST → MCP happy path +**When** администратор создаёт простую REST Operation, тестирует, публикует, привязывает её к Agent и вызывает из MCP-клиента +**Then** весь путь проходит на текущем brownfield stack +**And** evidence фиксирует operation/version, Agent revision, safe outcome и использованные команды без credentials или sensitive payloads. + +**Given** существующие automated suites +**When** выполняются targeted Rust tests, `just verify`, UI build и применимые Playwright smoke scenarios +**Then** каждый результат связан с соответствующими inventory flows +**And** failed, flaky, skipped или отсутствующий test не записывается как `pass`. + +**Given** существующий пользовательский интерфейс +**When** выполняется bounded exploratory pass основных экранов +**Then** для каждого flow фиксируются happy path, loading, empty, error и доступные recovery actions +**And** обнаруженные stale-response, localization или unsafe-output проблемы становятся traceable gaps. + +**Given** найденный функциональный или security defect +**When** он добавляется в baseline +**Then** запись содержит severity, воспроизводимые шаги, затронутый contract и owner +**And** Critical/High defect переводит связанный flow в `blocked`, а не скрывается общим статусом Epic. + +**Given** отсутствие автоматизированного evidence для существующего flow +**When** baseline завершается +**Then** flow получает явный manual-only либо gap status с требуемым следующим evidence +**And** Story 1.2 не подменяет полный manual regression из Epic 8. + +**Given** завершённая инвентаризация +**When** baseline фиксируется +**Then** machine-readable inventory, outcome taxonomy, manual checklist и результаты получают version/checksum +**And** последующие stories могут изменять status только вместе с новым связанным evidence. + +### Story 1.3: Создать расширяемый typed configuration foundation + +As an оператор, +I want единый проверяемый способ конфигурировать существующие процессы, +So that каждая следующая capability добавляет параметры без новых скрытых environment contracts. + +**Requirements:** FR-45 + +**Acceptance Criteria:** + +**Given** существующие runtime/Admin/MCP configuration parameters +**When** создаётся leaf crate `crank-config` +**Then** каждый текущий field получает type, unit-bearing name, default, bounds, sensitivity и cross-field validation +**And** libraries перестают читать environment напрямую, apps получают только validated config. + +**Given** canonical configuration schema +**When** генерируются environment examples и redacted diagnostics +**Then** defaults/bounds совпадают с runtime contract, secret показывается только как configured/unconfigured +**And** effective config имеет стабильный fingerprint без raw values. + +**Given** invalid, unknown либо conflicting current field +**When** процесс стартует +**Then** startup fail safe со stable field path/code и bounded RU/EN diagnostic +**And** secret value не отражается в log/error. + +**Given** новая capability в последующей story +**When** ей требуется configuration +**Then** field сначала добавляется в тот же typed schema вместе с docs/example/tests +**And** отдельный environment reader либо неподтверждённый default блокируется boundary check. + +**Given** legacy alias текущего field +**When** он используется в compatibility window +**Then** precedence и deprecation deterministic, конфликт с canonical field блокирует startup +**And** migration path documented. + +**Given** config foundation suite +**When** выполняются default/min/max/invalid, redaction и boundary tests +**Then** existing minimal deployment сохраняет поведение +**And** `just verify` проходит без dependency/toolchain changes. + +### Story 1.4: Учредить versioned migration authority + +As an оператор, +I want безопасный механизм последовательного изменения schema, +So that новые capability tables добавляются без изменения выпущенного baseline. + +**Requirements:** FR-43 + +**Acceptance Criteria:** + +**Given** brownfield migration inventory +**When** определяется canonical runner +**Then** `crank-registry` становится единственной migration authority, а immutable baseline v1 и его checksum не меняются +**And** legacy ledgers сопоставляются до mutation. + +**Given** новая schema migration +**When** owning story добавляет durable fields/tables +**Then** migration имеет новую monotonic version, immutable checksum и transaction под PostgreSQL advisory lock +**And** повторное применение idempotent либо безопасно отклоняется. + +**Given** service startup +**When** database проверяется +**Then** service только валидирует compatibility, controlled migration command применяет DDL +**And** concurrent app instances не мигрируют schema самостоятельно. + +**Given** partial, changed-checksum либо incompatible state +**When** preflight выполняется +**Then** readiness fail closed с actionable recovery diagnostic +**And** destructive automatic rollback отсутствует. + +**Given** future breaking storage change +**When** планируется evolution +**Then** contract требует expand → migrate/backfill → contract и N/N-1 window +**And** migration/backfill остаётся bounded и resumable. + +**Given** PostgreSQL 16 runner suite +**When** проверяются fresh, baseline, already-migrated, concurrent и failure states +**Then** sequence/checksums/audit детерминированы, baseline data сохранены +**And** `just verify` проходит. + +### Story 1.5: Ввести canonical request и trace identity + +As an оператор поддержки, +I want получать Request ID и Trace ID на существующих ingress/runtime paths, +So that все последующие capabilities наследуют correlation по готовому contract. + +**Requirements:** FR-27 + +**Acceptance Criteria:** + +**Given** UI, Admin API или MCP ingress +**When** request не содержит доверенных IDs либо содержит malformed/oversized values +**Then** создаются отдельные typed UUIDv7 Request ID и canonical W3C Trace ID +**And** response/boundary error возвращает safe local IDs. + +**Given** validated ingress context +**When** существующий synchronous Execution проходит service/runtime/outbound +**Then** TraceContext распространяется стандартными headers/spans, Request ID остаётся отдельной product identity +**And** mapped/user/upstream headers не могут заменить системную correlation. + +**Given** execution/history persistence +**When** record сохраняется +**Then** оба ID сохраняются независимо от sampling +**And** logs/audit используют bounded correlation fields без sensitive payloads. + +**Given** новая async/process boundary в последующей story +**When** она проектируется +**Then** typed parent context и оба IDs входят в durable contract до acknowledgement +**And** completion evidence добавляется в owning story. + +**Given** invalid incoming traceparent +**When** trust policy отклоняет его +**Then** создаётся новый local trace без отражения attacker-controlled value +**And** rejection не создаёт high-cardinality metric/log fields. + +**Given** correlation foundation suite +**When** выполняются success, validation, auth, retry, sampling-off и upstream failure cases +**Then** 100% существующих ingress/Execution records имеют оба ID +**And** propagation contract и `just verify` проходят. + +### Story 1.6: Учредить typed metrics registry + +As an оператор, +I want стабильный low-cardinality metrics contract до появления новых подсистем, +So that instrumentation не расходится по именам, labels и buckets. + +**Requirements:** FR-32 + +**Acceptance Criteria:** + +**Given** новый crate `crank-metrics` +**When** объявляется metric +**Then** name, type, unit, help, bounded label enums и histogram buckets задаются typed registry +**And** произвольные IDs, URLs, names и error text невозможно передать как labels через public API. + +**Given** существующий Admin/MCP/runtime traffic +**When** запрос завершается +**Then** counters/histograms отражают bounded route/method/outcome/stage, duration и saturation +**And** metric schema snapshot versioned. + +**Given** metric-to-trace correlation +**When** observation имеет Trace ID +**Then** используется exemplar, а не label +**And** отсутствие exemplar не меняет aggregate. + +**Given** новая capability в последующей story +**When** добавляется instrumentation +**Then** она расширяет typed registry и schema snapshot в том же change +**And** owning story доказывает traffic/error/duration/saturation metrics и cardinality bounds. + +**Given** direct metric declaration вне `crank-metrics` +**When** boundary check сканирует workspace +**Then** build fail с owner/path diagnostic +**And** alias/re-export не обходит guardrail. + +**Given** registry suite +**When** подаются миллионы distinct user values и unknown outcomes +**Then** series count остаётся в budget, enums нормализуются безопасно +**And** schema/bucket/overhead tests и `just verify` проходят. + +### Story 1.7: Гарантировать immutable lifecycle Operation + +As an администратор, +I want безопасно создавать, тестировать, версионировать, публиковать, архивировать, импортировать и экспортировать Operations, +So that изменение Draft никогда не меняет уже опубликованное поведение Agent. + +**Requirements:** FR-1 + +**Acceptance Criteria:** + +**Given** авторизованный администратор и выбранный workspace +**When** он создаёт или изменяет Draft Operation +**Then** schema, mapping, runtime и safety configuration валидируются до сохранения +**And** чужой workspace или stale UI response не может изменить текущую Operation. + +**Given** валидный Draft +**When** администратор запускает test execution +**Then** выполняется именно сохранённая Draft revision без публикации в Agent catalog +**And** UI показывает loading, success/error и безопасные Request ID/Trace ID без раскрытия credentials. + +**Given** валидный Draft без blocker findings +**When** администратор публикует Operation +**Then** создаётся новая immutable Published Version с монотонным version number +**And** опубликованные schema, mapping, runtime policy и tool identity больше нельзя изменить in place. + +**Given** существующая Published Version +**When** администратор редактирует Operation +**Then** изменения сохраняются в новом Draft и не меняют Published Version или текущий Agent catalog +**And** новая версия становится доступной Agent только после отдельной публикации и явного обновления Agent binding. + +**Given** Published Version, используемая immutable Agent snapshot +**When** исходная Operation архивируется +**Then** она недоступна для новых bindings и публикаций +**And** уже опубликованный Agent snapshot и историческое evidence не переписываются и остаются воспроизводимыми до явного изменения lifecycle Agent. + +**Given** Draft или конкретная Published Version +**When** администратор экспортирует её в YAML и импортирует обратно +**Then** normalized wire contract, schema, mappings, auth reference, runtime и safety settings сохраняют семантическое равенство +**And** raw credentials, internal filesystem paths и runtime-only metadata отсутствуют в export. + +**Given** YAML upsert для существующей Operation +**When** импорт содержит изменённый контракт +**Then** создаётся новая version/draft согласно явной conflict policy +**And** предыдущая Published Version и Invocation History не перезаписываются. + +**Given** malformed, oversized или schema-invalid YAML +**When** администратор выполняет import +**Then** операция отклоняется до мутации состояния со stable localized error code +**And** report остаётся валидным UTF-8/JSON и не содержит произвольного parser output или secrets. + +**Given** lifecycle UI +**When** выполняются create, test, publish, edit, archive, export и import +**Then** доступны loading, empty, error, confirmation и stale-response states на RU и EN +**And** Playwright покрывает Draft isolation, publish immutability и YAML roundtrip. + +**Given** реализация lifecycle +**When** выполняются проверки +**Then** проходят domain, registry, Admin API, runtime и real-stack regression tests +**And** Capability Inventory получает evidence для FR-1 без изменения существующего wire-контракта. + +### Story 1.8: Унифицировать REST execution и boundary errors + +As an администратор или MCP-пользователь, +I want получать одинаковое и предсказуемое выполнение Operation через UI и MCP, +So that результат и классификация ошибки не зависят от входной точки. + +**Requirements:** FR-2 + +**Acceptance Criteria:** + +**Given** Admin Test или MCP `tools/call` +**When** начинается выполнение Operation +**Then** оба пути используют контракт `RuntimeExecutionRequest → crank-runtime → crank-adapter-rest` +**And** route/transport layer не вызывает REST adapter или persistence implementation напрямую. + +**Given** создаваемый `RuntimeExecutionRequest` +**When** application service передаёт его в runtime +**Then** request содержит typed workspace, Agent, Operation/version, authorization context, input, deadline, correlation, approval и idempotency context +**And** отсутствующий обязательный scope отклоняется до outbound dispatch. + +**Given** Admin Test для Draft +**When** runtime разрешает execution target +**Then** исполняется явно выбранная сохранённая Draft revision +**And** этот путь не делает Draft доступным через MCP или Agent catalog. + +**Given** MCP Tool call +**When** runtime разрешает execution target +**Then** исполняется только точная Published Version из immutable Agent snapshot +**And** запрос к Draft, чужому Agent или capability вне snapshot возвращает safe not-found/denied outcome без metadata leakage. + +**Given** успешный upstream response +**When** runtime завершает schema validation и output mapping +**Then** Admin Test и MCP получают семантически одинаковый normalized outcome +**And** transport-specific serialization выполняется только на соответствующей boundary. + +**Given** failure на schema, mapping, authorization, persistence, adapter, upstream или runtime stage +**When** ошибка достигает HTTP/MCP boundary +**Then** typed error сохраняет исходную stage и один раз преобразуется в stable `error_code`, safe localized message и explicit retryability +**And** raw cause, credential, arbitrary payload и internal path не пересекают boundary. + +**Given** timeout, cancellation или uncertain external outcome +**When** execution завершается без обычного success +**Then** outcome не получает ложный success/terminal classification +**And** retryability определяется typed contract, а не текстом сообщения. + +**Given** Request ID и Trace ID execution +**When** формируется result или error +**Then** оба идентификатора возвращаются в безопасном boundary contract и сохраняются с execution record +**And** Request ID не используется как Trace ID. + +**Given** изменение runtime contracts +**When** проверяются workspace boundaries +**Then** `crank-core` остаётся framework-free, `crank-runtime` не зависит от registry/Axum/SQLx, а apps остаются composition roots +**And** обновлённые boundary checks предотвращают обход через re-export, alias или helper. + +**Given** реализация unified execution +**When** выполняются automated checks +**Then** contract tests сравнивают Admin Test и MCP outcomes для success и каждой failure stage +**And** проходят targeted suites, boundary tests и `just verify`. + +### Story 1.9: Защитить каждое outbound REST-соединение + +As an оператор закрытого контура, +I want применять единую fail-closed outbound policy ко всем REST executions, +So that пользовательская конфигурация не превращает Crank в SSRF, proxy bypass или механизм истощения ресурсов. + +**Requirements:** FR-2 + +**Acceptance Criteria:** + +**Given** Admin Test или MCP Tool execution +**When** REST adapter открывает соединение +**Then** shared `OutboundPolicy` проверяет фактический resolved address непосредственно перед каждым connection attempt +**And** deny rules имеют приоритет над allow rules. + +**Given** hostname, разрешающийся в loopback, private, link-local, multicast, unspecified или запрещённый service address +**When** adapter пытается подключиться по IPv4 или IPv6 +**Then** соединение блокируется до отправки HTTP data +**And** safe error не раскрывает внутреннюю сеть, DNS response или policy internals. + +**Given** изменение DNS result между validation и connection +**When** выполняется connection attempt или retry +**Then** policy применяется к адресу фактического соединения заново +**And** ранее разрешённый hostname не является разрешением для нового запрещённого IP. + +**Given** upstream redirect +**When** redirects не разрешены Operation policy +**Then** adapter не следует redirect +**And** возвращает typed non-retryable policy outcome. + +**Given** явно разрешённый redirect contract +**When** upstream возвращает новый location +**Then** scheme, host, port и фактический resolved address повторно проходят policy на каждом hop в пределах bounded redirect limit +**And** redirect не переносит Authorization, Cookie или другой credential на иной origin. + +**Given** process environment с HTTP/HTTPS proxy variables +**When** создаётся production HTTP client +**Then** system proxy не используется по умолчанию +**And** proxy может быть включён только отдельной typed operator configuration с тем же outbound security contract. + +**Given** пользовательские static или mapped headers +**When** формируется outbound request +**Then** системные correlation, authorization и safety headers имеют приоритет +**And** пользователь не может переопределить `traceparent`, Request ID, `Host`, content length или credential, выбранный Auth Profile. + +**Given** configured request, response, concurrency и deadline limits +**When** выполняется REST call +**Then** limits применяются до неограниченного ожидания или накопления body в памяти +**And** oversized request/response, exhausted concurrency и deadline возвращают разные typed outcomes. + +**Given** retry-enabled Operation +**When** происходит retryable failure +**Then** retries соблюдают общий deadline, bounded attempts/backoff и idempotency/side-effect policy +**And** write без подтверждённого idempotency contract не повторяется после uncertain dispatch. + +**Given** invalid или unsafe production outbound configuration +**When** Crank запускается либо проходит readiness +**Then** затронутый safety path fail closed с диагностируемой config error +**And** политика не отключается молча. + +**Given** outbound security test suite +**When** выполняются negative tests +**Then** покрыты IPv4/IPv6 variants, DNS rebinding, redirect chains, embedded credentials, encoded hosts, proxy environment, oversized bodies, timeout и concurrency saturation +**And** logs, traces и test failures не содержат credentials или sensitive payloads. + +**Given** завершение story +**When** выполняются проверки +**Then** Admin Test и MCP проходят один набор outbound contract tests, `just verify` успешен +**And** Capability Inventory содержит evidence для FR-2, NFR-S3 и NFR-S4. + +### Story 1.10: Защитить lifecycle Auth Profiles и machine keys + +As an администратор, +I want безопасно создавать, ротировать и отзывать credentials, +So that Agents и Operations получают только необходимый доступ без возможности повторно извлечь секрет. + +**Requirements:** FR-3 + +**Acceptance Criteria:** + +**Given** новый Auth Profile +**When** администратор передаёт credential +**Then** raw value принимается только через защищённый write contract, шифруется до persistence и заменяется typed `AuthProfileRef` во всех Operations +**And** Operation, YAML export и API response не содержат raw secret. + +**Given** создание MCP key или approval key +**When** key успешно создан +**Then** raw value возвращается ровно один раз только в create response +**And** persistence хранит безопасный hash, non-sensitive prefix, scope, timestamps и status без recoverable raw key. + +**Given** Auth Profile, MCP key или approval key после создания +**When** администратор выполняет get, list, export или diagnostics +**Then** возвращаются только redacted metadata и status +**And** повторно показать raw value невозможно даже привилегированному Admin API caller. + +**Given** MCP key +**When** он используется для Agent endpoint +**Then** проверяются exact Agent/workspace scope, status и разрешённые MCP actions +**And** key другого Agent или workspace возвращает safe denied/not-found outcome без metadata leakage. + +**Given** approval key +**When** им подтверждается Execution +**Then** ключ принимается только approval boundary и не может использоваться как Admin session или MCP execution credential +**And** Admin/MCP credentials аналогично не подменяют approval key. + +**Given** активный credential +**When** администратор отзывает его +**Then** revocation атомарно сохраняется в PostgreSQL и начинает действовать без restart +**And** любые cache/Valkey projections инвалидируются либо fail closed при невозможности подтвердить актуальный status. + +**Given** rotation Auth Profile или machine key +**When** создаётся новый credential +**Then** новая версия проверяется до активации, переход current/previous атомарен, а старое значение отзывается по явно подтверждённой policy +**And** Operation/Agent refs не требуют сохранения raw value или массовой перезаписи capability definitions. + +**Given** create/rotate/revoke action +**When** операция завершается успешно или с ошибкой +**Then** создаётся bounded audit event с actor, credential type/ref, action, outcome, Request ID и Trace ID +**And** event, logs, metrics, traces и error bodies не содержат secret, hash или полный key prefix. + +**Given** one-time disclosure UI +**When** raw key показан после создания +**Then** UI явно предупреждает, что значение нельзя восстановить, предоставляет безопасное copy action и очищает его после ухода со страницы +**And** refresh/back navigation, error telemetry и DOM snapshots не восстанавливают значение. + +**Given** credential UI на RU и EN +**When** выполняются create, rotate или revoke +**Then** реализованы loading, error, confirmation, success и stale-response states +**And** destructive revoke требует явного подтверждения. + +**Given** security test suite +**When** проверяются credential boundaries +**Then** negative tests покрывают cross-workspace/Agent access, revoked и malformed keys, wrong credential type, cache loss, exports, logs, errors и browser telemetry +**And** проходят registry/API/MCP/UI suites и `just verify`. + +### Story 1.11: Согласовать master-key identity и безопасную rotation + +As an оператор Crank, +I want все процессы использовать одну проверяемую master-key identity и безопасно менять ключ, +So that сохранённые secrets остаются доступными авторизованным execution paths после restart, rotation и восстановления. + +**Requirements:** FR-3 + +**Acceptance Criteria:** + +**Given** первый запуск secret-using deployment +**When** master-key identity регистрируется в PostgreSQL +**Then** сохраняются только non-secret fingerprint, active epoch и metadata алгоритма +**And** raw master key никогда не записывается в PostgreSQL, logs, traces, diagnostics или manifest. + +**Given** Admin API, MCP Server или другой secret-using process +**When** процесс проходит startup/readiness +**Then** он вычисляет fingerprint предоставленного key material и сверяет его с active identity в PostgreSQL +**And** mismatch, неизвестный epoch или неподдерживаемый cipher contract блокирует безопасный startup/readiness. + +**Given** сохранённый encrypted secret +**When** он записывается или читается +**Then** ciphertext содержит version/epoch и authenticated-encryption metadata, необходимые для выбора ключа и проверки целостности +**And** corrupt, truncated или unknown-version ciphertext возвращает typed security error без plaintext leakage. + +**Given** запрос на master-key rotation +**When** оператор запускает preflight +**Then** система проверяет доступность current и target key material, decryptability всех затронутых secret records и отсутствие уже активной несовместимой rotation +**And** preflight не изменяет ciphertext или active epoch. + +**Given** успешный preflight +**When** начинается re-encryption +**Then** rotation имеет durable ID/state и идемпотентно создаёт ciphertext target epoch без удаления current ciphertext +**And** concurrent secret writes используют явно определённый active/target contract без появления записей, недоступных работающим процессам. + +**Given** restart или crash во время rotation +**When** operator возобновляет процесс +**Then** rotation продолжает работу с последнего durable checkpoint без двойной обработки или потери secret +**And** current epoch остаётся рабочим, пока target epoch не проверен полностью. + +**Given** все записи re-encrypted +**When** выполняется verification +**Then** каждая запись успешно читается target key, counts совпадают с source set, а integrity failures блокируют promotion +**And** verification evidence содержит только IDs/counts/digests и безопасные errors. + +**Given** успешная verification +**When** target epoch становится active +**Then** promotion выполняется атомарно, все процессы перестают проходить readiness со старой identity после согласованного restart/reload boundary +**And** old key revocation разрешена только после подтверждённых reads новым key. + +**Given** ошибка rotation до promotion +**When** оператор выполняет abort/recovery +**Then** current epoch остаётся active, незавершённый target не используется для новых writes +**And** повторный запуск preflight безопасен и не требует раскрытия stored secrets. + +**Given** отдельно защищённое key-backup storage +**When** создаётся backup reference +**Then** Crank сохраняет только opaque reference и fingerprint/epoch metadata +**And** key bytes не попадают в product backup set или Evidence Manifest. + +**Given** master-key test matrix +**When** выполняются integration tests +**Then** покрыты совпадающие и несовпадающие процессы, corrupt ciphertext, crash до/после checkpoint и promotion, abort, successful rotation и old-key revocation +**And** ни один failure output не содержит plaintext или key material. + +### Story 1.12: Защитить Admin bootstrap, login и session lifecycle + +As an оператор self-hosted установки, +I want безопасно инициализировать и восстанавливать единственного администратора, +So that Crank не имеет default credentials и удалённый атакующий не может захватить Admin UI. + +**Requirements:** FR-3 + +**Acceptance Criteria:** + +**Given** новая установка без Admin credential +**When** оператор запускает локальный bootstrap process +**Then** создаётся bounded одноразовый bootstrap contract без default username/password +**And** raw bootstrap secret не печатается в service logs, container inspect output, telemetry или committed configuration. + +**Given** действующий bootstrap contract +**When** первый администратор задаёт credential +**Then** credential сохраняется только как memory-hard password verifier, bootstrap атомарно становится использованным +**And** concurrent или повторный bootstrap request не создаёт второго администратора и не переактивирует contract. + +**Given** использованный, истёкший или malformed bootstrap secret +**When** caller пытается завершить bootstrap +**Then** запрос отклоняется constant-shape ошибкой без раскрытия состояния account +**And** событие записывается в bounded security audit без secret. + +**Given** существующий Admin account +**When** выполняются login attempts +**Then** действует bounded rate limit и progressive backoff по безопасно выбранному scope +**And** ответы для неверного account, password, revoked session и throttling не позволяют определить существование account или verifier details. + +**Given** успешный login +**When** создаётся browser session +**Then** session identifier имеет достаточную entropy, сохраняется в безопасной форме и ротируется после authentication +**And** cookie использует `Secure` при TLS, `HttpOnly`, подходящий `SameSite`, bounded lifetime и явную expiry. + +**Given** state-changing browser request +**When** Admin UI вызывает API +**Then** server проверяет действующую session и CSRF contract, а CORS deny-by-default отклоняет чужой origin +**And** GET/read endpoint не становится обходом mutation или CSRF защиты. + +**Given** non-loopback production exposure +**When** Admin API определяет scheme, host и client identity +**Then** TLS обязателен, forwarded headers принимаются только от explicit trusted-proxy allowlist +**And** spoofed forwarding headers от недоверенного peer игнорируются. + +**Given** password rotation или recovery +**When** новое credential успешно активировано +**Then** все browser sessions и CSRF tokens атомарно отзываются, создаётся audit event +**And** старое credential и существующая session перестают работать без restart. + +**Given** потерянное Admin credential +**When** оператор выполняет offline recovery +**Then** recovery доступно только через local operator boundary и требует валидной master-key identity +**And** оно не раскрывает старый password, stored secrets или key material и не создаёт второй account. + +**Given** session expiry, logout или server-side revocation +**When** UI выполняет следующий protected request +**Then** shared `CrankAuth` обрабатывает `401`, очищает локальное session state и направляет пользователя в login flow +**And** protected pages не реализуют собственный обходной auth guard. + +**Given** Admin UI на RU и EN +**When** выполняются bootstrap, login, logout, password rotation или recovery-related actions +**Then** присутствуют loading, generic error, throttled, expired-session и success states +**And** сообщения содержат Request ID/Trace ID, но не раскрывают account existence или security internals. + +**Given** web-security test suite +**When** выполняются negative tests +**Then** покрыты bootstrap replay/race, brute-force throttling, session fixation, CSRF, hostile Origin, spoofed proxy headers, expired/revoked sessions и recovery misuse +**And** проходят Admin API integration tests, Playwright auth flows и `just verify`. + +### Story 1.13: Публиковать immutable Agent catalog + +As an администратор, +I want собирать и публиковать точный каталог разрешённых Tools для Agent, +So that MCP-клиент обнаруживает только утверждённые версии и получает стабильное поведение. + +**Requirements:** FR-4 + +**Acceptance Criteria:** + +**Given** Agent Draft +**When** администратор добавляет Tool binding +**Then** binding принимает только точную Published Operation Version из того же workspace +**And** Draft, archived Operation для нового binding или foreign-workspace capability отклоняется без metadata leakage. + +**Given** изменяемый Agent Draft +**When** администратор добавляет, удаляет или заменяет bindings и выбирает direct либо search mode +**Then** изменения сохраняются только в Draft revision +**And** текущий Published Agent catalog остаётся неизменным. + +**Given** валидный Agent Draft +**When** администратор публикует Agent +**Then** в одной PostgreSQL transaction создаются immutable Agent Version, exact binding snapshot и монотонно увеличенный `catalog_revision` +**And** MCP начинает читать новый snapshot только после успешного commit. + +**Given** concurrent edit или publish одного Agent Draft +**When** revision predicate устарел +**Then** операция возвращает conflict и не перезаписывает более новое состояние +**And** UI предлагает reload/review вместо автоматического повторения mutation. + +**Given** Published Agent Version +**When** связанная Operation получает новый Draft или новую Published Version +**Then** текущий Agent продолжает ссылаться на прежнюю точную Published Version +**And** обновление Tool требует нового Agent Draft, явной замены binding и повторной публикации. + +**Given** Agent в direct mode +**When** авторизованный MCP-клиент выполняет discovery +**Then** он получает только Tools immutable snapshot этого Agent с deterministic pagination +**And** Draft или Tool другого Agent отсутствует в результате. + +**Given** Agent в search mode +**When** MCP-клиент получает search result +**Then** result связан с Agent Version и `catalog_revision` +**And** после новой публикации устаревший result не может использоваться для вызова capability вне актуального snapshot. + +**Given** catalog cache +**When** публикуется новая Agent Version, Agent unpublish/archive или key revocation +**Then** cache key включает Agent ID/version/revision и full authorization scope, а stale projection инвалидируется +**And** потеря Valkey восстанавливает каталог из PostgreSQL без изменения correctness. + +**Given** Published Agent +**When** администратор выполняет unpublish или archive +**Then** новые MCP discovery/call requests перестают получать доступ согласно lifecycle contract +**And** immutable versions, bindings, Invocation History и audit evidence не удаляются и не переписываются. + +**Given** MCP key для конкретного Agent +**When** клиент обращается к endpoint другого Agent или revision +**Then** access отклоняется default-deny без раскрытия catalog metadata +**And** cache/session lookup сохраняет полный Agent/workspace/auth scope. + +**Given** Agent lifecycle UI на RU и EN +**When** выполняются edit, bind, publish, conflict resolution, unpublish или archive +**Then** реализованы loading, empty, error, confirmation и stale-response states +**And** UI явно показывает Draft versus Published Version и текущий `catalog_revision`. + +**Given** catalog performance test на Reference Deployment dataset +**When** выполняется Tool discovery +**Then** latency соответствует NFR-P4 — ≤150 ms p95 +**And** результат стабилен при 200 Agents и 2 000 Operations без draft leakage. + +**Given** automated test suite +**When** проверяется catalog lifecycle +**Then** покрыты atomic publish, concurrent conflict, exact-version pinning, direct/search modes, stale results, cache loss и cross-Agent/workspace negatives +**And** проходят registry, Admin API, MCP transport, Playwright и `just verify`. + +### Story 1.14: Сделать approvals атомарными и side effects честными + +As an администратор, +I want требовать точное и одноразовое подтверждение опасных Operations, +So that concurrent requests и retries не обходят approval и не создают неконтролируемые side effects. + +**Requirements:** FR-5 + +**Acceptance Criteria:** + +**Given** Published Operation Version с policy `approval_required` +**When** Agent запрашивает execution +**Then** до outbound dispatch вычисляется canonical input fingerprint и approval scope из workspace, Agent, Operation/version и input +**And** изменение любого элемента scope требует отдельного approval. + +**Given** несколько concurrent execution requests с одинаковым approval scope +**When** active approval отсутствует +**Then** в PostgreSQL создаётся один canonical pending approval record +**And** остальные requests получают ссылку на тот же record без конкурирующих approvals. + +**Given** active pending approval +**When** тот же request повторяется +**Then** возвращается существующий status и безопасная metadata +**And** новый approval cycle не создаётся без явного terminal outcome и нового разрешённого request. + +**Given** approval key +**When** выполняется approve или deny +**Then** проверяются workspace, Agent, Operation/version, fingerprint, key scope, key status и expiry +**And** foreign, revoked, malformed или wrong-purpose key отклоняется без metadata leakage. + +**Given** approve, deny, expiry или recovery происходят конкурентно +**When** выполняется state transition +**Then** PostgreSQL conditional update допускает ровно один разрешённый переход из текущего state +**And** проигравший caller получает deterministic prior/conflict outcome без перезаписи terminal decision. + +**Given** approved execution +**When** runtime собирается выполнить outbound dispatch +**Then** approval потребляется single-use атомарно с execution admission либо durable dispatch intent +**And** replay approval token не разрешает второй side effect. + +**Given** approval был выдан ранее +**When** перед dispatch изменились Agent publication, Operation version, credential status, deadline или authorization context +**Then** execution fail closed и не использует stale approval +**And** audit record объясняет безопасную причину отказа без раскрытия secret. + +**Given** mandatory approval/idempotency store недоступен +**When** Operation требует approval +**Then** execution отклоняется до outbound dispatch и dependency отражается в readiness +**And** Valkey или in-memory fallback не заменяет PostgreSQL authority. + +**Given** idempotency key для write Operation +**When** повторяется execution с тем же scoped key и тем же input fingerprint +**Then** возвращается ранее сохранённый outcome либо состояние существующей попытки +**And** тот же key с иным fingerprint возвращает conflict. + +**Given** write Operation без подтверждённого upstream idempotency contract +**When** после dispatch результат становится uncertain +**Then** Crank не обещает exactly-once и не выполняет автоматический retry +**And** outcome явно классифицируется как потенциально совершивший side effect с сохранённым attempt/audit trail. + +**Given** approval UI на RU и EN +**When** администратор просматривает, подтверждает или отклоняет request +**Then** UI показывает точные Agent, Operation Version, безопасный input summary, expiry, Request ID и Trace ID +**And** approve/deny имеют confirmation, loading, conflict, expired и stale-response states. + +**Given** approval security suite +**When** выполняются integration и race tests +**Then** покрыты concurrent creation/decision, token replay, fingerprint mismatch, cross-Agent/workspace access, key revocation, expiry, store outage и uncertain side effect +**And** проходят registry/runtime/Admin/MCP/Playwright tests и `just verify`. + +### Story 1.15: Предоставить безопасные Invocation History и Usage + +As an оператор Crank, +I want видеть фильтруемую историю и показатели выполнения, +So that могу диагностировать ошибки и оценивать качество работы Agents и Operations без доступа к чувствительным данным. + +**Requirements:** FR-6 + +**Acceptance Criteria:** + +**Given** завершённая или отклонённая Execution attempt +**When** формируется Invocation History record +**Then** сохраняются typed workspace, Agent, Operation/version, execution ID, outcome taxonomy, timestamps, duration, Request ID и Trace ID +**And** запись не содержит raw credential, arbitrary headers/body или unbounded error text. + +**Given** execution input и output +**When** создаются безопасные previews +**Then** применяется централизованная redaction и отдельные byte/field/depth limits с сохранением валидного UTF-8/JSON +**And** oversized content получает явный truncation marker вместо произвольного byte slicing. + +**Given** failure записи Invocation History после фактического execution outcome +**When** persistence недоступен или запись отклонена +**Then** исходный product result не заменяется ложным execution failure +**And** через typed `crank-metrics` увеличивается отдельный low-cardinality history-loss counter с alertable outcome. + +**Given** авторизованный Admin UI caller +**When** он открывает Logs +**Then** история фильтруется по bounded period, Agent, Operation и outcome с deterministic opaque pagination +**And** foreign-scope query не раскрывает counts, names или records. + +**Given** конкретная Invocation History record +**When** администратор открывает details +**Then** UI показывает stage, safe previews, duration, Agent, точную Operation Version, Request ID и Trace ID +**And** raw internal cause остаётся server-side. + +**Given** Usage query за период +**When** данные агрегируются +**Then** UI получает counts, success/failure outcomes и документированные latency percentiles по Agent и Operation +**And** upstream/client/schema outcomes отображаются отдельно от Crank-caused failures. + +**Given** period boundary +**When** агрегируются records на границе дня или timezone UI +**Then** storage/query contract использует UTC instants, а отображение локализует время только на presentation boundary +**And** один record не считается дважды из-за inclusive range overlap. + +**Given** CSV export +**When** администратор экспортирует отфильтрованный dataset +**Then** export применяет те же authorization, filters, redaction и bounded row/size policy, что и UI +**And** значения, способные вызвать spreadsheet formula injection, безопасно экранируются без повреждения CSV. + +**Given** configured Invocation History retention +**When** record достигает retention boundary +**Then** archive/delete выполняется по typed policy и наблюдаемому outcome +**And** удаление не повреждает Published Version audit, aggregate Usage или immutable release evidence. + +**Given** production-size dataset из 1 000 000 history records +**When** открываются основные Logs и Usage screens +**Then** они становятся интерактивными ≤2 s p95 в Reference Deployment LAN +**And** pagination/query не требует загрузки полного dataset в application memory или browser. + +**Given** Logs/Usage UI на RU и EN +**When** данные загружаются, отсутствуют, фильтруются, экспортируются или завершаются ошибкой +**Then** присутствуют loading, empty, error, retry и stale-response states +**And** workspace/request generation guard не позволяет старому response перезаписать новый filter context. + +**Given** automated verification +**When** выполняются history и usage suites +**Then** покрыты redaction, bounded previews, persistence loss, period boundaries, percentiles, CSV injection, retention, cross-scope access и production-size query plans +**And** проходят registry/Admin API/Playwright tests и `just verify`. + +### Story 1.16: Провести нового администратора к первому MCP Tool call + +As a новый self-hosted администратор, +I want пройти понятный возобновляемый путь от первого входа до вызова Tool, +So that получаю первую ценность без разработки и поиска последовательности по документации. + +**Requirements:** FR-1, FR-4, FR-33 + +**Acceptance Criteria:** + +**Given** администратор впервые завершил bootstrap/login в выбранном workspace +**When** открывается Admin UI +**Then** доступен необязательный Getting Started checklist с этапами `Operation → test → publish → Agent → key → MCP connection → first call` +**And** пользователь может свернуть/возобновить его, а dismiss не блокирует обычную навигацию. + +**Given** onboarding checklist +**When** определяется состояние шага +**Then** оно вычисляется из authoritative Published Versions, Agent catalog, key lifecycle и observed MCP outcomes, а не из дублирующего browser flag +**And** удалённый/revoked/изменённый объект возвращает шаг в честное actionable состояние. + +**Given** шаг создания Operation +**When** пользователь выбирает manual REST path +**Then** onboarding deep-link-ит в существующий полный UI flow с безопасным минимальным примером/подсказками +**And** не создаёт отдельную упрощённую domain model, скрытый Draft или обход validation/publish. + +**Given** успешный test и Published Operation +**When** пользователь продолжает onboarding +**Then** UI ведёт к созданию/публикации Agent с exact Tool Version и показывает catalog revision +**And** stale Operation/Agent revision требует явного refresh/reselection вместо silent binding. + +**Given** опубликованный Agent +**When** создаётся первый MCP key +**Then** raw key показывается только один раз вместе с copy-safe endpoint/client configuration для supported representative clients +**And** secret не сохраняется в local/session storage, telemetry или повторно читаемом onboarding state; UI предупреждает об ответственности системного clipboard. + +**Given** потерянный либо отозванный one-time key +**When** пользователь возвращается к connection step +**Then** UI не пытается восстановить raw value и предлагает безопасно создать/ротировать key +**And** старый configuration snippet явно считается недействительным. + +**Given** MCP client выполняет первый вызов +**When** он проходит public authenticated MCP endpoint, discovery и `tools/call` +**Then** checklist завершается только по authoritative successful outcome exact Agent/key scope +**And** UI показывает Tool, timestamp, Request ID/Trace ID и переходы в Invocation History/trace без sensitive payload. + +**Given** validation, upstream, auth, compatibility либо connection failure +**When** onboarding не может продолжиться +**Then** пользователь видит конкретный failed step, bounded RU/EN message, support IDs и recovery action +**And** retry продолжает с последнего подтверждённого шага без duplicate publication/key creation. + +**Given** refresh, reconnect, workspace/language change или parallel tab +**When** onboarding восстанавливается +**Then** server-authoritative progress и identity/revision guards предотвращают stale completion +**And** URL/back navigation, keyboard/focus/screen-reader status и reduced-motion соответствуют общему UI contract. + +**Given** local ProductEvents +**When** onboarding начинается, завершается или прекращается +**Then** фиксируются idempotent bounded milestones для SM-11…SM-13 с явным eligible denominator +**And** raw object/user identifiers и usage не покидают закрытый контур без opt-in. + +**Given** real-stack Playwright onboarding suite +**When** выполняется fresh manual REST path +**Then** покрыты first success ≤15 минут в reference usability run, refresh/resume, stale revision, lost key, failure recovery, RU/EN и accessibility +**And** вызов доказан через public MCP endpoint без test-only bypass, `just verify` проходит. + +## Epic 2: Надёжное создание Tools из реальных OpenAPI + +Пользователь загружает OpenAPI/Swagger, получает детерминированный preview, исправляет findings и атомарно создаёт пригодные к публикации Operations без silent loss. + +### Story 2.1: Реализовать безопасное immutable artifact storage + +As an оператор закрытого контура, +I want хранить загруженные bytes в отдельном защищённом content-addressed store, +So that последующие слои получают неизменяемый source без доверия к пользовательским путям. + +**Requirements:** FR-7, FR-9 + +**Depends on:** Epic 1 production foundation + +**Acceptance Criteria:** + +**Given** bounded source bytes +**When** `crank-artifacts` сохраняет artifact +**Then** SHA-256 становится единственным opaque physical reference, запись проходит через private temporary file, file fsync, atomic no-clobber publish и directory fsync +**And** повторная или конкурентная запись одинаковых bytes идемпотентно использует один immutable blob. + +**Given** read operation по opaque reference +**When** blob существует +**Then** store повторно вычисляет и проверяет digest до возврата bytes +**And** missing, truncated или corrupted blob возвращает typed integrity error без raw path/source в diagnostics. + +**Given** hostile filename, traversal, absolute path, symlink или root replacement race +**When** выполняется write/read/delete/list candidate +**Then** операция не выходит из configured artifact root и не следует symlink +**And** caller не может создать новый `file://` reference либо передать filesystem path вместо digest. + +**Given** crash, disk-full, interrupted publish или stale temporary file +**When** store восстанавливается либо запускает bounded housekeeping primitives +**Then** опубликованный blob остаётся либо полностью durable, либо отсутствует, временные файлы распознаются безопасно +**And** store не принимает policy-решение об удалении referenced blob без подтверждения registry. + +**Given** legacy absolute `file://` reference +**When** compatibility reader явно настроен оператором +**Then** read разрешён только внутри canonical validated legacy root и только с expected digest +**And** reference не переписывается и исходный файл не удаляется этой story. + +**Given** artifact crate test suite +**When** запускаются unit и filesystem integration tests +**Then** покрыты known digest, concurrent dedupe, corruption, crash boundaries, disk-full seam, traversal, symlink/root races, stale temp и legacy-root escape +**And** `cargo test -p crank-artifacts` и workspace formatting/lint gates проходят. + +### Story 2.2: Добавить workspace-scoped metadata artifacts + +As an администратор workspace, +I want artifact metadata быть транзакционными и изолированными по workspace, +So that дедупликация не раскрывает чужие source metadata, а последующий reconciliation получает строгий PostgreSQL contract. + +**Requirements:** FR-7, FR-9 + +**Depends on:** Story 2.1 + +**Acceptance Criteria:** + +**Given** действующая migration authority +**When** добавляется forward-only registry schema version +**Then** metadata хранит scoped source id, workspace owner, digest/ref, size, MIME, sensitivity, lifecycle state и timestamps +**And** прежние migration sources не изменяются, schema guard и clean/upgrade migration tests проходят. + +**Given** один physical digest связан с несколькими workspace +**When** metadata создаётся, читается или перечисляется +**Then** ownership relations независимы и все repository operations требуют authoritative workspace scope +**And** foreign id/ref возвращает обычный scoped not-found без existence, size или MIME oracle. + +**Given** одна и та же source identity либо digest replayed +**When** repository создаёт или изменяет scoped relation +**Then** identical replay идемпотентен, conflicting replay возвращает typed conflict, а lifecycle timestamps и detach transition проверяются транзакционно +**And** schema заранее содержит bounded blob lifecycle/claim fields, необходимые Stories 2.3 и 2.4, без запуска filesystem cleanup из этой story. + +**Given** metadata существует, но blob отсутствует или повреждён +**When** repository/service запрашивает source +**Then** typed availability/integrity outcome блокирует дальнейшую обработку +**And** система не подменяет source mutable external content и не удаляет metadata молча. + +**Given** scoped metadata с корректным, отсутствующим или повреждённым blob +**When** service выполняет verified read +**Then** корректные bytes возвращаются только после digest/size verification, а typed availability/integrity outcome блокирует дальнейшую обработку +**And** metadata сохраняется без external refetch, substitution или раскрытия raw source/path. + +**Given** registry metadata integration suite +**When** выполняются clean/V11→V12/replay/tamper/rollback, scoped CRUD/list/detach и verified-read scenarios +**Then** exact normalized schema guard отклоняет drift каждого V12 column/default/constraint/index и неожиданный V12-owned object без substring matching +**And** migration, replay, cross-workspace, missing/corrupt и pagination tests проходят последовательно и детерминированно. + +### Story 2.3: Artifact filesystem reconciliation + +As an оператор закрытого контура, +I want bounded filesystem reconciliation artifacts, +So that orphan candidates можно безопасно и resumable обнаруживать без полного inventory. + +**Requirements:** FR-7, FR-9 + +**Depends on:** Stories 2.1, 2.2 + +**Scope:** bounded filesystem scan, opaque continuation, capability revalidation, quarantine/delete primitives и filesystem fault classification. + +**Acceptance Criteria:** обязательны все пять групп из [Shared acceptance scope for Stories 2.3 and 2.4](#shared-acceptance-scope-for-stories-23-and-24) ниже в части filesystem contract. Это общие критерии двух stories, а не отсутствие AC у Story 2.3; индивидуальные подробности сохраняет canonical spec. + +### Story 2.4: Artifact claim recovery + +As an оператор закрытого контура, +I want bounded claim/recheck/finalize recovery coordination, +So that referenced blobs не удаляются, а crash/race outcomes безопасно возобновляются. + +**Requirements:** FR-7, FR-9 + +**Depends on:** Stories 2.1, 2.2, 2.3 + +**Scope:** PostgreSQL claim/recheck/finalize protocol, startup recovery и bounded Admin coordinator. + +#### Shared acceptance scope for Stories 2.3 and 2.4 + +Обе завершённые stories вместе сохраняют исходный общий scope acceptance criteria ниже; их разделение не меняет requirements или outcome. + +**Acceptance Criteria:** + +**Given** published bytes без metadata либо detached digest старше grace period +**When** reconciliation выполняет bounded streaming scan +**Then** filesystem traversal не строит полный tree inventory и останавливает syscall work при `scan_budget` либо `result_limit` +**And** opaque continuation указывает позицию до первого unreturned/retryable item, поэтому неизменный traversal выдаёт eligible set exact-once без starvation. + +**Given** orphan candidate claimed по digest +**When** одновременно появляется active source relation +**Then** транзакционный global reference recheck отклоняет stale claim до физической мутации +**And** capability revalidates root, shard, quarantine name/path и inode непосредственно перед idempotent unlink. + +**Given** unlink/quarantine mutation выполнена, но DB commit либо directory fsync завершился ошибкой или неопределённо +**When** текущий или следующий reconciliation восстанавливается +**Then** outcome типизирован как retryable/uncertain и сохраняет безопасный continuation до failed item либо явно начинает новый bounded cycle +**And** claim после возможного unlink не освобождается в `idle`; already-absent recovery идемпотентно доводит PostgreSQL state до `absent`. + +**Given** interrupted quarantine/delete, malformed namespace entry или exhausted batch +**When** startup recovery идёт до final orphan sweep +**Then** каждый item классифицируется как restored, deleted-duplicate, retryable, uncertain, integrity-blocked либо safety-blocked без пропуска последующей работы +**And** report содержит только bounded low-cardinality counts и usable continuation, без digest, workspace, source или filesystem path. + +**Given** reconciliation fault/race suite +**When** выполняются multi-page exact-once, multi-orphan post-delete continuation, attach-vs-cleanup, inode/name/path races, crash windows и fsync/DB failure injections +**Then** ни один active/referenced blob не удаляется, failed item не теряется, а restart завершает recoverable transitions детерминированно +**And** artifact, registry и Admin API integration suites вместе с workspace verification gates проходят. + +### Story 2.5: Ввести bounded multipart upload и verified OpenAPI preview + +As an администратор, +I want загрузить OpenAPI YAML или JSON через безопасный Admin API contract, +So that preview и последующий import ссылаются на одни и те же проверенные bytes. + +**Requirements:** FR-7, FR-9 + +**Depends on:** Stories 2.1, 2.2, 2.3, 2.4 + +**Acceptance Criteria:** + +**Given** authenticated workspace-scoped OpenAPI preview endpoint +**When** администратор передаёт один `.yaml`, `.yml` или `.json` файл через multipart +**Then** authorization/workspace, multipart shape, filename, media type, byte size (не более 256 KiB) и UTF-8 проверяются до artifact publish и parsing +**And** empty, oversized, malformed, duplicate-part или unsupported input отклоняется stable localized 4xx/413 outcome без metadata, import job или Draft Operations. + +**Given** допустимый upload +**When** Admin API создаёт source snapshot +**Then** orchestration выполняет durable blob write, scoped metadata commit и verified read, после чего parser получает именно сохранённые bytes +**And** import job хранит scoped source identity и digest, а не raw source или caller path. + +**Given** preview уже создан +**When** apply либо повторный preview использует source +**Then** source читается по scoped metadata и digest проверяется заново +**And** draft/input нельзя построить только из сохранённого preview JSON при отсутствующем или изменённом artifact. + +**Given** invalid parser input, storage/registry failure, cancellation или client disconnect +**When** request завершается ошибкой +**Then** частично созданные business entities отсутствуют, orphan обрабатывается lifecycle protocol +**And** RU/EN envelope содержит bounded code, Request ID и Trace ID без source, parser details и filesystem path. + +**Given** canary в examples/descriptions и полный request trace +**When** upload успешно или ошибочно проходит HTTP boundary +**Then** raw document отсутствует в logs, traces, metrics и response diagnostics +**And** request можно сопоставить в интерфейсе и GlitchTip по canonical Trace ID. + +**Given** outer Admin API integration suite +**When** тестируется реальный multipart router и service stack +**Then** покрыты valid YAML/JSON, malformed multipart, limits, unsupported encoding/MIME, scope isolation, restart, corruption, cancellation и no-Draft guarantees +**And** legacy JSON test-only compatibility path не считается доказательством production contract. + +### Story 2.6: Завершить OpenAPI upload UX и release evidence + +As an администратор, +I want понятный, локализованный и race-safe интерфейс загрузки OpenAPI, +So that я вижу актуальный результат файла и могу безопасно восстановиться после ошибки. + +**Requirements:** FR-7, FR-9 + +**Depends on:** Story 2.5 + +**Acceptance Criteria:** + +**Given** OpenAPI upload UI на RU и EN +**When** пользователь выбирает, валидирует, загружает, заменяет или отменяет файл +**Then** присутствуют keyboard-accessible idle, validating, uploading, error, cancelled и success states +**And** показываются только bounded metadata, Request ID/Trace ID и actionable recovery, без raw source и внутренних путей. + +**Given** file replacement, workspace/language change, navigation либо параллельный запрос +**When** старый response приходит позже нового +**Then** AbortController и monotonic identity/revision guard запрещают stale state update +**And** новый файл и authoritative workspace остаются выбранными. + +**Given** network, validation, integrity или service failure +**When** пользователь повторяет действие +**Then** retry не создаёт duplicate source relation или Draft Operations +**And** focus, screen-reader status и reduced-motion соответствуют общему UI contract. + +**Given** production documentation +**When** оператор настраивает artifact root, upload limits, backup/restore и reconciliation +**Then** docs точно описывают multipart contract, lifecycle, legacy compatibility, security boundaries и redacted observability +**And** не заявляют гарантий, не доказанных текущими tests/evidence. + +**Given** real-stack Playwright и release gates +**When** выполняются valid upload, replacement race, cancel, RU/EN, accessibility, restart и failure recovery scenarios +**Then** UI обращается к production multipart endpoint без test-only bypass и подтверждает canonical Trace ID +**And** artifact/registry/Admin API/Playwright suites, `just verify` и `just verify-ui` проходят либо внешний инфраструктурный blocker задокументирован с воспроизводимой командой. + +### Story 2.7: Преобразовать OpenAPI в детерминированный NormalizedIR + +As an администратор, +I want получить устойчивый анализ структуры загруженного API, +So that одинаковый документ всегда создаёт одинаковый preview и ни одна исходная конструкция не теряется молча. + +**Requirements:** FR-7, FR-8 + +**Acceptance Criteria:** + +**Given** verified source artifact +**When** `crank-import` начинает parsing +**Then** формат определяется по содержимому и поддерживает OpenAPI 3.0, OpenAPI 3.1 и Swagger 2.0 в YAML/JSON +**And** extension файла не используется как единственный источник версии или формата. + +**Given** parsing operation +**When** документ обрабатывается +**Then** parser остаётся pure относительно PostgreSQL, artifact metadata и Operations +**And** не создаёт Draft, ImportPlan или частичный domain state. + +**Given** syntactically valid document +**When** создаётся `NormalizedIR` +**Then** он содержит source digest/version, API metadata, server/base-path candidates, paths, methods, operation identifiers, tags и source locations +**And** каждый элемент имеет устойчивый source-construct ID для findings и coverage ledger. + +**Given** Swagger 2.0 либо OpenAPI 3.x document +**When** эквивалентные верхнеуровневые concepts нормализуются +**Then** различия версий отображаются в typed IR, а не в untyped JSON blob +**And** source-specific semantics сохраняются до последующих mapping stages. + +**Given** каждый распознанный source construct +**When** normalization завершается +**Then** construct связан с normalized representation либо explicit finding со stable code, severity и source location +**And** отсутствие mapping без finding считается validator failure. + +**Given** duplicate или отсутствующий `operationId` +**When** формируются internal candidate identities +**Then** importer применяет детерминированное naming rule из method/path/source order и создаёт явный finding +**And** повторный анализ не меняет имена из-за map ordering или runtime randomness. + +**Given** unsupported specification version, invalid root shape или документ без методов +**When** выполняется parsing +**Then** возвращается bounded structured blocker finding +**And** процесс не panic-ит, не создаёт пустой успешный import и не выводит raw parser internals. + +**Given** structural error, ограниченный одним endpoint +**When** остальные endpoints могут быть проанализированы +**Then** IR сохраняет валидные candidates и blocker finding повреждённого endpoint +**And** общий preview не разрешает Apply без explicit partial selection из последующей story. + +**Given** unresolved local или external reference +**When** parsing завершается до reference-resolution stage +**Then** IR содержит typed unresolved reference и source location +**And** parser не выполняет network или filesystem access самостоятельно. + +**Given** malicious YAML/JSON shape +**When** document превышает configured depth, node, alias, string или collection limits +**Then** parsing прерывается bounded error без unbounded CPU/memory growth +**And** diagnostic сохраняет валидный UTF-8/JSON и не включает исходный документ целиком. + +**Given** одинаковые source bytes и importer configuration +**When** normalization запускается многократно и конкурентно +**Then** canonical IR и ordered findings совпадают byte-for-byte +**And** source digest однозначно идентифицирует результат анализа. + +**Given** importer test suite +**When** выполняются fixture, property и fuzz regression tests +**Then** покрыты три версии specifications, YAML/JSON, duplicate IDs, empty/no-method documents, hostile nesting, aliases, malformed endpoints и deterministic ordering +**And** `crank-import` соблюдает architecture boundaries и проходит `just verify`. + +### Story 2.8: Безопасно разрешать references и schema composition + +As an администратор, +I want импортировать API со связанными schemas и разрешёнными external references, +So that сложные контракты сохраняют семантику и не создают SSRF или TOCTOU. + +**Requirements:** FR-9 + +**Acceptance Criteria:** + +**Given** local `$ref` внутри source artifact +**When** reference resolver обрабатывает JSON Pointer +**Then** target разрешается относительно immutable source snapshot с корректным escaping +**And** missing target, invalid pointer или type mismatch создаёт finding с source/target location без panic. + +**Given** external references по умолчанию +**When** документ содержит HTTP/HTTPS reference +**Then** network fetch не выполняется и reference получает explicit blocker/unsupported finding +**And** администратор видит, что требуется operator-controlled allowlist либо offline bundle. + +**Given** explicitly allowlisted external reference +**When** resolver загружает document +**Then** используется shared OutboundPolicy с более узким scheme/host/port/path/size contract, actual-address validation и disabled system proxy/implicit redirects +**And** credential из OpenAPI document или source URL не принимается автоматически. + +**Given** разрешённый external document +**When** preview загружает его успешно +**Then** bytes сохраняются как immutable content-addressed artifact с digest и ownership metadata +**And** NormalizedIR ссылается только на snapshot artifact, а не на mutable remote URL. + +**Given** remote content изменилось после preview +**When** ImportPlan применяется позднее +**Then** Apply использует сохранённые snapshot digests и не выполняет повторный network fetch +**And** получение новых remote bytes требует нового preview и нового plan digest. + +**Given** относительная external reference chain +**When** resolver вычисляет следующий target +**Then** URL нормализуется относительно текущего snapshot origin в пределах allowlist и bounded hop/depth/count limits +**And** traversal к `file:`, loopback, private service или иному запрещённому origin блокируется. + +**Given** recursive или cyclic references +**When** resolver строит schema graph +**Then** recursion представляется typed graph reference в пределах supported semantics +**And** превышение cycle/depth/expanded-size limits создаёт blocker finding без бесконечной рекурсии или schema duplication. + +**Given** `allOf` composition +**When** branches совместимы +**Then** required fields, properties, constraints и source provenance объединяются детерминированно +**And** conflicting constraints создают явный blocker вместо last-write-wins. + +**Given** `oneOf`, `anyOf` или discriminator +**When** capability schema может сохранить конструкцию без semantic loss +**Then** alternatives и discriminator mapping остаются typed в resolved IR +**And** неподдерживаемая комбинация блокирует affected candidate с точным finding, а не упрощается молча. + +**Given** OpenAPI 3.0 и 3.1 имеют различную `$ref` sibling semantics +**When** resolver обрабатывает sibling fields +**Then** применяется правило фактической specification version +**And** результат и finding подтверждены отдельными fixtures. + +**Given** один reference target повреждён или недоступен +**When** остальные candidates анализируются +**Then** affected dependency graph получает blocker finding, остальные candidates остаются в preview +**And** Apply всего документа остаётся запрещён без explicit partial selection. + +**Given** concurrent previews разных workspace +**When** они используют одинаковые URLs или bytes +**Then** resolution cache и ownership metadata включают полный security scope +**And** timing, error или cache response не раскрывает другому workspace наличие snapshot. + +**Given** reference/composition test suite +**When** выполняются fixtures и negative tests +**Then** покрыты local refs, escaped pointers, external allow/deny, redirects, DNS rebinding, relative chains, TOCTOU, cycles, recursion, `allOf` conflicts, `oneOf`/`anyOf` и discriminators +**And** raw remote content и credentials отсутствуют в logs/errors, а `just verify` проходит. + +### Story 2.9: Сохранить полный поддерживаемый HTTP contract + +As an администратор, +I want получить из каждого поддерживаемого endpoint точный Operation candidate, +So that созданный Tool принимает и возвращает те же данные, которые определены исходным API. + +**Requirements:** FR-8 + +**Acceptance Criteria:** + +**Given** resolved OpenAPI endpoint +**When** importer определяет HTTP method +**Then** поддерживаются `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` и `OPTIONS` +**And** `TRACE`, `CONNECT` и неизвестные methods получают explicit unsupported finding. + +**Given** parameters на path-level и operation-level +**When** они нормализуются +**Then** path, query, header и cookie parameters объединяются согласно правилам specification version +**And** operation-level override не создаёт duplicate либо silent replacement. + +**Given** каждый parameter +**When** строится Operation input schema и request mapping +**Then** сохраняются location, required, default, enum, nullable, format и применимые serialization semantics +**And** одинаковые имена в разных locations не конфликтуют во внутренней typed model. + +**Given** path parameter +**When** исходная specification ошибочно не помечает его required либо не содержит соответствующего path placeholder +**Then** candidate получает blocker finding +**And** importer не создаёт URL template с неоднозначной подстановкой. + +**Given** OpenAPI request body +**When** content type поддерживается +**Then** JSON, `application/x-www-form-urlencoded` и `multipart/form-data` преобразуются в typed input schema и deterministic mapping +**And** required body, required fields и content type сохраняются. + +**Given** multipart body +**When** schema содержит text, scalar, array или binary/file fields +**Then** importer сохраняет field names, required status, MIME metadata и bounded upload expectations +**And** unsupported multipart encoding получает finding вместо silent fallback к JSON. + +**Given** XML request/response media type +**When** он обнаружен +**Then** affected content variant получает explicit unsupported finding в соответствии с release scope +**And** XML не преобразуется неявно в JSON или text. + +**Given** endpoint с одним или несколькими успешными `2xx` responses +**When** строится output contract +**Then** сохраняются status codes, content types и все поддерживаемые success schemas +**And** importer не выбирает произвольно первый response и не теряет остальные branches. + +**Given** `204 No Content`, `HEAD` либо success response без body +**When** строится output schema +**Then** candidate получает явный no-content outcome без требования JSON body +**And** runtime mapping не классифицирует корректный пустой response как schema error. + +**Given** API/server/base-path metadata +**When** строится REST target template +**Then** scheme, host, port и base path нормализуются без embedded credential и проходят typed validation +**And** фактическое execution по-прежнему подчиняется OutboundPolicy из Story 1.9. + +**Given** descriptions, examples или defaults из source document +**When** они включаются в candidate preview +**Then** значения bounded и не влияют на executable mapping без явного typed contract +**And** secret-like examples создают finding и не попадают в generated headers/Auth Profile. + +**Given** unsupported parameter style, schema keyword, content type или response shape +**When** candidate формируется +**Then** coverage ledger содержит точный source construct и finding severity +**And** blocker semantic loss не может быть помечена как actionable Draft. + +**Given** одинаковый resolved IR +**When** HTTP mapping запускается повторно +**Then** Operation candidates, input/output schemas и mappings совпадают детерминированно +**And** каждый candidate можно сериализовать и валидировать без обращения к исходному parser state. + +**Given** HTTP-contract test suite +**When** выполняется representative matrix +**Then** покрыты все обязательные methods, четыре parameter locations, JSON/form/multipart, multiple 2xx, 204, defaults/enums/nullability/formats и unsupported XML +**And** каждый fixture доказывает expected semantics либо expected finding, а `just verify` проходит. + +### Story 2.10: Привязать security schemes через безопасный import API + +**Depends on:** Story 2.9, Story 1.10 + +**Work type:** implementation + +**Deliverable:** Привязать security schemes через безопасный import API. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want сопоставлять OpenAPI security requirements с Auth Profiles через import API, +So that безопасно сохраняю authentication contract без импорта credentials. + +**Requirements:** FR-10 + +**Acceptance Criteria:** + +**Given** OpenAPI 3.x `components.securitySchemes` или Swagger 2.0 `securityDefinitions` +**When** importer анализирует schemes +**Then** bearer HTTP, basic HTTP и API key в header/query/cookie преобразуются в typed security metadata +**And** source names, locations и применимые format hints сохраняются без credential values. + +**Given** global security requirement +**When** Operation не задаёт собственный override +**Then** candidate наследует global requirement согласно specification semantics +**And** operation-level requirement или explicit no-auth корректно заменяет global rule. + +**Given** security requirement с несколькими alternatives +**When** source определяет OR-семантику +**Then** preview сохраняет все допустимые alternatives и позволяет выбрать поддерживаемый вариант +**And** importer не объединяет alternatives в ложное обязательное AND. + +**Given** security requirement, требующий несколько schemes одновременно +**When** source определяет AND-семантику +**Then** candidate сохраняет составное требование, если runtime contract его поддерживает +**And** иначе affected Operation получает blocker finding с перечислением несохраняемой semantics. + +**Given** bearer, basic или API-key requirement +**When** формируется preview +**Then** администратору предлагается выбрать совместимый Auth Profile из текущего workspace либо оставить явный unresolved binding +**And** unresolved required authentication блокирует actionable Draft/Apply для affected Operation. + +**Given** выбранный Auth Profile +**When** создаётся candidate или ImportPlan +**Then** сохраняется только typed `AuthProfileRef` и scheme metadata +**And** raw secret, password, token, API key, hash или encrypted ciphertext не копируется в source snapshot, IR, findings, plan или Operation export. + +**Given** OAuth2, OpenID Connect, mutual TLS или неизвестная scheme +**When** release scope не поддерживает автоматическое mapping +**Then** importer создаёт explicit manual-configuration/unsupported finding +**And** не извлекает client secret, token URL credential, example token или vendor-extension secret. + +**Given** OpenAPI document содержит literal credential в example, default, extension, URL userinfo или header example +**When** security analysis выполняется +**Then** значение не используется как credential и создаёт redacted secret finding +**And** raw value не появляется в preview UI, logs, traces, metrics или diagnostics. + +**Given** Auth Profile был отозван, удалён или принадлежит другому workspace +**When** preview либо Apply проверяет binding +**Then** reference отклоняется до создания Draft +**And** ошибка не раскрывает metadata foreign profile. + +**Given** исходная security scheme изменилась после preview +**When** старый ImportPlan пытаются применить к новому source +**Then** plan digest mismatch блокирует Apply +**And** требуется новый preview и явное подтверждение Auth Profile mappings. + +**Given** security scheme test suite +**When** выполняются fixtures и negative tests +**Then** покрыты global/operation overrides, no-auth, bearer/basic/API-key locations, OR/AND requirements, OAuth/OpenID/unknown schemes, secret-like examples, revoked и cross-workspace refs +**And** redaction tests и `just verify` проходят. + +### Story 2.11: Выбирать security mappings в OpenAPI UI + +**Depends on:** Story 2.10 + +**Work type:** implementation + +**Deliverable:** Выбирать security mappings в OpenAPI UI. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want выбирать profile и security alternative в OpenAPI UI, +So that вижу unresolved/resolved/blocker state без раскрытия secrets. + +**Requirements:** FR-10 + +**Acceptance Criteria:** + +**Given** preview сохраняет OR alternatives и required authentication +**When** администратор выбирает alternative либо совместимый Auth Profile текущего workspace +**Then** UI передаёт выбор существующему import API и показывает authoritative resolved/unresolved/blocker status +**And** raw credentials не вводятся в mapping state и не копируются в IR/plan. + +**Given** смена alternative, удалённый/отозванный profile либо stale preview response +**When** API повторно валидирует binding +**Then** UI показывает safe blocker/revalidation guidance, не выдаёт предыдущий resolved state за текущий +**And** OR/AND semantics, workspace validation и secret redaction остаются ответственностью API Story 2.10. + +**Given** security-mapping UI на RU и EN +**When** пользователь выбирает profile, меняет alternative или получает unsupported scheme +**Then** UI показывает required/unresolved/resolved status, safe profile metadata и blocker findings +**And** loading, empty, error и stale-response states не раскрывают secrets. + +### Story 2.12: Предоставить полный preview и явный partial mode + +**Depends on:** Story 2.11 + +**Work type:** implementation + +**Deliverable:** Предоставить полный preview и явный partial mode. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want до импорта просмотреть все будущие Operations и проблемы документа, +So that могу осознанно исправить контракт либо импортировать только безопасную выбранную часть. + +**Requirements:** FR-7 + +**Acceptance Criteria:** + +**Given** успешно проанализированный source snapshot +**When** backend формирует preview +**Then** он возвращает groups/tags, endpoint candidates, proposed names, methods/paths, input/output schemas, mappings, security bindings, conflicts, warnings и unsupported findings +**And** каждый элемент связан с source location и stable finding code. + +**Given** preview request +**When** parsing, resolution и mapping завершаются +**Then** ни одна Operation, Operation Version, Agent binding или Auth Profile не создаётся и не изменяется +**And** единственными сохраняемыми объектами являются immutable source snapshots и preview/plan artifacts. + +**Given** одинаковые source digests, importer config, catalog revision и user selections +**When** preview формируется повторно +**Then** ordered candidates, findings, summary и plan digest совпадают детерминированно +**And** runtime timestamps и request IDs не входят в canonical digest. + +**Given** generated candidate names +**When** обнаружены duplicate, invalid или уже занятые names +**Then** UI показывает deterministic rename proposal и conflict type +**And** пользователь может выбрать разрешённое имя без изменения исходного snapshot. + +**Given** candidate без blocker findings и с разрешённой authentication +**When** preview оценивает готовность +**Then** candidate получает status `actionable` +**And** status вычисляется из typed findings/requirements, а не устанавливается клиентом произвольно. + +**Given** хотя бы один blocker finding +**When** пользователь не включал partial mode +**Then** Apply всего документа запрещён +**And** UI показывает полный blocker count и affected candidates без создания частичного набора Operations. + +**Given** пользователь явно включает partial mode +**When** он выбирает subset candidates +**Then** selected set может содержать только actionable candidates с замкнутыми разрешёнными dependencies +**And** excluded/blocked candidates и причина исключения сохраняются в ImportPlan и итоговом report. + +**Given** изменение selection, proposed name, Auth Profile mapping или conflict policy +**When** пользователь подтверждает новый preview state +**Then** создаётся новая immutable ImportPlan version с новым digest +**And** прежний plan остаётся доступным для audit, но не изменяется in place. + +**Given** immutable ImportPlan +**When** он сохраняется +**Then** plan связывает source и external snapshot digests, importer/support-matrix version, catalog revision, candidates, selections, mappings, findings и conflict decisions +**And** не содержит raw credentials или mutable remote references. + +**Given** catalog либо Auth Profile state изменились после preview +**When** UI повторно открывает plan +**Then** plan получает stale/revalidation-required status +**And** UI не утверждает, что прежний actionable status гарантирует успешный Apply. + +**Given** preview большого документа +**When** UI отображает до 2 000 candidates и bounded findings +**Then** используются search/filter/grouping и bounded pagination/virtualized rendering без загрузки unbounded DOM +**And** основной экран становится интерактивным ≤2 s p95 на Reference Deployment LAN. + +**Given** preview UI на RU и EN +**When** пользователь загружает реальный `openapi.yaml`, меняет selection или получает findings +**Then** UI реализует uploading, parsing, loading, empty/no-methods, error, actionable, blocked, stale и confirmation states +**And** request generation guard не позволяет старому preview перезаписать новый файл или selection. + +**Given** end-to-end upload regression +**When** загружаются valid `openapi.yaml`, invalid, empty, oversized и no-method documents +**Then** valid case показывает методы именно загруженного файла, остальные дают точные pre-mutation outcomes +**And** database assertions подтверждают отсутствие созданных Operations до Apply. + +**Given** preview verification suite +**When** выполняются API/Playwright tests +**Then** покрыты deterministic output, blockers, explicit partial selection, dependency closure, naming conflicts, stale plan, cross-workspace access и no-mutation contract +**And** `just verify` и UI build проходят. + +### Story 2.13: Атомарно применять ImportPlan и обрабатывать re-import + +**Depends on:** Story 2.12 + +**Work type:** implementation + +**Deliverable:** Атомарно применять ImportPlan и обрабатывать re-import. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want применить подтверждённый ImportPlan с выбранной conflict policy, +So that импорт создаёт ровно ожидаемые Draft Operations и безопасно переживает retries и concurrency. + +**Requirements:** FR-11 + +**Acceptance Criteria:** + +**Given** request на Apply +**When** Admin API принимает plan reference, digest и idempotency key +**Then** проверяются workspace ownership, Admin authorization, immutable plan digest и bounded request contract +**And** raw candidate data от клиента не используется вместо сохранённого ImportPlan. + +**Given** валидный ImportPlan +**When** начинается Apply +**Then** повторно проверяются source/external artifact digests, importer/support-matrix version, selected candidates, dependency closure, Auth Profile refs и актуальные conflicts +**And** stale либо повреждённый plan блокируется до mutation с re-preview guidance. + +**Given** default full-import plan +**When** хотя бы один selected candidate больше не actionable +**Then** весь Apply отклоняется без создания или изменения Operations +**And** report перечисляет точные revalidation failures. + +**Given** explicit partial ImportPlan +**When** он применяется +**Then** одной transaction обрабатывается ровно подтверждённый selected set +**And** excluded candidates не создаются неявно и сохраняются в report с причиной исключения. + +**Given** candidate без существующего Operation conflict +**When** Apply создаёт результат +**Then** создаются новая Operation и её Draft Version с contract из plan +**And** созданный Draft не становится доступным в Agent/MCP до отдельной публикации. + +**Given** conflict policy `skip` +**When** соответствующая Operation уже существует +**Then** существующее состояние не изменяется, candidate получает outcome `skipped` +**And** report связывает outcome с exact existing identity без раскрытия foreign-scope metadata. + +**Given** conflict policy `rename` +**When** выбранное новое имя свободно и валидно +**Then** создаётся отдельная Operation с подтверждённым именем +**And** runtime не генерирует другое имя во время Apply. + +**Given** conflict policy `new_version` +**When** target Operation принадлежит workspace и совместима с versioning contract +**Then** создаётся новая Draft Version без изменения текущей Published Version +**And** предыдущие versions, Agent bindings и Invocation History остаются immutable. + +**Given** concurrent Apply одного либо пересекающихся plans +**When** возникает uniqueness/revision conflict +**Then** PostgreSQL locks/conditional predicates допускают один согласованный commit +**And** проигравший Apply возвращает deterministic conflict/re-preview outcome без частичной mutation. + +**Given** повтор Apply с тем же scoped idempotency key и тем же plan digest +**When** первоначальный Apply уже committed +**Then** возвращается тот же immutable result report без создания дополнительных versions +**And** тот же key с другим digest возвращает conflict. + +**Given** crash до transaction commit +**When** клиент повторяет Apply +**Then** отсутствует частично видимое domain state, а replay может выполнить plan заново +**And** orphan artifact cleanup не удаляет snapshots действующего plan. + +**Given** crash после commit, но до HTTP response +**When** клиент повторяет request +**Then** idempotency record возвращает committed result +**And** Operations и versions не дублируются. + +**Given** успешный или отклонённый Apply +**When** формируется итоговый report +**Then** report immutable и содержит plan/source digests, counts и outcomes `created`, `versioned`, `renamed`, `skipped`, `rejected` для каждого candidate +**And** report bounded, redacted и доступен в human-readable и machine-readable form. + +**Given** Apply UI на RU и EN +**When** пользователь подтверждает import, ожидает результат или получает stale/conflict outcome +**Then** UI показывает exact candidate counts, destructive/versioning consequences, loading, success, partial, conflict и retry guidance +**And** duplicate click или stale response не запускает второй логический Apply. + +**Given** Apply integration suite +**When** выполняются transaction, crash и concurrency tests +**Then** покрыты все conflict policies, full/partial atomicity, idempotent replay, changed digest, Auth Profile revocation, concurrent plans и Draft isolation +**And** проходят registry/Admin API/Playwright tests и `just verify`. + +### Story 2.14: Зафиксировать OpenAPI support matrix и regression corpus + +**Depends on:** Story 2.13 + +**Work type:** implementation + +**Deliverable:** Зафиксировать OpenAPI support matrix и regression corpus. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As a владелец релиза, +I want иметь исполняемую матрицу поддержки и репрезентативный corpus OpenAPI, +So that качество importer измеряется по сохраняемой семантике, а не по числу созданных Operations. + +**Requirements:** FR-12 + +**Acceptance Criteria:** + +**Given** normative support matrix +**When** описывается OpenAPI/Swagger construct +**Then** запись содержит specification/version, construct ID, status `supported` или `unsupported`, точную сохраняемую semantics и expected finding +**And** неопределённый `partial` status без явного пользовательского выбора запрещён. + +**Given** обязательный baseline matrix +**When** проверяется полнота +**Then** она включает все REST methods кроме `TRACE`/`CONNECT`, path/query/header/cookie parameters, JSON/form/multipart bodies, все `2xx` responses, local и allowlisted external refs, common composition и bearer/basic/API-key schemes +**And** XML и другие non-goals перечислены с explicit unsupported outcome. + +**Given** versioned regression corpus +**When** он формируется +**Then** corpus содержит не менее 50 checksummed реальных или синтетических OpenAPI 3.0, OpenAPI 3.1 и Swagger 2.0 specifications +**And** provenance/license либо synthetic origin каждого fixture документированы. + +**Given** corpus fixture +**When** harness выполняет preview +**Then** fixture содержит expected candidates, schemas/mappings, findings, actionable/blocker statuses и canonical digest +**And** любое отличие создаёт readable deterministic diff. + +**Given** selected end-to-end fixtures +**When** harness выполняет полный workflow +**Then** документ загружается через реальный upload contract, preview формирует ImportPlan, Apply создаёт Draft, а representative Operation проходит validate/publish/test/MCP call +**And** bypass parser/import APIs не считается end-to-end evidence. + +**Given** все Operations в утверждённом representative corpus +**When** вычисляется import quality +**Then** ≥95% становятся actionable Draft без blocker finding +**And** denominator, exclusions и raw counts фиксируются в immutable result artifact. + +**Given** source construct coverage ledger +**When** corpus run завершается +**Then** каждый construct соответствует expected normalized semantics либо explicit expected finding +**And** silent loss относительно support matrix равен нулю и блокирует gate независимо от actionable percentage. + +**Given** defect importer +**When** исправление принимается +**Then** сначала добавляется минимальный воспроизводящий fixture и failing regression +**And** fixture остаётся в corpus после исправления. + +**Given** hostile-input subset +**When** выполняются security/reliability cases +**Then** покрыты empty, malformed, oversized, deep/alias-heavy documents, reference cycles, external-ref policy, duplicate IDs, composition conflicts и secret-like examples +**And** harness доказывает bounded resources, no mutation on blocker и redacted outputs. + +**Given** изменение support matrix, importer semantics или corpus expectation +**When** создаётся pull request +**Then** matrix/corpus version повышается, diff требует review, а новый checksum включается в evidence +**And** существующий expectation нельзя переписать без объяснения compatibility impact. + +**Given** corpus execution в CI +**When** suites запускаются повторно или параллельно +**Then** результаты не зависят от network, wall-clock ordering или shared mutable database +**And** обязательные tests не flaky и используют immutable/offline fixtures. + +**Given** опубликованная compatibility documentation +**When** пользователь проверяет возможности importer +**Then** human-readable matrix генерируется либо проверяется против machine-readable source +**And** маркетинговое описание не шире исполняемого evidence. + +**Given** завершение Epic 2 verification +**When** запускаются importer, artifact, registry, API, Playwright и corpus suites +**Then** FR-7…FR-12 связаны с immutable evidence, `just verify` проходит +**And** Capability Inventory обновлена без преждевременного статуса production-ready. + +### Story 2.15: Добавить OpenAPI-ветку в guided onboarding + +**Depends on:** Story 2.14 + +**Work type:** implementation + +**Deliverable:** Добавить OpenAPI-ветку в guided onboarding. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As a новый self-hosted администратор, +I want начать onboarding с готового `openapi.yaml`, +So that получаю первый MCP Tool call без ручного переноса REST-контракта. + +**Requirements:** FR-7, FR-11, FR-33 + +**Acceptance Criteria:** + +**Given** onboarding из Story 1.16 +**When** пользователь выбирает OpenAPI path +**Then** UI ведёт в существующий bounded upload/preview flow и сохраняет onboarding return context +**And** не создаёт отдельный importer или упрощённый parser path. + +**Given** preview с actionable endpoints +**When** пользователь выбирает endpoint и conflict/partial policy +**Then** onboarding показывает methods, findings, exact proposed Operation и последствия apply +**And** blocker/unsupported finding нельзя скрыть ради продолжения checklist. + +**Given** import требует Auth Profile +**When** security scheme сопоставляется +**Then** пользователь создаёт/выбирает только secret reference через canonical Auth Profile UI +**And** raw credential не попадает в OpenAPI artifact или onboarding state. + +**Given** atomic ImportPlan apply завершён +**When** создано несколько Draft Operations +**Then** пользователь явно выбирает одну actionable Draft для test/publish, остальные остаются в обычном import report +**And** onboarding не публикует endpoint автоматически. + +**Given** refresh, conflict либо исправление source +**When** import повторяется +**Then** checklist восстанавливается из authoritative ImportPlan/Operation state и не создаёт duplicate version +**And** changed source digest требует новый preview/confirmation. + +**Given** OpenAPI onboarding events +**When** пользователь достигает publication и первого MCP call +**Then** local rollups различают eligible import, import-to-publish и Agent activation без raw specification/user IDs +**And** data egress остаётся opt-in. + +**Given** real-stack Playwright suite +**When** новый пользователь загружает representative `openapi.yaml` +**Then** он проходит preview → apply → test → publish → Agent/key → public MCP call с RU/EN, refresh и failure recovery +**And** reference usability run и `just verify` проходят без test-only bypass. + +## Epic 3: Полноценный современный MCP-каталог + +Пользователь создаёт и публикует Tools, Resources и Prompts, связывает их с Agent и использует через совместимые MCP-клиенты. + +### Story 3.1: Согласовывать MCP revision и точные capabilities + +**Depends on:** Story 1.13 + +**Work type:** implementation + +**Deliverable:** Согласовывать MCP revision и точные capabilities. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an интегратор MCP-клиента, +I want endpoint явно согласовывать поддерживаемую protocol revision и capabilities, +So that клиент не полагается на поведение, которого сервер не реализует. + +**Requirements:** FR-13 + +**Acceptance Criteria:** + +**Given** наступление feature freeze +**When** утверждается MCP support window +**Then** из официальных stable specifications выбираются latest stable revision и две предыдущие поддерживаемые stable revisions +**And** конкретные versions, source digests и дата выбора фиксируются в Capability Inventory. + +**Given** существующая поддержка `2025-03-26` +**When** selected stable window её больше не включает +**Then** revision сохраняется до отдельного evidence-backed deprecation gate +**And** удаление не выполняется попутно с добавлением новых adapters. + +**Given** официальная stable MCP specification +**When** формируется server capability inventory +**Then** каждая capability и extension получает status `supported`, `not_applicable`, `experimental` или `deferred`, owner, fallback и evidence target +**And** применимая stable capability со status `deferred` блокирует feature-complete gate. + +**Given** клиент MCP `2026-07-28` +**When** он начинает работу с public endpoint +**Then** stateless adapter обслуживает обязательный `server/discover`, request-scoped metadata и применимые стандартные headers без initialize/session dependency +**And** рекламирует только реально реализованные methods/extensions. + +**Given** клиент одной из selected legacy revisions из Capability Inventory +**When** он выполняет initialize и последующие session requests +**Then** отдельный legacy adapter сохраняет согласованный lifecycle, headers и negotiation semantics +**And** ни один session contract не протекает в stateless adapter либо shared method services. + +**Given** unsupported, malformed или отсутствующая protocol identity +**When** request достигает соответствующего protocol-era adapter +**Then** endpoint возвращает структурированную revision-correct error либо только разрешённый specification fallback +**And** не угадывает adapter, experimental behavior или ложную session state. + +**Given** одна public MCP route +**When** запросы разных revisions поступают одновременно +**Then** version-specific headers, lifecycle, pagination, notifications и result shapes изолированы adapters +**And** shared method services получают typed internal requests без transport-specific DTO leakage. + +**Given** protocol adapter foundation +**When** capability либо extension добавляется последующей Story +**Then** Story 3.1 предоставляет единый typed registration mechanism для `server/discover` и legacy negotiation +**And** конкретный descriptor и method mapping принадлежат Story соответствующей capability, а не transport router. + +**Given** release-candidate или experimental MCP extension +**When** оператор включает её отдельной configuration +**Then** capability рекламируется только совместимому opted-in клиенту +**And** extension не становится единственным путём для критичного Tool и может быть выключена без потери stable core. + +**Given** клиент без Resources, Prompts или Tasks extension +**When** он завершает negotiation +**Then** сервер не отправляет неподдерживаемые methods/notifications +**And** Tools остаются доступны через согласованный stable path. + +**Given** request одного protocol era +**When** он использует lifecycle/header semantics другого era либо несовместимую revision +**Then** transport отклоняет request stable protocol error +**And** не маршрутизирует его молча в другой adapter и не создаёт скрытую state. + +**Given** изменение transport negotiation +**When** проверяются architecture boundaries +**Then** MCP headers, Accept negotiation, session и JSON/SSE semantics остаются в `crank-community-mcp` transport boundary +**And** core/application services не импортируют protocol-version DTOs. + +**Given** protocol fixture suite +**When** выполняется negotiation matrix +**Then** RED-first wire fixtures покрывают `server/discover`/stateless lifecycle `2026-07-28`, initialize/session lifecycle selected `2025-*`, malformed/unsupported versions, concurrent mixed clients и disabled experimental adapters +**And** advertised capabilities byte-for-byte соответствуют executable inventory. + +**Given** актуальный официальный Rust MCP SDK +**When** проектируется adapter `2026-07-28` +**Then** выполняется bounded compatibility assessment против существующих architecture boundaries, MSRV и transport tests +**And** default decision сохраняет существующий transport; SDK принимается только отдельным evidence-backed ADR/dependency change, а wire-level conformance остаётся обязательной при любом выборе. + +### Story 3.2: Обнаруживать Published Tools + +**Depends on:** Story 3.1 + +**Work type:** implementation + +**Deliverable:** Обнаруживать Published Tools. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an MCP-пользователь, +I want надёжно получать точный список опубликованных Tools, +So that discovery и pagination соответствуют immutable Agent catalog. + +**Requirements:** FR-14 + +**Acceptance Criteria:** + +**Given** авторизованный клиент Published Agent +**When** он вызывает `tools/list` +**Then** service возвращает только Tools immutable Agent snapshot с точными names, descriptions и input/output schemas +**And** Draft, archived/unpublished Agent или capability вне Agent scope не обнаруживается. + +**Given** Tool list больше page limit +**When** клиент запрашивает следующую страницу +**Then** используется opaque bounded cursor, связанный с Agent Version, `catalog_revision`, authorization scope и stable ordering +**And** cursor другого Agent/revision либо malformed cursor отклоняется safe protocol error. + +**Given** catalog изменился после выдачи cursor +**When** клиент продолжает старую pagination +**Then** service возвращает explicit stale-cursor outcome либо version-consistent snapshot согласно negotiated revision +**And** страницы разных revisions не смешиваются и не пропускают/дублируют Tools молча. + +**Given** production-size Agent catalog +**When** выполняется `tools/list` +**Then** discovery соответствует NFR-P4 ≤150 ms p95 и не загружает полный catalog в transport memory +**And** schema serialization остаётся bounded. + +**Given** Tools discovery suite +**When** она выполняется для каждой supported revision +**Then** покрыты scope, schemas, pagination, malformed/stale cursor, revision consistency и negative auth +**And** protocol fixtures, representative client smoke и `just verify` проходят. + +### Story 3.3: Вызывать Published Tools со structured outcomes + +**Depends on:** Story 3.2 + +**Work type:** implementation + +**Deliverable:** Вызывать Published Tools со structured outcomes. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an MCP-пользователь, +I want безопасно вызывать Tool и получать revision-correct результат, +So that validation и ошибки не зависят от transport implementation. + +**Requirements:** FR-14 + +**Acceptance Criteria:** + +**Given** валидный `tools/call` +**When** client передаёт input +**Then** input валидируется против exact Published Operation schema до execution +**And** неизвестные, missing, wrong-type или oversized values возвращают structured schema error без outbound dispatch. + +**Given** успешное Tool execution +**When** runtime возвращает normalized outcome +**Then** version adapter формирует допустимые negotiated structured content и metadata +**And** raw upstream response, internal DTO или unsupported content variant не пересекают MCP boundary. + +**Given** request MCP `2026-07-28` содержит request-scoped `_meta` +**When** Tool service обрабатывает вызов +**Then** adapter валидирует size/schema, передаёт только разрешённые typed hints и не использует untrusted metadata для authorization, scope или metric labels +**And** legacy adapters не получают неподдерживаемые поля и не меняют семантику Tool. + +**Given** negotiated revision поддерживает `resultType`, cache hints либо multi-round Tool result contract +**When** Tool формирует результат +**Then** adapter выдаёт только опубликованный и валидированный contract этой revision либо machine-readable `not_applicable` evidence +**And** legacy result остаётся revision-correct без неизвестных полей или скрытого continuation state. + +**Given** schema, authorization, approval, mapping, outbound, upstream или runtime failure +**When** Tool call завершается ошибкой +**Then** клиент получает structured safe error с корректным protocol shape и explicit retryability там, где revision это допускает +**And** Invocation History сохраняет точную internal outcome taxonomy, Request ID и Trace ID. + +**Given** production Reference Workload +**When** выполняется `tools/call` +**Then** platform execution overhead соответствует NFR-P4 p95/p99 limits +**And** input/result/error handling остаётся bounded. + +**Given** Tools call suite +**When** она выполняется для каждой supported revision +**Then** покрыты schema validation, structured success/errors, approval, upstream/runtime failures и negative auth scope +**And** protocol fixtures, real runtime path и `just verify` проходят. + +### Story 3.4: Управлять progress и cancellation Tool calls + +**Depends on:** Story 3.3 + +**Work type:** implementation + +**Deliverable:** Управлять progress и cancellation Tool calls. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an MCP-пользователь, +I want управлять progress и cancellation активного Tool call, +So that клиент остаётся отзывчивым без ложных terminal outcomes. + +**Requirements:** FR-14 + +**Acceptance Criteria:** + +**Given** клиент согласовал progress capability и передал допустимый progress token +**When** synchronous execution сообщает progress +**Then** server отправляет bounded monotonic progress updates в допустимом negotiated format +**And** отсутствие progress support либо token не влияет на корректность execution result. + +**Given** malformed, reused в недопустимом scope или oversized progress token +**When** Tool call начинается +**Then** token отклоняется либо progress отключается согласно specification +**And** token не попадает в metric labels, logs или authorization scope. + +**Given** клиент отправляет cancellation для active Tool call +**When** local execution ещё может быть остановлена +**Then** cancellation кооперативно распространяется через runtime и освобождает bounded resources +**And** result/Invocation History не получает ложный `completed` state. + +**Given** cancellation или timeout после возможного outbound dispatch +**When** внешний outcome нельзя подтвердить +**Then** server не утверждает, что side effect отменён или не произошёл +**And** write без idempotency не ретраится автоматически. + +**Given** Tools execution-lifecycle suite +**When** она выполняется для каждой supported revision +**Then** покрыты progress token bounds, monotonic updates, cancellation races и ambiguous outbound outcome +**And** protocol fixtures, representative client smoke и `just verify` проходят. + +### Story 3.5: Отправлять Tool catalog change signals + +**Depends on:** Story 3.4 + +**Work type:** implementation + +**Deliverable:** Отправлять Tool catalog change signals. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an MCP-пользователь, +I want получать Tool catalog changes после commit, +So that обновляю discovery без зависимости от доставки notification. + +**Requirements:** FR-14 + +**Acceptance Criteria:** + +**Given** Agent публикует новый catalog revision +**When** negotiated client поддерживает tools list-changed notification +**Then** server отправляет bounded notification после commit +**And** notification не является единственным источником каталога: повторный `tools/list` остаётся authoritative. + +**Given** client не поддерживает list-changed notification +**When** catalog обновляется +**Then** server не отправляет неподдерживаемое сообщение +**And** новый snapshot доступен при следующем обычном discovery request. + +**Given** Tools execution-lifecycle suite +**When** она выполняется для каждой supported revision +**Then** покрыты list-changed negotiation, post-commit delivery и authoritative discovery при отсутствии notification support +**And** protocol fixtures, representative client smoke и `just verify` проходят. + +### Story 3.6: Сохранять typed static Resource Drafts + +**Depends on:** Story 3.5 + +**Work type:** implementation + +**Deliverable:** Сохранять typed static Resource Drafts. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want безопасно сохранять text, JSON и binary Resource Drafts, +So that content имеет typed contract, bounded artifact и безопасный preview. + +**Requirements:** FR-15, FR-16 + +**Acceptance Criteria:** + +**Given** Resource domain model +**When** добавляется persistence и API contract +**Then** Resource является отдельным typed aggregate с собственными ID/version/lifecycle, `CapabilityKind::Resource`, sensitivity и immutable Published Version +**And** не хранится как untyped Operation subtype или универсальный JSON blob. + +**Given** новый Resource Draft +**When** администратор выбирает static text, JSON или binary kind +**Then** задаются URI, name, description, MIME type, sensitivity и bounded content +**And** URI и name валидируются как стабильные capability identifiers. + +**Given** static content +**When** оно сохраняется +**Then** bytes размещаются в content-addressed artifact store, а Resource Version хранит exact digest и metadata +**And** filesystem path, raw upload filename или mutable external reference не входит в published contract. + +**Given** JSON Resource +**When** Draft сохраняется или preview-ится +**Then** content валидируется как JSON и возвращается без изменения data semantics +**And** malformed либо oversized JSON отклоняется до publication. + +**Given** text Resource +**When** content принимается +**Then** он сохраняет валидный UTF-8 в пределах configured size +**And** invalid encoding или unsafe truncation отклоняются с stable finding. + +**Given** binary Resource +**When** он preview-ится или читается через MCP +**Then** MIME, byte size и negotiated binary representation соблюдаются version adapter +**And** content не декодируется как text и не помещается целиком в logs/errors. + +**Given** Resource с active либо browser-renderable content type, включая HTML или SVG +**When** Admin UI показывает preview/download +**Then** untrusted bytes не исполняются в origin Crank: используется inert text/metadata, sandboxed isolated preview либо attachment download по explicit allowlist +**And** response применяет safe `Content-Type`, `nosniff`, CSP/sandbox и filename sanitization без content sniffing. + +**Given** static Resource Draft suite +**When** выполняются domain, artifact и API tests +**Then** покрыты text/JSON/binary validation, MIME/size, active-content preview, malformed encoding и artifact integrity +**And** `just verify` проходит. + +### Story 3.7: Публиковать и привязывать static Resource Versions + +**Depends on:** Story 3.6 + +**Work type:** implementation + +**Deliverable:** Публиковать и привязывать static Resource Versions. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want публиковать проверенный Resource Draft и привязывать exact version к Agent, +So that MCP catalog получает immutable context с правильной sensitivity. + +**Requirements:** FR-15, FR-16 + +**Acceptance Criteria:** + +**Given** Resource Draft +**When** администратор выполняет preview/test read +**Then** UI показывает точный content type, size, safe preview и findings без публикации +**And** binary preview не раскрывает unbounded bytes в DOM или telemetry. + +**Given** publish request +**When** publication validator выполняется +**Then** проверяются URI, MIME, size, sensitivity, artifact digest/integrity и secret findings +**And** raw credential, private key либо access-bypassing reference блокирует publication. + +**Given** валидный Resource Draft +**When** администратор публикует его +**Then** создаётся immutable Published Resource Version +**And** последующее редактирование создаёт новый Draft без изменения published bytes или metadata. + +**Given** Agent Draft +**When** администратор добавляет Resource binding +**Then** binding ссылается на exact Published Resource Version через отдельную typed binding table +**And** Agent publication атомарно включает Resource в immutable catalog snapshot и повышает `catalog_revision`. + +**Given** Resource lifecycle API/UI +**When** выполняются create, upload, preview, publish, bind или archive +**Then** доступны loading, empty, validation, error, confirmation, stale-response и RU/EN states +**And** UI различает Draft, exact Published Version, MIME, size и effective sensitivity. + +**Given** static Resource lifecycle suite +**When** выполняются domain, artifact, registry, API и Playwright tests +**Then** покрыты preview, secret scan, immutable publication, exact binding, archive и stale Agent revision +**And** `just verify` проходит. + +### Story 3.8: Обнаруживать и читать static Resources через MCP + +**Depends on:** Story 3.7 + +**Work type:** implementation + +**Deliverable:** Обнаруживать и читать static Resources через MCP. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an MCP-пользователь, +I want находить и читать bound static Resources, +So that получаю exact published bytes без раскрытия чужих capabilities. + +**Requirements:** FR-15, FR-16 + +**Acceptance Criteria:** + +**Given** авторизованный MCP-клиент Published Agent +**When** он вызывает Resource discovery/list +**Then** service возвращает только bound Published Resources с opaque revision-scoped pagination +**And** Draft, foreign или unbound Resource не обнаруживается. + +**Given** клиент вызывает `resources/read` для bound static URI +**When** access и size checks успешны +**Then** version adapter возвращает exact published text/JSON/binary content и MIME в negotiated shape +**And** Request ID/Trace ID и read outcome сохраняются без content capture в telemetry. + +**Given** клиент вызывает неизвестный, Draft либо unbound Resource +**When** service разрешает URI +**Then** request получает safe not-found/denied protocol outcome без metadata leakage +**And** artifact bytes не читаются до authorization. + +**Given** Published Resource Version архивирована после фиксации в Agent snapshot +**When** существующий Agent читает exact bound version +**Then** archive запрещает новые bindings/publications, но не ломает воспроизводимое чтение immutable snapshot +**And** явная security revocation остаётся отдельным audited state transition и fail-closed contract. + +**Given** static Resource protocol suite +**When** она выполняется для каждой supported MCP revision +**Then** покрыты точные `resources/list` и `resources/read`, scope, pagination, archive/revocation, text/JSON/binary read, MIME/size, safe errors и artifact corruption +**And** discovery соответствует NFR-P4 ≤150 ms p95, representative clients и `just verify` проходят. + +### Story 3.9: Импортировать, экспортировать и сопровождать Resources в UI + +**Depends on:** Story 3.8 + +**Work type:** implementation + +**Deliverable:** Импортировать, экспортировать и сопровождать Resources в UI. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want переносить и сопровождать Resource Versions через безопасный UI, +So that lifecycle остаётся воспроизводимым между установками. + +**Requirements:** FR-15 + +**Acceptance Criteria:** + +**Given** Resource export/import +**When** администратор переносит Draft или Published Version +**Then** wire metadata и content digest сохраняются, content передаётся bounded artifact contract +**And** импорт создаёт новый owned Draft для явной проверки/публикации; raw filesystem paths, credentials, foreign ownership metadata и автоматическая Published state отсутствуют. + +**Given** Resource UI на RU и EN +**When** выполняются list, inspect, import, export или archive +**Then** присутствуют loading, empty, validation, error, confirmation и stale-response states +**And** UI явно различает Draft и точную Published Version. + +**Given** Resource portability suite +**When** выполняются roundtrip, malformed/oversized artifact, cross-workspace и stale UI cases +**Then** wire metadata/content digest сохраняются, secrets/internal paths отсутствуют +**And** Playwright и `just verify` проходят. + +### Story 3.10: Определять и публиковать REST-backed Resource templates + +**Depends on:** Story 3.9 + +**Work type:** implementation + +**Deliverable:** Определять и публиковать REST-backed Resource templates. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want определить безопасный REST-backed Resource template, +So that dynamic context публикуется только через pinned read-safe Operation. + +**Requirements:** FR-16 + +**Acceptance Criteria:** + +**Given** новый dynamic Resource Draft +**When** администратор выбирает REST-backed kind +**Then** Resource ссылается только на exact Published Operation Version того же workspace +**And** arbitrary URL, inline request definition или Draft Operation не принимаются. + +**Given** выбранная Published Operation Version +**When** publication validator проверяет Resource +**Then** разрешены только read-safe `GET` или `HEAD` Operations без destructive semantics +**And** write method, approval-required side effect или неподтверждённая read-safety classification блокирует публикацию. + +**Given** URI template Resource +**When** администратор определяет template parameters +**Then** каждый parameter имеет typed schema, required/default/enum/format и однозначное mapping в pinned Operation input +**And** неизвестный, duplicate или unmapped parameter создаёт blocker finding. + +**Given** URI template Resource задаёт cache и failure policy +**When** publication validator проверяет Draft +**Then** TTL/vary/size и safe failure outcome typed, bounded и совместимы с effective Agent/workspace/auth scope +**And** неограниченный cache, cross-scope reuse или arbitrary fallback content блокируют публикацию и объясняются в UI. + +**Given** Dynamic Resource definition UI +**When** выполняются source selection, parameter mapping, preview validation или publish +**Then** присутствуют loading, empty, validation, error, confirmation, stale-response и RU/EN states +**And** UI показывает pinned Operation Version, read-safety и effective sensitivity/access policy. + +**Given** template publication suite +**When** выполняются API/registry/Playwright tests +**Then** покрыты exact source version, GET/HEAD restriction, parameter mapping, host/scheme injection и immutable publication +**And** `just verify` проходит. + +### Story 3.11: Читать REST-backed Resources через общий runtime + +**Depends on:** Story 3.10 + +**Work type:** implementation + +**Deliverable:** Читать REST-backed Resources через общий runtime. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an MCP-пользователь, +I want читать параметризованные Resources из разрешённых REST sources, +So that Agent получает актуальный context без отдельного небезопасного network path. + +**Requirements:** FR-16 + +**Acceptance Criteria:** + +**Given** template URI и входные параметры +**When** MCP-клиент вызывает `resources/read` +**Then** parameters валидируются до execution и кодируются согласно URI-template contract +**And** traversal, delimiter injection, выход за разрешённый root и добавление произвольного host/scheme запрещены. + +**Given** Published Agent с bound Resource template +**When** клиент вызывает `resources/templates/list` +**Then** он получает только разрешённые templates, parameter metadata и MIME expectations exact Agent snapshot с revision-correct pagination +**And** Draft, foreign или unbound templates не обнаруживаются. + +**Given** валидный dynamic Resource read +**When** начинается получение данных +**Then** request проходит через `RuntimeExecutionRequest → crank-runtime → crank-adapter-rest` и shared OutboundPolicy +**And** Resource не имеет отдельного network path, обходящего SSRF, authentication, timeout, limits или correlation. + +**Given** pinned Operation использует Auth Profile +**When** Resource выполняет read +**Then** runtime разрешает credential только через exact `AuthProfileRef` и Agent/workspace scope +**And** secret не попадает в URI, cache key, Resource content, logs или protocol result. + +**Given** успешный REST response +**When** Resource mapping завершается +**Then** результат преобразуется только в опубликованный text, JSON или binary content contract с точным MIME и size limit +**And** unsupported content type или mapping failure не возвращается как arbitrary fallback text. + +**Given** `HEAD` Resource либо response без body +**When** contract допускает metadata-only result +**Then** возвращается явно опубликованное metadata representation +**And** отсутствие body не интерпретируется как JSON parsing failure. + +**Given** configured Resource cache policy +**When** identical read повторяется +**Then** cache key включает Resource Version, canonical parameters и полный Agent/workspace/auth scope +**And** потеря Valkey приводит к корректному uncached read, а не к cross-scope result или failure correctness. + +**Given** pinned Operation была revoked, archived либо её Auth Profile отозван +**When** выполняется новый Resource read +**Then** admission повторно проверяет текущую safety eligibility и fail closed до dispatch +**And** immutable Resource Version не переписывается, а error указывает безопасный recovery path. + +**Given** upstream timeout, oversized response или policy denial +**When** dynamic read завершается ошибкой +**Then** MCP получает structured safe Resource error с Request ID/Trace ID +**And** raw URL, credential, response body и внутренний network address не раскрываются. + +**Given** Dynamic Resource read UI на RU и EN +**When** выполняются preview/test read или failure recovery +**Then** присутствуют loading, empty, validation, error, confirmation и stale-response states +**And** preview показывает pinned Operation Version и effective sensitivity/access policy. + +**Given** dynamic Resource suite +**When** выполняются contract и negative tests +**Then** покрыты template discovery/read, parameter validation, traversal, host injection, SSRF, auth scope, cache isolation/loss, MIME/size, revoked dependency и empty responses +**And** каждая supported MCP revision, Playwright и `just verify` проходят. + +### Story 3.12: Создавать и preview-ить parameterized Prompt Drafts + +**Depends on:** Story 3.1, Story 1.13 + +**Work type:** implementation + +**Deliverable:** Создавать и preview-ить parameterized Prompt Drafts. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want создавать typed Prompt Draft и проверять rendering, +So that получаю валидированный шаблон до публикации. + +**Requirements:** FR-17 + +**Acceptance Criteria:** + +**Given** Prompt domain model +**When** добавляются persistence и API +**Then** Prompt является отдельным typed aggregate с ID/version/lifecycle, typed arguments, sensitivity и immutable Published Version +**And** не хранится как Tool либо untyped template blob. + +**Given** Prompt Draft +**When** задаются name, description, arguments и messages +**Then** argument names уникальны, schemas bounded, required/default/enum semantics валидны, а message roles принадлежат exact enum `system|user|assistant` и сохраняют порядок/границы +**And** arbitrary code, executable expression и unbounded interpolation запрещены. + +**Given** preview/test request +**When** arguments валидны +**Then** renderer детерминированно возвращает итоговые messages без публикации +**And** missing, unknown или invalid argument возвращает structured error до частичного rendering. + +**Given** Prompt UI на RU и EN +**When** выполняются create, preview или validation failure +**Then** присутствуют loading, empty, error, confirmation и stale-response states +**And** UI различает Draft и exact Published Version. + +**Given** Prompt suite +**When** выполняются API/Playwright tests +**Then** покрыты Draft lifecycle, typed arguments, deterministic preview и scope isolation +**And** `just verify` проходит. + +### Story 3.13: Публиковать Prompts и привязывать exact versions к Agent + +**Depends on:** Story 3.12 + +**Work type:** implementation + +**Deliverable:** Публиковать Prompts и привязывать exact versions к Agent. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want публиковать и привязывать exact Prompt Version, +So that Agent snapshot сохраняет immutable contract. + +**Requirements:** FR-17 + +**Acceptance Criteria:** + +**Given** валидный Draft +**When** Prompt публикуется +**Then** создаётся immutable Published Prompt Version, а последующее изменение создаёт новый Draft +**And** published arguments/messages не меняются in place. + +**Given** Agent Draft +**When** добавляется Prompt binding +**Then** binding указывает exact Published Prompt Version в отдельной typed table +**And** Agent publication атомарно включает Prompt в snapshot и повышает `catalog_revision`. + +**Given** Prompt UI на RU и EN +**When** выполняются publish, bind, archive или validation failure +**Then** присутствуют loading, empty, error, confirmation и stale-response states +**And** UI различает Draft и exact Published Version. + +**Given** Prompt suite +**When** выполняются API/Playwright tests +**Then** покрыты publication/archive lifecycle, exact binding, scope isolation и immutable versions +**And** `just verify` проходит. + +### Story 3.14: Обнаруживать и получать Published Prompts через MCP + +**Depends on:** Story 3.13 + +**Work type:** implementation + +**Deliverable:** Обнаруживать и получать Published Prompts через MCP. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an MCP-пользователь, +I want обнаруживать и получать bound Published Prompts, +So that получаю детерминированные сообщения с проверкой arguments и scope. + +**Requirements:** FR-17 + +**Acceptance Criteria:** + +**Given** авторизованный MCP-клиент +**When** вызывается `prompts/list` +**Then** видны только bound Published Prompts с revision-scoped pagination и typed argument metadata +**And** Draft, foreign либо unbound Prompt не раскрывается. + +**Given** авторизованный клиент вызывает `prompts/get` +**When** argument missing, unknown, wrong-type либо oversized +**Then** server возвращает structured revision-correct error до любого partial rendering +**And** ни одна часть messages, dependency content или foreign metadata не раскрывается. + +**Given** Published Prompt Version архивирована после фиксации в Agent snapshot +**When** существующий Agent получает exact bound version через `prompts/get` +**Then** archive запрещает новые bindings/publications, но сохраняет immutable snapshot behavior +**And** security revocation/dependency invalidation остаётся отдельным fail-closed state. + +**Given** Prompt suite +**When** выполняются API/MCP/Playwright tests для каждой revision +**Then** покрыты typed arguments, deterministic rendering, pagination, exact binding, scope isolation и immutable versions +**And** discovery ≤150 ms p95 и `just verify` проходит. + +### Story 3.15: Импортировать и экспортировать Prompts через API и UI + +**Depends on:** Story 3.14 + +**Work type:** implementation + +**Deliverable:** Импортировать и экспортировать Prompts через API и UI. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want переносить Prompts через import/export, +So that сохраняю wire contract без изменения Published Version. + +**Requirements:** FR-17 + +**Acceptance Criteria:** + +**Given** Prompt import/export +**When** переносится версия +**Then** wire contract сохраняет arguments/messages и exact metadata без secrets/internal paths +**And** upsert создаёт новый Draft, не меняя Published Version. + +**Given** Prompt UI на RU и EN +**When** выполняются import/export или validation failure +**Then** присутствуют loading, empty, error, confirmation и stale-response states +**And** UI различает Draft и exact Published Version. + +**Given** Prompt suite +**When** выполняются API/Playwright tests +**Then** покрыты import/export roundtrip, Draft-only upsert, scope isolation и immutable versions +**And** `just verify` проходит. + +### Story 3.16: Компоновать Prompts с Published Resources + +**Depends on:** Story 3.7, Story 3.11, Story 3.14 + +**Work type:** implementation + +**Deliverable:** Компоновать Prompts с Published Resources. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want включать разрешённые Resources в Prompt messages, +So that Agent получает составной контекст с фиксированными dependencies и effective security policy. + +**Requirements:** FR-18 + +**Acceptance Criteria:** + +**Given** Prompt Draft +**When** добавляется Resource dependency +**Then** она ссылается только на exact Published Resource Version того же workspace +**And** Draft, foreign или mutable reference блокируется. + +**Given** dependency graph Prompts/Resources +**When** выполняется publication validation +**Then** graph детерминированно проверяется на cycles, missing/unpublished nodes и bounded depth/count +**And** любой unresolved cycle/dependency блокирует публикацию с source path. + +**Given** dependency с более строгой sensitivity/access policy +**When** вычисляется effective Prompt policy +**Then** Prompt наследует наиболее строгие ограничения всех dependencies +**And** администратор не может понизить их локальным override. + +**Given** render Prompt +**When** Resource reference разрешается +**Then** используется exact pinned version и разрешённый negotiated representation +**And** rendering не выполняет arbitrary Tool/code и не обращается к unbound capability. + +**Given** static или dynamic Resource содержит инструкции, role-like delimiters либо иной untrusted external text +**When** content вставляется в Prompt messages +**Then** published template сохраняет фиксированные message roles/boundaries и provenance exact Resource Version/source class +**And** Resource content не может создать/заменить system message, а UI явно обозначает untrusted provenance и не обещает semantic prompt-injection sanitization. + +**Given** dynamic Resource dependency +**When** Prompt get инициирует разрешённое чтение +**Then** Resource проходит собственный authorization/outbound/size contract +**And** failure возвращается структурированно без partial secret-bearing Prompt. + +**Given** secret scan или access-bypassing content finding +**When** Prompt публикуется либо preview-ится +**Then** raw credentials и fallback-as-tool paths блокируются +**And** logs, traces и preview содержат только redacted findings. + +**Given** dependency получает новую version или archive status +**When** опубликованный Prompt читается +**Then** exact pinned dependency сохраняется immutable, но current safety eligibility revalidated там, где требуется +**And** обновление dependency требует нового Prompt Draft/publication. + +**Given** администратор preview-ит composed Prompt +**When** dependencies и arguments разрешены +**Then** UI показывает итоговые ordered messages, exact Resource Versions, provenance и effective sensitivity без выполнения arbitrary Tool/code +**And** loading, empty, validation, error, stale-response, keyboard/focus и RU/EN states покрыты Playwright. + +**Given** composition tests +**When** выполняются graph, rendering и scope suites +**Then** покрыты cycles, missing versions, sensitivity escalation, dynamic failure, secret scan, role/delimiter injection, provenance и deterministic output +**And** MCP/Playwright tests и `just verify` проходят. + +### Story 3.17: Предоставить MCP completion + +**Depends on:** Story 3.16 + +**Work type:** implementation + +**Deliverable:** Предоставить MCP completion. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an MCP-пользователь, +I want получать bounded completion suggestions, +So that могу заполнять Prompt и Resource parameters без раскрытия чужих данных. + +**Requirements:** FR-19 + +**Acceptance Criteria:** + +**Given** negotiated revision/capabilities +**When** клиент вызывает completion для Prompt argument или Resource template parameter +**Then** shared completion service возвращает bounded authorized suggestions из typed schemas +**And** не раскрывает foreign names, secrets или arbitrary database values. + +**Given** malformed token или completion request +**When** method service валидирует вход +**Then** возвращается revision-correct safe error без unbounded work +**And** идентификаторы не попадают в metric labels. + +**Given** capability suite +**When** выполняется по всем supported revisions +**Then** покрыты positive/negative completion и authorization +**And** representative clients и `just verify` проходят. + +### Story 3.18: Предоставить безопасное MCP server logging + +**Depends on:** Story 3.17 + +**Work type:** implementation + +**Deliverable:** Предоставить безопасное MCP server logging. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an MCP-пользователь, +I want задавать допустимый server logging level, +So that получаю безопасные negotiated events. + +**Requirements:** FR-19 + +**Acceptance Criteria:** + +**Given** server logging capability +**When** клиент задаёт допустимый level +**Then** adapter отправляет только safe structured events в рамках negotiated contract +**And** payloads, credentials, internal causes и user values не раскрываются. + +**Given** malformed logging level +**When** method service валидирует вход +**Then** возвращается revision-correct safe error без unbounded work +**And** идентификаторы не попадают в metric labels. + +**Given** capability suite +**When** выполняется по всем supported revisions +**Then** покрыты logging levels и redaction +**And** representative clients и `just verify` проходят. + +### Story 3.19: Отправлять Resource и Prompt change signals + +**Depends on:** Story 3.18 + +**Work type:** implementation + +**Deliverable:** Отправлять Resource и Prompt change signals. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an MCP-пользователь, +I want получать Resource/Prompt change signals, +So that восстанавливаю authoritative catalog при потере notification. + +**Requirements:** FR-19 + +**Acceptance Criteria:** + +**Given** Resource/Prompt catalog commit +**When** client поддерживает соответствующий list-changed signal +**Then** notification отправляется после commit и может coalesce-иться по revision +**And** обычный list/read/get остаётся authoritative при потере notification. + +**Given** exporter/transport/notification failure +**When** critical catalog state уже committed +**Then** failure наблюдаема, но не откатывает product transaction +**And** stateless client восстанавливает состояние через `server/discover` и обычные list/read/get, а legacy client — через свой revision-correct reinitialize/reconnect contract. + +**Given** capability suite +**When** выполняется по всем supported revisions +**Then** покрыты Resource/Prompt notification/subscription gating, coalescing и loss +**And** representative clients и `just verify` проходят. + +### Story 3.20: Учредить исполняемую MCP compatibility matrix + +**Depends on:** Story 3.19 + +**Work type:** implementation + +**Deliverable:** Учредить исполняемую MCP compatibility matrix. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As a пользователь Community release, +I want видеть доказанную совместимость MCP versions, methods и клиентов, +So that могу выбрать поддерживаемый клиент без доверия к декларациям. + +**Requirements:** FR-20 + +**Acceptance Criteria:** + +**Given** feature-freeze inventory +**When** строится machine-readable matrix +**Then** она охватывает 100% official stable server capabilities/extensions для latest stable, N-1/N-2 и retained legacy revisions, включая явные cells, владельцев и target Story для ещё не реализованного Tasks extension +**And** каждый cell содержит supported/not-applicable/experimental/deferred, fixture и fallback. + +**Given** применимая stable server capability +**When** status остаётся `deferred` или evidence отсутствует +**Then** matrix verifier fail closed и блокирует feature-complete gate +**And** documentation не может скрыть omission. + +**Given** завершение любой Story 3.1–3.19 +**When** её capability contract становится green +**Then** соответствующие machine-readable matrix cells и deterministic wire fixtures добавляются в той же Story +**And** Story 3.20 не используется для восполнения отложенного conformance coverage. + +**Given** protocol harness +**When** запускаются selected revisions +**Then** отдельно проверяются `server/discover`/stateless lifecycle `2026-07-28`, initialize/session lifecycle legacy adapters, request metadata, Tools, Resources, Prompts, completion, logging, progress, cancellation, subscriptions/pagination и notifications; Tasks cells допускаются planned только до owning Story Epic 4 +**And** expected wire fixtures versioned и deterministic. + +**Given** representative client set +**When** до RC выбираются минимум три актуальных клиента +**Then** versions/images/config фиксируются, каждый выполняет published discovery и representative calls +**And** client-specific workaround документирован и не меняет stable internal semantics. + +**Given** experimental adapter +**When** он включён или выключен +**Then** matrix отделяет его evidence от stable contract +**And** critical Tool остаётся вызываемым stable клиентом. + +**Given** matrix result +**When** release evidence формируется +**Then** raw results content-addressed и связаны с commit/image/config digests +**And** human-readable matrix проверяется против machine source. + +**Given** regression либо новая MCP revision после freeze +**When** она обнаружена +**Then** текущий RC contract не меняется молча, изменение входит в следующий compatibility cycle либо новый freeze decision +**And** fixed regression добавляет protocol fixture. + +**Given** завершение Epic 3 +**When** выполняются protocol/client suites +**Then** FR-13…FR-20 catalog/core cells имеют immutable evidence, applicable NFR выполняются, Capability Inventory обновлена, а Tasks extension имеет explicit owner в Epic 4 и blocker status до её evidence +**And** `just verify` проходит без удаления retained compatibility или ложного утверждения полной release qualification. + +## Epic 4: Безопасные параллельные и фоновые выполнения + +Пользователь запускает долгие Tools как durable Tasks, наблюдает progress, отменяет, восстанавливает после restart и разрешает `outcome_unknown` без неконтролируемого повторения side effects. + +### Story 4.1: Публиковать execution mode и применять admission limits + +**Depends on:** Story 3.4 + +**Work type:** implementation + +**Deliverable:** Публиковать execution mode и применять admission limits. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want задавать synchronous, background или adaptive execution policy и bounded concurrency, +So that нагрузка не разрушает систему, а клиент заранее знает доступное поведение. + +**Requirements:** FR-21, FR-24 + +**Acceptance Criteria:** + +**Given** Tool Draft +**When** задаётся execution mode +**Then** policy фиксирует `synchronous`, `background` или `adaptive`, deadline и fallback для клиента без Tasks +**And** background не включается неявно для запрещающего его Tool. + +**Given** sync или background request +**When** выполняется `ExecutionAdmission` +**Then** один policy snapshot проверяет global/per-Agent/per-Tool concurrency, authorization, approval, deadline и bounded queue capacity +**And** оба execution paths используют одинаковые safety gates. + +**Given** свободная capacity +**When** request принят +**Then** admission выдаёт scoped permit либо durable enqueue decision с exact Published Version semantics +**And** future policy change не меняет уже принятое execution. + +**Given** saturation +**When** лимит или queue исчерпаны +**Then** request отклоняется до unbounded allocation с typed overload outcome и retry guidance +**And** rejection, queue wait и oldest age записываются low-cardinality metrics. + +**Given** несколько Agents/Tools +**When** они конкурируют за capacity +**Then** documented fairness предотвращает starvation в пределах configured weights +**And** один Agent не обходит global limit множеством credentials, concurrent connections или protocol revisions. + +**Given** mandatory safety store недоступен +**When** admission не может подтвердить approval/idempotency/capacity state +**Then** зависимый path fail closed и readiness отражает dependency failure +**And** unsafe in-memory fallback не активируется. + +**Given** admission tests +**When** выполняются concurrency/race/overload cases +**Then** доказаны bounded queues, fairness, deadline propagation, exact policy pinning и sync compatibility +**And** `just verify` проходит. + +### Story 4.2: Атомарно принимать durable Tasks + +**Depends on:** Story 4.1 + +**Work type:** implementation + +**Deliverable:** Атомарно принимать durable Tasks. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an MCP-пользователь, +I want получить устойчивый Task ID только после надёжного принятия работы, +So that подтверждённая задача не теряется при crash или restart. + +**Requirements:** FR-22, FR-23 + +**Acceptance Criteria:** + +**Given** background admission +**When** Task принимается +**Then** PostgreSQL transaction сохраняет UUIDv7 Task, owner scope, pinned execution semantics, initial `queued` state и dispatch intent до acknowledgement +**And** отсутствует accepted response без durable record. + +**Given** Task model +**When** state читается +**Then** доступны `queued`, `working`, `input_required`, `outcome_unknown`, `completed`, `failed`, `cancelled`, progress, timestamps, attempts и result/error +**And** protocol adapter не определяет внутреннюю lifecycle semantics. + +**Given** Task и dispatch intent принимаются +**When** transaction commit завершается +**Then** Task record сохраняет отдельные Request ID, Trace ID и validated parent TraceContext независимо от sampling +**And** acknowledgement возвращает те же support IDs без смешения Task/Execution identity. + +**Given** terminal transition +**When** result commit выполняется +**Then** conditional update допускает ровно один переход из разрешённого non-terminal state +**And** terminal result immutable до retention expiry. + +**Given** crash до commit +**When** request повторяется +**Then** Task не считается принятым и idempotent retry безопасен +**And** partial Task/dispatch state невидим. + +**Given** crash после commit до response +**When** request повторяется с тем же scoped key/fingerprint +**Then** возвращается существующий Task ID +**And** duplicate Task не создаётся. + +**Given** тот же scoped idempotency key повторён с другим canonical input fingerprint +**When** background request принимается +**Then** сервер возвращает typed conflict до enqueue или outbound dispatch +**And** существующие Task, dispatch intent и audit evidence не изменяются. + +**Given** status/result request +**When** caller не владеет Agent/admin scope +**Then** доступ denied/not-found без metadata leakage +**And** Task payload читается только после authorization. + +**Given** Task envelope содержит input, progress, result/error, input schema или reconciliation metadata +**When** данные валидируются перед persistence +**Then** size/count/depth bounded, secret-bearing fields classified/redacted либо заменены безопасной artifact reference +**And** full workspace/Agent/authorization scope входит в Task, idempotency и cache keys; foreign collision не раскрывает metadata. + +**Given** Task store unavailable +**When** background request поступает +**Then** сервер fail closed без ephemeral future +**And** synchronous fallback используется только если он опубликован Tool policy. + +**Given** persistence suite +**When** выполняются transaction/crash/replay/retention tests +**Then** доказаны no-loss acceptance, immutable terminal state и scope isolation +**And** migrations fresh/already-migrated и `just verify` проходят. + +### Story 4.3: Исполнять Tasks через leases и fencing + +**Depends on:** Story 4.2 + +**Work type:** implementation + +**Deliverable:** Исполнять Tasks через leases и fencing. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an оператор, +I want workers безопасно восстанавливать Tasks после сбоев, +So that stale worker не перезаписывает progress или terminal outcome. + +**Requirements:** FR-22, FR-23 + +**Acceptance Criteria:** + +**Given** queued Tasks +**When** `task-worker` claims bounded batch +**Then** PostgreSQL использует `FOR UPDATE SKIP LOCKED`, lease owner/expiry и monotonic fencing token +**And** Valkey может только ускорять wake-up. + +**Given** active lease +**When** worker renews либо записывает progress/checkpoint/result +**Then** update содержит current owner/token и CAS predicate +**And** stale token после lease loss всегда отклоняется. + +**Given** claim перед outbound dispatch +**When** worker готовит attempt +**Then** он повторно проверяет Agent publication, exact capability version, credential, approval, deadline и capacity +**And** invalidated work завершается безопасно без dispatch. + +**Given** worker готов перейти от проверки к outbound dispatch +**When** он фиксирует начало попытки +**Then** dispatch checkpoint и Attempt ID атомарно записываются под current lease owner и fencing-token CAS до сетевого вызова +**And** stale worker до checkpoint не вызывает upstream, а uncertainty после checkpoint безопасно фиксируется как `outcome_unknown` без automatic retry. + +**Given** valid claimed attempt +**When** worker продолжает выполнение +**Then** он продолжает сохранённый parent trace, а каждый retry создаёт отдельный child attempt span с Attempt ID +**And** TraceContext не берётся из mutable queue/cache projection и не попадает в metric labels. + +**Given** worker crash +**When** lease expires +**Then** eligible Task становится доступен recovery ≤60 секунд +**And** прежний worker не может сделать terminal commit после возвращения. + +**Given** graceful shutdown +**When** worker получает stop +**Then** новые claims прекращаются, active work checkpoint-ится/сохраняется в пределах 30 секунд +**And** queued Tasks не теряются. + +**Given** полная потеря Valkey +**When** workers продолжают работу +**Then** PostgreSQL-only mode сохраняет correctness с допустимым снижением throughput +**And** projections восстанавливаются без duplicate terminal outcome. + +**Given** Task+dispatch intent committed, но process падает до Valkey wake-up +**When** worker стартует либо выполняет bounded authoritative scan +**Then** queued intent обнаруживается из PostgreSQL и доставляется at-least-once без ручного repair +**And** отсутствие Valkey влияет только на wake-up latency, а не на loss/correctness. + +**Given** lease/fencing suite +**When** моделируются crash, pause, partition, stale renew и concurrent claims +**Then** доказаны single terminal CAS, stale-write rejection и recovery timing +**And** `just verify` проходит. + +### Story 4.4: Управлять retry, cancellation и outcome_unknown + +**Depends on:** Story 4.3 + +**Work type:** implementation + +**Deliverable:** Управлять retry, cancellation и outcome_unknown. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an MCP-пользователь, +I want честно видеть результат cancellation и retry, +So that Crank не повторяет внешний side effect при утраченной определённости. + +**Requirements:** FR-25 + +**Acceptance Criteria:** + +**Given** новый execution attempt +**When** начинается dispatch +**Then** attempt ID, canonical input/idempotency fingerprint и policy сохраняются до outbound request +**And** retry не создаёт неучтённую попытку. + +**Given** retryable read либо write с verified upstream idempotency +**When** attempt fails до deadline +**Then** bounded attempts/backoff соблюдают policy и общий deadline +**And** каждый attempt имеет отдельный child span/outcome. + +**Given** write без verified idempotency +**When** certainty потеряна после dispatch +**Then** Task переходит в non-terminal `outcome_unknown` +**And** automatic retry и cancel-as-success блокируются. + +**Given** cancel до dispatch +**When** conditional cancel побеждает claim +**Then** Task становится `cancelled` без side effect +**And** race result deterministic. + +**Given** cancel во время execution +**When** cooperative cancellation подтверждена +**Then** `cancelled` допустим только если cancellation победила до durable dispatch checkpoint; после dispatch write без verified idempotency Task переходит в `outcome_unknown` +**And** для read/idempotent write применяется explicit policy outcome, local work прекращается по возможности и audit сохраняет фазу/certainty. + +**Given** deadline expiry +**When** Task не завершён +**Then** outcome зависит от dispatch certainty и idempotency contract +**And** timeout не превращает `outcome_unknown` в ordinary failed/retryable state. + +**Given** lease потеряна после durable dispatch checkpoint +**When** Task восстанавливает другой worker +**Then** verified idempotent write допускает только bounded new attempt, а unverified write переходит в `outcome_unknown` +**And** stale worker не изменяет Task, fencing защищает состояние Crank и не заявляется защитой внешней системы. + +**Given** retry/cancel suite +**When** покрываются before/after-dispatch races +**Then** доказаны at-least-once delivery, bounded retries и honest ambiguity +**And** `just verify` проходит. + +### Story 4.5: Продолжать Tasks через валидированный input + +**Depends on:** Story 4.3 + +**Work type:** implementation + +**Deliverable:** Продолжать Tasks через валидированный input. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an авторизованный пользователь, +I want передавать дополнительный Task input, +So that продолжаю выполнение только после schema validation и CAS. + +**Requirements:** FR-25 + +**Acceptance Criteria:** + +**Given** worker требует input +**When** Task входит в `input_required` +**Then** сохраняются versioned JSON schema, prompt metadata, TTL и update fingerprint contract +**And** новый side effect не выполняется до valid update. + +**Given** authorized update +**When** input проходит schema validation +**Then** identical replay возвращает прежний outcome, conflicting replay — conflict +**And** CAS переводит Task обратно в `working` ровно один раз. + +**Given** input TTL истёк +**When** sweeper обрабатывает Task +**Then** Task становится `failed` без нового dispatch +**And** expiry reason сохраняется в audit. + +**Given** input-update suite +**When** выполняются TTL/replay/conflict/scope/race tests +**Then** доказаны schema validation и idempotent update +**And** `just verify` проходит. + +### Story 4.6: Разрешать outcome_unknown через reconciliation evidence + +**Depends on:** Story 4.4 + +**Work type:** implementation + +**Deliverable:** Разрешать outcome_unknown через reconciliation evidence. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an оператор, +I want разрешать неизвестный outcome по evidence, +So that не повторяю внешний side effect неявно. + +**Requirements:** FR-25 + +**Acceptance Criteria:** + +**Given** `outcome_unknown` +**When** оператор предоставляет reconciliation evidence +**Then** разрешены только переходы в `completed`, `failed` либо новый явно подтверждённый attempt +**And** evidence immutable, bounded, redacted и связано с attempt/trace без raw secrets или произвольного payload. + +**Given** обычный retry/cancel request для `outcome_unknown` +**When** reconciliation отсутствует +**Then** request блокируется с предупреждением о side effect +**And** protocol adapter не отображает состояние как retriable failure. + +**Given** reconciliation suite +**When** выполняются replay/conflict/scope/race tests +**Then** доказаны evidence-bearing transitions и запрет retry/cancel без reconciliation +**And** `just verify` проходит. + +### Story 4.7: Предоставить MCP Task operations и fallback + +**Depends on:** Story 4.4, Story 4.5, Story 4.6 + +**Work type:** implementation + +**Deliverable:** Предоставить MCP Task operations и fallback. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an MCP-пользователь, +I want создавать, отслеживать, обновлять и отменять Tasks через совместимый protocol, +So that background execution не зависит от одного HTTP/SSE connection. + +**Requirements:** FR-21, FR-22, FR-25 + +**Acceptance Criteria:** + +**Given** negotiated Task-capable revision +**When** вызывается background/adaptive Tool +**Then** adapter возвращает Task ID только после durable commit +**And** disconnect клиента не отменяет Task. + +**Given** Story 4.7 активирует Tasks support +**When** extension descriptor регистрируется через typed mechanism Story 3.1 +**Then** `io.modelcontextprotocol/tasks` рекламируется только на совместимой enabled revision с exact method/result shapes +**And** disabled либо unsupported revision не видит descriptor, Task methods или Task notifications; executable Tasks cells добавляются в общий matrix contract этой же Story. + +**Given** клиент negotiated extension `io.modelcontextprotocol/tasks` +**When** он работает с background Tool +**Then** adapter реализует применимые `tools/call`, `tasks/get`, `tasks/update` и `tasks/cancel` contracts точной negotiated revision +**And** внутренние queue, lease, fencing и attempt records не становятся публичным protocol contract. + +**Given** клиент заявил Tasks extension для одной revision +**When** он отправляет descriptor, metadata или method shape другой revision +**Then** adapter возвращает revision-correct protocol error до чтения либо изменения Task +**And** не угадывает wire contract и не переключает adapter молча. + +**Given** клиент передаёт собственный Task ID при создании background execution +**When** adapter принимает `tools/call` +**Then** client-chosen identifier игнорируется либо отклоняется согласно точному wire contract, а непредсказуемый ID создаёт сервер после durable acceptance +**And** клиент не может занять namespace, вызвать collision или проверить существование чужой Task. + +**Given** Task ID +**When** вызываются `tasks/get`, `tasks/update` или `tasks/cancel` +**Then** каждый request заново проверяет полный workspace/Agent/key authorization scope и отображает internal state только в допустимые protocol statuses +**And** `outcome_unknown` не маскируется retriable failure. + +**Given** MCP-клиент пытается перечислить Tasks +**When** official extension не определяет `tasks/list` +**Then** server не изобретает публичный method и возвращает revision-correct method-not-found +**And** bounded listing остаётся отдельной Admin API/UI capability, не требуемой для завершения MCP adapter. + +**Given** клиент без Task capability +**When** вызывается background/adaptive Tool +**Then** применяется опубликованный synchronous fallback либо structured `unsupported` +**And** сервер не рекламирует Task methods. + +**Given** Tool запрещает background +**When** клиент пытается запросить Task mode +**Then** request отклоняется до enqueue +**And** synchronous behavior остаётся неизменным. + +**Given** progress/change notification +**When** client negotiated support +**Then** updates bounded и не являются authoritative state +**And** polling/status method восстанавливает состояние после loss/reconnect. + +**Given** protocol suite +**When** выполняются selected stable/extension adapters +**Then** покрыты create/status/result/cancel/update, disconnect, auth scope и fallback +**And** representative clients и `just verify` проходят. + +### Story 4.8: Находить Tasks и выполнять безопасные Admin actions + +**Depends on:** Story 4.7 + +**Work type:** implementation + +**Deliverable:** Находить Tasks и выполнять безопасные Admin actions. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want находить Tasks и выполнять разрешённые cancel/retry actions, +So that контролирую выполнения через безопасный UI. + +**Requirements:** FR-26 + +**Acceptance Criteria:** + +**Given** Tasks dataset +**When** открывается UI +**Then** доступны bounded filters по status, Agent, Tool, period и IDs с opaque pagination +**And** loading/empty/error/stale-response states реализованы RU/EN. + +**Given** Task details +**When** запись открыта +**Then** видны Task/Execution/Request/Trace IDs, pinned version, progress, attempts, deadline и safe result/error +**And** identifiers чётко различаются и копируются, а secret canary отсутствует в progress, result/error, evidence, DOM, telemetry и exported diagnostics. + +**Given** cancellable Task либо safely retryable failure +**When** администратор подтверждает action +**Then** UI вызывает conditional operation и показывает race/conflict outcome +**And** destructive bulk action требует отдельного confirmation и audit. + +**Given** UI polling/live updates +**When** workspace/filter/request generation меняется +**Then** old response не перезаписывает новый context +**And** listeners не дублируются. + +**Given** оператор открывает Tasks navigation, filters либо detail +**When** он использует keyboard, back/forward, refresh или reconnect +**Then** URL-addressable state, permission-aware visibility, focus restoration, semantic labels/errors и `aria-live` updates сохраняют authoritative context +**And** contrast соответствует WCAG 2.2 AA, смысл не зависит только от цвета, animation уважает reduced-motion, stale response не перезаписывает новый state. + +**Given** Task UI suite +**When** выполняется Playwright/API testing +**Then** покрыты filters, lifecycle, races, bulk confirmation и localization +**And** `just verify` проходит. + +### Story 4.9: Предоставить Task input и reconciliation UI + +**Depends on:** Story 4.8, Story 4.5, Story 4.6 + +**Work type:** implementation + +**Deliverable:** Предоставить Task input и reconciliation UI. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want передавать Task input и выполнять reconciliation через UI, +So that разрешаю ожидание и ambiguity с явным подтверждением. + +**Requirements:** FR-26 + +**Acceptance Criteria:** + +**Given** `input_required` +**When** вводится дополнительный input +**Then** form строится из versioned schema и server validates again +**And** duplicate submit idempotent, conflicting stale submit видим. + +**Given** `outcome_unknown` +**When** details открыты +**Then** обычные Retry/Cancel disabled, отображается предупреждение и reconciliation flow +**And** evidence/explicit new attempt требуют confirmation. + +**Given** UI polling/live updates +**When** workspace/filter/request generation меняется +**Then** old response не перезаписывает новый context +**And** listeners не дублируются. + +**Given** оператор открывает Task input либо reconciliation flow +**When** он использует keyboard, back/forward, refresh или reconnect +**Then** URL-addressable state, permission-aware visibility, focus restoration, semantic labels/errors и `aria-live` updates сохраняют authoritative context +**And** contrast соответствует WCAG 2.2 AA, смысл не зависит только от цвета, animation уважает reduced-motion, stale response не перезаписывает новый state. + +**Given** Task UI suite +**When** выполняется Playwright/API testing +**Then** покрыты input, reconciliation, races, confirmation и localization +**And** `just verify` проходит. + +### Story 4.10: Доказать Task capacity и recovery envelope + +**Depends on:** Story 4.9 + +**Work type:** qualification + +**Deliverable:** Доказать Task capacity и recovery envelope. + +**Completion:** accepted evidence всех AC на указанном build/RC и среде; harness-only и внешний handoff не являются pass. + +As an оператор, +I want воспроизводимо проверить concurrency и recovery Tasks, +So that заявленные границы подтверждены до production release. + +**Requirements:** FR-23, FR-24 + +**Acceptance Criteria:** + +**Given** Reference Workload background variant +**When** полный versioned mix выполняет не менее 128 concurrent synchronous/background Executions и до 10 000 queued Tasks +**Then** отсутствует unbounded resource growth, duplicate terminal outcome или starvation +**And** Task start ≤5 s p95 при нагрузке в пределах service rate, build/config/topology и workload checksum входят в evidence. + +**Given** steady-state service rate +**When** измеряется queue +**Then** queue wait p95 ≤5 s и oldest age ≤30 s +**And** saturation rejection и retry guidance корректно классифицированы. + +**Given** overload stopped with 10 000 backlog +**When** capacity восстановлена +**Then** backlog дренируется ≤60 минут без loss/duplicate terminal result +**And** live metrics отражают progress. + +**Given** worker/service restart +**When** новые claims остановлены и active workers имеют 30 s на checkpoint +**Then** eligible Tasks возобновляются ≤60 s +**And** stale worker terminal commit невозможен. + +**Given** Valkey loss и mandatory PostgreSQL/coordination failures +**When** выполняется dependency matrix +**Then** PG-only mode корректен, unsafe path fail closed, local readiness/dependency diagnostics и typed metrics точны +**And** восстановление projections не меняет outcomes. + +**Given** crash/partition matrix +**When** faults вводятся до/после claim, dispatch, side effect и terminal commit +**Then** каждый outcome соответствует delivery/idempotency contract +**And** raw results content-addressed и связаны с build/config. + +**Given** завершение Epic 4 +**When** capacity/recovery suites проходят +**Then** FR-21…FR-26 и NFR-P2/R2/R3/R5 имеют evidence +**And** Capability Inventory обновлена, `just verify` успешен. + +## 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. + +## Epic 6: Встроенная проверка производительности + +Оператор задаёт RPS, VU или модель DAU, безопасно запускает и останавливает Load Run, наблюдает live statistics и получает immutable сравнительный отчёт. + +### Story 6.1: Создавать versioned Load Scenarios + +**Depends on:** Story 5.13 + +**Work type:** implementation + +**Deliverable:** Создавать versioned Load Scenarios. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор производительности, +I want собрать воспроизводимый сценарий из Published Tools, +So that одинаковая нагрузка повторяется между releases. + +**Requirements:** FR-36 + +**Acceptance Criteria:** + +**Given** Agent catalog +**When** создаётся Load Scenario +**Then** можно выбрать только точные Published Tool Versions и задать weighted mix, bounded input data, RPS или VU, duration, ramp и thresholds +**And** Draft, archived/unpublished либо чужая capability не принимается. + +**Given** выбранные Tools +**When** Scenario сохраняется +**Then** pinned Agent revision, Tool versions, input schema digests, parameter generator contract и credentials refs фиксируются immutable version +**And** raw credentials и secret-bearing samples не сохраняются. + +**Given** target Tool +**When** он не объявлен `load-test-safe` либо является write +**Then** публикация Scenario блокируется до явной safety classification и требуемых sandbox controls +**And** UI объясняет причину без раскрытия policy metadata чужого объекта. + +**Given** Scenario edit +**When** уже существует использованная version +**Then** создаётся новая version, предыдущая остаётся доступной для report reproduction +**And** import/export roundtrip сохраняет весь bounded contract. + +**Given** Scenario UI +**When** пользователь создаёт, preview-ит, version-ит или архивирует его +**Then** реализованы loading/empty/validation/error/conflict/stale-response states и RU/EN localization +**And** computed request count, ceilings и expected data sources видны до сохранения. + +**Given** contract/API/Playwright suite +**When** проверяются mixed Tools, invalid weights, oversized data, stale catalog и roundtrip +**Then** validation детерминирована, никакой Run не стартует +**And** `just verify` проходит. + +### Story 6.2: Преобразовывать DAU в прозрачный arrival profile + +**Depends on:** Story 6.1 + +**Work type:** implementation + +**Deliverable:** Преобразовывать DAU в прозрачный arrival profile. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an администратор, +I want задавать понятную модель DAU вместо ручного расчёта RPS, +So that могу приблизить реальную пользовательскую активность. + +**Requirements:** FR-37 + +**Acceptance Criteria:** + +**Given** DAU mode +**When** оператор задаёт DAU, actions/session, sessions/user/day, activity window, think time и Tool mix +**Then** все assumptions обязательны, имеют units/bounds и не выводятся из скрытых defaults +**And** UI показывает формулы и предупреждает о неоднозначных сочетаниях. + +**Given** валидная модель +**When** выполняется preview +**Then** строится deterministic time-bucketed arrival/RPS curve, peak/average RPS, expected iterations и VU estimate +**And** rounding, timezone и seed зафиксированы в Scenario version. + +**Given** вычисленный профиль превышает capability/ceiling +**When** preview завершается +**Then** UI показывает exact limiting constraint и не разрешает Start +**And** оператор может изменить inputs без потери остальных полей. + +**Given** zero/very large values, short windows либо long think time +**When** модель валидируется +**Then** divide-by-zero, overflow, NaN и unbounded schedule невозможны +**And** сообщение локализовано и указывает поле/допустимый диапазон. + +**Given** одинаковые inputs и seed +**When** модель вычисляется backend и frontend preview +**Then** fingerprints и curves совпадают в установленной tolerance +**And** golden fixtures и Playwright charts проходят. + +### Story 6.3: Авторизовать Load Run явным safety plan + +**Depends on:** Story 6.2 + +**Work type:** implementation + +**Deliverable:** Авторизовать Load Run явным safety plan. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an оператор установки, +I want проверять и подтверждать blast radius до запуска, +So that встроенный load test не повреждает production или внешние системы. + +**Requirements:** FR-38 + +**Acceptance Criteria:** + +**Given** опубликованный Scenario +**When** запрашивается preflight +**Then** сервер повторно pin-ит capability versions, effective auth scope, targets, DNS/IPs, estimated iterations/RPS/VU/duration и installation capacity +**And** формирует immutable LoadAuthorizationPlan с expiry и config/release fingerprint. + +**Given** target endpoints +**When** policy проверяется после DNS resolution +**Then** каждый destination входит в dedicated load allowlist, redirects/system proxy запрещены по умолчанию +**And** private/production target требует соответствующего явного operator policy. + +**Given** write Tools +**When** создаётся plan +**Then** обязательны sandbox/test credential refs, quotas и documented cleanup/verification contract +**And** production write load дополнительно требует global operator flag и отдельного typed confirmation. + +**Given** requested load +**When** она превышает local capability либо hard ceiling 1000 RPS, 512 VU, 2 часа или 10 000 000 iterations +**Then** plan отклоняется без override path +**And** UI показывает requested/effective limits. + +**Given** valid plan +**When** уполномоченный admin подтверждает exact fingerprint +**Then** server подписывает short-lived plan, audit сохраняет actor/reason/scope +**And** изменение Scenario, credentials, target resolution, release или config инвалидирует plan. + +**Given** authorization negative suite +**When** проверяются forged/expired/replayed plans, DNS rebinding, revoked refs, cross-workspace access и writes without cleanup +**Then** Start fail closed до dispatch +**And** security evidence связано с Scenario fingerprint. + +### Story 6.4: Исполнять нагрузку в изолированном Load Runner + +**Depends on:** Story 6.3 + +**Work type:** implementation + +**Deliverable:** Исполнять нагрузку в изолированном Load Runner. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an оператор, +I want запускать нагрузку отдельно от control plane, +So that генератор не лишает меня возможности наблюдать или остановить тест. + +**Requirements:** FR-38 + +**Acceptance Criteria:** + +**Given** dispatch context и public MCP call отдельного load-runner +**When** Run/iteration проходит cross-process boundary +**Then** canonical Request ID/Trace ID распространяются и сохраняются согласно Story 5.1; integration evidence связывает runner, MCP и execution без high-cardinality labels +**And** spec фиксирует telemetry producer/ownership: при собственном exporter runner проходит применимые per-process spool/restart/redaction tests Story 5.5, при делегировании — проверяется существующий владелец delivery; наличие short-lived credential само по себе не требует нового spool. + +**Given** valid signed LoadAuthorizationPlan +**When** Start принимается атомарно +**Then** PostgreSQL создаёт durable Load Run/dispatch intent с scoped ID и immutable plan fingerprint +**And** повторный Start idempotent, иной fingerprint конфликтует. + +**Given** dispatched Run +**When** отдельный `load-runner` принимает его +**Then** он проверяет signature/expiry/release/config, вызывает только public MCP endpoint и не имеет прямого доступа к domain tables/secrets +**And** raw credentials разрешаются через scoped short-lived mechanism. + +**Given** active Run +**When** генерируется load +**Then** RPS/VU/ramp/mix/seed соблюдаются в documented tolerance, inputs bounded, responses streaming-aggregated +**And** per-iteration raw payloads по умолчанию не сохраняются. + +**Given** installation under test +**When** load-runner работает +**Then** control traffic использует reserved runtime/connection capacity, runner отправляет heartbeat +**And** отсутствие heartbeat переводит Run в visible failed/interrupted state и прекращает новые dispatches. + +**Given** independent emergency path +**When** API/UI/DB перегружены +**Then** локальный Unix kill socket/host command останавливает generators без зависимости от control plane +**And** endpoint permission restricted, action записывается после восстановления. + +**Given** runner crash/restart/dependency fault suite +**When** faults вводятся на start, ramp, steady и stop stages +**Then** одновременно не работают два generation owner, ceilings не превышаются, state converges +**And** isolation/resource-limit evidence проходит. + +### Story 6.5: Показывать live statistics и безопасно останавливать Run + +**Depends on:** Story 6.4 + +**Work type:** implementation + +**Deliverable:** Показывать live statistics и безопасно останавливать Run. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an оператор, +I want в реальном времени видеть качество нагрузки и гарантированно остановить её, +So that могу быстро реагировать на деградацию. + +**Requirements:** FR-39 + +**Acceptance Criteria:** + +**Given** queued/running/stopping Load Run +**When** UI открывает live view +**Then** видны generation, completed/failed, latency p50/p95/p99, active workers/VU, current RPS, dropped iterations, queue wait и saturation +**And** данные содержат freshness timestamp и bounded update rate. + +**Given** thresholds Scenario +**When** новые aggregates поступают +**Then** UI показывает pass/warn/fail по каждому threshold без объявления terminal pass до завершения +**And** product-caused, upstream и generator errors классифицированы раздельно. + +**Given** оператор нажимает Stop и подтверждает action +**When** command принят через reserved control path +**Then** новые dispatches прекращаются в bounded time, in-flight обрабатываются по pinned drain/cancel policy +**And** repeated Stop idempotent, terminal Run не меняется. + +**Given** обычный control plane недоступен +**When** используется emergency stop +**Then** runner прекращает generation независимо, local status подтверждает stop +**And** UI после recovery reconciles observed state вместо ложного success. + +**Given** browser disconnect, смена Run или out-of-order updates +**When** live view reconnects +**Then** authoritative snapshot восстанавливается, stale events отбрасываются identity/revision guard +**And** loading/empty/paused/error/stale states локализованы RU/EN. + +**Given** live/stop E2E under saturation +**When** Run достигает configured ceiling и UI/API испытывают нагрузку +**Then** statistics остаются доступны, Stop проходит через reserved capacity +**And** Playwright, protocol и fault tests подтверждают отсутствие listener leaks/duplicate actions. + +### Story 6.6: Формировать immutable отчёты и сравнивать releases + +**Depends on:** Story 6.5 + +**Work type:** implementation + +**Deliverable:** Формировать immutable отчёты и сравнивать releases. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As an оператор производительности, +I want получить воспроизводимый отчёт и сравнить одинаковые Scenarios, +So that release decision основан на доказательствах. + +**Requirements:** FR-40 + +**Acceptance Criteria:** + +**Given** terminal Load Run +**When** aggregates финализируются +**Then** content-addressed immutable report содержит Scenario/plan fingerprint, release/image/config, timing, achieved load, outcomes, percentiles, saturation и threshold verdicts +**And** incomplete/interrupted Run обозначен явно и не может быть pass. + +**Given** human-readable report +**When** он открыт в UI +**Then** доступны bounded graphs, summary, assumptions, warnings и validated Grafana/trace links +**And** loading/error/missing-artifact states и RU/EN text реализованы. + +**Given** machine-readable report +**When** он экспортируется +**Then** JSON соответствует versioned schema, остаётся valid UTF-8/JSON при malformed/oversized upstream data +**And** raw secrets/payloads redacted, artifact digest проверяется. + +**Given** два Runs +**When** оператор выбирает Compare +**Then** сравнение разрешено только для совместимого Scenario fingerprint либо явно показывает semantic differences +**And** delta по throughput, success, latency, queue/saturation и thresholds вычисляется детерминированно. + +**Given** history на production-size dataset +**When** фильтруют по Scenario, release, period и outcome +**Then** API использует bounded opaque pagination, UI защищён от stale responses +**And** retention не удаляет artifact, связанный с release evidence. + +**Given** Reference Workload validation +**When** выполняются 100 RPS 30 минут и 250 RPS burst 5 минут +**Then** report проверяет NFR-P1/P1a/P1b/P4 с minute-level success/saturation и platform overhead +**And** результаты связаны с metrics/traces и одним build/config fingerprint. + +**Given** завершение Epic 6 +**When** RPS, VU и DAU flows проходят API/UI/runner tests +**Then** FR-36…FR-40 имеют reproducible evidence +**And** Capability Inventory и Load Runs Grafana dashboard обновлены; панели Story 5.11 проверены с реальными series, links и bounded queries этого Run, а не только с empty/provisioned состоянием. + +**Given** сохранённый Scenario и разрешённый оператор +**When** пользователь проходит полный Load Run workflow +**Then** единая навигация ведёт через `Scenario → load model → preflight → confirmation → live run → report` +**And** каждый шаг показывает pinned fingerprint/status, не допускает скрытого Start и позволяет безопасно вернуться к authoritative state после refresh/disconnect. + +**Given** сквозной UI flow +**When** меняется Scenario revision, authorization expires либо Run становится terminal вне текущего экрана +**Then** stale локальные данные инвалидируются, следующий допустимый action пересчитывается сервером +**And** Playwright проверяет полный маршрут, back/refresh/reconnect и RU/EN states как один interaction contract. + +## 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 проходит без внешней сети. + +## Epic 8: Доказанный production-релиз + +Команда всесторонне проверяет один immutable RC, формирует подписанное evidence, публикует честную readiness page и только после прохождения gate разрешает анонс на Хабре. + +### Story 8.1: Зафиксировать immutable RC и Evidence Manifest contract + +**Depends on:** Story 7.9 + +**Work type:** implementation + +**Deliverable:** Зафиксировать immutable RC и Evidence Manifest contract. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As a release owner, +I want привязать все проверки к одному неизменяемому кандидату, +So that release нельзя объявить готовым на смеси разных builds и configurations. + +**Requirements:** FR-52 + +**Acceptance Criteria:** + +**Given** release candidate build +**When** он замораживается +**Then** фиксируются source revision, Rust/Node toolchains, binary/package/image/offline-bundle digests и release identifier +**And** любая пересборка или изменение bytes создаёт новый RC. + +**Given** production qualification environment +**When** она регистрируется +**Then** content-addressed artifacts фиксируют deployment/config fingerprints, component versions, workload/corpus/matrix versions и environment class +**And** raw secrets/hosts/user data отсутствуют. + +**Given** Evidence Manifest schema +**When** принимается evidence item +**Then** versioned JSON Schema требует requirement/gate IDs, RC/artifact/config digests, commands, started/completed times, result, output digests, reviewer/owner и freshness +**And** unknown status, missing linkage или malformed time fail validation. + +**Given** automated или manual evidence +**When** оно добавляется +**Then** raw bounded artifacts сохраняются content-addressed, manifest append/revision history audit-able +**And** fail/blocked/not-run никогда не нормализуются в pass. + +**Given** release-signing step +**When** manifest snapshot подписывается +**Then** signature охватывает schema version, all referenced digests и gate inputs через documented offline trust root +**And** missing/altered/expired evidence делает validation fail closed. + +**Given** release-signing trust root и signer identity +**When** key создаётся, ротируется, отзывается либо объявляется скомпрометированным +**Then** versioned offline policy задаёт custody, allowed algorithms, validity, threshold/approval, public-key distribution и revocation statement +**And** verifier fail closed для unknown/revoked key, не требует online signer и не принимает rollback на более старый trust state без explicit recovery procedure. + +**Given** manifest verifier +**When** проверяется complete либо intentionally incomplete RC +**Then** он детерминированно выводит per-requirement status, stale/missing/conflicting evidence и exact failure reasons +**And** verifier работает offline и проходит tampering/forgery/rollback negative tests. + +### Story 8.2: Завершить Capability Inventory и обязательные CI gates + +**Depends on:** Story 8.1 + +**Work type:** implementation + +**Deliverable:** Завершить Capability Inventory и обязательные CI gates. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As a release owner, +I want видеть automated/manual evidence для каждого flow, +So that существующая или новая функция не остаётся непроверенной. + +**Requirements:** FR-46 + +**Acceptance Criteria:** + +**Given** все UI, Admin API, MCP, worker, runner и deployment capabilities +**When** Capability Inventory обновляется для RC +**Then** каждый flow имеет stable identifier, support status, owner, contract/FR/NFR links и required automated/manual evidence +**And** обязательная capability не скрыта feature flag или общим allow-marker. + +**Given** inventory item +**When** он declared supported +**Then** test pyramid включает применимые unit, integration/contract, PostgreSQL real-stack E2E, UI Playwright и negative security tests +**And** bug fixes имеют regression fixture/test. + +**Given** Gitea-compatible CI +**When** RC pipeline запускается +**Then** выполняются format/lint/build, Rust tests, migrations, contract/roundtrip, frontend build, Playwright, deployment smoke, corpus/matrix и security gates +**And** mandatory suite нельзя silently skip из-за отсутствующего service/secret. + +**Given** flaky либо retried mandatory test +**When** первоначальный attempt не pass +**Then** outcome остаётся non-pass до root-cause disposition и clean rerun policy +**And** SM-2 требует flaky mandatory tests = 0. + +**Given** evidence collection +**When** suite завершается +**Then** command, tool version, seed, duration, result и logs/report digests записываются в Evidence Manifest +**And** результат относится к exact RC/config. + +**Given** inventory validator +**When** остаётся capability без owner/contract/evidence либо применимая stable MCP capability `deferred` +**Then** release gate fail closed с exact item list +**And** 100% scope coverage machine-checkable. + +### Story 8.3: Выполнить полный versioned manual regression + +**Depends on:** Story 8.2 + +**Work type:** qualification + +**Deliverable:** Выполнить полный versioned manual regression. + +**Completion:** accepted evidence всех AC на указанном build/RC и среде; harness-only и внешний handoff не являются pass. + +As a release coordinator, +I want вручную пройти все ключевые пользовательские flows на production profile, +So that интеграционные и UX-дефекты обнаружены до публичного релиза. + +**Requirements:** FR-47 + +**Acceptance Criteria:** + +**Given** Capability Inventory и immutable RC +**When** генерируется manual checklist +**Then** он versioned и покрывает onboarding, Operations, OpenAPI upload, Agents, Tools, Resources, Prompts, keys/auth, approvals, history, Tasks, traces, metrics и Load Runs +**And** для каждого шага заданы preconditions, exact action, expected outcome и evidence capture. + +**Given** production-like fresh deployment +**When** reviewer выполняет checklist RU и EN +**Then** проверяются success, validation, empty, error, confirmation, retry/recovery и permission boundaries +**And** browser matrix assignment и test data documented. + +**Given** manual result +**When** шаг завершён +**Then** reviewer записывает pass/fail/blocked/not-run, timestamp, RC/config и bounded screenshot/log/support IDs +**And** blocked/not-run не считается pass. + +**Given** найденный defect +**When** он регистрируется +**Then** defect связан с checklist step, severity, owner и evidence; fix создаёт новый RC и regression test +**And** affected steps повторяются на новом RC. + +**Given** destructive/recovery scenario +**When** проверяются revoke, cancel, reconciliation, stop, backup/restore или upgrade +**Then** confirmation/audit и post-condition верифицируются отдельно +**And** test environment cleanup documented. + +**Given** manual gate +**When** checklist закрывается +**Then** 100% steps имеют accepted pass, Critical/High defects = 0 +**And** signed reviewer summary доказывает SM-3/SM-4 на exact RC. + +### Story 8.4: Квалифицировать compatibility matrices + +**Depends on:** Story 8.2 + +**Work type:** qualification + +**Deliverable:** Квалифицировать compatibility matrices. + +**Completion:** accepted evidence всех AC на указанном build/RC и среде; harness-only и внешний handoff не являются pass. + +As a release owner, +I want опубликовать доказанную совместимость протоколов и зависимостей, +So that пользователи знают точные поддерживаемые сочетания. + +**Requirements:** FR-48 + +**Acceptance Criteria:** + +**Given** feature-freeze date +**When** MCP matrix замораживается +**Then** exact latest stable revision и две предыдущие поддерживаемые stable revisions зафиксированы с полным capability inventory +**And** experimental/RC extensions тестируются отдельно и не заменяют stable support. + +**Given** MCP matrix +**When** protocol harness и минимум три representative clients выполняют её +**Then** negotiation, Tools, Resources/templates, Prompts, completion, logging, progress, cancellation, changes и Tasks/fallback проверены применимо к revision +**And** advertised capabilities точно совпадают с поведением. + +**Given** OpenAPI matrix/corpus +**When** versioned ≥50 OpenAPI 3.0/3.1 и Swagger 2.0 specs проходят preview/apply/E2E upload +**Then** ≥95% Operations actionable Draft, silent loss = 0, unsupported constructs имеют explicit findings +**And** каждый discovered defect добавляет immutable fixture. + +**Given** data/browser matrix +**When** выполняются PostgreSQL 16, optional Valkey 8/PG-only и current stable Chromium/Firefox/WebKit suites +**Then** core flows и degraded dependency behavior проходят +**And** exact image/browser versions и deviations recorded. + +**Given** matrix cell +**When** result fail/blocked/not-run или evidence устарело +**Then** соответствующее support claim не публикуется и release gate остаётся закрыт +**And** rerun требует того же RC либо новый RC. + +**Given** accepted matrices +**When** формируются release notes/docs +**Then** human- и machine-readable results содержат supported/not-applicable/experimental/deferred status, known limits и evidence digests +**And** они доказывают SM-8/SM-9. + +### Story 8.5: Квалифицировать производительность фиксированного RC + +**Depends on:** Story 8.2 + +**Work type:** qualification + +**Deliverable:** Квалифицировать производительность фиксированного RC. + +**Completion:** accepted evidence всех AC на указанном build/RC и среде; harness-only и внешний handoff не являются pass. + +As a release owner, +I want воспроизводимо проверить скорость фиксированного RC, +So that performance claims подтверждены измерениями, а не ожиданиями. + +**Requirements:** FR-49 + +**Acceptance Criteria:** + +**Given** Reference Deployment/Workload v1 и accepted baseline +**When** выполняются три последовательных baseline/load/stress Runs +**Then** проверены NFR-P1…P5, minute-level success/saturation, latency/platform overhead, UI responsiveness и production-size datasets +**And** regression >10% объяснён и одобрен либо исправлен на новом RC. + +**Given** baseline Run +**When** измеряется platform overhead относительно 10 ms stub upstream +**Then** p95 ≤50 ms и p99 ≤150 ms, discovery ≤150 ms p95 +**And** telemetry-enabled overhead отдельно сравнивается с disabled baseline. + +**Given** production-size dataset +**When** тестируются 2 000 Operations, 200 Agents, 500 active keys и 1 000 000 history records +**Then** основные UI screens интерактивны ≤2 s p95 и flows функционально не деградируют +**And** query/series/resource budgets остаются bounded. + +**Given** stress progression beyond qualified load +**When** система достигает saturation +**Then** overload rejection bounded и классифицирован, control/stop capacity сохраняется +**And** unbounded growth, crash или silent SLO accounting отсутствуют. + +**Given** completed qualification +**When** отчёт финализируется +**Then** raw metrics/traces/logs/reports content-addressed и linked к RC/config/workload/seeds +**And** automated verdict доказывает SM-5. + +**Given** interrupted либо modified run +**When** artifact/config/workload digest меняется или telemetry gap необъяснён +**Then** run invalidated, частичная длительность не объединяется с другой +**And** три последовательных Runs начинаются заново на текущем RC. + +### Story 8.6: Провести 72-часовой soak и recovery qualification + +**Depends on:** Story 8.5 + +**Work type:** qualification + +**Deliverable:** Провести 72-часовой soak и recovery qualification. + +**Completion:** accepted evidence всех AC на указанном build/RC и среде; harness-only и внешний handoff не являются pass. + +As a release owner, +I want длительно проверить устойчивость того же RC под нагрузкой и сбоями, +So that recovery и отсутствие накопительных дефектов доказаны до burn-in. + +**Requirements:** FR-49 + +**Acceptance Criteria:** + +**Given** fixed RC после performance pass +**When** запускается непрерывный 72-hour soak с prescribed mix +**Then** нет data loss, deadlock, duplicate terminal outcomes, unbounded memory/disk/cardinality growth или SLI violation +**And** workload mix удерживается в tolerance, probes excluded from eligible event count. + +**Given** qualification window +**When** вводятся process restart, network partition, PostgreSQL/Valkey/backend outage, disk pressure и telemetry outage +**Then** declared fail-open/fail-closed behavior, drain, lease recovery, spool replay и alerts соответствуют contracts +**And** safety path не деградирует silently. + +**Given** 10 000 queued Tasks и concurrent sync/background work +**When** fault убран +**Then** queue/backlog recovery, fairness, start latency и deadlines остаются в NFR-P2/R5 envelope +**And** terminal accounting сходится. + +**Given** scheduled recovery probes +**When** выполняются backup/restore, worker restart и optional dependency rebuild +**Then** реальный MCP call, Task resume и correlation подтверждают восстановление +**And** probe outcomes связаны с fault window и expected recovery target. + +**Given** completed 72-hour qualification +**When** отчёт финализируется +**Then** raw metrics/traces/logs/recovery reports content-addressed и linked к RC/config/workload/fault schedule +**And** automated verdict доказывает 72-hour portion SM-6. + +**Given** interruption, digest change либо необъяснённый telemetry gap +**When** целостность qualification нарушена +**Then** run invalidated, partial duration не объединяется с другой +**And** полные 72 часа начинаются заново на текущем RC. + +### Story 8.7: Закрыть security release qualification + +**Depends on:** Story 8.2 + +**Work type:** qualification + +**Deliverable:** Закрыть security release qualification. + +**Completion:** accepted evidence всех AC на указанном build/RC и среде; harness-only и внешний handoff не являются pass. + +As a security reviewer, +I want проверить threat model, supply chain и ключевые attack surfaces, +So that публичный release не содержит известных Critical/High рисков. + +**Requirements:** FR-50 + +**Acceptance Criteria:** + +**Given** final feature surface RC +**When** threat-model review выполняется +**Then** обновлены assets, trust boundaries, actors, abuse cases и mitigations для Admin/MCP, OpenAPI, outbound, Resources/Prompts, Tasks, observability и Load Runner +**And** каждый in-scope threat связан с control/test/evidence либо blocker. + +**Given** exact source/dependencies/images/bundle +**When** запускаются pinned fresh SAST, dependency, container, secret и license scans +**Then** tool/rules/database versions и timestamps captured +**And** реальные Critical/High vulnerabilities/findings = 0, suppressions имеют reviewer/rationale/expiry. + +**Given** authorization/security test suite +**When** проверяются tenant/Agent isolation, bootstrap/session/CSRF/CORS, key lifecycle, approvals, idempotency, Task fencing и LoadAuthorizationPlan +**Then** default deny и fail-closed guarantees подтверждены +**And** metadata existence не раскрывается unauthorized actor. + +**Given** outbound/OpenAPI attack suite +**When** проверяются DNS rebinding, redirect/proxy, private IP, external refs, zip/path traversal, entity/schema bombs и oversized bodies +**Then** SSRF/resource bounds выполняются на каждом connection/stage +**And** crash/silent partial import отсутствуют. + +**Given** redaction audit +**When** canary secrets помещаются в headers, cookies, query, JSON/YAML, errors, browser events, traces, metrics, reports, exports и diagnostics +**Then** ни один canary не выходит за разрешённую encrypted authority +**And** negative regression evidence покрывает NFR-S2/O5. + +**Given** security gate review +**When** findings triaged +**Then** Critical/High product/security defects = 0, Medium имеют owner и не нарушают SLO/data integrity/security +**And** signed disposition и scan artifacts доказывают FR-50/SM-4. + +### Story 8.8: Проверить документацию и incident runbooks новым пользователем + +**Depends on:** Story 8.2 + +**Work type:** qualification + +**Deliverable:** Проверить документацию и incident runbooks новым пользователем. + +**Completion:** accepted evidence всех AC на указанном build/RC и среде; harness-only и внешний handoff не являются pass. + +As a новый self-hosted пользователь, +I want получить проверенную документацию от установки до диагностики, +So that могу безопасно эксплуатировать Crank без скрытых знаний команды. + +**Requirements:** FR-51 + +**Acceptance Criteria:** + +**Given** release documentation set +**When** он собирается +**Then** включает fresh quickstart, production/offline install, configuration, security model, capabilities/limits, compatibility matrices, troubleshooting и upgrade/deprecation guidance +**And** commands/versions соответствуют exact RC и canonical `deploy/community`. + +**Given** operations guide +**When** оператор настраивает observability +**Then** документированы metrics/buckets/cardinality, Prometheus/Grafana/GlitchTip integration, dashboards, SLO denominators/exclusions и telemetry loss handling +**And** compatible external endpoints описаны без cloud requirement. + +**Given** recovery guide +**When** оператор выполняет backup/restore, key recovery/rotation, drain/restart, N-1 upgrade или rollback +**Then** preconditions, irreversible boundaries, validation probes и failure recovery приведены пошагово +**And** raw secret material не предлагается хранить в manifest/config. + +**Given** shipped Critical/High alert +**When** проверяется runbook link +**Then** существует versioned page с meaning, impact, safe diagnostics, mitigation, recovery и verification +**And** базовые действия доступны при outage Grafana/GlitchTip. + +**Given** fresh-user validation на чистом online и air-gapped host +**When** участник без внутреннего контекста следует только shipped docs +**Then** он устанавливает продукт, публикует Tool, делает MCP call, находит trace и выполняет backup/restore probe +**And** ошибки/неясности фиксируются как release defects. + +**Given** docs CI +**When** проверяются links, commands, config fields, screenshots, schemas и runbook alert coverage +**Then** stale/broken content блокирует release +**And** signed fresh-user report и docs digest входят в Evidence Manifest. + +### Story 8.9: Провести 30-дневный burn-in и опубликовать readiness page + +**Depends on:** Story 8.3, Story 8.4, Story 8.6, Story 8.7, Story 8.8 + +**Work type:** qualification + +**Deliverable:** Провести 30-дневный burn-in и опубликовать readiness page. + +**Completion:** accepted evidence всех AC на указанном build/RC и среде; harness-only и внешний handoff не являются pass. + +As a потенциальный Community пользователь, +I want видеть длительно подтверждённую готовность и честные ограничения, +So that могу принять осознанное решение о production использовании. + +**Requirements:** FR-49, FR-53 + +**Acceptance Criteria:** + +**Given** тот же immutable RC после 72-hour qualification +**When** начинается supervised burn-in +**Then** он длится непрерывные 30 календарных дней без ускорения и выполняет Reference Workload mix ±2 п.п. +**And** probes не засчитываются в минимум 1 000 000 eligible events. + +**Given** burn-in execution +**When** собираются SLIs +**Then** product/control availability, latency, Task deadlines, trace delivery/completeness, resource growth и error budgets оцениваются на полном окне +**And** 100% e2e flows имеют одинаковый Trace ID в UI/history. + +**Given** planned fault windows +**When** вводятся restart/dependency/telemetry outage scenarios +**Then** recovery matrix проходит, spool replay завершается, alert срабатывает +**And** открытого Telemetry Loss Record, data loss, deadlock или unbounded growth не остаётся. + +**Given** остановка qualification observer/workload, незапланированное изменение среды либо RC/config/workload digest change +**When** целостность burn-in нарушена +**Then** gate invalidates run и новый 30-day window начинается заново +**And** paused time нельзя вычесть или склеить с другим RC. + +Плановый restart приложения в зафиксированном fault schedule не равен остановке qualification run: независимые observer/workload сохраняют непрерывность, same-RC fingerprints и полное evidence fault window. Если это не доказано, действует invalidation выше. Scope Story 8.9 конечен: одна accepted qualification и связанная readiness page; реакция page на stale evidence проверяется сценариями, а не бессрочным обслуживанием в coding session. + +**Given** accepted evidence +**When** readiness page генерируется +**Then** она публикует supported scope, deployment/reference limits, security/data-egress model, exact compatibility, SLO evidence и known non-blocking issues +**And** unsupported/experimental/deferred items обозначены явно без маркетингового расширения claims. + +**Given** readiness review +**When** known issue изменяется или evidence устаревает +**Then** page и machine-readable source обновляются с reviewer/audit +**And** Critical/High, SLO/data-integrity/security issue блокирует publication status. + +**Given** burn-in completion +**When** manifest validator принимает results +**Then** доказаны 30-day portions SM-6/SM-7 и FR-49/FR-53 на exact RC +**And** readiness page digest включён в подписанный Evidence Manifest. + +### Story 8.10: Вычислять Habr Release Gate без исключений + +**Depends on:** Story 8.9 + +**Work type:** implementation + +**Deliverable:** Вычислять Habr Release Gate без исключений. + +**Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. + +As a release owner, +I want получить однозначное machine-verifiable разрешение на анонс, +So that Community release публикуется только после полного доказательства готовности. + +**Requirements:** FR-54 + +**Acceptance Criteria:** + +**Given** signed Evidence Manifest exact RC +**When** Habr Gate evaluator запускается offline +**Then** он проверяет trust/signature/schema, immutable artifact linkage, freshness и coverage FR-1…FR-53 +**And** FR-54 не используется как собственное доказательство. + +**Given** success-metric evidence +**When** evaluator вычисляет gate +**Then** SM-2 automated quality, SM-3 manual, SM-4 defects, SM-5 performance, SM-6 reliability, SM-7 traceability, SM-8 OpenAPI, SM-9 MCP и SM-10 deployment/free scope имеют explicit pass +**And** denominators/thresholds совпадают с PRD, а inferred/manual override pass запрещён. + +**Given** обязательная capability deferred/hidden, Critical/High defect, SLO failure, flaky mandatory suite, incomplete manual pass либо incompatible artifact digest +**When** gate оценивается +**Then** status строго `BLOCKED` с exact requirement/evidence reasons +**And** waiver/exception path для этих условий отсутствует. + +**Given** Medium/known non-blocking issue +**When** он допускается readiness contract +**Then** требуются owner, rationale, user impact, workaround/target и proof отсутствия SLO/data-integrity/security impact +**And** issue опубликован на readiness page. + +**Given** все mandatory checks accepted +**When** gate финализируется +**Then** создаётся подписанный immutable `PUBLIC_READY` verdict с RC/bundle/readiness/manifest digests и timestamp +**And** только этот verdict разрешает release tooling сформировать Habr announcement assets/tag. + +**Given** artifact, manifest, page или evidence изменены после verdict +**When** release tooling повторно проверяет inputs +**Then** verdict становится invalid и publication блокируется до нового полного evaluation +**And** уже проверенные bytes нельзя заменить тем же version label. + +**Given** positive/negative gate fixtures +**When** CI проверяет evaluator +**Then** complete fixture passes, каждый missing/stale/tampered/failing input blocks детерминированно +**And** завершение Epic 8 подтверждает FR-46…FR-54 и production-ready Community release. + +## Story decomposition mapping — 2026-09-13 + +99 stories; 25 завершённых сохраняют номера и статус. Номера AC ниже относятся к предыдущей ревизии `epic-2-sequential`; разделённые общие UI/test AC перенесены по принадлежащему каждой slice поведению, не ослаблены. Архивные run/spec/evidence не перенумеровываются; новые runs используют только текущую ревизию. + +| Previous story | Current story | Previous AC groups | +|---|---|---| +| 2.10 | 2.10 | 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12 | +| 2.10 | 2.11 | 3/5/9 (UI perspective), 11 | +| 3.4 | 3.4 | 1, 2, 3, 4, 7 | +| 3.4 | 3.5 | 5, 6, 7 | +| 3.11 | 3.12 | 1, 2, 3, 10, 11 | +| 3.11 | 3.13 | 4, 5, 10, 11 | +| 3.11 | 3.14 | 6, 7, 8, 11 | +| 3.11 | 3.15 | 9, 10, 11 | +| 3.13 | 3.17 | 1, 5, 6 | +| 3.13 | 3.18 | 2, 5, 6 | +| 3.13 | 3.19 | 3, 4, 6 | +| 4.5 | 4.5 | 1, 2, 3, 6 | +| 4.5 | 4.6 | 4, 5, 6 | +| 4.7 | 4.8 | 1, 2, 3, 6, 7, 8 | +| 4.7 | 4.9 | 4, 5, 6, 7, 8 | +| 5.9 | 5.9 | 1, 2, 3, 4, 5, 6 | +| 5.9 | 5.10 | 7, 8, 9 | +| 5.11 | 5.12 | 1, 2, 3, 4, 5 | +| 5.11 | 5.13 | 7, 8, 9, 10, 6 | + +Дополнительные перемещения: прежние 6.1 AC7–8 → 6.6; прежний 7.5 AC4 → 7.9. Все остальные AC сохраняются у единственного successor: 2.11 → 2.12; 2.12 → 2.13; 2.13 → 2.14; 2.14 → 2.15; 3.5 → 3.6; 3.6 → 3.7; 3.7 → 3.8; 3.8 → 3.9; 3.9 → 3.10; 3.10 → 3.11; 3.12 → 3.16; 3.14 → 3.20; 4.6 → 4.7; 4.8 → 4.10; 5.10 → 5.11. diff --git a/_bmad-output/planning-artifacts/implementation-readiness-report-2026-08-08.md b/_bmad-output/planning-artifacts/implementation-readiness-report-2026-08-08.md new file mode 100644 index 0000000..bdade73 --- /dev/null +++ b/_bmad-output/planning-artifacts/implementation-readiness-report-2026-08-08.md @@ -0,0 +1,341 @@ +--- +stepsCompleted: ['step-01-document-discovery', 'step-02-prd-analysis', 'step-03-epic-coverage-validation', 'step-04-ux-alignment', 'step-05-epic-quality-review', 'step-06-final-assessment'] +lastStep: 'step-06-final-assessment' +lastSaved: '2026-08-08' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' +missingDocumentTypes: + - 'UX Design' +resolvedFindings: + - 'IR-MAJOR-001: Story 2.4 OutboundPolicy prerequisite corrected to Story 1.9 on 2026-08-08' +--- + +# Отчёт об оценке готовности к реализации + +**Дата:** 2026-08-08 +**Проект:** crank + +## Обнаружение документов + +### Документы, выбранные для оценки + +| Тип | Документ | Размер | Изменён | +|---|---|---:|---| +| Эпики и Story | `_bmad-output/planning-artifacts/epics.md` | 295520 байт | 2026-08-08 19:08 Europe/Moscow | +| PRD | `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` | 89711 байт | 2026-08-03 15:42 Europe/Moscow | +| Технический addendum | `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md` | 11960 байт | 2026-08-03 15:42 Europe/Moscow | +| Архитектура | `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` | 37203 байт | 2026-08-03 19:30 Europe/Moscow | + +### Предупреждения обнаружения + +- Отдельный UX Design не найден по стандартным шаблонам `*ux*.md` или sharded UX. +- Дубликатов в whole/sharded форматах не найдено. +- PRD, addendum и Architecture лежат во вложенных нестандартных каталогах без `index.md`; их канонические пути восстановлены из подтверждённого `inputDocuments` frontmatter файла `epics.md`. + +Пользователь подтвердил продолжение. Восстановленные канонические источники включены в оценку; UX намеренно отсутствует в рамках Fast Path и оценивается на достаточность, а не молча считается готовым отдельным артефактом. + +## Анализ PRD + +Авторитетные PRD и технический addendum восстановлены по каноническим путям из `epics.md` и полностью прочитаны. Ниже приведены извлечённые требования. + +### Функциональные требования + +- **FR-1 — Управление lifecycle Operation:** Администратор может создавать, тестировать, версионировать, публиковать, архивировать, импортировать и экспортировать Operations без изменения уже опубликованного поведения. +- **FR-2 — Безопасное REST-выполнение:** Crank выполняет поддерживаемые REST Operations с mapping, authentication, timeout, retry, cache, idempotency, response limits и outbound policy. +- **FR-3 — Secrets и ключи:** Администратор может создавать, ротировать и отзывать auth profiles, MCP keys и approval keys с one-time disclosure raw value. +- **FR-4 — Versioned Agent catalog:** Администратор может собирать опубликованный Agent из Published Versions capabilities и выбирать direct или search mode. +- **FR-5 — Approval и защита side effects:** Operation может требовать подтверждение, а повторный запрос не создаёт конкурирующие approval records. +- **FR-6 — История и usage:** UI предоставляет фильтруемую Invocation History и Usage по периоду, Agent и Operation с безопасными previews, outcome и percentiles. +- **FR-7 — Предварительный анализ без мутаций:** Администратор получает preview endpoints, groups, names, mappings, schemas, conflicts, warnings и unsupported constructs до создания Draft. +- **FR-8 — Полнота HTTP-контрактов:** Импорт поддерживает стандартные REST methods, path/query/header/cookie parameters, все успешные `2xx` responses и распространённые JSON, form и multipart request bodies. **Решение A-3:** XML payloads остаются вне production scope, но обнаруживаются как явный unsupported finding. +- **FR-9 — References и composition:** Importer корректно разрешает локальные references и безопасно обрабатывает разрешённые внешние references; `allOf`, `oneOf`, `anyOf`, recursion и discriminators либо сохраняются, либо блокируют создание с объяснением. +- **FR-10 — Security schemes:** Importer распознаёт поддерживаемые bearer/basic/api-key schemes и предлагает привязку к Auth Profile без импорта raw secret. +- **FR-11 — Управление конфликтами и повторный импорт:** Администратор может выбрать skip, rename или создание новой версии; повтор одного import request безопасен и атомарен. +- **FR-12 — Regression corpus:** Проект поддерживает versioned corpus реальных и синтетических спецификаций с expected import outcomes. +- **FR-13 — Protocol negotiation и совместимость:** MCP endpoint согласует protocol version и capabilities, не рекламируя неподдержанное поведение. +- **FR-14 — Полный Tools contract:** Существующие `tools/list` и `tools/call` поддерживают pagination, structured content/errors, progress, cancellation и list-changed notification там, где это предусмотрено согласованной версией. +- **FR-15 — Versioned Resources:** Администратор может создавать, preview, тестировать, версионировать, публиковать, архивировать, импортировать и экспортировать Resources, затем привязывать Published Versions к Agent. +- **FR-16 — Resource types:** Resource может предоставлять static text/JSON/binary content или динамически получать разрешённые данные из REST source по URI template. **Решение A-5:** динамический REST-backed Resource входит в public-launch scope, чтобы Resources давали ценность сверх статических файлов. +- **FR-17 — Versioned Prompts:** Администратор может создавать, preview, тестировать, версионировать, публиковать, архивировать, импортировать и экспортировать parameterized Prompts, затем привязывать Published Versions к Agent. +- **FR-18 — Prompt composition:** Prompt поддерживает системные/пользовательские/assistant messages и разрешённые ссылки на Resources без выполнения произвольного кода. +- **FR-19 — Completion, logging и notifications:** Crank поддерживает применимые stable completion, server logging, progress и capability-change notifications с соблюдением negotiated client capabilities. +- **FR-20 — MCP compatibility evidence:** Каждый production release публикует проверенную матрицу protocol versions, methods, extensions и representative clients. +- **FR-21 — Execution mode:** Для Tool задаётся режим `synchronous`, `background` или `adaptive`; клиенту возвращается поведение, совместимое с negotiated MCP capabilities. +- **FR-22 — Durable Task lifecycle:** Task имеет устойчивый ID, owner scope, внутренние статусы `queued`, `working`, `input_required`, `outcome_unknown`, `completed`, `failed`, `cancelled`, progress, timestamps, attempts и result/error. Protocol adapter отображает внутреннее состояние только в допустимые negotiated MCP statuses, не делая `outcome_unknown` retriable failure. +- **FR-23 — Recovery и delivery semantics:** Принятый Task сохраняется до подтверждения клиенту и восстанавливается после рестарта worker или сервиса. +- **FR-24 — Concurrency и backpressure:** Оператор управляет глобальными, per-Agent и per-Tool лимитами; система применяет bounded queues, fairness, timeout и overload rejection. +- **FR-25 — Retry, cancellation и deadlines:** Task policy определяет attempts, backoff, deadline, cancellation и поведение outcome-unknown. +- **FR-26 — Task operations в UI:** Администратор может фильтровать Tasks, просматривать progress/attempts/trace, отменять разрешённые Tasks и повторять безопасно повторяемые failures. +- **FR-27 — Correlation identity:** Каждый входящий запрос получает валидированные Request ID и Trace ID; W3C context распространяется через API, MCP, runtime, upstream и Task boundaries. +- **FR-28 — Поиск и переход из UI:** UI показывает, копирует и ищет Request ID и Trace ID, а также формирует deep link в настроенный trace backend. +- **FR-29 — GlitchTip integration:** Production profile отправляет errors и performance transactions в GlitchTip, сохраняя корреляцию logs/spans. **Решение A-7:** для типичной Community-установки default trace sample rate равен 100% с retention 7 дней; errors хранятся не менее 30 дней, а sampling/retention конфигурируются оператором. +- **FR-30 — Browser observability:** UI фиксирует navigation/API errors и browser spans, связывая их с server Trace ID без отправки чувствительных данных. +- **FR-31 — Telemetry resilience:** Очереди telemetry bounded; export failures, drops и saturation измеряются; graceful shutdown завершает принятые requests и flushes telemetry в пределах timeout. +- **FR-32 — Технические метрики:** Prometheus получает low-cardinality metrics по traffic, error, duration, saturation, queues/workers, DB/cache, MCP sessions, Tools/Resources/Prompts/Tasks и telemetry health. +- **FR-33 — Бизнес-метрики:** Crank локально считает activation и adoption events: создание/публикация capabilities, import outcome, Agent binding, first successful MCP call, active Agent, capability usage и Load Run outcome. +- **FR-34 — Prometheus и Grafana integration:** Community distribution предоставляет готовые scrape config, recording/alert rules, provisioned datasource и versioned Grafana dashboards. +- **FR-35 — SLO и error budgets:** Grafana отображает availability, latency-under-threshold, successful execution и Task deadline SLO с 30-дневным окном и fast/slow burn alerts. +- **FR-36 — Scenario и профиль нагрузки:** Администратор выбирает опубликованные Tools и задаёт mix, test data, RPS или VU, duration, ramp и thresholds. +- **FR-37 — Оценочный DAU-профиль:** UI преобразует DAU в arrival profile только при заданных actions per session, sessions per user per day, activity window, think time и scenario mix. +- **FR-38 — Безопасность запуска:** Load Run имеет RBAC-equivalent admin restriction, target allowlist, configurable hard limits, confirmation, emergency stop и запрет production targets по умолчанию. +- **FR-39 — Live execution и stop:** UI показывает generation rate, completed/failed, latency percentiles, active workers, dropped iterations, queue wait и saturation; пользователь может безопасно остановить Run. +- **FR-40 — Отчёт и история:** Load Run завершается immutable summary с pass/fail thresholds, environment fingerprint, release/version, графиками и ссылками на Grafana/traces. +- **FR-41 — Deployment profiles:** Community поставляет minimal и production profiles. Minimal сохраняет функциональность без полного observability stack; production включает все компоненты, необходимые для Release Gate. **Решение A-10:** Prometheus, Grafana и GlitchTip предоставляются как optional production profile, но могут быть заменены внешними endpoints. +- **FR-42 — Закрытый контур:** Все capabilities, telemetry и product metrics работают без исходящего cloud dependency; outbound доступ разрешается только к явно настроенным upstream и registries во время установки/обновления. +- **FR-43 — Upgrade, backup и recovery:** Администратор получает versioned migrations, preflight, backup/restore, rollback guidance и совместимый rolling/restart upgrade path. +- **FR-44 — Container hardening:** Production containers используют non-root user, минимальные privileges, health/readiness, graceful shutdown, resource limits, log rotation guidance и compatible read-only filesystem где возможно. +- **FR-45 — Единый конфигурационный контракт:** Документация, environment examples, Compose profiles, runtime parser и UI отражают один набор поддерживаемых параметров. +- **FR-46 — Автоматизированная test pyramid:** Каждый capability имеет unit, contract/integration и применимый real-stack E2E уровень; security boundaries покрыты negative tests. +- **FR-47 — Полный ручной regression pass:** Перед Release Candidate выполняется versioned manual checklist на production-like deployment с evidence по каждому пользовательскому пути. +- **FR-48 — Compatibility matrices:** Release проверяется по OpenAPI corpus, MCP protocol/client matrix, PostgreSQL/Valkey modes и supported browser matrix. +- **FR-49 — Performance, soak и recovery tests:** Release pipeline или управляемый pre-release pipeline выполняет baseline/load/stress, 72-hour soak, restart/recovery и dependency-failure scenarios. +- **FR-50 — Security release evidence:** Перед public launch выполняются threat-model review, dependency/container scan, secret/redaction audit, SSRF/authz/idempotency negative tests и review новых attack surfaces Tasks/Resources/Load Runs. +- **FR-51 — Документация и runbooks:** Пользователь получает quickstart, production deployment, capability guides, compatibility matrix, limits, troubleshooting, metrics catalog, dashboards, SLO alerts, backup/restore и incident runbooks. +- **FR-52 — Release Candidate:** Команда создаёт immutable RC artifact и выполняет все product, migration, deployment, manual и non-functional проверки именно на нём. +- **FR-53 — Публичная readiness-страница:** Перед анонсом публикуется честное описание supported scope, limits, security model, compatibility и известных non-blocking issues. +- **FR-54 — Habr Release Gate:** Публикация на Хабре разрешена только при одновременном выполнении всех условий §9 и §10. + +**Всего FR: 54** + +### Нефункциональные требования + +- **NFR-P1:** 100 RPS смешанного MCP/runtime workload в течение 30 минут и 250 RPS burst в течение 5 минут без нарушения SLO. +- **NFR-P1a:** в каждую минуту 250 RPS burst product-caused success ratio ≥99,95%, p95/p99 platform overhead остаются в NFR-P4, а saturation rejection ≤0,1%; 30-дневное усреднение не может скрыть burst failure. +- **NFR-P1b:** в каждую минуту 100 RPS steady Run product-caused success ratio ≥99,95%, p95/p99 остаются в NFR-P4, queue wait/age сохраняют установленную границу и saturation rejection ≤0,1%. +- **NFR-P2:** не менее 128 одновременно исполняемых synchronous/background Executions и 10 000 queued Tasks без unbounded resource growth. +- **NFR-P3:** Reference Deployment поддерживает 2 000 Operations, 200 Agents, 500 active keys и 1 000 000 записей Invocation History без функциональной деградации. +- **NFR-P4:** добавочная задержка Crank при stub upstream ≤50 мс p95 и ≤150 мс p99; catalog/resource/prompt discovery ≤150 мс p95. +- **NFR-P5:** основные UI-экраны становятся интерактивными ≤2 с p95 на локальной сети при Reference Deployment и production-size dataset. +- **NFR-R1:** product-caused successful-request ratio ≥99,95% на Reference Workload; control-plane availability ≥99,9% за 30-дневное окно, исключая документированное обслуживание. +- **NFR-R2:** ноль потерянных подтверждённых configuration changes, Published Versions, approvals и accepted Tasks при штатном или аварийном restart с исправным durable storage. +- **NFR-R3:** graceful shutdown прекращает приём новых requests, завершает или надёжно сохраняет принятые работы и укладывается в 30 секунд по умолчанию. +- **NFR-R4:** для disaster restore production profile использует проверяемый WAL/PITR path с RPO ≤5 минут и RTO ≤30 минут на Reference Deployment; фактическая гарантия зависит от доступности operator-provided backup storage. +- **NFR-R5:** Task начинает выполнение ≤5 секунд p95 при нагрузке в пределах NFR-P1; recovery зависших leases после restart ≤60 секунд. +- **NFR-S1:** default deny для workspace/Agent/capability access; чужой объект не раскрывает metadata. +- **NFR-S2:** секреты зашифрованы at rest, не возвращаются после создания/ротации и исключены из logs, traces, metrics, reports и exports. +- **NFR-S3:** outbound policy применяется после DNS resolution на каждом соединении; redirects и system proxy выключены по умолчанию. +- **NFR-S4:** bounded input, body, response, concurrency, queue и cardinality limits предотвращают неограниченное накопление ресурсов. +- **NFR-S5:** production release не содержит известных Critical/High vulnerabilities или Critical/High findings. +- **NFR-S6:** никакая usage/telemetry информация не покидает закрытый контур без явной opt-in конфигурации администратора. +- **NFR-S7:** недоступный mandatory coordination/cache/approval/idempotency store переводит зависимый safety path в fail-closed состояние; safety-механизм никогда не отключается молча. +- **NFR-S8:** previews, events, diagnostics и JSON reports ограничиваются с сохранением валидного UTF-8/JSON и проходят oversized/malformed negative tests. +- **NFR-O1:** 100% входящих UI/Admin API/MCP requests имеют отдельные Request ID и Trace ID; невалидный входящий Request ID заменяется UUIDv7; 100% Execution/Task records сохраняют оба идентификатора. +- **NFR-O2:** production profile генерирует 100% traces; Trace delivery latency SLI ≥99,99%, Trace eventual completeness = 100% за 25 часов при outage ≤24 часов, а каждый Telemetry Loss Record нарушает SLO и создаёт bounded-spool accounting/alert. +- **NFR-O2a:** capacity test сериализует фактический p95 trace size и доказывает 30-hour spool capacity/24-hour outage envelope в выделенном disk budget без eviction и влияния на PostgreSQL/artifact safety reserve. +- **NFR-O3:** observability overhead ≤5% p95 latency и ≤10% CPU на Reference Deployment относительно telemetry-disabled baseline. +- **NFR-O4:** метрики не создают series из пользовательских identifiers или произвольных значений; traces связываются через exemplars/deep links. +- **NFR-O5:** redaction имеет negative regression tests для headers, cookies, query, JSON, YAML, errors, browser events и Load Run artifacts. +- **NFR-C1:** Rust MSRV, Edition, workspace boundaries и публичные wire-контракты изменяются только отдельным совместимым change. +- **NFR-C2:** latest stable MCP на feature freeze и две поддерживаемые предшествующие версии проходят protocol matrix. +- **NFR-C3:** breaking change требует versioning/deprecation note и migration path; Published Version остаётся неизменяемой. +- **NFR-C4:** RU и EN получают новый пользовательский текст одновременно. + +**Всего NFR: 30** + +### Дополнительные требования + +- Reference Deployment: Linux x86_64, 4 vCPU, 8 GiB RAM, PostgreSQL 16, optional/rebuildable Valkey 8, заданные SSD/network budgets; генератор нагрузки и полный observability profile изолированы от измеряемых сервисов. +- Reference Workload v1 версионируется и имеет checksum; он фиксирует dataset, capability mix, payloads, upstream behavior, cache state, background distribution и telemetry mode. +- Community scope остаётся single-workspace, single-admin и REST-upstream-only; Resources, Prompts, Tasks и Load Runs являются явными расширениями scope. +- Последовательность выпуска: Baseline Frozen → Feature Complete → Quality Complete → immutable RC → 30-дневный Public Ready burn-in → Habr Gate. +- SM-1—SM-10 являются обязательным release-gate evidence; SM-11—SM-15 — post-launch product metrics, а SM-C1—SM-C5 предотвращают vanity- и небезопасные оптимизации. +- Четыре deferred decisions имеют владельцев и точки принятия: stable MCP versions, три representative clients, benchmark-проверка targets и retention в рамках storage budget. +- Addendum сохраняет технические направления и evidence contracts, не переопределяя нормативные outcomes PRD. + +### Оценка полноты PRD + +**Статус: ДОСТАТОЧНО ПОЛНО ДЛЯ ПРОВЕРКИ ТРАССИРУЕМОСТИ.** PRD имеет статус final, содержит 54 нумерованных FR, 30 нумерованных NFR, измеримые release gates, явные non-goals, границы scope, подтверждённые решения и владельцев deferred decisions. Широта требований создаёт execution risk, но сам источник требований авторитетен и проверяем. + +## Проверка покрытия эпиками + +### Матрица покрытия + +| FR | Покрытие Epic/Story | Статус | +|---|---|---| +| FR-1 | Эпик 1, Story 1.7; Эпик 1, Story 1.16 | ✓ Покрыто | +| FR-2 | Эпик 1, Story 1.8; Эпик 1, Story 1.9 | ✓ Покрыто | +| FR-3 | Эпик 1, Story 1.10; Эпик 1, Story 1.11; Эпик 1, Story 1.12 | ✓ Покрыто | +| FR-4 | Эпик 1, Story 1.13; Эпик 1, Story 1.16 | ✓ Покрыто | +| FR-5 | Эпик 1, Story 1.14 | ✓ Покрыто | +| FR-6 | Эпик 1, Story 1.15 | ✓ Покрыто | +| FR-7 | Эпик 2, Stories 2.1a–2.1d; Эпик 2, Story 2.2; Эпик 2, Story 2.6; Эпик 2, Story 2.9 | ✓ Покрыто | +| FR-8 | Эпик 2, Story 2.2; Эпик 2, Story 2.4 | ✓ Покрыто | +| FR-9 | Эпик 2, Stories 2.1a–2.1d; Эпик 2, Story 2.3 | ✓ Покрыто | +| FR-10 | Эпик 2, Story 2.5 | ✓ Покрыто | +| FR-11 | Эпик 2, Story 2.7; Эпик 2, Story 2.9 | ✓ Покрыто | +| FR-12 | Эпик 2, Story 2.8 | ✓ Покрыто | +| FR-13 | Эпик 3, Story 3.1 | ✓ Покрыто | +| FR-14 | Эпик 3, Story 3.2; Эпик 3, Story 3.3; Эпик 3, Story 3.4 | ✓ Покрыто | +| FR-15 | Эпик 3, Story 3.5; Эпик 3, Story 3.6; Эпик 3, Story 3.7; Эпик 3, Story 3.8 | ✓ Покрыто | +| FR-16 | Эпик 3, Story 3.5; Эпик 3, Story 3.6; Эпик 3, Story 3.7; Эпик 3, Story 3.9; Эпик 3, Story 3.10 | ✓ Покрыто | +| FR-17 | Эпик 3, Story 3.11 | ✓ Покрыто | +| FR-18 | Эпик 3, Story 3.12 | ✓ Покрыто | +| FR-19 | Эпик 3, Story 3.13 | ✓ Покрыто | +| FR-20 | Эпик 3, Story 3.14 | ✓ Покрыто | +| FR-21 | Эпик 4, Story 4.1; Эпик 4, Story 4.6 | ✓ Покрыто | +| FR-22 | Эпик 4, Story 4.2; Эпик 4, Story 4.3; Эпик 4, Story 4.6 | ✓ Покрыто | +| FR-23 | Эпик 4, Story 4.2; Эпик 4, Story 4.3; Эпик 4, Story 4.8 | ✓ Покрыто | +| FR-24 | Эпик 4, Story 4.1; Эпик 4, Story 4.8 | ✓ Покрыто | +| FR-25 | Эпик 4, Story 4.4; Эпик 4, Story 4.5; Эпик 4, Story 4.6 | ✓ Покрыто | +| FR-26 | Эпик 4, Story 4.7 | ✓ Покрыто | +| FR-27 | Эпик 1, Story 1.5; Эпик 5, Story 5.1 | ✓ Покрыто | +| FR-28 | Эпик 5, Story 5.2 | ✓ Покрыто | +| FR-29 | Эпик 5, Story 5.4; Эпик 5, Story 5.6 | ✓ Покрыто | +| FR-30 | Эпик 5, Story 5.3 | ✓ Покрыто | +| FR-31 | Эпик 5, Story 5.5; Эпик 5, Story 5.6 | ✓ Покрыто | +| FR-32 | Эпик 1, Story 1.6; Эпик 5, Story 5.7 | ✓ Покрыто | +| FR-33 | Эпик 1, Story 1.16; Эпик 2, Story 2.9; Эпик 5, Story 5.8 | ✓ Покрыто | +| FR-34 | Эпик 5, Story 5.9; Эпик 5, Story 5.10 | ✓ Покрыто | +| FR-35 | Эпик 5, Story 5.11 | ✓ Покрыто | +| FR-36 | Эпик 6, Story 6.1 | ✓ Покрыто | +| FR-37 | Эпик 6, Story 6.2 | ✓ Покрыто | +| FR-38 | Эпик 6, Story 6.3; Эпик 6, Story 6.4 | ✓ Покрыто | +| FR-39 | Эпик 6, Story 6.5 | ✓ Покрыто | +| FR-40 | Эпик 6, Story 6.6 | ✓ Покрыто | +| FR-41 | Эпик 7, Story 7.3; Эпик 7, Story 7.4 | ✓ Покрыто | +| FR-42 | Эпик 7, Story 7.5 | ✓ Покрыто | +| FR-43 | Эпик 1, Story 1.4; Эпик 7, Story 7.2; Эпик 7, Story 7.7; Эпик 7, Story 7.8; Эпик 7, Story 7.9 | ✓ Покрыто | +| FR-44 | Эпик 7, Story 7.6 | ✓ Покрыто | +| FR-45 | Эпик 1, Story 1.3; Эпик 7, Story 7.1 | ✓ Покрыто | +| FR-46 | Эпик 1, Story 1.1; Эпик 1, Story 1.2; Эпик 8, Story 8.2 | ✓ Покрыто | +| FR-47 | Эпик 8, Story 8.3 | ✓ Покрыто | +| FR-48 | Эпик 8, Story 8.4 | ✓ Покрыто | +| FR-49 | Эпик 8, Story 8.5; Эпик 8, Story 8.6; Эпик 8, Story 8.9 | ✓ Покрыто | +| FR-50 | Эпик 8, Story 8.7 | ✓ Покрыто | +| FR-51 | Эпик 8, Story 8.8 | ✓ Покрыто | +| FR-52 | Эпик 8, Story 8.1 | ✓ Покрыто | +| FR-53 | Эпик 8, Story 8.9 | ✓ Покрыто | +| FR-54 | Эпик 8, Story 8.10 | ✓ Покрыто | + +### Непокрытые требования + +- Непокрытые FR из PRD: **нет**. +- Ссылки на FR в эпиках, отсутствующие в PRD: **нет**. + +### Статистика покрытия + +- Всего FR в PRD: **54**. +- FR, покрытых хотя бы одной Story: **54**. +- Покрытие: **100% по заявленной Story mapping**. +- Проверено отдельных Story requirement declarations: **83**. + +Этот результат подтверждает распределение требований, но не качество реализации или достаточность acceptance criteria; они оцениваются на следующих этапах readiness. + +## Оценка согласованности UX + +### Статус UX-документа + +**Отдельного UX Design нет.** Это намеренное решение Fast Path: решение A-2 в PRD фиксирует, что пять user journeys восстановлены из текущего продукта и целевой аудитории без отдельного UX-исследования. + +UX при этом явно необходим. Продукт содержит Admin UI и требует OpenAPI upload/preview/apply, экраны lifecycle capabilities, управление и reconciliation Tasks, поиск trace/history, ссылки Grafana, workflows Load Scenario/Run, deployment diagnostics, RU/EN localization и UI responsiveness ≤2 s p95. + +### Согласованность PRD ↔ Architecture + +- User journeys UJ-1—UJ-5 поддержаны архитектурными областями OpenAPI, Resources/Prompts, correlation/GlitchTip, isolated Load Runs и durable Tasks. +- AD-19 сохраняет текущую модель Alpine.js и `window.Crank*`, требует identity/revision guards, локализованные safe boundary errors и trace support identifiers. +- NFR-P5 сохранён как UI performance budget; browser state остаётся за Admin API boundaries без параллельной frontend data model. +- Эпики задают общий UI contract: loading/empty/error/confirmation/stale-response states, RU/EN, safe DOM sinks, Playwright evidence и WCAG 2.2 AA для критических flows. +- Не найдено UI-требований, требующих неподдерживаемого framework, service topology или data boundary. + +### Проблемы согласованности + +1. Нет отдельной information architecture, navigation map, component inventory или visual specification. Межэкранная согласованность зависит от общего UI contract эпиков и acceptance criteria Story. +2. Нет валидированного user-research evidence для восстановленных journeys. Это не блокирует foundational repository/backend stories, но usability claims вроде первого успеха за 15 минут требуют последующего fresh-user evidence. +3. Точный layout панелей Grafana, визуализация Load Run и сложный Task reconciliation interaction намеренно отложены до feature/story design в рамках зафиксированных architecture и safety contracts. + +### Предупреждения и решение gate + +**Предупреждение, но не блокер Phase 4 для Story 1.1 и других non-UI foundations.** До первой UI-heavy vertical Story нужно создать отдельную UX specification либо явно проверить UX contract самой Story. UI Story не может опираться только на пять journey из PRD: она должна сохранять общий contract accessibility, states, localization, correlation и Playwright из `epics.md`. + +## Проверка качества эпиков + +### Объём проверки и структурные evidence + +- Проверено **8 эпиков и 83 Story**. +- Каждая Story содержит роль пользователя/владельца, desired outcome, value statement, ссылку на FR и сбалансированные Given/When/Then acceptance groups. +- Все **54 FR** имеют хотя бы одну Story mapping. +- Документ задаёт явный wave/dependency order и запрещает начинать Story до её prerequisites. +- Не найдено явных ссылок из Story на более позднюю Story как prerequisite реализации. +- Проект brownfield; Architecture прямо фиксирует, что starter template не требуется. +- Migration authority создаётся заранее, а feature tables/migrations остаются во владении первой Story, которой они нужны; предварительной Story «создать все модели/таблицы» нет. + +### Соответствие на уровне эпиков + +| Эпик | Пользовательская/операторская ценность | Направление зависимостей | Результат | +|---|---|---|---| +| 1 — Надёжный REST → MCP | Безопасно завершает существующий core flow | Foundation; нет зависимости от будущего эпика | Пройдено | +| 2 — Tools из OpenAPI | Импортирует реальные спецификации без silent loss | Использует hardened contracts Эпика 1 | Пройдено | +| 3 — Современный MCP-каталог | Публикует и использует Tools/Resources/Prompts | Использует stable core contracts; нет поздней зависимости | Пройдено | +| 4 — Параллельные/фоновые выполнения | Durable и управляемые Tasks | Использует предыдущий capability/runtime foundation | Пройдено | +| 5 — Эксплуатационная видимость | Трассирует запросы и управляет по metrics/SLO | Использует correlation/metrics foundations из Эпика 1 | Пройдено | +| 6 — Встроенная проверка производительности | Безопасно запускает и анализирует нагрузочные тесты | Использует опубликованные capabilities и observability | Пройдено | +| 7 — Production-развёртывание/восстановление | Устанавливает, обновляет, резервирует и восстанавливает | Квалифицирует предыдущие product surfaces | Пройдено, отмечена связь с bundle rebuild | +| 8 — Доказанный релиз | Квалифицирует один immutable RC и открывает Habr gate | Намеренно использует завершённые предыдущие эпики | Пройдено | + +### 🔴 Критические нарушения + +**Не найдены.** Нет technical-only эпика без operator/release outcome, circular/forward dependency, заставляющей ранний эпик зависеть от позднего, или пропущенного FR allocation. + +### 🟠 Существенные проблемы + +1. **Неверная ссылка на зависимость в Story 2.4 — ИСПРАВЛЕНО 2026-08-08.** Acceptance criterion для REST target ранее ссылался на `OutboundPolicy из Story 1.5`; ссылка исправлена на Story 1.9, которая действительно владеет OutboundPolicy. Finding закрыт, повторная проверка ссылки обязательна при валидации Story 2.4. + +2. **Двадцать Story содержат 10–15 acceptance groups.** Самые рискованные примеры: 2.7 (15), 2.4/2.6 (14), 1.13/2.3/2.8 (13), а также security/lifecycle Story Эпика 1. Документ содержит убедительное обоснование atomic boundary, поэтому это не автоматическая ошибка декомпозиции. Однако перед разработкой каждая такая Story должна получить отдельный файл с границами задач, явным порядком реализации и одним проверяемым vertical outcome. Если Story нельзя выполнить одним сфокусированным изменением без смешивания несвязанных migrations/UI/runtime/deployment работ, её нужно разделить с сохранением transaction/artifact invariant. + +3. **Покрытие NFR управляется глобально, но не отображено на уровне Story.** Architecture и правила декомпозиции требуют закрывать применимые performance, security, reliability, observability, localization и evidence внутри каждой Story, однако для 30 NFR нет story-level traceability matrix. До включения в sprint отдельный файл Story должен перечислить применимые NFR ID и команды/evidence проверки; release-only Эпик 8 нельзя использовать для их откладывания. + +### 🟡 Незначительные замечания + +1. Story 7.6 намеренно инвалидирует и пересобирает offline bundle из Story 7.5, когда hardening image меняет digest. AC обрабатывает это корректно, но sprint planning должен заложить повторную air-gapped проверку, а не считать результат 7.5 окончательным навсегда. +2. Несколько enabling Story (1.3–1.6) являются техническим foundation. Они допустимы, потому что каждая содержит явный operator/support outcome, brownfield integration constraints и немедленно используемые contracts; completion evidence должен доказывать outcome, а не только создание crate/file. +3. Документ эпиков очень велик. Для контекста implementation agent обязательны отдельные файлы Story; реализовывать непосредственно из агрегата на 4 433 строки нельзя. + +### Исправления перед разработкой + +- [x] Исправить prerequisite Story 2.4 с Story 1.5 на Story 1.9 до включения в sprint — выполнено 2026-08-08. +- Запускать `bmad-create-story:create` и `bmad-create-story:validate` для каждой Story, выбранной sprint planning. +- Добавлять применимые NFR ID, test levels и expectations к evidence в каждый отдельный файл Story. +- Делить любую из 20 крупных Story только если подробный task plan не помещается в одну согласованную vertical/transactional boundary. +- Сохранять объявленные delivery waves; не использовать qualification позднего эпика как замену story-local quality. + +## Итог и рекомендации + +### Общий статус готовности + +**ТРЕБУЕТ ДОРАБОТКИ** + +План продукта в основном полон и внутренне согласован: авторитетный PRD содержит 54 FR и 30 NFR, Architecture связывает весь scope, все 54 FR отображены на одну или несколько из 83 Story, критических forward/circular dependencies не найдено. Однако реализацию Phase 4 нельзя начинать прямо из агрегированного документа эпиков. Для implementation handoff ещё нужны sprint planning, отдельные валидированные файлы Story и явное story-level распределение NFR. + +Этот статус **не требует** переделывать PRD, Architecture или декомпозицию эпиков. Нужны короткое исправление и контролируемый переход в story cycle. + +### Критические вопросы, требующие немедленных действий + +Критических проблем product scope или Architecture не найдено. + +Обязательны следующие **существенные действия до реализации**: + +1. [x] Исправить ссылку в Story 2.4 с `OutboundPolicy из Story 1.5` на Story 1.9 — выполнено 2026-08-08. +2. Создать sprint plan/status, превращающий утверждённые dependency waves в исполняемый порядок. +3. Создать и валидировать отдельный implementation-файл Story 1.1 вместо разработки из `epics.md`; включить в него существующие ATDD-артефакты. +4. Добавить применимые NFR ID и команды evidence в Story 1.1 и повторять это для каждой последующей Story до начала её разработки. + +### Рекомендуемые следующие шаги + +1. [x] Внести единственное planning-исправление Story 2.4; production-код не затрагивается — выполнено 2026-08-08. +2. Запустить `[SP] bmad-sprint-planning` и создать упорядоченный implementation plan. +3. Запустить `[CS] bmad-create-story:create` для Story 1.1 и включить существующие пути ATDD checklist/test. +4. Запустить `[VS] bmad-create-story:validate` для Story 1.1; проверить scope, NFR mapping, task sizing и test commands. +5. Начинать `[DS] bmad-dev-story` только после успешной валидации, активируя подготовленные RED-тесты по одному сценарию. +6. До первой UI-heavy Story выполнить сфокусированную UX specification/review для IA, навигации, interaction states и уже обязательного WCAG 2.2 AA contract. +7. При создании Story повторно оценивать 20 крупных Story; делить только там, где одно reviewable vertical change не сохраняет заявленный transaction/artifact invariant. + +### Итоговое замечание + +Оценка выявила **7 findings в четырёх областях**: одно предупреждение UX handoff, три существенные проблемы готовности эпиков/Story и три незначительных planning-замечания. **Один существенный finding уже закрыт; открыты 6 findings, включая 2 существенных.** Ни одно не отменяет утверждённое направление продукта. После выполнения оставшихся handoff-действий foundational Story 1.1 можно реализовывать, не ожидая полного отдельного UX-документа. + +**Дата оценки:** 2026-08-08 +**Оценку выполнил:** Codex, workflow BMad Implementation Readiness +**Основание evidence:** канонические PRD/addendum, Architecture Spine, `epics.md`, project context и созданные ATDD-артефакты. diff --git a/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/.memlog.md b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/.memlog.md new file mode 100644 index 0000000..e482ad3 --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/.memlog.md @@ -0,0 +1,98 @@ +--- +topic: Crank Community — Production Readiness +updated: 2026-08-03T15:42 +--- + +- (decision) Текущий продуктовый этап сфокусирован на доведении Crank Community до production-ready состояния. +- (decision) Надёжность, качество и скорость всех существующих функций являются приоритетами релиза. +- (decision) Нужна сквозная трассировка запросов по trace_id с доступностью контекста в интерфейсе и GlitchTip. +- (decision) Нужны технические и бизнес-метрики с интеграциями Prometheus и Grafana. +- (decision) Нужен встроенный упрощённый нагрузочный тест: параметры вроде RPS или DAU, запуск из интерфейса и просмотр статистики качества обработки запросов. +- (decision) Нужно определить и поддержать параллельное и фоновое выполнение tools, включая возможности FastMCP для фоновых tools. +- (decision) MCP-поверхность продукта должна быть расширена поддержкой resources и prompts. +- (assumption) Уровень ставок трактуется как production launch; это требуется подтвердить пользователю для калибровки глубины PRD. +- (decision) Порядок достижения production-ready: сначала закрыть функциональные недоработки, затем провести полное всестороннее тестирование, включая ручное. +- (decision) Существующий базовый сценарий создания простого REST-метода и подключения его к MCP-клиенту подтверждён пользователем как рабочий. +- (change) Импорт методов из openapi.yaml и другие менее проверенные сценарии считаются зонами вероятных сбоев и требуют функционального аудита. +- (decision) Целевая аудитория Community: небольшие организации и частные разработчики, которым нужно без разработки быстро создавать MCP tools, resources и prompts. +- (decision) Ключевая ценность Community: бесплатный self-hosted продукт, сохраняющий данные внутри закрытого контура пользователя. +- (decision) Семантика существующего функционала должна быть сохранена; текущий scope продукта считается строго очерченным. +- (event) Из сохранившихся исходных материалов доступен project-context.md; прежний продуктовый и архитектурный контекст был утрачен и восстанавливается. +- (decision) Уровень ставок подтверждён как публичная production Community-версия для реального использования внешними пользователями. +- (event) Исследование MCP выявило необходимость раздельно специфицировать конкурентные вызовы, durable background tasks и внутреннюю очередь; современный Tasks extension несовместим со старым wire-контрактом, а FastMCP 4 пока beta. +- (event) Исследование observability выявило ключевые развилки: 100% traces против sampling, trace_id нельзя использовать как Prometheus label, DAU-нагрузка требует модели сессий, а генератор нагрузки нуждается в изоляции и защитных лимитах. +- (decision) Выбран Fast path: оставшиеся пробелы собираются в один-два консолидированных вопроса, после чего полный PRD создаётся с явными [ASSUMPTION]. +- (event) Инвентаризация репозитория подтвердила зрелый happy path REST operation → publish → agent catalog → MCP tools/call, а также строгие Community-контракты: self-hosted, один workspace/администратор, только опубликованные версии, one-time secret/key disclosure. +- (event) Инвентаризация выявила отсутствующие product capabilities: MCP resources, prompts, Tasks/background execution и встроенный load runner; OpenAPI importer имеет узкие форматы и недостаточный corpus реальных спецификаций. +- (event) Observability-фундамент уже включает request_id, W3C trace propagation, OTLP spans, защищённые Prometheus endpoints, redaction и технические метрики, но trace_id не хранится в invocation history/UI, GlitchTip не получает request traces, готовые dashboards/SLO/alerts отсутствуют. +- (event) Тестовая база и CI широкие, но нет свежего полного authenticated manual pass, performance/load/soak/chaos gates, MCP client/version matrix и формализованных SLO release gates; документация местами расходится с runtime/API/UI. +- (decision) Все перечисленные пользователем возможности обязательны для целевого production-релиза; публикация на Хабре разрешена только после прохождения release gate. +- (override) Пользователь делегировал автору PRD определение масштаба, SLO, бизнес-метрик, quality gates и остальных незаданных продуктовых решений для ускорения Fast path. +- (decision) Production-версия должна демонстрировать высокую скорость и безопасность, соответствующие ожиданиям от Rust-продукта. +- (decision) Целевой MCP-контракт должен поддерживать все современные стабильные server-side возможности, применимые к роли Crank, а не только tools. +- (assumption) Форм-фактор production-релиза сохраняется как self-hosted web UI + Admin API + MCP server + Docker Compose для закрытого контура. +- (assumption) A-1: Публичный анонс зависит от Release Gate, а не календарной даты; так как пользователь различает только момент публикации. +- (assumption) A-2: Пользовательские пути восстановлены из репозитория и brain dump без отдельного UX-исследования. +- (assumption) A-3: XML payloads не реализуются в production scope, но должны диагностироваться явно. +- (assumption) A-4: MCP compatibility охватывает latest stable на feature freeze и две предыдущие поддерживаемые версии; experimental отдельно. +- (assumption) A-5: Динамический REST-backed Resource входит в public-launch scope для практической ценности Resources. +- (assumption) A-6: Background Tasks имеют at-least-once delivery и effectively-once только при idempotency; exactly-once не обещается. +- (assumption) A-7: Default production profile сохраняет 100% traces 7 дней и errors не менее 30 дней с конфигурируемыми sampling/retention. +- (assumption) A-8: DAU определяется как уникальный Agent с хотя бы одним валидным MCP request за UTC-день; UI activity считается отдельно. +- (assumption) A-9: Load Run target ограничен опубликованными capabilities текущей установки ради безопасности. +- (assumption) A-10: Prometheus, Grafana и GlitchTip поставляются optional production profile и могут заменяться внешними endpoints. +- (assumption) A-11: Supported UI matrix включает Chromium/Firefox/WebKit, MCP matrix — минимум три representative clients плюс protocol harness. +- (assumption) A-12: Reference Deployment: Linux x86_64, 4 vCPU, 8 GiB RAM, SSD, PostgreSQL 16, Valkey 8 и отдельный load generator. +- (decision) Пользователь подтвердил A-1—A-12 без изменений; все допущения становятся принятыми решениями, phase-blocking open items отсутствуют. +- (change) Input reconciliation добавила versioned inventory всех существующих UI/API/MCP flows с обязательным regression evidence, чтобы ни одна текущая функция не выпала из Release Gate. +- (change) OpenAPI требования дополнены конкретным `.yaml/.yml/.json` file-upload E2E контрактом и malformed/empty/oversized/no-method fixtures из-за названного пользователем сбойного пути. +- (change) MCP gate дополнен полным inventory официальной stable specification со статусом каждой capability/extension, чтобы исключить субъективный пропуск современных возможностей. +- (decision) Весь обязательный Community production scope должен работать бесплатно, без premium gate или обязательного коммерческого backend; лицензии bundled-компонентов входят в gate. +- (decision) Resources, Prompts, Tasks и Load Runs являются намеренным расширением Community scope и требуют одновременного обновления docs, project-context и executable scope checks, а не allow-marker обхода. +- (decision) Disaster recovery production profile использует WAL/PITR с RPO не более 5 минут и RTO не более 30 минут; RPO=0 сохраняется только для restart с исправным durable storage. +- (change) Migration contract уточнён: immutable checksummed migrations, транзакции, advisory lock и expand/migrate/contract tests. +- (change) Safety stores получили fail-closed contract; недоступность coordination/cache/approval/idempotency dependency отражается в readiness и не отключает защиту молча. +- (change) Master-key identity, rotation/re-encryption и восстановление зашифрованного Auth Profile включены в production recovery gate. +- (change) Correlation и diagnostic artifacts уточнены: invalid request ID заменяется UUIDv7, Request ID отделён от Trace ID, truncation сохраняет валидный UTF-8/JSON. +- (change) Reviewer gate исправил циклический Release Gate: FR-54 выводится из evidence по FR-1—FR-53 и SM-2—SM-10. +- (decision) Reference Workload v1 формализован с фиксированными mix, dataset, payload, upstream, cache и telemetry parameters; Evidence Manifest становится исполняемым индексом gate. +- (decision) Публичный запуск требует 30-дневный supervised burn-in с минимум 1 000 000 eligible events; 72-hour soak остаётся pre-release qualification. +- (decision) Durable Tasks используют атомарный record+dispatch intent, CAS lease с fencing token и атомарный terminal transition; crash/partition matrix обязательна. +- (decision) Load Run разрешает только load-test-safe capabilities; destructive paths требуют sandbox/test credentials/quota/cleanup, emergency stop независим от основного worker pool. +- (decision) Trace contract разделён: локальная корреляция 100%, delivery SLI в GlitchTip не менее 99,99%, а недоставка фиксируется Telemetry Loss Record и bounded spool. +- (decision) Community upgrade contract выбран как single-instance drain/restart с N/N-1 schema/Task compatibility; rolling deployment не заявляется. +- (decision) Offline distribution оформляется подписанным digest-pinned bundle с SBOM/licenses и network-denied install/upgrade test. +- (decision) PostgreSQL является source of truth для durable/safety state; Valkey-assisted режим rebuildable, PostgreSQL-only сохраняет корректность с меньшим throughput. +- (change) Security gate унифицирован: реальные Critical/High findings и vulnerabilities запрещены; false positive требует evidence, scanner set фиксируется в RC manifest. +- (change) Availability SLI стал time-based: synthetic probe каждые 10 секунд, минута без evidence считается bad, поэтому отсутствие трафика не маскирует downtime. +- (change) 250 RPS burst получил отдельный per-minute gate на success ratio, latency и saturation rejection, не скрываемый 30-дневным усреднением. +- (change) OpenAPI zero-silent-loss теперь измеряется относительно нормативной versioned support matrix для OAS 3.0/3.1 и Swagger 2.0. +- (decision) Trace contract требует 100% eventual delivery в GlitchTip за 24 часа; latency SLI не менее 99,99%, любой Telemetry Loss Record является SLO breach. +- (change) Task deadline SLI не считает input-required успехом; ожидание input имеет bounded TTL и отдельную transition latency. +- (decision) Production web baseline включает TLS, trusted-proxy allowlist, secure session cookies, CSRF, deny-by-default CORS, session lifecycle и security headers. +- (decision) Background write без upstream idempotency при lease loss/cancel становится outcome_unknown и не повторяется автоматически; fencing защищает только состояние Crank. +- (change) DR evidence связывает WAL LSN, snapshot, artifacts/config checksums и opaque key-backup reference; RPO/RTO измеряются до реального MCP-вызова и проверяют re-encryption. +- (change) Reference Workload дополнен 128 active/10 000 queued Tasks, duration distribution и drain/checkpoint/restart recovery variant. +- (decision) Task state machine расширена non-terminal outcome_unknown с отдельным reconciliation flow; MCP adapter не отображает его как обычный retriable failure. +- (decision) Input-required Tasks принимают schema-validated idempotent update, имеют bounded TTL и не засчитываются как deadline success. +- (decision) Единственная admin credential создаётся one-time bootstrap, защищена rate-limit/backoff, а rotation/recovery отзывает sessions/CSRF и требует local operator access. +- (decision) OpenAPI gate требует обязательный baseline и минимум 95% actionable Operations в representative corpus; unsupported majority не может пройти gate. +- (change) Pre-launch burn-in не исключает maintenance; post-launch exclusions ограничены 30 минутами за 30 дней. +- (change) Steady 100 RPS получил per-minute success/latency/queue/saturation thresholds; backlog 10k Tasks обязан дренироваться не более 60 минут. +- (decision) Telemetry spool capacity обязана покрывать 24 часа при 100 RPS, burst 250 RPS/5 минут и 20% headroom; более долгий outage является SLO incident. +- (change) Evidence Manifest получил versioned JSON Schema и CI verification подписей, digests, freshness и immutable result references. +- (decision) External OpenAPI refs фиксируются immutable content-addressed snapshot между preview и commit, устраняя TOCTOU. +- (decision) OpenAPI mandatory baseline включает common methods/parameters/bodies/2xx/references/composition/security и требует минимум 95% actionable Operations corpus. +- (decision) Static Resources и composed Prompts наследуют sensitivity/access policies, проходят secret scan и не могут обходить Agent authorization или раскрывать credentials. +- (decision) Built-in Load Run имеет неотключаемые ceilings 1000 RPS/512 VU/2h/10M iterations, heartbeat dead-man stop, reserved control capacity и local kill switch. +- (decision) Trace spool capacity увеличена до 30 часов при guaranteed outage envelope 24 часа; eventual delivery deadline 25 часов согласован с replay. +- (change) 30-дневный burn-in требует 1M events в Reference Workload capability mix ±2 п.п.; probes исключены из объёма. +- (event) Reviewer Gate завершён: rubric GO, operability GO, adversarial passed; Critical/High findings равны нулю. +- (decision) 28 edge cases, 10 Medium, 3 Low и 15 adversarial improvements отложены владельцам Architecture/QA; до Baseline Frozen каждый finding требует отдельного disposition, массовое принятие запрещено. +- (decision) Latest stable MCP определяют Product+Architecture перед Capability Inventory; применимые stable gaps блокируют Baseline Frozen. +- (decision) Representative MCP clients определяют Product+QA до feature freeze и перепроверяют на RC. +- (decision) Reference Deployment targets пересматривают Performance QA+Architecture после первого полного workload run; изменение требует memlog decision до Baseline Frozen. +- (decision) Retention budget определяют SRE+Architecture после измерения telemetry/history sizes; решение блокирует production profile capacity evidence. +- (change) Структурная полировка сохранила стабильные FR/SM/NFR ссылки, разделила deferred decisions/reviewer dispositions и перестроила addendum в статусный MECE-справочник. +- (change) Prose polish устранил неоднозначные субъекты, slash-конструкции и неканонические термины без изменения scope, thresholds или gates. +- (event) PRD finalized diff --git a/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md new file mode 100644 index 0000000..e80394a --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md @@ -0,0 +1,97 @@ +# Addendum: технические направления + +Addendum сохраняет предложенные механизмы и интеграции, не превращая их автоматически в утверждённую архитектуру. Нормативные product outcomes находятся в `prd.md`. + +## Статусы положений + +- **User requirement** — механизм или интеграция названы пользователем и обязательны на уровне product outcome. +- **Confirmed decision** — решение принято и подтверждено в PRD. +- **Architecture direction** — рекомендуемый способ реализации; Architecture может заменить его при сохранении PRD outcomes и evidence. +- **Evidence contract** — обязательное доказательство, а не выбор реализации. + +## Reference Deployment + +- **Confirmed decision:** Reference Deployment запускает Crank services, PostgreSQL 16 и Valkey 8 на Linux x86_64 и выделяет всему deployment 4 vCPU, 8 GiB RAM, SSD ≥100 GB/3 000 IOPS/100 MB/s и сеть 1 Gbit/s. +- **Confirmed decision:** load generator размещается отдельно, чтобы CPU/RAM генератора не искажали измерение Crank. +- **Confirmed decision:** production observability stack получает отдельный resource budget и поставляется optional Compose profile; допускаются внешние Prometheus, Grafana и GlitchTip endpoints. + +## Наблюдаемость + +- **User requirement:** запросы коррелируются по `trace_id` между продуктовым интерфейсом и GlitchTip; технические и бизнес-метрики экспортируются в Prometheus и визуализируются в Grafana. +- **Architecture direction:** контекст W3C Trace Context распространяется через browser, server и background boundaries; `request_id` и `trace_id` сохраняются в PostgreSQL вместе с Invocation; GlitchTip получает Sentry-compatible performance telemetry, а Prometheus — metrics. +- **Architecture direction:** переход от метрики в Grafana к trace выполняется через exemplar или внешний URL, а не через Prometheus label с `trace_id`. +- **Confirmed decision:** production profile генерирует 100% traces, требует delivery latency SLI ≥99,99% и eventual completeness 100% за 25 часов при outage ≤24 часов; traces хранятся 7 дней, errors — не менее 30 дней. +- **Confirmed decision:** GlitchTip является default trace/error backend; совместимый внешний trace/error backend не заменяет обязательный tested GlitchTip path перед публичным запуском. +- **Architecture direction:** fail-open telemetry использует disk-backed bounded spool. Для недоставленного trace локально сохраняется Telemetry Loss Record; UI не утверждает, что этот trace присутствует в GlitchTip. +- **Evidence contract:** spool вмещает 30 часов telemetry при Reference Workload 100 RPS и один 5-минутный burst при 250 RPS; гарантированный outage envelope составляет 24 часа с replay/headroom. +- **Architecture direction:** inbound `traceparent` валидируется, а `tracestate` и `baggage` ограничиваются allowlist и size budget. + +## MCP capability surface + +- **User requirement:** Crank добавляет MCP Resources и Prompts наряду с существующими Tools и поддерживает современные стабильные MCP-возможности. +- **Confirmed decision:** на feature freeze поддерживаются latest stable MCP и две предшествующие stable MCP versions; ни один experimental MCP extension не становится единственным путём вызова Tool, объявленного критичным. +- **Confirmed decision:** Resource lifecycle использует versioned draft/publish/archive модель. Типы: static text/JSON/binary и REST-backed URI templates. +- **Confirmed decision:** Prompt lifecycle использует versioned draft/publish/archive модель и поддерживает parameterized messages и ссылки на Published Resource Versions. + +## Фоновые выполнения и Task semantics + +- **User requirement:** продукт поддерживает параллельные и фоновые Tool executions. +- **Confirmed decision:** параллельные requests, durable MCP Tasks и внутренняя очередь — разные контракты. +- **Architecture direction:** внутренняя durable Task сущность Crank независима от MCP Tasks extension; protocol extension является адаптером. +- **Architecture direction:** PostgreSQL остаётся source of truth, а Valkey обеспечивает rebuildable coordination и throughput. +- **Architecture direction:** Task record и dispatch intent фиксируются в одной PostgreSQL-транзакции; worker получает Task через compare-and-swap lease с монотонным fencing token. +- **Confirmed decision:** гарантия выполнения Task — at-least-once; effectively-once достигается через idempotency fingerprint/deduplication. Exactly-once для внешнего side effect не заявляется. +- **Confirmed decision:** fencing защищает только состояние Crank. После lease loss/cancel Task с Background write без upstream idempotency переходит в `outcome_unknown`; Background write не повторяется автоматически. +- **Confirmed decision:** `outcome_unknown` — внутреннее non-terminal состояние; MCP adapter не отображает `outcome_unknown` как обычный retriable failure, а UI требует reconciliation evidence. +- **Confirmed decision:** Task в состоянии `input_required` возобновляется после schema-validated Task update; состояние имеет bounded TTL и допускает идемпотентный identical replay. + +## Встроенное нагрузочное тестирование + +- **User requirement:** пользователь запускает тест из UI, задаёт RPS или DAU и видит статистику качества обработки запросов. +- **Architecture direction:** reference runner — изолированный k6-compatible worker/sidecar с arrival-rate/VU profiles, thresholds, live status и immutable report; конкретный engine подтверждается архитектурой и benchmark. +- **Confirmed decision:** входной параметр DAU преобразуется в load profile только после задания actions/session, sessions/user/day, activity window, think time и scenario mix. +- **Confirmed decision:** target ограничен опубликованными capabilities текущей установки; production target требует operator flag и повторное подтверждение. +- **Confirmed decision:** capability требует `load-test-safe` contract. Write/destructive path требует sandbox endpoint, test credentials, quota, cleanup и независимый emergency stop. +- **Confirmed decision:** built-in Load Run имеет неотключаемые ceilings 1 000 RPS, 512 VU, 2 часа и 10 000 000 iterations, heartbeat dead-man stop, reserved control capacity и local kill switch. + +## Upgrade и rollback + +- **Confirmed decision:** Community использует single-instance drain/restart upgrade, а не заявляет rolling deployment. +- **Evidence contract:** release N читает schema и Task envelope, созданные releases N и N-1, до конца rollback window; queued и active Tasks проходят checkpoint, restart и recovery без terminal commit от stale worker. + +## Backup и restore + +- **Confirmed decision:** production backup set включает PostgreSQL WAL/PITR, artifacts/config и отдельно защищённое master-key material. +- **Evidence contract:** backup manifest связывает snapshot timestamp, WAL LSN, checksums/config digest и opaque key-backup reference. +- **Evidence contract:** RPO/RTO фиксируются в момент успешного реального MCP-вызова с зашифрованным Auth Profile; rotation gate доказывает re-encryption и отзыв старого key. + +## Offline-поставка + +- **Confirmed decision:** offline bundle содержит подписанные digest-pinned images, Compose/config, SBOM, licenses и документацию. +- **Evidence contract:** fresh install и upgrade проверяются при полностью запрещённой внешней сети. + +## Web и admin security + +- **Confirmed decision:** non-loopback production exposure требует TLS, trusted-proxy allowlist, secure HttpOnly/SameSite cookies, CSRF, deny-by-default CORS, session rotation/expiry и security headers. +- **Confirmed decision:** единственная admin credential создаётся one-time bootstrap-процессом; rate-limit/backoff защищает login. Операции rotation/recovery требуют локального operator access и отзывают все sessions. + +## Общий evidence contract + +- **Evidence contract:** Reference Workload является versioned artifact с checksum и фиксирует mix, dataset, payloads, upstream latency/outcomes, cache и telemetry mode. +- **Evidence contract:** background variant фиксирует duration distribution, 128 active/10 000 queued Tasks, checkpoint/restart и drain/recovery ≤60 секунд. +- **Evidence contract:** подпись Evidence Manifest охватывает digests, workload/config, команды, результаты и идентификатор владельца gate; статус FR-54 определяется по evidence выполнения FR-1—FR-53 и SM-2—SM-10. + +## Источники технической проверки + +| Источник | Применение | +|---|---| +| [W3C Trace Context](https://www.w3.org/TR/trace-context/) | Распространение `traceparent`, `tracestate`, `baggage` | +| [OpenTelemetry log correlation](https://opentelemetry.io/docs/specs/otel/logs/) | Связь logs и traces | +| [GlitchTip Performance](https://glitchtip.com/documentation/performance/) | Performance transactions | +| [GlitchTip Logs](https://glitchtip.com/documentation/logs/) | Trace-correlated logs | +| [Prometheus instrumentation practices](https://prometheus.io/docs/practices/instrumentation/) | Technical/business metric design | +| [Grafana Prometheus exemplars](https://grafana.com/docs/grafana/latest/datasources/prometheus/configure/) | Metric-to-trace navigation | +| [MCP Tasks extension](https://modelcontextprotocol.io/extensions/tasks/overview) | Durable protocol Tasks | +| [MCP Resources](https://modelcontextprotocol.io/specification/draft/server/resources) | Resource contracts | +| [MCP Prompts](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts) | Prompt contracts | +| [k6 scenarios](https://grafana.com/docs/k6/latest/using-k6/scenarios/) | RPS/VU/load profiles | diff --git a/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/polish-prose-addendum.md b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/polish-prose-addendum.md new file mode 100644 index 0000000..7c22d90 --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/polish-prose-addendum.md @@ -0,0 +1,18 @@ +| Original Text | Revised Text | Changes | +|---------------|--------------|---------| +| **Confirmed decision:** Crank services, PostgreSQL 16 и Valkey 8 используют Linux x86_64, 4 vCPU, 8 GiB RAM, SSD ≥100 GB/3 000 IOPS/100 MB/s и сеть 1 Gbit/s. | Consider: **Confirmed decision:** Reference Deployment запускает Crank services, PostgreSQL 16 и Valkey 8 на Linux x86_64 и выделяет всему deployment 4 vCPU, 8 GiB RAM, SSD ≥100 GB/3 000 IOPS/100 MB/s и сеть 1 Gbit/s? | Уточняет, что характеристики относятся к deployment в целом, а не к каждому сервису; требуется подтверждение этой границы resource budget. | +| **Architecture direction:** W3C Trace Context проходит через browser/server/background boundaries; `request_id` и `trace_id` сохраняются в PostgreSQL вместе с Invocation; GlitchTip получает Sentry-compatible performance telemetry, Prometheus — metrics. | **Architecture direction:** Контекст W3C Trace Context распространяется через browser, server и background boundaries; `request_id` и `trace_id` сохраняются в PostgreSQL вместе с Invocation; GlitchTip получает Sentry-compatible performance telemetry, а Prometheus — metrics. | Заменён неверный субъект действия: через границы распространяется контекст, а не стандарт W3C Trace Context; добавлен союз между последними clauses. | +| **Architecture direction:** Grafana связывается с trace через exemplar или внешний URL, а не Prometheus label с `trace_id`. | **Architecture direction:** Переход от метрики в Grafana к trace выполняется через exemplar или внешний URL, а не через Prometheus label с `trace_id`. | Явно названы исходный объект и направление навигации; добавлен пропущенный предлог для параллельной конструкции. | +| **Confirmed decision:** GlitchTip является default trace/error backend; совместимый внешний backend не заменяет обязательный tested GlitchTip path перед публичным запуском. | **Confirmed decision:** GlitchTip является default trace/error backend; совместимый внешний trace/error backend не заменяет обязательный tested GlitchTip path перед публичным запуском. | Уточнён тип внешнего backend; LLM не должен выводить его назначение из первого clause. | +| **Architecture direction:** fail-open telemetry использует disk-backed bounded spool. Недоставленный trace сохраняет локальный Telemetry Loss Record, и UI не утверждает, что такой trace присутствует в GlitchTip. | **Architecture direction:** fail-open telemetry использует disk-backed bounded spool. Для недоставленного trace локально сохраняется Telemetry Loss Record; UI не утверждает, что этот trace присутствует в GlitchTip. | Исправлен субъект: trace не «сохраняет» record; заменена неоднозначная причинно-соединительная конструкция на два явных результата. | +| **Evidence contract:** spool вмещает 30 часов telemetry при 100 RPS Reference Workload плюс один 250 RPS/5-minute burst; гарантированный outage envelope — 24 часа с replay/headroom. | **Evidence contract:** spool вмещает 30 часов telemetry при Reference Workload 100 RPS и один 5-минутный burst при 250 RPS; гарантированный outage envelope составляет 24 часа с replay/headroom. | Устранена неоднозначная slash-конструкция `250 RPS/5-minute`; явно разделены интенсивность и длительность burst. | +| **Confirmed decision:** на feature freeze поддерживаются latest stable MCP и две предыдущие поддерживаемые версии; experimental extension не становится единственным путём вызова критичного Tool. | **Confirmed decision:** на feature freeze поддерживаются latest stable MCP и две предшествующие stable MCP versions; ни один experimental MCP extension не становится единственным путём вызова Tool, объявленного критичным. | Устранена тавтология «предыдущие поддерживаемые» и явно указано, к чему относятся versions и extension; уточнено, что critical — атрибут Tool. | +| **Confirmed decision:** Prompt lifecycle использует versioned draft/publish/archive модель и поддерживает parameterized messages и ссылки на Published Versions Resources. | **Confirmed decision:** Prompt lifecycle использует versioned draft/publish/archive модель и поддерживает parameterized messages и ссылки на Published Resource Versions. | Исправлен неоднозначный порядок терминов, который мог означать либо версии Resources, либо отдельную сущность `Versions Resources`. | +| **Architecture direction:** Task record и dispatch intent фиксируются одной PostgreSQL-транзакцией; worker claim использует compare-and-swap lease с монотонным fencing token. | **Architecture direction:** Task record и dispatch intent фиксируются в одной PostgreSQL-транзакции; worker получает Task через compare-and-swap lease с монотонным fencing token. | Добавлен нормативный предлог `в`; nominal phrase `worker claim` заменена явным действием worker над Task. | +| **Confirmed decision:** delivery — at-least-once; effectively-once достигается через idempotency fingerprint/deduplication. Exactly-once для внешнего side effect не заявляется. | **Confirmed decision:** гарантия выполнения Task — at-least-once; effectively-once достигается через idempotency fingerprint/deduplication. Exactly-once для внешнего side effect не заявляется. | Явно указано, к какому объекту относится delivery guarantee; это предотвращает перенос гарантии на telemetry или protocol messages. | +| **Confirmed decision:** fencing защищает только состояние Crank. Background write без upstream idempotency после lease loss/cancel становится `outcome_unknown` и не повторяется автоматически.

**Confirmed decision:** `outcome_unknown` — внутреннее non-terminal состояние; MCP adapter не выдаёт его как обычный retriable failure, а UI требует reconciliation evidence.

**Confirmed decision:** `input_required` возобновляется schema-validated Task update, имеет bounded TTL и идемпотентный identical replay. | **Confirmed decision:** fencing защищает только состояние Crank. После lease loss/cancel Task с Background write без upstream idempotency переходит в `outcome_unknown`; Background write не повторяется автоматически.

**Confirmed decision:** `outcome_unknown` — внутреннее non-terminal состояние; MCP adapter не отображает `outcome_unknown` как обычный retriable failure, а UI требует reconciliation evidence.

**Confirmed decision:** Task в состоянии `input_required` возобновляется после schema-validated Task update; состояние имеет bounded TTL и допускает идемпотентный identical replay. | Во всех трёх местах названы фактические субъекты перехода, отображения и возобновления; устранены неоднозначные местоимения и невозможный переход write-операции в состояние Task. | +| **Confirmed decision:** DAU преобразуется в нагрузку только через actions/session, sessions/user/day, activity window, think time и scenario mix. | **Confirmed decision:** входной параметр DAU преобразуется в load profile только после задания actions/session, sessions/user/day, activity window, think time и scenario mix. | Уточнены вход и результат преобразования; `через` заменено явным условием наличия параметров. | +| **Evidence contract:** N/N-1 schema и Task envelope читаются до конца rollback window; queued/active Tasks проходят checkpoint, restart и recovery без stale-worker terminal commit. | Consider: **Evidence contract:** release N читает schema и Task envelope, созданные releases N и N-1, до конца rollback window; queued и active Tasks проходят checkpoint, restart и recovery без terminal commit от stale worker? | Исходная формулировка не указывает читающий release и направление совместимости; предложенная трактовка требует подтверждения. Также раскрыта связь stale worker с запрещённым commit. | +| **Evidence contract:** RPO/RTO измеряются до реального MCP-вызова с зашифрованным Auth Profile; rotation gate доказывает re-encryption и отзыв старого key. | **Evidence contract:** RPO/RTO фиксируются в момент успешного реального MCP-вызова с зашифрованным Auth Profile; rotation gate доказывает re-encryption и отзыв старого key. | `Измеряются до` не определяет точку завершения восстановления; revised text задаёт наблюдаемое событие измерения без изменения gate. | +| **Confirmed decision:** единственная admin credential создаётся one-time bootstrap-процессом; rate-limit/backoff защищает login, а rotation/recovery отзывает sessions и требует локального operator access. | **Confirmed decision:** единственная admin credential создаётся one-time bootstrap-процессом; rate-limit/backoff защищает login. Операции rotation/recovery требуют локального operator access и отзывают все sessions. | Устранена грамматическая неоднозначность: явно указано, что оба требования относятся к операциям rotation/recovery, а не к rate-limit/backoff или login. | +| **Evidence contract:** Evidence Manifest подписывает digests, workload/config, команды, результаты и владельца gate; FR-54 выводится из evidence по FR-1—FR-53 и SM-2—SM-10. | **Evidence contract:** подпись Evidence Manifest охватывает digests, workload/config, команды, результаты и идентификатор владельца gate; статус FR-54 определяется по evidence выполнения FR-1—FR-53 и SM-2—SM-10. | Исправлен субъект криптографического действия; `владелец` заменён подписываемым идентификатором; явно назван определяемый атрибут FR-54. | diff --git a/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/polish-prose-prd.md b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/polish-prose-prd.md new file mode 100644 index 0000000..681d3b2 --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/polish-prose-prd.md @@ -0,0 +1,29 @@ +| Original Text | Revised Text | Changes | +|---------------|--------------|---------| +| Этот PRD определяет обязательный объём и измеримые критерии, после которых открытую Community-версию Crank можно публично представить как production-ready, в том числе опубликовать на Хабре. | Этот PRD определяет обязательный объём и измеримые критерии, при выполнении которых открытую Community-версию Crank можно публично представить как production-ready, в том числе опубликовать на Хабре. | Исправлена причинно-временная связь: релиз разрешает выполнение критериев, а не наступление момента «после критериев». | +| Любой запрос должен быть диагностируем по `request_id` и `trace_id`, а состояние системы — наблюдаемо через UI, GlitchTip, Prometheus и Grafana. | Любой запрос должен быть диагностируемым по `request_id` и `trace_id`, а состояние системы — наблюдаемым через UI, GlitchTip, Prometheus и Grafana. | Исправлено согласование составного именного сказуемого. | +| По одному идентификатору пройти от пользовательского действия до API, runtime, upstream и результата. | По одному Trace ID проследить путь от пользовательского действия через API, runtime и upstream до результата. | Устранена неоднозначность слова «идентификатор» и уточнена последовательность трассировки. | +| Если часть спецификации не поддержана, импорт не маскирует потерю данных и объясняет, что нужно исправить.

Ошибка сохраняет стадию отказа и не раскрывает credential или чувствительный payload.

Пользовательская ошибка отображает Request ID/Trace ID, пригодный для поддержки.

Image scan не содержит реальных Critical/High vulnerabilities. | Если часть спецификации не поддержана, отчёт импорта явно указывает потерю данных и объясняет, что нужно исправить.

Crank сохраняет стадию отказа и не раскрывает credential или чувствительный payload.

Сообщение об ошибке в UI отображает Request ID и Trace ID, пригодные для обращения в поддержку.

По результатам сканирования production images не содержат реальных Critical/High vulnerabilities. | Действия перенесены с неодушевлённых результатов и событий на компоненты, которые действительно их выполняют; устранены ложные субъекты. | +| **Resource** — versioned read-only MCP capability со статическим URI или URI template, возвращающее text, JSON или binary content. | **Resource** — versioned read-only MCP capability со статическим URI или URI template, который возвращает text, JSON или binary content. | Исправлено согласование определения с термином `Resource`; относительное предложение теперь однозначно относится к Resource. | +| **Draft** — изменяемая версия capability, недоступная через публичный Agent до публикации. | **Draft** — изменяемая версия capability, недоступная через опубликованный Agent до публикации. | Заменён не определённый термин «публичный Agent» на используемый в документе термин «опубликованный Agent». | +| его входной/выходной схемы

100% входящих UI/Admin API/MCP requests

UI показывает Request ID/Trace ID

environment fingerprint, release/version | его входная и выходная схемы

100% входящих запросов UI, Admin API и MCP

UI показывает Request ID и Trace ID

environment fingerprint, release ID и version | В нормативных перечислениях `/` заменён на явные союзы: slash неоднозначно означает «и», «или» либо составную категорию. Protocol method names (`tools/list`, `resources/read`) менять не следует. | +| `outcome_unknown` не terminal и блокирует retry/cancel-as-success до reconciliation; оно не учитывается как completed/failed SLI success. | Состояние `outcome_unknown` не является terminal state и блокирует retry/cancel-as-success до reconciliation; состояние `outcome_unknown` не учитывается как completed/failed SLI success. | Удалено неявное местоимение «оно» и явно назван объект обоих правил. | +| Rejection/queue wait/oldest task age наблюдаемы и возвращают retry guidance. | Rejection, queue wait и oldest task age наблюдаемы; ответ при rejection содержит retry guidance. | Разделены метрики и ответ: queue wait и task age не могут «возвращать» guidance. | +| При здоровом backend любой Trace ID появляется в GlitchTip не позднее 60 секунд; после контролируемого outage bounded spool доставляет его не позднее 5 минут после восстановления. | При здоровом backend trace с любым Trace ID появляется в GlitchTip не позднее 60 секунд; после контролируемого outage bounded spool доставляет соответствующий trace не позднее 5 минут после восстановления. | Уточнено, что доставляется trace, а не сам идентификатор; удалено неоднозначное «его». | +| Metrics listener вне loopback требует отдельную authentication и не использует admin/MCP credentials. | Metrics listener вне loopback требует отдельной authentication и не использует admin и MCP credentials. | Исправлено падежное управление и раскрыта slash-конструкция. | +| Scenario versioned; итоговый Run хранит точную версию параметров и capabilities. | Scenario версионируется; итоговый Run хранит точную версию параметров и capabilities. | Добавлено явное сказуемое вместо фрагмента без грамматической связи. | +| UI преобразует DAU в arrival profile только вместе с actions/session, sessions/user/day, activity window, think time и scenario mix. | UI преобразует DAU в arrival profile только при заданных actions per session, sessions per user per day, activity window, think time и scenario mix. | Уточнено, что перечисленные значения являются обязательными входными параметрами; slash-обозначения раскрыты. | +| Финальный artifact имеет тот же digest, что прошедший gate. | Финальный artifact имеет тот же digest, что и RC artifact, прошедший Release Gate. | Устранена неоднозначность: исходная формулировка не называла объект, который прошёл gate. | +| **Habr Launch:** разрешается FR-54; дата выбирается после достижения Public Ready. | **Habr Launch:** разрешается в соответствии с FR-54; дата выбирается после достижения Public Ready. | Уточнена связь: FR-54 задаёт условие разрешения, а не является субъектом, который «разрешается». | +| **NFR-P3:** рабочая установка поддерживает 2 000 Operations, 200 Agents, 500 active keys и 1 000 000 записей Invocation History без функциональной деградации. | **NFR-P3:** Reference Deployment поддерживает 2 000 Operations, 200 Agents, 500 active keys и 1 000 000 записей Invocation History без функциональной деградации. | Заменено неопределённое «рабочая установка» на определённый измерительный контекст. | +| **NFR-R1:** product-caused successful-request ratio ≥99,95% на supported workload; availability control plane ≥99,9% за 30-дневное окно, исключая документированное обслуживание. | **NFR-R1:** product-caused successful-request ratio ≥99,95% на Reference Workload; control-plane availability ≥99,9% за 30-дневное окно, исключая документированное обслуживание. | Заменён не определённый термин `supported workload` на канонический `Reference Workload`; унифицировано имя SLI `control-plane availability`. | +| **NFR-R5:** Task начинает выполнение ≤5 секунд p95 при нормальной загрузке; recovery зависших leases после restart ≤60 секунд. | **NFR-R5:** Task начинает выполнение ≤5 секунд p95 при нагрузке в пределах NFR-P1; recovery зависших leases после restart ≤60 секунд. | Заменено неизмеримое условие «нормальная загрузка» на ссылку на определённую границу нагрузки. | +| Good minute не содержит Crank-caused 5xx/timeout/data-integrity failure и имеет ≥99% предусмотренных outcomes среди валидных авторизованных requests. | В good minute отсутствуют Crank-caused 5xx, timeout и data-integrity failure; не менее 99% валидных авторизованных requests завершаются одним из предусмотренных outcomes. | Устранено ложное владение «минута имеет outcomes» и явно определено, к чему относится порог 99%. | +| Overload ниже NFR-P1 считается failure. | Overload при входящей нагрузке в пределах NFR-P1 считается failure. | Уточнено, что «ниже NFR-P1» относится к уровню входящей нагрузки, а не к степени overload или значению failure. | +| **NFR-S4:** bounded input/body/response/concurrency/queue/cardinality limits действуют до накопления неограниченного ресурса. | **NFR-S4:** bounded input, body, response, concurrency, queue и cardinality limits предотвращают неограниченное накопление ресурсов. | Заменена неясная временная конструкция «действуют до накопления» на требуемый причинный результат. | +| **SM-1 — Scope completeness:** 100% FR-1—FR-53 и элементов утверждённого Capability Inventory имеют принятое evidence. | **SM-1 — Scope completeness:** для 100% FR-1—FR-53 и элементов утверждённого Capability Inventory принято evidence. | Исправлено ложное владение: requirement или inventory item не «имеет принятое evidence»; evidence принимается для него. | +| **SM-4 — Defects:** открытые Critical/High product и security defects = 0; Medium имеют owner и не нарушают SLO/данные/безопасность. | **SM-4 — Defects:** количество открытых product и security defects уровня Critical или High равно нулю; defects уровня Medium имеют owner и не нарушают SLO, целостность данных или безопасность. | Явно назван субъект второй части и раскрыты severity и slash-конструкции. | +| каждый construct совпадает с expected semantics либо даёт явный unsupported finding | каждая конструкция в corpus соответствует expected semantics либо получает явный unsupported finding | Уточнена область квантора `каждый`: исходная формулировка не указывала, о конструкциях какого набора идёт речь. | +| **Scope breadth:** одновременное hardening и добавление четырёх крупных clusters может затянуть готовность. | Consider: перечислить четыре cluster явно: «одновременное hardening и добавление [cluster 1], [cluster 2], [cluster 3] и [cluster 4] может затянуть готовность». | Число «четыре» не связано с именованным перечнем, поэтому downstream AI не может однозначно определить затронутые группы; точный список требует решения автора. | +| Phase-blocking вопросов не осталось: пользователь делегировал решения Fast path. Перед feature freeze необходимо обновить значения, зависящие от внешнего состояния. | На текущем этапе phase-blocking вопросов нет: пользователь делегировал решения Fast path. До указанных ниже стадий необходимо определить четыре значения, зависящие от внешнего состояния. | Устранено кажущееся противоречие между отсутствием blockers и решениями, которые блокируют более поздние стадии; временная область утверждения сделана явной. | +| До Baseline Frozen каждый finding должен получить отдельный disposition: закрыт requirement/architecture/test, принят как non-goal с обоснованием либо повышен до blocker. | До Baseline Frozen каждый finding должен получить отдельный disposition: закрыт изменением requirement, architecture или test; принят как non-goal с обоснованием; либо повышен до blocker. | Раскрыта неоднозначная slash-конструкция и явно указано действие, которым закрывается finding. | diff --git a/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/polish-structure-addendum.md b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/polish-structure-addendum.md new file mode 100644 index 0000000..5743407 --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/polish-structure-addendum.md @@ -0,0 +1,59 @@ +## Document Summary +- **Purpose:** Зафиксировать технические направления, ограничения и проверяемые evidence-контракты, которые Architecture и QA должны превратить в архитектурные решения и исполняемые проверки для production-ready Community-релиза Crank. +- **Audience:** Архитекторы и QA-инженеры, использующие addendum как техническое дополнение к chain-top PRD. +- **Reader type:** llm; применяются dependency-first порядок, однозначные ссылки, единая терминология и структурированные форматы вместо повествовательного текста. +- **Structure model:** Reference/Database — документ должен поддерживать точечное извлечение требований, быть MECE и использовать одинаковую схему для каждого технического домена. +- **Core question:** Какие технические направления, системные инварианты и доказательства готовности должны быть учтены при архитектуре и проверке Community-релиза? +- **Current length:** 879 words across 6 sections. Карта разделов: вводная часть — 42; «Наблюдаемость» — 214; «Встроенное нагрузочное тестирование» — 121; «MCP» — 228; «Reference Deployment и Evidence» — 109; «Recovery и поставка» — 130; «Источники технической проверки» — 35. + +## Recommendations + +### 1. QUESTION - Нормативный статус каждого положения +**Rationale:** В одном списочном уровне смешаны пользовательские требования, обязательные системные инварианты, рекомендуемые механизмы и решения, которые ещё должна подтвердить архитектура, поэтому LLM и downstream-команды не могут надёжно определить обязательность утверждения. +**Impact:** ~+35 words за краткие маркеры статуса или одну таблицу-легенду (`requirement`, `invariant`, `recommendation`, `architecture decision pending`). + +### 2. MOVE - Выделить «Фоновые выполнения и Task semantics» из раздела «MCP» +**Rationale:** Durable Task, очередь, delivery, fencing, `outcome_unknown` и `input_required` образуют самостоятельный execution-контракт и не являются частью того же reference-кластера, что Resources, Prompts и protocol compatibility. +**Impact:** ~+6 words на новый заголовок; текст положений сохраняется без дублирования. + +### 3. MOVE - Разделить «Recovery и поставка» на четыре адресуемых подраздела +**Rationale:** Upgrade/rollback, backup/restore/key custody, offline bundle и web/auth security решают разные задачи и должны извлекаться независимо по схеме Reference/Database. +**Impact:** ~+12 words на заголовки «Upgrade и rollback», «Backup и restore», «Offline-поставка», «Web и admin security». + +### 4. MOVE - Поставить Reference Deployment перед нагрузкой и числовыми SLO +**Rationale:** Resource envelope и разделение load generator определяют контекст всех последующих численных performance, spool и recovery утверждений, поэтому должны быть объявлены до их использования. +**Impact:** ~0 words; меняется только порядок разделов и переносится один deployment-блок. + +### 5. MOVE - Отделить «Evidence contract» от «Reference Deployment» и поместить после технических доменов +**Rationale:** Workload artifact, background workload и Evidence Manifest описывают общий способ доказательства требований, а не среду развёртывания, и логически завершают все доменные контракты. +**Impact:** ~+3 words на отдельный заголовок; существующие три bullets переносятся без изменения смысла. + +### 6. CONDENSE - Нормализовать длинные compound bullets наблюдаемости +**Rationale:** Пункты про production profile, fail-open delivery и spool одновременно задают несколько независимо проверяемых полей; таблица `Concern | Contract | Default | Failure behavior | Evidence` устранит неоднозначность и повторяющиеся связки. +**Impact:** ~35 words saved при сохранении всех значений: 100%, 99,99%, 25/24/30 часов, 7/30 дней и 100/250 RPS. + +### 7. MERGE - Единожды определить изоляцию load generator +**Rationale:** Требование размещать генератор отдельно от измеряемого Crank повторяется в разделах «Встроенное нагрузочное тестирование» и «Reference Deployment и Evidence» без дополнительного смысла. +**Impact:** ~12 words saved; оставить норму в Reference Deployment, а из load-testing ссылаться на этот контракт только при необходимости. + +### 8. MOVE - Связать технические источники с соответствующими доменами +**Rationale:** Нижний неаннотированный список ссылок заставляет LLM самостоятельно угадывать, какой источник подтверждает конкретный trace, exemplar, MCP или k6 контракт. +**Impact:** ~0 words при переносе ссылок в `References` каждого доменного раздела; альтернативно ~+14 words на явную таблицу `Source | Applies to`. + +### 9. CONDENSE - Заменить повторяющиеся вводные формулы на статусные поля +**Rationale:** Формулировки «рекомендуемая топология», «рекомендуемый reference runner», «рекомендуемая модель» и «рекомендуемый dispatch pattern» повторяют модальность, которую точнее и короче выражает единая схема статусов из рекомендации 1. +**Impact:** ~20 words saved после введения статусной легенды. + +### 10. PRESERVE - Вводное ограничение об отсутствии преждевременного архитектурного выбора +**Rationale:** Эта одна фраза удерживает addendum в границах его роли и не даёт downstream-читателю ошибочно принять предложенные механизмы за уже утверждённую архитектуру. +**Impact:** ~0 words; сохранение предотвращает scope violation и не требует дополнительного пояснения. + +### 11. PRESERVE - Конкретные примеры и граничные значения +**Rationale:** `outcome_unknown`, fencing token, DAU decomposition, load-test-safe contract, spool envelope и состав offline bundle заземляют общие требования в проверяемом контексте Crank и снижают риск неверного вывода LLM. +**Impact:** ~0 words; эти детали не следует сокращать как «implementation noise» до принятия архитектурных решений и построения QA evidence. + +## Summary +- **Total recommendations:** 11 +- **Estimated reduction:** ~11 words net (~1% of original); цель структурного прохода — MECE, dependency order и однозначный нормативный статус, а не сокращение содержательной глубины. +- **Meets length target:** No target specified +- **Comprehension trade-offs:** Существенных trade-offs нет: рекомендованные сокращения затрагивают только повтор модальности и дублирование; примеры, числовые контракты и scope-оговорка явно сохраняются. diff --git a/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/polish-structure-prd.md b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/polish-structure-prd.md new file mode 100644 index 0000000..045ae6c --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/polish-structure-prd.md @@ -0,0 +1,134 @@ +## Document Summary + +- **Purpose:** Зафиксировать канонический, проверяемый контракт production-ready релиза Crank Community, пригодный для продуктовой декомпозиции, UX, архитектуры, реализации, QA и решения о публичном запуске. +- **Audience:** Product, Architecture, UX и QA; документ также служит точным источником требований для downstream AI. +- **Reader type:** `llm`; применяются принципы dependency-first, единой терминологии, явных ссылок и структурированных контрактов. +- **Structure model:** Strategic/Context (Pyramid) с вложенным Reference-модулем для FR/NFR. +- **Core question:** Какие возможности, ограничения, измеримые свойства и доказательства обязательны, чтобы Crank Community можно было обоснованно объявить production-ready и опубликовать на Хабре? +- **This document exists to help:** Product, Architecture, UX, QA и downstream AI однозначно определить, реализовать и доказать готовность Crank Community к публичному production-релизу. +- **Current length:** 7 811 слов в 14 основных разделах; 94 заголовка всех уровней. + +### Current structure map + +| Раздел | Примерный объём | Прямая связь с целью | Структурное наблюдение | +|---|---:|---|---| +| §0 Назначение документа | 67 слов | Да | Полезен, но частично повторяет видение и release thesis. | +| §1 Видение | 120 слов | Да | Хорошо формулирует продукт и принцип gate; решение A-1 затем повторяется. | +| §2 Целевые пользователи | 471 слово | Да | Роли, JTBD и пять journeys дают необходимую продуктовую рамку. | +| §3 Глоссарий | 299 слов | Да | Нормативен, но расположен после первого использования большей части терминов. | +| §4 Функциональные возможности | 4 223 слова | Да | Каноническое ядро; §4.9 смешивает product requirements и release governance. | +| §5 Сквозные нефункциональные требования | 1 262 слова | Да | Точные NFR зависят от Reference Deployment/Workload; часть текста описывает механизм реализации. | +| §6 Ограничения и guardrails | 189 слов | Да | Границы нужны до чтения FR, а не после них. | +| §7 Явные non-goals | 68 слов | Да | Логически является частью scope/boundaries. | +| §8 Scope production-релиза | 129 слов | Да | Полезная сводка, но повторяет группы §4 и правило A-1/FR-54. | +| §9 Последовательность достижения готовности | 104 слова | Да | Критический release contract, сейчас находится слишком поздно. | +| §10 Метрики успеха и Release Gate | 494 слова | Да | Критический gate, частично дублирует §4.9. | +| §11 Основные риски и смягчение | 146 слов | Да | Компактный и уместный раздел после контрактов. | +| §12 Открытые вопросы | 191 слово | Да частично | На деле содержит deferred decisions и временное review-состояние, а не открытые вопросы одного типа. | +| §13 Реестр подтверждённых решений | 163 слова | Да | Канонические решения скрыты после всех требований и повторяют inline-формулировки. | + +## Recommendations + +### 1. MERGE - §§6–8 в единый раздел «Scope и границы релиза» перед функциональными требованиями + +**Rationale:** Community scope, guardrails, non-goals и обязательный scope задают область интерпретации всех FR/NFR, поэтому должны быть прочитаны до них и храниться в одном MECE-разделе. + +**Impact:** ~50 слов сокращения за счёт устранения повторов между «обязательно до запуска», non-goals и Community scope. + +### 2. MOVE - §13 «Реестр подтверждённых решений» перед детальными требованиями и сделать его единственным источником текста A-1—A-12 + +**Rationale:** Downstream AI должен знать делегированные решения до интерпретации FR/NFR, а повторение полного решения inline и в реестре создаёт риск расхождения. + +**Impact:** ~90 слов сокращения; в FR/NFR остаются короткие ссылки вида «см. A-7», а нормативная формулировка хранится в реестре. + +### 3. MOVE - §3 «Глоссарий» сразу после краткого продуктового видения и до пользователей/journeys + +**Rationale:** `Operation`, `Agent`, `Resource`, `Prompt`, `Task`, `Execution`, `Trace ID` и другие локальные понятия используются в §1–§2 до определения, что нарушает dependency-first порядок для LLM. + +**Impact:** ~0 слов; меняется только последовательность. + +### 4. MERGE - §4.9, §9 и §10 в единый нормативный модуль «Release readiness и evidence contract» + +**Rationale:** Quality FR-46—FR-54, стадии готовности и SM-1—SM-10 описывают один gate с разных сторон и сейчас требуют от читателя вручную сводить взаимные ссылки. + +**Impact:** ~180 слов сокращения за счёт единственного определения RC, Public Ready, Evidence Manifest и запрета исключений; стабильные идентификаторы FR/SM сохраняются. + +### 5. MOVE - вынести implementation-specific механизмы из PRD в `addendum.md`, сохранив нормативные outcomes и прямые ссылки + +**Rationale:** CAS/fencing details в FR-22, атомарный dispatch intent в FR-23, устройство disk spool в FR-31/NFR-O2a, migration/WAL mechanics в FR-43 и JSON Schema verifier в FR-52 относятся к architecture/solution design, тогда как PRD должен удерживать capability, safety invariant и проверяемый результат. + +**Impact:** ~450 слов сокращения основного PRD без потери содержания в наборе артефактов; каждый перенос должен оставить в PRD стабильный ID, обязательный outcome и точную ссылку на addendum. + +### 6. CONDENSE - оставить правило «все обязательные возможности до Хабра» в одном каноническом месте + +**Rationale:** Одна и та же политика сформулирована в §1, §8.2, FR-54, §9 и косвенно в §12; для LLM повторение нормативного правила повышает риск будущего несовпадения редакций. + +**Impact:** ~70 слов сокращения; рекомендуемый источник истины — FR-54 внутри объединённого release-модуля, остальные места содержат только ссылку. + +### 7. CONDENSE - переименовать §12 в «Deferred decisions и review dispositions» и разделить два разных списка + +**Rationale:** Четыре параметрических решения с владельцами и сроками пересмотра не являются обычными open questions, а review findings представляют отдельный временный workflow-state. + +**Impact:** ~15 слов сокращения; структура становится `Deferred decisions` и `Review dispositions` с явным типом, owner, deadline и blocking stage. + +### 8. MOVE - вынести ссылки на конкретные `review-*.md` и требование disposition в release evidence/work tracker + +**Rationale:** Имена файлов текущего reviewer pass являются временной информацией процесса и быстро устареют в финальном каноническом PRD. + +**Impact:** ~55 слов сокращения PRD; постоянное правило «каждый finding получает disposition» остаётся в release/evidence contract. + +### 9. MOVE - отделить «Benchmark context» от каталога NFR внутри §5 + +**Rationale:** Reference Deployment и Reference Workload являются входными условиями измерения, а NFR-P/R/S/O/C — нормативными результатами; явное разделение не позволит downstream AI принять тестовые параметры за требования реализации или наоборот. + +**Impact:** ~0 слов; рекомендуемый порядок: `Measurement context` → `Performance` → `Reliability` → `Security` → `Observability` → `Compatibility`. + +### 10. MERGE - создать в начале одностраничный «Product and release contract» из §0 и ядра §1 + +**Rationale:** Pyramid-модель требует сразу сообщить, что строится, для кого, какой статус имеет документ и какое условие разрешает публичный запуск, прежде чем читатель погрузится в детали. + +**Impact:** ~35 слов сокращения; блок должен содержать только product definition, public-ready thesis, release condition и навигацию к scope/gate, не пересказывать требования. + +### 11. PRESERVE - стабильную схему каждого FR: capability statement → «Проверяемые последствия» + +**Rationale:** Повторяющаяся форма не является избыточностью: она делает FR-1—FR-54 адресуемыми, извлекаемыми и проверяемыми без неявных antecedents. + +**Impact:** ~0 слов; попытка свернуть 54 FR в одну широкую таблицу ухудшит точность и читаемость вложенных safety contracts. + +### 12. PRESERVE - пять именованных пользовательских journeys в §2.4 + +**Rationale:** Journeys связывают роли с end-to-end outcome и удерживают качественные аспекты UI, traceability, closed-loop deployment, load testing и background execution, которые легко потерять при чтении только FR. + +**Impact:** ~0 слов; блок следует сохранить как продуктовую scaffolding перед requirements. + +### 13. PRESERVE - Counter-metrics SM-C1—SM-C5 рядом с Primary gate metrics + +**Rationale:** Counter-metrics предотвращают формально успешное прохождение gate за счёт безопасности, корректности импорта, стабильности MCP, observability budget или vanity adoption. + +**Impact:** ~0 слов; эти ограничения являются функциональной частью определения успеха, а не повторным резюме. + +### 14. PRESERVE - детальный Reference Workload и численные NFR + +**Rationale:** Для chain-top PRD и downstream AI конкретные mix, payload, upstream behavior, capacity и telemetry mode необходимы, чтобы performance evidence было воспроизводимым и не трактовалось произвольно. + +**Impact:** ~0 слов; сокращать следует только mechanism-level детали, не параметры измерения и thresholds. + +## Recommended target order + +1. Product and release contract (объединённые §0 + ядро §1). +2. Glossary (текущий §3). +3. Target users, JTBD и user journeys (текущий §2). +4. Scope and boundaries (объединённые §§6–8). +5. Confirmed decision registry A-1—A-12 (текущий §13 как единственный источник). +6. Functional requirements FR-1—FR-45 (текущий §4.1–§4.8). +7. Measurement context and NFR catalog (текущий §5 с явным внутренним разделением). +8. Release readiness and evidence contract FR-46—FR-54 + SM-1—SM-15 + SM-C1—SM-C5 (объединённые §4.9, §9, §10). +9. Risks and mitigations (текущий §11). +10. Deferred decisions (перестроенный §12; временные review-файлы вынесены). + +## Summary + +- **Total recommendations:** 14 +- **Estimated reduction:** ~945 слов (около 12% исходного PRD); около 450 слов не удаляются из набора артефактов, а перемещаются в `addendum.md`. +- **Meets length target:** No target specified. +- **Comprehension trade-offs:** Предлагаемые сокращения не удаляют user journeys, стабильные FR/SM/NFR IDs, acceptance outcomes, численные thresholds или counter-metrics. Главный риск — потеря implementation invariants при переносе в addendum; поэтому каждый перенос требует нормативной строки в PRD и однозначной ссылки на точное место в addendum. diff --git a/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md new file mode 100644 index 0000000..cf49791 --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md @@ -0,0 +1,813 @@ +--- +title: "Crank Community — Production Readiness" +status: final +created: 2026-08-03 +updated: 2026-08-03 +--- + +# PRD: Crank Community — Production Readiness + +## 0. Назначение документа + +Этот PRD определяет обязательный объём и измеримые критерии, при выполнении которых открытую Community-версию Crank можно публично представить как production-ready, в том числе опубликовать на Хабре. Документ предназначен для продуктовой проработки, UX, архитектуры, декомпозиции на эпики, реализации и QA. Он сохраняет существующие продуктовые контракты, добавляет недостающие современные возможности MCP и превращает требования «быстро, безопасно и надёжно» в проверяемые условия. Делегированные пользователем решения перечислены в §13. + +## 1. Видение + +Crank Community — бесплатная self-hosted платформа, позволяющая небольшим организациям и частным разработчикам без написания интеграционного кода превращать REST API в MCP tools, resources и prompts, собирать из них каталоги агентов и безопасно использовать всё это внутри собственного контура. + +Production-ready версия должна не только выполнять простой happy path REST → MCP. Она должна предсказуемо обрабатывать реальные OpenAPI-спецификации, современные MCP-контракты, параллельные и долгие выполнения, перезапуски, ошибки зависимостей и эксплуатационные нагрузки. Любой запрос должен быть диагностируемым по `request_id` и `trace_id`, а состояние системы — наблюдаемым через UI, GlitchTip, Prometheus и Grafana. + +Публичный запуск — это доказанный уровень качества, а не дата. Все возможности, названные пользователем, обязательны до публикации на Хабре. **Решение A-1:** публичный анонс не выполняется по календарю; он разрешается только после прохождения Release Gate из FR-54. + +## 2. Целевые пользователи + +### 2.1 Основные пользователи + +- **Частный разработчик:** быстро подключает собственный или сторонний REST API к MCP-клиенту без создания отдельного MCP-сервера. +- **Инженер небольшой организации:** разворачивает Crank в закрытом контуре и предоставляет агентам контролируемый каталог возможностей. +- **Администратор/оператор:** управляет операциями, агентами, ключами, секретами, публикациями и качеством выполнения. +- **SRE/ответственный за эксплуатацию:** отслеживает запросы, SLO, насыщение, ошибки и деградацию; проводит нагрузочные и восстановительные проверки. + +### 2.2 Jobs To Be Done + +- Импортировать API или описать REST-операцию вручную и получить работающий MCP capability за минуты, а не дни. +- Предоставить агенту только опубликованные и разрешённые capabilities, не раскрывая секреты и внутренние данные. +- Создавать tools, resources и prompts в одном UI с единым lifecycle, версионированием и публикацией. +- Безопасно выполнять долгие операции в фоне, наблюдать прогресс, отменять и восстанавливать их после сбоя. +- По одному Trace ID проследить путь от пользовательского действия через API, runtime и upstream до результата. +- До публичного или внутреннего запуска доказать производительность системы воспроизводимым нагрузочным профилем. + +### 2.3 Не пользователи целевого релиза + +- Крупные организации, которым обязательны multi-workspace tenancy, команды, RBAC, SSO/SAML и коммерческий SLA. +- Пользователи, которым требуется managed SaaS или передача данных во внешний облачный контур Crank. +- Сценарии преобразования GraphQL, gRPC, SOAP/WSDL или произвольного кода в MCP capability. + +### 2.4 Ключевые пользовательские пути + +**Решение A-2:** пути сформированы из текущего продукта и целевой аудитории; отдельного UX-исследования пока нет. + +- **UJ-1. Алексей публикует надёжный MCP tool из OpenAPI.** Алексей разворачивает Crank Community в локальной сети, входит как администратор, загружает реальную OpenAPI-спецификацию, просматривает warnings и будущие операции, исправляет неоднозначности, создаёт drafts, тестирует одну операцию, публикует версию и привязывает её к агенту. В MCP-клиенте появляется tool, а успешный вызов виден в Logs с `request_id` и `trace_id`. Если часть спецификации не поддержана, отчёт импорта явно указывает потерю данных и объясняет, что нужно исправить. + +- **UJ-2. Елена создаёт закрытый агентный контекст.** Елена создаёт versioned Resource из внутреннего REST API и Prompt с параметрами, проверяет результат в preview, публикует версии и привязывает их к агенту. MCP-клиент обнаруживает только разрешённые опубликованные версии. Ни секреты, ни содержимое закрытого контура не отправляются за пределы установки. + +- **UJ-3. Игорь расследует сбой выполнения.** Игорь открывает неуспешное выполнение в UI, копирует `trace_id` или переходит по deep link в GlitchTip, видит связанные spans от входящего MCP-вызова до runtime и upstream. Затем открывает Grafana, сопоставляет всплеск error rate с saturation и конкретным exemplar, не используя высококардинальные labels. + +- **UJ-4. Мария проверяет готовность релиза нагрузкой.** Мария выбирает опубликованный сценарий, задаёт RPS или оценочный DAU-профиль, ramp, duration и thresholds. После подтверждения безопасных границ запускает тест, наблюдает live-статистику, останавливает его при необходимости и получает неизменяемый итоговый отчёт с pass/fail и ссылками на Grafana. + +- **UJ-5. Агент выполняет долгую задачу.** MCP-клиент вызывает task-enabled tool, получает устойчивый идентификатор задачи и отслеживает статус. После рестарта worker выполнение восстанавливается без неконтролируемого повторного side effect; пользователь может отменить задачу, а UI показывает прогресс, попытки, результат и коррелированный trace. + +## 3. Глоссарий + +- **Operation** — versioned описание одного REST-вызова, его входной и выходной схемы, mapping, runtime и safety policy. +- **Tool** — опубликованная Operation, доступная MCP-клиенту через Agent. +- **Resource** — versioned read-only MCP capability со статическим URI или URI template, который возвращает text, JSON или binary content. +- **Prompt** — versioned параметризованный MCP-шаблон сообщений, выбираемый пользователем или MCP-клиентом. +- **Agent** — versioned опубликованный каталог разрешённых Tools, Resources и Prompts с отдельным MCP endpoint. +- **Draft** — изменяемая версия capability, недоступная через опубликованный Agent до публикации. +- **Published Version** — неизменяемая версия capability, разрешённая для привязки к опубликованному Agent. +- **Execution** — одна попытка синхронного или фонового выполнения Tool. +- **Task** — durable представление долгого Execution со статусом, прогрессом, результатом и операциями получения, обновления и отмены. +- **Load Run** — один воспроизводимый прогон нагрузочного Scenario с параметрами, thresholds и итоговым отчётом. +- **Scenario** — versioned описание распределения вызовов и данных для Load Run. +- **Request ID** — идентификатор отдельного входящего запроса, предназначенный для продуктовой поддержки и журналов. +- **Trace ID** — W3C-совместимый идентификатор распределённой трассы через UI/API/MCP/runtime/upstream/background boundaries. +- **Invocation History** — локальная история Execution с безопасными previews, outcome, duration, Request ID и Trace ID. +- **SLI** — измеритель поведения системы с точки зрения пользователя или оператора. +- **SLO** — целевая граница SLI с периодом измерения и error budget. +- **Release Gate** — совокупность обязательных проверок, без которых публичный production-анонс запрещён. +- **Reference Deployment** — воспроизводимая конфигурация, на которой проверяются SLO и performance budgets. +- **Reference Workload** — versioned и checksummed сценарий с фиксированными mix, dataset, payloads, upstream behavior, cache state и telemetry mode. +- **Capability Inventory** — versioned реестр всех существующих и целевых UI/API/MCP flows с контрактом, статусом и regression evidence. +- **Evidence Manifest** — подписанный machine-readable индекс RC-артефакта, окружения, проверок, результатов и владельцев решения Release Gate. +- **Telemetry Loss Record** — локальная неизменяемая запись о trace, который не удалось доставить во внешний backend после bounded retries. + +## 4. Функциональные возможности + +### 4.1 Стабилизация существующего ядра + +**Описание:** существующие Operations, Agents, ключи, секреты, approvals, test run, YAML import/export, Logs и Usage сохраняют текущую семантику, но проходят полный контрактный и пользовательский аудит. Draft никогда не влияет на Published Version; секреты и raw keys раскрываются только один раз; Tool доступен только через разрешённый опубликованный каталог. + +#### FR-1: Управление lifecycle Operation + +Администратор может создавать, тестировать, версионировать, публиковать, архивировать, импортировать и экспортировать Operations без изменения уже опубликованного поведения. + +**Проверяемые последствия:** +- Draft edit не меняет каталог Agent до явной публикации и перепривязки. +- YAML roundtrip сохраняет wire-контракт; `upsert` создаёт новую версию, а не переписывает историю. + +#### FR-2: Безопасное REST-выполнение + +Crank выполняет поддерживаемые REST Operations с mapping, authentication, timeout, retry, cache, idempotency, response limits и outbound policy. + +**Проверяемые последствия:** +- SSRF, redirects, proxy use, response size, timeout и private-address policy применяются к фактическому соединению. +- Crank сохраняет стадию отказа и не раскрывает credential или чувствительный payload. + +#### FR-3: Secrets и ключи + +Администратор может создавать, ротировать и отзывать auth profiles, MCP keys и approval keys с one-time disclosure raw value. + +**Проверяемые последствия:** +- Сохранённое raw value нельзя получить через read/list/export/log. +- Отозванный ключ прекращает доступ без перезапуска сервиса. +- Admin API и MCP server используют одну подтверждённую master-key identity; несовпадение ключей блокирует безопасный startup/readiness. +- Rotation выполняется через проверяемый re-encryption path; backup/restore сохраняет доступ к key material без его раскрытия в артефактах. +- Первичная admin credential создаётся одноразовым bootstrap-процессом без default password, не печатается в logs и после использования становится недействительной. +- Login имеет bounded rate limit/backoff и не раскрывает существование account; password rotation/recovery отзывает все browser sessions/CSRF tokens и создаёт audit event. Offline recovery требует локального operator access и не обходит master-key protection. + +#### FR-4: Versioned Agent catalog + +Администратор может собирать опубликованный Agent из Published Versions capabilities и выбирать direct или search mode. + +**Проверяемые последствия:** +- MCP-клиент не обнаруживает Draft или capability вне своего Agent. +- Смена каталога инвалидирует устаревший search result через revision contract. + +#### FR-5: Approval и защита side effects + +Operation может требовать подтверждение, а повторный запрос не создаёт конкурирующие approval records. + +**Проверяемые последствия:** +- Approve/deny/expiry/recovery атомарны и изолированы по Agent, Operation, version и входу. +- Повторение write Execution не обещает exactly-once без idempotency support upstream. + +#### FR-6: История и usage + +UI предоставляет фильтруемую Invocation History и Usage по периоду, Agent и Operation с безопасными previews, outcome и percentiles. + +**Проверяемые последствия:** +- Потеря записи history наблюдаема отдельной метрикой и не изменяет результат Execution. +- CSV export соблюдает redaction и текущую изоляцию Community-профиля. + +### 4.2 Production-grade OpenAPI import + +**Описание:** импорт должен работать на репрезентативных реальных OpenAPI 3.0/3.1 и Swagger 2.0 документах. Неподдержанная конструкция становится явным finding; тихая потеря параметров, schema branches или security semantics запрещена. + +#### FR-7: Предварительный анализ без мутаций + +Администратор получает preview endpoints, groups, names, mappings, schemas, conflicts, warnings и unsupported constructs до создания Draft. + +**Проверяемые последствия:** +- UI принимает `.yaml`, `.yml` и `.json` файлы OpenAPI через явно ограниченный upload contract; UTF-8/encoding, multipart и file-size ошибки диагностируются до мутаций. +- E2E regression доказывает, что методы извлечены именно из загруженного `openapi.yaml`; отдельные cases покрывают повреждённый, пустой, oversized и не содержащий методов документ. +- Preview детерминирован для одного входного документа. +- Ошибка одного endpoint не создаёт частичный набор Operations без явно выбранного partial mode. + +#### FR-8: Полнота HTTP-контрактов + +Импорт поддерживает стандартные REST methods, path/query/header/cookie parameters, все успешные `2xx` responses и распространённые JSON, form и multipart request bodies. **Решение A-3:** XML payloads остаются вне production scope, но обнаруживаются как явный unsupported finding. + +**Проверяемые последствия:** +- Required/default/enum/nullable/format и content type не теряются молча. +- `204 No Content` и несколько success schemas создают корректный Operation contract. + +#### FR-9: References и composition + +Importer корректно разрешает локальные references и безопасно обрабатывает разрешённые внешние references; `allOf`, `oneOf`, `anyOf`, recursion и discriminators либо сохраняются, либо блокируют создание с объяснением. + +**Проверяемые последствия:** +- Внешняя загрузка выключена по умолчанию и ограничена operator-controlled allowlist/offline bundle. +- Preview загружает все разрешённые external references в immutable content-addressed snapshot; создание Draft использует только этот snapshot и его digest. Изменение remote content требует нового preview, что закрывает TOCTOU между анализом и import commit. +- Depth/size/cycle limits дают диагностируемый finding, а не crash или неполный schema. + +#### FR-10: Security schemes + +Importer распознаёт поддерживаемые bearer/basic/api-key schemes и предлагает привязку к Auth Profile без импорта raw secret. + +**Проверяемые последствия:** +- Неизвестная или OAuth-specific схема помечается как требующая ручной настройки. +- Secret value отсутствует в Draft, preview, logs и export. + +#### FR-11: Управление конфликтами и повторный импорт + +Администратор может выбрать skip, rename или создание новой версии; повтор одного import request безопасен и атомарен. + +**Проверяемые последствия:** +- Concurrent replay не создаёт дубликаты сверх выбранной политики. +- Итоговый отчёт перечисляет созданные, обновлённые, пропущенные и отклонённые endpoints. + +#### FR-12: Regression corpus + +Проект поддерживает versioned corpus реальных и синтетических спецификаций с expected import outcomes. + +**Проверяемые последствия:** +- Normative support matrix перечисляет применимые OpenAPI 3.0, OpenAPI 3.1 и Swagger 2.0 constructs со статусом `supported`/`unsupported`, точной сохраняемой семантикой и expected finding; `partial` без явного пользовательского выбора запрещён. +- Mandatory baseline включает все REST methods кроме `TRACE`/`CONNECT`, path/query/header/cookie parameters, JSON/form/multipart bodies, все `2xx` responses, local и allowlisted external references, common schema composition и bearer/basic/api-key schemes. Не менее 95% Operations в утверждённом representative corpus импортируются в actionable Draft без blocker finding. +- Любой исправленный import defect добавляет regression fixture. +- Corpus проверяет YAML/JSON file upload, large/hostile documents, reference cycles и сложные compositions. + +### 4.3 Современная MCP server surface + +**Описание:** Crank реализует стабильные server-side возможности актуального MCP, применимые к роли self-hosted capability server. **Решение A-4:** обязательная compatibility matrix на feature freeze включает последнюю стабильную MCP-версию и две предшествующие поддерживаемые версии; experimental extensions включаются отдельно и не заменяют стабильный путь. + +#### FR-13: Protocol negotiation и совместимость + +MCP endpoint согласует protocol version и capabilities, не рекламируя неподдержанное поведение. + +**Проверяемые последствия:** +- Для каждой заявленной версии выполняется автоматическая conformance matrix. +- Несовместимый клиент получает структурированную ошибку или documented fallback. + +#### FR-14: Полный Tools contract + +Существующие `tools/list` и `tools/call` поддерживают pagination, structured content/errors, progress, cancellation и list-changed notification там, где это предусмотрено согласованной версией. + +**Проверяемые последствия:** +- Cancel/timeout не оставляет Execution в ложном terminal state. +- Tool schema и Published Version стабильны в рамках Agent revision. + +#### FR-15: Versioned Resources + +Администратор может создавать, preview, тестировать, версионировать, публиковать, архивировать, импортировать и экспортировать Resources, затем привязывать Published Versions к Agent. + +**Проверяемые последствия:** +- MCP поддерживает discovery, templates и read для разрешённых Resources. +- Resource остаётся read-only и наследует workspace/Agent/auth/outbound policies. +- Static content имеет sensitivity classification, MIME/size limits и publish-time secret scan; raw credentials и ссылки, обходящие Agent access, блокируют публикацию. + +#### FR-16: Resource types + +Resource может предоставлять static text/JSON/binary content или динамически получать разрешённые данные из REST source по URI template. **Решение A-5:** динамический REST-backed Resource входит в public-launch scope, чтобы Resources давали ценность сверх статических файлов. + +**Проверяемые последствия:** +- Template parameters валидируются, traversal и выход за разрешённый root запрещены. +- MIME type, size limit, cache policy и безопасный failure outcome видны до публикации. + +#### FR-17: Versioned Prompts + +Администратор может создавать, preview, тестировать, версионировать, публиковать, архивировать, импортировать и экспортировать parameterized Prompts, затем привязывать Published Versions к Agent. + +**Проверяемые последствия:** +- MCP поддерживает prompts discovery и get с типизированными UI inputs. +- Отсутствующий/невалидный argument даёт понятную ошибку до выдачи частично отрендеренного Prompt. + +#### FR-18: Prompt composition + +Prompt поддерживает системные/пользовательские/assistant messages и разрешённые ссылки на Resources без выполнения произвольного кода. + +**Проверяемые последствия:** +- Preview показывает итоговые messages и используемые версии dependencies. +- Публикация блокируется при циклической или неопубликованной dependency. +- Composed Prompt фиксирует Published Versions Resources, наследует наиболее строгую sensitivity/access policy dependency и не может раскрыть secret-bearing content через rendering, preview или fallback-as-tool. + +#### FR-19: Completion, logging и notifications + +Crank поддерживает применимые stable completion, server logging, progress и capability-change notifications с соблюдением negotiated client capabilities. + +**Проверяемые последствия:** +- Notification не используется как единственный источник критического состояния. +- Уровни server logging не раскрывают secrets или payloads. + +#### FR-20: MCP compatibility evidence + +Каждый production release публикует проверенную матрицу protocol versions, methods, extensions и representative clients. + +**Проверяемые последствия:** +- На feature freeze каждая capability и extension официальной stable MCP specification получает статус `supported`, `not applicable`, `experimental` или `deferred` с обоснованием, fallback и evidence; молчаливый пропуск запрещён. +- `Deferred` для применимой stable server capability является release blocker; пройти gate могут только `supported` либо доказанно `not applicable` client-role capabilities. +- Matrix строится из исполняемых tests, а не только документации. +- Beta/experimental support явно отделён и может быть выключен без потери stable core. + +### 4.4 Параллельные и фоновые выполнения + +**Описание:** одновременные requests, долговременные MCP Tasks и внутренняя durable job-модель являются отдельными контрактами. Background execution не зависит от сохранения одного HTTP/SSE connection. + +#### FR-21: Execution mode + +Для Tool задаётся режим `synchronous`, `background` или `adaptive`; клиенту возвращается поведение, совместимое с negotiated MCP capabilities. + +**Проверяемые последствия:** +- Tool, запрещающий background, никогда не превращается в Task неявно. +- Клиент без Tasks получает documented synchronous fallback либо `unsupported`, выбранный при публикации Tool. + +#### FR-22: Durable Task lifecycle + +Task имеет устойчивый ID, owner scope, внутренние статусы `queued`, `working`, `input_required`, `outcome_unknown`, `completed`, `failed`, `cancelled`, progress, timestamps, attempts и result/error. Protocol adapter отображает внутреннее состояние только в допустимые negotiated MCP statuses, не делая `outcome_unknown` retriable failure. + +**Проверяемые последствия:** +- Status/result/cancel доступны через MCP и UI только авторизованному Agent/admin. +- Terminal state неизменяем и не исчезает до истечения configured retention. +- Недоступность обязательного Task/coordination store приводит к диагностируемому fail-closed отказу, а не к переходу на небезопасное недолговечное выполнение. +- Claim выполняется compare-and-swap с монотонным fencing token; stale worker не может обновить progress, result или side-effect checkpoint после потери lease. +- Terminal transition атомарен и допускается ровно один раз из разрешённого non-terminal state. +- Состояние `outcome_unknown` не является terminal state и блокирует retry/cancel-as-success до reconciliation; `outcome_unknown` не учитывается как completed/failed SLI success. + +#### FR-23: Recovery и delivery semantics + +Принятый Task сохраняется до подтверждения клиенту и восстанавливается после рестарта worker или сервиса. + +**Проверяемые последствия:** +- Нет принятого Task без durable record. +- Durable Task record и dispatch intent фиксируются атомарно до acknowledgement; crash между commit и delivery восстанавливается без потери работы. +- **Решение A-6:** продукт обещает at-least-once delivery и effectively-once side effect только при idempotency contract; exactly-once не заявляется. +- Crash/partition matrix покрывает до/после claim, до/после side effect, до/после terminal commit и повторную доставку. + +#### FR-24: Concurrency и backpressure + +Оператор управляет глобальными, per-Agent и per-Tool лимитами; система применяет bounded queues, fairness, timeout и overload rejection. + +**Проверяемые последствия:** +- Насыщение не приводит к unbounded memory growth. +- Rejection, queue wait и oldest task age наблюдаемы; ответ при rejection содержит retry guidance. +- Cache, lease, approval, idempotency и deduplication state изолированы полным workspace/Agent/auth scope; отказ обязательного safety store отражается в readiness и dependency-failure matrix. + +#### FR-25: Retry, cancellation и deadlines + +Task policy определяет attempts, backoff, deadline, cancellation и поведение outcome-unknown. + +**Проверяемые последствия:** +- `IdempotencyOutcomeUnknown` не ретраится автоматически. +- Cancellation кооперативна, её факт и возможный незавершённый side effect отражены явно. +- Background write допускает automatic retry/recovery только при подтверждённом upstream idempotency contract. Иначе lease loss/cancel после dispatch переводит Task в `outcome_unknown` и требует reconciliation/operator decision до повторного side effect. +- Fencing защищает состояние Crank, но не объявляется защитой внешней системы; execution attempt и idempotency fingerprint сохраняются до outbound dispatch. +- Для `input_required` авторизованный клиент передаёт schema-validated input через negotiated Task update; identical replay идемпотентен, conflicting replay возвращает conflict, истечение input TTL переводит Task в `failed` без нового side effect. +- Reconciliation фиксирует evidence и допускает только `outcome_unknown → completed`, `failed` либо новый явно подтверждённый attempt; cancel после возможного внешнего side effect не стирает `outcome_unknown` и audit trail. + +#### FR-26: Task operations в UI + +Администратор может фильтровать Tasks, просматривать progress/attempts/trace, отменять разрешённые Tasks и повторять безопасно повторяемые failures. + +**Проверяемые последствия:** +- UI различает Request ID, Trace ID, Execution ID и Task ID. +- Массовая destructive операция требует подтверждения и audit event. +- UI показывает `outcome_unknown`, запрещает обычный Retry/Cancel и предоставляет отдельный reconciliation flow с предупреждением о возможном повторном side effect. + +### 4.5 Сквозная наблюдаемость + +**Описание:** каждый продуктовый путь диагностируется от браузера или MCP boundary до upstream и background worker. Наблюдаемость не раскрывает данные и не превращает внешний telemetry backend в dependency продукта. + +#### FR-27: Correlation identity + +Каждый входящий запрос получает валидированные Request ID и Trace ID; W3C context распространяется через API, MCP, runtime, upstream и Task boundaries. + +**Проверяемые последствия:** +- Невалидный или превышающий лимит входящий `x-request-id` заменяется UUIDv7; Request ID никогда не используется как Trace ID. +- Недоверенный `traceparent` проходит строгую проверку; `tracestate` и `baggage` ограничены по размеру и allowlist keys, а секретные/пользовательские значения не передаются дальше. +- System correlation headers имеют приоритет над пользовательским mapping. +- Trace ID сохраняется в Invocation History и Task независимо от telemetry sampling. + +#### FR-28: Поиск и переход из UI + +UI показывает, копирует и ищет Request ID и Trace ID, а также формирует deep link в настроенный trace backend. + +**Проверяемые последствия:** +- Один e2e test доказывает путь UI action → API/MCP → runtime → upstream → UI history → trace backend. +- Недоступный backend не ломает Logs и не скрывает локальный Trace ID. + +#### FR-29: GlitchTip integration + +Production profile отправляет errors и performance transactions в GlitchTip, сохраняя корреляцию logs/spans. **Решение A-7:** для типичной Community-установки default trace sample rate равен 100% с retention 7 дней; errors хранятся не менее 30 дней, а sampling/retention конфигурируются оператором. + +**Проверяемые последствия:** +- При здоровом backend trace с любым Trace ID появляется в GlitchTip не позднее 60 секунд; после контролируемого outage bounded spool доставляет соответствующий trace не позднее 5 минут после восстановления. +- Каждый trace должен быть eventually доставлен в GlitchTip не позднее 25 часов от generation при outage не более 24 часов; Telemetry Loss Record означает нарушение SLO, остаётся доступен локально и не позволяет UI утверждать, что trace присутствует в GlitchTip. +- Telemetry payload проходит redaction и не содержит секреты, произвольные bodies или user-level labels. + +#### FR-30: Browser observability + +UI фиксирует navigation/API errors и browser spans, связывая их с server Trace ID без отправки чувствительных данных. + +**Проверяемые последствия:** +- Сообщение об ошибке в UI отображает Request ID и Trace ID, пригодные для обращения в поддержку. +- Browser telemetry полностью отключаема и остаётся внутри настроенного контура. + +#### FR-31: Telemetry resilience + +Очереди telemetry bounded; export failures, drops и saturation измеряются; graceful shutdown завершает принятые requests и flushes telemetry в пределах timeout. + +**Проверяемые последствия:** +- Отказ GlitchTip/OTLP/Prometheus не изменяет product response и readiness после успешного startup. +- Явно неверная telemetry configuration приводит к безопасной startup error. +- Disk-backed bounded spool переживает restart, имеет квоты/eviction policy и не может исчерпать storage продукта; drops и eviction создают Telemetry Loss Record и alert. +- Production spool capacity покрывает 30 часов trace generation при 100 RPS Reference Workload плюс один 250 RPS/5-minute burst; гарантированный outage envelope равен 24 часам, после чего остаётся replay/headroom. Outage сверх envelope является SLO incident, а не разрешением отбросить trace бесшумно. + +### 4.6 Технические и бизнес-метрики + +#### FR-32: Технические метрики + +Prometheus получает low-cardinality metrics по traffic, error, duration, saturation, queues/workers, DB/cache, MCP sessions, Tools/Resources/Prompts/Tasks и telemetry health. + +**Проверяемые последствия:** +- Trace ID, URL, workspace/user/Agent/Operation IDs и error text запрещены в labels. +- Histograms позволяют вычислять SLO и имеют документированные bounded buckets. + +#### FR-33: Бизнес-метрики + +Crank локально считает activation и adoption events: создание/публикация capabilities, import outcome, Agent binding, first successful MCP call, active Agent, capability usage и Load Run outcome. + +**Проверяемые последствия:** +- **Решение A-8:** DAU определяется как уникальный Agent с хотя бы одним валидным MCP request за UTC-день; UI-admin activity показывается отдельно и не смешивается с Agent DAU. +- Product metrics не покидают установку без явной opt-in настройки. + +#### FR-34: Prometheus и Grafana integration + +Community distribution предоставляет готовые scrape config, recording/alert rules, provisioned datasource и versioned Grafana dashboards. + +**Проверяемые последствия:** +- Dashboards покрывают Overview, MCP/runtime, upstream, Tasks/queues, DB/cache, business funnel и Load Runs. +- Metrics listener вне loopback требует отдельной authentication и не использует admin и MCP credentials. + +#### FR-35: SLO и error budgets + +Grafana отображает availability, latency-under-threshold, successful execution и Task deadline SLO с 30-дневным окном и fast/slow burn alerts. + +**Проверяемые последствия:** +- SLO исключения и denominator документированы; upstream/client/schema errors не маскируют product-caused failures. +- Alert ведёт к конкретному runbook и панели диагностики. +- Решение 2026-09-13: доставка application alerts выполняется через self-hosted Apprise API, без Python runtime внутри Rust-приложения. Каналы и получателей настраивает оператор; отправка вне закрытого контура требует явного opt-in. Credentials каналов являются secrets, payload проходит redaction. +- Общая граница уведомлений provider-neutral: приложение и alert evaluator используют единый versioned message contract и логический recipient/route reference, а не Apprise URLs, tags или response codes. Apprise — первый сменный delivery adapter. Замена поставщика требует только нового adapter и configuration/secret bindings, без переписывания producers, alert rules, UI и общих retry/redaction policies; перенос provider-specific destination configuration допускается. Для проверки заменяемости достаточно второго test adapter, не новой production-интеграции. +- Crank отвечает за ошибки/latency своих API и MCP/runtime, Tasks/queues, потерю telemetry и нарушения application SLO. Мониторинг хостов/LXC/VM, дисков, сети, инфраструктурных PostgreSQL/cache и внешняя проверка полной недоступности Crank — ответственность владельца инфраструктуры. Crank диагностирует влияние отказа зависимости на собственные операции, но не управляет устранением инфраструктурной причины; эта граница не отменяет fail-closed, recovery tests или согласованные правила SLI accounting. +- Уведомления имеют firing/resolved lifecycle, grouping/deduplication, ограниченную частоту повторов и bounded retry. Отказ Apprise/канала не блокирует product requests/readiness, не создаёт рекурсивную рассылку и виден локально; API acceptance не считается доказательством прочтения получателем. + +### 4.7 Встроенное нагрузочное тестирование + +**Описание:** UI позволяет безопасно запускать воспроизводимые нагрузочные проверки и видеть, выдерживает ли Crank заявленный профиль. Генератор отделён от измеряемых сервисов, чтобы не скрывать saturation. + +#### FR-36: Scenario и профиль нагрузки + +Администратор выбирает опубликованные Tools и задаёт mix, test data, RPS или VU, duration, ramp и thresholds. + +**Проверяемые последствия:** +- Scenario версионируется; итоговый Run хранит точную версию параметров и capabilities. +- Credentials ссылаются на Auth Profile и не копируются в Scenario/report. +- Operation Version должна быть явно помечена `load-test-safe`; флаг выключен по умолчанию и содержит классификацию side effects и разрешённый test environment. + +#### FR-37: Оценочный DAU-профиль + +UI преобразует DAU в arrival profile только при заданных actions per session, sessions per user per day, activity window, think time и scenario mix. + +**Проверяемые последствия:** +- UI явно показывает все допущения и получившийся RPS curve. +- Одно число DAU никогда не выдаётся за точную нагрузочную модель. + +#### FR-38: Безопасность запуска + +Load Run имеет RBAC-equivalent admin restriction, target allowlist, configurable hard limits, confirmation, emergency stop и запрет production targets по умолчанию. + +**Проверяемые последствия:** +- **Решение A-9:** Community разрешает тестирование только опубликованных capabilities текущей установки; произвольный URL не является target. +- Write/destructive capability требует sandbox endpoint, отдельный test Auth Profile, per-run quota и operator-defined cleanup; иначе встроенный Load Run его отклоняет. +- Production mode требует отдельного operator flag и повторного подтверждения impact. +- Emergency stop использует независимый control path и прекращает новые dispatches даже при насыщении основного API/worker pool. +- Встроенный runner имеет неотключаемый абсолютный ceiling: 1 000 RPS, 512 concurrent VUs, 2 часа и 10 000 000 iterations на Run; оператор может только понижать пределы. Большая нагрузка запускается внешним инструментом вне product UI. +- Run lease требует heartbeat; при его потере новые dispatches прекращаются автоматически. Независимый local-operator kill switch и reserved control capacity входят в Release Gate; их недоступность запрещает Start. + +#### FR-39: Live execution и stop + +UI показывает generation rate, completed/failed, latency percentiles, active workers, dropped iterations, queue wait и saturation; пользователь может безопасно остановить Run. + +**Проверяемые последствия:** +- Dropped iterations отделены от product failures. +- Stop прекращает новую нагрузку, дожидается или отменяет in-flight согласно выбранной политике. + +#### FR-40: Отчёт и история + +Load Run завершается immutable summary с pass/fail thresholds, environment fingerprint, release/version, графиками и ссылками на Grafana/traces. + +**Проверяемые последствия:** +- Отчёт экспортируется в machine-readable и human-readable format. +- UI сравнивает Runs одного Scenario между релизами и показывает regression. +- Preview, event и report limits сохраняют валидный UTF-8/JSON; сериализованные данные не обрезаются произвольным byte slice. + +### 4.8 Self-hosted production deployment + +#### FR-41: Deployment profiles + +Community поставляет minimal и production profiles. Minimal сохраняет функциональность без полного observability stack; production включает все компоненты, необходимые для Release Gate. **Решение A-10:** Prometheus, Grafana и GlitchTip предоставляются как optional production profile, но могут быть заменены внешними endpoints. + +**Проверяемые последствия:** +- Оба профиля валидируются в CI и документируют resource budgets. +- Production profile запускается одной документированной командой без обращения к proprietary service. +- Весь обязательный public-launch scope работает без платной лицензии, premium feature gate или обязательного коммерческого backend; лицензии bundled-компонентов проверены и раскрыты. +- Production profile фиксирует per-service CPU/RAM, disk/IOPS, network, DB/Valkey connection limits и минимальный 30% capacity headroom на Reference Workload. +- Non-loopback production exposure использует TLS; trusted proxies заданы явным allowlist, а forwarded headers от недоверенного peer игнорируются. +- Admin session cookies имеют `Secure`, `HttpOnly` и подходящий `SameSite`; state-changing browser requests защищены от CSRF, CORS по умолчанию запрещает чужие origins, session rotation/expiry и security headers проходят E2E negative tests. + +#### FR-42: Закрытый контур + +Все capabilities, telemetry и product metrics работают без исходящего cloud dependency; outbound доступ разрешается только к явно настроенным upstream и registries во время установки/обновления. + +**Проверяемые последствия:** +- Runtime не отправляет usage или diagnostics наружу по умолчанию. +- Offline installation/upgrade path документирован и проверен. +- Offline bundle подписан и содержит digest-pinned images, Compose/config, SBOM, licenses и документацию; install/upgrade test проходит при запрещённой внешней сети. + +#### FR-43: Upgrade, backup и recovery + +Администратор получает versioned migrations, preflight, backup/restore, rollback guidance и совместимый rolling/restart upgrade path. + +**Проверяемые последствия:** +- Выпущенный baseline остаётся immutable; каждая новая migration имеет собственный checksum, последовательно и транзакционно применяется под PostgreSQL advisory lock. +- Expand/migrate/contract и fresh/already-migrated paths проходят integration tests и сохраняют совместимость rolling update/rollback window. +- PostgreSQL, artifact/config state и защищённое master-key material восстанавливаются как согласованный backup set. +- Recovery gate завершается реальным MCP-вызовом Operation с зашифрованным Auth Profile после restore, а не только успешным startup UI/schema. +- Backup manifest связывает snapshot timestamp, PostgreSQL WAL LSN, artifact checksums, config digest и versioned reference на отдельно защищённый master-key backup; сам key material в manifest отсутствует. +- RPO/RTO измеряются от fault injection до проверенного MCP-вызова в трёх последовательных restore runs; gate включает restore старого key, re-encryption на новый key и отзыв старого key без потери secrets. +- Community upgrade использует single-instance drain/restart contract: новые claims останавливаются, in-flight/queued Tasks сохраняются, а N/N-1 schema и Task envelope читаются до завершения rollback window. +- Rolling multi-instance upgrade не заявляется; rollback sequence проверяет downgrade приложения без обратной destructive migration. + +#### FR-44: Container hardening + +Production containers используют non-root user, минимальные privileges, health/readiness, graceful shutdown, resource limits, log rotation guidance и compatible read-only filesystem где возможно. + +**Проверяемые последствия:** +- По результатам сканирования production images не содержат реальных Critical/High vulnerabilities; подтверждённый false positive требует воспроизводимого evidence, но risk acceptance не заменяет исправление. +- Secret values не попадают в image, environment dumps или diagnostics bundle. + +#### FR-45: Единый конфигурационный контракт + +Документация, environment examples, Compose profiles, runtime parser и UI отражают один набор поддерживаемых параметров. + +**Проверяемые последствия:** +- CI обнаруживает documented-but-unused и parsed-but-undocumented production parameters. +- Legacy root Compose не расходится с canonical Community deployment. + +### 4.9 Всесторонняя проверка и выпуск + +#### FR-46: Автоматизированная test pyramid + +Каждый capability имеет unit, contract/integration и применимый real-stack E2E уровень; security boundaries покрыты negative tests. + +**Проверяемые последствия:** +- Bug fix начинается с воспроизводящего regression test. +- CI выполняет Rust quality gates, dependency/license policy, UI build/audit, Playwright, deployment validation и authenticated product smoke. +- До feature freeze создаётся versioned inventory всех существующих UI/API/MCP flows; каждый flow связан с сохраняемым контрактом, автоматизированным или ручным regression evidence и owner при пробеле. +- Capability Inventory утверждается до оценки feature work и становится входом для эпиков, regression checklist и Evidence Manifest. + +#### FR-47: Полный ручной regression pass + +Перед Release Candidate выполняется versioned manual checklist на production-like deployment с evidence по каждому пользовательскому пути. + +**Проверяемые последствия:** +- Pass охватывает UI, OpenAPI import, lifecycle, MCP capabilities, approvals, Tasks, observability, Load Runs, backup/restore и upgrade. +- Blocked/not-run не считается pass; найденный defect связан с regression evidence. + +#### FR-48: Compatibility matrices + +Release проверяется по OpenAPI corpus, MCP protocol/client matrix, PostgreSQL/Valkey modes и supported browser matrix. + +**Проверяемые последствия:** +- **Решение A-11:** UI поддерживает актуальные stable Chromium, Firefox и WebKit; MCP matrix включает не менее трёх representative clients плюс protocol-level harness. +- Матрица и исключения публикуются рядом с release notes. + +#### FR-49: Performance, soak и recovery tests + +Release pipeline или управляемый pre-release pipeline выполняет baseline/load/stress, 72-hour soak, restart/recovery и dependency-failure scenarios. + +**Проверяемые последствия:** +- Результаты привязаны к commit/image digest и Reference Deployment. +- Regression против принятого baseline блокирует выпуск до анализа и решения. +- 72-hour soak является pre-release qualification, но не доказательством 30-дневного SLO; до Хабра RC проходит 30-дневный supervised burn-in, ускоренная замена которому не допускается. + +#### FR-50: Security release evidence + +Перед public launch выполняются threat-model review, dependency/container scan, secret/redaction audit, SSRF/authz/idempotency negative tests и review новых attack surfaces Tasks/Resources/Load Runs. + +**Проверяемые последствия:** +- Critical/High security findings равны нулю. +- Gate использует зафиксированные версии SAST/dependency/container/secret/license scanners и freshness window ≤24 часов для RC; подтверждённый false positive требует evidence, но risk acceptance для реального Critical/High запрещён. +- Medium findings имеют owner, mitigation и срок; release blocker определяется threat impact. + +#### FR-51: Документация и runbooks + +Пользователь получает quickstart, production deployment, capability guides, compatibility matrix, limits, troubleshooting, metrics catalog, dashboards, SLO alerts, backup/restore и incident runbooks. + +**Проверяемые последствия:** +- Документация проверяется на fresh environment человеком, не участвовавшим в реализации соответствующего flow. +- Каждый critical alert имеет диагностические и recovery steps. + +#### FR-52: Release Candidate + +Команда создаёт immutable RC artifact и выполняет все product, migration, deployment, manual и non-functional проверки именно на нём. + +**Проверяемые последствия:** +- После начала RC допускаются только исправления blocker defects с повтором затронутых и обязательных gates. +- Финальный artifact имеет тот же digest, что и RC artifact, прошедший Release Gate. +- Evidence Manifest содержит digests RC/images/offline bundle, Reference Workload version/checksum, redacted environment/config, команды, timestamps, raw-result locations, pass/fail, reviewer и подпись владельца gate. +- Manifest соответствует versioned JSON Schema; CI verifier отклоняет отсутствующее evidence, неверный digest/signature, истёкший freshness window или ссылку на изменяемый result artifact. + +#### FR-53: Публичная readiness-страница + +Перед анонсом публикуется честное описание supported scope, limits, security model, compatibility и известных non-blocking issues. + +**Проверяемые последствия:** +- Маркетинговое утверждение не шире доказанной matrix. +- Community limitations не скрыты за общим словом production-ready. + +#### FR-54: Habr Release Gate + +Публикация на Хабре разрешена только при одновременном выполнении всех условий §9 и §10. + +**Проверяемые последствия:** +- Gate вычисляется из принятого evidence по FR-1—FR-53 и SM-2—SM-10; FR-54 не доказывает сам себя. +- Gate имеет датированный подписанный Evidence Manifest со ссылками на immutable evidence. +- Исключение для Critical/High defect, невыполненного SLO, отсутствующей обязательной capability или неполного manual pass запрещено. +- Расширение Community scope для Resources, Prompts, Tasks и Load Runs одновременно обновляет Community docs, `project-context.md`, executable scope checks и их tests; локальный allow-marker не заменяет contract change. + +## 5. Сквозные нефункциональные требования + +### 5.1 Reference Deployment и масштаб + +**Решение A-12:** Reference Deployment — Linux x86_64; Crank services, PostgreSQL 16 и Valkey 8 используют 4 vCPU и 8 GiB RAM; load generator работает на отдельном хосте эквивалентной мощности. Полный observability profile размещается отдельно и имеет собственный документированный budget, чтобы не искажать capacity Crank. + +Reference Deployment использует SSD не менее 100 GB, 3 000 sustained IOPS, 100 MB/s и сеть 1 Gbit/s. Production profile фиксирует CPU/RAM limits каждого сервиса, PostgreSQL/Valkey connection limits и доказывает не менее 30% CPU/RAM/disk headroom при Reference Workload. + +**Reference Workload v1:** + +- Versioned artifact и seed dataset с checksum: 2 000 Operations, 200 Agents, 500 active keys, 1 000 000 Invocation History records и 10 000 queued Tasks. +- Capacity mix: 50% synchronous `tools/call`, 15% Task enqueue, 10% Task status/cancel, 10% `resources/read`, 5% `prompts/get`, 5% MCP discovery/list и 5% Admin Logs/Usage. +- Background execution profile поддерживает 128 active Tasks с duration p50 1 с, p95 30 с, p99 5 минут, смешивает read и idempotent write Operations и удерживает до 10 000 queued Tasks. +- При steady-state arrival rate не выше доказанной service rate queue wait p95 ≤5 секунд и oldest-task age ≤30 секунд; после остановки overload profile backlog 10 000 Tasks полностью дренируется ≤60 минут без потери или duplicate terminal outcome. +- Payload profile: request p50 1 KiB, p95 32 KiB, max 256 KiB; response p50 4 KiB, p95 64 KiB, max 1 MiB. +- Capacity upstream: latency p50 20 мс, p95 100 мс, p99 250 мс; 1% контролируемых upstream outcomes 4xx/5xx/timeouts для проверки классификации. +- Latency-baseline upstream: фиксированные 10 мс, уникальные inputs, response cache выключен; platform overhead измеряется отдельно от upstream wait. +- Production telemetry mode: 100% trace generation, Prometheus metrics и browser/server/background correlation включены. +- Все параметры, версии images/config и фактическая topology записываются в Evidence Manifest; изменение workload создаёт новую версию и новый baseline. +- Upgrade/recovery variant останавливает новые claims, даёт active workers 30 секунд на checkpoint, перезапускает сервис и требует возобновить eligible Tasks ≤60 секунд без потери queue или stale-worker terminal commit. + +- **NFR-P1:** 100 RPS смешанного MCP/runtime workload в течение 30 минут и 250 RPS burst в течение 5 минут без нарушения SLO. +- **NFR-P1a:** в каждую минуту 250 RPS burst product-caused success ratio ≥99,95%, p95/p99 platform overhead остаются в NFR-P4, а saturation rejection ≤0,1%; 30-дневное усреднение не может скрыть burst failure. +- **NFR-P1b:** в каждую минуту 100 RPS steady Run product-caused success ratio ≥99,95%, p95/p99 остаются в NFR-P4, queue wait/age сохраняют установленную границу и saturation rejection ≤0,1%. +- **NFR-P2:** не менее 128 одновременно исполняемых synchronous/background Executions и 10 000 queued Tasks без unbounded resource growth. +- **NFR-P3:** Reference Deployment поддерживает 2 000 Operations, 200 Agents, 500 active keys и 1 000 000 записей Invocation History без функциональной деградации. +- **NFR-P4:** добавочная задержка Crank при stub upstream ≤50 мс p95 и ≤150 мс p99; catalog/resource/prompt discovery ≤150 мс p95. +- **NFR-P5:** основные UI-экраны становятся интерактивными ≤2 с p95 на локальной сети при Reference Deployment и production-size dataset. + +### 5.2 Надёжность и восстановление + +- **NFR-R1:** product-caused successful-request ratio ≥99,95% на Reference Workload; control-plane availability ≥99,9% за 30-дневное окно, исключая документированное обслуживание. +- **NFR-R2:** ноль потерянных подтверждённых configuration changes, Published Versions, approvals и accepted Tasks при штатном или аварийном restart с исправным durable storage. +- **NFR-R3:** graceful shutdown прекращает приём новых requests, завершает или надёжно сохраняет принятые работы и укладывается в 30 секунд по умолчанию. +- **NFR-R4:** для disaster restore production profile использует проверяемый WAL/PITR path с RPO ≤5 минут и RTO ≤30 минут на Reference Deployment; фактическая гарантия зависит от доступности operator-provided backup storage. +- **NFR-R5:** Task начинает выполнение ≤5 секунд p95 при нагрузке в пределах NFR-P1; recovery зависших leases после restart ≤60 секунд. + +**Исполняемые SLI:** + +- **Control-plane availability:** доля good one-minute intervals за окно. В каждой минуте synthetic probe выполняется не реже раза в 10 секунд; минута без probe evidence считается bad. В good minute отсутствуют Crank-caused 5xx, timeout и data-integrity failure; не менее 99% валидных авторизованных requests завершаются одним из предусмотренных outcomes. В 30-дневном pre-launch burn-in maintenance не исключается; post-launch заранее опубликованные exclusions ограничены суммарно 30 минутами за 30 дней. Overload при входящей нагрузке в пределах NFR-P1 считается failure. +- **Execution reliability:** accepted Executions без Crank-caused failure, потери или неопределённого внутреннего состояния, делённые на все accepted Executions. Корректно переданные upstream/client/schema outcomes считаются handled и измеряются отдельными outcome metrics. +- **Latency-under-threshold:** доля eligible events, у которых измеренный platform overhead в Latency-baseline workload не превышает NFR-P4; UI SLI отдельно применяет NFR-P5. +- **Task deadline:** accepted Tasks, достигшие terminal `completed` либо корректного `failed` state в пределах configured execution deadline без Crank-caused failure, делённые на все accepted Tasks, кроме явно отменённых клиентом до claim. `input-required` не является успехом: user-wait clock приостанавливается не более configured input TTL, а transition latency измеряется отдельно. +- **Trace delivery latency:** generated traces, появившиеся в GlitchTip в течение 60 секунд при здоровом backend, делённые на все generated traces. **Trace eventual completeness:** доля traces, доставленных в течение 25 часов при backend outage не более 24 часов; любой Telemetry Loss Record считается failure. +- Для каждого denominator Evidence Manifest фиксирует outcome taxonomy, exclusions и raw counts. 30-дневный gate требует не менее 1 000 000 synthetic eligible events с capability mix Reference Workload в пределах ±2 процентных пунктов; availability probes в этот объём не входят. При меньшем объёме фактического post-launch traffic SLO публикуется как `insufficient volume`, а не как pass. + +### 5.3 Безопасность и приватность + +- **NFR-S1:** default deny для workspace/Agent/capability access; чужой объект не раскрывает metadata. +- **NFR-S2:** секреты зашифрованы at rest, не возвращаются после создания/ротации и исключены из logs, traces, metrics, reports и exports. +- **NFR-S3:** outbound policy применяется после DNS resolution на каждом соединении; redirects и system proxy выключены по умолчанию. +- **NFR-S4:** bounded input, body, response, concurrency, queue и cardinality limits предотвращают неограниченное накопление ресурсов. +- **NFR-S5:** production release не содержит известных Critical/High vulnerabilities или Critical/High findings. +- **NFR-S6:** никакая usage/telemetry информация не покидает закрытый контур без явной opt-in конфигурации администратора. +- **NFR-S7:** недоступный mandatory coordination/cache/approval/idempotency store переводит зависимый safety path в fail-closed состояние; safety-механизм никогда не отключается молча. +- **NFR-S8:** previews, events, diagnostics и JSON reports ограничиваются с сохранением валидного UTF-8/JSON и проходят oversized/malformed negative tests. + +### 5.4 Наблюдаемость + +- **NFR-O1:** 100% входящих UI/Admin API/MCP requests имеют отдельные Request ID и Trace ID; невалидный входящий Request ID заменяется UUIDv7; 100% Execution/Task records сохраняют оба идентификатора. +- **NFR-O2:** production profile генерирует 100% traces; Trace delivery latency SLI ≥99,99%, Trace eventual completeness = 100% за 25 часов при outage ≤24 часов, а каждый Telemetry Loss Record нарушает SLO и создаёт bounded-spool accounting/alert. +- **NFR-O2a:** capacity test сериализует фактический p95 trace size и доказывает 30-hour spool capacity/24-hour outage envelope в выделенном disk budget без eviction и влияния на PostgreSQL/artifact safety reserve. +- **NFR-O3:** observability overhead ≤5% p95 latency и ≤10% CPU на Reference Deployment относительно telemetry-disabled baseline. +- **NFR-O4:** метрики не создают series из пользовательских identifiers или произвольных значений; traces связываются через exemplars/deep links. +- **NFR-O5:** redaction имеет negative regression tests для headers, cookies, query, JSON, YAML, errors, browser events и Load Run artifacts. + +### 5.5 Совместимость и сопровождение + +- **NFR-C1:** Rust MSRV, Edition, workspace boundaries и публичные wire-контракты изменяются только отдельным совместимым change. +- **NFR-C2:** latest stable MCP на feature freeze и две поддерживаемые предшествующие версии проходят protocol matrix. +- **NFR-C3:** breaking change требует versioning/deprecation note и migration path; Published Version остаётся неизменяемой. +- **NFR-C4:** RU и EN получают новый пользовательский текст одновременно. + +## 6. Ограничения и guardrails + +### 6.1 Community scope + +- Один self-hosted deployment, один workspace и один администратор. +- REST является единственным upstream protocol target этого релиза. +- Static Agent keys и отдельные approval keys сохраняются; полноценные команды/RBAC/SSO не добавляются. +- PostgreSQL обязателен и является source of truth для Tasks, approvals, idempotency и durable safety state. Valkey ускоряет coordination/queues/cache, но остаётся rebuildable: PostgreSQL-only mode сохраняет корректность с меньшим throughput, Valkey-assisted mode проходит recovery после полной потери Valkey. Если безопасный PostgreSQL fallback невозможен для конкретного пути, он fail closed. +- Resources, Prompts, Tasks и Load Runs являются намеренным расширением прежней Community-границы; release обязан обновить её документацию и executable guardrails, не ослабляя остальные ограничения. + +### 6.2 Data governance + +- Все данные, traces, metrics и reports принадлежат оператору установки. +- Retention конфигурируется раздельно для Invocation History, Tasks, Load Runs, traces, errors и metrics. +- Удаление/архивация не нарушает auditability Published Versions и release evidence. + +### 6.3 Safety + +- Load Run, external references и динамические Resources наследуют outbound/SSRF policy. +- Retry и recovery не скрывают неопределённый side effect. +- Наблюдаемость fail-open для product request после успешного startup, но telemetry loss не остаётся бесшумной. + +## 7. Явные non-goals + +- Managed/SaaS-хостинг Crank. +- Multi-workspace, команды, приглашения, fine-grained RBAC, SSO/SAML/OIDC для Admin UI. +- Преобразование GraphQL, gRPC, SOAP/WSDL или произвольного пользовательского кода. +- Произвольный distributed load-testing service или атака на внешние targets. +- Обещание exactly-once для внешнего side effect без idempotency contract upstream. +- Обязательная поддержка experimental MCP extension как production contract до его стабилизации. +- Внешняя продуктовая аналитика или phone-home telemetry по умолчанию. + +## 8. Scope production-релиза + +### 8.1 Обязательно до публичного запуска + +- Hardening всех существующих flows и устранение расхождений code/docs/UI/runtime config. +- Production-grade OpenAPI importer и regression corpus. +- MCP Tools, Resources, Prompts и применимые современные server capabilities. +- Durable background Tasks, concurrency/backpressure, recovery и UI operations. +- Сквозной Trace ID в UI и GlitchTip, browser/server/background correlation. +- Технические и бизнес-метрики, Prometheus/Grafana dashboards, SLO и alerts. +- Встроенные безопасные Load Runs с RPS/VU/DAU, history и reports. +- Hardened minimal/production deployment profiles, offline path, backup/restore/upgrade. +- Полные automated/manual/performance/soak/recovery/security gates и документация. + +### 8.2 После публичного запуска + +Только улучшения, не перечисленные выше и не необходимые для выполнения FR/NFR. Ни одна обязательная capability не переносится после Хабра ради даты. + +## 9. Последовательность достижения готовности + +1. **Baseline Frozen:** утверждены Capability Inventory, Reference Workload, outcome taxonomy и начальный Evidence Manifest; только после этого оценивается feature work. +2. **Feature Complete:** реализованы FR-1—FR-45, устранены Critical/High функциональные defects, документация синхронизирована. +3. **Quality Complete:** выполнены FR-46—FR-51, закрыты regression corpus и compatibility matrices, пройдены SLO/performance/security требования. +4. **Release Candidate:** immutable artifact проходит полный manual pass, 72-hour soak, upgrade/restore, observability и production deployment проверки. +5. **Public Ready:** тот же RC проходит 30-дневный supervised burn-in с 1 000 000+ eligible events; выполнены SM-1—SM-10, нет blocker/open items, опубликована readiness-страница. +6. **Habr Launch:** разрешается в соответствии с FR-54; дата выбирается после достижения Public Ready. + +## 10. Метрики успеха и Release Gate + +### 10.1 Primary gate metrics + +- **SM-1 — Scope completeness:** для 100% FR-1—FR-53 и элементов утверждённого Capability Inventory принято evidence; обязательные capabilities не скрыты feature flag, а применимые stable MCP capabilities не имеют статуса `deferred`. +- **SM-2 — Automated quality:** 100% обязательных CI suites проходят на RC artifact; flaky mandatory tests = 0. +- **SM-3 — Manual quality:** 100% manual checklist выполнено на production profile; not-run/blocked = 0. +- **SM-4 — Defects:** количество открытых product и security defects уровня Critical или High равно нулю; defects уровня Medium имеют owner и не нарушают SLO, целостность данных или безопасность. +- **SM-5 — Performance:** NFR-P1—NFR-P5 выполнены на Reference Workload v1 в трёх последовательных воспроизводимых Runs; regression >10% против принятого baseline объяснён и одобрен либо исправлен. +- **SM-6 — Reliability:** 72-hour qualification и последующий 30-дневный burn-in с Reference Workload mix ±2 п.п. проходят без data loss, deadlock, unbounded growth или нарушения исполняемых SLI; probes не засчитываются в 1 000 000 events, restart/partition/recovery matrix проходит полностью. +- **SM-7 — Traceability:** 100% e2e flows имеют одинаковый Trace ID в UI history; Trace delivery latency ≥99,99% и eventual completeness = 100% в 30-дневном burn-in; outage injection создаёт alert и завершает replay без оставшегося Telemetry Loss Record. +- **SM-8 — OpenAPI quality:** normative support matrix и corpus содержат не менее 50 репрезентативных спецификаций и обязательный E2E `openapi.yaml` upload path; ≥95% Operations импортируются в actionable Draft без blocker finding, каждая конструкция в corpus соответствует expected semantics либо получает явный unsupported finding, silent loss относительно support matrix = 0. +- **SM-9 — MCP compatibility:** feature inventory охватывает 100% capabilities/extensions официальной stable specification; latest stable + две предыдущие поддерживаемые версии и не менее трёх representative clients проходят опубликованную matrix. +- **SM-10 — Deployment и бесплатность:** fresh install, upgrade с предыдущего Community release, WAL/PITR backup/restore и offline procedure проходят на документированном production profile; весь обязательный scope доступен без платной лицензии или обязательного коммерческого backend. + +### 10.2 Post-launch product metrics + +- **SM-11 — Time to first value:** медиана от первого входа до первого успешного MCP Tool call ≤15 минут среди завершивших onboarding. +- **SM-12 — Import activation:** ≥70% импортов без blocker findings доходят до публикации хотя бы одной Operation в течение 24 часов. +- **SM-13 — Agent activation:** ≥80% опубликованных Agents получают первый успешный MCP request в течение 24 часов. +- **SM-14 — Execution quality:** product-caused failure ratio <0,05% по формуле Execution reliability на Reference Workload; upstream/client/schema outcomes отображаются отдельно. +- **SM-15 — Capability adoption:** Usage раздельно показывает активные Tools, Resources, Prompts и Tasks без отправки данных наружу. + +### 10.3 Counter-metrics + +- **SM-C1 — Не жертвовать безопасностью ради throughput:** performance target не считается достигнутым при ослаблении authz, SSRF, redaction, confirmation или idempotency. +- **SM-C2 — Не жертвовать корректностью импорта ради success rate:** документ с silent semantic loss считается failure, даже если Operations созданы. +- **SM-C3 — Не жертвовать стабильностью ради MCP novelty:** experimental extension не заменяет stable fallback. +- **SM-C4 — Не жертвовать ресурсами ради 100% traces:** превышение observability budget NFR-O3 блокирует production default и требует оптимизации/configuration evidence. +- **SM-C5 — Не превращать DAU в vanity metric:** Agent DAU не заменяет successful outcomes, latency и reliability. + +## 11. Основные риски и смягчение + +- **Scope breadth:** одновременное hardening и добавление современных MCP capabilities, background Tasks, встроенного load testing и полного observability profile может затянуть готовность. Смягчение: последовательность Feature Complete → Quality Complete; ни один cluster не объявляется готовым без vertical evidence. +- **Изменчивость MCP:** protocol и Tasks extension меняются. Смягчение: capability negotiation, compatibility adapters, stable core и executable matrix. +- **OpenAPI variability:** стандарт допускает огромную поверхность. Смягчение: explicit support matrix, corpus, no-silent-loss policy и findings. +- **Background side effects:** retry/recovery способен повторить внешний write. Смягчение: честная at-least-once семантика, idempotency fingerprint, outcome-unknown и operator-visible attempts. +- **Load runner abuse:** встроенная нагрузка может стать SSRF/DoS механизмом. Смягчение: published-capability targets, hard limits, отдельный profile, confirmation и emergency stop. +- **Observability volume:** 100% traces увеличивают CPU/storage. Смягчение: измеримый overhead budget, configurable retention/sampling, telemetry-loss metrics и local-first defaults. +- **Утраченный продуктовый контекст:** часть прежних решений недоступна. Смягчение: этот PRD, memlog, addendum, executable contracts и последующее review становятся новой канонической базой. + +## 12. Deferred decisions и reviewer dispositions + +На текущем этапе phase-blocking вопросов нет: пользователь делегировал решения Fast path. До указанных ниже стадий необходимо определить четыре значения, зависящие от внешнего состояния: + +### 12.1 Deferred decisions + +1. Какая MCP-версия является latest stable на дату feature freeze? **Владелец:** Product + Architecture. **Пересмотр:** непосредственно перед утверждением Capability Inventory; статус применимых stable capabilities блокирует Baseline Frozen. +2. Какие три representative MCP clients актуальны на дату RC? **Владелец:** Product + QA. **Пересмотр:** при утверждении MCP client archetypes до feature freeze и повторно при создании RC. +3. Подтверждают ли benchmark результаты Reference Deployment или требуют корректировки targets до фиксации release baseline? **Владелец:** Performance QA + Architecture. **Пересмотр:** после первого полного Reference Workload run; изменение target требует memlog decision до Baseline Frozen. +4. Какой фактический retention помещается в документированный storage budget production profile? **Владелец:** SRE + Architecture. **Пересмотр:** после измерения p95 serialized telemetry/history size; решение блокирует production profile capacity evidence. + +Эти вопросы не разрешают ослабить публичный Release Gate; изменения фиксируются в memlog и PRD. + +### 12.2 Reviewer dispositions + +Неблокирующие reviewer findings из `review-rubric.md`, `review-adversarial-general.md`, `review-operability-security.md` и `review-edge-cases.md` передаются Architecture/QA. До Baseline Frozen каждый finding должен получить отдельный disposition: закрыт изменением requirement, architecture или test; принят как non-goal с обоснованием; либо повышен до blocker. Массовое принятие без разбора запрещено. + +## 13. Реестр подтверждённых решений + +Решения A-1—A-12 были первоначально сформулированы в Fast path и подтверждены пользователем без изменений 2026-08-03. + +- **A-1 (§1):** публичный анонс зависит от Release Gate, а не календарной даты. +- **A-2 (§2.4):** пользовательские пути восстановлены без отдельного UX-исследования. +- **A-3 (FR-8):** XML payloads не реализуются, но диагностируются явно. +- **A-4 (FR-13):** latest stable MCP + две предыдущие поддерживаемые версии; experimental отдельно. +- **A-5 (FR-16):** динамический REST-backed Resource входит в public scope. +- **A-6 (FR-23):** Tasks имеют at-least-once delivery и effectively-once только при idempotency. +- **A-7 (FR-29):** default 100% trace sampling/7 дней; errors ≥30 дней; всё конфигурируется. +- **A-8 (FR-33):** DAU — уникальный активный Agent за UTC-день. +- **A-9 (FR-38):** Load Run target — только опубликованные capabilities текущей установки. +- **A-10 (FR-41):** bundled observability предоставляется optional production profile с внешними endpoint alternatives. +- **A-11 (FR-48):** три актуальных browser engines и не менее трёх representative MCP clients. +- **A-12 (§5.1):** Reference Deployment — 4 vCPU, 8 GiB RAM, SSD, PostgreSQL 16, Valkey 8 и отдельный load generator. diff --git a/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/reconcile-project-context.md b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/reconcile-project-context.md new file mode 100644 index 0000000..c5971c1 --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/reconcile-project-context.md @@ -0,0 +1,97 @@ +# Reconciliation: project-context.md ↔ PRD Crank Community Production Readiness + +## Охват + +Источник: `_bmad-output/project-context.md` (status `complete`, 152 правила, 2026-08-02). + +Целевые артефакты: + +- `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md`; +- `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md`. + +Проверены границы Community, safety/security-инварианты, observability, миграции и восстановление, UI-корректность, testing/release guardrails и технические ограничения Rust/JavaScript. Детали реализации, которые не меняют продуктовый контракт, не считались обязательными для дублирования в PRD, но должны остаться обязательным project context при декомпозиции и реализации. + +## Вердикт + +PRD хорошо сохраняет большинство критических продуктовых и safety-инвариантов, но до Final PRD нужно устранить один явный конфликт scope и четыре недостаточно явных качественных ограничения. Ни один из gaps не отменяет согласованную продуктовую цель; они уточняют безопасный путь к ней. + +## Главные gaps + +### G1 — Расширение Community scope конфликтует с действующим executable guardrail + +**Уровень: Critical для планирования, не блокирует саму продуктовую цель.** + +`project-context.md` определяет Community как REST-source MCP Tools + simple admin auth + Agent keys + single self-hosted deployment + PostgreSQL + optional Valkey/Redis и обязывает `scripts/check-community-scope.sh` запрещать выход за эту границу. PRD намеренно добавляет Resources, Prompts, durable Tasks и Load Runs. Это согласованно с пользователем, поэтому ошибочно сужать PRD обратно; однако и обходить проверку локальными exceptions тоже нельзя. + +**Что добавить:** в FR-54/Release Gate или в §6.1 зафиксировать, что расширение Community scope — отдельное намеренное contract change, которое одновременно обновляет Community docs, `project-context.md`, `check-community-scope` и его tests. Сохранить прежние non-goals: без multi-workspace, teams/RBAC/SSO, managed SaaS и новых upstream protocols. Не считать `community-scope: allow` заменой этого решения. + +### G2 — Migration contract недоопределён, а RPO=0 не подкреплён моделью recovery + +**Уровень: High.** + +FR-43 требует versioned migrations, fresh/already-migrated tests, rollback guidance и согласованный backup PostgreSQL + artifacts/config. Но он не сохраняет критичную исходную особенность: текущий runner имеет immutable baseline v1, а любая новая schema должна идти новой immutable migration с checksum, последовательным транзакционным применением под PostgreSQL advisory lock. Rolling compatibility требует expand/migrate/contract, а не только общую «совместимость». + +Отдельно NFR-R4 обещает RPO=0 при restore из «доступного согласованного backup», но Reference Deployment не указывает WAL archiving/PITR или synchronous replica. Обычный periodic backup не может доказать RPO=0; такое обещание противоречит заданному single-deployment Community profile, если не добавить конкретный durability mechanism. + +**Что добавить:** закрепить immutable/checksummed/transactional/advisory-lock migration contract и expand/migrate/contract acceptance tests. Для RPO выбрать одно из двух: (a) обязать и проверять WAL/PITR и согласованное восстановление artifacts, либо (b) заменить RPO=0 на измеримый backup-dependent RPO. Сохранить RPO=0 для acknowledged PostgreSQL transactions при штатном restart отдельно от disaster restore. + +### G3 — Нет явного fail-closed контракта для safety stores + +**Уровень: High.** + +PRD верно требует fail-open поведение наблюдаемости после startup, `IdempotencyOutcomeUnknown` без auto-retry, durable Task record до acknowledgment и atomic approval transitions. Но он не переносит прямой инвариант source: если mandatory coordination/cache/approval store недоступен, соответствующий safety mechanism обязан fail closed, а не молча отключать idempotency, approvals, concurrency lease или deduplication. + +Это особенно важно из-за сочетания «Valkey optional» и новых Tasks/Load Runs: optional dependency не должна означать optional safety. Также в source кэш любого agent/workspace/auth-dependent состояния обязан иметь полный security scope. + +**Что добавить:** acceptance contract для dependency-failure matrix: какой путь продолжает работу, какой отклоняется с диагностируемой ошибкой, и как readiness отражает невозможность безопасно выполнить enabled capability. Включить negative tests на cross-Agent/workspace cache bleed и на отказ Valkey/approval store во время execution/recovery. + +### G4 — Secret master-key lifecycle не входит в production recovery contract + +**Уровень: High.** + +FR-3 и NFR-S2 покрывают one-time disclosure, rotation, encryption at rest и запрет утечки. Но в PRD нет критичного текущего контракта: Admin API и MCP должны использовать один и тот же master key; его замена без re-encryption/migration делает сохранённые secrets недоступными. Простой backup PostgreSQL/artifacts без защищённого key material тоже не доказывает restore работоспособного контура. + +**Что добавить:** требование единой key identity/configuration на всех composition roots, процедуру backup/restore key material без раскрытия самого key, и проверяемый rotation/re-encryption path. Recovery gate должен доказывать, что после restore MCP реально может исполнить Operation с зашифрованным Auth Profile, а не только поднять схему и UI. + +### G5 — Границы correlation/diagnostic artifacts недостаточно проверяемы + +**Уровень: Medium.** + +PRD требует validated Request ID/Trace ID, redaction, bounded telemetry queues, low-cardinality metrics и size limits для inputs/bodies/responses. Но source задаёт два более точных инварианта, которые в PRD нельзя однозначно проверить: + +1. inbound `x-request-id` должен быть ограничен и валидирован, а invalid value — заменён UUIDv7; Request ID остаётся отдельным от trace identity; +2. events, previews и JSON-поля должны иметь лимиты с сохранением валидного UTF-8/JSON; нельзя обрезать serialised data произвольным byte slice. + +С новыми Invocation History, Task attempts, browser events и Load Run artifacts второй пункт прямо влияет на memory/storage safety и корректность UI/export. + +**Что добавить:** в FR-27/NFR-O5 закрепить exact invalid-ID fallback и разделение Request/Trace identity; в NFR-S4/FR-6/FR-40 закрепить bounded, format-preserving previews/events/reports и negative tests на oversized/malformed values. + +## Важные инварианты, уже сохранённые PRD + +- Draft/Published isolation, immutable Published Versions и публикация MCP capabilities только через разрешённый Agent. +- SSRF-политика по фактическому connection address после DNS resolution; redirects/system proxy выключены; bounded timeout/body/response/concurrency. +- One-time raw secret/key disclosure, encryption at rest, redaction и запрет secrets в logs/traces/metrics/reports/exports. +- Scoped approvals, idempotency fingerprint, outcome-unknown без automatic retry, at-least-once Tasks без ложного exactly-once promise. +- Локальная Invocation History, `request_id`/`trace_id`, low-cardinality Prometheus labels, exemplars/deep links и fail-open telemetry после успешного startup. +- Отсутствие phone-home telemetry, offline deployment path, optional external observability endpoints и закрытый контур. +- Single workspace/admin, REST-only upstream, PostgreSQL + optional Valkey, отсутствие RBAC/SSO/SaaS/multi-protocol creep. +- Full test pyramid, OpenAPI regression corpus, MCP/client/browser matrices, manual regression, security evidence, 72-hour soak, dependency failure, backup/restore/upgrade и immutable RC artifact. +- RU/EN для нового UI-текста и обязательные async loading/error states через общий production-quality/manual regression intent. При реализации нужно также сохранить project-context guard от stale async responses. + +## Что остаётся implementation guardrail, а не пробелом PRD + +Следующие правила не нужно копировать в основной текст PRD, но они обязательны для архитектуры, эпиков, stories и code review: + +- Rust Edition/MSRV/toolchain/dependency lock и separate dependency updates; +- запрет panic/`unwrap`/`expect` на user/I/O/external paths, `unsafe` by default и typed stage-preserving errors; +- workspace dependency boundaries, pure `crank-core`, Apps как composition roots, routes/service/DTO separation, typed `crank-metrics` ownership; +- текущий vanilla JS/Alpine/bundle model, stale-response guards, safe DOM output и bundle-global discipline; +- real PostgreSQL integration tests, Streamable HTTP contract tests, UI build/Playwright отдельно от `just verify`, dependency/license gates, SQLx metadata discipline; +- source of truth `deploy/community/`, Gitea-specific CI, production-deploy side effect при push в `main` и release side effect при tag `v*`. + +## Рекомендуемая очерёдность устранения + +1. Явно принять новую границу Community и связать её с обновлением executable scope checks. +2. Исправить recovery/RPO contract и закрепить migration invariants до декомпозиции Tasks/Resources/Prompts/Load Runs, так как все они почти наверняка меняют schema. +3. Добавить fail-closed dependency matrix и secret-key recovery evidence в Security/Deployment Release Gate. +4. Уточнить bounded correlation/artifact contract как часть observability hardening. diff --git a/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/reconcile-user-brief.md b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/reconcile-user-brief.md new file mode 100644 index 0000000..d2b0de0 --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/reconcile-user-brief.md @@ -0,0 +1,54 @@ +# Сверка PRD с исходным пользовательским brief + +## Источник + +Все сообщения пользователя в текущей ветке, включая первоначальный brain dump, уточнения о целевой аудитории и подтверждение Fast path. Сверены: + +- `prd.md` +- `addendum.md` + +## Вердикт + +Основной замысел сохранён хорошо: обязательность всех перечисленных возможностей до анонса на Хабре, production-hardening существующего Community-продукта, закрытый контур, OpenAPI, Resources/Prompts, параллельные и фоновые выполнения, сквозной `trace_id`, GlitchTip, Prometheus/Grafana, технические и бизнес-метрики, встроенная нагрузка и последовательность «сначала функциональная полнота, затем всесторонняя проверка» отражены явно. Обнаружены четыре пробела и одна зона расширения scope. + +## Обнаруженные gaps + +### 1. Нет исчерпывающего реестра текущих функций и трассировки их regression-покрытия — высокий + +Пользователь потребовал, чтобы **все текущие функции** продолжали работать с максимальным качеством и без смысловых поломок. §4.1 перечисляет Operations, Agents, keys, secrets, approvals, test run, YAML import/export, Logs и Usage, но документ не доказывает, что это полный фактический surface репозитория. Release Gate проверяет выполнение FR-1—FR-54, поэтому уже существующая, но не попавшая в этот список функция может быть пропущена и при этом формально пройти gate. + +Нужно до feature freeze получить versioned inventory существующих UI/API/MCP flows из project context и репозитория и связать каждый flow с сохранённым контрактом, manual checklist и regression evidence. Это не требует раздувать PRD деталями: inventory может быть отдельным release-evidence артефактом, но обязан быть явно потребован PRD. + +### 2. Конкретный дефектный путь загрузки `openapi.yaml` задан недостаточно явно — высокий + +Пользователь отдельно назвал сбои при загрузке методов из файлов `openapi.yaml`. FR-7—FR-12 подробно определяют семантику импорта, однако нигде явно не закреплены поддерживаемые способы входа и форматы файла: загрузка `.yaml`/`.yml`, JSON, кодировка, multipart/file-size limits, parser diagnostics и проверка того, что методы действительно извлечены из загруженного файла. Формулировка «документ» допускает реализацию через иной канал и не гарантирует regression именно исходного проблемного пути. + +Нужно добавить проверяемый контракт file-upload импорта OpenAPI YAML и соответствующие fixtures/E2E cases, включая повреждённый YAML, пустой/большой файл и документ без распознаваемых методов. + +### 3. «Все современные возможности MCP» не имеют закрытого feature-inventory gate — высокий + +FR-13 говорит о «стабильных server-side возможностях … применимых к роли» и далее перечисляет Tools, Resources, Prompts, Tasks, completion, logging, progress и notifications. Это сильная база, но слова «применимые» оставляют субъективную лазейку: на feature freeze можно пропустить современную MCP capability, не зафиксировав решение `supported / not applicable / experimental / deferred` и причину. Пользователь сформулировал требование шире — поддерживать все современные MCP-функции. + +Нужно обязать feature-freeze inventory по официальной stable MCP specification: каждый server/client capability и extension получает явный статус, обоснование применимости, fallback и исполняемое evidence. Не применимые к Crank client-side возможности можно исключать, но исключение должно быть осознанным и опубликованным, а не следовать из расплывчатой формулировки. + +### 4. Бесплатность Community-пути осталась декларацией, а не release criterion — средний + +Пользователь назвал возможность пользоваться продуктом и создавать capabilities **не платя** одной из центральных ценностей. Vision фиксирует «бесплатная self-hosted платформа», FR-41 запрещает обязательный proprietary service, но Release Gate не проверяет, что весь обязательный production scope доступен без платной лицензии, коммерческого backend или premium feature gate. Бесплатный запуск возможен и с зависимостями, чьи production-ограничения проявятся позже. + +Нужно добавить release criterion: Community-пользователь может развернуть и использовать весь обязательный public-launch scope на документированном профиле без покупки лицензии или обязательного коммерческого сервиса; лицензии bundled-компонентов проверены и раскрыты. + +## Зона чрезмерного расширения scope + +PRD сделал обязательными до Хабра несколько существенных направлений, которые пользователь напрямую не перечислял: полноценные upgrade/backup/restore/rollback и offline-install процедуры, отдельную readiness-страницу, три browser engines, immutable load reports и сравнение прогонов между релизами. Они логично следуют из production-ready и закрытого контура, а пользователь делегировал такие решения Fast path, поэтому конфликта с brief нет. Однако это реальное расширение критического пути. Если срок анонса станет важнее полноты, сокращать следует глубину этих evidence/UX-механизмов, а не перечисленные пользователем MCP, observability, OpenAPI, performance и testing capabilities. + +## Сохранённые качественные идеи + +- Тон «Rust-продукт обязан быть быстрым и безопасным» переведён в конкретные performance, reliability, security и observability budgets. +- «Не отдавать данные на сторону» сохранено как local-first, offline-capable и opt-in-only telemetry. +- «Сначала функциональные недоработки, потом полное тестирование» сохранено в последовательности Feature Complete → Quality Complete → Release Candidate. +- Упрощённая кнопка RPS/DAU сохранена, при этом дополнена безопасными параметрами и честным переводом DAU в нагрузочный профиль. +- Указание на FastMCP не превратилось в жёсткую архитектурную зависимость: сохранён продуктовый контракт фоновых Tasks и совместимость MCP. + +## Конфликты и искажения + +Прямых конфликтов с пользовательским brief не обнаружено. diff --git a/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/review-adversarial-general.md b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/review-adversarial-general.md new file mode 100644 index 0000000..a3f6d4a --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/review-adversarial-general.md @@ -0,0 +1,31 @@ +# Adversarial review: Crank Community Production Readiness PRD + +- OpenAPI corpus измеряет успех по числу Operations, поэтому одна спецификация с тысячами простых endpoints может перевесить множество неработающих сложных документов. Полезно дополнить SM-8 отдельным per-document success rate и coverage mandatory constructs, не меняя уже достаточный blocker gate. + +- Content-addressed snapshot external `$ref` закрывает preview/apply TOCTOU, но не указан retention snapshot/provenance после публикации и удаления Operation. Для долгосрочного аудита стоит связать Published Version с сохранённым root digest и сроком хранения resolved bundle. + +- Effectively-once сформулирован безопасно через upstream idempotency и `outcome_unknown`, однако точные canonicalization, scope/retention deduplication и forwarding idempotency key оставлены архитектуре. Их следует закрепить в solution contract и crash-matrix fixtures до реализации. + +- `input_required` теперь имеет update, validation и TTL, но максимальный operator-configurable TTL и полномочия reconciliation не заданы численно. Архитектура должна исключить бесконечное user-wait pause и зафиксировать audit/confirmation policy для нового attempt. + +- Load Run получил абсолютный per-Run ceiling и независимый kill switch, но суммарная квота нескольких одновременных Runs не названа явно. Общий NFR-S4 требует bounded concurrency, однако test design стоит закрепить global concurrent-Run limit и aggregate dispatch ceiling. + +- Static Resources получили sensitivity, MIME/size limits и secret scan, но aggregate storage quota, decompression/expansion limit и политика неизвестного MIME остаются нечисловыми. Эти значения следует вынести в versioned limits catalog и negative fixtures. + +- Manual checklist охватывает все критические области, но его one-to-one mapping с Capability Inventory и проверяемыми последствиями FR не указан явно. Автоматическая проверка полноты mapping уменьшит риск случайного пробела в ручном regression pass. + +- Evidence Manifest защищает digests/signatures и immutable result artifacts, но trust root, key custody и запрет self-approval для объяснённой performance regression остаются процессными решениями. Для публичного проекта стоит описать минимальную two-person либо publicly reproducible approval policy. + +- RPO/RTO измеряются корректно до реального MCP-вызова, но характеристики operator-provided backup backend не входят в Reference Deployment. Evidence должен публиковать latency, bandwidth, fault domain, data/WAL volume и restore topology, чтобы результаты можно было воспроизвести. + +- Upgrade gate всё ещё обозначает baseline как previous Community release без конкретного version/digest и skip-level policy. Это не логическая лазейка после требования immutable baseline, но значение нужно заморозить в Baseline Frozen и опубликовать рядом с compatibility matrix. + +- External replacement Prometheus/Grafana/GlitchTip разрешён без отдельного conformance suite. Обязательный tested GlitchTip path закрывает launch gate, однако документации нужны чёткие критерии, какие dashboards, alerts, search/deep links и retention сохраняются при замене backend. + +- NFR-P3 использует выражение «без функциональной деградации», не связывая каждый catalog/Logs/Usage/lifecycle API с latency и error threshold. NFR-P4/P5 и workload уже дают общую границу, но test plan следует расширить route-level thresholds для million-row dataset. + +- NFR-P5 не перечисляет browser/device profile, cold/warm cache, network shaping, обязательные routes и конкретную web-vitals метрику. Это не safety blocker, но без фиксации профиля результат p95 ≤2 с будет плохо сравним между релизами. + +- MCP/browser matrix оставляет выбор representative clients и версий до RC. Перед feature freeze нужно закрепить client archetypes, transports, version pins и approval критерия `not applicable`, чтобы исключить удобный cherry-picking. + +- SM-4 не ограничивает число Medium product defects и не задаёт им общий срок, если они не влияют на SLO, данные или безопасность. Полезно добавить UX/functional impact rule либо cap, чтобы публичный релиз не накопил большой хвост раздражающих, но формально неблокирующих проблем. diff --git a/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/review-edge-cases.md b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/review-edge-cases.md new file mode 100644 index 0000000..f7d44dc --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/review-edge-cases.md @@ -0,0 +1,170 @@ +[ + { + "location": "prd.md:113-117", + "trigger_condition": "Сервис падает посередине ротации master key", + "guard_snippet": "persist rotation_state; resume_or_rollback_reencryption_atomically_before_readiness()", + "potential_consequence": "Часть секретов становится нерасшифровываемой после рестарта" + }, + { + "location": "prd.md:109-117", + "trigger_condition": "Ключ отзывается после авторизации, но до outbound dispatch", + "guard_snippet": "define_revocation_cutoff(); recheck_key_revision_immediately_before_dispatch()", + "potential_consequence": "Отозванный ключ всё ещё инициирует внешний side effect" + }, + { + "location": "prd.md:101-113", + "trigger_condition": "Auth Profile ротируется при наличии cached response", + "guard_snippet": "include_auth_profile_revision_in_cache_key_and_invalidate_on_rotation()", + "potential_consequence": "Новые credentials получают данные старого security context" + }, + { + "location": "prd.md:95-125", + "trigger_condition": "Публикация capability и привязка Agent выполняются конкурентно", + "guard_snippet": "bind_only_published_version_under_catalog_revision_compare_and_swap()", + "potential_consequence": "Agent обнаруживает неполностью опубликованную или устаревшую версию" + }, + { + "location": "prd.md:225-235", + "trigger_condition": "REST-backed Resource использует side-effecting HTTP method", + "guard_snippet": "require_resource_safe_method_or_explicit_read_only_upstream_contract_before_publish()", + "potential_consequence": "Обычный resources/read изменяет upstream данные" + }, + { + "location": "prd.md:212-218", + "trigger_condition": "Клиент повторно использует устаревший или чужой cursor", + "guard_snippet": "validate_cursor_signature_scope_catalog_revision_and_expiry_or_reject()", + "potential_consequence": "Pagination раскрывает capability или пропускает элементы" + }, + { + "location": "prd.md:276-282", + "trigger_condition": "Synchronous fallback переживает обрыв клиентского соединения", + "guard_snippet": "bind_fallback_to_scoped_idempotency_key_or_cancel_before_client_retry()", + "potential_consequence": "Повтор клиента запускает дублирующий side effect" + }, + { + "location": "prd.md:286-294", + "trigger_condition": "Retention истекает во время polling активного клиента", + "guard_snippet": "retain_result_until_max(retention,last_poll_plus_grace); return_tombstone_afterward()", + "potential_consequence": "Клиент получает необъяснимый not-found вместо результата" + }, + { + "location": "prd.md:298-304", + "trigger_condition": "Acknowledgement Task потерян, и клиент повторяет tools/call", + "guard_snippet": "deduplicate_task_creation_by_scoped_client_request_key_and_return_existing_task_id()", + "potential_consequence": "Retry создаёт вторую durable задачу" + }, + { + "location": "prd.md:308-313", + "trigger_condition": "Постоянный поток одного Agent вытесняет редкие задачи другого", + "guard_snippet": "assert_bounded_wait_per_scope_under_continuous_competing_load()", + "potential_consequence": "Отдельные Agents голодают несмотря на заявленную fairness" + }, + { + "location": "prd.md:286-325", + "trigger_condition": "Reconciliation outcome_unknown невозможно завершить достоверно", + "guard_snippet": "define_operator_escalation_ttl_and_non_retriable_tombstone_without_erasing_audit()", + "potential_consequence": "Non-terminal задачи навсегда накапливаются в хранилище" + }, + { + "location": "prd.md:317-325", + "trigger_condition": "Часы узлов расходятся при вычислении deadline", + "guard_snippet": "persist_absolute_deadline_once_and_use_monotonic_elapsed_time_per_attempt()", + "potential_consequence": "Task выполняется после deadline или отменяется преждевременно" + }, + { + "location": "prd.md:288-304", + "trigger_condition": "Agent key или capability отозваны пока Task ожидает claim", + "guard_snippet": "define_snapshot_semantics_or_reauthorize_owner_capability_and_auth_revision_at_claim()", + "potential_consequence": "Очередь выполняет работу после отзыва доступа" + }, + { + "location": "prd.md:342-348", + "trigger_condition": "Валидный недоверенный traceparent устанавливает sampled=false", + "guard_snippet": "override_remote_sampling_decision_when_production_generation_rate_is_one()", + "potential_consequence": "Клиент отключает обязательную трассировку своих запросов" + }, + { + "location": "prd.md:377-383", + "trigger_condition": "Один trace содержит аномально много spans или bytes", + "guard_snippet": "enforce_per_trace_span_and_byte_limits_with_explicit_loss_record()", + "potential_consequence": "Один запрос исчерпывает spool и вытесняет остальные traces" + }, + { + "location": "prd.md:395-401", + "trigger_condition": "Load Run requests учитываются как реальный Agent DAU", + "guard_snippet": "tag_synthetic_traffic_and_exclude_it_from_activation_and_DAU_metrics()", + "potential_consequence": "Встроенные тесты искусственно завышают бизнесовые метрики" + }, + { + "location": "prd.md:425-438", + "trigger_condition": "RPS, VU, duration или DAU-параметр нечисловой или отрицательный", + "guard_snippet": "require_finite_nonnegative_inputs_and_checked_arithmetic_before_curve_generation()", + "potential_consequence": "Runner обходит ceiling, падает или строит неверную нагрузку" + }, + { + "location": "prd.md:425-450", + "trigger_condition": "Capability архивируется или Auth Profile отзывается перед Start", + "guard_snippet": "atomically_revalidate_pinned_capability_load_safety_and_credentials_at_start()", + "potential_consequence": "Run использует запрещённую версию или недействительные credentials" + }, + { + "location": "prd.md:442-450", + "trigger_condition": "Повтор подтверждения Start создаёт два Load Runs", + "guard_snippet": "require_scoped_idempotency_key_for_load_run_start()", + "potential_consequence": "Нагрузка удваивается сверх подтверждённой интенсивности" + }, + { + "location": "prd.md:442-450", + "trigger_condition": "Несколько Runs одновременно достигают индивидуальных ceilings", + "guard_snippet": "enforce_global_aggregate_RPS_VU_iteration_and_duration_budget_across_runs()", + "potential_consequence": "Суммарная нагрузка многократно превышает абсолютный предел" + }, + { + "location": "prd.md:448-458", + "trigger_condition": "Runner теряет lease посередине выполнения", + "guard_snippet": "transition_run_to_interrupted_and_emit_immutable_partial_report_after_lease_timeout()", + "potential_consequence": "Run остаётся running без итогового evidence" + }, + { + "location": "prd.md:452-458", + "trigger_condition": "Остановленный Run уже создал background Tasks", + "guard_snippet": "define_stop_policy_for_spawned_tasks_and_report_each_surviving_task_id()", + "potential_consequence": "Нагрузка продолжает выполняться после успешного Stop" + }, + { + "location": "prd.md:462-467", + "trigger_condition": "Run завершается без единого успешного sample", + "guard_snippet": "if completed_samples == 0: verdict = invalid_not_pass", + "potential_consequence": "Пустой прогон ошибочно проходит thresholds" + }, + { + "location": "prd.md:462-467", + "trigger_condition": "Сравниваемые Runs имеют разные environment fingerprints", + "guard_snippet": "block_regression_comparison_unless_fingerprints_match_or_difference_is_acknowledged()", + "potential_consequence": "Изменение окружения выдаётся за регрессию продукта" + }, + { + "location": "prd.md:497-504", + "trigger_condition": "Backup снимается одновременно с migration или ротацией ключа", + "guard_snippet": "acquire_backup_barrier_across_schema_config_and_key_rotation_before_snapshot()", + "potential_consequence": "Согласованный набор невозможно расшифровать или мигрировать" + }, + { + "location": "prd.md:608-610", + "trigger_condition": "Reference host имеет существенно более медленные виртуальные CPU", + "guard_snippet": "pin_CPU_model_frequency_or_require_calibrated_minimum_compute_benchmark()", + "potential_consequence": "Performance Gate невоспроизводим между одинаковыми 4-vCPU hosts" + }, + { + "location": "prd.md:665", + "trigger_condition": "Spool sizing использует p95, но хвост trace size значительно больше", + "guard_snippet": "size_spool_from_bounded_worst_case_or_test_p999_plus_reserved_margin()", + "potential_consequence": "Гарантия 24-часового outage нарушается без среднего overload" + }, + { + "location": "prd.md:733-748", + "trigger_condition": "Новая stable MCP версия выходит во время 30-дневного burn-in", + "guard_snippet": "resolve_latest_stable_again_at_gate_and_rerun_or_publish_explicit_freeze_cutoff()", + "potential_consequence": "Readiness-страница на запуске уже не покрывает latest stable" + } +] diff --git a/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/review-operability-security.md b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/review-operability-security.md new file mode 100644 index 0000000..b8930de --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/review-operability-security.md @@ -0,0 +1,98 @@ +# Production operability/security review — финальный blocker-pass + +## Вердикт + +**GO для финализации PRD: Critical/High blockers отсутствуют.** Обновлённый документ задаёт достаточный production contract для архитектуры, эпиков и Release Gate. Task uncertainty теперь имеет отдельное состояние и reconciliation flow; admin identity получила one-time bootstrap, rate limiting, rotation/recovery и session revocation. Оставшиеся Medium/Low findings не делают PRD небезопасным для следующей фазы, но должны получить owner и быть закрыты до Release Candidate либо явно подтверждены исполняемым контрактом без ослабления gate. + +## Сводка + +| Severity | Количество | +|---|---:| +| Critical | 0 | +| High | 0 | +| Medium | 7 | +| Low | 2 | + +## Подтверждение закрытия прежних blockers + +- FR-22/FR-25 теперь включают `outcome_unknown` как non-terminal, блокируют Retry/Cancel-as-success и разрешают только audit-logged reconciliation transitions; MCP/UI не маскируют uncertainty. +- FR-3 задаёт одноразовый bootstrap без default password, bounded login rate limit/backoff, rotation/recovery с отзывом sessions/CSRF tokens и local operator-only recovery. +- TLS, trusted-proxy allowlist, secure cookies, CSRF/CORS и security-header tests закреплены в production profile. +- Reference Workload фиксирует background duration, active/queued Tasks, queue wait/age, restart recovery и drain target; steady/burst gates разделены. +- Backup manifest связывает WAL LSN, artifacts/config и versioned key-backup reference; RPO/RTO и rotation проверяются реальным MCP-вызовом. + +## Medium + +### M-1. Admin credential verifier strength оставлен архитектуре без security minimum + +**Где:** FR-3, FR-41, NFR-S1/S2. + +Bootstrap/rate limiting/recovery заданы, но не закреплены password/verifier strength, constant-time comparison и защита сохранённого verifier. + +**Исправление:** архитектура и acceptance tests должны потребовать memory-hard password hashing либо эквивалентный устойчивый verifier, constant-time verification, уникальную соль и запрет plaintext/reversible admin password storage. + +### M-2. Master-key rotation не задаёт crash-resumable cryptographic lifecycle + +**Где:** FR-3, FR-43, NFR-R4, addendum §Recovery. + +Rotation gate проверяет old→new→revoke, но не определены versioned ciphertext envelope, dual-read/single-write window, resume после crash и verify-before-retire. + +**Исправление:** зафиксировать key version в ciphertext, idempotent resumable re-encryption, метрику remaining-old-key records и запрет retire до нулевого остатка; добавить partial-rotation/wrong-key/corrupt-key-backup tests. + +### M-3. Synthetic traffic не отделён от бизнес-метрик + +**Где:** FR-33, FR-36—FR-40, §5.2, SM-11—SM-15. + +Load Runs и 30-дневный burn-in способны искусственно увеличить Agent DAU, adoption и usage. + +**Исправление:** доверенный internal `traffic_class=synthetic|organic`, недоступный пользовательскому mapping; synthetic остаётся в qualification/capacity SLI, но исключается из organic business funnel и post-launch product metrics. + +### M-4. Telemetry Loss Records не имеют отдельной retention/quota policy + +**Где:** глоссарий, FR-29/FR-31, NFR-O2/O2a, §6.2. + +24-hour spool budget защищает основной outage envelope, но редкие immutable Loss Records могут накапливаться весь срок установки. + +**Исправление:** отдельный retention/quota; после individual-record budget сохранять immutable aggregated loss intervals/counts и monotonic total-loss counter, не вытесняя product data. + +### M-5. Offline bundle не определяет trust bootstrap и revocation + +**Где:** FR-42, SM-10, addendum §Recovery. + +Bundle подписан и digest-pinned, но не указаны signature/provenance format, pinned trust-root fingerprint, rotation/revocation и local-registry import. + +**Исправление:** versioned manifest, offline-verifiable signature/provenance, документированный trust root и N-1→N→N-1 test через пустой local registry без внешней сети. + +### M-6. Evidence signature проверяется, но governance доверия не определён + +**Где:** FR-52/FR-54, §9/§10. + +JSON Schema и CI verifier появились, однако не заданы trust root/signing identity, separation preparer/approver и invalidation зависимого evidence после blocker fix. + +**Исправление:** определить signing identity/trust policy, audit identities preparer/approver и declarative dependency graph, по которому изменение RC/config/test invalidates затронутое evidence. + +### M-7. Dependency-failure matrix не перечисляет минимальный обязательный набор + +**Где:** FR-23/FR-24/FR-31/FR-49, SM-6. + +Название matrix остаётся шире минимальных проверяемых scenarios; реализация может ограничиться binary restarts. + +**Исправление:** обязательны PostgreSQL slow/unavailable/failover/disk-full/read-only; Valkey partition/flush; stale worker; DNS rebind/failure; upstream reset/partial body/timeout; clock skew; filesystem full; telemetry backend slow/outage/spool overflow — с expected readiness, invariant, alert и recovery evidence. + +## Low + +### L-1. Вводная строка FR-43 всё ещё говорит `rolling/restart` + +Ниже корректно закреплён single-instance drain/restart и rolling объявлен non-goal. + +**Исправление:** заменить вводную формулировку на `single-instance drain/restart upgrade`. + +### L-2. `RBAC-equivalent admin restriction` неприменим к single-admin Community + +**Где:** FR-38, §6.1. + +**Исправление:** заменить на `authenticated current admin identity + production reconfirmation + immutable audit event`. + +## Gate decision + +Operability/security reviewer разрешает финализацию PRD. Условие handoff: все Medium findings заносятся в open-item/evidence ownership без снижения SM-4/NFR-S5; любой новый Critical/High в архитектуре или threat model повторно закрывает gate. diff --git a/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/review-rubric.md b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/review-rubric.md new file mode 100644 index 0000000..9dc440e --- /dev/null +++ b/_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/review-rubric.md @@ -0,0 +1,66 @@ +# PRD Quality Review — Crank Community — Production Readiness + +## Overall verdict + +PRD готов служить основанием для архитектуры, UX, эпиков и QA: Critical/High замечаний не осталось. Task state machine теперь замкнута для `outcome_unknown` и `input_required`, а MCP scope, OpenAPI semantics, workload/SLI, observability loss, recovery, security и Release Gate описаны проверяемыми контрактами; оставшиеся Medium/Low — уточнения, не блокирующие начало downstream-проектирования. + +## Decision-readiness — adequate + +Ключевые решения сформулированы прямо: обязательный scope нельзя переносить ради даты (§1, §8), применимая stable MCP capability со статусом `deferred` блокирует релиз (FR-20), неопределённый внешний side effect требует reconciliation (FR-22/FR-25), multi-instance rolling upgrade не обещается (FR-43), а Habr Gate выводится из подписанного evidence FR-1—FR-53 (FR-54). §9 даёт однозначную последовательность Baseline Frozen → Feature Complete → Quality Complete → immutable RC → 30-дневный burn-in. + +Остаётся одна неблокирующая развилка change-control. + +### Findings + +- **medium** Подтверждённые targets остаются изменяемыми без формального product approval (§12, вопросы 3–4; §5.1 A-12; FR-29/A-7) — versioned baseline делает изменение видимым, но формулировка «требуют корректировки targets» не определяет, можно ли после benchmark снизить NFR-P* или retention и кто это утверждает. *Fix:* разрешить benchmark менять implementation/workload version, но снижение подтверждённых NFR/A-7 проводить отдельным product decision с записью в memlog/readiness scope и минимальными floors. + +## Substance over theater — strong + +Содержание заработано спецификой Crank. Видение связывает REST → MCP, закрытый контур, no-code authoring и доказанную production readiness; UJ-1—UJ-5 непосредственно порождают OpenAPI, Resources/Prompts, observability, Load Runs и Tasks. Normative OpenAPI matrix, Capability Inventory, конкретный Reference Workload, исполняемые SLI, telemetry spool/Loss Record, web-security baseline и restore-through-real-MCP-call исключают шаблонные NFR и process theater. + +## Strategic coherence — adequate + +Единый тезис сохраняется по всему документу: бесплатный self-hosted MCP путь имеет ценность только при предсказуемом импорте, исполнении, безопасности и эксплуатации. Feature clusters поддерживают этот тезис, а SM-C1—SM-C5 запрещают покупать throughput ценой security, correctness или ресурсов. + +Локальные post-launch метрики всё ещё не образуют механизм продуктового обучения для владельцев Community проекта. + +### Findings + +- **medium** Post-launch metrics не определяют способ проверки продуктовой гипотезы на уровне экосистемы (§10.2 SM-11—SM-15; FR-33; §7) — данные остаются внутри установки, а SM-11 считает TTFV только «среди завершивших onboarding», исключая пользователей без first value. *Fix:* разделить operator-local и ecosystem metrics; определить privacy-compatible evidence для вторых, а TTFV дополнить conversion-to-first-value с фиксированным timeout/censoring rule. + +## Done-ness clarity — adequate + +Большинство FR имеют проверяемые последствия. Reference Workload фиксирует background distribution, queue/drain bounds, payloads, upstream behavior, cache/telemetry и restart variant; SLI задают minute probes, denominators, outcome taxonomy и trace completeness. `outcome_unknown` теперь non-terminal, блокирует обычный retry/cancel, имеет допустимые reconciliation transitions и UI-flow; `input_required` получил schema-validated idempotent update и TTL (FR-22, FR-25, FR-26). + +Осталось несколько qualifiers, которые тест-плану придётся конкретизировать до RC. + +### Findings + +- **medium** Часть release-critical выборок и qualifiers остаётся недетерминированной (§5.1 NFR-P3, NFR-P5; §5.2 NFR-R5; FR-48/SM-9) — не названы «основные UI-экраны», не определены «функциональная деградация» и граница «нормальной загрузки»; критерии выбора трёх representative MCP clients отсутствуют. OpenAPI baseline уже существенно снижает аналогичный риск для importer. *Fix:* заморозить UI journeys/screens, допустимую деградацию, normal-load boundary и client-selection criteria; включить их версии/checksums в Evidence Manifest. + +## Scope honesty — strong + +§8.1 перечисляет всё обязательное, §8.2 запрещает перенос ради даты, §7 исключает SaaS, enterprise tenancy/identity, non-REST upstreams и exactly-once. Stable MCP нельзя скрыть за `deferred`; experimental surface отделена; OpenAPI silent loss оценивается относительно нормативной matrix; времязависимые вопросы честно вынесены в §12. + +## Downstream usability — adequate + +FR-1—FR-54, UJ-1—UJ-5 и SM-1—SM-15 уникальны и последовательны; journeys имеют именованных протагонистов; capability sections автономны; архитектурные рекомендации вынесены в addendum. Глоссарий включает ключевые evidence/workload/telemetry понятия, а state semantics теперь описаны непосредственно в FR. + +Небольшой терминологический долг сохраняется. + +### Findings + +- **low** Несколько contract nouns не имеют канонического определения (§3 и далее) — `capability`, `Auth Profile`, `owner scope`, `Agent revision`, `supported workload` и `product-caused failure` влияют на access и SLI, но отсутствуют в глоссарии; `defect/finding/error/failure` используются без явной границы. *Fix:* дополнить глоссарий и нормализовать допустимые синонимы. + +## Shape fit — strong + +Форма соответствует brownfield chain-top PRD. Пять journeys оправданы multi-role self-hosted продуктом и несут контекст inline, после чего основной вес отдан capability contracts, NFR, guardrails и release evidence. Hardening существующего ядра отделён от новых MCP surfaces; уровень формальности соответствует назначению для UX, архитектуры, эпиков и QA. + +## Mechanical notes + +- FR-1—FR-54, UJ-1—UJ-5 и SM-1—SM-15 непрерывны и без дублей. NFR-P1a/P1b и NFR-O2a понятны, но диапазоны `NFR-P1—NFR-P5`/`NFR-O1—O5` лучше явно определить как включающие суффиксные IDs. +- A-1—A-12 имеют исходное решение и запись в §13. A-4 находится во вводном абзаце §4.3, хотя индекс указывает `(FR-13)`; точнее сослаться на `§4.3`. +- FR-54 не самоссылочен: SM-1 требует evidence FR-1—FR-53. +- FR-43 начинает с `rolling/restart upgrade path` и `rolling update/rollback window`, затем исключает rolling multi-instance. Последующие bullets проясняют single-instance drain/restart, но унификация терминов уберёт двусмысленность. +- A-7 в §13 говорит «100% trace sampling», тогда как нормативный контракт различает generation, delivery latency и eventual completeness; индекс стоит синхронизировать. +- В addendum остаётся опечатка «не редоставляется автоматически»; корректно: «не доставляется повторно автоматически». diff --git a/_bmad-output/planning-artifacts/sprint-change-proposal-2026-08-25.md b/_bmad-output/planning-artifacts/sprint-change-proposal-2026-08-25.md new file mode 100644 index 0000000..4545611 --- /dev/null +++ b/_bmad-output/planning-artifacts/sprint-change-proposal-2026-08-25.md @@ -0,0 +1,101 @@ +# Sprint Change Proposal — декомпозиция Story 2.1 + +**Дата:** 2026-08-25 +**Проект:** crank +**Статус:** Approved / Applied +**Режим:** Batch +**Подтверждение:** пользователь выбрал вариант 1 сообщением «Ок, делай 1 вариант». + +## 1. Причина изменения + +Первая автоматическая реализация `2-1-openapi-source` была остановлена, вторая исчерпала 90-минутный лимит и завершилась после 457 114 weighted tokens без итогового review. Сама спецификация уже содержала предупреждение `oversized` и объединяла четыре самостоятельные инженерные границы: + +1. защищённый content-addressed filesystem store; +2. PostgreSQL metadata, workspace isolation, migration и reconciliation; +3. Admin API multipart orchestration и verified preview/apply source; +4. UI, outer E2E, документацию и release evidence. + +Проверка частичной реализации подтвердила, что увеличение timeout не решает проблему декомпозиции: в WIP отсутствовали registry v12 и workspace-scoped metadata, lifecycle/sweep не был связан с транзакционным recheck, filesystem boundary требовал дополнительного symlink/TOCTOU hardening, apply опирался на сохранённый preview JSON, а production multipart и UI не имели полного outer-surface evidence. + +## 2. Влияние на продукт и архитектуру + +- PRD не меняется: FR-7 и FR-9 остаются полностью покрыты. +- Architecture Spine не меняется: AD-15, AD-16, AD-19, AD-20 и AD-24 остаются обязательными инвариантами. +- Epic 2 outcome не меняется: пользователь всё так же получает immutable verified OpenAPI source, детерминированный preview и безопасный import. +- Scope Community Edition не меняется. +- Меняется только единица исполнения и порядок gates, чтобы каждый шаг был независимо проверяемым и пригодным для code review. + +## 3. Рассмотренные варианты + +### Вариант 1 — сохранить WIP и разделить Story 2.1 (выбран) + +Сохранить остановленную попытку в отдельной rescue-ветке, вернуть чистый `main`, заменить одну oversized story четырьмя последовательными stories и переносить код из WIP только выборочно после проверки против новых acceptance criteria. + +**Плюсы:** сохраняет полезное исследование; уменьшает blast radius; даёт отдельные security, persistence, API и UX gates; исключает повторное поглощение миллионов tokens одной сессией. +**Минусы:** четыре dev/review цикла; интеграционный пользовательский outcome появляется после 2.1d. + +### Вариант 2 — увеличить timeout и повторить исходную Story 2.1 (отклонён) + +Не устраняет смешение filesystem security, database lifecycle, HTTP orchestration и browser UX. Повышает стоимость и риск ещё одной незавершённой попытки. + +### Вариант 3 — удалить WIP и переписать Story 2.1 целиком (отклонён) + +Даёт чистый старт, но без необходимости теряет уже найденные подходы, тестовые seams и UI race guards. Rescue-ветка безопаснее и не загрязняет `main`. + +## 4. Изменение backlog: до и после + +### До + +`2-1-openapi-source` одновременно реализует crate, filesystem durability/security, registry v12, repository, lifecycle reconciliation, Admin API multipart, UI, docs и все уровни тестов. + +### После + +| Story | Authoritative outcome | Основной gate | +|---|---|---| +| `2-1a-openapi-artifact-store` | Immutable content-addressed filesystem boundary | known digest, atomic/durable write, verified read, corruption, crash/disk-full seams, traversal/symlink/root races, legacy-root containment | +| `2-1b-openapi-source-metadata` | Workspace-scoped registry metadata и concurrent-safe lifecycle | forward-only migration/schema guard, cross-scope not-found, commit/crash windows, grace/claim/recheck/delete, backup/restart | +| `2-1c-openapi-upload-preview` | Production bounded multipart Admin API и одни verified bytes для preview/apply | auth/workspace-before-write, 256 KiB/UTF-8/MIME/multipart limits, no-Draft failure, stable RU/EN errors, canary redaction, real router integration | +| `2-1d-openapi-upload-ui-evidence` | Race-safe RU/EN upload UX и release evidence | cancel/replace/stale/workspace/language/accessibility, production endpoint E2E, docs, `just verify`, `just verify-ui` | + +Обязательный порядок: + +`2.1a → 2.1b → 2.1c → 2.1d → 2.2 → … → 2.9` + +Story 2.2 не начинается до завершения 2.1d: Epic 2 получает законченный production vertical slice, включая operator/browser evidence, прежде чем расширять parser pipeline. + +## 5. Обращение с остановленной попыткой + +- WIP сохранён в ветке `rescue/story-2-1-timeout` коммитом `90f377d` (`wip: preserve timed-out Story 2.1 attempt`). +- Baseline `main` остаётся на `182bde8ac0709709be849f5ab51d2ce02aa5410b` до начала новой разработки. +- Старый run `20260825-014249-1de8` остановлен и архивирован; его рабочее дерево не используется как новый baseline. +- Старый `spec-2-1-openapi-source.md` помечен `superseded` и служит только историческим/audit reference. +- Запрещён wholesale merge/cherry-pick WIP. Каждая часть переносится выборочно, после проверки против своей story и текущего кода. + +## 6. Артефакты, изменённые предложением + +- `planning-artifacts/epics.md` — Story 2.1 заменена Stories 2.1a–2.1d; обновлены delivery order и scope rationale. +- `implementation-artifacts/sprint-status.yaml` — старый backlog key заменён четырьмя новыми ключами. +- `implementation-artifacts/epic-2-context.md` — обновлены story map и dependency chain. +- `planning-artifacts/implementation-readiness-report-2026-08-08.md` — актуализирована FR-7/FR-9 traceability без изменения verdict. +- `test-artifacts/test-design/crank-handoff.md` — риск R-002 привязан к новым story IDs. +- `implementation-artifacts/spec-2-1-openapi-source.md` — помечен как superseded historical artifact. + +PRD и Architecture Spine не требуют правок. + +## 7. Handoff и контроль выполнения + +1. Product/architecture: изменение уже утверждено; новые product decisions не требуются. +2. Development: начинать только `2.1a`, на чистом `main`; WIP использовать как справочный материал. +3. Security review: обязателен внутри 2.1a и 2.1b до перехода к HTTP surface. +4. Code review: отдельный adversarial review после каждой story; найденные дефекты исправляются до следующей dependency. +5. QA: outer multipart и browser tests не заменяются internal service tests; 2.1d закрывает вертикальный release gate. +6. Loop orchestration: сначала `validate` и dry-run одной Story 2.1a; реальную разработку запускать отдельным решением. + +## 8. Критерии успешности корректировки + +- `bmad-loop validate` принимает обновлённый sprint tracking. +- Dry-run выбирает `2-1a-openapi-artifact-store` первой и не включает старый `2-1-openapi-source`. +- `main` не содержит частичный код остановленной попытки. +- Rescue-коммит и архив run доступны для аудита и выборочного восстановления. +- В planning/context/test artifacts нет активных зависимостей на старый ключ Story 2.1. + diff --git a/_bmad-output/planning-artifacts/sprint-change-proposal-2026-08-26.md b/_bmad-output/planning-artifacts/sprint-change-proposal-2026-08-26.md new file mode 100644 index 0000000..b99ba91 --- /dev/null +++ b/_bmad-output/planning-artifacts/sprint-change-proposal-2026-08-26.md @@ -0,0 +1,34 @@ +# Sprint Change Proposal: стабилизация Story 2.1b + +## 1. Причина изменения + +Story 2.1b остановилась после шестого review-pass: общий набор тестов проходил, но реализация всё ещё нарушала уже зафиксированные правила continuation/recovery, exact V12 schema guard и обязательную fault/race matrix. Продуктовой неоднозначности нет (`intent_gap: 0`); проблема — слишком большой технический срез и накопление требований между repair-loop. + +## 2. Влияние + +- **PRD:** без изменений; требования production-grade OpenAPI, isolation и recovery сохраняются. +- **Epic 2:** цель, порядок и зависимости не меняются. Story 2.1c по-прежнему зависит от полностью закрытой Story 2.1b. +- **Архитектура и UX:** без изменений; HTTP/UI остаются вне scope 2.1b. +- **Sprint tracking:** без изменений в рамках escalation resolver. + +## 3. Принятое решение + +Разделить Story 2.1b на две independently reviewable stories без ослабления исходного контракта: + +1. `2-1b-openapi-source-metadata` — V12 schema, exact guard, workspace-scoped repository и verified-read outcomes. +2. `2-1b2-artifact-reconciliation` — bounded filesystem scan/quarantine, claim/recheck/unlink, continuation и crash/race recovery. + +Story 2.1c зависит от обеих. Текущий escalated key сохраняется за metadata story; reconciliation получает новый key и отдельный dev/review cycle. + +## 4. Критерии успеха + +- После delete при оставшейся работе возвращается continuation; тест не маскирует дефект повторным запуском с `None`. +- `uncertain`/retryable post-mutation outcome сохраняет безопасный recovery path без пропуска item. +- V12 guard выполняет exact canonical comparison всех перечисленных schema objects. +- Все перечисленные race/fault tests зарегистрированы отдельно и проходят вместе с workspace gates. + +## 5. Handoff + +Изменение умеренное и требует backlog reorganization, но не меняет PRD или architecture spine. Текущий resolver уточняет frozen spec `2.1b` и planning artifacts, не изменяя принадлежащий orchestrator файл `sprint-status.yaml`. После re-arm Developer завершает metadata story; Product Owner/orchestrator материализует `2-1b2-artifact-reconciliation` в sprint tracking перед `2.1c`. Reviewer не расширяет frozen intent: новая самостоятельная потребность оформляется отдельной story, а нарушение существующей safety-инварианты эскалируется человеку. + +Решение одобрено пользователем 2026-08-26. diff --git a/_bmad-output/project-context.md b/_bmad-output/project-context.md new file mode 100644 index 0000000..dcf252b --- /dev/null +++ b/_bmad-output/project-context.md @@ -0,0 +1,270 @@ +--- +project_name: 'crank' +user_name: 'Bsodfather' +date: '2026-08-02' +sections_completed: ['technology_stack', 'language_specific_rules', 'framework_specific_rules', 'testing_rules', 'code_quality_style_rules', 'development_workflow_rules', 'critical_dont_miss_rules'] +existing_patterns_found: 14 +status: 'complete' +rule_count: 152 +optimized_for_llm: true +--- + +# Project Context for AI Agents + +_Этот файл содержит критические правила и паттерны, которым AI-агенты должны следовать при реализации кода в этом проекте. Основное внимание уделяется неочевидным деталям, которые иначе легко упустить._ + +--- + +## Технологический стек и версии + +### Контрактная платформа + +- Crank workspace `0.3.1`; Rust Edition `2024`, Cargo resolver `3`. +- MSRV: Rust `1.96`; закреплённый toolchain разработки и сборки: `1.96.1`. +- Backend: Axum `0.8`, Tokio `1`, SQLx `0.9`, Reqwest `0.12`, Serde `1`, thiserror `2`. +- Observability: metrics `0.24.6`, OpenTelemetry `0.32.x`, tracing `0.1`, Sentry `0.49.0`. +- Storage: PostgreSQL `16-alpine`; опционально Valkey `8-alpine` через Redis client `0.29`. +- UI: Node.js `22-alpine`, vanilla JavaScript + Alpine.js `3.15.12`, js-yaml `5.2.2`, esbuild `0.28.1`; runtime image — nginx `1.27-alpine`. +- E2E: Playwright `1.61.1`, Chromium; Rust integration tests — Testcontainers `0.27`. + +### Воспроизводимость версий + +- `Cargo.toml` задаёт поддерживаемые диапазоны прямых зависимостей; `Cargo.lock` фиксирует точную Rust-сборку. +- `apps/ui/package.json` и `package-lock.json` совместно задают точную frontend-сборку; использовать `npm ci`, а не `npm install`. +- Не менять Rust toolchain, MSRV, Edition, Docker base images или зависимости попутно с функциональной задачей. +- Dependency update оформлять отдельным изменением с обновлёнными lock-файлами и успешным `just verify`. +- Не пытаться автоматически устранять несколько major-версий транзитивных crates: сначала определить владельца dependency path и проверить совместимость. +- Проверки зависимостей требуют `cargo-deny 0.20.2`, `cargo deny --locked` и `npm audit --audit-level=high`. +- Локальная версия Node.js отдельно не закреплена; до появления `engines` или toolchain-файла использовать Node.js 22. + +## Критические правила реализации + +### Языковые правила + +#### Rust + +- Соблюдать Rust Edition `2024` и MSRV `1.96`; более новые возможности языка требуют отдельного обновления MSRV и toolchain. +- Возвращать ошибки через `Result` и типизированные enum на `thiserror`; сохранять стадию отказа: schema, mapping, adapter, persistence, external service или runtime. +- В production-коде не использовать `unwrap`, `expect`, `todo!`, `unimplemented!`, `dbg!` и panic на путях, зависящих от пользовательского ввода, I/O или внешнего состояния. +- Panic допустим только для внутреннего инварианта, который невозможно нарушить через публичный API; исключение должно быть локальным, объяснимым и покрытым тестом. Существующие исключения не считать прецедентом. +- `unsafe` запрещён по умолчанию. Его добавление требует отдельного архитектурного решения, минимального блока и тестов вокруг границы безопасности. +- Идентификаторы моделировать отдельными типами (`OperationId`, `WorkspaceId` и т. п.), а не `String`. +- По умолчанию сохранять элементы приватными; предпочитать `pub(crate)` перед `pub`. Публичные re-export перечислять явно и не расширять API ради удобства соседнего модуля. +- Использовать `async` только на I/O-границах. Schema validation, mapping и чистая доменная логика остаются синхронными; production-код `crank-core` не должен зависеть от Tokio. +- Не применять лишние `clone` и `Arc>` как способ обойти проектирование ownership. +- Использовать `new()` для простого гарантированно валидного создания, `try_new()` — когда возможна ошибка валидации. +- JSON и YAML должны сериализовать одну доменную модель. Изменения `serde` names/tags, discriminator `kind`, defaults, timestamp format или `skip_serializing_if` считать изменениями wire-контракта и сопровождать contract/roundtrip tests. +- `#[allow(...)]` задавать в минимальной области и только для конкретного lint; не использовать crate-wide suppressions для обхода `-D warnings`. + +#### JavaScript + +- Работать в рамках текущего vanilla-JS pipeline: `scripts/build.js` конкатенирует файлы в упорядоченные bundles и компилирует их с target `es2019`. +- Внедрение TypeScript, ESM или другого bundler/module model требует отдельного архитектурного изменения; не смешивать такую миграцию с функциональной задачей. +- Перед добавлением top-level `const`, `let`, class или функции проверять все файлы того же bundle: после конкатенации они разделяют lexical scope и могут конфликтовать. +- Порядок файлов в `BUNDLES` является зависимостью выполнения. Между bundles обмениваться только через явно именованные `window.Crank*` API и DOM events. +- Общие browser API изолировать в IIFE и публиковать через согласованное пространство `window.Crank*`; не создавать случайные globals. +- Playwright-тесты и Node build scripts используют CommonJS (`require`, `module.exports`); не переносить этот формат в browser-код. +- HTTP-вызовы выполнять через `window.CrankApi`: dynamic path segments кодировать через `encodeURIComponent`, query собирать через `URLSearchParams`. +- Сохранять API error contract (`error.status`, `error.payload`) и централизованную обработку `401`; async UI-операции должны явно обновлять loading/error state. +- Внешние значения выводить через `textContent`/DOM API. `innerHTML` допустим только для контролируемого шаблона при явном экранировании каждого внешнего значения. + +### Framework-specific правила + +#### Backend и архитектурные слои + +- Соблюдать направление workspace-зависимостей, проверяемое `scripts/check-rust-boundaries.sh`: apps собирают crates, но crates не зависят от apps; `crank-core` находится ниже registry, runtime и adapters. +- Boundary scripts — исполняемые guardrails, а не лазейка: не обходить их через aliases, fully-qualified paths, re-exports или перенос запрещённого вызова в helper. +- Осознанное изменение архитектурной границы оформлять отдельным change: одновременно обновлять код, `docs/architecture.md`, boundary checks и их tests. +- `crank-core::domain` содержит доменные типы, `crank-core::ports` — контракты внешних зависимостей. Core не импортирует Axum, SQLx, Reqwest, Tokio или tracing в production-коде. +- Apps являются composition roots: они выбирают конкретные implementations ports и связывают registry, runtime, adapters и transport; не переносить это wiring в domain crates. +- В `admin-api` routes владеют Axum extractors и HTTP responses; `service/*` владеют use cases и не импортируют Axum; routes не вызывают `crank-runtime` напрямую. +- HTTP payloads и view models размещать в `apps/admin-api/src/dto.rs`; не протаскивать transport DTO в service/domain. +- `crank-registry` владеет persistence records, requests, PostgreSQL facade и migrations; он не импортирует HTTP framework/client и не зависит от runtime/adapters. +- `crank-runtime` оркестрирует execution и не зависит от registry, Axum или SQLx. Apps передают ему уже разрешённые зависимости и context. +- Новые execution parameters добавлять в `RuntimeExecutionRequest`; не создавать семейство методов `execute_with_*`. +- REST request/response behavior размещать в `crank-adapter-rest`, а не в runtime или registry. +- MCP headers, Accept negotiation, session id и JSON/SSE semantics изменять в `crank-community-mcp/src/transport.rs`; изменение сопровождать transport protocol integration tests. +- Product-код записывает метрики только через типизированный `crank-metrics`; имена и labels не объявлять напрямую в других crates. +- `crank-observability` может зависеть от `crank-metrics`, но domain/runtime crates не должны зависеть от observability implementation. + +#### UI и Alpine.js + +- Текущая UI-модель: `Alpine.data(...)` для локального состояния страницы/feature; общие auth, API, workspace, i18n и diagnostics находятся в `window.Crank*` сервисах. +- Переход на другую модель frontend state/framework требует отдельного migration change; не смешивать две модели состояния внутри функциональной задачи. +- Перед workspace-зависимыми запросами ожидать `window.whenWorkspacesReady()` и реагировать на `crank:workspacechange`. +- Async response не должен обновлять экран, если workspace или request generation изменились после начала запроса; использовать identity/version guard против stale responses. +- Сессионные и языковые изменения распространять через `crank:sessionchange` и `crank:langchange`; новые межкомпонентные события именовать `crank:*`, а их `detail` считать внутренним контрактом. +- Event listeners регистрировать один раз на жизненный цикл страницы либо явно снимать при уничтожении повторно создаваемого компонента. +- Protected pages загружают `protected-core` и проходят `window.CrankAuth.guardProtectedPage()`; не копировать auth guard локально. +- Новые страницы/scripts подключать через `BUNDLES` и placeholders в `scripts/build.js`; не ссылаться из HTML на unhashed source-файлы. +- Для async экранов поддерживать loading, error и empty states; после workspace/language change обновлять данные без полной перезагрузки. +- Новый пользовательский текст проводить через i18n helpers и добавлять одновременно для `ru` и `en`; существующий hardcoded текст считать legacy, а не образцом. + +### Правила тестирования + +- Каждый тест должен доказывать наблюдаемый контракт или конкретный риск, а не повторять внутренний алгоритм реализации. +- Исправление бага начинать с теста, воспроизводящего регрессию; затем исправлять код и подтверждать прохождение нового и существующих тестов. +- Короткие pure unit tests приватной логики допустимы рядом с модулем. PostgreSQL, HTTP servers, fake upstreams и multi-module flows размещать в `tests/`. +- Unit tests покрывают schema validation, JSONPath/mapping и чистые части `crank-core`; не поднимать transport/storage для проверки доменной функции. +- Registry integration tests используют реальный PostgreSQL `16-alpine` через `crank-test-support`/Testcontainers. +- Получать test database через `postgres_schema_url(...)`: общий container допустим, но каждый тест/suite использует уникальную schema. Не вводить фиксированную shared schema или внешнюю вручную настроенную test DB. +- Runtime и adapters тестировать отдельно: request preparation, mapping stages, normalized responses, errors, confirmation, idempotency, cache/Valkey и execution metrics. +- Admin API тестировать на поднятом Axum application с реальными service/registry boundaries; MCP transport — через Streamable HTTP contract tests. +- Обязательные regression areas: schema validation, invalid JSONPath, YAML import/export roundtrip, version increment, publish semantics, auth profile resolution, generated draft application и полный MCP execution path. +- Workspace/authz изменения включают negative tests на cross-workspace access, отсутствующую/неверную credential и недостаточный scope. +- Изменения observability проверяют redaction, correlation propagation, bounded metric labels и отсутствие секретов в logs/events. +- Изменение UI async/workspace logic должно моделировать перестановку ответов и доказывать, что stale response не перезаписывает состояние нового workspace. +- Для readiness/eventual consistency использовать assertions или bounded polling с диагностируемым timeout. Фиксированный sleep сам по себе не является синхронизацией. +- Fixtures хранить рядом с suite (`tests/fixtures/` при повторном использовании); секреты и реальные credentials не помещать в fixtures, snapshots или failure output. +- Не вводить глобальный процент coverage без отдельного решения: критерий — доказательство перечисленных контрактов и рисков. +- Для Rust сначала запускать целевой suite, затем `just test`; перед завершением значимого backend/change — `just verify`. Полный Rust suite требует доступный Docker. +- `just verify` не запускает UI build или Playwright. UI change требует `npm ci`, `npm run build` и Playwright: + - изолированный экран — его spec плюс затронутые shared smoke scenarios; + - shared auth/API/workspace/bundle code — полный `npm run e2e`. +- Playwright использует существующие helpers (`login`, `browserJson`, `getCurrentWorkspace`, `uniqueName`, `localized`), запускается с одним worker и не зависит от порядка spec-файлов. +- Локальный Playwright stack использует фиксированные default ports/container name; не запускать несколько default E2E stacks параллельно в одном окружении. +- При изменении SQLx macros/schema сначала обновлять offline metadata через `just sqlx-prepare `, затем выполнять `just sqlx-check` и migration/integration tests. + +### Правила качества и стиля кода + +- Process environment читается один раз только leaf crate `crank-config` до + observability, DB, workers и listeners. Reusable crates принимают validated + values; новый runtime field добавляется через registry, generated contract, + examples и `just config-contract-check`. + +#### Автоматические проверки + +- Rust-код форматировать через `cargo fmt --all`; перед завершением выполнять `just fmt-check`. +- Clippy запускается для всего workspace, всех targets и features с `-D warnings`. Новый warning исправлять либо подавлять минимальным обоснованным `#[allow]`. +- `scripts/check-rust-code-health.sh` проверяет все Rust-файлы, включая tests: новый файл — не более `1000` строк, inline test module — не более `500`. +- Лимиты являются верхним guardrail, а не целевым размером. Декомпозировать по ответственности раньше, если модуль становится трудно обозримым. +- Legacy-файлы из debt baseline не должны расти выше закреплённого потолка. При изменении выделять service/route/runtime helper или переносить integration tests в `tests/`. +- Не смешивать функциональное изменение с массовым форматированием, переименованием или unrelated cleanup. + +#### Именование и организация + +- Rust modules/files/functions/variables — `snake_case`; types/traits — `PascalCase`; constants — `SCREAMING_SNAKE_CASE`. +- Доменные ID оканчивать на `Id`, типизированные ошибки — на `Error`; persistence inputs/outputs сохранять в `requests`/`records`, HTTP models — в DTO layer. +- JavaScript source files именовать lower `kebab-case`; browser namespaces — `window.Crank*`; DOM events — `crank:*`; Playwright specs — `*.spec.js`. +- Новую логику размещать в минимальном владеющем слое. Не создавать catch-all `utils`/`helpers`, если у кода есть явный domain, transport, registry или UI owner. +- Комментарии объясняют причину, invariant, безопасность или внешний контракт; не пересказывают очевидный код. +- При изменении API, runtime config, deployment behavior, schema или operational procedure обновлять соответствующий документ в `docs/` тем же change. + +#### JavaScript style + +- В UI нет ESLint/Prettier-конфигурации. Следовать локальному стилю соседнего файла и проверять результат через build/E2E. +- Не вводить новые локальные style conventions и не модернизировать legacy `var`/function syntax без функциональной или отдельной migration-задачи. +- Успешный esbuild не заменяет lint/security review: отдельно проверять globals, bundle ordering, DOM sinks и async state. +- Повторяемую browser-логику сначала искать в `CrankApi`, `CrankAuth`, `CrankDom`, `CrankUi`, i18n и других существующих `window.Crank*` модулях. + +#### Зависимости и generated artifacts + +- Выбирать сначала `std`, затем существующие внутренние abstractions и только после этого новый внешний crate/package. +- Не добавлять wildcard versions или дублирующую библиотеку без подтверждённого use case. +- Rust dependency проходит `cargo deny --locked`; лицензия и точечные exceptions регулируются `deny.toml`. Не добавлять глобальные license exceptions. +- npm dependency проходит `npm audit --audit-level=high`; лицензионную совместимость проверять отдельно, поскольку `npm audit` её не подтверждает. +- `.sqlx/query-*.json` — единый generated metadata set: обновлять через `just sqlx-prepare`, просматривать добавленные и удалённые файлы и не редактировать их вручную. +- Не коммитить `target`, `apps/ui/dist`, `node_modules`, Playwright reports/results, `.tmp`, `.env` и runtime logs; `.env.example` остаётся документированным шаблоном без секретов. + +### Правила процесса разработки + +#### Git и pull requests + +- До изменения и перед handoff проверять `git status`, `git diff` и staged diff; сохранять существующие пользовательские правки и не включать unrelated files. +- В репозитории нет обязательного commit-message schema. Использовать короткий предметный imperative subject в стиле соседних commits; не вводить Conventional Commits или обязательный язык без отдельного решения. +- Не переписывать историю, не force-push и не отправлять изменения в remote без явного запроса пользователя. +- Запрос на commit сам по себе не разрешает push, merge, создание tag, release или deployment. +- Перед pull request выполнять `just verify`; для UI дополнительно `npm ci`, `npm run build` и требуемый Playwright suite. +- Pull request contributor должен выполнить требования `CLA.md`; агент не должен утверждать принятие CLA от имени человека. +- Gitea CI запускается для любого pull request и для push в `main`/`feat/**`. Это trigger configuration, а не общая branch naming policy. +- Push feature-ветки вне `feat/**` не запускает push-trigger CI, но CI всё равно запустится после открытия pull request. + +#### Границы Community + +- Не добавлять функциональность за пределами Community scope: текущая реализация — REST как источник MCP tools, простая admin auth, agent keys, single self-hosted deployment, PostgreSQL и optional Valkey/Redis. Resources, Prompts, Tasks и Load Runs являются разрешённым planned расширением, но до реализации имеют только `planned`, `gap` или `blocked` в `docs/capability-inventory.json`; только `implemented` считается pass. +- `scripts/check-community-scope.sh` по умолчанию сканирует только `git ls-files` и не видит untracked files. +- Перед handoff убедиться, что новые файлы tracked/staged, либо проверить их напрямую: `python3 scripts/check-community-scope.py --root . --files `. +- Capability baseline использует три независимые оси: implementation status, + execution verdict и evidence mode. Полный pass — только + `implemented + automated + pass`; retry-pass остаётся flaky, а + skipped/not-run/manual-only не повышаются до pass. +- Изменение canonical baseline artifact требует нового `baseline_version` и + lowercase SHA-256 exact bytes в `docs/capability-baseline/manifest.json`. + Raw browser reports, credentials, payloads и host paths не являются canonical + evidence. +- Не обходить forbidden markers переносом текста, aliases или переименованием. +- `community-scope: allow=` использовать только для необходимого упоминания; исключение не разрешает out-of-scope реализацию и должно быть очевидно обосновано в diff. +- Не коммитить `AGENTS.md`, `TASKS.md`, `.env`, secrets, private addresses или локальные настройки. + +#### CI, deployment и release + +- Изменение CI проверять относительно `.gitea/workflows/*.yml` и Gitea Actions runner; не добавлять GitHub-only assumptions без проверки совместимости. +- Push в `main` после Rust, UI, E2E и image-smoke jobs автоматически запускает production Deploy. Merge/push в `main` требует явного разрешения пользователя с пониманием этого side effect. +- Создание tag `v*` запускает Community Release с публикацией artifacts/images. Commit или push authorization не включает разрешение создавать release tag. +- Release pipeline включает quality gates, release builds, UI E2E, Compose validation, image scan, SBOM и публикацию artifacts/images. +- Source of truth для Community deployment находится в `deploy/community/`; изменения проверять через Compose validation, image build и authenticated product smoke. +- Миграции Community должны быть обратно совместимы с предыдущей версией приложения; schema/deploy change включает readiness, backup и rollback considerations. +- После deployment-sensitive изменений выполнять соответствующий staging smoke из `docs/deploy-and-staging-smoke.md`. +- Результаты фиксировать в `docs/staging-regression-notes.md` без credentials, tokens, private payloads или secret-bearing raw logs. +- CI/CD secrets загружаются через OpenBao. Не печатать secret values, не переносить их в workflow files и не заменять secret storage committed `.env`. + +### Критические правила, которые нельзя упустить + +#### Изоляция workspace и секреты + +- Для workspace-зависимого запроса получать `WorkspaceId` только из проверенного auth/request context. Отсутствующий или чужой workspace не заменять default workspace. +- Проверять принадлежность каждой сущности workspace, а не только существование её ID. Чужая сущность должна давать безопасный `not found`/`denied`, без раскрытия метаданных. +- Любое состояние, результат или разрешение, зависящие от workspace, agent или auth context, кэшировать с полным security scope. Глобальный кэш допустим только для доказанно инвариантных данных. +- В operation/config/YAML/static headers хранить только `auth_profile_ref` или ссылку на secret, но не credential в открытом виде. +- Stored secret после передачи шифруется и не возвращается через create/get/list/rotate. Raw API key разрешено показать только в ответе создания; сохранять только безопасный prefix/hash. +- Один и тот же master key должен использоваться `admin-api` и MCP. Его смена без процедуры re-encryption/migration делает сохранённые secrets недоступными. +- До сериализации логов и ошибок удалять authorization, cookies, tokens, secret values и чувствительные payload/query fields. Не логировать произвольные структуры через `Debug`. + +#### Outbound execution и safety controls + +- SSRF-policy применять к фактическому адресу каждого соединения после DNS resolution. Блокировать loopback, private, link-local и service addresses; redirects и system proxy оставлять выключенными. +- Deny rules имеют приоритет над allow rules. Семантика outbound policy должна совпадать в `admin-api` и MCP. +- Timeout, response-byte limit и concurrency limit применять до неограниченного ожидания или накопления response body. +- В MCP публиковать и исполнять только опубликованные версии operations; draft не должен становиться доступным через обходной lookup. +- Confirmation token привязывать к workspace, agent, operation, version и fingerprint входа; соблюдать TTL и single-use consumption. +- Approval проверяет workspace/agent/operation/version, status, expiry и полномочия approval key. Переходы состояния должны быть атомарными; bypass safety flow недопустим. +- Idempotency key scope включает workspace, agent, operation и version; fingerprint входа обязателен. Повтор того же key с другим входом является конфликтом. +- `IdempotencyOutcomeUnknown` не ретраить автоматически: внешний side effect мог уже произойти. +- Если обязательное coordination/cache/approval store недоступно, safety-механизм должен fail closed, а не молча отключаться. + +#### Observability без утечек и cardinality explosion + +- Имена log events и наборы metric labels должны быть статическими и низкокардинальными. Не помещать ID, URL, имена, request text или error text в labels. +- Входящий `x-request-id` валидировать и ограничивать; недопустимое значение заменять UUIDv7. Request ID распространять отдельно от trace identity. +- Системные correlation headers должны переопределять mapped/static пользовательские headers. +- При публикации Prometheus не только на loopback требовать отдельный bearer token. +- Недоступность OTLP/Sentry после успешного startup не должна менять product response или readiness. Явно заданная некорректная конфигурация должна завершать startup безопасной ошибкой. +- Events, previews и JSON-поля ограничивать по размеру с сохранением корректного UTF-8/JSON; не обрезать сериализованные данные произвольным byte slice. + +#### Миграции и восстановление данных + +- `crank-registry::MigrationAuthority` — единственный владелец runtime DDL и append-only migration sequence. Не изменять смысл, statement order или ledger checksum immutable baseline v1; новое изменение схемы всегда получает следующую contiguous `i64` version и lowercase SHA-256 exact source bytes. +- Admin API и MCP startup выполняют только read-only compatibility preflight. Схему изменяет исключительно controlled `crank-migrate apply`; Community Compose обязан завершить one-shot migration job до запуска обоих сервисов. +- Каждая migration должна быть transactional, иметь owner/phase/compatibility/backfill metadata и выполняться под canonical transaction-level PostgreSQL advisory lock. Никаких `down`, `force`, implicit repair или локальных ledger/runner в runtime crates. +- Schema changes должны поддерживать rolling update и rollback предыдущей версии; destructive change проводить поэтапно через expand/migrate/contract. +- PostgreSQL и artifact storage считать единым backup set; процедура restore должна восстанавливать согласованную пару. +- Изменение любого правила этого раздела требует negative regression tests на соответствующую границу безопасности или целостности. + +--- + +## Правила использования + +**Для AI-агентов:** + +- Прочитать этот файл до начала реализации или ревью кода. +- Следовать всем применимым правилам; при сомнении в security/safety выбирать fail-closed вариант. +- Не менять описанные границы или контракты попутно с функциональной задачей. +- Обновлять файл, когда в проекте появляется новый неочевидный и устойчивый паттерн. + +**Для людей:** + +- Сохранять файл компактным и ориентированным на практические решения агентов. +- Обновлять версии и правила вместе с изменением соответствующих контрактов проекта. +- Периодически удалять устаревшие правила и сведения, ставшие очевидными из автоматических guardrails. + +Последнее обновление: 2026-08-02 diff --git a/_bmad-output/test-artifacts/atdd-checklist-1-1-capability-inventory.md b/_bmad-output/test-artifacts/atdd-checklist-1-1-capability-inventory.md new file mode 100644 index 0000000..13e67c0 --- /dev/null +++ b/_bmad-output/test-artifacts/atdd-checklist-1-1-capability-inventory.md @@ -0,0 +1,200 @@ +--- +stepsCompleted: ['step-01-preflight-and-context', 'step-02-generation-mode', 'step-03-test-strategy', 'step-04c-aggregate', 'step-05-validate-and-complete'] +lastStep: 'step-05-validate-and-complete' +lastSaved: '2026-08-08' +storyId: '1.1' +storyKey: '1-1-capability-inventory' +storyFile: '_bmad-output/planning-artifacts/epics.md' +atddChecklistPath: '_bmad-output/test-artifacts/atdd-checklist-1-1-capability-inventory.md' +generatedTestFiles: + - 'tests/unit/test_validate_capability_inventory.py' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/project-context.md' + - '_bmad-output/test-artifacts/test-design-epic-1.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' + - 'scripts/check-community-scope.py' + - 'tests/unit/test_check_community_scope.py' + - 'apps/ui/playwright.config.js' +--- + +# ATDD Checklist — Story 1.1 Capability Inventory + +## Step 1: Preflight and Context + +- **Detected stack:** fullstack (Rust backend plus existing Playwright UI), while Story 1.1 itself is a repository-level Python/CLI/schema guardrail with no new browser behavior. +- **Story approval:** acceptance criteria are complete in `_bmad-output/planning-artifacts/epics.md`, Story 1.1. +- **Framework readiness:** Python `unittest` runs in `just test` and Gitea CI; Rust and Playwright frameworks are configured. Development environment is available. +- **Story key:** `1-1-capability-inventory`; **Story ID:** `1.1`. +- **Affected contracts:** Capability Inventory schema, validator CLI, machine-readable inventory, evidence references, Community scope scanner/guardrails, Community docs and `project-context.md`. +- **Risk links:** E1-R-001 (score 9), coverage groups E1-01 and E1-02. +- **Existing pattern:** `scripts/check-community-scope.py` exposes deterministic stdlib CLI behavior and explicit `--files`; `tests/unit/test_check_community_scope.py` uses temporary repositories and subprocess assertions. +- **TEA flags:** Playwright Utils on; Pact.js Utils off; Pact MCP off; browser automation auto; stack auto→fullstack. Contract testing is relevant at CLI/schema boundary; browser automation is not required for this Story. +- **Preflight result:** PASS. No prerequisite or user input is missing. + +## Step 2: Generation Mode + +- **Mode:** AI generation. +- **Reason:** Story 1.1 is a deterministic repository CLI/schema contract. Acceptance criteria are explicit, existing subprocess/unit patterns are authoritative, and no live UI selector or interaction must be recorded. +- **Browser state:** no session opened; no recording artifact created. + +## Step 3: Test Strategy + +### Acceptance-criteria mapping + +| Scenario | Acceptance contract | Level | Priority | Red-phase mechanism | +|---|---|---|---|---| +| ATDD-1.1-01 | Valid inventory requires unique ID, `ui/api/mcp`, FRs, outcome, owner, status and evidence | CLI contract/unit | P0 | Future validator script and schema do not exist | +| ATDD-1.1-02 | `implemented/planned/gap/blocked` accepted, while last three never counted as pass | CLI contract | P0 | Future summary/status logic absent | +| ATDD-1.1-03 | Duplicate ID, unknown status, owner missing and required field missing fail with stable codes | CLI contract | P0 | Future validation rules absent | +| ATDD-1.1-04 | Missing mandatory FR and broken evidence reference fail | CLI/filesystem integration | P0 | Future required-FR/evidence resolution absent | +| ATDD-1.1-05 | Error report is deterministic, ≤64 KiB and does not echo secret canaries/raw invalid payload | CLI security contract | P0 | Future bounded/redacted reporter absent | +| ATDD-1.1-06 | `resources`, `prompts`, `tasks`, `load_runs` are allowed planned capability kinds | CLI/schema contract | P0 | Future capability enum absent | +| ATDD-1.1-07 | `multi_workspace`, `enterprise_rbac`, `sso`, `non_rest_upstream`, `arbitrary_distributed_load_targets` remain forbidden even with allow-marker text | CLI/schema security | P0 | Future scope contract absent | +| ATDD-1.1-08 | Canonical inventory/schema/docs/project context files exist and do not claim planned target capabilities are implemented | Repository contract | P1 | Required artifacts/markers absent | + +### Contract decisions for the red scaffold + +- Canonical CLI: `scripts/validate-capability-inventory.py`. +- Canonical artifacts: `docs/capability-inventory.json` and `docs/schemas/capability-inventory.schema.json`. +- CLI accepts `--root`, `--inventory`, `--schema` and repeatable `--required-fr`; tests use temporary repositories and JSON only, adding no dependency. +- Deterministic failures use stable machine codes and sorted paths; sensitive values are never printed. Maximum human report is 64 KiB. +- Inventory `flows[]` owns `id`, `type`, `requirements`, `user_outcome`, `owner`, `status`, `capabilities` and `evidence`. Evidence links are repository-relative and must resolve to regular files. +- These are external test contracts, not implementation prescriptions: internal parsing/validation structure remains free. + +### Existing green evidence retained, not duplicated + +- `tests/unit/test_check_community_scope.py` already proves explicit `--files` scanning, forbidden markers, narrow inline directives and binary/default exclusions. +- New red tests focus on the missing Inventory-aware contract; they do not duplicate current scope-scanner branch tests or introduce browser tests. + +### Red-phase expectation + +All newly generated acceptance tests describe behavior that will fail before implementation because the validator/schema/inventory documentation contract is absent. During the shared RED-scaffold phase they are deliberately decorated with `@unittest.skip(RED_PHASE)` so ordinary CI stays green; each test is activated task-by-task and must be observed failing before the corresponding implementation is added. + +## Step 4: RED-Phase Test Scaffolds + +### Generation result + +- **Execution:** SUBAGENT (API + E2E); capability probe enabled and resolved to the available subagent runner. +- **CLI/API contract tests:** 10 scenarios in `tests/unit/test_validate_capability_inventory.py`, all guarded by `@unittest.skip(RED_PHASE)`. +- **E2E browser tests:** 0. Story 1.1 introduces no UI journey, so browser scaffolding would duplicate the repository-level CLI contract. +- **TDD compliance:** PASS. Every generated test has a RED-phase skip guard, contains behavioral assertions rather than placeholders, and is marked `expected_to_fail` in generation metadata. +- **Browser session:** not opened. + +### Acceptance Criteria Coverage + +1. Complete inventory schema and every `ui`/`api`/`mcp` flow field are covered by the valid-inventory scenario. +2. The four statuses are accepted, while only `implemented` contributes to pass. +3. Duplicate IDs, unknown status/type, missing owner/field, mandatory FR gaps, and invalid evidence links produce stable failures. +4. Reports are deterministic, sorted, redacted, and bounded to 64 KiB. +5. `resources`, `prompts`, `tasks`, and `load_runs` are accepted as planned Community capabilities. +6. Multi-workspace, enterprise RBAC/SSO, non-REST upstream, and arbitrary distributed load targets remain forbidden despite allow-marker text. +7. New/untracked inventory and guardrail files are explicitly scanned with positive and negative coverage. +8. Canonical schema, inventory, Community documentation, and project context exist without promoting planned work to implemented. + +### Fixture Infrastructure + +The Python scaffold contains the minimal RED-phase fixture infrastructure locally: temporary repository factory, canonical-schema installer, flow/evidence factories, validator and scope-scanner subprocess runners, plus a secret canary. Keeping these helpers in the single Story 1.1 module avoids adding an unused cross-suite fixture API before the contract exists. + +### Task-by-Task Activation + +During implementation: + +1. Remove `@unittest.skip(RED_PHASE)` only from the scenario for the current task. +2. Run `python3 -m unittest tests.unit.test_validate_capability_inventory` and observe the activated test fail for the missing behavior. +3. Implement the smallest production change that satisfies the contract, then rerun until green. +4. Keep unrelated scenarios skipped until their implementation task begins. +5. Finish with scope/boundary tests and `just verify` as required by Story 1.1. + +### Implementation Handoff + +- Validator CLI: `scripts/validate-capability-inventory.py` with `--root`, `--inventory`, `--schema`, and repeatable `--required-fr`. +- Canonical schema: `docs/schemas/capability-inventory.schema.json`. +- Canonical inventory: `docs/capability-inventory.json`. +- Community boundary: extend the existing scope checker without weakening narrow allow directives. +- Documentation: link the inventory from Community documentation and `_bmad-output/project-context.md`. +- Story backlink was not inserted because Story 1.1 lives inside the shared `epics.md` and has no dedicated `## Dev Notes` section. Use this checklist and its frontmatter as the implementation handoff. + +### Generated Files + +- `tests/unit/test_validate_capability_inventory.py` +- `_bmad-output/test-artifacts/atdd-checklist-1-1-capability-inventory.md` + +### Summary + +- Total tests: **10**, all skipped in shared RED scaffold. +- API/CLI tests: **10**. +- E2E tests: **0** (not applicable). +- Embedded fixture capabilities: **7**. +- Covered acceptance-contract groups: **8/8**. +- Activated tests are expected to fail until their corresponding behavior is implemented. + +## Step 5: Validation and Completion + +### Validation Result + +- **Prerequisites:** PASS — approved Story 1.1, testable acceptance criteria, working Python `unittest` harness, and existing scope-checker patterns are present. +- **Scaffold syntax/discovery:** PASS — `python3 -m unittest tests.unit.test_validate_capability_inventory` discovered 10 tests and reported `OK (skipped=10)`. +- **RED safety:** PASS — AST inspection found 10 test methods and 10 `@unittest.skip` decorators; no generated acceptance scenario is active in ordinary CI. +- **Acceptance mapping:** PASS — all eight contract groups from Story 1.1 are represented. +- **Handoff metadata:** PASS — story ID/key/source, checklist path, generated test path, activation commands, and implementation targets are recorded. +- **Session cleanup:** PASS — no browser was opened and no CLI/browser process remains. +- **Artifact hygiene:** PASS — transient worker JSON files were removed from `/tmp`; durable summary metadata is stored in `_bmad-output/test-artifacts/atdd-summary-1-1-capability-inventory.json`. +- **Formatting:** PASS — Python compilation and `git diff --check` complete without errors. + +### Applicability Decisions + +- Primary level is **CLI contract / repository integration**. The file lives under the repository's established `tests/unit/` convention even though it exercises subprocess and filesystem boundaries. +- Browser E2E, component tests, selectors, `data-testid`, headed/debug commands, network interception, HTTP status matrices, external mocks, Pact, routes, and UI components are **N/A** for this story. +- Faker/TypeScript factory requirements are **N/A**. Deterministic Python builders are preferable for a schema validator; every test gets a fresh temporary root and `tearDown()` removes it. +- The ten scenarios intentionally group closely related assertions around one contract outcome (for example bounded + deterministic + redacted report). This gives actionable diagnostics without multiplying expensive subprocess setup. + +### Implementation Checklist + +- [ ] Create the canonical JSON schema and a minimal canonical inventory with the required flow fields and enum values. +- [ ] Implement CLI parsing plus structural validation for IDs, types, owners, outcomes, requirements, status, and evidence shape. +- [ ] Implement required-FR completeness and repository-contained regular-file evidence resolution. +- [ ] Implement stable error codes and deterministic, sorted, redacted, 64 KiB-bounded reporting. +- [ ] Encode allowed target capabilities and forbidden Community capability kinds without a text-marker bypass. +- [ ] Extend explicit scope-scanner coverage for new/untracked inventory and guardrail files. +- [ ] Update Community documentation and `_bmad-output/project-context.md` without marking planned capabilities implemented. +- [ ] Activate scenarios task-by-task, prove RED then GREEN, and finish with targeted tests, boundary/scope tests, and `just verify`. + +Estimated implementation effort: **5–8 story points** (roughly 2–4 focused engineering days, excluding review latency). + +### Red–Green–Refactor Contract + +1. **RED:** remove the skip decorator from only the current scenario and run the specific module; retain the failing output in implementation evidence. +2. **GREEN:** implement the smallest compatible behavior until that scenario passes, without changing Rust dependencies, toolchain, or wire contracts. +3. **REFACTOR:** consolidate parser/reporting helpers only while all activated scenarios and existing scope tests remain green. + +Execution commands: + +```bash +# Discover the complete safe scaffold (all scenarios remain skipped initially) +python3 -m unittest tests.unit.test_validate_capability_inventory + +# After activating one or more scenarios +python3 -m unittest -v tests.unit.test_validate_capability_inventory + +# Existing boundary regression suite +python3 -m unittest -v tests.unit.test_check_community_scope + +# Final repository gate +just verify +``` + +### Deliverable Summary + +- Story: **1.1**, key `1-1-capability-inventory`. +- Story source: `_bmad-output/planning-artifacts/epics.md`. +- Primary level: CLI contract / repository integration. +- Tests: 10 CLI/API-contract, 0 E2E, 0 component. +- Generated test file: `tests/unit/test_validate_capability_inventory.py` (388 lines). +- Factories/fixtures: five local builders/runners plus temporary-root lifecycle and secret canary; no shared fixture files required. +- External mock requirements: 0; `data-testid` requirements: 0. +- Implementation tasks: 8; estimate: 5–8 points. +- Durable generation summary: `_bmad-output/test-artifacts/atdd-summary-1-1-capability-inventory.json`. +- Knowledge/patterns applied: API testing patterns, deterministic data factories, contract-testing principles, and the existing Community scope unittest/subprocess convention. +- Next workflow: implement Story 1.1 with `bmad-dev-story`; broader automation expansion follows after GREEN behavior exists. diff --git a/_bmad-output/test-artifacts/atdd-summary-1-1-capability-inventory.json b/_bmad-output/test-artifacts/atdd-summary-1-1-capability-inventory.json new file mode 100644 index 0000000..ea43d9f --- /dev/null +++ b/_bmad-output/test-artifacts/atdd-summary-1-1-capability-inventory.json @@ -0,0 +1,31 @@ +{ + "story_id": "1.1", + "story_key": "1-1-capability-inventory", + "tdd_phase": "RED", + "total_tests": 10, + "api_cli_tests": 10, + "e2e_tests": 0, + "component_tests": 0, + "all_tests_skipped": true, + "expected_to_fail_when_activated": true, + "embedded_fixture_capabilities": 7, + "acceptance_contract_groups_covered": 8, + "subagent_execution": "SUBAGENT (API + E2E)", + "generated_test_files": [ + "tests/unit/test_validate_capability_inventory.py" + ], + "validation": { + "syntax": "passed", + "discovery": "passed", + "tests_discovered": 10, + "tests_skipped": 10, + "browser_session_opened": false, + "orphaned_sessions": false + }, + "knowledge_fragments_applied": [ + "api-testing-patterns", + "data-factories", + "contract-testing", + "existing tests/unit/test_check_community_scope.py pattern" + ] +} diff --git a/_bmad-output/test-artifacts/test-design-architecture.md b/_bmad-output/test-artifacts/test-design-architecture.md new file mode 100644 index 0000000..bf1fccc --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-architecture.md @@ -0,0 +1,196 @@ +--- +workflowStatus: 'completed' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +lastSaved: '2026-09-13' +lastEdited: '2026-09-13' +editScope: 'system-level inventory and evidence-aware strategy refresh' +auditedRevision: '083974c27f3a21a15807dd248bb6bc4fe04a5cd8' +workflowType: 'testarch-test-design' +inputDocuments: + - '_bmad-output/project-context.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad-output/planning-artifacts/epics.md' +--- + +# Test Design for Architecture: Crank Community Production Readiness + +**Purpose:** Architectural testability contract between Engineering, Architecture, Security and QA. It defines what the system must expose so production claims can be proven; execution details live in `test-design-qa.md`. + +**Date:** 2026-09-13 (original design: 2026-08-08) +**Author:** BMad TEA / Bsodfather +**Status:** System-level design updated; production qualification remains unproven +**Project:** crank +**PRD:** `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` +**Architecture:** `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` + +## Executive Summary + +The Community edition is being advanced from a working brownfield REST→MCP core to a production-ready, self-hosted product for small organizations and private developers. Scope covers 54 FRs, 30 NFRs and 8 epics: real-world OpenAPI import; complete modern MCP Tools/Resources/Prompts and Tasks; safe concurrency; end-to-end traceability; Prometheus/Grafana/GlitchTip; built-in load testing; secure offline deployment/recovery; and evidence-backed release. + +Key decisions are a Rust hexagonal modular monolith; PostgreSQL as correctness authority with optional rebuildable Valkey; immutable/versioned capability catalogs; unified outbound execution; durable CAS/fenced Tasks; typed observability/metrics; and a fail-closed signed evidence manifest. + +Expected reference scale is 100 RPS for 30 minutes, a 250 RPS five-minute burst, 128 concurrent executions, 10,000 queued Tasks and a production-size catalog/history dataset on 4 vCPU/8 GiB. Platform overhead is bounded at 50 ms p95/150 ms p99. + +**Risk summary:** 15 risks: 14 high (score ≥6), 1 medium, 0 low. Five score-9 risks are release blockers. Scores describe inherent release risk, not a measured residual defect rate. The August effort estimate is superseded as a remaining-work forecast: significant foundation code and tests now exist. The PRD's 30-day burn-in remains non-accelerable calendar time. + +## Audit Boundary and Evidence State — 2026-09-13 + +This refresh inspects tracked source at `083974c27f3a21a15807dd248bb6bc4fe04a5cd8` (`main`). It does not declare the system production-ready or reopen epic/story implementation. + +- Story 2.9 commit `f8ee7c9bfeaa8a3f73a4850ff3f82b2bc2155fe8` is separate and not integrated into main. Its HTTP-contract tests and prior successful `just verify` apply to that candidate, not main. +- `docs/capability-baseline/results.json` contains historical revision-bound evidence, including records for `767428436d3a54e60809a727044dfcec48e1f1dd`. Validating that snapshot does not execute today's product or establish today's manual-regression verdict. +- Test source, an executed test report, measured coverage, and release qualification are four different claims. The QA companion records the inventory and required evidence; no current line/branch coverage report was found. +- Prior system and Epic 1 checkpoints are historical records. Epic plans, sprint statuses and the handoff document are unchanged by this edit; the two refreshed system documents take precedence for current inventory and CP-to-FR mapping. + +## Quick Guide + +### 🚨 BLOCKERS — architecture must provide + +1. **B-001 Deterministic control plane:** aggregate builders, per-test namespaces, controllable clock/IDs/scheduler and reliable cleanup. Owner: Core/Task Architecture; foundation through Epic 4. +2. **B-002 Named fault-injection seams:** upstream/DNS/redirect, PostgreSQL/Valkey, worker crash, telemetry endpoint, disk/fsync and network failure controls. Owner: Platform/SRE; before affected epic qualification. +3. **B-003 Queryable observability sinks:** local history, captured OTLP/Sentry envelopes, Prometheus exposition and Grafana provisioning queryable by request/trace ID. Owner: Observability; before Epic 5 qualification. +4. **B-004 Executable evidence contract:** stable schemas, content-addressed collectors and RC/config/topology provenance from the first enabling epic. Owner: Release Architecture; establish in Epic 1. +5. **B-005 Independently measurable load runner:** isolated resource accounting, calibrated stub/external reference, heartbeat and kill path. Owner: Performance/Platform; before Epic 6. + +The B-001..B-005 list is a required-capability contract, not a claim that all foundations are absent: + +| Seam | Existing foundation | Remaining system-level gap | +|---|---|---| +| B-001 | PostgreSQL Testcontainers, per-test schemas, runtime doubles, typed builders | Deterministic durable Task time/claim/crash control; UI isolation before increasing workers | +| B-002 | DNS/redirect/proxy negatives, artifact crash/disk-full tests, DB failure/rollback tests | Worker, telemetry-spool and full-stack recovery fault orchestration | +| B-003 | Captured OTLP, redaction, local request/trace identity and Prometheus tests | Actual GlitchTip receiver/delivery evidence, browser-to-receiver correlation, dashboards/alerts | +| B-004 | Versioned capability inventory, bounded collectors and accepted-run validation | Complete same-RC signed release evidence across every required surface, not only OpenAPI UI | +| B-005 | Local overhead/budget probes and an ignored million-row history query test | Calibrated full workload, built-in Load Runs, separate generator/SUT accounting and stop control | + +### ⚠️ HIGH PRIORITY — validate during implementation + +1. Freeze Task lease/poll/batch/fairness parameters by performance evidence without weakening NFRs. +2. Freeze MCP versions and digest-pinned observability images at feature freeze, then bind them into the RC manifest. +3. Prove PostgreSQL/artifact/config/key consistency before readiness and after restore; a green health endpoint alone is insufficient. +4. Start nightly contention, telemetry-replay and soak trends before the final epics so long-duration defects are found early. + +### 📋 INFO ONLY — agreed strategy + +- Lowest effective test level is authoritative; E2E is reserved for critical cross-boundary outcomes. +- PostgreSQL 16 Testcontainers, Rust property/state-machine tests, MCP protocol harnesses and Playwright browser journeys build on existing repository patterns. +- Target execution tiers are PR, nightly, weekly and immutable-RC qualification. Current Gitea files implement PR/push and release gates; scheduled qualification tiers are not yet established. +- Release requires 100% P0, complete mandatory evidence, no Critical/High findings and all quantitative NFRs met. + +## Risk Assessment + +| ID | Category | Risk | P | I | Score | Mitigation | Owner | Timeline | +|---|---|---|---:|---:|---:|---|---|---| +| R-001 | TECH | Untested brownfield regressions | 3 | 3 | **9** | Capability inventory, characterization and guided baseline | QA Lead + Core | Epic 1 | +| R-002 | DATA | OpenAPI semantic loss/mapping errors | 3 | 3 | **9** | ≥50-spec oracle corpus, deterministic IR/plan, atomic apply | Import Lead | Epic 2 | +| R-003 | TECH | Duplicate effects/stale Task writes after contention or crash | 3 | 3 | **9** | State model, PG contention/crash tests, fencing and reconciliation | Task Lead | Epic 4 | +| R-004 | SEC | SSRF/bypass or secret leakage crosses closed contour | 3 | 3 | **9** | Malicious network lab, canaries, fail-closed config | Security Owner | Every epic + RC | +| R-005 | OPS | Trace spool/replay failure creates false correlation claims | 2 | 3 | **6** | Capacity/outage/corruption tests and loss accounting | Observability Lead | Epic 5 | +| R-006 | PERF | DB/telemetry/runner contention breaches SLO | 3 | 3 | **9** | Calibrated workload, query plans, resource differential | Performance Owner | Epics 5–6 + RC | +| R-007 | SEC | Admin bootstrap/session/recovery authorization failure | 2 | 3 | **6** | Auth state model and full web-security matrix | Security + Admin API | Epic 7 | +| R-008 | OPS | Upgrade/restore produces schema/artifact/key mismatch | 2 | 3 | **6** | N/N-1 matrix and three product-probed PITR restores | Release/SRE | Epic 7 | +| R-009 | BUS | MCP clients see inconsistent catalog/semantics | 2 | 3 | **6** | Immutable snapshots and ≥3-client version matrix | MCP Lead | Epic 3 | +| R-010 | OPS | Built-in load runner escapes scope or cannot stop | 2 | 3 | **6** | Signed bounds, reserved capacity, watchdog/kill tests | Load + Security | Epic 6 | +| R-011 | DATA | Metrics rollups double-count or explode cardinality | 2 | 3 | **6** | Typed registry lint and idempotent differential replay | Metrics Lead | Epic 5 | +| R-012 | TECH | Flaky E2E hides defects and slows feedback | 2 | 2 | 4 | Isolated factories, deterministic waits and burn-in | QA Automation | Continuous | +| R-013 | OPS | Evidence mixes builds or is stale/incomplete | 2 | 3 | **6** | Fail-closed signed manifest binding all digests | Release Owner | Epic 1→8 | +| R-014 | SEC | Offline bundle is untrusted/vulnerable or leaks egress | 2 | 3 | **6** | SBOM/signature/air-gap/default-deny tests | Supply-chain Owner | Epics 7–8 | +| R-015 | OPS | 30-day run reveals leaks/corruption too late | 2 | 3 | **6** | Early nightly trends, 72 h pre-soak, final burn-in | QA/SRE | Epic 4→8 | + +Category meanings: TECH architecture/integration; SEC security/privacy; PERF performance/scalability; DATA integrity; BUS user/business behavior; OPS deployment/operations. + +## NFR Testability Requirements + +| Category | Bound requirement | Design support | Required seam / decision | Planned evidence | +|---|---|---|---|---| +| Security/privacy | Default deny; encrypted secrets; per-connection SSRF; no Critical/High; no opt-out egress | Strong invariants, partial implementation | Malicious network lab, secret canaries, security configuration fixture | Negative suites, SARIF/SBOM, egress and canary reports | +| Performance/scale | 100/250 RPS; 99.95% success; 128/10k; 50/150 ms overhead | Quantified and topology-bound | Calibrated stub/external generator, production dataset, independent runner accounting | Raw samples, resource series, query plans, threshold JSON | +| Reliability/recovery | 30 s drain, 60 s lease recovery, RPO 5 m/RTO 30 m, 72 h/30 d | Durable architecture defined | Crash/fault control, virtual time, consistency manifest | Crash schedule, restore manifests/probes, soak series | +| Observability | 100% IDs/traces; 99.99%/60 s delivery; 25 h completeness; 30 h spool; bounded overhead | Typed ownership and spool designed | Queryable capture sinks, disk/outage controls, loss oracle | Correlation graph, captured envelopes, spool ledger, metric/dashboard tests | +| Maintainability/compatibility | MSRV/wire discipline; MCP stable/N-1/N-2; RU+EN | Conventions defined | Feature-freeze matrix and executable architecture rules | Coverage/lint, protocol/corpus/browser matrices | +| Release provenance | One immutable RC, signed complete evidence, no mandatory waivers | Fail-closed manifest designed | Stable schemas/collectors/trust store from Epic 1 | Validated signed manifest and content-addressed raw tree | + +Product thresholds come from PRD §5 and §10; this design does not invent replacements. Exact client/revision/image matrices, measurement tooling, reference-host allocation and release trust material still require recorded freeze inputs. A missing measurement environment or report is an evidence gap even when the numerical threshold is known. + +## Testability Concerns and Architectural Gaps + +### 🚨 Actionable concerns + +| Concern | Impact | Architecture must provide | Owner | Timeline | +|---|---|---|---|---| +| Deterministic state/time | Flaky or impractically slow Task/retention tests | Builders, scoped cleanup, clock/ID/scheduler ports | Core/Task | Epic 1–4 | +| Incomplete fault controls | Recovery/security behavior cannot be reproduced | Named injection points with observable activation | Platform/SRE | Before each NFR epic gate | +| Non-queryable telemetry | Trace assertions depend on external UI/manual inspection | Local capture/query adapters and stable schemas | Observability | Epic 5 | +| Generator/SUT ambiguity | Invalid performance verdicts | Separate budgets/metrics plus external calibration | Performance | Epic 6 | +| Late evidence plumbing | Cross-RC or irreproducible release proof | Manifest schemas and collectors from foundation | Release | Epic 1 | +| UI shared state | Parallel browser collisions and stale assertions | Per-worker namespaces, seed/cleanup APIs, stable selectors | Admin/QA | Before full regression | + +### Required architectural improvements + +1. Reuse existing builders, runtime doubles and fault seams. Introduce time/claim/failure controls only at new stateful boundaries that require them; do not refactor all modules solely to match a testing pattern. +2. Treat test/evidence schemas as supported internal contracts, versioned alongside wire and migration changes. +3. Expose only safe, bounded test control in test profiles; production profiles must reject it. +4. Make observability truth distinguish `captured locally`, `delivered`, `lost` and `unknown`; UI must never infer GlitchTip presence. +5. Add resource ownership/accounting to load runner and telemetry spools so product and harness costs are separable. + +### Testability assessment summary + +- ✅ Hexagonal, framework-free core supports unit/property testing and adapter replacement. +- ✅ PostgreSQL authority plus optional Valkey enables correctness-first and differential cache tests. +- ✅ Existing Testcontainers support, Rust suites, in-memory runtime stores and Playwright coverage are a solid base. +- ✅ Typed errors/events/metrics, immutable revisions and version-isolated MCP adapters provide stable oracles. +- Quantitative NFRs and bounded capability collectors provide an objective starting point; complete signed release qualification is still a required future capability. + +Accepted trade-offs: single-instance drain/restart is the only claimed upgrade model; HA/rolling upgrades, S3 artifacts, SSO/RBAC, non-REST adapters and arbitrary distributed load targets remain out of this release and must not appear in evidence or documentation claims. + +## Risk Mitigation Plans + +All high risks follow the same gate: the owner implements the production seam/control, QA captures machine-readable evidence, and the risk closes only when the linked scenarios pass on the bound topology. Owners below are accountable roles, not claims that separate staffed teams exist. The product owner must assign a person before scheduling qualification. Existing tests reduce implementation work but do not by themselves close a risk. + +| Risk | Numbered strategy | Owner / timeline | Status | Verification | +|---|---|---|---|---| +| R-001 | 1. Inventory; 2. characterize; 3. run guided baseline before semantic changes | QA Lead + Core / Epic 1 | Open; see seam inventory | CP-01..04 and zero blocked baseline items | +| R-002 | 1. Build oracle corpus; 2. prove deterministic IR/plan; 3. prove rollback/zero loss | Import Lead / Epic 2 | Open; see seam inventory | CP-05..07 thresholds | +| R-003 | 1. Model states; 2. inject crash/contention; 3. prove fencing/reconciliation | Task Lead / Epic 4 | Open; see seam inventory | CP-12..15, no illegal/stale transition | +| R-004 | 1. Centralize policy; 2. attack every ingress; 3. scan every output with canaries | Security Owner / every epic + RC | Open; see seam inventory | CP-03/04/25/27 and malicious-network report | +| R-005 | 1. Implement delivery/loss ledger; 2. force outage/disk faults; 3. verify UI truth | Observability Lead / Epic 5 | Open; see seam inventory | CP-16..18 and spool accounting | +| R-006 | 1. Calibrate; 2. baseline/query-plan; 3. run contention and immutable-RC profiles | Performance Owner / Epics 5–6 + RC | Open; see seam inventory | CP-14/18/23/29 raw thresholds | +| R-007 | 1. Model auth; 2. exercise web config matrix; 3. prove recovery revocation | Security + Admin API / Epic 7 | Open; see seam inventory | CP-25 negative matrix | +| R-008 | 1. Bind consistency manifest; 2. exercise N/N-1/rollback; 3. restore three times | Release/SRE / Epic 7 | Open; see seam inventory | CP-26 and measured product probes | +| R-009 | 1. Isolate adapters; 2. freeze snapshots; 3. run revisions × clients | MCP Lead / Epic 3 | Open; see seam inventory | CP-08..11 matrix | +| R-010 | 1. Sign/bound plan; 2. reserve control capacity; 3. force watchdog/kill recovery | Load + Security / Epic 6 | Open; see seam inventory | CP-22..24 | +| R-011 | 1. Type registry; 2. enforce label budget; 3. replay/diff rollups and alerts | Metrics Lead / Epic 5 | Open; see seam inventory | CP-19..21 | +| R-013 | 1. Version schemas; 2. bind all digests/freshness; 3. verify trust/revocation failures | Release Owner / Epic 1→8 | Open; see seam inventory | CP-31 negative matrix | +| R-014 | 1. Pin/sign/SBOM; 2. scan; 3. install/upgrade with captured default-deny egress | Supply-chain Owner / Epics 7–8 | Open; see seam inventory | CP-27 | +| R-015 | 1. Start nightly trends; 2. pass 72 h soak; 3. complete 30-day immutable-RC burn-in | QA/SRE / Epic 4→8 | Open; see seam inventory | CP-29 with no drift/SLO breach | + +R-012 is medium (score 4): QA owns deterministic Playwright practices and continuous burn-in; it is monitored rather than treated as a production-architecture blocker. Final NFR status belongs to the later NFR assessment. + +## Assumptions and Dependencies + +Assumptions: + +1. Reference Deployment and all numeric thresholds in PRD/epics are normative. +2. PostgreSQL remains the correctness source; Valkey outage may reduce throughput but cannot change results. +3. Feature-freeze inputs may select versions/digests but cannot relax requirements. +4. Release identity changes on any code/config/topology digest change. + +Dependencies: + +1. Foundation test controls and evidence schemas — Epic 1. +2. Stable OpenAPI corpus oracle — Epic 2. +3. Representative MCP clients and protocol harness — Epic 3. +4. Fault/telemetry/load/recovery environments — before Epics 4–7 qualification. +5. Protected release signing/trust material — before Epic 8 RC. + +Risk to plan: specialized performance/security/SRE capacity or reference hardware may be unavailable. Contingency is to prepare hermetic fixtures and rehearsal environments early; qualification remains blocked rather than using incomparable evidence. + +## System-Level Handoff Boundary + +First review the QA inventory, evidence gaps and shared execution rules. Resolve common fixture, report-retention, compatibility and measurement prerequisites at system level; only then derive epic-level deltas from the same CP/R identifiers. Do not restart completed stories or create new mandatory features from this test design. Security, data-loss and unsupported-contract findings discovered during later testing must be triaged explicitly. + +This edit ran no product tests, load jobs or deployment operations. The only test-discovery command was Playwright `--list`; source inspection and document consistency checks are not a final NFR assessment. diff --git a/_bmad-output/test-artifacts/test-design-epic-1.md b/_bmad-output/test-artifacts/test-design-epic-1.md new file mode 100644 index 0000000..5326507 --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-epic-1.md @@ -0,0 +1,288 @@ +--- +workflowStatus: 'completed' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +lastSaved: '2026-09-13' +lastEdited: '2026-09-13' +runScope: 'epic-level' +runKey: 'epic-1' +auditedRevision: '083974c27f3a21a15807dd248bb6bc4fe04a5cd8' +workflowType: 'testarch-test-design' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad-output/project-context.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' +--- + +# Test Design: Epic 1 — Надёжный базовый REST → MCP продукт + +**Date:** 2026-09-13 +**Author:** Bsodfather / BMad TEA +**Status:** Updated regression planning baseline; implementation status unchanged, qualification not evaluated. + +## Executive Summary + +This epic-level plan covers Stories 1.1–1.16 and proves the safe core journey: create/test/version/publish a REST Operation, publish an Agent catalog, manage credentials/approvals, execute through MCP and diagnose the result. It also establishes configuration, migrations, identity, metrics and evidence contracts required by later epics. + +There are 15 risks: 13 high (six score 9), two medium and none low. The dominant categories are security, data integrity, execution consistency and operational correctness. + +Coverage retains the 41 historical scenario-family IDs for continuity. The former 650–1,050-case / 655–1,150-hour forecast predates completed Epic 1 work and is not a remaining-work estimate. Reuse existing tests before identifying gaps; do not reopen completed stories or create hundreds of tests just to satisfy a forecast. + +## Not in Scope + +| Item | Reason | Mitigation | +|---|---|---| +| Full modern Resources/Prompts/Tasks | Epics 3–4 | Epic 1 establishes shared config/identity/metrics/runtime contracts | +| GlitchTip spool, Grafana/SLO implementation | Epic 5 | Epic 1 proves correlation/redaction/typed metric foundations | +| Built-in load runner | Epic 6 | Use test-only calibrated performance harness for Epic 1 thresholds | +| Complete deployment/restore/air-gap qualification | Epics 7–8 | Migration/master-key contracts remain compatible and evidence-ready | +| 72-hour soak and 30-day burn-in | Epic 8 | Bounded contention/resource trend checks are proposed; nightly scheduling is not currently configured | + +## Existing Evidence Baseline + +- Real PostgreSQL 16 Testcontainers and unique-schema fixtures exist. +- Admin API covers basic Operation/Agent/key/secret/history/usage flows. +- MCP suites cover tool calls, catalog scope/refresh, approvals, transport and correlation. +- Runtime covers confirmation, idempotency, fail-closed stores and uncertain outcomes. +- Metrics/observability cover closed labels, redaction, propagation, Prometheus and OTLP configuration. +- Playwright covers key current screens, but is Chromium-only, one-worker and not yet production-qualification complete. + +Existing tests are reusable evidence candidates, not automatic acceptance: each must be linked to the Inventory and rerun against the Epic candidate. + +### 2026-09-13 Source and Gap Audit + +Main is `083974c27f3a21a15807dd248bb6bc4fe04a5cd8`. Epic 1 is already implemented in sprint tracking; this is a regression/evidence update, not instructions to restart 1.1. Source presence is not current execution evidence. Historical baseline `2026.08.24.1` binds revision `767428`, not this HEAD. No product tests were rerun during this planning update. + +| Story | Existing source to reuse | Remaining qualification distinction | +|---|---|---| +| 1.1 | `tests/unit/test_validate_capability_inventory.py`, `docs/capability-inventory.json` | Inventory schema correctness is not functional pass for every listed flow | +| 1.2 | `docs/capability-baseline/results.json`, `scripts/collect-capability-baseline.py` | Old results and manual not-run/fail entries require fresh disposition, not inferred pass | +| 1.3 | `crates/crank-config/tests/{contract,generation,redaction}.rs` | Config exists; later-process fields belong to owning stories/7.1 | +| 1.4 | `crates/crank-registry/tests/integration/migrations.rs`, `apps/admin-api/tests/migration_command.rs` | Real migration regressions exist; full production N/N-1 qualification is 7.2 | +| 1.5 | `crates/crank-observability/tests/{request_correlation,propagation}.rs` | Support IDs/capture do not prove GlitchTip delivery | +| 1.6 | `crates/crank-metrics/tests/`, `crates/crank-runtime/tests/product_metrics.rs` | Typed schema/budget tests are not complete future subsystem coverage | +| 1.7 | `apps/admin-api/tests/integration/operation_lifecycle.rs`, `apps/ui/tests/e2e/operation-lifecycle.spec.js` | Reuse immutable/conflict and RU/EN cases on changed lifecycle paths | +| 1.8 | `crates/crank-runtime/tests/stages.rs`, `apps/mcp-server/tests/integration/execution_stages.rs` | Preserve synchronous parity; candidate 2.9 evidence remains separate | +| 1.9 | `crates/crank-adapter-rest/tests/integration/outbound_security.rs` | Extend only new connection surfaces; production security qualification remains separate | +| 1.10 | `apps/admin-api/tests/integration/credential_lifecycle.rs` | Reuse credential scope/rotation/canary tests | +| 1.11 | `apps/admin-api/tests/migration_command.rs`, `apps/admin-api/tests/config_startup.rs` | Rotation/startup tests are not three qualified restore runs | +| 1.12 | `apps/admin-api/tests/integration/auth_rate_limit.rs`, `apps/ui/tests/e2e/login.spec.js` | Full deployment exposure matrix belongs to 7.4 | +| 1.13 | `apps/mcp-server/tests/integration/catalog_access.rs` | Source access/refresh regressions do not measure reference-scale discovery | +| 1.14 | `crates/crank-runtime/tests/integration/confirmation.rs` | Preserve counted side effects, replay/race and honest uncertainty | +| 1.15 | `apps/admin-api/tests/integration/logs_usage.rs`, `crates/crank-registry/tests/integration/observability.rs` | `production_size_invocation_history_queries_stay_bounded` is ignored; 1M-row qualification not claimed | +| 1.16 | `apps/ui/tests/e2e/onboarding.spec.js` | Real public MCP path exists; fresh-user five-participant ≤15-min protocol remains separate manual evidence | + +Current browser discovery: 56 tests /13 files, Chromium only, one worker. This is not full Firefox/WebKit × RU/EN coverage. No measured code-coverage report was found. Read the updated system QA inventory before scheduling gaps. + +## Risk Assessment + +### High-priority risks + +| Risk | Category | Failure | P | I | Score | Mitigation | Owner | Target | +|---|---|---|---:|---:|---:|---|---|---| +| E1-R-001 | TECH | False Capability Inventory/baseline hides gaps/regressions | 3 | 3 | **9** | Strict validator, checksummed evidence and blocked severe flows | QA + Release | 1.1–1.2 | +| E1-R-002 | OPS | Cross-process config drift/unsafe defaults | 3 | 3 | **9** | Single typed schema, golden config and boundary scans | Config/Core | 1.3 | +| E1-R-003 | DATA | Migration corruption/race/incompatibility | 2 | 3 | **6** | Real-PG fresh/current/concurrent/failure matrix | Registry | 1.4 | +| E1-R-004 | OPS | Missing/conflated/attacker-controlled IDs | 2 | 3 | **6** | Boundary contracts and golden correlation chain | Observability | 1.5 | +| E1-R-005 | PERF | Metric cardinality/overhead exhaustion | 2 | 3 | **6** | Closed API, million-value stress and budget | Metrics | 1.6 | +| E1-R-006 | DATA | Draft/import/archive mutates published behavior | 2 | 3 | **6** | State model, conflicts, roundtrip and snapshot regression | Operation | 1.7 | +| E1-R-007 | TECH | Admin and MCP execute/classify differently | 3 | 3 | **9** | Table-driven parity and architecture guardrails | Runtime | 1.8 | +| E1-R-008 | SEC | SSRF/proxy/redirect/header/retry bypass | 3 | 3 | **9** | Malicious-network matrix on Admin and MCP | Security + REST | 1.9 | +| E1-R-009 | SEC | Credential leak/scope bypass/master-key data loss | 3 | 3 | **9** | Canaries, purpose/scope matrix and crash-safe rotation | Security + Registry | 1.10–1.11 | +| E1-R-010 | SEC | Bootstrap/session/CSRF/proxy/recovery takeover | 2 | 3 | **6** | Auth model, concurrency and web-security matrix | Auth + Security | 1.12 | +| E1-R-011 | DATA | Stale/foreign/Draft catalog leakage | 2 | 3 | **6** | Atomic snapshot, exact pinning and cache differential | Agent + MCP | 1.13 | +| E1-R-012 | BUS | Approval race/replay causes unauthorized duplicate side effect | 3 | 3 | **9** | PG race model, single-use admission and uncertainty proof | Approval + Runtime | 1.14 | +| E1-R-013 | SEC | History/CSV leaks data or large queries fail | 2 | 3 | **6** | Redaction/scope/CSV/UTC/retention and 1M dataset | History + Admin | 1.15 | + +### Medium risks + +| Risk | Category | Failure | P | I | Score | Mitigation | Owner | +|---|---|---|---:|---:|---:|---|---| +| E1-R-014 | BUS | Onboarding duplicates state or never proves real MCP value | 2 | 2 | 4 | Server-authoritative real-endpoint/resume/usability E2E | Product + UI | +| E1-R-015 | TECH | Serial/shared-state browser suite masks races | 2 | 2 | 4 | Per-worker data/ports, trace-on-failure and burn-in | QA Automation | + +No low-priority risks were identified. Score 9 blocks the epic gate; score 6 requires verified mitigation. + +## NFR Planning + +| Category | Epic threshold/invariant | Risks | Validation | Evidence | +|---|---|---|---|---| +| Security/privacy | Default deny; no metadata/secret leakage; encryption; SSRF on actual connections; zero Critical/High | E1-R-008/009/010/013 | Malicious network, key/auth scope matrix, canaries, web-security, SAST/SCA | JUnit/JSON, network capture, canary and scanner reports | +| Performance/scale | Discovery ≤150 ms p95 at 200 Agents/2,000 Operations; Logs/Usage ≤2 s p95 at 1M records; bounded metric cardinality | E1-R-005/011/013 | Checksummed datasets, PG plans, raw browser/API timings, million-value metric stress | Plans, timing samples, resource/series report | +| Reliability/data | Durable immutable revisions/config/approvals; transactional checksummed migrations; safety stores fail closed | E1-R-003/006/011/012 | PG contention/restart/failure, state/property tests and adapter call counters | Seeds/schedules, checksums and invariant results | +| Observability | 100% Epic ingress/execution/history records have separate Request/Trace IDs; labels bounded; no secret payloads | E1-R-004/005/013 | Boundary/cross-process correlation, persistence queries, schema/redaction | Correlation map, trace capture, metric/redaction report | +| Compatibility/maintainability | Existing wire/core behavior retained; MSRV/boundaries unchanged; RU+EN; regression per defect | E1-R-001/002/007/015 | Inventory, `just verify`, snapshots, localization/static/flake checks | Inventory/evidence links and CI reports | +| UX/business | Fresh manual path reaches real MCP call ≤15 min; async states/recovery/stale guards/accessibility | E1-R-014 | Real-stack Playwright and frozen guided-usability protocol | Traces, accessibility and timing results | + +Controlled inputs and remaining execution prerequisites: + +- Reuse the shipped typed metric contract/series budgets from 1.6; freeze additional subsystem metrics in their owning stories, not by reopening 1.6. +- Session/bootstrap/backoff/retention defaults and bounds are authoritative in `crank-config`; regression tests must use that contract. +- The manual regression checklist specifies five fresh participants and median time-to-first-value ≤15 minutes; execution evidence is still required. + +This plan defines evidence; final NFR PASS/CONCERNS/FAIL belongs to the later NFR assessment. + +## Entry Criteria + +- Story acceptance criteria and Requirements tags are unchanged or their change is reviewed. +- Applicable typed config/migration/test-control seam exists and is production-safe. +- PostgreSQL/Valkey/upstream/telemetry/browser fixtures use deterministic scoped data and cleanup. +- Expected wire/state/security oracle is frozen before implementation. +- Existing affected suites pass or their baseline failure is recorded in Capability Inventory. + +## Exit Criteria + +- Every acceptance criterion in Stories 1.1–1.16 maps to test and immutable evidence. +- P0 and Story-acceptance P1 pass 100%; no blocked/skipped mandatory/manual item. +- Six score-9 risks are closed; score-6 risks have verified mitigations. +- No Critical/High defect or security finding; secret and cross-scope scans are clean. +- Numeric discovery/UI/cardinality/usability targets pass on checksummed inputs. +- Existing REST→MCP journey remains green; no unrelated dependency/toolchain/wire change is mixed in. + +## Test Coverage Plan + +P0/P1/P2/P3 describe risk priority, not execution timing. Detailed IDs E1-01..E1-41 are stable scenario-family identifiers. + +### P0 — Critical + +| IDs | Story | Primary coverage | Risk | Historical sizing, not remaining cases | +|---|---|---|---|---:| +| E1-01, E1-02, E1-03, E1-04 | 1.1–1.2 | Inventory/scope validator and real current REST→MCP baseline | E1-R-001 | 40–69 | +| E1-06, E1-07 | 1.3 | Typed config values, conflicts, redaction, fingerprints and boundary scan | E1-R-002 | 53–85 | +| E1-08, E1-09 | 1.4 | PG migration sequence/checksum/concurrency/failure/backfill | E1-R-003 | 30–48 | +| E1-10, E1-11 | 1.5 | Hostile IDs and full correlation/persistence chain | E1-R-004 | 30–48 | +| E1-12, E1-13 | 1.6 | Metric schema/guardrail/cardinality/exemplar/overhead | E1-R-005 | 28–44 + profiles | +| E1-14, E1-15 | 1.7 | Operation state/revision/YAML/API/history invariants | E1-R-006 | 55–85 | +| E1-17, E1-18, E1-19 | 1.8 | Admin/MCP target and failure parity plus boundaries | E1-R-007 | 51–82 | +| E1-20, E1-21 | 1.9 | Actual-connect SSRF, redirects, proxy, headers, bounds/retries | E1-R-008 | 60–95 | +| E1-22, E1-23, E1-24, E1-25 | 1.10–1.11 | Credential lifecycle/UI canary and master-key rotation/crash | E1-R-009 | 85–141 | +| E1-26, E1-27 | 1.12 | Bootstrap/auth/session concurrency and security config | E1-R-010 | 55–90 | +| E1-29, E1-30 | 1.13 | Atomic catalog/pinning/scope/cache/performance | E1-R-011 | 50–75 + profiles | +| E1-32, E1-33 | 1.14 | Approval model/races/scope/single-use/uncertainty | E1-R-012 | 55–85 | +| E1-35, E1-36, E1-37 | 1.15 | History redaction/scope/CSV/UTC/retention/1M performance | E1-R-013 | 53–87 + profiles | + +### P1 — High + +| IDs | Story | Primary coverage | Risk | Historical sizing, not remaining cases | +|---|---|---|---|---:| +| E1-05 | 1.2 | Bounded exploratory RU/EN baseline | E1-R-001 | 10–16 charters | +| E1-16 | 1.7 | Operation lifecycle stale/immutable/YAML UI journey | E1-R-006 | 8–14 | +| E1-23 | 1.10 | One-time secret DOM/storage/telemetry behavior | E1-R-009 | 10–16 | +| E1-28 | 1.12 | Login/throttle/expiry/recovery browser states | E1-R-010 | 10–16 | +| E1-31 | 1.13 | Agent Draft/Published/revision/conflict UI | E1-R-011 | 8–14 | +| E1-34 | 1.14 | Approval safe summary/expiry/conflict/stale UI | E1-R-012 | 8–12 | +| E1-38, E1-39, E1-40 | 1.16 | Authoritative onboarding, real call, failures, accessibility and usability | E1-R-014 | 41–69 + usability | +| E1-41 | All | Isolation, deterministic burn-in and traceability quality | E1-R-015 | 8–12 harness checks | + +### P2/P3 + +P2/P3 are optional focused exploratory/benchmark variants only. No numeric quota of new tests is required; neither replaces mandatory evidence. + +## Execution Strategy + +Run all functional coverage in PR when it fits the ≤15-minute target; defer only expensive infrastructure or duration. + +Nightly/weekly below describe the intended execution tiers, not existing scheduled jobs. Current CI runs PR/push and release gates. `just verify` does not include UI E2E, image or deployment qualification. Mandatory owning-story acceptance still requires its evidence even when a profile is expensive. + +- **PR:** changed unit/property/static tests; targeted PostgreSQL/Admin/MCP integration; Inventory/config/boundary contracts; changed Playwright plus shared auth/API smoke. +- **Nightly:** full Epic Rust/PG/Valkey/Admin/MCP and Chromium UI; security negatives; correlation; cardinality; migration/rotation/approval contention and flake burn-in. +- **Weekly:** malicious network, 200/2k/1M performance profiles, web-security matrix, master-key crash/recovery, guided onboarding/accessibility and required exploratory refresh. +- **Epic qualification:** complete traceability and evidence for one Epic candidate digest. Product-wide 72-hour/30-day qualification remains Epic 8. + +## Resource Estimates + +The old initial-implementation estimate is superseded. Provisional incremental QA audit/regression effort, assuming existing seams are reusable, excluding product implementation and qualification elapsed time: + +| Priority | Effort | +|---|---:| +| P0 | ~16–32 hours | +| P1 | ~8–16 hours | +| P2 | ~0–8 hours | +| P3 | ~0–4 hours | +| **Total** | **~24–60 hours** | + +Approximately 1–2 contributor-weeks, low confidence until AC-to-existing-test reconciliation. These are planning bounds, not authorizations for extra work or a token target. Missing reference hardware/manual reviewers add lead time; do not fold 1M-row or release qualification into every story session. + +Prerequisites include scoped data factories, malicious upstream/DNS proxy, controllable clock/IDs, ciphertext/key fixtures, production-size datasets, captured telemetry and safe failure injection. + +## Quality Gate Criteria + +- P0 100%; P1 ≥95% during development and 100% for acceptance/epic qualification. +- Security scenarios and score-9 mitigations 100%; no Critical/High findings. +- Requirement-to-test-to-evidence mapping 100% for Stories 1.1–1.16. +- Workspace coverage ≥80%; new critical config/migration/state/security code targets ≥90% where measured. These remain goals: no current coverage report proves them, and test counts cannot substitute for one. +- Discovery/UI/cardinality/usability targets pass; metric budget must be frozen first. +- Full NFR decision is deferred until implementation evidence is assessed. + +## Mitigation Plans + +The statuses below mean pending qualification evidence, not absent implementation. Use the source audit above to distinguish implemented controls from unexecuted qualification; no risk is closed solely by source presence. Risk scores are inherited conservative planning scores, not observed current failures. + +| Risk | Strategy | Verification | Status | +|---|---|---|---| +| E1-R-001 | Schema/validator → full mapping → immutable baseline | E1-01..05 and zero hidden severe flow | Planned | +| E1-R-002 | Central schema → process parity → env-read guardrail | E1-06, E1-07 | Planned | +| E1-R-003 | Immutable sequence → contention/faults → N/N-1 fixture | E1-08, E1-09 | Planned | +| E1-R-004 | Typed IDs → hostile boundary inputs → golden chain | E1-10, E1-11 | Planned | +| E1-R-005 | Closed registry → series budget → stress/overhead | E1-12, E1-13 | Planned | +| E1-R-006 | State model → PG revision conflicts → API/UI roundtrip | E1-14..16 | Planned | +| E1-R-007 | Unified request → stage parity → dependency guardrail | E1-17, E1-18, E1-19 | Planned | +| E1-R-008 | Actual-connect policy → attack matrix → no-secret scan | E1-20, E1-21 | Planned | +| E1-R-009 | Credential scope/canary → durable rotation → browser proof | E1-22, E1-23, E1-24, E1-25 | Planned | +| E1-R-010 | Auth model → web config matrix → browser/recovery proof | E1-26..28 | Planned | +| E1-R-011 | Atomic snapshot → cache/scope differential → scale/UI | E1-29..31 | Planned | +| E1-R-012 | Fingerprint/model → PG races → side-effect counters/UI | E1-32..34 | Planned | +| E1-R-013 | Redaction/scope → time/CSV/retention → 1M UI | E1-35, E1-36, E1-37 | Planned | + +## Assumptions and Dependencies + +Assumptions: + +1. PostgreSQL remains correctness authority; Valkey is optional acceleration. +2. Reference datasets and thresholds in PRD/epics are normative. +3. Existing tests may be refactored for traceability/isolation without changing product semantics. +4. Security-sensitive test controls are unavailable in production configuration. + +Dependencies: + +1. Preserve completed 1.1–1.16 state; rerun only relevant regressions when a later story touches shared contracts. +2. Reuse existing metric/security/key fixtures and approved usability protocol; remaining full-system evidence follows Epics 5–8. +3. Docker is available for PostgreSQL/Valkey/full-stack evidence. + +Risk to plan: single-worker/default-port Playwright infrastructure may delay PR feedback. Contingency is to keep targeted browser smoke serial while building per-worker data/ports; do not raise workers until repeated burn-in proves isolation. + +## Interworking and Regression + +| Component | Regression scope | +|---|---| +| Scope/docs/project context | Community boundary and Inventory validator tests | +| Admin API/UI | Existing Operations/Agents/keys/secrets/login/Logs/Usage specs plus owning Story gaps | +| MCP server/catalog | Transport, catalog access/search, approval and tool execution suites | +| Runtime/REST adapter | Mapping/stages/idempotency/confirmation/Valkey and outbound client suites | +| Registry/PostgreSQL | Operations/artifacts/workspace/approval/observability/migration suites | +| Metrics/trace/observability | Closed schema, propagation, redaction, Prometheus/OTLP/history-loss suites | + +Every defect fix starts with the lowest-level regression and adds a boundary test when the contract crossed layers. + +## Manual Follow-on + +- Do not restart Epic 1. For a separately approved new/fix story, run bounded ATDD before implementation, reusing existing tests and completed matching checklists. Never add red tests solely to make already-correct behavior fail. +- The requested automatic pre-implementation handoff is configured separately from this design; stock bmad-loop 0.11.1 TEA runs ATDD after dev and must not be mistaken for the intended order. +- Run broader automation after the corresponding production seams exist. +- Run traceability and NFR assessment only against implementation evidence. + +## References + +- `_bmad-output/planning-artifacts/epics.md` — Epic 1 Stories 1.1–1.16 +- `_bmad-output/test-artifacts/test-design-architecture.md` +- `_bmad-output/test-artifacts/test-design-qa.md` +- `_bmad-output/test-artifacts/test-design/crank-handoff.md` — historical handoff, not current execution evidence; current system QA/design and epic plans take precedence +- Risk governance, probability-impact, test levels/priorities and NFR criteria knowledge fragments + +**Generated by:** BMad TEA Agent +**Workflow:** `bmad-testarch-test-design` diff --git a/_bmad-output/test-artifacts/test-design-epic-2.md b/_bmad-output/test-artifacts/test-design-epic-2.md new file mode 100644 index 0000000..2be8ac9 --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-epic-2.md @@ -0,0 +1,185 @@ +--- +runScope: 'epic-level' +runKey: 'epic-2' +workflowStatus: 'completed' +workflowType: 'testarch-test-design' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +lastSaved: '2026-09-13' +auditedRevision: '083974c27f3a21a15807dd248bb6bc4fe04a5cd8' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' +--- + +# Test Design: Epic 2 — Надёжное создание Tools из реальных OpenAPI + +**Date:** 2026-09-13 +**Author:** Bsodfather / BMad TEA +**Status:** Updated planning baseline; qualification not evaluated. + +## Executive Summary + +Scope: FR-7–FR-12, 15 stories, system scenario families CP-05..07. This plan reflects the approved numbering revision; it neither changes product scope nor marks stories complete. + +4 inherent risks, 3 high (score ≥6). Coverage seeds: 22 P0 and 8 P1 independently assertable scenarios. Counts describe the two seeds per story below, not implemented tests, coverage percentages or the eventual parameterized case count. Every source AC remains mandatory. + +## Existing Coverage and Evidence + +Source inventory at main `083974c`: `crates/crank-artifacts/tests/{artifact_store,artifact_store_io,reconciliation}.rs`; `crates/crank-registry/tests/integration/{artifact_sources,artifact_reconciliation}.rs`; `apps/admin-api/tests/integration/openapi_source/`; `crates/crank-import/tests/{preview,coverage,normalization_details,reference_resolution}.rs`; `apps/admin-api/tests/integration/openapi_import/`; `apps/ui/tests/e2e/operations.spec.js`. + +2.1–2.6 source/metadata/reconciliation/preview and 2.7–2.8 have reusable source tests, not fresh acceptance evidence. 2.9 tests exist only at candidate f8ee7c9, not main 083974c; rerun after integration. Security-scheme API/UI mapping, full partial/re-import policy matrix, ≥50-spec corpus and OpenAPI onboarding still need story-level deltas. Two candidate review deferrals (reverse URL placeholder validation and object/array default projection) remain explicit triage inputs, not automatically accepted or added to every story. + +Source presence ≠ execution ≠ requirement coverage ≠ qualification. No product test, deployment or load execution was performed for this plan. Reuse source tests only after matching their oracle to the current AC and recording a run on the candidate under test. + +## Not in Scope + +| Item | Reason | Mitigation | +|---|---|---| +| Unrelated future-epic implementation and whole-product refactoring | This is Epic 2 test planning | Keep explicit prerequisites below; do not invent additional story acceptance | +| SSO/RBAC enterprise features, non-REST adapters, HA/rolling deployment | Outside approved Community scope | Preserve Community boundary checks | +| Declaring current production readiness from source inventory | No bound qualification run | Require real evidence before gate | +| Product-wide 72-hour soak / 30-day burn-in | Owned by Epic 8 | Component fault/performance obligations in this epic remain required | + +## Risk Assessment + +Score = probability × impact on a 1–3 scale. Score ≥6 needs verified mitigation; 9 is an unresolved critical release risk, not a command to implement every mitigation immediately. Categories: SEC security, DATA integrity, OPS operations, PERF performance, BUS user behavior, TECH architecture/testing. + +| Risk ID | Category | Failure | P | I | Score | System risk | Mitigation / accountable role / deadline | +|---|---|---|---:|---:|---:|---|---| +| E2-R1 | DATA | Silent HTTP/schema loss in supported imports | 3 | 3 | 9 | R-002 | Wire oracle + IR/ref/plan golden tests; Import owner, before 2.14 | +| E2-R2 | SEC | Hostile files/refs escape scope, leak secrets or exhaust resources | 3 | 3 | 9 | R-004 | Bounded parser/network/storage canaries; Security + Import, each source story | +| E2-R3 | DATA | GC/re-import races lose pinned artifacts or overwrite revisions | 2 | 3 | 6 | R-008 | Real PG + filesystem fault interleavings; Registry, before 2.13 | +| E2-R4 | TECH | Flaky preview UI/evidence masks failed import | 2 | 2 | 4 | R-012 | Stale-response tests + strict evidence; UI/QA, 2.6/2.15 | + +Medium risks: E2-R4 (4), tracked UI flakiness. No additional low risk is invented just to fill a template. Residual risk is unmeasured until evidence exists. + +## NFR Planning + +Zero silent semantic loss; ≥50 versioned specs and ≥95% actionable Draft operations (2.14). Source size/depth/time/scan budgets come from the typed contract; test min/max/over-limit, do not invent limits. No secrets outside allowed encrypted authority. Test artifact retention under reference/cleanup contention. + +| Category | Scenario linkage | Planned validation / evidence | +|---|---|---| +| Security/privacy | SEC risks and B scenarios below | Scope/abuse/canary tests, bounded sanitized logs and network/scan report | +| Reliability/data integrity | DATA/OPS risks and fault scenarios | Real authority/state assertions, fault schedule and reconciled counters/digests | +| Performance/scalability | Numeric epic obligations above | Calibrated raw latency/resource samples, achieved load and immutable config/topology fingerprint | +| Maintainability/compatibility | Every changed component | Existing `just verify`/UI gates as applicable, schema/contract diffs and traceable regression reports | + +Unknowns: exact execution hardware and fresh qualification artifacts are not available from this audit. Where the owning story requires a new tolerance, limit or version selection, freeze it in its approved contract before writing a numeric assertion; never replace the PRD threshold with a guessed easier value. Full NFR verdict belongs to `bmad-testarch-nfr` after execution. + +## Entry Criteria + +- Approved owning story/spec and prerequisites are available in the same worktree. +- ATDD loads the actual ACs from `epics.md` / selected spec and the system QA design. +- Existing tests and baseline failures are inspected before adding tests; no duplicate test suite solely for new IDs. +- Immutable hostile/valid YAML/JSON corpus with expected IR and wire outcomes; local allowlisted HTTP/DNS fixtures; isolated temp roots; real PostgreSQL schemas; reproducible crash checkpoints. File-size fault tests must retain pipe/PTY stdout rather than a regular-file redirect. +- Missing fixture, service or approval is reported as blocked/not-run, not silently skipped. + +## Test Coverage Plan + +P0/P1/P2/P3 indicate priority, **not execution timing**. Each table row has two separate scenario seeds: `--A` and `...-B`. Split a seed when independent assertions require different fixtures. Reuse an existing equivalent test rather than duplicating it; ATDD records exact test name/path and AC mapping. + +The AC-count column inventories `Given` groups, including the five shared groups inherited by both Stories 2.3 and 2.4; their physical placement under 2.4 does not mean 2.3 has no AC. Counts are not a claim that two tests exhaust those groups. The former security-mapping story is split without loss: 2.10 owns its former API groups 1–10 and 12, while 2.11 owns former group 11 plus the UI perspectives of groups 3 and 5. ATDD must map each group (story + ordinal + quoted acceptance text) to existing test, new test, or explicit not-run prerequisite before implementation. The approved spec controls finer-grained cases. + +### P0 — Critical + +Security, irreversible data integrity and false acceptance have no safe user workaround. + +| Story / scenario IDs | Requirements | AC groups | Primary level | Risk | A: expected behavior | B: rejection / fault | +|---|---|---:|---|---|---|---| +| 2.1 / 2.1-INT-A,B | FR-7, FR-9 | 6 | INT | E2-R2/E2-R3 | Immutable bytes: digest roundtrip and concurrent no-clobber dedupe | Corrupt/missing bytes, symlink/traversal and crash/disk-full must fail safely | +| 2.2 / 2.2-INT-A,B | FR-7, FR-9 | 6 | INT | E2-R2/E2-R3 | Workspace-owned metadata attach/read/detach and idempotent replay | Foreign scope indistinguishable from missing; conflicting replay and missing blob rejected | +| 2.3 / 2.3-INT-A,B | FR-7, FR-9 | 5 shared | INT | E2-R3 | Bounded scan continuation visits eligible entries exactly once | Malformed entries, quarantine/unlink race and retries preserve live bytes | +| 2.4 / 2.4-INT-A,B | FR-7, FR-9 | 5 | INT | E2-R3 | Claim/finalize recovery converges after process restart | Global reference recheck wins over cleanup; stale token and DB/fsync crash windows cannot delete referenced content | +| 2.5 / 2.5-API-A,B | FR-7, FR-9 | 6 | API | E2-R2 | Verified YAML/JSON multipart preview creates no Draft | Malformed/oversized/cancelled upload, foreign scope, corruption and parser canaries remain bounded/sanitized | +| 2.7 / 2.7-UNIT-A,B | FR-7, FR-8 | 12 | UNIT | E2-R1 | OAS3.0/3.1/Swagger2 normalize byte-for-byte to stable source-construct identities | Malformed, duplicate IDs and unsupported constructs yield bounded explicit findings, never silent loss | +| 2.8 / 2.8-INT-A,B | FR-9 | 13 | INT | E2-R1/E2-R2 | Local/external refs and supported composition preserve provenance/snapshot digests | Cycles, depth/size, SSRF/redirect/TOCTOU and foreign cached snapshots denied | +| 2.9 / 2.9-INT-A,B | FR-8 | 14 | INT | E2-R1 | All supported methods/parameter locations/body encodings replay expected wire bytes; 2xx/204 outcomes match | Unsupported XML/serialization or lost semantics block with findings; hostile headers/bodies fail before dispatch | +| 2.10 / 2.10-API-A,B | FR-10 | 11 | API | E2-R2 | Global/operation security overrides, OR/AND and explicit no-auth bind compatible AuthProfileRef | Revoked/foreign/wrong-scheme refs rejected; imported secret canaries absent from API IR/plan/export surfaces | +| 2.13 / 2.13-INT-A,B | FR-11 | 15 | INT | E2-R1/E2-R3 | skip/rename/new_version decisions apply atomically with immutable report and scoped replay | Concurrent/stale/conflicting plans and crash before/after commit leave no partial or mutated Published state | +| 2.14 / 2.14-INT-A,B | FR-12 | 13 | INT | E2-R1 | Checksummed corpus of at least 50 specs yields ≥95% actionable operations and zero silent loss | Bad fixture/checksum/unsupported construct is explicit; offline rerun reproduces oracle and evidence | + +### P1 — High + +Core user journeys and complex integrations; limited workaround, not relaxed acceptance. + +| Story / scenario IDs | Requirements | AC groups | Primary level | Risk | A: expected behavior | B: rejection / fault | +|---|---|---:|---|---|---|---| +| 2.6 / 2.6-E2E-A,B | FR-7, FR-9 | 5 | E2E | E2-R4 | Real multipart upload renders actionable preview and safe support IDs | Replace/navigation/cancel races reject stale responses; RU/EN keyboard flow and clean required evidence | +| 2.11 / 2.11-E2E-A,B | FR-10 | 3 | E2E | E2-R2/E2-R4 | Security mapping UI makes the selected compatible AuthProfileRef and explicit no-auth state visible without exposing secrets | Stale/foreign/revoked/wrong-scheme selections and secret canaries are rejected or absent from browser-visible state | +| 2.12 / 2.12-API-A,B | FR-7 | 14 | API | E2-R1/E2-R4 | Preview classifies every operation and computes dependency-closed explicit partial ImportPlan | Blockers/stale digest cannot apply; bounded 2k pagination and out-of-order UI updates do not change selection | +| 2.15 / 2.15-E2E-A,B | FR-7, FR-11, FR-33 | 7 | E2E | E2-R4 | OpenAPI onboarding reuses upload → selection → publish → Agent → real MCP call | Return context/digest changes/retry must not auto-publish, duplicate records or claim activation without call | + +### P2 / P3 + +No additional mandatory scope. Optional focused exploratory/cosmetic variants may be recorded later with owner and justification; they do not become an endless implementation/review queue. + +Levels: UNIT pure contract/model; INT real filesystem/database/runtime boundary; API actual handler/protocol; E2E critical browser journey; SYS isolated full-stack qualification; MANUAL named human protocol. Use unit cases for algorithms, real PG for transaction/fencing, wire fixtures for protocol, browser only for user-visible interaction. Intentional defense-in-depth checks different failure surfaces, not identical duplicated assertions. + +## Execution Strategy + +Run all functional tests in PRs when they fit the target 15-minute feedback window; defer only expensive infrastructure/duration, not inconvenient failures. Current Playwright is Chromium, one worker: parallelization is a future isolation-dependent optimization, not a current claim. + +- **PR:** changed functional/negative regressions and boundary suites; applicable Rust/tooling/config and UI gates. +- **Nightly:** bounded fault/contention, repeated isolation and resource trend tests after the required seams exist. +- **Weekly:** calibrated production-size performance, fresh-host/offline/recovery and manual qualification as applicable. +- **Epic / RC acceptance:** every mandatory AC and quantitative obligation must have exact-candidate evidence, even if its normal execution tier is weekly. Epic 8 owns the immutable long-duration release windows. + +Nightly/weekly scheduling is a proposed execution model; the current Gitea pipeline has PR/push and release jobs, not those schedules. This planning task does not create them. `just verify` does not replace Playwright, deployment/image or qualification jobs. + +## Resource Estimates + +Incremental QA test/evidence effort with working production seams and reusable fixtures, excluding feature implementation, provisioning lead time and unaccelerated duration. Low-confidence planning ranges, not token budgets or compulsory numbers of new tests; reassess at each story ATDD after deduplication. + +| Priority | Estimated effort | +|---|---| +| P0 | 40–80 hours | +| P1 | 20–40 hours | +| Optional P2 | 0–8 hours | +| Optional P3 | 0–4 hours | +| Total envelope | 60–132 hours, approximately 2–4 contributor-weeks | + +If a measurement environment is missing, report the prerequisite; do not run large workloads opportunistically inside a story session. + +## Exit Criteria and Quality Gates + +- P0 pass 100%; P1 ≥95% is an interim development signal only, **100% of mandatory P1 and manual ACs must pass for acceptance**. +- Every owning-story AC has test/protocol plus bound execution evidence; no mandatory skipped/flaky/blocked/not-run item becomes pass. +- No unresolved Critical/High defect; high-risk mitigation verified on the owning scenario before release. Mandatory Habr conditions have no waiver. +- Coverage targets remain system planning goals (80% workspace /90% new critical code where measured); **no coverage report currently proves them**. Scenario counts do not substitute for coverage instrumentation. +- NFR evidence names revision, config/topology, tool/data versions, command, seed, timestamps, raw sanitized output digest and result. +- Story completion follows its spec, not all remaining epic/system gaps; no automatic reopening of done stories. + +## Mitigation Plans + +Each high-risk owner in the matrix: (1) implement/reuse the production-safe seam; (2) run its A/B and detailed AC cases with controlled failures; (3) bind the output to the candidate; (4) re-evaluate residual risk. Status is planned or source-partial, never verified solely by this document. Required completion time is the owning story/epic milestone in the risk table. No generic follow-up review loop is created. + +## Assumptions and Dependencies + +Epic 1 safety foundation → 2.1/b/e/f → 2.5/d → 2.7 → 2.8 → 2.9 → 2.10/2.11 → 2.12 → 2.13 → 2.14 → 2.15; retain the explicit dependency graph in epics.md. Do not start later work by treating candidate-only 2.9 as merged. + +Accountable roles are responsibilities, not claims of staffed teams. Reference hardware, operator credentials and manual reviewers must be assigned before relevant qualification. Use disposable fixtures while waiting; lack of resources blocks the affected evidence, not permission to mutate a live deployment. + +## Interworking and Regression + +Affected components and reusable suites are named in Existing Coverage. Preserve existing REST→MCP, auth/credential/approval, config/migration, correlation and Community-boundary behavior whenever those shared contracts change. Frontend failures need actual browser regression; registry races need real-PG assertions, not UI mocks. + +## ATDD Handoff + +For the selected not-yet-implemented story only, load this plan and the exact approved spec; freeze its finite AC-to-test checklist before implementation. Prefer existing Rust/PG/Playwright patterns, add only uncovered acceptance scenarios and reproduce RED for missing behavior without artificial failure. Existing correct behavior may already be GREEN: record it honestly. Resume matching incomplete ATDD, reuse completed matching checklists and update only changed ACs. Do not invoke whole-epic automation on each review. + +Automatic pre-implementation ATDD requires the project build-auto handoff override; the stock bmad-loop0.11.1 TEA ATDD injection is post-dev and is not that sequence. Loop configuration is separate from completion of this plan. The design workflow itself does not run ATDD or product implementation. + +## References and Validation + +- Epic/AC source: `_bmad-output/planning-artifacts/epics.md`, Epic 2. +- System contract: [architecture](test-design-architecture.md), [QA inventory and execution](test-design-qa.md). +- Normative PRD and architecture spine: frontmatter inputDocuments. +- TEA knowledge: risk-governance, probability-impact, test-levels-framework, test-priorities-matrix, nfr-criteria. +- Utility integration: Playwright/Pact flags are true but packages absent. No imports, framework migration or Pact service are generated. Browser CLI unavailable; source-based design only. +- Validation: story IDs, approved old→new AC allocation, requirements, risk arithmetic/linkage and document paths checked; no final test/NFR PASS issued. Approval is planning-level user direction, not fabricated reviewer signatures. diff --git a/_bmad-output/test-artifacts/test-design-epic-3.md b/_bmad-output/test-artifacts/test-design-epic-3.md new file mode 100644 index 0000000..f2d9ea2 --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-epic-3.md @@ -0,0 +1,189 @@ +--- +runScope: 'epic-level' +runKey: 'epic-3' +workflowStatus: 'completed' +workflowType: 'testarch-test-design' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +lastSaved: '2026-09-13' +auditedRevision: '083974c27f3a21a15807dd248bb6bc4fe04a5cd8' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' +--- + +# Test Design: Epic 3 — Полноценный современный MCP-каталог + +**Date:** 2026-09-13 +**Author:** Bsodfather / BMad TEA +**Status:** Updated planning baseline; qualification not evaluated. + +## Executive Summary + +Scope: FR-13–FR-20, 20 stories, system scenario families CP-08..11. This plan reflects the approved numbering revision; it neither changes product scope nor marks stories complete. + +3 inherent risks, 3 high (score ≥6). Coverage seeds: 26 P0 and 14 P1 independently assertable scenarios. Counts describe the two seeds per story below, not implemented tests, coverage percentages or the eventual parameterized case count. Every source AC remains mandatory. + +## Existing Coverage and Evidence + +Source inventory at main `083974c`: `crates/crank-community-mcp/tests/unit/{manifest,session,tool_error}.rs`; `apps/mcp-server/tests/integration/{transport_protocol,catalog_access,tool_search,execution_stages}.rs`; `apps/ui/tests/e2e/onboarding.spec.js`. + +Existing tests cover baseline Tools, transport, catalog and runtime only. Resources/Prompts/modern adapter matrix are planned; no feature-level tests were found in main. Do not confuse MCP client-library behavior with implementation evidence. Tasks cells are completed by Story 4.7; 3.20 must mark them pending rather than falsely PASS. + +Source presence ≠ execution ≠ requirement coverage ≠ qualification. No product test, deployment or load execution was performed for this plan. Reuse source tests only after matching their oracle to the current AC and recording a run on the candidate under test. + +## Not in Scope + +| Item | Reason | Mitigation | +|---|---|---| +| Unrelated future-epic implementation and whole-product refactoring | This is Epic 3 test planning | Keep explicit prerequisites below; do not invent additional story acceptance | +| SSO/RBAC enterprise features, non-REST adapters, HA/rolling deployment | Outside approved Community scope | Preserve Community boundary checks | +| Declaring current production readiness from source inventory | No bound qualification run | Require real evidence before gate | +| Product-wide 72-hour soak / 30-day burn-in | Owned by Epic 8 | Component fault/performance obligations in this epic remain required | + +## Risk Assessment + +Score = probability × impact on a 1–3 scale. Score ≥6 needs verified mitigation; 9 is an unresolved critical release risk, not a command to implement every mitigation immediately. Categories: SEC security, DATA integrity, OPS operations, PERF performance, BUS user behavior, TECH architecture/testing. + +| Risk ID | Category | Failure | P | I | Score | System risk | Mitigation / accountable role / deadline | +|---|---|---|---:|---:|---:|---|---| +| E3-R1 | BUS | Advertised capabilities or version behavior disagree | 2 | 3 | 6 | R-009 | Revision/client matrix and wire errors; MCP owner, 3.20 | +| E3-R2 | SEC | Resource/Prompt scope or REST expansion leaks data | 3 | 3 | 9 | R-004 | Negative authorization + SSRF + redaction; Security, 3.8/3.11/3.16 | +| E3-R3 | DATA | Mutable catalog or stale cursor serves wrong published version | 2 | 3 | 6 | R-009 | Snapshot/revoke races; Registry/MCP, publication stories | + +Medium risks: shared R-012 (4), deterministic test isolation; QA owns continuous monitoring. No additional low risk is invented just to fill a template. Residual risk is unmeasured until evidence exists. + +## NFR Planning + +Discovery p95 ≤150 ms on 2,000 Operations/200 Agents; zero unauthorized metadata/content reads. Pin stable/N-1/N-2 and ≥3 clients at feature freeze. The 2026-07-28 wire shapes named in epics.md are planning inputs, not a newly verified claim about latest MCP; verify official specifications/digests before adapter ATDD, preserving legacy deprecation gate. + +| Category | Scenario linkage | Planned validation / evidence | +|---|---|---| +| Security/privacy | SEC risks and B scenarios below | Scope/abuse/canary tests, bounded sanitized logs and network/scan report | +| Reliability/data integrity | DATA/OPS risks and fault scenarios | Real authority/state assertions, fault schedule and reconciled counters/digests | +| Performance/scalability | Numeric epic obligations above | Calibrated raw latency/resource samples, achieved load and immutable config/topology fingerprint | +| Maintainability/compatibility | Every changed component | Existing `just verify`/UI gates as applicable, schema/contract diffs and traceable regression reports | + +Unknowns: exact execution hardware and fresh qualification artifacts are not available from this audit. Where the owning story requires a new tolerance, limit or version selection, freeze it in its approved contract before writing a numeric assertion; never replace the PRD threshold with a guessed easier value. Full NFR verdict belongs to `bmad-testarch-nfr` after execution. + +## Entry Criteria + +- Approved owning story/spec and prerequisites are available in the same worktree. +- ATDD loads the actual ACs from `epics.md` / selected spec and the system QA design. +- Existing tests and baseline failures are inspected before adding tests; no duplicate test suite solely for new IDs. +- Wire fixtures per protocol era; scope-separated Agent catalogs; text/JSON/binary hostile resources; exact-version graphs; capture upstream; clock/cancellation barriers; browser keyboard and RU/EN fixtures. +- Missing fixture, service or approval is reported as blocked/not-run, not silently skipped. + +## Test Coverage Plan + +P0/P1/P2/P3 indicate priority, **not execution timing**. Each table row has two separate scenario seeds: `--A` and `...-B`. Split a seed when independent assertions require different fixtures. Reuse an existing equivalent test rather than duplicating it; ATDD records exact test name/path and AC mapping. + +The AC-count column inventories all `Given` groups under that source story, not a claim that two tests exhaust those groups. The approved splits preserve source ACs: 3.4 owns former 3.4 groups 1–4 and part of 7; 3.5 owns 5, 6 and the remaining signal part of 7. Former Prompt groups distribute as 3.12 (1–3 plus Draft/preview portions), 3.13 (4–5 plus publish/binding portions), 3.14 (6–8 plus list/get portion) and 3.15 (9 plus portability UI portion). Former 3.13 groups distribute as 3.17 (1 plus completion portions), 3.18 (2 plus logging portions), and 3.19 (3–4 plus Resource/Prompt-signal portions). ATDD must map each group (story + ordinal + quoted acceptance text) to existing test, new test, or explicit not-run prerequisite before implementation. The approved spec controls finer-grained cases. + +### P0 — Critical + +Security, irreversible data integrity and false acceptance have no safe user workaround. + +| Story / scenario IDs | Requirements | AC groups | Primary level | Risk | A: expected behavior | B: rejection / fault | +|---|---|---:|---|---|---|---| +| 3.1 / 3.1-API-A,B | FR-13 | 14 | API | E3-R1 | Separate stateless server/discover and legacy initialize/session adapters according to pinned requirements | Malformed/mixed-era identity, disabled extension and unsupported revision never silently route to another adapter | +| 3.3 / 3.3-API-A,B | FR-14 | 7 | API | E3-R1/E3-R2 | tools/call validates exact schema and returns revision-correct structured outcomes | Invalid input/auth/approval failures perform no dispatch; upstream outcomes remain honest | +| 3.6 / 3.6-INT-A,B | FR-15, FR-16 | 8 | INT | E3-R2 | Typed text/JSON/binary Resource Draft stores verified immutable content reference | Oversize/corrupt content and unsafe HTML/SVG preview cannot execute or leak | +| 3.7 / 3.7-INT-A,B | FR-15, FR-16 | 6 | INT | E3-R3 | Publishing and Agent binding pin Resource Version/catalog revision | Concurrent edit/archive/publish and stale Agent revision cannot mutate a published snapshot | +| 3.8 / 3.8-API-A,B | FR-15, FR-16 | 5 | API | E3-R2/E3-R3 | resources/list/read returns bound content with correct MIME/binary shape | Authorization precedes content read; foreign/revoked/unpublished versions and stale cursor denied | +| 3.10 / 3.10-UNIT-A,B | FR-16 | 6 | UNIT | E3-R2 | REST-backed template binds exact read-only Published Operation and typed URI variables | Write/approval-dependent operation, host/path injection and invalid cache scope rejected | +| 3.11 / 3.11-INT-A,B | FR-16 | 11 | INT | E3-R2/E3-R3 | Resource read uses shared runtime/auth/cache/REST adapter and correct content conversion | Traversal/SSRF/credential revocation or dependency change fails safely without cross-scope cache reuse | +| 3.12 / 3.12-API-A,B | FR-17 | 5 | API | E3-R2/E3-R3 | Prompt Draft and preview preserve typed parameters and fixed role boundaries before publication | Invalid args, unsafe preview and foreign Draft access produce no partial render or leaked output | +| 3.13 / 3.13-INT-A,B | FR-17 | 4 | INT | E3-R2/E3-R3 | Prompt publication and Agent binding pin an immutable typed revision | Concurrent edit/archive/publish and stale Agent revision cannot mutate a published prompt | +| 3.14 / 3.14-API-A,B | FR-17 | 4 | API | E3-R2/E3-R3 | prompts/list and prompts/get expose only exact bound Published revisions | Foreign/archive/revocation, bad arguments and stale cursor cannot reveal or partially render content | +| 3.16 / 3.16-INT-A,B | FR-18 | 10 | INT | E3-R2/E3-R3 | Prompt composition pins Resource graph and propagates sensitivity | Cycles, delimiter/role injection and dynamic resource failure cannot yield leaked/partial output | +| 3.20 / 3.20-INT-A,B | FR-20 | 9 | INT | E3-R1 | Executable matrix maps each stable capability to exact adapter and ≥3 representative clients | Deferred stable cell/missing evidence blocks claim; experimental cells isolated and disabled path preserved | + +### P1 — High + +Core user journeys and complex integrations; limited workaround, not relaxed acceptance. + +| Story / scenario IDs | Requirements | AC groups | Primary level | Risk | A: expected behavior | B: rejection / fault | +|---|---|---:|---|---|---|---| +| 3.2 / 3.2-API-A,B | FR-14 | 5 | API | E3-R1/E3-R3 | tools/list exposes only exact bound Published versions with opaque pagination | Stale/foreign/tampered cursor and revoked binding do not reveal metadata or wrong revision | +| 3.4 / 3.4-API-A,B | FR-14 | 5 | API | E3-R1 | Monotonic bounded progress and cancel lifecycle preserve certainty across dispatch boundaries | Cancel-before/after-dispatch races preserve certainty; abusive tokens denied | +| 3.5 / 3.5-API-A,B | FR-14 | 3 | API | E3-R1 | Negotiated Tool catalog-change signal has authoritative refresh after loss | Unnegotiated notifications and malformed/rate-abusive tokens are denied | +| 3.9 / 3.9-E2E-A,B | FR-15 | 3 | E2E | E3-R2/E3-R3 | Resource import/export creates new owned Draft and verifies digest | Malformed/oversized/foreign artifact or stale UI action rejected; keyboard/RU/EN and inert preview verified | +| 3.15 / 3.15-E2E-A,B | FR-17 | 3 | E2E | E3-R2/E3-R3 | Prompt portability/import-export UI creates an owned Draft without changing a Published revision | Malformed/foreign import or stale UI action is rejected; keyboard/RU/EN and inert preview verified | +| 3.17 / 3.17-API-A,B | FR-19 | 3 | API | E3-R1/E3-R2 | Completion returns bounded authorized suggestions for Prompt arguments and Resource template parameters under the negotiated capability | Suggestions enforce scope and malformed tokens/rate bounds fail safely | +| 3.18 / 3.18-API-A,B | FR-19 | 3 | API | E3-R1/E3-R2 | Logging follows the negotiated capability with redacted structured entries | Sensitive fields and malformed tokens/rate bounds cannot leak or alter logs | +| 3.19 / 3.19-API-A,B | FR-19 | 3 | API | E3-R1/E3-R2 | Resource/Prompt change signals follow negotiated capability with polling recovery | Unauthorized, malformed or unnegotiated signals cannot change client-visible catalog state | + +### P2 / P3 + +No additional mandatory scope. Optional focused exploratory/cosmetic variants may be recorded later with owner and justification; they do not become an endless implementation/review queue. + +Levels: UNIT pure contract/model; INT real filesystem/database/runtime boundary; API actual handler/protocol; E2E critical browser journey; SYS isolated full-stack qualification; MANUAL named human protocol. Use unit cases for algorithms, real PG for transaction/fencing, wire fixtures for protocol, browser only for user-visible interaction. Intentional defense-in-depth checks different failure surfaces, not identical duplicated assertions. + +## Execution Strategy + +Run all functional tests in PRs when they fit the target 15-minute feedback window; defer only expensive infrastructure/duration, not inconvenient failures. Current Playwright is Chromium, one worker: parallelization is a future isolation-dependent optimization, not a current claim. + +- **PR:** changed functional/negative regressions and boundary suites; applicable Rust/tooling/config and UI gates. +- **Nightly:** bounded fault/contention, repeated isolation and resource trend tests after the required seams exist. +- **Weekly:** calibrated production-size performance, fresh-host/offline/recovery and manual qualification as applicable. +- **Epic / RC acceptance:** every mandatory AC and quantitative obligation must have exact-candidate evidence, even if its normal execution tier is weekly. Epic 8 owns the immutable long-duration release windows. + +Nightly/weekly scheduling is a proposed execution model; the current Gitea pipeline has PR/push and release jobs, not those schedules. This planning task does not create them. `just verify` does not replace Playwright, deployment/image or qualification jobs. + +## Resource Estimates + +Incremental QA test/evidence effort with working production seams and reusable fixtures, excluding feature implementation, provisioning lead time and unaccelerated duration. Low-confidence planning ranges, not token budgets or compulsory numbers of new tests; reassess at each story ATDD after deduplication. + +| Priority | Estimated effort | +|---|---| +| P0 | 60–120 hours | +| P1 | 32–64 hours | +| Optional P2 | 0–12 hours | +| Optional P3 | 0–4 hours | +| Total envelope | 92–200 hours, approximately 3–6 contributor-weeks | + +If a measurement environment is missing, report the prerequisite; do not run large workloads opportunistically inside a story session. + +## Exit Criteria and Quality Gates + +- P0 pass 100%; P1 ≥95% is an interim development signal only, **100% of mandatory P1 and manual ACs must pass for acceptance**. +- Every owning-story AC has test/protocol plus bound execution evidence; no mandatory skipped/flaky/blocked/not-run item becomes pass. +- No unresolved Critical/High defect; high-risk mitigation verified on the owning scenario before release. Mandatory Habr conditions have no waiver. +- Coverage targets remain system planning goals (80% workspace /90% new critical code where measured); **no coverage report currently proves them**. Scenario counts do not substitute for coverage instrumentation. +- NFR evidence names revision, config/topology, tool/data versions, command, seed, timestamps, raw sanitized output digest and result. +- Story completion follows its spec, not all remaining epic/system gaps; no automatic reopening of done stories. + +## Mitigation Plans + +Each high-risk owner in the matrix: (1) implement/reuse the production-safe seam; (2) run its A/B and detailed AC cases with controlled failures; (3) bind the output to the candidate; (4) re-evaluate residual risk. Status is planned or source-partial, never verified solely by this document. Required completion time is the owning story/epic milestone in the risk table. No generic follow-up review loop is created. + +## Assumptions and Dependencies + +Epic 1 foundation; 3.1 adapter registration before capability stories. 3.7 publication before static reads/templates/prompts; 3.11 + 3.13 before composition. 3.20 matrix extends in 4.7 rather than fabricating Tasks support. + +Accountable roles are responsibilities, not claims of staffed teams. Reference hardware, operator credentials and manual reviewers must be assigned before relevant qualification. Use disposable fixtures while waiting; lack of resources blocks the affected evidence, not permission to mutate a live deployment. + +## Interworking and Regression + +Affected components and reusable suites are named in Existing Coverage. Preserve existing REST→MCP, auth/credential/approval, config/migration, correlation and Community-boundary behavior whenever those shared contracts change. Frontend failures need actual browser regression; registry races need real-PG assertions, not UI mocks. + +## ATDD Handoff + +For the selected not-yet-implemented story only, load this plan and the exact approved spec; freeze its finite AC-to-test checklist before implementation. Prefer existing Rust/PG/Playwright patterns, add only uncovered acceptance scenarios and reproduce RED for missing behavior without artificial failure. Existing correct behavior may already be GREEN: record it honestly. Resume matching incomplete ATDD, reuse completed matching checklists and update only changed ACs. Do not invoke whole-epic automation on each review. + +Automatic pre-implementation ATDD requires the project build-auto handoff override; the stock bmad-loop0.11.1 TEA ATDD injection is post-dev and is not that sequence. Loop configuration is separate from completion of this plan. The design workflow itself does not run ATDD or product implementation. + +## References and Validation + +- Epic/AC source: `_bmad-output/planning-artifacts/epics.md`, Epic 3. +- System contract: [architecture](test-design-architecture.md), [QA inventory and execution](test-design-qa.md). +- Normative PRD and architecture spine: frontmatter inputDocuments. +- TEA knowledge: risk-governance, probability-impact, test-levels-framework, test-priorities-matrix, nfr-criteria. +- Utility integration: Playwright/Pact flags are true but packages absent. No imports, framework migration or Pact service are generated. Browser CLI unavailable; source-based design only. +- Validation: story IDs/requirements/AC counts, risk arithmetic/linkage and document paths checked; no final test/NFR PASS issued. Approval is planning-level user direction, not fabricated reviewer signatures. diff --git a/_bmad-output/test-artifacts/test-design-epic-4.md b/_bmad-output/test-artifacts/test-design-epic-4.md new file mode 100644 index 0000000..9382840 --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-epic-4.md @@ -0,0 +1,179 @@ +--- +runScope: 'epic-level' +runKey: 'epic-4' +workflowStatus: 'completed' +workflowType: 'testarch-test-design' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +lastSaved: '2026-09-13' +auditedRevision: '083974c27f3a21a15807dd248bb6bc4fe04a5cd8' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' +--- + +# Test Design: Epic 4 — Безопасные параллельные и фоновые выполнения + +**Date:** 2026-09-13 +**Author:** Bsodfather / BMad TEA +**Status:** Updated planning baseline; qualification not evaluated. + +## Executive Summary + +Scope: FR-21–FR-26, 10 stories, system scenario families CP-12..15. This plan reflects the approved numbering revision; it neither changes product scope nor marks stories complete. + +3 inherent risks, 3 high (score ≥6). Coverage seeds: 16 P0 and 4 P1 independently assertable scenarios. Counts describe the two seeds per story below, not implemented tests, coverage percentages or the eventual parameterized case count. Every source AC remains mandatory. + +## Existing Coverage and Evidence + +Source inventory at main `083974c`: `crates/crank-runtime/tests/{stages,product_metrics}.rs`, `crates/crank-runtime/tests/integration/{idempotency,confirmation,valkey}.rs`, `crates/crank-test-support/src/lib.rs` supply synchronous safety and real-PG fixture patterns. + +No durable Task/worker/admission lifecycle tests found in main. tokio::task usage is not MCP Tasks coverage. All story-specific Task acceptance scenarios are planned. Existing synchronous idempotency and approval tests must remain regression coverage, not be rewritten to make unsafe Task behavior pass. + +Source presence ≠ execution ≠ requirement coverage ≠ qualification. No product test, deployment or load execution was performed for this plan. Reuse source tests only after matching their oracle to the current AC and recording a run on the candidate under test. + +## Not in Scope + +| Item | Reason | Mitigation | +|---|---|---| +| Unrelated future-epic implementation and whole-product refactoring | This is Epic 4 test planning | Keep explicit prerequisites below; do not invent additional story acceptance | +| SSO/RBAC enterprise features, non-REST adapters, HA/rolling deployment | Outside approved Community scope | Preserve Community boundary checks | +| Declaring current production readiness from source inventory | No bound qualification run | Require real evidence before gate | +| Product-wide 72-hour soak / 30-day burn-in | Owned by Epic 8 | Component fault/performance obligations in this epic remain required | + +## Risk Assessment + +Score = probability × impact on a 1–3 scale. Score ≥6 needs verified mitigation; 9 is an unresolved critical release risk, not a command to implement every mitigation immediately. Categories: SEC security, DATA integrity, OPS operations, PERF performance, BUS user behavior, TECH architecture/testing. + +| Risk ID | Category | Failure | P | I | Score | System risk | Mitigation / accountable role / deadline | +|---|---|---|---:|---:|---:|---|---| +| E4-R1 | DATA | Stale lease or retry duplicates an external side effect | 3 | 3 | 9 | R-003 | Fencing + side-effect counters + unknown outcomes; Task owner, 4.3–4.6 | +| E4-R2 | PERF | Admission/queue exhaustion starves control plane | 3 | 3 | 9 | R-006 | Limits/fairness/recovery under load; Performance, 4.10 | +| E4-R3 | SEC | Cross-scope Task control or resume bypasses consent | 2 | 3 | 6 | R-004 | Owner-bound cancel/input/reconciliation; Security, 4.5–4.9 | + +Medium risks: shared R-012 (4), deterministic test isolation; QA owns continuous monitoring. No additional low risk is invented just to fill a template. Residual risk is unmeasured until evidence exists. + +## NFR Planning + +128 concurrent sync/background executions, up to 10,000 queued; start and steady queue wait p95 ≤5 s within service rate, oldest age ≤30 s; 10k backlog drains ≤60 minutes after overload ends. Shutdown ≤30 s and eligible lease recovery ≤60 s. Fencing protects Crank state, not exactly-once external side effects. + +| Category | Scenario linkage | Planned validation / evidence | +|---|---|---| +| Security/privacy | SEC risks and B scenarios below | Scope/abuse/canary tests, bounded sanitized logs and network/scan report | +| Reliability/data integrity | DATA/OPS risks and fault scenarios | Real authority/state assertions, fault schedule and reconciled counters/digests | +| Performance/scalability | Numeric epic obligations above | Calibrated raw latency/resource samples, achieved load and immutable config/topology fingerprint | +| Maintainability/compatibility | Every changed component | Existing `just verify`/UI gates as applicable, schema/contract diffs and traceable regression reports | + +Unknowns: exact execution hardware and fresh qualification artifacts are not available from this audit. Where the owning story requires a new tolerance, limit or version selection, freeze it in its approved contract before writing a numeric assertion; never replace the PRD threshold with a guessed easier value. Full NFR verdict belongs to `bmad-testarch-nfr` after execution. + +## Entry Criteria + +- Approved owning story/spec and prerequisites are available in the same worktree. +- ATDD loads the actual ACs from `epics.md` / selected spec and the system QA design. +- Existing tests and baseline failures are inspected before adding tests; no duplicate test suite solely for new IDs. +- Real PG independent worker connections; controllable clock/barriers and crash checkpoints before/after commit, claim, dispatch, side effect and terminal commit; counted upstream with and without verified idempotency; Valkey-off fixture; separate measured capacity host. +- Missing fixture, service or approval is reported as blocked/not-run, not silently skipped. + +## Test Coverage Plan + +P0/P1/P2/P3 indicate priority, **not execution timing**. Each table row has two separate scenario seeds: `--A` and `...-B`. Split a seed when independent assertions require different fixtures. Reuse an existing equivalent test rather than duplicating it; ATDD records exact test name/path and AC mapping. + +The AC-count column inventories all `Given` groups under that source story, not a claim that two tests exhaust those groups. The approved split preserves former 4.5 groups: 4.5 owns groups 1–3 and part of 6, while 4.6 owns 4–5 and the reconciliation part of 6. Former Admin UI groups split between 4.8 (1–3 and its basic/UI portions) and 4.9 (4–5 and the input/reconciliation portions). ATDD must map each group (story + ordinal + quoted acceptance text) to existing test, new test, or explicit not-run prerequisite before implementation. The approved spec controls finer-grained cases. + +### P0 — Critical + +Security, irreversible data integrity and false acceptance have no safe user workaround. + +| Story / scenario IDs | Requirements | AC groups | Primary level | Risk | A: expected behavior | B: rejection / fault | +|---|---|---:|---|---|---|---| +| 4.1 / 4.1-INT-A,B | FR-21, FR-24 | 7 | INT | E4-R2/E4-R3 | Pinned synchronous/background/adaptive admission shares safety policy and fair bounded permits | Global/per-Agent/per-Tool exhaustion and safety-store loss reject before allocation/dispatch | +| 4.2 / 4.2-INT-A,B | FR-22, FR-23 | 11 | INT | E4-R1/E4-R3 | Task and dispatch intent commit before acknowledgement; replay returns same Task/support IDs | Crash before/after commit, conflicting fingerprint, foreign access and terminal CAS races preserve durable truth | +| 4.3 / 4.3-INT-A,B | FR-22, FR-23 | 10 | INT | E4-R1 | SKIP LOCKED claim, renew and dispatch checkpoint enforce current fencing owner | Crash/partition/stale worker and lost Valkey wake-up recover via PG; stale owner cannot dispatch before checkpoint or commit after lease loss | +| 4.4 / 4.4-INT-A,B | FR-25 | 8 | INT | E4-R1 | Read/verified-idempotent retry respects attempt count, deadline and child spans | Write uncertainty after dispatch stays outcome_unknown; cancel/timeout/lease-loss cannot fabricate safe failure | +| 4.5 / 4.5-INT-A,B | FR-25 | 4 | INT | E4-R1/E4-R3 | Versioned input update transitions once under CAS and preserves task authority | TTL expiry, identical/conflicting replay and unauthorized update cause no new side effect | +| 4.6 / 4.6-INT-A,B | FR-25 | 3 | INT | E4-R1/E4-R3 | Evidence-bearing reconciliation transitions a Task once under CAS | Unauthorized normal retry of outcome_unknown and reconciliation replay cannot fabricate a safe result or new side effect | +| 4.7 / 4.7-API-A,B | FR-21, FR-22, FR-25 | 11 | API | E4-R1/E4-R3 | Negotiated Tasks extension returns durable IDs and supports exact get/update/cancel shapes plus fallback | Mixed revision/client-chosen collision/foreign scope denied; no invented tasks/list; disconnect does not cancel accepted work | +| 4.10 / 4.10-SYS-A,B | FR-23, FR-24 | 7 | SYS | E4-R1/E4-R2 | Qualified 128 concurrent / 10k queued workload meets start/wait/recovery budgets | Overload stop drains backlog without loss/duplicate terminal results; PG/Valkey/crash matrix preserves declared behavior | + +### P1 — High + +Core user journeys and complex integrations; limited workaround, not relaxed acceptance. + +| Story / scenario IDs | Requirements | AC groups | Primary level | Risk | A: expected behavior | B: rejection / fault | +|---|---|---:|---|---|---|---| +| 4.8 / 4.8-E2E-A,B | FR-26 | 6 | E2E | E4-R3 | Basic Task filters/detail and conditional actions preserve authoritative state | Stale polling and basic repeated actions remain safe; RU/EN keyboard/a11y and canary negatives | +| 4.9 / 4.9-E2E-A,B | FR-26 | 5 | E2E | E4-R3 | Input and reconciliation UI preserves authoritative state and conditional actions | Repeated submit and unknown-outcome Retry/Cancel remain safe; stale polling, RU/EN keyboard/a11y and canary negatives | + +### P2 / P3 + +No additional mandatory scope. Optional focused exploratory/cosmetic variants may be recorded later with owner and justification; they do not become an endless implementation/review queue. + +Levels: UNIT pure contract/model; INT real filesystem/database/runtime boundary; API actual handler/protocol; E2E critical browser journey; SYS isolated full-stack qualification; MANUAL named human protocol. Use unit cases for algorithms, real PG for transaction/fencing, wire fixtures for protocol, browser only for user-visible interaction. Intentional defense-in-depth checks different failure surfaces, not identical duplicated assertions. + +## Execution Strategy + +Run all functional tests in PRs when they fit the target 15-minute feedback window; defer only expensive infrastructure/duration, not inconvenient failures. Current Playwright is Chromium, one worker: parallelization is a future isolation-dependent optimization, not a current claim. + +- **PR:** changed functional/negative regressions and boundary suites; applicable Rust/tooling/config and UI gates. +- **Nightly:** bounded fault/contention, repeated isolation and resource trend tests after the required seams exist. +- **Weekly:** calibrated production-size performance, fresh-host/offline/recovery and manual qualification as applicable. +- **Epic / RC acceptance:** every mandatory AC and quantitative obligation must have exact-candidate evidence, even if its normal execution tier is weekly. Epic 8 owns the immutable long-duration release windows. + +Nightly/weekly scheduling is a proposed execution model; the current Gitea pipeline has PR/push and release jobs, not those schedules. This planning task does not create them. `just verify` does not replace Playwright, deployment/image or qualification jobs. + +## Resource Estimates + +Incremental QA test/evidence effort with working production seams and reusable fixtures, excluding feature implementation, provisioning lead time and unaccelerated duration. Low-confidence planning ranges, not token budgets or compulsory numbers of new tests; reassess at each story ATDD after deduplication. + +| Priority | Estimated effort | +|---|---| +| P0 | 64–128 hours | +| P1 | 20–40 hours | +| Optional P2 | 0–8 hours | +| Optional P3 | 0–4 hours | +| Total envelope | 84–180 hours, approximately 3–5 contributor-weeks | + +If a measurement environment is missing, report the prerequisite; do not run large workloads opportunistically inside a story session. + +## Exit Criteria and Quality Gates + +- P0 pass 100%; P1 ≥95% is an interim development signal only, **100% of mandatory P1 and manual ACs must pass for acceptance**. +- Every owning-story AC has test/protocol plus bound execution evidence; no mandatory skipped/flaky/blocked/not-run item becomes pass. +- No unresolved Critical/High defect; high-risk mitigation verified on the owning scenario before release. Mandatory Habr conditions have no waiver. +- Coverage targets remain system planning goals (80% workspace /90% new critical code where measured); **no coverage report currently proves them**. Scenario counts do not substitute for coverage instrumentation. +- NFR evidence names revision, config/topology, tool/data versions, command, seed, timestamps, raw sanitized output digest and result. +- Story completion follows its spec, not all remaining epic/system gaps; no automatic reopening of done stories. + +## Mitigation Plans + +Each high-risk owner in the matrix: (1) implement/reuse the production-safe seam; (2) run its A/B and detailed AC cases with controlled failures; (3) bind the output to the candidate; (4) re-evaluate residual risk. Status is planned or source-partial, never verified solely by this document. Required completion time is the owning story/epic milestone in the risk table. No generic follow-up review loop is created. + +## Assumptions and Dependencies + +Shared runtime/admission and MCP negotiation first; 4.1 → 4.2 → 4.3 → 4.4/4.5 → 4.6 → 4.7 → 4.8/4.9 → 4.10. Worker authority is PG; cache may only accelerate. + +Accountable roles are responsibilities, not claims of staffed teams. Reference hardware, operator credentials and manual reviewers must be assigned before relevant qualification. Use disposable fixtures while waiting; lack of resources blocks the affected evidence, not permission to mutate a live deployment. + +## Interworking and Regression + +Affected components and reusable suites are named in Existing Coverage. Preserve existing REST→MCP, auth/credential/approval, config/migration, correlation and Community-boundary behavior whenever those shared contracts change. Frontend failures need actual browser regression; registry races need real-PG assertions, not UI mocks. + +## ATDD Handoff + +For the selected not-yet-implemented story only, load this plan and the exact approved spec; freeze its finite AC-to-test checklist before implementation. Prefer existing Rust/PG/Playwright patterns, add only uncovered acceptance scenarios and reproduce RED for missing behavior without artificial failure. Existing correct behavior may already be GREEN: record it honestly. Resume matching incomplete ATDD, reuse completed matching checklists and update only changed ACs. Do not invoke whole-epic automation on each review. + +Automatic pre-implementation ATDD requires the project build-auto handoff override; the stock bmad-loop0.11.1 TEA ATDD injection is post-dev and is not that sequence. Loop configuration is separate from completion of this plan. The design workflow itself does not run ATDD or product implementation. + +## References and Validation + +- Epic/AC source: `_bmad-output/planning-artifacts/epics.md`, Epic 4. +- System contract: [architecture](test-design-architecture.md), [QA inventory and execution](test-design-qa.md). +- Normative PRD and architecture spine: frontmatter inputDocuments. +- TEA knowledge: risk-governance, probability-impact, test-levels-framework, test-priorities-matrix, nfr-criteria. +- Utility integration: Playwright/Pact flags are true but packages absent. No imports, framework migration or Pact service are generated. Browser CLI unavailable; source-based design only. +- Validation: story IDs/requirements/AC counts, risk arithmetic/linkage and document paths checked; no final test/NFR PASS issued. Approval is planning-level user direction, not fabricated reviewer signatures. diff --git a/_bmad-output/test-artifacts/test-design-epic-5.md b/_bmad-output/test-artifacts/test-design-epic-5.md new file mode 100644 index 0000000..a6f0aa4 --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-epic-5.md @@ -0,0 +1,231 @@ +--- +runScope: 'epic-level' +runKey: 'epic-5' +workflowStatus: 'completed' +workflowType: 'testarch-test-design' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +lastSaved: '2026-09-13' +lastEditMode: 'E' +lastEditScope: 'approved 5.9–5.13 Prometheus, notification gateway, Grafana, SLO and alert-delivery decomposition' +auditedRevision: '083974c27f3a21a15807dd248bb6bc4fe04a5cd8' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' +--- + +# Test Design: Epic 5 — Полная эксплуатационная видимость + +**Date:** 2026-09-13 +**Author:** Bsodfather / BMad TEA +**Status:** Updated planning baseline; qualification not evaluated. + +## Executive Summary + +Scope: FR-27–FR-35, 13 stories, system scenario families CP-16..21. This plan reflects the approved numbering revision; it neither changes product scope nor marks stories complete. + +Approved decision 2026-09-13: application alert delivery uses self-hosted Apprise API (HTTP gateway, no embedded Python in Rust). Story 5.9 owns Prometheus integration; 5.10 owns the provider-neutral notification gateway and tested evaluator payload adapter; 5.11 owns Grafana; 5.12 owns SLO measurement; 5.13 owns application alert delivery and end-of-epic evidence. Host/network/disk/infrastructure-service monitoring and independent whole-application outage detection belong to the infrastructure owner; application-visible dependency failures and existing safety/recovery obligations remain in scope. This is updated planning, not implementation evidence. + +6 inherent risks, 6 high (score ≥6). Coverage seeds: 22 P0 and 4 P1 independently assertable scenarios. Counts describe the two seeds per story below, not implemented tests, coverage percentages or the eventual parameterized case count. The 19 source AC rows now allocated across 5.9/5.10/5.12/5.13 below refine these seeds rather than add unrelated requirements or prescribe a test-file count. Every source AC remains mandatory. + +## Existing Coverage and Evidence + +Source inventory at main `083974c`: `crates/crank-observability/tests/{request_correlation,propagation,json_logging,redaction,critical_errors,otlp,prometheus,http_metrics,metrics_signals}.rs`; `apps/mcp-server/tests/integration/execution_stages.rs`; `apps/admin-api/tests/integration/logs_usage.rs`; `crates/crank-metrics/tests/`. + +IDs, local metric registry, redaction and captured OTLP are source-present foundations. Real GlitchTip receiver delivery, durable encrypted spool/loss reconciliation, complete ProductEvent rollups, packaged Prometheus/Grafana and SLO qualification are not proven by them. No services are provisioned in this task. + +Source presence ≠ execution ≠ requirement coverage ≠ qualification. No product test, deployment or load execution was performed for this plan. Reuse source tests only after matching their oracle to the current AC and recording a run on the candidate under test. + +Edit-mode source check at the same main revision: no Rust/Cargo matches for `NotificationMessage`, `NotificationSink`, `AppriseNotificationSink` or `apprise` under `crates`/`apps`. This search does not evidence the planned port/adapter; existing telemetry tests cannot be counted as its implementation or delivery proof. This targeted edit does not claim a whole-codebase re-audit. + +## Not in Scope + +| Item | Reason | Mitigation | +|---|---|---| +| Unrelated future-epic implementation and whole-product refactoring | This is Epic 5 test planning | Keep explicit prerequisites below; do not invent additional story acceptance | +| SSO/RBAC enterprise features, non-REST adapters, HA/rolling deployment | Outside approved Community scope | Preserve Community boundary checks | +| Declaring current production readiness from source inventory | No bound qualification run | Require real evidence before gate | +| Product-wide 72-hour soak / 30-day burn-in | Owned by Epic 8 | Component fault/performance obligations in this epic remain required | +| Host/LXC/VM, disk/network and infrastructure-service incident monitoring/remediation | Infrastructure owner responsibility | Document external availability monitoring handoff; preserve Crank dependency-failure diagnostics and safety tests | + +## Risk Assessment + +Score = probability × impact on a 1–3 scale. Score ≥6 needs verified mitigation; 9 is an unresolved critical release risk, not a command to implement every mitigation immediately. Categories: SEC security, DATA integrity, OPS operations, PERF performance, BUS user behavior, TECH architecture/testing. + +| Risk ID | Category | Failure | P | I | Score | System risk | Mitigation / accountable role / deadline | +|---|---|---|---:|---:|---:|---|---| +| E5-R1 | OPS | Spool/replay loss yields false trace completeness | 2 | 3 | 6 | R-005 | Independent envelope accounting and crash/outage; Observability, 5.6 | +| E5-R2 | SEC | Browser/export/link or notification route leaks secrets or executes unsafe URL | 3 | 3 | 9 | R-004 | Canaries, authenticated fixed routes and egress rejection; Security/UI, 5.2–5.4 and 5.10/5.13 | +| E5-R3 | DATA | Rollups/cardinality/SLI denominators lie | 2 | 3 | 6 | R-011 | Idempotency + UTC + rules oracles; Metrics, 5.8/5.12 | +| E5-R4 | PERF | Telemetry or notification pressure blocks product requests | 3 | 3 | 9 | R-006 | Quota isolation, bounded queue/retry/expiry and enabled/disabled comparison; Observability, 5.6/5.13 | +| E5-R5 | TECH | Provider fields escape the port or replacement silently changes queued recipients | 2 | 3 | 6 | Epic-local / AD-13 | Same suite on Apprise and recording sink; source boundaries and pinned route revision; Backend, 5.10 | +| E5-R6 | OPS | Accepted/uncertain/partial delivery is reported as received, or retries create an alert storm | 2 | 3 | 6 | Epic-local / FR-35 | Independent receiver ledger, fault classification and virtual-clock lifecycle; Backend/QA, 5.13 | + +Medium risks: shared R-012 (4), deterministic test isolation; QA owns continuous monitoring. No additional low risk is invented just to fill a template. Residual risk is unmeasured until evidence exists. + +## NFR Planning + +100% support IDs independent of sampling; healthy delivery ≥99.99% within60s; outage≤24h with100% saved-envelope delivery within25h, sized30h spool. Observability overhead≤5% p95 latency and≤10% CPU; drain≤30s. Availability30d≥99.95%, control plane≥99.9%. Exact series budgets/buckets and burn windows must use versioned typed/rule contracts; unspecified values remain UNKNOWN until owning story freezes them. + +| Category | Scenario linkage | Planned validation / evidence | +|---|---|---| +| Security/privacy | SEC risks and B scenarios below | Scope/abuse/canary tests, bounded sanitized logs and network/scan report | +| Reliability/data integrity | DATA/OPS risks and fault scenarios | Real authority/state assertions, fault schedule and reconciled counters/digests | +| Performance/scalability | Numeric epic obligations above | Calibrated raw latency/resource samples, achieved load and immutable config/topology fingerprint | +| Maintainability/compatibility | Every changed component | Existing `just verify`/UI gates as applicable, schema/contract diffs and traceable regression reports | + +Unknowns: exact execution hardware and fresh qualification artifacts are not available from this audit. Where the owning story requires a new tolerance, limit or version selection, freeze it in its approved contract before writing a numeric assertion; never replace the PRD threshold with a guessed easier value. Full NFR verdict belongs to `bmad-testarch-nfr` after execution. + +Notification unknowns to freeze once in the owning spec: evaluator/payload adapter and pinned Apprise version, queue/body capacity, timeout, retry/backoff/attempt limit, expiry and repeat/silence windows. Boundary tests use limit−1/limit/limit+1 and virtual time against these values. The trace spool's 24-hour/25-hour obligation is not automatically a notification delivery SLA. Unavailable pinned routes produce an explicit bounded failure, not fallback to another recipient. + +## Entry Criteria + +- Approved owning story/spec and prerequisites are available in the same worktree. +- ATDD loads the actual ACs from `epics.md` / selected spec and the system QA design. +- Existing tests and baseline failures are inspected before adding tests; no duplicate test suite solely for new IDs. +- For applicable stories only: local trace receiver and real GlitchTip qualification environment; independent generated/accepted/ACK/lost envelope ledger; bounded disk partitions and fault controls; golden UTC events; Prometheus synthetic series; provisioned Grafana fixture without committed secrets. Pure notification port tests do not require the whole stack. +- For 5.10/5.13: recording/fault-injection sink, controlled clock, bounded queue fixture and versioned logical routes; pinned Apprise API/private auth proxy and isolated local destination for integration. Gateway-acceptance and destination-receipt ledgers are separate. No production tokens, operator destinations or external messaging accounts. +- Missing fixture, service or approval is reported as blocked/not-run, not silently skipped. + +## Test Coverage Plan + +P0/P1/P2/P3 indicate priority, **not execution timing**. Each table row has two separate scenario seeds: `--A` and `...-B`. Split a seed when independent assertions require different fixtures. Reuse an existing equivalent test rather than duplicating it; ATDD records exact test name/path and AC mapping. + +The AC-count column inventories all `Given` groups under that source story, not a claim that two tests exhaust those groups. ATDD must map each group (story + ordinal + quoted acceptance text) to existing test, new test, or explicit not-run prerequisite before implementation. The approved spec controls finer-grained cases. + +### P0 — Critical + +Security, irreversible data integrity and false acceptance have no safe user workaround. + +| Story / scenario IDs | Requirements | AC groups | Primary level | Risk | A: expected behavior | B: rejection / fault | +|---|---|---:|---|---|---|---| +| 5.1 / 5.1-INT-A,B | FR-27 | 5 | INT | E5-R1/E5-R2 | Distinct Request/Trace IDs survive ingress, persistence, cache, retry and outbound spans with sampling off | Hostile/malformed upstream context cannot replace identity or leak raw fields | +| 5.3 / 5.3-API-A,B | FR-30 | 5 | API | E5-R2 | Scrubbed browser events use authenticated same-origin relay with bounded schemas | Disabled mode has no hooks/egress; CSRF/rate/body and secrets-in-stack/DOM/query tests reject leakage | +| 5.4 / 5.4-INT-A,B | FR-29 | 5 | INT | E5-R1/E5-R2 | Compatible receiver accepts envelopes with parent topology, release and IDs | Retryable/permanent/duplicate ACK classified; slow/outage exporter cannot change product result or readiness | +| 5.5 / 5.5-INT-A,B | FR-31 | 6 | INT | E5-R1/E5-R4 | Encrypted per-process/destination spool durably appends then ACKs and checkpoints consumption | Crash during append/ACK/compaction, corrupt tail, permissions and disk quota preserve accounting/reserves | +| 5.6 / 5.6-SYS-A,B | FR-29, FR-31 | 5 | SYS | E5-R1/E5-R4 | Measured 30h envelope and 24h outage/recovery satisfy delivery/completeness bounds | Disk-full/drop/rejection emits immutable local loss records; enabled-vs-disabled overhead stays bounded | +| 5.7 / 5.7-UNIT-A,B | FR-32 | 6 | UNIT | E5-R3/E5-R4 | Typed metric names/units/buckets/enum dimensions cover each implemented subsystem | Millions of distinct inputs do not increase series outside budget; IDs only exemplars | +| 5.8 / 5.8-INT-A,B | FR-33 | 7 | INT | E5-R3/E5-R2 | Idempotent ProductEvents and UTC rollups compute unique-Agent DAU, funnel and explicit denominators | Duplicates/late/cross-day/deleted entities give deterministic aggregates; missing data is not zero; offline no phone-home | +| 5.9 / 5.9-INT-A,B | FR-34 | 6 | INT | E5-R2/E5-R3 | Authorized scrape/rules and packaged Prometheus assets work without exposing secrets or blocking product probes | Wrong identity/TLS, arbitrary scrape paths, invalid rules/config reload and service outage remain visible and bounded | +| 5.10 / 5.10-INT-A,B | FR-35 | 3 | UNIT + INT | E5-R2/E5-R4/E5-R5 | Provider-neutral NotificationSink and evaluator payload adapter work with Apprise and recording sink without producer/rule/UI changes | Provider leakage, silent queued-message rerouting, arbitrary routes and disabled egress cannot compromise runtime or expose secrets | +| 5.12 / 5.12-INT-A,B | FR-35 | 5 | UNIT + INT | E5-R3/E5-R4 | Synthetic series prove denominators, burn windows, missing-data treatment and SLO state | Missing scrapes, duplicate/out-of-order data and zero denominators cannot create false green | +| 5.13 / 5.13-INT-A,B | FR-35 | 5 | UNIT + INT | E5-R2/E5-R4/E5-R6 | Real-stack firing/resolved application alerts reach configured test receiver with grouping and silence; final Epic 5 evidence links the same candidate | Uncertain delivery, partial failures, restart, queue/retry expiry and canary leakage cannot create false receipt, notification storm or product blocking | + +### P1 — High + +Core user journeys and complex integrations; limited workaround, not relaxed acceptance. + +| Story / scenario IDs | Requirements | AC groups | Primary level | Risk | A: expected behavior | B: rejection / fault | +|---|---|---:|---|---|---|---| +| 5.2 / 5.2-E2E-A,B | FR-28 | 6 | E2E | E5-R1/E5-R2 | Scoped exact-ID timeline, separate copy actions and validated trace link find real call | Foreign search, stale response and script/credential URL template rejected; backend outage retains local diagnosis | +| 5.11 / 5.11-E2E-A,B | FR-34 | 5 | E2E | E5-R1/E5-R3 | Provisioned Grafana datasource/panels return correctly unit-labelled data and exemplar links | Missing/stale datasource, unsafe links/variables and upgrade UID drift are visible, never false green; actual Load Run data acceptance is deferred to 6.6 | + +### Mandatory Prometheus, notification, SLO and alert-delivery design — refinements of the P0 seeds + +For 5.9/5.10/5.12/5.13 ATDD, freeze finite cases for endpoint authentication (a config key is not authentication), operator-controlled routes, outbound opt-in, sanitized payloads, stable fingerprint and firing/resolved lifecycle, silence/repeat policy, timeout/permanent/partial failure and bounded retry/expiry. Separate API acceptance from downstream receipt evidence; never infer exactly-once delivery. Use a pinned gateway with a local controlled destination, not real customer channels. No infrastructure monitoring product or new public alert-management surface is implied. + +Provider-neutrality regression: run the same NotificationSink contract suite against Apprise and an independent recording/fault-injection sink; assert canonical message serialization, logical routes, typed delivery outcomes, common retry/redaction/accounting and versioned queued-route behavior. Source-boundary checks reject provider DTOs/URLs/credentials in producers and common message types. A second production delivery integration is not required. This general gateway covers operator/application notifications, not MCP wire notifications. + +AC identities below retain the ordinal `Given` group from the pre-split source story and its approved destination. 5.9 owns former groups 1–6, 5.10 former 7–9, 5.12 former SLO groups 1–5, and 5.13 former delivery groups 6–10. ATDD retains quoted text as well as ordinal, so later insertion cannot silently change the mapping. All rows are planned/not-run. Separate fixtures may split a row without adding scope. + +| AC / source Given | Level | Required oracle and reusable seam | +|---|---|---| +| 5.9-AC01 — Community minimal profile | INT | Minimal metrics works without gateway; enabled versioned production profile starts its intended services. | +| 5.9-AC02 — metrics endpoint на non-loopback interface | API/INT | Dedicated machine identity accepted; absent/wrong identity and Admin/MCP credentials denied under the configured TLS/proxy policy. | +| 5.9-AC03 — authorized scrape | INT | Valid bounded OpenMetrics; concurrent/slow/unauthorized scrapes respect limits while product probes remain responsive. | +| 5.9-AC04 — packaged Prometheus assets | UNIT/INT | Versioned rules/config validate against registry labels/buckets, not just file existence. | +| 5.9-AC05 — config reload либо service outage | INT | Reload/outage preserves product result/readiness; local diagnostic identifies scrape/auth failure without secret values. | +| 5.9-AC06 — integration/security suite | INT | Supported deployment modes cover auth, proxy, cardinality, rule syntax and restart; evidence records build/config fingerprint. | +| 5.10-AC07 — оператор включает application alert delivery | INT | Packaged and operator-managed fixtures use explicit payload mapping; authenticated private ingress rejects config-key-only access; disabled egress produces no external traffic; local receiver confirms enabled delivery. No embedded Python in Rust. | +| 5.10-AC08 — application producer либо alert evaluator ingress | UNIT/contract | Roundtrip canonical envelope and logical route; dependency/source checks keep provider fields out of producers/core. MCP wire notifications do not invoke the sink; shared dispatch policies are provider-independent. | +| 5.10-AC09 — Apprise sink и независимый recording/fault-injection test sink | UNIT/INT | Unchanged producer fixture/harness run on both sinks with accepted/retryable/permanent/uncertain outcomes. Queue under route revision A, switch config to B: no silent recipient change, identical common sanitization/accounting. | +| 5.12-AC01 — versioned SLO specification | UNIT | Golden contract contains approved objectives, numerator/denominator, exclusions, maintenance and missing-data semantics. | +| 5.12-AC02 — recording rules | UNIT | Synthetic outcome taxonomy separates product, saturation, upstream and client failures as runtime codes prescribe. | +| 5.12-AC03 — 30-day window | INT/E2E | Seeded series drive objective/compliance/budget/trend and distinct Task/telemetry panels; not a real 30-day burn-in claim. | +| 5.12-AC04 — fast либо slow burn | UNIT/INT | Virtual-time thresholds yield expected severity/SLO/burn/dashboard/runbook; unavailable GlitchTip does not erase basic diagnosis. | +| 5.12-AC05 — synthetic good/bad series и missing scrapes | UNIT | Fire/recover at pinned windows, including missing data and zero denominators; linked rule/runbook coverage has no false green. | +| 5.13-AC06 — завершение Epic 5 | SYS | At epic acceptance, link FR-27..35/NFR-O evidence on the same candidate and demonstrate real local/GlitchTip Trace ID lookup. Not a whole-epic rerun on each adapter edit. | +| 5.13-AC07 — каталог application alerts | UNIT/MANUAL | Catalog/runbooks cover application signals and infrastructure handoff. Dependency injection proves application diagnosis/SLI classification, not host remediation. | +| 5.13-AC08 — firing, repeated и resolved состояния | UNIT/INT | Script fingerprint/lifecycle and virtual-clock repeat/silence boundaries; independent receiver confirms grouped firing/resolved and safe links. Missing trace omits the link, never fabricates correlation. | +| 5.13-AC09 — slow/unavailable gateway, partial channel failure, timeout после отправки либо restart dispatcher | INT | Inject timeout before/after receipt, partial/permanent failure and restart. Assert bounded queue/attempts/expiry, typed uncertainty and local accounting without recursive alerts; product probes stay responsive. Gateway ACK alone never proves receipt. | +| 5.13-AC10 — real-stack notification suite и canary secrets | INT | Pinned gateway/local receiver verify routing/lifecycle/recovery. Reject unauthorized ingress/arbitrary targets/attachments; scan captured sinks for canaries and traffic for opt-in. Bind evaluator/adapter/gateway/config versions to sanitized evidence. | + +Policy seams: evaluator owns grouping/silence/repeat; common dispatcher owns retry/queue/expiry/redaction/accounting; adapter owns one bounded transport attempt and response translation. Inject failure at each seam and assert no multiplying retries. The receiver ledger must not derive its receipt count from the dispatcher's success counter. + +### P2 / P3 + +No additional mandatory scope. Optional exploratory/cosmetic variants need owner and justification, not an endless review queue. Notification checks above are mandatory P0 refinements, not P2/P3 work. + +Levels: UNIT pure contract/model; INT real filesystem/database/runtime boundary; API actual handler/protocol; E2E critical browser journey; SYS isolated full-stack qualification; MANUAL named human protocol. Use unit cases for algorithms, real PG for transaction/fencing, wire fixtures for protocol, browser only for user-visible interaction. Intentional defense-in-depth checks different failure surfaces, not identical duplicated assertions. + +## Execution Strategy + +Run all functional tests in PRs when they fit the target 15-minute feedback window; defer only expensive infrastructure/duration, not inconvenient failures. Current Playwright is Chromium, one worker: parallelization is a future isolation-dependent optimization, not a current claim. + +- **PR:** changed functional/negative regressions and boundary suites; applicable Rust/tooling/config and UI gates. +- **Nightly:** bounded fault/contention, repeated isolation and resource trend tests after the required seams exist. +- **Weekly:** calibrated production-size performance, fresh-host/offline/recovery and manual qualification as applicable. +- **Epic / RC acceptance:** every mandatory AC and quantitative obligation must have exact-candidate evidence, even if its normal execution tier is weekly. Epic 8 owns the immutable long-duration release windows. + +Nightly/weekly scheduling is a proposed execution model; the current Gitea pipeline has PR/push and release jobs, not those schedules. This planning task does not create them. `just verify` does not replace Playwright, deployment/image or qualification jobs. + +## Resource Estimates + +Incremental QA test/evidence effort with working production seams and reusable fixtures, excluding feature implementation, provisioning lead time and unaccelerated duration. Low-confidence planning ranges, not token budgets or compulsory numbers of new tests; reassess at each story ATDD after deduplication. + +| Priority | Estimated effort | +|---|---| +| P0 | 60–120 hours | +| P1 | 24–48 hours | +| Optional P2 | 0–8 hours | +| Optional P3 | 0–4 hours | +| Total envelope | 84–180 hours, approximately 3–5 contributor-weeks | + +If a measurement environment is missing, report the prerequisite; do not run large workloads opportunistically inside a story session. + +The earlier estimate envelope has not been independently recalibrated for the gateway decision. It is historical low-confidence sizing until 5.10/5.13 ATDD maps existing fixtures and the selected adapter, not a promise that all contract cases fit that budget. + +## Exit Criteria and Quality Gates + +- P0 pass 100%; P1 ≥95% is an interim development signal only, **100% of mandatory P1 and manual ACs must pass for acceptance**. +- Every owning-story AC has test/protocol plus bound execution evidence; no mandatory skipped/flaky/blocked/not-run item becomes pass. +- No unresolved Critical/High defect; high-risk mitigation verified on the owning scenario before release. Mandatory Habr conditions have no waiver. +- Coverage targets remain system planning goals (80% workspace /90% new critical code where measured); **no coverage report currently proves them**. Scenario counts do not substitute for coverage instrumentation. +- NFR evidence names revision, config/topology, tool/data versions, command, seed, timestamps, raw sanitized output digest and result. +- Story completion follows its spec, not all remaining epic/system gaps; no automatic reopening of done stories. + +## Mitigation Plans + +Each high-risk owner in the matrix: (1) implement/reuse the production-safe seam; (2) run its A/B and detailed AC cases with controlled failures; (3) bind the output to the candidate; (4) re-evaluate residual risk. Status is planned or source-partial, never verified solely by this document. Required completion time is the owning story/epic milestone in the risk table. No generic follow-up review loop is created. + +## Assumptions and Dependencies + +1.5/1.6 foundations; each new subsystem owns its metric/trace additions. 5.4 receiver port → 5.5 spool → 5.6 capacity. 5.7/5.8 metric semantics → 5.9 Prometheus → 5.10 gateway and 5.11 Grafana → 5.12 SLO → 5.13 alert delivery/evidence. Task/Load views must not be called complete before respective epics provide data; actual Load Run data acceptance belongs to 6.6. + +5.10 freezes common message/port, route bindings and provider contract before 5.13 verifies delivery lifecycle; reuse that suite rather than recreate it. Pending numeric limits and evaluator/gateway compatibility block affected assertions until frozen, not permission to add infrastructure monitoring, another production provider or a new UI. + +Accountable roles are responsibilities, not claims of staffed teams. Reference hardware, operator credentials and manual reviewers must be assigned before relevant qualification. Use disposable fixtures while waiting; lack of resources blocks the affected evidence, not permission to mutate a live deployment. + +## Interworking and Regression + +Affected components and reusable suites are named in Existing Coverage. Preserve existing REST→MCP, auth/credential/approval, config/migration, correlation and Community-boundary behavior whenever those shared contracts change. Frontend failures need actual browser regression; registry races need real-PG assertions, not UI mocks. + +## ATDD Handoff + +For the selected not-yet-implemented story only, load this plan and the exact approved spec; freeze its finite AC-to-test checklist before implementation. Prefer existing Rust/PG/Playwright patterns, add only uncovered acceptance scenarios and reproduce RED for missing behavior without artificial failure. Existing correct behavior may already be GREEN: record it honestly. Resume matching incomplete ATDD, reuse completed matching checklists and update only changed ACs. Do not invoke whole-epic automation on each review. + +Automatic pre-implementation ATDD requires the project build-auto handoff override; the stock bmad-loop0.11.1 TEA ATDD injection is post-dev and is not that sequence. Loop configuration is separate from completion of this plan. The design workflow itself does not run ATDD or product implementation. + +## References and Validation + +- Epic/AC source: `_bmad-output/planning-artifacts/epics.md`, Epic 5. +- System contract: [architecture](test-design-architecture.md), [QA inventory and execution](test-design-qa.md). +- Normative PRD and architecture spine: frontmatter inputDocuments. +- TEA knowledge: risk-governance, probability-impact, test-levels-framework, test-priorities-matrix, nfr-criteria. +- Utility integration: Playwright/Pact flags are true but packages absent. No imports, framework migration or Pact service are generated. Browser CLI unavailable; source-based design only. +- Validation: story IDs/requirements/AC counts, risk arithmetic/linkage and document paths checked; no final test/NFR PASS issued. Approval is planning-level user direction, not fabricated reviewer signatures. diff --git a/_bmad-output/test-artifacts/test-design-epic-6.md b/_bmad-output/test-artifacts/test-design-epic-6.md new file mode 100644 index 0000000..8b445ae --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-epic-6.md @@ -0,0 +1,175 @@ +--- +runScope: 'epic-level' +runKey: 'epic-6' +workflowStatus: 'completed' +workflowType: 'testarch-test-design' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +lastSaved: '2026-09-13' +auditedRevision: '083974c27f3a21a15807dd248bb6bc4fe04a5cd8' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' +--- + +# Test Design: Epic 6 — Встроенная проверка производительности + +**Date:** 2026-09-13 +**Author:** Bsodfather / BMad TEA +**Status:** Updated planning baseline; qualification not evaluated. + +## Executive Summary + +Scope: FR-36–FR-40, 6 stories, system scenario families CP-22..24. This plan refines the current system design; it neither changes approved product scope nor marks stories complete. + +3 inherent risks, 3 high (score ≥6). Coverage seeds: 8 P0 and 4 P1 independently assertable scenarios. Counts describe the two seeds per story below, not implemented tests, coverage percentages or the eventual parameterized case count. Every source AC remains mandatory. + +## Existing Coverage and Evidence + +Source inventory at main `083974c`: Runtime metric/overhead patterns in `crates/crank-runtime/tests/product_metrics.rs` and `crates/crank-metrics/tests/overhead.rs`; real MCP fixture in `apps/ui/scripts/playwright-http-fixture.js` and `apps/ui/tests/e2e/onboarding.spec.js`. + +No Load Scenario, runner, safety-plan or report feature suites found. Existing microbenchmarks/local budget checks do not prove generated RPS, control-plane isolation or product capacity. DAU preview is a load model, not the measured unique-Agent DAU rollup of 5.8. + +Source presence ≠ execution ≠ requirement coverage ≠ qualification. No product test, deployment or load execution was performed for this plan. Reuse source tests only after matching their oracle to the current AC and recording a run on the candidate under test. + +## Not in Scope + +| Item | Reason | Mitigation | +|---|---|---| +| Unrelated future-epic implementation and whole-product refactoring | This is Epic 6 test planning | Keep explicit prerequisites below; do not invent additional story acceptance | +| SSO/RBAC enterprise features, non-REST adapters, HA/rolling deployment | Outside approved Community scope | Preserve Community boundary checks | +| Declaring current production readiness from source inventory | No bound qualification run | Require real evidence before gate | +| Product-wide 72-hour soak / 30-day burn-in | Owned by Epic 8 | Component fault/performance obligations in this epic remain required | + +## Risk Assessment + +Score = probability × impact on a 1–3 scale. Score ≥6 needs verified mitigation; 9 is an unresolved critical release risk, not a command to implement every mitigation immediately. Categories: SEC security, DATA integrity, OPS operations, PERF performance, BUS user behavior, TECH architecture/testing. + +| Risk ID | Category | Failure | P | I | Score | System risk | Mitigation / accountable role / deadline | +|---|---|---|---:|---:|---:|---|---| +| E6-R1 | SEC | Forged/stale load plan dispatches damaging writes | 3 | 3 | 9 | R-010 | Signed fingerprint + replay/SSRF/write negatives; Security, 6.3 | +| E6-R2 | OPS | Runner duplicates generation or cannot stop | 2 | 3 | 6 | R-010 | Owner fencing + reserved path + independent kill; Runner, 6.4–6.5 | +| E6-R3 | PERF | Generator bottleneck/aggregation reports false SUT performance | 3 | 3 | 9 | R-006 | External calibration + independent counts; Performance, 6.6 | + +Medium risks: shared R-012 (4), deterministic test isolation; QA owns continuous monitoring. No additional low risk is invented just to fill a template. Residual risk is unmeasured until evidence exists. + +## NFR Planning + +Hard non-overridable ceilings1000RPS/512VU/2h/10,000,000iterations (6.3). Qualification100RPS30m +250RPS5m, per-minute success≥99.95% and saturation rejects≤0.1%; platform overheadp95≤50ms/p99≤150ms with10ms upstream/cache off. Arrival tolerance and stop/drain policy must be frozen by owning story, never chosen silently by tests. + +| Category | Scenario linkage | Planned validation / evidence | +|---|---|---| +| Security/privacy | SEC risks and B scenarios below | Scope/abuse/canary tests, bounded sanitized logs and network/scan report | +| Reliability/data integrity | DATA/OPS risks and fault scenarios | Real authority/state assertions, fault schedule and reconciled counters/digests | +| Performance/scalability | Numeric epic obligations above | Calibrated raw latency/resource samples, achieved load and immutable config/topology fingerprint | +| Maintainability/compatibility | Every changed component | Existing `just verify`/UI gates as applicable, schema/contract diffs and traceable regression reports | + +Unknowns: exact execution hardware and fresh qualification artifacts are not available from this audit. Where the owning story requires a new tolerance, limit or version selection, freeze it in its approved contract before writing a numeric assertion; never replace the PRD threshold with a guessed easier value. Full NFR verdict belongs to `bmad-testarch-nfr` after execution. + +## Entry Criteria + +- Approved owning story/spec and prerequisites are available in the same worktree. +- ATDD loads the actual ACs from `epics.md` / selected spec and the system QA design. +- Existing tests and baseline failures are inspected before adding tests; no duplicate test suite solely for new IDs. +- Counted controllable upstream; signed-plan negative fixtures with exact change fingerprints; isolated runner CPU/memory/network and reserved control path; host kill socket in disposable sandbox; external calibrated generator/counters to separate harness saturation from SUT saturation. +- Missing fixture, service or approval is reported as blocked/not-run, not silently skipped. + +## Test Coverage Plan + +P0/P1/P2/P3 indicate priority, **not execution timing**. Each table row has two separate scenario seeds: `--A` and `...-B`. Split a seed when independent assertions require different fixtures. Reuse an existing equivalent test rather than duplicating it; ATDD records exact test name/path and AC mapping. + +The AC-count column inventories all `Given` groups under that source story, not a claim that two tests exhaust those groups. The last two former 6.1 full-workflow acceptance groups now belong to 6.6; 6.1 retains scenario definition only. Story 6.4 adds the approved correlation acceptance group. ATDD must map each group (story + ordinal + quoted acceptance text) to existing test, new test, or explicit not-run prerequisite before implementation. The approved spec controls finer-grained cases. + +### P0 — Critical + +Security, irreversible data integrity and false acceptance have no safe user workaround. + +| Story / scenario IDs | Requirements | AC groups | Primary level | Risk | A: expected behavior | B: rejection / fault | +|---|---|---:|---|---|---|---| +| 6.3 / 6.3-INT-A,B | FR-38 | 6 | INT | E6-R1 | Signed short-lived exact LoadAuthorizationPlan covers scope, resolved targets and safety limits | Forgery/expiry/replay/rebinding/revocation/writes without sandbox-cleanup fail before dispatch | +| 6.4 / 6.4-INT-A,B | FR-38 | 7 | INT | E6-R1/E6-R2 | Idempotent durable Start grants one isolated generator owner using only public MCP and correlates accepted Run, generator and report identities | Crash/restart/missing heartbeat or overloaded API cannot defeat ceilings and independent permission-restricted emergency kill; per-process spool is used only where the owning telemetry contract applies, not introduced as a blanket runner requirement | +| 6.5 / 6.5-E2E-A,B | FR-39 | 6 | E2E | E6-R2 | Fresh bounded live stats and idempotent Stop operate through reserved control capacity | Out-of-order/disconnect/terminal update cannot claim false pass; emergency stop reconciles after recovery | +| 6.6 / 6.6-SYS-A,B | FR-40 | 9 | SYS | E6-R3 | Immutable digest-bound report independently accounts achieved load, percentiles and comparable fingerprints, and owns the transferred full-workflow acceptance from 6.1 | Interrupted/changed/incompatible runs cannot pass/compare silently; malformed responses stay valid redacted JSON | + +### P1 — High + +Core user journeys and complex integrations; limited workaround, not relaxed acceptance. + +| Story / scenario IDs | Requirements | AC groups | Primary level | Risk | A: expected behavior | B: rejection / fault | +|---|---|---:|---|---|---|---| +| 6.1 / 6.1-API-A,B | FR-36 | 6 | API | E6-R1 | Scenario versions pin Tool/Agent/schema/generator refs and weighted mix | Draft/foreign/unsafe write/invalid weights or oversized samples rejected; editing never changes old Run semantics; end-to-end navigation/fingerprint acceptance is owned by 6.6 | +| 6.2 / 6.2-UNIT-A,B | FR-37 | 5 | UNIT | E6-R3 | Explicit DAU assumptions + seed deterministically produce matching backend/UI arrival curve | Zero/overflow/NaN/short-window/think-time conflicts rejected; peak capacity breach blocks Start | + +### P2 / P3 + +No additional mandatory scope. Optional focused exploratory/cosmetic variants may be recorded later with owner and justification; they do not become an endless implementation/review queue. + +Levels: UNIT pure contract/model; INT real filesystem/database/runtime boundary; API actual handler/protocol; E2E critical browser journey; SYS isolated full-stack qualification; MANUAL named human protocol. Use unit cases for algorithms, real PG for transaction/fencing, wire fixtures for protocol, browser only for user-visible interaction. Intentional defense-in-depth checks different failure surfaces, not identical duplicated assertions. + +## Execution Strategy + +Run all functional tests in PRs when they fit the target 15-minute feedback window; defer only expensive infrastructure/duration, not inconvenient failures. Current Playwright is Chromium, one worker: parallelization is a future isolation-dependent optimization, not a current claim. + +- **PR:** changed functional/negative regressions and boundary suites; applicable Rust/tooling/config and UI gates. +- **Nightly:** bounded fault/contention, repeated isolation and resource trend tests after the required seams exist. +- **Weekly:** calibrated production-size performance, fresh-host/offline/recovery and manual qualification as applicable. +- **Epic / RC acceptance:** every mandatory AC and quantitative obligation must have exact-candidate evidence, even if its normal execution tier is weekly. Epic 8 owns the immutable long-duration release windows. + +Nightly/weekly scheduling is a proposed execution model; the current Gitea pipeline has PR/push and release jobs, not those schedules. This planning task does not create them. `just verify` does not replace Playwright, deployment/image or qualification jobs. + +## Resource Estimates + +Incremental QA test/evidence effort with working production seams and reusable fixtures, excluding feature implementation, provisioning lead time and unaccelerated duration. Low-confidence planning ranges, not token budgets or compulsory numbers of new tests; reassess at each story ATDD after deduplication. + +| Priority | Estimated effort | +|---|---| +| P0 | 40–80 hours | +| P1 | 24–48 hours | +| Optional P2 | 0–8 hours | +| Optional P3 | 0–4 hours | +| Total envelope | 64–140 hours, approximately 2–4 contributor-weeks | + +If a measurement environment is missing, report the prerequisite; do not run large workloads opportunistically inside a story session. + +## Exit Criteria and Quality Gates + +- P0 pass 100%; P1 ≥95% is an interim development signal only, **100% of mandatory P1 and manual ACs must pass for acceptance**. +- Every owning-story AC has test/protocol plus bound execution evidence; no mandatory skipped/flaky/blocked/not-run item becomes pass. +- No unresolved Critical/High defect; high-risk mitigation verified on the owning scenario before release. Mandatory Habr conditions have no waiver. +- Coverage targets remain system planning goals (80% workspace /90% new critical code where measured); **no coverage report currently proves them**. Scenario counts do not substitute for coverage instrumentation. +- NFR evidence names revision, config/topology, tool/data versions, command, seed, timestamps, raw sanitized output digest and result. +- Story completion follows its spec, not all remaining epic/system gaps; no automatic reopening of done stories. + +## Mitigation Plans + +Each high-risk owner in the matrix: (1) implement/reuse the production-safe seam; (2) run its A/B and detailed AC cases with controlled failures; (3) bind the output to the candidate; (4) re-evaluate residual risk. Status is planned or source-partial, never verified solely by this document. Required completion time is the owning story/epic milestone in the risk table. No generic follow-up review loop is created. + +## Assumptions and Dependencies + +Published Tools + shared execution safety, metrics/artifacts and observable outcomes before live validation. 6.1 → 6.2 → 6.3 → 6.4 → 6.5 → 6.6. No arbitrary external targets or production writes authorized by this plan. + +Accountable roles are responsibilities, not claims of staffed teams. Reference hardware, operator credentials and manual reviewers must be assigned before relevant qualification. Use disposable fixtures while waiting; lack of resources blocks the affected evidence, not permission to mutate a live deployment. + +## Interworking and Regression + +Affected components and reusable suites are named in Existing Coverage. Preserve existing REST→MCP, auth/credential/approval, config/migration, correlation and Community-boundary behavior whenever those shared contracts change. Frontend failures need actual browser regression; registry races need real-PG assertions, not UI mocks. + +## ATDD Handoff + +For the selected not-yet-implemented story only, load this plan and the exact approved spec; freeze its finite AC-to-test checklist before implementation. Prefer existing Rust/PG/Playwright patterns, add only uncovered acceptance scenarios and reproduce RED for missing behavior without artificial failure. Existing correct behavior may already be GREEN: record it honestly. Resume matching incomplete ATDD, reuse completed matching checklists and update only changed ACs. Do not invoke whole-epic automation on each review. + +Automatic pre-implementation ATDD requires the project build-auto handoff override; the stock bmad-loop0.11.1 TEA ATDD injection is post-dev and is not that sequence. Loop configuration is separate from completion of this plan. The design workflow itself does not run ATDD or product implementation. + +## References and Validation + +- Epic/AC source: `_bmad-output/planning-artifacts/epics.md`, Epic 6. +- System contract: [architecture](test-design-architecture.md), [QA inventory and execution](test-design-qa.md). +- Normative PRD and architecture spine: frontmatter inputDocuments. +- TEA knowledge: risk-governance, probability-impact, test-levels-framework, test-priorities-matrix, nfr-criteria. +- Utility integration: Playwright/Pact flags are true but packages absent. No imports, framework migration or Pact service are generated. Browser CLI unavailable; source-based design only. +- Validation: story IDs/requirements/AC counts, risk arithmetic/linkage and document paths checked; no final test/NFR PASS issued. Approval is planning-level user direction, not fabricated reviewer signatures. diff --git a/_bmad-output/test-artifacts/test-design-epic-7.md b/_bmad-output/test-artifacts/test-design-epic-7.md new file mode 100644 index 0000000..9b0d5c4 --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-epic-7.md @@ -0,0 +1,178 @@ +--- +runScope: 'epic-level' +runKey: 'epic-7' +workflowStatus: 'completed' +workflowType: 'testarch-test-design' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +lastSaved: '2026-09-13' +auditedRevision: '083974c27f3a21a15807dd248bb6bc4fe04a5cd8' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' +--- + +# Test Design: Epic 7 — Автономное production-развёртывание и восстановление + +**Date:** 2026-09-13 +**Author:** Bsodfather / BMad TEA +**Status:** Updated planning baseline; qualification not evaluated. + +## Executive Summary + +Scope: FR-41–FR-45, 9 stories, system scenario families CP-25..27. This plan refines the current system design; it neither changes approved product scope nor marks stories complete. + +3 inherent risks, 3 high (score ≥6). Coverage seeds: 16 P0 and 2 P1 independently assertable scenarios. Counts describe the two seeds per story below, not implemented tests, coverage percentages or the eventual parameterized case count. Every source AC remains mandatory. + +## Existing Coverage and Evidence + +Source inventory at main `083974c`: `crates/crank-config/tests/{contract,generation,redaction}.rs`; `crates/crank-registry/tests/integration/migrations.rs` and `migrations/`; `apps/admin-api/tests/migration_command.rs`; `apps/admin-api/tests/config_startup.rs`; `scripts/restore-community.sh`; `scripts/authenticated-product-smoke.py`; `.gitea/workflows/ci.yml`. + +Config/migration/auth foundations and Compose authenticated smoke exist. Restore script presence is not three qualified PITR restores. Complete offline signed bundle, role isolation with future worker/runner and full N/N-1 online/offline matrix need evidence. Prior deployment failures require regression fixtures for legacy fingerprint, missing core, external PG topology and failed migrate diagnostics, not permission to reset databases. + +Source presence ≠ execution ≠ requirement coverage ≠ qualification. No product test, deployment or load execution was performed for this plan. Reuse source tests only after matching their oracle to the current AC and recording a run on the candidate under test. + +## Not in Scope + +| Item | Reason | Mitigation | +|---|---|---| +| Unrelated future-epic implementation and whole-product refactoring | This is Epic 7 test planning | Keep explicit prerequisites below; do not invent additional story acceptance | +| SSO/RBAC enterprise features, non-REST adapters, HA/rolling deployment | Outside approved Community scope | Preserve Community boundary checks | +| Declaring current production readiness from source inventory | No bound qualification run | Require real evidence before gate | +| Product-wide 72-hour soak / 30-day burn-in | Owned by Epic 8 | Component fault/performance obligations in this epic remain required | + +## Risk Assessment + +Score = probability × impact on a 1–3 scale. Score ≥6 needs verified mitigation; 9 is an unresolved critical release risk, not a command to implement every mitigation immediately. Categories: SEC security, DATA integrity, OPS operations, PERF performance, BUS user behavior, TECH architecture/testing. + +| Risk ID | Category | Failure | P | I | Score | System risk | Mitigation / accountable role / deadline | +|---|---|---|---:|---:|---:|---|---| +| E7-R1 | DATA | Schema/artifact/key mismatch destroys recovery | 2 | 3 | 6 | R-008 | Manifest + N/N-1 + three real restores; SRE, 7.8–7.9 | +| E7-R2 | SEC | Unsafe defaults/proxy/privileges expose installation | 2 | 3 | 6 | R-007 | Fresh-host negative exposure tests; Security, 7.4/7.6 | +| E7-R3 | SEC | Offline bundle untrusted or phones home | 2 | 3 | 6 | R-014 | Offline signature/tamper/egress tests; Release, 7.5 | + +Medium risks: shared R-012 (4), deterministic test isolation; QA owns continuous monitoring. No additional low risk is invented just to fill a template. Residual risk is unmeasured until evidence exists. + +## NFR Planning + +Each of3independent restores RPO≤5m/RTO≤30m with real MCP probe; drain≤30s and eligible Task recovery≤60s. Production sizing retains≥30% measured headroom. Zero known Critical/High, zero unapproved egress. Trust material/reference-host allocation and exact image digests are execution prerequisites, never generated secrets in docs. + +| Category | Scenario linkage | Planned validation / evidence | +|---|---|---| +| Security/privacy | SEC risks and B scenarios below | Scope/abuse/canary tests, bounded sanitized logs and network/scan report | +| Reliability/data integrity | DATA/OPS risks and fault scenarios | Real authority/state assertions, fault schedule and reconciled counters/digests | +| Performance/scalability | Numeric epic obligations above | Calibrated raw latency/resource samples, achieved load and immutable config/topology fingerprint | +| Maintainability/compatibility | Every changed component | Existing `just verify`/UI gates as applicable, schema/contract diffs and traceable regression reports | + +Unknowns: exact execution hardware and fresh qualification artifacts are not available from this audit. Where the owning story requires a new tolerance, limit or version selection, freeze it in its approved contract before writing a numeric assertion; never replace the PRD threshold with a guessed easier value. Full NFR verdict belongs to `bmad-testarch-nfr` after execution. + +## Entry Criteria + +- Approved owning story/spec and prerequisites are available in the same worktree. +- ATDD loads the actual ACs from `epics.md` / selected spec and the system QA design. +- Existing tests and baseline failures are inspected before adding tests; no duplicate test suite solely for new IDs. +- Disposable fresh host/network namespaces; PG16 current/N-1/legacy snapshots; checksummed artifacts/WAL plus out-of-band test keys; fault checkpoints; offline registry-less image archive; default-deny egress capture; fresh scanner DB pinned in report. +- Missing fixture, service or approval is reported as blocked/not-run, not silently skipped. + +## Test Coverage Plan + +P0/P1/P2/P3 indicate priority, **not execution timing**. Each table row has two separate scenario seeds: `--A` and `...-B`. Split a seed when independent assertions require different fixtures. Reuse an existing equivalent test rather than duplicating it; ATDD records exact test name/path and AC mapping. + +The AC-count column inventories all `Given` groups under that source story, not a claim that two tests exhaust those groups. The former offline-upgrade acceptance group moves from 7.5 to 7.9: 7.5 remains bundle creation/install trust coverage, while 7.9 owns upgrade/rollback continuity. ATDD must map each group (story + ordinal + quoted acceptance text) to existing test, new test, or explicit not-run prerequisite before implementation. The approved spec controls finer-grained cases. + +### P0 — Critical + +Security, irreversible data integrity and false acceptance have no safe user workaround. + +| Story / scenario IDs | Requirements | AC groups | Primary level | Risk | A: expected behavior | B: rejection / fault | +|---|---|---:|---|---|---|---| +| 7.1 / 7.1-UNIT-A,B | FR-45 | 6 | UNIT | E7-R2 | Typed schema generates matching examples/Compose/docs/redacted effective config | Unknown/unused/divergent/unsafe cross-field and conflicting alias values fail safely | +| 7.2 / 7.2-INT-A,B | FR-43 | 6 | INT | E7-R1 | Fresh/current/N-1/legacy PG16 states migrate idempotently through canonical authority | Checksum/future/partial drift and concurrent preflight reject before mutation; large backfill resumable | +| 7.4 / 7.4-API-A,B | FR-41 | 6 | API | E7-R2 | Explicit TLS/origin/host/trusted proxy and separate Admin/MCP/metrics identities work | Spoofed forwarded headers, host/CORS/CSRF/cookie downgrade and exposed recovery denied | +| 7.5 / 7.5-SYS-A,B | FR-42 | 5 | SYS | E7-R3 | Signed digest-pinned complete bundle installs with default-deny egress | Extra/missing/tampered/unpinned artifacts or invalid trust fail offline; no CDN/registry/phone-home | +| 7.6 / 7.6-SYS-A,B | FR-44 | 7 | SYS | E7-R2/E7-R3 | Images enforce role-scoped non-root/caps/read-only/resource/mount policy and≤30s drain | Runner cannot access DB/secrets; OOM/disk pressure isolated; changed hardened image invalidates and rebuilds bundle | +| 7.7 / 7.7-INT-A,B | FR-43 | 6 | INT | E7-R1 | Online consistent WAL/artifact/config cut produces immutable complete BackupManifest | Interrupted backup/missing WAL/wrong epoch/tampered bytes never become usable; retention keeps pinned dependencies | +| 7.8 / 7.8-SYS-A,B | FR-43 | 6 | SYS | E7-R1 | Three independent fresh-host restores prove RPO/RTO and real authenticated MCP plus key recovery | Mismatch blocks mutation; ciphertext/manifest errors explicit; crash during re-encryption preserves decryptability | +| 7.9 / 7.9-SYS-A,B | FR-43 | 8 | SYS | E7-R1 | N-1→N preflight/backup/drain/migrate/probe preserves pinned state online and through the transferred offline-upgrade path | Fault before reversible boundary rolls back safely; irreversible boundary requires explicit manifest restore | + +### P1 — High + +Core user journeys and complex integrations; limited workaround, not relaxed acceptance. + +| Story / scenario IDs | Requirements | AC groups | Primary level | Risk | A: expected behavior | B: rejection / fault | +|---|---|---:|---|---|---|---| +| 7.3 / 7.3-SYS-A,B | FR-41 | 6 | SYS | E7-R2 | Fresh minimal/production profile starts, persists, restarts and makes real MCP call; PG-only correct | Missing secrets/unsafe exposure fail readiness; optional backend outage cannot pretend safety store is optional | + +### P2 / P3 + +No additional mandatory scope. Optional focused exploratory/cosmetic variants may be recorded later with owner and justification; they do not become an endless implementation/review queue. + +Levels: UNIT pure contract/model; INT real filesystem/database/runtime boundary; API actual handler/protocol; E2E critical browser journey; SYS isolated full-stack qualification; MANUAL named human protocol. Use unit cases for algorithms, real PG for transaction/fencing, wire fixtures for protocol, browser only for user-visible interaction. Intentional defense-in-depth checks different failure surfaces, not identical duplicated assertions. + +## Execution Strategy + +Run all functional tests in PRs when they fit the target 15-minute feedback window; defer only expensive infrastructure/duration, not inconvenient failures. Current Playwright is Chromium, one worker: parallelization is a future isolation-dependent optimization, not a current claim. + +- **PR:** changed functional/negative regressions and boundary suites; applicable Rust/tooling/config and UI gates. +- **Nightly:** bounded fault/contention, repeated isolation and resource trend tests after the required seams exist. +- **Weekly:** calibrated production-size performance, fresh-host/offline/recovery and manual qualification as applicable. +- **Epic / RC acceptance:** every mandatory AC and quantitative obligation must have exact-candidate evidence, even if its normal execution tier is weekly. Epic 8 owns the immutable long-duration release windows. + +Nightly/weekly scheduling is a proposed execution model; the current Gitea pipeline has PR/push and release jobs, not those schedules. This planning task does not create them. `just verify` does not replace Playwright, deployment/image or qualification jobs. + +## Resource Estimates + +Incremental QA test/evidence effort with working production seams and reusable fixtures, excluding feature implementation, provisioning lead time and unaccelerated duration. Low-confidence planning ranges, not token budgets or compulsory numbers of new tests; reassess at each story ATDD after deduplication. + +| Priority | Estimated effort | +|---|---| +| P0 | 48–96 hours | +| P1 | 16–32 hours | +| Optional P2 | 0–8 hours | +| Optional P3 | 0–4 hours | +| Total envelope | 64–140 hours, approximately 2–4 contributor-weeks | + +If a measurement environment is missing, report the prerequisite; do not run large workloads opportunistically inside a story session. + +## Exit Criteria and Quality Gates + +- P0 pass 100%; P1 ≥95% is an interim development signal only, **100% of mandatory P1 and manual ACs must pass for acceptance**. +- Every owning-story AC has test/protocol plus bound execution evidence; no mandatory skipped/flaky/blocked/not-run item becomes pass. +- No unresolved Critical/High defect; high-risk mitigation verified on the owning scenario before release. Mandatory Habr conditions have no waiver. +- Coverage targets remain system planning goals (80% workspace /90% new critical code where measured); **no coverage report currently proves them**. Scenario counts do not substitute for coverage instrumentation. +- NFR evidence names revision, config/topology, tool/data versions, command, seed, timestamps, raw sanitized output digest and result. +- Story completion follows its spec, not all remaining epic/system gaps; no automatic reopening of done stories. + +## Mitigation Plans + +Each high-risk owner in the matrix: (1) implement/reuse the production-safe seam; (2) run its A/B and detailed AC cases with controlled failures; (3) bind the output to the candidate; (4) re-evaluate residual risk. Status is planned or source-partial, never verified solely by this document. Required completion time is the owning story/epic milestone in the risk table. No generic follow-up review loop is created. + +## Assumptions and Dependencies + +All shipped processes/config/metrics contracts from preceding epics. 7.1/7.2 preflight → profiles/exposure/bundle/hardening; 7.7 complete manifest →7.8 restore→7.9 upgrade. 7.6 image changes require7.5 bundle requalification. + +Accountable roles are responsibilities, not claims of staffed teams. Reference hardware, operator credentials and manual reviewers must be assigned before relevant qualification. Use disposable fixtures while waiting; lack of resources blocks the affected evidence, not permission to mutate a live deployment. + +## Interworking and Regression + +Affected components and reusable suites are named in Existing Coverage. Preserve existing REST→MCP, auth/credential/approval, config/migration, correlation and Community-boundary behavior whenever those shared contracts change. Frontend failures need actual browser regression; registry races need real-PG assertions, not UI mocks. + +## ATDD Handoff + +For the selected not-yet-implemented story only, load this plan and the exact approved spec; freeze its finite AC-to-test checklist before implementation. Prefer existing Rust/PG/Playwright patterns, add only uncovered acceptance scenarios and reproduce RED for missing behavior without artificial failure. Existing correct behavior may already be GREEN: record it honestly. Resume matching incomplete ATDD, reuse completed matching checklists and update only changed ACs. Do not invoke whole-epic automation on each review. + +Automatic pre-implementation ATDD requires the project build-auto handoff override; the stock bmad-loop0.11.1 TEA ATDD injection is post-dev and is not that sequence. Loop configuration is separate from completion of this plan. The design workflow itself does not run ATDD or product implementation. + +## References and Validation + +- Epic/AC source: `_bmad-output/planning-artifacts/epics.md`, Epic 7. +- System contract: [architecture](test-design-architecture.md), [QA inventory and execution](test-design-qa.md). +- Normative PRD and architecture spine: frontmatter inputDocuments. +- TEA knowledge: risk-governance, probability-impact, test-levels-framework, test-priorities-matrix, nfr-criteria. +- Utility integration: Playwright/Pact flags are true but packages absent. No imports, framework migration or Pact service are generated. Browser CLI unavailable; source-based design only. +- Validation: story IDs/requirements/AC counts, risk arithmetic/linkage and document paths checked; no final test/NFR PASS issued. Approval is planning-level user direction, not fabricated reviewer signatures. diff --git a/_bmad-output/test-artifacts/test-design-epic-8.md b/_bmad-output/test-artifacts/test-design-epic-8.md new file mode 100644 index 0000000..4964ba7 --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-epic-8.md @@ -0,0 +1,178 @@ +--- +runScope: 'epic-level' +runKey: 'epic-8' +workflowStatus: 'completed' +workflowType: 'testarch-test-design' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +lastSaved: '2026-09-13' +auditedRevision: '083974c27f3a21a15807dd248bb6bc4fe04a5cd8' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' +--- + +# Test Design: Epic 8 — Доказанный production-релиз + +**Date:** 2026-09-13 +**Author:** Bsodfather / BMad TEA +**Status:** Updated planning baseline; qualification not evaluated. + +## Executive Summary + +Scope: FR-46–FR-54, 10 stories, system scenario families CP-28..34. This plan refines the current system design; it neither changes approved product scope nor marks stories complete. + +3 inherent risks, 3 high (score ≥6). Coverage seeds: 16 P0 and 4 P1 independently assertable scenarios. Counts describe the two seeds per story below, not implemented tests, coverage percentages or the eventual parameterized case count. Every source AC remains mandatory. + +## Existing Coverage and Evidence + +Source inventory at main `083974c`: `docs/capability-inventory.json`; `docs/capability-baseline/results.json`; `scripts/collect-capability-baseline.py`; `scripts/validate-capability-run.py`; `tests/unit/`; `.gitea/workflows/{ci,release}.yml`; `scripts/scan-images.sh`; `docs/manual-regression-checklist.md`. + +Existing inventory/collector and CI scans are foundations, not full signed RC evidence. Historical baseline2026.08.24.1 uses revision767428, not current main. Chromium-only current suite is not Firefox/WebKit×RU/EN qualification. No measured coverage report,72h/30day accepted run or3PITR restores was produced by this planning task. + +Source presence ≠ execution ≠ requirement coverage ≠ qualification. No product test, deployment or load execution was performed for this plan. Reuse source tests only after matching their oracle to the current AC and recording a run on the candidate under test. + +## Not in Scope + +| Item | Reason | Mitigation | +|---|---|---| +| Unrelated future-epic implementation and whole-product refactoring | This is Epic 8 test planning | Keep explicit prerequisites below; do not invent additional story acceptance | +| SSO/RBAC enterprise features, non-REST adapters, HA/rolling deployment | Outside approved Community scope | Preserve Community boundary checks | +| Declaring current production readiness from source inventory | No bound qualification run | Require real evidence before gate | + +## Risk Assessment + +Score = probability × impact on a 1–3 scale. Score ≥6 needs verified mitigation; 9 is an unresolved critical release risk, not a command to implement every mitigation immediately. Categories: SEC security, DATA integrity, OPS operations, PERF performance, BUS user behavior, TECH architecture/testing. + +| Risk ID | Category | Failure | P | I | Score | System risk | Mitigation / accountable role / deadline | +|---|---|---|---:|---:|---:|---|---| +| E8-R1 | OPS | Mixed/stale/forged evidence produces PUBLIC_READY | 3 | 3 | 9 | R-013 | Offline signed verifier with negative fixture per gate input; Release, 8.1/8.10 | +| E8-R2 | OPS | Leaks/recovery failures appear only after sustained traffic | 2 | 3 | 6 | R-015 | 72h + 30 calendar days fixed RC; SRE, 8.6/8.9 | +| E8-R3 | SEC | Incomplete matrix/security/manual pass hides unsafe claims | 2 | 3 | 6 | R-014 | Full qualified cells + zero mandatory skips; QA/Security, 8.3/8.4/8.7 | + +Medium risks: shared R-012 (4), deterministic test isolation; QA owns continuous monitoring. No additional low risk is invented just to fill a template. Residual risk is unmeasured until evidence exists. + +## NFR Planning + +Inherit every PRD/system quantitative gate: full P0 and mandatory P1/manual pass, zero mandatory flakes and Critical/High; 3performance runs;72h then30calendar days≥1M eligible events on exact RC, no acceleration/stitching. Reference dataset2kOperations/200Agents/500keys/1Mhistory; UI≤2sp95. MCP stable window and exact tool/browser/image/scanner versions freeze at execution, not invented now. + +| Category | Scenario linkage | Planned validation / evidence | +|---|---|---| +| Security/privacy | SEC risks and B scenarios below | Scope/abuse/canary tests, bounded sanitized logs and network/scan report | +| Reliability/data integrity | DATA/OPS risks and fault scenarios | Real authority/state assertions, fault schedule and reconciled counters/digests | +| Performance/scalability | Numeric epic obligations above | Calibrated raw latency/resource samples, achieved load and immutable config/topology fingerprint | +| Maintainability/compatibility | Every changed component | Existing `just verify`/UI gates as applicable, schema/contract diffs and traceable regression reports | + +Unknowns: exact execution hardware and fresh qualification artifacts are not available from this audit. Where the owning story requires a new tolerance, limit or version selection, freeze it in its approved contract before writing a numeric assertion; never replace the PRD threshold with a guessed easier value. Full NFR verdict belongs to `bmad-testarch-nfr` after execution. + +## Entry Criteria + +- Approved owning story/spec and prerequisites are available in the same worktree. +- ATDD loads the actual ACs from `epics.md` / selected spec and the system QA design. +- Existing tests and baseline failures are inspected before adding tests; no duplicate test suite solely for new IDs. +- Content-addressed valid and one-fault-per-input signed manifests with disposable test trust root; immutable RC environment with calibrated load/fault schedule; actual fresh-user/manual reviewers; sanitized raw reports and logs plus independent timestamps. External qualification owners must return accepted, candidate-bound evidence for manual, soak, documentation and burn-in handoffs; a requested or planned handoff is not completion. Synthetic verifier fixtures never count as production qualification. +- Missing fixture, service or approval is reported as blocked/not-run, not silently skipped. + +## Test Coverage Plan + +P0/P1/P2/P3 indicate priority, **not execution timing**. Each table row has two separate scenario seeds: `--A` and `...-B`. Split a seed when independent assertions require different fixtures. Reuse an existing equivalent test rather than duplicating it; ATDD records exact test name/path and AC mapping. + +The AC-count column inventories all `Given` groups under that source story, not a claim that two tests exhaust those groups. ATDD must map each group (story + ordinal + quoted acceptance text) to existing test, new test, or explicit not-run prerequisite before implementation. The approved spec controls finer-grained cases. + +### P0 — Critical + +Security, irreversible data integrity and false acceptance have no safe user workaround. + +| Story / scenario IDs | Requirements | AC groups | Primary level | Risk | A: expected behavior | B: rejection / fault | +|---|---|---:|---|---|---|---| +| 8.1 / 8.1-UNIT-A,B | FR-52 | 7 | UNIT | E8-R1 | Offline verifier binds one RC/source/image/config/workload to signed complete evidence and current trust state | Unknown/revoked key, forged/stale/missing/conflicting digest/time/status and trust rollback reject | +| 8.2 / 8.2-INT-A,B | FR-46 | 6 | INT | E8-R1/E8-R3 | Every supported capability maps to mandatory CI/manual evidence; exact command/version/seed/duration retained | Absent services, skipped/flaky/retried tests or deferred stable capability cannot normalize to pass | +| 8.4 / 8.4-SYS-A,B | FR-48 | 6 | SYS | E8-R3 | Pinned MCP revisions×≥3clients,≥50OpenAPI corpus and PG16/Valkey8/PG-only/browser matrix qualify | Missing/failed/stale cells block claims; experimental never substitutes stable and unsupported constructs never disappear | +| 8.5 / 8.5-SYS-A,B | FR-49 | 6 | SYS | E8-R2 | Three consecutive calibrated runs on fixed RC/dataset prove exact performance envelope | Generator saturation/config drift/telemetry gaps invalidate run; >10% regression needs recorded disposition | +| 8.6 / 8.6-SYS-A,B | FR-49 | 6 | SYS | E8-R2 | Continuous72h prescribed mix with fault/recovery schedule shows bounded growth and consistent accounting, then external qualification accepts the candidate-bound run evidence | Partition/DB/cache/telemetry/disk faults obey safety contracts; integrity interruption cannot stitch partial durations; a planned or unaccepted handoff is not done | +| 8.7 / 8.7-SYS-A,B | FR-50 | 6 | SYS | E8-R3 | Threat→control→test evidence and fresh pinned source/dependency/image/secret/license scans cover final surface | SSRF/bombs/scope/fencing/load-plan and full-output canaries reject abuse; no unresolved Critical/High | +| 8.9 / 8.9-SYS-A,B | FR-49, FR-53 | 7 | SYS | E8-R1/E8-R2 | Same RC completes30calendar days and≥1M eligible events; external qualification accepts the evidence and honest readiness page binds accepted results | Digest/environment integrity change resets window; a planned restart is not continuity evidence; probes excluded; loss/hidden issues or an unaccepted handoff block publication | +| 8.10 / 8.10-UNIT-A,B | FR-54 | 7 | UNIT | E8-R1 | Complete signed fixtures yield PUBLIC_READY only for matching immutable manifest/bundle/readiness digests | Each missing/stale/tampered/failing mandatory input blocks; FR54 cannot prove itself; no mandatory waiver path | + +### P1 — High + +Core user journeys and complex integrations; limited workaround, not relaxed acceptance. + +| Story / scenario IDs | Requirements | AC groups | Primary level | Risk | A: expected behavior | B: rejection / fault | +|---|---|---:|---|---|---|---| +| 8.3 / 8.3-MANUAL-A,B | FR-47 | 6 | MANUAL | E8-R3 | Named external qualification reviewer completes all versioned RU/EN core and recovery flows against same RC and returns accepted evidence | Validation/error/permission/confirmation/retry states checked; a planned/rejected/missing handoff is not done; defect fix invalidates affected evidence and creates new RC | +| 8.8 / 8.8-MANUAL-A,B | FR-51 | 6 | MANUAL | E8-R3 | Fresh external qualification user follows only shipped online/offline docs to MCP call, trace and backup/restore and returns accepted evidence | Broken commands/config/links or unavailable external dashboard must not hide recovery/runbook instructions; a planned/rejected/missing handoff is not done | + +### P2 / P3 + +No additional mandatory scope. Optional focused exploratory/cosmetic variants may be recorded later with owner and justification; they do not become an endless implementation/review queue. + +Levels: UNIT pure contract/model; INT real filesystem/database/runtime boundary; API actual handler/protocol; E2E critical browser journey; SYS isolated full-stack qualification; MANUAL named human protocol. Use unit cases for algorithms, real PG for transaction/fencing, wire fixtures for protocol, browser only for user-visible interaction. Intentional defense-in-depth checks different failure surfaces, not identical duplicated assertions. + +## Execution Strategy + +Run all functional tests in PRs when they fit the target 15-minute feedback window; defer only expensive infrastructure/duration, not inconvenient failures. Current Playwright is Chromium, one worker: parallelization is a future isolation-dependent optimization, not a current claim. + +- **PR:** changed functional/negative regressions and boundary suites; applicable Rust/tooling/config and UI gates. +- **Nightly:** bounded fault/contention, repeated isolation and resource trend tests after the required seams exist. +- **Weekly:** calibrated production-size performance, fresh-host/offline/recovery and manual qualification as applicable. +- **Epic / RC acceptance:** every mandatory AC and quantitative obligation must have exact-candidate evidence, even if its normal execution tier is weekly. Epic 8 owns the immutable long-duration release windows. + +Nightly/weekly scheduling is a proposed execution model; the current Gitea pipeline has PR/push and release jobs, not those schedules. This planning task does not create them. `just verify` does not replace Playwright, deployment/image or qualification jobs. + +## Resource Estimates + +Incremental QA test/evidence effort with working production seams and reusable fixtures, excluding feature implementation, provisioning lead time and unaccelerated duration. Low-confidence planning ranges, not token budgets or compulsory numbers of new tests; reassess at each story ATDD after deduplication. + +| Priority | Estimated effort | +|---|---| +| P0 | 48–96 hours | +| P1 | 24–48 hours | +| Optional P2 | 0–8 hours | +| Optional P3 | 0–4 hours | +| Total envelope | 72–156 hours, approximately 2–5 contributor-weeks | + +The 72-hour soak and subsequent 30 calendar days of burn-in are additional elapsed time and cannot be compressed into the effort estimate. + +## Exit Criteria and Quality Gates + +- P0 pass 100%; P1 ≥95% is an interim development signal only, **100% of mandatory P1 and manual ACs must pass for acceptance**. +- Every owning-story AC has test/protocol plus bound execution evidence; no mandatory skipped/flaky/blocked/not-run item becomes pass. +- No unresolved Critical/High defect; high-risk mitigation verified on the owning scenario before release. Mandatory Habr conditions have no waiver. +- Coverage targets remain system planning goals (80% workspace /90% new critical code where measured); **no coverage report currently proves them**. Scenario counts do not substitute for coverage instrumentation. +- NFR evidence names revision, config/topology, tool/data versions, command, seed, timestamps, raw sanitized output digest and result. +- Story completion follows its spec, not all remaining epic/system gaps; no automatic reopening of done stories. + +## Mitigation Plans + +Each high-risk owner in the matrix: (1) implement/reuse the production-safe seam; (2) run its A/B and detailed AC cases with controlled failures; (3) bind the output to the candidate; (4) re-evaluate residual risk. Status is planned or source-partial, never verified solely by this document. Required completion time is the owning story/epic milestone in the risk table. No generic follow-up review loop is created. + +## Assumptions and Dependencies + +Epics1–7 functionality and component evidence →8.1RC/evidence contract →8.2/8.3/8.4 quality→8.5performance→8.6soak→8.9burn-in→8.10publication; security/docs qualify same RC before gate. 8.3/8.6/8.8/8.9 require an explicit external-qualification handoff with accepted candidate-bound evidence. A blocking defect requires new RC and applicable resets. A planned product restart is operational maintenance; it does not establish qualification continuity, and an integrity-changing restart resets the 8.9 burn-in window. + +Accountable roles are responsibilities, not claims of staffed teams. Reference hardware, operator credentials and manual reviewers must be assigned before relevant qualification. Use disposable fixtures while waiting; lack of resources blocks the affected evidence, not permission to mutate a live deployment. + +## Interworking and Regression + +Affected components and reusable suites are named in Existing Coverage. Preserve existing REST→MCP, auth/credential/approval, config/migration, correlation and Community-boundary behavior whenever those shared contracts change. Frontend failures need actual browser regression; registry races need real-PG assertions, not UI mocks. + +## ATDD Handoff + +For the selected not-yet-implemented story only, load this plan and the exact approved spec; freeze its finite AC-to-test checklist before implementation. Prefer existing Rust/PG/Playwright patterns, add only uncovered acceptance scenarios and reproduce RED for missing behavior without artificial failure. Existing correct behavior may already be GREEN: record it honestly. Resume matching incomplete ATDD, reuse completed matching checklists and update only changed ACs. Do not invoke whole-epic automation on each review. + +Automatic pre-implementation ATDD requires the project build-auto handoff override; the stock bmad-loop0.11.1 TEA ATDD injection is post-dev and is not that sequence. Loop configuration is separate from completion of this plan. The design workflow itself does not run ATDD or product implementation. + +## References and Validation + +- Epic/AC source: `_bmad-output/planning-artifacts/epics.md`, Epic 8. +- System contract: [architecture](test-design-architecture.md), [QA inventory and execution](test-design-qa.md). +- Normative PRD and architecture spine: frontmatter inputDocuments. +- TEA knowledge: risk-governance, probability-impact, test-levels-framework, test-priorities-matrix, nfr-criteria. +- Utility integration: Playwright/Pact flags are true but packages absent. No imports, framework migration or Pact service are generated. Browser CLI unavailable; source-based design only. +- Validation: story IDs/requirements/AC counts, risk arithmetic/linkage and document paths checked; no final test/NFR PASS issued. Approval is planning-level user direction, not fabricated reviewer signatures. diff --git a/_bmad-output/test-artifacts/test-design-epics.md b/_bmad-output/test-artifacts/test-design-epics.md new file mode 100644 index 0000000..3cbd7d2 --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-epics.md @@ -0,0 +1,24 @@ +# Epic Test Design Index + +Updated 2026-09-13 against main `083974c27f3a21a15807dd248bb6bc4fe04a5cd8`. Eight plans cover all 99 stories from the approved current epics decomposition (25 historically done, 74 backlog). Plans are not acceptance or execution evidence; the numbering revision does not change a tested commit or fabricate a new run. + +| Epic | Story count | Plan | +|---|---:|---| +| 1 — REST → MCP foundation | 16 | [Regression and remaining evidence](test-design-epic-1.md) | +| 2 — OpenAPI import | 15 | [Storage, refs, HTTP contract, preview and re-import](test-design-epic-2.md) | +| 3 — MCP catalog | 20 | [Protocol adapters, Tools, Resources and Prompts](test-design-epic-3.md) | +| 4 — Background execution | 10 | [Durable Tasks, fencing and recovery](test-design-epic-4.md) | +| 5 — Observability | 13 | [Correlation, GlitchTip, spool, metrics and SLO](test-design-epic-5.md) | +| 6 — Load testing | 6 | [Safety plans, runner, stop and reports](test-design-epic-6.md) | +| 7 — Deployment | 9 | [Offline installation, migrations, backup and restore](test-design-epic-7.md) | +| 8 — Release qualification | 10 | [Immutable RC, matrices, soak and publication gate](test-design-epic-8.md) | + +Shared authority: [system architecture testability](test-design-architecture.md), [current QA inventory and execution strategy](test-design-qa.md), approved PRD and epic acceptance criteria. Historical handoff/baseline artifacts are not current pass evidence. + +Current plans use the approved sequential IDs: Epic 2 2.1–2.15, Epic 3 3.1–3.20, Epic 4 4.1–4.10 and Epic 5 5.1–5.13. The old→new mapping and AC allocation are recorded in the corresponding plan tables. Archived execution records retain their original identifiers; no new test execution is implied by renumbering. + +## Development boundary + +ATDD should freeze a finite, story-scoped AC-to-test checklist before implementation, reuse existing tests and matching completed checklists, and avoid regenerating tests in review. A green existing behavior must not be deliberately broken to fake RED. Qualification work runs only at its owning milestone; updating these plans does not reopen completed stories or launch any workload. + +The project now configures pre-implementation ATDD through `_bmad/custom/bmad-build-auto.toml`. The TEA plugin remains enabled; only its stock post-dev ATDD injection is disabled in `.bmad-loop/policy.toml`. Test artifacts are seeded into new worktrees. Mandatory acceptance scaffolds must be activated and pass before story completion; skipped scaffolds are not executed RED evidence. This is workflow configuration, not evidence of a completed live loop run; existing runs were not modified. diff --git a/_bmad-output/test-artifacts/test-design-progress-epic-2.md b/_bmad-output/test-artifacts/test-design-progress-epic-2.md new file mode 100644 index 0000000..bbf7304 --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-progress-epic-2.md @@ -0,0 +1,54 @@ +--- +runScope: 'epic-level' +runKey: 'epic-2' +workflowStatus: 'completed' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad/tea/config.yaml' +lastSaved: '2026-09-13' +--- + +# Epic 2 test design progress + +Output: test-design-epic-2.md. Completed 2026-09-13. Story/requirement/AC-count coverage, source references, risk scores and format validated. Template adapted to existing-project inventory: counts are scenario seeds, estimates are provisional QA deltas, no synthetic code-coverage or execution claim. Native loop ATDD is post-dev; pre-implementation customization is a separate pending approval, not executed by this design run. + +## Coverage decisions + +15 story families, two independently assertable scenario seeds per family (A positive contract; B rejection/fault). Approved numbering splits former 2.10 into 2.10 API (former groups 1–10, 12) and 2.11 UI (former 11 plus UI perspectives of 3 and 5); old 2.11–2.14 become 2.12–2.15. All owning-story Given/When/Then groups remain required ATDD input; these are not a claim of exhaustive implemented test cases. + +Scope: FR-7–FR-12; system families CP-05..07. Lowest effective level assigned per family. P0 security/data integrity with no workaround; P1 user/core flow. No speculative mandatory P2/P3 additions. + +Source reuse: `crates/crank-artifacts/tests/{artifact_store,artifact_store_io,reconciliation}.rs`; `crates/crank-registry/tests/integration/{artifact_sources,artifact_reconciliation}.rs`; `apps/admin-api/tests/integration/openapi_source/`; `crates/crank-import/tests/{preview,coverage,normalization_details,reference_resolution}.rs`; `apps/admin-api/tests/integration/openapi_import/`; `apps/ui/tests/e2e/operations.spec.js`. + +Gaps: 2.1–2.6 source/metadata/reconciliation/preview and 2.7–2.8 have reusable source tests, not fresh acceptance evidence. 2.9 tests exist only at candidate f8ee7c9, not main 083974c; rerun after integration. Security-scheme API/UI mapping, full partial/re-import policy matrix, ≥50-spec corpus and OpenAPI onboarding still need story-level deltas. Two candidate review deferrals (reverse URL placeholder validation and object/array default projection) remain explicit triage inputs, not automatically accepted or added to every story. + +NFR: Zero silent semantic loss; ≥50 versioned specs and ≥95% actionable Draft operations (2.14). Source size/depth/time/scan budgets come from the typed contract; test min/max/over-limit, do not invent limits. No secrets outside allowed encrypted authority. Test artifact retention under reference/cleanup contention. + +Fixtures: Immutable hostile/valid YAML/JSON corpus with expected IR and wire outcomes; local allowlisted HTTP/DNS fixtures; isolated temp roots; real PostgreSQL schemas; reproducible crash checkpoints. File-size fault tests must retain pipe/PTY stdout rather than a regular-file redirect. + +Execution: PR functional tests, nightly bounded expensive/fault work, weekly calibrated qualifications; scheduled tiers are planned, not configured. Mandatory story ACs still must pass before acceptance, regardless of tier. 72h/30day release windows only in Epic8. QA effort assumption with prerequisite implementation ready: P0 40–80h; P1 20–40h; optional P2 0–8h/P3 0–4h; total 60–132h (~2–4 contributor-weeks). Not a backlog of compulsory new tests; refine against existing-test reuse during ATDD. + + +## Risks and NFR planning + +| Risk | Category | Failure | P | I | Score | System risk | Mitigation / owner / deadline | +|---|---|---|---:|---:|---:|---|---| +| E2-R1 | DATA | Silent HTTP/schema loss in supported imports | 3 | 3 | 9 | R-002 | Wire oracle + IR/ref/plan golden tests; Import owner, before 2.14 | +| E2-R2 | SEC | Hostile files/refs escape scope, leak secrets or exhaust resources | 3 | 3 | 9 | R-004 | Bounded parser/network/storage canaries; Security + Import, each source story | +| E2-R3 | DATA | GC/re-import races lose pinned artifacts or overwrite revisions | 2 | 3 | 6 | R-008 | Real PG + filesystem fault interleavings; Registry, before 2.13 | +| E2-R4 | TECH | Flaky preview UI/evidence masks failed import | 2 | 2 | 4 | R-012 | Stale-response tests + strict evidence; UI/QA, 2.6/2.15 | + +Scores describe inherent risk, not observed failures or a release verdict. Security/reliability/performance thresholds inherit the system design and owning story ACs; missing environment/measurement evidence remains explicit, never inferred PASS. + + +Context: Rust/PostgreSQL + browser JavaScript fullstack. Existing test source inventory at main 083974c; f8ee7c9 candidate is separate. Browser CLI absent; no live exploration, no fabricated evidence. Playwright/Pact utility flags are intentions only: packages absent; no library migration or Pact scaffolding in this planning scope. Required risk, probability/impact, test levels/priorities and NFR knowledge loaded; concrete source reuse and gaps appear in the epic plan. + +Explicit batch request, independent epic scope. Requirements and acceptance criteria: planning-artifacts/epics.md, Epic 2. System designs already updated; no product implementation or test execution authorized by this planning run. diff --git a/_bmad-output/test-artifacts/test-design-progress-epic-3.md b/_bmad-output/test-artifacts/test-design-progress-epic-3.md new file mode 100644 index 0000000..43936b1 --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-progress-epic-3.md @@ -0,0 +1,53 @@ +--- +runScope: 'epic-level' +runKey: 'epic-3' +workflowStatus: 'completed' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad/tea/config.yaml' +lastSaved: '2026-09-13' +--- + +# Epic 3 test design progress + +Output: test-design-epic-3.md. Completed 2026-09-13. Story/requirement/AC-count coverage, source references, risk scores and format validated. Template adapted to existing-project inventory: counts are scenario seeds, estimates are provisional QA deltas, no synthetic code-coverage or execution claim. Native loop ATDD is post-dev; pre-implementation customization is a separate pending approval, not executed by this design run. + +## Coverage decisions + +20 story families, two independently assertable scenario seeds per family (A positive contract; B rejection/fault). Approved decomposition separates call lifecycle from Tool signals, Prompt Draft/publish/list/portability, and completion/logging/Resource-Prompt signals; former 3.14 is now 3.20. All owning-story Given/When/Then groups remain required ATDD input; these are not a claim of exhaustive implemented test cases. + +Scope: FR-13–FR-20; system families CP-08..11. Lowest effective level assigned per family. P0 security/data integrity with no workaround; P1 user/core flow. No speculative mandatory P2/P3 additions. + +Source reuse: `crates/crank-community-mcp/tests/unit/{manifest,session,tool_error}.rs`; `apps/mcp-server/tests/integration/{transport_protocol,catalog_access,tool_search,execution_stages}.rs`; `apps/ui/tests/e2e/onboarding.spec.js`. + +Gaps: Existing tests cover baseline Tools, transport, catalog and runtime only. Resources/Prompts/modern adapter matrix are planned; no feature-level tests were found in main. Do not confuse MCP client-library behavior with implementation evidence. Tasks cells are completed by Story 4.7; 3.20 must mark them pending rather than falsely PASS. + +NFR: Discovery p95 ≤150 ms on 2,000 Operations/200 Agents; zero unauthorized metadata/content reads. Pin stable/N-1/N-2 and ≥3 clients at feature freeze. The 2026-07-28 wire shapes named in epics.md are planning inputs, not a newly verified claim about latest MCP; verify official specifications/digests before adapter ATDD, preserving legacy deprecation gate. + +Fixtures: Wire fixtures per protocol era; scope-separated Agent catalogs; text/JSON/binary hostile resources; exact-version graphs; capture upstream; clock/cancellation barriers; browser keyboard and RU/EN fixtures. + +Execution: PR functional tests, nightly bounded expensive/fault work, weekly calibrated qualifications; scheduled tiers are planned, not configured. Mandatory story ACs still must pass before acceptance, regardless of tier. 72h/30day release windows only in Epic8. QA effort assumption with prerequisite implementation ready: P0 60–120h; P1 32–64h; optional P2 0–12h/P3 0–4h; total 92–200h (~3–6 contributor-weeks). Not a backlog of compulsory new tests; refine against existing-test reuse during ATDD. + + +## Risks and NFR planning + +| Risk | Category | Failure | P | I | Score | System risk | Mitigation / owner / deadline | +|---|---|---|---:|---:|---:|---|---| +| E3-R1 | BUS | Advertised capabilities or version behavior disagree | 2 | 3 | 6 | R-009 | Revision/client matrix and wire errors; MCP owner, 3.20 | +| E3-R2 | SEC | Resource/Prompt scope or REST expansion leaks data | 3 | 3 | 9 | R-004 | Negative authorization + SSRF + redaction; Security, 3.8/3.11/3.16 | +| E3-R3 | DATA | Mutable catalog or stale cursor serves wrong published version | 2 | 3 | 6 | R-009 | Snapshot/revoke races; Registry/MCP, publication stories | + +Scores describe inherent risk, not observed failures or a release verdict. Security/reliability/performance thresholds inherit the system design and owning story ACs; missing environment/measurement evidence remains explicit, never inferred PASS. + + +Context: Rust/PostgreSQL + browser JavaScript fullstack. Existing test source inventory at main 083974c; f8ee7c9 candidate is separate. Browser CLI absent; no live exploration, no fabricated evidence. Playwright/Pact utility flags are intentions only: packages absent; no library migration or Pact scaffolding in this planning scope. Required risk, probability/impact, test levels/priorities and NFR knowledge loaded; concrete source reuse and gaps appear in the epic plan. + +Explicit batch request, independent epic scope. Requirements and acceptance criteria: planning-artifacts/epics.md, Epic 3. System designs already updated; no product implementation or test execution authorized by this planning run. diff --git a/_bmad-output/test-artifacts/test-design-progress-epic-4.md b/_bmad-output/test-artifacts/test-design-progress-epic-4.md new file mode 100644 index 0000000..e3e7fa3 --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-progress-epic-4.md @@ -0,0 +1,53 @@ +--- +runScope: 'epic-level' +runKey: 'epic-4' +workflowStatus: 'completed' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad/tea/config.yaml' +lastSaved: '2026-09-13' +--- + +# Epic 4 test design progress + +Output: test-design-epic-4.md. Completed 2026-09-13. Story/requirement/AC-count coverage, source references, risk scores and format validated. Template adapted to existing-project inventory: counts are scenario seeds, estimates are provisional QA deltas, no synthetic code-coverage or execution claim. Native loop ATDD is post-dev; pre-implementation customization is a separate pending approval, not executed by this design run. + +## Coverage decisions + +10 story families, two independently assertable scenario seeds per family (A positive contract; B rejection/fault). Former 4.5 splits into input (4.5) and reconciliation (4.6); former Admin UI splits into basic Task UI (4.8) and input/reconciliation UI (4.9). All owning-story Given/When/Then groups remain required ATDD input; these are not a claim of exhaustive implemented test cases. + +Scope: FR-21–FR-26; system families CP-12..15. Lowest effective level assigned per family. P0 security/data integrity with no workaround; P1 user/core flow. No speculative mandatory P2/P3 additions. + +Source reuse: `crates/crank-runtime/tests/{stages,product_metrics}.rs`, `crates/crank-runtime/tests/integration/{idempotency,confirmation,valkey}.rs`, `crates/crank-test-support/src/lib.rs` supply synchronous safety and real-PG fixture patterns. + +Gaps: No durable Task/worker/admission lifecycle tests found in main. tokio::task usage is not MCP Tasks coverage. All story-specific Task acceptance scenarios are planned. Existing synchronous idempotency and approval tests must remain regression coverage, not be rewritten to make unsafe Task behavior pass. + +NFR: 128 concurrent sync/background executions, up to 10,000 queued; start and steady queue wait p95 ≤5 s within service rate, oldest age ≤30 s; 10k backlog drains ≤60 minutes after overload ends. Shutdown ≤30 s and eligible lease recovery ≤60 s. Fencing protects Crank state, not exactly-once external side effects. + +Fixtures: Real PG independent worker connections; controllable clock/barriers and crash checkpoints before/after commit, claim, dispatch, side effect and terminal commit; counted upstream with and without verified idempotency; Valkey-off fixture; separate measured capacity host. + +Execution: PR functional tests, nightly bounded expensive/fault work, weekly calibrated qualifications; scheduled tiers are planned, not configured. Mandatory story ACs still must pass before acceptance, regardless of tier. 72h/30day release windows only in Epic8. QA effort assumption with prerequisite implementation ready: P0 64–128h; P1 20–40h; optional P2 0–8h/P3 0–4h; total 84–180h (~3–5 contributor-weeks). Not a backlog of compulsory new tests; refine against existing-test reuse during ATDD. + + +## Risks and NFR planning + +| Risk | Category | Failure | P | I | Score | System risk | Mitigation / owner / deadline | +|---|---|---|---:|---:|---:|---|---| +| E4-R1 | DATA | Stale lease or retry duplicates an external side effect | 3 | 3 | 9 | R-003 | Fencing + side-effect counters + unknown outcomes; Task owner, 4.3–4.6 | +| E4-R2 | PERF | Admission/queue exhaustion starves control plane | 3 | 3 | 9 | R-006 | Limits/fairness/recovery under load; Performance, 4.10 | +| E4-R3 | SEC | Cross-scope Task control or resume bypasses consent | 2 | 3 | 6 | R-004 | Owner-bound cancel/input/reconciliation; Security, 4.5–4.9 | + +Scores describe inherent risk, not observed failures or a release verdict. Security/reliability/performance thresholds inherit the system design and owning story ACs; missing environment/measurement evidence remains explicit, never inferred PASS. + + +Context: Rust/PostgreSQL + browser JavaScript fullstack. Existing test source inventory at main 083974c; f8ee7c9 candidate is separate. Browser CLI absent; no live exploration, no fabricated evidence. Playwright/Pact utility flags are intentions only: packages absent; no library migration or Pact scaffolding in this planning scope. Required risk, probability/impact, test levels/priorities and NFR knowledge loaded; concrete source reuse and gaps appear in the epic plan. + +Explicit batch request, independent epic scope. Requirements and acceptance criteria: planning-artifacts/epics.md, Epic 4. System designs already updated; no product implementation or test execution authorized by this planning run. diff --git a/_bmad-output/test-artifacts/test-design-progress-epic-5.md b/_bmad-output/test-artifacts/test-design-progress-epic-5.md new file mode 100644 index 0000000..60aaac8 --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-progress-epic-5.md @@ -0,0 +1,54 @@ +--- +runScope: 'epic-level' +runKey: 'epic-5' +workflowStatus: 'completed' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad/tea/config.yaml' +lastSaved: '2026-09-13' +--- + +# Epic 5 test design progress + +Output: test-design-epic-5.md. Completed 2026-09-13. Story/requirement/AC-count coverage, source references, risk scores and format validated. Template adapted to existing-project inventory: counts are scenario seeds, estimates are provisional QA deltas, no synthetic code-coverage or execution claim. Native loop ATDD is post-dev; pre-implementation customization is a separate pending approval, not executed by this design run. + +## Coverage decisions + +13 story families, two independently assertable scenario seeds per family (A positive contract; B rejection/fault). Former 5.9 splits into Prometheus (5.9) and notification gateway/Apprise (5.10); Grafana becomes 5.11; former 5.11 splits into SLO (5.12) and alert delivery/end-of-epic evidence (5.13). All owning-story Given/When/Then groups remain required ATDD input; these are not a claim of exhaustive implemented test cases. + +Scope: FR-27–FR-35; system families CP-16..21. Lowest effective level assigned per family. P0 security/data integrity with no workaround; P1 user/core flow. No speculative mandatory P2/P3 additions. + +Source reuse: `crates/crank-observability/tests/{request_correlation,propagation,json_logging,redaction,critical_errors,otlp,prometheus,http_metrics,metrics_signals}.rs`; `apps/mcp-server/tests/integration/execution_stages.rs`; `apps/admin-api/tests/integration/logs_usage.rs`; `crates/crank-metrics/tests/`. + +Gaps: IDs, local metric registry, redaction and captured OTLP are source-present foundations. Real GlitchTip receiver delivery, durable encrypted spool/loss reconciliation, complete ProductEvent rollups, packaged Prometheus/Grafana and SLO qualification are not proven by them. Actual Load Run data acceptance remains in 6.6, not Grafana story 5.11. No services are provisioned in this task. + +NFR: 100% support IDs independent of sampling; healthy delivery ≥99.99% within60s; outage≤24h with100% saved-envelope delivery within25h, sized30h spool. Observability overhead≤5% p95 latency and≤10% CPU; drain≤30s. Availability30d≥99.95%, control plane≥99.9%. Exact series budgets/buckets and burn windows must use versioned typed/rule contracts; unspecified values remain UNKNOWN until owning story freezes them. + +Fixtures: Queryable local trace/error receiver and real GlitchTip qualification environment; independent generated/accepted/ACK/lost envelope ledger; bounded disk partitions and fault controls; golden UTC events; Prometheus synthetic series; provisioned Grafana fixture without committed secrets. + +Execution: PR functional tests, nightly bounded expensive/fault work, weekly calibrated qualifications; scheduled tiers are planned, not configured. Mandatory story ACs still must pass before acceptance, regardless of tier. 72h/30day release windows only in Epic8. QA effort assumption with prerequisite implementation ready: P0 60–120h; P1 24–48h; optional P2 0–8h/P3 0–4h; total 84–180h (~3–5 contributor-weeks). Not a backlog of compulsory new tests; refine against existing-test reuse during ATDD. + + +## Risks and NFR planning + +| Risk | Category | Failure | P | I | Score | System risk | Mitigation / owner / deadline | +|---|---|---|---:|---:|---:|---|---| +| E5-R1 | OPS | Spool/replay loss yields false trace completeness | 2 | 3 | 6 | R-005 | Independent envelope accounting and crash/outage; Observability, 5.6 | +| E5-R2 | SEC | Browser/export/link leaks secrets or executes unsafe URL | 3 | 3 | 9 | R-004 | Canaries at every sink and hostile links; Security/UI, 5.2–5.4 | +| E5-R3 | DATA | Rollups/cardinality/SLI denominators lie | 2 | 3 | 6 | R-011 | Idempotency + UTC + rules oracles; Metrics, 5.8/5.12 | +| E5-R4 | PERF | Telemetry pressure blocks product requests | 3 | 3 | 9 | R-006 | Quota isolation + enabled/disabled comparison; SRE, 5.6 | + +Scores describe inherent risk, not observed failures or a release verdict. Security/reliability/performance thresholds inherit the system design and owning story ACs; missing environment/measurement evidence remains explicit, never inferred PASS. + + +Context: Rust/PostgreSQL + browser JavaScript fullstack. Existing test source inventory at main 083974c; f8ee7c9 candidate is separate. Browser CLI absent; no live exploration, no fabricated evidence. Playwright/Pact utility flags are intentions only: packages absent; no library migration or Pact scaffolding in this planning scope. Required risk, probability/impact, test levels/priorities and NFR knowledge loaded; concrete source reuse and gaps appear in the epic plan. + +Explicit batch request, independent epic scope. Requirements and acceptance criteria: planning-artifacts/epics.md, Epic 5. System designs already updated; no product implementation or test execution authorized by this planning run. diff --git a/_bmad-output/test-artifacts/test-design-progress-epic-6.md b/_bmad-output/test-artifacts/test-design-progress-epic-6.md new file mode 100644 index 0000000..b49da1f --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-progress-epic-6.md @@ -0,0 +1,53 @@ +--- +runScope: 'epic-level' +runKey: 'epic-6' +workflowStatus: 'completed' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad/tea/config.yaml' +lastSaved: '2026-09-13' +--- + +# Epic 6 test design progress + +Output: test-design-epic-6.md. Completed 2026-09-13. Story/requirement/AC-count coverage, source references, risk scores and format validated. Template adapted to existing-project inventory: counts are scenario seeds, estimates are provisional QA deltas, no synthetic code-coverage or execution claim. Native loop ATDD is post-dev; pre-implementation customization is a separate pending approval, not executed by this design run. + +## Coverage decisions + +6 story families, two independently assertable scenario seeds per family (A positive contract; B rejection/fault). The last two former 6.1 full-workflow groups move to 6.6; 6.4 adds the approved Run/generator/report correlation group (7 AC groups), and 6.6 has 9. Per-process spool applies only where the owning telemetry contract requires it; this revision does not add a blanket new spool. All owning-story Given/When/Then groups remain required ATDD input; these are not a claim of exhaustive implemented test cases. + +Scope: FR-36–FR-40; system families CP-22..24. Lowest effective level assigned per family. P0 security/data integrity with no workaround; P1 user/core flow. No speculative mandatory P2/P3 additions. + +Source reuse: Runtime metric/overhead patterns in `crates/crank-runtime/tests/product_metrics.rs` and `crates/crank-metrics/tests/overhead.rs`; real MCP fixture in `apps/ui/scripts/playwright-http-fixture.js` and `apps/ui/tests/e2e/onboarding.spec.js`. + +Gaps: No Load Scenario, runner, safety-plan or report feature suites found. Existing microbenchmarks/local budget checks do not prove generated RPS, control-plane isolation or product capacity. DAU preview is a load model, not the measured unique-Agent DAU rollup of 5.8. + +NFR: Hard non-overridable ceilings1000RPS/512VU/2h/10,000,000iterations (6.3). Qualification100RPS30m +250RPS5m, per-minute success≥99.95% and saturation rejects≤0.1%; platform overheadp95≤50ms/p99≤150ms with10ms upstream/cache off. Arrival tolerance and stop/drain policy must be frozen by owning story, never chosen silently by tests. + +Fixtures: Counted controllable upstream; signed-plan negative fixtures with exact change fingerprints; isolated runner CPU/memory/network and reserved control path; host kill socket in disposable sandbox; external calibrated generator/counters to separate harness saturation from SUT saturation. + +Execution: PR functional tests, nightly bounded expensive/fault work, weekly calibrated qualifications; scheduled tiers are planned, not configured. Mandatory story ACs still must pass before acceptance, regardless of tier. 72h/30day release windows only in Epic8. QA effort assumption with prerequisite implementation ready: P0 40–80h; P1 24–48h; optional P2 0–8h/P3 0–4h; total 64–140h (~2–4 contributor-weeks). Not a backlog of compulsory new tests; refine against existing-test reuse during ATDD. + + +## Risks and NFR planning + +| Risk | Category | Failure | P | I | Score | System risk | Mitigation / owner / deadline | +|---|---|---|---:|---:|---:|---|---| +| E6-R1 | SEC | Forged/stale load plan dispatches damaging writes | 3 | 3 | 9 | R-010 | Signed fingerprint + replay/SSRF/write negatives; Security, 6.3 | +| E6-R2 | OPS | Runner duplicates generation or cannot stop | 2 | 3 | 6 | R-010 | Owner fencing + reserved path + independent kill; Runner, 6.4–6.5 | +| E6-R3 | PERF | Generator bottleneck/aggregation reports false SUT performance | 3 | 3 | 9 | R-006 | External calibration + independent counts; Performance, 6.6 | + +Scores describe inherent risk, not observed failures or a release verdict. Security/reliability/performance thresholds inherit the system design and owning story ACs; missing environment/measurement evidence remains explicit, never inferred PASS. + + +Context: Rust/PostgreSQL + browser JavaScript fullstack. Existing test source inventory at main 083974c; f8ee7c9 candidate is separate. Browser CLI absent; no live exploration, no fabricated evidence. Playwright/Pact utility flags are intentions only: packages absent; no library migration or Pact scaffolding in this planning scope. Required risk, probability/impact, test levels/priorities and NFR knowledge loaded; concrete source reuse and gaps appear in the epic plan. + +Explicit batch request, independent epic scope. Requirements and acceptance criteria: planning-artifacts/epics.md, Epic 6. System designs already updated; no product implementation or test execution authorized by this planning run. diff --git a/_bmad-output/test-artifacts/test-design-progress-epic-7.md b/_bmad-output/test-artifacts/test-design-progress-epic-7.md new file mode 100644 index 0000000..2fdc15f --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-progress-epic-7.md @@ -0,0 +1,53 @@ +--- +runScope: 'epic-level' +runKey: 'epic-7' +workflowStatus: 'completed' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad/tea/config.yaml' +lastSaved: '2026-09-13' +--- + +# Epic 7 test design progress + +Output: test-design-epic-7.md. Completed 2026-09-13. Story/requirement/AC-count coverage, source references, risk scores and format validated. Template adapted to existing-project inventory: counts are scenario seeds, estimates are provisional QA deltas, no synthetic code-coverage or execution claim. Native loop ATDD is post-dev; pre-implementation customization is a separate pending approval, not executed by this design run. + +## Coverage decisions + +9 story families, two independently assertable scenario seeds per family (A positive contract; B rejection/fault). The offline-upgrade AC moves from 7.5 to 7.9: bundle install/trust remains 5 groups in 7.5 and upgrade/rollback continuity becomes 8 groups in 7.9. All owning-story Given/When/Then groups remain required ATDD input; these are not a claim of exhaustive implemented test cases. + +Scope: FR-41–FR-45; system families CP-25..27. Lowest effective level assigned per family. P0 security/data integrity with no workaround; P1 user/core flow. No speculative mandatory P2/P3 additions. + +Source reuse: `crates/crank-config/tests/{contract,generation,redaction}.rs`; `crates/crank-registry/tests/integration/migrations.rs` and `migrations/`; `apps/admin-api/tests/migration_command.rs`; `apps/admin-api/tests/config_startup.rs`; `scripts/restore-community.sh`; `scripts/authenticated-product-smoke.py`; `.gitea/workflows/ci.yml`. + +Gaps: Config/migration/auth foundations and Compose authenticated smoke exist. Restore script presence is not three qualified PITR restores. Complete offline signed bundle, role isolation with future worker/runner and full N/N-1 online/offline matrix need evidence. Prior deployment failures require regression fixtures for legacy fingerprint, missing core, external PG topology and failed migrate diagnostics, not permission to reset databases. + +NFR: Each of3independent restores RPO≤5m/RTO≤30m with real MCP probe; drain≤30s and eligible Task recovery≤60s. Production sizing retains≥30% measured headroom. Zero known Critical/High, zero unapproved egress. Trust material/reference-host allocation and exact image digests are execution prerequisites, never generated secrets in docs. + +Fixtures: Disposable fresh host/network namespaces; PG16 current/N-1/legacy snapshots; checksummed artifacts/WAL plus out-of-band test keys; fault checkpoints; offline registry-less image archive; default-deny egress capture; fresh scanner DB pinned in report. + +Execution: PR functional tests, nightly bounded expensive/fault work, weekly calibrated qualifications; scheduled tiers are planned, not configured. Mandatory story ACs still must pass before acceptance, regardless of tier. 72h/30day release windows only in Epic8. QA effort assumption with prerequisite implementation ready: P0 48–96h; P1 16–32h; optional P2 0–8h/P3 0–4h; total 64–140h (~2–4 contributor-weeks). Not a backlog of compulsory new tests; refine against existing-test reuse during ATDD. + + +## Risks and NFR planning + +| Risk | Category | Failure | P | I | Score | System risk | Mitigation / owner / deadline | +|---|---|---|---:|---:|---:|---|---| +| E7-R1 | DATA | Schema/artifact/key mismatch destroys recovery | 2 | 3 | 6 | R-008 | Manifest + N/N-1 + three real restores; SRE, 7.8–7.9 | +| E7-R2 | SEC | Unsafe defaults/proxy/privileges expose installation | 2 | 3 | 6 | R-007 | Fresh-host negative exposure tests; Security, 7.4/7.6 | +| E7-R3 | SEC | Offline bundle untrusted or phones home | 2 | 3 | 6 | R-014 | Offline signature/tamper/egress tests; Release, 7.5 | + +Scores describe inherent risk, not observed failures or a release verdict. Security/reliability/performance thresholds inherit the system design and owning story ACs; missing environment/measurement evidence remains explicit, never inferred PASS. + + +Context: Rust/PostgreSQL + browser JavaScript fullstack. Existing test source inventory at main 083974c; f8ee7c9 candidate is separate. Browser CLI absent; no live exploration, no fabricated evidence. Playwright/Pact utility flags are intentions only: packages absent; no library migration or Pact scaffolding in this planning scope. Required risk, probability/impact, test levels/priorities and NFR knowledge loaded; concrete source reuse and gaps appear in the epic plan. + +Explicit batch request, independent epic scope. Requirements and acceptance criteria: planning-artifacts/epics.md, Epic 7. System designs already updated; no product implementation or test execution authorized by this planning run. diff --git a/_bmad-output/test-artifacts/test-design-progress-epic-8.md b/_bmad-output/test-artifacts/test-design-progress-epic-8.md new file mode 100644 index 0000000..0426d5c --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-progress-epic-8.md @@ -0,0 +1,53 @@ +--- +runScope: 'epic-level' +runKey: 'epic-8' +workflowStatus: 'completed' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +inputDocuments: + - '_bmad-output/planning-artifacts/epics.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad/tea/config.yaml' +lastSaved: '2026-09-13' +--- + +# Epic 8 test design progress + +Output: test-design-epic-8.md. Completed 2026-09-13. Story/requirement/AC-count coverage, source references, risk scores and format validated. Template adapted to existing-project inventory: counts are scenario seeds, estimates are provisional QA deltas, no synthetic code-coverage or execution claim. Native loop ATDD is post-dev; pre-implementation customization is a separate pending approval, not executed by this design run. + +## Coverage decisions + +10 story families, two independently assertable scenario seeds per family (A positive contract; B rejection/fault). Stories 8.3, 8.6, 8.8 and 8.9 require external-qualification handoff with accepted candidate-bound evidence; planned/rejected/missing handoff is not done. In 8.9, a planned restart is operational maintenance, not qualification continuity; an integrity-changing restart resets its window. All owning-story Given/When/Then groups remain required ATDD input; these are not a claim of exhaustive implemented test cases. + +Scope: FR-46–FR-54; system families CP-28..34. Lowest effective level assigned per family. P0 security/data integrity with no workaround; P1 user/core flow. No speculative mandatory P2/P3 additions. + +Source reuse: `docs/capability-inventory.json`; `docs/capability-baseline/results.json`; `scripts/collect-capability-baseline.py`; `scripts/validate-capability-run.py`; `tests/unit/`; `.gitea/workflows/{ci,release}.yml`; `scripts/scan-images.sh`; `docs/manual-regression-checklist.md`. + +Gaps: Existing inventory/collector and CI scans are foundations, not full signed RC evidence. Historical baseline2026.08.24.1 uses revision767428, not current main. Chromium-only current suite is not Firefox/WebKit×RU/EN qualification. No measured coverage report,72h/30day accepted run or3PITR restores was produced by this planning task. + +NFR: Inherit every PRD/system quantitative gate: full P0 and mandatory P1/manual pass, zero mandatory flakes and Critical/High; 3performance runs;72h then30calendar days≥1M eligible events on exact RC, no acceleration/stitching. Reference dataset2kOperations/200Agents/500keys/1Mhistory; UI≤2sp95. MCP stable window and exact tool/browser/image/scanner versions freeze at execution, not invented now. + +Fixtures: Content-addressed valid and one-fault-per-input signed manifests with disposable test trust root; immutable RC environment with calibrated load/fault schedule; actual fresh-user/manual reviewers; sanitized raw reports and logs plus independent timestamps. Synthetic verifier fixtures never count as production qualification. + +Execution: PR functional tests, nightly bounded expensive/fault work, weekly calibrated qualifications; scheduled tiers are planned, not configured. Mandatory story ACs still must pass before acceptance, regardless of tier. 72h/30day release windows only in Epic8. QA effort assumption with prerequisite implementation ready: P0 48–96h; P1 24–48h; optional P2 0–8h/P3 0–4h; total 72–156h (~2–5 contributor-weeks). Not a backlog of compulsory new tests; refine against existing-test reuse during ATDD. + + +## Risks and NFR planning + +| Risk | Category | Failure | P | I | Score | System risk | Mitigation / owner / deadline | +|---|---|---|---:|---:|---:|---|---| +| E8-R1 | OPS | Mixed/stale/forged evidence produces PUBLIC_READY | 3 | 3 | 9 | R-013 | Offline signed verifier with negative fixture per gate input; Release, 8.1/8.10 | +| E8-R2 | OPS | Leaks/recovery failures appear only after sustained traffic | 2 | 3 | 6 | R-015 | 72h + 30 calendar days fixed RC; SRE, 8.6/8.9 | +| E8-R3 | SEC | Incomplete matrix/security/manual pass hides unsafe claims | 2 | 3 | 6 | R-014 | Full qualified cells + zero mandatory skips; QA/Security, 8.3/8.4/8.7 | + +Scores describe inherent risk, not observed failures or a release verdict. Security/reliability/performance thresholds inherit the system design and owning story ACs; missing environment/measurement evidence remains explicit, never inferred PASS. + + +Context: Rust/PostgreSQL + browser JavaScript fullstack. Existing test source inventory at main 083974c; f8ee7c9 candidate is separate. Browser CLI absent; no live exploration, no fabricated evidence. Playwright/Pact utility flags are intentions only: packages absent; no library migration or Pact scaffolding in this planning scope. Required risk, probability/impact, test levels/priorities and NFR knowledge loaded; concrete source reuse and gaps appear in the epic plan. + +Explicit batch request, independent epic scope. Requirements and acceptance criteria: planning-artifacts/epics.md, Epic 8. System designs already updated; no product implementation or test execution authorized by this planning run. diff --git a/_bmad-output/test-artifacts/test-design-progress.md b/_bmad-output/test-artifacts/test-design-progress.md new file mode 100644 index 0000000..f39cd66 --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-progress.md @@ -0,0 +1,447 @@ +--- +workflowStatus: 'completed' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +lastSaved: '2026-08-08' +inputDocuments: + - '_bmad-output/project-context.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md' + - '_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md' + - '_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md' + - '_bmad-output/planning-artifacts/epics.md' + - '.agents/skills/bmad-testarch-test-design/resources/tea-index.csv' + - '.agents/skills/bmad-testarch-test-design/resources/knowledge/adr-quality-readiness-checklist.md' + - '.agents/skills/bmad-testarch-test-design/resources/knowledge/nfr-criteria.md' + - '.agents/skills/bmad-testarch-test-design/resources/knowledge/test-levels-framework.md' + - '.agents/skills/bmad-testarch-test-design/resources/knowledge/risk-governance.md' + - '.agents/skills/bmad-testarch-test-design/resources/knowledge/test-quality.md' + - '.agents/skills/bmad-testarch-test-design/resources/knowledge/playwright-cli.md' + - '.agents/skills/bmad-testarch-test-design/resources/knowledge/contract-testing.md' + - '.agents/skills/bmad-testarch-test-design/resources/knowledge/test-priorities-matrix.md' + - '.agents/skills/bmad-testarch-test-design/resources/knowledge/probability-impact.md' + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' + - '_bmad-output/test-artifacts/test-design/crank-handoff.md' +--- + +# Test Design Progress — crank + +## Step 1: Mode and Prerequisites + +- **Mode:** System-Level. +- **Reason:** одновременно доступны PRD, Architecture Spine/architecture decisions и полные Epics/Stories; по правилу workflow системный test design предшествует epic-level plans. +- **PRD:** `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md`. +- **Architecture:** `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md`. +- **Story coverage:** `_bmad-output/planning-artifacts/epics.md` — 8 эпиков, 99 Story (25 исторически done, 74 backlog), 54 FR. Изменение декомпозиции не меняет факт или commit ранее выполненных проверок. +- **Prerequisite result:** PASS; обязательные входы найдены. + +## Step 2: Loaded Context and Knowledge Base + +- **Configuration:** `tea_use_playwright_utils=true`, `tea_use_pactjs_utils=false`, `tea_pact_mcp=none`, `tea_browser_automation=auto`, `test_stack_type=auto`, `test_artifacts=_bmad-output/test-artifacts`. +- **Detected stack:** `fullstack`. Backend indicators: Rust workspace/Cargo, Axum/Tokio/SQLx/PostgreSQL. Frontend indicators: `apps/ui/package.json`, Playwright config and existing browser specs using `page.goto`/locators. +- **Product inputs:** PRD plus addendum, Architecture Spine/ADRs, complete approved 8-epic/99-story plan and project-context rules. No required input is missing. +- **Pinned technology:** Rust 1.96.1 / Edition 2024 / MSRV 1.96, Axum 0.8, Tokio 1, SQLx 0.9, Reqwest 0.12, PostgreSQL 16, optional Valkey 8, Node 22, Alpine.js 3.15.12 and Playwright 1.61.1. +- **Primary integration boundaries:** Admin UI/API; version-isolated MCP server; REST upstream and OpenAPI external refs; PostgreSQL authority; optional Valkey acceleration; durable Task Worker; isolated Load Runner; artifact storage; GlitchTip/Sentry-compatible telemetry; Prometheus/Grafana; backup/PITR and signed offline release bundle. +- **Test-design scope:** all 54 FR, 30 NFR and 34 architecture requirements, including current REST→MCP regression, real-world OpenAPI corpus, Tools/Resources/Prompts and MCP revision matrix, synchronous/background execution, trace correlation, technical/business metrics, built-in Load Runs, deployment/recovery and one-RC release evidence. + +### Extracted NFR thresholds + +- Reference workload: 100 RPS for 30 minutes and 250 RPS for 5 minutes; per-minute product success ≥99.95%, saturation rejection ≤0.1%. +- Capacity: ≥128 concurrent executions, 10,000 queued Tasks, and production dataset of 2,000 Operations / 200 Agents / 500 keys / 1,000,000 history records. +- Latency: platform overhead ≤50 ms p95 / ≤150 ms p99 against a 10 ms stub; discovery ≤150 ms p95; principal UI screens ≤2 s p95 over local LAN. +- Reliability: product success ≥99.95%, control-plane availability ≥99.9%; graceful shutdown ≤30 s; Task start ≤5 s p95; lease recovery ≤60 s; RPO ≤5 min and RTO ≤30 min. +- Observability: IDs on 100% of requests/records; traces generated for 100%; delivery ≥99.99% within 60 s and 100% completeness within 25 h for outages ≤24 h; 30 h spool capacity; overhead ≤5% p95 latency and ≤10% CPU. +- Security: default deny, encrypted/non-returnable secrets, per-connection SSRF enforcement, bounded resources/cardinality, fail-closed safety stores, no Critical/High vulnerabilities or findings, and no telemetry egress without opt-in. +- Compatibility/release: latest stable MCP at feature freeze plus N-1/N-2; ≥50 OpenAPI fixtures with ≥95% actionable Drafts and zero silent loss; 72 h soak; non-accelerable 30-day/≥1M-event burn-in; complete manual regression and signed evidence for one immutable RC. + +### Threshold completeness and deferred parameters + +Critical release thresholds are measurable and sufficiently defined for system test design. Remaining values are implementation-time tuning parameters rather than missing product targets: PostgreSQL partition/index thresholds, Task polling/lease/batch/fairness values, exact Grafana panel layout/derived alert thresholds, digest-pinned observability images and feature-freeze MCP revisions. They must be frozen before the corresponding epic qualification tests and cannot weaken the NFRs above. + +### Loaded testing guidance + +- System-level readiness uses the 8-category/29-criterion ADR checklist and objective PASS/CONCERNS/FAIL evidence. +- Risk scoring is probability × impact (1–9); score ≥6 requires owner/mitigation and score 9 blocks the gate. +- Coverage follows the lowest effective level: Rust unit/property tests for pure invariants, PostgreSQL/container integration tests for persistence/concurrency, protocol/API contract tests for boundaries, Playwright only for critical UI journeys, and dedicated load/security/recovery tools for NFRs. +- Tests must be deterministic, isolated, parallel-safe, self-cleaning, without hard waits, with explicit assertions, focused files and controlled test data. +- Contract testing is relevant to Admin/OpenAPI/MCP/runtime boundaries, but Pact.js Utils and Pact MCP are disabled; contracts must be verified against authoritative Rust handlers/types or OpenAPI rather than consumer assumptions. +- Browser exploration is not required in this system-level step. With automation=`auto`, Playwright CLI remains the preferred lightweight selector/trace investigation path for later epic-level work, with trace artifacts retained on failure. + +## Step 3: Testability and Risk Assessment + +### 🚨 Testability concerns + +1. **Deterministic control plane is not yet a complete test contract.** The repository has `crank-test-support`, PostgreSQL Testcontainers, in-memory runtime stores and some seeded UI scenarios, but the target architecture still needs reusable builders/fixtures for every aggregate, controllable clocks/UUIDs, lifecycle transitions, cleanup and production-size datasets. Without these, Tasks, retention, leases and parallel runs will be slow or flaky. **Required before Epic 4 qualification.** +2. **Fault injection is not an explicit shared facility.** We need deterministic doubles/proxies for DNS rebinding, redirects, partial/oversized bodies, upstream timeouts/resets, PostgreSQL/Valkey interruptions, worker crash points, telemetry endpoint outage/corruption and disk-full/fsync failures. Each injected fault must be named and observable. **Required before reliability/security evidence.** +3. **Time-dependent Task semantics need virtual-time seams.** Lease expiry, retry/backoff, deadlines, input-required timeout, 30-hour spool, 25-hour completeness and retention cannot depend on wall-clock sleeps. Ports for clock/scheduler and persisted timestamps must be controllable while production wiring remains monotonic/UTC-correct. **Required during foundation/Task implementation.** +4. **End-to-end observability assertions need queryable sinks.** The architecture defines IDs, traces, GlitchTip, local records and metrics, but tests need bounded APIs/helpers to query local history, captured OTLP/Sentry envelopes, Prometheus exposition and Grafana provisioning by `request_id`/`trace_id`. Direct dependence on a live external GlitchTip is insufficiently deterministic. **Required before Epic 5.** +5. **Load generation must be independently measurable.** The built-in runner shares the host with the SUT in the reference profile; its own CPU/memory/network use, heartbeat and kill path must be measured separately so generator saturation cannot be misreported as product failure. A stub upstream and externally cross-checked reference load tool are required. **Required before Epic 6 evidence.** +6. **Release evidence needs executable provenance from the start.** Corpus/matrix/load/recovery/manual outputs must use stable schemas, content-addressed storage, deterministic commands and one-RC identity. Retrofitting this at Epic 8 risks unrepeatable or stale evidence. **Establish schemas and collectors in Epic 1, extend per epic.** +7. **Browser tests need parallel-safe state and selectors.** Existing Playwright coverage proves some flows, but production qualification requires API-first seeding, per-worker namespaces, self-cleanup, RU/EN coverage, stable role/test-id selectors and retained traces. Avoid UI setup for non-UI behavior. **Required before full manual/automated regression.** + +### ✅ Testability assessment summary + +- Hexagonal boundaries and framework-free core permit low-cost unit/property/state-machine tests and replaceable adapters. +- PostgreSQL is the single correctness authority and Valkey is explicitly rebuildable/optional, enabling PG-only reference assertions and differential cache tests. +- Existing `crank-test-support`, PostgreSQL 16 Testcontainers, runtime in-memory stores, Rust integration suites and Playwright tests provide a usable brownfield foundation. +- Typed errors, events, metric registry, identity conventions and immutable revisions create deterministic assertion surfaces. +- The OpenAPI NormalizedIR/ImportPlan pipeline, version-isolated MCP adapters and unified runtime execution path expose natural corpus, contract and differential-test boundaries. +- Quantified NFRs, immutable evidence artifacts and a fail-closed release manifest allow objective gates rather than subjective sign-off. + +### Architecturally Significant Requirements (ASRs) + +| ASR | Classification | Test-design consequence | +|---|---|---| +| PostgreSQL-authoritative Tasks with transactional dispatch, CAS leases and fencing | ACTIONABLE | Model/state-machine, crash-point, concurrency and real-PG tests; prove no stale terminal writes and explicit `outcome_unknown`. | +| Unified outbound pipeline with per-connection DNS/redirect policy and hard bounds | ACTIONABLE | Hermetic malicious-network lab; verify every ingress path uses identical policy. | +| Canonical W3C context across browser/MCP/runtime/worker and durable telemetry spool | ACTIONABLE | One cross-boundary golden E2E plus outage/replay/corruption/disk-capacity tests. | +| Immutable OpenAPI ParsedDocument→IR→Plan→Apply pipeline | ACTIONABLE | ≥50-spec corpus, metamorphic/determinism tests, transactional rollback and zero-silent-loss oracle. | +| Modern MCP adapters: stable N/N-1/N-2, Tools/Resources/Prompts and Tasks | ACTIONABLE | Protocol harness plus ≥3 real clients; adapter contract snapshots and negative negotiation tests. | +| Signed LoadAuthorizationPlan and isolated Load Runner | ACTIONABLE | Authorization/kill-switch tests and calibrated load/overload/soak evidence on reference hardware. | +| One migration authority, N/N-1 data compatibility, backup manifest and product-probe restore | ACTIONABLE | Upgrade/rollback matrix and three independent PITR restores measuring RPO/RTO. | +| One-time admin bootstrap, fail-closed security, encrypted secrets and air-gap bundle | ACTIONABLE | Abuse/negative tests, secret canaries, configuration matrix, SAST/SCA/container scans and default-deny egress test. | +| Alpine/vanilla JS remains the UI model | FYI | Use current bundle/build conventions; test async revision guards, safe DOM sinks, localization and accessibility without framework migration. | +| Single-instance drain/restart; HA/rolling upgrades deferred | FYI | Qualify claimed topology only and explicitly prevent HA claims in docs/evidence. | + +### Risk register + +Scoring is Probability (P) × Impact (I), each 1–3. Scores ≥6 are high and require owned mitigation; score 9 blocks release while open. + +| ID | Category | Risk | P | I | Score | Mitigation / evidence | Owner | Timeline | +|---|---|---|---:|---:|---:|---|---|---| +| R-001 | TECH | Brownfield regressions remain hidden because current core and UI are not fully manually/automatically baselined. | 3 | 3 | 9 | Capability inventory, characterization tests and complete guided baseline before semantic changes. | QA Lead + Core | Epic 1, before feature branches | +| R-002 | DATA | OpenAPI normalization silently drops or mis-maps real constructs, security or schema branches. | 3 | 3 | 9 | Versioned ≥50-spec corpus, finding oracle, round-trip/metamorphic tests, immutable preview and atomic apply rollback. | Import Lead | Epic 2 gate | +| R-003 | TECH | Concurrent workers duplicate side effects or accept stale writes after crash/lease expiry. | 3 | 3 | 9 | Model-based Task lifecycle, deterministic crash points, PG contention suite, fencing/idempotency invariants and reconciliation evidence. | Task Lead | Epic 4 gate | +| R-004 | SEC | SSRF, redirect/proxy bypass or secret leakage crosses the closed-contour boundary. | 3 | 3 | 9 | Malicious DNS/HTTP lab on every execution path; secret canaries across logs/traces/metrics/UI/artifacts; fail-closed configuration tests. | Security Owner | Per-epic + RC security gate | +| R-005 | OPS | Trace delivery outage, spool overflow/corruption or unsafe replay makes UI/GlitchTip correlation incomplete while UI claims success. | 2 | 3 | 6 | 30 h capacity, 24 h outage/replay, corruption and disk-pressure tests; loss records; golden trace query/deep-link E2E. | Observability Lead | Epic 5 gate | +| R-006 | PERF | Reference workload breaches latency/success due to DB contention, metric cardinality, telemetry or load-runner interference. | 3 | 3 | 9 | Calibrated stub, baseline/telemetry differential, production-size query plans, 100/250 RPS runs, generator resource accounting and ceilings. | Performance Owner | Epics 5–6; RC repeat | +| R-007 | SEC | Admin/session/bootstrap/recovery paths allow unauthorized state changes or metadata disclosure. | 2 | 3 | 6 | Auth state-machine tests, CSRF/CORS/cookie/proxy/TLS matrix, rate-limit tests, cross-scope negative corpus and recovery revocation proof. | Security + Admin API | Epic 7 gate | +| R-008 | OPS | Upgrade, rollback or PITR restore yields schema/artifact/key mismatch despite services becoming healthy. | 2 | 3 | 6 | N/N-1 expand/migrate/contract matrix, consistency manifest and three timed restores ending in encrypted-auth MCP probe. | Release/SRE | Epic 7 gate | +| R-009 | BUS | Resources, Prompts or current/previous MCP clients observe inconsistent catalog revisions or unsupported semantics. | 2 | 3 | 6 | Immutable catalog snapshots, adapter golden contracts, negotiation/change-signal tests and ≥3-client protocol matrix. | MCP Lead | Epic 3 gate | +| R-010 | OPS | Built-in load test can overload the control plane, escape its target scope or fail to stop. | 2 | 3 | 6 | Signed authorization bounds, reserved control capacity, target allowlist, heartbeat/watchdog, Unix kill socket and forced-stop chaos tests. | Load Lead + Security | Epic 6 gate | +| R-011 | DATA | Metrics/business rollups double count or expose high-cardinality/user identifiers. | 2 | 3 | 6 | Typed registry lint, label allowlist, idempotent rollup replay/differential tests, cardinality budget and exemplar validation. | Metrics Lead | Epic 5 gate | +| R-012 | TECH | Flaky or over-broad E2E suite delays feedback and hides low-level defects. | 2 | 2 | 4 | Test pyramid, per-worker data, network-first waits, no hard sleeps, burn-in/quarantine policy and trace-on-failure. | QA Automation | Continuous | +| R-013 | OPS | Evidence from different builds/configurations is combined or signed despite being stale/incomplete. | 2 | 3 | 6 | Schema-validated manifest binds RC/image/config/topology/commands/digests; freshness checks and fail-closed verifier. | Release Owner | Framework Epic 1; final Epic 8 | +| R-014 | SEC | Air-gapped deployment contains vulnerable/untrusted images or performs undeclared egress. | 2 | 3 | 6 | Digest/signature/SBOM/license verification, fresh install/N-1 upgrade in disconnected lab and default-deny egress capture. | Supply-chain Owner | Epic 7/8 | +| R-015 | OPS | 30-day burn-in exposes leaks or corruption too late for planned publication. | 2 | 3 | 6 | Begin continuous nightly/burn-in runs as soon as foundations exist; 72 h soak precheck; trend memory, handles, queues, spool and DB growth. | QA/SRE | Start Epic 4; final Epic 8 | + +### NFR validation plan + +| Category | Planned evidence sources | Threshold status | +|---|---|---| +| Security / privacy | Rust negative integration tests, malicious upstream lab, auth/browser E2E, secret-canary scans, SAST/SCA/SBOM/container/config scans, air-gap egress capture | Defined; no Critical/High and all default-deny/leak invariants are release blocking. | +| Performance / scalability | Criterion/k6-equivalent external calibration plus built-in runner, Prometheus snapshots, production-size DB plans, telemetry-on/off differential, 100/250 RPS and 128/10k concurrency variants | Defined numerically; hardware/topology fixed by Reference Deployment. | +| Reliability / recovery | Task model/crash tests, kill/restart/drain chaos, telemetry outage/replay, N/N-1 upgrade/rollback, three WAL/PITR restores with real MCP probe, 72 h soak and 30-day burn-in | Defined numerically; exact internal lease/poll tuning remains implementation-owned within limits. | +| Observability | Correlation contract tests, golden UI→API/MCP→runtime→upstream→history→GlitchTip flow, OTLP/Sentry capture, Prometheus schema/cardinality lint, Grafana provisioning/alert-rule tests | Defined; 100% identity/trace and delivery/completeness/overhead budgets apply. | +| Maintainability / compatibility | `cargo fmt/clippy/test`, architecture dependency checks, unsafe/panic lint, wire round-trips, OpenAPI corpus, MCP/client/browser/PG/Valkey matrices, localization lint and regression-per-defect rule | Version matrix is frozen at feature freeze; no unsupported compatibility claim before evidence. | +| Compliance / release provenance | Content-addressed raw evidence, JSON-Schema manifest validation, signature/trust/rotation/revocation tests, RC/config/topology digest checks and manual sign-off | Defined as fail-closed Habr/production release gate; no waivers for mandatory capabilities or Critical/High failures. | + +### Highest-priority mitigation order + +1. Close R-001 with an immutable current-product baseline and establish reusable deterministic fixtures/evidence schemas. +2. Develop R-002, R-003 and R-004 tests alongside OpenAPI, Task and outbound-security code; these are score-9 design drivers, not post-implementation QA. +3. Build observability and performance measurement seams before optimizing (R-005/R-006/R-011), including independent load-generator accounting. +4. Exercise upgrade/restore/security/offline paths continuously before the final RC (R-007/R-008/R-014), and start long-duration testing early enough to absorb R-015. +5. The release gate remains FAIL while any score-9 risk is open or required evidence cannot be tied to the same immutable RC. + +## Step 4: Coverage Plan and Execution Strategy + +### Coverage matrix + +The indicated level is the primary oracle. Defense-in-depth E2E is reserved for cross-boundary user outcomes; it does not repeat every branch already proven by unit/integration tests. + +| ID | Requirements / risks | Atomic validation scenario | Primary level / tool | Priority | Planned automated cases | +|---|---|---|---|---|---:| +| CP-01 | FR-1..6, R-001 | Characterize existing manual REST Operation → test → publish Agent → MCP discovery/call → history, including validation/upstream/store failures | API integration + 2 golden Playwright/MCP E2E | P0 | 30–45 | +| CP-02 | FR-1..6, AR-2/16/17 | Immutable revisions, publish snapshot atomicity, config bounds and migration compatibility/locking | Rust unit + PostgreSQL integration | P0 | 35–55 | +| CP-03 | FR-4/6, NFR-S1/S7 | Approval/idempotency state machines, deduplication, expiry, scope isolation and fail-closed store outage | Rust model/property + PostgreSQL contention | P0 | 25–40 | +| CP-04 | FR-5, NFR-S2 | Secret create/use/rotate/revoke lifecycle; ciphertext versioning; canary absent from every output channel | API/integration + artifact scanner | P0 | 25–40 | +| CP-05 | FR-7..12, R-002 | Parse/normalize/preview deterministic across YAML/JSON OAS 3.0/3.1/Swagger 2; explicit unsupported findings and zero silent loss | Rust corpus/property tests | P0 | 150–250 corpus assertions | +| CP-06 | FR-7..12 | Upload/encoding/size/ref limits, conflict selection, explicit partial mode and all-or-nothing apply/retry | API + PostgreSQL integration | P0 | 35–55 | +| CP-07 | FR-7..12 | User uploads, reviews findings, edits, applies and publishes representative OpenAPI specs | Playwright critical journey (RU/EN) | P1 | 8–14 | +| CP-08 | FR-013..16, NFR-C2 | MCP initialize/negotiation, list/call Tools, pagination/change signals, stable/N-1/N-2 wire contracts | Protocol harness + snapshots | P0 | 45–70 | +| CP-09 | FR-17..18 | Static/dynamic Resource draft/publish/list/read/templates; read-safe pinned Operation and sensitivity enforcement | Rust/API contract + MCP harness | P0 | 35–55 | +| CP-10 | FR-19..20 | Prompt draft/publish/list/get/render/completion; DAG validation, argument errors and side-effect freedom | Rust unit/property + MCP harness | P0 | 30–45 | +| CP-11 | FR-013..20, R-009 | ≥3 representative clients discover/use identical immutable catalog revisions across negotiated MCP versions | Cross-client E2E matrix | P0 | 18–30 | +| CP-12 | FR-21..26, R-003 | Task lifecycle model permits only legal/versioned/idempotent transitions and immutable terminal result | Rust model/property tests | P0 | 50–80 | +| CP-13 | FR-21..26 | Transactional enqueue, bounded SKIP LOCKED claim, CAS lease/fencing, retries, cancellation/input and `outcome_unknown` under contention/crash | PostgreSQL integration/chaos | P0 | 45–70 | +| CP-14 | FR-21..26, NFR-P2/R5 | Sync/background fairness, 128 active + 10k queue, deadline propagation, overload/retry guidance and ≤60 s recovery | Load/concurrency harness | P0 | 12–20 profiles | +| CP-15 | FR-21..26 | Client starts/observes/cancels/resumes a Task through disconnect/restart; fallback on revisions without Tasks | MCP E2E | P1 | 10–16 | +| CP-16 | FR-27..31, R-005 | Canonical IDs/W3C propagation through browser/Admin/MCP/runtime/upstream/worker retry/history; safe boundary errors | Rust/API contracts | P0 | 30–45 | +| CP-17 | FR-27..31 | Golden request is searchable/copied in UI and deep-links to captured GlitchTip trace; loss record suppresses false claim | Playwright + MCP + telemetry-sink E2E | P0 | 8–12 | +| CP-18 | FR-27..31, NFR-O2/O3 | Telemetry outage, 30 h spool sizing, encrypted persistence, restart, replay ordering/idempotency, corruption/disk pressure and overhead | Soak/chaos/performance | P0 | 15–25 profiles | +| CP-19 | FR-32..35, R-011 | Metric registry names/types/units/labels/buckets stable; cardinality rejects IDs/arbitrary values | Rust unit/schema lint | P0 | 25–40 | +| CP-20 | FR-32..35 | Product events/UTC rollups exactly-once under replay; Prometheus exposition and exemplar correlation agree with source records | PostgreSQL/API differential | P0 | 25–40 | +| CP-21 | FR-32..35 | Grafana dashboards/recording rules/SLO denominators and fast/slow burn alerts provision and fire against synthetic series | Config-as-code test + Prometheus/Grafana integration | P1 | 18–28 | +| CP-22 | FR-36..40, R-010 | Load plan validates/authenticates target and ceilings; start/status/stop/forced kill are safe and auditable | Rust/API integration | P0 | 25–40 | +| CP-23 | FR-36..40, NFR-P1/P4 | Built-in runner results cross-check external generator at 100 RPS/30 m and 250 RPS/5 m; error classes and percentiles are accurate | Calibrated performance test | P0 | 8–12 profiles | +| CP-24 | FR-36..40 | Operator launches RPS/DAU run, sees live status, safely stops and inspects correlated results | Playwright critical journey | P1 | 6–10 | +| CP-25 | FR-41..45, R-007 | Fresh bootstrap/login/session/recovery and TLS/proxy/cookie/CSRF/CORS/default-deny matrix | API/browser security suite | P0 | 35–55 | +| CP-26 | FR-41..45, R-008 | Fresh install, preflight, N/N-1 migration, drain/restart, rollback compatibility and three PITR restores ending in real encrypted-auth MCP probe | Deployment/recovery harness | P0 | 18–28 workflows | +| CP-27 | FR-41..45, R-014 | Signed digest-pinned offline bundle installs/updates in air gap; SBOM/license/signature valid and undeclared egress absent | Supply-chain/air-gap system test | P0 | 12–20 | +| CP-28 | FR-46..50 | Complete regression, OpenAPI/MCP/client/browser/PG/Valkey matrices, static/security scans and production-size dataset | CI matrix | P0 | Matrix-defined | +| CP-29 | FR-49, R-015 | 72 h soak and non-accelerable 30-day ≥1M-event burn-in show no leak, corruption, queue/spool drift or SLO breach | Long-duration system test | P0 | 2 qualification runs + probes | +| CP-30 | FR-51..53 | Fresh user/operator follows quickstart, upgrade, recovery, alert and incident runbooks in connected and air-gapped profiles | Guided manual + docs executable checks | P1 | 20–35 checks | +| CP-31 | FR-54, R-013 | Manifest rejects missing/stale/cross-RC/digest-mismatched/untrusted/revoked evidence and accepts only complete signed RC | Rust/CLI schema and signature tests | P0 | 30–45 | +| CP-32 | NFR-C1/C3/C4, AR-31..34 | Dependency direction, MSRV, unsafe/panic rules, wire compatibility, Gitea CI and simultaneous RU/EN strings | Static/contract CI | P1 | 15–25 gates | +| CP-33 | UX/accessibility | Loading/error/empty/stale-response states, keyboard/focus/labels, responsive critical screens and safe DOM sinks | Component/Playwright + axe-equivalent | P1 | 30–50 | +| CP-34 | Exploratory | Unscripted real OpenAPI/client combinations, operator diagnostics and usability under partial failures | Time-boxed exploratory/manual | P2 | 15–25 charters | + +### NFR coverage and evidence artifacts + +| NFR category | Validation scenarios | Evidence consumed later by `nfr-assess` | +|---|---|---| +| Security/privacy | CP-03/04/19/25/27/28 plus malicious-network and secret-canary suites | JUnit/JSON results, scanner SARIF, SBOM/signature reports, egress capture, redaction canary report and config digest | +| Performance/scalability | CP-14/18/20/21/23/28/29 on the checksummed Reference Workload | Raw request samples/histograms, generator and SUT resource series, Prometheus snapshot, query plans, run metadata and threshold verdict JSON | +| Reliability/recovery | CP-02/12/13/14/18/26/29 | State-model coverage, crash schedule/seed, Task invariants, telemetry accounting, upgrade/rollback logs, BackupManifest, measured RPO/RTO and product-probe output | +| Observability | CP-16..21 | Trace/ID correlation map, captured redacted envelopes, spool ledger/loss records, metric schema/cardinality report, dashboard/alert test results and overhead differential | +| Maintainability/compatibility | CP-01/05/08/11/28/31/32 | Rust/UI coverage, lint/architecture reports, corpus and protocol matrices, browser traces, signed manifest verifier results and regression index | +| Release provenance/manual quality | CP-28..31/34 | Content-addressed evidence tree for one RC, signed manifest, manual checklist with zero blocked/not-run, docs execution logs and defect disposition | + +No critical NFR threshold is UNKNOWN. Feature-freeze versions, image digests and implementation tuning values are controlled gate inputs; absence at their freeze point blocks the corresponding qualification run. + +### Execution strategy + +- **PR (target ≤15 minutes, fail fast):** formatting/lints/architecture checks; all changed-crate unit/property tests; targeted PostgreSQL integration; contract/corpus delta; P0 API/MCP smoke; Chromium critical UI smoke; manifest/schema tests. A full small suite may replace selection only while it stays below 15 minutes. +- **Nightly:** complete Rust and PostgreSQL/Valkey suites; full OpenAPI corpus; MCP adapters and representative-client matrix; Chromium full UI plus Firefox/WebKit critical paths; security negative suite; production-size dataset smoke; telemetry outage/replay short profile; flaky-test burn-in. +- **Weekly:** full browser/client matrices, dependency/container/security scans, high-contention Task chaos, migration/rollback, dashboard/alert integration, performance baseline and 100/250 RPS qualification rehearsal, spool/disk-pressure and backup/restore rotation. +- **Release candidate:** immutable RC only; all automated/manual matrices, three restore runs, air-gap fresh/N-1 flows, 72-hour soak, then non-accelerable 30-day burn-in. Any code/config/topology change creates a new RC and restarts freshness-dependent evidence. + +### Resource estimates + +These ranges estimate design and implementation of the automated/manual test capability and qualification assets, not feature development or the unavoidable 30-day wall-clock gate. + +| Priority | Estimated effort | +|---|---:| +| P0 | ~900–1,400 engineering hours | +| P1 | ~300–520 engineering hours | +| P2 | ~80–160 engineering hours | +| P3 / optional benchmarks | ~30–70 engineering hours | +| **Total** | **~1,310–2,150 engineering hours** | + +With 3–4 effective engineers spanning QA automation, Rust/backend, SRE/performance and security, implementation is roughly **12–22 working weeks**, followed/overlapped by the mandatory 30-day burn-in. A single engineer should plan roughly **8–13 person-months**; long-running environments and manual qualification add calendar time but not equivalent active hours. + +### Quality gates + +- P0 pass rate is **100%** on every applicable PR and RC; no quarantine or waiver for mandatory P0 release evidence. +- P1 pass rate is **≥95%** for development/nightly signal and **100% for RC scenarios mapped to FR-1..FR-54 or critical user journeys**. Any remaining P1 failure requires explicit non-release classification; it cannot mask an NFR or mandatory capability. +- All score-9 risks must be mitigated/closed; every score 6–8 risk needs verified mitigation and no expired waiver. Critical/High security risks cannot be waived for release. +- Rust line coverage target is **≥80% workspace-wide**, **≥90% for safety/domain state-machine crates**, with branch/property/mutation evidence on Task, import, auth, admission, redaction and manifest logic. Coverage percentage never substitutes for requirement traceability. +- 100% of FRs, NFR categories and ASRs map to planned scenarios and later immutable evidence; no manual item may be blocked or not-run. +- OpenAPI corpus has zero silent loss and ≥95% actionable Drafts; all required MCP/client/browser/database/cache matrices pass. +- All stated performance, availability, recovery, observability and spool thresholds must have raw machine-readable evidence from the same RC/reference topology. +- Full NFR PASS/CONCERNS/FAIL decision is intentionally deferred to `bmad-testarch-nfr` after implementation evidence exists. +- Habr/production release gate is fail-closed on missing/stale/cross-RC evidence, invalid signature/schema/digest, any open Critical/High defect or any mandatory SLO failure. + +## Step 5: Final Outputs and Validation + +- **Mode:** System-Level; resolved execution mode: sequential. +- **Architecture output:** `_bmad-output/test-artifacts/test-design-architecture.md`. +- **QA output:** `_bmad-output/test-artifacts/test-design-qa.md`. +- **BMAD handoff:** `_bmad-output/test-artifacts/test-design/crank-handoff.md`. +- **Validation:** workflow checklist reviewed; template-required sections, risk IDs R-001..R-015, priority separation, NFR planning boundary, PR/nightly/weekly strategy, ranges, fenced code and placeholders checked. No browser session was opened and no temporary artifact exists outside the test-artifacts tree. +- **Open controlled inputs:** feature-freeze MCP revisions and image digests, implementation tuning values, named owners where the repository does not identify a person, and provision of reference/performance/security environments. Missing any of these at its freeze/qualification point is a blocker, not an implicit default. +- **Next workflow:** epic-level Test Design or ATDD for the first implementation story; final NFR verdict waits for implementation evidence. + +--- + +# Epic-Level Test Design Progress — Epic 1 + +## Run 2 / Step 1: Mode and Prerequisites + +- **Mode:** Epic-Level. +- **Scope:** Epic 1 — «Надёжный базовый REST → MCP продукт»; выбран первым по утверждённому dependency order. +- **Reason:** system-level TD завершён, полный Epic 1 со Story и acceptance criteria доступен в `_bmad-output/planning-artifacts/epics.md`. +- **Architecture context:** Architecture Spine, PRD, project context and system-level test-design outputs are available. +- **Prerequisite result:** PASS; дополнительных материалов от пользователя не требуется. + +## Run 2 / Step 2: Epic 1 Context and Existing Coverage + +- **Configuration:** Playwright Utils enabled; Pact.js Utils disabled; Pact MCP disabled; browser automation `auto`; detected stack `fullstack`; artifacts root `_bmad-output/test-artifacts`. +- **Loaded product scope:** Epic 1 Stories 1.1–1.16 with all acceptance criteria; PRD/Architecture Spine/project context; completed system architecture/QA TD and handoff. +- **Epic requirements:** FR-1..FR-6, FR-27, FR-32, FR-33, FR-43, FR-45 and FR-46; inherited security, performance, reliability, observability and compatibility NFRs. +- **Integration boundaries:** Community scope validator/docs; typed configuration and process startup; PostgreSQL migration authority; Admin/MCP identity propagation; metric registry; Operation/Agent lifecycle; runtime/REST adapter; DNS/network boundary; Auth Profiles/machine/master keys; Admin auth/session; approvals/idempotency; history/usage/CSV/retention; real MCP onboarding. + +### Existing coverage and reusable patterns + +- `crank-test-support` supplies PostgreSQL 16 Testcontainers and unique schemas; registry, Admin API and MCP suites already use real PostgreSQL. +- Existing Admin API integration proves create/test/publish/archive Operations, Agent binding/publish/unpublish/archive, Auth Profile import/rotation, keys/revocation, Logs/Usage and request context. +- MCP integration proves published-tool discovery/call, catalog refresh/scope, direct/search behavior, transport negotiation/session, approvals, rate limits, request/trace context and uncertain approval recovery. +- Runtime tests cover confirmation single-use, idempotency contention/conflict, fail-closed coordination and uncertain outcomes; REST adapter tests cover private-target defaults, redirects and response size limits. +- `crank-metrics`, `crank-observability` and `crank-trace` have contract tests for closed labels, cardinality, redaction, propagation, Prometheus protection, OTLP config and history-loss signals. +- Existing Playwright specs cover Operations, Agents, keys, secrets, login, Logs/Usage and observability, but use Chromium only, one worker, retries only in CI and `trace: on-first-retry`. + +### Confirmed coverage gaps + +1. No executable Capability Inventory schema/validator/evidence mapping or frozen exploratory baseline for Story 1.1–1.2. +2. No demonstrated single `crank-config` authority covering every process, alias/deprecation conflict, generated docs and boundary scan (1.3). +3. Current migration coverage does not yet prove the full append-only checksummed authority, legacy consolidation, concurrent migrator/failure/resume and N/N-1 contract (1.4). +4. Correlation tests exist, but the full 100% UI/Admin/MCP/runtime/history contract and hostile header matrix are incomplete (1.5). +5. Metrics foundation exists, but million-distinct-value cardinality budget, direct-declaration workspace scan and measured overhead remain to prove (1.6). +6. Operation/Agent happy lifecycle exists, while immutable revision conflict/YAML semantic roundtrip/stale UI/cross-scope/production-size discovery cases remain incomplete (1.7/1.13). +7. Outbound tests do not yet form the complete DNS-rebinding/actual-connect/IPv4+IPv6/redirect credential stripping/proxy/encoded-host/deadline/concurrency matrix (1.9). +8. Auth Profile/key basics exist; one-time UI disclosure persistence, wrong-purpose/cross-scope/cache-loss matrix and master-key epoch/re-encryption/crash/abort/revocation lifecycle are incomplete (1.10–1.11). +9. Login/rate-limit coverage exists, but bootstrap race/replay, session fixation, CSRF/Origin/trusted-proxy/TLS, recovery misuse and password-rotation revocation need system proof (1.12). +10. Approval coverage is substantial; canonical full-scope fingerprint, conditional races, exact single-use dispatch and store-readiness coupling need explicit real-PG assertions (1.14). +11. History/Usage basic flows exist; bounded preview redaction, CSV injection, UTC boundary/no-double-count, retention and 1M-record/≤2s evidence are missing (1.15). +12. Getting Started checklist and first-call authoritative/resumable/accessibility flow are not present (1.16). +13. Browser suite is not parallel-safe by configuration and does not yet retain trace on first failure; this blocks the eventual fast PR target until per-worker data/ports exist. + +### Knowledge and exploration + +- Applied required epic-level risk governance, probability-impact, test-level, priority and NFR guidance, plus prior system TD. +- Contract testing remains relevant for Admin/MCP/runtime boundaries; provider Rust handlers/types are authoritative. +- `playwright-cli` is not installed and no bound-browser MCP is configured, so browser exploration was skipped per workflow fallback. No browser session or exploration artifact was created. +- **Loaded-input result:** complete; no user-supplied material is missing. + +## Run 2 / Step 3: Epic 1 Risk and NFR Planning + +### Epic 1 risk register + +| ID | Category | Real failure risk | P | I | Score | Mitigation / evidence | Owner | Timeline | +|---|---|---|---:|---:|---:|---|---|---| +| E1-R-001 | TECH | Capability Inventory/baseline marks gaps or flaky/manual flows as production-ready, allowing regressions to propagate through every later epic. | 3 | 3 | **9** | Strict schema/validator negative matrix, checksum baseline, traceable automated/manual evidence and blocked Critical/High flows. | QA Lead + Release | Stories 1.1–1.2 | +| E1-R-002 | OPS | Multiple env readers/defaults diverge across Admin/MCP/worker, causing unsafe or unreproducible startup. | 3 | 3 | **9** | One typed schema, cross-process golden config, alias-conflict/redaction/boundary tests and fingerprint comparison. | Config/Core Lead | Story 1.3 | +| E1-R-003 | DATA | Migration authority changes baseline, races, partially applies or prevents N/N-1 recovery. | 2 | 3 | **6** | Fresh/baseline/current/concurrent/failure PG matrix, immutable checksum and expand/migrate/contract fixtures. | Registry Lead | Story 1.4 | +| E1-R-004 | OPS | Request/Trace IDs are missing, attacker-controlled, conflated or lost between UI/Admin/MCP/runtime/history. | 2 | 3 | **6** | Boundary contract/property tests plus one real UI/Admin/MCP/upstream/history correlation chain at sampling off/on. | Observability Lead | Story 1.5 | +| E1-R-005 | PERF | Dynamic metric labels/cardinality or instrumentation overhead exhausts resources before later observability work. | 2 | 3 | **6** | Compile/API restriction, workspace scan, million-value stress, schema snapshots and overhead baseline. | Metrics Lead | Story 1.6 | +| E1-R-006 | DATA | Editing/importing/archiving an Operation mutates published Agent behavior or historical evidence. | 2 | 3 | **6** | Revision/state model, PG conflicts, YAML semantic roundtrip and Agent snapshot regression. | Operation Lead | Story 1.7 | +| E1-R-007 | TECH | Admin Test and MCP execute different targets/pipelines or classify the same failure differently. | 3 | 3 | **9** | Table-driven parity contracts for success/all stages, dependency-boundary guardrails and outbound call counters. | Runtime Lead | Story 1.8 | +| E1-R-008 | SEC | DNS/redirect/proxy/header/retry bypass enables SSRF, credential forwarding or resource exhaustion. | 3 | 3 | **9** | Hermetic malicious-network matrix against both Admin and MCP paths; actual-connect validation and no-secret outputs. | Security + REST Adapter | Story 1.9 | +| E1-R-009 | SEC | Credentials/master-key material leak, wrong-purpose/cross-scope keys work, or rotation makes stored secrets unreadable. | 3 | 3 | **9** | Secret canaries, full credential matrix, ciphertext corruption and crash-resumable epoch rotation with verified revocation. | Security + Registry | Stories 1.10–1.11 | +| E1-R-010 | SEC | Remote bootstrap takeover, session fixation, CSRF/proxy spoofing or recovery bypass compromises Admin UI. | 2 | 3 | **6** | Auth state-model/concurrency tests, web-security config matrix, browser flow and local-only recovery proof. | Auth/Security Lead | Story 1.12 | +| E1-R-011 | DATA | Agent publication/cache exposes Draft/foreign/stale Tools or changes exact published versions. | 2 | 3 | **6** | Atomic PG publish/conflict, exact-version snapshots, cache-loss differential, scope negatives and dataset discovery test. | Agent/MCP Lead | Story 1.13 | +| E1-R-012 | BUS | Approval races/replay/retries produce duplicate or unauthorized side effects or falsely claim exactly-once. | 3 | 3 | **9** | Real-PG concurrency model, single-use admission, scope fingerprint, store-outage and uncertain-dispatch assertions. | Approval/Runtime Lead | Story 1.14 | +| E1-R-013 | SEC | History/CSV/UI exposes sensitive data or foreign metadata; aggregation double-counts and large datasets time out. | 2 | 3 | **6** | Redaction/property/cross-scope/CSV injection/UTC boundary/retention tests and 1M-record query plans/UI timings. | History/Admin Lead | Story 1.15 | +| E1-R-014 | BUS | Onboarding uses browser flags or test bypass, loses one-time key, duplicates mutations or never proves a real MCP call. | 2 | 2 | 4 | Server-authoritative checklist, real public endpoint E2E, refresh/tab/stale/lost-key/recovery and accessibility/usability run. | Product/UI Lead | Story 1.16 | +| E1-R-015 | TECH | Serial, shared-port/state browser tests mask races and cannot meet PR feedback goals. | 2 | 2 | 4 | Per-worker data/ports, API-first fixtures, trace-on-failure, sharding and deterministic burn-in before raising workers. | QA Automation | Epic 1 continuous | + +### NFR planning for Epic 1 + +| Category | Applicable threshold / invariant | Planned evidence source | Status | +|---|---|---|---| +| Security/privacy | Default deny; no foreign metadata; secrets encrypted/non-returnable and absent from logs/traces/metrics/reports/DOM; SSRF policy on every actual connection; no Critical/High findings | Rust/API/MCP security suites, malicious network, secret-canary artifact scan, Playwright auth/key flows, SAST/SCA | Defined; P0 | +| Performance/scale | Tool discovery ≤150 ms p95 at 200 Agents/2,000 Operations; Logs/Usage interactive ≤2 s p95 at 1M history records; bounded resource use/cardinality | Criterion/external timing harness, PG plans, browser timings, metric-series/heap/CPU measurements | Defined except exact metric series budget | +| Reliability/data | Published Operation/Agent revisions, approvals and config changes durable; migration transactional/checksummed; safety stores fail closed | PostgreSQL contention/failure/restart tests, checksum audit, cache-loss differential and execution call counters | Defined invariants | +| Observability | 100% Epic 1 ingress and Execution/history records have separate Request/Trace IDs; bounded labels; no secret payloads | Correlation contract/E2E, persistence queries, metric schema/cardinality and redaction reports | Defined | +| Compatibility/maintainability | Rust/MSRV/boundaries unchanged; existing wire behavior retained; new user text RU+EN; regression per defect | `just verify`, boundary/health scripts, wire snapshots, localization/static checks, baseline inventory | Defined | +| UX/business | Fresh manual REST path reaches real first MCP call in ≤15 minutes; all async flows expose loading/error/empty/recovery and stale-response protection | Guided usability timing and real-stack Playwright RU/EN/accessibility suite | Defined | + +### Controlled UNKNOWN inputs + +- **Metric cardinality budget:** Story 1.6 says series count stays “in budget” but does not give a numeric maximum. Before Story 1.6 implementation, the Metrics owner must freeze per-process/per-metric series ceilings and measurement window; E1-R-005 remains open until then. +- **Session/bootstrap/backoff durations and history retention:** exact values are typed configuration decisions. Tests must validate declared bounds/defaults/precedence and boundary behavior; absence from the schema is a blocker under E1-R-002/E1-R-010/E1-R-013, but values are not guessed here. +- **Reference usability sample/protocol:** the ≤15-minute outcome is defined, while participant count and timing procedure must be frozen before Story 1.16 qualification; tracked under E1-R-014. + +### Highest-priority mitigation order + +1. E1-R-001 and E1-R-002 first: truthful baseline and one config contract are prerequisites for meaningful evidence from every later Story. +2. E1-R-003/004/005 establish durable schema, identity and metrics before capability state changes. +3. E1-R-006/007/008 lock immutable execution semantics and the outbound security boundary before adding credentials and Agents. +4. E1-R-009/010 close secret/admin takeover risks before production exposure. +5. E1-R-011/012/013 prove catalog, side-effect and diagnostic integrity; E1-R-014 validates first-user value only after those authoritative contracts exist. +6. Epic 1 gate is FAIL while any score-9 risk is open; implementation evidence, not existing partial tests, determines mitigation status. + +## Run 2 / Step 4: Epic 1 Coverage and Execution Plan + +### Atomic coverage matrix + +The primary level owns the detailed oracle. E2E validates only cross-boundary user outcomes and does not repeat domain branches. + +| Test group | Story | Atomic scenario / oracle | Primary level | Priority | Risk | New/extended cases | +|---|---|---|---|---|---|---:| +| E1-01 | 1.1 | Inventory schema accepts every required field/status and rejects duplicate/missing/unknown/broken evidence deterministically | Unit/CLI contract | P0 | E1-R-001 | 15–25 | +| E1-02 | 1.1 | Community scope positive/negative matrix includes target capabilities, rejects enterprise markers and explicitly scans untracked inputs | Python/unit + boundary CI | P0 | E1-R-001 | 10–18 | +| E1-03 | 1.2 | Inventory maps every existing UI/Admin/MCP flow and never promotes failed/flaky/skipped/manual-only/gap evidence | CLI/integration | P0 | E1-R-001 | 12–20 | +| E1-04 | 1.2 | Current REST Operation→test→publish→Agent→key→public MCP call→history passes with safe checksummed evidence | Real-stack API/MCP E2E | P0 | E1-R-001 | 3–6 | +| E1-05 | 1.2 | Bounded exploratory RU/EN pass captures loading/empty/error/recovery/stale/unsafe-output gaps with severity/owner | Guided manual/Playwright support | P1 | E1-R-001 | 10–16 charters | +| E1-06 | 1.3 | Typed config default/min/max/invalid/cross-field/unknown and alias precedence/conflict are identical across processes | Rust unit/property + app contract | P0 | E1-R-002 | 35–55 | +| E1-07 | 1.3 | Generated env/docs/effective fingerprint are stable; diagnostics redact every secret; direct env reads fail boundary scan | Snapshot/static/integration | P0 | E1-R-002 | 18–30 | +| E1-08 | 1.4 | Fresh, immutable baseline, sequential current, already-current and checksum mismatch states are deterministic and preserve data | PostgreSQL integration | P0 | E1-R-003 | 18–28 | +| E1-09 | 1.4 | Concurrent migrators, failed transaction, incompatible/partial legacy state and bounded resumable backfill fail safely | PostgreSQL contention/fault | P0 | E1-R-003 | 12–20 | +| E1-10 | 1.5 | Missing/malformed/oversized/multiple/untrusted IDs create separate UUIDv7 Request ID and valid W3C Trace ID with safe boundary response | Unit/API/MCP contract | P0 | E1-R-004 | 20–32 | +| E1-11 | 1.5 | System correlation overrides user mappings and persists through Admin/MCP/runtime/upstream/history for success/auth/retry/failure and sampling-off | Cross-boundary integration/E2E | P0 | E1-R-004 | 10–16 | +| E1-12 | 1.6 | Typed metric schema names/types/units/help/labels/buckets snapshot is closed; direct declarations/aliases fail workspace scan | Unit/static contract | P0 | E1-R-005 | 20–30 | +| E1-13 | 1.6 | Million distinct hostile values stay inside frozen series budget; exemplars do not alter aggregates; overhead is measured | Stress/benchmark | P0 | E1-R-005 | 8–14 profiles | +| E1-14 | 1.7 | Operation state/revision model rejects illegal/stale/cross-workspace mutations and keeps Published Version immutable | Unit/property + PostgreSQL | P0 | E1-R-006 | 30–45 | +| E1-15 | 1.7 | Draft test, publish/edit/archive, YAML semantic roundtrip/upsert/conflict/malformed/oversized and history preservation work through Admin API | API/PG integration | P0 | E1-R-006 | 25–40 | +| E1-16 | 1.7 | RU/EN lifecycle UI proves stale-response guards, confirmations, safe IDs and minimal immutable-publish/YAML journey | Playwright | P1 | E1-R-006 | 8–14 | +| E1-17 | 1.8 | Admin Draft and MCP exact Published snapshot enter one RuntimeExecutionRequest path and make only expected adapter calls | Rust/API/MCP integration | P0 | E1-R-007 | 18–28 | +| E1-18 | 1.8 | Success and schema/mapping/auth/persistence/adapter/upstream/runtime/timeout/cancel/uncertain failures have parity in stage/code/retryability/IDs | Table-driven contract | P0 | E1-R-007 | 25–40 | +| E1-19 | 1.8 | Architecture checks reject app/runtime/adapter/persistence dependency bypass through alias/re-export/helper | Static boundary tests | P0 | E1-R-007 | 8–14 | +| E1-20 | 1.9 | IPv4/IPv6 forbidden classes, encoded/embedded hosts, DNS rebinding and actual retry addresses are blocked before bytes leave | Malicious-network integration | P0 | E1-R-008 | 30–50 | +| E1-21 | 1.9 | Redirect hop revalidation/credential stripping, proxy env, reserved headers, byte/deadline/concurrency limits and write retry rules are fail closed | REST adapter + Admin/MCP contract | P0 | E1-R-008 | 30–45 | +| E1-22 | 1.10 | Auth Profile/key create/list/get/export/rotate/revoke enforce encryption, one-time disclosure, exact purpose/scope and immediate revocation/cache loss | API/PG/MCP security | P0 | E1-R-009 | 30–50 | +| E1-23 | 1.10 | RU/EN key UI does not restore raw secret via refresh/back/DOM/storage/telemetry and requires destructive confirmation | Playwright + artifact canary | P0 | E1-R-009 | 10–16 | +| E1-24 | 1.11 | Process fingerprint/epoch readiness, ciphertext version/integrity/corruption and non-secret backup reference behave safely | Rust/PG integration | P0 | E1-R-009 | 20–35 | +| E1-25 | 1.11 | Rotation preflight/re-encrypt/checkpoint/crash/resume/verify/promote/abort/old-key revoke is idempotent with concurrent writes | State-machine + PostgreSQL fault | P0 | E1-R-009 | 25–40 | +| E1-26 | 1.12 | Bootstrap one-time/race/replay, login constant shape/backoff, session entropy/rotation/expiry/revocation and password change are correct | Rust/API/PG concurrency | P0 | E1-R-010 | 30–50 | +| E1-27 | 1.12 | TLS/trusted proxy/spoofed headers/cookies/CSRF/CORS/hostile Origin and local recovery matrix is default deny | API/security integration | P0 | E1-R-010 | 25–40 | +| E1-28 | 1.12 | RU/EN browser login/logout/throttle/expiry/recovery states use shared guard and reveal no account/security details | Playwright | P1 | E1-R-010 | 10–16 | +| E1-29 | 1.13 | Agent draft/publish transaction, exact bindings/revision, concurrent conflict, pinning/unpublish/archive and stale search result preserve catalog | PostgreSQL + MCP integration | P0 | E1-R-011 | 30–45 | +| E1-30 | 1.13 | Cross-Agent/workspace/key scope and cache-loss differential expose no metadata; direct/search discovery ≤150 ms p95 at 200/2k | Security integration + performance | P0 | E1-R-011 | 20–30 + 4 profiles | +| E1-31 | 1.13 | RU/EN Agent UI displays exact Draft/Published/revision and handles conflicts/stale responses safely | Playwright | P1 | E1-R-011 | 8–14 | +| E1-32 | 1.14 | Canonical full-scope fingerprint deduplicates pending approval; concurrent decision/expiry/recovery permits one legal transition | Rust model + PostgreSQL race | P0 | E1-R-012 | 30–45 | +| E1-33 | 1.14 | Approval/key scope/replay/revalidation/store outage/idempotency mismatch and uncertain dispatch never produce duplicate/false exactly-once side effect | Runtime/MCP integration | P0 | E1-R-012 | 25–40 | +| E1-34 | 1.14 | RU/EN approval UI has safe summary/IDs, expiry/conflict/stale/confirmation states | Playwright | P1 | E1-R-012 | 8–12 | +| E1-35 | 1.15 | History redaction/bounds/UTF-8 marker/persistence-loss metric and cross-scope filters/details are correct | Property + API/PG | P0 | E1-R-013 | 25–40 | +| E1-36 | 1.15 | UTC ranges/percentiles/no overlap, CSV formula escaping/limits and retention preserve audit/aggregates/evidence | Unit/API/PG integration | P0 | E1-R-013 | 20–35 | +| E1-37 | 1.15 | 1M-record plans and Logs/Usage UI meet ≤2 s p95 with pagination, stale guards and RU/EN states | Performance + Playwright | P0 | E1-R-013 | 6 profiles + 8–12 | +| E1-38 | 1.16 | Server-authoritative checklist derives each step, survives refresh/workspace/tab/revision changes and never duplicates publish/key creation | API/component/Playwright | P1 | E1-R-014 | 18–30 | +| E1-39 | 1.16 | Fresh user reaches first real public MCP call ≤15 min; lost/revoked key and validation/auth/upstream failure recover safely | Real-stack Playwright + guided usability | P1 | E1-R-014 | 8–14 + usability sample | +| E1-40 | 1.16 | Keyboard/focus/screen-reader/reduced-motion, RU/EN and bounded ProductEvent denominators/opt-in pass | Accessibility/component/API | P1 | E1-R-014 | 15–25 | +| E1-41 | All | Existing test fixtures are deterministic, isolated and traceable; selected Playwright suites pass repeated burn-in without order/state dependence | Test-quality audit/burn-in | P1 | E1-R-015 | 8–12 harness checks | + +### NFR evidence artifacts + +| Category | Coverage groups | Evidence for later NFR assessment | +|---|---|---| +| Security/privacy | E1-10/11, E1-20..28, E1-30, E1-32..37 | JUnit/JSON, malicious-network capture, secret-canary scan, web-security matrix, SAST/SCA and browser traces | +| Performance/scale | E1-13, E1-30, E1-37 | Metric-series/CPU/memory report, raw discovery/UI timings, PG query plans and checksummed dataset/topology | +| Reliability/data | E1-08/09, E1-14/15, E1-24/25, E1-29, E1-32/33/35/36 | Migration/checksum logs, state-model/concurrency seeds, call counters, ciphertext/rotation audit and cache-loss differential | +| Observability | E1-10..13, E1-18, E1-35 | Correlation map, persistence queries, trace capture, metric schema/cardinality and redaction/history-loss reports | +| Compatibility/maintainability | E1-01..07, E1-19, E1-41 | Inventory/boundary/`just verify` results, wire/config snapshots, test-quality and flake report | +| UX/business | E1-05/16/23/28/31/34/37..40 | Playwright traces/screens, accessibility report, RU/EN coverage and timed usability protocol/results | + +### Execution strategy + +- **PR, target ≤15 minutes:** all changed-crate unit/property/static tests; targeted real-PG/API/MCP integration; inventory/scope/config/boundary contracts; changed Playwright spec plus shared auth/API smoke. Run all functional coverage when it remains within the target; otherwise select by changed contract and always include its P0 boundary cases. +- **Nightly:** full Epic 1 Rust/PG/Valkey/Admin/MCP suites, all current Chromium Playwright, full security negative subset, correlation chain, million-value cardinality stress, migration/rotation/approval contention and repeated flake burn-in. +- **Weekly:** malicious-network matrix, production-size 200/2k/1M performance profiles, browser security configuration matrix, master-key crash/recovery, fresh-user guided usability/accessibility and full exploratory baseline refresh where changes require it. +- **Epic qualification:** all 1.1–1.16 acceptance criteria traced; complete Inventory and manual checklist; all P0/P1 evidence bound to one Epic candidate digest. Full product RC soak/burn-in remains Epic 8, not duplicated here. + +### Incremental resource estimate + +Estimate covers closing Epic 1 test gaps and integrating evidence, reusing existing suites. It excludes feature implementation and later full-product qualification. + +| Priority | Effort range | +|---|---:| +| P0 | ~420–700 engineering hours | +| P1 | ~180–320 engineering hours | +| P2 exploratory extensions | ~40–90 engineering hours | +| P3 optional benchmarks | ~15–40 engineering hours | +| **Total** | **~655–1,150 engineering hours** | + +For 2–3 effective contributors across Rust/security/SRE/QA, this is approximately **7–14 working weeks**, overlapped with Story implementation. + +### Epic 1 quality gates + +- P0 = **100%**; P1 ≥**95%** during development and **100% for Story acceptance/epic qualification**. +- Every Story 1.1–1.16 has bidirectional requirement→test→evidence mapping; no acceptance criterion is silently manual or skipped. +- E1-R-001/002/007/008/009/012 (score 9) are closed by evidence; all score 6 risks have verified mitigation/owner. +- No Critical/High defect or security finding; secret-canary and scope-isolation scans are clean. +- Workspace coverage remains ≥80%, and newly introduced critical state/security/config/migration code targets ≥90% branch/contract evidence; coverage cannot replace traceability. +- Catalog discovery and Logs/Usage thresholds pass on checksummed production-size datasets; metric budget is frozen and passed before Story 1.6 closes. +- Existing REST→MCP baseline remains green, and no toolchain/dependency/wire change is mixed into the Epic without its own compatibility change. +- Final NFR PASS/CONCERNS/FAIL remains deferred to the NFR assessment after implementation evidence exists. + +## Run 2 / Step 5: Epic 1 Output and Validation + +- **Mode:** Epic-Level; Epic 1; single-worker sequential output as required for epic-level mode. +- **Output:** `_bmad-output/test-artifacts/test-design-epic-1.md`. +- **Validation:** template/checklist sections, E1-R-001..E1-R-015, E1-01..E1-41, priorities, NFR planning boundary, estimates, quality gates, placeholders and Markdown structure checked. +- **Browser hygiene:** Playwright CLI was unavailable, no browser session was opened, and no temporary exploration artifact was created. +- **Open controlled inputs:** numeric metric series budget, typed security/retention configuration values and Story 1.16 usability protocol must be frozen by their owning Story; no values were guessed. +- **Recommended next workflow:** ATDD for Story 1.1, followed by its implementation; Epic-level trace/NFR verdict waits for implementation evidence. diff --git a/_bmad-output/test-artifacts/test-design-qa.md b/_bmad-output/test-artifacts/test-design-qa.md new file mode 100644 index 0000000..4d57039 --- /dev/null +++ b/_bmad-output/test-artifacts/test-design-qa.md @@ -0,0 +1,295 @@ +--- +workflowStatus: 'completed' +totalSteps: 5 +stepsCompleted: ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output'] +lastStep: 'step-05-generate-output' +nextStep: '' +lastSaved: '2026-09-13' +lastEdited: '2026-09-13' +editScope: 'system-level inventory and evidence-aware strategy refresh' +auditedRevision: '083974c27f3a21a15807dd248bb6bc4fe04a5cd8' +workflowType: 'testarch-test-design' +inputDocuments: + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/planning-artifacts/epics.md' +--- + +# Test Design for QA: Crank Community Production Readiness + +**Purpose:** Execution recipe for proving Crank Community production readiness. Architectural requirements and production-code mitigations are in `test-design-architecture.md`. + +**Date:** 2026-09-13 (original design: 2026-08-08) +**Author:** BMad TEA / Bsodfather +**Status:** System-level design updated; current evidence inventory precedes epic-level planning +**Project:** crank + +## Executive Summary + +Scope covers all 54 FRs, 30 NFRs and the eight production-readiness epics. There are 15 risks: 14 high (five score 9), one medium and none low. Dominant categories are operations, security, technical/concurrency, data integrity and performance. + +The plan retains 34 scenario families, not a promise to write 850–1,250 additional tests. Existing tests must be reused. P0 denotes a security/data-integrity/core-operation failure with no safe workaround; ordinary feature variants are P1, not automatically P0. E2E checks cross-boundary outcomes rather than repeating parser or state-machine branch tests. + +Audit boundary: main `083974c27f3a21a15807dd248bb6bc4fe04a5cd8`. Story 2.9 candidate `f8ee7c9bfeaa8a3f73a4850ff3f82b2bc2155fe8` is recorded separately and is not integrated into main. This update is a source/configuration audit, not a fresh product test run. + +## Not in Scope + +| Item | Reason | Mitigation | +|---|---|---| +| HA/multi-instance rolling upgrade | Explicit post-launch scope | Document single-instance claim and reject HA evidence claims | +| S3-compatible artifacts, SSO/RBAC, non-REST adapters | Deferred by architecture | Preserve ports/invariants; revisit in later test design | +| Arbitrary distributed load targets or loads above built-in ceilings | Unsafe/outside Community goal | Load runner allowlists only Crank MCP and enforces signed ceilings | +| MCP revisions published after feature freeze | Unbounded moving target | Enter next adapter/compatibility cycle | + +## Dependencies and Test Blockers + +### Backend/architecture dependencies + +1. **B-001 deterministic control plane:** typed factories/builders, scoped cleanup, controllable time/IDs/scheduler. +2. **B-002 named fault injection:** network, stores, worker, telemetry and disk failure controls. +3. **B-003 queryable observability sinks:** captured trace/envelope/metric/dashboard state searchable by IDs. +4. **B-004 evidence contract:** stable artifact schemas and RC provenance collectors. +5. **B-005 measurable load runner:** calibrated stub/external generator, separate resource metrics and reliable kill path. + +### QA infrastructure setup + +- Extend `crank-test-support` with PostgreSQL 16/Valkey/telemetry/malicious-upstream fixtures and per-worker schemas. +- Provide seeded production-size and minimal datasets with deterministic seeds and automatic cleanup. +- Create MCP protocol/client matrix harness, OpenAPI corpus runner, browser storage-state fixtures and artifact collectors. +- Provision PR ephemeral dependencies, nightly full topology, weekly reference hardware/air-gap lab and immutable RC qualification environment. +- Retain JUnit/JSON, Playwright traces, raw metrics, logs and content-addressed evidence under `_bmad-output/test-artifacts/` or the release evidence store. + +### Actual Tooling vs Configuration + +`tea_use_playwright_utils=true` and `tea_use_pactjs_utils=true` are workflow preferences, not installed dependencies. The UI package currently contains `@playwright/test` 1.61.1 and esbuild; neither Utils nor Pact is installed. This design does not install or mandate a wholesale test rewrite. Retain working fixtures; evaluate additional tooling only for an identified gap. + +### Existing Test Inventory + +Presence below means inspected test source, not current pass or a coverage percentage. + +| Surface / FR | Representative existing source | What it exercises | Missing qualification / next evidence | +|---|---|---|---| +| Config, FR-45 | `crates/crank-config/tests/{contract,generation,redaction}.rs`; app `tests/config_startup.rs` | Config bounds, deterministic contracts, read-only startup, safe failures | Production-profile matrix on a bound artifact | +| Auth/secrets, FR-3/5 | `apps/admin-api/tests/integration/{auth_rate_limit,credential_lifecycle,secrets_import_auth}.rs`; runtime `tests/integration/{confirmation,idempotency}.rs` | CSRF/origin/rate-limit, lifecycle, encrypted credentials, approval/idempotency | Whole web-security and deployed secret-canary matrix | +| Operation/Agent lifecycle, FR-1/4/6 | Admin `tests/integration/{operation_lifecycle,operations_agents}.rs`; registry `tests/integration/operations_artifacts.rs` | Versions, publish, concurrency, immutable snapshots, history | Same-revision UI→API→MCP proof and complete manual pass | +| REST runtime, FR-2 | `crates/crank-runtime/tests/stages.rs`; adapter `tests/integration/{client,outbound_security}.rs` | Validation, retries/deadlines, SSRF/proxy/DNS, bounded execution | Calibrated performance and deployed network-fault profiles | +| OpenAPI, FR-7..12 | `crates/crank-import/tests/{preview,coverage,normalization_details,reference_resolution}.rs`; Admin `tests/integration/openapi_import.rs` and `openapi_import/external_references.rs` | Parser/IR/ref limits, provenance, preview/apply/replay, atomicity | ≥50-spec independent oracle corpus, remaining security/re-import semantics; candidate 2.9 tracked separately | +| Artifacts / recovery foundations | `crates/crank-artifacts/tests/{artifact_store,artifact_store_io,reconciliation}.rs`; registry migration tests | Digest integrity, symlink protection, crash/disk-full, reconciliation, schema drift/rollback | Full deployment restore with DB/artifacts/keys and measured RPO/RTO | +| MCP Tools, FR-13/14/20 | MCP app `tests/integration/{transport_protocol,catalog_access,tool_search}.rs`; `crates/crank-community-mcp/tests/` | JSON/SSE sessions, list/call, scope/revocation, stale catalog | Frozen revision matrix and ≥3 actual clients | +| Resources/Prompts/Tasks, FR-15..19/21..26 | Capability inventory marks planned flows | No implemented feature-level suite found | Model/contract tests plus public MCP/UI outcomes after features exist; internal tokio tasks are not MCP Tasks | +| Correlation / metrics, FR-27..35 | `crates/crank-observability/tests/`; app `tests/{request_context,product_metrics}.rs`; `crates/crank-metrics/tests/` | Local IDs, propagation, captured OTLP, redaction, metric contracts | Actual GlitchTip delivery/spool truth; browser correlation; Grafana/alerts; full overhead workload | +| Load Runs, FR-36..40 | Local metric overhead and concurrency probes only | Narrow budgets, not a built-in load capability | Bounded runner, external calibration, safe stop and report accuracy | +| Browser | `apps/ui/tests/e2e/`, `playwright.config.js` | 56 discovered tests in 13 files; selected RU/EN and mobile viewport cases | Firefox/WebKit; complete locale/critical-viewport matrix; isolation before parallelism | +| CI / tooling, FR-46/50 | `tests/unit/`, `justfile`, `.gitea/workflows/{ci,release}.yml` | 138 Python test methods; Rust/UI guards, dependency checks, image smoke, scan/evidence collectors | Coverage reports, scheduled long-run lanes, full release evidence and retention policy | + +Rust inventory method: `git ls-tree -r --name-only HEAD -- apps crates` filtered for `/tests/.*\\.rs$` or `/src/.*_tests\\.rs$` yields 116 files. `git grep -h -E '#\\[(tokio::test|test)' HEAD -- apps crates | wc -l` yields 768 attributes (including inline tests). These static counts are not executed cases or line/branch coverage. + +Playwright discovery was actually run: `./node_modules/.bin/playwright test --list --reporter=line` → 56 tests / 13 files, exit 0. No browsers or product services were started by this command. Real-stack scenarios include `onboarding.spec.js` public tools/call and OpenAPI upload; many failure/race UI tests use `page.route` and prove browser handling only. A local controlled upstream is appropriate for deterministic wire assertions, but does not qualify arbitrary external APIs. + +### Available Execution Evidence and Exclusions + +- Historical baseline `docs/capability-baseline/results.json` (`2026.08.24.1`) contains revision-bound accepted runs, historical failures and a not-run manual item. Do not transplant its verdicts to current main; validate the baseline as a historical contract only. +- Candidate 2.9 has a prior successful full `just verify`, documented in `_bmad-output/implementation-artifacts/spec-2-9-http-contract.md`; local log `/tmp/crank-24-verify-final-gate.log` is non-durable supporting evidence. It includes admin integration 81 and MCP integration 40 passes. It does not prove browser E2E, deployment or public readiness. +- Its review also leaves two explicitly deferred pre-existing cases: undeclared URL placeholders and composite object/array defaults. Preserve them in the future corpus/gap triage; a green candidate gate does not close these cases. +- `crates/crank-registry/tests/integration/observability.rs` has ignored `production_size_invocation_history_queries_stay_bounded`, inserting 1,000,000 rows. Standard workspace tests do not execute it; it belongs in an explicitly provisioned performance lane. +- No measured workspace line/branch coverage report was found. The existing ≥80%/≥90% targets below remain design targets, not observed values. +- Presence of restore scripts, manual checklists or SLO thresholds is not evidence that restores, manual qualification, 72-hour soak or 30-day burn-in passed. + + +## Risk Assessment + +| Risk | Score | QA coverage | +|---|---:|---| +| R-001 brownfield regressions | **9** | CP-01..04 characterization/manual baseline | +| R-002 OpenAPI semantic loss | **9** | CP-05..07 corpus, API and representative UI | +| R-003 Task duplicate/stale writes | **9** | CP-12..15 model, PG contention, chaos and MCP E2E | +| R-004 SSRF/secret leakage | **9** | CP-03/04/19/25/27 plus malicious-network/canary scans | +| R-005 trace spool/replay false claims | **6** | CP-16..18 outage/replay and golden correlation | +| R-006 SLO breach under contention | **9** | CP-14/18/20/23/29 calibrated performance | +| R-007 admin/session/recovery auth | **6** | CP-25 web-security state/config matrix | +| R-008 inconsistent upgrade/restore | **6** | CP-26 three restores and N/N-1 workflows | +| R-009 MCP catalog/client inconsistency | **6** | CP-08..11 protocol and real-client matrix | +| R-010 unsafe/uncontrollable Load Run | **6** | CP-22..24 authorization/kill/UI tests | +| R-011 metric double count/cardinality | **6** | CP-19..21 registry/differential/dashboard tests | +| R-013 mixed/stale evidence | **6** | CP-28..31 manifest negative matrix | +| R-014 untrusted/leaky offline bundle | **6** | CP-27 supply-chain and air-gap capture | +| R-015 late soak defect | **6** | CP-29 early trends + 72 h/30 d qualification | +| R-012 flaky E2E | 4 | Parallel-safety burn-in, trace-on-failure and quality lint | + +## NFR Test Coverage Plan + +| Category | Requirement / threshold | Planned validation | Tool / level | Evidence artifact | Priority | +|---|---|---|---|---|---| +| Security/privacy | Default deny, encrypted/no-leak secrets, per-connection SSRF, no Critical/High, opt-in egress | Auth/config abuse, malicious DNS/redirect/proxy, secret canaries, supply-chain scans | Rust/API/Playwright + SAST/SCA/SBOM | SARIF/JUnit, SBOM/signature, canary and egress reports | P0 | +| Performance/scale | 100 RPS/30 m, 250 RPS/5 m, ≥99.95%, reject ≤0.1%, 128/10k, overhead 50/150 ms | Calibrated built-in/external load, contention, production dataset and telemetry differential | External load tool + built-in runner + Prometheus | Raw samples, SUT/generator resource series, plans, verdict JSON | P0 | +| Reliability/recovery | drain ≤30 s, Task start ≤5 s p95, lease recovery ≤60 s, RPO≤5 m/RTO≤30 m | Crash schedules, restart/drain, N/N-1, three PITR restores, 72 h/30 d | PG integration/chaos/recovery/soak | State invariants, manifests, probe logs and time series | P0 | +| Observability | 100% IDs/traces, delivery ≥99.99%/60 s, completeness 100%/25 h, 30 h spool, overhead limits | Golden correlation, outage/replay/corruption/disk, metrics/cardinality/dashboard/alerts | API/MCP/Playwright + captured telemetry + Prom/Grafana | Correlation graph, envelopes, loss ledger, dashboard tests | P0 | +| Compatibility | MCP stable/N-1/N-2, ≥3 clients; OpenAPI ≥50/≥95%/zero silent loss; browser/PG/Valkey matrices | Corpus, protocol/clients, browser and dependency matrices | Rust corpus/protocol/CI matrix | Machine-readable matrices and raw failures | P0 | +| Maintainability/provenance | ≥80% overall, ≥90% critical crates; immutable one-RC evidence; RU/EN | Coverage/lint/architecture/wire/localization and manifest negative tests | CI/static/contract | Coverage, lint and signed manifest reports | P1/P0 manifest | + +Threshold source is PRD §5/§10; exact client/revision/image selections are freeze inputs, not guessed current versions. Missing evidence sources: reference performance host, calibrated generator, durable report storage, GlitchTip/Prometheus/Grafana test topology, recovery/air-gap environment and release signing trust. + +Measure steady and burst acceptance per minute (NFR-P1a/P1b), not only whole-run averages. Use PRD SLI denominators for handled upstream/client errors, product failures, saturation and missing probes. Run the required workload three consecutive times and retain raw inputs/config/resource series. Measure platform overhead separately from the controlled upstream delay. A million-row query-plan test alone cannot prove the mixed 100/250 RPS workload or UI p95. + +## Entry Criteria + +- Requirements/architecture/epics are versioned and the selected story has ATDD-ready acceptance criteria. +- Applicable B-001..B-005 seams are implemented and production-disabled where required. +- Test environment, deterministic factories, cleanup and artifact retention are operational. +- Feature is deployed with exact code/config/topology digest and migrations compatible with the test matrix. +- Test oracle (corpus expected result, protocol version, SLO formula or recovery checkpoint) is frozen. + +## Exit Criteria + +- P0 = 100%; development P1 ≥95%; RC P1 mapped to mandatory FR/critical journeys = 100%. +- No open Critical/High defect, security finding or score-9 risk; score 6–8 mitigations have evidence. +- Workspace coverage ≥80% and critical state/security crates ≥90%, without requirement gaps. +- All required corpus/client/browser/store matrices and manual checks pass; no manual item blocked/not-run. +- Every NFR has same-RC raw evidence and later NFR assessment; all numerical thresholds pass. +- Signed manifest validates and binds the exact published RC, config, topology and artifacts. + +## Test Coverage Plan + +P0/P1/P2/P3 indicate priority, **not execution timing**. The table is the corrected current system mapping; older CP mappings in the historical progress/handoff files are not authoritative. Each family will be decomposed only when its epic is planned. “Partial” means some source exists, not that the complete FR passes. + +### P0 — Critical + +Security, data integrity and core-operation invariants without a safe workaround. Negative subcases of P1 families are P0 where stated. + +### P1 — High + +Required feature variants, compatibility and operator outcomes with material reach. Mandatory release requirements still require 100% accepted evidence even when P1. + +### P2 — Medium + +Supplementary exploratory cases with an acceptable workaround; they do not replace the mandatory manual regression pass. + +### P3 — Low + +Optional cosmetic/experimental probes only; not mandatory release evidence. + +| ID | Requirement | Priority | Primary level | Risk | Required oracle / outcome | Main inventory | +|---|---|---|---|---|---|---| +| CP-01 | FR-1..6 | P0 | API + golden UI/MCP | R-001/R-004 | Create→test→publish→call→history; exact result and safe failure | Partial | +| CP-02 | FR-1/4/43/45 | P0 | Unit + PG | R-001/R-008 | Immutable versions, atomic publish, compatible migration and config | Partial | +| CP-03 | FR-5; NFR-S1/S7 | P0 | State/PG + boundary | R-004 | Approval/idempotency cannot duplicate effects or fail open | Partial | +| CP-04 | FR-3; NFR-S2 | P0 | API/PG + canary | R-004 | Create/use/rotate/revoke; no plaintext in output channels | Partial | +| CP-05 | FR-7/8/9/10/12 | P0 | Pure corpus + wire contract | R-002 | Canonical parse/replay; exact blockers; no silent semantic loss | Partial; 2.9 candidate separate | +| CP-06 | FR-7/11 | P0 | API/PG | R-002 | Preview no mutation; scoped, atomic, idempotent apply; re-import conflicts | Partial | +| CP-07 | FR-7..12 | P1 | Playwright real stack | R-002 | Upload→findings→selection→draft→publish; cancellation/recovery | Partial | +| CP-08 | FR-13/14/19 | P1 | MCP protocol | R-009 | Negotiation, Tools schema/results, pagination and notifications | Partial | +| CP-09 | FR-15/16 | P1 | Unit/API + public MCP | R-009/R-004 | Static/dynamic resources, templates, pinned read-safe operation; negative access P0 | Planned | +| CP-10 | FR-17/18/19 | P1 | Unit/API + public MCP | R-009/R-004 | Prompt arguments/render/DAG/completion; forbidden side effects P0 | Planned | +| CP-11 | FR-20; NFR-C2 | P1 | Actual-client matrix | R-009 | ≥3 clients × frozen stable/N-1/N-2; identical versioned semantics | Gap | +| CP-12 | FR-21/22 | P0 | Model/property | R-003 | Only legal Task states; immutable terminal result and pinned versions | Planned | +| CP-13 | FR-23/25 | P0 | PG crash/concurrency | R-003 | Enqueue/claim/fencing/retry/cancel; no stale writes or false exactly-once claim | Planned | +| CP-14 | FR-24; NFR-P2/R5 | P0 | Controlled load | R-003/R-006 | 128 active/10k queued; bounded wait/fairness and ≤60s recovery | Planned | +| CP-15 | FR-21..26 | P1 | Public MCP + UI | R-003/R-009 | Observe/cancel/resume through disconnect/restart and supported fallback | Planned | +| CP-16 | FR-27/30; NFR-O1/O5 | P0 | Contract/API | R-005/R-004 | Request/trace identities survive boundaries; redaction and invalid-input replacement | Partial | +| CP-17 | FR-28/29/30 | P1 | Browser→MCP→receiver | R-005 | Search/copy/deep-link actual delivered trace; missing/lost is never shown as delivered | Gap | +| CP-18 | FR-29/31; NFR-O2/O2a/O3 | P0 | Telemetry fault/capacity | R-005/R-006 | Outage/restart/replay/disk corruption; delivery/loss and resource budgets | Gap | +| CP-19 | FR-32; NFR-O4 | P0 | Unit/contract | R-011 | Names/units/buckets/labels bounded; no user identifiers as labels | Partial | +| CP-20 | FR-33 | P0 | PG differential | R-011 | UTC DAU/usage events and rollups agree; replay cannot double count | Partial | +| CP-21 | FR-34/35 | P1 | Prometheus/Grafana integration | R-011 | Provision dashboards/rules; known synthetic series trigger correct SLO alerts | Gap | +| CP-22 | FR-36/37/38/39 | P0 | API/state/security | R-010 | Validate target/auth/ceilings; reserve stop path; reject scope escape | Planned | +| CP-23 | FR-40; NFR-P1/P4 | P1 | Calibrated performance | R-006 | Report classifications/percentiles match external generator at reference workload | Planned | +| CP-24 | FR-36..40 | P1 | Playwright real stack | R-010 | RPS/DAU configuration→launch→live statistics→stop→report | Planned | +| CP-25 | FR-41/42/44/45 | P0 | API/browser security | R-007/R-004 | Bootstrap/session/recovery, TLS/proxy/cookie/CSRF/CORS/default-deny matrix | Partial | +| CP-26 | FR-43 | P0 | Deployment/restore | R-008 | Fresh/N-1/rollback + 3 PITR restores; real encrypted-auth MCP probe | Partial foundations | +| CP-27 | FR-42/44/50 | P0 | Supply-chain/air-gap | R-014 | Trusted pinned bundle/SBOM; zero undeclared egress and Critical/High findings | Partial scans | +| CP-28 | FR-46/48/50 | P1 | CI matrix | R-001/R-009 | Required suites, browsers, clients, PG/cache modes; retain failures too | Partial | +| CP-29 | FR-49 | P0 | Soak/recovery | R-006/R-015 | 72h then supervised 30-day qualification on immutable RC, no loss/drift | Gap | +| CP-30 | FR-47/51/52/53 | P1 | Guided manual/docs | R-001/R-008 | Operator can follow runbooks; readiness page reflects evidence, not promises | Partial docs; qualification missing | +| CP-31 | FR-54 | P0 | Manifest negative contract | R-013 | Reject missing/stale/mixed/untrusted evidence; FR-54 cannot prove itself | Partial collectors only | +| CP-32 | NFR-C1/C3/C4 | P1 | Static/contract | R-001/R-012 | Dependency/MSRV/wire rules; simultaneous RU/EN; coverage report | Partial | +| CP-33 | UI across FR-1..53 | P1 | Component/browser | R-012 | Loading/empty/error/stale states; keyboard/focus/viewport; no hidden controls | Partial | +| CP-34 | FR-47/51 | P2 | Time-boxed exploratory | R-001/R-002 | Real-spec/operator/client combinations beyond deterministic corpus | Not evidenced | + +This is family-level traceability, not a measured AC-to-test coverage matrix. Use the lowest effective test for exhaustive variants, then one representative cross-boundary success and failure for each critical journey. Retain explicit negative cases for authorization, secret leakage, corruption, concurrent mutation, cancellation and limits. Do not generate duplicate E2E tests for every unit-level combination. + +## Execution Strategy + +Current reality: Gitea runs full functional Rust tests, UI build/audit, Chromium E2E and image smoke on configured PR/push paths; release adds artifact/scanning steps. `just verify` does **not** run UI E2E, Docker image smoke or deployment. Playwright currently uses one worker and CI retry=1, not sharding. No scheduled nightly/weekly workflows or measured coverage gate were found. + +Target: run functional regression in PRs; move only explicitly expensive load/chaos/long-run qualification to provisioned lanes. The 10–15-minute feedback target below is aspirational, not measured. Do not weaken assertions, omit a failing test or increase timeouts merely to meet it. + +- **Every PR (10–15 min feedback target, not a current duration claim):** existing full functional Rust/PG suite, format/lint/boundaries, dependency/UI build checks, Chromium E2E, contract/evidence validation and applicable image smoke. Keep selected local tests for fast iteration, not as a substitute for the integration gate. Parallelism requires isolation evidence first. +- **Nightly (duration to measure after provisioning):** expanded browser/client/cache matrices, production-size history, bounded contention, telemetry outage/replay and repeat-run flake detection. Ordinary functional failures must not be moved here merely to unblock PRs. +- **Weekly (hours):** full browser/client matrices, scans, Task contention/chaos, upgrade/rollback, dashboard/alerts, 100/250 RPS rehearsal, spool/disk pressure and backup/restore rotation. +- **RC:** exact immutable artifact; all matrices/manual work, three restores, air-gap flows, 72-hour soak and then non-accelerable 30-day/≥1M-event burn-in. Any digest-changing fix creates a new RC. + +Before enabling Playwright sharding, prove per-worker data/ports/storage/session isolation; the existing single-worker setting stays until that evidence exists. Current traces are `on-first-retry`; screenshots/videos retain failures. A retry pass is flaky evidence, not a clean pass: existing OpenAPI accepted-run collection already rejects flaky/missing required cases. + +Before integration: targeted regression → affected subsystem → full Rust gate plus affected UI/deploy gate. Reuse a completed gate only for the identical source tree and relevant environment; record subsequent documentation-only changes. Capture subprocess fault tests through pipes (not direct regular-file stdout under RLIMIT_FSIZE). Keep a bounded log and the complete machine-readable outcome so failed attempts remain diagnosable. + +Provision explicitly for expensive probes: PostgreSQL16 and disk headroom for the million-row test; a PRD reference host for load; isolated backup/restore destinations and keys; test-only telemetry sinks; no production endpoints or customer secrets. Scheduled execution and provisioning are follow-up implementation work, not changes made by this design. + +## QA Effort Estimate + +The August estimate (~42–71 engineer-weeks, ~850–1,250 cases) predates the inventory and is **not a forecast of remaining work**. Remaining automation effort is UNKNOWN until each family separates reusable tests from missing assertions and unavailable product features. No new test-count quota is introduced. + +Estimate each epic delta as a range after system-design acceptance, based on fixture reuse and actual test durations; exclude production-feature implementation and infrastructure operations from QA effort. The 30-day burn-in is a PRD calendar constraint, not 30 days of full-time test-authoring effort. + +## Implementation Planning Handoff + +| Work item | Owner | Target | Dependencies | +|---|---|---|---| +| Deterministic fixtures/factories and per-worker cleanup | QA + Core | Epic 1 | B-001 | +| OpenAPI corpus oracle/runner | Import + QA | Epic 2 | Stable IR/findings | +| MCP protocol/representative-client harness | MCP + QA | Epic 3 | Version adapters | +| Task model/PG chaos harness | Task + QA/SRE | Epic 4 | B-001/B-002 | +| Telemetry/metrics capture and assertions | Observability + QA | Epic 5 | B-003 | +| Calibrated load and reference topology | Performance/SRE | Epic 6 | B-005 | +| Upgrade/restore/air-gap automation | Release/Security/QA | Epic 7 | B-002/B-004 | +| Evidence collector/manifest verifier and RC qualification | Release + QA | Epic 1→8 | B-004, all suites | + +## Tooling and Access + +| Tool/service | Purpose | Access | Status | +|---|---|---|---| +| PostgreSQL 16/Valkey Testcontainers | Storage/coordination integration | Container runtime | Existing foundation; extend | +| Playwright 1.61.1 | UI and real-stack/mocked-boundary browser tests | Node + Chromium | Installed; Utils/Pact are preferences only, absent from package.json | +| MCP protocol harness + ≥3 clients | Compatibility matrix | Pinned clients | Pending feature-freeze selection | +| Captured OTLP/Sentry endpoint, Prometheus/Grafana/GlitchTip | Observability assertions | Self-hosted test profile | Pending Epic 5 | +| External calibrated load/chaos tooling | Cross-check and fault injection | Reference host/lab | Pending | +| cargo-deny, npm audit, Trivy / SBOM | Dependency/container policy | CI toolchain/images | Configured; current scan reports and complete SAST/secret/signature evidence not established by this audit | + +## Interworking and Regression + +| Component | Impact | Regression scope | Validation | +|---|---|---|---| +| Core/runtime/REST adapter | Shared execution semantics/security | Existing REST→MCP + all ingress paths | CP-01..04, CP-16, malicious upstream | +| Import/artifacts/registry | New parser/transactional plans | OpenAPI and persisted revisions | CP-05..07 | +| MCP server/catalog | New capabilities and adapters | Stable/N-1/N-2 clients | CP-08..11 | +| Task worker/PostgreSQL/Valkey | New durable concurrency | State, contention, restart, PG-only | CP-12..15 | +| UI/Admin API | New operator flows/security | RU/EN, async state, auth, browser matrix | CP-07/17/24/25/33 | +| Observability/metrics stack | Cross-cutting data path | Correlation, redaction, cardinality, SLO | CP-16..21 | +| Load/deploy/release assets | Production operations | Safety, recovery, air gap, evidence | CP-22..31 | + +Every fixed defect adds the lowest-level regression and a boundary case if the failure crossed a contract. + +## Appendix A: Reproducible Discovery and Evidence + +```bash +# From apps/ui: enumerate only; does not prove a pass. +./node_modules/.bin/playwright test --list --reporter=line +# From the repository: static test attributes, not coverage. +git grep -h -E '#\[(tokio::test|test)' HEAD -- apps crates | wc -l +``` + +For each future accepted run retain source revision/tree, image/config/topology identifiers, dependency/client/browser versions, command, timestamps, cases passed/failed/skipped/flaky, raw report digest and sanitized diagnostics. Source files and generated “completed” planning metadata cannot serve as execution evidence. Keep secrets, credentials and unbounded payloads out of retained reports. + +Current tests do not have a complete @P0/@P1 tag taxonomy; selecting tags before annotating the suite may run zero tests. Use known files/test names now, and make empty mandatory selections fail. Report retention must cover ordinary failing runs as well as successful sanitized OpenAPI release evidence. + +## Edit Verification — 2026-09-13 + +Read source/configuration and previous plans; ran Playwright discovery only. Product tests, benchmarks, browser runs and deploy were not rerun. Document checks confirm 34 unique CP families covering all FR-1..54 at family level, shared risk identifiers, preserved PRD thresholds and explicit missing evidence. This is not an assertion-level coverage proof or final NFR PASS/CONCERNS/FAIL verdict. + +## Appendix B: Knowledge Base References + +- `risk-governance.md` and `test-priorities-matrix.md` +- `test-levels-framework.md` and `test-quality.md` +- `nfr-criteria.md` and `adr-quality-readiness-checklist.md` +- `playwright-cli.md` and `contract-testing.md` + +**Generated by:** BMad TEA Agent +**Workflow:** `bmad-testarch-test-design` diff --git a/_bmad-output/test-artifacts/test-design/crank-handoff.md b/_bmad-output/test-artifacts/test-design/crank-handoff.md new file mode 100644 index 0000000..d3204ab --- /dev/null +++ b/_bmad-output/test-artifacts/test-design/crank-handoff.md @@ -0,0 +1,117 @@ +--- +title: 'TEA Test Design → BMAD Handoff Document' +version: '1.0' +workflowType: 'testarch-test-design-handoff' +inputDocuments: + - '_bmad-output/test-artifacts/test-design-architecture.md' + - '_bmad-output/test-artifacts/test-design-qa.md' + - '_bmad-output/planning-artifacts/epics.md' +sourceWorkflow: 'testarch-test-design' +generatedBy: 'BMad TEA / Bsodfather' +generatedAt: '2026-08-08T00:00:00+03:00' +projectName: 'crank' +--- + +# TEA → BMAD Integration Handoff: crank + +## Purpose + +This document maps the system test design into the already-created epics/stories. Story refinement and ATDD must preserve these quality requirements; implementation status is not implied. + +## TEA Artifacts Inventory + +| Artifact | Path | Integration point | +|---|---|---| +| Architecture testability contract | `_bmad-output/test-artifacts/test-design-architecture.md` | Production seams, blockers, ASRs and risk ownership | +| QA execution recipe | `_bmad-output/test-artifacts/test-design-qa.md` | Scenario families, evidence, schedules and estimates | +| Progress/source analysis | `_bmad-output/test-artifacts/test-design-progress.md` | Detailed NFR thresholds and 34-group coverage matrix | +| Product stories | `_bmad-output/planning-artifacts/epics.md` | Requirements and acceptance-criteria insertion point | + +## Epic-Level Integration Guidance + +### Risk references + +- **Epic 1:** R-001, R-004, R-012, R-013 — freeze baseline; establish deterministic fixtures, security/correlation foundations and evidence schemas. +- **Epic 2:** R-002 — OpenAPI semantic oracle, immutable preview/apply and zero-silent-loss gate. +- **Epic 3:** R-009 — immutable catalog plus version/client compatibility evidence. +- **Epic 4:** R-003, R-015 — model-based Task lifecycle, real-PG crash/contention proof and early long-run trends. +- **Epic 5:** R-005, R-006, R-011 — trace truth, spool/loss accounting, metric cardinality/rollups and overhead evidence. +- **Epic 6:** R-006, R-010 — calibrated workload, generator accounting, signed limits and independent stop path. +- **Epic 7:** R-004, R-007, R-008, R-014 — web security, secret/egress protection, N/N-1 recovery and trusted air-gap delivery. +- **Epic 8:** R-001, R-006, R-013, R-015 plus all residual risks — complete one-RC qualification and fail-closed Habr gate. + +### Quality gates per epic + +| Epic | Gate | +|---|---| +| 1 | Existing core baseline passes; test controls and evidence schema exist; correlation/metrics foundations have contract tests | +| 2 | ≥50-spec corpus, ≥95% actionable Draft, zero silent loss, deterministic preview and atomic apply | +| 3 | Tools/Resources/Prompts pass stable/N-1/N-2 protocol and ≥3 representative clients | +| 4 | No illegal/stale terminal transitions; 128 active/10k queue/fairness and ≤60 s recovery evidence | +| 5 | 100% correlation, delivery/completeness/spool/overhead budgets, bounded cardinality, tested dashboards/alerts | +| 6 | Built-in/external results agree; 100/250 RPS thresholds pass; stop/kill/security controls proven | +| 7 | Fresh/N-1/rollback/three restores/air-gap/default-deny pass with real encrypted-auth MCP probes | +| 8 | P0/mandatory P1/manual/matrices/security/72 h/30 d all pass on one signed immutable RC | + +## Story-Level Integration Guidance + +### P0/P1 scenarios that must become acceptance criteria + +1. Every story names its Requirements tags and primary test level; fixed defects include a regression test. +2. State/storage stories include deterministic seed/cleanup, contention/crash and fail-closed negative criteria where applicable. +3. Wire/UI stories assert stable `error_code`, safe RU/EN message, `request_id` and `trace_id`; no raw payload/cause leakage. +4. OpenAPI stories add/modify corpus fixtures and expected findings for every supported or defective construct. +5. MCP stories update protocol snapshots/matrix and prove Agent scope/catalog revision before serialization. +6. Task stories prove legal lifecycle transitions, CAS/fencing, pinned semantics, idempotency and `outcome_unknown` reconciliation. +7. Observability stories deliver queryable machine-readable evidence, not only screenshots; UI distinguishes local/delivered/lost/unknown. +8. Metrics stories include registry/cardinality lint and idempotent event-rollup replay. +9. Load stories prove plan authorization, ceiling enforcement, runner/SUT accounting and forced-stop recovery. +10. Deploy/recovery/release stories bind evidence to code/config/topology digests and reject stale/cross-RC artifacts. + +### UI testability requirements + +- Prefer accessible roles/labels; add stable `data-testid` only where semantic locators are ambiguous. +- Required stable hooks include Operation/Agent/Resource/Prompt revision/state, import finding/operation IDs, Task ID/status/progress/attempt, request/trace copy/deep-link controls, telemetry delivery state, metric/SLO panel identifiers, Load Run ID/state/stop and security/error boundaries. +- Async lists/details must expose identity/revision so stale-response tests can assert the winning response. +- API-first per-worker data setup and cleanup is mandatory; never rely on shared fixed records. + +## Risk-to-Story Mapping + +| Risk | P×I | Recommended stories/epic | Primary level | +|---|---:|---|---| +| R-001 | 9 | 1.1–1.2, all regression stories, 8.3/8.9 | API + guided/E2E | +| R-002 | 9 | 2.1a–2.1d, 2.2–2.9 | Rust corpus + API/PG | +| R-003 | 9 | 4.1 onward (Task/admission/worker lifecycle) | Model/property + PG chaos | +| R-004 | 9 | 1.9–1.10, observability redaction, 7 security/offline stories | Security integration/system | +| R-005 | 6 | 5.1–5.7 correlation/spool/loss | Contract + telemetry E2E/chaos | +| R-006 | 9 | 5 overhead/metrics, 6 load, 8 perf/soak | Performance/system | +| R-007 | 6 | Epic 7 admin auth/hardening/recovery | API/browser security | +| R-008 | 6 | Epic 7 migration/upgrade/backup/restore | Deployment/recovery | +| R-009 | 6 | 3.1–3.14 | MCP protocol/client matrix | +| R-010 | 6 | Epic 6 authorization/runner/UI stories | API/system/Playwright | +| R-011 | 6 | 1.6 and Epic 5 metrics/rollups/Grafana | Unit/PG/config integration | +| R-012 | 4 | All UI stories and Epic 8 automation | Playwright quality/burn-in | +| R-013 | 6 | 1 enabling evidence work; Epic 8 manifest/gate | CLI/schema/signature | +| R-014 | 6 | Epic 7 offline/supply chain; Epic 8 security | Air-gap/system scan | +| R-015 | 6 | Epic 4 onward trends; 8 soak/burn-in | Long-duration system | + +## Recommended BMAD → TEA Sequence + +1. This system Test Design is complete. +2. Correct/refine existing stories using this handoff where acceptance criteria are missing. +3. Run epic-level Test Design per epic when it enters implementation. +4. Run ATDD for the next story before implementation. +5. Implement story and its lowest-level tests. +6. Expand automation, then generate traceability/gate evidence. +7. Run NFR assessment only after implementation evidence exists. + +## Phase Transition Quality Gates + +| From | To | Gate | +|---|---|---| +| System design | Epic refinement | Every score ≥6 risk has owner, mitigation and target epic | +| Epic refinement | ATDD | Story contains risk-linked, measurable and testable acceptance criteria | +| ATDD | Implementation | Failing P0/P1 acceptance scaffolds and deterministic prerequisites exist | +| Implementation | Automation/trace | Story tests pass and artifacts are machine-readable | +| Epic completion | Next epic | Epic gate above passes; residual risks recorded | +| RC qualification | Publication | Complete signed same-RC evidence, no prohibited waiver or missing run | diff --git a/docs/bmad-reconciliation-20261003.md b/docs/bmad-reconciliation-20261003.md new file mode 100644 index 0000000..7691e04 --- /dev/null +++ b/docs/bmad-reconciliation-20261003.md @@ -0,0 +1,21 @@ +# Согласование Git и BMAD — 2026-10-03 + +## Выполнено + +- История origin/main (82b215d) согласована с локальной интеграцией (3e801da). +- Merge fed5b7d сохраняет дерево 3e801da без изменений: прежняя серверная 2.10 заменена более новой реализацией ImportPlan ecfb4e7. Оба набора коммитов остаются в истории. +- Закрытые истории 2.10–2.14 уже входят в локальный main. Сохранённая попытка 2.12 0dbbff2 имеет то же дерево, что принятый ab35d67. +- Ветка maintenance/reconcile-20261003 сохраняет локальные planning/implementation/test artifacts и project-context, ранее исключённые из Git. Runtime loop, render и party-mode остаются локальными. + +## Работающая 2.15 + +На момент снимка loop 20261001-210704-f6bc показывает dev-running для 2-15-openapi-guided-onboarding. Работа ведётся в отдельном worktree. Значение backlog в сохранённом sprint-status.yaml не является доказательством отсутствия разработки. Этот снимок не должен перезаписывать более свежие артефакты работающего loop. + +После завершения 2.15 перед интеграцией этой ветки обновить копии sprint-status.yaml и прочих изменившихся BMAD-артефактов из целевого main и принятого результата story. Не переносить runtime state.json и не менять его вручную. + +## Ограничения приёмки + +- 2.12 закрыта с DW-3: Reference end-to-end p95 ≤2 s ещё не подтверждён после deployment. +- Невлитые старые attempt/rescue/loop ветки сохранены. Их нельзя массово вливать: часть содержит предыдущие реализации, часть только сведения о блокерах. +- Проверка согласования истории и сохранности документов не заменяет повторный запуск функциональных тестов. Код приложения в рамках согласования не изменялся. +- Push в main запускает deployment через .gitea/workflows/ci.yml. Публикацию main выполнять только после согласования deployment.