Incomex AI Portal
KB-74CE

Điều 0-G: Luật Khai Sinh — Birth Registry Law v1.0

11 min read Revision 1
architecturebirth-registryS157inspectionuniversal-counterlaw

ĐIỀU 0-G: LUẬT KHAI SINH — BIRTH REGISTRY LAW v1.0

(Bổ sung Hiến pháp Kiến trúc — Giám sát phổ quát mọi thực thể)

v1.0 | 2026-03-21 | S157 | Huyên đề xuất + Claude thiết kế Nguyên tắc gốc: "99.5% thực thể chưa sinh ra. Hạ tầng phải sẵn sàng đếm được MỌI THỨ SẼ SINH RA, không phải đếm đúng những thứ đã có." — Huyên Nguyên tắc thiết kế: Hệ thống thiết kế để CHẠY. Khi đã chạy, KHÔNG SỬA CODE. Thay đổi = thay đổi metadata, không phải code.

I. BỐI CẢNH

Vấn đề:

  • 2 tuần không đếm được bao nhiêu nguyên tử — vì bộ đếm hướng đối tượng (UNION ALL hardcode)
  • Thêm entity type mới → phải sửa VIEW, sửa function → không scale
  • Inspection/giám sát nằm rải rác, không tập trung → lọt entity không kiểm tra
  • Orphan detection phải quét từng collection riêng lẻ → phức tạp, chậm

Giải pháp: Birth Registry Collection

"Mọi thứ sinh ra trong PG đều có giấy khai sinh. Giám sát tập trung vào danh sách mới sinh. Qua kiểm tra → dán sticker certified." — Huyên

Một collection duy nhất (birth_registry) lưu giấy khai sinh cho MỌI entity sinh ra trong hệ thống. Giải quyết cùng lúc: đếm phổ quát + orphan detection + inspection pipeline.

II. THIẾT KẾ

2.1 Schema: birth_registry

CREATE TABLE birth_registry (
  id              bigserial PRIMARY KEY,
  
  -- KHAI SINH CƠ BẢN (PG trigger tự ghi)
  entity_code     text NOT NULL,              -- PREFIX-NNN
  collection_name text NOT NULL,              -- collection gốc
  species_code    text,                       -- auto từ species_collection_map (nullable: chưa map = audit)
  composition_level text,                     -- 6+1: atom/molecule/compound/material/product/building/meta
  dot_origin      text,                       -- DOT tool nào tạo
  born_at         timestamptz DEFAULT now(),  -- thời điểm sinh
  
  -- PHÂN LOẠI TỰ ĐỘNG
  governance_role text,                       -- governed/observed/excluded (auto từ collection_registry)
  
  -- THANH TRA (thêm cột = thêm inspector, KHÔNG SỬA CODE)
  inspect_pen     timestamptz,   -- Inspector 1: khai sinh đủ? (code, origin, species)
  inspect_stamp   timestamptz,   -- Inspector 2: metadata đủ? (name, description)
  inspect_gate    timestamptz,   -- Inspector 3: hợp lệ? (đúng chuồng, business rules)
  -- Tương lai: thêm inspect_security, inspect_compliance... = thêm cột, DOT cũ vẫn chạy
  
  -- KẾT QUẢ
  certified       boolean DEFAULT false,      -- TẤT CẢ inspector pass → true
  certified_at    timestamptz,
  
  -- INDEX
  CONSTRAINT uq_birth_entity UNIQUE (entity_code)
);

-- Partial index: chỉ query uncertified (danh sách cần kiểm tra)
CREATE INDEX idx_birth_uncertified ON birth_registry (born_at DESC) WHERE certified = false;
-- Index đếm per species
CREATE INDEX idx_birth_species ON birth_registry (species_code) WHERE governance_role = 'governed';
-- Index per collection
CREATE INDEX idx_birth_collection ON birth_registry (collection_name);

2.2 Cơ chế tự động (PG Trigger)

-- Trigger function: MỌI INSERT vào governed collection → auto INSERT birth_registry
CREATE OR REPLACE FUNCTION fn_birth_registry_auto()
RETURNS trigger AS $$
DECLARE
  v_entity_code text;
  v_species text;
  v_comp_level text;
  v_governance text;
  v_dot_origin text;
