Release Orchestrator · First Signal API

Provides a fast “first meaningful signal” for a run — the time-to-first-signal (TTFS) read — backed by a per-run snapshot, with weak-ETag conditional requests.

Audience: UI and CLI authors polling run progress, and integrators wiring early run telemetry.

Implemented by the Release Orchestrator service (StellaOps.ReleaseOrchestrator.WebApi, FirstSignalEndpoints → FirstSignalService). The signal is snapshot-only: this service does not compute signals from runs/jobs. It returns whatever snapshot an upstream producer has written via FirstSignalService.UpdateSnapshotAsync (persisted in release_orchestrator.first_signal_snapshots). There is no in-process cache layer, no cold-start computation path, and no background snapshot writer in this service.

Endpoint

Canonical route:

GET /api/v1/release-orchestrator/runs/{runId}/first-signal

Legacy compatibility alias (the gateway still routes UI /api/v1/jobengine/* paths to this service; JobEngineLegacyEndpoints registers the alias and delegates to the same handler):

GET /api/v1/jobengine/runs/{runId}/first-signal

{runId} is constrained to a GUID ({runId:guid}); a non-GUID segment does not match this route.

Authorization

• Scope required: orch:read (policy ReleaseOrchestratorPolicies.Read). Requests without a bearer token carrying orch:read are rejected by the authorization layer (401/403).
• The endpoint also applies RequireTenant(), so a tenant context must be present in addition to the header below.

Required headers

• X-Tenant-Id: tenant identifier (string). Resolved by TenantResolver; a missing or blank value yields 400 Bad Request.

Optional headers

• If-None-Match: weak ETag from a previous 200 response. Multiple comma-separated values are supported, and * matches any current ETag.

Responses

200 OK

Returns the first signal payload and a weak ETag.

Response headers:

• ETag: weak ETag (echo into If-None-Match on the next request). Only set when a signal is present.
• Cache-Control: private, max-age=60 (only set when ETag is set).
• Cache-Status: hit|miss. In the snapshot-only service this is always miss (there is no in-memory cache; CacheHit is always false).
• X-FirstSignal-Source: diagnostic source tag. In this service the value is always snapshot.

Body (application/json) — shape of FirstSignalResponse / FirstSignalDto:

{
  "runId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "firstSignal": {
    "type": "started",
    "stage": "resolve",
    "step": null,
    "message": "Run started",
    "at": "2025-12-15T12:00:10+00:00",
    "artifact": { "kind": "image", "range": null },
    "lastKnownOutcome": null
  },
  "summaryEtag": "W/\"...\""
}

Field notes (grounded in FirstSignalEndpoints.MapToResponse and FirstSignalDto):

• runId — the run GUID from the route.
• firstSignal.type — lower-cased FirstSignalKind: one of queued, started, phase, blocked, failed, succeeded, canceled, unavailable.
• firstSignal.stage — lower-cased FirstSignalPhase: one of resolve, fetch, restore, analyze, policy, report, unknown. Nullable.
• firstSignal.step — always null in the current implementation (reserved).
• firstSignal.message — signal.Summary.
• firstSignal.at — signal.Timestamp (DateTimeOffset).
• firstSignal.artifact.kind — signal.Scope.Type: repo, image, or artifact.
• firstSignal.artifact.range — { "start": <int>, "end": <int> } or null (never populated by the current mapper, which always emits range: null).
• firstSignal.lastKnownOutcome — null, or an object with signatureId, errorCode, token, excerpt, confidence (low|medium|high), firstSeenAt, and hitCount.
• summaryEtag — the same weak ETag as the ETag response header (empty string if no ETag).

Note: when a signal is present, firstSignal is non-null. firstSignal is serialized as null only via the MapToResponse branch where result.Signal is null, which is not reachable for a 200 in the current FirstSignalService (a found snapshot always carries a deserialized signal).

304 Not Modified

Returned when If-None-Match matches the current weak ETag (exact match, or *).

404 Not Found

Returned when no first-signal snapshot exists for the resolved tenant + run, or when the stored snapshot JSON is unparseable (the service deletes the bad row and returns 404). This is the “no signal available yet” case for the snapshot-only service.

400 Bad Request

Missing/blank X-Tenant-Id header, an empty run GUID, or other invalid argument. Body shape: { "error": "<message>" }.

Not currently returned: 204 No Content. The result-status enum defines a NotAvailable state that maps to 204, but the snapshot-only FirstSignalService never produces it — the absence of a snapshot is reported as 404 Not Found. Treat 204 as reserved/forward-looking.

ETag semantics

• Weak ETags (W/"<8-byte base64>") are a SHA-256 hash (first 8 bytes, base64-encoded) over a canonical JSON projection of the stable signal content: version, jobId, timestamp, kind, phase, scope, summary, etaSeconds, lastKnownOutcome, and nextActions.
• Per-request diagnostics (diagnostics.cacheHit, diagnostics.source, diagnostics.correlationId) are intentionally excluded from the ETag material.

Stored snapshot model

The snapshot the producer writes (and the GET reads) is persisted in PostgreSQL table release_orchestrator.first_signal_snapshots (migration 001_initial.sql), keyed by (tenant_id, run_id):

The underlying FirstSignal domain record also carries version (default "1.0"), signalId, scope { type, id }, and nextActions[] { type, label, target }, which are persisted in signal_json but are not all surfaced in the REST response DTO.

Streaming (SSE) — NOT IMPLEMENTED in this service

The Server-Sent Events stream described in earlier drafts (GET /api/v1/jobengine/stream/runs/{runId} emitting first_signal events) is not implemented by the Release Orchestrator. The legacy /api/v1/jobengine/stream/* prefix is registered as an unsupported compatibility route in JobEngineLegacyEndpoints and returns 501 Not Implemented with body { "error": "not_implemented", "message": "...not yet been migrated to the release-orchestrator service.", "path": "...", "hint": "..." }. Run-stream / first_signal push delivery is tracked in the orchestrator decomposition plan and is not available today.

Configuration

There is no FirstSignal (Cache / ColdPath / SnapshotWriter) or messaging configuration section for this endpoint in the Release Orchestrator. The feature is snapshot-only and Postgres-backed; the relevant configuration is the service’s database connection (the release_orchestrator schema is auto-migrated on startup via AddReleaseOrchestratorPersistence). No in-memory/Valkey cache backend, cold-path timeout, or background snapshot-writer poller is wired in this service.

The FirstSignal.Cache / FirstSignal.ColdPath / FirstSignal.SnapshotWriter block documented in earlier drafts belonged to the legacy JobEngine implementation and does not apply to the Release Orchestrator service that now serves these routes.