# Policy + Evidence Composition Contract (draft v0.1)

Scope: provide a single Console-friendly response that combines policy evaluation output with related advisory and VEX evidence linksets for the same findings/component(s).

This contract is intended to reduce UI round-trips by composing existing gateway surfaces:
- Policy + Exceptions (`POST /policy/effective`)
- Advisories (`GET /advisories`)
- VEX Evidence (`GET /vex/statements`)

## Security / headers
- `Authorization: Bearer <token>` (or `DPoP` where configured)
- `X-StellaOps-Tenant: <tenantId>` (required)
- `X-Stella-Project: <projectId>` (optional)
- `X-Stella-Trace-Id: <traceId>` (optional; clients SHOULD send one)
- Scopes:
  - `policy:read` AND `exception:read`
  - `advisory:read`
  - `vex:read`

## Endpoint
- `POST /policy/evidence/component` — compose policy result + evidence linksets for the supplied findings.

## Request/response notes
- Request shape reuses `PolicyFindingRef` fields from the Policy + Exceptions contract (`docs/api/gateway/policy-exceptions.md`).
- Response includes:
  - `policy` (Policy effective view; deterministic ordering by `findingId`)
  - `advisories` (summaries; deterministic ordering by `advisoryId`)
  - `vexStatements` (summaries; deterministic ordering by `statementId`)
  - `linksets` mapping each `findingId` to the related `advisoryIds` and `vexStatementIds`
- Implementations MUST NOT invent verdicts; this is a pure composition surface.

## Caching & limits
- Composition responses SHOULD be cacheable for a short TTL when inputs are identical.
- Recommended headers: `Cache-Control: private, max-age=30, stale-if-error=120`.
- Recommended caps (UI/Gateway): findings max `500`, advisories max `200`, VEX statements max `200`.

## Determinism rules
- `findings` sorted by `(findingId asc)` before evaluation.
- `policy.items` sorted by `(findingId asc)`.
- `advisories` sorted by `(advisoryId asc)`.
- `vexStatements` sorted by `(statementId asc)`.
- Timestamps: ISO-8601 UTC.

## Samples
- `docs/api/gateway/samples/policy-evidence-component.json`