rust_key_paths/

lock.rs

//! # Lock Keypath Module
//!
//! This module provides `LockKp` for safely navigating through locked/synchronized data structures.
//!
//! # Naming convention (aligned with [crate::Kp] and [crate::async_lock])
//!
//! - **`then`** – chain with a plain [crate::Kp]
//! - **`then_lock`** – chain with another [LockKp] for multi-level lock access
//!
//! # SHALLOW CLONING GUARANTEE & NO UNNECESSARY CLONES
//!
//! **IMPORTANT**: All cloning operations in this module are SHALLOW (reference-counted) clones:
//!
//! 1. **`LockKp` derives `Clone`**: Clones function pointers and PhantomData only
//!    - `prev` and `next` fields contain function pointers (cheap to copy)
//!    - `mid` field is typically just `PhantomData<T>` (zero-sized, zero-cost)
//!    - No heap allocations or deep data copies
//!
//! 2. **NO `Lock: Clone` required for most operations**:
//!    - `lock_write` takes `&Lock` (not `&mut Lock`) due to interior mutability
//!    - For `Arc<Mutex<T>>`: No cloning needed, we just use `&Arc<...>`
//!    - The actual data `T` inside is **NEVER** cloned during lock operations
//!    - This eliminates unnecessary Arc reference count increments
//!
//! 3. **`L: Clone` bound** (e.g., `ArcMutexAccess<T>`):
//!    - Only clones `PhantomData<T>` which is zero-sized
//!    - Compiled away completely - zero runtime cost
//!
//! ## Performance Characteristics
//!
//! - `LockKp::clone()`: O(1) - copies a few pointers
//! - `ArcMutexAccess::clone()`: O(1) - no-op (zero-sized type)
//! - **Lock operations**: No Arc cloning needed - direct reference use
//! - **Total**: All operations are constant-time with no deep copying
//!
//! ## Memory Safety
//!
//! The design is safe because:
//! - Locks provide interior mutability (no `&mut` needed for write operations)
//! - `Arc` provides thread-safe reference counting
//! - `Mutex` ensures exclusive access when needed
//! - No dangling pointers or use-after-free possible
//! - Rust's ownership system enforces correctness

use crate::Kp;
use std::sync::{Arc, Mutex};

/// Trait for types that can provide lock/unlock behavior
/// Converts from a Lock type to Inner or InnerMut value
pub trait LockAccess<Lock, Inner> {
    /// Get immutable access to the inner value
    fn lock_read(&self, lock: &Lock) -> Option<Inner>;

    /// Get mutable access to the inner value
    ///
    /// Note: Takes `&Lock` not `&mut Lock` because locks like Mutex/RwLock
    /// provide interior mutability - we don't need exclusive access to the
    /// lock container itself, just to the data inside.
    fn lock_write(&self, lock: &Lock) -> Option<Inner>;
}

/// A keypath that handles locked values (e.g., Arc<Mutex<T>>)
///
/// Structure:
/// - `prev`: Keypath from Root to Lock container (e.g., Arc<Mutex<Mid>>)
/// - `mid`: Lock access handler that goes from Lock to Inner value
/// - `next`: Keypath from Inner value to final Value
///
/// # Type Parameters
/// - `R`: Root type (base)
/// - `Lock`: Lock container type (e.g., Arc<Mutex<Mid>>)
/// - `Mid`: The type inside the lock
/// - `V`: Final value type
/// - Rest are the same generic parameters as Kp
///
/// # Cloning Behavior
///
/// **IMPORTANT**: All `Clone` operations in this struct are SHALLOW clones:
///
/// - `LockKp` itself derives `Clone` - this clones the three field references/closures
/// - `prev` and `next` fields are `Kp` structs containing function pointers (cheap to clone)
/// - `mid` field implements `LockAccess` trait - typically just `PhantomData` (zero-cost clone)
/// - NO `Lock: Clone` needed for lock operations - we use `&Lock` directly via interior mutability
/// - NO deep data cloning occurs - all clones are pointer/reference copies
///
/// # Example
/// ```
/// use std::sync::{Arc, Mutex};
///
/// struct Root {
///     data: Arc<Mutex<Inner>>,
/// }
///
/// struct Inner {
///     value: String,
/// }
///
/// // Create a LockKp that goes: Root -> Arc<Mutex<Inner>> -> String
/// let lock_kp = LockKp::new(
///     root_to_lock_kp,
///     ArcMutexAccess::new(),
///     inner_to_value_kp,
/// );
/// ```
#[derive(Clone)] // SHALLOW: Clones function pointers and PhantomData only
pub struct LockKp<
    R,
    Lock,
    Mid,
    V,
    Root,
    LockValue,
    MidValue,
    Value,
    MutRoot,
    MutLock,
    MutMid,
    MutValue,
    G1,
    S1,
    L,
    G2,
    S2,
> where
    Root: std::borrow::Borrow<R>,
    LockValue: std::borrow::Borrow<Lock>,
    MidValue: std::borrow::Borrow<Mid>,
    Value: std::borrow::Borrow<V>,
    MutRoot: std::borrow::BorrowMut<R>,
    MutLock: std::borrow::BorrowMut<Lock>,
    MutMid: std::borrow::BorrowMut<Mid>,
    MutValue: std::borrow::BorrowMut<V>,
    G1: Fn(Root) -> Option<LockValue>,
    S1: Fn(MutRoot) -> Option<MutLock>,
    L: LockAccess<Lock, MidValue> + LockAccess<Lock, MutMid>,
    G2: Fn(MidValue) -> Option<Value>,
    S2: Fn(MutMid) -> Option<MutValue>,
{
    /// Keypath from Root to Lock container
    pub prev: Kp<R, Lock, Root, LockValue, MutRoot, MutLock, G1, S1>,

    /// Lock access handler (converts Lock -> Inner)
    pub mid: L,

    /// Keypath from Inner to final Value
    pub next: Kp<Mid, V, MidValue, Value, MutMid, MutValue, G2, S2>,
}

impl<
    R,
    Lock,
    Mid,
    V,
    Root,
    LockValue,
    MidValue,
    Value,
    MutRoot,
    MutLock,
    MutMid,
    MutValue,
    G1,
    S1,
    L,
    G2,
    S2,
>
    LockKp<
        R,
        Lock,
        Mid,
        V,
        Root,
        LockValue,
        MidValue,
        Value,
        MutRoot,
        MutLock,
        MutMid,
        MutValue,
        G1,
        S1,
        L,
        G2,
        S2,
    >
