---
id: STATE-MBR-STR-003
title: Organization link period
object: DOM-MBR-STR-002
product_area: membership
module: structure
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
states:
  - name: open
    meaning: The dated relationship has no last day; a unit can have only one open legal-entity relationship.
  - name: ended
    meaning: >-
      The relationship has an inclusive last day no earlier than its first, including a possible future last
      day.
transitions:
  - from: open
    to: ended
    trigger: Staff supply the link's last day.
    guard: The link exists and the date is no earlier than its first day.
    side_effects:
      - The link version records the actor and last day.
      - A later nonoverlapping legal-entity relationship can be added.
    who: Structure administrator
    provenance: observed
    source: >-
      services-membership:modules/structure/services/persistence/organizational-unit-organizations.ts:unlinkOrganization
  - from: ended
    to: ended
    trigger: Staff repeat or shorten the last day.
    guard: 'The supplied day is between the first day and the existing last day, inclusive.'
    side_effects:
      - The end is rewritten and a version advances even for an unchanged date.
    who: Structure administrator
    provenance: observed
    source: >-
      services-membership:modules/structure/services/persistence/organizational-unit-organizations.ts:unlinkOrganization
invalid:
  - from: ended
    to: open
    why: No route clears the last day; a further relationship needs a new link record.
  - from: ended
    to: ended
    why: A last day later than the recorded last day is rejected as already ended.
concurrency: >-
  Creation locks the unit before checking legal-entity overlap, serializing link creations for that unit. The
  partial unique index separately prevents two open legal-entity links. Ending locks the link row; repeated
  creation can still duplicate a relationship purpose that permits overlap.
invariants:
  - INV-DOM-MBR-STR-002-04
evidence:
  - >-
    services-membership at 5994c270:
    modules/structure/services/persistence/organizational-unit-organizations.ts (linkOrganization,
    unlinkOrganization, requireDates); db/organizational-unit-organizations.table.ts.
---

# Organization link period

## The Lifecycle

```mermaid
stateDiagram-v2
  [*] --> open: first day supplied
  [*] --> ended: first and last days supplied
  open --> ended: last day recorded
  ended --> ended: repeat or shorten last day
```

## Transitions Explained

Staff can add an open relationship or one with both dates already known. Ending preserves the row as history. A later ending request can repeat or shorten the last day but cannot extend it.

## What Cannot Happen

The routes cannot reopen, remove or edit a link's organization, purpose or notes. Inclusive legal-entity periods for one unit cannot overlap.

## Concurrency and Timing

Creation serializes on the unit row and ending serializes on the link row. This prevents competing legal-entity creations from passing the same overlap check, while duplicate nonexclusive relationships remain possible on retry.