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/command_test.go

@@ -1,942 +0,0 @@
-package router_test
-
-import (
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	"galaxy/model/order"
-	"galaxy/model/rest"
-
-	"github.com/stretchr/testify/assert"
-)
-
-func TestCommandRaceQuit(t *testing.T) {
-	r := setupRouter()
-
-	payload := &rest.Command{
-		Actor: commandDefaultActor,
-		Commands: []json.RawMessage{
-			encodeCommand(&order.CommandRaceQuit{
-				CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeRaceQuit},
-			}),
-		},
-	}
-
-	w := httptest.NewRecorder()
-	req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-	r.ServeHTTP(w, req)
-
-	assert.Equal(t, commandNoErrorsStatus, w.Code, w.Body)
-
-	// error: actor not set
-	payload.Actor = ""
-	w = httptest.NewRecorder()
-	req, _ = http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-	r.ServeHTTP(w, req)
-
-	assert.Equal(t, http.StatusBadRequest, w.Code, w.Body)
-
-	payload.Actor = "       "
-	w = httptest.NewRecorder()
-	req, _ = http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-	r.ServeHTTP(w, req)
-
-	assert.Equal(t, http.StatusBadRequest, w.Code, w.Body)
-
-	// unrecognized command type
-	payload.Commands = []json.RawMessage{
-		encodeCommand(&order.CommandRaceQuit{
-			CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandType("-unknown-")},
-		}),
-	}
-	w = httptest.NewRecorder()
-	req, _ = http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-	r.ServeHTTP(w, req)
-
-	assert.Equal(t, http.StatusBadRequest, w.Code, w.Body)
-
-	// error: no commands
-	payload = &rest.Command{
-		Actor: commandDefaultActor,
-	}
-
-	w = httptest.NewRecorder()
-	req, _ = http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-	r.ServeHTTP(w, req)
-
-	assert.Equal(t, http.StatusBadRequest, w.Code, w.Body)
-}
-
-func TestCommandRaceVote(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		acceptor     string
-	}{
-		{commandNoErrorsStatus, "Valid request", "AnotherRace"},
-		{http.StatusBadRequest, "Empty acceptor", ""},
-		{http.StatusBadRequest, "Blank acceptor", "      "},
-		{http.StatusBadRequest, "Invalid acceptor", "Race_👽"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandRaceVote{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeRaceVote},
-						Acceptor:    tc.acceptor,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandRaceRelation(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		relation     string
-		acceptor     string
-	}{
-		{commandNoErrorsStatus, "Valid request 1", "WAR", "Opponent"},
-		{commandNoErrorsStatus, "Valid request 2", "PEACE", "Opponent"},
-		{http.StatusBadRequest, "Empty relation", "", "Opponent"},
-		{http.StatusBadRequest, "Blank relation", "  ", "Opponent"},
-		{http.StatusBadRequest, "Invalid relation", "Woina", "Opponent"},
-		{http.StatusBadRequest, "Empty acceptor", "WAR", ""},
-		{http.StatusBadRequest, "Blank acceptor", "WAR", "   "},
-		{http.StatusBadRequest, "Invalid acceptor", "PEACE", "Race_👽"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandRaceRelation{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeRaceRelation},
-						Acceptor:    tc.acceptor,
-						Relation:    tc.relation,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandShipClassCreate(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		D            float64
-		A            int
-		W, S, C      float64
-		name         string
-		expectStatus int
-		description  string
-	}{
-		{1, 0, 0, 0, 0, "Drone", commandNoErrorsStatus, "Simple Drone"},
-		{1, 1, 1, 0, 0, "Drone", commandNoErrorsStatus, "Armed Drone"},
-		{1, 0, 0, 1, 0, "Drone", commandNoErrorsStatus, "Shielded Drone"},
-		{1, 0, 0, 0, 1, "Drone", commandNoErrorsStatus, "Carrying Drone"},
-		{1, 0, 0, 0, 0, "", http.StatusBadRequest, "Empty name"},
-		{1, 0, 0, 0, 0, "   ", http.StatusBadRequest, "Blank name"},
-		{1, 0, 0, 0, 0, "Drone🚀", http.StatusBadRequest, "Invalid name"},
-		{-0.5, 0, 0, 0, 0, "Drone", http.StatusBadRequest, "Drive less than 0"},
-		{0.9, 0, 0, 0, 0, "Drone", http.StatusBadRequest, "Drive less than 1"},
-		{1, 1, 0, 0, 0, "Drone", http.StatusBadRequest, "Ammo without Weapons"},
-		{1, 0, 1, 0, 0, "Drone", http.StatusBadRequest, "Weapons without Ammo"},
-		{1, -1, 1, 0, 0, "Drone", http.StatusBadRequest, "Ammo less than 0"},
-		{1, 1, 0.9, 0, 0, "Drone", http.StatusBadRequest, "Weapons less than 1"},
-		{1, 1, -0.5, 0, 0, "Drone", http.StatusBadRequest, "Weapons less than 0"},
-		{1, 0, 0, -0.5, 0, "Drone", http.StatusBadRequest, "Shields less than 0"},
-		{1, 0, 0, 0.9, 0, "Drone", http.StatusBadRequest, "Shields less than 1"},
-		{1, 0, 0, 0, -0.5, "Drone", http.StatusBadRequest, "Cargo less than 0"},
-		{1, 0, 0, 0, 0.9, "Drone", http.StatusBadRequest, "Cargo less than 1"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandShipClassCreate{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeShipClassCreate},
-						Name:        tc.name,
-						Drive:       tc.D,
-						Armament:    tc.A,
-						Weapons:     tc.W,
-						Shields:     tc.S,
-						Cargo:       tc.C,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandShipClassMerge(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		name         string
-		target       string
-	}{
-		{commandNoErrorsStatus, "Valid request", "Drone", "Spy"},
-		{http.StatusBadRequest, "Empty name", "", "Spy"},
-		{http.StatusBadRequest, "Blank name", "   ", "Spy"},
-		{http.StatusBadRequest, "Invalid name", "Drone🚀", "Spy"},
-		{http.StatusBadRequest, "Empty name", "Drone", " "},
-		{http.StatusBadRequest, "Blank name", "Drone", "   "},
-		{http.StatusBadRequest, "Invalid name", "Drone", "Spy🚀"},
-		{http.StatusBadRequest, "Equal names", "Drone", "Drone"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandShipClassMerge{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeShipClassMerge},
-						Name:        tc.name,
-						Target:      tc.target,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandShipClassRemove(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		name         string
-	}{
-		{commandNoErrorsStatus, "Valid request", "Drone"},
-		{http.StatusBadRequest, "Empty name", ""},
-		{http.StatusBadRequest, "Blank name", "   "},
-		{http.StatusBadRequest, "Invalid name", "Drone🚀"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandShipClassRemove{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeShipClassRemove},
-						Name:        tc.name,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandShipGroupBreak(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		id           string
-		newId        string
-		quantity     int
-	}{
-		{commandNoErrorsStatus, "Valid request #1", validId1, validId2, 1},
-		{commandNoErrorsStatus, "Valid request #2", validId1, validId2, 0},
-		{http.StatusBadRequest, "Negative quantity", validId1, validId2, -1},
-		{http.StatusBadRequest, "Empty id", "", validId2, 1},
-		{http.StatusBadRequest, "Invalid id", invalidId, validId2, 1},
-		{http.StatusBadRequest, "Empty newId", validId1, "", 1},
-		{http.StatusBadRequest, "Invalid newId", validId1, invalidId, 1},
-		{http.StatusBadRequest, "Equal id and newId", validId1, validId1, 1},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandShipGroupBreak{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeShipGroupBreak},
-						ID:          tc.id,
-						NewID:       tc.newId,
-						Quantity:    tc.quantity,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandShipGroupLoad(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		id           string
-		cargo        string
-		quantity     float64
-	}{
-		{commandNoErrorsStatus, "Valid request #1", validId1, "COL", 0},
-		{commandNoErrorsStatus, "Valid request #2", validId1, "MAT", 1},
-		{commandNoErrorsStatus, "Valid request #2", validId1, "CAP", 2},
-		{http.StatusBadRequest, "Invalid quantity", validId1, "COL", -0.5},
-		{http.StatusBadRequest, "Empty cargo", validId1, "", 1},
-		{http.StatusBadRequest, "Invalid cargo", validId1, "IND", 1},
-		{http.StatusBadRequest, "Empty id", "", "COL", 1},
-		{http.StatusBadRequest, "Invalid id", invalidId, "COL", 1},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandShipGroupLoad{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeShipGroupLoad},
-						ID:          tc.id,
-						Cargo:       tc.cargo,
-						Quantity:    tc.quantity,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandShipGroupUnload(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		id           string
-		quantity     float64
-	}{
-		{commandNoErrorsStatus, "Valid request #1", validId1, 0},
-		{commandNoErrorsStatus, "Valid request #2", validId1, 1},
-		{http.StatusBadRequest, "Invalid quantity", validId1, -0.5},
-		{http.StatusBadRequest, "Empty id", "", 1},
-		{http.StatusBadRequest, "Invalid id", invalidId, 1},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandShipGroupUnload{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeShipGroupUnload},
-						ID:          tc.id,
-						Quantity:    tc.quantity,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandShipGroupSend(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		id           string
-		destination  int
-	}{
-		{commandNoErrorsStatus, "Valid request #1", validId1, 0},
-		{commandNoErrorsStatus, "Valid request #1", validId1, 1},
-		{http.StatusBadRequest, "Invalid destination", validId1, -1},
-		{http.StatusBadRequest, "Empty id", "", 1},
-		{http.StatusBadRequest, "Invalid id", invalidId, 1},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandShipGroupSend{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeShipGroupSend},
-						ID:          tc.id,
-						Destination: tc.destination,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandShipGroupUpgrade(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		id           string
-		tech         string
-		level        float64
-	}{
-		{commandNoErrorsStatus, "Valid request #1", validId1, "ALL", 0},
-		{commandNoErrorsStatus, "Valid request #1", validId1, "DRIVE", 1.1},
-		{commandNoErrorsStatus, "Valid request #1", validId1, "WEAPONS", 2.1},
-		{commandNoErrorsStatus, "Valid request #1", validId1, "SHIELDS", 3.1},
-		{commandNoErrorsStatus, "Valid request #1", validId1, "CARGO", 4.1},
-		{http.StatusBadRequest, "Negative level", validId1, "DRIVE", -0.5},
-		{http.StatusBadRequest, "Invalid level 0.5", validId1, "DRIVE", 0.5},
-		{http.StatusBadRequest, "Invalid level 1.0", validId1, "DRIVE", 1.0},
-		{http.StatusBadRequest, "Empty id", "", "ALL", 0},
-		{http.StatusBadRequest, "Invalid id", invalidId, "ALL", 0},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandShipGroupUpgrade{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeShipGroupUpgrade},
-						ID:          tc.id,
-						Tech:        tc.tech,
-						Level:       tc.level,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandShipGroupMerge(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-	}{
-		{commandNoErrorsStatus, "Valid request"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandShipGroupMerge{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeShipGroupMerge},
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandShipGroupDismantle(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		id           string
-	}{
-		{commandNoErrorsStatus, "Valid request", validId1},
-		{http.StatusBadRequest, "Empty id", ""},
-		{http.StatusBadRequest, "Invalid id", invalidId},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandShipGroupDismantle{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeShipGroupDismantle},
-						ID:          tc.id,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandShipGroupTransfer(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		id           string
-		acceptor     string
-	}{
-		{commandNoErrorsStatus, "Valid request", validId1, "AnotherRace"},
-		{http.StatusBadRequest, "Blank id", "", "AnotherRace"},
-		{http.StatusBadRequest, "Invalid id", invalidId, "AnotherRace"},
-		{http.StatusBadRequest, "Empty acceptor", validId1, ""},
-		{http.StatusBadRequest, "Blank acceptor", validId1, "      "},
-		{http.StatusBadRequest, "Invalid acceptor", validId1, "Race_👽"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandShipGroupTransfer{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeShipGroupTransfer},
-						ID:          tc.id,
-						Acceptor:    tc.acceptor,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandShipGroupJoinFleet(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		id           string
-		name         string
-	}{
-		{commandNoErrorsStatus, "Valid request", validId1, "AnotherRace"},
-		{http.StatusBadRequest, "Blank id", "", "AnotherRace"},
-		{http.StatusBadRequest, "Invalid id", invalidId, "AnotherRace"},
-		{http.StatusBadRequest, "Empty name", validId1, ""},
-		{http.StatusBadRequest, "Blank name", validId1, "      "},
-		{http.StatusBadRequest, "Invalid name", validId1, "Fleet_🚢"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandShipGroupJoinFleet{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeShipGroupJoinFleet},
-						ID:          tc.id,
-						Name:        tc.name,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandFleetMerge(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		name         string
-		target       string
-	}{
-		{commandNoErrorsStatus, "Valid request", "Fleet", "Bomber"},
-		{http.StatusBadRequest, "Empty name", "", "Bomber"},
-		{http.StatusBadRequest, "Invalid name", "Fleet_🚢", "Bomber"},
-		{http.StatusBadRequest, "Empty target", "Fleet", ""},
-		{http.StatusBadRequest, "Invalid target", "Fleet", "Bomber_🚢"},
-		{http.StatusBadRequest, "Equal name and target", "Fleet", "Fleet"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandFleetMerge{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeFleetMerge},
-						Name:        tc.name,
-						Target:      tc.target,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandFleetSend(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		name         string
-		destination  int
-	}{
-		{commandNoErrorsStatus, "Valid request #1", "Fleet", 0},
-		{commandNoErrorsStatus, "Valid request #2", "Fleet", 1},
-		{http.StatusBadRequest, "Invalid destination", "Fleet", -1},
-		{http.StatusBadRequest, "Empty name", "", 1},
-		{http.StatusBadRequest, "Invalid name", "Fleet_🚢", 1},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandFleetSend{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeFleetSend},
-						Name:        tc.name,
-						Destination: tc.destination,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandScienceCreate(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		D, W, S, C   float64
-		name         string
-	}{
-		{commandNoErrorsStatus, "Valid request", 0.25, 0.25, 0.25, 0.25, "Science"},
-		{http.StatusBadRequest, "Empty name", 0.25, 0.25, 0.25, 0.25, ""},
-		{http.StatusBadRequest, "Invalid name", 0.25, 0.25, 0.25, 0.25, "Science🧪"},
-		{http.StatusBadRequest, "Negative drive", -.5, 0.25, 0.25, 0.25, "Science"},
-		{http.StatusBadRequest, "Negative weapons", 0.25, -.5, 0.25, 0.25, "Science"},
-		{http.StatusBadRequest, "Negative shields", 0.25, 0.25, -.5, 0.25, "Science"},
-		{http.StatusBadRequest, "Negative cargo", 0.25, 0.25, 0.25, -.5, "Science"},
-		{http.StatusBadRequest, "Too big drive", 1.1, 0.25, 0.25, 0.25, "Science"},
-		{http.StatusBadRequest, "Too big weapons", 0.25, 1.05, 0.25, 0.25, "Science"},
-		{http.StatusBadRequest, "Too big shields", 0.25, 0.25, 1.5, 0.25, "Science"},
-		{http.StatusBadRequest, "Too big cargo", 0.25, 0.25, 0.25, 1.01, "Science"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandScienceCreate{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeScienceCreate},
-						Name:        tc.name,
-						Drive:       tc.D,
-						Weapons:     tc.W,
-						Shields:     tc.S,
-						Cargo:       tc.C,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandScienceRemove(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		name         string
-	}{
-		{commandNoErrorsStatus, "Valid request", "Drone"},
-		{http.StatusBadRequest, "Empty name", ""},
-		{http.StatusBadRequest, "Blank name", "   "},
-		{http.StatusBadRequest, "Invalid name", "Science🧪"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandScienceRemove{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeScienceRemove},
-						Name:        tc.name,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandPlanetRename(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		number       int
-		name         string
-	}{
-		{commandNoErrorsStatus, "Valid request #1", 0, "HW"},
-		{commandNoErrorsStatus, "Valid request #2", 1, "HW"},
-		{http.StatusBadRequest, "Invalid number", -1, "HW"},
-		{http.StatusBadRequest, "Empty name", 1, ""},
-		{http.StatusBadRequest, "Blank name", 1, "   "},
-		{http.StatusBadRequest, "Invalid name", 1, "Planet🪐"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandPlanetRename{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypePlanetRename},
-						Number:      tc.number,
-						Name:        tc.name,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandPlanetProduce(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus        int
-		description         string
-		number              int
-		production, subject string
-	}{
-		{commandNoErrorsStatus, "Valid request MAT", 0, "MAT", ""},
-		{commandNoErrorsStatus, "Valid request CAP", 1, "CAP", ""},
-		{commandNoErrorsStatus, "Valid request DRIVE", 2, "DRIVE", ""},
-		{commandNoErrorsStatus, "Valid request WEAPONS", 3, "WEAPONS", ""},
-		{commandNoErrorsStatus, "Valid request SHIELDS", 4, "SHIELDS", ""},
-		{commandNoErrorsStatus, "Valid request CARGO", 5, "CARGO", ""},
-		{commandNoErrorsStatus, "Valid request SCIENCE", 6, "SCIENCE", "Science"},
-		{commandNoErrorsStatus, "Valid request SHIP", 7, "SHIP", "Ship"},
-		{http.StatusBadRequest, "Empty production", 0, "", ""},
-		{http.StatusBadRequest, "Invalid production", 0, "IND", ""},
-		{http.StatusBadRequest, "Invalid planet", -1, "DRIVE", ""},
-		{http.StatusBadRequest, "Empty science subject", 6, "SCIENCE", ""},
-		{http.StatusBadRequest, "Invalid science subject", 6, "SCIENCE", "Science🧪"},
-		{http.StatusBadRequest, "Empty ship subject", 6, "SHIP", ""},
-		{http.StatusBadRequest, "Invalid ship subject", 6, "SHIP", "Ship🚀"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandPlanetProduce{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypePlanetProduce},
-						Number:      tc.number,
-						Production:  tc.production,
-						Subject:     tc.subject,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandPlanetRouteSet(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus        int
-		description         string
-		origin, destination int
-		loadType            string
-	}{
-		{commandNoErrorsStatus, "Valid request MAT", 1, 0, "MAT"},
-		{commandNoErrorsStatus, "Valid request CAP", 0, 1, "CAP"},
-		{commandNoErrorsStatus, "Valid request COL", 1, 2, "COL"},
-		{commandNoErrorsStatus, "Valid request EMP", 3, 0, "EMP"},
-		{http.StatusBadRequest, "Empty loadType", 0, 1, ""},
-		{http.StatusBadRequest, "Invalid loadType", 0, 1, "IND"},
-		{http.StatusBadRequest, "Invalid origin", -1, 1, "MAT"},
-		{http.StatusBadRequest, "Invalid destination", 1, -1, "MAT"},
-		{http.StatusBadRequest, "Origin equals destination", 1, 1, "COL"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandPlanetRouteSet{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypePlanetRouteSet},
-						Origin:      tc.origin,
-						Destination: tc.destination,
-						LoadType:    tc.loadType,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestCommandPlanetRouteRemove(t *testing.T) {
-	r := setupRouter()
-
-	for _, tc := range []struct {
-		expectStatus int
-		description  string
-		origin       int
-		loadType     string
-	}{
-		{commandNoErrorsStatus, "Valid request MAT", 0, "MAT"},
-		{commandNoErrorsStatus, "Valid request CAP", 1, "CAP"},
-		{commandNoErrorsStatus, "Valid request COL", 2, "COL"},
-		{commandNoErrorsStatus, "Valid request EMP", 0, "EMP"},
-		{http.StatusBadRequest, "Empty loadType", 1, ""},
-		{http.StatusBadRequest, "Invalid loadType", 1, "IND"},
-		{http.StatusBadRequest, "Invalid origin", -1, "MAT"},
-	} {
-		t.Run(tc.description, func(t *testing.T) {
-			payload := &rest.Command{
-				Actor: commandDefaultActor,
-				Commands: []json.RawMessage{
-					encodeCommand(&order.CommandPlanetRouteRemove{
-						CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypePlanetRouteRemove},
-						Origin:      tc.origin,
-						LoadType:    tc.loadType,
-					}),
-				},
-			}
-
-			w := httptest.NewRecorder()
-			req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-			r.ServeHTTP(w, req)
-
-			assert.Equal(t, tc.expectStatus, w.Code, w.Body)
-		})
-	}
-}
-
-func TestMultipleCommands(t *testing.T) {
-	e := newExecutor()
-	r := setupRouterExecutor(e)
-
-	payload := &rest.Command{
-		Actor: commandDefaultActor,
-		Commands: []json.RawMessage{
-			encodeCommand(&order.CommandRaceRelation{
-				CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeRaceRelation},
-				Acceptor:    "Opponent",
-				Relation:    "PEACE",
-			}),
-			encodeCommand(&order.CommandRaceVote{
-				CommandMeta: order.CommandMeta{CmdID: id(), CmdType: order.CommandTypeRaceVote},
-				Acceptor:    "Opponent",
-			}),
-		},
-	}
-
-	w := httptest.NewRecorder()
-	req, _ := http.NewRequest(apiCommandMethod, apiCommandPath, asBody(payload))
-	r.ServeHTTP(w, req)
-
-	assert.Equal(t, commandNoErrorsStatus, w.Code, w.Body)
-
-	assert.Equal(t, 2, e.(*dummyExecutor).CommandsExecuted)
-}

game/internal/router/handler/banish.go

@@ -8,13 +8,13 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-func BanishHandler(c *gin.Context, executor CommandExecutor) {
+func BanishHandler(c *gin.Context, engine Engine) {
 	var req rest.BanishRequest
 	if errorResponse(c, c.ShouldBindJSON(&req)) {
 		return
 	}
 
-	if errorResponse(c, executor.BanishRace(req.RaceName)) {
+	if errorResponse(c, engine.BanishRace(req.RaceName)) {
 		return
 	}
 

game/internal/router/handler/battle.go

@@ -8,7 +8,7 @@ import (
 	"github.com/google/uuid"
 )
 
-func BattleHandler(c *gin.Context, executor CommandExecutor) {
+func BattleHandler(c *gin.Context, engine Engine) {
 	turn := c.Param("turn")
 	t, err := strconv.Atoi(turn)
 	if err != nil {
@@ -25,7 +25,7 @@ func BattleHandler(c *gin.Context, executor CommandExecutor) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
-	r, exists, err := executor.FetchBattle(uint(t), battleID)
+	r, exists, err := engine.FetchBattle(uint(t), battleID)
 	if errorResponse(c, err) {
 		return
 	}

game/internal/router/handler/command.go

@@ -1,347 +0,0 @@
-package handler
-
-import (
-	"encoding/json"
-	"fmt"
-	"net/http"
-
-	"galaxy/game/internal/controller"
-
-	"github.com/go-playground/validator/v10"
-	"github.com/google/uuid"
-
-	"galaxy/model/order"
-	"galaxy/model/rest"
-
-	"github.com/gin-gonic/gin"
-	"github.com/gin-gonic/gin/binding"
-)
-
-func CommandHandler(c *gin.Context, executor CommandExecutor) {
-	var cmd rest.Command
-	if errorResponse(c, c.ShouldBindJSON(&cmd)) {
-		return
-	}
-
-	commands := make([]Command, len(cmd.Commands))
-	for i := range cmd.Commands {
-		command, err := parseCommand(cmd.Actor, cmd.Commands[i])
-		if errorResponse(c, err) {
-			return
-		}
-		commands[i] = command
-	}
-	if len(commands) == 0 {
-		// `PUT /api/v1/command` is the immediate-execution path —
-		// running an empty batch is a meaningless no-op, so we
-		// reject it with `400` rather than rely on the validator.
-		// `PUT /api/v1/order` keeps an empty list (the player
-		// cleared their draft) — see `OrderHandler`.
-		c.JSON(http.StatusBadRequest, gin.H{"error": "no commands given"})
-		return
-	}
-
-	if errorResponse(c, executor.Execute(commands...)) {
-		return
-	}
-
-	c.Status(http.StatusAccepted)
-}
-
-func parseCommand(actor string, c json.RawMessage) (Command, error) {
-	meta := new(order.CommandMeta)
-	if err := json.Unmarshal(c, meta); err != nil {
-		return nil, err
-	}
-	switch t := meta.CmdType; t {
-	case order.CommandTypeRaceQuit:
-		return commandRaceQuit(actor)
-	case order.CommandTypeRaceVote:
-		return commandRaceVote(actor, c)
-	case order.CommandTypeRaceRelation:
-		return commandRaceRelation(actor, c)
-	case order.CommandTypeShipClassCreate:
-		return commandShipClassCreate(actor, c)
-	case order.CommandTypeShipClassMerge:
-		return commandShipClassMerge(actor, c)
-	case order.CommandTypeShipClassRemove:
-		return commandShipClassRemove(actor, c)
-	case order.CommandTypeShipGroupBreak:
-		return commandShipGroupBreak(actor, c)
-	case order.CommandTypeShipGroupLoad:
-		return commandShipGroupLoad(actor, c)
-	case order.CommandTypeShipGroupUnload:
-		return commandShipGroupUnload(actor, c)
-	case order.CommandTypeShipGroupSend:
-		return commandShipGroupSend(actor, c)
-	case order.CommandTypeShipGroupUpgrade:
-		return commandShipGroupUpgrade(actor, c)
-	case order.CommandTypeShipGroupMerge:
-		return commandShipGroupMerge(actor, c)
-	case order.CommandTypeShipGroupDismantle:
-		return commandShipGroupDismantle(actor, c)
-	case order.CommandTypeShipGroupTransfer:
-		return commandShipGroupTransfer(actor, c)
-	case order.CommandTypeShipGroupJoinFleet:
-		return commandShipGroupJoinFleet(actor, c)
-	case order.CommandTypeFleetMerge:
-		return commandFleetMerge(actor, c)
-	case order.CommandTypeFleetSend:
-		return commandFleetSend(actor, c)
-	case order.CommandTypeScienceCreate:
-		return commandScienceCreate(actor, c)
-	case order.CommandTypeScienceRemove:
-		return commandScienceRemove(actor, c)
-	case order.CommandTypePlanetRename:
-		return commandPlanetRename(actor, c)
-	case order.CommandTypePlanetProduce:
-		return commandPlanetProduce(actor, c)
-	case order.CommandTypePlanetRouteSet:
-		return commandPlanetRouteSet(actor, c)
-	case order.CommandTypePlanetRouteRemove:
-		return commandPlanetRouteRemove(actor, c)
-	default:
-		return nil, fmt.Errorf("unknown comman type: %s", t)
-	}
-}
-
-func commandRaceQuit(actor string) (Command, error) {
-	return func(c controller.Ctrl) error { return c.RaceQuit(actor) }, nil
-}
-
-func commandRaceVote(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandRaceVote)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.RaceVote(actor, v.Acceptor)
-		}, nil
-	}
-}
-
-func commandRaceRelation(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandRaceRelation)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.RaceRelation(actor, v.Acceptor, v.Relation)
-		}, nil
-	}
-}
-
-func commandShipClassCreate(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandShipClassCreate)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.ShipClassCreate(actor, v.Name, v.Drive, int(v.Armament), v.Weapons, v.Shields, v.Cargo)
-		}, nil
-	}
-}
-
-func commandShipClassMerge(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandShipClassMerge)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.ShipClassMerge(actor, v.Name, v.Target)
-		}, nil
-	}
-}
-
-func commandShipClassRemove(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandShipClassRemove)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.ShipClassRemove(actor, v.Name)
-		}, nil
-	}
-}
-
-func commandShipGroupBreak(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandShipGroupBreak)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.ShipGroupBreak(actor, uuid.MustParse(v.ID), uuid.MustParse(v.NewID), uint(v.Quantity))
-		}, nil
-	}
-}
-
-func commandShipGroupLoad(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandShipGroupLoad)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.ShipGroupLoad(actor, uuid.MustParse(v.ID), v.Cargo, v.Quantity)
-		}, nil
-	}
-}
-
-func commandShipGroupUnload(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandShipGroupUnload)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.ShipGroupUnload(actor, uuid.MustParse(v.ID), v.Quantity)
-		}, nil
-	}
-}
-
-func commandShipGroupSend(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandShipGroupSend)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.ShipGroupSend(actor, uuid.MustParse(v.ID), uint(v.Destination))
-		}, nil
-	}
-}
-
-func commandShipGroupUpgrade(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandShipGroupUpgrade)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.ShipGroupUpgrade(actor, uuid.MustParse(v.ID), v.Tech, v.Level)
-		}, nil
-	}
-}
-
-func commandShipGroupMerge(actor string, c json.RawMessage) (Command, error) {
-	return func(c controller.Ctrl) error {
-		return c.ShipGroupMerge(actor)
-	}, nil
-}
-
-func commandShipGroupDismantle(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandShipGroupDismantle)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.ShipGroupDismantle(actor, uuid.MustParse(v.ID))
-		}, nil
-	}
-}
-
-func commandShipGroupTransfer(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandShipGroupTransfer)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.ShipGroupTransfer(actor, v.Acceptor, uuid.MustParse(v.ID))
-		}, nil
-	}
-}
-
-func commandShipGroupJoinFleet(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandShipGroupJoinFleet)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.ShipGroupJoinFleet(actor, v.Name, uuid.MustParse(v.ID))
-		}, nil
-	}
-}
-
-func commandFleetMerge(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandFleetMerge)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.FleetMerge(actor, v.Name, v.Target)
-		}, nil
-	}
-}
-
-func commandFleetSend(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandFleetSend)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.FleetSend(actor, v.Name, uint(v.Destination))
-		}, nil
-	}
-}
-
-func commandScienceCreate(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandScienceCreate)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.ScienceCreate(actor, v.Name, v.Drive, v.Weapons, v.Shields, v.Cargo)
-		}, nil
-	}
-}
-
-func commandScienceRemove(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandScienceRemove)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.ScienceRemove(actor, v.Name)
-		}, nil
-	}
-}
-
-func commandPlanetRename(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandPlanetRename)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.PlanetRename(actor, v.Number, v.Name)
-		}, nil
-	}
-}
-
-func commandPlanetProduce(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandPlanetProduce)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.PlanetProduce(actor, v.Number, v.Production, v.Subject)
-		}, nil
-	}
-}
-
-func commandPlanetRouteSet(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandPlanetRouteSet)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.PlanetRouteSet(actor, v.LoadType, uint(v.Origin), uint(v.Destination))
-		}, nil
-	}
-}
-
-func commandPlanetRouteRemove(actor string, c json.RawMessage) (Command, error) {
-	if v, err := unmarshallCommand(c, new(order.CommandPlanetRouteRemove)); err != nil {
-		return nil, err
-	} else {
-		return func(c controller.Ctrl) error {
-			return c.PlanetRouteRemove(actor, v.LoadType, uint(v.Origin))
-		}, nil
-	}
-}
-
-// Helpers
-
-func unmarshallCommand[T order.DecodableCommand](c json.RawMessage, v T) (T, error) {
-	if err := json.Unmarshal(c, v); err != nil {
-		return v, err
-	}
-	if err := validateCommand(v); err != nil {
-		return v, err
-	}
-	return v, nil
-}
-
-func validateCommand(v order.DecodableCommand) error {
-	if ve, ok := binding.Validator.Engine().(*validator.Validate); ok {
-		if err := ve.Struct(v); err != nil {
-			return err
-		}
-	}
-	return nil
-}

