# V2 Season Pass XP Sources

This runbook covers `TODOS.phase-72.72.12.2.3`: season pass XP sources for match
completion, daily challenges, weekly challenges, and event bonuses.

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

## XP Source Format

Supported XP sources:

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

Each XP source definition includes:

- `source`
- `displayName`
- `cadence`
- `baseXp`
- `maxXpPerGrant`
- `replayEvidenceRequired`
- `antiCheatValidated`
- `serverAuthoritative`

The source surface validates duplicate and missing sources, positive XP values,
max grant caps, supported cadences, and server-authoritative XP ownership. The
client-facing metadata keeps `requiresClientPatch: false`; no client patch is
required for supported XP-source payloads.

## Grant Calculation

`calculateV2SeasonPassXpGrantFromSource` turns a trusted server source event
into a `V2SeasonPassXpGrant`. It validates season ID, account hash, grant ID,
source, award time, and optional multiplier. The grant calculation multiplies
`baseXp`, rounds to an integer, caps the result at `maxXpPerGrant`, and returns
the same grant shape consumed by `applyV2SeasonPassXpGrant`.

Primary APIs:

- `buildV2SeasonPassXpSourceSurface`
- `calculateV2SeasonPassXpGrantFromSource`

Endpoints:

- `GET /v2/live-ops/season-pass/{seasonId}/xp-sources`
- `POST /v2/live-ops/season-pass/{seasonId}/xp-sources/preview-grant`

## Operator Flow

1. Define the four required XP sources before a season starts.
2. Keep match completion, daily challenges, and weekly challenges tied to replay
   evidence and anti-cheat validation.
3. Use event bonuses for live event multipliers or participation bonuses.
4. Preview grant values before launch so multipliers cannot exceed
   `maxXpPerGrant`.
5. Pass accepted grants into the season pass progression system.

## Release Gates

Required gates:

- `season-pass-xp-sources-surface`
- `season-pass-xp-sources-match-completion`
- `season-pass-xp-sources-daily-weekly`
- `season-pass-xp-sources-event-bonus`
- `season-pass-xp-sources-grant-calculation`
- `season-pass-xp-sources-validation`
- `season-pass-xp-sources-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-xp-sources.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py
```