save checkpoint

docs/features/checked/vexlens/vex-merge-explanation.md

@@ -0,0 +1,28 @@
+# VEX merge explanation
+
+## Module
+VexLens
+
+## Status
+IMPLEMENTED
+
+## Description
+Consensus rationale models and service expose the reasoning behind VEX merge decisions from the consensus engine.
+
+## Implementation Details
+- **Rationale models**: `src/VexLens/StellaOps.VexLens/Api/ConsensusRationaleModels.cs` -- consensus rationale data models explaining merge decisions
+- **Rationale service**: `src/VexLens/StellaOps.VexLens/Api/IConsensusRationaleService.cs` -- service interface for querying merge explanations
+- **Rationale cache**: `src/VexLens/StellaOps.VexLens/Caching/IConsensusRationaleCache.cs` -- caches rationale for repeated queries
+- **Delta report**: `src/VexLens/StellaOps.VexLens/Delta/DeltaReport.cs`, `DeltaReportBuilder.cs`, `DeltaEntry.cs`, `DeltaSection.cs` -- builds reports explaining what changed between VEX merge rounds
+- **VEX delta mapper**: `src/VexLens/StellaOps.VexLens/Mapping/VexDeltaMapper.cs` -- maps delta changes to explanation models
+- **VEX delta compute**: `src/VexLens/StellaOps.VexLens/Services/VexDeltaComputeService.cs` -- computes deltas between consensus rounds
+- **Proof builder**: `src/VexLens/StellaOps.VexLens/Proof/VexProofBuilder.cs` -- includes merge reasoning in proof artifacts
+- **Tests**: `src/VexLens/__Tests/StellaOps.VexLens.Tests/Delta/DeltaReportBuilderTests.cs`, `StellaOps.VexLens/__Tests/StellaOps.VexLens.Tests/Caching/ConsensusRationaleCacheTests.cs`
+- **Source**: Feature matrix scan
+
+## E2E Test Plan
+- [ ] Verify rationale service explains why specific VEX status was chosen
+- [ ] Test delta report identifies changes between consensus rounds
+- [ ] Verify rationale cache returns consistent results
+- [ ] Test merge explanation includes source weights and trust scores
+- [ ] Verify proof artifacts contain merge reasoning