Rust panic safety

Start here: find the boundaries

# Every function that foreign code can call.
rg -n 'extern "(C|system|C-unwind|system-unwind)"|#\[jni_mangle|native_method!' --type rust

# Every symbol that leaves the crate unmangled.
rg -n '#\[unsafe\(no_mangle\)\]|#\[no_mangle\]|#\[export_name|#\[unsafe\(export_name' --type rust

# Every guard that already exists.
rg -n 'catch_unwind|AssertUnwindSafe|with_env' --type rust

# Every panic strategy declared in the tree: manifests, config files, and rustflags.
rg -n --hidden 'panic\s*=\s*"?(abort|unwind)' \
  -g '**/Cargo.toml' -g '**/.cargo/config.toml' -g '**/.cargo/config'

Compare list 1 with list 3. A native_method! entry has a generated with_env guard, unless it is raw or sets catch_unwind = false. An entry point in list 1 with no guard and no documented abort policy (Rule 1) is a finding. Derive the lists from the tree for each review; do not reuse an old count. This skill names other skills; use them when they are installed.

Verify a boundary change

Run the --print cfg check with the same --target, --profile, and environment as the shipping build. It then reflects every source of the strategy: the root manifest profile, [profile.<name>] in .cargo/config.toml, CARGO_PROFILE_<NAME>_PANIC, RUSTFLAGS, CARGO_ENCODED_RUSTFLAGS, build.rustflags, and target.<triple>.rustflags. Without --target, Cargo builds for the host and skips the rustflags of the shipping triple, so the check can print unwind for a library that ships with abort. Replace --release with --profile <name> when the shipping profile is not release. When the boundary decodes untrusted input, fuzz the decoder behind it: a guard turns each panic into a status code and hides it from every other test. See the rust-test-tools skill.

Done when

• Every inventory entry point has a guard, or a comment that states abort as its policy.
• Every extern body is a guard plus a delegation call to a testable plain Rust function.
• The --print cfg check prints panic="unwind" if any guard uses catch_unwind.
• The panic exit differs from every domain error exit.
• The boundary discards the payload through a second guard. Only a run-once loader such as JNI_OnLoad can leak it instead, with ManuallyDrop::new, never mem::forget.
• The bootstrap installs the hook once. It emits only a closed site code plus numeric location. No shipped log, exception message, or tombstone can carry user data from a panic.
• Every AssertUnwindSafe has a comment that names the invariant.
• Every crate on the FFI path denies clippy::unwrap_used and clippy::panic.
• No Drop can panic. Every spawned task or thread reports its panic at a join point or through its own guard.

Failure triage

Silent hazards

A test run rarely shows these defects.

• Treat every panic message as a log line. On Android, panic = "abort" copies a &str or String payload into the tombstone Abort message through android_set_abort_message. UniFFI copies it into the foreign exception message. Never put secrets or user data in a panic, expect, or unreachable! message.
• Result::unwrap and Result::expect append the error's Debug text. An error type on an FFI path must not carry input data in Debug, or the call must map the error before it panics.
• The JNI ThrowRuntimeExAndDefault policy copies the error's Display text and a constant panic message into the exception. Use a fixed-message policy when that text can carry input data.
• Swift calls a non-throwing UniFFI export through try!, so a panic there ends the app. Keep such exports panic-free.
• core::hint::unreachable_unchecked() with a wrong proof is undefined behaviour, not a panic. Use it only with a SAFETY comment that proves the branch is impossible.

Rule 1: decide what a panic does at each foreign entry point

Since Rust 1.81, a panic that reaches an extern "C" or extern "system" function aborts the process with panic in a function that cannot unwind. The abort is defined behaviour, and the host sees a native crash, not a Rust error. Before 1.81 the same unwind was undefined behaviour, so a crate with an MSRV below 1.81 must guard every entry point.

This skill is the catalog's single home for this policy:

• Guard with catch_unwind every entry point whose caller must get an error instead of a dead process. That is the default for a library that a host process loads: a JNI library, a plugin, a cdylib behind Swift or C.
• Leave a body unguarded only where an abort is the intended result, for example a callback in a standalone binary. Write that intent in a comment on the function.
• extern "C-unwind" lets a Rust panic or a foreign exception cross the boundary. Use it only when the other side can unwind through it, such as C++ built with exceptions. A Java, Swift, or -fno-exceptions C caller cannot.
• A foreign exception that unwinds into Rust through a function declared extern "C" is undefined behaviour. Catch a C++ exception on the C++ side, or declare the import extern "C-unwind".

Choose the panic strategy before you write the guard

• panic = "unwind" (default) keeps panics catchable; landing pads add code. Use it when a panic must be survived: a shared library inside a host process, a server that isolates a request, any FFI boundary that returns an error to the caller.
• panic = "abort" aborts at the panic site. It is smaller and marginally faster. Use it when no guard depends on catching, for example a standalone binary where a panic is a crash anyway. It silently turns every catch_unwind guard into dead code.

[profile.release]
panic = "unwind"                # required if any entry point relies on catch_unwind
overflow-checks = true          # a wrapped length becomes a panic, not a bad slice bound
debug = "line-tables-only"      # file and line when you symbolicate a backtrace offline

Rules:

