JobEngine Gateway Contract (draft v0.2)

This contract exposes the Stella Ops JobEngine job and DAG inspection surface through the Web gateway. It is tenant-scoped, paginates deterministically, and emits cache headers for the Console job views.

Withdrawn groups (2026-10-01, SPRINT_20260928_008 PCD-129). Earlier drafts listed job sources, quotas and backpressure, dead-letter handling and pack-run control under /jobengine/. No service publishes those paths, and the Console and CLI callers were withdrawn. JobEngine maps only the jobs and DAG routes below (JobEngineJobEndpointExtensions).

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: orch:read or scheduler:read. Every served route is a read; the contract has no mutating request.

Endpoints

• 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.

Not served: /jobengine/sources*, /jobengine/quotas*, /jobengine/jobs/summary, /jobengine/deadletter* and /jobengine/pack-runs*.

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:
  • jobs: (createdAt desc, jobId desc)
  • DAG children: (createdAt asc, jobId 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.