--- id: CON-MBR-STR-005 name: Term Lifecycle feature: FEAT-MBR-STR-05 product_area: membership module: structure revision: 1 status: draft product_intent: proposed implementation_evidence: observed source_sha: services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- The term lifecycle is the shared interpretation of term dates, effective states, membership standing and continuity, with cache and boundary-processing decisions. owned_by: MOD-MBR-STR synonyms: - term engine - period interpretation not_to_be_confused_with: - Stored membership terms - Price calculation - Purchase fulfilment facets: - name: Period calculation meaning: Offering rules produce a start and optional end from explicit calendar inputs. used_for: Deriving term dates consistently. - name: Later purchases meaning: Continuation and reinstatement distinguish retained period continuity from a fresh start. used_for: Interpreting renewal and rejoin dates. - name: Effective states meaning: 'Committed, superseded and terminated periods count, while pending and cancelled periods do not.' used_for: Selecting periods relevant to standing. - name: Membership standing meaning: 'Precedence resolves suspension, activity, grace, lapse and future or pending conditions.' used_for: Answering a holding’s status on a date. - name: Grace allowance meaning: Type-specific or program days extend the grace interpretation after an effective end. used_for: Identifying the transition to lapse. - name: Continuity meaning: Effective periods form episodes using the permitted gap between them. used_for: Supplying continuous-membership dates independently of first join. - name: Boundary work meaning: Sweep decisions select date boundaries and full recomputation after missed work. used_for: Keeping cached interpretations and detections current. - name: Action explanations meaning: 'Configured reasons distinguish termination, cancellation and suspension uses.' used_for: Explaining membership status actions. relationships: - to: CON-MBR-STR-004 statement: Package date and renewal settings provide inputs to period calculation. provenance: observed source: 'services-membership:modules/configuration/services/persistence/membership-packages.ts' - to: CON-MBR-STR-003 statement: Classification and program inputs provide grace and continuity settings. provenance: observed source: 'services-membership:modules/terms/services/holding-cache.ts:holdingCacheOf' lifecycle: - state: pending meaning: The period has not become effective coverage. how_it_changes: The owning membership process commits or cancels it. - state: committed meaning: The period contributes coverage over its dates even after those dates pass. how_it_changes: Its owner can supersede or terminate it; reaching its end does not itself change this state. - state: terminated meaning: The period retains its earlier effective coverage up to the recorded end. how_it_changes: The terminated period remains historical rather than becoming a fresh period. - state: cancelled meaning: The period contributes no effective date coverage. how_it_changes: The cancelled period remains an ineffective historical record. acted_on_by: - CAP-MBR-STR-015 - CAP-MBR-STR-016 - CAP-MBR-STR-017 visible_to: - ACT-MBR-001 - ACT-MBR-002 - ACT-MBR-004 evidence: - >- services-membership: Verified material includes the term engine’s term rules, status, episodes, cache and sweep functions, and the status reasons configuration. - >- services-membership: Verified material includes the term engine unit suites (with Rhythm 1.0’s cases) and scenario 4. supersedes: - react-console acceptance inventory CAP-MBR-CFG-005 - react-console acceptance inventory CAP-MBR-CFG-008 --- # Term Lifecycle ## What It Is The term lifecycle is how Rhythm interprets membership periods over time. It determines a period’s dates from an offering rule and answers the holding’s standing on a requested date from its terms. It also groups effective periods into continuity episodes and supplies decisions for cached views and nightly boundary work. These are related interpretations of time rather than additional memberships to create. The engine receives explicit inputs and returns decisions. It does not read an ambient clock or own the membership rows it interprets. Anniversary and calendar calculations retain substantial Rhythm 1.0 behavior, while selected differences include real February month endings and nonmutating inputs. The recorded extraction intent keeps the engine independent so another term-based domain can eventually use the same mechanism. ## What It Is Not The engine does not replace the stored terms belonging to a membership. It does not compute monetary amounts or decide that an order has been paid. Term state is also distinct from date-based standing: a committed period can finish without its state becoming a new expiry state. Cached status is a convenient stored interpretation, not a substitute for resolving the relevant date. ## How It Is Used Consumers request dates when preparing a period and status when interpreting a holding. They can ask about an earlier date using the same effective-period rules. Membership administration persists the decisions and runs the sweep on its own schedule. Staff configure action reasons and select them during status actions. Surprising outcomes often arise at fixed-window boundaries or where two consumers interpret an absent reinstatement allowance differently. Those cases need product decisions rather than a different wording of the same calculation. ## Its Facets **Period calculation.** The basis, length and threshold choices determine the dates. **Later purchases.** Continuation begins after an existing end, while a restart uses a fresh basis. **Effective states.** Earlier committed history remains relevant after supersession or termination. **Membership standing.** Suspension and covering periods take precedence over later status possibilities. **Grace allowance.** A classification override can replace the program allowance, including with zero. **Continuity.** The latest episode begun by a requested date remains its continuity reference even after that episode ends. **Boundary work.** Normal sweeps select relevant boundaries; missed work requires catch-up. **Action explanations.** Reasons qualify particular status actions rather than replacing effective dates. ## How It Relates Packages supply date rules and renewal choices. Programs and types supply allowances and benefits information. The memberships module owns holding records, terms, caches, event persistence and scheduling. Commerce requests relevant decisions while retaining monetary responsibility. Configuration safeguards govern the reason catalogue used by staff actions. ## What It Could Become The product should settle first-purchase behavior immediately after a fixed window closes and reconcile empty reinstatement meanings across consumers. It should also decide what grace means for benefits, beyond the existing status label. A second adopting domain can trigger the recorded extraction, but that reuse should preserve explicit inputs and the separation between decisions and persistence.