Đề bài cải tiến — Tái cấu trúc hệ thống theo Ma trận lắp ráp

Trạng thái: DRAFT — tài liệu đề bài nền để định hướng triển khai.
Vị trí: knowledge/dev/laws-new/de-bai-cai-tien.md
Mục tiêu: làm rõ hướng tái cấu trúc để hệ thống có thể triển khai nhỏ hơn, cô lập hơn, nhanh hơn, ít rủi ro hơn.
Đọc kèm (cùng thư mục, track Ma trận): matrix-refactor-implementation-plan.md · matrix-refactor-quick-rules.md · matrix-stamp-governance-addendum.md · required-stamps.v0.1.json · promote-checker-v0.1-spec.md

I. Tại sao phải tái cấu trúc?

Cấu trúc hiện tại chưa quá lớn nhưng triển khai đã rất vất vả, vì nhiều thành phần đang bị dính thành một khối. Mỗi lần sửa hoặc thêm tính năng đều phải rà soát quá rộng, không khả thi để scale.
Định hướng ban đầu của hệ thống là lắp ráp theo tầng, từ nguyên tử đến công trình. Hệ đã có nền 6 tầng:
- nguyên tử;
- phân tử;
- hợp chất;
- vật liệu;
- thành phẩm;
- hệ con / công trình.
Hệ cũng đã có tư duy loài/species, nhưng tư duy này chưa được triển khai triệt để vào cấu trúc vận hành.
Mục tiêu tái cấu trúc là biến hệ thống từ “một khối khó sửa” thành “các ô nhỏ có thể lắp ráp”, để mỗi phần mới có thể được triển khai cô lập, kiểm thử nhanh, sai thì xóa, đúng thì promote vào kho chính.

II. Cách cấu trúc mới

1. Xác định ít đối tượng nền

Hệ thống mới chỉ nên xoay quanh một số đối tượng cơ bản:

Nguyên tử / viên gạch nền: đơn vị nhỏ nhất có thể dùng để lắp các tầng trên. Trong hệ tri thức, miếng thông tin là “viên gạch thông minh” để xây lên tài liệu, luật, quy trình, công thức và tri thức vận hành.
Loài / species: nhóm đối tượng cùng bản chất, cùng cách quản lý.
Kho / collection: nơi lưu đối tượng theo tầng, loài và trạng thái.
Công thức / khuôn / quy trình: mô tả cách lắp một đối tượng từ các đầu vào trực tiếp.
Máy lắp / DOT / khung chạy: công cụ thực thi, kiểm tra, promote hoặc rollback.
IO Contract: hợp đồng vào/ra tối thiểu giữa các ô lắp ráp.
Governance: lớp kiểm soát quan hệ, quyền, trạng thái, promote và an toàn hệ thống.

2. Dùng ma trận để chia nhỏ hệ thống

Ma trận lõi dùng để định vị mọi việc:

Tầng × Loài × Kho × Miền chuyên môn

Trong mỗi ô sẽ gắn thêm:

Công thức + DOT + Governance state + IO Contract

Không đưa quan hệ, task, người thực hiện hoặc “năng lực / điều kiện đáp ứng” thành chiều lõi. Các yếu tố đó chỉ là thuộc tính, overlay hoặc lớp graph bên ngoài.

3. Lắp ráp theo tầng

Nguyên tắc:

Tầng trên được lắp từ thành phẩm hoặc vật liệu của tầng dưới.

Mỗi mục tiêu phải được hiểu thành:

Mục tiêu = nguyên liệu đầu vào + công thức + kho + máy lắp

Mỗi tầng cần có:

kho tạm;
kho chính;
công thức của tầng đó;
DOT / máy lắp của tầng đó;
validator;
quy tắc promote;
rollback / xóa bỏ.

Công thức tầng nào chỉ xử lý nguyên liệu trực tiếp của tầng đó, không nhảy xuống quản toàn bộ tầng dưới.

4. Kho tạm là chìa khóa tăng tốc

Phần lớn việc mới phải được làm trong kho tạm:

mở ô tạm → lắp thử → kiểm nhanh → sai thì xóa → đúng thì promote

