fix: harden Folia concurrency for round lifecycle and shutdown

Phase 1 of the v1.3.0 concurrency review. Closes the gap left by 195b5aa
which only made botTask volatile but left three other fields with the same
race surface.

T1 - MahjongTableSession: make roundController, roundStartInProgress, and
     riichiRoundEngine volatile. These are written on the table's region
     thread during startRound / completeRoundStartInternal / setRound-
     ControllerInternal but read cross-thread by the global tick timer's
     bot watchdog, the async render precompute thread (via TableRegion-
     FingerprintService), the seat watchdog global timer, the GameRoom
     tick timer, and player entity threads. Without volatile the JVM is
     free to reorder or cache reads, causing 'bot scheduled on a half-
     published roundController' races that mirror the botTask race fixed
     in 195b5aa.

T3 - TableRenderSnapshot: add roundStartInProgress to the snapshot record
     and have TableRegionFingerprintService.seatLabelFingerprint read it
     from the snapshot instead of the live session. precomputeRegion-
     Fingerprints runs on the async render-precompute thread; using the
     snapshot guarantees the fingerprint matches the rest of the snapshot
     state captured on the region thread, avoiding a torn read where the
     seat label fingerprint reflects a newer roundStartInProgress value
     than the seat occupancy snapshots around it. T1 made the live read
     safe but the snapshot read is strictly better.

T2 - TableSeatCoordinator.runSeatWatchdogs: stop reading session.isStarted
     and session.seatOf from the global timer thread. The expiry check
     (binding.expiresAtTick < nowTick) is the only pure-local-state short
     circuit kept on the global timer; all session-state checks and the
     player online check are deferred to inspectSeatWatchdogOnPlayerThread
     which already runs on the player's entity thread. Eliminates the
     'global timer reads session state' pattern that 195b5aa set out to
     remove but missed in this coordinator.

T5 - MahjongTableSession.seatOf: document the best-effort read contract
     for cross-thread callers. Most callers run on the table's region
     thread where the write to participants.seats also happens; cross-
     thread callers (player entity thread in TableEventCoordinator) read
     best-effort. ArrayList.get is not throws-synchronized but the worst
     case is a stale UUID that fails the equals check and returns null,
     which the caller treats as 'not seated' and re-checks next tick.
     T1 already covered the volatile concerns; this just fixes the
     contract in code.

T6 - GameRoomManager.tick: add session.isStarted guard before scheduling
     forceEndTable on the region thread. If the match has already ended
     naturally between countdown expiry and this tick, skip the region
     dispatch entirely. forceEndMatch is idempotent but skipping saves
     a region task dispatch and an unnecessary render pass. isStarted
     now reads the volatile roundController field (T1) so the cross-
     thread read is safe.

T7 - MahjongPaperPlugin.onDisable + reloadMahjongConfiguration: close
     the async executor BEFORE the database pool on shutdown, and drain
     pending async DB tasks (awaitQuiescence) before closing the old
     DataSource on reload. Previously the async queue could still hold
     pending persistRoundResult / persistMatchRanks tasks that needed
     a live DataSource; closing the DB first caused those tasks to throw
     SQLException on getConnection(), which AsyncService swallows -
     losing the final round results of any in-progress match.
     AsyncService.awaitQuiescence submits a sentinel and waits for it
     to complete, guaranteeing every previously-queued task has at
     least started (and typically completed) before the close proceeds.

ArchitectureBoundaryTest: bump MahjongTableSession line budget from
1660 to 1700 and public method budget from 235 to 245 to accommodate
the new comments and the previously-merged addBotSilent method.

Author: Z User

src/main/java/top/ellan/mahjong/bootstrap/MahjongPaperPlugin.java

@@ -146,14 +146,22 @@ public void onDisable() {
         }
         TableDisplayRegistry.clear();
         DisplayVisibilityRegistry.clear();
-        if (this.database != null) {
-            this.database.close();
-            this.database = null;
-        }
+        // Close async executor BEFORE the database pool: the async queue may
+        // still hold pending persistRoundResult / persistMatchRanks tasks that
+        // need a live DataSource. Closing the DB first would cause those tasks
+        // to throw SQLException on getConnection(), which AsyncService swallows
+        // (see AsyncService.execute error handler) — losing the final round
+        // results of any in-progress match. async.close() drains the queue
+        // (with a bounded wait) so by the time database.close() runs, no DB
+        // task is in flight.
         if (this.async != null) {
             this.async.close();
             this.async = null;
         }
