moonpool_sim/chaos/

assertions.rs

//! Antithesis-style assertion macros and result tracking for simulation testing.
//!
//! This module provides 15 assertion macros for testing distributed system
//! properties. Assertions are tracked by `moonpool-assertions` (a dependency-free
//! accounting layer). When the `exploration` feature is on, that table lives in
//! `MAP_SHARED` memory so counts are visible across forked exploration timelines;
//! otherwise it is a plain heap table — the macros behave identically either way.
//!
//! Following the Antithesis principle: **assertions never crash your program**.
//! Always-type assertions log violations at ERROR level and record them via a
//! thread-local flag, allowing the simulation to continue running and discover
//! cascading failures. The simulation runner checks `has_always_violations()`
//! after each iteration to report failures through the normal result pipeline.
//!
//! # Assertion Kinds
//!
//! | Macro | Tracks | Panics | Forks |
//! |-------|--------|--------|-------|
//! | `assert_always!` | yes | no | no |
//! | `assert_always_or_unreachable!` | yes | no | no |
//! | `assert_sometimes!` | yes | no | on first success |
//! | `assert_reachable!` | yes | no | on first reach |
//! | `assert_unreachable!` | yes | no | no |
//! | `assert_always_greater_than!` | yes | no | no |
//! | `assert_always_greater_than_or_equal_to!` | yes | no | no |
//! | `assert_always_less_than!` | yes | no | no |
//! | `assert_always_less_than_or_equal_to!` | yes | no | no |
//! | `assert_sometimes_greater_than!` | yes | no | on watermark improvement |
//! | `assert_sometimes_greater_than_or_equal_to!` | yes | no | on watermark improvement |
//! | `assert_sometimes_less_than!` | yes | no | on watermark improvement |
//! | `assert_sometimes_less_than_or_equal_to!` | yes | no | on watermark improvement |
//! | `assert_sometimes_all!` | yes | no | on frontier advance |
//! | `assert_sometimes_each!` | yes | no | on discovery/quality |

use std::cell::Cell;
use std::collections::HashMap;

// =============================================================================
// Thread-local violation tracking (Antithesis-style: never panic)
// =============================================================================

thread_local! {
    static ALWAYS_VIOLATION_COUNT: Cell<u64> = const { Cell::new(0) };
    /// When set, the next call to [`reset_assertion_results`] is skipped.
    /// Used by multi-seed runs to prevent `SimWorld::create` from zeroing
    /// assertion state that the between-seed reset already handled (a selective
    /// reset under exploration, or accumulation without it).
    static SKIP_NEXT_ASSERTION_RESET: Cell<bool> = const { Cell::new(false) };
}

/// Record that an always-type assertion was violated during this iteration.
///
/// Called by always-type macros instead of panicking. The simulation runner
/// checks `has_always_violations()` after each iteration to report failures.
pub fn record_always_violation() {
    ALWAYS_VIOLATION_COUNT.with(|c| c.set(c.get() + 1));
}

/// Reset the violation counter. Must be called at the start of each iteration.
pub fn reset_always_violations() {
    ALWAYS_VIOLATION_COUNT.with(|c| c.set(0));
}

/// Check whether any always-type assertion was violated during this iteration.
#[must_use]
pub fn has_always_violations() -> bool {
    ALWAYS_VIOLATION_COUNT.with(|c| c.get() > 0)
}

/// Statistics for a tracked assertion.
///
/// Records the total number of times an assertion was checked and how many
/// times it succeeded, enabling calculation of success rates for probabilistic
/// properties in distributed systems.
#[derive(Debug, Clone, PartialEq)]
pub struct AssertionStats {
    /// Total number of times this assertion was evaluated
    pub total_checks: usize,
    /// Number of times the assertion condition was true
    pub successes: usize,
}

impl AssertionStats {
    /// Create new assertion statistics starting at zero.
    #[must_use]
    pub fn new() -> Self {
        Self {
            total_checks: 0,
            successes: 0,
        }
    }