Không được ghi thẳng vào kho chính.

Kho chính chỉ nhận kết quả thông qua quy trình promote.

5. Governance chia thành 3 mức

Mức 1 — Workspace / kho tạm

Dành cho thử nghiệm, lắp ráp, tạo candidate.

Kiểm nhẹ.
Sai thì xóa.
Không ghi canonical.
Không sửa lõi hệ thống.
Không sửa công thức / kho / loài canonical.

Mức 2 — Promotion / đưa vào kho chính

Dành cho kết quả đã lắp xong, muốn đưa vào kho chính.

Chỉ kiểm cục bộ:

đúng ô chưa;
đúng input chưa;
đúng schema chưa;
DOT kiểm pass chưa;
relation bắt buộc đủ chưa;
rollback có chưa;
owner / scope có rõ chưa.

Mức 3 — Canonical / Kernel Governance

Dành cho việc nguy hiểm:

sửa khai sinh;
sửa kernel;
tạo tầng / loài / collection canonical mới;
sửa công thức canonical;
sửa owner / scope;
sửa production gate;
sửa approval / audit / rollback rule.

Mức này vẫn dùng kiểm soát chặt như hiện tại.

III. Quy định cách làm cụ thể

Mọi việc mới phải được đặt vào một ô ma trận trước khi triển khai.
Không tạo module / lane / registry mới nếu việc đó có thể biểu diễn bằng:
- tầng;
- loài;
- kho;
- miền chuyên môn;
- công thức;
- DOT;
- IO Contract.
Mặc định mọi triển khai mới đi vào kho tạm.
Chỉ khi promote vào kho chính mới kiểm chặt.
Sai trong kho tạm thì xóa kho tạm hoặc xóa phần triển khai, không kéo toàn hệ vào sửa.
Mỗi ô phải có IO Contract tối thiểu:
- nhận gì;
- trả gì;
- schema tối thiểu;
- DOT kiểm;
- rollback / xóa thế nào.
Mỗi tầng phải chuẩn hóa:
- danh mục kho;
- công thức;
- DOT lắp;
- DOT kiểm;
- DOT promote;
- quy tắc rollback.
Quan hệ không phải chiều ma trận. Quan hệ là graph riêng để trả lời:
- tôi thuộc ai;
- ai thuộc tôi;
- tôi dùng ai;
- ai dùng tôi;
- tôi được tạo bởi công thức nào;
- tôi do DOT nào kiểm;
- tôi nằm ở kho nào;
- tôi governed_by ai.
Miếng thông tin là viên gạch thông minh của hệ tri thức. Nó là nguyên liệu nền để xây tài liệu, luật, quy trình, công thức, knowledge graph và các lớp thông tin cao hơn.

IV. Bổ sung: Cách tiếp cận mới về Khai sinh và Đóng dấu kiểm soát

1. Lý do phải đơn giản hóa khai sinh

Cách tiếp cận cũ có xu hướng dồn quá nhiều việc vào khai sinh: vừa cấp căn cước, vừa quét toàn hệ, vừa gắn governance, vừa xác định quan hệ, DOT, collection, owner, promote. Cách này nghe hợp lý về mặt lý thuyết nhưng khi triển khai thực tế trở nên quá nặng, dễ hardcode, sửa nhiều vòng vẫn chưa ổn định.

Cách tiếp cận mới cần tách rõ:

Khai sinh không gánh toàn bộ governance.
Khai sinh chỉ cấp căn cước tối thiểu.
Các lớp kiểm soát khác được đóng dấu dần bởi DOT chuyên trách.

Mục tiêu là làm hệ thống đơn giản hơn, dễ triển khai song song hơn, và không bắt một P0 phải hoàn hảo trước khi toàn hệ có thể vận hành.

2. Khai sinh tối thiểu

Khai sinh chỉ cần trả lời các câu hỏi nền:

Tôi là ai?
Tôi thuộc tầng nào?
Tôi thuộc loài nào?
Tôi nằm ở kho nào?
Tôi thuộc miền chuyên môn nào?
Tôi là workspace, candidate hay canonical?
Ai tạo tôi?
Tạo lúc nào?

