---
paths:
  - "src/core/**/*.cpp"
  - "src/core/**/*.hpp"
  - "src/core/**/*.h"
  - "CMakeLists.txt"
domain: "cpp_core"
---

# AutoPOE2 - C++23 Core Engine Rules (Hot Path 120Hz)

> **Tài liệu quy chuẩn chuyên biệt cho tầng Tier 1 C++23 Core Engine.**  
> Mở rộng từ Hiến pháp SSoT tại [`AGENTS.md`](../../../AGENTS.md) và [Doc 50](docs/development/50_two_tier_asymmetric_hybrid_architecture_specification.md).

## 1. Hot Path 120Hz & Triết Lý Zero Dynamic Allocation
- **Zero Dynamic Allocation trong Combat Loop**: Tuyệt đối CẤM `new`, `delete`, `malloc`, `free`, hoặc mở rộng container tự động (`std::vector::push_back` gây realloc, `std::string` cấp phát động) bên trong vòng lặp chiến đấu 120Hz (`CombatEngine`, `ReflexManager`, `BotBrain`).
- **Data-Oriented Design (DOD)**: Lưu trữ và duyệt mảng thực thể theo cấu trúc mảng phẳng (flat array) thân thiện với L1/L2 cache CPU.
- **SPSC Ring Buffer & Seqlock IPC**: Giao tiếp IPC với Python qua vùng nhớ chia sẻ (Shared Memory 39KB) dùng Seqlock Double-Buffer + SPSC Ring Buffer 16 slot; đảm bảo 0 torn-read, lock-free, không block Hot Path.

## 2. Quản Lý Tài Nguyên & Hiện Đại Hóa C++23
- **RAII triệt để**: Sử dụng Smart Pointers (`std::unique_ptr`) cho quyền sở hữu độc quyền. Chỉ dùng `std::shared_ptr` khi thực sự cần chia sẻ vòng đời đa luồng.
- **Compile-time Constants**: Ưu tiên `constexpr` / `consteval` cho các hằng số toán học, kích thước buffer, và offset cấu trúc.
- **String Handling**: Sử dụng `std::string_view` cho tham số chỉ đọc để triệt tiêu việc sao chép chuỗi không cần thiết.

## 3. Kỷ Luật Biên Dịch & Chống Khóa File Windows (Rule 6)
- **Pre-Build Process Kill**: Trên Windows, các file `.exe` đang chạy sẽ khóa quyền ghi (`LNK1104`). Trước khi build C++, BẮT BUỘC gọi lệnh tắt process:
  ```powershell
  cmd /c "taskkill /F /IM AutoPOE2_Tests.exe >nul 2>&1 || exit 0"
  cmd /c "taskkill /F /IM AutoPOE2_Core.exe >nul 2>&1 || exit 0"
  ```
- **Zero Binary Drift**: Luôn kiểm tra timestamp nhị phân sau khi biên dịch để đảm bảo binary mới đã được ghi đè thành công.

## 4. Các Invariant Bắt Buộc Giám Sát Trong C++
- `INV-CI-01`: Nhân vật Chaos Inoculation (`HP 1/1`) cấm dùng Life Flask, trigger reflex dựa trên Energy Shield.
- `INV-TERRAIN-ORIGIN`: `worldOrigin` calibrate từ struct địa hình thật; cấm slide JPS khi `grid == nullptr`.
- `INV-BRAIN-CONFLICT-GATEKEEPER`: Từ chối Opcode 96 (`TRIGGER_WORLD_MAP_TRAVEL`) khi ở Hideout hoặc khi MapDevice active.
- `INV-F8-MUTES-BRAIN`: Khi `allowPhysicalMove == false` (F8 Pause), tắt ngay `botBrain.Process` và nhả toàn bộ phím WASD.