# BÁO CÁO REVIEW CHUYÊN SÂU & THẨM ĐỊNH ĐỐI KHÁNG (MILESTONE M1)

> **Người thực hiện**: `reviewer_m1_progression_1` (teamwork_preview_reviewer)  
> **Người nhận**: `orchestrator_4` (`6f4a2aa2-4315-4660-8cb7-8352a7220c95`)  
> **Phạm vi thẩm định**: Milestone M1 (Piecewise EXP Curve, Database Schema Extension, Seeder & Integrity Engine)  
> **Thời điểm**: 2026-10-01T02:21:00Z  

---

## 1. Review Summary

**Verdict**: **APPROVE**  
**Overall Risk Assessment**: **LOW**  
**Integrity Audit**: **PASS (Zero Integrity Violations Detected)**  
- Không phát hiện hardcoded test expectations trong logic nghiệp vụ.
- Không phát hiện dummy/facade implementations. Toàn bộ 100 cấp độ được sinh bằng công thức toán học phân khúc 7 giai đoạn thực chất.
- Cơ sở dữ liệu `data/game_design_matrix.db` được nạp đầy đủ 100 bản ghi với 13 cột chuẩn.
- Các bài kiểm tra unit, e2e và hygiene đều thực thi thực tế và vượt qua 100%.

---

## 2. Findings

### [Minor] Finding 1: Type Incompatibility in `GameDesignMatrixService.seed_canonical_data`
- **What**: Giá trị trả về không tương thích kiểu khai báo khi `force=False` và database đã có dữ liệu.
- **Where**: `server/world/game_design_matrix_service.py:95`
- **Why**: Chữ ký hàm khai báo `-> Dict[str, int]`, nhưng tại dòng 95 trả về `{"status": "already_seeded"}` (`dict[str, str]`). Điều này gây cảnh báo type error khi chạy `mypy --strict`.
- **Suggestion**: Đổi giá trị trả về thành `{"already_seeded": 1}` hoặc cập nhật type annotation thành `Dict[str, Any]` / `Dict[str, Union[int, str]]`.

### [Minor] Finding 2: Missing Return Type Annotation in `_get_connection`
- **What**: Phương thức context manager `_get_connection` thiếu type annotation cho giá trị trả về.
- **Where**: `server/world/game_design_matrix_service.py:49`
- **Why**: Vi phạm quy chuẩn strict typing `no-untyped-def` của mypy.
- **Suggestion**: Thêm type annotation: `def _get_connection(self) -> Generator[sqlite3.Connection, None, None]:`.

### [Minor] Finding 3: Potential Edge Case in Partial Migration (`_check_and_migrate_schema`)
- **What**: Nguy cơ bảng `progression_benchmarks` rỗng nếu khởi tạo DB cũ với `force=False`.
- **Where**: `server/world/game_design_matrix_service.py:78-87` & `92-96`
- **Why**: Nếu một database cũ có `story_acts` đã nạp nhưng `progression_benchmarks` có ít hơn 13 cột, phương thức `_check_and_migrate_schema` sẽ drop bảng cũ và tạo lại bảng rỗng. Nếu sau đó gọi `seed_canonical_data(force=False)`, dịch vụ kiểm tra `story_acts > 0` và trả về `already_seeded`, khiến bảng `progression_benchmarks` không được nạp dữ liệu.
- **Suggestion**: Trong `seed_canonical_data`, kiểm tra thêm `SELECT COUNT(*) FROM progression_benchmarks` hoặc chủ động gọi reseed `progression_benchmarks` khi phát hiện di trú. (Lưu ý: Với lệnh chuẩn `verify_game_design_matrix.py --sync`, tham số `force=True` luôn được dùng nên không ảnh hưởng môi trường hiện tại).

---

## 3. Verified Claims

| Worker Claim | Verification Method | Result | Notes |
|---|---|---|---|
| Đường cong 7 phân đoạn tăng đơn điệu ngặt từ cấp 1 đến 100 | Script đối soát trực tiếp 99 bước chuyển cấp trong SQLite & Python | **PASS** | $cumulative\_exp(L) > cumulative\_exp(L-1)$ với mọi $L \in [2, 100]$. Không có bước lùi nào. |
| EXP cấp 1-20 $< 0.1\%$ tổng tích lũy cả đời | Tính tỷ lệ: $\sum_{1}^{20} \Delta / \sum_{1}^{99} \Delta$ | **PASS** | Đạt $0.0115\% < 0.1\%$ ($2,755,579 / 23,925,692,466$). |
| Delta EXP cấp 99 $\to$ 100 $\ge 30\%$ tích lũy 1-98 | Tính tỷ lệ: $\Delta_{99} / \sum_{1}^{98} \Delta$ | **PASS** | Đạt $33.00\% \ge 30\%$ ($5,936,450,010 / 17,989,242,456$). |
| Delta EXP cấp 99 $\to$ 100 chiếm 20-35% tổng EXP cả đời | Tính tỷ lệ: $\Delta_{99} / \sum_{1}^{99} \Delta$ | **PASS** | Đạt $24.81\%$ ($5,936,450,010 / 23,925,692,466$). |
| Schema `progression_benchmarks` có 13 cột chuẩn | `PRAGMA table_info(progression_benchmarks)` | **PASS** | Đầy đủ 13 cột, ràng buộc `CHECK` hợp lệ. |
| Dataclass `ProgressionBenchmarkRow` tuân thủ 2026 standard | Kiểm tra mã nguồn `game_design_matrix_types.py` | **PASS** | `@dataclass(slots=True, frozen=True)` với 13 trường. |
| Tuân thủ giới hạn độ dài file (Soft Cap $\le 350$) | `check_code_and_doc_hygiene.py --strict` | **PASS** | 5/5 file M1 đều $\le 340$ dòng. |
| `tools/lint/verify_game_design_matrix.py --sync` | Thực thi CLI | **PASS** | Exit code 0, 100% in sync. |
| `pytest tests/unit/test_game_design_matrix.py` | Thực thi pytest | **PASS** | 8 passed in 0.31s. |
| `pytest tests/e2e/test_level_progression_e2e.py -k "test_f01 or test_f02 or test_f04"` | Thực thi pytest | **PASS** | 21 passed, 3 xpassed (F2 negative baselines nay đã pass). |