Như vậy, khai sinh cấp cho object một căn cước tối thiểu để hệ thống biết nó tồn tại và có thể quản lý tiếp.

Không đưa vào khai sinh P0:

full governance;
full owner / scope;
full relation graph;
full DOT mapping;
full approval / quorum;
full promotion;
full knowledge graph.

Những phần này được xử lý bằng cơ chế đóng dấu sau khai sinh.

3. Cơ chế đóng dấu kiểm soát

Sau khi một object có căn cước tối thiểu, các DOT hoặc checker chuyên trách sẽ lần lượt đóng dấu cho nó.

Các dấu kiểm soát v0.1 nên giữ ít và ổn định:

BIRTH_STAMP       đã có căn cước tối thiểu
CELL_STAMP        đã map được vào ô ma trận: tầng × loài × kho × miền
IO_STAMP          đã có IO Contract tối thiểu
VALIDATION_STAMP  đã được DOT kiểm pass
ROLLBACK_STAMP    đã có cách xóa hoặc rollback
PROMOTE_STAMP     đủ điều kiện đưa vào kho chính

Các dấu nâng cao như owner, relation, governance, DOT chi tiết có thể bổ sung ở phase sau hoặc chỉ bắt buộc với vùng rủi ro cao.

4. Object chưa có dấu thì xử lý thế nào?

Object chưa đủ dấu không làm hệ thống vỡ.

Nó được đưa vào một trong các trạng thái:

UNSTAMPED
MISSING_STAMP
ORPHAN
QUARANTINE
PROMOTE_BLOCKED

Tức là hệ thống không cần cố sửa ngay mọi thứ. Trước hết chỉ cần liệt kê, cảnh báo, phân loại, rồi xử lý dần.

Cách tiếp cận mới là:

Không cố quét và hiểu toàn hệ ngay từ đầu.
Chỉ quản lý chặt cái đã khai sinh và đã đóng dấu.
Phần còn lại được scanner liệt kê để xử lý tiếp.

5. DOT đóng dấu từng phần

Mỗi DOT chỉ làm một việc nhỏ:

DOT khai sinh       → đóng BIRTH_STAMP
DOT cell mapping    → đóng CELL_STAMP
DOT IO contract     → đóng IO_STAMP
DOT validation      → đóng VALIDATION_STAMP
DOT rollback        → đóng ROLLBACK_STAMP
DOT promote         → đóng PROMOTE_STAMP

Không DOT nào phải hiểu toàn bộ hệ thống. Nhờ đó các phần có thể được triển khai song song, dễ kiểm thử và dễ thay thế.

6. Scanner / cơ quan liệt kê phần chưa đủ dấu

Cần có một cơ quan quét đơn giản, nhiệm vụ không phải là sửa toàn bộ hệ thống, mà chỉ liệt kê:

Object nào chưa khai sinh?
Object nào đã khai sinh nhưng chưa map vào ô ma trận?
Object nào có kho nhưng thiếu IO Contract?
Object nào có IO Contract nhưng chưa có DOT kiểm?
Object nào muốn promote nhưng thiếu rollback?
Object nào thiếu dấu bắt buộc?
Object nào nên bị quarantine hoặc chặn promote?

Đây là cơ chế kiểm soát thực tế hơn: cái gì chưa đủ thì hiện ra bảng đỏ, xử lý từng phần, không kéo toàn hệ vào một macro lớn.

7. Quan hệ với kho tạm và kho chính

Trong kho tạm, object có thể chưa đủ dấu. Nó được phép thử, sửa, xóa, làm lại.

Nhưng muốn vào kho chính thì phải đủ dấu bắt buộc.

Luồng chuẩn:

mở kho tạm
→ tạo object với căn cước tối thiểu
→ đóng dấu từng phần
→ thiếu dấu thì cảnh báo hoặc chặn
→ đủ dấu thì promote
→ vào kho chính

Promote phải fail-closed:

Thiếu BIRTH_STAMP      → không promote
Thiếu CELL_STAMP       → không promote
Thiếu IO_STAMP         → không promote
Thiếu VALIDATION_STAMP → không promote
Thiếu ROLLBACK_STAMP   → không promote
Thiếu PROMOTE_STAMP    → không ghi kho chính

8. Điểm khác biệt với cách tiếp cận cũ

Cách cũ:

Quét toàn hệ
→ cố hiểu mọi thứ
→ đưa hết vào khai sinh
→ P0 quá nặng
→ hardcode và sửa mãi không xong

Cách mới:

Khai sinh tối thiểu
→ đóng dấu từng phần
→ cái gì thiếu thì liệt kê
→ xử lý dần
→ chỉ promote khi đủ dấu

Đây là cách phù hợp hơn với mục tiêu tái cấu trúc: chia nhỏ, làm nhanh, sai thì xóa, đúng thì đưa vào kho chính.

9. Nguyên tắc chốt

Khai sinh không phải toàn bộ governance.
Khai sinh chỉ cấp căn cước.
Đóng dấu mới là cách kiểm soát từng phần.
Scanner chỉ liệt kê phần chưa đủ dấu, không làm vỡ hệ.
Kho tạm được phép thiếu dấu.
Kho chính chỉ nhận object đủ dấu bắt buộc.

Cách tiếp cận này giúp hệ thống không chết trên chính sự phức tạp của mình, đồng thời vẫn giữ được nguyên tắc quản lý: cái gì đã vào kho chính phải có căn cước, có ô ma trận, có IO Contract, có DOT kiểm, có rollback và có dấu promote.

10. Hai loại căn cước: workspace/candidate và canonical birth

Phải tách rõ hai loại căn cước để tránh nhầm:

Căn cước tạm (TEMP_ID_STAMP / CANDIDATE_ID_STAMP): object trong kho tạm mang workspace_id hoặc candidate_id. Đây là căn cước để thao tác — đủ để chỉnh, kiểm, xóa, rollback ngay trong kho tạm.
Căn cước chính thức (BIRTH_STAMP): object đã có birth_id / entity_code canonical, chỉ sinh sau khi promote pass (nếu cần).

Ba điều cần nhớ:

Object tạm KHÔNG phải object vô danh — nó có ID tạm để hệ thống quản lý, xóa, rollback.
ID tạm KHÔNG đồng nghĩa với khai sinh canonical.
Khai sinh canonical xảy ra một lần, tại thời điểm promote (thống nhất với "khai sinh khi promote" ở §IV.2 và kế hoạch chính).

kho tạm:   workspace_id / candidate_id   (căn cước tạm — thao tác, xóa, rollback)
promote:   birth_id / entity_code         (căn cước chính thức — canonical birth)

KHÔNG dùng cùng một dấu cho hai nghĩa. TEMP_ID_STAMP (kho tạm) và BIRTH_STAMP (canonical, sau promote) là hai dấu tách biệt.

Vòng đời căn cước:

Trước canonical birth, stamp nằm trong candidate/workspace metadata hoặc staging record — KHÔNG ghi birth_registry canonical trong kho tạm.
Khi promote pass, mới sinh birth_id / entity_code và đóng BIRTH_STAMP + PROMOTE_STAMP.
Checker kiểm preconditions, không yêu cầu output stamp (BIRTH_STAMP/PROMOTE_STAMP) trước khi chạy.
Hai nơi lưu stamp: pre-promote (TEMP_ID/CELL/IO/VALIDATION/ROLLBACK) ở candidate/workspace staging metadata; post-promote (BIRTH/PROMOTE) ở canonical substrate / birth_registry. Pre-promote KHÔNG ghi birth_registry. Chi tiết: addendum §2b.

Câu hỏi "Tôi là workspace, candidate hay canonical?" ở §IV.2 là câu hỏi về trạng thái; mục này làm rõ cơ chế ID đứng sau từng trạng thái.

11. Stamp v0.1 không được mở rộng tùy tiện

Bộ dấu v0.1 chỉ gồm dấu lõi, giữ ít và ổn định:

TEMP_ID_STAMP · BIRTH_STAMP · CELL_STAMP · IO_STAMP · VALIDATION_STAMP · ROLLBACK_STAMP · PROMOTE_STAMP

