P8 Implementation Design Plan v0.4 OFFICIAL
P8 — Implementation Design Plan v0.4
Loại: Implementation design — Điều 38 Text as Code Phase: P8 (Production Design) Trạng thái: OFFICIAL v0.4 — v0.3 + E-E3 amendment (§5 expanded). GPT PASS. Ngày: 2026-04-27 | Phiên: S182 (v0.3) → S183 (v0.4 E-E3) Agent soạn: Opus 4.6 (Desktop) GPT review: v0.3 OFFICIAL + E-E3 PASS (4 minor patches)
0. Executive Summary
P7 sandbox chứng minh schema hoạt động. P8 thiết kế dây chuyền production. P8 chỉ thiết kế. Không production DDL/DML. Không P9.
Operating model: User duyệt mục tiêu P8. Opus điều hành. GPT giám sát. Escalate về User khi: đổi mục tiêu, đụng production, rủi ro/luật/governance lớn.
1. Production Schema Hardening
1.1 CHECK enum → FK vocab
| Field | Sandbox | Production | Lý do |
|---|---|---|---|
| lu.lifecycle_status | CHECK (3) | FK → tac_lu_lifecycle_vocab |
Governance mở rộng |
| uv.lifecycle_status | CHECK (4) | FK → tac_uv_lifecycle_vocab |
Governance mở rộng |
| uv.review_state | CHECK (5) | FK → tac_review_state_vocab |
Review process evolve |
| pub.lifecycle_status | CHECK (4) | FK → tac_pub_lifecycle_vocab |
Governance mở rộng |
| cs.lifecycle_status | CHECK (7) | FK → tac_cs_lifecycle_vocab |
Workflow mở rộng |
| uv.length_flag | CHECK (3) | Giữ CHECK | Cố định technical |
| uv.vector_sync_status | CHECK (4) | Giữ CHECK — P5 enum hiện hành. Cần skip → amend P5 trước. |
Cố định technical |
5 new lifecycle vocab tables + 1 config table:
tac_lu_lifecycle_vocab (code PK, name, description, sort_order)
tac_uv_lifecycle_vocab (code PK, name, description, sort_order)
tac_review_state_vocab (code PK, name, description, sort_order)
tac_pub_lifecycle_vocab (code PK, name, description, sort_order)
tac_cs_lifecycle_vocab (code PK, name, description, sort_order)
tac_birth_gate_config (checker_id PK, mode TEXT DEFAULT 'block', enabled BOOLEAN DEFAULT TRUE)
tac_birth_gate_config: Per-checker config cho birth gate tiered enforcement (§2.3). NT4: mode stored in PG table, not hardcoded in trigger.
1.2 Constraint/index production
CHECK (sort_order >= 0), partial index WHERE lifecycle_status='enacted', GIN indexes on JSONB profiles.
1.3 Schema placement
public schema (Đ33 §0.1). Prefix tac_. Directus quản lý collections.
1.4 Production table summary
| # | Table | Type |
|---|---|---|
| 1–5 | tac_*_lifecycle_vocab (5) | Vocab FK targets |
| 6 | tac_section_type_vocab | Vocab FK target |
| 7 | tac_publication_type_vocab | Vocab FK target |
| 8 | tac_birth_gate_config | Config |
| 9 | tac_logical_unit | Core |
| 10 | tac_unit_version | Core |
| 11 | tac_publication | Core |
| 12 | tac_publication_member | Core |
| 13 | tac_change_set | Hook |
| 14 | tac_change_set_member | Hook |
14 tables total.
2. AI/Agent Write-path Design
2.1 Gateway
Directus REST API (Đ33 §0.1). E1 exception for DDL bootstrap (DOT-TAC-SCHEMA-ENSURE).
2.2 Write operations
| Operation | Gateway | Gate | Approval |
|---|---|---|---|
| Create logical_unit | Directus API POST | Birth gate (§2.3) | Auto nếu BG PASS |
| Create unit_version (draft) | Directus API POST | Birth gate (§2.3) | Auto nếu BG PASS |
| Transition draft→enacted | Directus API PATCH | Pre-enactment full | CS + APR (Đ32) |
| Create publication | Directus API POST | Minimal | Auto |
| Enact publication | Directus API PATCH | Pre-enact full | CS + APR + Council |
| Add publication_member | Directus API POST | PM consistency | Auto nếu pub=proposed |
| Create/submit change_set | Directus API | APR for submit | APR pending |
2.3 Birth gate — tiered enforcement
| Category | Checks | Mode | Rationale |
|---|---|---|---|
| Hard invariants | BG-LU-01→05, BG-LU-06, BG-UV-01 | BLOCK | Structural, no exception |
| Required profile | BG-UV-04 (required per section_type) | BLOCK | Structural requirement |
| Enrichment quality | BG-UV-04 (optional fields) | WARN | Quality, can grace |
| Other quality | BG-UV-02, BG-UV-03, BG-UV-05, BG-UV-06 | WARN default, BLOCK per config | Metadata quality |
Trigger reads tac_birth_gate_config + tac_section_type_vocab.
2.4 Content hash
fn_tac_uv_compute_derived() trigger BEFORE INSERT OR UPDATE.
2.5 Agent identity + Directus permissions
| Role | Scope | Creation | Usage |
|---|---|---|---|
tac-agent |
CRUD tac_* only | DOT-TAC-ROLE-ENSURE (API) | Daily ops |
tac-admin |
Full tac_* + DDL | DOT-TAC-ROLE-ENSURE (API) | Bootstrap + emergency |
DOT-driven. Manual = fallback only. Token via GSM.
3. 100% DOT Governance
3.1 Policy
100% DOT. Thiếu → thiết kế. UI = view/report only.
3.2 DOT registry (19 DOTs: 8 Cấp B + 11 Cấp A)
| DOT code | Tier | Paired | Trigger |
|---|---|---|---|
| DOT-TAC-SCHEMA-ENSURE | B | DOT-TAC-SCHEMA-VERIFY | on-deploy |
| DOT-TAC-SCHEMA-VERIFY | A | — | on-deploy + daily |
| DOT-TAC-COLLECTION-REGISTER | B | DOT-TAC-COLLECTION-VERIFY | on-deploy |
| DOT-TAC-COLLECTION-VERIFY | A | — | daily |
| DOT-TAC-ROLE-ENSURE | B | DOT-TAC-ROLE-VERIFY | on-deploy |
| DOT-TAC-ROLE-VERIFY | A | — | daily |
| DOT-TAC-BIRTH-GATE | B | DOT-TAC-BIRTH-VERIFY | event |
| DOT-TAC-BIRTH-VERIFY | A | — | daily |
| DOT-TAC-SEGMENTER | B | DOT-TAC-SEG-VERIFY | on-demand |
| DOT-TAC-SEG-VERIFY | A | — | daily |
| DOT-TAC-DAILY-INVARIANT | A | — | cron daily |
| DOT-TAC-ENACT-GATE | A | — | event |
| DOT-TAC-HASH-DRIFT | A | — | cron weekly |
| DOT-TAC-VECTOR-SYNC | B | DOT-TAC-VECTOR-VERIFY | cron (if enabled) |
| DOT-TAC-VECTOR-VERIFY | A | — | cron (if enabled) |
| DOT-TAC-LABEL-SYNC | B | DOT-TAC-LABEL-VERIFY | on-demand + cron |
| DOT-TAC-LABEL-VERIFY | A | — | cron daily |
| DOT-TAC-LABEL-FACET-VERIFY | A | — | on-demand (pre-P9) |
| DOT-TAC-LABEL-FORMAT-VERIFY | A | — | on-demand (pre-P9) |
3.3 dot_tools registration
Via dot-dot-register (Đ35 §5). Không ghi tay. Adapter = OD-P8-07.
3.4 Cron schedule
| DOT | Schedule |
|---|---|
| DOT-TAC-DAILY-INVARIANT | 0 3 * * * |
| DOT-TAC-HASH-DRIFT | 0 4 * * 0 |
| DOT-TAC-BIRTH-VERIFY | 0 6 * * * |
| DOT-TAC-SCHEMA-VERIFY | 0 7 * * * |
| DOT-TAC-COLLECTION-VERIFY | 30 7 * * * |
| DOT-TAC-ROLE-VERIFY | 45 7 * * * |
| DOT-TAC-SEG-VERIFY | 0 8 * * * |
| DOT-TAC-LABEL-VERIFY | 0 9 * * * |
| DOT-TAC-VECTOR-SYNC/VERIFY | if enabled |
4. P6 Checker Implementation
Birth gate hard = PG trigger BLOCK. Quality = WARN (config). Pre-enact = transition function. Daily = DOT cron → system_issues (verify schema pre-P9, adapter nếu cần). Self-healing: A detects, B fixes draft, enacted = escalate + APR.
5. Đ24 Label Integration (amended E-E3, S183)
5.1 Facet alias mapping
Trong design docs (P5, P6, C1A, etc.), doc, topic, layer là alias thiết kế, KHÔNG phải facet code production.
| Design alias | Candidate production code | Candidate name | Status |
|---|---|---|---|
| doc | FAC-07 | Thuộc tài liệu nào? | Candidate — chờ APR |
| topic | FAC-08 | Chủ đề nội dung? | Candidate — chờ APR |
| layer | FAC-09 | Tầng kiến trúc? | Candidate — chờ APR |
Rules:
- FAC-07/08/09 là candidate codes theo naming pattern hiện có (FAC-01→FAC-06, FAC-PROV). APR (Đ32) có quyền approve/modify/reject.
- No APR = no facet creation. Không seed trực tiếp.
- Production code/facet identity sẽ là kết quả APR. APR có thể đổi code, tên, scope hoặc reject toàn bộ.
- Design docs tiếp tục dùng alias
doc/topic/layerđể đọc dễ, nhưng code production tham chiếu facet_id FK → taxonomy_facets.
5.2 Entity code contract — D38 local
Scope: Contract này chỉ áp dụng cho D38 Text as Code domain. KHÔNG phải global Đ24 standard. Mỗi domain tự chốt entity_code convention riêng.
Contract:
entity_code=tac_logical_unit.canonical_address(verbatim, không transform)- Regex:
^D38-[A-Z0-9]+-((ROOT)|(S[0-9]+(-P[0-9]+(-[0-9]+)*)?))$ - Character set: uppercase alphanumeric + hyphen
- Length: 10–30 chars
- UNIQUE: enforced by
tac_logical_unit.canonical_addressconstraint - Prefix:
D38-
Coverage: Verified by P7A pilot (76 units) and C2B seed verification. Exact counts in reports/c2b-seed-verification-report-2026-04-27.md. All 76 units match regex.
| Pattern | Example |
|---|---|
| D38-{DOC}-ROOT | D38-HOWTO-ROOT |
| D38-{DOC}-S{n} | D38-C1A-S4 |
| D38-{DOC}-S{n}-P{n} | D38-C1A-S4-P1 |
| D38-{DOC}-S{n}-P{n}-{n} | (future deep nesting, not yet used) |
5.3 DOT verification (pre-P9)
| DOT | Check | Phải PASS pre-P9 |
|---|---|---|
| DOT-TAC-LABEL-FACET-VERIFY | taxonomy_facets chứa facets theo APR outcome | ✅ |
| DOT-TAC-LABEL-FORMAT-VERIFY | canonical_address khớp regex §5.2 | ✅ |
Flow khi facet thiếu:
DOT-TAC-LABEL-FACET-VERIFY detect missing
→ fn_tac_log_checker_issue('DOT-TAC-LABEL-FACET-VERIFY', 'ERROR', ...)
→ APR request tạo qua approved DOT/API path (không manual)
request_type='create_taxonomy_facet'
→ User/Council approve/modify/reject
→ If approved → DOT-TAC-LABEL-SYNC creates via Directus API
→ Re-verify
APR request cũng phải tạo qua governed DOT/API path, không tạo tay. DOT-first principle áp dụng cho cả governance flow.
5.4 Label storage
Labels ONLY in entity_labels table (CI-9, Đ24 standard). Không embed labels trong tac_* tables.
5.5 Checker adapter
public.fn_tac_log_checker_issue (created E-R3, S183) wraps fn_log_issue với:
- Severity mapping: P6 BLOCK/ERROR→critical, WARN→warning, INFO→info
- Dedup:
coalesce_key = md5(lower(checker_id) || '|' || entity_code || '|' || issue_signature) - Escalation: severity chỉ tăng, không giảm
- Evidence:
reports/p9-e-r3-execution-log-2026-04-27.md
Function đã tồn tại trên production. Tuy nhiên, usage bởi các checker/DOT cụ thể yêu cầu DOT đó phải được registered và approved theo Đ35 trước khi gọi function. Function sẵn sàng ≠ DOT được phép chạy.
6. Qdrant/KG
Deferred post-P9 core. DOTs designed not enabled.
7. Component/BOM
Default DEFER khỏi P9. Include only nếu explicit approve.
8. Migration/Rollback
8.1 Steps
10 steps: vocab+config → core tables → functions/triggers → Directus collections (DOT-driven) → roles (DOT-driven) → DOTs (dot-dot-register) → seed (Directus API) → crons → verify.
8.2 Seed source authority
KB OFFICIAL snapshot + SHA-256 + change-set/APR. Sandbox = evidence, NOT SoT. Direct sandbox data reuse needs explicit approve + hash verify.
8.3 Rollback
Steps 1–4 atomic. Post-seed: DROP CASCADE + DOT-driven Directus cleanup.
9. Đ33 Compliance
E1 DDL, Directus API DML, DOT-driven roles, GSM password, DOT-driven collection registration, dot-dot-register for dot_tools.
10. P8→P9 Gate
P8 PASS: all consistent, constitutional, GPT, 19 DOTs paired, migration reviewed, birth gate tiered, seed authority documented.
P9 entry: P8 OFFICIAL + facets verified + format verified + DOTs registered + dry-run PASS + system_issues verified + roles created + backup + TRIGGER-GUARD + User explicit approval + Component/BOM default defer.
11. Constitutional Check
All PASS: NT1/2/4/8/11/13, Đ24/32/33/35, P5/P5b/P6, LSL-01/L4/L5.
12. Open Decisions
OD-P8-01 tac_* prefix, OD-P8-02 Directus API endpoints, OD-P8-03 Component/BOM defer (default), OD-P8-04 Qdrant timing, OD-P8-05 cs_lifecycle values, OD-P8-06 WARN→BLOCK timeline, OD-P8-07 dot-dot-register adapter.
13. Not Authorized
Production DDL/DML ❌. P9 ❌. Directus collections ❌. Sandbox mod ❌. dot_tools registration ❌. Qdrant ❌.
Patch log
v0.1→v0.2: 12 patches (GPT R1)
v0.2→v0.3: 8 patches (GPT R2)
v0.3 OFFICIAL: 1 editorial (cron 0 7 30 → 30 7)
v0.3→v0.4: E-E3 amendment (§5 expanded, 4 GPT patches)
| # | GPT patch | Fix |
|---|---|---|
| 1 | §5.1 APR scope | ✅ "Production code/facet identity sẽ là kết quả APR" + APR có thể đổi code/tên/scope/reject |
| 2 | §5.3 APR via DOT/API | ✅ APR request phải tạo qua governed DOT/API path, không manual |
| 3 | §5.5 function ≠ DOT approved | ✅ Function sẵn sàng ≠ DOT được phép chạy; DOT phải registered/approved |
| 4 | §5.2 approximate numbers | ✅ Bỏ ~30/~40; reference to reports + "all 76 match" |
P8 v0.4 OFFICIAL | S182→S183 | 2026-04-27 | Opus 4.6 v0.3 GPT FINAL PASS + E-E3 amendment GPT PASS (4 patches)