# Doc 73: Server-Client Desync Sentinel, Zero-Latency CI Shock Watchdog & Commercial KPI Specification (SSoT 2026)

## 1. Bối Cảnh & Mục Tiêu Kỹ Thuật (Executive Summary)
- **Hệ thống**: AutoPOE2 (Path of Exile 2 v0.5.5+, C++23 DOD Hot Path 120Hz & Python 3.11 EDA Cold Path).
- **Mục tiêu**: Nâng cấp AutoPOE2 lên chuẩn thương mại top-tier toàn cầu, triệt tiêu 100% hai nguyên nhân tử trận và kẹt bot bí hiểm:
  1. *Server-Client Spatial Desync & Collider Snagging*: Hiện tượng nhân vật kẹt địa hình hoặc giật lùi (rubberbanding) khi chạy WASD.
  2. *Monk CI Lethal Shock Wave*: Đòn burst sát thương lớn (tụt > 50% ES trong 1 tick $\le 16.6\text{ms}$) trên nhân vật Chaos Inoculation (HP 1/1, ES 4284) bị trễ do cơ chế mô phỏng người chơi thật ($125\text{ms}$).
  3. *Commercial Bot KPI Metric Framework*: Bộ chỉ số định lượng đánh giá hiệu năng (MPH $\ge 12$, Net Worth $\ge 800\text{c/h}$, Death Rate $0.00\%$).

---

## 2. Bất Biến Mới: INV-CI-0MS-BURST-WATCHDOG (Reflex Fallback Ladder)

### A. Vấn đề cốt lõi & Phản biện Cooldown
- Monk CI có Maximum HP $= 1$ cố định, toàn bộ thanh sinh mệnh phụ thuộc vào Energy Shield (ES). Thuật toán cũ chỉ theo dõi HP burst ratio nên hoàn toàn mù trước các cú đánh rút cạn ES.
- **Rủi ro Cooldown của Dodge Roll**: Dodge Roll trong POE2 có internal cooldown ($\approx 400\text{ms} - 500\text{ms}$). Nếu vừa lộn nhào xong mà ăn tiếp cú đánh chí mạng (Shock ES $> 50\%$), spam Spacebar sẽ bị game engine nuốt lệnh.

### B. Đặc tả Thang Phản Xạ Đa Tầng (Reflex Fallback Ladder)
Mỗi nhịp 120Hz ($8.33\text{ms}$), mạch 0ms tính toán:
$$\Delta ES = ES_{t-1} - ES_t \quad \implies \quad \text{ShockRatio} = \frac{\Delta ES}{ES_{max}}$$

Khi $\text{ShockRatio} \ge 0.50$ HOẶC $ES \le 0.35 \times ES_{max}$:
1. **0ms Bypass**: Lập tức loại bỏ toàn bộ hàng đợi trễ sinh học người chơi (`humanReactionLatency`), không chờ `dodgeScheduledMs`.
2. **Thang Phản Xạ Đa Tầng (Ladder Hierarchy)**:
   - **Bậc 1 (I-frame Dodge Roll - Spacebar)**: Nếu `dodgeRollOnCooldown == false`, kích hoạt ngay phím `Spacebar` (I-frame 300ms bất tử).
   - **Bậc 2 (Defensive Guard Skill Fallback)**: Nếu `dodgeRollOnCooldown == true`, chuyển tức thời sang phát lệnh kỹ năng phòng ngự khẩn cấp (Defensive Stance / Frost Shield / Molten Shell / Warcry) để hấp thụ sát thương. Tuyệt đối CẤM kẹt/stall ở phím Spacebar.
   - **Bậc 3 (Extreme Emergency Escape)**: Nếu $ES \le 20\%$ và các kỹ năng phòng ngự đã cạn, kích hoạt ngay Town Portal (`.`) hoặc phát lệnh TCP RST Logout khẩn cấp cứu mạng.

---

## 3. Bất Biến Mới: INV-DESYNC-DETECT-RESYNC (Body-Block Siege Breakout)

### A. Vấn đề cốt lõi & Phân biệt Snag vs Body-Block
- Tiêu chí vận tốc thực tế $V_{net} < 0.8\text{u/s}$ dưới phím di chuyển WASD $\ge 350\text{ms}$ xuất hiện trong 2 hoàn cảnh hoàn toàn khác nhau:
  1. *Mesh/Collider Snag*: Kẹt gờ đá, mép cửa, hoặc desync tọa độ server-client (quanh người không có quái vật).
  2. *Monster Body-Block Siege*: Bị bầy quái vật vây kín 360 độ cản đường.

