QUY ĐỊNH GHI BALO FUNCTION CHO AGENT DISCOVERY

Trạng thái: CANONICAL v1.1 — áp dụng cho loai_census = function Ngày ban hành: 2026-07-23 Phạm vi: Balo Function trong PG Census Mục tiêu: giúp AI/Agent hiểu nhanh hệ thống đang có function gì, function nào có thể gọi, dùng khi nào và cần kiểm soát ra sao. Nguyên tắc ưu tiên: nếu tài liệu khác mâu thuẫn về cách ghi Balo Function, tài liệu này được ưu tiên cho đến khi có phiên bản mới thay thế rõ ràng.

1. Mục tiêu duy nhất

Balo Function là lớp chú giải đặt trên PG Census để AI/Agent tra cứu nhanh, không phải tài liệu mô tả PostgreSQL đầy đủ và không thay thế pg_catalog.

Một Agent khi đọc một dòng Balo Function phải trả lời nhanh được 6 câu hỏi:

Function này thuộc miền công việc nào?
Nó là DOT có thể gọi, trigger, helper hay hàm extension?
Nếu là DOT, đây là DOT đọc hay DOT ghi?
Agent có được gọi trực tiếp không hay phải qua gate/approval?
Function nhận đầu vào gì và tác động chính là gì?
Mức độ tin cậy của mô tả đến từ nguồn nào?

Nếu một trường chưa có đủ bằng chứng thì phải ghi rõ “chưa xác minh”, không được bịa.

2. Nguồn sự thật và thứ tự bằng chứng

Khi ghi hoặc cập nhật Balo Function, áp dụng thứ tự sau:

PG Census/live pg_catalog — xác nhận function có tồn tại, schema, tên và chữ ký.
trigger_registry — xác nhận function đang được trigger sử dụng và mô tả trigger.
Registry/tài liệu DOT đã ban hành — xác nhận vai trò DOT, gate, paired DOT hoặc mục đích nghiệp vụ.
Thân hàm/DDL — xác nhận kiểu trả về, bảng đọc/ghi, side effect và điều kiện lỗi.
Tên + chữ ký function — chỉ dùng để phân loại sơ bộ khi chưa có nguồn mạnh hơn.

Không được biến suy luận từ tên thành sự thật tuyệt đối. Ghi chú phải nêu nguồn bằng chứng.

3. Hợp đồng cho từng cột

3.1 `nhom` — miền công việc cấp cao

Chỉ dùng một trong các giá trị chuẩn sau:

Đơn vị thông tin (IU)
Quản trị & tuân thủ
Workflow & điều phối
Sự kiện & điều phối
Khai sinh & vòng đời
Phê duyệt & an toàn
Registry & metadata
Nhãn & phân loại
Kiểm tra & giám sát
Đo lường & kiểm soát
Pivot & báo cáo
Nội dung & tri thức
Bảo mật & mật mã
Hệ thống PostgreSQL
Sandbox & kiểm thử
Tiện ích hệ thống

Không tự tạo biến thể chính tả hoặc tên gần giống. Nếu cần nhóm mới, phải sửa tài liệu này trước rồi mới sử dụng.

3.2 `loai` — vai trò thực thi

Chỉ dùng 5 giá trị:

DOT giám sát (đọc) — điểm gọi dành cho Agent để đọc, kiểm tra, audit, validate, healthcheck, plan hoặc preview.
DOT hành động (ghi) — điểm gọi dành cho Agent có khả năng tạo, sửa, chuyển trạng thái, đồng bộ, phát sự kiện hoặc thay đổi dữ liệu.
Trigger nội bộ — function được trigger gọi tự động; Agent không gọi trực tiếp.
Hàm tiện ích — helper dùng bên trong function/luồng khác; không phải điểm gọi nghiệp vụ chính.
Hàm extension — function do PostgreSQL extension cung cấp; không phải DOT nghiệp vụ.

Quy tắc an toàn: nếu chưa đủ bằng chứng để kết luận function là DOT, phân loại bảo thủ thành Hàm tiện ích, không nâng thành DOT.

3.3 `chuyen_mon` — nhãn máy đọc

Dùng slug chữ thường theo dạng domain.subdomain, ổn định và không dấu. Ví dụ:

iu.staging, iu.cut, iu.collection, iu.event, iu.core
approval, birth_registry, workflow, process, queue, event_runtime
registry, classification, audit_monitoring, measurement, pivot
governance, normative, qt001, pa, rp, tac
content_metadata, security.crypto
postgres.extension.btree_gist, postgres.extension.pgcrypto, postgres.extension.fdw
sandbox, utility, code_generation

Đây là trường ưu tiên để Agent lọc máy móc; không viết câu văn vào trường này.

3.4 `lop` — giữ nguyên theo vocabulary nền hiện hữu

