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 (theepochs/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
A3fwitha3F. - 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.
.gitattributesmarks every file binary with no text conversion, no diff and no merge driver, so that autocrlf and smudge filters cannot corrupt ciphertext.vault.jsonis 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 invault.json.- Snapshots of the folded state are ordinary events under
events/, not a separate directory (ADR 0007). - There is no index, manifest,
latestpointer or shared head file. The optionalheads/<keyid>.headfile 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.