# Implementation plan — Vexer

## Delivery phases
- **Phase 1 – Connectors & normalization**  
  Build connectors for OpenVEX, CSAF VEX, CycloneDX VEX, OCI attestations; capture provenance, signatures, and source metadata; normalise into `VexClaim`.
- **Phase 2 – Mapping & trust registry**  
  Implement product mapping (CPE → purl/version), issuer registry (trust tiers, signatures), scope scoring, and justification taxonomy.
- **Phase 3 – Consensus & projections**  
  Deliver consensus computation, conflict preservation, projections (`vex_consensus`, history, provider snapshots), and DSSE events.
- **Phase 4 – APIs & integrations**  
  Expose REST/CLI endpoints for claims, consensus, conflicts, exports; integrate Policy Engine, Vuln Explorer, Advisory AI, Export Center.
- **Phase 5 – Observability & offline**  
  Ship metrics, logs, traces, dashboards, incident runbooks, Offline Kit bundles, and performance tuning (10M claims/tenant).

## Work breakdown
- **Connectors**
  - Fetchers for vendor feeds, CSAF repositories, OpenVEX docs, OCI referrers.
  - Signature verification (PGP, cosign, PKI) per source; schema validation; rate limiting.
  - Source configuration (trust tier, fetch cadence, blackout windows) stored in metadata registry.
- **Normalization**
  - Canonical `VexClaim` schema with deterministic IDs, provenance, supersedes chains.
  - Product tree parsing, mapping to canonical product keys and environments.
  - Justification and scope scoring derived from source semantics.
- **Consensus & projections**
  - Lattice join with precedence rules, conflict tracking, confidence scores, recency decay.
  - Append-only history, conflict queue, DSSE events (`vex.consensus.updated`).
  - Export-ready JSONL & DSSE bundles for Offline Kit and Export Center.
- **APIs & UX**
  - REST endpoints (`/claims`, `/consensus`, `/conflicts`, `/providers`) with tenant RBAC.
  - CLI commands `stella vex claims|consensus|conflicts|export`.
  - Console modules (list/detail, conflict diagnostics, provider health, simulation hooks).
- **Integrations**
  - Policy Engine trust knobs, Vuln Explorer consensus badges, Advisory AI narrative generation, Notify alerts for conflicts.
  - Orchestrator jobs for recompute/backfill triggered by Excitator deltas.
- **Observability & Ops**
  - Metrics (ingest latency, signature failure rate, conflict rate, consensus latency).
  - Logs/traces with tenant/issuer/provenance context.
  - Runbooks for mapping failures, signature errors, recompute storms, quota exhaustion.

## Acceptance criteria
- Connectors ingest validated VEX statements with signed provenance, deterministic mapping, and tenant isolation.
- Consensus outputs reproducible, include conflicts, and integrate with Policy Engine/Vuln Explorer/Export Center.
- CLI/Console provide evidence inspection, conflict analysis, and exports; Offline Kit bundles replay verification offline.
- Observability dashboards/alerts capture ingest health, trust anomalies, conflict spikes, and performance budgets.
- Recompute pipeline handles policy changes and new evidence without dropping deterministic outcomes.

## Risks & mitigations
- **Mapping ambiguity:** maintain scope scores, manual overrides, highlight warnings.
- **Signature trust gaps:** issuer registry with auditing, fallback trust policies, tenant overrides.
- **Evidence surges:** orchestrator backpressure, prioritised queues, shardable workers.
- **Performance regressions:** indexing, caching, load tests, budget enforcement.
- **Tenant leakage:** strict RBAC/filters, fuzz tests, compliance reviews.

## Test strategy
- **Unit:** connector parsers, normalization, mapping conversions, lattice operations.
- **Property:** randomised evidence ensuring commutative consensus and deterministic digests.
- **Integration:** end-to-end pipeline from Excitator to consensus export, policy simulation, conflict handling.
- **Performance:** large feed ingestion, recompute stress, CLI export throughput.
- **Security:** signature tampering, issuer revocation, RBAC.
- **Offline:** export/import verification, DSSE bundle validation.

## Definition of done
- Connectors, normalization, consensus, APIs, and integrations deployed with telemetry, runbooks, and Offline Kit parity.
- Documentation (overview, architecture, algorithm, issuer registry, API/CLI, runbooks) updated with imposed rule compliance.
- ./TASKS.md and ../../TASKS.md reflect active status and dependencies.