feat: complete Epic 1 production foundation

2026-08-25 01:24:11 +03:00
parent 767428436d
commit 182bde8ac0
298 changed files with 35719 additions and 5299 deletions
@@ -0,0 +1,36 @@
+# 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`