# V2 Live Event Scheduling

This runbook covers `TODOS.phase-72.72.12.2.5`: a live event scheduling system
that defines start/end times, enables event game modes, and activates event
rewards.

The implementation lives in `@v2/live-event-scheduling-service` at
`apps/v2/live-event-scheduling-service/`. Its contract is
`V2/ue/Content/V2/LiveOps/LiveEventScheduling_V2_Contract.json` and the
validation gate is `V2/ue/Tools/check-v2-live-event-scheduling.py`.

## Schedule Definitions

Each live event schedule definition includes:

- `eventId`
- `displayName`
- `startsAt`
- `endsAt`
- `visibilityStartsAt`
- `regions`
- `activationTags`
- `gameModes`
- `rewards`

The scheduler validates duplicate event IDs, start/end times, visibility times,
missing game modes, duplicate game mode IDs, missing event rewards, duplicate
reward IDs, unsupported reward kinds, and overlapping game mode windows before
publishing the live event schedule.

## Game Mode Activation

`buildV2LiveEventSchedulingSurface` classifies every event as `upcoming`,
`active`, or `ended` for the requested `generatedAt` timestamp. Active events
emit enabled game modes with `enabledAt` and `disabledAt` timestamps that match
the event start/end times. Upcoming and ended events remain visible in the
schedule surface but do not enable event game modes.

## Event Rewards

Event rewards activate only during the same event window as their game modes.
Active rewards include `rewardId`, `rewardKind`, `quantity`, `grantRef`,
`claimLimitPerAccount`, `activatesAt`, and `expiresAt`. Event rewards remain
server-authoritative and require no client patch when schedule or reward
definitions change.

Primary APIs:

- `buildV2LiveEventSchedulingSurface`
- `resolveV2LiveEventScheduleState`

Endpoints:

- `GET /v2/live-ops/events/schedule`
- `GET /v2/live-ops/events/active`
- `POST /v2/live-ops/events/{eventId}/rewards/activate`

## Operator Flow

1. Author event schedule definitions with start/end times, game modes, and event
   rewards.
2. Preview the active schedule with `buildV2LiveEventSchedulingSurface`.
3. Publish active game mode queue IDs and ruleset IDs from `enabledGameModes`.
4. Activate reward grants from `activeEventRewards`.
5. Keep the event visible after it ends for audit and make-good workflows.

## Release Gates

Required gates:

- `live-event-scheduling-package`
- `live-event-scheduling-windows`
- `live-event-scheduling-game-modes`
- `live-event-scheduling-event-rewards`
- `live-event-scheduling-auto-activation`
- `live-event-scheduling-validation`
- `live-event-scheduling-ci-wired`

## Verification

```bash
pnpm --filter @v2/live-event-scheduling-service test
pnpm --filter @v2/live-event-scheduling-service typecheck
pnpm --filter @v2/live-event-scheduling-service lint
pnpm --filter @v2/live-event-scheduling-service build
python3 V2/ue/Tools/check-v2-live-event-scheduling.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py
```