---
id: STATE-PFM-INT-001
title: Integration release lifecycle
object: DOM-PFM-INT-001
product_area: platform
module: integrations
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03
states:
  - name: absent
    meaning: This release version has no registry record.
  - name: validated
    meaning: Registration validated the declaration without offering it to customers.
  - name: published
    meaning: The release is published for eligible customers and its manifest is immutable.
  - name: deprecated
    meaning: Existing account pins remain usable while the release is deprecated.
  - name: retired
    meaning: The release is retained after retirement and no live account may remain pinned.
  - name: draft
    meaning: 'The table permits this status, but normal registration does not write it.'
  - name: rejected
    meaning: 'The table permits rejection status, but the examined registration path does not produce it.'
transitions:
  - from: absent
    to: validated
    trigger: Register without release publication
    guard: Manifest and runtime validation pass and the caller has adapter authority
    side_effects:
      - Save a first definition with internal availability
      - Save capability entries and replace the environment deployment.
    who: Registration service function
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/registration/register-integration-version.integration.spec.js#refuses
      a hash that is not the manifest’s, and writes nothing
  - from: absent
    to: published
    trigger: Register for immediate publication
    guard: Registration passes its manifest and authority checks
    side_effects:
      - Stamp publication and update the current pointer when eligible.
    who: Registration service function
    provenance: observed
    source: >-
      services-platform:modules/integrations/services/persistence/integration-versions.ts:writeRegisteredVersion
  - from: validated
    to: validated
    trigger: Replace an unpublished declaration
    guard: The existing version remains mutable
    side_effects:
      - 'Replace the release manifest, capabilities and deployment.'
    who: Registration service function
    provenance: observed
    source: >-
      services-platform:modules/integrations/services/persistence/integration-versions.ts:writeRegisteredVersion
  - from: published
    to: published
    trigger: Redeploy an immutable release
    guard: The manifest fingerprint matches the retained release
    side_effects:
      - Keep release content and update the deployment.
    who: Registration service function
    provenance: observed
    source: >-
      services-platform:modules/integrations/services/persistence/integration-versions.ts:writeRegisteredVersion
  - from: validated
    to: published
    trigger: Publish through staff administration
    guard: The locked release remains validated
    side_effects:
      - Record publication and advance an eligible current pointer.
    who: Rhythm staff with release publishing
    provenance: observed
    source: >-
      services-platform:modules/integrations/services/persistence/integration-versions.ts:transitionIntegrationVersion
  - from: published
    to: deprecated
    trigger: Deprecate through staff administration
    guard: The locked release remains published
    side_effects:
      - Record deprecation while leaving the current pointer unchanged.
    who: Rhythm staff with release publishing
    provenance: observed
    source: >-
      services-platform:modules/integrations/services/persistence/integration-versions.ts:transitionIntegrationVersion
  - from: deprecated
    to: retired
    trigger: Retire through staff administration
    guard: The deprecated release has no non-disconnected connection pin in any workspace
    side_effects:
      - Read the cross-workspace pin count before recording retirement.
    who: Rhythm staff with release publishing
    provenance: observed
    source: >-
      services-platform:modules/integrations/services/persistence/integration-versions.ts:pinnedConnectionCount
invalid:
  - from: published
    to: validated
    why: 'Publication freezes content, so registration cannot turn the release mutable again.'
  - from: validated
    to: deprecated
    why: Deprecation requires a published source release.
  - from: published
    to: retired
    why: A release must first be deprecated before staff can retire it.
  - from: retired
    to: published
    why: >-
      Staff publication requires validated status, so retired releases cannot be republished by that
      transition.
concurrency: >-
  Registration and staff transitions commit atomically and existing release rows are locked. A concurrent
  insert of the same new version can lose to database uniqueness. Deprecation does not recompute the current
  pointer and there is no forced account upgrade timer.
invariants:
  - INV-DOM-PFM-INT-001-02
  - INV-DOM-PFM-INT-001-03
  - INV-DOM-PFM-INT-001-04
  - INV-DOM-PFM-INT-001-05
evidence:
  - >-
    services-platform at ad3f6a65: modules/integrations/db/integration-versions.table.ts;
    services/persistence/integration-versions.ts; services/registration/register-integration-version.ts;
    aws/api/integrations.routes.ts (publish, deprecate, retire)
---

# Integration release lifecycle

## The Lifecycle

```mermaid
stateDiagram-v2
  state "absent" as s0
  state "validated" as s1
  state "published" as s2
  state "deprecated" as s3
  state "retired" as s4
  state "draft" as s5
  state "rejected" as s6
  s0 --> s1: Register without release publication
  s0 --> s2: Register for immediate publication
  s1 --> s1: Replace an unpublished declaration
  s2 --> s2: Redeploy an immutable release
  s1 --> s2: Publish through staff administration
  s2 --> s3: Deprecate through staff administration
  s3 --> s4: Retire through staff administration
```

## Transitions Explained

Registration records a validated release or publishes it immediately when requested. Staff can publish, deprecate and retire through guarded operations. A published manifest stays immutable through later status changes; identical redeployment only replaces runtime information.

## What Cannot Happen

Publication freezes content, so registration cannot turn the release mutable again. Deprecation requires a published source release. A release must first be deprecated before staff can retire it. Staff publication requires validated status, so retired releases cannot be republished by that transition.

## Concurrency and Timing

Registration and staff transitions commit atomically and existing release rows are locked. A concurrent insert of the same new version can lose to database uniqueness. Deprecation does not recompute the current pointer and there is no forced account upgrade timer.