🛡️ ZERO DATA LOSS REFACTORING: PHƯƠNG PHÁP BẢO TỒN 100% DỮ LIỆU KHI TÁI CẤU TRÚC MÃ NGUỒN & AI BRAIN¶

+--------------------------------------------------------------------------------------------------+
| DẤU HIỆU NHẬN DIỆN THẤT THOÁT                                                                    |
+--------------------------------------------------------------------------------------------------+
| [!] Mất quy chuẩn ngầm: Agent bắt đầu trả lời sai định dạng, dùng bảng markdown, thiếu giọng nói |
| [!] Gãy liên kết Symlink: Các đường dẫn chéo giữa brain -> apps -> books bị báo No such file     |
| [!] SQLite Reset: Bảng dữ liệu bị mất toàn bộ lịch sử bài học chỉ còn lại schema rỗng           |
| [!] Thiếu tệp tin di sản: Các kinh nghiệm thực chiến bị gom vào thư mục archive rồi biến mất     |
| [!] Không thể Rollback: Khi phát hiện lỗi mới thì mã nguồn cũ đã bị sửa nát, không thể hoàn tác   |
+--------------------------------------------------------------------------------------------------+

====================================================================================================
🏛️ MÔ HÌNH 4 TẦNG "ZERO DATA LOSS REFACTORING"
====================================================================================================

      ┌────────────────────────────────────────────────────────┐
      │  TẦNG 1: IMMUTABLE VAULT SNAPSHOT                      │
      │  - Đóng băng thư mục gốc (Read-Only Snapshot)          │
      │  - Băm SHA-256 toàn bộ file -> manifest_before.json   │
      │  - Dump SQL DB -> data_snapshot.sql                    │
      └──────────────────────────┬─────────────────────────────┘
                                 │
                                 ▼
      ┌────────────────────────────────────────────────────────┐
      │  TẦNG 2: BLUE/GREEN PARALLEL WORKSPACE                 │
      │  - Nhân bản nguyên trạng: cp -a /current /target-next   │
      │  - Tuyệt đối cấm thao tác trên thư mục Live            │
      │  - Mọi chỉnh sửa, tối ưu hóa diễn ra tại target-next   │
      └──────────────────────────┬─────────────────────────────┘
                                 │
                                 ▼
      ┌────────────────────────────────────────────────────────┐
      │  TẦNG 3: ADDITIVE-ONLY CONTRACT & ADAPTER              │
      │  - DB Migration: Chỉ ADD column/table, cấm DROP        │
      │  - Markdown: Di sản đưa vào _legacy/, mapping qua index│
      │  - Config: Hỗ trợ cả key cũ lẫn key mới (Fallback)     │
      └──────────────────────────┬─────────────────────────────┘
                                 │
                                 ▼
      ┌────────────────────────────────────────────────────────┐
      │  TẦNG 4: PARITY VERIFICATION & ATOMIC SWITCH           │
      │  - Chạy test kiểm kê: check_parity(before, after) == 100%│
      │  - Nếu PASS: ln -sfn /target-next /active_symlink       │
      │  - Nếu FAIL: Hủy target-next, hệ thống cũ nguyên vẹn 1s │
      └────────────────────────────────────────────────────────┘
====================================================================================================

# 1. Tạo thư mục Snapshot có gắn timestamp
SNAPSHOT_DIR="/home/crystal-aress/downloads/archives/snapshot_$(date +%Y%m%d_%H%M%S)"
mkdir -p "$SNAPSHOT_DIR"

# 2. Dump toàn bộ cơ sở dữ liệu SQLite
sqlite3 /home/crystal-aress/harness-core/08_SHARED_MEMORY/blackboard.db ".dump" > "$SNAPSHOT_DIR/blackboard_dump.sql"

# 3. Tạo Manifest kiểm kê toàn bộ file kèm mã băm SHA256
find /home/crystal-aress/harness-core -type f -not -path '*/.*' -exec sha256sum {} + | sort -k 2 > "$SNAPSHOT_DIR/manifest_before.txt"

