refactor

core/racing/domain/entities/season/Season.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+  RacingDomainInvariantError,
+  RacingDomainValidationError,
+} from '@core/racing/domain/errors/RacingDomainError';
+
+import { SeasonScoringConfig } from '@core/racing/domain/value-objects/SeasonScoringConfig';
+import {
+  SeasonDropPolicy,
+} from '@core/racing/domain/value-objects/SeasonDropPolicy';
+import { SeasonStewardingConfig } from '@core/racing/domain/value-objects/SeasonStewardingConfig';
+import { createMinimalSeason, createBaseSeason } from '../../../../../testing/factories/racing/SeasonFactory';
+
+
+describe('Season aggregate lifecycle', () => {
+  it('transitions Planned → Active → Completed → Archived with timestamps', () => {
+    const planned = createMinimalSeason({ status: 'planned' });
+
+    const activated = planned.activate();
+    expect(activated.status).toBe('active');
+    expect(activated.startDate).toBeInstanceOf(Date);
+    expect(activated.endDate).toBeUndefined();
+
+    const completed = activated.complete();
+    expect(completed.status).toBe('completed');
+    expect(completed.startDate).toEqual(activated.startDate);
+    expect(completed.endDate).toBeInstanceOf(Date);
+
+    const archived = completed.archive();
+    expect(archived.status).toBe('archived');
+    expect(archived.startDate).toEqual(completed.startDate);
+    expect(archived.endDate).toEqual(completed.endDate);
+  });
+
+  it('throws when activating a non-planned season', () => {
+    const active = createMinimalSeason({ status: 'active' });
+    const completed = createMinimalSeason({ status: 'completed' });
+    const archived = createMinimalSeason({ status: 'archived' });
+    const cancelled = createMinimalSeason({ status: 'cancelled' });
+
+    expect(() => active.activate()).toThrow(RacingDomainInvariantError);
+    expect(() => completed.activate()).toThrow(RacingDomainInvariantError);
+    expect(() => archived.activate()).toThrow(RacingDomainInvariantError);
+    expect(() => cancelled.activate()).toThrow(RacingDomainInvariantError);
+  });
+
+  it('throws when completing a non-active season', () => {
+    const planned = createMinimalSeason({ status: 'planned' });
+    const completed = createMinimalSeason({ status: 'completed' });
+    const archived = createMinimalSeason({ status: 'archived' });
+    const cancelled = createMinimalSeason({ status: 'cancelled' });
+
+    expect(() => planned.complete()).toThrow(RacingDomainInvariantError);
+    expect(() => completed.complete()).toThrow(RacingDomainInvariantError);
+    expect(() => archived.complete()).toThrow(RacingDomainInvariantError);
+    expect(() => cancelled.complete()).toThrow(RacingDomainInvariantError);
+  });
+
+  it('throws when archiving a non-completed season', () => {
+    const planned = createMinimalSeason({ status: 'planned' });
+    const active = createMinimalSeason({ status: 'active' });
+    const archived = createMinimalSeason({ status: 'archived' });
+    const cancelled = createMinimalSeason({ status: 'cancelled' });
+
+    expect(() => planned.archive()).toThrow(RacingDomainInvariantError);
+    expect(() => active.archive()).toThrow(RacingDomainInvariantError);
+    expect(() => archived.archive()).toThrow(RacingDomainInvariantError);
+    expect(() => cancelled.archive()).toThrow(RacingDomainInvariantError);
+  });
+
+  it('allows cancelling planned or active seasons and rejects completed/archived', () => {
+    const planned = createMinimalSeason({ status: 'planned' });
+    const active = createMinimalSeason({ status: 'active' });
+    const completed = createMinimalSeason({ status: 'completed' });
+    const archived = createMinimalSeason({ status: 'archived' });
+
+    const cancelledFromPlanned = planned.cancel();
+    expect(cancelledFromPlanned.status).toBe('cancelled');
+    expect(cancelledFromPlanned.startDate).toBe(planned.startDate);
+    expect(cancelledFromPlanned.endDate).toBeInstanceOf(Date);
+
+    const cancelledFromActive = active.cancel();
+    expect(cancelledFromActive.status).toBe('cancelled');
+    expect(cancelledFromActive.startDate).toBe(active.startDate);
+    expect(cancelledFromActive.endDate).toBeInstanceOf(Date);
+
+    expect(() => completed.cancel()).toThrow(RacingDomainInvariantError);
+    expect(() => archived.cancel()).toThrow(RacingDomainInvariantError);
+  });
+
+  it('cancel is idempotent for already cancelled seasons', () => {
+    const planned = createMinimalSeason({ status: 'planned' });
+    const cancelled = planned.cancel();
+
+    const cancelledAgain = cancelled.cancel();
+    expect(cancelledAgain).toBe(cancelled);
+  });
+
+  it('canWithdrawFromWallet only when completed', () => {
+    const planned = createMinimalSeason({ status: 'planned' });
+    const active = createMinimalSeason({ status: 'active' });
+    const completed = createMinimalSeason({ status: 'completed' });
+    const archived = createMinimalSeason({ status: 'archived' });
+    const cancelled = createMinimalSeason({ status: 'cancelled' });
+
+    expect(planned.canWithdrawFromWallet()).toBe(false);
+    expect(active.canWithdrawFromWallet()).toBe(false);
+    expect(completed.canWithdrawFromWallet()).toBe(true);
+    expect(archived.canWithdrawFromWallet()).toBe(false);
+    expect(cancelled.canWithdrawFromWallet()).toBe(false);
+  });
+});
+
+describe('Season configuration updates', () => {
+
+  it('withScoringConfig returns a new Season with updated scoringConfig only', () => {
+    const season = createBaseSeason();
+    const scoringConfig = new SeasonScoringConfig({
+      scoringPresetId: 'sprint-main-driver',
+      customScoringEnabled: true,
+    });
+
+    const updated = season.withScoringConfig(scoringConfig);
+
+    expect(updated).not.toBe(season);
+    expect(updated.scoringConfig).toBe(scoringConfig);
+    expect(updated.schedule).toBe(season.schedule);
+    expect(updated.dropPolicy).toBe(season.dropPolicy);
+    expect(updated.stewardingConfig).toBe(season.stewardingConfig);
+    expect(updated.maxDrivers).toBe(season.maxDrivers);
+  });
+
+  it('withDropPolicy returns a new Season with updated dropPolicy only', () => {
+    const season = createBaseSeason();
+    const dropPolicy = new SeasonDropPolicy({
+      strategy: 'bestNResults',
+      n: 3,
+    });
+
+    const updated = season.withDropPolicy(dropPolicy);
+
+    expect(updated).not.toBe(season);
+    expect(updated.dropPolicy).toBe(dropPolicy);
+    expect(updated.scoringConfig).toBe(season.scoringConfig);
+    expect(updated.schedule).toBe(season.schedule);
+    expect(updated.stewardingConfig).toBe(season.stewardingConfig);
+    expect(updated.maxDrivers).toBe(season.maxDrivers);
+  });
+
+  it('withStewardingConfig returns a new Season with updated stewardingConfig only', () => {
+    const season = createBaseSeason();
+    const stewardingConfig = new SeasonStewardingConfig({
+      decisionMode: 'steward_vote',
+      requiredVotes: 3,
+      requireDefense: true,
+      defenseTimeLimit: 24,
+      voteTimeLimit: 24,
+      protestDeadlineHours: 48,
+      stewardingClosesHours: 72,
+      notifyAccusedOnProtest: true,
+      notifyOnVoteRequired: true,
+    });
+
+    const updated = season.withStewardingConfig(stewardingConfig);
+
+    expect(updated).not.toBe(season);
+    expect(updated.stewardingConfig).toBe(stewardingConfig);
+    expect(updated.scoringConfig).toBe(season.scoringConfig);
+    expect(updated.schedule).toBe(season.schedule);
+    expect(updated.dropPolicy).toBe(season.dropPolicy);
+    expect(updated.maxDrivers).toBe(season.maxDrivers);
+  });
+
+  it('withMaxDrivers updates maxDrivers when positive', () => {
+    const season = createBaseSeason();
+
+    const updated = season.withMaxDrivers(30);
+
+    expect(updated.maxDrivers).toBe(30);
+    expect(updated.id).toBe(season.id);
+    expect(updated.leagueId).toBe(season.leagueId);
+    expect(updated.gameId).toBe(season.gameId);
+  });
+
+  it('withMaxDrivers allows undefined to clear value', () => {
+    const season = createBaseSeason();
+
+    const updated = season.withMaxDrivers(undefined);
+
+    expect(updated.maxDrivers).toBeUndefined();
+  });
+
+  it('withMaxDrivers rejects non-positive values', () => {
+    const season = createBaseSeason();
+
+    expect(() => season.withMaxDrivers(0)).toThrow(
+      RacingDomainValidationError,
+    );
+    expect(() => season.withMaxDrivers(-5)).toThrow(
+      RacingDomainValidationError,
+    );
+  });
+});
+
+

