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

52 KiB
Raw Blame History

story_id, story_key, requirement, status, baseline_commit
story_id story_key requirement status baseline_commit
1.7 1-7-immutable-lifecycle-operation FR-1 done 767428436d

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

  • Task 1 — Freeze executable lifecycle/wire oracle before production changes (AC: 1–14)

    • 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.
    • Freeze transition table, current-version semantics, error codes, YAML bounds/canonical equality and delete/archive policy in tests/docs.
    • Verify Stories 1.1–1.6 contracts remain prerequisites: typed config only, MigrationAuthority-only DDL, canonical IDs, typed metrics and honest evidence.
  • Task 2 — Implement typed aggregate/version state model (AC: 1–2, 4–8)

    • Separate aggregate availability from version state without changing existing external enum spellings; expose explicit allowed transitions/no pointer rewind.
    • Add deterministic portable semantic fingerprint/equality excluding persistence metadata and secret values.
    • Add table-driven/property tests for legal/illegal transitions, monotonic versions, semantic no-op, archive/delete and rollback-as-new-version rules.
  • Task 3 — Add append-only Operation lifecycle migration v4 (AC: 1–5, 7–8, 14)

    • 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.
    • 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.
    • New v4 writes record native snapshot provenance and per-version publication metadata; exact reads stop joining mutable values for snapshot construction.
    • 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.
    • 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.
  • Task 4 — Make registry mutations transactional and concurrency-safe (AC: 1–5, 7–8, 10, 12)

    • Replace check-then-write with one transaction, scoped SELECT ... FOR UPDATE, expected current version/state and deterministic unique monotonic insert.
    • PATCH/create-version/upsert insert new immutable revision; semantic no-op returns current. Never UPDATE existing version payload.
    • Publish only current active Draft, prevent pointer rewind, make same-version retry idempotent and return typed stale/transition errors.
    • Archive only aggregate; hard delete only never-published/no-reference Draft; reject new archived bindings while preserving published Agent snapshots.
    • 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)

    • Validate complete Operation payload before save and immediately before publish; blocker findings cannot be bypassed via direct API.
    • 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.
    • 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)

    • Create closed Rust v2 DTO + checked operation-export-v2 schema; derive export/import projection from the same typed domain contract.
    • 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.
    • Preserve normalized target/schema/mapping/auth-ref/runtime/safety/tool semantics; exclude IDs/status/version/timestamps/samples/generated/wizard/internal metadata.
    • Implement 256 KiB/depth/node/item/scalar/document/alias/tag/duplicate-key/unknown-field limits before mutation; diagnostics bounded to 16 KiB and redacted.
    • 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.
  • Task 7 — Update Admin API contract without route churn (AC: 3–13)

    • 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.
    • 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.
    • 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.
    • 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.
    • 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)

    • Catalog/wizard show authoritative Draft/Published/current version/archive state; published edit creates next Draft; archive replaces delete for published Operations.
    • 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)

    • 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.
    • 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.
    • 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)

    • Update data model, Admin API/YAML, migration, UI/manual regression and operator recovery docs; clearly distinguish immutable Published Version from archived aggregate.
    • Update Capability Inventory/baseline with accepted automated evidence and increment exact-byte baseline version/checksums.
    • 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.

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
  • SQLx 0.9 documentation
  • PostgreSQL row-level locking
  • PostgreSQL trigger behavior

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

  • [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]
  • [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]
  • [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]
  • [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]
  • [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]
  • [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]
  • [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]
  • [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]
  • [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]
  • [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]
  • [Review][Patch] Return persisted publication/archive timestamps on idempotent retries instead of newly generated timestamps [apps/admin-api/src/service/operations.rs:438]
  • [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]
  • [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]
  • [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]
  • [Review][Patch] Reject YAML anchors/aliases before serde materializes them, with bounded regression fixtures [apps/admin-api/src/service/import_export.rs:260]
  • [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]
  • [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]
  • [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]
  • [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.