Rhythm 2.0 Specifications

Appearance

CAP-MBR-MEM-006Derive package grants and organizational child memberships

Markdown

CAP-MBR-MEM-006

Derive package grants and organizational child memberships

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-012
Depends on
CAP-MBR-MEM-001
Related
CAP-MBR-MEM-003, CAP-MBR-MEM-004, CAP-MBR-MEM-012
Proved by
ATS-MBR-MEM-006

KindCapabilityProduct areaMembershipModuleMemberships, Applications and Membership BillingRevision1

Read atservices-membership 5994c270react-console baf6dae3

Derive package grants and organizational child memberships ​

Purpose ​

Staff use bundled packages and corporate memberships to provide coverage beyond the original period’s immediate purpose. The distinction matters: a package grant creates a term on a principal membership, while organizational flow-down and assigned seats create dependent memberships.

How It Works ​

The membership write invokes the package’s grant plan and reports planned and skipped grants. Staff can inspect the additional program periods after the write. An organizational membership follows a different derivation, based on CRM relationships and contacts selected for assigned seats. Current and future parental periods are reconsidered against current eligibility; ended periods preserve the people they previously covered. Corrections and closures cause existing child mirrors to be reconsidered. CRM deliveries provide another trigger for the same derivation. Staff should inspect the seat limit alongside people already covered by flow-down, because the selection can consume a slot for someone already covered. The former-parent reparenting finding and CRM subscription dependency remain unresolved.

Relationships ​

  • Staff creation and term extension trigger grant application and organizational derivation.
  • CRM Entities supplies the organizational hierarchy and effective contact roles.
  • Application decisions supply the contacts used for assigned seats.

The Formal Contract

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

Outcomes
Package grants create additional periods for the same owner.Eligible organizational contacts receive dependent membership periods.Delivered CRM changes trigger recalculation of affected organizational coverage.
Surfaces
apijob
Constraints
Cascading flow-down searches at most ten descendant levels.
Intent sources
services-membership:README.md#2026-10-18 — Final acceptanceservices-membership:modules/memberships/services/grants/apply-grants.ts (the decision of 2026-10-17)

Controls

43 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-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-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
membership.terms.createapitenant

Business Rules

12 rules, 10 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
Committing a package term applies its non-self grants in the same transaction, creating a principal membership in each target program when needed and linking the granted term to its source.
origin: the decision of 2026-10-17 on package grants (services-membership:modules/memberships/services/grants/apply-grants.ts header)
no proof recorded yet
policyserviceobserved
services-membership:modules/memberships/services/grants/apply-grants.ts:applyPackageGrants
02must prove
Confirmed
A same-as-primary grant uses the source dates; an own-rule grant computes its period without starting before the source, and package renewal runs the grant calculation again.
no proof recorded yet
calculationservicetest
services-membership:modules/memberships/tests/unit/grant-plan.spec.ts#plans a granted term by the grant’s own rule, never starting before the primary term
03must prove
Confirmed
A planned grant overlapping any effective term already held in the target membership is skipped and identifies the overlapping term.
no proof recorded yet
policyservicetest
services-membership:modules/memberships/tests/unit/grant-plan.spec.ts#skips a grant the member already holds for those dates, naming the term
04must prove
Confirmed
Organizational flow-down selects contacts with currently effective configured roles and affiliations, then mirrors parent terms using the configured flow-down type or the parent type when none is specified.
no proof recorded yet
policyserviceobserved
services-membership:modules/memberships/services/flowdown/organization-children.ts:syncOrganizationChildren
05must prove
Confirmed
When cascading is enabled, flow-down considers qualifying contacts in descendant organizations matching the configured types, through depth ten.
no proof recorded yet
calculationservicetest
services-membership:modules/memberships/tests/integration/services/organization-children.integration.spec.ts#cascades to the contacts of child organizations down to depth 10 and no further
06must prove
Confirmed
Assigned-seat derivation takes the first contacts from decided applications up to the package limit before excluding contacts already covered by flow-down.
no proof recorded yet
policyserviceobserved
services-membership:modules/memberships/services/flowdown/organization-children.ts:wantedPeople
07must prove
Confirmed
Recalculating an organizational parent updates dependent mirrors to follow corrected dates and term closure.
no proof recorded yet
invariantserviceobserved
services-membership:modules/memberships/services/flowdown/organization-children.ts:syncOrganizationChildren
08must prove
Confirmed
On loss of eligibility, a started child term ends on the handling day, limited by its existing end, while a future child term is cancelled.
no proof recorded yet
lifecycleserviceobserved
services-membership:modules/memberships/services/flowdown/organization-children.ts:syncOrganizationChildren
09must prove
Confirmed
The CRM change handler recalculates affected organizational memberships from current CRM rows, including the current ancestor chain, so duplicate deliveries do not rely on event ordering.
no proof recorded yet
policyserviceobserved
services-membership:modules/memberships/services/flowdown/crm-change-events.ts:handleCrmChangeEvents
10must prove
Confirmed
The product should recalculate the former organizational parent after a CRM reparenting so people lose coverage derived from the old hierarchy.
no proof recorded yet
policyserviceunknown
FND-MBR-MEM-019
11
Confirmed
Organizational children receive program numbers, are excluded from billing, and accept term changes only through their principal parent.
policyserviceobserved
services-membership:modules/memberships/services/flowdown/organization-children.ts:syncOrganizationChildren; modules/billing/services/planning/run-plan.ts:exclusionOf; modules/memberships/services/operations/staff-operations.ts:refuseChild
12
Confirmed
An organization-owned membership must have principal origin.
invariantdatabaseobserved
services-membership:modules/memberships/db/memberships.table.ts:memberships_organization_principal_check

Scenarios

IdGivenWhenThenProvenance
01Acme has a corporate type configured for employee flow-down and cascading.Staff create its corporate membership with a term.Eligible contacts receive mirrored Employee terms through the permitted organizational depths.test
services-membership:tests/acceptance/affiliations/MBR-ACC-0274.acceptance.ts#MBR-ACC-0274: Acme's corporate membership reaches its CEO, its engineers and the people of its subsidiaries ten levels down, each with a mirrored employee term, and follows the parent through correction, termination, suspension and restore
02A member’s bundle includes a grant into a section program.The bundle receives a renewed term.The section receives its next grant unless existing effective coverage overlaps the planned period.test
services-membership:tests/acceptance/memberships/MBR-ACC-0181.acceptance.ts#MBR-ACC-0181: A bundle package grants a section membership with the national one, renews it with each renewal, skips a grant the member already holds, ignores a grant into its own program, and the granted membership stands on its own

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