BEGIN
  -- Lấy code từ NEW record
  v_entity_code := NEW.code;
  IF v_entity_code IS NULL THEN RETURN NEW; END IF;
  
  -- Auto lookup species từ mapping
  SELECT scm.species_code, es.composition_level
  INTO v_species, v_comp_level
  FROM species_collection_map scm
  JOIN entity_species es ON scm.species_code = es.species_code
  WHERE scm.collection_name = TG_TABLE_NAME
    AND scm.is_primary = true
  LIMIT 1;
  
  -- Auto lookup governance từ collection_registry
  SELECT governance_role INTO v_governance
  FROM collection_registry
  WHERE collection_name = TG_TABLE_NAME;
  
  -- Lấy _dot_origin nếu có
  v_dot_origin := CASE 
    WHEN TG_TABLE_NAME IN (SELECT table_name FROM information_schema.columns 
                           WHERE column_name = '_dot_origin' AND table_schema = 'public')
    THEN (to_jsonb(NEW)->>'_dot_origin')
    ELSE NULL
  END;
  
  -- INSERT vào birth_registry
  INSERT INTO birth_registry (entity_code, collection_name, species_code, 
                              composition_level, dot_origin, governance_role)
  VALUES (v_entity_code, TG_TABLE_NAME, v_species, 
          v_comp_level, v_dot_origin, v_governance)
  ON CONFLICT (entity_code) DO NOTHING;
  
  RETURN NEW;
END; $$ LANGUAGE plpgsql;

Trigger DDL: Mỗi governed collection cần trigger riêng (giống pattern Điều 24 label triggers). DOT tool dot-birth-trigger-setup sẽ tự generate DDL đúng per collection dựa trên collection_registry.

2.3 Bộ đếm phổ quát

-- Đếm per species — 1 câu SQL, KHÔNG BAO GIỜ SỬA
SELECT species_code, COUNT(*) as total
FROM birth_registry
WHERE governance_role = 'governed'
GROUP BY species_code;

-- Đếm per composition_level
SELECT composition_level, COUNT(*) as total
FROM birth_registry
WHERE governance_role = 'governed'
GROUP BY composition_level;

-- Đếm uncertified (danh sách cần giám sát)
SELECT collection_name, COUNT(*) as uncertified
FROM birth_registry
WHERE certified = false AND governance_role = 'governed'
GROUP BY collection_name;

Thêm species mới, collection mới, entity type mới → KHÔNG SỬA QUERY. Query đọc metadata.

2.4 Inspection Pipeline

Entity mới INSERT → PG trigger → birth_registry record (certified = false)
    │
    ▼
[DOT Inspector PEN] — chạy theo schedule hoặc event
    Query: WHERE inspect_pen IS NULL AND governance_role = 'governed'
    Kiểm tra: entity_code NOT NULL? _dot_origin NOT NULL? species_code NOT NULL?
    Pass → UPDATE inspect_pen = now()
    Fail → INSERT audit queue
    │
    ▼
[DOT Inspector STAMP] — chạy độc lập
    Query: WHERE inspect_stamp IS NULL AND inspect_pen IS NOT NULL
    Kiểm tra: name NOT NULL? description NOT NULL? status NOT NULL?
    Pass → UPDATE inspect_stamp = now()
    Fail → INSERT audit queue
    │
    ▼
[DOT Inspector GATE] — chạy độc lập
    Query: WHERE inspect_gate IS NULL AND inspect_stamp IS NOT NULL
    Kiểm tra: đúng chuồng (species mapping)? business rules pass?
    Pass → UPDATE inspect_gate = now()
    Fail → INSERT audit queue
    │
    ▼
[Auto Certify] — trigger AFTER UPDATE on birth_registry
    Khi TẤT CẢ inspect_* IS NOT NULL → certified = true, certified_at = now()

