--- id: DOM-PFM-INT-003 title: Capability Call realises: CON-PFM-INT-003 product_area: platform module: integrations revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-PFM-INT-integrations lifecycle: - STATE-PFM-INT-006 - STATE-PFM-INT-007 custom_fields: none identity: >- A generated execution identifier locates the call in its monthly partition and accompanies provider idempotency and investigation. The caller’s request key is unique for a capability within a workspace. Binding history continues the numbering at a capability major and scope. attributes: - name: capability and contract major kind: reference required: true computed: false notes: The shared contract defines the requested operation and supported major. - name: binding kind: document required: false computed: false notes: >- A binding selects an account at record, business-unit, application or workspace scope with required features, policy, revision and status. - name: binding revisions kind: collection required: true computed: true notes: 'Scope changes append immutable snapshots, retaining up to two hundred recent revisions.' - name: caller kind: document required: true computed: false notes: 'Caller attribution includes the application or console actor, subject and selection context.' - name: serving facts kind: document required: true computed: false notes: 'The execution records the binding revision, account, release, deployment and selection explanation.' - name: idempotency key and request fingerprint kind: text required: false computed: false notes: >- A supplied request key accompanies a canonical-input fingerprint; execution records do not retain an original request for console retry. - name: mode and standing kind: enum required: true computed: false notes: >- Synchronous or asynchronous mode is separate from accepted, running, retrying, uncertain, attention or settled status. - name: attempts kind: collection required: true computed: false notes: >- Attempt records retain timing, outcome, error classification, provider request reference and optional diagnostic reference. - name: summaries kind: document required: false computed: false notes: >- Scalar summaries are limited to four kilobytes and exclude secret, personal and payment-instrument information. - name: stored answer kind: document required: false computed: false notes: The response store retains the first answer for replay to an identical request. - name: settling facts kind: document required: false computed: true notes: Derived investigation information shows the next lookup and whether automatic settlement has stopped. - name: archive marker kind: boolean required: false computed: true notes: Archive reads mark records moved beyond the thirteen-month online retention window. relationships: - to: DOM-PFM-INT-002 cardinality: Each served call and each binding name one connection. ownership: Calls and bindings refer to the account without owning its record. cross_service: false - to: DOM-PFM-INT-001 cardinality: A call retains the release and deployment used and respects accepted installation capabilities. ownership: Execution reads the catalogue and installation without modifying them. cross_service: false - to: DOM-PFM-INT-004 cardinality: An asynchronous or unanswered call can produce its applicable completion event at settlement. ownership: 'The event store owns that event, written within the settlement transaction.' cross_service: false invariants: - id: INV-DOM-PFM-INT-003-01 statement: 'A capability major and scope have one current binding, and replacing it increases the revision.' enforced_at: - service - database provenance: test source: >- services-platform:modules/integrations/tests/integration/services/persistence/integration-bindings.integration.spec.js#leaves one active binding at the scope - id: INV-DOM-PFM-INT-003-02 statement: A binding mutation appends a revision snapshot that application writers cannot alter. enforced_at: - service - database provenance: test source: >- services-platform:modules/integrations/tests/integration/db/integration-binding-revisions.table.integration.spec.js#refuses an UPDATE of a revision by the application role, so a history cannot be rewritten - id: INV-DOM-PFM-INT-003-03 statement: >- Within a workspace and capability, a request key returns its pending execution or retained result and refuses changed input. enforced_at: - service - database provenance: test source: >- services-platform:modules/integrations/tests/unit/services/execution-idempotency.spec.ts#replays the stored answer of a succeeded execution, exactly - id: INV-DOM-PFM-INT-003-04 statement: >- Provider attempts use the execution identifier for idempotency; work that may have reached the provider is investigated without resending. enforced_at: - service 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 - id: INV-DOM-PFM-INT-003-05 statement: >- Safe retries of a money operation stop when the synchronous budget is spent, failing the call without queued continuation and releasing its key. enforced_at: - service 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 - id: INV-DOM-PFM-INT-003-06 statement: 'The execution cannot exceed ten attempts, including attempts an operator requests.' enforced_at: - service 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 - id: INV-DOM-PFM-INT-003-07 statement: Settlement commits its result with at most one applicable completion event. enforced_at: - service provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/execution-settlement.integration.spec.js#is written once for two settlements that both read the execution running, the loser moving nothing - id: INV-DOM-PFM-INT-003-08 statement: An open circuit appears in the selection trace without rerouting the call to a different account. enforced_at: - service 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 - id: INV-DOM-PFM-INT-003-09 statement: Resolution reads current workspace records within a read-only transaction on every request. enforced_at: - service 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 - id: INV-DOM-PFM-INT-003-10 statement: A person records an investigation outcome without contacting the provider or reversing its work. enforced_at: - service provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/reconciler.integration.spec.js#lets an operator resolve a needs_attention execution by hand, audited, with no call to the provider readable_by: - SVC-PFM-INT-integrations physical: - platform.integration_bindings - platform.integration_binding_revisions - platform.integration_executions - platform.integration_execution_attempts - platform.integration_execution_responses - platform.integration_execution_keys - platform.integration_execution_dispatches evidence: - >- services-platform at ad3f6a65: modules/integrations/db/integration-bindings.table.ts, integration-binding-revisions.table.ts, integration-executions.table.ts, integration-execution-*.table.ts; services/bindings/*; services/executions/* - >- services-platform at ad3f6a65: docs/integrations/README.md (Bindings; The runtime); docs/milestones/INTG-M2-calls-through-the-gateway.md (Decisions M2-D2 to M2-D9) - >- macroservice-libraries at 54536a44: packages/integration-contracts (envelope, binding policies, capabilities) --- # Capability Call ## What It Models A capability call retains one provider request across attempts and later investigation. It explains who asked, how the account was selected, what was sent at a safe summary level and whether the provider completed the work. Bindings are a facet of this object because they supply the account choice recorded by each execution. ## Identity and Attributes A generated execution identifier locates the call in its monthly partition and accompanies provider idempotency and investigation. The caller’s request key is unique for a capability within a workspace. Binding history continues the numbering at a capability major and scope. The shared contract defines the requested operation and supported major. A binding selects an account at record, business-unit, application or workspace scope with required features, policy, revision and status. Scope changes append immutable snapshots, retaining up to two hundred recent revisions. Caller attribution includes the application or console actor, subject and selection context. The execution records the binding revision, account, release, deployment and selection explanation. A supplied request key accompanies a canonical-input fingerprint; execution records do not retain an original request for console retry. Synchronous or asynchronous mode is separate from accepted, running, retrying, uncertain, attention or settled status. Attempt records retain timing, outcome, error classification, provider request reference and optional diagnostic reference. Scalar summaries are limited to four kilobytes and exclude secret, personal and payment-instrument information. The response store retains the first answer for replay to an identical request. Derived investigation information shows the next lookup and whether automatic settlement has stopped. Archive reads mark records moved beyond the thirteen-month online retention window. ## Relationships Each served call and each binding name one connection.. Calls and bindings refer to the account without owning its record.. A call retains the release and deployment used and respects accepted installation capabilities.. Execution reads the catalogue and installation without modifying them.. An asynchronous or unanswered call can produce its applicable completion event at settlement.. The event store owns that event, written within the settlement transaction.. ## Invariants A capability major and scope have one current binding, and replacing it increases the revision. A binding mutation appends a revision snapshot that application writers cannot alter. Within a workspace and capability, a request key returns its pending execution or retained result and refuses changed input. Provider attempts use the execution identifier for idempotency; work that may have reached the provider is investigated without resending. Safe retries of a money operation stop when the synchronous budget is spent, failing the call without queued continuation and releasing its key. The execution cannot exceed ten attempts, including attempts an operator requests. Settlement commits its result with at most one applicable completion event. An open circuit appears in the selection trace without rerouting the call to a different account. Resolution reads current workspace records within a read-only transaction on every request. A person records an investigation outcome without contacting the provider or reversing its work. ## How It Is Stored and Shared The integrations service owns bindings, execution partitions, attempts, key records, dispatch work and stored responses. Separate key records preserve request uniqueness across monthly partitions. Optional diagnostic payloads and archives use object storage; an application receives results through the gateway and completion events. Custom fields are not enabled. ## Open Design Questions Concurrent admission and the full circuit threshold still lack complete proof. Archived execution expiry is undecided. Investigation uses the account’s current release, so an upgrade during an uncertain call can change the adapter that looks it up.