P3C3 — IU Natural Save Router — Design Note (rev2)

Date: 2026-05-07 Status: DESIGN rev2 — consensus GPT+Opus+User. Chờ final review. Prerequisite: P3C2 PASS (apply + edit functions must exist). Required before: Broad AI/Agent use of IU write path.

---

1. Vấn đề

AI/Agent stateless phải nhớ 4 function khác nhau. Mất phiên = quên quy trình = gọi sai.

Nguyên tắc User: nếu phải nhớ quy trình → thiết kế lại.

---

2. Giải pháp: 2 nút rõ ràng

AI chỉ cần biết 2 function:

Muốn làm gì	Gọi function nào
Lưu/sửa/tạo nội dung	fn_iu_save(address, body, actor)
Góp ý/ghi chú	fn_iu_comment(address, actor, comment)

Không cần biết thêm gì. Hệ thống tự quyết phía sau.

fn_iu_save — cửa chính cho nội dung

fn_iu_save(
  p_address    text,       -- canonical address
  p_body       text,       -- nội dung
  p_actor      text,       -- ai đang làm
  p_title      text DEFAULT NULL,
  p_reason     text DEFAULT NULL,
  p_mode       text DEFAULT 'save'  -- 'save' | 'draft'
) RETURNS jsonb

fn_iu_comment — đã có sẵn từ P3C1

fn_iu_comment(address, author, body, ...)  -- free-flow, no approval

---

3. fn_iu_save behavior tự động

mode = 'save' (default):
  ├─ address chưa tồn tại → fn_iu_create → version 1 official → DONE
  │   (lần đầu tạo mới = auto-approve)
  │
  └─ address đã tồn tại → fn_iu_create_edit_draft → draft
       ├─ policy = auto_apply → fn_iu_apply_edit_draft → DONE
       ├─ policy = require_review → return draft_created_review_required
       └─ no_change → return no_change

mode = 'draft':
  ├─ address tồn tại → fn_iu_create_edit_draft → return draft (never auto-apply)
  └─ address không tồn tại → fn_iu_create → version 1 (same as save)

---

4. Chính sách phê duyệt (approval policy)

3 tầng quyết định (ưu tiên từ trên xuống):

1. Per-IU policy — information_unit.identity_profile->>'edit_policy'
2. Per-actor policy (nếu cần mở rộng sau)
3. System default — dot_config key='iu_edit.policy.default_mode'

Nguyên tắc đã chốt:

• Lần đầu tạo mới → auto-approve (không có gì để so sánh)
• Lần 2+ sửa nội dung → default require_review
• Việc nhỏ/low-risk → auto_apply (per-IU hoặc per-actor)
• Việc lớn → kiểm tra chéo (1 sửa, 1 duyệt)
• Comment = free-flow, không cần approval, comment nhiều lần thoải mái

Ai duyệt khi require_review?

Reviewer gọi trực tiếp:

SELECT fn_iu_apply_edit_draft(draft_id, 'reviewer:gpt', 'approved');

P3D notification outbox sẽ thông báo reviewer khi có draft chờ.

---

5. fn_iu_save bọc lại — không thay thế

fn_iu_save (AI front-door — nội dung)
  ├── fn_iu_create (tạo mới — đã có)
  ├── fn_iu_create_edit_draft (tạo nháp — P3C1)
  └── fn_iu_apply_edit_draft (phê duyệt — P3C2, chỉ khi auto_apply)

fn_iu_comment (AI front-door — góp ý — P3C1, đã có, không đổi)

fn_iu_edit (P3C2) = internal convenience wrapper, không phải AI front-door.

---

6. Tận dụng PG tối đa, code mới tối thiểu

Cơ chế	PG native hay code mới?
Policy lookup	dot_config table + identity_profile jsonb → PG query, không code mới
Auto-apply routing	Gọi existing functions → PG function call, không logic mới
Draft/stale management	Đã có trong fn_iu_apply_edit_draft (P3C2)
Comment	fn_iu_comment đã có (P3C1)
Gateway enforcement	Trigger đã có (Pack 22)
fn_iu_save	Duy nhất code mới: 1 PL/pgSQL function ~30 dòng, router logic only

fn_iu_save không tạo table mới, không trigger mới, không gateway mới. Chỉ là router gọi lại functions đã có.

---

7. Implementation plan

Step	Nội dung	Phụ thuộc
P3C2 dispatch	Tạo fn_iu_apply_edit_draft + fn_iu_edit	rev7 approved
P3C3 implement	Tạo fn_iu_save router (~30 dòng PL/pgSQL)	P3C2 PASS
Policy switch	Đổi default_mode → require_review	P3C3 PASS
P3D	Notification outbox → reviewer biết có draft chờ	P3C3 PASS

---

8. Thiết kế đơn giản — tuyên ngôn

Vĩnh viễn hay tạm? → fn_iu_save là cửa chính vĩnh viễn cho AI. Cơ hội nhầm? → 2 nút rõ (save vs comment) giảm thiểu nhầm lẫn. Code mới là giải pháp cuối cùng? → fn_iu_save chỉ ~30 dòng router, mọi thứ khác đã có sẵn trong PG.

---

P3C3 Design Note rev2 | 2026-05-07 | Consensus GPT+Opus+User | 2 nút: save + comment | Chờ final review