62 lines
5.1 KiB
Markdown
62 lines
5.1 KiB
Markdown
# 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)
|