dot-iu-cutter v0.5 — WS-1 Design Brief (Relation Edge + Topic Graph + Assembly Contract)

Phase: design-only · 2026-05-18 · Scope: G1+G2+G3+G4+G5 Self-contained. Pseudo-schema chỉ là YAML field list / logical pattern — KHÔNG executable SQL (QG4). Không có CREATE/ALTER/INDEX, không dry-run, không mutation (QG2/§6 forbidden).

Quy ước reference: phần đã chốt chỉ trỏ tới path+section của P44-4A / P11D / P11C / P38-XC / v0.4 Hybrid / v0.5 — KHÔNG viết lại (QG1).

G1 — Assembly Contract

Problem

Hiện mỗi loại "lắp ráp tài liệu" là một pipeline ad-hoc: assembly-by-document (P10D, Nuxt Laws Page — đã chạy thật) và assembly-by-topic (P11D §6 — logical proof). Khi thêm loại mới (theo entity, theo compliance, theo code area, theo report) sẽ phải viết pipeline hardcode từng loại → vi phạm "Assembly First" + "No hardcode".

Existing reference (không redesign)

P11D §6.1 — pipeline 5 bước GATHER→ENRICH→GROUP→QUALITY→PROVENANCE. G1 build on top, không thay thế.
P11D §5 — Q-T1..Q-T5 là các "query primitive" mà assembly profile gọi lại.
v0.5 Label/Metadata — pattern "registry row + resolve runtime, không hardcode" là khuôn cho cách đăng ký profile.

Bổ sung so với P11D: abstract `assembly_profile`

Một bản ghi mô tả "công thức lắp ráp", resolve lúc runtime. Pipeline engine đọc profile và chạy lại 5 bước P11D — KHÔNG có code riêng cho từng loại.

Pseudo-schema (YAML field list, logical only):

assembly_profile:
  profile_id: text            # identity, immutable
  profile_type: text          # resolve qua registry, KHÔNG enum hardcode
  input_selector: jsonb       # cách chọn IU gốc: by topic_code | by source_document_ref | by compliance_requirement | by entity_ref | by code_area
  ordering_rule: jsonb        # thứ tự render; có thể authority-aware (xem G4)
  inclusion_rule: jsonb       # điều kiện thêm IU
  exclusion_rule: jsonb       # điều kiện loại IU (vd retired)
  relation_filter: jsonb      # edge types whitelist khi ENRICH (tham chiếu P11D §5.3.1)
  source_family_filter: jsonb # giới hạn/đánh dấu source family (xem G4)
  render_template: text       # pointer tới template (Directus/Nuxt), KHÔNG phải authority (G5)
  output_format: text         # logical shape, không phải API/UI contract (P11D §6.2)
  provenance_policy: jsonb    # mức trace bắt buộc (gắn P11D §7)
  lifecycle: text             # proposed|active|deprecated
  created_by / created_at

Đăng ký profile mới = thêm row (sovereign-gated ở cycle sau), KHÔNG patch code engine. Profile tham chiếu: relation edges (P44-4A universal_edges), topic (P11D content_profile.topic_labels), source profile (WS-2), metadata key registry (R6) — bằng reference key, không nhúng logic.

3 concrete profile sketches (QG5 — cover ≥3 loại khác nhau)

original_document — input_selector={by: source_document_ref}, ordering=render_order/section_type, relation_filter=contains/belongs_to (Cap-5), output=cây tài liệu gốc. (Tương đương P10D đang chạy, nay được mô tả bằng contract.)
topic_thread — input_selector={by: topic_code}, chạy đúng Q-T1→Q-T5, relation_filter=P11D §5.3.1 whitelist (references, depends_on, compatible_with, contradicts(annotate), implements, supersedes), output=topic view.
compliance_matrix — input_selector={by: compliance_requirement}, ordering=authority-aware (G4: normative→evidence→implementation), relation_filter=implements, governed_by, evidenced_by, output=ma trận "yêu cầu ↔ cái chứng minh đã đáp ứng".

Recommendation

Chốt assembly_profile là logical contract trong WS-1; physical table defer cycle schema-design riêng. Engine = generic executor chạy pipeline P11D theo profile.

Trade-offs / Risks

(+) Hết hardcode pipeline; thêm loại = thêm row. (−) Engine generic phức tạp hơn engine chuyên biệt.
Risk R-G1: profile quá tự do → assembly không deterministic. Mitigate: provenance_policy bắt buộc + output là logical shape (P11D §6.2), không phải API contract.

Ví dụ nôm na

Nhà hàng có một kho nguyên liệu (IU). assembly_profile là các công thức trình bày: "set menu theo món gốc" (original_document), "combo theo chủ đề món chay" (topic_thread), "bảng đối chiếu món nào đạt chuẩn vệ sinh" (compliance_matrix). Bếp không viết lại quy trình bếp cho từng kiểu — chỉ đổi tờ công thức.

