asupersync 0.3.4

//! Graded/quantitative types for obligations and budgets.
//!
//! Explores an opt-in type layer where obligations carry resource annotations,
//! making "no obligation leaks" a type error (or at minimum a `#[must_use]`
//! warning + panic-on-drop) for code using the graded surface.
//!
//! # Typing Judgment Sketch
//!
//! The graded type discipline assigns resource weights to obligation values:
//!
//! ```text
//! Γ ⊢ reserve(K)    : Obligation<K>     [creates 1 unit of resource K]
//! Γ, x: Obligation<K> ⊢ commit(x) : ()  [consumes 1 unit of resource K]
//! Γ, x: Obligation<K> ⊢ abort(x)  : ()  [consumes 1 unit of resource K]
//!
//! // Scope rule: exit with 0 outstanding obligations
//! Γ ⊢ scope(body) : τ    iff    Γ_exit has no live Obligation<K> values
//! ```
//!
//! In a fully linear type system, forgetting to consume an obligation would
//! be a *type error*. Rust is affine (values may be dropped silently), not
//! linear. We approximate linearity with:
//!
//! 1. **`#[must_use]`**: Compiler warns if an `Obligation<K>` is ignored.
//! 2. **Drop bomb**: `Drop` impl panics if the obligation was not resolved.
//!    In debug/lab mode this catches leaks immediately. In release mode,
//!    this can be replaced with a log+metric.
//! 3. **API shape**: The only ways to disarm the drop bomb are `commit()`,
//!    `abort()`, or `into_raw()` (escape hatch for FFI/tests).
//!
//! # Resource Semiring
//!
//! The graded annotation forms a semiring over obligation counts:
//!
//! ```text
//! (ℕ, +, 0, ×, 1)
//! ```
//!
//! - `0`: no obligation held (empty)
//! - `1`: one obligation held (reserve)
//! - `+`: sequential composition (obligations accumulate)
//! - `×`: parallel composition (obligations from both branches)
//!
//! # Example
//!
//! ```
//! use asupersync::obligation::graded::{GradedObligation, Resolution};
//! use asupersync::record::ObligationKind;
//!
//! // Correct usage: obligation is resolved before scope exit.
//! let ob = GradedObligation::reserve(ObligationKind::SendPermit, "test permit");
//! ob.resolve(Resolution::Commit);
//!
//! // This would panic on drop:
//! // let leaked = GradedObligation::reserve(ObligationKind::Ack, "leaked");
//! // drop(leaked); // PANIC: obligation leaked!
//! ```

use crate::record::{ObligationKind, ObligationState};
use crate::types::{RegionId, id::next_bootstrap_region_id};
use std::fmt;
use std::marker::PhantomData;
use std::sync::LazyLock;
use std::sync::atomic::{AtomicU64, Ordering};

// ============================================================================
// Panic-Safe Leak Tracker
// ============================================================================

/// Tracks obligation leaks that occur during panic unwinding.
///
/// This preserves the "no obligation leaks" invariant even when obligations
/// are dropped during panic unwinding, where we cannot panic again.
struct PanicLeakTracker {
    /// Total number of obligations leaked during panic unwinding.
    leak_count: AtomicU64,
}

impl PanicLeakTracker {
    const fn new() -> Self {
        Self {
            leak_count: AtomicU64::new(0),
        }
    }

    /// Record an obligation leak during panic unwinding.
    ///
    /// This is panic-safe and will not panic even if called during unwinding.
    fn record_panic_leak(&self) {
        self.leak_count.fetch_add(1, Ordering::Relaxed);
    }

    /// Get the total number of panic leaks recorded.
    pub fn leak_count(&self) -> u64 {
        self.leak_count.load(Ordering::Relaxed)
    }
}

/// Global panic leak tracker instance.
static PANIC_LEAK_TRACKER: LazyLock<PanicLeakTracker> = LazyLock::new(PanicLeakTracker::new);

/// Returns the number of obligations that have leaked during panic unwinding.
///
/// This is useful for tests and monitoring to ensure that the "no obligation leaks"
/// invariant is maintained even during exceptional circumstances.
pub fn panic_leak_count() -> u64 {
    PANIC_LEAK_TRACKER.leak_count()
}

// ============================================================================
// Resolution
// ============================================================================

/// How an obligation was resolved.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Resolution {
    /// Obligation was committed (effect took place).
    Commit,
    /// Obligation was aborted (clean cancellation).
    Abort,
}

impl fmt::Display for Resolution {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Commit => f.write_str("commit"),
            Self::Abort => f.write_str("abort"),
        }
    }
}

impl Resolution {
    /// Returns the matching runtime obligation record state.
    #[inline]
    #[must_use]
    pub const fn obligation_state(self) -> ObligationState {
        match self {
            Self::Commit => ObligationState::Committed,
            Self::Abort => ObligationState::Aborted,
        }
    }
}

// ============================================================================
// GradedObligation
// ============================================================================

/// A graded obligation value that must be resolved before being dropped.
///
/// This type approximates a linear type in Rust's affine type system.
/// It uses `#[must_use]` to warn at compile time if the value is unused,
/// and panics on `Drop` if the obligation was not resolved.
///
/// # Graded Semantics
///
/// Each `GradedObligation` represents exactly 1 unit of resource.
/// Resolving it (via `resolve()`) consumes the resource and returns
/// a `Resolved<K>` proof token. Dropping without resolving panics.
///
/// # Type-Level Encoding
///
/// In a fully graded type system, we would write:
/// ```text
/// reserve : () →₁ Obligation<K>
/// commit  : Obligation<K> →₁ ()
/// abort   : Obligation<K> →₁ ()
/// ```
/// where `→₁` means "consumes exactly 1 unit". In Rust, we approximate
/// this with move semantics (value is consumed) and Drop (leak detection).
#[must_use = "obligations must be resolved (commit or abort); dropping leaks the obligation"]
pub struct GradedObligation {
    /// The kind of obligation.
    kind: ObligationKind,
    /// Description for diagnostics.
    description: String,
    /// Whether the obligation has been resolved.
    resolved: bool,
}

impl GradedObligation {
    /// Reserve a new obligation of the given kind.
    ///
    /// This is the `reserve` typing rule:
    /// ```text
    /// Γ ⊢ reserve(K, desc) : Obligation<K>     [+1 resource]
    /// ```
    pub fn reserve(kind: ObligationKind, description: impl Into<String>) -> Self {
        Self {
            kind,
            description: description.into(),
            resolved: false,
        }
    }

    /// Resolve the obligation (commit or abort), consuming the graded value.
    ///
    /// This is the `commit`/`abort` typing rule:
    /// ```text
    /// Γ, x: Obligation<K> ⊢ resolve(x, r) : Proof<K>     [-1 resource]
    /// ```
    ///
    /// Returns a [`ResolvedProof`] token that proves the obligation was handled.
    #[must_use]
    pub fn resolve(mut self, resolution: Resolution) -> ResolvedProof {
        self.resolved = true;
        ResolvedProof {
            kind: self.kind,
            resolution,
        }
    }

    /// Returns the obligation kind.
    #[must_use]
    pub fn kind(&self) -> ObligationKind {
        self.kind
    }

    /// Returns the description.
    #[must_use]
    pub fn description(&self) -> &str {
        &self.description
    }

    /// Returns whether the obligation has been resolved.
    #[must_use]
    pub fn is_resolved(&self) -> bool {
        self.resolved
    }

    /// Escape hatch: disarm the drop bomb without resolving.
    ///
    /// Use only for FFI boundaries, test harnesses, or migration paths.
    /// This intentionally leaks the obligation.
    #[must_use]
    pub fn into_raw(mut self) -> RawObligation {
        self.resolved = true; // Disarm the bomb.
        RawObligation {
            kind: self.kind,
            description: std::mem::take(&mut self.description),
        }
    }
}

impl Drop for GradedObligation {
    fn drop(&mut self) {
        if !self.resolved {
            if std::thread::panicking() {
                // During panic unwinding, we cannot panic again, but we must still
                // track the obligation leak to maintain the "no obligation leaks" invariant.
                // This preserves leak detection even during panic unwinding.
                PANIC_LEAK_TRACKER.record_panic_leak();
                return;
            }
            // In lab/debug mode: panic to surface the bug immediately.
            // In production: this could log+metric instead of panicking.
            panic!(
                "OBLIGATION LEAKED: {} obligation '{}' was dropped without being resolved. \
                 Call .resolve(Resolution::Commit) or .resolve(Resolution::Abort) before scope exit.",
                self.kind, self.description,
            );
        }
    }
}

impl fmt::Debug for GradedObligation {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("GradedObligation")
            .field("kind", &self.kind)
            .field("description", &self.description)
            .field("resolved", &self.resolved)
            .finish()
    }
}

// ============================================================================
// ResolvedProof
// ============================================================================

/// Proof token that an obligation was resolved.
///
/// Created by [`GradedObligation::resolve`]. This is a zero-cost witness
/// value: it proves at the type level that the obligation was handled.
/// The fields are intentionally opaque so callers cannot forge resolution
/// proofs without actually consuming an obligation.
///
/// In a dependent type system, this would be:
/// ```text
/// ResolvedProof<K, R> : Type    where R ∈ {Commit, Abort}
/// ```
#[derive(Debug, PartialEq, Eq)]
pub struct ResolvedProof {
    /// The kind of obligation that was resolved.
    kind: ObligationKind,
    /// How it was resolved.
    resolution: Resolution,
}

