# @v2/remote-config-service

V2 live-ops remote config service for shipped game parameters. The package
builds validated remote config snapshots, resolves values for clients, and emits
compact client payloads that can be refreshed without a client patch. It also
tracks immutable config versions and publishes rollback snapshots when a bad
config change must be reverted immediately. The config change audit log records
who changed what, when the change happened, and why it was made. Validation
rules block obviously broken changes such as enemy health 0, drop rate 100%, and
decreasing XP curve values before publish. Preview/staging support builds
staging-only snapshots so operators can test changes before promotion to
production. Delivery optimization uses delta updates, client caching, and ETag
revalidation to minimize bandwidth. Maintenance mode uses the same remote config
channel to redirect all clients to a maintenance message during server updates,
force clients through a short client staleness refresh, and clear the redirect
with no client patch.

Covered launch parameter families:

- enemy health
- weapon damage
- reward drop rates
- economy prices
- economy rewards
- XP curves

Primary API:

- `buildV2RemoteConfigServiceSurface`
- `resolveV2RemoteConfigParameter`
- `updateV2RemoteConfigParameter`
- `buildV2RemoteConfigClientPayload`
- `buildV2RemoteConfigVersionHistory`
- `planV2RemoteConfigRollback`
- `rollbackV2RemoteConfigVersion`
- `buildV2RemoteConfigSegmentTargetingSurface`
- `resolveV2RemoteConfigForPlayer`
- `buildV2RemoteConfigChangeAuditLog`
- `buildV2RemoteConfigChangeAuditLogFromHistory`
- `buildV2RemoteConfigValidationRulesSurface`
- `buildV2RemoteConfigPreviewStagingSurface`
- `buildV2RemoteConfigDeliveryOptimizationSurface`
- `buildV2RemoteConfigMaintenanceModeSurface`
- `resolveV2RemoteConfigMaintenanceRedirect`

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

- `GET /v2/live-ops/remote-config/{environment}`
- `GET /v2/live-ops/remote-config/{environment}/etag/{etag}`
- `POST /v2/live-ops/remote-config/{environment}/parameters/{key}`
- `GET /v2/live-ops/remote-config/{environment}/versions`
- `POST /v2/live-ops/remote-config/{environment}/rollback/{versionId}`
- `GET /v2/live-ops/remote-config/{environment}/segments`
- `POST /v2/live-ops/remote-config/{environment}/segments/evaluate`
- `GET /v2/live-ops/remote-config/{environment}/audit-log`
- `GET /v2/live-ops/remote-config/{environment}/audit-log/{auditId}`
- `GET /v2/live-ops/remote-config/{environment}/validation-rules`
- `POST /v2/live-ops/remote-config/{environment}/validate`
- `POST /v2/live-ops/remote-config/{environment}/preview`
- `POST /v2/live-ops/remote-config/staging/promote`
- `GET /v2/live-ops/remote-config/{environment}/optimized`
- `GET /v2/live-ops/remote-config/{environment}/delta/{etag}`
- `HEAD /v2/live-ops/remote-config/{environment}/etag/{etag}`
- `GET /v2/live-ops/remote-config/{environment}/maintenance-mode`
- `POST /v2/live-ops/remote-config/{environment}/maintenance-mode`

## Versioning And Rollback

Each published surface can be recorded in a version history with its ETag,
parameter hash, publisher, change summary, incident ID, and immutable snapshot.
`planV2RemoteConfigRollback` rejects unknown targets, the currently active
version, and duplicate rollback version IDs. `rollbackV2RemoteConfigVersion`
publishes a new active snapshot whose client payload restores the selected
previous version while keeping `requiresClientPatch: false`.

## Config Change Audit Log

`buildV2RemoteConfigChangeAuditLogFromHistory` derives a full traceability audit
log from version history. Each immutable entry carries `changedBy`, `changedAt`,
`reason`, `parameterChanges`, and a traceability block with `who`, `what`,
`when`, and `why`. `buildV2RemoteConfigChangeAuditLog` also accepts manual
entries and validates non-empty reasons, parameter diffs, duplicate audit IDs,
and environment mismatches.

Audit entries include `auditHash` and `previousAuditHash` fields to form a
tamper-evident hash chain across publishes, parameter updates, rollbacks, and
segment overrides. The focused validation gate is
`check-v2-remote-config-audit-log.py`.

## Config Validation Rules

