Incomex AI Portal
KB-72A3

S178 Fix25 — dot-dot-health generic executor refactor

10 min read Revision 1
s178-fix25dot-healthreportdieu35

S178 Fix25 — dot-dot-health generic executor auto-scale

Session: S178 Fix25 Date: 2026-04-21 Goal: Refactor dot-dot-health từ 9 hardcoded inline checks thành generic executor đọc từ system_health_checks, theo pattern dot-context-pack-verify.sh. Sau refactor: thêm check = INSERT 1 row, không đụng code.

Outcome: ✅ Đạt. 0 hardcode dot_tools inline SQL, 15/15 checks dispatch từ bảng, dry-run PASS, git committed.

1. Generic executor — cấu trúc dispatch

Script mới v2.0.0 (17KB) copy nguyên pattern dot-context-pack-verify.sh:

Thành phần dot-context-pack-verify.sh dot-dot-health.v2.0.0
Env SSOT /opt/incomex/secrets/.env.production (Đ33 §14) ✅ same
PG R/W helper run_pg_rw (psql TCP + PGPASSWORD) ✅ same
PG R/O helper run_pg_ro_db (RO role + read_only tx + statement_timeout) ✅ same
KB fetch curl ${AGENT_DATA_URL}/documents/...?full=true | jq -r '.content' ✅ same (dùng cho cả dispatch_sql và fetch_kb_query)
Load check list SELECT ... FROM system_health_checks WHERE jurisdiction=? AND is_active=true ORDER BY order_index ✅ same (jurisdiction=NRM-LAW-35-V5P2)
Dispatch loop case etype in builtin|sql|function ✅ same
Dispatch builtin Gọi function match executor_ref. declare -F missing → return 2 (soft WARN) ✅ same
Dispatch sql 5 guards: path whitelist + banned tokens + single-statement + RO role + statement_timeout. Wrap SELECT row_to_json(t) FROM (${sql}) t LIMIT 1. So sánh với threshold/comparator/result_field từ threshold_config ✅ same
Dispatch function pg_proc check → gọi fn(cfg::jsonb)::text → t/f ✅ same
Rollup has_critical_fail ? fail : (any_warn ? warn : healthy). Exit 1 nếu critical ✅ same
Results table TSV printf summary (CODE TYPE REF SEV RESULT) ✅ same

Khác biệt nhỏ: dot-dot-health không UPDATE manifest (không có manifest), không --manifest-id. Thêm fetch_kb_query() helper (guards 1-2 only) cho builtin handlers load data-query từ KB — tránh inline SQL.

2. Seed rows — 9 rows DOT-H1..DOT-H9 theo Đ35 §8.1

jurisdiction NRM-LAW-35-V5P2, check_kind detect_only, severity warn (chờ grace-period tracking sau để escalate critical), _dot_origin='dieu35_fix25', is_active=true, order_index=1..9.

Code Executor_type Executor_ref threshold_config
DOT-H1 sql knowledge__current-state__queries__health-dot-h1-unclassified-domain.sql {"threshold":0,"comparator":"eq","result_field":"unclassified_count"}
DOT-H2 sql ...h2-unpaired-b.sql {"threshold":0,"comparator":"eq","result_field":"unpaired_b_count"}
DOT-H3 sql ...h3-missing-target-collections.sql {"threshold":0,"comparator":"eq","result_field":"missing_target_count"}
DOT-H4 builtin check_phantom_file {"data_query":"...h4-filepath-list.sql"} (data từ KB, filesystem loop trong bash)
DOT-H5 sql ...h5-retired-cron.sql {"threshold":0,"comparator":"eq","result_field":"retired_cron_count"}
DOT-H6 sql ...h6-stale-cron.sql {"threshold":0,"comparator":"eq","result_field":"stale_cron_count"}
DOT-H7 builtin check_orphan_file {"data_query":"...h7-registered-paths.sql"} (ls + KB data, filesystem loop)
DOT-H8 sql ...h8-coverage-inconsistent.sql {"threshold":0,"comparator":"eq","result_field":"inconsistent_coverage_count"}
DOT-H9 sql ...h9-retired-reregister.sql {"threshold":0,"comparator":"eq","result_field":"retired_reregister_count"}

Tại sao 2 check builtin thay vì sql: DOT-H4 (phantom) và DOT-H7 (orphan) cần filesystem check ([[ ! -e "$path" ]] / ls /opt/incomex/dot/bin/dot-*) mà SQL executor không làm được. Nhưng data source (list file_path từ registry) vẫn load từ KB query qua fetch_kb_query → giữ nguyên tắc "0 inline dot_tools SQL".

Total KB files uploaded: 9 files, tất cả prefix knowledge/current-state/queries/health-dot-h*.sql:

  • 7 threshold queries (H1, H2, H3, H5, H6, H8, H9) — dispatch_sql nạp
  • 2 data queries (H4, H7) — fetch_kb_query nạp cho builtin handlers

3. Checks ngoài luật (3 items từ v1.0.0 KHÔNG có trong Đ35 §8.1)

Theo yêu cầu: không tự thêm vào bảng, báo cáo để Desktop quyết định:

v1.0.0 Check Mô tả Đề xuất
Check 1 (tier NULL) tier IS NULL — DOT thiếu phân loại A/B Vẫn hữu ích. Nên thêm DOT-H15 sql, severity warn, result_field null_tier_count. Không cần luật mới vì NT11 yêu cầu phân tier.
Check 6 (duplicate code) 2+ DOT cùng code Critical. DB đã có idx_dot_tools_dot_tools_code_unique UNIQUE index nên về lý thuyết không thể xảy ra — nhưng DB-as-SSOT check vẫn nên có (phòng index bị drop). Đề xuất DOT-H16 sql, severity critical, result_field dup_code_count.
Check 7 (missing file_path) file_path IS NULL Overlap với DOT-H4 phantom (coverage_status khác biệt). Đề xuất gộp vào DOT-H4 data-query hoặc thêm DOT-H17 nếu muốn tách biệt.

