Rhythm 2.0 Specifications

Appearance

CAP-MBR-MEM-001Record a membership and its first term without a purchase

Markdown

CAP-MBR-MEM-001

Record a membership and its first term without a purchase

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationPartially observed

Planning

Feature
FEAT-MBR-MEM-01
Key concepts
CON-MBR-MEM-001, CON-MBR-MEM-002
Actors
ACT-MBR-007, ACT-MBR-003
Journeys
JNY-MBR-MEM-001
Related
CAP-MBR-MEM-002, CAP-MBR-MEM-006, CAP-MBR-MEM-007
Proved by
ATS-MBR-MEM-001

KindCapabilityProduct areaMembershipModuleMemberships, Applications and Membership BillingRevision1

Read atservices-membership 5994c270react-console baf6dae3

Record a membership and its first term without a purchase ​

Purpose ​

This capability gives staff a direct way to establish membership for complimentary, historical and migrated records. The owner receives a continuing membership with an initial period even when no order is involved.

How It Works ​

A coordinator identifies the owner and selects the program, membership type and any package. They explain why the membership is being recorded and either provide the period or use the package’s date calculation. Creation checks the selected configuration and the owner’s existing holdings before saving. A duplicate principal holding is refused with guidance to add a period to the existing membership. An overlap with an exclusive program is also refused. Successful creation allocates the number, saves the initial period and records the enrolment reason together. Unit affiliations and package grants participate through their own capabilities. Migration producers instead load memberships and periods in dependency order through the data job engine. Import insertion records its own event, while an upsert changes existing values without adding another imported event. Imports suppress automatic grants and organizational children because the producer loads those records explicitly. The product should close the import validation and custom-field entry gaps identified in the findings. Staff have no separate editor for the owner, original join date or member choices after creation; import upserts can replace them.

Relationships ​

  • Membership configuration and the term engine supply eligible programs, types, packages and period calculations.
  • Derived membership handles grants and organizational children produced by a committed period.
  • Chapter and section affiliation places an affiliation-bound membership in its units.

The Formal Contract

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

Outcomes
Comped and migrated owners have a membership record equivalent to one established through purchase.Principal holdings remain unique within a program and its identity unit, with overlapping exclusive programs refused.New staff memberships receive their number and first period together.
Surfaces
consoleapijob
Preconditions
The selected program, type and any selected package are active and compatible.
Postconditions
Creation saves the initial committed term, enrolment event and refreshed membership status.
Constraints
Term notes allow up to 2,000 characters, and a term request permits up to 20 unit affiliations.
Intent sources
services-membership:README.md#2026-10-18 — Final acceptanceservices-membership:docs/migrations/membership-core/README.md#The operations and their keysservices-membership:AGENTS.md#Custom Fields Are Opt-In Per Entity: R2-ARCH-001 (Andrew, 2026-10-19)

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

Permissions

