# V2 Player Compensation System

This runbook covers `TODOS.phase-72.72.12.2.12`: a player compensation system to
grant items and currency to affected players after bugs or outages.

The service package is `@v2/player-compensation-service` at
`apps/v2/player-compensation-service/`. Its contract is
`V2/ue/Content/V2/LiveOps/PlayerCompensation_V2_Contract.json`, and the focused
gate is `V2/ue/Tools/check-v2-player-compensation.py`.

## Runtime Contract

Primary APIs:

- `buildV2PlayerCompensationSurface`
- `planV2PlayerCompensationGrants`
- `applyV2PlayerCompensationGrant`

Service endpoints:

- `GET /v2/live-ops/compensation/campaigns`
- `POST /v2/live-ops/compensation/campaigns/{campaignId}/grants/plan`
- `POST /v2/live-ops/compensation/campaigns/{campaignId}/grants/apply`

Campaigns are tied to an `incidentId`, reason, affected-player evidence, grant
bundle, and approval records. The supported reasons are:

- `bug`
- `outage`

The grant bundle must include item grants and currency grants. Item grants carry
`catalogRef` and `entitlementRef` metadata, while currency grants carry a
currency id and positive amount. Affected-player rows must include an
`accountIdHash`, affected window id, evidence reference, severity, and affected
time span.

## Grant Flow

1. Live ops creates a compensation campaign after a bug or outage incident.
2. Incident evidence selects affected players and records the affected window.
3. An approver signs the campaign before grants are planned.
4. `planV2PlayerCompensationGrants` builds idempotent item and currency grants.
5. `applyV2PlayerCompensationGrant` applies each grant to the account ledger and
   skips already processed grant ids.

The service is server-authoritative and keeps `requiresClientPatch: false`.

## Required Gates

- `player-compensation-package`
- `player-compensation-affected-players`
- `player-compensation-bug-outage`
- `player-compensation-item-grants`
- `player-compensation-currency-grants`
- `player-compensation-idempotency`
- `player-compensation-validation`
- `player-compensation-ci-wired`

## Verification

```sh
pnpm --filter @v2/player-compensation-service test
pnpm --filter @v2/player-compensation-service typecheck
pnpm --filter @v2/player-compensation-service lint
pnpm --filter @v2/player-compensation-service build
python3 V2/ue/Tools/check-v2-player-compensation.py
```