kuilt-crdt/us.tractat.kuilt.crdt/GCounter

GCounter

@Serializable

A grow-only counter: a per-replica map of counts that only ever increase. Each replica increments its own slot; piece is elementwise max, so the merged value is the sum of every replica's highest-seen count.

Delta-state: inc does not mutate — it returns a Patch (a tiny GCounter carrying just the bumped slot) that any replica absorbs with piece. This is the first type in the zoo to actually emit a delta.

Because merge is max, two replicas must never increment the same slot concurrently — each replica owns its own ReplicaId slot.

Samples

val a = ReplicaId("A")
val b = ReplicaId("B")

var replicaA = GCounter.ZERO
var replicaB = GCounter.ZERO

// Each replica increments its own slot.
replicaA = replicaA.piece(replicaA.inc(a, 3))
replicaB = replicaB.piece(replicaB.inc(b, 5))

// After merging both deltas, every replica converges to the same value.
val merged = replicaA.piece(replicaB)
check(merged.value == 8L) // 3 + 5

val a = ReplicaId("A")
val b = ReplicaId("B")

val left = GCounter.of(a to 2L, b to 1L)
val right = GCounter.of(a to 1L, b to 3L)
// merge takes max per slot: a→2, b→3
check(left.piece(right) == GCounter.of(a to 2L, b to 3L))