Ngưỡng đề xuất:

v0.1 không quá 8–10 dấu lõi.
Thêm một dấu bắt buộc mới = thay đổi cấp Canonical/Kernel Governance (Mức 3) — không phải việc của workspace hay promote.
Chỉ khi phát sinh nhu cầu history / evidence / expiry phức tạp mới xét tới stamp ledger hoặc GCOS candidate-state. Không để stamp tự biến thành một registry/quy trình mới.

GOV_STAMP / OWNER_STAMP và các inspector chi tiết hơn (species/collection/relation trong addendum) vẫn nằm dưới trần 8–10 và chỉ bắt buộc ở vùng rủi ro cao — xem §12 và §16.

12. Required stamps phải cấu hình bằng metadata, không hardcode

Tập dấu bắt buộc cho từng cổng (workspace / promote / canonical) phải khai trong metadata, KHÔNG hardcode trong code checker. Đề xuất một file nhỏ:

knowledge/dev/laws-new/required-stamps.v0.1.json

{
  "workspace_required":    ["TEMP_ID_STAMP"],
  "promote_preconditions": ["TEMP_ID_STAMP","CELL_STAMP","IO_STAMP","VALIDATION_STAMP","ROLLBACK_STAMP"],
  "promote_outputs":       ["BIRTH_STAMP","PROMOTE_STAMP"],
  "canonical_required":    ["BIRTH_STAMP","CELL_STAMP","IO_STAMP","VALIDATION_STAMP","ROLLBACK_STAMP","PROMOTE_STAMP"]
}

Checker kiểm preconditions, KHÔNG yêu cầu output stamp (BIRTH_STAMP/PROMOTE_STAMP) trước khi chạy — output chỉ đóng sau khi pass (tránh circular requirement).

GOV_STAMP / OWNER_STAMP chỉ bắt buộc ở vùng canonical/kernel/high-risk — không phải mọi object đều cần GOV/OWNER ở v0.1.

13. Promote checker phải có trước promote lane

Quy tắc cứng: No checker, no lane. Chưa có promote_checker_v0.1 chạy thật (fail-closed, có selftest) thì không được tuyên bố có promote lane. Nếu checker chưa chạy thật, mọi thứ chỉ là giấy.

Promote checker v0.1 tối thiểu phải kiểm:

candidate/workspace object có ID tạm;
cell_id hợp lệ;
IO Contract tồn tại;
đủ dấu preconditions (promote_preconditions trong required-stamps.v0.1.json); KHÔNG yêu cầu output stamp (BIRTH/PROMOTE) trước khi chạy;
validator pass;
rollback tồn tại;
không đụng kernel/canonical rule ngoài scope;
thiếu bất kỳ điều kiện nào → PROMOTE_BLOCKED + lý do.

Checker đọc một candidate packet (binding theo candidate_id + packet_hash), verdict-only — không tự sinh birth, không tự ghi canonical. Việc tạo canonical birth + đóng BIRTH/PROMOTE stamp + consume staging thuộc Atomic Promote Contract (chạy sau checker, trong một transaction; rollback toàn bộ nếu lỗi).

Spec ngắn: promote-checker-v0.1-spec.md (candidate packet §2.1, binding §2.2) · Atomic Promote Contract: addendum §7b.

14. UNKNOWN/PENDING chỉ được phép ở kho tạm

Để matrix không biến thành nghi lễ phân loại:

Nếu chưa chắc tầng/loài/miền, đưa object vào UNKNOWN hoặc PENDING_CLASSIFICATION trong kho tạm.
KHÔNG promote nếu còn UNKNOWN/PENDING (CELL_STAMP chưa đóng được → PROMOTE_BLOCKED).

Điều này giúp việc thử nghiệm không bị kẹt vì tranh luận taxonomy.

15. Miền chuyên môn là tag có kiểm soát

Miền (domain) ở v0.1 chỉ là tag có kiểm soát, không phải ontology lớn. Tối thiểu cần:

domain_code · domain_name · owner · scope · allowed_species

