Menu
Audit unsafe blocks — verify necessity, add SAFETY comments, confirm test coverage, encapsulate in safe public API
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | unsafe-review |
| description | Audit unsafe blocks — verify necessity, add SAFETY comments, confirm test coverage, encapsulate in safe public API |
# List all unsafe in the project
grep -rn "unsafe" crates/ --include="*.rs" | grep -v "// SAFETY:"
# See full context of each unsafe
grep -rn -A 5 -B 2 "unsafe {" crates/ --include="*.rs"
Try safe alternatives first:
// Can it be solved with bytemuck?
use bytemuck::{Pod, Zeroable};
#[repr(C)]
#[derive(Pod, Zeroable, Clone, Copy)]
struct Page { ... }
let page: &Page = bytemuck::from_bytes(&bytes); // safe!
// Can it be solved with rkyv?
use rkyv::{Archive, Deserialize};
let archived = unsafe { rkyv::access_unchecked::<Page>(&bytes) };
// rkyv handles the unsafe internally with guaranteed invariants
// Can it be restructured to avoid the raw pointer?
The SAFETY comment must be specific, not generic:
// ❌ BAD — too vague
// SAFETY: it is safe
// ❌ BAD — does not explain the invariant
// SAFETY: we trust the pointer is valid
// ✅ GOOD — specific and verifiable
// SAFETY: `ptr` is valid because:
// 1. It comes from `mmap.as_ptr()` which always returns valid memory
// 2. `page_id < self.total_pages` verified at line 42
// 3. The alignment of Page (align=64) is compatible with the mmap pointer
// 4. The mmap lives as long as `StorageEngine` exists (guaranteed by Arc<Mmap>)
let page = unsafe { &*(ptr as *const Page) };
#[test]
fn test_safety_invariant_mmap_pointer() {
// Verify the unsafe is truly safe at edge cases
let storage = MmapStorage::create_temp();
// Edge case: last valid page
let last_page = storage.total_pages() - 1;
let result = storage.read_page(last_page);
assert!(result.is_ok());
// Verify it fails appropriately out of range
let result = storage.read_page(storage.total_pages());
assert!(matches!(result, Err(DbError::PageNotFound { .. })));
}
// ❌ BAD — unsafe exposed to caller
pub fn get_page_ptr(id: u64) -> *const Page { ... }
// ✅ GOOD — unsafe encapsulated, public interface is safe
pub fn read_page(&self, id: u64) -> Result<&Page, DbError> {
if id >= self.total_pages {
return Err(DbError::PageNotFound { page_id: id });
}
let ptr = self.mmap.as_ptr().add(id as usize * PAGE_SIZE);
// SAFETY: [complete invariant here]
Ok(unsafe { &*(ptr as *const Page) })
}
[ ] Did I try bytemuck/rkyv/restructuring first?
[ ] Does the SAFETY comment explain the specific invariant?
[ ] Does the comment mention why each condition holds?
[ ] Is there a test that verifies the contract at edge cases?
[ ] Does the public function have a safe signature even if it uses unsafe internally?
[ ] Did I run miri on this code?
# Verify with miri (detects UB in unsafe)
cargo +nightly miri test unsafe_test_name
Verify and fix documented gaps one at a time — reproduce, root cause, minimal fix, wire-test regression, close
Discover undocumented gaps by comparing AxiomDB against MySQL/PostgreSQL — build inventory, run tests, classify, hand off to hunt-gap
Run Criterion micro-benchmarks and 3-Docker comparison benchmarks, verify no regression against MySQL/PostgreSQL
Explore approaches before proposing — read context, ask questions, present 2+ options with trade-offs, write sprint with dependencies
Save session context to a checkpoint file so the next session can resume without losing state
Systematic debug protocol — reproduce with minimal test, 2+ hypotheses, fix root cause, add regression test