zenith-runtime 0.1.0

//! ChangeSet 引擎
//!
//! ChangeSet 是 Zenith 运行时中实现"零丢包热更新"的核心机制。
//! 它以状态机的方式驱动一次配置/代码/数据面的切换过程，
//! 支持原子激活、超时回滚与双写（Shadow）验证。
//!
//! ## 状态迁移（Prepare → Commit / Rollback）
//! ```text
//! Prepare ──► Validate ──► ResourceProof ──► Shadow
//!                                                │
//!                                                ▼
//!                                          Activate
//!                                           │      │
//!                                           ▼      ▼
//!                                    StopOldAdmission  (rollback)
//!                                           │      │
//!                                           ▼      ▼
//!                                        Drain ──► Commit
//!                                                  │
//!                                                  ▼
//!                                               Rollback
//! ```
//!
//! ## 设计要点
//! - 每个阶段都校验前置条件，非法迁移被拒绝
//! - 支持基于时间戳的超时自动回滚
//! - 生成号（generation）追踪每次激活，支持 A/B 双 Bank
//! - 全程无堆分配的热路径字段

use core::time::Duration;
use std::fmt;

use thiserror::Error;

/// ChangeSet 错误
#[derive(Debug, Error, PartialEq, Eq)]
pub enum ChangeSetError {
    /// 非法状态转换
    #[error("invalid changeset transition: from={from:?} to={to:?}")]
    InvalidTransition {
        /// 当前状态
        from: ChangeSetState,
        /// 目标状态
        to: ChangeSetState,
    },