where
    Root: std::borrow::Borrow<R>,
    LockValue: std::borrow::Borrow<Lock>,
    MidValue: std::borrow::Borrow<Mid>,
    Value: std::borrow::Borrow<V>,
    MutRoot: std::borrow::BorrowMut<R>,
    MutLock: std::borrow::BorrowMut<Lock>,
    MutMid: std::borrow::BorrowMut<Mid>,
    MutValue: std::borrow::BorrowMut<V>,
    G1: Fn(Root) -> Option<LockValue>,
    S1: Fn(MutRoot) -> Option<MutLock>,
    L: LockAccess<Lock, MidValue> + LockAccess<Lock, MutMid>,
    G2: Fn(MidValue) -> Option<Value>,
    S2: Fn(MutMid) -> Option<MutValue>,
{
    /// Create a new LockKp with prev, mid, and next components
    pub fn new(
        prev: Kp<R, Lock, Root, LockValue, MutRoot, MutLock, G1, S1>,
        mid: L,
        next: Kp<Mid, V, MidValue, Value, MutMid, MutValue, G2, S2>,
    ) -> Self {
        Self { prev, mid, next }
    }

    /// Get the value through the lock
    ///
    /// This will:
    /// 1. Use `prev` to get to the Lock
    /// 2. Use `mid` to lock and get Inner value
    /// 3. Use `next` to get from Inner to final Value
    ///
    /// Get an immutable reference through the lock.
    ///
    /// # Cloning Behavior
    /// Only requires `V: Clone` for the final value.
    /// NO `Lock: Clone` needed because `lock_read` takes `&Lock`.
    #[inline]
    pub fn get(&self, root: Root) -> Option<Value>
    where
        V: Clone,
    {
        (self.prev.get)(root).and_then(|lock_value| {
            let lock: &Lock = lock_value.borrow();
            self.mid
                .lock_read(lock)
                .and_then(|mid_value| (self.next.get)(mid_value))
        })
    }

    /// Get mutable access to the value through the lock
    ///
    /// # NO CLONING Required!
    ///
    /// No longer needs `Lock: Clone` because `lock_write` now takes `&Lock` instead of `&mut Lock`
    #[inline]
    pub fn get_mut(&self, root: MutRoot) -> Option<MutValue> {
        (self.prev.set)(root).and_then(|mut lock_value| {
            let lock: &Lock = lock_value.borrow();
            self.mid
                .lock_write(lock)
                .and_then(|mid_value| (self.next.set)(mid_value))
        })
    }

    /// Set the value through the lock using an updater function
    ///
    /// # NO CLONING Required!
    ///
    /// Unlike the original implementation, we NO LONGER need `Lock: Clone` because:
    /// - Locks like `Mutex` and `RwLock` provide interior mutability
    /// - We only need `&Lock`, not `&mut Lock`, to get mutable access to the inner data
    /// - This eliminates an unnecessary Arc reference count increment
    pub fn set<F>(&self, root: Root, updater: F) -> Result<(), String>
    where
        F: FnOnce(&mut V),
        MutValue: std::borrow::BorrowMut<V>,
    {
        (self.prev.get)(root)
            .ok_or_else(|| "Failed to get lock container".to_string())
            .and_then(|lock_value| {
                let lock: &Lock = lock_value.borrow();
                // NO CLONE NEEDED! lock_write now takes &Lock instead of &mut Lock
                self.mid
                    .lock_write(lock)
                    .ok_or_else(|| "Failed to lock".to_string())
                    .and_then(|mid_value| {
                        (self.next.set)(mid_value)
                            .ok_or_else(|| "Failed to get value".to_string())
                            .map(|mut value| {
                                updater(value.borrow_mut());
                            })
                    })
            })
    }

    /// Chain this LockKp with another regular Kp
    ///
    /// This allows you to continue navigating after getting through the lock:
    /// Root -> Lock -> Mid -> Value1 -> Value2
    ///
    /// # Cloning Behavior
    /// No cloning occurs in this method - closures are moved into the new Kp
    pub fn then<V2, Value2, MutValue2, G3, S3>(
        self,
        next_kp: Kp<V, V2, Value, Value2, MutValue, MutValue2, G3, S3>,
    ) -> LockKp<
        R,
        Lock,
        Mid,
        V2,
        Root,
        LockValue,
        MidValue,
        Value2,
        MutRoot,
        MutLock,
        MutMid,
        MutValue2,
        G1,
        S1,
        L,
        impl Fn(MidValue) -> Option<Value2>,
        impl Fn(MutMid) -> Option<MutValue2>,
    >
    where
        V: 'static,
        V2: 'static,
        Value: std::borrow::Borrow<V>,
        Value2: std::borrow::Borrow<V2>,
        MutValue: std::borrow::BorrowMut<V>,
        MutValue2: std::borrow::BorrowMut<V2>,
        G3: Fn(Value) -> Option<Value2> + 'static,
        S3: Fn(MutValue) -> Option<MutValue2> + 'static,
    {
        // Extract closures (move, no clone)
        let next_get = self.next.get;
        let next_set = self.next.set;

        // Create chained keypath by composing closures (no cloning)
        let chained_kp = Kp::new(
            move |mid_value: MidValue| next_get(mid_value).and_then(|v| (next_kp.get)(v)),
            move |mid_value: MutMid| next_set(mid_value).and_then(|v| (next_kp.set)(v)),
        );

        LockKp::new(self.prev, self.mid, chained_kp)
    }

    /// Chain with another LockKp for multi-level lock access (then_lock convention)
    ///
    /// This allows you to chain through multiple lock levels:
    /// Root -> Lock1 -> Mid1 -> Lock2 -> Mid2 -> Value
    ///
    /// # Cloning Behavior - ALL CLONES ARE SHALLOW
    ///
    /// This method requires two types of cloning, both SHALLOW:
    ///
    /// 1. **`L2: Clone`** (line 261): Clones the lock accessor trait object
    ///    - For `ArcMutexAccess<T>`: Only clones `PhantomData` (zero-cost)
    ///    - No data is cloned, just the lock access behavior
    ///
    /// 2. **`Lock2: Clone`** (line 287): Clones the lock container
    ///    - For `Arc<Mutex<T>>`: Only increments Arc reference count
    ///    - The actual data `T` inside the Mutex is NOT cloned
    ///    - This is necessary to satisfy borrow checker in closure context
    ///
    /// **Performance**: Both clones are O(1) operations with no deep data copying
    ///
    /// # Example
    /// ```
    /// // Root -> Arc<Mutex<Mid1>> -> Mid1 -> Arc<Mutex<Mid2>> -> Mid2 -> String
    /// let lock_kp1 = LockKp::new(root_to_lock1, ArcMutexAccess::new(), lock1_to_mid1);
    /// let lock_kp2 = LockKp::new(mid1_to_lock2, ArcMutexAccess::new(), mid2_to_value);
    ///
    /// let chained = lock_kp1.then_lock(lock_kp2);
    /// ```
    pub fn then_lock<
        Lock2,
        Mid2,
        V2,
        LockValue2,
        MidValue2,
        Value2,
        MutLock2,
        MutMid2,
        MutValue2,
        G2_1,
        S2_1,
        L2,
        G2_2,
        S2_2,
    >(
        self,
        other: LockKp<
            V,
            Lock2,
            Mid2,
            V2,
            Value,
            LockValue2,
            MidValue2,
            Value2,
            MutValue,
            MutLock2,
            MutMid2,
            MutValue2,
            G2_1,
            S2_1,
            L2,
            G2_2,
            S2_2,
        >,
    ) -> LockKp<
        R,
        Lock,
        Mid,
        V2,
        Root,
        LockValue,
        MidValue,
        Value2,
        MutRoot,
        MutLock,
        MutMid,
        MutValue2,
        G1,
        S1,
        L,
        impl Fn(MidValue) -> Option<Value2>,
        impl Fn(MutMid) -> Option<MutValue2>,
    >
    where
        V: 'static + Clone,
        V2: 'static,
        Lock2: Clone, // SHALLOW: For Arc<Mutex<T>>, only increments refcount
        Value: std::borrow::Borrow<V>,
        LockValue2: std::borrow::Borrow<Lock2>,
        MidValue2: std::borrow::Borrow<Mid2>,
        Value2: std::borrow::Borrow<V2>,
        MutValue: std::borrow::BorrowMut<V>,
        MutLock2: std::borrow::BorrowMut<Lock2>,
        MutMid2: std::borrow::BorrowMut<Mid2>,
        MutValue2: std::borrow::BorrowMut<V2>,
        G2_1: Fn(Value) -> Option<LockValue2> + 'static,
        S2_1: Fn(MutValue) -> Option<MutLock2> + 'static,
        L2: LockAccess<Lock2, MidValue2> + LockAccess<Lock2, MutMid2> + Clone + 'static, // SHALLOW: PhantomData clone
        G2_2: Fn(MidValue2) -> Option<Value2> + 'static,
        S2_2: Fn(MutMid2) -> Option<MutValue2> + 'static,
    {
        // Extract closures from self (move, no clone)
        let next_get = self.next.get;
        let next_set = self.next.set;

        // Extract closures from other (move, no clone)
        let other_prev_get = other.prev.get;
        let other_prev_set = other.prev.set;

        // SHALLOW CLONE: Clone the lock accessor (typically just PhantomData)
        // For ArcMutexAccess<T>, this is a zero-cost clone of PhantomData
        let other_mid1 = other.mid.clone();
        let other_mid2 = other.mid;

        let other_next_get = other.next.get;
        let other_next_set = other.next.set;

        // Create a composed keypath: Mid -> Lock2 -> Mid2 -> Value2
        let composed_kp = Kp::new(
            move |mid_value: MidValue| {
                // First, navigate from Mid to V using self.next
                next_get(mid_value).and_then(|value1| {
                    // Then navigate from V to Lock2 using other.prev
                    other_prev_get(value1).and_then(|lock2_value| {
                        let lock2: &Lock2 = lock2_value.borrow();
                        // Lock and get Mid2 using other.mid (no clone here)
                        other_mid1.lock_read(lock2).and_then(|mid2_value| {
                            // Finally navigate from Mid2 to Value2 using other.next
                            other_next_get(mid2_value)
                        })
                    })
                })
            },
            move |mid_value: MutMid| {
                // Same flow but for mutable access
                next_set(mid_value).and_then(|value1| {
                    other_prev_set(value1).and_then(|mut lock2_value| {
                        let lock2: &mut Lock2 = lock2_value.borrow_mut();

                        // SHALLOW CLONE: For Arc<Mutex<T>>, only increments Arc refcount
                        // The actual data T inside Mutex is NOT cloned
                        // This is required to satisfy Rust's borrow checker in closure context
                        let mut lock2_clone = lock2.clone();

                        other_mid2
                            .lock_write(&mut lock2_clone)
                            .and_then(|mid2_value| other_next_set(mid2_value))
                    })
                })
            },
        );

        LockKp::new(self.prev, self.mid, composed_kp)
    }

    /// Chain with an async keypath. Use `.get(&root).await` on the returned keypath.
    /// When `AsyncKp::Value` is a reference type (`&T` / `&mut T`), `V2` is inferred as `T` via [crate::KeyPathValueTarget].
    pub fn then_async<AsyncKp>(
        self,
        async_kp: AsyncKp,
    ) -> crate::async_lock::KpThenAsyncKeyPath<
        R,
        V,
        <AsyncKp::Value as crate::KeyPathValueTarget>::Target,
        Root,
        Value,
        AsyncKp::Value,
        MutRoot,
        MutValue,
        AsyncKp::MutValue,
        Self,
        AsyncKp,
    >
    where
        V: 'static + Clone,
        Value: std::borrow::Borrow<V>,
        MutValue: std::borrow::BorrowMut<V>,
        AsyncKp: crate::async_lock::AsyncKeyPathLike<Value, MutValue>,
        AsyncKp::Value: crate::KeyPathValueTarget
            + std::borrow::Borrow<<AsyncKp::Value as crate::KeyPathValueTarget>::Target>,
        AsyncKp::MutValue: std::borrow::BorrowMut<<AsyncKp::Value as crate::KeyPathValueTarget>::Target>,
        <AsyncKp::Value as crate::KeyPathValueTarget>::Target: 'static,
    {
        crate::async_lock::KpThenAsyncKeyPath {
            first: self,
            second: async_kp,
            _p: std::marker::PhantomData,
        }
    }
}

// ============================================================================
// KpThenLockKp: Kp .then_lock(LockKp) — sync keypath then sync lock
// ============================================================================

/// Keypath that chains a [crate::Kp] with a [LockKp]. Use [crate::Kp::then_lock] to create.
#[derive(Clone)]
pub struct KpThenLockKp<R, V, V2, Root, Value, Value2, MutRoot, MutValue, MutValue2, First, Second> {
    pub(crate) first: First,
    pub(crate) second: Second,
    pub(crate) _p: std::marker::PhantomData<(R, V, V2, Root, Value, Value2, MutRoot, MutValue, MutValue2)>,
}

impl<R, V, V2, Root, Value, Value2, MutRoot, MutValue, MutValue2, First, Second>
    KpThenLockKp<R, V, V2, Root, Value, Value2, MutRoot, MutValue, MutValue2, First, Second>
where
    First: crate::async_lock::SyncKeyPathLike<Root, Value, MutRoot, MutValue>,
    Second: crate::async_lock::SyncKeyPathLike<Value, Value2, MutValue, MutValue2>,
{
    /// Get through first keypath then second (sync).
    #[inline]
    pub fn get(&self, root: Root) -> Option<Value2>
    where
        Value2: Clone,
    {
        let v = self.first.sync_get(root)?;
        self.second.sync_get(v)
    }
    /// Get mutable through first then second (sync).
    #[inline]
    pub fn get_mut(&self, root: MutRoot) -> Option<MutValue2> {
        let mut_v = self.first.sync_get_mut(root)?;
        self.second.sync_get_mut(mut_v)
    }
}

// ============================================================================
// Standard Lock Access Implementations
// ============================================================================

/// Lock access implementation for Arc<Mutex<T>>
///
/// # Cloning Behavior
///
/// This struct only contains `PhantomData<T>`, which is a zero-sized type.
/// Cloning `ArcMutexAccess<T>` is a **zero-cost operation** - no data is copied.
///
/// The `Clone` impl is required for the `then_lock()` method to work, but it's
/// completely free (compiled away to nothing).
#[derive(Clone)] // ZERO-COST: Only clones PhantomData (zero-sized type)
pub struct ArcMutexAccess<T> {
    _phantom: std::marker::PhantomData<T>, // Zero-sized, no runtime cost
}

impl<T> ArcMutexAccess<T> {
    pub fn new() -> Self {
        Self {
            _phantom: std::marker::PhantomData,
        }
    }
}

impl<T> Default for ArcMutexAccess<T> {
    fn default() -> Self {
        Self::new()
    }
}

// Implementation for immutable access (returns reference to locked value)
impl<'a, T: 'static> LockAccess<Arc<Mutex<T>>, &'a T> for ArcMutexAccess<T> {
    #[inline]
    fn lock_read(&self, lock: &Arc<Mutex<T>>) -> Option<&'a T> {
        // Note: This is a simplified implementation
        // In practice, returning a reference from a MutexGuard is tricky
        // This works for the pattern but may need adjustment for real usage
        lock.lock().ok().map(|guard| {
            let ptr = &*guard as *const T;
            unsafe { &*ptr }
        })
    }

    #[inline]
    fn lock_write(&self, lock: &Arc<Mutex<T>>) -> Option<&'a T> {
        lock.lock().ok().map(|guard| {
            let ptr = &*guard as *const T;
            unsafe { &*ptr }
        })
    }
}

// Implementation for mutable access
impl<'a, T: 'static> LockAccess<Arc<Mutex<T>>, &'a mut T> for ArcMutexAccess<T> {
    #[inline]
    fn lock_read(&self, lock: &Arc<Mutex<T>>) -> Option<&'a mut T> {
        lock.lock().ok().map(|mut guard| {
            let ptr = &mut *guard as *mut T;
            unsafe { &mut *ptr }
        })
    }

    #[inline]
    fn lock_write(&self, lock: &Arc<Mutex<T>>) -> Option<&'a mut T> {
        lock.lock().ok().map(|mut guard| {
            let ptr = &mut *guard as *mut T;
            unsafe { &mut *ptr }
        })
    }
}

// ============================================================================
// RwLock Access Implementation
// ============================================================================

/// Lock access implementation for Arc<RwLock<T>>
///
/// # RwLock Semantics
///
/// `RwLock` provides reader-writer lock semantics:
/// - Multiple readers can access simultaneously (shared/immutable access)
/// - Only one writer can access at a time (exclusive/mutable access)
/// - Readers and writers are mutually exclusive
///
/// # Cloning Behavior
///
/// Like `ArcMutexAccess`, this struct only contains `PhantomData<T>`.
/// Cloning is a **zero-cost operation** - no data is copied.
///
/// # Performance vs Mutex
///
/// - **Better for read-heavy workloads**: Multiple concurrent readers
/// - **Slightly more overhead**: RwLock has more complex internal state
/// - **Use when**: Many readers, few writers
/// - **Avoid when**: Frequent writes or simple cases (use Mutex)
#[derive(Clone)] // ZERO-COST: Only clones PhantomData (zero-sized type)
pub struct ArcRwLockAccess<T> {
    _phantom: std::marker::PhantomData<T>, // Zero-sized, no runtime cost
}

impl<T> ArcRwLockAccess<T> {
    pub fn new() -> Self {
        Self {
            _phantom: std::marker::PhantomData,
        }
    }
}