core/racing/domain/entities/season/Season.ts

@@ -0,0 +1,419 @@
+export type SeasonStatus =
+  | 'planned'
+  | 'active'
+  | 'completed'
+  | 'archived'
+  | 'cancelled';
+
+import {
+  RacingDomainInvariantError,
+  RacingDomainValidationError,
+} from '../../errors/RacingDomainError';
+import type { IEntity } from '@core/shared/domain';
+import type { SeasonSchedule } from '../../value-objects/SeasonSchedule';
+import type { SeasonScoringConfig } from '../../value-objects/SeasonScoringConfig';
+import type { SeasonDropPolicy } from '../../value-objects/SeasonDropPolicy';
+import type { SeasonStewardingConfig } from '../../value-objects/SeasonStewardingConfig';
+
+export class Season implements IEntity<string> {
+  readonly id: string;
+  readonly leagueId: string;
+  readonly gameId: string;
+  readonly name: string;
+  readonly year: number | undefined;
+  readonly order: number | undefined;
+  readonly status: SeasonStatus;
+  readonly startDate: Date | undefined;
+  readonly endDate: Date | undefined;
+  readonly schedule: SeasonSchedule | undefined;
+  readonly scoringConfig: SeasonScoringConfig | undefined;
+  readonly dropPolicy: SeasonDropPolicy | undefined;
+  readonly stewardingConfig: SeasonStewardingConfig | undefined;
+  readonly maxDrivers: number | undefined;
+
+  private constructor(props: {
+    id: string;
+    leagueId: string;
+    gameId: string;
+    name: string;
+    year?: number;
+    order?: number;
+    status: SeasonStatus;
+    startDate?: Date;
+    endDate?: Date;
+    schedule?: SeasonSchedule;
+    scoringConfig?: SeasonScoringConfig;
+    dropPolicy?: SeasonDropPolicy;
+    stewardingConfig?: SeasonStewardingConfig;
+    maxDrivers?: number;
+  }) {
+    this.id = props.id;
+    this.leagueId = props.leagueId;
+    this.gameId = props.gameId;
+    this.name = props.name;
+    this.year = props.year;
+    this.order = props.order;
+    this.status = props.status;
+    this.startDate = props.startDate;
+    this.endDate = props.endDate;
+    this.schedule = props.schedule;
+    this.scoringConfig = props.scoringConfig;
+    this.dropPolicy = props.dropPolicy;
+    this.stewardingConfig = props.stewardingConfig;
+    this.maxDrivers = props.maxDrivers;
+  }
+
+  static create(props: {
+    id: string;
+    leagueId: string;
+    gameId: string;
+    name: string;
+    year?: number;
+    order?: number;
+    status?: SeasonStatus;
+    startDate?: Date;
+    endDate?: Date | undefined;
+    schedule?: SeasonSchedule;
+    scoringConfig?: SeasonScoringConfig;
+    dropPolicy?: SeasonDropPolicy;
+    stewardingConfig?: SeasonStewardingConfig;
+    maxDrivers?: number;
+  }): Season {
+    if (!props.id || props.id.trim().length === 0) {
+      throw new RacingDomainValidationError('Season ID is required');
+    }
+
+    if (!props.leagueId || props.leagueId.trim().length === 0) {
+      throw new RacingDomainValidationError('Season leagueId is required');
+    }
+
+    if (!props.gameId || props.gameId.trim().length === 0) {
+      throw new RacingDomainValidationError('Season gameId is required');
+    }
+
+    if (!props.name || props.name.trim().length === 0) {
+      throw new RacingDomainValidationError('Season name is required');
+    }
+
+    const status: SeasonStatus = props.status ?? 'planned';
+
+    return new Season({
+      id: props.id,
+      leagueId: props.leagueId,
+      gameId: props.gameId,
+      name: props.name,
+      ...(props.year !== undefined ? { year: props.year } : {}),
+      ...(props.order !== undefined ? { order: props.order } : {}),
+      status,
+      ...(props.startDate !== undefined ? { startDate: props.startDate } : {}),
+      ...(props.endDate !== undefined ? { endDate: props.endDate } : {}),
+      ...(props.schedule !== undefined ? { schedule: props.schedule } : {}),
+      ...(props.scoringConfig !== undefined
+        ? { scoringConfig: props.scoringConfig }
+        : {}),
+      ...(props.dropPolicy !== undefined ? { dropPolicy: props.dropPolicy } : {}),
+      ...(props.stewardingConfig !== undefined
+        ? { stewardingConfig: props.stewardingConfig }
+        : {}),
+      ...(props.maxDrivers !== undefined ? { maxDrivers: props.maxDrivers } : {}),
+    });
+  }
+
+  /**
+   * Domain rule: Wallet withdrawals are only allowed when season is completed
+   */
+  canWithdrawFromWallet(): boolean {
+    return this.status === 'completed';
+  }
+
+  /**
+   * Check if season is active
+   */
+  isActive(): boolean {
+    return this.status === 'active';
+  }
+
+  /**
+   * Check if season is completed
+   */
+  isCompleted(): boolean {
+    return this.status === 'completed';
+  }
+
+  /**
+   * Check if season is planned (not yet active)
+   */
+  isPlanned(): boolean {
+    return this.status === 'planned';
+  }
+
+  /**
+   * Activate the season from planned state.
+   */
+  activate(): Season {
+    if (this.status !== 'planned') {
+      throw new RacingDomainInvariantError(
+        'Only planned seasons can be activated',
+      );
+    }
+
+    return Season.create({
+      id: this.id,
+      leagueId: this.leagueId,
+      gameId: this.gameId,
+      name: this.name,
+      ...(this.year !== undefined ? { year: this.year } : {}),
+      ...(this.order !== undefined ? { order: this.order } : {}),
+      status: 'active',
+      ...(this.startDate !== undefined ? { startDate: this.startDate } : {
+        startDate: new Date(),
+      }),
+      ...(this.endDate !== undefined ? { endDate: this.endDate } : {}),
+      ...(this.schedule !== undefined ? { schedule: this.schedule } : {}),
+      ...(this.scoringConfig !== undefined
+        ? { scoringConfig: this.scoringConfig }
+        : {}),
+      ...(this.dropPolicy !== undefined ? { dropPolicy: this.dropPolicy } : {}),
+      ...(this.stewardingConfig !== undefined
+        ? { stewardingConfig: this.stewardingConfig }
+        : {}),
+      ...(this.maxDrivers !== undefined ? { maxDrivers: this.maxDrivers } : {}),
+    });
+  }
+
+  /**
+   * Mark the season as completed.
+   */
+  complete(): Season {
+    if (this.status !== 'active') {
+      throw new RacingDomainInvariantError(
+        'Only active seasons can be completed',
+      );
+    }
+
+    return Season.create({
+      id: this.id,
+      leagueId: this.leagueId,
+      gameId: this.gameId,
+      name: this.name,
+      ...(this.year !== undefined ? { year: this.year } : {}),
+      ...(this.order !== undefined ? { order: this.order } : {}),
+      status: 'completed',
+      ...(this.startDate !== undefined ? { startDate: this.startDate } : {}),
+      ...(this.endDate !== undefined ? { endDate: this.endDate } : {
+        endDate: new Date(),
+      }),
+      ...(this.schedule !== undefined ? { schedule: this.schedule } : {}),
+      ...(this.scoringConfig !== undefined
+        ? { scoringConfig: this.scoringConfig }
+        : {}),
+      ...(this.dropPolicy !== undefined ? { dropPolicy: this.dropPolicy } : {}),
+      ...(this.stewardingConfig !== undefined
+        ? { stewardingConfig: this.stewardingConfig }
+        : {}),
+      ...(this.maxDrivers !== undefined ? { maxDrivers: this.maxDrivers } : {}),
+    });
+  }
+
+  /**
+   * Archive a completed season.
+   */
+  archive(): Season {
+    if (!this.isCompleted()) {
+      throw new RacingDomainInvariantError(
+        'Only completed seasons can be archived',
+      );
+    }
+
+    return Season.create({
+      id: this.id,
+      leagueId: this.leagueId,
+      gameId: this.gameId,
+      name: this.name,
+      ...(this.year !== undefined ? { year: this.year } : {}),
+      ...(this.order !== undefined ? { order: this.order } : {}),
+      status: 'archived',
+      ...(this.startDate !== undefined ? { startDate: this.startDate } : {}),
+      ...(this.endDate !== undefined ? { endDate: this.endDate } : {}),
+      ...(this.schedule !== undefined ? { schedule: this.schedule } : {}),
+      ...(this.scoringConfig !== undefined
+        ? { scoringConfig: this.scoringConfig }
+        : {}),
+      ...(this.dropPolicy !== undefined ? { dropPolicy: this.dropPolicy } : {}),
+      ...(this.stewardingConfig !== undefined
+        ? { stewardingConfig: this.stewardingConfig }
+        : {}),
+      ...(this.maxDrivers !== undefined ? { maxDrivers: this.maxDrivers } : {}),
+    });
+  }
+
+  /**
+   * Cancel a planned or active season.
+   */
+  cancel(): Season {
+    if (this.status === 'completed' || this.status === 'archived') {
+      throw new RacingDomainInvariantError(
+        'Cannot cancel a completed or archived season',
+      );
+    }
+
+    if (this.status === 'cancelled') {
+      return this;
+    }
+
+    return Season.create({
+      id: this.id,
+      leagueId: this.leagueId,
+      gameId: this.gameId,
+      name: this.name,
+      ...(this.year !== undefined ? { year: this.year } : {}),
+      ...(this.order !== undefined ? { order: this.order } : {}),
+      status: 'cancelled',
+      ...(this.startDate !== undefined ? { startDate: this.startDate } : {}),
+      ...(this.endDate !== undefined ? { endDate: this.endDate } : {
+        endDate: new Date(),
+      }),
+      ...(this.schedule !== undefined ? { schedule: this.schedule } : {}),
+      ...(this.scoringConfig !== undefined
+        ? { scoringConfig: this.scoringConfig }
+        : {}),
+      ...(this.dropPolicy !== undefined ? { dropPolicy: this.dropPolicy } : {}),
+      ...(this.stewardingConfig !== undefined
+        ? { stewardingConfig: this.stewardingConfig }
+        : {}),
+      ...(this.maxDrivers !== undefined ? { maxDrivers: this.maxDrivers } : {}),
+    });
+  }
+
+  /**
+   * Update schedule while keeping other properties intact.
+   */
+  withSchedule(schedule: SeasonSchedule): Season {
+    return Season.create({
+      id: this.id,
+      leagueId: this.leagueId,
+      gameId: this.gameId,
+      name: this.name,
+      ...(this.year !== undefined ? { year: this.year } : {}),
+      ...(this.order !== undefined ? { order: this.order } : {}),
+      status: this.status,
+      ...(this.startDate !== undefined ? { startDate: this.startDate } : {}),
+      ...(this.endDate !== undefined ? { endDate: this.endDate } : {}),
+      schedule,
+      ...(this.scoringConfig !== undefined
+        ? { scoringConfig: this.scoringConfig }
+        : {}),
+      ...(this.dropPolicy !== undefined ? { dropPolicy: this.dropPolicy } : {}),
+      ...(this.stewardingConfig !== undefined
+        ? { stewardingConfig: this.stewardingConfig }
+        : {}),
+      ...(this.maxDrivers !== undefined ? { maxDrivers: this.maxDrivers } : {}),
+    });
+  }
+
+  /**
+   * Update scoring configuration for the season.
+   */
+  withScoringConfig(scoringConfig: SeasonScoringConfig): Season {
+    return Season.create({
+      id: this.id,
+      leagueId: this.leagueId,
+      gameId: this.gameId,
+      name: this.name,
+      ...(this.year !== undefined ? { year: this.year } : {}),
+      ...(this.order !== undefined ? { order: this.order } : {}),
+      status: this.status,
+      ...(this.startDate !== undefined ? { startDate: this.startDate } : {}),
+      ...(this.endDate !== undefined ? { endDate: this.endDate } : {}),
+      ...(this.schedule !== undefined ? { schedule: this.schedule } : {}),
+      scoringConfig,
+      ...(this.dropPolicy !== undefined ? { dropPolicy: this.dropPolicy } : {}),
+      ...(this.stewardingConfig !== undefined
+        ? { stewardingConfig: this.stewardingConfig }
+        : {}),
+      ...(this.maxDrivers !== undefined ? { maxDrivers: this.maxDrivers } : {}),
+    });
+  }
+
+  /**
+   * Update drop policy for the season.
+   */
+  withDropPolicy(dropPolicy: SeasonDropPolicy): Season {
+    return Season.create({
+      id: this.id,
+      leagueId: this.leagueId,
+      gameId: this.gameId,
+      name: this.name,
+      ...(this.year !== undefined ? { year: this.year } : {}),
+      ...(this.order !== undefined ? { order: this.order } : {}),
+      status: this.status,
+      ...(this.startDate !== undefined ? { startDate: this.startDate } : {}),
+      ...(this.endDate !== undefined ? { endDate: this.endDate } : {}),
+      ...(this.schedule !== undefined ? { schedule: this.schedule } : {}),
+      ...(this.scoringConfig !== undefined
+        ? { scoringConfig: this.scoringConfig }
+        : {}),
+      dropPolicy,
+      ...(this.stewardingConfig !== undefined
+        ? { stewardingConfig: this.stewardingConfig }
+        : {}),
+      ...(this.maxDrivers !== undefined ? { maxDrivers: this.maxDrivers } : {}),
+    });
+  }
+
+  /**
+   * Update stewarding configuration for the season.
+   */
+  withStewardingConfig(stewardingConfig: SeasonStewardingConfig): Season {
+    return Season.create({
+      id: this.id,
+      leagueId: this.leagueId,
+      gameId: this.gameId,
+      name: this.name,
+      ...(this.year !== undefined ? { year: this.year } : {}),
+      ...(this.order !== undefined ? { order: this.order } : {}),
+      status: this.status,
+      ...(this.startDate !== undefined ? { startDate: this.startDate } : {}),
+      ...(this.endDate !== undefined ? { endDate: this.endDate } : {}),
+      ...(this.schedule !== undefined ? { schedule: this.schedule } : {}),
+      ...(this.scoringConfig !== undefined
+        ? { scoringConfig: this.scoringConfig }
+        : {}),
+      ...(this.dropPolicy !== undefined ? { dropPolicy: this.dropPolicy } : {}),
+      stewardingConfig,
+      ...(this.maxDrivers !== undefined ? { maxDrivers: this.maxDrivers } : {}),
+    });
+  }
+
+  /**
+   * Update max driver capacity for the season.
+   */
+  withMaxDrivers(maxDrivers: number | undefined): Season {
+    if (maxDrivers !== undefined && maxDrivers <= 0) {
+      throw new RacingDomainValidationError(
+        'Season maxDrivers must be greater than 0 when provided',
+      );
+    }
+
+    return Season.create({
+      id: this.id,
+      leagueId: this.leagueId,
+      gameId: this.gameId,
+      name: this.name,
+      ...(this.year !== undefined ? { year: this.year } : {}),
+      ...(this.order !== undefined ? { order: this.order } : {}),
+      status: this.status,
+      ...(this.startDate !== undefined ? { startDate: this.startDate } : {}),
+      ...(this.endDate !== undefined ? { endDate: this.endDate } : {}),
+      ...(this.schedule !== undefined ? { schedule: this.schedule } : {}),
+      ...(this.scoringConfig !== undefined
+        ? { scoringConfig: this.scoringConfig }
+        : {}),
+      ...(this.dropPolicy !== undefined ? { dropPolicy: this.dropPolicy } : {}),
+      ...(this.stewardingConfig !== undefined
+        ? { stewardingConfig: this.stewardingConfig }
+        : {}),
+      ...(maxDrivers !== undefined ? { maxDrivers } : {}),
+    });
+  }
+}