G2 — IU ↔ non-IU Entity Binding

Problem

IU cần trỏ tới authority object phi-IU (SQL entity, Directus item, code module, Git commit/file, report, process step, contract, customer, order, invoice) mà không copy toàn bộ data vào IU. SQL/entity vẫn là authority; IU chỉ giữ semantic reference + provenance.

Existing reference

P44-4A §2.1 — endpoint là bất kỳ Object OQC≥3/4, không chỉ information_unit. Nhưng business entity SQL thô (customer_id, invoice) thường KHÔNG phải Object đã đăng ký → universal_edges thuần không phủ.
P44-4A §3.3 — edge type ngoài 11 loại phải qua APR cấp medium.
v0.4 Hybrid §2 — "blob/object pointer": pointer là SQL-authoritative, pointee ở store ngoài.

Options A/B/C/D + trade-off (QG6)

Opt	Mô tả	Pros	Cons
A Extend universal_edges nhận non-IU target	Tái dùng SSOT edge, 1 cơ chế	Phá ngữ nghĩa Object-edge của P44-4A; non-IU không có OQC; risk drift INV-DUAL	Vi phạm "không redesign P44-4A"
B Bảng typed `iu_entity_binding` riêng + minimal `entity_reference_registry`	Tách bạch, audit rõ, scale tốt	Thêm 2 khái niệm; cần đồng bộ với assembly	Trùng một phần ngữ nghĩa edge
C JSONB pointer trong content_profile	Nhanh, không bảng mới	Pointer thành hidden authority (vi phạm P7); không FK/audit ở scale	Không hợp millions, không auditable
D Hybrid: universal_edges giữ Object↔Object (gồm non-IU Object đã đăng ký theo P44-4A); typed `iu_entity_binding` xử lý IU↔raw business entity; assembly contract (G1) tiêu thụ cả hai	Tôn trọng P44-4A nguyên vẹn; binding business entity có audit; G1 đọc được cả hai	Hai đường binding, cần ranh giới rõ ràng

Recommendation: Option D (hybrid)

universal_edges: KHÔNG đổi (reference P44-4A). Object phi-IU đã đăng ký (vd publication, vector_projection) vẫn dùng edge như P44-4A §2.1.
iu_entity_binding: chỉ cho IU ↔ entity thô (customer/contract/invoice/GitHub file/code module) — semantic reference + provenance, KHÔNG copy data.
assembly_profile.input_selector có thể {by: entity_ref} và đọc binding.

Minimal viable registry (QG8 — core 5 field, KHÔNG over-design):

entity_reference_registry:   # core minimal
  entity_ref_id: text        # identity
  entity_kind: text          # resolve registry (vd sql_entity|code_module|git_file|directus_item) — KHÔNG enum hardcode
  source_system: text        # hệ nguồn (PG schema / GitHub repo / Directus)
  natural_key: text          # khoá tự nhiên bên nguồn (vd customer_id)
  authority_note: text       # vì sao nguồn này là authority
# --- deferred fields (logical placeholder, chốt khi có pilot thật) ---
  permission_policy_ref: text   # DEFERRED post-pilot
  snapshot_policy_ref: text     # DEFERRED post-pilot (cho rendered document)

iu_entity_binding:
  binding_id: text
  iu_id: text                 # -> IU identity (UMC U1)
  entity_ref_id: text         # -> entity_reference_registry
  binding_kind: text          # resolve registry: describes|governs|implements|evidences|references_entity
  provenance: jsonb           # who/when/why/source (auditable — ràng buộc bắt buộc)
  created_by / created_at
  retracted_at: timestamptz NULL   # append-only, retract = state mới (theo R6 pattern)

Constraints (giữ nguyên từ đề bài, đã thoả)

SQL/entity = authority; IU giữ reference+provenance không copy; binding auditable who/when/why/source; permission & snapshot là logical placeholder defer; scale millions; KHÔNG full contract lifecycle; KHÔNG executable SQL.

Risks

R-G2a: binding stale khi entity đổi → cần snapshot_policy (defer). Mitigate: binding trỏ natural_key, đọc live từ SSOT lúc assembly.
R-G2b: binding_kind mới có thể trùng ngữ nghĩa edge type P44-4A → flag open decision, không tự tạo.

Ví dụ nôm na

Thẻ khách hàng: miếng ghi chú "khách VIP thích bàn cạnh cửa sổ" chỉ trỏ tới hồ sơ khách hàng thật trong sổ cái (customer_id), không chép cả hồ sơ vào tờ ghi chú. Sổ cái đổi địa chỉ → ghi chú vẫn đúng vì nó trỏ, không copy. Ví dụ kỹ thuật: IU "ghi chú kiến trúc về sync registry" bind tới GitHub file web-test/dot/bin/dot-flow-setup-registry-sync (entity_kind=git_file) thay vì dán nội dung code vào IU.