Desktop có thể INSERT 3 rows mới mà không cần đụng code script — đúng mục tiêu auto-scale.

4. Verify

4.1 Dry-run PASS — 15/15 checks dispatch

$ /opt/incomex/dot/bin/dot-dot-health --dry-run
[OK]    env loaded from SSOT (Đ33 §14)
[OK]    PG healthy (directus@127.0.0.1:5432/directus)
[OK]    jurisdiction=NRM-LAW-35-V5P2 valid
[INFO]  verify: 15 active health_check(s) jurisdiction=NRM-LAW-35-V5P2
...
[INFO]  rollup: pass=5 soft_warn=5 fail_warn=5 fail_crit=0 -> warn
[OK]    dot-dot-health completed   # exit 0

4.2 Results (15 rows) — dispatch breakdown

Code Type Result Ghi chú
DOT-H1 sql PASS 0 unclassified
DOT-H2 sql FAIL_WARN 148 tier-B unpaired (data quality issue)
DOT-H3 sql FAIL_WARN 224 tier-B missing target_collections
DOT-H4 builtin FAIL_WARN 224/224 phantom (many file_paths relative, missing /)
DOT-H5 sql PASS 0 retired+cron
DOT-H6 sql PASS 0 stale cron
DOT-H7 builtin FAIL_WARN 204/204 bin files orphan (registry paths don't match disk paths)
DOT-H8 sql FAIL_WARN 101 coverage_status NULL
DOT-H9 sql PASS 0 retired-reregister in 24h
H10 sql PASS 268 active DOT (existing row pre-Fix25)
DOT-H10..H14 builtin WARN handlers chưa define (existing stubs, return code 2)

Rollup: warn (no critical), exit 0. 5 FAIL_WARN phát hiện vấn đề data quality có thật — nhiệm vụ tiếp theo (follow-up) là clean data, không phải bug script.

4.3 Hardcode SQL = 0 ✅

$ grep -cE '(SELECT|INSERT|UPDATE|DELETE).*dot_tools' /opt/incomex/dot/bin/dot-dot-health
0

Các SELECT còn trong script chỉ chạm các bảng generic (normative_registry, system_health_checks, pg_proc) — không có bảng domain nào hardcode.

4.4 Row count ≥ 15 ✅

SELECT count(*) FROM system_health_checks WHERE jurisdiction='NRM-LAW-35-V5P2';
 count
-------
    15

Breakdown: 9 mới (DOT-H1..H9) + 6 cũ (DOT-H10..H14 + H10) = 15.

5. Git commits

  • Inner repo /opt/incomex/dot: db9286cf4a2318329dd85d3e5020137e210e678f
    • bin/dot-dot-health (refactored v2.0.0)
    • bin/dot-dot-health.bak-fix25 (Đ41 backup)
  • Outer repo /opt/incomex: 47e2be1ce68ee8c5db6c1ce7c6d082182c83b454
    • Mirror dot/bin/dot-dot-health (backup file bị .gitignore, giữ trên disk)

6. Scaling proof — "thêm 1 check = INSERT 1 row"

Để thêm check thứ 16 (ví dụ: tier NULL):

-- Bước 1: Upload SQL query lên KB (1 lần)
-- POST ${AGENT_DATA_URL}/documents với doc_id=knowledge/current-state/queries/health-dot-h15-null-tier.sql

-- Bước 2: INSERT 1 row
INSERT INTO system_health_checks
  (code, name, jurisdiction, check_kind, executor_type, executor_ref, threshold_config, severity_on_fail, is_active, order_index, description, _dot_origin)
VALUES
  ('DOT-H15', 'DOT có tier NULL', 'NRM-LAW-35-V5P2', 'detect_only', 'sql',
   'knowledge__current-state__queries__health-dot-h15-null-tier.sql',
   '{"threshold":0,"comparator":"eq","result_field":"null_tier_count"}'::jsonb,
   'warn', true, 10, 'Đ35 §8.1: tier bắt buộc', 'ops');

-- Bước 3: dot-dot-health tự discover row mới, không cần sửa code.

Không cần: sửa script, restart service, hoặc test regression vì handlers dispatch generic.

NT12 (auto-scale) + NT13 (PG Driven) đạt.

7. Follow-up / Tech-debt

  1. DOT-H10..H14 (5 critical stubs): Handlers dot-dot-health:H10..H14 chưa implement — hiện return rc=2 WARN. Không thể gọi qua declare -F vì tên có :. Đề xuất: UPDATE executor_ref thành check_operation_null_post_grace etc. rồi implement builtin handlers tương ứng. Scope: session khác.

  2. Grace-period tracking: §8.1 spec "warn trong grace, critical sau grace" nhưng schema chưa có cột grace_expires_at. Hiện tất cả 9 check severity=warn. Khi có grace tracking, escalate DB-side (không đụng code).

  3. 3 checks ngoài luật (tier NULL, duplicate code, NULL file_path): Chờ Desktop quyết định thêm DOT-H15/H16/H17 hay bỏ.

  4. File_path data quality: 224 phantom + 204 orphan phát lộ registry drift — nhiệm vụ clean data tách biệt.

  5. log_issue stub: Vẫn dùng stub như verify.sh. Khi Đ22 triển khai fn_log_issue PG function, cả 2 script nên chuyển sang gọi DB function thay vì log_warn stderr.