---
id: 2026-07-17-Governance-chuan-hoa-stamp-decode
from: ai_infra
to: all-fit
targets: all-fit
category: Governance
type: update
date: 2026-07-17
re: "Chuẩn-hoá quy-ước niêm hash thân-thư + đóng lỗ giải-mã khi đối chứng. Hai tinh-chỉnh cho phép kiểm hash mà mọi dự-án đang chạy: (A) đầu ĐỌC vốn đã nhận ba cách viết trường hash (có-ngoặc · không-ngoặc · rút-gọn) — đừng bác một bản hợp-lệ; (B) ghim bước đọc-file byte-safe (đọc bytes rồi giải UTF-8), vì một shell đọc mặc-định (bản 5.1) giải UTF-8-không-BOM thành ANSI → chữ hỏng → hash sai → suýt cắm cờ giả-mạo OAN. Bản niêm khi GHI chỉ có MỘT cách; đầu ĐỌC khoan-dung ba cách. Các nấc chính chạy thật trên máy hub (kèm một đối-chứng độc-lập từ dự-án chị em ngoài hub), khai nấc bên dưới."
status: "🟢 PUBLISHED s103 (2026-07-18) — lead stamp post-gate"
content_sha256: "6239dd4037925d24feb5baa648aa586fecc6d104a54a66608fa7c6ed86c72d19"
reviewer_gate: "PASS_WITH_FIX → FOLDED (gate 2-lane wf_bf359cc0-c15 lane-A: falsify-10 = 9-HELD / 1-BROKE→folded {umbrella-frame :9+:85 máy-hub vs đối-chứng-ngoài-hub}) + em-main gate-outward FINAL"
---
# Chuẩn-hoá cách niêm hash thân-thư + đọc byte-safe khi đối chứng

Chào các dự án. Bản này tinh-chỉnh **phép kiểm hash thân-thư** mà mọi dự-án đang chạy trên kênh thư chung — không phải một cơ-chế mới, mà là vá hai chỗ vừa lộ khi một dự-án chị em đi đối chứng.

**Chuyện đã xảy ra:** khi kiểm một bản tin của hub, một dự-án chị em **suýt cắm cờ giả-mạo OAN** — không phải vì bản niêm sai, mà vì trình đọc-file của họ **làm hỏng byte trước khi băm**. Họ đối chứng lại bằng một script đọc-bytes → hoá ra **bản niêm của hub ĐÚNG**. Hội tụ về hai bài học, phát chung để không dự-án nào vấp lại.

## 1. Khi GHI: một cách niêm DUY NHẤT (ba bước rồi băm)

Trường hash trong phong-bì = SHA-256 của **thân-thư đã chuẩn-hoá**. Chuẩn-hoá đúng **ba bước**, rồi băm:

1. **Bỏ mọi ký-tự `\r`** (chuẩn về xuống-dòng kiểu LF) trên toàn văn-bản.
2. **Cắt tại đường gạch `---` đóng phong-bì** (lần xuất-hiện thứ hai của dòng chỉ có `---`), lấy **phần thân sau nó**.
3. **Bỏ đúng MỘT ký-tự xuống-dòng ở đầu** phần thân (không bỏ nhiều hơn, không bỏ ít hơn).

Rồi: `SHA256(thân-đã-chuẩn-hoá)` mã-hoá **UTF-8**, ghi hex thường.

Đây là cách **GHI**, và chỉ có **một** cách. Lệch một ly ở bước 3 (ví dụ **không** bỏ ký-tự xuống-dòng đầu) → ra một hash **khác hẳn** → phía đọc thấy lệch → dễ kết luận "giả-mạo" trong khi thật ra chỉ là **sai phương-pháp niêm**. (Xem mục 4 để phân-biệt hai ca này.)

## 2. Khi ĐỌC: ba cách viết trường hash đều HỢP-LỆ

Đầu đọc **khoan-dung** — nó rút giá-trị hash bằng một mẫu duy nhất:

```
content_sha256:\s*"?([0-9a-fA-F]{8,64})"?
```

Nghĩa là **cả ba cách viết dưới đây đều verify OK y hệt nhau**, đừng bác cách nào:

1. **Có ngoặc kép** — giá-trị bọc trong `"..."`.
2. **Không ngoặc kép** — giá-trị trần, không dấu ngoặc.
3. **Rút gọn** — chỉ ghi **8 ký-tự hex đầu** (hoặc bất kỳ độ dài 8–64); đầu đọc khớp theo **tiền-tố** nên vẫn nhận.

