Skip to content

feat(runtimes): add --json to rocm runtimes list (ROCMAI-148) - #1098

Merged
rominf merged 7 commits into
mainfrom
ROCMAI-148-feat-runtimes-list-json
Nov 17, 2026
Merged

rominf merged 7 commits into
mainfrom
ROCMAI-148-feat-runtimes-list-json

Conversation

@rominf

@rominf rominf commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Why

A script that wants the registered ROCm runtimes, which one is active, which is the rollback target and where each came from has to scrape the rocm runtimes list text table, its */- markers and its provenance: lines. There was also no written record of which commands offer --json, which do not, and why.

Publishing those flags as a contract also meant fixing what they mean. The listing used to decide "active" and "rollback target" by matching rules of its own, so in some configurations (an active key in other letter case, a dead active key whose default id still resolves, two keys differing only in letter case, a previous key with surrounding whitespace or given as a runtime id) it marked a different runtime than the one rocm examine, rocm runtimes activate, rollback, uninstall and rocm update actually act on.

What changes

  • rocm runtimes list --json prints the listing as one JSON document on stdout through the shared JsonOrText/print_json_or_text: each runtime's key, id, version, format, family, mode, status, toolchain, install root and provenance, active and rollback_target flags in place of the markers, and whether it is usable (unusable_reason). The top level carries default_runtime_id, active_runtime_key, previous_runtime_key, the registry and marker paths, and active_problem. Unset values are null. The listing is computed once into a value and both the text and the JSON render from it, so the flags and the markers cannot disagree. The empty-registry next-step hint stays text-only.
  • Each runtime's provenance is an object with the four facts the text prints on its provenance: line, under the same names: channel, source, source_layout_generation and device_target. Each is the recorded value (trimmed), or null where the text prints unrecorded (recorded nowhere or blank, the source of an adopted runtime, the exact target of a tarball or family-wide install), so a script cannot take the placeholder for a value. The names and their order come from one list, RuntimeProvenance::recorded_fields, which the text's RuntimeProvenance::fields is now derived from, so the two forms cannot name the facts differently.
  • The listing marks what the commands act on. active is the runtime current_runtime_manifest resolves, the resolver rocm examine, activate, rollback, uninstall and update use; rollback_target is the runtime select_runtime_manifest resolves previous_runtime_key to, which is what rocm runtimes rollback selects (a value rollback would refuse, as missing or ambiguous, marks nothing). The resolvers themselves are unchanged.
  • active_problem reports the configuration by the same matching: missing_manifest_for_key when active_runtime_key names no runtime (letter case ignored), missing_manifest_for_id / ambiguous_runtime_id for default_runtime_id when no active key is set. A dead active key is still reported as missing_manifest_for_key when the commands fall back to the default id and the listing marks that runtime active; that is the one state where a problem is shown beside an active runtime.
  • The JSON field carrying the configured default id is named default_runtime_id, since it is the config value and not necessarily the active runtime's id. The text label stays active_runtime_id:, as in rocm examine.
  • registry, marker and install_root are written with to_string_lossy, so a path that is not valid UTF-8 is listed with U+FFFD (as the text form prints it) instead of --json failing with empty stdout.
  • toolchain is an enum serialized as included/excluded, the words the text and rocm examine print, pinned by an agreement test like mode.
  • --json is on list only; rocm runtimes --json (bare) is rejected by the parser rather than read as list --json.
  • New docs/json-output.md audits --json per command family (supported / intentionally unsupported / follow-up, each with its rationale) and states the rules: stdout carries only the document, diagnostics stay on stderr, documented fields change only additively, a failing command exits 1 with its error on stderr and nothing on stdout unless it documents its own code, and a command line the argument parser rejects exits 2 before the command runs. It documents one known exception to the stdout rule (see Scope). Its "Which runtimes are marked" section describes the rules above. README, docs/ux-guidelines.md, docs/testing.md, docs/manual-testing.md and docs/architecture.md are updated to match.

Text output changes

Compared with origin/main, rocm runtimes list text output changes only in these states, all reached by a hand-edited config, a deleted registry entry, or case-twin keys/ids; every other state prints byte-identical output:

  • Active key differing from a runtime's key only in letter case: the active_status: missing manifest for active_runtime_key=… line is removed, and that runtime gains *.
  • Active key naming no runtime while the default id resolves one: the status line is unchanged, and that runtime gains *.
  • No active key, default id matching one runtime only when letter case is ignored: the false missing-id status line is removed (the row was already *).
  • No active key, runtime ids differing only in letter case: an ambiguous-runtime-id status line is added.
  • Two keys differing only in letter case: * goes to the first of them in list order, the one the commands act on.
  • Previous key differing from a runtime's key in letter case, given as a runtime id, or padded with whitespace: that runtime gains -.
  • Dead active key falling back onto the rollback target: that runtime's - becomes *.

