feat(persistence): retention deletion legal-hold SQL contracts (0007)

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to TEPP are documented here. The format follows Keep a Chang
 
 ### Added
 
+- `persistence_postgres` retention/deletion/legal-hold (migration `0007`): policy rows, legal holds that block completed deletion, evidence tombstones without raw-source restore, and analysis exclusion for revoked/tombstoned documents.
 - `persistence_postgres` backup/restore integrity: restored snapshots stay unusable until tenant, canonical `SHA-256`, knowledge-cutoff eligibility, temporal window order, and append-only triggers revalidate; SQL probes raise `restore integrity failed` (ADR 0013).
 - `persistence_postgres` concurrent document-write stress: atomic revise `DO` block that requires exactly one open `system_to` close, SQLSTATE mapping onto `ConcurrentWriteConflict` / `DuplicateDocumentRecord`, and live multi-session insert/revise/append-only proofs. No new migration number.
 - `tepp_api` naruon HTTP interchange: versioned `https` POST contracts for analysis-run create and modular export authorization that refuse table-access URLs, review/Copilot credential headers, reserved standard-header redefinition, principal-only export idempotency keys, and lexical inference claims (ADR 0011).

DOCUMENTATION.md

@@ -33,6 +33,7 @@ TEPP's approved PRD v0.4 and implementation plan are the primary product baselin
 | Hourly NIM product-development operations | [`docs/operations/HOURLY_NIM_PRODUCT_DEVELOPMENT.md`](docs/operations/HOURLY_NIM_PRODUCT_DEVELOPMENT.md) |
 | Actions workflow fleet audit | [`docs/operations/ACTIONS_WORKFLOW_FLEET.md`](docs/operations/ACTIONS_WORKFLOW_FLEET.md) |
 | Actions fleet research doctoring | [`docs/research/actions-workflow-fleet.md`](docs/research/actions-workflow-fleet.md) |
+| Retention/deletion/legal-hold doctoring | [`docs/research/retention-deletion-legal-hold.md`](docs/research/retention-deletion-legal-hold.md) |
 | Hourly NIM OpenCode doctoring | [`docs/doctoring/hourly-nim-opencode-development.md`](docs/doctoring/hourly-nim-opencode-development.md) |
 | Change history | [`CHANGELOG.md`](CHANGELOG.md) |
 

crates/persistence_postgres/src/artifact_sql.rs