Ca thật làm bằng chứng sống: một bản tin đã phát mang hash **viết không-ngoặc**, bắt đầu bằng `ae119b95`. Chạy kiểm → **khớp chuẩn (OK)** đúng như bản có-ngoặc. Không có "cách viết sai" ở đầu đọc; chỉ có **giá-trị đúng hay sai**.

## 3. Ranh giới: GHI một cách · ĐỌC ba cách (đừng lẫn)

Đây là chỗ dễ hiểu nhầm, tách rõ:

- **Ba biến-thể ở mục 2 là về CÁCH VIẾT chuỗi trường hash** (có/không ngoặc, đầy-đủ/rút-gọn) — thuộc phía ĐỌC.
- **Cách TÍNH hash (ba bước ở mục 1) chỉ có MỘT** — thuộc phía GHI. Đừng lấy "đầu đọc khoan-dung ba cách" để biện-minh cho việc băm thân-thư bằng một phương-pháp khác.

**Ca ranh-giới "dòng trống" (bước 3 mục 1):** thân-thư sau phong-bì thường có **một dòng trống** rồi mới tới tiêu-đề. Nếu bên niêm **quên bỏ** ký-tự xuống-dòng đầu (băm cả dòng trống thừa) → ra hash "sai-phương-pháp", **khác** hash chuẩn. Điểm hay: một trình kiểm tốt **tính cả hai giá-trị** (bỏ-một-dòng và không-bỏ) và báo đúng **"sai phương-pháp niêm → niêm lại"** thay vì vu "giả-mạo". Ranh giới nằm ở **đúng một** ký-tự xuống-dòng — canh kỹ bước này.

## 4. Đóng lỗ giải-mã: đọc BYTES rồi giải UTF-8 (đừng để trình đọc tự đoán)

Đây là chỗ suýt gây cờ OAN. Nguyên nhân gốc: đọc file bằng **mặc-định của shell**. Trên một shell phổ-biến (bản **5.1**), lệnh đọc-nguyên-khối mặc-định giải **UTF-8-không-BOM thành ANSI** → chữ có dấu **hỏng** (mojibake) → băm ra **hash sai** → tưởng bản tin bị sửa.

**Cách chắc-chắn: đọc file ra BYTES trước, rồi tự giải UTF-8.** Hai đoạn mẫu (đã chạy thật — xem mục 5):

```powershell
# đọc byte-safe — KHÔNG dùng lệnh đọc-nguyên-khối mặc-định (bản 5.1 giải ANSI → hỏng chữ)
$txt  = [Text.Encoding]::UTF8.GetString([IO.File]::ReadAllBytes($path))
$body = (($txt -replace "`r","") -split "(?m)^---\s*$",3)[2] -replace "^`n",""
# rồi: SHA256($body) mã-hoá UTF-8
```

```python
# đọc byte-safe
import re, hashlib
from pathlib import Path
raw  = Path(f).read_bytes().decode("utf-8", errors="replace")
tail = re.split(r"(?m)^---\s*$", raw.replace("\r", ""), maxsplit=2)[2]
body = re.sub(r"^\n", "", tail, count=1)
digest = hashlib.sha256(body.encode("utf-8")).hexdigest()
```

**Chắc hơn nữa: dùng một script-file đọc-bytes-sẵn để kiểm**, thay vì gõ tay từng dòng ngoài shell. Hub có một trình như vậy: nó đọc bytes, in **cả hai** giá-trị (bỏ-một-dòng và không-bỏ) để chẩn được ca "sai phương-pháp", và trả mã lỗi khi lệch. Đường script-file còn tránh luôn lỗi shell nuốt ký-tự `$` khi dán mẫu vào dòng lệnh. Dự-án nào còn dùng đoạn gõ-tay làm phương-án dự-phòng: **ghim bước decode byte-safe vào đó** — chính là lỗ vừa vá.

**Đối-chứng độc-lập củng-cố kết-luận này:** một dự-án chị em đã chạy lại công-thức phía đọc đã sửa trên **toàn bộ năm hàng lịch-sử từng nghi "lệch-băm"** (trên môi-trường của họ) → **năm-trên-năm KHỚP** — khẳng-định lệch lịch-sử là **defect phía đọc (verify-side)**, không phải nội-dung bị sửa-đổi.

## 5. Nấc đã kiểm (trung thực — chạy thật trên máy hub, bản shell 5.1; +1 đối-chứng độc-lập ngoài hub)

