Rhythm 2.0 Specifications

Appearance

CAP-PFM-QRY-019Preserve and inspect monthly data snapshots

Markdown

CAP-PFM-QRY-019

Preserve and inspect monthly data snapshots

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

Planning

Feature
FEAT-PFM-QRY-08
Exercised by
FAS-PFM-QRY-07-03, FAS-PFM-QRY-08-01, FAS-PFM-QRY-08-02, FAS-PFM-QRY-08-03, FAS-PFM-QRY-08-04, FAS-PFM-QRY-08-05
Key concepts
CON-PFM-QRY-006
Actors
ACT-PFM-013, ACT-PFM-015, ACT-PFM-012, ACT-PFM-016
Proved by
ATS-PFM-QRY-019

Implementation

Executable suites
TST-PFM-QRY-467, TST-PFM-QRY-468, TST-PFM-QRY-471, TST-PFM-QRY-472, TST-PFM-QRY-473

KindCapabilityProduct areaPlatformModuleQuestions, record exploration and data deliveryRevision1

Read atservices-platform ad3f6a65react-console baf6dae3

Preserve and inspect monthly data snapshots ​

Purpose ​

Keep an accountable monthly snapshot ledger so staff can identify available history and operators can repair missing periods.

How It Works ​

Applications declare snapshot types for the data they own. Planning identifies the month and eligible workspace for each owed snapshot. Ledger rows record the decision, version and eventual result. Each owning application admits work under its own concurrency limit. Validation and publication determine which completed version is current. Failure preserves the preceding publication and can lead to retries or operator attention. Rhythm staff inspect runs, policies and missing periods through HQ operations. Workspace users can read available periods through the API. The console period picker remains an unfinished consumer of that information.

Relationships ​

Applications declare and fill snapshot types. The shared snapshot ledger supports available-period discovery and administrative recovery.

The Formal Contract

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

Outcomes
Applications maintain monthly history through a shared ledger.Operators can repair missing periods while preserving prior publications.The period API identifies the months available to reporting.
Surfaces
consoleapijob
Intent sources
services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions (all approved as recommended, 2026-10-15) D1services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions (all approved as recommended, 2026-10-15) D2services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions (all approved as recommended, 2026-10-15) D4services-platform:docs/proposals/snapshot-architecture.md#Status (approved by Andrew on 2026-10-15)

Controls

34 controls apply, from the corpus control catalogue.

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-DAT-001 TC-DAT-003 TC-DAT-004 TC-IAM-001 TC-IAM-002 TC-IAM-003 TC-IAM-004 TC-IAM-005 TC-LOG-001 TC-LOG-002 TC-LOG-003 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-TEN-001 TC-TEN-002 TC-TEN-003 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

