Deciding who owns what, and agreeing before acting.
The last family arbitrates decisions rather than merging values: who holds a resource, who runs a task, what everyone has agreed to. Reads here are often non-optimistic, because showing an outcome you might lose is worse than showing nothing.
They ascend from first-writer-wins ownership through versioned registers, FIFO queues, and task failover to a quorum-consensus map that will not commit a value until every required client signs off.
The structures from this family that fit the shared gauge rig run
below on watershed’s Gleam kernels. Structures with dedicated
interactions link to their own demos. Pending edits print in
magenta; once the sequencer stamps
an SN, every replica lands the same ink
state. The picker switches among the loaded views, which share one
ordered stream.
Nudge a value, race a concurrent write, or stretch the link latency
to watch each merge rule hold.
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: 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: 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 strike only
removes stockpile entries the striker had seen. Race a strike against a
concurrent delivery and the row survives, with every logged yard.
Re-opening a struck pile brings its ledger back.
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
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
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
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
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
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
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…
Latency and jitter affect simulated arrival order; animation speed
changes playback only. “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.
No. 01
Claims
DDS
claims_kernel
First come, first served ownership of named slots (no takebacks).
A claims register assigns exclusive ownership of named slots. The first client whose claim is sequenced becomes the holder; every later claim is refused against the sequenced holder and its reference sequence number.
Reads are non-optimistic by design: a filed claim never shows as the holder until it wins, so the UI can never display a claim you might lose. Magenta annotates only the in-flight claim. There is no unclaim op; releasing means tearing off a fresh sheet.
Best for
Exclusive resource ownership: locks, seat or room assignment, leader election
Uniqueness constraints (one owner per key, arbitrated by the server)
‘First one wins, no takebacks’ allocation
Merge rule
the first client to claim a slot owns it; every later claim is refused
Optimistic behavior
a claim only shows as yours once it has actually won, never before
Summary shape
who owns what reloads intact
Model
Distributed data structure: converges by server order
No. 02
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
No. 03
OrderedCollection
DDS
ordered_collection_kernel
A shared queue where the first client to grab an item holds it.
An ordered collection is a shared FIFO queue. Items are added, and clients acquire (dequeue) them; add, acquire, complete, and release are non-optimistic and resolve strictly in sequence order.
When two clients race to acquire the same item, the first sequenced acquire holds it and the second resolves empty. The server order is the sole arbiter, so an item is never double-held.
Best for
Work queues and job dispatch with exactly-one-owner semantics
Turn-taking and ordered task handoff between collaborators
Anything needing deterministic FIFO ordering across clients
Merge rule
items come out in the order the server received them; first to grab one holds it
Optimistic behavior
queue changes stay hidden until the server confirms them
Summary shape
the queue and who holds what reload intact
Model
Distributed data structure: converges by server order
No. 04
TaskManager
DDS
task_manager_kernel
Task assignment with a volunteer queue and automatic failover.
TaskManager builds on ordered semantics to coordinate who does what. Clients volunteer for named tasks; the first sequenced volunteer is assigned and later volunteers queue behind them in sequence order.
If the assignee drops, the next queued volunteer takes over automatically. It is the coordination primitive for dividing exclusive work across an unreliable set of collaborators.
Best for
Distributing exclusive tasks across peers (leader-per-task, sharded work)
Failover assignment where a backup should take over automatically
Collaborative apps dividing responsibilities across clients
Merge rule
the first client to volunteer gets the task; the rest wait in line
Optimistic behavior
volunteering only shows once it’s confirmed; one client wins and the rest queue
Summary shape
assignments and the waiting list survive reconnect
Model
Distributed data structure: converges by server order
No. 05
PactMap
DDS
pact_map_kernel
A map where a value takes effect only after everyone required agrees.
A pact map is the strongest coordination structure here: it reaches agreement before committing. Proposing a value and sequencing that set freezes the list of clients who must sign off, and each connected client auto-submits the accept ops it owes.
The value becomes accepted only once the signoff list drains. Concurrent proposals for the same pact resolve to the first sequenced one; the competitor is dropped. The design is modeled after Fluid’s quorum-consensus primitive.
Best for
Agreement before action: schema upgrades, feature-flag flips everyone must honor
Config that must be consistent across all clients before it takes effect
Decisions requiring explicit quorum rather than last-write-wins
Merge rule
a value takes effect only once every required client has signed off
Optimistic behavior
a pending proposal blocks competing ones until it’s accepted or dropped
Summary shape
accepted values and pending sign-offs save and restore together
Model
Distributed data structure: converges by server order
Magenta indicates revisions not yet field-checkedConvergence by server sequencing — assumptions on the models sheettylerbutler.com