Incomex AI Portal
KB-36F0 rev 6

Điều 3: Luật Metadata

10 min read Revision 6
lawdieu-3metadatadescriptionmachine-checkables178-fix23

ĐIỀU 3: LUẬT METADATA — MỌI THỨ PHẢI CÓ NHÃN DÁN

§1. Nguyên tắc

Mỗi thực thể, kể cả đơn vị nhỏ nhất, phải mang metadata đầy đủ. Metadata phải tìm kiếm được (search/query).

Metadata = ngôn ngữ để hệ thống TỰ HIỂU MÌNH. Khi metadata đủ → AI tự trả lời: thực thể này dùng ở đâu? ai quản lý? liên quan gì? trạng thái?

§2. Khung metadata bắt buộc

Field Mục đích Bắt buộc
code Mã PREFIX-NNN ✅
name Tên hiển thị (VN) ✅
name_en Tên tiếng Anh (cho AI/agents) ✅
description Mô tả mục đích — theo quy cách §2.1 ✅
classification Phân loại — xem §2.3 legacy ✅
status Vòng đời: draft → active → deprecated → retired ✅
owner Ai/agent chịu trách nhiệm ✅
layer Tầng kiến trúc (1-5) ✅

§2.1 — Quy cách Description (bổ sung S178 Fix 23, Đ43 Phase C Track A)

Description phải đạt 4 tiêu chí machine-checkable:

Tiêu chí Kiểm tra PG enforcement
C1: Không rỗng btrim(description) != '' Trigger (Đ4 §2.1)
C2: Đủ dài length(btrim(description)) >= min_length (config-driven, baseline 30 ký tự) Trigger (Đ4 §2.1)
C3: Không gaming description !~ '^(.)\1{9,}' AND description !~ '^[.\-_\s]{10,}' Trigger (Đ4 §2.1)
C4: Tiếng Việt có dấu Viết tiếng Việt có dấu, cho phép xen thuật ngữ kỹ thuật tiếng Anh Spot-check (không PG enforce)

Config PG: dot_config.description_min_length = 30 (UPDATE để điều chỉnh, NT4).

Enforcement: Đ4 §2.1 Birth Description Guard enforce C1-C3 tại INSERT/UPDATE. Đ43 H11 scan định kỳ (dual-trigger NT12).

§2.2 — Quy cách riêng per entity type (bổ sung S178 Fix 23)

Loại entity Nội dung bắt buộc Độ dài khuyến nghị
DOT (dot_tools) Mục đích + Trigger + Paired DOT → xem Đ35 §4.1.1 50-200 ký tự
Collection / Table Chứa gì + vai trò trong hệ thống + lớp (Não/Kho/Cổng) 30-150 ký tự
Domain Phạm vi quản lý + thành phần chính 30-100 ký tự
Config / Seed Tham số điều khiển hành vi nào 20-100 ký tự
Species / Taxonomy Đại diện nhóm nào + quan hệ parent 30-100 ký tự
Governance Quy tắc/ràng buộc gì + áp dụng đối tượng nào 30-150 ký tự

Bảng trên = hướng dẫn nội dung mô tả chi tiết (mức 2, §2.5), không enforce cứng PG. PG chỉ enforce C1-C3 (§2.1). Nội dung đúng quy cách = trách nhiệm agent viết + spot-check khi review.

Viện dẫn: Mô tả cơ bản (mức 1) theo template §2.6 + Phụ lục Đ3. DOT riêng xem Đ35 §4.1.1.

§2.3 — Field classification — ghi chú legacy (bổ sung S178 Fix 23)

Field classification (core/module/data/governance/operational) trong §2 là thiết kế ban đầu từ trước khi Đ24 (Luật Nhãn), Đ29 (Luật Phân loại) được enacted. Hiện tại hệ thống phân loại đa chiều đã có:

  • Đ24: 6 facets + entity_labels + label_rules
  • Đ29: governance_role (governed/observed/excluded)
  • Đ35: tier/domain cho DOT

Field classification vẫn giữ cho tương thích ngược. Khi Track B hoàn thành (Đ24 mở rộng + Đ29 tích hợp), field này sẽ được deprecated chính thức và thay bằng tham chiếu Đ24/Đ29.

§2.4 — Ngoại lệ backfill description (bổ sung S178 Fix 23)

