Ore ⛏️ — docs

One abstraction — state — and backups, archives, distribution, sync, and
filesystems all fall out of it.

Ore stores your data as versioned, content-addressed state instead of as
files-in-a-filesystem or blobs-in-a-bucket. You snapshot data into a state, the
history is immutable and deduplicated, and every other behaviour — backing up,
archiving, serving, syncing, mounting — is just a view of that one model.

This directory is the user-facing documentation: what Ore is for and how
it feels to use. For the design rationale and on-disk format, see
../todo/architecture/.

---

The mental model (the whole thing)

Node                a sovereign machine: an identity (ed25519 key) + an object store
 └─ State           a versioned thing with a stable UUID (photos, postgres, dataset…)
     └─ Branch      a mutable named pointer → a snapshot   (the ONLY mutable thing)
         └─ Tree    the snapshot's content: files + dirs
             └─ entry   each file/dir carries tags (mode, owner, mtime, xattrs)

The one rule everything follows:

data        = immutable, content-addressed (id = BLAKE3 of the stored bytes)
references  = mutable, named               (branches)

Integrity, dedup, cheap snapshots, rollback, and replication are consequences
of that rule, not features bolted on.

Three things worth internalising:

• A node holds many states. There is no separate "repo" — the .ore/
  directory is a node. A node can hold a public docs state and an encrypted
  secrets state side by side, each with its own key.
• Directories are decoupled from states. A state owns no directory. You
  snapshot a directory into a state and materialize a state out to a
  directory. The same history can be projected to many directories, or none.
• Encryption is per-state, the store is always opaque. The object store only
  ever holds hash-addressed bytes; a private state's bytes are ciphertext and its
  id is the hash of that ciphertext — so a machine can hold and replicate an
  encrypted state without ever holding the key (a blind replica).

---

Use cases

Start here — each one is the same model wearing a different hat:

Use case	One line	Status
Backups	The bk/restic successor: snapshot + replicate, encrypted	✅ core works
Archive & big data	Frozen, browsable, deduplicated history of huge trees	✅ core works
Synchronization	The same state on many machines, authenticated	✅ core works
Artifacts	Immutable, content-addressed build outputs / releases	🟡 usable, no registry UX
CDN / content distribution	Serve state to many readers from edge replicas	🟡 read API exists
Filesystem (FUSE)	Mount a state and live in it	🧪 designed, not built
Containers / CSI	State as a Kubernetes volume	🧪 designed, not built

Status legend: ✅ works today · 🟡 partially works / rough edges · 🧪 designed,
stubbed, or not yet built. Docs for 🧪 features describe the intended UX so the
shape is committed before the code exists.

---

Also here

• Concepts — the architecture model: nodes, states, squads,
  policies, sharing, replication, and how they interact.
• CLI reference — every ore command that exists today.
• Storage architecture — the durability invariants,
  write protocol, fsck model, and real-node test gate.
• Running with Nix — dev shell, the ore package, and the
  services.ore NixOS module (the declarative-backups story).
• Monitoring — the /metrics Prometheus endpoint and an
  importable Grafana dashboard.