Bản v1.1 không ghi giá trị mới vào lop vì cột đang có CHECK constraint của thiết kế nền và vocabulary chưa được xác minh trong phạm vi quy định Function.

Khả năng gọi của Agent được biểu diễn bằng:

loai
kiem_soat
thẻ [GỌI] trong ghi_chu

Không sửa constraint, không thêm vocabulary lop chỉ để phục vụ Balo Function. Khi vocabulary nền được xác minh, phải sửa tài liệu này trước khi backfill.

3.5 `active` và `da_mat` — tình trạng tồn tại

Bản v1.1 không tự ghi active vì vocabulary/constraint hiện hữu chưa được xác minh. Tình trạng tồn tại trước mắt đọc từ PG Census và da_mat:

da_mat = false — đang có trong live Census tại lần reconcile gần nhất.
da_mat = true — đã mất khỏi live PG nhưng Balo giữ để truy vết.

Không dùng tình trạng tồn tại để suy ra quyền gọi. Quyền gọi nằm ở loai, kiem_soat và thẻ [GỌI].

3.6 `kiem_soat` — yêu cầu kiểm soát trước khi Agent gọi

true — DOT ghi hoặc function có thể thay đổi dữ liệu/quyền/trạng thái; Agent phải kiểm tra gate, approval, quyền và chế độ dry-run trước khi gọi.
false — DOT đọc hoặc function không phải entry point cho Agent.

kiem_soat = false không có nghĩa function nội bộ được phép gọi trực tiếp. Phải đọc cùng loai và thẻ [GỌI].

3.7 `ghi_chu` — thẻ đọc nhanh cho Agent

Ghi theo một dòng có cấu trúc cố định:

[MỤC ĐÍCH] ... | [KHI DÙNG] ... | [INPUT] ... | [TÁC ĐỘNG] ... | [GỌI] ... | [BẰNG CHỨNG] ... | [TỪ KHÓA] ...

Yêu cầu:

MỤC ĐÍCH: một câu ngắn, bắt đầu bằng động từ.
KHI DÙNG: tình huống Agent nên tìm function này.
INPUT: lấy từ chữ ký PG Census; không tự thêm tham số.
TÁC ĐỘNG: một trong ĐỌC/KIỂM TRA, GHI/THAY ĐỔI DỮ LIỆU, TỰ ĐỘNG QUA TRIGGER, HỖ TRỢ NỘI BỘ, POSTGRESQL NỘI BỘ.
GỌI: dùng đúng một trong AGENT_CALLABLE, AGENT_GATED, INTERNAL_TRIGGER, INTERNAL_HELPER, PG_EXTENSION và kèm cảnh báo cần thiết.
BẰNG CHỨNG: ví dụ PG Census + trigger_registry, PostgreSQL extension, PG Census: tên + chữ ký; chưa đọc thân hàm.
TỪ KHÓA: gồm tên function, chuyên môn, từ nghiệp vụ tiếng Việt và từ kỹ thuật tiếng Anh quan trọng.

Không viết ghi chú chung chung như “xử lý dữ liệu” hoặc “hàm hệ thống”.

4. Quy tắc nhận diện

4.1 DOT giám sát (đọc)

Dấu hiệu: audit, check, health, scan, verify, validate, status, coverage, plan, preview, query, render, census, drift, orphan.

Chỉ gắn DOT đọc khi function là entry point hữu ích cho Agent. Helper predicate/validator được function khác gọi vẫn có thể là Hàm tiện ích.

4.2 DOT hành động (ghi)

Dấu hiệu: create, apply, approve, reject, update, sync, refresh, register, transition, emit, enqueue, cleanup, retire, restore, merge, split, open, close, publish.

Mọi DOT ghi phải có:

loai = DOT hành động (ghi)
kiem_soat = true
[GỌI] AGENT_GATED; kiểm tra gate/quyền/dry-run trước khi gọi trong ghi chú.

4.3 Trigger nội bộ

Nếu trigger_registry.function_name khớp function hoặc tên thể hiện rõ trigger handler:

loai = Trigger nội bộ
kiem_soat = false
thẻ [GỌI] INTERNAL_TRIGGER; không gọi trực tiếp
ghi chú phải nêu trigger dùng function và nguồn trigger_registry khi có.

4.4 Hàm extension

Các họ như gbt_*, gbtreekey*, pgp_*, armor, crypt, digest, encrypt, decrypt, hmac, postgres_fdw_*:

loai = Hàm extension
kiem_soat = false
thẻ [GỌI] PG_EXTENSION; không gọi như DOT nghiệp vụ
không tính vào số DOT nghiệp vụ.

4.5 Hàm tiện ích

Dùng khi function là helper, predicate, formatter, hasher, resolver nội bộ hoặc chưa đủ bằng chứng để coi là DOT:

loai = Hàm tiện ích
kiem_soat = false
thẻ [GỌI] INTERNAL_HELPER; không gọi như entry point
không gọi trực tiếp nếu chưa đọc call contract.

