# Signals Reachability API Contract (draft placeholder)

**Status:** Draft v0.2 · owner-proposed

## Scope
- `/signals/callgraphs`, `/signals/facts`, reachability scoring overlays feeding UI/Web.
- Deterministic fixtures for SIG-26 chain (columns/badges, call paths, timelines, overlays, coverage).

## Endpoints
- `GET /signals/callgraphs` — returns call paths contributing to reachability.
- `GET /signals/facts` — returns reachability/coverage facts.

Common headers: `Authorization: DPoP <token>`, `DPoP: <proof>`, `X-StellaOps-Tenant`, optional `If-None-Match`.
Pagination: cursor via `pageToken`; default 50, max 200.
ETag: required on responses; clients must send `If-None-Match` for cache validation.

### Callgraphs response (draft)
```jsonc
{
  "tenantId": "tenant-default",
  "assetId": "registry.local/library/app@sha256:abc123",
  "paths": [
    {
      "id": "path-1",
      "source": "api-gateway",
      "target": "jwt-auth-service",
      "hops": [
        { "service": "api-gateway", "endpoint": "/login", "timestamp": "2025-12-05T10:00:00Z" },
        { "service": "jwt-auth-service", "endpoint": "/verify", "timestamp": "2025-12-05T10:00:01Z" }
      ],
      "evidence": { "traceId": "trace-abc", "spanCount": 2, "score": 0.92 }
    }
  ],
  "pagination": { "nextPageToken": null },
  "etag": "sig-callgraphs-etag"
}
```

### Facts response (draft)
```jsonc
{
  "tenantId": "tenant-default",
  "facts": [
    {
      "id": "fact-1",
      "type": "reachability",
      "assetId": "registry.local/library/app@sha256:abc123",
      "component": "pkg:npm/jsonwebtoken@9.0.2",
      "status": "reachable",
      "confidence": 0.88,
      "observedAt": "2025-12-05T10:10:00Z",
      "signalsVersion": "signals-2025.310.1"
    }
  ],
  "pagination": { "nextPageToken": "..." },
  "etag": "sig-facts-etag"
}
```

### Samples
- Callgraphs: `docs/api/signals/samples/callgraph-sample.json`
- Facts: `docs/api/signals/samples/facts-sample.json`

### Outstanding
- Finalize score model, accepted `type` values, and max page size.
- Provide OpenAPI/JSON schema and error codes.