---
id: STATE-PFM-TNL-002
title: Provisioning attempt
object: DOM-PFM-TNL-002
product_area: platform
module: tenant-lifecycle
revision: 1
status: draft
design_intent: confirmed
origin: services-platform:docs/jobs.md#§2 Adding a job; services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.4
  (approved 2026-10-09)
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
states:
- name: pending
  meaning: The attempt is stored and awaits execution progress.
- name: running
  meaning: The attempt is processing its planned participant steps.
- name: succeeded
  meaning: The attempt finished successfully and remains terminal.
- name: failed
  meaning: The attempt stopped; completed work remains and retry uses another attempt.
transitions:
- from: pending
  to: running
  trigger: The execution publishes its participant steps.
  guard: Its live participant order matches the recorded plan.
  side_effects:
  - Publish the step catalog.
  who: shared job engine
  provenance: observed
  source: services-platform:modules/tenants/services/provisioning/provision-tenant-operations.ts:tenantProvisioningOperations
- from: pending
  to: failed
  trigger: Reconciliation settles an attempt whose execution is absent or lost.
  guard: The shared job recovery policy admits settlement of the pending attempt.
  side_effects:
  - Apply workspace failure consequences.
  - Attempt requester notification and the HQ failure alert.
  who: jobs reconciler
  provenance: documented
  source: services-platform:docs/jobs.md#§2 step 8
- from: running
  to: succeeded
  trigger: The workflow finishes activation.
  guard: Readiness has passed for the planned participants.
  side_effects:
  - Open the workspace and attempt success communications.
  who: provisioning job
  provenance: observed
  source: services-platform:modules/tenants/services/provisioning/provision-tenant-operations.ts:tenantProvisioningOperations
- from: running
  to: failed
  trigger: A workflow task refuses, exhausts retries or exceeds execution time.
  guard: The failure handler or reconciler settles the attempt.
  side_effects:
  - Record an operator-safe summary and apply failure consequences.
  who: provisioning job or jobs reconciler
  provenance: observed
  source: services-platform:modules/tenants/services/provisioning/provision-tenant-workflow.ts:tenantProvisioningWorkflow
invalid:
- from: succeeded
  to: running
  why: A successful attempt is terminal; initialization handles later defaults.
- from: failed
  to: running
  why: Retry allocates a linked attempt rather than changing the failed attempt back to running.
- from: failed
  to: succeeded
  why: A failed terminal attempt cannot become successful; the new retry carries its own result.
concurrency: A partial unique index permits one open attempt per workspace. Participant work runs sequentially.
  Remote work can outlast the task deadline, so repeated invocation may overlap even where later calls converge.
  Execution has a seven-day bound; recovery depends on the shared job engine.
invariants:
- INV-DOM-PFM-TNL-002-02
- INV-DOM-PFM-TNL-002-03
- INV-DOM-PFM-TNL-002-04
- INV-DOM-PFM-TNL-002-06
evidence:
- 'services-platform at ad3f6a65: modules/tenants/services/provisioning/*.ts; db/migrations/0037_tenant_provisioning_job.sql;
  docs/jobs.md.'
---

# Provisioning Attempt

## The Lifecycle

```mermaid
stateDiagram-v2
  [*] --> pending: request committed
  pending --> running: execution started
  pending --> failed: reconciler, never started
  running --> succeeded: workspace opened
  running --> failed: refusal, exhausted retries or timeout
  succeeded --> [*]
  failed --> [*]: a retry is a new attempt
```

## Transitions Explained

The request stores a pending attempt before starting execution. Publishing checks participant order, and the workflow processes construction, readiness and activation. Task refusals, exhausted retries and execution timeout can settle it failed; shared reconciliation also recovers missing execution. Success and failure communications have their own delivery limits.

## What Cannot Happen

A terminal attempt is not resumed in place. Retry creates another attempt with a link and copied completed steps. The workspace cannot reopen through that retry until the remaining workflow and readiness succeed.

## Concurrency and Timing

A partial unique index permits one open attempt per workspace. Participant work runs sequentially. Remote work can outlast the task deadline, so repeated invocation may overlap even where later calls converge. Execution has a seven-day bound; recovery depends on the shared job engine.