feat: gamemaster

gamemaster/internal/service/commandexecute/errors.go

@@ -0,0 +1,51 @@
+package commandexecute
+
+// Stable error codes returned in `Result.ErrorCode`. The values match the
+// vocabulary frozen by `gamemaster/README.md §Error Model` and
+// `gamemaster/api/internal-openapi.yaml`. Stage 19's REST handler imports
+// these names rather than redeclare them; renaming any of them is a
+// contract change.
+const (
+	// ErrorCodeInvalidRequest reports that the request envelope failed
+	// structural validation (empty required field, malformed payload,
+	// non-object payload, payload missing the `commands` array).
+	ErrorCodeInvalidRequest = "invalid_request"
+
+	// ErrorCodeRuntimeNotFound reports that no `runtime_records` row
+	// exists for the requested game id.
+	ErrorCodeRuntimeNotFound = "runtime_not_found"
+
+	// ErrorCodeRuntimeNotRunning reports that the runtime exists but its
+	// current status is not `running`. Hot-path commands are rejected
+	// outside the running state to avoid racing with admin transitions
+	// and turn generation.
+	ErrorCodeRuntimeNotRunning = "runtime_not_running"
+
+	// ErrorCodeForbidden reports that the caller is not an active member
+	// of the game, or that the (game_id, user_id) pair lacks a player
+	// mapping. Either way the caller is not authorised to act.
+	ErrorCodeForbidden = "forbidden"
+
+	// ErrorCodeEngineUnreachable reports that the engine /api/v1/command
+	// call returned a 5xx status, timed out, or could not be dispatched.
+	ErrorCodeEngineUnreachable = "engine_unreachable"
+
+	// ErrorCodeEngineValidationError reports that the engine returned
+	// 4xx with a per-command result. The body is forwarded verbatim
+	// through `Result.RawResponse` so the gateway can surface the
+	// per-command error vocabulary.
+	ErrorCodeEngineValidationError = "engine_validation_error"
+
+	// ErrorCodeEngineProtocolViolation reports that the engine response
+	// did not match the expected schema (malformed JSON, unexpected
+	// types). Stage 19 maps this to 502.
+	ErrorCodeEngineProtocolViolation = "engine_protocol_violation"
+
+	// ErrorCodeServiceUnavailable reports that a steady-state dependency
+	// (PostgreSQL, Lobby) was unreachable for this call.
+	ErrorCodeServiceUnavailable = "service_unavailable"
+
+	// ErrorCodeInternal reports an unexpected error not classified by
+	// the other codes.
+	ErrorCodeInternal = "internal_error"
+)