---
id: WF-PFM-TNL-002
title: Build a workspace and open it
trigger: Construct participant resources in dependency order, verify readiness and activate the workspace.
product_area: platform
module: tenant-lifecycle
revision: 1
status: draft
design_intent: confirmed
origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.2, §4.5 (approved 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-002
- CAP-PFM-TNL-004
- CAP-PFM-TNL-007
- CAP-PFM-TNL-008
moves:
- STATE-PFM-TNL-001
- STATE-PFM-TNL-002
- 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
- SVC-PFM-NOT-notifications
idempotency: Ledgered defaults and deterministic provider adoption support repeated construction. Commerce adoption
  can recreate a removed default. Repeated activation preserves its recorded first instant.
concurrency: Steps run sequentially; only CRM, Commerce, Submissions and Websites declare the examined single-call
  reservation. Remote task timeouts can overlap unfinished work.
hops:
- n: 1
  actor_or_service: Provisioning job (publish)
  action: Compare live participant order with the catalog plan and publish steps.
  anchor: services-platform:modules/tenants/services/provisioning/provision-tenant-operations.ts:tenantProvisioningOperations
  seam: state_machine
  on_failure: Refuse a changed order and apply build failure handling.
  left_inconsistent: A retry may already have resources from an earlier attempt.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/provisioning/provision-tenant-workflow.ts
- n: 2
  actor_or_service: Provisioning job (participant step)
  action: Run unfinished participant steps in dependency order, locally or by remote invocation.
  anchor: services-platform:modules/tenants/services/provisioning/provision-tenant-operations.ts:provisionParticipant
  seam: state_machine
  on_failure: Retry eligible failures, then settle failure without compensation.
  left_inconsistent: Completed resources remain even if a later participant fails.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/provisioning/provision-tenant-operations.ts:provisionParticipant
- n: 3
  actor_or_service: Platform security participant
  action: Apply the new customer’s first-administrator invitation through its seed mechanism.
  anchor: services-platform:modules/tenants/services/lifecycle/first-administrator.ts:inviteFirstAdministrator
  seam: sync
  on_failure: Refuse incompatible existing administration standing.
  left_inconsistent: Invitation delivery can precede later build failure.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/lifecycle/first-administrator.ts
- n: 4
  actor_or_service: Communications sender-identity participant
  action: Prepare or adopt association sender identities and retain required DNS facts without waiting for verification.
  anchor: services-platform:modules/tenants/services/lifecycle/participants.ts (communications.sender-identity)
  seam: sync
  on_failure: Retry eligible errors and fail if preparation cannot finish.
  left_inconsistent: Provider resources can exist before the build completes.
  observer: Job progress and service logs.
  provenance: documented
  source: services-platform:docs/hq/rhythm-hq-plan.md#§D5 option A
- n: 5
  actor_or_service: Application lifecycle functions
  action: Invoke remote construction for application defaults and required schedules.
  anchor: services-crm:modules/tenant-lifecycle/services/lifecycle/tenant-lifecycle-operations.ts:runTenantLifecycleOperation
  seam: sync
  on_failure: Return remote errors to job handling and retry under task policy.
  left_inconsistent: Committed remote work remains; timed-out invocation can still be running.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/lifecycle/remote-participants.ts
- n: 6
  actor_or_service: Provisioning job (verify readiness)
  action: Ask planned participants for readiness and missing requirements.
  anchor: services-platform:modules/tenants/services/provisioning/provision-tenant-operations.ts:verifyParticipant
  seam: state_machine
  on_failure: Refuse readiness with the missing resources.
  left_inconsistent: The constructed resources remain while the workspace fails provisioning.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/provisioning/provision-tenant-operations.ts:verifyParticipant
- n: 7
  actor_or_service: Provisioning job (activate)
  action: Activate the locked workspace with requested business standing and first provisioning activation.
  anchor: services-platform:modules/tenants/services/persistence/tenants.ts:activateProvisionedTenant
  seam: sync
  on_failure: Repeat activation under task retry policy.
  left_inconsistent: Database activation can commit before later task work succeeds.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/persistence/tenants.ts:activateProvisionedTenant
- n: 8
  actor_or_service: Provisioning job (activate)
  action: Enable always-available applications, clear local availability and attempt staff access, licences and
    success messages.
  anchor: services-platform:modules/tenants/services/provisioning/provision-tenant-operations.ts:activateOperation
  seam: state_machine
  on_failure: Application-enablement failure can fail the task; the other follow-up failures are logged under their
    own handling.
  left_inconsistent: An active workspace can have a failed build attempt and missing follow-up results.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/provisioning/provision-tenant-operations.ts:activateOperation
branches:
- Copied completed participant steps are skipped.
- Development bootstrap uses existing workspace context without creating a customer or first administrator.
waits:
- Construction execution has a seven-day maximum.
evidence:
- 'services-platform at ad3f6a65: modules/tenants/services/provisioning/{provision-tenant-workflow, provision-tenant-operations}.ts;
  services/lifecycle/{participants, remote-participants, first-administrator}.ts; aws/logic/tenant-provisioning.step-function.ts.'
- 'services-crm, services-commerce, services-committees, services-membership at their pinned commits: modules/tenant-lifecycle
  lifecycle operations and participants.'
controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CHG-007, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, 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]
---

# Build A Workspace And Open It

## What It Does

Construct participant resources in dependency order, verify readiness and activate the workspace. Ledgered defaults and deterministic provider adoption support repeated construction. Commerce adoption can recreate a removed default. Repeated activation preserves its recorded first instant.

## The Flow

```mermaid
sequenceDiagram
  autonumber
  participant Job as Build job (Step Functions)
  participant PFM as Platform participants
  participant Apps as Application lifecycle functions
  participant DB as Platform database
  participant Note as Requester notice and HQ alert
  Job->>Job: compare live plan with planned steps
  loop each participant in dependency order
    alt Platform participant
      Job->>PFM: provision (in the workspace)
    else other application
      Job->>Apps: provision (identifiers only)
    end
  end
  Job->>PFM: verify readiness
  Job->>Apps: verify readiness
  Job->>DB: workspace active, status, first activation time
  Job->>DB: always-available applications, founding staff access
  Job->>Note: workspace ready (once)
```

## When Something Fails

Refuse a changed order and apply build failure handling. A retry may already have resources from an earlier attempt. Retry eligible failures, then settle failure without compensation. Completed resources remain even if a later participant fails. Refuse incompatible existing administration standing. Invitation delivery can precede later build failure. Retry eligible errors and fail if preparation cannot finish. Provider resources can exist before the build completes. Return remote errors to job handling and retry under task policy. Committed remote work remains; timed-out invocation can still be running. Refuse readiness with the missing resources. The constructed resources remain while the workspace fails provisioning. Repeat activation under task retry policy. Database activation can commit before later task work succeeds. Application-enablement failure can fail the task; the other follow-up failures are logged under their own handling. An active workspace can have a failed build attempt and missing follow-up results.

## Open Design Questions

Participant declarations can drift without changing order. Serial execution differs from the planned parallel stages, and post-activation follow-up can fail after the workspace opens.