---
id: CAP-MBR-STR-005
title: Find units and inspect current or historical structure
feature: FEAT-MBR-STR-01
product_area: membership
module: structure
revision: 1
status: draft
product_intent: proposed
implementation_evidence: observed
supersedes:
  - react-console acceptance inventory CAP-MBR-STR-004
  - react-console acceptance inventory CAP-MBR-STR-008
  - react-console acceptance inventory CAP-MBR-STR-012
source_sha:
  services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
intent_sources: []
purpose: 'Readers obtain a consistent view of units, their ancestry and their placements on earlier dates.'
outcomes:
  - Current structure is available to staff and connected applications.
  - Dated reporting can distinguish effective placement from when it was recorded.
concepts:
  - CON-MBR-STR-001
  - CON-MBR-STR-002
actors:
  - ACT-MBR-002
  - ACT-MBR-001
  - ACT-MBR-005
surfaces:
  - api
preconditions: []
postconditions: []
permissions:
  - key: membership.structure.read
    where_checked: api
    scope: tenant
  - key: membership.application.access
    where_checked: api
    scope: tenant
rules:
  - id: BR-CAP-MBR-STR-005-01
    proved_by: [ATS-MBR-STR-005-01, TST-MBR-STR-006, TST-MBR-STR-100]
    statement: >-
      Current descendants and ancestors include the requested unit at distance zero and sort by distance
      followed by unit code.
    kind: calculation
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: test
    source: >-
      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
    origin: none
  - id: BR-CAP-MBR-STR-005-02
    proved_by: [ATS-MBR-STR-002-14, ATS-MBR-STR-005-02, TST-MBR-STR-006, TST-MBR-STR-011, TST-MBR-STR-072, TST-MBR-STR-098, TST-MBR-STR-100]
    statement: >-
      Historical descendants use parent periods effective on the requested day and versions visible at the
      requested knowledge time, defaulting to the present knowledge time.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      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
    origin: none
  - id: BR-CAP-MBR-STR-005-03
    proved_by: [ATS-MBR-STR-005-06]
    statement: >-
      Historical structure returns current unit codes and names and excludes units absent from that date’s
      tree.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-membership:modules/structure/services/persistence/organizational-units.ts:descendantsAsOf'
    origin: none
  - id: BR-CAP-MBR-STR-005-04
    proved_by: [ATS-MBR-STR-005-07, TST-MBR-STR-006]
    statement: >-
      Tree pages sort by depth followed by code and include parent and depth for either the whole structure or
      a selected branch.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      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
    origin: none
  - id: BR-CAP-MBR-STR-005-05
    proved_by: [ATS-MBR-STR-005-08]
    statement: >-
      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.
    kind: calculation
    enforced_at:
      - api
      - service
    must_prove: true
    provenance: observed
    source: >-
      services-membership:modules/structure/services/persistence/organizational-units.ts:listOrganizationalUnits
    origin: none
  - id: BR-CAP-MBR-STR-005-06
    proved_by: [ATS-MBR-STR-005-03, TST-MBR-STR-068, TST-MBR-STR-100]
    statement: >-
      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.
    kind: validation
    enforced_at:
      - api
      - service
    must_prove: true
    provenance: observed
    source: 'services-membership:modules/structure/aws/api/structure.routes.ts:structureRoutes'
    origin: none
  - id: BR-CAP-MBR-STR-005-07
    proved_by: [ATS-MBR-STR-005-09]
    statement: 'Parent history lists retained periods from oldest to newest with their dates, reason and actor.'
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-membership:modules/structure/services/persistence/organizational-units.ts:listParentHistory'
    origin: none
  - id: BR-CAP-MBR-STR-005-08
    proved_by: []
    statement: >-
      Unknown-unit collection reads and unknown kind, parent or root filters return empty collections rather
      than a not-found response.
    kind: policy
    enforced_at:
      - service
    must_prove: false
    provenance: observed
    source: 'services-membership:modules/structure/aws/api/structure.routes.ts:structureRoutes'
    origin: none
  - id: BR-CAP-MBR-STR-005-09
    proved_by: [ATS-MBR-STR-005-04, TST-MBR-STR-006, TST-MBR-STR-085]
    statement: >-
      Published descendant and ancestor functions support connected applications within their transactions and
      return no rows outside the caller’s workspace.
    kind: invariant
    enforced_at:
      - database
    must_prove: true
    provenance: test
    source: >-
      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
    origin: none
  - id: BR-CAP-MBR-STR-005-10
    proved_by: []
    statement: >-
      Registration manifests describe unit and kind query datasets under structure read authority, including
      custom values and unit ancestry.
    kind: policy
    enforced_at:
      - service
    must_prove: false
    provenance: test
    source: >-
      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
    origin: none
  - id: BR-CAP-MBR-STR-005-11
    proved_by: [ATS-MBR-STR-005-05, ATS-MBR-STR-005-10, ATS-MBR-STR-019-07, TST-MBR-STR-006, TST-MBR-STR-085]
    statement: Workspace isolation prevents readers from obtaining another workspace’s unit records or list rows.
    kind: permission
    enforced_at:
      - database
    must_prove: true
    provenance: test
    source: >-
      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
    origin: none
