Rust Unsafe Review skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Rust Unsafe Review"
  short_description: "Prove every unsafe block or flag it"
  default_prompt: "$rust-unsafe-review Review the unsafe blocks in this ring buffer for soundness"

# Unsafe Rust patterns: wrong and right

Read the section that matches the code under review. Each pattern states the bug, a
correct version, and the safe alternative to suggest first.

## 1. Writing into spare capacity

Wrong: exposes uninitialised elements, and a panic in `produce` leaves `len` too large.

```rust
let mut v: Vec<T> = Vec::with_capacity(n);
unsafe { v.set_len(n); }
for i in 0..n { v[i] = produce(i); }   // drops uninitialised "old" values on assignment
```

Right: write through raw pointers or `spare_capacity_mut`, then set the length once.

```rust
let mut v: Vec<T> = Vec::with_capacity(n);
for (i, slot) in v.spare_capacity_mut()[..n].iter_mut().enumerate() {
    slot.write(produce(i));            // a panic here leaks written items but is sound
}
// SAFETY: the loop above initialised exactly n elements; n <= capacity.
unsafe { v.set_len(n); }
```

Safe alternative: `(0..n).map(produce).collect::<Vec<_>>()` is usually as fast.

## 2. Arrays of MaybeUninit

```rust
use std::mem::MaybeUninit;

let mut buf: [MaybeUninit<u32>; 16] = [const { MaybeUninit::uninit() }; 16];
for (i, slot) in buf.iter_mut().enumerate() { slot.write(i as u32 * 2); }
// SAFETY: all 16 slots were written above.
let buf: [u32; 16] = unsafe { std::mem::transmute(buf) };
```

Safe alternative: `std::array::from_fn(|i| i as u32 * 2)`.

Never call `MaybeUninit::<T>::uninit().assume_init()` for any `T` with validity
invariants (`bool`, `char`, enums, references, `NonZero*`, `Box`): instant UB even if the
value is never read.

## 3. Aliasing through raw pointers

Wrong: two `&mut` exist at once, even if used one after the other.

```rust
let a = unsafe { &mut *p };
let b = unsafe { &mut *p };   // invalidates `a` under Stacked/Tree Borrows
*a += 1;
```

Right: keep raw pointers until the last moment, create one reference at a time, and derive
field pointers without intermediate references.

```rust
// SAFETY: p is valid and unaliased for this scope (see constructor invariant).
unsafe {
    let len_ptr = &raw mut (*p).len;        // no &mut to the whole struct
    *len_ptr += 1;
}
```

`addr_of!`/`addr_of_mut!` are the pre-1.82 equivalents of `&raw const`/`&raw mut`.

## 4. Reinterpreting bytes

Wrong:

```rust
let words: &[u32] = unsafe { std::slice::from_raw_parts(bytes.as_ptr() as *const u32, bytes.len() / 4) };
// misaligned when bytes.as_ptr() is not 4-aligned; endianness implicit
```

Right (no unsafe):

```rust
let words: Vec<u32> = bytes.chunks_exact(4).map(|c| u32::from_le_bytes(c.try_into().unwrap())).collect();
```

Zero-copy when the data is aligned: `bytemuck::try_cast_slice::<u8, u32>(bytes)` returns an
error instead of UB; types need `#[derive(Pod, Zeroable)]`. `zerocopy` offers the same with
derive-checked layouts.

## 5. Box and raw ownership round trips

```rust
let raw: *mut State = Box::into_raw(Box::new(State::default()));
// hand `raw` to C as `void *user_data`
// ... later, exactly once:
// SAFETY: raw came from Box::into_raw above and C returns it only in the destroy callback,
// which runs at most once.
let state: Box<State> = unsafe { Box::from_raw(raw) };
```

Check for: `from_raw` called twice (double free), called on a pointer C allocated, or never
called (leak). Document who owns the pointer at each stage.

## 6. Send and Sync for wrappers