    /// Calculate the success rate as a percentage (0.0 to 100.0).
    ///
    /// Returns 0.0 if no checks have been performed yet.
    #[must_use]
    pub fn success_rate(&self) -> f64 {
        if self.total_checks == 0 {
            0.0
        } else {
            let successes_u32 = u32::try_from(self.successes).unwrap_or(u32::MAX);
            let total_u32 = u32::try_from(self.total_checks).unwrap_or(u32::MAX);
            (f64::from(successes_u32) / f64::from(total_u32)) * 100.0
        }
    }

    /// Record a new assertion check with the given result.
    ///
    /// Increments `total_checks` and successes (if the result was true).
    pub fn record(&mut self, success: bool) {
        self.total_checks += 1;
        if success {
            self.successes += 1;
        }
    }
}

impl Default for AssertionStats {
    fn default() -> Self {
        Self::new()
    }
}

// =============================================================================
// Details formatting (log-only, never stored in shared memory)
// =============================================================================

/// Format key-value details for assertion logging.
///
/// Used by assertion macros to produce human-readable context on failure.
/// Output format: `key1=val1, key2=val2, ...`
/// Saturating conversion to `i64` for numeric assertion macros.
///
/// Accepts any integer type that implements [`TryInto<i64>`]. Falls back to
/// `i64::MAX` when the value is out of range. Mirrors the historical
/// `as i64` cast used in numeric assertion macros without triggering
/// `clippy::cast_*` lints at expansion sites.
pub fn to_i64_saturating<T>(value: T) -> i64
where
    T: TryInto<i64>,
{
    value.try_into().unwrap_or(i64::MAX)
}

/// Format a list of named values for assertion failure messages.
pub fn format_details(pairs: &[(&str, &dyn std::fmt::Display)]) -> String {
    pairs
        .iter()
        .map(|(k, v)| format!("{k}={v}"))
        .collect::<Vec<_>>()
        .join(", ")
}

// =============================================================================
// Thin backing wrappers (for $crate:: macro hygiene)
// =============================================================================

/// Boolean assertion backing wrapper.
///
/// Delegates to `moonpool_assertions::assertion_bool`.
/// Accepts both `&str` and `String` message arguments.
pub fn on_assertion_bool(
    msg: impl AsRef<str>,
    condition: bool,
    kind: moonpool_assertions::AssertKind,
    must_hit: bool,
) {
    moonpool_assertions::assertion_bool(kind, must_hit, condition, msg.as_ref());
}

/// Numeric assertion backing wrapper.
///
/// Delegates to `moonpool_assertions::assertion_numeric`.
/// Accepts both `&str` and `String` message arguments.
pub fn on_assertion_numeric(
    msg: impl AsRef<str>,
    value: i64,
    cmp: moonpool_assertions::AssertCmp,
    threshold: i64,
    kind: moonpool_assertions::AssertKind,
    maximize: bool,
) {
    moonpool_assertions::assertion_numeric(kind, cmp, maximize, value, threshold, msg.as_ref());
}

/// Compound boolean assertion backing wrapper.
///
/// Delegates to `moonpool_assertions::assertion_sometimes_all`.
pub fn on_assertion_sometimes_all(msg: impl AsRef<str>, named_bools: &[(&str, bool)]) {
    moonpool_assertions::assertion_sometimes_all(msg.as_ref(), named_bools);
}

/// Notify the exploration framework of a per-value bucketed assertion.
///
/// This delegates to moonpool-explorer's `EachBucket` infrastructure for
/// fork-based exploration with identity keys and quality watermarks.
pub fn on_sometimes_each(msg: &str, keys: &[(&str, i64)], quality: &[(&str, i64)]) {
    moonpool_assertions::assertion_sometimes_each(msg, keys, quality);
}

// =============================================================================
// Shared-memory-based result collection
// =============================================================================

