commit

docs/ARCHITECTURE_VEXER.md

@@ -26,6 +26,7 @@ MongoDB acts as the canonical store; collections (with logical responsibilities)
 - `vex.consensus` – consensus projections per `(vulnId, productKey)` capturing rollup status, source weights, conflicts, and policy revision.
 - `vex.exports` – export manifests containing artifact digests, cache metadata, and attestation pointers.
 - `vex.cache` – index from `querySignature`/`format` to export digest for fast reuse.
+- `vex.migrations` – tracks applied storage migrations (index bootstrap, future schema updates).
 
 GridFS is used for large raw payloads when necessary, and artifact stores (S3/MinIO/file) hold serialized exports referenced by `vex.exports`.
 
@@ -54,6 +55,7 @@ Policy snapshots are immutable and versioned so consensus records capture the po
 - JSON serialization uses `VexCanonicalJsonSerializer`, enforcing property ordering and camelCase naming for reproducible snapshots and test fixtures.
 - `VexQuerySignature` produces canonical filter/order strings and SHA-256 digests, enabling cache keys shared across services.
 - Export manifests reuse cached artifacts when the same signature/format is requested unless `ForceRefresh` is explicitly set.
+- For scorring multiple sources on same VEX topic use - `VEXER_SCORRING.md`
 
 ## 6. Observability & offline posture
 
@@ -68,5 +70,16 @@ Policy snapshots are immutable and versioned so consensus records capture the po
 - Build WebService endpoints (`/vexer/status`, `/vexer/claims`, `/vexer/exports`) plus CLI verbs mirroring Feedser patterns.
 - Provide CSAF, CycloneDX VEX, and OpenVEX normalizers along with vendor-specific connectors (Red Hat, Cisco, SUSE, MSRC, Oracle, Ubuntu, OCI attestation).
 - Extend policy diagnostics with schema validation, change tracking, and operator-facing diff reports.
+- Mongo bootstrapper runs ordered migrations (`vex.migrations`) to ensure indexes for raw documents, providers, consensus snapshots, exports, and cache entries.
+
+## Appendix A – Policy diagnostics workflow
+
+- `StellaOps.Vexer.Policy` now exposes `IVexPolicyDiagnostics`, producing deterministic diagnostics reports with timestamp, severity counts, active provider overrides, and the full issue list surfaced by `IVexPolicyProvider`.
+- CLI/WebService layers should call `IVexPolicyDiagnostics.GetDiagnostics()` to display operator-friendly summaries (`vexer policy diagnostics` and `/vexer/policy/diagnostics` are the planned entry points).
+- Recommendations in the report guide operators to resolve blocking errors, review warnings, and audit override usage before consensus runs—embed them directly in UX copy instead of re-deriving logic.
+- Export/consensus telemetry should log the diagnostic `Version` alongside `policyRevisionId` so dashboards can correlate policy changes with consensus decisions.
+- Offline installations can persist the diagnostics report (JSON) in the Offline Kit to document policy headroom during audits; the output is deterministic and diff-friendly.
+- Use `VexPolicyBinder` when ingesting operator-supplied YAML/JSON bundles; it normalizes weight/override values, reports deterministic issues, and returns the consensus-ready `VexConsensusPolicyOptions` used by `VexPolicyProvider`.
+- Reload telemetry emits `vex.policy.reloads` (tags: `revision`, `version`, `issues`) whenever a new digest is observed—feed this into dashboards to correlate policy changes with consensus outcomes.
 
 This architecture keeps Vexer aligned with StellaOps' deterministic, offline-operable design while layering VEX-specific consensus and attestation capabilities on top of the Feedser foundations.