---
id: STATE-MBR-MEM-003
title: Membership term lifecycle
object: DOM-MBR-MEM-002
product_area: membership
module: memberships
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
states:
  - name: pending
    meaning: A reserved period blocks conflicting days while awaiting commitment.
  - name: committed
    meaning: The period contributes effective coverage on its inclusive dates.
  - name: superseded
    meaning: >-
      The stored vocabulary supports effective restated coverage, although
      amendment execution is missing.
  - name: terminated
    meaning: >-
      Early closure or a recorded drop retains the period’s remaining effective
      days.
  - name: cancelled
    meaning: The period contributes no effective coverage and frees its reserved days.
transitions:
  - from: pending
    to: committed
    trigger: Commerce fulfils the package obligation.
    guard: Its authorization is new and no outstanding fence blocks the holding.
    side_effects:
      - Set commitment and order references.
      - 'Record commitment, units and grants and mark the claim fulfilled.'
    who: 'Commerce, through fulfilment'
    provenance: test
    source: >-
      services-membership:modules/commerce-participant/tests/integration/participant.integration.spec.ts#answers
      a redelivered authorization with the same records
  - from: pending
    to: cancelled
    trigger: Cancellation or a rejecting decision closes the reservation.
    guard: The period remains pending.
    side_effects:
      - >-
        Close its claim as cancelled; eligible first-purchase cancellation can
        remove an otherwise empty holding.
    who: Commerce cancellation; the decision handler
    provenance: test
    source: >-
      services-membership:modules/applications/tests/integration/decision-handler.integration.spec.ts#cancels
      the pending term of a rejected application whose purchas
  - from: committed
    to: committed
    trigger: Staff correct the committed period.
    guard: The submitted version is current and revised dates do not overlap.
    side_effects:
      - 'Preserve earlier values, trim affiliations and update linked periods.'
      - Record correction and the superseded business event.
    who: Membership staff
    provenance: test
    source: >-
      services-membership:modules/memberships/tests/integration/services/staff-operations.integration.spec.ts#keeps
      the old truth of a correction in the versions
  - from: committed
    to: terminated
    trigger: A writer closes started coverage.
    guard: >-
      The effective closure date follows the start; staff also submit the
      current version.
    side_effects:
      - 'Shorten the end when needed, record closure and trim related dates.'
      - Propagate to linked periods and resolve enabled attention.
    who: 'Staff, billing runs, Commerce, the flow-down re-derivation'
    provenance: observed
    source: >-
      services-membership:modules/memberships/services/operations/staff-operations.ts:terminateTerm
  - from: committed
    to: cancelled
    trigger: A writer closes coverage before it becomes effective.
    guard: The closure date is on or before the start.
    side_effects:
      - Free the period’s days and publish cancellation.
    who: 'Staff, Commerce, the flow-down re-derivation'
    provenance: test
    source: >-
      services-membership:modules/events/tests/integration/business-events.integration.spec.ts#states
      membership.term.cancelled, not terminated, for a term that had n
  - from: committed
    to: superseded
    trigger: A future amendment restates coverage.
    guard: Amendment implementation remains absent.
    side_effects:
      - A future writer would connect the successor.
    who: 'Commerce, through modify'
    provenance: unknown
    source: FND-MBR-MEM-029
invalid:
  - from: terminated
    to: committed
    why: The supported staff and partner operations do not reopen closed coverage.
  - from: cancelled
    to: committed
    why: >-
      Cancelled coverage requires a new period rather than a reopening
      operation.
  - from: committed
    to: pending
    why: Effective coverage has no supported transition back into reservation.
  - from: terminated
    to: terminated
    why: A staff closure of already closed coverage is rejected.
concurrency: >-
  Term version checks protect staff requests and holding locks order dependent
  writes. Authorization uniqueness recognizes fulfilment repeats. Sweep
  detection does not itself change the stored term to terminated.
invariants:
  - INV-DOM-MBR-MEM-002-01
  - INV-DOM-MBR-MEM-002-03
  - INV-DOM-MBR-MEM-002-04
  - INV-DOM-MBR-MEM-002-06
  - INV-DOM-MBR-MEM-002-07
  - INV-DOM-MBR-MEM-002-09
evidence:
  - >-
    services-membership at 5994c270: modules/terms/services/status.ts
    (TERM_STATES); modules/memberships/services/operations/staff-operations.ts;
    modules/commerce-participant/services/fulfilment/fulfill.ts,
    cancellation/cancellation.ts;
    modules/applications/services/decisions/decision-handler.ts
---

# Membership term lifecycle

## The Lifecycle

```mermaid
stateDiagram-v2
  state pending
  state committed
  state superseded
  state terminated
  state cancelled
  pending --> committed
  pending --> cancelled
  committed --> committed
  committed --> terminated
  committed --> cancelled
```

## Transitions Explained

Commerce reservations begin pending and fulfilment makes them effective. Staff, import, grant and child paths can insert committed periods directly. Correction preserves committed state; closure chooses termination or cancellation according to the effective date.

## What Cannot Happen

Supported operations do not reopen closed periods or turn committed coverage into a reservation. Supersession fields exist, but the amendment transition remains unknown until implemented.

## Concurrency and Timing

Term version checks protect staff requests and holding locks order dependent writes. Authorization uniqueness recognizes fulfilment repeats. Sweep detection does not itself change the stored term to terminated.