# Live Service & Community

A universe this size is a service, not a box. V5 is one UE5 open-world narrative
universe split across ruleset cells — a 1947-noir **Urban** heist city, a
Prohibition-era **Period** crime saga, an 1899 **Frontier**, a Witcher-flavoured
**Hunter** world, a hard-SF **Sci-Fi** theatre, and the cross-cell **Mind
Palace** deduction layer — and it ships those five launch cells and then keeps
growing for years. The post-launch product is the part that arrives _after_
launch and keeps arriving: a 90-day season every quarter, a 100-tier per-cell
battle pass, weekly contracts, persistent world events, faction-reputation
ladders that decay and recover, Twitch drops and a creator-partner program,
AI-narrated highlight reels, curated community spotlights, 24/7 support, and a
public balance ledger so the community can audit every tuning change. This page
is the feature-side companion to the **Modes, Online Services & Live
Operations** group, and it is unusually honest about a seam that runs straight
through the middle of the subject: the **live-ops machinery is real, shipped
TypeScript and C++**, while a good deal of the _content_ that machinery delivers
— the specific Year-1 cosmetics, the per-cell theme drops, the authored
restoration missions — is design data the services execute, not engine artifacts
cooked to disk. Where a claim is backed by code this page names the package and
function; where it is authored design data or a plan, it says so. The feature
hub is [../V5_features.md](../V5_features.md).

The design line underneath everything is the same competitive-integrity rule the
rest of V5 draws and that V2 and V4 drew before it: **nothing sold or seasonal
ever touches gameplay power.** The battle pass marks gameplay-affecting rewards
`never-paid-only`, every calendar payload asserts
`exclusiveGameplayRewards: false`, store bundles are cosmetic-only, faction-rep
decay can never be bypassed with money, and balance ships as data, never a
forced binary patch. Live service grows the world; it never sells an advantage
in it.

## What ships, honestly

The split is clean, and stating it up front keeps the rest of the page honest.

The **live-ops services are real**. `apps/v5/` holds **16 deployable NestJS +
Fastify packages** (each with a `contract.json`, a `Dockerfile`, k8s manifests,
and a `contract.test.ts`), wired over one shared `@v5/service-shared` runtime.
The live-service-relevant ones — `live-service-calendar` (port 4223),
`faction-rep`, `replays`, `workshop`, `telemetry`, `balance-ledger`,
`companion-app-bridge` — are genuine services with typed contracts and pinned
endpoint sets.

The **load-bearing domain logic is real Postgres-backed code.** Under
`apps/v5/service-shared/src/domain/` sit the engines the live service runs on:
`FactionRepDomain` (a genuine exponential time-decay reputation model with an
append-only ledger), `WorkshopDomain` (a UGC marketplace with a moderation state
machine and an exact-to-the-cent revenue split), `ReplaysDomain` (a
content-addressed, deduplicated replay store with signed download grants),
`TelemetryDomain` (validating batched event aggregation), and
`LiveServiceCalendarDomain` (time-windowed events with a SHA-256 content ETag).
Each is unit- and integration-tested for **domain correctness**, not just data
flow.

The **UE client tier is real C++.** `V5/ue/Source/V5OnlineServices` ships
`UV5_Online_LiveServiceCalendarClient`, `UV5_Online_FactionRepClient`, and the
replay/highlight builders as `UBlueprintFunctionLibrary` composers
(`BuildYear1Calendar`, `BuildYear1DecayPolicy`, `BuildYear1AIHighlightReel`),
over an 809-line automation test that pins the season rotations, the decay caps,
and the highlight scoring.

Three honest caveats matter. **First, the deployed REST feed paths return
authored literals.** A request to `/v5/live-service-calendar/year1` resolves
through `handleRealRequest` to `evaluateServiceSpecificRule`
(`service-shared/src/runtime.ts:1389`), which returns hand-authored constants —
`seasonalThemeRotations: 4` (`:1863`), `scriptCount: 12` (`:1847`),
`exclusiveGameplayRewards: false` — not rows read from the calendar domain. The
real Postgres `LiveServiceCalendarDomain` and the real `FactionRepDomain` decay
model are exercised on the realtime path (`realtime.ts`) and by the read-only
companion bridge, and pinned by tests; they sit one wiring step from the REST
feed. **Second, the seasonal content is authored design data, not cooked
assets** — like V4, V5 represents drops, themes, and reward sets as JSON
manifests under `V5/live-service/`, not binary `.uasset`. **Third, the consumer
companion app is a mockup**: `V5/companion/` holds design-token Swift/Kotlin
stubs with no buildable iOS/Android project (per `V5_features.md` and the
`v5-verification-2026-05-31` audit). The companion _bridge service_ is real and
read-only; the phone app that would consume it is not built.