impl ResolvedProof {
    /// Returns the obligation kind proven to be resolved.
    #[must_use]
    pub fn kind(&self) -> ObligationKind {
        self.kind
    }

    /// Returns how the obligation was resolved.
    #[must_use]
    pub fn resolution(&self) -> Resolution {
        self.resolution
    }

    /// Returns the matching runtime obligation record state.
    #[must_use]
    pub fn obligation_state(&self) -> ObligationState {
        self.resolution.obligation_state()
    }
}

impl fmt::Display for ResolvedProof {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "resolved({}, {})", self.kind, self.resolution)
    }
}

// ============================================================================
// RawObligation
// ============================================================================

/// An obligation that was disarmed via [`GradedObligation::into_raw`].
///
/// Holds the metadata but not the drop bomb. Used for FFI, migration,
/// and test harness escape paths.
#[derive(Debug, Clone)]
pub struct RawObligation {
    /// The kind of obligation.
    pub kind: ObligationKind,
    /// Description.
    pub description: String,
}

// ============================================================================
// GradedScope
// ============================================================================

/// A scope that tracks obligation counts and verifies zero-leak at exit.
///
/// Models the scope typing rule:
/// ```text
/// Γ ⊢ scope(body) : τ    iff    Γ_exit has 0 outstanding obligations
/// ```
///
/// The scope tracks how many obligations have been reserved and resolved.
/// At scope exit (via `close()`), it verifies the counts match.
pub struct GradedScope {
    /// Label for diagnostics.
    label: String,
    /// Number of obligations reserved.
    reserved: u32,
    /// Number of obligations resolved.
    resolved: u32,
    /// Whether the scope has been explicitly closed.
    closed: bool,
}

impl GradedScope {
    /// Open a new graded scope.
    #[must_use]
    pub fn open(label: impl Into<String>) -> Self {
        Self {
            label: label.into(),
            reserved: 0,
            resolved: 0,
            closed: false,
        }
    }

    /// Record a reservation (obligation created in this scope).
    pub fn on_reserve(&mut self) {
        self.reserved = self
            .reserved
            .checked_add(1)
            .expect("on_reserve overflowed outstanding obligation count");
    }

    /// Record a resolution (obligation resolved in this scope).
    ///
    /// # Panics
    ///
    /// Panics if called more times than `on_reserve`, which would indicate
    /// a double-resolution bug.
    pub fn on_resolve(&mut self) {
        assert!(
            self.resolved < self.reserved,
            "on_resolve called more times than on_reserve ({} >= {})",
            self.resolved,
            self.reserved,
        );
        self.resolved = self
            .resolved
            .checked_add(1)
            .expect("on_resolve overflowed resolved obligation count");
    }

    /// Returns the number of outstanding (unresolved) obligations.
    #[must_use]
    pub fn outstanding(&self) -> u32 {
        self.reserved.saturating_sub(self.resolved)
    }

    /// Close the scope, verifying zero outstanding obligations.
    ///
    /// # Errors
    ///
    /// Returns `Err` with the number of leaked obligations if any remain.
    #[must_use = "close() must be checked; Err indicates leaked obligations"]
    pub fn close(mut self) -> Result<ScopeProof, ScopeLeakError> {
        let outstanding = self.outstanding();
        if outstanding == 0 {
            self.closed = true;
            Ok(ScopeProof {
                label: self.label.clone(),
                total_reserved: self.reserved,
                total_resolved: self.resolved,
            })
        } else {
            let err = ScopeLeakError {
                label: self.label.clone(),
                outstanding,
                reserved: self.reserved,
                resolved: self.resolved,
            };
            // Mark closed so Drop doesn't panic — the caller explicitly
            // called close() and received the error, so they are aware of
            // the leak. Drop panics are reserved for implicit drops where
            // close() was never called.
            self.closed = true;
            Err(err)
        }
    }

    /// Returns the scope label.
    #[must_use]
    pub fn label(&self) -> &str {
        &self.label
    }
}

impl Drop for GradedScope {
    fn drop(&mut self) {
        if !self.closed && self.outstanding() > 0 {
            if std::thread::panicking() {
                return;
            }
            panic!(
                "SCOPE LEAKED: scope '{}' dropped with {} outstanding obligation(s) \
                 ({} reserved, {} resolved). Call .close() before scope exit.",
                self.label,
                self.outstanding(),
                self.reserved,
                self.resolved,
            );
        }
    }
}

impl fmt::Debug for GradedScope {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("GradedScope")
            .field("label", &self.label)
            .field("reserved", &self.reserved)
            .field("resolved", &self.resolved)
            .field("outstanding", &self.outstanding())
            .field("closed", &self.closed)
            .finish()
    }
}

// ============================================================================
// ScopeProof / ScopeLeakError
// ============================================================================

/// Proof that a scope was closed with zero outstanding obligations.
///
/// This witness is intentionally opaque so callers cannot fabricate a clean
/// closure proof without running the scope accounting.
#[derive(Debug, PartialEq, Eq)]
pub struct ScopeProof {
    /// Scope label.
    label: String,
    /// Total obligations reserved.
    total_reserved: u32,
    /// Total obligations resolved.
    total_resolved: u32,
}

impl ScopeProof {
    /// Returns the label of the cleanly closed scope.
    #[must_use]
    pub fn label(&self) -> &str {
        &self.label
    }

    /// Returns how many obligations were reserved in the scope.
    #[must_use]
    pub fn total_reserved(&self) -> u32 {
        self.total_reserved
    }

    /// Returns how many obligations were resolved in the scope.
    #[must_use]
    pub fn total_resolved(&self) -> u32 {
        self.total_resolved
    }
}

impl fmt::Display for ScopeProof {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "scope '{}' clean: {}/{} resolved",
            self.label, self.total_resolved, self.total_reserved
        )
    }
}

/// Error when a scope is closed with outstanding obligations.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ScopeLeakError {
    /// Scope label.
    pub label: String,
    /// Number of leaked obligations.
    pub outstanding: u32,
    /// Total reserved.
    pub reserved: u32,
    /// Total resolved.
    pub resolved: u32,
}

impl fmt::Display for ScopeLeakError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "scope '{}' leaked: {} outstanding ({} reserved, {} resolved)",
            self.label, self.outstanding, self.reserved, self.resolved,
        )
    }
}

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

// ============================================================================
// Toy API demonstration
// ============================================================================

/// Demonstrates the graded obligation API with a toy channel-like pattern.
///
/// This module shows how the graded type discipline makes obligation leaks
/// into compile warnings or runtime panics, while correct usage compiles
/// and runs cleanly.
pub mod toy_api {
    use super::{GradedObligation, ObligationKind, Resolution, ResolvedProof};

    fn assert_send_permit(permit: &GradedObligation, operation: &str) {
        assert_eq!(
            permit.kind(),
            ObligationKind::SendPermit,
            "{operation} requires a SendPermit obligation (got {})",
            permit.kind()
        );
    }

    /// A toy channel that uses graded obligations for the two-phase send.
    pub struct ToyChannel {
        capacity: usize,
        messages: Vec<String>,
        reserved_permits: usize,
    }

    impl ToyChannel {
        /// Creates a new channel with the given capacity.
        #[must_use]
        pub fn new(capacity: usize) -> Self {
            Self {
                capacity,
                messages: Vec::new(),
                reserved_permits: 0,
            }
        }

        #[cfg(test)]
        pub(super) fn from_state(
            capacity: usize,
            messages: Vec<String>,
            reserved_permits: usize,
        ) -> Self {
            Self {
                capacity,
                messages,
                reserved_permits,
            }
        }

        /// Reserve a send permit.
        ///
        /// Returns a [`GradedObligation`] that must be resolved:
        /// - `resolve(Commit)` — message is sent
        /// - `resolve(Abort)` — permit is cancelled
        ///
        /// Dropping the permit without resolving panics.
        #[must_use]
        pub fn reserve_send(&mut self) -> Option<GradedObligation> {
            let occupied = self
                .messages
                .len()
                .checked_add(self.reserved_permits)
                .expect("toy channel occupancy overflowed");
            if occupied < self.capacity {
                self.reserved_permits = self
                    .reserved_permits
                    .checked_add(1)
                    .expect("toy channel reserved permit count overflowed");
                Some(GradedObligation::reserve(
                    ObligationKind::SendPermit,
                    "toy channel send permit",
                ))
            } else {
                None
            }
        }

        /// Commit a send: consumes the permit and enqueues the message.
        pub fn commit_send(&mut self, permit: GradedObligation, message: String) -> ResolvedProof {
            assert_send_permit(&permit, "commit_send");
            self.reserved_permits = self
                .reserved_permits
                .checked_sub(1)
                .expect("commit_send requires an outstanding reservation");
            self.messages.push(message);
            permit.resolve(Resolution::Commit)
        }

        /// Abort a send: cancels the permit without sending.
        #[must_use]
        pub fn abort_send(&mut self, permit: GradedObligation) -> ResolvedProof {
            assert_send_permit(&permit, "abort_send");
            self.reserved_permits = self
                .reserved_permits
                .checked_sub(1)
                .expect("abort_send requires an outstanding reservation");
            permit.resolve(Resolution::Abort)
        }

        /// Returns the number of messages in the channel.
        #[must_use]
        pub fn len(&self) -> usize {
            self.messages.len()
        }

