evorule-governance 0.2.3

// SPDX-License-Identifier: AGPL-3.0-or-later
// Copyright (C) 2026 EvoRule Project
// This file is part of EvoRule, licensed under GNU Affero General Public License v3 or later.
//! 审计器 - 基于 FactsLog 构建审计链
//!
//! # 功能
//! - 定期从 FactsLog 读取新事实
//! - 计算每个 Fact 的哈希，维护哈希链
//! - 生成审计报告（因果链、版本历史）
//! - 验证审计链完整性
//!
//! # 哈希链算法
//! - `last_hash` 初始为 `"genesis"`
//! - 每个事实的链哈希 = `blake3(prev_hash + fact_hash)`
//! - 该链哈希作为下一条目的 `prev_hash`，形成不可篡改的链式结构
//!
//! # 两套 WAL 合并
//! 自 0.2.0 起，哈希链已提升到 tier1 的 FactsLog/WAL 层。
//! - tier1 WAL 写入时自动计算并存储哈希链（`content_hash`/`prev_hash`/`chain_hash`）
//! - 审计器不再独立写 WAL（`append_wal` 已废弃）
//! - 审计器的 `last_hash` 应与 `FactsLog::last_hash()` 一致
//! - 恢复审计状态使用 [`Auditor::load_from_tier1_wal`]（读取 tier1 WAL 并验证哈希链）

use crate::clock::LogicalClock;
use crate::hash;
use evorule_reactor::{Fact, FactId, FactsLog};
use std::collections::BTreeMap;

/// 审计条目
///
/// 对应一个被审计的 [`Fact`]，记录其哈希、逻辑时间戳及哈希链前驱。
#[derive(Debug, Clone)]
pub struct AuditEntry {
    /// Fact ID
    pub fact_id: FactId,
    /// Fact 类型名
    pub fact_type: &'static str,
    /// 逻辑时钟值
    pub logical_time: u64,
    /// 内容哈希
    pub content_hash: String,
    /// 前一条目的哈希（形成哈希链）
    pub prev_hash: String,
    /// 因果父 Fact ID（如有）
    pub cause: Option<FactId>,
}

/// 审计链加载错误（两套 WAL 合并）
///
/// `load_from_tier1_wal` 的错误类型，涵盖哈希链验证的各种失败场景。
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum LoadError {
    /// 文件读取失败（I/O 错误或 WAL 格式错误）
    IoError(String),
    /// 哈希计算失败（Fact 序列化错误）
    HashError(String),
    /// Fact 内容被篡改（存储的 content_hash 与重算的不匹配）
    ContentHashMismatch {
        /// 记录索引
        index: usize,
        /// Fact ID
        fact_id: FactId,
        /// WAL 中存储的哈希
        stored: String,
        /// 重算得到的哈希
        recomputed: String,
    },
    /// 哈希链断裂（prev_hash 链接不正确）
    ChainBroken {
        /// 记录索引
        index: usize,
        /// Fact ID
        fact_id: FactId,
        /// WAL 中存储的 prev_hash
        stored_prev: String,
        /// 期望的 prev_hash（前一条的 chain_hash）
        expected_prev: String,
    },
    /// 链哈希被篡改（存储的 chain_hash 与重算的不匹配）
    ChainHashMismatch {
        /// 记录索引
        index: usize,
        /// Fact ID
        fact_id: FactId,
        /// WAL 中存储的 chain_hash
        stored: String,
        /// 重算得到的 chain_hash
        recomputed: String,
    },
}

impl core::fmt::Display for LoadError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            LoadError::IoError(msg) => write!(f, "WAL 读取失败: {msg}"),
            LoadError::HashError(msg) => write!(f, "哈希计算失败: {msg}"),
            LoadError::ContentHashMismatch {
                index,
                fact_id,
                stored,
                recomputed,
            } => write!(
                f,
                "Fact[{}] (id={}) 内容哈希不匹配: stored={stored}, recomputed={recomputed}",
                index, fact_id.0
            ),
            LoadError::ChainBroken {
                index,
                fact_id,
                stored_prev,
                expected_prev,
            } => write!(
                f,
                "Fact[{}] (id={}) 哈希链断裂: stored_prev={stored_prev}, expected_prev={expected_prev}",
                index, fact_id.0
            ),
            LoadError::ChainHashMismatch {
                index,
                fact_id,
                stored,
                recomputed,
            } => write!(
                f,
                "Fact[{}] (id={}) 链哈希不匹配: stored={stored}, recomputed={recomputed}",
                index, fact_id.0
            ),
        }
    }
}

impl std::error::Error for LoadError {}

/// 审计器
///
/// 周期性消费 [`FactsLog`] 中的新增事实，构建带哈希链的审计条目列表。
/// 维护 `BTreeMap<FactId, usize>` 实时索引，支持 O(log n) 的因果链查询。
///
/// # 持久化（WAL）
/// 可选地通过 [`Auditor::with_wal_path`] 启用 WAL 持久化。
/// 启用后，每个新增审计条目以 JSONL 格式追加写入磁盘，
/// 进程重启后可通过 [`Auditor::load_from_wal`] 恢复审计状态。
pub struct Auditor {
    /// FactsLog 引用
    facts_log: FactsLog,
    /// 逻辑时钟
    clock: LogicalClock,
    /// 已审计到的版本
    last_audited_version: u64,
    /// 审计条目列表
    entries: Vec<AuditEntry>,
    /// 上一条目的哈希
    last_hash: String,
    /// FactId -> entries 索引的实时索引（优化因果链查询）
    index: BTreeMap<FactId, usize>,
    /// WAL 持久化路径（可选）
    wal_path: Option<std::path::PathBuf>,
    /// 是否在 audit_new 后自动验证审计链完整性（P06）
    ///
    /// 启用后每次 audit_new 完成后自动调用 verify()，及时发现数据篡改。
    /// 性能开销为 O(n)（n 为审计条目数），建议在大条目数场景配合
    /// `auto_verify_threshold` 和 `auto_verify_interval` 使用。
    auto_verify: bool,
    /// 自动验证阈值（P06）
    ///
    /// 当审计条目数超过此阈值时，跳过自动验证以避免性能问题。
    /// 默认 1000。设为 0 表示不限制（始终验证）。
    auto_verify_threshold: usize,
    /// 自动验证间隔（P06）
    ///
    /// 每 N 次 audit_new 执行一次自动验证（仅在 auto_verify=true 时生效）。
    /// 默认 1（每次都验证）。设为 100 表示每 100 次验证一次。
    auto_verify_interval: usize,
    /// audit_new 调用计数（P06，用于间隔控制）
    audit_new_count: u64,
}

impl Auditor {
    /// 创建新审计器
    ///
    /// `last_hash` 初始为 `"genesis"`，`last_audited_version` 初始为 0。
    pub fn new(facts_log: FactsLog) -> Self {
        Self {
            facts_log,
            clock: LogicalClock::new(),
            last_audited_version: 0,
            entries: Vec::new(),
            last_hash: String::from("genesis"),
            index: BTreeMap::new(),
            wal_path: None,
            auto_verify: false,
            auto_verify_threshold: 1000,
            auto_verify_interval: 1,
            audit_new_count: 0,
        }
    }

    /// 创建带实时验证配置的审计器（P06）
    ///
    /// # 参数
    /// - `facts_log`：FactsLog 引用
    /// - `auto_verify`：是否在 audit_new 后自动验证
    /// - `auto_verify_threshold`：条目数超过此阈值时跳过验证（0 表示不限制）
    /// - `auto_verify_interval`：每 N 次 audit_new 验证一次（1 表示每次都验证）
    pub fn new_with_auto_verify(
        facts_log: FactsLog,
        auto_verify: bool,
        auto_verify_threshold: usize,
        auto_verify_interval: usize,
    ) -> Self {
        Self {
            facts_log,
            clock: LogicalClock::new(),
            last_audited_version: 0,
            entries: Vec::new(),
            last_hash: String::from("genesis"),
            index: BTreeMap::new(),
            wal_path: None,
            auto_verify,
            auto_verify_threshold,
            auto_verify_interval: if auto_verify_interval == 0 {
                1
            } else {
                auto_verify_interval
            },
            audit_new_count: 0,
        }
    }

    /// 设置实时验证配置（P06）
    ///
    /// 可在创建后修改自动验证配置。
    pub fn set_auto_verify(
        &mut self,
        auto_verify: bool,
        auto_verify_threshold: usize,
        auto_verify_interval: usize,
    ) {
        self.auto_verify = auto_verify;
        self.auto_verify_threshold = auto_verify_threshold;
        self.auto_verify_interval = if auto_verify_interval == 0 {
            1
        } else {
            auto_verify_interval
        };
    }

    /// 查询当前是否启用自动验证（P06）
    pub fn is_auto_verify_enabled(&self) -> bool {
        self.auto_verify
    }

