feat: add ranked season window policy

server/domain/rating.go

@@ -14,6 +14,7 @@ const (
 	GlickoInitialRating     = 1500.0
 	GlickoInitialRD         = 350.0
 	GlickoInitialVolatility = 0.06
+	RankedSeasonLength      = 12 * 7 * 24 * time.Hour
 )
 
 type Rating struct {
@@ -64,6 +65,24 @@ type RankedProfile struct {
 	SeasonHistory []string
 }
 
+type RankedSeason struct {
+	SeasonID     string
+	StartsAt     time.Time
+	EndsAt       time.Time
+	RolledOverAt time.Time
+}
+
+func NewRankedSeason(seasonID string, startsAt time.Time) (RankedSeason, error) {
+	if seasonID == "" || startsAt.IsZero() {
+		return RankedSeason{}, fmt.Errorf("invalid ranked season")
+	}
+	return RankedSeason{SeasonID: seasonID, StartsAt: startsAt, EndsAt: startsAt.Add(RankedSeasonLength)}, nil
+}
+
+func SeasonRolloverDue(season RankedSeason, now time.Time) bool {
+	return season.SeasonID != "" && !season.EndsAt.IsZero() && !now.Before(season.EndsAt) && season.RolledOverAt.IsZero()
+}
+
 func RankedIsProvisional(profile RankedProfile) bool { return profile.RankedGames < 10 }
 
 // ApplySeasonRollover is idempotent by season ID. It intentionally accepts a

server/domain/season_test.go

@@ -1,6 +1,9 @@
 package domain
 
-import "testing"
+import (
+	"testing"
+	"time"
+)
 
 func TestRankedProvisionalBoundaryIsFirstTenGames(t *testing.T) {
 	for games := 0; games < 10; games++ {
@@ -57,3 +60,18 @@ func TestCasualRatingHasNoSeasonOperation(t *testing.T) {
 		t.Fatal("casual boundary test fixture unexpectedly provisional")
 	}
 }
+
+func TestRankedSeasonWindowIsExactlyTwelveWeeksAndDueIsIdempotent(t *testing.T) {
+	start := time.Unix(1000, 0)
+	season, err := NewRankedSeason("season-1", start)
+	if err != nil || season.EndsAt.Sub(start) != RankedSeasonLength {
+		t.Fatalf("season = %+v err=%v", season, err)
+	}
+	if SeasonRolloverDue(season, season.EndsAt.Add(-time.Nanosecond)) || !SeasonRolloverDue(season, season.EndsAt) {
+		t.Fatal("season due boundary is wrong")
+	}
+	season.RolledOverAt = season.EndsAt
+	if SeasonRolloverDue(season, season.EndsAt.Add(time.Hour)) {
+		t.Fatal("completed season remained due")
+	}
+}