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>

pkg/transcoder/order.go

@@ -931,72 +931,6 @@ func cloneStringPointer(value *string) *string {
 	return &cloned
 }
 
-// UserGamesCommandToPayload converts model.UserGamesCommand to
-// FlatBuffers bytes suitable for the authenticated gateway transport.
-// `GameID` is required.
-func UserGamesCommandToPayload(req *model.UserGamesCommand) ([]byte, error) {
-	if req == nil {
-		return nil, errors.New("encode user games command payload: request is nil")
-	}
-
-	builder := flatbuffers.NewBuilder(1024)
-	commandsVec, err := encodeCommandItemVector(builder, req.Commands, "user games command")
-	if err != nil {
-		return nil, err
-	}
-
-	fbs.UserGamesCommandStart(builder)
-	hi, lo := uuidToHiLo(req.GameID)
-	fbs.UserGamesCommandAddGameId(builder, commonfbs.CreateUUID(builder, hi, lo))
-	if commandsVec != 0 {
-		fbs.UserGamesCommandAddCommands(builder, commandsVec)
-	}
-	offset := fbs.UserGamesCommandEnd(builder)
-	fbs.FinishUserGamesCommandBuffer(builder, offset)
-
-	return builder.FinishedBytes(), nil
-}
-
-// PayloadToUserGamesCommand converts FlatBuffers payload bytes into
-// model.UserGamesCommand.
-func PayloadToUserGamesCommand(data []byte) (result *model.UserGamesCommand, err error) {
-	if len(data) == 0 {
-		return nil, errors.New("decode user games command payload: data is empty")
-	}
-
-	defer func() {
-		if recovered := recover(); recovered != nil {
-			result = nil
-			err = fmt.Errorf("decode user games command payload: panic recovered: %v", recovered)
-		}
-	}()
-
-	flat := fbs.GetRootAsUserGamesCommand(data, 0)
-	gameID := flat.GameId(nil)
-	if gameID == nil {
-		return nil, errors.New("decode user games command payload: game_id is missing")
-	}
-	out := &model.UserGamesCommand{
-		GameID: uuidFromHiLo(gameID.Hi(), gameID.Lo()),
-	}
-	count := flat.CommandsLength()
-	if count > 0 {
-		out.Commands = make([]model.DecodableCommand, count)
-		flatCommand := new(fbs.CommandItem)
-		for i := 0; i < count; i++ {
-			if !flat.Commands(flatCommand, i) {
-				return nil, fmt.Errorf("decode user games command %d: command item is missing", i)
-			}
-			cmd, decodeErr := decodeOrderCommand(flatCommand, i)
-			if decodeErr != nil {
-				return nil, decodeErr
-			}
-			out.Commands[i] = cmd
-		}
-	}
-	return out, nil
-}
-
 // UserGamesOrderToPayload converts model.UserGamesOrder to FlatBuffers
 // bytes suitable for the authenticated gateway transport.
 func UserGamesOrderToPayload(req *model.UserGamesOrder) ([]byte, error) {
@@ -1068,19 +1002,6 @@ func PayloadToUserGamesOrder(data []byte) (result *model.UserGamesOrder, err err
 	return out, nil
 }
 
-// EmptyUserGamesCommandResponsePayload returns a FlatBuffers-encoded
-// empty `UserGamesCommandResponse` buffer. Used by gateway to ack a
-// successful `MessageTypeUserGamesCommand` even though the engine
-// returns 204 No Content — the typed envelope keeps the message-type
-// contract symmetric with other authenticated routes.
-func EmptyUserGamesCommandResponsePayload() []byte {
-	builder := flatbuffers.NewBuilder(16)
-	fbs.UserGamesCommandResponseStart(builder)
-	offset := fbs.UserGamesCommandResponseEnd(builder)
-	fbs.FinishUserGamesCommandResponseBuffer(builder, offset)
-	return builder.FinishedBytes()
-}
-
 // UserGamesOrderResponseToPayload encodes the engine's response body
 // for `PUT /api/v1/order` into the wire FlatBuffers envelope expected
 // for `MessageTypeUserGamesOrder`. The engine populates per-command
@@ -1298,9 +1219,8 @@ func PayloadToUserGamesOrderGetResponse(data []byte) (order *model.UserGamesOrde
 }
 
 // encodeCommandItemVector serialises a slice of DecodableCommand into a
-// FlatBuffers vector of CommandItem. Used by UserGamesCommandToPayload
-// and UserGamesOrderToPayload to keep the per-command encoding logic in
-// one place.
+// FlatBuffers vector of CommandItem. Used by UserGamesOrderToPayload to
+// keep the per-command encoding logic in one place.
 func encodeCommandItemVector(builder *flatbuffers.Builder, commands []model.DecodableCommand, opLabel string) (flatbuffers.UOffsetT, error) {
 	offsets := make([]flatbuffers.UOffsetT, len(commands))
 	for i := range commands {
@@ -1331,12 +1251,7 @@ func encodeCommandItemVector(builder *flatbuffers.Builder, commands []model.Deco
 	if len(offsets) == 0 {
 		return 0, nil
 	}
-	// `UserGamesCommandStartCommandsVector` and the corresponding
-	// `UserGamesOrderStartCommandsVector` are identical helpers (both
-	// expand to `builder.StartVector(4, numElems, 4)`); we use the
-	// command flavour for both message types so the helper has a
-	// single dependency point.
-	fbs.UserGamesCommandStartCommandsVector(builder, len(offsets))
+	fbs.UserGamesOrderStartCommandsVector(builder, len(offsets))
 	for i := len(offsets) - 1; i >= 0; i-- {
 		builder.PrependUOffsetT(offsets[i])
 	}

pkg/transcoder/order_test.go

@@ -10,32 +10,6 @@ import (
 	"github.com/google/uuid"
 )
 
-func TestUserGamesCommandPayloadRoundTrip(t *testing.T) {
-	t.Parallel()
-
-	source := &model.UserGamesCommand{
-		GameID: uuid.MustParse("11111111-2222-3333-4444-555555555555"),
-		Commands: []model.DecodableCommand{
-			&model.CommandRaceVote{CommandMeta: commandMeta("cmd-01", model.CommandTypeRaceVote, nil, nil), Acceptor: "race-a"},
-			&model.CommandShipGroupSend{CommandMeta: commandMeta("cmd-02", model.CommandTypeShipGroupSend, nil, nil), ID: "group-1", Destination: 7},
-		},
-	}
-
-	payload, err := UserGamesCommandToPayload(source)
-	if err != nil {
-		t.Fatalf("encode user games command: %v", err)
-	}
-
-	decoded, err := PayloadToUserGamesCommand(payload)
-	if err != nil {
-		t.Fatalf("decode user games command: %v", err)
-	}
-
-	if !reflect.DeepEqual(source, decoded) {
-		t.Fatalf("round-trip mismatch\nsource: %#v\ndecoded:%#v", source, decoded)
-	}
-}
-
 func TestUserGamesOrderPayloadRoundTrip(t *testing.T) {
 	t.Parallel()
 
@@ -62,15 +36,9 @@ func TestUserGamesOrderPayloadRoundTrip(t *testing.T) {
 	}
 }
 
-func TestUserGamesCommandRejectsNilAndEmpty(t *testing.T) {
+func TestUserGamesOrderRejectsNilAndEmpty(t *testing.T) {
 	t.Parallel()
 
-	if _, err := UserGamesCommandToPayload(nil); err == nil {
-		t.Fatalf("expected error encoding nil user games command")
-	}
-	if _, err := PayloadToUserGamesCommand(nil); err == nil {
-		t.Fatalf("expected error decoding empty user games command")
-	}
 	if _, err := UserGamesOrderToPayload(nil); err == nil {
 		t.Fatalf("expected error encoding nil user games order")
 	}