BoundedCounterTransferCoordinator

Coordinator that automatically rebalances BoundedCounter quota across peers over a Seam.

Role

BoundedCounter's BoundedCounter.trySpend enforces local quota without coordination. When quota runs low, however, a replica needs to obtain quota from peers. This coordinator provides that active rebalancing.

Protocol

Requester side (targeted borrow): when BoundedCounter.quota for self drops to or below BoundedCounterTransferConfig.lowWaterThreshold, a BoundedCounterCoordMessage.TransferRequest is sent via Seam.sendTo to the top-BORROW_FAN_OUT surplus peers, computed locally from BoundedCounter.quota(peerId) over the connected peer set — so it is partition-safe and needs no global roster. Only reachable peers (in Seam.peers) are considered. The coordinator retries up to BoundedCounterTransferConfig.maxRetries times with exponential backoff. If no transfer arrives, the requester degrades gracefully — BoundedCounter.trySpend continues to deny locally.

Donor side: on receiving a BoundedCounterCoordMessage.TransferRequest, this replica evaluates its own surplus (quota(self) - surplusFloor). If positive, it calls BoundedCounter.transfer and passes the resulting Patch to applyTransfer, which broadcasts the state delta via Quilter. The state update then propagates via the existing delta-replication path — there is no explicit response message.

Safety invariant

The transfer request is advisory and does not bypass BoundedCounter.trySpend. The local quota check on BoundedCounter.trySpend is the ultimate gatekeeper — it is the only place where "spend" is committed, and it always uses the current merged state. A transfer that hasn't propagated yet cannot unlock a BoundedCounter.trySpend — quota is only available once the state delta arrives and is merged.

Two concurrent donors responding to the same request compose correctly: each writes its own row of the transfer matrix (per BoundedCounter.transfer's design), so there is no collision. The requester simply receives more quota than it asked for, which is safe.

Multiplexing

The coordinator receives frames from a us.tractat.kuilt.core.MuxSeam channel — a Seam view that carries only frames tagged with its assigned byte prefix. This avoids a second collection of the underlying seam's Seam.incoming flow (which is single-collection by contract).

Proactive equalizer (optional)

When equalizerConfig is non-null, a periodic background task fires on each tick and transfers surplus quota to the single lowest-quota reachable peer. The equalizer's goal is to keep quotas near the fair share (bound / liveN) so low-water events rarely fire under stable load. It skips ticks where this replica's surplus over the fair share is within BoundedCounterEqualizerConfig.minImbalanceThreshold — avoiding idle noise.

The equalizer is optional = tuning, not a functional gate: passing null (the default) leaves the reactive targeted-borrow path fully correct. The equalizer only reduces how often reactive borrows fire.

Parameters