Incomex AI Portal
KB-7E05

[ARCHIVE] Quy định kho tạm LEGO — DRAFT v1 (GPT, trước rà soát SSOT)

9 min read Revision 1
laws-newkho-tamarchivedraft-v1superseded

[ARCHIVE] QUY ĐỊNH KHO TẠM LEGO — DRAFT v1 (bản GPT, TRƯỚC rà soát SSOT)

TRẠNG THÁI ARCHIVE — KHÔNG DÙNG LÀM CĂN CỨ. Đây là bản lưu nguyên văn của quy-dinh-kho-tam.md DRAFT v1 (do GPT soạn), được archive lúc 2026-06-24 ngay trước khi viết lại theo SSOT /laws-new/. Bản v1 này có các lỗi đã được xác nhận: enum tầng sai (atom/molecule/cell/organ/building/system), bỏ qua ma trận Tầng × Loài × Kho × Miền, bỏ qua substrate staging thật đang chạy (iu_core.iu_staging_record/payload, schema sandbox_tac, Điều 41 zones), tự đặt namespace DOT mới dot-lego-sandbox-* mà không reuse-first, thiếu nguyên tắc "No lane before checker", xóa sandbox theo manifest-trust thay vì bằng cấu trúc. Bản chính thức (đang hiệu lực để review) là DRAFT v2 tại knowledge/dev/laws-new/kho-tam/quy-dinh-kho-tam.md. Báo cáo rà soát: knowledge/dev/laws-new/reports/kho-tam-root-doc-ssot-rewrite/.

(Phần dưới là nội dung v1 nguyên văn, giữ nguyên để truy vết.)

QUY ĐỊNH KHO TẠM LEGO

Mã tài liệu: KHO-TAM-LEGO-ROOT-001 Đường dẫn: knowledge/dev/laws-new/kho-tam/quy-dinh-kho-tam.md Trạng thái: DRAFT — CHỜ OWNER DUYỆT Phạm vi: Quy định gốc về khái niệm, tiêu chuẩn kỹ thuật, DOT tạo kho tạm, cách gọi, quy trình chạy thử và xóa kho tạm. Không thuộc phạm vi tài liệu này: Quy trình promote/đồng bộ kết quả từ kho tạm vào kho chính. Nội dung đó phải được viết thành tài liệu độc lập sau.

0. Nguyên tắc điều hành

Kho tạm được tạo ra để phục vụ triết lý LEGO:

Làm thử nhanh, sửa nhanh, xóa nhanh. Đúng thì sau này mới đưa vào kho chính. Sai thì bỏ, không kéo theo rủi ro cho hệ chính.

Vì vậy, kho tạm không được biến thành một quy trình chính thống thu nhỏ với quá nhiều gate promotion, quorum, stamp chain hoặc audit chain nặng. Ngược lại, kho tạm cũng không phải vùng vô luật. Mọi thao tác tạo, chạy, sửa, xóa kho tạm vẫn phải đi qua DOT được quy định.

Nguyên tắc cân bằng:

Staging lane: DOT 100% + auto/light gate + isolation + cleanup + raw evidence.
Official lane: DOT 100% + promotion gate + approval/quorum + registry/catalog chính thức.

Trong kho tạm, ưu tiên tốc độ và khả năng quan sát kết quả thật. Chỉ chặn khi có rủi ro trực tiếp:

  • Đụng hoặc làm thay đổi kho chính.
  • Không xóa/rollback được.
  • Kết quả valid/bad bị false PASS.
  • IO contract bị sai lệch khiến kết quả thử không còn ý nghĩa.
  • Không có bằng chứng tối thiểu để đọc lại.

1. Định nghĩa kho tạm

Kho tạm LEGO là một môi trường chạy thử cô lập, do DOT tạo ra, có hình dạng kỹ thuật đủ giống kho chính ở các điểm quyết định khả năng chạy đúng của một miếng LEGO, nhưng dùng dữ liệu tối thiểu/copy-on-write để thử nhanh và xóa nhanh.

Kho tạm không phải là bản sao đầy đủ dữ liệu production. Kho tạm là bản sao đủ của hình dạng vận hành:

  • Cùng IO contract hoặc compatible IO contract.
  • Cùng schema shape hoặc schema projection cần thiết.
  • Cùng quy tắc lỗi/fail-closed đối với phần đang thử.
  • Cùng giao diện gọi DOT ở mức cần thiết.
  • Cùng cách đọc/ghi artifact trong phạm vi thử.
  • Cùng đường promote dự kiến, nhưng chưa tự promote.

Nói ngắn:

Kho tạm = môi trường thử giống kho chính ở contract và behavior, không nhất thiết giống về toàn bộ dữ liệu.

2. Kho chính là gì?

Trong phạm vi /laws-new, kho chính là hệ chính thức đang được coi là nguồn sự thật vận hành, bao gồm các lớp có thể liên quan:

  • PostgreSQL/Directus official runtime.
  • DOT chính thức trong /opt/incomex/dot/bin/ và registry liên quan.
  • Catalog/registry chính thức như dot_tools, dot_agent_api_contract, table_registry, CAT nếu có.
  • AgentData KB với các tài liệu luật, bằng chứng và báo cáo đã được ghi nhận là SSOT bằng chứng.
  • Các bảng governance/approval/ledger chính thức.

Kho tạm không được ghi trực tiếp vào các thành phần chính thức này, trừ read-only snapshot hoặc thao tác promote sau này đã được quy định riêng.

3. Kho tạm giống kho chính đến mức nào?

Kho tạm phải giống kho chính ở các tiêu chuẩn tối thiểu sau:

3.1 Giống về IO contract

