# Orchestrator Gateway Contract (draft v0.2)

Scope: expose Orchestrator read + operator control surfaces through the Web gateway (tenant-scoped, deterministic pagination, cache headers) to unblock Console control-plane views.

This is an interim contract until the gateway is aligned to the Orchestrator OpenAPI (`/openapi/orchestrator.json` in the Orchestrator service).

## 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: `orch:read`, `orch:quota`, `orch:operate`, `orch:backfill` (endpoint-specific)
- Operator audit headers (required on mutating requests):
  - `X-Stella-Operator-Reason: <free-text>`
  - `X-Stella-Operator-Ticket: <ticket-id>` (optional but recommended)

## Endpoints
- `GET /orchestrator/sources` — list registered job sources (tenant-scoped).
  - Query params: `sourceType`, `enabled`, `limit`, `continuationToken`
- `GET /orchestrator/sources/{sourceId}` — source detail.
- `GET /orchestrator/quotas` — list quotas (scope: `orch:quota`).
  - Query params: `jobType`, `paused`, `limit`, `continuationToken`
- `GET /orchestrator/quotas/{quotaId}` — quota detail (scope: `orch:quota`).
- `POST /orchestrator/quotas` — create quota (scope: `orch:quota`).
- `PUT /orchestrator/quotas/{quotaId}` — update quota (scope: `orch:quota`).
- `DELETE /orchestrator/quotas/{quotaId}` — delete quota (scope: `orch:quota`).
- `POST /orchestrator/quotas/{quotaId}/pause` — pause quota (scope: `orch:quota`).
- `POST /orchestrator/quotas/{quotaId}/resume` — resume quota (scope: `orch:quota`).
- `GET /orchestrator/quotas/summary` — quota/backpressure metrics summary (scope: `orch:quota`).
- `GET /orchestrator/jobs/summary` — job summary counts (scope: `orch:read`).
- `GET /orchestrator/deadletter/stats` — deadletter stats and top error clustering (scope: `orch:operate`).
- `GET /orchestrator/deadletter/summary` — grouped deadletter summary (scope: `orch:operate`).
- `POST /orchestrator/deadletter/{entryId}/replay` — replay a deadletter entry (scope: `orch:backfill`).
- `POST /orchestrator/deadletter/replay/batch` — replay a set of entry IDs (scope: `orch:backfill`).
- `POST /orchestrator/deadletter/replay/pending` — replay pending entries by filter (scope: `orch:backfill`).
- `POST /orchestrator/pack-runs/{packRunId}/cancel` — cancel a pack run (scope: `orch:operate`).
- `POST /orchestrator/pack-runs/{packRunId}/retry` — retry a pack run (scope: `orch:backfill`).

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

## Determinism rules
- Ordering:
  - sources: `(name asc, sourceId asc)`
  - quotas: `(jobType asc, quotaId asc)`
  - deadletter summary: `(category asc, errorCode asc)`
- Timestamps: ISO-8601 UTC.

## Samples
- `docs/api/gateway/samples/orchestrator-sources.json`
- `docs/api/gateway/samples/orchestrator-quotas.json`
- `docs/api/gateway/samples/orchestrator-quota-summary.json`
- `docs/api/gateway/samples/orchestrator-deadletter-stats.json`
- `docs/api/gateway/samples/orchestrator-deadletter-summary.json`
- `docs/api/gateway/samples/orchestrator-deadletter-replay.json`
- `docs/api/gateway/samples/orchestrator-packrun-cancel.json`
- `docs/api/gateway/samples/orchestrator-packrun-retry.json`