core/racing/domain/entities/season/SeasonId.ts

@@ -0,0 +1,20 @@
+import { RacingDomainValidationError } from '../../errors/RacingDomainError';
+
+export class SeasonId {
+  private constructor(private readonly value: string) {}
+
+  static create(value: string): SeasonId {
+    if (!value || value.trim().length === 0) {
+      throw new RacingDomainValidationError('Season ID cannot be empty');
+    }
+    return new SeasonId(value.trim());
+  }
+
+  toString(): string {
+    return this.value;
+  }
+
+  equals(other: SeasonId): boolean {
+    return this.value === other.value;
+  }
+}

core/racing/domain/entities/season/SeasonSponsorship.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+  RacingDomainInvariantError,
+  RacingDomainValidationError,
+} from '../../errors/RacingDomainError';
+
+import { SeasonSponsorship } from './SeasonSponsorship';
+import { Money } from '../../value-objects/Money';
+
+describe('SeasonSponsorship', () => {
+  const validProps = {
+    id: 'sponsorship-1',
+    seasonId: 'season-1',
+    sponsorId: 'sponsor-1',
+    tier: 'main' as const,
+    pricing: Money.create(1000),
+    status: 'pending' as const,
+    createdAt: new Date(),
+  };
+
+  it('creates a valid SeasonSponsorship', () => {
+    const sponsorship = SeasonSponsorship.create(validProps);
+    expect(sponsorship.id).toBe('sponsorship-1');
+    expect(sponsorship.seasonId).toBe('season-1');
+    expect(sponsorship.sponsorId).toBe('sponsor-1');
+    expect(sponsorship.tier).toBe('main');
+    expect(sponsorship.status).toBe('pending');
+  });
+
+  it('throws on invalid id', () => {
+    expect(() => SeasonSponsorship.create({ ...validProps, id: '' })).toThrow(RacingDomainValidationError);
+  });
+
+  it('throws on invalid seasonId', () => {
+    expect(() => SeasonSponsorship.create({ ...validProps, seasonId: '' })).toThrow(RacingDomainValidationError);
+  });
+
+  it('throws on invalid sponsorId', () => {
+    expect(() => SeasonSponsorship.create({ ...validProps, sponsorId: '' })).toThrow(RacingDomainValidationError);
+  });
+
+  it('throws on invalid pricing', () => {
+    expect(() => SeasonSponsorship.create({ ...validProps, pricing: Money.create(0) })).toThrow(RacingDomainValidationError);
+  });
+
+  it('activates from pending', () => {
+    const sponsorship = SeasonSponsorship.create(validProps);
+    const activated = sponsorship.activate();
+    expect(activated.status).toBe('active');
+    expect(activated.activatedAt).toBeInstanceOf(Date);
+  });
+
+  it('throws when activating active sponsorship', () => {
+    const active = SeasonSponsorship.create({ ...validProps, status: 'active' });
+    expect(() => active.activate()).toThrow(RacingDomainInvariantError);
+  });
+
+  it('ends active sponsorship', () => {
+    const active = SeasonSponsorship.create({ ...validProps, status: 'active' });
+    const ended = active.end();
+    expect(ended.status).toBe('ended');
+    expect(ended.endedAt).toBeInstanceOf(Date);
+  });
+
+  it('cancels pending sponsorship', () => {
+    const sponsorship = SeasonSponsorship.create(validProps);
+    const cancelled = sponsorship.cancel();
+    expect(cancelled.status).toBe('cancelled');
+    expect(cancelled.cancelledAt).toBeInstanceOf(Date);
+  });
+
+  it('isActive returns true for active status', () => {
+    const active = SeasonSponsorship.create({ ...validProps, status: 'active' });
+    expect(active.isActive()).toBe(true);
+  });
+
+  it('calculates platform fee', () => {
+    const sponsorship = SeasonSponsorship.create(validProps);
+    const fee = sponsorship.getPlatformFee();
+    expect(fee.amount).toBe(100);
+  });
+
+  it('calculates net amount', () => {
+    const sponsorship = SeasonSponsorship.create(validProps);
+    const net = sponsorship.getNetAmount();
+    expect(net.amount).toBe(900);
+  });
+});