# 4. Ghi nhận số lượng thực thể cốt lõi
echo "=== METRICS BEFORE REFACTOR ===" > "$SNAPSHOT_DIR/stats.txt"
echo "Total files: $(wc -l < "$SNAPSHOT_DIR/manifest_before.txt")" >> "$SNAPSHOT_DIR/stats.txt"
sqlite3 /home/crystal-aress/harness-core/08_SHARED_MEMORY/blackboard.db "SELECT 'lessons_count: ' || COUNT(*) FROM episodic_lessons;" >> "$SNAPSHOT_DIR/stats.txt"
sqlite3 /home/crystal-aress/harness-core/08_SHARED_MEMORY/blackboard.db "SELECT 'handoffs_count: ' || COUNT(*) FROM shift_handoffs;" >> "$SNAPSHOT_DIR/stats.txt"

# Nhân bản hoàn toàn bảo lưu thuộc tính, quyền hạn và symlink
cp -a /home/crystal-aress/harness-core /home/crystal-aress/harness-core-next

-- Ví dụ: Nâng cấp bảng bài học từ schema cũ lên schema Master Series
-- Tạo bảng mới phiên bản v2
CREATE TABLE IF NOT EXISTS episodic_lessons_v2 (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    legacy_id INTEGER,
    reporter_role TEXT NOT NULL,
    category TEXT NOT NULL,
    summary TEXT NOT NULL,
    details TEXT,
    solution TEXT,
    trace_id TEXT,             -- Trường mới của Master Series
    severity_level TEXT,       -- Trường mới của Master Series
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Bơm toàn bộ dữ liệu di sản sang schema mới mà không làm mất 1 dòng nào
INSERT INTO episodic_lessons_v2 (legacy_id, reporter_role, category, summary, details, solution, created_at)
SELECT id, reporter_role, category, summary, details, solution, created_at FROM episodic_lessons;

-- Tạo View tương thích ngược để code cũ vẫn đọc được như bình thường
CREATE VIEW IF NOT EXISTS episodic_lessons_compat AS SELECT * FROM episodic_lessons_v2;

#!/usr/bin/env python3
"""
VERIFY PARITY GATE: Công cụ kiểm tra độ khớp và bảo tồn dữ liệu 100%
Vị trí: tools/verify_parity.py
"""

import sys
import os
import sqlite3
import json
from pathlib import Path

def verify_refactor(legacy_dir: str, target_dir: str, legacy_db: str, target_db: str):
    print("=" * 80)
    print("🔍 BẮT ĐẦU KIỂM ĐỊNH TÍNH TOÀN VẸN VÀ BẢO TỒN DỮ LIỆU...")
    print(f"Legacy: {legacy_dir}")
    print(f"Target: {target_dir}")
    print("=" * 80)

    errors = []

    # 1. Kiểm tra CSDL SQLite: Số lượng bản ghi không được giảm
    if os.path.exists(legacy_db) and os.path.exists(target_db):
        conn_leg = sqlite3.connect(legacy_db)
        conn_tar = sqlite3.connect(target_db)

        # Lấy danh sách bảng trong DB cũ
        cur_leg = conn_leg.cursor()
        cur_leg.execute("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%';")
        tables = [r[0] for r in cur_leg.fetchall()]

        for tbl in tables:
            cur_leg.execute(f"SELECT COUNT(*) FROM {tbl};")
            count_leg = cur_leg.fetchone()[0]

            cur_tar = conn_tar.cursor()
            # Kiểm tra xem bảng có tồn tại ở DB mới không
            cur_tar.execute(f"SELECT name FROM sqlite_master WHERE type='table' AND name='{tbl}';")
            if not cur_tar.fetchone():
                errors.append(f"[DB ERROR] Bảng di sản '{tbl}' bị biến mất trong DB mới!")
                continue

            cur_tar.execute(f"SELECT COUNT(*) FROM {tbl};")
            count_tar = cur_tar.fetchone()[0]

            if count_tar < count_leg:
                errors.append(f"[DATA LOSS] Bảng '{tbl}' bị hụt dữ liệu! (Cũ: {count_leg}, Mới: {count_tar})")
            else:
                print(f"  [OK] CSDL Table '{tbl}': {count_leg} -> {count_tar} bản ghi (Bảo toàn 100%)")

        conn_leg.close()
        conn_tar.close()

    # 2. Kiểm tra các Rule nghiệp vụ cốt lõi trong tài liệu Markdown
    core_rules = [
        "Rule 1", "Rule 2", "Rule 3", "Rule 4", "Rule 5",
        "Rule 6", "Rule 7", "Rule 8", "Rule 9", "Rule 10",
        "Rule 11", "Rule 12", "Rule 13", "Rule 14"
    ]

    # Gom toàn bộ nội dung markdown trong target_dir
    combined_content = ""
    for root, _, files in os.walk(target_dir):
        for f in files:
            if f.endswith(".md"):
                file_path = os.path.join(root, f)
                try:
                    with open(file_path, "r", encoding="utf-8", errors="ignore") as md_f:
                        combined_content += md_f.read() + "\n"
                except Exception:
                    pass

    missing_rules = []
    for r in core_rules:
        if r.lower() not in combined_content.lower():
            missing_rules.append(r)

    if missing_rules:
        errors.append(f"[RULE LOSS] Phát hiện thất lạc các quy chuẩn thép: {', '.join(missing_rules)}")
    else:
        print("  [OK] Kiểm kê quy chuẩn nghiệp vụ: Đủ 14/14 Rules cốt lõi hiện diện trong hệ thống mới!")

    # 3. Kết luận
    print("=" * 80)
    if errors:
        print("❌ KIỂM ĐỊNH THẤT BẠI! PHÁT HIỆN LỖI MẤT DỮ LIỆU:")
        for err in errors:
            print(f"   -> {err}")
        return False
    else:
        print("🎉 KIỂM ĐỊNH HOÀN TOÀN THÀNH CÔNG! ĐẠT CHUẨN ZERO DATA LOSS 100%.")
        return True

if __name__ == "__main__":
    if len(sys.argv) < 5:
        print("Usage: python3 verify_parity.py <legacy_dir> <target_dir> <legacy_db> <target_db>")
        sys.exit(1)

    success = verify_refactor(sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4])
    sys.exit(0 if success else 1)

