---
id: WF-PFM-TNL-013
title: Purge a workspace and prove it is gone
trigger: Remove declared participant resources, verify reported leftovers and retain deletion completion evidence.
product_area: platform
module: tenant-lifecycle
revision: 1
status: draft
design_intent: confirmed
origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§5.9 Final sweep, §5.10, §6.2, §6.4, §9 (approved
  2026-10-09; D5 Andrew 2026-10-09)
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
  services-committees: 36129c24daeaadcdb339218c38cdeaff9861359d
  services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893
  services-submissions: 64236c19be89579ef5897aad7de3925ed3ce03bf
  services-websites: 5fc6823c69d5e6f208c21dba8c0eb3132f8bdc4c
  services-marketing: d071a159fe9782bb71ff246d5c67d5bbfe07fbfa
implements:
- CAP-PFM-TNL-017
- CAP-PFM-TNL-018
- CAP-PFM-TNL-007
moves:
- STATE-PFM-TNL-001
- STATE-PFM-TNL-004
- STATE-PFM-TNL-005
- STATE-PFM-TNL-006
crosses:
- SVC-PFM-TNL-tenants
- SVC-PFM-TNL-crm-tenant-lifecycle
- SVC-PFM-TNL-commerce-tenant-lifecycle
- SVC-PFM-TNL-committees-tenant-lifecycle
- SVC-PFM-TNL-membership-tenant-lifecycle
- SVC-PFM-TNL-submissions-tenant-lifecycle
- SVC-PFM-TNL-marketing-tenant-lifecycle
- SVC-PFM-SEC-security
idempotency: Repeated batches work toward empty resources. Completed request replay can finish external work, but
  failure after workspace removal and before completion is not recoverable through ordinary retry.
concurrency: Tasks check the current purge reference and deleting standing. Finalization has separate commits, and
  function concurrency differs by application.
hops:
- n: 1
  actor_or_service: Purge job (publish)
  action: Check live removal order against the job catalog before publishing its steps.
  anchor: services-platform:modules/tenants/services/deletion/tenant-purge-operations.ts:tenantPurgeOperations
  seam: state_machine
  on_failure: Refuse mismatched order and apply failure consequences.
  left_inconsistent: Earlier attempts can already have removed resources.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/deletion/tenant-purge-operations.ts
- n: 2
  actor_or_service: Purge job (flush authorizer)
  action: Submit the authorizer-flush job and clear local availability without awaiting flush completion.
  anchor: services-platform:modules/tenants/services/deletion/tenant-purge-operations.ts
  seam: state_machine
  on_failure: Use the flush service’s logged failure handling.
  left_inconsistent: Previously cached authority can survive until its own expiry.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/deletion/tenant-purge-operations.ts
- n: 3
  actor_or_service: Purge job (participant steps)
  action: In reverse dependency order, verify job ownership, run one batch and record returned counts before looping.
  anchor: services-platform:modules/tenants/services/deletion/tenant-purge-operations.ts:purgeParticipant
  seam: state_machine
  on_failure: Retry eligible faults; a blocked response refuses the purge.
  left_inconsistent: Committed batches remain removed, and lost results can understate totals.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/deletion/tenant-purge-operations.ts:requirePurgeAuthority
- n: 4
  actor_or_service: Application participants
  action: Apply each participant’s scoped database or provider removal, including protected histories and delimited
    storage prefixes.
  anchor: services-crm:modules/tenant-lifecycle/services/participants/purge-batches.ts
  seam: sync
  on_failure: Return participant errors to the purge task.
  left_inconsistent: The participant can remain partly removed.
  observer: Job progress and service logs.
  provenance: observed
  source: services-committees:modules/tenant-lifecycle/services/persistence/tenant-purges.ts
- n: 5
  actor_or_service: Purge job (verify)
  action: Count removable inventories, repeating removal when nonzero and refusing after the bounded verification
    rounds.
  anchor: services-platform:modules/tenants/services/deletion/tenant-purge-operations.ts:inventoryAll
  seam: state_machine
  on_failure: Fail with resource counts when the sweep bound is reached.
  left_inconsistent: Declared leftovers remain; omitted resources are outside this proof.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/deletion/tenant-purge-workflow.ts:TENANT_PURGE_VERIFICATION_ROUNDS
