# VEX Consensus Lens architecture

> Based on Epic 7 – VEX Consensus Lens; consolidates trust modelling, consensus computation, and API contracts.

## 1) Purpose

Compute a deterministic, reproducible consensus view over multiple VEX statements for each `(artifact, advisory)` tuple while preserving conflicts and provenance. Output is consumed by Policy Engine, Vulnerability Explorer, Advisory AI, and Console overlays.

## 2) Inputs

- `vex_normalized` tuples emitted by Excititor (status, justification, scope, timestamp, content hash).
- Issuer trust registry (`vex_issuer_registry`) providing trust tier, confidence, authority scope.
- Optional runtime context (Zastava exposure) and policy precedence rules.

## 3) Core algorithm

1. Group tuples by `(artifactId, advisoryKey)`.
2. Sort statements by `timestamp` then trust tier (critical → low) then confidence.
3. Apply lattice join:
   - States: `unknown < under_investigation < not_affected | affected < fixed`.
   - Conflicts triggered when competing issuers disagree at the same precedence level.
4. Generate consensus record with fields:
   ```json
   {
     "artifact": "pkg:rpm/redhat/openssl@3.0.9",
     "advisory": "CVE-2025-13579",
     "status": "not_affected",
     "confidence": 0.92,
     "derived_from": ["vex_raw:openvex:VEX-2025-00001:v2", "vex_raw:csaf:RHSA-2025:1234:v1"],
     "conflicts": [{"issuer":"vendor:upstream","status":"affected"}],
     "issued_at": "2025-08-30T12:05:00Z",
     "consensus_digest": "sha256:..."
   }
   ```
5. Persist consensus and emit `vex.consensus.updated` DSSE event.

Conflicts remain visible through `conflicts` array; Policy Engine can decide suppression strategy based on trust weights.

## 4) APIs

- `GET /v1/vex/consensus?artifact=...&advisory=...` — returns consensus record and conflict list.
- `GET /v1/vex/conflicts` — list outstanding conflicts with severity, trust delta, and time since disagreement.
- `POST /v1/vex/trust/weights` — (admin) update trust tiers/confidence (requires Authority scopes); updates propagate to recomputation jobs.
- `GET /v1/vex/consensus/export` — stream deterministic JSONL for Offline Kit / Export Center mirror bundles.

All responses include provenance fields (`consensus_digest`, `derived_from`, DSSE signature references) for audit.

## 5) Storage

- `vex_consensus` collection keyed by `(tenant, artifactId, advisoryKey)` with current consensus, metadata, conflict summary, and digests.
- `vex_consensus_history` append-only history to support replay and audit.
- `vex_conflict_queue` for unresolved conflicts requiring manual review.

## 6) Recompute strategy

- Incremental updates triggered by Excititor deltas, trust registry changes, or policy precedence updates.
- Recompute jobs run via Orchestrator; deterministic ordering ensures identical results for the same input set.
- Jobs produce SRM-style manifests for recomputation verification.

## 7) Observability

- Metrics: `vex_consensus_conflicts_total`, `vex_consensus_latency_seconds`, `vex_consensus_recompute_seconds{reason}`.
- Logs: include `artifactId`, `advisoryKey`, `issuer`, `status`, `trustTier`.
- Traces: `consensus.group`, `consensus.join`, `consensus.persist` spans.

## 8) Offline & export

- Bundle format: `consensus.jsonl`, `conflicts.jsonl`, `manifest.json`, `signatures/`. Each record references raw statement digests and trust metadata.
- Export Center uses the bundle for mirror profiles; CLI supports `stella vex consensus export` mirroring the API.