From 93eb1fc936e03736dd6c794777cecf9105d5d433 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Mon, 30 Mar 2026 18:41:57 -0400 Subject: [PATCH 01/11] 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 From 293b8a4c79901496de840c0607adc66fee2385fc Mon Sep 17 00:00:00 2001 From: VinPropane Date: Mon, 30 Mar 2026 18:48:07 -0400 Subject: [PATCH 02/11] docs: expand module register to full epic catalog (37 modules) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Split dependency table by epic; every Depends On ID is a register row - Add InteractionRequest to E1.M1 contract column per epic 1 - Footnote E4.M3 backend world services; E4.M3 register deps E4.M1 only - Add 28 new module markdown files (E1.M3–E9.M4 gaps) - Link per-module docs index to all 37 files - Cross-link existing module docs; remove obsolete E1.M3 register note from E5.M1 - Update decomposition README modules blurb Made-with: Cursor --- docs/decomposition/README.md | 2 +- .../modules/E1_M1_InputAndMovementRuntime.md | 4 +- .../E1_M3_InteractionAndTargetingLayer.md | 47 +++++++ .../modules/E1_M4_AbilityInputScaffold.md | 45 +++++++ .../modules/E2_M1_SkillDefinitionRegistry.md | 43 ++++++ .../modules/E2_M2_XpAwardAndLevelEngine.md | 4 +- .../modules/E2_M3_MasteryAndPerkUnlocks.md | 43 ++++++ .../E2_M4_ProgressionPacingControls.md | 44 +++++++ .../E3_M1_ResourceNodeAndGatherLoop.md | 45 +++++++ .../E3_M2_RefinementAndRecipeExecution.md | 10 +- .../E3_M3_ItemizationAndInventorySchema.md | 43 ++++++ .../E3_M4_SinkAndDurabilityLifecycle.md | 44 +++++++ .../modules/E3_M5_EconomyBalancePolicy.md | 45 +++++++ .../modules/E4_M1_ZoneGraphAndTravelRules.md | 44 +++++++ .../modules/E4_M2_SpawnEcologyController.md | 45 +++++++ .../E4_M3_SeamlessHandoffAndRegionState.md | 45 +++++++ .../modules/E4_M4_SecurityTierZoneFlags.md | 8 +- .../modules/E5_M1_CombatRulesEngine.md | 6 +- .../modules/E5_M2_NpcAiAndBehaviorProfiles.md | 44 +++++++ .../modules/E5_M3_EncounterAndRewardTables.md | 47 +++++++ .../modules/E5_M4_GroupCombatScaling.md | 44 +++++++ .../modules/E6_M2_ConsentAndRiskUxSignals.md | 44 +++++++ .../E6_M3_LossPenaltyAndAntiGriefRules.md | 44 +++++++ .../modules/E6_M4_RewardParityEnforcer.md | 45 +++++++ .../modules/E7_M1_QuestStateMachine.md | 8 +- .../modules/E7_M2_RewardAndUnlockRouter.md | 46 +++++++ .../modules/E7_M3_FactionReputationLedger.md | 44 +++++++ .../modules/E7_M4_ContractMissionGenerator.md | 45 +++++++ .../modules/E8_M1_PartyAndMatchAssembly.md | 44 +++++++ .../E8_M2_GuildCorpProgressionState.md | 44 +++++++ .../E8_M3_PlayerTradeAndMarketplace.md | 45 +++++++ .../E8_M4_ChatModerationAndReporting.md | 43 ++++++ .../modules/E9_M2_KpiDashboardsAndAlerting.md | 45 +++++++ .../modules/E9_M3_LiveBalanceControlPlane.md | 46 +++++++ .../E9_M4_IntegrityAndAbuseResponse.md | 44 +++++++ .../modules/module_dependency_register.md | 122 ++++++++++++++++-- 36 files changed, 1377 insertions(+), 34 deletions(-) create mode 100644 docs/decomposition/modules/E1_M3_InteractionAndTargetingLayer.md create mode 100644 docs/decomposition/modules/E1_M4_AbilityInputScaffold.md create mode 100644 docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md create mode 100644 docs/decomposition/modules/E2_M3_MasteryAndPerkUnlocks.md create mode 100644 docs/decomposition/modules/E2_M4_ProgressionPacingControls.md create mode 100644 docs/decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md create mode 100644 docs/decomposition/modules/E3_M3_ItemizationAndInventorySchema.md create mode 100644 docs/decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md create mode 100644 docs/decomposition/modules/E3_M5_EconomyBalancePolicy.md create mode 100644 docs/decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md create mode 100644 docs/decomposition/modules/E4_M2_SpawnEcologyController.md create mode 100644 docs/decomposition/modules/E4_M3_SeamlessHandoffAndRegionState.md create mode 100644 docs/decomposition/modules/E5_M2_NpcAiAndBehaviorProfiles.md create mode 100644 docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md create mode 100644 docs/decomposition/modules/E5_M4_GroupCombatScaling.md create mode 100644 docs/decomposition/modules/E6_M2_ConsentAndRiskUxSignals.md create mode 100644 docs/decomposition/modules/E6_M3_LossPenaltyAndAntiGriefRules.md create mode 100644 docs/decomposition/modules/E6_M4_RewardParityEnforcer.md create mode 100644 docs/decomposition/modules/E7_M2_RewardAndUnlockRouter.md create mode 100644 docs/decomposition/modules/E7_M3_FactionReputationLedger.md create mode 100644 docs/decomposition/modules/E7_M4_ContractMissionGenerator.md create mode 100644 docs/decomposition/modules/E8_M1_PartyAndMatchAssembly.md create mode 100644 docs/decomposition/modules/E8_M2_GuildCorpProgressionState.md create mode 100644 docs/decomposition/modules/E8_M3_PlayerTradeAndMarketplace.md create mode 100644 docs/decomposition/modules/E8_M4_ChatModerationAndReporting.md create mode 100644 docs/decomposition/modules/E9_M2_KpiDashboardsAndAlerting.md create mode 100644 docs/decomposition/modules/E9_M3_LiveBalanceControlPlane.md create mode 100644 docs/decomposition/modules/E9_M4_IntegrityAndAbuseResponse.md diff --git a/docs/decomposition/README.md b/docs/decomposition/README.md index 060e71d..b615f61 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](modules/module_dependency_register.md), one [module doc per registered module](modules/module_dependency_register.md#per-module-documentation), and interface notes. +- `modules/` - Cross-epic contracts, [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](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 index 34ee3a6..9e75afc 100644 --- a/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md +++ b/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md @@ -35,8 +35,8 @@ Contract readiness is tracked in the [module dependency register](module_depende ## 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. +- **E1.M2** — [IsometricCameraController](E1_M2_IsometricCameraController.md): stable player anchor / position. +- **E1.M3** — [InteractionAndTargetingLayer](E1_M3_InteractionAndTargetingLayer.md): interaction and targeting on movement/position. - **Downstream epics** — Gathering (E3.M1), zone transitions (E4.M1), and others consume position implicitly via higher layers. ## Related implementation slices diff --git a/docs/decomposition/modules/E1_M3_InteractionAndTargetingLayer.md b/docs/decomposition/modules/E1_M3_InteractionAndTargetingLayer.md new file mode 100644 index 0000000..331e823 --- /dev/null +++ b/docs/decomposition/modules/E1_M3_InteractionAndTargetingLayer.md @@ -0,0 +1,47 @@ +# E1.M3 — InteractionAndTargetingLayer + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E1.M3 | +| **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 + +World object selection, target lock, focus swap rules, and hover/highlight feedback. Bridges movement/position ([E1.M1](E1_M1_InputAndMovementRuntime.md)) into combat, gathering, and ability activation ([E1.M4](E1_M4_AbilityInputScaffold.md), [E5.M1](E5_M1_CombatRulesEngine.md)). + +## Responsibilities + +- Resolve `TargetState` for tab-target and interaction flows. +- Describe interactables via `InteractableDescriptor` and emit `SelectionEvent` for UI and systems. + +## Key contracts + +| Contract | Role | +|----------|------| +| `TargetState` | Current locked target, validity, and swap rules. | +| `InteractableDescriptor` | What can be selected or used in range. | +| `SelectionEvent` | Selection changes for feedback and downstream consumers. | + +## Module dependencies + +- **E1.M1** — InputAndMovementRuntime: range and position source of truth. + +## Dependents (by design) + +- **E1.M4** — AbilityInputScaffold. +- **E3.M1** — ResourceNodeAndGatherLoop. +- **E5.M1** — CombatRulesEngine. +- **E8.M1** — PartyAndMatchAssembly (player/party context hooks per epic). + +## Related implementation slices + +Epic 1 **Slice 3** — interaction, targeting, and ability input wiring with [E5.M1](E5_M1_CombatRulesEngine.md). + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 1. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E1_M4_AbilityInputScaffold.md b/docs/decomposition/modules/E1_M4_AbilityInputScaffold.md new file mode 100644 index 0000000..006314a --- /dev/null +++ b/docs/decomposition/modules/E1_M4_AbilityInputScaffold.md @@ -0,0 +1,45 @@ +# E1.M4 — AbilityInputScaffold + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E1.M4 | +| **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 + +Hotbar bindings, cooldown slot UI hooks, and the client/input path that issues `AbilityCastRequest` into [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md), using targeting from [E1.M3](E1_M3_InteractionAndTargetingLayer.md). + +## Responsibilities + +- Map hotbar slots to abilities and emit `AbilityCastRequest` with validation hints. +- Surface `HotbarLoadout` and `CooldownSnapshot` for UI sync. + +## Key contracts + +| Contract | Role | +|----------|------| +| `AbilityCastRequest` | Intent sent to combat resolution. | +| `HotbarLoadout` | Bound abilities per slot. | +| `CooldownSnapshot` | Client/server-visible cooldown state for UI. | + +## Module dependencies + +- **E1.M3** — InteractionAndTargetingLayer: target lock and cast validity. +- **E5.M1** — CombatRulesEngine: authoritative accept/deny of casts. + +## Dependents (by design) + +- Consumed by UX and telemetry; combat engine remains the authority. + +## Related implementation slices + +Epic 1 **Slice 3** — `ability_cast_requested`, `ability_cast_denied` with reason codes. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 1. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md b/docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md new file mode 100644 index 0000000..b492124 --- /dev/null +++ b/docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md @@ -0,0 +1,43 @@ +# E2.M1 — SkillDefinitionRegistry + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E2.M1 | +| **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 catalog for skill metadata, category tags, and unlock prerequisites. All prototype activities reference skills by stable IDs validated against this registry. + +## Responsibilities + +- Load and validate `SkillDef` from data; expose `SkillCategory` and `UnlockRequirement` for gating. + +## Key contracts + +| Contract | Role | +|----------|------| +| `SkillDef` | Per-skill metadata and references. | +| `SkillCategory` | Grouping for UX and balance. | +| `UnlockRequirement` | Prerequisites before XP or use counts apply. | + +## Module dependencies + +- **None** + +## Dependents (by design) + +- **E2.M2** — XpAwardAndLevelEngine (primary). + +## Related implementation slices + +Epic 2 **Slice 1** — skill registry and prototype skills; invalid references fail at load or in CI. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 2. +- [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 index 8c60881..1fe06ba 100644 --- a/docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md +++ b/docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md @@ -15,7 +15,7 @@ Central server-authoritative engine for classless skill progression: applying XP ## Responsibilities -- Apply `XpGrantEvent` (or equivalent) per skill with validated skill references from E2.M1. +- Apply `XpGrantEvent` (or equivalent) per skill with validated skill references from [E2.M1](E2_M1_SkillDefinitionRegistry.md). - Resolve experience against `LevelCurve` / threshold tables. - Emit `LevelUpEvent` when thresholds are crossed. - Support data-driven curves and reload policy agreed for prototype. @@ -30,7 +30,7 @@ Central server-authoritative engine for classless skill progression: applying XP ## Module dependencies -- **E2.M1** — SkillDefinitionRegistry: `SkillDef`, categories, and validation of skill IDs. +- **E2.M1** — [SkillDefinitionRegistry](E2_M1_SkillDefinitionRegistry.md): `SkillDef`, categories, and validation of skill IDs. ## Dependents (by design) diff --git a/docs/decomposition/modules/E2_M3_MasteryAndPerkUnlocks.md b/docs/decomposition/modules/E2_M3_MasteryAndPerkUnlocks.md new file mode 100644 index 0000000..1dd4db8 --- /dev/null +++ b/docs/decomposition/modules/E2_M3_MasteryAndPerkUnlocks.md @@ -0,0 +1,43 @@ +# E2.M3 — MasteryAndPerkUnlocks + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E2.M3 | +| **Epic** | [Epic 2 — Classless Progression](../epics/epic_02_classless_progression.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Mastery tracks and perk unlock state so classless builds have expressive identity beyond raw level curves. + +## Responsibilities + +- Progress `MasteryTrack` data; emit `PerkUnlockEvent` and persist `PerkState`. + +## Key contracts + +| Contract | Role | +|----------|------| +| `MasteryTrack` | Branch progress per design. | +| `PerkUnlockEvent` | Unlocks for UI and combat/craft hooks. | +| `PerkState` | Current unlocked perks per character. | + +## Module dependencies + +- **E2.M2** — XpAwardAndLevelEngine. + +## Dependents (by design) + +- Gameplay systems that gate abilities or recipes on perks (integration per content). + +## Related implementation slices + +Epic 2 **Slice 4** — at least one mastery path unlocks a perk without blocking other skills. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 2. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E2_M4_ProgressionPacingControls.md b/docs/decomposition/modules/E2_M4_ProgressionPacingControls.md new file mode 100644 index 0000000..f5bcd06 --- /dev/null +++ b/docs/decomposition/modules/E2_M4_ProgressionPacingControls.md @@ -0,0 +1,44 @@ +# E2.M4 — ProgressionPacingControls + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E2.M4 | +| **Epic** | [Epic 2 — Classless Progression](../epics/epic_02_classless_progression.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Tuning knobs for progression velocity and catch-up policy, informed by KPIs from [E9.M2](E9_M2_KpiDashboardsAndAlerting.md). + +## Responsibilities + +- Apply `XpModifierProfile`, `CatchUpRule`, and `PacingPolicy` without breaking skill-ID integrity from [E2.M1](E2_M1_SkillDefinitionRegistry.md) / [E2.M2](E2_M2_XpAwardAndLevelEngine.md). + +## Key contracts + +| Contract | Role | +|----------|------| +| `XpModifierProfile` | Multipliers or bands per cohort. | +| `CatchUpRule` | Acceleration for lapsed or new players. | +| `PacingPolicy` | Named policy bundles for ops toggles. | + +## Module dependencies + +- **E2.M2** — XpAwardAndLevelEngine. +- **E9.M2** — KpiDashboardsAndAlerting. + +## Dependents (by design) + +- **E9.M3** — LiveBalanceControlPlane (remote tuning). + +## Related implementation slices + +Epic 2 **Slice 4** — pacing policy toggles for test cohorts where possible without full redeploy. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 2. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md b/docs/decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md new file mode 100644 index 0000000..77e1e4a --- /dev/null +++ b/docs/decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md @@ -0,0 +1,45 @@ +# E3.M1 — ResourceNodeAndGatherLoop + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E3.M1 | +| **Epic** | [Epic 3 — Crafting Economy](../epics/epic_03_crafting_economy.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +World resource nodes, gather interactions, and yield outputs feeding inventory ([E3.M3](E3_M3_ItemizationAndInventorySchema.md)) and XP ([E2.M2](E2_M2_XpAwardAndLevelEngine.md)). + +## Responsibilities + +- Spawn/manage nodes per `ResourceNodeDef`; resolve `GatherResult` via `ResourceYieldTable`; integrate interaction range via [E1.M3](E1_M3_InteractionAndTargetingLayer.md). + +## Key contracts + +| Contract | Role | +|----------|------| +| `ResourceNodeDef` | Node type, capacity, regen. | +| `GatherResult` | Items and depletion state. | +| `ResourceYieldTable` | Probabilities or fixed yields. | + +## Module dependencies + +- **E1.M3** — InteractionAndTargetingLayer. +- **E2.M2** — XpAwardAndLevelEngine. + +## Dependents (by design) + +- **E3.M2** — RefinementAndRecipeExecution (inputs). +- **E4.M2** — SpawnEcologyController. + +## Related implementation slices + +Epic 3 **Slice 2** — 4–6 node types; `resource_gathered`, `gather_node_depleted`. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 3. +- [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 index 0c2503e..3645271 100644 --- a/docs/decomposition/modules/E3_M2_RefinementAndRecipeExecution.md +++ b/docs/decomposition/modules/E3_M2_RefinementAndRecipeExecution.md @@ -11,7 +11,7 @@ ## 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. +Implements the processing and crafting pipeline: raw-to-refined flows and recipe execution with server-authoritative inventory mutations. Bridges gathered materials ([E3.M1](E3_M1_ResourceNodeAndGatherLoop.md)) and item definitions ([E3.M3](E3_M3_ItemizationAndInventorySchema.md)) into usable outputs for combat, quests, and economy loops. ## Responsibilities @@ -29,13 +29,13 @@ Implements the processing and crafting pipeline: raw-to-refined flows and recipe ## 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. +- **E3.M1** — [ResourceNodeAndGatherLoop](E3_M1_ResourceNodeAndGatherLoop.md): refined materials from gather outputs into crafting inputs. +- **E3.M3** — [ItemizationAndInventorySchema](E3_M3_ItemizationAndInventorySchema.md): `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. +- **E7.M1** — [QuestStateMachine](E7_M1_QuestStateMachine.md): quest steps may require crafted items or craft completion. +- **E6.M4** — [RewardParityEnforcer](E6_M4_RewardParityEnforcer.md): PvP ↔ 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 diff --git a/docs/decomposition/modules/E3_M3_ItemizationAndInventorySchema.md b/docs/decomposition/modules/E3_M3_ItemizationAndInventorySchema.md new file mode 100644 index 0000000..198dcec --- /dev/null +++ b/docs/decomposition/modules/E3_M3_ItemizationAndInventorySchema.md @@ -0,0 +1,43 @@ +# E3.M3 — ItemizationAndInventorySchema + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E3.M3 | +| **Epic** | [Epic 3 — Crafting Economy](../epics/epic_03_crafting_economy.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Item definitions, rarity/quality, stackability, and equipment metadata plus `InventorySlot` representation. Foundation for craft outputs, quest rewards, combat loot, and trade. + +## Responsibilities + +- Version `ItemDef` / `ItemInstance` schema; enforce stack and slot rules server-side. + +## Key contracts + +| Contract | Role | +|----------|------| +| `ItemDef` | Static template data. | +| `ItemInstance` | Per-item state (stack, durability hook, binds). | +| `InventorySlot` | Container model for players and exchanges. | + +## Module dependencies + +- **None** + +## Dependents (by design) + +- **E3.M2**, **E3.M4**, **E5.M3**, **E7.M2**, **E8.M3**, and any system moving items. + +## Related implementation slices + +Epic 3 **Slice 1** — MVP inventory; `item_created`, transfer failures. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 3. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md b/docs/decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md new file mode 100644 index 0000000..80d10c5 --- /dev/null +++ b/docs/decomposition/modules/E3_M4_SinkAndDurabilityLifecycle.md @@ -0,0 +1,44 @@ +# E3.M4 — SinkAndDurabilityLifecycle + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E3.M4 | +| **Epic** | [Epic 3 — Crafting Economy](../epics/epic_03_crafting_economy.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Item decay, consumption, repair, and other sinks that sustain demand; may integrate with market/trade flows from [E8.M3](E8_M3_PlayerTradeAndMarketplace.md). + +## Responsibilities + +- Track `DurabilityState`; emit `ItemSinkEvent`; apply `RepairCostRule` server-authoritatively. + +## Key contracts + +| Contract | Role | +|----------|------| +| `DurabilityState` | Wear and breakage. | +| `ItemSinkEvent` | Destruction/consumption audit trail. | +| `RepairCostRule` | Currency and material costs. | + +## Module dependencies + +- **E3.M3** — ItemizationAndInventorySchema. +- **E8.M3** — PlayerTradeAndMarketplace (epic dependency for settlement-related sinks). + +## Dependents (by design) + +- **E3.M5** — EconomyBalancePolicy. + +## Related implementation slices + +Epic 3 **Slice 4** — `item_sink`, `repair_performed`. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 3. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E3_M5_EconomyBalancePolicy.md b/docs/decomposition/modules/E3_M5_EconomyBalancePolicy.md new file mode 100644 index 0000000..389df91 --- /dev/null +++ b/docs/decomposition/modules/E3_M5_EconomyBalancePolicy.md @@ -0,0 +1,45 @@ +# E3.M5 — EconomyBalancePolicy + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E3.M5 | +| **Epic** | [Epic 3 — Crafting Economy](../epics/epic_03_crafting_economy.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Faucet/sink parameter sets and guardrails for inflation/deflation; feeds alerts via [E9.M2](E9_M2_KpiDashboardsAndAlerting.md). + +## Responsibilities + +- Encode `EconomyPolicy`, `PriceBandRule`, `FaucetSinkRatio` thresholds; integrate with [E3.M4](E3_M4_SinkAndDurabilityLifecycle.md) sinks. + +## Key contracts + +| Contract | Role | +|----------|------| +| `EconomyPolicy` | Named tunable bundles. | +| `PriceBandRule` | Listing/fee bands for [E8.M3](E8_M3_PlayerTradeAndMarketplace.md). | +| `FaucetSinkRatio` | KPI targets and breach signals. | + +## Module dependencies + +- **E3.M4** — SinkAndDurabilityLifecycle. +- **E9.M2** — KpiDashboardsAndAlerting. + +## Dependents (by design) + +- **E8.M3** — marketplace fees and validation. +- **E9.M3** — LiveBalanceControlPlane. + +## Related implementation slices + +Epic 3 **Slice 4** — policy alerts on ratio breaches. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 3. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md b/docs/decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md new file mode 100644 index 0000000..645cc5b --- /dev/null +++ b/docs/decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md @@ -0,0 +1,44 @@ +# E4.M1 — ZoneGraphAndTravelRules + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E4.M1 | +| **Epic** | [Epic 4 — World Topology](../epics/epic_04_world_topology.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Regional zone graph, transition links, and travel constraints. Server and client agree on current zone id; illegal shortcuts are blocked. + +## Responsibilities + +- Author `ZoneDef` and `ZoneEdge`; evaluate `TravelRule` on transitions. + +## Key contracts + +| Contract | Role | +|----------|------| +| `ZoneDef` | Identity, bounds or graph membership. | +| `ZoneEdge` | Valid transitions. | +| `TravelRule` | Gating (level, quest, faction). | + +## Module dependencies + +- **None** + +## Dependents (by design) + +- **E4.M2**, **E4.M3**, **E4.M4** — SecurityTierZoneFlags and world layers. +- **E7.M4** — ContractMissionGenerator. + +## Related implementation slices + +Epic 4 **Slice 1** — `zone_enter`, `zone_exit`, invalid transition attempts. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 4. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E4_M2_SpawnEcologyController.md b/docs/decomposition/modules/E4_M2_SpawnEcologyController.md new file mode 100644 index 0000000..73bdaad --- /dev/null +++ b/docs/decomposition/modules/E4_M2_SpawnEcologyController.md @@ -0,0 +1,45 @@ +# E4.M2 — SpawnEcologyController + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E4.M2 | +| **Epic** | [Epic 4 — World Topology](../epics/epic_04_world_topology.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Resource and NPC spawn profiles per zone, respawn pacing, and depletion/recovery so densities stay within design bounds. + +## Responsibilities + +- Drive `SpawnProfile` / `RespawnRule`; maintain `ZoneEcologyState`; coordinate with [E3.M1](E3_M1_ResourceNodeAndGatherLoop.md) and [E5.M2](E5_M2_NpcAiAndBehaviorProfiles.md). + +## Key contracts + +| Contract | Role | +|----------|------| +| `SpawnProfile` | What spawns where and how often. | +| `RespawnRule` | Timers and caps. | +| `ZoneEcologyState` | Current density/depletion snapshot. | + +## Module dependencies + +- **E4.M1** — ZoneGraphAndTravelRules. +- **E3.M1** — ResourceNodeAndGatherLoop. +- **E5.M2** — NpcAiAndBehaviorProfiles. + +## Dependents (by design) + +- Content and live ops tuning; telemetry for spawn waves and recovery. + +## Related implementation slices + +Epic 4 **Slice 3** — `spawn_wave`, depletion/recovery markers. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 4. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E4_M3_SeamlessHandoffAndRegionState.md b/docs/decomposition/modules/E4_M3_SeamlessHandoffAndRegionState.md new file mode 100644 index 0000000..c7f98b7 --- /dev/null +++ b/docs/decomposition/modules/E4_M3_SeamlessHandoffAndRegionState.md @@ -0,0 +1,45 @@ +# E4.M3 — SeamlessHandoffAndRegionState + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E4.M3 | +| **Epic** | [Epic 4 — World Topology](../epics/epic_04_world_topology.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Cross-region handoff behavior and region authority boundaries. Minimal spike: two regions with authority transfer and no duplicate entities. + +**Epic note:** Depends on **backend world services** in addition to E4.M1; those integrations are out-of-repo contracts until defined. + +## Responsibilities + +- Orchestrate `RegionHandoffEvent`; model `RegionAuthority` and `TransferState` during handoff. + +## Key contracts + +| Contract | Role | +|----------|------| +| `RegionHandoffEvent` | Start/complete/fail lifecycle. | +| `RegionAuthority` | Which service owns simulation for an entity. | +| `TransferState` | Serializable handoff payload. | + +## Module dependencies + +- **E4.M1** — ZoneGraphAndTravelRules. + +## Dependents (by design) + +- World/shard services (external); client runtime for loading/streaming. + +## Related implementation slices + +Epic 4 **Slice 4** — `region_handoff_start`, `region_handoff_complete`, rollback path documented. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 4. +- [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 index 1430677..9a84980 100644 --- a/docs/decomposition/modules/E4_M4_SecurityTierZoneFlags.md +++ b/docs/decomposition/modules/E4_M4_SecurityTierZoneFlags.md @@ -15,7 +15,7 @@ Layer on top of the zone graph that tags each zone with security tier (e.g. high ## Responsibilities -- Assign and persist `SecurityTier` per zone (from data on E4.M1). +- Assign and persist `SecurityTier` per zone (from data on [E4.M1](E4_M1_ZoneGraphAndTravelRules.md)). - Publish `ZonePolicyState` for server and client display alignment. - Emit or serve `ZoneEntryWarning` when players transition into higher-risk zones. @@ -29,12 +29,12 @@ Layer on top of the zone graph that tags each zone with security tier (e.g. high ## Module dependencies -- **E4.M1** — ZoneGraphAndTravelRules: `ZoneDef`, edges, and travel context for tier attachment. +- **E4.M1** — [ZoneGraphAndTravelRules](E4_M1_ZoneGraphAndTravelRules.md): `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. +- **E6.M1** — [PvPEligibilityAndFlagState](E6_M1_PvPEligibilityAndFlagState.md): who may engage in PvP where. +- **E6.M2** — [ConsentAndRiskUxSignals](E6_M2_ConsentAndRiskUxSignals.md): risk UI from tier and warnings. ## Related implementation slices diff --git a/docs/decomposition/modules/E5_M1_CombatRulesEngine.md b/docs/decomposition/modules/E5_M1_CombatRulesEngine.md index a5fb6da..7405a08 100644 --- a/docs/decomposition/modules/E5_M1_CombatRulesEngine.md +++ b/docs/decomposition/modules/E5_M1_CombatRulesEngine.md @@ -30,10 +30,8 @@ Core tab-target combat resolution: valid actions against a locked target, hit re ## 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. +- **E1.M3** — [InteractionAndTargetingLayer](E1_M3_InteractionAndTargetingLayer.md): `TargetState`, selection, and alignment with **E1.M4** ([AbilityInputScaffold](E1_M4_AbilityInputScaffold.md)) for `AbilityCastRequest` wiring. +- **E2.M2** — [XpAwardAndLevelEngine](E2_M2_XpAwardAndLevelEngine.md): combat XP grants. ## Dependents (by design) diff --git a/docs/decomposition/modules/E5_M2_NpcAiAndBehaviorProfiles.md b/docs/decomposition/modules/E5_M2_NpcAiAndBehaviorProfiles.md new file mode 100644 index 0000000..ba4aae3 --- /dev/null +++ b/docs/decomposition/modules/E5_M2_NpcAiAndBehaviorProfiles.md @@ -0,0 +1,44 @@ +# E5.M2 — NpcAiAndBehaviorProfiles + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E5.M2 | +| **Epic** | [Epic 5 — PvE Combat](../epics/epic_05_pve_combat.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Enemy archetype behavior loops, aggro logic, and telegraph scheduling on top of [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md). + +## Responsibilities + +- Run `NpcBehaviorDef`; emit `TelegraphEvent`; apply `AggroRule` / threat integration with combat state. + +## Key contracts + +| Contract | Role | +|----------|------| +| `NpcBehaviorDef` | Archetype scripts or state machines. | +| `TelegraphEvent` | Telegraph timing for UI and dodge windows. | +| `AggroRule` | Target selection and leash behavior. | + +## Module dependencies + +- **E5.M1** — CombatRulesEngine. + +## Dependents (by design) + +- **E4.M2** — SpawnEcologyController. +- **E5.M3** — EncounterAndRewardTables. + +## Related implementation slices + +Epic 5 **Slice 2** — three archetypes; `telegraph_fired`, `npc_state_transition`. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 5. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md b/docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md new file mode 100644 index 0000000..5a84ba9 --- /dev/null +++ b/docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md @@ -0,0 +1,47 @@ +# E5.M3 — EncounterAndRewardTables + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E5.M3 | +| **Epic** | [Epic 5 — PvE Combat](../epics/epic_05_pve_combat.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Encounter templates, completion criteria, and reward drop routing into items ([E3.M3](E3_M3_ItemizationAndInventorySchema.md)) and quest credit via [E7.M2 — RewardAndUnlockRouter](E7_M2_RewardAndUnlockRouter.md). + +## Responsibilities + +- Instantiate `EncounterDef`; roll `RewardTable`; emit `EncounterCompleteEvent` for downstream routers and parity checks. + +## Key contracts + +| Contract | Role | +|----------|------| +| `EncounterDef` | Spawns, objectives, completion rules. | +| `RewardTable` | Loot and currency references validated against item schema. | +| `EncounterCompleteEvent` | Completion signal for quests and telemetry. | + +## Module dependencies + +- **E5.M1** — CombatRulesEngine. +- **E3.M3** — ItemizationAndInventorySchema. +- **E7.M2** — RewardAndUnlockRouter. + +## Dependents (by design) + +- **E5.M4** — GroupCombatScaling. +- **E6.M4** — RewardParityEnforcer. +- **E7.M4** — ContractMissionGenerator. + +## Related implementation slices + +Epic 5 **Slice 3** — `encounter_complete`, reward attribution once. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 5. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E5_M4_GroupCombatScaling.md b/docs/decomposition/modules/E5_M4_GroupCombatScaling.md new file mode 100644 index 0000000..de35722 --- /dev/null +++ b/docs/decomposition/modules/E5_M4_GroupCombatScaling.md @@ -0,0 +1,44 @@ +# E5.M4 — GroupCombatScaling + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E5.M4 | +| **Epic** | [Epic 5 — PvE Combat](../epics/epic_05_pve_combat.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Duo/squad scaling and anti-trivialization hooks using party context from [E8.M1 — PartyAndMatchAssembly](E8_M1_PartyAndMatchAssembly.md). + +## Responsibilities + +- Apply `ScalingProfile`, `PartySizeModifier`, and `CombatDifficultyBand` when resolving encounters ([E5.M3](E5_M3_EncounterAndRewardTables.md)). + +## Key contracts + +| Contract | Role | +|----------|------| +| `ScalingProfile` | HP/damage modifiers per party size. | +| `PartySizeModifier` | Discrete steps or curves. | +| `CombatDifficultyBand` | Named difficulty for tuning. | + +## Module dependencies + +- **E5.M3** — EncounterAndRewardTables. +- **E8.M1** — PartyAndMatchAssembly. + +## Dependents (by design) + +- Encounter runtime and telemetry `party_combat_scaling_applied`. + +## Related implementation slices + +Epic 5 **Slice 4** — duo fairness metrics. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 5. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E6_M2_ConsentAndRiskUxSignals.md b/docs/decomposition/modules/E6_M2_ConsentAndRiskUxSignals.md new file mode 100644 index 0000000..db18d13 --- /dev/null +++ b/docs/decomposition/modules/E6_M2_ConsentAndRiskUxSignals.md @@ -0,0 +1,44 @@ +# E6.M2 — ConsentAndRiskUxSignals + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E6.M2 | +| **Epic** | [Epic 6 — PvP Security](../epics/epic_06_pvp_security.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Entry warnings, in-zone risk UI, and clear PvP state communication using eligibility from [E6.M1](E6_M1_PvPEligibilityAndFlagState.md) and camera/readability context from [E1.M2](E1_M2_IsometricCameraController.md). + +## Responsibilities + +- Show `RiskPrompt` on low-sec entry; drive `ZoneRiskState` / `PvPIndicatorState` in HUD. + +## Key contracts + +| Contract | Role | +|----------|------| +| `RiskPrompt` | Consent dialog payload and outcomes. | +| `ZoneRiskState` | Display model for current zone risk. | +| `PvPIndicatorState` | Persistent indicator semantics. | + +## Module dependencies + +- **E6.M1** — PvPEligibilityAndFlagState. +- **E1.M2** — IsometricCameraController. + +## Dependents (by design) + +- Client UX only; server remains authoritative via E6.M1 / E4.M4. + +## Related implementation slices + +Epic 6 **Slice 2** — `risk_prompt_shown`, accepted/declined. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 6. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E6_M3_LossPenaltyAndAntiGriefRules.md b/docs/decomposition/modules/E6_M3_LossPenaltyAndAntiGriefRules.md new file mode 100644 index 0000000..fc49bb6 --- /dev/null +++ b/docs/decomposition/modules/E6_M3_LossPenaltyAndAntiGriefRules.md @@ -0,0 +1,44 @@ +# E6.M3 — LossPenaltyAndAntiGriefRules + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E6.M3 | +| **Epic** | [Epic 6 — PvP Security](../epics/epic_06_pvp_security.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Death/loss rules in PvP contexts, spawn protection, and abuse mitigation with escalation hooks to [E9.M4 — IntegrityAndAbuseResponse](E9_M4_IntegrityAndAbuseResponse.md). + +## Responsibilities + +- Encode `PvPLossRule`; track `SpawnProtectionState`; raise `GriefingStrike` signals for ops review. + +## Key contracts + +| Contract | Role | +|----------|------| +| `PvPLossRule` | Drop, durability, or flag penalties. | +| `SpawnProtectionState` | Timers and invuln windows. | +| `GriefingStrike` | Escalation input to integrity pipeline. | + +## Module dependencies + +- **E6.M1** — PvPEligibilityAndFlagState. +- **E9.M4** — IntegrityAndAbuseResponse. + +## Dependents (by design) + +- Combat resolution and spawn systems when in PvP context. + +## Related implementation slices + +Epic 6 **Slice 4** — `pvp_death`, `spawn_protection_applied`, `grief_flag_raised`. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 6. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E6_M4_RewardParityEnforcer.md b/docs/decomposition/modules/E6_M4_RewardParityEnforcer.md new file mode 100644 index 0000000..eb3e9fb --- /dev/null +++ b/docs/decomposition/modules/E6_M4_RewardParityEnforcer.md @@ -0,0 +1,45 @@ +# E6.M4 — RewardParityEnforcer + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E6.M4 | +| **Epic** | [Epic 6 — PvP Security](../epics/epic_06_pvp_security.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Ensure functional equivalents for PvP rewards through PvE/crafting paths; blocks ship when mapping incomplete per policy. + +## Responsibilities + +- Maintain `RewardParityMap` and `EquivalentPowerBand`; emit `ParityViolationAlert` for CI or live checks across [E3.M2](E3_M2_RefinementAndRecipeExecution.md), [E5.M3](E5_M3_EncounterAndRewardTables.md), [E7.M2](E7_M2_RewardAndUnlockRouter.md). + +## Key contracts + +| Contract | Role | +|----------|------| +| `RewardParityMap` | PvP-only reward → equivalent path. | +| `EquivalentPowerBand` | Acceptable power band comparison. | +| `ParityViolationAlert` | Blocking or warning signal. | + +## Module dependencies + +- **E3.M2** — RefinementAndRecipeExecution. +- **E5.M3** — EncounterAndRewardTables. +- **E7.M2** — RewardAndUnlockRouter. + +## Dependents (by design) + +- Release/content gates; telemetry `parity_violation`, `parity_grant_path_completed`. + +## Related implementation slices + +Epic 6 **Slice 3** — prototype sidegrade example validated. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — 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 index 6127662..6ba6e2b 100644 --- a/docs/decomposition/modules/E7_M1_QuestStateMachine.md +++ b/docs/decomposition/modules/E7_M1_QuestStateMachine.md @@ -34,10 +34,10 @@ Data-driven quest lifecycle: start, step progression, branching, failure/reset, ## 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. +- **E7.M2** — [RewardAndUnlockRouter](E7_M2_RewardAndUnlockRouter.md): idempotent delivery after completion. +- **E7.M3** — [FactionReputationLedger](E7_M3_FactionReputationLedger.md): reputation-gated content (pre-production). +- **E5.M3** — [EncounterAndRewardTables](E5_M3_EncounterAndRewardTables.md): encounter completion and quest credit. +- **E6.M4** — [RewardParityEnforcer](E6_M4_RewardParityEnforcer.md): quest/PvP reward alignment. ## Related implementation slices diff --git a/docs/decomposition/modules/E7_M2_RewardAndUnlockRouter.md b/docs/decomposition/modules/E7_M2_RewardAndUnlockRouter.md new file mode 100644 index 0000000..cf9660c --- /dev/null +++ b/docs/decomposition/modules/E7_M2_RewardAndUnlockRouter.md @@ -0,0 +1,46 @@ +# E7.M2 — RewardAndUnlockRouter + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E7.M2 | +| **Epic** | [Epic 7 — Quest / Faction](../epics/epic_07_quest_faction.md) | +| **Stage target** | Prototype | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Route quest and encounter outputs to XP, items, unlocks, and flags with **idempotent** delivery ([E7.M1](E7_M1_QuestStateMachine.md) completion, [E2.M2](E2_M2_XpAwardAndLevelEngine.md), [E3.M3](E3_M3_ItemizationAndInventorySchema.md)). + +## Responsibilities + +- Apply `QuestRewardBundle`; grant `UnlockGrant`; emit `RewardDeliveryEvent` for audit. + +## Key contracts + +| Contract | Role | +|----------|------| +| `QuestRewardBundle` | Composite rewards for a step or completion. | +| `UnlockGrant` | Blueprints, gates, cosmetics. | +| `RewardDeliveryEvent` | Idempotency key and outcome. | + +## Module dependencies + +- **E2.M2** — XpAwardAndLevelEngine. +- **E3.M3** — ItemizationAndInventorySchema. +- **E7.M1** — QuestStateMachine. + +## Dependents (by design) + +- **E5.M3** — EncounterAndRewardTables. +- **E6.M4** — RewardParityEnforcer. + +## Related implementation slices + +Epic 7 **Slice 2** — `reward_delivery`, `unlock_granted`; no double-claim on replay. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 7. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E7_M3_FactionReputationLedger.md b/docs/decomposition/modules/E7_M3_FactionReputationLedger.md new file mode 100644 index 0000000..7a1bf29 --- /dev/null +++ b/docs/decomposition/modules/E7_M3_FactionReputationLedger.md @@ -0,0 +1,44 @@ +# E7.M3 — FactionReputationLedger + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E7.M3 | +| **Epic** | [Epic 7 — Quest / Faction](../epics/epic_07_quest_faction.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Faction standing, reputation deltas, and `FactionGateRule` evaluation for content and contracts. + +## Responsibilities + +- Persist auditable `FactionStanding`; apply `ReputationDelta`; fail closed on tamper for gates. + +## Key contracts + +| Contract | Role | +|----------|------| +| `FactionStanding` | Current rep per faction. | +| `ReputationDelta` | Change events with source attribution. | +| `FactionGateRule` | Unlock conditions for content. | + +## Module dependencies + +- **E7.M1** — QuestStateMachine. + +## Dependents (by design) + +- **E7.M4** — ContractMissionGenerator. +- **E8.M2** — GuildCorpProgressionState. + +## Related implementation slices + +Epic 7 **Slice 3** — `reputation_delta`, `faction_gate_blocked`. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 7. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E7_M4_ContractMissionGenerator.md b/docs/decomposition/modules/E7_M4_ContractMissionGenerator.md new file mode 100644 index 0000000..a11e87b --- /dev/null +++ b/docs/decomposition/modules/E7_M4_ContractMissionGenerator.md @@ -0,0 +1,45 @@ +# E7.M4 — ContractMissionGenerator + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E7.M4 | +| **Epic** | [Epic 7 — Quest / Faction](../epics/epic_07_quest_faction.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Semi-procedural repeatable contracts from templates, keyed by zone difficulty ([E4.M1](E4_M1_ZoneGraphAndTravelRules.md)), encounter templates ([E5.M3](E5_M3_EncounterAndRewardTables.md)), and faction state ([E7.M3](E7_M3_FactionReputationLedger.md)). + +## Responsibilities + +- Emit validated `ContractTemplate` instances from `ContractSeed`; record `ContractOutcome`. + +## Key contracts + +| Contract | Role | +|----------|------| +| `ContractTemplate` | Parameterized mission skeleton. | +| `ContractSeed` | RNG or daily seed inputs. | +| `ContractOutcome` | Completion and reward linkage. | + +## Module dependencies + +- **E4.M1** — ZoneGraphAndTravelRules. +- **E5.M3** — EncounterAndRewardTables. +- **E7.M3** — FactionReputationLedger. + +## Dependents (by design) + +- Live ops and content pipelines; validate against economy/parity rules per epic. + +## Related implementation slices + +Epic 7 **Slice 4** — `contract_issued`, `contract_complete`, reward anomalies. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 7. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E8_M1_PartyAndMatchAssembly.md b/docs/decomposition/modules/E8_M1_PartyAndMatchAssembly.md new file mode 100644 index 0000000..814d0e6 --- /dev/null +++ b/docs/decomposition/modules/E8_M1_PartyAndMatchAssembly.md @@ -0,0 +1,44 @@ +# E8.M1 — PartyAndMatchAssembly + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E8.M1 | +| **Epic** | [Epic 8 — Social / Guild](../epics/epic_08_social_guild.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Party creation, invites, ready-state, and party-scoped hooks for cooperative activities, anchored on player identity/selection from [E1.M3](E1_M3_InteractionAndTargetingLayer.md). + +## Responsibilities + +- Server-authoritative `PartyState`; `InviteEvent` lifecycle; optional `RolePreference` for matchmaking. + +## Key contracts + +| Contract | Role | +|----------|------| +| `PartyState` | Members, leader, ready flags. | +| `InviteEvent` | Invite, accept, decline, timeout. | +| `RolePreference` | Role or build hints for assembly. | + +## Module dependencies + +- **E1.M3** — InteractionAndTargetingLayer. + +## Dependents (by design) + +- **E5.M4** — GroupCombatScaling. +- **E8.M2** — GuildCorpProgressionState. + +## Related implementation slices + +Epic 8 **Slice 1** — `party_formed`, `party_disbanded`, invite failures. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 8. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E8_M2_GuildCorpProgressionState.md b/docs/decomposition/modules/E8_M2_GuildCorpProgressionState.md new file mode 100644 index 0000000..9f8b554 --- /dev/null +++ b/docs/decomposition/modules/E8_M2_GuildCorpProgressionState.md @@ -0,0 +1,44 @@ +# E8.M2 — GuildCorpProgressionState + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E8.M2 | +| **Epic** | [Epic 8 — Social / Guild](../epics/epic_08_social_guild.md) | +| **Stage target** | Production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Guild/corp membership, rank permissions, and shared progression tied to faction/social goals via [E7.M3](E7_M3_FactionReputationLedger.md). + +## Responsibilities + +- Maintain `GuildState` and `GuildRolePolicy`; emit `GuildProgressionEvent`; prevent permission bypass griefing. + +## Key contracts + +| Contract | Role | +|----------|------| +| `GuildState` | Org roster, level, shared unlocks. | +| `GuildRolePolicy` | Permission matrix. | +| `GuildProgressionEvent` | Shared milestones. | + +## Module dependencies + +- **E8.M1** — PartyAndMatchAssembly. +- **E7.M3** — FactionReputationLedger. + +## Dependents (by design) + +- Social UI, contracts, and telemetry `guild_progression_event`. + +## Related implementation slices + +Epic 8 **Slice 4** — corp progress not griefable by solo permission bypass. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 8. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E8_M3_PlayerTradeAndMarketplace.md b/docs/decomposition/modules/E8_M3_PlayerTradeAndMarketplace.md new file mode 100644 index 0000000..1c73b77 --- /dev/null +++ b/docs/decomposition/modules/E8_M3_PlayerTradeAndMarketplace.md @@ -0,0 +1,45 @@ +# E8.M3 — PlayerTradeAndMarketplace + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E8.M3 | +| **Epic** | [Epic 8 — Social / Guild](../epics/epic_08_social_guild.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Listings, direct trade, purchases, and **atomic server settlement** for player economy, grounded in [E3.M3](E3_M3_ItemizationAndInventorySchema.md) and policy from [E3.M5](E3_M5_EconomyBalancePolicy.md). + +## Responsibilities + +- `MarketListing` / `TradeOffer` validation; `SettlementEvent` with duplication and cancel-edge coverage. + +## Key contracts + +| Contract | Role | +|----------|------| +| `MarketListing` | Seller, item, price, fees. | +| `TradeOffer` | Bilateral trade window state. | +| `SettlementEvent` | Completed exchange audit. | + +## Module dependencies + +- **E3.M3** — ItemizationAndInventorySchema. +- **E3.M5** — EconomyBalancePolicy. + +## Dependents (by design) + +- **E3.M4** — SinkAndDurabilityLifecycle (epic coupling). +- Integrity and fraud telemetry. + +## Related implementation slices + +Epic 8 **Slice 2** — `trade_completed`, `listing_created`, `purchase_completed`, fraud flags. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 8. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E8_M4_ChatModerationAndReporting.md b/docs/decomposition/modules/E8_M4_ChatModerationAndReporting.md new file mode 100644 index 0000000..96768f9 --- /dev/null +++ b/docs/decomposition/modules/E8_M4_ChatModerationAndReporting.md @@ -0,0 +1,43 @@ +# E8.M4 — ChatModerationAndReporting + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E8.M4 | +| **Epic** | [Epic 8 — Social / Guild](../epics/epic_08_social_guild.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Channel chat with rate limits, player reports, and moderation action logs escalated to [E9.M4 — IntegrityAndAbuseResponse](E9_M4_IntegrityAndAbuseResponse.md). + +## Responsibilities + +- Emit `ChatMessageEvent` with stable ids; accept `PlayerReport`; record `ModerationAction` for audit export. + +## Key contracts + +| Contract | Role | +|----------|------| +| `ChatMessageEvent` | Message payload + channel + ids. | +| `PlayerReport` | Reason codes and context. | +| `ModerationAction` | Mute/ban/warn with actor and timestamp. | + +## Module dependencies + +- **E9.M4** — IntegrityAndAbuseResponse. + +## Dependents (by design) + +- Moderator tooling and compliance exports. + +## Related implementation slices + +Epic 8 **Slice 3** — trace message id to action history in test; `chat_message_sent`, `moderation_action`. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 8. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E9_M2_KpiDashboardsAndAlerting.md b/docs/decomposition/modules/E9_M2_KpiDashboardsAndAlerting.md new file mode 100644 index 0000000..c2d9e3d --- /dev/null +++ b/docs/decomposition/modules/E9_M2_KpiDashboardsAndAlerting.md @@ -0,0 +1,45 @@ +# E9.M2 — KpiDashboardsAndAlerting + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E9.M2 | +| **Epic** | [Epic 9 — LiveOps / Integrity](../epics/epic_09_liveops_integrity.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +KPI aggregation, dashboards, trend alerts, and milestone gate signals built on [E9.M1 — TelemetryEventSchema](E9_M1_TelemetryEventSchema.md). + +## Responsibilities + +- Define `KpiDefinition` and `AlertThreshold`; emit `MilestoneGateSignal` for phase checklists. + +## Key contracts + +| Contract | Role | +|----------|------| +| `KpiDefinition` | Query + visualization binding. | +| `AlertThreshold` | Breach conditions. | +| `MilestoneGateSignal` | Pass/fail inputs for milestones. | + +## Module dependencies + +- **E9.M1** — TelemetryEventSchema. + +## Dependents (by design) + +- **E2.M4** — ProgressionPacingControls. +- **E3.M5** — EconomyBalancePolicy. +- **E9.M3** — LiveBalanceControlPlane. + +## Related implementation slices + +Epic 9 **Slice 2** — each prototype gate has at least one chart or query. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 9. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E9_M3_LiveBalanceControlPlane.md b/docs/decomposition/modules/E9_M3_LiveBalanceControlPlane.md new file mode 100644 index 0000000..55d7e5d --- /dev/null +++ b/docs/decomposition/modules/E9_M3_LiveBalanceControlPlane.md @@ -0,0 +1,46 @@ +# E9.M3 — LiveBalanceControlPlane + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E9.M3 | +| **Epic** | [Epic 9 — LiveOps / Integrity](../epics/epic_09_liveops_integrity.md) | +| **Stage target** | Production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Runtime-safe application of signed `BalancePatch` bundles to combat, progression, and economy knobs with `RolloutState` and rollback story. + +## Responsibilities + +- Version `ConfigVersion` per patch; stage `RolloutState`; integrate with [E9.M2](E9_M2_KpiDashboardsAndAlerting.md), [E5.M1](E5_M1_CombatRulesEngine.md), [E2.M4](E2_M4_ProgressionPacingControls.md), [E3.M5](E3_M5_EconomyBalancePolicy.md). + +## Key contracts + +| Contract | Role | +|----------|------| +| `BalancePatch` | Signed tunable diff bundle. | +| `ConfigVersion` | Client/server hash visibility. | +| `RolloutState` | Canary, full, rollback. | + +## Module dependencies + +- **E9.M2** — KpiDashboardsAndAlerting. +- **E5.M1** — CombatRulesEngine. +- **E2.M4** — ProgressionPacingControls. +- **E3.M5** — EconomyBalancePolicy. + +## Dependents (by design) + +- Operations UI and automated rollback SLOs. + +## Related implementation slices + +Epic 9 **Slice 4** — `balance_patch_applied`, client config hash; rollback within agreed SLO. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 9. +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/E9_M4_IntegrityAndAbuseResponse.md b/docs/decomposition/modules/E9_M4_IntegrityAndAbuseResponse.md new file mode 100644 index 0000000..f0c8054 --- /dev/null +++ b/docs/decomposition/modules/E9_M4_IntegrityAndAbuseResponse.md @@ -0,0 +1,44 @@ +# E9.M4 — IntegrityAndAbuseResponse + +## Summary + +| Field | Value | +|--------|--------| +| **Module ID** | E9.M4 | +| **Epic** | [Epic 9 — LiveOps / Integrity](../epics/epic_09_liveops_integrity.md) | +| **Stage target** | Pre-production | +| **Status** | Planned (see [dependency register](module_dependency_register.md)) | + +## Purpose + +Correlate exploit/bot signals from [E9.M1](E9_M1_TelemetryEventSchema.md) to `IncidentTicket` and `EnforcementAction` with audit trail. + +## Responsibilities + +- Ingest `IntegritySignal`; open/close incidents; log `EnforcementAction` for moderation and economy response. + +## Key contracts + +| Contract | Role | +|----------|------| +| `IntegritySignal` | Detection pipeline output. | +| `IncidentTicket` | Triage record. | +| `EnforcementAction` | Ban, rollback, warning with actor. | + +## Module dependencies + +- **E9.M1** — TelemetryEventSchema. + +## Dependents (by design) + +- **E6.M3** — LossPenaltyAndAntiGriefRules. +- **E8.M4** — ChatModerationAndReporting. + +## Related implementation slices + +Epic 9 **Slice 3** — known exploit replay produces ticket + action log; `integrity_signal`, `incident_open`, `enforcement_action`. + +## Source anchors + +- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — 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 d9dd576..4f62b7f 100644 --- a/docs/decomposition/modules/module_dependency_register.md +++ b/docs/decomposition/modules/module_dependency_register.md @@ -1,24 +1,94 @@ # Module Dependency Register -Tracks cross-epic dependencies and contract readiness. +Tracks cross-epic dependencies and contract readiness. Every **Depends On** module ID in this table has its own row (closed graph). -Fleshed-out scope, contracts, and integration notes for each row below live in **per-module documents** (see [Per-module documentation](#per-module-documentation)). +Fleshed-out scope, contracts, and integration notes live in **per-module documents** (see [Per-module documentation](#per-module-documentation)). ## Dependency Table +### Epic 1 — Core Player Runtime + | Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | |---|---|---|---|---|---| -| E1.M1 | InputAndMovementRuntime | None | MoveCommand, PositionState | Prototype | Planned | -| E1.M2 | IsometricCameraController | E1.M1 | CameraState, ZoomBandConfig | Prototype | Planned | -| E2.M2 | XpAwardAndLevelEngine | E2.M1 | XpGrantEvent, LevelUpEvent | Prototype | Planned | -| E3.M2 | RefinementAndRecipeExecution | E3.M1, E3.M3 | CraftRequest, CraftResult | Prototype | Planned | -| E5.M1 | CombatRulesEngine | E1.M3, E2.M2 | CombatAction, CombatResolution | Prototype | Planned | -| E4.M4 | SecurityTierZoneFlags | E4.M1 | SecurityTier, ZonePolicyState, ZoneEntryWarning | Prototype | Planned | -| E6.M1 | PvPEligibilityAndFlagState | E4.M4 | PvPFlagState, EligibilityRule | Prototype | Planned | -| E7.M1 | QuestStateMachine | E3.M2, E5.M1 | QuestStateTransition | Prototype | Planned | -| E9.M1 | TelemetryEventSchema | None | TelemetryEvent envelope | Prototype | Planned | +| E1.M1 | InputAndMovementRuntime | None | MoveCommand, PositionState, InteractionRequest | Prototype | Planned | +| E1.M2 | IsometricCameraController | E1.M1 | CameraState, ZoomBandConfig, OcclusionPolicy | Prototype | Planned | +| E1.M3 | InteractionAndTargetingLayer | E1.M1 | TargetState, InteractableDescriptor, SelectionEvent | Prototype | Planned | +| E1.M4 | AbilityInputScaffold | E1.M3, E5.M1 | AbilityCastRequest, HotbarLoadout, CooldownSnapshot | 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. +### Epic 2 — Classless Progression + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E2.M1 | SkillDefinitionRegistry | None | SkillDef, SkillCategory, UnlockRequirement | Prototype | Planned | +| E2.M2 | XpAwardAndLevelEngine | E2.M1 | XpGrantEvent, LevelCurve, LevelUpEvent | Prototype | Planned | +| E2.M3 | MasteryAndPerkUnlocks | E2.M2 | MasteryTrack, PerkUnlockEvent, PerkState | Pre-production | Planned | +| E2.M4 | ProgressionPacingControls | E2.M2, E9.M2 | XpModifierProfile, CatchUpRule, PacingPolicy | Pre-production | Planned | + +### Epic 3 — Crafting Economy + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E3.M1 | ResourceNodeAndGatherLoop | E1.M3, E2.M2 | ResourceNodeDef, GatherResult, ResourceYieldTable | Prototype | Planned | +| E3.M2 | RefinementAndRecipeExecution | E3.M1, E3.M3 | RecipeDef, CraftRequest, CraftResult | Prototype | Planned | +| E3.M3 | ItemizationAndInventorySchema | None | ItemDef, ItemInstance, InventorySlot | Prototype | Planned | +| E3.M4 | SinkAndDurabilityLifecycle | E3.M3, E8.M3 | DurabilityState, ItemSinkEvent, RepairCostRule | Pre-production | Planned | +| E3.M5 | EconomyBalancePolicy | E3.M4, E9.M2 | EconomyPolicy, PriceBandRule, FaucetSinkRatio | Pre-production | Planned | + +### Epic 4 — World Topology + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E4.M1 | ZoneGraphAndTravelRules | None | ZoneDef, ZoneEdge, TravelRule | Prototype | Planned | +| E4.M2 | SpawnEcologyController | E4.M1, E3.M1, E5.M2 | SpawnProfile, RespawnRule, ZoneEcologyState | Pre-production | Planned | +| E4.M3 | SeamlessHandoffAndRegionState | E4.M1 | RegionHandoffEvent, RegionAuthority, TransferState | Pre-production | Planned | +| E4.M4 | SecurityTierZoneFlags | E4.M1 | SecurityTier, ZonePolicyState, ZoneEntryWarning | Prototype | Planned | + +**E4.M3:** Epic also references backend world services for region authority; treat as external integration alongside E4.M1 contracts. + +### Epic 5 — PvE Combat + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E5.M1 | CombatRulesEngine | E1.M3, E2.M2 | CombatAction, CombatResolution, ThreatState | Prototype | Planned | +| E5.M2 | NpcAiAndBehaviorProfiles | E5.M1 | NpcBehaviorDef, TelegraphEvent, AggroRule | Prototype | Planned | +| E5.M3 | EncounterAndRewardTables | E5.M1, E3.M3, E7.M2 | EncounterDef, RewardTable, EncounterCompleteEvent | Prototype | Planned | +| E5.M4 | GroupCombatScaling | E5.M3, E8.M1 | ScalingProfile, PartySizeModifier, CombatDifficultyBand | Pre-production | Planned | + +### Epic 6 — PvP Security + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E6.M1 | PvPEligibilityAndFlagState | E4.M4 | PvPFlagState, EligibilityRule, PvPStateChanged | Prototype | Planned | +| E6.M2 | ConsentAndRiskUxSignals | E6.M1, E1.M2 | RiskPrompt, ZoneRiskState, PvPIndicatorState | Prototype | Planned | +| E6.M3 | LossPenaltyAndAntiGriefRules | E6.M1, E9.M4 | PvPLossRule, SpawnProtectionState, GriefingStrike | Pre-production | Planned | +| E6.M4 | RewardParityEnforcer | E3.M2, E5.M3, E7.M2 | RewardParityMap, EquivalentPowerBand, ParityViolationAlert | Prototype | Planned | + +### Epic 7 — Quest / Faction + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E7.M1 | QuestStateMachine | E3.M2, E5.M1 | QuestDef, QuestStepState, QuestStateTransition | Prototype | Planned | +| E7.M2 | RewardAndUnlockRouter | E2.M2, E3.M3, E7.M1 | QuestRewardBundle, UnlockGrant, RewardDeliveryEvent | Prototype | Planned | +| E7.M3 | FactionReputationLedger | E7.M1 | FactionStanding, ReputationDelta, FactionGateRule | Pre-production | Planned | +| E7.M4 | ContractMissionGenerator | E4.M1, E5.M3, E7.M3 | ContractTemplate, ContractSeed, ContractOutcome | Pre-production | Planned | + +### Epic 8 — Social / Guild + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E8.M1 | PartyAndMatchAssembly | E1.M3 | PartyState, InviteEvent, RolePreference | Pre-production | Planned | +| E8.M2 | GuildCorpProgressionState | E8.M1, E7.M3 | GuildState, GuildRolePolicy, GuildProgressionEvent | Production | Planned | +| E8.M3 | PlayerTradeAndMarketplace | E3.M3, E3.M5 | MarketListing, TradeOffer, SettlementEvent | Pre-production | Planned | +| E8.M4 | ChatModerationAndReporting | E9.M4 | ChatMessageEvent, PlayerReport, ModerationAction | Pre-production | Planned | + +### Epic 9 — LiveOps / Integrity + +| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | +|---|---|---|---|---|---| +| E9.M1 | TelemetryEventSchema | None | TelemetryEvent, EventSchemaVersion, ClientEventEnvelope | Prototype | Planned | +| E9.M2 | KpiDashboardsAndAlerting | E9.M1 | KpiDefinition, AlertThreshold, MilestoneGateSignal | Pre-production | Planned | +| E9.M3 | LiveBalanceControlPlane | E9.M2, E5.M1, E2.M4, E3.M5 | BalancePatch, ConfigVersion, RolloutState | Production | Planned | +| E9.M4 | IntegrityAndAbuseResponse | E9.M1 | IntegritySignal, IncidentTicket, EnforcementAction | Pre-production | Planned | ## Per-module documentation @@ -26,13 +96,41 @@ Fleshed-out scope, contracts, and integration notes for each row below live in * |-----------|----------| | E1.M1 | [E1_M1_InputAndMovementRuntime.md](E1_M1_InputAndMovementRuntime.md) | | E1.M2 | [E1_M2_IsometricCameraController.md](E1_M2_IsometricCameraController.md) | +| E1.M3 | [E1_M3_InteractionAndTargetingLayer.md](E1_M3_InteractionAndTargetingLayer.md) | +| E1.M4 | [E1_M4_AbilityInputScaffold.md](E1_M4_AbilityInputScaffold.md) | +| E2.M1 | [E2_M1_SkillDefinitionRegistry.md](E2_M1_SkillDefinitionRegistry.md) | | E2.M2 | [E2_M2_XpAwardAndLevelEngine.md](E2_M2_XpAwardAndLevelEngine.md) | +| E2.M3 | [E2_M3_MasteryAndPerkUnlocks.md](E2_M3_MasteryAndPerkUnlocks.md) | +| E2.M4 | [E2_M4_ProgressionPacingControls.md](E2_M4_ProgressionPacingControls.md) | +| E3.M1 | [E3_M1_ResourceNodeAndGatherLoop.md](E3_M1_ResourceNodeAndGatherLoop.md) | | E3.M2 | [E3_M2_RefinementAndRecipeExecution.md](E3_M2_RefinementAndRecipeExecution.md) | +| E3.M3 | [E3_M3_ItemizationAndInventorySchema.md](E3_M3_ItemizationAndInventorySchema.md) | +| E3.M4 | [E3_M4_SinkAndDurabilityLifecycle.md](E3_M4_SinkAndDurabilityLifecycle.md) | +| E3.M5 | [E3_M5_EconomyBalancePolicy.md](E3_M5_EconomyBalancePolicy.md) | +| E4.M1 | [E4_M1_ZoneGraphAndTravelRules.md](E4_M1_ZoneGraphAndTravelRules.md) | +| E4.M2 | [E4_M2_SpawnEcologyController.md](E4_M2_SpawnEcologyController.md) | +| E4.M3 | [E4_M3_SeamlessHandoffAndRegionState.md](E4_M3_SeamlessHandoffAndRegionState.md) | | E4.M4 | [E4_M4_SecurityTierZoneFlags.md](E4_M4_SecurityTierZoneFlags.md) | | E5.M1 | [E5_M1_CombatRulesEngine.md](E5_M1_CombatRulesEngine.md) | +| E5.M2 | [E5_M2_NpcAiAndBehaviorProfiles.md](E5_M2_NpcAiAndBehaviorProfiles.md) | +| E5.M3 | [E5_M3_EncounterAndRewardTables.md](E5_M3_EncounterAndRewardTables.md) | +| E5.M4 | [E5_M4_GroupCombatScaling.md](E5_M4_GroupCombatScaling.md) | | E6.M1 | [E6_M1_PvPEligibilityAndFlagState.md](E6_M1_PvPEligibilityAndFlagState.md) | +| E6.M2 | [E6_M2_ConsentAndRiskUxSignals.md](E6_M2_ConsentAndRiskUxSignals.md) | +| E6.M3 | [E6_M3_LossPenaltyAndAntiGriefRules.md](E6_M3_LossPenaltyAndAntiGriefRules.md) | +| E6.M4 | [E6_M4_RewardParityEnforcer.md](E6_M4_RewardParityEnforcer.md) | | E7.M1 | [E7_M1_QuestStateMachine.md](E7_M1_QuestStateMachine.md) | +| E7.M2 | [E7_M2_RewardAndUnlockRouter.md](E7_M2_RewardAndUnlockRouter.md) | +| E7.M3 | [E7_M3_FactionReputationLedger.md](E7_M3_FactionReputationLedger.md) | +| E7.M4 | [E7_M4_ContractMissionGenerator.md](E7_M4_ContractMissionGenerator.md) | +| E8.M1 | [E8_M1_PartyAndMatchAssembly.md](E8_M1_PartyAndMatchAssembly.md) | +| E8.M2 | [E8_M2_GuildCorpProgressionState.md](E8_M2_GuildCorpProgressionState.md) | +| E8.M3 | [E8_M3_PlayerTradeAndMarketplace.md](E8_M3_PlayerTradeAndMarketplace.md) | +| E8.M4 | [E8_M4_ChatModerationAndReporting.md](E8_M4_ChatModerationAndReporting.md) | | E9.M1 | [E9_M1_TelemetryEventSchema.md](E9_M1_TelemetryEventSchema.md) | +| E9.M2 | [E9_M2_KpiDashboardsAndAlerting.md](E9_M2_KpiDashboardsAndAlerting.md) | +| E9.M3 | [E9_M3_LiveBalanceControlPlane.md](E9_M3_LiveBalanceControlPlane.md) | +| E9.M4 | [E9_M4_IntegrityAndAbuseResponse.md](E9_M4_IntegrityAndAbuseResponse.md) | ## Status Legend From 8ac9953c924db16683cc7e086c51b4b33734b605 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Mon, 30 Mar 2026 18:51:35 -0400 Subject: [PATCH 03/11] docs: define contract kinds and artifacts (wire, content, telemetry) Add modules/contracts.md: Protobuf wire vs server-internal vs JSON Schema content vs telemetry catalog; mapping Key contracts to kinds; proposed contracts/ repo layout; versioning and Ready criteria. Link from dependency register, decomposition README, tech_stack Related docs; pointer from E9.M1 module doc. Made-with: Cursor --- docs/architecture/tech_stack.md | 1 + docs/decomposition/README.md | 2 +- .../modules/E9_M1_TelemetryEventSchema.md | 2 + docs/decomposition/modules/contracts.md | 79 +++++++++++++++++++ .../modules/module_dependency_register.md | 2 + 5 files changed, 85 insertions(+), 1 deletion(-) create mode 100644 docs/decomposition/modules/contracts.md diff --git a/docs/architecture/tech_stack.md b/docs/architecture/tech_stack.md index bdc24c4..6e233d7 100644 --- a/docs/architecture/tech_stack.md +++ b/docs/architecture/tech_stack.md @@ -111,3 +111,4 @@ Revisit this document if: - [`neon_sprawl_vision.plan.md`](../neon_sprawl_vision.plan.md) — product locks and phase gates - [`docs/decomposition/README.md`](../decomposition/README.md) — epic/module decomposition +- [`docs/decomposition/modules/contracts.md`](../decomposition/modules/contracts.md) — contract kinds (wire, content, telemetry), repo layout, versioning vs. register “Contract needed” diff --git a/docs/decomposition/README.md b/docs/decomposition/README.md index b615f61..1020225 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, [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](modules/module_dependency_register.md#per-module-documentation), and interface notes. +- `modules/` - [Contract definitions (what a “contract” is)](modules/contracts.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](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/E9_M1_TelemetryEventSchema.md b/docs/decomposition/modules/E9_M1_TelemetryEventSchema.md index 899f90d..5127c33 100644 --- a/docs/decomposition/modules/E9_M1_TelemetryEventSchema.md +++ b/docs/decomposition/modules/E9_M1_TelemetryEventSchema.md @@ -11,6 +11,8 @@ ## Purpose +Artifact policy for telemetry (envelope, field naming, versioning) aligns with [contracts.md — contract kinds](contracts.md#contract-kinds) and **Telemetry** row. + 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 diff --git a/docs/decomposition/modules/contracts.md b/docs/decomposition/modules/contracts.md new file mode 100644 index 0000000..896556f --- /dev/null +++ b/docs/decomposition/modules/contracts.md @@ -0,0 +1,79 @@ +# What a “contract” is (Neon Sprawl) + +Decomposition modules and the [dependency register](module_dependency_register.md) use **contract** as the name for a **stable boundary**: something two systems (client and server, two server subsystems, or server and content pipeline) can depend on without sharing an undocumented struct. + +This doc fixes **artifact types**, **ownership**, and **versioning** so “Contract needed” in the register is actionable. + +**Baseline stack alignment:** [`docs/architecture/tech_stack.md`](../../architecture/tech_stack.md) — authoritative server in C#; client in Godot/GDScript; **Protobuf** for versioned client–server messages (JSON acceptable only for the earliest spike); **JSON/YAML + JSON Schema** for content tables. + +--- + +## Contract kinds + +| Kind | Use for | Authoritative form | Typical consumers | +|------|---------|-------------------|-------------------| +| **Wire** | Player intents, state snapshots, RPC payloads crossing the network | **Protocol Buffer** `.proto` definitions; generated C# on server; mirrored types or codegen path in GDScript client | Client runtime, server host | +| **Server-internal** | Shapes used only inside the ASP.NET process (persistence DTOs, internal queues) until promoted | **C#** records/types in the server solution; behavior covered by tests | Server modules only | +| **Content** | Data-driven defs (`SkillDef`, `RecipeDef`, `QuestDef`, …) | **JSON or YAML** files + **JSON Schema** (or **CUE** later) validated in CI | Server load; tools; optional client bundles | +| **Telemetry** | Analytics and ops events ([E9.M1](E9_M1_TelemetryEventSchema.md)) | Versioned **event catalog** (JSON Schema or equivalent) + transport envelope; align names with OpenTelemetry where practical | Client emitters, ingest, dashboards | +| **HTTP (optional)** | Health, admin, or tooling — not the primary game sim path | **OpenAPI** if exposed; keep game loop on Protobuf per tech stack | Ops, CI, external tools | + +A single logical name (e.g. `MoveCommand`) might appear as a **protobuf message** on the wire and a **different** internal server type that maps to/from it; the **wire schema** is what client and server must agree on. Until Protobuf exists for a message, a spike may use JSON with an explicit **throwaway** note in PRs and a tracked issue to migrate. + +--- + +## Mapping module “Key contracts” to kinds + +Rough default (exceptions per module): + +- **Intents and state sync** (`MoveCommand`, `PositionState`, `CombatAction`, `CombatResolution`, …) → **Wire** (protobuf). +- **Catalog / defs** (`RecipeDef`, `QuestDef`, `ItemDef`, `SkillDef`, …) → **Content** (files + JSON Schema). +- **Pure server resolution** (e.g. internal threat tables, idempotency keys not sent to client) → **Server-internal** until a client or tool needs them; then promote to wire or document as admin-only HTTP. + +When unsure, default to **wire protobuf** for anything the **Godot client** must send or interpret; default to **content + schema** for anything authored as **bulk data**. + +--- + +## Repository layout (convention) + +Paths are **conventions** until the first codegen lands; adjust in one doc PR when you add the first artifact. + +| Artifact | Planned location | Notes | +|----------|------------------|--------| +| `.proto` files | `contracts/proto/` (repo root) | Keeps schemas visible to both server and client tooling; generate C# into `server/` and client bindings per chosen Godot/protobuf workflow | +| JSON Schema for content | `contracts/schemas/content/` (or co-located `schema.json` next to data) | Validate in CI before server boot in strict modes | +| Telemetry catalog | `contracts/schemas/telemetry/` or under `docs/` until ingest exists | Must carry **schema / semver** for [E9.M1](E9_M1_TelemetryEventSchema.md) | + +Server-only helpers stay next to features (e.g. `NeonSprawl.Server/Game/...`) until extracted to a shared assembly if multiple hosts need them. + +--- + +## Naming + +- Register and epics use **PascalCase** names (`CraftRequest`, `LevelUpEvent`). **Protobuf messages** use the same PascalCase style; **protobuf field names** follow `snake_case` in `.proto` if you adopt common style guides (generated C# still maps to idiomatic names). +- **JSON Schema** `$id` and file names should include a **version** or folder (`v1/`) when breaking changes ship. + +--- + +## Versioning and “Ready” + +- **Wire:** additive changes via new fields and reserved numbers; breaking changes require a **new message** or a negotiated major bump and client rollout strategy. +- **Content:** schema version in CI; server rejects or migrates unknown versions per policy. +- **Telemetry:** bump **EventSchemaVersion** (E9.M1); document in changelog for dashboards. + +A module’s register **Status** can move to **Ready** when the contracts it **exports** are published in the agreed form (proto checked in, or schema in CI, plus a minimal consumer test or stub). + +--- + +## What this doc does not decide + +- **Exact** Protobuf package layout and service vs unary choices — decide when the first real RPC is added. +- **Godot** protobuf library choice — tooling decision; still must consume the same `.proto` truth as the server. + +--- + +## Related docs + +- [`docs/architecture/tech_stack.md`](../../architecture/tech_stack.md) — Protobuf vs JSON spike, content validation, client/server split +- [Module dependency register](module_dependency_register.md) +- [Decomposition README](../README.md) diff --git a/docs/decomposition/modules/module_dependency_register.md b/docs/decomposition/modules/module_dependency_register.md index 4f62b7f..d63157a 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. Every **Depends On** module ID in this table has its own row (closed graph). +**Contract** means a stable boundary with a defined artifact (Protobuf wire message, JSON Schema content file, telemetry catalog entry, or server-internal type until promoted). See **[What a contract is](contracts.md)** for kinds, repo layout, and versioning. + Fleshed-out scope, contracts, and integration notes live in **per-module documents** (see [Per-module documentation](#per-module-documentation)). ## Dependency Table From 837251d439df3ded6566435267f239e308664095 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Mon, 30 Mar 2026 18:53:29 -0400 Subject: [PATCH 04/11] docs: client vs server authority (#3) policy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add modules/client_server_authority.md: default server truth for persistence/economy/combat; intents vs state table; E1.M1–E1.M4 and E5.M1 ownership; economy/quest/zone/PvP blanket; deferred tick rate and lag comp. Link from contracts.md, register, decomposition README, tech_stack; one-line Authority pointers in E1_M1, E1_M2, E5_M1. Fix contracts.md baseline link formatting. Made-with: Cursor --- docs/architecture/tech_stack.md | 1 + docs/decomposition/README.md | 2 +- .../modules/E1_M1_InputAndMovementRuntime.md | 2 + .../E1_M2_IsometricCameraController.md | 2 + .../modules/E5_M1_CombatRulesEngine.md | 2 + .../modules/client_server_authority.md | 82 +++++++++++++++++++ docs/decomposition/modules/contracts.md | 34 ++++---- .../modules/module_dependency_register.md | 2 +- 8 files changed, 111 insertions(+), 16 deletions(-) create mode 100644 docs/decomposition/modules/client_server_authority.md diff --git a/docs/architecture/tech_stack.md b/docs/architecture/tech_stack.md index 6e233d7..58bcbc7 100644 --- a/docs/architecture/tech_stack.md +++ b/docs/architecture/tech_stack.md @@ -112,3 +112,4 @@ Revisit this document if: - [`neon_sprawl_vision.plan.md`](../neon_sprawl_vision.plan.md) — product locks and phase gates - [`docs/decomposition/README.md`](../decomposition/README.md) — epic/module decomposition - [`docs/decomposition/modules/contracts.md`](../decomposition/modules/contracts.md) — contract kinds (wire, content, telemetry), repo layout, versioning vs. register “Contract needed” +- [`docs/decomposition/modules/client_server_authority.md`](../decomposition/modules/client_server_authority.md) — intents vs authoritative state; movement, camera, combat, economy ownership diff --git a/docs/decomposition/README.md b/docs/decomposition/README.md index 1020225..b5e6794 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/` - [Contract definitions (what a “contract” is)](modules/contracts.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](modules/module_dependency_register.md#per-module-documentation), and interface notes. +- `modules/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](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 index 9e75afc..a7aa295 100644 --- a/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md +++ b/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md @@ -11,6 +11,8 @@ ## Purpose +**Authority:** [Client vs server](client_server_authority.md#e1m1-inputandmovementruntime) — server owns `PositionState`; client sends move intent and may predict; reconcile to server. + 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 diff --git a/docs/decomposition/modules/E1_M2_IsometricCameraController.md b/docs/decomposition/modules/E1_M2_IsometricCameraController.md index 200520b..61a4719 100644 --- a/docs/decomposition/modules/E1_M2_IsometricCameraController.md +++ b/docs/decomposition/modules/E1_M2_IsometricCameraController.md @@ -11,6 +11,8 @@ ## Purpose +**Authority:** [Client vs server](client_server_authority.md#e1m2-isometriccameracontroller) — camera is client-local for prototype; server does not use camera pose for gameplay checks. + 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 diff --git a/docs/decomposition/modules/E5_M1_CombatRulesEngine.md b/docs/decomposition/modules/E5_M1_CombatRulesEngine.md index 7405a08..483320d 100644 --- a/docs/decomposition/modules/E5_M1_CombatRulesEngine.md +++ b/docs/decomposition/modules/E5_M1_CombatRulesEngine.md @@ -11,6 +11,8 @@ ## Purpose +**Authority:** [Client vs server](client_server_authority.md#e5m1-combatrulesengine) — server validates intents and computes all outcomes; never trust client damage/healing/crit/death. + 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 diff --git a/docs/decomposition/modules/client_server_authority.md b/docs/decomposition/modules/client_server_authority.md new file mode 100644 index 0000000..990c501 --- /dev/null +++ b/docs/decomposition/modules/client_server_authority.md @@ -0,0 +1,82 @@ +# Client vs server authority (Neon Sprawl) + +This doc answers **who owns truth** for gameplay-relevant state and what the client may assume or predict. It complements [contracts.md](contracts.md) (what shapes cross the wire) and [`docs/architecture/tech_stack.md`](../../architecture/tech_stack.md) (stack locks). + +--- + +## Default rule + +- **Server** is authoritative for anything that affects **persistence**, **other players**, **economy**, **progression**, **security / PvP policy**, or **anti-cheat**. +- **Client** owns **input**, **presentation**, **UI**, **camera framing**, and **optional local prediction** that must **reconcile** to the server without changing committed outcomes. + +Matches tech stack: client sends **intents**; server emits **state** (deltas or snapshots). Authoritative logic stays in **ASP.NET Core**, not Godot multiplayer templates. + +--- + +## Intents vs authoritative state + +| Direction | Content | Rule | +|-----------|---------|------| +| Client → server | **Intents** (move path, ability use, craft request, interact, chat, …) | Server validates every intent against rules, content, and current sim state. | +| Server → client | **Authoritative state** (`PositionState`, inventory, combat resolution, quest flags, zone tier, PvP eligibility, …) | Client displays and may predict; server wins on conflict. | + +Naming on the wire may use `*Command` or `*Intent` for client→server and `*State` / `*Resolution` / snapshots for server→client; the **role** (intent vs truth) matters more than the suffix. + +--- + +## By module (prototype defaults) + +### E1.M1: InputAndMovementRuntime + +- **Authoritative:** `PositionState` (and any rule derived from it: interaction range, zone presence) is owned by the **server** simulation. +- **Client:** Sends movement **intent** (e.g. destination, path id, or tick-aligned input—exact wire shape in Protobuf later). May **predict** the local avatar for responsiveness. +- **Reconciliation:** One documented ruleset: on server snapshot or correction, the client **must** converge to server truth (snap or blend—implementation choice; server outcome is final). Log material desync via [E9.M1 — TelemetryEventSchema](E9_M1_TelemetryEventSchema.md) when schema exists. +- **Deferred (not fixed here):** Sim tick rate, snapshot cadence, delta vs full snapshot protocol, and prediction smoothing curves—pick when networking MVP is scoped. + +### E1.M2: IsometricCameraController + +- **Authoritative:** **None** for prototype gameplay. Camera follow, zoom band, and occlusion are **client-local**; the server does **not** need `CameraState` for combat, zones, or PvP unless a future feature (e.g. replay) explicitly requires it. +- **Server:** Must not use client-reported camera pose for **gameplay checks** (targeting, line of sight, etc.); those use **world geometry + server-known positions**, not “what the player saw.” + +### E1.M3: InteractionAndTargetingLayer + +- **Authoritative:** Valid **target** and **interactable** eligibility (range, faction, phase, alive/dead) are decided on the **server**. Client sends selection or use **intent**; server responds with accepted `TargetState` or denial. +- **Client:** Hover, highlights, and tentative selection are presentation; may be wrong until server confirms. + +### E1.M4: AbilityInputScaffold + +- **Client:** Emits ability **intent** (`AbilityCastRequest` / equivalent) with ability id, target id, optional aim data as designed. +- **Server:** [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md) (and related systems) validate cooldowns, resources, range, facing/LOS rules, and [E6.M1](E6_M1_PvPEligibilityAndFlagState.md) where relevant; emits **CombatResolution** (or denies with reason). + +### E5.M1: CombatRulesEngine + +- **Never trust** client-supplied **damage**, **healing**, **crit rolls**, or **death** outcomes as source of truth. +- **Trust** only what the client can **observe** as intent: which action, which target, timing within tolerance—then **recompute** everything server-side from `SkillDef`, stats, and combat state. + +### Economy, crafting, inventory, quests, zones, PvP + +- **E3.\*, E7.\*, E4.\*, E6.\*:** Commit state and validate requests **only** on the server; client UI is a **view** over server-driven data. Already assumed in epics; this doc makes the split explicit for implementers. + +--- + +## Telemetry and debugging + +- **Authority violations** (client assumed an outcome the server denied) should be **visible**: denied intents with reason codes, optional lightweight desync counters—not silent fixes in production without logging. + +--- + +## What this doc does not fix yet + +- Exact **network update rate** and **interest management** (who receives which entity updates). +- **Lag compensation** model for tab-target combat (if any)—decide with combat design and E5.M1 implementation. +- **Rollback** vs **hard snap** reconciliation for movement—engineering choice after first multiplayer vertical slice. + +Revisit when the first **Protobuf** game channel and a **multiplayer** milestone are defined. + +--- + +## Related docs + +- [`docs/architecture/tech_stack.md`](../../architecture/tech_stack.md) — server-authoritative critical paths, intents vs state +- [contracts.md](contracts.md) — wire vs content artifacts +- [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/contracts.md b/docs/decomposition/modules/contracts.md index 896556f..b038627 100644 --- a/docs/decomposition/modules/contracts.md +++ b/docs/decomposition/modules/contracts.md @@ -4,19 +4,21 @@ Decomposition modules and the [dependency register](module_dependency_register.m This doc fixes **artifact types**, **ownership**, and **versioning** so “Contract needed” in the register is actionable. -**Baseline stack alignment:** [`docs/architecture/tech_stack.md`](../../architecture/tech_stack.md) — authoritative server in C#; client in Godot/GDScript; **Protobuf** for versioned client–server messages (JSON acceptable only for the earliest spike); **JSON/YAML + JSON Schema** for content tables. +**Baseline stack alignment:** [tech stack](../../architecture/tech_stack.md) — authoritative server in C#; client in Godot/GDScript; **Protobuf** for versioned client–server messages (JSON acceptable only for the earliest spike); **JSON/YAML + JSON Schema** for content tables. **Who owns truth** for movement, camera, and combat: [client vs server authority](client_server_authority.md). --- ## Contract kinds -| Kind | Use for | Authoritative form | Typical consumers | -|------|---------|-------------------|-------------------| -| **Wire** | Player intents, state snapshots, RPC payloads crossing the network | **Protocol Buffer** `.proto` definitions; generated C# on server; mirrored types or codegen path in GDScript client | Client runtime, server host | -| **Server-internal** | Shapes used only inside the ASP.NET process (persistence DTOs, internal queues) until promoted | **C#** records/types in the server solution; behavior covered by tests | Server modules only | -| **Content** | Data-driven defs (`SkillDef`, `RecipeDef`, `QuestDef`, …) | **JSON or YAML** files + **JSON Schema** (or **CUE** later) validated in CI | Server load; tools; optional client bundles | -| **Telemetry** | Analytics and ops events ([E9.M1](E9_M1_TelemetryEventSchema.md)) | Versioned **event catalog** (JSON Schema or equivalent) + transport envelope; align names with OpenTelemetry where practical | Client emitters, ingest, dashboards | -| **HTTP (optional)** | Health, admin, or tooling — not the primary game sim path | **OpenAPI** if exposed; keep game loop on Protobuf per tech stack | Ops, CI, external tools | + +| Kind | Use for | Authoritative form | Typical consumers | +| ------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | +| **Wire** | Player intents, state snapshots, RPC payloads crossing the network | **Protocol Buffer** `.proto` definitions; generated C# on server; mirrored types or codegen path in GDScript client | Client runtime, server host | +| **Server-internal** | Shapes used only inside the ASP.NET process (persistence DTOs, internal queues) until promoted | **C#** records/types in the server solution; behavior covered by tests | Server modules only | +| **Content** | Data-driven defs (`SkillDef`, `RecipeDef`, `QuestDef`, …) | **JSON or YAML** files + **JSON Schema** (or **CUE** later) validated in CI | Server load; tools; optional client bundles | +| **Telemetry** | Analytics and ops events ([E9.M1](E9_M1_TelemetryEventSchema.md)) | Versioned **event catalog** (JSON Schema or equivalent) + transport envelope; align names with OpenTelemetry where practical | Client emitters, ingest, dashboards | +| **HTTP (optional)** | Health, admin, or tooling — not the primary game sim path | **OpenAPI** if exposed; keep game loop on Protobuf per tech stack | Ops, CI, external tools | + A single logical name (e.g. `MoveCommand`) might appear as a **protobuf message** on the wire and a **different** internal server type that maps to/from it; the **wire schema** is what client and server must agree on. Until Protobuf exists for a message, a spike may use JSON with an explicit **throwaway** note in PRs and a tracked issue to migrate. @@ -38,11 +40,13 @@ When unsure, default to **wire protobuf** for anything the **Godot client** must Paths are **conventions** until the first codegen lands; adjust in one doc PR when you add the first artifact. -| Artifact | Planned location | Notes | -|----------|------------------|--------| -| `.proto` files | `contracts/proto/` (repo root) | Keeps schemas visible to both server and client tooling; generate C# into `server/` and client bindings per chosen Godot/protobuf workflow | -| JSON Schema for content | `contracts/schemas/content/` (or co-located `schema.json` next to data) | Validate in CI before server boot in strict modes | -| Telemetry catalog | `contracts/schemas/telemetry/` or under `docs/` until ingest exists | Must carry **schema / semver** for [E9.M1](E9_M1_TelemetryEventSchema.md) | + +| Artifact | Planned location | Notes | +| ----------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `.proto` files | `contracts/proto/` (repo root) | Keeps schemas visible to both server and client tooling; generate C# into `server/` and client bindings per chosen Godot/protobuf workflow | +| JSON Schema for content | `contracts/schemas/content/` (or co-located `schema.json` next to data) | Validate in CI before server boot in strict modes | +| Telemetry catalog | `contracts/schemas/telemetry/` or under `docs/` until ingest exists | Must carry **schema / semver** for [E9.M1](E9_M1_TelemetryEventSchema.md) | + Server-only helpers stay next to features (e.g. `NeonSprawl.Server/Game/...`) until extracted to a shared assembly if multiple hosts need them. @@ -74,6 +78,8 @@ A module’s register **Status** can move to **Ready** when the contracts it **e ## Related docs -- [`docs/architecture/tech_stack.md`](../../architecture/tech_stack.md) — Protobuf vs JSON spike, content validation, client/server split +- [tech stack](../../architecture/tech_stack.md) — Protobuf vs JSON spike, content validation, client/server split +- [Client vs server authority](client_server_authority.md) — intents vs state, E1/E5 defaults, deferred networking choices - [Module dependency register](module_dependency_register.md) - [Decomposition README](../README.md) + diff --git a/docs/decomposition/modules/module_dependency_register.md b/docs/decomposition/modules/module_dependency_register.md index d63157a..3c13292 100644 --- a/docs/decomposition/modules/module_dependency_register.md +++ b/docs/decomposition/modules/module_dependency_register.md @@ -2,7 +2,7 @@ Tracks cross-epic dependencies and contract readiness. Every **Depends On** module ID in this table has its own row (closed graph). -**Contract** means a stable boundary with a defined artifact (Protobuf wire message, JSON Schema content file, telemetry catalog entry, or server-internal type until promoted). See **[What a contract is](contracts.md)** for kinds, repo layout, and versioning. +**Contract** means a stable boundary with a defined artifact (Protobuf wire message, JSON Schema content file, telemetry catalog entry, or server-internal type until promoted). See **[What a contract is](contracts.md)** for kinds, repo layout, and versioning. **Authority** (who owns `PositionState`, camera, combat outcomes): **[Client vs server authority](client_server_authority.md)**. Fleshed-out scope, contracts, and integration notes live in **per-module documents** (see [Per-module documentation](#per-module-documentation)). From c9765da311cb2d1bd026c42b2a6e45076dd37699 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Mon, 30 Mar 2026 18:55:46 -0400 Subject: [PATCH 05/11] =?UTF-8?q?docs:=20PvP=20=C3=97=20combat=20engine=20?= =?UTF-8?q?integration=20(#4)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add pvp_combat_integration.md: single E5.M1 pipeline for PvE/PvP; E6.M1 gate before player-target hostility; stub for PvE-only milestones; shared kernel + profiles escape hatch; deny reason / telemetry notes; E6.M3 ordering after resolution. Register cross-cutting subsection; links from E5.M1, E6.M1, client_server_authority, contracts, decomposition README, tech_stack. Fix E6.M1 master plan link markup. Made-with: Cursor --- docs/architecture/tech_stack.md | 1 + docs/decomposition/README.md | 2 +- .../modules/E5_M1_CombatRulesEngine.md | 4 +- .../E6_M1_PvPEligibilityAndFlagState.md | 29 ++++++----- .../modules/client_server_authority.md | 2 + docs/decomposition/modules/contracts.md | 1 + .../modules/module_dependency_register.md | 6 ++- .../modules/pvp_combat_integration.md | 51 +++++++++++++++++++ 8 files changed, 81 insertions(+), 15 deletions(-) create mode 100644 docs/decomposition/modules/pvp_combat_integration.md diff --git a/docs/architecture/tech_stack.md b/docs/architecture/tech_stack.md index 58bcbc7..d628f3d 100644 --- a/docs/architecture/tech_stack.md +++ b/docs/architecture/tech_stack.md @@ -113,3 +113,4 @@ Revisit this document if: - [`docs/decomposition/README.md`](../decomposition/README.md) — epic/module decomposition - [`docs/decomposition/modules/contracts.md`](../decomposition/modules/contracts.md) — contract kinds (wire, content, telemetry), repo layout, versioning vs. register “Contract needed” - [`docs/decomposition/modules/client_server_authority.md`](../decomposition/modules/client_server_authority.md) — intents vs authoritative state; movement, camera, combat, economy ownership +- [`docs/decomposition/modules/pvp_combat_integration.md`](../decomposition/modules/pvp_combat_integration.md) — E5.M1 combat engine × E6.M1 PvP eligibility (single pipeline, deny reasons) diff --git a/docs/decomposition/README.md b/docs/decomposition/README.md index b5e6794..217ca75 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/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](modules/module_dependency_register.md#per-module-documentation), and interface notes. +- `modules/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](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/E5_M1_CombatRulesEngine.md b/docs/decomposition/modules/E5_M1_CombatRulesEngine.md index 483320d..722e3d4 100644 --- a/docs/decomposition/modules/E5_M1_CombatRulesEngine.md +++ b/docs/decomposition/modules/E5_M1_CombatRulesEngine.md @@ -15,10 +15,12 @@ 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). +**PvP:** Single engine for PvE and PvP; player-target hostility **gates** on [E6.M1](E6_M1_PvPEligibilityAndFlagState.md). See [PvP and the combat engine](pvp_combat_integration.md). + ## Responsibilities - Combat state machine for tab-target flow (attacks, abilities per prototype scope). -- Validate and apply `CombatAction`; produce `CombatResolution` for UI and logs. +- Validate and apply `CombatAction`; produce `CombatResolution` for UI and logs (include **PvP deny reasons** when player targets are blocked; see [pvp_combat_integration.md](pvp_combat_integration.md)). - Integrate with targeting/interaction from **E1.M3** (target lock, valid target checks). - Award combat XP via E2.M2 integration where specified in slices. diff --git a/docs/decomposition/modules/E6_M1_PvPEligibilityAndFlagState.md b/docs/decomposition/modules/E6_M1_PvPEligibilityAndFlagState.md index 9575a6f..4d27b0c 100644 --- a/docs/decomposition/modules/E6_M1_PvPEligibilityAndFlagState.md +++ b/docs/decomposition/modules/E6_M1_PvPEligibilityAndFlagState.md @@ -2,12 +2,14 @@ ## 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)) | + +| 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 @@ -21,11 +23,13 @@ Server-enforced rules for whether player-versus-player combat is allowed: driven ## 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). | + +| 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 @@ -35,7 +39,7 @@ Server-enforced rules for whether player-versus-player combat is allowed: driven - **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). +- **Combat resolution** — [E5.M1](E5_M1_CombatRulesEngine.md) consults E6.M1 **in the same pipeline** before applying player-target hostility; see [PvP and the combat engine](pvp_combat_integration.md). ## Related implementation slices @@ -50,3 +54,4 @@ See Epic 6 **Slice 1 — Zone-based PvP flag core**: high-sec blocks player comb - 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/client_server_authority.md b/docs/decomposition/modules/client_server_authority.md index 990c501..325a591 100644 --- a/docs/decomposition/modules/client_server_authority.md +++ b/docs/decomposition/modules/client_server_authority.md @@ -52,6 +52,7 @@ Naming on the wire may use `*Command` or `*Intent` for client→server and `*Sta - **Never trust** client-supplied **damage**, **healing**, **crit rolls**, or **death** outcomes as source of truth. - **Trust** only what the client can **observe** as intent: which action, which target, timing within tolerance—then **recompute** everything server-side from `SkillDef`, stats, and combat state. +- **Player targets:** Before applying hostile effects to another player, consult [E6.M1](E6_M1_PvPEligibilityAndFlagState.md) in-process; one combat engine for PvE and PvP — [details](pvp_combat_integration.md). ### Economy, crafting, inventory, quests, zones, PvP @@ -79,4 +80,5 @@ Revisit when the first **Protobuf** game channel and a **multiplayer** milestone - [`docs/architecture/tech_stack.md`](../../architecture/tech_stack.md) — server-authoritative critical paths, intents vs state - [contracts.md](contracts.md) — wire vs content artifacts +- [PvP and the combat engine](pvp_combat_integration.md) — E5.M1 × E6.M1 integration shape - [Module dependency register](module_dependency_register.md) diff --git a/docs/decomposition/modules/contracts.md b/docs/decomposition/modules/contracts.md index b038627..b03bcf8 100644 --- a/docs/decomposition/modules/contracts.md +++ b/docs/decomposition/modules/contracts.md @@ -80,6 +80,7 @@ A module’s register **Status** can move to **Ready** when the contracts it **e - [tech stack](../../architecture/tech_stack.md) — Protobuf vs JSON spike, content validation, client/server split - [Client vs server authority](client_server_authority.md) — intents vs state, E1/E5 defaults, deferred networking choices +- [PvP and the combat engine](pvp_combat_integration.md) — E5.M1 gating with E6.M1, deny reasons - [Module dependency register](module_dependency_register.md) - [Decomposition README](../README.md) diff --git a/docs/decomposition/modules/module_dependency_register.md b/docs/decomposition/modules/module_dependency_register.md index 3c13292..6d566bd 100644 --- a/docs/decomposition/modules/module_dependency_register.md +++ b/docs/decomposition/modules/module_dependency_register.md @@ -2,7 +2,7 @@ Tracks cross-epic dependencies and contract readiness. Every **Depends On** module ID in this table has its own row (closed graph). -**Contract** means a stable boundary with a defined artifact (Protobuf wire message, JSON Schema content file, telemetry catalog entry, or server-internal type until promoted). See **[What a contract is](contracts.md)** for kinds, repo layout, and versioning. **Authority** (who owns `PositionState`, camera, combat outcomes): **[Client vs server authority](client_server_authority.md)**. +**Contract** means a stable boundary with a defined artifact (Protobuf wire message, JSON Schema content file, telemetry catalog entry, or server-internal type until promoted). See **[What a contract is](contracts.md)** for kinds, repo layout, and versioning. **Authority** (who owns `PositionState`, camera, combat outcomes): **[Client vs server authority](client_server_authority.md)**. **PvP × combat:** **[PvP and the combat engine](pvp_combat_integration.md)**. Fleshed-out scope, contracts, and integration notes live in **per-module documents** (see [Per-module documentation](#per-module-documentation)). @@ -65,6 +65,10 @@ Fleshed-out scope, contracts, and integration notes live in **per-module documen | E6.M3 | LossPenaltyAndAntiGriefRules | E6.M1, E9.M4 | PvPLossRule, SpawnProtectionState, GriefingStrike | Pre-production | Planned | | E6.M4 | RewardParityEnforcer | E3.M2, E5.M3, E7.M2 | RewardParityMap, EquivalentPowerBand, ParityViolationAlert | Prototype | Planned | +### Cross-cutting: combat and PvP eligibility + +When hostile actions can target **players**, [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md) **must** consult [E6.M1 — PvPEligibilityAndFlagState](E6_M1_PvPEligibilityAndFlagState.md) in the same server handling path before applying effects. **PvE-only** milestones may use a **stub** that denies all player-target hostility until PvP is enabled. Shape and deny reasons: **[PvP and the combat engine](pvp_combat_integration.md)**. + ### Epic 7 — Quest / Faction | Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | diff --git a/docs/decomposition/modules/pvp_combat_integration.md b/docs/decomposition/modules/pvp_combat_integration.md new file mode 100644 index 0000000..fe99936 --- /dev/null +++ b/docs/decomposition/modules/pvp_combat_integration.md @@ -0,0 +1,51 @@ +# PvP and the combat engine (#4) + +This doc fixes **how** [E6.M1 — PvPEligibilityAndFlagState](E6_M1_PvPEligibilityAndFlagState.md) connects to [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md): one pipeline vs a forked “PvP combat” module, and how denials surface on the wire. + +Complements [client_server_authority.md](client_server_authority.md) (authority) and [contracts.md](contracts.md) (artifact types). + +--- + +## Decision: single combat rules engine + +**Default for Neon Sprawl:** **E5.M1** is the **only** combat resolution engine for tab-target play. **Player vs player** uses the **same** code path as **player vs NPC** for formulas that should stay aligned (hit checks, cooldowns, resources, ability application), with **extra gating** when the target (or victims in an AoE) include **players**. + +**Do not** introduce a separate “PvP combat engine” for the prototype unless design later proves **irreconcilable** rule divergence. If that happens, prefer a **shared resolution kernel** (pure functions / shared module) plus **policy profiles** (PvE vs PvP) rather than two divergent engines. + +**Rationale:** One engine reduces duplicate bugs, keeps `CombatAction` / `CombatResolution` as a single wire story, and matches optional-PvP product goals (PvP is policy on top of the same abilities, not a different game). + +--- + +## Where E6.M1 plugs in + +- **When:** During **validation** of a `CombatAction` (or internal equivalent) **before** applying damage, debuffs, displacement, or other hostile effects to another **player** character. +- **Who calls whom:** **E5.M1** calls into **E6.M1** (or an abstraction it owns, implemented by E6.M1) — e.g. `CanApplyHostility(attacker, target, actionContext) → Allow | Deny(reason)`. +- **Consistency:** Use **current server** eligibility and zone policy for that tick/request; avoid stale client-only flags. If eligibility is cached per session, invalidate on zone transition and on `PvPStateChanged`. + +**NPC targets:** No E6.M1 check for ordinary PvE (unless a future rule ties NPC combat to zone policy — then call out explicitly). + +**Register note:** Epic 5 lists E5.M1 dependencies as E1.M3 and E2.M2 only. **Enabling player-target hostility** adds a **logical** dependency on E6.M1; PvE-only milestones may ship with a **stub** implementation that denies all player-target hostility until Epic 6 wiring lands. See [cross-cutting note in the dependency register](module_dependency_register.md#cross-cutting-combat-and-pvp-eligibility). + +--- + +## Deny reasons and telemetry + +PvP blocks must be **first-class** in combat outcomes, not silent failures: + +- Extend the combat deny / `CombatResolution` reason set (or parallel field) with stable codes such as: `pvp_forbidden_in_zone`, `attacker_pvp_not_eligible`, `target_pvp_not_eligible`, `pvp_consent_required`, `pvp_flag_mismatch` (exact names to be frozen when Protobuf enums are defined). +- Align high-signal events with [E9.M1](E9_M1_TelemetryEventSchema.md) (e.g. ability denied with reason) and Epic 6 hooks (`pvp_state_changed`, zone enter/exit) without double-counting. + +--- + +## E6.M3 and beyond + +**E6.M3** (loss, spawn protection, grief strikes) applies **after** hostility is **allowed** by E6.M1 and **resolved** by E5.M1 (e.g. on death in PvP context). Order: **eligibility → combat resolution → loss/anti-grief rules**. + +--- + +## Related docs + +- [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md) +- [E6.M1 — PvPEligibilityAndFlagState](E6_M1_PvPEligibilityAndFlagState.md) +- [Client vs server authority](client_server_authority.md) +- [Module dependency register](module_dependency_register.md) From 137da33dcc3c0d75daf21685d8dc5d0bdd109765 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Mon, 30 Mar 2026 18:58:23 -0400 Subject: [PATCH 06/11] docs: quest scope and party rules (#5) Add quest_scope_and_party.md: per-character QuestStepState default; QuestDef modes for solo vs party credit and optional leader turn-in; E8.M1 dependency for party features; E7.M2 per-character rewards; open-world prototype default; instance_id binding deferred; edge cases and telemetry. Register cross-cutting subsection + intro link; update E7.M1, E7.M2, E8.M1; contracts, decomposition README, tech_stack related docs. Made-with: Cursor --- docs/architecture/tech_stack.md | 1 + docs/decomposition/README.md | 2 +- .../modules/E7_M1_QuestStateMachine.md | 4 +- .../modules/E7_M2_RewardAndUnlockRouter.md | 2 +- .../modules/E8_M1_PartyAndMatchAssembly.md | 1 + docs/decomposition/modules/contracts.md | 1 + .../modules/module_dependency_register.md | 6 +- .../modules/quest_scope_and_party.md | 69 +++++++++++++++++++ 8 files changed, 82 insertions(+), 4 deletions(-) create mode 100644 docs/decomposition/modules/quest_scope_and_party.md diff --git a/docs/architecture/tech_stack.md b/docs/architecture/tech_stack.md index d628f3d..0432578 100644 --- a/docs/architecture/tech_stack.md +++ b/docs/architecture/tech_stack.md @@ -114,3 +114,4 @@ Revisit this document if: - [`docs/decomposition/modules/contracts.md`](../decomposition/modules/contracts.md) — contract kinds (wire, content, telemetry), repo layout, versioning vs. register “Contract needed” - [`docs/decomposition/modules/client_server_authority.md`](../decomposition/modules/client_server_authority.md) — intents vs authoritative state; movement, camera, combat, economy ownership - [`docs/decomposition/modules/pvp_combat_integration.md`](../decomposition/modules/pvp_combat_integration.md) — E5.M1 combat engine × E6.M1 PvP eligibility (single pipeline, deny reasons) +- [`docs/decomposition/modules/quest_scope_and_party.md`](../decomposition/modules/quest_scope_and_party.md) — quest state per character, party credit, turn-in, instance deferral diff --git a/docs/decomposition/README.md b/docs/decomposition/README.md index 217ca75..0ef09d6 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/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](modules/module_dependency_register.md#per-module-documentation), and interface notes. +- `modules/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [quest scope × party](modules/quest_scope_and_party.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](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/E7_M1_QuestStateMachine.md b/docs/decomposition/modules/E7_M1_QuestStateMachine.md index 6ba6e2b..5b9f225 100644 --- a/docs/decomposition/modules/E7_M1_QuestStateMachine.md +++ b/docs/decomposition/modules/E7_M1_QuestStateMachine.md @@ -13,9 +13,11 @@ 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. +**Scope / party:** [Per-character state by default](quest_scope_and_party.md#persistence-per-character-by-default); optional [party credit and turn-in rules](quest_scope_and_party.md#quest-modes-content-driven) via `QuestDef` and [E8.M1](E8_M1_PartyAndMatchAssembly.md). + ## Responsibilities -- Load and interpret `QuestDef`; track `QuestStepState` per player (or party scope as designed). +- Load and interpret `QuestDef`; track `QuestStepState` **per character**; synchronize party-credit advances per [quest_scope_and_party.md](quest_scope_and_party.md). - 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. diff --git a/docs/decomposition/modules/E7_M2_RewardAndUnlockRouter.md b/docs/decomposition/modules/E7_M2_RewardAndUnlockRouter.md index cf9660c..38cde7c 100644 --- a/docs/decomposition/modules/E7_M2_RewardAndUnlockRouter.md +++ b/docs/decomposition/modules/E7_M2_RewardAndUnlockRouter.md @@ -11,7 +11,7 @@ ## Purpose -Route quest and encounter outputs to XP, items, unlocks, and flags with **idempotent** delivery ([E7.M1](E7_M1_QuestStateMachine.md) completion, [E2.M2](E2_M2_XpAwardAndLevelEngine.md), [E3.M3](E3_M3_ItemizationAndInventorySchema.md)). +Route quest and encounter outputs to XP, items, unlocks, and flags with **idempotent** delivery ([E7.M1](E7_M1_QuestStateMachine.md) completion, [E2.M2](E2_M2_XpAwardAndLevelEngine.md), [E3.M3](E3_M3_ItemizationAndInventorySchema.md)). **Party:** [Per-character idempotent grants](quest_scope_and_party.md#rewards-e7m2) when party credit completes multiple characters. ## Responsibilities diff --git a/docs/decomposition/modules/E8_M1_PartyAndMatchAssembly.md b/docs/decomposition/modules/E8_M1_PartyAndMatchAssembly.md index 814d0e6..ef50c14 100644 --- a/docs/decomposition/modules/E8_M1_PartyAndMatchAssembly.md +++ b/docs/decomposition/modules/E8_M1_PartyAndMatchAssembly.md @@ -33,6 +33,7 @@ Party creation, invites, ready-state, and party-scoped hooks for cooperative act - **E5.M4** — GroupCombatScaling. - **E8.M2** — GuildCorpProgressionState. +- **E7.M1** — [QuestStateMachine](E7_M1_QuestStateMachine.md) when `QuestDef` uses party credit or leader-only turn-in ([quest scope](quest_scope_and_party.md)). ## Related implementation slices diff --git a/docs/decomposition/modules/contracts.md b/docs/decomposition/modules/contracts.md index b03bcf8..cc3f169 100644 --- a/docs/decomposition/modules/contracts.md +++ b/docs/decomposition/modules/contracts.md @@ -81,6 +81,7 @@ A module’s register **Status** can move to **Ready** when the contracts it **e - [tech stack](../../architecture/tech_stack.md) — Protobuf vs JSON spike, content validation, client/server split - [Client vs server authority](client_server_authority.md) — intents vs state, E1/E5 defaults, deferred networking choices - [PvP and the combat engine](pvp_combat_integration.md) — E5.M1 gating with E6.M1, deny reasons +- [Quest scope and party rules](quest_scope_and_party.md) — per-character quest state, party credit, turn-in - [Module dependency register](module_dependency_register.md) - [Decomposition README](../README.md) diff --git a/docs/decomposition/modules/module_dependency_register.md b/docs/decomposition/modules/module_dependency_register.md index 6d566bd..5a06862 100644 --- a/docs/decomposition/modules/module_dependency_register.md +++ b/docs/decomposition/modules/module_dependency_register.md @@ -2,7 +2,7 @@ Tracks cross-epic dependencies and contract readiness. Every **Depends On** module ID in this table has its own row (closed graph). -**Contract** means a stable boundary with a defined artifact (Protobuf wire message, JSON Schema content file, telemetry catalog entry, or server-internal type until promoted). See **[What a contract is](contracts.md)** for kinds, repo layout, and versioning. **Authority** (who owns `PositionState`, camera, combat outcomes): **[Client vs server authority](client_server_authority.md)**. **PvP × combat:** **[PvP and the combat engine](pvp_combat_integration.md)**. +**Contract** means a stable boundary with a defined artifact (Protobuf wire message, JSON Schema content file, telemetry catalog entry, or server-internal type until promoted). See **[What a contract is](contracts.md)** for kinds, repo layout, and versioning. **Authority** (who owns `PositionState`, camera, combat outcomes): **[Client vs server authority](client_server_authority.md)**. **PvP × combat:** **[PvP and the combat engine](pvp_combat_integration.md)**. **Quests × party:** **[Quest scope and party rules](quest_scope_and_party.md)**. Fleshed-out scope, contracts, and integration notes live in **per-module documents** (see [Per-module documentation](#per-module-documentation)). @@ -69,6 +69,10 @@ Fleshed-out scope, contracts, and integration notes live in **per-module documen When hostile actions can target **players**, [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md) **must** consult [E6.M1 — PvPEligibilityAndFlagState](E6_M1_PvPEligibilityAndFlagState.md) in the same server handling path before applying effects. **PvE-only** milestones may use a **stub** that denies all player-target hostility until PvP is enabled. Shape and deny reasons: **[PvP and the combat engine](pvp_combat_integration.md)**. +### Cross-cutting: quests and party + +Quest state is **per-character** by default; **party credit** and **leader-only turn-in** use [E8.M1 — PartyAndMatchAssembly](E8_M1_PartyAndMatchAssembly.md) when enabled in `QuestDef`. Solo milestones need no party service. Details: **[Quest scope and party rules](quest_scope_and_party.md)**. + ### Epic 7 — Quest / Faction | Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | diff --git a/docs/decomposition/modules/quest_scope_and_party.md b/docs/decomposition/modules/quest_scope_and_party.md new file mode 100644 index 0000000..f3be842 --- /dev/null +++ b/docs/decomposition/modules/quest_scope_and_party.md @@ -0,0 +1,69 @@ +# Quest scope and party rules (#5) + +This doc fixes **solo vs party** quest behavior: where `QuestStepState` lives, who gets credit, who can turn in, and how open-world vs instanced scope is handled. It complements [E7.M1 — QuestStateMachine](E7_M1_QuestStateMachine.md), [E7.M2 — RewardAndUnlockRouter](E7_M2_RewardAndUnlockRouter.md), and [E8.M1 — PartyAndMatchAssembly](E8_M1_PartyAndMatchAssembly.md). + +--- + +## Persistence: per-character by default + +- **Authoritative state** for a quest is stored **per character** (`QuestStepState` keyed by character / player id, plus quest id and any run id if replays exist). +- There is **no** single shared “party quest row” in the prototype model; party play is expressed by **synchronizing advances** across multiple per-character states when content opts in (see below). + +**Rationale:** Avoids orphan state when members leave the party, keeps abandon/reset rules simple, and matches “classless solo-friendly” progression with optional co-op credit. + +--- + +## Quest modes (content-driven) + +Express in **`QuestDef`** (or equivalent content) — exact field names are for the content schema when added: + +| Mode | Behavior | +|------|----------| +| **Solo (default)** | Objectives and completion use **only** the acting character. No read of [E8.M1](E8_M1_PartyAndMatchAssembly.md) `PartyState`. | +| **Party credit** | When an objective completes, the server evaluates **eligible party members** and advances **each** eligible character’s `QuestStepState` **idem**potently (same step transition, no double-apply). Eligibility rules are data-driven, e.g. in zone, within distance of completer, alive, was in party when step started—minimum set TBD per quest in content. | +| **Leader-only turn-in (optional)** | If set, only the **party leader** (per authoritative `PartyState`) may trigger the final hand-in / complete interaction; otherwise **any** character in completable state may turn in. | + +**Starting / accepting:** Each character **accepts** the quest individually unless content defines a rare “party accepts as one” flow (defer unless needed); prototype can require all intended recipients to accept the same quest id. + +--- + +## Party dependency + +- **Party credit** and **leader-only turn-in** require server-authoritative **party membership** from [E8.M1 — PartyAndMatchAssembly](E8_M1_PartyAndMatchAssembly.md). +- **Milestone ordering:** Solo quests ship without E8.M1. **Party-credit** quests are **gated** until E8.M1 (or a minimal stub that returns “solo only”) exists; document in slice plans. + +--- + +## Rewards: E7.M2 + +- After completion, **rewards are granted per character** with **idempotent** keys (e.g. `(character_id, quest_id, completion_epoch_or_counter)`). +- If **party credit** advanced multiple characters to completion in one logical event, **each** receives their bundle per `QuestRewardBundle` rules (same bundle vs per-role bundles—content choice). + +--- + +## Open world vs instances (prototype) + +- **Prototype default:** Objectives live in **shared zones** ([E4.M1](E4_M1_ZoneGraphAndTravelRules.md)); no separate quest instance id required. +- **Instanced steps (later):** When dungeon / private instance exists, bind objectives to an **`instance_id`** (or shard key) so credit does not leak across instances. Wire when instance module and E4 handoff slices define the authoritative instance handle. + +--- + +## Edge cases (explicit) + +- **Member leaves party mid-quest:** Per-character state **freezes** at last server-advanced step unless `QuestDef` defines abandon-on-leave. No implicit merge of two solo runs into one party run. +- **Disband:** Same as leave for remaining members; leader-only turn-in re-evaluates on next `PartyState` update. + +--- + +## Telemetry + +- Emit `quest_step_complete` / `quest_complete` **per character** credited; optional correlation id linking party-synchronized advances for funnel debugging. + +--- + +## Related docs + +- [E7.M1 — QuestStateMachine](E7_M1_QuestStateMachine.md) +- [E7.M2 — RewardAndUnlockRouter](E7_M2_RewardAndUnlockRouter.md) +- [E8.M1 — PartyAndMatchAssembly](E8_M1_PartyAndMatchAssembly.md) +- [Module dependency register — cross-cutting: quests and party](module_dependency_register.md#cross-cutting-quests-and-party) From 0f25edb86ad51d4abc6a89022d2c9d053c81bb73 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Mon, 30 Mar 2026 19:00:06 -0400 Subject: [PATCH 07/11] docs: drop conversation-only (#4)/(#5) from module doc titles Made-with: Cursor --- docs/decomposition/modules/pvp_combat_integration.md | 2 +- docs/decomposition/modules/quest_scope_and_party.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/decomposition/modules/pvp_combat_integration.md b/docs/decomposition/modules/pvp_combat_integration.md index fe99936..e831782 100644 --- a/docs/decomposition/modules/pvp_combat_integration.md +++ b/docs/decomposition/modules/pvp_combat_integration.md @@ -1,4 +1,4 @@ -# PvP and the combat engine (#4) +# PvP and the combat engine This doc fixes **how** [E6.M1 — PvPEligibilityAndFlagState](E6_M1_PvPEligibilityAndFlagState.md) connects to [E5.M1 — CombatRulesEngine](E5_M1_CombatRulesEngine.md): one pipeline vs a forked “PvP combat” module, and how denials surface on the wire. diff --git a/docs/decomposition/modules/quest_scope_and_party.md b/docs/decomposition/modules/quest_scope_and_party.md index f3be842..eb6e04e 100644 --- a/docs/decomposition/modules/quest_scope_and_party.md +++ b/docs/decomposition/modules/quest_scope_and_party.md @@ -1,4 +1,4 @@ -# Quest scope and party rules (#5) +# Quest scope and party rules This doc fixes **solo vs party** quest behavior: where `QuestStepState` lives, who gets credit, who can turn in, and how open-world vs instanced scope is handled. It complements [E7.M1 — QuestStateMachine](E7_M1_QuestStateMachine.md), [E7.M2 — RewardAndUnlockRouter](E7_M2_RewardAndUnlockRouter.md), and [E8.M1 — PartyAndMatchAssembly](E8_M1_PartyAndMatchAssembly.md). From 4a510847b76ac0a4617b845be4cd08e3afb18e42 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Mon, 30 Mar 2026 19:00:59 -0400 Subject: [PATCH 08/11] docs: data reload and telemetry operations policy (#6) Add data_and_ops_policy.md: boot-time content load, optional dev reload, E9.M3/E2.M4 for live tuning; telemetry PII rules, sampling, retention principles; baseline events from vision plan with future catalog as field source of truth. Register cross-cutting + intro; E9.M1, E2.M2, contracts, decomposition README, tech_stack (Related + Observability pointer). Made-with: Cursor --- docs/architecture/tech_stack.md | 3 +- docs/decomposition/README.md | 2 +- .../modules/E2_M2_XpAwardAndLevelEngine.md | 2 +- .../modules/E9_M1_TelemetryEventSchema.md | 2 +- docs/decomposition/modules/contracts.md | 1 + .../modules/data_and_ops_policy.md | 59 +++++++++++++++++++ .../modules/module_dependency_register.md | 6 +- 7 files changed, 70 insertions(+), 5 deletions(-) create mode 100644 docs/decomposition/modules/data_and_ops_policy.md diff --git a/docs/architecture/tech_stack.md b/docs/architecture/tech_stack.md index 0432578..18a8487 100644 --- a/docs/architecture/tech_stack.md +++ b/docs/architecture/tech_stack.md @@ -85,7 +85,7 @@ The [`client/`](../../client/) Godot project targets **4.6** (`config/features` ## Observability - **Serilog** and/or **OpenTelemetry** for .NET from early prototype. -- Align event names with `E9.M1 TelemetryEventSchema` in the vision doc; client batches to server or OTLP endpoint as capacity allows. +- Align event names with `E9.M1 TelemetryEventSchema` in the vision doc; client batches to server or OTLP endpoint as capacity allows. **PII, sampling, retention, reload:** [`docs/decomposition/modules/data_and_ops_policy.md`](../decomposition/modules/data_and_ops_policy.md). ## Security (proportionate to phase) @@ -115,3 +115,4 @@ Revisit this document if: - [`docs/decomposition/modules/client_server_authority.md`](../decomposition/modules/client_server_authority.md) — intents vs authoritative state; movement, camera, combat, economy ownership - [`docs/decomposition/modules/pvp_combat_integration.md`](../decomposition/modules/pvp_combat_integration.md) — E5.M1 combat engine × E6.M1 PvP eligibility (single pipeline, deny reasons) - [`docs/decomposition/modules/quest_scope_and_party.md`](../decomposition/modules/quest_scope_and_party.md) — quest state per character, party credit, turn-in, instance deferral +- [`docs/decomposition/modules/data_and_ops_policy.md`](../decomposition/modules/data_and_ops_policy.md) — content boot load vs dev reload, telemetry PII/sampling/retention, baseline events vs vision plan diff --git a/docs/decomposition/README.md b/docs/decomposition/README.md index 0ef09d6..9cbbad1 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/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [quest scope × party](modules/quest_scope_and_party.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](modules/module_dependency_register.md#per-module-documentation), and interface notes. +- `modules/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [quest scope × party](modules/quest_scope_and_party.md), [data reload × telemetry ops](modules/data_and_ops_policy.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](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/E2_M2_XpAwardAndLevelEngine.md b/docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md index 1fe06ba..a75d636 100644 --- a/docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md +++ b/docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md @@ -18,7 +18,7 @@ Central server-authoritative engine for classless skill progression: applying XP - Apply `XpGrantEvent` (or equivalent) per skill with validated skill references from [E2.M1](E2_M1_SkillDefinitionRegistry.md). - Resolve experience against `LevelCurve` / threshold tables. - Emit `LevelUpEvent` when thresholds are crossed. -- Support data-driven curves and reload policy agreed for prototype. +- Support data-driven curves; **reload policy:** [Data reload and telemetry operations policy](data_and_ops_policy.md#content-and-gameplay-data-reload) (boot load default; optional dev reload). ## Key contracts diff --git a/docs/decomposition/modules/E9_M1_TelemetryEventSchema.md b/docs/decomposition/modules/E9_M1_TelemetryEventSchema.md index 5127c33..34fc30a 100644 --- a/docs/decomposition/modules/E9_M1_TelemetryEventSchema.md +++ b/docs/decomposition/modules/E9_M1_TelemetryEventSchema.md @@ -11,7 +11,7 @@ ## Purpose -Artifact policy for telemetry (envelope, field naming, versioning) aligns with [contracts.md — contract kinds](contracts.md#contract-kinds) and **Telemetry** row. +Artifact policy for telemetry (envelope, field naming, versioning) aligns with [contracts.md — contract kinds](contracts.md#contract-kinds) and **Telemetry** row. **PII, sampling, retention, baseline list:** [Data reload and telemetry operations policy](data_and_ops_policy.md). 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. diff --git a/docs/decomposition/modules/contracts.md b/docs/decomposition/modules/contracts.md index cc3f169..d225271 100644 --- a/docs/decomposition/modules/contracts.md +++ b/docs/decomposition/modules/contracts.md @@ -82,6 +82,7 @@ A module’s register **Status** can move to **Ready** when the contracts it **e - [Client vs server authority](client_server_authority.md) — intents vs state, E1/E5 defaults, deferred networking choices - [PvP and the combat engine](pvp_combat_integration.md) — E5.M1 gating with E6.M1, deny reasons - [Quest scope and party rules](quest_scope_and_party.md) — per-character quest state, party credit, turn-in +- [Data reload and telemetry operations policy](data_and_ops_policy.md) — content reload, PII, sampling, retention, baseline events - [Module dependency register](module_dependency_register.md) - [Decomposition README](../README.md) diff --git a/docs/decomposition/modules/data_and_ops_policy.md b/docs/decomposition/modules/data_and_ops_policy.md new file mode 100644 index 0000000..0b112c9 --- /dev/null +++ b/docs/decomposition/modules/data_and_ops_policy.md @@ -0,0 +1,59 @@ +# 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) diff --git a/docs/decomposition/modules/module_dependency_register.md b/docs/decomposition/modules/module_dependency_register.md index 5a06862..2e2a830 100644 --- a/docs/decomposition/modules/module_dependency_register.md +++ b/docs/decomposition/modules/module_dependency_register.md @@ -2,7 +2,7 @@ Tracks cross-epic dependencies and contract readiness. Every **Depends On** module ID in this table has its own row (closed graph). -**Contract** means a stable boundary with a defined artifact (Protobuf wire message, JSON Schema content file, telemetry catalog entry, or server-internal type until promoted). See **[What a contract is](contracts.md)** for kinds, repo layout, and versioning. **Authority** (who owns `PositionState`, camera, combat outcomes): **[Client vs server authority](client_server_authority.md)**. **PvP × combat:** **[PvP and the combat engine](pvp_combat_integration.md)**. **Quests × party:** **[Quest scope and party rules](quest_scope_and_party.md)**. +**Contract** means a stable boundary with a defined artifact (Protobuf wire message, JSON Schema content file, telemetry catalog entry, or server-internal type until promoted). See **[What a contract is](contracts.md)** for kinds, repo layout, and versioning. **Authority** (who owns `PositionState`, camera, combat outcomes): **[Client vs server authority](client_server_authority.md)**. **PvP × combat:** **[PvP and the combat engine](pvp_combat_integration.md)**. **Quests × party:** **[Quest scope and party rules](quest_scope_and_party.md)**. **Data reload × telemetry ops:** **[Data reload and telemetry operations policy](data_and_ops_policy.md)**. Fleshed-out scope, contracts, and integration notes live in **per-module documents** (see [Per-module documentation](#per-module-documentation)). @@ -73,6 +73,10 @@ When hostile actions can target **players**, [E5.M1 — CombatRulesEngine](E5_M1 Quest state is **per-character** by default; **party credit** and **leader-only turn-in** use [E8.M1 — PartyAndMatchAssembly](E8_M1_PartyAndMatchAssembly.md) when enabled in `QuestDef`. Solo milestones need no party service. Details: **[Quest scope and party rules](quest_scope_and_party.md)**. +### Cross-cutting: data reload and telemetry + +Gameplay **content and curves** default to **boot load** with optional **dev-only** reload; live tuning defers to **E9.M3 / E2.M4** when available. **Telemetry:** PII rules, sampling, retention principles, and **baseline event taxonomy** (vision plan + future catalog). See **[Data reload and telemetry operations policy](data_and_ops_policy.md)**. + ### Epic 7 — Quest / Faction | Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | From c47892c782ba9c99f00fd54286ee75b5bd8a6a5a Mon Sep 17 00:00:00 2001 From: VinPropane Date: Mon, 30 Mar 2026 19:03:03 -0400 Subject: [PATCH 09/11] docs: documentation vs implementation alignment (#7) Add documentation_and_implementation_alignment.md: register Status semantics, Planned vs partial work, per-module snapshot guidance, implementation tracking table (E1.M1 + NS-15). Expand register Status legend; set E1.M1 to In Progress; E1.M1 module doc Implementation snapshot and status. Link from contracts, decomposition README, tech_stack. Made-with: Cursor --- docs/architecture/tech_stack.md | 1 + docs/decomposition/README.md | 2 +- .../modules/E1_M1_InputAndMovementRuntime.md | 8 ++- docs/decomposition/modules/contracts.md | 1 + ...umentation_and_implementation_alignment.md | 55 +++++++++++++++++++ .../modules/module_dependency_register.md | 14 +++-- 6 files changed, 73 insertions(+), 8 deletions(-) create mode 100644 docs/decomposition/modules/documentation_and_implementation_alignment.md diff --git a/docs/architecture/tech_stack.md b/docs/architecture/tech_stack.md index 18a8487..b91a7cb 100644 --- a/docs/architecture/tech_stack.md +++ b/docs/architecture/tech_stack.md @@ -116,3 +116,4 @@ Revisit this document if: - [`docs/decomposition/modules/pvp_combat_integration.md`](../decomposition/modules/pvp_combat_integration.md) — E5.M1 combat engine × E6.M1 PvP eligibility (single pipeline, deny reasons) - [`docs/decomposition/modules/quest_scope_and_party.md`](../decomposition/modules/quest_scope_and_party.md) — quest state per character, party credit, turn-in, instance deferral - [`docs/decomposition/modules/data_and_ops_policy.md`](../decomposition/modules/data_and_ops_policy.md) — content boot load vs dev reload, telemetry PII/sampling/retention, baseline events vs vision plan +- [`docs/decomposition/modules/documentation_and_implementation_alignment.md`](../decomposition/modules/documentation_and_implementation_alignment.md) — module register Status vs code, implementation tracking table diff --git a/docs/decomposition/README.md b/docs/decomposition/README.md index 9cbbad1..e142cf0 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/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [quest scope × party](modules/quest_scope_and_party.md), [data reload × telemetry ops](modules/data_and_ops_policy.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](modules/module_dependency_register.md#per-module-documentation), and interface notes. +- `modules/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [quest scope × party](modules/quest_scope_and_party.md), [data reload × telemetry ops](modules/data_and_ops_policy.md), [docs vs implementation](modules/documentation_and_implementation_alignment.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](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 index a7aa295..f1e6b43 100644 --- a/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md +++ b/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md @@ -7,7 +7,7 @@ | **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)) | +| **Status** | In Progress (see [dependency register](module_dependency_register.md); [implementation snapshot](#implementation-snapshot)) | ## Purpose @@ -31,6 +31,12 @@ Provides the foundational client/runtime path for character locomotion and world Contract readiness is tracked in the [module dependency register](module_dependency_register.md). +## Implementation snapshot + +- **Done (spike):** Server-side authoritative **read** API for `PositionState` (JSON over HTTP, versioned payload); in-memory store. See [NS-15 implementation plan](../../plans/NS-15-implementation-plan.md), `server/NeonSprawl.Server/Game/PositionState/`, and [server README — Position state](../../../server/README.md#position-state-ns-15). +- **Not yet:** `MoveCommand` ingestion, client sync, persistence, full movement loop per Epic 1 Slice 1. +- **Alignment:** [Documentation and implementation alignment](documentation_and_implementation_alignment.md). + ## Module dependencies - **None** — root of the player runtime stack. diff --git a/docs/decomposition/modules/contracts.md b/docs/decomposition/modules/contracts.md index d225271..5aaa499 100644 --- a/docs/decomposition/modules/contracts.md +++ b/docs/decomposition/modules/contracts.md @@ -83,6 +83,7 @@ A module’s register **Status** can move to **Ready** when the contracts it **e - [PvP and the combat engine](pvp_combat_integration.md) — E5.M1 gating with E6.M1, deny reasons - [Quest scope and party rules](quest_scope_and_party.md) — per-character quest state, party credit, turn-in - [Data reload and telemetry operations policy](data_and_ops_policy.md) — content reload, PII, sampling, retention, baseline events +- [Documentation and implementation alignment](documentation_and_implementation_alignment.md) — register Status vs repo, tracking table - [Module dependency register](module_dependency_register.md) - [Decomposition README](../README.md) diff --git a/docs/decomposition/modules/documentation_and_implementation_alignment.md b/docs/decomposition/modules/documentation_and_implementation_alignment.md new file mode 100644 index 0000000..7a24879 --- /dev/null +++ b/docs/decomposition/modules/documentation_and_implementation_alignment.md @@ -0,0 +1,55 @@ +# Documentation and implementation alignment + +The [module dependency register](module_dependency_register.md) **Status** column and each module’s summary table should **not silently disagree** with the repo. This doc defines how to keep decomposition docs truthful and where to record **partial** work. + +--- + +## Roles + +| Source | Role | +|--------|------| +| **Register + module markdown** | Intent, dependencies, contracts, policies (authority, PvP, quests, ops). | +| **Code + tests** | What actually runs; paths under `server/`, `client/`, etc. | +| **Plans** | `docs/plans/` (e.g. NS-* implementation plans) tie stories to acceptance criteria. | +| **This doc’s tracking table** | Quick **inventory** of modules that have started implementation; expand as work lands. | + +--- + +## Status column (register) + +| Status | Meaning | +|--------|---------| +| **Planned** | No meaningful implementation toward this module yet, or only unrelated spikes. | +| **In Progress** | At least one tracked story or code path exists toward the module; contracts may be partial. | +| **Ready** | Exported contracts meet [contracts.md](contracts.md) “Ready” guidance and dependents may integrate. | +| **Blocked** | Upstream module or external dependency prevents progress. | + +**Rule:** When a story merges that implements part of a module (API, store, schema), move that row from **Planned** to **In Progress** (or **Ready** when appropriate) in the same PR or a follow-up doc PR. + +**Partial modules** stay **In Progress** until the **prototype slice** for that module is satisfied or contracts are explicitly frozen for dependents. + +--- + +## Per-module docs + +Optional **`## Implementation snapshot`** (or a short bullet under Summary) on a module page: one paragraph + links to `docs/plans/…`, server paths, and [server README](../../../server/README.md) sections—avoid duplicating the full tracking table on every page. + +The **Summary** table **Status** field should match the register row for that module. + +--- + +## Implementation tracking table + +Rows appear when work starts; default for unlisted modules is **Planned** / not started. + + +| Module | Register status | Snapshot | Plans / pointers | +|--------|-----------------|----------|-------------------| +| E1.M1 | In Progress | Authoritative **read** `PositionState` over HTTP (JSON spike); in-memory store; no `MoveCommand` / client sync yet. | [NS-15 plan](../../plans/NS-15-implementation-plan.md); code: `server/NeonSprawl.Server/Game/PositionState/`; [server README — Position state](../../../server/README.md#position-state-ns-15) | + +--- + +## Related docs + +- [Module dependency register](module_dependency_register.md) +- [contracts.md](contracts.md) — versioning and Ready criteria diff --git a/docs/decomposition/modules/module_dependency_register.md b/docs/decomposition/modules/module_dependency_register.md index 2e2a830..3d4745e 100644 --- a/docs/decomposition/modules/module_dependency_register.md +++ b/docs/decomposition/modules/module_dependency_register.md @@ -2,7 +2,7 @@ Tracks cross-epic dependencies and contract readiness. Every **Depends On** module ID in this table has its own row (closed graph). -**Contract** means a stable boundary with a defined artifact (Protobuf wire message, JSON Schema content file, telemetry catalog entry, or server-internal type until promoted). See **[What a contract is](contracts.md)** for kinds, repo layout, and versioning. **Authority** (who owns `PositionState`, camera, combat outcomes): **[Client vs server authority](client_server_authority.md)**. **PvP × combat:** **[PvP and the combat engine](pvp_combat_integration.md)**. **Quests × party:** **[Quest scope and party rules](quest_scope_and_party.md)**. **Data reload × telemetry ops:** **[Data reload and telemetry operations policy](data_and_ops_policy.md)**. +**Contract** means a stable boundary with a defined artifact (Protobuf wire message, JSON Schema content file, telemetry catalog entry, or server-internal type until promoted). See **[What a contract is](contracts.md)** for kinds, repo layout, and versioning. **Authority** (who owns `PositionState`, camera, combat outcomes): **[Client vs server authority](client_server_authority.md)**. **PvP × combat:** **[PvP and the combat engine](pvp_combat_integration.md)**. **Quests × party:** **[Quest scope and party rules](quest_scope_and_party.md)**. **Data reload × telemetry ops:** **[Data reload and telemetry operations policy](data_and_ops_policy.md)**. **Docs vs code:** **[Documentation and implementation alignment](documentation_and_implementation_alignment.md)**. Fleshed-out scope, contracts, and integration notes live in **per-module documents** (see [Per-module documentation](#per-module-documentation)). @@ -12,7 +12,7 @@ Fleshed-out scope, contracts, and integration notes live in **per-module documen | Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | |---|---|---|---|---|---| -| E1.M1 | InputAndMovementRuntime | None | MoveCommand, PositionState, InteractionRequest | Prototype | Planned | +| E1.M1 | InputAndMovementRuntime | None | MoveCommand, PositionState, InteractionRequest | Prototype | In Progress | | E1.M2 | IsometricCameraController | E1.M1 | CameraState, ZoomBandConfig, OcclusionPolicy | Prototype | Planned | | E1.M3 | InteractionAndTargetingLayer | E1.M1 | TargetState, InteractableDescriptor, SelectionEvent | Prototype | Planned | | E1.M4 | AbilityInputScaffold | E1.M3, E5.M1 | AbilityCastRequest, HotbarLoadout, CooldownSnapshot | Prototype | Planned | @@ -148,7 +148,9 @@ Gameplay **content and curves** default to **boot load** with optional **dev-onl ## Status Legend -- Planned: identified but not implemented -- In Progress: currently being implemented -- Ready: contract stable and usable by dependents -- Blocked: dependency missing or unstable +- **Planned:** No meaningful implementation toward this module yet (see [documentation and implementation alignment](documentation_and_implementation_alignment.md)). +- **In Progress:** Partial implementation or active stories; contracts may be incomplete. +- **Ready:** Contract stable and usable by dependents ([contracts.md](contracts.md)). +- **Blocked:** Dependency missing or unstable. + +**Tracking table** (modules with code or plans in flight): [documentation_and_implementation_alignment.md — Implementation tracking table](documentation_and_implementation_alignment.md#implementation-tracking-table). From 85d30709699ce76179957e182db1d518a7f205d7 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Mon, 30 Mar 2026 19:04:58 -0400 Subject: [PATCH 10/11] rules: code review must cite plans and decomposition docs Require identifying docs/plans and docs/decomposition/modules (register, module pages, cross-cutting policies, implementation alignment); verify implementation against them; add Documentation checked to review output. Extend checklist; AGENTS.md code review row summarizes requirement. Made-with: Cursor --- .cursor/rules/code-review-agent.md | 23 ++++++++++++++++++----- AGENTS.md | 2 +- 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/.cursor/rules/code-review-agent.md b/.cursor/rules/code-review-agent.md index c42b2eb..8380f32 100644 --- a/.cursor/rules/code-review-agent.md +++ b/.cursor/rules/code-review-agent.md @@ -25,7 +25,18 @@ Align recommendations with repo rules and docs, including: - [jira-git-naming](jira-git-naming.md) — branch/commit prefixes when the work is ticketed. - [git-workflow](git-workflow.md) — branch vs `main`, story-scoped plans. -If the change contradicts an adopted plan under `docs/plans/`, call that out. +### Plan and decomposition documentation (required to reference) + +For every review, **identify and cite** the documentation that defines intent for the change, then **check the implementation against it** (not only style and correctness). + +1. **Story / implementation plans** — If the work maps to a ticket or plan under `docs/plans/` (e.g. `NS-*-implementation-plan.md`), treat that document as acceptance criteria. If the diff diverges without an updated plan or an explicit “out of scope” note, call it out (blocking or non-blocking by severity). +2. **Module docs** — Map the change to one or more modules in [`docs/decomposition/modules/module_dependency_register.md`](../../docs/decomposition/modules/module_dependency_register.md) and the corresponding `docs/decomposition/modules/E*_*.md` pages. Verify behavior matches **Purpose**, **Responsibilities**, **Key contracts**, and **Authority** / linked policy sections where relevant. +3. **Cross-cutting policies** — When applicable, align with `docs/decomposition/modules/` policy docs (e.g. [`contracts.md`](../../docs/decomposition/modules/contracts.md), [`client_server_authority.md`](../../docs/decomposition/modules/client_server_authority.md), [`pvp_combat_integration.md`](../../docs/decomposition/modules/pvp_combat_integration.md), [`data_and_ops_policy.md`](../../docs/decomposition/modules/data_and_ops_policy.md)). +4. **Implementation status** — If the register or [`documentation_and_implementation_alignment.md`](../../docs/decomposition/modules/documentation_and_implementation_alignment.md) tracks the module, note whether **Status** / the implementation tracking table should be updated after this merge. + +In the **saved review document**, include a subsection **Documentation checked**: bullet list of paths consulted and whether the diff **matches**, **partially matches**, or **conflicts** with them. If no decomposition doc applies (e.g. pure tooling), state that explicitly. + +If the change contradicts an adopted plan under `docs/plans/` or documented module/policy intent without justification, treat that as at least a **should fix** (or **blocking** if it breaks contracts or authority). ## Review checklist @@ -38,6 +49,7 @@ Work through what applies to the diff (skip irrelevant sections briefly). 5. **Tests** — Happy path, failure modes, integration boundaries per [testing-expectations](testing-expectations.md); note gaps. 6. **Observability** — Logging/metrics where failures would be hard to diagnose (server/runtime code). 7. **Docs** — README or plan updates when behavior or run instructions change. +8. **Plan & decomposition alignment** — Per **Plan and decomposition documentation** above: relevant `docs/plans/` and module/policy docs cited; implementation checked against them; **Documentation checked** section in the saved review file. ## Code review document (required) @@ -60,10 +72,11 @@ Use this structure in **both** the saved document and (abbreviated if you want) 1. **Verdict** — One line: `Approve` / `Approve with nits` / `Request changes`. 2. **Summary** — 2–5 sentences on what the change does and overall risk. -3. **Blocking issues** — Numbered list; empty section if none. -4. **Suggestions** — Non-blocking improvements. -5. **Nits** — Optional; prefix with “Nit:”. -6. **Verification** — Commands or manual steps the author should run before merge (e.g. `dotnet test`, Godot scenario). +3. **Documentation checked** — Paths under `docs/plans/` and `docs/decomposition/modules/` (and related) consulted; **matches** / **partially matches** / **conflicts** / **N/A** per item; note if register/tracking table updates are needed. +4. **Blocking issues** — Numbered list; empty section if none. +5. **Suggestions** — Non-blocking improvements. +6. **Nits** — Optional; prefix with “Nit:”. +7. **Verification** — Commands or manual steps the author should run before merge (e.g. `dotnet test`, Godot scenario). In **chat only**, you may use Cursor line-number **code citations** when referencing existing code. For hypothetical fixes, use normal fenced code blocks everywhere. diff --git a/AGENTS.md b/AGENTS.md index 1838faf..9c5804d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,6 @@ Optional **personas** for Cursor. Enable by **@ mentioning** the rule in chat or | Agent | Rule file | When to use | |--------|-----------|-------------| -| **Code review** | [`.cursor/rules/code-review-agent.md`](.cursor/rules/code-review-agent.md) | PR / diff / pre-merge review; **always writes** `docs/reviews/YYYY-MM-DD-{slug}.md` plus a short chat pointer | +| **Code review** | [`.cursor/rules/code-review-agent.md`](.cursor/rules/code-review-agent.md) | PR / diff / pre-merge review; **always writes** `docs/reviews/YYYY-MM-DD-{slug}.md` with **Documentation checked** vs `docs/plans/` and `docs/decomposition/modules/`; short chat pointer | Project-wide conventions live under [`.cursor/rules/`](.cursor/rules/) (many are `alwaysApply`). From 813baa670d6e7317cd2605a599a383345ec247a8 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Mon, 30 Mar 2026 19:05:49 -0400 Subject: [PATCH 11/11] docs: tidy data_and_ops_policy table and vision plan links Widen content-reload policy table columns; use proper markdown links to neon_sprawl_vision.plan.md (not code-span wrapped URLs). Made-with: Cursor --- docs/decomposition/modules/data_and_ops_policy.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/decomposition/modules/data_and_ops_policy.md b/docs/decomposition/modules/data_and_ops_policy.md index 0b112c9..bae1976 100644 --- a/docs/decomposition/modules/data_and_ops_policy.md +++ b/docs/decomposition/modules/data_and_ops_policy.md @@ -8,11 +8,13 @@ Prototype-through–early-pre-production rules for **how gameplay data is loaded 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. | + +| 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.