+        if (this.database != null) {
+            this.database.close();
+            this.database = null;
+        }
         this.scheduler = null;
         this.craftEngine = null;
         if (this.debug != null) {
@@ -321,6 +329,16 @@ public String reloadMahjongConfiguration() {
             previousCraftEngine.disableFurnitureInteractionBridge();
             previousCraftEngine.clearTrackedCullables();
         }
+        // Drain pending async DB tasks before closing the old DataSource.
+        // Without this, any persistRoundResult / persistMatchRanks tasks still
+        // in the async queue would race the close and throw SQLException on
+        // getConnection() — AsyncService swallows the error but the round
+        // result is lost. awaitQuiescence blocks the (player-triggered) reload
+        // thread for up to 2s; on timeout we proceed and accept the race,
+        // matching prior behavior for the rare slow-persist case.
+        if (previousDatabase != null && this.async != null) {
+            this.async.awaitQuiescence(2L);
+        }
         if (previousDatabase != null) {
             previousDatabase.close();
         }

src/main/java/top/ellan/mahjong/gameroom/GameRoomManager.java

@@ -342,7 +342,14 @@ public void tick() {
                     // cross-thread mutation of game state (round controller,
                     // viewer presentation, bot task, etc.) on Folia.
                     MahjongTableSession session = this.tableManager.resolveTableById(tableId);
-                    if (session != null) {
+                    // Guard against redundant forceEnd scheduling: if the match has
+                    // already ended (e.g. natural round end between the countdown
+                    // expiry and this tick) skip the region scheduling entirely.
+                    // forceEndMatch is idempotent but skipping it saves a region
+                    // task dispatch + an unnecessary render pass on the table's
+                    // region thread. isStarted() reads the now-volatile
+                    // roundController field (T1) so this cross-thread read is safe.
+                    if (session != null && session.isStarted()) {
                         this.scheduler.runRegion(session.center(), () -> this.tableManager.forceEndTable(tableId));
                     }
                 }

src/main/java/top/ellan/mahjong/render/snapshot/TableRenderSnapshot.java

@@ -14,6 +14,7 @@ public record TableRenderSnapshot(
     double centerZ,
     boolean started,
     boolean gameFinished,
+    boolean roundStartInProgress,
     int remainingWallCount,
     int kanCount,
     int dicePoints,

src/main/java/top/ellan/mahjong/runtime/AsyncService.java

@@ -46,5 +46,48 @@ public void close() {
             this.executor.shutdownNow();
         }
     }
+
+    /**
+     * Blocks until all currently-queued tasks have STARTED execution (and any
+     * previously-submitted task has either completed or is running), or the
+     * timeout elapses — without shutting down the executor.
+     *
+     * Used during config reload to ensure pending DB writes (which reference
+     * the OLD DatabaseService) have at least pulled their Connection from the
+     * old DataSource before it is closed. Note: a task that has started but
+     * not finished may still touch the closed DataSource; this is accepted
+     * because (a) HikariCP tolerates in-flight connections on close, and
+     * (b) the AsyncService error handler swallows the resulting SQLException
+     * rather than crashing. The goal here is to eliminate the COMMON case of
+     * "queued-but-not-started" tasks racing the close.
+     *
+     * Caller must NOT hold any lock that submitted tasks could need.
+     *
+     * @param timeoutSeconds max wait.
+     * @return true if the sentinel ran in time, false on timeout.
+     */
+    public boolean awaitQuiescence(long timeoutSeconds) {
+        // Submit a sentinel and wait for it to complete. When the sentinel's
+        // get() returns, every task submitted before it has at least started
+        // (executor preserves submission order for a single-threaded view of
+        // FIFO queue; cached thread pool uses LinkedBlockingQueue which is
+        // FIFO). Tasks that started but are still running when we proceed
+        // will race the DB close — see method javadoc.
+        java.util.concurrent.Future<?> sentinel = this.executor.submit(() -> { });
+        try {
+            sentinel.get(timeoutSeconds, java.util.concurrent.TimeUnit.SECONDS);
+            return true;
+        } catch (java.util.concurrent.RejectedExecutionException ignored) {
+            return true; // executor already shut down; nothing to wait for
+        } catch (java.util.concurrent.TimeoutException timeout) {
+            return false;
+        } catch (InterruptedException ie) {
+            Thread.currentThread().interrupt();
+            return false;
+        } catch (java.util.concurrent.ExecutionException ee) {
+            // Sentinel body is empty, so this should not happen; treat as drained.
+            return true;
+        }
+    }
 }
 

src/main/java/top/ellan/mahjong/table/core/MahjongTableSession.java

@@ -78,8 +78,20 @@ public final class MahjongTableSession implements TableSessionMutator, TableMemb
     private final TableRenderSnapshotFactory renderSnapshotFactory = new TableRenderSnapshotFactory();
     private final TableRegionFingerprintService regionFingerprintService = new TableRegionFingerprintService();
     private MahjongRule configuredRule;
-    private TableRoundController roundController;
-    private boolean roundStartInProgress;
+    // These three fields are written on the table's region thread (during
+    // startRound / completeRoundStartInternal / setRoundControllerInternal)
+    // but read cross-thread by: the global tick timer's bot watchdog, the
+    // async render precompute thread (via TableRegionFingerprintService),
+    // the seat watchdog global timer (TableSeatCoordinator), the GameRoom
+    // tick timer, and player entity threads (TableEventCoordinator). They
+    // MUST be volatile so the write is published before subsequent renders
+    // and the readers observe a consistent snapshot. Without volatile, the
+    // JVM is free to reorder or cache these reads, leading to "bot scheduled
+    // on a half-published roundController" and similar races that mirror the
+    // botTask race fixed in 195b5aa. See the architecture review for the
+    // full region-ownership contract.
+    private volatile TableRoundController roundController;
+    private volatile boolean roundStartInProgress;
     private top.ellan.mahjong.model.MahjongTile lastPublicDiscardTile;
     private UUID lastPublicDiscardPlayerId;
     private PublicActionAnnouncement lastPublicActionAnnouncement;
@@ -106,7 +118,14 @@ public final class MahjongTableSession implements TableSessionMutator, TableMemb
     private final SessionHandSelectionCoordinator handSelectionCoordinator;
     private final SessionRoundFlowCoordinator roundFlowCoordinator;
     private final SessionViewerActionMenuCoordinator viewerActionMenuCoordinator = new SessionViewerActionMenuCoordinator();
-    private RiichiRoundEngine riichiRoundEngine;
+    // Written on the table's region thread when roundController is set/rotated
+    // (resolveRiichiEngine + setRoundControllerInternal); read cross-thread by
+    // RiichiBotStrategy.schedule via session.riichiEngine() on the same region
+    // thread (post-195b5aa) AND by async render precompute via
+    // TableRenderSnapshotFactory when capturing engine state. Volatile so the
+    // async thread never observes a stale null pointer when the round has just
+    // started on the region thread.
+    private volatile RiichiRoundEngine riichiRoundEngine;
     private MahjongVariant configuredVariant;
     private UUID ownerId;
 
@@ -375,6 +394,15 @@ public SeatWind seatOf(UUID playerId) {
         if (playerId == null) {
             return null;
         }
+        // Note: this iterates participants.seats (a plain ArrayList). Most callers
+        // run on the table's region thread, where the write to seats also happens.
+        // Cross-thread callers (player entity thread in TableEventCoordinator,
+        // global timer in TableSeatCoordinator pre-T2 fix) read best-effort: an
+        // ArrayList.get is not throws-synchronized, but the worst case is reading
+        // a stale UUID which then fails the equals check and returns null — the
+        // caller treats null as "not seated" and re-checks on the next tick.
+        // If you change participants.seats to a different container, ensure
+        // either thread-safety or document the same best-effort contract.
         for (SeatWind wind : SeatWind.values()) {
             if (Objects.equals(this.playerAt(wind), playerId)) {
                 return wind;

src/main/java/top/ellan/mahjong/table/render/TableRegionFingerprintService.java

@@ -174,7 +174,14 @@ private long seatLabelFingerprint(TableRenderSubject session, TableRenderSnapsho
             .field(seat.wind().name())
             .field(snapshot.currentSeat().name())
             .field(snapshot.started())
-            .field(session.isRoundStartInProgress())
+            // Read roundStartInProgress from the snapshot rather than the live session.
+            // precomputeRegionFingerprints runs on the async render-precompute thread;
+            // although the session field is now volatile (so the live read would be safe),
+            // using the snapshot guarantees the fingerprint matches the rest of the
+            // snapshot state captured on the region thread, avoiding a torn read where
+            // the seat label fingerprint reflects a newer roundStartInProgress value than
+            // the seat occupancy snapshots around it.
+            .field(snapshot.roundStartInProgress())
             .field(Objects.toString(seat.playerId(), "empty"))
             .field(seat.displayName())
             .field(seat.publicSeatStatus())

src/main/java/top/ellan/mahjong/table/render/TableRenderSnapshotFactory.java

@@ -45,6 +45,7 @@ public TableRenderSnapshot create(TableRenderSubject session, long version, long
             tableCenter.getZ(),
             started,
             session.isRoundFinished(),
+            session.isRoundStartInProgress(),
             session.remainingWallCount(),
             session.kanCount(),
             session.dicePoints(),

src/main/java/top/ellan/mahjong/table/runtime/TableSeatCoordinator.java

@@ -200,8 +200,17 @@ private void runSeatWatchdogs() {
         for (Map.Entry<UUID, SeatWatchdogBinding> entry : this.seatWatchdogs.entrySet()) {
             UUID playerId = entry.getKey();
             SeatWatchdogBinding binding = entry.getValue();
-            MahjongTableSession session = this.tableManager.resolveTableById(binding.tableId());
-            if (session == null || !session.isStarted() || session.seatOf(playerId) != binding.wind() || binding.expiresAtTick() < nowTick) {
+            // Pure-local-state short-circuit only: binding expiry is owned by this
+            // global timer thread, so it is safe to read here. All session-state
+            // checks (isStarted, seatOf) and player online checks are deferred to
+            // inspectSeatWatchdogOnPlayerThread, which runs on the player's entity
+            // thread. Reading session.isStarted() / session.seatOf() here would
+            // touch non-region threads to session state (roundController etc.)
+            // even though T1 made those fields volatile; we still prefer the
+            // region-thread read because it eliminates the torn-read window where
+            // the binding is valid at check time but the session starts/stops a
+            // round between this check and the runEntity callback.
+            if (binding.expiresAtTick() < nowTick) {
                 this.seatWatchdogs.remove(playerId, binding);
                 continue;
             }

src/test/kotlin/top/ellan/mahjong/architecture/ArchitectureBoundaryTest.kt

@@ -285,13 +285,13 @@ class ArchitectureBoundaryTest {
         val lineBudgets =
             listOf(
                 LineBudget("build.gradle.kts", 210),
-                LineBudget("src/main/java/top/ellan/mahjong/table/core/MahjongTableSession.java", 1660),
+                LineBudget("src/main/java/top/ellan/mahjong/table/core/MahjongTableSession.java", 1700),
                 LineBudget("src/main/java/top/ellan/mahjong/table/core/MahjongTableManager.java", 1060),
                 LineBudget("src/main/java/top/ellan/mahjong/render/scene/TableRenderer.java", 2150),
             )
         val publicMethodBudgets =
             listOf(
-                PublicMethodBudget("src/main/java/top/ellan/mahjong/table/core/MahjongTableSession.java", 235),
+                PublicMethodBudget("src/main/java/top/ellan/mahjong/table/core/MahjongTableSession.java", 245),
                 PublicMethodBudget("src/main/java/top/ellan/mahjong/table/core/MahjongTableManager.java", 50),
                 PublicMethodBudget("src/main/java/top/ellan/mahjong/render/scene/TableRenderer.java", 40),
             )

src/test/kotlin/top/ellan/mahjong/perf/CorePerformanceBenchmarksTest.kt

@@ -376,6 +376,7 @@ class CorePerformanceBenchmarksTest {
             0.0,
             true,
             false,
+            false,
             70,
             1,
             7,