• Cargo reads manifest profiles only from the workspace root. A [profile] table in a member manifest has no effect, and a per-package override cannot set panic. A config-file profile, CARGO_PROFILE_<NAME>_PANIC, and -C panic in any rustflags source override the manifest.
• Cargo ignores the panic key for tests, benchmarks, build scripts, and proc macros. A #[should_panic] test therefore runs under unwind even when release aborts. Do not read a green test run as proof that the shipped library unwinds.
• State the reason for the strategy in a comment next to the panic key.

What catch_unwind catches

std::panic::catch_unwind catches an unwinding panic that starts inside the closure, on the same thread. The panic hook runs first, before unwinding starts. It does not catch:

• A panic on another thread. Join that thread and inspect its result.
• A process abort: a panic inside a Drop during unwinding, panic in a function that cannot unwind, an unsafe precondition(s) violated check, or an allocation failure.
• A stack overflow. That is a signal, not a panic.
• A foreign exception, in any reliable way. The result is unspecified: an abort after the destructors run, or Err with an opaque payload. Do not rely on either. Catch it on the foreign side.

Do not remove a guard for speed without a benchmark that shows its cost.

Read references/unwind-state.md when the catch_unwind closure captures &mut or interior-mutable state and needs AssertUnwindSafe.

The guard pattern: hand-rolled C ABI

Return a status code, never a Result and never a panic. Reserve one code for a caught panic so the caller can tell a domain error from a bug.

pub const OK: i32 = 0;
pub const ERR_INVALID_INPUT: i32 = -1;
pub const ERR_IO: i32 = -2;
pub const ERR_PANIC: i32 = -99;

fn discard_panic_payload(payload: Box<dyn std::any::Any + Send>) {
    let second = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| drop(payload)));
    if let Err(payload) = second {
        // The destructor of the first payload panicked. Do not drop the second payload here.
        let _leaked = std::mem::ManuallyDrop::new(payload);
    }
}

/// # Safety
/// `ptr` must be non-null, aligned, writable for `len` bytes, and unaliased for
/// this call. `len` must not exceed `isize::MAX`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn lib_render(ptr: *mut u8, len: usize) -> i32 {
    if ptr.is_null() || len > isize::MAX as usize {
        return ERR_INVALID_INPUT;
    }
    let result = std::panic::catch_unwind(|| {
        // SAFETY: the caller guarantees the contract above.
        let buf = unsafe { std::slice::from_raw_parts_mut(ptr, len) };
        render_into(buf)
    });
    match result {
        Ok(Ok(())) => OK,
        Ok(Err(Error::InvalidInput)) => ERR_INVALID_INPUT,
        Ok(Err(Error::Io(_))) => ERR_IO,
        Err(payload) => {
            discard_panic_payload(payload);
            ERR_PANIC
        }
    }
}

Keep the extern body to a guard plus a delegation call. Put the logic in a plain Rust function that the tests can call directly.

The payload's destructor can panic, so discard_panic_payload drops it inside a second guard. It leaks the second payload with ManuallyDrop, a bounded leak on the double-panic path only, so no unwind leaves the boundary. Do not inspect or format either payload.

Read references/boundary-patterns.md when the entry point returns a pointer or an opaque handle, writes out-parameters, is a callback that a foreign runtime invokes, drives async work with block_on, or when the crate exports enough functions to need a macro-generated extern layer. It also holds the runnable proof of discard_panic_payload.

JNI, UniFFI, and the panic hook

Read references/hosts-hooks-and-tasks.md when the entry point is a JNI export, JNI_OnLoad, or a UniFFI export, or when you install or review the panic hook that reports a caught panic.

.unwrap() and .expect() on FFI-reachable paths

The rust-discipline skill owns the general unwrap and expect rule. On a path that a foreign caller reaches, a panic kills the host process unless a guard catches it.

Not allowed on such a path:

• .unwrap() or .expect() on a Result that input or the environment can make Err. Propagate with ? and let the boundary map the error.
• .unwrap() or .expect() on an Option whose None comes from input: parsed data, a network reply, user configuration, an environment variable, a map lookup keyed by external data.
• .expect("should never happen"). Either state the invariant in the message, or model it in the type system so the case disappears. unreachable!() keeps the panic and states the intent. For unreachable_unchecked, see Silent hazards and the rust-unsafe skill.

Deny clippy::unwrap_used, clippy::panic, clippy::todo, clippy::unimplemented, and clippy::panic_in_result_fn in every crate on an FFI path. Set clippy::expect_used and clippy::indexing_slicing to at least warn. Set them as crate-root attributes and keep [lints] workspace = true, so the crate keeps the workspace floor that the rust-lints skill owns. Read references/unwrap-audit.md when you roll these lints out or a crate already has many sites. It holds the crate-root block, the clippy.toml test exemptions (and the panic_in_result_fn case, which has none), the reachability ranking, the replacement recipes, and the #[expect] contract. Count the debt with a command, never from memory:

rg -n --type rust '\.unwrap\(\)|\.expect\(' \
  -g '!target/**' -g '!**/tests/**' -g '!**/benches/**' | wc -l

Errors at the boundary

Keep the panic exit distinct from every error exit. A panic means a bug in Rust; an error means an expected failure. If they share a code, you cannot triage the crash report. Read the typed-errors section of references/unwrap-audit.md when you design or map the error type of a crate on an FFI path.

Shared state, tasks, and threads

Read references/hosts-hooks-and-tasks.md when guarded code mutates shared state or holds a lock, or when a panic can start in a spawned task, a thread, or a future that block_on drives.