crank/docs/operation-lifecycle.md

Operation lifecycle contract

This contract is the executable oracle for Community Operation lifecycle.

State and revision model

• Aggregate availability is active or archived.
• A version is draft or published; legacy testing remains read-compatible only.
• Every changed save appends exactly one monotonic version. Existing version payloads are never updated.
• PostgreSQL rejects direct Published payload mutation and direct deletion/rewind of publication pointers.
• New Agent bindings lock referenced Operation rows and reject archived aggregates; existing published Agent snapshots remain executable.
• Publishing is limited to the current active Draft. Retrying the already published current version is idempotent; an older pointer is never restored.
• Editing published content appends the next Draft. An Agent keeps its exact pinned Operation version until an explicit Agent lifecycle change.
• Archiving changes aggregate availability only. Existing versions, published pointers, Agent snapshots and Invocation History remain unchanged.
• Hard delete is limited to an active, never-published Draft without durable references.

Conditional mutation contract

Aggregate reads return a strong state ETag bound to workspace, Operation identity, current version, availability, latest published version and representation version. Mutations of an existing Operation require that token in If-Match. Missing and stale preconditions return deterministic 428 and 409 outcomes. Exact version reads use a separate content-stable ETag.

Portable YAML

Canonical export uses format_version: "2". Legacy version 1 is import-only and is normalized into v2. The body limit is 256 KiB; one document, depth 64, at most 20,000 nodes, 4,096 collection items and 64 KiB line/scalar values are accepted. Credentials, URL userinfo, storage paths and persistence/runtime-only metadata are never portable.

Stable failure codes

• operation_precondition_required
• operation_stale_version
• operation_invalid_transition
• operation_archived
• operation_publish_blocked
• operation_delete_forbidden
• operation_yaml_too_large
• operation_yaml_invalid
• operation_yaml_unsupported
• operation_yaml_conflict