API Evangelist enrichment overlay for the Silverflow API

overlay: 1.0.0
info:
  title: API Evangelist enrichment overlay for the Silverflow API
  version: 1.0.0
x-provenance:
  generated: '2026-08-27'
  method: generated
  source: openapi/silverflow-openapi.yml
  extends: openapi/silverflow-openapi.yml
  note: >-
    Non-destructive overlay carrying API Evangelist's enrichment findings back onto Silverflow's
    published contract. It asserts nothing Silverflow does not already document — every action
    below annotates an operation or component that exists in the spec, using facts sourced from
    Silverflow's own guides. The original spec is never mutated. Applying this overlay is
    optional; its purpose is to make runtime semantics (idempotency, reversibility, retry,
    pagination) legible to a code generator or an agent that reads only the contract.
actions:
- target: $.info
  description: Record the enrichment provenance and the runtime-semantics artifacts on the
    document root.
  update:
    x-apievangelist-enrichment:
      profiled: '2026-08-27'
      conventions: conventions/silverflow-conventions.yml
      errors: errors/silverflow-problem-types.yml
      decline_codes: errors/silverflow-decline-codes.yml
      lifecycle: lifecycle/silverflow-lifecycle.yml
      events: asyncapi/silverflow-events-webhooks.yml
      data_model: data-model/silverflow-data-model.yml
      conformance: conformance/silverflow-conformance.yml
- target: $
  description: Declare the cross-cutting runtime semantics Silverflow documents in prose but
    does not express in the contract.
  update:
    x-runtime-semantics:
      idempotency:
        header: Idempotency-Key
        retention_hours: 24
        match_scope: full URL + byte-identical request body INCLUDING JSON attribute order
        fails_open: true
        source: https://docs.silverflow.com/guides/idempotency
      conditional_updates:
        header: If-Match
        value: ETag response header or the object's `version` attribute
        conflict_status: 412
        source: https://docs.silverflow.com/guides/idempotency
      pagination:
        style: cursor
        params: [limit, offsetToken, sortOrder]
        limit_default: 10
        limit_max: 100
        terminator: absence of offsetToken in the response
        source: https://docs.silverflow.com/guides/pagination
      errors:
        standard: RFC 7807
        media_type: application/json
        deviation: not application/problem+json
        type_namespace: /silverflow/problems/
        source: https://docs.silverflow.com/guides/error-handling
      retry:
        retriable_status_codes: [429, 502, 503, 504]
        retry_after_header: Retry-After
        source: https://docs.silverflow.com/guides/error-handling
      events:
        envelope: CloudEvents 1.0
        delivery: at-least-once, unordered, thin payload
        dedup_key: id
        signature_verification: not documented
        source: https://docs.silverflow.com/guides/event-notifications
- target: $.components.securitySchemes.MutualTLS
  description: >-
    Flag the mTLS scheme modelling defect. OpenAPI 3.0.3 has no `mutualTLS` type, so Silverflow
    declared it as `type: apiKey, in: header, name: '-'`, which makes a generator emit a bogus
    header parameter named '-'. Annotated rather than corrected, because rewriting the type
    would break 3.0.3 validity.
  update:
    x-actual-type: mutualTLS
    x-modelling-note: Declared as apiKey because OpenAPI 3.0.3 predates the mutualTLS scheme
      type. Clients must not send a header named '-'; they must present an X.509 client
      certificate at the TLS handshake.
    x-upgrade-path: 'On a move to OpenAPI 3.1, replace with `type: mutualTLS`.'
- target: $.paths['/charges/{chargeKey}/reverse'].post
  description: Record the reversal window so an agent can tell before calling whether this is
    the right undo operation.
  update:
    x-reversal-of: authorization
    x-window: while clearingMode = manual AND the charge is not yet cleared
    x-on-window-expiry: use POST /charges/{chargeKey}/refund
    x-source: https://docs.silverflow.com/guides/charge-actions
- target: $.paths['/charges/{chargeKey}/cancel'].post
  description: Record the cancel window, including the one explicit clock-based boundary in the
    charge surface.
  update:
    x-reversal-of: scheduled clearing + authorization
    x-window: while clearingMode = auto AND the charge is not yet sent for clearing; where the
      charge carries `clearAfter`, up until that timestamp
    x-on-window-expiry: >-
      HTTP 409 /silverflow/problems/charge/clearing-already-submitted; use
      POST /charges/{chargeKey}/refund
    x-source: https://docs.silverflow.com/guides/charge-actions
- target: $.paths['/charges/{chargeKey}/refund'].post
  description: Record that the refund window is unbounded in Silverflow's own documentation.
  update:
    x-reversal-of: a cleared charge
    x-window-stated: false
    x-window-note: Silverflow publishes no maximum refund age; the card networks' own rules
      apply and are not restated in the contract.
    x-source: https://docs.silverflow.com/guides/charge-actions
- target: $.paths['/disputes/{disputeKey}/accept'].post
  description: Mark the one-way door on the dispute surface.
  update:
    x-irreversible: true
    x-warning: Accepting a dispute concedes the chargeback. There is no un-accept operation and
      the terminal state is closedAccepted. Never call speculatively.
    x-recoverable-alternative: POST /disputes/{disputeKey}/defend
- target: $.components.parameters.IdempotencyKey
  description: Make the strict byte-match requirement visible at the parameter, not only in the
    guide.
  update:
    x-retention-hours: 24
    x-match-scope: full URL + byte-identical request body INCLUDING JSON attribute order
    x-mismatch-response: '409 /silverflow/problems/idempotency/request-mismatch'
    x-in-flight-response: '409 /silverflow/problems/idempotency/request-is-still-being-processed'
    x-fails-open: Silverflow processes the request WITHOUT idempotency if its idempotency store
      is unavailable, so this header is not an absolute exactly-once guarantee.
    x-source: https://docs.silverflow.com/guides/idempotency
- target: $.components.schemas.isoFieldResponseCode
  description: Name the standard the field belongs to, so a consumer knows whose registry
    defines its values.
  update:
    x-standard: ISO 8583 field 39
    x-registry-owner: the card network named in authorizationResponse.network — values differ
      per network
    x-documented-values: errors/silverflow-decline-codes.yml