Incomex AI Portal
KB-7531

§2.6d KS.3 Metadata Shells + §2.7 9 Writer Verify

7 min read Revision 1
s176pg-reconfigks3metadata-shellsfile-path-gap

§2.6d + §2.7 — KS.3 METADATA SHELLS + VERIFY 9 WRITER S175

Part of: PG Reform Tools — S176 mission Prev: 05-ks2-mar10-debunked.md ← | → Next: 07-phuong-an-a-plus.md Khối điều tra: KS.3 (15 script unregistered) + verify 9 writer S175 Kết quả: Pattern metadata catch-up gap ~22% registry. 4 TD mới.

§2.6d PATTERN "METADATA SHELLS" — Phát hiện KS.3

🟡 METADATA CATCH-UP GAP — Pattern lặp ở ~22% registry:

K1 đã thấy 60/272 record file_path=NULL. KS.3 điều tra 15 script dot/bin/ không match registry qua file_path, giải thích được 14 trong 60 và mở ra pattern hệ thống hơn.

Kết quả KS.3

Nhóm Số lượng Mô tả
(a) Cố tình bypass 0/15 (0%) Không ai cố tình trốn luật
(b) Metadata catch-up gap 14/15 (93.3%) Có metadata DOT_* đầy đủ (tier, domain, paired, trigger) nhưng file_path=NULL
(c) Di tích hợp lệ 1/15 (6.7%) dot-cron-matrix-setup — installer one-shot đã chạy xong

Smoking gun KS.3: 14/15 script có first commit ghi nguyên văn "sync: copy 35 VPS-only files to macbook (Step 2A)" ngày 2026-04-05 → script chạy trên VPS production nhiều ngày/tuần TRƯỚC khi git biết. Commit tự thừa nhận "VPS-only files".

Trong 14 script "quên link", 6 đang CHẠY THẬT trên production cron

  • dot-script-lint — CN 03:30
  • dot-nrm-discover — CN 04:00
  • dot-nrm-verify — daily 05:00
  • dot-nrm-sync — daily 05:30
  • dot-nrm-lifecycle — daily 06:00
  • dot-doc-partition — quarterly

Phát hiện mỉa mai

dot-script-lint là linter chống hardcode (quét pattern PG_CONTAINER="postgres", -U directus, docker exec postgres) nhưng chính nó dùng ${PG_CONTAINER:-postgres} để lách regex. Thanh tra tự bẻ cong luật mình. Semantic vẫn là direct PG writer qua run_pg psql.

5 WHY

WHY-A — dot-cron-matrix-setup + dot-script-lint

Không cố tình bypass. cron-matrix-setup là oversight (installer one-shot không được coi là DOT — asymmetry với dot-cron-pivot-setup DOT-308 có register). script-lint là self-aware lỗ hổng — regex detection literal không bắt được semantic. Bài học: định nghĩa "DOT là gì" chưa đủ chặt.

WHY-B — Cụm dot-nrm-* (10)

Metadata khai đầy đủ (tier/domain/paired/trigger chuẩn chỉnh), chỉ thiếu file_path. Không phải decision (nếu cố tình sẽ có exempted_reason). Là workflow bug: OR §VI "sửa VPS → git push 2×/ngày" nhưng không có bước dot-register-self sau khi tạo script trên VPS. Operator BIẾT cách set fp (DOT_NRM_DRAFT có fp) — chỉ quên ở 14 record còn lại. Dù Đ33 §13 E3 hợp pháp hoá ngoại lệ normative, file_path gap vẫn là bug.

WHY-C — Cụm dot-doc-* (3)

Cùng pattern (b), cộng thêm "DOT đăng ký trước implementation". 2/3 là placeholder chờ dep (docxtemplater, Carbone CE). NT12 pair tier-A ↔ tier-B đều placeholder → pair không verify được gì thật.

WHY-D — Tại sao §0-AY không catch

