Repository navigation
ROCMAI-850: move the engine runtime and env-root helpers out of engines_cmd.rs to break the import cycle with runtime_install_finalize.rs - #872
Conversation
…es_cmd.rs engines_cmd.rs imported four helpers from runtime_install_finalize.rs while runtime_install_finalize.rs imported four others from engines_cmd.rs, both outside the test modules, so the two modules formed a production import cycle. The helpers runtime_install_finalize.rs needs (engine_manages_own_runtime, env_root_for_engine_install, runtime_key_for_python and, from its torch-alignment child, runtime_manifest_for_selector) now live in a neutral engine_install_env.rs together with what they depend on (env_root_for_runtime, env_root_for_self_managed_engine and the private runtime_key_owning_python). engines_cmd.rs, runtime_install_finalize.rs, serve_cmd.rs and runtime_services.rs import them from there, and main.rs no longer re-imports them. env_root_for_service and ensure_self_managed_engine_ready stay in engines_cmd.rs. The code and the five tests that exercise it move verbatim; behaviour is unchanged. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…alize relationship engines_cmd.rs claimed that main.rs re-imports env_root_for_engine_install, env_root_for_service and runtime_key_for_python and that the last two are used only from main.rs. Neither was true: the re-import was a different set, env_root_for_service is called from services_text.rs and service_launch.rs, and runtime_key_for_python from runtime_install_finalize.rs. The module doc now states what the module holds and where the helpers it used to hold live, and the comment block in main.rs no longer lists helpers it does not re-import. docs/architecture.md gains an entry for engine_install_env.rs and updates the engines_cmd.rs, runtime_install_finalize.rs and runtimes_cmd.rs entries, so the direction of each dependency matches the code. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
There was a problem hiding this comment.
🟡 Changes recommended
The helper module still creates a production import cycle through runtimes_cmd; import directly from runtime_adopt and runtime_registry and update the dependency documentation.
1 open issue
What changed in this PR
This refactor moves engine runtime and environment-root helpers into engine_install_env.rs, removing the direct import cycle between engine commands and runtime finalization while preserving behavior.
Changes:
- Relocates seven helpers, five tests, and their shared fixture into the new module.
- Updates callers to import helpers directly and removes unused crate-root re-imports.
- Revises module comments and architecture documentation to describe the extraction.
| File | Description |
|---|---|
docs/architecture.md |
Documents the extracted module and revised dependencies. |
apps/rocm/src/serve_cmd.rs |
Imports runtime ownership logic from the new module. |
apps/rocm/src/runtime_services.rs |
Replaces crate-root helper imports with direct imports. |
apps/rocm/src/runtime_install_finalize/torch_alignment.rs |
Redirects the runtime selector import. |
apps/rocm/src/runtime_install_finalize.rs |
Imports environment helpers from the extracted module. |
apps/rocm/src/main.rs |
Declares the module and removes obsolete re-imports. |
apps/rocm/src/engines_cmd.rs |
Removes relocated helpers and tests; updates imports and comments. |
apps/rocm/src/engine_install_env.rs |
Houses runtime/environment helpers and their existing tests. |
Review effort: Balanced
…not through runtimes_cmd engine_install_env.rs reached recover_setup_runtime_registration, select_runtime_manifest and validate_runtime_manifest_for_activation through the pub(crate) use re-exports in runtimes_cmd.rs. runtimes_cmd.rs calls into runtime_services.rs, which imports engine_install_env.rs, so that route kept a production import cycle alive. The helpers are now imported from where they are defined: recover_setup_runtime_registration from runtime_adopt.rs, and the other two from runtime_registry.rs. The module doc and the docs/architecture.md entry now say what the module imports and from where, instead of claiming nothing in runtimes_cmd.rs calls back. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
nowycondro
left a comment
There was a problem hiding this comment.
test probe 3 after backoff — ignore, will be replaced
nowycondro
left a comment
There was a problem hiding this comment.
(Note: my previous review on this PR, "test probe 3 after backoff — ignore, will be replaced", was accidental tool-debugging noise from a transient API error on my end while publishing — please disregard it entirely. This review is the actual content.)
Review — needs work
Full review of the whole change (8 files, +349/-306 across 3 commits: d407b89, ffe6495, d0144d7).
Completes ROCMAI-850 (confirmed against the ticket): move the engine-runtime/env-root helpers out of engines_cmd.rs into a new engine_install_env.rs to break its production import cycle with runtime_install_finalize.rs, and fix the module docs describing that relationship. The change's stated scope matches the ticket; ticket status is In Progress, consistent with this PR still being open.
Blocking
-
docs/architecture.md's own doc-accuracy fixes are internally inconsistent, and leave one entry stale —docs/architecture.md:67,docs/architecture.md:68,docs/architecture.md:72
This PR's second commit exists specifically to fix stale/incorrect module-relationship claims in this file, but three concrete errors remain, each verified directly against the actual code in this diff:- Line 67 (
runtime_install_finalize.rsentry, new text) sayssettle_engine_installis "read fromengines_cmd.rs" (i.e.engines_cmd.rsstill imports it), then claims two sentences later "so the two modules no longer import each other in production code." Self-contradictory:engines_cmd.rsstill hasuse crate::runtime_install_finalize::{ensure_libatomic_for_torch, ensure_libnuma_for_torch, ensure_openmpi_for_vllm, settle_engine_install};. Only the reverse edge was cut; the modules still import one another, just not mutually. - Line 68 (
torch_alignment.rsentry, unchanged by this diff) still says it depends onruntime_manifest_for_selector"inengines_cmd.rs". This PR's own diff changes that import inruntime_install_finalize/torch_alignment.rstocrate::engine_install_env::runtime_manifest_for_selector; this line should have moved with it. - Line 72 (
runtimes_cmd.rsentry) contradicts line 50 (engine_install_env.rsentry), both touched by this PR. Line 72 listsengine_install_env.rsas importing throughruntimes_cmd.rs's re-exports; line 50 says the opposite, and the code agrees with line 50 (use crate::runtime_adopt::recover_setup_runtime_registration;, a direct import). Per the PR's own rationale, routing throughruntimes_cmd.rshere would recreate a cycle viaruntime_services.rs, so line 72 describes a design that was deliberately avoided.
Confidence 85 (diffed
docs/architecture.mdagainst the actualusestatements inengines_cmd.rs,torch_alignment.rsandengine_install_env.rsat the PR head). Category: mechanical (doc-accuracy — the whole point of this commit). Fix: reword line 67 to describe a one-way edge; repoint line 68 atengine_install_env.rs; dropengine_install_env.rsfrom line 72's list. - Line 67 (
Non-blocking
None.
Decisions for the author
None.
Positive signals
- The two visibility bumps (
env_root_for_runtime,env_root_for_self_managed_engine: private →pub(crate)) are scoped to exactly the two remaining call sites inengines_cmd.rs— verified by grep, no broader visibility leak than necessary. - Importing
recover_setup_runtime_registration/select_runtime_manifest/validate_runtime_manifest_for_activationdirectly fromruntime_adopt.rs/runtime_registry.rsinstead of throughruntimes_cmd.rs's re-exports is the right call — the re-export route would have recreated a cycle viaruntime_services.rs. The code gets this right even though the docs describing it (see Blocking) don't consistently say so. - The moved test module (5 tests plus the shared
side_by_side_runtimesfixture) reads as a verbatim relocation intoengine_install_env.rs, with nothing left behind or duplicated.
Deployment notes
None — pure internal refactor, no behavior change, no new runtime dependency.
What this covered
Read completely: the new apps/rocm/src/engine_install_env.rs (309 lines, including its test module), the full removal diff in apps/rocm/src/engines_cmd.rs, and the import-only diffs in apps/rocm/src/main.rs, apps/rocm/src/runtime_install_finalize.rs, apps/rocm/src/runtime_install_finalize/torch_alignment.rs, apps/rocm/src/runtime_services.rs, apps/rocm/src/serve_cmd.rs and docs/architecture.md, plus surrounding content of engines_cmd.rs, runtimes_cmd.rs, runtime_registry.rs, runtime_adopt.rs and therock.rs needed to verify the import-cycle claim. Diffed against base 08235c55 at head d0144d797593df151b9368359fa05d4867e68629. Independently grepped the whole crate to confirm no production (non-test, non-comment) code still names engines_cmd from runtime_install_finalize.rs, torch_alignment.rs or runtime_services.rs, and that engine_install_env.rs's own imports don't lead back to engines_cmd, runtime_install_finalize, runtime_services or runtimes_cmd. Checked CI via the PR's status-check rollup: all 24 non-skipped checks are SUCCESS at this head (2 skipped: skill checks, Sphinx build — unrelated). Retrieved ROCMAI-850 from the tracker and compared its stated scope to the diff.
Two background passes covered this in parallel: one over engine_install_env.rs plus the engines_cmd.rs removal diff (verbatim-move/visibility verification — clean), one over the five caller/doc diffs (import correctness — clean; docs/architecture.md accuracy — the three issues above). Both workers' claims were independently re-verified by me directly against the diff and file content before inclusion, rather than taken secondhand.
Did not run: no local cargo build/test/clippy (no Rust toolchain in this review environment) — relied on the PR's green CI run instead, consistent with what the PR body reports running locally. Not reconciled against the existing Copilot review thread or the author's own review comment on this PR.
juhovainio
left a comment
There was a problem hiding this comment.
Looks good. The moved helpers are byte-identical to the originals, the only visibility change is pub(crate) on env_root_for_runtime and env_root_for_self_managed_engine, and the new module imports only runtime_adopt, runtime_registry and therock, so the engines_cmd <-> runtime_install_finalize cycle is gone. Callers now import from the defining modules instead of the runtimes_cmd re-exports. CI is green at this head.
Two small non-blocking items are inline: a stale torch_alignment.rs entry in docs/architecture.md, and a comment wrap nit in main.rs. This is a read of the diff plus CI status, not a local build.
| - [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs) — full domain extraction, crate-level (split out of [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs)): registering a runtime that `rocm install sdk` did not install. `import_runtime_manifest` records a manifest written elsewhere, `adopt_runtime_from_python_options` (with `AdoptRuntimeOptions`, `AdoptRuntimeRequest`, `infer_adopt_runtime_request` and `adopt_runtime_from_probe`) probes an existing Python environment and registers it, and `recover_setup_runtime_registration` registers the runtime `rocm setup` created, with `newest_installed_runtime_manifest` and `setup_runtime_paths` beside it. It depends on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) (manifest paths, activation validation, `paths_equivalent`) and `therock.rs`, not on `runtimes_cmd.rs`, which calls into it and re-exports `newest_installed_runtime_manifest`, `recover_setup_runtime_registration` and `setup_runtime_paths`. `import_runtime_manifest`, `AdoptRuntimeOptions`, `adopt_runtime_from_python_options` (with the fields of `AdoptRuntimeOptions` and `AdoptRuntimeRequest`) and `adopt_runtime_from_probe` are `pub(crate)` for `runtimes()` and for the `runtimes_cmd.rs` tests that adopt or import a runtime and then list or activate it; `newest_installed_runtime_manifest`, `recover_setup_runtime_registration` and `setup_runtime_paths` are `pub(crate)` too, for the modules that import them through `runtimes_cmd.rs`'s re-exports; the rest is private. Its tests cover the import and adopt rules that do not involve activation or listing. | ||
| - [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) — mechanical relocation, owns types (part of [`main.rs`](../apps/rocm/src/main.rs)'s Phase 6c split, ROCMAI-89, alongside [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) below): settling an engine onto a runtime after an SDK install: the orchestration (`finish_sdk_install`, `settle_engine_install`, `finalize_successful_sdk_install`), the engine-dependency check, the runtime device check and the post-install verdict built on it, and `SdkInstallConsents`. The torch alignment and retention it runs live in the child module [`runtime_install_finalize/torch_alignment.rs`](../apps/rocm/src/runtime_install_finalize/torch_alignment.rs). `SdkInstallConsents` is `pub(crate)` and read from `install_cmd.rs`'s `install()`; `settle_engine_install` is `pub(crate)` and read from [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs). The host system-package installs live in [`system_packages.rs`](../apps/rocm/src/system_packages.rs); this module re-exports `ensure_libatomic_for_torch`/`ensure_libnuma_for_torch` (called from both `install_cmd.rs`'s `install()` and `engines_cmd.rs`) and `ensure_openmpi_for_vllm` (called from `engines_cmd.rs` and, for the engine auto-install after an SDK install, from here) so those callers keep their imports. | ||
| - [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) — mechanical relocation, owns types (part of [`main.rs`](../apps/rocm/src/main.rs)'s Phase 6c split, ROCMAI-89, alongside [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) below): settling an engine onto a runtime after an SDK install: the orchestration (`finish_sdk_install`, `settle_engine_install`, `finalize_successful_sdk_install`), the engine-dependency check, the runtime device check and the post-install verdict built on it, and `SdkInstallConsents`. The torch alignment and retention it runs live in the child module [`runtime_install_finalize/torch_alignment.rs`](../apps/rocm/src/runtime_install_finalize/torch_alignment.rs). `SdkInstallConsents` is `pub(crate)` and read from `install_cmd.rs`'s `install()`; `settle_engine_install` is `pub(crate)` and read from [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs). It reaches the engine environment and runtime-selection helpers it needs (`engine_manages_own_runtime`, `env_root_for_engine_install`, `runtime_key_for_python`, and `runtime_manifest_for_selector` from the torch-alignment child) in [`engine_install_env.rs`](../apps/rocm/src/engine_install_env.rs), not in `engines_cmd.rs`, so the two modules no longer import each other in production code. The host system-package installs live in [`system_packages.rs`](../apps/rocm/src/system_packages.rs); this module re-exports `ensure_libatomic_for_torch`/`ensure_libnuma_for_torch` (called from both `install_cmd.rs`'s `install()` and `engines_cmd.rs`) and `ensure_openmpi_for_vllm` (called from `engines_cmd.rs` and, for the engine auto-install after an SDK install, from here) so those callers keep their imports. | ||
| - [`runtime_install_finalize/torch_alignment.rs`](../apps/rocm/src/runtime_install_finalize/torch_alignment.rs) — full domain extraction, a child of `runtime_install_finalize.rs` that depends on its parent's device check (`RuntimeDeviceCheck`, `device_check_verdict`) and on `runtime_manifest_for_selector` in [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs) (split out of [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)): what to do about the torch an engine install finds in a managed runtime. `plan_torch_alignment` decides whether the SDK's torch must be realigned to the engine's pin, `align_runtime_torch` runs the realignment, `classify_retained_torch` decides when a torch that already works is kept as an intended divergence instead, and the `render_*` and `report_*` functions with `TorchAlignment` and `TorchRetention` print and log the outcome. The manifest readers (`sdk_torch_build_for_key`, `sdk_torch_build_from_manifest`, `runtime_python_for_key`, `runtime_library_paths_for_key`, `runtime_index_url_for_key`) live here too. The parent stays the caller (`settle_engine_install` and `maybe_auto_install_sdk_preferred_engine`), so it could not be a crate-level sibling without a cycle with the parent's device check. The items the parent calls are `pub(super)`: `TorchAlignment`, `TorchRetention`, `report_torch_alignment`, `report_torch_retention`, `classify_retained_torch`, `retained_diverged_package`, `deliberately_diverged_package`, `sdk_torch_build_for_key`, `runtime_python_for_key` and `runtime_library_paths_for_key`; the rest is private. Its tests cover planning, rendering, the opt-out and the retention rules, and reach the parent's private engine-dependency check as a descendant of it. |
There was a problem hiding this comment.
This entry still says torch_alignment.rs depends on runtime_manifest_for_selector in engines_cmd.rs, but this PR moves that function to engine_install_env.rs (see the changed import in torch_alignment.rs). Please point it at engine_install_env.rs so it matches the updated runtime_install_finalize.rs entry above.
There was a problem hiding this comment.
Fixed in 5e06e28: the torch_alignment.rs entry now points runtime_manifest_for_selector at engine_install_env.rs. While there I re-checked every dependency and caller claim in the entries this PR touches against the actual use statements, and fixed two more: the runtime_install_finalize.rs entry now describes a one-way edge (engines_cmd.rs imports from runtime_install_finalize.rs, which imports from engine_install_env.rs, not back from engines_cmd.rs), and the runtimes_cmd.rs entry no longer lists engine_install_env.rs among the modules that import through its re-exports (it imports runtime_adopt.rs and runtime_registry.rs directly, on purpose), with the list of modules that do use the re-exports corrected.
| // them from there. Several root-level chat/examine helpers call into | ||
| // `runtimes_cmd` directly; `current_runtime_manifest` stays re-imported here | ||
| // for other root-level commands outside `dispatch()` that call it directly. | ||
| // `select_runtime_manifest` |
There was a problem hiding this comment.
Nit: the identifier is stranded on its own line and the sentence continues on the next one. Reflowing the comment would read better.
There was a problem hiding this comment.
Reflowed in 5e06e28, so select_runtime_manifest no longer sits alone on a line.
…ll-env Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The architecture entries for runtime_install_finalize.rs and runtimes_cmd.rs described the import edges after the engine_install_env.rs split inaccurately. engines_cmd.rs still imports settle_engine_install and the system-package re-exports from runtime_install_finalize.rs; only the reverse edge was cut, so say the edge runs one way. torch_alignment.rs now depends on runtime_manifest_for_selector in engine_install_env.rs, not engines_cmd.rs. engine_install_env.rs imports runtime_adopt.rs and runtime_registry.rs directly rather than through the runtimes_cmd.rs re-exports, so it is dropped from that list, and the list now names the modules that do import through it. Also reflow the main.rs comment that left select_runtime_manifest alone on a line. Comment and documentation text only. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
|
Pushed a0622e4 (main merged in) and 5e06e28 (documentation and comment fixes from review). The docs commit corrects the three |

Why
engines_cmd.rsimportedensure_libatomic_for_torch,ensure_libnuma_for_torch,ensure_openmpi_for_vllmandsettle_engine_installfromruntime_install_finalize.rs, whileruntime_install_finalize.rs(and itstorch_alignment.rschild) importedengine_manages_own_runtime,env_root_for_engine_install,runtime_key_for_pythonandruntime_manifest_for_selectorfromengines_cmd.rs. Both imports sat outside the test modules, so the two modules formed a production import cycle. This is part of the follow-up work from the modularization audit; it is a pure move and changes no behaviour. Completes ROCMAI-850.What changes
A new neutral module,
apps/rocm/src/engine_install_env.rs, now holds the helpers that answer which runtime an engine installs into and where its environment lives:engine_manages_own_runtime,env_root_for_engine_install,runtime_manifest_for_selectorandruntime_key_for_python, plus what they depend on (env_root_for_runtime,env_root_for_self_managed_engineand the privateruntime_key_owning_python). The code moved verbatim; only the visibility ofenv_root_for_runtimeandenv_root_for_self_managed_enginechanged, from private topub(crate), becauseengines_cmd.rsstill calls them fromenv_root_for_serviceandensure_self_managed_engine_ready, which stay where they were. The five tests that exercise the moved code moved with it (the sharedside_by_side_runtimesfixture included), and the new module is declared as a privatemodinmain.rswith an SPDX header like its siblings.engines_cmd.rs,runtime_install_finalize.rs,runtime_install_finalize/torch_alignment.rs,serve_cmd.rsandruntime_services.rsnow import the helpers from the new module.main.rsno longer re-importsengine_manages_own_runtimeandruntime_manifest_for_selectorat the crate root, since their only crate-root consumer wasruntime_services.rs, which now imports them directly. The new module importsrecover_setup_runtime_registrationfromruntime_adopt.rs,select_runtime_manifestandvalidate_runtime_manifest_for_activationfromruntime_registry.rs, and the runtime-manifest model fromtherock.rs; it deliberately does not import them through thepub(crate) usere-exports inruntimes_cmd.rs, becauseruntimes_cmd.rscalls intoruntime_services.rs, which imports this module, and that route would have recreated a production cycle. Following only non-test imports fromengine_install_env.rs, everything reachable isruntime_adopt,runtime_registry,therockandcli_progress; none of them importsengines_cmd,runtime_install_finalize,runtime_servicesorengine_install_envitself, so the move adds no cycle. The remaining edge between the two original modules is one-way:engines_cmd.rscallssettle_engine_installand the system-package installs inruntime_install_finalize.rs, which no longer importsengines_cmd.rs.The second commit fixes the docs that described the relationship. The
engines_cmd.rsmodule doc claimed thatmain.rsre-importsenv_root_for_engine_install,env_root_for_serviceandruntime_key_for_pythonand that the last two are used only frommain.rs; neither was true, so it now says what the module holds and where the helpers live, and the stale comment block inmain.rsno longer lists helpers it does not re-import.docs/architecture.mdgains an entry forengine_install_env.rsand updates theengines_cmd.rs,runtime_install_finalize.rsandruntimes_cmd.rsentries. The ticket also asked for theruntimes_cmd.rsandruntime_install_finalize.rsmodule docs to be corrected because they inverted the dependency; on current main both already state the direction correctly, so they needed no change.Verification
Run locally against the final branch:
cargo fmt --all --check(clean);cargo clippy -p rocm --all-targets -- -D warnings(clean);cargo test -p rocm --bin rocm -- engine_install_env engines_cmd runtime_install_finalize runtime_services runtimes_cmd serve_cmd(149 passed, 0 failed, including the five moved tests);cargo xtask manifest --checkandcargo xtask check-crate-edges(both pass);lychee --offline docs/architecture.md(0 errors); and the repository's pre-commit hooks on both commits (fmt, license headers, markdown links, commit signing, sign-off). A grep of the production imports shows the cycle is gone: nothing outside comments inruntime_install_finalize.rsor itstorch_alignment.rschild namesengines_cmd, they import fromengine_install_envinstead, andengine_install_env.rsimports neitherengines_cmd,runtime_install_finalize,runtime_servicesnorruntimes_cmd. A transitive check over the non-testuse crate::imports (test-only modules and#[cfg(test)]blocks excluded, crate-root items checked separately) starting fromengine_install_env.rsreaches onlyruntime_adopt,runtime_registry,therockandcli_progress, and none of those leads back toengine_install_env,engines_cmd,runtime_install_finalizeorruntime_services. A leak scan of the diff and a conflict-marker grep are clean, and a merge dry-run against the currentmainreports no conflicts.Not run locally: the full workspace tests, the
tests/e2e-cucumbersuite, the Windows lane and the coverage floors. CI carries them; a move of this size should leave the floors unchanged, and none was re-blessed.Overlaps and scope
Open PRs that touch
runtimes_cmd.rs(#853 and #859) do not conflict with this change in code, since this PR does not edit that file, but expect textual conflicts indocs/architecture.md, which every modularization PR edits. This is a pure behaviour-preserving move and no user-observable output changes, so no new end-to-end scenario is needed; the moved unit tests and the existing engine and runtime tests cover it.