Write-ahead journal for atomic buffer-to-flash storage (DETWS_ENABLE_WAL). More...

#include "ServerConfig.h"
#include <stddef.h>
#include <stdint.h>

Detailed Description

Write-ahead journal for atomic buffer-to-flash storage (DETWS_ENABLE_WAL).

A power-loss-safe write-ahead log, the substrate for on-device data stores (dbm / sqlite / nosql). It is built to the envelope measured on real hardware (docs/FEATURE_PERFORMANCE.md): an SD card over SPI writes ~1.5 MB/s sequentially but only ~40-100 durable random IOPS with 100+ ms tail spikes, and the durable-throughput knee is a ~32 KiB write with a flush every ~128-256 KiB. So the log appends sequentially in fixed pages and checkpoints in bulk, never scattering small durable writes.

On-media record framing (this file - increment 1, pure + host-tested): each record is

[magic u32][seq u64][len u32][crc u32][payload len bytes]   (little-endian; ::WAL_RECORD_HEADER = 20)

where crc is a CRC-32 (IEEE 802.3) over the 16 header bytes plus the payload. Recovery on mount walks records from the start and stops at the first record with a bad magic, a bad CRC, or a truncated tail

i.e. the torn write left by a power loss - so a crash costs at most the last, un-checkpointed record. This is the atomicity core, and it is pure (no I/O) so it is fully host-testable: feed it a journal image with a corrupted or truncated tail and it recovers to the last good record.

The durable store layer - A/B superblock, checkpoint, and mount/recover over a block-device seam - is built on this codec in wal_store.h; wal_fs.h binds that seam to a real fs::FS file (SD / LittleFS). The whole path is hardware-verified on an SD card over SPI (checkpoint recovery, torn-tail drop, byte-level payload persistence, and survival across a chip reset all pass).

Definition in file wal.h.