fix: game order api & tests

game/openapi.yaml

@@ -136,8 +136,9 @@ paths:
       description: |
         Applies one or more game commands for the specified actor. Serialized
         to one concurrent execution; requests that cannot acquire the execution
-        slot within 100 ms return `504 Gateway Timeout`. Returns `204 No
-        Content` on success.
+        slot within 100 ms return `504 Gateway Timeout`. Returns `202 Accepted`
+        with no body on success. Reserved for future use; player order
+        submissions go through `/api/v1/order`.
       requestBody:
         required: true
         content:
@@ -145,8 +146,8 @@ paths:
             schema:
               $ref: "#/components/schemas/CommandRequest"
       responses:
-        "204":
-          description: All commands applied successfully.
+        "202":
+          description: All commands accepted.
         "400":
           $ref: "#/components/responses/ValidationError"
         "504":
@@ -161,7 +162,9 @@ paths:
       summary: Validate and store a player order without executing it
       description: |
         Validates and stores the game commands structurally without executing them.
-        Returns `204 No Content` if the order is valid and accepted.
+        On success returns `202 Accepted` with the stored order, including the
+        engine-assigned `updatedAt` timestamp used by clients to detect stale
+        submissions.
       requestBody:
         required: true
         content:
@@ -169,8 +172,37 @@ paths:
             schema:
               $ref: "#/components/schemas/CommandRequest"
       responses:
+        "202":
+          description: Order is structurally valid and stored.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UserGamesOrder"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+    get:
+      tags:
+        - PlayerActions
+      operationId: getOrder
+      summary: Fetch the stored order for a player and turn
+      description: |
+        Returns the order previously stored by `PUT /api/v1/order` for the
+        specified player and turn. Responds `204 No Content` when no order
+        has been stored for that turn.
+      parameters:
+        - $ref: "#/components/parameters/PlayerParam"
+        - $ref: "#/components/parameters/TurnParam"
+      responses:
+        "200":
+          description: Stored player order for the requested turn.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UserGamesOrder"
         "204":
-          description: Order is structurally valid.
+          description: No order has been stored for this player on this turn.
         "400":
           $ref: "#/components/responses/ValidationError"
         "500":
@@ -362,6 +394,32 @@ components:
           minItems: 1
           items:
             $ref: "#/components/schemas/Command"
+    UserGamesOrder:
+      type: object
+      description: |
+        Stored player order. Returned by `PUT /api/v1/order` after successful
+        validation and by `GET /api/v1/order` when fetching a previously stored
+        batch. `cmd` mirrors the command list submitted by the player; entries
+        carry per-command result fields (`cmdApplied`, `cmdErrorCode`) once the
+        order has been processed during turn generation.
+      required:
+        - game_id
+        - updatedAt
+        - cmd
+      properties:
+        game_id:
+          type: string
+          format: uuid
+          description: Identifier of the game this order belongs to.
+        updatedAt:
+          type: integer
+          format: int64
+          description: Engine-assigned UTC millisecond timestamp of the last write.
+        cmd:
+          type: array
+          description: Commands stored as part of this order, in submission order.
+          items:
+            $ref: "#/components/schemas/Command"
     Command:
       type: object
       description: |