impl<T> Default for ArcRwLockAccess<T> {
    fn default() -> Self {
        Self::new()
    }
}

// Implementation for immutable access (read lock)
impl<'a, T: 'static> LockAccess<Arc<std::sync::RwLock<T>>, &'a T> for ArcRwLockAccess<T> {
    fn lock_read(&self, lock: &Arc<std::sync::RwLock<T>>) -> Option<&'a T> {
        // Acquire read lock - allows multiple concurrent readers
        lock.read().ok().map(|guard| {
            let ptr = &*guard as *const T;
            unsafe { &*ptr }
        })
    }

    fn lock_write(&self, lock: &Arc<std::sync::RwLock<T>>) -> Option<&'a T> {
        // For immutable access, we still use read lock
        lock.read().ok().map(|guard| {
            let ptr = &*guard as *const T;
            unsafe { &*ptr }
        })
    }
}

// Implementation for mutable access (write lock)
impl<'a, T: 'static> LockAccess<Arc<std::sync::RwLock<T>>, &'a mut T> for ArcRwLockAccess<T> {
    fn lock_read(&self, lock: &Arc<std::sync::RwLock<T>>) -> Option<&'a mut T> {
        // For mutable access, we need write lock (exclusive)
        lock.write().ok().map(|mut guard| {
            let ptr = &mut *guard as *mut T;
            unsafe { &mut *ptr }
        })
    }

    fn lock_write(&self, lock: &Arc<std::sync::RwLock<T>>) -> Option<&'a mut T> {
        // Acquire write lock - exclusive access
        lock.write().ok().map(|mut guard| {
            let ptr = &mut *guard as *mut T;
            unsafe { &mut *ptr }
        })
    }
}

// ============================================================================
// Direct Mutex Access Implementation (without Arc)
// ============================================================================

/// Lock access implementation for std::sync::Mutex<T> (without Arc wrapper)
///
/// # When to Use
///
/// Use this when you have a direct reference to a Mutex, not wrapped in Arc.
/// Common scenarios:
/// - Mutex is owned by a struct
/// - Single-threaded or thread-local usage
/// - When the Mutex lifetime is managed by other means
///
/// # Note
///
/// Since we're working with `&Mutex<T>`, this requires the Mutex to be
/// stored somewhere with a stable address (e.g., in a struct, Box, or static).
#[derive(Clone)]
pub struct StdMutexAccess<T> {
    _phantom: std::marker::PhantomData<T>,
}

impl<T> StdMutexAccess<T> {
    pub fn new() -> Self {
        Self {
            _phantom: std::marker::PhantomData,
        }
    }
}

impl<T> Default for StdMutexAccess<T> {
    fn default() -> Self {
        Self::new()
    }
}

// Implementation for immutable access
impl<'a, T: 'static> LockAccess<Mutex<T>, &'a T> for StdMutexAccess<T> {
    fn lock_read(&self, lock: &Mutex<T>) -> Option<&'a T> {
        lock.lock().ok().map(|guard| {
            let ptr = &*guard as *const T;
            unsafe { &*ptr }
        })
    }

    fn lock_write(&self, lock: &Mutex<T>) -> Option<&'a T> {
        lock.lock().ok().map(|guard| {
            let ptr = &*guard as *const T;
            unsafe { &*ptr }
        })
    }
}

// Implementation for mutable access
impl<'a, T: 'static> LockAccess<Mutex<T>, &'a mut T> for StdMutexAccess<T> {
    fn lock_read(&self, lock: &Mutex<T>) -> Option<&'a mut T> {
        lock.lock().ok().map(|mut guard| {
            let ptr = &mut *guard as *mut T;
            unsafe { &mut *ptr }
        })
    }

    fn lock_write(&self, lock: &Mutex<T>) -> Option<&'a mut T> {
        lock.lock().ok().map(|mut guard| {
            let ptr = &mut *guard as *mut T;
            unsafe { &mut *ptr }
        })
    }
}

// ============================================================================
// Direct RwLock Access Implementation (without Arc)
// ============================================================================

/// Lock access implementation for std::sync::RwLock<T> (without Arc wrapper)
///
/// # RwLock Semantics
///
/// - Multiple concurrent readers allowed
/// - Single exclusive writer
/// - Better for read-heavy workloads
///
/// # When to Use
///
/// Use this when you have a direct reference to an RwLock, not wrapped in Arc.
#[derive(Clone)]
pub struct StdRwLockAccess<T> {
    _phantom: std::marker::PhantomData<T>,
}

impl<T> StdRwLockAccess<T> {
    pub fn new() -> Self {
        Self {
            _phantom: std::marker::PhantomData,
        }
    }
}

impl<T> Default for StdRwLockAccess<T> {
    fn default() -> Self {
        Self::new()
    }
}

// Implementation for immutable access (read lock)
impl<'a, T: 'static> LockAccess<std::sync::RwLock<T>, &'a T> for StdRwLockAccess<T> {
    fn lock_read(&self, lock: &std::sync::RwLock<T>) -> Option<&'a T> {
        lock.read().ok().map(|guard| {
            let ptr = &*guard as *const T;
            unsafe { &*ptr }
        })
    }

    fn lock_write(&self, lock: &std::sync::RwLock<T>) -> Option<&'a T> {
        lock.read().ok().map(|guard| {
            let ptr = &*guard as *const T;
            unsafe { &*ptr }
        })
    }
}

// Implementation for mutable access (write lock)
impl<'a, T: 'static> LockAccess<std::sync::RwLock<T>, &'a mut T> for StdRwLockAccess<T> {
    fn lock_read(&self, lock: &std::sync::RwLock<T>) -> Option<&'a mut T> {
        lock.write().ok().map(|mut guard| {
            let ptr = &mut *guard as *mut T;
            unsafe { &mut *ptr }
        })
    }

    fn lock_write(&self, lock: &std::sync::RwLock<T>) -> Option<&'a mut T> {
        lock.write().ok().map(|mut guard| {
            let ptr = &mut *guard as *mut T;
            unsafe { &mut *ptr }
        })
    }
}

// ============================================================================
// Parking Lot Mutex Access Implementation
// ============================================================================
// cargo test --lib --features "tokio,parking_lot" 2>&1 | grep -E "(test result|running)" | tail -5
#[cfg(feature = "parking_lot")]
/// Lock access implementation for Arc<parking_lot::Mutex<T>>
///
/// # Parking Lot Mutex
///
/// `parking_lot::Mutex` is a faster, more compact alternative to `std::sync::Mutex`:
/// - **Smaller**: Only 1 byte of overhead vs std's platform-dependent size
/// - **Faster**: More efficient locking algorithm
/// - **No poisoning**: Unlike std::Mutex, doesn't panic on poisoned state
/// - **Fair**: Implements a fair locking algorithm (FIFO)
///
/// # Cloning Behavior
///
/// This struct only contains `PhantomData<T>`.
/// Cloning is a **zero-cost operation** - no data is copied.
///
/// # Performance
///
/// - **~2-3x faster** than std::Mutex in many scenarios
/// - Better for high-contention workloads
/// - More predictable latency due to fair scheduling
///
/// # When to Use
///
/// - High-contention scenarios where performance matters
/// - When you want fair lock acquisition (no writer starvation)
/// - When you don't need lock poisoning semantics
#[derive(Clone)] // ZERO-COST: Only clones PhantomData (zero-sized type)
pub struct ParkingLotMutexAccess<T> {
    _phantom: std::marker::PhantomData<T>,
}

#[cfg(feature = "parking_lot")]
impl<T> ParkingLotMutexAccess<T> {
    pub fn new() -> Self {
        Self {
            _phantom: std::marker::PhantomData,
        }
    }
}

#[cfg(feature = "parking_lot")]
impl<T> Default for ParkingLotMutexAccess<T> {
    fn default() -> Self {
        Self::new()
    }
}

// Implementation for immutable access
#[cfg(feature = "parking_lot")]
impl<'a, T: 'static> LockAccess<Arc<parking_lot::Mutex<T>>, &'a T> for ParkingLotMutexAccess<T> {
    fn lock_read(&self, lock: &Arc<parking_lot::Mutex<T>>) -> Option<&'a T> {
        let guard = lock.lock();
        let ptr = &*guard as *const T;
        unsafe { Some(&*ptr) }
    }

    fn lock_write(&self, lock: &Arc<parking_lot::Mutex<T>>) -> Option<&'a T> {
        let guard = lock.lock();
        let ptr = &*guard as *const T;
        unsafe { Some(&*ptr) }
    }
}

// Implementation for mutable access
#[cfg(feature = "parking_lot")]
impl<'a, T: 'static> LockAccess<Arc<parking_lot::Mutex<T>>, &'a mut T>
    for ParkingLotMutexAccess<T>
{
    fn lock_read(&self, lock: &Arc<parking_lot::Mutex<T>>) -> Option<&'a mut T> {
        let mut guard = lock.lock();
        let ptr = &mut *guard as *mut T;
        unsafe { Some(&mut *ptr) }
    }

    fn lock_write(&self, lock: &Arc<parking_lot::Mutex<T>>) -> Option<&'a mut T> {
        let mut guard = lock.lock();
        let ptr = &mut *guard as *mut T;
        unsafe { Some(&mut *ptr) }
    }
}

// ============================================================================
// Parking Lot RwLock Access Implementation
// ============================================================================

#[cfg(feature = "parking_lot")]
/// Lock access implementation for Arc<parking_lot::RwLock<T>>
///
/// # Parking Lot RwLock
///
/// `parking_lot::RwLock` is a faster alternative to `std::sync::RwLock`:
/// - **Smaller**: More compact memory representation
/// - **Faster**: More efficient locking and unlocking
/// - **No poisoning**: Unlike std::RwLock, doesn't panic on poisoned state
/// - **Writer-preferring**: Writers have priority to prevent writer starvation
/// - **Deadlock detection**: Optional deadlock detection in debug builds
///
/// # Cloning Behavior
///
/// This struct only contains `PhantomData<T>`.
/// Cloning is a **zero-cost operation** - no data is copied.
///
/// # Performance
///
/// - **Significantly faster** than std::RwLock for both read and write operations
/// - Better scalability with many readers
/// - Lower overhead per operation
///
/// # Writer Preference
///
/// Unlike std::RwLock which can starve writers, parking_lot's RwLock:
/// - Gives priority to writers when readers are present
/// - Prevents writer starvation in read-heavy workloads
/// - Still allows multiple concurrent readers when no writers are waiting
///
/// # When to Use
///
/// - Read-heavy workloads with occasional writes
/// - High-performance requirements
/// - When you need predictable writer scheduling
/// - When you don't need lock poisoning semantics
#[derive(Clone)] // ZERO-COST: Only clones PhantomData (zero-sized type)
pub struct ParkingLotRwLockAccess<T> {
    _phantom: std::marker::PhantomData<T>,
}

#[cfg(feature = "parking_lot")]
impl<T> ParkingLotRwLockAccess<T> {
    pub fn new() -> Self {
        Self {
            _phantom: std::marker::PhantomData,
        }
    }
}

#[cfg(feature = "parking_lot")]
impl<T> Default for ParkingLotRwLockAccess<T> {
    fn default() -> Self {
        Self::new()
    }
}

// Implementation for immutable access (read lock)
#[cfg(feature = "parking_lot")]
impl<'a, T: 'static> LockAccess<Arc<parking_lot::RwLock<T>>, &'a T> for ParkingLotRwLockAccess<T> {
    fn lock_read(&self, lock: &Arc<parking_lot::RwLock<T>>) -> Option<&'a T> {
        let guard = lock.read();
        let ptr = &*guard as *const T;
        unsafe { Some(&*ptr) }
    }

    fn lock_write(&self, lock: &Arc<parking_lot::RwLock<T>>) -> Option<&'a T> {
        // For immutable access, use read lock
        let guard = lock.read();
        let ptr = &*guard as *const T;
        unsafe { Some(&*ptr) }
    }
}