5. Cách Agent tìm nhanh

Muốn tìm điểm gọi đọc: lọc loai = DOT giám sát (đọc), rồi đọc thẻ [GỌI] AGENT_CALLABLE.
Muốn tìm điểm gọi ghi: lọc loai = DOT hành động (ghi), sau đó bắt buộc kiểm tra kiem_soat = true và thẻ [GỌI] AGENT_GATED.
Muốn biết logic tự chạy ở đâu: lọc loai = Trigger nội bộ và tìm theo chuyen_mon.
Muốn tránh kết quả nhiễu: loại Hàm extension và Hàm tiện ích khỏi truy vấn DOT.
Tìm theo nghiệp vụ trước bằng nhom, thu hẹp bằng chuyen_mon, cuối cùng đọc ghi_chu và chữ ký.

6. Quy tắc tự cập nhật

Reconcile tự động được phép cập nhật tồn tại, schema, chữ ký và da_mat từ live PG Census; không tự ghi active khi vocabulary/constraint chưa được xác minh.
Không được tự ghi đè mô tả đã xác minh bằng suy luận yếu hơn.
Khi function mới xuất hiện, reconcile xác nhận bằng PG Census và đặt da_mat = false; nếu chưa đủ bằng chứng thì dùng Hàm tiện ích, ghi thẻ [GỌI] INTERNAL_HELPER và “chưa đọc thân hàm”.
Khi function biến mất, giữ dòng Balo để truy vết và đặt da_mat = true; không tự ghi vocabulary active khi chưa xác minh constraint.
Khi taxonomy thay đổi, cập nhật tài liệu này trước; sau đó mới chạy backfill dữ liệu.

7. Ví dụ chuẩn

DOT ghi

Nhóm: Đơn vị thông tin (IU)
Loài: DOT hành động (ghi)
Chuyên môn: iu.staging
Lớp: — (giữ nguyên theo vocabulary nền)
Active: — (đọc tình trạng từ da_mat/live Census)
Kiểm soát: true
Ghi chú: [MỤC ĐÍCH] Phê duyệt bản ghi IU staging | [KHI DÙNG] Khi staging đã đủ hồ sơ phê duyệt | [INPUT] p_staging_record_id uuid, p_approved_by text, p_approval_doc_id text | [TÁC ĐỘNG] GHI/THAY ĐỔI DỮ LIỆU | [GỌI] AGENT_GATED; kiểm tra gate/quyền trước khi gọi | [BẰNG CHỨNG] PG Census: tên + chữ ký; chưa đọc thân hàm | [TỪ KHÓA] fn_iu_staging_approve, iu.staging, approve, phê duyệt

Trigger

Loài: Trigger nội bộ
Lớp: — (khả năng gọi nằm trong thẻ [GỌI])
Kiểm soát: false
Ghi chú: [MỤC ĐÍCH] Tự động gán nhãn khi bản ghi thay đổi | [KHI DÙNG] Tra cứu cơ chế tự động, không gọi trực tiếp | [INPUT] trigger context | [TÁC ĐỘNG] TỰ ĐỘNG QUA TRIGGER | [GỌI] INTERNAL_TRIGGER; không gọi trực tiếp | [BẰNG CHỨNG] PG Census + trigger_registry | [TỪ KHÓA] fn_auto_label_assignment, trigger, label

8. Chỉ số kiểm tra sau mỗi lần cập nhật

Phải báo cáo tối thiểu:

Tổng số Function Balo.
Số DOT đọc.
Số DOT ghi.
Số trigger nội bộ.
Số helper.
Số extension.
Số dòng thiếu nhom, loai, chuyen_mon hoặc ghi_chu.
Số DOT ghi có kiem_soat = false — kết quả bắt buộc bằng 0.
Số trigger thiếu thẻ [GỌI] INTERNAL_TRIGGER hoặc extension thiếu thẻ [GỌI] PG_EXTENSION — kết quả bắt buộc bằng 0.

9. Quản lý thay đổi

Mọi thay đổi tên nhóm, loại, vocabulary thẻ [GỌI] hoặc cấu trúc ghi chú phải:

sửa tài liệu này;
tăng phiên bản;
ghi ngày và lý do thay đổi;
chạy lại kiểm tra toàn bộ Balo Function;
đánh giá kết quả trước khi áp dụng quy định cho Balo thứ hai.

Lịch sử

v1.1 — 2026-07-23: Điều chỉnh theo constraint thực tế của bảng: không ghi vocabulary mới vào lop/active; khả năng gọi nằm ở loai, kiem_soat và thẻ [GỌI]. Đã backfill + verify 654 Function Balo.
v1.0 — 2026-07-23: Ban hành chuẩn đầu tiên cho Agent Discovery; đề xuất 5 lớp khả năng gọi nhưng chưa tương thích CHECK constraint hiện hữu.