- n: 6
  actor_or_service: Purge job (finalize)
  action: Remove final customer security when requested, remove the workspace, then record counts, optional customer
    removal and request completion.
  anchor: services-platform:modules/tenants/services/deletion/tenant-purge-operations.ts:tenantPurgeOperations
  seam: state_machine
  on_failure: A later failure can make retry refuse the already-missing workspace.
  left_inconsistent: The workspace can be gone while its decision, counts and customer work remain unfinished.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/deletion/tenant-purge-operations.ts
- n: 7
  actor_or_service: Purge job (finalize)
  action: Attempt completion notices and write the external deletion ledger.
  anchor: services-platform:modules/tenants/services/deletion/deletion-ledger.ts:writeTenantDeletionLedgerEntry
  seam: state_machine
  on_failure: Retry the task; exhausted ledger failure leaves completed request standing untouched.
  left_inconsistent: The completed deletion can lack its external ledger with no ordinary recovery route.
  observer: Job progress and service logs.
  provenance: inferred
  source: services-platform:modules/tenants/services/deletion/tenant-purge-failure.ts:applyTenantPurgeFailure
- n: 8
  actor_or_service: Purge failure consequence
  action: On settled failure, fail an executing request that still names this job and attempt its failure notice.
  anchor: services-platform:modules/tenants/services/deletion/tenant-purge-failure.ts:applyTenantPurgeFailure
  seam: sync
  on_failure: Ignore stale consequences and log notice delivery errors.
  left_inconsistent: Partial destruction remains and the workspace is not reopened.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/deletion/tenant-purge-failure.ts
branches:
- Linked recovery carries completed participant steps.
- Final-customer removal requires the requester’s choice and no remaining sibling workspace.
waits:
- Purge execution is bounded to twenty-four hours.
evidence:
- 'services-platform at ad3f6a65: modules/tenants/services/deletion/{tenant-purge-workflow, tenant-purge-operations,
  tenant-purge-failure, deletion-ledger}.ts; services/lifecycle/{participants, purge-batches, asset-prefix-store}.ts;
  aws/logic/tenant-purge.step-function.ts; aws/resources/tenant-deletion-ledger.s3.ts.'
- 'services-crm, services-committees, services-membership, services-marketing, services-commerce, services-submissions
  at their pinned commits: participant purge implementations.'
- 'FND-PFM-TNL-051: finalization has no transaction spanning workspace removal and request completion.'
controls: [TC-AVL-001, TC-AVL-002, TC-AVL-003, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-DAT-006, TC-DAT-007, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Purge A Workspace And Prove It Is Gone

## What It Does

Remove declared participant resources, verify reported leftovers and retain deletion completion evidence. Repeated batches work toward empty resources. Completed request replay can finish external work, but failure after workspace removal and before completion is not recoverable through ordinary retry.

## The Flow

```mermaid
sequenceDiagram
  autonumber
  participant Job as Purge job
  participant Sec as Security authorizer flush
  participant PFM as Platform participants
  participant Apps as Application lifecycle functions
  participant DB as Platform database
  participant Led as Deletion ledger
  Job->>Job: live plan equals planned steps?
  Job->>Sec: flush cached decisions
  loop each participant, reverse build order
    loop until done
      Job->>DB: request names this job, workspace deleting?
      Job->>PFM: purge one batch (or Apps)
      Job->>DB: add batch counts
    end
  end
  Job->>PFM: inventory (and Apps)
  alt anything left (at most three rounds)
    Job->>Job: purge round again
  end
  Job->>DB: remove workspace record, complete request
  Job->>Led: completed notice, ledger entry
```

## When Something Fails

Refuse mismatched order and apply failure consequences. Earlier attempts can already have removed resources. Use the flush service’s logged failure handling. Previously cached authority can survive until its own expiry. Retry eligible faults; a blocked response refuses the purge. Committed batches remain removed, and lost results can understate totals. Return participant errors to the purge task. The participant can remain partly removed. Fail with resource counts when the sweep bound is reached. Declared leftovers remain; omitted resources are outside this proof. A later failure can make retry refuse the already-missing workspace. The workspace can be gone while its decision, counts and customer work remain unfinished. Retry the task; exhausted ledger failure leaves completed request standing untouched. The completed deletion can lack its external ledger with no ordinary recovery route. Ignore stale consequences and log notice delivery errors. Partial destruction remains and the workspace is not reopened.

## Open Design Questions

Complete deletion cannot be claimed for disabled or unimplemented resources. Finalization needs recovery for missing-workspace and missing-ledger failure windows.