ci(rust): refresh nightly coverage and track stable compiler

.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  - package-ecosystem: "rust-toolchain"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 1

.github/workflows/ci.yml

@@ -223,13 +223,13 @@ jobs:
           printf 'TEST_DATABASE_URL=host=localhost user=postgres password=ci_%s_%s dbname=psychometrics_commons_test\n' \
             "$GITHUB_RUN_ID" "$GITHUB_RUN_ATTEMPT" >> "$GITHUB_ENV"
       - name: Install pinned nightly with LLVM tools
-        run: rustup toolchain install nightly-2026-08-01 --profile minimal --component llvm-tools-preview
+        run: rustup toolchain install nightly-2026-08-18 --profile minimal --component llvm-tools-preview
       - name: Install pinned cargo-llvm-cov
-        run: cargo +nightly-2026-08-01 install cargo-llvm-cov --locked --version "$CARGO_LLVM_COV_VERSION"
+        run: cargo +nightly-2026-08-18 install cargo-llvm-cov --locked --version "$CARGO_LLVM_COV_VERSION"
       - name: Verify cargo-llvm-cov version
-        run: cargo +nightly-2026-08-01 llvm-cov --version | grep -F "$CARGO_LLVM_COV_VERSION"
+        run: cargo +nightly-2026-08-18 llvm-cov --version | grep -F "$CARGO_LLVM_COV_VERSION"
       - name: Generate branch coverage
-        run: cargo +nightly-2026-08-01 llvm-cov --branch --json --summary-only --output-path coverage-branches.json
+        run: cargo +nightly-2026-08-18 llvm-cov --branch --json --summary-only --output-path coverage-branches.json
       - name: Enforce complete branch coverage
         run: python3 scripts/check_coverage.py coverage-branches.json --kind branches
       - name: Diagnose missing branch coverage
@@ -252,7 +252,7 @@ jobs:
                       f"{file_entry.get('filename')}"
                   )
           PY
-          cargo +nightly-2026-08-01 llvm-cov report --branch --lcov --output-path coverage-branches.lcov
+          cargo +nightly-2026-08-18 llvm-cov report --branch --lcov --output-path coverage-branches.lcov
           python3 - <<'PY'
           from pathlib import Path
 

docs/doctoring/rust-toolchain-freshness.md

@@ -0,0 +1,29 @@
+# Rust toolchain freshness
+
+Psychometrics Commons uses Rust `1.97.1` as its exact stable compiler baseline.
+The project does not use a floating `stable` channel: a compiler transition is a
+reviewed change that must preserve formatting, compilation, Clippy, tests,
+rustdoc, PostgreSQL integration, and exact production coverage on one unchanged
+head.
+
+Branch coverage uses `cargo-llvm-cov` 0.8.6 with the reproducible
+`nightly-2026-08-18` toolchain because upstream Rust branch coverage remains
+unstable and nightly-only. Installation, tool verification, coverage generation,
+and missing-branch diagnostics use the same date pin. Repository contract tests
+reject both the predecessor `nightly-2026-08-01` value and inconsistent partial
+updates.
+
+GitHub Dependabot monitors the root `rust-toolchain.toml` through the
+`rust-toolchain` package ecosystem. Stable compiler upgrades therefore arrive as
+reviewable pull requests rather than silently changing CI behavior.
+
+## References
+
+GitHub. (2025, August 19). *Dependabot now supports Rust toolchain updates*.
+GitHub Changelog. https://github.blog/changelog/2025-08-19-dependabot-now-supports-rust-toolchain-updates/
+
+Rust Project Developers. (2026, July 16). *Announcing Rust 1.97.1*. Rust Blog.
+https://blog.rust-lang.org/2026/07/16/Rust-1.97.1/
+
+Taiki Endo and contributors. (2026). *cargo-llvm-cov* (Version 0.8.6)
+[Computer software]. GitHub. https://github.com/taiki-e/cargo-llvm-cov

tests/ci_contract.rs

@@ -1,6 +1,8 @@
 //! Integration tests for repository CI evidence semantics.
 
 const CI_WORKFLOW: &str = include_str!("../.github/workflows/ci.yml");
+const RUST_TOOLCHAIN: &str = include_str!("../rust-toolchain.toml");
+const DEPENDABOT: &str = include_str!("../.github/dependabot.yml");
 
 #[test]
 fn every_checkout_is_bound_to_the_pull_request_head() {
@@ -100,8 +102,38 @@ fn line_coverage_failure_diagnostic_emits_machine_readable_annotations() {
 #[test]
 fn branch_coverage_failure_diagnostic_uses_lcov_branch_records() {
     assert!(CI_WORKFLOW.contains(
-        "cargo +nightly-2026-08-01 llvm-cov report --branch --lcov --output-path coverage-branches.lcov"
+        "cargo +nightly-2026-08-18 llvm-cov report --branch --lcov --output-path coverage-branches.lcov"
     ));
     assert!(CI_WORKFLOW.contains("raw_line.startswith(\"BRDA:\")"));
     assert!(CI_WORKFLOW.contains("taken in {\"0\", \"-\"}"));
 }
+
+#[test]
+fn rust_toolchains_are_exact_and_reviewably_updated() {
+    const STABLE_QUALITY_INSTALL: &str =
+        "rustup toolchain install 1.97.1 --profile minimal --component clippy --component rustfmt";
+    const STABLE_COVERAGE_INSTALL: &str =
+        "rustup toolchain install 1.97.1 --profile minimal --component llvm-tools-preview";
+    const NIGHTLY_COVERAGE_INSTALL: &str =
+        "rustup toolchain install nightly-2026-08-18 --profile minimal --component llvm-tools-preview";
+    const NIGHTLY_LLVM_COV_INSTALL: &str =
+        "cargo +nightly-2026-08-18 install cargo-llvm-cov --locked --version \"$CARGO_LLVM_COV_VERSION\"";
+    const NIGHTLY_LLVM_COV_VERSION: &str =
+        "cargo +nightly-2026-08-18 llvm-cov --version | grep -F \"$CARGO_LLVM_COV_VERSION\"";
+    const NIGHTLY_BRANCH_JSON: &str =
+        "cargo +nightly-2026-08-18 llvm-cov --branch --json --summary-only --output-path coverage-branches.json";
+
+    assert!(RUST_TOOLCHAIN.contains("channel = \"1.97.1\""));
+    assert!(!RUST_TOOLCHAIN.contains("channel = \"stable\""));
+    assert!(CI_WORKFLOW.contains(STABLE_QUALITY_INSTALL));
+    assert!(CI_WORKFLOW.contains(STABLE_COVERAGE_INSTALL));
+    assert!(CI_WORKFLOW.contains(NIGHTLY_COVERAGE_INSTALL));
+    assert!(CI_WORKFLOW.contains(NIGHTLY_LLVM_COV_INSTALL));
+    assert!(CI_WORKFLOW.contains(NIGHTLY_LLVM_COV_VERSION));
+    assert!(CI_WORKFLOW.contains(NIGHTLY_BRANCH_JSON));
+    assert!(!CI_WORKFLOW.contains("nightly-2026-08-01"));
+
+    assert!(DEPENDABOT.contains("package-ecosystem: \"rust-toolchain\""));
+    assert!(DEPENDABOT.contains("directory: \"/\""));
+    assert!(DEPENDABOT.contains("interval: \"weekly\""));
+}