# Transport and Contracts

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

## Target State

AWP uses Hono for HTTP transport, with runtime-neutral contracts shared by gateway, web and control plane. Transport schemas express external DTOs; domain objects remain internal and provider-neutral.

```text
Browser / CLI / MCP / webhook
        ↓
Gateway transport contract
        ↓ authenticated internal request
Control-plane application command/query
        ↓
Domain result / typed error
        ↓
Transport response/event
```

## Invariants From Day 1

- Hono types never appear in domain primitives.
- Provider SDK objects never cross public API/CLI/MCP contracts.
- All mutation endpoints accept/derive idempotency/correlation information where repeated delivery is possible.
- Every mutation establishes a `Principal` and authorization context before lifecycle change.
- Public errors are typed/stable enough for UI/CLI recovery without leaking secrets/internal stack traces.
- Provider webhooks are authenticated/validated and treated as observations, not direct lifecycle authority.
- External event envelopes use CloudEvents where useful; internal domain event meaning remains AWP-defined.

## Contract Families

### Command contracts

Represent requested state changes. Include target IDs, expected revision/precondition where concurrency matters, client correlation/idempotency key when retryable, and explicit options rather than implicit side effects.

### Query contracts

Read authoritative state/projections. Pagination/cursors are stable. Large logs/diffs/artifacts may return signed/object references rather than embedding unbounded payloads.

### Realtime contracts

Realtime messages are projections with sequence/revision information. Clients recover missed state by re-querying authoritative APIs.

### Provider/webhook contracts

Adapters validate provider signatures and normalize observations before application reconciliation. Unknown/duplicate deliveries are safe.

### CLI/MCP contracts

CLI and MCP call the same application capabilities/transport contracts rather than becoming separate orchestration authorities. Machine-oriented output has explicit schemas and stable IDs.

## Versioning

Internal dogfood contracts may evolve atomically until a declared stable consumer boundary exists. Once declared stable/external:

```text
compatible additive change -> normal evolution
breaking change -> Decision + version/migration policy + R4 compatibility gate
```

OpenAPI is the HTTP contract format where practical. `oasdiff` is preferred for breaking-change detection once compatibility protection activates.

## Concurrency and Idempotency

Use expected revision/ETag-style semantics where stale mutation would be dangerous. Commands that may be retried must be idempotent by natural operation key or explicit idempotency key. Provider webhook/event deduplication uses provider delivery ID plus provider/account scope.

## Authentication Boundary

The gateway may establish a session and reject bad credentials. The control plane independently trusts only authenticated gateway/system callers and resolves the effective `Principal`; forwarded arbitrary headers are insufficient.

## Error Model

Errors should distinguish at least:

```text
validation
authentication
authorization/not permitted
not found
conflict/stale revision
precondition/policy blocked
rate/capacity unavailable
provider degraded
retryable infrastructure failure
terminal domain failure
```

UI/CLI use error type + structured details for recovery copy/actions.

## Increment Realization

| Increment | Contract realization |
|---|---|
| I0 | Core ID/schema/error/auth/correlation conventions; gateway/control contracts. |
| I1 | Project/Plan/Task/Run/ChangeSet/Review/Merge endpoints/events. |
| I2 | Planning conversation/session/defaults/connections. |
| I3 | Decision/Approval/Policy APIs. |
| I4 | richer Factory realtime/log/diff streams. |
| I5 | CI/verification contracts and first-class compatibility gates. |
| I6 | Artifact/Release/Deployment contracts. |
| I7–I9 | Cluster, incident, enterprise/reliability contracts. |

## Current Implementation State

Contract ownership is specification-first; executable schemas/OpenAPI are created with implementation but must conform to this target.

## Deferred Realization

Stable public API/adapter SDK guarantees remain I9. Earlier internal contracts still preserve ownership/versioning discipline without pretending to be externally frozen.

## Temporary Dogfood Behavior

Dogfood may use one internal API version. Any shortcut must preserve stable AWP IDs and typed errors so later external versioning does not require replacing the domain model.

## Decisions / ADRs

See ADR 0003 for Hono. R4 policy is defined in engineering-practices and activates at declared compatibility boundaries.