diff --git a/Delta-Sync-flow.md b/Delta-Sync-flow.md new file mode 100644 index 0000000..1db5627 --- /dev/null +++ b/Delta-Sync-flow.md @@ -0,0 +1,607 @@ +# Delta Sync Flow -- End-to-End Reference + +This document traces the full lifecycle of a game state delta: from the moment +a player action is received on the server, through delta computation, +serialisation, transport, and final application on the client. + +--- + +## Table of Contents + +1. [Overview](#1-overview-) +2. [Wire Types](#2-wire-types-) +3. [Server -- Action Handler](#3-server----action-handler-) +4. [Server -- State Persistence (SaveStateAsync)](#4-server----state-persistence-savestateasync-) +5. [Server -- Delta Computation (GameStateDiffer)](#5-server----delta-computation-gamestatediffer-) +6. [Server -- Push Decision (PushStateToPlayersAsync)](#6-server----push-decision-pushstatetoplayersasync-) +7. [Transport -- Redis Pub/Sub via IClientPush](#7-transport----redis-pubsub-via-iclientpush-) +8. [Client -- WebSocket Reception (Network.gd)](#8-client----websocket-reception-networkgd-) +9. [Client -- Push Dispatch (Game.gd)](#9-client----push-dispatch-gamegd-) +10. [Client -- Delta Application (_apply_delta)](#10-client----delta-application-applydelta-) +11. [Client -- Unit Merge (_merge_unit_delta)](#11-client----unit-merge-mergeunitdelta-) +12. [Fallback and Resync Paths](#12-fallback-and-resync-paths-) +13. [Design Invariants](#13-design-invariants-) + +--- + +## 1. Overview + +``` +Player action (WebSocket request) + | v +[Handler] load session (FOR UPDATE lock) + | capture prevStateJson BEFORE mutation + | v +[GameEngine] apply action -> newState + | v +[SaveStateAsync] serialize newState -> DB, commit tx + | v +[PushStateToPlayersAsync] compute per-viewer deltas + | (or fallback to full state) + +---> player A delta ---> Redis channel push:{accountA} + +---> player B delta ---> Redis channel push:{accountB} + +---> spectators ---> full state_update (never delta) + | v (gateway subscribes to Redis and forwards) + WebSocket push -> client + | v +[Network.gd] parse JSON, emit message_received signal + | v +[Game.gd _on_server_push] match game.state_delta + | version guard: too old -> drop; gap -> fetch full + | v +[_apply_delta] 10-section merge loop -> state_updated.emit(state) +``` + +--- + +## 2. Wire Types + +**File:** `Server/src/SOR.Game/GameMessages.cs` + +### Envelope (line 506) +```csharp +public sealed record GameStateDeltaPush(GameStateDelta Delta); +``` +Sent as the payload of a `game.state_delta` push message. + +### GameStateDelta (lines 512-523) +```csharp +public sealed record GameStateDelta( + int StateVersion, + IReadOnlyList? ChangedTiles, + IReadOnlyList? UnitsAdded, + IReadOnlyList? UnitsRemoved, + IReadOnlyList? UnitsChanged, + IReadOnlyDictionary? ArchSpiritByAccount, + IReadOnlyDictionary? PlayerStatsByAccount, + IReadOnlyDictionary? PublicCountsByAccount, + PrivateViewerDelta? PrivateByViewer, + GameMetaDelta? MetaDelta, + IReadOnlyList? ActiveEffects = null); +``` +**Sparse pattern:** a `null` collection means no change in that category. +`ActiveEffects` is always populated when effects exist -- full replacement, not delta. + +### Sub-types + +| Type | Lines | Description | +|---|---|---| +| `TileDelta` | 525-536 | Board coord + changed base1/base2/affinity/occupant/ruin. `OccupantCleared` and `RuinCleared` are explicit booleans to distinguish set-to-null from no-change. | +| `UnitSnapshot` | 538-540 | Full `CardInstanceDto` with `OwnerAccountId` -- used for newly placed units. | +| `UnitDelta` | 542-561 | Partial unit update; nullable fields; `null` = unchanged. | +| `PublicCountsDelta` | 563-566 | Hand/deck/discard counts visible to opponents (not actual cards). | +| `ArchSpiritUpdate` | 568-570 | Either a `Full` snapshot or a `Delta` -- server sends full on first sight, delta thereafter. | +| `PrivateViewerDelta` | 572-575 | Own hand additions, removals by ID, discard additions. Never sent to opponents. | +| `PlayerStatsDelta` | 577-582 | SP, ST, and zone counts per account. | +| `GameMetaDelta` | 584-587 | Phase, active player account ID, turn number. | + +--- + +## 3. Server -- Action Handler + +**Example file:** `Server/src/SOR.Game/Handlers/GameDrawHandler.cs` + +Every game-action handler follows the same four-step skeleton: + +```csharp +// GameDrawHandler.cs lines 36-48 +var session = await LoadActiveSessionAsync(_gameDb, req.SessionId, actorId, ct); +var prevStateJson = session.StateJson!; // <- capture BEFORE mutation +var state = GameEngine.Deserialize(prevStateJson); +var (newState, _) = GameEngine.Draw(state, actorId); // <- engine returns new object +await SaveStateAsync(_gameDb, session, newState, actorId, "game.draw", + JsonSerializer.Serialize(req), ct); // <- persist + commit tx +await PushStateToPlayersAsync(_clientPush, session, newState, ct, prevStateJson); +``` +**Critical ordering:** +- `prevStateJson` captured from `session.StateJson` **before** calling `SaveStateAsync`. +- `SaveStateAsync` overwrites `session.StateJson` with the new state. +- `PushStateToPlayersAsync` receives both snapshots to compute the diff. + +### LoadActiveSessionAsync (GameHandlerBase.cs lines 29-61) + +Begins a PostgreSQL transaction and issues `SELECT ... FOR UPDATE` to serialize +concurrent mutations on the same session row. Lock held until `SaveStateAsync` commits. + +```csharp +var session = await gameDb.GameSessions + .FromSqlInterpolated($""" + SELECT * FROM game.game_sessions + WHERE "Id" = {sessionId} + FOR UPDATE + """) + .SingleOrDefaultAsync(ct); +``` + +--- + +## 4. Server -- State Persistence (SaveStateAsync) + +**File:** `Server/src/SOR.Game/Handlers/GameHandlerBase.cs`, lines 68-90 + +```csharp +internal static async Task SaveStateAsync( + GameDbContext gameDb, GameSession session, GameState state, + string actorId, string actionType, string? payloadJson, + CancellationToken ct, string? resultJson = null) +{ + var seqNum = state.NextActionSequence++; // increment; saved JSON reflects consumed number + session.StateJson = GameEngine.Serialize(state); + session.LastActionAt = DateTimeOffset.UtcNow; + gameDb.ActionLogs.Add(new GameActionLog { SequenceNumber = seqNum, ... }); + await gameDb.SaveChangesAsync(ct); + await gameDb.Database.CommitTransactionAsync(ct); +} +``` +`state.NextActionSequence` becomes the `StateVersion` carried in deltas -- +the client uses this integer to detect gaps. + + +--- + +## 5. Server -- Delta Computation (GameStateDiffer) + +**File:** `Server/src/SOR.Game/GameStateDiffer.cs` + +### ComputeDelta -- viewer-specific (line 21) + +```csharp +public static GameStateDelta ComputeDelta(GameState prev, GameState next, string viewerAccountId) +{ + var changedTiles = DiffTiles(prev, next); + var (unitsAdded, unitsRemoved, unitsChanged) = DiffAllFieldUnits(prev, next); + + // Private data: only this viewer's hand / discard changes + PrivateViewerDelta? privateByViewer = null; + if (prevViewer != null && nextViewer != null) + { + var added = nextHandIds.Except(prevHandIds); // hand diff: set operations + var removed = prevHandIds.Except(nextHandIds); + // discard: append-only via Skip(prevCount) + if (handAdded != null || handRemovedIds != null || discardAdded != null) + privateByViewer = new PrivateViewerDelta(handAdded, handRemovedIds, discardAdded); + } + return new GameStateDelta( + StateVersion: next.NextActionSequence, + ChangedTiles: changedTiles, + UnitsAdded: unitsAdded, + UnitsRemoved: unitsRemoved, + UnitsChanged: unitsChanged, + ArchSpiritByAccount: DiffArchByAccount(prev, next), + PlayerStatsByAccount: DiffStatsByAccount(prev, next), + PublicCountsByAccount: DiffPublicCountsByAccount(prev, next, viewerAccountId), + PrivateByViewer: privateByViewer, + MetaDelta: DiffMeta(prev, next), + ActiveEffects: DiffActiveEffects(next)); +} +``` +### ComputeSpectatorDelta (line 82) + +Same structure but `PrivateByViewer = null` and `viewerAccountId = null` -- spectators see +all public counts, no private zone data. + +### Diff Helpers + +| Method | Lines | What it diffs | +|---|---|---| +| `DiffTiles` | 123-181 | Board tiles; emits `TileDelta` for each coord where base1/base2/affinity/occupant/ruin changed. | +| `DiffAllFieldUnits` | 184-229 | Builds prev/next unit maps by `InstanceId` across all players; splits into added/removed/changed. | +| `DiffUnit` | 231-288 | Compares individual `CardInstance` fields; returns `null` when nothing changed. | +| `DiffPlayerStats` | 290-307 | Compares SP, ST, deck/hand/discard counts; returns `null` when unchanged. | +| `DiffArchByAccount` | 309-343 | Per-account ArchSpirit: `Full` snapshot if prev had none, otherwise `Delta` from `DiffUnit`. | +| `DiffStatsByAccount` | 345-363 | Calls `DiffPlayerStats` per account; omits null results. | +| `DiffPublicCountsByAccount` | 365-392 | Hand/deck/discard counts for players other than the viewer. | +| `DiffMeta` | 407-419 | Phase, active player, turn number. | +| `DiffActiveEffects` | 112-120 | Always returns the full active-effects list (full replacement, never sparse). | + +--- + +## 6. Server -- Push Decision (PushStateToPlayersAsync) + +**File:** `Server/src/SOR.Game/Handlers/GameHandlerBase.cs`, lines 291-393 + +```csharp +internal static async Task PushStateToPlayersAsync( + IClientPush clientPush, GameSession session, GameState state, + CancellationToken ct, string? prevStateJson = null) +{ + if (prevStateJson != null) + { + var prevState = GameEngine.Deserialize(prevStateJson); + var allIds = GetAllPlayerIds(session); // P1, P2, + any AdditionalPlayers + + // ActiveEffects excluded from IsEmpty: it is always populated even when empty, + // so including it would always trigger the full-state fallback. (line 313) + static bool IsEmpty(GameStateDelta d) => + d.MetaDelta == null && d.ChangedTiles == null && d.UnitsAdded == null && + d.UnitsRemoved == null && d.UnitsChanged == null && + d.ArchSpiritByAccount == null && d.PlayerStatsByAccount == null && + d.PublicCountsByAccount == null && d.PrivateByViewer == null; + + // lines 315-317: one viewer-specific delta per player + var deltas = allIds.ToDictionary( + pid => pid, + pid => GameStateDiffer.ComputeDelta(prevState, state, pid)); + + if (deltas.Values.Any(IsEmpty)) // line 321 -- any player sees no change? + { + // Fallback: push full game.state_update to everyone + foreach (var pid in allIds) + tasks.Add(clientPush.PushAsync(pid, + ServerMessage.Push("game.state_update", + new GameStateUpdatePush(GameEngine.ToDto(state, pid))), ct)); + } + else + { + // Happy path: viewer-specific delta to each player (lines 344-346) + foreach (var (pid, delta) in deltas) + tasks.Add(clientPush.PushAsync(pid, + ServerMessage.Push("game.state_delta", + new GameStateDeltaPush(delta)), ct)); + } + // Spectators always receive full public state, never a delta (lines 348-360) + foreach (var specId in spectators) + tasks.Add(clientPush.PushAsync(specId.ToString(), + ServerMessage.Push("game.state_update", + new GameStateUpdatePush(GameEngine.ToDtoSpectator(state))), ct)); + await Task.WhenAll(tasks); + } + else + { + // No prevStateJson: initial connect / reconnect / timer expiry -> full state + } + await PushPendingPromptsAsync(clientPush, state, ct); // ability pause prompts +} +``` +**Decision tree:** + +``` +prevStateJson present? ++-- NO -> full game.state_update to all players ++-- YES -> compute per-player deltas + any delta IsEmpty? + +-- YES -> full game.state_update to all players + +-- NO -> game.state_delta (viewer-specific) to each player + spectators always -> game.state_update (public DTO, no delta) +``` + +--- + +## 7. Transport -- Redis Pub/Sub via IClientPush + +**Interface:** `Server/src/SOR.Networking.Abstractions/Push/IClientPush.cs` + +```csharp +Task PushAsync(string userId, IServerMessage message, CancellationToken ct); +``` +**Implementation:** `Server/src/SOR.Networking.Redis/RedisClientPush.cs` + +- Serialises the `IServerMessage` to bytes via `IMessageSerializer`. +- Publishes to Redis channel `push:{userId}`. +- The gateway (SOR.Host) subscribes to these channels and forwards bytes over the player's active WebSocket connection. +- Best-effort delivery: if the player is disconnected the publish is dropped silently. + +**Wire JSON format:** + +```json +{ + "type": "game.state_delta", + "ref": 0, + "payload": { + "delta": { + "stateVersion": 42, + "changedTiles": [...], + "unitsChanged": [...], + "privateByViewer": { "handAdded": [...] }, + "metaDelta": { "phase": "combat" }, + "activeEffects": [...] + } + } +} +``` +`ref: 0` indicates an unsolicited push (not a reply to a client request). + +--- + +## 8. Client -- WebSocket Reception (Network.gd) + +**File:** `Client/origin-client/autoloads/Network.gd` + +```gdscript +## Emitted for server-pushed messages that do not match a pending request. +signal message_received(type: String, payload: Variant) # line 35 +``` +All incoming WebSocket packets are polled in `_process`. Each packet is parsed as JSON +and its `ref` sequence number checked against `_pending` (outstanding requests): + +```gdscript +# Network.gd lines 283-284 +# Not a reply to a known request -- broadcast/push to listeners. +message_received.emit(type, payload) +``` +Push messages (`ref == 0`) bypass the request-reply correlation table and are broadcast +via `message_received` to any connected listener. + +--- + +## 9. Client -- Push Dispatch (Game.gd) + +**File:** `Client/origin-client/autoloads/Game.gd` + +### Subscription (line 109) + +```gdscript +func _ready() -> void: + Network.message_received.connect(_on_server_push) +``` +### Version-guarded dispatch (lines 702-755) + +```gdscript +func _on_server_push(type: String, payload: Variant) -> void: + match type: + "game.state_delta": # line 739 + var d := payload as Dictionary + var delta := d.get("delta", {}) as Dictionary + if delta.is_empty(): return + var v := int(delta.get("stateVersion", -1)) + # Already up to date (acting player got full state in their ACK reply) + if _state_version >= 0 and v <= _state_version: # line 744 + return + # Gap detected: missed one or more deltas + if _state_version >= 0 and v > _state_version + 1: # line 747 + print("[Game] WARN: missed delta (have %d, got %d) -- requesting full sync" + % [_state_version, v]) + _fetch_state() # sends game.get_state request to server + return + _apply_delta(delta) # line 755 -- happy path +``` +`_state_version` (line 104) initialised to `-1`; updated on full state receipt (line 727) +and after each applied delta (line 669). + +--- + +## 10. Client -- Delta Application (_apply_delta) + +**File:** `Client/origin-client/autoloads/Game.gd`, lines 512-674 + +Ten sections processed in order. Each guarded with `is Array` / `is Dictionary` +so a missing or null section is safely skipped. + +### Section 1 -- Changed Tiles (lines 517-536) + +```gdscript +var changed_tiles = delta.get("changedTiles") +if changed_tiles is Array: + var tiles: Array = state.get("board", {}).get("tiles", []) + for td: Dictionary in changed_tiles: + var tx := int(td.get("x", -1)) + var ty := int(td.get("y", -1)) + for tile: Dictionary in tiles: + if c.get("x") == tx and c.get("y") == ty: + if td.has("base1") and td["base1"] != null: tile["base1"] = td["base1"] + if td.has("occupantCleared") and bool(td["occupantCleared"]): + tile["occupantId"] = null; tile["occupantOwner"] = null + elif td.has("occupantId") and td["occupantId"] != null: + tile["occupantId"] = td["occupantId"] + # ... base2, resolvedAffinity, ruinId, ruinOwner, occupantOwner + break +``` +`OccupantCleared` and `RuinCleared` booleans handle the set-to-null case +that a plain nullable field cannot express. + +### Section 2 -- Added Units (lines 538-556) + +```gdscript +var added_units = delta.get("unitsAdded") +if added_units is Array: + for add_entry: Dictionary in added_units: + var owner_id := str(add_entry.get("ownerAccountId", "")) + var unit := add_entry.get("unit", {}) as Dictionary + var field: Array = _player_by_id(owner_id).get("field", []) + if not exists: # idempotency guard: skip if instanceId already present + field.append(unit) +``` +### Section 3 -- Removed Units (lines 558-567) + +```gdscript +var removed_ids = delta.get("unitsRemoved") +if removed_ids is Array: + for iid: String in removed_ids: + for p: Dictionary in state.get("players", []): + var field: Array = p.get("field", []) + for i in range(field.size() - 1, -1, -1): + if field[i].get("instanceId", "") == iid: + field.remove_at(i); break +``` +### Section 4 -- Changed Units (lines 569-576) + +```gdscript +var changed_units = delta.get("unitsChanged") +if changed_units is Array: + for ud: Dictionary in changed_units: + var iid := str(ud.get("instanceId", "")) + var unit := get_unit_by_id(iid) + if not unit.is_empty(): + _merge_unit_delta(unit, ud) # see Section 11 +``` +### Section 5 -- Private Viewer Data (lines 578-600) + +```gdscript +var private_delta = delta.get("privateByViewer") +if private_delta is Dictionary and not private_delta.is_empty(): + # handAdded -> append new cards to own hand + # handRemovedIds -> remove by instanceId from own hand + # discardAdded -> append to own discard +``` +Never present in another player's delta -- the server sets `PrivateByViewer` only for the owning account. + +### Section 6 -- Public Counts (lines 602-613) + +```gdscript +var public_counts = delta.get("publicCountsByAccount") +if public_counts is Dictionary: + for aid_v in public_counts.keys(): + var player := _player_by_id(str(aid_v)) + if counts.has("handCount") ...: player["handCount"] = int(counts["handCount"]) + if counts.has("deckCount") ...: player["deckCount"] = int(counts["deckCount"]) + if counts.has("discardCount") ...: player["discardCount"] = int(counts["discardCount"]) +``` +Opponents see card **counts** here; their actual cards are never transmitted. + +### Section 7 -- ArchSpirit Updates (lines 615-638) + +```gdscript +var arch_by_account = delta.get("archSpiritByAccount") +if arch_by_account is Dictionary: + var full_arch: Variant = arch_update.get("full") + if full_arch is Dictionary and not full_arch.is_empty(): + player["archSpirit"] = full_arch # full replacement on first sight + continue + var arch_delta := arch_update.get("delta") as Dictionary + if arch.is_empty(): + request_sync() # missing baseline -> fetch full state + continue + _merge_unit_delta(arch, arch_delta) +``` +Server sends `Full` on first sight of an arch spirit (e.g. just placed), `Delta` thereafter. + +### Section 8 -- Player Stats (lines 640-655) + +```gdscript +var stats_by_account = delta.get("playerStatsByAccount") +if stats_by_account is Dictionary: + if stats.has("currentSp") and stats["currentSp"] != null: + player["currentSp"] = int(stats["currentSp"]) + if stats.has("currentSt") and stats["currentSt"] != null: + player["currentSt"] = int(stats["currentSt"]) + # also: deckCount, handCount, discardCount +``` +### Section 9 -- Meta (lines 657-662) + +```gdscript +var meta = delta.get("metaDelta") +if meta is Dictionary and not meta.is_empty(): + if meta.has("phase") ...: state["phase"] = meta["phase"] + if meta.has("activePlayerAccountId") ...: state["activePlayerAccountId"] = ... + if meta.has("turnNumber") ...: state["turnNumber"] = int(meta["turnNumber"]) +``` +### Section 10 -- Active Effects (lines 664-667) + +```gdscript +var active_effects = delta.get("activeEffects") +if active_effects is Array: + state["activeEffects"] = active_effects # full replacement +``` +### Version Update and Signal (lines 669-674) + +```gdscript +_state_version = int(delta.get("stateVersion", _state_version)) +state_updated.emit(state) # triggers UI rebuild +``` + +--- + +## 11. Client -- Unit Merge (_merge_unit_delta) + +**File:** `Client/origin-client/autoloads/Game.gd`, lines 677-699 + +Used by sections 4 (field units) and 7 (arch spirits). Merges only non-null fields: + +```gdscript +func _merge_unit_delta(unit: Dictionary, ud: Dictionary) -> void: + if ud.has("currentHealth") and ud["currentHealth"] != null: + unit["currentHealth"] = int(ud["currentHealth"]) + if ud.has("maxHealth") and ud["maxHealth"] != null: + unit["maxHealth"] = int(ud["maxHealth"]) + if ud.has("currentDefense") and ud["currentDefense"] != null: + unit["currentDefense"] = int(ud["currentDefense"]) + if ud.has("maxDefense") and ud["maxDefense"] != null: + unit["maxDefense"] = int(ud["maxDefense"]) + if ud.has("damage") and ud["damage"] != null: + unit["damage"] = int(ud["damage"]) + if ud.has("isExhausted") and ud["isExhausted"] != null: + unit["isExhausted"] = bool(ud["isExhausted"]) + if ud.has("canMove") and ud["canMove"] != null: + unit["canMove"] = bool(ud["canMove"]) + if ud.has("canAttack") and ud["canAttack"] != null: + unit["canAttack"] = bool(ud["canAttack"]) + if ud.has("canBeAttacked") and ud["canBeAttacked"] != null: + unit["canBeAttacked"] = bool(ud["canBeAttacked"]) + if ud.has("canUseAbility") and ud["canUseAbility"] != null: + unit["canUseAbility"] = bool(ud["canUseAbility"]) + if ud.has("currentMp") and ud["currentMp"] != null: + unit["currentMp"] = int(ud["currentMp"]) + if ud.has("maxMp") and ud["maxMp"] != null: + unit["maxMp"] = int(ud["maxMp"]) + if ud.has("extraAttacksRemaining") and ud["extraAttacksRemaining"] != null: + unit["extraAttacksRemaining"] = int(ud["extraAttacksRemaining"]) + if ud.has("position") and ud["position"] != null: + unit["position"] = ud["position"] + if ud.has("abilitiesJson") and ud["abilitiesJson"] != null: + unit["abilitiesJson"] = ud["abilitiesJson"] + if ud.has("abilityUsesJson") and ud["abilityUsesJson"] != null: + unit["abilityUsesJson"] = ud["abilityUsesJson"] + # art2dUrl / Art2dUrl and modelUrl / ModelUrl / modelurl all checked (capitalisation guard) + if ud.has("art2dUrl") and ud["art2dUrl"] != null: unit["art2dUrl"] = ud["art2dUrl"] + if ud.has("modelUrl") and ud["modelUrl"] != null: unit["modelUrl"] = ud["modelUrl"] +``` +The `ud.has(k) and ud[k] != null` pattern distinguishes JSON `null` (no change) from a missing key. + +--- + +## 12. Fallback and Resync Paths + +| Trigger | Behaviour | +|---|---| +| `prevStateJson == null` passed to handler | Full `game.state_update` pushed to all players (initial connect, reconnect, timer expiry). | +| Any player's delta `IsEmpty()` | All players receive full `game.state_update` instead of deltas. | +| Spectator | Always receives full `game.state_update` (public DTO, no private data, no delta). | +| Client: `v <= _state_version` | Delta dropped -- acting player already received the new state in their ACK reply. | +| Client: `v > _state_version + 1` | Gap in sequence -- client calls `_fetch_state()` which sends `game.get_state`; server replies with full state. | +| Client: arch spirit `is_empty()` | Missing baseline -- client calls `request_sync()` for the same full-state recovery. | + +--- + +## 13. Design Invariants + +1. **`prevStateJson` must be captured before `SaveStateAsync`.** + Breaking this produces an empty diff (state compared to itself). + +2. **`StateVersion` == `state.NextActionSequence` at time of push.** + Incremented inside `SaveStateAsync` before serialisation, so the value baked into the delta exactly matches what is stored in the DB. + +3. **`ActiveEffects` is always a full replacement, never sparse.** + Comment at `GameStateDiffer.cs:109`: the collection is small, ordering matters, and partial diffs of effect lists would be error-prone. + +4. **`PrivateByViewer` is viewer-exclusive.** + `ComputeDelta` is called once per player with that player's account ID. Each player's delta contains only their own private zone data. + +5. **Spectators never receive deltas.** + `ComputeSpectatorDelta` exists but `PushStateToPlayersAsync` always pushes a full `game.state_update` to spectators (lines 348-360). + +6. **FOR UPDATE lock serialises concurrent mutations.** + All action handlers call `LoadActiveSessionAsync` which opens a transaction and locks the session row. Concurrent requests for the same session queue up in PostgreSQL. + +7. **IsEmpty check excludes `ActiveEffects`.** + Comment at `GameHandlerBase.cs:313`: `ActiveEffects` is always populated (even when it is an empty list), so including it in the emptiness check would always trigger the full-state fallback. +