Implement checkpoint modes with docs/tests and reorganize project file layout

src/CBDD.Core/Transactions/CheckpointMode.cs

@@ -1,32 +1,52 @@
 namespace ZB.MOM.WW.CBDD.Core.Transactions;
 
-/// <summary>
-/// Defines checkpoint modes for WAL (Write-Ahead Log) checkpointing.
-/// Similar to SQLite's checkpoint strategies.
-/// </summary>
-public enum CheckpointMode
-{
-    /// <summary>
-    /// Passive checkpoint: Non-blocking, best-effort transfer from WAL to database.
-    /// Does not wait for readers or writers. May not checkpoint all frames.
-    /// </summary>
+/// <summary>
+/// Defines checkpoint modes for WAL (Write-Ahead Log) checkpointing.
+/// Similar to SQLite's checkpoint strategies.
+/// </summary>
+public enum CheckpointMode
+{
+    /// <summary>
+    /// Passive checkpoint: non-blocking, best-effort transfer from WAL to database.
+    /// If the checkpoint lock is busy, the operation is skipped.
+    /// WAL content is preserved and a checkpoint marker is appended when work is applied.
+    /// </summary>
     Passive = 0,
 
-    /// <summary>
-    /// Full checkpoint: Waits for concurrent readers/writers, then checkpoints all
-    /// committed transactions from WAL to database. Blocks until complete.
-    /// </summary>
+    /// <summary>
+    /// Full checkpoint: waits for the checkpoint lock, transfers committed pages to
+    /// the page file, and preserves WAL content by appending a checkpoint marker.
+    /// </summary>
     Full = 1,
 
-    /// <summary>
-    /// Truncate checkpoint: Same as Full, but also truncates the WAL file after
-    /// successful checkpoint. Use this to reclaim disk space.
-    /// </summary>
+    /// <summary>
+    /// Truncate checkpoint: same as <see cref="Full"/> but truncates WAL after
+    /// successfully applying committed pages. Use this to reclaim disk space.
+    /// </summary>
     Truncate = 2,
 
-    /// <summary>
-    /// Restart checkpoint: Truncates WAL and restarts with a new WAL file.
-    /// Forces a fresh start. Most aggressive mode.
-    /// </summary>
-    Restart = 3
-}
+    /// <summary>
+    /// Restart checkpoint: same as <see cref="Truncate"/> and then reinitializes
+    /// the WAL stream for a fresh writer session.
+    /// </summary>
+    Restart = 3
+}
+
+/// <summary>
+/// Result of a checkpoint execution.
+/// </summary>
+/// <param name="Mode">Requested checkpoint mode.</param>
+/// <param name="Executed">True when checkpoint logic ran; false when skipped (for passive mode contention).</param>
+/// <param name="AppliedPages">Number of pages copied from WAL index to page file.</param>
+/// <param name="WalBytesBefore">WAL size before the operation.</param>
+/// <param name="WalBytesAfter">WAL size after the operation.</param>
+/// <param name="Truncated">True when WAL was truncated by this operation.</param>
+/// <param name="Restarted">True when WAL stream was restarted by this operation.</param>
+public readonly record struct CheckpointResult(
+    CheckpointMode Mode,
+    bool Executed,
+    int AppliedPages,
+    long WalBytesBefore,
+    long WalBytesAfter,
+    bool Truncated,
+    bool Restarted);