ADR-002: Rust toolchain pinning and MSRV policy

Status: Accepted Current state: Toolchain pinned at 1.96.0 in rust-toolchain.toml. MSRV 1.94 declared in Cargo.toml. Edition 2024. Date: 2026-05-30 Deciders: Operator + agent

Context

Rust releases a new stable every six weeks. Without an explicit pin, rustup resolves to whatever stable the developer's machine has, which differs between contributors and CI runs. Two separate concerns need a home:

1. The pinned toolchain — the exact Rust version used for development, CI, and release builds.
2. The MSRV (Minimum Supported Rust Version) — the oldest stable Rust that can compile the crate.

Decision

Pinned toolchain: rust-toolchain.toml is the single source of truth.

[toolchain]
channel = "1.96.0"
components = ["clippy", "rustfmt"]
targets = ["aarch64-unknown-linux-gnu", "x86_64-unknown-linux-gnu"]

rustup, rust-analyzer, mise (via idiomatic version file detection), and CI (via jdx/mise-action) all read this file. The channel is a specific stable version, never stable or nightly, so every build environment uses identical compiler behaviour.

The channel is bumped when a new stable release adds a feature the codebase wants to use (e.g. edition = "2024" requires ≥ 1.85; let-else, let-chains, and other 2024 edition features drive the floor up over time). Bumps land as a separate commit so the diff is unambiguous.

MSRV: declared in Cargo.toml as rust-version.

rust-version = "1.94"

The MSRV is the oldest stable Rust that compiles the workspace without --ignore-rust-version. It is verified by a dedicated msrv CI job that builds with the declared version. MSRV is always ≤ the pinned toolchain.

Edition: 2024 (edition = "2024" in every crate's Cargo.toml). The 2024 edition floor is ≥ 1.85.

Consequences

• Every contributor and CI job compiles with the same compiler. "Works on my machine" compiler differences are eliminated.
• rust-toolchain.toml channel bumps are intentional and reviewable; accidental toolchain drift is impossible.
• The MSRV CI job catches regressions before they reach main: adding a dependency or language feature that requires a newer compiler fails the msrv job immediately.
• mise install on a fresh checkout installs the exact toolchain version without a separate rustup command.