barrel_version (barrel_docdb v1.0.0)
View SourceDocument versions: an HLC timestamp plus the id of the database that authored the write.
Versions replace rev-tree revisions ("Gen-Hash") as the identity of a document write. The HLC gives causally meaningful last-write-wins ordering; the author id breaks ties deterministically and identifies the writer. Authorship is per-database (each database carries a source id, see barrel_db_server), not per-node: two databases on one node share the HLC clock, so node-level authorship would totally order their writes and hide concurrency. The API _rev token is <hex(hlc)>@<author>: the hex is fixed width, so lexicographic token order equals causal order.
The winner among sibling versions is the maximum under compare/2, a commutative rule: any replica that sees the same version set picks the same winner.
Summary
Functions
Total order over versions: HLC first, author id as tie-break.
Decode a storage-encoded version.
Storage encoding: fixed-width HLC first, author id after, so the version parses from the front and sorts by HLC.
Parse an API token back to a version.
The greater of two versions (the deterministic winner rule).
A version at a given HLC authored by an explicit identity (the authoring database's source id).
API token: <hex(hlc)>@<author>. Author ids (lowercase hex) can never contain @.
Types
-type token() :: binary().
API form: <<"0000018abc...@f1e061a70714abcd">>
-type version() :: {barrel_hlc:timestamp(), binary()}.
{WriteHlc, AuthorId}
Functions
Total order over versions: HLC first, author id as tie-break.
Decode a storage-encoded version.
Storage encoding: fixed-width HLC first, author id after, so the version parses from the front and sorts by HLC.
Parse an API token back to a version.
-spec hlc(version()) -> barrel_hlc:timestamp().
The greater of two versions (the deterministic winner rule).
-spec new(barrel_hlc:timestamp(), binary()) -> version().
A version at a given HLC authored by an explicit identity (the authoring database's source id).
API token: <hex(hlc)>@<author>. Author ids (lowercase hex) can never contain @.