leafsleep-ADR-001 - Sharded Sleep State Machine, Idempotent Epoch CAS, and Hybrid Direct/Database Sync¶
Status: Accepted Date: 2026-10-27
Context¶
LeafSleep is the sharded sequel to OnePlayerSleep. Classic OnePlayerSleep assumes a single-JVM, single-threaded World where player counts, bed-enter/leave events, and world-clock transitions are local and synchronous.
On modern survival networks, a single logical world is frequently sharded across:
1. Intra-JVM regional tick threads (Folia): Players in the same dimension tick on independent regional threads (Rule F-001..F-003).
2. Cross-JVM server shards (Paper, Folia, Fabric, NeoForge behind Velocity): Multiple backend servers host regions or instances of the same logical Overworld (shardGroupId, e.g., overworld-main).
Two distinct data-plane velocities are required for cross-shard sleep:
- Interactive sleep/cancel coordination (BED_ENTER, BED_LEAVE, SLEEP_VOTE, CANCEL_SLEEP, EPOCH_COMMIT) must propagate in < 50 ms so countdowns, quorum tallies, and [Cancel] clicks feel instantaneous.
- Persistent player state and epoch watermarks (sleepIgnored opt-out flags, wakeup message preferences, personal sleep/cancel counters, cooldowns, and last-committed targetDayEpoch) belong in a shared SQL database (SQLite, MySQL, MariaDB, PostgreSQL) so state survives server switches and restarts without blocking tick threads.
Decision¶
Implement a deterministic sharded quorum and epoch state machine (ShardSleepCoordinator) in leafsleep-common, backed by a hybrid Direct Messaging Bus (fast transient state) and an Asynchronous SQL Store (durable player and epoch state).
1. ShardGroup Quorum Aggregation & Warmup Window¶
- Each configured world maps to a logical
shardGroupId(defaulting to the local world name when unsharded, or a shared cluster identifier such asoverworld-main). - Each shard tracks its local
(eligibleCount, sleepingCount, ignoredCount)from platform-neutralPlayerSleepSnapshotrecords (excluding AFK, vanished, Creative/Spectator, orsleepIgnoredplayers per config) and broadcasts delta frames to peers in the sameshardGroupId. ShardSleepCoordinatorevaluates the aggregated counts across all live shards inshardGroupIdagainst the configured policy:ONE_PLAYER(classic 1-player sleep across the entire shard group)PERCENTAGE(e.g.,25%of eligible players across all shards in the group)FIXED_COUNT(e.g.,Nsleeping players across the group)ABSOLUTE_MAJORITY(> 50%of eligible players)- When quorum is met, a configurable
warmupDelayTickscountdown begins. During the warmup window, any player withleafsleep.cancel(via/sleep cancelor clickable chat[Cancel]) aborts the pending skip across all shards in the group, optionally waking sleeping players and applying a cancel cooldown.
2. Idempotent targetDayEpoch Transition (Split-Brain Prevention)¶
- When the warmup completes with quorum intact, the coordinating shard emits
EPOCH_COMMIT(shardGroupId, targetDayEpoch, targetDayTimeTicks, clearWeather)wheretargetDayEpoch = currentFullTime / 24000L + 1. - Every shard in
shardGroupIdappliesEPOCH_COMMITidempotently using an atomic high-water mark (if (targetDayEpoch <= lastCommittedDayEpoch) return;CAS): - Advances the world clock to
targetDayTimeTicks(dawn) and clears weather on the global region thread. - Resets
TIME_SINCE_RESTfor eligible online players on their owning entity threads so Phantoms do not spawn on any shard after a group night skip. - Dispatches weighted random wakeup messages and
effects-apiwakeup buffs/sounds/particles locally. - Periodic
SHARD_HEARTBEATframes and SQL epoch watermarks reconcile world clocks for newly booted or reconnecting shards.
3. Hybrid Transport & Storage Plane¶
- Fast Path — Direct Messaging Bus (
SleepSyncTransport): - Supports
DIRECT_SOCKET(HMAC-signed TCP/UDP peer gossip for fastest direct server-to-server delivery),PLUGIN_MESSAGING(leafsleep:syncwith optionalleafsleep-velocityproxy fanout),REDIS_PUBSUB, andLOCAL_ONLY. - Protected per player and per shard by
BudgetPacer(api/predict-api) to prevent bed-click spam from amplifying across the network. - Durable Path — Async SQL Database (
SleepDatabaseStore): - Supports
SQLITE(default single-server file DB) andMYSQL/MARIADB/POSTGRESQLvia lightweight connection pooling. - All queries and writes execute strictly off the tick thread (
TaskScheduler#runAsync): player profiles warm-load onPlayerLifecycleHook#onPlayerJoinand flush write-behind on mutation;shard_group_epochspersists the latest committedtargetDayEpochand world clock watermark.
Alternatives Considered¶
| Alternative | Why Rejected |
|---|---|
| Database-polling only for sleep synchronization | Polling SQL every tick adds 50-500 ms latency and unnecessary DB load during interactive bed-enter and cancel windows. |
| Direct messaging only (no SQL persistence) | Loses player ignore/opt-out preferences, cooldowns, and targetDayEpoch watermarks when players switch servers or a shard restarts. |
| Unbounded or unversioned time-skip broadcasts | Without a monotonic targetDayEpoch CAS guard, two shards reaching quorum on the same tick would double-advance the world clock. |
Consequences¶
- Positive:
- Sub-50ms cross-shard bed-enter, vote, and cancel responsiveness via direct messaging.
- Durable cross-server player preferences, cooldowns, and epoch recovery via async SQL.
- Zero double-skips or clock oscillation under concurrent multi-shard quorum commits.
- Negative / Trade-offs:
- Direct peer UDP/TCP or plugin-messaging deployments require a shared HMAC secret or proxy channel configuration when running across multiple hosts.
References¶
ADR-002(Multi-Platform Carrier Architecture viaServerAccessor,OnePlayerSleepConfiguration Superset, and[OPS bit])api/predict-api(BudgetPacer)