--- id: DOM-PFM-INT-002 title: Connection realises: CON-PFM-INT-002 product_area: platform module: integrations revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-PFM-INT-integrations lifecycle: - STATE-PFM-INT-003 - STATE-PFM-INT-004 - STATE-PFM-INT-008 custom_fields: none identity: >- A connection’s configuration identifier is unique within its workspace and remains stable after renaming. Credential records receive generated identifiers. Each circuit combines a deployment and connection. attributes: - name: connection identifier and name kind: text required: true computed: false notes: 'A permanent configuration identifier accompanies the editable name, labels and optional business unit.' - name: installation and pinned release kind: reference required: true computed: false notes: The connection references its installation and the adapter release verified for that account. - name: standing kind: enum required: true computed: false notes: >- Status distinguishes authentication, verification, usable operation, degradation, reauthorization, suspension and final disconnection. - name: authentication method kind: enum required: true computed: false notes: >- Authentication must use a method declared by the pinned release, including entered credentials, OAuth or a platform account. - name: active credential kind: reference required: false computed: false notes: This reference selects the credential whose value is held in secret storage. - name: credential facts kind: document required: false computed: true notes: >- Visible metadata includes method, configuration time, permitted hint, expiries, scopes and recent refresh or use. - name: verified account and features kind: document required: false computed: false notes: 'Verification saves the provider’s account reference, feature support and classification as live or test.' - name: health and figures kind: document required: false computed: true notes: 'The latest check and eligible completed calls supply recent health, success share and latency figures.' - name: connection configuration kind: document required: false computed: false notes: Connection settings must satisfy the pinned release’s declared form. - name: connector notices kind: collection required: false computed: true notes: 'Successful calls can record one notice per warning code, retaining recurrence counts for thirty days.' - name: circuit kind: document required: false computed: true notes: >- Each deployment and connection has a closed, open or half-open breaker with its probe timing and failure history. - name: rate limits kind: collection required: false computed: true notes: >- Declared limits can be lowered by an operator writer, and provider retry-after responses temporarily reduce admission. - name: disconnection facts kind: document required: false computed: false notes: 'Disconnection or discard records retain the responsible actor, time and reason.' - name: version kind: computed required: true computed: true notes: Editing account configuration uses the connection version the person read. relationships: - to: DOM-PFM-INT-001 cardinality: Each connection refers to one installation and one release of its integration. ownership: 'The installation contains the link, whose row remains after disconnection.' cross_service: false - to: DOM-PFM-INT-003 cardinality: Any number of bindings and executions can name a connection. ownership: A current binding reference blocks closing the connection. cross_service: false - to: DOM-PFM-INT-004 cardinality: Each declared notification kind can have one endpoint on the connection. ownership: Verification provisions endpoints and disconnection disables them. cross_service: false invariants: - id: INV-DOM-PFM-INT-002-01 statement: 'Named service transitions govern connection status, and disconnected has no outgoing transition.' enforced_at: - service provenance: test source: >- services-platform:modules/integrations/tests/unit/services/connection-state-machine.spec.ts#is chapter 09 §4.3’s, edge for edge, and the three discards of INTG-M1 (D7) - id: INV-DOM-PFM-INT-002-02 statement: >- Within an installation, a provider account can appear on only one connection that has not been disconnected. enforced_at: - service - database provenance: test source: >- services-platform:modules/integrations/tests/integration/db/integration-connections.table.integration.spec.js#refuses the same provider account connected twice under the installation - id: INV-DOM-PFM-INT-002-03 statement: 'Every current binding that references a connection blocks its disconnection, without an override.' enforced_at: - service provenance: test source: >- services-platform:modules/integrations/tests/e2e/disconnect-and-uninstall.e2e.spec.js#answers a disconnection of a bound connection 409, code connection_has_bindings, naming each binding - id: INV-DOM-PFM-INT-002-04 statement: >- An account link with no successful verification can be discarded so abandoned setup does not block uninstallation. enforced_at: - service provenance: test source: >- services-platform:modules/integrations/tests/integration/services/connections/disconnect-discard-uninstall.integration.spec.js#ends a pending_auth connection disconnected, by the caller, with a reason saying it was discarded before it was ever connected - id: INV-DOM-PFM-INT-002-05 statement: >- Credential reads expose safe metadata; secret values are excluded from stored record fields and response logging. enforced_at: - api - service provenance: test source: >- services-platform:modules/integrations/tests/integration/services/credentials/credential-state.integration.spec.js#answers no secret value, secret name or key version - id: INV-DOM-PFM-INT-002-06 statement: >- Credential leases identify their execution and adapter, last five minutes by default, cannot exceed sixty minutes and refuse suspended connections. enforced_at: - service provenance: test source: >- services-platform:modules/integrations/tests/integration/services/credentials/broker.integration.spec.js#is refused as connection_unavailable for a suspended connection - id: INV-DOM-PFM-INT-002-07 statement: >- Replacing a credential requests deletion of the old secret with a seven-day recovery window; scheduling failure can delay cleanup, and destroyed records cannot return to use. enforced_at: - service provenance: observed source: >- services-platform:modules/integrations/services/credentials/credential-store.ts:storeConnectionCredential - id: INV-DOM-PFM-INT-002-08 statement: >- A connection has at most one open job of each check kind; another request receives the existing verification or health job. enforced_at: - service provenance: test source: >- services-platform:modules/integrations/tests/integration/services/connections/connection-job-dedup.integration.spec.js#answers one job to both requests, which the connection’s lock serializes - id: INV-DOM-PFM-INT-002-09 statement: >- The documented breaker opens after five consecutive unavailable or timeout outcomes, initially waits sixty seconds and doubles failed-probe waits to a fifteen-minute ceiling. enforced_at: - service provenance: documented source: 'services-platform:docs/integrations/README.md#Circuits (13 §10)' - id: INV-DOM-PFM-INT-002-10 statement: >- A release update changes the connection pin only after verification succeeds for the same provider account. enforced_at: - service provenance: observed source: >- services-platform:modules/integrations/services/connections/connection-operations.ts:requestVersionUpdate readable_by: - SVC-PFM-INT-integrations physical: - platform.integration_connections - platform.integration_credentials - platform.integration_oauth_states - platform.integration_connection_notices - platform.integration_circuit_states - platform.integration_rate_limits - platform.integration_verification_jobs - platform.integration_verification_job_steps - platform.integration_verification_job_events - platform.integration_health_jobs - platform.integration_health_job_steps - platform.integration_health_job_events - platform.integration_health_cursors evidence: - >- services-platform at ad3f6a65: modules/integrations/db/integration-connections.table.ts, integration-credentials.table.ts, integration-circuit-states.table.ts, integration-connection-notices.table.ts; services/connections/transition.ts, connection-operations.ts, submit-connection-jobs.ts; services/credentials/broker.ts, credential-store.ts - >- services-platform at ad3f6a65: docs/integrations/README.md (The connection state machine; Verification and health; Credentials; Circuits; Connection notices) - >- react-console at baf6dae3: components/integrations/connection-detail.tsx, connection-wizard.tsx; lib/integrations/connection-dot.ts --- # Connection ## What It Models A connection records the link to one provider account. It holds the verified account identity, adapter release pin, safe authentication metadata and operational health that determine whether a call can use that account. Its routing choices live in bindings rather than in the account link itself. ## Identity and Attributes A connection’s configuration identifier is unique within its workspace and remains stable after renaming. Credential records receive generated identifiers. Each circuit combines a deployment and connection. A permanent configuration identifier accompanies the editable name, labels and optional business unit. The connection references its installation and the adapter release verified for that account. Status distinguishes authentication, verification, usable operation, degradation, reauthorization, suspension and final disconnection. Authentication must use a method declared by the pinned release, including entered credentials, OAuth or a platform account. This reference selects the credential whose value is held in secret storage. Visible metadata includes method, configuration time, permitted hint, expiries, scopes and recent refresh or use. Verification saves the provider’s account reference, feature support and classification as live or test. The latest check and eligible completed calls supply recent health, success share and latency figures. Connection settings must satisfy the pinned release’s declared form. Successful calls can record one notice per warning code, retaining recurrence counts for thirty days. Each deployment and connection has a closed, open or half-open breaker with its probe timing and failure history. Declared limits can be lowered by an operator writer, and provider retry-after responses temporarily reduce admission. Disconnection or discard records retain the responsible actor, time and reason. Editing account configuration uses the connection version the person read. ## Relationships Each connection refers to one installation and one release of its integration.. The installation contains the link, whose row remains after disconnection.. Any number of bindings and executions can name a connection.. A current binding reference blocks closing the connection.. Each declared notification kind can have one endpoint on the connection.. Verification provisions endpoints and disconnection disables them.. ## Invariants Named service transitions govern connection status, and disconnected has no outgoing transition. Within an installation, a provider account can appear on only one connection that has not been disconnected. Every current binding that references a connection blocks its disconnection, without an override. An account link with no successful verification can be discarded so abandoned setup does not block uninstallation. Credential reads expose safe metadata; secret values are excluded from stored record fields and response logging. Credential leases identify their execution and adapter, last five minutes by default, cannot exceed sixty minutes and refuse suspended connections. Replacing a credential requests deletion of the old secret with a seven-day recovery window; scheduling failure can delay cleanup, and destroyed records cannot return to use. A connection has at most one open job of each check kind; another request receives the existing verification or health job. The documented breaker opens after five consecutive unavailable or timeout outcomes, initially waits sixty seconds and doubles failed-probe waits to a fifteen-minute ceiling. A release update changes the connection pin only after verification succeeds for the same provider account. ## How It Is Stored and Shared The integrations service stores connections and credential metadata; secret values remain in secret storage. Check jobs retain their own steps and events. The examined table declarations and service predicates separate workspace records, while provider operations cross the external boundary through the adapter. This object has no custom-field declaration. ## Open Design Questions The attention summary and queue disagree about deliberate suspension. Circuit thresholds depend partly on process-local counts. OAuth acceptance, operator rate-limit controls and deletion of retained secrets still need decisions or connected proof.