Skip to content

CAP-MBR-STR-005Find units and inspect current or historical structure

Markdown

CAP-MBR-STR-005

Find units and inspect current or historical structure

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

KindCapabilityProduct areaMembershipModuleOrganizational Structure, Membership Configuration and TermsRevision1

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
Current structure is available to staff and connected applications.Dated reporting can distinguish effective placement from when it was recorded.
Surfaces
api

Controls

29 controls apply, from the corpus control catalogue.

TC-AVL-002 TC-AVL-003 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-007 TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-PI-001 TC-SEC-001 TC-SEC-004 TC-TEN-001 TC-TEN-002 TC-TEN-003

Permissions

KeyChecked atScope
membership.structure.readapitenant
membership.application.accessapitenant

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Proposed
Current descendants and ancestors include the requested unit at distance zero and sort by distance followed by unit code.
no proof recorded yet
calculationservice, databasetest
services-membership:modules/structure/tests/integration/services/persistence/organizational-units.integration.spec.ts#organizational units in the database › the closure › answers the descendants of a unit from the closure, nearest first
02must prove
Proposed
Historical descendants use parent periods effective on the requested day and versions visible at the requested knowledge time, defaulting to the present knowledge time.
no proof recorded yet
calculationservicetest
services-membership:modules/structure/tests/integration/services/persistence/organizational-units.integration.spec.ts#organizational units in the database › the parent history and the as-of tree › answers the descendants as of 2027-06-30 equal to the tree recorded that day
03must prove
Proposed
Historical structure returns current unit codes and names and excludes units absent from that date’s tree.
no proof recorded yet
calculationserviceobserved
04must prove
Proposed
Tree pages sort by depth followed by code and include parent and depth for either the whole structure or a selected branch.
no proof recorded yet
calculationservicetest
services-membership:modules/structure/tests/integration/services/persistence/organizational-units.integration.spec.ts#organizational units in the database › the closure › pages the tree breadth first with each unit’s parent
05must prove
Proposed
Flat lists sort by code with kind, parent and status filters; searches require a nonblank fragment, match code or name without case sensitivity and treat wildcard characters literally.
no proof recorded yet
calculationapi, serviceobserved
06must prove
Proposed
Paged unit and kind lists default to 50 rows, reject limits outside 1–500 and validate cursor key shape; ancestor, descendant, history, organization-link and dues-product reads are unpaged.
no proof recorded yet
validationapi, serviceobserved
07must prove
Proposed
Parent history lists retained periods from oldest to newest with their dates, reason and actor.
no proof recorded yet
calculationserviceobserved
08
Proposed
Unknown-unit collection reads and unknown kind, parent or root filters return empty collections rather than a not-found response.
policyserviceobserved
09must prove
Proposed
Published descendant and ancestor functions support connected applications within their transactions and return no rows outside the caller’s workspace.
no proof recorded yet
invariantdatabasetest
services-membership:modules/structure/tests/integration/services/persistence/organizational-units.integration.spec.ts#organizational units in the database › the published functions › answers nothing of a tenant other than the reader’s own
10
Proposed
Registration manifests describe unit and kind query datasets under structure read authority, including custom values and unit ancestry.
policyservicetest
services-membership:tests/unit/metadata-registration.spec.ts#Membership’s registration manifests › reads the units’ dataset under membership.structure.read, with custom field values and the ancestors over the closure
11must prove
Proposed
Workspace isolation prevents readers from obtaining another workspace’s unit records or list rows.
no proof recorded yet
permissiondatabasetest
services-membership:modules/structure/tests/integration/services/persistence/organizational-units.integration.spec.ts#organizational units in the database › row-level security › reads nothing of another tenant’s unit by id

Scenarios

IdGivenWhenThenProvenance
01Atlanta’s current region differs from its region the previous December.A reader requests the former region’s December structure.The dated result includes Atlanta in that earlier branch.test
services-membership:tests/e2e/s09-restructuring.e2e.spec.ts#scenario 9: organizational restructuring › still holds Atlanta among the Eastern Region’s descendants as of the period end

Edge Cases

IdGivenWhenThenProvenance
02A placement correction is entered after the original report.A reader reproduces the report using its original knowledge time.The result excludes knowledge introduced by the later correction.test
services-membership:modules/structure/tests/integration/services/persistence/organizational-units.integration.spec.ts#organizational units in the database › the parent history and the as-of tree › answers nothing for a known_at before the moves were recorded, beyond the tree as it was then known

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.