--- id: DOM-PFM-QRY-006 title: Monthly Snapshot realises: CON-PFM-QRY-006 product_area: platform module: queries revision: 1 status: draft design_intent: confirmed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 owned_by: SVC-PFM-QRY-snapshots readable_by: [] lifecycle: STATE-PFM-QRY-014 custom_fields: none identity: >- Each snapshot run identifies a workspace, registered type, local calendar month and version. Scheduled planning creates version one; a requested rerun allocates the next version and replaces the current version only after publication. attributes: - name: snapshot type kind: reference required: true computed: false notes: >- Owners register estimation, generation and validation behavior; disabled types are not registered. - name: owner service kind: text required: true computed: false notes: 'The owning service’s database role can write its runs, and its schema retains generated rows.' - name: period kind: date required: true computed: false notes: 'The period describes the workspace-local month, capture basis and publication due time.' - name: version and supersession kind: number required: true computed: false notes: 'The run retains its period version, superseded version and current-version marker.' - name: status kind: enum required: true computed: false notes: >- The ledger distinguishes planned, queued, running, validating, published, failed, skipped and cancelled work. - name: trigger and reason kind: enum required: true computed: false notes: >- Triggers distinguish scheduled, period-close, manual and backfill requests; staff requests require a reason. - name: basis kind: enum required: true computed: false notes: >- The basis records captured, finalized, reconstructed, estimated or imported history. Backfill does not replace captured or finalized data without an explicit supersession request. - name: attempts and outcome kind: collection required: false computed: true notes: >- Attempts retain the current job, row count and failure or skip details, with retry delays of fifteen minutes, one hour and four hours. - name: eligibility policy kind: collection required: false computed: false notes: >- Staff can override type-specific or workspace-wide eligibility with a reason and optional starting period. Type-specific policy takes precedence over workspace policy and defaults. - name: snapshot rows kind: collection required: true computed: true notes: >- Type owners retain their generated rows separately; Platform’s enabled self-test produces four user-status counts. relationships: - to: DOM-PFM-QRY-003 cardinality: one-to-many ownership: >- Available-period reads support an intended report month selector; the console has not connected that selector. cross_service: false invariants: - id: INV-DOM-PFM-QRY-006-01 statement: >- Unique indexes allow one active run and one current version for each workspace, type and period. enforced_at: - database provenance: observed source: >- services-platform:modules/snapshots/db/snapshot-runs.table.ts (the library's active and current unique indexes) - id: INV-DOM-PFM-QRY-006-02 statement: >- Final validation and publication commit together. Small-run failures discard all generated rows; chunked failures can retain committed but unpublished rows. enforced_at: - service - database provenance: observed source: >- services-platform:node_modules/@rhythmsoftware/macroservice-snapshots/dist/snapshot-run-workflow.js:advanceSnapshotRun - id: INV-DOM-PFM-QRY-006-03 statement: >- Database security confines each owning service to its runs and prevents application roles from deleting ledger rows. enforced_at: - database provenance: observed source: >- services-platform:modules/snapshots/db/snapshot-runs.table.ts (migration 0105, snapshotSecuritySql) - id: INV-DOM-PFM-QRY-006-04 statement: >- Runs preserve earlier versions as history until workspace deletion removes the workspace’s data. enforced_at: - service provenance: observed source: 'services-platform:modules/snapshots/services/persistence/snapshot-runs.ts' - id: INV-DOM-PFM-QRY-006-05 statement: >- The planner inserts only period version one, so repeated planning does not create duplicate scheduled versions. enforced_at: - database - service provenance: observed source: 'services-platform:modules/snapshots/aws/logic/snapshots-functions.lambda.ts' - id: INV-DOM-PFM-QRY-006-06 statement: Admission respects the configured total cap and permits at most one admitted backfill. enforced_at: - service provenance: observed source: 'services-platform:modules/snapshots/aws/snapshots.configuration.ts' - id: INV-DOM-PFM-QRY-006-07 statement: >- Workspace period reads remain workspace-scoped and select the current version, or otherwise the highest version, for each month. enforced_at: - service - database provenance: test source: >- services-platform:modules/snapshots/tests/e2e/snapshots.e2e.spec.js#refuses another customer’s user the tenant’s periods physical: - platform.snapshot_runs - platform.snapshot_tenant_policies - platform.snapshot_run_jobs - platform.snapshot_run_job_steps - platform.snapshot_run_job_events - platform.snapshot_user_status_counts evidence: - >- services-platform at ad3f6a6: modules/snapshots/**; @rhythmsoftware/macroservice-snapshots (snapshot-states); docs/snapshots/README.md; docs/proposals/snapshot-architecture.md (D1–D8 approved 2026-10-15) --- # Monthly Snapshot ## What It Models Monthly snapshots preserve a versioned view for later reporting. The shared ledger makes missing, skipped and failed periods visible as operational outcomes. ## Identity and Attributes Every type owns its generation behavior and rows. The workspace’s time zone defines its calendar periods; staff policy controls eligibility. ## Relationships The available-period interface is ready for a report selector, but the corresponding console integration remains unfinished. ## Invariants The invariant rows separate final publication atomicity from chunk staging. Earlier published versions remain current when final validation fails. ## How It Is Stored and Shared The snapshot service declares the shared ledger and Platform self-test types. Owner roles use the shared library; the jobs HTTP function hosts snapshot routes. ## Open Design Questions Cross-application staff reruns and backfills remain outside the implemented scope. Product must reconcile the failed-run row-retention promise with chunked generation.