Durable acknowledgement
Durable is the default mode. The engine acknowledges a commit only after syncing its complete WAL frame. Acknowledged durable writes survive supported process crashes, subject to the filesystem/device honoring sync guarantees.
Relaxed skips per-commit sync and may lose acknowledged writes. Close syncs both modes.
No test result here certifies sudden-power-loss durability, filesystem crash consistency, or device failure handling.
Checkpoint publication order
- Write and sync a temporary compacted table.
- Rename the table into place and sync the directory where supported.
- Verify/open the new table.
- Publish the synced manifest, then CURRENT, using temporary-file replacement.
- Release the old table, truncate the WAL to its retained header, sync it, and reclaim obsolete files.
Older WAL records may remain after a crash during reclamation. Recovery validates them but does not reapply sequences covered by the checkpoint.
Open-time recovery
After acquiring the process lock, the engine verifies CURRENT, the manifest, table length/count, checksums, sorted keys, and sequence bounds. It then replays complete valid WAL batches newer than the checkpoint, requiring consecutive sequence numbers.
A final incomplete frame header/payload is truncated to the last complete frame and synced before writes resume. A complete bad-checksum frame is an error. The engine never exposes half of a recovered batch.
Missing CURRENT alongside storage, missing/empty WAL, missing tables, and malformed manifests are rejected instead of silently initializing replacement data.
Important boundaries
A complete unacknowledged WAL frame may recover. Failed acknowledgements do not imply rollback. The current API does not deduplicate retries with operation IDs.
A corrupted length that looks like an incomplete final frame cannot always be distinguished from a torn write. Supported truncated-tail handling is not arbitrary media repair or middle-of-file salvage.
Do not edit internal files, remove LOCK while open, or use network filesystems. The Unix lock is associated with its inode; replacing its pathname can defeat directory ownership.
Platform behavior
Linux, macOS, and FreeBSD use flock; Windows uses an unshared file handle. The OS releases ownership after a process exits.
Unix directory sync is used where supported. Windows file data is synced, but this implementation does not provide a portable directory fsync. Power-loss rename guarantees remain platform dependent.
Review validation and testing for the scenarios actually exercised.