G3 — Topic Registry Decision

Problem

P11D §3.5 defer topic vocab table sang P44-6, dùng free-text topic_code. Nếu WS-3 pilot topic assembly thật → rủi ro duplicate (birth_gate vs birthgate vs BG, AP-3 P11D §8.1). Cần phân biệt logical registry contract vs physical table creation vs seed governance vs duplicate mitigation vs topic ownership.

Existing reference

P11D §3.1 (4 field bắt buộc), §3.4 (provenance bắt buộc), §3.5 + Q-D3 (free-text + provenance, vocab table defer P44-6), OPEN P11D-α (vocab governance), P11D-δ (alias resolution).

Options

Opt	Mô tả	Pro	Con
A	Tạo physical minimal `topic_vocab` sớm	Hết duplicate ngay	Vi phạm forbidden (schema migration); mâu thuẫn P11D defer
B	Tiếp tục JSONB free-text + duplicate mitigation	Không đụng schema	Duplicate tích luỹ; khó governance
C	Chốt logical topic registry contract NGAY, defer physical table	Có contract để WS-3 bám; không phá P11D defer; không mở migration	Vẫn dùng free-text tới khi physical

Recommendation: Option C

Logical contract: topic phải có topic_code/namespace/status/provenance (P11D §3.1/§3.4 — reference), thêm quy ước ownership (topic_namespace có owner) + duplicate mitigation logic (chuẩn hoá snake_case + alias candidate list ở provenance) — đây là logical, chưa tạo bảng.
Physical topic_vocab chỉ chuyển khi đồng thời: (i) Pilot Tier 1 cần topic assembly thật, (ii) duplicate rate đo được vượt ngưỡng, (iii) APR Đ32 PASS (đúng P11D-α). KHÔNG tự mở schema migration ở phase này.
Phân biệt rõ: logical contract (nay) ≠ physical table (P44-6) ≠ seed governance (APR) ≠ duplicate mitigation (chuẩn hoá + alias, một phần làm được nay ở tầng logical) ≠ ownership (gắn namespace).

Risks

R-G3: free-text kéo dài → duplicate khó dọn về sau. Mitigate: contract bắt buộc snake_case + provenance.source_context ngay từ WS-3, giảm nợ.

Ví dụ nôm na

Sổ tay phân loại kho hàng: thống nhất quy tắc đặt tên ngăn kéo trước ("snake_case, mỗi khu có người phụ trách") — đó là logical contract. Chưa cần đóng tủ gỗ thật (physical table) cho tới khi hàng nhiều và đã duyệt ngân sách (APR).

G4 — Cross-source-family Assembly

Problem

P11D proof chỉ chạy 3 publication cùng một source family. User yêu cầu xâu chủ đề xuyên nhiều loại nguồn authority khác nhau. Không được xếp ngang hàng luật / report / code khi authority khác nhau.

Existing reference

P11D §6 pipeline + Q-T3 ENRICH qua relation edges (build on top, không thay).
P44-4A §3.1/§3.2 edge types; §3.3 — edge mới phải APR medium.

Bổ sung so với P11D

source_family taxonomy (resolve qua registry, KHÔNG hardcode — gắn WS-2): internal_incomex_constitution, internal_incomex_law, internal_process, external_government_law, sql_entity, code_artifact, report, lesson, architecture_note.

authority_semantics (gắn vào assembly, không vào IU core):

normative_authority — thứ có quyền quy định (hiến pháp/luật nội bộ/luật nhà nước)
evidence_authority — thứ chứng minh đã/chưa làm (report, lesson)
implementation_authority — thứ đang chạy thật (SQL schema, code)

ordering_rule per assembly context (giá trị của assembly_profile.ordering_rule): compliance_external_law | internal_architecture | implementation_trace | contract_lifecycle.

Relation types nối cross-family: implements, governed_by (đã có P44-4A core/candidate) + mới: constrains, maps_to_requirement, maps_to_process, maps_to_code, evidenced_by, lesson_from.

⚠️ 6 loại mới chưa có trong P44-4A 11 edge types → phải qua P44-4A §3.3 APR cấp medium trước khi WS-3 dùng. Ghi thành open decision (file 3 OD-FA4), KHÔNG tự tạo (NT4 no-hardcode + §6 forbidden).

design_requirement thoả: assembly profile cross-family gắn authority_semantics cho mỗi IU theo source_family; ordering authority-aware (normative trước, evidence/implementation chú thích rõ "rule nói gì / report chứng minh gì / code đang chạy gì"); KHÔNG xếp ngang hàng nếu authority khác.

