52 KiB
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
-
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.
-
Полный самостоятельный 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 сохраняются.
- Given Operation Version
-
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 409operation_stale_versionс current version и recovery action - And нет lost update, hybrid payload, duplicate version, gap, raw SQLx error или 5xx при 32-way contention.
- Given два клиента прочитали одну base version
-
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
operationsDELETE иON DELETE CASCADEpath.
-
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.
- Given Published Version
-
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-hextrace_id, tested version и bounded previews/errors без credential, raw upstream/parser cause или internal path - And historical Published/archived/foreign/nonexistent target не маскируется под Draft test.
- Given current saved Draft
-
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 остаётся доступен.
-
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 с явным подтверждением.
-
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, typedauth_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.
-
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 не меняются.
-
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.
-
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.
-
Полный 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.
-
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. Aggregatearchivedне переписывает 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
testingspelling остаётся deserialize-compatible, но test execution является событием над exact Draft и не сохраняет промежуточный version statetesting. - 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, восстанавливаемой из authoritativepublished_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_leveland currently observable contract fields; mark every legacy rowlegacy_observedat cutover. Backfillpublished_at/published_byonly 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.
- Add
-
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.
- Replace check-then-write with one transaction, scoped
-
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-v2schema; 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
--checkfails 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.
- Create closed Rust v2 DTO + checked
-
Task 7 — Update Admin API contract without route churn (AC: 3–13)
- Add scoped aggregate state
ETagon Operation reads/mutations and requireIf-Matchfor 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
Stringextraction 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.
- Add scoped aggregate state
-
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 exactvN; 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-outputare 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.rshas one conflatedOperationStatusand no transition/CAS model.crates/crank-registry/src/postgres/operation.rs::update_operation_draftupdates the currentoperation_versionsJSON row in place. Publish leavescurrent_draft_versionon that row, so the next UI PATCH rewrites Published behavior.- Exact version builders and Agent/MCP queries currently obtain
name,display_name,category,protocolandsecurity_levelfrom mutableoperations; pinning(operation_id,version)alone is therefore insufficient. create_versioncomputes next version before transaction/lock.publish_operationaccepts any existing version and upserts a latest pointer without monotonic/state/archive guard.archive_operationmutates 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 rawserde_yamlerrors, 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 incrank-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.sqldocs/schemas/operation-export-v2.schema.jsonapps/admin-api/tests/integration/operation_lifecycle.rsapps/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}, relevantapps/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.mdand 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.sqlor 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 versionaction 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
7674284freezes Story 1.6 review evidence;b7face0contains 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
HEADwhendev-storystarts; 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 unboundedString. - Locked SQLx 0.9 supports explicit PostgreSQL transactions and bound queries. Row-level
SELECT ... FOR UPDATEprotects 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+deprecatedis 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=1reproduced 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-Matchpart 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_refin 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_operationsandoperations.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
StringRejectionvalues 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::MAXand 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.rsapps/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.rscrates/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.mddocs/schemas/{migration-sequence.json,operation-export-v2.schema.json}docs/capability-inventory.jsondocs/capability-baseline/{manifest.json,manual-checklist.md,outcome-taxonomy.json,required-surfaces.json,results.json}scripts/authenticated-product-smoke.pytests/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.