Signals API — Reachability Contract

Status: Working contract (aligns with src/Signals/StellaOps.Signals/Program.cs).

This document is the as-wired contract for the Stella Ops Signals service: it enumerates exactly the HTTP routes the Signals host registers in the request pipeline, the scopes each requires, and the routes that are defined in the assembly but not served. It is the authoritative companion to the Signals API reference, which presents the same surface in a more narrative form — when the two disagree, prefer this contract and the source it cites.

All routes are registered in Program.cs (minimal-API endpoints), CompatibilityApiV1Endpoints.cs, and ScmWebhookEndpoints.cs. URLs are lowercased (AddRouting(LowercaseUrls = true)).

Auth, scopes, sealed mode

• Scopes: signals:read, signals:write, signals:admin (endpoint-specific; see below). These map to SignalsPolicies.Read / .Write / .Admin in src/Signals/StellaOps.Signals/Routing/SignalsPolicies.cs, and to StellaOpsScopes.SignalsRead / SignalsWrite / SignalsAdmin in the canonical scope catalog. The compatibility endpoints under /api/v1/signals additionally accept orch:read (StellaOpsScopes.OrchRead) as an alternative to signals:read.
• Per-request authorization model: the /signals/** and /api/v1/signals endpoints do not use ASP.NET authorization filters/policies on the route. Instead each handler calls Program.TryAuthorize (single scope) or Program.TryAuthorizeAny (any-of scopes). An authenticated principal that lacks the required scope receives 403; an unauthenticated request receives 401 (unless the dev fallback applies — see below).
• Dev fallback: when Authority auth is disabled (Signals:Authority:Enabled=false) the service uses the Anonymous authentication handler and the handlers honour the Signals:Authority:AllowAnonymousFallback flag. When fallback is allowed, requests must include X-Scopes: <space-separated scopes> (example: X-Scopes: signals:write). AllowAnonymousFallback=true is rejected at startup outside the local-harness environment by SignalsRuntimeConfigurationValidator.
• Sealed mode (air-gap): controlled by Signals:AirGap:SealedMode (SignalsSealedModeMonitor). When enforcement is enabled and evidence is not compliant, most endpoints return 503 with { "error": "sealed-mode evidence invalid", "reason": "<detail>" }. Enforcement is a no-op when EnforcementEnabled is false.

Endpoints

Discovery, health & status

• GET /openapi/v1.json (anonymous) — OpenAPI 3.1 discovery document used by the gateway aggregator fan-out.
• GET /healthz (anonymous) — health check.
• GET /readyz (anonymous) — 503 with { "status": "sealed-mode-blocked", "reason": ... } when sealed-mode enforcement blocks readiness; 503 (no body) when not yet ready; otherwise 200 with { "status": "ready" }.
• GET /buildinfo (anonymous) — image-provenance/build-info endpoint mapped via BuildInfoEndpointExtensions.MapBuildInfoEndpoint (fallback module name signals), for the operator verify aggregator.
• GET /signals/ping (scope: signals:read, response: 204 No Content).
• GET /signals/status (scope: signals:read) — returns { service, version, sealedMode: { enforced, compliant, reason } }.

Callgraph ingestion & retrieval

• POST /signals/callgraphs (scope: signals:write)
  • Body: CallgraphIngestRequest. Required fields: language, component, version, artifactContentType, artifactFileName, artifactContentBase64. Optional: metadata, schemaVersion, analyzer.
  • Response: 202 Accepted with CallgraphIngestResponse (callgraphId, artifactPath, artifactHash, casUri, graphHash, manifestCasUri, schemaVersion, nodeCount, edgeCount, rootCount) and Location: /signals/callgraphs/{callgraphId}.
  • Graph hash is computed deterministically from normalized nodes/edges/roots; see graphHash in the response.
  • Validation failures return 400 (CallgraphIngestionValidationException, CallgraphParserNotFoundException, FormatException) or 422 (CallgraphParserValidationException).
• GET /signals/callgraphs/{callgraphId} (scope: signals:read) — 404 when not found.
• GET /signals/callgraphs/{callgraphId}/manifest (scope: signals:read) — returns the manifest file (application/json); 404 when the callgraph or manifest is missing.

Sample request: docs/api/signals/samples/callgraph-sample.json

Runtime facts ingestion

• POST /signals/runtime-facts (scope: signals:write)
  • Body: RuntimeFactsIngestRequest with subject, callgraphId, events[] (RuntimeFactEvent), and optional metadata.
  • Response: 202 Accepted with RuntimeFactsIngestResponse (factId, subjectKey, callgraphId, runtimeFactCount, totalHitCount, storedAt) and Location: /signals/runtime-facts/{subjectKey}.
• POST /signals/runtime-facts/ndjson (scope: signals:write)
  • Query parameters (RuntimeFactsStreamMetadata): callgraphId (required), plus optional scanId, imageDigest, component, version, purl.
  • Body: NDJSON of RuntimeFactEvent objects; Content-Encoding: gzip supported. An empty stream returns 400.
• POST /signals/runtime-facts/synthetic (scope: signals:write)
  • Generates a small deterministic sample set of runtime events for a callgraph to unblock testing.
  • Local-harness only: this route is registered only when SignalsRuntimeConfigurationValidator.IsSignalsLocalHarness is true (Development / TestingLocalHarness). It returns 404 in normal deployments.

Runtime observations ingestion (internal agent)

• POST /api/v1/runtime/observations (scope: signals:write; tenant from the token)
  • Sprint 20260512_020 RO-RUN-003 unified runtime-evidence ingest, consumed by the deployment-observation agent, which posts to Signals directly inside the network — the SOLE ingest target since Q-7 (executed P8-16; the former Findings.Ledger dual-write copy is deleted). Since PCD-865 (owner ruling 2026-10-18) the agent presents an Authority client-credentials token (signals:write aoc:verify, minted for its tenant) and the route requires it (401 without a token, 403 without signals:write). The observation is written for the token’s tenant, resolved to the canonical UUID through Signals’ own tenants replica (503 with Retry-After while the replica is disabled or cannot answer). A body tenantId that names another tenant is refused with 403 and nothing is written. The route is withheld from Router publication, so it is not reachable at the gateway.
  • Requires durable PostgreSQL persistence. When Signals runs without a configured Postgres connection string, the route is still mapped but returns 503 { "error": "runtime observation ingest requires durable PostgreSQL persistence." }.
  • Body: RuntimeObservationIngestRequest (eventId non-empty GUID — the agent-stamped idempotency key, dedupped on (tenant, eventId) so a publish retry cannot double-increment hit_count; optional tenantId GUID that must name the token’s tenant; agentId GUID, imageDigest sha256:..., containerName required; plus releaseId, hostId, containerId, containerName, imageRef, captureMode, capturedAt, containerLabels, processList, portBindings, metadata, userStack, kernelStack, stackCaptureMode). Missing/invalid eventId/agentId/ imageDigest/containerName return 400.
  • Response: 202 Accepted with { factId, releaseId, imageDigest } and Location: /api/v1/runtime/observations/{factId}.

Unknowns ingestion, retrieval & query

• POST /signals/unknowns (scope: signals:write)
  • Body: UnknownsIngestRequest (subject, callgraphId, unknowns[] of UnknownSymbolEntry).
  • Response: 202 Accepted with UnknownsIngestResponse (subjectKey, unknownsCount) and Location: /signals/unknowns/{subjectKey}.
• GET /signals/unknowns/{subjectKey} (scope: signals:read) — returns the unknown entries for a subject; 404 when none.
• GET /signals/unknowns (scope: signals:read)
  • Query parameters: optional band (parsed against the UnknownsBand enum), limit (default 100, clamped 1–1000), offset (default 0).
  • Response: 200 with { items, count, limit, offset, band }.
• GET /signals/unknowns/{id}/explain (scope: signals:read)
  • Response: 200 with { id, subjectKey, band, score, normalizationTrace, flags, createdAt, updatedAt }; 404 when the id is unknown.

Reachability scoring & facts

• POST /signals/reachability/recompute (scope: signals:admin)
  • Body: ReachabilityRecomputeRequest (callgraphId, subject, entryPoints[], targets[], optional runtimeHits[], optional blockedEdges[] of ReachabilityBlockedEdge { from, to }, optional metadata).
  • Response: 200 OK with { id, callgraphId, subject, entryPoints, states, computedAt }. Validation failures return 400 (ReachabilityScoringValidationException); unknown callgraph returns 404 (ReachabilityCallgraphNotFoundException).
• GET /signals/facts/{subjectKey} (scope: signals:read)
  • Response: ReachabilityFactDocument (per-target states, score, riskScore, unknownsCount, unknownsPressure, optional uncertainty, optional runtimeFacts snapshot and runtimeFactsBatchUri/runtimeFactsBatchHash, optional edgeBundles, hasQuarantinedEdges); 404 when not found.

Sample fact: docs/api/signals/samples/facts-sample.json

Execution evidence

• POST /signals/execution-evidence (scope: signals:write)
  • Body: ExecutionEvidenceRequest (artifactId and environmentId required).
  • Response: 202 Accepted with the built evidence and Location: /signals/execution-evidence/{artifactId}/{environmentId}. Returns 400 when ids are missing, 422 when there are insufficient trace events or the pipeline is disabled, and 200 with { status: "rate_limited", ... } when rate-limited.

Beacon attestation

• POST /signals/beacons (scope: signals:write)
  • Body: BeaconIngestRequest (events[] — at least one required, else 400).
  • Response: 202 Accepted with the ingest response and Location: /signals/beacons.
• GET /signals/beacons/rate/{artifactId}/{environmentId} (scope: signals:read)
  • Response: 200 with the verification rate; 404 when no beacon data exists for the artifact/environment pair.

Reachability union bundle ingestion (CAS layout)

• POST /signals/reachability/union (scope: signals:write)
  • Body: application/zip bundle containing nodes.ndjson, edges.ndjson, meta.json. A non-application/zip Content-Type returns 400.
  • Optional header: X-Analysis-Id (defaults to a new GUID N format if omitted).
  • Response: 202 Accepted with ReachabilityUnionIngestResponse (analysisId, casRoot, files[] of { path, sha256, records }) and Location: /signals/reachability/union/{analysisId}/meta.
• GET /signals/reachability/union/{analysisId}/meta (scope: signals:read) — returns meta.json (application/json); 404 when missing.
• GET /signals/reachability/union/{analysisId}/files/{fileName} (scope: signals:read) — returns the requested file (application/json for *.json, otherwise application/x-ndjson); 404 when missing.

Compatibility surface (/api/v1/signals)

These return a fixed, in-memory deterministic sample dataset (operator/console compatibility) and accept either signals:read or orch:read.

• GET /api/v1/signals (scope: signals:read or orch:read)
  • Query parameters: optional type, status, provider, limit (default 50, clamped 1–200), cursor (numeric offset).
  • Response: 200 with { items, total, cursor }.
• GET /api/v1/signals/stats (scope: signals:read or orch:read)
  • Response: 200 with aggregate counts (total, byType, byStatus, byProvider, lastHourCount, successRate, avgProcessingMs).

SCM / CI webhooks

Anonymous endpoints (AllowAnonymous()); authentication is per-provider signature/token validation rather than Authority scopes. All are subject to sealed-mode enforcement.

• POST /webhooks/github — validates X-Hub-Signature-256 HMAC; reads X-GitHub-Event, X-GitHub-Delivery, optional X-Integration-Id/X-Tenant-Id.
• POST /webhooks/gitlab — validates X-Gitlab-Token; reads X-Gitlab-Event, X-Gitlab-Event-UUID.
• POST /webhooks/gitea — validates X-Hub-Signature-256 (falls back to X-Hub-Signature); reads X-Gitea-Event, X-Gitea-Delivery.

Responses: 501 Not Implemented problem+json with code source_scan_not_available (or sbom_ingest_not_available) when the event asks for a scan or an SBOM ingest, which Signals cannot dispatch; 200 with a message when the event asks for neither or is not mapped; 400/401 on validation failures. No webhook answers 202.

Withdrawn surfaces

Withdrawn 2026-09-27 (SPRINT_20260927_003 PCD-44). The attribute-routed controllers that were compiled into the Signals assembly but never served (Program.cs maps no MVC controllers) are withdrawn, and their routes answer 404:

• RuntimeAgentController / RuntimeFactsController, route base api/v1/agents (register, heartbeat, get, list, delete, commands, posture, facts). That base is Release Orchestrator’s agent surface. Runtime observations are ingested at POST /api/v1/runtime/observations and POST /signals/runtime-facts.
• HotSymbolsController, route base api/v1/signals: hot-symbols, hot-symbols/top, hot-symbols/stats, hot-symbols/correlated.