Skip to content

research: unsafe - #30

Open
si618 wants to merge 5 commits into
mainfrom
research/unsafe
Open

si618 wants to merge 5 commits into
mainfrom
research/unsafe

Conversation

@si618

@si618 si618 commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Question

What should a Rust developer know and do about unsafe: soundness, unsafe_op_in_unsafe_fn, and Miri? This is the unsafe.md topic in PLAN.md's phase 6. The topic is in research/unsafe.md.

Recommendation

Add #![forbid(unsafe_code)] to the root of every crate that has no unsafe, and justify each use in a crate that needs it. Keep each invariant in a private field so the module is the soundness boundary. Document every unsafe with // SAFETY: and # Safety: missing_safety_doc warns by default for the sections. Turning on undocumented_unsafe_blocks and the two unnecessary_safety_* lints is unsupported. Prefer &raw and the strict provenance APIs, and run cargo miri test in CI. Maturity: GA. Everything recommended is stable in 1.99.1, except Miri and cargo-careful, tools that run only on nightly.

Sources

  • What unsafe blocks and functions promise, the definition of soundness, and that no aliasing model is decided: The Rust Reference (citable, rust-docs)
  • Unsafe code pollutes a whole module, privacy contains it, and unsafe code can't trust a safe Ord: The Rustonomicon (citable, rust-docs)
  • SAFETY comments, small unsafe blocks, and running Miri on nightly: The Rust Programming Language, chapter 20.1 (citable, rust-docs)
  • unsafe_op_in_unsafe_fn warns on edition 2024: Rust Edition Guide (citable, rust-docs)
  • Clippy lint groups and defaults, and forbid versus deny with #[expect]: Clippy --explain, and the editor's probes on 1.99.1 (citable, rust-docs)
  • Strict provenance, &raw, unsafe extern, and unsafe attributes: Rust Blog 1.82 and 1.84, and std::ptr (citable, rust-blog, rust-docs)
  • The lints added in 1.88 to 1.98, the 1.93 MaybeUninit slice methods, and the 1.81 abort on unwind: the published Rust Release Notes (citable, rust-docs)
  • Safety and validity invariants, what Miri catches, -Zmiri-many-seeds, that a pass isn't a proof, and cargo-careful: Ralf Jung (citable, ralf-jung)
  • The module is the boundary, and two correct blocks can be wrong together: Alex Kladov (citable, matklad)
  • LANG-UNSAFE, LANG-UNSAFE-ENCP, FFI rules, and MEM-FORGET and MEM-LEAK: ANSSI Secure Rust Guidelines (citable, anssi-rust, whose note scopes it to security.md. Only LANG-UNSAFE-ENCP is cross-checked against rust-docs)
  • Miri in a production-hardening CI job: Matthias Endler (citable, corrode)
  • Miri in the bzip2 port, and slices removing unsafe: Tweede golf (citable, tweede-golf)
  • How to run Miri, Stacked Borrows as the default, Tree Borrows as more experimental, #[cfg_attr(miri, ignore)], and what Miri misses with exposed provenance: Miri README, with a probe on nightly 2026-10-18 (not on the roster: a reference, for reference facts about the tool)
  • M-UNSAFE, M-UNSAFE-IMPLIES-UB, M-STATIC-VERIFICATION, and Item 16: Microsoft Pragmatic Rust Guidelines, Effective Rust (watch-list, cross-check only)
  • Status of unsafe fields and unsafe binders: rust-lang/rust tracking issues (not on the roster: references)
  • Status of the sanitizers, BorrowSanitizer, and normative unsafe documentation: Rust Project Goals 2026 (unvetted)

For resolve-research

Proposed outcome: promote, without the six claims the topic marks unsupported unless a citable source turns up for them. Every other recommendation cites a roster source or a reference for a reference fact.

Target files: a new opinions/unsafe.md, with sections on when to write unsafe, encapsulation and the module boundary, documentation and the lint table, raw pointers and provenance, FFI, and Miri. README.md's Scope list and layout tree. templates/Cargo.toml gains undocumented_unsafe_blocks, unnecessary_safety_comment, and unnecessary_safety_doc in [workspace.lints.clippy] once a roster source supports them, and the unsafe_code setting once resolve-research settles it. The two unnecessary_safety_* lints fire on a // SAFETY: comment or # Safety section on safe code, in any crate. No template holds a crate root, so the forbid rule goes in the opinion only.

Blockers: none for promotion. Five decisions are for resolve-research:

  • Six claims are unsupported: a new abstraction as a fourth reason to write unsafe, which only watch-list ms-rust-guidelines allows, keeping the default aliasing model, the 0..16 seed range, turning on the three Clippy safety lints, which only watch-list ms-rust-guidelines picks, leaving out multiple_unsafe_ops_per_block, and a workspace deny over a workspace forbid.
  • Settle one unsafe_code design with security.md, which proposes a workspace forbid.
  • Rule on anssi-rust's scope, or cross-check the FFI rules, LANG-UNSAFE, and the crate-root forbid against rust-docs.
  • Confirm that an opinion may recommend Miri and cargo-careful, tools that run only on nightly. The freshness rule covers features the code uses, and the code stays on stable.
  • Rust Project Goals is a vet-source candidate. Admit it, or name it as a reference, before an opinion's Coming next note cites it.

