watershed Collaborative data structures for Gleam

← watershed · Data structures / Registers

Registers

One shared value, and three different answers to a race.

A register is the smallest place collaboration can still go wrong: one cell, two writers, and no neutral meaning of “last.” The interesting part isn't storage. It's the rule that decides what survives.

LWWRegister trusts timestamp and replica identity to select one winner without caring about delivery order. MvRegister refuses the forced choice and keeps concurrent answers until a writer who has seen them resolves them. RegisterCollection keeps every server-sequenced version so each read can choose the first uncontested write or the latest one.

LWWRegister

CRDT
lww_register_kernel

One shared string where the newest timestamp wins—and the author breaks a tie.

A last-writer-wins register stores one string plus the timestamp and replica ID that wrote it. Every replica merges by choosing the greater timestamp; if two writers use the same timestamp, the greater replica ID breaks the tie.

That makes delivery order irrelevant, but it also makes the clock part of the data. The demo races two equal-time revisions, then re-delivers the winning delta: every client keeps the same winner and the duplicate changes nothing.

Best for

  • Offline settings where one deterministic winner is preferable to preserving every conflict
  • Small shared labels, modes, or status fields with trustworthy logical clocks
  • Cases where arrival order must not decide the winner
Merge rule
the highest timestamp wins; equal timestamps break by replica ID, not arrival order
Optimistic behavior
your revision appears immediately while its timestamp waits to merge
Summary shape
the winning value, timestamp, and author reload together
Model
Conflict-free replicated data type: converges by merge

MvRegister

CRDT
mv_register_kernel

One cell, several answers: concurrent revisions stay until someone resolves them.

Open the revision slate and API notes →

Last-write-wins picks a winner. A multi-value register keeps the disagreement: two offline authors can write different revisions and every replica converges on both. The returned list is sorted for display, not ranked by time or preference.

Resolution is an ordinary write after reading the alternatives. It replaces those observed revisions, not an unseen third writer. Equal text from concurrent authors still occupies two entries; an empty string is a value, not deletion.

Best for

  • Offline settings where silently dropping a revision would be a mistake
  • Review workflows that ask a person to combine concurrent answers
  • One shared string with an explicit conflict-resolution step
Merge rule
keep concurrent writes; a new write replaces only the history its author has seen
Optimistic behavior
your revision appears in magenta while the confirmed alternatives stay in ink
Summary shape
tagged alternatives and the full causal clock survive reload, including retired history
Model
Conflict-free replicated data type: converges by merge

RegisterCollection

DDS
register_collection_kernel

Single-value cells you can read as first-writer-wins or most-recent-wins.

A register holds a single value with two read strategies. An atomic read resolves the first non-concurrent writer (a consensus-flavored pick). A last-write-wins read returns the most recent version by sequence number.

Concurrent versions are retained with their sequence numbers, so either policy can be applied at read time. Writes stay invisible until sequenced, then resolve as atomic winners or as retained versions.

Best for

  • Single-value cells that need a choice of conflict policy per read
  • Config or setpoint values where you sometimes want first-writer, sometimes latest
  • A coordination building block where retained versions matter
Merge rule
read the first uncontested write, or the most recent one (your choice, per read)
Optimistic behavior
writes stay hidden until confirmed, then settle as the winner or a kept version
Summary shape
every competing version is kept, so either read rule still works later
Model
Distributed data structure: converges by server order