Skip to content

CAP-MBR-MEM-008Preserve member connections through transfers and unit merges

Markdown

CAP-MBR-MEM-008

Preserve member connections through transfers and unit merges

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationPartially observed

KindCapabilityProduct areaMembershipModuleMemberships, Applications and Membership BillingRevision1

Read atservices-membership 5994c270react-console baf6dae3

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Transfers retain the connection between the ending row and its successor.Merges account for current, future, duplicate and closed affiliations.Dated roster and officer views follow the resulting relationships.
Surfaces
consoleapi
Intent sources
services-membership:README.md#2026-10-18 — Final acceptance (decision 1: "Build the move now")services-membership:docs/migrations/unit-merge/README.md

Controls

46 controls apply, from the corpus control catalogue.

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-004 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-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

Permissions

KeyChecked atScope
membership.affiliations.manageapirecord
membership.structure.manageapitenant

Business Rules

12 rules, 11 to be proved before approval. A rule's product intent is derived from its origin: 12 confirmed by a product decision, the rest inheriting this capability's confirmed.

IdRuleKindEnforced atProvenance
01must prove
Confirmed
A transfer ends the original affiliation on the preceding day and creates a successor on the effective date with its primary flag, end and lineage, recording a transfer event.
no proof recorded yet
lifecycleserviceobserved
02must prove
Confirmed
A direct transfer into a unit with applicable active dues is refused and identifies the Commerce component-change amendment required to carry the charge.
no proof recorded yet
policyservicetest
services-membership:tests/e2e/s06-midterm-transfer.e2e.spec.ts#refuses the console’s transfer 409 requires_amendment, naming the component_change amendment
03must prove
Confirmed
Dated rosters reflect the old and new units on their respective dates and retain membership in any shared ancestor reached by another affiliation.
no proof recorded yet
calculationservicetest
services-membership:tests/e2e/s06-midterm-transfer.e2e.spec.ts#takes Jo out of Atlanta’s roster from 2027-01-01 and into the Pacific Zone’s, keeping them in the Southeast Zone’s through Savannah
04must prove
Confirmed
A merge transfers begun affiliations, repoints future affiliations, ends or withdraws overlaps with the survivor, and leaves closed or cancelled-period affiliations unchanged.
origin: Andrew 2026-10-18, guided build acceptance decision 1 (services-membership:docs/migrations/unit-merge/README.md)
no proof recorded yet
lifecycleserviceobserved
services-membership:modules/memberships/services/affiliations/unit-merge.ts:decideMergedTerm, writeDecision
05must prove
Confirmed
A merge plan refuses affiliations requiring a different survivor type or introducing a unit-rule problem absent before the merge, identifying affected memberships before writes occur.
origin: Andrew 2026-10-18, guided build acceptance decision 1 (services-membership:docs/migrations/unit-merge/README.md)
no proof recorded yet
validationserviceobserved
06must prove
Confirmed
Identity-bound memberships move to the survivor unless a principal membership’s owner already holds that program in the surviving identity unit, which produces a merge refusal.
origin: Andrew 2026-10-18, guided build acceptance decision 1 (services-membership:docs/migrations/unit-merge/README.md)
no proof recorded yet
lifecycleserviceobserved
07must prove
Confirmed
Any affiliation naming a unit, including a closed historical row, prevents deletion of that unit.
no proof recorded yet
invariantservice, databasetest
services-membership:tests/e2e/s13-unit-merge.e2e.spec.ts#refuses to delete Savannah while affiliations name it (unit_has_affiliations)
08must prove
Confirmed
After a merge, the survivor’s officers can read moved members through their new in-scope affiliations.
no proof recorded yet
policyservicetest
services-membership:tests/e2e/s13-unit-merge.e2e.spec.ts#shows Alex Pat now, with Pat’s Atlanta affiliation in scope
09must prove
Confirmed
The product should publish transfer-equivalent business events for every merge ending, withdrawal and repointing.
no proof recorded yet
policyserviceunknown
10must prove
Confirmed
The product should retain a current primary designation when a primary affiliation merges into an existing nonprimary survivor affiliation.
no proof recorded yet
invariantserviceunknown
11
Confirmed
Merging affiliations carries no dues line or payment and leaves the merged unit’s dues products for a separate finance decision.
policyservicedocumented
12must prove
Confirmed
Reparenting a chapter changes no affiliation row; current rosters use the new tree while past-date ancestry uses the historical tree.
no proof recorded yet
policyserviceobserved
services-membership:modules/memberships/services/reads/membership-views.ts:membershipFiltersOf; tests/e2e/s09-restructuring.e2e.spec.ts#rewrites no affiliation: Jo’s row is the same row, version and unit

Scenarios

IdGivenWhenThenProvenance
01Pat belongs only to Savannah, while Jo belongs to both Savannah and Atlanta.An administrator merges Savannah into Atlanta today.Pat continues in Atlanta, Jo’s duplicate Savannah tie ends, and today’s Savannah roster has no members.observed
services-membership:modules/memberships/services/affiliations/unit-merge.ts:decideMergedTerm, writeDecision
02Open chapter affiliations would have to move into a survivor of another unit type.Staff request the incompatible merge.The refusal leaves the units and affiliation rows unchanged and identifies the affected memberships.test

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.