Module log 

Append-only canonical log per docs/concepts/write-protocol.md.

CanonicalLog is the single durable file backing a workspace. It exposes only four operations: append, sync (fsync), truncate, and scan for the last CHECKPOINT. The write protocol (see store.rs) composes these into two-phase commits.

File format

Every canonical log starts with an 8-byte header:

offset 0..4 : ASCII magic `MIMR` (4 bytes)
offset 4..8 : little-endian u32 format version
offset 8..  : record stream (opcode + varint length + body, repeating)

The header is written eagerly when CanonicalLog::open is called against an empty (or non-existent) file. On reopen, the header is validated and a non-Mimir or wrong-version file is rejected with LogError::IncompatibleFormat BEFORE any truncation, append, or recovery logic runs. This closes the destructive-truncate footgun where opening Store against a misrouted path would zero an arbitrary file.

From the LogBackend trait’s perspective the header is invisible: len, read_all, last_checkpoint_end, and truncate all operate in logical bytes (record stream only). CanonicalLog handles the physical header transparently; in-memory test backends like FaultyLog carry no header because they never persist.

Engineering notes:

• Plain file handle; no mmap, no O_DIRECT.
• sync() is fsync (full metadata + data per spec § 6.2).
• Orphan detection via forward scan from start. Spec § 10.1 suggests a backward-scan optimization for healthy logs; deferred until we have a realistic benchmark.

The LogBackend trait abstracts the four filesystem primitives so Store can be parameterized over a fault-injecting test backend. Production code uses CanonicalLog (the default).

Structs

CanonicalLog

The append-only canonical log file.

Enums

LogError

Errors produced by CanonicalLog.

Constants

LOG_FORMAT_VERSION

Current canonical-log format version. Bumped on any wire-format break that the decoder cannot handle transparently.

LOG_HEADER_SIZE

Physical byte length of the on-disk header (magic + version).

LOG_MAGIC

4-byte ASCII magic prefix identifying an Mimir canonical log.

Traits

LogBackend

The filesystem primitives a Store needs from its underlying log.