WarpStats

A CRDT-mergeable statistics map: per-source cardinality sketches gathered as HyperLogLog instances, so they converge when gossiped on the same anti-entropy as the rest of the warp state.

Lattice laws. piece is a join-semilattice operation: for every source key the register arrays are merged element-wise via HyperLogLog.piece (itself element-wise max). The key set is add-only (no removal). Together these make piece idempotent, commutative, and associative — convergence is unconditional.

Delta-state gossip. observe returns a Patch whose delta contains only the single changed source's sparse HLL fragment; it is a valid lattice fragment and can be forwarded directly to Quilter without carrying the full state.

Read API for the E-3 cost model. estimatedCardinality returns the HLL estimate for a given source (0 when the source has never been observed). The estimate is within ~0.81% relative standard error at the default HLL precision of 14.

No networking in this type. WarpStats is a pure CRDT value — no Seam, no coroutines. Gossip transport is the us.tractat.kuilt.quilter.Quilter's job; this class only defines what gets gossiped.

See also

Samples

val src = OpId("source.docs")

// Observe 100 distinct elements.
var stats = WarpStats.empty()
for (i in 1..100) stats = stats.piece(stats.observe(src, "doc_$i"))

// estimatedCardinality is a HyperLogLog sketch — within ~0.81% relative error.
val estimate = stats.estimatedCardinality(src)
check(estimate in 90L..110L) { "expected ~100, got $estimate" }

// Unseen sources return 0.
check(stats.estimatedCardinality(OpId("source.other")) == 0L)

// Two replicas that observed different halves converge to the same answer.
var replicaA = WarpStats.empty()
for (i in 1..50) replicaA = replicaA.piece(replicaA.observe(src, "doc_$i"))
var replicaB = WarpStats.empty()
for (i in 51..100) replicaB = replicaB.piece(replicaB.observe(src, "doc_$i"))

val merged = replicaA.piece(replicaB)
check(merged.estimatedCardinality(src) == stats.estimatedCardinality(src)) {
    "merging two halves must equal observing all at once"
}