## The live service

### Seasons and the per-cell battle pass

Season One is authored end-to-end in
`V5/live-service/season-1-live-service-manifest.json`: _Fracture Signals_, a
90-day window (2027-03-01 → 2027-05-30) opened by a 30-day _Continuum Signal_
day-one event. Its battle pass is the recurring engagement spine — **one pass
per cell, 100 tiers across the 90 days**, with a free and a paid track, advanced
on a `battle_pass_xp` currency earned from missions, contracts, and PvP, pacing
toward completion at a target `{ min: 6, max: 8 }` hours per week. Every
per-cell track (`bp.s01.urban.fracture_signals` and four siblings) defines a
free track with 34 claimable rewards and a paid track with 100, and the
monetization line is drawn in the data itself: `tierSkipPolicy` allows
purchasable skips (`purchaseEnabled: true`, `maxSkipsPerSeason: 20`) but stamps
`gameplayAffectingRewards: "never-paid-only"`. Reward families are cosmetic —
`outfit`, `vehicle-wrap`, `emote`, `nameplate`, `ship-decal` — never frame data
or stats. Unclaimed rewards stay `claimable-until-season-end`, so the pass never
expires a reward mid-season.

**Weekly contracts** are the inner loop: `weeklyContracts` authors 7 contracts
per week rotating Mondays at `00:00 UTC` across a 13-week season, drawn per cell
from a typed `poolByCell` with an `intro | standard | hard | expert` difficulty
spread. The honest policy is in the data —
`unfinished-contracts-expire-at-cycle-rollover` but
`missed-contracts-do-not-remove-earned-pass-progress` — so a player who skips a
week loses that week's contracts, not their tier position. Each season's
`seasonalThemeDrops` re-skins all five cells (Urban summer-beach, Period
winter-noir, Frontier high-summer, Hunter dark-autumn, Sci-Fi solar-storm) and
the Year-1 calendar manifest authors all four rotations — Fracture Signals, Neon
Harvest, Long Night Protocol, Founders Return — each with five per-cell themes.

### Faction reputation, decay, and restoration

Faction reputation is where the live service has its deepest real algorithm.
`FactionRepDomain` (`service-shared/src/domain/faction-rep.ts`) replaces a prior
`simulatedDecay: true` echo with a genuine model: reputation relaxes toward a
neutral floor while a player is inactive,
`rep(t) = floor + (rep0 − floor) · exp(−ln2/halfLife · days)`, with
`REP_FLOOR = 0`, `REP_CEILING = 1000`, `DEFAULT_HALF_LIFE_DAYS = 30`, and a
`DEFAULT_GRACE_DAYS = 14` window below which nothing decays. The surplus over
the floor halves every 30 idle days; `applyDelta` clamps every event to
`±REP_DELTA_CLAMP` (100) and journals it; the weekly `runDecay(nowUnix)` writes
every decrement into an append-only `v5_faction_rep_ledger`. The test
(`faction-rep.test.ts`) pins the math against known-correct answers —
`decayedRep(100, 14 + 30)` is `toBeCloseTo(50, 5)`, two half-lives is `25`, the
grace window decays nothing — a test that would _fail_ on a hardcoded or random
return. The UE client mirrors it: `SimulateFactionRepDecay` asserts an inactive
paragon account decays `8200 → 8100` under its rule cap and that the 14-day
grace blocks decay entirely.

The recovery side is authored design data the model serves.
`year-1-faction-reputation-decay.json` defines the weekly decay job
(`cadenceDays: 7`, `inactivityGraceDays: 14`, `protectNeutralTier: true`,
`notificationLeadDays: 3`) plus **five per-cell restoration mission arcs** —
Harbor Truce (Urban), Press Amnesty (Period), Range Mediation (Frontier),
Village Rite (Hunter), Station Amnesty (Sci-Fi) — each three missions restoring
up to `maxRestoreRep: 450` and each clearing one rival lock on completion. The
release gates assert what the design promises: `noDecayBelowNeutral: true` and
`noPaidRestorationShortcuts: true`. You climb back by playing, not by paying.

### The calendar, world events, and hot-fixes

```mermaid
flowchart TD
  subgraph Authored["V5/live-service/*.json — design source of truth"]
    S1[season-1 manifest<br/>battle pass · contracts · drops]
    Y1[year-1 calendar · world-events<br/>faction-decay · highlight-reel]
  end
  subgraph Services["apps/v5 — 16 NestJS services over @v5/service-shared"]
    Cal[live-service-calendar :4223<br/>5 JWT-gated feeds]
    Dom[(Postgres domains<br/>FactionRep · Workshop · Replays<br/>Telemetry · Calendar)]
    Lit[evaluateServiceSpecificRule<br/>authored literal payloads]
  end
  subgraph Client["V5/ue/Source/V5OnlineServices — C++"]
    UE[UV5_Online_* builders<br/>BuildYear1Calendar · DecayPolicy · Reel]
  end
  S1 -. authors .-> Lit
  Y1 -. authors .-> Lit
  Y1 -. authors .-> UE
  Lit -->|ETag feed, Bearer JWT| UE
  Dom -.realtime + companion read.-> Bridge[companion-app-bridge<br/>read-only home view]
  Lit -->|/api/public/season-calendar| Web[apps/v5/web public calendar + store]
```