/// Get current assertion statistics for all tracked assertions.
///
/// Reads from shared memory assertion slots. Returns a snapshot of assertion
/// results for reporting and validation.
#[must_use]
pub fn assertion_results() -> HashMap<String, AssertionStats> {
    let slots = moonpool_assertions::assertion_read_all();
    let mut results = HashMap::new();

    for slot in &slots {
        let total =
            usize::try_from(slot.pass_count.saturating_add(slot.fail_count)).unwrap_or(usize::MAX);
        if total == 0 {
            continue;
        }
        results.insert(
            slot.msg.clone(),
            AssertionStats {
                total_checks: total,
                successes: usize::try_from(slot.pass_count).unwrap_or(usize::MAX),
            },
        );
    }

    results
}

/// Request that the next call to [`reset_assertion_results`] be skipped.
///
/// Used by multi-seed runs: the between-seed reset preserves pass/fail counts
/// (selectively, under exploration, via the explorer's `prepare_next_seed`; or
/// by accumulation without it), so the full zero in `SimWorld::create` must be
/// suppressed.
pub fn skip_next_assertion_reset() {
    SKIP_NEXT_ASSERTION_RESET.with(|c| c.set(true));
}

/// Reset all assertion statistics.
///
/// Zeros the shared memory assertion table unless a skip was requested via
/// [`skip_next_assertion_reset`]. Should be called before each simulation
/// run to ensure clean state between consecutive simulations.
pub fn reset_assertion_results() {
    let skip = SKIP_NEXT_ASSERTION_RESET.with(|c| {
        let v = c.get();
        c.set(false); // always consume the flag
        v
    });
    if !skip {
        moonpool_assertions::reset();
    }
}

/// Validate all assertion contracts based on their kind.
///
/// Returns two vectors:
/// - **`always_violations`**: Definite bugs — always-type assertions that failed,
///   or unreachable code that was reached.  Safe to check with any iteration count.
/// - **`coverage_violations`**: Statistical — sometimes-type assertions that were
///   never satisfied, or reachable code that was never reached.  Only meaningful
///   with enough iterations for statistical coverage.
#[must_use]
pub fn validate_assertion_contracts() -> (Vec<String>, Vec<String>) {
    let mut always_violations = Vec::new();
    let mut coverage_violations = Vec::new();
    let slots = moonpool_assertions::assertion_read_all();

    for slot in &slots {
        let total = slot.pass_count.saturating_add(slot.fail_count);
        let kind = moonpool_assertions::AssertKind::from_u8(slot.kind);

        match kind {
            Some(moonpool_assertions::AssertKind::Always) => {
                if slot.fail_count > 0 {
                    always_violations.push(format!(
                        "assert_always!('{}') failed {} times out of {}",
                        slot.msg, slot.fail_count, total
                    ));
                }
                if slot.must_hit != 0 && total == 0 {
                    always_violations
                        .push(format!("assert_always!('{}') was never reached", slot.msg));
                }
            }
            Some(moonpool_assertions::AssertKind::AlwaysOrUnreachable) => {
                if slot.fail_count > 0 {
                    always_violations.push(format!(
                        "assert_always_or_unreachable!('{}') failed {} times out of {}",
                        slot.msg, slot.fail_count, total
                    ));
                }
            }
            Some(moonpool_assertions::AssertKind::Sometimes) => {
                if total > 0 && slot.pass_count == 0 {
                    coverage_violations.push(format!(
                        "assert_sometimes!('{}') has 0% success rate ({} checks)",
                        slot.msg, total
                    ));
                }
            }
            Some(moonpool_assertions::AssertKind::Reachable) => {
                if slot.pass_count == 0 {
                    coverage_violations.push(format!(
                        "assert_reachable!('{}') was never reached",
                        slot.msg
                    ));
                }
            }
            Some(moonpool_assertions::AssertKind::Unreachable) => {
                if slot.pass_count > 0 {
                    always_violations.push(format!(
                        "assert_unreachable!('{}') was reached {} times",
                        slot.msg, slot.pass_count
                    ));
                }
            }
            Some(moonpool_assertions::AssertKind::NumericAlways) => {
                if slot.fail_count > 0 {
                    always_violations.push(format!(
                        "numeric assert_always ('{}') failed {} times out of {}",
                        slot.msg, slot.fail_count, total
                    ));
                }
            }
            Some(moonpool_assertions::AssertKind::NumericSometimes) => {
                if total > 0 && slot.pass_count == 0 {
                    coverage_violations.push(format!(
                        "numeric assert_sometimes ('{}') has 0% success rate ({} checks)",
                        slot.msg, total
                    ));
                }
            }
            Some(moonpool_assertions::AssertKind::BooleanSometimesAll) | None => {
                // BooleanSometimesAll: no simple pass/fail violation contract
                // (the frontier tracking is the guidance mechanism)
            }
        }
    }

    (always_violations, coverage_violations)
}

