# V2 Season Pass Challenge System

This runbook covers `TODOS.phase-72.72.12.2.4`: a daily and weekly challenge
system that is randomly generated from a challenge pool, rewards XP and
currency, and auto-rotates on UTC windows.

The implementation extends `@v2/season-pass-service` at
`apps/v2/season-pass-service/`. Its contract is
`V2/ue/Content/V2/LiveOps/SeasonPassChallengeSystem_V2_Contract.json` and the
validation gate is `V2/ue/Tools/check-v2-season-pass-challenge-system.py`.

## Challenge Pool

Challenge pool entries define:

- `challengeId`
- `title`
- `cadence`
- `category`
- `objectiveKey`
- `targetValue`
- `weight`
- `xpReward`
- `currencyReward`

The supported cadences are `daily` and `weekly`. Supported categories are
`combat`, `engagement`, `ranked`, and `event`. The challenge system validates
duplicate IDs, unsupported cadence or category values, positive targets,
positive weights, and positive XP and currency rewards before any rotation is
published.

## Rotation Model

`buildV2SeasonPassChallengeSystemSurface` creates active daily challenges and
active weekly challenges from the configured challenge pool. Daily challenges
start at 00:00 UTC and auto-rotate every day. Weekly challenges start on Monday
at 00:00 UTC and auto-rotate every seven days. Selection is deterministic for a
season and rotation window, but it is randomly generated from the challenge pool
using each entry weight, so operators can adjust pool composition without a
client patch.

## Rewards

`completeV2SeasonPassChallenge` grants the active challenge reward. Daily
challenge completions emit a `daily-challenge` season-pass XP grant, weekly
challenge completions emit a `weekly-challenge` season-pass XP grant, and both
cadences emit `season-credits` currency grants. XP and currency rewards are
server-authoritative and keep `requiresClientPatch: false`; no client patch is
required for updated daily challenges, weekly challenges, or reward tuning.

Primary APIs:

- `buildV2SeasonPassChallengeSystemSurface`
- `completeV2SeasonPassChallenge`

Endpoints:

- `GET /v2/live-ops/season-pass/{seasonId}/challenges`
- `POST /v2/live-ops/season-pass/{seasonId}/challenges/rotate`
- `POST /v2/live-ops/season-pass/{seasonId}/challenges/{challengeId}/complete`

## Operator Flow

1. Author daily and weekly challenge pool entries before a season starts.
2. Weight challenge entries according to desired rotation frequency.
3. Preview daily and weekly windows with
   `buildV2SeasonPassChallengeSystemSurface`.
4. Publish the generated active challenge lists to the live-ops surface.
5. Route completion events through `completeV2SeasonPassChallenge` so XP and
   currency rewards are granted consistently.

## Release Gates

Required gates:

- `season-pass-challenge-system-surface`
- `season-pass-challenge-system-daily-weekly`
- `season-pass-challenge-system-random-pool`
- `season-pass-challenge-system-auto-rotate`
- `season-pass-challenge-system-xp-currency-rewards`
- `season-pass-challenge-system-validation`
- `season-pass-challenge-system-ci-wired`

## Verification

```bash
pnpm --filter @v2/season-pass-service test
pnpm --filter @v2/season-pass-service typecheck
pnpm --filter @v2/season-pass-service lint
pnpm --filter @v2/season-pass-service build
python3 V2/ue/Tools/check-v2-season-pass-challenge-system.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py
```