feat: gamemaster

game/openapi.yaml

@@ -30,16 +30,17 @@ tags:
   - name: Health
     description: Technical liveness probes used by Runtime Manager and operator tooling.
 paths:
-  /api/v1/status:
+  /api/v1/admin/status:
     get:
       tags:
         - GameLifecycle
-      operationId: getGameStatus
+      operationId: adminGetGameStatus
       summary: Get the current game state
       description: |
         Returns the current game state including turn number, stage, and a
         summary of all players. Returns `501` if the game has not yet been
-        initialized.
+        initialized. Routed only from the trusted network segment that
+        connects `Game Master` to the engine container.
       responses:
         "200":
           description: Current game state.
@@ -51,15 +52,17 @@ paths:
           description: Game has not been initialized yet.
         "500":
           $ref: "#/components/responses/InternalError"
-  /api/v1/init:
+  /api/v1/admin/init:
     post:
       tags:
         - GameLifecycle
-      operationId: initGame
+      operationId: adminInitGame
       summary: Initialize a new game
       description: |
         Generates a new game instance with the supplied list of races.
-        Requires at least 10 race entries.
+        Requires at least 10 race entries. Routed only from the trusted
+        network segment that connects `Game Master` to the engine
+        container.
       requestBody:
         required: true
         content:
@@ -77,6 +80,30 @@ paths:
           $ref: "#/components/responses/ValidationError"
         "500":
           $ref: "#/components/responses/InternalError"
+  /api/v1/admin/race/banish:
+    post:
+      tags:
+        - GameLifecycle
+      operationId: adminBanishRace
+      summary: Deactivate a race after a permanent platform-level removal
+      description: |
+        Deactivates the named race in the running engine. Called by `Game
+        Master` after a Lobby-driven permanent membership removal. Routed
+        only from the trusted network segment that connects `Game Master`
+        to the engine container. 
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/BanishRequest"
+      responses:
+        "204":
+          description: Race deactivated; no response body.
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "500":
+          $ref: "#/components/responses/InternalError"
   /api/v1/report:
     get:
       tags:
@@ -148,15 +175,16 @@ paths:
           $ref: "#/components/responses/ValidationError"
         "500":
           $ref: "#/components/responses/InternalError"
-  /api/v1/turn:
+  /api/v1/admin/turn:
     put:
       tags:
         - GameLifecycle
-      operationId: generateTurn
+      operationId: adminGenerateTurn
       summary: Advance the game to the next turn
       description: |
         Processes the current turn and generates the next one. Returns the
-        updated game state.
+        updated game state. Routed only from the trusted network segment
+        that connects `Game Master` to the engine container.
       responses:
         "200":
           description: Updated game state after turn generation.
@@ -175,10 +203,10 @@ paths:
       description: |
         Returns `{"status":"ok"}` with HTTP `200` whenever the HTTP server
         is serving requests, regardless of whether the engine has been
-        initialised through `POST /api/v1/init`. Used by `Runtime Manager`
-        to probe a freshly started container before `init` runs. Carries
-        no game-state semantics; use `GET /api/v1/status` for game-state
-        inspection.
+        initialised through `POST /api/v1/admin/init`. Used by `Runtime
+        Manager` to probe a freshly started container before `init` runs.
+        Carries no game-state semantics; use `GET /api/v1/admin/status`
+        for game-state inspection.
       responses:
         "200":
           description: Engine HTTP server is up.
@@ -225,6 +253,7 @@ components:
         - turn
         - stage
         - player
+        - finished
       properties:
         id:
           type: string
@@ -243,6 +272,15 @@ components:
           description: Summary state for each player participating in the game.
           items:
             $ref: "#/components/schemas/PlayerState"
+        finished:
+          type: boolean
+          description: |
+            True exactly once on the turn-generation response that ends the
+            game; otherwise false. Server default: false. `Game Master`
+            uses this flag as the sole signal to run the platform finish
+            flow. The conditional logic that flips it to true lives in
+            the engine's domain code and is owned by the engine
+            maintainers.
     PlayerState:
       type: object
       description: Brief player state returned as part of the game state response.
@@ -292,6 +330,18 @@ components:
           type: string
           description: Name of the race. Must be non-blank and satisfy the entity-name format.
           minLength: 1
+    BanishRequest:
+      type: object
+      description: |
+        Request body for the admin banish endpoint. `race_name` must
+        identify an existing race in the engine roster.
+      required:
+        - race_name
+      properties:
+        race_name:
+          type: string
+          description: Name of the race to banish. Must be non-blank.
+          minLength: 1
     CommandRequest:
       type: object
       description: |