---
id: CAP-MBR-STR-016
title: Interpret membership status and continuity by date
feature: FEAT-MBR-STR-05
product_area: membership
module: structure
revision: 1
status: draft
product_intent: proposed
implementation_evidence: observed
supersedes: []
source_sha:
  services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
intent_sources:
  - >-
    services-membership:README.md#The term engine (D-45, decided 2026-10-17: the engine imports nothing of
    Membership and is extracted later)
purpose: Rhythm determines a holding’s standing and continuity from its effective periods and configured allowances.
outcomes:
  - Status can be interpreted consistently on a requested date.
  - Cache and sweep decisions identify changes without owning membership persistence.
concepts:
  - CON-MBR-STR-005
actors:
  - ACT-MBR-004
  - ACT-MBR-002
surfaces:
  - job
  - api
preconditions: []
postconditions: []
permissions:
  - key: membership.application.access
    where_checked: api
    scope: tenant
rules:
  - id: BR-CAP-MBR-STR-016-01
    proved_by: [ATS-MBR-STR-015-12, ATS-MBR-STR-016-01, TST-MBR-STR-013, TST-MBR-STR-016]
    statement: >-
      Status precedence is suspension, covering active status with or without benefits, grace, lapse, future,
      pending and no status.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-membership:modules/terms/tests/unit/status.spec.ts#holding status: the precedence of §2 › puts
      suspended over grace
    origin: none
  - id: BR-CAP-MBR-STR-016-02
    proved_by: [ATS-MBR-STR-016-02, ATS-MBR-STR-017-05, TST-MBR-STR-016]
    statement: >-
      Committed, superseded and terminated terms count for their effective dates; pending and cancelled terms
      do not, and cancelled terms do not start grace.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-membership:modules/terms/tests/unit/status.spec.ts#holding status: the effective states of §1 ›
      never lets a pending term cover a date
    origin: none
  - id: BR-CAP-MBR-STR-016-03
    proved_by: [ATS-MBR-STR-009-09, ATS-MBR-STR-016-03, TST-MBR-STR-014, TST-MBR-STR-016, TST-MBR-STR-097]
    statement: >-
      Grace follows the latest ended effective term, uses its type override or program allowance and includes
      its final day before lapse.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-membership:modules/terms/tests/unit/status.spec.ts#holding status: the rows of §2 › is in grace
      on the last day of grace (D = E + grace_days)
    origin: none
  - id: BR-CAP-MBR-STR-016-04
    proved_by: [ATS-MBR-STR-011-07, ATS-MBR-STR-016-04, ATS-MBR-STR-016-11, TST-MBR-STR-014, TST-MBR-STR-016]
    statement: A covering term without classification benefits produces active status without benefits.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-membership:modules/terms/tests/unit/status.spec.ts#holding status: the rows of §2 › is active
      without benefits when the covering term’s classification confers none
    origin: none
  - id: BR-CAP-MBR-STR-016-05
    proved_by: [ATS-MBR-STR-016-05, TST-MBR-STR-016, TST-MBR-STR-097]
    statement: >-
      Effective periods within the continuity allowance form episodes, and continuous membership refers to the
      latest episode begun by the requested date even after it ends.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-membership:modules/terms/services/status.ts:continuousSinceOf'
    origin: none
  - id: BR-CAP-MBR-STR-016-06
    proved_by: [ATS-MBR-STR-016-06, TST-MBR-STR-014, TST-MBR-STR-097]
    statement: >-
      An absent original join date takes the earliest effective start, while a join date already supplied is
      retained.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: documented
    source: 'services-membership:modules/terms/services/holding-cache.ts:firstJoinDateOf'
    origin: none
  - id: BR-CAP-MBR-STR-016-07
    proved_by: [ATS-MBR-STR-016-07, TST-MBR-STR-017]
    statement: >-
      Normal sweeps select starting, expiry and grace-ending boundaries, while a missed or absent prior sweep
      calls for full recomputation.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-membership:modules/terms/tests/unit/sweep.spec.ts#the sweep’s catch-up rule › catches up after
      a missed night
    origin: none
  - id: BR-CAP-MBR-STR-016-08
    proved_by: [ATS-MBR-STR-016-08, TST-MBR-STR-017]
    statement: >-
      Sweep detections identify expiry after a term ends and lapse after grace ends, with no detections during
      suspension or a covering effective term.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-membership:modules/terms/tests/unit/sweep.spec.ts#the sweep’s detections › detects the lapse
      the day after grace ends, effective that day, with the expiry
    origin: none
  - id: BR-CAP-MBR-STR-016-09
    proved_by: []
    statement: >-
      The cache decision returns only differences in computed cache values and leaves persistence and
      entitlement enforcement to its caller.
    kind: invariant
    enforced_at:
      - service
    must_prove: false
    provenance: observed
    source: 'services-membership:modules/terms/services/holding-cache.ts:holdingCacheChanges'
    origin: none
  - id: BR-CAP-MBR-STR-016-10
    proved_by: []
    statement: Status and continuity inputs reject negative or fractional day allowances.
    kind: validation
    enforced_at:
      - service
    must_prove: false
    provenance: test
    source: >-
      services-membership:modules/terms/tests/unit/status.spec.ts#holding status: the effective states of §1 ›
      refuses a negative number of grace days
    origin: none
  - id: BR-CAP-MBR-STR-016-11
    proved_by: [ATS-MBR-STR-016-09, TST-MBR-STR-012]
    statement: >-
      Engine column declarations constrain term date order, five term states and eight cached holding
      statuses.
    kind: invariant
    enforced_at:
      - database
    must_prove: true
    provenance: test
    source: >-
      services-membership:modules/terms/tests/unit/columns.spec.ts#term columns (§3.2) › order the dates: an
      end, when there is one, on or after the start
    origin: none
  - id: BR-CAP-MBR-STR-016-12
    proved_by: [ATS-MBR-STR-016-10, TST-MBR-STR-013]
    statement: >-
      Unbuilt Commerce-participant and billing-run engine hooks fail with errors naming their intended
      delivery phase.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-membership:modules/terms/tests/unit/define-term-engine.spec.ts#defineTermEngine › refuses the
      Commerce participant, naming P3
    origin: none