---

## 4. Adversarial Review & Stress-Testing

### Challenge 1: 64-bit Integer Overflow Boundary (Endgame EXP Scaling)
- **Assumption Challenged**: Hệ thống lưu trữ và truyền tải EXP an toàn với kiểu số nguyên mặc định.
- **Attack Scenario**: Tổng EXP tích lũy ở cấp 100 là $23,925,692,466$ (~23.9 tỷ). Giới hạn số nguyên 32-bit có dấu là $2,147,483,647$ (~2.14 tỷ). Tại cấp 82, tổng EXP đạt $2,031,508,437$; sang cấp 83, EXP vượt quá $2.18$ tỷ. Nếu Client, Protobuf hoặc dịch vụ mạng dùng `int32`, giá trị sẽ bị tràn số (integer overflow) thành số âm, làm sập logic thăng cấp ở giai đoạn Endgame.
- **Blast Radius**: Lỗi rollback cấp độ hoặc crash client từ cấp 83 trở lên.
- **Mitigation & Readiness**:
  - SQLite lưu trữ kiểu 64-bit signed integer (hỗ trợ tối đa $9 \times 10^{18}$), Python 3 tự động mở rộng độ dài số nguyên $\implies$ Tầng M1 hoàn toàn an toàn.
  - **Khuyến nghị bắt buộc cho Milestone M2 & Protobuf**: Tất cả các trường EXP (`current_exp`, `target_exp`, `cumulative_exp`, `monster_exp`) trong Protobuf và DTO phải dùng `int64` / `uint64`.

### Challenge 2: Derivative Smoothness at Segment Boundaries
- **Stress-Test**: Kiểm tra tính liên tục và tỷ lệ gia tăng ($\Delta_{L+1} / \Delta_L$) tại 6 điểm giao thoa phân đoạn:
  - Cấp 20 $\to$ 21: $493,291 \to 599,976$ (tỷ lệ $1.2163$)
  - Cấp 40 $\to$ 41: $5,350,276 \to 5,865,854$ (tỷ lệ $1.0964$)
  - Cấp 60 $\to$ 61: $33,688,217 \to 37,730,803$ (tỷ lệ $1.1200$)
  - Cấp 80 $\to$ 81: $114,539,937 \to 132,412,699$ (tỷ lệ $1.1560$)
  - Cấp 90 $\to$ 91: $488,296,867 \to 620,746,977$ (tỷ lệ $1.2712$)
  - Cấp 98 $\to$ 99: $3,330,652,650 \to 5,936,450,010$ (tỷ lệ $1.7824$)
- **Kết quả**: Tất cả các điểm giao thoa đều có tỷ lệ $> 1.0$, không xuất hiện bước hẫng (không có hiện tượng cấp sau dễ cày hơn cấp trước), đồng thời cấp 98 $\to$ 99 tăng vọt $1.78\times$ tạo đúng cảm giác "bức tường cực hạn" chuẩn PoE2.

---

## 5. Coverage Gaps & Unverified Items
- **Phạm vi Milestone M2-M4**: Các tính năng `LevelProgressionService`, `simulate_level_progression.py`, và `AscendancyEngine` thuộc các milestone tiếp theo, không thuộc phạm vi nghiệm thu của M1.
- Không có vùng thiếu sót nào trong phạm vi Milestone M1.

---

## 6. Kết luận & Khuyến nghị Bàn giao
Milestone M1 đã hoàn thành xuất sắc các mục tiêu toán học và cấu trúc dữ liệu nền tảng, mã nguồn sạch sẽ, tuân thủ nghiêm ngặt các chỉ thị kỹ thuật 2026. Đề xuất Orchestrator tiến hành **phê duyệt (APPROVE)** để chuyển tiếp nhiệm vụ sang Milestone M2 (`worker_m2_progression_service`).