Mỗi miếng LEGO phải chạy trong kho tạm bằng cùng input/output contract dự kiến dùng khi đưa vào kho chính.

Nếu phải dùng contract rút gọn, tài liệu dry-run phải ghi rõ:

  • Contract nào được giữ nguyên.
  • Contract nào đang mock/rút gọn.
  • Vì sao rút gọn không làm sai kết quả kiểm thử.

3.2 Giống về schema shape

Kho tạm cần có schema hoặc bảng/view tương đương với phần mà miếng LEGO chạm tới. Không yêu cầu copy toàn bộ schema nếu miếng đó chỉ cần một projection nhỏ.

Quy tắc:

Thử cái gì thì schema của cái đó phải đủ giống.
Không thử cái gì thì không cần copy.

3.3 Giống về behavior lỗi

Kho tạm phải fail-closed theo cùng logic tối thiểu:

  • Input sai phải bị reject.
  • Bad-case không được được tính PASS nếu sai kỳ vọng.
  • Evidence không được báo PASS nếu valid/bad/cleanup chưa đủ.

3.4 Không cần giống về dữ liệu đầy đủ

Kho tạm nên dùng dữ liệu tối thiểu:

  • Seed nhỏ.
  • Fixture rõ.
  • Copy-on-write nếu cần.
  • Không copy dữ liệu nhạy cảm hoặc dữ liệu production lớn nếu không bắt buộc.

4. Một kho chung hay mỗi lớp một kho?

Không tạo mỗi lớp một cơ chế kho tạm riêng.

Quy định gốc:

Một factory chung tạo kho tạm.
Mỗi lần thử tạo một sandbox riêng theo layer/scope.

Tức là dùng một bộ DOT chung, truyền tham số:

  • --layer atom|molecule|cell|organ|building|system|...
  • --scope C1|C2|...|tên-miếng-lego
  • --purpose "mô tả ngắn"
  • --ttl 24h hoặc giá trị được cho phép.

Lý do không tạo DOT riêng cho mỗi lớp:

  • Tránh mỗi lớp tự chế staging khác nhau.
  • Tránh sinh quái vật kiểm thử.
  • Giữ một chuẩn tạo/xóa/sync kho tạm thống nhất.
  • Khi cần cải thiện an toàn hoặc tốc độ, chỉ sửa factory chung.

5. Kho tạm cố định hay mỗi lần tạo mới?

Dùng mô hình hai tầng:

5.1 Base template cố định

Tên khuyến nghị:

lego_sandbox_base

Base template là bản nền được đồng bộ từ kho chính ở mức schema/contract cần thiết. Base có thể cập nhật khi kho chính đổi.

Base không phải nơi chạy thử trực tiếp.

5.2 Run sandbox tạm thời theo từng lần thử

Mỗi lần thử tạo một sandbox mới từ base.

Tên khuyến nghị:

lego_sandbox_run_<layer>_<scope>_<yyyymmdd_hhmmss>_<shortid>

Ví dụ:

lego_sandbox_run_atom_c1_20260624_153000_a7f2
lego_sandbox_run_building_c1_20260624_154100_b1c9

Run sandbox được dùng để chạy thử, ghi lỗi, sửa, xóa. Không dùng run sandbox lâu dài làm kho chính.

6. Làm thế nào để kho tạm nhẹ nhất?

Kho tạm phải nhẹ theo các nguyên tắc:

  • Tạo từ template hoặc schema projection, không rebuild quá nhiều.
  • Chỉ seed dữ liệu cần cho scope đang thử.
  • Không copy production data nếu không cần.
  • Dùng TTL và cleanup mặc định.
  • Ghi raw evidence tối thiểu đủ đọc lại, không bắt buộc promotion-grade stamp chain.
  • Không tự động tạo registry/catalog chính thức.

Mức nhẹ tối thiểu cho một miếng LEGO:

schema/contract projection + fixture nhỏ + runner + cleanup + raw evidence.

7. Khi kho chính thay đổi thì kho tạm đồng bộ thế nào?

Có DOT đồng bộ base template từ kho chính:

dot-lego-sandbox-sync

Quy trình dự kiến:

  1. Read-only snapshot kho chính.
  2. Xác định schema/contract thay đổi.
  3. Cập nhật lego_sandbox_base hoặc base projection tương ứng.
  4. Ghi manifest sync:
    • source version/hash;
    • schema projection;
    • timestamp;
    • DOT run id;
    • evidence ref.
  5. Các run sandbox mới sau đó clone từ base mới.

Không bắt buộc mỗi lần kho chính đổi phải rebuild mọi sandbox đang chạy. Sandbox đang chạy có thể tiếp tục theo base version cũ, nhưng report phải ghi base version.

8. DOT nào tạo kho tạm?

Quy định bộ DOT gốc như sau.

8.1 DOT factory chính

dot-lego-sandbox-create

Nhiệm vụ:

  • Nhận layer, scope, purpose, ttl, owner/operator.
  • Tạo run sandbox mới từ base hoặc projection.
  • Ghi manifest sandbox.
  • Trả về machine-readable output.

8.2 DOT đồng bộ base

dot-lego-sandbox-sync

8.3 DOT xóa kho tạm

dot-lego-sandbox-drop

8.4 DOT trạng thái kho tạm

dot-lego-sandbox-status

8.5 DOT lập kế hoạch promote

dot-lego-sandbox-promote-plan

9–16

(Các mục 9–16 của bản v1: cách gọi, quy trình tạo, khi nào xóa, khi nào promote, evidence tối thiểu, quan hệ với C1, trạng thái áp dụng, tóm tắt quyết định — đã được thay thế trọn vẹn trong DRAFT v2. Xem v2 để biết nội dung đúng theo SSOT.)

Hết bản archive v1.