How revisions work
Three rules cover the whole model. Once they click, everything else follows.
1. An entry has one identity and many versions
Every entry has a stable identity that never changes — the same entry "is" the same entry from creation to deletion. On top of that identity sit numbered versions. Version 1 is the original. Every change adds the next version. The identity is the entry; the versions are its history.
2. A change adds a version — it never edits one
Update a password, rename a field, add a URL — each is a brand-new revision written on top. The earlier revisions are never modified and never deleted. This is why the history is trustworthy: there is no code path that rewrites the past, by design.
Scope changes (who can see an entry) and edits both create revisions. The one thing that doesn't is marking a credential as confirmed working after a successful login — that's recorded on the current version as usage, not a content change. (More in How it works.)
3. Reading returns the latest version
When you open an entry, the CLI fetches a value, or the browser extension fills a form, Clavitor returns the highest version — the current state. The history is there when you ask for it, and invisible when you don't. You never have to think about versions to use the vault normally.
What a revision carries
Each revision is a full, self-contained snapshot of the entry at that moment:
| Part | What it records |
|---|---|
| Version | its position in the history (1, 2, 3 …) |
| When | the time this revision was written |
| Values | the fields, URLs, and metadata as they stood |
| State | normal, or a tombstone if this is the deletion |
Because every revision is complete, viewing history is just reading the stack — no reconstructing, no replaying a log of diffs.