scenarios:
  - id: SC-CAP-MBR-STR-005-01
    given: Atlanta’s current region differs from its region the previous December.
    when: A reader requests the former region’s December structure.
    then: The dated result includes Atlanta in that earlier branch.
    provenance: test
    source: >-
      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:
  - id: SC-CAP-MBR-STR-005-02
    given: A placement correction is entered after the original report.
    when: A reader reproduces the report using its original knowledge time.
    then: The result excludes knowledge introduced by the later correction.
    provenance: test
    source: >-
      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
constraints: []
depends_on:
  - CAP-MBR-STR-002
related:
  - CAP-MBR-STR-019
journeys:
  - JNY-MBR-STR-002
open_questions: []
evidence:
  - >-
    services-membership: Examination of the tree reads of the unit persistence, paging, routes, metadata
    registration and the published functions.
  - >-
    services-membership: Examination of integration tests of the closure, as-of tree and published functions;
    structure end-to-end; metadata registration unit tests.
  - 'services-membership:modules/structure/aws/api/structure.routes.ts'
  - 'services-membership:modules/structure/services/persistence/organizational-units.ts'
  - >-
    services-membership:modules/structure/tests/integration/services/persistence/organizational-units.integration.spec.ts
  - 'services-membership:tests/e2e/structure-api.e2e.spec.ts'
  - 'services-membership:tests/unit/metadata-registration.spec.ts'
controls: [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]
exercised_by: [FAS-MBR-STR-01-01, FAS-MBR-STR-01-02, FAS-MBR-STR-01-03, FAS-MBR-STR-01-04, FAS-MBR-STR-01-05]
suites: [TST-MBR-STR-006, TST-MBR-STR-011, TST-MBR-STR-068, TST-MBR-STR-072, TST-MBR-STR-085, TST-MBR-STR-098, TST-MBR-STR-100]
---

# Find units and inspect current or historical structure

## Purpose

Readers obtain a consistent view of units, their ancestry and their placements on earlier dates.

## How It Works

Readers can find units through a filtered list or a code-and-name search. A paged tree provides enough parent information to present the structure incrementally. Unit-specific ancestry and descendant reads return complete collections. Readers can also inspect the retained parent periods. A historical request supplies an effective date and, when needed, the moment whose knowledge should be reproduced. This distinguishes a backdated correction from what an earlier report could know. Codes and names still come from the current unit records. Collection reads for unknown references return empty answers, so integrations must distinguish that behavior from reading one missing record. Published database functions let connected applications use the same current structure within their work. Query registration describes how reports can navigate unit ancestry. Registration evidence does not establish that those datasets have been deployed and exercised.

## Relationships

- Restructuring supplies the dated periods used in historical reads.
- Access controls govern staff reads and workspace isolation.