// =============================================================================
// Assertion Macros
// =============================================================================

/// Assert that a condition is always true.
///
/// Tracks pass/fail in shared memory for cross-process visibility.
/// Does **not** panic — records the violation via `record_always_violation()`
/// and logs at ERROR level with the seed, following the Antithesis principle
/// that assertions never crash the program.
#[macro_export]
macro_rules! assert_always {
    ($condition:expr, $message:expr) => {
        let __msg = $message;
        let cond = $condition;
        $crate::chaos::assertions::on_assertion_bool(
            &__msg,
            cond,
            $crate::chaos::assertions::_re_export::AssertKind::Always,
            true,
        );
        if !cond {
            $crate::chaos::assertions::record_always_violation();
        }
    };
    ($condition:expr, $message:expr, { $($key:expr => $val:expr),+ $(,)? }) => {
        let __msg = $message;
        let cond = $condition;
        $crate::chaos::assertions::on_assertion_bool(
            &__msg,
            cond,
            $crate::chaos::assertions::_re_export::AssertKind::Always,
            true,
        );
        if !cond {
            $crate::chaos::assertions::record_always_violation();
            eprintln!(
                "[ASSERTION FAILED] {} (seed={}) | {}",
                __msg,
                $crate::current_sim_seed(),
                $crate::chaos::assertions::format_details(
                    &[ $(($key, &$val as &dyn std::fmt::Display)),+ ]
                )
            );
        }
    };
}

/// Assert that a condition is always true when reached, but the code path
/// need not be reached. Does not panic if never evaluated.
///
/// Does **not** panic on failure — records the violation and logs at ERROR level.
#[macro_export]
macro_rules! assert_always_or_unreachable {
    ($condition:expr, $message:expr) => {
        let __msg = $message;
        let cond = $condition;
        $crate::chaos::assertions::on_assertion_bool(
            &__msg,
            cond,
            $crate::chaos::assertions::_re_export::AssertKind::AlwaysOrUnreachable,
            false,
        );
        if !cond {
            $crate::chaos::assertions::record_always_violation();
        }
    };
    ($condition:expr, $message:expr, { $($key:expr => $val:expr),+ $(,)? }) => {
        let __msg = $message;
        let cond = $condition;
        $crate::chaos::assertions::on_assertion_bool(
            &__msg,
            cond,
            $crate::chaos::assertions::_re_export::AssertKind::AlwaysOrUnreachable,
            false,
        );
        if !cond {
            $crate::chaos::assertions::record_always_violation();
            eprintln!(
                "[ASSERTION FAILED] {} (seed={}) | {}",
                __msg,
                $crate::current_sim_seed(),
                $crate::chaos::assertions::format_details(
                    &[ $(($key, &$val as &dyn std::fmt::Display)),+ ]
                )
            );
        }
    };
}