The calendar is the single source of truth for live-service _timing_.
`V5LiveServiceCalendarController` (`live-service-calendar/src/controller.ts`)
exposes five GET routes — `/feed`, `/year1`, `/world-events/year1`,
`/pro-stadium-tour`, `/year3-pipeline` — each `requiresJwt: true` and
`regional: true` in `contract.json`, which declares **21 capabilities** and a
`regional-active-active` failover across `iad/fra/sin` primaries with
`pdx/dublin/syd` fallbacks. Events resolve to an `Upcoming | Live | Ended` state
from a start/end window; an event that fails to start surfaces a retry notice
rather than a silent gap, and a time-limited reward, once granted, is kept
permanently. **Persistent world events** ride the `/world-events/year1` feed: 12
one-week scripts (Gang War Week first) that open a calendar window, record
objective and faction telemetry, persist settled world-state mutations for 30
days, and ship `exclusiveGameplayRewards: false` — a player who misses Gang War
Week loses a moment, not power. The Postgres `LiveServiceCalendarDomain` behind
this (real `upsertEvent`/`activeEvents` plus a content-derived SHA-256 `etag`)
is the shape the literal feed grows into; the architecture-level treatment of
the calendar spine and the DLC GameFeature boundary lives in the arch companion,
[../architecture/live-service-and-dlc.md](../architecture/live-service-and-dlc.md).

Hot-fixes are **data, not binaries.** `season-1`'s `balanceHotfixPipeline`
authors the rule: `delivery: "cdn-served-signed-data"`,
`binaryPatchRequired: false`, fetched at `session-start`, signed `ed25519`, with
a `last-known-good-with-ledger-reversal` rollback and eligible domains of
weapon-stats, economy-values, UI strings, calendar, and faction-rep gates. Every
balance change it carries posts to the public `balance-ledger` service with the
change, the rationale, and the effective date — the transparency layer that lets
the community trace exactly what moved and when.

### AI commentary and highlight reels

Post-match content is real service code over a real replay store.
`ReplaysDomain` (`domain/replays.ts`) stores replay chunks content-addressed by
SHA-256 — a repeated chunk bumps a refcount instead of re-storing bytes, so two
replays sharing a chunk cost one copy — and issues time-bounded, HMAC-signed
download grants (`signDownloadGrant`, 900-second TTL). On top of that store, the
Year-1 AI highlight reel is authored in `year-1-ai-highlight-reel.json` and
built client-side by `UV5_Online_ReplaysService::BuildYear1AIHighlightReel` /
`BuildTop10HighlightClips`. It is honest about being AI-assisted: an optional
CoquiTTS commentator track (`syntheticContentIndicator: true`,
`humanCasterOverride: true`, `playerDisableable: true`,
`transcriptRequired: true`), a top-10 reel ranked by a weighted
`v5-highlight-ranker-v1` model (kill-multiplicity 40, objective-impact 30,
clutch-context 20, teamplay-chain 10), and a per-match recap attached to match
history with a `source-replay-verification` requirement and an explicit
"AI-generated recap; verify with source replay" disclaimer. The reel never
touches progression (`noProgressionImpact: true`), and the underlying replay
stays downloadable so a viewer can check the summary against the source.

## Community features

### Creator partnership and Twitch drops

The creator ecosystem is authored in the season manifest. `creatorPartnership`
defines three revocable tiers gated on monthly views — `creator-affiliate` (50k,
referral code + hub profile), `creator-partner` (250k, embargoed preview build +
creator cosmetic set + private support channel), and `creator-featured` (1M,
launch-stream slot + curated gallery feature) — with viewer interaction confined
to `nonGameplayHooks` (photo-theme votes, poll-driven emotes, a stream-safe
soundboard), so a stream can never vote a gameplay advantage. `twitchDrops`
schedules watch-time-gated cosmetic campaigns (launch week at 30/60/120 minutes,
a capital-raid final at 45/90) through the calendar, links them to the V5
account via `@v5/service-auth`, and grants on next login. A Streamer Mode
privacy surface masks gamertags, invite codes, and the in-game social feed, and
substitutes a cleared-for-broadcast music bed where audio rights require it.

