feat(datasources): govern approvals and retention

2026-08-22 19:37:44 +02:00
parent b54d1919e4
commit 7a7654cc0f
24 changed files with 2753 additions and 28 deletions
@@ -116,6 +116,59 @@ replace the Datasource's current state. Valid warnings produce
 catalogue side effect. These terminal states are preserved for Dataflow and
 Workflow handoffs instead of being collapsed into generic success.

-Approval authority, approval expiry, and retention/deletion execution remain
-separate work under `govoplan-datasources#2`. Until those contracts are added,
-no JSON flag is treated as an approval and no stage is deleted automatically.
+## Promotion approval
+
+Approval is a separate deterministic contract in
+`governance.approval_policy`:
+
+```json
+{
+  "version": "monthly-promotion-v2",
+  "required": true,
+  "required_approvals": 2,
+  "separation_of_duties": true,
+  "expires_after_hours": 72,
+  "policy_ref": "policy:monthly-register-promotion"
+}
+```
+
+A valid stage enters `awaiting_approval` instead of `ready`. Each decision is
+bound to the stage fingerprint, quality-policy hash, normalized approval-policy
+hash, actor authority, reason, and expiry. Actors are distinct and the stage
+creator cannot approve when separation of duties is enabled. The exact quorum
+snapshot and hash-chained evidence are copied into materialization provenance.
+A changed target policy or staged subject requires a new stage; request JSON
+cannot claim that an approval occurred.
+
+Cached origins use `POST /datasources/{id}/refresh/stage` when approval is
+required. Direct refresh then fails closed, so connector content cannot become
+current before the staged validation and approval quorum succeed.
+
+## Retention
+
+Retention is independently configured in `governance.retention_policy`:
+
+```json
+{
+  "version": "register-retention-v3",
+  "enabled": true,
+  "stage_days": 30,
+  "materialization_days": 365,
+  "frozen_evidence_days": 3650,
+  "policy_ref": "policy:register-retention"
+}
+```
+
+Durations are optional; omitting a class retains it indefinitely. Empty or
+disabled local policy never deletes content. An administrator first requests a
+read-only plan. The plan includes all due targets, policy versions and hashes,
+eligibility dates, blockers, and one hash over the complete preview. Applying
+retention accepts only targets from the unchanged plan.
+
+Pending approvals, current materializations, legal holds, and materializations
+referenced by producer publications are blocked. Eligible stages are deleted.
+Eligible materialization payload rows are purged while the revision retains its
+schema, provenance, row/byte counts, payload checksum, disposition metadata,
+and immutable hash-chained lifecycle evidence. Frozen evidence is eligible only
+when `frozen_evidence_days` is explicitly configured. No hidden scheduler or
+arbitrary Policy/Access flag performs deletion.