        /// Returns true if the channel is empty.
        #[must_use]
        pub fn is_empty(&self) -> bool {
            self.messages.is_empty()
        }
    }
}

// ============================================================================
// Sealed trait pattern (prevents external impls of TokenKind)
// ============================================================================

mod sealed {
    pub trait Sealed {}
}

// ============================================================================
// TokenKind trait + kind marker enums
// ============================================================================

/// Trait mapping a zero-sized kind marker to its [`ObligationKind`] variant.
///
/// Sealed: cannot be implemented outside this crate.
pub trait TokenKind: sealed::Sealed {
    /// Returns the [`ObligationKind`] corresponding to this marker.
    fn obligation_kind() -> ObligationKind;
}

/// Error returned when dynamic obligation metadata does not match a typed token.
///
/// This is the migration bridge from existing runtime/ledger surfaces that
/// still carry [`ObligationKind`] dynamically into the stronger typestate API.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TypedObligationKindError {
    /// Static obligation kind required by the requested token type.
    pub expected: ObligationKind,
    /// Dynamic obligation kind supplied by the caller.
    pub actual: ObligationKind,
}

impl fmt::Display for TypedObligationKindError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "typed obligation kind mismatch: expected {}, got {}",
            self.expected, self.actual
        )
    }
}

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

/// Contract row describing the typed obligation bridge evidence surface.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TypedObligationBridgeContract {
    /// Bead that introduced the bridge contract.
    pub bead_id: &'static str,
    /// Protocol family strengthened by the typed bridge.
    pub protocol_family: &'static str,
    /// Typed API entrypoint that materializes a static obligation token.
    pub typed_entrypoint: &'static str,
    /// Dynamic fallback path that remains authoritative during migration.
    pub dynamic_fallback: &'static str,
    /// Compile-fail proof surface for invalid typestate transitions.
    pub compile_fail_surface: &'static str,
    /// Focused reproduction command for the contract evidence.
    pub replay_command: &'static str,
    /// Stable invariant checklist covered by the focused tests.
    pub invariants: &'static [&'static str],
}

const TYPED_OBLIGATION_BRIDGE_INVARIANTS: &[&str] = &[
    "matching dynamic kind creates a typed token",
    "mismatched dynamic kind does not arm a token",
    "scope accounting increments only after kind proof succeeds",
    "abort cleanup balances a scoped lease token",
    "committed proof has no abort transition",
];

/// Returns the contract row for the dynamic-to-typed obligation bridge.
#[must_use]
pub const fn typed_obligation_bridge_contract() -> TypedObligationBridgeContract {
    TypedObligationBridgeContract {
        bead_id: "asupersync-d87ytw.13",
        protocol_family: "send-permit/ack/lease graded obligations",
        typed_entrypoint: "asupersync::obligation::graded::ObligationToken::try_reserve_kind",
        dynamic_fallback: "asupersync::record::ObligationKind",
        compile_fail_surface: "src/obligation/graded.rs::ObligationToken commit-then-abort doctest",
        replay_command: "rch exec -- env CARGO_INCREMENTAL=0 CARGO_PROFILE_TEST_DEBUG=0 RUSTFLAGS='-C debuginfo=0' CARGO_TARGET_DIR=${TMPDIR:-/tmp}/rch_target_asupersync_graded_bridge cargo test -p asupersync --lib dynamic_kind_bridge --features test-internals -- --nocapture",
        invariants: TYPED_OBLIGATION_BRIDGE_INVARIANTS,
    }
}

/// Marker type for [`ObligationKind::SendPermit`].
#[derive(Debug)]
pub enum SendPermit {}
impl sealed::Sealed for SendPermit {}
impl TokenKind for SendPermit {
    fn obligation_kind() -> ObligationKind {
        ObligationKind::SendPermit
    }
}

/// Marker type for [`ObligationKind::Ack`].
#[derive(Debug)]
pub enum AckKind {}
impl sealed::Sealed for AckKind {}
impl TokenKind for AckKind {
    fn obligation_kind() -> ObligationKind {
        ObligationKind::Ack
    }
}

/// Marker type for [`ObligationKind::Lease`].
#[derive(Debug, PartialEq, Eq)]
pub enum LeaseKind {}
impl sealed::Sealed for LeaseKind {}
impl TokenKind for LeaseKind {
    fn obligation_kind() -> ObligationKind {
        ObligationKind::Lease
    }
}

/// Marker type for [`ObligationKind::IoOp`].
#[derive(Debug)]
pub enum IoOpKind {}
impl sealed::Sealed for IoOpKind {}
impl TokenKind for IoOpKind {
    fn obligation_kind() -> ObligationKind {
        ObligationKind::IoOp
    }
}

/// Marker type for [`ObligationKind::SemaphorePermit`].
#[derive(Debug)]
pub enum SemaphorePermitKind {}
impl sealed::Sealed for SemaphorePermitKind {}
impl TokenKind for SemaphorePermitKind {
    fn obligation_kind() -> ObligationKind {
        ObligationKind::SemaphorePermit
    }
}

// ============================================================================
// ObligationToken<K> — typestate linear token
// ============================================================================

/// A typestate-encoded obligation token that must be consumed via
/// [`commit`](Self::commit) or [`abort`](Self::abort).
///
/// Dropping without consuming panics ("drop bomb"), approximating a linear
/// type in Rust's affine type system.
///
/// Invalid transitions stay unrepresentable: after a token is committed, the
/// resulting proof has no `abort` transition.
///
/// ```compile_fail
/// use asupersync::obligation::graded::{ObligationToken, SendPermitToken};
///
/// let token: SendPermitToken = ObligationToken::reserve_test("send");
/// let committed = token.commit();
/// let _late_abort = committed.abort();
/// ```
#[must_use = "obligation tokens must be consumed via commit() or abort()"]
pub struct ObligationToken<K: TokenKind> {
    description: String,
    region: RegionId,
    armed: bool,
    _kind: PhantomData<K>,
}

impl<K: TokenKind> ObligationToken<K> {
    /// Reserve a new obligation token with the given description and region context.
    ///
    /// This method ensures the obligation is properly scoped to a region, preventing
    /// obligation leaks that could occur if tokens outlive their intended scope.
    ///
    /// # Region Validation
    ///
    /// The region must be valid and active. Creating obligations outside of proper
    /// region context violates the "no obligation leaks" invariant.
    #[allow(clippy::double_must_use)]
    #[must_use = "obligation tokens must be committed or aborted"]
    pub fn reserve(description: impl Into<String>, region: RegionId) -> Self {
        let description = description.into();
        // Validate that the region is not the root region (which should not hold obligations)
        // and that we're in a valid execution context. The root region typically has
        // index 0, generation 0.
        assert!(
            region.as_u64() != 0,
            "Cannot create obligation token in root region: obligations must be \
             scoped to non-root regions to prevent leaks. Description: {description}"
        );

        Self {
            description,
            region,
            armed: true,
            _kind: PhantomData,
        }
    }

    /// Returns the region this obligation is scoped to.
    #[must_use]
    pub fn region(&self) -> RegionId {
        self.region
    }

    /// Reserve a token for testing with a synthetic test region.
    ///
    /// This method should only be used in tests where proper region context
    /// is not available. Production code should use `reserve()` with a real
    /// region from the current Cx.
    #[cfg(any(test, feature = "test-internals"))]
    #[must_use = "obligation tokens must be committed or aborted"]
    pub fn reserve_test(description: impl Into<String>) -> Self {
        Self::reserve(description, RegionId::new_ephemeral())
    }

    /// Reserve a typed token from dynamic obligation metadata.
    ///
    /// This preserves the existing dynamic [`ObligationKind`] source of truth
    /// while refusing to manufacture a static token for the wrong protocol
    /// family. On mismatch no token is created, so no drop bomb is armed.
    ///
    /// # Errors
    ///
    /// Returns [`TypedObligationKindError`] when `kind` differs from `K`.
    pub fn try_reserve_kind(
        kind: ObligationKind,
        description: impl Into<String>,
        region: RegionId,
    ) -> Result<Self, TypedObligationKindError> {
        let expected = K::obligation_kind();
        if kind == expected {
            Ok(Self::reserve(description, region))
        } else {
            Err(TypedObligationKindError {
                expected,
                actual: kind,
            })
        }
    }

    /// Commit the obligation, consuming the token and returning a
    /// [`CommittedProof`].
    #[must_use]
    pub fn commit(mut self) -> CommittedProof<K> {
        self.armed = false;
        CommittedProof { _kind: PhantomData }
    }

    /// Abort the obligation, consuming the token and returning an
    /// [`AbortedProof`].
    #[must_use]
    pub fn abort(mut self) -> AbortedProof<K> {
        self.armed = false;
        AbortedProof { _kind: PhantomData }
    }

    /// Escape hatch: disarm the drop bomb and convert to a [`RawObligation`].
    ///
    /// Use only for FFI boundaries, test harnesses, or migration paths.
    #[must_use]
    pub fn into_raw(mut self) -> RawObligation {
        self.armed = false;
        let description = std::mem::take(&mut self.description);
        RawObligation {
            kind: K::obligation_kind(),
            description,
        }
    }

    /// Returns the description.
    #[must_use]
    pub fn description(&self) -> &str {
        &self.description
    }
}

