# Adapter Contracts

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

## Target State

Providers are replaceable mechanics behind AWP-owned capability interfaces. Interfaces are named for the product capability, not the current vendor.

```text
Domain/Application
   ↓
Provider interface
   ↓
Adapter
   ↓
External provider/native API
```

Primary interfaces include:

```text
ForgeProvider
FactoryProvider
AgentProvider
WorkspaceProvider
DurableWorkflowProvider
CIProvider
ArtifactStoreProvider
DeploymentProvider
SecretStore
CommunicationProvider
TelemetryExporter boundary
```

## Invariants From Day 1

- domain/application APIs use AWP types/IDs, not SDK types;
- adapter maps provider-native IDs into explicit `ProviderReference` records;
- capability discovery is explicit, so unsupported features fail predictably;
- adapter calls are idempotent/reconcilable where lifecycle changes depend on them;
- provider events/webhooks normalize to observations before domain transitions;
- credentials are obtained through `CredentialReference`/SecretStore, scoped to operation;
- provider outage/degradation is distinguishable from auth/permission/configuration failures;
- provider replacement does not change primitive identity.

## Common Adapter Contract

Each provider operation defines:

```text
input AWP IDs + operation context
required Connection/capability/resource
idempotency/operation key
provider request mapping
provider reference/result mapping
retry classification
reconciliation/read-back method
cancellation where applicable
normalized errors
telemetry correlation
```

## Capability Discovery

Adapters expose a typed capability descriptor, e.g. supported auth modes, review/PR mechanics, model features, runtime classes or deployment strategies. Product planning can recommend only capabilities actually supported by the selected provider/account/resource.

## Provider Selection

Selection is policy/application logic, not hidden inside adapters. AWP records why a provider/account/model was chosen. For Attempt-like operations, resolved provider/account/model is immutable.

## Error Taxonomy

At minimum:

```text
unavailable/transient
rate/capacity exhausted
auth invalid / reauth required
permission insufficient
resource missing/invalid
unsupported capability
conflict/stale provider state
provider terminal failure
adapter bug/protocol violation
```

## Reconciliation

Mutation adapters provide read-back/reconcile semantics when external side effects can outlive a request. A timeout is not automatically failure; AWP queries provider state using operation/provider references before retrying.

## FOSS Ownership Examples

- Fabro: factory graph/execution mechanics; AWP owns FactoryRun/Task relationships.
- ACP/native: agent protocol mechanics; AWP owns AgentRun/Attempt.
- GitHub: forge/check/workflow mechanics; AWP owns ChangeSet/Review/CI correlation/progression.
- ARC: runner scale/listener/pod lifecycle; AWP owns CI meaning.
- Kubernetes: scheduling/apply/runtime mechanics; AWP owns Workspace/Deployment/Cluster product state.
- DBOS: durable checkpoint/replay; AWP owns workflow meaning.

## Increment Realization

| Increment | Adapter work |
|---|---|
| I0 | interface framework; Git/model/account/K8s/DBOS baseline adapters. |
| I1 | Factory/Agent/Forge publication/review/check consumption. |
| I5 | full CIProvider semantics. |
| I6 | Artifact/Deployment providers. |
| I7 | richer cluster/machine providers. |
| I8+ | communications/resolution/enterprise adapters as required. |

## Current Implementation State

Exact package exports are finalized with code, but target ownership and error/reconciliation contracts are fixed now.

## Deferred Realization

A public third-party adapter SDK is I9 productization. Internal interfaces still use stable AWP vocabulary from day one.

## Temporary Dogfood Behavior

An adapter may initially support only the exact provider capabilities needed by I1. Unsupported target operations return typed `unsupported capability`; they do not leak vendor-specific exceptions or encourage direct SDK bypass.

## Decisions / ADRs

Any direct provider SDK use outside adapter/infrastructure boundaries must be justified by an explicit architecture exception Decision.