Profile sketch: profile_type=cross_source_topic_thread, input_selector={by: topic_code}, source_family_filter=[constitution,law,process,sql_entity,code_artifact,report,lesson], ordering_rule=internal_architecture (authority-aware), relation_filter=[implements,governed_by,constrains,maps_to_*,evidenced_by,lesson_from].

Ví dụ chain — topic = "cấu trúc collection": Hiến pháp nội bộ → Luật nội bộ → Quy trình → Directus/PG schema → Code → Report → Lesson.

Risks

R-G4: dùng edge type mới trước khi APR → vi phạm P44-4A. Mitigate: gate cứng OD-FA4, WS-3 chỉ chạy sau APR PASS.

Ví dụ nôm na

Hồ sơ xây nhà: giấy phép xây dựng (luật — normative, được quyền quy định) ≠ biên bản nghiệm thu (report — evidence, chứng minh đã làm) ≠ căn nhà đang ở (code/schema — implementation, đang chạy thật). Xếp chung một tập hồ sơ theo chủ đề "phần móng", nhưng đánh dấu rõ cái nào ra lệnh, cái nào chứng minh, cái nào thực tế — không coi biên bản nghiệm thu ngang giấy phép.

G5 — Directus Boundary Formal

Problem

Nguyên tắc Directus = UI/assembly, SQL/IU Fabric = authority đã chốt (v0.4 Hybrid §1; GPT Position) nhưng chưa formal hóa → session sau dễ biến Directus thành authority.

Existing reference

v0.4 Hybrid §1 (SQL SSOT, Directus = projection); GPT Position (Directus is UI/form/template assembly; SQL/IU Fabric remains semantic authority). G5 chỉ formal hóa, không tạo nguyên tắc mới.

Boundary formal (logical, binding)

Directus ĐƯỢC: UI/form; inspection; template assembly khi phù hợp; preview; read/write UI vào collection được phép chỉ khi đã có DOT/change package. IU Fabric ĐƯỢC (own): semantic authority; provenance; IU lifecycle; compliance mapping; relation graph; source/version/checksum; assembly contract (G1); audit/governance. Directus template feature: được dùng render hợp đồng/document nếu đọc dữ liệu authoritative từ SQL/IU; KHÔNG được biến Directus thành authority của hợp đồng hay IU. Directus KHÔNG ĐƯỢC: own IU lifecycle; own compliance mapping; own provenance/audit; bypass PG/governance; manual UI config nếu đã yêu cầu DOT-driven. Governance: Directus config changes vẫn DOT/change-package governed; Directus đọc PG/Directus collections; PG remains source of truth.

Risks

R-G5: WS-3 dùng Directus template render → dễ tưởng Directus là authority. Mitigate: assembly_profile.render_template chỉ là pointer; provenance_policy vẫn do IU Fabric giữ.

Ví dụ nôm na

Nhà hàng: bếp (IU Fabric) quyết định công thức và nguyên liệu thật, giữ sổ ghi nguồn gốc. Quầy kính trưng bày (Directus) chỉ bày món cho khách xem và gọi — đẹp, tiện, nhưng không tự đổi công thức và không phải nơi quyết định món gốc.

Tổng kết WS-1

G1 (assembly_profile contract) là xương sống; G2 (binding option D) mở chiều IU↔entity; G3 (option C) chốt topic contract không phá defer; G4 mở cross-source authority-aware (gated APR cho edge mới); G5 formal hóa ranh giới Directus. Tất cả logical/pseudo-schema, không schema/code/dry-run. Open decisions → file 3.

dot-iu-cutter v0.5 — WS-1 Design Brief (Relation Edge + Topic Graph + Assembly Contract)

G1 — Assembly Contract

Problem

Existing reference (không redesign)

Bổ sung so với P11D: abstract assembly_profile

3 concrete profile sketches (QG5 — cover ≥3 loại khác nhau)

Recommendation

Trade-offs / Risks

Ví dụ nôm na

G2 — IU ↔ non-IU Entity Binding

Problem

Existing reference

Options A/B/C/D + trade-off (QG6)

Recommendation: Option D (hybrid)

Constraints (giữ nguyên từ đề bài, đã thoả)

Risks

Ví dụ nôm na

G3 — Topic Registry Decision

Problem

Existing reference

Options

Recommendation: Option C

Risks

Ví dụ nôm na

G4 — Cross-source-family Assembly

Problem

Existing reference

Bổ sung so với P11D

Risks

Ví dụ nôm na

G5 — Directus Boundary Formal

Problem

Existing reference

Boundary formal (logical, binding)

Risks

Ví dụ nôm na

Tổng kết WS-1

Bổ sung so với P11D: abstract `assembly_profile`