watershed Collaborative data structures for Gleam

← watershed · Data structures / Coordination

Coordination

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 FIFO queues and task failover to a quorum-consensus map that won't commit a value until every required client signs off.

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

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

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

PactMap

DDS
pact_map_kernel

A map where a value takes effect only after everyone required agrees.

PactMap has watershed's strictest coordination rule: 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