# Exception Events Gateway Contract (draft v0.1)

Scope: stream exception workflow events (`exception.*`) for Console activity feeds and Notify integrations.

## Security / headers
- `Authorization: Bearer <token>` (or `DPoP` where configured)
- `X-StellaOps-Tenant: <tenantId>` (required)
- `X-Stella-Project: <projectId>` (optional)
- Scopes: `exception:read`

## Endpoint
- `GET /exceptions/events` — Server-Sent Events (SSE) stream.
  - Query params: `tenant`, `traceId`, `projectId` (optional)
  - Response: `text/event-stream`

## Event types
- `exception.created`
- `exception.updated`
- `exception.status_changed`
- `exception.deleted`

## Rate limits (proposal)
- Max 1 active SSE connection per browser session.
- Heartbeat every 30s; server closes idle connections after 60s without reads.
- When rate limited: `429` with `Retry-After`.

## Notify integration
Gateways SHOULD forward these events to Notify where configured:
- `exception.status_changed` → `notify.event` with severity derived from exception severity and status.
- All events include `traceId` for audit correlation.

## Samples
- `docs/api/gateway/samples/exception-events.ndjson`