KeyChecked atScope
platform.snapshots.readapitenant
hq.snapshots.readapiglobal
hq.snapshots.manageapiglobal

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
Workspace period reads list each month once newest first using its current or highest version, with status, basis, publication or skip detail, and reject users from another customer.
origin: services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions (all approved as recommended, 2026-10-15) D1
proved by ATS-PFM-QRY-019-01, TST-PFM-QRY-467, TST-PFM-QRY-473
permissionapi, servicetest
services-platform:modules/snapshots/tests/e2e/snapshots.e2e.spec.js#refuses another customer’s user the tenant’s periods
02must prove
Confirmed
HQ snapshot operations are staff-only, separate read permission from run and policy management, and refuse customer administrators.
proved by ATS-PFM-QRY-019-02, TST-PFM-QRY-467
permissionapitest
services-platform:modules/snapshots/tests/e2e/snapshots.e2e.spec.js#refuses a customer’s own administrator every HQ route, which are staff-only
03must prove
Confirmed
Snapshot periods follow the workspace’s own time zone and identify the month described.
origin: services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions (all approved as recommended, 2026-10-15) D2
proved by ATS-PFM-QRY-019-03, TST-PFM-QRY-472
calculationservicetest
services-platform:modules/snapshots/tests/integration/lifecycle/pipeline/snapshot-pipeline.integration.spec.js#plans the eligible tenant's September in its own zone, as version 1 of a captured, scheduled run
04must prove
Confirmed
Planning includes active eligible workspaces, skips loading or disabled workspaces with recorded reasons, and applies type-specific policy ahead of workspace-wide policy and defaults.
origin: services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions (all approved as recommended, 2026-10-15) D4
proved by ATS-PFM-QRY-019-04, TST-PFM-QRY-472
policyservicetest
services-platform:modules/snapshots/tests/integration/lifecycle/pipeline/snapshot-pipeline.integration.spec.js#reads the disabled tenant's month in its own zone, August, and skips it with the policy's reason
05must prove
Confirmed
Manual reruns allocate a new period version and reject overlapping active runs, while back-fill skips existing months unless supersession is requested.
proved by ATS-PFM-QRY-019-05, TST-PFM-QRY-467
lifecycleservicetest
services-platform:modules/snapshots/tests/e2e/snapshots.e2e.spec.js#refuses a second request for the same month while the first is under way (409)
06must prove
Confirmed
Validation and publication commit together, leaving no rows or current-version change after failure and preserving earlier versions when a rerun publishes.
origin: services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions (all approved as recommended, 2026-10-15) D1
proved by ATS-PFM-QRY-019-06, TST-PFM-QRY-472
invariantservice, databasetest
services-platform:modules/snapshots/tests/integration/lifecycle/pipeline/snapshot-pipeline.integration.spec.js#publishes nothing: none of its rows were kept, and version 2 is still the current one
07must prove
Confirmed
The shared snapshot ledger restricts application writers to their own service’s runs and denies deletion.
proved by ATS-PFM-QRY-019-07, TST-PFM-QRY-468, TST-PFM-QRY-471
invariantdatabasetest
services-platform:modules/snapshots/tests/integration/db/snapshot-runs-accounting-writer.integration.spec.js#refuses a run whose owner_service is another service’s, in its own tenant
08must prove
Confirmed
The database permits only one active run and one current version per workspace, snapshot type and period.
proved by ATS-PFM-QRY-019-08, TST-PFM-QRY-471
invariantdatabasetest
services-platform:modules/snapshots/tests/integration/db/snapshot-runs.table.integration.spec.js#refuses a second active run of the same tenant, type and period
09must prove
Confirmed
Failed snapshots retry after fifteen minutes, one hour and four hours, stop after a fourth failure, and raise overdue alarms when publication misses its deadline.
proved by ATS-PFM-QRY-019-09
lifecycleservicedocumented
services-platform:docs/snapshots/README.md#Configuration and the runbook
10must prove
Confirmed
Snapshot requests require a reason, valid month and configured type, with run pages capped at one thousand.
proved by ATS-PFM-QRY-019-10, TST-PFM-QRY-467
validationapitest
services-platform:modules/snapshots/tests/e2e/snapshots.e2e.spec.js#refuses a request with no reason, naming the field
11must prove
Confirmed
Workspace purge removes every snapshot version, run and policy override for that workspace.
proved by ATS-PFM-QRY-017-15, ATS-PFM-QRY-018-17, ATS-PFM-QRY-019-11, ATS-PFM-QRY-019-12, ATS-PFM-QRY-019-13, TST-PFM-QRY-472
lifecycleservicetest
services-platform:modules/snapshots/tests/integration/lifecycle/pipeline/snapshot-pipeline.integration.spec.js#removes every snapshot row, run and override of the purged tenants, the run's version chain included
12
Confirmed
Requests create ledger work that each owning application admits through its own dispatcher, capped at four concurrent runs including at most one back-fill.
proved by ATS-PFM-QRY-019-14
policyservicedocumented
services-platform:docs/snapshots/README.md#Configuration and the runbook

Scenarios

IdGivenWhenThenProvenance
01An eligible workspace reaches month end in its own calendar.The planner creates that month’s work.The ledger records version one for the workspace’s completed month.test
services-platform:modules/snapshots/tests/integration/lifecycle/pipeline/snapshot-pipeline.integration.spec.js#plans the eligible tenant's September in its own zone, as version 1 of a captured, scheduled run

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