# Advisory Gateway Contract (draft v0.1)

Scope: proxy Advisory surfaces through the Web gateway with tenant scoping, deterministic responses, ETag caching, and offline-friendly pagination.

## Security / headers
- `Authorization: Bearer <token>` (or `DPoP` where configured)
- `X-StellaOps-Tenant: <tenantId>` (required)
- `X-Stella-Project: <projectId>` (optional)
- `X-Stella-Trace-Id: <traceId>` (optional; clients SHOULD send one)
- Scopes: `advisory:read`

## Endpoints
- `GET /advisories` — list advisories (tenant-scoped).
  - Query params: `search`, `severity`, `sortBy`, `sortOrder`, `limit`, `continuationToken`
  - Response: `AdvisoryListResponse` (see sample)
- `GET /advisories/{advisoryId}` — advisory detail (tenant-scoped).

## Caching & pagination
- `limit` max: `200`.
- Cursor/paging uses `continuationToken` (opaque string).
- `ETag` MUST be a stable hash over a sorted payload; clients MAY send `If-None-Match`.
- Recommended headers: `Cache-Control: private, max-age=60, stale-if-error=300`.

## Determinism rules
- Ordering: `items` sorted by `(advisoryId asc)` unless `sortBy` is supplied; ties break by `advisoryId`.
- Timestamps: ISO-8601 UTC.

## Samples
- `docs/api/gateway/samples/advisories-list.json`
- `docs/api/gateway/samples/advisory-detail.json`