feat: define governed tenant erasure contracts

tests/test_module_system.py

@@ -344,6 +344,18 @@ class ModuleSystemTests(unittest.TestCase):
         self.assertTrue(scopes_grant_compatible(["access:membership:read"], "admin:users:read"))
         self.assertTrue(scopes_grant_compatible(["admin:users:read"], "access:membership:read"))
         self.assertTrue(scopes_grant_compatible(["access:tenant:read"], "system:tenants:read"))
+        self.assertTrue(
+            scopes_grant_compatible(
+                ["access:tenant:erase"],
+                "system:tenants:erase",
+            )
+        )
+        self.assertFalse(
+            scopes_grant_compatible(
+                ["system:tenants:write"],
+                "system:tenants:erase",
+            )
+        )
         self.assertTrue(scopes_grant_compatible(["system:*"], "access:tenant:read"))
         self.assertTrue(
             scopes_grant_compatible(
@@ -1015,8 +1027,10 @@ finally:
                         json={"mode": "destroy", "reason": "not supported"},
                     )
                     self.assertEqual(409, destructive.status_code, destructive.text)
-                    issue_codes = {item["code"] for item in destructive.json()["detail"]["plan"]["issues"]}
-                    self.assertIn("tenant_data_present", issue_codes)
+                    self.assertIn(
+                        "Direct destructive deletion is disabled",
+                        destructive.json()["detail"]["message"],
+                    )
 
                     with database.session() as session:
                         empty_tenant = Tenant(
@@ -1029,15 +1043,43 @@ finally:
                         session.commit()
                         empty_tenant_id = empty_tenant.id
 
-                    destroyed = client.request(
-                        "DELETE",
-                        f"/api/v1/admin/tenants/{empty_tenant_id}",
+                    erasure_policy = client.patch(
+                        "/api/v1/admin/tenant-erasure-policy",
                         headers=headers,
-                        json={"mode": "destroy", "reason": "empty tenant cleanup"},
+                        json={
+                            "production_profile": False,
+                            "required_approvals": 1,
+                            "preview_ttl_seconds": 900,
+                            "recent_authentication_seconds": 900,
+                        },
                     )
-                    self.assertEqual(200, destroyed.status_code, destroyed.text)
-                    self.assertEqual("destroy", destroyed.json()["plan"]["action"])
-                    self.assertTrue(destroyed.json()["plan"]["destructive_supported"])
+                    self.assertEqual(200, erasure_policy.status_code, erasure_policy.text)
+                    erasure_preview = client.post(
+                        f"/api/v1/admin/tenants/{empty_tenant_id}/erasure-operations",
+                        headers=headers,
+                        json={
+                            "idempotency_key": f"empty-destroy-{name}",
+                            "reason": "empty tenant cleanup",
+                        },
+                    )
+                    self.assertEqual(201, erasure_preview.status_code, erasure_preview.text)
+                    self.assertTrue(erasure_preview.json()["preview"]["allowed"])
+                    operation_id = erasure_preview.json()["id"]
+                    approved_erasure = client.post(
+                        f"/api/v1/admin/tenants/{empty_tenant_id}/erasure-operations/{operation_id}/approve",
+                        headers=headers,
+                        json={"confirmation": f"empty-destroy-{name}"},
+                    )
+                    self.assertEqual(200, approved_erasure.status_code, approved_erasure.text)
+                    self.assertEqual("ready", approved_erasure.json()["state"])
+                    executed_erasure = client.post(
+                        f"/api/v1/admin/tenants/{empty_tenant_id}/erasure-operations/{operation_id}/execute",
+                        headers=headers,
+                        json={"confirmation": f"empty-destroy-{name}"},
+                    )
+                    self.assertEqual(200, executed_erasure.status_code, executed_erasure.text)
+                    self.assertEqual("completed", executed_erasure.json()["state"])
+                    self.assertIsNone(executed_erasure.json()["reason"])
 
                     retired = client.request(
                         "DELETE",

tests/test_tenant_erasure_contract.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from types import SimpleNamespace
+
+import pytest
+
+from govoplan_core.core.tenant_erasure import (
+    TENANT_ERASURE_PROVIDER_CAPABILITY_PREFIX,
+    TenantErasurePreview,
+    TenantErasureResource,
+    TenantErasureStep,
+    TenantErasureStepResult,
+    collect_tenant_erasure_inventory,
+    tenant_erasure_providers,
+)
+
+
+class _Provider:
+    module_id = "files"
+
+    def preview_tenant_erasure(self, session, tenant_id: str) -> TenantErasurePreview:
+        del session
+        assert tenant_id == "tenant-1"
+        return TenantErasurePreview(
+            module_id=self.module_id,
+            complete=True,
+            resources=(
+                TenantErasureResource(
+                    resource_type="file_blobs",
+                    count=2,
+                    disposition="erase",
+                    summary="Two tenant-owned file blobs will be erased.",
+                ),
+            ),
+            steps=(
+                TenantErasureStep(
+                    step_id="erase-blobs",
+                    kind="erase",
+                    summary="Erase tenant-owned file blobs.",
+                    destructive=True,
+                    irreversible=True,
+                ),
+            ),
+        )
+
+    def execute_tenant_erasure_step(
+        self, session, tenant_id: str, step_id: str, idempotency_key: str
+    ) -> TenantErasureStepResult:
+        del session, tenant_id, step_id, idempotency_key
+        return TenantErasureStepResult(
+            state="completed",
+            summary="Tenant file blobs erased.",
+            metrics={"deleted": 2},
+        )
+
+    def reconcile_tenant_erasure_step(
+        self, session, tenant_id: str, step_id: str, idempotency_key: str
+    ) -> TenantErasureStepResult:
+        return self.execute_tenant_erasure_step(
+            session, tenant_id, step_id, idempotency_key
+        )
+
+
+class _Registry:
+    def __init__(self, *, provider: object | None = None, counts: dict[str, int] | None = None):
+        self._provider = provider
+        self._counts = counts
+
+    def manifests(self):
+        return (
+            SimpleNamespace(id="core"),
+            SimpleNamespace(id="files"),
+            SimpleNamespace(id="wiki"),
+        )
+
+    def capability_names(self):
+        if self._provider is None:
+            return ()
+        return (f"{TENANT_ERASURE_PROVIDER_CAPABILITY_PREFIX}files",)
+
+    def capability(self, name: str):
+        assert name.endswith("files")
+        return self._provider
+
+    def tenant_summary_providers(self):
+        if self._counts is None:
+            return {}
+        return {"files": lambda _session, _tenant_id: self._counts}
+
+
+def test_contract_rejects_unsafe_irreversible_step() -> None:
+    with pytest.raises(ValueError, match="must be destructive"):
+        TenantErasureStep(
+            step_id="unsafe",
+            kind="erase",
+            summary="Invalid step.",
+            destructive=False,
+            irreversible=True,
+        )
+
+
+def test_contract_rejects_cyclic_step_dependencies() -> None:
+    with pytest.raises(ValueError, match="contain a cycle"):
+        TenantErasurePreview(
+            module_id="files",
+            complete=True,
+            steps=(
+                TenantErasureStep(
+                    step_id="first",
+                    kind="erase",
+                    summary="First.",
+                    destructive=True,
+                    irreversible=True,
+                    depends_on=("second",),
+                ),
+                TenantErasureStep(
+                    step_id="second",
+                    kind="verify",
+                    summary="Second.",
+                    destructive=False,
+                    irreversible=False,
+                    depends_on=("first",),
+                ),
+            ),
+        )
+
+
+def test_contract_requires_action_or_blocker_for_tenant_data() -> None:
+    resource = TenantErasureResource(
+        resource_type="files",
+        count=1,
+        disposition="erase",
+        summary="One file exists.",
+    )
+    with pytest.raises(ValueError, match="steps or an explicit blocker"):
+        TenantErasurePreview(
+            module_id="files",
+            complete=True,
+            resources=(resource,),
+        )
+
+
+def test_inventory_collects_provider_and_marks_non_data_modules() -> None:
+    inventory = collect_tenant_erasure_inventory(
+        _Registry(provider=_Provider()),
+        object(),
+        "tenant-1",
+        observed_at=datetime(2026, 8, 24, 12, 0, tzinfo=UTC),
+    )
+
+    assert inventory.complete
+    assert inventory.allowed
+    assert [item.module_id for item in inventory.modules] == ["core", "files", "wiki"]
+    assert inventory.modules[1].steps[0].irreversible
+    assert inventory.to_dict()["generated_at"] == "2026-08-24T12:00:00+00:00"
+
+
+def test_summary_fallback_blocks_when_data_exists() -> None:
+    inventory = collect_tenant_erasure_inventory(
+        _Registry(counts={"file_blobs": 3}),
+        object(),
+        "tenant-1",
+    )
+
+    files = next(item for item in inventory.modules if item.module_id == "files")
+    assert inventory.complete
+    assert not inventory.allowed
+    assert files.resources[0].disposition == "unavailable"
+    assert files.blockers == (
+        "Tenant-owned data exists but the module has no erasure provider.",
+    )
+
+
+def test_provider_identity_must_match_capability_suffix() -> None:
+    provider = _Provider()
+    provider.module_id = "mail"
+
+    with pytest.raises(ValueError, match="identity"):
+        tenant_erasure_providers(_Registry(provider=provider))