Điều 31: Luật Toàn Vẹn Hệ Thống — System Integrity Verification Law v1.2 BAN HÀNH
Điều 31: Luật Toàn Vẹn Hệ Thống — System Integrity Verification Law
Version: v1.2 BAN HÀNH | Soạn: S131 | Sửa: S131-R3 (sau hội đồng vòng 2) Tác giả: Huyên (tầm nhìn), Claude Desktop (soạn thảo) Hội đồng: Vòng 1: Gemini (GO), GPT (CONDITIONAL GO → GO). Vòng 2: Gemini (GO), GPT (GO). Tổng điểm sửa: 23 (vòng 1) + 15 (vòng 2) = 38 điểm. Kiểm tra khả thi: PASS 4/4 yếu tố (Design Feasibility Formula). Tham chiếu: Hiến pháp Kiến trúc, Công thức Thiết kế Khả thi, PHỤ LỤC Điều 31.
I. TẦM NHÌN
"Nguyên tắc tuyệt vời nhất của 1 hệ thống: khi có vấn đề, vấn đề đó cần được PHƠI BÀY NGAY (tự động), sau đó đấu nối quy trình triển khai." — Huyên, S129
"Hàng trăm, thậm chí hàng ngàn công cụ tự động, mỗi công cụ làm 1 việc. AI/Agent và User tập trung vào ý tưởng. Hệ thống tự vận hành." — Huyên, S129
Điều 31 KHÔNG phải 1 điều luật đơn lẻ. Đây là tầm nhìn lớn: hệ thống PHẢI tự kiểm tra mình liên tục, tự mở rộng danh mục kiểm tra theo thời gian, và đảm bảo nguyên tắc "Đúng, đủ, sạch, sống" xuyên suốt mọi chuỗi dữ liệu — từ DB đến UI, từ Directus đến Agent Data, từ khai báo (contract) đến thực tế (production).
Thước đo thành công: Khi hệ thống có vấn đề — dù nhỏ nhất — hệ thống TỰ BIẾT trước khi bất kỳ ai (khách hàng, user, agent) phát hiện.
Câu hỏi nền tảng: Chúng ta trông đợi vào hệ thống báo lỗi để biết vấn đề — nhưng chính hệ thống đó chết thì sao? → Xem §IV.9 WATCHDOG.
1.1 Phép ẩn dụ: Bảng đồng hồ buồng lái
Hãy tưởng tượng Incomex web là một chiếc máy bay hiện đại — hoặc gần hơn, một chiếc ô tô thông minh. Khi lái xe, bạn KHÔNG CẦN mở nắp capô mỗi 10 phút để kiểm tra động cơ. Hệ thống cảm biến LIÊN TỤC đo áp suất lốp, nhiệt độ động cơ, mức dầu, tốc độ, ABS, airbag... Khi có vấn đề — dù nhỏ — đèn cảnh báo trên bảng đồng hồ sáng lên NGAY LẬP TỨC. Phi công/tài xế chỉ cần NHÌN bảng đồng hồ là biết máy bay/xe có khỏe không.
Incomex web cũng phải hoạt động như vậy:
| Máy bay / Ô tô | Incomex Web |
|---|---|
| Cảm biến (sensor) | Contract JSON — mỗi contract là 1 cảm biến đo 1 thông số |
| Bảng đồng hồ (dashboard) | Registries Dòng 11 + Health Dashboard — nhìn là biết |
| Đèn cảnh báo (warning light) | system_issues với severity CRITICAL/WARNING |
| Hộp đen (black box) | GH Actions artifacts + evidence_snapshot — mọi sự kiện đều được ghi |
| Kiểm tra định kỳ (maintenance check) | Cron hàng ngày (Vòng B) + Deep Audit (Vòng C) |
| Kiểm tra sau sửa chữa (post-repair check) | Post-Deploy (Vòng A) + Event Recheck (Vòng D) |
| Chế độ tự chẩn đoán (self-diagnostic) | WATCHDOG — hệ thống tự kiểm tra chính mình |
| Kênh khẩn cấp (emergency beacon) | Discord/Telegram webhook — khi mọi thứ khác chết |
Điều 31 KHÔNG chỉ là kiểm tra vài con số trên Registries. Điều 31 là NỀN TẢNG cho toàn bộ độ tin cậy của web — một hệ thống web động, với liên tục các quy trình, dữ liệu thay đổi mỗi ngày bởi nhiều AI agents và con người. Trong môi trường này, việc hệ thống TỰ PHÁT HIỆN sai sót là vô cùng quan trọng — nó là sự khác biệt giữa "một website" và "một cơ thể sống biết tự chẩn đoán."
1.2 Tầm nhìn dài hạn: Từ 5 cảm biến đến 1000+
| Giai đoạn | Số cảm biến (contracts) | Trạng thái hệ thống |
|---|---|---|
| Pilot (hiện tại) | 5 | Biết được 3 trang cốt lõi + sync + runner sống |
| Phase 2-3 | 20-50 | Phủ mọi trang quan trọng, mọi luồng dữ liệu chính |
| 6 tháng | 100+ | Như đồng hồ ô tô — nhìn dashboard là biết web khỏe hay bệnh |
| 1 năm | 500+ | Như cockpit máy bay — mọi thông số đều có cảm biến, mọi drift đều phát hiện trong phút |
| Dài hạn | Tự sinh cảm biến | Hệ thống TỰ phát hiện trang/số/luồng mới chưa có cảm biến → tự đề xuất contract → con người duyệt → cảm biến mới hoạt động |
Mục tiêu cuối cùng: hệ thống KHÔNG BAO GIỜ sai mà không biết. Giống như máy bay hiện đại — tai nạn vẫn có thể xảy ra, nhưng KHÔNG BAO GIỜ xảy ra mà hệ thống không cảnh báo trước.
II. VẤN ĐỀ GỐC RỄ
2.1 Chuỗi dữ liệu phức tạp, xác suất lỗi cao
PostgreSQL → Directus → Agency OS / API Server → Nuxt SSR → Trình duyệt người dùng
PostgreSQL → Directus → Directus Flows → Agent Data (vector) → AI Agents
Mỗi mắt xích trong chuỗi có thể gây lệch: PG trigger không fire, Directus permission sai, API trả thiếu data, Nuxt render sai component, cache cũ, Directus Flow không sync đến Agent Data, vector orphan không có record gốc... BẤT KỲ lệch nào giữa các tầng dữ liệu đều là LỖI.
2.2 Kiểm tra thủ công không bền vững
- User không có thời gian và kiến thức kỹ thuật để kiểm tra chi tiết.
- AI/Agent kiểm tra tốn hàng chục tool calls, mất context, tốn token. Cũng không thể kiểm tra 24/7.
- Kết quả: Vấn đề tồn tại vài ngày/tuần trước khi ai đó tình cờ phát hiện → fix xong lại phát sinh vấn đề mới ở nơi khác → vòng luẩn quẩn.
2.3 Bài học thực tế
Nhiều lần trong lịch sử dự án: agent deploy xong, CI GREEN, nhưng Nuxt hiển thị sai (thiếu dòng, số lệch, UI mất). Agent Data mất đồng bộ với Directus (vector orphan, document thiếu). Nguyên nhân đa dạng: permission, trigger, cache, regression, sync flow lỗi. Tất cả đều có chung 1 đặc điểm: hệ thống không tự biết mình sai.
III. NGUYÊN TẮC CỐT LÕI
Nguyên tắc 1: MỌI lệch đều là lỗi
BẤT KỲ sai khác nào giữa các tầng dữ liệu — dù chỉ 1 con số, 1 dòng text, 1 link, 1 vector orphan — đều là LỖI cần điều tra. Không có "lệch chấp nhận được."
Ở tầng thực thi, cần phân biệt giữa lệch cứng (strict_equals — chắc chắn sai) và lệch mềm (eventual_equals — có thể do timing/cache). Triết lý "mọi lệch = lỗi" giữ nguyên ở mức hiến pháp; operators giúp tránh false positive ở mức runtime.
Nguyên tắc 2: Phát hiện TRƯỚC, fix SAU
Ưu tiên số 1 là PHÁT HIỆN và PHƠI BÀY vấn đề. Fix là bước 2. Hệ thống biết mình sai > hệ thống sai mà không biết.
Nguyên tắc 3: Kiểm tra bằng config, KHÔNG bằng code
Thêm mục kiểm tra mới = thêm 1 dòng trong contract JSON. KHÔNG SỬA CODE runner. Đây là nguyên tắc vàng thiết kế Incomex: thay đổi kinh doanh = thay đổi metadata/config. Đi sửa code = thiết kế tồi.
Nguyên tắc 4: Tự mở rộng theo thời gian
Hôm nay: 5 contracts (pilot). Tháng tới: 20. Năm tới: 100+. Hệ thống PHẢI cho phép mở rộng danh mục kiểm tra KHÔNG GIỚI HẠN — chỉ bằng cách thêm config. Như lắp thêm cảm biến vào xe — không cần thiết kế lại xe.
Nguyên tắc 5: "Đúng, đủ, sạch, sống" cho mọi kiểm tra
- Đúng: Giá trị kiểm tra khớp với thực tế trong DB.
- Đủ: Coverage metrics đạt ngưỡng tối thiểu (xem §IV.8).
- Sạch: Không false positive (2-pass verify), không issue trùng (fingerprint dedupe).
- Sống: Kiểm tra chạy TỰ ĐỘNG, liên tục, không cần ai nhắc. WATCHDOG đảm bảo bản thân runner cũng sống (§IV.9).
Nguyên tắc 6: Ai canh gác người canh gác?
Hệ thống giám sát mà tự chết thì mọi thứ bên trong cũng chết theo — nhưng không ai biết. Điều 31 PHẢI có cơ chế tự kiểm tra chính mình (WATCHDOG). Nếu WATCHDOG im lặng = BÁO ĐỘNG KHẨN CẤP.
IV. MÔ HÌNH TỔNG THỂ
4.1 Kiến trúc Contract-Driven Verification
┌─────────────────────────────────────────────────────────┐
│ §0: CONTRACT SCHEMA (JSON Schema) │
│ Validate contracts trước khi chúng được dùng │
└──────────────────────┬──────────────────────────────────┘
│ validate
┌──────────────────────▼──────────────────────────────────┐
│ CONTRACTS (JSON) — SSOT: định nghĩa MỌI kiểm tra │
│ + WATCHDOG contract (luôn fail — §IV.9) │
│ Mỗi contract có: contract_id, owner, version, │
│ last_verified_at, tier, enabled, grace_seconds │
└──────────────────────┬──────────────────────────────────┘
│ đọc
┌──────────────────────▼──────────────────────────────────┐
│ HEALTH GATE — Kiểm tra production reachable trước │
│ Nếu down → tạo infra_fault, DỪNG integrity checks │
└──────────────────────┬──────────────────────────────────┘
│ production OK
┌──────────────────────▼──────────────────────────────────┐
│ RUNNERS (Playwright + API scripts) │
│ Chạy kiểm tra: DOM vs API vs PG vs Agent Data │
│ 2-pass verify: fail lần 1 → chờ grace_seconds → lần 2 │
│ Mỗi run có run_id duy nhất │
└──────────────────────┬──────────────────────────────────┘
│ phát hiện lệch
┌──────────────────────▼──────────────────────────────────┐
│ DEDUPE ENGINE — violation_hash + business_logic_hash │
│ Cùng lỗi → reopen + tăng count, KHÔNG tạo mới │
│ Cascade → parent issue, child chỉ ghi artifact │
└──────────────────────┬──────────────────────────────────┘
│ issue mới hoặc reopen
┌──────────────────────▼──────────────────────────────────┐
│ SYSTEM ISSUES (Directus collection CAT-017) │
│ Tự tạo/reopen issue: severity + issue_class + evidence │
│ Chỉ chứa VẤN ĐỀ. Pass INFO → artifact/log/report. │
└──────────────────────┬──────────────────────────────────┘
│ hiển thị (3 kênh)
┌──────────────────────▼──────────────────────────────────┐
│ KÊNH 1: Registries Dòng 11 — Dashboard UI │
│ KÊNH 2: Directus system_issues filtered view │
│ KÊNH 3: GH Actions summary / cron report artifact │
└──────────────────────┬──────────────────────────────────┘
│ triage → investigate → fix
┌──────────────────────▼──────────────────────────────────┐
│ Agent/User triage → investigate → fix → re-verify → PASS │
│ Fix xong → close → archive │
└─────────────────────────────────────────────────────────┘
4.2 Contract Schema — "Hợp đồng của chính contract"
Trước khi bất kỳ contract nào được dùng, nó PHẢI pass schema validation.
Bắt buộc validate:
contract_idunique toàn hệ thốngowner(ai chịu trách nhiệm — phải map được tới user/agent hợp lệ)contract_version(semver)last_verified_at(ngày cuối contract được xác nhận còn đúng)enabled(boolean — bật/tắt contract có chủ đích)page_urlhợp lệ (Tier A phải tồn tại trong route map)tierthuộc {A, B, C}operatorthuộc enum hợp lệ (xem §4.4)severitythuộc {CRITICAL, WARNING, INFO}typethuộc enum hợp lệ (xem §4.3)grace_seconds(integer, default 60 — thời gian chờ cho eventual_equals)- Selector/query KHÔNG null theo logic từng check type
dom_vs_dbphải có đủ selector + querydirectus_vs_vectorphải có direction- Cấm 2 checks trùng cùng semantic target trong 1 contract
Stale contract detection: Nếu last_verified_at cũ hơn stale_contract_days (default: 90 ngày), runner tự tạo issue contract_fault WARNING. Contract quá cũ = có thể đã outdated.
Contract mới hoặc chỉnh contract phải đi kèm evidence hoặc bug class tương ứng.
CI pipeline validate contract schema trước khi merge — contract sai = PR bị chặn.
4.3 Năm loại kiểm tra
| Loại | Type code | So sánh gì | Khi nào dùng | Ví dụ |
|---|---|---|---|---|
| DOM vs DB | dom_vs_db |
Nuxt hiển thị vs PG thực tế | Phát hiện chuỗi render lệch | Registries count trên UI ≠ PG query |
| DB vs DB | db_vs_db |
2 nguồn trong PG đều phải khớp | Kiểm chứng kép (Điều 22 §2b) | sum(species) = total row |
| DOM vs Contract | dom_vs_contract |
UI hiển thị vs kỳ vọng cố định | Kiểm tra nội dung static/structure | Trang phải có 30 dòng, 10 headers |
| API vs DB | api_vs_db |
API response vs PG thực tế | Bóc tách render fault vs API fault | Nuxt API endpoint trả sai data |
| Directus vs Agent Data | directus_vs_vector |
Record Directus ↔ Vector Agent Data | Đảm bảo toàn vẹn giữa 2 hệ thống | Record có trong Directus nhưng thiếu vector; vector orphan không có record gốc |
v1.0 core types: dom_vs_db, db_vs_db, dom_vs_contract. Luật cho phép mở rộng thêm types.
Loại 5 — Directus vs Agent Data: Kiểm tra HAI CHIỀU:
- Chiều A: Mỗi record trong các collection có Directus Flow sync → kiểm tra có document tương ứng trong Agent Data không?
- Chiều B: Mỗi document trong Agent Data → kiểm tra có record gốc trong Directus không? (phát hiện vector orphan — rác nguy hại nhất trong hệ thống RAG vì gây hallucination cho AI mà không truy vết được nguồn gốc)
4.4 Operators — Phép so sánh
| Operator | Ý nghĩa | Khi nào dùng |
|---|---|---|
strict_equals |
Giá trị phải khớp chính xác | Số liệu chính xác: count, total |
eventual_equals |
Fail lần 1 → chờ grace_seconds → check lại |
Data có thể delay do sync/cache |
within_window |
Chênh lệch trong khoảng cho phép | Timing-sensitive data |
exists |
Element/value phải tồn tại | Kiểm tra structure: header, link, section |
not_exists |
Element/value KHÔNG được tồn tại | Orphan, deprecated content |
always_fail |
LUÔN FAIL — dùng cho WATCHDOG | Kiểm tra runner còn sống (§IV.9) |
equals |
Alias của strict_equals (backward compatible) | — |
2-pass verify: Khi check fail lần 1 với severity WARNING, runner chờ grace_seconds (default 60s, có thể override per-contract) rồi chạy lại. Chỉ tạo issue nếu fail lần 2. CRITICAL fail = tạo issue ngay (không chờ).
4.5 Severity — Phân cấp tín hiệu
| Severity | Ý nghĩa | Hành động |
|---|---|---|
| CRITICAL | User-facing number/content/link sai, production page hỏng, Tier A fail cứng | Auto-create issue + cảnh báo ngay |
| WARNING | Drift phát hiện nhưng chưa chắc lỗi (cache/timing/eventual consistency) | 2-pass verify → nếu vẫn fail → create issue |
| INFO | Audit pass — ghi nhận để tracking | KHÔNG tạo issue. Ghi vào GH artifact/log/report |
Severity override: Contract có thể ghi severity_override để nâng severity cho trường hợp đặc biệt. Ví dụ: chiều A (Directus→Vector) cho collection must_sync_realtime=true → nâng từ WARNING lên CRITICAL nếu fail quá grace_seconds.
4.6 Issue Class — Phân loại nguyên nhân
Severity ≠ Root cause. Mỗi issue PHẢI có cả severity VÀ issue_class.
| Issue Class | Ý nghĩa | Ví dụ |
|---|---|---|
render_fault |
DB đúng, DOM/UI sai | Nuxt component render lỗi |
data_fault |
DB nguồn sai | Trigger không fire, data import sai |
sync_fault |
Source A và B trong hệ thống lệch nhau | Directus vs Agent Data, PG count vs API count |
contract_fault |
Contract sai/outdated, không phải hệ thống sai | Contract kỳ vọng 30 dòng nhưng thực tế đã thêm 2 dòng mới |
infra_fault |
Production down, timeout, auth, cache | VPS restart, Directus permission reset |
watchdog_fault |
Runner/hệ thống giám sát chết | WATCHDOG không báo fail → runner đã chết (§IV.9) |
4.7 Issue Dedupe — Chống bội thực cảnh báo
Vấn đề: Với 138 collections và 15k records, 1 logic sai có thể đẻ hàng ngàn issues.
Giải pháp:
-
Fingerprint hai tầng:
violation_hash= hash(contract_id + check_id + issue_class) — fingerprint chínhbusiness_logic_hash= hash(nội dung check logic, KHÔNG hash URL/page) — detect lỗi di chuyển khi refactor URL- Unique index cho issue đang mở cùng violation_hash
-
Reopen thay vì tạo mới:
- Cùng hash + issue mở → tăng
occurrence_count+ cập nhậtlast_seen_at+ evidence - Cùng hash + issue close + cùng contract major version → reopen
- Cùng hash + issue close + KHÁC contract major version → tạo mới
- Evidence giữ:
latest_value,sample_values(3 gần nhất),max_delta
- Cùng hash + issue mở → tăng
-
Aggregation:
- CHỈ gom khi cùng TẤT CẢ:
issue_class+source_system+page_url/collection+run_id - KHÔNG gom nếu khác root cause
- Tạo 1 issue tổng kèm danh sách check_ids mẫu (tối đa 10)
- CHỈ gom khi cùng TẤT CẢ:
-
Parent issue cho cascade:
-
5 checks cùng run_id fail → tạo 1 PARENT issue (infra_fault hoặc sync_fault)
- Child fails chỉ ghi artifact, KHÔNG tạo issue riêng
-
-
Fields bắt buộc cho system_issues:
source_system,issue_class,violation_hash,business_logic_hashrun_id,first_seen_at,last_seen_at,occurrence_countverification_contract_id,evidence_snapshot(JSON với latest_value, sample_values, max_delta)
4.8 Coverage Metrics
3 chỉ số BẮT BUỘC:
| Metric | Công thức | Loại ngưỡng | Ngưỡng | Hành động khi không đạt |
|---|---|---|---|---|
| Page Coverage | Trang có contract / Tổng trang theo tier | GATE (cứng) | Tier A: 100% | CHẶN: không mở rộng Tier B |
| Invariant Coverage | Invariant đã encode / Tổng invariant | TARGET (mềm) | ≥ 80% | CẢNH BÁO: ưu tiên bổ sung |
| Runtime Pass Rate | Checks pass / Tổng checks | HEALTH (KPI) | ≥ 95% | ĐIỀU TRA: phân tích root cause |
4.9 WATCHDOG — Ai canh gác người canh gác?
"Who watches the watchmen?"
Vấn đề: Runner chết → mọi kiểm tra dừng → KHÔNG AI BIẾT. Sự im lặng giả tạo.
Giải pháp — WATCHDOG contract:
{
"contract_id": "CTR-WATCHDOG",
"name": "WATCHDOG — Runner Liveness Check",
"tier": "A",
"type": "dom_vs_contract",
"owner": "system",
"enabled": true,
"contract_version": "1.0.0",
"checks": [
{
"check_id": "CTR-WATCHDOG-01",
"description": "Check luôn FAIL — nếu không thấy fail, runner đã chết",
"operator": "always_fail",
"severity": "CRITICAL",
"expected": "Phải tạo issue watchdog_fault MỖI LẦN chạy"
}
]
}
Cơ chế:
- WATCHDOG LUÔN chạy trong mọi vòng (A, B, D). Không thể tắt.
- Mỗi run → PHẢI fail → cập nhật watchdog issue
last_seen_at. - Cron ĐỘC LẬP kiểm tra mỗi giờ:
last_seen_atcũ hơn 26h → BÁO ĐỘNG KHẨN CẤP qua Discord/Telegram. - WATCHDOG không đếm vào pass rate (meta-check).
- Kênh ngoài là backup ĐỘC LẬP — khi GH Actions/Dòng 11 đều chết, webhook vẫn báo.
V. QUY TRÌNH KHÉP KÍN
5.1 Bốn vòng lặp kiểm tra
| Vòng | Tần suất | Trigger | Phạm vi |
|---|---|---|---|
| A. Post-Deploy | Sau MỖI deploy | GH Actions workflow_run | Tier A + WATCHDOG |
| B. Scheduled Audit | Cron 3h sáng | GH Actions cron | TẤT CẢ + WATCHDOG |
| C. Deep Audit | Khi nghi ngờ / milestone | Manual | PG raw vs API vs DOM vs Vector |
| D. Event-Triggered | Khi có sự kiện | GH Actions dispatch | Liên quan + WATCHDOG |
5.2 Quy trình xử lý
1. HEALTH GATE → down → infra_fault, DỪNG
2. WATCHDOG → PHẢI fail → cập nhật last_seen_at
3. Checks → CRITICAL=issue ngay, WARNING=2-pass, INFO=artifact only
→ Cascade (>5 fails) → parent issue
4. DEDUPE → violation_hash + business_logic_hash + contract major version rule
5. TRIAGE → SLA: watchdog 30m, infra 1h, CRITICAL 4h, WARNING 24h
6. INVESTIGATE → phân loại issue_class + evidence_snapshot
7. FIX → root cause (KHÔNG lừa check)
8. RE-VERIFY → runner chạy lại → close
9. ARCHIVE → close > 30 ngày → archive
10. UPDATE → bug class mới → bổ sung contract
5.3 Pilot Report Template
Mỗi run → GH artifact chứa: run_id, timestamp, contracts_loaded, checks_run/pass/fail, issues_new/reopened, pass_rate, page_coverage, watchdog_status (ALIVE/DEAD).
5.4 Mở rộng danh mục
Thêm kiểm tra = thêm contract JSON → CI validate → merge → runner tự đọc. KHÔNG SỬA CODE.
VI. TÍCH HỢP DOT SCANNING — Điều 23 dưới Điều 31
Điều 23 là nguyên tắc tam quyền kiểm tra độc lập. Điều 31 là cơ chế thực thi các kiểm tra đó dưới dạng contracts và runners. Điều 31 không thay thế Điều 23.
| Hoạt động | Từ v1.1+ thuộc Điều 31 |
|---|---|
| Orphan detection (L1/L2/L3) | Contract type: db_vs_db |
_dot_origin validation |
db_vs_db hoặc dom_vs_contract |
verify_counts() |
Vòng B Scheduled Audit |
| Entity lifecycle | db_vs_db |
| Directus ↔ Agent Data | directus_vs_vector |
6.3 CTR-SYNC-001 (Directus ↔ Agent Data)
{
"contract_id": "CTR-SYNC-001",
"name": "Directus ↔ Agent Data Bidirectional Sync",
"tier": "A", "type": "directus_vs_vector",
"owner": "system", "enabled": true,
"contract_version": "1.0.0", "grace_seconds": 300,
"checks": [
{
"check_id": "CTR-SYNC-001-A",
"description": "Directus record → Agent Data document tồn tại",
"direction": "directus_to_vector",
"collections": ["knowledge_documents"],
"match_keys": ["source_id", "source_collection", "source_pk"],
"operator": "eventual_equals", "severity": "WARNING",
"severity_override": { "condition": "grace_seconds_exceeded", "escalate_to": "CRITICAL" },
"freshness_check": { "enabled": true, "max_lag_seconds": 3600 }
},
{
"check_id": "CTR-SYNC-001-B",
"description": "Agent Data document → Directus record gốc tồn tại",
"direction": "vector_to_directus",
"match_keys": ["source_id", "source_collection", "source_pk"],
"operator": "exists", "severity": "CRITICAL"
}
]
}
Pilot: CHỈ knowledge_documents. Mở rộng sau.
VII. QUAN HỆ ĐIỀU 30 ↔ ĐIỀU 31
| Điều 30 | Điều 31 | |
|---|---|---|
| Khi | Trước deploy (CI gate) | Sau deploy + liên tục |
| Môi trường | Preview/Staging | Production |
| Focus | Regression from code change | Drift across live chain |
| Outcome | PR blocked | system_issue created |
Khác môi trường, trigger, artifact, outcome. Overlap có chủ đích, không conflict.
VIII. CÔNG CỤ + MÔI TRƯỜNG
| Bước | Tool | Sẵn? | Nơi đọc/ghi |
|---|---|---|---|
| Validate contracts | JSON Schema | ⚠️ Tạo | tests/contracts/schema.json |
| Health gate | curl/Playwright | ✅ | Production URL |
| WATCHDOG | Contract + cron + webhook | ⚠️ Tạo | tests/contracts/watchdog.json + Discord |
| Run checks | Playwright + fetch | ✅ | tests/e2e/ |
| 2-pass verify | Grace period wrapper | ⚠️ Tạo | Trong runner |
| Dedupe | Hash + upsert | ⚠️ Tạo | system_issues (CAT-017) |
| Create/reopen issue | Directus API | ✅ | CAT-017 (cần ~8 fields mới) |
| Dòng 11 UI | Registries component | ❌ Khôi phục | Nuxt UI |
| Cron/Event | GH Actions | ✅ | .github/workflows/ |
| DB source | API endpoints | ✅ | /api/registry/* (cần raw-counts) |
| Vector source | Agent Data API | ✅ | Agent Data |
| Pilot report | GH artifact | ⚠️ Tạo | GH Actions |
IX. DANH MỤC PILOT
| Contract | Scope | Tier | Checks |
|---|---|---|---|
| CTR-001 | Registries Layer 1 | A | ~15 |
| CTR-002 | Health Dashboard | A | ~5 |
| CTR-003 | Species Matrix | A | ~10 |
| CTR-SYNC-001 | Directus ↔ Agent Data (knowledge_documents) | A | 2 + freshness |
| CTR-WATCHDOG | Runner liveness | A | 1 (always_fail) |
Phase 2: CTR-004 (Unmanaged), CTR-005 (Homepage), mở rộng sync collections.
X. THỨ TỰ TRIỂN KHAI
| # | Item | Lý do |
|---|---|---|
| 1 | Contract Validation | Nền sai → mọi thứ sai |
| 2 | Ranh giới Điều 30 ↔ 31 | Không tách → lẫn preview/prod |
| 3 | Dedupe + WATCHDOG | Issue storm + runner chết = mù |
| 4 | Coverage Metrics | Biết thiếu gì — sau 3 items trên |
XI. REGISTRIES DÒNG 11
Khôi phục Dòng 11 + 3 kênh phơi bày (UI + Directus filtered + GH report). Nếu Dòng 11 hỏng → 2 kênh còn lại. Nếu runner chết → WATCHDOG qua kênh ngoài.
XII. TẦM NHÌN DÀI HẠN
12.1 Lộ trình
| Giai đoạn | Contracts | Phạm vi |
|---|---|---|
| Pilot | 5 | 3 trang + sync + WATCHDOG |
| Phase 2 | ~10 | + Homepage, Unmanaged, L2, thêm sync |
| Phase 3 | ~20 | + Entity detail, Workflow |
| 6 tháng | ~100 | Như đồng hồ ô tô |
| 1 năm | 500+ | Như cockpit máy bay |
| Dài hạn | Tự sinh | Hệ thống tự đề xuất contract cho trang/số chưa có cảm biến |
12.2 Tính năng nâng cao (ghi nhận)
| Tính năng | Mô tả |
|---|---|
| Self-Healing | Agent tự fix lỗi đơn giản + log "Auto-fixed" |
| CRITICAL blocks PR | "Stop the line" |
| Cross-Service Integrity | File GCS vs Record DB |
| Auto-generated contracts | Từ registry metadata |
| Selector feasibility | Shadow DOM/iframe detection |
XIII. TÍCH HỢP ĐIỀU LUẬT KHÁC
| Điều | Quan hệ |
|---|---|
| Điều 6 (Đồng bộ) | Điều 31 = cơ chế thực thi |
| Điều 22 (Tự sửa chữa) | Điều 31 = đầu vào |
| Điều 23 (DOT Scanning) | Điều 23 = nguyên tắc, Điều 31 = thực thi (§VI) |
| Điều 26 (Counting Law) | verify_counts() → contract hóa |
| Điều 28 (Standard Template) | Contract theo template |
| Điều 29 (Species) | Species priority → thứ tự kiểm tra |
| Điều 30 (Hồi quy) | Pre-deploy ↔ Post-deploy (§VII) |
| Luật 5 (Tự Phát hiện) | Điều 31 = hiện thực hóa |
XIV. KIỂM TRA KHẢ THI (Design Feasibility Formula)
| # | Yếu tố | Đánh giá | ✅/❌ |
|---|---|---|---|
| 1 | Mô hình tổng thể | Contract-driven: thêm cảm biến = thêm JSON, không sửa code. Scale vô hạn bằng metadata. Giải thích 3 câu: "Mỗi con số trên web có 1 cảm biến (contract). Cảm biến đo liên tục. Lệch = đèn cảnh báo sáng." | ✅ |
| 2 | Quy trình khép kín | Deploy/Cron/Event → Health Gate → WATCHDOG → Checks → Dedupe → Issue → Triage → Fix → Re-verify → Close → Archive → Update Contract → quay lại. Không mũi tên nào đi vào void. WATCHDOG = meta-loop kiểm tra cả hệ thống giám sát. | ✅ |
| 3 | Công cụ đầy đủ | 8 items cần tạo (glue/config), 0 framework mới. Playwright ✅, Directus API ✅, GH Actions ✅, PG ✅, Agent Data API ✅. | ✅ |
| 4 | Môi trường thực thi | Contracts ở tests/contracts/, runner ở tests/e2e/, issues ở CAT-017, workflows ở .github/, UI ở Registries. 80% sẵn, 20% cần tạo/khôi phục. |
✅ |
Kết luận: PASS 4/4. Khả thi để triển khai pilot.
Điều 31 v1.2 BAN HÀNH | S131 | 38 điểm sửa qua 2 vòng hội đồng. PASS 4/4 khả thi.
Hội đồng: Gemini GO×2, GPT GO×2.
search_knowledge("system integrity verification law")