Policy + Evidence Composition Contract (draft v0.1)

This contract defines a single Console-friendly response that combines policy evaluation output with the related advisory and VEX evidence linksets for the same findings or components. It reduces UI round-trips by composing existing Stella Ops gateway surfaces into one call:

• Policy + Exceptions (POST /policy/effective)
• Advisories (GET /advisories)
• VEX Evidence (GET /vex/statements)

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:
  • policy:read AND exceptions: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.
• 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

• samples/policy-evidence-component.json