ADR-002: Latest stable Rust toolchain policy

Status: Accepted Current state: Toolchain pinned at 1.97.0 in rust-toolchain.toml. Matching rust-version = "1.97" 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. The repository needs one reproducible current toolchain:

1. The pinned toolchain — the exact newest stable Rust version used for development, CI, and release builds.
2. The manifest declaration — rust-version matches that toolchain so package metadata never advertises an older compatibility floor.

Decision

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

[toolchain]
channel = "1.97.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 whenever a new stable release is available. Bumps land as a separate commit when practical so the diff is unambiguous.

Supported Rust version: declared in Cargo.toml as rust-version.

rust-version = "1.97"

This value always matches the pinned stable channel. CI has no older-compiler lane, compatibility target directory, or older-toolchain cache.

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.
• New language and library capabilities can be adopted immediately; older Rust releases are explicitly unsupported.
• mise install on a fresh checkout installs the exact toolchain version without a separate rustup command.