Atomic Store — A Tiny, Crash-Safe, Multi-File Atomic Commit Library

Atomic Store is a minimal, embeddable C library that lets you update any number of logical files atomically, using a single append-only binary file as a transactional store.

It is designed for environments where:

• POSIX cannot guarantee multi-file atomic updates
• corruption on crash is unacceptable
• simplicity, portability, and auditability matter
• a full database (e.g., SQLite, LMDB) would be overkill

Atomic Store solves this by placing all logical “files” into one store file, using checksummed snapshots.
Each commit is fully atomic, crash-safe, and easy to reason about.

---

🚀 Features

• True atomic multi-file commits
• Crash-safe append-only format
• Corruption detection via checksums
• Simple, minimal C API
• Zero dependencies
• Portable across platforms & architectures
• Small, auditable codebase

---

📦 Why This Exists

POSIX only guarantees atomicity for single-file rename(), not for updating multiple files together.

If you update:

player.dat
world.dat
inventory.dat
quests.dat

…and your process crashes halfway, you may end up with inconsistent or corrupt state.

Atomic Store avoids that by committing all logical files in one atomic snapshot.
On open, the library finds the last valid snapshot, guaranteeing consistency.

This makes it ideal for:

• Game save systems
• Trading engines and bots
• IoT/embedded configuration bundles
• Applications with multi-file state
• Safe, crash-proof config management

---

📁 The Store File (.aw)

The store contains:

[snapshot blob][footer]
[snapshot blob][footer]
...

Each snapshot includes:

• file count
• file paths
• file contents
• checksum

The last valid snapshot becomes the active state.

---

💻 Example Usage (C)

aw_store_t *st = aw_store_open("mystore.aw", 1);

aw_tx_t *tx = aw_tx_begin(st);
aw_tx_add_buffer(tx, "A.txt", "Hello!", 6);
aw_tx_add_buffer(tx, "B.txt", "World!", 6);
aw_tx_commit(tx);

void *data;
size_t len;
aw_store_get(st, "A.txt", &data, &len);
printf("A.txt = %.*s\n", (int)len, (char*)data);
free(data);

---

🔨 Building

Build static library

cc -c atomic_store.c -o atomic_store.o
ar rcs libatomicstore.a atomic_store.o

Link your program

cc test.c -L. -latomicstore -o test

---

🧪 Test Program

A demonstration program (test.c) is included.
It:

• creates a store
• writes multiple logical files
• commits atomically
• reopens and verifies data

---

🛡 Safety Philosophy

Atomic Store aims for:

• minimalism
• predictable behavior
• crash consistency
• small, understandable code

It is not a full database.
It is a high-integrity, atomic snapshot system.

With:

• proper use of fsync
• stable hardware
• backups or snapshots
• crash testing

…it becomes suitable for production environments.

---

📘 License

MIT License — free for personal and commercial use.

---

🤝 Contributing

Contributions are welcome, but the core must stay:

• small
• auditable
• simple
• focused