litclaude-ai 0.2.2

package/plugins/litclaude/skills/programming/references/rust/type-state.md

@@ -0,0 +1,354 @@
+# Type-State and Newtype Patterns
+
+The single highest-leverage thing Rust gives a coding agent: encode invariants in the type system so the compiler refuses incorrect code. The agent does not have to "remember" rules - the rules are physical.
+
+## The Two Core Patterns
+
+1. **Newtype wrappers for distinct semantic units.** Money, IDs, byte offsets, coordinate spaces - each gets its own tuple struct. The agent cannot pass meters where feet are expected, even though both are `f64` under the hood. This is the `euclid::Point<Screen>` vs `euclid::Point<World>` example Chris Allen called out.
+2. **Type-state for state machines.** Instead of a struct with a `status: enum { Draft, Validated, Persisted }` field and methods that check `if self.status == ...`, model each state as its own type. Transitions are method calls that consume `self` and return a new type. Illegal transitions become unrepresentable.
+
+## Newtype Wrapper Cookbook
+
+### Domain IDs
+
+```rust
+use uuid::Uuid;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+#[serde(transparent)]
+pub struct UserId(Uuid);
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+#[serde(transparent)]
+pub struct ProductId(Uuid);
+
+impl UserId {
+    pub fn new() -> Self { Self(Uuid::now_v7()) }
+    pub fn as_uuid(&self) -> &Uuid { &self.0 }
+}
+
+impl ProductId {
+    pub fn new() -> Self { Self(Uuid::now_v7()) }
+    pub fn as_uuid(&self) -> &Uuid { &self.0 }
+}
+
+// `fn buy(user: UserId, product: ProductId)` cannot be called with arguments swapped.
+```
+
+`#[serde(transparent)]` keeps JSON/SQL round-trips identical to a bare `Uuid` - the wrapper is purely a compile-time discipline.
+
+### Quantities with Phantom Type Tags
+
+```rust
+use core::marker::PhantomData;
+use core::ops::{Add, Sub, Mul};
+
+#[derive(Debug, Clone, Copy)]
+pub struct Quantity<Unit> {
+    raw: f64,
+    _unit: PhantomData<Unit>,
+}
+
+// Tag types - zero-sized, never instantiated.
+pub struct Meters;
+pub struct Feet;
+pub struct Seconds;
+
+impl<U> Quantity<U> {
+    pub const fn new(value: f64) -> Self {
+        Self { raw: value, _unit: PhantomData }
+    }
+    pub fn raw(self) -> f64 { self.raw }
+}
+
+// Adding same-unit quantities: allowed.
+impl<U> Add for Quantity<U> {
+    type Output = Self;
+    fn add(self, rhs: Self) -> Self { Self::new(self.raw + rhs.raw) }
+}
+
+// Subtraction: allowed.
+impl<U> Sub for Quantity<U> {
+    type Output = Self;
+    fn sub(self, rhs: Self) -> Self { Self::new(self.raw - rhs.raw) }
+}
+
+// Multiplying by scalar: allowed.
+impl<U> Mul<f64> for Quantity<U> {
+    type Output = Self;
+    fn mul(self, rhs: f64) -> Self { Self::new(self.raw * rhs) }
+}
+
+// Conversions are explicit, named methods - never `From`/`Into` between units.
+impl Quantity<Meters> {
+    pub fn to_feet(self) -> Quantity<Feet> {
+        Quantity::new(self.raw * 3.280_84)
+    }
+}
+```
+
+Now:
+
+```rust
+let distance: Quantity<Meters> = Quantity::new(100.0);
+let height: Quantity<Feet> = Quantity::new(50.0);
+let combined = distance + height; // ❌ compile error
+let combined = distance + height.to_feet().to_meters_oops(); // ❌ no such method
+let combined = distance + distance; // ✅
+```
+
+The agent cannot accidentally mix units. Refactors that change a quantity's underlying unit are caught at compile time everywhere the type flows.
+
+### Byte Offsets vs Character Offsets
+
+```rust
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub struct ByteOffset(pub u32);
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub struct CharOffset(pub u32);
+
+impl ByteOffset {
+    pub fn add(self, delta: u32) -> Self { Self(self.0 + delta) }
+}
+
+// Converting between them is a function on the actual text.
+pub fn byte_to_char(text: &str, byte: ByteOffset) -> Option<CharOffset> {
+    text.get(..byte.0 as usize).map(|prefix| CharOffset(prefix.chars().count() as u32))
+}
+```
+
+A function signature `fn slice(text: &str, start: ByteOffset, end: ByteOffset)` cannot be called with character offsets. The UTF-8 boundary bug is now a compile error.
+
+### Currency
+
+```rust
+use rust_decimal::Decimal;
+
+pub struct Krw;
+pub struct Usd;
+pub struct Jpy;
+
+#[derive(Debug, Clone, Copy)]
+pub struct Money<Currency> {
+    amount: Decimal,
+    _ccy: PhantomData<Currency>,
+}
+
+impl<C> Money<C> {
+    pub const fn new(amount: Decimal) -> Self { Self { amount, _ccy: PhantomData } }
+}
+
+impl<C> Add for Money<C> {
+    type Output = Self;
+    fn add(self, rhs: Self) -> Self { Self::new(self.amount + rhs.amount) }
+}
+
+// No blanket From<Money<X>> for Money<Y> - conversions go through an explicit
+// FX rate function that takes a `Rate<From, To>` argument.
+
+pub struct Rate<From, To> {
+    factor: Decimal,
+    _from: PhantomData<From>,
+    _to: PhantomData<To>,
+}
+
+impl<From, To> Money<From> {
+    pub fn convert(self, rate: Rate<From, To>) -> Money<To> {
+        Money::new(self.amount * rate.factor)
+    }
+}
+```
+
+The agent cannot add KRW and USD by accident. They cannot convert without a rate. They cannot apply a USD→JPY rate to a KRW value.
+
+### Paths Rooted at Different Bases
+
+```rust
+use std::path::{Path, PathBuf};
+
+/// A path guaranteed to be relative to the project root.
+#[derive(Debug, Clone)]
+pub struct ProjectRel(PathBuf);
+
+/// A path guaranteed to be relative to the user's home directory.
+#[derive(Debug, Clone)]
+pub struct HomeRel(PathBuf);
+
+impl ProjectRel {
+    pub fn new(path: impl AsRef<Path>) -> Result<Self, PathError> {
+        let path = path.as_ref();
+        if path.is_absolute() { return Err(PathError::NotRelative); }
+        if path.components().any(|c| matches!(c, std::path::Component::ParentDir)) {
+            return Err(PathError::EscapesRoot);
+        }
+        Ok(Self(path.to_path_buf()))
+    }
+
+    pub fn resolve(&self, project_root: &Path) -> PathBuf {
+        project_root.join(&self.0)
+    }
+}
+```
+
+The agent's path-handling code now distinguishes between project-relative and home-relative paths at the type level. A function taking `ProjectRel` cannot be called with a `HomeRel`.
+
+## Type-State State Machines
+
+Encode the lifecycle of a value as a sequence of types. Each transition consumes the previous state and returns the next.
+
+### HTTP Request Builder
+
+```rust
+pub struct RequestBuilder<State> {
+    url: String,
+    method: Method,
+    headers: HeaderMap,
+    body: Option<Vec<u8>>,
+    _state: PhantomData<State>,
+}
+
+pub struct NeedsUrl;
+pub struct NeedsMethod;
+pub struct Ready;
+
+impl RequestBuilder<NeedsUrl> {
+    pub fn new() -> Self {
+        Self {
+            url: String::new(),
+            method: Method::GET,
+            headers: HeaderMap::new(),
+            body: None,
+            _state: PhantomData,
+        }
+    }
+    pub fn url(mut self, url: impl Into<String>) -> RequestBuilder<NeedsMethod> {
+        self.url = url.into();
+        RequestBuilder { url: self.url, method: self.method, headers: self.headers, body: self.body, _state: PhantomData }
+    }
+}
+
+impl RequestBuilder<NeedsMethod> {
+    pub fn method(mut self, method: Method) -> RequestBuilder<Ready> {
+        self.method = method;
+        RequestBuilder { url: self.url, method: self.method, headers: self.headers, body: self.body, _state: PhantomData }
+    }
+}
+
+// .header(), .body() available in any state that has at least URL.
+impl<S> RequestBuilder<S> {
+    pub fn header(mut self, name: HeaderName, value: HeaderValue) -> Self {
+        self.headers.insert(name, value);
+        self
+    }
+}
+
+// .send() only available once URL and method are set.
+impl RequestBuilder<Ready> {
+    pub async fn send(self, client: &Client) -> reqwest::Result<Response> { /* ... */ }
+}
+```
+
+`client.send(RequestBuilder::new().send(...))` - compile error. The agent has to fill in the required steps. The IDE autocomplete also reflects only the legal next steps.
+
+### File Handles
+
+```rust
+pub struct File<State> {
+    fd: RawFd,
+    _state: PhantomData<State>,
+}
+
+pub struct Open;
+pub struct Locked;
+pub struct Closed;
+
+impl File<Open> {
+    pub fn open(path: &Path) -> std::io::Result<Self> { /* ... */ }
+    pub fn lock_exclusive(self) -> std::io::Result<File<Locked>> { /* flock */ }
+    pub fn close(self) -> std::io::Result<File<Closed>> { /* ... */ }
+}
+
+impl File<Locked> {
+    pub fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> { /* ... */ }
+    pub fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> { /* ... */ }
+    pub fn unlock(self) -> std::io::Result<File<Open>> { /* ... */ }
+}
+
+impl File<Closed> {
+    // No methods. The type only exists to be dropped.
+}
+```
+
+You cannot `read()` an unlocked file. You cannot `close()` while holding a lock without unlocking first. You cannot use a closed file at all - it has no methods.
+
+## Sealed Traits
+
+Sometimes you want a closed set of types implementing a trait, defined by the crate, not extensible by downstream. The sealed trait pattern:
+
+```rust
+mod sealed {
+    pub trait Sealed {}
+}
+
+pub trait Renderer: sealed::Sealed {
+    fn render(&self, frame: &mut Frame);
+}
+
+pub struct OpenGl;
+pub struct Vulkan;
+pub struct Metal;
+
+impl sealed::Sealed for OpenGl {}
+impl sealed::Sealed for Vulkan {}
+impl sealed::Sealed for Metal {}
+
+impl Renderer for OpenGl { fn render(&self, f: &mut Frame) { /* ... */ } }
+impl Renderer for Vulkan { fn render(&self, f: &mut Frame) { /* ... */ } }
+impl Renderer for Metal  { fn render(&self, f: &mut Frame) { /* ... */ } }
+```
+
+Downstream code cannot add new `impl Renderer for Whatever` because they cannot implement `sealed::Sealed` (its module is private). Useful when you want trait dispatch but maintain the invariant that you control all implementations.
+
+## NonEmpty Collections
+
+```rust
+pub struct NonEmptyVec<T> {
+    head: T,
+    tail: Vec<T>,
+}
+
+#[derive(Debug, thiserror::Error)]
+#[error("vector was empty")]
+pub struct Empty;
+
+impl<T> NonEmptyVec<T> {
+    pub fn try_from_vec(mut v: Vec<T>) -> Result<Self, Empty> {
+        if v.is_empty() { return Err(Empty); }
+        let tail = v.split_off(1);
+        let head = v.into_iter().next().expect("checked non-empty");
+        Ok(Self { head, tail })
+    }
+
+    pub fn first(&self) -> &T { &self.head }
+    pub fn len(&self) -> usize { self.tail.len() + 1 }
+}
+```
+
+Functions taking `NonEmptyVec<T>` cannot receive an empty vector. The `first()` method returns `&T`, not `Option<&T>`. The agent never has to write `match v.first() { Some(x) => ..., None => panic!(...) }` again.
+
+## When NOT to Newtype
+
+- For one-off internal computations where the unit lives in a single function and never crosses a boundary.
+- When the wrapper does not change behavior or invariants vs. the underlying type (e.g., a `struct Count(u32)` that is only ever used in one struct).
+- When `From`/`Into` conversions would be ergonomic but would defeat the purpose (if you find yourself wanting `impl From<UserId> for Uuid`, you do not want a newtype - you want a type alias).
+
+The cost of a newtype is one tuple struct + the impls you need. The break-even is around three uses across different functions, or any use that crosses an API boundary.
+
+## When NOT to Use Type-State
+
+- When the state space is small and transitions are simple (`Option<T>` and `Result<T, E>` are state machines already).
+- When the type-state would force runtime branching upward (e.g., reading "should this run as Open or Locked?" from config means you store `Box<dyn FileLike>` anyway).
+- When the API is consumed by code that does not know the state at compile time (heterogeneous collections, dynamic dispatch boundaries).
+
+In those cases, regular enum-tagged states are correct. The line is: **can the call site know the state statically?** If yes, type-state. If no, enum-with-tag.

