--- id: SVC-PFM-TNL-tenants title: Workspace Lifecycle Service (Platform) product_area: platform module: tenant-lifecycle repository: services-platform source_module: modules/tenants revision: 1 status: draft design_intent: confirmed origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§8.2 API (approved 2026-10-09); services-platform:docs/hq/rhythm-hq-plan.md#§H1 Permission catalog (approved 2026-10-11); services-platform:docs/data-jobs/tenant-reset.md#§4 The API implementation_evidence: observed inference: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 owns: - DOM-PFM-TNL-001 - DOM-PFM-TNL-002 - DOM-PFM-TNL-003 - DOM-PFM-TNL-004 - DOM-PFM-TNL-005 does_not_own: - Ordinary workspace records, administrative business standing and HQ browsing. - Customer and identity ownership, evaluated authority and standing staff grants. - Shared durable execution and reconciliation. - Import execution, uploads and Data Runs. - Whole-package export coordination and delivery. - Provider sender identity ownership and general communication delivery. - Application business records and participant implementations. operations: - operation_id: createTenant route: POST /tenants intent: Record workspace construction and submit its durable attempt, creating a customer when requested. access: system permission: hq.tenants.provision realises: - CAP-PFM-TNL-001 - CAP-PFM-TNL-004 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/tenants.routes.ts:createTenant - operation_id: getTenantProvisioning route: GET /tenants/{id}/provisioning intent: Inspect the workspace’s latest build attempt and execution details. access: system permission: hq.tenants.read realises: - CAP-PFM-TNL-003 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/tenants.routes.ts:getTenantProvisioning - operation_id: retryTenantProvisioning route: POST /tenants/{id}/provisioning/retry intent: Submit a linked recovery attempt for failed construction. access: system permission: hq.tenants.provision realises: - CAP-PFM-TNL-003 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/tenants.routes.ts:retryTenantProvisioning - operation_id: initializeTenant route: POST /tenants/{id}/initialization intent: Apply a selected participant’s configuration to an eligible existing workspace. access: system permission: hq.tenants.provision realises: - CAP-PFM-TNL-009 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/tenants.routes.ts:initializeTenant - operation_id: deleteTenant route: DELETE /tenants/{id} intent: Reject the retired immediate-removal operation and direct the caller to a deletion request. access: system permission: hq.tenants.update realises: - CAP-PFM-TNL-018 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/tenants.routes.ts:deleteTenant - operation_id: requestTenantDeletion route: POST /tenants/{id}/deletion_requests intent: Record a deliberate removal request, fixed eligibility and notice obligations. access: system permission: platform.tenants.deletion-request realises: - CAP-PFM-TNL-013 - CAP-PFM-TNL-015 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/tenant-deletion-requests.routes.ts:requestTenantDeletion - operation_id: listTenantDeletionRequests route: GET /tenant_deletion_requests intent: Read a paged deletion-decision history with standing and workspace filters. access: system permission: platform.tenants.deletion-read realises: - CAP-PFM-TNL-014 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/tenant-deletion-requests.routes.ts:listTenantDeletionRequests - operation_id: getTenantDeletionRequest route: GET /tenant_deletion_requests/{id} intent: Inspect one retained deletion decision and its notice records. access: system permission: platform.tenants.deletion-read realises: - CAP-PFM-TNL-014 - CAP-PFM-TNL-018 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/tenant-deletion-requests.routes.ts:getTenantDeletionRequest - operation_id: holdTenantDeletionRequest route: POST /tenant_deletion_requests/{id}/hold intent: Pause a scheduled deletion using a reason and reviewed version. access: system permission: platform.tenants.deletion-hold realises: - CAP-PFM-TNL-014 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/tenant-deletion-requests.routes.ts:holdTenantDeletionRequest - operation_id: releaseTenantDeletionRequest route: POST /tenant_deletion_requests/{id}/release intent: Release a hold with an extended eligibility floor and another final reminder. access: system permission: platform.tenants.deletion-hold realises: - CAP-PFM-TNL-014 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/tenant-deletion-requests.routes.ts:releaseTenantDeletionRequest - operation_id: cancelTenantDeletionRequest route: POST /tenant_deletion_requests/{id}/cancel intent: Withdraw a reversible deletion while keeping the workspace disabled. access: system permission: platform.tenants.deletion-cancel realises: - CAP-PFM-TNL-014 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/tenant-deletion-requests.routes.ts:cancelTenantDeletionRequest - operation_id: resumeTenantDeletionSchedule route: POST /tenant_deletion_requests/{id}/resume_schedule intent: Replace stopped watcher machinery without changing the fixed decision date. access: system permission: platform.tenants.deletion-request realises: - CAP-PFM-TNL-016 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/tenant-deletion-requests.routes.ts:resumeTenantDeletionSchedule - operation_id: retryTenantPurge route: POST /tenant_deletion_requests/{id}/retry intent: Submit forward recovery for a failed purge with a still-deleting workspace. access: system permission: platform.tenants.deletion-request realises: - CAP-PFM-TNL-017 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/tenant-deletion-requests.routes.ts:retryTenantPurge - operation_id: enterHqTenantLoading route: POST /hq/tenants/{id}/loading intent: Record an initial loading entry on an active implementation workspace. access: system permission: hq.data-runs.manage realises: - CAP-PFM-TNL-011 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/hq-tenant-loading.routes.ts:enterHqTenantLoading - operation_id: activateHqTenant route: POST /hq/tenants/{id}/activation intent: End loading independently of business standing and reset-job outcome. access: system permission: hq.tenants.activate realises: - CAP-PFM-TNL-011 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/hq-tenant-loading.routes.ts:activateHqTenant - operation_id: resetHqTenant route: POST /hq/tenants/{id}/reset intent: Submit a classified initial-load reset and return its accepted job reference. access: system permission: hq.data-runs.manage realises: - CAP-PFM-TNL-012 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/hq-tenant-loading.routes.ts:resetHqTenant - operation_id: getHqTenantReset route: GET /hq/tenants/{id}/reset intent: Inspect the workspace’s latest reset and accumulated resource counts. access: system permission: hq.data-runs.manage realises: - CAP-PFM-TNL-012 published_to_submissions: 'not published: staff administration uses a dedicated system operation.' provenance: observed source: services-platform:modules/tenants/aws/api/hq-tenant-loading.routes.ts:getHqTenantReset events: - name: platform.tenants.provisioning_completed direction: produced when: The construction task completes its activation follow-up. payload_summary: HQ outcome information naming the workspace and job. - name: platform.tenants.provisioning_failed direction: produced when: A construction failure consequence attempts its keyed outcome alert. payload_summary: HQ failure information with a safe summary. - name: job reconciler pass completed direction: consumed when: Shared job reconciliation invokes the registered repair hook after its pass. payload_summary: An in-process callback rather than a transported business-event payload. jobs: - name: tenant_provisioning kind: state machine platform-tenant-provisioning trigger: Invoked by the declared lifecycle caller or deployment hook; enablement and recovery limits are stated below. notes: Construction permits linked retry and uses a seven-day execution bound; failure changes only a still-provisioning workspace. - name: tenant_deletion_schedule kind: state machine platform-tenant-deletion-schedule trigger: Invoked by the declared lifecycle caller or deployment hook; enablement and recovery limits are stated below. notes: The watcher waits in Step Functions with a one-year bound and requires replacement-job recovery after failure. - name: tenant_purge kind: state machine platform-tenant-purge trigger: Invoked by the declared lifecycle caller or deployment hook; enablement and recovery limits are stated below. notes: Removal uses bounded batches and a twenty-four-hour execution limit, with forward retry and request failure consequences. - name: tenant_reset kind: state machine platform-tenant-reset trigger: Invoked by the declared lifecycle caller or deployment hook; enablement and recovery limits are stated below. notes: Reset is bounded to three thousand batches and is recovered through a new request, without a separate failure notice. - name: stranded provisioning repair kind: hook after each reconciler pass trigger: Invoked by the declared lifecycle caller or deployment hook; enablement and recovery limits are stated below. notes: The repair hook processes at most twenty-five stranded workspaces after a reconciliation pass. - name: tenants:reapply-deletions, tenants:orphans, tenants:long-disabled kind: operator scripts trigger: Invoked by the declared lifecycle caller or deployment hook; enablement and recovery limits are stated below. notes: Restore reapplication defaults to inspection; leftover and long-disabled reports only read. - name: tenant.deletion.notice_failed kind: alarm on a log metric trigger: Invoked by the declared lifecycle caller or deployment hook; enablement and recovery limits are stated below. notes: The notice-failure metric supplies an operations alarm while required obligations remain unsatisfied. integrations: - system: AWS Step Functions direction: outbound contract: Start the four declared workflow executions after their records commit and reconcile their outcomes. - system: Application lifecycle functions (CRM, Commerce, Committees, Membership, Submissions, Websites, Marketing, Accounting) direction: outbound contract: Invoke the operation selected for an enabled application participant through its declared lifecycle function. - system: Amazon SES through Platform's e-mail library direction: outbound contract: Send deletion obligations through Platform’s email path to configured internal recipients. - system: Amazon S3 deletion ledger bucket direction: outbound contract: Write versioned completion evidence and read it for restore reapplication. - system: Security authorizer flush job direction: outbound contract: Request cache-flush work without waiting for its completion. consistency: - rule: Initial construction records the customer when needed, workspace, sender setting and attempt in one commit before starting execution. kind: transactional compensation: Unstarted execution is handled by shared reconciliation. - rule: Deletion admission commits its request, notice obligations, pending-deletion lifecycle and watcher together. kind: transactional compensation: Staff can replace a watcher that never starts. - rule: Irreversible handoff commits executing request, deleting workspace, notice obligation and purge job together. kind: transactional compensation: Recovery retries removal forward after failure. - rule: Lifecycle cache clearing is local, with other processes refreshing facts after thirty seconds. kind: eventual compensation: The cache window does not prove that every route is gated. - rule: Participant work commits before Platform records returned results and counts. kind: eventual compensation: Repeated removal continues forward; lost results can leave counts incomplete. - rule: Construction failure retains created resources and preserves activation already committed. kind: eventual compensation: Staff choose a supported retry or deletion decision. - rule: Notice delivery occurs before its persisted outcome and can repeat. kind: eventual compensation: No exclusive claim guarantees one external send. evidence: - 'services-platform at ad3f6a65: modules/tenants/aws/api/{tenants, tenant-deletion-requests, hq-tenant-loading}.routes.ts; services/**; tenants-notifications.ts; aws/logic/*.ts; aws/resources/*.ts; scripts/*.ts; aws/platform.service.ts (HQ_TENANTS_PERMISSIONS, HQ_DATA_RUNS_PERMISSIONS, TENANTS_PERMISSIONS).' 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-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CHG-007, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, 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-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Workspace Lifecycle Service (Platform) ## What This Service Is For Platform coordinates workspace construction, controlled initial loading, reset and deliberate removal. It retains the decisions and progress staff need to inspect and recover those operations. Its availability implementation evaluates lifecycle and business standing for gated workspace requests. ## Boundary Workspace administration retains ordinary customer and workspace records. Shared jobs own execution and reconciliation; Security owns authority; the Data Job Engine owns imports; export coordination owns packaging and delivery. Application lifecycle functions implement their participant work. Provider sending and identity concerns retain their existing service owners. ## Operations in Words Staff can request construction, inspect its attempt, retry failed construction and initialize an existing participant. Import authority opens loading, submits reset and reads reset progress; separate activation authority ends loading. Deletion-request authority creates a decision and recovers stopped watcher or purge work. Hold authority pauses and releases reversible decisions; cancellation authority withdraws them. Deletion-reading authority exposes retained requests and their notices. Immediate removal is refused. The exact route permission and capability mappings remain in the structured operation rows. ## Events and Jobs Construction attempts publish keyed HQ outcome notifications and attempt requester messages. The reconciliation hook repairs stranded construction; it is an in-process callback rather than a business event. Four state machines perform construction, watching, purge and reset. Operator scripts inspect leftovers and disabled candidates or reapply ledger-recorded removal after restore. Notice failures feed an operations alarm. The reviewed lifecycle interface performs no model inference. ## Consistency Guarantees Normal admission and irreversible handoff commit their domain records with new job records before execution starts. Provisioning retry and deletion recovery have separate-commit gaps. Participant commits also precede result accounting, so repeated removal can converge while counts remain incomplete. Availability facts expire per process; HQ record routes outside the gate need their own safeguards. Purge finalization is not one transaction: failure after workspace removal can prevent completion and ordinary retry. Completion also precedes the external ledger write, whose exhausted failure has no ordinary recovery route. Notice records prevent duplicate obligations but do not ensure one message or eventual delivery.