    /// 前置条件未满足
    #[error("prerequisite not met: {0}")]
    PrerequisiteNotMet(&'static str),

    /// 资源证明失败
    #[error("resource proof failed: {0}")]
    ResourceProofFailed(&'static str),

    /// 已超时
    #[error("changeset timeout: {0:?}")]
    Timeout(Duration),

    /// 未超时（rollback_on_timeout 在未超时时调用的语义错误）
    #[error("changeset not timed out yet: elapsed={0:?}")]
    NotTimedOut(Duration),

    /// 版本冲突
    #[error("generation conflict: current={current}, expected={expected}")]
    GenerationConflict {
        /// 当前生成号
        current: u64,
        /// 期望的生成号
        expected: u64,
    },

    /// 已关闭
    #[error("changeset already finalized")]
    Finalized,

    /// 阴影验证失败
    #[error("shadow verification failed: {0}")]
    ShadowVerificationFailed(&'static str),

    /// 停止准入失败
    #[error("stop old admission failed: {0}")]
    StopAdmissionFailed(&'static str),

    /// 排空失败
    #[error("drain failed: {0}")]
    DrainFailed(&'static str),
}

/// ChangeSet 状态枚举
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ChangeSetState {
    /// 准备阶段（收集变更）
    Prepare,
    /// 校验阶段（语义/合法性校验）
    Validate,
    /// 资源证明阶段（确认资源充足）
    ResourceProof,
    /// 阴影阶段（双写验证）
    Shadow,
    /// 激活阶段（原子切换）
    Activate,
    /// 停止旧准入（切断旧流量）
    StopOldAdmission,
    /// 排空旧数据
    Drain,
    /// 提交
    Commit,
    /// 回滚
    Rollback,
}

impl ChangeSetState {
    /// 检查到目标状态的迁移是否合法
    #[inline]
    pub fn can_transition_to(self, to: ChangeSetState) -> bool {
        use ChangeSetState::*;
        matches!(
            (self, to),
            (Prepare, Validate)
                | (Validate, ResourceProof)
                | (ResourceProof, Shadow)
                | (Shadow, Activate)
                | (Activate, StopOldAdmission)
                | (StopOldAdmission, Drain)
                | (Drain, Commit)
                | (Activate, Rollback)
                | (StopOldAdmission, Rollback)
                | (Drain, Rollback)
                | (Prepare, Rollback)
                | (Validate, Rollback)
                | (ResourceProof, Rollback)
                | (Shadow, Rollback)
                | (Commit, Prepare)
                | (Rollback, Prepare)
        )
    }

    /// 是否为终态
    #[inline]
    pub fn is_terminal(self) -> bool {
        matches!(self, ChangeSetState::Commit | ChangeSetState::Rollback)
    }
}

impl fmt::Display for ChangeSetState {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            ChangeSetState::Prepare => write!(f, "Prepare"),
            ChangeSetState::Validate => write!(f, "Validate"),
            ChangeSetState::ResourceProof => write!(f, "ResourceProof"),
            ChangeSetState::Shadow => write!(f, "Shadow"),
            ChangeSetState::Activate => write!(f, "Activate"),
            ChangeSetState::StopOldAdmission => write!(f, "StopOldAdmission"),
            ChangeSetState::Drain => write!(f, "Drain"),
            ChangeSetState::Commit => write!(f, "Commit"),
            ChangeSetState::Rollback => write!(f, "Rollback"),
        }
    }
}

/// ChangeSet 结果
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ChangeSetOutcome {
    /// 成功提交
    Committed {
        /// 新版本生成号
        generation: u64,
    },
    /// 已回滚
    RolledBack {
        /// 回滚的目标版本
        generation: u64,
    },
}

/// ChangeSet 引擎
///
/// 一个 `ChangeSet` 实例对应一次"希望发生的变更"。
/// 通过状态机推进，每一步都需要显式调用对应方法。
#[derive(Debug, Clone)]
pub struct ChangeSet {
    /// 当前状态
    state: ChangeSetState,
    /// 目标生成号（变更后）
    target_generation: u64,
    /// 当前活跃生成号
    active_generation: u64,
    /// 激活前的生成号（rollback(None) 的默认回滚目标）
    previous_generation: u64,
    /// 超时配置
    timeout: Duration,
    /// 已执行步骤计数
    steps_completed: u32,
    /// 是否发生过回滚
    rolled_back: bool,
}

impl ChangeSet {
    /// 创建新的 ChangeSet
    ///
    /// # Arguments
    /// * `active_generation` - 当前线上生成号
    /// * `target_generation` - 本次变更的目标生成号
    pub fn new(active_generation: u64, target_generation: u64) -> Self {
        Self {
            state: ChangeSetState::Prepare,
            target_generation,
            active_generation,
            // 激活前 initial previous = active（尚未激活时的安全默认）
            previous_generation: active_generation,
            timeout: Duration::from_secs(30),
            steps_completed: 0,
            rolled_back: false,
        }
    }

    /// 设置超时
    pub fn with_timeout(mut self, timeout: Duration) -> Self {
        self.timeout = timeout;
        self
    }

    /// 当前状态
    #[inline]
    pub fn state(&self) -> ChangeSetState {
        self.state
    }

    /// 目标生成号
    #[inline]
    pub fn target_generation(&self) -> u64 {
        self.target_generation
    }

    /// 当前活跃生成号
    #[inline]
    pub fn active_generation(&self) -> u64 {
        self.active_generation
    }

    /// 已完成步骤数
    #[inline]
    pub fn steps_completed(&self) -> u32 {
        self.steps_completed
    }

    /// 是否已终止
    #[inline]
    pub fn is_finalized(&self) -> bool {
        self.state.is_terminal()
    }

    fn transition(
        &mut self,
        to: ChangeSetState,
    ) -> Result<(), ChangeSetError> {
        if self.state.is_terminal() {
            return Err(ChangeSetError::Finalized);
        }
        if !self.state.can_transition_to(to) {
            return Err(ChangeSetError::InvalidTransition { from: self.state, to });
        }
        self.state = to;
        self.steps_completed = self.steps_completed.saturating_add(1);
        Ok(())
    }

    fn check_generation(&self, expected: u64) -> Result<(), ChangeSetError> {
        if self.active_generation != expected {
            return Err(ChangeSetError::GenerationConflict {
                current: self.active_generation,
                expected,
            });
        }
        Ok(())
    }

    // ------------------------------------------------------------------
    // 阶段方法
    // ------------------------------------------------------------------

    /// Prepare：收集变更，进入 Prepare 阶段
    ///
    /// 要求：当前处于 Prepare 或已终止（Commit/Rollback）。
    pub fn prepare(&mut self) -> Result<(), ChangeSetError> {
        if self.state == ChangeSetState::Prepare {
            self.steps_completed = self.steps_completed.saturating_add(1);
            return Ok(());
        }
        // 允许从终态重启一次新的 Prepare
        if self.state.is_terminal() {
            self.state = ChangeSetState::Prepare;
            self.steps_completed = 1;
            self.rolled_back = false;
            return Ok(());
        }
        Err(ChangeSetError::InvalidTransition {
            from: self.state,
            to: ChangeSetState::Prepare,
        })
    }

    /// Validate：对变更做合法性校验
    pub fn validate(&mut self) -> Result<(), ChangeSetError> {
        self.transition(ChangeSetState::Validate)
    }

    /// ResourceProof：资源证明
    ///
    /// # Arguments
    /// * `check_fn` - 资源检查函数
    pub fn resource_proof<F>(&mut self, check_fn: F) -> Result<(), ChangeSetError>
    where
        F: FnOnce() -> Result<(), &'static str>,
    {
        let prev_state = self.state;
        self.transition(ChangeSetState::ResourceProof)?;
        if let Err(e) = check_fn() {
            // 验证失败时回退到前一状态，避免状态卡在 ResourceProof
            // 导致后续调用返回 InvalidTransition
            self.state = prev_state;
            return Err(ChangeSetError::ResourceProofFailed(e));
        }
        Ok(())
    }

    /// Shadow：进入双写验证
    ///
    /// # Arguments
    /// * `verify_fn` - 阴影验证函数
    pub fn shadow<F>(&mut self, verify_fn: F) -> Result<(), ChangeSetError>
    where
        F: FnOnce() -> Result<(), &'static str>,
    {
        let prev_state = self.state;
        self.transition(ChangeSetState::Shadow)?;
        if let Err(e) = verify_fn() {
            // 验证失败时回退到前一状态，与 resource_proof 同理
            self.state = prev_state;
            return Err(ChangeSetError::ShadowVerificationFailed(e));
        }
        Ok(())
    }

    /// Activate：原子激活新版本
    ///
    /// # Arguments
    /// * `expected_generation` - 期望的当前生成号（避免并发冲突）
    pub fn activate(
        &mut self,
        expected_generation: u64,
    ) -> Result<(), ChangeSetError> {
        self.check_generation(expected_generation)?;
        self.transition(ChangeSetState::Activate)?;
        // 记录激活前生成号：rollback(None) 必须回到此版本而非 target-1
        self.previous_generation = self.active_generation;
        self.active_generation = self.target_generation;
        Ok(())
    }

    /// StopOldAdmission：切断旧版本的新流量
    pub fn stop_old_admission(&mut self) -> Result<(), ChangeSetError> {
        self.transition(ChangeSetState::StopOldAdmission)
    }

    /// Drain：排空旧连接
    ///
    /// # Arguments
    /// * `drain_fn` - 排空回调，返回剩余未排空的字节数/连接数（None 表示完全排空）
    ///
    /// # 失败可重试
    /// 若 `drain_fn` 失败或返回仍有剩余，状态回退到 Drain 之前的状态，
    /// 调用方可再次调用 `drain` 重试，而非卡死在 Drain 状态收到
    /// [`ChangeSetError::InvalidTransition`]。
    pub fn drain<F>(&mut self, drain_fn: F) -> Result<(), ChangeSetError>
    where
        F: FnOnce() -> Result<Option<u64>, &'static str>,
    {
        let prev_state = self.state;
        self.transition(ChangeSetState::Drain)?;
        let remaining = drain_fn().map_err(|e| {
            // 回退状态：避免卡死在 Drain，再次 drain() 可重试
            self.state = prev_state;
            ChangeSetError::DrainFailed(e)
        })?;
        if remaining.is_some() {
            self.state = prev_state;
            return Err(ChangeSetError::DrainFailed("drain not fully complete"));
        }
        Ok(())
    }

    /// Commit：提交变更
    ///
    /// 返回最终结果。
    pub fn commit(&mut self) -> Result<ChangeSetOutcome, ChangeSetError> {
        self.transition(ChangeSetState::Commit)?;
        Ok(ChangeSetOutcome::Committed {
            generation: self.target_generation,
        })
    }

    /// Rollback：回滚到指定版本
    ///
    /// # Arguments
    /// * `to_generation` - 回滚到的版本；若为 `None` 则回到**激活前**版本
    ///   （`activate()` 记录的 `previous_generation`，而非 `target_generation - 1`）
    pub fn rollback(
        &mut self,
        to_generation: Option<u64>,
    ) -> Result<ChangeSetOutcome, ChangeSetError> {
        // 允许从任意阶段触发回滚
        if !self.state.is_terminal() && self.state != ChangeSetState::Prepare {
            self.state = ChangeSetState::Rollback;
            self.steps_completed = self.steps_completed.saturating_add(1);
        } else if self.state == ChangeSetState::Prepare {
            // Prepare 阶段直接标记为回滚终态
            self.state = ChangeSetState::Rollback;
            self.steps_completed = self.steps_completed.saturating_add(1);
        } else {
            return Err(ChangeSetError::Finalized);
        }
        let target = to_generation.unwrap_or(self.previous_generation);
        self.active_generation = target;
        self.rolled_back = true;
        Ok(ChangeSetOutcome::RolledBack { generation: target })
    }

    /// 基于时间戳的超时检查
    ///
    /// # Arguments
    /// * `elapsed` - 已耗时
    pub fn check_timeout(&self, elapsed: Duration) -> Result<(), ChangeSetError> {
        if elapsed > self.timeout {
            return Err(ChangeSetError::Timeout(self.timeout));
        }
        Ok(())
    }

    /// 超时触发自动回滚
    ///
    /// # 语义
    /// - `elapsed > timeout`：执行回滚（回到激活前版本），返回 `Ok(RolledBack)`
    /// - 未超时：返回 `Err(NotTimedOut)`，状态机不变更
    pub fn rollback_on_timeout(
        &mut self,
        elapsed: Duration,
    ) -> Result<ChangeSetOutcome, ChangeSetError> {
        match self.check_timeout(elapsed) {
            Ok(()) => Err(ChangeSetError::NotTimedOut(elapsed)),
            Err(ChangeSetError::Timeout(_)) => self.rollback(None),
            Err(e) => Err(e),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_changeset_initial_state() {
        let cs = ChangeSet::new(1, 2);
        assert_eq!(cs.state(), ChangeSetState::Prepare);
        assert_eq!(cs.active_generation(), 1);
        assert_eq!(cs.target_generation(), 2);
        assert!(!cs.is_finalized());
    }

    #[test]
    fn test_full_happy_path() {
        let mut cs = ChangeSet::new(1, 2);
        cs.prepare().unwrap();
        cs.validate().unwrap();
        cs.resource_proof(|| Ok(())).unwrap();
        cs.shadow(|| Ok(())).unwrap();
        cs.activate(1).unwrap();
        assert_eq!(cs.active_generation(), 2);
        cs.stop_old_admission().unwrap();
        cs.drain(|| Ok(None)).unwrap();
        let outcome = cs.commit().unwrap();
        assert!(matches!(outcome, ChangeSetOutcome::Committed { generation: 2 }));
        assert!(cs.is_finalized());
    }

    #[test]
    fn test_invalid_transition() {
        let mut cs = ChangeSet::new(1, 2);
        // 不能从 Prepare 直接跳到 Activate
        let err = cs.activate(1).unwrap_err();
        assert!(matches!(
            err,
            ChangeSetError::InvalidTransition {
                from: ChangeSetState::Prepare,
                to: ChangeSetState::Activate,
            }
        ));
    }

    #[test]
    fn test_resource_proof_failure() {
        let mut cs = ChangeSet::new(1, 2);
        cs.prepare().unwrap();
        cs.validate().unwrap();
        let err = cs
            .resource_proof(|| Err("out of memory"))
            .unwrap_err();
        assert!(matches!(err, ChangeSetError::ResourceProofFailed("out of memory")));
        // 验证失败后状态回退到前一状态（Validate），而非卡在 ResourceProof
        assert_eq!(cs.state(), ChangeSetState::Validate);
        // 可以重试 resource_proof 而不会 InvalidTransition
        cs.resource_proof(|| Ok(())).unwrap();
        assert_eq!(cs.state(), ChangeSetState::ResourceProof);
    }

    #[test]
    fn test_shadow_failure() {
        let mut cs = ChangeSet::new(1, 2);
        cs.prepare().unwrap();
        cs.validate().unwrap();
        cs.resource_proof(|| Ok(())).unwrap();
        let err = cs.shadow(|| Err("hash mismatch")).unwrap_err();
        assert!(matches!(
            err,
            ChangeSetError::ShadowVerificationFailed("hash mismatch")
        ));
        // 验证失败后状态回退到前一状态（ResourceProof），可重试
        assert_eq!(cs.state(), ChangeSetState::ResourceProof);
        cs.shadow(|| Ok(())).unwrap();
        assert_eq!(cs.state(), ChangeSetState::Shadow);
    }

    #[test]
    fn test_activate_generation_conflict() {
        let mut cs = ChangeSet::new(1, 2);
        cs.prepare().unwrap();
        cs.validate().unwrap();
        cs.resource_proof(|| Ok(())).unwrap();
        cs.shadow(|| Ok(())).unwrap();
        // 传入错误的当前生成号
        let err = cs.activate(99).unwrap_err();
        assert!(matches!(
            err,
            ChangeSetError::GenerationConflict {
                current: 1,
                expected: 99,
            }
        ));
    }

    #[test]
    fn test_rollback_from_activate() {
        let mut cs = ChangeSet::new(1, 2);
        cs.prepare().unwrap();
        cs.validate().unwrap();
        cs.resource_proof(|| Ok(())).unwrap();
        cs.shadow(|| Ok(())).unwrap();
        cs.activate(1).unwrap();
        let outcome = cs.rollback(Some(1)).unwrap();
        assert!(matches!(
            outcome,
            ChangeSetOutcome::RolledBack { generation: 1 }
        ));
        assert!(cs.is_finalized());
    }

    #[test]
    fn test_rollback_default_generation() {
        let mut cs = ChangeSet::new(10, 15);
        cs.prepare().unwrap();
        cs.validate().unwrap();
        cs.resource_proof(|| Ok(())).unwrap();
        cs.shadow(|| Ok(())).unwrap();
        cs.activate(10).unwrap();
        let outcome = cs.rollback(None).unwrap();
        // 默认回到激活前版本 = 10（而非 target - 1 = 14）
        assert!(matches!(
            outcome,
            ChangeSetOutcome::RolledBack { generation: 10 }
        ));
        assert_eq!(cs.active_generation(), 10);
    }

    #[test]
    fn test_rollback_on_timeout_actually_rolls_back() {
        // 已超时：必须真正回滚到激活前版本
        let mut cs = ChangeSet::new(3, 7).with_timeout(Duration::from_millis(5));
        cs.prepare().unwrap();
        cs.validate().unwrap();
        cs.resource_proof(|| Ok(())).unwrap();
        cs.shadow(|| Ok(())).unwrap();
        cs.activate(3).unwrap();
        let outcome = cs.rollback_on_timeout(Duration::from_millis(10)).unwrap();
        assert!(matches!(
            outcome,
            ChangeSetOutcome::RolledBack { generation: 3 }
        ));
        assert_eq!(cs.active_generation(), 3);
        assert!(cs.is_finalized());
    }

    #[test]
    fn test_rollback_on_timeout_not_timed_out() {
        // 未超时：返回 NotTimedOut，状态机不变更
        let mut cs = ChangeSet::new(1, 2).with_timeout(Duration::from_secs(30));
        cs.prepare().unwrap();
        cs.validate().unwrap();
        let err = cs
            .rollback_on_timeout(Duration::from_millis(1))
            .unwrap_err();
        assert!(matches!(err, ChangeSetError::NotTimedOut(_)));
        assert_eq!(cs.state(), ChangeSetState::Validate);
        assert!(!cs.is_finalized());
    }

    #[test]
    fn test_drain_failure() {
        let mut cs = ChangeSet::new(1, 2);
        cs.prepare().unwrap();
        cs.validate().unwrap();
        cs.resource_proof(|| Ok(())).unwrap();
        cs.shadow(|| Ok(())).unwrap();
        cs.activate(1).unwrap();
        cs.stop_old_admission().unwrap();
        let err = cs.drain(|| Ok(Some(42))).unwrap_err();
        assert!(matches!(err, ChangeSetError::DrainFailed("drain not fully complete")));
    }

    #[test]
    fn test_timeout() {
        let cs = ChangeSet::new(1, 2).with_timeout(Duration::from_millis(1));
        let elapsed = Duration::from_millis(10);
        let err = cs.check_timeout(elapsed).unwrap_err();
        assert!(matches!(err, ChangeSetError::Timeout(_)));
    }

    #[test]
    fn test_steps_counter() {
        let mut cs = ChangeSet::new(1, 2);
        assert_eq!(cs.steps_completed(), 0);
        cs.prepare().unwrap();
        assert_eq!(cs.steps_completed(), 1);
        cs.validate().unwrap();
        assert_eq!(cs.steps_completed(), 2);
    }

    #[test]
    fn test_prepare_idempotent() {
        let mut cs = ChangeSet::new(1, 2);
        cs.prepare().unwrap();
        cs.prepare().unwrap(); // 再次 prepare 应成功
        assert_eq!(cs.state(), ChangeSetState::Prepare);
    }

    #[test]
    fn test_prepare_after_finalized() {
        let mut cs = ChangeSet::new(1, 2);
        cs.prepare().unwrap();
        cs.validate().unwrap();
        cs.resource_proof(|| Ok(())).unwrap();
        cs.shadow(|| Ok(())).unwrap();
        cs.activate(1).unwrap();
        cs.stop_old_admission().unwrap();
        cs.drain(|| Ok(None)).unwrap();
        let _ = cs.commit().unwrap();
        assert!(cs.is_finalized());

        // 通过 prepare 重启新的变更
        cs.prepare().unwrap();
        assert_eq!(cs.state(), ChangeSetState::Prepare);
        assert!(!cs.is_finalized());
    }

    #[test]
    fn test_changeset_state_display() {
        let states = [
            ChangeSetState::Prepare,
            ChangeSetState::Validate,
            ChangeSetState::ResourceProof,
            ChangeSetState::Shadow,
            ChangeSetState::Activate,
            ChangeSetState::StopOldAdmission,
            ChangeSetState::Drain,
            ChangeSetState::Commit,
            ChangeSetState::Rollback,
        ];
        for state in states.iter() {
            let display = format!("{}", state);
            assert!(!display.is_empty());
        }
    }

    #[test]
    fn test_changeset_state_is_terminal() {
        assert!(ChangeSetState::Commit.is_terminal());
        assert!(ChangeSetState::Rollback.is_terminal());
        assert!(!ChangeSetState::Prepare.is_terminal());
        assert!(!ChangeSetState::Activate.is_terminal());
        assert!(!ChangeSetState::Drain.is_terminal());
    }

    #[test]
    fn test_changeset_state_can_transition() {
        use ChangeSetState::*;
        assert!(Prepare.can_transition_to(Validate));
        assert!(Validate.can_transition_to(ResourceProof));
        assert!(ResourceProof.can_transition_to(Shadow));
        assert!(Shadow.can_transition_to(Activate));
        assert!(Activate.can_transition_to(StopOldAdmission));
        assert!(StopOldAdmission.can_transition_to(Drain));
        assert!(Drain.can_transition_to(Commit));
        assert!(Activate.can_transition_to(Rollback));
        assert!(Commit.can_transition_to(Prepare));
        assert!(Rollback.can_transition_to(Prepare));
        assert!(!Prepare.can_transition_to(Activate));
        assert!(!Commit.can_transition_to(Activate));
    }

    #[test]
    fn test_changeset_outcome_debug() {
        let committed = ChangeSetOutcome::Committed { generation: 42 };
        let debug_str = format!("{:?}", committed);
        assert!(!debug_str.is_empty());
        assert!(debug_str.contains("42"));

        let rolled_back = ChangeSetOutcome::RolledBack { generation: 10 };
        let debug_str = format!("{:?}", rolled_back);
        assert!(!debug_str.is_empty());
        assert!(debug_str.contains("10"));
    }

    #[test]
    fn test_changeset_error_display() {
        let err = ChangeSetError::Timeout(Duration::from_secs(30));
        let display = format!("{}", err);
        assert!(!display.is_empty());
        assert!(display.contains("timeout"));

        let err = ChangeSetError::Finalized;
        let display = format!("{}", err);
        assert!(!display.is_empty());
    }

    #[test]
    fn test_changeset_error_debug() {
        let err = ChangeSetError::InvalidTransition {
            from: ChangeSetState::Prepare,
            to: ChangeSetState::Commit,
        };
        let debug_str = format!("{:?}", err);
        assert!(!debug_str.is_empty());
    }

    #[test]
    fn test_changeset_with_timeout() {
        let cs = ChangeSet::new(1, 2).with_timeout(Duration::from_secs(60));
        let result = cs.check_timeout(Duration::from_secs(30));
        assert!(result.is_ok());
        let result = cs.check_timeout(Duration::from_secs(90));
        assert!(result.is_err());
    }

    #[test]
    fn test_rollback_from_prepare() {
        let mut cs = ChangeSet::new(5, 10);
        let outcome = cs.rollback(None).unwrap();
        assert!(matches!(outcome, ChangeSetOutcome::RolledBack { .. }));
        assert!(cs.is_finalized());
    }

    #[test]
    fn test_rollback_from_validate() {
        let mut cs = ChangeSet::new(5, 10);
        cs.prepare().unwrap();
        cs.validate().unwrap();
        let outcome = cs.rollback(Some(5)).unwrap();
        assert!(matches!(outcome, ChangeSetOutcome::RolledBack { generation: 5 }));
        assert!(cs.is_finalized());
    }

    #[test]
    fn test_rollback_when_already_finalized() {
        let mut cs = ChangeSet::new(1, 2);
        cs.prepare().unwrap();
        cs.validate().unwrap();
        cs.resource_proof(|| Ok(())).unwrap();
        cs.shadow(|| Ok(())).unwrap();
        cs.activate(1).unwrap();
        cs.stop_old_admission().unwrap();
        cs.drain(|| Ok(None)).unwrap();
        let _ = cs.commit().unwrap();
        assert!(cs.is_finalized());

        let result = cs.rollback(None);
        assert!(result.is_err());
        assert!(matches!(result.unwrap_err(), ChangeSetError::Finalized));
    }

    #[test]
    fn test_drain_error_propagation() {
        let mut cs = ChangeSet::new(1, 2);
        cs.prepare().unwrap();
        cs.validate().unwrap();
        cs.resource_proof(|| Ok(())).unwrap();
        cs.shadow(|| Ok(())).unwrap();
        cs.activate(1).unwrap();
        cs.stop_old_admission().unwrap();
        let err = cs.drain(|| Err("drain function failed")).unwrap_err();
        assert!(matches!(err, ChangeSetError::DrainFailed("drain function failed")));
    }

    #[test]
    fn test_stop_old_admission_from_activate() {
        let mut cs = ChangeSet::new(1, 2);
        cs.prepare().unwrap();
        cs.validate().unwrap();
        cs.resource_proof(|| Ok(())).unwrap();
        cs.shadow(|| Ok(())).unwrap();
        cs.activate(1).unwrap();
        assert_eq!(cs.state(), ChangeSetState::Activate);
        cs.stop_old_admission().unwrap();
        assert_eq!(cs.state(), ChangeSetState::StopOldAdmission);
    }

    #[test]
    fn test_rolled_back_flag() {
        let mut cs = ChangeSet::new(1, 2);
        assert!(!cs.rolled_back);
        let _ = cs.rollback(None);
        assert!(cs.rolled_back);
    }
}