This topic owns the Miri CI job, as the ci.md and testing.md topics say, and ci.md sets the workflow rules the job follows. ANSSI's leak rules go to security.md. None of the Coming next features shipped in 1.100.0, checked against the Rust Blog announcement on 2026-11-14. The statuses themselves date from 2026-10-19.

Checked

The topic has the metadata AGENTS.md: Metadata defines, and just verify passes. The links added on 2026-11-12 returned 200 with curl, because lychee isn't installed locally.

  • Code: the example, with its test, passes CARGO_BUILD_WARNINGS=deny cargo check --all-targets and CARGO_BUILD_WARNINGS=deny cargo clippy --all-targets on 1.99.1, and cargo +nightly miri test runs the test and passes on nightly 2026-10-18, all on 2026-11-14. It needs no crate beyond std.
  • Advisories: doesn't apply. The topic recommends no crate as a dependency, and Miri and cargo-careful are tools.
  • Claims: every claim cites a roster source or a reference for a reference fact, or is marked unsupported, as the reference-fact rule from docs: let a reference support a fact about its own crate #103 defines. A local review on 2026-11-14 found ten issues, and each is fixed except retargeting to 1.100, which waits for refresh-rust-versions to retarget the repository. A second review that day found five more, and each is fixed.

@coderabbitai

coderabbitai Bot commented Oct 19, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

No actionable comments were generated in the recent review.

Walkthrough

The PR adds a research document on Rust unsafe-code policy, soundness, tooling, and follow-up items. It also adds technical terms and names to the spelling dictionary.

Changes: Unsafe-code research and terminology

Layer / File(s) Summary
Research document and spelling entries
research/unsafe.md, cspell.words.txt
The document covers unsafe-code policy, soundness, pointer and FFI guidance, testing tools, source disagreements, and repository follow-up items. The spelling dictionary gains technical terms and names.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: Minimal · up to a8b43

This adds research guidance and spell-check vocabulary without changing runtime enforcement. The checked lint recommendation works on the documented Rust version, so no actionable merge blocker remains.

Architecture risk: Low · up to a8b43

The change affects 2 systems.

