--- id: CAP-PFM-INT-009 title: Run provider operations safely through the gateway feature: FEAT-PFM-INT-03 product_area: platform module: integrations revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-INT-EXE-001 - CAP-INT-EXE-002 - CAP-INT-EXE-003 - CAP-INT-EXE-004 - CAP-INT-EXE-005 - CAP-INT-EXE-007 - CAP-INT-EXE-008 - CAP-INT-EXE-019 - CAP-INT-EXE-021 - CAP-INT-EXE-022 - CAP-INT-SEC-004 - CAP-INT-SEC-006 - CAP-INT-ADP-003 - CAP-INT-ADP-008 - CAP-INT-ADP-015 - CAP-INT-ADP-017 - CAP-INT-ADP-027 - CAP-INT-ADP-028 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.md#M2-D7' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#A1' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#A2' - '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-S05' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S06' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S07' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S08' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S12' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S13' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S14' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S19' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S20' purpose: Applications perform provider operations through a recorded call with safeguards against unsafe repetition. outcomes: - 'Call history includes the execution, its attempts and selected binding.' - Repeated identical requests reuse the existing result. - Admission controls protect providers and stop payments that cannot run within their budget. concepts: - CON-PFM-INT-003 actors: - ACT-PFM-020 - ACT-PFM-017 - ACT-PFM-006 surfaces: - api - job preconditions: [] postconditions: [] permissions: - key: platform.integrations.invoke where_checked: api scope: tenant - key: platform.integrations.invoke where_checked: service scope: tenant rules: - id: BR-CAP-PFM-INT-009-01 proved_by: [ATS-PFM-INT-009-01, TST-PFM-INT-580] statement: >- Before recording an execution, the gateway rejects requests over one megabyte, contract violations, unsupported modes, missing required idempotency keys, keys with surrounding whitespace and excessive timeout requests. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/unit/services/gateway-refusals.spec.ts#refuses a request the contract refuses, invalid_request with the failing path origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S20' - id: BR-CAP-PFM-INT-009-02 proved_by: [ATS-PFM-INT-009-02, TST-PFM-INT-543, TST-PFM-INT-580] statement: >- Application principals invoke only for their own application except Platform, while a console caller needs invoke authority and the capability’s permission. kind: permission enforced_at: - api - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/unit/services/gateway-refusals.spec.ts#refuses a service principal naming another application, access_denied origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S19' - id: BR-CAP-PFM-INT-009-03 proved_by: [ATS-PFM-INT-009-03, ATS-PFM-INT-009-19, TST-PFM-INT-543] statement: >- Idempotency keys distinguish calls within a workspace and capability: identical pending calls return in progress, settled calls replay their first response and changed requests conflict; cancellation or admission refusal releases the key. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/unit/services/execution-idempotency.spec.ts#replays the stored answer of a succeeded execution, exactly origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S06' - id: BR-CAP-PFM-INT-009-04 proved_by: [ATS-PFM-INT-009-04, ATS-PFM-INT-009-18, ATS-PFM-INT-012-08, TST-PFM-INT-543, TST-PFM-INT-579] statement: >- An execution records attempts, request fingerprint, serving binding and connection and scalar summaries within four kilobytes that exclude secrets and personal or payment-instrument details; the provider uses the execution identifier for idempotency. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/invoke-capability.integration.spec.js#records the execution succeeded, with its digest, summaries, reference and one attempt origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#A2' - id: BR-CAP-PFM-INT-009-05 proved_by: [ATS-PFM-INT-009-05, ATS-PFM-INT-009-13, ATS-PFM-INT-009-15, ATS-PFM-INT-010-11, TST-PFM-INT-481, TST-PFM-INT-543] statement: >- Immediate retries reuse the execution at one, four and sixteen seconds within the caller budget for unavailability, rate limits or pre-send timeouts, and retry adapter errors once; declines, refusals and unknown post-send outcomes are not repeated. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/invoke-capability.integration.spec.js#retries a timeout before send after the sync schedule’s first delay, with the same execution id, and succeeds origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D4' - id: BR-CAP-PFM-INT-009-06 proved_by: [ATS-PFM-INT-009-06, ATS-PFM-INT-009-13, TST-PFM-INT-481, TST-PFM-INT-543, TST-PFM-INT-583] statement: >- A sensitive call that cannot retry within its budget settles failed, frees the key and queues nothing, while a non-sensitive call can continue asynchronously. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/invoke-capability.integration.spec.js#queues no continuation and nudges no dispatcher, so nothing runs in the background origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#A1' - id: BR-CAP-PFM-INT-009-07 proved_by: [ATS-PFM-INT-005-14, ATS-PFM-INT-007-13, ATS-PFM-INT-008-10, ATS-PFM-INT-009-07, ATS-PFM-INT-009-17, TST-PFM-INT-481, TST-PFM-INT-543] statement: >- Each attempt passes circuit, rate and credential admission; refusal returns the appropriate retry or re-authorization information, never switches connections and releases the unused key. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/invoke-capability.integration.spec.js#refuses with 503 provider_unavailable while the circuit is open, and releases the key origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#A3' - id: BR-CAP-PFM-INT-009-08 proved_by: [ATS-PFM-INT-009-08, ATS-PFM-INT-009-14] statement: >- Five consecutive provider-unavailable or timeout outcomes open the connection circuit for sixty seconds; one probe follows, failed probes double the wait up to fifteen minutes and success closes it. kind: calculation enforced_at: - service must_prove: true provenance: documented source: 'services-platform:docs/integrations/README.md#Circuits (13 §10)' origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D4' - id: BR-CAP-PFM-INT-009-09 proved_by: [ATS-PFM-INT-009-09, ATS-PFM-INT-009-13, TST-PFM-INT-540, TST-PFM-INT-543] statement: >- Asynchronous invocation returns acceptance before provider contact and uses six queued attempts with delays of one, five and thirty minutes, two hours and six hours. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/invoke-capability.integration.spec.js#answers 202 accepted and queues the first attempt with the execution, calling no adapter origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D4' - id: BR-CAP-PFM-INT-009-10 proved_by: [ATS-PFM-INT-009-10, ATS-PFM-INT-009-13, ATS-PFM-INT-009-16, TST-PFM-INT-542] statement: >- An execution permits at most ten attempts including operator retries; a requested retry at ten is refused and an eleventh queued attempt settles failed with key release. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/execution-settlement.integration.spec.js#settles an execution whose next attempt is the eleventh failed, with the last class and retry_exhausted.attempt_limit origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D4' - id: BR-CAP-PFM-INT-009-11 proved_by: [ATS-PFM-INT-009-11, TST-PFM-INT-544, TST-PFM-INT-576] statement: >- Opted-in non-sensitive payloads are redacted, truncated at one megabyte and retained for thirty days, while sensitive payloads are never recorded and storage failure does not fail the call. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/payload-recording.integration.spec.js#writes nothing for a sensitive capability, though the manifest records payloads origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D7' - id: BR-CAP-PFM-INT-009-12 proved_by: [] statement: >- Provider rate declarations govern admission, operator overrides can lower them and retry-after drains the bucket for the requested wait; immediate calls receive a retry time and queued calls wait. kind: calculation enforced_at: - service must_prove: false provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/invoke-capability.integration.spec.js#honours a provider’s retry_after before the next attempt, and records the bucket’s refill origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D4' - id: BR-CAP-PFM-INT-009-13 proved_by: [ATS-PFM-INT-009-12] statement: Stored gateway request keys contain at most one hundred and twenty-eight characters. kind: validation enforced_at: - database must_prove: true provenance: observed source: >- services-platform:modules/integrations/db/integration-execution-keys.table.ts:integration_execution_keys_key_check origin: none scenarios: - id: SC-CAP-PFM-INT-009-01 given: A test payment for one hundred and twenty dollars encounters two provider-unavailable results. when: Accounting authorizes through the gateway. then: The third attempt succeeds about five seconds after the first under the same execution. provenance: test source: >- services-platform:modules/integrations/tests/e2e-adapters/gateway-dummy.adapters.spec.js#honours the provider’s retry_after of one second, then succeeds (04) - id: SC-CAP-PFM-INT-009-02 given: The selected processor’s circuit is open. when: A payment is requested for its merchant account. then: Admission reports provider unavailability without contacting another processor. provenance: test source: >- services-platform:modules/integrations/tests/e2e-adapters/gateway-dummy.adapters.spec.js#touches no processor: neither the open one nor another edge_cases: [] constraints: [] depends_on: - CAP-PFM-INT-008 - CAP-PFM-INT-005 related: - CAP-PFM-INT-010 - CAP-PFM-INT-011 journeys: - JNY-PFM-INT-003 open_questions: [] evidence: - >- services-platform source inventory: modules/integrations/services/executions/invoke-capability.ts, attempt-loop.ts, idempotency.ts, refusals.ts, circuit-store.ts, rate-limits.ts, payload-recording.ts, dispatcher.ts, summaries.ts; aws/api/gateway.routes.ts, executions.routes.ts; rule-level automated test references; docs/integrations/README.md (The runtime); docs/milestones/INTG-M2-* (M2-D4, M2-D7, A1 to A3). - 'macroservice-libraries source inventory: packages/integration-contracts (envelope, errors, capabilities).' - 'react-console source inventory: acceptance/integrations/coverage/intg-m2-scenarios.json.' - 'Operation coverage: invokeIntegrationCapability, invokeIntegrationCapabilityFromConsole.' - >- Persistent record coverage: integration_executions, integration_execution_attempts, integration_execution_responses, integration_execution_keys, integration_execution_dispatches, integration_circuit_states, integration_rate_limits. - 'End-to-end definition inventory: gateway-dummy.adapters.spec.js.' controls: [TC-AVL-001, TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, 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-03-01, FAS-PFM-INT-03-02, FAS-PFM-INT-03-03, FAS-PFM-INT-03-04, FAS-PFM-INT-03-05] suites: [TST-PFM-INT-481, TST-PFM-INT-540, TST-PFM-INT-542, TST-PFM-INT-543, TST-PFM-INT-544, TST-PFM-INT-576, TST-PFM-INT-579, TST-PFM-INT-580, TST-PFM-INT-583] --- # Run provider operations safely through the gateway ## Purpose Applications perform provider operations through a recorded call with safeguards against unsafe repetition. ## How It Works An application submits a contract-shaped request to the gateway. The gateway authorizes the caller, selects a connection and records the operation. It uses the execution as the continuing identity across safe attempts. Existing-key requests return the existing state or answer instead of creating another provider operation. Admission can hold a provider off before delivery. Failures are classified before deciding whether to wait, retry or investigate. Queued work continues non-sensitive operations that cannot finish immediately. Optional payload records support diagnosis where the contract permits them. The product should keep retry controls subordinate to whether the original operation may already have happened. ## Relationships - Requires explain and select the connection for a call to supply the prerequisite configuration or operation. - Requires protect credentials throughout their useful life to supply the prerequisite configuration or operation. - Connects with determine the result of uncertain or overdue calls through shared integration records. - Connects with inspect calls and resolve operational problems through shared integration records.