impl<K: TokenKind> Drop for ObligationToken<K> {
    fn drop(&mut self) {
        if self.armed {
            if std::thread::panicking() {
                return;
            }
            panic!(
                // ubs:ignore - intentional panic on leak in debug build
                "OBLIGATION TOKEN LEAKED: {} token '{}' was dropped without being consumed. \
                 Call .commit() or .abort() before scope exit.",
                K::obligation_kind(),
                self.description,
            );
        }
    }
}

impl<K: TokenKind> fmt::Debug for ObligationToken<K> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("ObligationToken")
            .field("kind", &K::obligation_kind())
            .field("description", &self.description)
            .field("armed", &self.armed)
            .finish()
    }
}

// ============================================================================
// CommittedProof<K> / AbortedProof<K> — ZST witnesses
// ============================================================================

/// Proof that an [`ObligationToken`] was committed.
///
/// Commit proofs are affine witnesses: they are intentionally non-cloneable
/// and can only be constructed by consuming a live token.
#[derive(Debug, PartialEq, Eq)]
pub struct CommittedProof<K: TokenKind> {
    _kind: PhantomData<K>,
}

impl<K: TokenKind> CommittedProof<K> {
    /// Bridge to the existing [`ResolvedProof`] system.
    #[must_use]
    pub fn into_resolved_proof(self) -> ResolvedProof {
        ResolvedProof {
            kind: K::obligation_kind(),
            resolution: Resolution::Commit,
        }
    }

    /// Returns the obligation kind.
    #[must_use]
    pub fn kind(&self) -> ObligationKind {
        K::obligation_kind()
    }
}

/// Proof that an [`ObligationToken`] was aborted.
///
/// Abort proofs are affine witnesses: they are intentionally non-cloneable
/// and can only be constructed by consuming a live token.
#[derive(Debug, PartialEq, Eq)]
pub struct AbortedProof<K: TokenKind> {
    _kind: PhantomData<K>,
}

impl<K: TokenKind> AbortedProof<K> {
    /// Bridge to the existing [`ResolvedProof`] system.
    #[must_use]
    pub fn into_resolved_proof(self) -> ResolvedProof {
        ResolvedProof {
            kind: K::obligation_kind(),
            resolution: Resolution::Abort,
        }
    }

    /// Returns the obligation kind.
    #[must_use]
    pub fn kind(&self) -> ObligationKind {
        K::obligation_kind()
    }
}

// ============================================================================
// Type aliases (ergonomic names)
// ============================================================================

/// Token for a send-permit obligation.
pub type SendPermitToken = ObligationToken<SendPermit>;
/// Token for an acknowledgement obligation.
pub type AckToken = ObligationToken<AckKind>;
/// Token for a lease obligation.
pub type LeaseToken = ObligationToken<LeaseKind>;
/// Token for an I/O operation obligation.
pub type IoOpToken = ObligationToken<IoOpKind>;

// ============================================================================
// GradedScope convenience methods for tokens
// ============================================================================

impl GradedScope {
    /// Reserve a typed obligation token, recording it in this scope.
    #[allow(clippy::double_must_use)]
    #[must_use]
    pub fn reserve_token<K: TokenKind>(
        &mut self,
        description: impl Into<String>,
    ) -> ObligationToken<K> {
        self.on_reserve();
        ObligationToken::reserve(description, next_bootstrap_region_id())
    }

    /// Reserve a typed token from dynamic obligation metadata and record it.
    ///
    /// Scope accounting is updated only after the dynamic kind matches the
    /// requested static token kind. A mismatch therefore cannot create a
    /// synthetic outstanding obligation in the graded scope.
    ///
    /// # Errors
    ///
    /// Returns [`TypedObligationKindError`] when `kind` differs from `K`.
    pub fn try_reserve_token_kind<K: TokenKind>(
        &mut self,
        kind: ObligationKind,
        description: impl Into<String>,
    ) -> Result<ObligationToken<K>, TypedObligationKindError> {
        let token =
            ObligationToken::try_reserve_kind(kind, description, next_bootstrap_region_id())?;
        self.on_reserve();
        Ok(token)
    }

    /// Commit a typed obligation token, recording the resolution in this scope.
    #[must_use]
    pub fn resolve_commit<K: TokenKind>(&mut self, token: ObligationToken<K>) -> CommittedProof<K> {
        self.on_resolve();
        token.commit()
    }

    /// Abort a typed obligation token, recording the resolution in this scope.
    #[must_use]
    pub fn resolve_abort<K: TokenKind>(&mut self, token: ObligationToken<K>) -> AbortedProof<K> {
        self.on_resolve();
        token.abort()
    }
}

// ============================================================================
// Tests
// ============================================================================