Cảnh sát hiện có (dot-dot-coverage, dot-dot-health, dot-orphan-scan) chỉ kiểm "có trong registry không", không kiểm "link đúng file_path không". Registry có thể có shell rỗng fp → §0-AY literal thoả mãn. Thiếu DOT dot-file-path-orphan-check đối chiếu ls dot/bin/ vs SELECT file_path FROM dot_tools WHERE file_path IS NOT NULL. Không có CI gate pre-merge.

WHY-E — Pattern lặp ở bao nhiêu cụm (bài học gốc nhất)

K1 có 60/272 record file_path=∅ (22%). KS.3 giải thích 14/60. Còn 46 record thuộc nhiều cụm khác: cụm MATRIX (DOT-312..314), cụm KG (DOT_KG_* ~20), cụm NRM còn dư, cụm MISC. Pattern lặp ≥ 4 cụm, ảnh hưởng ~22% registry. Không phải bug riêng lẻ — là hệ quả cấu trúc: registry không có constraint file_path NOT NULL + CI gate thiếu + DOT 100% ban hành 2026-03-30 không kèm registry sanity check → registry đã dirty từ trước khi luật có hiệu lực.

4 TD mới phát sinh từ KS.3

TD Priority Mô tả
TD-S176-METADATA-CATCHUP 🔴 High (áp đảo 14/15) PG CHECK constraint file_path IS NOT NULL OR file_path_status='placeholder'; DOT mới dot-file-path-orphan-check tier A cron daily; CI pre-merge hook; backfill 46 record. Đợt 8+9 + Đ33 §17.
TD-S176-VPS-FIRST-NO-HOOK 🟡 Medium OR §VI không có bước dot-register-self sau khi tạo script VPS. Fix: cron push 2×/ngày thêm dot-file-path-orphan-check trước git push HOẶC VPS pre-commit hook. Đợt 8.
TD-S176-LINTER-SELF-EXEMPT 🟢 Low dot-script-lint tự lách regex. Fix: (1) mở rộng pattern bắt ${VAR:-default} HOẶC (2) chuyển ghi system_issues qua Directus API. Đợt 4.
TD-S176-INSTALLER-NOT-DOT 🟢 Low Định nghĩa DOT chưa cover installer/bootstrap/one-shot. Fix: thêm field kind vào dot_tools enum {writer, checker, installer, bootstrap, one_shot}. Đợt 3.

Hệ quả thiết kế

  • §0-AY đang bị vô hiệu hoá bằng "metadata shells" (row có code nhưng rỗng file_path) → luật hiện tại không chặn được, cần constraint cứng ở tầng PG schema
  • "Registry không tin được" — mọi audit sau này phải xử lý trường hợp file_path=NULL. Fix gốc = constraint cứng + backfill 1 lần, sau đó mọi query có thể tin
  • VPS-first workflow là tính năng, không phải bug — nhưng phải có hook xác nhận metadata đầy đủ trước khi git push, không phải sau

§2.7 Verify 9 writer S175

# Writer Tồn tại? Credential L H
1 dedupe.js ✅ Directus API L1 via Directus H3
2 dot-collection-health ✅ Directus API L1 H3
3 dot-apr-health ✅ Directus API L1 H3
4 dot-layer-integrity-audit ✅ Directus API L1 H3
5 dot-registry-crosscheck ✅ Directus API L1 H3
6 dot-pg-audit-ensure ✅ docker exec postgres L2 (DDL bootstrap) H3
7 dot-id-collision-check ✅ Directus API L1 (read) H3
8 dedupeAndReport (main.js 7 call sites) ✅ via dedupe.js L1 via Directus H3

Tất cả 9 writer còn tồn tại. Bệnh dup không phải do writer biến mất, mà do pattern code + thiếu UNIQUE constraint + thiếu DOT cặp verifier. KS.5 sẽ cross-check với 12 file SELECT-then-INSERT (K1) — dot-collection-health nằm trong cả 2 danh sách.

File 06 — §2.6d KS.3 + §2.7 | Index | S176 | Living doc