# Data reload and telemetry operations policy

Prototype-through–early-pre-production rules for **how gameplay data is loaded and refreshed** (including progression curves and content tables) and **how telemetry is collected** (PII, sampling, retention, baseline events). Aligns with [contracts.md](contracts.md), [E9.M1 — TelemetryEventSchema](E9_M1_TelemetryEventSchema.md), and [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md).

---

## Content and gameplay data reload

Applies to **JSON/YAML** (or equivalent) loaded by the server: [E2.M1](E2_M1_SkillDefinitionRegistry.md) / [E2.M2](E2_M2_XpAwardAndLevelEngine.md) `LevelCurve` and skill data, items, recipes, quests, zones, etc.


| Environment / phase         | Policy                                                                                                                                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Prototype default**       | Load at **process start** after **CI validation** (JSON Schema or agreed validators). No requirement for hot reload in the first milestone.                                                                  |
| **Development**             | Optional **file-watcher reload** or **developer-only** admin endpoint to re-read tables; must be **disabled or authenticated** in any shared/staging/prod-like deploy. Document the switch in server config. |
| **Tuning without redeploy** | Prefer **[E9.M3 — LiveBalanceControlPlane](E9_M3_LiveBalanceControlPlane.md)** and **[E2.M4](E2_M4_ProgressionPacingControls.md)** when those exist—not ad-hoc editing production disk files.                |


**E2.M2:** Replace vague “reload policy TBD” with: **boot load** for prototype; optional dev reload as above; production path goes through gated balance patches per tech stack.

---

## Telemetry: privacy and payload rules

- **Identifiers:** Use **opaque** account/session/character ids in telemetry. Do not send email addresses, real names, billing identifiers, or unhashed hardware fingerprints in the default `ClientEventEnvelope` / event catalog.
- **User-generated content:** **No** free-form chat, player names, or report narrative in high-volume analytics streams unless a **separate**, access-controlled pipeline exists with stricter retention (integrity / moderation workflows may use different storage—see [E9.M4](E9_M4_IntegrityAndAbuseResponse.md), [E8.M4](E8_M4_ChatModerationAndReporting.md)).
- **Geo / device:** Collect only what is needed for stability and fraud signals; document any addition in the event catalog with purpose.
- **Envelope:** `ClientEventEnvelope` (or successor) carries **schema version**, **sampling** metadata, and a **privacy review flag** for events that need explicit approval before shipping to general ingest.

---

## Sampling and volume

- Follow vision plan **decision-driven instrumentation**: high-frequency signals (e.g. movement samples) are **sampled or bucketed**, not logged raw at full tick rate, unless a short-lived debug cohort is enabled.
- Each **high-volume** event class gets an explicit **default sample rate** in the E9.M1 catalog when defined; ops may raise/lower within agreed bounds.
- **Noise:** Prefer fewer, well-named events over many redundant ones; use `schema_version_mismatch` / ingest errors to catch client drift (see [Epic 9](../epics/epic_09_liveops_integrity.md) Slice 1).

---

## Retention and storage

- **Retention buckets** (raw vs aggregate, per-region legal requirements) are chosen when **ingest and storage** are provisioned—not fixed in this doc. Record the chosen values in runbooks or infra config.
- **Principle:** Raw events shorter retention; rolled-up KPIs longer. Integrity / incident artifacts may follow a **separate** retention policy under E9.M4.

---

## Baseline event taxonomy: source of truth

**Product baseline (categories and examples):** [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — section **“Event Instrumentation Baseline”** (session lifecycle, progression, economy, combat, PvP, system health), plus **“KPI and Telemetry Framework”** for what decisions the events must support.

**Machine-readable schemas:** When implemented, the versioned catalog under the repo layout in [contracts.md](contracts.md) (e.g. `contracts/schemas/telemetry/`) is the **field-level** source of truth for implementers; the vision plan remains the **intent** check. If the two disagree, **fix the catalog** and note the vision update if product meaning changed.

---

## Related docs

- [E9.M1 — TelemetryEventSchema](E9_M1_TelemetryEventSchema.md)
- [E2.M2 — XpAwardAndLevelEngine](E2_M2_XpAwardAndLevelEngine.md)
- [contracts.md](contracts.md)
- [Module dependency register — cross-cutting: data reload and telemetry](module_dependency_register.md#cross-cutting-data-reload-and-telemetry)
- [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md)