feat: gamemaster

2026-05-03 07:59:03 +02:00
parent a7cee15115
commit 3e2622757e
229 changed files with 41521 additions and 1098 deletions
@@ -0,0 +1,971 @@
+// Package turngeneration implements the turn-generation orchestrator
+// owned by Game Master. It is the single entry point through which the
+// scheduler ticker (Stage 15 worker) and the admin force-next-turn flow
+// (Stage 17) drive a turn through the engine container.
+//
+// Lifecycle and failure-mode semantics follow `gamemaster/README.md
+// §Lifecycles → Turn generation` and §Force-next-turn. Design rationale
+// is captured in
+// `gamemaster/docs/stage15-scheduler-and-turn-generation.md`.
+package turngeneration
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"sort"
+	"strings"
+	"time"
+
+	"galaxy/gamemaster/internal/domain/operation"
+	"galaxy/gamemaster/internal/domain/playermapping"
+	"galaxy/gamemaster/internal/domain/runtime"
+	"galaxy/gamemaster/internal/logging"
+	"galaxy/gamemaster/internal/ports"
+	"galaxy/gamemaster/internal/service/scheduler"
+	"galaxy/gamemaster/internal/telemetry"
+	"galaxy/notificationintent"
+)
+
+// Trigger classifies the caller of one turn-generation operation. The
+// value flows into telemetry and structured logs only — it does not
+// branch the orchestrator's persistence path. The skip-tick mechanic is
+// driven exclusively by the runtime record's `skip_next_tick` column.
+type Trigger string
+
+const (
+	// TriggerScheduler labels turn generations dispatched by the
+	// `schedulerticker` worker.
+	TriggerScheduler Trigger = "scheduler"
+
+	// TriggerForce labels turn generations dispatched by the admin
+	// force-next-turn flow (Stage 17 `service/adminforce`).
+	TriggerForce Trigger = "force"
+)
+
+// IsKnown reports whether trigger belongs to the frozen trigger
+// vocabulary.
+func (trigger Trigger) IsKnown() bool {
+	switch trigger {
+	case TriggerScheduler, TriggerForce:
+		return true
+	default:
+		return false
+	}
+}
+
+// Input stores the per-call arguments for one turn-generation
+// operation.
+type Input struct {
+	// GameID identifies the runtime to drive.
+	GameID string
+
+	// Trigger classifies the caller. Used for telemetry and logs only.
+	Trigger Trigger
+
+	// OpSource classifies how the request entered Game Master. Used to
+	// stamp `operation_log.op_source`. Defaults to `admin_rest` when
+	// missing or unrecognised.
+	OpSource operation.OpSource
+
+	// SourceRef stores the optional opaque per-source reference (REST
+	// request id, scheduler tick id). Empty when the caller does not
+	// provide one.
+	SourceRef string
+}
+
+// Validate reports whether input carries the structural invariants the
+// service requires before any store is touched.
+func (input Input) Validate() error {
+	if strings.TrimSpace(input.GameID) == "" {
+		return fmt.Errorf("game id must not be empty")
+	}
+	if !input.Trigger.IsKnown() {
+		return fmt.Errorf("trigger %q is unsupported", input.Trigger)
+	}
+	if !input.OpSource.IsKnown() {
+		return fmt.Errorf("op source %q is unsupported", input.OpSource)
+	}
+	return nil
+}
+
+// Result stores the deterministic outcome of one Handle call.
+type Result struct {
+	// Record carries the post-mutation runtime record. Populated on
+	// every success outcome and on `engine_*` failures (where the row
+	// was moved to `generation_failed`); zero on early-rejection
+	// outcomes (`invalid_request`, `runtime_not_found`,
+	// `runtime_not_running`, `conflict` on initial CAS,
+	// `service_unavailable` on initial Get).
+	Record runtime.RuntimeRecord
+
+	// Trigger echoes back Input.Trigger for log/telemetry consumers.
+	Trigger Trigger
+
+	// Finished is true when the engine reported `finished=true` on this
+	// turn and the runtime transitioned to `finished`.
+	Finished bool
+
+	// Outcome reports whether the operation completed (success) or
+	// produced a stable failure code.
+	Outcome operation.Outcome
+
+	// ErrorCode stores the stable error code on failure. Empty on
+	// success.
+	ErrorCode string
+
+	// ErrorMessage stores the operator-readable detail on failure.
+	// Empty on success.
+	ErrorMessage string
+}
+
+// IsSuccess reports whether the result represents a successful
+// operation.
+func (result Result) IsSuccess() bool {
+	return result.Outcome == operation.OutcomeSuccess
+}
+
+// Dependencies groups the collaborators required by Service.
+type Dependencies struct {
+	// RuntimeRecords drives every CAS and scheduling persistence step.
+	RuntimeRecords ports.RuntimeRecordStore
+
+	// PlayerMappings supplies the per-game roster used to project
+	// engine player state to user-facing notification recipients and
+	// `player_turn_stats`.
+	PlayerMappings ports.PlayerMappingStore
+
+	// OperationLogs records the audit entry for the operation.
+	OperationLogs ports.OperationLogStore
+
+	// Engine drives the engine /admin/turn call.
+	Engine ports.EngineClient
+
+	// LobbyEvents publishes `runtime_snapshot_update` and
+	// `game_finished` to `gm:lobby_events`.
+	LobbyEvents ports.LobbyEventsPublisher
+
+	// Notifications publishes `game.turn.ready`, `game.finished`, and
+	// `game.generation_failed` intents to `notification:intents`.
+	Notifications ports.NotificationIntentPublisher
+
+	// Lobby resolves the human-readable `game_name` consumed by
+	// notification payloads. Failure is fail-soft: the orchestrator
+	// falls back to `game_id`.
+	Lobby ports.LobbyClient
+
+	// Scheduler computes the post-success `next_generation_at` value.
+	Scheduler *scheduler.Service
+
+	// Telemetry records the turn-generation outcome counter, lobby
+	// publication counter, and notification publish-attempt counter.
+	Telemetry *telemetry.Runtime
+
+	// Logger records structured service-level events. Defaults to
+	// `slog.Default()` when nil.
+	Logger *slog.Logger
+
+	// Clock supplies the wall-clock used for operation timestamps.
+	// Defaults to `time.Now` when nil.
+	Clock func() time.Time
+}
+
+// Service executes the turn-generation lifecycle operation.
+type Service struct {
+	runtimeRecords ports.RuntimeRecordStore
+	playerMappings ports.PlayerMappingStore
+	operationLogs  ports.OperationLogStore
+	engine         ports.EngineClient
+	lobbyEvents    ports.LobbyEventsPublisher
+	notifications  ports.NotificationIntentPublisher
+	lobby          ports.LobbyClient
+	scheduler      *scheduler.Service
+
+	telemetry *telemetry.Runtime
+	logger    *slog.Logger
+	clock     func() time.Time
+}
+
+// NewService constructs one Service from deps.
+func NewService(deps Dependencies) (*Service, error) {
+	switch {
+	case deps.RuntimeRecords == nil:
+		return nil, errors.New("new turn generation service: nil runtime records")
+	case deps.PlayerMappings == nil:
+		return nil, errors.New("new turn generation service: nil player mappings")
+	case deps.OperationLogs == nil:
+		return nil, errors.New("new turn generation service: nil operation logs")
+	case deps.Engine == nil:
+		return nil, errors.New("new turn generation service: nil engine client")
+	case deps.LobbyEvents == nil:
+		return nil, errors.New("new turn generation service: nil lobby events publisher")
+	case deps.Notifications == nil:
+		return nil, errors.New("new turn generation service: nil notification publisher")
+	case deps.Lobby == nil:
+		return nil, errors.New("new turn generation service: nil lobby client")
+	case deps.Scheduler == nil:
+		return nil, errors.New("new turn generation service: nil scheduler")
+	case deps.Telemetry == nil:
+		return nil, errors.New("new turn generation service: nil telemetry runtime")
+	}
+
+	clock := deps.Clock
+	if clock == nil {
+		clock = time.Now
+	}
+	logger := deps.Logger
+	if logger == nil {
+		logger = slog.Default()
+	}
+	logger = logger.With("service", "gamemaster.turngeneration")
+
+	return &Service{
+		runtimeRecords: deps.RuntimeRecords,
+		playerMappings: deps.PlayerMappings,
+		operationLogs:  deps.OperationLogs,
+		engine:         deps.Engine,
+		lobbyEvents:    deps.LobbyEvents,
+		notifications:  deps.Notifications,
+		lobby:          deps.Lobby,
+		scheduler:      deps.Scheduler,
+		telemetry:      deps.Telemetry,
+		logger:         logger,
+		clock:          clock,
+	}, nil
+}
+
+// Handle executes one turn-generation operation end-to-end. The
+// Go-level error return is reserved for non-business failures (nil
+// context, nil receiver). Every business outcome flows through Result.
+func (service *Service) Handle(ctx context.Context, input Input) (Result, error) {
+	if service == nil {
+		return Result{}, errors.New("turn generation: nil service")
+	}
+	if ctx == nil {
+		return Result{}, errors.New("turn generation: nil context")
+	}
+
+	opStartedAt := service.clock().UTC()
+
+	if err := input.Validate(); err != nil {
+		return service.recordEarlyFailure(ctx, opStartedAt, input,
+			ErrorCodeInvalidRequest, err.Error()), nil
+	}
+
+	record, outcome, ok := service.loadRecord(ctx, opStartedAt, input)
+	if !ok {
+		return outcome, nil
+	}
+
+	if record.Status != runtime.StatusRunning {
+		return service.recordEarlyFailure(ctx, opStartedAt, input,
+			ErrorCodeRuntimeNotRunning,
+			fmt.Sprintf("runtime status is %q, expected %q",
+				record.Status, runtime.StatusRunning)), nil
+	}
+
+	if outcome, ok := service.casToInProgress(ctx, opStartedAt, input); !ok {
+		return outcome, nil
+	}
+
+	state, engineOK, engineCode, engineMsg := service.callEngineTurn(ctx, record)
+	mappings, listErr := service.playerMappings.ListByGame(ctx, input.GameID)
+	if listErr != nil {
+		// Without mappings we cannot project player_turn_stats; treat
+		// as a service_unavailable failure but still try to roll the
+		// runtime to generation_failed because the engine call may
+		// have already mutated state.
+		return service.failGeneration(ctx, opStartedAt, input, record,
+			ErrorCodeServiceUnavailable,
+			fmt.Sprintf("list player mappings: %s", listErr.Error())), nil
+	}
+
+	if !engineOK {
+		return service.failGeneration(ctx, opStartedAt, input, record,
+			engineCode, engineMsg), nil
+	}
+
+	if outcome, ok := service.validateRoster(ctx, opStartedAt, input, record, state, mappings); !ok {
+		return outcome, nil
+	}
+
+	if state.Finished {
+		return service.completeFinished(ctx, opStartedAt, input, record, state, mappings), nil
+	}
+	return service.completeRunning(ctx, opStartedAt, input, record, state, mappings), nil
+}
+
+// loadRecord reads the runtime record and maps store errors to
+// orchestrator outcomes. ok=false means the flow stops with the
+// returned Result.
+func (service *Service) loadRecord(ctx context.Context, opStartedAt time.Time, input Input) (runtime.RuntimeRecord, Result, bool) {
+	record, err := service.runtimeRecords.Get(ctx, input.GameID)
+	switch {
+	case err == nil:
+		return record, Result{}, true
+	case errors.Is(err, runtime.ErrNotFound):
+		return runtime.RuntimeRecord{}, service.recordEarlyFailure(ctx, opStartedAt, input,
+			ErrorCodeRuntimeNotFound, "runtime record does not exist"), false
+	default:
+		return runtime.RuntimeRecord{}, service.recordEarlyFailure(ctx, opStartedAt, input,
+			ErrorCodeServiceUnavailable, fmt.Sprintf("get runtime record: %s", err.Error())), false
+	}
+}
+
+// casToInProgress flips the runtime row from `running` to
+// `generation_in_progress`. ok=false means the flow stops with the
+// returned Result; the caller has not touched the engine yet.
+func (service *Service) casToInProgress(ctx context.Context, opStartedAt time.Time, input Input) (Result, bool) {
+	err := service.runtimeRecords.UpdateStatus(ctx, ports.UpdateStatusInput{
+		GameID:       input.GameID,
+		ExpectedFrom: runtime.StatusRunning,
+		To:           runtime.StatusGenerationInProgress,
+		Now:          opStartedAt,
+	})
+	switch {
+	case err == nil:
+		return Result{}, true
+	case errors.Is(err, runtime.ErrConflict):
+		return service.recordEarlyFailure(ctx, opStartedAt, input,
+			ErrorCodeConflict,
+			fmt.Sprintf("cas runtime status to generation_in_progress: %s", err.Error())), false
+	case errors.Is(err, runtime.ErrNotFound):
+		return service.recordEarlyFailure(ctx, opStartedAt, input,
+			ErrorCodeRuntimeNotFound,
+			fmt.Sprintf("cas runtime status to generation_in_progress: %s", err.Error())), false
+	default:
+		return service.recordEarlyFailure(ctx, opStartedAt, input,
+			ErrorCodeServiceUnavailable,
+			fmt.Sprintf("cas runtime status to generation_in_progress: %s", err.Error())), false
+	}
+}
+
+// callEngineTurn dispatches the engine /admin/turn call and classifies
+// the outcome. engineOK=true means the response is well-formed at the
+// transport level; engineOK=false populates errorCode / errorMessage
+// with a stable failure shape.
+func (service *Service) callEngineTurn(ctx context.Context, record runtime.RuntimeRecord) (state ports.StateResponse, engineOK bool, errorCode string, errorMessage string) {
+	state, err := service.engine.Turn(ctx, record.EngineEndpoint)
+	if err == nil {
+		return state, true, "", ""
+	}
+	return ports.StateResponse{}, false, classifyEngineError(err), fmt.Sprintf("engine turn: %s", err.Error())
+}
+
+// classifyEngineError maps the engine port sentinels to the
+// turn-generation stable error codes.
+func classifyEngineError(err error) string {
+	switch {
+	case errors.Is(err, ports.ErrEngineValidation):
+		return ErrorCodeEngineValidationError
+	case errors.Is(err, ports.ErrEngineProtocolViolation):
+		return ErrorCodeEngineProtocolViolation
+	case errors.Is(err, ports.ErrEngineUnreachable):
+		return ErrorCodeEngineUnreachable
+	default:
+		return ErrorCodeEngineUnreachable
+	}
+}
+
+// validateRoster checks that the engine response carries exactly the
+// race set installed at register-runtime. ok=false means the flow stops
+// (and the runtime row is moved to `generation_failed`).
+func (service *Service) validateRoster(ctx context.Context, opStartedAt time.Time, input Input, record runtime.RuntimeRecord, state ports.StateResponse, mappings []playermapping.PlayerMapping) (Result, bool) {
+	if len(state.Players) != len(mappings) {
+		message := fmt.Sprintf("engine player count %d does not match roster size %d",
+			len(state.Players), len(mappings))
+		return service.failGeneration(ctx, opStartedAt, input, record,
+			ErrorCodeEngineProtocolViolation, message), false
+	}
+	expected := make(map[string]struct{}, len(mappings))
+	for _, mapping := range mappings {
+		expected[mapping.RaceName] = struct{}{}
+	}
+	for _, player := range state.Players {
+		if _, ok := expected[player.RaceName]; !ok {
+			message := fmt.Sprintf("engine returned race %q not present in roster", player.RaceName)
+			return service.failGeneration(ctx, opStartedAt, input, record,
+				ErrorCodeEngineProtocolViolation, message), false
+		}
+	}
+	return Result{}, true
+}
+
+// completeFinished handles the `finished=true` branch: CAS to finished,
+// clear scheduling, publish game_finished, publish game.finished
+// notification, audit success.
+func (service *Service) completeFinished(ctx context.Context, opStartedAt time.Time, input Input, record runtime.RuntimeRecord, state ports.StateResponse, mappings []playermapping.PlayerMapping) Result {
+	finishedAt := service.clock().UTC()
+
+	err := service.runtimeRecords.UpdateStatus(ctx, ports.UpdateStatusInput{
+		GameID:       input.GameID,
+		ExpectedFrom: runtime.StatusGenerationInProgress,
+		To:           runtime.StatusFinished,
+		Now:          finishedAt,
+	})
+	if err != nil {
+		return service.handlePostEngineCASFailure(ctx, opStartedAt, input, record, err)
+	}
+
+	if err := service.runtimeRecords.UpdateScheduling(ctx, ports.UpdateSchedulingInput{
+		GameID:           input.GameID,
+		NextGenerationAt: nil,
+		SkipNextTick:     false,
+		CurrentTurn:      state.Turn,
+		Now:              finishedAt,
+	}); err != nil {
+		// The CAS to finished succeeded; the row is in the terminal
+		// state. Surface a service_unavailable to the caller but keep
+		// the audit and snapshot consistent.
+		return service.recordTerminalFailure(ctx, opStartedAt, input,
+			ErrorCodeServiceUnavailable,
+			fmt.Sprintf("update scheduling on finish: %s", err.Error()))
+	}
+
+	persisted, reloadErr := service.runtimeRecords.Get(ctx, input.GameID)
+	if reloadErr != nil {
+		return service.recordTerminalFailure(ctx, opStartedAt, input,
+			ErrorCodeServiceUnavailable,
+			fmt.Sprintf("reload runtime record: %s", reloadErr.Error()))
+	}
+
+	stats := projectPlayerStats(state, mappings)
+
+	finishedMsg := ports.GameFinished{
+		GameID:          input.GameID,
+		FinalTurnNumber: state.Turn,
+		RuntimeStatus:   runtime.StatusFinished,
+		PlayerTurnStats: stats,
+		FinishedAt:      finishedAt,
+	}
+	if err := service.lobbyEvents.PublishGameFinished(ctx, finishedMsg); err != nil {
+		service.logger.ErrorContext(ctx, "publish game finished",
+			"game_id", input.GameID,
+			"err", err.Error(),
+		)
+	} else {
+		service.telemetry.RecordLobbyEventPublished(ctx, "game_finished")
+	}
+
+	gameName := service.resolveGameName(ctx, input.GameID)
+	recipients := recipientUserIDs(mappings)
+	service.publishGameFinishedIntent(ctx, input, gameName, state.Turn, recipients, finishedAt)
+
+	service.appendSuccessLog(ctx, opStartedAt, input)
+	service.telemetry.RecordTurnGenerationOutcome(ctx,
+		string(operation.OutcomeSuccess), "", string(input.Trigger))
+
+	logArgs := []any{
+		"game_id", input.GameID,
+		"trigger", string(input.Trigger),
+		"final_turn", state.Turn,
+		"finished", true,
+	}
+	logArgs = append(logArgs, logging.ContextAttrs(ctx)...)
+	service.logger.InfoContext(ctx, "turn generation finished game", logArgs...)
+
+	return Result{
+		Record:   persisted,
+		Trigger:  input.Trigger,
+		Finished: true,
+		Outcome:  operation.OutcomeSuccess,
+	}
+}
+
+// completeRunning handles the `finished=false` branch: recompute next
+// tick, CAS back to running, publish snapshot, publish
+// game.turn.ready notification, audit success.
+func (service *Service) completeRunning(ctx context.Context, opStartedAt time.Time, input Input, record runtime.RuntimeRecord, state ports.StateResponse, mappings []playermapping.PlayerMapping) Result {
+	completedAt := service.clock().UTC()
+
+	next, _, err := service.scheduler.ComputeNext(record.TurnSchedule, completedAt, record.SkipNextTick)
+	if err != nil {
+		return service.failGeneration(ctx, opStartedAt, input, record,
+			ErrorCodeInvalidRequest,
+			fmt.Sprintf("recompute next tick: %s", err.Error()))
+	}
+
+	if err := service.runtimeRecords.UpdateStatus(ctx, ports.UpdateStatusInput{
+		GameID:       input.GameID,
+		ExpectedFrom: runtime.StatusGenerationInProgress,
+		To:           runtime.StatusRunning,
+		Now:          completedAt,
+	}); err != nil {
+		return service.handlePostEngineCASFailure(ctx, opStartedAt, input, record, err)
+	}
+
+	if err := service.runtimeRecords.UpdateScheduling(ctx, ports.UpdateSchedulingInput{
+		GameID:           input.GameID,
+		NextGenerationAt: &next,
+		SkipNextTick:     false,
+		CurrentTurn:      state.Turn,
+		Now:              completedAt,
+	}); err != nil {
+		return service.recordTerminalFailure(ctx, opStartedAt, input,
+			ErrorCodeServiceUnavailable,
+			fmt.Sprintf("update scheduling on running: %s", err.Error()))
+	}
+
+	persisted, reloadErr := service.runtimeRecords.Get(ctx, input.GameID)
+	if reloadErr != nil {
+		return service.recordTerminalFailure(ctx, opStartedAt, input,
+			ErrorCodeServiceUnavailable,
+			fmt.Sprintf("reload runtime record: %s", reloadErr.Error()))
+	}
+
+	stats := projectPlayerStats(state, mappings)
+
+	snapshot := ports.RuntimeSnapshotUpdate{
+		GameID:              input.GameID,
+		CurrentTurn:         state.Turn,
+		RuntimeStatus:       runtime.StatusRunning,
+		EngineHealthSummary: persisted.EngineHealth,
+		PlayerTurnStats:     stats,
+		OccurredAt:          completedAt,
+	}
+	if err := service.lobbyEvents.PublishSnapshotUpdate(ctx, snapshot); err != nil {
+		service.logger.ErrorContext(ctx, "publish runtime snapshot update",
+			"game_id", input.GameID,
+			"err", err.Error(),
+		)
+	} else {
+		service.telemetry.RecordLobbyEventPublished(ctx, "runtime_snapshot_update")
+	}
+
+	gameName := service.resolveGameName(ctx, input.GameID)
+	recipients := recipientUserIDs(mappings)
+	service.publishGameTurnReadyIntent(ctx, input, gameName, state.Turn, recipients, completedAt)
+
+	service.appendSuccessLog(ctx, opStartedAt, input)
+	service.telemetry.RecordTurnGenerationOutcome(ctx,
+		string(operation.OutcomeSuccess), "", string(input.Trigger))
+
+	logArgs := []any{
+		"game_id", input.GameID,
+		"trigger", string(input.Trigger),
+		"current_turn", state.Turn,
+		"next_generation_at", next.Format(time.RFC3339Nano),
+	}
+	logArgs = append(logArgs, logging.ContextAttrs(ctx)...)
+	service.logger.InfoContext(ctx, "turn generation succeeded", logArgs...)
+
+	return Result{
+		Record:  persisted,
+		Trigger: input.Trigger,
+		Outcome: operation.OutcomeSuccess,
+	}
+}
+
+// failGeneration handles every post-CAS failure path: CAS to
+// generation_failed, publish snapshot, publish game.generation_failed
+// admin notification, audit failure.
+func (service *Service) failGeneration(ctx context.Context, opStartedAt time.Time, input Input, _ runtime.RuntimeRecord, errorCode string, errorMessage string) Result {
+	failedAt := service.clock().UTC()
+
+	casErr := service.runtimeRecords.UpdateStatus(ctx, ports.UpdateStatusInput{
+		GameID:       input.GameID,
+		ExpectedFrom: runtime.StatusGenerationInProgress,
+		To:           runtime.StatusGenerationFailed,
+		Now:          failedAt,
+	})
+	if casErr != nil && !errors.Is(casErr, runtime.ErrConflict) {
+		// Best-effort transition. The original error code remains the
+		// caller-visible one; log the secondary failure.
+		service.logger.ErrorContext(ctx, "cas runtime status to generation_failed",
+			"game_id", input.GameID,
+			"err", casErr.Error(),
+		)
+	}
+
+	persisted, reloadErr := service.runtimeRecords.Get(ctx, input.GameID)
+	publishedStatus := runtime.StatusGenerationFailed
+	if reloadErr == nil {
+		publishedStatus = persisted.Status
+	}
+
+	snapshot := ports.RuntimeSnapshotUpdate{
+		GameID:              input.GameID,
+		CurrentTurn:         persistedTurn(persisted, reloadErr),
+		RuntimeStatus:       publishedStatus,
+		EngineHealthSummary: persistedHealth(persisted, reloadErr),
+		PlayerTurnStats:     nil,
+		OccurredAt:          failedAt,
+	}
+	if err := service.lobbyEvents.PublishSnapshotUpdate(ctx, snapshot); err != nil {
+		service.logger.ErrorContext(ctx, "publish runtime snapshot update on failure",
+			"game_id", input.GameID,
+			"err", err.Error(),
+		)
+	} else {
+		service.telemetry.RecordLobbyEventPublished(ctx, "runtime_snapshot_update")
+	}
+
+	gameName := service.resolveGameName(ctx, input.GameID)
+	service.publishGameGenerationFailedIntent(ctx, input, gameName, errorCode, errorMessage, failedAt)
+
+	service.appendFailureLog(ctx, opStartedAt, input, errorCode, errorMessage)
+	service.telemetry.RecordTurnGenerationOutcome(ctx,
+		string(operation.OutcomeFailure), errorCode, string(input.Trigger))
+
+	logArgs := []any{
+		"game_id", input.GameID,
+		"trigger", string(input.Trigger),
+		"error_code", errorCode,
+		"error_message", errorMessage,
+	}
+	logArgs = append(logArgs, logging.ContextAttrs(ctx)...)
+	service.logger.WarnContext(ctx, "turn generation failed", logArgs...)
+
+	return Result{
+		Record:       persisted,
+		Trigger:      input.Trigger,
+		Outcome:      operation.OutcomeFailure,
+		ErrorCode:    errorCode,
+		ErrorMessage: errorMessage,
+	}
+}
+
+// handlePostEngineCASFailure maps a CAS error that surfaced after the
+// engine call already succeeded. Conflict means an external actor (e.g.
+// admin stop) won the race; other errors are treated as
+// service_unavailable. No publication is issued — the external mutation
+// owns its own snapshot.
+func (service *Service) handlePostEngineCASFailure(ctx context.Context, opStartedAt time.Time, input Input, _ runtime.RuntimeRecord, casErr error) Result {
+	switch {
+	case errors.Is(casErr, runtime.ErrConflict):
+		return service.recordTerminalFailure(ctx, opStartedAt, input,
+			ErrorCodeConflict,
+			fmt.Sprintf("cas runtime status post-engine: %s", casErr.Error()))
+	case errors.Is(casErr, runtime.ErrNotFound):
+		return service.recordTerminalFailure(ctx, opStartedAt, input,
+			ErrorCodeRuntimeNotFound,
+			fmt.Sprintf("cas runtime status post-engine: %s", casErr.Error()))
+	default:
+		return service.recordTerminalFailure(ctx, opStartedAt, input,
+			ErrorCodeServiceUnavailable,
+			fmt.Sprintf("cas runtime status post-engine: %s", casErr.Error()))
+	}
+}
+
+// recordEarlyFailure handles failures that occur before the runtime row
+// is in `generation_in_progress`. No status mutation, no publication;
+// only audit and telemetry.
+func (service *Service) recordEarlyFailure(ctx context.Context, opStartedAt time.Time, input Input, errorCode string, errorMessage string) Result {
+	service.appendFailureLog(ctx, opStartedAt, input, errorCode, errorMessage)
+	service.telemetry.RecordTurnGenerationOutcome(ctx,
+		string(operation.OutcomeFailure), errorCode, string(input.Trigger))
+	logArgs := []any{
+		"game_id", input.GameID,
+		"trigger", string(input.Trigger),
+		"error_code", errorCode,
+		"error_message", errorMessage,
+	}
+	logArgs = append(logArgs, logging.ContextAttrs(ctx)...)
+	service.logger.WarnContext(ctx, "turn generation rejected", logArgs...)
+	return Result{
+		Trigger:      input.Trigger,
+		Outcome:      operation.OutcomeFailure,
+		ErrorCode:    errorCode,
+		ErrorMessage: errorMessage,
+	}
+}
+
+// recordTerminalFailure handles failures after a post-engine CAS or a
+// reload failed. The runtime row is in an undetermined state owned by
+// whatever mutation won; we record the audit and surface the failure
+// without further publication.
+func (service *Service) recordTerminalFailure(ctx context.Context, opStartedAt time.Time, input Input, errorCode string, errorMessage string) Result {
+	service.appendFailureLog(ctx, opStartedAt, input, errorCode, errorMessage)
+	service.telemetry.RecordTurnGenerationOutcome(ctx,
+		string(operation.OutcomeFailure), errorCode, string(input.Trigger))
+	logArgs := []any{
+		"game_id", input.GameID,
+		"trigger", string(input.Trigger),
+		"error_code", errorCode,
+		"error_message", errorMessage,
+	}
+	logArgs = append(logArgs, logging.ContextAttrs(ctx)...)
+	service.logger.WarnContext(ctx, "turn generation post-engine failure", logArgs...)
+	return Result{
+		Trigger:      input.Trigger,
+		Outcome:      operation.OutcomeFailure,
+		ErrorCode:    errorCode,
+		ErrorMessage: errorMessage,
+	}
+}
+
+// resolveGameName fetches the human-readable game name from Lobby and
+// falls back to the platform game id on any error per Stage 15 D1.
+func (service *Service) resolveGameName(ctx context.Context, gameID string) string {
+	summary, err := service.lobby.GetGameSummary(ctx, gameID)
+	if err != nil {
+		logArgs := []any{
+			"game_id", gameID,
+			"error_code", "lobby_unavailable",
+			"err", err.Error(),
+		}
+		logArgs = append(logArgs, logging.ContextAttrs(ctx)...)
+		service.logger.WarnContext(ctx, "resolve game name fell back to game id", logArgs...)
+		return gameID
+	}
+	if strings.TrimSpace(summary.GameName) == "" {
+		return gameID
+	}
+	return summary.GameName
+}
+
+// publishGameTurnReadyIntent publishes the user-targeted notification
+// that announces a freshly generated turn. Empty recipient sets are
+// dropped silently — the validator inside notificationintent rejects
+// them outright, but the orchestrator should not break commit.
+func (service *Service) publishGameTurnReadyIntent(ctx context.Context, input Input, gameName string, turnNumber int, recipients []string, occurredAt time.Time) {
+	if len(recipients) == 0 {
+		service.logger.WarnContext(ctx, "skip game.turn.ready notification: empty recipient set",
+			"game_id", input.GameID,
+		)
+		return
+	}
+	intent, err := notificationintent.NewGameTurnReadyIntent(
+		notificationintent.Metadata{
+			IdempotencyKey: fmt.Sprintf("game.turn.ready:%s:%d", input.GameID, turnNumber),
+			OccurredAt:     occurredAt,
+			RequestID:      logging.RequestIDFromContext(ctx),
+		},
+		recipients,
+		notificationintent.GameTurnReadyPayload{
+			GameID:     input.GameID,
+			GameName:   gameName,
+			TurnNumber: int64(turnNumber),
+		},
+	)
+	if err != nil {
+		service.logger.ErrorContext(ctx, "build game.turn.ready intent",
+			"game_id", input.GameID,
+			"err", err.Error(),
+		)
+		service.telemetry.RecordNotificationPublishAttempt(ctx,
+			string(notificationintent.NotificationTypeGameTurnReady), "error")
+		return
+	}
+	if err := service.notifications.Publish(ctx, intent); err != nil {
+		service.logger.ErrorContext(ctx, "publish game.turn.ready intent",
+			"game_id", input.GameID,
+			"err", err.Error(),
+		)
+		service.telemetry.RecordNotificationPublishAttempt(ctx,
+			string(notificationintent.NotificationTypeGameTurnReady), "error")
+		return
+	}
+	service.telemetry.RecordNotificationPublishAttempt(ctx,
+		string(notificationintent.NotificationTypeGameTurnReady), "ok")
+}
+
+// publishGameFinishedIntent publishes the user-targeted notification
+// that announces a finished game.
+func (service *Service) publishGameFinishedIntent(ctx context.Context, input Input, gameName string, finalTurnNumber int, recipients []string, occurredAt time.Time) {
+	if len(recipients) == 0 {
+		service.logger.WarnContext(ctx, "skip game.finished notification: empty recipient set",
+			"game_id", input.GameID,
+		)
+		return
+	}
+	intent, err := notificationintent.NewGameFinishedIntent(
+		notificationintent.Metadata{
+			IdempotencyKey: fmt.Sprintf("game.finished:%s:%d", input.GameID, finalTurnNumber),
+			OccurredAt:     occurredAt,
+			RequestID:      logging.RequestIDFromContext(ctx),
+		},
+		recipients,
+		notificationintent.GameFinishedPayload{
+			GameID:          input.GameID,
+			GameName:        gameName,
+			FinalTurnNumber: int64(finalTurnNumber),
+		},
+	)
+	if err != nil {
+		service.logger.ErrorContext(ctx, "build game.finished intent",
+			"game_id", input.GameID,
+			"err", err.Error(),
+		)
+		service.telemetry.RecordNotificationPublishAttempt(ctx,
+			string(notificationintent.NotificationTypeGameFinished), "error")
+		return
+	}
+	if err := service.notifications.Publish(ctx, intent); err != nil {
+		service.logger.ErrorContext(ctx, "publish game.finished intent",
+			"game_id", input.GameID,
+			"err", err.Error(),
+		)
+		service.telemetry.RecordNotificationPublishAttempt(ctx,
+			string(notificationintent.NotificationTypeGameFinished), "error")
+		return
+	}
+	service.telemetry.RecordNotificationPublishAttempt(ctx,
+		string(notificationintent.NotificationTypeGameFinished), "ok")
+}
+
+// publishGameGenerationFailedIntent publishes the admin-email
+// notification that announces a failed turn generation.
+func (service *Service) publishGameGenerationFailedIntent(ctx context.Context, input Input, gameName string, errorCode string, errorMessage string, occurredAt time.Time) {
+	failureReason := errorCode
+	if strings.TrimSpace(errorMessage) != "" {
+		failureReason = fmt.Sprintf("%s: %s", errorCode, errorMessage)
+	}
+	intent, err := notificationintent.NewGameGenerationFailedIntent(
+		notificationintent.Metadata{
+			IdempotencyKey: fmt.Sprintf("game.generation_failed:%s:%d",
+				input.GameID, occurredAt.UnixMilli()),
+			OccurredAt: occurredAt,
+			RequestID:  logging.RequestIDFromContext(ctx),
+		},
+		notificationintent.GameGenerationFailedPayload{
+			GameID:        input.GameID,
+			GameName:      gameName,
+			FailureReason: failureReason,
+		},
+	)
+	if err != nil {
+		service.logger.ErrorContext(ctx, "build game.generation_failed intent",
+			"game_id", input.GameID,
+			"err", err.Error(),
+		)
+		service.telemetry.RecordNotificationPublishAttempt(ctx,
+			string(notificationintent.NotificationTypeGameGenerationFailed), "error")
+		return
+	}
+	if err := service.notifications.Publish(ctx, intent); err != nil {
+		service.logger.ErrorContext(ctx, "publish game.generation_failed intent",
+			"game_id", input.GameID,
+			"err", err.Error(),
+		)
+		service.telemetry.RecordNotificationPublishAttempt(ctx,
+			string(notificationintent.NotificationTypeGameGenerationFailed), "error")
+		return
+	}
+	service.telemetry.RecordNotificationPublishAttempt(ctx,
+		string(notificationintent.NotificationTypeGameGenerationFailed), "ok")
+}
+
+// projectPlayerStats joins the engine response on RaceName against the
+// installed roster to build one PlayerTurnStats per active member.
+// Result is sorted by UserID for a deterministic wire order.
+func projectPlayerStats(state ports.StateResponse, mappings []playermapping.PlayerMapping) []ports.PlayerTurnStats {
+	if len(state.Players) == 0 || len(mappings) == 0 {
+		return nil
+	}
+	userByRace := make(map[string]string, len(mappings))
+	for _, mapping := range mappings {
+		userByRace[mapping.RaceName] = mapping.UserID
+	}
+	stats := make([]ports.PlayerTurnStats, 0, len(state.Players))
+	for _, player := range state.Players {
+		userID, ok := userByRace[player.RaceName]
+		if !ok {
+			continue
+		}
+		stats = append(stats, ports.PlayerTurnStats{
+			UserID:     userID,
+			Planets:    player.Planets,
+			Population: player.Population,
+		})
+	}
+	sort.Slice(stats, func(i, j int) bool { return stats[i].UserID < stats[j].UserID })
+	return stats
+}
+
+// recipientUserIDs returns the deduplicated, sorted-ascending list of
+// platform user ids derived from the roster. Mirrors the
+// notificationintent validator's expectations.
+func recipientUserIDs(mappings []playermapping.PlayerMapping) []string {
+	if len(mappings) == 0 {
+		return nil
+	}
+	seen := make(map[string]struct{}, len(mappings))
+	result := make([]string, 0, len(mappings))
+	for _, mapping := range mappings {
+		userID := strings.TrimSpace(mapping.UserID)
+		if userID == "" {
+			continue
+		}
+		if _, ok := seen[userID]; ok {
+			continue
+		}
+		seen[userID] = struct{}{}
+		result = append(result, userID)
+	}
+	sort.Strings(result)
+	return result
+}
+
+// persistedTurn returns the stored CurrentTurn when reloadErr is nil,
+// or zero otherwise. Used to populate the failure-side snapshot
+// without making a second DB read.
+func persistedTurn(record runtime.RuntimeRecord, reloadErr error) int {
+	if reloadErr != nil {
+		return 0
+	}
+	return record.CurrentTurn
+}
+
+// persistedHealth returns the stored EngineHealth when reloadErr is
+// nil, or empty string otherwise.
+func persistedHealth(record runtime.RuntimeRecord, reloadErr error) string {
+	if reloadErr != nil {
+		return ""
+	}
+	return record.EngineHealth
+}
+
+// appendSuccessLog records the success operation_log entry.
+func (service *Service) appendSuccessLog(ctx context.Context, opStartedAt time.Time, input Input) {
+	finishedAt := service.clock().UTC()
+	service.bestEffortAppend(ctx, operation.OperationEntry{
+		GameID:     input.GameID,
+		OpKind:     operation.OpKindTurnGeneration,
+		OpSource:   fallbackOpSource(input.OpSource),
+		SourceRef:  input.SourceRef,
+		Outcome:    operation.OutcomeSuccess,
+		StartedAt:  opStartedAt,
+		FinishedAt: &finishedAt,
+	})
+}
+
+// appendFailureLog records the failure operation_log entry.
+func (service *Service) appendFailureLog(ctx context.Context, opStartedAt time.Time, input Input, errorCode string, errorMessage string) {
+	finishedAt := service.clock().UTC()
+	service.bestEffortAppend(ctx, operation.OperationEntry{
+		GameID:       input.GameID,
+		OpKind:       operation.OpKindTurnGeneration,
+		OpSource:     fallbackOpSource(input.OpSource),
+		SourceRef:    input.SourceRef,
+		Outcome:      operation.OutcomeFailure,
+		ErrorCode:    errorCode,
+		ErrorMessage: errorMessage,
+		StartedAt:    opStartedAt,
+		FinishedAt:   &finishedAt,
+	})
+}
+
+// bestEffortAppend writes one operation_log entry. A failure is logged
+// and discarded; the runtime row is the source of truth.
+func (service *Service) bestEffortAppend(ctx context.Context, entry operation.OperationEntry) {
+	if _, err := service.operationLogs.Append(ctx, entry); err != nil {
+		service.logger.ErrorContext(ctx, "append operation log",
+			"game_id", entry.GameID,
+			"op_kind", string(entry.OpKind),
+			"outcome", string(entry.Outcome),
+			"error_code", entry.ErrorCode,
+			"err", err.Error(),
+		)
+	}
+}
+
+// fallbackOpSource defaults to admin_rest when source is missing or
+// unrecognised. Mirrors `gamemaster/README.md §Trusted Surfaces`.
+func fallbackOpSource(source operation.OpSource) operation.OpSource {
+	if source.IsKnown() {
+		return source
+	}
+	return operation.OpSourceAdminRest
+}