KeyChecked atScope
membership.memberships.createapitenant

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
Staff creation requires a program, owner category, matching owner reference, a reason between 1 and 500 characters and an initial term, and refuses an inactive program or an owner category that the program excludes.
✓ A coordinator records a complimentary Regular term for a person in the national program and explains the board’s decision.✗ An organization cannot join a program restricted to individual owners; creation returns a validation refusal.
no proof recorded yet
validationapi, serviceobserved
services-membership:modules/memberships/services/operations/staff-operations.ts:createMembership
02must prove
Confirmed
An owner cannot receive another principal membership in the same program and identity unit; the refusal directs staff to extend the existing membership with a term.
no proof recorded yet
invariantservice, databaseobserved
services-membership:modules/memberships/services/operations/staff-operations.ts:createMembership
03must prove
Confirmed
Identity-bound programs require a unit of their configured identity type, while programs without that binding refuse an identity unit.
origin: D-02 (services-membership:README.md, architecture decisions approved 2026-10-17)
no proof recorded yet
validationservice, databaseobserved
services-membership:modules/memberships/services/operations/staff-operations.ts:createMembership
04must prove
Confirmed
The chosen type must be active within the program, any package must be active and belong to that type, and a term without a package requires explicit starting and ending dates.
no proof recorded yet
validationserviceobserved
services-membership:modules/memberships/services/operations/staff-operations.ts:requirePackageOf
05must prove
Confirmed
Where dates are omitted, the package rule calculates the period from the supplied effective date or the workspace business date; an explicit start without an end uses that rule to calculate the end.
no proof recorded yet
calculationserviceobserved
services-membership:modules/memberships/services/operations/staff-operations.ts:datesOf
06must prove
Confirmed
The service rejects overlap with effective or pending terms and identifies the conflict, while the database exclusion independently rejects overlap between effective terms and does not cover pending terms.
no proof recorded yet
invariantservice, databasetest
services-membership:modules/memberships/tests/integration/services/term-concurrency.integration.spec.ts#is backed by the migration’s exclusion when the persistence check is bypassed
07must prove
Confirmed
An owner cannot have overlapping effective or pending periods in different programs belonging to the same exclusivity group.
no proof recorded yet
policyservicetest
services-membership:tests/acceptance/memberships/MBR-ACC-0171.acceptance.ts#step 3: POST /memberships/{tenantId}/memberships for c_kim_{run} in premium, term gold/premium_annual…
08must prove
Confirmed
Creation allocates the membership number using the workspace sequence, program sequence or owner’s CRM number selected by the program, refusing CRM numbering when the owner has no number.
origin: D-41 (services-membership:modules/memberships/services/membership-numbers.ts header)
no proof recorded yet
calculationservicetest
services-membership:tests/acceptance/memberships/MBR-ACC-0186.acceptance.ts#MBR-ACC-0186: Membership numbers come from the program's numbering scope: one sequence for the workspace, a program's own sequence, or the owner's CRM number, which refuses an owner without one and repeats across programs
09must prove
Confirmed
The enrolment event retains the creation reason, and the original join date uses the first effective term’s start unless staff supply a date that is recorded as their choice.
no proof recorded yet
lifecycleserviceobserved
services-membership:modules/memberships/services/operations/staff-operations.ts:createMembership
10must prove
Confirmed
Imports match records by identity or producer source key and load configuration before memberships before terms; inserts record an imported event, all term writes refresh status, and neither grants nor flow-down children are generated.
no proof recorded yet
policyserviceobserved
services-membership:modules/memberships/services/data-operations/membership-operations.ts:writeImportedTerm
11must prove
Confirmed
Prevalidation identifies malformed import fields before writing, and an overlapping imported term is classified as a conflict for that item.
no proof recorded yet
validationservicetest
services-membership:modules/memberships/tests/integration/data-operations/membership-data-operations.integration.spec.ts#classifies an overlapping term as that item’s conflict, term_overlap
12must prove
Confirmed
The product should validate imported owners, programs, types and packages as staff creation does and prevent an upsert from changing a term belonging to another membership.
no proof recorded yet
validationserviceunknown
FND-MBR-MEM-017
13must prove
Confirmed
The product should support staff and import entry of customer-defined membership values under the declared custom-field contract.
origin: R2-ARCH-001 (services-membership:AGENTS.md, Andrew 2026-10-19)
no proof recorded yet
policyserviceunknown
FND-MBR-MEM-016
14
Confirmed
Staff creation sets renewal, drop, directory and auto-renew choices without offering later staff edits to those choices, the join date or owner, although import upserts can replace these values.
lifecycleserviceobserved
services-membership:modules/memberships/services/data-operations/membership-operations.ts:updateImportedMembership

Scenarios

IdGivenWhenThenProvenance
01A person has no principal membership in the national program.A coordinator records a complimentary Regular period and supplies the reason.Creation returns the numbered membership, committed period, enrolment event and recalculated standing.observed
services-membership:modules/memberships/services/operations/staff-operations.ts:createMembership
02Kim belongs to National, and Premium shares National’s exclusivity group.A coordinator attempts a Premium membership covering days already held in National.The request fails and identifies the existing membership and overlapping period.test
services-membership:tests/acceptance/memberships/MBR-ACC-0171.acceptance.ts#MBR-ACC-0171: An owner never holds two tiers at once: overlapping programs of one exclusivity group are refused, adjacent and ungrouped ones allowed, pending terms count, and two simultaneous adds probe the lock

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.

Rhythm Software