--- id: CON-PFM-INT-003 name: Capability Call feature: FEAT-PFM-INT-03 product_area: platform module: integrations revision: 1 status: draft product_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A capability call is a recorded request for a provider operation through Rhythm’s gateway, with its selected account, attempts and eventual outcome. owned_by: MOD-PFM-INT synonyms: - Execution - Gateway call - Invocation not_to_be_confused_with: - Application customization execution - Host-owned configured action execution facets: - name: Capability and contract meaning: >- A capability contract describes the request, response, major, execution mode, budget and sensitivity of the provider job. used_for: Validating an operation before provider delivery. - name: Binding meaning: A scope-specific connection choice retains the workspace’s routing decision and revision history. used_for: Separating business context from provider selection. - name: Resolution trace meaning: The explanation records considered scopes and eligibility results. used_for: Understanding selection and configuration refusals. - name: Idempotency key meaning: A caller-supplied request identity links repeated submissions to one recorded operation. used_for: Reusing results and refusing changed requests under the same identity. - name: Attempt meaning: Each provider delivery attempt records timing and a classified result within the continuing execution. used_for: Choosing safe retries and explaining failures. - name: Outcome and settlement meaning: >- The execution retains success, failure, cancellation or uncertainty and records one committed settlement. used_for: Supplying the applicable completion result to the invoking application. - name: Lookup and needs attention meaning: 'Provider lookup investigates uncertain results, with unresolved cases becoming manual attention.' used_for: Avoiding resubmission of work that might already have happened. - name: Recorded payloads and archive meaning: 'Permitted diagnostics hold redacted payload references, while older executions use archive read-through.' used_for: Supporting investigation beyond the online retention period. - name: Test call meaning: The Library can initiate a real gateway operation on a provider-reported test account. used_for: Checking provider behaviour before relying on the account. relationships: - to: CON-PFM-INT-002 statement: An execution selects one connection and borrows authentication for its provider attempt. provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/invoke-capability.integration.spec.js#hands the adapter the execution id, the lease and the callback, and stores no credential - to: CON-PFM-INT-001 statement: The selected release and accepted installation access constrain bound capability calls. provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/consent-narrowing.integration.spec.js#INT-ACC-0509 step 4: refuses the refund 409 binding_ineligible - to: CON-PFM-INT-004 statement: Applicable asynchronous settlement produces an integration completion event. provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/execution-settlement.integration.spec.js#is written when the queue consumer settles an async execution lifecycle: - state: accepted or running meaning: The operation is recorded for immediate or queued work. how_it_changes: 'An attempt, cancellation, retry or uncertain result advances it.' - state: retrying meaning: Another provider attempt is pending. how_it_changes: 'Attempt execution, exhaustion or timeout decides its next state.' - state: unknown meaning: Provider delivery may have occurred without a known result. how_it_changes: Lookup establishes an outcome or leads to attention. - state: needs attention meaning: Automatic investigation is exhausted. how_it_changes: An authorized operator records the result. - state: 'succeeded, failed or cancelled' meaning: The execution has a retained final outcome. how_it_changes: Settlement remains final; a retained idempotency key reuses it. acted_on_by: - CAP-PFM-INT-007 - CAP-PFM-INT-008 - CAP-PFM-INT-009 - CAP-PFM-INT-010 - CAP-PFM-INT-011 - CAP-PFM-INT-012 visible_to: - ACT-PFM-017 - ACT-PFM-018 - ACT-PFM-019 - ACT-PFM-020 - ACT-PFM-021 - ACT-PFM-006 evidence: - >- services-platform source inventory: modules/integrations/services/bindings/*, services/executions/*, services/adapter-callbacks/adapter-callbacks.ts, db/integration-bindings.table.ts, integration-executions.table.ts and the execution tables; docs/integrations/README.md (Bindings, The runtime); docs/milestones/INTG-M2-*. - >- macroservice-libraries source inventory: packages/integration-contracts (capabilities, envelope, binding-policies, errors). - >- react-console source inventory: components/integrations/bindings-screen.tsx, resolution-explain.tsx, activity-screen.tsx, execution-detail.tsx, try-a-call.tsx. supersedes: [] --- # Capability Call ## What It Is A capability call is the continuing record of one requested provider operation. An application asks for a business job, such as authorizing a payment, using a shared contract. The gateway selects an account, attempts the job and retains the result or the uncertainty that remains. Staff see that continuing record as an execution in Activity. The execution distinguishes the request from each attempt made to deliver it. That distinction matters when a provider is temporarily unavailable or when an answer is lost after delivery. A request identity supplied by the caller connects repeated submissions to the existing operation. The execution identity then follows provider attempts and investigation. A product manager can use this model to ask whether another attempt is safe without assuming that an unanswered request failed. ## What It Is Not A call is different from the invoice, payment or meeting record that motivates it. The owning application remains responsible for that business record and for interpreting completion. An extension invocation supplies customized application behaviour, and a workflow action run records configured work in its host. Either may cause provider work, but its record does not replace the gateway execution. ## How It Is Used Applications use the gateway so business code can request a capability without choosing a provider implementation itself. Administrators configure the account choices and use Explain to investigate selection. Operators inspect execution detail when a call fails or remains uncertain, comparing the attempts, summaries and provider references. Good operational practice distinguishes an admission refusal from work that may have reached the provider. The former can release an unused request identity; the latter needs investigation. A person who checks the provider’s dashboard can record the result when automatic investigation is exhausted. The Library’s test panel creates the same kind of execution, with a test-account boundary and an initiating person. ## Its Facets **Capability contract and binding.** The contract defines the request and result, while a scope-specific choice supplies the provider account. These are separate inputs to a call. **Trace and request identity.** The trace explains selection checks. The idempotency key links repeat requests to the retained operation and distinguishes changed input. **Attempts.** Delivery timing and classified outcomes guide safe repetition. Multiple attempts still belong to one execution. **Settlement and investigation.** Unknown outcomes use provider lookup. Exhausted investigation becomes a manual task, and settlement supplies one applicable completion event. **Diagnostics and archive.** Safe summaries remain with execution records. Optional payload capture and older-record read-through support support work without making retained payloads a source for console retries. **Test calls.** Provider-reported test accounts let administrators see actual gateway work without treating the Library as a general business-operation screen. ## How It Relates The selected connection supplies authentication and a provider implementation. Its installation acceptance limits supported access. Completion travels as an integration event back to the application that initiated the call. A workflow action may request a provider job, but the host’s action record remains its explanation for why that call was made. ## What It Could Become The product should prove concurrent admission, uncertain-outcome settlement and complete circuit opening before relying on a sourced description as operational acceptance. Retry remains disabled in the console because the application owns the original request. Archive expiry and some staff controls are unresolved. The gateway milestone has approved intent and open defects, so documented or observed behaviour does not yet mean that the milestone is accepted.