# 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`