Day 66 — State Dumping: JSON Snapshots of the Account Balance
The AutoQuant-Alpha Architecture
The core pattern: write to a temp file in the same directory, fsync it, then atomically rename it over the target. os.replace() on POSIX systems (and on Windows, since Python 3.3) is a single filesystem operation — the kernel guarantees any reader observes either the old inode or the new one, never a partial file. There is no in-between state to observe, because the rename doesn’t touch file contents at all; it just repoints a directory entry.
Design Decision Why it matters tempfile.mkstemp(dir=target_dir) Atomic rename only works within one filesystem/mount. A temp file in /tmp renamed onto a target in /data silently degrades to a non-atomic copy-then-delete on some platforms. f.flush() + os.fsync(f.fileno()) flush() only moves bytes into the OS page cache. fsync is what forces the kernel to persist them before we proceed to the rename. Skip it and a power loss right after os.replace() can leave a committed rename pointing at data that never made it to disk. os.replace() for the rename Atomic on POSIX and Windows — readers see the old file or the new file, never a torn one. .sha256 sidecar written after rename Detects silent bit-level corruption on read. A flipped byte on a failing disk is otherwise indistinguishable from a correct snapshot. os.fsync on the directory fd Some filesystems need a separate durability barrier for the directory-entry update, or a crash can lose the rename even though the file’s own blocks are safely written. Ring buffer, retain=N If the newest snapshot is somehow corrupted, latest() falls back through history automatically instead of raising and halting the system. Decimal, serialized as string Never a bare JSON number — some parsers round-trip those through float anyway. Every dollar figure survives the round trip exactly. schema_version field Add a field in six months and old snapshots don’t silently misparse — the reader raises clearly on a version it doesn’t recognize.
