feat: game lobby service

lobby/internal/service/redeeminvite/service.go

@@ -0,0 +1,357 @@
+// Package redeeminvite implements the `lobby.invite.redeem` message type. It
+// validates the invitee against the private-game enrollment rules, reserves
+// the chosen race name, transitions the invite from created to redeemed,
+// creates the matching active membership, opens the gap window when the new
+// approved count equals max_players, and publishes the
+// `lobby.invite.redeemed` notification intent to the private-game owner.
+package redeeminvite
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"time"
+
+	"galaxy/lobby/internal/domain/common"
+	"galaxy/lobby/internal/domain/game"
+	"galaxy/lobby/internal/domain/invite"
+	"galaxy/lobby/internal/domain/membership"
+	"galaxy/lobby/internal/logging"
+	"galaxy/lobby/internal/ports"
+	"galaxy/lobby/internal/service/shared"
+	"galaxy/lobby/internal/telemetry"
+	"galaxy/notificationintent"
+)
+
+// Service executes the private-game invite redemption use case.
+type Service struct {
+	games       ports.GameStore
+	invites     ports.InviteStore
+	memberships ports.MembershipStore
+	directory   ports.RaceNameDirectory
+	users       ports.UserService
+	gapStore    ports.GapActivationStore
+	intents     ports.IntentPublisher
+	ids         ports.IDGenerator
+	clock       func() time.Time
+	logger      *slog.Logger
+	telemetry   *telemetry.Runtime
+}
+
+// Dependencies groups the collaborators used by Service.
+type Dependencies struct {
+	// Games loads the target game record for status verification and the
+	// owner notification recipient.
+	Games ports.GameStore
+
+	// Invites loads the target invite and applies the
+	// created → redeemed transition.
+	Invites ports.InviteStore
+
+	// Memberships persists the new active membership and supplies the
+	// approved-count for the gap-window decision and capacity guard.
+	Memberships ports.MembershipStore
+
+	// Directory canonicalizes the race name and reserves it for the
+	// invitee.
+	Directory ports.RaceNameDirectory
+
+	// Users resolves the synchronous eligibility snapshot for both the
+	// inviter and the invitee. uses it to short-circuit
+	// redemption when either party has been permanently blocked or
+	// soft-deleted between invite creation and the redeem attempt.
+	Users ports.UserService
+
+	// GapStore records the gap-window activation timestamp when the new
+	// approved count equals max_players.
+	GapStore ports.GapActivationStore
+
+	// Intents publishes the lobby.invite.redeemed intent to the owner.
+	Intents ports.IntentPublisher
+
+	// IDs mints the new opaque membership identifier.
+	IDs ports.IDGenerator
+
+	// Clock supplies the wall-clock used for DecidedAt, JoinedAt,
+	// gap-activation time, and the notification's OccurredAt.
+	Clock func() time.Time
+
+	// Logger records structured service-level events.
+	Logger *slog.Logger
+
+	// Telemetry records the `lobby.invite.outcomes` and
+	// `lobby.membership.changes` counters. Optional; nil disables
+	// metric emission.
+	Telemetry *telemetry.Runtime
+}
+
+// NewService constructs one Service with deps.
+func NewService(deps Dependencies) (*Service, error) {
+	switch {
+	case deps.Games == nil:
+		return nil, errors.New("new redeem invite service: nil game store")
+	case deps.Invites == nil:
+		return nil, errors.New("new redeem invite service: nil invite store")
+	case deps.Memberships == nil:
+		return nil, errors.New("new redeem invite service: nil membership store")
+	case deps.Directory == nil:
+		return nil, errors.New("new redeem invite service: nil race name directory")
+	case deps.Users == nil:
+		return nil, errors.New("new redeem invite service: nil user service")
+	case deps.GapStore == nil:
+		return nil, errors.New("new redeem invite service: nil gap activation store")
+	case deps.Intents == nil:
+		return nil, errors.New("new redeem invite service: nil intent publisher")
+	case deps.IDs == nil:
+		return nil, errors.New("new redeem invite service: nil id generator")
+	}
+	clock := deps.Clock
+	if clock == nil {
+		clock = time.Now
+	}
+	logger := deps.Logger
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &Service{
+		games:       deps.Games,
+		invites:     deps.Invites,
+		memberships: deps.Memberships,
+		directory:   deps.Directory,
+		users:       deps.Users,
+		gapStore:    deps.GapStore,
+		intents:     deps.Intents,
+		ids:         deps.IDs,
+		clock:       clock,
+		logger:      logger.With("service", "lobby.redeeminvite"),
+		telemetry:   deps.Telemetry,
+	}, nil
+}
+
+// Input stores the arguments required to redeem one invite.
+type Input struct {
+	// Actor identifies the caller. Must be the invitee.
+	Actor shared.Actor
+
+	// GameID identifies the game referenced by the request path; it must
+	// match the loaded invite's GameID.
+	GameID common.GameID
+
+	// InviteID identifies the target invite.
+	InviteID common.InviteID
+
+	// RaceName stores the desired in-game name in original casing.
+	RaceName string
+}
+
+// Handle authorizes the invitee, validates the invite + game state, reserves
+// the race name, transitions the invite, persists the active membership,
+// opens the gap window if appropriate, and publishes the
+// lobby.invite.redeemed intent on success.
+func (service *Service) Handle(ctx context.Context, input Input) (membership.Membership, error) {
+	if service == nil {
+		return membership.Membership{}, errors.New("redeem invite: nil service")
+	}
+	if ctx == nil {
+		return membership.Membership{}, errors.New("redeem invite: nil context")
+	}
+	if err := input.Actor.Validate(); err != nil {
+		return membership.Membership{}, fmt.Errorf("redeem invite: actor: %w", err)
+	}
+	if !input.Actor.IsUser() {
+		return membership.Membership{}, fmt.Errorf(
+			"%w: only the invited user may redeem an invite",
+			shared.ErrForbidden,
+		)
+	}
+	if err := input.GameID.Validate(); err != nil {
+		return membership.Membership{}, fmt.Errorf("redeem invite: %w", err)
+	}
+	if err := input.InviteID.Validate(); err != nil {
+		return membership.Membership{}, fmt.Errorf("redeem invite: %w", err)
+	}
+
+	inv, err := service.invites.Get(ctx, input.InviteID)
+	if err != nil {
+		return membership.Membership{}, fmt.Errorf("redeem invite: %w", err)
+	}
+	if inv.GameID != input.GameID {
+		// Defensive: opaque ids must not leak across games.
+		return membership.Membership{}, fmt.Errorf(
+			"redeem invite: invite %q does not belong to game %q: %w",
+			inv.InviteID, input.GameID, invite.ErrNotFound,
+		)
+	}
+	if inv.InviteeUserID != input.Actor.UserID {
+		return membership.Membership{}, fmt.Errorf(
+			"%w: invite is addressed to a different user",
+			shared.ErrForbidden,
+		)
+	}
+	if inv.Status != invite.StatusCreated {
+		return membership.Membership{}, fmt.Errorf(
+			"redeem invite: status %q is not %q: %w",
+			inv.Status, invite.StatusCreated, invite.ErrConflict,
+		)
+	}
+
+	gameRecord, err := service.games.Get(ctx, input.GameID)
+	if err != nil {
+		return membership.Membership{}, fmt.Errorf("redeem invite: %w", err)
+	}
+	if gameRecord.GameType != game.GameTypePrivate {
+		return membership.Membership{}, fmt.Errorf(
+			"redeem invite: game %q is not private: %w",
+			gameRecord.GameID, game.ErrConflict,
+		)
+	}
+	if gameRecord.Status != game.StatusEnrollmentOpen {
+		return membership.Membership{}, fmt.Errorf(
+			"redeem invite: game %q is not in enrollment_open: %w",
+			gameRecord.GameID, game.ErrConflict,
+		)
+	}
+
+	// cascade guard: a permanent_block or DeleteUser on the
+	// inviter or the invitee makes the invite untusable. Return
+	// subject_not_found so the caller sees the same outcome as if the
+	// invite never existed, even when the user-lifecycle cascade has
+	// not yet flipped the invite to revoked.
+	if err := service.requireActiveParty(ctx, inv.InviterUserID, "inviter"); err != nil {
+		return membership.Membership{}, err
+	}
+	if err := service.requireActiveParty(ctx, input.Actor.UserID, "invitee"); err != nil {
+		return membership.Membership{}, err
+	}
+
+	cap := gameRecord.MaxPlayers + gameRecord.StartGapPlayers
+	currentActive, err := shared.CountActiveMemberships(ctx, service.memberships, gameRecord.GameID)
+	if err != nil {
+		return membership.Membership{}, fmt.Errorf("redeem invite: %w", err)
+	}
+	if currentActive >= cap {
+		return membership.Membership{}, fmt.Errorf(
+			"redeem invite: roster full (%d active >= %d cap): %w",
+			currentActive, cap, game.ErrConflict,
+		)
+	}
+
+	canonical, err := service.directory.Canonicalize(input.RaceName)
+	if err != nil {
+		return membership.Membership{}, fmt.Errorf("redeem invite: %w", err)
+	}
+
+	if err := service.directory.Reserve(ctx, gameRecord.GameID.String(), input.Actor.UserID, input.RaceName); err != nil {
+		return membership.Membership{}, fmt.Errorf("redeem invite: %w", err)
+	}
+
+	now := service.clock().UTC()
+	updateErr := service.invites.UpdateStatus(ctx, ports.UpdateInviteStatusInput{
+		InviteID:     inv.InviteID,
+		ExpectedFrom: invite.StatusCreated,
+		To:           invite.StatusRedeemed,
+		At:           now,
+		RaceName:     input.RaceName,
+	})
+	if updateErr != nil {
+		// Concurrent mutation lost the CAS race. Release the
+		// reservation we just made so it does not orphan; the user
+		// may retry redeem later under the same canonical key.
+		if releaseErr := service.directory.ReleaseReservation(ctx, gameRecord.GameID.String(), input.Actor.UserID, input.RaceName); releaseErr != nil {
+			service.logger.WarnContext(ctx, "release reservation after redeem cas failure",
+				"invite_id", inv.InviteID.String(),
+				"err", releaseErr.Error(),
+			)
+		}
+		return membership.Membership{}, fmt.Errorf("redeem invite: %w", updateErr)
+	}
+
+	membershipID, err := service.ids.NewMembershipID()
+	if err != nil {
+		return membership.Membership{}, fmt.Errorf("redeem invite: %w", err)
+	}
+	memberRecord, err := membership.New(membership.NewMembershipInput{
+		MembershipID: membershipID,
+		GameID:       gameRecord.GameID,
+		UserID:       input.Actor.UserID,
+		RaceName:     input.RaceName,
+		CanonicalKey: canonical,
+		Now:          now,
+	})
+	if err != nil {
+		return membership.Membership{}, fmt.Errorf("redeem invite: %w", err)
+	}
+	if err := service.memberships.Save(ctx, memberRecord); err != nil {
+		return membership.Membership{}, fmt.Errorf("redeem invite: %w", err)
+	}
+
+	// Gap-window trigger: count after Save now includes the new
+	// membership, so if it equals max_players we just crossed the
+	// threshold. The worker reads gap_activated_at to time
+	// out the gap; auto-transition to ready_to_start is its job.
+	if currentActive+1 == gameRecord.MaxPlayers {
+		if err := service.gapStore.MarkActivated(ctx, gameRecord.GameID, now); err != nil {
+			service.logger.WarnContext(ctx, "mark gap activation",
+				"game_id", gameRecord.GameID.String(),
+				"err", err.Error(),
+			)
+		}
+	}
+
+	intent, err := notificationintent.NewLobbyInviteRedeemedIntent(
+		notificationintent.Metadata{
+			IdempotencyKey: "lobby.invite.redeemed:" + inv.InviteID.String(),
+			OccurredAt:     now,
+		},
+		gameRecord.OwnerUserID,
+		notificationintent.LobbyInviteRedeemedPayload{
+			GameID:        gameRecord.GameID.String(),
+			GameName:      gameRecord.GameName,
+			InviteeUserID: memberRecord.UserID,
+			InviteeName:   memberRecord.RaceName,
+		},
+	)
+	if err != nil {
+		service.logger.ErrorContext(ctx, "build invite redeemed intent",
+			"invite_id", inv.InviteID.String(),
+			"err", err.Error(),
+		)
+	} else if _, publishErr := service.intents.Publish(ctx, intent); publishErr != nil {
+		service.logger.WarnContext(ctx, "publish invite redeemed intent",
+			"invite_id", inv.InviteID.String(),
+			"err", publishErr.Error(),
+		)
+	}
+
+	service.telemetry.RecordInviteOutcome(ctx, "redeemed")
+	service.telemetry.RecordMembershipChange(ctx, "activated")
+
+	logArgs := []any{
+		"game_id", gameRecord.GameID.String(),
+		"game_status", string(gameRecord.Status),
+		"invite_id", inv.InviteID.String(),
+		"membership_id", memberRecord.MembershipID.String(),
+		"user_id", memberRecord.UserID,
+		"race_name", memberRecord.RaceName,
+		"canonical_key", string(memberRecord.CanonicalKey),
+	}
+	logArgs = append(logArgs, logging.ContextAttrs(ctx)...)
+	service.logger.InfoContext(ctx, "invite redeemed", logArgs...)
+	return memberRecord, nil
+}
+
+// requireActiveParty fetches the eligibility snapshot for userID and
+// returns shared.ErrSubjectNotFound when the user no longer exists or
+// has been permanently blocked. Transport failures wrap
+// shared.ErrServiceUnavailable so the caller can map to HTTP 503.
+func (service *Service) requireActiveParty(ctx context.Context, userID, role string) error {
+	eligibility, err := service.users.GetEligibility(ctx, userID)
+	if err != nil {
+		return fmt.Errorf("redeem invite: %w of %s: %w", shared.ErrServiceUnavailable, role, err)
+	}
+	if !eligibility.Exists || eligibility.PermanentBlocked {
+		return fmt.Errorf("redeem invite: %s no longer active: %w", role, shared.ErrSubjectNotFound)
+	}
+	return nil
+}

