λιμνη · ABOUT
The lake, the layer,
the format.
LimniFS is Greek and English at once:λιμνη (limnē) is "lake"; Layered,Immutable,Merkle-rooted,NetworkImage File[system].
THE NAME
Why a lake?
A lake is not a puddle. It is a layered body of water, held within definite shores, whose physical structure shapes the life within. From top to bottom:
επι
epi · on top
The warm, sun-lit surface. Where bytes land first, fast and uncompressed.
μετα
meta · between
The thermocline. The transition zone where deepening happens.
υπο
hypo · below
The cold, dense deep. Where bytes rest, compressed, waiting.
Limnology (the study of lakes) gave us this vocabulary and we adopt it without apology. The terms are load-bearing, not decorative:
- drop — content-addressed chunk; the atom of storage and the unit of identity.
- slab — a contiguous byte object (4–64 MiB) holding many drops. Slab packing is the Taobao TFS lesson.
- epilimnion — the hot tier. Freshly written, fast codec (LZ4), unconsolidated slabs.
- metalimnion — the transition tier. The thermocline is the moving boundary where background re-compression happens.
- hypolimnion — the cold tier. Deep-compressed (zstd, lzma, brotli per class), consolidated slabs.
- turnover — a derivation that mixes layers: flatten, defragment, re-encode. Produces a new image, leaves the old valid.
- meromictic — an overlay chain that is never flattened. A valid long-term state; readers MUST NOT require flattening. (From limnology: a meromictic lake never fully mixes.)
- limn — to sketch a lake. The CLI verb for building:
limni limn ./my-app -o my-app.lim.
THE PRINCIPLES
Six invariants of the lake.
01
Layered
Three independent layers — drop store, metadata, manifest. Each versioned, byte-addressable, independently parsed.
02
Immutable
A .lim image never changes. Mutation is derivation: delta, flatten, turnover. Each derivation is a new image with a new ManifestRoot.
03
Merkle-rooted
The signed Merkle root is the image identity. Every byte is reachable from it; every claim is verifiable from it.
04
Network-native
The manifest detaches from the drop store. Slabs live behind any locator: file, HTTP, S3, IPFS, P2P. Mirror racing fetches in parallel.
05
Spec-first
The wire format is the spec. No FlatBuffers IDL, no Avro schema, no external serialization runtime. Python and Ruby adapters implement from the spec alone.
06
Custom
Owned wire format. No vtable overhead, no per-record schema tags, no external dependencies. Every byte is determined by SPEC.md.
THE PALETTE
Eight colors from a lake at dusk.
Every LimniFS color is drawn from the layer cake illustration: the cold deep of hypolimnion, the warm surface of epilimnion, the vermillion of last light on the water, the gold of the sun.
Abyss
The cold deep — primary background, depth
Deep
Hypolimnion — section backgrounds, cards
Surface
Epilimnion — highlights, links on dark
Mist
Lapping waves — borders, subtle UI
Paper
The air above — light theme background
Vermillion
Last light — primary accent, identity
Gold
Sun on water — highlights, warm gradient end
Amber
Warm halo — secondary accent
THE FORMAT EXTENSION
Why .lim?
Three characters. Distinctive enough that file(1) and MIME registries can adopt it without conflict. Short enough to type. Carries the name.
Byte-level identification is independent of extension: every .lim file begins with the magic bytes LMFS (manifest) or LIM1 (slab). The extension is for humans; the magic is for machines.
Ready to wade in?
The format is dissected bit by bit in the Format section.