IU-0 Minimal Implementation Planning Pack

Trạng thái: PLANNING — chưa triển khai, chưa mở P44-6 Phiên: S191 (2026-05-04) Prerequisite: Pilot Round 1 COMPLETE (G-Pilot-5 PASS, 2/2 writable slices, H1-H4 ✅) Ranh giới: Không DDL/code/migration (GR-2). Không mở P44-6 (GR-3). Schema sketch = NON-NORMATIVE.

---

1. Mục tiêu

Thiết kế bước tối thiểu để information_unit có hạ tầng thật trong PG — tạo, đọc, sửa, version hóa miếng thông tin. Pilot Round 1 đã chứng minh workflow hoạt động trên KB docs (77-95% token savings). Bước tiếp là có table thật để slice editing không chỉ patch KB markdown mà quản lý structured data.

Planning pack này là thiết kế logical. Triển khai thật cần User approve mở P44-6 + DDL riêng.

---

2. Logical schema plan

2.1 information_unit table (logical)

⚠️ NON-NORMATIVE EXAMPLE — physical schema chốt qua APR khi mở P44-6.

Chứa UMC 10 elements + identity profile JSONB:

Column (logical)	UMC	Type sketch	Note
id	U1	UUID PK	System auto, immutable
canonical_address	U2	TEXT UNIQUE	Immutable sau birth. Format per unit_kind.
unit_kind	U3	TEXT FK vocab	proposed_pilot: design_doc_section. Extensible.
lifecycle_status	U4	TEXT FK vocab	Default draft.
content_anchor_ref	U5	TEXT	→ unit_version.id hoặc KB path
version_anchor_ref	U6	UUID FK	→ unit_version current
owner_ref	U7	TEXT	Agent/user ID
parent_or_container_ref	U9	UUID FK nullable	→ parent unit hoặc publication
conformance_status	U10	TEXT	Default open. DOT update Tier 4.
identity_profile	—	JSONB	title, owner_lookup_ref, primary_section_type_ref + optional fields
created_at	U8	TIMESTAMPTZ	System auto, immutable
updated_at	U8	TIMESTAMPTZ	System auto
created_by	U8	TEXT	System auto
updated_by	U8	TEXT	System auto
deleted_at	—	TIMESTAMPTZ nullable	Soft-delete. NULL = active. Set khi retire/delete (HP-14).

Birth gate trigger: kiểm 15 required elements (10 UMC + 3 identity required + 2 publication required). Mode: block production, warn pilot.

2.2 unit_version table (logical)

Column (logical)	Type sketch	Note
id	UUID PK	System auto
unit_id	UUID FK	→ information_unit.id
body	TEXT	Content body
content_hash	TEXT	SHA-256, computed local (HP-4)
version_seq	INT	Monotonic per unit
lifecycle_status	TEXT FK vocab	Per-version lifecycle
content_profile	JSONB	word_count, topics, etc. (optional, DOT enrich)
created_at	TIMESTAMPTZ	Immutable
created_by	TEXT	—

Invariant: INSERT-only per version. Sửa body = INSERT version mới, không UPDATE version cũ. Version cũ giữ nguyên cho audit trail (→ xem 07b §5 Layer 2).

2.3 Profile JSONB structure (logical)

identity_profile trong information_unit:

Field	Required?	Fill
title	✅ Required	Agent
owner_lookup_ref	✅ Required	Agent
primary_section_type_ref	✅ Required	Agent
composition_role	Optional	Agent (default atomic)
aliases	Optional	Agent
summary_text	Optional	Agent
description	Optional	Agent/System

content_profile trong unit_version:

All optional, DOT enrich dần: word_count, key_entities, topics, claim_extractions, granularity_level.

publication_profile: defer — publication-level, không per-unit. Reuse tac_publication pattern hoặc tạo iu_publication table nếu cần.

2.4 Creation transaction & birth gate timing

Vấn đề: information_unit.version_anchor_ref trỏ tới unit_version.id, nhưng unit_version.unit_id trỏ ngược lại. INSERT nào trước?

Giải pháp: Tạo unit + version trong cùng 1 PG transaction, 2 bước:

