From 93eb1fc936e03736dd6c794777cecf9105d5d433 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Mon, 30 Mar 2026 18:41:57 -0400 Subject: [PATCH] docs: add per-module decomposition docs and register links Add nine module documents aligned with module_dependency_register rows (E1.M1, E1.M2, E2.M2, E3.M2, E4.M4, E5.M1, E6.M1, E7.M1, E9.M1) with purpose, contracts, dependencies, dependents, slices, and risks. Link register and decomposition README to the new files; note E1.M3 as E5.M1 dependency without a register row yet. Made-with: Cursor --- docs/decomposition/README.md | 2 +- .../modules/E1_M1_InputAndMovementRuntime.md | 53 +++++++++++++++++ .../E1_M2_IsometricCameraController.md | 50 ++++++++++++++++ .../modules/E2_M2_XpAwardAndLevelEngine.md | 55 ++++++++++++++++++ .../E3_M2_RefinementAndRecipeExecution.md | 53 +++++++++++++++++ .../modules/E4_M4_SecurityTierZoneFlags.md | 51 ++++++++++++++++ .../modules/E5_M1_CombatRulesEngine.md | 58 +++++++++++++++++++ .../E6_M1_PvPEligibilityAndFlagState.md | 52 +++++++++++++++++ .../modules/E7_M1_QuestStateMachine.md | 54 +++++++++++++++++ .../modules/E9_M1_TelemetryEventSchema.md | 52 +++++++++++++++++ .../modules/module_dependency_register.md | 18 ++++++ 11 files changed, 497 insertions(+), 1 deletion(-) create mode 100644 docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md create mode 100644 docs/decomposition/modules/E1_M2_IsometricCameraController.md create mode 100644 docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md create mode 100644 docs/decomposition/modules/E3_M2_RefinementAndRecipeExecution.md create mode 100644 docs/decomposition/modules/E4_M4_SecurityTierZoneFlags.md create mode 100644 docs/decomposition/modules/E5_M1_CombatRulesEngine.md create mode 100644 docs/decomposition/modules/E6_M1_PvPEligibilityAndFlagState.md create mode 100644 docs/decomposition/modules/E7_M1_QuestStateMachine.md create mode 100644 docs/decomposition/modules/E9_M1_TelemetryEventSchema.md diff --git a/docs/decomposition/README.md b/docs/decomposition/README.md index 612574b..060e71d 100644 --- a/docs/decomposition/README.md +++ b/docs/decomposition/README.md @@ -9,7 +9,7 @@ This workspace contains detailed planning artifacts derived from the finalized m ## Folder Layout - `epics/` - One file per epic with implementation slices. -- `modules/` - Cross-epic contracts, dependency register, and interface notes. +- `modules/` - Cross-epic contracts, [dependency register](modules/module_dependency_register.md), one [module doc per registered module](modules/module_dependency_register.md#per-module-documentation), and interface notes. - `milestones/` - Phase-gated implementation tracks and pass/fail checklists. ## Working Rules diff --git a/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md b/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md new file mode 100644 index 0000000..34ee3a6 --- /dev/null +++ b/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md @@ -0,0 +1,53 @@ +# E1.M1 — InputAndMovementRuntime + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E1.M1 | +| **Epic** | [Epic 1 — Core Player Runtime](../epics/epic_01_core_player_runtime.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Provides the foundational client/runtime path for character locomotion and world interaction: click-to-move or path-follow baseline, interaction trigger range checks, and the authoritative reconciliation surface for where the player is in the world. Other epics attach gameplay (gathering, combat, quests) on top of stable position and movement contracts. + +## Responsibilities + +- Character locomotion and movement command handling. +- Interaction trigger range checks using a single source of truth for distance. +- Emitting or consuming movement-related state suitable for server reconciliation in multiplayer tests. + +## Key contracts + +| Contract | Role | +|----------|------| +| `MoveCommand` | Client or input layer requests movement; server (or sim) validates and applies. | +| `PositionState` | Current authoritative (or reconciled) position for the avatar. | +| `InteractionRequest` | Optional path for interaction attempts; pairs with range checks. | + +Contract readiness is tracked in the [module dependency register](module_dependency_register.md). + +## Module dependencies + +- **None** — root of the player runtime stack. + +## Dependents (by design) + +- **E1.M2** — Isometric camera follows the player; needs stable player anchor / position. +- **E1.M3** — Interaction and targeting builds on movement and position. +- **Downstream epics** — Gathering (E3.M1), zone transitions (E4.M1), and others consume position implicitly via higher layers. + +## Related implementation slices + +See Epic 1 **Slice 1 — Movement and position sync**: server-authoritative or client-predicted baseline with `MoveCommand` / `PositionState` reconciliation; interaction range single source of truth; telemetry hooks such as `session_start`, lightweight position samples, and `interaction_attempt` failures. + +## Risks and telemetry + +- Desync between client prediction and server authority: mitigate with one reconciliation ruleset and log desync via [E9.M1 — TelemetryEventSchema](E9_M1_TelemetryEventSchema.md) when schema exists. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 1. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E1_M2_IsometricCameraController.md b/docs/decomposition/modules/E1_M2_IsometricCameraController.md new file mode 100644 index 0000000..200520b --- /dev/null +++ b/docs/decomposition/modules/E1_M2_IsometricCameraController.md @@ -0,0 +1,50 @@ +# E1.M2 — IsometricCameraController + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E1.M2 | +| **Epic** | [Epic 1 — Core Player Runtime](../epics/epic_01_core_player_runtime.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Delivers a locked isometric camera that keeps the player readable during motion: follow behavior, discrete zoom bands, occlusion handling, and explicit **no rotation** so combat telegraphs and UI remain consistent with the vision for fixed isometric presentation. + +## Responsibilities + +- Locked isometric follow (camera does not freely orbit). +- Zoom bands and configuration-driven limits. +- Occlusion policy so critical gameplay elements remain visible where possible. +- Enforcement of no-rotation rules for the prototype camera model. + +## Key contracts + +| Contract | Role | +|----------|------| +| `CameraState` | Current follow target, zoom level, and policy flags for consumers (e.g. risk UX). | +| `ZoomBandConfig` | Data-driven min/max or discrete zoom steps. | +| `OcclusionPolicy` | Rules for fading, dithering, or offset when geometry blocks the view. | + +## Module dependencies + +- **E1.M1** — InputAndMovementRuntime: camera follows the player anchor derived from movement/position. + +## Dependents (by design) + +- **E6.M2** — Consent and risk UX may use camera-adjacent presentation; epic lists E1.M2 as a dependency for in-zone risk signaling and readability. + +## Related implementation slices + +See Epic 1 **Slice 2 — Locked isometric camera**: follow-center, zoom bands, occlusion policy, no rotation; optional telemetry such as throttled `camera_zoom_changed` and perf stress markers for occluders. + +## Risks and telemetry + +- Occlusion hiding telegraphs: tune policy early and include readability checklist in prototype gates. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 1. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md b/docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md new file mode 100644 index 0000000..8c60881 --- /dev/null +++ b/docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md @@ -0,0 +1,55 @@ +# E2.M2 — XpAwardAndLevelEngine + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E2.M2 | +| **Epic** | [Epic 2 — Classless Progression](../epics/epic_02_classless_progression.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Central server-authoritative engine for classless skill progression: applying XP grants, resolving levels against data-driven curves, and emitting level-up events. Gathering, crafting, and combat integrate **as callers** of this API without being hard dependencies for implementing the engine itself (see Epic 2 Slice 2 vs Slice 3). + +## Responsibilities + +- Apply `XpGrantEvent` (or equivalent) per skill with validated skill references from E2.M1. +- Resolve experience against `LevelCurve` / threshold tables. +- Emit `LevelUpEvent` when thresholds are crossed. +- Support data-driven curves and reload policy agreed for prototype. + +## Key contracts + +| Contract | Role | +|----------|------| +| `XpGrantEvent` | Structured XP award (skill id, amount, source, modifiers). | +| `LevelCurve` | Thresholds or formula per skill or global policy. | +| `LevelUpEvent` | Notification for UI, unlocks, and downstream systems. | + +## Module dependencies + +- **E2.M1** — SkillDefinitionRegistry: `SkillDef`, categories, and validation of skill IDs. + +## Dependents (by design) + +- **E5.M1** — CombatRulesEngine: combat awards XP via integration (Epic 5 / Epic 2 slices). +- **E3.M1 / E3.M2** — Gathering and crafting award XP when wired in Slice 3. +- **E7.M2** — RewardAndUnlockRouter routes quest rewards including XP through E2.M2. +- **E2.M3 / E2.M4** — Mastery and pacing layers build on level/XP state (pre-production). + +## Related implementation slices + +- **Epic 2 Slice 2 — XP engine (E2.M2 core)**: implement contracts and tests without requiring Epic 3 or 5 modules. +- **Epic 2 Slice 3 — XP award integration**: wire E3.M1, E3.M2, E5.M1 to the award API for three prototype skill lines. + +## Risks and telemetry + +- Runaway leveling in one skill: diminishing returns per slice; monitor distribution via E9.M2 when available. +- Telemetry: `xp_grant`, `level_up`, time-to-first-level-up once real activity fires. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 2. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E3_M2_RefinementAndRecipeExecution.md b/docs/decomposition/modules/E3_M2_RefinementAndRecipeExecution.md new file mode 100644 index 0000000..0c2503e --- /dev/null +++ b/docs/decomposition/modules/E3_M2_RefinementAndRecipeExecution.md @@ -0,0 +1,53 @@ +# E3.M2 — RefinementAndRecipeExecution + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E3.M2 | +| **Epic** | [Epic 3 — Crafting Economy](../epics/epic_03_crafting_economy.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Implements the processing and crafting pipeline: raw-to-refined flows and recipe execution with server-authoritative inventory mutations. Bridges gathered materials (E3.M1) and item definitions (E3.M3) into usable outputs for combat, quests, and economy loops. + +## Responsibilities + +- Validate `CraftRequest` against `RecipeDef`, costs, and player inventory state. +- Produce `CraftResult` (success/failure, outputs, failures with reason codes). +- Support prototype recipe set (e.g. 8–12 starter recipes per epic slice minimums). + +## Key contracts + +| Contract | Role | +|----------|------| +| `RecipeDef` | Inputs, outputs, skill gates, station requirements (as scoped for prototype). | +| `CraftRequest` | Actor, recipe, quantities, optional targeting for UI/server sync. | +| `CraftResult` | Deterministic outcome for inventory and telemetry. | + +## Module dependencies + +- **E3.M1** — ResourceNodeAndGatherLoop: refined materials flow from gather outputs into crafting inputs. +- **E3.M3** — ItemizationAndInventorySchema: `ItemDef`, `ItemInstance`, inventory slots for costs and outputs. + +## Dependents (by design) + +- **E7.M1** — QuestStateMachine: quest steps may require crafted items or craft completion. +- **E6.M4** — RewardParityEnforcer: maps PvP rewards to PvE/crafting equivalents involving craft outputs. +- **Epic 2 integration** — Callers award crafting XP via [E2.M2](E2_M2_XpAwardAndLevelEngine.md) at activity sites. + +## Related implementation slices + +See Epic 3 **Slice 3 — Recipes and crafting pipeline**: gather → refine → item used in combat or quest; telemetry `item_crafted`, `craft_failed`, time-to-first-craft. + +## Risks and telemetry + +- Duplication or negative stacks: server-authoritative craft and inventory; integrity signals via E9.M4 when live. +- Quest/economy parity: lint reward bundles against E6.M4 and E3.M5 policies in later phases. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 3. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E4_M4_SecurityTierZoneFlags.md b/docs/decomposition/modules/E4_M4_SecurityTierZoneFlags.md new file mode 100644 index 0000000..1430677 --- /dev/null +++ b/docs/decomposition/modules/E4_M4_SecurityTierZoneFlags.md @@ -0,0 +1,51 @@ +# E4.M4 — SecurityTierZoneFlags + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E4.M4 | +| **Epic** | [Epic 4 — World Topology](../epics/epic_04_world_topology.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Layer on top of the zone graph that tags each zone with security tier (e.g. high / low / contested) and exposes **server-authoritative** policy state and entry-warning payloads. Enables PvP eligibility ([E6.M1](E6_M1_PvPEligibilityAndFlagState.md)) and risk UX without circular dependencies: Epic 6 consumes this data; E4.M4 does not depend on Epic 6. + +## Responsibilities + +- Assign and persist `SecurityTier` per zone (from data on E4.M1). +- Publish `ZonePolicyState` for server and client display alignment. +- Emit or serve `ZoneEntryWarning` when players transition into higher-risk zones. + +## Key contracts + +| Contract | Role | +|----------|------| +| `SecurityTier` | Discrete tier driving PvP and risk rules. | +| `ZonePolicyState` | Authoritative flags for what is allowed in-zone. | +| `ZoneEntryWarning` | Structured warning for consent flows and UI copy. | + +## Module dependencies + +- **E4.M1** — ZoneGraphAndTravelRules: `ZoneDef`, edges, and travel context for tier attachment. + +## Dependents (by design) + +- **E6.M1** — PvPEligibilityAndFlagState: primary consumer for who may engage in PvP where. +- **E6.M2** — ConsentAndRiskUxSignals: displays risk using tier and warning contracts. + +## Related implementation slices + +See Epic 4 **Slice 2 — Security tier tagging and UI hooks**: server and client agree on tier at transitions; entry-warning contract stable for Epic 6; telemetry `security_zone_enter`, `security_zone_exit` aligned with PvP events. + +## Risks and telemetry + +- Client/server mismatch: server is source of truth; client prediction display-only. +- Coordinate with Epic 6 prototype gates for optionality and clarity. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 4. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E5_M1_CombatRulesEngine.md b/docs/decomposition/modules/E5_M1_CombatRulesEngine.md new file mode 100644 index 0000000..a5fb6da --- /dev/null +++ b/docs/decomposition/modules/E5_M1_CombatRulesEngine.md @@ -0,0 +1,58 @@ +# E5.M1 — CombatRulesEngine + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E5.M1 | +| **Epic** | [Epic 5 — PvE Combat](../epics/epic_05_pve_combat.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Core tab-target combat resolution: valid actions against a locked target, hit resolution, cooldown and resource timing, and threat state as needed for prototype encounters. Presents readable outcomes in fixed isometric view and feeds XP awards through [E2.M2](E2_M2_XpAwardAndLevelEngine.md). + +## Responsibilities + +- Combat state machine for tab-target flow (attacks, abilities per prototype scope). +- Validate and apply `CombatAction`; produce `CombatResolution` for UI and logs. +- Integrate with targeting/interaction from **E1.M3** (target lock, valid target checks). +- Award combat XP via E2.M2 integration where specified in slices. + +## Key contracts + +| Contract | Role | +|----------|------| +| `CombatAction` | Attack, ability, or other combat intent from client/input scaffold. | +| `CombatResolution` | Hits, misses, damage, denies with reason codes (no silent failures). | +| `ThreatState` | Aggro/threat for NPC and encounter coordination (as scoped). | + +## Module dependencies + +- **E1.M3** — InteractionAndTargetingLayer: `TargetState`, selection, and ability request path alignment with **E1.M4** (AbilityInputScaffold; see [Epic 1](../epics/epic_01_core_player_runtime.md)) for `AbilityCastRequest` wiring to this engine. +- **E2.M2** — XpAwardAndLevelEngine: combat XP grants. + +> **Register note:** The [module dependency register](module_dependency_register.md) lists `E1.M3` for this module; E1.M3 is defined in [Epic 1](../epics/epic_01_core_player_runtime.md) but is not a separate row in the register table. + +## Dependents (by design) + +- **E5.M2** — NpcAiAndBehaviorProfiles. +- **E5.M3** — EncounterAndRewardTables. +- **E1.M4** — AbilityInputScaffold sends `AbilityCastRequest` to combat. +- **E7.M1** — QuestStateMachine for combat-related quest steps. +- **E2.M2** — Invoked as integration caller for XP (not a structural child). + +## Related implementation slices + +See Epic 5 **Slice 1 — Combat rules MVP**: target lock, basic attacks, 4–6 abilities, cooldowns/resources; telemetry `encounter_start`, `ability_used`, `player_death`, `enemy_defeat`. + +## Risks and telemetry + +- Sluggish or opaque tab-target: prototype readability gate; instrument time-in-combat and deny reasons. +- Desync logging via E9.M1 taxonomy when available. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 5. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E6_M1_PvPEligibilityAndFlagState.md b/docs/decomposition/modules/E6_M1_PvPEligibilityAndFlagState.md new file mode 100644 index 0000000..9575a6f --- /dev/null +++ b/docs/decomposition/modules/E6_M1_PvPEligibilityAndFlagState.md @@ -0,0 +1,52 @@ +# E6.M1 — PvPEligibilityAndFlagState + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E6.M1 | +| **Epic** | [Epic 6 — PvP Security](../epics/epic_06_pvp_security.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Server-enforced rules for whether player-versus-player combat is allowed: driven by [E4.M4](E4_M4_SecurityTierZoneFlags.md) security tiers and explicit opt-in context. Ensures PvP is never client-only toggles; eligibility is authoritative and auditable. + +## Responsibilities + +- Evaluate `EligibilityRule` against current zone policy and player PvP flag / consent context. +- Maintain and transition `PvPFlagState` (or equivalent) with clear semantics for combat engine gating. +- Emit `PvPStateChanged` (or equivalent) for UI, telemetry, and downstream systems. + +## Key contracts + +| Contract | Role | +|----------|------| +| `PvPFlagState` | Current opt-in and effective PvP capability for an actor in context. | +| `EligibilityRule` | Policy mapping from tier + context to allow/deny. | +| `PvPStateChanged` | Event for subscribers (UX, analytics, combat deny reasons). | + +## Module dependencies + +- **E4.M4** — SecurityTierZoneFlags: `SecurityTier`, `ZonePolicyState`, `ZoneEntryWarning` inputs. + +## Dependents (by design) + +- **E6.M2** — ConsentAndRiskUxSignals: prompts and HUD indicators. +- **E6.M3** — LossPenaltyAndAntiGriefRules: builds on eligibility and zone context. +- **Combat resolution** — E5.M1 (or dedicated PvP branch) consults eligibility before applying player-vs-player actions (integration detail per implementation). + +## Related implementation slices + +See Epic 6 **Slice 1 — Zone-based PvP flag core**: high-sec blocks player combat; server-enforced eligibility; telemetry `pvp_state_changed`, `pvp_zone_enter`, `pvp_zone_exit`. + +## Risks and telemetry + +- PvP feeling mandatory: pair with E6.M4 reward parity and design gates from master plan. +- Griefing: high-sec safe hubs; fast iteration using telemetry and E9 integrity paths when live. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 6. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E7_M1_QuestStateMachine.md b/docs/decomposition/modules/E7_M1_QuestStateMachine.md new file mode 100644 index 0000000..6127662 --- /dev/null +++ b/docs/decomposition/modules/E7_M1_QuestStateMachine.md @@ -0,0 +1,54 @@ +# E7.M1 — QuestStateMachine + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E7.M1 | +| **Epic** | [Epic 7 — Quest / Faction](../epics/epic_07_quest_faction.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Data-driven quest lifecycle: start, step progression, branching, failure/reset, and completion with durable persistence. Integrates crafting and combat outcomes so guided content ties together gather–craft–combat loops without duplicate rewards. + +## Responsibilities + +- Load and interpret `QuestDef`; track `QuestStepState` per player (or party scope as designed). +- Apply `QuestStateTransition` rules for advance, abandon, fail, and complete. +- Invoke or subscribe to [E3.M2](E3_M2_RefinementAndRecipeExecution.md) and [E5.M1](E5_M1_CombatRulesEngine.md) (or their events) for step completion predicates. + +## Key contracts + +| Contract | Role | +|----------|------| +| `QuestDef` | Steps, prerequisites, objectives, and branching metadata. | +| `QuestStepState` | Current step progress and internal flags. | +| `QuestStateTransition` | Valid transitions and side effects (before E7.M2 reward routing). | + +## Module dependencies + +- **E3.M2** — RefinementAndRecipeExecution: craft completion, item hand-ins, refine steps. +- **E5.M1** — CombatRulesEngine: defeat objectives, encounter-linked steps. + +## Dependents (by design) + +- **E7.M2** — RewardAndUnlockRouter: idempotent delivery after completion. +- **E7.M3** — FactionReputationLedger: reputation-gated content (pre-production). +- **E5.M3** — EncounterAndRewardTables: encounter completion and quest credit. +- **E6.M4** — RewardParityEnforcer: quest/PvP reward alignment. + +## Related implementation slices + +See Epic 7 **Slice 1 — Quest core and persistence**: 3–5 onboarding quests plus one chain across gather/craft/combat; telemetry `quest_start`, `quest_step_complete`, `quest_complete`, funnel times. + +## Risks and telemetry + +- Scripting weight: keep `QuestDef` data-first; templates in decomposition/tooling path per epic. +- Double-claim: design for idempotency before E7.M2; lint bundles vs E6.M4 / E3.M5. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 7. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E9_M1_TelemetryEventSchema.md b/docs/decomposition/modules/E9_M1_TelemetryEventSchema.md new file mode 100644 index 0000000..899f90d --- /dev/null +++ b/docs/decomposition/modules/E9_M1_TelemetryEventSchema.md @@ -0,0 +1,52 @@ +# E9.M1 — TelemetryEventSchema + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E9.M1 | +| **Epic** | [Epic 9 — LiveOps / Integrity](../epics/epic_09_liveops_integrity.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Canonical taxonomy and versioning for gameplay and operations events: session, progression, economy, combat, PvP, movement desync, and integrity-adjacent signals. Provides the shared **envelope** so every epic can instrument consistently and breaking changes are explicit. + +## Responsibilities + +- Define `TelemetryEvent` shapes (or schema IDs) and required context fields. +- Govern `EventSchemaVersion` and migration rules for ingest pipelines. +- Specify `ClientEventEnvelope` (batching, privacy guardrails, delivery semantics) for prototype SDK. + +## Key contracts + +| Contract | Role | +|----------|------| +| `TelemetryEvent` | Named event with versioned payload; single registry or catalog. | +| `EventSchemaVersion` | Bump policy when fields or semantics change. | +| `ClientEventEnvelope` | Transport wrapper: timestamps, session, sampling, PII policy hooks. | + +## Module dependencies + +- **None** — horizontal capability; other modules depend on E9.M1 for event names and fields. + +## Dependents (by design) + +- **E9.M2** — KpiDashboardsAndAlerting: aggregates and gates. +- **E9.M4** — IntegrityAndAbuseResponse: correlates signals to incidents. +- **All epics** — Slices reference concrete events (e.g. `xp_grant`, `zone_enter`, `pvp_state_changed`) once schema exists. + +## Related implementation slices + +See Epic 9 **Slice 1 — Baseline event SDK and schema versioning**: prototype funnel events match master plan baseline; breaking changes versioned; telemetry for `schema_version_mismatch` and ingest errors. + +## Risks and telemetry + +- Noise drowning signals: decision-driven instrumentation, sampling strategy from master plan. +- Privacy: guardrails in envelope and field catalog before wide client shipment. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 9. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/module_dependency_register.md b/docs/decomposition/modules/module_dependency_register.md index e0da946..d9dd576 100644 --- a/docs/decomposition/modules/module_dependency_register.md +++ b/docs/decomposition/modules/module_dependency_register.md @@ -2,6 +2,8 @@ Tracks cross-epic dependencies and contract readiness. +Fleshed-out scope, contracts, and integration notes for each row below live in **per-module documents** (see [Per-module documentation](#per-module-documentation)). + ## Dependency Table | Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | @@ -16,6 +18,22 @@ Tracks cross-epic dependencies and contract readiness. | E7.M1 | QuestStateMachine | E3.M2, E5.M1 | QuestStateTransition | Prototype | Planned | | E9.M1 | TelemetryEventSchema | None | TelemetryEvent envelope | Prototype | Planned | +**Note:** E5.M1 depends on **E1.M3** (InteractionAndTargetingLayer; [Epic 1](../epics/epic_01_core_player_runtime.md)). E1.M3 is not listed as its own row in this register; document it when it is promoted to a tracked cross-epic contract. + +## Per-module documentation + +| Module ID | Document | +|-----------|----------| +| E1.M1 | [E1_M1_InputAndMovementRuntime.md](E1_M1_InputAndMovementRuntime.md) | +| E1.M2 | [E1_M2_IsometricCameraController.md](E1_M2_IsometricCameraController.md) | +| E2.M2 | [E2_M2_XpAwardAndLevelEngine.md](E2_M2_XpAwardAndLevelEngine.md) | +| E3.M2 | [E3_M2_RefinementAndRecipeExecution.md](E3_M2_RefinementAndRecipeExecution.md) | +| E4.M4 | [E4_M4_SecurityTierZoneFlags.md](E4_M4_SecurityTierZoneFlags.md) | +| E5.M1 | [E5_M1_CombatRulesEngine.md](E5_M1_CombatRulesEngine.md) | +| E6.M1 | [E6_M1_PvPEligibilityAndFlagState.md](E6_M1_PvPEligibilityAndFlagState.md) | +| E7.M1 | [E7_M1_QuestStateMachine.md](E7_M1_QuestStateMachine.md) | +| E9.M1 | [E9_M1_TelemetryEventSchema.md](E9_M1_TelemetryEventSchema.md) | + ## Status Legend - Planned: identified but not implemented