dot-iu-cutter v0.5 WS-2 — Metadata Key Registry Design (D1)

Phase: design-only (WS-2) · 2026-05-18 · Authority: WS-1 promoted (GPT cleanup PASS) + v0.5 Label/Metadata concept + v0.4 Hybrid. Self-contained.

Concrete hóa metadata_key_registry từ v0.5 Label/Metadata concept — KHÔNG redesign concept. Pseudo-schema/YAML only, KHÔNG executable SQL, KHÔNG tạo bảng/migration (QG2/QG4). Đây là lớp chống hardcode metadata key.

---

0. Mục tiêu & nền tham chiếu (không redesign)

• v0.5 Label/Metadata (...v0.5-constitution-hardtest-design/dot-iu-cutter-v0.5-information-unit-label-metadata-registry-master-design-2026-05-17.md) §2: concept label_dictionary, label_assignment (append-only), metadata_key_registry, metadata_value, hot_key_promotion_ledger; §5 promotion flow cold→observe→propose→sovereign_gate→execute_later; §8 OD-L1..L5. Reference, concrete hóa, không viết lại concept.
• v0.4 Hybrid §1 (SQL cutter_governance = SSOT; JSONB không là hidden authority) + §4 (normalize queue, idempotency_key graduate đầu). Tuân thủ.

---

1. metadata_key_registry — concrete pseudo-schema (logical, YAML field list)

metadata_key_registry:           # concrete hóa v0.5 §2 concept — chưa tạo bảng
  metadata_key: text PK          # canonical, snake_case, immutable identity
  key_namespace: text            # resolve qua registry (vd lineage|authority|structure|quality) — KHÔNG literal trong runtime
  key_type: text                 # text|int|bool|ts|enum_ref|json (v0.5 value_type)
  allowed_values_policy: text    # free | enum_ref:<label_namespace> | range:<min,max> | regex_ref:<id>
  cardinality_policy: text       # single | multi  (per IU)
  mutability_policy: text        # immutable | append_only | mutable_gated
  index_policy: text             # none | promoted_sql | promoted_index | gin   (v0.5 §2)
  hot_threshold_hint: text       # guidance cho promotion — KHÔNG inline constant
  lifecycle: text                # proposed | active | deprecated
  owner_role: text               # role/đơn vị governance key này
  created_by: text
  created_at: timestamptz

Quan hệ lưu giá trị (tham chiếu v0.5 §2, không redesign):

• metadata_value cho key cold/sparse: JSONB-on-IU (vd tac_unit_version.content_profile), KHÔNG queried hot.
• Key hot đã promote: cột SQL/index riêng theo index_policy + hot_key_promotion_ledger (append-only, sovereign-gated). JSONB chỉ giữ làm cold mirror hoặc drop theo policy → JSONB không bao giờ là hidden authority (v0.4 P7).

---

2. Hot-key promotion rule (concrete governance)

Flow giữ nguyên v0.5 §5 (reference): cold → observe → propose → sovereign_gate → execute_later. Concrete hóa ai làm gì (không có code, chỉ logical):

Bước	Ai	Hành động (design)
cold	mặc định	key mới sống trong JSONB metadata_value, không migration
observe	telemetry (read-only, design)	đo query-frequency + latency của key
propose	DOT/agent	khi vượt hot_threshold_hint → emit hot_key_promotion_ledger row state=proposed (KHÔNG auto-DDL)
sovereign_gate	GPT/User	duyệt promotion
execute_later	cycle DDL riêng có sovereign gate	promote sang cột/index; ledger.promoted_at set khi xong

Promotion forward-only + audited, không silent schema drift (v0.4 §6 invariant).

---

3. Governance tạo metadata key mới (chống hardcode)

• Key mới = thêm row lifecycle=proposed + gán owner_role; sovereign approve → active. Runtime resolve key qua registry, không literal (v0.5 §6 binding; v0.4 P3).
• key_namespace, allowed_values_policy, cardinality_policy, mutability_policy, index_policy đều là cột registry, không phải nhánh code.

---

4. Resolve OD-L1..L5 (QG8)

OD	Câu hỏi	Recommendation (design-only)	Trạng thái
OD-L1	label_assignment bảng riêng vs tái dùng append-only ledger pattern	Tái dùng append-only ledger pattern trong cutter_governance (nhất quán v0.4 P2 append-only; mutation = row mới, retract = state mới). label_assignment/metadata_value là projection của ledger pattern.	resolve (logical)
OD-L2	metadata_value JSONB-on-IU vs EAV rows	Both, per key — quyết bởi index_policy: cold/sparse → JSONB-on-IU; promoted → cột/index SQL. Không chọn cứng 1 kiểu.	resolve (logical)
OD-L3	Cardinality enforce app-level vs partial unique index	App-level write-time check (registry-driven) NGAY; partial unique index defer sang promotion/DDL cycle (cùng đường hot-key).	resolve (logical) + physical defer
OD-L4	Hot-key threshold policy + telemetry source	Registry hot_threshold_hint + read-only telemetry (query-freq/latency observation, design) + sovereign gate. Threshold số defer benchmark.	resolve (policy) + số defer post-pilot
OD-L5	Ownership schema (cutter_governance vs new) + role grants	cutter_governance (nhất quán 12 cg tables hiện có, v0.4 SSOT); grants theo pattern cutter_ro (read) / cutter_exec,cutter_verify (write). Final ratify ở schema-design cycle.	recommend + physical defer

Physical table creation cho tất cả: defer cycle schema-design riêng có sovereign gate (v0.5 Q5; forbidden §5). Không mở migration phase này.

---

5. Ví dụ nôm na (QG3)

Sổ quy tắc nhãn kho hàng: mỗi loại nhãn ("hạn sử dụng", "nhiệt độ bảo quản", "lô hàng") phải đăng ký trong sổ quy tắc (metadata_key_registry): kiểu giá trị (ngày/số/chữ), được dán mấy cái một thùng (cardinality), có sửa được không (mutability). Nhân viên KHÔNG tự bịa nhãn mới viết tay lên thùng — phải xin thêm dòng vào sổ và được duyệt. Nhãn nào dùng tra cứu liên tục ("hạn sử dụng") → khắc hẳn lên mép kệ cho tra nhanh (promote sang cột SQL), thay vì lục từng thùng (JSONB). Quyết định khắc lên kệ phải được quản lý kho duyệt (sovereign gate), không tự ý đục kệ.

---

6. Statements

• Concrete hóa, KHÔNG redesign v0.5 concept (QG1). Reference path+section cụ thể.
• OD-L1..L5 đã address (resolve logical / physical defer có justify).
• Không tạo bảng/migration/code/dry-run/Directus/vector/edge/APR/commit (QG2). Pseudo-schema YAML, không executable SQL (QG4).
• No repo/VPS access in this session. code_changed: false; commit_made: false.
• Self-advance PROHIBITED — file này nằm trong gói 4 file WS-2; STOP sau upload đủ 4 → GPT/User review.