# Core `rt-host` — Runtime host & module loader

> 07/7/2026 · Repo: **ws_suns** · Đánh giá: **✅ Ledger tốt · ⚠ migration tracking + seed tạm** · Bản HTML: [rt-host.html](rt-host.html) · [Review tổng core](core-review-2026-07-07.md)

## 1. Vai trò
Trái tim runtime: **ledger `installed_modules`** (version, checksum_sha256, enabled/status), loader mount module lúc boot, **enable/disable không cần restart**, hooks install/upgrade/uninstall.

## 2. Thành phần chính

| Thành phần | Vai trò |
|---|---|
| **runtime-core (package)** | createRuntimeCore: ledger + đối chiếu ledger⇄disk (fail-fast khi lệch) + coreTables bảo vệ + checksum |
| **runtimeCore.js (host)** | Inject authenticate/authz/verifyLicense/hooks; onInstalled copy roleTemplates vào engine + bump epoch |
| **ogapp CLI** | list/install/uninstall/enable/disable/info · tải từ registry hoặc CP · hỗ trợ file local |
| **Migrations** | SQL chạy theo alphabet, quy ước idempotent IF NOT EXISTS — **không có bảng tracking đã chạy** |

## 3. Hiện trạng (đọc từ code)
- Ledger có checksum_sha256, cờ enabled (route 404 ngay không cần restart), fail-fast khi ledger bật mà thiếu code trên disk — ngang cơ chế npm/Docker
- Hooks lifecycle tách bạch, lỗi hook không phá cài đặt (log warning) — hợp lý
- ⚠ **Migration không tracking:** chỉ dựa idempotent convention. Đủ cho CREATE TABLE, nhưng GĐ1 sắp ALTER (student 1.2 thêm cột) — chạy lại toàn bộ file mỗi lần cài đè là mong manh
- ⚠ Khối **auto-run seeds đóng gói** đánh dấu 'TẠM THỜI — XÓA SAU TEST' (03/7) vẫn còn; lỗi seed không fail install

## 4. Khuyến nghị — tham chiếu hệ phổ biến

| Tham chiếu | Khuyến nghị |
|---|---|
| **Flyway / Knex / Odoo module upgrade** | **Ưu tiên cao:** thêm bảng `module_migrations(module_key, filename, checksum, applied_at)` — chỉ chạy file chưa applied, chặn file đã applied bị sửa nội dung. Nhỏ (~2-3 ngày) nhưng chặn cả lớp lỗi upgrade trước khi module domain vào giai đoạn ALTER |
| **Vệ sinh** | Gỡ khối auto-seed tạm thời đúng như ghi chú; seed chuyển thành lệnh chủ động `ogapp seed <key>` |
| **Docker health** | Thêm health-check per-module sau mount (route ping) — phát hiện module hỏng ngay lúc boot thay vì lúc user bấm |

## 5. Liên kết trong core
- **sdk** — build ra .ogapp mà host cài
- **rt-authz** — nhận roleTemplates lúc onInstalled
- **registry / cp-store** — nguồn artifact


## Ma trận tác nhân × năng lực

Core không phải module nghiệp vụ — ma trận theo **tác nhân**, kèm cơ chế/quyền gate. R đọc · W thực hiện · A duyệt.

| Năng lực | Cơ chế / quyền gate | SUPER | OWNER/QTHT | DEV | SVC | USER |
|---|---|:--:|:--:|:--:|:--:|:--:|
| Cài / gỡ module | system.admin.modules.install/delete | — | W | — | — | — |
| Bật / tắt module (không restart) | system.admin.modules.* | — | W | — | — | — |
| Mount + chạy migrations lúc boot | tiến trình hệ thống | — | — | — | W | — |
| Verify checksum/license lúc cài (đích P1/CP-03) | hook verifyLicense + checksum | — | — | — | W | — |
| Xem health module (đích) | system.admin.health.view | — | R | — | — | — |

SUPER = super admin CP · OWNER/QTHT = quản trị WS · DEV = developer/publisher · SVC = service-to-service · USER = người dùng cuối. Mục **(đích)** = theo khuyến nghị P1–P5.