Improve queue UX, ranked sync latency, and match/lobby flows

Author: Dieg0Code

.railwayignore

@@ -27,3 +27,8 @@ web/test-results/
 *.swp
 *.tmp
 node_modules/
+
+# Local runtime/debug artifacts that can grow very large.
+.tmp*
+*.log
+SCI-FI_UI_SFX_PACK.zip

src/api/error_handling.py

@@ -77,6 +77,8 @@ async def attach_request_id(
             request_id = _resolve_request_id(request)
             status_code = 503 if isinstance(exc, (OperationalError, OSError)) else 500
             detail = "Database unavailable" if status_code == 503 else "Internal server error"
+            raw_error_detail = str(getattr(exc, "orig", exc))
+            error_detail = raw_error_detail[:240] if raw_error_detail else type(exc).__name__
             logger.error(
                 "request_failed",
                 extra={
@@ -85,6 +87,7 @@ async def attach_request_id(
                     "path": request.url.path,
                     "status_code": status_code,
                     "error_type": type(exc).__name__,
+                    "error_detail": error_detail,
                 },
             )
             body = _build_error_body(

src/api/modules/gameplay/repository.py

@@ -213,11 +213,24 @@ async def create_move(self, move: GameMove) -> GameMove:
         await self.session.refresh(move)
         return move
 
+    async def rollback(self) -> None:
+        await self.session.rollback()
+
     async def next_ply(self, game_id: UUID) -> int:
         stmt = select(func.count()).select_from(GameMove).where(GameMove.game_id == game_id)
         result = await self.session.execute(stmt)
         return int(result.scalar_one())
 
+    async def get_last_move(self, game_id: UUID) -> GameMove | None:
+        stmt = (
+            select(GameMove)
+            .where(GameMove.game_id == game_id)
+            .order_by(col(GameMove.ply).desc())
+            .limit(1)
+        )
+        result = await self.session.execute(stmt)
+        return result.scalar_one_or_none()
+
     async def list_moves(self, game_id: UUID, limit: int = 200) -> list[GameMove]:
         stmt = select(GameMove).where(GameMove.game_id == game_id).limit(limit)
         result = await self.session.execute(stmt)

src/api/modules/gameplay/router.py

@@ -37,7 +37,7 @@
     MoveResponse,
     StoredMoveResponse,
 )
-from api.modules.gameplay.service import GameplayService
+from api.modules.gameplay.service import GameplayService, MoveConflictError
 from api.modules.gameplay.ws import gameplay_ws_hub
 from game.actions import ACTION_SPACE
 from game.serialization import board_from_state
@@ -541,6 +541,9 @@ async def post_game_move(
     status_code=status.HTTP_201_CREATED,
     summary="Apply Manual Move",
     description="Stores one explicit move payload for a game. Allowed for participants or admin.",
+    responses={
+        409: {"description": "Move conflict due to stale board or concurrent write."},
+    },
 )
 async def post_game_manual_move(
     game_id: UUID,
@@ -575,6 +578,11 @@ async def post_game_manual_move(
             status_code=status.HTTP_403_FORBIDDEN,
             detail=str(exc),
         ) from exc
+    except MoveConflictError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=str(exc),
+        ) from exc
     except ValueError as exc:
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,

src/api/modules/gameplay/service.py

@@ -4,6 +4,8 @@
 from datetime import datetime, timezone
 from uuid import UUID
 
+from sqlalchemy.exc import DBAPIError
+
 from api.db.enums import (
     AgentType,
     GameStatus,
@@ -24,6 +26,27 @@
 logger = logging.getLogger(__name__)
 
 
+class MoveConflictError(ValueError):
+    """Raised when a move collides with a newer persisted board or concurrent write."""
+
+
+def _is_concurrent_move_db_error(exc: DBAPIError) -> bool:
+    message = str(getattr(exc, "orig", exc)).lower()
+    # Multiple DB backends/drivers report write races with different messages.
+    # Normalize to one conflict path so the API returns 409 instead of 500.
+    conflict_signals = (
+        "duplicate key value",
+        "unique constraint",
+        "uq_game_moves_game_ply",
+        "deadlock detected",
+        "could not serialize access",
+        "serialization failure",
+        "database is locked",
+        "lock timeout",
+    )
+    return any(signal in message for signal in conflict_signals)
+
+
 class GameplayService:
     def __init__(
         self,
@@ -303,35 +326,52 @@ async def record_manual_move(
         mode: str = "manual",
     ) -> tuple[GameMove, Game]:
         game = await self.ensure_can_view_game(game_id=game_id, actor_user=actor_user)
+        board_before = board_to_state(board)
+        last_move = await self.game_repository.get_last_move(game_id)
+        if (
+            last_move is not None
+            and isinstance(last_move.board_after, dict)
+            and last_move.board_after != board_before
+        ):
+            raise MoveConflictError(
+                "Board state is stale; refresh game state and retry the move."
+            )
 
         legal_moves = board.get_valid_moves()
         if move not in legal_moves:
             raise ValueError("Illegal move for provided board state.")
 
         ply = await self.game_repository.next_ply(game_id)
         side = PlayerSide.P1 if board.current_player == 1 else PlayerSide.P2
-        board_before = board_to_state(board)
         scratch = board.copy()
         scratch.step(move)
         board_after = board_to_state(scratch)
 
         r1, c1, r2, c2 = move
-        stored_move = await self.game_repository.create_move(
-            GameMove(
-                game_id=game_id,
-                ply=ply,
-                player_side=side,
-                r1=r1,
-                c1=c1,
-                r2=r2,
-                c2=c2,
-                board_before=board_before,
-                board_after=board_after,
-                mode=mode,
-                action_idx=ACTION_SPACE.encode(move),
-                value=0.0,
+        try:
+            stored_move = await self.game_repository.create_move(
+                GameMove(
+                    game_id=game_id,
+                    ply=ply,
+                    player_side=side,
+                    r1=r1,
+                    c1=c1,
+                    r2=r2,
+                    c2=c2,
+                    board_before=board_before,
+                    board_after=board_after,
+                    mode=mode,
+                    action_idx=ACTION_SPACE.encode(move),
+                    value=0.0,
+                )
             )
-        )
+        except DBAPIError as exc:
+            await self.game_repository.rollback()
+            if _is_concurrent_move_db_error(exc):
+                raise MoveConflictError(
+                    "Concurrent move conflict; refresh board and retry."
+                ) from exc
+            raise
         await self._update_game_state(game=game, board_after=scratch)
         return stored_move, game
 

src/api/modules/matchmaking/repository.py

@@ -123,6 +123,12 @@ async def cancel_waiting_entry(
     async def get_entry_by_id(self, queue_id: UUID) -> QueueEntry | None:
         return await self.session.get(QueueEntry, queue_id)
 
+    async def get_game(self, game_id: UUID) -> Game | None:
+        return await self.session.get(Game, game_id)
+
+    async def get_user(self, user_id: UUID) -> User | None:
+        return await self.session.get(User, user_id)
+
     async def list_matched_entries_for_game(self, *, season_id: UUID, game_id: UUID) -> list[QueueEntry]:
         stmt = (
             select(QueueEntry)

src/api/modules/matchmaking/schemas.py

@@ -16,6 +16,7 @@ class QueueJoinResponse(BaseModel):
                 "season_id": "4aaddf8e-ca81-4347-a278-f6f7be86c6d0",
                 "game_id": "44efed45-d197-4416-bc45-d1cc804f3936",
                 "matched_with": "bot",
+                "opponent_username": "mm-bot-hard",
                 "created_at": "2026-02-23T01:10:00",
                 "updated_at": "2026-02-23T01:10:02",
             }
@@ -27,6 +28,7 @@ class QueueJoinResponse(BaseModel):
     season_id: UUID
     game_id: UUID | None
     matched_with: Literal["human", "bot"] | None = None
+    opponent_username: str | None = None
     created_at: datetime
     updated_at: datetime
 
@@ -40,6 +42,7 @@ class QueueStatusResponse(BaseModel):
                 "season_id": "4aaddf8e-ca81-4347-a278-f6f7be86c6d0",
                 "game_id": None,
                 "matched_with": None,
+                "opponent_username": None,
                 "created_at": "2026-02-23T01:10:00",
                 "updated_at": "2026-02-23T01:10:00",
             }
@@ -51,6 +54,7 @@ class QueueStatusResponse(BaseModel):
     season_id: UUID | None
     game_id: UUID | None
     matched_with: Literal["human", "bot"] | None = None
+    opponent_username: str | None = None
     created_at: datetime | None = None
     updated_at: datetime | None = None
 

src/api/modules/matchmaking/service.py

@@ -80,12 +80,17 @@ async def join_ranked_queue(self, *, actor_user: User) -> QueueJoinResponse:
         refreshed = await self.repository.get_entry_by_id(entry.id)
         if refreshed is None:
             raise LookupError("Queue entry not found after join.")
+        opponent_username = await self._resolve_opponent_username(
+            actor_user_id=actor_user.id,
+            game_id=refreshed.matched_game_id,
+        )
         return QueueJoinResponse(
             queue_id=refreshed.id,
             status=self._status_value(refreshed.status),
             season_id=refreshed.season_id,
             game_id=game_id,
             matched_with=matched_with,
+            opponent_username=opponent_username,
             created_at=refreshed.created_at,
             updated_at=refreshed.updated_at,
         )
@@ -115,13 +120,24 @@ async def get_status(self, *, actor_user: User) -> QueueStatusResponse:
                 refreshed = await self.repository.get_entry_by_id(entry.id)
                 if refreshed is not None:
                     entry = refreshed
+        elif entry.status == QueueEntryStatus.MATCHED:
+            matched_with = await self._resolve_matched_with(
+                actor_user_id=actor_user.id,
+                game_id=entry.matched_game_id,
+            )
+
+        opponent_username = await self._resolve_opponent_username(
+            actor_user_id=actor_user.id,
+            game_id=entry.matched_game_id,
+        )
 
         return QueueStatusResponse(
             queue_id=entry.id,
             status=self._status_value(entry.status),
             season_id=entry.season_id,
             game_id=entry.matched_game_id,
             matched_with=matched_with,
+            opponent_username=opponent_username,
             created_at=entry.created_at,
             updated_at=entry.updated_at,
         )
@@ -326,3 +342,53 @@ def _select_bot_candidate(
             if roll <= cumulative:
                 return bot_user
         return candidates[-1][0]
+
+    async def _resolve_opponent_username(
+        self,
+        *,
+        actor_user_id: UUID,
+        game_id: UUID | None,
+    ) -> str | None:
+        if game_id is None:
+            return None
+        game = await self.repository.get_game(game_id)
+        if game is None:
+            return None
+
+        opponent_user_id: UUID | None = None
+        if game.player1_id == actor_user_id:
+            opponent_user_id = game.player2_id
+        elif game.player2_id == actor_user_id:
+            opponent_user_id = game.player1_id
+        if opponent_user_id is None:
+            return None
+
+        opponent_user = await self.repository.get_user(opponent_user_id)
+        if opponent_user is None:
+            return None
+        return opponent_user.username
+
+    async def _resolve_matched_with(
+        self,
+        *,
+        actor_user_id: UUID,
+        game_id: UUID | None,
+    ) -> MatchedWith | None:
+        if game_id is None:
+            return None
+        game = await self.repository.get_game(game_id)
+        if game is None:
+            return None
+
+        opponent_user_id: UUID | None = None
+        if game.player1_id == actor_user_id:
+            opponent_user_id = game.player2_id
+        elif game.player2_id == actor_user_id:
+            opponent_user_id = game.player1_id
+        if opponent_user_id is None:
+            return None
+
+        opponent_user = await self.repository.get_user(opponent_user_id)
+        if opponent_user is None:
+            return None
+        return "bot" if opponent_user.is_bot else "human"

src/api/modules/ranking/repository.py

@@ -67,14 +67,18 @@ async def list_rating_events(
         limit: int = 50,
         offset: int = 0,
     ) -> list[RatingEvent]:
-        stmt = select(RatingEvent).where(
-            RatingEvent.user_id == user_id,
-            RatingEvent.season_id == season_id,
+        stmt = (
+            select(RatingEvent)
+            .where(
+                RatingEvent.user_id == user_id,
+                RatingEvent.season_id == season_id,
+            )
+            .order_by(col(RatingEvent.created_at).desc(), col(RatingEvent.id).desc())
+            .limit(limit)
+            .offset(offset)
         )
         result = await self.session.execute(stmt)
-        rows = list(result.scalars().all())
-        rows.sort(key=lambda row: row.created_at, reverse=True)
-        return rows[offset : offset + limit]
+        return list(result.scalars().all())
 
     async def get_latest_rating_events_for_user_ids(
         self,

tests/test_api_games_integration.py

@@ -270,6 +270,40 @@ def test_creator_can_control_bot_vs_bot_game(self) -> None:
         )
         self.assertEqual(outsider_move.status_code, 403)
 
+    def test_manual_move_rejects_stale_board_snapshot(self) -> None:
+        user = self._register_and_login("gp-stale-user", "gp-stale-user@example.com")
+        create_resp = self.client.post(
+            "/api/v1/gameplay/games",
+            json={"queue_type": "casual"},
+            headers={"Authorization": f"Bearer {user['access_token']}"},
+        )
+        self.assertEqual(create_resp.status_code, 201)
+        game_id = create_resp.json()["id"]
+
+        board = AtaxxBoard()
+        first_move = self.client.post(
+            f"/api/v1/gameplay/games/{game_id}/move/manual",
+            json={
+                "board": board_to_state(board),
+                "move": {"r1": 0, "c1": 0, "r2": 1, "c2": 1},
+                "mode": "manual",
+            },
+            headers={"Authorization": f"Bearer {user['access_token']}"},
+        )
+        self.assertEqual(first_move.status_code, 201)
+
+        stale_move = self.client.post(
+            f"/api/v1/gameplay/games/{game_id}/move/manual",
+            json={
+                "board": board_to_state(board),
+                "move": {"r1": 0, "c1": 0, "r2": 1, "c2": 1},
+                "mode": "manual",
+            },
+            headers={"Authorization": f"Bearer {user['access_token']}"},
+        )
+        self.assertEqual(stale_move.status_code, 409)
+        self.assertIn("stale", str(stale_move.json()["detail"]).lower())
+
     def test_create_game_rejects_same_player_on_both_sides(self) -> None:
         creator = self._register_and_login("gp-owner-same", "gp-owner-same@example.com")
         bot_id = self._create_bot_user_with_profile(