/// Assert a condition that should sometimes be true, tracking stats and triggering exploration.
///
/// Does not panic. On first success, triggers a fork to explore alternate timelines.
#[macro_export]
macro_rules! assert_sometimes {
    ($condition:expr, $message:expr) => {
        $crate::chaos::assertions::on_assertion_bool(
            &$message,
            $condition,
            $crate::chaos::assertions::_re_export::AssertKind::Sometimes,
            true,
        );
    };
}

/// Assert that a code path is reachable (should be reached at least once).
///
/// Does not panic. On first reach, triggers a fork.
#[macro_export]
macro_rules! assert_reachable {
    ($message:expr) => {
        $crate::chaos::assertions::on_assertion_bool(
            &$message,
            true,
            $crate::chaos::assertions::_re_export::AssertKind::Reachable,
            true,
        );
    };
}

/// Assert that a code path should never be reached.
///
/// Does **not** panic — records the violation and logs at ERROR level.
/// Tracks in shared memory for reporting.
#[macro_export]
macro_rules! assert_unreachable {
    ($message:expr) => {
        let __msg = $message;
        $crate::chaos::assertions::on_assertion_bool(
            &__msg,
            true,
            $crate::chaos::assertions::_re_export::AssertKind::Unreachable,
            false,
        );
        $crate::chaos::assertions::record_always_violation();
    };
    ($message:expr, { $($key:expr => $val:expr),+ $(,)? }) => {
        let __msg = $message;
        $crate::chaos::assertions::on_assertion_bool(
            &__msg,
            true,
            $crate::chaos::assertions::_re_export::AssertKind::Unreachable,
            false,
        );
        $crate::chaos::assertions::record_always_violation();
        eprintln!(
            "[ASSERTION FAILED] {} | {}",
            __msg,
            $crate::chaos::assertions::format_details(
                &[ $(($key, &$val as &dyn std::fmt::Display)),+ ]
            )
        );
    };
}

/// Assert that `val > threshold` always holds.
///
/// Does **not** panic on failure — records the violation and logs at ERROR level.
#[macro_export]
macro_rules! assert_always_greater_than {
    ($val:expr, $thresh:expr, $message:expr) => {
        let __msg = $message;
        let __v = $crate::chaos::assertions::to_i64_saturating($val);
        let __t = $crate::chaos::assertions::to_i64_saturating($thresh);
        $crate::chaos::assertions::on_assertion_numeric(
            &__msg,
            __v,
            $crate::chaos::assertions::_re_export::AssertCmp::Gt,
            __t,
            $crate::chaos::assertions::_re_export::AssertKind::NumericAlways,
            false,
        );
        if !(__v > __t) {
            $crate::chaos::assertions::record_always_violation();
        }
    };
    ($val:expr, $thresh:expr, $message:expr, { $($key:expr => $dval:expr),+ $(,)? }) => {
        let __msg = $message;
        let __v = $crate::chaos::assertions::to_i64_saturating($val);
        let __t = $crate::chaos::assertions::to_i64_saturating($thresh);
        $crate::chaos::assertions::on_assertion_numeric(
            &__msg,
            __v,
            $crate::chaos::assertions::_re_export::AssertCmp::Gt,
            __t,
            $crate::chaos::assertions::_re_export::AssertKind::NumericAlways,
            false,
        );
        if !(__v > __t) {
            $crate::chaos::assertions::record_always_violation();
            eprintln!(
                "[ASSERTION FAILED] {} ({}>{} failed, seed={}) | {}",
                __msg, __v, __t,
                $crate::current_sim_seed(),
                $crate::chaos::assertions::format_details(
                    &[ $(($key, &$dval as &dyn std::fmt::Display)),+ ]
                )
            );
        }
    };
}

