--- id: CAP-PFM-QRY-019 title: Preserve and inspect monthly data snapshots feature: FEAT-PFM-QRY-08 product_area: platform module: queries revision: 1 status: draft product_intent: confirmed implementation_evidence: observed supersedes: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - >- services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions (all approved as recommended, 2026-10-15) D1 - >- services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions (all approved as recommended, 2026-10-15) D2 - >- services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions (all approved as recommended, 2026-10-15) D4 - 'services-platform:docs/proposals/snapshot-architecture.md#Status (approved by Andrew on 2026-10-15)' purpose: >- Keep an accountable monthly snapshot ledger so staff can identify available history and operators can repair missing periods. 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. concepts: - CON-PFM-QRY-006 actors: - ACT-PFM-013 - ACT-PFM-015 - ACT-PFM-012 - ACT-PFM-016 surfaces: - console - api - job preconditions: [] postconditions: [] permissions: - key: platform.snapshots.read where_checked: api scope: tenant - key: hq.snapshots.read where_checked: api scope: global - key: hq.snapshots.manage where_checked: api scope: global rules: - id: BR-CAP-PFM-QRY-019-01 proved_by: [ATS-PFM-QRY-019-01, TST-PFM-QRY-467, TST-PFM-QRY-473] statement: >- 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. kind: permission enforced_at: - api - service must_prove: true provenance: test source: >- services-platform:modules/snapshots/tests/e2e/snapshots.e2e.spec.js#refuses another customer’s user the tenant’s periods origin: >- services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions (all approved as recommended, 2026-10-15) D1 - id: BR-CAP-PFM-QRY-019-02 proved_by: [ATS-PFM-QRY-019-02, TST-PFM-QRY-467] statement: >- HQ snapshot operations are staff-only, separate read permission from run and policy management, and refuse customer administrators. kind: permission enforced_at: - api must_prove: true provenance: test source: >- services-platform:modules/snapshots/tests/e2e/snapshots.e2e.spec.js#refuses a customer’s own administrator every HQ route, which are staff-only origin: none - id: BR-CAP-PFM-QRY-019-03 proved_by: [ATS-PFM-QRY-019-03, TST-PFM-QRY-472] statement: Snapshot periods follow the workspace’s own time zone and identify the month described. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: >- services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions (all approved as recommended, 2026-10-15) D2 - id: BR-CAP-PFM-QRY-019-04 proved_by: [ATS-PFM-QRY-019-04, TST-PFM-QRY-472] statement: >- 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. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: >- services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions (all approved as recommended, 2026-10-15) D4 - id: BR-CAP-PFM-QRY-019-05 proved_by: [ATS-PFM-QRY-019-05, TST-PFM-QRY-467] statement: >- Manual reruns allocate a new period version and reject overlapping active runs, while back-fill skips existing months unless supersession is requested. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- 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) origin: none - id: BR-CAP-PFM-QRY-019-06 proved_by: [ATS-PFM-QRY-019-06, TST-PFM-QRY-472] statement: >- Validation and publication commit together, leaving no rows or current-version change after failure and preserving earlier versions when a rerun publishes. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- 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 origin: >- services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions (all approved as recommended, 2026-10-15) D1 - id: BR-CAP-PFM-QRY-019-07 proved_by: [ATS-PFM-QRY-019-07, TST-PFM-QRY-468, TST-PFM-QRY-471] statement: >- The shared snapshot ledger restricts application writers to their own service’s runs and denies deletion. kind: invariant enforced_at: - database must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-PFM-QRY-019-08 proved_by: [ATS-PFM-QRY-019-08, TST-PFM-QRY-471] statement: >- The database permits only one active run and one current version per workspace, snapshot type and period. kind: invariant enforced_at: - database must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-PFM-QRY-019-09 proved_by: [ATS-PFM-QRY-019-09] statement: >- 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. kind: lifecycle enforced_at: - service must_prove: true provenance: documented source: 'services-platform:docs/snapshots/README.md#Configuration and the runbook' origin: none - id: BR-CAP-PFM-QRY-019-10 proved_by: [ATS-PFM-QRY-019-10, TST-PFM-QRY-467] statement: >- Snapshot requests require a reason, valid month and configured type, with run pages capped at one thousand. kind: validation enforced_at: - api must_prove: true provenance: test source: >- services-platform:modules/snapshots/tests/e2e/snapshots.e2e.spec.js#refuses a request with no reason, naming the field origin: none - id: BR-CAP-PFM-QRY-019-11 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] statement: 'Workspace purge removes every snapshot version, run and policy override for that workspace.' kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-PFM-QRY-019-12 proved_by: [ATS-PFM-QRY-019-14] statement: >- Requests create ledger work that each owning application admits through its own dispatcher, capped at four concurrent runs including at most one back-fill. kind: policy enforced_at: - service must_prove: false provenance: documented source: 'services-platform:docs/snapshots/README.md#Configuration and the runbook' origin: none scenarios: - id: SC-CAP-PFM-QRY-019-01 given: An eligible workspace reaches month end in its own calendar. when: The planner creates that month’s work. then: The ledger records version one for the workspace’s completed month. provenance: test source: >- 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 edge_cases: [] constraints: [] depends_on: [] related: [] journeys: [] open_questions: [] operations: - listSnapshotPeriods - listSnapshotRunsInHq - getSnapshotRunInHq - getSnapshotPeriodStatusInHq - listOverdueSnapshotRunsInHq - requestSnapshotRunInHq - requestSnapshotBackfillInHq - listSnapshotPoliciesInHq - putSnapshotPolicyInHq - deleteSnapshotPolicyInHq tables: - snapshot-runs.table.ts - snapshot-tenant-policies.table.ts - snapshot-run-jobs.table.ts - snapshot-run-job-steps.table.ts - snapshot-run-job-events.table.ts - snapshot-user-status-counts.table.ts evidence: - 'Pinned reference: services-platform:docs/proposals/snapshot-architecture.md' - 'Pinned reference: services-platform:docs/snapshots/README.md' - 'Pinned reference: services-platform:modules/snapshots/tests/e2e/snapshots.e2e.spec.js' - >- Pinned reference: services-platform:modules/snapshots/tests/integration/db/snapshot-runs-accounting-writer.integration.spec.js - >- Pinned reference: services-platform:modules/snapshots/tests/integration/db/snapshot-runs.table.integration.spec.js - >- Pinned reference: services-platform:modules/snapshots/tests/integration/lifecycle/pipeline/snapshot-pipeline.integration.spec.js controls: [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] 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] suites: [TST-PFM-QRY-467, TST-PFM-QRY-468, TST-PFM-QRY-471, TST-PFM-QRY-472, TST-PFM-QRY-473] --- # 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.