# Concurrency & durability This guide documents the runtime architecture decisions that keep live game state safe: the single-owner loop, the durable money journal, the account lifecycle transactions, and the graceful-shutdown sequence. ## Single-owner game state One goroutine — the **owner loop** (`internal/game/owner.go`) — executes all mutation of live game state: session input handlers, connect/disconnect transitions, every tick callback (the master per-tick system sequence and all dynamically registered callbacks), and admin mutations. Network and admin goroutines submit tasks; they never touch live players, sessions, Hub membership, or game runtime maps directly. Rules: - `Game.RunOnOwner(fn)` (and `Game.HandleSessionOnOwner` for session input) block the caller until the closure has executed on the owner. Connection goroutines submit one task per input line, giving per-client backpressure without ever blocking another client. - Code already running on the owner must NOT call `Game.RunOnOwner` — it would deadlock waiting for itself. Owner-executed code calls functions directly. - Task execution is FIFO, so tick callbacks serialize against session input and admin mutations in submission order. Tick callbacks still run in engine registration-ID order (see tick_order.md); the owner wrapper only moves their execution onto the owner goroutine. - Slow clients cannot stall the world: `Session` writes are queued (`net.Session.StartWriter` puts a transport session into queued mode) and a dedicated per-session writer goroutine performs the network I/O with per-message write deadlines. A full queue disconnects only that client. - Saves run on the owner and serialize a value snapshot; concurrent read-modify-write cycles of the same files cannot happen. Unit tests construct Games without an owner; such Games run submitted tasks inline on the caller's goroutine (legacy behavior), which is fine for synthetic tests but production Games always have the owner (started by `game.New`). ## Durable money (casino wallet) Every wager and payout is journaled before the balance mutation (`internal/game/economy.go`, `data/economy/journal.jsonl`): 1. A durable journal record with balance checkpoints (before/after) is appended and fsynced. 2. The in-memory balance mutates. 3. The character save makes the balance durable. 4. A settlement marker closes the record. A failed save reverts the in-memory mutation and voids the record — the game must not proceed on a stake that could not be made durable, and the player is told the house could not process the transaction (distinct from an insufficient-funds message). Payouts keep their record open when the save fails; startup recovery re-pays the owed settlement. At startup (`game.New`), open records are reduced (latest line per record ID wins) and compensated: - open **wager** with the file at the pre-debit balance → void (nothing was charged); - open **wager** with the file at the post-debit balance → the stake is **refunded** (the round state was lost in the crash); - open **payout** with the file at the pre-payout balance → the payout is **re-applied** (the player is owed it); - otherwise the record settles, or is surfaced for operator inspection when the balance is ambiguous. Currency arithmetic is checked (`internal/casino/credits.go`): explicit `MaxCredits` cap, bounded `DefaultMaxBet` default (the explicit unlimited sentinel is still honored), floor conversion for payout multipliers, and overflow rejected instead of wrapping. ## Account lifecycle transactions Account and character lifecycle operations (create, rename, delete, purge) are single journal transactions (`internal/persistence/txn.go`): a journal entry with before-images is written durably BEFORE any file changes, the operations apply, and the journal is removed at the commit point. Any failure rolls back every applied operation; a crash mid-commit is rolled back at the next startup by `persistence.Recover`. Characters carry a stable UUID (`player.Player.ID`) and owner field (`player.Player.Account`), assigned at creation and backfilled at first startup. Cached membership authorizes by the character file's owner, not by its renameable filename, so a stale cached name can never authorize connecting, renaming, or deleting a character reassigned to another account. After any lifecycle mutation, `Game.publishAccountUpdate` republishes the account state to every authenticated session of that account — including sessions sitting in menus — resetting stale pending selections. The online check and the file mutation run as one owner step, closing the check-then-rename gap. ## Graceful shutdown Signals (SIGINT/SIGTERM) and the in-game `shutdown` command converge on `Game.RequestShutdown`, which runs the sequence exactly once: 1. **Admissions stop:** session input and disconnect forfeit/save callbacks become no-ops (server-initiated shutdown is not a player disconnect). 2. **Tick stop and join:** `Engine.StopAndWait` stops the ticker and waits for the in-flight callback to finish. 3. **Drain and persist (on the owner):** remaining queued commands execute, outstanding wagers are refunded (`Casino.RefundAll`), and every online character is saved. Save failures are logged for the operator. 4. **Owner stop:** the owner loop drains and stops. 5. **Transports close:** HTTP(S) servers drain, listeners close, and sessions flush their outbound queues before their sockets drop. `ListenAndServe` returns and main exits normally — no `os.Exit`. ## Room-ID migration Live room-ID changes (admin rename, swapid) execute as one mutation plan: the renamed room's file (id field, filename, self-loop references) plus every other room whose references moved, applied as a single journal transaction, followed by the full runtime migration (`Game.MigrateRoomIDs`): player state, Hub room buckets, casino room keys, world room-keyed state (ground items, seeded markers, object states), and live mob instances. Undo/redo store the whole plan (all before/after images plus the idMap) and apply the inverse/forward runtime migration through the same wired callback.