--- id: SVC-MBR-MEM-events title: Membership Business Events Service Module product_area: membership module: memberships repository: services-membership source_module: modules/events revision: 1 status: draft design_intent: proposed implementation_evidence: partially-observed inference: [] source_sha: services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: [] does_not_own: - >- History owns the broad evidence concept; this service implements its publication facet. - Committees owns appointment changes resulting from delivered termination. - >- Platform owns the integration catalogue, where these event keys remain unregistered. operations: - operation_id: publishBusinessEvent intent: >- Validate and insert a partner event inside the transaction of its business change. access: internal permission: 'none: an in-process service call of the macroservice''s modules' realises: - CAP-MBR-MEM-020 published_to_submissions: >- not published: an internal service, partner or query contract; no intake route is registered - operation_id: change-events dispatcher and consumer intent: >- Claim event transport rows, queue matched handler work and process receiver outcomes. access: internal permission: 'none: scheduled and queue-driven functions' realises: - CAP-MBR-MEM-020 published_to_submissions: >- not published: an internal service, partner or query contract; no intake route is registered events: - name: membership.term.committed direction: produced when: 'A writer commits initial, renewed, granted or child coverage.' payload_summary: >- Holding identity, classification, period, purchase context and attribution. - name: membership.term.superseded direction: produced when: A supported correction or linked-period update revises coverage. payload_summary: Holding reference and earlier and revised period facts. - name: membership.term.terminated direction: produced when: A writer closes started coverage or the sweep records its first lapse. payload_summary: >- Holding reference, final rights day, first day without coverage and closure reason. - name: membership.term.cancelled direction: produced when: A writer closes coverage effective on or before its start. payload_summary: Holding reference and whether first-purchase cancellation removed it. - name: membership.affiliation.started direction: produced when: 'A new term, direct addition or transfer creates a connection.' payload_summary: 'Holding reference, selected unit and type, span and primary designation.' - name: membership.affiliation.ended direction: produced when: >- A direct end or transfer closes a connection; merge deletion and trimming are separate exceptions. payload_summary: 'Holding reference, unit and inclusive final affiliation day.' - name: membership.membership.suspended direction: produced when: A successful staff or enforcement write sets suspension. payload_summary: Holding reference and available suspension reason. - name: membership.membership.restored direction: produced when: A writer clears an eligible suspension. payload_summary: Identity and attribution for the holding whose suspension cleared. - name: membership.unit.reparented direction: produced when: Structure commits a dated change to unit ancestry. payload_summary: 'Moved unit, previous and new parent and effective business date.' jobs: - name: change-events dispatcher kind: schedule when: >- A minute schedule claims streams, queues matched receiver work and removes unmatched transport. standard: The shared change-event dispatcher owns transport claiming. - name: change-events consumer kind: queue when: >- Queue messages invoke configured handlers; the queue isolates repeatedly failing work after its receive limit. standard: The shared consumer interprets per-event results and retry. integrations: - system: Committees direction: outbound contract: >- Invoke the configured Committees receiver in bounded event batches and interpret one result per event. consistency: - rule: Published events share their source write’s transaction. kind: transactional compensation: Rollback removes both the business effect and its stated event. - rule: Transport retries can duplicate and reorder messages. kind: eventual compensation: >- Queue failures retry and eventually require operator redrive from the dead-letter queue. evidence: - >- services-membership at 5994c270: modules/events (contracts/business-events.ts, db, services, aws); aws/membership.change-events.ts; docs/migrations/events/README.md. controls: [TC-AVL-002, TC-AVL-003, 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-CRY-001, TC-CRY-002, TC-CRY-003, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-007, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-SEC-001, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003] --- # Membership Business Events Service Module ## What This Service Is For The event service preserves strict partner messages describing committed membership changes. It delivers configured receiver work through the shared change-event transport. ## Boundary Business writers state events; this service owns the publication and dispatch facet of membership history. Receivers own their reactions. The separate integration catalogue remains an unresolved ownership choice. ## Operations in Words The in-process publisher requires a transaction and validates payloads before insertion. Dispatcher and consumer functions claim transport work, identify matching handlers and report delivery outcomes. ## Events and Jobs Nine event types cover periods, unit connections, suspension and tree movement. The dispatcher runs every minute; matched work reaches the queue and persistent failures reach its dead-letter queue. Without a configured Committees receiver, transport is discarded while the published log remains. ## Consistency Guarantees Publication rolls back with its source write. Delivery can repeat and arrive out of order, so receivers require deduplication. A dispatch interval does not establish a delivery deadline or imply that every logged event has a receiver.