refactor(game): lock-free storage, remove /command, flatten engine wrapper

Three-stage refactor of the game-engine plumbing (game logic untouched):

Stage 1 — lock-free persistence + admin serialisation. Remove the file
lock from repo/fs (the .lock file, the Read/Write-vs-*Safe duality and the
dead ReadSafe polling) and replace the two-step rename with a single atomic
rename so concurrent reads are torn-free without a lock. Serialise the
state-mutating admin writers (init/turn/banish) with one shared router
LimitMiddleware, rewritten to block on the request context instead of a
racy shared 100ms timer.

Stage 2 — remove the obsolete immediate-command path end to end. Players
submit through PUT /api/v1/order; the legacy PUT /api/v1/command path is
deleted across game (route, handler, 24 command factories, Ctrl), backend
(Commands handler/route, engineclient.ExecuteCommands), gateway (dispatch +
executeUserGamesCommand + routing entry), the FlatBuffers/model contract
(UserGamesCommand[Response]) and transcoder, plus every affected
OpenAPI/README/FUNCTIONAL/ARCHITECTURE doc. The integration proxy test is
converted to the order path.

Stage 3 — flatten the REST->engine wrapper. Replace the executor adapter,
the controller package functions and RepoController with one concrete
controller.Service; drop the single-implementation Repo and Storage
interfaces (repo.Repo / fs.FS are now concrete). Handlers depend on a thin
handler.Engine seam and own the domain->REST projection; storage is
resolved once at startup instead of per request.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

backend/internal/engineclient/client.go

@@ -23,7 +23,6 @@ const (
 	pathAdminStatus     = "/api/v1/admin/status"
 	pathAdminTurn       = "/api/v1/admin/turn"
 	pathAdminRaceBanish = "/api/v1/admin/race/banish"
-	pathPlayerCommand   = "/api/v1/command"
 	pathPlayerOrder     = "/api/v1/order"
 	pathPlayerReport    = "/api/v1/report"
 	pathPlayerBattle    = "/api/v1/battle"
@@ -183,16 +182,10 @@ func (c *Client) BanishRace(ctx context.Context, baseURL, raceName string) error
 	}
 }
 
-// ExecuteCommands calls `PUT /api/v1/command` with payload forwarded
+// PutOrders calls `PUT /api/v1/order` with the payload forwarded
 // verbatim. The engine response body is returned verbatim; on 4xx the
-// body is returned alongside ErrEngineValidation so callers can
-// forward the per-command error.
-func (c *Client) ExecuteCommands(ctx context.Context, baseURL string, payload json.RawMessage) (json.RawMessage, error) {
-	return c.forwardPlayerWrite(ctx, baseURL, pathPlayerCommand, payload, "engine command")
-}
-
-// PutOrders calls `PUT /api/v1/order` with the same forwarding
-// semantics as ExecuteCommands.
+// body is returned alongside ErrEngineValidation so callers can forward
+// the per-command error.
 func (c *Client) PutOrders(ctx context.Context, baseURL string, payload json.RawMessage) (json.RawMessage, error) {
 	return c.forwardPlayerWrite(ctx, baseURL, pathPlayerOrder, payload, "engine order")
 }

backend/internal/engineclient/client_test.go

@@ -156,27 +156,6 @@ func TestClientBanishRace(t *testing.T) {
 	}
 }
 
