docs consolidation and others

docs/modules/vex-lens/guides/consensus-overview.md

@@ -0,0 +1,31 @@
+# VEX Evidence and Consensus (Detailed)
+
+This document complements `docs/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/UI_GUIDE.md`
+- Triage model: `docs/VULNERABILITY_EXPLORER_GUIDE.md`