    /// 设置 WAL 持久化路径（deprecated）
    ///
    /// # ⚠️ 已废弃（两套 WAL 合并）
    /// 自 0.2.0 起，哈希链已由 tier1 FactsLog/WAL 自动维护，
    /// 审计器不再需要独立写 WAL。此方法仅保留向后兼容，
    /// 设置的路径不会被使用（`append_wal` 已禁用）。
    ///
    /// # 迁移指南
    /// 审计状态持久化请使用 tier1 WAL（`FactsLog::with_wal`），
    /// 恢复审计状态请使用 [`Auditor::load_from_tier1_wal`]。
    #[deprecated(
        since = "0.2.0",
        note = "两套 WAL 合并：审计器不再独立写 WAL，请使用 tier1 FactsLog WAL"
    )]
    pub fn with_wal_path<P: AsRef<std::path::Path>>(mut self, path: P) -> Self {
        self.wal_path = Some(path.as_ref().to_path_buf());
        self
    }

    /// 将单条审计条目序列化为 JSONL 行（deprecated，仅供向后兼容）
    #[deprecated(since = "0.2.0", note = "两套 WAL 合并：审计器不再独立写 WAL")]
    #[allow(dead_code)]
    fn entry_to_json_line(entry: &AuditEntry) -> String {
        serde_json::json!({
            "fact_id": entry.fact_id.0,
            "fact_type": entry.fact_type,
            "logical_time": entry.logical_time,
            "content_hash": entry.content_hash,
            "prev_hash": entry.prev_hash,
            "cause": entry.cause.map(|c| c.0),
        })
        .to_string()
    }

    /// 追加单条审计条目到 WAL 文件（deprecated，已禁用）
    ///
    /// # ⚠️ 已废弃（两套 WAL 合并）
    /// 自 0.2.0 起，此函数不再执行任何写入操作。
    /// 哈希链由 tier1 FactsLog/WAL 自动维护。
    #[deprecated(
        since = "0.2.0",
        note = "两套 WAL 合并：审计器不再独立写 WAL，哈希链由 tier1 WAL 维护"
    )]
    #[allow(dead_code)]
    fn append_wal(&self, _entry: &AuditEntry) {
        // 两套 WAL 合并：不再写入 auditor WAL
        // 哈希链已由 tier1 FactsLog::append() 自动写入 tier1 WAL
    }

    /// 审计新增事实
    ///
    /// 从 FactsLog 读取 `last_audited_version` 之后的所有事实，
    /// 为每个事实创建 [`AuditEntry`]，更新哈希链。
    ///
    /// # 去重策略
    /// 由于 `FactsLog::read_from` 按 `version_before` 过滤，而同一版本下可能
    /// 存在多条不改变版本号的事实（如 `Command`/`IoRequest`），直接以版本号
    /// 做去重会导致重复审计。故本实现以 `entries.len()` 作为已审计进度，
    /// 从 `FactsLog::history()` 中读取尚未审计的尾部事实，保证每条事实仅审计一次。
    ///
    /// # 返回值
    /// 本次新增的审计条目数量。
    // 审计遍历 + 哈希 + append 多步串联, 拆函数需共享 self 状态。详见 GATE_REFERENCE.md §六(豁免索引)
    #[allow(clippy::cognitive_complexity)]
    pub fn audit_new(&mut self) -> usize {
        // P06: 计数始终递增（按调用次数，而非新事实数），用于自动验证间隔控制
        self.audit_new_count += 1;

        let history = self.facts_log.history();
        let start = self.entries.len();
        if start >= history.len() {
            self.last_audited_version = self.facts_log.version();
            tracing::debug!(version = self.last_audited_version, "audit_new: 无新增事实");
            return 0;
        }

        let count = history.len() - start;
        for (idx_offset, fact) in history[start..].iter().enumerate() {
            let fact_id = fact.id();
            let fact_type = fact.type_name();
            let logical_time = self.clock.tick();
            let content_hash = match hash::fact_hash(fact) {
                Ok(h) => h,
                Err(e) => {
                    tracing::error!(
                        事实ID = ?fact_id,
                        事实类型 = %fact_type,
                        错误 = %e,
                        "审计器: 事实哈希计算失败，跳过损坏事实"
                    );
                    continue;
                }
            };
            let prev_hash = self.last_hash.clone();
            let cause = extract_cause(fact);

            // 计算新的链哈希：blake3(prev_hash + content_hash)
            let combined = format!("{}{}", prev_hash, content_hash);
            let new_hash = blake3::hash(combined.as_bytes()).to_hex().to_string();
            self.last_hash = new_hash;

            let entry_index = start + idx_offset;
            self.index.insert(fact_id, entry_index);

            self.entries.push(AuditEntry {
                fact_id,
                fact_type,
                logical_time,
                content_hash,
                prev_hash,
                cause,
            });

            // 两套 WAL 合并：不再写入 auditor WAL
            // 哈希链已由 tier1 FactsLog::append() 自动写入 tier1 WAL
        }

        self.last_audited_version = self.facts_log.version();
        tracing::debug!(
            audited = count,
            version = self.last_audited_version,
            "audit_new: 完成"
        );

        // P06: 实时审计验证
        if self.should_auto_verify() {
            if !self.verify() {
                tracing::error!(
                    entries = self.entries.len(),
                    audit_new_count = self.audit_new_count,
                    "audit_new: 实时审计验证失败，审计链可能存在数据篡改或损坏"
                );
            } else {
                tracing::debug!(entries = self.entries.len(), "audit_new: 实时审计验证通过");
            }
        }

        count
    }

    /// 判断本次是否应执行自动验证（P06）
    ///
    /// 综合考虑三个条件：
    /// 1. `auto_verify` 必须为 true
    /// 2. 条目数不超过 `auto_verify_threshold`（0 表示不限制）
    /// 3. `audit_new_count` 是 `auto_verify_interval` 的倍数
    fn should_auto_verify(&self) -> bool {
        if !self.auto_verify || self.entries.is_empty() {
            return false;
        }
        if self.auto_verify_threshold > 0 && self.entries.len() > self.auto_verify_threshold {
            tracing::debug!(
                entries = self.entries.len(),
                threshold = self.auto_verify_threshold,
                "实时审计验证: 条目数超过阈值，跳过验证"
            );
            return false;
        }
        if self.auto_verify_interval > 1
            && self.audit_new_count % (self.auto_verify_interval as u64) != 0
        {
            return false;
        }
        true
    }

    /// 验证审计链完整性
    ///
    /// 重新计算每个条目的链哈希，并校验其存储的 `prev_hash` 与上一条目
    /// 重算出的链哈希一致，确认链式结构未被篡改。
    ///
    /// # 返回值
    /// - `true`：所有条目的 `prev_hash` 链接自洽
    /// - `false`：发现断裂（某条目 `prev_hash` 与前驱重算哈希不匹配）
    pub fn verify(&self) -> bool {
        let mut prev_hash = String::from("genesis");
        for entry in &self.entries {
            if entry.prev_hash != prev_hash {
                tracing::warn!(
                    fact_id = entry.fact_id.0,
                    "verify: 哈希链断裂，prev_hash 不匹配"
                );
                return false;
            }
            // 重新计算当前条目的链哈希，作为下一跳的预期 prev_hash
            let combined = format!("{}{}", entry.prev_hash, entry.content_hash);
            let recomputed = blake3::hash(combined.as_bytes()).to_hex().to_string();
            prev_hash = recomputed;
        }
        tracing::debug!(entries = self.entries.len(), "verify: 审计链完整");
        true
    }

    /// 获取审计条目
    pub fn entries(&self) -> &[AuditEntry] {
        &self.entries
    }

    /// 获取当前审计链的末尾哈希
    ///
    /// 返回最后一条审计条目的链哈希，初始为 `"genesis"`。
    /// 可用于快速获取审计链状态，无需解析 `report()` 的 JSON。
    pub fn last_hash(&self) -> &str {
        &self.last_hash
    }

    /// 生成审计报告（JSON 格式）
    ///
    /// 包含审计器元信息（已审计版本、条目数、末尾哈希）与全部审计条目。
    pub fn report(&self) -> String {
        let entries_json: Vec<serde_json::Value> = self
            .entries
            .iter()
            .map(|e| {
                serde_json::json!({
                    "fact_id": e.fact_id.0,
                    "fact_type": e.fact_type,
                    "logical_time": e.logical_time,
                    "content_hash": e.content_hash,
                    "prev_hash": e.prev_hash,
                    "cause": e.cause.map(|c| c.0),
                })
            })
            .collect();

        let report = serde_json::json!({
            "last_audited_version": self.last_audited_version,
            "entry_count": self.entries.len(),
            "last_hash": self.last_hash,
            "entries": entries_json,
        });

        serde_json::to_string_pretty(&report).unwrap_or_else(|_| String::from("{}"))
    }

    /// 获取因果链（从指定 FactId 开始追溯 cause 链）
    ///
    /// 返回从该 FactId 起，沿 `cause` 字段向上追溯的审计条目列表，
    /// 顺序为：起始条目 → 其因果父 → … → 根因（`cause` 为 `None` 的条目）。
    /// 若中途找不到对应条目，则在断点处终止追溯。
    ///
    /// # 性能优化
    /// 使用实时维护的 `BTreeMap<FactId, usize>` 索引，查询复杂度为 O(log n)。
    pub fn causal_chain(&self, fact_id: FactId) -> Vec<AuditEntry> {
        let mut chain = Vec::new();
        let mut current = Some(fact_id);
        while let Some(cur_id) = current {
            match self.index.get(&cur_id) {
                Some(&i) => {
                    let entry = self.entries[i].clone();
                    current = entry.cause;
                    chain.push(entry);
                }
                None => {
                    tracing::warn!(fact_id = cur_id.0, "causal_chain: 追溯中断，未找到审计条目");
                    break;
                }
            }
        }
        chain
    }

    /// 从 WAL 文件加载审计状态（deprecated，读取旧 auditor WAL 格式）
    ///
    /// # ⚠️ 已废弃（两套 WAL 合并）
    /// 自 0.2.0 起，审计状态应从 tier1 WAL 恢复，请使用
    /// [`Auditor::load_from_tier1_wal`] 代替。
    ///
    /// 本方法仍可读取旧格式 auditor WAL 文件（`fact_id`/`fact_type`/
    /// `logical_time`/`content_hash`/`prev_hash`/`cause` JSONL），
    /// 但不验证哈希链完整性（旧格式无 `chain_hash` 字段）。
    ///
    /// # 注意
    /// 此方法不校验 FactsLog 中是否存在对应 Fact，仅恢复内存结构。
    /// 调用方应确保 WAL 文件来自可信来源。
    #[deprecated(
        since = "0.2.0",
        note = "两套 WAL 合并：请使用 load_from_tier1_wal 读取 tier1 WAL（带哈希验证）"
    )]
    pub fn load_from_wal(&mut self, path: &std::path::Path) -> std::io::Result<()> {
        use std::io::BufRead;

        if !path.exists() {
            return Ok(());
        }

        let file = std::fs::File::open(path)?;
        let reader = std::io::BufReader::new(file);

        for (idx, line) in reader.lines().enumerate() {
            let line = line?;
            if line.trim().is_empty() {
                continue;
            }

            let parsed: serde_json::Value = match serde_json::from_str(&line) {
                Ok(v) => v,
                Err(_) => {
                    tracing::warn!(line = idx, "load_from_wal: 跳过无效 JSON 行");
                    continue;
                }
            };

            let fact_id_num = match parsed.get("fact_id").and_then(|v| v.as_u64()) {
                Some(n) => n,
                None => continue,
            };
            let fact_type = match parsed.get("fact_type").and_then(|v| v.as_str()) {
                Some(s) => s,
                None => continue,
            };
            let logical_time = parsed
                .get("logical_time")
                .and_then(|v| v.as_u64())
                .unwrap_or(0);
            let content_hash = parsed
                .get("content_hash")
                .and_then(|v| v.as_str())
                .unwrap_or("")
                .to_string();
            let prev_hash = parsed
                .get("prev_hash")
                .and_then(|v| v.as_str())
                .unwrap_or("")
                .to_string();
            let cause = parsed.get("cause").and_then(|v| v.as_u64()).map(FactId);

            let fact_id = FactId(fact_id_num);
            let entry = AuditEntry {
                fact_id,
                // 安全：fact_type 是静态字符串名（来自 Fact::type_name），
                // 此处使用泄漏扩展生命周期。WAL 中的类型名都是已知的固定字符串，
                // 实际使用中应做类型映射表。这里做简化处理。
                fact_type: FACT_TYPE_STATIC_TABLE
                    .iter()
                    .copied()
                    .find(|t| *t == fact_type)
                    .unwrap_or("Unknown"),
                logical_time,
                content_hash: content_hash.clone(),
                prev_hash: prev_hash.clone(),
                cause,
            };

            self.index.insert(fact_id, self.entries.len());
            self.entries.push(entry);

            // 重算链哈希（验证并更新 last_hash）
            let combined = format!("{}{}", prev_hash, content_hash);
            self.last_hash = blake3::hash(combined.as_bytes()).to_hex().to_string();

            // 更新时钟到最大值
            if logical_time > self.clock.current() {
                // 逻辑时钟通过 tick 推进；从 WAL 恢复时直接设置到最大值+1
                // 这里我们用一个小技巧：多次 tick 直到达到目标
                while self.clock.current() < logical_time {
                    self.clock.tick();
                }
            }
        }

        self.wal_path = Some(path.to_path_buf());
        Ok(())
    }

    /// 从 tier1 WAL 加载审计状态并验证哈希链完整性（两套 WAL 合并）
    ///
    /// 读取 tier1 WAL 文件（统一格式，含 `content_hash`/`prev_hash`/`chain_hash`），
    /// 重建审计器的 `entries`、`index`、`last_hash` 和 `clock`，同时**验证**
    /// 哈希链完整性。
    ///
    /// # 验证内容
    /// 1. **content_hash 验证**：重算每个 Fact 的哈希，与 WAL 中存储的 `content_hash` 比对
    /// 2. **prev_hash 链接验证**：每条记录的 `prev_hash` 应等于前一条的 `chain_hash`
    /// 3. **chain_hash 验证**：重算 `blake3(prev_hash + content_hash)`，与存储的 `chain_hash` 比对
    ///
    /// # 向后兼容
    /// - **新格式**（有 `chain_hash` 字段）：执行完整哈希链验证
    /// - **旧格式**（无 `chain_hash` 字段）：仅重建状态，不验证哈希（发出警告）
    ///
    /// # 参数
    /// - `path`: tier1 WAL 文件路径
    ///
    /// # 返回值
    /// - `Ok(())`：加载并验证成功
    /// - `Err(LoadError)`：文件读取失败或哈希链验证失败
    ///
    /// # 错误类型
    /// - [`LoadError::IoError`]：文件读取失败
    /// - [`LoadError::ContentHashMismatch`]：Fact 内容被篡改（content_hash 不匹配）
    /// - [`LoadError::ChainBroken`]：哈希链断裂（prev_hash 链接不正确）
    /// - [`LoadError::ChainHashMismatch`]：链哈希不匹配（chain_hash 被篡改）
    pub fn load_from_tier1_wal(&mut self, path: &std::path::Path) -> Result<(), LoadError> {
        use evorule_reactor::read_wal_with_hash;

        let records = read_wal_with_hash(path).map_err(|e| LoadError::IoError(e.to_string()))?;

        // 清空当前状态
        self.entries.clear();
        self.index.clear();
        self.last_hash = String::from("genesis");
        self.last_audited_version = 0;
        self.audit_new_count = 0;

        let mut prev_hash = String::from("genesis");
        let mut has_hash_fields = false;
        let mut max_logical_time = 0u64;

        for (idx, record) in records.iter().enumerate() {
            let fact = &record.fact;
            let fact_id = fact.id();
            let fact_type = fact.type_name();

            // 检查是否有哈希字段（新格式）
            if record.chain_hash.is_some() {
                has_hash_fields = true;
            }

            // 验证 content_hash（新格式）
            if let Some(stored_content) = &record.content_hash {
                let recomputed = hash::fact_hash(fact)
                    .map_err(|e| LoadError::HashError(format!("fact[{}]: {}", idx, e)))?;
                if stored_content != &recomputed {
                    return Err(LoadError::ContentHashMismatch {
                        index: idx,
                        fact_id,
                        stored: stored_content.clone(),
                        recomputed,
                    });
                }
            }

            // 验证 prev_hash 链接（新格式）
            if let Some(stored_prev) = &record.prev_hash {
                if stored_prev != &prev_hash {
                    return Err(LoadError::ChainBroken {
                        index: idx,
                        fact_id,
                        stored_prev: stored_prev.clone(),
                        expected_prev: prev_hash.clone(),
                    });
                }
            }

            // 重算链哈希
            let content_hash = record
                .content_hash
                .clone()
                .unwrap_or_else(|| hash::fact_hash(fact).unwrap_or_else(|_| String::new()));
            let combined = format!("{}{}", prev_hash, content_hash);
            let recomputed_chain = blake3::hash(combined.as_bytes()).to_hex().to_string();

            // 验证 chain_hash（新格式）
            if let Some(stored_chain) = &record.chain_hash {
                if stored_chain != &recomputed_chain {
                    return Err(LoadError::ChainHashMismatch {
                        index: idx,
                        fact_id,
                        stored: stored_chain.clone(),
                        recomputed: recomputed_chain.clone(),
                    });
                }
            }

            prev_hash = recomputed_chain.clone();

            // 构建 AuditEntry
            let logical_time = idx as u64 + 1;
            let cause = extract_cause(fact);
            let entry = AuditEntry {
                fact_id,
                fact_type: FACT_TYPE_STATIC_TABLE
                    .iter()
                    .copied()
                    .find(|t| *t == fact_type)
                    .unwrap_or("Unknown"),
                logical_time,
                content_hash,
                prev_hash: if record.prev_hash.is_some() {
                    record.prev_hash.clone().unwrap_or_default()
                } else {
                    // 旧格式：使用重算的 prev_hash（初始为 genesis）
                    String::from("genesis")
                },
                cause,
            };

            self.index.insert(fact_id, idx);
            self.entries.push(entry);

            if logical_time > max_logical_time {
                max_logical_time = logical_time;
            }
        }

        // 恢复末尾哈希
        self.last_hash = if has_hash_fields {
            // 新格式：使用最后一条记录的 chain_hash
            records
                .last()
                .and_then(|r| r.chain_hash.clone())
                .unwrap_or(prev_hash)
        } else {
            // 旧格式：使用重算的链哈希
            prev_hash
        };

        // 同步逻辑时钟
        while self.clock.current() < max_logical_time {
            self.clock.tick();
        }

        // 更新已审计版本（从最后一条 Fact 推断）
        self.last_audited_version = records.len() as u64;

        if !has_hash_fields {
            tracing::warn!(
                path = %path.display(),
                "load_from_tier1_wal: 旧格式 WAL（无哈希字段），仅重建状态，未验证哈希链"
            );
        } else {
            tracing::info!(
                path = %path.display(),
                entries = self.entries.len(),
                last_hash = %self.last_hash,
                "load_from_tier1_wal: 加载并验证审计链成功"
            );
        }

        Ok(())
    }

    /// 导出审计链为 JSON 格式（P04）
    ///
    /// 返回包含所有审计条目的 JSON 字符串，可用于跨实例迁移或离线分析。
    ///
    /// # 导出格式
    /// ```json
    /// {
    ///   "version": "1.0",
    ///   "last_hash": "<末尾链哈希>",
    ///   "last_audited_version": <已审计版本>,
    ///   "entry_count": <条目数>,
    ///   "entries": [ { ...AuditEntry }, ... ]
    /// }
    /// ```
    ///
    /// # 安全说明
    /// 导出数据包含完整的哈希链信息，可作为审计证据。
    /// 调用方应妥善保护导出数据，防止被篡改。
    pub fn export(&self) -> String {
        let entries_json: Vec<serde_json::Value> = self
            .entries
            .iter()
            .map(|e| {
                serde_json::json!({
                    "fact_id": e.fact_id.0,
                    "fact_type": e.fact_type,
                    "logical_time": e.logical_time,
                    "content_hash": e.content_hash,
                    "prev_hash": e.prev_hash,
                    "cause": e.cause.map(|c| c.0),
                })
            })
            .collect();

        let export = serde_json::json!({
            "version": "1.0",
            "last_hash": self.last_hash,
            "last_audited_version": self.last_audited_version,
            "entry_count": self.entries.len(),
            "entries": entries_json,
        });

        serde_json::to_string_pretty(&export).unwrap_or_else(|_| String::from("{}"))
    }

    /// 从 JSON 导入审计链（P04）
    ///
    /// 覆盖当前审计状态，导入外部审计数据。
    ///
    /// # 参数
    /// `json_str`：由 `export()` 产生的 JSON 字符串
    ///
    /// # 返回
    /// - `Ok(())`：导入成功
    /// - `Err(String)`：JSON 解析或字段缺失错误
    ///
    /// # 安全注意事项
    /// 1. 导入操作会**完全覆盖**当前审计链，具有破坏性
    /// 2. 调用方应确保导入数据来自可信来源
    /// 3. 导入后会自动调用 `verify()` 校验哈希链完整性
    /// 4. `fact_type` 字段会被映射到 `FACT_TYPE_STATIC_TABLE` 中的已知类型，
    ///    未知类型会被替换为 `"Unknown"`（保留哈希链但丢失类型语义）
    pub fn import(&mut self, json_str: &str) -> Result<(), String> {
        let parsed: serde_json::Value =
            serde_json::from_str(json_str).map_err(|e| format!("JSON parse error: {}", e))?;

        let version = parsed
            .get("version")
            .and_then(|v| v.as_str())
            .ok_or_else(|| "Missing 'version' field".to_string())?;

        if version != "1.0" {
            return Err(format!("Unsupported version: {} (expected 1.0)", version));
        }

        let entries_arr = parsed
            .get("entries")
            .and_then(|e| e.as_array())
            .ok_or_else(|| "Missing 'entries' array".to_string())?;

        // 清空当前状态
        self.entries.clear();
        self.index.clear();
        self.last_hash = String::from("genesis");
        self.last_audited_version = 0;
        self.audit_new_count = 0;

        for (idx, entry_val) in entries_arr.iter().enumerate() {
            let fact_id_num = entry_val
                .get("fact_id")
                .and_then(|v| v.as_u64())
                .ok_or_else(|| format!("Entry {} missing 'fact_id'", idx))?;
            let fact_type_str = entry_val
                .get("fact_type")
                .and_then(|v| v.as_str())
                .ok_or_else(|| format!("Entry {} missing 'fact_type'", idx))?;
            let logical_time = entry_val
                .get("logical_time")
                .and_then(|v| v.as_u64())
                .unwrap_or(0);
            let content_hash = entry_val
                .get("content_hash")
                .and_then(|v| v.as_str())
                .unwrap_or("")
                .to_string();
            let prev_hash = entry_val
                .get("prev_hash")
                .and_then(|v| v.as_str())
                .unwrap_or("")
                .to_string();
            let cause = entry_val.get("cause").and_then(|v| v.as_u64()).map(FactId);

            // 复用 FACT_TYPE_STATIC_TABLE 将字符串映射为 &'static str
            let fact_type: &'static str = FACT_TYPE_STATIC_TABLE
                .iter()
                .copied()
                .find(|t| *t == fact_type_str)
                .unwrap_or("Unknown");

            let entry = AuditEntry {
                fact_id: FactId(fact_id_num),
                fact_type,
                logical_time,
                content_hash,
                prev_hash,
                cause,
            };

            self.index.insert(entry.fact_id, idx);
            self.entries.push(entry);
        }

        // 恢复末尾哈希和已审计版本
        self.last_hash = parsed
            .get("last_hash")
            .and_then(|v| v.as_str())
            .unwrap_or("genesis")
            .to_string();
        self.last_audited_version = parsed
            .get("last_audited_version")
            .and_then(|v| v.as_u64())
            .unwrap_or(0);

        // 同步逻辑时钟到导入数据中的最大 logical_time
        let max_logical_time = self
            .entries
            .iter()
            .map(|e| e.logical_time)
            .max()
            .unwrap_or(0);
        while self.clock.current() < max_logical_time {
            self.clock.tick();
        }

        tracing::info!(
            entries = self.entries.len(),
            last_audited_version = self.last_audited_version,
            "import: 审计链导入完成"
        );

        Ok(())
    }

    /// 导入后立即验证审计链完整性（P04 便捷方法）
    ///
    /// 等价于 `import()` 后调用 `verify()`，返回导入是否成功且审计链完整。
    pub fn import_and_verify(&mut self, json_str: &str) -> Result<bool, String> {
        self.import(json_str)?;
        let valid = self.verify();
        if !valid {
            tracing::warn!(
                entries = self.entries.len(),
                "import_and_verify: 导入后审计链验证失败，数据可能已损坏"
            );
        }
        Ok(valid)
    }

    /// 导出压缩的审计链（P05）
    ///
    /// 使用 gzip 压缩 [`export`](Self::export) 产生的 JSON 数据，
    /// 减少传输和存储大小。压缩率通常可达 5-10 倍（取决于条目数和哈希重复度）。
    ///
    /// # 返回
    /// - `Ok(Vec<u8>)`：gzip 压缩字节流
    /// - `Err(String)`：压缩失败（极少见，通常是内存不足）
    ///
    /// # 使用场景
    /// - 网络传输：减少带宽占用
    /// - 长期归档：减少存储成本
    /// - 跨实例迁移：批量传输
    pub fn export_compressed(&self) -> Result<Vec<u8>, String> {
        use flate2::write::GzEncoder;
        use flate2::Compression;
        use std::io::Write;

        let export_str = self.export();
        let mut encoder = GzEncoder::new(Vec::new(), Compression::default());
        encoder
            .write_all(export_str.as_bytes())
            .map_err(|e| format!("Compression write error: {}", e))?;
        encoder
            .finish()
            .map_err(|e| format!("Compression finish error: {}", e))
    }

    /// 从压缩数据导入审计链（P05）
    ///
    /// 解压 gzip 数据后调用 [`import`](Self::import)。
    ///
    /// # 参数
    /// `compressed`：由 [`export_compressed`](Self::export_compressed) 产生的 gzip 字节流
    ///
    /// # 返回
    /// - `Ok(())`：解压并导入成功
    /// - `Err(String)`：解压失败或导入数据格式错误
    ///
    /// # 安全说明
    /// 与 [`import`](Self::import) 相同，调用方应确保数据来自可信来源。
    /// 此方法**不会**自动调用 `verify()`，如需验证请使用
    /// [`import_compressed_and_verify`](Self::import_compressed_and_verify)。
    pub fn import_compressed(&mut self, compressed: &[u8]) -> Result<(), String> {
        use flate2::read::GzDecoder;
        use std::io::Read;

        let mut decoder = GzDecoder::new(compressed);
        let mut decompressed = String::new();
        decoder
            .read_to_string(&mut decompressed)
            .map_err(|e| format!("Decompression error: {}", e))?;

        self.import(&decompressed)
    }

    /// 从压缩数据导入并立即验证（P05 便捷方法）
    ///
    /// 等价于 [`import_compressed`](Self::import_compressed) 后调用 [`verify`](Self::verify)，
    /// 返回导入是否成功且审计链完整。
    pub fn import_compressed_and_verify(&mut self, compressed: &[u8]) -> Result<bool, String> {
        self.import_compressed(compressed)?;
        let valid = self.verify();
        if !valid {
            tracing::warn!(
                entries = self.entries.len(),
                "import_compressed_and_verify: 导入后审计链验证失败"
            );
        }
        Ok(valid)
    }
}

