Skip to content

0004: Write-once, content-addressed repository layout

  • Status: accepted
  • Date: 2026-09-22
  • Amended by: 0046 (policy records are named by slot, policy/<seqno>.pol, not by content hash), 0052 (the epochs/ line of the layout gains the <link> segment)
  • See also: 0041 (in-repo vaults sync on a dedicated branch, where this layout makes sync a tree union)

Context

Git merges are conflict-free when two branches add different files and conflict when they modify the same file. A vault used by a team on git, or synchronised through a shared folder, must never produce a merge conflict and must never lose a write.

Decision

No file in the vault directory is ever modified after creation, and every file's name is derived from its content. Same content means same path; different content means different path. Deletion of an entry is a tombstone event, not a file removal.

Layout:

.vaultfold/
  vault.json                  format version, vault id, genesis suite ids,
                              root collection; written once at init
  .gitattributes              ** -text -diff -merge binary
  keys/<keyid>.key            device public key + member, signed (ADR 0008)
  epochs/<collection-id>/<epoch>/<link>/<keyid>.wrap
                              KEK wrapped to a device key (ADR 0003);
                              <link> is the first 16 hex characters of
                              the id of the policy link that calls for
                              the wrap (ADR 0052)
  events/<xx>/<hash>.evt      encrypted, signed event (ADR 0005)
  policy/<seqno>.pol          signed policy record at its slot, seqno as
                              20 zero-padded decimal digits (ADR 0046)
  heads/<keyid>.head          optional, written only by that device (ADR 0006)

Rules:

  • Hashes are BLAKE3, rendered as lowercase hex. Base64 is forbidden in file names because case-insensitive filesystems (macOS, Windows) would collide A3f with a3F.
  • Event files are sharded by the first two hex characters of their id to avoid very large directories and Windows path-length limits. Policy files are few and are not sharded.
  • .gitattributes marks every file binary with no text conversion, no diff and no merge driver, so that autocrlf and smudge filters cannot corrupt ciphertext.
  • vault.json is written once at init and is never modified: it carries the format version, the vault id, the genesis suite ids and the root collection. Everything mutable (collections, members, roles) lives only in the signed policy chain, never in vault.json.
  • Snapshots of the folded state are ordinary events under events/, not a separate directory (ADR 0007).
  • There is no index, manifest, latest pointer or shared head file. The optional heads/<keyid>.head file is written only by the device that owns that key. Current state is derived by folding the event set (ADR 0005). Clients keep a local cache of the fold outside the repository, encrypted under a machine key.
  • Last-seen heads for anti-rollback are stored locally (ADR 0006).

Consequences

  • Two clients can always merge, in git or by copying directories; the union of two valid vault directories is a valid vault directory. ADR 0041 relies on this: a sync of a vault branch is a tree union on the fetched tip.
  • The format is safe in synchronised folders (iCloud Drive, Dropbox) where a git repository would corrupt, which enables the dumb-blob-store backends of ADR 0010.
  • File count grows without bound until compaction (ADR 0007). Sharding and snapshots keep this practical.
  • Repository size leaks entry count and activity volume (see threat-model.md).

Alternatives considered

  • One file per entry, rewritten on change. Rejected: conflicts on concurrent edits and history of values is lost or left to git.
  • A single encrypted database file. Rejected: every write conflicts.
  • Custom git merge driver. Rejected: does not help non-git backends and requires per-clone setup.