IU Creation Gateway — README

Nếu bạn thấy lỗi "IU Gateway blocked" thì đọc tài liệu này. Status: enforced as of 2026-05-06 via Pack 22-P3-P2 rev7.

---

Quy tắc

KHÔNG direct INSERT hoặc UPDATE vào public.information_unit hoặc public.unit_version.

Mọi IU mới phải đi qua canonical path:

1. Dry-run trước: SELECT public.fn_iu_create_plan(address, title, body, actor) — kiểm tra input hợp lệ, không tạo row.
2. Tạo IU: SELECT public.fn_iu_create(address, title, body, actor) — tạo IU + UV + birth + invariant verify, trả JSON kết quả.

Signature đầy đủ

public.fn_iu_create(
  p_canonical_address text,
  p_title text,
  p_body text,
  p_actor text,
  p_unit_kind text DEFAULT NULL,        -- auto-resolve từ vocab
  p_section_type text DEFAULT NULL,      -- auto-resolve từ vocab
  p_owner_ref text DEFAULT NULL,         -- default = p_actor
  p_publication_type text DEFAULT NULL,  -- optional, explicit only
  p_parent_ref uuid DEFAULT NULL         -- optional parent/container
) RETURNS jsonb

fn_iu_create_plan có cùng signature.

Kết quả trả về

• status = 'created' → thành công, IU mới đã tạo
• status = 'exists_complete' → idempotent success, IU đã tồn tại với đầy đủ invariants
• status = 'exists_missing_birth' / 'exists_missing_version' / 'exists_anchor_invalid' / 'exists_duplicate_version' / 'exists_unknown_state' → health/remediation states, KHÔNG phải success. Cần health check, không phải retry.
• status = 'plan_ok' (chỉ fn_iu_create_plan) → input hợp lệ, sẵn sàng tạo

Những điều KHÔNG được làm

• Không INSERT INTO public.information_unit trực tiếp → bị trigger guard chặn
• Không UPDATE public.information_unit trực tiếp → bị trigger guard chặn
• Không INSERT/UPDATE public.unit_version trực tiếp → bị trigger guard chặn
• Không tự SET app.canonical_writer = 'fn_iu_create' rồi INSERT — marker là speed bump chặn lỗi vô ý, không phải cơ chế cấp quyền. Tự set marker = bypass có chủ đích, sẽ bị detector phát hiện
• Không INSERT trực tiếp vào birth_registry — birth do PG trigger tự xử lý khi fn_iu_create tạo IU

Migration / Import

Nếu cần import hàng loạt hoặc migration: mở task/exemption request theo Điều 44 / Gateway Governance. Exemption phải có ticket_id, owner, expiry, và audit note. Không tự bypass gateway.

Adapter / UI

Adapter, Directus Flow, API endpoint, hoặc UI sau này phải là thin wrapper gọi fn_iu_create. Không direct INSERT/UPDATE.

Tham khảo

• Gateway design: knowledge/dev/laws/dieu44-trien-khai/design/22-p3-iu-creation-gateway-scope.md
• Policy keys: SELECT key, value FROM dot_config WHERE key LIKE 'iu_create.gateway.%'
• Deployment report: knowledge/dev/laws/dieu44-trien-khai/reports/22-p3-p2-iu-gateway-trigger-guard-report.md

---

IU Creation Gateway README | 2026-05-06 | Enforced via Pack 22-P3-P2 rev7