dot-iu-cutter v0.5 WS-2 — Entity Reference Registry + Canonical Address Namespacing (D5 / D6)

Phase: design-only (WS-2) · 2026-05-18 · Self-contained.

Concrete hóa, KHÔNG redesign. Reference: WS-1 brief G2 + WS-1 binding-authority-clarification-note (...v0.5-fabric-addendum-scope/dot-iu-cutter-v0.5-WS1-binding-authority-clarification-note-2026-05-18.md); v0.5 canonicalization/address-grammar design §4 (...canonicalization-and-address-grammar-design-2026-05-17.md); v0.5 source-document ingestion §2. Pseudo-schema YAML only, no executable SQL/table/migration (QG2/QG4).

---

D5 — entity_reference_registry (concrete core-minimal)

Nền (không redesign)

WS-1 G2 + binding-authority-clarification-note: Option D hybrid — iu_entity_binding cho IU↔raw_entity; universal_edges cho registered_object↔registered_object (P44-4A nguyên vẹn). entity_reference_registry = core 5 field + 2 deferred. GPT ruling OD-FA5 = APPROVE_CORE_MINIMAL.

Concrete pseudo-schema (logical)

entity_reference_registry:         # chưa tạo bảng — core minimal
  entity_ref_id: text PK           # identity
  entity_kind: text                # FK -> entity_kind_registry (KHÔNG enum hardcode)
  source_system: text              # hệ nguồn (PG schema / GitHub repo / Directus instance)
  natural_key: text                # khoá tự nhiên bên nguồn (vd customer_id, contract_id, file path)
  authority_note: text             # vì sao nguồn này là authority
  # --- DEFERRED (mở khi có pilot contract/entity thật — GPT OD-FA5) ---
  permission_policy_ref: text NULL # DEFERRED
  snapshot_policy_ref: text NULL   # DEFERRED (cho rendered document/contract)
  lifecycle: text                  # proposed | active | deprecated
  registered_by / registered_at

entity_kind_registry:              # để entity_kind KHÔNG hardcode
  entity_kind: text PK
  display: text
  description: text
  default_source_system_hint: text
  lifecycle: text

Seed strategy entity_kind (ban đầu)

sql_entity, code_module, git_file, directus_item, report_path. Mỗi cái là 1 row entity_kind_registry lifecycle=active.

Governance

• Đăng ký entity_kind mới = thêm row entity_kind_registry lifecycle=proposed → sovereign approve → active. Runtime resolve qua registry, KHÔNG literal (v0.4 P3).
• iu_entity_binding (WS-1 binding note — reference, không redesign) trỏ entity_ref_id; binding append-only + provenance who/when/why/source; SQL/entity vẫn là authority, IU không copy data (đọc live từ SSOT lúc assembly).
• permission_policy_ref / snapshot_policy_ref: vẫn DEFERRED. Khi nào mở: chỉ khi có pilot contract/entity thật cần render snapshot hoặc phân quyền per-binding (GPT defer render/snapshot lifecycle; OD-FA5). Không over-design phase này (QG: không over-design).

Ví dụ nôm na (QG3)

Thẻ kho trỏ ngăn kệ: phiếu ghi chú "hợp đồng này khách thích giao buổi sáng" KHÔNG chép cả hợp đồng vào phiếu — chỉ ghi mã ngăn kệ (entity_kind=sql_entity, natural_key=contract_id=...) trỏ tới hồ sơ gốc trong sổ cái. Sổ đăng ký các loại mã ngăn (entity_kind_registry) để ai cũng hiểu "mã ngăn" là gì; thêm loại mã mới phải xin duyệt, không tự bịa.

---

D6 — canonical_address namespacing (giải quyết OD-A1)

Nền (không redesign)

Canon §4 (reference): goal: globally unique, deterministic, human-legible, stable across re-ingest; shape (proposal, OD-A1): "<DOCPREFIX>-<L1>-...-<Lk>"; docprefix derived from source_document_ref, NOT a literal; address không bao giờ encode volatile state; re-ingest same content_checksum => identical addresses; iu_id = sha-derived(document_version_id, canonical_address) (canon §5). Canon doc tự flag mâu thuẫn separator: shape ghi hyphen <DOCPREFIX>-<L1> nhưng ví dụ dùng slash ICX-CONST/NT-12.

Recommendation giải OD-A1 (logical, không tạo gì)

1. docprefix = mã ngắn deterministic, lưu trong source_document registry (field address_docprefix, derive từ source_document_ref), KHÔNG literal trong code (nhất quán canon §4 + ingestion §2 anti-hardcode).
2. Separator chuẩn hoá (giải mâu thuẫn canon §4): <DOCPREFIX>/<L1>-<L2>-...-<Lk> — slash ngăn docprefix với path, hyphen giữa các level. Lý do: khớp ví dụ canon (ICX-CONST/NT-12) và giữ style path hiện có (D38-DIEU28-S3-P1).
3. Collision prevention: address_docprefix UNIQUE trong source_document registry (1 document → 1 prefix); full path unique trong 1 document. docprefix chảy vào iu_id (canon §5) → IU khác document không thể đụng nhau.
4. Address giữ ordinal theo source numbering (roman→arabic ghi nhận nhưng address giữ dạng nguồn cho dễ đọc — canon §4), KHÔNG encode ✅/📋 (status là metadata).

Ví dụ collision (QG3 / đề bài D6)

Document	source_document_ref	docprefix	"Điều 5" → canonical_address
Hiến pháp Kiến trúc nội bộ	incomex-constitution	ICX-CONST	ICX-CONST/DIEU-5
Luật Doanh nghiệp 2020	vn-ldn-2020	VN-LDN2020	VN-LDN2020/CHUONG-I-DIEU-5
Corpus cũ DIEU_28 (legacy)	—	(giữ nguyên)	D38-DIEU28-S3-P1 (không đổi)

→ Hai "Điều 5" khác document KHÔNG đụng nhau nhờ docprefix. Corpus cũ giữ nguyên (canon §4: docprefix đảm bảo không collide với D38-DIEU28...).

Ví dụ nôm na

Địa chỉ nhà: hai nhà cùng "số 5" ở hai phường khác nhau sẽ nhầm nếu chỉ ghi "số 5". Thêm tên phường phía trước ("Phường A / số 5" vs "Phường B / số 5") là hết nhầm. docprefix chính là "tên phường" của địa chỉ miếng thông tin.

OD-A1 trạng thái

• Resolve (recommendation): scheme <DOCPREFIX>/<L1>-...-<Lk>, docprefix trong source_document registry, UNIQUE-enforced.
• Còn cần GPT/User chốt: xác nhận separator slash-vs-hyphen (canon doc tự mâu thuẫn) — flag, KHÔNG tự quyết cuối cùng ngoài recommendation. Liên quan OD-G3 (status marker in address vs metadata) → giữ nguyên "không encode status" (defer chi tiết canon OD-G3).

---

Statements

• Concrete hóa WS-1 G2 + canon §4, KHÔNG redesign (QG1). OD-A1 addressed (resolve + flag 1 điểm cho GPT). OD-L*/OD-A1 đã cover trong gói WS-2 (QG8).
• Pseudo-schema YAML, no executable SQL/table/migration/code/dry-run/Directus/vector/edge/APR/commit (QG2/QG4).
• No repo/VPS access in this session. code_changed: false; commit_made: false.
• Self-advance PROHIBITED — STOP sau khi đủ 4 file WS-2 → GPT/User review.