/// Assert that `val >= threshold` always holds.
///
/// Does **not** panic on failure — records the violation and logs at ERROR level.
#[macro_export]
macro_rules! assert_always_greater_than_or_equal_to {
    ($val:expr, $thresh:expr, $message:expr) => {
        let __msg = $message;
        let __v = $crate::chaos::assertions::to_i64_saturating($val);
        let __t = $crate::chaos::assertions::to_i64_saturating($thresh);
        $crate::chaos::assertions::on_assertion_numeric(
            &__msg,
            __v,
            $crate::chaos::assertions::_re_export::AssertCmp::Ge,
            __t,
            $crate::chaos::assertions::_re_export::AssertKind::NumericAlways,
            false,
        );
        if !(__v >= __t) {
            $crate::chaos::assertions::record_always_violation();
        }
    };
    ($val:expr, $thresh:expr, $message:expr, { $($key:expr => $dval:expr),+ $(,)? }) => {
        let __msg = $message;
        let __v = $crate::chaos::assertions::to_i64_saturating($val);
        let __t = $crate::chaos::assertions::to_i64_saturating($thresh);
        $crate::chaos::assertions::on_assertion_numeric(
            &__msg,
            __v,
            $crate::chaos::assertions::_re_export::AssertCmp::Ge,
            __t,
            $crate::chaos::assertions::_re_export::AssertKind::NumericAlways,
            false,
        );
        if !(__v >= __t) {
            $crate::chaos::assertions::record_always_violation();
            eprintln!(
                "[ASSERTION FAILED] {} ({}>={} failed, seed={}) | {}",
                __msg, __v, __t,
                $crate::current_sim_seed(),
                $crate::chaos::assertions::format_details(
                    &[ $(($key, &$dval as &dyn std::fmt::Display)),+ ]
                )
            );
        }
    };
}

/// Assert that `val < threshold` always holds.
///
/// Does **not** panic on failure — records the violation and logs at ERROR level.
#[macro_export]
macro_rules! assert_always_less_than {
    ($val:expr, $thresh:expr, $message:expr) => {
        let __msg = $message;
        let __v = $crate::chaos::assertions::to_i64_saturating($val);
        let __t = $crate::chaos::assertions::to_i64_saturating($thresh);
        $crate::chaos::assertions::on_assertion_numeric(
            &__msg,
            __v,
            $crate::chaos::assertions::_re_export::AssertCmp::Lt,
            __t,
            $crate::chaos::assertions::_re_export::AssertKind::NumericAlways,
            true,
        );
        if !(__v < __t) {
            $crate::chaos::assertions::record_always_violation();
        }
    };
    ($val:expr, $thresh:expr, $message:expr, { $($key:expr => $dval:expr),+ $(,)? }) => {
        let __msg = $message;
        let __v = $crate::chaos::assertions::to_i64_saturating($val);
        let __t = $crate::chaos::assertions::to_i64_saturating($thresh);
        $crate::chaos::assertions::on_assertion_numeric(
            &__msg,
            __v,
            $crate::chaos::assertions::_re_export::AssertCmp::Lt,
            __t,
            $crate::chaos::assertions::_re_export::AssertKind::NumericAlways,
            true,
        );
        if !(__v < __t) {
            $crate::chaos::assertions::record_always_violation();
            eprintln!(
                "[ASSERTION FAILED] {} ({}<{} failed, seed={}) | {}",
                __msg, __v, __t,
                $crate::current_sim_seed(),
                $crate::chaos::assertions::format_details(
                    &[ $(($key, &$dval as &dyn std::fmt::Display)),+ ]
                )
            );
        }
    };
}