-func TestClientCommandsForwardsBody(t *testing.T) {
-	want := json.RawMessage(`{"actor":"alpha","cmd":[{"@type":"raceQuit"}]}`)
-	gotResp := json.RawMessage(`{"applied":true}`)
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != pathPlayerCommand || r.Method != http.MethodPut {
-			t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
-		}
-		_, _ = w.Write(gotResp)
-	}))
-	t.Cleanup(srv.Close)
-
-	cli := newTestClient(t, srv)
-	resp, err := cli.ExecuteCommands(context.Background(), srv.URL, want)
-	if err != nil {
-		t.Fatalf("ExecuteCommands: %v", err)
-	}
-	if string(resp) != string(gotResp) {
-		t.Fatalf("response = %s, want %s", string(resp), string(gotResp))
-	}
-}
-
 func TestClientReportsForwardsQuery(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path != pathPlayerReport {

backend/internal/runtime/errors.go

@@ -52,7 +52,7 @@ var (
 	ErrTurnAlreadyClosed = errors.New("runtime: turn already closed")
 
 	// ErrGamePaused reports that the game is not in a state that
-	// accepts user-games commands or orders: the runtime row
+	// accepts user-games orders: the runtime row
 	// carries `paused = true`, or the runtime status lands on any
 	// terminal value (`engine_unreachable`, `generation_failed`,
 	// `stopped`, `finished`, `removed`), or the game has not yet

backend/internal/runtime/service.go

@@ -258,10 +258,10 @@ func (s *Service) ResolvePlayerMapping(ctx context.Context, gameID, userID uuid.
 }
 
 // CheckOrdersAccept verifies that the runtime is in a state that
-// accepts user-games commands and orders. It is called by the user
-// game-proxy handlers (`Commands`, `Orders`) before forwarding to
-// engine, so the backend's turn-cutoff and pause guards run before
-// network traffic leaves the host. The decision itself lives in the
+// accepts user-games orders. It is called by the user game-proxy
+// handler (`Orders`) before forwarding to engine, so the backend's
+// turn-cutoff and pause guards run before network traffic leaves the
+// host. The decision itself lives in the
 // pure helper `OrdersAcceptStatus` so it can be unit-tested without
 // constructing a full Service.
 //
@@ -276,7 +276,7 @@ func (s *Service) CheckOrdersAccept(ctx context.Context, gameID uuid.UUID) error
 }
 
 // OrdersAcceptStatus inspects a runtime record and returns the
-// matching sentinel for the user-games order/command pre-check:
+// matching sentinel for the user-games order pre-check:
 //
 //   - `runtime_status = generation_in_progress` → `ErrTurnAlreadyClosed`.
 //     The cron-driven `Scheduler.tick` has flipped the row before

backend/internal/server/handlers_user_games.go

@@ -39,55 +39,6 @@ func NewUserGamesHandlers(rt *runtime.Service, engine *engineclient.Client, logg
 	return &UserGamesHandlers{runtime: rt, engine: engine, logger: logger.Named("http.user.games")}
 }
 
-// Commands handles POST /api/v1/user/games/{game_id}/commands.
-func (h *UserGamesHandlers) Commands() gin.HandlerFunc {
-	if h == nil || h.runtime == nil || h.engine == nil {
-		return handlers.NotImplemented("userGamesCommands")
-	}
-	return func(c *gin.Context) {
-		gameID, ok := parseGameIDParam(c)
-		if !ok {
-			return
-		}
-		userID, ok := userid.FromContext(c.Request.Context())
-		if !ok {
-			httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "user id missing")
-			return
-		}
-		body, err := io.ReadAll(c.Request.Body)
-		if err != nil {
-			httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "request body could not be read")
-			return
-		}
-		ctx := c.Request.Context()
-		if err := h.runtime.CheckOrdersAccept(ctx, gameID); err != nil {
-			respondGameProxyError(c, h.logger, "user games commands", ctx, err)
-			return
-		}
-		mapping, err := h.runtime.ResolvePlayerMapping(ctx, gameID, userID)
-		if err != nil {
-			respondGameProxyError(c, h.logger, "user games commands", ctx, err)
-			return
-		}
-		endpoint, err := h.runtime.EngineEndpoint(ctx, gameID)
-		if err != nil {
-			respondGameProxyError(c, h.logger, "user games commands", ctx, err)
-			return
-		}
-		payload, err := rebindActor(body, mapping.RaceName)
-		if err != nil {
-			httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "request body must be a JSON object")
-			return
-		}
-		resp, err := h.engine.ExecuteCommands(ctx, endpoint, payload)
-		if err != nil {
-			respondEngineProxyError(c, h.logger, "user games commands", ctx, resp, err)
-			return
-		}
-		c.Data(http.StatusOK, "application/json", resp)
-	}
-}
-
 // Orders handles POST /api/v1/user/games/{game_id}/orders.
 func (h *UserGamesHandlers) Orders() gin.HandlerFunc {
 	if h == nil || h.runtime == nil || h.engine == nil {

backend/internal/server/router.go

@@ -270,7 +270,6 @@ func registerUserRoutes(router *gin.Engine, instruments *metrics.Instruments, de
 	raceNames.POST("/register", deps.UserLobbyRaceNames.Register())
 
 	userGames := group.Group("/games")
-	userGames.POST("/:game_id/commands", deps.UserGames.Commands())
 	userGames.POST("/:game_id/orders", deps.UserGames.Orders())
 	userGames.GET("/:game_id/orders", deps.UserGames.GetOrders())
 	userGames.GET("/:game_id/reports/:turn", deps.UserGames.Report())