C2 — Metadata Governance Operating Model
C2 — METADATA GOVERNANCE OPERATING MODEL
Design Note tiền-schema — Điều 38 Text as Code
Trạng thái: DỰ THẢO — GPT review vòng 2 PASS, chờ User duyệt Loại: Design note (operating model), KHÔNG phải schema Phase: P2 trong Design Phase (P1–P7) Inputs pháp lý: L3 (Metadata Governance), L1 (Text Unit), L4 (Birth Gate), L5 (Review + Change-set) Tiền đề: C1 — Text Unit Operating Model (GPT PASS vòng 2) Soạn: Opus 4.6 Review: GPT vòng 1 (17 chỉnh + 4 khuyến nghị) → GPT vòng 2 PASS Ngày: 2026-04-25
1. Mục đích
Mô tả cách hệ thống vận hành metadata cho 4 loại object: document envelope, logical unit + unit version, component, relation. Trả lời câu hỏi: "field nào bắt buộc, ai điền, khi nào điền, máy tự điền gì, kiểm tra bằng gì, sai thì xử lý thế nào?"
Đây là "sổ tay vận hành nhà máy metadata": core metadata là bộ khung cứng, profile là phần mở rộng linh hoạt, field responsibility matrix phân công ai làm gì, validation matrix kiểm tra chất lượng.
C2 dựa trên L3 (luật metadata) + C1 (operating model text unit, đặc biệt phân biệt logical unit vs unit version). C2 đủ chi tiết để P5 chuyển thành schema, nhưng chưa phải schema.
2. Phạm vi
2.1 Bao gồm
- Core metadata framework: 4 nhóm chung + core-equivalent theo object family.
- Profile model: required vs optional, lifecycle, registration.
- Field responsibility matrix: system auto / DOT derive / agent manual / agent assisted — cho document, logical unit, unit version, component, relation, change-set, published snapshot.
- Validation matrix: completeness (birth) / correctness (DOT daily) / consistency (DOT daily/weekly).
- Controlled vocabulary governance: registry, lifecycle, thêm/sửa.
- Metadata trên logical unit vs unit version: field nào gắn identity, field nào gắn version.
- Metadata trong change-set và published snapshot.
- Self-healing cho metadata/derived fields.
2.2 Không bao gồm
- Tên bảng/cột, kiểu dữ liệu, constraint cụ thể (thuộc P5).
- Trigger/function (thuộc P5/P6).
- DOT list/config cụ thể (thuộc P6).
- Danh sách profile fields cụ thể (= config data, seed ở P5).
- Storage model cho profile (JSONB / EAV / dedicated columns) — đây là OD-M2, C2 chưa chọn.
- Migration plan (thuộc P7).
- Component/BOM operating model (thuộc C3, nhưng C2 chốt metadata rules áp cho component).
- KG/vector implementation.
3. Inputs
| Input | Lấy gì cho C2 |
|---|---|
| L3 — Metadata Governance | Core 4 nhóm, core-equivalent, profile 2 tầng, field responsibility 4 fill types, 3 tầng kiểm tra, controlled vocabulary, 10 nguyên tắc bắt buộc |
| C1 — Text Unit Operating Model | Phân biệt logical unit vs unit version, published snapshot = tập unit versions, hot/cold path, invariants |
| L1 — Text Unit Governance | Core-equivalent cho text unit, document envelope |
| L4 — Birth Gate Extension | Birth check = completeness, enforcement mode config-driven |
| L5 — Review + Change-set | Review state = metadata trên unit, approval status = metadata trên change-set |
4. Core metadata framework
4.1 Bốn nhóm core metadata
Đây là khung cứng. Mọi object thuộc scope Đ38 phải có 4 nhóm core metadata hoặc core-equivalent theo family. Thay đổi core = amend path hợp pháp, không xử lý như config change (L3 §3.1).
| Nhóm | Mô tả | Ví dụ concept |
|---|---|---|
| Identifier | Định danh duy nhất toàn hệ thống | Canonical address (logical unit), version identity (unit version), code (component), edge_id (relation) |
| Status / Validity | Trạng thái hiện hành | Lifecycle status (draft/enacted/superseded/retired), governance status, valid_time |
| Timestamps | Khi nào tạo, khi nào sửa | created_at, updated_at |
| Classification | Thuộc loại gì | doc_type, section_type, component_type, edge_type |
Lưu ý: Không phải mọi object family có đủ 4 nhóm theo nghĩa giống nhau. Relation không có owner/title/version thông thường — provenance + valid_time thay vai trò tương đương. L3 đã cố ý dùng "core-equivalent" để phân biệt.
4.2 Core-equivalent theo object family
Ngoài 4 nhóm chung, mỗi loại object có core-equivalent đặc thù — bắt buộc cho loại đó. Đây là concept-level, không chốt tên cột hay kiểu dữ liệu.
4.2.1 Document envelope
Name, owner, version, description, doc_type, article_number/legal_number (nếu doc_type yêu cầu — SOP/knowledge có thể không có), enacted_at, council_score, kb_path. Có thể map với normative_registry (C1 §4.1).
4.2.2 Logical text unit (identity metadata)
Canonical address, doc_code (thuộc document nào), parent (cây cấu trúc), sort_order, section_code (human-readable alias — thay đổi section_code không đổi canonical address), owner, section_type.
Lưu ý quan trọng (từ C1 §4.2): Các fields này gắn với logical unit identity — tồn tại xuyên suốt versions. Canonical address bất biến. Doc_code và parent thường ổn định nhưng có thể thay đổi qua structural change-set (re-parent, split/merge).
Về owner: Owner mặc định là logical unit owner (thường kế thừa từ document owner). Nếu cần version-level owner riêng thì phải có rule — mặc định logical unit-level để tránh authority rối.
Về section_type: Mặc định section_type thuộc logical unit vì nó mô tả vai trò cấu trúc của unit (article, paragraph, heading, note...). Thay đổi section_type là structural/content change, phải qua change-set. Nếu schema phase chọn version-level thì phải có rule rõ ràng — đây là OD-M8.
4.2.3 Unit version (content metadata)
Title, version_number, description, body (content payload theo section_type — heading/container có thể không có body dài), body_hash (derived), tier (derived-first), review_state, editor/contributor (nếu cần phân biệt ai sửa version này).
Lưu ý: Các fields này gắn với unit version — thay đổi theo version. Mỗi version có title, body, description riêng. Enacted version bất biến (C1 §4.2.2).
4.2.4 Component
Name, owner, version, description (spec_summary), component_type, interface (in/out ở mức governance), lifecycle_status, governance_status, base_component (nếu variant), reuse_decision_ref. Chi tiết xem L2.
4.2.5 Relation
Source, target, edge_type, confidence, provenance, status. Relation không có title/owner/version theo nghĩa thông thường — provenance + valid_time thay vai trò tương đương.
Phân biệt authoritative vs proposed: Authoritative relation phải qua write path hợp pháp. Proposed edge từ KG/cold path là projection — rule required fields có thể khác (ít strict hơn), nhưng vẫn phải có source, target, edge_type, provenance.
4.3 Metadata trên logical unit vs unit version — bảng tổng hợp
Đây là phân biệt quan trọng cho schema phase.
| Loại metadata | Gắn với | Đặc tính | Ví dụ |
|---|---|---|---|
| Identity metadata | Logical unit | Ổn định xuyên versions. Canonical address bất biến. | canonical_address, doc_code, parent, sort_order, section_code, owner, section_type |
| Content metadata | Unit version | Thay đổi theo version. Enacted version bất biến. | title, body, body_hash, description, version_number, tier, review_state, editor/contributor |
Quy tắc vận hành:
- Khi tạo version mới (C1 §6.3): identity metadata giữ nguyên (vì gắn logical unit), content metadata tạo mới (vì gắn version mới).
- Published snapshot tham chiếu unit versions → chứa cả identity metadata (qua logical unit) lẫn content metadata (qua version).
- Birth gate kiểm khác nhau tùy loại birth:
- Birth logical unit mới: kiểm identity metadata (address unique, parent hợp lệ, doc_code, owner, section_type) + content metadata draft version đầu tiên (title, body, description).
- Birth/creation version mới: chủ yếu kiểm content metadata + inherited identity (address giữ nguyên, parent kế thừa).
4.4 Về description
Description thuộc core governance expectation (L3 §4.3):
- Document, unit version, component: bắt buộc.
- Relation: không bắt buộc — provenance + edge_type đã đủ ngữ nghĩa.
- Object kỹ thuật nhỏ: theo config, tránh bắt tuyệt đối quá sớm.
4.5 Bảng tổng hợp metadata theo level
| Level | Metadata chính | Ghi chú |
|---|---|---|
| Document | Name, owner, version, doc_type, description, lifecycle, council_score, article_number (nếu áp dụng), enacted_at, kb_path | Bao bì văn bản |
| Logical unit | Canonical address, doc_code, parent, sort_order, section_code, owner, section_type | Identity ổn định xuyên versions |
| Unit version | Version_number, title, body, body_hash, description, tier, review_state, lifecycle, editor/contributor, timestamps | Content thay đổi theo version |
| Change-set | CS identity, owner, scope description, lifecycle, APR ref, snapshot ref, timestamps | Container gom thay đổi |
| Published snapshot | Snapshot identity, version, timestamp, membership (logical_unit_id → unit_version_id) | Bản chính thức document |
| Component | Code, name, owner, version, component_type, spec_summary, interface, lifecycle, base_component, reuse_decision_ref | Registry component |
| Relation | Edge_id, source, target, edge_type, confidence, provenance, status, timestamps | Quan hệ ngang |
5. Profile model
5.1 Nguyên tắc 2 tầng
Core = khung cứng (amend path hợp pháp). Profile = mở rộng linh hoạt (config/registration path PG-native, L3 §3.2). 2 tầng = vừa đủ: core giữ kỷ luật, profile cho linh hoạt.
5.2 Profile áp theo ngữ cảnh
Profile mở rộng core theo: doc family, section_type, component_type, edge_type. Ví dụ:
- Luật cần: legal_effect, enforcement_date.
- SOP cần: actor, department, frequency.
- Guard cần: trigger_timing, severity.
Danh sách profile fields cụ thể = config data, chốt tại design/seed phase, KHÔNG chốt trong C2.
5.3 Required vs optional profile
| Loại | Birth path | DOT daily | Nguồn |
|---|---|---|---|
| Required profile | Block/warn/escalate theo rule; mặc định block nếu không có ngoại lệ | — | L3 §5.2 |
| Optional profile | Không block | Nhắc nếu thiếu (INFO level) | L3 §5.2 |
Phân loại required/optional cho từng field = config data khi đăng ký profile.
5.4 Quy tắc profile
| Quy tắc | Mô tả | Nguồn |
|---|---|---|
| Profile không phá core | Profile chỉ thêm, không ghi đè core metadata | L3 §3.2 |
| Config, không code | Thêm profile mới theo config/registration path PG-native | L3 §3.2, NT4 |
| Agent không tự sáng tác | Field phải nằm trong config đã đăng ký. Free-form = cấm. | L3 §3.2 |
| Justify "PG không tự biết" | Mỗi field phải justify tại sao PG không tự tính được | L3 §3.2, NT11 |
5.5 Profile lifecycle
Profile không phải "đống config vô chủ" (L3 §3.2). Profile schema phải có governance:
| Thuộc tính | Mô tả |
|---|---|
| Owner | Ai chịu trách nhiệm profile schema này |
| Version | Profile schema có version — thay đổi fields = version mới |
| Status | active / deprecated / retired |
| Registration | Profile phải đăng ký trong PG (config table/registry) |
Thêm/sửa/retire profile field → approval path theo risk/config; có thể không cần high-risk APR nếu policy cho phép, nhưng phải có owner + audit trail.
6. Field responsibility matrix
6.1 Bốn loại fill (L3 §6.1)
| Loại fill | Ai làm | Khi nào | Cơ chế |
|---|---|---|---|
| System auto | PG-native mechanism | Mỗi INSERT/UPDATE, tự động | Ví dụ: trigger, generated column, default value — đây là ví dụ cơ chế, không phải quyết định C2. Cơ chế cụ thể thuộc P5. |
| DOT derive | DOT theo schedule hoặc event | Sau INSERT, daily, hoặc event trigger | DOT paired (writer derive + checker verify). Áp theo từng object type, không phải mọi field derive áp cho mọi object. |
| Agent manual | Agent khi tạo/sửa object | Birth (INSERT) hoặc amend (UPDATE draft) | Birth path validate bắt buộc |
| Agent assisted | Agent fill, system gợi ý | Birth hoặc sửa, có suggest | Tương lai: search/recommend từ KG hoặc catalog |
6.2 Nguyên tắc phân công (L3 §6.2)
| Nguyên tắc | Giải thích |
|---|---|
| Máy trước, người sau | Nếu PG có thể tự tính (timestamps, hash, status transitions) → system auto. Không bắt agent khai cái máy biết. |
| Derived-first cho metadata cấu trúc | Tier, binding count, species count = tính từ PG data, không hardcode. Agent chỉ đề xuất ban đầu; DOT/system xác nhận cuối cùng. |
| Agent chỉ khai cái người biết | Owner, body, title, doc_type, component_type, section_type = chỉ agent biết. |
| DOT kiểm cái có thể sai | Business rule, cross-object consistency, drift = DOT daily. |
6.3 Field responsibility — Document envelope
| Field (concept) | Fill type | Khi nào | Ghi chú |
|---|---|---|---|
| Identifier (doc_code) | Agent manual | Birth | Unique, có thể system-assisted |
| Name | Agent manual | Birth | — |
| Owner | Agent manual | Birth | — |
| Doc_type | Agent manual | Birth | FK controlled vocabulary |
| Description | Agent manual | Birth | Bắt buộc |
| Article_number / legal_number | Agent manual | Birth | Chỉ áp dụng nếu doc_type yêu cầu (luật, chính sách). SOP/knowledge có thể không có. |
| Version | System auto | Khi change-set enacted | Bump theo rule (C1 §6.5) |
| Lifecycle status | System auto / default | Transition events | draft (default) → enacted → superseded → retired |
| Timestamps | System auto | INSERT/UPDATE | — |
| Council score | Agent manual / DOT derive | Sau council review | — |
| Enacted_at | System auto | Khi enacted | — |
6.4 Field responsibility — Logical unit (identity metadata)
| Field (concept) | Fill type | Khi nào | Ghi chú |
|---|---|---|---|
| Canonical address | System auto hoặc agent manual | Birth | Bất biến sau birth. Reserved trước commit nếu system-auto (C1 §4.3). |
| Doc_code (FK document) | Agent manual | Birth | Bất biến thông thường. Thay đổi = structural change-set. |
| Parent (FK self) | Agent manual | Birth hoặc structural change | Cùng document. Thay đổi = change-set. |
| Sort_order | Agent manual | Birth hoặc reorder | — |
| Section_code | Agent manual / DOT derive | Birth hoặc render | Human-readable alias, có thể đổi. Thay đổi section_code không đổi canonical address. |
| Owner | Agent manual | Birth | Mặc định kế thừa từ document owner. Thay đổi = change-set nếu cần. |
| Section_type | Agent manual | Birth | FK controlled vocabulary. Mặc định logical unit-level (OD-M8). Thay đổi section_type = structural/content change qua change-set. |
6.5 Field responsibility — Unit version (content metadata)
| Field (concept) | Fill type | Khi nào | Ghi chú |
|---|---|---|---|
| Version_number | System auto | Khi tạo version mới | Sequential hoặc semantic — OD (C1 §10) |
| Title | Agent manual | Birth / sửa draft | — |
| Body | Agent manual | Birth / sửa draft | Content payload theo section_type. Heading/container có thể không có body dài. |
| Body_hash | System auto / DOT derive | Sau INSERT/UPDATE | Derived từ body |
| Description | Agent manual | Birth | Bắt buộc |
| Editor/contributor | System auto / agent manual | Khi sửa version | Ai sửa version này (khác owner logical unit) |
| Tier | DOT derive | Sau birth | Derived-first: tính từ vị trí trong cây |
| Lifecycle status | System auto / default | Transition events | draft (default) → enacted → superseded → retired |
| Review_state | Agent manual (reviewer) | Sau review | unreviewed → in_review → pass/fail → needs_re_review |
| Timestamps | System auto | INSERT/UPDATE | — |
| Required profile fields | Agent manual | Birth | Theo config đăng ký cho section_type/doc_family |
| Optional profile fields | Agent manual / agent assisted | Birth hoặc sau | DOT nhắc nếu thiếu |
6.6 Field responsibility — Component
| Field (concept) | Fill type | Khi nào | Ghi chú |
|---|---|---|---|
| Code | Agent manual | Birth | Unique |
| Name | Agent manual | Birth | — |
| Spec_summary | Agent manual | Birth | — |
| Component_type | Agent manual | Birth | FK controlled vocabulary |
| Owner | Agent manual | Birth | — |
| Description | Agent manual | Birth | Bắt buộc |
| Interface | Agent manual | Birth hoặc sửa | Governance-level, không implementation |
| Lifecycle/governance status | System auto / default | Transitions | — |
| Base_component | Agent manual | Birth (nếu variant) | FK component tồn tại |
| Reuse_decision_ref | Agent manual | Birth (tạo mới/variant) | Bắt buộc theo L2/L4 |
| Version | System auto | Version bump | — |
| Timestamps | System auto | INSERT/UPDATE | — |
6.7 Field responsibility — Relation
| Field (concept) | Fill type | Khi nào | Ghi chú |
|---|---|---|---|
| Edge_id | System auto | Birth | — |
| Source | Agent manual / DOT derive | Birth | FK object |
| Target | Agent manual / DOT derive | Birth | FK object |
| Edge_type | Agent manual | Birth | FK controlled vocabulary |
| Confidence | Agent manual / DOT derive | Birth hoặc update | — |
| Provenance | System auto | Birth | Ai/gì tạo edge |
| Status | System auto / default | Transitions | — |
| Timestamps | System auto | INSERT/UPDATE | — |
Lưu ý: Proposed edge từ KG/cold path và authoritative relation có rule required fields khác nhau. Authoritative relation phải qua write path hợp pháp; proposed edge rule có thể ít strict hơn nhưng vẫn phải có source, target, edge_type, provenance.
6.8 Field responsibility — Change-set
| Field (concept) | Fill type | Khi nào | Ghi chú |
|---|---|---|---|
| CS identity | System auto | Birth | — |
| Owner | Agent manual | Birth | Ai tạo change-set |
| Scope description | Agent manual | Birth | Self-contained: đọc hiểu scope (L5 §3.3) |
| Lifecycle status | System auto | Transitions | draft → submitted → review_passed → approval_passed → enacted/applied / rejected / withdrawn |
| APR reference | System auto / DOT | Khi submitted | Liên kết APR Đ32 |
| Snapshot reference | System auto | Khi submitted | Liên kết change-set snapshot đóng băng |
| Timestamps | System auto | INSERT/UPDATE | — |
6.9 Field responsibility — Published snapshot
| Field (concept) | Fill type | Khi nào | Ghi chú |
|---|---|---|---|
| Snapshot identity | System auto | Khi tạo/update snapshot | — |
| Version | System auto | Khi change-set enacted | Khớp document version |
| Timestamp | System auto | Khi transition | — |
| Membership | System auto | Khi change-set enacted | Danh sách (logical_unit_id → unit_version_id). Mỗi logical unit tối đa 1 version. KHÔNG BAO GIỜ trỏ tới draft version. |
7. Validation matrix — 3 tầng kiểm tra
7.1 Tầng 1: Completeness — đủ metadata (birth path)
Khi nào: Tại INSERT hoặc creation/write path tương ứng (L4).
Kiểm gì: Core metadata + required profile phải có giá trị hợp lệ. Lifecycle status có thể do system auto/default cấp — không bắt agent khai.
Ai kiểm: Birth gate mechanism (PG-native).
Fail thì sao: Block/warn/escalate theo enforcement mode config (L4 §6). Mặc định: core thiếu → block, required profile thiếu → block, optional profile thiếu → warn.
| Object family | Kiểm completeness gì | Nguồn |
|---|---|---|
| Document envelope | Name, owner, doc_type, description, lifecycle status (default) | L3 §4.2, L4 |
| Logical unit mới + draft version đầu tiên | Identity: address (unique), doc_code, parent, sort_order, owner, section_type. Content (version): title, body (theo section_type), description, lifecycle status (default), required profile. | L4 §4.2, C1 §6.1 |
| Version mới (của enacted unit) | Chủ yếu content metadata: title, body (theo section_type), description, version_number, lifecycle status (default), required profile. Identity kế thừa từ logical unit. | L4 §9.2, C1 §6.3 |
| Component | Code, name, spec_summary, component_type, owner, description, interface (nếu required), reuse_decision (nếu tạo mới/variant), lifecycle status (default), required profile | L4 §5.2 |
| Relation (authoritative) | Source, target, edge_type, provenance, status (default) | L3 §4.2 |
| Relation (proposed/KG) | Source, target, edge_type, provenance — rule có thể ít strict hơn authoritative | C1 §8.2 |
7.2 Tầng 2: Correctness — đúng logic (DOT daily)
Khi nào: Sau INSERT, theo schedule hoặc event-driven.
Kiểm gì: Giá trị metadata phải đúng ngữ nghĩa, đúng business rule.
Ai kiểm: DOT paired (checker verify).
| Kiểm tra | Mô tả | Object family |
|---|---|---|
| Parent hợp lệ | Parent trỏ logical unit cùng document, tồn tại | Logical unit |
| Ref target hợp lệ | Edge target tồn tại, status hợp lệ | Relation |
| Classification hợp lệ | doc_type, section_type, component_type, edge_type nằm trong controlled vocabulary active | Tất cả |
| Derived fields đúng | Tier, body_hash, counts khớp với data thực | Unit version, component |
| Lifecycle nhất quán | Status unit version khớp change-set + document (C1 §7.5) | Unit version |
| Review state nhất quán | Review pass nhưng change-set rejected → cần re-review | Unit version |
| Reuse decision hợp lệ | Reuse_decision_ref trỏ record tồn tại + approved | Component |
Xử lý sai:
- Draft objects → self-healing nếu rule cho phép: auto-fix metadata/derived fields + re-check + log (L3 §7.2).
- Enacted objects → escalate, không auto-fix nội dung (L3 §8.6).
7.3 Tầng 3: Consistency — nhất quán chéo (DOT daily/weekly)
Khi nào: Schedule, thường daily hoặc weekly cho cross-object.
Kiểm gì: Metadata giữa các object liên quan phải nhất quán.
| Kiểm tra | Mô tả |
|---|---|
| Document enacted ↔ published snapshot | Published snapshot chỉ chứa enacted/current unit versions (C1 §7.3) |
| Duplicate enacted version | Cùng logical unit không có 2+ enacted versions trong published snapshot (C1 §7.6) |
| Document version ↔ change-set | Document version khớp với change-set enacted gần nhất |
| Component BOM ↔ component version | BOM entry trỏ đúng version component hiện hành |
| Cross-document ref | Ref ngang trỏ tới unit/document hợp lệ, không retired/orphan |
7.4 Optional enrichment (DOT nhắc)
Object có đủ core + required profile nhưng thiếu optional profile fields → INFO level. Nhắc fill, không block. Đây là enrichment, không phải enforcement.
7.5 Validation tổng hợp
Birth (INSERT / creation path) → Completeness check (Tầng 1)
↓ PASS
Object vào PG (draft)
↓
DOT daily → Correctness check (Tầng 2) + Consistency check (Tầng 3)
↓ nếu sai
├── Draft → self-healing (auto-fix + re-check + log)
└── Enacted → escalate (không auto-fix content/metadata)
↓
DOT daily → Optional enrichment (INFO nhắc)
8. Controlled vocabulary governance
8.1 Controlled vocabulary là gì
Danh sách giá trị cho phép của classification metadata: doc_type, section_type, component_type, edge_type. Mỗi giá trị = FK config đã đăng ký (L3 §8.9). Không free-form.
8.2 Governance
| Thuộc tính | Mô tả |
|---|---|
| Registry | Controlled vocabulary sống trong PG (config table/registry). Mỗi vocabulary có danh sách values. |
| Lifecycle | Mỗi value: active / deprecated / retired. Deprecated = vẫn hợp lệ cho object cũ, không cho object mới. Retired = không hợp lệ. |
| Thêm value mới | Approval path theo risk/config; phải có owner + audit trail. |
| Deprecate/retire value | Cần kiểm impact: bao nhiêu object đang dùng? DOT migration plan nếu retire. Approval path theo risk/config. |
| Validation | Birth gate kiểm: value phải active. DOT daily kiểm: object dùng deprecated value → warn, retired value → error. |
8.3 Ví dụ controlled vocabulary (concept-level)
| Vocabulary | Áp cho | Ví dụ values |
|---|---|---|
| doc_type | Document envelope | law, policy, sop, guideline, knowledge |
| section_type | Logical unit | article, paragraph, definition, table, note, heading, appendix |
| component_type | Component | template, snippet, guard, validator, formatter, renderer |
| edge_type | Relation | references, amends, supersedes, depends_on, related_to |
Danh sách cụ thể = config data, chốt ở design/seed phase.
9. Self-healing cho metadata
9.1 Nguyên tắc (L3 §7.2, 02DY)
Self-healing = phát hiện sai → log issue → auto-fix nếu draft + rule cho phép → re-check → escalate nếu không fix được.
9.2 Scope self-healing
| Scope | Cho phép auto-fix? | Lý do |
|---|---|---|
| Draft object — derived fields | Có | Tier, body_hash, counts = tính lại từ data. Không ảnh hưởng nội dung agent viết. |
| Draft object — metadata fields | Có (theo rule) | VD: section_type deprecated → chuyển sang successor value nếu có mapping. Log + nhắc owner. |
| Enacted object — derived fields | Có điều kiện | Recompute/checksum repair chỉ khi source content unchanged và rule cho phép. Nếu body_hash sai mà nghi corruption (source content thay đổi/không khớp) → escalate, không auto-fix. |
| Enacted object — content/metadata | KHÔNG | Enacted = bất biến. Phải version mới + change-set + APR. Escalate. |
9.3 Self-healing loop
DOT detect issue → log issue
↓
Draft? → auto-fix (nếu rule cho phép) → re-check
├── Fixed → close issue
└── Not fixed → escalate
↓
Enacted derived? → recompute nếu source unchanged + rule cho phép
├── Fixed → close issue
└── Nghi corruption → escalate
↓
Enacted content/metadata? → escalate (không auto-fix)
10. Metadata trong change-set và published snapshot
10.1 Change-set metadata
Change-set bản thân có metadata riêng (L5 §8.2):
- Change-set identity, owner, scope description.
- Lifecycle status (draft/submitted/review_passed/approval_passed/enacted/rejected/withdrawn).
- APR reference (liên kết APR Đ32).
- Snapshot reference (liên kết change-set snapshot đóng băng).
- Timestamps.
Tất cả phải PG-native (L5 §8.4, HP NT13).
10.2 Published snapshot membership
Published snapshot = tập unit versions enacted/current (C1 §4.9). Metadata vận hành:
- Snapshot có identity + version + timestamp.
- Membership = danh sách (logical_unit_id, unit_version_id) — mỗi logical unit tối đa 1 version.
- Published snapshot membership không bao giờ trỏ tới draft version. Đây là invariant cứng (C1 I8).
- Snapshot transition khi change-set enacted: thêm versions enacted mới, loại versions superseded/retired.
10.3 Metadata transition khi enacted
Khi change-set enacted/applied:
- Unit versions trong change-set: draft → enacted.
- Unit versions cũ (nếu có): enacted → superseded.
- Published snapshot: cập nhật membership — không bao giờ trỏ tới draft version.
- Document: version bump theo rule (không phải mọi change-set đều bump).
- Review state: có thể transition theo rule (VD: enacted → archived/accepted).
- Timestamps: updated_at cập nhật.
Tất cả metadata transitions phải atomic hoặc transactionally consistent — chi tiết transaction boundary thuộc P5/implementation.
11. Invariants bắt buộc
| # | Invariant | Nguồn |
|---|---|---|
| M1 | Metadata governance áp đồng đều 4 object family. Không có object family nào miễn core governance; mức field cụ thể theo core-equivalent/profile. | L3 §8.1 |
| M2 | Core schema = amend path hợp pháp. Thay đổi core không phải config change. | L3 §8.2, HP |
| M3 | Profile = config. Thêm profile theo config/registration path PG-native. Agent không tự sáng tác field. | L3 §8.3, NT4 |
| M4 | Birth path validate completeness. Core + required profile phải đủ tại INSERT hoặc creation/write path tương ứng. | L3 §8.4, L4 |
| M5 | DOT daily validate correctness + consistency. | L3 §8.5 |
| M6 | Self-healing cho draft. Escalate cho enacted. Enacted derived fields: recompute chỉ khi source unchanged + rule cho phép; nghi corruption → escalate. | L3 §8.6 |
| M7 | Derived-first cho metadata cấu trúc. Tier, counts = tính từ data. | L3 §8.7, NT11 |
| M8 | Máy trước, người sau. System auto > DOT derive > agent manual. | L3 §8.8, NT2, NT11 |
| M9 | Controlled vocabulary cho mọi classification. FK config, không free-form. | L3 §8.9 |
| M10 | Reuse pattern proven, không copy nguyên trạng. Birth gate, config-driven = nguyên lý. Schema/trigger mới. | L3 §8.10, 02DY |
| M11 | Identity metadata gắn logical unit, content metadata gắn unit version. Canonical address bất biến xuyên versions. Owner + section_type mặc định logical unit-level. | C1 §4.2, §4.3 |
| M12 | APR/change-set metadata phải PG-native. | L5 §8.4, HP NT13 |
| M13 | Profile phải có owner/version/lifecycle. Không phải "đống config vô chủ". | L3 §3.2 |
| M14 | Published snapshot membership không bao giờ trỏ tới draft version. | C1 I8, L5 §6.3 |
12. Open decisions — chuyển sang schema phase
| # | Open decision | Ghi chú |
|---|---|---|
| OD-M1 | Identity metadata vs content metadata storage. Logical unit table riêng hay cùng row với version? Liên quan C1 OD12. | Quan trọng nhất |
| OD-M2 | Profile storage model. JSONB, EAV, hay dedicated columns? C2 chưa chọn. | Ảnh hưởng query + validation |
| OD-M3 | Controlled vocabulary table structure. 1 bảng chung hay mỗi vocabulary 1 bảng? | Ảnh hưởng FK + performance |
| OD-M4 | Self-healing rule storage. Config table hay hardcode? | Ảnh hưởng flexibility |
| OD-M5 | Profile field registry schema. Cách đăng ký profile field: field_name, field_type, required/optional, default_value... | Seed ở P5 |
| OD-M6 | Published snapshot storage. Materialized view, snapshot table, hay versioned membership table? | Ảnh hưởng query + consistency |
| OD-M7 | Derived field computation model. Trigger (realtime) hay DOT (scheduled)? Per-field decision. | Performance vs consistency tradeoff |
| OD-M8 | Section_type thuộc logical unit-level hay unit-version-level? Default C2 nghiêng về logical unit-level (mô tả vai trò cấu trúc); schema phase phải chốt. | Quan trọng trước P5 |
13. Ranh giới — C2 không làm gì
| Không làm | Lý do |
|---|---|
| Không chốt tên bảng/cột, kiểu dữ liệu, constraint | Schema thuộc P5 |
| Không chốt trigger/function cụ thể | Implementation thuộc P5/P6 |
| Không liệt kê danh sách profile fields cụ thể | Config data, seed ở P5 |
| Không chốt DOT list/config cụ thể | Implementation thuộc P6 |
| Không chốt enforcement mode per field | Config thuộc L4/P6 |
| Không chốt storage model (JSONB/EAV/dedicated) | OD-M2, thuộc P5 |
| Không định nghĩa text unit / component model | Thuộc C1, C3 |
| Không chốt review/approval flow | Thuộc C1 (từ L5) |
| Không migration plan | Thuộc P7 |
| Không KG/vector implementation | Ngoài scope |
14. Điều kiện PASS
| # | Điều kiện |
|---|---|
| 1 | Core metadata 4 nhóm + core-equivalent rõ ràng, nhất quán với L3. Không áp cứng giống nhau cho mọi object — core-equivalent theo family. |
| 2 | Metadata phân biệt rõ identity (logical unit) vs content (unit version), nhất quán với C1 §4.2 |
| 3 | C2 làm rõ owner, section_type và content payload thuộc logical unit hay unit version. Owner + section_type mặc định logical unit-level. Content payload theo section_type. |
| 4 | Profile model (required/optional, lifecycle, registration) nhất quán với L3 §3, §5 |
| 5 | Field responsibility matrix (4 fill types) nhất quán với L3 §6 — cover document, logical unit, unit version, component, relation, change-set, published snapshot |
| 6 | Validation matrix (3 tầng) nhất quán với L3 §7, bao gồm self-healing rules. Phân biệt birth logical unit mới vs version mới. |
| 7 | Controlled vocabulary governance rõ ràng: registry, lifecycle, validation |
| 8 | Metadata trong change-set + published snapshot nhất quán với C1 + L5. Published snapshot membership không trỏ draft version. |
| 9 | Không trượt sang schema/implementation/tên bảng/tên cột |
| 10 | Không mâu thuẫn với C1, L1, L3, L4, L5, Đ4, Đ0-G, Đ32, Đ33, HP |
| 11 | Đủ chi tiết để P5 (schema draft) có field responsibility matrix + validation matrix làm input |
| 12 | GPT review PASS + User duyệt |
DỰ THẢO | C2 — Metadata Governance Operating Model | Design Note tiền-schema | Opus 4.6 | GPT review vòng 1 + vòng 2 PASS | 2026-04-25