Scope

This is the first slice. Deliberately not done here, and recorded as follow-ups in the audit table: a shared response envelope, JSON on failure paths, and --json on mutating commands (activate, rollback, uninstall, import, adopt, service and install commands). The envelope would change the shapes of the frozen rocm examine and rocm fix contracts, so it needs an owner decision; docs/json-output.md leaves it as an open decision.

Known limitation, recorded in docs/json-output.md and tracked as a follow-up: the startup update check that runs before most commands (refresh_startup_update_check_quietly in apps/rocm/src/main.rs) prints its Python progress line through progress_line, which writes to stdout. So on the first run in a check interval, when the runtime it checks is a wheel install whose recorded Python is not usable and the Python it finds instead does not fit, a line such as Python from PATH is not usable for this ROCm install (… is required). precedes the document of any --json command. This predates this PR and was reproduced with rocm runtimes list --json on a planted wheel runtime. ROCM_CLI_DISABLE_STARTUP_UPDATE_CHECK turns the check off; scenario runtime-lifecycle-31 sets it for that reason.

Three other surfaces still resolve the active runtime by their own rules and are listed under "Known differences" in docs/json-output.md; aligning them is follow-up work:

  • the runtime manager in rocm dash matches the active key, the default id and the previous key exactly;
  • rocm setup status looks the active key up ignoring letter case but does not fall back to the default id;
  • rocm engines install without --runtime-id, for an engine on the ROCm runtime, resolves the active key (or, when unset, the default id) the way rollback resolves a key, so a dead key fails the install instead of falling back, and a key matching case twins only by letter case is refused as ambiguous.

Reviewer notes: apps/rocm/src/runtime_registry.rs changes only to share the unusable_status_text helper with the listing and to add RuntimeProvenance::recorded_fields, from which fields is now derived (its output is unchanged). apps/rocm/src/dash.rs only gains a comment stating the dash's own matching rules and pointing at docs/json-output.md for the comparison. The branch merges main twice (#1106, #1090) rather than rebasing; main's scenarios keep runtime-lifecycle-19 to -22, so this PR's are -23 to -31.

