--- id: CAP-PFM-INT-001 title: Publish integration releases for eligible customers feature: FEAT-PFM-INT-01 product_area: platform module: integrations revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-INT-CAT-001 - CAP-INT-CAT-003 - CAP-INT-CAT-004 - CAP-INT-CAT-005 - CAP-INT-CAT-006 - CAP-INT-CRD-010 - CAP-INT-SEC-005 - CAP-INT-SEC-007 - CAP-INT-ADP-001 - CAP-INT-ADP-002 - CAP-INT-ADP-009 - CAP-INT-ADP-010 - CAP-INT-ADP-011 - CAP-INT-ADP-014 - CAP-INT-ADP-018 - CAP-INT-ADP-019 - CAP-INT-ADP-020 - CAP-INT-ADP-021 - CAP-INT-ADP-022 - CAP-INT-ADP-023 - CAP-INT-ADP-024 - CAP-INT-ADP-025 - CAP-INT-ADP-026 - CAP-INT-ADP-030 - CAP-INT-ADP-031 source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 intent_sources: - 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D3' - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#A5' purpose: Rhythm makes validated provider releases available to the customers eligible to use them. outcomes: - Contract validation precedes a release’s admission to the catalogue. - Customers keep the published manifest their connection uses. - 'Availability distinguishes public offers, named customers and Rhythm’s internal use.' concepts: - CON-PFM-INT-001 actors: - ACT-PFM-019 - ACT-PFM-021 surfaces: - api - job preconditions: [] postconditions: [] permissions: - key: hq.integrations.publish where_checked: api scope: global - key: hq.integrations.operate where_checked: api scope: global rules: - id: BR-CAP-PFM-INT-001-01 proved_by: [ATS-PFM-INT-001-01, TST-PFM-INT-563, TST-PFM-INT-582] statement: >- Only an adapter’s own principal may register its integration key, except that Platform may register any key outside production; unauthorized registration is refused without writes. kind: permission enforced_at: - service must_prove: true 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 origin: none - id: BR-CAP-PFM-INT-001-02 proved_by: [ATS-PFM-INT-001-02, ATS-PFM-INT-001-13, TST-PFM-INT-563, TST-PFM-INT-582] statement: >- Registration accepts a release only if its manifest fits the shared schemas, declares known capability majors and features, uses no newer contract package and matches its recomputed fingerprint; invalid releases leave no records. kind: validation enforced_at: - service must_prove: true 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 origin: none - id: BR-CAP-PFM-INT-001-03 proved_by: [ATS-PFM-INT-001-03, TST-PFM-INT-563] statement: First registration gives an integration internal availability until Rhythm changes the offer. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/registration/register-integration-version.integration.spec.js#creates the definition by its key, internal until Rhythm offers it origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D3' - id: BR-CAP-PFM-INT-001-04 proved_by: [ATS-PFM-INT-001-04, ATS-PFM-INT-001-13, TST-PFM-INT-562, TST-PFM-INT-563] statement: >- Publication freezes a version’s manifest through deprecation and retirement; a changed fingerprint is refused, while identical registration preserves the version and may replace its deployment. kind: invariant enforced_at: - service must_prove: true provenance: observed source: >- services-platform:modules/integrations/services/persistence/integration-versions.ts:writeRegisteredVersion origin: none - id: BR-CAP-PFM-INT-001-05 proved_by: [ATS-PFM-INT-001-05, TST-PFM-INT-503, TST-PFM-INT-563] statement: >- Registration records deployment location, permits one active deployment per release and environment, and drains the deployment being replaced. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/registration/register-integration-version.integration.spec.js#drains the deployment it replaces origin: none - id: BR-CAP-PFM-INT-001-06 proved_by: [ATS-PFM-INT-001-06, ATS-PFM-INT-001-13] statement: >- Authorized Rhythm staff move a validated version to published, a published version to deprecated and a deprecated version to retired, with every other transition refused. kind: lifecycle enforced_at: - api - service must_prove: true provenance: observed source: 'services-platform:modules/integrations/services/persistence/integration-versions.ts:VERSION_TRANSITIONS' origin: none - id: BR-CAP-PFM-INT-001-07 proved_by: [ATS-PFM-INT-001-07, ATS-PFM-INT-001-15] statement: Retirement is refused while any customer has a non-disconnected connection pinned to that version. kind: policy enforced_at: - service must_prove: true provenance: observed source: >- services-platform:modules/integrations/services/persistence/integration-versions.ts:pinnedConnectionCount origin: none - id: BR-CAP-PFM-INT-001-08 proved_by: [ATS-PFM-INT-001-08] statement: >- A published release becomes current if it is newer than the current published release, or if the current release is absent or no longer published. kind: calculation enforced_at: - service must_prove: true provenance: observed source: >- services-platform:modules/integrations/services/persistence/integration-versions.ts:moveCurrentVersionIfNewest origin: none - id: BR-CAP-PFM-INT-001-09 proved_by: [ATS-PFM-INT-001-09, ATS-PFM-INT-001-14, TST-PFM-INT-515] statement: >- Rhythm staff choose public, internal or restricted availability; restricted grants replace the whole customer list, and supplying grants for another availability is refused. kind: policy enforced_at: - api - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/catalog/catalog.integration.spec.js#replaces the whole list of grants origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D3' - id: BR-CAP-PFM-INT-001-10 proved_by: [ATS-PFM-INT-001-10, TST-PFM-INT-489, TST-PFM-INT-515] statement: >- The staff catalogue includes integrations of every availability with their versions, deployments and release notes; customer callers cannot read it. kind: permission enforced_at: - api must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/e2e/integrations.e2e.spec.js#is refused Rhythm HQ’s catalog (403) origin: none - id: BR-CAP-PFM-INT-001-11 proved_by: [ATS-PFM-INT-001-11, TST-PFM-INT-486, TST-PFM-INT-534] statement: >- Rhythm staff list declared platform-secret purposes and versions without values, write only declared purposes and leave a security record for each write; customer administrators are refused. kind: permission enforced_at: - api - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/e2e/credentials.e2e.spec.js#lists the integration’s declared secrets by name and version, never a value origin: none - id: BR-CAP-PFM-INT-001-12 proved_by: [ATS-PFM-INT-001-12] statement: >- Registration rejects external hosting, mismatched deployment principal, runtime or environment, duplicate capabilities and unsupported execution modes before saving the release. kind: validation enforced_at: - service must_prove: true provenance: observed source: >- services-platform:modules/integrations/services/registration/register-integration-version.ts:registerIntegrationVersion origin: none scenarios: - id: SC-CAP-PFM-INT-001-01 given: A test adapter release is deployed to development. when: Its pipeline registers a releasable version. then: The published version becomes current and its replacement deployment drains the earlier one. provenance: test source: >- services-platform:modules/integrations/tests/integration/services/registration/register-integration-version.integration.spec.js#publishes the version - id: SC-CAP-PFM-INT-001-02 given: A principal belongs to one provider adapter. when: It registers a different provider’s integration key. then: Registration refuses the request and saves no release records. 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 edge_cases: [] constraints: [] depends_on: [] related: - CAP-PFM-INT-002 - CAP-PFM-INT-004 journeys: [] open_questions: [] evidence: - >- services-platform source inventory: modules/integrations/services/registration/register-integration-version.ts, services/persistence/integration-versions.ts, services/catalog/catalog.ts, services/principals.ts, aws/api/registration.routes.ts, aws/api/integrations.routes.ts (HQ routes); rule-level automated test references; docs/integrations/README.md (The catalog, The registration service function); docs/milestones/INTG-M1-find-install-connect.md (D3), INTG-M6-rhythm-hq-operations.md. - >- macroservice-libraries source inventory: packages/integration-contracts (manifest, registry, compatibility). - >- Operation coverage: registerIntegrationVersion, publishIntegrationVersion, deprecateIntegrationVersion, retireIntegrationVersion, setIntegrationAvailability, listStaffIntegrationCatalog, listIntegrationPlatformSecrets, putIntegrationPlatformSecret. - >- Persistent record coverage: integration_definitions, integration_versions, capability_definitions, integration_capabilities, integration_deployments, integration_availability_grants. - 'End-to-end definition inventory: integrations.e2e.spec.js, credentials.e2e.spec.js.' controls: [TC-AVL-001, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-004, TC-IAM-001, TC-IAM-003, TC-IAM-006, TC-LOG-001, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-003, TC-PI-005, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] exercised_by: [FAS-PFM-INT-01-01, FAS-PFM-INT-01-02, FAS-PFM-INT-01-03, FAS-PFM-INT-01-04] suites: [TST-PFM-INT-486, TST-PFM-INT-489, TST-PFM-INT-503, TST-PFM-INT-515, TST-PFM-INT-534, TST-PFM-INT-562, TST-PFM-INT-563, TST-PFM-INT-582] --- # Publish integration releases for eligible customers ## Purpose Rhythm makes validated provider releases available to the customers eligible to use them. ## How It Works An adapter pipeline submits a release and the place where it runs. Rhythm validates the package before adding its catalogue records. Staff decide which releases and customers are ready for the offer. Administrators then discover that offer through the Library. Published manifests give existing connections a stable description of provider behaviour. Corrections arrive as another release rather than a rewrite of that description. Provider accounts held by Rhythm use separate staff-managed secrets. Publication and availability are operated through direct requests while staff screens await their later milestone. The product should keep the distinction between validating a release and accepting it for customer use visible. ## Relationships - Connects with explore the integrations available to a workspace through shared integration records. - Connects with maintain a verified provider account connection through shared integration records.