---
id: DOM-PFM-TNL-002
title: Provisioning
realises: CON-PFM-TNL-002
product_area: platform
module: tenant-lifecycle
revision: 1
status: draft
design_intent: confirmed
origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§4 (approved 2026-10-09); services-platform:docs/hq/rhythm-hq-plan.md#§I
  Provisioning workflow, §D5, §D11 (approved 2026-10-11)
implementation_evidence: observed
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
owned_by: SVC-PFM-TNL-tenants
readable_by:
- SVC-PFM-SEC-tenants
lifecycle: STATE-PFM-TNL-002
custom_fields: none
identity: Each attempt has its generated job identity, submission identity and workspace reference; retry allocates
  a linked attempt.
attributes:
- name: workspace
  kind: reference
  required: true
  computed: false
  notes: Workspace identity carried by the attempt; initial submission commits them together.
- name: customer
  kind: reference
  required: true
  computed: false
  notes: Existing customer or the customer created with the first workspace.
- name: submission identity
  kind: text
  required: true
  computed: false
  notes: Caller-supplied identity used to recover the recorded submission.
- name: requested business status
  kind: enum
  required: true
  computed: false
  notes: Requested live or implementation standing, defaulting to implementation and applied at activation.
- name: customer created
  kind: enum
  required: true
  computed: false
  notes: Records whether this submission creates the customer and can invite its first administrator.
- name: first administrator
  kind: collection
  required: false
  computed: false
  notes: The paired name and email address for the new customer’s administrator invitation.
- name: plan
  kind: collection
  required: true
  computed: false
  notes: Static dependency order followed by readiness and activation; publication compares live participant order.
- name: step outcomes
  kind: collection
  required: true
  computed: false
  notes: Recorded task results and attempts, with completed steps copied to linked retry.
- name: history
  kind: collection
  required: true
  computed: false
  notes: Sequenced durable execution events for progress inspection.
- name: status
  kind: enum
  required: true
  computed: false
  notes: Pending, running, succeeded or failed; this kind does not expose engine cancellation.
- name: failure summary
  kind: text
  required: false
  computed: false
  notes: A safe operational explanation of the failure and missing requirements.
- name: retry of
  kind: reference
  required: false
  computed: false
  notes: The prior failed attempt linked by this retry.
- name: requester outcome notice
  kind: collection
  required: false
  computed: false
  notes: Shared claim and delivery result for the requester’s attempt-outcome message.
- name: sender setting
  kind: reference
  required: false
  computed: false
  notes: Association sender configuration recorded at submission and prepared by its participant.
relationships:
- to: DOM-PFM-TNL-001
  cardinality: many-to-one
  ownership: The attempt points to the workspace it constructs.
  cross_service: false
- to: DOM-PFM-TNL-003
  cardinality: many-to-many
  ownership: The plan identifies participating implementations without owning their business records.
  cross_service: true
- to: DOM-PFM-SEC-001
  cardinality: many-to-one
  ownership: The attempt names a customer, which workspace administration owns and the request may create.
  cross_service: false
invariants:
- id: INV-DOM-PFM-TNL-002-01
  statement: Initial construction commits new customer when requested, workspace, sender setting and attempt together.
  enforced_at:
  - service
  - database
  provenance: observed
  source: services-platform:modules/tenants/services/provisioning/submit-tenant-provisioning.ts:submitTenantProvisioning
- id: INV-DOM-PFM-TNL-002-02
  statement: A recorded submission identity resolves to its original workspace and attempt.
  enforced_at:
  - service
  - database
  provenance: observed
  source: services-platform:modules/tenants/services/provisioning/submit-tenant-provisioning.ts:submitTenantProvisioning
    (findTenantProvisioningJobBySubmission)
- id: INV-DOM-PFM-TNL-002-03
  statement: The database permits only one pending or running attempt per workspace.
  enforced_at:
  - database
  provenance: observed
  source: services-platform:db/migrations/0037_tenant_provisioning_job.sql:tenant_provisioning_jobs_open_uidx
- id: INV-DOM-PFM-TNL-002-04
  statement: Step publication refuses a live participant order different from the catalog plan.
  enforced_at:
  - service
  provenance: observed
  source: services-platform:modules/tenants/services/provisioning/provision-tenant-operations.ts:tenantProvisioningOperations
- id: INV-DOM-PFM-TNL-002-05
  statement: The build workflow checks each planned participant before activation.
  enforced_at:
  - service
  provenance: observed
  source: services-platform:modules/tenants/services/provisioning/provision-tenant-operations.ts:verifyParticipant
- id: INV-DOM-PFM-TNL-002-06
  statement: Failure retains constructed resources and changes only a workspace still provisioning; activation already
    committed is preserved.
  enforced_at:
  - service
  provenance: observed
  source: services-platform:modules/tenants/services/provisioning/provision-tenant-failure.ts:applyTenantProvisioningFailure
- id: INV-DOM-PFM-TNL-002-07
  statement: Requester outcome delivery uses a per-attempt claim and does not determine the build outcome.
  enforced_at:
  - service
  - database
  provenance: documented
  source: services-platform:docs/hq/rhythm-hq-plan.md#§D11 Provisioning notifications
physical:
- platform.tenant_provisioning_jobs
- platform.tenant_provisioning_job_steps
- platform.tenant_provisioning_job_events
- platform.job_notices
- platform.communication_sender_identities
evidence:
- 'services-platform at ad3f6a65: modules/tenants/services/provisioning/{submit-tenant-provisioning, provision-tenant-workflow,
  provision-tenant-operations, provision-tenant-failure, repair-stranded-provisioning, provisioning-notice, publish-provisioning-alert}.ts;
  db/tenant-provisioning-job*.table.ts; db/migrations/0037_tenant_provisioning_job.sql; docs/jobs.md §2.'
- 'FND-PFM-TNL-054: custom-field registration absence is not established within the permitted source scope.'
---

# Provisioning

## What It Models

Provisioning records a construction attempt across application participants. It preserves progress, failure and retry lineage so staff can recover a build without discarding completed resources.

## Identity and Attributes

Each attempt has its generated job identity, submission identity and workspace reference; retry allocates a linked attempt. Workspace identity carried by the attempt; initial submission commits them together. Existing customer or the customer created with the first workspace. Caller-supplied identity used to recover the recorded submission. Requested live or implementation standing, defaulting to implementation and applied at activation. Records whether this submission creates the customer and can invite its first administrator. The paired name and email address for the new customer’s administrator invitation. Static dependency order followed by readiness and activation; publication compares live participant order. Recorded task results and attempts, with completed steps copied to linked retry. Sequenced durable execution events for progress inspection. Pending, running, succeeded or failed; this kind does not expose engine cancellation. A safe operational explanation of the failure and missing requirements. The prior failed attempt linked by this retry. Shared claim and delivery result for the requester’s attempt-outcome message. Association sender configuration recorded at submission and prepared by its participant.

## Relationships

The attempt points to the workspace it constructs. The plan identifies participating implementations without owning their business records. The attempt names a customer, which workspace administration owns and the request may create.

## Invariants

The structured invariants distinguish service and database enforcement from documented obligations. The listed enforcement points bound what the workflow can rely on.

## How It Is Stored and Shared

Platform’s lifecycle service owns this design object. The physical declarations identify its stored records, while shared jobs provide durable execution and inspection.

## Open Design Questions

A retry changes lifecycle before creating its attempt. Post-activation failures can also leave an active workspace with a failed job outcome; both need deliberate recovery behavior.