### B. Đặc tả Thuật toán Phân Nhánh Thích Ứng (Adaptive Branching Engine)
Kiểm tra số lượng quái vật trong bán kính cận chiến $15\text{u}$ (`monsters_near_15u`):

```mermaid
flowchart TD
    A["Phát hiện Desync / V_net < 0.8u/s (Dwell >= 350ms)"] --> B{"monsters_near_15u >= 3 ?"}
    B -- "Có (Monster Body-Block)" --> C["KÍCH HOẠT PHÁ VÂY KHẨN CẤP"]
    C --> C1["Từ chối trượt tiếp tuyến 90°"]
    C --> C2["Kích hoạt tức thì AOE Clear / Phasing Skill"]
    C --> C3["Dọn sạch vòng vây quái vật rồi tiếp tục lộ trình"]
    B -- "Không (Mesh / Terrain Snag)" --> D["KÍCH HOẠT 3-TIER MESH RESYNC"]
    D --> D1["Tier 1: Dodge Roll (Root-motion Server Position Update)"]
    D --> D2["Tier 2: Tangent Slide ±90° (Bézier Wall Bypass)"]
    D --> D3["Tier 3: In-Game /oos command hoặc Town Portal Escape"]
```

---

## 4. Ma Trận KPI Đánh Giá Chất Lượng Bot Thương Mại (Commercial KPI Metric Framework)

| Nhóm Chỉ Số | Tên Chỉ Số KPI | Ngưỡng Mục Tiêu Top-Tier | Phương Pháp Đo Lường Thực Nghiệm |
|---|---|---|---|
| **Vận Hành Tốc Độ** | **Maps Per Hour (MPH)** | **$\ge 12.0$ maps/h** (Mục tiêu tối ưu: 14–16 maps/h) | Tổng số map hoàn tất chia cho tổng thời gian chạy thực tế của phiên. |
| | **Hideout Cycle Downtime** | **$\le 18.0\text{s}$** | Thời gian thực thi toàn bộ chuỗi Hideout (Stage 0, 1, 2, 3, 4). |
| | **Average In-Map Clear Time** | **$90\text{s} - 210\text{s}$** | Thời gian dọn map tuân thủ 4 cổng `INV-MAP-LEGITIMATE-CLEAR`. |
| **Hiệu Năng Kinh Tế** | **Net Worth Growth Rate** | **$\ge 800\text{ Chaos/h}$** (hoặc $\ge 5.0\text{ Divine/h}$) | Đo lường vi sai tài sản ròng qua `NetWorthEstimator` & `AtlasProgressionService`. |
| | **Valuable Loot Efficiency** | **$\ge 92.0\%$** | Tỷ lệ đồ giá trị được cất vào Stash / tổng đồ nhặt được trong khoang túi. |
| | **Faustus Arbitrage Yield** | **$\ge 15\text{ Chaos/session}$** | Lợi nhuận ròng sau mỗi đợt chốt lời phụ tệ qua Sàn giao dịch Currency Exchange. |
| **Độ Bền & Sinh Tồn** | **Death Rate (Zero-Death Policy)**| **$0.00\%$ (Tuyệt đối 0 tử trận)** | Đảm bảo không mất $10\%$ EXP tại Level 90-100; CI HP giữ $1/1$, ES luôn $> 0$. |
| | **Unstuck Success Rate** | **$\ge 99.5\%$** | Khả năng tự giải thoát kẹt địa hình / desync trong vòng $< 1.5\text{s}$. |
| | **Autonomy Readiness Score (ARS)**| **$100.0\%$ (19+ Invariants)** | Bất kỳ vi phạm nào lập tức kích hoạt Fail-Closed ARS = $0.0\%$. |
| **An Toàn Phần Cứng** | **Focus Leak Incidents** | **$0$ incidents (Tuyệt đối 0)** | Zero mouse/key leak ra desktop khi game window mất tiêu điểm. |
| | **Hot Path Dispatch Latency** | **$< 25\mu\text{s}$** | Độ trễ từ lúc phát hiện dị thường đến khi gói tin HID rời máy tính. |
| | **Hot Path Memory Allocation** | **$0\text{ bytes}$ dynamic heap** | Tuân thủ bất biến `INV-ZERO-HEAP-HOTPATH` (O(1) pre-allocated buffers). |

---

## 5. Kết Luận & Quy Chuẩn Nghiệm Thu Sư Đoàn 4
- Toàn bộ cơ chế phản xạ đa tầng và phân nhánh phá vây đã được kiểm chứng 100% qua bộ kiểm thử tự động `tests/test_endless_multi_map_loop.py`.
- Tài liệu này đóng vai trò Single Source of Truth (SSoT) kiến trúc cho chu kỳ nâng cấp AutoPOE2 lên chuẩn thương mại toàn cầu.