---
id: STATE-PFM-ELG-002
title: Rule version lifecycle
object: DOM-PFM-ELG-001
product_area: platform
module: eligibility
revision: 1
status: draft
design_intent: confirmed
origin: >-
  Eligibility Engine architecture (governance chapter 14: immutable versions,
  rollback as a new version, effective periods), approved by Andrew 2026-10-17
  as recorded in PLAT-M11 "Decisions"; PLAT-M11 plan D4, 2026-10-21
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
states:
  - name: draft
    meaning: >-
      The sole editable expression; saves may retain validation problems, but
      consumers do not evaluate this draft.
  - name: published
    meaning: An immutable numbered release available within its effective interval.
  - name: superseded
    meaning: >-
      A release replaced by overlapping later publication; existing or new valid
      pins can still evaluate it.
  - name: retired
    meaning: >-
      A withdrawn release: existing pins remain stored but produce an
      unpublished-reference reason; a new pin cannot select it.
transitions:
  - from: draft
    to: draft
    trigger: >-
      saveEligibilityDefinitionDraft, createEligibilityDefinition when
      expression is supplied, duplicateEligibilityDefinition
    guard: >-
      Write authority, an unarchived definition and a matching draft version
      when supplied.
    side_effects:
      - Return validation problems and summary
      - Replace draft dependencies
      - Record the draft change
    who: Rule author
    provenance: observed
    source: >-
      services-platform:modules/eligibility/services/model/authoring.ts:saveDefinitionDraft
  - from: draft
    to: published
    trigger: publishEligibilityDefinition
    guard: >-
      Publish authority, valid licensed expression and references, unchanged
      draft, acceptable effective interval, compatible followers unless forced
      and valid cited simulation.
    side_effects:
      - Assign the next number
      - Supersede the overlapping latest release
      - Suspend forced incompatible followers
      - Delete affected plans
      - Audit choices and counts
      - Queue role checks
    who: Rule publisher
    provenance: observed
    source: >-
      services-platform:modules/eligibility/services/governance/publish.ts:publishDefinition
  - from: published
    to: superseded
    trigger: Later overlapping publication or rollback
    guard: >-
      A later release commits with an interval overlapping this latest
      publication.
    side_effects:
      - Following uses select the applicable later release
    who: Rule publisher (as a consequence)
    provenance: observed
    source: 'services-platform:docs/eligibility.md#2. The lifecycle rules'
  - from: published
    to: retired
    trigger: retireVersion through persistence only
    guard: 'The persistence lifecycle permits retirement, but no API exposes it.'
    side_effects:
      - Retained pins return an unpublished-reference reason
    who: Nobody today
    provenance: observed
    source: >-
      services-platform:modules/eligibility/services/persistence/versions.ts:retireVersion
  - from: superseded
    to: retired
    trigger: retireVersion through persistence only
    guard: 'The persistence lifecycle permits retirement, but no API exposes it.'
    side_effects:
      - Retained pins return an unpublished-reference reason
    who: Nobody today
    provenance: observed
    source: 'services-platform:modules/eligibility/lifecycle.ts:VERSION_TRANSITIONS'
invalid:
  - from: published
    to: draft
    why: >-
      Released expressions never return to an editable draft; rollback creates
      another release.
  - from: superseded
    to: published
    why: A superseded number is not restored in place.
  - from: retired
    to: published
    why: Retirement has no outgoing release transition.
  - from: draft
    to: retired
    why: >-
      Draft retirement is unsupported; unreleased definitions can instead be
      deleted.
concurrency: >-
  Publication validates before entering the transaction, then locks and compares
  the draft fingerprint. Competing publications serialize and one succeeds.
  Effective-range exclusion is implemented by the service rather than a database
  exclusion constraint.
invariants:
  - INV-DOM-PFM-ELG-001-02
  - INV-DOM-PFM-ELG-001-03
  - INV-DOM-PFM-ELG-001-04
  - INV-DOM-PFM-ELG-001-05
evidence:
  - >-
    services-platform at ad3f6a6: modules/eligibility/lifecycle.ts;
    services/governance/publish.ts; services/persistence/versions.ts;
    services/model/authoring.ts; db/eligibility-versions.table.ts;
    docs/eligibility.md §2, §7.3;
    docs/debt/eligibility-published-range-exclusion.md.
---
# Rule version lifecycle

## The Lifecycle

```mermaid
stateDiagram-v2
  draft --> published
  published --> superseded
  published --> retired
  superseded --> retired
```

## Transitions Explained

Publication freezes the draft expression and assigns a new release number. An overlapping latest release becomes superseded, whereas disjoint scheduled releases can remain published. Retirement exists as persistence behavior without a public operation.

## What Cannot Happen

Released expressions never return to an editable draft; rollback creates another release. A superseded number is not restored in place. Retirement has no outgoing release transition. Draft retirement is unsupported; unreleased definitions can instead be deleted.

## Concurrency and Timing

Publication validates before entering the transaction, then locks and compares the draft fingerprint. Competing publications serialize and one succeeds. Effective-range exclusion is implemented by the service rather than a database exclusion constraint.