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.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Status can be interpreted consistently on a requested date.Cache and sweep decisions identify changes without owning membership persistence.
Surfaces: jobapi
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)

Controls

27 controls apply, from the corpus control catalogue.

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

Permissions

Key	Checked at	Scope
`membership.application.access`	api	tenant

Business Rules

12 rules, 10 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	Status precedence is suspension, covering active status with or without benefits, grace, lapse, future, pending and no status. no proof recorded yet	calculation	service	test services-membership:modules/terms/tests/unit/status.spec.ts#holding status: the precedence of §2 › puts suspended over grace
`02`must prove Proposed	Committed, superseded and terminated terms count for their effective dates; pending and cancelled terms do not, and cancelled terms do not start grace. no proof recorded yet	calculation	service	test services-membership:modules/terms/tests/unit/status.spec.ts#holding status: the effective states of §1 › never lets a pending term cover a date
`03`must prove Proposed	Grace follows the latest ended effective term, uses its type override or program allowance and includes its final day before lapse. no proof recorded yet	calculation	service	test 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)
`04`must prove Proposed	A covering term without classification benefits produces active status without benefits. no proof recorded yet	calculation	service	test 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
`05`must prove Proposed	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. no proof recorded yet	calculation	service	observed services-membership:modules/terms/services/status.ts:continuousSinceOf
`06`must prove Proposed	An absent original join date takes the earliest effective start, while a join date already supplied is retained. no proof recorded yet	calculation	service	documented services-membership:modules/terms/services/holding-cache.ts:firstJoinDateOf
`07`must prove Proposed	Normal sweeps select starting, expiry and grace-ending boundaries, while a missed or absent prior sweep calls for full recomputation. no proof recorded yet	calculation	service	test services-membership:modules/terms/tests/unit/sweep.spec.ts#the sweep’s catch-up rule › catches up after a missed night
`08`must prove Proposed	Sweep detections identify expiry after a term ends and lapse after grace ends, with no detections during suspension or a covering effective term. no proof recorded yet	calculation	service	test 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
`09` Proposed	The cache decision returns only differences in computed cache values and leaves persistence and entitlement enforcement to its caller.	invariant	service	observed services-membership:modules/terms/services/holding-cache.ts:holdingCacheChanges
`10` Proposed	Status and continuity inputs reject negative or fractional day allowances.	validation	service	test services-membership:modules/terms/tests/unit/status.spec.ts#holding status: the effective states of §1 › refuses a negative number of grace days
`11`must prove Proposed	Engine column declarations constrain term date order, five term states and eight cached holding statuses. no proof recorded yet	invariant	database	test 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
`12`must prove Proposed	Unbuilt Commerce-participant and billing-run engine hooks fail with errors naming their intended delivery phase. no proof recorded yet	policy	service	test services-membership:modules/terms/tests/unit/define-term-engine.spec.ts#defineTermEngine › refuses the Commerce participant, naming P3

Scenarios

Id	Given	When	Then	Provenance
`01`	Sam’s effective term ends in September with sixty grace days.	Status is evaluated on the following October day and at the start of December.	The earlier date returns grace and the later date returns lapse.	test 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	Given	When	Then	Provenance
`02`	The holding is in grace and its purchased renewal is still pending.	The holding’s status is evaluated.	The pending period does not displace grace with active status.	test 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

Planning

Interpret membership status and continuity by date ​

Purpose ​

How It Works ​

Relationships ​