Không tạo domain tree phức tạp ở v0.1. Miền gắn như thuộc tính/jurisdiction (Đ37), không phải máy móc mới.

16. Production/kernel vẫn dùng governance nặng

Hard rule:

Matrix/stamp chỉ tăng tốc ở workspace và promote nội bộ.
Đụng production, kernel, luật enacted, approval, rollback rule, birth gate → vẫn dùng governance nặng như hiện tại (Mức 3 / lane Canonical / Đ32).
KHÔNG dùng Matrix/Stamp để né production/kernel gate.

Tham chiếu: Module Contract First / Federated Registry chỉ còn là tài liệu tham khảo cho cấp canonical/high-risk nếu cần — không dùng làm hướng chính cho mọi object. Cách ưu tiên là IO Contract tối thiểu giữa các ô; không dùng module contract lớn cho việc nhỏ.

17. Scanner chỉ liệt kê, không sửa toàn hệ

Scanner:

chỉ liệt kê thiếu dấu, orphan, promote-blocked;
không tự sửa toàn hệ;
không thay thế promote checker;
không trở thành macro governance mới.

Kết quả scanner là bảng cảnh báo để xử lý từng phần, không phải một macro kiểm toàn hệ.

18. Pilot bắt buộc chứng minh "sai thì xóa được"

Pilot chỉ tính là thành công khi chạy thật được trọn vòng trong kho tạm:

mở kho tạm;
tạo candidate (có ID tạm);
gắn IO Contract tối thiểu;
chạy DOT check;
phát hiện thiếu dấu;
xóa candidate / kho tạm;
rehearsal promote trong staging / dry-run;
không ghi canonical.

Nếu sau 7–10 ngày không có pilot chạy thật → dừng viết thêm giấy.

V. Roadmap triển khai

Bước 1 — Chốt đề bài nền

Soạn và thống nhất tài liệu định hướng tái cấu trúc này.

Sau khi thống nhất, đẩy lên:

knowledge/dev/laws-new/

Bước 2 — Rà lại `laws-new`

Các draft Fable5 đã đẩy lên trước đó cần được phân loại:

phần nào phù hợp với cấu trúc ma trận thì giữ làm tham khảo;
phần nào quá phức tạp, tạo module / contract / lane mới không cần thiết thì loại bỏ hoặc hạ vai trò;
không dùng lại những thiết kế làm hệ phình thêm.

Bước 3 — Cho Claude Code khảo sát tính khả thi

Yêu cầu Claude Code đọc:

tài liệu định hướng mới;
các file hiện có trong laws-new;
Hiến pháp cũ;
bản thiết kế UI tham khảo: constitution-new-index.html;
các thiết kế Governance / GCOS / One-Roof đã có.

Nhiệm vụ:

đánh giá cái gì dùng lại được;
cái gì thiếu;
cái gì đang hardcode;
cái gì cần sửa tối thiểu;
không thiết kế lại từ đầu nếu nền cũ đã có.

Bước 4 — Lập danh mục thiếu cần thực hiện

Danh mục thiếu dự kiến:

hoàn thiện lớp khai sinh đang bị hardcode;
chuẩn hóa danh mục tầng;
chuẩn hóa danh mục loài;
chuẩn hóa kho / collection theo từng tầng;
chuẩn hóa công thức theo tầng;
chuẩn hóa DOT lắp ráp, kiểm, promote, rollback;
chuẩn hóa IO Contract tối thiểu;
chuẩn hóa relation graph / object card;
chuẩn hóa quy trình workspace → promote → canonical.

Bước 5 — Hiệu chỉnh luật cũ

Các luật cũ không bị bỏ. Chúng trở thành nền tham khảo và mục tiêu chuyên môn.

Cách xử lý:

giữ tinh thần đúng;
bỏ phần làm phình hệ;
diễn giải lại theo ma trận lắp ráp;
ưu tiên công thức, kho, DOT, IO Contract, workspace và promote.

Bước 6 — Luật độc lập vẫn triển khai độc lập

Các luật / hệ độc lập như Knowledge Graph vẫn có thể triển khai riêng.