--- id: WF-PFM-INT-011 title: Invoke a capability through the gateway trigger: The initiating calling application starts this flow. product_area: platform module: integrations revision: 1 status: draft design_intent: confirmed implementation_evidence: observed origin: >- docs/milestones/INTG-M2-calls-through-the-gateway.md#Decisions M2-D1, M2-D4 (Andrew); docs/integrations/README.md#The pipeline (13 §5) (Andrew 2026-10-19 decisions 1 and 2) inference: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f implements: - CAP-PFM-INT-009 - CAP-PFM-INT-008 - CAP-PFM-INT-012 moves: - STATE-PFM-INT-007 - STATE-PFM-INT-008 crosses: [] idempotency: >- Request keys return the existing execution or saved answer, reject changed input and can be reused after permitted key release. concurrency: >- Key claiming and execution acceptance commit together; shared permits govern rate admission and circuit reads can use a five-second local cache. hops: - 'n': 1 actor_or_service: Calling application action: 'Submit the capability contract, context, request and key, with an explicit account when needed.' anchor: 'services-platform:modules/integrations/services/executions/invoke-capability.ts:invokeCapability' seam: sync on_failure: Return request refusal to the caller. left_inconsistent: Rejected requests create no provider work. observer: The caller provenance: observed source: 'services-platform:modules/integrations/services/executions/invoke-capability.ts:invokeCapability' - 'n': 2 actor_or_service: Gateway action: >- Validate request size and contract, mode, key and budget and authorize the service’s application or console actor. anchor: 'services-platform:modules/integrations/services/executions/invoke-capability.ts:invokeCapability' seam: sync on_failure: Reject invalid or unauthorized input. left_inconsistent: No execution is accepted. observer: The caller provenance: observed source: 'services-platform:modules/integrations/services/executions/invoke-capability.ts:invokeCapability' - 'n': 3 actor_or_service: Gateway action: 'Resolve scopes from most specific outward or validate the named account, retaining the selection trace.' anchor: 'services-platform:modules/integrations/services/bindings/resolve.ts:resolveBinding' seam: sync on_failure: A sensitive or refuse-policy failure stops the scope search. left_inconsistent: No provider has been contacted during resolution. observer: The caller and the Explain screen provenance: observed source: 'services-platform:modules/integrations/services/bindings/resolve.ts:resolveBinding' - 'n': 4 actor_or_service: Gateway action: >- Commit the accepted execution with its request fingerprint and key claim; return existing progress, replay or conflict for a repeat. anchor: 'services-platform:modules/integrations/services/executions/idempotency.ts' seam: sync on_failure: Return the existing-key decision or rollback database failure. left_inconsistent: One claimed identity remains associated with its execution. observer: Activity provenance: observed source: 'services-platform:modules/integrations/services/executions/idempotency.ts' - 'n': 5 actor_or_service: Gateway action: >- Check circuit and rate admission, lease credentials, start the attempt record and deliver a deadline-bound adapter envelope. anchor: 'services-platform:modules/integrations/services/executions/attempt-loop.ts' seam: sync on_failure: Fail refused admission and release the unused request key. left_inconsistent: Admission refusal sends nothing to the provider. observer: Activity and Needs Attention provenance: observed source: 'services-platform:modules/integrations/services/executions/attempt-loop.ts' - 'n': 6 actor_or_service: Adapter action: Invoke provider work through the adapter with the execution identity used for provider deduplication. anchor: 'services-platform:modules/integrations/services/transport/adapter-transport.ts' seam: sync on_failure: Classify failure by whether delivery may have reached the provider. left_inconsistent: An uncertain answer can leave a real provider effect without a settled result. observer: Activity provenance: observed source: 'services-platform:modules/integrations/services/transport/adapter-transport.ts' - 'n': 7 actor_or_service: Gateway action: >- Store results, retry safe pre-send failures within budget, investigate post-send uncertainty and queue only eligible non-sensitive continuation. anchor: 'services-platform:modules/integrations/services/executions/settle-execution.ts:settleExecution' seam: sync on_failure: A competing settlement can win the status compare-and-set. left_inconsistent: >- Uncertain executions wait for investigation; optional notice recording does not determine provider success. observer: Activity and the caller provenance: observed source: 'services-platform:modules/integrations/services/executions/settle-execution.ts:settleExecution' branches: - condition: A test call from the Library path: >- The connection must report a test environment, be usable and verified for the capability; the call bypasses bindings and is recorded with the person. - condition: An asynchronous call path: Recording answers accepted at once and the dispatcher continues the work through the queue. evidence: - >- services-platform at ad3f6a65: modules/integrations/services/executions/invoke-capability.ts, attempt-loop.ts, idempotency.ts, settle-execution.ts, try-connection.ts; services/bindings/resolve.ts, eligibility.ts; docs/integrations/README.md (The pipeline; Idempotency) - >- services-platform:modules/integrations/tests/unit/services/gateway-refusals.spec.ts#refuses a request the contract refuses, invalid_request with the failing path - >- services-platform:modules/integrations/tests/unit/services/gateway-refusals.spec.ts#refuses a service principal naming another application, access_denied - >- 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 - >- services-platform:modules/integrations/tests/unit/services/execution-idempotency.spec.ts#replays the stored answer of a succeeded execution, exactly - >- 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 - >- 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 - >- 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 controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, 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-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, 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-MON-002, TC-PI-001, TC-PI-002, TC-PI-003, 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] --- # Invoke a capability through the gateway ## What It Does The gateway authorizes a provider-independent request, explains account selection and retains one execution before calling the adapter. Admission checks precede provider delivery. Classified results determine settlement, safe retry, queued continuation or investigation. ## The Flow ```mermaid sequenceDiagram participant P0 as Calling application participant P1 as Gateway participant P2 as Adapter P0->>P0: 1. Submit the capability contract P1->>P1: 2. Validate request size and contract P1->>P1: 3. Resolve scopes from most specific outward or validate the named account P1->>P1: 4. Commit the accepted execution with its request fingerprint and key claim P1->>P1: 5. Check circuit and rate admission P2->>P2: 6. Invoke provider work through the adapter with the execution identity used for provider deduplication. P1->>P1: 7. Store results ``` ## When Something Fails Return request refusal to the caller. Rejected requests create no provider work. Reject invalid or unauthorized input. No execution is accepted. A sensitive or refuse-policy failure stops the scope search. No provider has been contacted during resolution. Return the existing-key decision or rollback database failure. One claimed identity remains associated with its execution. Fail refused admission and release the unused request key. Admission refusal sends nothing to the provider. Classify failure by whether delivery may have reached the provider. An uncertain answer can leave a real provider effect without a settled result. A competing settlement can win the status compare-and-set. Uncertain executions wait for investigation; optional notice recording does not determine provider success. ## Open Design Questions Full concurrent admission and breaker behavior still need proof, and the gateway milestone retains recorded defects.