Backfill description là công việc trí tuệ: đọc code, hiểu ngữ cảnh, viết mô tả. DOT bash không có khả năng suy luận ngữ nghĩa.

  • Pha suy luận/sinh: AI agent (Gemini CLI, Codex, Claude Code) đọc source code + metadata → sinh description. Ngoại lệ trí tuệ.
  • Pha ghi dữ liệu: PHẢI đi qua write path hợp pháp có audit: Directus REST API (gateway chính thức DB directus — Đ33 §0.1) hoặc DOT có log. KHÔNG ghi raw SQL.
  • Truy vết: Ghi admin_fallback_log cho toàn chiến dịch backfill. Retroactive APR sau 48h.
  • Provenance: Gán label PROV-AI (Đ24 facet FAC-PROV) cho mọi description do AI sinh. Chuyển PROV-HUMAN sau khi human review.
  • Tương lai: Khi Langroid agent hoặc Đ37/Đ38 hoàn thiện → chuyển sang DOT tự động.

§2.5 — Hai mức mô tả (bổ sung S178 Fix 28, Description Governance Package)

Mọi entity có cột description phân biệt 2 mức:

Mức Tên Ai viết Khi nào Nội dung Provenance (Đ24)
Cơ bản Mô tả cơ bản Hệ thống tự sinh (PG trigger tại birth — Đ4 §2.1) INSERT tự động Metadata có sẵn trong PG: lớp cấu tạo (Đ0-B), loài (Đ29), domain, trigger, paired — theo template §2.6 PROV-DOT
Chi tiết Mô tả chi tiết AI agent hoặc người Sau birth, batch hoặc on-demand Nhiệm vụ cụ thể, ngữ cảnh, lý do tồn tại — nội dung ngữ nghĩa máy không tự suy luận được PROV-AI hoặc PROV-HUMAN

Quy tắc:

  • Mô tả cơ bản = bắt buộc 100%, hệ thống tự sinh. Thiếu = hạ tầng hỏng.
  • Mô tả chi tiết = nâng cao, có lộ trình. Thiếu = công việc chưa hoàn thành.
  • Mô tả chi tiết GHI ĐÈ mô tả cơ bản (cùng cột description). Provenance label chuyển từ PROV-DOT → PROV-AI/PROV-HUMAN (Đ24 FAC-PROV).
  • Mô tả chi tiết PHẢI bao hàm hoặc paraphrase thông tin cơ bản. Agent/người viết PHẢI đọc mô tả cơ bản hiện tại trước khi ghi đè.
  • Kiểm tra mức: xem provenance label (Đ24). PROV-DOT = chỉ cơ bản. PROV-AI/PROV-HUMAN = đã chi tiết.

Phạm vi mô tả chi tiết (mức 2) — Phân biệt thực thể kiến trúc vs bản ghi vận hành:

Mô tả chi tiết CHỈ áp dụng cho thực thể kiến trúc — entity đại diện cho thành phần cố định trong thiết kế hệ thống. KHÔNG áp dụng cho bản ghi dữ liệu vận hành — entity được tạo liên tục bởi hoạt động runtime.

Tiêu chí Thực thể kiến trúc Bản ghi dữ liệu vận hành
Tồn tại vì Thiết kế hệ thống Hoạt động runtime
Số lượng Ổn định, thay đổi chậm Biến động liên tục
Thêm/xóa = Thay đổi kiến trúc Hoạt động bình thường
Mô tả chi tiết CẦN — giúp hiểu vai trò + cách hoạt động KHÔNG CẦN — metadata cấu trúc (title, severity, source) đã đủ

Ví dụ bản ghi vận hành trong governed: system_issues (ISS-XXXX, tạo/đóng liên tục bởi executor). Ví dụ ngoài governed (đã đúng sẵn): system_log, audit_log.

Quy tắc:

  • Bản ghi vận hành vẫn được mô tả CƠ BẢN (mức 1, trigger auto-gen).
  • Bản ghi vận hành KHÔNG nằm trong scope H11b (Đ43 §9.1) và KHÔNG nằm trong scope enrichment (Phụ lục Đ3 §A.3).
  • governance_role KHÔNG ĐỔI — system_issues vẫn governed (cần code, lifecycle, auto-close). Chỉ loại khỏi scope enrichment.
  • Config PG (NT4+NT13): dot_config.h11b_exclude_species = JSON array species_code loại trừ. H11b query + enrichment đọc config này. Thêm species = UPDATE config, 0 sửa code.