game/internal/router/handler/handler.go

@@ -12,7 +12,6 @@ import (
 
 	e "galaxy/error"
 
-	"galaxy/game/internal/controller"
 	"galaxy/game/internal/model/game"
 
 	"github.com/gin-gonic/gin"
@@ -20,25 +19,22 @@ import (
 	"github.com/google/uuid"
 )
 
-type CommandExecutor interface {
-	GenerateGame(gameID uuid.UUID, races []string) (rest.StateResponse, error)
-	GenerateTurn() (rest.StateResponse, error)
-	GameState() (rest.StateResponse, error)
-	BanishRace(string) error
+// Engine is the set of operations the HTTP handlers invoke on the game engine.
+// Its sole production implementation is *controller.Service; the interface
+// exists so the transport layer can be exercised against a lightweight fake
+// without standing up real storage. Methods return domain types — handlers own
+// the projection into the REST wire shapes.
+type Engine interface {
+	GenerateGame(gameID uuid.UUID, races []string) (game.State, error)
+	GenerateTurn() (game.State, error)
+	GameState() (game.State, error)
+	BanishRace(actor string) error
 	LoadReport(actor string, turn uint) (*report.Report, error)
-	// Execute is reserved for future use; any API request for orders should use ValidateOrder
-	Execute(cmd ...Command) error
 	ValidateOrder(actor string, cmd ...order.DecodableCommand) (*order.UserGamesOrder, error)
 	FetchOrder(actor string, turn uint) (*order.UserGamesOrder, bool, error)
 	FetchBattle(turn uint, ID uuid.UUID) (*report.BattleReport, bool, error)
 }
 
-type Command func(controller.Ctrl) error
-
-type executor struct {
-	cfg controller.Configurer
-}
-
 // ResolveStoragePath returns the engine storage path resolved from
 // STORAGE_PATH (preferred, historical name) or GAME_STATE_PATH (canonical
 // name written by Runtime Manager). It returns an error when neither
@@ -53,77 +49,8 @@ func ResolveStoragePath() (string, error) {
 	return "", errors.New("storage path is not set: provide STORAGE_PATH or GAME_STATE_PATH")
 }
 
-func initConfig() controller.Configurer {
-	return func(p *controller.Param) {
-		// Validated once at startup by ResolveStoragePath; the error
-		// is dropped here to keep the Configurer signature simple.
-		p.StoragePath, _ = ResolveStoragePath()
-	}
-}
-
-func NewDefaultExecutor() CommandExecutor {
-	return NewDefaultConfigExecutor(initConfig())
-}
-
-func NewDefaultConfigExecutor(configurer controller.Configurer) CommandExecutor {
-	return &executor{cfg: configurer}
-}
-
-func (e *executor) Execute(cmd ...Command) error {
-	return controller.ExecuteCommand(e.cfg, func(c controller.Ctrl) error {
-		for i := range cmd {
-			if err := cmd[i](c); err != nil {
-				return err
-			}
-		}
-		return nil
-	})
-}
-
-func (e *executor) ValidateOrder(actor string, cmd ...order.DecodableCommand) (*order.UserGamesOrder, error) {
-	return controller.ValidateOrder(e.cfg, actor, cmd...)
-}
-
-func (e *executor) FetchOrder(actor string, turn uint) (*order.UserGamesOrder, bool, error) {
-	return controller.FetchOrder(e.cfg, actor, turn)
-}
-
-func (e *executor) FetchBattle(turn uint, ID uuid.UUID) (*report.BattleReport, bool, error) {
-	return controller.FetchBattle(e.cfg, turn, ID)
-}
-
-func (e *executor) GenerateGame(gameID uuid.UUID, races []string) (rest.StateResponse, error) {
-	s, err := controller.GenerateGame(e.cfg, gameID, races)
-	if err != nil {
-		return rest.StateResponse{}, err
-	}
-	return stateResponse(s), nil
-}
-
-func (e *executor) GenerateTurn() (rest.StateResponse, error) {
-	err := controller.GenerateTurn(e.cfg)
-	if err != nil {
-		return rest.StateResponse{}, err
-	}
-	return e.GameState()
-}
-
-func (e *executor) GameState() (rest.StateResponse, error) {
-	s, err := controller.GameState(e.cfg)
-	if err != nil {
-		return rest.StateResponse{}, err
-	}
-	return stateResponse(s), nil
-}
-
-func (e *executor) BanishRace(raceName string) error {
-	return controller.BanishRace(e.cfg, raceName)
-}
-
-func (e *executor) LoadReport(actor string, turn uint) (*report.Report, error) {
-	return controller.LoadReport(e.cfg, actor, turn)
-}
-
+// stateResponse projects the engine's domain game.State into the REST
+// StateResponse wire shape.
 func stateResponse(s game.State) rest.StateResponse {
 	result := &rest.StateResponse{
 		ID:       s.ID,

game/internal/router/handler/init.go

@@ -11,7 +11,7 @@ import (
 	"github.com/google/uuid"
 )
 
-func InitHandler(c *gin.Context, executor CommandExecutor) {
+func InitHandler(c *gin.Context, engine Engine) {
 	var init rest.InitRequest
 	if errorResponse(c, c.ShouldBindJSON(&init)) {
 		return
@@ -26,7 +26,7 @@ func InitHandler(c *gin.Context, executor CommandExecutor) {
 		races[i] = init.Races[i].RaceName
 	}
 
-	s, err := executor.GenerateGame(init.GameID, races)
+	s, err := engine.GenerateGame(init.GameID, races)
 	if err != nil {
 		if errors.Is(err, controller.ErrGameAlreadyInit) {
 			c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
@@ -37,5 +37,5 @@ func InitHandler(c *gin.Context, executor CommandExecutor) {
 		}
 	}
 
-	c.JSON(http.StatusCreated, s)
+	c.JSON(http.StatusCreated, stateResponse(s))
 }

game/internal/router/handler/order.go

@@ -9,9 +9,11 @@ import (
 	"galaxy/game/internal/repo"
 
 	"github.com/gin-gonic/gin"
+	"github.com/gin-gonic/gin/binding"
+	"github.com/go-playground/validator/v10"
 )
 
-func PutOrderHandler(c *gin.Context, executor CommandExecutor) {
+func PutOrderHandler(c *gin.Context, engine Engine) {
 	var cmd rest.Command
 	if errorResponse(c, c.ShouldBindJSON(&cmd)) {
 		return
@@ -30,7 +32,7 @@ func PutOrderHandler(c *gin.Context, executor CommandExecutor) {
 		commands[i] = command
 	}
 
-	result, err := executor.ValidateOrder(cmd.Actor, commands...)
+	result, err := engine.ValidateOrder(cmd.Actor, commands...)
 	if errorResponse(c, err) {
 		return
 	}
@@ -43,7 +45,7 @@ type orderParam struct {
 	Turn   int    `form:"turn" binding:"gte=0"`
 }
 
-func GetOrderHandler(c *gin.Context, executor CommandExecutor) {
+func GetOrderHandler(c *gin.Context, engine Engine) {
 	p := &orderParam{}
 	// ShouldBindQuery surfaces both validator failures and strconv parse
 	// errors; both are client-side faults, so 400 is the correct mapping.
@@ -52,7 +54,7 @@ func GetOrderHandler(c *gin.Context, executor CommandExecutor) {
 		return
 	}
 
-	o, ok, err := executor.FetchOrder(p.Player, uint(p.Turn))
+	o, ok, err := engine.FetchOrder(p.Player, uint(p.Turn))
 	if errorResponse(c, err) {
 		return
 	}
@@ -64,3 +66,15 @@ func GetOrderHandler(c *gin.Context, executor CommandExecutor) {
 
 	c.JSON(http.StatusOK, o)
 }
+
+// validateCommand runs the gin-registered struct validators against a
+// decoded command. It is the per-command validation hook shared by the
+// order-submission path (PutOrderHandler) and repo.ParseOrder.
+func validateCommand(v order.DecodableCommand) error {
+	if ve, ok := binding.Validator.Engine().(*validator.Validate); ok {
+		if err := ve.Struct(v); err != nil {
+			return err
+		}
+	}
+	return nil
+}

game/internal/router/handler/report.go

@@ -11,14 +11,14 @@ type reportParam struct {
 	Turn   int    `form:"turn" binding:"gte=0"`
 }
 
-func ReportHandler(c *gin.Context, executor CommandExecutor) {
+func ReportHandler(c *gin.Context, engine Engine) {
 	p := &reportParam{}
 	err := c.ShouldBindQuery(p)
 	if errorResponse(c, err) {
 		return
 	}
 
-	r, err := executor.LoadReport(p.Player, uint(p.Turn))
+	r, err := engine.LoadReport(p.Player, uint(p.Turn))
 	if errorResponse(c, err) {
 		return
 	}

game/internal/router/handler/status.go

@@ -6,12 +6,12 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-func StatusHandler(c *gin.Context, executor CommandExecutor) {
-	state, err := executor.GameState()
+func StatusHandler(c *gin.Context, engine Engine) {
+	state, err := engine.GameState()
 
 	if errorResponse(c, err) {
 		return
 	}
 
-	c.JSON(http.StatusOK, state)
+	c.JSON(http.StatusOK, stateResponse(state))
 }

game/internal/router/handler/turn.go

@@ -6,12 +6,12 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-func TurnHandler(c *gin.Context, executor CommandExecutor) {
-	state, err := executor.GenerateTurn()
+func TurnHandler(c *gin.Context, engine Engine) {
+	state, err := engine.GenerateTurn()
 
 	if errorResponse(c, err) {
 		return
 	}
 
-	c.JSON(http.StatusOK, state)
+	c.JSON(http.StatusOK, stateResponse(state))
 }

game/internal/router/healthz_test.go

@@ -6,7 +6,8 @@ import (
 	"net/http/httptest"
 	"testing"
 
-	"galaxy/game/internal/controller"
+	"galaxy/util"
+
 	"galaxy/game/internal/router"
 	"galaxy/game/internal/router/handler"
 
@@ -15,9 +16,10 @@ import (
 )
 
 func TestHealthzReturnsOKWithoutInit(t *testing.T) {
-	r := router.SetupRouter(handler.NewDefaultConfigExecutor(func(p *controller.Param) {
-		p.StoragePath = ""
-	}))
+	root, cleanup := util.CreateWorkDir(t)
+	defer cleanup()
+
+	r := router.SetupRouter(newService(t, root))
 
 	w := httptest.NewRecorder()
 	req, _ := http.NewRequest(http.MethodGet, "/healthz", nil)

game/internal/router/init_test.go

@@ -10,9 +10,7 @@ import (
 
 	"galaxy/util"
 
-	"galaxy/game/internal/controller"
 	"galaxy/game/internal/router"
-	"galaxy/game/internal/router/handler"
 
 	"github.com/google/uuid"
 	"github.com/stretchr/testify/assert"
@@ -22,7 +20,7 @@ func TestInit(t *testing.T) {
 	root, cleanup := util.CreateWorkDir(t)
 	defer cleanup()
 
-	r := router.SetupRouter(handler.NewDefaultConfigExecutor(func(p *controller.Param) { p.StoragePath = root }))
+	r := router.SetupRouter(newService(t, root))
 
 	payload := generateInitRequest(10)
 
@@ -51,7 +49,7 @@ func TestInitRejectsNilUUID(t *testing.T) {
 	root, cleanup := util.CreateWorkDir(t)
 	defer cleanup()
 
-	r := router.SetupRouter(handler.NewDefaultConfigExecutor(func(p *controller.Param) { p.StoragePath = root }))
+	r := router.SetupRouter(newService(t, root))
 
 	payload := generateInitRequest(10)
 	payload.GameID = uuid.Nil
@@ -67,7 +65,7 @@ func TestInitRejectsExistingGameWithDifferentID(t *testing.T) {
 	root, cleanup := util.CreateWorkDir(t)
 	defer cleanup()
 
-	r := router.SetupRouter(handler.NewDefaultConfigExecutor(func(p *controller.Param) { p.StoragePath = root }))
+	r := router.SetupRouter(newService(t, root))
 
 	first := generateInitRequest(10)
 	w := httptest.NewRecorder()

game/internal/router/middleware.go

@@ -2,27 +2,31 @@ package router
 
 import (
 	"net/http"
-	"time"
 
 	"github.com/gin-gonic/gin"
 )
 
-// LimitMiddleware limits number of concurrent connections using a buffered channel with limit spaces
+// LimitMiddleware caps the number of requests executing the routes it guards
+// at limit. A request blocks until a slot frees up; if the request context is
+// cancelled or expires while waiting, it answers 503 Service Unavailable.
+//
+// The semaphore is owned by the returned handler, so sharing a single instance
+// across several routes serialises those routes against each other. The engine
+// relies on this to serialise every operation that mutates the canonical game
+// state file, which must never run concurrently against one storage directory.
 func LimitMiddleware(limit int) gin.HandlerFunc {
 	if limit <= 0 {
 		panic("limit must be greater than 0")
 	}
-	semaphore := make(chan bool, limit)
-	t := time.NewTimer(time.Millisecond * 100)
+	semaphore := make(chan struct{}, limit)
 
 	return func(c *gin.Context) {
-		t.Reset(time.Millisecond * 100)
 		select {
-		case semaphore <- true:
+		case semaphore <- struct{}{}:
+			defer func() { <-semaphore }()
 			c.Next()
-			<-semaphore
-		case <-t.C:
-			c.Status(http.StatusGatewayTimeout)
+		case <-c.Request.Context().Done():
+			c.AbortWithStatus(http.StatusServiceUnavailable)
 		}
 	}
 }

game/internal/router/report_test.go

@@ -8,9 +8,7 @@ import (
 
 	"galaxy/model/rest"
 
-	"galaxy/game/internal/controller"
 	"galaxy/game/internal/router"
-	"galaxy/game/internal/router/handler"
 
 	"github.com/google/uuid"
 	"github.com/stretchr/testify/assert"
@@ -19,7 +17,7 @@ import (
 func TestGetReport(t *testing.T) {
 	root := t.ArtifactDir()
 
-	r := router.SetupRouter(handler.NewDefaultConfigExecutor(func(p *controller.Param) { p.StoragePath = root }))
+	r := router.SetupRouter(newService(t, root))
 
 	payload := generateInitRequest(10)
 

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
 }

game/internal/router/router_export_test.go

@@ -6,7 +6,7 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-func SetupRouter(e handler.CommandExecutor) *gin.Engine {
+func SetupRouter(e handler.Engine) *gin.Engine {
 	gin.SetMode(gin.TestMode)
 	return setupRouter(e)
 }

game/internal/router/router_helper_test.go

@@ -3,11 +3,13 @@ package router_test
 import (
 	"encoding/json"
 	"net/http"
+	"testing"
 
 	"galaxy/model/order"
 	"galaxy/model/report"
-	"galaxy/model/rest"
 
+	"galaxy/game/internal/controller"
+	"galaxy/game/internal/model/game"
 	"galaxy/game/internal/router"
 	"galaxy/game/internal/router/handler"
 
@@ -19,7 +21,6 @@ var (
 	commandNoErrorsStatus = http.StatusAccepted
 	commandDefaultActor   = "Gorlum"
 	apiCommandMethod      = "PUT"
-	apiCommandPath        = "/api/v1/command"
 	apiOrderPath          = "/api/v1/order"
 	validId1              = id()
 	validId2              = id()
@@ -81,25 +82,20 @@ func (e *dummyExecutor) FetchBattle(turn uint, ID uuid.UUID) (*report.BattleRepo
 	return e.FetchBattleResult, e.FetchBattleOK, e.FetchBattleErr
 }
 
-func (e *dummyExecutor) Execute(command ...handler.Command) error {
-	e.CommandsExecuted = len(command)
-	return nil
+func (e *dummyExecutor) GenerateGame(gameID uuid.UUID, races []string) (game.State, error) {
+	return game.State{ID: gameID}, nil
 }
 
-func (e *dummyExecutor) GenerateGame(gameID uuid.UUID, races []string) (rest.StateResponse, error) {
-	return rest.StateResponse{ID: gameID}, nil
-}
-
-func (e *dummyExecutor) GenerateTurn() (rest.StateResponse, error) {
-	return rest.StateResponse{}, nil
+func (e *dummyExecutor) GenerateTurn() (game.State, error) {
+	return game.State{}, nil
 }
 
 func (e *dummyExecutor) BanishRace(raceName string) error {
 	return nil
 }
 
-func (e *dummyExecutor) GameState() (rest.StateResponse, error) {
-	return rest.StateResponse{}, nil
+func (e *dummyExecutor) GameState() (game.State, error) {
+	return game.State{}, nil
 }
 
 func (e *dummyExecutor) LoadReport(actor string, turn uint) (*report.Report, error) {
@@ -110,14 +106,25 @@ func setupRouter() *gin.Engine {
 	return setupRouterExecutor(newExecutor())
 }
 
-func setupRouterExecutor(e handler.CommandExecutor) *gin.Engine {
+func setupRouterExecutor(e handler.Engine) *gin.Engine {
 	return router.SetupRouter(e)
 }
 
-func newExecutor() handler.CommandExecutor {
+func newExecutor() handler.Engine {
 	return &dummyExecutor{}
 }
 
+// newService builds a real controller.Service backed by a storage directory,
+// for handler tests that exercise the engine end to end rather than the fake.
+func newService(t *testing.T, root string) *controller.Service {
+	t.Helper()
+	svc, err := controller.NewService(root)
+	if err != nil {
+		t.Fatalf("new service: %v", err)
+	}
+	return svc
+}
+
 func encodeCommand(cmd any) json.RawMessage {
 	v, err := json.Marshal(cmd)
 	if err != nil {

game/internal/router/router_test.go

@@ -1,6 +1,7 @@
 package router_test
 
 import (
+	"context"
 	"encoding/json"
 	"fmt"
 	"net/http"
@@ -9,6 +10,7 @@ import (
 	"sync"
 	"sync/atomic"
 	"testing"
+	"time"
 
 	"galaxy/model/rest"
 
@@ -38,6 +40,92 @@ func TestLimitConnections(t *testing.T) {
 	wg.Wait()
 }
 
+// TestLimitSharedInstanceSerialisesRoutes pins the property the engine relies
+// on to serialise state mutations: a single LimitMiddleware(1) instance shared
+// across several routes admits at most one request across all of them at a
+// time. The handler tracks the high-water concurrency and asserts it never
+// exceeds one.
+func TestLimitSharedInstanceSerialisesRoutes(t *testing.T) {
+	gin.SetMode(gin.ReleaseMode)
+	r := gin.New()
+	r.Use(gin.Recovery())
+
+	shared := router.LimitMiddleware(1)
+
+	var inFlight, maxSeen atomic.Int32
+	handler := func(c *gin.Context) {
+		n := inFlight.Add(1)
+		for {
+			cur := maxSeen.Load()
+			if n <= cur || maxSeen.CompareAndSwap(cur, n) {
+				break
+			}
+		}
+		time.Sleep(time.Millisecond) // widen the overlap window
+		inFlight.Add(-1)
+		c.Status(http.StatusOK)
+	}
+	r.GET("/a", shared, handler)
+	r.PUT("/b", shared, handler)
+
+	wg := sync.WaitGroup{}
+	for i := range 200 {
+		method, path := http.MethodGet, "/a"
+		if i%2 == 1 {
+			method, path = http.MethodPut, "/b"
+		}
+		wg.Go(func() {
+			w := httptest.NewRecorder()
+			req, _ := http.NewRequest(method, path, nil)
+			r.ServeHTTP(w, req)
+			assert.Equal(t, http.StatusOK, w.Code, w.Body)
+		})
+	}
+	wg.Wait()
+	assert.Equal(t, int32(1), maxSeen.Load(), "a shared limiter must serialise across every route it guards")
+}
+
+// TestLimitReleasesOnContextCancel verifies the wait path: while one request
+// holds the only slot, a second request blocked on the limiter answers 503
+// once its request context is cancelled, instead of hanging.
+func TestLimitReleasesOnContextCancel(t *testing.T) {
+	gin.SetMode(gin.ReleaseMode)
+	r := gin.New()
+	r.Use(gin.Recovery())
+
+	shared := router.LimitMiddleware(1)
+	entered := make(chan struct{})
+	release := make(chan struct{})
+	r.GET("/hold", shared, func(c *gin.Context) {
+		close(entered)
+		<-release
+		c.Status(http.StatusOK)
+	})
+
+	// First request grabs and holds the only slot.
+	go func() {
+		w := httptest.NewRecorder()
+		req, _ := http.NewRequest(http.MethodGet, "/hold", nil)
+		r.ServeHTTP(w, req)
+	}()
+	<-entered
+
+	// Second request blocks on the limiter, then loses its context.
+	ctx, cancel := context.WithCancel(context.Background())
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, "/hold", nil)
+	done := make(chan struct{})
+	go func() {
+		r.ServeHTTP(w, req)
+		close(done)
+	}()
+	cancel()
+	<-done
+
+	assert.Equal(t, http.StatusServiceUnavailable, w.Code)
+	close(release)
+}
+
 func asBody(body any) *strings.Reader {
 	commandJson, _ := json.Marshal(body)
 	return strings.NewReader(string(commandJson))

game/internal/router/status_test.go

@@ -10,9 +10,7 @@ import (
 
 	"galaxy/util"
 
-	"galaxy/game/internal/controller"
 	"galaxy/game/internal/router"
-	"galaxy/game/internal/router/handler"
 
 	"github.com/google/uuid"
 	"github.com/stretchr/testify/assert"
@@ -22,7 +20,7 @@ func TestGetStatus(t *testing.T) {
 	root, cleanup := util.CreateWorkDir(t)
 	defer cleanup()
 
-	r := router.SetupRouter(handler.NewDefaultConfigExecutor(func(p *controller.Param) { p.StoragePath = root }))
+	r := router.SetupRouter(newService(t, root))
 
 	payload := generateInitRequest(10)
 

game/internal/router/turn_test.go

@@ -10,9 +10,7 @@ import (
 
 	"galaxy/util"
 
-	"galaxy/game/internal/controller"
 	"galaxy/game/internal/router"
-	"galaxy/game/internal/router/handler"
 
 	"github.com/google/uuid"
 	"github.com/stretchr/testify/assert"
@@ -22,7 +20,7 @@ func TestGetTurn(t *testing.T) {
 	root, cleanup := util.CreateWorkDir(t)
 	defer cleanup()
 
-	r := router.SetupRouter(handler.NewDefaultConfigExecutor(func(p *controller.Param) { p.StoragePath = root }))
+	r := router.SetupRouter(newService(t, root))
 
 	// create game