docs consolidation and others

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

@@ -0,0 +1,37 @@
+# VEX Consensus Algorithm (Deterministic)
+
+This document describes the consensus computation at a high level. It is not an API contract; see `docs/vex/consensus-json.md` and `docs/vex/consensus-api.md` for payload and endpoint details.
+
+## Inputs
+
+- Normalized VEX tuples (status, justification, scope, timestamp, source digest)
+- Issuer trust registry (tiers, weights, verification state)
+- Optional policy precedence rules for how to treat conflicts
+
+## Grouping and Ordering
+
+1. Group tuples by correlation key (typically `(artifactId/productKey, vulnerabilityId)` per tenant).
+2. Apply a stable sort for evaluation, commonly:
+   - Most recent statement first (timestamp)
+   - Higher trust tier/weight first
+   - Higher verification confidence first
+
+Ordering must be deterministic for identical inputs.
+
+## Lattice Join
+
+Consensus uses a lattice-style join to avoid false safety:
+
+- Model states with an explicit uncertainty ordering (e.g., `unknown` and `under_investigation` remain meaningful outcomes).
+- Preserve conflicts when competing issuers disagree at comparable precedence.
+
+The output includes:
+
+- Effective status
+- Confidence/weight summary
+- References to source statements (digests)
+- Conflict list (who disagrees and how)
+
+## References
+
+- `docs/modules/vex-lens/architecture.md`