--- id: CAP-PFM-INT-008 title: Explain and select the connection for a call feature: FEAT-PFM-INT-03 product_area: platform module: integrations revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-INT-BND-005 - CAP-INT-BND-006 - CAP-INT-BND-007 - CAP-INT-BND-011 - CAP-INT-BND-012 - CAP-INT-LIB-012 - CAP-INT-ADP-004 source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D4' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#A3' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S01' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S02' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S04' purpose: 'Applications obtain an eligible connection, and staff can inspect the reasoning before making a call.' outcomes: - Resolution selects the configured eligible connection or refuses before provider contact. - An explanation exposes the same checks an application’s call uses. concepts: - CON-PFM-INT-003 actors: - ACT-PFM-017 - ACT-PFM-018 - ACT-PFM-020 surfaces: - console - api preconditions: [] postconditions: [] permissions: - key: platform.integrations.read where_checked: api scope: tenant - key: platform.integrations.read where_checked: console scope: tenant rules: - id: BR-CAP-PFM-INT-008-01 proved_by: [ATS-PFM-INT-007-12, ATS-PFM-INT-008-01, TST-PFM-INT-374, TST-PFM-INT-514, TST-PFM-INT-572] statement: >- Resolution examines available scopes in record, business unit, application and workspace order, skipping scopes missing from the call context. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/unit/services/binding-resolution.spec.ts#asks every scope the policy allows and the context names, most specific first origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D4' - id: BR-CAP-PFM-INT-008-02 proved_by: [ATS-PFM-INT-008-02, TST-PFM-INT-488, TST-PFM-INT-539, TST-PFM-INT-569] statement: >- The trace records eligibility checks for binding state, connection state, installation, deployed usable release, capability major and mode, verified features, amount and geography constraints, circuit state, and caller authorization with accepted capability access. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/unit/services/binding-eligibility.spec.ts#fails a published version with no active deployment here origin: none - id: BR-CAP-PFM-INT-008-03 proved_by: [ATS-PFM-INT-008-03, TST-PFM-INT-514, TST-PFM-INT-572] statement: >- An ineligible sensitive binding or refuse-policy binding stops resolution; other policies continue to broader scopes and report a skipped-binding warning. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/unit/services/binding-resolution.spec.ts#stops at the first ineligible binding with binding_ineligible, never reaching the broader scope origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D4' - id: BR-CAP-PFM-INT-008-04 proved_by: [ATS-PFM-INT-008-04, TST-PFM-INT-514, TST-PFM-INT-572] statement: >- When no scope has a binding, resolution refuses for missing configuration and records every scope examined. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/unit/services/binding-resolution.spec.ts#refuses no_binding with every visited scope recorded, each with no binding origin: none - id: BR-CAP-PFM-INT-008-05 proved_by: [ATS-PFM-INT-008-05, TST-PFM-INT-572] statement: >- Retired or sunset contract majors refuse before binding reads, deprecated majors remain usable before sunset and unknown capabilities are invalid requests. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/unit/services/binding-resolution.spec.ts#refuses contract_retired after its sunset, reading no scope origin: none - id: BR-CAP-PFM-INT-008-06 proved_by: [ATS-PFM-INT-008-06, TST-PFM-INT-488, TST-PFM-INT-514] statement: >- Degraded connections remain eligible with a warning, while suspended or re-authorization-required connections are ineligible. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/bindings/resolve.integration.spec.js#resolves with the connection_degraded warning while the circuit is closed origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S04' - id: BR-CAP-PFM-INT-008-07 proved_by: [ATS-PFM-INT-008-07, ATS-PFM-INT-008-10, ATS-PFM-INT-009-17, TST-PFM-INT-514, TST-PFM-INT-572] statement: >- An open circuit appears in the trace without invalidating its binding, so the gateway refuses provider availability on the selected connection rather than switches providers. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/unit/services/binding-resolution.spec.ts#resolves a payment whose processor’s circuit is open rather than refusing it binding_ineligible origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#A3' - id: BR-CAP-PFM-INT-008-08 proved_by: [ATS-PFM-INT-008-08, ATS-PFM-INT-008-11, ATS-PFM-INT-012-07, TST-PFM-INT-514] statement: >- Explicit-connection calls bypass bindings but require a usable workspace connection on a deployed release supporting the capability and mode; disconnected is reported distinctly from other unavailable states. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/bindings/resolve.integration.spec.js#reaches the processor that took the payment through its named connection origin: none - id: BR-CAP-PFM-INT-008-09 proved_by: [ATS-PFM-INT-008-09, TST-PFM-INT-400, TST-PFM-INT-488] statement: >- Integration readers may Explain using the same application context and trace as resolution, including refusal when an explicitly named connection lacks support. kind: permission enforced_at: - api - console must_prove: true provenance: test source: 'services-platform:modules/integrations/tests/e2e/integration-bindings.e2e.spec.js#may explain' origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S01' - id: BR-CAP-PFM-INT-008-10 proved_by: [] statement: >- Resolution uses a read-only transaction, rereads workspace records on each request and caches catalogue facts for no more than sixty seconds. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/bindings/resolve.integration.spec.js#read the tenant’s rows afresh on every resolution: a suspension is seen at once origin: none scenarios: - id: SC-CAP-PFM-INT-008-01 given: 'A meeting record’s room account lacks webinars, while the application’s broader account supports them.' when: The application resolves a webinar call for that record. then: Resolution uses the broader account and warns that it skipped the record choice. provenance: test source: >- services-platform:modules/integrations/tests/e2e/integration-bindings.e2e.spec.js#explains a webinar: the main account, by the application, warning that the resource binding was skipped edge_cases: [] constraints: [] depends_on: - CAP-PFM-INT-007 related: - CAP-PFM-INT-009 - CAP-PFM-INT-012 journeys: - JNY-PFM-INT-003 open_questions: [] evidence: - >- services-platform source inventory: modules/integrations/services/bindings/resolve.ts, eligibility.ts, catalog-cache.ts; rule-level automated test references; docs/integrations/README.md (The resolver, The explicit-connection check); docs/milestones/INTG-M2-* (M2-D4, A3). - >- macroservice-libraries source inventory: packages/integration-contracts/src/binding-policies.ts; associated unit test. - >- react-console source inventory: components/integrations/resolution-explain.tsx, lib/integrations/resolution.ts; acceptance journeys INT-ACC-0033, 0059. - 'Operation coverage: resolveIntegrationBinding.' - 'Persistent record coverage: integration_bindings, integration_circuit_states.' - 'End-to-end definition inventory: integration-bindings.e2e.spec.js.' controls: [TC-AVL-001, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-LOG-001, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] exercised_by: [FAS-PFM-INT-03-01, FAS-PFM-INT-03-02, FAS-PFM-INT-03-04] suites: [TST-PFM-INT-374, TST-PFM-INT-400, TST-PFM-INT-488, TST-PFM-INT-514, TST-PFM-INT-539, TST-PFM-INT-569, TST-PFM-INT-572] --- # Explain and select the connection for a call ## Purpose Applications obtain an eligible connection, and staff can inspect the reasoning before making a call. ## How It Works An application asks for a provider job in its business context. Rhythm examines the configured choices and their eligibility. Explain lets an administrator inspect that selection without performing the job. A trace shows where configuration is missing or an account cannot serve. A direct-account request supports operations tied to a previously used provider. Provider admission follows selection and keeps an open circuit from silently changing the chosen account. Fresh workspace reads let a configuration change affect subsequent resolutions. The product should present selection and provider availability as separate reasons for a call not proceeding. ## Relationships - Requires assign provider connections to business needs to supply the prerequisite configuration or operation. - Connects with run provider operations safely through the gateway through shared integration records. - Connects with exercise a provider capability on a test account through shared integration records.