refactor: fix Miri violations and improve concurrency safety

.github/workflows/rust.yml

@@ -44,3 +44,17 @@ jobs:
         token: ${{ secrets.CODECOV_TOKEN }}
         slug: SF-Zhou/lockmap
         files: target/nextest/default/junit.xml
+
+  miri:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install nightly toolchain with Miri
+        uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: miri
+
+      - name: Run Miri tests
+        run: cargo miri test lockmap::tests

Cargo.toml

@@ -10,6 +10,7 @@ description = "A high-performance, thread-safe HashMap implementation for Rust t
 license = "MIT OR Apache-2.0"
 
 [dependencies]
+aliasable = "0.1.3"
 atomic-wait = "1"
 foldhash = "0.1.5"
 

README.md

@@ -39,28 +39,6 @@ keys.insert("key2".to_string());
 let mut locked_entries = map.batch_lock::<std::collections::HashMap<_, _>>(keys);
 ```
 
-## FAQ
-
-### Why is the miri test failing?
-
-Running `cargo miri test` will report a Stacked Borrows violation. This is **expected and intentional**. 
-
-The crate uses a pattern where we obtain a raw pointer to heap-allocated data before moving the `Box` into the internal map. This is done to atomically insert and obtain access to the state in a single lock-protected operation: 
-
-```rust
-let mut state: Box<_> = Box::new(State { /* ... */ });
-let ptr = state.as_mut() as *mut State<V>;
-(UpdateAction::Replace(state), ptr)  // Move Box, return pointer
-```
-
-While this violates Miri's experimental [Stacked Borrows](https://github.com/rust-lang/unsafe-code-guidelines/blob/master/wip/stacked-borrows.md) model, it is **safe in practice** because:
-
-1. Moving a `Box` doesn't relocate the heap data—the pointer remains valid
-2. The `refcnt` mechanism guarantees exclusive access to the state
-3. Extensive concurrent tests validate correctness under heavy contention
-
-For a detailed explanation, see [#20](https://github.com/SF-Zhou/lockmap/issues/20).
-
 ## License
 
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FSF-Zhou%2Flockmap.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2FSF-Zhou%2Flockmap?ref=badge_large)

src/futex.rs

@@ -77,7 +77,7 @@ impl Mutex {
     /// Acquires the lock, blocking the current thread until it becomes available.
     ///
     /// This function will not return until the lock has been acquired.
-    /// 
+    ///
     /// # Panics
     ///
     /// This function may panic if the current thread already holds the lock.