# Transport Contract Schema

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

## Target State

Runtime-neutral validation schemas define external/internal HTTP, CLI and MCP DTO contracts. Hono is the handler transport and does not own schema/domain semantics.

## Envelope Conventions

A normal resource/query response returns typed data and metadata only when meaningful. Mutations include correlation/current revision and structured result. Avoid a universal noisy wrapper if HTTP semantics already express status cleanly.

Error schema:

```text
AWPError {
  code
  category
  message
  retryable
  targetId?
  correlationId
  details?          # structured, non-secret, schema-versioned
  requiredAction?
}
```

Categories include validation, authentication, authorization, not-found, conflict/stale, precondition/policy, rate/capacity, provider-degraded, retryable-infrastructure and terminal-domain failure.

## Mutation Contracts

Where applicable:

```text
command payload
expectedResourceRevision?
idempotencyKey?
requested options
```

Never accept implicit provider credentials or trust fields from clients that are resolved server-side.

## Pagination / Filtering

Use cursor-based pagination for potentially unbounded histories/logs. Filters are explicit typed fields and meaningful page/filter state is URL-compatible in web UI.

## Realtime

Realtime payload references durable primitive ID + resource/event revision/sequence. A client detecting a gap re-fetches authoritative projection.

## CLI / MCP

Machine-oriented commands expose the same stable IDs/status/error categories. Human pretty output is a CLI presentation layer; JSON/schema output is stable contract. MCP tools cannot bypass normal authorization/policy merely because they are local/agent-facing.

## OpenAPI / Compatibility

HTTP contracts should generate or maintain OpenAPI where practical. A declared stable/external API boundary sets compatibility status. Once stable, breaking change requires:

```text
Decision
migration/versioning plan
updated spec
R4 oasdiff/compatibility gate
```

Internal pre-stable dogfood endpoints may evolve atomically with web/control implementation while preserving domain identity.

## Sensitive Data

Schema marks fields that may contain user/source/log data and requires redaction/classification handling. Credential secret values are never normal response fields.

## Increment Realization

I0 core errors/auth/IDs/config. I1 first lifecycle. I2 Planning. I3 governance. I4 streams. I5 CI. I6 delivery. I7–I9 remaining domains. Public stable API productization is I9 unless earlier consumer declaration triggers compatibility boundary.

## Acceptance

Web/CLI/MCP can recover from typed errors and evolve contracts without leaking Hono/provider implementation objects into domain consumers.