temporary storage

docs/SAFETY.md

@@ -0,0 +1,30 @@
+# An Toàn — recovery_core
+
+> Cảnh báo an toàn khi dùng interface này. Đọc trước khi triển khai plugin họ vận tốc.
+
+## recovery_core KHÔNG đảm bảo
+
+- **Không collision-check tự động.** Interface không kiểm tra va chạm khi sinh vận tốc
+  (backup/spin) hay khi tạo path. Việc tránh va chạm là trách nhiệm của **plugin** (dùng
+  costmap được cấp qua `initialize`) hoặc của **caller**.
+- **Không quản lý vòng lặp thời gian thực.** Caller chịu trách nhiệm gọi `computeCommand(dt)`
+  đúng nhịp và publish command.
+- **Không đảm bảo frame/đơn vị.** Pose lấy từ costmap/tf phải đúng frame; đơn vị phải nhất quán
+  (m, rad, s, m/s, rad/s).
+- **Default per-cycle fail an toàn.** Behavior không override `computeCommand(dt)` sẽ nhận
+  `RecoveryResult::Failed()` thay vì velocity mặc định.
+
+## Nguyên tắc cho plugin
+
+- Guard `initialized_` và costmap/tf null trước khi thao tác; fail an toàn -> `RecoveryResult::Failed()`.
+- Guard `dt <= 0`, `NaN`, `Inf` trước khi tính velocity.
+- Với họ vận tốc: khi không chắc an toàn, trả **stop command** (Twist 0), không trả vận tốc mù.
+- Kiểm tra NaN/Inf của pose/vận tốc trước khi xuất command.
+- Tôn trọng giới hạn vận tốc/gia tốc của robot (đọc qua param).
+- `BackUpRecovery` có param `require_costmap` để bắt buộc có local costmap trước khi xuất
+  vận tốc lùi. Adapter production vẫn nên có safety gate/collision check riêng trước publish.
+
+## Trách nhiệm caller/adapter
+
+- Đảm bảo ngữ cảnh cho phép recovery (vd: đã dừng planner, vùng xung quanh đủ an toàn).
+- Áp timeout/giám sát ngoài để tránh recovery chạy vô hạn.