A last-write-wins cell would discard one revision. This one keeps the
disagreement. Race "raise crest" against "arm pump": all three clients
reach the same two alternatives. Nothing is stuck in transit.
Once you've read both, resolve with "raise crest + arm pump".
That's an ordinary write, not a special conflict API. An unseen third
revision would survive it.
Confirmed alternatives stay in ink; your pending revision appears
in magenta. Cut Client B's link, write on both sides, then restore it.
Agreement means every crew sees the same alternatives, not necessarily
a single answer.
Re-deliver keeps an earlier delta even after resolution. The old
revision stays retired. Reset tears off a fresh slate and discards
delayed work from the previous one.
1 · local edit prints in magenta
2 · the sequencer stamps it with an SN
3 · every client lands the same ink state
Merge rule: last write wins. Race two writes to the
same key and the op the sequencer stamps later overwrites the earlier
one, identically on every replica.
Merge rule: timestamp wins per key. A later SN needn't
win: race A's newer “open” against B's later-sequenced “closed”.
At equal time, B's writer ID makes “closed” beat A's “open”; a tombstone
beats either. Unlike SharedMap's server order, arrival
order doesn't choose the value. Both maps discard losing concurrent values.
This is an in-page sequenced rig, not a live mesh.
The runtime supplies wall-clock time and advances it past the key's
observed timestamp. A fast clock can still win over a later human edit.
OR-map's concurrent add survives an observed remove; LWWMap removal wins
only at equal or greater time. LWWMap and LWWRegister both use author
identity to settle equal-time writes.
Reset reloads this survey and discards its queued edits. It's not a
clear or tombstone-pruning API.
Merge rule: increments commute. Race two increments
and both apply. The counter converges on the sum; nothing is
overwritten.
Merge rule: grow-only max per replica. Each client owns
one monotonically increasing tally. Race two inspections or deliver a
delta twice: replicas converge by keeping the maximum count seen for
each author.
Merge rule: deltas join a lattice. Every update
travels as a CRDT delta; merging is commutative and idempotent. Race
it, resend it, deliver it twice: it counts exactly once, and the
balance converges on fill − cut.
Merge rule: timestamp wins; author breaks a tie. Race two
equal-time revisions and every replica picks the same author, regardless
of which delta arrives first.
Merge rule: keep concurrent alternatives. Two revisions
can converge without agreeing on one answer. After both arrive, write
a combined revision to replace the alternatives you've seen.
Merge rule: first writer wins. A claim commits only
if the slot is still unclaimed when the sequencer stamps it (or its
reference SN matches the holder’s exactly). Nothing prints
optimistically: a filed claim is invisible, even to you, until it
round-trips as won or lost.
Merge rule: add-wins, observed-remove. A tally strike
hides the stockpile; re-opening brings its ledger back. Race a strike
against a concurrent delivery and the row survives with every logged yard.
Merge the members, not a replacement array. A and B can
add "draft" and "reviewed" to one document and keep both. Write those as
separate JSON arrays in SharedMap, in the same stream order, and the later
whole value replaces the earlier one: ["reviewed"].
Remove a member to clear its observed tags; remove a key to clear the
observed members as well. An unseen addition survives either race.
Removing the last member leaves an empty set, not a missing key.
Keep the key. Read the disagreement. The OR-map decides
whether a key survives: remove it while another client writes, and that
unseen write keeps the key alive. The MV register inside the key keeps
concurrent alternatives. Neither server order nor a timestamp picks one
for you.
Race two gate revisions, then try Resolve observed.
It combines the selected key's alternatives in one ordinary write,
replacing only what that client has seen. Cut B's link and write there
first: A's resolution can't erase B's unseen revision.
Each OR-map has one homogeneous leaf mode: all tallies,
all LWW registers, all MV registers, or all string sets. This view and the stockpile ledger
are separate instances of the same structure, not mixed values in one map.
Reset reloads this instance's survey and discards its queued edits.
Merge rule: add-wins, observed-remove. Clearing a marker
removes only the add tags this replica had observed. Race a clear against
a concurrent re-mark and the marker remains present because the fresh tag
was unseen by the clear.
Merge rule: grow-only union. Marking a benchmark is a
permanent fact. Race two marks or deliver one twice: the registry only
grows, and duplicate deltas are absorbed.
Merge rule: tombstone wins. A retired marker can never
become active again. Race a re-place against a retire: both replicas keep
the tombstone, and duplicate retire deltas are absorbed.
Merge rule: atomic plus retained versions. A write that
knew the current atomic sequence wins the linearizable slot. Concurrent
losers still append a version, so LWW reads can intentionally diverge from
atomic reads.
Merge rule: FIFO by sequence. Adds enter the queue in
server order. Acquires remove the front item when their op sequences; a
racing acquire may come back empty because the earlier SN already took it.
Merge rule: one assignee, FIFO waiters. Volunteers join
a per-task queue in sequenced order. The first connected volunteer owns the
task; abandon promotes the next waiter, and complete clears the queue.
Merge rule: quorum acceptance. A set first prints as
pending with a frozen signoff list. It becomes accepted only after every
connected client signs off, or leaves drain the list.
Client A
0 pending
Shared map replica on Client A
mill-race
24
kettle-run
61
low-ford
42
sandbags-placed
earthwork-balance · yd³
fill Σ
74
cut Σ
30
cutfill
inspection-count
A Σ
0
B Σ
0
C Σ
0
Gate settings
Confirmed entries, sorted by key
Local view
Confirmed timestamps and tombstones (null)
An empty string is still a value. Removal retains a
timestamped tombstone; a newer ordinary edit can restore the key.
Field note
Confirmed value
Local view
Race uses one timestamp for both writers. The author ID—not arrival order—breaks the tie.
Revision slate
Confirmed alternatives
Local view
Resolve writes "raise crest + arm pump". Any new revision replaces only the history this client has seen.
Gate revisions
Confirmed entries, sorted by key and value
Local view
Sorted doesn't mean preferred. Equal text from two
concurrent writers still counts as two alternatives; an empty
string is a revision, not a removal.
Claims replica on Client A
north-levee
spillway-gate
pump-house
OR-map stockpile ledger replica on Client A
spoil-north
borrow-pit-7
wash-fill
Document checklist
inspection-brief
ConfirmedLocal view
spillway-plan
ConfirmedLocal view
pump-watch
ConfirmedLocal view
OR-set field marker roster replica on Client A
north-stake
sluice-tag
borrow-flag
G-set permanent benchmark registry replica on Client A
BM-17
BM-22
BM-31
2P-set retired marker ledger replica on Client A
stake-3
gate-pin
silt-flag
RegisterCollection replica on Client A
register
atomic
LWW
revise
north-bench
gate-setpoint
pump-mode
OrderedCollection replica on Client A
sheet
state
op
queue
held jobs
PactMap replica on Client A
pact
accepted
pending
op
datum-grid
gate-policy
inspection-window
TaskManager replica on Client A
task
assigned
waiters
op
sluice-inspection
pump-watch
crest-walk
Client B
0 pending
link cut — ops park locally until the link is restored
Shared map replica on Client B
mill-race
24
kettle-run
61
low-ford
42
sandbags-placed
earthwork-balance · yd³
fill Σ
74
cut Σ
30
cutfill
inspection-count
A Σ
0
B Σ
0
C Σ
0
Gate settings
Confirmed entries, sorted by key
Local view
Confirmed timestamps and tombstones (null)
An empty string is still a value. Removal retains a
timestamped tombstone; a newer ordinary edit can restore the key.
Field note
Confirmed value
Local view
Race uses one timestamp for both writers. The author ID—not arrival order—breaks the tie.
Revision slate
Confirmed alternatives
Local view
Resolve writes "raise crest + arm pump". Any new revision replaces only the history this client has seen.
Gate revisions
Confirmed entries, sorted by key and value
Local view
Sorted doesn't mean preferred. Equal text from two
concurrent writers still counts as two alternatives; an empty
string is a revision, not a removal.
Claims replica on Client B
north-levee
spillway-gate
pump-house
OR-map stockpile ledger replica on Client B
spoil-north
borrow-pit-7
wash-fill
Document checklist
inspection-brief
ConfirmedLocal view
spillway-plan
ConfirmedLocal view
pump-watch
ConfirmedLocal view
OR-set field marker roster replica on Client B
north-stake
sluice-tag
borrow-flag
G-set permanent benchmark registry replica on Client B
BM-17
BM-22
BM-31
2P-set retired marker ledger replica on Client B
stake-3
gate-pin
silt-flag
RegisterCollection replica on Client B
register
atomic
LWW
revise
north-bench
gate-setpoint
pump-mode
OrderedCollection replica on Client B
sheet
state
op
queue
held jobs
PactMap replica on Client B
pact
accepted
pending
op
datum-grid
gate-policy
inspection-window
TaskManager replica on Client B
task
assigned
waiters
op
sluice-inspection
pump-watch
crest-walk
Client C
0 pending
Shared map replica on Client C
mill-race
24
kettle-run
61
low-ford
42
sandbags-placed
earthwork-balance · yd³
fill Σ
74
cut Σ
30
cutfill
inspection-count
A Σ
0
B Σ
0
C Σ
0
Gate settings
Confirmed entries, sorted by key
Local view
Confirmed timestamps and tombstones (null)
An empty string is still a value. Removal retains a
timestamped tombstone; a newer ordinary edit can restore the key.
Field note
Confirmed value
Local view
Race uses one timestamp for both writers. The author ID—not arrival order—breaks the tie.
Revision slate
Confirmed alternatives
Local view
Resolve writes "raise crest + arm pump". Any new revision replaces only the history this client has seen.
Gate revisions
Confirmed entries, sorted by key and value
Local view
Sorted doesn't mean preferred. Equal text from two
concurrent writers still counts as two alternatives; an empty
string is a revision, not a removal.
Claims replica on Client C
north-levee
spillway-gate
pump-house
OR-map stockpile ledger replica on Client C
spoil-north
borrow-pit-7
wash-fill
Document checklist
inspection-brief
ConfirmedLocal view
spillway-plan
ConfirmedLocal view
pump-watch
ConfirmedLocal view
OR-set field marker roster replica on Client C
north-stake
sluice-tag
borrow-flag
G-set permanent benchmark registry replica on Client C
BM-17
BM-22
BM-31
2P-set retired marker ledger replica on Client C
stake-3
gate-pin
silt-flag
RegisterCollection replica on Client C
register
atomic
LWW
revise
north-bench
gate-setpoint
pump-mode
OrderedCollection replica on Client C
sheet
state
op
queue
held jobs
PactMap replica on Client C
pact
accepted
pending
op
datum-grid
gate-policy
inspection-window
TaskManager replica on Client C
task
assigned
waiters
op
sluice-inspection
pump-watch
crest-walk
Sequencer
Loading
booting watershed kernels…
Jitter can change simulated arrival order; animation speed changes
playback only. Each moving request shows its sampled hop latency. “Ops in
flight” counts every hop still travelling: one
client → sequencer leg, then one
sequencer → replica leg per client.
The live demo couldn't start: it runs watershed's runtime counter channel
and kernels as compiled JavaScript modules, and this browser didn't load
them. The rest of the page works fine without it. Reload the page to retry.
A list isn't a queue
mv_register_values returns a result containing a sorted
List(String). The order is for display, not priority.
A fresh register reads []; writing an empty string reads
[""]. There's no delete hidden in that spelling.
Two concurrent writes of the same text still produce two entries.
Don't deduplicate them and mistake that for causal agreement. A fresh
write after observing both replaces both, even if its text is unchanged.
The clock advances, though no visible-value event need fire.
One typed field on the sequenced stream
The JavaScript facade's ensure callback returns an MvRegister
handle. Ensure waits for synchronization before looking up or creating
the field; it doesn't make the next user write wait for acknowledgement.
The read below includes that optimistic write. On the BEAM,
watershed_beam has the corresponding typed API with blocking
ensures and subject subscriptions.
pub type RevisionSheetpub fn revision() -> schema.ChannelField( RevisionSheet, schema.MvRegisterChannel,) { schema.channel_field("revision")}pub fn ensure_and_revise( document: watershed.Document(RevisionSheet), text: String, done: fn(Result(List(String), String)) -> Nil,) -> Nil { // Ensure waits for synchronization before it reads or creates the field. use ensured <- watershed.ensure_mv_register( document, watershed.root_typed(document), revision(), ) let values = { use register <- result.try(ensured) watershed.mv_register_set(register, text) watershed.mv_register_values(register) |> result.map_error(fn(_) { "Could not read revision alternatives" }) } done(values)}
Or let the peers exchange revisions
A CRDT document can use this register as its root. Connect with this
configuration, then use the document delivered by a successful readiness
callback. If you're filling a missing default rather than handling a
user edit, wait for readiness and inspect the synchronized value first:
an early seed can become a concurrent alternative.
pub fn configure( signaling: Signaling,) -> crdt_js.Config(schema.MvRegisterChannel) { crdt_js.config( room_id: "revision-slate", replica_label: "field-crew", compatibility_tag: "revision-slate/v1", root: p2p.mv_register_root(), signaling: signaling, ) |> crdt_js.with_transport_policy(crdt_js.P2pOnly)}// Call after readiness succeeds. Use this for an intentional user edit.pub fn revise( document: crdt_js.CrdtDocument(schema.MvRegisterChannel), text: String,) -> Result(List(String), p2p.P2pError) { let register = crdt_js.root(document) use _ <- result.try(crdt_js.mv_register_set(register, text)) crdt_js.mv_register_values(register)}
The merge example is a regression, too
This is the kernel test the suite runs, not a second merge implementation
written for the page. A and B author independently, observe each other's
alternatives, then A writes a combined revision. An unseen C would not
be superseded: resolution covers only the history the writer observed.
test/watershed/mv_register_kernel_test.gleam
pub fn concurrent_writes_survive_until_observed_resolution_test() -> Nil { let #(a, _, write_a, id_a) = mv.set(mv.new(replica_id.new("a")), "raise crest") let #(b, _, write_b, id_b) = mv.set(mv.new(replica_id.new("b")), "arm pump") let assert Ok(a) = mv.ack_local_with_message_id(a, write_a, id_a) let assert Ok(b) = mv.ack_local_with_message_id(b, write_b, id_b) let #(a, _) = mv.apply_remote(a, write_b) let #(b, _) = mv.apply_remote(b, write_a) mv.values(a) |> expect.to_equal(["arm pump", "raise crest"]) mv.values(b) |> expect.to_equal(["arm pump", "raise crest"]) let #(a, _, resolved, resolved_id) = mv.set(a, "raise crest + arm pump") let assert Ok(a) = mv.ack_local_with_message_id(a, resolved, resolved_id) let #(b, _) = mv.apply_remote(b, resolved) mv.values(a) |> expect.to_equal(["raise crest + arm pump"]) mv.values(b) |> expect.to_equal(["raise crest + arm pump"])}
Return to the MvRegister field
sheet, or compare RegisterCollection, which maintains atomic and last-write-wins views using server sequence
numbers, and PactMap, which
waits for a frozen quorum's protocol acknowledgements. None of those
acknowledgements means a person approved a revision. Here, the application
decides when and how to offer a resolving write.
Magenta indicates revisions not yet field-checkedConvergence by server sequencing — assumptions on the models sheettylerbutler.com