Tests

  • Gherkin scenarios in tests/e2e-cucumber/features/runtime_lifecycle.feature, all on planted read-only runtimes with no GPU or network, run by the Linux E2E tests lane (ubuntu-24.04 and ubuntu-26.04):
    • @id:runtime-lifecycle-list-json-marks-active-and-rollback (runtime-lifecycle-23): the JSON flags, and that text markers and JSON flags mark the same runtimes.
    • @id:runtime-lifecycle-list-json-empty-registry (runtime-lifecycle-24).
    • @id:runtime-lifecycle-list-json-reports-unusable-runtime (runtime-lifecycle-25): a runtime whose folder is gone.
    • @id:runtime-lifecycle-list-json-reports-missing-active-manifest (runtime-lifecycle-26): an active key whose registry entry is gone.
    • @id:runtime-lifecycle-list-default-id-in-other-letter-case (runtime-lifecycle-27): a default id set in other letter case through rocm config set-default-runtime is active with no problem, in both JSON and text.
    • @id:runtime-lifecycle-list-active-key-in-other-letter-case (runtime-lifecycle-28): an active key edited to other letter case marks that runtime active with no problem in both forms, and rocm examine --json reports the same runtime's folder as active_runtime_root.
    • @id:runtime-lifecycle-list-dead-active-key-falls-back-to-default (runtime-lifecycle-29): an active key naming no runtime marks the default-id runtime active, reports missing_manifest_for_key in the JSON and the matching active_status: line in the text, and rocm examine --json reports that runtime's folder.
    • @id:runtime-lifecycle-list-json-failure-prints-nothing-on-stdout (runtime-lifecycle-30): the failure path. A registry entry is replaced by a folder of the same name, which the listing cannot read on any platform or as root (an entry that reads but does not parse is skipped by design, so it cannot stand in); --json exits 1 with nothing on stdout and a plain-text error on stderr naming that entry.
    • @id:runtime-lifecycle-list-json-names-runtime-provenance (runtime-lifecycle-31): the provenance object for a planted nightly runtime with an exact GPU target, an older one that recorded neither layout nor target (null), and an adopted one (source is null), compared fact by fact with the text listing of the same state. It sets ROCM_CLI_DISABLE_STARTUP_UPDATE_CHECK because of the known limitation under Scope.
  • The default text listing stays covered by the existing @id:runtime-lifecycle-list-shows-marker-legend (runtime-lifecycle-07), and the text provenance: line by main's @id:runtime-lifecycle-list-names-runtime-provenance (runtime-lifecycle-22).
  • Unit-only coverage, stated plainly:
    • the listing_state_* tests in runtimes_cmd.rs are a state matrix built in memory, one test per row (no config; active key exact, in other case, or dead with the default id resolving one, none or several; no active key with the default id matching none, one, one in other case, two, or two differing in case; case-twin keys; previous key exact, in other case, as a runtime id, with whitespace, missing, ambiguous, or naming one case twin exactly; a dead key falling back onto the rollback target). Each checks the JSON flags, active_problem, the text markers and the active_status: line, and that active/rollback_target equal what current_runtime_manifest/select_runtime_manifest return. Case-twin keys are only reachable on a case-sensitive filesystem, which is why these rows are in memory rather than e2e;
    • runtimes_list_json_names_recorded_provenance_and_null_for_unrecorded pins the whole provenance object for a nightly, an older, an adopted, a tarball, a padded and an all-blank runtime; runtimes_list_text_and_json_name_the_same_provenance checks the text line and the JSON object agree for each;
    • runtimes_list_json_writes_a_non_utf8_path_lossily (Unix only) for the lossy paths;
    • runtime_toolchain_text_and_json_words_agree_for_every_variant for the toolchain words;
    • the exact key set (including provenance's) and the newest-install-first sort tie-break, by runtimes_list_json_has_exactly_the_documented_fields_newest_install_first and the property test registry_sort_is_newest_install_first_then_by_key;
    • the bare --json rejection, by runtimes_json_is_a_list_flag.
  • Shown to fail with their target broken: scenarios 23 to 27 and their unit tests (the default-id rule, the rollback flag, renaming active, unusable_reason, marker precedence, the text glyphs and the sort tie-break); scenario 30 when the error path printed {} on stdout; scenario 31 and the provenance unit tests when the JSON wrote unrecorded instead of null and when it dropped source. The tests added for the resolver alignment, the lossy paths and the toolchain enum (listing_state_*, scenarios 28 and 29, the non-UTF-8 and toolchain tests) have not been through that exercise.

Verification

Passed locally on Linux on the final tree: cargo fmt --check; cargo clippy --workspace --all-targets -- -D warnings and the e2e test target with -D warnings; cargo test -p rocm --bin rocm; the xtask e2e_prewarm tests; cargo xtask check-architecture-doc, check-module-size and check-crate-edges; feature_naming and skill_reference; cargo xtask e2e for runtime-lifecycle-01 to -11 and -13 to -31, and examine-54; the prek hooks (including lychee) on the changed files.

Not verified locally:

  • runtime-lifecycle-12 (@requires-gpu, real SDK download) was not run.
  • cargo test --workspace passed apart from three tests that fail on the development host for reasons outside this change: a Docker-dependent service_control test, and two build_script git-watch tests affected by the host's global git configuration.
  • cargo xtask smoke, cargo xtask coverage and the Sphinx docs build were not run; CI is the authoritative check for them.
  • Windows was not exercised locally. The per-PR Windows lane runs the unit tests but not these scenarios; if they are run on Windows, the path comparisons in scenarios 23, 25, 28, 29 and 30 are the part to watch.

Checklist

  • If this PR fixes a bug, searched tests/e2e-cucumber/expectations.toml for the fixed ticket ID and removed/narrowed any now-stale xfail rows. (No rows reference this ticket or these scenarios.)
  • If this PR adds a new subcommand or subsystem, its domain implementation lives in its own file per docs/architecture.md (the clap declaration in cli.rs and the dispatch wiring in main.rs/lib.rs are expected, not a violation). (A flag on an existing subcommand; the listing lives in runtimes_cmd.rs.)
  • If this PR adds, renames or removes a production source file (or a .rs file under xtask/src or tests/e2e-cucumber), docs/architecture.md has the matching entry (cargo xtask check-architecture-doc fails otherwise), and the prose of any entry whose file changed role still describes it, which the check cannot verify. (No files added; the runtimes_cmd.rs and runtime_lifecycle_steps.rs entries are updated.)
  • Every new or changed user-facing message was read against the code path that runs after it, and its test asserts the resulting state — not only the wording — per AGENTS.md §3. Covers claims of an outcome, remediation advice naming a command, and promises that something will not happen. (Scenario 27 asserts the removed false line together with the active state in both forms; scenario 29 asserts the active_status: line together with the active runtime and what rocm examine reports; scenario 30 asserts the documented promise of nothing on stdout on failure together with the exit code.)
  • Comments and doc lines this PR adds or changes that state how the code behaves were checked against that code, and each that is the reason for a decision names the file and the function, constant or test that makes it true (AGENTS.md §3). (Not audited line by line against this item. The stdout-exception paragraph in docs/json-output.md was checked against refresh_startup_update_check_quietly and progress_line and reproduced; it and the comment on scenario 31 name the startup update check and its variable but not those functions.)
  • Any existing scenario this PR moves off the blocking mock e2e job (for example by a tag) is justified as a deletion (AGENTS.md §8). (No existing scenario's tags change; all new scenarios run on the mock lane.)
  • Commits answering review feedback were diffed whole against the reviewed head and widen no documented user-facing option's meaning or authority (AGENTS.md §11). (provenance is an added JSON field; no option changes meaning.)
  • Every commit message on the branch describes what its own commit does in words still true at the branch head (AGENTS.md §5). (One exception by numbering only: 96cd2e22 names its scenario runtime-lifecycle-29, its number at that commit; the merge 7836b920 records its move to -30.)

Scripts that want the registered runtimes, which one is active and
which is the rollback target currently have to scrape the text table
and its `*`/`-` markers. `rocm runtimes list --json` prints the same
listing as one JSON document on stdout, through the shared JsonOrText
helper.

The listing is now computed once into a value and both forms render
from it, so the JSON `active`/`rollback_target` flags and the text
markers cannot disagree. Unset values are null in the JSON, and the
empty-registry next-step hint stays text-only.

The text output of `rocm runtimes list` is unchanged except where
`default_runtime_id` matches a runtime id only when letter case is
ignored. The listing now applies one default-id rule, ASCII case
ignored, to both the active marker and the problem report: the false
"missing manifest for active_runtime_id" line printed next to an
active runtime is gone, and runtime ids that differ only in case now
report an ambiguous-runtime line instead.

docs/json-output.md audits `--json` support per command family, states
the rules those commands follow (stdout carries only the document,
errors stay on stderr, documented fields change only additively), and
records where the listing still differs from the resolver `rocm
examine` uses. Whether to adopt a shared envelope across commands is
left open there.

Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor
Security scan found no critical or high findings on lines changed by this pull request

View the security scan run for complete reports.

“New” means the finding is located in a changed file on an added or modified line; it is not a base-versus-head findings delta.

@rominf
rominf marked this pull request as ready for review November 16, 2026 15:35
@rominf
rominf requested a review from a team as a code owner November 16, 2026 15:35
@rominf
rominf requested a review from juhovainio November 16, 2026 15:35

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I went through this PR and found nothing that blocks merging. There are a few things I'd like fixed before the JSON shape is published as additive-only, so I'm requesting changes. They are left as inline comments, and the first two matter most.

Worth fixing before this ships

  1. active, rollback_target and active_runtime_id follow the listing's own matching rules, not the resolver that examine/activate/rollback use. active_runtime_id is also the configured default id, not the active runtime's id. The PR documents this, but also says aligning later is a contract change, so the cheapest time to align or rename is now.
  2. --json errors out with empty stdout when a path is not valid UTF-8, while the text form works.
  3. toolchain is a bare &'static str, while mode got an enum with an agreement test. A wording change in the helper would silently change the documented JSON values.
  4. docs/json-output.md says failures exit 1 unless documented, but clap usage errors exit 2.
  5. The comment added in dash.rs describes three other modules and will drift.

Things I checked that look fine

  • Text and JSON render from one computed value through the shared JsonOrText helper, so the text marker and the JSON flag can't disagree.
  • Scenarios 19-23 cover the user-visible behavior. Scenario 23 asserts the removed false message together with the resulting state.
  • The case-only default-id change to the text output is disclosed in the PR body. Please confirm it's intended.
  • The shared envelope and failure-path JSON are explicitly deferred, so this shouldn't be read as closing ROCMAI-148.
  • Required CI jobs are green on 6868e6e. The MI300X E2E and CodeQL (rust) were still pending when I looked. I did not build or run anything locally.

Comment thread apps/rocm/src/runtimes_cmd.rs Outdated
/// `default_runtime_id` from the config, as configured; `null` when unset.
/// Not necessarily the active runtime's `runtime_id`: an `active_runtime_key`
/// takes precedence, and the id may differ in letter case or match nothing.
active_runtime_id: Option<String>,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

active_runtime_id is the configured default id, not the active runtime's id, and active/rollback_target follow listing-only matching rules that differ from the resolver examine/activate use. The PR states this and that aligning later would be a non-additive contract change. Worth aligning (or renaming/omitting this field) before the shape is published as additive-only.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aligned rather than documented, in 70b3926. The listing no longer has matching rules of its own: active is the runtime current_runtime_manifest returns (the resolver rocm examine, activate, rollback, uninstall and update use), and rollback_target is what select_runtime_manifest resolves previous_runtime_key to, i.e. what rocm runtimes rollback would select. The resolvers themselves are unchanged. active_problem uses the same matching, and still reports missing_manifest_for_key for a dead active key even when the default id fallback marks a runtime active.

The JSON field is renamed default_runtime_id, since it is the config value; the text label stays active_runtime_id: as in rocm examine.

This moves some text markers in hand-edited or case-twin states (e.g. an active key in other letter case now gets * and loses its false active_status: line; case-twin keys mark the first in list order, the one the commands act on). The exact list is under "Text output changes" in the PR body; every other state is byte-identical. The listing state matrix (listing_state_*) checks each row against both resolvers, and scenarios runtime-lifecycle-24 and -25 cross-check the marked runtime against rocm examine --json.

The rocm dash runtime manager, rocm setup status and rocm engines install (without --runtime-id) still resolve with their own rules; they are listed under "Known differences" in docs/json-output.md and aligning them is follow-up work.

active_runtime_id: Option<String>,
active_runtime_key: Option<String>,
previous_runtime_key: Option<String>,
registry: PathBuf,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

serde serializes PathBuf through to_str() and errors on non-UTF-8, so --json would fail (empty stdout) for a non-UTF-8 data dir while the text form works. Consider to_string_lossy Strings for registry/marker/install_root, or document it.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 70b3926: registry, marker and install_root now serialize through to_string_lossy, so a non-UTF-8 path is written with U+FFFD (the same replacement the text form prints via Path::display) instead of --json failing with empty stdout. docs/json-output.md says so, including that such a path cannot be passed back to the filesystem from the JSON as it stands. Covered by runtimes_list_json_writes_a_non_utf8_path_lossily (Unix only), which lists a data folder whose path is not valid UTF-8.

Comment thread apps/rocm/src/runtimes_cmd.rs Outdated
#[serde(flatten)]
usability: RuntimeUsability,
/// `included` or `excluded`, the words `toolchain_state_text` uses.
toolchain: &'static str,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mode got an enum with a text/JSON agreement test, but toolchain is a bare &'static str from toolchain_state_text, so a wording change there silently changes the documented JSON values. An enum with serde rename plus the same agreement test would pin it.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 70b3926: toolchain is now a RuntimeToolchain enum serialized as included/excluded, and its text form goes through toolchain_state_text (the words rocm examine prints). runtime_toolchain_text_and_json_words_agree_for_every_variant ties the two together for every variant, as the mode test does, so a wording change in the helper now fails a test instead of silently changing the JSON.

Comment thread apps/rocm/src/dash.rs Outdated
// Mirror `render_runtimes_text`: a runtime is active by an explicit
// active_runtime_key, or — absent one — by being the single manifest whose
// runtime_id matches the configured default_runtime_id.
// Which runtime is active is governed by `current_runtime_manifest`

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment describes the behaviour of three other modules; it will drift (AGENTS.md section 5). Consider keeping it to what the dash does and pointing at docs/json-output.md for the comparison.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Trimmed in 70b3926: the comment now states only the dash's own matching rules (exact active key; otherwise the single runtime whose id equals the default id; exact previous key) and points at docs/json-output.md, whose "Known differences" list is the one place comparing them with what rocm runtimes list marks.

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent pass over the current head (6868e6e). CI is fully green now — the two checks still pending at the last review (MI300X E2E, CodeQL (rust)) have since completed successfully, and I see no failing required checks.

This substantially corroborates the existing review rather than contradicting it:

  • Confirmed: toolchain has no text/JSON agreement test. mode is pinned by runtime_mode_text_and_json_words_agree_for_every_variant against every RuntimeMode variant, but toolchain comes from toolchain_state_text (a bare &'static str) with nothing tying its JSON string to the documented contract. A wording change there would silently change the published shape.
  • Confirmed, and worth sharpening: the exit-code note. docs/json-output.md says a failing --json command exits non-zero (1, unless documented), written against a documented --json command's own execution failure. Clap's own usage-error exit (2) isn't carved out, and that's reachable on any --json command, not just the bare rocm runtimes --json case — a typo'd flag on an actual --json command (e.g. rocm examine --json --bogus) looks the same to a script as "the command failed," and also exits 2.
  • Confirmed, and slightly broader: the dash.rs comment drift risk. The same three-way comparison (dash's own exact-match rules vs. the resolver's case-insensitive rules vs. the listing's own rules) is now independently restated in both the dash.rs comment and docs/json-output.md's "Known limitation" section, with nothing tying the two descriptions together if either underlying rule changes later.
  • Agree, with the same framing already in the PR: the active/rollback_target/default-id matching-rule mismatch against the resolver is real and present in runtimes_listing, but it's explicitly documented and tested today. I'd treat it as the design decision already on the table (align/rename before the shape locks additive-only) rather than a separate defect.
  • Narrower than stated: the non-UTF-8 path concern. PathBuf fields here would indeed fail JSON serialization for a non-UTF-8 path, but that's the same pattern already in use elsewhere under JsonOrText (e.g. RuntimeUsage::install_root), so this extends an existing, accepted limitation to a new command rather than introducing a new one.

One gap I didn't see raised, left inline: none of the new scenarios exercise the "errors are not JSON" rule for runtimes list --json itself — all of 19-23 are success-path.

No new blocking defects beyond what's already open, and there's already an unresolved change-request review on this exact commit, so I'm leaving this as a comment rather than a second approval or change request.

🤖 Automated by an AI agent

Comment thread docs/json-output.md
progress and warnings go to stderr. A command that has no single document to
print is listed below as unsupported rather than given a `--json` that mixes
the two.
- **Errors are not JSON today.** A command that fails with `--json` prints its

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This "errors are not JSON" rule isn't exercised for rocm runtimes list --json itself — scenarios 19-23 are all success-path (active/rollback flags, empty registry, unusable runtime, missing manifest, case-insensitive default id). Nothing asserts that a failing load (e.g. an unreadable registry file) prints nothing on stdout and a plain error on stderr for this command, the way sibling commands in the table above are covered. Worth a scenario or a unit test pinning that contract for the new flag too.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added in 96cd2e2: scenario runtime-lifecycle-30 (@id:runtime-lifecycle-list-json-failure-prints-nothing-on-stdout; it was numbered 29 in that commit and moved to 30 when the merge 7836b92 brought in main's provenance scenario). It replaces a registry entry with a folder of the same name so the load fails, then asserts exit code 1, an empty stdout, and a stderr that does not parse as JSON and names that entry (failed to read …). It uses an unreadable entry rather than an unparseable one because an entry that reads but does not parse is skipped by design, so it would not fail the list; a folder in place of the file cannot be read on any platform or as root. The scenario went red when the error path was changed to print {} on stdout.

Related, and pre-existing on main: the startup update check that runs before most commands can print a Python progress line on stdout ahead of any --json document (on the first run in a check interval, for a wheel runtime whose recorded Python is not usable and whose fallback Python does not fit). dec432b documents that exception in docs/json-output.md, with ROCM_CLI_DISABLE_STARTUP_UPDATE_CHECK as the way to turn it off; moving that line off stdout is a follow-up.

`rocm runtimes list` decided which runtime was active and which was the
rollback target by rules of its own, so it could mark a runtime other
than the one `rocm examine`, `rocm runtimes activate`, `rollback`,
`uninstall` and `rocm update` act on: an active key in other letter
case, a dead key whose default id still resolves, case-twin keys, or a
previous key that rollback trims, matches ignoring case or reads as a
runtime id.

The listing now asks the resolvers those commands use:
`current_runtime_manifest` for `active` and `select_runtime_manifest`
on `previous_runtime_key` for `rollback_target`. `active_problem`
reports the configuration with the same matching, so a dead active key
is still reported as `missing_manifest_for_key` while the runtime the
commands fall back to is marked active. The resolvers are unchanged.

In the JSON, `active_runtime_id` is renamed `default_runtime_id`, the
config value it carries; the text label stays `active_runtime_id:`.
`registry`, `marker` and `install_root` are written lossily, so a path
that is not valid UTF-8 no longer makes `--json` fail with empty
stdout. `toolchain` is an enum serialized with the words the text and
`rocm examine` print.

docs/json-output.md describes which runtimes are marked, lists the
surfaces that still resolve differently (the dash runtime manager,
`rocm setup status`, `rocm engines install`), and states the exit
codes: 1 for a failed command unless documented, 2 for a command line
the argument parser rejects. The dash comment keeps only the dash's
own rules and points there.

A state matrix of in-memory unit tests covers every configuration
row; scenarios runtime-lifecycle-24 and -25 check an active key in
other letter case and a dead key falling back to the default id, each
against `rocm examine --json`.

Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
@rominf

rominf commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator Author

Thanks for the review. Item 4 (exit codes) is fixed in 70b3926: docs/json-output.md now says a failing command exits 1 unless it documents its own code (as rocm fix does), and that a command line the argument parser rejects (an unknown flag such as --json on a command without one, or a missing argument) exits 2 with a usage message on stderr before the command runs.

Items 1, 2, 3 and 5 are answered in their inline threads, all in the same commit.

On the case-only default-id text change: yes, it is intended. With no active key, a default id that matches one runtime only when letter case is ignored is the runtime the commands act on, so the listing marks it * without the false missing-id line. Ids that differ only in letter case now report an ambiguous-runtime-id line. That state and the others whose markers moved with the resolver alignment are listed under "Text output changes" in the PR body.

Conflicts in apps/rocm/src/runtimes_cmd.rs (imports: both the listing's
unusable_status_text and main's relocated write_active_runtime_marker),
docs/architecture.md (both sides' descriptions of runtime_uninstall.rs,
runtimes_cmd.rs and the e2e step files), runtime_lifecycle.feature and its
steps (main's config_path/read_json_if_present helpers now back this
branch's config reads and edits).

Main's side-by-side scenarios keep runtime-lifecycle-19 to 21; this
branch's runtime list scenarios move from 19-25 to 22-28, with
docs/testing.md and docs/json-output.md updated to match.

Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
…when it fails (ROCMAI-148)

The JSON rules say a failing --json command prints its error to stderr,
nothing on stdout, and exits 1, but every runtimes list scenario was a
success path. Scenario runtime-lifecycle-29 replaces a registry entry
with a folder of the same name, which the listing cannot read on any
platform or as root (an entry that reads but does not parse is skipped,
so it cannot stand in), and checks exit 1, an empty stdout, and a
plain-text error naming that entry.

Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
Brings in #1090, which prints a `provenance:` line under each runtime in
`rocm runtimes list`. Conflicts were in cli.rs, runtimes_cmd.rs,
docs/architecture.md and runtime_lifecycle.feature.

The listing on this branch is a computed value that both the text and
the JSON render from, so main's provenance line is folded into it: each
entry keeps an owned copy of `InstalledRuntimeManifest::provenance`, and
the text renderer prints it through `RuntimeProvenance::fields` after
`install_root:`, in the position main's renderer and the e2e prewarm
expect. The text output equals main's for every state in which this
branch does not deliberately change the markers or the status line. The
field is kept out of the JSON here; it is added there separately.

The `list` help keeps main's provenance description beside the `--json`
flag. Main's provenance scenario keeps its number, runtime-lifecycle-22,
so this branch's JSON listing scenarios move from 22-29 to 23-30, with
the references in docs/testing.md and docs/json-output.md renumbered to
match. The architecture entry for the runtime-lifecycle steps describes
both sides' steps.

Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
The text listing names each runtime's channel, package source, source
layout generation and exact GPU target on its `provenance:` line, but
the JSON form left them out, so a script had to parse the text to learn
which stream or GPU a runtime was installed for.

Each runtime in `rocm runtimes list --json` now carries a `provenance`
object with the same four facts under the same names, as strings, or
`null` where the text prints `unrecorded`, so a script cannot take the
placeholder for a recorded value. The JSON takes its names and order
from a new `RuntimeProvenance::recorded_fields`, which `fields` (what the
text and `rocm examine` print) is now derived from, so the two forms
cannot name the facts differently.

Unit tests pin the object for recorded, unrecorded, blank and padded
values, check that the text line and the JSON object agree for each
runtime, and add the object to the exact-key-set contract test. Scenario
runtime-lifecycle-31 reads the provenance from the JSON for planted
nightly, older and adopted runtimes and compares it with the text
listing. It turns the startup update check off, as the examine
scenarios do, because with wheel runtimes registered that check can
print a progress line on stdout ahead of the document. README,
docs/json-output.md, docs/testing.md and docs/manual-testing.md describe
the field.

Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
…aced test comment (ROCMAI-148)

docs/json-output.md promises that --json leaves only the document on
stdout. The startup update check that runs before most commands can
still print a Python progress line on stdout first, once per check
interval, when the runtime it checks is a wheel install whose recorded
Python is unusable and the Python it finds instead does not fit.
State that exception and the variable that turns the check off, so a
script author knows about it until the follow-up moves the line.

Also move the doc comment of the active-and-rollback-target list test
back above that test; the provenance fixture helper had been inserted
between them.

Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
@rominf

rominf commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator Author

Branch updated by merging main rather than rebasing, so the reviewed commits and the review threads keep their anchors:

New head: dec432b. The PR description is updated to match.

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent re-review at the current head (dec432b), after reading the full diff against main (production code, tests, and docs) directly and cross-checking against the resolver functions it claims to align with.

The five points from the earlier change-request review, plus the one coverage gap noted since, are all genuinely fixed here, not just documented as fixed:

  1. active/rollback_target now come from calling the live resolver functions directly (current_runtime_manifest/select_runtime_manifest in runtime_registry.rs), matched back to each manifest by std::ptr::eq position — not a separate matching implementation. Traced the position-matching for the aliasing bug this pattern invites (manifests reordered between index computation and consumption): no issue, the same unmoved Vec is used throughout, and sorting happens earlier in the registry loader. active_runtime_problem reproduces the resolver's key-matching step in isolation (clone + clear default_runtime_id) rather than re-deriving its own rule. The listing_state_* matrix (~24 rows) and its assert_listing_state helper cross-check this against the resolvers directly, including case-twin states impossible to construct on a case-insensitive filesystem — this is good, rigorous test design.
  2. Non-UTF-8 paths: registry/marker/install_root serialize via to_string_lossy (serialize_path_lossy), not serde's own Path impl which errors on invalid UTF-8. Covered by runtimes_list_json_writes_a_non_utf8_path_lossily.
  3. toolchain is now a real RuntimeToolchain enum (Included/Excluded) with a text/JSON agreement test (runtime_toolchain_text_and_json_words_agree_for_every_variant) analogous to mode's.
  4. docs/json-output.md now correctly distinguishes a failing --json command's exit 1 from a clap usage error's exit 2, and that's backed by pre-existing, tested exit-code plumbing (ClapExitCode/exit_code_for).
  5. The dash.rs comment now states only the dash's own matching rules and points at docs/json-output.md for the cross-module comparison, instead of describing three other modules inline.
  6. The previously-missing "errors are not JSON" scenario for runtimes list --json itself now exists (runtime-lifecycle-30) and its steps assert exit code 1, exactly-empty stdout, and that stderr fails to parse as JSON while naming the specific unreadable entry — not just "an error happened."

I also had three independent blind passes (no access to this PR's description or review threads) separately cover (a) the production code in runtimes_cmd.rs/runtime_registry.rs/dash.rs/cli.rs, (b) every new/changed unit test and e2e scenario with revert/break reasoning, and (c) the docs against the code. Between those and my own reading, no blocking defects surfaced. The Serialize impls for RuntimeListingProvenance/RuntimeUsability are correct (including under #[serde(flatten)]), the exact-field-set test (runtimes_list_json_has_exactly_the_documented_fields_newest_install_first) guards the shape with a deliberately order-scrambled fixture, and the provenance tests hand-trace the trim/blank-filter behavior through realistic fixtures (padded, all-blank, adopted, tarball).

One small, non-blocking finding left inline: docs/json-output.md's "Known differences" section describes rocm dash/rocm setup status/rocm engines install's own matching rules without naming the function that makes each claim true, unlike the rest of the document (which names current_runtime_manifest/select_runtime_manifest by symbol throughout) — and the engines install bullet undersells that it calls select_runtime_manifest directly, not merely something resembling it.

CI is green at this head (all required checks completed/success; CodeQL rust/general and the two Linux/Windows E2E lanes passed). One self-hosted E2E tests (MI300X, current) job was still queued at the time of this review — not failing, just not yet started; worth a glance before merge but not a blocker on its own.

No new blocking issues found. Approving.

🤖 Automated by an AI agent

Comment thread docs/json-output.md
`ambiguous_runtime_id`.
- `rocm setup status` looks `active_runtime_key` up ignoring letter case but
does not fall back to `default_runtime_id`.
- `rocm engines install` without `--runtime-id`, for an engine that runs on the

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpick, non-blocking: unlike every other claim in this doc (which names its symbol, e.g. "the resolver they use (current_runtime_manifest in runtime_registry.rs...)" and "(select_runtime_manifest, same file)" a few paragraphs up), the three "Known differences" bullets above and below describe rocm dash, rocm setup status and rocm engines install's matching behavior without naming the function that makes each claim true — runtime_summaries (apps/rocm/src/dash.rs), render_setup_status_text (apps/rocm/src/setup_cmd.rs), and for this bullet specifically, resolve_runtime_selector_to_exact_key (apps/rocm/src/engine_runtime_select.rs:219).

That last one is also slightly undersold: it doesn't just resolve "the way rollback resolves a key" — it calls select_runtime_manifest directly, the identical function this doc already names by symbol for rollback_target. Worth naming the three symbols here so this section can't silently drift the way the old dash.rs comment it replaces could have (and per this repo's own AGENTS.md §3, on naming where a decision-describing claim is made true).

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, and confirmed against the code: the three bullets are made true by runtime_summaries (apps/rocm/src/dash.rs), render_setup_status_text (apps/rocm/src/setup_cmd.rs) and resolve_runtime_selector_to_exact_key (apps/rocm/src/engine_runtime_select.rs), and the last one calls select_runtime_manifest directly rather than merely resolving "the way rollback does". I'm not pushing that edit onto the approved head; it goes into the follow-up that aligns those three surfaces with the listing, which will rewrite this section anyway, and the symbols will be named there.

@rominf
rominf added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit bfff521 Nov 17, 2026
45 of 46 checks passed
@rominf
rominf deleted the ROCMAI-148-feat-runtimes-list-json branch November 17, 2026 15:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants