--- id: SVC-MBR-MEM-memberships title: Memberships Service Module product_area: membership module: memberships repository: services-membership source_module: modules/memberships revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-MBR-MEM-001 - DOM-MBR-MEM-002 - DOM-MBR-MEM-003 does_not_own: - >- Structure owns units, programs, offers, status reasons and the period engine used here. - >- CRM retains ownership of people, organizations and the relationships used for child coverage. - >- Commerce owns purchasing and payment; this service delegates its participant work to the corresponding module. - >- Platform supplies authorization, attention, communications, queries and durable execution. operations: - operation_id: getMembershipsHealth intent: Return deployment and build health without customer records. access: public permission: 'none: the shared module health route' realises: [] published_to_submissions: 'not published: deployment health exposes no submission capture' - operation_id: listMemberships intent: >- Find visible holdings using owner, program, standing and dated unit filters before paging. access: portal permission: membership.members.read realises: - CAP-MBR-MEM-005 - CAP-MBR-MEM-007 - CAP-MBR-MEM-015 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: createMembership intent: >- Establish a principal holding and first committed period through reasoned staff entry. access: console permission: membership.memberships.create realises: - CAP-MBR-MEM-001 - CAP-MBR-MEM-006 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: getMembership intent: >- Read a visible holding with its periods, computed standing, continuity and lifecycle entries, marking affiliation scope. access: portal permission: membership.members.read realises: - CAP-MBR-MEM-005 - CAP-MBR-MEM-015 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: getMembershipAsOf intent: Reconstruct the visible holding for a business date and recording instant. access: portal permission: membership.members.read realises: - CAP-MBR-MEM-018 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: createTerm intent: >- Add reasoned staff coverage to an existing principal holding without creating an order. access: console permission: membership.terms.create realises: - CAP-MBR-MEM-002 - CAP-MBR-MEM-006 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: suspendMembership intent: >- Withhold a principal holding’s rights and propagate suspension to its organizational children. access: console permission: membership.memberships.suspend realises: - CAP-MBR-MEM-004 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: restoreMembership intent: Clear staff suspension and recompute standing from the remaining periods. access: console permission: membership.memberships.suspend realises: - CAP-MBR-MEM-004 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: correctTerm intent: Revise a committed period while retaining the earlier recorded values. access: console permission: membership.terms.correct realises: - CAP-MBR-MEM-003 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: terminateTerm intent: >- Close coverage at an effective date, choosing termination or cancellation according to its start. access: console permission: membership.terms.terminate realises: - CAP-MBR-MEM-003 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: addAffiliation intent: >- Create a dated unit connection for effective coverage after scope, unit-rule and dues checks. access: portal permission: membership.affiliations.manage realises: - CAP-MBR-MEM-007 - CAP-MBR-MEM-015 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: endAffiliation intent: >- Shorten a unit connection or withdraw its live row by an explicit pre-start end. access: portal permission: membership.affiliations.manage realises: - CAP-MBR-MEM-007 - CAP-MBR-MEM-015 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: setPrimaryAffiliation intent: >- Select a primary connection and clear conflicting same-type primary flags where required. access: portal permission: membership.affiliations.manage realises: - CAP-MBR-MEM-007 - CAP-MBR-MEM-015 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: transferAffiliation intent: >- Move a dated unit connection into a successor while preserving predecessor lineage. access: portal permission: membership.affiliations.manage realises: - CAP-MBR-MEM-008 - CAP-MBR-MEM-015 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: runStatusSweep intent: >- Recompute today’s workspace standing caches and record first expiry or lapse detections. access: console permission: membership.operations.run realises: - CAP-MBR-MEM-005 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: updateMemberContact intent: >- Delegate permitted person-contact field changes to CRM with the caller’s acting identity. access: portal permission: membership.member-contact.update realises: - CAP-MBR-MEM-016 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: getMembershipFinancialSummary intent: Read membership financial lines visible through the caller’s unit reach. access: portal permission: membership.members.read realises: - CAP-MBR-MEM-016 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: renewMembership intent: >- Prepare and request a Commerce renewal for a member the officer can reach, including grace. access: portal permission: membership.terms.renew realises: - CAP-MBR-MEM-016 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: enrollMember intent: >- Prepare and request enrolment for a recipient whose selected units the caller may administer. access: portal permission: membership.memberships.enroll realises: - CAP-MBR-MEM-016 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: exportRoster intent: >- Capture an authorized filtered membership set and submit its asynchronous roster job. access: portal permission: membership.rosters.export realises: - CAP-MBR-MEM-017 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: getRosterExport intent: >- Read export progress and row pages as the requester or a workspace-wide export reader. access: portal permission: membership.rosters.export realises: - CAP-MBR-MEM-017 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: getMyMemberships intent: >- Read the holdings of the person linked to the portal account without staff record access. access: portal permission: membership.self.read realises: - CAP-MBR-MEM-017 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: getScopeSettings intent: Read grace visibility and role-based contact field allowances. access: console permission: membership.configuration.read realises: - CAP-MBR-MEM-015 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: replaceScopeSettings intent: Replace the complete scope-settings document using its read version. access: console permission: membership.configuration.manage realises: - CAP-MBR-MEM-015 published_to_submissions: >- not published: membership administration or reads; application decisions arrive through the separate Submissions handler - operation_id: handleCrmChangeEvents intent: >- Reconcile organizational child coverage affected by delivered current CRM changes. access: internal permission: 'none: invoked by CRM''s change-event remote handler over IAM' realises: - CAP-MBR-MEM-006 published_to_submissions: >- not published: an internal service, partner or query contract; no intake route is registered - operation_id: mergedUnitAffiliations intent: >- Plan and apply membership connection changes within Structure’s unit merge. access: internal permission: >- none: called in process by the structure module's merge, whose caller holds membership.structure.manage realises: - CAP-MBR-MEM-008 published_to_submissions: >- not published: an internal service, partner or query contract; no intake route is registered - operation_id: membershipDataOperations intent: Import or upsert holdings and periods through the data engine. access: internal permission: 'none: run by Platform''s data job engine under the job''s own authority' realises: - CAP-MBR-MEM-001 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: CRM contact and organization change events direction: consumed when: CRM delivers a registered owner or relationship change batch. payload_summary: Changed owner references used to recalculate against current CRM tables. jobs: - name: nightly status sweep kind: schedule when: >- Local-midnight occurrences are claimed by the minute dispatcher and processed in the workspace context. standard: The shared schedule contract handles due work and repeated failure pause. - name: expiring-memberships attention sweep kind: schedule when: 'The daily 06:00 UTC pass checks expiry attention across workspaces.' standard: >- Platform attention-provider publication is controlled by the environment switch. - name: roster export job kind: durable job when: >- An accepted export submits captured holding identifiers for asynchronous row generation. standard: The shared durable-job engine owns execution and job evidence. - name: idempotency ledger purge kind: schedule when: >- The dispatcher checks the daily purge window during the first five minutes after 03:00 UTC. standard: The shared idempotency library provides retention purge. integrations: - system: CRM direction: inbound and outbound contract: >- Read owner and relationship data from CRM tables; delegated contact updates currently use a refusing adapter. - system: Commerce direction: outbound contract: >- Delegated officer order placement and financial-line reads currently use refusing Commerce adapters. - system: Platform attention direction: outbound contract: >- Publish and resolve expiry attention only when enabled by environment configuration. consistency: - rule: >- Term creation commits its lifecycle, unit connections, eligible grants and children, events, enabled resolution and cache refresh together under holding locks. kind: transactional compensation: Rollback reverses local writes; sequence allocations need not be restored. - rule: >- Cached standing converges through the nightly sweep, while rights are computed from dated facts. kind: eventual compensation: A catch-up pass refreshes all holdings after missed sweep history. - rule: >- Organizational children are recalculated from current CRM facts after connected delivery, with known old-parent gaps. kind: eventual compensation: 'Without the CRM subscription, automatic convergence does not occur.' - rule: >- Export inclusion captures request-time reach, while row values are generated asynchronously. kind: eventual compensation: No recall removes a previously captured export after access withdrawal. evidence: - >- services-membership at 5994c270: modules/memberships/aws/api/memberships.routes.ts; modules/history/aws/api/history.routes.ts (served by this module's function, contracted under history); aws/membership.service.ts; services/**; aws/lambda/*.ts; aws/membership.idempotency.ts; aws/membership.attention.ts. controls: [TC-AVL-002, TC-AVL-003, TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, 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-004, TC-DAT-005, TC-DAT-007, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, 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, TC-TEN-004] --- # Memberships Service Module ## What This Service Is For Membership staff maintain holdings, periods and chapter connections here. The same service supports unit-scoped officers, portal self-reads, imports and cached-standing refresh. ## Boundary Holdings and their dependent periods and affiliations are owned here. Structure supplies program, offer and period rules; CRM supplies owners and relationships. Contact updates, ordering, attention and job execution remain delegated responsibilities. ## Operations in Words Staff establish and correct coverage and manage suspension. Scoped reads and affiliation operations evaluate unit reach before exposing records. Officers request renewals, enrolments, contact changes, financial reads and roster exports; portal members use their linked-person read. Administrators maintain scope settings and can trigger the sweep. ## Events and Jobs Term, affiliation and suspension writes state business events in their transactions. CRM delivery can trigger organizational recalculation. Schedules refresh standing and expiry attention, durable work generates exports, and dispatch also runs daily ledger purge work. ## Consistency Guarantees Local term effects commit together. Computed standing supplies rights independently of cache freshness. Organizational recalculation uses current CRM facts but requires subscription delivery and has known old-parent gaps. Export inclusion is captured at request time while values are produced later.