P3D — Multidimensional Entity DB Architecture Design v3
P3D — Multidimensional Entity DB Architecture Design v3
Date: 2026-05-12 Author: Opus (Claude) Rev: 3 (TAC→UI baseline required, terminology precision, deploy status corrected) Mode: DESIGN ONLY — no execution, no DB write, no Agent dispatch Authority: GPT directive v3 TAC UI baseline
A. Vì sao phải dừng 5C2
Mỗi vòng review 5C2 phát hiện thêm concept bị bỏ sót — thiếu 1 bản contract nền. Bản thiết kế này khóa contract đó.
Thêm: TAC→UI implementation exists (P10D-2B commit 5ce3437); production deploy status remains UNKNOWN until targeted baseline verification. Migration IU phải chạy SONG SONG mà không phá TAC→UI hiện tại.
B. Thuật ngữ bắt buộc (binding contract)
| Thuật ngữ | Luật | Trả lời câu hỏi | Phân loại | Scope |
|---|---|---|---|---|
| Tầng | Điều 5 | Hệ thống xây ở đâu? | 5 cấp (1→5) | Kiến trúc toàn hệ thống |
| Lớp | Điều 0-B | Entity cấu tạo từ gì? | 6 lớp primary (1→6) + 1 loài | Phân loại MỖI entity |
| Layer | Điều 26 | Nhìn gì trên màn hình? | 5 cấp (1→5) | UI navigation / Pivot |
| Loài | Điều 29 | Entity thuộc nhóm phân loại nào? | Meta-class ngoài 6 lớp | Phân loại metadata |
| Entity Living DB | Điều 21 | Entity biết gì về chính nó? | 6 heading, 8 quy tắc | Mỗi entity |
Primary terminology: 6 lớp + 1 loài = nguyên tử/atom → công trình/building + loài. Hạ nguyên tử (Lớp 0) là policy category cho subordinate artifacts (vd: unit_version hiện tại); không tính là một trong 6 lớp primary trong user-facing terminology.
"Entity Living DB" vs "Lớp 3 hợp chất": Entity Living DB (Điều 21, DB sống của thực thể) là concept về trang chi tiết sống của mỗi entity. KHÔNG nhầm với Lớp 3 hợp chất (Điều 0-B, composition class). Trong prompts, dùng "Entity Living DB" hoặc "DB sống của thực thể", KHÔNG dùng "Lớp 3" đơn lẻ vì gây nhầm.
"Meta-layer": glossary dùng "meta-layer" chỉ loài đứng ngoài 6 lớp. Đây là thuật ngữ glossary, KHÔNG phải UI Layer Điều 26. Khi cần rõ, dùng "meta-class".
Cấm: "Tầng nguyên tử", "Layer nguyên tử", "Lớp UI", "Species = nguyên tử", "7 lớp + meta" (user-facing).
C. Ma trận luật liên quan
| Concept | Luật chính | PG artifact |
|---|---|---|
| Entity recognition | Điều 0 | meta_catalog |
| Composition (6 lớp) | Điều 0-B | composition_level col |
| Species (loài) | Điều 29 + Điều 0-G | entity_species, species_collection_map |
| Birth | Điều 0-G | birth_registry, fn_birth_registry_auto |
| Architecture (5 tầng) | Điều 5 | — (conceptual) |
| Entity Living DB (8 quy tắc) | Điều 21 | FK/M2M + entity_dependencies + vector |
| Pivot / counting | Điều 26 | pivot_definitions, pivot_count() |
| UI navigation (5 layers) | Điều 26 + Điều 28 | Nuxt routes |
| Knowledge Graph | Điều 39 | universal_edges (future) |
| Relations / Dependencies | Điều 21 + Điều 0-B §I-C | entity_dependencies |
| Governance relations | Điều 37 §8.4 | governance_relations |
| Labels/Facets | Điều 24 | entity_labels |
| Collection governance | Điều 36 | collection_registry |
| IU / TAC | Điều 44 + Điều 38 | information_unit, tac_* |
| TAC→UI | P10D v0.2 | Nuxt /knowledge/laws/[pubId].vue |
D. 6 lớp + 1 loài
6 lớp cấu tạo (Điều 0-B)
Primary terminology: 6 lớp (1→6) = nguyên tử → công trình.
Lớp 1: Nguyên tử — có ID, không chứa entity khác
Lớp 2: Phân tử — nhóm atoms, không có logic
Lớp 3: Hợp chất — phân tử + atoms + quy trình/logic
Lớp 4–6: Vật liệu / Sản phẩm / Công trình (tương lai)
Hạ nguyên tử (Lớp 0) = subordinate artifacts không có ID riêng (field values, activity logs). Đây là policy category, không nằm trong 6 lớp primary.
Quy tắc: CHỈ NÂNG KHÔNG HẠ. Mỗi entity thuộc ĐÚNG 1 lớp.
1 loài (species meta-class)
Species là meta-class phân loại, đứng ngoài 6 lớp. Chọn species = chọn luôn composition_level.
| Nguồn | Số species | Ghi chú |
|---|---|---|
| Glossary / luật lịch sử | 33 | Con số tham chiếu trong luật |
| Live runtime (probe 5C1A/5C2A, 2026-05-11) | 40 | Con số thực tế production |
Không dùng số cũ làm sự thật hiện tại. Thêm species = thêm row metadata, KHÔNG sửa code.
E. Metadata như ma trận đa chiều — anti-hardcode contract
Mỗi entity là 1 tọa độ trong ma trận nhiều chiều. KHÔNG enumerate tổ hợp, KHÔNG CASE ladder, KHÔNG hardcode species list. Thêm chiều = metadata row, KHÔNG code.
E.1 Matrix dimension registry contract (design-only)
| Field | Type | Mô tả |
|---|---|---|
| dimension_id | text PK | Mã chiều |
| dimension_name | text | Tên hiển thị |
| source_table | text | Bảng chứa giá trị |
| source_query | text | Query pattern |
| applies_to | text[] | Collections áp dụng |
| cardinality | text | single / multi |
| is_pivotable | boolean | Dùng trong pivot_count() |
| is_birth_required | boolean | Phải có tại khai sinh |
| is_enrichment_dimension | boolean | Làm giàu sau khai sinh |
| is_ui_filterable | boolean | Filter trên Layer 2/3 |
| owner_law | text | Điều luật quản lý |
Design contract, chưa triển khai DB. Thêm chiều = thêm row, KHÔNG code.
F. Entity Living DB — operational contract (Điều 21, 8 quy tắc)
F.1 Six headings — operational detail
IDENTITY — "Tôi là ai?" (Quy tắc 1)
- Runtime: Registry row (meta_catalog, birth_registry)
- Birth req: ID + canonical_address + species + composition + identity_profile core keys
- Enrichment: identity_profile JSONB extensible
- No-cache: Query PG trực tiếp. Không cache species.
- 5C2: ✅ fn_iu_create + merge
RELATIONS — "Tôi thuộc ai? Tôi chứa gì?" (Quy tắc 2 BELONGS_TO + Quy tắc 3 CONTAINS)
- Runtime: FK/M2M native + identity_profile soft links
- Birth req: FK IU→UV auto. D3a hierarchy in JSON.
- Enrichment: universal_edges (Pack 2+)
- No-cache: Quét FK schema trực tiếp.
- 5C2: ✅ Partial (D3a JSON)
DEPENDENCIES — "Tôi dùng ai? Ai dùng tôi?" (Quy tắc 4 DEPENDS_ON + Quy tắc 5 USED_BY)
- Runtime: entity_dependencies
- Birth req: KHÔNG bắt buộc. Entity tồn tại trước, dependencies phát hiện sau.
- Enrichment: dot-relation-discover scan. Transitive = BFS ≤ 3 on-demand (Quy tắc 6).
- No-cache: Query trực tiếp.
- 5C2: ❌ Deferred. Hook: IU uuid.
HISTORY — "Ai sửa?" (auto)
- Runtime: directus_activity + directus_revisions
- Birth req: Auto — Directus ghi.
- 5C2: ✅ Auto
LABELS — "Nhãn gì?" (Quy tắc 7 PEERS = output)
- Runtime: entity_labels junction (Điều 24)
- Birth req: KHÔNG bắt buộc. Labels gán sau.
- 5C2: ❌ Deferred. Hook: IU uuid.
METRICS — "Đếm, health" (Pivot)
- Runtime: pivot_count() + system_health_checks
- Birth req: KHÔNG bắt buộc. Computed từ data.
- No-cache: PG-first. Nuxt renders only.
- 5C2: ❌ Deferred. Hook: birth_registry row.
F.2 Relation-pair matrix
Source: Điều 21 v3.0, Luật Tổ chức Lớp 3 — Hạ tầng Thông tin, §III "8 Quy tắc Quan hệ Phổ quát", path: knowledge/dev/architecture/layer3-information-law.md.
| # | Quy tắc | Câu hỏi (exact from Điều 21 §III) | Hướng | Nguồn PG | IU pilot |
|---|---|---|---|---|---|
| 1 | IDENTITY | "Tôi là ai?" | — | Registry row | ✅ |
| 2 | BELONGS_TO | "Tôi thuộc về ai?" | ↑ | FK M2O | ✅ partial |
| 3 | CONTAINS | "Tôi chứa gì?" | ↓ | reverse FK O2M | ✅ partial |
| 4 | DEPENDS_ON | "Tôi cần gì để hoạt động?" | → | entity_dependencies source | ❌ deferred |
| 5 | USED_BY | "Ai đang dùng tôi?" | ← | entity_dependencies target | ❌ deferred |
| 6 | TRANSITIVE | "Ai liên quan qua trung gian?" | →→→ | BFS depth ≤ 3 | ❌ deferred |
| 7 | PEERS | "Ai giống tôi?" | ↔ | Same classification query | ❌ deferred |
| 8 | SIMILAR | "Ai liên quan ngữ nghĩa?" | ~ | Qdrant vector | ❌ deferred |
G. Pivot model — PG-first, Nuxt renders only
Old registries/counting = reference/draft where incomplete. Operating path = PG-first Pivot: pivot_definitions, pivot_count(), metadata rows. Nuxt renders only. Không Nuxt business counting.
H. Birth model
IU birth chain
fn_iu_create → trg_birth_information_unit → fn_birth_registry_auto()
→ species_collection_map → SPE-IUA → atom → birth_registry
unit_version policy
Current P3D IU policy: unit_version behaves as subordinate/hạ-nguyên-tử-like artifact for birth/species purposes (no birth trigger, subordinate via FK). Not a universal law.
I–J. IU/TAC impact + Vector/Event/UI
5C2 rev2 preserves Identity heading. Hooks for all other headings ready. Deferred items = Pack 2+. Vector/event/UI = deferred pipelines.
K. Runtime gap matrix
| Concept | Status | TAC UI dep | Preserve | Cutover now |
|---|---|---|---|---|
| information_unit table | VERIFIED_LIVE | None | true | false |
| unit_version table | VERIFIED_LIVE | None | true | false |
| fn_iu_create | VERIFIED_LIVE | None | true | false |
| fn_iu_birth_gate_layer1 | VERIFIED_LIVE | None | true | false |
| birth_registry trigger (IU) | VERIFIED_LIVE | None | true | false |
| species_collection_map (IU) | VERIFIED_LIVE | None | true | false |
| vocab.publication_authority | VERIFIED_LIVE | None | true | false |
| tac_publication | VERIFIED_LIVE | Yes — feeds UI | true | false |
| tac_logical_unit | VERIFIED_LIVE | Yes — feeds UI | true | false |
| tac_unit_version | VERIFIED_LIVE | Yes — feeds UI | true | false |
| tac_publication_member | VERIFIED_LIVE | Yes — feeds UI | true | false |
| Nuxt Laws Page | UNKNOWN — pending baseline | Yes — renders TAC | true | false |
| universal_edges (IU) | DESIGNED_ONLY | None | true | false |
| entity_dependencies (IU) | DESIGNED_ONLY | None | true | false |
| entity_labels (IU) | DESIGNED_ONLY | None | true | false |
| pivot_definitions (IU) | MISSING | None | true | false |
| Qdrant IU chunks | MISSING | None | true | false |
L. Anti-hardcode checklist (binding)
□ Column names qua concept registry, live-verified
□ Counts live-derived
□ Species/composition từ mapping table
□ Vocab từ dot_config lookup
□ Rollback bằng captured keys
□ Không CASE/IF/SWITCH theo species/lớp/layer
□ Không enumerate species list
□ Không Nuxt business counting
□ JSONB extend bằng merge
□ Birth verification 4 tầng
□ Advisory lock, verify-before-commit, VPS log
□ TAC source tables NEVER written
□ Không hardcode table/column names trong executable
□ Không hardcode số lớp, số loài, species list
M. Sequence tiếp theo
1. GPT review v3 design ← HIỆN TẠI
2. GPT chốt contract nền
3. TAC→UI baseline read-only check (REQUIRED before 5C2)
4. GPT review baseline report
5. Opus patch 5C2 rev3
6. GPT review 5C2 rev3
7. User GO → Agent dispatch 5C2 (parallel pilot)
8. Post-pilot: render fidelity comparison
9. If fidelity proven: UI cutover pack (separate)
10. Đ32 + Đ28 migration
TAC→UI baseline check (step 3) is a migration safety prerequisite, not optional.
N. Conclusion
5C2 may resume as a parallel IU pilot that does not affect current TAC→UI runtime, after: (1) v3 design approved, (2) TAC→UI baseline check PASS. UI cutover remains a separate future pack after fidelity verification. A targeted preflight/inventory remains allowed if GPT identifies additional assumptions.
O. TAC→UI runtime preservation contract
O.1 Current path
P10D-2B implementation exists at commit 5ce3437 on nuxt-repo main branch. Production deploy status remains UNKNOWN until targeted baseline verification. P10D-2B report notes: "New page will materialize on next CI deploy."
Data flow (when deployed): Nuxt → Directus SDK → tac_* tables → buildDocsTree() → DocsTreeView + markdownToHtml.
O.2 Tables feeding UI
| Table | Fields | Purpose |
|---|---|---|
| tac_publication | id, doc_code, version, name, lifecycle_status | Listing + header |
| tac_publication_member | publication_id, unit_version_id, render_order | Tree order + content |
| tac_logical_unit | id, parent_id, sort_order, canonical_address | Tree structure |
| tac_unit_version | id, title, body | Display content |
O.3–O.5 Preserve / Forbidden
PRESERVE: 3 publications render, tree view, scroll sync, generic renderer, no branching
FORBIDDEN: schema change to tac_*, readItems query change, IU data in tree, permission change, data archive
REDIRECT: NOT in pilot. Separate pack after fidelity proof.
O.6 Evidence
| Evidence | Status |
|---|---|
| P10D design brief v0.2 | VERIFIED (KB doc) |
| P10D-2B implementation report | VERIFIED (KB doc) |
| Commit 5ce3437 | VERIFIED (git) |
| 3 publications TAC data | VERIFIED_LIVE (probe) |
| Production deploy of Laws Page | UNKNOWN — requires baseline check |
| Visual rendering | UNKNOWN — requires baseline check |
O.7 Required baseline check
P3D_PACK1_TAC_UI_BASELINE_READONLY_CHECK is required before 5C2 migration. See prompt: prompts/p3d-pack1-tac-ui-baseline-readonly-check-prompt-DRAFT.md.
P3D Multidimensional Entity DB Architecture Design v3 | 2026-05-12