// Implementation for mutable access (write lock)
#[cfg(feature = "parking_lot")]
impl<'a, T: 'static> LockAccess<Arc<parking_lot::RwLock<T>>, &'a mut T>
    for ParkingLotRwLockAccess<T>
{
    fn lock_read(&self, lock: &Arc<parking_lot::RwLock<T>>) -> Option<&'a mut T> {
        // For mutable access, use write lock
        let mut guard = lock.write();
        let ptr = &mut *guard as *mut T;
        unsafe { Some(&mut *ptr) }
    }

    fn lock_write(&self, lock: &Arc<parking_lot::RwLock<T>>) -> Option<&'a mut T> {
        let mut guard = lock.write();
        let ptr = &mut *guard as *mut T;
        unsafe { Some(&mut *ptr) }
    }
}

// ============================================================================
// Direct Parking Lot Mutex Access Implementation (without Arc)
// ============================================================================

#[cfg(feature = "parking_lot")]
/// Lock access implementation for parking_lot::Mutex<T> (without Arc wrapper)
///
/// # Parking Lot Advantages
///
/// - Faster and more compact than std::sync::Mutex
/// - No lock poisoning
/// - Fair scheduling (FIFO)
///
/// # When to Use
///
/// Use this when you have a direct reference to a parking_lot::Mutex,
/// not wrapped in Arc.
#[derive(Clone)]
pub struct DirectParkingLotMutexAccess<T> {
    _phantom: std::marker::PhantomData<T>,
}

#[cfg(feature = "parking_lot")]
impl<T> DirectParkingLotMutexAccess<T> {
    pub fn new() -> Self {
        Self {
            _phantom: std::marker::PhantomData,
        }
    }
}

#[cfg(feature = "parking_lot")]
impl<T> Default for DirectParkingLotMutexAccess<T> {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(feature = "parking_lot")]
impl<'a, T: 'static> LockAccess<parking_lot::Mutex<T>, &'a T> for DirectParkingLotMutexAccess<T> {
    fn lock_read(&self, lock: &parking_lot::Mutex<T>) -> Option<&'a T> {
        let guard = lock.lock();
        let ptr = &*guard as *const T;
        unsafe { Some(&*ptr) }
    }

    fn lock_write(&self, lock: &parking_lot::Mutex<T>) -> Option<&'a T> {
        let guard = lock.lock();
        let ptr = &*guard as *const T;
        unsafe { Some(&*ptr) }
    }
}

#[cfg(feature = "parking_lot")]
impl<'a, T: 'static> LockAccess<parking_lot::Mutex<T>, &'a mut T>
    for DirectParkingLotMutexAccess<T>
{
    fn lock_read(&self, lock: &parking_lot::Mutex<T>) -> Option<&'a mut T> {
        let mut guard = lock.lock();
        let ptr = &mut *guard as *mut T;
        unsafe { Some(&mut *ptr) }
    }

    fn lock_write(&self, lock: &parking_lot::Mutex<T>) -> Option<&'a mut T> {
        let mut guard = lock.lock();
        let ptr = &mut *guard as *mut T;
        unsafe { Some(&mut *ptr) }
    }
}

// ============================================================================
// Direct Parking Lot RwLock Access Implementation (without Arc)
// ============================================================================

#[cfg(feature = "parking_lot")]
/// Lock access implementation for parking_lot::RwLock<T> (without Arc wrapper)
///
/// # Parking Lot RwLock Advantages
///
/// - Faster than std::sync::RwLock
/// - More compact memory footprint
/// - Fair scheduling
/// - Better for read-heavy workloads
///
/// # When to Use
///
/// Use this when you have a direct reference to a parking_lot::RwLock,
/// not wrapped in Arc.
#[derive(Clone)]
pub struct DirectParkingLotRwLockAccess<T> {
    _phantom: std::marker::PhantomData<T>,
}

#[cfg(feature = "parking_lot")]
impl<T> DirectParkingLotRwLockAccess<T> {
    pub fn new() -> Self {
        Self {
            _phantom: std::marker::PhantomData,
        }
    }
}

#[cfg(feature = "parking_lot")]
impl<T> Default for DirectParkingLotRwLockAccess<T> {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(feature = "parking_lot")]
impl<'a, T: 'static> LockAccess<parking_lot::RwLock<T>, &'a T> for DirectParkingLotRwLockAccess<T> {
    fn lock_read(&self, lock: &parking_lot::RwLock<T>) -> Option<&'a T> {
        let guard = lock.read();
        let ptr = &*guard as *const T;
        unsafe { Some(&*ptr) }
    }

    fn lock_write(&self, lock: &parking_lot::RwLock<T>) -> Option<&'a T> {
        let guard = lock.read();
        let ptr = &*guard as *const T;
        unsafe { Some(&*ptr) }
    }
}

#[cfg(feature = "parking_lot")]
impl<'a, T: 'static> LockAccess<parking_lot::RwLock<T>, &'a mut T>
    for DirectParkingLotRwLockAccess<T>
{
    fn lock_read(&self, lock: &parking_lot::RwLock<T>) -> Option<&'a mut T> {
        let mut guard = lock.write();
        let ptr = &mut *guard as *mut T;
        unsafe { Some(&mut *ptr) }
    }

    fn lock_write(&self, lock: &parking_lot::RwLock<T>) -> Option<&'a mut T> {
        let mut guard = lock.write();
        let ptr = &mut *guard as *mut T;
        unsafe { Some(&mut *ptr) }
    }
}

// ============================================================================
// RefCell Access Implementation (Single-threaded)
// ============================================================================

/// Lock access implementation for Rc<RefCell<T>>
///
/// # RefCell Semantics
///
/// `RefCell<T>` provides interior mutability with runtime borrow checking:
/// - Multiple immutable borrows are allowed simultaneously
/// - Only one mutable borrow is allowed at a time
/// - Borrows are checked at runtime (will panic if violated)
/// - **NOT thread-safe** - use only in single-threaded contexts
///
/// # Cloning Behavior
///
/// Like `ArcMutexAccess` and `ArcRwLockAccess`, this struct only contains `PhantomData<T>`.
/// Cloning is a **zero-cost operation** - no data is copied.
///
/// # Rc vs Arc
///
/// - **`Rc<RefCell<T>>`**: Single-threaded, lower overhead, no atomic operations
/// - **`Arc<Mutex<T>>`**: Multi-threaded, thread-safe, atomic reference counting
///
/// Use `RcRefCellAccess` when:
/// - Working in single-threaded context
/// - Want lower overhead than Arc/Mutex
/// - Don't need thread safety
///
/// # Example
///
/// ```rust
/// use std::rc::Rc;
/// use std::cell::RefCell;
///
/// #[derive(Clone)]
/// struct Root {
///     data: Rc<RefCell<Inner>>,
/// }
///
/// struct Inner {
///     value: String,
/// }
///
/// let lock_kp = LockKp::new(
///     Kp::new(|r: &Root| Some(&r.data), |r: &mut Root| Some(&mut r.data)),
///     RcRefCellAccess::new(),
///     Kp::new(|i: &Inner| Some(&i.value), |i: &mut Inner| Some(&mut i.value)),
/// );
/// ```
#[derive(Clone)] // ZERO-COST: Only clones PhantomData (zero-sized type)
pub struct RcRefCellAccess<T> {
    _phantom: std::marker::PhantomData<T>, // Zero-sized, no runtime cost
}

impl<T> RcRefCellAccess<T> {
    pub fn new() -> Self {
        Self {
            _phantom: std::marker::PhantomData,
        }
    }
}

impl<T> Default for RcRefCellAccess<T> {
    fn default() -> Self {
        Self::new()
    }
}

// Implementation for immutable access (borrow)
impl<'a, T: 'static> LockAccess<std::rc::Rc<std::cell::RefCell<T>>, &'a T> for RcRefCellAccess<T> {
    fn lock_read(&self, lock: &std::rc::Rc<std::cell::RefCell<T>>) -> Option<&'a T> {
        // Acquire immutable borrow - allows multiple concurrent readers
        // SHALLOW CLONE: Only Rc refcount is incremented when accessing lock
        // Note: borrow() panics on borrow violation (not thread-safe, runtime check)
        let guard = lock.borrow();
        let ptr = &*guard as *const T;
        unsafe { Some(&*ptr) }
    }

    fn lock_write(&self, lock: &std::rc::Rc<std::cell::RefCell<T>>) -> Option<&'a T> {
        // For immutable access, we use borrow (not borrow_mut)
        let guard = lock.borrow();
        let ptr = &*guard as *const T;
        unsafe { Some(&*ptr) }
    }
}

// Implementation for mutable access (borrow_mut)
impl<'a, T: 'static> LockAccess<std::rc::Rc<std::cell::RefCell<T>>, &'a mut T>
    for RcRefCellAccess<T>
{
    fn lock_read(&self, lock: &std::rc::Rc<std::cell::RefCell<T>>) -> Option<&'a mut T> {
        // For mutable access, we need exclusive borrow
        // Note: borrow_mut() panics on borrow violation (not thread-safe, runtime check)
        let mut guard = lock.borrow_mut();
        let ptr = &mut *guard as *mut T;
        unsafe { Some(&mut *ptr) }
    }

    fn lock_write(&self, lock: &std::rc::Rc<std::cell::RefCell<T>>) -> Option<&'a mut T> {
        // Acquire mutable borrow - exclusive access
        let mut guard = lock.borrow_mut();
        let ptr = &mut *guard as *mut T;
        unsafe { Some(&mut *ptr) }
    }
}

// ============================================================================
// Helper Functions
// ============================================================================

/// Type alias for common LockKp usage with Arc<Mutex<T>>
pub type LockKpType<'a, R, Mid, V> = LockKp<
    R,
    Arc<Mutex<Mid>>,
    Mid,
    V,
    &'a R,
    &'a Arc<Mutex<Mid>>,
    &'a Mid,
    &'a V,
    &'a mut R,
    &'a mut Arc<Mutex<Mid>>,
    &'a mut Mid,
    &'a mut V,
    for<'b> fn(&'b R) -> Option<&'b Arc<Mutex<Mid>>>,
    for<'b> fn(&'b mut R) -> Option<&'b mut Arc<Mutex<Mid>>>,
    ArcMutexAccess<Mid>,
    for<'b> fn(&'b Mid) -> Option<&'b V>,
    for<'b> fn(&'b mut Mid) -> Option<&'b mut V>,
