--- id: STATE-PFM-INT-002 title: Installation lifecycle object: DOM-PFM-INT-001 product_area: platform module: integrations revision: 1 status: draft design_intent: confirmed implementation_evidence: observed origin: 'docs/milestones/INTG-M1-find-install-connect.md#Decisions D7, D11 (INTG-M1 Product Accepted)' source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 states: - name: absent meaning: The workspace has no retained installation for this integration. - name: enabled meaning: The installation is usable and its eligible accounts can serve calls. - name: suspended meaning: 'Adoption is paused with a reason, affecting usable accounts and their bindings.' - name: uninstalled meaning: The retained adoption record is removed from use and its subscriptions have been deleted. transitions: - from: absent to: enabled trigger: Adopt the integration guard: The offer is visible with a published current release and valid settings and accepted access side_effects: - Commit adoption values and both audit entries. who: Integration administrator provenance: test source: >- services-platform:modules/integrations/tests/integration/services/installations/installation-lifecycle.integration.spec.js#refuses an integration installed already, and writes no second - from: enabled to: enabled trigger: Edit adopted configuration guard: The supplied version matches and values fit the current declaration side_effects: - Clear notices affected by settings - Pause subscriptions to withdrawn event types - Commit both audit entries. who: Integration administrator provenance: test source: >- services-platform:modules/integrations/tests/integration/services/installations/installation-lifecycle.integration.spec.js#refuses a stale version and leaves the settings as they were - from: enabled to: suspended trigger: Pause adoption guard: The request includes a suspension reason side_effects: - Pause active and degraded accounts with installation attribution - Invalidate their bindings and retain audit entries. who: Integration administrator provenance: test source: >- services-platform:modules/integrations/tests/integration/services/installations/installation-lifecycle.integration.spec.js#suspends the active and degraded connections of the installation when it is suspended - from: suspended to: enabled trigger: Restore adoption guard: The installation remains suspended side_effects: - Restore only accounts paused by this installation and bindings eligible again. who: Integration administrator provenance: test source: >- services-platform:modules/integrations/tests/integration/services/installations/installation-lifecycle.integration.spec.js#suspends the active and degraded connections of the installation when it is suspended - from: enabled to: uninstalled trigger: Remove adoption guard: Every account link has reached disconnected side_effects: - Delete subscriptions and commit both audit entries. who: Integration administrator provenance: test source: >- services-platform:modules/integrations/tests/integration/services/connections/disconnect-discard-uninstall.integration.spec.js#is refused while a connection is not disconnected, naming each by id, name and status - from: suspended to: uninstalled trigger: Remove paused adoption guard: Every account link has reached disconnected side_effects: - Delete the installation’s subscriptions with removal. who: Integration administrator provenance: observed source: >- services-platform:modules/integrations/services/installations/installation-lifecycle.ts:uninstallInstallation - from: uninstalled to: enabled trigger: Adopt after prior removal guard: Ordinary offer and configuration validation passes again side_effects: - Reuse the retained record with new acceptance and record reinstallation. who: Integration administrator provenance: test source: >- services-platform:modules/integrations/tests/integration/services/installations/installation-lifecycle.integration.spec.js#installs again as the same row, enabled with the new acceptance, audited as a reinstallation invalid: - from: absent to: suspended why: An adoption starts enabled; a duplicate installed record is refused. - from: uninstalled to: suspended why: Removed adoption must be installed again before suspension. - from: suspended to: suspended why: A source-status guard rejects an already paused installation. concurrency: >- Edits compare the version the administrator read. Lifecycle routes instead lock and compare status, with account cascades in the same transaction. Concurrent lifecycle actions can therefore succeed without a stale-version warning when their source status remains acceptable. invariants: - INV-DOM-PFM-INT-001-07 - INV-DOM-PFM-INT-001-08 - INV-DOM-PFM-INT-001-09 - INV-DOM-PFM-INT-001-10 evidence: - >- services-platform at ad3f6a65: modules/integrations/services/installations/installation-lifecycle.ts; services/persistence/integration-installations.ts; docs/milestones/INTG-M1-find-install-connect.md (D7, D11) --- # Installation lifecycle ## The Lifecycle ```mermaid stateDiagram-v2 state "absent" as s0 state "enabled" as s1 state "suspended" as s2 state "uninstalled" as s3 s0 --> s1: Adopt the integration s1 --> s1: Edit adopted configuration s1 --> s2: Pause adoption s2 --> s1: Restore adoption s1 --> s3: Remove adoption s2 --> s3: Remove paused adoption s3 --> s1: Adopt after prior removal ``` ## Transitions Explained Installation retains one adoption record, including after removal. Suspension marks the accounts it pauses so resumption can leave individually paused accounts alone. Removing adoption waits for all links to close and deletes the subscriptions instead of preserving their definitions. ## What Cannot Happen An adoption starts enabled; a duplicate installed record is refused. Removed adoption must be installed again before suspension. A source-status guard rejects an already paused installation. ## Concurrency and Timing Edits compare the version the administrator read. Lifecycle routes instead lock and compare status, with account cascades in the same transaction. Concurrent lifecycle actions can therefore succeed without a stale-version warning when their source status remains acceptable.