Skip to content
LimniFS

.format · the .lim spec

Every byte,
dissected.

The LimniFS wire format is owned end-to-end. No FlatBuffers, no Avro, no Cap'n Proto. Every fixed-width type is specified to bit position; every optional section carries an explicit presence bit; every byte is determined by SPEC.md.

A lake, in three layers.

A .lim image is structured like a body of water. The manifest floats on the surface — small, signed, identity. The metadata extends through the thermocline — a Merkle B-tree whose nodes are content-addressed, whose every level shares structure with prior versions. The drop store lies below the thermocline — cold, dense, packed.

Each layer is independently versioned (per-section version bytes, not per-record vtables). Each layer is independently parsed (no layer reaches into another's bytes). Each layer is independently addressable (HTTP range fetches the section you need).

→ Start with the manifest dissect — it is the smallest, most concrete, most signed.

LAYER 3 · MANIFESTThe signed identity.magic · versions · feature flags · slab index · cryptoparams · EC params · DMS · delta · history · Merkle rootthermoclineLAYER 2 · FILESYSTEM METADATAThe Merkle B-tree.inodes · directory tree · xattrs · slice → drop mapsper-class Seine recordsdeterministic · content-addressed · delta-friendlyLAYER 1 · DROP STOREThe bulk bytes.slabs (4–64 MiB) · drops · solid windows · Reed-Solomon shardsslab 0slab 1slab 2slab 3+ Reed-Solomon shards (optional)SURFACETHERMOCLINEDEEP

DropId = BLAKE3(plaintext) · the same drop lives in many representations across all three layers

.sections

Six sections. Read in order, or jump.

01

Layer 1

Drop store

The bulk bytes. Slabs of 4–64 MiB holding many drops, packed for small-file efficiency. Solid windows compress consecutive drops. Optional Reed-Solomon shards.

Read the dissect

02

Layer 2

Filesystem metadata

Inodes, xattrs, slice→drop maps. The directory tree is a deterministic Merkle B-tree — every node content-addressed, structural sharing built in.

Read the dissect

03

Layer 3

Manifest

The small signed head of the image. Magic + versions + feature flags + slab index + crypto + EC + DMS + delta + history + Merkle root. 16-byte header, dissected bit by bit.

Read the dissect

04

Cross-cutting

Identity & Merkle

DropId = BLAKE3(plaintext). ManifestRoot = BLAKE3 of the Merkle hash list. Representation plane (codec, AEAD, EC, locator) never affects identity.

Read the dissect

05

Cross-cutting

Locators & distribution

Manifest detaches from drop store. Slabs live behind file://, https://, s3://, ipfs://, limni-p2p://. Mirror racing fetches in parallel; lying locators are demoted.

Read the dissect

06

Operations

Derivations

Delta (base_root + tree_ops). Flatten (metadata-only compaction). Turnover (full repack + GC). Deepen (representation upgrade; identity preserved). Each appends to history.

Read the dissect

.format-invariants

Five things every reader MUST honor.

  1. Identity rule. DropId = BLAKE3(plaintext). Codec, AEAD, EC, locator are representations — never identity.
  2. Merkle root = image identity. The signed root over the metadata blob and manifest sections. Two images with the same root are byte-equivalent.
  3. Two-level addressing. Slice → drop → (slab, offset, len, representation). Small drops never map to scattered storage.
  4. Determinism. Same input + same parameters ⇒ byte-identical image. Nondeterminism is a tracked bug class.
  5. Per-section versioning. Within a version byte, every field is fixed-width and order-pinned. Cross-version: forward compatible, backward explicit-reject.