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

docs/features/storage-transactions.md

@@ -29,6 +29,24 @@ Non-goals:
 - `WriteAheadLog`
 - Storage engine modules under `src/CBDD.Core/Storage`
 
+Checkpoint APIs:
+- `DocumentDbContext.Checkpoint(CheckpointMode mode = CheckpointMode.Truncate)`
+- `DocumentDbContext.CheckpointAsync(CheckpointMode mode = CheckpointMode.Truncate, CancellationToken ct = default)`
+- `StorageEngine.Checkpoint(CheckpointMode mode)`
+- `StorageEngine.CheckpointAsync(CheckpointMode mode, CancellationToken ct = default)`
+
+Checkpoint modes:
+- `Passive`: non-blocking best-effort checkpoint. Returns `Executed = false` when lock is contended.
+- `Full`: applies committed WAL pages and appends a WAL checkpoint marker without truncating WAL.
+- `Truncate`: applies committed WAL pages and truncates WAL (default behavior).
+- `Restart`: same as truncate, then reinitializes WAL writer session.
+
+Usage guidance:
+- Use `Passive` for background/low-priority maintenance where latency matters more than immediate WAL cleanup.
+- Use `Full` when you want durable page-file sync but prefer to preserve WAL history until a later truncate.
+- Use `Truncate` for routine manual checkpoints and disk-space recovery.
+- Use `Restart` for aggressive maintenance boundaries (for example after incident remediation flows).
+
 ## Permissions And Data Handling
 
 - Database files require host-managed filesystem access controls.

docs/troubleshooting.md

@@ -28,6 +28,8 @@ Database startup fails or recovery path throws WAL/storage errors.
 ### Resolution
 - Pin consumers to last known-good package.
 - Apply fix and add regression coverage in recovery/transaction tests.
+- If WAL growth is the issue, run `CheckpointMode.Truncate` (or `Restart`) instead of `Full`.
+- If foreground latency is a concern, schedule `CheckpointMode.Passive` retries and use `Truncate` during maintenance windows.
 
 ## Query And Index Issues