Skip to content

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.