0010: Storage backends are dumb, immutable blob stores
- Status: accepted
- Date: 2026-09-22
- Amended by: 0046 (privilege writes use the backend's compare-and-swap; a shared folder detects lost races afterwards)
Context
ADR 0004 makes the vault a set of write-once, content-addressed files. Git is one way to replicate such a set, but it is not the only one, and many intended users (families, small teams, people who do not use git) should not need it.
Decision
The core defines a storage interface with four operations:
put-if-absent(path, bytes) (immutable; a put to an existing path with
different content is an error), get(path), list(prefix), and an optional
delete(path) that only compaction uses and that a backend may omit.
Everything above the interface is backend-agnostic.
Backends:
- git: the vault directory in a repository, with
sync= fetch, fold, add, commit, push. No rebase or merge logic is needed because all changes are file additions. - fs: a plain directory, including synchronised folders (iCloud Drive, Dropbox, Google Drive, a network share). Safe because no file is ever modified in place.
- S3-compatible / WebDAV: object stores with conditional put.
- hosted: the vaultfold sync service, an HTTP blob store that is
zero-knowledge (stores only ciphertext and public metadata) and that
additionally:
- validates every event's signature against the vault's policy chain before accepting it, giving real write prevention;
- records reads per device key, giving a read audit log;
- hosts the relay (ADR 0011) and push notifications for approvals.
A local profile holds the user's identities and a registry of vaults, each
with (backend, location, identity). All clients (CLI, TUI, desktop, mobile)
read the same registry, so one interface shows many vaults, and a reference
vault://<vault>/<path>#<field> resolves against it. A per-repository
vault.toml names the default vault for that project.
Consequences
- The git backend is the free, self-hosted path and needs no server.
- The hosted backend recovers the two guarantees the format cannot provide (write prevention, read audit) and is the natural paid tier (ADR 0014).
- Anti-rollback (ADR 0006) matters more on dumb backends, where there is no protected branch; the local last-seen head check is mandatory on all backends.
- Multi-vault is a registry feature, not a format feature; a family vault and a project vault differ only in backend and membership.
Alternatives considered
- Git only. Rejected: excludes non-developers and makes the family use case impractical.
- A required central server. Rejected: contradicts the offline-first, self-hostable goal.