scenarios:
  - id: SC-CAP-MBR-STR-016-01
    given: Sam’s effective term ends in September with sixty grace days.
    when: Status is evaluated on the following October day and at the start of December.
    then: The earlier date returns grace and the later date returns lapse.
    provenance: test
    source: >-
      services-membership:tests/e2e/s04-lapse-and-rejoin.e2e.spec.ts#scenario 4: lapse, drop and rejoin
      through a staff term › answers grace the day after the term ended and lapsed once the 60 days are over
edge_cases:
  - id: SC-CAP-MBR-STR-016-02
    given: The holding is in grace and its purchased renewal is still pending.
    when: The holding’s status is evaluated.
    then: The pending period does not displace grace with active status.
    provenance: test
    source: >-
      services-membership:modules/terms/tests/unit/status.spec.ts#holding status: the precedence of §2 › keeps
      a member in grace who has bought a pending renewal
constraints: []
depends_on:
  - CAP-MBR-STR-015
  - CAP-MBR-STR-009
related:
  - CAP-MBR-STR-011
journeys:
  - JNY-MBR-STR-005
open_questions:
  - OQ-MBR-STR-003
evidence:
  - >-
    services-membership: Examination of the term engine’s status, episode, cache and sweep functions and the
    engine definition.
  - 'services-membership: Examination of their unit suites and scenario 4 end-to-end.'
  - 'services-membership:modules/terms/tests/unit/columns.spec.ts'
  - 'services-membership:modules/terms/tests/unit/define-term-engine.spec.ts'
  - 'services-membership:modules/terms/tests/unit/holding-cache.spec.ts'
  - 'services-membership:modules/terms/tests/unit/status.spec.ts'
  - 'services-membership:modules/terms/tests/unit/sweep.spec.ts'
controls: [TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-004, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-004, TC-SEC-001, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003]
exercised_by: [FAS-MBR-STR-03-02, FAS-MBR-STR-05-01, FAS-MBR-STR-05-02, FAS-MBR-STR-05-03, FAS-MBR-STR-05-04, FAS-MBR-STR-05-05]
suites: [TST-MBR-STR-012, TST-MBR-STR-013, TST-MBR-STR-014, TST-MBR-STR-016, TST-MBR-STR-017, TST-MBR-STR-097]
---

# Interpret membership status and continuity by date

## Purpose

Rhythm determines a holding’s standing and continuity from its effective periods and configured allowances.

## How It Works

The caller supplies the holding’s terms and the date being evaluated. The engine identifies which periods have been effective and which cover that date. Suspension takes precedence over the period-based result. Grace and lapse follow the latest ended effective term when none covers the date. Classification choices distinguish activity with benefits from activity without them. Continuity groups effective periods using the configured gap allowance. The latest episode begun by the date remains the continuity reference even during a later lapse. Cache computation packages the current interpretation for the caller to persist. The sweep decisions identify relevant date boundaries and catch-up work. Membership storage and scheduling remain in the memberships module. The product should review grace-benefit behavior separately from the status vocabulary.

## Relationships

- Programs and types supply grace, continuity and benefit inputs.
- Term-date computation determines the periods being interpreted.
- The memberships module persists caches and executes scheduled work.