1. INSERT information_unit với version_anchor_ref = NULL.
2. INSERT unit_version (có unit_id FK).
3. UPDATE information_unit.version_anchor_ref = version.id vừa tạo.
4. Birth gate trigger kiểm 15 elements sau bước 3 (deferred constraint hoặc trigger AFTER).
5. COMMIT.

Nếu birth gate FAIL → ROLLBACK toàn bộ transaction. Không có unit mồ côi.

Hệ quả: version_anchor_ref NOT NULL constraint phải là DEFERRED (kiểm lúc COMMIT, không lúc INSERT). Hoặc nullable + trigger kiểm khi transaction kết thúc.

---

3. Pilot vocab plan

Value	Domain	Current status	Implementation plan
design_doc_section	unit_kind	proposed_pilot	INSERT vào vocab table (dot_config hoặc Đ24 vocab). APR cấp medium.
section	section_type	proposed_pilot	INSERT vào existing section_type vocab.
design_doc	publication_type	proposed_pilot	INSERT vào existing publication_type vocab.

Sequencing: Vocab INSERT trước table creation. Birth gate reference vocab FK → vocab phải tồn tại trước birth.

---

4. Birth gate Tier 0 — logical design

15 elements strict. Birth gate kiểm trong creation transaction, sau khi unit + version + anchor đã đủ, trước COMMIT (xem §2.4):

#	Element	Check	Action khi fail
U1-U10	10 UMC	NOT NULL (U9 nullable OK)	Block INSERT
P-id1	title	identity_profile->>'title' NOT NULL	Block INSERT
P-id2	owner_lookup_ref	identity_profile->>'owner_lookup_ref' NOT NULL	Block INSERT
P-id3	primary_section_type_ref	identity_profile->>'primary_section_type_ref' NOT NULL + FK valid	Block INSERT
P-pub1	publication_authority_ref	Resolved via parent/publication	Pilot: WARN (publication table defer). Production: BLOCK.
P-pub2	publication_type_ref	Resolved via parent/publication	Pilot: WARN. Production: BLOCK.

Pilot mode: P-pub1/P-pub2 WARN thay vì BLOCK vì publication table chưa ready. Chuyển BLOCK khi production + publication table tồn tại.

U9 container semantics: parent_or_container_ref nullable (top-level unit hợp lệ). Birth gate đếm U9 vào 10 UMC nhưng NULL = valid cho root documents. Pilot: root units (IU-0, P38-XC) có U9 = NULL; child slices có U9 = parent unit_id.

---

5. CRUD hot path — logical flow

Kế thừa HP-1..15 + IU-HP-1..5 từ 07b §5.A. Tóm tắt flow:

Operation	Steps (PG local only)	Latency target
Create unit	INSERT information_unit (birth gate check) + INSERT unit_version (body + hash) + INSERT outbox	<10ms
Read slice	SELECT body FROM unit_version WHERE unit_id = ? ORDER BY version_seq DESC LIMIT 1	<5ms
Edit slice	INSERT unit_version mới (body + hash) + UPDATE information_unit.version_anchor_ref + INSERT outbox	<10ms
Profile update	UPDATE identity_profile JSONB (jsonb_set)	<5ms
Delete	UPDATE deleted_at + INSERT outbox (delete, 30-60s delay)	<5ms

Không trong hot path: OpenAI embedding, Qdrant upsert, remote API call. Tất cả qua outbox cold path.

---

6. Outbox logical plan

Reuse outbox design từ 07b §5.A.4-5. Logical table sketch (NON-NORMATIVE):

Column	Purpose
outbox_id	PK
source_kind	information_unit / unit_version / kb_document
source_id	FK
debounce_key	unit_version_id (IU) / document_id (legacy)
operation	upsert / delete
content_hash	Skip nếu đã embed
earliest_run_at	now() + 120s
status	pending / processing / done / dead_letter
retry_count / last_error	Worker management

Worker chưa tạo. Outbox table tồn tại nhưng worker = separate implementation step. Rows accumulate cho đến khi worker ready — không block CRUD.

Shared vs separate outbox: OPEN IU-0-λ. Khuyến nghị shared (1 table, phân biệt source_kind), pilot verify.

---

7. Điều kiện mở P44-6