#[cfg(test)]
mod tests {
    #![allow(
        clippy::pedantic,
        clippy::nursery,
        clippy::expect_fun_call,
        clippy::map_unwrap_or,
        clippy::cast_possible_wrap,
        clippy::future_not_send
    )]
    use super::*;
    use crate::record::ObligationKind;

    fn init_test(name: &str) {
        crate::test_utils::init_test_logging();
        crate::test_phase!(name);
    }

    // ---- GradedObligation: correct usage -----------------------------------

    #[test]
    fn obligation_commit_clean() {
        init_test("obligation_commit_clean");
        let ob = GradedObligation::reserve(ObligationKind::SendPermit, "test");
        let kind = ob.kind();
        crate::assert_with_log!(
            kind == ObligationKind::SendPermit,
            "kind",
            ObligationKind::SendPermit,
            kind
        );
        let is_resolved = ob.is_resolved();
        crate::assert_with_log!(!is_resolved, "not yet resolved", false, is_resolved);

        let proof = ob.resolve(Resolution::Commit);
        let r = proof.resolution();
        crate::assert_with_log!(r == Resolution::Commit, "resolution", Resolution::Commit, r);
        let state = proof.obligation_state();
        crate::assert_with_log!(
            state == ObligationState::Committed,
            "record state",
            ObligationState::Committed,
            state
        );
        crate::test_complete!("obligation_commit_clean");
    }

    #[test]
    fn obligation_abort_clean() {
        init_test("obligation_abort_clean");
        let ob = GradedObligation::reserve(ObligationKind::Ack, "ack-test");
        let proof = ob.resolve(Resolution::Abort);
        let r = proof.resolution();
        crate::assert_with_log!(r == Resolution::Abort, "resolution", Resolution::Abort, r);
        let state = proof.obligation_state();
        crate::assert_with_log!(
            state == ObligationState::Aborted,
            "record state",
            ObligationState::Aborted,
            state
        );
        crate::test_complete!("obligation_abort_clean");
    }

    #[test]
    fn obligation_into_raw_disarms() {
        init_test("obligation_into_raw_disarms");
        let ob = GradedObligation::reserve(ObligationKind::Lease, "lease-test");
        let raw = ob.into_raw();
        let kind = raw.kind;
        crate::assert_with_log!(
            kind == ObligationKind::Lease,
            "raw kind",
            ObligationKind::Lease,
            kind
        );
        // raw can be dropped without panic.
        drop(raw);
        crate::test_complete!("obligation_into_raw_disarms");
    }

    // ---- GradedObligation: leak detection ----------------------------------

    #[test]
    #[should_panic(expected = "OBLIGATION LEAKED")]
    fn obligation_drop_without_resolve_panics() {
        init_test("obligation_drop_without_resolve_panics");
        let _ob = GradedObligation::reserve(ObligationKind::IoOp, "leaked-io");
        // Dropped without resolving — should panic.
    }

    // ---- GradedScope: correct usage ----------------------------------------

    #[test]
    fn scope_clean_close() {
        init_test("scope_clean_close");
        let mut scope = GradedScope::open("test-scope");
        scope.on_reserve();
        scope.on_resolve();
        let outstanding = scope.outstanding();
        crate::assert_with_log!(outstanding == 0, "outstanding", 0, outstanding);

        let proof = scope.close().expect("scope should close cleanly");
        let label = proof.label();
        crate::assert_with_log!(label == "test-scope", "label", "test-scope", label);
        let total = proof.total_reserved();
        crate::assert_with_log!(total == 1, "reserved", 1, total);
        crate::test_complete!("scope_clean_close");
    }

    #[test]
    fn scope_multiple_obligations() {
        init_test("scope_multiple_obligations");
        let mut scope = GradedScope::open("multi");
        scope.on_reserve();
        scope.on_reserve();
        scope.on_reserve();
        let outstanding = scope.outstanding();
        crate::assert_with_log!(outstanding == 3, "outstanding", 3, outstanding);

        scope.on_resolve();
        scope.on_resolve();
        scope.on_resolve();
        let outstanding = scope.outstanding();
        crate::assert_with_log!(outstanding == 0, "outstanding", 0, outstanding);

        let proof = scope.close().expect("clean");
        let total = proof.total_reserved();
        crate::assert_with_log!(total == 3, "reserved", 3, total);
        crate::test_complete!("scope_multiple_obligations");
    }

    #[test]
    fn scope_close_with_leak_returns_error() {
        init_test("scope_close_with_leak_returns_error");
        let mut scope = GradedScope::open("leaky-scope");
        scope.on_reserve();
        scope.on_reserve();
        scope.on_resolve(); // Only 1 of 2 resolved.

        let err = scope.close().expect_err("should fail");
        let outstanding = err.outstanding;
        crate::assert_with_log!(outstanding == 1, "outstanding", 1, outstanding);
        let label = &err.label;
        crate::assert_with_log!(label == "leaky-scope", "label", "leaky-scope", label);

        // Verify Display impl.
        let msg = format!("{err}");
        let has_leaked = msg.contains("leaked");
        crate::assert_with_log!(has_leaked, "display has leaked", true, has_leaked);
        crate::test_complete!("scope_close_with_leak_returns_error");
    }

    #[test]
    #[should_panic(expected = "SCOPE LEAKED")]
    fn scope_drop_with_outstanding_panics() {
        init_test("scope_drop_with_outstanding_panics");
        let mut scope = GradedScope::open("drop-leak");
        scope.on_reserve();
        // Dropped without closing — should panic because outstanding > 0.
    }

    #[test]
    fn scope_drop_without_close_ok_when_empty() {
        init_test("scope_drop_without_close_ok_when_empty");
        let _scope = GradedScope::open("empty-scope");
        // No obligations reserved, drop is fine.
    }

    // ---- Combined: obligation + scope --------------------------------------

    #[test]
    fn combined_obligation_and_scope() {
        init_test("combined_obligation_and_scope");
        let mut scope = GradedScope::open("combined");

        // Reserve two obligations.
        let ob1 = GradedObligation::reserve(ObligationKind::SendPermit, "send");
        scope.on_reserve();
        let ob2 = GradedObligation::reserve(ObligationKind::Ack, "ack");
        scope.on_reserve();

        let outstanding = scope.outstanding();
        crate::assert_with_log!(outstanding == 2, "outstanding", 2, outstanding);

        // Resolve both.
        let _proof1 = ob1.resolve(Resolution::Commit);
        scope.on_resolve();
        let _proof2 = ob2.resolve(Resolution::Abort);
        scope.on_resolve();

        // Close scope.
        let proof = scope.close().expect("clean close");
        let total = proof.total_reserved();
        crate::assert_with_log!(total == 2, "total reserved", 2, total);
        crate::test_complete!("combined_obligation_and_scope");
    }

    // ---- Toy API -----------------------------------------------------------

    #[test]
    fn toy_channel_correct_usage() {
        init_test("toy_channel_correct_usage");
        let mut ch = toy_api::ToyChannel::new(10);

        // Reserve and commit.
        let permit = ch.reserve_send().expect("should get permit");
        let proof = ch.commit_send(permit, "hello".to_string());
        let resolution = proof.resolution();
        crate::assert_with_log!(
            resolution == Resolution::Commit,
            "commit",
            Resolution::Commit,
            resolution
        );
        let len = ch.len();
        crate::assert_with_log!(len == 1, "len", 1, len);
        crate::test_complete!("toy_channel_correct_usage");
    }

    #[test]
    fn toy_channel_abort_usage() {
        init_test("toy_channel_abort_usage");
        let mut ch = toy_api::ToyChannel::new(10);

        let permit = ch.reserve_send().expect("should get permit");
        let proof = ch.abort_send(permit);
        let resolution = proof.resolution();
        crate::assert_with_log!(
            resolution == Resolution::Abort,
            "abort",
            Resolution::Abort,
            resolution
        );
        let len = ch.len();
        crate::assert_with_log!(len == 0, "len", 0, len);
        crate::test_complete!("toy_channel_abort_usage");
    }

    #[test]
    #[should_panic(expected = "OBLIGATION LEAKED")]
    fn toy_channel_leaked_permit_panics() {
        init_test("toy_channel_leaked_permit_panics");
        let mut ch = toy_api::ToyChannel::new(10);
        let _permit = ch.reserve_send().expect("should get permit");
        // Dropped without commit or abort — panics.
    }

    #[test]
    fn toy_channel_full_returns_none() {
        init_test("toy_channel_full_returns_none");
        let mut ch = toy_api::ToyChannel::new(0);
        let permit = ch.reserve_send();
        let is_none = permit.is_none();
        crate::assert_with_log!(is_none, "full", true, is_none);
        crate::test_complete!("toy_channel_full_returns_none");
    }

    #[test]
    fn toy_channel_reservation_tracks_outstanding_capacity() {
        init_test("toy_channel_reservation_tracks_outstanding_capacity");
        let mut ch = toy_api::ToyChannel::new(1);

        let first = ch.reserve_send().expect("first permit should succeed");
        let second = ch.reserve_send();
        crate::assert_with_log!(
            second.is_none(),
            "second permit blocked by outstanding reservation",
            true,
            second.is_none()
        );

        let _proof = ch.abort_send(first);
        let retry = ch.reserve_send();
        let retry_present = retry.is_some();
        crate::assert_with_log!(
            retry_present,
            "capacity should reopen after abort",
            true,
            retry_present
        );
        let retry = retry.expect("retry permit should be present after abort");
        let _retry_proof = ch.abort_send(retry);
        crate::test_complete!("toy_channel_reservation_tracks_outstanding_capacity");
    }

    #[test]
    fn toy_channel_commit_rejects_wrong_obligation_kind() {
        init_test("toy_channel_commit_rejects_wrong_obligation_kind");
        let mut ch = toy_api::ToyChannel::from_state(1, Vec::new(), 1);
        let forged = GradedObligation::reserve(ObligationKind::Ack, "forged ack");

        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            ch.commit_send(forged, "hello".to_string())
        }));

        crate::assert_with_log!(
            result.is_err(),
            "wrong kind rejected",
            true,
            result.is_err()
        );
        crate::assert_with_log!(ch.is_empty(), "no message enqueued", true, ch.is_empty());
        let retry = ch.reserve_send();
        crate::assert_with_log!(
            retry.is_none(),
            "reservation count preserved after rejected commit",
            true,
            retry.is_none()
        );
        crate::test_complete!("toy_channel_commit_rejects_wrong_obligation_kind");
    }

    #[test]
    fn toy_channel_abort_rejects_wrong_obligation_kind() {
        init_test("toy_channel_abort_rejects_wrong_obligation_kind");
        let mut ch = toy_api::ToyChannel::from_state(1, Vec::new(), 1);
        let forged = GradedObligation::reserve(ObligationKind::Lease, "forged lease");

        let result =
            std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| ch.abort_send(forged)));

        crate::assert_with_log!(
            result.is_err(),
            "wrong kind rejected",
            true,
            result.is_err()
        );
        crate::assert_with_log!(ch.is_empty(), "abort does not enqueue", true, ch.is_empty());
        let retry = ch.reserve_send();
        crate::assert_with_log!(
            retry.is_none(),
            "reservation count preserved after rejected abort",
            true,
            retry.is_none()
        );
        crate::test_complete!("toy_channel_abort_rejects_wrong_obligation_kind");
    }

    // ---- Display impls -----------------------------------------------------

    #[test]
    fn display_impls() {
        init_test("graded_display_impls");
        let proof = ResolvedProof {
            kind: ObligationKind::SendPermit,
            resolution: Resolution::Commit,
        };
        let s = format!("{proof}");
        let has_resolved = s.contains("resolved");
        crate::assert_with_log!(has_resolved, "proof display", true, has_resolved);

        let scope_proof = ScopeProof {
            label: "test".to_string(),
            total_reserved: 3,
            total_resolved: 3,
        };
        let s = format!("{scope_proof}");
        let has_clean = s.contains("clean");
        crate::assert_with_log!(has_clean, "scope proof display", true, has_clean);

        let err = ScopeLeakError {
            label: "bad".to_string(),
            outstanding: 2,
            reserved: 5,
            resolved: 3,
        };
        let s = format!("{err}");
        let has_leaked = s.contains("leaked");
        crate::assert_with_log!(has_leaked, "scope error display", true, has_leaked);

        let resolution = format!("{}", Resolution::Commit);
        crate::assert_with_log!(
            resolution == "commit",
            "resolution display",
            "commit",
            resolution
        );

        crate::test_complete!("graded_display_impls");
    }

    // ---- Typing judgment demonstration -------------------------------------

    #[test]
    fn typing_judgment_demonstration() {
        init_test("typing_judgment_demonstration");
        // This test demonstrates the typing discipline:
        //
        // 1. reserve() creates an obligation (1 resource unit)
        // 2. resolve() consumes it (0 resource units)
        // 3. Scope verifies zero-leak at exit
        //
        // The key insight: in a linear type system, step 2 is mandatory.
        // In Rust (affine), we enforce it with Drop + #[must_use].

        let mut scope = GradedScope::open("typing_demo");

        // Typing rule: Γ ⊢ reserve(SendPermit) : Obligation<SendPermit>  [+1]
        let ob = GradedObligation::reserve(ObligationKind::SendPermit, "demo");
        scope.on_reserve();

        // Typing rule: Γ, ob: Obligation<SendPermit> ⊢ resolve(ob, Commit) : Proof  [-1]
        let proof = ob.resolve(Resolution::Commit);
        scope.on_resolve();

        // Typing rule: Γ ⊢ scope_close : ScopeProof   [requires 0 outstanding]
        let scope_proof = scope.close().expect("scope should be clean");

        // Verify the proof tokens exist (zero-cost witnesses).
        let kind = proof.kind();
        crate::assert_with_log!(
            kind == ObligationKind::SendPermit,
            "proof kind",
            ObligationKind::SendPermit,
            kind
        );
        let label = scope_proof.label();
        crate::assert_with_log!(label == "typing_demo", "scope label", "typing_demo", label);

        crate::test_complete!("typing_judgment_demonstration");
    }

    // ---- Resource semiring properties --------------------------------------

    #[test]
    fn resource_semiring_identity() {
        init_test("resource_semiring_identity");
        // 0 is the identity for +: scope with 0 obligations is clean.
        let scope = GradedScope::open("zero");
        let proof = scope.close().expect("zero obligations = clean");
        let total = proof.total_reserved();
        crate::assert_with_log!(total == 0, "zero reserved", 0, total);
        crate::test_complete!("resource_semiring_identity");
    }

    #[test]
    fn resource_semiring_additive() {
        init_test("resource_semiring_additive");
        // + is additive: obligations accumulate and must all be resolved.
        let mut scope = GradedScope::open("additive");

        // Reserve 3 obligations (1 + 1 + 1 = 3).
        for _ in 0..3 {
            let ob = GradedObligation::reserve(ObligationKind::Lease, "lease");
            scope.on_reserve();
            let _proof = ob.resolve(Resolution::Commit);
            scope.on_resolve();
        }

        let proof = scope.close().expect("all resolved");
        let total = proof.total_reserved();
        crate::assert_with_log!(total == 3, "3 reserved", 3, total);
        let resolved = proof.total_resolved();
        crate::assert_with_log!(resolved == 3, "3 resolved", 3, resolved);
        crate::test_complete!("resource_semiring_additive");
    }

    // ---- ObligationToken typestate tests ------------------------------------

    #[test]
    fn token_commit_returns_proof() {
        init_test("token_commit_returns_proof");
        let token: SendPermitToken = ObligationToken::reserve_test("commit-test");
        let proof = token.commit();
        let kind = proof.kind();
        crate::assert_with_log!(
            kind == ObligationKind::SendPermit,
            "proof kind",
            ObligationKind::SendPermit,
            kind
        );
        crate::test_complete!("token_commit_returns_proof");
    }

    #[test]
    fn token_abort_returns_proof() {
        init_test("token_abort_returns_proof");
        let token: AckToken = ObligationToken::reserve_test("abort-test");
        let proof = token.abort();
        let kind = proof.kind();
        crate::assert_with_log!(
            kind == ObligationKind::Ack,
            "proof kind",
            ObligationKind::Ack,
            kind
        );
        crate::test_complete!("token_abort_returns_proof");
    }

    #[test]
    fn token_dynamic_kind_bridge_accepts_matching_hot_path_kind() {
        init_test("token_dynamic_kind_bridge_accepts_matching_hot_path_kind");
        let token: SendPermitToken = ObligationToken::try_reserve_kind(
            ObligationKind::SendPermit,
            "hot-path send",
            RegionId::new_ephemeral(),
        )
        .expect("send permit dynamic kind should map to SendPermitToken");

        let proof = token.commit();
        crate::assert_with_log!(
            proof.kind() == ObligationKind::SendPermit,
            "typed proof kind",
            ObligationKind::SendPermit,
            proof.kind()
        );
        let resolved = proof.into_resolved_proof();
        crate::assert_with_log!(
            resolved.resolution() == Resolution::Commit,
            "resolved proof",
            Resolution::Commit,
            resolved.resolution()
        );
        crate::test_complete!("token_dynamic_kind_bridge_accepts_matching_hot_path_kind");
    }

    #[test]
    fn token_dynamic_kind_bridge_rejects_mismatched_protocol_family() {
        init_test("token_dynamic_kind_bridge_rejects_mismatched_protocol_family");
        let err = SendPermitToken::try_reserve_kind(
            ObligationKind::Ack,
            "wrong dynamic family",
            RegionId::new_ephemeral(),
        )
        .expect_err("Ack must not manufacture a SendPermitToken");

        crate::assert_with_log!(
            err.expected == ObligationKind::SendPermit,
            "expected typed kind",
            ObligationKind::SendPermit,
            err.expected
        );
        crate::assert_with_log!(
            err.actual == ObligationKind::Ack,
            "actual dynamic kind",
            ObligationKind::Ack,
            err.actual
        );
        crate::assert_with_log!(
            format!("{err}").contains("expected send_permit, got ack"),
            "diagnostic",
            true,
            format!("{err}").contains("expected send_permit, got ack")
        );
        crate::test_complete!("token_dynamic_kind_bridge_rejects_mismatched_protocol_family");
    }

    #[test]
    fn scoped_dynamic_kind_bridge_tracks_abort_cleanup_parity() {
        init_test("scoped_dynamic_kind_bridge_tracks_abort_cleanup_parity");
        let mut scope = GradedScope::open("lease-hot-path");
        let token: LeaseToken = scope
            .try_reserve_token_kind(ObligationKind::Lease, "lease cancellation cleanup")
            .expect("Lease dynamic kind should map to LeaseToken");
        crate::assert_with_log!(scope.outstanding() == 1, "reserved", 1, scope.outstanding());

        let proof = scope.resolve_abort(token);
        crate::assert_with_log!(
            proof.kind() == ObligationKind::Lease,
            "abort proof kind",
            ObligationKind::Lease,
            proof.kind()
        );
        let resolved = proof.into_resolved_proof();
        crate::assert_with_log!(
            resolved.resolution() == Resolution::Abort,
            "abort bridges to resolved proof",
            Resolution::Abort,
            resolved.resolution()
        );

        let scope_proof = scope.close().expect("abort must leave scope balanced");
        crate::assert_with_log!(
            scope_proof.total_reserved() == 1,
            "scope reserved count",
            1,
            scope_proof.total_reserved()
        );
        crate::assert_with_log!(
            scope_proof.total_resolved() == 1,
            "scope resolved count",
            1,
            scope_proof.total_resolved()
        );
        crate::test_complete!("scoped_dynamic_kind_bridge_tracks_abort_cleanup_parity");
    }

    #[test]
    fn scoped_dynamic_kind_bridge_mismatch_does_not_increment_scope() {
        init_test("scoped_dynamic_kind_bridge_mismatch_does_not_increment_scope");
        let mut scope = GradedScope::open("mismatch");
        let err = scope
            .try_reserve_token_kind::<AckKind>(ObligationKind::SendPermit, "wrong ack family")
            .expect_err("SendPermit must not reserve AckToken scope state");

        crate::assert_with_log!(
            err.expected == ObligationKind::Ack,
            "expected typed kind",
            ObligationKind::Ack,
            err.expected
        );
        crate::assert_with_log!(
            err.actual == ObligationKind::SendPermit,
            "actual dynamic kind",
            ObligationKind::SendPermit,
            err.actual
        );
        crate::assert_with_log!(
            scope.outstanding() == 0,
            "mismatch leaves scope empty",
            0,
            scope.outstanding()
        );
        let proof = scope.close().expect("mismatch must not leak scope state");
        crate::assert_with_log!(
            proof.total_reserved() == 0,
            "no reservation recorded",
            0,
            proof.total_reserved()
        );
        crate::test_complete!("scoped_dynamic_kind_bridge_mismatch_does_not_increment_scope");
    }

    #[test]
    fn typed_obligation_bridge_contract_logs_required_evidence_fields() {
        init_test("typed_obligation_bridge_contract_logs_required_evidence_fields");
        let contract = typed_obligation_bridge_contract();

        crate::assert_with_log!(
            contract.bead_id == "asupersync-d87ytw.13",
            "bead id",
            "asupersync-d87ytw.13",
            contract.bead_id
        );
        crate::assert_with_log!(
            contract.protocol_family.contains("send-permit")
                && contract.protocol_family.contains("lease"),
            "protocol family",
            "send-permit/ack/lease graded obligations",
            contract.protocol_family
        );
        crate::assert_with_log!(
            contract
                .typed_entrypoint
                .ends_with("ObligationToken::try_reserve_kind"),
            "typed entrypoint",
            "ObligationToken::try_reserve_kind",
            contract.typed_entrypoint
        );
        crate::assert_with_log!(
            contract.dynamic_fallback == "asupersync::record::ObligationKind",
            "dynamic fallback",
            "asupersync::record::ObligationKind",
            contract.dynamic_fallback
        );
        crate::assert_with_log!(
            contract.compile_fail_surface.contains("commit-then-abort"),
            "compile-fail surface",
            "commit-then-abort",
            contract.compile_fail_surface
        );
        crate::assert_with_log!(
            contract.replay_command.contains("rch exec --")
                && contract
                    .replay_command
                    .contains("--lib dynamic_kind_bridge"),
            "replay command",
            "rch exec -- cargo test --lib dynamic_kind_bridge",
            contract.replay_command
        );
        crate::assert_with_log!(
            contract
                .invariants
                .contains(&"mismatched dynamic kind does not arm a token"),
            "migration fallback invariant",
            true,
            contract
                .invariants
                .contains(&"mismatched dynamic kind does not arm a token")
        );
        crate::test_complete!("typed_obligation_bridge_contract_logs_required_evidence_fields");
    }

    #[test]
    #[should_panic(expected = "OBLIGATION TOKEN LEAKED")]
    fn token_drop_without_consume_panics() {
        init_test("token_drop_without_consume_panics");
        let _token: SendPermitToken = ObligationToken::reserve_test("leaked-token");
        // Dropped without commit or abort — should panic.
    }

    #[test]
    fn token_into_raw_disarms() {
        init_test("token_into_raw_disarms");
        let token: LeaseToken = ObligationToken::reserve_test("raw-escape");
        let raw = token.into_raw();
        let kind = raw.kind;
        crate::assert_with_log!(
            kind == ObligationKind::Lease,
            "raw kind",
            ObligationKind::Lease,
            kind
        );
        drop(raw);
        crate::test_complete!("token_into_raw_disarms");
    }

    #[test]
    fn committed_proof_bridge() {
        init_test("committed_proof_bridge");
        let token: SendPermitToken = ObligationToken::reserve_test("bridge-commit");
        let committed = token.commit();
        let resolved = committed.into_resolved_proof();
        let r = resolved.resolution();
        crate::assert_with_log!(r == Resolution::Commit, "resolution", Resolution::Commit, r);
        let kind = resolved.kind();
        crate::assert_with_log!(
            kind == ObligationKind::SendPermit,
            "kind",
            ObligationKind::SendPermit,
            kind
        );
        crate::test_complete!("committed_proof_bridge");
    }

    #[test]
    fn aborted_proof_bridge() {
        init_test("aborted_proof_bridge");
        let token: AckToken = ObligationToken::reserve_test("bridge-abort");
        let aborted = token.abort();
        let resolved = aborted.into_resolved_proof();
        let r = resolved.resolution();
        crate::assert_with_log!(r == Resolution::Abort, "resolution", Resolution::Abort, r);
        let kind = resolved.kind();
        crate::assert_with_log!(
            kind == ObligationKind::Ack,
            "kind",
            ObligationKind::Ack,
            kind
        );
        crate::test_complete!("aborted_proof_bridge");
    }

    #[test]
    fn token_kind_mapping() {
        init_test("token_kind_mapping");
        let sp = SendPermit::obligation_kind();
        crate::assert_with_log!(
            sp == ObligationKind::SendPermit,
            "SendPermit",
            ObligationKind::SendPermit,
            sp
        );
        let ack = AckKind::obligation_kind();
        crate::assert_with_log!(
            ack == ObligationKind::Ack,
            "AckKind",
            ObligationKind::Ack,
            ack
        );
        let lease = LeaseKind::obligation_kind();
        crate::assert_with_log!(
            lease == ObligationKind::Lease,
            "LeaseKind",
            ObligationKind::Lease,
            lease
        );
        let io = IoOpKind::obligation_kind();
        crate::assert_with_log!(
            io == ObligationKind::IoOp,
            "IoOpKind",
            ObligationKind::IoOp,
            io
        );
        crate::test_complete!("token_kind_mapping");
    }

    #[test]
    fn scope_reserve_and_commit_token() {
        init_test("scope_reserve_and_commit_token");
        let mut scope = GradedScope::open("token-scope-commit");
        let token: SendPermitToken = scope.reserve_token("scoped-send");
        let outstanding = scope.outstanding();
        crate::assert_with_log!(outstanding == 1, "outstanding", 1, outstanding);

        let proof = scope.resolve_commit(token);
        let outstanding = scope.outstanding();
        crate::assert_with_log!(outstanding == 0, "outstanding", 0, outstanding);

        let kind = proof.kind();
        crate::assert_with_log!(
            kind == ObligationKind::SendPermit,
            "kind",
            ObligationKind::SendPermit,
            kind
        );

        let scope_proof = scope.close().expect("scope should close cleanly");
        let total = scope_proof.total_reserved();
        crate::assert_with_log!(total == 1, "reserved", 1, total);
        crate::test_complete!("scope_reserve_and_commit_token");
    }

    #[test]
    fn scope_reserve_and_abort_token() {
        init_test("scope_reserve_and_abort_token");
        let mut scope = GradedScope::open("token-scope-abort");
        let token: AckToken = scope.reserve_token("scoped-ack");
        let outstanding = scope.outstanding();
        crate::assert_with_log!(outstanding == 1, "outstanding", 1, outstanding);

        let proof = scope.resolve_abort(token);
        let outstanding = scope.outstanding();
        crate::assert_with_log!(outstanding == 0, "outstanding", 0, outstanding);

        let kind = proof.kind();
        crate::assert_with_log!(
            kind == ObligationKind::Ack,
            "kind",
            ObligationKind::Ack,
            kind
        );

        let scope_proof = scope.close().expect("scope should close cleanly");
        let total = scope_proof.total_reserved();
        crate::assert_with_log!(total == 1, "reserved", 1, total);
        crate::test_complete!("scope_reserve_and_abort_token");
    }

    #[test]
    fn all_four_token_kinds() {
        init_test("all_four_token_kinds");

        // SendPermit
        let t1: SendPermitToken = ObligationToken::reserve_test("sp");
        let p1 = t1.commit();
        let k1 = p1.kind();
        crate::assert_with_log!(
            k1 == ObligationKind::SendPermit,
            "SendPermit",
            ObligationKind::SendPermit,
            k1
        );

        // Ack
        let t2: AckToken = ObligationToken::reserve_test("ack");
        let p2 = t2.abort();
        let k2 = p2.kind();
        crate::assert_with_log!(k2 == ObligationKind::Ack, "Ack", ObligationKind::Ack, k2);

        // Lease
        let t3: LeaseToken = ObligationToken::reserve_test("lease");
        let p3 = t3.commit();
        let k3 = p3.kind();
        crate::assert_with_log!(
            k3 == ObligationKind::Lease,
            "Lease",
            ObligationKind::Lease,
            k3
        );

        // IoOp
        let t4: IoOpToken = ObligationToken::reserve_test("io");
        let p4 = t4.abort();
        let k4 = p4.kind();
        crate::assert_with_log!(k4 == ObligationKind::IoOp, "IoOp", ObligationKind::IoOp, k4);

        crate::test_complete!("all_four_token_kinds");
    }

    // =========================================================================
    // Wave 59 – pure data-type trait coverage
    // =========================================================================

    #[test]
    fn resolution_debug_clone_copy_eq() {
        let r = Resolution::Commit;
        let dbg = format!("{r:?}");
        assert!(dbg.contains("Commit"), "{dbg}");
        let copied = r;
        let cloned = r;
        assert_eq!(copied, cloned);
        assert_ne!(r, Resolution::Abort);
    }

    #[test]
    fn resolved_proof_debug_eq() {
        let rp = ResolvedProof {
            kind: ObligationKind::SendPermit,
            resolution: Resolution::Commit,
        };
        let dbg = format!("{rp:?}");
        assert!(dbg.contains("ResolvedProof"), "{dbg}");
        let rp_same = ResolvedProof {
            kind: ObligationKind::SendPermit,
            resolution: Resolution::Commit,
        };
        assert_eq!(rp, rp_same);
    }

    #[test]
    fn scope_proof_debug_accessors() {
        let sp = ScopeProof {
            label: "test".to_string(),
            total_reserved: 5,
            total_resolved: 5,
        };
        let dbg = format!("{sp:?}");
        assert!(dbg.contains("ScopeProof"), "{dbg}");
        assert_eq!(sp.label(), "test");
        assert_eq!(sp.total_reserved(), 5);
        assert_eq!(sp.total_resolved(), 5);
    }

    #[test]
    #[should_panic(expected = "on_reserve overflowed outstanding obligation count")]
    fn scope_on_reserve_overflow_panics_instead_of_wrapping() {
        let mut scope = GradedScope {
            label: "overflow".to_string(),
            reserved: u32::MAX,
            resolved: 0,
            closed: false,
        };
        scope.on_reserve();
    }

    #[test]
    #[should_panic(expected = "toy channel occupancy overflowed")]
    fn toy_channel_capacity_overflow_panics_instead_of_wrapping() {
        let mut ch =
            toy_api::ToyChannel::from_state(usize::MAX, vec!["occupied".to_string()], usize::MAX);
        let _ = ch.reserve_send();
    }

    #[test]
    fn close_err_does_not_panic_when_caller_handles_error() {
        let mut scope = GradedScope::open("leak-test");
        scope.on_reserve();
        // close() returns Err because 1 obligation is outstanding.
        // The caller explicitly called close() and received the error,
        // so Drop should NOT panic — the leak is acknowledged.
        let err = scope.close().expect_err("should return leak error");
        assert_eq!(err.outstanding, 1);
    }

    // ========================================================================
    // GRADED-REFINEMENT conformance harness (Pattern 4: spec-derived)
    //
    // The typing judgment at the top of this module is the spec:
    //
    //   Γ ⊢ reserve(K)     : Obligation<K>     [+1 unit of K]
    //   Γ, x: Obligation<K> ⊢ commit(x) : ()   [-1 unit of K]
    //   Γ, x: Obligation<K> ⊢ abort(x)  : ()   [-1 unit of K]
    //   Γ ⊢ scope(body) : τ   iff   Γ_exit has 0 outstanding Obligation<K>
    //
    // Each GRADED-REFINEMENT-N clause below mechanically verifies one
    // refinement-boundary law implied by the judgment.
    //
    // Every case emits one stderr JSON-line verdict of shape:
    //   {"id":"GRADED-REFINEMENT-N","verdict":"PASS|FAIL","level":"MUST"}
    // so a CI harness can grep+count pass/fail without parsing panics.
    // ========================================================================

    fn emit_verdict(id: &str, pass: bool) {
        eprintln!(
            "{{\"id\":\"{id}\",\"verdict\":\"{}\",\"level\":\"MUST\"}}",
            if pass { "PASS" } else { "FAIL" }
        );
    }

    // GRADED-REFINEMENT-1: reserve(K) increases reserved count by exactly 1.
    #[test]
    fn conformance_graded_refinement_1_reserve_is_plus_one() {
        init_test("GRADED-REFINEMENT-1");
        let mut scope = GradedScope::open("L1");
        let r0 = scope.outstanding();
        scope.on_reserve();
        let r1 = scope.outstanding();
        let pass = r0 == 0 && r1 == 1;
        emit_verdict("GRADED-REFINEMENT-1", pass);
        // Clean up so Drop doesn't panic.
        scope.on_resolve();
        let _ = scope.close();
        assert!(pass, "reserve did not increment outstanding by exactly 1");
    }

    // GRADED-REFINEMENT-2: commit(x) decreases outstanding by exactly 1.
    #[test]
    fn conformance_graded_refinement_2_commit_is_minus_one() {
        init_test("GRADED-REFINEMENT-2");
        let mut scope = GradedScope::open("L2");
        scope.on_reserve();
        let before = scope.outstanding();
        let tok: ObligationToken<SendPermit> = ObligationToken::reserve_test("L2");
        let _proof = tok.commit(); // consume token
        scope.on_resolve();
        let after = scope.outstanding();
        let pass = before == 1 && after == 0;
        emit_verdict("GRADED-REFINEMENT-2", pass);
        let _ = scope.close();
        assert!(pass, "commit did not decrement outstanding by exactly 1");
    }

    // GRADED-REFINEMENT-3: abort(x) decreases outstanding by exactly 1
    // (symmetric with commit: the refinement sees only "resolved").
    #[test]
    fn conformance_graded_refinement_3_abort_is_minus_one() {
        init_test("GRADED-REFINEMENT-3");
        let mut scope = GradedScope::open("L3");
        scope.on_reserve();
        let before = scope.outstanding();
        let tok: ObligationToken<AckKind> = ObligationToken::reserve_test("L3");
        let _proof = tok.abort();
        scope.on_resolve();
        let after = scope.outstanding();
        let pass = before == 1 && after == 0;
        emit_verdict("GRADED-REFINEMENT-3", pass);
        let _ = scope.close();
        assert!(pass, "abort did not decrement outstanding by exactly 1");
    }

    // GRADED-REFINEMENT-4: scope close() at 0 outstanding yields a ScopeProof
    // whose total_reserved == total_resolved.
    #[test]
    fn conformance_graded_refinement_4_close_clean_boundary() {
        init_test("GRADED-REFINEMENT-4");
        let mut scope = GradedScope::open("L4");
        for _ in 0..7 {
            scope.on_reserve();
            scope.on_resolve();
        }
        let result = scope.close();
        let pass = match &result {
            Ok(p) => p.total_reserved() == 7 && p.total_resolved() == 7,
            Err(_) => false,
        };
        emit_verdict("GRADED-REFINEMENT-4", pass);
        assert!(
            pass,
            "close() at 0 outstanding did not produce matching counts"
        );
    }

    // GRADED-REFINEMENT-5: scope close() with outstanding > 0 yields a
    // ScopeLeakError whose fields satisfy reserved - resolved == outstanding.
    #[test]
    fn conformance_graded_refinement_5_close_leak_exact_accounting() {
        init_test("GRADED-REFINEMENT-5");
        let mut scope = GradedScope::open("L5");
        for _ in 0..5 {
            scope.on_reserve();
        }
        for _ in 0..2 {
            scope.on_resolve();
        }
        let err = scope.close().expect_err("expected leak");
        let pass = err.reserved == 5
            && err.resolved == 2
            && err.outstanding == err.reserved - err.resolved
            && err.outstanding == 3;
        emit_verdict("GRADED-REFINEMENT-5", pass);
        assert!(pass, "leak accounting diverges from reserved - resolved");
    }

    // GRADED-REFINEMENT-6: outstanding() is a pure function of the running
    // net of reserves vs. resolves. After any prefix of a balanced interleaving,
    // outstanding() == (#reserves_seen - #resolves_seen) and is non-negative.
    //
    // Note: on_resolve() panics if called more times than on_reserve(), so the
    // op sequence below is a valid prefix (net never goes negative).
    #[test]
    fn conformance_graded_refinement_6_outstanding_tracks_running_net() {
        init_test("GRADED-REFINEMENT-6");
        let mut scope = GradedScope::open("L6");
        let ops = [
            true, true, false, true, false, false, true, true, false, false,
        ];
        let mut net: i64 = 0;
        let mut ok = true;
        for reserve in ops {
            if reserve {
                scope.on_reserve();
                net += 1;
            } else {
                scope.on_resolve();
                net -= 1;
            }
            let got = i64::from(scope.outstanding());
            if got != net || net < 0 {
                ok = false;
            }
        }
        // Balanced: outstanding must be exactly 0 at the end.
        ok = ok && scope.outstanding() == 0 && net == 0;
        emit_verdict("GRADED-REFINEMENT-6", ok);
        let _ = scope.close();
        assert!(ok, "outstanding diverged from the running net of ops");
    }

    // GRADED-REFINEMENT-7: Resolution preserves obligation kind.
    // GradedObligation::reserve(K, _).resolve(r).kind() == K.
    #[test]
    fn conformance_graded_refinement_7_resolution_preserves_kind() {
        init_test("GRADED-REFINEMENT-7");
        let cases = [
            (ObligationKind::SendPermit, Resolution::Commit),
            (ObligationKind::SendPermit, Resolution::Abort),
            (ObligationKind::Ack, Resolution::Commit),
            (ObligationKind::Ack, Resolution::Abort),
            (ObligationKind::Lease, Resolution::Commit),
            (ObligationKind::Lease, Resolution::Abort),
            (ObligationKind::IoOp, Resolution::Commit),
            (ObligationKind::IoOp, Resolution::Abort),
            (ObligationKind::SemaphorePermit, Resolution::Commit),
            (ObligationKind::SemaphorePermit, Resolution::Abort),
        ];
        let mut pass = true;
        for (k, r) in cases {
            let ob = GradedObligation::reserve(k, "kind-test");
            let proof = ob.resolve(r);
            if proof.kind() != k || proof.resolution() != r {
                pass = false;
            }
        }
        emit_verdict("GRADED-REFINEMENT-7", pass);
        assert!(pass, "resolution dropped kind or resolution on the floor");
    }

    // GRADED-REFINEMENT-8: Typestate ObligationToken<K> preserves K through
    // CommittedProof<K> / AbortedProof<K>.
    #[test]
    fn conformance_graded_refinement_8_typestate_preserves_kind() {
        init_test("GRADED-REFINEMENT-8");
        let send_commit = <SendPermit as TokenKind>::obligation_kind();
        let ack_abort = <AckKind as TokenKind>::obligation_kind();

        let t1: SendPermitToken = ObligationToken::reserve_test("send");
        let p1 = t1.commit();
        let pass1 = p1.kind() == send_commit && p1.into_resolved_proof().kind() == send_commit;

        let t2: AckToken = ObligationToken::reserve_test("ack");
        let p2 = t2.abort();
        let pass2 = p2.kind() == ack_abort && p2.into_resolved_proof().kind() == ack_abort;

        let pass = pass1 && pass2;
        emit_verdict("GRADED-REFINEMENT-8", pass);
        assert!(pass, "typestate token lost kind across commit/abort");
    }

    // GRADED-REFINEMENT-9: into_raw() disarms the drop bomb AND preserves kind.
    #[test]
    fn conformance_graded_refinement_9_into_raw_disarms_and_preserves_kind() {
        init_test("GRADED-REFINEMENT-9");
        let ob = GradedObligation::reserve(ObligationKind::Lease, "raw");
        let raw = ob.into_raw();
        let pass_a = raw.kind == ObligationKind::Lease && raw.description == "raw";

        let tok: LeaseToken = ObligationToken::reserve_test("raw-ts");
        let raw2 = tok.into_raw();
        let pass_b = raw2.kind == ObligationKind::Lease && raw2.description == "raw-ts";

        // If into_raw did NOT disarm the drop bomb, the two calls above would
        // have panicked. Reaching this point is the disarm proof.
        let pass = pass_a && pass_b;
        emit_verdict("GRADED-REFINEMENT-9", pass);
        assert!(
            pass,
            "into_raw lost kind or description across the boundary"
        );
    }

    // GRADED-REFINEMENT-10: Boundary monotonicity — scope close() returning
    // Ok implies all ScopeProof counts are ≥ 0 and total_reserved == total_resolved;
    // scope close() returning Err implies outstanding > 0 and
    // reserved > resolved. Cases are disjoint and cover the boundary.
    #[test]
    fn conformance_graded_refinement_10_close_boundary_disjoint() {
        init_test("GRADED-REFINEMENT-10");
        // Clean side.
        let mut clean = GradedScope::open("L10-clean");
        for _ in 0..3 {
            clean.on_reserve();
            clean.on_resolve();
        }
        let clean_ok = clean.close();
        let clean_pass =
            matches!(&clean_ok, Ok(p) if p.total_reserved() == 3 && p.total_resolved() == 3);

        // Leaky side.
        let mut leaky = GradedScope::open("L10-leaky");
        for _ in 0..4 {
            leaky.on_reserve();
        }
        for _ in 0..1 {
            leaky.on_resolve();
        }
        let leaky_err = leaky.close();
        let leaky_pass = matches!(
            &leaky_err,
            Err(e) if e.outstanding == 3 && e.reserved > e.resolved && e.reserved == 4 && e.resolved == 1
        );

        let pass = clean_pass && leaky_pass;
        emit_verdict("GRADED-REFINEMENT-10", pass);
        assert!(
            pass,
            "close() boundary cases are not disjoint or mis-accounted"
        );
    }
}