Changed systems: cspell.words.txt, research

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — cspell.words.txt (service) was modified; 1 changed file maps to changed impact.
  • observed — research (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

  • observed — Modified behavior in cspell.words.txt: Added anssi, ANSSI's, CKNONROBUST, CTYPE, ENCP, interleavings and Kani to the spelling dictionary.
  • observed — Modified behavior in cspell.words.txt: Added NODROP, NOENUM, NOPANIC, PFTYPE, PLDI and POPL to the spelling dictionary.
  • observed — Modified behavior in cspell.words.txt: Added Rustaceans, SAFEWRAPPING and tweede to the spelling dictionary.
  • observed — Modified behavior in research/unsafe.md: Added a research document covering unsafe-code policy and soundness, an encapsulated NonEmpty example, lint and pointer guidance, FFI rules, Miri and other testing tools, source disagreements, upcoming features, and repository follow-up items.
Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title clearly identifies the research topic and matches the main change in the pull request.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description check Passed The description is specific and on-topic. It states the research question (soundness, unsafe_op_in_unsafe_fn, and Miri), points to research/unsafe.md and the PLAN.md phase 6 topic, summarises the reco…
Full details: Description check

Explanation

The description is specific and on-topic. It states the research question (soundness, unsafe_op_in_unsafe_fn, and Miri), points to research/unsafe.md and the PLAN.md phase 6 topic, summarises the recommendations (forbid unsafe_code in crates without unsafe, private-field invariants, SAFETY and Safety docs, raw pointer and strict provenance APIs, cargo miri test in CI), and lists sources, the proposed outcome, and checks run. It matches the changeset, which adds research/unsafe.md and dictionary entries.

Finishing Touches

🧪 Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

ℹ️ Recent review info

⚙️ Run configuration

  • Configuration used: Repository: awesome-humans/coderabbit/.coderabbit.yaml
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 5bf9d358-215c-440b-8c68-bf23d9126545
📥 Commits

Reviewing files that changed from the base of the PR and between 0a5e575 and a8b43bf.

📒 Files selected for processing: 2

  • cspell.words.txt
  • research/unsafe.md

si618 added a commit that referenced this pull request Oct 21, 2026
## What changed

The site's Rust sidebar now leads with Awesome humans, right after the
overview, ahead of Opinions.

It also gains a Research section after Templates, with an overview and
a page per open topic in `research/`. Each topic page carries the same
metadata strip as an opinion, without the freshness chip, and opens
with a line saying it's unresolved research rather than guidance.
`llms.txt` still leaves research out, so agents follow only the
opinions.

A topic's sidebar label is its title up to the first ": ", without "in
Rust" or "for Rust", so "Unsafe: soundness, `unsafe_op_in_unsafe_fn`,
and Miri" reads as Unsafe. Its page and the research overview keep the
full title.

No topic is open on `main` yet, so the section stays hidden until the
first research pull request merges, as the other sections do when
empty. Checked with `just check`, a new case in the staging test, and a
stage of the `research/unsafe` branch with this code.

## Why

A reader should meet the people behind the opinions before the
opinions themselves. Open research shows what's being worked on and
what's blocked on a source, which today is visible only on GitHub.

Refs: #23, #24, #25, #26, #27, #28, #29, #30, #31
@si618

si618 commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor Author

The checks for research are tightening, in awesome-humans/.github#15 (the research template) and #66 (research-topic). Before this merges, re-review the topic against them, and record each one in the description's Checked section:

  • Code: every code example compiles on the declared targets with cargo check and cargo clippy -- -D warnings, with the toolchain, crate versions, and date recorded under it.
  • Advisories: every crate the topic recommends has no open security advisory at the version it names, checked with cargo deny check advisories or the RustSec Advisory Database.
  • Claims: every claim the recommendation rests on has a citable roster source, or is marked in the topic as unsupported.

Written by an agent: Claude Code, Opus 5.5.

@si618

si618 commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

Rebased on main after #103 and #104, and fixed the findings from a local review, since CodeRabbit is rate limited:

  • unsafe_op_in_unsafe_fn requires an explicit unsafe {} block around each unsafe operation, but one block can hold several. The opening list now says so.
  • The opening list leaves out the unsupported claims. The topic now marks five: two it hadn't marked are leaving out multiple_unsafe_ops_per_block and a workspace deny over forbid.
  • Under docs: let a reference support a fact about its own crate #103, #[cfg_attr(miri, ignore)] and the exposed-provenance limit are reference facts from the Miri README, so they're supported now.
  • The two unnecessary_safety_* lints fire on safe code in any crate, which a probe confirmed, so the template note no longer says they're silent.
  • The example has a test, so cargo miri test checks an execution. Clippy passes on 1.99.1, and Miri passes on nightly 2026-10-18, with the compile recorded under it.
  • Also corrected: anssi-rust's scope to security.md, cargo-careful needing nightly, which rust.md rows are new, the watch-list contradiction, and the 1.100 recheck against the Rust Blog.

Not done: retargeting to 1.100. The rest of the repository still targets 1.99, so refresh-rust-versions should retarget everything together. security.md (#29) proposes a workspace forbid where this topic proposes deny, and both topics now say so.

Written by an agent: Claude Code, Opus 5.5.

Replace "carry" with a precise verb and reword idioms, as
docs/tighten-prose does for the other topics.

Fix the ten code-review findings: this topic owns the Miri job, the
release facts cite the published release notes, a crate with no unsafe
adds forbid to its root as ANSSI requires, and four claims that no
citable source makes are marked unsupported. Rust Project Goals is
flagged as unvetted and listed as a vet-source candidate.
Under #103, #[cfg_attr(miri, ignore)] and the exposed-provenance limit
are reference facts from the Miri README. Correct what
unsafe_op_in_unsafe_fn requires and which Clippy lints fire on safe
code. Keep the unsupported claims out of the opening list, and mark the
two that weren't marked: leaving out multiple_unsafe_ops_per_block and
workspace deny over forbid, which security.md proposes the other way.
Give the example a test, so the Miri pass checks something, and record
the compile under it. Note that anssi-rust is scoped to security.md,
that cargo-careful needs nightly too, which rust.md rows are new, and
that 1.100.0 shipped none of the Coming next features.
Turning on an optional lint is a choice, and only a watch-list source
makes it, so the three Clippy safety lints leave the opening list and
become the sixth unsupported claim. Name the workspace deny claim the
same way everywhere, make the template lints wait for support, and
say that a reference fact cites a reference. Scope the Miri README's
limit to integer-to-pointer casts and with_exposed_provenance.
@si618

si618 commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

A second local review of the 2026-11-14 fix commit found five issues. 7ec1f9e fixes each:

  • Clippy safety lints: turning on undocumented_unsafe_blocks, unnecessary_safety_comment, and unnecessary_safety_doc is a choice that only watch-list ms-rust-guidelines makes. It left the opening list and is the sixth unsupported claim.
  • Workspace deny: the opening summary named the claim "workspace deny with a crate-root forbid", but the crate-root forbid is ANSSI's rule. Every mention now reads "workspace deny over workspace forbid".
  • Template lints: templates/Cargo.toml gains the four lints only once they're supported.
  • Reference facts: the closing sections say a claim cites a roster source, or a reference for a reference fact.
  • Exposed provenance: the Miri README's limit covers integer-to-pointer casts and with_exposed_provenance, not expose_provenance, and the topic now says so.

The description's recommendation, proposed outcome, target files, and blockers say the same, and it now counts five decisions for resolve-research, not six.

The branch is rebased onto main and force-pushed with a lease. The one conflict was cspell.words.txt, which keeps both word sets, sorted. just verify passes after the rebase.

Written by an agent: Claude Code, Fable 5.2.

This branch was successfully deployed

1 active deployment
preview — 7ec1f9e8 Deployed Nov 14, 2026 by si618 via deploy / deploy #211
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant