# V2 Season Pass Progression

This runbook covers `TODOS.phase-72.72.12.2.1`: a season/battle pass progression
system with an XP-based track, free and premium tiers, and rewards at each
level. The season pass progression surface explicitly validates rewards at every
level.

Rewards at every level are required for both lanes; rewards at every level are
part of the validated track contract.

The service package is `@v2/season-pass-service` at
`apps/v2/season-pass-service/`. Its contract is
`V2/ue/Content/V2/LiveOps/SeasonPassProgression_V2_Contract.json` and the
validation gate is `V2/ue/Tools/check-v2-season-pass-progression.py`.

## Progression Model

The first progression surface owns a 60-tier, 90-day track. Tier 1 starts at 0
XP, later tiers use strictly increasing XP thresholds, and the final tier caps
account progression so a large grant cannot overflow the season track.

Each level has two reward lanes:

- `free` rewards are claimable by every account that reaches the tier.
- `premium` rewards require the account's premium entitlement SKU.

The service validates that every level has at least one free reward and one
premium reward. The client payload includes `requiresClientPatch: false`, an
ETag, current tier, total XP, claimable rewards, and locked premium rewards; no
client patch is required for supported clients.

No client patch is part of the supported delivery contract; no client patch is
required for the published progression payload.

Primary APIs:

- `buildV2SeasonPassProgressionSurface`
- `resolveV2SeasonPassTierProgress`
- `applyV2SeasonPassXpGrant`

Endpoints:

- `GET /v2/live-ops/season-pass/{seasonId}/track`
- `GET /v2/live-ops/season-pass/{seasonId}/progression/{accountIdHash}`
- `POST /v2/live-ops/season-pass/{seasonId}/xp-grants`

## XP Grants

XP grants are server-authoritative. The server-authoritative XP flow in
`applyV2SeasonPassXpGrant` validates season ID, account hash, XP source,
positive XP, and ISO award time before adding XP to the account state. Duplicate
grant IDs are idempotent, so duplicate grant idempotency prevents retrying the
same grant from double-awarding XP.

Supported initial sources are:

- `match-completion`
- `daily-challenge`
- `weekly-challenge`
- `event-bonus`

## Operator Flow

1. Publish the season definition with start/end timestamps, premium SKU, max
   tier, and tier thresholds.
2. Validate the track before production: all tiers are sequential, XP thresholds
   increase, every level has free and premium rewards, and reward IDs are
   unique.
3. Grant XP from trusted server flows only.
4. Build the client progression surface after each accepted grant.
5. Let clients claim unlocked free rewards immediately and show locked premium
   rewards until entitlement is present.
6. Keep the season payload refreshable without a client patch.

## Release Gates

Required gates:

- `season-pass-progression-package`
- `season-pass-progression-xp-track`
- `season-pass-progression-free-premium`
- `season-pass-progression-rewards-every-level`
- `season-pass-progression-xp-grants`
- `season-pass-progression-validation`
- `season-pass-progression-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-progression.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py
```