fix(multitude): gate over-aligned doctest behind utc_backend cfg

[Kateřina Churanová (kate-shine)]

Problem

cargo test -p multitude --doc fails on codegen backends that support a lower maximum type alignment than the default one.

The doctest on AllocError::is_alignment_too_large has to declare an over-aligned type in order to demonstrate the error it documents:

#[repr(align(32768))]
struct OverAligned;

let arena = multitude::Arena::new();
let Some(error) = arena.try_alloc(OverAligned).err() else {
    panic!("over-aligned values must be rejected");
};
assert!(error.is_alignment_too_large());

On a backend that caps alignment below that value, the type cannot be compiled at all, so the doctest fails.

#501 gated the equivalent integration tests behind cfg(utc_backend) and registered that cfg in the workspace check-cfg list, but this doctest was missed.

Fix

Wrap the body in the hidden #[cfg(...)] shim documented in AGENTS-feature-gated-doctests.md (Pattern C — no ?, no user main):

/// # fn main() {
/// # #[cfg(not(utc_backend))] {
/// ... existing body, unchanged ...
/// # }
/// # }

The # prefix keeps the shim out of the rendered documentation, so the published example is unchanged.

Note for reviewers: RUSTDOCFLAGS is required

Doctests are compiled by rustdoc, and cargo passes RUSTFLAGS to rustc but not to rustdoc. Enabling the gate for doctests therefore needs both:

RUSTFLAGS=--cfg utc_backend
RUSTDOCFLAGS=--cfg utc_backend

Verified: with RUSTFLAGS alone the gate compiles in but the doctest still fails, because rustdoc never sees the cfg. Anything driving this build (for example a publish pipeline that currently sets only RUSTFLAGS) needs RUSTDOCFLAGS as well, otherwise this fix will appear to have no effect.

Verification

• Doctests with the gate set (both env vars): 301 passed, 0 failed — previously 1 failed.
• Doctests without the gate, on a normal toolchain: 301 passed, 0 failed — the example still genuinely compiles and asserts, it is not silently skipped.
• cargo clippy -p multitude --profile dev --all-targets --all-features --locked — clean, zero warnings.
• just package=multitude format-check — clean.
• just spellcheck — clean.

Confirmed separately that the multitude library builds cleanly on such a backend and its 46 unit tests pass. The library declares no over-aligned types; alignment is handled at runtime via align_of::<T>(). Only test and doc code that must construct an over-aligned type is affected.

AB#7707893

[Copilot]

Pull request overview

Restores the repository’s root rust-toolchain.toml so clean checkouts build/test under the intended pinned LLVM-backed Rust toolchain, avoiding failures when a developer’s default rustup toolchain uses the Microsoft UTC backend (with its 8192B alignment cap that breaks multitude’s intentionally over-aligned tests).

Changes:

• Reintroduce the workspace toolchain pin at channel = "1.96.1" (matches RUST_LATEST in constants.env).
• Ensure clippy and rustfmt are installed for the pinned toolchain (so rustup users on the minimal profile can still run just clippy / just format).
• Restore the previously-pinned additional compilation targets.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.0%. Comparing base (d799037) to head (d25a7f5).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #650   +/-   ##
=======================================
  Coverage   100.0%   100.0%           
=======================================
  Files         473      473           
  Lines       45493    45493           
=======================================
  Hits        45493    45493           

Flag	Coverage Δ
linux	80.1% <ø> (-19.9%)	⬇️
linux-arm	80.1% <ø> (-19.9%)	⬇️
scheduled	?
windows	80.1% <ø> (-19.9%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Ralf Biedert (ralfbiedert)]

🤖 This new pin is required to match RUST_LATEST, but scripts/update_rust_toolchain.ps1 only reads and rewrites constants.env. The next stable update will advance CI while leaving clean local checkouts on the old toolchain. Please update rust-toolchain.toml atomically in that script and adjust its README description.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

[Ralf Biedert (ralfbiedert)]

🤖 Approved.

[Ralf Biedert (ralfbiedert)]

🤖 Reviewed exact head d25a7f5. The cfg polarity is correct, normal backends continue executing the doctest, and the UTC backend avoids compiling the unsupported over-aligned declaration. I found no blocking correctness, performance, or unsafe-context issues.