feat: gamemaster

gamemaster/internal/service/turngeneration/errors.go

@@ -0,0 +1,56 @@
+package turngeneration
+
+// 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`. Stages 17 and 19 import these
+// names rather than redeclare them; renaming any of them is a contract
+// change.
+const (
+	// ErrorCodeInvalidRequest reports that the input envelope failed
+	// structural validation (empty game id, unsupported trigger,
+	// unsupported op_source) or that the runtime record's stored
+	// `turn_schedule` could not be parsed at recompute time.
+	ErrorCodeInvalidRequest = "invalid_request"
+
+	// ErrorCodeRuntimeNotFound reports that no `runtime_records` row
+	// exists for the requested game id. The orchestrator does no other
+	// work and never publishes events.
+	ErrorCodeRuntimeNotFound = "runtime_not_found"
+
+	// ErrorCodeRuntimeNotRunning reports that the runtime exists but
+	// its current status is not `running`. The orchestrator returns
+	// without calling the engine.
+	ErrorCodeRuntimeNotRunning = "runtime_not_running"
+
+	// ErrorCodeConflict reports that a CAS guard failed mid-flow
+	// because the runtime row changed concurrently (typical cause:
+	// admin issued a stop while a generation was in progress).
+	ErrorCodeConflict = "conflict"
+
+	// ErrorCodeEngineUnreachable reports that the engine /admin/turn
+	// call returned a 5xx status, timed out, or could not be
+	// dispatched. The runtime row is moved to `generation_failed` and a
+	// snapshot plus admin notification are published before the code
+	// reaches the caller.
+	ErrorCodeEngineUnreachable = "engine_unreachable"
+
+	// ErrorCodeEngineValidationError reports that the engine
+	// /admin/turn call returned a 4xx status. Distinguished from
+	// `engine_unreachable` so operators can tell "engine is alive but
+	// rejected the request shape" from "engine is unreachable".
+	ErrorCodeEngineValidationError = "engine_validation_error"
+
+	// ErrorCodeEngineProtocolViolation reports that the engine response
+	// did not match the expected schema or did not match the runtime's
+	// installed roster (player count mismatch, race-name set mismatch,
+	// missing required fields).
+	ErrorCodeEngineProtocolViolation = "engine_protocol_violation"
+
+	// ErrorCodeServiceUnavailable reports that a steady-state
+	// dependency (PostgreSQL, Redis) was unreachable for this call.
+	ErrorCodeServiceUnavailable = "service_unavailable"
+
+	// ErrorCodeInternal reports an unexpected error not classified by
+	// the other codes.
+	ErrorCodeInternal = "internal_error"
+)