DocumentDbContext.Dispose() does not checkpoint WAL - file may not be self-contained after close

[mrdevrobot]

Summary

DocumentDbContext.Dispose() disposes the StorageEngine without first flushing the Write-Ahead Log into the main data file. After disposal the .blite file may still have pending WAL records not merged into the main page file, making it fragile to copy, ship, or open cold on another machine.

Current behaviour

DocumentDbContext.Dispose() calls _storage?.Dispose() without calling CheckpointAsync() first. The StorageEngine already exposes CheckpointAsync() and it is used correctly in BLiteEngine and BLiteMigration, but not wired up on context disposal.

Expected behaviour

Either:

1. DocumentDbContext exposes a public CheckpointAsync() that delegates to _storage.CheckpointAsync(), so callers can flush before closing; OR
2. DisposeAsync() automatically checkpoints when there are no active transactions.

Option 1 is safer (no hidden async work in Dispose), but option 2 covers the common write-and-close use-case.

Workaround

Re-open the file with BLiteEngine immediately after disposing the context:

using (var db = new HelpDbContext(path))
    await db.HelpChunks.InsertBulkAsync(chunks, transaction: null);

using var engine = new BLiteEngine(path);
await engine.CheckpointAsync();

Context

Discovered during a bulk-insert build tool where help.blite is generated once and shipped as an embedded asset. Without an explicit checkpoint the resulting file is not guaranteed to be fully self-contained.