KB-7394

IU-0 Pack 2A — Description/Birth Contract Decision Note

5 min read Revision 1

iu-0pack-2adescriptionbirth-contractdecision-note

Date: 2026-05-04 Input: Discovery report + Opus assessment + GPT review Status: Decision note — làm cơ sở cho file 12 rev2

9 câu hỏi discovery — disposition

Q	Phát hiện	Disposition
Q1	dot-collection-register v1.1.0: --description, --governance_role, --source_kind, --migration_state, --storage_role, --update. Ghi qua Directus API. Không unregister/rollback	Dùng tool này. Forward-only + --update nếu sai
Q2	Mode=warn, min_length=30, auto-gen chỉ cho governed+empty	observed cần truyền --description rõ ràng
Q3	Convention: governed = chức năng + luật; observed = ngắn gọn + scope; auto-gen = template format	Viết theo Đ3 §A.3 Collection format
Q4	18 triggers trên collection_registry, birth auto, provenance auto, duplicate birth trigger (tech debt)	Tool INSERT → triggers tự fire. Duplicate = log TD
Q5	Không có DOT unregister/rollback	Forward-only. --update sửa sai. Raw DELETE = design riêng
Q6	40 species, không có IU species	Skip cho observed. Follow-up trước governed
Q7	storage_role: DB có 6 values, tool whitelist chỉ 4 (primary/junction/log/system)	Dùng `primary` (trong whitelist)
Q8	Writes qua Directus REST API, không raw SQL	Đ7 compliant
Q9	Mọi COL-* đều PROV-DOT. Tool không có --description-provenance	Accept PROV-DOT cho DOT-channel birth description. TD cho provenance nâng cao

#	Decision	Chốt	Lý do
1	Rollback	Forward-only + --update	Không có tool. Raw DELETE = cần legal design riêng
2	Species	Skip	observed không yêu cầu species mapping (convention S128)
3	storage_role	primary cho cả 2	unit_version = version domain data, không phải operational log. Trong tool whitelist
4	Provenance	PROV-DOT	Pack 2A = DOT-channel birth/basic description, không phải AI-enriched. Convention hiện tại
5	Duplicate birth triggers	Log TD	Pre-existing, non-blocking
6	law_artifact role	Không dùng	IU không phải law artifact
7	Tool whitelist gaps	source_kind: dùng `native` (closest semantic cho application tables) hoặc omit. KHÔNG dùng `pg_table` (ngoài whitelist)	Preflight phải verify tool accept `native`

Tool whitelist: registry | native | derived | policy. DB thực tế có thêm pg_table, pg_only nhưng tool reject.

Giá trị whitelist	Semantic	IU match?
registry	Metadata/config tables (collection_registry, entity_species...)	Không — IU là data table
native	Native application tables	Có — IU là application data table native
derived	Computed/view tables	Không
policy	Governance/rule tables	Không

→ native là giá trị phù hợp nhất. Preflight phải verify tool accept trước khi write.

observed là trạng thái pilot/readiness hợp pháp, không phải cách né luật:

IU đang ở pilot — 0 production rows, Pack 1 mới xong
IU tables không có physical description column — dùng identity_profile JSONB thay
HC-SCHEMA (Đ36 GP8.1) sẽ flag CRITICAL nếu governed + thiếu cột description
fn_description_birth_guard auto-gen chỉ cho governed — observed bypass auto-gen nhưng vẫn warn

Điều kiện nâng governed (follow-up):

Chốt IU description strategy: thêm cột description? hay amend HC-SCHEMA hiểu profile?
Species registration cho IU
Birth trigger deploy + description guard verify
HC-SCHEMA/Đ36 alignment

Form: [Vai trò governance]. Chứa [nội dung chính]. Lớp [Não/Kho/Cổng]. Thuộc [Luật]. [FK chính].

information_unit: [observed] Chứa đơn vị thông tin có version và identity_profile. Lớp Kho. Thuộc Đ44 (IU-0 pilot). FK anchor tới unit_version.
unit_version: [observed] Chứa lịch sử version immutable cho information_unit. Lớp Kho. Thuộc Đ44 (IU-0 pilot). FK tới information_unit.

Đây là DOT-channel birth/basic description (PROV-DOT). Không phải AI-enriched description. Rich description = TD riêng.

Pack 2A chỉ đăng ký bảng, chưa tạo IU rows. Nhưng ghi nhận: