# Project: FreeExile Level 1-100 Progression, Piecewise EXP Curve, Hybrid Death Penalty & Godhood Ascension

## Architecture
- **Mathematical & Database Layer**:
  - `server/world/game_design_matrix_seeder.py`: 7-segment piecewise exponential EXP curve seeder populating `progression_benchmarks` in `data/game_design_matrix.db`.
  - `data/game_design_matrix.db`: SQLite database storing progression benchmarks (levels 1-100, cumulative exp, delta exp, death penalty ratios, level gap parameters).
  - `server/world/game_design_matrix_service.py`: Query and integrity verification service enforcing strict monotonicity.
- **Progression & Core Service Layer**:
  - `server/world/level_progression_types.py`: Strictly typed immutable models (`@dataclass(slots=True, frozen=True)`) for EXP awards, level gap metrics, death penalties, and level-up events.
  - `server/world/level_progression_service.py`: Core progression service managing monster EXP distribution, level-up stat/talent calculations, level gap penalties ($\exp(-0.60 \cdot (\Delta - 5))$), and tiered death penalties (0%, 5%, 10%, 15%, 25%) with safe floor.
  - `server/world/combat_engine.py`: Integration with combat resolution to dispatch fatal damage events and player death hooks.
  - `server/world/zone_engine.py`: Player death evacuation and safe haven respawn handling.
- **Ascendancy & Godhood Keystone Layer**:
  - `server/world/ascendancy_catalog.py`: Registration of `GODHOOD_AVATAR_METAMORPHOSIS` keystone and strict `required_level=100` gating for `TRIAL_10_GODHOOD_TRANSCENDENCE`.
  - `server/world/ascendancy_types.py`: Extended `AscendancyAppliedEffects` with `avatar_metamorphosis_active: bool = False`, +40% More Damage, and +5% Max Elemental/Chaos Resists.
  - `server/world/ascendancy_engine.py`: Level 100 validation gate in `complete_trial()`.
- **Simulation & Verification Layer**:
  - `tools/balance/simulate_level_progression.py`: Monte Carlo simulation running 1,000 player scenarios over a 90-day season (5 hours/day, 75 maps/day) proving level 100 soft-wall balance.
  - `tests/e2e/test_level_progression_e2e.py`: Comprehensive opaque-box E2E test suite (Tiers 1-4) with `TEST_READY.md`.

## Feature Inventory
| # | Feature | Description | Milestone | Source |
|---|---------|-------------|-----------|--------|
| 1 | 7-Segment Piecewise EXP Curve | Levels 1-100 piecewise exponential curve: Lv 1-20 < 0.1%, Lv 99->100 delta >= 30% of lifetime 1-99 | M1 | ORIGINAL_REQUEST §R1 |
| 2 | Progression Benchmarks Schema & Seeder | Extend `progression_benchmarks` schema with delta EXP and penalties; update `game_design_matrix_seeder.py` | M1 | ORIGINAL_REQUEST §R1, R4 |
| 3 | Level Gap Penalty Formula | $\eta(\Delta) = \exp(-0.60 \cdot (\Delta - 5))$ for $\Delta > 5$; $\le 5\%$ EXP when gap >= 10 levels | M2 | ORIGINAL_REQUEST §R2 |
| 4 | Tiered Hybrid Death Penalty | 1-60: 0%, 61-80: 5%, 81-89: 10%, 90-99: 15%, 99->100: 25% with safe floor at 0% of current level | M2 | ORIGINAL_REQUEST §R2 |
| 5 | LevelProgressionService Engine | Core service managing monster EXP awarding, level up stats/passives, and death penalty hooks | M2 | ORIGINAL_REQUEST §R4 |
| 6 | Trial 10 Ascension Level 100 Gating | Strictly gate `TRIAL_10_GODHOOD_TRANSCENDENCE` at `level == 100`; reject Lv 99 and below | M3 | ORIGINAL_REQUEST §R3 |
| 7 | Godhood Avatar Metamorphosis Keystone | Keystone node unlocking `avatar_metamorphosis_active = True`, +40% More Damage, +5% Max Resists | M3 | ORIGINAL_REQUEST §R3 |
| 8 | Monte Carlo Simulation Tool | `simulate_level_progression.py`: 1,000 players over 90 days proving Lv 100 unattainable for death rate >= 1% | M4 | ORIGINAL_REQUEST §R4 |
| 9 | Requirement-Driven E2E Test Suite | Opaque-box E2E test suite across Tiers 1-4 publishing `TEST_READY.md` | E2E | Dual-Track |
| 10 | Final E2E Pass & Adversarial Hardening | 100% E2E pass + Tier 5 white-box adversarial stress testing + Hygiene and Security audits | M5 | Project Pattern |

