From 0e6e293700b86f8d47e2c567ec3acb1b66585766 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Fri, 30 Oct 2026 17:36:48 +0200 Subject: [PATCH 01/11] fix(sdk): treat a two-component version pin as that release line `--version 10.1` stayed on the canonical 7.x index because it did not parse as major.minor.patch, then suggested `--channel nightly`, which refuses ROCm 10. A numeric major.minor pin now selects the newest stable publish in that line, and a failed ROCm 10 pin no longer points at nightly. Signed-off-by: Roman Inflianskas --- README.md | 19 +- apps/rocm/src/cli.rs | 6 +- apps/rocm/src/therock/resolve/tarball.rs | 109 ++++++++-- apps/rocm/src/therock/resolve/wheel.rs | 117 ++++++++++- apps/rocm/src/therock/source.rs | 190 ++++++++++++++++-- apps/rocm/src/therock/version.rs | 46 ++++- .../features/therock_next_generation.feature | 23 +++ tests/e2e-cucumber/tests/e2e/therock_steps.rs | 104 ++++++++++ 8 files changed, 571 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index fed2c5bcd6..9c58ab000d 100644 --- a/README.md +++ b/README.md @@ -256,9 +256,12 @@ legacy install. ROCm CLI supports ROCm 7.14, 10.0, and 10.1. Without `--version`, `rocm install sdk` currently installs ROCm 7.14. To install ROCm 10.0 or 10.1, -add `--version`. If ROCm CLI can't tell which exact GPU arch this computer has, -or you want a different one, also add `--family` with the raw `gfx` code from -`rocm examine`. For example: `--version 10.1.0 --family gfx1200`. +add `--version`. A `major.minor` pin such as `--version 10.1` selects the +newest stable release in that line (for example `10.1.0`). A +`major.minor.patch` pin such as `--version 10.1.0` stays exact. If ROCm CLI +can't tell which exact GPU arch this computer has, or you want a different +one, also add `--family` with the raw `gfx` code from `rocm examine`. For +example: `--version 10.1.0 --family gfx1200`. Running `rocm install sdk` when a managed runtime is already the active default asks first, because the new install takes over as the active default; see @@ -448,7 +451,7 @@ hardware, not something an install or a setting can put right. ``` rocm install sdk [--channel release|nightly] [--format wheel|tarball] - [--version x.y.z | --build-date YYYY-MM-DD] + [--version x.y[.z] | --build-date YYYY-MM-DD] [--family gfx110X-all] [--prefix PATH] [--devel] [--dry-run] [--approve-replacing-active-default] [--yes] @@ -536,9 +539,11 @@ active default runtime, not about what a named prefix loses. #### ROCm 10 and newer ROCm 10 and newer ship from a different source layout. You opt in by pinning the -version with `--version`. These versions select their device payload by exact -GPU arch, so when ROCm CLI can't resolve one for this computer (it detects only -a family of GPUs, or none), or you want to target a different GPU, also pass +version with `--version`. A two-component pin (`--version 10.1`) is the 10.1 +line and installs the newest stable release in it; `--version 10.1.0` installs +that exact release. These versions select their device payload by exact GPU +arch, so when ROCm CLI can't resolve one for this computer (it detects only a +family of GPUs, or none), or you want to target a different GPU, also pass `--family` with the raw `gfx` code instead of a family label: ``` diff --git a/apps/rocm/src/cli.rs b/apps/rocm/src/cli.rs index 34561fda51..2ce4adc4fa 100644 --- a/apps/rocm/src/cli.rs +++ b/apps/rocm/src/cli.rs @@ -790,7 +790,11 @@ rocm install sdk --devel")] /// Full folder path where the ROCm Python environment should be created. #[arg(long)] prefix: Option, - /// Exact TheRock package version to install. + /// TheRock package version to install. + /// + /// `major.minor.patch` is exact, including a prerelease suffix. + /// `major.minor` (for example `10.1`) selects the newest stable + /// release in that line. #[arg(long, conflicts_with = "build_date")] version: Option, /// Pick the TheRock package built on this date. diff --git a/apps/rocm/src/therock/resolve/tarball.rs b/apps/rocm/src/therock/resolve/tarball.rs index 453b8969ed..3070afe391 100644 --- a/apps/rocm/src/therock/resolve/tarball.rs +++ b/apps/rocm/src/therock/resolve/tarball.rs @@ -18,8 +18,10 @@ use super::super::fetch::download_text_cached; use super::super::platform_tarball_token; use super::super::source::{ RuntimeVersionSelector, SourceLayout, TheRockChannel, resolve_source, select_source_layout, + selector_is_release_line, }; use super::super::version::{compare_version_strings, is_stable_runtime_version}; +use super::wheel::next_layout_unsatisfied_hint; use anyhow::{Context, Result, bail}; use rocm_core::AppPaths; use serde::Deserialize; @@ -102,15 +104,12 @@ pub(in crate::therock) fn resolve_tarball_artifact_with_timeout( version_selector, ) .with_context(|| { - format!( - "canonical TheRock {} tarball stream is incomplete for the resolved GPU family\n\n{}", - channel.as_str(), - family_resolution_hint( - &family_resolution.source, - &family_resolution.family, - channel, - "tarball", - ) + tarball_resolution_failure_context( + channel, + layout, + &family_resolution.source, + &family_resolution.family, + version_selector, ) })?; Ok(TarballArtifact { @@ -182,16 +181,50 @@ fn select_tarball_candidate( Some((file.clone(), version)) }) .collect::>(); + // An unpinned catalog pick is "newest upload". A major.minor line pin is + // "newest stable release in that line", even when an older patch was + // uploaded later. Exact pins match one archive, so the order does not + // change which file they select. + let prefer_newest_line_release = version_selector.is_some_and(selector_is_release_line); candidates.sort_by(|left, right| { - left.0 + let by_mtime = left + .0 .mtime .partial_cmp(&right.0.mtime) - .unwrap_or(Ordering::Equal) - .then_with(|| compare_version_strings(&left.1, &right.1)) + .unwrap_or(Ordering::Equal); + let by_version = compare_version_strings(&left.1, &right.1); + if prefer_newest_line_release { + by_version.then(by_mtime) + } else { + by_mtime.then(by_version) + } }); candidates.pop() } +fn tarball_resolution_failure_context( + channel: TheRockChannel, + layout: SourceLayout, + family_source: &str, + family: &str, + version_selector: Option<&RuntimeVersionSelector>, +) -> String { + let (stream, hint) = match layout { + SourceLayout::Next => ( + "next-layout", + next_layout_unsatisfied_hint(version_selector), + ), + SourceLayout::Canonical => ( + "canonical", + family_resolution_hint(family_source, family, channel, "tarball"), + ), + }; + format!( + "{stream} TheRock {} tarball stream is incomplete for the resolved GPU family\n\n{hint}", + channel.as_str() + ) +} + fn parse_tarball_index_html(html: &str) -> Result> { let start = html .find("const files = ") @@ -437,4 +470,56 @@ mod tests { Some("10.1.0a20260822".to_owned()) ); } + + #[test] + fn release_line_pin_prefers_the_newest_stable_tarball_in_the_line() { + let platform = platform_tarball_token(); + let files = vec![ + TarballIndexFile { + name: format!("therock-dist-{platform}-gfx120X-all-10.1.0.tar.gz"), + mtime: 5.0, + }, + TarballIndexFile { + name: format!("therock-dist-{platform}-gfx120X-all-10.1.2.tar.gz"), + mtime: 1.0, + }, + TarballIndexFile { + name: format!("therock-dist-{platform}-gfx120X-all-10.1.0a20260822.tar.gz"), + mtime: 9.0, + }, + TarballIndexFile { + name: format!("therock-dist-{platform}-gfx120X-all-10.0.0.tar.gz"), + mtime: 8.0, + }, + TarballIndexFile { + name: format!("therock-dist-{platform}-gfx120X-all-tests-10.1.3.tar.gz"), + mtime: 9.0, + }, + ]; + let line = RuntimeVersionSelector::version("10.1").unwrap(); + assert_eq!( + select_tarball_candidate( + &files, + TheRockChannel::Release, + SourceLayout::Next, + "gfx120X-all", + Some(&line), + ) + .map(|(_, version)| version), + Some("10.1.2".to_owned()) + ); + + let exact = RuntimeVersionSelector::version("10.1.0").unwrap(); + assert_eq!( + select_tarball_candidate( + &files, + TheRockChannel::Release, + SourceLayout::Next, + "gfx120X-all", + Some(&exact), + ) + .map(|(_, version)| version), + Some("10.1.0".to_owned()) + ); + } } diff --git a/apps/rocm/src/therock/resolve/wheel.rs b/apps/rocm/src/therock/resolve/wheel.rs index dc9c5ff937..88c736f560 100644 --- a/apps/rocm/src/therock/resolve/wheel.rs +++ b/apps/rocm/src/therock/resolve/wheel.rs @@ -47,6 +47,7 @@ use super::super::source::{ }; use super::super::version::{ ParsedVersion, compare_version_strings, is_stable_runtime_version, parse_version, + stable_release_line_pin, }; use super::uv_access::{ UvAccess, UvPolicy, VersionResolution, plan_version_resolution, uv_for_compile, @@ -801,12 +802,7 @@ fn resolve_pip_runtime_plan( &uv, ) .with_context(|| { - format!( - "failed to resolve TheRock {} wheel runtime from canonical source {}\n\n{}", - channel.as_str(), - source.index_url, - canonical_wheel_resolution_hint(channel) - ) + wheel_resolution_failure_context(channel, layout, &source.index_url, version_selector) }) } @@ -1513,8 +1509,67 @@ fn canonical_wheel_resolution_hint(channel: TheRockChannel) -> String { hint } +/// The sentence appended when wheel resolution fails. +/// +/// A ROCm >= 10 pin already refused `--channel nightly` before resolution +/// (`select_source_layout`), so the canonical hint's nightly suggestion must +/// not be what that failure prints. The next-layout branch points at the +/// layout that was searched, a full version, and an exact `--family`. +fn wheel_resolution_failure_context( + channel: TheRockChannel, + layout: SourceLayout, + index_url: &str, + version_selector: Option<&RuntimeVersionSelector>, +) -> String { + let (source_label, hint) = match layout { + SourceLayout::Next => ( + "next-layout source", + next_layout_unsatisfied_hint(version_selector), + ), + SourceLayout::Canonical => ("canonical source", canonical_wheel_resolution_hint(channel)), + }; + format!( + "failed to resolve TheRock {} wheel runtime from {source_label} {index_url}\n\n{hint}", + channel.as_str() + ) +} + +/// Recovery guidance when a ROCm >= 10 pin cannot be satisfied on the next layout. +/// +/// Does not offer `--channel nightly`: that channel refuses these pins, and +/// the refusal tells the user to come back to the release channel. +pub(in crate::therock) fn next_layout_unsatisfied_hint( + version_selector: Option<&RuntimeVersionSelector>, +) -> String { + let requested = version_selector.map_or_else( + || "the requested release".to_owned(), + RuntimeVersionSelector::describe, + ); + let version_clause = match version_selector { + Some(RuntimeVersionSelector::Version(version)) => { + if let Some((major, minor)) = stable_release_line_pin(version) { + format!( + "Re-run with a full version in that line, such as `--version {major}.{minor}.0`, and an exact GPU arch, for example `--family gfx1200`." + ) + } else { + format!( + "Re-run with that full version and an exact GPU arch, for example `--version {version} --family gfx1200`." + ) + } + } + _ => "Re-run with a full version such as `--version 10.0.0` and an exact GPU arch, for example `--family gfx1200`." + .to_owned(), + }; + format!( + "No complete compatible package stack was found for {requested} on the ROCm {THEROCK_NEXT_MIN_MAJOR}+ next layout. {version_clause}" + ) +} + #[cfg(test)] mod tests { + use super::super::super::source::{ + THEROCK_NEXT_PIP_INDEX_BASE, THEROCK_RELEASE_PIP_INDEX_BASE, + }; use super::super::super::test_support::test_runtime_manifest; use super::*; use crate::runtime_registry::{InstalledRuntimeManifest, wheel_composition_includes_devel}; @@ -3158,4 +3213,54 @@ sdk install ); } } + + /// The wording is produced by [`wheel_resolution_failure_context`], which + /// `resolve_pip_runtime_plan` appends when resolution fails. The + /// install that prints it is `@id:therock-next-17-unsatisfied-line-pin-skips-nightly`. + #[test] + fn unsatisfied_rocm_10_line_pin_does_not_suggest_nightly() { + let line = RuntimeVersionSelector::version("10.1").unwrap(); + let message = wheel_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Next, + THEROCK_NEXT_PIP_INDEX_BASE, + Some(&line), + ); + assert!( + !message.contains("nightly"), + "a ROCm 10 pin must not be told to try nightly: {message}" + ); + assert!(message.contains("next layout"), "{message}"); + assert!(message.contains(THEROCK_NEXT_PIP_INDEX_BASE), "{message}"); + assert!(message.contains("--version 10.1.0"), "{message}"); + assert!(message.contains("--family gfx1200"), "{message}"); + + let exact = RuntimeVersionSelector::version("10.1.0").unwrap(); + let exact_message = wheel_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Next, + THEROCK_NEXT_PIP_INDEX_BASE, + Some(&exact), + ); + assert!(!exact_message.contains("nightly"), "{exact_message}"); + assert!( + exact_message.contains("--version 10.1.0"), + "{exact_message}" + ); + assert!( + exact_message.contains("--family gfx1200"), + "{exact_message}" + ); + + // Canonical misses keep the other-channel hint. The 10.1 advice is the + // next-layout branch, not a rewrite of every resolution error. + let canonical = wheel_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Canonical, + THEROCK_RELEASE_PIP_INDEX_BASE, + None, + ); + assert!(canonical.contains("--channel nightly"), "{canonical}"); + assert!(canonical.contains("canonical source"), "{canonical}"); + } } diff --git a/apps/rocm/src/therock/source.rs b/apps/rocm/src/therock/source.rs index f0946679e8..c88a6f3ee1 100644 --- a/apps/rocm/src/therock/source.rs +++ b/apps/rocm/src/therock/source.rs @@ -14,18 +14,19 @@ use super::version::{ VersionStage, normalize_requested_build_date, parse_version, runtime_version_build_date, + stable_release_line_pin, version_request_matches, }; use anyhow::{Result, bail}; use rocm_core::detect_host_gpu_diagnostics; const THEROCK_NIGHTLY_PIP_INDEX_BASE: &str = "https://rocm.nightlies.amd.com/whl-multi-arch"; -const THEROCK_RELEASE_PIP_INDEX_BASE: &str = "https://repo.amd.com/rocm/whl-multi-arch"; +pub(super) const THEROCK_RELEASE_PIP_INDEX_BASE: &str = "https://repo.amd.com/rocm/whl-multi-arch"; const THEROCK_RELEASE_TARBALL_BASE: &str = "https://repo.amd.com/rocm/tarball/"; const THEROCK_NIGHTLY_TARBALL_BASE: &str = "https://rocm.nightlies.amd.com/tarball/"; /// ROCm 10's aggregate pip index. Same simple-index shape the canonical /// multi-arch stream publishes, on a separate host, with its own package /// generation; it is not a mirror of, or a fallback for, the canonical index. -const THEROCK_NEXT_PIP_INDEX_BASE: &str = "https://stable.repo.amd.com/rocm/whl-next"; +pub(super) const THEROCK_NEXT_PIP_INDEX_BASE: &str = "https://stable.repo.amd.com/rocm/whl-next"; /// ROCm 10's tarball catalog. Same scrapeable listing the canonical catalog /// uses, but it publishes non-release sibling archives beside the real dist /// archive (see `select_tarball_candidate` in `resolve/tarball.rs`). @@ -135,12 +136,21 @@ impl RuntimeVersionSelector { pub(super) fn matches_version(&self, version: &str) -> bool { match self { - Self::Version(requested) => version == requested, + Self::Version(requested) => version_request_matches(requested, version), Self::BuildDate(date) => runtime_version_build_date(version).as_deref() == Some(date), } } } +/// Whether `selector` pins a `major.minor` release line rather than one +/// release. +pub(super) fn selector_is_release_line(selector: &RuntimeVersionSelector) -> bool { + matches!( + selector, + RuntimeVersionSelector::Version(version) if stable_release_line_pin(version).is_some() + ) +} + impl TheRockChannel { pub(super) fn parse(value: &str) -> Result { match value.trim().to_ascii_lowercase().as_str() { @@ -239,18 +249,23 @@ pub(super) fn resolve_source(channel: TheRockChannel, layout: SourceLayout) -> R /// Whether `selector` names a ROCm release that only the next layout publishes. /// -/// An exact *stable* pin is the only signal that qualifies. A build date names -/// a nightly build, an unparseable string names nothing this CLI can reason -/// about, and neither is evidence that the canonical stream cannot serve the -/// request. Nor is a pinned prerelease of a future major: the canonical -/// nightly stream already serves those (see -/// `nightly_accepts_future_prerelease_major_without_cli_changes`), so gating -/// on major alone would route a nightly alpha pin like `10.1.0a20260822` into -/// a refusal the release-channel retry it suggests could never satisfy. +/// A stable pin is the only signal that qualifies: an exact `major.minor.patch` +/// release, or a `major.minor` line (`10.1`) at major >= +/// [`THEROCK_NEXT_MIN_MAJOR`]. A build date names a nightly build, an +/// unparseable string names nothing this CLI can reason about, and neither is +/// evidence that the canonical stream cannot serve the request. Nor is a +/// pinned prerelease of a future major: the canonical nightly stream already +/// serves those (see +/// `nightly_accepts_future_prerelease_major_without_cli_changes`), so reading +/// `10.1.0a20260822` as the `10.1` line would route a nightly alpha into a +/// refusal the release-channel retry it suggests could never satisfy. pub(super) fn next_layout_requested(selector: &RuntimeVersionSelector) -> bool { let RuntimeVersionSelector::Version(version) = selector else { return false; }; + if let Some((major, _)) = stable_release_line_pin(version) { + return major >= THEROCK_NEXT_MIN_MAJOR; + } parse_version(version).is_some_and(|parsed| { parsed.stage == VersionStage::Stable && parsed.major >= THEROCK_NEXT_MIN_MAJOR }) @@ -258,10 +273,12 @@ pub(super) fn next_layout_requested(selector: &RuntimeVersionSelector) -> bool { /// The layout an install must read from, and the refusal when it cannot. /// -/// Only an explicit pin at ROCm >= [`THEROCK_NEXT_MIN_MAJOR`] selects `Next`, -/// because that is the one request the canonical stream provably cannot serve. -/// No selector, a build date, an unparseable pin, or an older pin all stay -/// canonical, so nothing that resolves today starts resolving somewhere else. +/// Only an explicit stable pin at ROCm >= [`THEROCK_NEXT_MIN_MAJOR`] selects +/// `Next` — an exact `major.minor.patch`, or a `major.minor` line — because +/// that is the one request the canonical stream provably cannot serve. +/// No selector, a build date, an unparseable pin, a prerelease, or an older +/// pin all stay canonical, so nothing that resolves today starts resolving +/// somewhere else. /// A pin that does reach `Next` still needs an exact arch, because that layout /// picks its device payload by exact arch and a grouped family names none. pub(super) fn select_source_layout( @@ -275,7 +292,14 @@ pub(super) fn select_source_layout( let RuntimeVersionSelector::Version(version) = selector else { return Ok(SourceLayout::Canonical); }; - let major = parse_version(version).map_or(THEROCK_NEXT_MIN_MAJOR, |parsed| parsed.major); + // `parse_version` only accepts `major.minor.patch`. A line pin such as + // `10.1` or `11.2` has no patch, so its major comes from the line parser. + // Falling back to [`THEROCK_NEXT_MIN_MAJOR`] would tell an `11.2` request + // that it was installing ROCm 10. + let major = parse_version(version) + .map(|parsed| parsed.major) + .or_else(|| stable_release_line_pin(version).map(|(major, _)| major)) + .unwrap_or(THEROCK_NEXT_MIN_MAJOR); if !matches!(channel, TheRockChannel::Release) { bail!( "ROCm {major} and newer is published only on the release channel; re-run `rocm install sdk --channel release --version {version}`" @@ -323,6 +347,7 @@ pub(super) fn requested_source_layout( mod tests { use super::*; use crate::test_support::PROCESS_ENV_TEST_LOCK; + use crate::therock::resolve::select_rocm_version; use crate::therock::test_support::family_for_test; /// Everything a user can ask for today must keep resolving the canonical @@ -498,4 +523,137 @@ mod tests { SourceLayout::Next ); } + + /// `--version 10.1` is a stable 10.1 line, not a failed parse and not the + /// literal `10.1.0`. It must take the next layout, the same exact-arch + /// gate as `10.1.0`, and the newest stable release in that line. A + /// three-component pin stays exact, a prerelease is not a line pin, and + /// an unpinned request stays canonical. + #[test] + fn two_component_version_pin_routes_and_matches_its_release_line() { + let exact = family_for_test("gfx120X-all", Some("gfx1200")); + let grouped = family_for_test("gfx120X-all", None); + let line = RuntimeVersionSelector::version("10.1").unwrap(); + + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, Some(&line)).unwrap(), + SourceLayout::Next, + "a ROCm 10.1 line pin must leave the canonical index" + ); + assert_eq!( + requested_source_layout(None, Some(&line)), + SourceLayout::Next + ); + assert!( + line.matches_version("10.1.0"), + "10.1 must match the published 10.1.0 release" + ); + assert!(line.matches_version("10.1.2")); + assert!( + !line.matches_version("10.1.0a20260822"), + "a line pin must not swallow a prerelease in that line" + ); + assert!(!line.matches_version("10.0.0")); + assert!( + !line.matches_version("10.10.0"), + "10.1 must not prefix-match 10.10" + ); + + let selected = select_rocm_version( + TheRockChannel::Release, + &[ + "10.0.0".to_owned(), + "10.1.0".to_owned(), + "10.1.0a20260822".to_owned(), + "10.1.2".to_owned(), + "10.10.0".to_owned(), + "7.14.1".to_owned(), + ], + Some(&line), + ); + assert_eq!(selected.as_deref(), Some("10.1.2")); + + let grouped_error = select_source_layout(TheRockChannel::Release, &grouped, Some(&line)) + .expect_err("a 10.1 line pin still requires an exact arch") + .to_string(); + assert!( + grouped_error.contains("requires an exact GPU arch"), + "{grouped_error}" + ); + assert!( + grouped_error.contains("--family gfx1200"), + "{grouped_error}" + ); + + let nightly_error = select_source_layout(TheRockChannel::Nightly, &exact, Some(&line)) + .expect_err("a 10.1 line pin has no nightly stream") + .to_string(); + assert!( + nightly_error.contains("--channel release"), + "{nightly_error}" + ); + assert!( + !nightly_error.contains("try `--channel nightly`"), + "{nightly_error}" + ); + + // Routes that already worked must not move. + let exact_next = RuntimeVersionSelector::version("10.1.0").unwrap(); + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, Some(&exact_next)).unwrap(), + SourceLayout::Next + ); + assert!(exact_next.matches_version("10.1.0")); + assert!(!exact_next.matches_version("10.1.2")); + assert!(!exact_next.matches_version("10.1")); + + let older = RuntimeVersionSelector::version("7.14.1").unwrap(); + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, Some(&older)).unwrap(), + SourceLayout::Canonical + ); + assert!(older.matches_version("7.14.1")); + assert!(!older.matches_version("7.14.0")); + assert!(!older.matches_version("7.14.2")); + + let older_line = RuntimeVersionSelector::version("7.14").unwrap(); + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, Some(&older_line)).unwrap(), + SourceLayout::Canonical, + "a two-component pin below ROCm 10 stays on the canonical index" + ); + assert!(older_line.matches_version("7.14.0")); + assert!(older_line.matches_version("7.14.1")); + assert!(!older_line.matches_version("7.15.0")); + assert_eq!( + select_rocm_version( + TheRockChannel::Release, + &[ + "7.14.0".to_owned(), + "7.14.1".to_owned(), + "7.15.0".to_owned() + ], + Some(&older_line), + ) + .as_deref(), + Some("7.14.1") + ); + + let prerelease = RuntimeVersionSelector::version("10.1.0a20260822").unwrap(); + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, Some(&prerelease)).unwrap(), + SourceLayout::Canonical, + "a prerelease must not be read as a stable two-component pin" + ); + assert_eq!( + select_source_layout(TheRockChannel::Nightly, &exact, Some(&prerelease)).unwrap(), + SourceLayout::Canonical + ); + + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, None).unwrap(), + SourceLayout::Canonical + ); + assert_eq!(requested_source_layout(None, None), SourceLayout::Canonical); + } } diff --git a/apps/rocm/src/therock/version.rs b/apps/rocm/src/therock/version.rs index cefbef9b99..fdeb4380c4 100644 --- a/apps/rocm/src/therock/version.rs +++ b/apps/rocm/src/therock/version.rs @@ -70,7 +70,10 @@ pub(super) enum VersionStage { /// Total order over published version strings — the total order used for /// sorting candidates in the `therock` module's "which build does the user get?" /// decisions. It is not always the first key: `select_tarball_candidate` (in -/// `resolve/tarball.rs`) orders by upload time first and uses this only to break ties. +/// `resolve/tarball.rs`) orders an unpinned catalog by upload time first and +/// uses this only to break ties. A `major.minor` line pin orders by this key +/// first, so the newest stable release in the line wins even when an older +/// patch was uploaded later. /// /// Ordering is PEP 440's, because these strings come from a Python simple /// index: within one release `7.0.0.dev1` < `7.0.0a1` < `7.0.0b1` < @@ -248,6 +251,47 @@ pub(super) fn parse_version_for_ordering(value: &str) -> Option }) } +/// Whether a requested version string selects the published `version`. +/// +/// A stable two-component pin (`10.1`) selects every stable release in that +/// major.minor line. Callers that want one of them take the newest. A +/// three-component pin, including a prerelease suffix, stays an exact string +/// match: `10.1.0` does not select `10.1.1`, and `10.1.0a20260822` is not the +/// `10.1` line. +pub(super) fn version_request_matches(requested: &str, published: &str) -> bool { + if let Some((major, minor)) = stable_release_line_pin(requested) { + return published_in_stable_line(published, major, minor); + } + published == requested +} + +/// A stable `major.minor` pin: two numeric components and nothing after them. +/// +/// `10.1` names the 10.1 line. `10.1.0` is an exact pin. `10.1.0a20260822` is +/// a prerelease, so it is not this shape and a line pin's parser cannot +/// retarget it onto the next layout. +pub(super) fn stable_release_line_pin(value: &str) -> Option<(u32, u32)> { + let (major, rest) = split_u32_prefix(value)?; + let rest = rest.strip_prefix('.')?; + let (minor, rest) = split_u32_prefix(rest)?; + rest.is_empty().then_some((major, minor)) +} + +fn split_u32_prefix(value: &str) -> Option<(u32, &str)> { + let (number, rest) = split_leading_number(value)?; + Some((u32::try_from(number).ok()?, rest)) +} + +/// Whether `published` is a stable release of the `major.minor` line. +fn published_in_stable_line(published: &str, major: u32, minor: u32) -> bool { + if let Some(parsed) = parse_version(published) { + return parsed.stage == VersionStage::Stable + && parsed.major == major + && parsed.minor == minor; + } + stable_release_line_pin(published) == Some((major, minor)) +} + /// Split a leading run of ASCII digits off `value`, returning it and the rest. /// `None` when `value` does not start with a digit, or the digits overflow. fn split_leading_number(value: &str) -> Option<(u64, &str)> { diff --git a/tests/e2e-cucumber/features/therock_next_generation.feature b/tests/e2e-cucumber/features/therock_next_generation.feature index 58ce4a24c4..e748e9de52 100644 --- a/tests/e2e-cucumber/features/therock_next_generation.feature +++ b/tests/e2e-cucumber/features/therock_next_generation.feature @@ -276,3 +276,26 @@ Feature: TheRock "next" ROCm 10 install layout Given a canonical release pip index fixture and a ROCm 10 pip index fixture When the user previews a wheel SDK install for arch gfx1200 into a folder whose name has a quote Then the dry-run command line names that folder as a single argument + + # `--version 10.1` is the 10.1 line, not a failed parse of `10.1.0` and not + # an exact pin. The fixture publishes 10.0.0 and 10.1.0; the line pin must + # take 10.1.0 from the next index and must not stay on the canonical 7.x index. + @id:therock-next-16-two-component-line-pin + Scenario: therock-next-16 - A ROCm 10.1 line pin installs the newest stable build in that line + Given a ROCm 10 pip index fixture that also publishes a newer ROCm 10 build + And a uv is already installed + When the user previews a wheel SDK install for arch gfx1200 pinned to ROCm 10.1 + Then the preview resolves the ROCm 10 pip index for ROCm 10.1.0 + And the preview reports the next source layout generation + And the preview installs the hardware-verified torchaudio for ROCm 10.1.0, not the newer rebuild + + # The same pin against a next index that only publishes 10.0.0 cannot be + # satisfied. The refusal must name the next layout, a full version, and an + # exact arch. It must not offer `--channel nightly`: that channel refuses + # ROCm 10 and the suggestion cannot succeed. + @id:therock-next-17-unsatisfied-line-pin-skips-nightly + Scenario: therock-next-17 - An unsatisfied ROCm 10.1 line pin does not suggest the nightly channel + Given a canonical release pip index fixture and a ROCm 10 pip index fixture + When the user tries to preview a wheel SDK install for arch gfx1200 pinned to ROCm 10.1 + Then the install fails + And the failure names the ROCm 10 next layout and a full version, without suggesting nightly diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index ed2d54a65d..e95491da12 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -1122,6 +1122,46 @@ async fn preview_newer_pinned_wheel_install(world: &mut E2eWorld) { ); } +#[when("the user previews a wheel SDK install for arch gfx1200 pinned to ROCm 10.1")] +async fn preview_line_pinned_wheel_install(world: &mut E2eWorld) { + preview_ok( + world, + &[ + "install", + "sdk", + "--channel", + "release", + "--format", + "wheel", + "--family", + RAW_ARCH, + "--version", + "10.1", + "--dry-run", + ], + ); +} + +#[when("the user tries to preview a wheel SDK install for arch gfx1200 pinned to ROCm 10.1")] +async fn try_preview_line_pinned_wheel_install(world: &mut E2eWorld) { + preview( + world, + &[ + "install", + "sdk", + "--channel", + "release", + "--format", + "wheel", + "--family", + RAW_ARCH, + "--version", + "10.1", + "--dry-run", + ], + ); +} + #[when("the user tries to preview a wheel SDK install for arch gfx1200 pinned to ROCm 10.0.0")] async fn try_preview_pinned_wheel_install(world: &mut E2eWorld) { preview( @@ -1589,6 +1629,33 @@ async fn preview_resolves_next_pip_index(world: &mut E2eWorld) { ); } +#[then("the preview resolves the ROCm 10 pip index for ROCm 10.1.0")] +async fn preview_resolves_next_pip_index_for_rocm_10_1_line(world: &mut E2eWorld) { + let base = next_pip_base(world); + assert_contains(world, &format!("canonical_source: {base}"), "next source"); + assert_contains(world, &format!("index_url: {base}"), "resolved index"); + assert_contains( + world, + &format!("latest_compatible_version: {NEWER_NEXT_ROCM_VERSION}"), + "resolved 10.1 line", + ); + assert_contains( + world, + "requested: version 10.1", + "the pin that selected the line", + ); + assert!( + !stdout(world).contains(&format!("latest_compatible_version: {NEXT_ROCM_VERSION}")), + "a 10.1 line pin selected 10.0.0:\n{}", + stdout(world) + ); + assert!( + !stdout(world).contains(¤t_pip_base(world)), + "a 10.1 line pin resolved the canonical index:\n{}", + stdout(world) + ); +} + #[then("the preview resolves the default ROCm 10 pip index")] async fn preview_resolves_default_next_pip_index(world: &mut E2eWorld) { assert_contains( @@ -1821,6 +1888,43 @@ async fn failure_names_the_missing_torchaudio_build(world: &mut E2eWorld) { ); } +#[then("the failure names the ROCm 10 next layout and a full version, without suggesting nightly")] +async fn failure_names_next_layout_without_nightly(world: &mut E2eWorld) { + let reported = format!( + "{}\n{}", + stdout(world), + world.cli_stderr.as_deref().unwrap_or_default() + ); + assert!( + reported.contains(&next_pip_base(world)), + "the refusal did not search the ROCm 10 next layout:\n{reported}" + ); + assert!( + !reported.contains(¤t_pip_base(world)), + "the refusal searched the canonical index:\n{reported}" + ); + assert!( + reported.contains("next layout"), + "the refusal did not name the next layout:\n{reported}" + ); + assert!( + reported.contains("--version 10.1.0"), + "the refusal did not name a full version in the 10.1 line:\n{reported}" + ); + assert!( + reported.contains(&format!("--family {RAW_ARCH}")), + "the refusal did not name an exact arch:\n{reported}" + ); + assert!( + !reported.contains("--channel nightly"), + "the refusal told the user to try nightly:\n{reported}" + ); + assert!( + !reported.contains("package_specs:"), + "the refusal still printed an install plan:\n{reported}" + ); +} + #[then("the failure asks for an exact GPU arch and names --family gfx1200")] async fn failure_names_the_exact_arch_flag(world: &mut E2eWorld) { // Both streams: what matters is that the user is told how to fix it, not From ce405083a42a7840803aa6cd6eb329aa0ea39350 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 3 Nov 2026 11:10:07 +0200 Subject: [PATCH 02/11] fix(sdk): suggest a published release when a ROCm 10 pin fails The next-layout failure hint told a failed `--version 10.1` to re-run with `--version 10.1.0` and a failed exact pin to re-run with itself, always with `--family gfx1200`. Neither could clear the failure. The hint now lists the stable ROCm 10 releases the next layout publishes, leaves out the release the failed request resolved to, keeps only versions a re-run would route back to the next layout, and suggests the newest with the arch the request used. With nothing else published, or no exact arch, it names no version. A line pin also matches four-component publishes such as 7.2.4.70204. therock-next-17 re-runs the suggested command; therock-next-18 covers the tarball line pin taking the newest release over the newest upload. Signed-off-by: Roman Inflianskas --- README.md | 4 +- apps/rocm/src/therock/resolve/tarball.rs | 113 ++++-- apps/rocm/src/therock/resolve/wheel.rs | 326 +++++++++++++++--- apps/rocm/src/therock/source.rs | 15 + apps/rocm/src/therock/version.rs | 17 +- docs/manual-testing.md | 11 + docs/testing.md | 14 + .../features/therock_next_generation.feature | 23 +- tests/e2e-cucumber/tests/e2e/therock_steps.rs | 126 ++++++- 9 files changed, 561 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index 9c58ab000d..0987611e43 100644 --- a/README.md +++ b/README.md @@ -585,7 +585,9 @@ carries the same ROCm build identifier. Nothing about this happens on its own. Without a `--version` of 10 or newer, `install sdk` resolves the same release and nightly sources as before. It doesn't quietly retry against the ROCm 10 sources when a lookup finds nothing; it tells -you what it couldn't find instead. +you what it couldn't find instead. When a ROCm 10 pin can't be satisfied, the +error lists the other stable ROCm 10 releases that source publishes, if any, +and suggests one of them to re-run with. #### Driver installation diff --git a/apps/rocm/src/therock/resolve/tarball.rs b/apps/rocm/src/therock/resolve/tarball.rs index 3070afe391..6fcc76db9d 100644 --- a/apps/rocm/src/therock/resolve/tarball.rs +++ b/apps/rocm/src/therock/resolve/tarball.rs @@ -17,8 +17,8 @@ use super::super::family::{family_resolution_hint, resolve_family}; use super::super::fetch::download_text_cached; use super::super::platform_tarball_token; use super::super::source::{ - RuntimeVersionSelector, SourceLayout, TheRockChannel, resolve_source, select_source_layout, - selector_is_release_line, + FamilyResolution, RuntimeVersionSelector, SourceLayout, TheRockChannel, resolve_source, + select_source_layout, selector_is_release_line, }; use super::super::version::{compare_version_strings, is_stable_runtime_version}; use super::wheel::next_layout_unsatisfied_hint; @@ -104,12 +104,17 @@ pub(in crate::therock) fn resolve_tarball_artifact_with_timeout( version_selector, ) .with_context(|| { + let published = + tarball_family_candidates(&files, channel, layout, &family_resolution.family) + .into_iter() + .map(|(_, version)| version) + .collect::>(); tarball_resolution_failure_context( channel, layout, - &family_resolution.source, - &family_resolution.family, + &family_resolution, version_selector, + &published, ) })?; Ok(TarballArtifact { @@ -143,28 +148,23 @@ fn tarball_family_token(layout: SourceLayout, family: &str) -> &str { } } -/// The newest archive in `files` that this request can actually install. +/// Every archive in `files` this channel can install for `family`, before any +/// version pin narrows them, paired with the version its name carries. /// -/// The release channel's stable-version filter does double duty on the next -/// catalog: that catalog publishes non-release siblings beside the real dist -/// archive (`...-tests-10.0.0.tar.gz`) whose leftover suffix is not a version at -/// all, and whose mtime is *later* than the archive they shadow, so an unfiltered -/// "newest wins" would pick the wrong file. Requiring a parseable stable version -/// excludes them without inventing a second grammar for the canonical catalogs, -/// which publish no such siblings and have never been held to one. -fn select_tarball_candidate( +/// [`select_tarball_candidate`] picks from these. A next-layout failure lists +/// their versions, so the releases it suggests are ones the pick could take. +fn tarball_family_candidates( files: &[TarballIndexFile], channel: TheRockChannel, layout: SourceLayout, family: &str, - version_selector: Option<&RuntimeVersionSelector>, -) -> Option<(TarballIndexFile, String)> { +) -> Vec<(TarballIndexFile, String)> { let prefix = format!( "therock-dist-{}-{}-", platform_tarball_token(), tarball_family_token(layout, family) ); - let mut candidates = files + files .iter() .filter_map(|file| { let version = file @@ -175,12 +175,31 @@ fn select_tarball_candidate( if matches!(channel, TheRockChannel::Release) && !is_stable_runtime_version(&version) { return None; } - if version_selector.is_some_and(|selector| !selector.matches_version(&version)) { - return None; - } Some((file.clone(), version)) }) - .collect::>(); + .collect() +} + +/// The newest archive in `files` that this request can actually install. +/// +/// The release channel's stable-version filter does double duty on the next +/// catalog: that catalog publishes non-release siblings beside the real dist +/// archive (`...-tests-10.0.0.tar.gz`) whose leftover suffix is not a version at +/// all, and whose mtime is *later* than the archive they shadow, so an unfiltered +/// "newest wins" would pick the wrong file. Requiring a parseable stable version +/// excludes them without inventing a second grammar for the canonical catalogs, +/// which publish no such siblings and have never been held to one. +fn select_tarball_candidate( + files: &[TarballIndexFile], + channel: TheRockChannel, + layout: SourceLayout, + family: &str, + version_selector: Option<&RuntimeVersionSelector>, +) -> Option<(TarballIndexFile, String)> { + let mut candidates = tarball_family_candidates(files, channel, layout, family); + if let Some(selector) = version_selector { + candidates.retain(|(_, version)| selector.matches_version(version)); + } // An unpinned catalog pick is "newest upload". A major.minor line pin is // "newest stable release in that line", even when an older patch was // uploaded later. Exact pins match one archive, so the order does not @@ -205,18 +224,28 @@ fn select_tarball_candidate( fn tarball_resolution_failure_context( channel: TheRockChannel, layout: SourceLayout, - family_source: &str, - family: &str, + family_resolution: &FamilyResolution, version_selector: Option<&RuntimeVersionSelector>, + published: &[String], ) -> String { let (stream, hint) = match layout { SourceLayout::Next => ( "next-layout", - next_layout_unsatisfied_hint(version_selector), + next_layout_unsatisfied_hint( + version_selector, + Some(published), + family_resolution.raw_arch.as_deref(), + Some(&family_resolution.family), + ), ), SourceLayout::Canonical => ( "canonical", - family_resolution_hint(family_source, family, channel, "tarball"), + family_resolution_hint( + &family_resolution.source, + &family_resolution.family, + channel, + "tarball", + ), ), }; format!( @@ -288,6 +317,7 @@ fn validate_tarball_file_name(name: &str) -> Result<()> { #[cfg(test)] mod tests { + use super::super::super::test_support::family_for_test; use super::*; use rocm_core::normalize_therock_family; @@ -522,4 +552,39 @@ mod tests { Some("10.1.0".to_owned()) ); } + + #[test] + fn tarball_failure_on_next_layout_suggests_a_published_release() { + let family = family_for_test("gfx120X-all", Some("gfx1200")); + let line = RuntimeVersionSelector::version("10.1").unwrap(); + let next = tarball_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Next, + &family, + Some(&line), + &["10.0.0".to_owned()], + ); + assert!( + next.starts_with("next-layout TheRock release tarball"), + "{next}" + ); + assert!( + next.contains("`--version 10.0.0 --family gfx1200`"), + "{next}" + ); + assert!(!next.contains("nightly"), "{next}"); + + let canonical = tarball_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Canonical, + &family, + None, + &[], + ); + assert!( + canonical.starts_with("canonical TheRock release tarball"), + "{canonical}" + ); + assert!(canonical.contains("--channel nightly"), "{canonical}"); + } } diff --git a/apps/rocm/src/therock/resolve/wheel.rs b/apps/rocm/src/therock/resolve/wheel.rs index 88c736f560..8869e89c13 100644 --- a/apps/rocm/src/therock/resolve/wheel.rs +++ b/apps/rocm/src/therock/resolve/wheel.rs @@ -43,11 +43,10 @@ use super::super::python::WheelCompatibility; use super::super::slugify; use super::super::source::{ FamilyResolution, RuntimeVersionSelector, SourceLayout, THEROCK_NEXT_MIN_MAJOR, TheRockChannel, - resolve_source, select_source_layout, + next_layout_requested, resolve_source, select_source_layout, }; use super::super::version::{ ParsedVersion, compare_version_strings, is_stable_runtime_version, parse_version, - stable_release_line_pin, }; use super::uv_access::{ UvAccess, UvPolicy, VersionResolution, plan_version_resolution, uv_for_compile, @@ -790,11 +789,32 @@ fn resolve_pip_runtime_plan( ), published_device_targets, }; + // Loaded here rather than inside `resolve_pip_runtime_from_index` so a + // failure further down can name the releases this index does publish. + let exact_arch = family_resolution.raw_arch.as_deref(); + let rocm_versions = load_simple_index_versions( + paths, + &source.index_url, + "rocm", + None, + download_timeout_secs, + ) + .with_context(|| { + wheel_resolution_failure_context( + channel, + layout, + &source.index_url, + version_selector, + None, + exact_arch, + ) + })?; resolve_pip_runtime_from_index( paths, channel, &family_resolution, &source, + &rocm_versions, wheel_compatibility, version_selector, include_devel, @@ -802,7 +822,14 @@ fn resolve_pip_runtime_plan( &uv, ) .with_context(|| { - wheel_resolution_failure_context(channel, layout, &source.index_url, version_selector) + wheel_resolution_failure_context( + channel, + layout, + &source.index_url, + version_selector, + Some(&rocm_versions), + exact_arch, + ) }) } @@ -815,6 +842,7 @@ fn resolve_pip_runtime_from_index( channel: TheRockChannel, family_resolution: &FamilyResolution, source: &ResolvedAggregateWheelSource, + rocm_versions: &[String], wheel_compatibility: &WheelCompatibility, version_selector: Option<&RuntimeVersionSelector>, include_devel: bool, @@ -824,8 +852,6 @@ fn resolve_pip_runtime_from_index( let index_url = source.index_url.as_str(); let mut version_resolution_specs = None; let mut torchaudio_selection = None; - let rocm_versions = - load_simple_index_versions(paths, index_url, "rocm", None, download_timeout_secs)?; if matches!(channel, TheRockChannel::Release) && version_selector.is_none() && !rocm_versions @@ -840,7 +866,7 @@ fn resolve_pip_runtime_from_index( // Only meaningful when we auto-selected "latest" (no explicit request), so a // caller can warn when that newest version has no installable wheels. let newest_repo_version = if version_selector.is_none() { - channel_rocm_candidates(&rocm_versions, channel) + channel_rocm_candidates(rocm_versions, channel) .into_iter() .last() } else { @@ -872,7 +898,7 @@ fn resolve_pip_runtime_from_index( )?; select_matching_pip_package_versions( channel, - &rocm_versions, + rocm_versions, &torch_versions, &torchvision_versions, &torchaudio_versions, @@ -897,7 +923,7 @@ fn resolve_pip_runtime_from_index( ) } }; - let rocm_version = select_rocm_version(channel, &rocm_versions, version_selector) + let rocm_version = select_rocm_version(channel, rocm_versions, version_selector) .with_context(|| { let requested = version_selector.map_or_else( || "latest compatible version".to_owned(), @@ -1514,17 +1540,21 @@ fn canonical_wheel_resolution_hint(channel: TheRockChannel) -> String { /// A ROCm >= 10 pin already refused `--channel nightly` before resolution /// (`select_source_layout`), so the canonical hint's nightly suggestion must /// not be what that failure prints. The next-layout branch points at the -/// layout that was searched, a full version, and an exact `--family`. +/// layout that was searched and at the releases it does publish; see +/// [`next_layout_unsatisfied_hint`]. `published` is `None` when the `rocm` +/// listing itself could not be read. fn wheel_resolution_failure_context( channel: TheRockChannel, layout: SourceLayout, index_url: &str, version_selector: Option<&RuntimeVersionSelector>, + published: Option<&[String]>, + exact_arch: Option<&str>, ) -> String { let (source_label, hint) = match layout { SourceLayout::Next => ( "next-layout source", - next_layout_unsatisfied_hint(version_selector), + next_layout_unsatisfied_hint(version_selector, published, exact_arch, None), ), SourceLayout::Canonical => ("canonical source", canonical_wheel_resolution_hint(channel)), }; @@ -1534,35 +1564,94 @@ fn wheel_resolution_failure_context( ) } -/// Recovery guidance when a ROCm >= 10 pin cannot be satisfied on the next layout. +/// How many published releases a next-layout failure lists by name. +const NEXT_LAYOUT_HINT_MAX_LISTED: usize = 5; + +/// Recovery guidance when a ROCm >= 10 request cannot be satisfied on the next layout. /// /// Does not offer `--channel nightly`: that channel refuses these pins, and /// the refusal tells the user to come back to the release channel. +/// +/// The suggested `--version` is one the next layout actually publishes, never +/// the request that just failed. `published` is that layout's version listing +/// (`None` when the listing itself could not be read), narrowed to one GPU +/// family when `family_scope` names it. The release the failed request +/// resolved to is derived with [`select_rocm_version`], the function that +/// chose it, and left out: a line pin that failed on `10.1.2` must not be told +/// to try `10.1.2` again. Only releases [`next_layout_requested`] would route +/// back to this layout are offered, so a re-run with the suggestion searches +/// the same layout rather than the canonical one. When nothing else qualifies +/// the hint says so and names no command, because no `--version` pin could +/// succeed. `exact_arch` is the arch the failed request resolved with, so the +/// suggested command repeats it. Without one this layout cannot resolve any +/// version, so the hint asks for `--family` instead of a version. pub(in crate::therock) fn next_layout_unsatisfied_hint( version_selector: Option<&RuntimeVersionSelector>, + published: Option<&[String]>, + exact_arch: Option<&str>, + family_scope: Option<&str>, ) -> String { + let layout = format!("the ROCm {THEROCK_NEXT_MIN_MAJOR}+ next layout"); + let Some(published) = published else { + return format!( + "Could not read the releases {layout} publishes, so no other version can be suggested." + ); + }; let requested = version_selector.map_or_else( || "the requested release".to_owned(), RuntimeVersionSelector::describe, ); - let version_clause = match version_selector { - Some(RuntimeVersionSelector::Version(version)) => { - if let Some((major, minor)) = stable_release_line_pin(version) { - format!( - "Re-run with a full version in that line, such as `--version {major}.{minor}.0`, and an exact GPU arch, for example `--family gfx1200`." - ) - } else { - format!( - "Re-run with that full version and an exact GPU arch, for example `--version {version} --family gfx1200`." - ) - } - } - _ => "Re-run with a full version such as `--version 10.0.0` and an exact GPU arch, for example `--family gfx1200`." - .to_owned(), + let lead = + format!("No complete compatible package stack was found for {requested} on {layout}."); + let Some(exact_arch) = exact_arch else { + return format!( + "{lead} That layout needs an exact GPU arch: re-run with `--family` set to the raw `gfx` code `rocm examine` reports." + ); }; - format!( - "No complete compatible package stack was found for {requested} on the ROCm {THEROCK_NEXT_MIN_MAJOR}+ next layout. {version_clause}" - ) + let scope = family_scope.map_or_else(String::new, |family| format!(" for {family}")); + let attempted = select_rocm_version(TheRockChannel::Release, published, version_selector); + let mut alternatives = published + .iter() + .filter(|version| attempted.as_deref() != Some(version.as_str())) + .filter(|version| { + next_layout_requested(&RuntimeVersionSelector::Version((*version).clone())) + }) + .map(String::as_str) + .collect::>(); + alternatives.sort_by(|left, right| compare_version_strings(right, left)); + alternatives.dedup(); + let other = if attempted.is_some() { " other" } else { "" }; + let Some(newest) = alternatives.first() else { + return format!( + "{lead} It publishes no{other} stable release{scope}, so no `--version` pin can install from it yet." + ); + }; + let mut listed = alternatives + .iter() + .take(NEXT_LAYOUT_HINT_MAX_LISTED) + .copied() + .collect::>() + .join(", "); + if alternatives.len() > NEXT_LAYOUT_HINT_MAX_LISTED { + let older = alternatives.len() - NEXT_LAYOUT_HINT_MAX_LISTED; + listed.push_str(", and "); + listed.push_str(&older.to_string()); + listed.push_str(" older"); + } + let command = match version_selector { + Some(_) => format!( + "Re-run with one of them, for example `--version {newest} --family {exact_arch}`." + ), + None => format!( + "Install one of them, for example `rocm install sdk --channel release --version {newest} --family {exact_arch}`." + ), + }; + let label = if attempted.is_some() { + "Other stable releases it publishes" + } else { + "Stable releases it publishes" + }; + format!("{lead} {label}{scope}: {listed}. {command}") } #[cfg(test)] @@ -2720,11 +2809,17 @@ mod tests { find_present: &find_present, acquire: &acquire, }; + // `resolve_pip_runtime_plan` reads the `rocm` listing before it + // calls this, so the test does too. + let rocm_versions = + load_simple_index_versions(&paths, &source.index_url, "rocm", None, None) + .expect("the fixture index lists rocm"); let plan = resolve_pip_runtime_from_index( &paths, TheRockChannel::Release, &super::super::super::test_support::family_for_test("gfx1200", Some("gfx1200")), &source, + &rocm_versions, &compatibility, None, false, @@ -3216,15 +3311,19 @@ sdk install /// The wording is produced by [`wheel_resolution_failure_context`], which /// `resolve_pip_runtime_plan` appends when resolution fails. The - /// install that prints it is `@id:therock-next-17-unsatisfied-line-pin-skips-nightly`. + /// install that prints it, and the re-run that proves its suggestion + /// clears the failure, is `@id:therock-next-17-unsatisfied-line-pin-skips-nightly`. #[test] fn unsatisfied_rocm_10_line_pin_does_not_suggest_nightly() { let line = RuntimeVersionSelector::version("10.1").unwrap(); + let published = vec!["10.0.0".to_owned()]; let message = wheel_resolution_failure_context( TheRockChannel::Release, SourceLayout::Next, THEROCK_NEXT_PIP_INDEX_BASE, Some(&line), + Some(&published), + Some("gfx1201"), ); assert!( !message.contains("nightly"), @@ -3232,24 +3331,13 @@ sdk install ); assert!(message.contains("next layout"), "{message}"); assert!(message.contains(THEROCK_NEXT_PIP_INDEX_BASE), "{message}"); - assert!(message.contains("--version 10.1.0"), "{message}"); - assert!(message.contains("--family gfx1200"), "{message}"); - - let exact = RuntimeVersionSelector::version("10.1.0").unwrap(); - let exact_message = wheel_resolution_failure_context( - TheRockChannel::Release, - SourceLayout::Next, - THEROCK_NEXT_PIP_INDEX_BASE, - Some(&exact), - ); - assert!(!exact_message.contains("nightly"), "{exact_message}"); assert!( - exact_message.contains("--version 10.1.0"), - "{exact_message}" + message.contains("`--version 10.0.0 --family gfx1201`"), + "the suggestion must name a published release and the arch the request used: {message}" ); assert!( - exact_message.contains("--family gfx1200"), - "{exact_message}" + !message.contains("--version 10.1"), + "the index publishes no 10.1 release, so none may be suggested: {message}" ); // Canonical misses keep the other-channel hint. The 10.1 advice is the @@ -3259,8 +3347,158 @@ sdk install SourceLayout::Canonical, THEROCK_RELEASE_PIP_INDEX_BASE, None, + Some(&published), + None, ); assert!(canonical.contains("--channel nightly"), "{canonical}"); assert!(canonical.contains("canonical source"), "{canonical}"); } + + /// Every state [`next_layout_unsatisfied_hint`] can be reached in. The + /// rule under test: the hint never suggests the release the failed + /// request resolved to, and never names a command when the index offers + /// nothing else. + #[test] + fn next_layout_unsatisfied_hint_only_suggests_releases_that_were_not_tried() { + let versions = |list: &[&str]| list.iter().map(|v| (*v).to_owned()).collect::>(); + let line = RuntimeVersionSelector::version("10.1").unwrap(); + let exact = RuntimeVersionSelector::version("10.1.0").unwrap(); + + // A line pin whose newest release (10.1.2) was found but could not be + // installed: the other 10.1 release is still worth trying, 10.1.2 is not. + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&["10.0.0", "10.1.0", "10.1.2"])), + Some("gfx1200"), + None, + ); + assert!( + hint.contains("Other stable releases it publishes: 10.1.0, 10.0.0."), + "{hint}" + ); + assert!( + hint.contains("`--version 10.1.0 --family gfx1200`"), + "{hint}" + ); + assert!(!hint.contains("10.1.2"), "{hint}"); + + // An exact pin that is published but failed is not suggested again. + let hint = next_layout_unsatisfied_hint( + Some(&exact), + Some(&versions(&["10.0.0", "10.1.0"])), + Some("gfx1200"), + None, + ); + assert!( + hint.contains("`--version 10.0.0 --family gfx1200`"), + "{hint}" + ); + assert!(!hint.contains("--version 10.1.0"), "{hint}"); + + // An exact pin that is the only release: nothing else to suggest, so + // no command is named. + let hint = next_layout_unsatisfied_hint( + Some(&exact), + Some(&versions(&["10.1.0"])), + Some("gfx1200"), + None, + ); + assert!( + hint.contains("It publishes no other stable release"), + "{hint}" + ); + assert!(!hint.contains("--version 10"), "{hint}"); + + // An index with no stable release at all; prereleases are not offered. + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&["10.1.0a20260822"])), + Some("gfx1200"), + None, + ); + assert!(hint.contains("It publishes no stable release"), "{hint}"); + assert!(!hint.contains("10.1.0a20260822"), "{hint}"); + assert!(!hint.contains("--version 10"), "{hint}"); + + // `rocm update --apply` reaches the next layout with no selector. The + // newest release is the one it tried; the hint offers the full + // install command for an older one. + let hint = next_layout_unsatisfied_hint( + None, + Some(&versions(&["10.0.0", "10.1.0"])), + Some("gfx1200"), + None, + ); + assert!(hint.contains("the requested release"), "{hint}"); + assert!( + hint.contains("`rocm install sdk --channel release --version 10.0.0 --family gfx1200`"), + "{hint}" + ); + assert!(!hint.contains("--version 10.1.0"), "{hint}"); + assert!(!hint.contains("nightly"), "{hint}"); + + // No exact arch (only reachable through `rocm update --apply`): this + // layout cannot resolve any version without one, so the hint asks for + // `--family` and suggests no version. + let hint = + next_layout_unsatisfied_hint(Some(&line), Some(&versions(&["10.0.0"])), None, None); + assert!(hint.contains("needs an exact GPU arch"), "{hint}"); + assert!(hint.contains("`--family`"), "{hint}"); + assert!(!hint.contains("--version 10"), "{hint}"); + + // The listing itself could not be read: say that, not "no stack was + // found", and suggest nothing. + let hint = next_layout_unsatisfied_hint(Some(&line), None, Some("gfx1200"), None); + assert!( + hint.starts_with("Could not read the releases the ROCm 10+ next layout publishes"), + "{hint}" + ); + assert!( + !hint.contains("No complete compatible package stack"), + "{hint}" + ); + assert!(!hint.contains("--version 10"), "{hint}"); + + // Only releases a re-run would route back to this layout are offered. + // A four-component or sub-10 publish would re-resolve against the + // canonical index, so suggesting it could not clear the failure. + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&["9.9.0", "10.0.0", "10.0.1.12345"])), + Some("gfx1200"), + None, + ); + assert!( + hint.contains("Stable releases it publishes: 10.0.0. "), + "{hint}" + ); + assert!(!hint.contains("10.0.1.12345"), "{hint}"); + assert!(!hint.contains("9.9.0"), "{hint}"); + + // A family-scoped listing (the tarball catalog) says so. + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&[])), + Some("gfx1200"), + Some("gfx120X-all"), + ); + assert!( + hint.contains("It publishes no stable release for gfx120X-all"), + "{hint}" + ); + + // A long listing is capped, newest first. + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&[ + "10.0.0", "10.0.1", "10.0.2", "10.0.3", "10.0.4", "10.0.5", "10.0.6", + ])), + Some("gfx1200"), + None, + ); + assert!( + hint.contains("10.0.6, 10.0.5, 10.0.4, 10.0.3, 10.0.2, and 2 older."), + "{hint}" + ); + } } diff --git a/apps/rocm/src/therock/source.rs b/apps/rocm/src/therock/source.rs index c88a6f3ee1..caf8c59eac 100644 --- a/apps/rocm/src/therock/source.rs +++ b/apps/rocm/src/therock/source.rs @@ -639,6 +639,21 @@ mod tests { Some("7.14.1") ); + // A four-component publish is still a stable release of its line. + let four_component_line = RuntimeVersionSelector::version("7.2").unwrap(); + assert!(four_component_line.matches_version("7.2.4.70204")); + assert!(!four_component_line.matches_version("7.20.4.70204")); + assert!(!four_component_line.matches_version("7.2.4.70204rc1")); + assert_eq!( + select_rocm_version( + TheRockChannel::Release, + &["7.2.3".to_owned(), "7.2.4.70204".to_owned()], + Some(&four_component_line), + ) + .as_deref(), + Some("7.2.4.70204") + ); + let prerelease = RuntimeVersionSelector::version("10.1.0a20260822").unwrap(); assert_eq!( select_source_layout(TheRockChannel::Release, &exact, Some(&prerelease)).unwrap(), diff --git a/apps/rocm/src/therock/version.rs b/apps/rocm/src/therock/version.rs index fdeb4380c4..461a2a7776 100644 --- a/apps/rocm/src/therock/version.rs +++ b/apps/rocm/src/therock/version.rs @@ -283,13 +283,18 @@ fn split_u32_prefix(value: &str) -> Option<(u32, &str)> { } /// Whether `published` is a stable release of the `major.minor` line. +/// +/// Reads `published` with the lenient [`parse_version_for_ordering`], not the +/// strict three-component [`parse_version`], because an index can publish a +/// four-component release such as `7.2.4.70204`, and that is still a stable +/// release of the 7.2 line. The ordering key drops trailing zeros, so a +/// missing minor component reads as zero, as PEP 440 pads it. fn published_in_stable_line(published: &str, major: u32, minor: u32) -> bool { - if let Some(parsed) = parse_version(published) { - return parsed.stage == VersionStage::Stable - && parsed.major == major - && parsed.minor == minor; - } - stable_release_line_pin(published) == Some((major, minor)) + parse_version_for_ordering(published).is_some_and(|key| { + key.stage == VersionStage::Stable + && key.release.first().copied().unwrap_or(0) == u64::from(major) + && key.release.get(1).copied().unwrap_or(0) == u64::from(minor) + }) } /// Split a leading run of ASCII digits off `value`, returning it and the rest. diff --git a/docs/manual-testing.md b/docs/manual-testing.md index f449632823..ac4ed45183 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -233,6 +233,17 @@ Use `--family` only when a test needs a fixed package family. Do not use it for normal user setup. The script checks the default install; add `--devel` to check the opt-in compiler toolchain path instead. +Version pins, checked with `--dry-run`: + +- `rocm install sdk --version 10.1 --family --dry-run` previews the + newest stable 10.1.x from the ROCm 10 source (`source_layout_generation: + next-v1`), and `--version 10.1.0` previews exactly 10.1.0. +- `--version 7.14 --dry-run` previews the newest stable 7.14.x from the + canonical index. +- A ROCm 10 pin the source cannot satisfy fails with a list of the other + stable ROCm 10 releases it publishes, if any, and a `--version` to try. Running that suggestion + must succeed, and the error must not suggest `--channel nightly`. + ### 2a. A GPU target with no ROCm build Any machine can run this one; it needs no particular GPU. `gfx90c` is the Vega diff --git a/docs/testing.md b/docs/testing.md index 40ffb27e8c..17b98c0360 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -909,6 +909,20 @@ The `update_check` tool and the plain `rocm update` check (no `--apply`) are not previews in this sense: on a ROCm 10 or newer runtime they resolve with `uv` and can fetch it. They prepare no Python, though (see `update-09` and `update-10`). +`--version` accepts a `major.minor` line as well as an exact +`major.minor.patch`. `--version 10.1` resolves the newest stable 10.1.x on the +ROCm 10 next layout, and `--version 7.14` the newest stable 7.14.x on the +canonical index. When a ROCm 10 pin cannot be satisfied, the error lists the +other stable ROCm 10 releases that layout publishes, if any, and suggests one +of them, never the release that just failed and never `--channel nightly`. +Loopback-fixture scenarios in +[therock_next_generation.feature](../tests/e2e-cucumber/features/therock_next_generation.feature) +cover this: `therock-next-16` (a wheel line pin), `therock-next-17` (the +failure, which re-runs the suggested command to prove it succeeds) and +`therock-next-18` (a tarball line pin takes the newest release in the line, not +the newest upload). They run in the default e2e lane; `therock-next-18` is +Linux-only because Windows refuses tarball installs. + Then it verifies: - runtime manifest metadata diff --git a/tests/e2e-cucumber/features/therock_next_generation.feature b/tests/e2e-cucumber/features/therock_next_generation.feature index e748e9de52..04d61eadee 100644 --- a/tests/e2e-cucumber/features/therock_next_generation.feature +++ b/tests/e2e-cucumber/features/therock_next_generation.feature @@ -290,12 +290,25 @@ Feature: TheRock "next" ROCm 10 install layout And the preview installs the hardware-verified torchaudio for ROCm 10.1.0, not the newer rebuild # The same pin against a next index that only publishes 10.0.0 cannot be - # satisfied. The refusal must name the next layout, a full version, and an - # exact arch. It must not offer `--channel nightly`: that channel refuses - # ROCm 10 and the suggestion cannot succeed. + # satisfied. The refusal must name the next layout and suggest a release that + # index does publish, with the arch the request used. It must not offer + # `--channel nightly` (that channel refuses ROCm 10) or a 10.1 version (the + # index has none), because neither suggestion can succeed. Running the + # suggested command proves the advice clears the failure. @id:therock-next-17-unsatisfied-line-pin-skips-nightly - Scenario: therock-next-17 - An unsatisfied ROCm 10.1 line pin does not suggest the nightly channel + Scenario: therock-next-17 - An unsatisfied ROCm 10.1 line pin suggests a published release, not the nightly channel Given a canonical release pip index fixture and a ROCm 10 pip index fixture When the user tries to preview a wheel SDK install for arch gfx1200 pinned to ROCm 10.1 Then the install fails - And the failure names the ROCm 10 next layout and a full version, without suggesting nightly + And the failure suggests the published ROCm 10.0.0 for arch gfx1200, without suggesting nightly or a 10.1 version + When the user re-runs the preview with the version and arch the failure suggested + Then the preview resolves the ROCm 10 pip index + + # On the tarball catalog an unpinned pick is "newest upload". A line pin is + # "newest stable release in the line": the fixture uploads 10.1.0 AFTER + # 10.1.2, so upload order alone would pick the older patch. + @id:therock-next-18-tarball-line-pin-takes-newest-release @requires-os:linux + Scenario: therock-next-18 - A ROCm 10.1 line pin on the tarball catalog takes the newest 10.1 release, not the newest upload + Given a ROCm 10 tarball fixture whose older 10.1 patch was uploaded last + When the user previews a tarball SDK install for arch gfx1200 pinned to ROCm 10.1 + Then the preview selects the ROCm 10.1.2 tarball, not the later-uploaded 10.1.0 diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index e95491da12..5242f07e93 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -360,6 +360,14 @@ async fn pip_index_fixtures(world: &mut E2eWorld) { fn serve_pip_fixtures(world: &mut E2eWorld) { let served = root(world).join("therock-pip-fixtures"); world.artifact_server = Some(LoopbackServer::start(&served)); + point_at_pip_fixtures(world); +} + +/// Queue the env that points the next `rocm` run at the served pip fixtures. +/// Each run consumes `command_env`, so a step that runs `rocm` a second time +/// in one scenario calls this again; without it the second run would read the +/// real indexes. +fn point_at_pip_fixtures(world: &mut E2eWorld) { allow_base_overrides(world); let current = current_pip_base(world); let next = next_pip_base(world); @@ -744,6 +752,39 @@ async fn tarball_index_fixtures(world: &mut E2eWorld) { .push(("ROCM_CLI_THEROCK_NEXT_TARBALL_BASE", next.into())); } +/// The newer 10.1 patch, uploaded first. +const NEXT_LINE_NEWEST_TARBALL: &str = "therock-dist-linux-gfx120X-all-10.1.2.tar.gz"; +/// The older 10.1 patch, uploaded last: newest by mtime, not by version. +const NEXT_LINE_LATEST_UPLOAD_TARBALL: &str = "therock-dist-linux-gfx120X-all-10.1.0.tar.gz"; + +#[given("a ROCm 10 tarball fixture whose older 10.1 patch was uploaded last")] +async fn tarball_line_fixture(world: &mut E2eWorld) { + let served = root(world).join("therock-tarball-fixtures"); + write_fixture( + &served.join("tarball").join("current").join("index.html"), + &tarball_index_html(&[(CURRENT_TARBALL, 1_787_000_000.0)]), + ); + write_fixture( + &served.join("tarball").join("next").join("index.html"), + &tarball_index_html(&[ + (NEXT_REAL_TARBALL, 1_787_500_000.0), + (NEXT_LINE_NEWEST_TARBALL, 1_787_600_000.0), + (NEXT_LINE_LATEST_UPLOAD_TARBALL, 1_787_700_000.0), + ]), + ); + world.artifact_server = Some(LoopbackServer::start(&served)); + allow_base_overrides(world); + let base = server_base(world); + let next = next_tarball_base(world); + world.command_env.push(( + "ROCM_CLI_THEROCK_RELEASE_TARBALL_BASE", + format!("{base}/tarball/current/").into(), + )); + world + .command_env + .push(("ROCM_CLI_THEROCK_NEXT_TARBALL_BASE", next.into())); +} + /// Size and pacing for the paced tarball fixture below: large enough (versus /// the chunk size) that several chunk boundaries — and therefore several /// observable progress frames — land before the transfer completes, and slow @@ -1202,6 +1243,26 @@ async fn preview_pinned_tarball_install(world: &mut E2eWorld) { ); } +#[when("the user previews a tarball SDK install for arch gfx1200 pinned to ROCm 10.1")] +async fn preview_line_pinned_tarball_install(world: &mut E2eWorld) { + preview_ok( + world, + &[ + "install", + "sdk", + "--channel", + "release", + "--format", + "tarball", + "--family", + RAW_ARCH, + "--version", + "10.1", + "--dry-run", + ], + ); +} + #[when("the user previews a tarball SDK install for family gfx120X-all pinned to ROCm 10.0.0")] async fn preview_pinned_tarball_install_with_group_family(world: &mut E2eWorld) { preview( @@ -1832,6 +1893,22 @@ async fn preview_selects_real_tarball(world: &mut E2eWorld) { ); } +#[then("the preview selects the ROCm 10.1.2 tarball, not the later-uploaded 10.1.0")] +async fn preview_selects_newest_line_tarball(world: &mut E2eWorld) { + let base = next_tarball_base(world); + assert_contains( + world, + &format!("tarball_url: {base}{NEXT_LINE_NEWEST_TARBALL}"), + "newest 10.1 release", + ); + assert_contains(world, "latest_version: 10.1.2", "selected line version"); + assert!( + !stdout(world).contains(NEXT_LINE_LATEST_UPLOAD_TARBALL), + "a 10.1 line pin took the latest upload instead of the newest release:\n{}", + stdout(world) + ); +} + #[then("the preview does not select the tests artifact")] async fn preview_does_not_select_tests_tarball(world: &mut E2eWorld) { assert!( @@ -1888,13 +1965,19 @@ async fn failure_names_the_missing_torchaudio_build(world: &mut E2eWorld) { ); } -#[then("the failure names the ROCm 10 next layout and a full version, without suggesting nightly")] -async fn failure_names_next_layout_without_nightly(world: &mut E2eWorld) { - let reported = format!( +fn reported_output(world: &E2eWorld) -> String { + format!( "{}\n{}", stdout(world), world.cli_stderr.as_deref().unwrap_or_default() - ); + ) +} + +#[then( + "the failure suggests the published ROCm 10.0.0 for arch gfx1200, without suggesting nightly or a 10.1 version" +)] +async fn failure_suggests_published_next_release(world: &mut E2eWorld) { + let reported = reported_output(world); assert!( reported.contains(&next_pip_base(world)), "the refusal did not search the ROCm 10 next layout:\n{reported}" @@ -1908,12 +1991,14 @@ async fn failure_names_next_layout_without_nightly(world: &mut E2eWorld) { "the refusal did not name the next layout:\n{reported}" ); assert!( - reported.contains("--version 10.1.0"), - "the refusal did not name a full version in the 10.1 line:\n{reported}" + reported.contains(&format!( + "`--version {NEXT_ROCM_VERSION} --family {RAW_ARCH}`" + )), + "the refusal did not suggest the published {NEXT_ROCM_VERSION} with the requested arch:\n{reported}" ); assert!( - reported.contains(&format!("--family {RAW_ARCH}")), - "the refusal did not name an exact arch:\n{reported}" + !reported.contains("--version 10.1"), + "the refusal suggested a 10.1 version the index does not publish:\n{reported}" ); assert!( !reported.contains("--channel nightly"), @@ -1925,6 +2010,31 @@ async fn failure_names_next_layout_without_nightly(world: &mut E2eWorld) { ); } +/// Runs exactly the `--version`/`--family` pair the previous failure printed, +/// so the scenario proves the advice clears the failure rather than only +/// pinning its wording. +#[when("the user re-runs the preview with the version and arch the failure suggested")] +async fn rerun_with_suggested_version(world: &mut E2eWorld) { + let reported = reported_output(world); + let suggested = reported + .split('`') + .find(|chunk| chunk.starts_with("--version ")) + .unwrap_or_else(|| panic!("the failure suggested no `--version` command:\n{reported}")) + .to_owned(); + let mut args = vec![ + "install", + "sdk", + "--channel", + "release", + "--format", + "wheel", + ]; + args.extend(suggested.split_whitespace()); + args.push("--dry-run"); + point_at_pip_fixtures(world); + preview_ok(world, &args); +} + #[then("the failure asks for an exact GPU arch and names --family gfx1200")] async fn failure_names_the_exact_arch_flag(world: &mut E2eWorld) { // Both streams: what matters is that the user is told how to fix it, not From c4901f69d5572cce7afcc7a85fa55ed14eb7b627 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 9 Nov 2026 13:24:05 +0200 Subject: [PATCH 03/11] test(sdk): pin the --version help and both re-run hint wordings The `--version` help is the most-read description of what a two-component pin does, and nothing asserted its wording. Read the argument's own help, so the sibling `--build-date` doc cannot satisfy it. The re-run hint words a pinned request ("Re-run with one of them") and the unpinned `rocm update --apply` path (a full `rocm install sdk` command) differently. Assert each arm's own phrasing and the absence of the other's, so a swap is named by the failure rather than caught by a backtick position. Signed-off-by: Roman Inflianskas --- apps/rocm/src/cli.rs | 40 ++++++++++++++++++++++++++ apps/rocm/src/therock/resolve/wheel.rs | 15 ++++++++++ 2 files changed, 55 insertions(+) diff --git a/apps/rocm/src/cli.rs b/apps/rocm/src/cli.rs index 2ce4adc4fa..bb53b6bad6 100644 --- a/apps/rocm/src/cli.rs +++ b/apps/rocm/src/cli.rs @@ -1620,6 +1620,46 @@ mod tests { ); } + #[test] + fn install_sdk_version_help_describes_line_and_exact_pins() { + // Wording pin: `--version 10.1` selecting the newest stable 10.1.x, and + // `--version 10.1.0` staying exact, are proven by + // `two_component_version_pin_routes_and_matches_its_release_line` in + // `therock/source.rs` and by scenarios therock-next-16 and -18. This + // only keeps the help that describes them from drifting back to + // "exact version". It reads the `version` argument's own help, so the + // sibling `--build-date` doc cannot satisfy it. + let mut command = Cli::command(); + let sdk = command + .find_subcommand_mut("install") + .expect("install subcommand") + .find_subcommand_mut("sdk") + .expect("install sdk subcommand"); + let version = sdk + .get_arguments() + .find(|arg| arg.get_id() == "version") + .expect("`install sdk` must offer --version"); + let version_help = version + .get_long_help() + .or_else(|| version.get_help()) + .expect("--version must be documented") + .to_string(); + + assert!( + version_help.contains("`major.minor.patch` is exact"), + "`--version` must say a three-component pin is exact:\n{version_help}" + ); + assert!( + version_help.contains("`major.minor` (for example `10.1`) selects the newest stable"), + "`--version` must say a two-component pin selects the newest stable \ + release in that line:\n{version_help}" + ); + assert!( + !version_help.starts_with("Exact"), + "`--version` no longer takes only an exact version:\n{version_help}" + ); + } + #[test] fn install_sdk_help_separates_the_two_consents_yes_carries() { // `--yes` approves two unrelated things: replacing the active default diff --git a/apps/rocm/src/therock/resolve/wheel.rs b/apps/rocm/src/therock/resolve/wheel.rs index 8869e89c13..7a279fa1b5 100644 --- a/apps/rocm/src/therock/resolve/wheel.rs +++ b/apps/rocm/src/therock/resolve/wheel.rs @@ -3381,6 +3381,16 @@ sdk install "{hint}" ); assert!(!hint.contains("10.1.2"), "{hint}"); + // A pinned request re-runs its own command with a different + // `--version`, so it is told to re-run, not handed a whole install + // command. The unpinned `rocm update --apply` case below gets the full + // command instead. + assert!( + hint.contains("Re-run with one of them, for example `--version 10.1.0"), + "{hint}" + ); + assert!(!hint.contains("Install one of them"), "{hint}"); + assert!(!hint.contains("rocm install sdk"), "{hint}"); // An exact pin that is published but failed is not suggested again. let hint = next_layout_unsatisfied_hint( @@ -3434,6 +3444,11 @@ sdk install hint.contains("`rocm install sdk --channel release --version 10.0.0 --family gfx1200`"), "{hint}" ); + assert!( + hint.contains("Install one of them, for example `rocm install sdk"), + "{hint}" + ); + assert!(!hint.contains("Re-run with one of them"), "{hint}"); assert!(!hint.contains("--version 10.1.0"), "{hint}"); assert!(!hint.contains("nightly"), "{hint}"); From b3e72ff44e6f0067ae4a68480d756c68a5f20c3e Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 9 Nov 2026 14:45:25 +0200 Subject: [PATCH 04/11] test(sdk): pin a line pin's refusal major and the unpinned tarball order Three branches of the line-pin change stayed green when broken alone: the major an `11.2` refusal prints (it fell back to the ROCm 10 floor), the u32 overflow guard on a pin component, and the unpinned tarball pick, which must keep "newest upload wins" while only a line pin orders by version first. Each assertion goes red when its branch is reverted. Signed-off-by: Roman Inflianskas --- apps/rocm/src/therock/resolve/tarball.rs | 15 +++++++++++++++ apps/rocm/src/therock/source.rs | 20 ++++++++++++++++++++ 2 files changed, 35 insertions(+) diff --git a/apps/rocm/src/therock/resolve/tarball.rs b/apps/rocm/src/therock/resolve/tarball.rs index 6fcc76db9d..b40b2ab594 100644 --- a/apps/rocm/src/therock/resolve/tarball.rs +++ b/apps/rocm/src/therock/resolve/tarball.rs @@ -551,6 +551,21 @@ mod tests { .map(|(_, version)| version), Some("10.1.0".to_owned()) ); + + // Unpinned, the same catalog keeps "newest upload wins": 10.0.0 was + // uploaded after both 10.1 releases, so it is the pick even though + // its version is lower. Only a line pin orders by version first. + assert_eq!( + select_tarball_candidate( + &files, + TheRockChannel::Release, + SourceLayout::Next, + "gfx120X-all", + None, + ) + .map(|(_, version)| version), + Some("10.0.0".to_owned()) + ); } #[test] diff --git a/apps/rocm/src/therock/source.rs b/apps/rocm/src/therock/source.rs index caf8c59eac..d93f1fa56d 100644 --- a/apps/rocm/src/therock/source.rs +++ b/apps/rocm/src/therock/source.rs @@ -597,6 +597,26 @@ mod tests { "{nightly_error}" ); + // A line pin's refusals name its own major, not the ROCm 10 floor. + let later_line = RuntimeVersionSelector::version("11.2").unwrap(); + let later_nightly_error = + select_source_layout(TheRockChannel::Nightly, &exact, Some(&later_line)) + .expect_err("an 11.2 line pin has no nightly stream") + .to_string(); + assert!( + later_nightly_error.starts_with("ROCm 11 and newer is published only"), + "{later_nightly_error}" + ); + + // A component past u32 is not a line pin. Truncating 2^32 + 10 would + // read it as the ROCm 10 line and leave the canonical index. + let overflowing = RuntimeVersionSelector::version("4294967306.1").unwrap(); + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, Some(&overflowing)).unwrap(), + SourceLayout::Canonical + ); + assert!(!overflowing.matches_version("10.1.0")); + // Routes that already worked must not move. let exact_next = RuntimeVersionSelector::version("10.1.0").unwrap(); assert_eq!( From 90ab5a80aec702db00fc31a711c5e85a4bf9d79c Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 9 Nov 2026 14:45:25 +0200 Subject: [PATCH 05/11] docs(testing): say a wheel line pin can pick a four-component release The comparison section said a four-component release such as 7.2.4.70204 is never picked on the release channel. That holds for an unpinned pick and for the tarball catalog, but a wheel `--version 7.2` selects it. Also move the `--version` paragraph below the dry-run verification list it had split from its introduction. Signed-off-by: Roman Inflianskas --- docs/testing.md | 41 +++++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/testing.md b/docs/testing.md index 17b98c0360..56ca5acd30 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -909,20 +909,6 @@ The `update_check` tool and the plain `rocm update` check (no `--apply`) are not previews in this sense: on a ROCm 10 or newer runtime they resolve with `uv` and can fetch it. They prepare no Python, though (see `update-09` and `update-10`). -`--version` accepts a `major.minor` line as well as an exact -`major.minor.patch`. `--version 10.1` resolves the newest stable 10.1.x on the -ROCm 10 next layout, and `--version 7.14` the newest stable 7.14.x on the -canonical index. When a ROCm 10 pin cannot be satisfied, the error lists the -other stable ROCm 10 releases that layout publishes, if any, and suggests one -of them, never the release that just failed and never `--channel nightly`. -Loopback-fixture scenarios in -[therock_next_generation.feature](../tests/e2e-cucumber/features/therock_next_generation.feature) -cover this: `therock-next-16` (a wheel line pin), `therock-next-17` (the -failure, which re-runs the suggested command to prove it succeeds) and -`therock-next-18` (a tarball line pin takes the newest release in the line, not -the newest upload). They run in the default e2e lane; `therock-next-18` is -Linux-only because Windows refuses tarball installs. - Then it verifies: - runtime manifest metadata @@ -947,6 +933,20 @@ Then it verifies: `rocm_sdk.find_libraries("amdhip64", "hipblas")` - vLLM adapter discovery of the managed TheRock runtime environment +`--version` accepts a `major.minor` line as well as an exact +`major.minor.patch`. `--version 10.1` resolves the newest stable 10.1.x on the +ROCm 10 next layout, and `--version 7.14` the newest stable 7.14.x on the +canonical index. When a ROCm 10 pin cannot be satisfied, the error lists the +other stable ROCm 10 releases that layout publishes, if any, and suggests one +of them, never the release that just failed and never `--channel nightly`. +Loopback-fixture scenarios in +[therock_next_generation.feature](../tests/e2e-cucumber/features/therock_next_generation.feature) +cover this: `therock-next-16` (a wheel line pin), `therock-next-17` (the +failure, which re-runs the suggested command to prove it succeeds) and +`therock-next-18` (a tarball line pin takes the newest release in the line, not +the newest upload). They run in the default e2e lane; `therock-next-18` is +Linux-only because Windows refuses tarball installs. + Run the full live test with auto-detected GPU family: ```bash @@ -2585,10 +2585,15 @@ compare them in one PEP 440 order over published version strings (`7.9` < `7.10.0`, `7.0.0b1` < `7.0.0rc1` < `7.0.0` < `7.0.0.post1`, `7.2.4.70204` above `7.2.4`). That covers picking the newest ROCm version from a wheel index, breaking ties between tarball builds uploaded at the same time, and the -update-or-not verdict. It does not decide everything on its own: tarball builds -are picked by upload time first, and on the release channel only a stable -version in the strict `X.Y.Z` shape is a candidate at all, so a four-component -release such as `7.2.4.70204` is never picked there. The property tests check +update-or-not verdict. It does not decide everything on its own: an unpinned +tarball pick goes by upload time first (a `major.minor` line pin such as +`--version 10.1` goes by this order first), and without a `--version` pin the +release channel takes only a stable version in the strict `X.Y.Z` shape, so an +unpinned pick never lands on a four-component release such as `7.2.4.70204`. +A wheel line pin is different: `--version 7.2` selects the newest stable +release in the 7.2 line, `7.2.4.70204` included. The tarball catalog still +requires the strict shape, so the same line pin cannot pick that release +there. The property tests check that the order is total, that picks do not depend on the order the index lists versions in, and that the update verdict points the same way as the order. Two spellings of one version (`7.0.0-rc1` and `7.0.0rc1`) are not offered as an From 7d9faf021f7998321cc4fe460a6bc0a0e7a87941 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 10 Nov 2026 13:35:50 +0200 Subject: [PATCH 06/11] fix(sdk): suggest a ROCm 10 release only when another version can help A failed ROCm 10 resolution used to append the list of published releases and a --version/--family re-run to every error, including failures no other release can clear (an unknown device target, a uv that could not be fetched, an unreachable index), and to rocm update, which takes neither flag. Failures a different --version can clear are now raised as a typed VersionUnsatisfied: an unmatched pin, a release with no torchaudio for this Python and platform, a uv pip compile with no solution, and a tarball catalog with no archive for the request. Only those get the release list, which leaves out the release just attempted. A pinned install is told which --version and --family to re-run with. A failed rocm update is given a whole rocm install sdk command that keeps the runtime's format, exact arch and --devel toolchain, and a runtime that recorded no exact arch gets no version advice at all. Signed-off-by: Roman Inflianskas --- apps/rocm/src/therock.rs | 2 +- apps/rocm/src/therock/resolve.rs | 4 +- apps/rocm/src/therock/resolve/next_hint.rs | 482 +++++++++++++++++++++ apps/rocm/src/therock/resolve/tarball.rs | 44 +- apps/rocm/src/therock/resolve/wheel.rs | 434 ++++++++----------- apps/rocm/src/therock/source.rs | 24 + docs/architecture.md | 1 + 7 files changed, 732 insertions(+), 259 deletions(-) create mode 100644 apps/rocm/src/therock/resolve/next_hint.rs diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index 75bccb49b5..f264469720 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -227,7 +227,7 @@ pub(crate) fn install_sdk( && !next_layout_requested(selector) { bail!( - "specific TheRock version selection for tarball installs is only supported for a stable ROCm {THEROCK_NEXT_MIN_MAJOR}+ pin (e.g. `--version 10.0.0`); for any other version, use `--format wheel`" + "specific TheRock version selection for tarball installs is only supported for a stable ROCm {THEROCK_NEXT_MIN_MAJOR}+ pin, exact or a `major.minor` line (e.g. `--version 10.0.0` or `--version 10.1`); for any other version, use `--format wheel`" ) } install_tarball_runtime( diff --git a/apps/rocm/src/therock/resolve.rs b/apps/rocm/src/therock/resolve.rs index 6e1aca6340..68b1ddfe70 100644 --- a/apps/rocm/src/therock/resolve.rs +++ b/apps/rocm/src/therock/resolve.rs @@ -6,8 +6,10 @@ //! declarations and re-exports live here, no logic: `tarball` resolves the SDK //! tarball from the catalog's index, `wheel` resolves the wheel stack from the //! wheel indexes (with `uv_access` deciding who may fetch `uv` while it does), -//! and the rest of `therock` reads the names below. +//! `next_hint` words what a failed ROCm 10 resolution suggests next, and the +//! rest of `therock` reads the names below. +mod next_hint; mod tarball; mod uv_access; mod wheel; diff --git a/apps/rocm/src/therock/resolve/next_hint.rs b/apps/rocm/src/therock/resolve/next_hint.rs new file mode 100644 index 0000000000..f52767427a --- /dev/null +++ b/apps/rocm/src/therock/resolve/next_hint.rs @@ -0,0 +1,482 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! What a failed ROCm 10 resolution tells the user to do next. +//! +//! Only a failure a different `--version` could clear carries a version +//! suggestion. Such a failure is raised as a [`VersionUnsatisfied`]: the +//! requested release is not published, the release it resolved to has no +//! torchaudio for this Python and platform, or `uv` found no jointly +//! installable package set for it. Every other failure gets no version advice: +//! an undetermined device target, a `uv` that could not be fetched or run, or a +//! listing that could not be read. A different version leaves each of those +//! exactly where it was. +//! +//! [`next_layout_unsatisfied_hint`] writes the suggestion. A pinned install +//! (`rocm install sdk --version …`) is told which `--version`/`--family` to +//! re-run with. `rocm update`, which re-resolves an installed runtime with no +//! pin and has no `--family` or `--version` of its own, is given a whole +//! `rocm install sdk` command that keeps the runtime's format and toolchain +//! extras ([`NextLayoutRecovery`]). +//! +//! A leaf child of `therock/resolve.rs` that builds on `therock/source.rs` and +//! `therock/version.rs`. `wheel.rs` and `tarball.rs` raise the marker and call +//! the hint. + +use super::super::source::{RuntimeVersionSelector, THEROCK_NEXT_MIN_MAJOR, next_layout_requested}; +use super::super::version::compare_version_strings; +use std::fmt; + +/// A next-layout resolution failure that a different `--version` could clear. +/// +/// `attempted` is the release the request resolved to before it failed, when it +/// resolved to one. The hint leaves that release out, because suggesting it +/// again cannot help. The resolver that picked it records it here. A hint that +/// re-derived it would have to repeat that resolver's ordering (by version for a +/// wheel listing, by upload time for an unpinned tarball pick) and could get it +/// wrong. +/// +/// Its `Display` is the failure's own message, so raising this in place of a +/// plain error leaves what the user reads unchanged. +#[derive(Debug)] +pub(in crate::therock) struct VersionUnsatisfied { + attempted: Option, + message: String, +} + +impl VersionUnsatisfied { + pub(in crate::therock) fn new(attempted: Option<&str>, message: String) -> Self { + Self { + attempted: attempted.map(str::to_owned), + message, + } + } + + pub(in crate::therock) fn attempted(&self) -> Option<&str> { + self.attempted.as_deref() + } + + /// The marker anywhere in `error`'s chain, whatever context was added on top. + pub(in crate::therock) fn find(error: &anyhow::Error) -> Option<&Self> { + error.chain().find_map(|cause| cause.downcast_ref::()) + } +} + +impl fmt::Display for VersionUnsatisfied { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter.write_str(&self.message) + } +} + +impl std::error::Error for VersionUnsatisfied {} + +/// The artifact kind a failed resolution was for, so a suggested install +/// command installs the same kind. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub(in crate::therock) enum RecoveryFormat { + Wheel, + Tarball, +} + +/// What a suggested command has to carry over from the request that failed. +#[derive(Clone, Copy, Debug)] +pub(in crate::therock) struct NextLayoutRecovery<'a> { + pub(in crate::therock) format: RecoveryFormat, + /// The exact arch the request resolved with, so the command repeats it. + pub(in crate::therock) exact_arch: Option<&'a str>, + /// Whether the runtime has the `devel` toolchain extras. Only an update + /// carries it into the command; a pinned install re-runs its own command, + /// flags included. + pub(in crate::therock) include_devel: bool, +} + +/// How many published releases a next-layout failure lists by name. +const NEXT_LAYOUT_HINT_MAX_LISTED: usize = 5; + +/// Recovery guidance when a ROCm >= 10 request cannot be satisfied on the next +/// layout, for a failure raised as a [`VersionUnsatisfied`]. +/// +/// It never offers `--channel nightly`, because that channel refuses these pins. +/// +/// The suggested `--version` is one the next layout publishes and is never the +/// release that just failed. `published` is that layout's version listing +/// (`None` when the listing could not be read), narrowed to one GPU family when +/// `family_scope` names it. `attempted` is the release the failure recorded, +/// and the hint leaves it out. It also leaves out any release +/// [`next_layout_requested`] would not route back to this layout, so a re-run +/// searches the same layout. When nothing else qualifies, the hint says so and +/// names no command. +/// +/// The command depends on the caller: +/// - A pinned install (`version_selector` is `Some`) is told which +/// `--version`/`--family` pair to re-run with. Its other flags are its own. +/// - `rocm update` (`version_selector` is `None`, because an update re-resolves +/// with no pin) has no such flags. It is given the whole `rocm install sdk` +/// command, with the runtime's format and toolchain extras, so following it +/// installs the same kind of runtime. +pub(in crate::therock) fn next_layout_unsatisfied_hint( + version_selector: Option<&RuntimeVersionSelector>, + published: Option<&[String]>, + attempted: Option<&str>, + recovery: NextLayoutRecovery<'_>, + family_scope: Option<&str>, +) -> String { + let layout = format!("the ROCm {THEROCK_NEXT_MIN_MAJOR}+ next layout"); + let Some(published) = published else { + return format!( + "Could not read the releases {layout} publishes, so no other version can be suggested." + ); + }; + let requested = version_selector.map_or_else( + || "the newest release".to_owned(), + RuntimeVersionSelector::describe, + ); + let scope = family_scope.map_or_else(String::new, |family| format!(" for {family}")); + let lead = match recovery.format { + RecoveryFormat::Wheel => { + format!("No complete compatible package stack was found for {requested} on {layout}.") + } + RecoveryFormat::Tarball => { + format!("No archive{scope} was found for {requested} on {layout}.") + } + }; + let mut alternatives = published + .iter() + .filter(|version| attempted != Some(version.as_str())) + .filter(|version| { + next_layout_requested(&RuntimeVersionSelector::Version((*version).clone())) + }) + .map(String::as_str) + .collect::>(); + alternatives.sort_by(|left, right| compare_version_strings(right, left)); + alternatives.dedup(); + let other = if attempted.is_some() { " other" } else { "" }; + let Some(newest) = alternatives.first() else { + return format!( + "{lead} It publishes no{other} stable release{scope}, so no `--version` pin can install from it yet." + ); + }; + let mut listed = alternatives + .iter() + .take(NEXT_LAYOUT_HINT_MAX_LISTED) + .copied() + .collect::>() + .join(", "); + if alternatives.len() > NEXT_LAYOUT_HINT_MAX_LISTED { + let older = alternatives.len() - NEXT_LAYOUT_HINT_MAX_LISTED; + listed.push_str(", and "); + listed.push_str(&older.to_string()); + listed.push_str(" older"); + } + let command = recovery_command(version_selector.is_some(), newest, recovery); + let label = if attempted.is_some() { + "Other stable releases it publishes" + } else { + "Stable releases it publishes" + }; + format!("{lead} {label}{scope}: {listed}. {command}") +} + +/// The sentence naming what to run. `pinned` is whether the failed request +/// carried a `--version`. +fn recovery_command(pinned: bool, version: &str, recovery: NextLayoutRecovery<'_>) -> String { + // A ROCm 10 pin needs an exact arch, so a placeholder stands in only where + // none is known, which a pinned install never reaches: it is refused + // before resolution without one. + let family = recovery.exact_arch.unwrap_or(""); + let placeholder_note = if recovery.exact_arch.is_none() { + ", where `` is the raw `gfx` code `rocm examine` reports" + } else { + "" + }; + if pinned { + return format!( + "Re-run with one of them, for example `--version {version} --family {family}`{placeholder_note}." + ); + } + let format = match recovery.format { + RecoveryFormat::Wheel => "wheel", + RecoveryFormat::Tarball => "tarball", + }; + let devel = if recovery.include_devel { + " --devel" + } else { + "" + }; + format!( + "Install one of them, for example `rocm install sdk --channel release --format {format} --version {version} --family {family}{devel}`{placeholder_note}." + ) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn versions(list: &[&str]) -> Vec { + list.iter().map(|version| (*version).to_owned()).collect() + } + + const WHEEL_AT_GFX1200: NextLayoutRecovery<'static> = NextLayoutRecovery { + format: RecoveryFormat::Wheel, + exact_arch: Some("gfx1200"), + include_devel: false, + }; + + /// Every state the hint can be reached in. The rules under test: it never + /// suggests the release the failure recorded, never names a command when + /// the index offers nothing else, and a suggested install command + /// installs the same kind of runtime that failed. + #[test] + fn next_layout_unsatisfied_hint_only_suggests_releases_that_were_not_tried() { + let line = RuntimeVersionSelector::version("10.1").unwrap(); + let exact = RuntimeVersionSelector::version("10.1.0").unwrap(); + + // A line pin that resolved to 10.1.2 and could not install it: the + // other 10.1 release is still worth trying, 10.1.2 is not. + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&["10.0.0", "10.1.0", "10.1.2"])), + Some("10.1.2"), + WHEEL_AT_GFX1200, + None, + ); + assert!( + hint.contains("Other stable releases it publishes: 10.1.0, 10.0.0."), + "{hint}" + ); + // A pinned request re-runs its own command with a different + // `--version`, so it is told to re-run, not handed a whole install + // command. The unpinned `rocm update` case below gets the full + // command instead. + assert!( + hint.contains( + "Re-run with one of them, for example `--version 10.1.0 --family gfx1200`." + ), + "{hint}" + ); + assert!(!hint.contains("Install one of them"), "{hint}"); + assert!(!hint.contains("rocm install sdk"), "{hint}"); + assert!(!hint.contains("10.1.2"), "{hint}"); + + // The release the failure recorded is what is left out, not whatever + // version order would pick: an unpinned tarball pick goes by upload + // time, so it can have tried an older release than the newest. + let hint = next_layout_unsatisfied_hint( + None, + Some(&versions(&["10.0.0", "10.1.0", "10.1.2"])), + Some("10.1.0"), + WHEEL_AT_GFX1200, + None, + ); + assert!( + hint.contains("Other stable releases it publishes: 10.1.2, 10.0.0."), + "{hint}" + ); + + // An exact pin that is published but failed is not suggested again. + let hint = next_layout_unsatisfied_hint( + Some(&exact), + Some(&versions(&["10.0.0", "10.1.0"])), + Some("10.1.0"), + WHEEL_AT_GFX1200, + None, + ); + assert!( + hint.contains("`--version 10.0.0 --family gfx1200`"), + "{hint}" + ); + assert!(!hint.contains("--version 10.1.0"), "{hint}"); + + // An exact pin that is the only release: nothing else to suggest, so + // no command is named. + let hint = next_layout_unsatisfied_hint( + Some(&exact), + Some(&versions(&["10.1.0"])), + Some("10.1.0"), + WHEEL_AT_GFX1200, + None, + ); + assert!( + hint.contains("It publishes no other stable release"), + "{hint}" + ); + assert!(!hint.contains("--version 10"), "{hint}"); + + // A pin nothing matched: no release was attempted, and none of the + // published ones is "other". + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&["10.0.0"])), + None, + WHEEL_AT_GFX1200, + None, + ); + assert!( + hint.contains("Stable releases it publishes: 10.0.0. "), + "{hint}" + ); + + // An index with no stable release at all; prereleases are not offered. + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&["10.1.0a20260822"])), + None, + WHEEL_AT_GFX1200, + None, + ); + assert!(hint.contains("It publishes no stable release"), "{hint}"); + assert!(!hint.contains("10.1.0a20260822"), "{hint}"); + assert!(!hint.contains("--version 10"), "{hint}"); + + // The listing itself could not be read: say that, not "no stack was + // found", and suggest nothing. + let hint = next_layout_unsatisfied_hint(Some(&line), None, None, WHEEL_AT_GFX1200, None); + assert!( + hint.starts_with("Could not read the releases the ROCm 10+ next layout publishes"), + "{hint}" + ); + assert!( + !hint.contains("No complete compatible package stack"), + "{hint}" + ); + assert!(!hint.contains("--version 10"), "{hint}"); + + // Only releases a re-run would route back to this layout are offered. + // A four-component or sub-10 publish would re-resolve against the + // canonical index, so suggesting it could not clear the failure. + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&["9.9.0", "10.0.0", "10.0.1.12345"])), + None, + WHEEL_AT_GFX1200, + None, + ); + assert!( + hint.contains("Stable releases it publishes: 10.0.0. "), + "{hint}" + ); + assert!(!hint.contains("10.0.1.12345"), "{hint}"); + assert!(!hint.contains("9.9.0"), "{hint}"); + + // A long listing is capped, newest first. + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&[ + "10.0.0", "10.0.1", "10.0.2", "10.0.3", "10.0.4", "10.0.5", "10.0.6", + ])), + None, + WHEEL_AT_GFX1200, + None, + ); + assert!( + hint.contains("10.0.6, 10.0.5, 10.0.4, 10.0.3, 10.0.2, and 2 older."), + "{hint}" + ); + } + + /// `rocm update` reaches the next layout with no pin. It has no `--family` + /// or `--version` of its own, so the hint names a whole `rocm install sdk` + /// command, and that command installs what the failed runtime was: the same + /// format and the same toolchain extras. + #[test] + fn an_update_is_given_an_install_command_that_keeps_its_format_and_extras() { + let published = versions(&["10.0.0", "10.1.0"]); + + let wheel_with_toolchain = next_layout_unsatisfied_hint( + None, + Some(&published), + Some("10.1.0"), + NextLayoutRecovery { + format: RecoveryFormat::Wheel, + exact_arch: Some("gfx1200"), + include_devel: true, + }, + None, + ); + assert!( + wheel_with_toolchain.contains( + "Install one of them, for example `rocm install sdk --channel release --format wheel --version 10.0.0 --family gfx1200 --devel`." + ), + "{wheel_with_toolchain}" + ); + assert!( + wheel_with_toolchain.contains("for the newest release"), + "{wheel_with_toolchain}" + ); + assert!( + !wheel_with_toolchain.contains("Re-run with one of them"), + "{wheel_with_toolchain}" + ); + assert!( + !wheel_with_toolchain.contains("nightly"), + "{wheel_with_toolchain}" + ); + + let plain_wheel = next_layout_unsatisfied_hint( + None, + Some(&published), + Some("10.1.0"), + WHEEL_AT_GFX1200, + None, + ); + assert!( + plain_wheel.contains( + "`rocm install sdk --channel release --format wheel --version 10.0.0 --family gfx1200`." + ), + "{plain_wheel}" + ); + + // A tarball runtime's update names a tarball install, and the catalog + // it read was the family's, so the hint is about archives, not a + // package stack. A tarball runtime records only its grouped family, so + // no exact arch is known: the command says where to get one, and does + // not claim the update itself takes `--family`. + let tarball = next_layout_unsatisfied_hint( + None, + Some(&published), + None, + NextLayoutRecovery { + format: RecoveryFormat::Tarball, + exact_arch: None, + include_devel: false, + }, + Some("gfx120X-all"), + ); + assert!( + tarball.starts_with( + "No archive for gfx120X-all was found for the newest release on the ROCm 10+ next layout." + ), + "{tarball}" + ); + assert!( + tarball.contains( + "`rocm install sdk --channel release --format tarball --version 10.1.0 --family `, where `` is the raw `gfx` code `rocm examine` reports." + ), + "{tarball}" + ); + assert!(!tarball.contains("package stack"), "{tarball}"); + assert!(!tarball.contains("re-run with `--family`"), "{tarball}"); + } + + /// The marker is found however many context layers sit on top of it, and a + /// failure without one is not mistaken for it. + #[test] + fn the_marker_survives_added_context_and_keeps_its_message() { + let marked = anyhow::Error::new(VersionUnsatisfied::new( + Some("10.1.0"), + "no torchaudio built for ROCm 10.1.0".to_owned(), + )) + .context("failed to resolve") + .context("outer"); + let found = VersionUnsatisfied::find(&marked).expect("marker is in the chain"); + assert_eq!(found.attempted.as_deref(), Some("10.1.0")); + assert!( + format!("{marked:#}").contains("no torchaudio built for ROCm 10.1.0"), + "{marked:#}" + ); + + let plain = anyhow::anyhow!("uv could not be downloaded").context("failed to resolve"); + assert!(VersionUnsatisfied::find(&plain).is_none()); + } +} diff --git a/apps/rocm/src/therock/resolve/tarball.rs b/apps/rocm/src/therock/resolve/tarball.rs index b40b2ab594..fdf3ab2a86 100644 --- a/apps/rocm/src/therock/resolve/tarball.rs +++ b/apps/rocm/src/therock/resolve/tarball.rs @@ -21,7 +21,7 @@ use super::super::source::{ select_source_layout, selector_is_release_line, }; use super::super::version::{compare_version_strings, is_stable_runtime_version}; -use super::wheel::next_layout_unsatisfied_hint; +use super::next_hint::{NextLayoutRecovery, RecoveryFormat, next_layout_unsatisfied_hint}; use anyhow::{Context, Result, bail}; use rocm_core::AppPaths; use serde::Deserialize; @@ -91,8 +91,12 @@ pub(in crate::therock) fn resolve_tarball_artifact_with_timeout( )? .text; let files = parse_tarball_index_html(&html).with_context(|| { + let catalog = match layout { + SourceLayout::Canonical => "canonical", + SourceLayout::Next => "next-layout", + }; format!( - "unknown canonical TheRock tarball catalog layout at {}", + "unknown {catalog} TheRock tarball catalog layout at {}", source.tarball_catalog ) })?; @@ -221,6 +225,13 @@ fn select_tarball_candidate( candidates.pop() } +/// The context added when [`select_tarball_candidate`] finds no archive. +/// +/// That is the only failure it wraps, and a different `--version` can clear +/// it, so on the next layout it is always followed by the list of releases to +/// try. No archive was picked, so no release counts as attempted. The +/// suggested command is a tarball install. It carries no `devel` extras, +/// because a tarball has none. fn tarball_resolution_failure_context( channel: TheRockChannel, layout: SourceLayout, @@ -234,7 +245,12 @@ fn tarball_resolution_failure_context( next_layout_unsatisfied_hint( version_selector, Some(published), - family_resolution.raw_arch.as_deref(), + None, + NextLayoutRecovery { + format: RecoveryFormat::Tarball, + exact_arch: family_resolution.raw_arch.as_deref(), + include_devel: false, + }, Some(&family_resolution.family), ), ), @@ -588,6 +604,28 @@ mod tests { "{next}" ); assert!(!next.contains("nightly"), "{next}"); + // An archive catalog has no package stack to speak of. + assert!( + next.contains("No archive for gfx120X-all was found for version 10.1"), + "{next}" + ); + assert!(!next.contains("package stack"), "{next}"); + + // `rocm update` re-resolves a tarball runtime with no pin. The command + // it is given installs a tarball, not the default wheel. + let update = tarball_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Next, + &family, + None, + &["10.0.0".to_owned()], + ); + assert!( + update.contains( + "`rocm install sdk --channel release --format tarball --version 10.0.0 --family gfx1200`" + ), + "{update}" + ); let canonical = tarball_resolution_failure_context( TheRockChannel::Release, diff --git a/apps/rocm/src/therock/resolve/wheel.rs b/apps/rocm/src/therock/resolve/wheel.rs index 7a279fa1b5..7fdec56381 100644 --- a/apps/rocm/src/therock/resolve/wheel.rs +++ b/apps/rocm/src/therock/resolve/wheel.rs @@ -43,11 +43,14 @@ use super::super::python::WheelCompatibility; use super::super::slugify; use super::super::source::{ FamilyResolution, RuntimeVersionSelector, SourceLayout, THEROCK_NEXT_MIN_MAJOR, TheRockChannel, - next_layout_requested, resolve_source, select_source_layout, + resolve_source, select_source_layout, }; use super::super::version::{ ParsedVersion, compare_version_strings, is_stable_runtime_version, parse_version, }; +use super::next_hint::{ + NextLayoutRecovery, RecoveryFormat, VersionUnsatisfied, next_layout_unsatisfied_hint, +}; use super::uv_access::{ UvAccess, UvPolicy, VersionResolution, plan_version_resolution, uv_for_compile, }; @@ -763,8 +766,12 @@ fn resolve_pip_runtime_plan( let root_html = download_text_cached(paths, &root_cache_key, &root_url, download_timeout_secs)?.text; validate_aggregate_index_layout(&root_html).with_context(|| { + let source_label = match layout { + SourceLayout::Canonical => "canonical source", + SourceLayout::Next => "next-layout source", + }; format!( - "failed to resolve TheRock {} wheel runtime from canonical source {}", + "failed to resolve TheRock {} wheel runtime from {source_label} {}", channel.as_str(), source.wheel_index ) @@ -791,7 +798,11 @@ fn resolve_pip_runtime_plan( }; // Loaded here rather than inside `resolve_pip_runtime_from_index` so a // failure further down can name the releases this index does publish. - let exact_arch = family_resolution.raw_arch.as_deref(); + let recovery = NextLayoutRecovery { + format: RecoveryFormat::Wheel, + exact_arch: family_resolution.raw_arch.as_deref(), + include_devel, + }; let rocm_versions = load_simple_index_versions( paths, &source.index_url, @@ -806,7 +817,8 @@ fn resolve_pip_runtime_plan( &source.index_url, version_selector, None, - exact_arch, + None, + recovery, ) })?; resolve_pip_runtime_from_index( @@ -821,15 +833,17 @@ fn resolve_pip_runtime_plan( download_timeout_secs, &uv, ) - .with_context(|| { - wheel_resolution_failure_context( + .map_err(|error| { + let context = wheel_resolution_failure_context( channel, layout, &source.index_url, version_selector, Some(&rocm_versions), - exact_arch, - ) + VersionUnsatisfied::find(&error), + recovery, + ); + error.context(context) }) } @@ -924,12 +938,15 @@ fn resolve_pip_runtime_from_index( } }; let rocm_version = select_rocm_version(channel, rocm_versions, version_selector) - .with_context(|| { + .ok_or_else(|| { let requested = version_selector.map_or_else( || "latest compatible version".to_owned(), RuntimeVersionSelector::describe, ); - format!("no TheRock rocm package was found for {requested} in {index_url}") + VersionUnsatisfied::new( + None, + format!("no TheRock rocm package was found for {requested} in {index_url}"), + ) })?; // Chosen here, not by `uv`: see `published_pip_requirements`. let torchaudio_versions = load_simple_index_versions( @@ -980,6 +997,7 @@ fn resolve_pip_runtime_from_index( let versions = resolve_published_pip_package_versions( paths, &compile_uv, + &rocm_version, index_url, &requirements, wheel_compatibility, @@ -1112,6 +1130,7 @@ fn parse_uv_compiled_package_versions(output: &str) -> Result anyhow::Error { + let detail = stderr.trim(); + let message = format!("published ROCm X package metadata is not jointly installable: {detail}"); + if detail.contains("No solution found") { + VersionUnsatisfied::new(Some(rocm_version), message).into() + } else { + anyhow::Error::msg(message) + } +} + fn select_matching_pip_package_versions( channel: TheRockChannel, rocm_versions: &[String], @@ -1347,9 +1385,15 @@ fn torchaudio_pin( ) -> Result { let built_for_rocm = package_versions_matching_rocm(published, rocm_version); if built_for_rocm.is_empty() { - bail!( - "no torchaudio built for ROCm {rocm_version} is published for this Python and platform in {index_url}" - ); + // Another ROCm release can publish a torchaudio this host can install, + // so a different `--version` can clear this one. + return Err(VersionUnsatisfied::new( + Some(rocm_version), + format!( + "no torchaudio built for ROCm {rocm_version} is published for this Python and platform in {index_url}" + ), + ) + .into()); } let pin = |version, basis| TorchaudioPin { version, @@ -1535,123 +1579,63 @@ fn canonical_wheel_resolution_hint(channel: TheRockChannel) -> String { hint } -/// The sentence appended when wheel resolution fails. +/// The context added when wheel resolution fails. /// /// A ROCm >= 10 pin already refused `--channel nightly` before resolution /// (`select_source_layout`), so the canonical hint's nightly suggestion must -/// not be what that failure prints. The next-layout branch points at the -/// layout that was searched and at the releases it does publish; see -/// [`next_layout_unsatisfied_hint`]. `published` is `None` when the `rocm` -/// listing itself could not be read. +/// not be what a next-layout failure prints. On the next layout: +/// - `published` is `None` when the `rocm` listing itself could not be read, +/// and the context says no other version can be suggested. +/// - `unsatisfied` is the [`VersionUnsatisfied`] in the failure's chain. Only +/// such a failure is followed by [`next_layout_unsatisfied_hint`]'s list of +/// releases to try, because only it can be cleared by another `--version`. +/// - Any other failure gets the source line alone. Its own message (an +/// undetermined device target, a `uv` that could not run, an unreachable +/// index) is the advice, and a version suggestion would send the user to a +/// re-run that meets the same failure. fn wheel_resolution_failure_context( channel: TheRockChannel, layout: SourceLayout, index_url: &str, version_selector: Option<&RuntimeVersionSelector>, published: Option<&[String]>, - exact_arch: Option<&str>, + unsatisfied: Option<&VersionUnsatisfied>, + recovery: NextLayoutRecovery<'_>, ) -> String { let (source_label, hint) = match layout { - SourceLayout::Next => ( - "next-layout source", - next_layout_unsatisfied_hint(version_selector, published, exact_arch, None), + SourceLayout::Next => { + let hint = match (published, unsatisfied) { + (None, _) => Some(next_layout_unsatisfied_hint( + version_selector, + None, + None, + recovery, + None, + )), + (Some(published), Some(unsatisfied)) => Some(next_layout_unsatisfied_hint( + version_selector, + Some(published), + unsatisfied.attempted(), + recovery, + None, + )), + (Some(_), None) => None, + }; + ("next-layout source", hint) + } + SourceLayout::Canonical => ( + "canonical source", + Some(canonical_wheel_resolution_hint(channel)), ), - SourceLayout::Canonical => ("canonical source", canonical_wheel_resolution_hint(channel)), }; - format!( - "failed to resolve TheRock {} wheel runtime from {source_label} {index_url}\n\n{hint}", + let head = format!( + "failed to resolve TheRock {} wheel runtime from {source_label} {index_url}", channel.as_str() - ) -} - -/// How many published releases a next-layout failure lists by name. -const NEXT_LAYOUT_HINT_MAX_LISTED: usize = 5; - -/// Recovery guidance when a ROCm >= 10 request cannot be satisfied on the next layout. -/// -/// Does not offer `--channel nightly`: that channel refuses these pins, and -/// the refusal tells the user to come back to the release channel. -/// -/// The suggested `--version` is one the next layout actually publishes, never -/// the request that just failed. `published` is that layout's version listing -/// (`None` when the listing itself could not be read), narrowed to one GPU -/// family when `family_scope` names it. The release the failed request -/// resolved to is derived with [`select_rocm_version`], the function that -/// chose it, and left out: a line pin that failed on `10.1.2` must not be told -/// to try `10.1.2` again. Only releases [`next_layout_requested`] would route -/// back to this layout are offered, so a re-run with the suggestion searches -/// the same layout rather than the canonical one. When nothing else qualifies -/// the hint says so and names no command, because no `--version` pin could -/// succeed. `exact_arch` is the arch the failed request resolved with, so the -/// suggested command repeats it. Without one this layout cannot resolve any -/// version, so the hint asks for `--family` instead of a version. -pub(in crate::therock) fn next_layout_unsatisfied_hint( - version_selector: Option<&RuntimeVersionSelector>, - published: Option<&[String]>, - exact_arch: Option<&str>, - family_scope: Option<&str>, -) -> String { - let layout = format!("the ROCm {THEROCK_NEXT_MIN_MAJOR}+ next layout"); - let Some(published) = published else { - return format!( - "Could not read the releases {layout} publishes, so no other version can be suggested." - ); - }; - let requested = version_selector.map_or_else( - || "the requested release".to_owned(), - RuntimeVersionSelector::describe, ); - let lead = - format!("No complete compatible package stack was found for {requested} on {layout}."); - let Some(exact_arch) = exact_arch else { - return format!( - "{lead} That layout needs an exact GPU arch: re-run with `--family` set to the raw `gfx` code `rocm examine` reports." - ); - }; - let scope = family_scope.map_or_else(String::new, |family| format!(" for {family}")); - let attempted = select_rocm_version(TheRockChannel::Release, published, version_selector); - let mut alternatives = published - .iter() - .filter(|version| attempted.as_deref() != Some(version.as_str())) - .filter(|version| { - next_layout_requested(&RuntimeVersionSelector::Version((*version).clone())) - }) - .map(String::as_str) - .collect::>(); - alternatives.sort_by(|left, right| compare_version_strings(right, left)); - alternatives.dedup(); - let other = if attempted.is_some() { " other" } else { "" }; - let Some(newest) = alternatives.first() else { - return format!( - "{lead} It publishes no{other} stable release{scope}, so no `--version` pin can install from it yet." - ); - }; - let mut listed = alternatives - .iter() - .take(NEXT_LAYOUT_HINT_MAX_LISTED) - .copied() - .collect::>() - .join(", "); - if alternatives.len() > NEXT_LAYOUT_HINT_MAX_LISTED { - let older = alternatives.len() - NEXT_LAYOUT_HINT_MAX_LISTED; - listed.push_str(", and "); - listed.push_str(&older.to_string()); - listed.push_str(" older"); - } - let command = match version_selector { - Some(_) => format!( - "Re-run with one of them, for example `--version {newest} --family {exact_arch}`." - ), - None => format!( - "Install one of them, for example `rocm install sdk --channel release --version {newest} --family {exact_arch}`." - ), - }; - let label = if attempted.is_some() { - "Other stable releases it publishes" - } else { - "Stable releases it publishes" - }; - format!("{lead} {label}{scope}: {listed}. {command}") + match hint { + Some(hint) => format!("{head}\n\n{hint}"), + None => head, + } } #[cfg(test)] @@ -3309,6 +3293,12 @@ sdk install } } + const WHEEL_AT_GFX1201: NextLayoutRecovery<'static> = NextLayoutRecovery { + format: RecoveryFormat::Wheel, + exact_arch: Some("gfx1201"), + include_devel: false, + }; + /// The wording is produced by [`wheel_resolution_failure_context`], which /// `resolve_pip_runtime_plan` appends when resolution fails. The /// install that prints it, and the re-run that proves its suggestion @@ -3317,13 +3307,16 @@ sdk install fn unsatisfied_rocm_10_line_pin_does_not_suggest_nightly() { let line = RuntimeVersionSelector::version("10.1").unwrap(); let published = vec!["10.0.0".to_owned()]; + let unsatisfied = + VersionUnsatisfied::new(None, "no TheRock rocm package was found".to_owned()); let message = wheel_resolution_failure_context( TheRockChannel::Release, SourceLayout::Next, THEROCK_NEXT_PIP_INDEX_BASE, Some(&line), Some(&published), - Some("gfx1201"), + Some(&unsatisfied), + WHEEL_AT_GFX1201, ); assert!( !message.contains("nightly"), @@ -3349,171 +3342,104 @@ sdk install None, Some(&published), None, + WHEEL_AT_GFX1201, ); assert!(canonical.contains("--channel nightly"), "{canonical}"); assert!(canonical.contains("canonical source"), "{canonical}"); } - /// Every state [`next_layout_unsatisfied_hint`] can be reached in. The - /// rule under test: the hint never suggests the release the failed - /// request resolved to, and never names a command when the index offers - /// nothing else. + /// A next-layout failure a different `--version` cannot clear gets no + /// version advice: only the source it searched. An undetermined device + /// target, a `uv` that could not be fetched and an unreachable index each + /// fail again on any release, so naming one would send the user to a + /// re-run that meets the same error. The end-to-end case, an update whose + /// runtime records no exact arch, is therock-next-20. #[test] - fn next_layout_unsatisfied_hint_only_suggests_releases_that_were_not_tried() { - let versions = |list: &[&str]| list.iter().map(|v| (*v).to_owned()).collect::>(); + fn a_next_layout_failure_no_version_can_clear_suggests_no_version() { let line = RuntimeVersionSelector::version("10.1").unwrap(); - let exact = RuntimeVersionSelector::version("10.1.0").unwrap(); - - // A line pin whose newest release (10.1.2) was found but could not be - // installed: the other 10.1 release is still worth trying, 10.1.2 is not. - let hint = next_layout_unsatisfied_hint( + let published = vec!["10.0.0".to_owned(), "10.1.0".to_owned()]; + let context = wheel_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Next, + THEROCK_NEXT_PIP_INDEX_BASE, Some(&line), - Some(&versions(&["10.0.0", "10.1.0", "10.1.2"])), - Some("gfx1200"), - None, - ); - assert!( - hint.contains("Other stable releases it publishes: 10.1.0, 10.0.0."), - "{hint}" - ); - assert!( - hint.contains("`--version 10.1.0 --family gfx1200`"), - "{hint}" - ); - assert!(!hint.contains("10.1.2"), "{hint}"); - // A pinned request re-runs its own command with a different - // `--version`, so it is told to re-run, not handed a whole install - // command. The unpinned `rocm update --apply` case below gets the full - // command instead. - assert!( - hint.contains("Re-run with one of them, for example `--version 10.1.0"), - "{hint}" - ); - assert!(!hint.contains("Install one of them"), "{hint}"); - assert!(!hint.contains("rocm install sdk"), "{hint}"); - - // An exact pin that is published but failed is not suggested again. - let hint = next_layout_unsatisfied_hint( - Some(&exact), - Some(&versions(&["10.0.0", "10.1.0"])), - Some("gfx1200"), - None, - ); - assert!( - hint.contains("`--version 10.0.0 --family gfx1200`"), - "{hint}" - ); - assert!(!hint.contains("--version 10.1.0"), "{hint}"); - - // An exact pin that is the only release: nothing else to suggest, so - // no command is named. - let hint = next_layout_unsatisfied_hint( - Some(&exact), - Some(&versions(&["10.1.0"])), - Some("gfx1200"), + Some(&published), None, + WHEEL_AT_GFX1201, ); - assert!( - hint.contains("It publishes no other stable release"), - "{hint}" + assert_eq!( + context, + format!( + "failed to resolve TheRock release wheel runtime from next-layout source {THEROCK_NEXT_PIP_INDEX_BASE}" + ) ); - assert!(!hint.contains("--version 10"), "{hint}"); - // An index with no stable release at all; prereleases are not offered. - let hint = next_layout_unsatisfied_hint( + // The listing itself could not be read: say so, still without a version. + let unreadable = wheel_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Next, + THEROCK_NEXT_PIP_INDEX_BASE, Some(&line), - Some(&versions(&["10.1.0a20260822"])), - Some("gfx1200"), - None, - ); - assert!(hint.contains("It publishes no stable release"), "{hint}"); - assert!(!hint.contains("10.1.0a20260822"), "{hint}"); - assert!(!hint.contains("--version 10"), "{hint}"); - - // `rocm update --apply` reaches the next layout with no selector. The - // newest release is the one it tried; the hint offers the full - // install command for an older one. - let hint = next_layout_unsatisfied_hint( None, - Some(&versions(&["10.0.0", "10.1.0"])), - Some("gfx1200"), None, + WHEEL_AT_GFX1201, ); - assert!(hint.contains("the requested release"), "{hint}"); - assert!( - hint.contains("`rocm install sdk --channel release --version 10.0.0 --family gfx1200`"), - "{hint}" - ); - assert!( - hint.contains("Install one of them, for example `rocm install sdk"), - "{hint}" - ); - assert!(!hint.contains("Re-run with one of them"), "{hint}"); - assert!(!hint.contains("--version 10.1.0"), "{hint}"); - assert!(!hint.contains("nightly"), "{hint}"); - - // No exact arch (only reachable through `rocm update --apply`): this - // layout cannot resolve any version without one, so the hint asks for - // `--family` and suggests no version. - let hint = - next_layout_unsatisfied_hint(Some(&line), Some(&versions(&["10.0.0"])), None, None); - assert!(hint.contains("needs an exact GPU arch"), "{hint}"); - assert!(hint.contains("`--family`"), "{hint}"); - assert!(!hint.contains("--version 10"), "{hint}"); - - // The listing itself could not be read: say that, not "no stack was - // found", and suggest nothing. - let hint = next_layout_unsatisfied_hint(Some(&line), None, Some("gfx1200"), None); assert!( - hint.starts_with("Could not read the releases the ROCm 10+ next layout publishes"), - "{hint}" - ); - assert!( - !hint.contains("No complete compatible package stack"), - "{hint}" + unreadable.contains("so no other version can be suggested"), + "{unreadable}" ); - assert!(!hint.contains("--version 10"), "{hint}"); + assert!(!unreadable.contains("--version"), "{unreadable}"); + } - // Only releases a re-run would route back to this layout are offered. - // A four-component or sub-10 publish would re-resolve against the - // canonical index, so suggesting it could not clear the failure. - let hint = next_layout_unsatisfied_hint( - Some(&line), - Some(&versions(&["9.9.0", "10.0.0", "10.0.1.12345"])), - Some("gfx1200"), + /// The three failures a different release can clear are raised as the + /// marker, each recording the release it tried where there was one, and + /// each keeping its own message. + #[test] + fn the_version_clearable_failures_are_marked_and_the_rest_are_not() { + // No torchaudio for this release on this platform. + let error = torchaudio_pin( + &["2.11.0+rocm10.1.0".to_owned()], + "10.0.0", None, - ); + "https://index.test", + ) + .expect_err("no torchaudio is built for ROCm 10.0.0"); + let marker = VersionUnsatisfied::find(&error).expect("a missing torchaudio is marked"); + assert_eq!(marker.attempted(), Some("10.0.0")); assert!( - hint.contains("Stable releases it publishes: 10.0.0. "), - "{hint}" + error + .to_string() + .starts_with("no torchaudio built for ROCm 10.0.0 is published"), + "{error}" ); - assert!(!hint.contains("10.0.1.12345"), "{hint}"); - assert!(!hint.contains("9.9.0"), "{hint}"); - // A family-scoped listing (the tarball catalog) says so. - let hint = next_layout_unsatisfied_hint( - Some(&line), - Some(&versions(&[])), - Some("gfx1200"), - Some("gfx120X-all"), + // `uv` found no solution for the release: marked. + let unsatisfiable = uv_compile_failure( + "10.1.0", + " x No solution found when resolving dependencies:\n torch==2.11.0 is unavailable\n", + ); + assert_eq!( + VersionUnsatisfied::find(&unsatisfiable).and_then(VersionUnsatisfied::attempted), + Some("10.1.0") ); assert!( - hint.contains("It publishes no stable release for gfx120X-all"), - "{hint}" + unsatisfiable.to_string().starts_with( + "published ROCm X package metadata is not jointly installable: x No solution found" + ), + "{unsatisfiable}" ); - // A long listing is capped, newest first. - let hint = next_layout_unsatisfied_hint( - Some(&line), - Some(&versions(&[ - "10.0.0", "10.0.1", "10.0.2", "10.0.3", "10.0.4", "10.0.5", "10.0.6", - ])), - Some("gfx1200"), - None, + // `uv` could not reach the index: not marked, same message shape. + let unreachable = uv_compile_failure( + "10.1.0", + "error: Failed to fetch: `http://127.0.0.1:9/next/torch/`\n Connection refused\n", ); + assert!(VersionUnsatisfied::find(&unreachable).is_none()); assert!( - hint.contains("10.0.6, 10.0.5, 10.0.4, 10.0.3, 10.0.2, and 2 older."), - "{hint}" + unreachable + .to_string() + .starts_with("published ROCm X package metadata is not jointly installable: error: Failed to fetch"), + "{unreachable}" ); } } diff --git a/apps/rocm/src/therock/source.rs b/apps/rocm/src/therock/source.rs index d93f1fa56d..ed5378889c 100644 --- a/apps/rocm/src/therock/source.rs +++ b/apps/rocm/src/therock/source.rs @@ -597,6 +597,30 @@ mod tests { "{nightly_error}" ); + // A post-release is not a release of the line: the release channel + // installs only `X.Y.Z` stables (`is_stable_runtime_version`), and a + // line pin must not reach what an unpinned pick on that channel skips. + assert!(!line.matches_version("10.1.0.post1")); + assert_eq!( + select_rocm_version( + TheRockChannel::Release, + &["10.1.0".to_owned(), "10.1.0.post1".to_owned()], + Some(&line), + ) + .as_deref(), + Some("10.1.0") + ); + + // PEP 440 reads release components as integers, so `10.01` is `10.1`, + // as `uv` and pip read it. It routes and matches as the 10.1 line. + let zero_padded = RuntimeVersionSelector::version("10.01").unwrap(); + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, Some(&zero_padded)).unwrap(), + SourceLayout::Next + ); + assert!(zero_padded.matches_version("10.1.2")); + assert!(!zero_padded.matches_version("10.10.0")); + // A line pin's refusals name its own major, not the ROCm 10 floor. let later_line = RuntimeVersionSelector::version("11.2").unwrap(); let later_nightly_error = diff --git a/docs/architecture.md b/docs/architecture.md index bcca9d8f84..327ed482b3 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -118,6 +118,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`therock/python.rs`](../apps/rocm/src/therock/python.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/io.rs`, `therock/process.rs` and `therock/source.rs` (split out of `therock.rs`): the Python an install runs on. `python_requirement` maps a `SourceLayout` to the interpreter the layout needs (`PythonRequirement`: wheel tag and `uv` version), which is why `source.rs` had to move first; `resolve_python_launcher` finds one in order of an explicit `ROCM_CLI_PYTHON`, `PATH`, the saved managed Python, then `ensure_managed_python`, which installs one through `uv` and records it in the managed-Python manifest; the resolver reads its environment through `PythonResolverEnv`, so tests steer it with a thread-local override (`OverridePythonResolverEnv`) rather than rewriting `PATH`; `wheel_compatibility_for_python` and `current_platform_wheel_tags` report the wheel tags an interpreter and platform accept (`WheelCompatibility`); `ensure_uv_venv` creates, or recreates when the interpreter tag no longer matches, the runtime's virtual environment. `plan_python_launcher` is the same lookup for a caller that must change nothing, an install preview or an update check: it returns a `PlannedPython`, either `Ready` with the interpreter a real install would pick or `WouldPrepareManaged` with the managed Python a real install would prepare and this caller did not, and it raises the refusals the real resolution raises before that step. `python_for_install` is the install's one choice between that and `resolve_python_launcher`, and prints the progress line that names the interpreter; `PlannedPython` also writes the `python_note:` line from the decision itself, `note` for an install preview and `update_note` for an update check, so a note cannot name a version the install will not prepare. `venv_python_path` stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The items `therock.rs` reaches, `plan_python_launcher` with `PlannedPython`'s `wheel_compatibility` and `update_note`, which `therock/update.rs` reads, and `split_runtime_path`, which `therock/probe.rs` reads, are `pub(super)`; the rest is private, including `ensure_managed_python` and `resolve_python_launcher_in` (the resolver's entry point that takes its environment as an argument). Its Unix-only tests drive fake interpreters and `uv` scripts. - [`therock/probe.rs`](../apps/rocm/src/therock/probe.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/process.rs` and `therock/python.rs` (split out of `therock.rs`): asking an installed runtime about itself through its own interpreter. `probe_rocm_sdk_runtime` runs `ROCM_SDK_PROBE_SCRIPT` and parses what `rocm_sdk` reports into the `RocmSdkPythonProbe` that [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) owns and validates; `probe_runtime_devices` runs `RUNTIME_DEVICE_PROBE_SCRIPT` to count the devices the runtime's torch can open and whether one can run a kernel (`RuntimeDeviceProbe`); `probe_torch_alignment` reads the installed torch and the one an engine pins from distribution metadata without importing torch (`TorchAlignmentProbe`); and `split_local_version`, `requirement_pinned_version` and `install_pinned_package` are the torch-pin helpers [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) uses to put the SDK's torch back after an engine install. The `pub(crate)` items are re-exported by `therock.rs` for [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) and [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs); `probe_rocm_sdk_runtime_for_target`, which `install_wheel_runtime` calls with the device payload it just chose, is `pub(super)`. - [`therock/resolve.rs`](../apps/rocm/src/therock/resolve.rs) — a child of `therock.rs` that holds no logic (split out of `therock.rs`): only the `mod` declarations for the artifact-resolution modules under `therock/resolve/` and the `pub(super) use` lines through which `therock.rs` reads them. It is the parent the `resolve/` files hang from, so a module there is `pub(in crate::therock)` for the items `therock.rs` reaches and private otherwise. +- [`therock/resolve/next_hint.rs`](../apps/rocm/src/therock/resolve/next_hint.rs) — full domain extraction, a leaf child of `therock/resolve.rs` that builds on `therock/source.rs` and `therock/version.rs` (split out of `therock/resolve/wheel.rs` to keep it within the module-size limit): what a failed ROCm 10 resolution suggests next. A failure a different `--version` can clear is raised as a `VersionUnsatisfied`, which carries the release the resolver attempted and displays as the failure's own message. `wheel.rs` raises one for an unmatched pin, a missing torchaudio or a `uv pip compile` with no solution, and `tarball.rs` treats its no-archive failure the same way. `VersionUnsatisfied::find` looks for one anywhere in an error's chain. `next_layout_unsatisfied_hint` lists the stable releases the layout publishes, leaving out the attempted one and any release a re-run would route back to the canonical index. A pinned install is told which `--version`/`--family` to re-run with. `rocm update`, which re-resolves with no pin, is given a whole `rocm install sdk` command, and `NextLayoutRecovery` carries the format, exact arch and `devel` extras that command keeps. Any other failure gets no version advice. Everything is `pub(in crate::therock)` and read by `wheel.rs` and `tarball.rs`. - [`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/fetch.rs`, `therock/family.rs`, `therock/source.rs` and `therock/version.rs` (split out of `therock.rs`): resolving the SDK tarball a request installs. `resolve_tarball_artifact` (and `resolve_tarball_artifact_with_timeout`, which takes the metadata download timeout) resolves the family and source layout, downloads the catalog through the cached metadata fetch, and returns the `TarballArtifact` it chose; `parse_tarball_index_html` reads the catalog's embedded file list into `TarballIndexFile`s and `validate_tarball_file_name` refuses an entry that is not a plain file name; `select_tarball_candidate` picks the newest archive the request can install, with `tarball_family_token` spelling the family the way the next layout's catalog does. `platform_tarball_token`, which names the archives' platform, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. Only `resolve_tarball_artifact*` and `TarballArtifact` are visible beyond this file. - [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/family.rs`, `therock/fetch.rs`, `therock/process.rs`, `therock/python.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for `WheelRuntimeComposition` (split out of `therock.rs`): resolving the wheel stack a request installs. `resolve_pip_runtime` (and `resolve_pip_runtime_with_timeout`, which takes the metadata download timeout and an optional source layout) resolves the family and the layout, reads the aggregate root, decides the device payload and returns a `PipRuntimeResolution`; on the canonical layout `select_matching_pip_package_versions` then takes the newest `rocm` whose `torch`, `torchvision` and `torchaudio` listings agree, and on the next layout `torchaudio_pin` pins a torchaudio first (the hardware-verified release when it is published, read from the vLLM engine's table) and `resolve_published_pip_package_versions` has `uv pip compile` choose the rest. That compile is the one step that may fetch `uv`, so who may is decided in one pure function, [`therock/resolve/uv_access.rs`](../apps/rocm/src/therock/resolve/uv_access.rs)'s `plan_version_resolution`, which takes the layout, a `UvAccess` and whether a `uv` is present, and answers scrape the indexes (canonical), compile with a `UvChoice` (acquire the managed `uv`, or use the present one) or skip. `resolve_pip_runtime` and `resolve_pip_runtime_with_timeout` (a real install and `rocm update`) are always `UvAccess::Acquire`, which never skips and never asks whether a `uv` is present; `preview_pip_runtime` is `UvAccess::PresentOnly`, which uses a present `uv` (`rocm_core::find_uv_binary`) and otherwise returns `PipRuntimePlan::NeedsUv` holding an `UnresolvedPipRuntime`: what was chosen without `uv` (the `rocm` version, the torchaudio pin, the requirements `uv` would be given) and no package versions, so nothing made from them can be built from it. `wheel.rs` acts on the answer; the real `find_uv_binary` and `ensure_uv_binary` reach it through a `UvPolicy` so that a test can count the calls. `wheel_runtime_composition` turns a resolution into the exact package specs (`therock_pip_package_specs`) an install gives `uv` and records in the manifest, `published_pip_requirements` is the matching requirement set for `uv pip compile`, and `canonical_auto_select_needs_next_python` peeks at the channel's own `rocm` listing so the interpreter can be picked before resolution. Beneath that, `parse_aggregate_package_links` and `parse_aggregate_device_targets` read the package links of the canonical aggregate root and the exact device targets it publishes, and `validate_aggregate_index_layout` refuses a root that lacks the expected packages or any device payload; `AggregateDeviceTarget::resolve` picks the one exact target a host gets, or records why it could not (`Undetermined`), and `AggregateDeviceTarget::prefer_recorded` is the one place a recorded target (an update apply's, or the one a runtime's manifest was built with) replaces the detected one, called by `therock.rs`, `therock/update.rs` and `therock/wheel_plan.rs`; `load_simple_index_versions` fetches a package's simple-index listing through the cached metadata download and `parse_simple_index_versions` reads the versions out of it, dropping wheels the interpreter's tags do not accept when given them (`wheel_stem_matches_compatibility` and the `wheel_*_tag_matches` helpers); `package_release_key` orders the PEP 440 versions found there (`PackageReleaseKey`). `slugify`, which keys the cached listing, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The functions and types `therock.rs` and `therock/update.rs` name are `pub(in crate::therock)` and reach them through `therock/resolve.rs`; `PipRuntimeResolution` and `TheRockPipPackageVersions` are `pub(in crate::therock)` with the fields they read, and `TorchaudioPin` with its `describe`, so they can use what `resolve_pip_runtime` returns without naming the types; the rest is private. - [`therock/resolve/uv_access.rs`](../apps/rocm/src/therock/resolve/uv_access.rs) — full domain extraction, a leaf child of `therock/resolve.rs` that builds only on `therock/source.rs` for `SourceLayout` (split out of `therock/resolve/wheel.rs` to keep it within the module-size limit): who may fetch `uv` while a wheel stack is resolved. `UvAccess` says how far a resolution may go (`Acquire`, what a real install and `rocm update` pass, or `PresentOnly`, a preview's), `plan_version_resolution` turns that, the layout and whether a `uv` is present into a `VersionResolution` (scrape the indexes, compile with a `UvChoice`, or skip) without touching anything, and `uv_for_compile` hands the compile step the `uv` it runs, acquiring it only on `Acquire`, with the context a failed fetch has always carried. `UvPolicy` carries the access and the two real lookups (`find_uv_binary`, `ensure_uv_binary`) as closures so a test can count what a resolution asks for. Everything is `pub(super)` and read by `wheel.rs`; the state matrix over layout, access and presence lives in this module's tests. From 577ac06bc1f9b3f7642d13eafb2a326e99234e4d Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 10 Nov 2026 13:36:31 +0200 Subject: [PATCH 07/11] refactor(sdk): move torchaudio pinning into its own module The ROCm 10 recovery hint pushed resolve/wheel.rs past the 1,500-line module-size limit. The torchaudio pin (the verified-release preference, its newest-build fallback and the TorchaudioPin wording) is a self-contained decision, so it moves to resolve/torchaudio.rs with its tests. wheel.rs keeps the PEP 440 helpers and exposes them to the new module as pub(super). No behavior changes. Signed-off-by: Roman Inflianskas --- apps/rocm/src/therock/resolve.rs | 11 +- apps/rocm/src/therock/resolve/torchaudio.rs | 523 ++++++++++++++++++++ apps/rocm/src/therock/resolve/wheel.rs | 506 +------------------ docs/architecture.md | 3 +- 4 files changed, 541 insertions(+), 502 deletions(-) create mode 100644 apps/rocm/src/therock/resolve/torchaudio.rs diff --git a/apps/rocm/src/therock/resolve.rs b/apps/rocm/src/therock/resolve.rs index 68b1ddfe70..66bc0d2545 100644 --- a/apps/rocm/src/therock/resolve.rs +++ b/apps/rocm/src/therock/resolve.rs @@ -6,19 +6,22 @@ //! declarations and re-exports live here, no logic: `tarball` resolves the SDK //! tarball from the catalog's index, `wheel` resolves the wheel stack from the //! wheel indexes (with `uv_access` deciding who may fetch `uv` while it does), -//! `next_hint` words what a failed ROCm 10 resolution suggests next, and the -//! rest of `therock` reads the names below. +//! `torchaudio` chooses the torchaudio build a ROCm 10 stack pins, `next_hint` +//! words what a failed ROCm 10 resolution suggests next, and the rest of +//! `therock` reads the names below. mod next_hint; mod tarball; +mod torchaudio; mod uv_access; mod wheel; pub(super) use self::tarball::{resolve_tarball_artifact, resolve_tarball_artifact_with_timeout}; +pub(super) use self::torchaudio::{TorchaudioPin, unverified_torchaudio_note}; #[cfg(test)] pub(super) use self::wheel::select_rocm_version; pub(super) use self::wheel::{ - AggregateDeviceTarget, PipRuntimePlan, TorchaudioPin, UnresolvedPipRuntime, + AggregateDeviceTarget, PipRuntimePlan, UnresolvedPipRuntime, canonical_auto_select_needs_next_python, preview_pip_runtime, resolve_pip_runtime, - resolve_pip_runtime_with_timeout, unverified_torchaudio_note, wheel_runtime_composition, + resolve_pip_runtime_with_timeout, wheel_runtime_composition, }; diff --git a/apps/rocm/src/therock/resolve/torchaudio.rs b/apps/rocm/src/therock/resolve/torchaudio.rs new file mode 100644 index 0000000000..97f1ee6bcb --- /dev/null +++ b/apps/rocm/src/therock/resolve/torchaudio.rs @@ -0,0 +1,523 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! Which torchaudio build a ROCm 10 wheel stack pins, and why. +//! +//! `torchaudio_pin` picks the build for one ROCm release. It prefers the +//! hardware-verified release the vLLM engine records for that ROCm line, and +//! falls back to the newest build (`latest_build_for_rocm`) when none is +//! recorded or it is not published here. `TorchaudioPin` carries the choice +//! and its basis, and `describe` words it. The plan's `torchaudio_selection:` +//! line and `unverified_torchaudio_note`'s install-log note both come from +//! `describe`, so what is printed follows from the decision. A ROCm release +//! with no torchaudio for this Python and platform fails as a +//! `VersionUnsatisfied`, because another release may publish one. +//! +//! A leaf child of `therock/resolve.rs`, split out of `wheel.rs` to keep that +//! module within the size limit. It reads the PEP 440 helpers +//! (`package_release_key`, `package_rocm_suffix`, +//! `package_versions_matching_rocm`) from `wheel.rs`, and `wheel.rs` calls +//! `torchaudio_pin` while resolving the next layout. + +use super::next_hint::VersionUnsatisfied; +use super::wheel::{package_release_key, package_rocm_suffix, package_versions_matching_rocm}; +use anyhow::{Context, Result}; + +/// The torchaudio build pinned for a ROCm 10 install, and why it was chosen. +/// The plan line and install-log note are both [`TorchaudioPin::describe`], so +/// what is printed is derived from the decision rather than restated beside it. +#[derive(Debug, Clone, PartialEq, Eq)] +pub(in crate::therock) struct TorchaudioPin { + /// The published version pinned, `+rocm…` label included. + pub(super) version: String, + /// The ROCm build `version` was chosen for. + rocm_version: String, + basis: TorchaudioPinBasis, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +enum TorchaudioPinBasis { + /// `version` is the hardware-verified release for this ROCm line. + Verified, + /// A verified release is recorded for this ROCm line, but the index + /// publishes no build of it labelled for this exact ROCm build (`+rocm` + /// label) for this Python and platform, so `version` is the newest build + /// instead. + VerifiedNotPublished { + release: &'static str, + /// A build of `release` this Python and platform can install, labelled + /// for another ROCm build, when one is published. The verified release + /// is matched by ROCm line, so a `10.1.1` request can find it published + /// only as `+rocm10.1.0`; the reason must then name the ROCm build, not + /// the Python or platform. + other_build: Option, + }, + /// No verified release is recorded for this ROCm line, so `version` is the + /// newest build. + NoVerifiedRelease, +} + +impl TorchaudioPin { + const fn is_verified(&self) -> bool { + matches!(self.basis, TorchaudioPinBasis::Verified) + } + + pub(in crate::therock) fn describe(&self) -> String { + let Self { + version, + rocm_version, + basis, + } = self; + match basis { + TorchaudioPinBasis::Verified => format!( + "torchaudio {version}, the build verified on hardware for ROCm {rocm_version}" + ), + TorchaudioPinBasis::VerifiedNotPublished { + release, + other_build: None, + } => format!( + "torchaudio {version}, the newest build published for ROCm {rocm_version}; it is not hardware-verified, because the verified release, {release}, is not published for this Python and platform" + ), + TorchaudioPinBasis::VerifiedNotPublished { + release, + other_build: Some(other_build), + } => format!( + "torchaudio {version}, the newest build published for ROCm {rocm_version}; it is not hardware-verified, because the verified release, {release}, is published for this Python and platform only for another ROCm build ({other_build}), not for ROCm {rocm_version}" + ), + TorchaudioPinBasis::NoVerifiedRelease => format!( + "torchaudio {version}, the newest build published for ROCm {rocm_version}; it is not hardware-verified, because no torchaudio release is recorded as verified for this ROCm line" + ), + } + } +} + +/// The install-log line for a torchaudio pin that is not hardware-verified, or +/// `None` for one that is. +/// +/// An unverified torchaudio is the one stack choice ROCm CLI makes on its own +/// judgement, so a real install says so in the install log, not only in the +/// plan's `torchaudio_selection:` line. A verified pin needs no such warning. +/// The text is [`TorchaudioPin::describe`], so it cannot disagree with the pin. +pub(in crate::therock) fn unverified_torchaudio_note(pin: &TorchaudioPin) -> Option { + (!pin.is_verified()).then(|| format!("Note: {}", pin.describe())) +} + +/// The torchaudio build to pin for `rocm_version`, from `published` (this +/// Python and platform's builds on the index). +/// +/// `verified_release` comes first: it is the release confirmed on hardware for +/// this ROCm line ([`rocm_engine_vllm::verified_torchaudio_release`], read from +/// the vLLM ROCm 10.x discover-build table so the SDK and its vLLM install pin +/// the same build). Recency alone is not a safe choice among builds sharing a +/// `+rocm` label: `whl-next` publishes `2.11.0`, `2.11.0.2` and +/// `2.11.0.3` all as `+rocm10.1.0`, and `2.11.0` is a CPU-only rebuild with no +/// HIP kernels, which nothing in the version or label distinguishes. Only when +/// no verified release is recorded, or it is not published here, does this fall +/// back to [`latest_build_for_rocm`], and the returned basis says so. +/// +/// Refuses when no build for `rocm_version` is published at all, or when none of +/// the published builds' versions can be read — the second is not the first, +/// and reporting it as "none published" would send the user to the wrong place. +pub(super) fn torchaudio_pin( + published: &[String], + rocm_version: &str, + verified_release: Option<&'static str>, + index_url: &str, +) -> Result { + let built_for_rocm = package_versions_matching_rocm(published, rocm_version); + if built_for_rocm.is_empty() { + // Another ROCm release can publish a torchaudio this host can install, + // so a different `--version` can clear this one. + return Err(VersionUnsatisfied::new( + Some(rocm_version), + format!( + "no torchaudio built for ROCm {rocm_version} is published for this Python and platform in {index_url}" + ), + ) + .into()); + } + let pin = |version, basis| TorchaudioPin { + version, + rocm_version: rocm_version.to_owned(), + basis, + }; + let basis = match verified_release { + Some(release) => match published_build_of(&built_for_rocm, release) { + Some(version) => return Ok(pin(version, TorchaudioPinBasis::Verified)), + // Not among `built_for_rocm`, so a labelled build of it in the + // whole listing is one for another ROCm build. + None => TorchaudioPinBasis::VerifiedNotPublished { + release, + other_build: published_build_of( + &published + .iter() + .filter(|version| package_rocm_suffix(version).is_some()) + .cloned() + .collect::>(), + release, + ), + }, + }, + None => TorchaudioPinBasis::NoVerifiedRelease, + }; + let newest = latest_build_for_rocm(published, rocm_version).with_context(|| { + format!( + "torchaudio builds for ROCm {rocm_version} are published in {index_url}, but none has a PEP 440 version ROCm CLI can order: {}", + built_for_rocm.join(", ") + ) + })?; + Ok(pin(newest, basis)) +} + +/// The build in `versions` whose public version is `release` under PEP 440 +/// (local label ignored, trailing zeros insignificant), as `uv` would match +/// `torchaudio=={release}`. Not a prefix match: `2.11.0` must not find +/// `2.11.0.2`. +fn published_build_of(versions: &[String], release: &str) -> Option { + let wanted = package_release_key(release)?; + versions + .iter() + .find(|version| package_release_key(version).as_ref() == Some(&wanted)) + .cloned() +} + +/// The newest of `versions` built for exactly `rocm_version`, chosen the way +/// `uv` would choose among them: in PEP 440 order, with final releases ahead of +/// any pre-release. +/// +/// The fallback for [`torchaudio_pin`] only, never the first choice: newest is +/// not a safe discriminator among builds sharing a `+rocm` label (see +/// there for the CPU-only `2.11.0+rocm10.1.0` precedent, and the vLLM engine's +/// ROCm 10.x discover-build table, which pins `2.11.0.2` exactly for the same +/// reason). Nothing on the index pairs a torchaudio build with a torch build, +/// so this assumes the newest torchaudio of a ROCm build is the one built +/// against that build's torch — the same choice `uv` made unaided when the +/// pinned build was also the newest one on the index. +/// +/// Not [`select_latest_stack_package`]: [`parse_version`] reads only +/// `major.minor.patch` and rejects the rest, and torchaudio publishes rebuilds +/// as extra release segments (`2.11.0.2`, `2.11.0.3`), so that would drop every +/// rebuild and settle on the original `2.11.0` build. +fn latest_build_for_rocm(versions: &[String], rocm_version: &str) -> Option { + package_versions_matching_rocm(versions, rocm_version) + .into_iter() + .filter_map(|version| package_release_key(&version).map(|key| (key, version))) + .max_by(|(left, _), (right, _)| (left.is_final(), left).cmp(&(right.is_final(), right))) + .map(|(_, version)| version) +} + +#[cfg(test)] +mod tests { + use super::super::wheel::published_pip_requirements; + use super::*; + + /// The live ROCm 10 index publishes torchaudio rebuilds as a fourth release + /// segment beside the original build, for more than one ROCm build at once. + #[test] + fn torchaudio_pin_is_the_newest_rebuild_of_the_requested_rocm_build() { + let published = [ + "2.11.0+rocm10.0.0", + "2.11.0.2+rocm10.0.0", + "2.11.0+rocm10.1.0", + "2.11.0.2+rocm10.1.0", + "2.11.0.3+rocm10.1.0", + ] + .map(str::to_owned); + + assert_eq!( + latest_build_for_rocm(&published, "10.0.0").as_deref(), + Some("2.11.0.2+rocm10.0.0") + ); + assert_eq!( + latest_build_for_rocm(&published, "10.1.0").as_deref(), + Some("2.11.0.3+rocm10.1.0") + ); + assert_eq!(latest_build_for_rocm(&published, "10.2.0"), None); + } + + /// Mirrors uv's default: a pre-release is only chosen when no final + /// release exists for that build, and a post-release counts as final. + #[test] + fn torchaudio_pin_prefers_final_releases_like_uv() { + let published = [ + "2.12.0a0+rocm10.0.0", + "2.11.0.2+rocm10.0.0", + "2.11.0+rocm10.0.0", + ] + .map(str::to_owned); + assert_eq!( + latest_build_for_rocm(&published, "10.0.0").as_deref(), + Some("2.11.0.2+rocm10.0.0") + ); + + let only_pre = ["2.12.0a0+rocm10.0.0", "2.12.0a1+rocm10.0.0"].map(str::to_owned); + assert_eq!( + latest_build_for_rocm(&only_pre, "10.0.0").as_deref(), + Some("2.12.0a1+rocm10.0.0") + ); + + let post = ["2.11.0+rocm10.0.0", "2.11.0.post1+rocm10.0.0"].map(str::to_owned); + assert_eq!( + latest_build_for_rocm(&post, "10.0.0").as_deref(), + Some("2.11.0.post1+rocm10.0.0") + ); + } + + /// The live `whl-next` shape for `+rocm10.1.0`: a CPU-only `2.11.0`, the + /// hardware-verified `2.11.0.2`, and a newer `2.11.0.3` sharing the label. + fn rocm10_1_torchaudio_builds() -> Vec { + [ + "2.11.0+rocm10.1.0", + "2.11.0.2+rocm10.1.0", + "2.11.0.3+rocm10.1.0", + "2.11.0.2+rocm10.0.0", + ] + .map(str::to_owned) + .to_vec() + } + + /// A verified release that is published wins over a newer build with the + /// same `+rocm` label, and the printed line says it is the verified one. + #[test] + fn torchaudio_pin_takes_the_published_verified_release_over_a_newer_build() -> Result<()> { + let pin = torchaudio_pin( + &rocm10_1_torchaudio_builds(), + "10.1.0", + Some("2.11.0.2"), + "https://index.test", + )?; + assert_eq!(pin.version, "2.11.0.2+rocm10.1.0"); + assert_eq!(pin.basis, TorchaudioPinBasis::Verified); + assert!(pin.is_verified()); + let line = pin.describe(); + assert!( + line.contains("torchaudio 2.11.0.2+rocm10.1.0, the build verified on hardware") + && !line.contains("not hardware-verified"), + "{line}" + ); + // The requirement handed to `uv` names the same build the line does. + assert_eq!( + published_pip_requirements("10.1.0", &pin.version, "gfx1200", false)[3], + "torchaudio==2.11.0.2+rocm10.1.0" + ); + Ok(()) + } + + /// The verified release is matched as a whole PEP 440 version, never a + /// prefix: a verified `2.11.0` must not be satisfied by `2.11.0.2`. + #[test] + fn torchaudio_pin_matches_the_verified_release_exactly() -> Result<()> { + let published = ["2.11.0.2+rocm10.1.0", "2.11.0.3+rocm10.1.0"].map(str::to_owned); + let pin = torchaudio_pin(&published, "10.1.0", Some("2.11.0"), "https://index.test")?; + assert_eq!( + pin.basis, + TorchaudioPinBasis::VerifiedNotPublished { + release: "2.11.0", + other_build: None, + } + ); + assert_eq!(pin.version, "2.11.0.3+rocm10.1.0"); + Ok(()) + } + + /// A verified release published only for another ROCm build falls back to + /// the newest build for the requested one, and the printed reason names the + /// ROCm build as the cause, not the Python or platform: the verified release + /// is matched by ROCm line, so it can be published here under another label + /// of the same line. + #[test] + fn torchaudio_pin_falls_back_to_newest_when_the_verified_release_is_published_for_another_rocm_build() + -> Result<()> { + let published = [ + "2.11.0+rocm10.1.1", + "2.11.0.3+rocm10.1.1", + "2.11.0.2+rocm10.1.0", + ] + .map(str::to_owned); + let pin = torchaudio_pin(&published, "10.1.1", Some("2.11.0.2"), "https://index.test")?; + assert_eq!(pin.version, "2.11.0.3+rocm10.1.1"); + assert_eq!( + pin.basis, + TorchaudioPinBasis::VerifiedNotPublished { + release: "2.11.0.2", + other_build: Some("2.11.0.2+rocm10.1.0".to_owned()), + } + ); + assert!(!pin.is_verified()); + let line = pin.describe(); + assert!( + line.contains( + "torchaudio 2.11.0.3+rocm10.1.1, the newest build published for ROCm 10.1.1" + ) && line.contains("not hardware-verified") + && line.contains( + "the verified release, 2.11.0.2, is published for this Python and platform only for another ROCm build (2.11.0.2+rocm10.1.0), not for ROCm 10.1.1" + ) + && !line.contains("is not published for this Python and platform"), + "{line}" + ); + Ok(()) + } + + /// A verified release with no build at all for this Python and platform + /// falls back to the newest build, and the printed line says the release is + /// not published here. An unlabelled build is not a ROCm build, so it does + /// not count as one "for another ROCm build". + #[test] + fn torchaudio_pin_falls_back_to_newest_when_the_verified_release_is_unpublished() -> Result<()> + { + let published = ["2.11.0+rocm10.1.0", "2.11.0.3+rocm10.1.0", "2.11.0.2"].map(str::to_owned); + let pin = torchaudio_pin(&published, "10.1.0", Some("2.11.0.2"), "https://index.test")?; + assert_eq!(pin.version, "2.11.0.3+rocm10.1.0"); + assert_eq!( + pin.basis, + TorchaudioPinBasis::VerifiedNotPublished { + release: "2.11.0.2", + other_build: None, + } + ); + assert!(!pin.is_verified()); + let line = pin.describe(); + assert!( + line.contains( + "torchaudio 2.11.0.3+rocm10.1.0, the newest build published for ROCm 10.1.0" + ) && line.contains("not hardware-verified") + && line.contains( + "the verified release, 2.11.0.2, is not published for this Python and platform" + ), + "{line}" + ); + Ok(()) + } + + /// A real install notes an unverified torchaudio in its install log, for + /// both reasons a pin can be unverified, and stays quiet for a verified + /// one. The note is the pin's own `describe()` line, so it states the + /// decision that was actually taken. + #[test] + fn unverified_torchaudio_note_is_logged_only_for_an_unverified_pin() -> Result<()> { + let builds = rocm10_1_torchaudio_builds(); + let verified = torchaudio_pin(&builds, "10.1.0", Some("2.11.0.2"), "https://index.test")?; + let not_published = + torchaudio_pin(&builds, "10.1.0", Some("2.11.0.9"), "https://index.test")?; + let no_verified_release = torchaudio_pin(&builds, "10.1.0", None, "https://index.test")?; + assert_eq!(verified.basis, TorchaudioPinBasis::Verified); + assert!(matches!( + not_published.basis, + TorchaudioPinBasis::VerifiedNotPublished { .. } + )); + assert_eq!( + no_verified_release.basis, + TorchaudioPinBasis::NoVerifiedRelease + ); + + assert_eq!(unverified_torchaudio_note(&verified), None); + for pin in [¬_published, &no_verified_release] { + let note = unverified_torchaudio_note(pin); + assert_eq!(note, Some(format!("Note: {}", pin.describe()))); + assert!( + note.as_deref() + .is_some_and(|note| note.contains("torchaudio 2.11.0.3+rocm10.1.0") + && note.contains("not hardware-verified")), + "{note:?}" + ); + } + Ok(()) + } + + /// With no verified release recorded for the line, the newest build is + /// pinned, and the printed line says it is not hardware-verified. + #[test] + fn torchaudio_pin_falls_back_to_newest_when_no_release_is_verified() -> Result<()> { + let pin = torchaudio_pin( + &rocm10_1_torchaudio_builds(), + "10.1.0", + None, + "https://index.test", + )?; + assert_eq!(pin.version, "2.11.0.3+rocm10.1.0"); + assert_eq!(pin.basis, TorchaudioPinBasis::NoVerifiedRelease); + assert!(!pin.is_verified()); + let line = pin.describe(); + assert!( + line.contains( + "torchaudio 2.11.0.3+rocm10.1.0, the newest build published for ROCm 10.1.0" + ) && line.contains("not hardware-verified") + && line.contains("no torchaudio release is recorded as verified"), + "{line}" + ); + Ok(()) + } + + /// The verified release the SDK reads is the vLLM engine's: 10.1 has one, + /// 10.0 has none yet. Pins the wiring, not the table (which the engine's + /// own tests own), so a change to it is seen here as a deliberate choice. + #[test] + fn torchaudio_verified_release_comes_from_the_vllm_discover_table() { + assert_eq!( + rocm_engine_vllm::verified_torchaudio_release("10.1.0"), + Some("2.11.0.2") + ); + assert_eq!( + rocm_engine_vllm::verified_torchaudio_release("10.0.0"), + None + ); + } + + /// A version the parser cannot read is left out, never guessed at: a newer + /// unreadable build must not win the pin. + #[test] + fn torchaudio_pin_skips_versions_it_cannot_read() -> Result<()> { + let published = [ + "2.11.0+rocm10.0.0", + "2.12.0-local-hack+rocm10.0.0", + "2.11.0.2+rocm10.0.0", + ] + .map(str::to_owned); + assert_eq!( + torchaudio_pin(&published, "10.0.0", None, "https://index.test")?.version, + "2.11.0.2+rocm10.0.0" + ); + Ok(()) + } + + /// The two refusals name different problems, so each says which one it is. + #[test] + fn torchaudio_pin_refusal_says_whether_the_build_is_missing_or_unreadable() { + let other_build = ["2.11.0.3+rocm10.1.0"].map(str::to_owned); + let missing = torchaudio_pin( + &other_build, + "10.0.0", + Some("2.11.0.2"), + "https://index.test", + ) + .expect_err("no torchaudio for the pinned build must refuse") + .to_string(); + assert!( + missing.contains("no torchaudio built for ROCm 10.0.0 is published"), + "{missing}" + ); + + let unreadable = ["2.12.0-local-hack+rocm10.0.0"].map(str::to_owned); + let unreadable = torchaudio_pin(&unreadable, "10.0.0", None, "https://index.test") + .expect_err("an unreadable-only build must refuse") + .to_string(); + assert!( + unreadable.contains("none has a PEP 440 version") + && unreadable.contains("2.12.0-local-hack+rocm10.0.0") + && !unreadable.contains("no torchaudio built"), + "{unreadable}" + ); + } + + /// A post-release that is itself a dev build is still a pre-release to + /// `uv`, so a final release wins over it. + #[test] + fn torchaudio_pin_treats_a_dev_post_release_as_a_pre_release() { + let published = ["2.11.0+rocm10.0.0", "2.11.0.post1.dev0+rocm10.0.0"].map(str::to_owned); + assert_eq!( + latest_build_for_rocm(&published, "10.0.0").as_deref(), + Some("2.11.0+rocm10.0.0") + ); + } +} diff --git a/apps/rocm/src/therock/resolve/wheel.rs b/apps/rocm/src/therock/resolve/wheel.rs index 7fdec56381..1262af0d51 100644 --- a/apps/rocm/src/therock/resolve/wheel.rs +++ b/apps/rocm/src/therock/resolve/wheel.rs @@ -51,6 +51,7 @@ use super::super::version::{ use super::next_hint::{ NextLayoutRecovery, RecoveryFormat, VersionUnsatisfied, next_layout_unsatisfied_hint, }; +use super::torchaudio::{TorchaudioPin, torchaudio_pin}; use super::uv_access::{ UvAccess, UvPolicy, VersionResolution, plan_version_resolution, uv_for_compile, }; @@ -237,7 +238,7 @@ impl AggregateDeviceTarget { /// PEP 440's: field order is comparison order, and each enum's variants are /// declared lowest first. #[derive(Debug, PartialEq, Eq, PartialOrd, Ord)] -struct PackageReleaseKey { +pub(super) struct PackageReleaseKey { epoch: u64, /// Trailing zeros dropped, so `2.11` and `2.11.0` compare equal. release: Vec, @@ -264,7 +265,7 @@ enum DevRelease { impl PackageReleaseKey { /// `uv` only picks a pre-release (including any `.devN`) when no final /// release is available; a post-release counts as final. - fn is_final(&self) -> bool { + pub(super) fn is_final(&self) -> bool { self.pre == PreRelease::Final && self.dev == DevRelease::Absent } } @@ -273,7 +274,7 @@ impl PackageReleaseKey { /// (`[N!]N(.N)*[{a|b|rc}N][.postN][.devN][+local]`), already percent-decoded /// by [`parse_simple_index_versions`]. Anything else is `None`, and is skipped /// rather than guessed at. -fn package_release_key(version: &str) -> Option { +pub(super) fn package_release_key(version: &str) -> Option { fn number(rest: &mut &str) -> Option { let len = rest.chars().take_while(char::is_ascii_digit).count(); let (digits, tail) = rest.split_at(len); @@ -337,7 +338,7 @@ fn package_release_key(version: &str) -> Option { }) } -fn package_rocm_suffix(version: &str) -> Option { +pub(super) fn package_rocm_suffix(version: &str) -> Option { let decoded = decode_simple_index_version(version); let lower = decoded.to_ascii_lowercase(); let marker = "+rocm"; @@ -590,7 +591,7 @@ const fn therock_sdk_extras(include_devel: bool) -> &'static str { /// constrains the chosen versions by a toolchain they declined, and can fail the /// whole install with a toolchain-resolution error on a default /// `rocm install sdk`. -fn published_pip_requirements( +pub(super) fn published_pip_requirements( rocm_version: &str, torchaudio_version: &str, device_target: &str, @@ -1282,190 +1283,10 @@ fn select_latest_stack_package( candidates.pop() } -/// The torchaudio build pinned for a ROCm 10 install, and why it was chosen. -/// The plan line and install-log note are both [`TorchaudioPin::describe`], so -/// what is printed is derived from the decision rather than restated beside it. -#[derive(Debug, Clone, PartialEq, Eq)] -pub(in crate::therock) struct TorchaudioPin { - /// The published version pinned, `+rocm…` label included. - version: String, - /// The ROCm build `version` was chosen for. - rocm_version: String, - basis: TorchaudioPinBasis, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -enum TorchaudioPinBasis { - /// `version` is the hardware-verified release for this ROCm line. - Verified, - /// A verified release is recorded for this ROCm line, but the index - /// publishes no build of it labelled for this exact ROCm build (`+rocm` - /// label) for this Python and platform, so `version` is the newest build - /// instead. - VerifiedNotPublished { - release: &'static str, - /// A build of `release` this Python and platform can install, labelled - /// for another ROCm build, when one is published. The verified release - /// is matched by ROCm line, so a `10.1.1` request can find it published - /// only as `+rocm10.1.0`; the reason must then name the ROCm build, not - /// the Python or platform. - other_build: Option, - }, - /// No verified release is recorded for this ROCm line, so `version` is the - /// newest build. - NoVerifiedRelease, -} - -impl TorchaudioPin { - const fn is_verified(&self) -> bool { - matches!(self.basis, TorchaudioPinBasis::Verified) - } - - pub(in crate::therock) fn describe(&self) -> String { - let Self { - version, - rocm_version, - basis, - } = self; - match basis { - TorchaudioPinBasis::Verified => format!( - "torchaudio {version}, the build verified on hardware for ROCm {rocm_version}" - ), - TorchaudioPinBasis::VerifiedNotPublished { - release, - other_build: None, - } => format!( - "torchaudio {version}, the newest build published for ROCm {rocm_version}; it is not hardware-verified, because the verified release, {release}, is not published for this Python and platform" - ), - TorchaudioPinBasis::VerifiedNotPublished { - release, - other_build: Some(other_build), - } => format!( - "torchaudio {version}, the newest build published for ROCm {rocm_version}; it is not hardware-verified, because the verified release, {release}, is published for this Python and platform only for another ROCm build ({other_build}), not for ROCm {rocm_version}" - ), - TorchaudioPinBasis::NoVerifiedRelease => format!( - "torchaudio {version}, the newest build published for ROCm {rocm_version}; it is not hardware-verified, because no torchaudio release is recorded as verified for this ROCm line" - ), - } - } -} - -/// The install-log line for a torchaudio pin that is not hardware-verified, or -/// `None` for one that is. -/// -/// An unverified torchaudio is the one stack choice ROCm CLI makes on its own -/// judgement, so a real install says so in the install log, not only in the -/// plan's `torchaudio_selection:` line. A verified pin needs no such warning. -/// The text is [`TorchaudioPin::describe`], so it cannot disagree with the pin. -pub(in crate::therock) fn unverified_torchaudio_note(pin: &TorchaudioPin) -> Option { - (!pin.is_verified()).then(|| format!("Note: {}", pin.describe())) -} - -/// The torchaudio build to pin for `rocm_version`, from `published` (this -/// Python and platform's builds on the index). -/// -/// `verified_release` comes first: it is the release confirmed on hardware for -/// this ROCm line ([`rocm_engine_vllm::verified_torchaudio_release`], read from -/// the vLLM ROCm 10.x discover-build table so the SDK and its vLLM install pin -/// the same build). Recency alone is not a safe choice among builds sharing a -/// `+rocm` label: `whl-next` publishes `2.11.0`, `2.11.0.2` and -/// `2.11.0.3` all as `+rocm10.1.0`, and `2.11.0` is a CPU-only rebuild with no -/// HIP kernels, which nothing in the version or label distinguishes. Only when -/// no verified release is recorded, or it is not published here, does this fall -/// back to [`latest_build_for_rocm`], and the returned basis says so. -/// -/// Refuses when no build for `rocm_version` is published at all, or when none of -/// the published builds' versions can be read — the second is not the first, -/// and reporting it as "none published" would send the user to the wrong place. -fn torchaudio_pin( - published: &[String], +pub(super) fn package_versions_matching_rocm( + versions: &[String], rocm_version: &str, - verified_release: Option<&'static str>, - index_url: &str, -) -> Result { - let built_for_rocm = package_versions_matching_rocm(published, rocm_version); - if built_for_rocm.is_empty() { - // Another ROCm release can publish a torchaudio this host can install, - // so a different `--version` can clear this one. - return Err(VersionUnsatisfied::new( - Some(rocm_version), - format!( - "no torchaudio built for ROCm {rocm_version} is published for this Python and platform in {index_url}" - ), - ) - .into()); - } - let pin = |version, basis| TorchaudioPin { - version, - rocm_version: rocm_version.to_owned(), - basis, - }; - let basis = match verified_release { - Some(release) => match published_build_of(&built_for_rocm, release) { - Some(version) => return Ok(pin(version, TorchaudioPinBasis::Verified)), - // Not among `built_for_rocm`, so a labelled build of it in the - // whole listing is one for another ROCm build. - None => TorchaudioPinBasis::VerifiedNotPublished { - release, - other_build: published_build_of( - &published - .iter() - .filter(|version| package_rocm_suffix(version).is_some()) - .cloned() - .collect::>(), - release, - ), - }, - }, - None => TorchaudioPinBasis::NoVerifiedRelease, - }; - let newest = latest_build_for_rocm(published, rocm_version).with_context(|| { - format!( - "torchaudio builds for ROCm {rocm_version} are published in {index_url}, but none has a PEP 440 version ROCm CLI can order: {}", - built_for_rocm.join(", ") - ) - })?; - Ok(pin(newest, basis)) -} - -/// The build in `versions` whose public version is `release` under PEP 440 -/// (local label ignored, trailing zeros insignificant), as `uv` would match -/// `torchaudio=={release}`. Not a prefix match: `2.11.0` must not find -/// `2.11.0.2`. -fn published_build_of(versions: &[String], release: &str) -> Option { - let wanted = package_release_key(release)?; - versions - .iter() - .find(|version| package_release_key(version).as_ref() == Some(&wanted)) - .cloned() -} - -/// The newest of `versions` built for exactly `rocm_version`, chosen the way -/// `uv` would choose among them: in PEP 440 order, with final releases ahead of -/// any pre-release. -/// -/// The fallback for [`torchaudio_pin`] only, never the first choice: newest is -/// not a safe discriminator among builds sharing a `+rocm` label (see -/// there for the CPU-only `2.11.0+rocm10.1.0` precedent, and the vLLM engine's -/// ROCm 10.x discover-build table, which pins `2.11.0.2` exactly for the same -/// reason). Nothing on the index pairs a torchaudio build with a torch build, -/// so this assumes the newest torchaudio of a ROCm build is the one built -/// against that build's torch — the same choice `uv` made unaided when the -/// pinned build was also the newest one on the index. -/// -/// Not [`select_latest_stack_package`]: [`parse_version`] reads only -/// `major.minor.patch` and rejects the rest, and torchaudio publishes rebuilds -/// as extra release segments (`2.11.0.2`, `2.11.0.3`), so that would drop every -/// rebuild and settle on the original `2.11.0` build. -fn latest_build_for_rocm(versions: &[String], rocm_version: &str) -> Option { - package_versions_matching_rocm(versions, rocm_version) - .into_iter() - .filter_map(|version| package_release_key(&version).map(|key| (key, version))) - .max_by(|(left, _), (right, _)| (left.is_final(), left).cmp(&(right.is_final(), right))) - .map(|(_, version)| version) -} - -fn package_versions_matching_rocm(versions: &[String], rocm_version: &str) -> Vec { +) -> Vec { versions .iter() .filter(|version| package_rocm_suffix(version).as_deref() == Some(rocm_version)) @@ -1922,315 +1743,6 @@ mod tests { Ok(()) } - /// The live ROCm 10 index publishes torchaudio rebuilds as a fourth release - /// segment beside the original build, for more than one ROCm build at once. - #[test] - fn torchaudio_pin_is_the_newest_rebuild_of_the_requested_rocm_build() { - let published = [ - "2.11.0+rocm10.0.0", - "2.11.0.2+rocm10.0.0", - "2.11.0+rocm10.1.0", - "2.11.0.2+rocm10.1.0", - "2.11.0.3+rocm10.1.0", - ] - .map(str::to_owned); - - assert_eq!( - latest_build_for_rocm(&published, "10.0.0").as_deref(), - Some("2.11.0.2+rocm10.0.0") - ); - assert_eq!( - latest_build_for_rocm(&published, "10.1.0").as_deref(), - Some("2.11.0.3+rocm10.1.0") - ); - assert_eq!(latest_build_for_rocm(&published, "10.2.0"), None); - } - - /// Mirrors uv's default: a pre-release is only chosen when no final - /// release exists for that build, and a post-release counts as final. - #[test] - fn torchaudio_pin_prefers_final_releases_like_uv() { - let published = [ - "2.12.0a0+rocm10.0.0", - "2.11.0.2+rocm10.0.0", - "2.11.0+rocm10.0.0", - ] - .map(str::to_owned); - assert_eq!( - latest_build_for_rocm(&published, "10.0.0").as_deref(), - Some("2.11.0.2+rocm10.0.0") - ); - - let only_pre = ["2.12.0a0+rocm10.0.0", "2.12.0a1+rocm10.0.0"].map(str::to_owned); - assert_eq!( - latest_build_for_rocm(&only_pre, "10.0.0").as_deref(), - Some("2.12.0a1+rocm10.0.0") - ); - - let post = ["2.11.0+rocm10.0.0", "2.11.0.post1+rocm10.0.0"].map(str::to_owned); - assert_eq!( - latest_build_for_rocm(&post, "10.0.0").as_deref(), - Some("2.11.0.post1+rocm10.0.0") - ); - } - - /// The live `whl-next` shape for `+rocm10.1.0`: a CPU-only `2.11.0`, the - /// hardware-verified `2.11.0.2`, and a newer `2.11.0.3` sharing the label. - fn rocm10_1_torchaudio_builds() -> Vec { - [ - "2.11.0+rocm10.1.0", - "2.11.0.2+rocm10.1.0", - "2.11.0.3+rocm10.1.0", - "2.11.0.2+rocm10.0.0", - ] - .map(str::to_owned) - .to_vec() - } - - /// A verified release that is published wins over a newer build with the - /// same `+rocm` label, and the printed line says it is the verified one. - #[test] - fn torchaudio_pin_takes_the_published_verified_release_over_a_newer_build() -> Result<()> { - let pin = torchaudio_pin( - &rocm10_1_torchaudio_builds(), - "10.1.0", - Some("2.11.0.2"), - "https://index.test", - )?; - assert_eq!(pin.version, "2.11.0.2+rocm10.1.0"); - assert_eq!(pin.basis, TorchaudioPinBasis::Verified); - assert!(pin.is_verified()); - let line = pin.describe(); - assert!( - line.contains("torchaudio 2.11.0.2+rocm10.1.0, the build verified on hardware") - && !line.contains("not hardware-verified"), - "{line}" - ); - // The requirement handed to `uv` names the same build the line does. - assert_eq!( - published_pip_requirements("10.1.0", &pin.version, "gfx1200", false)[3], - "torchaudio==2.11.0.2+rocm10.1.0" - ); - Ok(()) - } - - /// The verified release is matched as a whole PEP 440 version, never a - /// prefix: a verified `2.11.0` must not be satisfied by `2.11.0.2`. - #[test] - fn torchaudio_pin_matches_the_verified_release_exactly() -> Result<()> { - let published = ["2.11.0.2+rocm10.1.0", "2.11.0.3+rocm10.1.0"].map(str::to_owned); - let pin = torchaudio_pin(&published, "10.1.0", Some("2.11.0"), "https://index.test")?; - assert_eq!( - pin.basis, - TorchaudioPinBasis::VerifiedNotPublished { - release: "2.11.0", - other_build: None, - } - ); - assert_eq!(pin.version, "2.11.0.3+rocm10.1.0"); - Ok(()) - } - - /// A verified release published only for another ROCm build falls back to - /// the newest build for the requested one, and the printed reason names the - /// ROCm build as the cause, not the Python or platform: the verified release - /// is matched by ROCm line, so it can be published here under another label - /// of the same line. - #[test] - fn torchaudio_pin_falls_back_to_newest_when_the_verified_release_is_published_for_another_rocm_build() - -> Result<()> { - let published = [ - "2.11.0+rocm10.1.1", - "2.11.0.3+rocm10.1.1", - "2.11.0.2+rocm10.1.0", - ] - .map(str::to_owned); - let pin = torchaudio_pin(&published, "10.1.1", Some("2.11.0.2"), "https://index.test")?; - assert_eq!(pin.version, "2.11.0.3+rocm10.1.1"); - assert_eq!( - pin.basis, - TorchaudioPinBasis::VerifiedNotPublished { - release: "2.11.0.2", - other_build: Some("2.11.0.2+rocm10.1.0".to_owned()), - } - ); - assert!(!pin.is_verified()); - let line = pin.describe(); - assert!( - line.contains( - "torchaudio 2.11.0.3+rocm10.1.1, the newest build published for ROCm 10.1.1" - ) && line.contains("not hardware-verified") - && line.contains( - "the verified release, 2.11.0.2, is published for this Python and platform only for another ROCm build (2.11.0.2+rocm10.1.0), not for ROCm 10.1.1" - ) - && !line.contains("is not published for this Python and platform"), - "{line}" - ); - Ok(()) - } - - /// A verified release with no build at all for this Python and platform - /// falls back to the newest build, and the printed line says the release is - /// not published here. An unlabelled build is not a ROCm build, so it does - /// not count as one "for another ROCm build". - #[test] - fn torchaudio_pin_falls_back_to_newest_when_the_verified_release_is_unpublished() -> Result<()> - { - let published = ["2.11.0+rocm10.1.0", "2.11.0.3+rocm10.1.0", "2.11.0.2"].map(str::to_owned); - let pin = torchaudio_pin(&published, "10.1.0", Some("2.11.0.2"), "https://index.test")?; - assert_eq!(pin.version, "2.11.0.3+rocm10.1.0"); - assert_eq!( - pin.basis, - TorchaudioPinBasis::VerifiedNotPublished { - release: "2.11.0.2", - other_build: None, - } - ); - assert!(!pin.is_verified()); - let line = pin.describe(); - assert!( - line.contains( - "torchaudio 2.11.0.3+rocm10.1.0, the newest build published for ROCm 10.1.0" - ) && line.contains("not hardware-verified") - && line.contains( - "the verified release, 2.11.0.2, is not published for this Python and platform" - ), - "{line}" - ); - Ok(()) - } - - /// A real install notes an unverified torchaudio in its install log, for - /// both reasons a pin can be unverified, and stays quiet for a verified - /// one. The note is the pin's own `describe()` line, so it states the - /// decision that was actually taken. - #[test] - fn unverified_torchaudio_note_is_logged_only_for_an_unverified_pin() -> Result<()> { - let builds = rocm10_1_torchaudio_builds(); - let verified = torchaudio_pin(&builds, "10.1.0", Some("2.11.0.2"), "https://index.test")?; - let not_published = - torchaudio_pin(&builds, "10.1.0", Some("2.11.0.9"), "https://index.test")?; - let no_verified_release = torchaudio_pin(&builds, "10.1.0", None, "https://index.test")?; - assert_eq!(verified.basis, TorchaudioPinBasis::Verified); - assert!(matches!( - not_published.basis, - TorchaudioPinBasis::VerifiedNotPublished { .. } - )); - assert_eq!( - no_verified_release.basis, - TorchaudioPinBasis::NoVerifiedRelease - ); - - assert_eq!(unverified_torchaudio_note(&verified), None); - for pin in [¬_published, &no_verified_release] { - let note = unverified_torchaudio_note(pin); - assert_eq!(note, Some(format!("Note: {}", pin.describe()))); - assert!( - note.as_deref() - .is_some_and(|note| note.contains("torchaudio 2.11.0.3+rocm10.1.0") - && note.contains("not hardware-verified")), - "{note:?}" - ); - } - Ok(()) - } - - /// With no verified release recorded for the line, the newest build is - /// pinned, and the printed line says it is not hardware-verified. - #[test] - fn torchaudio_pin_falls_back_to_newest_when_no_release_is_verified() -> Result<()> { - let pin = torchaudio_pin( - &rocm10_1_torchaudio_builds(), - "10.1.0", - None, - "https://index.test", - )?; - assert_eq!(pin.version, "2.11.0.3+rocm10.1.0"); - assert_eq!(pin.basis, TorchaudioPinBasis::NoVerifiedRelease); - assert!(!pin.is_verified()); - let line = pin.describe(); - assert!( - line.contains( - "torchaudio 2.11.0.3+rocm10.1.0, the newest build published for ROCm 10.1.0" - ) && line.contains("not hardware-verified") - && line.contains("no torchaudio release is recorded as verified"), - "{line}" - ); - Ok(()) - } - - /// The verified release the SDK reads is the vLLM engine's: 10.1 has one, - /// 10.0 has none yet. Pins the wiring, not the table (which the engine's - /// own tests own), so a change to it is seen here as a deliberate choice. - #[test] - fn torchaudio_verified_release_comes_from_the_vllm_discover_table() { - assert_eq!( - rocm_engine_vllm::verified_torchaudio_release("10.1.0"), - Some("2.11.0.2") - ); - assert_eq!( - rocm_engine_vllm::verified_torchaudio_release("10.0.0"), - None - ); - } - - /// A version the parser cannot read is left out, never guessed at: a newer - /// unreadable build must not win the pin. - #[test] - fn torchaudio_pin_skips_versions_it_cannot_read() -> Result<()> { - let published = [ - "2.11.0+rocm10.0.0", - "2.12.0-local-hack+rocm10.0.0", - "2.11.0.2+rocm10.0.0", - ] - .map(str::to_owned); - assert_eq!( - torchaudio_pin(&published, "10.0.0", None, "https://index.test")?.version, - "2.11.0.2+rocm10.0.0" - ); - Ok(()) - } - - /// The two refusals name different problems, so each says which one it is. - #[test] - fn torchaudio_pin_refusal_says_whether_the_build_is_missing_or_unreadable() { - let other_build = ["2.11.0.3+rocm10.1.0"].map(str::to_owned); - let missing = torchaudio_pin( - &other_build, - "10.0.0", - Some("2.11.0.2"), - "https://index.test", - ) - .expect_err("no torchaudio for the pinned build must refuse") - .to_string(); - assert!( - missing.contains("no torchaudio built for ROCm 10.0.0 is published"), - "{missing}" - ); - - let unreadable = ["2.12.0-local-hack+rocm10.0.0"].map(str::to_owned); - let unreadable = torchaudio_pin(&unreadable, "10.0.0", None, "https://index.test") - .expect_err("an unreadable-only build must refuse") - .to_string(); - assert!( - unreadable.contains("none has a PEP 440 version") - && unreadable.contains("2.12.0-local-hack+rocm10.0.0") - && !unreadable.contains("no torchaudio built"), - "{unreadable}" - ); - } - - /// A post-release that is itself a dev build is still a pre-release to - /// `uv`, so a final release wins over it. - #[test] - fn torchaudio_pin_treats_a_dev_post_release_as_a_pre_release() { - let published = ["2.11.0+rocm10.0.0", "2.11.0.post1.dev0+rocm10.0.0"].map(str::to_owned); - assert_eq!( - latest_build_for_rocm(&published, "10.0.0").as_deref(), - Some("2.11.0+rocm10.0.0") - ); - } - #[test] fn uv_metadata_plan_rejects_mixed_rocm_builds() { let error = parse_uv_compiled_package_versions( diff --git a/docs/architecture.md b/docs/architecture.md index 327ed482b3..cc2e9ac6a9 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -120,7 +120,8 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`therock/resolve.rs`](../apps/rocm/src/therock/resolve.rs) — a child of `therock.rs` that holds no logic (split out of `therock.rs`): only the `mod` declarations for the artifact-resolution modules under `therock/resolve/` and the `pub(super) use` lines through which `therock.rs` reads them. It is the parent the `resolve/` files hang from, so a module there is `pub(in crate::therock)` for the items `therock.rs` reaches and private otherwise. - [`therock/resolve/next_hint.rs`](../apps/rocm/src/therock/resolve/next_hint.rs) — full domain extraction, a leaf child of `therock/resolve.rs` that builds on `therock/source.rs` and `therock/version.rs` (split out of `therock/resolve/wheel.rs` to keep it within the module-size limit): what a failed ROCm 10 resolution suggests next. A failure a different `--version` can clear is raised as a `VersionUnsatisfied`, which carries the release the resolver attempted and displays as the failure's own message. `wheel.rs` raises one for an unmatched pin, a missing torchaudio or a `uv pip compile` with no solution, and `tarball.rs` treats its no-archive failure the same way. `VersionUnsatisfied::find` looks for one anywhere in an error's chain. `next_layout_unsatisfied_hint` lists the stable releases the layout publishes, leaving out the attempted one and any release a re-run would route back to the canonical index. A pinned install is told which `--version`/`--family` to re-run with. `rocm update`, which re-resolves with no pin, is given a whole `rocm install sdk` command, and `NextLayoutRecovery` carries the format, exact arch and `devel` extras that command keeps. Any other failure gets no version advice. Everything is `pub(in crate::therock)` and read by `wheel.rs` and `tarball.rs`. - [`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/fetch.rs`, `therock/family.rs`, `therock/source.rs` and `therock/version.rs` (split out of `therock.rs`): resolving the SDK tarball a request installs. `resolve_tarball_artifact` (and `resolve_tarball_artifact_with_timeout`, which takes the metadata download timeout) resolves the family and source layout, downloads the catalog through the cached metadata fetch, and returns the `TarballArtifact` it chose; `parse_tarball_index_html` reads the catalog's embedded file list into `TarballIndexFile`s and `validate_tarball_file_name` refuses an entry that is not a plain file name; `select_tarball_candidate` picks the newest archive the request can install, with `tarball_family_token` spelling the family the way the next layout's catalog does. `platform_tarball_token`, which names the archives' platform, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. Only `resolve_tarball_artifact*` and `TarballArtifact` are visible beyond this file. -- [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/family.rs`, `therock/fetch.rs`, `therock/process.rs`, `therock/python.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for `WheelRuntimeComposition` (split out of `therock.rs`): resolving the wheel stack a request installs. `resolve_pip_runtime` (and `resolve_pip_runtime_with_timeout`, which takes the metadata download timeout and an optional source layout) resolves the family and the layout, reads the aggregate root, decides the device payload and returns a `PipRuntimeResolution`; on the canonical layout `select_matching_pip_package_versions` then takes the newest `rocm` whose `torch`, `torchvision` and `torchaudio` listings agree, and on the next layout `torchaudio_pin` pins a torchaudio first (the hardware-verified release when it is published, read from the vLLM engine's table) and `resolve_published_pip_package_versions` has `uv pip compile` choose the rest. That compile is the one step that may fetch `uv`, so who may is decided in one pure function, [`therock/resolve/uv_access.rs`](../apps/rocm/src/therock/resolve/uv_access.rs)'s `plan_version_resolution`, which takes the layout, a `UvAccess` and whether a `uv` is present, and answers scrape the indexes (canonical), compile with a `UvChoice` (acquire the managed `uv`, or use the present one) or skip. `resolve_pip_runtime` and `resolve_pip_runtime_with_timeout` (a real install and `rocm update`) are always `UvAccess::Acquire`, which never skips and never asks whether a `uv` is present; `preview_pip_runtime` is `UvAccess::PresentOnly`, which uses a present `uv` (`rocm_core::find_uv_binary`) and otherwise returns `PipRuntimePlan::NeedsUv` holding an `UnresolvedPipRuntime`: what was chosen without `uv` (the `rocm` version, the torchaudio pin, the requirements `uv` would be given) and no package versions, so nothing made from them can be built from it. `wheel.rs` acts on the answer; the real `find_uv_binary` and `ensure_uv_binary` reach it through a `UvPolicy` so that a test can count the calls. `wheel_runtime_composition` turns a resolution into the exact package specs (`therock_pip_package_specs`) an install gives `uv` and records in the manifest, `published_pip_requirements` is the matching requirement set for `uv pip compile`, and `canonical_auto_select_needs_next_python` peeks at the channel's own `rocm` listing so the interpreter can be picked before resolution. Beneath that, `parse_aggregate_package_links` and `parse_aggregate_device_targets` read the package links of the canonical aggregate root and the exact device targets it publishes, and `validate_aggregate_index_layout` refuses a root that lacks the expected packages or any device payload; `AggregateDeviceTarget::resolve` picks the one exact target a host gets, or records why it could not (`Undetermined`), and `AggregateDeviceTarget::prefer_recorded` is the one place a recorded target (an update apply's, or the one a runtime's manifest was built with) replaces the detected one, called by `therock.rs`, `therock/update.rs` and `therock/wheel_plan.rs`; `load_simple_index_versions` fetches a package's simple-index listing through the cached metadata download and `parse_simple_index_versions` reads the versions out of it, dropping wheels the interpreter's tags do not accept when given them (`wheel_stem_matches_compatibility` and the `wheel_*_tag_matches` helpers); `package_release_key` orders the PEP 440 versions found there (`PackageReleaseKey`). `slugify`, which keys the cached listing, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The functions and types `therock.rs` and `therock/update.rs` name are `pub(in crate::therock)` and reach them through `therock/resolve.rs`; `PipRuntimeResolution` and `TheRockPipPackageVersions` are `pub(in crate::therock)` with the fields they read, and `TorchaudioPin` with its `describe`, so they can use what `resolve_pip_runtime` returns without naming the types; the rest is private. +- [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/family.rs`, `therock/fetch.rs`, `therock/process.rs`, `therock/python.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for `WheelRuntimeComposition` (split out of `therock.rs`): resolving the wheel stack a request installs. `resolve_pip_runtime` (and `resolve_pip_runtime_with_timeout`, which takes the metadata download timeout and an optional source layout) resolves the family and the layout, reads the aggregate root, decides the device payload and returns a `PipRuntimeResolution`; on the canonical layout `select_matching_pip_package_versions` then takes the newest `rocm` whose `torch`, `torchvision` and `torchaudio` listings agree, and on the next layout [`therock/resolve/torchaudio.rs`](../apps/rocm/src/therock/resolve/torchaudio.rs)'s `torchaudio_pin` pins a torchaudio first (the hardware-verified release when it is published, read from the vLLM engine's table) and `resolve_published_pip_package_versions` has `uv pip compile` choose the rest. That compile is the one step that may fetch `uv`, so who may is decided in one pure function, [`therock/resolve/uv_access.rs`](../apps/rocm/src/therock/resolve/uv_access.rs)'s `plan_version_resolution`, which takes the layout, a `UvAccess` and whether a `uv` is present, and answers scrape the indexes (canonical), compile with a `UvChoice` (acquire the managed `uv`, or use the present one) or skip. `resolve_pip_runtime` and `resolve_pip_runtime_with_timeout` (a real install and `rocm update`) are always `UvAccess::Acquire`, which never skips and never asks whether a `uv` is present; `preview_pip_runtime` is `UvAccess::PresentOnly`, which uses a present `uv` (`rocm_core::find_uv_binary`) and otherwise returns `PipRuntimePlan::NeedsUv` holding an `UnresolvedPipRuntime`: what was chosen without `uv` (the `rocm` version, the torchaudio pin, the requirements `uv` would be given) and no package versions, so nothing made from them can be built from it. `wheel.rs` acts on the answer; the real `find_uv_binary` and `ensure_uv_binary` reach it through a `UvPolicy` so that a test can count the calls. `wheel_runtime_composition` turns a resolution into the exact package specs (`therock_pip_package_specs`) an install gives `uv` and records in the manifest, `published_pip_requirements` is the matching requirement set for `uv pip compile`, and `canonical_auto_select_needs_next_python` peeks at the channel's own `rocm` listing so the interpreter can be picked before resolution. Beneath that, `parse_aggregate_package_links` and `parse_aggregate_device_targets` read the package links of the canonical aggregate root and the exact device targets it publishes, and `validate_aggregate_index_layout` refuses a root that lacks the expected packages or any device payload; `AggregateDeviceTarget::resolve` picks the one exact target a host gets, or records why it could not (`Undetermined`), and `AggregateDeviceTarget::prefer_recorded` is the one place a recorded target (an update apply's, or the one a runtime's manifest was built with) replaces the detected one, called by `therock.rs`, `therock/update.rs` and `therock/wheel_plan.rs`; `load_simple_index_versions` fetches a package's simple-index listing through the cached metadata download and `parse_simple_index_versions` reads the versions out of it, dropping wheels the interpreter's tags do not accept when given them (`wheel_stem_matches_compatibility` and the `wheel_*_tag_matches` helpers); `package_release_key` orders the PEP 440 versions found there (`PackageReleaseKey`). `slugify`, which keys the cached listing, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The functions and types `therock.rs` and `therock/update.rs` name are `pub(in crate::therock)` and reach them through `therock/resolve.rs`; `PipRuntimeResolution` and `TheRockPipPackageVersions` are `pub(in crate::therock)` with the fields they read, so they can use what `resolve_pip_runtime` returns without naming the types. A failure a different `--version` can clear is raised as [`therock/resolve/next_hint.rs`](../apps/rocm/src/therock/resolve/next_hint.rs)'s `VersionUnsatisfied`, and only such a failure is followed by that module's list of releases to try; the PEP 440 helpers `torchaudio.rs` reads are `pub(super)`; the rest is private. +- [`therock/resolve/torchaudio.rs`](../apps/rocm/src/therock/resolve/torchaudio.rs) — full domain extraction, a leaf child of `therock/resolve.rs` that builds on `therock/resolve/wheel.rs` for the PEP 440 helpers (`package_release_key`, `package_rocm_suffix`, `package_versions_matching_rocm`) and on `therock/resolve/next_hint.rs` for `VersionUnsatisfied` (split out of `therock/resolve/wheel.rs` to keep it within the module-size limit): which torchaudio build a ROCm 10 wheel stack pins. `torchaudio_pin` prefers the hardware-verified release the vLLM engine records for the ROCm line, and falls back to the newest build for the ROCm build (`latest_build_for_rocm`), matched by PEP 440 rather than by prefix (`published_build_of`). A release with no torchaudio for this Python and platform fails as a `VersionUnsatisfied`. `TorchaudioPin` carries the build and its basis, and `TorchaudioPin::describe` words it for both the plan line and `unverified_torchaudio_note`'s install-log note, which `therock.rs` reads through `therock/resolve.rs`. - [`therock/resolve/uv_access.rs`](../apps/rocm/src/therock/resolve/uv_access.rs) — full domain extraction, a leaf child of `therock/resolve.rs` that builds only on `therock/source.rs` for `SourceLayout` (split out of `therock/resolve/wheel.rs` to keep it within the module-size limit): who may fetch `uv` while a wheel stack is resolved. `UvAccess` says how far a resolution may go (`Acquire`, what a real install and `rocm update` pass, or `PresentOnly`, a preview's), `plan_version_resolution` turns that, the layout and whether a `uv` is present into a `VersionResolution` (scrape the indexes, compile with a `UvChoice`, or skip) without touching anything, and `uv_for_compile` hands the compile step the `uv` it runs, acquiring it only on `Acquire`, with the context a failed fetch has always carried. `UvPolicy` carries the access and the two real lookups (`find_uv_binary`, `ensure_uv_binary`) as closures so a test can count what a resolution asks for. Everything is `pub(super)` and read by `wheel.rs`; the state matrix over layout, access and presence lives in this module's tests. - [`therock/consent.rs`](../apps/rocm/src/therock/consent.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/source.rs` and `therock/version.rs` and reaches the registry through [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) (split out of `therock.rs`): the consent gate for an install that would displace the active default runtime. `active_default_runtime_relation` says what the install would replace (an upgrade, downgrade or reinstall when it is the same family and channel, otherwise the different runtime it displaces) or `None` when nothing is the active default, and it fails closed, with a relation naming what could not be resolved, when the config names an active default the registry cannot resolve; `SdkInstallConsent` and `SdkInstallApprovalSource` say how consent is obtained (asked for, or already granted by `--yes`, `--approve-replacing-active-default` or `rocm update --apply`); `sdk_install_approval` turns those and whether a terminal is attached into proceed, prompt or refuse (`SdkInstallApproval`); `preapproved_install_line`, `fresh_install_line`, `refuse_non_interactive_message` and `confirm_overwrite_existing_sdk` are the wording of each outcome, and the prompt reads its answer through `prompt_yes_no` and the shared [`confirm.rs`](../crates/rocm-core/src/confirm.rs). `SdkInstallConsent`, `SdkInstallApprovalSource` and `preapproved_install_line` are re-exported by `therock.rs`; the other items `therock.rs` calls are `pub(super)`, as is `active_default_relation_text`, which the version property tests call, and the rest is private. - [`therock/wheel_plan.rs`](../apps/rocm/src/therock/wheel_plan.rs) — full domain extraction, a leaf child of `therock.rs` (split out of `install_wheel_runtime`) that builds on `therock/python.rs` and `therock/resolve.rs` for the Python decision and the resolution it prints: the `sdk install` plan a wheel install prints, key by key. `WheelPlan` carries the facts, `write_wheel_plan` writes the lines a preview and a real install share, and `write_dry_run_tail` the lines only a preview adds (the `uv` commands it would run and the manifest path). `PlanStack` is the one place the plan differs: `Resolved` carries the package specs, runtime key, install folder and manifest path, and `NeedsUv` (a ROCm 10 preview on a host with no `uv`, see `UnresolvedPipRuntime` in `therock/resolve/wheel.rs`) prints those as `not resolved by this preview` and adds the `resolution_note:` line, so one writer serves both and a line the plan gains appears in both. `unresolved_wheel_preview` renders the second kind whole. `therock.rs` reads it through `pub(super)` items; it reads the provenance, host-note and `venv_python_path` helpers back from `therock.rs`. From 701f7cccbbfaa7f6c3eb8d3d0d240ffa0510d273 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 10 Nov 2026 13:37:14 +0200 Subject: [PATCH 08/11] test(sdk): cover the scoped ROCm 10 recovery hint end to end New scenarios drive each outcome through the CLI against loopback fixtures: an unsatisfied tarball pin lists the published archives and its suggested re-run succeeds (therock-next-19), an update whose runtime records no exact arch gets no version or --family advice (20), a failed update suggests an install command that keeps the runtime's format and toolchain and that command previews successfully (21), an exact pin ignores later patches (22), and a canonical 7.14 line pin takes the line's newest stable build (23). therock-next-16 now publishes several 10.1 builds, a prerelease and a 10.10 build, so it shows the line pin takes the newest stable 10.1.x rather than any of those. README, testing and manual-testing docs describe which failures get a version suggestion and what rocm update suggests instead. Signed-off-by: Roman Inflianskas --- README.md | 10 +- docs/manual-testing.md | 5 + docs/testing.md | 39 +- .../features/therock_next_generation.feature | 74 ++- tests/e2e-cucumber/tests/e2e/therock_steps.rs | 426 +++++++++++++++++- 5 files changed, 514 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 0987611e43..d133ab8a60 100644 --- a/README.md +++ b/README.md @@ -585,9 +585,13 @@ carries the same ROCm build identifier. Nothing about this happens on its own. Without a `--version` of 10 or newer, `install sdk` resolves the same release and nightly sources as before. It doesn't quietly retry against the ROCm 10 sources when a lookup finds nothing; it tells -you what it couldn't find instead. When a ROCm 10 pin can't be satisfied, the -error lists the other stable ROCm 10 releases that source publishes, if any, -and suggests one of them to re-run with. +you what it couldn't find instead. When a ROCm 10 pin can't be satisfied +because that release isn't published, or has no installable packages for this +computer, the error lists the other stable ROCm 10 releases that source +publishes, if any, and suggests one of them to re-run with. When `rocm update` +fails the same way, it suggests a whole `rocm install sdk` command that keeps +the runtime's format and `--devel` toolchain. A failure no other version can +fix, such as an unknown GPU arch or a network error, suggests no version. #### Driver installation diff --git a/docs/manual-testing.md b/docs/manual-testing.md index ac4ed45183..b07fdcf3f1 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -243,6 +243,11 @@ Version pins, checked with `--dry-run`: - A ROCm 10 pin the source cannot satisfy fails with a list of the other stable ROCm 10 releases it publishes, if any, and a `--version` to try. Running that suggestion must succeed, and the error must not suggest `--channel nightly`. +- A `rocm update --apply` of a ROCm 10 runtime that fails the same way + suggests a whole `rocm install sdk` command with the runtime's `--format` + and, for a `--devel` runtime, `--devel`. Running that command with + `--dry-run` must succeed. A failure no other version can clear, such as an + unknown device target, must suggest no version. ### 2a. A GPU target with no ROCm build diff --git a/docs/testing.md b/docs/testing.md index 56ca5acd30..5c6ff558a9 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -936,16 +936,39 @@ Then it verifies: `--version` accepts a `major.minor` line as well as an exact `major.minor.patch`. `--version 10.1` resolves the newest stable 10.1.x on the ROCm 10 next layout, and `--version 7.14` the newest stable 7.14.x on the -canonical index. When a ROCm 10 pin cannot be satisfied, the error lists the -other stable ROCm 10 releases that layout publishes, if any, and suggests one -of them, never the release that just failed and never `--channel nightly`. +canonical index. A `major.minor.patch` pin stays exact. When a ROCm 10 pin +cannot be satisfied because no release matches, the release has no torchaudio +for this Python and platform, or `uv` finds no installable package set for it, +the error lists the other stable ROCm 10 releases that layout publishes, if +any, and suggests one of them, never the release that just failed and never +`--channel nightly`. An install is told which `--version`/`--family` to re-run +with. `rocm update`, which has neither flag, is given a whole +`rocm install sdk` command with the runtime's `--format` and `--devel`. Any +other failure, such as an unknown device target, a `uv` that could not be +fetched or an unreachable index, suggests no version, because no release can +clear it. + Loopback-fixture scenarios in [therock_next_generation.feature](../tests/e2e-cucumber/features/therock_next_generation.feature) -cover this: `therock-next-16` (a wheel line pin), `therock-next-17` (the -failure, which re-runs the suggested command to prove it succeeds) and -`therock-next-18` (a tarball line pin takes the newest release in the line, not -the newest upload). They run in the default e2e lane; `therock-next-18` is -Linux-only because Windows refuses tarball installs. +cover this: + +- `therock-next-16`: a wheel line pin takes the line's newest stable build, + not an older one, a prerelease or a `10.10` build. +- `therock-next-17`: an unsatisfied wheel pin. The scenario re-runs the + suggested command to prove it succeeds. +- `therock-next-18`: a tarball line pin takes the newest release in the line, + not the newest upload. +- `therock-next-19`: an unsatisfied tarball pin lists the archives the catalog + publishes. The scenario re-runs the suggestion. +- `therock-next-20`: an update whose runtime records no exact arch gets no + version or `--family` advice. +- `therock-next-21`: a failed update suggests an install that keeps the + runtime's format and toolchain. The scenario runs that command. +- `therock-next-22`: an exact pin ignores later patches. +- `therock-next-23`: a canonical `7.14` line pin. + +They run in the default e2e lane. `therock-next-18` and `therock-next-19` are +Linux-only, because Windows refuses tarball installs. Run the full live test with auto-detected GPU family: diff --git a/tests/e2e-cucumber/features/therock_next_generation.feature b/tests/e2e-cucumber/features/therock_next_generation.feature index 04d61eadee..5bebe768e6 100644 --- a/tests/e2e-cucumber/features/therock_next_generation.feature +++ b/tests/e2e-cucumber/features/therock_next_generation.feature @@ -278,16 +278,17 @@ Feature: TheRock "next" ROCm 10 install layout Then the dry-run command line names that folder as a single argument # `--version 10.1` is the 10.1 line, not a failed parse of `10.1.0` and not - # an exact pin. The fixture publishes 10.0.0 and 10.1.0; the line pin must - # take 10.1.0 from the next index and must not stay on the canonical 7.x index. + # an exact pin. The fixture publishes the 10.1 line's 10.1.0 and 10.1.2 beside + # a 10.1.3rc1 prerelease, a 10.10.0 and a 10.0.0, so the pin must take + # 10.1.2: the oldest of the line, an exact `10.1.0`, a prerelease and a + # `10.10` prefix match would each pick something else. It must also leave the + # canonical 7.x index. Needs no uv: the version is chosen before `uv` runs. @id:therock-next-16-two-component-line-pin Scenario: therock-next-16 - A ROCm 10.1 line pin installs the newest stable build in that line - Given a ROCm 10 pip index fixture that also publishes a newer ROCm 10 build - And a uv is already installed + Given a ROCm 10 pip index fixture that publishes several 10.1 builds, a 10.1 prerelease and a 10.10 build When the user previews a wheel SDK install for arch gfx1200 pinned to ROCm 10.1 - Then the preview resolves the ROCm 10 pip index for ROCm 10.1.0 + Then the preview resolves the ROCm 10 pip index for ROCm 10.1.2, the newest stable build of the 10.1 line And the preview reports the next source layout generation - And the preview installs the hardware-verified torchaudio for ROCm 10.1.0, not the newer rebuild # The same pin against a next index that only publishes 10.0.0 cannot be # satisfied. The refusal must name the next layout and suggest a release that @@ -312,3 +313,64 @@ Feature: TheRock "next" ROCm 10 install layout Given a ROCm 10 tarball fixture whose older 10.1 patch was uploaded last When the user previews a tarball SDK install for arch gfx1200 pinned to ROCm 10.1 Then the preview selects the ROCm 10.1.2 tarball, not the later-uploaded 10.1.0 + + # A line pin that matches nothing on the tarball catalog. The refusal names + # the archives that catalog does publish for the family, newest first, and a + # `--version`/`--family` pair to re-run with. It says archive, not package + # stack, and offers no nightly. Re-running the suggestion proves it clears + # the failure. + @id:therock-next-19-unsatisfied-tarball-line-pin-suggests-a-published-archive @requires-os:linux + Scenario: therock-next-19 - An unsatisfied ROCm 10 tarball pin suggests an archive the catalog publishes + Given a ROCm 10 tarball fixture whose older 10.1 patch was uploaded last + When the user tries to preview a tarball SDK install for arch gfx1200 pinned to ROCm 10.2 + Then the install fails + And the failure lists the published ROCm 10 archives for gfx120X-all and suggests 10.1.2 for arch gfx1200 + When the user re-runs the tarball preview with the version and arch the failure suggested + Then the preview selects the ROCm 10.1.2 tarball, not the later-uploaded 10.1.0 + + # `rocm update` re-resolves an installed runtime with no `--version` and has + # no `--family`. A ROCm 10 runtime whose manifest records only its grouped + # family has no exact arch, so its update cannot resolve a device payload on + # any release. That failure must say so and must not send the user to a + # `--version` or tell them to re-run the update with `--family`, which it + # does not accept. + @id:therock-next-20-update-with-no-exact-arch-gets-no-version-advice + Scenario: therock-next-20 - An update that cannot resolve a device target is not told to change its version + Given a canonical release pip index fixture and a ROCm 10 pip index fixture + And a registered ROCm 10 wheel runtime that records no exact arch + When the user tries to preview applying the pending update to that runtime + Then the install fails + And the failure says no exact device target is known, without suggesting a version or a --family re-run + + # The newest release's torchaudio is only a wheel this host cannot install, + # so the update of a ROCm 10 runtime fails on it. An update has no `--version` + # to change, so the failure names a whole `rocm install sdk` command for the + # older release that keeps the runtime's format and toolchain extras. + # Running that command proves it exists, accepts those flags, and resolves. + @id:therock-next-21-failed-update-suggests-an-install-that-keeps-its-extras + Scenario: therock-next-21 - A failed ROCm 10 update suggests an install command that keeps the runtime's format and toolchain + Given a ROCm 10 pip index fixture whose ROCm 10.1.0 torchaudio is only a wheel this host cannot install + And a registered ROCm 10 wheel runtime with a grouped family + When the user tries to preview applying the pending update to that runtime + Then the install fails + And the failure suggests installing the published ROCm 10.0.0 as a wheel for arch gfx1200 with the toolchain + When the user previews the install command the failure suggested + Then the preview resolves ROCm 10.0.0 with the gfx1200 device extras and the toolchain + + # A `major.minor.patch` pin stays exact even when later patches of its line + # are published: `--version 10.1.0` must not drift to 10.1.2. + @id:therock-next-22-exact-pin-ignores-later-patches + Scenario: therock-next-22 - An exact ROCm 10.1.0 pin installs 10.1.0 even when a later 10.1 patch is published + Given a ROCm 10 pip index fixture that publishes several 10.1 builds, a 10.1 prerelease and a 10.10 build + When the user previews a wheel SDK install for arch gfx1200 pinned to ROCm 10.1.0 + Then the preview resolves the ROCm 10 pip index for exactly ROCm 10.1.0, not the later 10.1.2 + + # A line pin below ROCm 10 stays on the canonical index and takes the newest + # stable release of its line: 7.14.1, not 7.14.0, the 7.14.2rc1 prerelease or + # 7.15.0. + @id:therock-next-23-canonical-line-pin + Scenario: therock-next-23 - A ROCm 7.14 line pin installs the newest stable 7.14 build from the canonical index + Given a canonical release pip index fixture that publishes several 7.14 builds, a 7.14 prerelease and a 7.15 build + When the user previews a wheel SDK install for arch gfx1200 pinned to ROCm 7.14 + Then the preview resolves the canonical release pip index for ROCm 7.14.1 + And the preview never mentions the ROCm 10 pip index diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 5242f07e93..70329d674f 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -430,6 +430,115 @@ fn serve_two_next_builds_with_torchaudio_rebuilds(world: &mut E2eWorld) { serve_two_next_builds(world, &torchaudio); } +/// One build of each stack package per `rocm` version in `builds`, every one +/// labelled for its `rocm` build and requiring it the way the live index does: +/// torch its exact `rocm`, torchvision and torchaudio their exact torch. The +/// torch and torchvision releases are any pair the canonical matcher accepts; +/// what a scenario reads is which `rocm` build was chosen. +fn write_line_builds(served: &Path, builds: &[&str], torch: &str, torchvision: &str) { + write_fixture(&served.join("index.html"), &aggregate_root_html()); + let torch_of = |rocm: &str| format!("{torch}+rocm{rocm}"); + let rocm = builds + .iter() + .map(|rocm| (*rocm, ANY_WHEEL_TAG, Vec::new())) + .collect::>(); + let torch_versions = builds.iter().map(|rocm| torch_of(rocm)).collect::>(); + let torchvision_versions = builds + .iter() + .map(|rocm| format!("{torchvision}+rocm{rocm}")) + .collect::>(); + let torch_builds = builds + .iter() + .zip(&torch_versions) + .map(|(rocm, torch)| (torch.as_str(), ANY_WHEEL_TAG, vec![format!("rocm=={rocm}")])) + .collect::>(); + let torchvision_builds = torchvision_versions + .iter() + .zip(&torch_versions) + .map(|(torchvision, torch)| { + ( + torchvision.as_str(), + ANY_WHEEL_TAG, + vec![format!("torch=={torch}")], + ) + }) + .collect::>(); + // torchaudio shares torch's release number and build label. + let torchaudio_builds = torch_versions + .iter() + .map(|torch| { + ( + torch.as_str(), + ANY_WHEEL_TAG, + vec![format!("torch=={torch}")], + ) + }) + .collect::>(); + write_wheel_index_builds(&served.join("rocm"), "rocm", &rocm); + write_wheel_index_builds(&served.join("torch"), "torch", &torch_builds); + write_wheel_index_builds( + &served.join("torchvision"), + "torchvision", + &torchvision_builds, + ); + write_wheel_index_builds(&served.join("torchaudio"), "torchaudio", &torchaudio_builds); +} + +/// The 10.1 line's newest stable build: what `--version 10.1` must select. +const NEXT_LINE_NEWEST_VERSION: &str = "10.1.2"; +/// A prerelease above it, a `10.10` build a prefix match would take, an older +/// build of the line and a build of the previous line. +const NEXT_LINE_BUILDS: [&str; 5] = [ + "10.0.0", + "10.1.0", + NEXT_LINE_NEWEST_VERSION, + "10.1.3rc1", + "10.10.0", +]; + +#[given( + "a ROCm 10 pip index fixture that publishes several 10.1 builds, a 10.1 prerelease and a 10.10 build" +)] +async fn pip_index_fixture_with_next_line_builds(world: &mut E2eWorld) { + let served = root(world).join("therock-pip-fixtures").join("next"); + write_line_builds(&served, &NEXT_LINE_BUILDS, "2.11.0", "0.26.0"); + serve_pip_fixtures(world); +} + +/// The 7.14 line's newest stable build: what `--version 7.14` must select. +const CANONICAL_LINE_NEWEST_VERSION: &str = "7.14.1"; +const CANONICAL_LINE_BUILDS: [&str; 4] = [ + "7.14.0", + CANONICAL_LINE_NEWEST_VERSION, + "7.14.2rc1", + "7.15.0", +]; + +#[given( + "a canonical release pip index fixture that publishes several 7.14 builds, a 7.14 prerelease and a 7.15 build" +)] +async fn pip_index_fixture_with_canonical_line_builds(world: &mut E2eWorld) { + let served = root(world).join("therock-pip-fixtures").join("current"); + write_line_builds(&served, &CANONICAL_LINE_BUILDS, "2.9.0", "0.24.0"); + serve_pip_fixtures(world); +} + +/// The newer build's only torchaudio is a wheel this host cannot install, so +/// for this Python and platform it publishes none; the older build publishes +/// an installable one. The mirror of the fixture below. +#[given( + "a ROCm 10 pip index fixture whose ROCm 10.1.0 torchaudio is only a wheel this host cannot install" +)] +async fn pip_index_fixture_without_newest_torchaudio(world: &mut E2eWorld) { + serve_two_next_builds( + world, + &[ + (NEXT_TORCHAUDIO_VERSION, ANY_WHEEL_TAG), + (NEWER_NEXT_TORCHAUDIO_ORIGINAL_VERSION, FOREIGN_WHEEL_TAG), + ], + ); +} + #[given("a ROCm 10 pip index fixture that also publishes a newer ROCm 10 build")] async fn pip_index_fixture_with_newer_next_build(world: &mut E2eWorld) { serve_two_next_builds_with_torchaudio_rebuilds(world); @@ -473,6 +582,22 @@ const NEXT_GROUPED_FAMILY_RUNTIME_KEY: &str = "release-wheel-next-v1-gfx120x-all /// `source_layout_generation`, not derived from the version string. #[given("a registered ROCm 10 wheel runtime with a grouped family")] async fn registered_next_wheel_runtime_with_grouped_family(world: &mut E2eWorld) { + plant_next_wheel_runtime(world, Some(RAW_ARCH)); +} + +/// The same runtime from before ROCm CLI recorded the exact arch: no +/// `rocm_sdk_target`, and no `device-*` extra in its specs to recover one from, +/// so only the grouped family is known. +#[given("a registered ROCm 10 wheel runtime that records no exact arch")] +async fn registered_next_wheel_runtime_without_exact_arch(world: &mut E2eWorld) { + plant_next_wheel_runtime(world, None); +} + +fn plant_next_wheel_runtime(world: &mut E2eWorld, exact_arch: Option<&str>) { + let rocm_extras = exact_arch.map_or_else( + || "libraries,devel".to_owned(), + |arch| format!("libraries,devel,device-{arch}"), + ); let install_root = root(world).join("runtime-next-grouped-family"); std::fs::create_dir_all(&install_root).expect("failed to create install root"); @@ -493,12 +618,12 @@ async fn registered_next_wheel_runtime_with_grouped_family(world: &mut E2eWorld) "wheel_composition": { "source_layout_generation": "next-v1", "package_specs": [ - format!("rocm[libraries,devel,device-{RAW_ARCH}]==9.0.0"), + format!("rocm[{rocm_extras}]==9.0.0"), "torch==2.9.0+rocm9.0.0", "torchvision==0.24.0+rocm9.0.0", "torchaudio==2.9.0+rocm9.0.0", ], - "rocm_sdk_target": RAW_ARCH, + "rocm_sdk_target": exact_arch, }, "installed_at_unix_ms": 1_700_000_000_000u64, })) @@ -704,6 +829,20 @@ async fn preview_apply_pending_update(world: &mut E2eWorld) { ); } +#[when("the user tries to preview applying the pending update to that runtime")] +async fn try_preview_apply_pending_update(world: &mut E2eWorld) { + preview( + world, + &[ + "update", + "--apply", + "--dry-run", + "--runtime", + NEXT_GROUPED_FAMILY_RUNTIME_KEY, + ], + ); +} + #[given("an untrusted ROCm 10 pip base override")] async fn untrusted_pip_index_fixture(world: &mut E2eWorld) { let served = root(world).join("untrusted-therock-pip-fixture"); @@ -757,6 +896,21 @@ const NEXT_LINE_NEWEST_TARBALL: &str = "therock-dist-linux-gfx120X-all-10.1.2.ta /// The older 10.1 patch, uploaded last: newest by mtime, not by version. const NEXT_LINE_LATEST_UPLOAD_TARBALL: &str = "therock-dist-linux-gfx120X-all-10.1.0.tar.gz"; +/// Queue the env that points the next `rocm` run at the served tarball +/// catalogs. Each run consumes `command_env`, so a second run calls this again. +fn point_at_tarball_fixtures(world: &mut E2eWorld) { + allow_base_overrides(world); + let base = server_base(world); + let next = next_tarball_base(world); + world.command_env.push(( + "ROCM_CLI_THEROCK_RELEASE_TARBALL_BASE", + format!("{base}/tarball/current/").into(), + )); + world + .command_env + .push(("ROCM_CLI_THEROCK_NEXT_TARBALL_BASE", next.into())); +} + #[given("a ROCm 10 tarball fixture whose older 10.1 patch was uploaded last")] async fn tarball_line_fixture(world: &mut E2eWorld) { let served = root(world).join("therock-tarball-fixtures"); @@ -773,16 +927,7 @@ async fn tarball_line_fixture(world: &mut E2eWorld) { ]), ); world.artifact_server = Some(LoopbackServer::start(&served)); - allow_base_overrides(world); - let base = server_base(world); - let next = next_tarball_base(world); - world.command_env.push(( - "ROCM_CLI_THEROCK_RELEASE_TARBALL_BASE", - format!("{base}/tarball/current/").into(), - )); - world - .command_env - .push(("ROCM_CLI_THEROCK_NEXT_TARBALL_BASE", next.into())); + point_at_tarball_fixtures(world); } /// Size and pacing for the paced tarball fixture below: large enough (versus @@ -1263,6 +1408,46 @@ async fn preview_line_pinned_tarball_install(world: &mut E2eWorld) { ); } +#[when("the user tries to preview a tarball SDK install for arch gfx1200 pinned to ROCm 10.2")] +async fn try_preview_unpublished_line_tarball_install(world: &mut E2eWorld) { + preview( + world, + &[ + "install", + "sdk", + "--channel", + "release", + "--format", + "tarball", + "--family", + RAW_ARCH, + "--version", + "10.2", + "--dry-run", + ], + ); +} + +#[when("the user previews a wheel SDK install for arch gfx1200 pinned to ROCm 7.14")] +async fn preview_canonical_line_pinned_wheel_install(world: &mut E2eWorld) { + preview_ok( + world, + &[ + "install", + "sdk", + "--channel", + "release", + "--format", + "wheel", + "--family", + RAW_ARCH, + "--version", + "7.14", + "--dry-run", + ], + ); +} + #[when("the user previews a tarball SDK install for family gfx120X-all pinned to ROCm 10.0.0")] async fn preview_pinned_tarball_install_with_group_family(world: &mut E2eWorld) { preview( @@ -1690,25 +1875,40 @@ async fn preview_resolves_next_pip_index(world: &mut E2eWorld) { ); } -#[then("the preview resolves the ROCm 10 pip index for ROCm 10.1.0")] -async fn preview_resolves_next_pip_index_for_rocm_10_1_line(world: &mut E2eWorld) { - let base = next_pip_base(world); - assert_contains(world, &format!("canonical_source: {base}"), "next source"); - assert_contains(world, &format!("index_url: {base}"), "resolved index"); +/// The `selected_rocm_version:` line names `expected` and none of the other +/// builds the fixture publishes. +fn assert_selected_rocm_version(world: &E2eWorld, expected: &str, published: &[&str]) { assert_contains( world, - &format!("latest_compatible_version: {NEWER_NEXT_ROCM_VERSION}"), - "resolved 10.1 line", + &format!("selected_rocm_version: {expected}\n"), + "selected ROCm build", ); + for other in published.iter().filter(|version| **version != expected) { + assert!( + !stdout(world).contains(&format!("selected_rocm_version: {other}\n")), + "the preview selected {other} instead of {expected}:\n{}", + stdout(world) + ); + } +} + +#[then( + "the preview resolves the ROCm 10 pip index for ROCm 10.1.2, the newest stable build of the 10.1 line" +)] +async fn preview_resolves_next_pip_index_for_rocm_10_1_line(world: &mut E2eWorld) { + let base = next_pip_base(world); + assert_contains(world, &format!("canonical_source: {base}"), "next source"); assert_contains( world, "requested: version 10.1", "the pin that selected the line", ); - assert!( - !stdout(world).contains(&format!("latest_compatible_version: {NEXT_ROCM_VERSION}")), - "a 10.1 line pin selected 10.0.0:\n{}", - stdout(world) + assert_selected_rocm_version(world, NEXT_LINE_NEWEST_VERSION, &NEXT_LINE_BUILDS); + // What `uv` would be asked to install: the line's newest build, whole. + assert_contains( + world, + &format!("rocm[libraries,device-{RAW_ARCH}]=={NEXT_LINE_NEWEST_VERSION} "), + "line build in the requirements", ); assert!( !stdout(world).contains(¤t_pip_base(world)), @@ -1717,6 +1917,49 @@ async fn preview_resolves_next_pip_index_for_rocm_10_1_line(world: &mut E2eWorld ); } +#[then("the preview resolves the ROCm 10 pip index for exactly ROCm 10.1.0, not the later 10.1.2")] +async fn preview_resolves_exact_pin_despite_later_patch(world: &mut E2eWorld) { + assert_contains( + world, + &format!("canonical_source: {}", next_pip_base(world)), + "next source", + ); + assert_selected_rocm_version(world, NEWER_NEXT_ROCM_VERSION, &NEXT_LINE_BUILDS); +} + +#[then("the preview resolves the canonical release pip index for ROCm 7.14.1")] +async fn preview_resolves_canonical_line(world: &mut E2eWorld) { + assert_contains( + world, + &format!("canonical_source: {}", current_pip_base(world)), + "canonical source", + ); + assert_contains( + world, + "requested: version 7.14", + "the pin that selected the line", + ); + assert_selected_rocm_version(world, CANONICAL_LINE_NEWEST_VERSION, &CANONICAL_LINE_BUILDS); + // The device extra on the canonical layout follows the GPU this host + // reports, so only the versions are asserted: the whole stack is the + // line's newest build. + assert_contains( + world, + &format!("latest_compatible_version: {CANONICAL_LINE_NEWEST_VERSION}\n"), + "canonical line version", + ); + assert_contains( + world, + &format!("]=={CANONICAL_LINE_NEWEST_VERSION} torch[device-"), + "canonical line install plan", + ); + assert_contains( + world, + &format!("torchaudio==2.9.0+rocm{CANONICAL_LINE_NEWEST_VERSION}\n"), + "canonical line torchaudio", + ); +} + #[then("the preview resolves the default ROCm 10 pip index")] async fn preview_resolves_default_next_pip_index(world: &mut E2eWorld) { assert_contains( @@ -2035,6 +2278,143 @@ async fn rerun_with_suggested_version(world: &mut E2eWorld) { preview_ok(world, &args); } +#[then( + "the failure lists the published ROCm 10 archives for gfx120X-all and suggests 10.1.2 for arch gfx1200" +)] +async fn failure_lists_published_next_archives(world: &mut E2eWorld) { + let reported = reported_output(world); + assert!( + reported.contains("next-layout TheRock release tarball stream is incomplete"), + "the refusal did not name the next-layout catalog:\n{reported}" + ); + assert!( + reported.contains(&format!( + "No archive for {GROUP_FAMILY} was found for version 10.2 on the ROCm 10+ next layout. \ + Stable releases it publishes for {GROUP_FAMILY}: 10.1.2, 10.1.0, 10.0.0. \ + Re-run with one of them, for example `--version 10.1.2 --family {RAW_ARCH}`." + )), + "the refusal did not list the published archives and suggest the newest:\n{reported}" + ); + for absent in ["nightly", "package stack", "tarball_url:"] { + assert!( + !reported.contains(absent), + "the refusal contains `{absent}`:\n{reported}" + ); + } +} + +/// The tarball twin of [`rerun_with_suggested_version`]. +#[when("the user re-runs the tarball preview with the version and arch the failure suggested")] +async fn rerun_tarball_with_suggested_version(world: &mut E2eWorld) { + let reported = reported_output(world); + let suggested = reported + .split('`') + .find(|chunk| chunk.starts_with("--version ")) + .unwrap_or_else(|| panic!("the failure suggested no `--version` command:\n{reported}")) + .to_owned(); + let mut args = vec![ + "install", + "sdk", + "--channel", + "release", + "--format", + "tarball", + ]; + args.extend(suggested.split_whitespace()); + args.push("--dry-run"); + point_at_tarball_fixtures(world); + preview_ok(world, &args); +} + +#[then( + "the failure says no exact device target is known, without suggesting a version or a --family re-run" +)] +async fn failure_names_missing_device_target_without_version_advice(world: &mut E2eWorld) { + let reported = reported_output(world); + assert!( + reported.contains("without an exact device target"), + "the refusal did not say the device target is unknown:\n{reported}" + ); + assert!( + reported.contains(&format!("from next-layout source {}", next_pip_base(world))), + "the refusal did not name the next-layout source:\n{reported}" + ); + // No release can clear this, and `rocm update` takes no `--family`. + for absent in [ + "--version", + "re-run with `--family`", + "Install one of them", + "Re-run with one of them", + "nightly", + ] { + assert!( + !reported.contains(absent), + "the refusal contains `{absent}`:\n{reported}" + ); + } +} + +/// The install command a failed update suggests for its runtime: a wheel with +/// the toolchain extras the runtime had, at the exact arch it recorded. +fn suggested_update_install(version: &str) -> String { + format!( + "rocm install sdk --channel release --format wheel --version {version} --family {RAW_ARCH} --devel" + ) +} + +#[then( + "the failure suggests installing the published ROCm 10.0.0 as a wheel for arch gfx1200 with the toolchain" +)] +async fn failure_suggests_install_that_keeps_extras(world: &mut E2eWorld) { + let reported = reported_output(world); + assert!( + reported.contains(&format!( + "no torchaudio built for ROCm {NEWER_NEXT_ROCM_VERSION} is published for this Python and platform" + )), + "the refusal did not say why {NEWER_NEXT_ROCM_VERSION} failed:\n{reported}" + ); + assert!( + reported.contains(&format!( + "Install one of them, for example `{}`.", + suggested_update_install(NEXT_ROCM_VERSION) + )), + "the refusal did not suggest an install that keeps the runtime's format and extras:\n{reported}" + ); + for absent in ["Re-run with one of them", "nightly", "package_specs:"] { + assert!( + !reported.contains(absent), + "the refusal contains `{absent}`:\n{reported}" + ); + } +} + +/// Runs exactly the `rocm install sdk` command the previous failure printed, as +/// a preview, so the scenario proves the command exists, accepts those flags +/// and resolves. +#[when("the user previews the install command the failure suggested")] +async fn preview_suggested_install_command(world: &mut E2eWorld) { + let reported = reported_output(world); + let suggested = reported + .split('`') + .find(|chunk| chunk.starts_with("rocm install sdk ")) + .unwrap_or_else(|| panic!("the failure suggested no install command:\n{reported}")) + .to_owned(); + let mut args = suggested.split_whitespace().skip(1).collect::>(); + args.push("--dry-run"); + point_at_pip_fixtures(world); + preview_ok(world, &args); +} + +#[then("the preview resolves ROCm 10.0.0 with the gfx1200 device extras and the toolchain")] +async fn preview_resolves_suggested_install(world: &mut E2eWorld) { + assert_contains( + world, + &format!("selected_rocm_version: {NEXT_ROCM_VERSION}\n"), + "suggested release", + ); + assert_version_resolution_extras(world, true); +} + #[then("the failure asks for an exact GPU arch and names --family gfx1200")] async fn failure_names_the_exact_arch_flag(world: &mut E2eWorld) { // Both streams: what matters is that the user is told how to fix it, not From a020c6c0a613d473bc7d709ff45165068682646f Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 17 Nov 2026 14:54:00 +0200 Subject: [PATCH 09/11] fix(sdk): suggest a ROCm 10 release only for a release-channel failure The next-layout recovery hint assumed the release channel: it filtered the listing for stable releases and printed `--channel release`. A nightly request also reads the next layout, which publishes only prerelease builds for it, so a failed nightly install or update was told no stable release exists, or handed a command that moves it to the release channel. `NextLayoutRecovery` now carries the request's channel, the filter and the printed `--channel` use it, and a nightly failure gets no release list: the wheel context prints the source line alone and the tarball context says no nightly archive matched. Signed-off-by: Roman Inflianskas --- README.md | 4 +- apps/rocm/src/therock/resolve/next_hint.rs | 33 +++++++-- apps/rocm/src/therock/resolve/tarball.rs | 79 ++++++++++++++++------ apps/rocm/src/therock/resolve/wheel.rs | 37 ++++++++++ docs/manual-testing.md | 3 +- 5 files changed, 130 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 1a75b5bc89..5b228430b4 100644 --- a/README.md +++ b/README.md @@ -754,7 +754,9 @@ ROCm 10 releases that source publishes, if any, and suggests one of them to re-run with, in the same `--format` as the failed request. When `rocm update` fails the same way, it suggests a whole `rocm install sdk` command that keeps the runtime's format and `--devel` toolchain. A failure no other version can -fix, such as an unknown GPU arch or a network error, suggests no version. +fix, such as an unknown GPU arch or a network error, suggests no version, and +neither does a failed `--channel nightly` request, whose builds are not stable +releases. #### Driver installation diff --git a/apps/rocm/src/therock/resolve/next_hint.rs b/apps/rocm/src/therock/resolve/next_hint.rs index 3f80dfdacd..5ee254c81d 100644 --- a/apps/rocm/src/therock/resolve/next_hint.rs +++ b/apps/rocm/src/therock/resolve/next_hint.rs @@ -85,6 +85,9 @@ pub(in crate::therock) enum RecoveryFormat { /// What a suggested command has to carry over from the request that failed. #[derive(Clone, Copy, Debug)] pub(in crate::therock) struct NextLayoutRecovery<'a> { + /// The channel the failed request read. Only the release channel gets a + /// list of releases to try: see [`NextLayoutRecovery::suggests_releases`]. + pub(in crate::therock) channel: TheRockChannel, pub(in crate::therock) format: RecoveryFormat, /// The exact arch the request resolved with, so the command repeats it. pub(in crate::therock) exact_arch: Option<&'a str>, @@ -94,6 +97,18 @@ pub(in crate::therock) struct NextLayoutRecovery<'a> { pub(in crate::therock) include_devel: bool, } +impl NextLayoutRecovery<'_> { + /// Whether a failure on the next layout is followed by + /// [`next_layout_unsatisfied_hint`]. On the release channel a different + /// stable release can clear it. The nightly channel publishes only + /// prerelease builds there, which that hint does not name and which a + /// `--version` re-run on the release channel would leave, so a nightly + /// failure gets its own message and no suggestion. + pub(in crate::therock) fn suggests_releases(&self) -> bool { + self.channel == TheRockChannel::Release + } +} + /// How many published releases a next-layout failure lists by name. const NEXT_LAYOUT_HINT_MAX_LISTED: usize = 5; @@ -107,8 +122,9 @@ const NEXT_LAYOUT_HINT_MAX_LISTED: usize = 5; /// (`None` when the listing could not be read), narrowed to one GPU family when /// `family_scope` names it. `attempted` is the release the failure recorded, /// and the hint leaves it out. It also leaves out any release -/// [`layout_serving`] would not route (the re-run is a release-channel pin) back to this layout, so a re-run -/// searches the same layout. When nothing else qualifies, the hint says so and +/// [`layout_serving`] would not route back to this layout on the request's +/// channel, so a re-run searches the same layout. Callers reach it only for +/// the release channel ([`NextLayoutRecovery::suggests_releases`]). When nothing else qualifies, the hint says so and /// names no command. /// /// The command depends on the caller: @@ -149,7 +165,7 @@ pub(in crate::therock) fn next_layout_unsatisfied_hint( .filter(|version| attempted != Some(version.as_str())) .filter(|version| { layout_serving( - TheRockChannel::Release, + recovery.channel, Some(&RuntimeVersionSelector::Version((*version).clone())), ) == SourceLayout::Next }) @@ -210,8 +226,9 @@ fn recovery_command(pinned: bool, version: &str, recovery: NextLayoutRecovery<'_ } else { "" }; + let channel = recovery.channel.as_str(); format!( - "Install one of them, for example `rocm install sdk --channel release --format {format} --version {version} --family {family}{devel}`{placeholder_note}." + "Install one of them, for example `rocm install sdk --channel {channel} --format {format} --version {version} --family {family}{devel}`{placeholder_note}." ) } @@ -244,7 +261,9 @@ pub(super) fn canonical_wheel_resolution_hint(channel: TheRockChannel) -> String /// /// A ROCm >= 10 pin already refused `--channel nightly` before resolution /// (`select_source_layout`), so the canonical hint's nightly suggestion must -/// not be what a next-layout failure prints. On the next layout: +/// not be what a next-layout failure prints. On the next layout, a nightly +/// failure gets the source line alone (see +/// [`NextLayoutRecovery::suggests_releases`]). On the release channel: /// - `published` is `None` when the `rocm` listing itself could not be read, /// and the context says no other version can be suggested. /// - `unsatisfied` is the [`VersionUnsatisfied`] in the failure's chain. Only @@ -266,6 +285,7 @@ pub(super) fn wheel_resolution_failure_context( let (source_label, hint) = match layout { SourceLayout::Next => { let hint = match (published, unsatisfied) { + _ if !recovery.suggests_releases() => None, (None, _) => Some(next_layout_unsatisfied_hint( version_selector, None, @@ -308,6 +328,7 @@ mod tests { } const WHEEL_AT_GFX1200: NextLayoutRecovery<'static> = NextLayoutRecovery { + channel: TheRockChannel::Release, format: RecoveryFormat::Wheel, exact_arch: Some("gfx1200"), include_devel: false, @@ -478,6 +499,7 @@ mod tests { Some(&published), Some("10.1.0"), NextLayoutRecovery { + channel: TheRockChannel::Release, format: RecoveryFormat::Wheel, exact_arch: Some("gfx1200"), include_devel: true, @@ -527,6 +549,7 @@ mod tests { Some(&published), None, NextLayoutRecovery { + channel: TheRockChannel::Release, format: RecoveryFormat::Tarball, exact_arch: None, include_devel: false, diff --git a/apps/rocm/src/therock/resolve/tarball.rs b/apps/rocm/src/therock/resolve/tarball.rs index 28dac5943a..5da76c0990 100644 --- a/apps/rocm/src/therock/resolve/tarball.rs +++ b/apps/rocm/src/therock/resolve/tarball.rs @@ -17,8 +17,8 @@ use super::super::family::{family_resolution_hint, resolve_family}; use super::super::fetch::download_text_cached; use super::super::platform_tarball_token; use super::super::source::{ - FamilyResolution, RuntimeVersionSelector, SourceLayout, TheRockChannel, gate_install_layout, - resolve_source, selector_is_release_line, + FamilyResolution, RuntimeVersionSelector, SourceLayout, THEROCK_NEXT_MIN_MAJOR, TheRockChannel, + gate_install_layout, resolve_source, selector_is_release_line, }; use super::super::version::{ compare_version_strings, is_parseable_runtime_version, is_stable_runtime_version, @@ -238,9 +238,10 @@ fn select_tarball_candidate( /// The context added when [`select_tarball_candidate`] finds no archive. /// -/// That is the only failure it wraps, and a different `--version` can clear -/// it, so on the next layout it is always followed by the list of releases to -/// try. No archive was picked, so no release counts as attempted. The +/// That is the only failure it wraps, and on the release channel a different +/// `--version` can clear it, so there the next layout's failure is always +/// followed by the list of releases to try; a nightly one is not (see +/// `NextLayoutRecovery::suggests_releases`). No archive was picked, so no release counts as attempted. The /// suggested command is a tarball install. It carries no `devel` extras, /// because a tarball has none. fn tarball_resolution_failure_context( @@ -251,20 +252,30 @@ fn tarball_resolution_failure_context( published: &[String], ) -> String { let (stream, hint) = match layout { - SourceLayout::Next => ( - "next-layout", - next_layout_unsatisfied_hint( - version_selector, - Some(published), - None, - NextLayoutRecovery { - format: RecoveryFormat::Tarball, - exact_arch: family_resolution.raw_arch.as_deref(), - include_devel: false, - }, - Some(&family_resolution.family), - ), - ), + SourceLayout::Next => { + let recovery = NextLayoutRecovery { + channel, + format: RecoveryFormat::Tarball, + exact_arch: family_resolution.raw_arch.as_deref(), + include_devel: false, + }; + let hint = if recovery.suggests_releases() { + next_layout_unsatisfied_hint( + version_selector, + Some(published), + None, + recovery, + Some(&family_resolution.family), + ) + } else { + format!( + "No {} archive for {} matched this request on the ROCm {THEROCK_NEXT_MIN_MAJOR}+ next layout.", + channel.as_str(), + family_resolution.family + ) + }; + ("next-layout", hint) + } SourceLayout::Canonical => ( "canonical", family_resolution_hint( @@ -638,6 +649,36 @@ mod tests { "{update}" ); + // A nightly request on the next layout gets no release list and no + // command: that catalog publishes prerelease archives, which the + // stable-release hint cannot name, and a `--channel release` command + // would move the user off the channel they asked for. + let nightly = tarball_resolution_failure_context( + TheRockChannel::Nightly, + SourceLayout::Next, + &family, + None, + &["10.3.0a20261111".to_owned()], + ); + assert!( + nightly.starts_with("next-layout TheRock nightly tarball"), + "{nightly}" + ); + assert!( + nightly.contains( + "No nightly archive for gfx120X-all matched this request on the ROCm 10+ next layout." + ), + "{nightly}" + ); + for absent in [ + "--version", + "--channel", + "rocm install sdk", + "stable release", + ] { + assert!(!nightly.contains(absent), "{nightly} contains {absent}"); + } + let canonical = tarball_resolution_failure_context( TheRockChannel::Release, SourceLayout::Canonical, diff --git a/apps/rocm/src/therock/resolve/wheel.rs b/apps/rocm/src/therock/resolve/wheel.rs index 39eb7849a1..93f1bcddcc 100644 --- a/apps/rocm/src/therock/resolve/wheel.rs +++ b/apps/rocm/src/therock/resolve/wheel.rs @@ -804,6 +804,7 @@ fn resolve_pip_runtime_plan( // Loaded here rather than inside `resolve_pip_runtime_from_index` so a // failure further down can name the releases this index does publish. let recovery = NextLayoutRecovery { + channel, format: RecoveryFormat::Wheel, exact_arch: family_resolution.raw_arch.as_deref(), include_devel, @@ -2932,6 +2933,7 @@ sdk install } const WHEEL_AT_GFX1201: NextLayoutRecovery<'static> = NextLayoutRecovery { + channel: TheRockChannel::Release, format: RecoveryFormat::Wheel, exact_arch: Some("gfx1201"), include_devel: false, @@ -3029,6 +3031,41 @@ sdk install assert!(!unreadable.contains("--version"), "{unreadable}"); } + /// A nightly request reads the next layout too, but that layout publishes + /// only prerelease builds for it, which the stable-release hint cannot name. + /// Even a failure another release could clear gets no release list and no + /// `--channel release` command, which would move the user off the channel + /// they asked for. + #[test] + fn a_nightly_next_layout_failure_suggests_no_release() { + let nightly = NextLayoutRecovery { + channel: TheRockChannel::Nightly, + ..WHEEL_AT_GFX1201 + }; + let published = vec!["10.3.0a20261110".to_owned(), "10.3.0a20261111".to_owned()]; + let unsatisfied = VersionUnsatisfied::new( + Some("10.3.0a20261111"), + "no torchaudio built for ROCm 10.3.0a20261111 is published".to_owned(), + ); + for (selector, listing) in [(None, Some(published.as_slice())), (None, None)] { + let context = wheel_resolution_failure_context( + TheRockChannel::Nightly, + SourceLayout::Next, + THEROCK_NEXT_PIP_INDEX_BASE, + selector, + listing, + Some(&unsatisfied), + nightly, + ); + assert_eq!( + context, + format!( + "failed to resolve TheRock nightly wheel runtime from next-layout source {THEROCK_NEXT_PIP_INDEX_BASE}" + ) + ); + } + } + /// The three failures a different release can clear are raised as the /// marker, each recording the release it tried where there was one, and /// each keeping its own message. diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 8266c4ceb9..1b94a9edd2 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -295,7 +295,8 @@ Version pins, checked with `--dry-run`: suggests a whole `rocm install sdk` command with the runtime's `--format` and, for a `--devel` runtime, `--devel`. Running that command with `--dry-run` must succeed. A failure no other version can clear, such as an - unknown device target, must suggest no version. + unknown device target, must suggest no version, and so must a failed + `--channel nightly` install or update. ### 2a. A GPU target with no ROCm build From afcf0d48ee005986b5aa609384cd56be5605096d Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 17 Nov 2026 14:54:00 +0200 Subject: [PATCH 10/11] test(sdk): drive a failed update's install suggestion end to end therock-next-32 registers a ROCm 10 runtime whose newest release lists every package but has no installable set, so a real `uv pip compile` reports no solution. The update fails with the install command for the other release, and the scenario runs that command and checks it resolves with the same extras. It goes red if the "No solution found" classification stops matching uv's output. Also isolate the line-pin major check (`10.1` must not match `11.1.0` or `9.1.0`) and drop a step definition no scenario used. Signed-off-by: Roman Inflianskas --- apps/rocm/src/therock/source.rs | 6 + docs/testing.md | 7 +- .../features/therock_next_generation.feature | 15 +++ tests/e2e-cucumber/tests/e2e/therock_steps.rs | 124 ++++++++++++++++-- 4 files changed, 137 insertions(+), 15 deletions(-) diff --git a/apps/rocm/src/therock/source.rs b/apps/rocm/src/therock/source.rs index bb564bc129..cbb61436b7 100644 --- a/apps/rocm/src/therock/source.rs +++ b/apps/rocm/src/therock/source.rs @@ -846,6 +846,12 @@ mod tests { !line.matches_version("10.10.0"), "10.1 must not prefix-match 10.10" ); + // Same minor, another major: only the major check rejects these. + assert!( + !line.matches_version("11.1.0"), + "10.1 must not match a later major's 1 line" + ); + assert!(!line.matches_version("9.1.0")); let selected = select_rocm_version( TheRockChannel::Release, diff --git a/docs/testing.md b/docs/testing.md index 83acf2cf50..d1d31e1f61 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1377,7 +1377,9 @@ with. `rocm update`, which has neither flag, is given a whole `rocm install sdk` command with the runtime's `--format` and `--devel`. Any other failure, such as an unknown device target, a `uv` that could not be fetched or an unreachable index, suggests no version, because no release can -clear it. +clear it. A nightly request that fails on the ROCm 10 layout gets no +suggestion either: that layout publishes only prerelease builds for the +nightly channel, which the stable-release list cannot name. Loopback-fixture scenarios in [therock_next_generation.feature](../tests/e2e-cucumber/features/therock_next_generation.feature) @@ -1398,6 +1400,9 @@ cover this: - `therock-next-31`: an unpinned install where no build has an installable torchaudio fails with no version suggested, because another version would fail the same way. +- `therock-next-32`: an update whose newest release has no installable package + set (a real `uv pip compile` reports no solution) suggests an install that + keeps the runtime's format and toolchain. The scenario runs that command. They run in the default e2e lane. `therock-next-26` and `therock-next-27` are Linux-only, because Windows refuses tarball installs. diff --git a/tests/e2e-cucumber/features/therock_next_generation.feature b/tests/e2e-cucumber/features/therock_next_generation.feature index 1960ad2d9e..b559f63007 100644 --- a/tests/e2e-cucumber/features/therock_next_generation.feature +++ b/tests/e2e-cucumber/features/therock_next_generation.feature @@ -471,3 +471,18 @@ Feature: TheRock "next" ROCm 10 install layout When the user tries to preview a wheel SDK install for arch gfx1200 with no version pin Then the install fails And the failure names the missing torchaudio without suggesting another version + + # An update has no `--version` to change. When the newest release has every + # package listed but no installable set (`uv pip compile` finds no + # solution), the failure names a whole `rocm install sdk` command for the + # other release, keeping the runtime's format and toolchain extras. Running + # that command proves it exists, accepts those flags, and resolves. + @id:therock-next-32-failed-update-suggests-an-install-that-keeps-its-extras + Scenario: therock-next-32 - A ROCm 10 update with no installable package set suggests an install command that keeps the runtime's format and toolchain + Given a ROCm 10 pip index fixture whose newest build has no installable package set + And a registered ROCm 10 wheel runtime with a grouped family + When the user tries to preview applying the pending update to that runtime + Then the install fails + And the failure suggests installing the other published ROCm 10.0.0 as a wheel for arch gfx1200 with the toolchain + When the user previews the install command the failure suggested + Then the preview resolves ROCm 10.0.0 with the gfx1200 device extras and the toolchain diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 64f93ccf96..0222351480 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -401,6 +401,18 @@ fn arm_pip_fixture_env(world: &mut E2eWorld) { /// build. `torchaudio` lists the torchaudio builds the index publishes, each /// with its wheel tag. fn serve_two_next_builds(world: &mut E2eWorld, torchaudio: &[(&str, &str)]) { + serve_two_next_builds_where_newer_torch_requires(world, torchaudio, NEWER_NEXT_ROCM_VERSION); +} + +/// [`serve_two_next_builds`], with the newer build's torch requiring +/// `rocm=={newer_torch_rocm}` instead of its own `rocm` build. Naming a `rocm` +/// the index does not publish leaves that build with every package listed but +/// no installable set, which `uv pip compile` reports as "No solution found". +fn serve_two_next_builds_where_newer_torch_requires( + world: &mut E2eWorld, + torchaudio: &[(&str, &str)], + newer_torch_rocm: &str, +) { let served = root(world).join("therock-pip-fixtures").join("next"); write_fixture(&served.join("index.html"), &aggregate_root_html()); let builds = [ @@ -416,8 +428,14 @@ fn serve_two_next_builds(world: &mut E2eWorld, torchaudio: &[(&str, &str)]) { ), ]; let rocm = builds.map(|(rocm, ..)| (rocm, ANY_WHEEL_TAG, Vec::new())); - let torch = - builds.map(|(rocm, torch, _)| (torch, ANY_WHEEL_TAG, vec![format!("rocm=={rocm}")])); + let torch = builds.map(|(rocm, torch, _)| { + let requires = if rocm == NEWER_NEXT_ROCM_VERSION { + newer_torch_rocm + } else { + rocm + }; + (torch, ANY_WHEEL_TAG, vec![format!("rocm=={requires}")]) + }); let torchvision = builds.map(|(_, torch, torchvision)| { (torchvision, ANY_WHEEL_TAG, vec![format!("torch=={torch}")]) }); @@ -538,19 +556,22 @@ async fn pip_index_fixture_with_canonical_line_builds(world: &mut E2eWorld) { serve_pip_fixtures(world); } -/// The newer build's only torchaudio is a wheel this host cannot install, so -/// for this Python and platform it publishes none; the older build publishes -/// an installable one. The mirror of the fixture below. -#[given( - "a ROCm 10 pip index fixture whose ROCm 10.1.0 torchaudio is only a wheel this host cannot install" -)] -async fn pip_index_fixture_without_newest_torchaudio(world: &mut E2eWorld) { - serve_two_next_builds( +/// A `rocm` build no fixture publishes, so a torch that requires it cannot be +/// installed. +const UNPUBLISHED_NEXT_ROCM_VERSION: &str = "10.9.9"; + +/// Both builds list every package, so an unpinned resolution takes the newer +/// one, but its torch requires a `rocm` that is not published: `uv pip +/// compile` finds no solution for it, and a different release (the older +/// build) can still install. +#[given("a ROCm 10 pip index fixture whose newest build has no installable package set")] +async fn pip_index_fixture_with_unsolvable_newest_build(world: &mut E2eWorld) { + let mut torchaudio = vec![(NEXT_TORCHAUDIO_VERSION, ANY_WHEEL_TAG)]; + torchaudio.extend(NEWER_NEXT_TORCHAUDIO_VERSIONS.map(|version| (version, ANY_WHEEL_TAG))); + serve_two_next_builds_where_newer_torch_requires( world, - &[ - (NEXT_TORCHAUDIO_VERSION, ANY_WHEEL_TAG), - (NEWER_NEXT_TORCHAUDIO_ORIGINAL_VERSION, FOREIGN_WHEEL_TAG), - ], + &torchaudio, + UNPUBLISHED_NEXT_ROCM_VERSION, ); } @@ -2690,6 +2711,81 @@ async fn failure_names_missing_torchaudio_without_version_advice(world: &mut E2e } } +/// The install command a failed update suggests for its runtime: a wheel with +/// the toolchain extras the runtime had, at the exact arch it recorded. +fn suggested_update_install(version: &str) -> String { + format!( + "rocm install sdk --channel release --format wheel --version {version} --family {RAW_ARCH} --devel" + ) +} + +#[then( + "the failure suggests installing the other published ROCm 10.0.0 as a wheel for arch gfx1200 with the toolchain" +)] +async fn failure_suggests_install_that_keeps_extras(world: &mut E2eWorld) { + let reported = reported_output(world); + // The real `uv pip compile` output: the CLI classifies the failure as one + // another release can clear by finding this phrase, so a `uv` that reworded + // it would fail this step instead of silently dropping the suggestion. + for expected in [ + "published ROCm X package metadata is not jointly installable", + "No solution found", + UNPUBLISHED_NEXT_ROCM_VERSION, + ] { + assert!( + reported.contains(expected), + "the refusal did not carry `{expected}` from uv's failure:\n{reported}" + ); + } + // 10.1.0 is the release that failed, so it is not offered again. + assert!( + reported.contains(&format!( + "Other stable releases it publishes: {NEXT_ROCM_VERSION}." + )), + "the refusal did not list only the release that was not tried:\n{reported}" + ); + assert!( + reported.contains(&format!( + "Install one of them, for example `{}`.", + suggested_update_install(NEXT_ROCM_VERSION) + )), + "the refusal did not suggest an install that keeps the runtime's format and extras:\n{reported}" + ); + for absent in ["Re-run with one of them", "nightly", "package_specs:"] { + assert!( + !reported.contains(absent), + "the refusal contains `{absent}`:\n{reported}" + ); + } +} + +/// Runs exactly the `rocm install sdk` command the previous failure printed, as +/// a preview, so the scenario proves the command exists, accepts those flags +/// and resolves. +#[when("the user previews the install command the failure suggested")] +async fn preview_suggested_install_command(world: &mut E2eWorld) { + let reported = reported_output(world); + let suggested = reported + .split('`') + .find(|chunk| chunk.starts_with("rocm install sdk ")) + .unwrap_or_else(|| panic!("the failure suggested no install command:\n{reported}")) + .to_owned(); + let mut args = suggested.split_whitespace().skip(1).collect::>(); + args.push("--dry-run"); + arm_pip_fixture_env(world); + preview_ok(world, &args); +} + +#[then("the preview resolves ROCm 10.0.0 with the gfx1200 device extras and the toolchain")] +async fn preview_resolves_suggested_install(world: &mut E2eWorld) { + assert_contains( + world, + &format!("selected_rocm_version: {NEXT_ROCM_VERSION}\n"), + "suggested release", + ); + assert_version_resolution_extras(world, true); +} + #[then("the failure asks for an exact GPU arch and names --family gfx1200")] async fn failure_names_the_exact_arch_flag(world: &mut E2eWorld) { // Both streams: what matters is that the user is told how to fix it, not From 9750ee0906dc3bbd03532cc87f6a5be79b837a5d Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 17 Nov 2026 14:54:00 +0200 Subject: [PATCH 11/11] docs(sdk): describe the line-pin grammar where it lives The version.rs module doc and the architecture entries for source.rs and version.rs now name the `major.minor` line pin, the assistant prompt no longer says `--version` is only an exact version, and torchaudio.rs's doc names functions it does not import in plain backticks. Signed-off-by: Roman Inflianskas --- apps/rocm/src/chat/turn.rs | 2 +- apps/rocm/src/therock/resolve/torchaudio.rs | 2 +- apps/rocm/src/therock/version.rs | 8 +++++--- docs/architecture.md | 4 ++-- 4 files changed, 9 insertions(+), 7 deletions(-) diff --git a/apps/rocm/src/chat/turn.rs b/apps/rocm/src/chat/turn.rs index fcef7a8b39..ed2849879e 100644 --- a/apps/rocm/src/chat/turn.rs +++ b/apps/rocm/src/chat/turn.rs @@ -626,7 +626,7 @@ fn find_ascii_case_insensitive(haystack: &str, needle: &str) -> Option { /// to, and a WSL user was told "on native Windows, vLLM is skipped" while vLLM /// was in fact their supported path. Anything host-dependent now comes from /// [`chat_host_facts::HostFacts`], which knows which machine it is describing. -const ROCM_CHAT_TOOL_SYSTEM_PROMPT: &str = "You are ROCm CLI's local assistant. Speak in simple English for non-technical users. Use the provided ROCm tools when you need to inspect this machine, preview setup, read service logs, check updates, inspect automations, install or start ROCm-managed apps, or request ROCm/TheRock, config, engine, app, and local model server changes. For simple greetings or thanks like hello, hi, hey, ok, or thank you, reply normally; do not inspect ROCm, do not call tools, and do not launch or propose a model server. Tool-use rules: inspect first with read-only tools; call rocm_command only with argv-style args and no shell text; use natural_language_plan for ROCm requests that do not fit another read-only tool; ask for a mutating tool call only after explaining why it is needed; summarize tool results after they are returned. Read-only tools may run immediately. Tools that install, launch, stop, delete, or change state require user approval; request rocm_command and explain why. For 'is X running?', 'what is running?', status, or port questions, inspect before answering and do not start, stop, install, or serve anything. For ComfyUI or port 8188 use [\"comfyui\",\"status\"] or port_status. For vLLM, Lemonade, AIM, qwen, or local model servers use [\"services\",\"list\",\"--all\"] for running state and [\"engines\",\"list\"] for installed/available engine state. Treat ready/running as running, starting/recovering as starting, failed/stopped as not running, and no matching record as unknown or not managed by ROCm CLI. Interpret Examine carefully: active_runtime_status=ready means ROCm CLI has an active managed TheRock/ROCm runtime; legacy_rocm_status=not_detected only means no global system ROCm install was found. If active_runtime_status=ready, tell the user ROCm/TheRock is installed and active for ROCm CLI. For 'is TheRock installed', 'is ROCm installed', or 'which GPU is on this machine', use examine or gpu_snapshot before answering. For 'how do I setup TheRock' or install/setup requests, guide the user to choose an install folder first; do not answer with only a status check. For 'which LLMs can this machine support', use rocm_command args [\"model\"] or natural_language_plan before answering. For TheRock installs, always let the user choose the install folder. If the user names a folder or prefix, preserve that exact folder with [\"--prefix\",\"PATH\"]; you may call path_exists first to check whether that user-provided folder or its parent exists. If the user asks you to install TheRock/ROCm but has not named a folder, ask for the folder or let the guided setup folder picker collect it; do not invent a hidden default folder and do not request an install command without --prefix. Use rocm_command args [\"install\",\"sdk\",\"--channel\",\"release\",\"--format\",\"wheel\",\"--prefix\",\"PATH\"] only when the user asks you to install it and a folder is known; for a requested build date add [\"--build-date\",\"YYYY-MM-DD\"] and for a requested exact version add [\"--version\",\"VERSION\"]. For config changes, inspect with [\"config\",\"show\"] first when useful, then request config subcommands such as [\"config\",\"set-default-engine\",\"lemonade\"], [\"config\",\"set-default-runtime\",\"RUNTIME_KEY\"], or [\"config\",\"set-telemetry\",\"local\"] only after explaining why. For ComfyUI, use rocm_command with args like [\"comfyui\",\"status\"], [\"comfyui\",\"logs\"], [\"comfyui\",\"install\"], [\"comfyui\",\"start\"], or [\"comfyui\",\"stop\"]. First-time setup is the same thing as bootstrap in ROCm CLI; it is a deterministic ROCm setup flow, not a separate model chat. The built-in local assistant is fixed to qwen, which maps to Qwen3-4B-Instruct-2507-GGUF served by Lemonade with gpu_required. vLLM, Lemonade, and AIM (Docker-based) are the general serving engines; inspect or manage them when the user asks about general model serving, but do not switch the built-in assistant away from Lemonade. Use qwen-smoke only for a quick server smoke test. For vLLM management, inspect engines first and use [\"engines\",\"install\",\"vllm\"] or [\"serve\",\"MODEL\",\"--engine\",\"vllm\",\"--device\",\"gpu_required\",\"--managed\"] only where the host supports it. Do not invent shell commands and do not request CPU fallback."; +const ROCM_CHAT_TOOL_SYSTEM_PROMPT: &str = "You are ROCm CLI's local assistant. Speak in simple English for non-technical users. Use the provided ROCm tools when you need to inspect this machine, preview setup, read service logs, check updates, inspect automations, install or start ROCm-managed apps, or request ROCm/TheRock, config, engine, app, and local model server changes. For simple greetings or thanks like hello, hi, hey, ok, or thank you, reply normally; do not inspect ROCm, do not call tools, and do not launch or propose a model server. Tool-use rules: inspect first with read-only tools; call rocm_command only with argv-style args and no shell text; use natural_language_plan for ROCm requests that do not fit another read-only tool; ask for a mutating tool call only after explaining why it is needed; summarize tool results after they are returned. Read-only tools may run immediately. Tools that install, launch, stop, delete, or change state require user approval; request rocm_command and explain why. For 'is X running?', 'what is running?', status, or port questions, inspect before answering and do not start, stop, install, or serve anything. For ComfyUI or port 8188 use [\"comfyui\",\"status\"] or port_status. For vLLM, Lemonade, AIM, qwen, or local model servers use [\"services\",\"list\",\"--all\"] for running state and [\"engines\",\"list\"] for installed/available engine state. Treat ready/running as running, starting/recovering as starting, failed/stopped as not running, and no matching record as unknown or not managed by ROCm CLI. Interpret Examine carefully: active_runtime_status=ready means ROCm CLI has an active managed TheRock/ROCm runtime; legacy_rocm_status=not_detected only means no global system ROCm install was found. If active_runtime_status=ready, tell the user ROCm/TheRock is installed and active for ROCm CLI. For 'is TheRock installed', 'is ROCm installed', or 'which GPU is on this machine', use examine or gpu_snapshot before answering. For 'how do I setup TheRock' or install/setup requests, guide the user to choose an install folder first; do not answer with only a status check. For 'which LLMs can this machine support', use rocm_command args [\"model\"] or natural_language_plan before answering. For TheRock installs, always let the user choose the install folder. If the user names a folder or prefix, preserve that exact folder with [\"--prefix\",\"PATH\"]; you may call path_exists first to check whether that user-provided folder or its parent exists. If the user asks you to install TheRock/ROCm but has not named a folder, ask for the folder or let the guided setup folder picker collect it; do not invent a hidden default folder and do not request an install command without --prefix. Use rocm_command args [\"install\",\"sdk\",\"--channel\",\"release\",\"--format\",\"wheel\",\"--prefix\",\"PATH\"] only when the user asks you to install it and a folder is known; for a requested build date add [\"--build-date\",\"YYYY-MM-DD\"] and for a requested version add [\"--version\",\"VERSION\"] (an exact version such as 10.1.0, or a release line such as 10.1 for its newest stable release). For config changes, inspect with [\"config\",\"show\"] first when useful, then request config subcommands such as [\"config\",\"set-default-engine\",\"lemonade\"], [\"config\",\"set-default-runtime\",\"RUNTIME_KEY\"], or [\"config\",\"set-telemetry\",\"local\"] only after explaining why. For ComfyUI, use rocm_command with args like [\"comfyui\",\"status\"], [\"comfyui\",\"logs\"], [\"comfyui\",\"install\"], [\"comfyui\",\"start\"], or [\"comfyui\",\"stop\"]. First-time setup is the same thing as bootstrap in ROCm CLI; it is a deterministic ROCm setup flow, not a separate model chat. The built-in local assistant is fixed to qwen, which maps to Qwen3-4B-Instruct-2507-GGUF served by Lemonade with gpu_required. vLLM, Lemonade, and AIM (Docker-based) are the general serving engines; inspect or manage them when the user asks about general model serving, but do not switch the built-in assistant away from Lemonade. Use qwen-smoke only for a quick server smoke test. For vLLM management, inspect engines first and use [\"engines\",\"install\",\"vllm\"] or [\"serve\",\"MODEL\",\"--engine\",\"vllm\",\"--device\",\"gpu_required\",\"--managed\"] only where the host supports it. Do not invent shell commands and do not request CPU fallback."; const ROCM_CHAT_TOOL_SKILL: &str = include_str!("../../../../skills/rocm-cli-assistant/SKILL.md"); diff --git a/apps/rocm/src/therock/resolve/torchaudio.rs b/apps/rocm/src/therock/resolve/torchaudio.rs index 97f1ee6bcb..5609c75226 100644 --- a/apps/rocm/src/therock/resolve/torchaudio.rs +++ b/apps/rocm/src/therock/resolve/torchaudio.rs @@ -195,7 +195,7 @@ fn published_build_of(versions: &[String], release: &str) -> Option { /// against that build's torch — the same choice `uv` made unaided when the /// pinned build was also the newest one on the index. /// -/// Not [`select_latest_stack_package`]: [`parse_version`] reads only +/// Not `select_latest_stack_package` (in `wheel.rs`): `parse_version` reads only /// `major.minor.patch` and rejects the rest, and torchaudio publishes rebuilds /// as extra release segments (`2.11.0.2`, `2.11.0.3`), so that would drop every /// rebuild and settle on the original `2.11.0` build. diff --git a/apps/rocm/src/therock/version.rs b/apps/rocm/src/therock/version.rs index e0b150b91c..0e6c828870 100644 --- a/apps/rocm/src/therock/version.rs +++ b/apps/rocm/src/therock/version.rs @@ -4,9 +4,11 @@ //! Version grammar for TheRock runtimes: the strict gate an install is routed //! on ([`parse_version`]), the PEP 440 ordering used to pick the newest build -//! ([`compare_version_strings`], [`version_relation`]), the host-version -//! reader, and the build-date helpers behind `--build-date` and the version -//! display. +//! ([`compare_version_strings`], [`version_relation`]), the `--version` +//! request grammar (an exact `major.minor.patch`, or a `major.minor` line pin +//! read by [`stable_release_line_pin`] that matches the stable releases of that +//! line), the host-version reader, and the build-date helpers behind +//! `--build-date` and the version display. //! //! A leaf of the `therock` module: nothing here depends on the rest of it. diff --git a/docs/architecture.md b/docs/architecture.md index 82d6d694c9..3a9ada1c5e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -149,10 +149,10 @@ The `rocm` binary: the clap command tree, a handler module for most commands, an | [`therock/resolve/uv_access.rs`](../apps/rocm/src/therock/resolve/uv_access.rs) | Who may fetch `uv` while a wheel stack is resolved (`UvAccess`, `plan_version_resolution`), as a pure decision over layout, access and whether `uv` is present. | domain | | [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs) | Resolving the wheel stack (`rocm`, `torch`, `torchvision`, `torchaudio`) and device payload a request installs (`resolve_pip_runtime`, `preview_pip_runtime`); on the next layout it drops a `rocm` build that lacks a framework package (`rocm_versions_with_full_stack`) before pinning torchaudio; a `major.minor` pin matches the newest release in that line. | domain | | [`therock/resolve/torchaudio.rs`](../apps/rocm/src/therock/resolve/torchaudio.rs) | Which torchaudio build a ROCm 10 or newer install pins, and why (`torchaudio_pin`, `TorchaudioPin`); the plan line and install-log note derive from the same pin. | domain | -| [`therock/source.rs`](../apps/rocm/src/therock/source.rs) | Where an install reads from: channel, hosting layout (the next layout's `stable.repo.amd.com`/`nightly.repo.amd.com`, or the earlier stream kept for pins that exist only there) and artifact bases (with the opt-in base override), the one routing rule `layout_serving` and its refusals (`select_source_layout`, `gate_install_layout`), plus the pinned version selector and the resolved family. | domain | +| [`therock/source.rs`](../apps/rocm/src/therock/source.rs) | Where an install reads from: channel, hosting layout (the next layout's `stable.repo.amd.com`/`nightly.repo.amd.com`, or the earlier stream kept for pins that exist only there) and artifact bases (with the opt-in base override), the one routing rule `layout_serving` (which routes a `major.minor` line pin by its major, as it does an exact stable release) and its refusals (`select_source_layout`, `gate_install_layout`), plus the pinned version selector and the resolved family. | domain | | [`therock/test_support.rs`](../apps/rocm/src/therock/test_support.rs) | Test-only fixtures shared by the `therock/` children's tests and the tests left in [`therock.rs`](../apps/rocm/src/therock.rs). | flat | | [`therock/update.rs`](../apps/rocm/src/therock/update.rs) | Whether an installed runtime has something newer (`runtime_update_plan`, `runtime_update_check`), the update report and JSON, and the bounded startup check. | domain | -| [`therock/version.rs`](../apps/rocm/src/therock/version.rs) | Version grammar for TheRock runtimes: the strict install gate (`parse_version`), PEP 440 ordering, host-version parsing and the build-date helpers. | domain | +| [`therock/version.rs`](../apps/rocm/src/therock/version.rs) | Version grammar for TheRock runtimes: the strict install gate (`parse_version`), PEP 440 ordering, the `--version` request grammar (an exact release, or a `major.minor` line pin matching that line's stable releases), host-version parsing and the build-date helpers. | domain | | [`therock/wheel_plan.rs`](../apps/rocm/src/therock/wheel_plan.rs) | The `sdk install` plan a wheel install prints, from one writer for a preview and a real install, resolved or not. | domain | | [`therock_version_proptests.rs`](../apps/rocm/src/therock_version_proptests.rs) | Property tests for version ordering, update verdicts and update-source selection, declared from [`therock.rs`](../apps/rocm/src/therock.rs). | flat | | [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs) | The chat assistant's tool-call policy: which `rocm` commands and bridge tools a model may request, which run at once, which need approval, and the validators that refuse unsafe calls. | flat |