`buildV2RemoteConfigValidationRulesSurface` evaluates proposed changes against
validation rules before publish. The rules include `known-parameter-key`,
`enemy-health-positive`, `weapon-damage-non-negative`,
`drop-rate-below-100-percent`, `economy-price-non-negative`,
`economy-reward-non-negative`, `xp-curve-non-decreasing`, and
`numeric-bounds-enforced`.

The validation report includes `blocksPublish`, `rejectedValue`, `requestedBy`,
and `reason` so operators can see which change was blocked and why. Protected
examples include enemy health 0, drop rate 100%, negative economy prices,
negative economy rewards, and decreasing XP curve. The focused validation gate
is `check-v2-remote-config-validation-rules.py`.

## Config Preview And Staging

`buildV2RemoteConfigPreviewStagingSurface` validates proposed changes, builds a
staging snapshot, and emits `stagingClientPayload` for testing when the
`validationReport` is clean. Invalid previews keep `readyForProduction: false`
and omit staging payloads, while valid previews keep `productionUnchanged: true`
and `requiresClientPatch: false`.

Preview endpoints support staging validation and production promotion:

- `POST /v2/live-ops/remote-config/{environment}/preview`
- `POST /v2/live-ops/remote-config/staging/promote`

The focused validation gate is `check-v2-remote-config-preview-staging.py`.

## Config Delivery Optimization

`buildV2RemoteConfigDeliveryOptimizationSurface` provides delivery optimization
for minimal bandwidth by comparing the current payload with an optional previous
client payload and choosing `cache-hit`, `delta`, or `full` delivery. Cache hits
skip payload download when the ETag is current. Delta delivery sends only
changed parameters when it is smaller than the full payload. Full delivery
remains available when no previous payload exists.

The cache policy includes `max-age`, `stale-while-revalidate`, offline cache
seconds, `If-None-Match` revalidation, and a stable cache key. The surface
reports estimated bytes, estimated bytes saved, compression recommendation,
`minimalBandwidth: true`, and `requiresClientPatch: false`. The focused
validation gate is `check-v2-remote-config-delivery-optimization.py`.

## Maintenance Mode

`buildV2RemoteConfigMaintenanceModeSurface` activates or clears maintenance mode
through the remote config service. When active, the payload sets
`maintenanceActive: true`, `redirectAllClients: true`, and
`redirectRoute: '/maintenance'` so every client redirects to a maintenance
message instead of entering gameplay during server updates. The message includes
title, body, operator reason, optional estimated resume time, status page URL,
and support URL.

The maintenance surface publishes a refreshed config version with a capped
`maxClientStalenessSeconds` window, invalidates the previous ETag, and emits a
forced refresh instruction with `cacheBustToken`, `invalidatedEtags`, and
`forceRefreshBeforeUse: true`. `resolveV2RemoteConfigMaintenanceRedirect`
returns a blocking redirect decision while active and a non-redirect decision
when maintenance mode is inactive. The flow requires no client patch and is
validated by `check-v2-remote-config-maintenance-mode.py`.

Maintenance mode endpoints are:

- `GET /v2/live-ops/remote-config/{environment}/maintenance-mode`
- `POST /v2/live-ops/remote-config/{environment}/maintenance-mode`

## Segment Targeting

Segment targeting lets live ops apply config differently by region, platform,
player level, and A/B test group. `buildV2RemoteConfigSegmentTargetingSurface`
validates segment IDs, priorities, criteria, parameter keys, value bounds, and
targeting dimensions. `resolveV2RemoteConfigForPlayer` evaluates a hashed player
context, applies matched segments in deterministic priority order, and returns a
segmented client payload with matched segments, parameter sources, and
`requiresClientPatch: false`.

## Verification

```bash
pnpm --filter @v2/remote-config-service test
pnpm --filter @v2/remote-config-service typecheck
python3 V2/ue/Tools/check-v2-remote-config-service.py
python3 V2/ue/Tools/check-v2-remote-config-versioning.py
python3 V2/ue/Tools/check-v2-remote-config-segment-targeting.py
python3 V2/ue/Tools/check-v2-remote-config-audit-log.py
python3 V2/ue/Tools/check-v2-remote-config-validation-rules.py
python3 V2/ue/Tools/check-v2-remote-config-preview-staging.py
python3 V2/ue/Tools/check-v2-remote-config-delivery-optimization.py
python3 V2/ue/Tools/check-v2-remote-config-maintenance-mode.py
```