Files
sor/Delta-Sync-flow.md
88a68a1443 Update Delta-Sync-flow.md to reflect all 6 fixes as implemented
- §2 UnitDelta: note Art2dUrl/ModelUrl removed; only in UnitSnapshot
- §6 Push Decision: note spectator registry is now Redis-backed
- §9 Push Dispatch: note _fetch_state is guarded by _syncing flag
- §11 _merge_unit_delta: remove stale art2dUrl/modelUrl snippet; add note
  that URLs are applied once on unitsAdded and stay on the unit dict
- §12 Fallback/Resync: update _fetch_state row (_syncing guard, session-id
  validation); update arch spirit null row (is Dictionary guard)
- §14: replace "Known Issues & Planned Fixes" with "Fixes Applied" —
  documents all 6 commits with root cause, resolution, and files changed

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>
2026-05-21 06:06:22 -04:00

32 KiB

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
  2. Wire Types
  3. Server -- Action Handler
  4. Server -- State Persistence (SaveStateAsync)
  5. Server -- Delta Computation (GameStateDiffer)
  6. Server -- Push Decision (PushStateToPlayersAsync)
  7. Transport -- Redis Pub/Sub via IClientPush
  8. Client -- WebSocket Reception (Network.gd)
  9. Client -- Push Dispatch (Game.gd)
  10. Client -- Delta Application (_apply_delta)
  11. Client -- Unit Merge (_merge_unit_delta)
  12. Fallback and Resync Paths
  13. Design Invariants
  14. Fixes Applied

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)

public sealed record GameStateDeltaPush(GameStateDelta Delta);

Sent as the payload of a game.state_delta push message.

GameStateDelta (lines 512-523)

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. Art2dUrl and ModelUrl were removed — those fields belong only in UnitSnapshot (CardInstanceDto) and are stable for the lifetime of a card definition.
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:

// 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.

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

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)

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

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).
        // Spectator IDs are fetched from a Redis Set (key: spectators:{sessionId}),
        // so registration survives pod restarts and cross-pod load balancing.
        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

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:

{
  "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

## 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):

# 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)

func _ready() -> void:
    Network.message_received.connect(_on_server_push)

Version-guarded dispatch (lines 702-755)

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()    # guarded by _syncing flag; at most one in-flight request
                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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

var active_effects = delta.get("activeEffects")
if active_effects is Array:
    state["activeEffects"] = active_effects   # full replacement

Version Update and Signal (lines 669-674)

_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 -- function _merge_unit_delta

Note on line numbers throughout this document: line references were accurate at time of writing but drift as code evolves. Prefer the method/symbol name for navigation; treat line numbers as a starting hint only.

Used by sections 4 (field units) and 7 (arch spirits). Merges only non-null fields:

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("effectsJson")           and ud["effectsJson"] != null:
        unit["effectsJson"]           = ud["effectsJson"]
    if ud.has("abilitiesJson")         and ud["abilitiesJson"] != null:
        unit["abilitiesJson"]         = ud["abilitiesJson"]
    if ud.has("abilityUsesJson")       and ud["abilityUsesJson"] != null:
        unit["abilityUsesJson"]       = ud["abilityUsesJson"]

The ud.has(k) and ud[k] != null pattern distinguishes JSON null (no change) from a missing key.

art2dUrl and modelUrl are not merged here — they are stripped from UnitDelta on the server and only ever present in the initial UnitSnapshot (§2). They are applied once when the unit is added (§10 Section 2) and remain on the unit dict for the session.


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. In practice this should never fire: every turn-start regenerates MP for all units, meaning every player always has at least one stat change. If it does fire it indicates a diff bug, not a valid "no change" case.
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(). A _syncing flag prevents multiple concurrent requests; subsequent gaps while a sync is in-flight are no-ops. _apply_state_from_payload validates the response sessionId before applying, discarding stale responses from a previous session.
Client: arch spirit null or missing baseline archSpirit key may exist with a null value (player disconnect). An is Dictionary guard detects this; missing baseline triggers request_sync() for 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.


14. Fixes Applied

All six issues identified in the original audit have been implemented and committed.


Fix 1 — Spectator registry moved to Redis (commit 14a467d)

Was: SpectatorRegistryService held an in-memory ConcurrentDictionary per server pod. In a load-balanced deployment, game.spectate could land on pod A while the next action landed on pod B — pod B's registry was empty, so spectator pushes were silently skipped.

Now: SpectatorRegistryService uses Redis Sets (spectators:{sessionId}). RegisterAsync → SADD with a 24-hour TTL; UnregisterAsync → SREM; GetSpectatorsAsync → SMEMBERS; RemoveSessionAsync → DEL. Spectator registration is now shared across all pods.

Files changed: SOR.Game/SpectatorRegistryService.cs, SOR.Shared/Redis/RedisKeys.cs, SOR.Game/Handlers/GameHandlerBase.cs, GameSpectateHandler.cs, GameStopSpectatingHandler.cs


Fix 2 — Null arch spirit guard in get_unit_by_id and _apply_delta §7 (commit e7bf257)

Was: p.get("archSpirit", {}) returns null (not {}) when the key exists with a null value (server clears it on player disconnect). Calling .get(...) on null crashed: Invalid call. Nonexistent function 'get' in base 'Nil'.

Now: Both sites use the safe pattern:

var arch_val: Variant = p.get("archSpirit")
if arch_val is Dictionary and not (arch_val as Dictionary).is_empty():
    ...

File changed: Client/origin-client/autoloads/Game.gd


Fix 3 — DiffTiles guard confirmed complete (commit e7bf257)

Was: Concern that ChangedTiles might include unchanged tiles in some paths.

Audit result: The no-change guard at GameStateDiffer.cs:159-161 is complete for all fields present in TileDelta. RuinDisabledUntilTurn is intentionally absent from TileDelta (it is a server-side scheduler value, not a client-visible state field). No code change needed.


Fix 4 — modelUrl / art2dUrl stripped from UnitDelta (commit 93e3c8b)

Was: UnitDelta included Art2dUrl and ModelUrl on every unit update. These CDN URLs are fixed for the lifetime of a card definition and were wasteful to repeat. The client had a multi-casing fallback (modelUrl, ModelUrl, modelurl, etc.) as evidence of the inconsistency.

Now:

  • UnitDelta record has no URL fields. URLs are only in UnitSnapshot (CardInstanceDto), delivered once when the unit is first added.
  • DiffUnit no longer compares or emits Art2dUrl / ModelUrl.
  • _merge_unit_delta no longer applies URL fields from deltas.
  • modelUrl and art2dUrl are set once on the unit dict in the unitsAdded path and remain there for the session.

Files changed: SOR.Game/GameMessages.cs, SOR.Game/GameStateDiffer.cs, Client/origin-client/autoloads/Game.gd


Fix 5 — iOS Safari scoped asset loading (commit c8c3666)

Was: All 3D models were loaded and retained indefinitely. On iOS Safari (~300 MB per-tab limit) this caused tab crashes as more distinct cards appeared over a game.

Now:

  • Platform.gd (new autoload): Platform.is_ios_safari() detects iPhone/iPad Safari via JavaScriptBridge.eval("navigator.userAgent"), excluding Chrome/CriOS.
  • ModelCache.release_model(url, etag): on iOS Safari, removes the PackedScene from the in-memory _mem dict when a unit leaves the board. Disk cache is preserved for fast reload if the same card type reappears. No-op on all other platforms.
  • unit_mesh_builder.gd: stores the resolved model_url/model_etag per unit in _unit_model_urls / _unit_model_etags. In the to_remove loop, calls ModelCache.release_model before pooling or freeing each unit.
  • ContentCache.get_model_url_for_definition(definition_id): stub for looking up a card's Model3D CDN URL from the definition cache without a live unit dict — foundation for future eviction paths that do not require a fully loaded unit.

Files changed: Client/origin-client/autoloads/Platform.gd (new), Client/origin-client/autoloads/ModelCache.gd, Client/origin-client/autoloads/ContentCache.gd, Client/origin-client/scenes/game/components/units/unit_mesh_builder.gd, Client/origin-client/project.godot


Fix 6 — _fetch_state race: _syncing guard and session-id validation (commit 7e22d87)

Was: _fetch_state() had no in-flight guard. On poor connections, multiple consecutive deltas with gaps triggered concurrent game.get_state requests. _apply_state_from_payload had no session-id check, so a stale response in-flight from a previous session could overwrite state for a new game.

Now:

  • var _syncing: bool = false added to state vars; reset in _clear_state().
  • _fetch_state() returns immediately if _syncing is true; sets it to true before the request; clears it in both the success and error callbacks.
  • _apply_state_from_payload() validates s.get("sessionId") against the current session_id before applying state. Mismatched responses are silently discarded.

File changed: Client/origin-client/autoloads/Game.gd