Add Delta-Sync-flow.md: end-to-end delta sync reference

Documents the complete delta lifecycle from server action handler
through GameStateDiffer computation, PushStateToPlayersAsync dispatch,
Redis transport, and client-side application in Game.gd/_apply_delta.
Includes line numbers, code snippets, wire types, and design invariants.

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
This commit is contained in:
dingo
2026-05-20 07:46:55 -04:00
co-authored by Claude Happy
parent 41c18da1ed
commit 83217c630e
+607
View File
@@ -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<TileDelta>? ChangedTiles,
IReadOnlyList<UnitSnapshot>? UnitsAdded,
IReadOnlyList<string>? UnitsRemoved,
IReadOnlyList<UnitDelta>? UnitsChanged,
IReadOnlyDictionary<string, ArchSpiritUpdate>? ArchSpiritByAccount,
IReadOnlyDictionary<string, PlayerStatsDelta>? PlayerStatsByAccount,
IReadOnlyDictionary<string, PublicCountsDelta>? PublicCountsByAccount,
PrivateViewerDelta? PrivateByViewer,
GameMetaDelta? MetaDelta,
IReadOnlyList<ActiveEffectDto>? 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.