--- id: DOM-PFM-INT-001 title: Integration realises: CON-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 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-PFM-INT-integrations lifecycle: - STATE-PFM-INT-001 - STATE-PFM-INT-002 custom_fields: none identity: >- The integration key identifies an offer. Releases combine that key with a semantic version, and deployments add an environment and sequence. A workspace keeps a single installation for each integration, including after removal. attributes: - name: integration key kind: text required: true computed: false notes: The manifest supplies a permanent lowercase configuration key. - name: 'name, description, categories and presentation' kind: text required: true computed: false notes: 'The current release supplies the name, description, categories and presentation shown in the catalogue.' - name: availability kind: enum required: true computed: false notes: New offers start internal; staff can make them public or restrict them to named workspaces. - name: availability grants kind: collection required: false computed: false notes: 'For restricted availability, staff replace the complete list of eligible workspaces.' - name: definition standing kind: enum required: true computed: false notes: >- Definitions can be active, hidden or retired; catalogue reads also require a published current-release pointer. - name: current release kind: reference required: false computed: true notes: >- Publication advances a published pointer only to a newer release, or replaces an absent or unpublished pointer; deprecation leaves it unchanged. - name: release kind: collection required: true computed: false notes: >- Each release retains the manifest, fingerprint, contract package version, release notes and declared status. - name: implemented capabilities kind: collection required: true computed: false notes: >- Capability majors retain execution modes, feature support and constraints, alongside shared contract catalogue entries. - name: deployment kind: collection required: true computed: false notes: >- Deployments identify the runtime location, service principal and entry points for a release and environment, with active, draining or inactive status. - name: installation standing kind: enum required: true computed: false notes: 'An installation is enabled, suspended with a reason, or uninstalled.' - name: installation settings kind: document required: false computed: false notes: Installation values must satisfy the form declared by the current release. - name: accepted access kind: document required: true computed: false notes: >- The saved capability, event, data-scope and Rhythm-permission lists cannot exceed the current declaration. - name: platform secret purposes kind: collection required: false computed: true notes: Declared Rhythm-owned secret purposes expose existence and version metadata without revealing values. - name: version kind: computed required: true computed: true notes: Settings and acceptance edits include the installation version previously read. relationships: - to: DOM-PFM-INT-002 cardinality: 'One installation contains any number of connections, each pinned to a release of that integration.' ownership: The installation owns the account links and refuses removal until all are disconnected. cross_service: false - to: DOM-PFM-INT-003 cardinality: A release can implement capability majors used by many calls. ownership: Execution records reference the serving release and deployment without owning the catalogue. cross_service: false - to: DOM-PFM-INT-004 cardinality: 'An installation can have several subscriptions, using the release’s event declarations.' ownership: Installation removal deletes its subscriptions. cross_service: false invariants: - id: INV-DOM-PFM-INT-001-01 statement: >- Registration accepts an adapter only for its own integration; Platform can register other integrations in non-production environments. enforced_at: - service provenance: test source: >- services-platform:modules/integrations/tests/integration/services/registration/register-integration-version.integration.spec.js#refuses an adapter principal registering another adapter’s key (403), and writes nothing - id: INV-DOM-PFM-INT-001-02 statement: A release that has been published rejects a different manifest fingerprint on registration. enforced_at: - service provenance: observed source: >- services-platform:modules/integrations/services/persistence/integration-versions.ts:writeRegisteredVersion - id: INV-DOM-PFM-INT-001-03 statement: >- Deployment replacement drains the preceding deployment and leaves at most one active deployment for that release in each environment. enforced_at: - service - database provenance: test source: >- services-platform:modules/integrations/tests/integration/services/registration/register-integration-version.integration.spec.js#drains the deployment it replaces - id: INV-DOM-PFM-INT-001-04 statement: >- Staff publish validated releases, deprecate published releases and retire deprecated releases only after all live connection pins are removed. enforced_at: - service provenance: observed source: 'services-platform:modules/integrations/services/persistence/integration-versions.ts:VERSION_TRANSITIONS' - id: INV-DOM-PFM-INT-001-05 statement: >- Publishing replaces a missing or unpublished current pointer, or advances a published pointer to a newer release. enforced_at: - service provenance: observed source: >- services-platform:modules/integrations/services/persistence/integration-versions.ts:moveCurrentVersionIfNewest - id: INV-DOM-PFM-INT-001-06 statement: >- The customer catalogue requires an active definition and published current pointer, with availability granted publicly, explicitly or through staff access. enforced_at: - service provenance: test source: >- services-platform:modules/integrations/tests/integration/services/catalog/catalog.integration.spec.js#shows a restricted integration only to the tenant granted it - id: INV-DOM-PFM-INT-001-07 statement: >- Installation is unique for an integration within a workspace; reinstalling restores the existing uninstalled record. enforced_at: - service - database 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 - id: INV-DOM-PFM-INT-001-08 statement: Installation and edits validate accepted access and settings against the current release declaration. enforced_at: - service provenance: observed source: >- services-platform:modules/integrations/services/installations/installation-lifecycle.ts:requireAcceptance - id: INV-DOM-PFM-INT-001-09 statement: Uninstallation refuses every connection that has not reached disconnected. enforced_at: - service 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 - id: INV-DOM-PFM-INT-001-10 statement: >- An accepted installation mutation commits its integration and security audit entries together; refusals add neither entry. enforced_at: - service provenance: test source: >- services-platform:modules/integrations/tests/integration/services/installations/history-and-security-trail.integration.spec.js#writes the narrowing to the history and to the security trail readable_by: - SVC-PFM-INT-integrations physical: - platform.integration_definitions - platform.integration_versions - platform.capability_definitions - platform.integration_capabilities - platform.integration_deployments - platform.integration_availability_grants - platform.integration_installations - platform.integration_audit_events evidence: - >- services-platform at ad3f6a65: modules/integrations/db/integration-definitions.table.ts, integration-versions.table.ts, integration-installations.table.ts, integration-deployments.table.ts; services/catalog/catalog.ts; services/registration/register-integration-version.ts; services/installations/installation-lifecycle.ts; services/persistence/integration-versions.ts - >- services-platform at ad3f6a65: docs/integrations/README.md (The catalog; The registration service function); docs/milestones/INTG-M1-find-install-connect.md (Decisions D3, D4, D7, D11) - 'macroservice-libraries at 54536a44: packages/integration-contracts (manifest schema, capability registry)' - 'rhythm-v2-docs: specs/platform/integrations/planning/concepts/CON-PFM-INT-001-integration.md' --- # Integration ## What It Models An integration connects an adapter offering to the customers allowed to adopt it. Adapter registration creates the global offer and release declaration; staff set availability; a customer administrator creates an installation with selected settings and access. These global and workspace records remain one concept because they describe successive parts of adopting the same offering. ## Identity and Attributes The integration key identifies an offer. Releases combine that key with a semantic version, and deployments add an environment and sequence. A workspace keeps a single installation for each integration, including after removal. The manifest supplies a permanent lowercase configuration key. The current release supplies the name, description, categories and presentation shown in the catalogue. New offers start internal; staff can make them public or restrict them to named workspaces. For restricted availability, staff replace the complete list of eligible workspaces. Definitions can be active, hidden or retired; catalogue reads also require a published current-release pointer. Publication advances a published pointer only to a newer release, or replaces an absent or unpublished pointer; deprecation leaves it unchanged. Each release retains the manifest, fingerprint, contract package version, release notes and declared status. Capability majors retain execution modes, feature support and constraints, alongside shared contract catalogue entries. Deployments identify the runtime location, service principal and entry points for a release and environment, with active, draining or inactive status. An installation is enabled, suspended with a reason, or uninstalled. Installation values must satisfy the form declared by the current release. The saved capability, event, data-scope and Rhythm-permission lists cannot exceed the current declaration. Declared Rhythm-owned secret purposes expose existence and version metadata without revealing values. Settings and acceptance edits include the installation version previously read. ## Relationships One installation contains any number of connections, each pinned to a release of that integration.. The installation owns the account links and refuses removal until all are disconnected.. A release can implement capability majors used by many calls.. Execution records reference the serving release and deployment without owning the catalogue.. An installation can have several subscriptions, using the release’s event declarations.. Installation removal deletes its subscriptions.. ## Invariants Registration accepts an adapter only for its own integration; Platform can register other integrations in non-production environments. A release that has been published rejects a different manifest fingerprint on registration. Deployment replacement drains the preceding deployment and leaves at most one active deployment for that release in each environment. Staff publish validated releases, deprecate published releases and retire deprecated releases only after all live connection pins are removed. Publishing replaces a missing or unpublished current pointer, or advances a published pointer to a newer release. The customer catalogue requires an active definition and published current pointer, with availability granted publicly, explicitly or through staff access. Installation is unique for an integration within a workspace; reinstalling restores the existing uninstalled record. Installation and edits validate accepted access and settings against the current release declaration. Uninstallation refuses every connection that has not reached disconnected. An accepted installation mutation commits its integration and security audit entries together; refusals add neither entry. ## How It Is Stored and Shared The integrations service owns the catalogue, deployment and installation records. Global declarations are shared, while installations and operational history are workspace records. The scoped declarations describe workspace isolation; cross-workspace retirement checks use a privileged count. Custom-field support is not declared. ## Open Design Questions Access restoration remains disputed against the recorded narrowing decision. Deprecating the current release can hide the offer because its pointer is not recomputed. Staff release screens and complete automated lifecycle proof remain unfinished.