---
id: STATE-MBR-MEM-012
title: Monthly snapshot version
object: DOM-MBR-MEM-006
product_area: membership
module: memberships
revision: 1
status: draft
design_intent: proposed
implementation_evidence: partially-observed
source_sha:
  services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
states:
  - name: planned
    meaning: The snapshot ledger has scheduled work that has not begun.
  - name: running
    meaning: An admitted job is generating and checking the month.
  - name: published
    meaning: The month’s validated rows are published as the current version.
  - name: failed
    meaning: An attempt failed and may qualify for another ledger retry.
  - name: superseded
    meaning: >-
      A newer publication is current; this version remains available for earlier
      reports.
transitions:
  - from: planned
    to: running
    trigger: Dispatch admits planned work.
    guard: The ledger permits this run under its cap.
    side_effects:
      - Ensure the required month storage before generation.
    who: Snapshot dispatcher
    provenance: observed
    source: >-
      services-membership:modules/snapshots/aws/logic/snapshot-functions.lambda.ts
  - from: running
    to: published
    trigger: Generation completes and checks pass.
    guard: >-
      Grouped totals, type references, independent count and affiliation
      ownership checks succeed.
    side_effects:
      - Publish the new version and replace the prior current selection.
    who: Snapshot run job
    provenance: test
    source: >-
      services-membership:modules/snapshots/tests/integration/membership-snapshot.integration.spec.ts#fails
      the run on the counts check, publishes nothing
  - from: running
    to: failed
    trigger: Generation or validation fails.
    guard: A supported check or execution error aborts the attempt.
    side_effects:
      - >-
        Publish nothing; the ledger applies retry back-off and final failure
        handling.
    who: Snapshot run job
    provenance: observed
    source: >-
      services-membership:modules/snapshots/services/runs/snapshot-run-workflow.ts
      (header)
  - from: failed
    to: running
    trigger: An eligible retry becomes due.
    guard: The shared ledger has not exhausted its retry budget.
    side_effects:
      - Admit another attempt under the dispatch cap.
    who: Snapshot dispatcher
    provenance: observed
    source: >-
      services-membership:modules/snapshots/services/runs/snapshot-run-workflow.ts
      (header)
  - from: published
    to: superseded
    trigger: A subsequent rerun passes publication checks.
    guard: The newer version is validated.
    side_effects:
      - >-
        Use the new current version while retaining prior rows and captured
        characteristics.
    who: Snapshot run job
    provenance: test
    source: >-
      services-membership:modules/snapshots/tests/integration/membership-snapshot.integration.spec.ts#writes
      identical member, affiliation and count rows with the original known_at
invalid:
  - from: failed
    to: published
    why: Only successful validated generation can publish a month.
  - from: superseded
    to: published
    why: >-
      Normal reruns publish newer versions and do not reselect an earlier
      version as current.
concurrency: >-
  Scheduled reconstruction uses the exclusive month end in the customer zone.
  Dispatch uses its cap and owner lock; generation failure leaves the prior
  publication visible.
invariants:
  - INV-DOM-MBR-MEM-006-05
  - INV-DOM-MBR-MEM-006-06
evidence:
  - >-
    services-membership at 5994c270:
    modules/snapshots/services/runs/snapshot-run-workflow.ts;
    services/types/membership-snapshot.ts;
    services/generation/membership-snapshot-checks.ts;
    aws/logic/snapshot-functions.lambda.ts
---

# Monthly snapshot version

## The Lifecycle

```mermaid
stateDiagram-v2
  state planned
  state running
  state published
  state failed
  state superseded
  planned --> running
  running --> published
  running --> failed
  failed --> running
  published --> superseded
```

## Transitions Explained

The shared snapshot ledger governs run admission and retry. Membership generates, checks and publishes a complete month within a transaction. A later successful rerun changes the current version while keeping earlier publications available.

## What Cannot Happen

Failed generation cannot publish unchecked rows. An earlier superseded version has no normal path back to current through Membership’s generation flow.

## Concurrency and Timing

Scheduled reconstruction uses the exclusive month end in the customer zone. Dispatch uses its cap and owner lock; generation failure leaves the prior publication visible.