How CLIO Core is built.

Pages

The stack

Design principles

1. No central metadata service. Every blob, tag, directory block and inode has exactly one home container chosen by hashing. There is no metadata server to scale or fail over. The cost is that whole-namespace questions (sizes, listings, searches) are broadcasts.
2. One writer per object. Each object's home serializes its mutations. That makes versioning, coherence and crash ordering tractable. Parallelism comes from many objects, not from concurrent writers to one object.
3. Everything is a blob. File data, directory blocks, inode records, extended attributes and staged appends are all ordinary CTE blobs. One tiering, replication and durability mechanism covers data and metadata alike.
4. Mechanism in the core, policy in layers. The core provides replica slots, transform flags, invalidation, fault handlers and conditional puts. Replication, caching, compression, indexing and filesystem semantics are separate, optional ChiMods composed into a chain.
5. Operators rank tiers; data carries a score. Placement matches a blob's score to configured tier scores, and measurements only break ties. Movement between tiers is explicit, by rescoring, flushing or eviction, and always copies before it frees.
6. Durable on fsync, like ext4. Acknowledged writes run at memory speed. Power-loss and node-loss durability are paid for on request, through fsync and replication.
7. Order operations so a crash leaks rather than corrupts. Logs trail data, new copies precede frees, records precede names, link counts rise before links appear. The failure mode is wasted space, never a reference to the wrong bytes.
8. Fail closed. Lost volatile data reads as an I/O error, not zeros. Expired caches that cannot be revalidated fail, rather than serving stale data. Coherence stamps that cannot vouch for a file drop the cache.
9. Keep hot paths off the network. Zero-IPC reads from shared memory, local path resolution from pushed caches, write sieves and write-behind, and node-local cache copies all exist to turn common operations into memory accesses.

One write, end to end

An application on node A appends 4 KiB to /mnt/clio/run/log.txt through the FUSE mount, then calls fsync.

1. Kernel to daemon. FUSE delivers the write to the daemon on node A. On a single node, the kernel's cached size supplies the append offset. On a multi-node mount, the append is staged locally and merged by the file's stream home.
2. Sieve. The bytes are copied into the client's write sieve: a 64 KiB shared-memory page for the file's 1 MiB page blob. The write returns immediately.
3. Ship. Within about 500 µs the sieve page is sent as a put to the filesystem's chain. The cache layer routes it to node A. The file's page blob is owned by node B, the hash of (file tag, page number), so the authoritative put travels to B. B invalidates other nodes' cache copies and registers A's copy.
4. Owner. On B, replication writes the primary (and any remote copies) and passes the put to the core. The core takes the blob's write token, drains readers, places the bytes (the RAM tier, since the blob's score defaults to 1.0), writes them, logs the new layout, and acknowledges.
5. fsync. The daemon drains the sieve, publishes the file's size to its stream home, and waits for replication. It then syncs the file's tag: B moves the page blob to a persistent tier (place, swap, log, free) and fsyncs that device and its metadata log. The daemon then fsyncs the stream's size log and syncs the parent directory's tag, so the name is durable too. Only then does fsync return.

Any later reader on node A finds the bytes in its node-local cache copy and reads them through shared memory without a request. A reader on node C fetches them from B and gets a cache copy of its own, registered against B's current version.

Tradeoff summary

Component maturity

These pages describe the dev branch as of October 2026. When the design changes, update the matching page. Each page is self-contained and links to its neighbors.