Rust Unsafe Boundaries
Testing & Qualityrust-unsafe-boundariesRust Unsafe Boundaries is an Agent Skill for testing & quality published in the hashgraph-online/awesome-codex-plugins repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Isolate and review unsafe Rust behind small, documented, testable boundaries with explicit invariants. Use when writing, refactoring, or reviewing unsafe code, raw pointers, unsafe functions, unsafe traits, MaybeUninit, pointer aliasing, panic safety, Miri checks, or safe abstractions over unsafe internals.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/hashgraph-online/awesome-codex-plugins/blob/HEAD/plugins/LVTD-LLC/skills/skills/rust-unsafe-boundaries/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/rust-unsafe-boundaries, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Rust Unsafe Boundaries
Use this skill to isolate unsafe Rust behind small, documented, testable boundaries. Unsafe code is acceptable only when a safe API cannot express the needed operation with acceptable correctness and performance.
Core Workflow
- Try the safe design first. Check standard APIs, ownership restructuring, iterators, synchronization primitives, and existing crates.
- State the invariant that safe Rust cannot prove. If the invariant cannot be written down, do not write unsafe code yet.
- Keep unsafe blocks tiny. Put runtime checks and setup in safe code before the block.
- Add a
// SAFETY:comment immediately before each unsafe block explaining why every unsafe operation inside is valid. - Mark a function
unsafe fnonly when callers must uphold extra conditions. Document those conditions in a# Safetysection. - Enable or respect
unsafe_op_in_unsafe_fn; unsafe operations inside unsafe functions should still be wrapped in explicit unsafe blocks. - Test normal behavior, boundary cases, panic paths, and drop behavior. Run Miri when the project supports it.
Boundary Rules
Read references/safety-invariants.md before adding or approving unsafe code.
- Prefer private unsafe internals plus a safe public wrapper.
- Prefer
MaybeUninit<T>over deprecated or ad hoc uninitialized memory patterns. - Never create references from raw pointers unless validity, alignment, initialization, aliasing, and lifetime are all proven.
- Do not use
set_len, pointer arithmetic, orfrom_raw_partswithout proving capacity, initialization, and ownership. - Make panic safety explicit when partially initialized values, manual drops, or length changes are involved.
- Avoid
static mut; preferOnceLock,LazyLock, atomics, or locked state.
Documentation Pattern
/// # Safety
///
/// `ptr` must be non-null, aligned for `T`, initialized, and valid for reads
/// for the returned lifetime. No mutable reference may alias the same value.
pub unsafe fn read_ref<'a, T>(ptr: *const T) -> &'a T {
// SAFETY: The caller guarantees `ptr` satisfies the documented contract.
unsafe { &*ptr }
}
Review Checklist
- Every unsafe block has a local
SAFETYexplanation. - Every
unsafe fnor unsafe trait has a# Safetycontract. - Public safe APIs cannot be used to violate internal invariants.
- Drop, panic, and early-return paths preserve initialization and ownership.
- Tests or Miri cover the dangerous edge, not only the happy path.