# VEX Observations and Linksets

This document describes how StellaOps stores and correlates VEX without rewriting upstream sources.

## Observations (Append-Only Evidence)

An observation is the immutable record of a VEX document *as received*.

Recorded fields typically include:

- **Provenance:** tenant, provider/issuer identity, retrieved/received timestamps (UTC), signature verification status, trust metadata, and content digest.
- **Raw payload:** stored losslessly to support audit and offline verification.
- **Derived indexes:** extracted identifiers and tuples used to correlate evidence (without replacing the raw payload).

If upstream republishes a VEX document, the new version is stored as a new observation with a `supersedes` relationship.

## Normalization (Projection Only)

Normalization produces tuples used by downstream layers:

- `(vulnerabilityId, productKey)` keys for correlation
- VEX status and justification
- Optional scope and validity windows

Normalization is a projection; it does not delete, mutate, or merge upstream evidence.

## Linksets (Correlation Without Precedence)

Linksets group tuples that refer to the same conceptual product-vulnerability pair.

Properties:

- **Deterministic:** linkset identifiers are derived from canonical, sorted key material.
- **Conflict-preserving:** disagreements remain visible (status, scope, justification, issuer identity).
- **Provenance-linked:** every item in a linkset references its source observation digest and issuer metadata.

Downstream consumers (Policy/Console/Exports) use linksets to explain what disagrees and why.

## References

- `docs/16_VEX_CONSENSUS_GUIDE.md`
- `docs/modules/excititor/architecture.md`
- `docs/modules/vex-lens/architecture.md`