feat(state): add validated persistent game state

design/log.md

@@ -6,6 +6,17 @@ description: Chronological record of material decisions affecting the Spigot Tyr
 
 # Spigot Tyrant Design Log
 
+## 2026-08-14 — Configuration and persistence completed
+
+- Completed US-012 with validated defaults for ranges, timers, effects, items, messages, and mob restrictions, including runtime Bukkit section parsing.
+- Added immutable lifecycle and player state for roles, dual-alignment classes, progression, participation, cooldowns, bound items, and captured mobs.
+- Added RFC 3339 UTC timestamp persistence, paused deadline shifting, atomic YAML replacement, invalid-record rejection, unknown-field preservation, periodic saves, and shutdown saves.
+- Verified all state, settings, bundled configuration, corruption, forward-compatibility, and pause-time tests with `./gradlew clean check jar`.
+
+## 2026-08-14 — Configuration and persistence implementation started
+
+- US-012 begins with test-first validated defaults, immutable UUID-keyed domain state, paused-time-aware clocks, and defensive atomic YAML persistence.
+
 ## 2026-08-14 — Build and release foundation completed
 
 - Completed US-013 with a Java 17 Gradle build, Spigot 26.2 API, strict compiler linting, JUnit 5 and Mockito dependencies, plugin metadata, and a minimal plugin entrypoint.

design/user-stories/us-012-configure-and-persist-state.md

@@ -2,7 +2,7 @@
 type: User Story
 title: "US-012: Configure and persist game state"
 description: Give operators validated configuration and durable defensive storage for all Tyrant behavior.
-status: backlog
+status: done
 ---
 
 # US-012: Configure and persist game state
@@ -11,15 +11,15 @@ As a **server operator**, I want configurable and durable game behavior so that
 
 ## Acceptance criteria
 
-- [ ] Configuration covers ranges, durations, cooldowns, inactivity periods, candidate windows, retry intervals, effect levels and caps, mob restrictions, item materials and names, messages, and timer behavior.
-- [ ] Defaults match the approved user stories, including a 50-block Tyrant range and Follower range, seven-day opt-out, 48-hour inactivity, and 24-hour candidate windows.
-- [ ] Invalid required configuration prevents partial plugin initialization and produces a clear server log message.
-- [ ] UUID-keyed state stores lifecycle, current and pending roles, assignments, login history, participation, reign progression, purchases, choices, cooldowns, paused time, item delivery, and captured mobs.
-- [ ] Cooldowns and deadlines use UTC instants and exclude administratively paused time.
-- [ ] State is saved using atomic replacement where supported so failed writes do not replace valid state with partial data.
-- [ ] Corrupt, unknown, or invalid records cannot silently grant progression, roles, powers, items, or duplicated mobs.
-- [ ] Unknown forward-compatible configuration and state fields are preserved where practical.
-- [ ] Plugin disable removes transient effects and presentation safely while preserving durable state.
+- [x] Configuration covers ranges, durations, cooldowns, inactivity periods, candidate windows, retry intervals, effect levels and caps, mob restrictions, item materials and names, messages, and timer behavior.
+- [x] Defaults match the approved user stories, including a 50-block Tyrant range and Follower range, seven-day opt-out, 48-hour inactivity, and 24-hour candidate windows.
+- [x] Invalid required configuration prevents partial plugin initialization and produces a clear server log message.
+- [x] UUID-keyed state stores lifecycle, current and pending roles, assignments, login history, participation, reign progression, purchases, choices, cooldowns, paused time, item delivery, and captured mobs.
+- [x] Cooldowns and deadlines use UTC instants and exclude administratively paused time.
+- [x] State is saved using atomic replacement where supported so failed writes do not replace valid state with partial data.
+- [x] Corrupt, unknown, or invalid records cannot silently grant progression, roles, powers, items, or duplicated mobs.
+- [x] Unknown forward-compatible configuration and state fields are preserved where practical.
+- [x] Plugin disable removes transient effects and presentation safely while preserving durable state.
 
 ## Related