--- id: SVC-PFM-QRY-snapshots title: Snapshots service module product_area: platform module: queries repository: services-platform source_module: modules/snapshots revision: 1 status: draft design_intent: confirmed implementation_evidence: observed inference: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-PFM-QRY-006 does_not_own: - >- Other applications register their own types and generate their rows under owner-restricted access to the shared ledger. - The jobs service supplies the HTTP function and common durable job machinery. - The report console has not implemented the period-selector integration. operations: - operation_id: getSnapshotsHealth intent: Return this API’s health and deployed service identity. method: GET /snapshots/health access: public permission: 'none: public route' realises: [] published_to_submissions: 'not published: diagnostic health read' provenance: observed source: 'services-platform:modules/snapshots/aws/api/snapshots.routes.ts:healthRoute' - operation_id: listSnapshotRunsInHq intent: Page the shared run ledger across owners and workspaces. method: GET /hq/snapshots/runs access: system permission: hq.snapshots.read realises: - CAP-PFM-QRY-019 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/snapshots/aws/api/snapshots.routes.ts:listSnapshotRunsInHq' - operation_id: getSnapshotRunInHq intent: 'Read any retained run version, including superseded history.' method: 'GET /hq/snapshots/runs/{runId}' access: system permission: hq.snapshots.read realises: - CAP-PFM-QRY-019 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/snapshots/aws/api/snapshots.routes.ts:getSnapshotRunInHq' - operation_id: getSnapshotPeriodStatusInHq intent: Inspect period coverage across expected workspaces with outcome and completeness counts. method: GET /hq/snapshots/periods access: system permission: hq.snapshots.read realises: - CAP-PFM-QRY-019 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/snapshots/aws/api/snapshots.routes.ts:getSnapshotPeriodStatusInHq' - operation_id: listOverdueSnapshotRunsInHq intent: Find overdue runs whose period still lacks publication. method: GET /hq/snapshots/overdue access: system permission: hq.snapshots.read realises: - CAP-PFM-QRY-019 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/snapshots/aws/api/snapshots.routes.ts:listOverdueSnapshotRunsInHq' - operation_id: requestSnapshotRunInHq intent: Create a reasoned new Platform-type run version for later dispatcher admission. method: POST /hq/snapshots/runs access: system permission: hq.snapshots.manage realises: - CAP-PFM-QRY-019 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/snapshots/aws/api/snapshots.routes.ts:requestSnapshotRunInHq' - operation_id: requestSnapshotBackfillInHq intent: 'Request permitted Platform-type period versions across a range, respecting protected history.' method: POST /hq/snapshots/backfills access: system permission: hq.snapshots.manage realises: - CAP-PFM-QRY-019 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/snapshots/aws/api/snapshots.routes.ts:requestSnapshotBackfillInHq' - operation_id: listSnapshotPoliciesInHq intent: Read workspace snapshot eligibility overrides. method: GET /hq/snapshots/policies access: system permission: hq.snapshots.read realises: - CAP-PFM-QRY-019 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/snapshots/aws/api/snapshots.routes.ts:listSnapshotPoliciesInHq' - operation_id: putSnapshotPolicyInHq intent: Replace the reasoned override for one type or the workspace-wide default. method: PUT /hq/snapshots/policies access: system permission: hq.snapshots.manage realises: - CAP-PFM-QRY-019 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/snapshots/aws/api/snapshots.routes.ts:putSnapshotPolicyInHq' - operation_id: deleteSnapshotPolicyInHq intent: Remove the override and restore fallback eligibility evaluation. method: DELETE /hq/snapshots/policies access: system permission: hq.snapshots.manage realises: - CAP-PFM-QRY-019 published_to_submissions: 'not published: internal staff administration' provenance: observed source: 'services-platform:modules/snapshots/aws/api/snapshots.routes.ts:deleteSnapshotPolicyInHq' - operation_id: listSnapshotPeriods intent: Read workspace periods and their current or highest version for future report selection. method: 'GET /snapshots/{tenantId}/periods' access: console permission: platform.snapshots.read realises: - CAP-PFM-QRY-019 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/snapshots/aws/api/snapshots.routes.ts:listSnapshotPeriods' - operation_id: planSnapshotRuns intent: Insert initial ended-month period versions and explicit skipped outcomes. method: EventBridge rule (rate 15 minutes) on platform_snapshot_planner access: internal permission: 'none: scheduled' realises: - CAP-PFM-QRY-019 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/snapshots/aws/api/snapshots.routes.ts (imported), aws/logic/*.ts, aws/snapshots.configuration.ts, services/**, db/*.table.ts; @rhythmsoftware/macroservice-snapshots; docs/snapshots/README.md; docs/proposals/snapshot-architecture.md (approved 2026-10-15) - operation_id: dispatchSnapshotRuns intent: Claim owner-capacity slots and submit durable attempt jobs. method: EventBridge rule (rate 1 minute) and async nudge on platform_snapshot_dispatcher access: internal permission: 'none: scheduled' realises: - CAP-PFM-QRY-019 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/snapshots/aws/api/snapshots.routes.ts (imported), aws/logic/*.ts, aws/snapshots.configuration.ts, services/**, db/*.table.ts; @rhythmsoftware/macroservice-snapshots; docs/snapshots/README.md; docs/proposals/snapshot-architecture.md (approved 2026-10-15) - operation_id: runSnapshot intent: 'Generate or resume the owner’s snapshot, then validate and publish its final transaction.' method: Step Functions platform-snapshot-run with task function platform_snapshot_run access: internal permission: 'none: submitted only by the dispatcher' realises: - CAP-PFM-QRY-019 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/snapshots/aws/api/snapshots.routes.ts (imported), aws/logic/*.ts, aws/snapshots.configuration.ts, services/**, db/*.table.ts; @rhythmsoftware/macroservice-snapshots; docs/snapshots/README.md; docs/proposals/snapshot-architecture.md (approved 2026-10-15) - operation_id: snapshotsLifecycleParticipant intent: 'Remove Platform snapshot rows, policy and ledger data during workspace purge.' method: workspace lifecycle participant (snapshots) access: internal permission: 'none: invoked by the lifecycle jobs' realises: - CAP-PFM-QRY-019 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/snapshots/aws/api/snapshots.routes.ts (imported), aws/logic/*.ts, aws/snapshots.configuration.ts, services/**, db/*.table.ts; @rhythmsoftware/macroservice-snapshots; docs/snapshots/README.md; docs/proposals/snapshot-architecture.md (approved 2026-10-15) events: [] jobs: - >- Platform plans periods every fifteen minutes and dispatches admitted runs every minute, with configured run capacity and one backfill slot. - Each attempt uses the shared snapshot durable workflow and owner-specific generation behavior. integrations: - system: Other owning services direction: inbound contract: >- Snapshot owners use the shared library to write their permitted ledger rows and generated data. - system: Durable job engine (Platform jobs module) direction: outbound contract: >- The common job engine runs and reconciles attempts, while the jobs HTTP function hosts the snapshot routes. consistency: - rule: >- Final generation, validation and current-version publication share a transaction, while earlier chunks may already be committed. kind: transactional compensation: >- A failed final transaction preserves previous publication; unpublished chunks remain for owner recovery or cleanup. - rule: Ended local months receive planned runs and eventual publication. kind: eventual compensation: 'Dispatcher retries, final-failure metrics and overdue inspection expose unfinished periods.' - rule: Unique indexes restrict the period to one active run and one current version. kind: transactional compensation: Conflicting admission or overlapping reruns are refused. evidence: - >- services-platform at ad3f6a6: modules/snapshots/aws/api/snapshots.routes.ts (imported), aws/logic/*.ts, aws/snapshots.configuration.ts, services/**, db/*.table.ts; @rhythmsoftware/macroservice-snapshots; docs/snapshots/README.md; docs/proposals/snapshot-architecture.md (approved 2026-10-15) 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-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, 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-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Snapshots service module ## What This Service Is For Snapshots supplies the shared period-run ledger and Platform’s configured self-test generation. It exposes workspace period availability and staff operational inspection. ## Boundary Each application owns its type registration, rows and generation behavior. Platform staff requests are restricted to the types registered here; other owners still share read-only operational ledger views. ## Operations in Words Staff can inspect runs, coverage and overdue periods, manage eligibility overrides and request supported new versions. Workspace readers can obtain periods for a future report selector. ## Events and Jobs Planner and dispatcher schedules lead to durable attempt jobs. The self-test registration is enabled only where configuration permits it. ## Consistency Guarantees Publication and validation are atomic in the final transaction. Large runs retain committed progress chunks, so failed final validation does not establish that the owner has no generated rows.