Rhythm 2.0 Specifications

Appearance

CAP-PFM-OPS-015Prepare and operate workspace applications

Markdown

CAP-PFM-OPS-015

Prepare and operate workspace applications

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

Planning

Feature
FEAT-PFM-OPS-04
Exercised by
FAS-PFM-OPS-04-01, FAS-PFM-OPS-04-02, FAS-PFM-OPS-04-03, FAS-PFM-OPS-04-04, FAS-PFM-OPS-04-05
Key concepts
CON-PFM-OPS-004
Actors
ACT-PFM-004, ACT-PFM-006
Journeys
JNY-PFM-OPS-004
Related
CAP-PFM-OPS-011, CAP-PFM-OPS-014, CAP-PFM-SEC-003, CAP-PFM-SEC-004
Proved by
ATS-PFM-OPS-015

Implementation

Executable suites
TST-PFM-OPS-081, TST-PFM-OPS-087, TST-PFM-OPS-104

KindCapabilityProduct areaPlatformModuleOperational RecordsRevision1

Read atservices-platform ad3f6a65

Prepare and operate workspace applications ​

Purpose ​

Establish application readiness and support deliberate suspension, recovery and resumption.

How It Works ​

An application is prepared by recording provisioning and invoking its declared workspace participants. Successful preparation records enabled; participant failure records a bounded explanation and leaves the commercial decision intact. Staff recover a failed preparation through retry. Suspension and resumption change operational standing without discarding application data. Services validate the starting state before asking the persistence writer to lock and change the row. That split permits races between concurrent state changes. Completed staff actions request a flush and then attempt security-history insertion, so later failures do not undo the committed state. Activation and release backfill supply missing always-available states without overriding an existing suspension.

Relationships ​

Licence decisions feed availability alongside operational state; security applies the resulting access decision and the console explains it.

The Formal Contract

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

Outcomes
Preparation and staff changes leave an explainable operational record.Suspension and resumption preserve prepared information.
Surfaces
consoleapijob
Preconditions
The staff caller holds HQ licensing-management authority for an operational action.
Postconditions
The workspace retains a single operational record for each prepared application.
Constraints
Application preparation runs synchronously and relies on lifecycle participants’ idempotent seed handling.
Intent sources
services-platform:docs/proposals/application-access-and-entitlements.md#6.2 (operational states; built and accepted 2026-10-15)services-platform:docs/proposals/application-access-and-entitlements.md#10.2 Later (D5: automatic initialization on licence; default taken)

Controls

37 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-AZ-006 TC-CHG-001 TC-CHG-002 TC-CHG-003 TC-CHG-004 TC-CHG-005 TC-CHG-006 TC-DAT-001 TC-DAT-003 TC-DAT-004 TC-IAM-001 TC-IAM-003 TC-IAM-006 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 TC-PI-005 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

