--- id: CON-MBR-MEM-006 name: Membership History feature: FEAT-MBR-MEM-07 product_area: membership module: memberships revision: 1 status: draft product_intent: confirmed implementation_evidence: partially-observed source_sha: services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- Membership history brings together recorded versions, attributed revisions, past-date reconstruction, monthly reporting copies and retained business-event publication records. owned_by: MOD-MBR-MEM synonyms: - audit trail - membership reporting history not_to_be_confused_with: - The membership business log records effective lifecycle actions. - Platform security auditing concerns access and account activity. facets: - name: Versions meaning: >- Recorded versions retain previous membership, term, affiliation and custom-field values with their recording intervals. used_for: Reconstructing what Membership knew before a later correction. - name: Change timeline meaning: Membership and term revision lists attribute configured changes and group their details into sections. used_for: Inspecting who changed the record and the recorded source. - name: As-of reconstruction meaning: >- A dated reconstruction combines membership versions, historical units and available committee history with a currently captured contact. used_for: Investigating membership facts for a past business day. - name: Monthly snapshot meaning: >- Validated period-end copies retain member details, affiliations, dimensions and grouped counts in published run versions. used_for: Maintaining month-by-month reporting independent of ordinary live corrections. - name: Snapshot characteristics meaning: >- Selected contact and custom-field characteristics use captured or reconstructed values according to their source. used_for: Grouping historical reports while making the value’s basis explicit. - name: Query datasets meaning: Live and published reporting datasets each have their own query permission. used_for: Supporting authorized membership analysis. - name: Business events meaning: >- The retained catalogue records nine kinds of selected change announcements for delivery to other applications. used_for: Providing dependent applications with membership outcomes. relationships: - to: CON-MBR-MEM-001 statement: >- Configured membership revisions exclude cache-only bookkeeping and support historical inspection alongside version-based reconstruction. provenance: observed source: 'services-membership:modules/history/db/change-event-streams.ts:MEMBERSHIP_STREAM' - to: CON-MBR-MEM-002 statement: 'The term has a separate revision timeline, and its recorded versions supply earlier period values.' provenance: observed source: 'services-membership:modules/history/history/term-history.config.ts' - to: CON-MBR-MEM-003 statement: Snapshot affiliations retain the units and ancestors effective at the reporting period’s end. provenance: test source: >- services-membership:modules/snapshots/tests/integration/membership-snapshot.integration.spec.ts#files each affiliation with its unit and every ancestor the unit had at the period end, nearest first acted_on_by: - CAP-MBR-MEM-018 - CAP-MBR-MEM-019 - CAP-MBR-MEM-020 - CAP-MBR-MEM-003 visible_to: - ACT-MBR-007 - ACT-MBR-008 - ACT-MBR-006 evidence: - >- services-membership at 5994c270e8a37a30f848e99ba5b5ee6b87c08893: modules/history (streams, record revisions, configurations, reconstruction); modules/snapshots (type, generation, checks, dimension settings, datasets); modules/events (catalogue, publisher, handlers); docs/migrations/history/README.md; docs/migrations/events/README.md. supersedes: - 'inventory:CAP-MBR-HIS-003' --- # Membership History ## What It Is Membership history is the information retained to explain a holding’s earlier values and changes. It supports distinct questions: who corrected a term, what coverage existed on a past day, what the system knew before a later correction and which membership counts were published for a completed month. These questions use related records without treating them as one universal audit trail. Recorded versions preserve earlier values and their recording intervals. Attributed revisions organize configured changes into a timeline for staff inspection. Past-date reconstruction reads versions for a selected business day and recording instant. Monthly snapshots produce validated reporting copies, while business-event publication retains selected announcements intended for other applications. ## What It Is Not The membership’s lifecycle log describes actions such as enrolment, renewal or detected lapse and their effective days. Revision history describes configured changes to record content. Platform’s security audit describes access rather than those business changes. A frozen monthly copy also differs from a live query, whose answers can change as current records and configuration change. ## How It Is Used Staff inspect a membership’s revisions and narrow the timeline by operation or actor. They open a revision’s sections to understand which retained values changed. A term has its own timeline as well. History access requires its additional permission; ordinary officer visibility does not automatically expose past values. Auditors request membership for a past day with a chosen knowledge instant. The reconstruction can include historical units and available committee information, while the contact is explicitly captured from its current record. Analysts use live datasets for current questions and published monthly copies for period comparisons. Snapshot settings determine the additional characteristics retained with members. Blank captured values, migration recording dates and instant precision currently limit some answers and publication paths. ## Its Facets **Versions.** Recording intervals distinguish an earlier fact from a later correction. A backdated change becomes visible to reconstruction when the selected knowledge instant includes its recording. **Change timeline.** Revisions retain the configured business changes and attribution. Cache-only status bookkeeping and a change undone within the same transaction do not create equivalent revision entries. Some business details remain absent from the rendered history. **As-of reconstruction.** The result combines effective dates with recording time. Committee seats depend on available external history, while the current contact is marked as captured rather than represented as a historical contact value. **Monthly snapshot.** Generation builds a versioned month-end copy and validates it before publication. Failed validation leaves that month unpublished. A deliberate rerun can use later knowledge while retaining earlier run records. **Snapshot characteristics.** Contact characteristics are captured from the live contact on first capture and carried forward during reruns. Membership custom-field characteristics reconstruct recorded values instead. The distinction matters when a person’s current information differs from the reporting period. **Query datasets.** Memberships, periods, lifecycle events and affiliations support live analysis. Published snapshot datasets expose members, affiliations, characteristics and counts under separate query permissions. **Business events.** Selected operations record announcements with their business write for at-least-once delivery. Imports and some automatic changes do not publish equivalent announcements, so event delivery is not a complete revision ledger. ## How It Relates Memberships and terms supply the business records being inspected. Affiliations and the structure’s dated hierarchy place members in units for past-date and period-end questions. Platform supplies the query and snapshot infrastructure, while Committees provides available appointment history and consumes term-termination announcements. ## What It Could Become The product should decide whether officers gain scoped history access and how membership events fit the integration catalogue and retention policy. It should also settle migrated-month reporting, retain full recording precision and make blank contact characteristics safe for publication. Larger associations need generation that can progress in bounded portions, and recorded configuration revisions still need an appropriate read workflow.