Thêm inspector mới:

  1. ALTER TABLE birth_registry ADD COLUMN inspect_xxx timestamptz;
  2. Tạo DOT tool dot-inspect-xxx
  3. DOT cũ vẫn chạy bình thường — mỗi DOT chỉ UPDATE cột của mình
  4. Auto-certify trigger cần update: tất cả inspect_* NOT NULL. Hoặc tốt hơn: đọc từ metadata danh sách inspectors bắt buộc → so sánh.

2.5 Orphan Detection

-- Entity trong governed collection nhưng KHÔNG có birth record = orphan
SELECT gc.code, gc.collection_name
FROM v_all_governed_entities gc
LEFT JOIN birth_registry br ON gc.code = br.entity_code
WHERE br.id IS NULL;

-- Birth record nhưng collection gốc đã xóa entity = phantom
SELECT br.entity_code, br.collection_name
FROM birth_registry br
LEFT JOIN v_all_governed_entities gc ON br.entity_code = gc.code
WHERE gc.code IS NULL AND br.governance_role = 'governed';

2.6 Cleanup định kỳ

-- Xóa birth records cho excluded collections (không cần giám sát)
DELETE FROM birth_registry 
WHERE governance_role = 'excluded' 
  AND certified = true 
  AND born_at < now() - interval '30 days';

-- Hoặc: không insert excluded ngay từ trigger (governance_role check)

Lựa chọn tốt hơn: Trigger chỉ INSERT cho governed + observed. Excluded = không tạo birth record. Giữ birth_registry gọn nhất.

III. PERFORMANCE ANALYSIS

Metric Giá trị Ghi chú
Row size ~200-300 bytes Chỉ text metadata + timestamps
1 triệu records ~300 MB Nhẹ
100 triệu records ~30 GB PG xử lý tốt
Query uncertified < 10ms Partial index trên certified = false
Query đếm per species < 50ms Index trên species_code
Trigger overhead per INSERT < 1ms 1 INSERT thêm, transactional

Khi nào scale: > 100 triệu → partition theo năm. > 1 tỷ → archive + materialized views. Nhưng hệ thống Incomex hiện tại xa mức này.

IV. 4 YẾU TỐ KHẢ THI (CHECKLIST)

# Yếu tố Trạng thái
1 Mô hình tổng thể: Birth Registry = kho hồ sơ khai sinh quốc gia, 1 collection quản lý mọi entity ✅ Rõ ràng
2 Quy trình khép kín: INSERT → birth record → inspect 1,2,3 → certified → done ✅ Khép kín
3 Công cụ đầy đủ: PG trigger (auto birth), DOT inspectors (kiểm tra), DOT birth-trigger-setup (deploy) ⚠️ Cần tạo
4 Môi trường thực thi: birth_registry collection = nơi inspectors làm việc ✅ Rõ ràng

V. QUAN HỆ VỚI LUẬT HIỆN CÓ

Luật Thay đổi
Điều 0 +Mọi entity sinh ra PHẢI có birth record
Điều 0-B Giữ nguyên. composition_level ghi vào birth record.
Luật Loài species_code auto lookup khi birth. Không tìm được = audit queue.
Điều 26 (Counting) ĐƠN GIẢN HÓA: Đếm = COUNT trên birth_registry. Không cần UNION ALL, dynamic function.
entity_audit_queue Inspector fail → tạo audit issue. Giữ nguyên vai trò.

VI. DOT TOOLS CẦN TẠO

DOT Chức năng Priority
dot-birth-trigger-setup Generate + deploy trigger per governed collection 🔴 Phase A
dot-inspect-pen Kiểm tra khai sinh: code, origin, species 🔴 Phase A
dot-inspect-stamp Kiểm tra metadata: name, description, status 🟡 Phase B
dot-inspect-gate Kiểm tra hợp lệ: đúng chuồng, business rules 🟡 Phase B
dot-certify-scan Quét + auto certify records đủ điều kiện 🟡 Phase B
dot-birth-orphan-scan Cross-check birth vs collection gốc 🟡 Phase C

Điều 0-G v1.0 | S157 | Huyên đề xuất Birth Registry + Claude thiết kế "Mọi thứ sinh ra đều có giấy khai sinh. Giám sát danh sách mới. Certified = yên tâm."