Repository navigation
feat(runtimes): add --json to rocm runtimes list (ROCMAI-148) - #1098
Conversation
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>
Security scan found no critical or high findings on lines changed by this pull requestView 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. |
juhovainio
left a comment
There was a problem hiding this comment.
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
active,rollback_targetandactive_runtime_idfollow the listing's own matching rules, not the resolver thatexamine/activate/rollbackuse.active_runtime_idis 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.--jsonerrors out with empty stdout when a path is not valid UTF-8, while the text form works.toolchainis a bare&'static str, whilemodegot an enum with an agreement test. A wording change in the helper would silently change the documented JSON values.- docs/json-output.md says failures exit 1 unless documented, but clap usage errors exit 2.
- 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
JsonOrTexthelper, 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.
| /// `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>, |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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, |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| #[serde(flatten)] | ||
| usability: RuntimeUsability, | ||
| /// `included` or `excluded`, the words `toolchain_state_text` uses. | ||
| toolchain: &'static str, |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| // 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` |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
left a comment
There was a problem hiding this comment.
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:
toolchainhas no text/JSON agreement test.modeis pinned byruntime_mode_text_and_json_words_agree_for_every_variantagainst everyRuntimeModevariant, buttoolchaincomes fromtoolchain_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.mdsays a failing--jsoncommand exits non-zero (1, unless documented), written against a documented--jsoncommand's own execution failure. Clap's own usage-error exit (2) isn't carved out, and that's reachable on any--jsoncommand, not just the barerocm runtimes --jsoncase — a typo'd flag on an actual--jsoncommand (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.
PathBuffields here would indeed fail JSON serialization for a non-UTF-8 path, but that's the same pattern already in use elsewhere underJsonOrText(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
| 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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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>
|
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 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 |
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>
|
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
left a comment
There was a problem hiding this comment.
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:
active/rollback_targetnow come from calling the live resolver functions directly (current_runtime_manifest/select_runtime_manifestinruntime_registry.rs), matched back to each manifest bystd::ptr::eqposition — 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 unmovedVecis used throughout, and sorting happens earlier in the registry loader.active_runtime_problemreproduces the resolver's key-matching step in isolation (clone + cleardefault_runtime_id) rather than re-deriving its own rule. Thelisting_state_*matrix (~24 rows) and itsassert_listing_statehelper 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.- Non-UTF-8 paths:
registry/marker/install_rootserialize viato_string_lossy(serialize_path_lossy), not serde's ownPathimpl which errors on invalid UTF-8. Covered byruntimes_list_json_writes_a_non_utf8_path_lossily. toolchainis now a realRuntimeToolchainenum (Included/Excluded) with a text/JSON agreement test (runtime_toolchain_text_and_json_words_agree_for_every_variant) analogous tomode's.docs/json-output.mdnow correctly distinguishes a failing--jsoncommand'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).- The
dash.rscomment now states only the dash's own matching rules and points atdocs/json-output.mdfor the cross-module comparison, instead of describing three other modules inline. - The previously-missing "errors are not JSON" scenario for
runtimes list --jsonitself 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
| `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 |
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.
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 listtext table, its*/-markers and itsprovenance: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,uninstallandrocm updateactually act on.What changes
rocm runtimes list --jsonprints the listing as one JSON document on stdout through the sharedJsonOrText/print_json_or_text: each runtime's key, id, version, format, family, mode, status, toolchain, install root and provenance,activeandrollback_targetflags in place of the markers, and whether it is usable (unusable_reason). The top level carriesdefault_runtime_id,active_runtime_key,previous_runtime_key, the registry and marker paths, andactive_problem. Unset values arenull. 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.provenanceis an object with the four facts the text prints on itsprovenance:line, under the same names:channel,source,source_layout_generationanddevice_target. Each is the recorded value (trimmed), ornullwhere the text printsunrecorded(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'sRuntimeProvenance::fieldsis now derived from, so the two forms cannot name the facts differently.activeis the runtimecurrent_runtime_manifestresolves, the resolverrocm examine,activate,rollback,uninstallandupdateuse;rollback_targetis the runtimeselect_runtime_manifestresolvesprevious_runtime_keyto, which is whatrocm runtimes rollbackselects (a value rollback would refuse, as missing or ambiguous, marks nothing). The resolvers themselves are unchanged.active_problemreports the configuration by the same matching:missing_manifest_for_keywhenactive_runtime_keynames no runtime (letter case ignored),missing_manifest_for_id/ambiguous_runtime_idfordefault_runtime_idwhen no active key is set. A dead active key is still reported asmissing_manifest_for_keywhen 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.default_runtime_id, since it is the config value and not necessarily the active runtime's id. The text label staysactive_runtime_id:, as inrocm examine.registry,markerandinstall_rootare written withto_string_lossy, so a path that is not valid UTF-8 is listed with U+FFFD (as the text form prints it) instead of--jsonfailing with empty stdout.toolchainis an enum serialized asincluded/excluded, the words the text androcm examineprint, pinned by an agreement test likemode.--jsonis onlistonly;rocm runtimes --json(bare) is rejected by the parser rather than read aslist --json.docs/json-output.mdaudits--jsonper 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.mdanddocs/architecture.mdare updated to match.Text output changes
Compared with
origin/main,rocm runtimes listtext 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_status: missing manifest for active_runtime_key=…line is removed, and that runtime gains*.*.*).*goes to the first of them in list order, the one the commands act on.-.-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
--jsonon mutating commands (activate,rollback,uninstall,import,adopt, service and install commands). The envelope would change the shapes of the frozenrocm examineandrocm fixcontracts, so it needs an owner decision;docs/json-output.mdleaves it as an open decision.Known limitation, recorded in
docs/json-output.mdand tracked as a follow-up: the startup update check that runs before most commands (refresh_startup_update_check_quietlyinapps/rocm/src/main.rs) prints its Python progress line throughprogress_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 asPython from PATH is not usable for this ROCm install (… is required).precedes the document of any--jsoncommand. This predates this PR and was reproduced withrocm runtimes list --jsonon a planted wheel runtime.ROCM_CLI_DISABLE_STARTUP_UPDATE_CHECKturns the check off; scenarioruntime-lifecycle-31sets 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:rocm dashmatches the active key, the default id and the previous key exactly;rocm setup statuslooks the active key up ignoring letter case but does not fall back to the default id;rocm engines installwithout--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.rschanges only to share theunusable_status_texthelper with the listing and to addRuntimeProvenance::recorded_fields, from whichfieldsis now derived (its output is unchanged).apps/rocm/src/dash.rsonly gains a comment stating the dash's own matching rules and pointing atdocs/json-output.mdfor the comparison. The branch merges main twice (#1106, #1090) rather than rebasing; main's scenarios keepruntime-lifecycle-19to-22, so this PR's are-23to-31.Tests
tests/e2e-cucumber/features/runtime_lifecycle.feature, all on planted read-only runtimes with no GPU or network, run by the LinuxE2E testslane (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 throughrocm config set-default-runtimeis 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, androcm examine --jsonreports the same runtime's folder asactive_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, reportsmissing_manifest_for_keyin the JSON and the matchingactive_status:line in the text, androcm examine --jsonreports 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);--jsonexits 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): theprovenanceobject for a planted nightly runtime with an exact GPU target, an older one that recorded neither layout nor target (null), and an adopted one (sourceisnull), compared fact by fact with the text listing of the same state. It setsROCM_CLI_DISABLE_STARTUP_UPDATE_CHECKbecause of the known limitation under Scope.@id:runtime-lifecycle-list-shows-marker-legend(runtime-lifecycle-07), and the textprovenance:line by main's@id:runtime-lifecycle-list-names-runtime-provenance(runtime-lifecycle-22).listing_state_*tests inruntimes_cmd.rsare 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 theactive_status:line, and thatactive/rollback_targetequal whatcurrent_runtime_manifest/select_runtime_manifestreturn. 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_unrecordedpins the wholeprovenanceobject for a nightly, an older, an adopted, a tarball, a padded and an all-blank runtime;runtimes_list_text_and_json_name_the_same_provenancechecks 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_variantfor the toolchain words;provenance's) and the newest-install-first sort tie-break, byruntimes_list_json_has_exactly_the_documented_fields_newest_install_firstand the property testregistry_sort_is_newest_install_first_then_by_key;--jsonrejection, byruntimes_json_is_a_list_flag.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 wroteunrecordedinstead ofnulland when it droppedsource. 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 warningsand the e2e test target with-D warnings;cargo test -p rocm --bin rocm; the xtaske2e_prewarmtests;cargo xtask check-architecture-doc,check-module-sizeandcheck-crate-edges;feature_namingandskill_reference;cargo xtask e2eforruntime-lifecycle-01to-11and-13to-31, andexamine-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 --workspacepassed apart from three tests that fail on the development host for reasons outside this change: a Docker-dependentservice_controltest, and twobuild_scriptgit-watch tests affected by the host's global git configuration.cargo xtask smoke,cargo xtask coverageand the Sphinx docs build were not run; CI is the authoritative check for them.Checklist
tests/e2e-cucumber/expectations.tomlfor the fixed ticket ID and removed/narrowed any now-stale xfail rows. (No rows reference this ticket or these scenarios.)docs/architecture.md(the clap declaration incli.rsand the dispatch wiring inmain.rs/lib.rsare expected, not a violation). (A flag on an existing subcommand; the listing lives inruntimes_cmd.rs.).rsfile underxtask/srcortests/e2e-cucumber),docs/architecture.mdhas the matching entry (cargo xtask check-architecture-docfails otherwise), and the prose of any entry whose file changed role still describes it, which the check cannot verify. (No files added; theruntimes_cmd.rsandruntime_lifecycle_steps.rsentries are updated.)active_status:line together with the active runtime and whatrocm examinereports; scenario 30 asserts the documented promise of nothing on stdout on failure together with the exit code.)docs/json-output.mdwas checked againstrefresh_startup_update_check_quietlyandprogress_lineand reproduced; it and the comment on scenario 31 name the startup update check and its variable but not those functions.)e2ejob (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.)provenanceis an added JSON field; no option changes meaning.)96cd2e22names its scenarioruntime-lifecycle-29, its number at that commit; the merge7836b920records its move to-30.)