---
id: STATE-PFM-NOT-001
title: Notification definition registration
object: DOM-PFM-NOT-003
product_area: platform
module: notifications
revision: 1
status: draft
design_intent: confirmed
origin: D-03 (definitions registered at deploy through a manifest intake), Andrew 2026-10-21 17:15 ET,
  services-platform:docs/proposals/notifications/23-decisions.md#D-03. Definitions are registered at deploy,
  with their default templates
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
states:
- name: undeclared
  meaning: Registration has not created this definition.
- name: active
  meaning: The definition is available for request processing.
- name: retired
  meaning: History retains the definition, but new requests cannot use it.
transitions:
- from: undeclared
  to: active
  trigger: A release submits its notification manifest.
  guard: The complete declaration passes ownership, vocabulary, audience, schema, rendering, route and
    action checks; system alerts also require an HQ channel mapping.
  side_effects:
  - Create the first version and record the declaring release.
  who: Application release registration
  provenance: test
  source: services-platform:modules/notifications/tests/integration/services/registration/register-service-notifications.integration.spec.js#refuses
    a key that belongs to another application
- from: active
  to: active
  trigger: A subsequent release includes the definition.
  guard: Category and preference mode must match their stored values.
  side_effects:
  - Leave identical content unchanged.
  - Save changed content as another version with the release recorded.
  who: Application release registration
  provenance: test
  source: services-platform:modules/notifications/tests/integration/services/registration/register-service-notifications.integration.spec.js#refuses
    a category that changes between releases, telling the owner to re-key the definition
- from: active
  to: retired
  trigger: A valid release removes the definition from its manifest.
  guard: All remaining declarations must pass validation.
  side_effects:
  - After registry commit, cancel and settle open accepted requests in each operational workspace; log
    a workspace failure and continue.
  - Existing notices and queued deliveries remain in place.
  who: Application release registration
  provenance: observed
  source: services-platform:modules/notifications/services/registration/register-service-notifications.ts:cancelRetiredRequests;
    services-platform:modules/notifications/services/persistence/requests.ts:cancelOpenRequestsOfDefinition
- from: retired
  to: active
  trigger: A release restores a retired declaration.
  guard: Validation must pass and the original category and preference mode must be retained.
  side_effects:
  - Reactivate the row and record the updated declaration and release.
  who: Application release registration
  provenance: observed
  source: services-platform:modules/notifications/services/persistence/definitions.ts:upsertDefinition
invalid:
- from: active
  to: undeclared
  why: Historical references require the definition row to remain.
- from: retired
  to: undeclared
  why: Retirement preserves the historical row.
- from: active
  to: active
  why: Changing category or preference mode requires a different definition key.
concurrency: Registry changes share one transaction. The later of competing application registrations
  determines the final manifest. Request cancellation runs after commit and logs failures without retrying
  them.
invariants:
- INV-DOM-PFM-NOT-003-10
evidence:
- 'services-platform at ad3f6a65: modules/notifications/services/registration/{register-service-notifications,registration-manifest}.ts;
  services/persistence/definitions.ts; templates.ts; docs/notifications.md §3.'
---
# Notification definition registration

## The Lifecycle

```mermaid
stateDiagram-v2
    state "undeclared" as s0
    state "active" as s1
    state "retired" as s2
    s0 --> s1
    s1 --> s1
    s1 --> s2
    s2 --> s1
```

## Transitions Explained

The transition rows describe stored state changes, their checks and their recorded effects. A queue receive, provider outcome and staff action can reach different lifecycle boundaries.

## What Cannot Happen

Historical references require the definition row to remain. Retirement preserves the historical row. Changing category or preference mode requires a different definition key.

## Concurrency and Timing

Registry changes share one transaction. The later of competing application registrations determines the final manifest. Request cancellation runs after commit and logs failures without retrying them.