--- id: STATE-PFM-TNL-004 title: Deletion request object: DOM-PFM-TNL-005 product_area: platform module: tenant-lifecycle revision: 1 status: draft design_intent: confirmed origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§5.1 States, §5.4 (approved 2026-10-09) implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 states: - name: scheduled meaning: The decision waits for eligibility and satisfied notice obligations. - name: held meaning: The decision is paused by staff or by failed requester-authority checks. - name: cancelled meaning: The reversible decision was withdrawn and remains in history. - name: executing meaning: The decision is irreversible and its purge is underway. - name: failed meaning: Removal stopped and needs forward recovery while the workspace stays deleting. - name: completed meaning: Database removal completed; external completion work can still fail. transitions: - from: scheduled to: held trigger: Staff place a scheduled request on hold. guard: The reviewed version matches and the reason has ten to two thousand characters. side_effects: - Record hold actor, time and explanation; owe a hold notice. - Retain the eligibility instant. who: Rhythm staff with hold authority provenance: observed source: services-platform:modules/tenants/services/deletion/deletion-holds.ts:holdTenantDeletion - from: scheduled to: held trigger: Irreversible-removal checks find that the requester lost authority. guard: Current grant evaluation fails deletion-request authority. side_effects: - Place the request on hold with an explanation for staff review. who: deletion schedule job provenance: observed source: services-platform:modules/tenants/services/deletion/begin-destruction.ts:beginTenantDestruction - from: held to: scheduled trigger: Staff release a held request. guard: The request is held, its reviewed version matches and a valid reason is supplied. side_effects: - Move eligibility to no earlier than three days from release. - Record release and a new final-reminder obligation. who: Rhythm staff with hold authority provenance: observed source: services-platform:modules/tenants/services/deletion/deletion-holds.ts:releaseTenantDeletion - from: scheduled to: cancelled trigger: Staff cancel a scheduled request. guard: The request remains reversible and its reviewed version and reason pass. side_effects: - Record cancellation and its notice obligation. - Return workspace lifecycle to active while retaining disabled business standing. who: Rhythm staff with cancel authority provenance: observed source: services-platform:modules/tenants/services/deletion/deletion-holds.ts:cancelTenantDeletion - from: held to: cancelled trigger: Staff cancel a held request. guard: The request remains reversible and its reviewed version and reason pass. side_effects: - Record cancellation and its notice obligation. - Return workspace lifecycle to active while retaining disabled business standing. who: Rhythm staff with cancel authority provenance: observed source: services-platform:modules/tenants/services/deletion/deletion-holds.ts:cancelTenantDeletion - from: scheduled to: executing trigger: The current watcher passes the irreversible-removal decision. guard: The locked request is eligible and scheduled, required notices are satisfied, the workspace meets removal conditions and the requester remains authorized. side_effects: - Commit deleting workspace, executing request, executing notice and purge job together. who: deletion schedule job provenance: observed source: services-platform:modules/tenants/services/deletion/begin-destruction.ts:beginTenantDestruction - from: executing to: completed trigger: The purge finalization completes database removal. guard: Participant inventory finds no removable declared resources. side_effects: - Remove workspace records and optionally its final customer. - Record completion, counts and verification. - Attempt due notices and write the external ledger after database completion. who: purge job provenance: observed source: services-platform:modules/tenants/services/deletion/tenant-purge-operations.ts:tenantPurgeOperations - from: executing to: failed trigger: The purge is settled failed. guard: The request is executing and still names the failing job. side_effects: - Record the safe failure summary and attempt the failure notice. - Keep workspace lifecycle deleting. who: purge job or jobs reconciler provenance: observed source: services-platform:modules/tenants/services/deletion/tenant-purge-failure.ts:applyTenantPurgeFailure - from: failed to: executing trigger: Staff retry failed removal. guard: The request is failed and its workspace remains deleting. side_effects: - Create a linked retry carrying completed steps and repoint the request. - Refuse subsequent work from superseded jobs. who: Rhythm staff with deletion-request authority provenance: observed source: services-platform:modules/tenants/services/deletion/operator-recovery.ts:retryTenantPurge invalid: - from: executing to: cancelled why: Cancellation is refused after execution begins, before the reviewed version is compared. - from: executing to: held why: Execution cannot be paused through preservation actions. - from: held to: executing why: A held decision needs release and its extended wait before execution. - from: cancelled to: scheduled why: Another decision needs a new request and waiting period. - from: completed to: executing why: Completion remains terminal; restore recovery creates separate removal work. - from: failed to: cancelled why: Partial removal cannot be preserved through cancellation. concurrency: Conditional request updates and row locks arbitrate preservation against destruction. Watcher and purge tasks check the job references before acting. The schedule sleeps in the state machine, rechecking conditions at recorded notice times and after retry waits; its execution is bounded to one year. invariants: - INV-DOM-PFM-TNL-005-01 - INV-DOM-PFM-TNL-005-04 - INV-DOM-PFM-TNL-005-05 - INV-DOM-PFM-TNL-005-06 - INV-DOM-PFM-TNL-005-08 evidence: - 'services-platform at ad3f6a65: modules/tenants/services/deletion/{request-deletion, deletion-holds, begin-destruction, tenant-purge-operations, tenant-purge-failure, operator-recovery}.ts; services/persistence/tenant-deletion-requests.ts; db/tenant-deletion-requests.table.ts.' --- # Deletion Request ## The Lifecycle ```mermaid stateDiagram-v2 [*] --> scheduled: deletion requested scheduled --> held: staff hold, or requester lost authority held --> scheduled: released, at least three more days scheduled --> cancelled: called off held --> cancelled: called off scheduled --> executing: point of no return executing --> completed: verified and finalized executing --> failed: purge stopped failed --> executing: staff retry cancelled --> [*] completed --> [*] ``` ## Transitions Explained A new request waits with fixed eligibility. Staff can hold, release or cancel it while reversible; release extends eligibility and creates another reminder. The watcher rechecks the locked decision and requester authority. Lost authority places it on hold, while passing checks commits execution and its purge job. Failed removal keeps destruction standing and permits forward retry. Database finalization records completion before notice and ledger work finishes, so completed standing does not prove every external obligation succeeded. ## What Cannot Happen Hold, release and cancellation cannot reverse executing or failed removal. Cancelled and completed decisions are historical records; new removal uses a new request. A held request must be released before the watcher can execute it. ## Concurrency and Timing Conditional request updates and row locks arbitrate preservation against destruction. Watcher and purge tasks check the job references before acting. The schedule sleeps in the state machine, rechecking conditions at recorded notice times and after retry waits; its execution is bounded to one year.