diff --git a/README.md b/README.md index 0f2ea1d78..f5ffc7b4e 100644 --- a/README.md +++ b/README.md @@ -871,12 +871,30 @@ rocm runtimes adopt --python [--root ] [--runtime-id ID] [--runtime-key KEY] [--channel LABEL] [--replace] ``` -`list` shows each runtime's version, GPU family, mode, and whether it carries -the compiler toolchain (`toolchain=included|excluded`). Runtimes are told apart -by the packages they were installed from, not by version alone, so one version -can appear more than once: a `--devel` install and a plain one of the same -version are two separate runtimes, as are two installs that resolved different -GPU device payloads. +`list` shows each runtime's version (with its build date when the version +encodes one), GPU family, mode, and whether it carries the compiler toolchain +(`toolchain=included|excluded`). A `provenance:` line under each runtime names +where it came from: its `channel`, the package `source` it was installed from +(the wheel index, or the downloaded archive for a tarball install), its +`source_layout_generation`, and the exact `device_target` its packages were +installed for. The values are the ones the runtime's manifest recorded: the +package index, else the artifact URL; the layout field, else the wheel +composition's; the recorded target, else the `device-` extra in the +package specs. For the layout and target that is the same recorded field +`rocm update` uses; the listing then trims the value and prints a blank one as +`unrecorded`, as it does a fact recorded nowhere. Nothing is guessed from other +facts (the target is never the family) — so a tarball or family-wide install +shows `device_target=unrecorded`, and an adopted runtime, which installed +nothing, shows `source=unrecorded`. An adopted runtime's channel is the one adoption +recorded: the channel `--channel` or `--runtime-id` named, `release` when neither +names one. +`rocm examine` reports the same four facts for the active runtime as +`active_runtime_channel`, `active_runtime_source`, +`active_runtime_source_layout_generation` and `active_runtime_device_target`. +Runtimes are told apart by the packages they were installed from, not by +version alone, so one version can appear more than once: a `--devel` install +and a plain one of the same version are two separate runtimes, as are two +installs that resolved different GPU device payloads. `activate` and `rollback` change which runtime the next install or server picks up. A server that is already running is not moved: it keeps serving on diff --git a/apps/rocm/src/cli.rs b/apps/rocm/src/cli.rs index 9130f148d..734cfb00f 100644 --- a/apps/rocm/src/cli.rs +++ b/apps/rocm/src/cli.rs @@ -984,6 +984,12 @@ rocm engines install vllm --reinstall")] #[derive(Subcommand, Debug)] pub(crate) enum RuntimesCommand { /// Show ROCm runtimes known to ROCm CLI. + /// + /// Each runtime is listed with its version (and build date), GPU family, + /// mode and toolchain, then its channel, package source, source layout + /// generation and exact GPU target as its manifest recorded them. A fact + /// recorded nowhere, or recorded blank, is shown as `unrecorded`; nothing + /// is guessed from other facts. List, /// Use the selected ROCm runtime by default. Activate { diff --git a/apps/rocm/src/examine_report_text.rs b/apps/rocm/src/examine_report_text.rs index 1dd991f22..5045c384e 100644 --- a/apps/rocm/src/examine_report_text.rs +++ b/apps/rocm/src/examine_report_text.rs @@ -326,6 +326,12 @@ pub(crate) fn append_examine_runtime_state( "managed" }; let _ = writeln!(output, " active_runtime_mode: {mode}"); + // Where the active runtime came from, from the same fields and in the + // same words as the `provenance:` line `rocm runtimes list` prints for + // it, so the two commands cannot describe one runtime differently. + for (name, value) in manifest.provenance().fields() { + let _ = writeln!(output, " active_runtime_{name}: {value}"); + } } if let Some((setup_root, pip_cache_dir)) = setup_runtime_paths(config) { let _ = writeln!(output, " setup_runtime_root: {}", setup_root.display()); diff --git a/apps/rocm/src/runtime_adopt.rs b/apps/rocm/src/runtime_adopt.rs index 18e594f44..d142bfc0a 100644 --- a/apps/rocm/src/runtime_adopt.rs +++ b/apps/rocm/src/runtime_adopt.rs @@ -29,9 +29,9 @@ use rocm_core::{ }; use crate::runtime_registry::{ - ManifestOverwrite, paths_equivalent, runtime_manifest_path, runtime_registry_dir, - sort_manifests_newest_install_first, validate_runtime_manifest_for_activation, - write_runtime_manifest, + ADOPTED_RUNTIME_ARTIFACT_URL, ManifestOverwrite, paths_equivalent, runtime_manifest_path, + runtime_registry_dir, sort_manifests_newest_install_first, + validate_runtime_manifest_for_activation, write_runtime_manifest, }; use crate::therock; @@ -298,7 +298,7 @@ pub(crate) fn adopt_runtime_from_probe( family_source: "runtime_id".to_owned(), version, install_root: install_root.clone(), - selected_artifact_url: "adopted-read-only".to_owned(), + selected_artifact_url: ADOPTED_RUNTIME_ARTIFACT_URL.to_owned(), source_layout_generation: None, index_url: None, tarball_file_name: None, @@ -644,12 +644,36 @@ mod tests { Ok(()) } - /// The other half of the same derivation: an adopted environment that does - /// expose a CMake path has the toolchain, and the manifest must say so or - /// the next `rocm update` would quietly reinstall without it. - #[test] - fn runtime_adopt_records_devel_when_the_probe_finds_cmake() -> Result<()> { - let (root, paths) = test_paths("runtime-adopt-devel"); + /// Adopts a fake external TheRock venv under `root` whose probe reports a + /// CMake path, through the same `adopt_runtime_from_probe` that + /// `rocm runtimes adopt` runs, and returns the manifest it registered. + fn adopt_test_runtime( + root: &Path, + paths: &AppPaths, + ) -> Result { + adopt_test_runtime_with(root, paths, TestAdoptRequest::HandBuilt) + } + + /// How [`adopt_test_runtime_with`] builds its adoption request. + enum TestAdoptRequest { + /// A request with the runtime id and key spelled out. + HandBuilt, + /// The request `rocm runtimes adopt` builds, through + /// [`infer_adopt_runtime_request`]; `runtime_id` is `--runtime-id` and + /// `channel` is `--channel`. + Inferred { + runtime_id: Option<&'static str>, + channel: Option<&'static str>, + }, + } + + /// Adopts a fake external environment, building the request as `request` + /// says. + fn adopt_test_runtime_with( + root: &Path, + paths: &AppPaths, + request: TestAdoptRequest, + ) -> Result { let external_root = root.join("external-therock-venv"); let scripts_dir = external_root.join(if cfg!(windows) { "Scripts" } else { "bin" }); let python_executable = scripts_dir.join(if cfg!(windows) { @@ -680,38 +704,59 @@ mod tests { fs::write(&amdhip, "amdhip")?; fs::write(&hipblas, "hipblas")?; - let adopted = adopt_runtime_from_probe( - &paths, - AdoptRuntimeRequest { + let probe = therock::RocmSdkPythonProbe { + import_ok: true, + rocm_sdk_version: Some("7.13.0".to_owned()), + root_path: Some(sdk_root.clone()), + bin_path: Some(sdk_bin.clone()), + cmake_path: Some(cmake_path), + runtime_roots: vec![sdk_root], + bin_paths: vec![sdk_bin.clone()], + library_paths: vec![sdk_bin], + resolved_libraries: vec![ + therock::RocmSdkLibraryProbe { + shortname: "amdhip64".to_owned(), + paths: vec![amdhip], + }, + therock::RocmSdkLibraryProbe { + shortname: "hipblas".to_owned(), + paths: vec![hipblas], + }, + ], + resolved_target_family: Some("gfx120X-all".to_owned()), + ..therock::RocmSdkPythonProbe::default() + }; + let request = match request { + TestAdoptRequest::HandBuilt => AdoptRuntimeRequest { python_executable, install_root: external_root, runtime_id: "therock-release:gfx120X-all".to_owned(), runtime_key: "adopted-release-pip-gfx120x-all-7-13-0".to_owned(), replace: false, }, - therock::RocmSdkPythonProbe { - import_ok: true, - rocm_sdk_version: Some("7.13.0".to_owned()), - root_path: Some(sdk_root.clone()), - bin_path: Some(sdk_bin.clone()), - cmake_path: Some(cmake_path), - runtime_roots: vec![sdk_root], - bin_paths: vec![sdk_bin.clone()], - library_paths: vec![sdk_bin], - resolved_libraries: vec![ - therock::RocmSdkLibraryProbe { - shortname: "amdhip64".to_owned(), - paths: vec![amdhip], - }, - therock::RocmSdkLibraryProbe { - shortname: "hipblas".to_owned(), - paths: vec![hipblas], - }, - ], - resolved_target_family: Some("gfx120X-all".to_owned()), - ..therock::RocmSdkPythonProbe::default() - }, - )?; + TestAdoptRequest::Inferred { + runtime_id, + channel, + } => infer_adopt_runtime_request( + python_executable, + Some(external_root), + runtime_id.map(str::to_owned), + None, + channel.map(str::to_owned), + false, + &probe, + )?, + }; + adopt_runtime_from_probe(paths, request, probe) + } + + /// The other half of the same derivation: an adopted environment that does + /// expose a CMake path has the toolchain, and the manifest must say so or + /// the next `rocm update` would quietly reinstall without it. + #[test] + fn runtime_adopt_records_devel_when_the_probe_finds_cmake() -> Result<()> { + let (root, paths) = test_paths("runtime-adopt-devel"); + let adopted = adopt_test_runtime(&root, &paths)?; assert!( adopted.devel, @@ -722,6 +767,49 @@ mod tests { Ok(()) } + /// Adoption installs nothing, so there is no package source to name: the + /// manifest's artifact URL holds only the adoption marker. The listing must + /// say the source was not recorded rather than present that marker as one. + /// The channel is the one adoption recorded, for each way the request + /// `rocm runtimes adopt` builds can name it: adoption's default, `release`, + /// when neither `--channel` nor `--runtime-id` names one; `nightly` after + /// `--channel nightly`; and `nightly` after `--runtime-id + /// therock-nightly:` with no `--channel`, where the channel comes + /// from the runtime id alone. The family is the one the test probe reports. + #[test] + fn adopted_runtime_lists_its_channel_and_its_source_as_unrecorded() -> Result<()> { + for (runtime_id_flag, channel_flag, expected_channel) in [ + (None, None, "release"), + (None, Some("nightly"), "nightly"), + (Some("therock-nightly:gfx120X-all"), None, "nightly"), + ] { + let flags = format!("--runtime-id {runtime_id_flag:?} --channel {channel_flag:?}"); + let (root, paths) = test_paths("runtime-adopt-provenance"); + let adopted = adopt_test_runtime_with( + &root, + &paths, + TestAdoptRequest::Inferred { + runtime_id: runtime_id_flag, + channel: channel_flag, + }, + )?; + let rendered = + crate::runtimes_cmd::render_runtimes_text(&paths, &RocmCliConfig::default())?; + let _ = fs::remove_dir_all(root); + + assert_eq!(adopted.channel, expected_channel, "{flags}"); + assert_eq!( + crate::runtimes_cmd::tests::provenance_line(&rendered, &adopted.runtime_key), + format!( + " provenance: channel={expected_channel} source=unrecorded \ + source_layout_generation=unrecorded device_target=unrecorded" + ), + "{flags}:\n{rendered}" + ); + } + Ok(()) + } + #[test] fn runtime_adopt_request_infers_ids_from_probe() -> Result<()> { let (root, _) = test_paths("runtime-adopt-infer"); diff --git a/apps/rocm/src/runtime_registry.rs b/apps/rocm/src/runtime_registry.rs index e8b24ae67..a939b86b8 100644 --- a/apps/rocm/src/runtime_registry.rs +++ b/apps/rocm/src/runtime_registry.rs @@ -112,6 +112,18 @@ const fn devel_default_for_legacy_manifest() -> bool { true } +/// The `selected_artifact_url` an adopted runtime records (`rocm runtimes +/// adopt`). Adoption installs nothing, so there is no artifact to name; this +/// marks that instead, and is never a package source. +pub(crate) const ADOPTED_RUNTIME_ARTIFACT_URL: &str = "adopted-read-only"; + +/// The value a provenance chain chose, trimmed, or `None` when there is none or +/// it is blank. Applied once, after the chain has picked its field: a blank +/// value is shown as `unrecorded`, it does not make the chain try the next one. +fn recorded(value: Option<&str>) -> Option<&str> { + value.map(str::trim).filter(|value| !value.is_empty()) +} + impl InstalledRuntimeManifest { /// Whether this runtime has the compiler toolchain. /// @@ -134,6 +146,49 @@ impl InstalledRuntimeManifest { !self.read_only && self.imported_from.is_none() } + /// The source layout generation this runtime recorded: the manifest's own + /// field, else the one its wheel composition was written with. `None` when + /// neither is recorded. + /// + /// Shared by update planning (which treats `None` as the canonical stream) + /// and by [`Self::provenance`], so both choose the same recorded field. + /// They differ in what they do with its value: update planning uses it + /// as recorded, while the listing trims it and prints a blank one (or + /// `None`) as `unrecorded`. + pub(crate) fn recorded_source_layout_generation(&self) -> Option<&str> { + self.source_layout_generation.as_deref().or_else(|| { + self.wheel_composition + .as_ref() + .map(|composition| composition.source_layout_generation.as_str()) + }) + } + + /// Where this runtime came from, as far as its manifest recorded it. + /// + /// The layout and target come from the same recorded field update planning + /// uses, through [`Self::recorded_source_layout_generation`] and + /// [`wheel_composition_device_target`]; the source is the package index, + /// else the artifact URL unless it is the adoption marker. Each chain moves + /// to its next field only when a field is absent. The chosen value then + /// goes through [`recorded`], which trims it and turns a blank one into + /// `None` (shown as `unrecorded`) rather than skipping it. + pub(crate) fn provenance(&self) -> RuntimeProvenance<'_> { + RuntimeProvenance { + channel: recorded(Some(self.channel.as_str())), + // A wheel install records the package index it resolved from; a + // tarball install records only the archive it downloaded. An + // adopted runtime records neither, only the adoption marker. + source: recorded(self.index_url.as_deref().or_else(|| { + Some(self.selected_artifact_url.as_str()) + .filter(|url| *url != ADOPTED_RUNTIME_ARTIFACT_URL) + })), + source_layout_generation: recorded(self.recorded_source_layout_generation()), + device_target: recorded(wheel_composition_device_target( + self.wheel_composition.as_ref(), + )), + } + } + pub(crate) fn normalize_host_paths(mut self) -> Self { self.install_root = normalize_manifest_path(self.install_root); self.python_launcher = self @@ -173,6 +228,50 @@ impl InstalledRuntimeManifest { } } +/// Printed in place of a provenance fact the runtime's manifest does not record. +/// +/// Older manifests predate some of these fields, and a tarball install never +/// had an exact GPU target. [`RuntimeProvenance::fields`] shows this for a fact +/// [`InstalledRuntimeManifest::provenance`] left `None`: its chain of recorded +/// fields found nothing, or found a blank value. Neither ever guesses one fact +/// from another — a target from the family, or a layout from the channel, +/// would read as something the install recorded. +pub(crate) const UNRECORDED_PROVENANCE: &str = "unrecorded"; + +/// Where an installed runtime came from: the channel, the package source it was +/// resolved from, the source layout generation, and the exact GPU target its +/// packages were installed for. Every field is what the manifest recorded, +/// trimmed, and `None` when it recorded nothing or a blank value. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) struct RuntimeProvenance<'a> { + pub channel: Option<&'a str>, + pub source: Option<&'a str>, + pub source_layout_generation: Option<&'a str>, + pub device_target: Option<&'a str>, +} + +impl RuntimeProvenance<'_> { + /// Each fact as `(name, shown value)`, in display order, with + /// [`UNRECORDED_PROVENANCE`] for a fact that was not recorded. + /// + /// `rocm runtimes list` and `rocm examine` both print from this, so the + /// names and values the two show for one runtime cannot drift apart. + pub(crate) fn fields(&self) -> [(&'static str, &str); 4] { + fn shown(value: Option<&str>) -> &str { + value.unwrap_or(UNRECORDED_PROVENANCE) + } + [ + ("channel", shown(self.channel)), + ("source", shown(self.source)), + ( + "source_layout_generation", + shown(self.source_layout_generation), + ), + ("device_target", shown(self.device_target)), + ] + } +} + #[derive(Debug, Clone, Default, Serialize, Deserialize)] pub(crate) struct RocmSdkPythonProbe { #[serde(default)] @@ -907,6 +1006,20 @@ mod tests { } } + /// The adoption marker is persisted manifest format: every runtime adopted + /// so far holds this exact string in its `selected_artifact_url` on disk, + /// and the listing recognises it by comparison. Changing the value without + /// a migration would make those runtimes list the marker as their package + /// source. In-crate code — the producer, the reader and the other unit + /// tests — uses the constant, so it cannot notice the value changing. Two + /// checks pin the on-disk literal instead: this test, and scenario + /// `runtime-lifecycle-22`, whose `plant_adopted_runtime` step writes the + /// literal into a manifest and expects it listed as `source=unrecorded`. + #[test] + fn adoption_marker_keeps_its_persisted_value() { + assert_eq!(ADOPTED_RUNTIME_ARTIFACT_URL, "adopted-read-only"); + } + /// A manifest from before compositions were recorded has only the field, /// and one older still has neither — those installs all had the toolchain. #[test] diff --git a/apps/rocm/src/runtimes_cmd.rs b/apps/rocm/src/runtimes_cmd.rs index e098ad5a2..e0b3b4589 100644 --- a/apps/rocm/src/runtimes_cmd.rs +++ b/apps/rocm/src/runtimes_cmd.rs @@ -55,13 +55,13 @@ use crate::runtime_adopt::{ pub(crate) use crate::runtime_adopt::{ newest_installed_runtime_manifest, recover_setup_runtime_registration, setup_runtime_paths, }; -use crate::runtime_registry::write_active_runtime_marker; pub(crate) use crate::runtime_registry::{ ActiveRuntimeMarker, active_runtime_marker_path, current_runtime_manifest, default_runtime_id_matches, normalize_path_for_compare, runtime_keys_text, runtime_manifest_path, runtime_registry_dir, runtime_usability_status, select_runtime_manifest, validate_runtime_manifest_for_activation, }; +use crate::runtime_registry::{RuntimeProvenance, write_active_runtime_marker}; pub(crate) use crate::runtime_uninstall::{ InstallRootDecision, lemonade_record_report_line, should_remove_runtime_install_root, uninstall_runtime, @@ -720,6 +720,11 @@ pub(crate) fn render_runtimes_text(paths: &AppPaths, config: &RocmCliConfig) -> " install_root: {}", manifest.install_root.display() ); + let _ = writeln!( + output, + " provenance: {}", + provenance_text(&manifest.provenance()) + ); } Ok(output) @@ -869,6 +874,18 @@ fn rollback_runtime( }) } +/// A runtime's provenance as the `name=value` pairs `rocm runtimes list` prints +/// on its `provenance:` line. `rocm examine` prints the same pairs for the +/// active runtime as `active_runtime_:` lines. +fn provenance_text(provenance: &RuntimeProvenance<'_>) -> String { + provenance + .fields() + .iter() + .map(|(name, value)| format!("{name}={value}")) + .collect::>() + .join(" ") +} + /// How the CLI names the toolchain state of a runtime. /// /// `rocm runtimes list` reports it per runtime and `rocm examine` reports it @@ -1182,6 +1199,436 @@ pub(crate) mod tests { Ok(()) } + /// The row a runtime's `provenance:` line belongs to, found by its key: the + /// first `provenance:` line after that runtime's marked row. + pub(crate) fn provenance_line<'a>(rendered: &'a str, runtime_key: &str) -> &'a str { + let row = format!(" {runtime_key} runtime_id="); + rendered + .lines() + .skip_while(|line| !line.contains(&row)) + .skip(1) + .find(|line| line.trim_start().starts_with("provenance:")) + .unwrap_or_else(|| panic!("no provenance line for {runtime_key}:\n{rendered}")) + } + + /// A nightly ROCm 10 wheel runtime installed for one exact GPU, with every + /// provenance fact recorded the way `rocm install sdk` records it. The + /// family is the family-wide `gfx120X-all`, so a target inferred from the + /// family instead of read from the install shows up as a wrong value. + fn nightly_exact_target_manifest( + base: therock::InstalledRuntimeManifest, + ) -> therock::InstalledRuntimeManifest { + therock::InstalledRuntimeManifest { + runtime_key: "nightly-wheel-gfx1201-10-1-0a20260822".to_owned(), + runtime_id: "therock-nightly:gfx120X-all".to_owned(), + channel: "nightly".to_owned(), + family: "gfx120X-all".to_owned(), + version: "10.1.0a20260822".to_owned(), + selected_artifact_url: "https://example.invalid/whl-multi-arch".to_owned(), + index_url: Some("https://example.invalid/whl-multi-arch".to_owned()), + source_layout_generation: Some("next-v1".to_owned()), + wheel_composition: Some(therock::WheelRuntimeComposition { + source_layout_generation: "next-v1".to_owned(), + package_specs: vec!["rocm[libraries,device-gfx1201]==10.1.0a20260822".to_owned()], + rocm_sdk_target: Some("gfx1201".to_owned()), + }), + ..base + } + } + + fn rewrite_manifest( + paths: &AppPaths, + manifest: &therock::InstalledRuntimeManifest, + ) -> Result<()> { + fs::write( + runtime_manifest_path(paths, &manifest.runtime_key), + serde_json::to_vec_pretty(manifest)?, + )?; + Ok(()) + } + + /// The install report names the channel, source, layout and exact GPU + /// target; afterwards the only record of them is the manifest, so the + /// listing is where a user finds out which stream and which GPU a runtime + /// is for. Each value is asserted exactly, so a field printed from the + /// wrong source (the family for the target, the channel for the layout) + /// fails here. + #[test] + fn runtime_list_names_where_each_runtime_came_from() -> Result<()> { + let (root, paths) = test_paths("runtime-list-provenance"); + let base = write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all-7-13-0", + "therock-release:gfx120X-all", + "7.13.0", + 10, + )?; + + // Written before the index, the layout and the composition were + // recorded: only the artifact URL every manifest carries is left. + let legacy = therock::InstalledRuntimeManifest { + index_url: None, + source_layout_generation: None, + wheel_composition: None, + ..base.clone() + }; + rewrite_manifest(&paths, &legacy)?; + + let nightly = nightly_exact_target_manifest(base.clone()); + write_test_pip_runtime( + &paths, + &nightly.runtime_key, + &nightly.runtime_id, + &nightly.version, + 20, + )?; + rewrite_manifest(&paths, &nightly)?; + + // A tarball install records the archive it downloaded and its layout; + // it was never installed for one exact GPU. + let tarball = therock::InstalledRuntimeManifest { + runtime_key: "release-tarball-gfx120x-all-7-13-0".to_owned(), + format: "tarball".to_owned(), + selected_artifact_url: + "https://example.invalid/tarball/therock-dist-linux-gfx120X-all-7.13.0.tar.gz" + .to_owned(), + index_url: None, + source_layout_generation: Some("multi-arch-v2".to_owned()), + wheel_composition: None, + ..base + }; + rewrite_manifest(&paths, &tarball)?; + + let rendered = render_runtimes_text(&paths, &RocmCliConfig::default())?; + let _ = fs::remove_dir_all(root); + + // `cargo xtask e2e` prewarm (`assess` in xtask/src/e2e_prewarm.rs) + // reads the line directly after a runtime's row as its + // `install_root:`, so the order row, `install_root:`, `provenance:` is + // pinned here by index; `provenance_line` searches ahead and would not + // notice a reorder. + let lines: Vec<&str> = rendered.lines().collect(); + let row = format!(" {} runtime_id=", nightly.runtime_key); + let row_index = lines + .iter() + .position(|line| line.contains(&row)) + .unwrap_or_else(|| panic!("no row for {}:\n{rendered}", nightly.runtime_key)); + assert_eq!( + lines.get(row_index + 1).copied(), + Some(format!(" install_root: {}", nightly.install_root.display()).as_str()), + "the line after the row must be its install_root:\n{rendered}" + ); + assert_eq!( + lines.get(row_index + 2).copied(), + Some(provenance_line(&rendered, &nightly.runtime_key)), + "the line after install_root: must be its provenance:\n{rendered}" + ); + + assert_eq!( + provenance_line(&rendered, &nightly.runtime_key), + " provenance: channel=nightly source=https://example.invalid/whl-multi-arch \ + source_layout_generation=next-v1 device_target=gfx1201", + "{rendered}" + ); + assert!( + rendered.contains("version=10.1.0a20260822 (build 2026-08-22)"), + "the nightly's version must show its build date:\n{rendered}" + ); + assert_eq!( + provenance_line(&rendered, &legacy.runtime_key), + " provenance: channel=release source=https://example.invalid/therock \ + source_layout_generation=unrecorded device_target=unrecorded", + "{rendered}" + ); + assert_eq!( + provenance_line(&rendered, &tarball.runtime_key), + " provenance: channel=release \ + source=https://example.invalid/tarball/therock-dist-linux-gfx120X-all-7.13.0.tar.gz \ + source_layout_generation=multi-arch-v2 device_target=unrecorded", + "{rendered}" + ); + Ok(()) + } + + /// The layout and target are read from the same recorded fields + /// `rocm update` reads; it does not read the recorded source. Each chain + /// moves to its next field only when a field is absent: package index, + /// else artifact URL (never the adoption marker); layout field, else the + /// wheel composition's layout; `rocm_sdk_target`, else the + /// `device-` package extra. The value chosen is printed trimmed, + /// and a fact recorded nowhere, or recorded blank, reads `unrecorded`. One + /// runtime per rule: + /// + /// - index and artifact URL both recorded and differing: the index wins; + /// - layout field and composition layout differing, and `rocm_sdk_target` + /// and package extra differing: the field earlier in each chain wins; + /// - layout only in the composition (manifests older than the field): it is + /// still the layout; + /// - target only as a package extra (manifests older than + /// `rocm_sdk_target`): it is still the target; + /// - an adopted runtime (marker, no index): source `unrecorded`; + /// - a blank index, layout field and `rocm_sdk_target` in front of a + /// recorded artifact URL, composition layout and package extra: each + /// reads `unrecorded`, since a blank value is not skipped; + /// - an empty `device-` extra and no `rocm_sdk_target`: `unrecorded`; + /// - values padded with whitespace: printed trimmed; + /// - every field blank: each fact `unrecorded`, never an empty `name=`. + /// + /// Blank or padded values are not what `rocm install sdk` writes; they can + /// come from a hand-edited manifest or one brought in with + /// `rocm runtimes import`. + #[test] + fn runtime_list_reads_each_provenance_fact_from_where_it_was_recorded() -> Result<()> { + let (root, paths) = test_paths("runtime-list-provenance-precedence"); + let base = write_test_pip_runtime( + &paths, + "release-pip-index-and-artifact", + "therock-release:gfx120X-all", + "7.13.0", + 10, + )?; + + let index_and_artifact = therock::InstalledRuntimeManifest { + index_url: Some("https://example.invalid/simple".to_owned()), + selected_artifact_url: "https://example.invalid/whl/rocm-7.13.0.tar.gz".to_owned(), + ..base.clone() + }; + rewrite_manifest(&paths, &index_and_artifact)?; + + let composition_layout = therock::InstalledRuntimeManifest { + runtime_key: "release-pip-composition-layout".to_owned(), + source_layout_generation: None, + wheel_composition: Some(therock::WheelRuntimeComposition { + source_layout_generation: "next-v1".to_owned(), + package_specs: vec!["rocm[libraries]==7.13.0".to_owned()], + rocm_sdk_target: None, + }), + ..base.clone() + }; + rewrite_manifest(&paths, &composition_layout)?; + + let spec_target = therock::InstalledRuntimeManifest { + runtime_key: "release-pip-spec-target".to_owned(), + wheel_composition: Some(therock::WheelRuntimeComposition { + source_layout_generation: "multi-arch-v2".to_owned(), + package_specs: vec!["rocm[libraries,device-gfx1201]==7.13.0".to_owned()], + rocm_sdk_target: None, + }), + ..base.clone() + }; + rewrite_manifest(&paths, &spec_target)?; + + let adopted = therock::InstalledRuntimeManifest { + runtime_key: "adopted-release-pip".to_owned(), + index_url: None, + selected_artifact_url: crate::runtime_registry::ADOPTED_RUNTIME_ARTIFACT_URL.to_owned(), + read_only: true, + ..base.clone() + }; + rewrite_manifest(&paths, &adopted)?; + + let blank_before_fallback = therock::InstalledRuntimeManifest { + runtime_key: "release-pip-blank-before-fallback".to_owned(), + index_url: Some(String::new()), + selected_artifact_url: "https://example.invalid/therock".to_owned(), + source_layout_generation: Some(String::new()), + wheel_composition: Some(therock::WheelRuntimeComposition { + source_layout_generation: "next-v1".to_owned(), + package_specs: vec!["rocm[libraries,device-gfx1201]==7.13.0".to_owned()], + rocm_sdk_target: Some(String::new()), + }), + ..base.clone() + }; + rewrite_manifest(&paths, &blank_before_fallback)?; + + let first_in_chain_wins = therock::InstalledRuntimeManifest { + runtime_key: "release-pip-first-in-chain-wins".to_owned(), + source_layout_generation: Some("multi-arch-v2".to_owned()), + wheel_composition: Some(therock::WheelRuntimeComposition { + source_layout_generation: "next-v1".to_owned(), + package_specs: vec!["rocm[libraries,device-gfx1201]==7.13.0".to_owned()], + rocm_sdk_target: Some("gfx1100".to_owned()), + }), + ..base.clone() + }; + rewrite_manifest(&paths, &first_in_chain_wins)?; + + let padded = therock::InstalledRuntimeManifest { + runtime_key: "release-pip-padded".to_owned(), + channel: " release ".to_owned(), + index_url: Some(" https://example.invalid/simple ".to_owned()), + source_layout_generation: Some(" multi-arch-v2 ".to_owned()), + wheel_composition: Some(therock::WheelRuntimeComposition { + source_layout_generation: "multi-arch-v2".to_owned(), + package_specs: vec!["rocm[libraries,device-gfx1201]==7.13.0".to_owned()], + rocm_sdk_target: Some(" gfx1201 ".to_owned()), + }), + ..base.clone() + }; + rewrite_manifest(&paths, &padded)?; + + let empty_device_extra = therock::InstalledRuntimeManifest { + runtime_key: "release-pip-empty-device-extra".to_owned(), + wheel_composition: Some(therock::WheelRuntimeComposition { + source_layout_generation: "multi-arch-v2".to_owned(), + package_specs: vec!["rocm[libraries,device-]==7.13.0".to_owned()], + rocm_sdk_target: None, + }), + ..base.clone() + }; + rewrite_manifest(&paths, &empty_device_extra)?; + + let all_blank = therock::InstalledRuntimeManifest { + runtime_key: "release-pip-all-blank".to_owned(), + channel: String::new(), + index_url: Some(" ".to_owned()), + selected_artifact_url: String::new(), + source_layout_generation: Some(String::new()), + wheel_composition: Some(therock::WheelRuntimeComposition { + source_layout_generation: String::new(), + package_specs: vec!["rocm[libraries]==7.13.0".to_owned()], + rocm_sdk_target: Some(String::new()), + }), + ..base + }; + rewrite_manifest(&paths, &all_blank)?; + + let rendered = render_runtimes_text(&paths, &RocmCliConfig::default())?; + let _ = fs::remove_dir_all(root); + + assert_eq!( + provenance_line(&rendered, &index_and_artifact.runtime_key), + " provenance: channel=release source=https://example.invalid/simple \ + source_layout_generation=unrecorded device_target=unrecorded", + "the index must win over the artifact URL:\n{rendered}" + ); + assert_eq!( + provenance_line(&rendered, &composition_layout.runtime_key), + " provenance: channel=release source=https://example.invalid/therock \ + source_layout_generation=next-v1 device_target=unrecorded", + "a layout recorded only in the composition is still recorded:\n{rendered}" + ); + assert_eq!( + provenance_line(&rendered, &spec_target.runtime_key), + " provenance: channel=release source=https://example.invalid/therock \ + source_layout_generation=multi-arch-v2 device_target=gfx1201", + "a target recorded only in the package specs is still recorded:\n{rendered}" + ); + assert_eq!( + provenance_line(&rendered, &adopted.runtime_key), + " provenance: channel=release source=unrecorded \ + source_layout_generation=unrecorded device_target=unrecorded", + "the adoption marker is not a package source:\n{rendered}" + ); + assert_eq!( + provenance_line(&rendered, &first_in_chain_wins.runtime_key), + " provenance: channel=release source=https://example.invalid/therock \ + source_layout_generation=multi-arch-v2 device_target=gfx1100", + "the first recorded value in each chain must win:\n{rendered}" + ); + assert_eq!( + provenance_line(&rendered, &blank_before_fallback.runtime_key), + " provenance: channel=release source=unrecorded \ + source_layout_generation=unrecorded device_target=unrecorded", + "a blank first value reads unrecorded, not the field after it:\n{rendered}" + ); + assert_eq!( + provenance_line(&rendered, &empty_device_extra.runtime_key), + " provenance: channel=release source=https://example.invalid/therock \ + source_layout_generation=multi-arch-v2 device_target=unrecorded", + "an empty device extra names no target:\n{rendered}" + ); + assert_eq!( + provenance_line(&rendered, &padded.runtime_key), + " provenance: channel=release source=https://example.invalid/simple \ + source_layout_generation=multi-arch-v2 device_target=gfx1201", + "shown values must be trimmed:\n{rendered}" + ); + assert_eq!( + provenance_line(&rendered, &all_blank.runtime_key), + " provenance: channel=unrecorded source=unrecorded \ + source_layout_generation=unrecorded device_target=unrecorded", + "a fact recorded only as blank must read unrecorded:\n{rendered}" + ); + Ok(()) + } + + /// `rocm examine` reports the active runtime's provenance as one line per + /// fact. They must be the facts and words the listing shows for that same + /// runtime, so this compares the two outputs as well as pinning each. + /// Two active runtimes: a nightly install that recorded every fact, and an + /// adopted one whose manifest holds only the adoption marker where an + /// artifact URL would be, which must not be reported as its source. + #[test] + fn examine_names_the_active_runtime_provenance_the_listing_shows() -> Result<()> { + type Build = fn(therock::InstalledRuntimeManifest) -> therock::InstalledRuntimeManifest; + let adopted: Build = |base| therock::InstalledRuntimeManifest { + index_url: None, + selected_artifact_url: crate::runtime_registry::ADOPTED_RUNTIME_ARTIFACT_URL.to_owned(), + read_only: true, + imported_from: Some(base.install_root.clone()), + ..base + }; + let cases: [(&str, &str, &str, Build, [&str; 4]); 2] = [ + ( + "nightly-wheel-gfx1201-10-1-0a20260822", + "therock-nightly:gfx120X-all", + "10.1.0a20260822", + nightly_exact_target_manifest, + [ + " active_runtime_channel: nightly", + " active_runtime_source: https://example.invalid/whl-multi-arch", + " active_runtime_source_layout_generation: next-v1", + " active_runtime_device_target: gfx1201", + ], + ), + ( + "adopted-release-pip-gfx120x-all-7-13-0", + "therock-release:gfx120X-all", + "7.13.0", + adopted, + [ + " active_runtime_channel: release", + " active_runtime_source: unrecorded", + " active_runtime_source_layout_generation: unrecorded", + " active_runtime_device_target: unrecorded", + ], + ), + ]; + for (runtime_key, runtime_id, version, build, expected) in cases { + let (root, paths) = test_paths("examine-runtime-provenance"); + let base = write_test_pip_runtime(&paths, runtime_key, runtime_id, version, 10)?; + let manifest = build(base); + rewrite_manifest(&paths, &manifest)?; + let config = RocmCliConfig { + active_runtime_key: Some(manifest.runtime_key.clone()), + ..RocmCliConfig::default() + }; + + let listed = render_runtimes_text(&paths, &config)?; + let mut examined = String::new(); + append_examine_runtime_state(&mut examined, &paths, &config)?; + let _ = fs::remove_dir_all(root); + + let listed_pairs = provenance_line(&listed, &manifest.runtime_key) + .trim_start() + .strip_prefix("provenance: ") + .expect("provenance prefix") + .split(' ') + .map(|pair| pair.split_once('=').expect("name=value pair")) + .map(|(name, value)| format!(" active_runtime_{name}: {value}")) + .collect::>(); + assert_eq!(listed_pairs, expected, "{runtime_key}:\n{listed}"); + for line in expected { + assert!( + examined.lines().any(|examined_line| examined_line == line), + "{runtime_key}: examine must report {line:?} as the listing does:\n{examined}" + ); + } + } + Ok(()) + } + #[test] fn runtime_lists_display_build_date_from_version_string() -> Result<()> { let (root, paths) = test_paths("runtime-build-date-display"); diff --git a/apps/rocm/src/therock/update.rs b/apps/rocm/src/therock/update.rs index 1f0972ba3..98751906c 100644 --- a/apps/rocm/src/therock/update.rs +++ b/apps/rocm/src/therock/update.rs @@ -461,12 +461,7 @@ fn plan_runtime_update( /// a base can be overridden or rehosted, and the recorded generation is the only /// statement about the stream that survives that. fn manifest_source_layout(manifest: &InstalledRuntimeManifest) -> Result { - SourceLayout::from_generation(manifest.source_layout_generation.as_deref().or_else(|| { - manifest - .wheel_composition - .as_ref() - .map(|composition| composition.source_layout_generation.as_str()) - })) + SourceLayout::from_generation(manifest.recorded_source_layout_generation()) } /// The family override to re-resolve a wheel manifest's update *plan* with. diff --git a/docs/architecture.md b/docs/architecture.md index f993c1ed3..75d87bf0e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -105,7 +105,7 @@ The `rocm` binary: the clap command tree, a handler module for most commands, an | [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs) | Registering runtimes `rocm install sdk` did not install (import, adopt, recovering the `rocm setup` runtime) and the one ready-runtime rule (`select_single_ready_runtime`). | domain | | [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) | Settling an engine onto a runtime after an SDK install (`finish_sdk_install`, `settle_engine_install`): engine-dependency and device checks and the post-install verdict. | relocation | | [`runtime_install_finalize/torch_alignment.rs`](../apps/rocm/src/runtime_install_finalize/torch_alignment.rs) | Whether an engine install realigns the runtime's torch to the engine's pin or keeps it as an intended divergence, running and reporting that, and the manifest readers it uses. | domain | -| [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) | The installed-runtime registry: the manifest model, where manifests live, writing and loading them, selection and activation validation, and the active-runtime marker with the atomic writer activation, rollback and uninstall use (a failed activation's restore writes or removes it directly, and `rocm config set-default-runtime`/`clear-default-runtime` remove it). | domain | +| [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) | The installed-runtime registry: the manifest model, where manifests live, writing and loading them, selection and activation validation, and the active-runtime marker with the atomic writer activation, rollback and uninstall use (a failed activation's restore writes or removes it directly, and `rocm config set-default-runtime`/`clear-default-runtime` remove it), and the recorded provenance (`RuntimeProvenance`) that the runtime list and `rocm examine` both print. | domain | | [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs) | Reconciling running local servers with a runtime being activated or rolled back: classifying each, the report, and moving stale ones with `--restart-services`. | domain | | [`runtime_uninstall.rs`](../apps/rocm/src/runtime_uninstall.rs) | `rocm runtimes uninstall`: planning, revalidating after the prompt, and applying the removal of a registered runtime, including dropping it as the active or rollback runtime in the config and the active-runtime marker and clearing a Lemonade record inside its folder. | domain | | [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) | `rocm runtimes` (`runtimes`): activation and rollback, which write the active-runtime marker through `runtime_registry.rs`, and the runtime list. | relocation | @@ -857,7 +857,7 @@ Gherkin `.feature` files under `features/` backed by Rust step functions that dr | [`tests/e2e/diagnose_steps.rs`](../tests/e2e-cucumber/tests/e2e/diagnose_steps.rs) | Steps for [`diagnose.feature`](../tests/e2e-cucumber/features/diagnose.feature): `rocm diagnose` matches and `rocm fix` listings, previews, printed verify commands and failing fixes. | flat | | [`tests/e2e/driver_steps.rs`](../tests/e2e-cucumber/tests/e2e/driver_steps.rs) | Steps for [`driver_install.feature`](../tests/e2e-cucumber/features/driver_install.feature): previewing and approving GPU driver installation plans on WSL, Linux and Windows hosts. | flat | | [`tests/e2e/engines_steps.rs`](../tests/e2e-cucumber/tests/e2e/engines_steps.rs) | Steps for [`engine_shell.feature`](../tests/e2e-cucumber/features/engine_shell.feature): `rocm engines shell` under a pseudo-terminal, since the defect shows only in what the terminal renders. | flat | -| [`tests/e2e/examine_steps.rs`](../tests/e2e-cucumber/tests/e2e/examine_steps.rs) | Steps for [`examine.feature`](../tests/e2e-cucumber/features/examine.feature): `rocm examine`, version and help output, engine listing and the driver plan preview. | flat | +| [`tests/e2e/examine_steps.rs`](../tests/e2e-cucumber/tests/e2e/examine_steps.rs) | Steps for [`examine.feature`](../tests/e2e-cucumber/features/examine.feature): `rocm examine`, the active runtime's provenance, version and help output, engine listing and the driver plan preview. | flat | | [`tests/e2e/host_guard.rs`](../tests/e2e-cucumber/tests/e2e/host_guard.rs) | The host check the Windows driver-install steps run before any CLI call, kept free of the cucumber world so a separate test can include it. | flat | | [`tests/e2e/lemonade_install_steps.rs`](../tests/e2e-cucumber/tests/e2e/lemonade_install_steps.rs) | Steps for [`lemonade_installs.feature`](../tests/e2e-cucumber/features/lemonade_installs.feature): what the user is told about the Lemonade copies on disk, from planted trees and install records. | flat | | [`tests/e2e/lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/lifecycle_steps.rs) | Steps for [`install_lifecycle.feature`](../tests/e2e-cucumber/features/install_lifecycle.feature): `xtask package`, the root installer and the installed binaries, from install through uninstall. | flat | @@ -865,7 +865,7 @@ Gherkin `.feature` files under `features/` backed by Rust step functions that dr | [`tests/e2e/model_catalog_steps.rs`](../tests/e2e-cucumber/tests/e2e/model_catalog_steps.rs) | Steps for [`model_catalog.feature`](../tests/e2e-cucumber/features/model_catalog.feature): the verbose catalog's AIM entry, its Docker-unavailable flag and its staleness warning. | flat | | [`tests/e2e/planner_steps.rs`](../tests/e2e-cucumber/tests/e2e/planner_steps.rs) | Steps for the planning-assistant scenarios in [`chat.feature`](../tests/e2e-cucumber/features/chat.feature), with a scripted mock proving a request is handed over once and its plan is the one shown. | flat | | [`tests/e2e/remote_steps.rs`](../tests/e2e-cucumber/tests/e2e/remote_steps.rs) | Steps for [`remote.feature`](../tests/e2e-cucumber/features/remote.feature): `rocm remote` against the `fake-tailscale` stand-in and a status document the step writes. | flat | -| [`tests/e2e/runtime_lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs) | Steps for [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` activate, rollback, uninstall and import over planted read-only tarball runtimes. | flat | +| [`tests/e2e/runtime_lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs) | Steps for [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` activate, rollback, uninstall and import over planted read-only tarball runtimes, and listing planted nightly wheel, older and adopted runtimes with their provenance. | flat | | [`tests/e2e/runtime_side_by_side_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_side_by_side_steps.rs) | Steps for the side-by-side scenarios in [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` list, activate and uninstall over managed wheel runtimes planted as installs from before and after the ROCm 10 layout leave them, comparing their install records byte for byte. | flat | | [`tests/e2e/runtime_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_steps.rs) | Steps for [`runtime_setup.feature`](../tests/e2e-cucumber/features/runtime_setup.feature): SDK install previews and installs, runtime folders reached through a link, and the managed runtime they leave active. | flat | | [`tests/e2e/service_cleanup_steps.rs`](../tests/e2e-cucumber/tests/e2e/service_cleanup_steps.rs) | Steps for [`service_record_cleanup.feature`](../tests/e2e-cucumber/features/service_record_cleanup.feature): `rocm services remove` and `prune` over planted service records, asserting on the files that survive, and [`service_record_unqueryable.feature`](../tests/e2e-cucumber/features/service_record_unqueryable.feature): a record whose process cannot be queried (the `e2e-test-hooks` build reads `ROCM_E2E_UNQUERYABLE_PIDS`) is stopped as unverified, refused by `remove`, and cleared by `remove --force` only when no recorded process is confirmed running. | flat | diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 613cd8c2a..f7bab1843 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -114,7 +114,15 @@ rocm runtimes list Expected result: - `rocm examine` shows a managed runtime. -- `rocm runtimes list` shows the runtime key for the installed TheRock venv. +- `rocm runtimes list` shows the runtime key for the installed TheRock venv, + and under it a `provenance:` line naming the `channel`, the package `source`, + the `source_layout_generation` and the exact `device_target` the install + printed. A fact recorded nowhere, or recorded blank, reads `unrecorded`; + none is guessed (the target is never the family). +- `rocm examine` reports the same four facts for the active runtime as its + `active_runtime_channel`, `active_runtime_source`, + `active_runtime_source_layout_generation` and `active_runtime_device_target` + lines. - The active runtime is ready, or the output gives one clear next command. Optional: an unreadable settings file. Copy `config.json` from the config diff --git a/docs/testing.md b/docs/testing.md index 2227bcfbe..9c42bb5fd 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1788,6 +1788,63 @@ List registered managed or read-only runtimes and their exact side-by-side keys: rocm runtimes list ``` +Each runtime's row is followed by its `install_root:` and a `provenance:` line +naming the `channel`, the package `source` (the wheel index, or the downloaded +archive for a tarball install), the `source_layout_generation` and the exact +`device_target` its manifest recorded, for example: + +```text + provenance: channel=nightly source= source_layout_generation=next-v1 device_target=gfx1201 +``` + +The values are the ones the manifest recorded: the package index, else the +artifact URL (never the marker an adopted runtime keeps there); the layout +field, else the wheel composition's; the recorded target, else the +`device-` extra in the package specs. For the layout and target this +chooses the same recorded field `rocm update` uses, through the same accessors; +`rocm update` then uses the value as recorded, while the listing trims it and +prints a blank one as `unrecorded`. Each step moves on only when a field is +absent, so a blank field is not skipped in favour of the next one, and a fact +recorded nowhere also prints `unrecorded`. Nothing is guessed from other +facts: a family-wide or tarball install shows `device_target=unrecorded` rather +than a target guessed from its family, and a runtime registered with +`rocm runtimes adopt` shows `source=unrecorded`. The chains, their precedence, +the blank and trimming rules are pinned by +`runtime_list_reads_each_provenance_fact_from_where_it_was_recorded`; blank or +padded values are not what `rocm install sdk` writes, but can come from a +hand-edited manifest or one brought in with `rocm runtimes import`. An adopted +runtime's channel is the one adoption recorded: the channel `--channel` or +`--runtime-id` named, `release` when neither names one. All three paths +(neither flag, `--channel nightly`, and `--runtime-id therock-nightly:` +with no `--channel`) are pinned by +`adopted_runtime_lists_its_channel_and_its_source_as_unrecorded` in +[runtime_adopt.rs](../apps/rocm/src/runtime_adopt.rs). The marker adoption +writes in place of an artifact URL is persisted manifest format. Code in the +crate refers to it only through its constant, so two checks pin the literal +value: `adoption_marker_keeps_its_persisted_value` in +[runtime_registry.rs](../apps/rocm/src/runtime_registry.rs), and +`runtime-lifecycle-22` (below), which plants it in an adopted runtime's +manifest. +`rocm examine` prints the same four facts for the active runtime as +`active_runtime_channel`, `active_runtime_source`, +`active_runtime_source_layout_generation` and `active_runtime_device_target`, +from the same fields. The unit tests +`runtime_list_names_where_each_runtime_came_from` and +`examine_names_the_active_runtime_provenance_the_listing_shows` in +[runtimes_cmd.rs](../apps/rocm/src/runtimes_cmd.rs) pin the values, the +latter for an active nightly runtime and an active adopted one; +`@id:runtime-lifecycle-list-names-runtime-provenance` (`runtime-lifecycle-22`) +checks the listing end to end with a planted nightly runtime, an older one +that recorded neither its layout nor an exact target, and an adopted one whose +manifest holds the adoption marker as earlier releases wrote it, which must +list `source=unrecorded`; and +`@id:examine-reports-where-the-active-runtime-came-from` (`examine-54`) checks +the `examine` lines. Both plant read-only manifests and run on the mock lane: + +```bash +RUSTC_WRAPPER= cargo xtask e2e -- -n 'runtime-lifecycle-22 |examine-54 ' +``` + Activate one validated runtime: ```bash diff --git a/tests/e2e-cucumber/features/examine.feature b/tests/e2e-cucumber/features/examine.feature index 8f508d28b..a5a7d1c52 100644 --- a/tests/e2e-cucumber/features/examine.feature +++ b/tests/e2e-cucumber/features/examine.feature @@ -782,3 +782,14 @@ Feature: GPU detection and system inspection Then the inspection lists that runtime's librocdxg as one its own runtime does not load When the user runs the command the inspection advises for that runtime's librocdxg and inspects again Then the inspection lists no runtime librocdxg that its own runtime does not load + + # `examine` reports the active runtime's channel, package source, source layout + # and exact GPU target in the same words and from the same manifest fields as + # the `provenance:` line `rocm runtimes list` prints for it + # (`runtime-lifecycle-22`). The planted manifest needs no GPU or download, so + # this runs on the mock lane. + @id:examine-reports-where-the-active-runtime-came-from + Scenario: examine-54 - Examining the system says where the active runtime came from + Given the active runtime is a nightly runtime installed for one exact GPU + When the user inspects the system + Then the runtime state names the channel, package source, source layout and exact GPU target that runtime was installed from diff --git a/tests/e2e-cucumber/features/runtime_lifecycle.feature b/tests/e2e-cucumber/features/runtime_lifecycle.feature index 3cd8681b4..d4e4f1086 100644 --- a/tests/e2e-cucumber/features/runtime_lifecycle.feature +++ b/tests/e2e-cucumber/features/runtime_lifecycle.feature @@ -308,3 +308,23 @@ Feature: Runtime lifecycle state machine When the user activates a runtime by the name the two release runtimes share Then the CLI refuses and names both release runtimes And no runtime is in use + + # The install report names a runtime's channel, package source, source layout + # and exact GPU target; afterwards only its manifest still knows them. The + # listing reads them back and says when one was never recorded rather than + # inferring it — the older runtime's family is itself an exact target, so a + # guess would look like a recorded value. An adopted runtime installed + # nothing, so it has no package source; its manifest holds only the marker + # adoption writes in place of one, in the on-disk form earlier releases wrote, + # and the listing must not show that marker as a source. The planted manifests + # need no SDK download or GPU, so this runs on the mock lane. + @id:runtime-lifecycle-list-names-runtime-provenance + Scenario: runtime-lifecycle-22 - Listing runtimes says which stream, source and GPU each runtime was installed from + Given a registered nightly runtime installed for one exact GPU + And a registered runtime installed before its source layout and GPU target were recorded + And a registered runtime adopted from an environment ROCm CLI did not install + When the user lists the registered runtimes + Then the nightly runtime's listing names its channel, package source, source layout and exact GPU target + And its version shows its build date + And the older runtime's listing says which of those facts were not recorded instead of guessing + And the adopted runtime's listing says it has no recorded package source diff --git a/tests/e2e-cucumber/tests/e2e/examine_steps.rs b/tests/e2e-cucumber/tests/e2e/examine_steps.rs index 4f5f03cd9..a3b34fef3 100644 --- a/tests/e2e-cucumber/tests/e2e/examine_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/examine_steps.rs @@ -546,6 +546,54 @@ fn planted_setup_runtime_root(world: &E2eWorld) -> std::path::PathBuf { .join("setup-runtime") } +#[given("the active runtime is a nightly runtime installed for one exact GPU")] +async fn active_runtime_is_nightly_exact_target(world: &mut E2eWorld) { + use super::runtime_lifecycle_steps::{ + NIGHTLY_EXACT_TARGET_KEY, plant_nightly_exact_target_runtime, + }; + plant_nightly_exact_target_runtime(world); + // Black-box: plain JSON matching the CLI's on-disk config schema; every + // other field defaults. `examine` reads the active runtime from here. + let config_dir = world + .isolated_root + .as_ref() + .expect("no isolated root") + .path() + .join("config"); + std::fs::create_dir_all(&config_dir).expect("failed to create config dir"); + let config = serde_json::json!({ "active_runtime_key": NIGHTLY_EXACT_TARGET_KEY }); + std::fs::write( + config_dir.join("config.json"), + serde_json::to_string_pretty(&config).expect("failed to serialize config"), + ) + .expect("failed to write config"); +} + +#[then( + "the runtime state names the channel, package source, source layout and exact GPU target that runtime was installed from" +)] +async fn runtime_state_names_active_provenance(world: &mut E2eWorld) { + use super::runtime_lifecycle_steps::{ + NIGHTLY_DEVICE_TARGET, NIGHTLY_SOURCE, NIGHTLY_SOURCE_LAYOUT, + }; + let out = world.cli_output.clone().unwrap_or_default(); + for (field, expected) in [ + ("active_runtime_channel", "nightly"), + ("active_runtime_source", NIGHTLY_SOURCE), + ( + "active_runtime_source_layout_generation", + NIGHTLY_SOURCE_LAYOUT, + ), + ("active_runtime_device_target", NIGHTLY_DEVICE_TARGET), + ] { + assert_eq!( + field_value(&out, field), + Some(expected), + "examine must report {field} for the active runtime:\n{out}" + ); + } +} + #[given("setup names a runtime folder the registry has forgotten")] async fn setup_names_folder_registry_forgot(world: &mut E2eWorld) { let root = world.isolated_root.as_ref().expect("no isolated root"); diff --git a/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs b/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs index 0ccfac83b..83d34d6ad 100644 --- a/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs @@ -128,6 +128,114 @@ fn runtime_manifest_json(key: &str, family: &str, install_root: &Path) -> String .expect("failed to serialize runtime manifest") } +/// A nightly ROCm 10 wheel runtime installed for one exact GPU. Its family is the +/// family-wide `gfx120X-all` while its exact target is `gfx1201`, so a listing +/// that guessed the target from the family would show a different value. +pub(crate) const NIGHTLY_EXACT_TARGET_KEY: &str = "nightly-wheel-gfx1201-10-1-0a20260822"; +/// The package index the nightly runtime records. `.invalid` never resolves; +/// nothing here is fetched, the value is only read back. +pub(crate) const NIGHTLY_SOURCE: &str = "https://example.invalid/whl-multi-arch"; +/// The artifact URL the nightly runtime records beside its index. Deliberately +/// different from [`NIGHTLY_SOURCE`], so a listing that showed the artifact URL +/// instead of the package index would be caught. (`rocm install sdk` writes the +/// index into both; an imported manifest can carry two different values.) +const NIGHTLY_ARTIFACT_URL: &str = "https://example.invalid/artifacts/rocm-10.1.0a20260822"; +/// The source layout generation a ROCm 10 nightly is published under. +pub(crate) const NIGHTLY_SOURCE_LAYOUT: &str = "next-v1"; +/// The exact GPU target the nightly runtime's packages were installed for. +pub(crate) const NIGHTLY_DEVICE_TARGET: &str = "gfx1201"; + +/// Write a read-only nightly `wheel` runtime manifest recording every provenance +/// fact the way `rocm install sdk` records it: channel, package index, source +/// layout generation, and the exact GPU target in its wheel composition. Its +/// version embeds a build date. Read-only and with no Python, it lists as +/// unusable — which does not matter to what these scenarios read from it. +pub(crate) fn plant_nightly_exact_target_runtime(world: &E2eWorld) { + let root = world.isolated_root.as_ref().expect("no isolated root"); + let install_root = root.path().join("runtime-nightly-gfx1201"); + std::fs::create_dir_all(&install_root).expect("failed to create install root"); + let registry = registry_dir(world); + std::fs::create_dir_all(®istry).expect("failed to create registry dir"); + let manifest = serde_json::json!({ + "runtime_key": NIGHTLY_EXACT_TARGET_KEY, + "runtime_id": "therock-nightly:gfx120X-all", + "channel": "nightly", + "format": "wheel", + "family": "gfx120X-all", + "family_source": "detected", + "version": "10.1.0a20260822", + "install_root": install_root, + "selected_artifact_url": NIGHTLY_ARTIFACT_URL, + "source_layout_generation": NIGHTLY_SOURCE_LAYOUT, + "index_url": NIGHTLY_SOURCE, + "wheel_composition": { + "source_layout_generation": NIGHTLY_SOURCE_LAYOUT, + "package_specs": [format!("rocm[libraries,device-{NIGHTLY_DEVICE_TARGET}]==10.1.0a20260822")], + "rocm_sdk_target": NIGHTLY_DEVICE_TARGET, + }, + "read_only": true, + "devel": false, + "installed_at_unix_ms": 1_700_000_000_000u64, + }); + std::fs::write( + registry.join(format!("{NIGHTLY_EXACT_TARGET_KEY}.json")), + serde_json::to_string_pretty(&manifest).expect("failed to serialize runtime manifest"), + ) + .expect("failed to write runtime manifest"); +} + +/// Key of the planted adopted runtime, in the shape `rocm runtimes adopt` +/// derives when no key is given: `adopted-{channel}-pip-{family}-{version}`. +const ADOPTED_KEY: &str = "adopted-release-pip-gfx1100-7-13-0"; +/// Version matching [`ADOPTED_KEY`]. +const ADOPTED_VERSION: &str = "7.13.0"; + +/// Write a runtime manifest carrying the fields the listing reads, as adoption +/// writes them for an environment ROCm CLI did not install: read-only, +/// `imported_from` its own folder, no package index or source layout, and the +/// adoption marker where an artifact URL would be. It is not everything +/// `rocm runtimes adopt` writes (there is no SDK probe or Python), and it is +/// planted rather than adopted because adopting needs a real ROCm SDK +/// environment to probe. +fn plant_adopted_runtime(world: &E2eWorld) { + let install_root = plant_runtime(world, ADOPTED_KEY, "gfx1100"); + let manifest_path = registry_dir(world).join(format!("{ADOPTED_KEY}.json")); + let mut manifest: serde_json::Value = serde_json::from_str( + &std::fs::read_to_string(&manifest_path).expect("failed to read planted manifest"), + ) + .expect("planted manifest is not JSON"); + let fields = manifest + .as_object_mut() + .expect("planted manifest is not an object"); + fields.insert("version".into(), ADOPTED_VERSION.into()); + fields.insert("format".into(), "wheel".into()); + fields.insert("family_source".into(), "runtime_id".into()); + fields.insert("imported_from".into(), serde_json::json!(install_root)); + // The literal adoption has always written here, NOT the CLI's constant: + // runtimes adopted by earlier releases hold exactly this on disk, so the + // listing must keep recognising it. If the CLI changes the marker without + // a migration, this scenario goes red, as does the unit test + // `adoption_marker_keeps_its_persisted_value` in runtime_registry.rs, + // which pins the same literal against the constant. + fields.insert("selected_artifact_url".into(), "adopted-read-only".into()); + std::fs::write( + &manifest_path, + serde_json::to_string_pretty(&manifest).expect("failed to serialize runtime manifest"), + ) + .expect("failed to write runtime manifest"); +} + +/// The `provenance:` line the listing prints under `runtime_key`'s row: the +/// first one after the row that names the key. +fn listed_provenance<'a>(out: &'a str, runtime_key: &str) -> &'a str { + let row = format!(" {runtime_key} runtime_id="); + out.lines() + .skip_while(|line| !line.contains(&row)) + .skip(1) + .find_map(|line| line.trim().strip_prefix("provenance: ")) + .unwrap_or_else(|| panic!("no provenance line listed for {runtime_key}:\n{out}")) +} + /// Plant a managed-service record the CLI reads as a LIVE local server that was /// launched against `recorded_runtime_key`, so activation has something real to /// report on. Uses the shared record schema (`write_service_record_with`) rather @@ -447,6 +555,26 @@ async fn one_readonly_runtime(world: &mut E2eWorld) { world.model_name = Some(install_root.to_string_lossy().into_owned()); } +#[given("a registered nightly runtime installed for one exact GPU")] +async fn registered_nightly_exact_target_runtime(world: &mut E2eWorld) { + plant_nightly_exact_target_runtime(world); +} + +/// The planted tarball manifest records its archive URL and nothing about a +/// source layout or an exact GPU target, as manifests written before those +/// fields did. Its family is the exact `gfx942`, so a target guessed from the +/// family would be indistinguishable from a recorded one — which is the guess +/// the listing must not make. +#[given("a registered runtime installed before its source layout and GPU target were recorded")] +async fn registered_runtime_without_recorded_provenance(world: &mut E2eWorld) { + plant_runtime(world, FIRST_KEY, "gfx942"); +} + +#[given("a registered runtime adopted from an environment ROCm CLI did not install")] +async fn registered_adopted_runtime(world: &mut E2eWorld) { + plant_adopted_runtime(world); +} + #[given("a runtime manifest to import")] async fn manifest_to_import(world: &mut E2eWorld) { let path = write_import_manifest(world); @@ -1412,3 +1540,59 @@ async fn server_record_still_names_first_runtime(world: &mut E2eWorld) { the live one it was:\n{record}" ); } + +#[then( + "the nightly runtime's listing names its channel, package source, source layout and exact GPU target" +)] +async fn nightly_listing_names_provenance(world: &mut E2eWorld) { + let out = ok_output(world); + assert_eq!( + listed_provenance(&out, NIGHTLY_EXACT_TARGET_KEY), + format!( + "channel=nightly source={NIGHTLY_SOURCE} \ + source_layout_generation={NIGHTLY_SOURCE_LAYOUT} \ + device_target={NIGHTLY_DEVICE_TARGET}" + ), + "the listing must name where the nightly runtime came from:\n{out}" + ); +} + +#[then("its version shows its build date")] +async fn nightly_version_shows_build_date(world: &mut E2eWorld) { + let out = ok_output(world); + let row = out + .lines() + .find(|line| line.contains(&format!(" {NIGHTLY_EXACT_TARGET_KEY} runtime_id="))) + .unwrap_or_else(|| panic!("no row listed for the nightly runtime:\n{out}")); + assert!( + row.contains(" version=10.1.0a20260822 (build 2026-08-22) "), + "the nightly runtime's version must show its build date:\n{row}" + ); +} + +#[then( + "the older runtime's listing says which of those facts were not recorded instead of guessing" +)] +async fn older_listing_says_unrecorded(world: &mut E2eWorld) { + let out = ok_output(world); + assert_eq!( + listed_provenance(&out, FIRST_KEY), + format!( + "channel=release source=https://example.invalid/{FIRST_KEY}.tar.gz \ + source_layout_generation=unrecorded device_target=unrecorded" + ), + "an unrecorded fact must say so, not be inferred from the family:\n{out}" + ); +} + +#[then("the adopted runtime's listing says it has no recorded package source")] +async fn adopted_listing_says_source_unrecorded(world: &mut E2eWorld) { + let out = ok_output(world); + assert_eq!( + listed_provenance(&out, ADOPTED_KEY), + "channel=release source=unrecorded \ + source_layout_generation=unrecorded device_target=unrecorded", + "adoption installed nothing, so the listing must not present the \ + adoption marker as a package source:\n{out}" + ); +} diff --git a/xtask/src/e2e_prewarm.rs b/xtask/src/e2e_prewarm.rs index abd07a44c..0baf1de29 100644 --- a/xtask/src/e2e_prewarm.rs +++ b/xtask/src/e2e_prewarm.rs @@ -430,8 +430,8 @@ pub fn dangling_active_runtime(runtimes_list_report: &str) -> Option<&str> { }) } -/// The already-installed runtime (from `rocm runtimes list`, which carries no -/// `channel=` field at all) whose key names `pin` within `channel`. +/// The already-installed runtime (from `rocm runtimes list`) whose key names +/// `pin` within `channel`. /// /// Mirrors `decide()`'s pin branch, which scopes its own search to /// `channel_runtimes` (or a same-channel unattributed error line) before ever @@ -439,9 +439,11 @@ pub fn dangling_active_runtime(runtimes_list_report: &str) -> Option<&str> { /// pin's token/digit-run appears in a key, with no notion of channel, so an /// unscoped search here could match a `release` pin against an installed /// `nightly` runtime that happens to share the pin's version/build-date -/// digits, silently serving the wrong channel's SDK. Since this listing has no -/// channel field to key off at all, the guard is the same `{channel}-` prefix -/// `decide()` falls back to for its own degraded, channel-less lines. +/// digits, silently serving the wrong channel's SDK. The listing prints +/// `channel=` only on each runtime's separate `provenance:` line, and +/// `RuntimeEntry::parse` reads only the row line, so the guard is the same +/// `{channel}-` key prefix `decide()` falls back to for its own degraded, +/// channel-less lines. /// /// Read-only (adopted/imported) entries are excluded for the same reason /// `activation_candidates` excludes them: a matching entry here becomes @@ -1170,11 +1172,14 @@ source: index\n" ) } - /// A real `rocm runtimes list` on a tree holding all three shapes that matter, - /// captured verbatim from the built binary rather than written by hand: one - /// poisoned managed runtime (an install root under a per-scenario temp dir that - /// is gone), one healthy managed runtime inside the tree, and one read-only - /// runtime adopted from outside it. + /// A `rocm runtimes list` on a tree holding all three shapes that matter, + /// captured from the built binary rather than written by hand: one poisoned + /// managed runtime (an install root under a per-scenario temp dir that is + /// gone), one healthy managed runtime inside the tree, and one read-only + /// runtime adopted from outside it. The capture predates the rows' + /// `toolchain=` field, which is not added back here; the `provenance:` line + /// the listing now prints after each `install_root:` was added by hand, in + /// that position, so [`assess`] is read against the current row order. /// /// Note that ALL THREE report `status=unusable` here. That is the whole reason /// [`assess`] keys off the install root instead: the healthy one is unusable @@ -1192,10 +1197,13 @@ registered ROCm runtimes adopted-external-env runtime_id=external-adopted version=7.14.0 format=wheel family=gfx94X-dcgpu mode=read-only status=unusable (pip runtime manifest is missing rocm_sdk probe data) install_root: /opt/external-rocm + provenance: channel=release source=unrecorded source_layout_generation=unrecorded device_target=unrecorded release-wheel-gfx94x-dcgpu-7-15-0 runtime_id=therock-release-gfx94x-dcgpu version=7.15.0 format=wheel family=gfx94X-dcgpu mode=managed status=unusable (pip runtime manifest is missing rocm_sdk probe data) install_root: /w/e2e-prewarm/data/runtimes/wheel/release-wheel-gfx94x-dcgpu-7-15-0 + provenance: channel=release source=https://example.invalid/whl source_layout_generation=unrecorded device_target=unrecorded release-wheel-gfx94x-dcgpu-7-13-0 runtime_id=therock-release-gfx94x-dcgpu version=7.13.0 format=wheel family=gfx94X-dcgpu mode=managed status=unusable (install root is missing: /tmp/rocm-e2e-7MidR2/data/runtimes/wheel/release-wheel-gfx94x-dcgpu-7-13-0) install_root: /tmp/rocm-e2e-7MidR2/data/runtimes/wheel/release-wheel-gfx94x-dcgpu-7-13-0 + provenance: channel=release source=https://example.invalid/whl source_layout_generation=unrecorded device_target=unrecorded "; /// A real `rocm runtimes list` on an empty tree, captured from the binary. @@ -1210,9 +1218,10 @@ registered ROCm runtimes next step: rocm install sdk --channel release --format wheel "; - /// A real `rocm runtimes list` on the tree that killed the lane: the config - /// still names the 7.14.0 runtime that was removed out of band, while two - /// runtimes it could be pointed at sit right there. + /// A `rocm runtimes list` on the tree that killed the lane, captured before + /// the rows gained `toolchain=` and `provenance:` lines, neither added here: + /// the config still names the 7.14.0 runtime that was removed out of band, + /// while two runtimes it could be pointed at sit right there. /// /// Note there is no `*` marker on any entry — the renderer only marks the /// active one by matching `active_runtime_key` against a manifest, and that is @@ -1374,11 +1383,12 @@ registered ROCm runtimes #[test] fn pinned_runtime_entry_does_not_match_another_channels_installed_runtime() { // 7.14.0 is only installed under `nightly`, not the requested - // `release`. `rocm runtimes list` carries no `channel=` field at all - // (unlike `rocm update`'s report), so the `{channel}-` prefix guard is - // the only thing standing between this and silently serving the wrong - // channel's SDK for a pin that happens to share another channel's - // installed version. + // `release`. `rocm runtimes list` prints `channel=` only on each + // runtime's `provenance:` line, which `RuntimeEntry::parse` does not + // read (it reads the row line alone), so the `{channel}-` key prefix + // guard is the only thing standing between this and silently serving + // the wrong channel's SDK for a pin that happens to share another + // channel's installed version. assert!(find_pinned_runtime_entry(MULTI_CHANNEL, "release", "7.14.0").is_none()); assert_eq!( find_pinned_runtime_entry(MULTI_CHANNEL, "nightly", "7.14.0").map(|e| e.runtime_key), @@ -1455,6 +1465,19 @@ mode=managed status=ready\n install_root: /tmp/rocm-e2e-XXXX/data/runtimes/ assert!(RuntimeEntry::parse(" install_root: /tmp/x").is_none()); } + #[test] + fn a_provenance_line_is_not_read_as_an_entry() { + // `rocm runtimes list` prints a `provenance:` line under each runtime, + // whose `name=value` fields sit beside the row's own. + assert!( + RuntimeEntry::parse( + " provenance: channel=release source=unrecorded \ +source_layout_generation=unrecorded device_target=unrecorded" + ) + .is_none() + ); + } + #[test] fn a_tarball_runtime_reports_its_own_format() { // The folder to remove is `//`, so the format has to