--- id: CON-PFM-QRY-006 name: Monthly Snapshot feature: FEAT-PFM-QRY-08 product_area: platform module: queries revision: 1 status: draft product_intent: confirmed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A monthly snapshot retains a versioned view of application data for a workspace month, with a shared ledger explaining how that view was planned, validated and published. owned_by: MOD-PFM-QRY synonyms: - Period snapshot - Month-end history not_to_be_confused_with: - A downloadable package outside the service - A record’s individual change history - A database restoration backup facets: - name: Snapshot type meaning: The owning application declares the subject it records at month end. used_for: Keeping separate histories for different business subjects. source: 'services-platform:docs/proposals/snapshot-architecture.md' provenance: documented - name: Period meaning: A workspace-local month identifies the history being described. used_for: Selecting a past reporting month. source: 'services-platform:docs/proposals/snapshot-architecture.md' provenance: documented - name: Run and version meaning: 'An attempt has a version within its type and month, with a published current selection.' used_for: Repairing history while retaining earlier publications. source: 'services-platform:docs/proposals/snapshot-architecture.md' provenance: documented - name: Eligibility and policy meaning: Defaults and staff overrides decide which workspace periods receive work. used_for: Explaining admitted and skipped periods. source: 'services-platform:docs/proposals/snapshot-architecture.md' provenance: documented - name: Validation meaning: The owner checks its computed rows before publication. used_for: Avoiding publication of a failed calculation. source: 'services-platform:docs/proposals/snapshot-architecture.md' provenance: documented - name: Basis meaning: The run records whether its figures come from dated history or a capture of current state. used_for: Interpreting the historical meaning of a result. source: 'services-platform:docs/proposals/snapshot-architecture.md' provenance: documented relationships: - to: CON-PFM-QRY-003 statement: >- Available-period reads support a future report month picker, whose console consumption remains unfinished. provenance: documented source: 'services-platform:docs/snapshots/README.md#The APIs' lifecycle: - state: planned meaning: The period has ledger work awaiting its owner’s dispatcher. how_it_changes: Owner admission begins processing or records an eligibility skip. - state: running meaning: The owning application computes the period’s rows. how_it_changes: Validation leads to publication or a recorded failed attempt. - state: published meaning: The period has a retained publication and a current version. how_it_changes: A later successful rerun selects a new current version without removing the older one. - state: failed or skipped meaning: The period has an unsuccessful or intentionally omitted run with a reason. how_it_changes: Failures can retry or be rerun; operators can revisit missing periods. acted_on_by: - CAP-PFM-QRY-019 visible_to: - ACT-PFM-013 - ACT-PFM-015 - ACT-PFM-012 - ACT-PFM-016 evidence: - 'Pinned reference: services-platform:docs/snapshots/README.md' supersedes: [] origin: 'services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions' intent_sources: - 'services-platform:docs/proposals/snapshot-architecture.md#13.2 Decisions' --- # Monthly Snapshot ## What It Is A monthly snapshot is retained application information for the end of a particular workspace month. It supports questions that current records alone cannot answer reliably, such as the receivables position at a previous month end. The month follows the workspace’s calendar rather than a single shared server clock. Each application declares what its snapshot type captures and stores the resulting rows it owns. Platform supplies the shared ledger, policies and execution framework. The ledger records which month was considered, why work was admitted or skipped, which version ran and whether validation and publication succeeded. Product can therefore distinguish a missing month from an intentionally omitted one and a current publication from an earlier retained version. A snapshot is identified by its workspace, subject type and period, with versioned attempts underneath that identity. A rerun can repair a period without pretending the earlier published figures never existed. This gives historical reporting an accountable basis rather than only another table of copied rows. ## What It Is Not A snapshot does not deliver a portable customer package or restore a database backup. It remains within application history for reporting. Record revisions explain successive changes to one record; a snapshot describes a selected population at a period boundary. Platform also does not define the business meaning of every snapshot row. That remains the responsibility of the application declaring the type. ## How It Is Used Applications plan and run eligible periods automatically. Their dispatchers control admission so snapshot work does not overwhelm shared resources. Validation checks the produced rows before publication selects a current version. A failed attempt preserves the earlier current publication, records its reason and can be retried. Rhythm staff inspect runs and missing periods through HQ operations. They can adjust a workspace policy, request a new attempt or back-fill a range. Workspace users have an API for available periods. A reporting picker is a planned consumer of that API, but the pinned console does not yet read it. Staff should not infer an existing screen from the presence of the period contract. ## Its Facets **Snapshot type.** The subject belongs to the application that calculates its history. Platform’s small self-test type exercises the framework without owning Accounting’s figures. **Period.** The label names the month described in the workspace zone. Calendar interpretation remains part of the historical meaning. **Run and version.** Attempts and retained publications explain repair. The current version is selected separately from merely having a high version number. **Eligibility and policy.** Loading state, default eligibility and explicit staff overrides affect admission. Recorded reasons make omitted periods understandable. **Validation.** Publication and validated rows are committed together so a failed validation leaves no partial publication. **Basis.** Capturing current state and reconstructing dated history are different sources of historical truth. The ledger records which basis the result uses. ## How It Relates Reports consume available historical periods. The owning application controls its snapshot rows while the shared ledger restricts writers to their own service. Workspace purge removes the workspace’s retained versions and policies. Other background work shares resource constraints, which makes dispatcher admission part of predictable operation. ## What It Could Become The product should complete the reporting consumer and clearly identify which application types are available. Additional membership history and legacy-history imports remain extensions described by the architecture. Any future archive policy should preserve the ability to explain a period’s basis, publication and repair history.