package/plugins/litclaude/skills/programming/references/rust/unsafe-discipline.md

@@ -0,0 +1,250 @@
+# Unsafe Discipline
+
+The reason Chris Allen's "implementing a persistent memory arena in Rust was not hard" works: the unsafe surface area is microscopic, it lives behind one newtype with one constructor, and every block has a SAFETY comment that names a specific invariant. Coding agents follow the pattern mechanically once the shape is established.
+
+## The Three Required Components
+
+Every `unsafe` block needs all three. No exceptions.
+
+1. **Safe wrapper.** No `unsafe fn` or raw pointer types in the crate's public API. If a caller needs to construct an instance, the constructor either does the work safely or is `unsafe` with a documented contract.
+2. **SAFETY comment.** A `// SAFETY:` line within 5 lines above the `unsafe { ... }` block, stating which invariant is upheld and where it comes from. Generic phrases ("this is safe because we checked") fail review.
+3. **miri proof.** A test that exercises the unsafe path under `cargo +nightly miri nextest run`. If the path cannot be exercised under miri (FFI, syscalls), provide an alternate proof and gate behind a feature flag ending in `-skip-miri`.
+
+## The Wrapper Pattern (`NonNull<T>` style)
+
+Reference the screenshot Chris Allen quoted - `std::ptr::NonNull<T>`. Mirror this shape for every raw pointer, raw slice, raw transmute, or uninit memory operation in your own code.
+
+```rust
+use core::marker::PhantomData;
+use core::ptr::NonNull;
+
+/// A non-null, properly aligned, initialized pointer that does not alias.
+///
+/// All invariants are upheld by [`Self::new`] (checked) or [`Self::new_unchecked`]
+/// (delegated to the caller's contract). Once you hold an `InitPtr<T>`, every
+/// public method on it is safe to call.
+#[derive(Debug)]
+#[repr(transparent)]
+pub struct InitPtr<T> {
+    inner: NonNull<T>,
+    _marker: PhantomData<T>,
+}
+
+// Send/Sync are NOT automatic for raw-pointer-bearing types. Decide deliberately.
+// SAFETY: `InitPtr<T>` owns no concurrency state of its own; whether it is
+// Send/Sync depends on `T`. The bounds below mirror `Box<T>`.
+unsafe impl<T: Send> Send for InitPtr<T> {}
+unsafe impl<T: Sync> Sync for InitPtr<T> {}
+
+impl<T> InitPtr<T> {
+    /// Wrap a raw pointer after checking alignment and non-null. The
+    /// initialization invariant is not statically checkable here; callers must
+    /// only feed pointers to memory that was written before this call.
+    pub fn new(ptr: *mut T) -> Option<Self> {
+        if !ptr.is_aligned() {
+            return None;
+        }
+        // SAFETY: alignment checked above; `NonNull::new` filters null. The
+        // caller is documented to provide an initialized location.
+        NonNull::new(ptr).map(|inner| Self { inner, _marker: PhantomData })
+    }
+
+    /// Wrap a raw pointer the caller asserts is valid.
+    ///
+    /// # Safety
+    ///
+    /// - `ptr` is non-null.
+    /// - `ptr` is aligned to `align_of::<T>()`.
+    /// - `*ptr` is initialized at the time of this call.
+    /// - For the lifetime of the returned value, no other `&T` or `&mut T`
+    ///   aliases `*ptr`.
+    pub unsafe fn new_unchecked(ptr: *mut T) -> Self {
+        // SAFETY: caller upholds non-null per the function contract.
+        Self { inner: unsafe { NonNull::new_unchecked(ptr) }, _marker: PhantomData }
+    }
+
+    pub fn as_ref(&self) -> &T {
+        // SAFETY: the constructor's invariants guarantee `inner` points at an
+        // initialized, aligned, non-aliased `T`. Reborrowing through `&self`
+        // ties the resulting lifetime to `self`, enforcing the rest via
+        // standard borrow rules.
+        unsafe { self.inner.as_ref() }
+    }
+
+    pub fn as_mut(&mut self) -> &mut T {
+        // SAFETY: `&mut self` proves no other reference can alias `inner` for
+        // the lifetime of the returned `&mut T`; remaining invariants come
+        // from construction.
+        unsafe { self.inner.as_mut() }
+    }
+}
+```
+
+The list of features this single shape gives you:
+
+- The agent cannot construct `InitPtr<T>` without going through a checked path or accepting the `unsafe` obligation explicitly.
+- The agent cannot leak the raw pointer; `as_ref` / `as_mut` return safe references with proper lifetimes.
+- The agent cannot accidentally Send/Sync where it shouldn't - the `unsafe impl` is explicit per-bound.
+- `#[repr(transparent)]` means the type is layout-compatible with `*mut T` for FFI, without exposing the raw pointer.
+
+## SAFETY Comment Grammar
+
+Every comment maps one-to-one to an invariant. Format:
+
+```rust
+// SAFETY: <which invariant is upheld>: <how it is established here>.
+```
+
+Anti-examples (do not pass review):
+
+```rust
+// SAFETY: this is fine
+// SAFETY: we know what we're doing
+// SAFETY: the caller will not pass null
+// SAFETY: tested
+```
+
+Good examples:
+
+```rust
+// SAFETY: `len <= self.capacity` was checked at line 87 and `self.ptr` was
+// allocated by the same allocator we are reading through.
+
+// SAFETY: `read_volatile` requires alignment and non-null; both hold because
+// `self.inner` is an `InitPtr<T>` whose constructor enforced them.
+
+// SAFETY: We hold `&mut self`, so no concurrent reader exists. The slice
+// reference is dropped before the next `&self` borrow because we shrink the
+// returned scope manually.
+```
+
+## Persistent Memory Arena Pattern (the Chris Allen example)
+
+A persistent memory arena (PMA) is an `mmap`-backed bump allocator that survives process restarts. It is the classic "lots of unsafe under one safe surface" project.
+
+Shape:
+
+```rust
+pub struct Arena {
+    map: Mmap,          // wraps `mmap(2)` - safe wrapper from `memmap2` crate
+    head: AtomicUsize,  // current bump offset, atomic for multi-writer if needed
+}
+
+impl Arena {
+    pub fn open(path: &Path, capacity: usize) -> std::io::Result<Self> { /* mmap, init header */ }
+
+    pub fn alloc<T>(&self, value: T) -> Result<Handle<T>, ArenaFull> {
+        let layout = Layout::new::<T>();
+        let aligned = align_up(self.head.load(Acquire), layout.align());
+        let next = aligned.checked_add(layout.size()).ok_or(ArenaFull)?;
+        if next > self.map.len() { return Err(ArenaFull); }
+        // CAS the head forward; retry on contention.
+        // ... omitted for brevity ...
+
+        // SAFETY: `aligned + layout.size() <= self.map.len()` was just proven.
+        // The mmap region is exclusively owned by this arena while we hold the
+        // bump. `aligned` is aligned to `layout.align()` by `align_up`. No
+        // other writer can have observed this offset because the CAS above
+        // returned `Ok`.
+        let ptr = unsafe { self.map.as_mut_ptr().add(aligned) as *mut T };
+        // SAFETY: `ptr` is non-null (mmap base + offset), aligned (above),
+        // exclusively owned (CAS), and we are about to initialize it.
+        unsafe { ptr::write(ptr, value) };
+
+        // SAFETY: same invariants; we wrap the now-initialized pointer in the
+        // safe handle which encapsulates further accesses.
+        Ok(unsafe { Handle::new_unchecked(ptr, self) })
+    }
+}
+
+pub struct Handle<'a, T> {
+    inner: InitPtr<T>,
+    _arena: PhantomData<&'a Arena>,
+}
+```
+
+Three `unsafe` blocks, three SAFETY comments, one safe handle type emerging on the other side. The agent now uses `Handle<T>` everywhere - never `*mut T`.
+
+## Miri Invocation
+
+```bash
+# install once
+rustup install nightly
+rustup component add miri rust-src --toolchain nightly
+
+# run on every change that touches unsafe
+MIRIFLAGS="-Zmiri-strict-provenance -Zmiri-symbolic-alignment-check" \
+  cargo +nightly miri nextest run --all-features
+```
+
+What miri catches that the borrow checker cannot:
+
+- Use-after-free
+- Double-free
+- Reads of uninitialized memory
+- Pointer-from-integer reconstruction that violates strict provenance
+- Alignment lies (transmuting unaligned data)
+- Stacked borrows / Tree borrows aliasing violations
+- Data races (single-threaded model, but catches concurrent access through `UnsafeCell` misuse)
+- Atomic ordering bugs in some patterns
+- Memory leaks (with `-Zmiri-track-pointer-tag`)
+
+## When Miri Cannot Run
+
+Certain paths are off-limits for miri: most syscalls beyond a curated allowlist, real network I/O, `std::process` calls, OS-specific FFI, hardware-dependent intrinsics on non-x86. Strategy:
+
+1. **Isolate.** Put the un-mirifiable code in its own module behind `#[cfg(feature = "ffi-real")]` or similar.
+2. **Mock at the boundary.** For everything below the FFI boundary, write a safe Rust fake (a `Vec<u8>`-backed "disk", a fake clock, an in-memory socket pair). Expose it as a trait the production code consumes.
+3. **Test the fake under miri.** The fake implementation exercises the same logic minus the syscall. If the logic is unsafe (raw pointer manipulation in the fake "disk" buffer), miri catches the bug.
+4. **Test the real path under regular `cargo test`.** With `cargo nextest run --features ffi-real`. No miri, but the surface area is now just the syscall boundary.
+5. **Document.** A `# Safety` section in the rustdoc names the obligations the FFI puts on us, and a `# Testing` section explains the mock-vs-real split.
+
+## Loom for Concurrency
+
+When `unsafe` participates in a concurrent algorithm (lock-free queue, hazard pointers, custom Arc), miri's single-thread model is insufficient. Use `loom`:
+
+```rust
+#[cfg(loom)]
+use loom::sync::atomic::{AtomicUsize, Ordering};
+#[cfg(not(loom))]
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    #[cfg(loom)]
+    fn concurrent_push_pop() {
+        loom::model(|| {
+            let queue = std::sync::Arc::new(MyQueue::new());
+            let q1 = queue.clone();
+            let q2 = queue.clone();
+            let h1 = loom::thread::spawn(move || q1.push(1));
+            let h2 = loom::thread::spawn(move || q2.pop());
+            h1.join().unwrap();
+            h2.join().unwrap();
+        });
+    }
+}
+```
+
+Run: `RUSTFLAGS="--cfg loom" cargo test --release`. Loom exhaustively explores thread interleavings for the test scope. Combined with miri on the single-thread paths, you have machine-checked soundness over the full state space.
+
+## The Forbidden List
+
+Reject in code review, automatic CI fail:
+
+- `unsafe { ... }` with no SAFETY comment within 5 lines above.
+- `unsafe { unsafe_op_a(); unsafe_op_b(); }` (multiple unsafe ops in one block - split them, one SAFETY each). Clippy: `multiple_unsafe_ops_per_block`.
+- `unsafe fn` exposed publicly without a documented `# Safety` section in rustdoc.
+- `std::mem::transmute` for anything but lifetime extension on the same layout (and that should usually be `core::mem::transmute_copy` or `bytemuck::cast` if the relayout is well-defined).
+- `std::ptr::read_unaligned` / `write_unaligned` without a comment explaining why aligned access is impossible.
+- `from_raw_parts` / `from_raw_parts_mut` without proving the source pointer's provenance covers the entire slice.
+- `Arc::get_mut_unchecked`, `Box::leak` to bypass ownership, `MaybeUninit::assume_init` on partially-initialized data.
+- `unsafe impl Send`, `unsafe impl Sync` on types containing raw pointers, without a comment naming exactly which interior-mutability rule is upheld.
+- Any `unsafe` block whose justification depends on "in practice this never happens".
+
+## The One-Line Summary
+
+> Wrap once. Prove once. Test under miri. Never let `unsafe` escape.