feat: gamemaster

game/README.md

@@ -39,13 +39,54 @@ do not pass per-game limits.
 ## Endpoints
 
 The contract is the union of `openapi.yaml` and the technical liveness probe
-described below.
+described below. Endpoints split into two route classes:
+
+| Class | Path | Caller | Purpose |
+| --- | --- | --- | --- |
+| Admin (GM-only) | `POST /api/v1/admin/init` | `Game Master` | Initialise the engine with the race roster. |
+| Admin (GM-only) | `GET /api/v1/admin/status` | `Game Master` | Read the full game state. |
+| Admin (GM-only) | `PUT /api/v1/admin/turn` | `Game Master` | Generate the next turn. |
+| Admin (GM-only) | `POST /api/v1/admin/race/banish` | `Game Master` | Deactivate a race after a permanent platform removal. |
+| Player | `PUT /api/v1/command` | `Game Master` (forwarded from `Edge Gateway`) | Execute a batch of player commands. |
+| Player | `PUT /api/v1/order` | `Game Master` | Validate and store a batch of player orders. |
+| Player | `GET /api/v1/report` | `Game Master` | Fetch the per-player turn report. |
+| Probe | `GET /healthz` | `Runtime Manager` | Technical liveness probe. |
+
+Admin paths are unauthenticated but are routed only from inside the
+trusted network segment that connects `Game Master` to the engine
+container. The engine does not enforce caller identity — network-level
+segmentation is the boundary. Player paths apply the same rule and rely
+on `Game Master` to forward only verified player payloads.
 
 ### Game endpoints
 
 Documented in [`openapi.yaml`](openapi.yaml). When the engine has not been
-initialised through `POST /api/v1/init`, game endpoints respond `501 Not
-Implemented` to make the uninitialised state unambiguous.
+initialised through `POST /api/v1/admin/init`, game endpoints respond
+`501 Not Implemented` to make the uninitialised state unambiguous.
+
+### `StateResponse.finished`
+
+`StateResponse` (returned by `GET /api/v1/admin/status` and
+`PUT /api/v1/admin/turn`) carries a required boolean `finished` field.
+The engine sets it to `true` exactly once on the turn-generation response
+that ends the game; otherwise it stays `false`. `Game Master` uses this
+field as the sole signal to run the platform finish flow. The conditional
+logic that flips `finished` to `true` lives in the engine's domain code
+and is owned by the engine maintainers.
+
+### `POST /api/v1/admin/race/banish`
+
+Deactivates a race after a permanent platform-level membership removal.
+`Game Master` calls this endpoint synchronously after a Lobby-driven
+remove-and-banish flow.
+
+- Request body: `{ "race_name": "<name>" }`. `race_name` must be
+  non-empty and must match an existing race in the engine's roster.
+- Successful response: `204 No Content` with an empty body.
+- Error responses follow the same `400` / `500` envelope shape as the
+  other admin endpoints. The engine-side mechanics of `banish` (what
+  exactly happens to the race's planets, fleets, and pending orders) are
+  owned by the engine maintainers.
 
 ### `GET /healthz`
 
@@ -53,9 +94,9 @@ Technical liveness probe used by `Runtime Manager` and operator tooling.
 
 - 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`.
-- Carries no game-state semantics. Use `GET /api/v1/status` for game-state
-  inspection.
+  through `POST /api/v1/admin/init`.
+- Carries no game-state semantics. Use `GET /api/v1/admin/status` for
+  game-state inspection.
 
 This endpoint exists so that `Runtime Manager` can probe a freshly started
 container before `init` runs.