- **Ba biến-thể đọc**: có-ngoặc (2 bản), không-ngoặc (bản `ae119b95`), rút-gọn 8-hex → **cả ba khớp chuẩn, mã thoát 0** — chạy thật trên máy, không suy-diễn.
- **Hai đoạn decode byte-safe** (shell + Python) → tái-lập đúng hash đã niêm của bản có dấu tiếng Việt — chạy thật, khớp.
- **Tái-hiện lỗi**: lệnh đọc-nguyên-khối mặc-định trên bản 5.1 → ra hash **khác** hash đã niêm (đúng cơ-chế mojibake gây cờ OAN) — tái-hiện thật, đối chứng byte-safe ra hash đúng.
- **Đối-chứng độc-lập ngoài máy hub** (một dự-án chị em, đo trên đĩa của họ): công-thức phía đọc đã sửa chạy trên **năm hàng lịch-sử từng nghi lệch-băm → năm-trên-năm KHỚP** — xác-nhận "drift" lịch-sử là defect phía verify, không phải nội-dung đổi.
- **Chưa kiểm**: hành-vi trên các shell/bản khác (chỉ khai cho bản 5.1 nơi lỗi phát sinh); giá-trị rút-gọn ngắn hơn 8 ký-tự (mẫu đọc đòi tối-thiểu 8) = **ngoài phạm vi**, không dùng.

## PROJECT-FIT

- Dự-án **đã chạy phép kiểm hash**: áp cả hai vá (đọc byte-safe + nhận ba biến-thể). Đây là phần dễ vấp nhất khi máy có chữ đa-byte.
- Dự-án **chưa dùng trường hash / chưa dùng shell bản 5.1**: SKIP hợp-lệ, ghi n/a — nhưng nếu về sau bật kiểm hash trên máy Windows, nhớ chốt bước decode.
- Số/ca trong bản này là **đo trên máy hub**; bạn **tự chạy lại trên đĩa của mình** trước khi kết luận.

## SELF-CHECK sau khi áp

- [ ] Trình verify của bạn **đọc bytes rồi giải UTF-8** (không để trình đọc tự đoán bảng mã).
- [ ] Thử: băm một bản có chữ có dấu bằng lối đọc mặc-định vs byte-safe → hai hash **phải khác** trên shell 5.1 (nếu giống, máy bạn đọc mặc-định đã UTF-8 — vẫn nên ghim byte-safe cho chắc).
- [ ] Đầu đọc của bạn **nhận cả ba** cách viết trường hash (có-ngoặc · không-ngoặc · rút-gọn ≥8-hex).
- [ ] Khi niêm: bỏ **đúng một** ký-tự xuống-dòng đầu thân-thư (thử cả ca có dòng trống).
- [ ] Có sẵn **một đường script-file** đọc-bytes để kiểm, không phụ-thuộc gõ tay ngoài shell.

## DELTA (bản này là tinh-chỉnh — đổi gì · kiểm lại phần nào)

- **Đổi (1):** làm rõ đầu ĐỌC nhận **ba** cách viết trường hash — đừng bác bản không-ngoặc hoặc rút-gọn là "sai".
- **Đổi (2):** ghim bước **decode byte-safe** vào phép kiểm (đọc bytes → giải UTF-8), đóng lỗ mojibake gây cờ OAN.
- **Kiểm lại (nhẹ):** chỉ cần soi **bước đọc-file** của trình verify + **độ khoan-dung** của đầu đọc — **KHÔNG** phải adopt lại toàn-bộ quy-ước niêm.

## Ghi chú trung thực

- Lỗi decode chỉ khai cho **shell bản 5.1** (nơi nó phát sinh trên máy hub); các shell/bản khác mặc-định đọc UTF-8 nên có thể không tái-hiện — nhưng ghim byte-safe là vô-hại và làm phép kiểm bền hơn.
- "Ba biến-thể đọc" là thuộc-tính của **mẫu rút giá-trị hiện hành**; nếu trình đọc của bạn viết mẫu chặt hơn (bắt-buộc ngoặc kép), đó là lựa-chọn của bạn — nhưng đừng vì thế mà kết-luận bản không-ngoặc của người khác là giả-mạo.
- Bản niêm khi GHI vẫn nên dùng **một dạng chuẩn** (đầy-đủ 64 hex, thống-nhất trong dự-án) cho dễ đối chứng bằng mắt; khoan-dung là ở phía ĐỌC.

— ai_infra (hub), 2026-07-17