/// Assert that `val <= threshold` always holds.
///
/// Does **not** panic on failure — records the violation and logs at ERROR level.
#[macro_export]
macro_rules! assert_always_less_than_or_equal_to {
    ($val:expr, $thresh:expr, $message:expr) => {
        let __msg = $message;
        let __v = $crate::chaos::assertions::to_i64_saturating($val);
        let __t = $crate::chaos::assertions::to_i64_saturating($thresh);
        $crate::chaos::assertions::on_assertion_numeric(
            &__msg,
            __v,
            $crate::chaos::assertions::_re_export::AssertCmp::Le,
            __t,
            $crate::chaos::assertions::_re_export::AssertKind::NumericAlways,
            true,
        );
        if !(__v <= __t) {
            $crate::chaos::assertions::record_always_violation();
        }
    };
    ($val:expr, $thresh:expr, $message:expr, { $($key:expr => $dval:expr),+ $(,)? }) => {
        let __msg = $message;
        let __v = $crate::chaos::assertions::to_i64_saturating($val);
        let __t = $crate::chaos::assertions::to_i64_saturating($thresh);
        $crate::chaos::assertions::on_assertion_numeric(
            &__msg,
            __v,
            $crate::chaos::assertions::_re_export::AssertCmp::Le,
            __t,
            $crate::chaos::assertions::_re_export::AssertKind::NumericAlways,
            true,
        );
        if !(__v <= __t) {
            $crate::chaos::assertions::record_always_violation();
            eprintln!(
                "[ASSERTION FAILED] {} ({}<={} failed, seed={}) | {}",
                __msg, __v, __t,
                $crate::current_sim_seed(),
                $crate::chaos::assertions::format_details(
                    &[ $(($key, &$dval as &dyn std::fmt::Display)),+ ]
                )
            );
        }
    };
}

/// Assert that `val > threshold` sometimes holds. Forks on watermark improvement.
#[macro_export]
macro_rules! assert_sometimes_greater_than {
    ($val:expr, $thresh:expr, $message:expr) => {
        $crate::chaos::assertions::on_assertion_numeric(
            &$message,
            $crate::chaos::assertions::to_i64_saturating($val),
            $crate::chaos::assertions::_re_export::AssertCmp::Gt,
            $crate::chaos::assertions::to_i64_saturating($thresh),
            $crate::chaos::assertions::_re_export::AssertKind::NumericSometimes,
            true,
        );
    };
}

/// Assert that `val >= threshold` sometimes holds. Forks on watermark improvement.
#[macro_export]
macro_rules! assert_sometimes_greater_than_or_equal_to {
    ($val:expr, $thresh:expr, $message:expr) => {
        $crate::chaos::assertions::on_assertion_numeric(
            &$message,
            $crate::chaos::assertions::to_i64_saturating($val),
            $crate::chaos::assertions::_re_export::AssertCmp::Ge,
            $crate::chaos::assertions::to_i64_saturating($thresh),
            $crate::chaos::assertions::_re_export::AssertKind::NumericSometimes,
            true,
        );
    };
}

/// Assert that `val < threshold` sometimes holds. Forks on watermark improvement.
#[macro_export]
macro_rules! assert_sometimes_less_than {
    ($val:expr, $thresh:expr, $message:expr) => {
        $crate::chaos::assertions::on_assertion_numeric(
            &$message,
            $crate::chaos::assertions::to_i64_saturating($val),
            $crate::chaos::assertions::_re_export::AssertCmp::Lt,
            $crate::chaos::assertions::to_i64_saturating($thresh),
            $crate::chaos::assertions::_re_export::AssertKind::NumericSometimes,
            false,
        );
    };
}

/// Assert that `val <= threshold` sometimes holds. Forks on watermark improvement.
#[macro_export]
macro_rules! assert_sometimes_less_than_or_equal_to {
    ($val:expr, $thresh:expr, $message:expr) => {
        $crate::chaos::assertions::on_assertion_numeric(
            &$message,
            $crate::chaos::assertions::to_i64_saturating($val),
            $crate::chaos::assertions::_re_export::AssertCmp::Le,
            $crate::chaos::assertions::to_i64_saturating($thresh),
            $crate::chaos::assertions::_re_export::AssertKind::NumericSometimes,
            false,
        );
    };
}

