Code assurance

Unsafe code policy and inventory

In reviewUpdated 2026-11-15Trust Center

In review. This record, and the tools and files it cites, are on a review branch. They are not in the main source tree yet, so you cannot check them in a copy of the main source today.

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

scopeconstructswith SAFETY%
all first-party24724197.6
production code17817698.9
tests, benches, examples696594.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)

categoryconstructswith SAFETY%
ffi-c-abi117117100.0
other252392.0
raw-pointers-buffers3535100.0
unsafe-impl-send-sync11100.0

By crate

cratepathconstructsproduction% documented
benchmarksbenchmarks43090.7
aster-fuzz-nativefuzz/native33100.0
aster-runtimenative/runtime493895.9
aster-ui-hostnative/ui-host99100.0
hudlife-androidrust/crates/hudlife-android4747100.0
hudlife-labrust/crates/hudlife-lab1912100.0
hudlife-win32rust/crates/hudlife-win322524100.0
tv-androidrust/crates/tv-android77100.0
toolstools99100.0
store-update-profiletools/store-update-profile99100.0
aster-webweb/aster-web2720100.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 treecrateversionunsafewell-known
gpu/vendorwindows0.62.215618yes
rust/vendorwindows-sys0.61.214917yes
gpu/vendorobjc2-foundation0.3.214398
gpu/vendorash0.38.0+1.3.2818788yes
gpu/vendorobjc2-metal0.3.27122
gpu/vendorobjc2-core-foundation0.3.23102
gpu/vendorndk-sys0.6.0+117699132921
gpu/vendorglow0.17.02666
gpu/vendorwgpu-hal30.0.12640yes
gpu/vendorobjc2-core-graphics0.3.21787
gpu/vendorobjc2-quartz-core0.3.21600
gpu/vendorobjc20.6.51170
gpu/vendortokio1.54.11153
gpu/vendorzerocopy-derive0.8.63818
gpu/vendorlibc0.2.191798yes
gpu/vendorhashbrown0.17.1785yes
gpu/vendorportable-atomic1.15.0628
gpu/vendorzerocopy0.8.63601yes
gpu/vendorwgpu-core30.0.1550yes
gpu/vendorjni-sys0.3.1481
rust/vendorjni-sys0.3.1481
gpu/vendorspirv0.4.0+sdk-1.4.341.0414
gpu/vendorbytemuck1.25.2339yes
rust/vendorbytemuck1.25.2339yes
rust/vendormemchr2.8.3333yes

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:

boundarycrate / modulewhy it needs unsafe
C ABI of the runtime (aster.h)native/runtimethe exported extern "C" functions take raw pointers from foreign callers
Windows window and clipboardrust/crates/hudlife-win32, native/ui-host/src/win32_clipboard.rsWin32 calls are foreign functions
Android surface and JNIrust/crates/hudlife-android, rust/crates/tv-androidNDK ANativeWindow and JNI are foreign functions
WebAssembly ABI and allocatorweb/aster-webthe page calls exported C functions with raw pointers; the wasm global allocator is a GlobalAlloc
allocation countersrust/crates/hudlife-lab, benchmarks/, tools/store-update-profile, tools/state-compat-checka 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

  1. 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 an unsafe fn the same content goes in a # Safety rustdoc section.
  2. unsafe_op_in_unsafe_fn = "deny": an unsafe fn does 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.
  3. 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.
  4. 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".
  5. Keep the surface small. Wrap each foreign API once in a safe type (AndroidSurface, Window, AsterApp) so callers never write unsafe; prefer forbid(unsafe_code) in the crate that uses the wrapper.
  6. 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 # Safety section. A caught panic is turned into an error string at the boundary (nothing unwinds across extern "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_parts pairs 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 because wasm32-unknown-unknown has 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 GlobalAlloc counters (forward unchanged to System) and #[unsafe(no_mangle)].

What this work changed

  • Added the inventory tool and the snapshot; added // SAFETY: / # Safety documentation to every undocumented site after reading each one (about 150 sites, no behaviour change). Comments state the real invariant, e.g. the ownership rule behind aster_app_free, why aw_free rebuilds a Vec with capacity len.max(1), and why the mock ANativeWindow pointer is never dereferenced.
  • Added undocumented_unsafe_blocks and unsafe_op_in_unsafe_fn as deny in 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, realloc content 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:

  1. aw_alloc/aw_free (web/aster-web/src/abi.rs): aw_free rebuilds a Vec with capacity len.max(1), which equals the allocation size only because Vec::<u8>::with_capacity(n) allocates exactly n bytes in today's standard library (the documentation promises "at least"). Switching aw_alloc to a boxed slice would make this exact by construction. Left unchanged: it is wasm-only ABI code and the fix changes the ABI helpers.
  2. Small::realloc falls back to the old layout when Layout::from_size_align(new, align) fails. That path is unreachable for callers that honour the GlobalAlloc::realloc contract (the rounded size fits isize).

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 groupcrateMiri status
mock NDK surface testshudlife-androidnot run
small-block allocatoraster-webnot run (native run passes)
counting allocator probeshudlife-labnot run
C ABI, no-render subsetaster-runtimenot run

Verification status (honest)

  • Inventory: ran on the final tree (numbers above).
  • Native test runs that did finish: hudlife-android + hudlife-lab lib tests pass; aster-web allocator tests (2) pass; the fuzz/core regression replay passes (all committed seeds); x86_64-pc-windows-gnu clippy of hudlife-win32 is clean with undocumented_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_doc or unsafe_op_in_unsafe_fn finding was reported for any crate. Plain clippy -D warnings does fail in aster-blueprint, aster-runtime and aster-web on code unrelated to this work (unused variables, neg_cmp_op_on_partial_ord, is_multiple_of suggestions, an ambiguous glob import in hudlife-lab/tests/facade_plugins.rs); those were present before this branch and were not touched here.
  • fuzz/native regression replay was interrupted with the clippy pass; fuzz/native compiles (27 minutes under load).

How to re-run

Shell
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

Source docs/trust/UNSAFE.mdlast changed 2026-11-15

More records

Every record in the Trust Center is public.