# @v2/feature-flag-service

V2 live-ops feature flag service for shipped game features. The package builds
validated feature flag snapshots, evaluates per-account rollout buckets, and
emits compact payloads that can toggle features without a client patch.

Covered launch workflows:

- enable a new game mode remotely
- disable a broken gameplay feature immediately
- instantly disable a shipped feature with a kill switch
- gradually roll out a feature by percentage

Primary API:

- `buildV2FeatureFlagServiceSurface`
- `evaluateV2FeatureFlag`
- `updateV2FeatureFlag`
- `buildV2FeatureFlagKillSwitchSurface`
- `buildV2FeatureFlagClientPayload`
- `buildV2FeatureFlagClientCache`
- `planV2FeatureFlagClientRefresh`
- `readV2FeatureFlagFromClientCache`

The service exposes these live-ops endpoints as contract metadata:

- `GET /v2/live-ops/feature-flags/{environment}`
- `POST /v2/live-ops/feature-flags/{environment}/flags/{flagKey}`
- `POST /v2/live-ops/feature-flags/{environment}/flags/{flagKey}/rollout`
- `POST /v2/live-ops/feature-flags/{environment}/kill-switches/{flagKey}`
- `GET /v2/live-ops/feature-flags/{environment}/kill-switches/active`

## Kill Switch

`buildV2FeatureFlagKillSwitchSurface` publishes a kill switch activation that
sets the target flag to `force-disabled`, rollout percentage 0, and no client
patch required. It carries incident metadata, the previous ETag, the new ETag,
and a forced client refresh plan with a short max client staleness window so
clients can instantly disable the feature on their next flag refresh. The no
client patch rule is enforced by the contract and tests.

Guarantees:

- no client patch

## Client SDK

The client SDK helpers check flag state at startup, plan periodic refreshes, and
use cached flags for offline play. `buildV2FeatureFlagClientCache` records
refresh and offline-expiry timestamps. `planV2FeatureFlagClientRefresh` returns
startup fetch, periodic fetch, cache-use, offline-cache, or fail-closed actions.
`readV2FeatureFlagFromClientCache` reads cached flag values and disables flags
after offline cache expiry.

## Verification

```bash
pnpm --filter @v2/feature-flag-service test
pnpm --filter @v2/feature-flag-service typecheck
python3 V2/ue/Tools/check-v2-feature-flag-service.py
python3 V2/ue/Tools/check-v2-feature-flag-client-sdk.py
python3 V2/ue/Tools/check-v2-feature-flag-kill-switch.py
```