====================================================================================================
📜 10 NGUYÊN TẮC BẤT DI BẤT DỊCH TRONG MỌI CUỘC REFACTOR CODE & AI BRAIN
====================================================================================================

1. LUẬT BẤT BIẾN THƯ MỤC GỐC:
   Không bao giờ được gõ lệnh sửa đổi trực tiếp trên thư mục live đang hoạt động.

2. LUẬT SNAPSHOT TRƯỚC TIÊN:
   Luôn dump database và lập manifest băm SHA-256 trước khi viết dòng code refactor đầu tiên.

3. LUẬT SAO CHÉP KẾ THỪA:
   Luôn dùng `cp -a` để nhân bản cấu trúc sang môi trường thử nghiệm song song.

4. LUẬT TIẾP BIẾN CƠ SỞ DỮ LIỆU (ADDITIVE-ONLY):
   Chỉ thêm bảng mới hoặc thêm cột mới, cấm tuyệt đối DROP TABLE hoặc DROP COLUMN dữ liệu cũ.

5. LUẬT BẢO TỒN DI SẢN (LEGACY VAULT):
   File cũ không bao giờ được xóa sổ. Nếu thay thế, phải di dời nguyên vẹn vào `_legacy_vault/`.

6. LUẬT KHÔNG TIN TƯỞNG TÓM TẮT:
   Không để AI tự ý tóm tắt gộp nhiều file kỹ thuật thành một file ngắn gọn vì sẽ rơi rụng cờ hệ thống.

7. LUẬT MA TRẬN ÁNH XẠ (MAPPING MATRIX):
   Mỗi file mới sinh ra phải có dòng chú thích chỉ rõ nó kế thừa và thay thế cho file cũ nào.

8. LUẬT KIỂM CHỨNG ĐỊNH LƯỢNG (PARITY VERIFICATION):
   Số bản ghi DB sau refactor phải >= trước refactor. Số rule bao phủ phải đạt đúng 100%.

9. LUẬT ĐẢO CHIỀU 1 GIÂY (ATOMIC SYMLINK SWITCH):
   Chỉ chuyển đổi môi trường bằng symlink nguyên tử `ln -sfn`. Nếu có sự cố, đảo ngược trong 1s.

10. LUẬT GIAO CA BẰNG CHỨNG THỰC TẾ:
    Mọi đợt refactor hoàn tất bắt buộc phải có log đối chiếu định lượng trước khi thông báo xong.
====================================================================================================