§5 CẤU TRÚC DOT MỚI — 5 NHÓM + CATALOG CHO AI

Part of: PG Reform Tools — S176 mission Prev: 07-phuong-an-a-plus.md ← | → Next: 09-khai-sinh-collection.md

---

§5.1 Phân nhóm DOT — 5 nhóm tự nhiên

Nhóm	Vai trò	DB target	Lớp	Domain	Ví dụ
1. Schema	DDL	directus + incomex_metadata	KHO	infrastructure.schema	dot-pg-*-ensure
2. Data	DML	directus	KHO	collection, lifecycle, workflow, kg.*, normative	dot-task-*, dot-nrm-*
3. Audit/Health	Tier A kiểm tra	mọi DB	KHO + NÃO	monitoring.integrity, audit	dot-collection-health
4. Lifecycle	State transition	directus (qua function)	KHO	lifecycle	dot-entity-retire
5. Infra	Cron, deploy, backup	mọi DB + FS	KHO + CỔNG	infrastructure.*	dot-cron-pivot-setup

Quy tắc bắt buộc cho mỗi DOT (mở rộng sau KS.3):

• domain ∈ 5 nhóm
• tier (A/B)
• paired_dot (NT12)
• target_db (mới): directus/incomex_metadata/workflow/cluster
• target_layer: kho/nao/cong
• dot_type: type_1_approval/type_2_auto
• (MỚI KS.3) kind: writer/checker/installer/bootstrap/one_shot — fix asymmetry installer
• (MỚI KS.3) file_path NOT NULL constraint (trừ status='placeholder' chờ deps)

---

§5.2 Catalog DOT cho AI — Trọng tâm Huyên muốn

Vấn đề thực sự: AI/agent không biết gọi DOT nào → tự viết script mới = sinh writer bypass = bệnh quay lại. Đây là gốc bệnh, không phải password.

Lớp 1 — SSOT là dot_tools trong PG (mở rộng metadata)

Bổ sung 5 field metadata mới + 2 field KS.3:

Field	Kiểu	Mục đích
purpose	text	1 câu mô tả mục đích NGHIỆP VỤ
when_to_use	text[]	Keywords tình huống
inputs	jsonb	Schema input
outputs	jsonb	Schema output
example_call	text	Ví dụ gọi cụ thể
kind (KS.3)	text	writer/checker/installer/bootstrap/one_shot
file_path_status (KS.3)	text	linked/placeholder/deprecated — chỉ placeholder được phép file_path=NULL

Bảo vệ chống nhầm:

• PG CHECK constraint: file_path IS NOT NULL OR file_path_status='placeholder'
• PG trigger: insert thiếu 5 field → reject
• DOT mới không có cặp Cấp A → reject
• DOT trùng tên → unique constraint

Lớp 2 — dot-find (cổng tra cứu duy nhất cho AI)

Agent gọi dot-find("tôi muốn làm việc X") → query dot_tools → trả về top 3 DOT + purpose + when_to_use + example_call.

Đây là cổng DUY NHẤT agent dùng để tra DOT. Không match → "chưa có DOT, xin tạo qua approval_request".

Lớp 3 — README auto-generated

DOT cron dot-readme-export daily sinh knowledge/dev/dot/README.md. README = view phái sinh, KHÔNG là SSOT.

---

§5.3 Vòng khép kín toàn bộ

1. Agent có việc → gọi dot-find → biết DOT nào
2. Agent gọi DOT đó với password GSM → PG cho phép
3. DOT chạy → ghi vào dot_run_log (bảng mới, fix lỗ hổng K0)
4. DOT cặp Cấp A đọc dot_run_log → verify → ghi system_issues nếu lệch
5. dot-readme-export đọc dot_tools daily → cập nhật doc
6. dot-pg-credential-audit weekly → quét hardcoded password
7. (MỚI KS.1) dot-ddl-audit-monitor daily → quét ddl_audit_log
8. (MỚI KS.3) dot-file-path-orphan-check daily → cross-ref disk vs registry

---

§5.4 Bảng dot_run_log mới

CREATE TABLE IF NOT EXISTS dot_run_log (
  id bigserial PRIMARY KEY,
  dot_code text NOT NULL,
  started_at timestamptz NOT NULL DEFAULT now(),
  finished_at timestamptz,
  status text CHECK (status IN ('running','success','failed','timeout')),
  caller text, caller_id text,
  inputs jsonb, outputs jsonb, errors text[],
  duration_ms integer,
  target_db text, target_tables text[],
  pg_user text,
  CONSTRAINT fk_dot_run_log_dot FOREIGN KEY (dot_code) REFERENCES dot_tools(code)
);
CREATE INDEX idx_dot_run_log_dot ON dot_run_log(dot_code, started_at DESC);
CREATE INDEX idx_dot_run_log_status ON dot_run_log(status, started_at DESC) WHERE status != 'success';

Retention: 90 ngày.

---

§5.5 Bảng ddl_audit_log mới (MỚI KS.1)

CREATE TABLE IF NOT EXISTS ddl_audit_log (
  id bigserial PRIMARY KEY,
  event_time timestamptz NOT NULL DEFAULT now(),
  command_tag text NOT NULL,
  object_type text, object_identity text, schema_name text,
  pg_user text NOT NULL,
  application_name text, client_addr inet,
  dot_owner text,  -- trace back via application_name convention 'dot:DOT_CODE'
  sql_snippet text
);
CREATE INDEX idx_ddl_audit_log_time ON ddl_audit_log(event_time DESC);
CREATE INDEX idx_ddl_audit_log_orphan ON ddl_audit_log(event_time DESC) WHERE dot_owner IS NULL;

-- Event trigger SECURITY DEFINER
CREATE OR REPLACE FUNCTION fn_ddl_audit_capture() RETURNS event_trigger AS $$
DECLARE r record;
BEGIN
  FOR r IN SELECT * FROM pg_event_trigger_ddl_commands() LOOP
    INSERT INTO ddl_audit_log (command_tag, object_type, object_identity, schema_name, pg_user, application_name, client_addr, dot_owner)
    VALUES (r.command_tag, r.object_type, r.object_identity, r.schema_name,
            current_user, current_setting('application_name', true),
            inet_client_addr(),
            CASE WHEN current_setting('application_name', true) LIKE 'dot:%'
                 THEN substring(current_setting('application_name', true) from 5)
                 ELSE NULL END);
  END LOOP;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

CREATE EVENT TRIGGER trg_ddl_audit ON ddl_command_end EXECUTE FUNCTION fn_ddl_audit_capture();

Retention: 180 ngày (DDL events hiếm, giữ lâu hơn).

---

§5.6 Dedup 42 cặp DOT trùng tên

Chọn DOT_SEMANTIC làm canonical. Migration merge metadata → DELETE DOT-NNN. Update reference. DOT dot-naming-audit quét tuần.

---

File 08 — §5 DOT mới + catalog | Index | S176 | Living doc