## Milestones
| # | Name | Scope | Dependencies | Status |
|---|------|-------|-------------|--------|
| E2E | E2E Testing Track | Opaque-box test suite (Tiers 1-4), test runner, publishing `TEST_READY.md` | none | DONE |
| M1 | Piecewise EXP Curve & Seeder Upgrade | 7-segment curve, `progression_benchmarks` schema extension, seeder, monotonicity test | none | DONE |
| M2 | LevelProgressionService & Death Penalty | `level_progression_service.py`, types, level gap penalty, death penalty, combat hooks | M1 | IN_PROGRESS |
| M3 | Trial 10 Ascension & Keystone Metamorphosis | Trial 10 Level 100 gating, `GODHOOD_AVATAR_METAMORPHOSIS` keystone, `AscendancyAppliedEffects` | M2 | PLANNED |
| M4 | Monte Carlo Simulation Tool | `simulate_level_progression.py` 1,000 players 90-day simulation and empirical verification | M1, M2 | PLANNED |
| M5 | Final E2E Pass, Hardening & Security Audit | 100% E2E pass, Tier 5 adversarial tests, hygiene gate (`--strict`), security audit | E2E, M3, M4 | PLANNED |

## Interface Contracts
### LevelProgressionService ↔ Combat & World Loop
- `award_monster_exp(player_id: str, monster_level: int, base_exp: int, zone_level: int) -> ExpAwardResult`:
  Calculates level gap penalty, updates player EXP, checks and triggers level up events.
- `apply_death_penalty(player_id: str) -> DeathPenaltyResult`:
  Applies tiered percentage penalty (0%, 5%, 10%, 15%, 25%) to current level EXP, clamping to 0% floor without de-leveling.
- `get_level_info(player_id: str) -> PlayerLevelState`:
  Returns current level, current EXP, EXP required for next level, and lifetime cumulative EXP.

### AscendancyEngine ↔ LevelProgressionService
- `can_enter_trial(actor_id: int, trial_index: int, player_level: int) -> bool`:
  Enforces `player_level >= required_level`, specifically `player_level == 100` for Trial 10.
- `complete_trial(actor_id: int, trial_index: int, player_level: int) -> AscendancyTrialResult`:
  Validates eligibility, awards 3 ascendancy points, and enables keystone allocation.

### Progression Benchmarks Matrix ↔ Game Engine
- `get_level_benchmark(level: int) -> ProgressionBenchmarkDTO`:
  Queries level row with cumulative_exp, exp_to_next_level, death_penalty_ratio, and combat stats.

## Code Layout
- `server/world/game_design_matrix_seeder.py`: Curve seeder (Code <= 350-500 lines).
- `server/world/level_progression_types.py`: Progression DTOs (Types <= 350 lines).
- `server/world/level_progression_service.py`: Core progression logic (Code <= 350-500 lines).
- `server/world/ascendancy_types.py`: Ascendancy models & effects (Types <= 350 lines).
- `server/world/ascendancy_catalog.py`: Trial & keystone definitions (Catalog <= 700 lines).
- `server/world/ascendancy_engine.py`: Trial validation & completion (Code <= 350 lines).
- `tools/balance/simulate_level_progression.py`: Monte Carlo simulation (Tool <= 350-500 lines).
- `tests/unit/test_level_progression.py`: Unit test suite.
- `tests/e2e/test_level_progression_e2e.py`: Opaque-box E2E test suite.