# Adapter Schema Contract

**Status:** Approved target-state baseline  
**First realization:** I0.

## Provider Descriptor

Each adapter exposes provider identity/version and capabilities using AWP-owned schema:

```text
ProviderDescriptor {
  providerId
  kind
  adapterVersion
  capabilities[]
  authModes[]
  resourceTypes[]
  healthFeatures[]
}
```

Capability shape is provider-kind specific but avoids exposing raw SDK classes.

## Operation Context

Provider mutation inputs include:

```text
operationId / idempotencyKey
correlationId
Principal/system authority context (not user-supplied arbitrary claims)
Connection/CredentialReference handle
resource/provider mappings
AWP target IDs/revisions
requested capability/options
```

## Normalized Result

A result carries provider references, normalized state/output, observation time and reconciliation token/revision when available. It does not directly mutate unrelated domain aggregates.

## Error Schema

```text
ProviderError {
  category:
    unavailable | rate-capacity | auth | permission | missing-resource |
    unsupported-capability | conflict-stale | terminal-provider |
    adapter-protocol
  retryable
  providerId
  accountId?
  resourceRef?
  safeMessage/details
  observedAt
}
```

## Reconciliation Contract

Every side-effecting adapter operation that can outlive a request defines a reconcile/read-back function keyed by operation/provider reference. Timeout/unknown result triggers reconcile before duplicate mutation.

## Cancellation

Long-running supported operations expose cancel semantics and post-cancel reconciliation. `cancel requested` is not the same as provider resource confirmed gone/stopped.

## Event/Webhook Contract

Adapter verifies provider origin and converts payload into `ProviderObservation` before application reconciliation. Raw webhook cannot directly become domain state.

## Compatibility

Internal adapter interfaces are versioned with AWP source. Public third-party adapter SDK only becomes stable when I9 declares the boundary, at which point semantic versioning/R4 compatibility applies.

## Increment Realization

I0 implements baseline interfaces and provider descriptors/errors/reconciliation. Each later provider adapter extends capability-specific contracts under same laws.

## Acceptance

A provider can be replaced without changing AWP primitive IDs, policy semantics or UI contracts; unsupported mechanics fail explicitly rather than causing direct SDK bypass.