PSA/ee/docs/plans/2026-03-16-service-period-first-billing-and-cadence-ownership/RECURRING_SERVICE_PERIOD_LIFECYCLE.md

Recurring Service-Period Lifecycle

Purpose

F233 defines the first explicit lifecycle model for persisted recurring service-period records created in F231-F232.

This checkpoint defines:

• what each lifecycle state means
• which transitions are allowed now
• which states are terminal for v1

This checkpoint does not yet define edit operations, regeneration conflict handling, invoice linkage, or corrective flows. Those remain sequenced behind F238-F254.

State Meanings

State	Meaning
generated	A future period created directly from source recurrence rules with no user override yet applied.
edited	A future period whose boundaries or scheduling semantics differ intentionally from the generated default.
skipped	A future period that remains on the ledger for auditability but is intentionally excluded from billing selection.
locked	A period whose boundaries are frozen for an upcoming billing action or operational review and should not be changed by normal authoring paths.
billed	A period that has already been consumed by invoice linkage and is immutable in normal v1 flows.
superseded	A period revision that has been replaced by a newer record for the same logical period slot.
archived	A period retained only for history, audit, or storage-management purposes and no longer participates in live operational flows.

Allowed Transitions

The v1 lifecycle contract is intentionally conservative:

• generated -> edited | skipped | locked | billed | superseded | archived
• edited -> skipped | locked | billed | superseded | archived
• skipped -> edited | locked | superseded | archived
• locked -> billed | superseded | archived
• billed -> archived
• superseded -> archived
• archived -> no further transitions

Terminal States

The v1 terminal states are:

• billed
• superseded
• archived

locked is not terminal. It is intentionally a pre-billing freeze state that still permits lifecycle advancement into billed, superseded, or archived.

Lifecycle Invariants

• billed periods are immutable in normal v1 flows. Later corrective flows must create explicit follow-on behavior instead of silently mutating billed records in place.
• superseded periods remain queryable for provenance but are no longer eligible for normal due selection.
• skipped periods remain visible on the ledger; skip is not the same thing as deletion.
• archived is a storage and audit state, not a billing state.
• transitions that are not explicitly listed above are invalid for v1 and must fail fast rather than being interpreted implicitly by callers.

Authoritative Runtime Contract

The shared lifecycle transition contract now lives in:

• shared/billingClients/recurringServicePeriodLifecycle.ts

That module exports:

• RECURRING_SERVICE_PERIOD_LIFECYCLE_TRANSITIONS
• RECURRING_SERVICE_PERIOD_TERMINAL_STATES
• canTransitionRecurringServicePeriodState(...)
• isRecurringServicePeriodStateTerminal(...)

Future regeneration, editing, skip/defer, and billing-linkage flows should consume that shared transition contract rather than open-coding state rules locally.