--- id: STATE-MBR-STR-004 title: Term effective state object: DOM-MBR-STR-005 product_area: membership module: structure revision: 1 status: draft design_intent: proposed implementation_evidence: partially-observed source_sha: services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f states: - name: pending meaning: A prepared term has not been committed and supplies no coverage. - name: committed meaning: >- A committed term supplies coverage over its inclusive effective dates, whether those dates are past, current or future. - name: superseded meaning: >- The engine recognizes this effective stored state, but the examined correction writer retains committed state while emitting a superseded event; a writer entering this state is not established. - name: terminated meaning: >- An early close retains coverage through the recorded last day; ordinary expiry does not change a committed term to this state. - name: cancelled meaning: The term supplies no coverage or grace after its effect is cancelled. transitions: - from: pending to: committed trigger: Commerce completes a claimed package purchase. guard: >- A matching claim and membership exist, the term remains pending, no Commerce fence blocks fulfilment and the frozen payload validates; an already completed authorization returns the previous result. side_effects: - The term becomes committed with purchase and authorization references. - 'Affiliations, grants, history and caches are written and the claim closes in the same transaction.' who: Membership purchase participant provenance: observed source: 'services-membership:modules/commerce-participant/services/fulfilment/fulfill.ts:fulfill' - from: pending to: cancelled trigger: Commerce authorizes cancellation of a pending purchase. guard: >- The cancellation obligation resolves its claim and pending term; repeated completed obligations are handled by the cancellation flow. side_effects: - The term becomes ineffective; a claim-created membership can be removed if no other term requires it. who: Membership purchase participant provenance: observed source: 'services-membership:modules/commerce-participant/services/cancellation/cancellation.ts:cancel' - from: committed to: committed trigger: 'Staff correct dates, classification or package on a committed term.' guard: >- The principal membership and term are locked, the supplied version matches, the term is committed, selected type and package are valid, and corrected dates pass ordering and overlap checks. side_effects: - >- The existing term remains committed with corrected values; versions retain previous values and a superseded event describes the correction. who: Membership staff operations provenance: observed source: 'services-membership:modules/memberships/services/operations/staff-operations.ts:correctTerm' - from: committed to: terminated trigger: 'Staff end a started term, or Commerce applies an authorized termination.' guard: >- Staff require a committed principal term at the read version and an active termination reason; Commerce uses its own authorized cancellation contract. side_effects: - >- The last day is shortened when appropriate, the term becomes terminated and dependent granted terms and derived membership data follow. who: Membership staff or purchase operations provenance: observed source: 'services-membership:modules/memberships/services/operations/staff-operations.ts:terminateTerm' - from: committed to: cancelled trigger: 'Staff end a term on or before its start, or Commerce cancels an unstarted term.' guard: >- Staff require a committed principal term at the read version and accept an active cancellation reason or the explicit termination-reason fallback; Commerce uses its own cancellation guards. side_effects: - >- The term becomes cancelled without supplying coverage; dependent granted terms and derived data are updated. who: Membership staff or purchase operations provenance: observed source: 'services-membership:modules/memberships/services/operations/staff-operations.ts:terminateTerm' invalid: - from: cancelled to: committed why: The examined writers reject recommitting a cancelled term; later membership purchases create a new term. - from: terminated to: committed why: The examined operations do not reopen a terminated term; continuation uses a new term. - from: committed to: pending why: No examined writer moves a committed term back to pending. concurrency: >- Memberships owns term changes and takes the holding row lock before mutation and cache recomputation. The engine interprets the supplied states rather than validating a universal transition graph. Reaching a term's last day affects computed standing without changing its stored state. invariants: - INV-DOM-MBR-STR-005-03 - INV-DOM-MBR-STR-005-05 evidence: - >- services-membership at 5994c270: modules/terms/services/status.ts (TERM_STATES, EFFECTIVE_TERM_STATES); modules/terms/db/term-columns.ts; modules/memberships/services/operations/staff-operations.ts; modules/commerce-participant/services/fulfilment/fulfill.ts and cancellation/cancellation.ts (the callers that move states). --- # Term effective state ## The Lifecycle ```mermaid stateDiagram-v2 [*] --> pending: prepared purchase [*] --> committed: staff term or fulfilled purchase pending --> committed: authorization fulfilled pending --> cancelled: authorization cancelled committed --> committed: correction with superseded event committed --> terminated: close started term committed --> cancelled: close unstarted term state superseded ``` ## Transitions Explained The engine defines coverage meaning; Memberships and its purchase participant implement state changes. Correction changes the existing committed term and emits a superseded event without selecting superseded state. The latter remains part of the recognized stored vocabulary, with no observed writer entering it in this examination. ## What Cannot Happen The invalid rows describe refusals in the examined writers, rather than a database transition trigger. Pending and cancelled terms provide no effective coverage. Passing an end date changes calculated status without changing the stored term state. ## Concurrency and Timing Term writes and cache recomputation share the holding lock with sweep work. Staff operations enforce their own version and reason checks; Commerce follows its claim, authorization and cancellation contracts.