### Curated surfaces: Player of the Week, Hall of Fame, ambassadors

The community-stewardship surface is authored in
`V5/community/customer-support-community-manifest.json`, and its permission
model is the interesting part. **Community ambassadors** are a volunteer program
(≥48 active across NA/EU/LATAM/APAC) staffing report-queue triage, workshop and
gallery curation, and help-channel seeding under a required conduct agreement
and five training modules — with a deliberately constrained permission set:
`canModerate: false`, `canViewPrivatePlayerData: false`, `canEscalate: true`,
`canCurate: true`. Volunteers curate and escalate; they never adjudicate or see
private data. **Hall of Fame** recognises top-rated Mind Palace solves (sourced
from `mindpalace-cloud-sync`, `antiCheatReviewRequired: true`) and top workshop
contributors (sourced from `workshop`), both `privacyOptOutRespected`. **Player
of the Week** runs a four-step review workflow (community shortlist →
trust-safety check → privacy-consent check → scheduled card) with a
`cosmeticOnlyReward` and a 90-day post-enforcement cooldown. Every spotlight
requires opt-in for personal content and preserves synthetic-content indicators
where AI-assisted work is featured. These surfaces are authored design data
whose `sourceServices` point at the real `workshop`, `leaderboards`, `replays`,
`mindpalace-cloud-sync`, and `compliance-dsar` contracts that back them.

### Customer support, telemetry, and balance transparency

**Support** is a first-class capability, not an afterthought. The manifest
authors a 24/7 posture: a tier-1 live chat with a 60-second first-response SLA
across six knowledge domains, and a tier-2 ticket queue with per-category SLAs
(account 12h, billing/technical/privacy 24h, moderation 48h) routed to
trust-safety, platform-commerce, live-ops, engineering-oncall, or privacy-legal,
with `auditLogRequired: true` and a DSAR escalation into
`/v5/compliance-dsar/export`. Ban and anti-cheat appeals file through this path
with a 7-day SLA.

**Telemetry** that feeds balance is real ingestion. `TelemetryDomain`
(`domain/telemetry.ts`) validates and aggregates events into
per-`(cell, region, event-type, day)` counters: it rejects oversize events
(`MAX_EVENT_BYTES = 2048`) and caps batches (`MAX_BATCH = 500`), folding
survivors into Postgres with one upsert per distinct key — a real, queryable
aggregate that does not require a ClickHouse cluster to function (ClickHouse
remains the production analytics sink). Each event carries only an opaque
per-account ID and a region; consent is a per-region opt-in that stops
collection rather than anonymising after the fact. Every balance change
telemetry motivates posts to the public balance ledger, so the loop from "the
data said X" to "we changed Y, here is why" is auditable.

### The companion app — bridge real, app a mockup

The companion _bridge_ is genuine. `CompanionAppBridgeDomain`
(`domain/companion-app-bridge.ts`) is a strictly read-only aggregator that
composes a single home view from the real persisted stores — recent replays, the
Mind Palace graph summary, the balance-ledger head, and decayed faction
reputation — every field a live query against a real backing table, and it
stamps `readOnly: true` to match the companion-app security model: it never
mutates gameplay state. What is _not_ built is the consumer app that would
render it. `V5/companion/` holds design-token Swift/Kotlin mockups with no Xcode
or Gradle project; the planned Mind Palace editor, AR-overlay, and
VTuber/crime-scene modes (each with its own privacy-preserving bridge endpoint)
are target vision, honestly labelled as such in `V5_features.md`. The bridge is
ready; the phone is not.

## Where this connects

The through-line is consistent with the rest of V5: the **machinery is real
service and engine code** composing one shared backbone, and the page is precise
about where shipped TypeScript and C++ end and the authored Year-1 content (and
the unbuilt companion app) begin.

- [Online Services & Infrastructure](./online-services-and-infrastructure.md) —
  the `V5OnlineServices` client catalog, matchmaking, leaderboards, anti-cheat,
  crossplay, and the JWT auth and Bureau account/XP ledgers the seasonal
  calendar, world events, and faction-rep decay read from and write to.
- [Content Creator Tools & Workshop](./content-creator-tools-and-workshop.md) —
  the workshop marketplace (`WorkshopDomain`'s 70/20/5/3/2 revenue split,
  moderation state machine, and 48-hour refund window) and the creator surfaces
  the partner program, Hall of Fame, and curated showcases feed.
- Architecture companion:
  [../architecture/live-service-and-dlc.md](../architecture/live-service-and-dlc.md)
  — the calendar spine internals, the DLC GameFeature plugin boundary, the
  literal-vs-domain feed seam, and the no-pay-to-win / no-binary-hot-patch
  invariants at architecture depth.
- The feature hub: [../V5_features.md](../V5_features.md)