37 lines
2.2 KiB
Markdown
37 lines
2.2 KiB
Markdown
# 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`
|