JobEngine Gateway Contract (draft v0.2)

This contract exposes the Stella Ops JobEngine read and operator control surfaces through the Web gateway: job sources, quotas and backpressure, job/DAG inspection, dead-letter handling, and pack-run control. It is tenant-scoped, paginates deterministically, and emits cache headers to unblock Console control-plane views.

Status: Interim contract until the gateway is aligned to the JobEngine OpenAPI (/openapi/jobengine.json in the JobEngine service).

Security / headers

• Authorization: Bearer <token> (or DPoP where configured).
• X-StellaOps-TenantId: <tenantId> (required; see tenant-auth).
• X-StellaOps-Project: <projectId> (optional; legacy alias X-Stella-Project is accepted only when the gateway is started with EnableLegacyHeaders=true).
• X-StellaOps-TraceId: <traceId> (optional; clients SHOULD send one).
• Scopes (endpoint-specific): orch:read, orch:quota, orch:operate, orch:backfill.
• Operator audit headers (required on mutating requests):
  • X-Stella-Operator-Reason: <free-text>
  • X-Stella-Operator-Ticket: <ticket-id> (optional but recommended)

Endpoints

• GET /jobengine/sources — list registered job sources (tenant-scoped).
  • Query params: sourceType, enabled, limit, continuationToken
• GET /jobengine/sources/{sourceId} — source detail.
• GET /jobengine/quotas — list quotas (scope: orch:quota).
  • Query params: jobType, paused, limit, continuationToken
• GET /jobengine/quotas/{quotaId} — quota detail (scope: orch:quota).
• POST /jobengine/quotas — create quota (scope: orch:quota).
• PUT /jobengine/quotas/{quotaId} — update quota (scope: orch:quota).
• DELETE /jobengine/quotas/{quotaId} — delete quota (scope: orch:quota).
• POST /jobengine/quotas/{quotaId}/pause — pause quota (scope: orch:quota).
• POST /jobengine/quotas/{quotaId}/resume — resume quota (scope: orch:quota).
• GET /jobengine/quotas/summary — quota/backpressure metrics summary (scope: orch:quota).
• GET /jobengine/jobs — list Scheduler-run-backed JobEngine compatibility jobs (scope: orch:read or scheduler:read).
• GET /jobengine/jobs/{jobId} — get one Scheduler-run-backed compatibility job record.
• GET /jobengine/jobs/{jobId}/detail — get a compatibility detail record with a canonical Scheduler run evidence payload and digest.
• GET /jobengine/dag/job/{jobId}/parents — parent dependency edges for the job; currently only verified Scheduler retry_of edges.
• GET /jobengine/dag/job/{jobId}/children — child dependency edges for the job; currently only verified Scheduler retry_of edges.
• GET /jobengine/jobs/summary — job summary counts (scope: orch:read).
• GET /jobengine/deadletter/stats — deadletter stats and top error clustering (scope: orch:operate).
• GET /jobengine/deadletter/summary — grouped deadletter summary (scope: orch:operate).
• POST /jobengine/deadletter/{entryId}/replay — replay a deadletter entry (scope: orch:backfill).
• POST /jobengine/deadletter/replay/batch — replay a set of entry IDs (scope: orch:backfill).
• POST /jobengine/deadletter/replay/pending — replay pending entries by filter (scope: orch:backfill).
• POST /jobengine/pack-runs/{packRunId}/cancel — cancel a pack run (scope: orch:operate).
• POST /jobengine/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)
  • jobs: (createdAt desc, jobId desc)
  • DAG children: (createdAt asc, jobId asc)
  • deadletter summary: (category asc, errorCode asc)
• Timestamps: ISO-8601 UTC.

Job detail evidence notes

• scheduler-run details are backed by scheduler.runs, not a synthetic ReleaseOrchestrator placeholder.
• payload is a canonical evidence envelope (jobengine.scheduler-run.evidence.v1) containing the stored run stats, reason, deltas, and retry dependency evidence.
• payloadDigest is the digest of the returned payload.
• If Scheduler has no durable proof for release scripts, idempotency keys, or leases, those fields are null or marked unavailable; clients must not treat empty fields as successful execution proof.

Samples

• samples/jobengine-sources.json
• samples/jobengine-quotas.json
• samples/jobengine-quota-summary.json
• samples/jobengine-deadletter-stats.json
• samples/jobengine-deadletter-summary.json
• samples/jobengine-deadletter-replay.json
• samples/jobengine-packrun-cancel.json
• samples/jobengine-packrun-retry.json