Files
crank/_bmad-output/implementation-artifacts/1-7-immutable-lifecycle-operation.md
T

488 lines
52 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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 <every NEW/UPDATE tracked candidate>
```
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.