Rhythm 2.0 Specifications

Appearance

CAP-PFM-TNL-003Understand and recover a workspace build

Markdown

CAP-PFM-TNL-003

Understand and recover a workspace build

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

Planning

Feature
FEAT-PFM-TNL-01
Key concepts
CON-PFM-TNL-002
Actors
ACT-PFM-004, ACT-PFM-039, ACT-PFM-012
Journeys
JNY-PFM-TNL-001, JNY-PFM-TNL-002
Depends on
CAP-PFM-TNL-002
Related
CAP-PFM-TNL-001, CAP-PFM-TNL-013
Proved by
ATS-PFM-TNL-003

KindCapabilityProduct areaPlatformModuleWorkspace Lifecycle Across ApplicationsRevision2

Read atservices-platform ad3f6a65

Understand and recover a workspace build ​

Purpose ​

Staff inspect build progress and recover failed construction with its partial resources preserved.

How It Works ​

The administrator reads the latest build snapshot to see the completed work and failure explanation. Customer administrators cannot inspect or retry this staff operation. A failed build keeps the workspace and everything already created. After the cause is corrected, staff submit a retry. Rhythm records a new attempt linked to the failed job and carries its completed steps. The requester’s outcome notice links back to the job. The operations channel receives a separate alert. Notification problems do not reverse the build result. A repair pass also finds workspaces still provisioning after their job has settled failed and makes them available for staff recovery.

Relationships ​

  • Open a workspace after its applications are ready: The construction job provides the result and retained steps that recovery inspects.
  • Request a complete customer workspace: The capabilities share the workspace’s recorded lifecycle decision.
  • Schedule deliberate workspace deletion: The capabilities share the workspace’s recorded lifecycle decision.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Provisioning snapshots explain completed steps and failures.Retry preserves partial construction instead of compensating it away.Requester notices and operations alerts report the result.Repair resolves workspaces stranded behind settled jobs.
Surfaces
consoleapijob
Intent sources
services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.1services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.4services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.6services-platform:docs/hq/rhythm-hq-plan.md#§D11

Controls

32 controls apply, from the corpus control catalogue.

TC-AVL-001 TC-AVL-004 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-IAM-001 TC-IAM-003 TC-IAM-006 TC-LOG-001 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-MON-002 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

Permissions

KeyChecked atScope
hq.tenants.readapiglobal
hq.tenants.provisionapiglobal

Business Rules

8 rules, 6 to be proved before approval. A rule's product intent is derived from its origin: 8 confirmed by a product decision, the rest inheriting this capability's confirmed.

IdRuleKindEnforced atProvenance
01must prove
Confirmed
Authorized staff read the latest provisioning snapshot; customer administrators are refused and missing workspaces or absent provisioning jobs return not found.
origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.1 (approved 2026-10-09)
no proof recorded yet
permissionapi, servicetest
services-platform:modules/tenants/tests/e2e/tenant-provisioning.e2e.spec.js#may not watch the provisioning of their own tenant
02must prove
Confirmed
A failed build retains the workspace and its partial resources in provisioning-failed state.
origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.4 No automatic compensation (approved 2026-10-09)
no proof recorded yet
lifecycleservicetest
services-platform:modules/tenants/tests/e2e/tenant-provisioning.e2e.spec.js#leaves the tenant saying its provisioning failed, which is what makes it retryable
03must prove
Confirmed
Only failed provisioning can be retried; retry restores provisioning state and creates a linked job carrying completed steps.
origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.1 Retry (approved 2026-10-09)
no proof recorded yet
lifecycleapi, servicetest
services-platform:modules/tenants/tests/e2e/tenant-provisioning.e2e.spec.js#refuses to provision a tenant again whose provisioning did not fail
04must prove
Confirmed
The requester’s outcome notice names the workspace, result, failure summary when applicable and job link; a handled notice is not resent and sending failure does not fail the build.
origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.6 (approved 2026-10-09); services-platform:docs/hq/rhythm-hq-plan.md#§D11
no proof recorded yet
policyservicetest
services-platform:modules/tenants/tests/integration/services/provisioning/provisioning-notices.integration.spec.js#sends nothing a second time when the activate task runs again
05
Confirmed
Failure notices explain that the workspace remains and that staff can choose retry or deletion without an automatic follow-up.
origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.6 (approved 2026-10-09)
policyservicetest
services-platform:modules/tenants/tests/unit/services/provisioning/provisioning-notice.spec.js#says the two things the requester may do with it: retry it or delete it
06must prove
Confirmed
The HQ operations alert accompanies the requester’s e-mail, and alert delivery failure leaves the job’s result intact.
origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.6 (PLAT-M23 D1, approved)
no proof recorded yet
policyservicetest
services-platform:modules/tenants/tests/e2e/tenant-provisioning-alerts.e2e.spec.js#tells the requester by e-mail as well: the alert is beside the notice, not instead of it
07must prove
Confirmed
After reconciliation, repair moves a stranded provisioning workspace to failed and handles its requester notice once; running jobs remain untouched.
origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.4 A tenant stranded behind a failed job is repaired (approved)
no proof recorded yet
lifecycleservicetest
services-platform:modules/tenants/tests/integration/services/provisioning/repair-stranded-provisioning.integration.spec.js#moves the stranded tenant to provisioning_failed, which makes it retryable and deletable again
08
Confirmed
Staff dispose of an unwanted failed build through a deletion request rather than automatic rollback.
origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.4 (approved 2026-10-09)
policyservicedocumented
services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.4 Getting rid of a failed tenant

Scenarios

IdGivenWhenThenProvenance
01CRM became unreachable during construction.Staff retry after restoring the connection.The replacement attempt completes outstanding work and opens the workspace.test
services-platform:modules/tenants/tests/e2e/tenant-provisioning.e2e.spec.js#leaves the tenant usable after the retry
02A never-started job is settled without updating its workspace.The repair pass examines it.The workspace becomes provisioning failed and its requester notice is handled.test
services-platform:modules/tenants/tests/integration/lifecycle/reconciled-job-failure.integration.spec.js#tells the staff member who asked for the tenant that it failed, though no task of the job ever ran

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software