```rust
pub struct Handle { ptr: NonNull<ffi::ctx> }
// Without these lines Handle is neither Send nor Sync (raw pointers are !Send + !Sync).

// SAFETY: libfoo documents that a ctx may be used from any thread, but not concurrently.
unsafe impl Send for Handle {}
// Do NOT add Sync: concurrent &Handle calls would race inside libfoo.
```

Generic wrappers must bound `T`: `unsafe impl<T: Send> Send for Channel<T> {}`, and for
Sync usually `T: Send` (values move between threads) and sometimes `T: Sync` (shared refs
handed out).

## 7. Pinning and self-references

`Pin<&mut Self>` methods that call `get_unchecked_mut` must never move fields that are
pointed to, including via `mem::swap`, `mem::replace` or `Option::take` of the pinned
field. `Drop` for a `!Unpin` type gets `&mut self`; treat it as pinned. Prefer
`pin-project-lite` for projections instead of hand-written unsafe.

## 8. FFI signatures and strings

```rust
use core::ffi::{c_char, c_int};
use std::ffi::{CStr, CString};

unsafe extern "C" {                      // Rust 2024 syntax; plain `extern "C"` before
    fn foo_open(path: *const c_char, out: *mut *mut FooCtx) -> c_int;
    fn foo_last_error(ctx: *const FooCtx) -> *const c_char;
    fn foo_close(ctx: *mut FooCtx);
}

pub fn open(path: &str) -> Result<Handle, FooError> {
    let c_path = CString::new(path).map_err(|_| FooError::InteriorNul)?;
    let mut ctx = std::ptr::null_mut();
    // SAFETY: c_path is a valid NUL-terminated string alive for the call; ctx is a valid
    // out-pointer; foo_open does not retain path (documented in foo.h).
    let rc = unsafe { foo_open(c_path.as_ptr(), &mut ctx) };
    if rc != 0 || ctx.is_null() {
        return Err(FooError::Open(rc));
    }
    Ok(Handle { ptr: NonNull::new(ctx).expect("checked non-null above") })
}

impl Drop for Handle {
    fn drop(&mut self) {
        // SAFETY: ptr came from foo_open and is closed exactly once here.
        unsafe { foo_close(self.ptr.as_ptr()) }
    }
}

fn last_error(h: &Handle) -> String {
    // SAFETY: foo_last_error returns a NUL-terminated string owned by ctx, valid until the
    // next call on ctx; we copy it immediately.
    unsafe {
        let p = foo_last_error(h.ptr.as_ptr());
        if p.is_null() { return String::new(); }
        CStr::from_ptr(p).to_string_lossy().into_owned()
    }
}
```

Classic bug: `CString::new(path).unwrap().as_ptr()` in one expression. The CString is a
temporary dropped at the end of the statement, leaving a dangling pointer.

## 9. Callbacks from C

```rust
extern "C" fn on_event(user_data: *mut c_void, code: c_int) -> c_int {
    let result = std::panic::catch_unwind(|| {
        // SAFETY: user_data is the Box<State> pointer registered in subscribe(), alive
        // until unsubscribe() which first deregisters this callback.
        let state = unsafe { &*(user_data as *const State) };
        state.handle(code)
    });
    match result { Ok(Ok(())) => 0, _ => -1 }
}
```

Check that the C side cannot call the callback after the Rust state is freed, and that it
is not called concurrently unless `State: Sync`.

## 10. Global mutable state

`static mut` plus references is denied in Rust 2024 and UB-prone in all editions. Replace
with `static X: AtomicU64`, `static CONFIG: OnceLock<Config>`, `LazyLock` (1.80+), or a
`Mutex` in a `static`. If `static mut` must remain (FFI symbol), access it only through
`&raw const X` / `&raw mut X` and document the synchronisation.

## Severity heuristics

- A safe public function that can produce UB with any input: unsound, block release.
- Unsafe code relying on a caller-maintained invariant that is not part of an `unsafe fn`
  contract: unsound.
- Correct code with a missing or vague SAFETY comment: hardening, but require the comment
  before merge, since the next editor cannot see the proof.