Status: as of 2026-11-11. Numbers below are generated by tools/unsafe/inventory.py
(a real Rust lexer, not grep: comments, strings, raw strings and lifetimes are handled) and committed as
docs/trust/unsafe-inventory.json. Re-run tools/unsafe/check.sh to regenerate.
The numbers
| scope | constructs | with SAFETY | % |
|---|---|---|---|
| all first-party | 247 | 241 | 97.6 |
| production code | 178 | 176 | 98.9 |
| tests, benches, examples | 69 | 65 | 94.2 |
Plus 97 #[unsafe(no_mangle)] attributes and unsafe fn(..) pointer types, counted separately. Kinds: block 157, extern 10, fn 69, impl 11.
Six constructs are still reported as undocumented by the lexer heuristic although a SAFETY comment sits directly above the statement: four one-line allocator wrappers in benchmarks/native_mixed_profile/main.rs (comment above the line, block on the same line) and two in native/runtime/src/lib.rs where the block is inside a larger expression. They are left in the count rather than hidden.
"Construct" means one unsafe block, unsafe fn, unsafe impl, unsafe trait or unsafe extern block.
#[unsafe(no_mangle)] attributes and unsafe fn(..) pointer types are counted separately because they carry no
per-site proof obligation. "Documented" means a // SAFETY: comment (or a # Safety doc section for an unsafe fn)
sits on the construct, or an unsafe fn is a method of an unsafe impl Trait whose own comment discharges the trait
contract. The inventory skips docs/ (archived experiment snapshots and qualification probes: not shipped code) and
counts benchmarks/ and tests/ as "tests, benches, examples".
Before this work: 90 of 238 constructs documented (37.8%), 50.6% of production constructs. After: 241 of 247 (97.6%), 98.9% of production constructs.
By category (production code)
| category | constructs | with SAFETY | % |
|---|---|---|---|
| ffi-c-abi | 117 | 117 | 100.0 |
| other | 25 | 23 | 92.0 |
| raw-pointers-buffers | 35 | 35 | 100.0 |
| unsafe-impl-send-sync | 1 | 1 | 100.0 |
By crate
| crate | path | constructs | production | % documented |
|---|---|---|---|---|
| benchmarks | benchmarks | 43 | 0 | 90.7 |
| aster-fuzz-native | fuzz/native | 3 | 3 | 100.0 |
| aster-runtime | native/runtime | 49 | 38 | 95.9 |
| aster-ui-host | native/ui-host | 9 | 9 | 100.0 |
| hudlife-android | rust/crates/hudlife-android | 47 | 47 | 100.0 |
| hudlife-lab | rust/crates/hudlife-lab | 19 | 12 | 100.0 |
| hudlife-win32 | rust/crates/hudlife-win32 | 25 | 24 | 100.0 |
| tv-android | rust/crates/tv-android | 7 | 7 | 100.0 |
| tools | tools | 9 | 9 | 100.0 |
| store-update-profile | tools/store-update-profile | 9 | 9 | 100.0 |
| aster-web | web/aster-web | 27 | 20 | 100.0 |
The full per-module table is in tools/unsafe/inventory-latest.md; every single site (file, line, kind, category,
documented or not) is in docs/trust/unsafe-inventory.json.
Vendored crates (reported separately)
89556 unsafe constructs in 110 vendored crates (58 vendored crates have none). Top entries:
| source tree | crate | version | unsafe | well-known |
|---|---|---|---|---|
| gpu/vendor | windows | 0.62.2 | 15618 | yes |
| rust/vendor | windows-sys | 0.61.2 | 14917 | yes |
| gpu/vendor | objc2-foundation | 0.3.2 | 14398 | |
| gpu/vendor | ash | 0.38.0+1.3.281 | 8788 | yes |
| gpu/vendor | objc2-metal | 0.3.2 | 7122 | |
| gpu/vendor | objc2-core-foundation | 0.3.2 | 3102 | |
| gpu/vendor | ndk-sys | 0.6.0+11769913 | 2921 | |
| gpu/vendor | glow | 0.17.0 | 2666 | |
| gpu/vendor | wgpu-hal | 30.0.1 | 2640 | yes |
| gpu/vendor | objc2-core-graphics | 0.3.2 | 1787 | |
| gpu/vendor | objc2-quartz-core | 0.3.2 | 1600 | |
| gpu/vendor | objc2 | 0.6.5 | 1170 | |
| gpu/vendor | tokio | 1.54.1 | 1153 | |
| gpu/vendor | zerocopy-derive | 0.8.63 | 818 | |
| gpu/vendor | libc | 0.2.191 | 798 | yes |
| gpu/vendor | hashbrown | 0.17.1 | 785 | yes |
| gpu/vendor | portable-atomic | 1.15.0 | 628 | |
| gpu/vendor | zerocopy | 0.8.63 | 601 | yes |
| gpu/vendor | wgpu-core | 30.0.1 | 550 | yes |
| gpu/vendor | jni-sys | 0.3.1 | 481 | |
| rust/vendor | jni-sys | 0.3.1 | 481 | |
| gpu/vendor | spirv | 0.4.0+sdk-1.4.341.0 | 414 | |
| gpu/vendor | bytemuck | 1.25.2 | 339 | yes |
| rust/vendor | bytemuck | 1.25.2 | 339 | yes |
| rust/vendor | memchr | 2.8.3 | 333 | yes |
These are third-party crates compiled from rust/vendor and gpu/vendor. They are not reviewed line by line by us.
well-known marks widely used ecosystem crates; it is a statement about their popularity, not a claim that we audited
them. Large counts for windows, windows-sys and the objc2-* family are machine-generated platform bindings
(every foreign function is declared unsafe), not hand-written logic. Supply-chain review of the vendored set (SBOM,
licenses, cargo vet/cargo deny) is the subject of docs/trust/SUPPLY-CHAIN.md.
Where unsafe is allowed
Aster's rendering core has no unsafe code. rust/Cargo.toml sets [workspace.lints.rust] unsafe_code = "forbid" and
aster-ui, hudlife-core, hudlife-cpu, hudlife-opentype, aster-appkit, aster-blueprint and
tv-gallery inherit it ([lints] workspace = true), so the compiler rejects any unsafe there, including
inside macros and #[allow] attempts (forbid cannot be overridden by an inner attribute).
Unsafe is allowed only at the operating-system and language boundaries, each in its own crate or module:
| boundary | crate / module | why it needs unsafe |
|---|---|---|
C ABI of the runtime (aster.h) | native/runtime | the exported extern "C" functions take raw pointers from foreign callers |
| Windows window and clipboard | rust/crates/hudlife-win32, native/ui-host/src/win32_clipboard.rs | Win32 calls are foreign functions |
| Android surface and JNI | rust/crates/hudlife-android, rust/crates/tv-android | NDK ANativeWindow and JNI are foreign functions |
| WebAssembly ABI and allocator | web/aster-web | the page calls exported C functions with raw pointers; the wasm global allocator is a GlobalAlloc |
| allocation counters | rust/crates/hudlife-lab, benchmarks/, tools/store-update-profile, tools/state-compat-check | a counting GlobalAlloc wrapper for measuring allocations; not part of the shipped renderer |
Anywhere else, adding unsafe needs a design note in the pull request, a forbid-compatible alternative considered
first, and review by a second person.
Rules
- Every unsafe construct has a
// SAFETY:comment that states the actual invariant: which pointer is valid and why, which thread owns it, what the caller promised. "Safe because we checked" is not enough. For anunsafe fnthe same content goes in a# Safetyrustdoc section. unsafe_op_in_unsafe_fn = "deny": anunsafe fndoes not grant unsafe context to its body, so every operation inside still gets its own block and its own comment. Set in the Cargo.toml of every crate with first-party unsafe.clippy::undocumented_unsafe_blocks = "deny"in the Cargo.toml of every crate with first-party unsafe:native/runtime,native/ui-host,hudlife-android,hudlife-win32,hudlife-lab,tv-android,aster-web. A new block without a comment fails clippy.- Review. A change that adds or modifies an unsafe construct needs a second reviewer who reads the SAFETY comment against the code. The reviewer's question is "is the invariant true at every call site", not "does it run".
- Keep the surface small. Wrap each foreign API once in a safe type (
AndroidSurface,Window,AsterApp) so callers never writeunsafe; preferforbid(unsafe_code)in the crate that uses the wrapper. - Test the boundary. Unsafe code gets tests that run under Miri where possible and fuzz targets for anything
that parses untrusted input (see
docs/trust/FUZZING.md).
Justification per category
- FFI / C ABI. Foreign code cannot be expressed in safe Rust. The C ABI functions are the product's public
interface, so they check every argument they can (NULL, UTF-8, owner thread, not freed mid-call) and refuse
instead of crashing; each remaining obligation is written into the function's
# Safetysection. A caught panic is turned into an error string at the boundary (nothing unwinds acrossextern "C"). - Raw pointers and buffers. Used where an API hands us memory: the wasm allocator (free lists inside 64 KiB chunks),
the Android locked buffer,
Vec::from_raw_partspairs for strings the page writes. Each is bounded by an explicit length that the code checks first. unsafe impl Send/Sync. One occurrence in shipped code: the wasm allocator, justified becausewasm32-unknown-unknownhas no threads.- SIMD / intrinsics. None. The CPU rasteriser is portable safe Rust, which keeps
forbid(unsafe_code)on the renderer and makes output byte-identical across machines. - Other. Mostly the test-only
GlobalAlloccounters (forward unchanged toSystem) and#[unsafe(no_mangle)].
What this work changed
- Added the inventory tool and the snapshot; added
// SAFETY:/# Safetydocumentation to every undocumented site after reading each one (about 150 sites, no behaviour change). Comments state the real invariant, e.g. the ownership rule behindaster_app_free, whyaw_freerebuilds aVecwith capacitylen.max(1), and why the mockANativeWindowpointer is never dereferenced. - Added
undocumented_unsafe_blocksandunsafe_op_in_unsafe_fnasdenyin the seven crates above. - Added a host test,
alloc::tests::small_allocator_honours_the_global_alloc_contract, that drives the wasm small-block allocator through alignment, non-overlap,realloccontent preservation and reuse; it passes natively and is the unit to run under Miri.
Findings while reading the blocks
No block was found whose stated invariant is false. Two assumptions worth knowing, neither a bug today:
aw_alloc/aw_free(web/aster-web/src/abi.rs):aw_freerebuilds aVecwith capacitylen.max(1), which equals the allocation size only becauseVec::<u8>::with_capacity(n)allocates exactlynbytes in today's standard library (the documentation promises "at least"). Switchingaw_allocto a boxed slice would make this exact by construction. Left unchanged: it is wasm-only ABI code and the fix changes the ABI helpers.Small::reallocfalls back to the old layout whenLayout::from_size_align(new, align)fails. That path is unreachable for callers that honour theGlobalAlloc::realloccontract (the rounded size fitsisize).
Crates that could be forbid(unsafe_code)
Crates with zero first-party unsafe (from the inventory): aster-fuzz-core, aster-gpu, aster-native-dashboard, aster-host-winit, aster-appkit, aster-blueprint, aster-ui, hudlife-core, hudlife-cpu, hudlife-opentype, tv-gallery, aster-app-bundle, aster-blueprint-native, aster-blueprint-profile, fill-throughput-profile, aster-iterate, pointer-invalidation-profile, raster-worker-profile, aster-resize-profile, scaled-image-profile, scene-profile, text-policy-parity, text-prepare-profile, text-scratch-profile, vector-preflight-profile.
Those in rust/ already inherit forbid. The others (aster-gpu, aster-native-dashboard, the tools/*-profile
crates) have no unsafe today but no forbid yet. Adding [lints.rust] unsafe_code = "forbid" to them is a one-line
change per crate; it was not done in this work because the verifying build (compile + clippy + tests) was stopped to
free the build host (below). It is the first follow-up.
Miri
Plan: run cargo +nightly miri test (image aster-unsafe-tools:L2, nightly 1.102 with Miri) over the tests that
exercise unsafe paths: hudlife-android (mock ANativeWindow tests), the aster-web allocator test, the
hudlife-lab allocator probes, and the allocation-free parts of native/runtime (JSON/Markdown and the C ABI tests that
do not render).
Status: not run. The builds were stopped on purpose (see below), so there are no Miri results yet. The expected per-group status is recorded here once run; until then nothing is claimed.
| test group | crate | Miri status |
|---|---|---|
| mock NDK surface tests | hudlife-android | not run |
| small-block allocator | aster-web | not run (native run passes) |
| counting allocator probes | hudlife-lab | not run |
| C ABI, no-render subset | aster-runtime | not run |
Verification status (honest)
- Inventory: ran on the final tree (numbers above).
- Native test runs that did finish:
hudlife-android+hudlife-lablib tests pass;aster-weballocator tests (2) pass; thefuzz/coreregression replay passes (all committed seeds);x86_64-pc-windows-gnuclippy ofhudlife-win32is clean withundocumented_unsafe_blocks = deny. - The full clippy pass was interrupted on purpose (2026-11-11) before it finished. In the part that completed, no
undocumented_unsafe_blocks,missing_safety_docorunsafe_op_in_unsafe_fnfinding was reported for any crate. Plainclippy -D warningsdoes fail inaster-blueprint,aster-runtimeandaster-webon code unrelated to this work (unused variables,neg_cmp_op_on_partial_ord,is_multiple_ofsuggestions, an ambiguous glob import inhudlife-lab/tests/facade_plugins.rs); those were present before this branch and were not touched here. fuzz/nativeregression replay was interrupted with the clippy pass;fuzz/nativecompiles (27 minutes under load).
How to re-run
tools/unsafe/inventory.py --json docs/trust/unsafe-inventory.json --md tools/unsafe/inventory-latest.md
tools/unsafe/check.sh # inventory + clippy lint + fuzz replay + short fuzz smoke; writes a summary JSON