>;

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

    #[test]
    fn test_lock_kp_basic() {
        #[derive(Debug, Clone)]
        struct Root {
            locked_data: Arc<Mutex<Inner>>,
        }

        #[derive(Debug, Clone)]
        struct Inner {
            value: String,
        }

        let root = Root {
            locked_data: Arc::new(Mutex::new(Inner {
                value: "hello".to_string(),
            })),
        };

        // Create prev keypath (Root -> Arc<Mutex<Inner>>)
        let prev_kp: KpType<Root, Arc<Mutex<Inner>>> = Kp::new(
            |r: &Root| Some(&r.locked_data),
            |r: &mut Root| Some(&mut r.locked_data),
        );

        // Create next keypath (Inner -> String)
        let next_kp: KpType<Inner, String> = Kp::new(
            |i: &Inner| Some(&i.value),
            |i: &mut Inner| Some(&mut i.value),
        );

        // Create lock keypath
        let lock_kp = LockKp::new(prev_kp, ArcMutexAccess::new(), next_kp);

        // Test get
        let value = lock_kp.get(&root);
        assert!(value.is_some());
        // Note: Direct comparison may not work due to lifetime issues in this simple test
    }

    #[test]
    fn test_lock_kp_structure() {
        // This test verifies that the structure has the three required fields
        #[derive(Debug, Clone)]
        struct Root {
            data: Arc<Mutex<Mid>>,
        }

        #[derive(Debug, Clone)]
        struct Mid {
            value: i32,
        }

        let prev: KpType<Root, Arc<Mutex<Mid>>> =
            Kp::new(|r: &Root| Some(&r.data), |r: &mut Root| Some(&mut r.data));

        let mid = ArcMutexAccess::<Mid>::new();

        let next: KpType<Mid, i32> =
            Kp::new(|m: &Mid| Some(&m.value), |m: &mut Mid| Some(&mut m.value));

        let lock_kp = LockKp::new(prev, mid, next);

        // Verify the fields exist and are accessible
        let _prev_field = &lock_kp.prev;
        let _mid_field = &lock_kp.mid;
        let _next_field = &lock_kp.next;
    }

    #[test]
    fn test_lock_kp_then_chaining() {
        #[derive(Debug, Clone)]
        struct Root {
            data: Arc<Mutex<Mid>>,
        }

        #[derive(Debug, Clone)]
        struct Mid {
            inner: Inner2,
        }

        #[derive(Debug, Clone)]
        struct Inner2 {
            value: String,
        }

        let root = Root {
            data: Arc::new(Mutex::new(Mid {
                inner: Inner2 {
                    value: "chained".to_string(),
                },
            })),
        };

        // Root -> Arc<Mutex<Mid>>
        let prev: KpType<Root, Arc<Mutex<Mid>>> =
            Kp::new(|r: &Root| Some(&r.data), |r: &mut Root| Some(&mut r.data));

        // Mid -> Inner2
        let to_inner: KpType<Mid, Inner2> =
            Kp::new(|m: &Mid| Some(&m.inner), |m: &mut Mid| Some(&mut m.inner));

        // Inner2 -> String
        let to_value: KpType<Inner2, String> = Kp::new(
            |i: &Inner2| Some(&i.value),
            |i: &mut Inner2| Some(&mut i.value),
        );

        // Create initial lock keypath: Root -> Lock -> Mid -> Inner2
        let lock_kp = LockKp::new(prev, ArcMutexAccess::new(), to_inner);

        // Chain with another keypath: Inner2 -> String
        let chained = lock_kp.then(to_value);

        // The chained keypath should work
        // Note: Full functional test may require more complex setup due to lifetimes
        let _result = chained;
    }

    #[test]
    fn test_lock_kp_compose_single_level() {
        // Test composing two single-level LockKps
        #[derive(Debug, Clone)]
        struct Root {
            data: Arc<Mutex<Mid1>>,
        }

        #[derive(Debug, Clone)]
        struct Mid1 {
            nested: Arc<Mutex<Mid2>>,
        }

        #[derive(Debug, Clone)]
        struct Mid2 {
            value: String,
        }

        let root = Root {
            data: Arc::new(Mutex::new(Mid1 {
                nested: Arc::new(Mutex::new(Mid2 {
                    value: "nested-lock".to_string(),
                })),
            })),
        };

        // First LockKp: Root -> Arc<Mutex<Mid1>> -> Mid1
        let lock_kp1 = {
            let prev: KpType<Root, Arc<Mutex<Mid1>>> =
                Kp::new(|r: &Root| Some(&r.data), |r: &mut Root| Some(&mut r.data));
            let next: KpType<Mid1, Mid1> = Kp::new(|m: &Mid1| Some(m), |m: &mut Mid1| Some(m));
            LockKp::new(prev, ArcMutexAccess::new(), next)
        };

        // Second LockKp: Mid1 -> Arc<Mutex<Mid2>> -> String
        let lock_kp2 = {
            let prev: KpType<Mid1, Arc<Mutex<Mid2>>> = Kp::new(
                |m: &Mid1| Some(&m.nested),
                |m: &mut Mid1| Some(&mut m.nested),
            );
            let next: KpType<Mid2, String> =
                Kp::new(|m: &Mid2| Some(&m.value), |m: &mut Mid2| Some(&mut m.value));
            LockKp::new(prev, ArcMutexAccess::new(), next)
        };

        // Compose them: Root -> Lock1 -> Mid1 -> Lock2 -> Mid2 -> String
        let composed = lock_kp1.then_lock(lock_kp2);

        // Verify composition works
        let value = composed.get(&root);
        assert!(value.is_some());
    }

    #[test]
    fn test_lock_kp_compose_two_levels() {
        // Test composing at two lock levels
        #[derive(Debug, Clone)]
        struct Root {
            level1: Arc<Mutex<Level1>>,
        }

        #[derive(Debug, Clone)]
        struct Level1 {
            data: String,
            level2: Arc<Mutex<Level2>>,
        }

        #[derive(Debug, Clone)]
        struct Level2 {
            value: i32,
        }

        let root = Root {
            level1: Arc::new(Mutex::new(Level1 {
                data: "level1".to_string(),
                level2: Arc::new(Mutex::new(Level2 { value: 42 })),
            })),
        };

        // First lock level
        let lock1 = {
            let prev: KpType<Root, Arc<Mutex<Level1>>> = Kp::new(
                |r: &Root| Some(&r.level1),
                |r: &mut Root| Some(&mut r.level1),
            );
            let next: KpType<Level1, Level1> =
                Kp::new(|l: &Level1| Some(l), |l: &mut Level1| Some(l));
            LockKp::new(prev, ArcMutexAccess::new(), next)
        };

        // Second lock level
        let lock2 = {
            let prev: KpType<Level1, Arc<Mutex<Level2>>> = Kp::new(
                |l: &Level1| Some(&l.level2),
                |l: &mut Level1| Some(&mut l.level2),
            );
            let next: KpType<Level2, i32> = Kp::new(
                |l: &Level2| Some(&l.value),
                |l: &mut Level2| Some(&mut l.value),
            );
            LockKp::new(prev, ArcMutexAccess::new(), next)
        };

        // Compose both locks
        let composed = lock1.then_lock(lock2);

        // Test get
        let value = composed.get(&root);
        assert!(value.is_some());
    }

    #[test]
    fn test_lock_kp_compose_three_levels() {
        // Test composing three lock levels
        #[derive(Debug, Clone)]
        struct Root {
            lock1: Arc<Mutex<L1>>,
        }

        #[derive(Debug, Clone)]
        struct L1 {
            lock2: Arc<Mutex<L2>>,
        }

        #[derive(Debug, Clone)]
        struct L2 {
            lock3: Arc<Mutex<L3>>,
        }

        #[derive(Debug, Clone)]
        struct L3 {
            final_value: String,
        }

        let root = Root {
            lock1: Arc::new(Mutex::new(L1 {
                lock2: Arc::new(Mutex::new(L2 {
                    lock3: Arc::new(Mutex::new(L3 {
                        final_value: "deeply-nested".to_string(),
                    })),
                })),
            })),
        };

        // Lock level 1: Root -> L1
        let lock_kp1 = {
            let prev: KpType<Root, Arc<Mutex<L1>>> =
                Kp::new(|r: &Root| Some(&r.lock1), |r: &mut Root| Some(&mut r.lock1));
            let next: KpType<L1, L1> = Kp::new(|l: &L1| Some(l), |l: &mut L1| Some(l));
            LockKp::new(prev, ArcMutexAccess::new(), next)
        };

        // Lock level 2: L1 -> L2
        let lock_kp2 = {
            let prev: KpType<L1, Arc<Mutex<L2>>> =
                Kp::new(|l: &L1| Some(&l.lock2), |l: &mut L1| Some(&mut l.lock2));
            let next: KpType<L2, L2> = Kp::new(|l: &L2| Some(l), |l: &mut L2| Some(l));
            LockKp::new(prev, ArcMutexAccess::new(), next)
        };

        // Lock level 3: L2 -> L3 -> String
        let lock_kp3 = {
            let prev: KpType<L2, Arc<Mutex<L3>>> =
                Kp::new(|l: &L2| Some(&l.lock3), |l: &mut L2| Some(&mut l.lock3));
            let next: KpType<L3, String> = Kp::new(
                |l: &L3| Some(&l.final_value),
                |l: &mut L3| Some(&mut l.final_value),
            );
            LockKp::new(prev, ArcMutexAccess::new(), next)
        };

        // Compose all three levels
        let composed_1_2 = lock_kp1.then_lock(lock_kp2);
        let composed_all = composed_1_2.then_lock(lock_kp3);

        // Test get through all three lock levels
        let value = composed_all.get(&root);
        assert!(value.is_some());
    }

    #[test]
    fn test_lock_kp_compose_with_then() {
        // Test combining compose and then
        #[derive(Debug, Clone)]
        struct Root {
            lock1: Arc<Mutex<Mid>>,
        }

        #[derive(Debug, Clone)]
        struct Mid {
            lock2: Arc<Mutex<Inner>>,
        }

        #[derive(Debug, Clone)]
        struct Inner {
            data: Data,
        }

        #[derive(Debug, Clone)]
        struct Data {
            value: i32,
        }

        let root = Root {
            lock1: Arc::new(Mutex::new(Mid {
                lock2: Arc::new(Mutex::new(Inner {
                    data: Data { value: 100 },
                })),
            })),
        };

        // First lock
        let lock1 = {
            let prev: KpType<Root, Arc<Mutex<Mid>>> =
                Kp::new(|r: &Root| Some(&r.lock1), |r: &mut Root| Some(&mut r.lock1));
            let next: KpType<Mid, Mid> = Kp::new(|m: &Mid| Some(m), |m: &mut Mid| Some(m));
            LockKp::new(prev, ArcMutexAccess::new(), next)
        };

        // Second lock
        let lock2 = {
            let prev: KpType<Mid, Arc<Mutex<Inner>>> =
                Kp::new(|m: &Mid| Some(&m.lock2), |m: &mut Mid| Some(&mut m.lock2));
            let next: KpType<Inner, Inner> = Kp::new(|i: &Inner| Some(i), |i: &mut Inner| Some(i));
            LockKp::new(prev, ArcMutexAccess::new(), next)
        };

        // Regular keypath after locks
        let to_data: KpType<Inner, Data> =
            Kp::new(|i: &Inner| Some(&i.data), |i: &mut Inner| Some(&mut i.data));

        let to_value: KpType<Data, i32> =
            Kp::new(|d: &Data| Some(&d.value), |d: &mut Data| Some(&mut d.value));

        // Compose locks, then chain with regular keypaths
        let composed = lock1.then_lock(lock2);
        let with_data = composed.then(to_data);
        let with_value = with_data.then(to_value);

        // Test get
        let value = with_value.get(&root);
        assert!(value.is_some());
    }

    // ============================================================================
    // RwLock Tests
    // ============================================================================

    #[test]
    fn test_rwlock_basic() {
        use std::sync::RwLock;

        #[derive(Debug, Clone)]
        struct Root {
            data: Arc<RwLock<Inner>>,
        }

        #[derive(Debug, Clone)]
        struct Inner {
            value: String,
        }

        let root = Root {
            data: Arc::new(RwLock::new(Inner {
                value: "rwlock_value".to_string(),
            })),
        };

        // Create RwLock keypath
        let prev: KpType<Root, Arc<RwLock<Inner>>> =
            Kp::new(|r: &Root| Some(&r.data), |r: &mut Root| Some(&mut r.data));

        let next: KpType<Inner, String> = Kp::new(
            |i: &Inner| Some(&i.value),
            |i: &mut Inner| Some(&mut i.value),
        );

        let rwlock_kp = LockKp::new(prev, ArcRwLockAccess::new(), next);

        // Test get (read lock)
        let value = rwlock_kp.get(&root);
        assert!(value.is_some());
    }

    #[test]
    fn test_rwlock_compose_two_levels() {
        use std::sync::RwLock;

        #[derive(Debug, Clone)]
        struct Root {
            level1: Arc<RwLock<Level1>>,
        }

        #[derive(Debug, Clone)]
        struct Level1 {
            level2: Arc<RwLock<Level2>>,
        }

        #[derive(Debug, Clone)]
        struct Level2 {
            value: i32,
        }

        let root = Root {
            level1: Arc::new(RwLock::new(Level1 {
                level2: Arc::new(RwLock::new(Level2 { value: 100 })),
            })),
        };

        // First RwLock level
        let lock1 = {
            let prev: KpType<Root, Arc<RwLock<Level1>>> = Kp::new(
                |r: &Root| Some(&r.level1),
                |r: &mut Root| Some(&mut r.level1),
            );
            let next: KpType<Level1, Level1> =
                Kp::new(|l: &Level1| Some(l), |l: &mut Level1| Some(l));
            LockKp::new(prev, ArcRwLockAccess::new(), next)
        };

        // Second RwLock level
        let lock2 = {
            let prev: KpType<Level1, Arc<RwLock<Level2>>> = Kp::new(
                |l: &Level1| Some(&l.level2),
                |l: &mut Level1| Some(&mut l.level2),
            );
            let next: KpType<Level2, i32> = Kp::new(
                |l: &Level2| Some(&l.value),
                |l: &mut Level2| Some(&mut l.value),
            );
            LockKp::new(prev, ArcRwLockAccess::new(), next)
        };

        // Compose both RwLocks
        let composed = lock1.then_lock(lock2);

        // Test get through both read locks
        let value = composed.get(&root);
        assert!(value.is_some());
    }

    #[test]
    fn test_rwlock_mixed_with_mutex() {
        use std::sync::RwLock;

        #[derive(Debug, Clone)]
        struct Root {
            rwlock_data: Arc<RwLock<Mid>>,
        }

        #[derive(Debug, Clone)]
        struct Mid {
            mutex_data: Arc<Mutex<Inner>>,
        }

        #[derive(Debug, Clone)]
        struct Inner {
            value: String,
        }

        let root = Root {
            rwlock_data: Arc::new(RwLock::new(Mid {
                mutex_data: Arc::new(Mutex::new(Inner {
                    value: "mixed".to_string(),
                })),
            })),
        };

        // RwLock level
        let rwlock_kp = {
            let prev: KpType<Root, Arc<RwLock<Mid>>> = Kp::new(
                |r: &Root| Some(&r.rwlock_data),
                |r: &mut Root| Some(&mut r.rwlock_data),
            );
            let next: KpType<Mid, Mid> = Kp::new(|m: &Mid| Some(m), |m: &mut Mid| Some(m));
            LockKp::new(prev, ArcRwLockAccess::new(), next)
        };

        // Mutex level
        let mutex_kp = {
            let prev: KpType<Mid, Arc<Mutex<Inner>>> = Kp::new(
                |m: &Mid| Some(&m.mutex_data),
                |m: &mut Mid| Some(&mut m.mutex_data),
            );
            let next: KpType<Inner, String> = Kp::new(
                |i: &Inner| Some(&i.value),
                |i: &mut Inner| Some(&mut i.value),
            );
            LockKp::new(prev, ArcMutexAccess::new(), next)
        };

        // Compose RwLock -> Mutex
        let composed = rwlock_kp.then_lock(mutex_kp);

        // Test get through both locks
        let value = composed.get(&root);
        assert!(value.is_some());
    }

    #[test]
    fn test_rwlock_structure() {
        use std::sync::RwLock;

        // Verify ArcRwLockAccess has the same zero-cost structure
        #[derive(Debug, Clone)]
        struct Root {
            data: Arc<RwLock<Inner>>,
        }

        #[derive(Debug, Clone)]
        struct Inner {
            value: i32,
        }

        let root = Root {
            data: Arc::new(RwLock::new(Inner { value: 42 })),
        };

        let prev: KpType<Root, Arc<RwLock<Inner>>> =
            Kp::new(|r: &Root| Some(&r.data), |r: &mut Root| Some(&mut r.data));

        let mid = ArcRwLockAccess::<Inner>::new();

        let next: KpType<Inner, i32> = Kp::new(
            |i: &Inner| Some(&i.value),
            |i: &mut Inner| Some(&mut i.value),
        );

        let rwlock_kp = LockKp::new(prev, mid, next);

        // Verify fields are accessible
        let _prev_field = &rwlock_kp.prev;
        let _mid_field = &rwlock_kp.mid;
        let _next_field = &rwlock_kp.next;

        // Test basic get
        let value = rwlock_kp.get(&root);
        assert!(value.is_some());
    }

    #[test]
    fn test_rwlock_three_levels() {
        use std::sync::RwLock;

        #[derive(Debug, Clone)]
        struct Root {
            lock1: Arc<RwLock<L1>>,
        }

        #[derive(Debug, Clone)]
        struct L1 {
            lock2: Arc<RwLock<L2>>,
        }

        #[derive(Debug, Clone)]
        struct L2 {
            lock3: Arc<RwLock<L3>>,
        }

        #[derive(Debug, Clone)]
        struct L3 {
            value: String,
        }

        let root = Root {
            lock1: Arc::new(RwLock::new(L1 {
                lock2: Arc::new(RwLock::new(L2 {
                    lock3: Arc::new(RwLock::new(L3 {
                        value: "deep_rwlock".to_string(),
                    })),
                })),
            })),
        };

        // Create three RwLock levels
        let lock1 = {
            let prev: KpType<Root, Arc<RwLock<L1>>> =
                Kp::new(|r: &Root| Some(&r.lock1), |r: &mut Root| Some(&mut r.lock1));
            let next: KpType<L1, L1> = Kp::new(|l: &L1| Some(l), |l: &mut L1| Some(l));
            LockKp::new(prev, ArcRwLockAccess::new(), next)
        };

        let lock2 = {
            let prev: KpType<L1, Arc<RwLock<L2>>> =
                Kp::new(|l: &L1| Some(&l.lock2), |l: &mut L1| Some(&mut l.lock2));
            let next: KpType<L2, L2> = Kp::new(|l: &L2| Some(l), |l: &mut L2| Some(l));
            LockKp::new(prev, ArcRwLockAccess::new(), next)
        };

        let lock3 = {
            let prev: KpType<L2, Arc<RwLock<L3>>> =
                Kp::new(|l: &L2| Some(&l.lock3), |l: &mut L2| Some(&mut l.lock3));
            let next: KpType<L3, String> =
                Kp::new(|l: &L3| Some(&l.value), |l: &mut L3| Some(&mut l.value));
            LockKp::new(prev, ArcRwLockAccess::new(), next)
        };

        // Compose all three RwLocks
        let composed = lock1.then_lock(lock2).then_lock(lock3);

        // Test get through all three read locks
        let value = composed.get(&root);
        assert!(value.is_some());
    }

    #[test]
    fn test_rwlock_panic_on_clone_proof() {
        use std::sync::RwLock;

        /// This struct PANICS if cloned - proving no deep cloning occurs
        struct PanicOnClone {
            data: String,
        }

        impl PanicOnClone {
            fn new(s: &str) -> Self {
                Self {
                    data: s.to_string(),
                }
            }

            fn get_data(&self) -> &String {
                &self.data
            }
        }

        impl Clone for PanicOnClone {
            fn clone(&self) -> Self {
                panic!(
                    "❌ DEEP CLONE DETECTED! PanicOnClone was cloned! This should NEVER happen!"
                );
            }
        }

        #[derive(Clone)]
        struct Root {
            lock1: Arc<RwLock<Level1>>,
        }

        /// Level1 contains PanicOnClone - if it's cloned, test will panic
        struct Level1 {
            panic_data: PanicOnClone,
            lock2: Arc<RwLock<Level2>>,
        }

        // We need Clone for Arc<RwLock<Level1>> to work, but we only clone the Arc
        impl Clone for Level1 {
            fn clone(&self) -> Self {
                // This should never be called during keypath operations
                // because Arc cloning doesn't clone the inner value
                panic!("❌ Level1 was deeply cloned! This should NEVER happen!");
            }
        }

        /// Level2 also contains PanicOnClone
        struct Level2 {
            panic_data2: PanicOnClone,
            value: i32,
        }

        impl Clone for Level2 {
            fn clone(&self) -> Self {
                panic!("❌ Level2 was deeply cloned! This should NEVER happen!");
            }
        }

        // Create nested structure with PanicOnClone at each level
        let root = Root {
            lock1: Arc::new(RwLock::new(Level1 {
                panic_data: PanicOnClone::new("level1_data"),
                lock2: Arc::new(RwLock::new(Level2 {
                    panic_data2: PanicOnClone::new("level2_data"),
                    value: 42,
                })),
            })),
        };

        // First RwLock level
        let lock1 = {
            let prev: KpType<Root, Arc<RwLock<Level1>>> =
                Kp::new(|r: &Root| Some(&r.lock1), |r: &mut Root| Some(&mut r.lock1));
            let next: KpType<Level1, Level1> =
                Kp::new(|l: &Level1| Some(l), |l: &mut Level1| Some(l));
            LockKp::new(prev, ArcRwLockAccess::new(), next)
        };

        // Second RwLock level
        let lock2 = {
            let prev: KpType<Level1, Arc<RwLock<Level2>>> = Kp::new(
                |l: &Level1| Some(&l.lock2),
                |l: &mut Level1| Some(&mut l.lock2),
            );
            let next: KpType<Level2, i32> = Kp::new(
                |l: &Level2| Some(&l.value),
                |l: &mut Level2| Some(&mut l.value),
            );
            LockKp::new(prev, ArcRwLockAccess::new(), next)
        };

        // CRITICAL TEST: Compose both locks
        // If any deep cloning occurs, the PanicOnClone will trigger and test will fail
        let composed = lock1.then_lock(lock2);

        // If we get here without panic, shallow cloning is working correctly!
        // Now actually use the composed keypath
        let value = composed.get(&root);

        // ✅ SUCCESS: No panic means no deep cloning occurred!
        // The Arc was cloned (shallow), but Level1, Level2, and PanicOnClone were NOT
        assert!(value.is_some());
    }

    #[test]
    fn test_mutex_panic_on_clone_proof() {
        /// This struct PANICS if cloned - proving no deep cloning occurs
        struct PanicOnClone {
            data: Vec<u8>,
        }

        impl PanicOnClone {
            fn new(size: usize) -> Self {
                Self {
                    data: vec![0u8; size],
                }
            }
        }

        impl Clone for PanicOnClone {
            fn clone(&self) -> Self {
                panic!("❌ DEEP CLONE DETECTED! PanicOnClone was cloned!");
            }
        }

        #[derive(Clone)]
        struct Root {
            lock1: Arc<Mutex<Mid>>,
        }

        struct Mid {
            panic_data: PanicOnClone,
            lock2: Arc<Mutex<Inner>>,
        }

        impl Clone for Mid {
            fn clone(&self) -> Self {
                panic!("❌ Mid was deeply cloned! This should NEVER happen!");
            }
        }

        struct Inner {
            panic_data: PanicOnClone,
            value: String,
        }

        impl Clone for Inner {
            fn clone(&self) -> Self {
                panic!("❌ Inner was deeply cloned! This should NEVER happen!");
            }
        }

        // Create structure with PanicOnClone at each level
        let root = Root {
            lock1: Arc::new(Mutex::new(Mid {
                panic_data: PanicOnClone::new(1_000_000), // 1MB
                lock2: Arc::new(Mutex::new(Inner {
                    panic_data: PanicOnClone::new(1_000_000), // 1MB
                    value: "test".to_string(),
                })),
            })),
        };

        // First Mutex level
        let lock1 = {
            let prev: KpType<Root, Arc<Mutex<Mid>>> =
                Kp::new(|r: &Root| Some(&r.lock1), |r: &mut Root| Some(&mut r.lock1));
            let next: KpType<Mid, Mid> = Kp::new(|m: &Mid| Some(m), |m: &mut Mid| Some(m));
            LockKp::new(prev, ArcMutexAccess::new(), next)
        };

        // Second Mutex level
        let lock2 = {
            let prev: KpType<Mid, Arc<Mutex<Inner>>> =
                Kp::new(|m: &Mid| Some(&m.lock2), |m: &mut Mid| Some(&mut m.lock2));
            let next: KpType<Inner, String> = Kp::new(
                |i: &Inner| Some(&i.value),
                |i: &mut Inner| Some(&mut i.value),
            );
            LockKp::new(prev, ArcMutexAccess::new(), next)
        };

        // CRITICAL TEST: Compose both Mutex locks
        // If any deep cloning occurs, PanicOnClone will trigger
        let composed = lock1.then_lock(lock2);

        // ✅ SUCCESS: No panic means no deep cloning!
        let value = composed.get(&root);
        assert!(value.is_some());
    }

    #[test]
    fn test_mixed_locks_panic_on_clone_proof() {
        use std::sync::RwLock;

        /// Panic-on-clone struct for verification
        struct NeverClone {
            id: usize,
            large_data: Vec<u8>,
        }

        impl NeverClone {
            fn new(id: usize) -> Self {
                Self {
                    id,
                    large_data: vec![0u8; 10_000],
                }
            }
        }

        impl Clone for NeverClone {
            fn clone(&self) -> Self {
                panic!("❌ NeverClone with id {} was cloned!", self.id);
            }
        }

        #[derive(Clone)]
        struct Root {
            rwlock: Arc<RwLock<Mid>>,
        }

        struct Mid {
            never_clone1: NeverClone,
            mutex: Arc<Mutex<Inner>>,
        }

        impl Clone for Mid {
            fn clone(&self) -> Self {
                panic!("❌ Mid was deeply cloned!");
            }
        }

        struct Inner {
            never_clone2: NeverClone,
            value: i32,
        }

        impl Clone for Inner {
            fn clone(&self) -> Self {
                panic!("❌ Inner was deeply cloned!");
            }
        }

        // Create mixed RwLock -> Mutex structure
        let root = Root {
            rwlock: Arc::new(RwLock::new(Mid {
                never_clone1: NeverClone::new(1),
                mutex: Arc::new(Mutex::new(Inner {
                    never_clone2: NeverClone::new(2),
                    value: 999,
                })),
            })),
        };

        // RwLock level
        let rwlock_kp = {
            let prev: KpType<Root, Arc<RwLock<Mid>>> = Kp::new(
                |r: &Root| Some(&r.rwlock),
                |r: &mut Root| Some(&mut r.rwlock),
            );
            let next: KpType<Mid, Mid> = Kp::new(|m: &Mid| Some(m), |m: &mut Mid| Some(m));
            LockKp::new(prev, ArcRwLockAccess::new(), next)
        };

        // Mutex level
        let mutex_kp = {
            let prev: KpType<Mid, Arc<Mutex<Inner>>> =
                Kp::new(|m: &Mid| Some(&m.mutex), |m: &mut Mid| Some(&mut m.mutex));
            let next: KpType<Inner, i32> = Kp::new(
                |i: &Inner| Some(&i.value),
                |i: &mut Inner| Some(&mut i.value),
            );
            LockKp::new(prev, ArcMutexAccess::new(), next)
        };

        // CRITICAL TEST: Compose RwLock with Mutex
        // If deep cloning occurs, NeverClone will panic
        let composed = rwlock_kp.then_lock(mutex_kp);

        // ✅ SUCCESS: No panic = no deep cloning!
        // Only Arc refcounts were incremented
        let value = composed.get(&root);
        assert!(value.is_some());

        // Additional verification: Use it multiple times
        let value2 = composed.get(&root);
        assert!(value2.is_some());

        // Still no panic - proves shallow cloning is consistent
    }

    // ========================================================================
    // Rc<RefCell<T>> Tests (Single-threaded)
    // ========================================================================

    #[test]
    fn test_rc_refcell_basic() {
        use std::cell::RefCell;
        use std::rc::Rc;

        #[derive(Clone)]
        struct Root {
            data: Rc<RefCell<Inner>>,
        }

        #[derive(Clone)]
        struct Inner {
            value: String,
        }

        let root = Root {
            data: Rc::new(RefCell::new(Inner {
                value: "hello".to_string(),
            })),
        };

        // Create LockKp for Rc<RefCell<T>>
        let lock_kp = {
            let prev: KpType<Root, Rc<RefCell<Inner>>> =
                Kp::new(|r: &Root| Some(&r.data), |r: &mut Root| Some(&mut r.data));
            let next: KpType<Inner, String> = Kp::new(
                |i: &Inner| Some(&i.value),
                |i: &mut Inner| Some(&mut i.value),
            );
            LockKp::new(prev, RcRefCellAccess::new(), next)
        };

        // Test get
        let value = lock_kp.get(&root);
        assert!(value.is_some());
        assert_eq!(value.unwrap(), "hello");

        // Test set
        let result = lock_kp.set(&root, |s| {
            *s = "world".to_string();
        });
        assert!(result.is_ok());

        // Verify the change
        let value = lock_kp.get(&root);
        assert_eq!(value.unwrap(), "world");
    }

    #[test]
    fn test_rc_refcell_compose_two_levels() {
        use std::cell::RefCell;
        use std::rc::Rc;

        #[derive(Clone)]
        struct Root {
            level1: Rc<RefCell<Level1>>,
        }

        #[derive(Clone)]
        struct Level1 {
            level2: Rc<RefCell<Level2>>,
        }

        #[derive(Clone)]
        struct Level2 {
            value: i32,
        }

        let root = Root {
            level1: Rc::new(RefCell::new(Level1 {
                level2: Rc::new(RefCell::new(Level2 { value: 42 })),
            })),
        };

        // First level
        let lock1 = {
            let prev: KpType<Root, Rc<RefCell<Level1>>> = Kp::new(
                |r: &Root| Some(&r.level1),
                |r: &mut Root| Some(&mut r.level1),
            );
            let next: KpType<Level1, Level1> =
                Kp::new(|l: &Level1| Some(l), |l: &mut Level1| Some(l));
            LockKp::new(prev, RcRefCellAccess::new(), next)
        };

        // Second level
        let lock2 = {
            let prev: KpType<Level1, Rc<RefCell<Level2>>> = Kp::new(
                |l: &Level1| Some(&l.level2),
                |l: &mut Level1| Some(&mut l.level2),
            );
            let next: KpType<Level2, i32> = Kp::new(
                |l: &Level2| Some(&l.value),
                |l: &mut Level2| Some(&mut l.value),
            );
            LockKp::new(prev, RcRefCellAccess::new(), next)
        };

        // Compose both levels
        let composed = lock1.then_lock(lock2);

        // Test get through both locks
        let value = composed.get(&root);
        assert!(value.is_some());
        assert_eq!(*value.unwrap(), 42);

        // Test set through both locks
        let result = composed.set(&root, |v| {
            *v = 100;
        });
        assert!(result.is_ok());

        // Verify change
        let value = composed.get(&root);
        assert_eq!(*value.unwrap(), 100);
    }

    #[test]
    fn test_rc_refcell_three_levels() {
        use std::cell::RefCell;
        use std::rc::Rc;

        #[derive(Clone)]
        struct Root {
            l1: Rc<RefCell<L1>>,
        }

        #[derive(Clone)]
        struct L1 {
            l2: Rc<RefCell<L2>>,
        }

        #[derive(Clone)]
        struct L2 {
            l3: Rc<RefCell<L3>>,
        }

        #[derive(Clone)]
        struct L3 {
            value: String,
        }

        let root = Root {
            l1: Rc::new(RefCell::new(L1 {
                l2: Rc::new(RefCell::new(L2 {
                    l3: Rc::new(RefCell::new(L3 {
                        value: "deep".to_string(),
                    })),
                })),
            })),
        };

        // Level 1
        let lock1 = {
            let prev: KpType<Root, Rc<RefCell<L1>>> =
                Kp::new(|r: &Root| Some(&r.l1), |r: &mut Root| Some(&mut r.l1));
            let next: KpType<L1, L1> = Kp::new(|l: &L1| Some(l), |l: &mut L1| Some(l));
            LockKp::new(prev, RcRefCellAccess::new(), next)
        };

        // Level 2
        let lock2 = {
            let prev: KpType<L1, Rc<RefCell<L2>>> =
                Kp::new(|l: &L1| Some(&l.l2), |l: &mut L1| Some(&mut l.l2));
            let next: KpType<L2, L2> = Kp::new(|l: &L2| Some(l), |l: &mut L2| Some(l));
            LockKp::new(prev, RcRefCellAccess::new(), next)
        };

        // Level 3
        let lock3 = {
            let prev: KpType<L2, Rc<RefCell<L3>>> =
                Kp::new(|l: &L2| Some(&l.l3), |l: &mut L2| Some(&mut l.l3));
            let next: KpType<L3, String> =
                Kp::new(|l: &L3| Some(&l.value), |l: &mut L3| Some(&mut l.value));
            LockKp::new(prev, RcRefCellAccess::new(), next)
        };

        // Compose all three levels
        let composed_1_2 = lock1.then_lock(lock2);
        let composed_all = composed_1_2.then_lock(lock3);

        // Test get through all three locks
        let value = composed_all.get(&root);
        assert!(value.is_some());
        assert_eq!(value.unwrap(), "deep");
    }

    #[test]
    fn test_rc_refcell_panic_on_clone_proof() {
        use std::cell::RefCell;
        use std::rc::Rc;

        /// This struct PANICS if cloned - proving no deep cloning occurs
        struct PanicOnClone {
            data: String,
        }

        impl Clone for PanicOnClone {
            fn clone(&self) -> Self {
                panic!("❌ DEEP CLONE DETECTED! PanicOnClone was cloned in Rc<RefCell>!");
            }
        }

        #[derive(Clone)]
        struct Root {
            level1: Rc<RefCell<Level1>>,
        }

        struct Level1 {
            panic_data: PanicOnClone,
            level2: Rc<RefCell<Level2>>,
        }

        impl Clone for Level1 {
            fn clone(&self) -> Self {
                panic!("❌ Level1 was deeply cloned in Rc<RefCell>!");
            }
        }

        struct Level2 {
            panic_data2: PanicOnClone,
            value: i32,
        }

        impl Clone for Level2 {
            fn clone(&self) -> Self {
                panic!("❌ Level2 was deeply cloned in Rc<RefCell>!");
            }
        }

        // Create nested Rc<RefCell> structure with PanicOnClone
        let root = Root {
            level1: Rc::new(RefCell::new(Level1 {
                panic_data: PanicOnClone {
                    data: "level1".to_string(),
                },
                level2: Rc::new(RefCell::new(Level2 {
                    panic_data2: PanicOnClone {
                        data: "level2".to_string(),
                    },
                    value: 123,
                })),
            })),
        };

        // First level
        let lock1 = {
            let prev: KpType<Root, Rc<RefCell<Level1>>> = Kp::new(
                |r: &Root| Some(&r.level1),
                |r: &mut Root| Some(&mut r.level1),
            );
            let next: KpType<Level1, Level1> =
                Kp::new(|l: &Level1| Some(l), |l: &mut Level1| Some(l));
            LockKp::new(prev, RcRefCellAccess::new(), next)
        };

        // Second level
        let lock2 = {
            let prev: KpType<Level1, Rc<RefCell<Level2>>> = Kp::new(
                |l: &Level1| Some(&l.level2),
                |l: &mut Level1| Some(&mut l.level2),
            );
            let next: KpType<Level2, i32> = Kp::new(
                |l: &Level2| Some(&l.value),
                |l: &mut Level2| Some(&mut l.value),
            );
            LockKp::new(prev, RcRefCellAccess::new(), next)
        };

        // CRITICAL TEST: Compose both Rc<RefCell> locks
        // If any deep cloning occurs, PanicOnClone will trigger
        let composed = lock1.then_lock(lock2);

        // ✅ SUCCESS: No panic means no deep cloning!
        // Only Rc refcounts were incremented (shallow)
        let value = composed.get(&root);
        assert!(value.is_some());
        assert_eq!(*value.unwrap(), 123);

        // Additional test: Multiple accesses don't clone
        let value2 = composed.get(&root);
        assert!(value2.is_some());
    }

    #[test]
    fn test_rc_refcell_vs_arc_mutex() {
        use std::cell::RefCell;
        use std::rc::Rc;

        // This test demonstrates the API similarity between Rc<RefCell> and Arc<Mutex>

        #[derive(Clone)]
        struct RcRoot {
            data: Rc<RefCell<String>>,
        }

        #[derive(Clone)]
        struct ArcRoot {
            data: Arc<Mutex<String>>,
        }

        // Rc<RefCell> version (single-threaded)
        let rc_root = RcRoot {
            data: Rc::new(RefCell::new("rc_value".to_string())),
        };

        let rc_kp = {
            let prev: KpType<RcRoot, Rc<RefCell<String>>> = Kp::new(
                |r: &RcRoot| Some(&r.data),
                |r: &mut RcRoot| Some(&mut r.data),
            );
            let next: KpType<String, String> =
                Kp::new(|s: &String| Some(s), |s: &mut String| Some(s));
            LockKp::new(prev, RcRefCellAccess::new(), next)
        };

        // Arc<Mutex> version (multi-threaded)
        let arc_root = ArcRoot {
            data: Arc::new(Mutex::new("arc_value".to_string())),
        };

        let arc_kp = {
            let prev: KpType<ArcRoot, Arc<Mutex<String>>> = Kp::new(
                |r: &ArcRoot| Some(&r.data),
                |r: &mut ArcRoot| Some(&mut r.data),
            );
            let next: KpType<String, String> =
                Kp::new(|s: &String| Some(s), |s: &mut String| Some(s));
            LockKp::new(prev, ArcMutexAccess::new(), next)
        };

        // Both have identical API usage!
        let rc_value = rc_kp.get(&rc_root);
        let arc_value = arc_kp.get(&arc_root);

        assert_eq!(rc_value.unwrap(), "rc_value");
        assert_eq!(arc_value.unwrap(), "arc_value");
    }

    // ========================================================================
    // Parking Lot Tests
    // ========================================================================

    #[cfg(feature = "parking_lot")]
    #[test]
    fn test_parking_lot_mutex_basic() {
        use parking_lot::Mutex;

        #[derive(Clone)]
        struct Root {
            data: Arc<Mutex<String>>,
        }

        let root = Root {
            data: Arc::new(Mutex::new("parking_lot_mutex".to_string())),
        };

        let lock_kp = {
            let prev: KpType<Root, Arc<Mutex<String>>> =
                Kp::new(|r: &Root| Some(&r.data), |r: &mut Root| Some(&mut r.data));
            let next: KpType<String, String> =
                Kp::new(|s: &String| Some(s), |s: &mut String| Some(s));
            LockKp::new(prev, ParkingLotMutexAccess::new(), next)
        };

        let value = lock_kp.get(&root);
        assert_eq!(value.unwrap(), &"parking_lot_mutex".to_string());
    }

    #[cfg(feature = "parking_lot")]
    #[test]
    fn test_parking_lot_rwlock_basic() {
        use parking_lot::RwLock;

        #[derive(Clone)]
        struct Root {
            data: Arc<RwLock<Vec<i32>>>,
        }

        let root = Root {
            data: Arc::new(RwLock::new(vec![1, 2, 3, 4, 5])),
        };

        let lock_kp = {
            let prev: KpType<Root, Arc<RwLock<Vec<i32>>>> =
                Kp::new(|r: &Root| Some(&r.data), |r: &mut Root| Some(&mut r.data));
            let next: KpType<Vec<i32>, Vec<i32>> =
                Kp::new(|v: &Vec<i32>| Some(v), |v: &mut Vec<i32>| Some(v));
            LockKp::new(prev, ParkingLotRwLockAccess::new(), next)
        };

        let value = lock_kp.get(&root);
        assert_eq!(value.unwrap().len(), 5);
        assert_eq!(value.unwrap()[2], 3);
    }

    #[cfg(feature = "parking_lot")]
    #[test]
    fn test_parking_lot_mutex_compose() {
        use parking_lot::Mutex;

        #[derive(Clone)]
        struct Root {
            level1: Arc<Mutex<Level1>>,
        }

        #[derive(Clone)]
        struct Level1 {
            level2: Arc<Mutex<i32>>,
        }

        let root = Root {
            level1: Arc::new(Mutex::new(Level1 {
                level2: Arc::new(Mutex::new(42)),
            })),
        };

        // First level: Root -> Level1
        let lock1 = {
            let prev: KpType<Root, Arc<Mutex<Level1>>> = Kp::new(
                |r: &Root| Some(&r.level1),
                |r: &mut Root| Some(&mut r.level1),
            );
            let next: KpType<Level1, Level1> =
                Kp::new(|l: &Level1| Some(l), |l: &mut Level1| Some(l));
            LockKp::new(prev, ParkingLotMutexAccess::new(), next)
        };

        // Second level: Level1 -> i32
        let lock2 = {
            let prev: KpType<Level1, Arc<Mutex<i32>>> = Kp::new(
                |l: &Level1| Some(&l.level2),
                |l: &mut Level1| Some(&mut l.level2),
            );
            let next: KpType<i32, i32> = Kp::new(|n: &i32| Some(n), |n: &mut i32| Some(n));
            LockKp::new(prev, ParkingLotMutexAccess::new(), next)
        };

        // Compose both levels
        let composed = lock1.then_lock(lock2);
        let value = composed.get(&root);
        assert_eq!(value.unwrap(), &42);
    }

    #[cfg(feature = "parking_lot")]
    #[test]
    fn test_parking_lot_rwlock_write() {
        use parking_lot::RwLock;

        #[derive(Clone)]
        struct Root {
            data: Arc<RwLock<i32>>,
        }

        let mut root = Root {
            data: Arc::new(RwLock::new(100)),
        };

        let lock_kp = {
            let prev: KpType<Root, Arc<RwLock<i32>>> =
                Kp::new(|r: &Root| Some(&r.data), |r: &mut Root| Some(&mut r.data));
            let next: KpType<i32, i32> = Kp::new(|n: &i32| Some(n), |n: &mut i32| Some(n));
            LockKp::new(prev, ParkingLotRwLockAccess::new(), next)
        };

        // Read initial value
        let value = lock_kp.get(&root);
        assert_eq!(value.unwrap(), &100);

        // Get mutable access and modify
        let mut_value = lock_kp.get_mut(&mut root);
        assert!(mut_value.is_some());
        if let Some(v) = mut_value {
            *v = 200;
        }

        // Verify the change
        let new_value = lock_kp.get(&root);
        assert_eq!(new_value.unwrap(), &200);
    }

    #[cfg(feature = "parking_lot")]
    #[test]
    fn test_parking_lot_panic_on_clone_proof() {
        use parking_lot::Mutex;

        /// This struct PANICS if cloned - proving no deep cloning occurs
        struct PanicOnClone {
            data: String,
        }

        impl Clone for PanicOnClone {
            fn clone(&self) -> Self {
                panic!("❌ PARKING_LOT DEEP CLONE DETECTED! PanicOnClone was cloned!");
            }
        }

        #[derive(Clone)]
        struct Root {
            level1: Arc<Mutex<Level1>>,
        }

        struct Level1 {
            panic_data: PanicOnClone,
            value: i32,
        }

        impl Clone for Level1 {
            fn clone(&self) -> Self {
                panic!("❌ Level1 was deeply cloned in parking_lot context!");
            }
        }

        let root = Root {
            level1: Arc::new(Mutex::new(Level1 {
                panic_data: PanicOnClone {
                    data: "test".to_string(),
                },
                value: 123,
            })),
        };

        let lock_kp = {
            let prev: KpType<Root, Arc<Mutex<Level1>>> = Kp::new(
                |r: &Root| Some(&r.level1),
                |r: &mut Root| Some(&mut r.level1),
            );
            let next: KpType<Level1, i32> = Kp::new(
                |l: &Level1| Some(&l.value),
                |l: &mut Level1| Some(&mut l.value),
            );
            LockKp::new(prev, ParkingLotMutexAccess::new(), next)
        };

        // CRITICAL TEST: If any deep cloning occurs, PanicOnClone will trigger
        let value = lock_kp.get(&root);

        // ✅ SUCCESS: No panic means no deep cloning!
        assert_eq!(value.unwrap(), &123);
    }

    #[test]
    fn test_std_mutex_direct() {
        use std::sync::Mutex;

        struct Root {
            data: Mutex<Inner>,
        }

        struct Inner {
            value: i32,
        }

        let mut root = Root {
            data: Mutex::new(Inner { value: 42 }),
        };

        let lock_kp = {
            let prev: KpType<Root, Mutex<Inner>> =
                Kp::new(|r: &Root| Some(&r.data), |r: &mut Root| Some(&mut r.data));
            let next: KpType<Inner, i32> = Kp::new(
                |i: &Inner| Some(&i.value),
                |i: &mut Inner| Some(&mut i.value),
            );
            LockKp::new(prev, StdMutexAccess::new(), next)
        };

        // Test read access
        let value = lock_kp.get(&root);
        assert_eq!(value, Some(&42));

        // Test write access
        lock_kp.get_mut(&mut root).map(|v| *v = 100);
        let value = lock_kp.get(&root);
        assert_eq!(value, Some(&100));
    }

    #[test]
    fn test_std_rwlock_direct() {
        use std::sync::RwLock;

        struct Root {
            data: RwLock<Inner>,
        }

        struct Inner {
            value: String,
        }

        let mut root = Root {
            data: RwLock::new(Inner {
                value: "hello".to_string(),
            }),
        };

        let lock_kp = {
            let prev: KpType<Root, RwLock<Inner>> =
                Kp::new(|r: &Root| Some(&r.data), |r: &mut Root| Some(&mut r.data));
            let next: KpType<Inner, String> = Kp::new(
                |i: &Inner| Some(&i.value),
                |i: &mut Inner| Some(&mut i.value),
            );
            LockKp::new(prev, StdRwLockAccess::new(), next)
        };

        // Test read access
        let value = lock_kp.get(&root);
        assert_eq!(value.as_ref().map(|s| s.as_str()), Some("hello"));

        // Test write access
        lock_kp.get_mut(&mut root).map(|v| *v = "world".to_string());
        let value = lock_kp.get(&root);
        assert_eq!(value.as_ref().map(|s| s.as_str()), Some("world"));
    }

    #[cfg(feature = "parking_lot")]
    #[test]
    fn test_parking_lot_mutex_direct() {
        use parking_lot::Mutex;

        struct Root {
            data: Mutex<Inner>,
        }

        struct Inner {
            value: i32,
        }

        let mut root = Root {
            data: Mutex::new(Inner { value: 42 }),
        };

        let lock_kp = {
            let prev: KpType<Root, Mutex<Inner>> =
                Kp::new(|r: &Root| Some(&r.data), |r: &mut Root| Some(&mut r.data));
            let next: KpType<Inner, i32> = Kp::new(
                |i: &Inner| Some(&i.value),
                |i: &mut Inner| Some(&mut i.value),
            );
            LockKp::new(prev, DirectParkingLotMutexAccess::new(), next)
        };

        // Test read access
        let value = lock_kp.get(&root);
        assert_eq!(value, Some(&42));

        // Test write access
        lock_kp.get_mut(&mut root).map(|v| *v = 100);
        let value = lock_kp.get(&root);
        assert_eq!(value, Some(&100));
    }

    #[cfg(feature = "parking_lot")]
    #[test]
    fn test_parking_lot_rwlock_direct() {
        use parking_lot::RwLock;

        struct Root {
            data: RwLock<Inner>,
        }

        struct Inner {
            value: String,
        }

        let mut root = Root {
            data: RwLock::new(Inner {
                value: "hello".to_string(),
            }),
        };

        let lock_kp = {
            let prev: KpType<Root, RwLock<Inner>> =
                Kp::new(|r: &Root| Some(&r.data), |r: &mut Root| Some(&mut r.data));
            let next: KpType<Inner, String> = Kp::new(
                |i: &Inner| Some(&i.value),
                |i: &mut Inner| Some(&mut i.value),
            );
            LockKp::new(prev, DirectParkingLotRwLockAccess::new(), next)
        };

        // Test read access
        let value = lock_kp.get(&root);
        assert_eq!(value.as_ref().map(|s| s.as_str()), Some("hello"));

        // Test write access
        lock_kp.get_mut(&mut root).map(|v| *v = "world".to_string());
        let value = lock_kp.get(&root);
        assert_eq!(value.as_ref().map(|s| s.as_str()), Some("world"));
    }
}