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>

game/internal/router/router.go

@@ -18,24 +18,20 @@ const (
 )
 
 type Router struct {
-	r        *gin.Engine
-	executor handler.CommandExecutor
+	r *gin.Engine
 }
 
 func (r Router) Run() error {
 	return r.r.Run()
 }
 
-func NewRouter() Router {
+// NewRouter builds the HTTP router around the supplied engine.
+func NewRouter(engine handler.Engine) Router {
 	gin.SetMode(gin.ReleaseMode)
-	return NewRouterExecutor(handler.NewDefaultExecutor())
+	return Router{r: setupRouter(engine)}
 }
 
-func NewRouterExecutor(executor handler.CommandExecutor) Router {
-	return Router{r: setupRouter(executor)}
-}
-
-func setupRouter(executor handler.CommandExecutor) *gin.Engine {
+func setupRouter(engine handler.Engine) *gin.Engine {
 	r := gin.New()
 
 	// Logger middleware will write the logs to gin.DefaultWriter even if you set with GIN_MODE=release.
@@ -67,19 +63,22 @@ func setupRouter(executor handler.CommandExecutor) *gin.Engine {
 
 	groupV1 := r.Group("/api/v1")
 
+	// One shared limiter serialises every operation that mutates the
+	// canonical game state file (state.json): there is at most one such
+	// write in flight at a time. Orders write independent per-player files
+	// and stay unsynchronised; reads are lock-free.
+	stateMutationLimit := LimitMiddleware(1)
+
 	groupAdmin := groupV1.Group("/admin")
-	groupAdmin.GET("/status", func(ctx *gin.Context) { handler.StatusHandler(ctx, executor) })
-	groupAdmin.POST("/init", func(ctx *gin.Context) { handler.InitHandler(ctx, executor) })
-	groupAdmin.PUT("/turn", func(ctx *gin.Context) { handler.TurnHandler(ctx, executor) })
-	groupAdmin.POST("/race/banish", func(ctx *gin.Context) { handler.BanishHandler(ctx, executor) })
+	groupAdmin.GET("/status", func(ctx *gin.Context) { handler.StatusHandler(ctx, engine) })
+	groupAdmin.POST("/init", stateMutationLimit, func(ctx *gin.Context) { handler.InitHandler(ctx, engine) })
+	groupAdmin.PUT("/turn", stateMutationLimit, func(ctx *gin.Context) { handler.TurnHandler(ctx, engine) })
+	groupAdmin.POST("/race/banish", stateMutationLimit, func(ctx *gin.Context) { handler.BanishHandler(ctx, engine) })
 
-	groupV1.GET("/report", func(ctx *gin.Context) { handler.ReportHandler(ctx, executor) })
-	groupV1.PUT("/order", func(ctx *gin.Context) { handler.PutOrderHandler(ctx, executor) })
-	groupV1.GET("/order", func(ctx *gin.Context) { handler.GetOrderHandler(ctx, executor) })
-	groupV1.GET("/battle/:turn/:uuid", func(ctx *gin.Context) { handler.BattleHandler(ctx, executor) })
-
-	// /command is reserved for future use; any API request for orders should use /order
-	groupV1.PUT("/command", LimitMiddleware(1), func(ctx *gin.Context) { handler.CommandHandler(ctx, executor) })
+	groupV1.GET("/report", func(ctx *gin.Context) { handler.ReportHandler(ctx, engine) })
+	groupV1.PUT("/order", func(ctx *gin.Context) { handler.PutOrderHandler(ctx, engine) })
+	groupV1.GET("/order", func(ctx *gin.Context) { handler.GetOrderHandler(ctx, engine) })
+	groupV1.GET("/battle/:turn/:uuid", func(ctx *gin.Context) { handler.BattleHandler(ctx, engine) })
 
 	return r
 }