@@ -222,6 +222,10 @@ mod tests {
         with_ref.source_size_bytes = 0;
         let referenced = insert_source_artifact_sql(&with_ref).expect("ref");
         assert!(referenced.contains("s3://tepp/object"));
+        let referenced_assertion =
+            assert_source_artifact_matches_sql(&with_ref).expect("referenced assertion");
+        assert!(referenced_assertion.contains("s3://tepp/object"));
+        assert!(referenced_assertion.contains("IS NOT DISTINCT FROM 's3://tepp/object'"));
 
         assert_eq!(
             insert_source_artifact_sql(&SourceArtifactRecord {

crates/persistence_postgres/src/document_sql.rs

@@ -68,21 +68,16 @@ pub fn revise_document_sqls(record: &DocumentRecord) -> Result<[String; 2], Pers
 pub fn revise_document_atomic_sql(record: &DocumentRecord) -> Result<String, PersistenceError> {
     let insert = insert_document_sql(record)?;
     Ok(format!(
-        "DO $tepp$ \
-         DECLARE closed_count integer; \
-         BEGIN \
-           PERFORM 1 FROM document_record \
-            WHERE document_record_id = '{document_id}'::uuid AND system_to IS NULL \
-            FOR UPDATE NOWAIT; \
-           UPDATE document_record SET system_to = '{system_from}'::timestamptz \
-            WHERE document_record_id = '{document_id}'::uuid AND system_to IS NULL; \
-           GET DIAGNOSTICS closed_count = ROW_COUNT; \
-           IF closed_count <> 1 THEN \
-             RAISE EXCEPTION 'concurrent document revision conflict' \
-               USING ERRCODE = 'serialization_failure'; \
-           END IF; \
-           {insert}; \
-         END $tepp$",
+        "DO $tepp$ DECLARE closed_count integer; BEGIN \
+         PERFORM 1 FROM document_record WHERE document_record_id = '{document_id}'::uuid \
+         AND system_to IS NULL FOR UPDATE NOWAIT; \
+         UPDATE document_record SET system_to = '{system_from}'::timestamptz \
+         WHERE document_record_id = '{document_id}'::uuid AND system_to IS NULL; \
+         GET DIAGNOSTICS closed_count = ROW_COUNT; \
+         IF closed_count <> 1 THEN \
+         RAISE EXCEPTION 'concurrent document revision conflict' \
+         USING ERRCODE = 'serialization_failure'; END IF; \
+         {insert}; END $tepp$",
         system_from = record.system_from.to_rfc3339(),
         document_id = record.document_record_id,
     ))

crates/persistence_postgres/src/error.rs

@@ -42,6 +42,12 @@ pub enum PersistenceError {
     ConcurrentWriteConflict,
     /// A restored snapshot failed integrity revalidation and is not usable.
     RestoreIntegrityFailed,
+    /// A retention, hold, deletion, or tombstone record failed closed validation.
+    InvalidRetentionLifecycle,
+    /// An active legal hold blocked completed deletion.
+    LegalHoldBlocksDeletion,
+    /// Tombstoned evidence cannot be restored, and raw-source deletion cannot keep reproduction available.
+    UngovernedEvidenceRestore,
 }
 
 impl fmt::Display for PersistenceError {
@@ -65,6 +71,9 @@ impl fmt::Display for PersistenceError {
             Self::InvalidAuditEvent => "invalid audit event",
             Self::ConcurrentWriteConflict => "concurrent write conflict",
             Self::RestoreIntegrityFailed => "restore integrity failed",
+            Self::InvalidRetentionLifecycle => "invalid retention lifecycle",
+            Self::LegalHoldBlocksDeletion => "legal hold blocks deletion",
+            Self::UngovernedEvidenceRestore => "ungoverned evidence restore",
         };
         formatter.write_str(message)
     }
@@ -96,6 +105,8 @@ pub enum MigrationContractError {
     MissingAppendOnlyTrigger,
     /// Temporal interval ordering checks were incomplete when declared.
     MissingTemporalIntervalConstraint,
+    /// Retention/legal-hold migration declarations were incomplete.
+    MissingRetentionLegalHold,
 }
 
 impl fmt::Display for MigrationContractError {
@@ -111,6 +122,7 @@ impl fmt::Display for MigrationContractError {
             Self::MissingTenantSessionGuc => "missing tenant session guc",
             Self::MissingAppendOnlyTrigger => "missing append-only immutability trigger",
             Self::MissingTemporalIntervalConstraint => "missing temporal interval constraint",
+            Self::MissingRetentionLegalHold => "missing retention legal hold",
         };
         formatter.write_str(message)
     }
@@ -197,6 +209,18 @@ mod tests {
             PersistenceError::RestoreIntegrityFailed.to_string(),
             "restore integrity failed"
         );
+        assert_eq!(
+            PersistenceError::InvalidRetentionLifecycle.to_string(),
+            "invalid retention lifecycle"
+        );
+        assert_eq!(
+            PersistenceError::LegalHoldBlocksDeletion.to_string(),
+            "legal hold blocks deletion"
+        );
+        assert_eq!(
+            PersistenceError::UngovernedEvidenceRestore.to_string(),
+            "ungoverned evidence restore"
+        );
         assert_eq!(
             MigrationContractError::SingleWordObjectName.to_string(),
             "single-word database object name"
@@ -237,5 +261,9 @@ mod tests {
             MigrationContractError::MissingTemporalIntervalConstraint.to_string(),
             "missing temporal interval constraint"
         );
+        assert_eq!(
+            MigrationContractError::MissingRetentionLegalHold.to_string(),
+            "missing retention legal hold"
+        );
     }
 }

crates/persistence_postgres/src/lib.rs

@@ -19,7 +19,9 @@
 //! exactly one open row to close, and live `SQLx` maps racing SQLSTATEs onto
 //! typed conflict errors. Restore integrity probes refuse to mark analytical
 //! state usable until tenant, digest, cutoff, temporal windows, and append-only
-//! triggers revalidate.
+//! triggers revalidate. Retention, deletion, and legal-hold SQL (migration
+//! `0007`) records policy-driven lifecycle without restoring tombstoned
+//! evidence or completing a deletion under an active hold.
 
 mod artifact_sql;
 mod concurrent_write;
@@ -38,6 +40,7 @@ mod model_run_sql;
 mod naming;
 mod relation_sql;
 mod restore_integrity;
+mod retention_sql;
 mod sql_session;
 mod sqlx_gate;
 #[cfg(feature = "live-sqlx")]
@@ -164,6 +167,30 @@ pub use restore_integrity::backup_scope_tables;
 pub use restore_integrity::mark_restored_state_usable;
 /// SQL probes that fail closed on unusable restored rows.
 pub use restore_integrity::restore_integrity_probe_sqls;
+/// Auditable deletion request row.
+pub use retention_sql::DeletionRequestRecord;
+/// Append-only evidence tombstone row.
+pub use retention_sql::EvidenceTombstoneRecord;
+/// Legal or contractual hold row.
+pub use retention_sql::LegalHoldRecord;
+/// Tenant-scoped retention policy row.
+pub use retention_sql::RetentionPolicyRecord;
+/// Render insert SQL for a completed deletion after hold evaluation.
+pub use retention_sql::insert_completed_deletion_request_sql;
+/// Render insert SQL for a validated deletion request.
+pub use retention_sql::insert_deletion_request_sql;
+/// Render insert SQL for a validated evidence tombstone.
+pub use retention_sql::insert_evidence_tombstone_sql;
+/// Render insert SQL for a validated legal hold.
+pub use retention_sql::insert_legal_hold_sql;
+/// Render insert SQL for a validated retention policy.
+pub use retention_sql::insert_retention_policy_sql;
+/// Render SQL that releases one active legal hold.
+pub use retention_sql::release_legal_hold_sql;
+/// Render active-analysis selection that excludes revoked or tombstoned documents.
+pub use retention_sql::select_active_analysis_document_sql;
+/// Render supersede SQL for a successive retention policy.
+pub use retention_sql::supersede_retention_policy_sql;
 /// Recording SQL transport for offline contract tests.
 pub use sql_session::RecordingSqlSession;
 /// Live SQL transport contract.