feat(datasources): govern approvals and retention

docs/CONCEPT.md

@@ -88,6 +88,21 @@ The first slice stores bounded tabular JSON/CSV stages. Future providers may
 stage file references, object-store blobs, directory snapshots, or streaming
 checkpoints through the same lifecycle contract.
 
+Valid stages may be subject to a versioned local approval policy. Required
+quorums keep the stage non-consumable, enforce distinct attributable actors and
+optional creator/approver separation, and bind every decision to exact policy
+and subject hashes. Cached refreshes use this same staging path when approval is
+required. An installation without separate Access or Policy modules retains
+safe local scope and policy defaults; optional modules do not manufacture an
+approval from configuration metadata.
+
+Retention policy separately defines durations for stages, ordinary
+materializations, and frozen evidence. Administrators receive a deterministic
+plan before applying any disposition. Holds, current state, pending decisions,
+and publication evidence are blockers. Payload disposal preserves a minimized
+materialization tombstone and hash-chained lifecycle evidence, so chronological
+authority and policy proof survive the configured content-retention boundary.
+
 ## Consumer Contract
 
 Consumers request:

docs/QUALITY_POLICY.md

@@ -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.