/// Fact 类型名静态表（用于 WAL 加载时获取 &'static str）
///
/// 包含所有已知的 Fact 变体类型名，加载 WAL 时从中查找匹配项，
/// 以获取 `&'static str` 引用。
const FACT_TYPE_STATIC_TABLE: &[&str] = &[
    "StateTransition",
    "Command",
    "PayloadUpdate",
    "IoRequest",
    "IoResponse",
    "ControlSignal",
    "Error",
    "Unknown",
];

/// 从 Fact 中提取因果父 Fact ID
///
/// - [`Fact::StateTransition`] / [`Fact::IoRequest`]：返回其 `cause` 字段
/// - [`Fact::IoResponse`]：返回其 `request_id`（语义上为因果前驱）
/// - 其他变体：返回 `None`
fn extract_cause(fact: &Fact) -> Option<FactId> {
    match fact {
        Fact::StateTransition { cause, .. } => Some(*cause),
        Fact::IoRequest { cause, .. } => Some(*cause),
        Fact::IoResponse { request_id, .. } => Some(*request_id),
        _ => None,
    }
}

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::panic, clippy::expect_used)]
    use super::*;
    use evorule_reactor::{Fact, FactId, FactsLog, IoType};
    use evorule_tcb::JsonValue;

    fn make_facts_log() -> FactsLog {
        FactsLog::new()
    }

    #[test]
    fn test_auditor_basic_chain() {
        let log = make_facts_log();
        let f0 = Fact::PayloadUpdate {
            id: FactId(1),
            path: "k1".into(),
            value: JsonValue::string("v1"),
        };
        let id0 = f0.id();
        log.append(f0).unwrap();

        let f1 = Fact::StateTransition {
            id: FactId(2),
            cause: id0,
            new_payload: JsonValue::empty_object(),
            new_queue: vec![],
        };
        log.append(f1).unwrap();

        let mut auditor = Auditor::new(log);
        let n = auditor.audit_new();
        assert_eq!(n, 2);
        assert!(auditor.verify());
        assert_eq!(auditor.entries().len(), 2);
    }

    #[test]
    fn test_auditor_causal_chain() {
        let log = make_facts_log();

        let f0 = Fact::PayloadUpdate {
            id: FactId(1),
            path: "root".into(),
            value: JsonValue::from(0i64),
        };
        let id0 = f0.id();
        log.append(f0).unwrap();

        let f1 = Fact::StateTransition {
            id: FactId(2),
            cause: id0,
            new_payload: JsonValue::empty_object(),
            new_queue: vec![],
        };
        let id1 = f1.id();
        log.append(f1).unwrap();

        let f2 = Fact::IoRequest {
            id: FactId(3),
            cause: id1,
            io_type: IoType::http_get(),
            params: JsonValue::empty_object(),
        };
        let id2 = f2.id();
        log.append(f2).unwrap();

        let mut auditor = Auditor::new(log);
        auditor.audit_new();

        let chain = auditor.causal_chain(id2);
        assert_eq!(chain.len(), 3);
        assert_eq!(chain[0].fact_id, id2);
        assert_eq!(chain[1].fact_id, id1);
        assert_eq!(chain[2].fact_id, id0);
    }

    #[test]
    fn test_auditor_wal_persist_and_reload() {
        let tmp =
            std::env::temp_dir().join(format!("auditor_wal_test_{}.jsonl", std::process::id()));
        let _ = std::fs::remove_file(&tmp);

        // 第一轮：通过 tier1 WAL 写入（两套 WAL 合并后的统一路径）
        {
            let log = FactsLog::with_wal(&tmp).expect("create wal");
            let f0 = Fact::PayloadUpdate {
                id: FactId(1),
                path: "a".into(),
                value: JsonValue::from(1i64),
            };
            let f1 = Fact::PayloadUpdate {
                id: FactId(2),
                path: "b".into(),
                value: JsonValue::from(2i64),
            };
            log.append(f0).unwrap();
            log.append(f1).unwrap();

            let mut auditor = Auditor::new(log);
            let n = auditor.audit_new();
            assert_eq!(n, 2);
            assert!(auditor.verify());
        }

        // 第二轮：从 tier1 WAL 恢复（带哈希链验证）
        {
            let log = make_facts_log();
            let mut auditor = Auditor::new(log);
            auditor.load_from_tier1_wal(&tmp).expect("load tier1 wal");
            assert_eq!(auditor.entries().len(), 2);
            assert!(auditor.verify());
        }

        let _ = std::fs::remove_file(&tmp);
    }

    /// 验证 load_from_tier1_wal 能检测 Fact 内容篡改
    #[test]
    fn test_load_from_tier1_wal_detects_content_tamper() {
        let tmp =
            std::env::temp_dir().join(format!("auditor_tamper_test_{}.jsonl", std::process::id()));
        let _ = std::fs::remove_file(&tmp);

        // 写入正常 WAL
        {
            let log = FactsLog::with_wal(&tmp).expect("create wal");
            let f = Fact::PayloadUpdate {
                id: FactId(1),
                path: "a".into(),
                value: JsonValue::from(42i64),
            };
            log.append(f).unwrap();
        }

        // 篡改 WAL 文件中的 Fact 内容（修改 value 字段）
        {
            let content = std::fs::read_to_string(&tmp).expect("read wal");
            let tampered = content.replace("42", "999");
            std::fs::write(&tmp, tampered).expect("write tampered wal");
        }

        // 加载应失败（content_hash 不匹配）
        let log = make_facts_log();
        let mut auditor = Auditor::new(log);
        let result = auditor.load_from_tier1_wal(&tmp);
        assert!(result.is_err(), "篡改 Fact 内容应被检测到");
        match result.unwrap_err() {
            LoadError::ContentHashMismatch { .. } => {}
            other => panic!("期望 ContentHashMismatch，得到: {other}"),
        }

        let _ = std::fs::remove_file(&tmp);
    }

    /// 验证 load_from_tier1_wal 能检测哈希链断裂
    #[test]
    fn test_load_from_tier1_wal_detects_chain_break() {
        let tmp =
            std::env::temp_dir().join(format!("auditor_chain_break_{}.jsonl", std::process::id()));
        let _ = std::fs::remove_file(&tmp);

        // 写入 2 条 Fact
        {
            let log = FactsLog::with_wal(&tmp).expect("create wal");
            let f0 = Fact::PayloadUpdate {
                id: FactId(1),
                path: "a".into(),
                value: JsonValue::from(1i64),
            };
            let f1 = Fact::PayloadUpdate {
                id: FactId(2),
                path: "b".into(),
                value: JsonValue::from(2i64),
            };
            log.append(f0).unwrap();
            log.append(f1).unwrap();
        }

        // 篡改第二条记录的 prev_hash（破坏链）
        {
            let content = std::fs::read_to_string(&tmp).expect("read wal");
            let lines: Vec<&str> = content.lines().collect();
            // 修改第二行的 prev_hash 字段
            let tampered_line2 = lines[1].replace("\"prev_hash\":\"", "\"prev_hash\":\"tampered");
            let tampered = format!("{}\n{}\n", lines[0], tampered_line2);
            std::fs::write(&tmp, tampered).expect("write tampered wal");
        }

        // 加载应失败（prev_hash 链接不匹配）
        let log = make_facts_log();
        let mut auditor = Auditor::new(log);
        let result = auditor.load_from_tier1_wal(&tmp);
        assert!(result.is_err(), "哈希链断裂应被检测到");
        match result.unwrap_err() {
            LoadError::ChainBroken { .. } | LoadError::ChainHashMismatch { .. } => {}
            other => panic!("期望 ChainBroken 或 ChainHashMismatch，得到: {other}"),
        }

        let _ = std::fs::remove_file(&tmp);
    }

    #[test]
    #[allow(deprecated)]
    fn test_auditor_wal_nonexistent_file() {
        let log = make_facts_log();
        let mut auditor = Auditor::new(log);
        let result = auditor.load_from_wal(std::path::Path::new("/nonexistent/path/wal.jsonl"));
        assert!(result.is_ok());
        assert_eq!(auditor.entries().len(), 0);
    }

    #[test]
    fn test_auditor_wal_incremental() {
        let tmp =
            std::env::temp_dir().join(format!("auditor_wal_incr_{}.jsonl", std::process::id()));
        let _ = std::fs::remove_file(&tmp);

        // 使用 tier1 WAL 持久化（两套 WAL 合并后的统一路径）
        let log = FactsLog::with_wal(&tmp).expect("create wal");
        let mut auditor = Auditor::new(log.clone());

        // 第一批
        let f1 = Fact::PayloadUpdate {
            id: FactId(1),
            path: "k1".into(),
            value: JsonValue::string("v1"),
        };
        log.append(f1).unwrap();
        assert_eq!(auditor.audit_new(), 1);

        // 第二批
        let f2 = Fact::PayloadUpdate {
            id: FactId(2),
            path: "k2".into(),
            value: JsonValue::string("v2"),
        };
        log.append(f2).unwrap();
        assert_eq!(auditor.audit_new(), 1);

        // 从 tier1 WAL 恢复应得到 2 条（带哈希链验证）
        let mut auditor2 = Auditor::new(make_facts_log());
        auditor2.load_from_tier1_wal(&tmp).expect("load tier1 wal");
        assert_eq!(auditor2.entries().len(), 2);
        assert!(auditor2.verify());

        let _ = std::fs::remove_file(&tmp);
    }

    #[test]
    fn test_auditor_empty() {
        let log = make_facts_log();
        let mut auditor = Auditor::new(log);
        assert_eq!(auditor.audit_new(), 0);
        assert!(auditor.verify());
        assert_eq!(auditor.entries().len(), 0);
    }

    #[test]
    fn test_auditor_incremental_idempotent() {
        let log = make_facts_log();
        let f = Fact::PayloadUpdate {
            id: FactId(1),
            path: "x".into(),
            value: JsonValue::string("y"),
        };
        log.append(f).unwrap();

        let mut auditor = Auditor::new(log);
        assert_eq!(auditor.audit_new(), 1);
        // 再次调用 audit_new，无新事实，应返回 0
        assert_eq!(auditor.audit_new(), 0);
        assert_eq!(auditor.audit_new(), 0);
        assert_eq!(auditor.entries().len(), 1);
    }

    #[test]
    fn test_auditor_causal_chain_not_found() {
        let log = make_facts_log();
        let f = Fact::PayloadUpdate {
            id: FactId(1),
            path: "x".into(),
            value: JsonValue::string("y"),
        };
        log.append(f).unwrap();

        let mut auditor = Auditor::new(log);
        auditor.audit_new();

        // 不存在的 fact_id
        let chain = auditor.causal_chain(FactId(999));
        assert!(chain.is_empty());
    }

    #[test]
    fn test_auditor_causal_chain_root() {
        let log = make_facts_log();
        let f = Fact::PayloadUpdate {
            id: FactId(1),
            path: "x".into(),
            value: JsonValue::string("y"),
        };
        let id = f.id();
        log.append(f).unwrap();

        let mut auditor = Auditor::new(log);
        auditor.audit_new();

        // 根因（没有 cause）的因果链只有自己
        let chain = auditor.causal_chain(id);
        assert_eq!(chain.len(), 1);
        assert_eq!(chain[0].fact_id, id);
        assert!(chain[0].cause.is_none());
    }

    #[test]
    fn test_auditor_report_format() {
        let log = make_facts_log();
        let f = Fact::PayloadUpdate {
            id: FactId(1),
            path: "k".into(),
            value: JsonValue::string("v"),
        };
        log.append(f).unwrap();

        let mut auditor = Auditor::new(log);
        auditor.audit_new();

        let report = auditor.report();
        let parsed: serde_json::Value = serde_json::from_str(&report).unwrap();
        assert_eq!(parsed["entry_count"], 1);
        assert_eq!(parsed["entries"].as_array().unwrap().len(), 1);
        assert!(parsed["last_hash"].is_string());
        assert!(parsed["last_audited_version"].is_number());
    }

    #[test]
    fn test_auditor_verify_empty_chain() {
        let log = make_facts_log();
        let auditor = Auditor::new(log);
        assert!(auditor.verify());
    }

    #[test]
    fn test_auditor_io_response_causal_link() {
        let log = make_facts_log();
        let req = Fact::IoRequest {
            id: FactId(10),
            cause: FactId(1),
            io_type: IoType::http_get(),
            params: JsonValue::empty_object(),
        };
        let req_id = req.id();
        log.append(req).unwrap();

        let resp = Fact::IoResponse {
            id: FactId(11),
            request_id: req_id,
            result: JsonValue::string("ok"),
            error: None,
        };
        let resp_id = resp.id();
        log.append(resp).unwrap();

        let mut auditor = Auditor::new(log);
        auditor.audit_new();

        // IoResponse 的因果父是 request_id
        let chain = auditor.causal_chain(resp_id);
        assert_eq!(chain.len(), 2);
        assert_eq!(chain[0].fact_id, resp_id);
        assert_eq!(chain[1].fact_id, req_id);
    }

    #[test]
    fn test_auditor_last_hash_genesis() {
        let log = make_facts_log();
        let auditor = Auditor::new(log);
        // 初始 last_hash 为 "genesis"
        // 通过 report 间接验证
        let report = auditor.report();
        let parsed: serde_json::Value = serde_json::from_str(&report).unwrap();
        assert_eq!(parsed["last_hash"], "genesis");
    }

    #[test]
    #[allow(deprecated)]
    fn test_auditor_wal_with_invalid_lines() {
        let tmp =
            std::env::temp_dir().join(format!("auditor_wal_bad_{}.jsonl", std::process::id()));
        let _ = std::fs::remove_file(&tmp);

        // 手动写入混合有效和无效行的 WAL
        use std::io::Write;
        let mut file = std::fs::File::create(&tmp).unwrap();
        writeln!(file, "not valid json").unwrap();
        writeln!(
            file,
            r#"{{"fact_id": 5, "fact_type": "PayloadUpdate", "logical_time": 3, "content_hash": "abc", "prev_hash": "genesis", "cause": null}}"#
        )
        .unwrap();
        writeln!(file).unwrap(); // 空行
        drop(file);

        let log = make_facts_log();
        let mut auditor = Auditor::new(log);
        auditor.load_from_wal(&tmp).expect("load wal");

        // 只有 1 条有效条目
        assert_eq!(auditor.entries().len(), 1);
        assert_eq!(auditor.entries()[0].fact_id, FactId(5));
        assert_eq!(auditor.entries()[0].fact_type, "PayloadUpdate");

        let _ = std::fs::remove_file(&tmp);
    }

    // === P06 实时审计验证测试 ===

    #[test]
    fn test_auto_verify_default_disabled() {
        let log = make_facts_log();
        let auditor = Auditor::new(log);
        assert!(
            !auditor.is_auto_verify_enabled(),
            "auto_verify 默认应为 false"
        );
    }

    #[test]
    fn test_auto_verify_enabled() {
        let log = make_facts_log();
        let auditor = Auditor::new_with_auto_verify(log, true, 1000, 1);
        assert!(auditor.is_auto_verify_enabled());
    }

    #[test]
    fn test_auto_verify_runs_after_audit_new() {
        let log = make_facts_log();
        log.append(Fact::Command {
            id: FactId(1),
            instruction: JsonValue::empty_object(),
        })
        .unwrap();
        log.append(Fact::StateTransition {
            id: FactId(2),
            cause: FactId(1),
            new_payload: JsonValue::empty_object(),
            new_queue: vec![],
        })
        .unwrap();

        // 启用自动验证
        let mut auditor = Auditor::new_with_auto_verify(log, true, 1000, 1);
        let n = auditor.audit_new();
        assert_eq!(n, 2);
        // 验证审计链应通过
        assert!(auditor.verify());
    }

    #[test]
    fn test_auto_verify_threshold_skips_verification() {
        let log = make_facts_log();

        // 添加 3 条事实
        for i in 0..3 {
            log.append(Fact::Command {
                id: FactId(i as u64 + 1),
                instruction: JsonValue::empty_object(),
            })
            .unwrap();
        }

        // 设置阈值为 2（条目数 3 > 2，应跳过验证）
        let mut auditor = Auditor::new_with_auto_verify(log, true, 2, 1);
        auditor.audit_new();
        // 条目数超过阈值，但审计链本身是正确的
        assert_eq!(auditor.entries().len(), 3);
        assert!(auditor.verify()); // 手动验证仍然通过
    }

    #[test]
    fn test_auto_verify_threshold_zero_means_no_limit() {
        let log = make_facts_log();

        for i in 0..100 {
            log.append(Fact::Command {
                id: FactId(i as u64 + 1),
                instruction: JsonValue::empty_object(),
            })
            .unwrap();
        }

        // 阈值 0 表示不限制
        let mut auditor = Auditor::new_with_auto_verify(log, true, 0, 1);
        auditor.audit_new();
        assert_eq!(auditor.entries().len(), 100);
        assert!(auditor.verify());
    }

    #[test]
    fn test_auto_verify_interval_skips_intermediate_calls() {
        let log = make_facts_log();

        // 第一次 audit_new 前添加事实
        log.append(Fact::Command {
            id: FactId(1),
            instruction: JsonValue::empty_object(),
        })
        .unwrap();

        // 间隔为 3，只在第 3、6、9... 次执行验证
        let mut auditor = Auditor::new_with_auto_verify(log, true, 0, 3);
        auditor.audit_new(); // count=1，不验证
        assert_eq!(auditor.audit_new_count, 1);

        // 再添加事实
        auditor
            .facts_log
            .append(Fact::Command {
                id: FactId(2),
                instruction: JsonValue::empty_object(),
            })
            .unwrap();
        auditor.audit_new(); // count=2，不验证
        assert_eq!(auditor.audit_new_count, 2);

        // 再添加事实
        auditor
            .facts_log
            .append(Fact::Command {
                id: FactId(3),
                instruction: JsonValue::empty_object(),
            })
            .unwrap();
        auditor.audit_new(); // count=3，验证
        assert_eq!(auditor.audit_new_count, 3);
        assert_eq!(auditor.entries().len(), 3);
    }

    #[test]
    fn test_set_auto_verify_after_creation() {
        let log = make_facts_log();
        let mut auditor = Auditor::new(log);
        assert!(!auditor.is_auto_verify_enabled());

        auditor.set_auto_verify(true, 500, 10);
        assert!(auditor.is_auto_verify_enabled());
    }

    #[test]
    fn test_auto_verify_interval_zero_becomes_one() {
        let log = make_facts_log();
        // 间隔 0 会被自动修正为 1
        let auditor = Auditor::new_with_auto_verify(log, true, 0, 0);
        // 通过行为间接验证：添加一条事实后 audit_new 应执行验证（因为间隔=1）
        drop(auditor);
    }

    #[test]
    fn test_auto_verify_empty_entries_skips() {
        let log = make_facts_log();
        // 没有 fact 时 audit_new 应返回 0 且不验证
        let mut auditor = Auditor::new_with_auto_verify(log, true, 0, 1);
        let n = auditor.audit_new();
        assert_eq!(n, 0);
        assert_eq!(auditor.entries().len(), 0);
        // verify 在空条目时返回 true（无链可验证）
        assert!(auditor.verify());
    }

    #[test]
    fn test_auto_verify_detects_corruption() {
        let log = make_facts_log();
        log.append(Fact::Command {
            id: FactId(1),
            instruction: JsonValue::empty_object(),
        })
        .unwrap();
        log.append(Fact::Command {
            id: FactId(2),
            instruction: JsonValue::empty_object(),
        })
        .unwrap();

        let mut auditor = Auditor::new_with_auto_verify(log, true, 0, 1);
        auditor.audit_new();

        // 篡改第一条审计条目的 prev_hash
        auditor.entries[0].prev_hash = "tampered".to_string();

        // verify 应检测到篡改
        assert!(!auditor.verify());
    }

    // ===== P04: 导出/导入 测试 =====

    fn build_auditor_with_entries() -> Auditor {
        let log = make_facts_log();
        let f0 = Fact::PayloadUpdate {
            id: FactId(10),
            path: "k1".into(),
            value: JsonValue::string("v1"),
        };
        let id0 = f0.id();
        log.append(f0).unwrap();

        let f1 = Fact::StateTransition {
            id: FactId(11),
            cause: id0,
            new_payload: JsonValue::empty_object(),
            new_queue: vec![],
        };
        log.append(f1).unwrap();

        let mut auditor = Auditor::new(log);
        auditor.audit_new();
        auditor
    }

    #[test]
    fn test_export_format() {
        let auditor = build_auditor_with_entries();
        let json_str = auditor.export();

        let parsed: serde_json::Value = serde_json::from_str(&json_str).unwrap();
        assert_eq!(parsed["version"], "1.0");
        assert!(parsed["last_hash"].is_string());
        assert_eq!(parsed["last_audited_version"], 2); // 断点 11: PayloadUpdate(v1) + StateTransition(v2)
        assert_eq!(parsed["entry_count"], 2);
        assert!(parsed["entries"].is_array());
        assert_eq!(parsed["entries"].as_array().unwrap().len(), 2);

        // 检查第一个条目字段
        let e0 = &parsed["entries"][0];
        assert_eq!(e0["fact_id"], 10);
        assert_eq!(e0["fact_type"], "PayloadUpdate");
        assert_eq!(e0["prev_hash"], "genesis");
        assert!(e0["cause"].is_null());
    }

    #[test]
    fn test_export_empty_auditor() {
        let log = make_facts_log();
        let auditor = Auditor::new(log);
        let json_str = auditor.export();

        let parsed: serde_json::Value = serde_json::from_str(&json_str).unwrap();
        assert_eq!(parsed["version"], "1.0");
        assert_eq!(parsed["entry_count"], 0);
        assert_eq!(parsed["entries"], serde_json::Value::Array(vec![]));
        assert_eq!(parsed["last_hash"], "genesis");
    }

    #[test]
    fn test_import_export_roundtrip() {
        let auditor = build_auditor_with_entries();
        let export_str = auditor.export();
        let original_verify = auditor.verify();
        assert!(original_verify);

        // 导入到新 auditor
        let log2 = make_facts_log();
        let mut imported = Auditor::new(log2);
        let result = imported.import(&export_str);
        assert!(result.is_ok());

        // 验证数据一致性
        assert_eq!(imported.entries().len(), 2);
        assert_eq!(imported.entries()[0].fact_id, FactId(10));
        assert_eq!(imported.entries()[1].fact_id, FactId(11));
        assert_eq!(
            imported.entries()[0].content_hash,
            auditor.entries()[0].content_hash
        );
        assert_eq!(imported.entries()[0].prev_hash, "genesis");
        assert_eq!(imported.last_hash, auditor.last_hash);
        assert_eq!(imported.last_audited_version, auditor.last_audited_version);

        // 导入后哈希链应保持完整
        assert!(imported.verify());
    }

    #[test]
    fn test_import_version_check() {
        let log = make_facts_log();
        let mut auditor = Auditor::new(log);

        let bad_version = r#"{"version": "2.0", "entries": []}"#;
        let result = auditor.import(bad_version);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("Unsupported version"));
    }

    #[test]
    fn test_import_missing_version() {
        let log = make_facts_log();
        let mut auditor = Auditor::new(log);

        let no_version = r#"{"entries": []}"#;
        let result = auditor.import(no_version);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("version"));
    }

    #[test]
    fn test_import_missing_entries() {
        let log = make_facts_log();
        let mut auditor = Auditor::new(log);

        let no_entries = r#"{"version": "1.0"}"#;
        let result = auditor.import(no_entries);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("entries"));
    }

    #[test]
    fn test_import_invalid_json() {
        let log = make_facts_log();
        let mut auditor = Auditor::new(log);

        let result = auditor.import("not a valid json {{{");
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("JSON parse error"));
    }

    #[test]
    fn test_import_unknown_fact_type_becomes_unknown() {
        let log = make_facts_log();
        let mut auditor = Auditor::new(log);

        // 构造包含未知 fact_type 的导入数据
        let import_data = r#"{
            "version": "1.0",
            "last_hash": "anyhash",
            "last_audited_version": 1,
            "entries": [
                {
                    "fact_id": 99,
                    "fact_type": "SomeUnknownType",
                    "logical_time": 5,
                    "content_hash": "abc",
                    "prev_hash": "genesis",
                    "cause": null
                }
            ]
        }"#;

        let result = auditor.import(import_data);
        assert!(result.is_ok());
        assert_eq!(auditor.entries().len(), 1);
        assert_eq!(auditor.entries()[0].fact_type, "Unknown");
        assert_eq!(auditor.entries()[0].fact_id, FactId(99));
    }

    #[test]
    fn test_import_resets_state() {
        // 原审计器有 2 个条目
        let mut auditor = build_auditor_with_entries();
        assert_eq!(auditor.entries().len(), 2);

        // 导入空数据
        let empty_export = r#"{
            "version": "1.0",
            "last_hash": "genesis",
            "last_audited_version": 0,
            "entries": []
        }"#;
        let result = auditor.import(empty_export);
        assert!(result.is_ok());
        assert_eq!(auditor.entries().len(), 0);
        assert_eq!(auditor.last_hash, "genesis");
        assert_eq!(auditor.last_audited_version, 0);
    }

    #[test]
    fn test_import_and_verify_detects_corruption() {
        let log = make_facts_log();
        let mut auditor = Auditor::new(log);

        // 构造 prev_hash 不连续的损坏数据
        let corrupted = r#"{
            "version": "1.0",
            "last_hash": "fakehash",
            "last_audited_version": 1,
            "entries": [
                {
                    "fact_id": 1,
                    "fact_type": "Command",
                    "logical_time": 1,
                    "content_hash": "hash1",
                    "prev_hash": "genesis",
                    "cause": null
                },
                {
                    "fact_id": 2,
                    "fact_type": "Command",
                    "logical_time": 2,
                    "content_hash": "hash2",
                    "prev_hash": "WRONG_PREV_HASH",
                    "cause": null
                }
            ]
        }"#;

        let result = auditor.import_and_verify(corrupted);
        assert!(result.is_ok());
        // 导入成功但验证应失败
        assert!(!result.unwrap());
    }

    #[test]
    fn test_import_preserves_causal_chain() {
        let auditor = build_auditor_with_entries();
        let export_str = auditor.export();

        // 验证原审计器的因果链
        let original_chain = auditor.causal_chain(FactId(11));
        assert_eq!(original_chain.len(), 2);

        // 导入到新审计器
        let log2 = make_facts_log();
        let mut imported = Auditor::new(log2);
        imported.import(&export_str).unwrap();

        // 因果链应可正确追溯
        let chain = imported.causal_chain(FactId(11));
        assert_eq!(chain.len(), 2);
        assert_eq!(chain[0].fact_id, FactId(11));
        assert_eq!(chain[1].fact_id, FactId(10));
    }

    #[test]
    fn test_import_resets_audit_new_count() {
        // 原审计器已多次调用 audit_new，计数 > 0
        let mut auditor = build_auditor_with_entries();
        auditor.audit_new(); // 再次调用，count = 2
        assert_eq!(auditor.audit_new_count, 2);

        // 导入应重置 audit_new_count
        let export_str = auditor.export();
        let log2 = make_facts_log();
        let mut imported = Auditor::new(log2);
        imported.import(&export_str).unwrap();
        assert_eq!(imported.audit_new_count, 0);
    }

    // ===== P05: 压缩导出/导入 测试 =====

    #[test]
    fn test_export_compressed_returns_valid_gzip() {
        let auditor = build_auditor_with_entries();
        let compressed = auditor.export_compressed().unwrap();

        // gzip magic number: 0x1f 0x8b
        assert!(compressed.len() >= 2);
        assert_eq!(compressed[0], 0x1f);
        assert_eq!(compressed[1], 0x8b);
    }

    #[test]
    fn test_export_compressed_smaller_than_json() {
        // 构造较大的审计链（100 条目）
        let log = make_facts_log();
        for i in 0..100 {
            log.append(Fact::Command {
                id: FactId(i as u64 + 1),
                instruction: JsonValue::empty_object(),
            })
            .unwrap();
        }
        let mut auditor = Auditor::new(log);
        auditor.audit_new();

        let json_size = auditor.export().len();
        let compressed = auditor.export_compressed().unwrap();
        let compressed_size = compressed.len();

        // 压缩后应明显小于 JSON（通常 < 30%）
        // 由于 fact_type 等字段重复度高，压缩率应很好
        assert!(
            compressed_size < json_size,
            "compressed {} should be < json {}",
            compressed_size,
            json_size
        );
        // 压缩率至少应小于 50%
        let ratio = compressed_size as f64 / json_size as f64;
        assert!(ratio < 0.5, "compression ratio {} should be < 0.5", ratio);
    }

    #[test]
    fn test_import_compressed_roundtrip() {
        let auditor = build_auditor_with_entries();
        let compressed = auditor.export_compressed().unwrap();
        let original_verify = auditor.verify();
        assert!(original_verify);

        // 解压并导入到新 auditor
        let log2 = make_facts_log();
        let mut imported = Auditor::new(log2);
        let result = imported.import_compressed(&compressed);
        assert!(result.is_ok());

        // 验证数据一致性
        assert_eq!(imported.entries().len(), 2);
        assert_eq!(imported.entries()[0].fact_id, FactId(10));
        assert_eq!(imported.entries()[1].fact_id, FactId(11));
        assert_eq!(imported.entries()[0].prev_hash, "genesis");
        assert_eq!(imported.last_hash, auditor.last_hash);

        // 导入后哈希链应保持完整
        assert!(imported.verify());
    }

    #[test]
    fn test_import_compressed_invalid_gzip() {
        let log = make_facts_log();
        let mut auditor = Auditor::new(log);

        // 非 gzip 数据应返回错误
        let bad_data = b"this is not gzip data at all";
        let result = auditor.import_compressed(bad_data);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("Decompression error"));
    }

    #[test]
    fn test_import_compressed_empty_data() {
        let log = make_facts_log();
        let mut auditor = Auditor::new(log);

        // 空数据应返回错误
        let result = auditor.import_compressed(&[]);
        assert!(result.is_err());
    }

    #[test]
    fn test_import_compressed_and_verify_detects_corruption() {
        // 构造损坏的 JSON 数据（prev_hash 不连续）
        let corrupted_json = r#"{
            "version": "1.0",
            "last_hash": "fakehash",
            "last_audited_version": 1,
            "entries": [
                {
                    "fact_id": 1,
                    "fact_type": "Command",
                    "logical_time": 1,
                    "content_hash": "hash1",
                    "prev_hash": "genesis",
                    "cause": null
                },
                {
                    "fact_id": 2,
                    "fact_type": "Command",
                    "logical_time": 2,
                    "content_hash": "hash2",
                    "prev_hash": "WRONG",
                    "cause": null
                }
            ]
        }"#;

        // 先压缩损坏的 JSON
        use flate2::write::GzEncoder;
        use flate2::Compression;
        use std::io::Write;
        let mut encoder = GzEncoder::new(Vec::new(), Compression::default());
        encoder.write_all(corrupted_json.as_bytes()).unwrap();
        let corrupted_compressed = encoder.finish().unwrap();

        // 导入并验证应返回 Ok(false)
        let log = make_facts_log();
        let mut auditor = Auditor::new(log);
        let result = auditor.import_compressed_and_verify(&corrupted_compressed);
        assert!(result.is_ok());
        assert!(!result.unwrap());
    }

    #[test]
    fn test_export_compressed_empty_auditor() {
        let log = make_facts_log();
        let auditor = Auditor::new(log);
        let compressed = auditor.export_compressed().unwrap();

        // 空审计器也能正常压缩（gzip 头 + 空 entries 数组）
        assert!(!compressed.is_empty());

        // 解压后应为有效 JSON
        let log2 = make_facts_log();
        let mut imported = Auditor::new(log2);
        imported.import_compressed(&compressed).unwrap();
        assert_eq!(imported.entries().len(), 0);
        assert_eq!(imported.last_hash, "genesis");
    }

    #[test]
    fn test_compressed_preserves_causal_chain() {
        let auditor = build_auditor_with_entries();
        let compressed = auditor.export_compressed().unwrap();

        // 导入到新审计器
        let log2 = make_facts_log();
        let mut imported = Auditor::new(log2);
        imported.import_compressed(&compressed).unwrap();

        // 因果链应可正确追溯
        let chain = imported.causal_chain(FactId(11));
        assert_eq!(chain.len(), 2);
        assert_eq!(chain[0].fact_id, FactId(11));
        assert_eq!(chain[1].fact_id, FactId(10));
    }

    #[test]
    fn test_compressed_roundtrip_large_chain() {
        // 大批量数据的压缩/解压往返测试
        // 构造真实因果链：Fact1 → Fact2 → ... → Fact501（IoRequest 链）
        let log = make_facts_log();

        // 第 1 个：PayloadUpdate（根，无 cause）
        log.append(Fact::PayloadUpdate {
            id: FactId(1),
            path: "root".into(),
            value: JsonValue::from(0i64),
        })
        .unwrap();

        // 第 2..501：IoRequest 链，每个 cause 指向上一个
        for i in 1..500 {
            log.append(Fact::IoRequest {
                id: FactId(i as u64 + 1),
                cause: FactId(i as u64),
                io_type: evorule_reactor::IoType::http_get(),
                params: JsonValue::empty_object(),
            })
            .unwrap();
        }

        let mut auditor = Auditor::new(log);
        auditor.audit_new();
        assert_eq!(auditor.entries().len(), 500);

        // 压缩 → 解压 → 导入
        let compressed = auditor.export_compressed().unwrap();
        let log2 = make_facts_log();
        let mut imported = Auditor::new(log2);
        imported.import_compressed(&compressed).unwrap();

        // 验证数据完整
        assert_eq!(imported.entries().len(), 500);
        assert!(imported.verify());

        // 因果链应可从末尾追溯到根（长度 500）
        let chain = imported.causal_chain(FactId(500));
        assert_eq!(chain.len(), 500);
        assert_eq!(chain[0].fact_id, FactId(500)); // 末尾
        assert_eq!(chain[499].fact_id, FactId(1)); // 根
    }
}