core/racing/domain/entities/season/SeasonSponsorship.ts

@@ -0,0 +1,268 @@
+/**
+ * Domain Entity: SeasonSponsorship
+ *
+ * Represents a sponsorship relationship between a Sponsor and a Season.
+ * Aggregate root for managing sponsorship slots and pricing.
+ */
+ 
+import { RacingDomainValidationError, RacingDomainInvariantError } from '../../errors/RacingDomainError';
+import type { IEntity } from '@core/shared/domain';
+
+import type { Money } from '../../value-objects/Money';
+
+export type SponsorshipTier = 'main' | 'secondary';
+export type SponsorshipStatus = 'pending' | 'active' | 'ended' | 'cancelled';
+
+export interface SeasonSponsorshipProps {
+  id: string;
+  seasonId: string;
+  /**
+   * Optional denormalized leagueId for fast league-level aggregations.
+   * Must always match the owning Season's leagueId when present.
+   */
+  leagueId?: string;
+  sponsorId: string;
+  tier: SponsorshipTier;
+  pricing: Money;
+  status: SponsorshipStatus;
+  createdAt: Date;
+  activatedAt?: Date;
+  endedAt?: Date;
+  cancelledAt?: Date;
+  description?: string;
+}
+
+export class SeasonSponsorship implements IEntity<string> {
+  readonly id: string;
+  readonly seasonId: string;
+  readonly leagueId: string | undefined;
+  readonly sponsorId: string;
+  readonly tier: SponsorshipTier;
+  readonly pricing: Money;
+  readonly status: SponsorshipStatus;
+  readonly createdAt: Date;
+  readonly activatedAt: Date | undefined;
+  readonly endedAt: Date | undefined;
+  readonly cancelledAt: Date | undefined;
+  readonly description: string | undefined;
+
+  private constructor(props: SeasonSponsorshipProps) {
+    this.id = props.id;
+    this.seasonId = props.seasonId;
+    this.leagueId = props.leagueId;
+    this.sponsorId = props.sponsorId;
+    this.tier = props.tier;
+    this.pricing = props.pricing;
+    this.status = props.status;
+    this.createdAt = props.createdAt;
+    this.activatedAt = props.activatedAt;
+    this.endedAt = props.endedAt;
+    this.cancelledAt = props.cancelledAt;
+    this.description = props.description;
+  }
+
+  static create(props: Omit<SeasonSponsorshipProps, 'createdAt' | 'status'> & {
+    createdAt?: Date;
+    status?: SponsorshipStatus;
+  }): SeasonSponsorship {
+    this.validate(props);
+
+    return new SeasonSponsorship({
+      id: props.id,
+      seasonId: props.seasonId,
+      ...(props.leagueId !== undefined ? { leagueId: props.leagueId } : {}),
+      sponsorId: props.sponsorId,
+      tier: props.tier,
+      pricing: props.pricing,
+      status: props.status ?? 'pending',
+      createdAt: props.createdAt ?? new Date(),
+      ...(props.activatedAt !== undefined ? { activatedAt: props.activatedAt } : {}),
+      ...(props.endedAt !== undefined ? { endedAt: props.endedAt } : {}),
+      ...(props.cancelledAt !== undefined ? { cancelledAt: props.cancelledAt } : {}),
+      ...(props.description !== undefined ? { description: props.description } : {}),
+    });
+  }
+
+  private static validate(props: Omit<SeasonSponsorshipProps, 'createdAt' | 'status'>): void {
+    if (!props.id || props.id.trim().length === 0) {
+      throw new RacingDomainValidationError('SeasonSponsorship ID is required');
+    }
+
+    if (!props.seasonId || props.seasonId.trim().length === 0) {
+      throw new RacingDomainValidationError('SeasonSponsorship seasonId is required');
+    }
+
+    if (!props.sponsorId || props.sponsorId.trim().length === 0) {
+      throw new RacingDomainValidationError('SeasonSponsorship sponsorId is required');
+    }
+
+    if (!props.tier) {
+      throw new RacingDomainValidationError('SeasonSponsorship tier is required');
+    }
+
+    if (!props.pricing) {
+      throw new RacingDomainValidationError('SeasonSponsorship pricing is required');
+    }
+
+    if (props.pricing.amount <= 0) {
+      throw new RacingDomainValidationError('SeasonSponsorship pricing must be greater than zero');
+    }
+  }
+
+  /**
+   * Activate the sponsorship
+   */
+  activate(): SeasonSponsorship {
+    if (this.status === 'active') {
+      throw new RacingDomainInvariantError('SeasonSponsorship is already active');
+    }
+
+    if (this.status === 'cancelled') {
+      throw new RacingDomainInvariantError('Cannot activate a cancelled SeasonSponsorship');
+    }
+
+    if (this.status === 'ended') {
+      throw new RacingDomainInvariantError('Cannot activate an ended SeasonSponsorship');
+    }
+
+    const base: SeasonSponsorshipProps = {
+      id: this.id,
+      seasonId: this.seasonId,
+      ...(this.leagueId !== undefined ? { leagueId: this.leagueId } : {}),
+      sponsorId: this.sponsorId,
+      tier: this.tier,
+      pricing: this.pricing,
+      status: 'active',
+      createdAt: this.createdAt,
+      activatedAt: new Date(),
+      ...(this.endedAt !== undefined ? { endedAt: this.endedAt } : {}),
+      ...(this.cancelledAt !== undefined ? { cancelledAt: this.cancelledAt } : {}),
+    };
+
+    const next: SeasonSponsorshipProps =
+      this.description !== undefined
+        ? { ...base, description: this.description }
+        : base;
+
+    return new SeasonSponsorship(next);
+  }
+
+  /**
+   * Mark the sponsorship as ended (completed term)
+   */
+  end(): SeasonSponsorship {
+    if (this.status === 'cancelled') {
+      throw new RacingDomainInvariantError('Cannot end a cancelled SeasonSponsorship');
+    }
+
+    if (this.status === 'ended') {
+      throw new RacingDomainInvariantError('SeasonSponsorship is already ended');
+    }
+
+    const base: SeasonSponsorshipProps = {
+      id: this.id,
+      seasonId: this.seasonId,
+      ...(this.leagueId !== undefined ? { leagueId: this.leagueId } : {}),
+      sponsorId: this.sponsorId,
+      tier: this.tier,
+      pricing: this.pricing,
+      status: 'ended',
+      createdAt: this.createdAt,
+      ...(this.activatedAt !== undefined ? { activatedAt: this.activatedAt } : {}),
+      endedAt: new Date(),
+      ...(this.cancelledAt !== undefined ? { cancelledAt: this.cancelledAt } : {}),
+    };
+
+    const next: SeasonSponsorshipProps =
+      this.description !== undefined
+        ? { ...base, description: this.description }
+        : base;
+
+    return new SeasonSponsorship(next);
+  }
+
+  /**
+   * Cancel the sponsorship
+   */
+  cancel(): SeasonSponsorship {
+    if (this.status === 'cancelled') {
+      throw new RacingDomainInvariantError('SeasonSponsorship is already cancelled');
+    }
+
+    const base: SeasonSponsorshipProps = {
+      id: this.id,
+      seasonId: this.seasonId,
+      ...(this.leagueId !== undefined ? { leagueId: this.leagueId } : {}),
+      sponsorId: this.sponsorId,
+      tier: this.tier,
+      pricing: this.pricing,
+      status: 'cancelled',
+      createdAt: this.createdAt,
+      ...(this.activatedAt !== undefined ? { activatedAt: this.activatedAt } : {}),
+      ...(this.endedAt !== undefined ? { endedAt: this.endedAt } : {}),
+      cancelledAt: new Date(),
+    };
+
+    const next: SeasonSponsorshipProps =
+      this.description !== undefined
+        ? { ...base, description: this.description }
+        : base;
+
+    return new SeasonSponsorship(next);
+  }
+
+  /**
+   * Update pricing/terms when allowed
+   */
+  withPricing(pricing: Money): SeasonSponsorship {
+    if (pricing.amount <= 0) {
+      throw new RacingDomainValidationError('SeasonSponsorship pricing must be greater than zero');
+    }
+
+    if (this.status === 'cancelled' || this.status === 'ended') {
+      throw new RacingDomainInvariantError('Cannot update pricing for ended or cancelled SeasonSponsorship');
+    }
+
+    const base: SeasonSponsorshipProps = {
+      id: this.id,
+      seasonId: this.seasonId,
+      ...(this.leagueId !== undefined ? { leagueId: this.leagueId } : {}),
+      sponsorId: this.sponsorId,
+      tier: this.tier,
+      pricing,
+      status: this.status,
+      createdAt: this.createdAt,
+      ...(this.activatedAt !== undefined ? { activatedAt: this.activatedAt } : {}),
+      ...(this.endedAt !== undefined ? { endedAt: this.endedAt } : {}),
+      ...(this.cancelledAt !== undefined ? { cancelledAt: this.cancelledAt } : {}),
+    };
+
+    const next: SeasonSponsorshipProps =
+      this.description !== undefined
+        ? { ...base, description: this.description }
+        : base;
+
+    return new SeasonSponsorship(next);
+  }
+
+  /**
+   * Check if sponsorship is active
+   */
+  isActive(): boolean {
+    return this.status === 'active';
+  }
+
+  /**
+   * Get the platform fee for this sponsorship
+   */
+  getPlatformFee(): Money {
+    return this.pricing.calculatePlatformFee();
+  }
+
+  /**
+   * Get the net amount after platform fee
+   */
+  getNetAmount(): Money {
+    return this.pricing.calculateNetAmount();
+  }
+}