#	Điều kiện	Status
1	IU-0 baseline active (07/07b/07c)	✅ Done
2	Pilot Round 1 COMPLETE (H1-H4 PASS)	✅ Done
3	Minimal Implementation Planning Pack reviewed	⬜ File này — chờ GPT/User review
4	User explicit approve "mở P44-6"	⬜ Chưa
5	DDL review process (Đ32 APR)	⬜ Chưa — cần APR khi P44-6 mở
6	Rollback plan cho DDL	⬜ Cần thiết kế khi P44-6 mở
7	Legacy vector impact = zero	✅ VG-1..9 hold, IU table tách biệt hoàn toàn

Gate: 1-2 đã done. 3-6 cần trước khi P44-6. 7 confirmed.

7.1 P44-6 Pre-open Checklist

Trước khi User approve mở P44-6, cần tick:

#	Check	☐
C1	09 planning pack reviewed GPT PASS	☐
C2	Logical schema consistent P38-XC UMC + P44-3 Profile	☐
C3	Creation transaction timing clear (§2.4)	☐
C4	Delete lifecycle field present (deleted_at)	☐
C5	U9 container pilot semantics clear	☐
C6	Publication fields pilot WARN / production BLOCK clear	☐
C7	3 implementation packs scoped + gated (§9)	☐
C8	Rollback plan per DDL step	☐
C9	Legacy vector impact = zero (VG-1..9)	☐
C10	User explicit "mở P44-6"	☐

---

8. Conflict check

Check	IU-0 07	07b	07c	P38-XC	P44-3	GR	VG
UMC 10 elements match	✅	—	—	✅	—	—	—
Profile 15 birth gate match	✅	✅	✅	✅	✅	—	—
CRUD hot path = PG only	—	✅	—	—	—	✅ GR-2	—
Vector = cold path only	—	✅	—	—	—	✅ GR-10	✅ VG-1..9
No legacy mutation	—	✅	—	—	—	✅ GR-5	✅ VG-1
Schema sketch NON-NORMATIVE	✅	—	—	—	—	✅ GR-2	—
Implementation pattern OPEN	—	—	—	✅ P38-X-12	—	—	—

Không phát hiện conflict. Schema logical trong file này nhất quán với IU-0 baseline + P38-XC SSOT. Implementation pattern vẫn OPEN (P38-X-12) — logical sketch không chốt single/per-kind/hybrid.

---

9. Implementation packs (đề xuất khi P44-6 mở)

Pack 1: Vocab + Schema + APR

Step	What
I-1	Vocab INSERT 3 values (APR cấp medium)
I-2	DDL: CREATE TABLE information_unit + unit_version (1 APR, 1 DDL review, 1 rollback plan)
I-3	Birth gate trigger (deferred constraint + AFTER trigger)
Gate	Smoke test: tạo 1 unit + 1 version + birth gate verify

Pack 2: CRUD + Version smoke

Step	What
I-4	Smoke test CRUD: create, read, edit (new version), profile update, soft-delete
I-5	Verify: hot path <10ms, version audit trail intact, delete lifecycle correct
I-6	Migrate 1 pilot doc (IU-0 07) → IU records
Gate	Round-trip verify: IU records → reconstruct original doc → diff = 0

Pack 3: Outbox + Vector prep

Step	What
I-7	DDL: CREATE TABLE iu_outbox (hoặc extend existing outbox)
I-8	Outbox worker Phase 1: IU collection config + delayed embed
Gate	Outbox smoke: create unit → outbox row → worker embed → Qdrant point verify

Mỗi pack = 1 vòng APR → DDL review → execute → smoke test → gate. Không batch nhiều packs. Pack N+1 chỉ bắt đầu sau Pack N gate PASS.

---

10. Câu hỏi GPT/User

#	Câu hỏi
Q1	Planning pack đủ quality cho GPT review?
Q2	Logical schema có consistent với P38-XC UMC + P44-3 Profile?
Q3	Implementation sequencing I-1..I-8 hợp lý?
Q4	Khi nào User sẵn sàng approve mở P44-6?

---

Minimal Implementation Planning Pack | S191 | Round 1 COMPLETE | GR-2/GR-3 vẫn active | Chờ review → P44-6 gate