lobby/internal/service/redeeminvite/service_test.go

@@ -0,0 +1,471 @@
+package redeeminvite_test
+
+import (
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"testing"
+	"time"
+
+	"galaxy/lobby/internal/adapters/gamestub"
+	"galaxy/lobby/internal/adapters/gapactivationstub"
+	"galaxy/lobby/internal/adapters/intentpubstub"
+	"galaxy/lobby/internal/adapters/invitestub"
+	"galaxy/lobby/internal/adapters/membershipstub"
+	"galaxy/lobby/internal/adapters/racenamestub"
+	"galaxy/lobby/internal/adapters/userservicestub"
+	"galaxy/lobby/internal/domain/common"
+	"galaxy/lobby/internal/domain/game"
+	"galaxy/lobby/internal/domain/invite"
+	"galaxy/lobby/internal/domain/membership"
+	"galaxy/lobby/internal/ports"
+	"galaxy/lobby/internal/service/redeeminvite"
+	"galaxy/lobby/internal/service/shared"
+	"galaxy/notificationintent"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const (
+	ownerUserID   = "user-owner"
+	inviteeUserID = "user-invitee"
+	defaultRace   = "VoidRunner"
+)
+
+func silentLogger() *slog.Logger { return slog.New(slog.NewTextHandler(io.Discard, nil)) }
+
+func fixedClock(at time.Time) func() time.Time { return func() time.Time { return at } }
+
+type fixedIDs struct {
+	membershipID common.MembershipID
+}
+
+func (f fixedIDs) NewGameID() (common.GameID, error)               { return "", errors.New("not used") }
+func (f fixedIDs) NewApplicationID() (common.ApplicationID, error) { return "", errors.New("not used") }
+func (f fixedIDs) NewInviteID() (common.InviteID, error)           { return "", errors.New("not used") }
+func (f fixedIDs) NewMembershipID() (common.MembershipID, error)   { return f.membershipID, nil }
+
+type fixture struct {
+	now         time.Time
+	games       *gamestub.Store
+	invites     *invitestub.Store
+	memberships *membershipstub.Store
+	directory   *racenamestub.Directory
+	users       *userservicestub.Service
+	gapStore    *gapactivationstub.Store
+	intents     *intentpubstub.Publisher
+	ids         fixedIDs
+	game        game.Game
+}
+
+func newFixture(t *testing.T, maxPlayers, gapPlayers int) *fixture {
+	t.Helper()
+	now := time.Date(2026, 4, 25, 10, 0, 0, 0, time.UTC)
+	dir, err := racenamestub.NewDirectory(racenamestub.WithClock(fixedClock(now)))
+	require.NoError(t, err)
+	games := gamestub.NewStore()
+	invites := invitestub.NewStore()
+	memberships := membershipstub.NewStore()
+
+	gameRecord, err := game.New(game.NewGameInput{
+		GameID:              "game-private",
+		GameName:            "Friends Only",
+		GameType:            game.GameTypePrivate,
+		OwnerUserID:         ownerUserID,
+		MinPlayers:          2,
+		MaxPlayers:          maxPlayers,
+		StartGapHours:       2,
+		StartGapPlayers:     gapPlayers,
+		EnrollmentEndsAt:    now.Add(24 * time.Hour),
+		TurnSchedule:        "0 */6 * * *",
+		TargetEngineVersion: "1.0.0",
+		Now:                 now,
+	})
+	require.NoError(t, err)
+	gameRecord.Status = game.StatusEnrollmentOpen
+	require.NoError(t, games.Save(context.Background(), gameRecord))
+
+	users := userservicestub.NewService()
+	activeEligibility := ports.Eligibility{
+		Exists:               true,
+		CanLogin:             true,
+		CanCreatePrivateGame: true,
+		CanManagePrivateGame: true,
+		CanJoinGame:          true,
+		CanUpdateProfile:     true,
+	}
+	users.SetEligibility(ownerUserID, activeEligibility)
+	users.SetEligibility(inviteeUserID, activeEligibility)
+
+	return &fixture{
+		now:         now,
+		games:       games,
+		invites:     invites,
+		memberships: memberships,
+		directory:   dir,
+		users:       users,
+		gapStore:    gapactivationstub.NewStore(),
+		intents:     intentpubstub.NewPublisher(),
+		ids:         fixedIDs{membershipID: "membership-fixed"},
+		game:        gameRecord,
+	}
+}
+
+func newService(t *testing.T, f *fixture) *redeeminvite.Service {
+	t.Helper()
+	svc, err := redeeminvite.NewService(redeeminvite.Dependencies{
+		Games:       f.games,
+		Invites:     f.invites,
+		Memberships: f.memberships,
+		Directory:   f.directory,
+		Users:       f.users,
+		GapStore:    f.gapStore,
+		Intents:     f.intents,
+		IDs:         f.ids,
+		Clock:       fixedClock(f.now),
+		Logger:      silentLogger(),
+	})
+	require.NoError(t, err)
+	return svc
+}
+
+func seedCreatedInvite(t *testing.T, f *fixture, inviteID common.InviteID, invitee string) invite.Invite {
+	t.Helper()
+	inv, err := invite.New(invite.NewInviteInput{
+		InviteID:      inviteID,
+		GameID:        f.game.GameID,
+		InviterUserID: ownerUserID,
+		InviteeUserID: invitee,
+		Now:           f.now,
+		ExpiresAt:     f.game.EnrollmentEndsAt,
+	})
+	require.NoError(t, err)
+	require.NoError(t, f.invites.Save(context.Background(), inv))
+	return inv
+}
+
+func defaultInput(f *fixture, inv invite.Invite) redeeminvite.Input {
+	return redeeminvite.Input{
+		Actor:    shared.NewUserActor(inviteeUserID),
+		GameID:   f.game.GameID,
+		InviteID: inv.InviteID,
+		RaceName: defaultRace,
+	}
+}
+
+func TestRedeemHappyPath(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	svc := newService(t, f)
+
+	got, err := svc.Handle(context.Background(), defaultInput(f, inv))
+	require.NoError(t, err)
+	assert.Equal(t, common.MembershipID("membership-fixed"), got.MembershipID)
+	assert.Equal(t, defaultRace, got.RaceName)
+	assert.Equal(t, "voidrunner", got.CanonicalKey)
+	assert.Equal(t, membership.StatusActive, got.Status)
+	assert.Equal(t, f.now, got.JoinedAt)
+	assert.Equal(t, inviteeUserID, got.UserID)
+
+	updated, err := f.invites.Get(context.Background(), inv.InviteID)
+	require.NoError(t, err)
+	assert.Equal(t, invite.StatusRedeemed, updated.Status)
+	assert.Equal(t, defaultRace, updated.RaceName)
+	require.NotNil(t, updated.DecidedAt)
+
+	avail, err := f.directory.Check(context.Background(), defaultRace, "user-other")
+	require.NoError(t, err)
+	assert.True(t, avail.Taken)
+	assert.Equal(t, inviteeUserID, avail.HolderUserID)
+
+	intents := f.intents.Published()
+	require.Len(t, intents, 1)
+	assert.Equal(t, notificationintent.NotificationTypeLobbyInviteRedeemed, intents[0].NotificationType)
+	assert.Equal(t, []string{ownerUserID}, intents[0].RecipientUserIDs)
+	assert.Contains(t, intents[0].PayloadJSON, `"invitee_name":"`+defaultRace+`"`)
+
+	assert.False(t, f.gapStore.WasActivated(f.game.GameID))
+}
+
+func TestRedeemRejectsInviterPermanentBlock(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	f.users.SetEligibility(ownerUserID, ports.Eligibility{
+		Exists:           true,
+		PermanentBlocked: true,
+	})
+	svc := newService(t, f)
+
+	_, err := svc.Handle(context.Background(), defaultInput(f, inv))
+	require.ErrorIs(t, err, shared.ErrSubjectNotFound)
+
+	updated, err := f.invites.Get(context.Background(), inv.InviteID)
+	require.NoError(t, err)
+	assert.Equal(t, invite.StatusCreated, updated.Status, "invite must remain unchanged on aborted redeem")
+}
+
+func TestRedeemRejectsInviteePermanentBlock(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	f.users.SetEligibility(inviteeUserID, ports.Eligibility{
+		Exists:           true,
+		PermanentBlocked: true,
+	})
+	svc := newService(t, f)
+
+	_, err := svc.Handle(context.Background(), defaultInput(f, inv))
+	require.ErrorIs(t, err, shared.ErrSubjectNotFound)
+}
+
+func TestRedeemRejectsDeletedInviter(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	f.users.SetEligibility(ownerUserID, ports.Eligibility{Exists: false})
+	svc := newService(t, f)
+
+	_, err := svc.Handle(context.Background(), defaultInput(f, inv))
+	require.ErrorIs(t, err, shared.ErrSubjectNotFound)
+}
+
+func TestRedeemSurfacesUserServiceTransportFailure(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	f.users.SetFailure(ownerUserID, ports.ErrUserServiceUnavailable)
+	svc := newService(t, f)
+
+	_, err := svc.Handle(context.Background(), defaultInput(f, inv))
+	require.ErrorIs(t, err, shared.ErrServiceUnavailable)
+}
+
+func TestRedeemActivatesGapAtMaxPlayers(t *testing.T) {
+	t.Parallel()
+	// max=2, gap=1; pre-seed 1 active member. Redeem pushes count to 2 (== max).
+	f := newFixture(t, 2, 1)
+	preexisting, err := membership.New(membership.NewMembershipInput{
+		MembershipID: "membership-pre",
+		GameID:       f.game.GameID,
+		UserID:       "user-pre",
+		RaceName:     "PriorMember",
+		CanonicalKey: "priormember",
+		Now:          f.now,
+	})
+	require.NoError(t, err)
+	require.NoError(t, f.memberships.Save(context.Background(), preexisting))
+
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	svc := newService(t, f)
+
+	_, err = svc.Handle(context.Background(), defaultInput(f, inv))
+	require.NoError(t, err)
+	assert.True(t, f.gapStore.WasActivated(f.game.GameID))
+	assert.Equal(t, f.now, f.gapStore.ActivatedAt(f.game.GameID))
+}
+
+func TestRedeemDoesNotActivateGapBelowMax(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	svc := newService(t, f)
+
+	_, err := svc.Handle(context.Background(), defaultInput(f, inv))
+	require.NoError(t, err)
+	assert.False(t, f.gapStore.WasActivated(f.game.GameID))
+}
+
+func TestRedeemAdminActorForbidden(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	svc := newService(t, f)
+
+	in := defaultInput(f, inv)
+	in.Actor = shared.NewAdminActor()
+
+	_, err := svc.Handle(context.Background(), in)
+	require.ErrorIs(t, err, shared.ErrForbidden)
+}
+
+func TestRedeemNonInviteeForbidden(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	svc := newService(t, f)
+
+	in := defaultInput(f, inv)
+	in.Actor = shared.NewUserActor("user-impostor")
+
+	_, err := svc.Handle(context.Background(), in)
+	require.ErrorIs(t, err, shared.ErrForbidden)
+}
+
+func TestRedeemInviteNotFound(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	svc := newService(t, f)
+
+	_, err := svc.Handle(context.Background(), redeeminvite.Input{
+		Actor:    shared.NewUserActor(inviteeUserID),
+		GameID:   f.game.GameID,
+		InviteID: "invite-missing",
+		RaceName: defaultRace,
+	})
+	require.ErrorIs(t, err, invite.ErrNotFound)
+}
+
+func TestRedeemCrossGameInviteNotFound(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	svc := newService(t, f)
+
+	in := defaultInput(f, inv)
+	in.GameID = "game-other"
+
+	_, err := svc.Handle(context.Background(), in)
+	require.ErrorIs(t, err, invite.ErrNotFound)
+}
+
+func TestRedeemAlreadyRedeemedConflict(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	require.NoError(t, f.invites.UpdateStatus(context.Background(), ports.UpdateInviteStatusInput{
+		InviteID:     inv.InviteID,
+		ExpectedFrom: invite.StatusCreated,
+		To:           invite.StatusDeclined,
+		At:           f.now,
+	}))
+
+	svc := newService(t, f)
+	_, err := svc.Handle(context.Background(), defaultInput(f, inv))
+	require.ErrorIs(t, err, invite.ErrConflict)
+}
+
+func TestRedeemGameNotEnrollmentOpenConflict(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+
+	rec, err := f.games.Get(context.Background(), f.game.GameID)
+	require.NoError(t, err)
+	rec.Status = game.StatusReadyToStart
+	require.NoError(t, f.games.Save(context.Background(), rec))
+
+	svc := newService(t, f)
+	_, err = svc.Handle(context.Background(), defaultInput(f, inv))
+	require.ErrorIs(t, err, game.ErrConflict)
+}
+
+func TestRedeemRosterFullConflict(t *testing.T) {
+	t.Parallel()
+	// Capacity = max(2) + gap(1) = 3; seed 3 active members.
+	f := newFixture(t, 2, 1)
+	for i := range 3 {
+		member, err := membership.New(membership.NewMembershipInput{
+			MembershipID: common.MembershipID("membership-seed-" + string(rune('a'+i))),
+			GameID:       f.game.GameID,
+			UserID:       "seed-user-" + string(rune('a'+i)),
+			RaceName:     "Seed " + string(rune('A'+i)),
+			CanonicalKey: "seed" + string(rune('a'+i)),
+			Now:          f.now,
+		})
+		require.NoError(t, err)
+		require.NoError(t, f.memberships.Save(context.Background(), member))
+	}
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	svc := newService(t, f)
+
+	_, err := svc.Handle(context.Background(), defaultInput(f, inv))
+	require.ErrorIs(t, err, game.ErrConflict)
+}
+
+func TestRedeemNameTakenByAnotherUser(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	require.NoError(t, f.directory.Reserve(context.Background(), "game-other", "user-other", defaultRace))
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	svc := newService(t, f)
+
+	_, err := svc.Handle(context.Background(), defaultInput(f, inv))
+	require.ErrorIs(t, err, ports.ErrNameTaken)
+}
+
+func TestRedeemInvalidRaceName(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	svc := newService(t, f)
+
+	in := defaultInput(f, inv)
+	in.RaceName = "   "
+
+	_, err := svc.Handle(context.Background(), in)
+	require.ErrorIs(t, err, ports.ErrInvalidName)
+}
+
+// redeemCASStub wraps invitestub.Store but injects ErrConflict on the next
+// UpdateStatus call so we can observe the rollback path.
+type redeemCASStub struct {
+	*invitestub.Store
+	failNext bool
+}
+
+func (s *redeemCASStub) UpdateStatus(ctx context.Context, input ports.UpdateInviteStatusInput) error {
+	if s.failNext {
+		s.failNext = false
+		return invite.ErrConflict
+	}
+	return s.Store.UpdateStatus(ctx, input)
+}
+
+func TestRedeemCASConflictReleasesReservation(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+
+	cas := &redeemCASStub{Store: f.invites, failNext: true}
+	svc, err := redeeminvite.NewService(redeeminvite.Dependencies{
+		Games:       f.games,
+		Invites:     cas,
+		Memberships: f.memberships,
+		Directory:   f.directory,
+		Users:       f.users,
+		GapStore:    f.gapStore,
+		Intents:     f.intents,
+		IDs:         f.ids,
+		Clock:       fixedClock(f.now),
+		Logger:      silentLogger(),
+	})
+	require.NoError(t, err)
+
+	_, err = svc.Handle(context.Background(), defaultInput(f, inv))
+	require.ErrorIs(t, err, invite.ErrConflict)
+
+	avail, err := f.directory.Check(context.Background(), defaultRace, "user-other")
+	require.NoError(t, err)
+	assert.False(t, avail.Taken, "reservation must be released after CAS failure")
+	assert.Empty(t, avail.HolderUserID)
+}
+
+func TestRedeemPublishFailureDoesNotRollback(t *testing.T) {
+	t.Parallel()
+	f := newFixture(t, 4, 1)
+	inv := seedCreatedInvite(t, f, "invite-1", inviteeUserID)
+	f.intents.SetError(errors.New("publish failed"))
+
+	svc := newService(t, f)
+	got, err := svc.Handle(context.Background(), defaultInput(f, inv))
+	require.NoError(t, err)
+	assert.Equal(t, common.MembershipID("membership-fixed"), got.MembershipID)
+
+	updated, err := f.invites.Get(context.Background(), inv.InviteID)
+	require.NoError(t, err)
+	assert.Equal(t, invite.StatusRedeemed, updated.Status)
+}