/// Compound boolean assertion: all named bools should sometimes be true simultaneously.
///
/// Tracks a frontier (max number of simultaneously true bools). Forks when
/// the frontier advances.
///
/// # Usage
///
/// ```ignore
/// assert_sometimes_all!("all_nodes_healthy", [
///     ("node_a", node_a_healthy),
///     ("node_b", node_b_healthy),
///     ("node_c", node_c_healthy),
/// ]);
/// ```
#[macro_export]
macro_rules! assert_sometimes_all {
    ($msg:expr, [ $(($name:expr, $val:expr)),+ $(,)? ]) => {
        $crate::chaos::assertions::on_assertion_sometimes_all($msg, &[ $(($name, $val)),+ ])
    };
}

/// Per-value bucketed sometimes assertion with optional quality watermarks.
///
/// Each unique combination of identity keys gets its own bucket. On first
/// discovery of a new bucket, a fork is triggered for exploration. If quality
/// keys are provided, re-forks when quality improves.
///
/// # Usage
///
/// ```ignore
/// // Identity keys only
/// assert_sometimes_each!("gate", [("lock", lock_id), ("depth", depth)]);
///
/// // With quality watermarks
/// assert_sometimes_each!("descended", [("to_floor", floor)], [("health", hp)]);
/// ```
#[macro_export]
macro_rules! assert_sometimes_each {
    ($msg:expr, [ $(($name:expr, $val:expr)),+ $(,)? ]) => {
        $crate::chaos::assertions::on_sometimes_each(
            $msg,
            &[ $(($name, $crate::chaos::assertions::to_i64_saturating($val))),+ ],
            &[],
        )
    };
    ($msg:expr, [ $(($name:expr, $val:expr)),+ $(,)? ], [ $(($qname:expr, $qval:expr)),+ $(,)? ]) => {
        $crate::chaos::assertions::on_sometimes_each(
            $msg,
            &[ $(($name, $crate::chaos::assertions::to_i64_saturating($val))),+ ],
            &[ $(($qname, $crate::chaos::assertions::to_i64_saturating($qval))),+ ],
        )
    };
}

/// Re-exports for macro hygiene (`$crate::chaos::assertions::_re_export::*`).
pub mod _re_export {
    pub use moonpool_assertions::{AssertCmp, AssertKind};
}

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

    #[test]
    fn test_assertion_stats_new() {
        let stats = AssertionStats::new();
        assert_eq!(stats.total_checks, 0);
        assert_eq!(stats.successes, 0);
        assert!(stats.success_rate().abs() < f64::EPSILON);
    }

    #[test]
    fn test_assertion_stats_record() {
        let mut stats = AssertionStats::new();

        stats.record(true);
        assert_eq!(stats.total_checks, 1);
        assert_eq!(stats.successes, 1);
        assert!((stats.success_rate() - 100.0).abs() < f64::EPSILON);

        stats.record(false);
        assert_eq!(stats.total_checks, 2);
        assert_eq!(stats.successes, 1);
        assert!((stats.success_rate() - 50.0).abs() < f64::EPSILON);

        stats.record(true);
        assert_eq!(stats.total_checks, 3);
        assert_eq!(stats.successes, 2);
        let expected = 200.0 / 3.0;
        assert!((stats.success_rate() - expected).abs() < 1e-10);
    }

    #[test]
    fn test_assertion_stats_success_rate_edge_cases() {
        let mut stats = AssertionStats::new();
        assert!(stats.success_rate().abs() < f64::EPSILON);

        stats.record(false);
        assert!(stats.success_rate().abs() < f64::EPSILON);

        stats.record(true);
        assert!((stats.success_rate() - 50.0).abs() < f64::EPSILON);
    }

    #[test]
    fn test_assertion_results_empty() {
        // When no assertions have been tracked, results should be empty
        // (assertion table not initialized = empty)
        let results = assertion_results();
        // May or may not be empty depending on prior test state,
        // but should not panic
        let _ = results;
    }

    #[test]
    fn test_validate_contracts_empty() {
        // Should produce no violations when no assertions tracked
        let violations = validate_assertion_contracts();
        // May or may not be empty, but should not panic
        let _ = violations;
    }
}