Viện dẫn: Template → Phụ lục Đ3 §A.1. Enforcement → Đ4 §2.1. Giám sát → Đ43 §9.1 (H11a/H11b). Provenance → Đ24 FAC-PROV. Lớp cấu tạo → Đ0-B. Loài → Đ29.

§2.6 — Phụ lục Template mô tả cơ bản (bổ sung S178 Fix 28, Description Governance Package)

SSOT phân rõ:

  • dot_config = runtime SSOT DUY NHẤT cho template. Trigger/function đọc từ đây.
  • Phụ lục Đ3 = documentation mirror. Khi thay đổi: UPDATE dot_config TRƯỚC, cập nhật phụ lục SAU.

Lookup chain 4 tầng:

1. desc_template_<table>_<composition_level>   (ưu tiên cao nhất)
2. desc_template_<table>                        (table-specific)
3. desc_template_level_<composition_level>       (level-default)
4. desc_template_default                         (fallback cuối)
5. NULL → KHÔNG gen, fail-safe (NT9)

Ngôn ngữ: Tiếng Việt có dấu mặc định (Đ3 §2.1 C4). Giữ nguyên code/enum/thuật ngữ kỹ thuật.

Viện dẫn: Chi tiết template → Phụ lục Đ3 §A.1.

§3. Khung metadata mở rộng (tuỳ chọn)

Field Mục đích Bắt buộc
tags Nhãn tự do, dùng cho search/filter 🟡
notes Ghi chú bổ sung cho trường hợp đặc biệt không mô tả hết bằng description. Lưu extra_metadata JSONB nơi có, cuối description nơi chưa có JSONB. 🟡
used_by Danh sách thực thể đang dùng (dependency ngược) 🟡
triggers Danh sách sự kiện mà thực thể này kích hoạt 🟡
triggered_by Danh sách sự kiện kích hoạt thực thể này 🟡
related_to Liên kết tới thực thể liên quan (không phải dependency cứng) 🟡

Nguyên tắc mở rộng: Khi tương lai phát sinh loại metadata mới → thêm field vào khung. KHÔNG tạo bảng riêng cho metadata. Metadata gắn liền với thực thể, không tách rời.

§4. Metadata cho checkpoint và quy trình

Checkpoint là thực thể → cần metadata đầy đủ:

  • CP type: nằm trong bao nhiêu tổ hợp? trigger bao nhiêu quy trình? đang dùng ở đâu?
  • CP set: chứa bao nhiêu checkpoints? gắn với node nào? quy trình nào dùng?
  • CP instance: đang ở trạng thái nào? ai verify? bằng chứng gì?

Quy trình Tầng 4 (khách hàng) sẽ có hàng ngàn checkpoint instances → metadata PHẢI query được để trả lời: "Khách hàng X đã qua những checkpoint nào? Còn thiếu gì?"

§5. Hệ quả

Thêm 1 label mới cho 20.000 fields → phải có batch update 1 lệnh. Làm thủ công từng field → thiết kế SAI.

§6. Công cụ có sẵn

Directus meta.note (mô tả), meta.group (phân loại), translations (đa ngôn ngữ) đã có sẵn. ✅ ĐÃ KHAI THÁC: meta.note 100% filled, meta.group 86.8% filled. Tools: dot-metadata-audit + dot-metadata-fill.

CHANGELOG (inline)

Ngày Nội dung
S178 Fix 23 (2026-04-20) +§2.1 Quy cách description machine-checkable (4 tiêu chí C1-C4). +§2.2 Quy cách per entity type. +§2.3 classification=legacy. +§2.4 Ngoại lệ backfill description + provenance. +§3 thêm notes. Hội đồng 2 vòng APPROVE FINAL (Gemini 10 + GPT 9.4).
S178 Fix 28 (2026-04-22) +§2.5 Hai mức mô tả (cơ bản + chi tiết). +§2.6 Phụ lục template mô tả cơ bản (dot_config SSOT + lookup 4 tầng). Sửa §2.2 thêm viện dẫn. Description Governance Package — Council 2 vòng (Gemini 10 + GPT 9.0 + Desktop 8.5).