KeyChecked atScope
hq.licensing.manageapiglobal

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
Application preparation records provisioning before running workspace participants and then records enabled or a participant-specific failure, without undoing the triggering commercial decision; enabled applications need no repeat preparation.
proved by ATS-PFM-OPS-015-01, ATS-PFM-OPS-015-09, ATS-PFM-OPS-015-11, ATS-PFM-OPS-015-14, TST-PFM-OPS-087
lifecycleservicetest
services-platform:modules/licensing/tests/integration/services/enablement/provision-tenant-application.integration.spec.js#says which participant could not run, in the reason an operator reads
02must prove
Confirmed
Retry requires failed preparation, suspend requires enabled state and resume requires suspension, with absent operational records and invalid starting states refused.
proved by ATS-PFM-OPS-013-09, ATS-PFM-OPS-014-10, ATS-PFM-OPS-015-02, ATS-PFM-OPS-015-10, ATS-PFM-OPS-015-14, TST-PFM-OPS-087
validationservicetest
services-platform:modules/licensing/tests/integration/services/enablement/provision-tenant-application.integration.spec.js#refuses every move for an application the tenant has never been provisioned for
03must prove
Confirmed
Suspended and failed-preparation states require reasons, while enabled and provisioning states clear reasons; an unexplained suspension is refused.
proved by ATS-PFM-OPS-015-03, ATS-PFM-OPS-015-14, TST-PFM-OPS-081, TST-PFM-OPS-087
validationapi, service, databasetest
services-platform:modules/licensing/tests/e2e/licensing.e2e.spec.js#refuses a suspension with no reason, with 400
04must prove
Confirmed
Suspending and resuming retain application data and the original first-enabled timestamp.
proved by ATS-PFM-OPS-015-04
invariantservicetest
services-platform:modules/licensing/tests/integration/services/persistence/tenant-applications.integration.spec.js#keeps the instant it was first enabled through a suspension and a resumption
05must prove
Confirmed
Staff state-change services request a flush after committing and routes then attempt audit insertion, so failures in later work do not undo state changes; rejected transitions request no flush.
proved by ATS-PFM-OPS-015-05
policyserviceobserved
services-platform:modules/licensing/aws/api/licensing.routes.ts:suspendTenantApplication; services-platform:modules/licensing/services/enablement/provision-tenant-application.ts:suspendTenantApplication
06must prove
Confirmed
Provisioning activation and deployment backfill add missing always-available operational rows without changing existing rows, including suspensions.
origin: services-platform:docs/licensing.md#6. Where the rows come from
proved by ATS-PFM-OPS-015-06, TST-PFM-OPS-104
lifecycleservice, databasetest
services-platform:modules/licensing/tests/integration/services/persistence/tenant-applications.integration.spec.js#leaves a suspended row suspended, so a redeploy never undoes an operational decision
07must prove
Confirmed
Staff application-state actions require licensing-management authority and refuse read-only staff.
proved by ATS-PFM-OPS-015-07, TST-PFM-OPS-081
permissionapitest
services-platform:modules/licensing/tests/e2e/licensing.e2e.spec.js#refuses a staff member who may only read, with 403
08
Confirmed
Concurrent state writers resolve an insertion collision on one shared row, without thereby serializing participant execution or protecting the entire transition.
proved by ATS-PFM-OPS-015-13, TST-PFM-OPS-104
invariantservice, databaseobserved
services-platform:modules/licensing/services/persistence/tenant-applications.ts:setTenantApplicationState
09must prove
Confirmed
Workspace purge includes its licence overrides and application states in the licensing participant’s declared resources.
proved by ATS-PFM-OPS-001-17, ATS-PFM-OPS-015-08, ATS-PFM-OPS-015-12, ATS-PFM-OPS-015-15
lifecycleservice, databaseobserved
services-platform:modules/licensing/services/maintenance/tenant-participant.ts:licensingParticipant
10must prove
Confirmed
Operational services check their starting state before the writer obtains its row lock, allowing a concurrent action to overwrite a newer state decision.
no proof recorded yet
invariantserviceobserved
services-platform:modules/licensing/services/enablement/provision-tenant-application.ts:suspendTenantApplication; services-platform:modules/licensing/services/persistence/tenant-applications.ts:setTenantApplicationState

Scenarios

IdGivenWhenThenProvenance
01An application participant is unable to finish workspace preparation.Preparation runs and is attempted again after the participant is repaired.The failed attempt retains an explanation and a successful subsequent attempt records enabled.inferred
services-platform:modules/licensing/tests/integration/services/enablement/provision-tenant-application.integration.spec.js#succeeds when it is retried after the participants would run, which is the enabled path of the same call
02A licensed application is operationally enabled.Staff suspend it with a reason and later resume it.Operational standing changes without deleting data, with audit attempts and cache invalidation following the staff actions.inferred
services-platform:modules/licensing/tests/e2e/licensing.e2e.spec.js#resumes a suspended application

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