# VEX Evidence and Consensus (Detailed)

This document complements `docs/16_VEX_CONSENSUS_GUIDE.md` with implementation-oriented detail: what objects exist, how evidence is correlated without rewriting sources, and what “consensus” means in practice.

## Pipeline (Evidence First)

1. **Ingest raw VEX** as immutable observations (append-only, provenance preserved).
2. **Normalize** observations into tuples used for correlation and UI display.
3. **Correlate** tuples into deterministic linksets (grouping without merge or precedence).
4. **Compute consensus (optional)** using issuer trust and lattice rules to produce an “effective” status and conflict summary.
5. **Expose evidence** to Policy Engine, Console, and Vulnerability Explorer; include in Offline Kit snapshots.

## Core Objects

- **Raw observation:** upstream OpenVEX/CSAF/CycloneDX payload stored losslessly with provenance (issuer/provider, receive time, signature verification, content digest).
- **Normalized tuple:** extracted fields used for correlation and decisioning, typically `(vulnerabilityId, productKey, status, justification?, scope?, timestamp, sourceDigest)`.
- **Linkset:** a correlation group tying multiple tuples to the same conceptual `(vulnerabilityId, productKey)` without collapsing disagreements.
- **Consensus record:** a deterministic summary for a linkset: effective status, confidence/weight, and conflict list (still referencing raw evidence).

## Determinism Guarantees

- Canonical UTF-8 JSON bytes are hashed to compute stable digests for raw observations.
- Linkset IDs are derived from canonical, sorted key material.
- Consensus outputs are stable for identical inputs: ordering, timestamps, and digests are deterministic.

## Where This Lives

- Ingestion, raw store, and linksets: `docs/modules/excititor/architecture.md`
- Consensus and issuer trust: `docs/modules/vex-lens/architecture.md`
- Console/operator view: `docs/15_UI_GUIDE.md`
- Triage model: `docs/20_VULNERABILITY_EXPLORER_GUIDE.md`