--- id: CON-MBR-MEM-002 name: Membership Term feature: FEAT-MBR-MEM-01 product_area: membership module: memberships revision: 1 status: draft product_intent: confirmed implementation_evidence: observed source_sha: services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A membership term records one period under a membership type and usually a package, with dates and a state distinguishing reservation, commitment, supersession and closure. owned_by: MOD-MBR-MEM synonyms: - membership period - membership year not_to_be_confused_with: - The membership persists across its periods. - A package’s term rule calculates a period rather than being the period itself. facets: - name: Dates meaning: 'Inclusive local start and end days, with the planned end retained when a period is shortened.' used_for: 'Establishing coverage and the boundaries used for grace, renewal and billing.' - name: Type and package meaning: The type held for this period and any package used to establish it. used_for: 'Applying benefits, grace, unit requirements, grants and purchase policy.' - name: State meaning: >- Pending, committed, superseded, terminated and cancelled distinguish reservation, effective periods and closure. used_for: Determining which periods participate in date-based standing. - name: How it was made meaning: >- The creation operation distinguishes staff entry, purchase, import and derived periods, with source references for mirrored terms. used_for: Explaining how a period arose and which source controls it. - name: Purchase references meaning: >- Order, line and authorization references connect purchased periods to Commerce, alongside reservations and purchase fences. used_for: 'Supporting fulfilment, cancellation and accountability without storing the money here.' - name: Closing reason meaning: A closing status reason accompanies recorded closure attribution and time. used_for: Explaining cancellations and terminations in membership reporting. - name: Versions meaning: Earlier term values retain the time they were recorded and their actor. used_for: Reconstructing a period as previously known and inspecting corrections. - name: Migration quality meaning: Imported periods retain the producer’s classification of migration quality. used_for: Helping staff assess the reliability of loaded history. relationships: - to: CON-MBR-MEM-001 statement: 'One membership owns each period, and the period carries that membership’s program.' provenance: observed source: 'services-membership:modules/memberships/db/membership-terms.table.ts' - to: CON-MBR-MEM-003 statement: Dated unit affiliations belong to the term during which they place the member in those units. provenance: observed source: 'services-membership:modules/memberships/db/membership-term-organizational-units.table.ts' - to: CON-MBR-MEM-005 statement: Billing plans select actions from terms whose end dates fall within the run’s range. provenance: observed source: 'services-membership:modules/billing/services/planning/run-plan.ts' acted_on_by: - CAP-MBR-MEM-001 - CAP-MBR-MEM-002 - CAP-MBR-MEM-003 - CAP-MBR-MEM-005 - CAP-MBR-MEM-006 - CAP-MBR-MEM-009 - CAP-MBR-MEM-010 - CAP-MBR-MEM-012 - CAP-MBR-MEM-013 - CAP-MBR-MEM-014 - CAP-MBR-MEM-020 visible_to: - ACT-MBR-006 - ACT-MBR-007 - ACT-MBR-008 - ACT-MBR-009 - ACT-MBR-010 lifecycle: - state: pending meaning: The purchase reserves a period that has not yet taken effect. how_it_changes: >- Fulfilment commits it; purchase cancellation or application rejection can cancel it; release of a voided reservation deletes the pending term. - state: committed meaning: The period contributes coverage on its effective days. how_it_changes: >- Staff correction updates the term while retaining prior versions; closure changes its state, and natural expiry leaves the dates in place. - state: superseded meaning: The state represents a restated term whose effective dates can still contribute coverage. how_it_changes: 'The planned amendment workflow uses this state, but current live operations do not produce it.' - state: terminated meaning: A recorded termination closes a period early or records a drop after its existing end. how_it_changes: This is a final lifecycle state. - state: cancelled meaning: The cancelled period provides no effective coverage and no longer reserves its days. how_it_changes: This is a final lifecycle state. evidence: - >- services-membership at 5994c270e8a37a30f848e99ba5b5ee6b87c08893: modules/memberships/db/membership-terms.table.ts, membership-terms-versions.table.ts; modules/terms/db/term-columns.ts; services/operations/staff-operations.ts, term-writes.ts; modules/commerce-participant/db/commerce-claims.table.ts; services/fulfilment/fulfill.ts; docs/migrations/membership-core/README.md; docs/migrations/participant/README.md. supersedes: - 'inventory:CAP-MBR-MEM-014' --- # Membership Term ## What It Is A term describes one period within a continuing membership. It might be a Regular membership year, a prepaid future year or an open-ended lifetime period. The term identifies the type held, any package used and the local days covered. It also records how the period arose, allowing a staff entry, imported history, purchase and derived benefit to remain distinguishable. The record exists before coverage necessarily starts. Commerce reserves a pending term when an order is placed and later commits that same reservation through fulfilment. Staff can instead record a committed period directly. Package grants and organizational derivation create related periods from a source. An import supplies the historical period rather than asking live processing to infer that history. ## What It Is Not The term is a period of membership rather than the durable owner relationship itself. An order or invoice belongs to the financial workflow; its references can explain the purchase behind a term without making Membership responsible for payment accounting. A package rule supplies a calculation of dates, while the term stores the resulting period or dates explicitly supplied by staff. ## How It Is Used Coordinators add another period to a member’s existing holding, correct mistakes and record departures or drops. Their changes retain earlier values so a reader can distinguish the current correction from what was known before it. Correcting a committed term updates that record; it does not create a superseded lifecycle state. Checkout uses a reserved period to prevent competing purchases from claiming the same membership dates. Billing selects ending periods when planning renewal and drop actions. Scheduled status processing notices effective boundaries, while historical reads inspect recorded versions. Concurrent staff additions remain a delivery concern: serialization can prevent an overlap while still allowing two undated renewals to book consecutive periods. ## Its Facets **Dates.** Start and end days are inclusive in the workspace calendar. A period can have no end. The planned end remains available when a closure shortens the actual period. **Type and package.** The type identifies the membership classification held during these days. A package supplies the associated offer and period calculation, with related unit and grant policies. Derived periods can hold a type without purchasing a package of their own. **State.** Pending reserves dates without granting coverage. Committed, superseded and terminated periods contribute through their effective dates; cancellation removes effective coverage. Live amendment processing that would produce supersession remains unbuilt. **How it was made.** The operation distinguishes direct entry, purchase, import and dependent creation. A mirrored period refers to its source, so later processing can follow that source rather than treating the benefit as independently editable. **Purchase references.** A purchased period retains the order, line and authorization associated with fulfilment. Reservation and cancellation controls coordinate Membership’s records with Commerce’s transaction and delivery obligations. **Closing reason.** A closure can retain a configured status reason together with its time and actor. These facts help explain why a member’s period ends rather than merely showing that it does. **Versions.** Recorded versions preserve earlier dates and classifications. Historical reads use the recording time to answer what was known before or after a correction. **Migration quality.** Producer-supplied quality classifications describe how confidently an imported period represents earlier membership history. They accompany the loaded term without replacing its dates or state. ## How It Relates The membership owns the period and determines its program. Unit affiliations belong to that period and supply dated chapter connections. Grants and organizational children refer to source terms. Applications can lead to reserved purchase periods, billing acts on selected endings, and expiry attention examines approaching end dates. History and business-event delivery remain separate records of revision and selected outcomes. ## What It Could Become The product should complete the amendment workflow before offering purchased changes of type or chapter during a term. It should also resolve corrections that move a start earlier without moving the associated chapters and make simultaneous staff renewals behave deliberately. Those choices need to preserve the distinction between correcting a recorded fact, purchasing a change and adding another period.