diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9a14c25e7..8c957cc72 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,5 +6,5 @@ SPDX-License-Identifier: MIT - [ ] 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. - [ ] 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). -- [ ] If this PR adds, renames or removes a production source file, `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. +- [ ] 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. - [ ] 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. diff --git a/AGENTS.md b/AGENTS.md index 393441cf2..2e8b5742e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -278,7 +278,7 @@ Guardrails: - `crates/rocm-engine-protocol` is a contract surface; verify all impacted engines after protocol changes - first-party crate-layering invariants (e.g. `rocmd` must never depend on `rocm`) are enforced by `cargo xtask check-crate-edges` (`xtask/src/crate_edges.rs`); a new first-party dependency edge failing that check means the edge needs review, not a bypass - source file size is checked by `cargo xtask check-module-size` ([`module_size.rs`](xtask/src/module_size.rs)): no source file may exceed 1,500 production lines (test-gated items excluded), with one limit for every file and no exemption mechanism. A PR that would push a file past it splits the file in the same change; do not raise the limit or opt a file out. The check blocks merges: the `clippy` CI job, a required check that also runs on merge-queue runs, fails when any source file is over the limit, so a file over it is split before anything else merges. The `cargo-module-size` pre-commit hook is its local mirror: it runs the same check and refuses the commit, for anyone who installed the hooks; see `docs/architecture.md` -- every production source file (a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src`) has an entry in `docs/architecture.md`, enforced by `cargo xtask check-architecture-doc` ([architecture_doc.rs](xtask/src/architecture_doc.rs)) in the `clippy` CI job and in the `architecture-doc` prek hook at commit and push. Add the entry in the same change as the file. The check has no exemption list: document the file. The check reads no prose, so keeping an entry's description true is still on you +- every production source file (a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src`), and every `.rs` file under `xtask/src`, `tests/e2e-cucumber/src` and `tests/e2e-cucumber/tests`, has an entry in `docs/architecture.md`, enforced by `cargo xtask check-architecture-doc` ([architecture_doc.rs](xtask/src/architecture_doc.rs)) in the `clippy` CI job and in the `architecture-doc` prek hook at commit and push. Add the entry in the same change as the file. The check has no exemption list: document the file. The check reads no prose, so keeping an entry's description true is still on you - preserve strict GPU-required behavior; do not introduce silent CPU fallback - respect platform gates (for example, native Windows handling for vLLM) - pin third-party GitHub Actions to a full commit SHA with a trailing `# vX.Y.Z` comment, never a moving tag (`@v2`, `@main`); a retagged or compromised action otherwise enters CI silently. Bump the SHA and comment together when upgrading diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 68e87f88e..3b9adc15e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -89,7 +89,7 @@ New subcommands and subsystems default to their own file from day one. Don't let Crate-layering invariants, such as `rocmd` never depending on `rocm`, are enforced by `cargo xtask check-crate-edges` (`xtask/src/crate_edges.rs`). File size is checked by `cargo xtask check-module-size` (`xtask/src/module_size.rs`): no source file may exceed 1,500 production lines, test code excluded, and a change that would cross the limit splits the file in the same change instead. The `clippy` CI job fails on a file over the limit, and the `cargo-module-size` pre-commit hook runs the same check locally and refuses the commit, so it is the local mirror of the CI step (it only runs if you installed the hooks). It measures the working tree, so it also fails on a Rust file under a crate's `src/` that no `mod` declares, even an untracked scratch file, and it refuses every intermediate commit of a split spread over several commits, where `SKIP=cargo-module-size git commit ...` commits those steps; `docs/architecture.md` has the details. -Every production source file, meaning a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src`, must have an entry in `docs/architecture.md`: a relative markdown link to it, which has to render as a link (a path inside an HTML comment, a code block or a code span does not count, and neither does a malformed link such as one missing its `)`, or an image). Use an inline `[text](path)` link with its text on one line; reference-style links, a `?query` suffix and root-relative paths are not recognised. `build.rs` files and the `tests/` and `examples/` trees are out of scope. `cargo xtask check-architecture-doc` (`xtask/src/architecture_doc.rs`) enforces that in the `clippy` CI job and in the `architecture-doc` prek hook, which runs on every commit and every push, over the whole tree. A file with no entry fails it, and there is no exemption list. This is the opposite direction to the `lychee` check below, which only confirms that links already in the doc still resolve. Test-only helpers (`test_support.rs`, `test_env.rs`, `*_proptests.rs`, `*_props.rs`, `*_properties.rs`) need no entry. The check does not read the prose of an entry, so keeping a description true when a file's role changes is still up to you. +Every production source file, meaning a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src`, must have an entry in `docs/architecture.md`: a relative markdown link to it, which has to render as a link (a path inside an HTML comment, a code block or a code span does not count, and neither does a malformed link such as one missing its `)`, or an image). Use an inline `[text](path)` link with its text on one line; reference-style links, a `?query` suffix and root-relative paths are not recognised. `build.rs` files and the `tests/` and `examples/` trees of those crates are out of scope. The same holds for every `.rs` file under `xtask/src`, `tests/e2e-cucumber/src` and `tests/e2e-cucumber/tests`, which also need an entry. `cargo xtask check-architecture-doc` (`xtask/src/architecture_doc.rs`) enforces that in the `clippy` CI job and in the `architecture-doc` prek hook, which runs on every commit and every push, over the whole tree. A file with no entry fails it, and there is no exemption list. This is the opposite direction to the `lychee` check below, which only confirms that links already in the doc still resolve. Test-only helpers (`test_support.rs`, `test_env.rs`, `*_proptests.rs`, `*_props.rs`, `*_properties.rs`) of those product crates need no entry; the `xtask` and `tests/e2e-cucumber` trees have no such exemption. The check does not read the prose of an entry, so keeping a description true when a file's role changes is still up to you. Every local (relative-path) Markdown link and `#anchor` fragment in the repository (outside `docs/rocm-docs/`, which `docs-build` covers instead, and hidden directories such as `.github/`, which neither check walks) is checked by the `docs-links` CI job and by the `lychee` prek hook above, both configured by `lychee.toml` (which lists the current exclusions). Both run offline only, so they don't catch broken external `https://` links. diff --git a/apps/rocm/src/automations.rs b/apps/rocm/src/automations.rs index 382afbe52..dc6760ae0 100644 --- a/apps/rocm/src/automations.rs +++ b/apps/rocm/src/automations.rs @@ -9,10 +9,9 @@ //! Mechanically relocated from `main.rs` with no behavior change — the //! `dispatch()` call site stays `automations(command)`, re-imported with //! `render_daemon_text` via -//! `use crate::automations::{automations, render_daemon_text};`. As of -//! Phase 6f (ROCMAI-210, see `docs/architecture.md`) this module also owns the -//! rendering/classification -//! helpers behind `render_automations_text` (the `rocm automations` status +//! `use crate::automations::{automations, render_daemon_text};`. This +//! module also owns the rendering/classification helpers behind +//! `render_automations_text` (the `rocm automations` status //! report: watcher status/policy lines, recent automation activity, and //! plain-language proposal/audit summaries) and `render_daemon_text` (the //! `rocm daemon --status` summary) — both folded in from `main.rs` alongside diff --git a/apps/rocm/src/engine_runtime_select.rs b/apps/rocm/src/engine_runtime_select.rs index aa65af269..3200aaec7 100644 --- a/apps/rocm/src/engine_runtime_select.rs +++ b/apps/rocm/src/engine_runtime_select.rs @@ -21,15 +21,13 @@ //! `service_model_gpu_ready`, `service_model_reports_rocm_backend`, //! `service_model_names_match`). //! -//! Mechanically relocated from `main.rs` with no behavior change — Phase 6f -//! (ROCMAI-215) of the `main.rs` modularization (see -//! `docs/architecture.md`). This is the last sub-phase of the `main.rs` -//! Phase 6f split that lands before the file's single shared -//! `#[cfg(test)] mod tests` block starts: the function immediately after this -//! cluster in the original file, `treat_as_natural_language`, is -//! dispatch-adjacent natural-language-invocation routing left over from an -//! earlier phase (ROCMAI-87) and stays in `main.rs` on purpose — it is not -//! part of this module and is not touched by this change. +//! Mechanically relocated from `main.rs` with no behavior change (the +//! `relocation` class in `docs/architecture.md`). The cluster ended where the +//! file's single shared `#[cfg(test)] mod tests` block starts: the function +//! immediately after it in the original file, `treat_as_natural_language`, is +//! dispatch-adjacent natural-language-invocation routing that stays in +//! `main.rs` on purpose — it is not part of this module and is not touched by +//! this change. //! //! One item physically interleaved in this span in `main.rs` stayed there //! instead of moving: `const fn status_for_readiness` sits between diff --git a/apps/rocm/src/freeform_execution.rs b/apps/rocm/src/freeform_execution.rs index 9838e4066..33de867cb 100644 --- a/apps/rocm/src/freeform_execution.rs +++ b/apps/rocm/src/freeform_execution.rs @@ -2,8 +2,8 @@ // // SPDX-License-Identifier: MIT -//! The freeform natural-language planner's plan-*execution*/consent cluster -//! (ROCMAI-726, a Phase 6e, ROCMAI-87 follow-up). +//! The freeform natural-language planner's plan-*execution*/consent cluster, +//! the half that `freeform_planner.rs` left behind. //! //! Mechanically relocated from `main.rs` with no behavior change — `main.rs`'s //! `execute_freeform_next_action()` call sites stay byte-identical @@ -18,7 +18,7 @@ //! to execute. //! //! This is the other half of the freeform-planner cluster that -//! `freeform_planner.rs` (Phase 6e, ROCMAI-87) deliberately left behind: that +//! `freeform_planner.rs` deliberately left behind: that //! module builds a plan; this one reads/acts on its `FreeformPlanAction` //! internals, grants it the consent the outer `--yes` already carries, and //! computes planner-specific output text — a dispatch-adjacent concern diff --git a/apps/rocm/src/gpu_policy.rs b/apps/rocm/src/gpu_policy.rs index 81bef3432..108a642d3 100644 --- a/apps/rocm/src/gpu_policy.rs +++ b/apps/rocm/src/gpu_policy.rs @@ -10,10 +10,9 @@ //! --json`, with an amdgpu DRM sysfs fallback), and building the serve-plan //! low-VRAM warning from it. //! -//! Mechanically relocated from `main.rs` with no behavior change — Phase 6f -//! (ROCMAI-214) of the `main.rs` modularization (see -//! `docs/architecture.md`). `dispatch()` calls directly into this module at -//! one point — the `Command::EngineServeHttp` arm's +//! Mechanically relocated from `main.rs` with no behavior change (the +//! `relocation` class in `docs/architecture.md`). `dispatch()` calls directly +//! into this module at one point — the `Command::EngineServeHttp` arm's //! `parse_gpu_indices_arg(gpu.as_deref())?` — re-imported via `use //! crate::gpu_policy::parse_gpu_indices_arg;`; `dispatch()`'s own body is //! otherwise unaffected. @@ -32,8 +31,9 @@ //! //! One item physically interleaved in this span in `main.rs` stayed there //! instead of moving: `const fn device_policy_name` sits immediately after -//! `detect_gpu_count` and before the next cluster's (ROCMAI-215) -//! `EngineSelection`/`resolve_engine_selection`, but it already had callers +//! `detect_gpu_count` and before the engine-selection cluster's +//! `EngineSelection`/`resolve_engine_selection` (now in +//! `engine_runtime_select.rs`), but it already had callers //! outside this cluster — `engine_ipc.rs` and `service_launch.rs` reach it //! unqualified via `use crate::{...}`, same as `serve_cmd.rs` does — plus its //! own test, so it is not part of this cluster's relocation. diff --git a/apps/rocm/src/main.rs b/apps/rocm/src/main.rs index d713b0c10..776590c87 100644 --- a/apps/rocm/src/main.rs +++ b/apps/rocm/src/main.rs @@ -96,7 +96,7 @@ mod update_cmd; // for other root-level commands outside `dispatch()` that call it directly. // `select_runtime_manifest` is no longer needed here: // `single_ready_runtime_key`/`resolve_runtime_selector_to_exact_key` moved out -// to `engine_runtime_select.rs` in ROCMAI-215 (Phase 6f), reaching it via that +// to `engine_runtime_select.rs`, reaching it via that // module's own grouped `use crate::runtimes_cmd::{...}` import instead. // `update_cmd.rs`'s `apply_runtime_update`/`append_update_activate_summary` // call into `runtimes_cmd` directly too, via their own imports rather than @@ -105,9 +105,9 @@ mod update_cmd; // `managed_service_process_command`, and // `ensure_public_service_has_endpoint_key` are no longer needed here either: // their only caller outside `dispatch()`, `restart_internal_managed_service` -// (and the endpoint-key check inside it), moved out to `services_text.rs` in -// ROCMAI-209 (Phase 6f) and has since moved on to `service_control.rs`, which -// reaches them via its own imports instead. +// (and the endpoint-key check inside it), moved out to `services_text.rs` and +// has since moved on to `service_control.rs`, which reaches them via its own +// imports instead. // `record_cli_audit_event`, `cli_lifecycle_log_path` and `sanitize_log_value` // (from `cli_audit.rs`) are re-imported so other modules keep reaching them as // `crate::`. diff --git a/apps/rocm/src/managed_service_status.rs b/apps/rocm/src/managed_service_status.rs index 15deaef21..ccd8826ef 100644 --- a/apps/rocm/src/managed_service_status.rs +++ b/apps/rocm/src/managed_service_status.rs @@ -5,10 +5,10 @@ //! Managed-service liveness classification and the dashboard-sidebar //! status/counts helpers derived from it. //! -//! Mechanically relocated from `main.rs` with no behavior change — Phase 6f -//! (ROCMAI-211) of the `main.rs` modularization (see -//! `docs/architecture.md`). `dispatch()`'s call sites are unaffected: none of -//! this module's functions are called directly from `dispatch()`. +//! Mechanically relocated from `main.rs` with no behavior change (the +//! `relocation` class in `docs/architecture.md`). `dispatch()`'s call sites are +//! unaffected: none of this module's functions are called directly from +//! `dispatch()`. //! //! This module owns: reading and liveness-refreshing the on-disk managed-service //! registry (`load_managed_services`, `refresh_managed_service_runtime_liveness`, diff --git a/apps/rocm/src/runtime_services.rs b/apps/rocm/src/runtime_services.rs index 636a3e454..84f020ef8 100644 --- a/apps/rocm/src/runtime_services.rs +++ b/apps/rocm/src/runtime_services.rs @@ -16,8 +16,8 @@ //! [`ServiceRuntimeState`], [`RuntimeServiceEntry`], [`FailedServiceRestart`], //! [`RuntimeServiceReconciliation`] and [`ServiceRuntimePin`]. `RuntimesCommand` //! lives in `cli.rs` (part of the `Command`/`Cli` clap definition); `fn -//! runtimes()` itself moved to `runtimes_cmd.rs` in Phase 6c (ROCMAI-89), which -//! calls back into this file via `crate::runtime_services`. +//! runtimes()` itself lives in `runtimes_cmd.rs`, which calls back into this +//! file via `crate::runtime_services`. use std::fmt::Write as _; diff --git a/apps/rocm/src/serve_cmd.rs b/apps/rocm/src/serve_cmd.rs index 711e169b6..836eaaf72 100644 --- a/apps/rocm/src/serve_cmd.rs +++ b/apps/rocm/src/serve_cmd.rs @@ -28,16 +28,16 @@ //! `parse_device_policy`, `parse_gpu_selection`, //! `select_gpu_indices_under_launch_lock`, `serve_gpu_low_memory_warning`, //! and `validate_pinned_gpu_index` moved out of `main.rs` into -//! `gpu_policy.rs` in ROCMAI-214 (Phase 6f); `resolve_engine_selection` and +//! `gpu_policy.rs`; `resolve_engine_selection` and //! `validate_engine_selection_runtime` moved out of `main.rs` into -//! `engine_runtime_select.rs` in ROCMAI-215 (Phase 6f); this file's `use` +//! `engine_runtime_select.rs`; this file's `use` //! list below points to both now instead of at the crate root. The //! managed-service-spawning tail this file calls into — `start_managed_service`, //! `run_attached_service`, `resolve_endpoint_auth`, //! `ensure_public_bind_engine_supported`, //! `drop_orphaned_endpoint_key_on_already_running`, `print_managed_launch_plain`, //! `validate_bind_host`, `ensure_background_helper_running_quiet` — was relocated -//! to `service_launch.rs` in ROCMAI-91 (Phase 6b), along with its test module; +//! to `service_launch.rs`, along with its test module; //! this file's `use` list below points there now instead of at the crate root. use anyhow::{Context as _, Result, bail}; diff --git a/apps/rocm/src/service_launch.rs b/apps/rocm/src/service_launch.rs index 8653d6a69..ae5c2fdb5 100644 --- a/apps/rocm/src/service_launch.rs +++ b/apps/rocm/src/service_launch.rs @@ -8,13 +8,13 @@ //! Relocated from `main.rs`, since extended with the port-allocation and //! launch-lock transaction. This module //! is the managed-service-spawning tail that was deliberately deferred out of -//! the Phase 6a (ROCMAI-82) split: `start_managed_service`, +//! the earlier relocation of the service-record code: `start_managed_service`, //! `run_attached_service`, `spawn_managed_engine_child`, `stream_attached_logs`, //! and the rest of what was then a single file. It was entangled with crate-root launch helpers //! — `record_cli_audit_event`, `existing_live_managed_service_in`, and the stop //! action of the service-record-management cluster (this module reaches only //! stop, via `AttachOutcome::Stop`; restart/remove/prune are not called here) -//! — and this later pass (ROCMAI-91, Phase 6b) separates the spawning tail out +//! — and this later pass separates the spawning tail out //! from them; see below for where they live now. //! //! `dispatch()`'s call sites are unaffected: `Command::Services { command } => diff --git a/apps/rocm/src/uninstall_plan.rs b/apps/rocm/src/uninstall_plan.rs index c350ae86e..3c3da4e6d 100644 --- a/apps/rocm/src/uninstall_plan.rs +++ b/apps/rocm/src/uninstall_plan.rs @@ -5,8 +5,8 @@ //! The uninstall plan: what would be removed, how that plan is rendered for //! review, and the filesystem-removal primitive used to carry it out. //! -//! Mechanically relocated from `main.rs` with no behavior change — Phase 6f -//! (ROCMAI-212) of the `main.rs` modularization (see `docs/architecture.md`). +//! Mechanically relocated from `main.rs` with no behavior change (the +//! `relocation` class in `docs/architecture.md`). //! `dispatch()`'s call sites are unaffected: none of this module's functions //! are called directly from `dispatch()`. //! diff --git a/apps/rocm/src/update_cmd.rs b/apps/rocm/src/update_cmd.rs index e98c6d69a..10fac53f1 100644 --- a/apps/rocm/src/update_cmd.rs +++ b/apps/rocm/src/update_cmd.rs @@ -11,8 +11,8 @@ //! update-source/installed-runtime pickers behind it //! (`select_runtime_update_source`, `select_installed_update_runtime`). //! -//! Mechanically relocated from `main.rs` with no behavior change — Phase 6f -//! (ROCMAI-210) of the `main.rs` modularization (see `docs/architecture.md`). +//! Mechanically relocated from `main.rs` with no behavior change (the +//! `relocation` class in `docs/architecture.md`). //! The `update` command arm of `dispatch()` calls `update`, the handler whose //! body was that arm's own and which was relocated here verbatim, re-imported //! via `use crate::update_cmd::update;`; `update` in turn calls diff --git a/docs/architecture.md b/docs/architecture.md index 12b06a75c..fbd94b875 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -6,18 +6,18 @@ SPDX-License-Identifier: MIT # Architecture -This is the living module map for rocm-cli. It's a contributor-facing reference to where things live and why, updated in the same PR as the code it documents. It documents what exists now; the few moves that are still deferred are called out in the entries they affect. Phase labels such as "Phase 5 of ROCMAI-27's sequencing" name the original modularization effort's ordering and are kept only so a module can be traced to the ticket that moved it. It is also not a design-history document: entries describe current structure, not the decisions or debates that produced it. +This is the living module map for rocm-cli: a contributor-facing reference to where things live and why, updated in the same PR as the code it documents. It documents the current structure, not the decisions or debates that produced it. -> Before relying on any entry below, verify current file and function boundaries directly (e.g. `grep`) rather than trusting this doc's wording. Module boundaries shift as the codebase grows, and a stale-but-plausible-looking note is worse than an explicit prompt to check. Every concrete file citation in the Module map's per-crate inventories below — except "the old agent.rs" in the `rocm-dash-tui` entry (historical prose about a deleted file) and `report.json` in the `crates/e2e-report` entry (cucumber's untracked generated output) — is a relative markdown link rather than a bare filename, checked offline by [lychee](https://github.com/lycheeverse/lychee) in CI (the `docs-links` job, config in `lychee.toml`) — a moved or deleted file fails CI immediately, naming the broken link. That check doesn't check that the surrounding prose (e.g. which extraction pattern a module follows) is still accurate; the caution above still applies to everything but link resolution. +> Before relying on any entry below, verify current file and function boundaries directly (e.g. `grep`) rather than trusting this doc's wording. Module boundaries shift as the codebase grows, and a stale-but-plausible-looking note is worse than an explicit prompt to check. A citation of a specific file in this document is a relative markdown link at its first mention in a table row or bullet; later mentions of the same file in that row or bullet are bare, and so are generic mentions (such as `main.rs`, `lib.rs`, `mod.rs` or the workspace `Cargo.toml`), runtime or generated files (such as `config.json` or `report.json`) and files that are not tracked in this repository. The links are checked offline by [lychee](https://github.com/lycheeverse/lychee) in CI (the `docs-links` job, config in [`lychee.toml`](../lychee.toml)), so a moved or deleted file fails CI immediately and names the broken link. That check does not verify that the surrounding prose is still accurate; the caution above still applies to everything but link resolution. -A second check runs the other way: `cargo xtask check-architecture-doc` ([`architecture_doc.rs`](../xtask/src/architecture_doc.rs)) fails when a production source file — a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src` — has no link in this document, so a new module cannot land without an entry. Only a link that renders as one counts: a path inside an HTML comment, a code block or a code span does not, and neither does a malformed link (one missing its `[` or `)`, or with an escaped bracket), an image, or the outer brackets of a link that contains another link. Write the entry as an inline `[text](path)` link with its text on one line; `` delimiters around the destination are accepted, but reference-style links, a `?query` suffix and root-relative paths are not. `build.rs` files and the `tests/` and `examples/` trees are out of scope. It runs in the `clippy` CI job and in the `architecture-doc` prek hook, at commit and at push. Test-only helpers (`test_support.rs`, `test_env.rs`, `*_proptests.rs`, `*_props.rs`, `*_properties.rs`) need no entry. There is no exemption list: a production file with no entry fails the check. +A second check runs the other way: `cargo xtask check-architecture-doc` ([`architecture_doc.rs`](../xtask/src/architecture_doc.rs)) fails when a production source file, meaning a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src`, has no link in this document, so a new module cannot land without a link here, normally its row. It covers the repository's own tooling and test harness the same way: every `.rs` file under `xtask/src`, `tests/e2e-cucumber/src` and `tests/e2e-cucumber/tests` needs a link too. Only a link that renders as one counts: a path inside an HTML comment, a code block or a code span does not, and neither does a malformed link (one missing its `[` or `)`, or with an escaped bracket), an image, or the outer brackets of a link that contains another link. Write the row's file cell as an inline `[text](path)` link with its text on one line; `` delimiters around the destination are accepted, but reference-style links, a `?query` suffix and root-relative paths are not. `build.rs` files and the `tests/` and `examples/` trees of the product crates are out of scope. It runs in the `clippy` CI job and in the `architecture-doc` prek hook, at commit and at push. Test-only helpers (`test_support.rs`, `test_env.rs`, `proptests.rs`, `*_proptests.rs`, `*_props.rs`, `*_properties.rs`) may have a row but need none in a production crate; in the `xtask` and `tests/e2e-cucumber` trees every file needs one, whatever its name. There is no exemption list: a file in scope with no link fails the check. The check reads no prose, so keeping a row's description true is up to the change that edits the file. ## Module organization convention -New subcommands and subsystems default to their own file from day one — they should not grow inside `main.rs`/`lib.rs` waiting for a future extraction pass. Two extraction patterns already exist in the codebase; use whichever fits: +New subcommands and subsystems default to their own file from day one. They should not grow inside `main.rs`/`lib.rs` waiting for a future extraction pass. Two extraction patterns exist in the codebase; use whichever fits. The Class column of the module map below records which one a file was extracted under, where that is recorded. -- **Full domain extraction** — a subsystem's domain implementation moves into its own file that owns its own types (structs/enums), not just relocated functions; that ownership is usually what distinguishes this pattern from mechanical relocation below, though the Phase 6a variant described next shows ownership alone doesn't fully tell them apart — every `apps/rocm` module is a private `mod x;` regardless of pattern, so module privacy alone doesn't tell the two apart either. Full-domain-extraction modules are typically reached via qualified paths (e.g. `comfyui::render_status(...)`); mechanically relocated modules with no owned types are reached the same way (e.g. [`endpoint_keys.rs`](../apps/rocm/src/endpoint_keys.rs), [`logging.rs`](../apps/rocm/src/logging.rs)). The exception — reached unqualified through `use crate::x::{...}` re-imports, matching their dispatch call sites' pre-extraction form — is limited to the clusters that moved as a dispatch-adjacent group; the block of `use crate::x::{...}` re-imports near the top of [`main.rs`](../apps/rocm/src/main.rs) is the current list of the modules it reaches that way (a few of them re-imported for reasons other than dispatch, as the comment above the block explains). [`service_launch.rs`](../apps/rocm/src/service_launch.rs) (as of Phase 6b, ROCMAI-91) uses the same unqualified re-import form for its cross-module callers, but it is not a dispatch-adjacent cluster in the same sense — one of its callers, `automations.rs`, is not a dispatch call site, and its pre-extraction form was a qualified `crate::` call rather than an unqualified import, so the re-import is new rather than kept. This call-site form, not type ownership or dispatch-fn placement, is what actually separates the Phase 6a variant below from full domain extraction. Where a subsystem has a dedicated clap subcommand, its command *enum* usually lives in [`cli.rs`](../apps/rocm/src/cli.rs) as part of the `Command`/`Cli` definition (e.g. `ComfyuiCommand`, `RuntimesCommand`), the way [`apps/rocmd`](../apps/rocmd/src/cli.rs) keeps its command tree in a `cli.rs` of its own — but the dispatch function, the match over that tree, does not stay in `main.rs` with it: `comfyui::run` lives in `comfyui.rs`, reached by the qualified path full domain extraction uses, while `engines()` and `runtimes()` moved out to `engines_cmd.rs`/`runtimes_cmd.rs` respectively, following the mechanical-relocation re-import form below. Only the top-level `dispatch()`, the match that sends each `Command` variant to its handler, stays in `main.rs`. Not every domain-extracted module has a dedicated command enum at all (`providers.rs` has none; it's invoked from the existing chat/config command flows). In library crates (`crates/rocm-core`) the module is `pub mod x;` plus a `pub use x::{...};` re-export, since it's part of the crate's public API. This is the default for new subsystems. Examples: [`apps/rocm/src/therock.rs`](../apps/rocm/src/therock.rs) (TheRock SDK install orchestration, with its update planning and other clusters in `therock/` child modules and no command enum of its own), [`comfyui.rs`](../apps/rocm/src/comfyui.rs) (`ComfyuiCommand`), [`providers.rs`](../apps/rocm/src/providers.rs) (no dedicated command enum); `crates/rocm-core`'s [`diagnose.rs`](../crates/rocm-core/src/diagnose.rs)/[`examine.rs`](../crates/rocm-core/src/examine.rs). -- **Mechanical relocation** — a `pub(crate) fn` moves out verbatim, with shared types/config staying at the crate root and reached via `crate::`. Used for dispatch-adjacent clusters where a minimal, easy-to-review diff matters more than full extraction. Example: [`apps/rocm/src/update_cmd.rs`](../apps/rocm/src/update_cmd.rs). Variant: when the cluster is large enough to own types (part of `main.rs`'s Phase 6a split, ROCMAI-82, `main.rs`'s Phase 6b split, ROCMAI-91, `main.rs`'s Phase 6c split, ROCMAI-89, and Phase 6e's follow-up, ROCMAI-726), those types move with it instead of staying in `main.rs` — [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs)'s types are used nowhere else, but [`driver_install.rs`](../apps/rocm/src/driver_install.rs)'s `DriverInstallResult`/`DriverInstallError` are `pub(crate)` and read from [`install_cmd.rs`](../apps/rocm/src/install_cmd.rs)'s `install()` (`result.output`/`result.executed`, `error.source`/`error.executed`); [`freeform_execution.rs`](../apps/rocm/src/freeform_execution.rs)'s `FreeformExecution` is `pub(crate)` and read from `main.rs`'s `execute_freeform_next_action()` (`execution.action`) — it was already `pub(crate)` before the split, unlike the two functions that return/consume it, which widened from module-private; [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs)'s `ServeEngineSelection`/`ServeArgs` both stay `pub(crate)` and are used from `main.rs` (`ServeArgs`) and [`model_fit.rs`](../apps/rocm/src/model_fit.rs) (`assess_model_for_host` calls `select_serve_engine` and reads the resulting `ServeEngineSelection`'s `.engine`/`.source` fields) — and `ServeGenerationDefaults` moved out with the engine-recipe overrides to [`serve_recipe.rs`](../apps/rocm/src/serve_recipe.rs), where it and its fields are `pub(crate)` because `serve()` builds it; the types in the child modules of [`service_launch.rs`](../apps/rocm/src/service_launch.rs) are private to the child that owns them (`AttachOutcome`, `RawModeGuard`, `AutostartClaim`) or `pub(super)` where a sibling child reads them (`ManagedSpawn`, `ManagedPortDecision`), except `ManagedLaunchReport`, which is `pub(crate)` and read from [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) for the interactive summary, and `ManagedReuseRefusal`, which is `pub(crate)` because `managed_service_reuse_refusal`, a function `serve_cmd.rs` calls, returns it; [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs)'s `RuntimeActivationResult` and `ActiveRuntimeMarker` are `pub(crate)` and read from [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs)'s `apply_runtime_update`/`append_update_activate_summary` and from [`storage.rs`](../apps/rocm/src/storage.rs) respectively; its sibling [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)'s `SdkInstallConsents` is `pub(crate)` and read from `install_cmd.rs`'s `install()`. The pattern is still "mechanical relocation" rather than full domain extraction because call sites keep their pre-extraction unqualified-re-import form — the exception named above — rather than switching to the qualified paths full-domain-extraction modules use. Where a subcommand's dispatch fn lives is not what makes it so: a full-domain-extraction module can host its own dispatch fn too (see `comfyui::run` above). +- **Full domain extraction** (`domain`): a subsystem's domain implementation moves into its own file that owns its own types, not just relocated functions. Every `apps/rocm` module is a private `mod x;` regardless of pattern, so privacy does not tell the two patterns apart. Domain-extracted modules are typically reached through qualified paths (e.g. `comfyui::run(...)`), and so are mechanically relocated modules that own no types (e.g. [`endpoint_keys.rs`](../apps/rocm/src/endpoint_keys.rs), [`logging.rs`](../apps/rocm/src/logging.rs)). The exception, reached unqualified through `use crate::x::{...}` re-imports that match the dispatch call sites' pre-extraction form, is limited to the clusters that moved as a dispatch-adjacent group; the block of `use crate::x::{...}` re-imports near the top of [`main.rs`](../apps/rocm/src/main.rs) is the current list of modules reached that way. Where a subsystem has a dedicated clap subcommand, its command enum usually lives in [`cli.rs`](../apps/rocm/src/cli.rs) with the rest of the `Cli`/`Command` definition (e.g. `ComfyuiCommand`, `RuntimesCommand`), the way [`apps/rocmd`](../apps/rocmd/src/cli.rs) keeps its command tree in a `cli.rs` of its own. The dispatch function, the match over that tree, does not stay with the enum: `comfyui::run` lives in [`comfyui.rs`](../apps/rocm/src/comfyui.rs), and `engines()` and `runtimes()` live in [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs) and [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs). Only the top-level `dispatch()`, the match that sends each `Command` variant to its handler, stays in `main.rs`. [`bootstrap.rs`](../apps/rocm/src/bootstrap.rs) and [`remote/mod.rs`](../apps/rocm/src/remote/mod.rs) own their command enum as well as their dispatch. Not every domain-extracted module has a command enum at all ([`providers.rs`](../apps/rocm/src/providers.rs) has none). In library crates (`crates/rocm-core`) a new subsystem is `pub mod x;` plus a `pub use x::{...};` re-export, since it is part of the crate's public API. This is the default for new subsystems. Examples: [`therock.rs`](../apps/rocm/src/therock.rs) (TheRock SDK install orchestration, with its other clusters in `therock/` child modules and no command enum of its own), [`comfyui.rs`](../apps/rocm/src/comfyui.rs) and [`providers.rs`](../apps/rocm/src/providers.rs); `crates/rocm-core`'s [`diagnose.rs`](../crates/rocm-core/src/diagnose.rs) and [`examine.rs`](../crates/rocm-core/src/examine.rs). +- **Mechanical relocation** (`relocation`): a `pub(crate) fn` moves out verbatim, with shared types and config staying at the crate root and reached via `crate::`. Used for dispatch-adjacent clusters where a minimal, easy-to-review diff matters more than full extraction. Example: [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs). When the cluster is large enough to own types, they move with it instead of staying in `main.rs` (e.g. [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), [`driver_install.rs`](../apps/rocm/src/driver_install.rs), [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs)). It is still mechanical relocation rather than domain extraction, because the call sites kept their pre-extraction unqualified re-import form when the code moved. Where a subcommand's dispatch function lives is not what decides it: a domain-extraction module can host its own (see `comfyui::run` above). Moving a `proptest!` block to another file leaves its saved failure cases behind unless they are carried over: proptest keys them by the test's source file (`/src/.rs` reads `/proptest-regressions/.txt`, where `src/` is the directory holding `main.rs` or `lib.rs`) and does not warn when the file stops matching. Carry them in the same commit, and how depends on how much moved. When every property test of the file moves and the new file has no regression file yet, `git mv` the old one to the name the new file needs. When only some move, the tests left behind still read the old file, so keep it, and copy the saved cases to the new file's regression file (appending to it when it already exists, so its own cases stay). An `xtask` test fails the build on a regression file no test reads; it cannot notice a regression file that was moved away from tests that still need it, so check a split's diff for that. See [Property tests](testing.md#property-tests). @@ -25,441 +25,854 @@ A flat size limit backs this convention: `cargo xtask check-module-size` ([`modu ## Module map -Scoped to the crates that make up the shipped CLI/daemon/dashboard/engine surface, plus `crates/e2e-report` (a shared exception: it's HTML/markdown reporting consumed only by `xtask` and `tests/e2e-cucumber`, but it's still one of the modularization effort's target files, so it's mapped below). Dev-tooling and test-harness workspace members (`xtask`, `tests/e2e-cucumber` themselves) are otherwise out of scope — they're not part of the modularization effort's inventory. +Scoped to the crates that make up the shipped CLI, daemon, dashboard and engine surface, plus `crates/e2e-report`, `xtask` and `tests/e2e-cucumber`. `crates/e2e-report` is HTML and markdown reporting consumed only by `xtask` and `tests/e2e-cucumber`; those two are the repository's tooling and test harness, and `check-architecture-doc` checks that every file in them has a row. -Each per-crate module inventory lists one file per line. Flat inventories (every one below except `rocm-dash-tui`'s directory-split `agent/`, `app/` and `ui/tabs/` lists, `e2e-report`'s directory-split `consolidated/` list and the `engines/aim` list) are sorted alphabetically by filename, so a newly-extracted module has a predictable insertion point and doesn't force a rewrite of its neighbors; the `agent/`, `app/` and `consolidated/` lists instead keep `mod.rs` first, then the other files in logical (not alphabetical) order, and the `ui/tabs/` list keeps `mod.rs` first and then sorts the tabs alphabetically. +Each crate has a table with a row per source file (`rocm-dash-tui` and `tests/e2e-cucumber` have one table per directory), sorted by path with the crate roots (`main.rs`, `lib.rs`) first and a directory's `mod.rs` first within its directory. The Class column records how a file came to be, not a rule a new file is judged by: `domain` (full domain extraction or a child module of one, the default for a new subsystem), `relocation` (mechanical relocation) and `flat` (everything else: crate roots, files with no extraction pattern recorded, and test-only support). The `xtask` and `tests/e2e-cucumber` tables are `flat` throughout, since they hold tooling and test files rather than extracted subsystems, so the column carries no information for them. Under each table, **Boundaries** lists some of the facts a row cannot show, such as layering and leaf modules, deliberate privacy and shared sources of truth. It is a selection, not an inventory; the source files carry the rest. ### `apps/rocm` — main CLI binary -[`main.rs`](../apps/rocm/src/main.rs) is the crate root. Besides smaller helpers, it holds `main()`, `run()` and `dispatch()`, the match over the clap `Cli`/`Command` tree that [`cli.rs`](../apps/rocm/src/cli.rs) defines; the builders that turn that tree into a `clap::Command` (`cli_command()`, `completion_command()`); the command handlers still defined here (`version()` and `launch_default()`, the no-subcommand arm); freeform-invocation routing (`parse_freeform_invocation`, `should_treat_as_freeform`, `run_freeform`, `execute_freeform_next_action`, `treat_as_natural_language`); a few crate-root items several modules share (`status_for_readiness`, `device_policy_name`, `engine_inventory`, `ROLLBACK_RECOVERY_HINT`); the `use crate::x::{...}` re-import block described above, which also re-imports the `cli.rs` types so other modules keep reaching them as `crate::Command`, `crate::Provider` and so on; and the crate's shared `mod tests` block. - -- [`automations.rs`](../apps/rocm/src/automations.rs) — mechanical relocation, owns private types (Phase 6f, ROCMAI-210): the `rocm automations` dispatch handler (`automations()`) plus the `rocm automations` status report it prints (`render_automations_text`), the `ProposalKind` classification that report renders through (`proposal_kind`, `fallback_tool_for_automation_action`, `proposal_plain_summary`, `proposal_plain_reason`), the small plain-language label helpers (`proposal_status_label`, `proposal_bool_argument`, `automation_event_plain_summary`, `audit_event_plain_summary`, `watcher_mode_plain_label`, `watcher_last_check`, `watcher_plain_name`, `watcher_plain_trigger`, `watcher_plain_action`, `watcher_policy_note`), and the unrelated `rocm daemon --status` summary (`render_daemon_text`). `render_automations_text` and `render_daemon_text` are `pub(crate)`: [`main.rs`](../apps/rocm/src/main.rs)'s `dispatch()` calls `render_daemon_text` directly (re-imported alongside `automations` via `use crate::automations::{automations, render_daemon_text};`; `render_automations_text` has no `dispatch()` call site of its own, reached only through `automations()` above, now local to this file), and [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs)'s read-only command runner calls both. Every other item in this list, including `watcher_policy_note` (called from `automations()`'s `Enable` arm and from `render_automations_text`, both in this same file), has no caller outside this module and stays private. The cluster's regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::` the same way other mechanically relocated modules do. -- [`background_helper.rs`](../apps/rocm/src/background_helper.rs) — mechanical relocation out of [`service_launch.rs`](../apps/rocm/src/service_launch.rs), owns one `pub(crate)` type: what the CLI can tell about the background automation helper (`rocm daemon`). It holds `background_helper_already_running` (the file-based liveness check behind the no-double-spawn decision), the `HelperNote` type and `background_helper_note` with its `helper_note_for` wording, which [`services_text.rs`](../apps/rocm/src/services_text.rs) prints after a stop and [`uninstall_plan.rs`](../apps/rocm/src/uninstall_plan.rs) turns into an uninstall warning. Spawning the helper (`ensure_background_helper_running` and its autostart lock) stays in [`service_launch/helper_autostart.rs`](../apps/rocm/src/service_launch/helper_autostart.rs), a child of [`service_launch.rs`](../apps/rocm/src/service_launch.rs), which reads `background_helper_already_running` from here. The module is a leaf: it imports nothing from the service modules, so the note can be read from [`services_text.rs`](../apps/rocm/src/services_text.rs) without that module importing the one that spawns services. The cluster's regression tests live in this module's own `mod tests`, which stays private: the `runtime_state` and `set_helper_facts` fixtures they share with the helper-autostart and stop-output tests in [`service_launch/helper_autostart.rs`](../apps/rocm/src/service_launch/helper_autostart.rs) live in the crate-level [`test_support.rs`](../apps/rocm/src/test_support.rs). -- [`bootstrap.rs`](../apps/rocm/src/bootstrap.rs) — a further-extracted variant of full domain extraction: it owns its clap command enum (`BootstrapCommand`) and dispatch function too, rather than leaving the enum in [`cli.rs`](../apps/rocm/src/cli.rs) and the dispatch in [`main.rs`](../apps/rocm/src/main.rs). -- [`bridge_snapshot.rs`](../apps/rocm/src/bridge_snapshot.rs) — mechanical relocation, no owned types: the host snapshot behind the internal bridge surface (`build_codex_bridge_snapshot`, `build_codex_bridge_gpu_snapshot`, `builtin_codex_bridge_engine_inventory`), whose engine list is derived from `main.rs`'s `engine_inventory`, the single table of built-in engine ids that `rocm examine`, `rocm update` and the `--engine` help test read as well. All three are `pub(crate)`: [`main.rs`](../apps/rocm/src/main.rs)'s `dispatch()` calls `build_codex_bridge_snapshot` through a re-import, [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs)'s internal MCP tools reach them as `crate::` through the same re-import. It has no tests of its own. -- [`chat.rs`](../apps/rocm/src/chat.rs) — the chat assistant's entry points and the module that ties its pieces together, a file beside a `chat/` directory of child modules (as [`providers.rs`](../apps/rocm/src/providers.rs) is beside `providers/`). It keeps `read_piped_prompt` and `piped_prompt_from_input` (the `echo "…" | rocm chat` path), `render_chat_text` (the status screen), `render_chat_prompt_text` (the one-shot reply text, which calls into `chat/turn.rs`), `plain_provider_auth_status` and the clap value parsers for the sampling flags (`parse_non_negative_temperature`, `parse_unit_interval`, `parse_positive_u32`), plus the re-exports below. The work behind them lives in four leaf children: [`chat/turn.rs`](../apps/rocm/src/chat/turn.rs) (the turn loop, the system prompt and the transcript), [`chat/intent.rs`](../apps/rocm/src/chat/intent.rs) (the prompt-intent heuristics), [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs) (the MCP tool bridge and in-process command execution) and [`chat/summaries.rs`](../apps/rocm/src/chat/summaries.rs) (the deterministic tool-output summaries); `turn` is the top of that call graph and calls the other three, none of which calls back. The tool-call validation and approval policy (`validate_chat_tool_call`, the `validate_chat_*_tool_call` family, `ChatRocmCommandAction`, `ChatToolApprovalRequest`) lives in [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs), which the children call into. Callers in other modules, production and test-only, reach the moved items through the `chat::` module boundary, so `chat.rs` re-exports each one another module reads: `run_internal_mcp_call` (`main.rs`, `dash_seam.rs`), `rocm_chat_tool_system_prompt_for_host` (`dash.rs`), `chat_tool_approval_request`, `chat_tool_call_is_read_only` and `validate_chat_tool_call` (`dash_seam.rs`), `any_substring` and `ensure_flag` (from `prompt_text.rs` and `rocm_argv.rs`, for `freeform_answer.rs` and `freeform_execution.rs`), and, only under `#[cfg(test)]`, `deterministic_comfyui_tool_summary` (`comfyui.rs`'s tests, unix only), `ChatRocmCommandAction`, `rocm_chat_tool_requested_args`, `chat_install_driver_action` and `chat_rocm_command_action_from_args` (`driver_plan.rs`'s and `system_packages.rs`'s tests). Each child's tests live in its own `mod tests`, with their original names; the two piped-prompt tests and the command-preview property tests (which drive the tool-call guards, the planner's guards and the rendered command lines across the policy, the bridge and the turn loop) stay in `chat.rs`. `serve_negative_sampling_space_form_reaches_range_validator`, a shared clap value-parser wiring test living alongside its sibling command-parsing tests, has moved with them to the test module in [`cli.rs`](../apps/rocm/src/cli.rs); the four structural checks that read [`chat_cmd.rs`](../apps/rocm/src/chat_cmd.rs)'s source for the `Command::Chat` handler's wiring (`command_chat_interactive_routes_to_dash_run_chat_not_tui`, `command_chat_interactive_notes_dropped_provider_flag`, `command_chat_honors_chat_mock_and_keeps_prompt_passthrough`, `command_chat_reads_prompt_from_piped_stdin`) live in that module's own `mod tests`. -- [`chat/turn.rs`](../apps/rocm/src/chat/turn.rs) — mechanical relocation out of `chat.rs`, a child of `chat.rs` and the top of its call graph: the chat turn loop and transcript. `render_chat_prompt_result_with_progress` is the entry point: it picks the assistant model, answers an install request that names no folder with the folder-needed text, builds the system prompt, asks the provider (or takes a tool call the intent heuristics propose when no model server is ready), runs the read-only tool calls the reply requests through the bridge, summarizes their output (through `chat/summaries.rs`, or by asking the local model for a follow-up) and renders the transcript, returning a `ChatPromptResult` (the rendered text and the approval request, if the assistant asked for a change). It owns `ChatPromptResult` and `ChatToolRunResult`, the system prompt (`ROCM_CHAT_TOOL_SYSTEM_PROMPT`, which `rocm_chat_tool_system_prompt` joins to the compiled-in assistant skill at `skills/rocm-cli-assistant/SKILL.md`, and `rocm_chat_tool_system_prompt_for_host`, which grounds it in the machine it answers for), `append_chat_tool_results` and the helpers around it (the `local_*` decisions about intermediate and final replies and the missing-service text, `deterministic_mutating_tool_call_for_prompt` and `supplemental_read_only_tool_call_for_prompt`, the tool-call display labels, `mcp_tool_result_is_error`, `visible_chat_content` which strips reasoning blocks, and `render_install_sdk_folder_needed_chat_text`). `render_chat_prompt_result_with_progress` and `ChatPromptResult` are `pub(super)` (called from `chat.rs`), `rocm_chat_tool_system_prompt_for_host` is `pub(crate)` and re-exported from `chat.rs` for `dash.rs`, and the rest is private. Its edges out are `chat/intent.rs`, `chat/mcp_bridge.rs`, `chat/summaries.rs`, `tool_policy.rs`, `rocm_argv.rs`, `freeform_planner.rs` (`format_structured_tool_call`), `engine_runtime_select.rs`, `managed_service_status.rs`, `chat_host_facts.rs` and `providers`; nothing below it calls back. Most of the former `chat.rs` tests moved with it into its own `mod tests`, with their original names. -- [`chat/summaries.rs`](../apps/rocm/src/chat/summaries.rs) — full domain extraction, a leaf child of `chat.rs`: the deterministic summaries of the read-only tool output the assistant reads back. `deterministic_chat_tool_summary` is the entry point the turn loop calls; it tries `deterministic_rocm_tool_summary` (`examine`), `deterministic_model_tool_summary` (model recipes, with `deterministic_engine_fit_summary` and `deterministic_available_engine_names`) and `deterministic_combined_status_tool_summary` (ComfyUI, port status, engine inventory and services, via the `deterministic_*_tool_summary` functions) in that order, and `deterministic_summary_can_stand_alone` says whether a summary may replace the model's own follow-up. The row types and parsers behind them (`DeterministicModelRecipe`, `DeterministicServiceRow`, `DeterministicEngineRow`, the `parse_deterministic_*` functions and their line helpers), `chat_tool_value` and `managed_service_running_state`, the status-to-running-state mapping that the services tool text in `chat/mcp_bridge.rs` also uses, live here too. `deterministic_chat_tool_summary`, `deterministic_summary_can_stand_alone` and `managed_service_running_state` are `pub(super)`, called from `chat/turn.rs` (and `chat/mcp_bridge.rs` for the last); `deterministic_rocm_tool_summary` is `pub(super)` for `chat/turn.rs`'s tests, and `deterministic_comfyui_tool_summary` stays `pub(crate)` for `comfyui.rs`'s tests, reached through `chat.rs`; the rest is private. Its only edges out are `providers` (the assistant model ids), `managed_service_status::friendly_engine_label` and `rocm_core::placeholder::empty_as_unknown`; nothing here calls back into `chat.rs`. The tests of the parsers, `managed_service_running_state` and the summary builders that need no chat turn live in this module's own `mod tests`; the tests that run a summary through the turn loop's follow-up decision stay in `chat/turn.rs`. -- [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs) — mechanical relocation out of `chat.rs`, a leaf child of `chat.rs`: the MCP bridge and in-process command execution behind the assistant's tools. `run_internal_mcp_call` is the tool dispatch (`rocm mcp-call`, the dash execution seam and the assistant's read-only path all end in it): it validates the call through `tool_policy.rs`, refuses a state-changing tool unless mutation was allowed, then runs the tool in process or hands an approved `rocm` command to a child process. `run_rocm_read_only_in_process` is the in-process runner for the read-only `rocm` commands the assistant may ask for, `run_rocm_command_for_paths` and `run_rocm_capture_for_paths` wrap a command's output as a `CommandCapture`, and `internal_mcp_arguments`, `internal_mcp_tool_success` and `internal_mcp_tool_result_from_command` build the MCP tool result, and `mcp_tool_result_text` reads the text back out of one. It also holds `run_chat_read_only_tool` (the assistant's own read-only path), the `path_exists` and `port_status` tools (`run_chat_path_exists_tool`, `run_chat_port_status_tool`, with `loopback_tcp_port_is_reachable` and `loopback_host_key`), `render_services_tool_result_text` (the text of the `services` tool), the `install sdk --dry-run` argument and preview helpers (`internal_mcp_install_sdk_args`, `render_install_sdk_dry_run_for_args`) and the `logs` flag parsers (`parse_optional_query`, `parse_optional_lines`). `run_internal_mcp_call` is `pub(crate)` and re-exported from `chat.rs` for `main.rs` and `dash_seam.rs`; `run_chat_read_only_tool`, `loopback_host_key` and `mcp_tool_result_text` are `pub(super)` for the turn loop in `chat/turn.rs`, and `run_chat_path_exists_tool` and `mcp_tool_result_text` are also read by the command-preview property tests in `chat.rs`; the rest is private. Its edges out are `tool_policy.rs`, `rocm_argv.rs`, `chat/summaries.rs` (`managed_service_running_state`), `freeform_planner.rs` (the `natural_language_plan` tool), `providers` (the tool-call type) and the crate-root renderers and bridge builders; nothing in it calls back into the turn loop, its tests included. Its tests (the `logs` flag parsers, `mcp_tool_result_text`, the services text, the `proposal_action` tool, the in-process read-only commands, `natural_language_plan` and the port check) live in its own `mod tests`, with their original names. -- [`chat/intent.rs`](../apps/rocm/src/chat/intent.rs) — mechanical relocation out of `chat.rs`, a leaf child of `chat.rs`: the prompt-intent heuristics, which decide from a user's latest message alone what it asks for. `fallback_rocm_tool_call_for_prompt` maps a prompt to the read-only or approval-gated tool call the assistant proposes without asking the local model (with `fallback_config_tool_call_for_prompt`, `fallback_engine_list_tool_call` and `fallback_services_list_tool_call` behind it), `prompt_can_use_read_only_without_local_assistant` says whether a status question can be answered before any model server is up, and `install_sdk_chat_approval_for_prompt` (with `install_sdk_without_prefix_chat_approval`) turns an install or setup request into the `rocm install sdk` approval request. The phrase lists live in the `prompt_asks_running_or_status`, `prompt_asks_engine_install_state`, `prompt_mentions_serving_engine_or_service`, `prompt_requests_rocm_install_or_setup` and `prompt_requests_install_action` predicates, and `latest_user_chat_message` cuts the newest message out of the conversation text the chat builds around it, so older words never steer these heuristics; it moved here with the heuristics because three of them call it, and leaving it with the turn loop would make the two modules call each other. Ten of the functions are `pub(super)`, called from `chat/turn.rs`; the other three are private. Its edges out are [`prompt_text.rs`](../apps/rocm/src/prompt_text.rs), [`rocm_argv.rs`](../apps/rocm/src/rocm_argv.rs), `tool_policy.rs` (`ChatToolApprovalRequest`), `freeform_planner.rs` (`format_structured_tool_call`) and `providers` (the tool-call type); nothing in it calls back into `chat/turn.rs` or `chat.rs`. Its tests, the `fallback_tool_call_*` family and the install-intent checks that call the heuristics directly, live in its own `mod tests`, with their original names. -- [`chat_cmd.rs`](../apps/rocm/src/chat_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm chat`'s command handler (`run_chat_command`, the body of the `Command::Chat` arm of `dispatch()`), which hands off to the dashboard chat (`dash::run_chat`) in a terminal with no `--prompt` and otherwise prints the reply or status screen through `chat::render_chat_prompt_text`/`chat::render_chat_text`. It is a module of its own, not part of [`chat.rs`](../apps/rocm/src/chat.rs), because it calls into both `chat.rs` and [`dash.rs`](../apps/rocm/src/dash.rs) while `dash.rs` already calls into `chat.rs`; this module depends on both and neither depends on it. `Provider` lives in [`cli.rs`](../apps/rocm/src/cli.rs) and `ChatInferenceParams` stays in [`main.rs`](../apps/rocm/src/main.rs); `run_chat_command` is `pub(crate)` and re-imported there for `dispatch()`. Four source-text tests in this module's own `mod tests` read this file and assert on the handler's text, so a rename of the function or of the calls they look for has to be made there too. -- [`chat_host_facts.rs`](../apps/rocm/src/chat_host_facts.rs) — full domain extraction. -- [`cli.rs`](../apps/rocm/src/cli.rs) — the `rocm` command line definition: `Cli`, `Command`, the subcommand enums nested under it (`BenchCommand`, `InstallTarget`, `EnginesCommand`, `RuntimesCommand`, `StorageCommand`, `ComfyuiCommand`, `ServicesCommand`, `AutomationsCommand`, `ConfigCommand`, `SetupCommand`) and re-exports the clap value enums behind `--provider`, `--device`, `--framework` and similar arguments, which [`cli_args.rs`](../apps/rocm/src/cli_args.rs) defines, with `SUPPORTED_ENGINES` (the `--engine` choices). Like [`apps/rocmd`](../apps/rocmd/src/cli.rs)'s `cli.rs`, it holds definitions only: the `dispatch()` that matches on `Command` stays in [`main.rs`](../apps/rocm/src/main.rs). Declaration order sets the order of every nested `--help` command list (the top-level list is sorted alphabetically by `cli_command()` in `main.rs`), so reordering variants reorders help output. Its items are `pub(crate)` and re-imported in `main.rs`, so other modules keep reaching them as `crate::Command`, `crate::Provider` and so on; [`bootstrap.rs`](../apps/rocm/src/bootstrap.rs) and [`remote/mod.rs`](../apps/rocm/src/remote/mod.rs) own their enums and appear in `Command` as a single variant each. The tests that parse the tree or render its help live in its own `mod tests`. -- [`cli_args.rs`](../apps/rocm/src/cli_args.rs) — mechanical relocation out of [`cli.rs`](../apps/rocm/src/cli.rs), owns types: the clap value enums behind `--provider`, `--device`, `--framework` and similar arguments (`Provider`, `DevicePolicyArg`, `FrameworkArg`, `InstallFormat`, `WatcherModeArg`, `TelemetryModeArg`, `SandboxToolArg`, `PermissionsModeArg`) and the conversions from a value enum to its domain type. `cli.rs` re-exports every one, so other modules keep reaching them as `crate::cli::Provider` and so on. Moved so `cli.rs`, which every new subcommand grows, stays under the module size limit. -- [`cli_audit.rs`](../apps/rocm/src/cli_audit.rs) — mechanical relocation, no owned types: the CLI audit and lifecycle log (`record_cli_audit_event`, plus the helpers behind it that write `logs/cli-lifecycle.log` and the per-action files under `logs/cli/`). Its production code depends only on `rocm-core`. `record_cli_audit_event`, `cli_lifecycle_log_path` and `sanitize_log_value` are `pub(crate)` and reached from other modules as `crate::` through a re-import in [`main.rs`](../apps/rocm/src/main.rs); every other item is private. The two regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::`. -- [`cli_progress.rs`](../apps/rocm/src/cli_progress.rs) — shared CLI-output component (`Spinner`, `AnimatedSpinner`). -- [`cli_report.rs`](../apps/rocm/src/cli_report.rs) — shared CLI-output component (`ActionReport`, `write_marked_row`, `JsonOrText`/`print_json_or_text`). -- [`comfyui.rs`](../apps/rocm/src/comfyui.rs) — full domain extraction; serves the `comfyui` subcommand, whose command enum (`ComfyuiCommand`) lives in [`cli.rs`](../apps/rocm/src/cli.rs) while its dispatch fn `run`, the body of the `Comfyui` arm of `dispatch()` in [`main.rs`](../apps/rocm/src/main.rs), is defined here (unlike [`bootstrap.rs`](../apps/rocm/src/bootstrap.rs) above, which owns the enum as well). It owns that dispatch fn, which also records the audit event for each ComfyUI action, the ComfyUI types and constants, the install and state paths, the manifest and state files, `status` and `logs` rendering, and the helpers that run a Python child and capture its output. Choosing the ROCm runtime and building its environment ([`comfyui/runtime_env.rs`](../apps/rocm/src/comfyui/runtime_env.rs)), the process lifecycle ([`comfyui/process.rs`](../apps/rocm/src/comfyui/process.rs)) and the install ([`comfyui/install.rs`](../apps/rocm/src/comfyui/install.rs)) are in child modules, listed below with the other `apps/rocm` modules; `start`, `stop` and `install` are re-exported from them so callers still write `comfyui::start`, `comfyui::stop` and `comfyui::install`. -- [`config_cmd.rs`](../apps/rocm/src/config_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm config`'s command handler (`config()`), the provider-key prompt it uses (`read_provider_key_from_user`) and the text `rocm config show` prints (`render_config_text`, `telemetry_policy_summary`). `ConfigCommand` lives in [`cli.rs`](../apps/rocm/src/cli.rs). `config()` and `render_config_text` are `pub(crate)`: `dispatch()` calls `config()` and [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs)'s read-only handling of `rocm config show` calls `render_config_text`, both through re-imports in `main.rs`; the other two functions are private. The two `render_config_text` regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::`. -- [`dash.rs`](../apps/rocm/src/dash.rs) — full domain extraction. -- [`dash_seam.rs`](../apps/rocm/src/dash_seam.rs) — full domain extraction. -- [`diagnose_cmd.rs`](../apps/rocm/src/diagnose_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: the command handlers for `rocm diagnose` and `rocm fix` (`diagnose()`, `fix()`) and the report step behind `rocm diagnose --report` (`show_prepared_report`, `prepare_cli_report`, `perform_delivery`, `established_entry`). `diagnose()` and `fix()` are `pub(crate)` and re-imported in [`main.rs`](../apps/rocm/src/main.rs) for `dispatch()`; the other functions are private. `diagnose()` gets its `--model` verdict from [`model_fit.rs`](../apps/rocm/src/model_fit.rs), and `fix()` returns a failing exit code through `FixExitCode`, which stays in `main.rs` with the other exit-code plumbing. The report and delivery regression tests live in this module's own `mod tests`; the exit-code tests stay in `main.rs`. -- [`diagnose_model.rs`](../apps/rocm/src/diagnose_model.rs) — full domain extraction: the binary's side of `rocm diagnose --model`'s GGUF context-size estimate — the `--kv-cache-type` value enum, the model question the flags ask (`ModelQuery`), the note `--report` prints when it ignores them, and `attach_gguf_estimate`, which adds the estimate and the device-visibility-mask caveat over `amd-smi`'s rows to a readiness answer. Reached by qualified path. The estimate itself is in [`model_readiness.rs`](../crates/rocm-core/src/model_readiness.rs) and the `gguf*` modules; the `Diagnose` variant stays in [`main.rs`](../apps/rocm/src/main.rs), `diagnose()` is in [`diagnose_cmd.rs`](../apps/rocm/src/diagnose_cmd.rs), and the curated-model host assessment it predates (`assess_model_on_this_host` and its helpers) is in [`model_fit.rs`](../apps/rocm/src/model_fit.rs). -- [`driver_install.rs`](../apps/rocm/src/driver_install.rs) — mechanical relocation, owns types (part of [`main.rs`](../apps/rocm/src/main.rs)'s Phase 6a split, ROCMAI-82; see the Phase 6a variant note above): `install_driver()`/`reconcile_driver_install()`, running an approved plan's shell commands, and the install state persisted to `state.json` (`DriverInstallState`, `DriverReconciliationState` and the passive-check types). The plan it runs lives in [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs), which this module imports from and which does not import from it; the os-release the plan is built from comes from `real_os_release` in [`hardware_root.rs`](../crates/rocm-core/src/hardware_root.rs), the one reader of the real host's os-release. Its `pub(crate)` surface is `install_driver` and `reconcile_driver_install`, `DriverInstallResult` and `DriverInstallError` (read from `install_cmd.rs`'s `install()`), `driver_install_state_path`, and a re-export of `host_install_driver_only_reports` for [`chat.rs`](../apps/rocm/src/chat.rs) and [`freeform_planner.rs`](../apps/rocm/src/freeform_planner.rs). -- [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs) — full domain extraction, crate-level (split out of [`driver_install.rs`](../apps/rocm/src/driver_install.rs)): the plan `rocm install driver` builds and prints. It owns the model (`DriverInstallPlan` with `execution_commands`, `DriverPlanCommand`, `DriverCommandPhase`, and `PrivilegeEscalation`, which decides whether a generated shell line gets a `sudo ` prefix), `render_driver_install_plan` with its approval label, the helpers the builders share (`driver_command`, `driver_root_preflight_checks`, `resolve_shell_default_template`, `is_safe_shell_token`), and the builders: `build_driver_install_plan_read`, which `install_driver` calls with the real host's os-release, and `build_driver_install_plan_at` beneath it, with the apt, dnf and SLES plans, the `ID_LIKE` fallback, the repository URL helpers, `resolve_repo_version_expr` (the `ROCM_CLI_AMDGPU_DRIVER_VERSION` override and the retired version variables it refuses), and the refusal plans for an unreadable os-release or an invalid override. It also owns `install_driver_only_reports_on`/`host_install_driver_only_reports` (true on native Windows, where the plan only reports); `driver_install.rs` re-exports the latter. It declares the child module [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs) and re-exports its `wsl_rocdxg_driver_plan`. Production code in this file uses only `std` and `rocm_core`, and nothing here depends on `driver_install.rs`. The model types and their fields, `execution_commands`, `PrivilegeEscalation::detect`, `driver_command`, `render_driver_install_plan`, `build_driver_install_plan_read`, `install_driver_only_reports_on` and `host_install_driver_only_reports` are `pub(crate)`, as is `invalid_driver_version_override_plan`, which a test that stays in `driver_install.rs` builds a plan with; the rest is private. Its test module is `pub(crate)` so `driver_install.rs`'s tests can reuse its `test_examine` and `os_release_found` helpers. It holds the plan-builder tests, including the one that keeps the supported-distro matrix in step with `dkms_driver_plan_is_supported` in `rocm-core`, and the tests of the template resolver and the shell-token filter. -- [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs) — full domain extraction, a child of `driver_plan.rs` that depends on the plan model, `driver_command`, `driver_root_preflight_checks` and `resolve_shell_default_template` in its parent, and on `truthy_env` in [`therock.rs`](../apps/rocm/src/therock.rs) (split out of [`driver_install.rs`](../apps/rocm/src/driver_install.rs)): the WSL2 rocDXG plan. `wsl_rocdxg_driver_plan` builds the plan that installs the `rocdxg-roct` package, `resolve_rocdxg_verification` decides how that download is authenticated (a supplied digest, the digest pinned for the version in `ROCDXG_PINNED_DIGESTS`, or the explicit opt-out), and `wsl_rocdxg_refusal_plan` is the plan that installs nothing and says why when it cannot be authenticated or the version is not a well-formed package version. `ROCDXG_PINNED_DIGESTS` is the trust anchor an unattended root install is checked against, so a change to it is a security-relevant diff; it moved byte for byte. `wsl_rocdxg_driver_plan` is `pub(crate)` and re-exported by `driver_plan.rs` (its builders call it, and tests in `driver_install.rs` use it as a plan fixture); everything else in production code is private. Its tests are the `wsl_rocdxg_*` plan tests, including the one that runs the generated digest step against a real file on Unix. The test-only `scoped_rocdxg_env` helper that clears the rocDXG environment lives here too, `pub(super)` for the plan-builder tests in `driver_plan.rs`. -- [`endpoint_keys.rs`](../apps/rocm/src/endpoint_keys.rs) — mechanical relocation, no owned types, reached by qualified path. -- [`engine_install_env.rs`](../apps/rocm/src/engine_install_env.rs) — mechanical relocation out of [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), no owned types: which runtime an engine installs into and where its environment lives. `engine_manages_own_runtime` says whether an engine brings its own runtime; `env_root_for_engine_install`, `env_root_for_runtime` and `env_root_for_self_managed_engine` resolve the engine environment root; `runtime_manifest_for_selector` resolves a selector to one installed runtime; `runtime_key_for_python` names the runtime whose install root contains an interpreter (the private `runtime_key_owning_python` is the decision behind it). It is the neutral layer that [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs) and [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) (with its `torch_alignment.rs` child) both import from, so neither imports the other for these helpers. It imports `recover_setup_runtime_registration` from [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs), `select_runtime_manifest` and `validate_runtime_manifest_for_activation` from [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs), and the runtime-manifest model from [`therock.rs`](../apps/rocm/src/therock.rs); it does not go through the re-exports in [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs), which would lead back to it via `runtime_services.rs`. Its functions are `pub(crate)` for those two modules plus [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) and [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs). Their tests moved with them. -- [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs) — mechanical relocation, owns private types (Phase 6f, ROCMAI-213): resolving an engine's binary path (`resolve_engine_binary_path`, `resolve_engine_binary_path_with_paths`, `find_engine_plugin_binary`), the request entry points, which either answer from the in-process built-in handler or run the resolved engine binary with `stdio` (`engine_request`, `engine_request_with_env_root`, and `engine_stdio_child_request`, which hands the child to the stdio client `rocm` shares with `rocmd`, from [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs), and chooses what `rocm` asks of it: the app paths and engine environments root for the child, progress for an install, and the child's stderr forwarded to the terminal), the `ScopedEnvVar`/`with_scoped_builtin_engine_env` env-scoping helpers and the `BUILTIN_ENGINE_ENV_LOCK` mutex they serialize on, `builtin_engine_request`, `run_builtin_engine_stdio`), and the built-in HTTP-serving path (`builtin_engine_available`, `run_builtin_engine_serve_http`, `builtin_engine_serve_http_args`). One item that sits physically inside this span in `main.rs` stayed there instead of moving: `impl From for WatcherMode` is unrelated clap-arg conversion that merely happened to be interleaved between `find_engine_plugin_binary` and `engine_request` (it has since moved to [`cli.rs`](../apps/rocm/src/cli.rs), next to the enum it converts). `resolve_engine_binary_path`, `resolve_engine_binary_path_with_paths`, `engine_request`, `engine_request_with_env_root`, `builtin_engine_available`, and `builtin_engine_serve_http_args` are `pub(crate)` and read from other modules (for example [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs), [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) and [`service_launch.rs`](../apps/rocm/src/service_launch.rs)), not from `main.rs`. `run_builtin_engine_stdio` and `run_builtin_engine_serve_http` are `pub(crate)` and reached directly from `main.rs`'s `dispatch()` (the `Command::EngineStdio` and `__engine-serve-http` arms); `find_engine_plugin_binary`, `with_scoped_builtin_engine_env`, `builtin_engine_request`, and `ScopedEnvVar` have no callers outside this module and stay private. -- [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs) — mechanical relocation, owns types (Phase 6f, ROCMAI-215): deciding which runtime/env a `serve`/`engines install` invocation resolves to (`EngineSelection`, `resolve_engine_selection`, `validate_engine_selection_runtime`, `single_ready_runtime_key`, `resolve_runtime_selector_to_exact_key`), small argv-building helpers used when relaunching a managed engine (`engine_recipe_json_arg`, `parse_engine_recipe_json_arg`, `daemon_run_argv`, `managed_service_launcher_path`), the `ROCM_CLI_*` environment variables every managed child inherits (`app_path_env_var_values`/`app_path_env_var_refs`, over [`AppPaths::env_vars`](../crates/rocm-core/src/paths.rs)), and polling a freshly launched service until it can answer inference requests (`wait_for_service_http_ready`, `wait_for_service_http_ready_with_progress`, `service_http_readiness_paths`, `http_get_local_service`, `http_post_local_service_json`, `service_http_readiness_response_ready`, `lemonade_health_ready_for_model`, `model_list_ready_for_model`, `service_model_gpu_ready`, `service_model_reports_rocm_backend`, `service_model_names_match`). `single_ready_runtime_key` does not decide which runtimes count as ready: it asks [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs)'s `select_single_ready_runtime`, which `rocm comfyui install` shares. `const fn status_for_readiness` sits physically interleaved in this span in `main.rs` but stayed there instead of moving — it has callers outside this cluster ([`service_launch.rs`](../apps/rocm/src/service_launch.rs) and [`service_control.rs`](../apps/rocm/src/service_control.rs)'s `record_restart_readiness`, which `restart_internal_managed_service_with` calls), so it stays a shared crate-root function, reached only from this module's own tests, via `use crate::status_for_readiness;`. Which items are `pub(crate)` and who calls them is documented in the module's own doc comment rather than repeated here. The cluster's regression tests live in the module's own `mod tests`. What remains in `main.rs` immediately after this cluster is `treat_as_natural_language`, dispatch-adjacent natural-language-invocation routing left over from an earlier phase (ROCMAI-87), explicitly out of scope and untouched by this split. -- [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs) — mechanical relocation, owns private types (Phase 6a): `engines()` (the `rocm engines` command), `ensure_self_managed_engine_ready` (the readiness check [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) runs for engines that bring their own runtime) and `env_root_for_service` (read from [`service_launch.rs`](../apps/rocm/src/service_launch.rs) and [`service_control.rs`](../apps/rocm/src/service_control.rs)). Which runtime an engine installs into and where its environment lives is answered in [`engine_install_env.rs`](../apps/rocm/src/engine_install_env.rs), which this module imports from. This module also calls into [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) for `settle_engine_install` and the host system-package installs; that module does not import this one. -- [`examine_cmd.rs`](../apps/rocm/src/examine_cmd.rs) — mechanical relocation, dispatch-adjacent, owns private types: `rocm examine`'s command handler (`examine()`), which prints the human report through [`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs)'s `examine_human_report`, or with `--json` the document built from the private `ExamineJson`/`ExamineJsonSummary` types (the `Examination` verbatim plus a summary of what the CLI knows but the probe cannot). `examine()` is `pub(crate)` and re-imported in [`main.rs`](../apps/rocm/src/main.rs) for `dispatch()`. No test in the crate calls it or builds the document directly. -- [`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs) — mechanical relocation: the launch-summary/examine text surfaces (`render_launch_summary`, `render_examine_text`, `render_examine_text_with_paths`, `examine_human_report`, `render_examine_plain_header`, `plain_status_label`) and the engine-inventory listing shared by `rocm engines` and `rocm examine` (`write_default_engine_legend`, `render_engine_inventory_text_with_paths`, `append_examine_runtime_state`, `append_examine_engine_inventory`, `append_engine_detect_summary`, `friendly_engine_runtime_kind`, `friendly_engine_detect_notes`, `friendly_engine_detect_note_fallback`, `engine_runtime_status_label`). The `DEFAULT_ENGINE_MARKER` constant is shared by both engine-inventory renderers so the two copies cannot drift apart. The `rocm model` catalog renderer is not here; it lives in [`model_catalog_text.rs`](../apps/rocm/src/model_catalog_text.rs), and nothing in this file calls into it. [`examine_cmd.rs`](../apps/rocm/src/examine_cmd.rs)'s `examine()`, which the `Command::Examine` arm calls, imports and calls `examine_human_report`; `main.rs`'s own `launch_default` calls `render_launch_summary`, re-imported there. `render_examine_text`, `render_examine_text_with_paths` and `render_engine_inventory_text_with_paths` are `pub(crate)`, read from [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs)'s read-only command runner; `render_engine_inventory_text_with_paths` is also read from [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs)'s `render_engine_inventory_text`; `append_examine_runtime_state` is also `pub(crate)`, read only from [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs)'s own test module, so `main.rs`'s re-import of it is itself `#[cfg(test)]` rather than carrying an otherwise-unused import into a non-test build. Every other item in this list has no caller outside this module and stays private. This module also reaches items that live at the crate root because they have other callers: `engine_inventory()` (also read from [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs) and [`bridge_snapshot.rs`](../apps/rocm/src/bridge_snapshot.rs)), `PlatformRuleOut` and `engine_ruled_out_by_platform` (defined in [`model_fit.rs`](../apps/rocm/src/model_fit.rs) and re-imported in `main.rs`) — all reached via `use crate::{...};`. The regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::` and `write_test_pip_runtime`/`runtime_manifest_path` through `crate::test_support::`/`crate::runtimes_cmd::`. Its tests do not call into `model_catalog_text.rs`: the test of the note the verbose `rocm model` listing prints for a rule-out engine lives beside that renderer. -- [`freeform_answer.rs`](../apps/rocm/src/freeform_answer.rs) — mechanical relocation, no owned types: the answers a freeform request can get without running a command — `render_freeform_read_only_answer`, which answers a single approval-free `examine`, `comfyui status` or `comfyui logs` action, and `render_freeform_examine_answer`, the plain-language ROCm status it prints for `examine`. `run_freeform` in [`main.rs`](../apps/rocm/src/main.rs) is the only caller of the first, which is `pub(crate)` and re-imported there; the second is private. Besides `chat.rs` (`any_substring`, re-exported there from [`prompt_text.rs`](../apps/rocm/src/prompt_text.rs)), it depends on `comfyui.rs`, `runtimes_cmd.rs` and `therock.rs`, none of which calls back into it. No unit test calls either function directly. -- [`freeform_execution.rs`](../apps/rocm/src/freeform_execution.rs) — mechanical relocation, dispatch-adjacent, owns a `pub(crate)` type (as of Phase 6e's follow-up, ROCMAI-726; see the Phase 6a variant note above for the owned-types pattern). Holds the freeform natural-language planner's plan-*execution*/consent half that [`freeform_planner.rs`](../apps/rocm/src/freeform_planner.rs) below deliberately left out: `validate_freeform_execution_action()`, `prepare_freeform_execution()`, `apply_freeform_execution_consent()`, `render_freeform_execution_header()`, and the `pub(crate)` `FreeformExecution` struct that `prepare_freeform_execution` returns and `render_freeform_execution_header` consumes. `main.rs`'s `execute_freeform_next_action()` and `run_freeform()` stay in `main.rs` — both are dispatch-level, not part of deciding whether a plan's next action is safe to execute — and `execute_freeform_next_action()` calls in via the unqualified re-import `use crate::freeform_execution::{prepare_freeform_execution, render_freeform_execution_header};` (`run_freeform()` only calls `execute_freeform_next_action()`, never this module directly), matching [`driver_install.rs`](../apps/rocm/src/driver_install.rs)'s dispatch-adjacent form rather than `freeform_planner.rs`'s own qualified-path form. `prepare_freeform_execution` takes the already-built `plan` by value rather than rebuilding it from `request`/`paths`/`config` (ROCMAI-725's single-build guarantee, inherited unchanged from `main.rs`); `prepare_freeform_execution`/`render_freeform_execution_header` are `pub(crate)` for that cross-module call; `FreeformExecution` was already `pub(crate)` (read directly by `main.rs` and this module's own tests); `validate_freeform_execution_action`/`apply_freeform_execution_consent` have no caller outside this module and stay module-private, unchanged from before the move. The cluster's six regression tests moved out of `main.rs`'s shared `mod tests` into this module's own `mod tests`, inheriting the qualified `freeform_planner::` path they already used to reach `freeform_planner.rs`'s items as `main.rs`'s former tests — this module reaches in from outside using the same qualified path `main.rs` and `providers.rs`'s tests use (unlike `chat.rs`/`comfyui.rs`, which import it unqualified). -- [`freeform_planner.rs`](../apps/rocm/src/freeform_planner.rs) — full domain extraction (Phase 6e, ROCMAI-87). Owns the freeform natural-language planner cluster's types (`StructuredRequestPlan`, `PlannerIntent`, `PlannedToolCall`, `FreeformPlanAction`, `ProviderPlannerResponse`, `ProviderPlannerToolCall`, all module-private except `FreeformPlanAction`, `StructuredRequestPlan` and `PlannedToolCall`, which are `pub(crate)`, and `ProviderPlannerToolCall`, `pub(crate)` together with `validate_provider_planner_tool_call` and `planner_failure_note` so [`chat.rs`](../apps/rocm/src/chat.rs)'s command-preview property tests can drive the planner's guards), the deterministic plan builder (`build_freeform_plan*`), the provider-assisted path (`resolve_freeform_plan_with_provider`, `build_provider_planner_prompt`, `provider_planner_response_to_plan`, `validate_provider_planner_tool_call`), and plan rendering (`render_structured_request_plan`). [`main.rs`](../apps/rocm/src/main.rs) calls `build_freeform_plan_with_context`/`render_structured_request_plan` directly for the dispatch/review flow ([`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs)'s `render_launch_summary` → `host_default_engine` is another call into this module, unrelated to planning: bare `rocm`'s non-interactive launch summary), while [`freeform_execution.rs`](../apps/rocm/src/freeform_execution.rs) above calls `plan_next_action`/`format_structured_tool_call` for the execution flow and reads `FreeformPlanAction`/`StructuredRequestPlan` by type for its execution-validation functions — those live there, not here, because they decide whether a plan's next action is safe to *execute*, a dispatch-adjacent concern distinct from *building* the plan; `main.rs`'s `run_freeform` builds a plan exactly once via `build_freeform_plan_with_context` and threads that same value through `execute_freeform_next_action` to `prepare_freeform_execution` rather than rebuilding it (ROCMAI-725: building a plan can call a configured cloud `planner_provider`, which is not guaranteed deterministic, so a second independent build could silently disagree with the first). [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs)'s `natural_language_plan` MCP tool gets the same single-build guarantee from `plan_freeform_request_with_context`, which builds once and returns both the rendered text and the next action; `chat/turn.rs` and `chat/mcp_bridge.rs` also call `format_structured_tool_call` directly, like [`comfyui.rs`](../apps/rocm/src/comfyui.rs) does, while [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs)'s `validate_serve_command_safety` holds the four rules a model-proposed `serve` must satisfy (no public bind, no CPU device, a loopback host, `--managed` without `--foreground`), reading `serve_args_request_cpu_device` from [`rocm_argv.rs`](../apps/rocm/src/rocm_argv.rs) for the no-CPU-fallback rule; `validate_provider_planner_tool_call` calls it from its `serve` branch with the actor `provider planner` (`validate_chat_rocm_command_safety` calls it with `local assistant`, so the two refusals differ only in that name), and hands an `install sdk` call to `tool_policy::validate_chat_rocm_command_safety`. `host_default_engine`, `build_freeform_plan_with_context`, `render_structured_request_plan`, `plan_next_action`, `plan_freeform_request_with_context` and `provider_planner_response_to_plan` are `pub(crate)` for these reasons, as is `plan_driver_request` (read from [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs)'s test module); `format_structured_tool_call` lives in [`rocm_argv.rs`](../apps/rocm/src/rocm_argv.rs) and is re-exported here with `pub(crate) use`, so the callers above keep their `freeform_planner::` path, while the planner's own argv lookups call `rocm_argv`, its phrase and engine readers call [`prompt_text.rs`](../apps/rocm/src/prompt_text.rs) and its safety check calls `tool_policy.rs`, directly: the planner no longer imports `chat`, and only `chat` imports the planner (`plan_freeform_request_with_context`); a source-scan test in `xtask` ([`chat_import_contract.rs`](../xtask/src/chat_import_contract.rs)) fails if this file or the three leaf modules above import `chat` in non-test code; `freeform_plan_next_action` and `render_freeform_plan` are test-only (`#[cfg(test)]`) and `FreeformPlanAction` was already `pub(crate)` before the split. `parse_freeform_invocation`/`should_treat_as_freeform` (deciding whether an invocation is freeform at all) stay in `main.rs`, a dispatch-level concern outside both this module and `freeform_execution.rs`. The cluster's regression tests live in `freeform_planner.rs`'s own `mod tests`; the handful of `main.rs` tests that exercise the invocation classifier/clap-suggestion-avoidance stay in `main.rs`'s shared `mod tests`, since neither is specific to this module or to `freeform_execution.rs` (and neither touches `freeform_planner::` at all), and the ROCMAI-725 regression tests proving the single-build guarantee live in `providers.rs`'s `mod tests` (reusing its mock local-provider server), reaching this module's items through the qualified `freeform_planner::` path like any other external caller. -- [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs) — mechanical relocation, owns types (Phase 6f, ROCMAI-214): `--device`/`--gpu` parsing (`parse_device_policy`, `parse_gpu_selection`, `parse_gpu_indices_arg`), the managed-launch-lock GPU selection (`select_gpu_indices_under_launch_lock`, `validate_pinned_gpu_index`, `effective_gpu_count`, `auto_select_gpu_indices`, `select_auto_gpu_index`, `busy_gpu_indices`), per-GPU VRAM telemetry (the `GpuVramUsage` type, `gpu_vram_usage`, `simulated_low_vram_usage`, `gpu_vram_usage_amd_smi`, `gpu_vram_usage_sysfs`, `read_drm_vram_usage`, `read_sysfs_u64`, `drm_device_is_amd`, `parse_gpu_vram_usage`), and the serve-plan low-VRAM warning (`gpu_low_memory_warning`, `vram_capacity_is_meaningful`, `serve_gpu_low_memory_warning`), plus the best-effort `amd-smi`-based GPU count (`detect_gpu_count`).Both `amd-smi` probes go through `rocm_core::amd_smi_json` (the `/dev/kfd` pre-flight) with this module's own `AMD_SMI_SERVE_PROBE_TIMEOUT`, whose doc records the resulting worst-case `serve` latency. `const fn device_policy_name` sits immediately after this cluster's last function in the original file but stayed in `main.rs` rather than moving — it already had callers outside the cluster (`engine_ipc.rs`, `service_launch.rs`, `serve_cmd.rs`) plus its own test. `GpuVramUsage` (and its fields), `gpu_vram_usage`, `parse_gpu_indices_arg`, `serve_gpu_low_memory_warning`, and `vram_capacity_is_meaningful` are `pub(crate)` and read from [`model_fit.rs`](../apps/rocm/src/model_fit.rs) (`classify_accelerator_memory`, `host_accelerator_memory`) [`main.rs`](../apps/rocm/src/main.rs) (the `dispatch()` `Command::EngineServeHttp` arm) and [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) (`collect_serve_notes`); `detect_gpu_count`, `gpu_vram_usage`, `parse_device_policy`, `parse_gpu_selection`, `select_gpu_indices_under_launch_lock`, `serve_gpu_low_memory_warning`, and `validate_pinned_gpu_index` are also `pub(crate)` and read from [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs); `parse_device_policy` is also read from [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs)'s `run_builtin_engine_serve_http` and, as of Phase 6f (ROCMAI-209), from [`service_control.rs`](../apps/rocm/src/service_control.rs)'s `restart_child_argv` (moved out of `main.rs` in that same phase, and since relocated from `services_text.rs`). `effective_gpu_count`, `auto_select_gpu_indices`, `select_auto_gpu_index`, `simulated_low_vram_usage`, `gpu_vram_usage_amd_smi`, `gpu_vram_usage_sysfs` (both the Linux and non-Linux `cfg` variants), `read_drm_vram_usage`, `read_sysfs_u64`, `drm_device_is_amd`, `parse_gpu_vram_usage`, `gpu_low_memory_warning`, and `busy_gpu_indices` have no callers outside this module and stay private. The cluster's regression tests live in `gpu_policy.rs`'s own `mod tests`; two small test-only fixture builders (`vram`, `host_gpu`) are duplicated rather than shared, since `serve_cmd.rs`'s own `serve_notes_pair_low_vram_with_the_vllm_utilization_hint` (testing `collect_serve_notes`) needs them too. -- [`install_cmd.rs`](../apps/rocm/src/install_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm install`'s command handler (`install()`, for the `sdk` and `driver` targets), the `--version`/`--build-date` selector parsing and display it uses (`therock_install_version_selector`, `therock_install_version_selector_display`) and `sdk_install_request`, which maps the parsed `install sdk` arguments onto a `therock::SdkInstallRequest` and moved here from [`chat.rs`](../apps/rocm/src/chat.rs) with its two tests. `InstallTarget` and `InstallFormat` live in [`cli.rs`](../apps/rocm/src/cli.rs). `install()` is `pub(crate)` and re-imported in `main.rs` for `dispatch()`; `therock_install_version_selector` is `pub(crate)` too, and `chat/mcp_bridge.rs`'s `render_install_sdk_dry_run_for_args` reaches it as `crate::therock_install_version_selector` through the same kind of re-import, which is why `sdk_install_request` lives here and not in `chat.rs`: this module does not depend on `chat.rs`. `sdk_install_request` keeps the `pub(crate)` it had, although only `install()` and the tests call it now. -- [`logging.rs`](../apps/rocm/src/logging.rs) — mechanical relocation, no owned types, reached by qualified path. -- [`managed_service_status.rs`](../apps/rocm/src/managed_service_status.rs) — mechanical relocation, owns types (Phase 6f, ROCMAI-211): managed-service liveness classification (`managed_service_is_live`, `refresh_managed_service_runtime_liveness`, `existing_live_managed_service_in`'s idempotency guard) and the dashboard-sidebar status/counts helpers derived from it (`ManagedServiceSidebarCounts`/`managed_service_sidebar_counts`/`local_server_sidebar_status`), plus the engine display-name helper `friendly_engine_label`, read only by [`chat/summaries.rs`](../apps/rocm/src/chat/summaries.rs). `ManagedServiceSidebarCounts` is `pub(crate)` to match the visibility of the `pub(crate)` functions that return/take it; `friendly_engine_label`, `existing_live_managed_service_in`, `recorded_service_pids`, `refresh_managed_service_runtime_liveness`, `local_server_sidebar_status`, `managed_service_sidebar_counts`, and `load_managed_services` are `pub(crate)` for the same reason — each has a confirmed caller outside this module. [`service_records.rs`](../apps/rocm/src/service_records.rs) uses its liveness helpers (`managed_service_is_live`, `recorded_service_pids`) for the in-use check behind service-record removal and pruning, both of which, like the deferred key cleanup and the reconciliation to `stopped` here, take a recorded process for gone only when `probe_process` confirms it (a process that cannot be queried counts as possibly running; when the deferred cleanup does complete, it also forgets the recorded processes and reads the record as stopped, so a later stop cannot signal a recycled PID; an unconfirmed stop of a container-backed engine, decided by the engine `Stop`, is never completed or read as stopped from the supervisor's PID, and `container_stop_unresolved` makes the in-use check treat it as in use), and `load_managed_services` for prune planning, while [`bridge_snapshot.rs`](../apps/rocm/src/bridge_snapshot.rs) uses `load_managed_services` for the codex-bridge snapshot; [`service_launch.rs`](../apps/rocm/src/service_launch.rs) is the only caller of the `existing_live_managed_service_in` duplicate-launch guard; [`services_text.rs`](../apps/rocm/src/services_text.rs) reads the sidebar helpers; other modules, including [`chat/turn.rs`](../apps/rocm/src/chat/turn.rs), [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs) and [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs), read the registry and liveness helpers. -- [`model_catalog_text.rs`](../apps/rocm/src/model_catalog_text.rs) — mechanical relocation out of `examine_report_text.rs`: the `rocm model` (alias `models`) catalog renderer. `render_model_registry_text_with_context_and_host` prints the curated list grouped by hardware target (`model_catalog_platform_heading`, `model_catalog_header`, `model_recipe_memory_label`, `model_recipe_gpu_fit_label`), and `render_model_registry_verbose_text_with_context_and_host` prints the per-recipe diagnostics behind `rocm model --verbose` (`append_model_recipe_registry_source`, `append_model_recipe_metadata_lines`, `append_model_engine_recipe_settings_lines`, `append_model_recipe_staleness_lines`, `append_model_artifact_lines`, `append_artifact_source_policy_lines`, `artifact_source_policy_label`, `append_model_host_ram_fit_lines`, `append_model_fit_lines`, `append_manual_alternative_lines`, `manual_alternative_recommendations`, `recipe_is_manual_fit`, `append_model_engine_support_lines`, `model_registry_adapter_availability_note`, `recipe_display_ref`, `preferred_engine_action_target`, `model_registry_reason`, plus the small formatters `format_list_or_none`, `format_string_map_or_none`, `format_gib` and `once_per_call`). `format_bytes`, the human-readable size formatter, lives here too. The two renderers and `format_bytes` are `pub(crate)`: [`main.rs`](../apps/rocm/src/main.rs) imports them for the `Command::Model` arm, and [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs) (the verbose renderer), [`storage.rs`](../apps/rocm/src/storage.rs) and [`automations.rs`](../apps/rocm/src/automations.rs) (`format_bytes`) reach them as `crate::`. Every other item, including `model_registry_adapter_availability_note`, is private. The module has no edge to `examine_report_text.rs`; it reaches the engine-availability helpers in [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs), `PlatformRuleOut` and `engine_ruled_out_by_platform_with` at the crate root, and [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs)'s `select_serve_engine`. The catalog's regression tests live in this module's own `mod tests`; they keep the names they had in `examine_report_text.rs`. The `format_bytes` property test's saved failure case lives in [`model_catalog_text.txt`](../apps/rocm/proptest-regressions/model_catalog_text.txt), which proptest finds by the test's source file, so the saved case has to follow the test when it moves (see [Property tests](testing.md#property-tests) for how, which depends on whether the whole file moves). -- [`model_fit.rs`](../apps/rocm/src/model_fit.rs) — mechanical relocation, owns a `pub(crate)` type: answering whether a host can run a model for `rocm diagnose --model` (`assess_model_on_this_host`, `assess_model_with_host_paths`, `assess_model_for_host`), the accelerator-memory fact it rests on (`host_accelerator_memory`, `classify_accelerator_memory`, `examination_reports_amd_gpu`) and the platform gate that rules an engine out (`PlatformRuleOut`, `engine_ruled_out_by_platform`, `unsupported_here_for`). It is a module of its own, rather than part of the `diagnose` handler, so [`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs) and [`model_catalog_text.rs`](../apps/rocm/src/model_catalog_text.rs), which read `PlatformRuleOut` and the platform gate (`engine_ruled_out_by_platform` and `engine_ruled_out_by_platform_with` respectively), do not depend on a command module. It depends on [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) (`select_serve_engine`) and [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs), neither of which depends on it. `assess_model_on_this_host` (called from [`diagnose_cmd.rs`](../apps/rocm/src/diagnose_cmd.rs)), `PlatformRuleOut` and `engine_ruled_out_by_platform` are `pub(crate)`, and [`main.rs`](../apps/rocm/src/main.rs) re-imports the last two so `examine_report_text.rs` reaches them as `crate::` (`model_catalog_text.rs` reaches `PlatformRuleOut` and `engine_ruled_out_by_platform_with` the same way); every other item is private. The cluster's regression tests live in this module's own `mod tests`; the one that re-runs the test binary on a helper test by its full path (`engine_ruled_out_by_platform_gates_aim_on_docker_reachability`) names the helper's new path, `model_fit::tests::docker_unreachable_subprocess_helper`. -- [`prompt_text.rs`](../apps/rocm/src/prompt_text.rs) — text extraction from a natural-language request, shared by `chat/intent.rs`'s prompt-intent heuristics (`fallback_rocm_tool_call_for_prompt`, `fallback_config_tool_call_for_prompt`, `install_sdk_chat_approval_for_prompt` and the `prompt_*` predicates) and the freeform planner, in a leaf module that depends only on `therock::RuntimeVersionSelector` (`tool_policy.rs` does not use it): `any_substring`, the install-folder, TheRock build-date and TheRock version readers (`requested_install_prefix_from_prompt`, `requested_therock_build_date_from_prompt`, `requested_therock_version_from_prompt`, with `requested_bare_install_prefix_from_prompt`, `clean_requested_install_prefix`, `looks_like_user_path` and `looks_like_therock_runtime_version` private beside them) from `chat.rs`, and `infer_engine_from_request` from `freeform_planner.rs`. They moved verbatim, together with `infer_engine_from_request`'s regression test, so that `freeform_planner.rs` no longer imports `chat` for them; `chat.rs` re-exports `any_substring`, which [`freeform_answer.rs`](../apps/rocm/src/freeform_answer.rs) still reaches as `chat::any_substring`. -- [`provider_keys.rs`](../apps/rocm/src/provider_keys.rs) — full domain extraction. -- [`providers.rs`](../apps/rocm/src/providers.rs) — full domain extraction (no dedicated command enum; invoked from the existing chat/config command flows). Keeps the request/response types, the `ProviderAdapter` trait and the `provider_*` dispatch, the `LocalProvider` and `RemoteProvider` implementations, local-service selection (`select_local_chat_service`, `ready_local_services`), the remote model and endpoint resolution, the `ureq` remote transport and the `SseBytesEmitter` trait. The ROCm tool schema, the local HTTP/SSE transport and the provider wire formats live in child modules under `providers/`, below; `providers.rs` imports the request-body builders, response parsers and SSE emitters it calls from `providers/wire.rs`. -- [`providers/tool_schema.rs`](../apps/rocm/src/providers/tool_schema.rs) — full domain extraction, a leaf child of `providers.rs`: the ROCm tool catalog a provider advertises to a model, as OpenAI function definitions (`rocm_openai_tool_definitions`) and reshaped for Anthropic's `tools` field (`rocm_anthropic_tool_definitions`). Both are `pub(super)`, read by the request-body builders in `providers/wire.rs`; `rocm_openai_tool`, the one-tool constructor behind them, is private. Depends on nothing else in `providers`. -- [`providers/local_http.rs`](../apps/rocm/src/providers/local_http.rs) — full domain extraction, a child of `providers.rs`: the local provider's hand-rolled HTTP/1.1 transport. `post_json_to_local_endpoint` (with `post_json_to_local_endpoint_body` and `local_bearer_header`) is the blocking JSON POST; `stream_json_from_local_endpoint` is the streamed POST, which reads the response in whichever body framing the engine answers with (`read_sse_body` picks between `read_chunked_sse_body`, `read_fixed_sse_body` and `read_close_delimited_sse_body` from the headers, via `header_value`) and feeds an `OpenAiSseEmitter`; `body_truncated_at_eof` and `LOCAL_STREAM_TRUNCATED` name the failure when an engine closes the connection mid-answer; `parse_http_endpoint` reads the `http://` endpoint URL. `post_json_to_local_endpoint` and `stream_json_from_local_endpoint` are `pub(super)`, called from `LocalProvider`, and `LOCAL_STREAM_TRUNCATED` is also `pub(super)` (imported by `providers.rs` for its test module only); the rest is private. Its edges back into `providers` are `OpenAiSseEmitter` from `providers/wire.rs`, the `SseBytesEmitter` trait the emitter is pushed bytes through (which stays in `providers.rs`), and the shared `ProviderStreamEvent` type; nothing in `wire.rs` reads `local_http.rs`, so the edge is one-way. [`providers/local_http/proptests.rs`](../apps/rocm/src/providers/local_http/proptests.rs) holds the property tests of the SSE body readers and is declared from this module so they sit with the readers they test; the example-based test of `parse_http_endpoint` is in this module's own `mod tests`, and the tests that drive `LocalProvider` end to end against a mock server stay in `providers.rs`'s `mod tests` with their server helpers. -- [`providers/wire.rs`](../apps/rocm/src/providers/wire.rs) — full domain extraction, a child of `providers.rs`: the OpenAI-compatible and Anthropic wire formats. The request-body builders (`openai_chat_request_body`, `openai_stream_chat_request_body`, `openai_local_chat_request_body`, `openai_local_stream_chat_request_body`, `anthropic_chat_request_body`, `anthropic_stream_chat_request_body`, and the helpers behind them, including `local_openai_compatible_request` and `apply_local_model_request_defaults`; the rule that one applies, `local_model_should_disable_thinking`, lives in [`rocm-dash-core`](../crates/rocm-dash-core/src/chat_template.rs)'s `chat_template` module, because the dashboard's chat client has to decide it identically), the parsers for non-streaming responses (`parse_openai_chat_message`, `parse_anthropic_chat_message`), and the SSE emitters with their line parsers (`OpenAiSseEmitter` and `AnthropicSseEmitter`, which implement the `SseBytesEmitter` trait that stays in `providers.rs`; `parse_openai_sse_line`, `parse_anthropic_sse_line`). The builders, the two chat-message parsers and the two emitters (with their `new` and `finish`) are `pub(super)`, called from `LocalProvider` and `RemoteProvider`; `OpenAiSseEmitter` is also read by `providers/local_http.rs`. Depends on the shared request/response types in `providers.rs`, on `providers/tool_schema.rs` and on `rocm-dash-core`'s `chat_template`, and on nothing else. The tests of the builders and parsers live in this module's own `mod tests`, with the tool-catalog assertions that read through the request bodies, and [`providers/wire/sse_emitter_proptests.rs`](../apps/rocm/src/providers/wire/sse_emitter_proptests.rs), the split-invariance and panic-guard properties of the emitters and line parsers, is declared from this module; the stream tests that run an emitter against a mock server stay in `providers.rs`'s `mod tests`. -- [`rocm_argv.rs`](../apps/rocm/src/rocm_argv.rs) — the argv helpers that `chat.rs`, `tool_policy.rs` and the freeform planner share, in a leaf module whose only `crate::` dependency is the leaf [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs): `chat_cli_arg_value`, `chat_cli_arg_value_checked`, `chat_cli_has_flag` and `ensure_flag` (from `chat.rs`), and `format_structured_tool_call` (which quotes each argument with `shell_quote`), `serve_args_request_cpu_device` and `device_policy_is_cpu_mode` (from `freeform_planner.rs`). They moved so that `freeform_planner.rs` no longer imports `chat` for them; `chat.rs` re-exports `ensure_flag` (read by `freeform_execution.rs`) and `freeform_planner.rs` re-exports `format_structured_tool_call`, so every other caller keeps its path. -- [`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. `select_single_ready_runtime` is the one rule for picking "the one ready runtime" when nothing else says which to use: it recovers the setup runtime first, then returns a `SingleReadyRuntime` (`One`, `Zero` with every registered runtime, or `Many` with the ready ones), where ready is `validate_runtime_manifest_for_activation`; its pure half is `classify_single_ready_runtime`. A setup runtime that cannot be used is not a ready runtime and is not counted: it does not stop a registered ready runtime from being picked (or refused as ambiguous), and its own error is returned only when the registry holds no ready runtime, while a failure to write a usable setup runtime's entry back is always returned. Its `SetupRecovery` argument says whether recovering the setup runtime may write its lost registry entry back (`Persist`, what the engine paths and a real ComfyUI install use) or only count the runtime from its own manifest and write nothing (`PreviewOnly`, for a `--dry-run` preview, which must name the runtime the real run will use without changing a file); `SetupRecovery::for_dry_run` maps the flag. `registered_runtimes_with_setup` is the list that rule counts from (the registry plus the setup runtime, written back or not as `SetupRecovery` says), which `comfyui/runtime_env.rs` also searches when a choice that names a runtime is not answered by the registry alone. Both [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs) (which treats `Zero` and `Many` as no selection and leaves the advice to its callers) and [`comfyui/runtime_env.rs`](../apps/rocm/src/comfyui/runtime_env.rs) (which words them as refusals) call it directly rather than through `runtimes_cmd.rs`, and neither keeps its own copy. 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 imported by [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), so the import edge between the two runs one way, from `engines_cmd.rs` to this module. This module (and its torch-alignment child) does not import `engines_cmd.rs`: 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) are imported from [`engine_install_env.rs`](../apps/rocm/src/engine_install_env.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/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 [`engine_install_env.rs`](../apps/rocm/src/engine_install_env.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`, `diverged_packages`, `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. -- [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) — full domain extraction, crate-level (split out of `therock.rs`): the installed-runtime manifest model (`InstalledRuntimeManifest`, `WheelRuntimeComposition`, `RocmSdkPythonProbe`, `RocmSdkPackageProbe`, `RocmSdkLibraryProbe`, whose serde shape is the on-disk contract of the registry files and each install's `.rocm-cli-runtime.json`), where those files live (`runtime_registry_dir`, `runtime_manifest_path`), writing them (`write_runtime_manifest`, the one routine every way of registering a runtime goes through: an SDK install, `rocm runtimes import`, `rocm runtimes adopt` and the recovery of the runtime `rocm setup` created. It writes the registry entry, and for a runtime ROCm CLI owns (`InstalledRuntimeManifest::owns_install_root`, the same rule uninstall and prune use to decide whether they may delete the folder) the `.rocm-cli-runtime.json` in its install root; an imported or adopted runtime is someone else's folder, so it gets the registry entry only. The registry entry is written last, so a failed write of either file never leaves a new entry behind and an error that says a runtime could not be registered or restored is true. Its one parameter is `ManifestOverwrite`: an install replaces its own entry, import and adopt refuse an existing one unless `--replace` is given, and recovery refuses so it only fills a missing entry. Neither file is written atomically) and loading them (`load_runtime_manifests`, `load_runtime_manifests_reporting_unparsed`, `sort_manifests_newest_install_first`), the composition readers (`wheel_composition_includes_devel`, `wheel_composition_device_target`), the probe validator (`validate_rocm_sdk_runtime_probe`), and registry selection and validation (`current_runtime_manifest`, `default_runtime_id_matches`, `runtime_keys_text`, `select_runtime_manifest`, `runtime_usability_status`, `validate_runtime_manifest_for_activation`, and the wheel/tarball validators behind it; the tarball one asks `rocm_core::install_root_has_payload` whether the root holds a payload). Lives at the crate level and depends on neither `therock.rs` nor `runtimes_cmd.rs`, so both build on it. [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) still depends on `therock.rs` (it reaches the manifest types and loaders through `therock.rs`'s re-exports), but `therock.rs` no longer depends on `runtimes_cmd.rs` in production code (one of its tests still calls into it). It also holds `paths_equivalent` and `normalize_path_for_compare`, the path comparison that [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs), [`runtime_uninstall.rs`](../apps/rocm/src/runtime_uninstall.rs) and `runtimes_cmd.rs` need, and the on-disk active-runtime marker: `ActiveRuntimeMarker` (user state, so its serde shape is as fixed as the manifest's; its fields are `pub(crate)` because `runtimes_cmd.rs` builds it on activation and rollback), `active_runtime_marker_path` and `active_runtime_marker_matches`, which uninstall uses to decide whether the runtime it removes was the active one. `write_active_runtime_marker` stays in `runtimes_cmd.rs` with the activation transaction. `runtimes_cmd.rs` re-exports the selection and path-helper names that other modules import from it. Its own tests cover the manifest round-trip, the `devel`/composition readers, and runtime selector resolution. -- [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs) — full domain extraction; reads the live local servers at activation time, classifies each against the runtime being activated, renders the report, and moves stale ones with `--restart-services`. `fn runtimes()` lives in [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) and `RuntimesCommand` in [`cli.rs`](../apps/rocm/src/cli.rs); this file owns `ServiceRuntimeState`/`RuntimeServiceEntry`/`FailedServiceRestart`/`UnconfirmedServiceRestart`/`ServiceRestartOutcome`/`RuntimeServiceReconciliation`/`ServiceRuntimePin`, reached from `runtimes_cmd.rs` via `crate::runtime_services`. -- [`runtime_uninstall.rs`](../apps/rocm/src/runtime_uninstall.rs) — full domain extraction, crate-level (split out of [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs)): `rocm runtimes uninstall` and the storage pruning that removes a registered runtime. `plan_runtime_uninstall` builds the plan (`RuntimeUninstallPlan`, with the `InstallRootDecision` for its folder), `print_runtime_uninstall_plan` shows it, `confirm_and_revalidate_runtime_uninstall` asks and then checks that nothing changed while the prompt was open (`revalidate_runtime_uninstall_plan`), and `apply_runtime_uninstall` unregisters the runtime, clears the active and default state that named it and removes its install root when `should_remove_runtime_install_root` says ROCm CLI owns it (`local_runtime_manifest_matches`, `ensure_runtime_install_root_is_safe_to_remove`). `RuntimeUninstallPlan` also records whether Lemonade's install record points inside the runtime's folder (`lemonade_install_inside`, from `rocm_engine_lemonade::recorded_runtime_dir`), which `print_runtime_uninstall_plan` reports, and whether the folder holds a Lemonade tree at all (`holds_lemonade_tree`), which decides whether an unreadable record is worth reporting; `apply_runtime_uninstall` clears that record once the folder is removed (`RuntimeUninstallResult::lemonade_record`, a `RecordCleanup` that also carries a failed deletion or an unreadable record, worded by `lemonade_record_report_line`). `uninstall_runtime` is the non-interactive entry point. It reads the registry, the active-runtime marker and the path comparison from [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs), and does not depend on `runtimes_cmd.rs`, which calls into it from `runtimes()` and re-exports `uninstall_runtime`, `should_remove_runtime_install_root`, `InstallRootDecision` and `lemonade_record_report_line`. The planning and apply entry points, `RuntimeUninstallPlan`, `RuntimeUninstallConfirmation` and `RuntimeUninstallResult` (with its fields) are `pub(crate)` for `runtimes()`; `revalidate_runtime_uninstall_plan` and the folder-safety helpers are private. Its tests cover planning, revalidation, the folder-removal rules and uninstalling a read-only imported runtime; the uninstall tests that first activate a runtime stay with the activation tests in `runtimes_cmd.rs`. -- [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) — mechanical relocation, owns types (Phase 6c, ROCMAI-89): `runtimes()` and its activate/rollback handlers (the activation transaction, including `write_active_runtime_marker`), plus the runtime list rendering; the import and adopt handlers it dispatches to live in [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs) and the uninstall plan, confirmation and apply in [`runtime_uninstall.rs`](../apps/rocm/src/runtime_uninstall.rs); registry selection and manifest validation moved to [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs), which this module re-exports for the callers that import them from here. `RuntimesCommand` lives in [`cli.rs`](../apps/rocm/src/cli.rs) (part of the `Command`/`Cli` clap definition, the same way `EnginesCommand` does). `RuntimeActivationResult` is `pub(crate)`, read from [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs)'s `apply_runtime_update`/`append_update_activate_summary`; `uninstall_runtime`, `should_remove_runtime_install_root`, `InstallRootDecision` and `lemonade_record_report_line` (from `runtime_uninstall.rs`) and `ActiveRuntimeMarker` and `active_runtime_marker_path` (from `runtime_registry.rs`) are re-exported for [`storage.rs`](../apps/rocm/src/storage.rs) and [`config_cmd.rs`](../apps/rocm/src/config_cmd.rs); `recover_setup_runtime_registration`, `newest_installed_runtime_manifest` and `setup_runtime_paths` (from `runtime_adopt.rs`) and `normalize_path_for_compare` (from `runtime_registry.rs`) are re-exported for the modules that import them from here, such as [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs), [`examine_cmd.rs`](../apps/rocm/src/examine_cmd.rs) and [`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs). [`engine_install_env.rs`](../apps/rocm/src/engine_install_env.rs) is deliberately not one of them: it imports from `runtime_adopt.rs` and `runtime_registry.rs` directly, because going through this module would lead back to it via `runtime_services.rs`. The dependency on the sibling [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) above runs the other way: that module calls into this one (`activate_runtime`, `newest_installed_runtime_manifest`, `recover_setup_runtime_registration`), while this module reaches it only from its test module. -- [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) — mechanical relocation, owns types (Phase 6a): `serve()`, plus the engine selection that runs ahead of it (`select_serve_engine`, `recipe_preferred_engine`, `serve_model_ref_for_engine`) and the AIM pre-flight that runs inside it: the Hugging Face token check, the GPU-family profile check and pin, the multi-GPU refusal (`aim_gpu_preflight`), and the board note. The engine-recipe overrides `serve()` applies to the launch hint live in [`serve_recipe.rs`](../apps/rocm/src/serve_recipe.rs); this module imports them by name. It also holds `collect_serve_notes`, the GPU/device warnings folded into the interactive summary, which was relocated here from `main.rs` with its two tests. Its tests cover engine selection, the AIM pre-flight and the reuse pre-gate; the AIM tests build their hint with `protocol_engine_recipe_hint` and `engine_recipe_with_extra_env` from `serve_recipe.rs`, which `serve()` also calls. -- [`serve_recipe.rs`](../apps/rocm/src/serve_recipe.rs) — mechanical relocation, owns a type (split out of [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs), which imports the entry points by name): the pure transforms `serve()` applies to the selected engine's launch recipe hint. `protocol_engine_recipe_hint` maps the catalog's engine record onto the protocol hint, and `render_serve_engine_recipe_lines` prints it for the serve plan. The explicit controls are then layered on top: `--tool-call-parser` (`engine_recipe_with_tool_call_override`), `--gpu-memory-utilization` (`parse_gpu_memory_utilization`, `engine_recipe_with_gpu_memory_utilization_override`), `--temperature`/`--top-p`/`--max-tokens` (`ServeGenerationDefaults`, `engine_recipe_with_generation_defaults`) and `--engine-env` (`engine_recipe_with_extra_env`, `engine_env_ignored_note`, with the env names it refuses to override in `RESERVED_ENGINE_ENV_KEYS`); `engine_recipe_enables_tool_choice` reads the result back. The per-flag rewriters (`set_vllm_tool_call_parser`, `set_vllm_gpu_memory_utilization`, `set_vllm_override_generation_config`, `set_lemonade_generation_defaults`) are private. The entry points above, and `ServeGenerationDefaults`, are `pub(crate)` for `serve()` and for the AIM tests in `serve_cmd.rs`; `RESERVED_ENGINE_ENV_KEYS` is private. Among first-party crates the module depends only on `rocm_core` and `rocm_engine_protocol`, and nothing in it calls back into `serve_cmd.rs`. Its tests cover each override on its own. -- [`serve_summary.rs`](../apps/rocm/src/serve_summary.rs) — full domain extraction. -- [`service_control.rs`](../apps/rocm/src/service_control.rs) — mechanical relocation, owns private types: stopping and restarting a managed local server, the process control behind `rocm services stop|restart`, the chat/LLM sandbox tool-calling path and `runtime_services.rs`'s moves onto a new runtime. It holds the sandbox-tool runner (`run_internal_sandbox_tool`), the stop path (`stop_recorded_processes`, which hands the recorded PIDs to the routine [`proc_lifecycle.rs`](../crates/rocm-core/src/proc_lifecycle.rs) shares with `rocmd`, `scripted_stop_outcome`, the end-to-end hook behind the `e2e-test-hooks` feature, `stop_internal_managed_service`, `stop_internal_managed_service_with`, `stop_internal_managed_service_confirmed_with`, `unload_lemonade_service_model`) and the restart path (`apply_restart_runtime_pin`, `load_service_for_restart`, `restart_child_argv`, `restart_internal_managed_service`, `restart_internal_managed_service_with`, `update_restarting_record`, `record_restarted_child`, `record_restart_readiness`). Only `run_internal_sandbox_tool` and `restart_internal_managed_service` are `pub(crate)`: the first is read from `dispatch()` in [`main.rs`](../apps/rocm/src/main.rs), from [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs)'s `run_approved_service_action` and from [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs), which passes it to [`service_launch.rs`](../apps/rocm/src/service_launch.rs)'s `run_attached_service` as the stop for a Ctrl-C, the second from [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs); each importer reaches them through `crate::service_control` rather than a re-export. Every other item has no caller outside this module and stays private — see [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs)'s and [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs)'s entries above for how those two modules' own doc comments describe this module as the caller of their helpers. The module reads managed-service records through [`services_text.rs`](../apps/rocm/src/services_text.rs) (`load_managed_service`, `read_managed_service_manifest`) and shapes the `stop_server` answer with its `internal_stop_server_value`; `services_text.rs` does not call back into it. This module takes `ensure_public_service_has_endpoint_key` and the spawn helpers from [`service_launch.rs`](../apps/rocm/src/service_launch.rs), which does not import it back. The cluster's regression tests live in this module's own `mod tests`, reaching shared fixtures (`test_paths`, `ScopedTestEnv`, `plant_service_record_on_runtime`, `OLD_RUNTIME_KEY`, `NEW_RUNTIME_KEY`) through `crate::tests::` the same way other mechanically relocated modules do, and `runtime_services::` through its own `use crate::runtime_services;` for the handful of tests that drive a restart through `runtime_services`'s public entry points rather than calling it directly. -- [`serve_port.rs`](../apps/rocm/src/serve_port.rs) — full domain extraction: the central `rocm serve` port policy (automatic vs explicit request, reservation by live managed services, OS preflight lease), used by [`service_launch.rs`](../apps/rocm/src/service_launch.rs); the CLI restart path shares the `rocm-core` lease primitives (`lease_loopback_port_or_bind_error`, `is_canonical_loopback_host`) rather than this module. -- [`service_hints.rs`](../apps/rocm/src/service_hints.rs) — shared CLI-output component: the `rocm services stop|restart|remove --yes` hint text, shared by [`remote/mod.rs`](../apps/rocm/src/remote/mod.rs), [`serve_summary.rs`](../apps/rocm/src/serve_summary.rs), [`service_launch.rs`](../apps/rocm/src/service_launch.rs), [`service_records.rs`](../apps/rocm/src/service_records.rs), [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs), and [`services_text.rs`](../apps/rocm/src/services_text.rs) so they cannot go out of sync with each other, as `serve_summary.rs`'s stop row did from the day it was added — #417. It also holds the helpers that map a service tool name to the command word, verb and past tense those hints and messages use (`service_action_command`, `service_action_verb`, `service_action_past_tense`) and to its `SandboxToolArg` (`sandbox_tool_arg_from_service_tool`); [`services_text.rs`](../apps/rocm/src/services_text.rs) reads `service_action_past_tense` from here rather than through the crate root. It quotes the service id with `shell_quote`, so a hint names exactly the argv it runs. -- [`service_launch.rs`](../apps/rocm/src/service_launch.rs) — mechanical relocation, since split into a directory of child modules, owns no code of its own beyond its declarations: spawning/attaching to a managed service process and streaming its log, the port allocation transaction and failed-launch cleanup (under the shared launch lock), plus the endpoint-key/auth checks that gate a public bind, divided among the children listed below. The file declares the children, a `test_support` module compiled only for tests (the fixtures more than one child's tests share), and `pub(crate) use` re-exports of the items other modules call, so [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs), [`automations.rs`](../apps/rocm/src/automations.rs), [`service_control.rs`](../apps/rocm/src/service_control.rs) and [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs) still reach them as `crate::service_launch::name`; [`main.rs`](../apps/rocm/src/main.rs) does not. An item that sibling children share is `pub(super)` and reached through `super::`; everything else is private to the child that owns it. `ServicesCommand` lives in [`cli.rs`](../apps/rocm/src/cli.rs) rather than moving alongside, and `services()` lives in [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs); the record removal and pruning it dispatches to now lives in [`service_records.rs`](../apps/rocm/src/service_records.rs), and only stop/restart are also reachable from the chat/LLM sandbox tool-calling path. This module does not import [`service_control.rs`](../apps/rocm/src/service_control.rs), which imports it: `run_attached_service` takes the stop for a Ctrl-C as a parameter, and [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) passes `run_internal_sandbox_tool`. -- [`service_launch/endpoint_auth.rs`](../apps/rocm/src/service_launch/endpoint_auth.rs) — mechanical relocation out of [`service_launch.rs`](../apps/rocm/src/service_launch.rs), a leaf child of it, no owned types: bind-host validation and the endpoint API key policy. `validate_bind_host` refuses a non-loopback host without `--allow-public-bind` (`is_loopback_host` is the inverse of `rocm_engine_protocol::is_public_bind_host`, which `rocmd` shares); `resolve_endpoint_auth` decides the key a launch uses (none for a loopback bind unless a key is required, otherwise the supplied key trimmed or a generated one, refusing an empty key or one with a control character); `drop_orphaned_endpoint_key_on_already_running` clears a key staged for an attempt that spawned nothing; `ensure_public_bind_engine_supported` refuses a public bind with Windows managed Lemonade, whose key cannot be enforced; and `ensure_public_service_has_endpoint_key` is the guard a respawn runs so a public (or `--require-api-key`) service whose key file is gone is not reopened without authentication. All six are `pub(crate)` and re-exported by the parent: [`service_control.rs`](../apps/rocm/src/service_control.rs) reads `ensure_public_service_has_endpoint_key`, [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs) reads `is_loopback_host`, and [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) reads the rest. -- [`service_launch/launch_transaction.rs`](../apps/rocm/src/service_launch/launch_transaction.rs) — mechanical relocation out of [`service_launch.rs`](../apps/rocm/src/service_launch.rs), a leaf child of it, owns types: the part of a managed launch that decides before anything spawns. `resolve_managed_port_in_transaction` refreshes liveness, answers an equivalent live service before leasing any port (`ManagedPortDecision`), and otherwise leases a concrete port against both the ports live records still reserve (`live_managed_services`, `reserved_service_ports`) and the real OS through [`serve_port.rs`](../apps/rocm/src/serve_port.rs); a caller must hold the launch lock across it and the record write that follows. `abandon_failed_managed_launch` undoes a failed attempt before that lock is released: a spawned child is terminated first, through the same `rocm_core::terminate_recorded_pid_within` routine a stop uses (so on Windows its descendants are taken down too), and its record kept, marked stopped, while an attempt that never spawned has every artifact removed. A spawned child whose start token was not captured, on a host that records tokens (Linux and Windows, which records the process creation time), is not signalled (`launch_cleanup_refusal`): it was gone before it could be captured and its pid may belong to another process. `managed_service_reuse_refusal` (with `ManagedReuseRefusal`) is the one answer to whether a live matching service can serve a request (recipe, `--require-api-key`, device policy), and `no_usable_gpu_refusal` words the no-usable-GPU refusal once for `serve()`'s pre-flight and for the spawn. `managed_service_reuse_refusal` and `no_usable_gpu_refusal` are `pub(crate)`, re-exported, and read from [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs), and `ManagedReuseRefusal` is `pub(crate)` too because the first returns it (only [`service_launch/spawn.rs`](../apps/rocm/src/service_launch/spawn.rs) matches on it); `ManagedPortDecision`, `live_managed_services`, `resolve_managed_port_in_transaction` and `abandon_failed_managed_launch` are `pub(super)` for [`service_launch/spawn.rs`](../apps/rocm/src/service_launch/spawn.rs). -- [`service_launch/spawn.rs`](../apps/rocm/src/service_launch/spawn.rs) — mechanical relocation out of [`service_launch.rs`](../apps/rocm/src/service_launch.rs), a leaf child of it, owns types: the detached engine child that the background and attached serve paths share. The process and stdio plumbing (`detach_background_command`, `attach_background_stdio`, `managed_service_process_command`, `managed_engine_startup_failure_detail`) is `pub(crate)` and, off Windows, re-exported: [`service_control.rs`](../apps/rocm/src/service_control.rs) reads all four for a restart and [`service_launch/helper_autostart.rs`](../apps/rocm/src/service_launch/helper_autostart.rs) reads the first three. On Windows `managed_engine_startup_failure_detail` is re-exported for test builds only, because the [`services_text.rs`](../apps/rocm/src/services_text.rs) log-tail tests call it through `crate::service_launch` there too. `ManagedLaunchReport` (`pub(crate)`) is the engine-neutral result of a launch, and `ManagedSpawn` (`pub(super)`) says whether the launch found a live service or spawned a child. `spawn_managed_engine_child` is the whole serialized transaction under the launch lock (duplicate detection, port lease, manifest and log creation, argv preparation, the bounded immediate-exit check and record publication) and returns before any readiness wait; `launch_managed_engine_child_locked` is its side-effecting half, split out so that every failure after the record's first write goes through `abandon_failed_managed_launch`. The tests reach the spawn through a test-only, thread-scoped hook (`TEST_SPAWN_HOOK`, `pub(super)` so the tests in [`service_launch/start.rs`](../apps/rocm/src/service_launch/start.rs) can observe the state at the instant of the spawn). -- [`service_launch/readiness.rs`](../apps/rocm/src/service_launch/readiness.rs) — mechanical relocation out of [`service_launch.rs`](../apps/rocm/src/service_launch.rs), a leaf child of it, owns private items: waiting on a service after it is launched or found live. `wait_for_record_ready` and `wait_on_existing_service` run the wait (one wait is bounded by `READINESS_WAIT`, and `wait_past_readiness_budget` is what `rocm serve --wait` uses to keep polling past it until the server answers or stops being live), `service_pid_is_alive`, `record_still_live` and `service_still_live` decide whether the tracked process is still there, `settle_exited_service` demotes the manifest of one that is not, and `died_during_wait` and `record_wait_outcome` end a wait, writing its outcome back without discarding what changed on disk meanwhile. `e2e_simulate_oom_launch` and `simulate_oom_managed_launch` are the end-to-end fault-injection seam behind the `e2e-oom-fault-injection` feature: the first is a `const fn` returning false without the feature, is `pub(crate)` and re-exported, and is read from [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs); the second fabricates the on-disk state of a launch that ran out of memory. `wait_for_record_ready`, `wait_on_existing_service`, `service_pid_is_alive`, `died_during_wait`, `record_wait_outcome` and `simulate_oom_managed_launch` are `pub(super)` for [`service_launch/start.rs`](../apps/rocm/src/service_launch/start.rs); the rest are private. -- [`service_launch/start.rs`](../apps/rocm/src/service_launch/start.rs) — mechanical relocation out of [`service_launch.rs`](../apps/rocm/src/service_launch.rs), a leaf child of it, no owned types: the background launch path. `start_managed_service` runs the spawn transaction, releases the launch lock once the record is published, waits for HTTP readiness and returns a `ManagedLaunchReport`; if the launch fails before a record exists it drops the endpoint key `serve()` staged for the attempt. `print_managed_launch_plain` renders the report line by line for output that is not interactive, and `wait_begin_client_config` returns the one-time client configuration for a generated key when a wait begins, built by `render_endpoint_client_config` (`pub(super)`, since [`service_launch/attach.rs`](../apps/rocm/src/service_launch/attach.rs) prints it too). The three functions other modules call are `pub(crate)`, re-exported, and read from [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs). -- [`service_launch/helper_autostart.rs`](../apps/rocm/src/service_launch/helper_autostart.rs) — mechanical relocation out of [`service_launch.rs`](../apps/rocm/src/service_launch.rs), a leaf child of it, owns a private type: starting the background automation helper (`rocm daemon`) when a watcher needs it. `ensure_background_helper_running` and `ensure_background_helper_running_quiet` do nothing unless an automation is enabled and [`background_helper.rs`](../apps/rocm/src/background_helper.rs)'s `background_helper_already_running` says no helper is running; `ensure_background_helper_running_with` takes the spawn as a parameter so the decision is testable, and `spawn_background_helper` does the detached spawn. Concurrent callers queue on an autostart lock, and `AutostartClaim` (with `AUTOSTART_CLAIM_TTL_MS`, `read_autostart_claim`, `write_autostart_claim` and `autostart_spawn_in_flight`) records a spawn in flight so the next holder defers instead of starting a second helper. Both entry points are `pub(crate)` and re-exported: [`automations.rs`](../apps/rocm/src/automations.rs) calls the first, and [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) and [`service_launch/attach.rs`](../apps/rocm/src/service_launch/attach.rs) call the quiet one. -- [`service_launch/attach.rs`](../apps/rocm/src/service_launch/attach.rs) — mechanical relocation out of [`service_launch.rs`](../apps/rocm/src/service_launch.rs), a leaf child of it, owns private types: the attached serve path (`--verbose`/`--foreground`). `run_attached_service` spawns the same detached child the background path does and follows its log in the terminal until the user detaches with Ctrl-D (the server keeps running) or stops it with Ctrl-C, or the engine exits; `AttachOutcome` is that result and `detach_key_outcome` maps a key press to it. `stream_attached_logs` reads keys in crossterm raw mode (`RawModeGuard` restores the terminal on every exit path) and `stream_attached_logs_no_tty` follows the log until the process exits when stdin is not a terminal. `finish_attached_stop` turns the answer of the stop that Ctrl-C ran into output: a confirmed stop is reported on stdout, an unconfirmed one becomes the error, and a failed stop signals the child this session launched. `run_attached_service` is `pub(crate)`, re-exported, and read from [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs). -- [`service_records.rs`](../apps/rocm/src/service_records.rs) — mechanical relocation, owns types: removing one managed-service record and every file it owns (`remove_managed_service_record`, `service_record_artifacts`) and the `rocm services prune` plan/render/apply steps (`build_service_prune_plan`, `render_service_prune_plan`, `apply_service_prune_plan`, `prune_managed_service_records`) with the age gate behind them (`DEFAULT_SERVICE_PRUNE_MIN_AGE_HOURS`, `service_prune_min_age_hours`). It reads record state through [`managed_service_status.rs`](../apps/rocm/src/managed_service_status.rs) and [`services_text.rs`](../apps/rocm/src/services_text.rs) and builds its advice text with [`service_hints.rs`](../apps/rocm/src/service_hints.rs); none of the three depends on it. `remove_managed_service_record_with` takes `--force` and the read of each recorded PID: `--force` removes a record only when none of its recorded processes is confirmed running, one could not be queried and a stop was requested, and reports which. `remove_managed_service_record_with`, `prune_managed_service_records`, `service_prune_min_age_hours` and `DEFAULT_SERVICE_PRUNE_MIN_AGE_HOURS` are `pub(crate)` (`services()` in [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs) calls the first three; the `ServicesCommand::Prune` clap definition in [`cli.rs`](../apps/rocm/src/cli.rs) uses the constant), and `ServicePruneOutcome`, the return type of `prune_managed_service_records`, is `pub(crate)` with `pub(crate)` `text`, `removed_records`, `removed_files` and `failures` fields that `services()` reads. Every other item is private. The cluster's regression tests live in this module's own `mod tests`, reaching the shared `test_paths`, `plant_service_record` and `plant_service_record_without_its_key` fixtures through `crate::tests::` (the last two widened to `pub(crate)` for that). -- [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm services`' command handler (`services()`, which dispatches `list`, `logs`, `stop`, `restart`, `remove` and `prune`) and `run_approved_service_action`, the approval-gated stop/restart path. `ServicesCommand` lives in [`cli.rs`](../apps/rocm/src/cli.rs). Both functions are `pub(crate)`: `dispatch()` calls `services()` through a re-import, and [`advised_commands.rs`](../apps/rocm/src/advised_commands.rs)'s test reaches `run_approved_service_action` through a test-only re-import in `main.rs`. The module reads from [`services_text.rs`](../apps/rocm/src/services_text.rs), [`service_control.rs`](../apps/rocm/src/service_control.rs), [`service_records.rs`](../apps/rocm/src/service_records.rs), [`service_hints.rs`](../apps/rocm/src/service_hints.rs) and [`cli_audit.rs`](../apps/rocm/src/cli_audit.rs); none of them calls back into it. The cluster's one regression test lives in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::`. -- [`services_text.rs`](../apps/rocm/src/services_text.rs) — mechanical relocation, owns private types (Phase 6f, ROCMAI-209): the CLI/TUI logs browser (`render_logs_text`, `render_logs_browser_text`, `render_logs_browser_page_text`, `render_logs_browser_page_text_with_options`, `logs_browser_total_pages`, the `LogBrowserEntry` type, `collect_log_browser_entries`, `filter_log_browser_entries`, `log_browser_source_label`, `write_past_attempts_hint`), the `rocm services`/`rocm services logs` status surfaces (`render_services_text`, `render_services_json`, `render_service_logs_text`, `render_service_logs_text_with_options`, `render_service_action_result`, `read_managed_service_manifest`, `load_managed_service`), the `--follow` tail behind `rocm logs --service --follow` and `rocm services logs --follow` (`follow_service_logs`, `follow_service_logs_with`, the `FollowCursor`, `LogSegment` and `FollowFooter` types, `write_log_segments`, `newly_ready`; new code written in this module, not relocated; `FollowCursor` is the private cursor that reads what a growing log gained, and is not [`rocm_core::LogTail`](../crates/rocm-core/src/log_tail.rs), the result of a bounded tail read that the log views in this module use), the internal `rocmd`-compatible status surface (`render_internal_status_text`), the `stop_server` answer shape and its renderer (`internal_stop_server_value`, `service_stop_unconfirmed`, `render_unconfirmed_service_stop`, `process_check_command`), plus `validate_service_id`, `list_log_files`, `read_optional_tail_lines`, and the CLI-lifecycle-log tail formatting helpers (`format_cli_lifecycle_tail_line`, `lifecycle_event_label`, `humanize_log_label`, `lifecycle_field`, `read_log_tail`). The managed-service stop and restart implementation that used to live here is in [`service_control.rs`](../apps/rocm/src/service_control.rs). The `LogBrowserEntry` struct moved here from `main.rs` with the logs browser and stays private. `dispatch()` calls directly into this module at several points — `render_internal_status_text`, `render_service_logs_text`, `render_logs_browser_text`, and `render_logs_text` — all re-imported via `use crate::services_text::{...};`; [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs)'s `services()` calls `render_services_text`, `render_services_json` and `render_service_logs_text` through its own imports. `render_service_action_result`, `service_stop_unconfirmed` and `validate_service_id` are also `pub(crate)` and read from `services_cmd.rs`'s `run_approved_service_action`; `validate_service_id` is also read from [`service_records.rs`](../apps/rocm/src/service_records.rs)'s `remove_managed_service_record`/`service_record_artifacts`, and `load_managed_service` from its `remove_managed_service_record`/`apply_service_prune_plan`. `load_managed_service` is `pub(crate)`, read from [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs) (reconciling live servers against a runtime activation), from [`service_control.rs`](../apps/rocm/src/service_control.rs) and from [`managed_service_status.rs`](../apps/rocm/src/managed_service_status.rs)'s own test module; `read_managed_service_manifest` and `internal_stop_server_value` are `pub(crate)` for `service_control.rs`, and `process_check_command` for its tests; `read_log_tail`, `render_logs_text`, `render_logs_browser_text`, `render_services_text`, `render_service_logs_text`, and `validate_service_id` are also `pub(crate)`, read from [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs)'s read-only command runner; `read_optional_tail_lines` and `render_service_action_result` are also `pub(crate)`, read from [`service_launch.rs`](../apps/rocm/src/service_launch.rs)'s managed-spawn/attach path. Every other item in this list has no caller outside this module and stays private. The cluster's regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::` the same way other mechanically relocated modules do; `assert_no_retry_line` stays here as a `pub(crate)` test helper because it checks the unconfirmed-stop rendering and `service_launch.rs`'s tests read it too. Two tests that call this module's `load_managed_service` only incidentally — their primary subject is `runtime_services::pin_service_record_to_runtime`/`restore_service_record_pin` and `runtime_services::restart_service_onto_runtime_with`'s outcome classification respectively — stay in `main.rs`'s shared `mod tests` instead. -- [`setup_cmd.rs`](../apps/rocm/src/setup_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm setup`'s command handler (`setup()`, which runs `setup status` by default and `setup reset`), the text `rocm setup status` prints (`render_setup_status_text`) and the reset that clears the saved first-time prompt state (`reset_setup_prompt_state`). `SetupCommand` lives in [`cli.rs`](../apps/rocm/src/cli.rs). `setup()` and `render_setup_status_text` are `pub(crate)` and re-imported in `main.rs`: `dispatch()` calls the first, and [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs)'s read-only handling of `rocm setup` and `rocm setup status` reaches the second as `crate::render_setup_status_text`; `reset_setup_prompt_state` is private. The three regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::` and `write_test_pip_runtime` through `crate::test_support::`. -- [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) — shared CLI-output component (`shell_quote`): the CLI's name for `rocm-core`'s POSIX quoter, [`posix_shell_quote`](../crates/rocm-core/src/quoting.rs). `rocm-dash-tui` keeps a copy as `ui::exec::quote_display_arg` in [`exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs), since the crate-edge check forbids it `rocm-core`; a per-character walk and a property test here hold the two to the same output. It covers the remote `ssh` command line, the chat approval card and the plan for a free-form request, the install dry-run `command:` line, the [`service_hints.rs`](../apps/rocm/src/service_hints.rs) hints, the runtime-activation report, the `rocm services logs ` lines `rocm services` lists and the `rocm comfyui install --runtime-id` advice a failed ComfyUI reinstall prints — not every `rocm …` hint the CLI prints; older ones such as `rocm logs ` still interpolate their value bare. Also holds `has_terminal_control_character`, the predicate the chat tool-call guards refuse on. -- [`storage.rs`](../apps/rocm/src/storage.rs) — full domain extraction. Its report also lists each Lemonade install tree (`EngineInstallUsage`, built by `lemonade_install_usages` from the read-only view in [`footprint.rs`](../engines/lemonade/src/footprint.rs)) with its size and whether the install record uses it (`EngineInstallStatus`, decided by `classify_engine_install`), and whether `rocm runtimes uninstall` would delete it with its runtime. -- [`system_packages.rs`](../apps/rocm/src/system_packages.rs) — full domain extraction, a leaf of the crate (split out of [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)): the host system-package installs that `rocm install sdk` and `rocm engines install vllm` run through `sudo` apt, dnf or zypper. It owns the distro-aware OpenMPI, libatomic and libnuma flows (`ensure_openmpi_for_vllm`, `ensure_libatomic_for_torch`, `ensure_libnuma_for_torch`), the choice between printing the commands and running them (`SystemPackageInstallAction`, `system_package_install_action`), the guard that refuses an `apt-get install` which would remove ROCm packages, and reads the os-release every one of these plans is built from through `rocm_core::hardware_root::real_os_release`, which has no copy here. Production code uses only `std`, `anyhow` and `rocm_core`; the three `ensure_*` functions are `pub(crate)` and the rest is private. `runtime_install_finalize.rs` re-exports the three `ensure_*` names for [`install_cmd.rs`](../apps/rocm/src/install_cmd.rs) and [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs). `SdkInstallConsents` stays in `runtime_install_finalize.rs` (it carries a `therock::SdkInstallConsent`); the functions here take its plain `system_packages` bool. `torch_runtime_dep_checks_disabled` is the E2E hook that skips the torch dependency checks; it only does anything under `e2e-test-hooks`. Its tests cover the consent decision (reaching `consents_for_install_sdk_argv` in `runtime_install_finalize.rs`'s test module) and, under `e2e-test-hooks` on Linux, that `rocm_core::hardware_root::real_os_release` and the three OpenMPI/libatomic/libnuma install hints ignore a simulated host root, and a scan that no source file of the binary reads os-release by hand. -- [`therock.rs`](../apps/rocm/src/therock.rs) — full domain extraction; owns TheRock SDK install orchestration and is the parent of the `therock/` children below. It keeps `install_sdk` and `install_sdk_for_update` (with `SdkInstallRequest` and `SdkInstallResult`), the wheel and tarball install paths (`install_wheel_runtime`, `install_tarball_runtime`) with the provenance and notes they print (`render_canonical_provenance`, the plan itself being written by `therock/wheel_plan.rs`, the host-newer-ROCm and no-wheels messages, `quote_display_arg`), and the helpers that name an install and its folders: `runtime_key`, `wheel_runtime_key`, `managed_runtime_root`, `resolved_install_root`, `venv_python_path`, `platform_tarball_token` and `slugify`, plus `ensure_tarball_install_target_is_clean`, the refusal to extract a tarball into a root that already holds a payload. What "holds a payload" means is not defined here: it is `rocm_core::install_root_has_payload`, the one rule shared with `runtime_registry.rs` and `therock/update.rs`. The runtime-manifest model and registry loaders it writes through live in [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs); `therock.rs` re-exports the names other modules reach as `therock::...`: `InstalledRuntimeManifest`, `WheelRuntimeComposition`, `RocmSdkPythonProbe`, `load_runtime_manifests` and `validate_rocm_sdk_runtime_probe` from `runtime_registry.rs` (plus `RocmSdkLibraryProbe`, for tests only), and from its child modules the `pub(crate)` names each child's entry below lists. The children read five of them from here, so they stay in `therock.rs` for good: `slugify` ([`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) and [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs)), `venv_python_path` ([`therock/python.rs`](../apps/rocm/src/therock/python.rs)), `platform_tarball_token` ([`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs)), and `runtime_key` and `wheel_runtime_key` ([`therock/update.rs`](../apps/rocm/src/therock/update.rs)). The `runtimes` subcommand's command enum (`RuntimesCommand`) lives in [`cli.rs`](../apps/rocm/src/cli.rs); its dispatch fn and most of its domain logic — rendering, activation, and manifest import — live in [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs). -- [`therock/version.rs`](../apps/rocm/src/therock/version.rs) — full domain extraction, a leaf child of `therock.rs` (split out of it): the version grammar behind runtime selection and update checks. `parse_version` is the strict gate an install is routed on; `parse_version_for_ordering`, `compare_version_strings` and `version_relation` implement the PEP 440 ordering and the "is this a different version" question; `parse_host_version` reads a host-reported ROCm version through the same parser; `runtime_version_display`, `runtime_version_build_date`, `normalize_requested_build_date` and the calendar helpers behind them handle build dates; `is_stable_runtime_version` and the `ParsedVersion`/`VersionOrderKey`/`VersionStage` types back them. The items `therock.rs` and its property-test module use are `pub(super)` (including the `ParsedVersion` and `VersionOrderKey` fields they read); the parsing and calendar helpers behind them are private; and `runtime_version_display` is `pub(crate)`, re-exported by `therock.rs` for the other modules that render versions. Depends on nothing else in `therock`. `therock_version_proptests.rs` stays declared from `therock.rs` because it also reaches update, wheel and registry code. -- [`therock/io.rs`](../apps/rocm/src/therock/io.rs) — full domain extraction, a leaf child of `therock.rs` (split out of it): unique scratch directories (`linux_temp_dir`, `windows_temp_dir`), both `pub(super)`. The atomic file writes that used to live here are rocm-core's shared [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs), which [`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs), [`therock/update.rs`](../apps/rocm/src/therock/update.rs) and [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) call directly. -- [`therock/process.rs`](../apps/rocm/src/therock/process.rs) — full domain extraction, a child of `therock.rs` that depends on `therock/io.rs` for scratch directories (split out of `therock.rs`): running and capturing child commands (`run_command*`, `capture_command_output*`, `capture_python_stdout*`, `run_uv_progress_command`, and the Windows temp-file variants with `windows_child_path`), the bounded wait (`wait_with_output_bounded`), the progress-line output with its `--json` suppression guard (`SuppressProgressOutput`, `progress_line`), and unpacking the SDK tarball (`extract_tarball`, `extract_tarball_and_discard_archive`, which is why it sits here and not in `io.rs`: it spawns `tar` through `run_command`). Its `archive_properties` property tests run on Unix only. The process-wide environment lock these tests take is the single `PROCESS_ENV_TEST_LOCK` in [`test_support.rs`](../apps/rocm/src/test_support.rs), shared with the tests left in `therock.rs`. -- [`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) — full domain extraction, a child of `therock.rs` that depends on rocm-core's [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs) for atomic writes and on `slugify` in the parent for cache file names (split out of `therock.rs`): HTTP fetching for installs. `download_text_cached` is the metadata GET with its on-disk etag cache (`CachedHttp*`) and detached-signature verification (`MetadataSignaturePolicy`, `PINNED_METADATA_PUBLIC_KEY_PEM`, the unset trust root that `cargo xtask verify-pinned-keys` checks against the canonical published key, so its path is pinned in `xtask`); `download_file` is the streaming artifact download; `head_content_length` and `preflight_tarball_space` size the download and check free space first; `http_get` is the shared request. `truthy_env` is `pub(crate)` and re-exported by `therock.rs` for [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs); `download_text_cached`, `download_file`, `preflight_tarball_space` and the `CachedHttpText` struct (with its `text` field) that `download_text_cached` returns are `pub(super)` for the install and resolution code that stays in `therock.rs`; everything else is private. -- [`therock/source.rs`](../apps/rocm/src/therock/source.rs) — full domain extraction, a child of `therock.rs` that depends only on `therock/version.rs` (split out of `therock.rs`): where an install reads from. `TheRockChannel` (release or nightly) and `SourceLayout` (the canonical stream, or ROCm 10's separately hosted next layout) are the two axes; `resolve_source` maps a pair to the `ResolvedSource` wheel-index and tarball-catalog bases, honouring a `ROCM_CLI_THEROCK_*_BASE` override only behind the explicit opt-in (`therock_base_override_allowed`, `select_base_override`, `env_override_base`); `select_source_layout`, `requested_source_layout` and `next_layout_requested` decide the layout from a pin; `RuntimeVersionSelector` is the version or build date a user pins (`pub(crate)`, re-exported by `therock.rs`). `FamilyResolution` lives here rather than in `therock/family.rs` because choosing the layout reads it; that keeps the dependency one-way, with `family.rs` building on this file. `TheRockChannel`, `SourceLayout`, `ResolvedSource` and `FamilyResolution` (with their methods and fields), `RuntimeVersionSelector`'s `describe` and `matches_version`, `resolve_source`, the three layout functions, and the `THEROCK_SOURCE_LAYOUT_GENERATION` and `THEROCK_NEXT_MIN_MAJOR` constants are `pub(super)` for `therock.rs` and its siblings; the base-override helpers and the other constants (the per-channel and next-layout base URLs, and the next layout's generation tag) are private to this file. -- [`therock/family.rs`](../apps/rocm/src/therock/family.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/source.rs` for `TheRockChannel` and `FamilyResolution` (split out of `therock.rs`): which package family a request targets. `resolve_family` picks it from `--family`, `ROCM_CLI_THEROCK_FAMILY`, a managed runtime or the host GPU, in that order, and refuses a GPU with no ROCm build (`unsupported_host_gpu_message`, `unsupported_requested_target_message`) instead of substituting another family; `family_override_or_recovered_arch` and `raw_arch_agreeing_with_family` recover the exact arch behind a grouped family; `family_resolution_hint` is the recovery text appended when no runtime is found. `resolve_family`, `family_override_or_recovered_arch` and `family_resolution_hint` are `pub(super)`; the rest is private. -- [`therock/python.rs`](../apps/rocm/src/therock/python.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/io.rs`, `therock/process.rs` and `therock/source.rs` (split out of `therock.rs`): the Python an install runs on. `python_requirement` maps a `SourceLayout` to the interpreter the layout needs (`PythonRequirement`: wheel tag and `uv` version), which is why `source.rs` had to move first; `python_requirement_for_version` narrows it to the interpreter `rocm install sdk --python-version` asked for (a ROCm 10 layout takes 3.10 to 3.14, the canonical layout only its own), and `python_requirement_for_tag` maps a runtime's recorded wheel tag back to its requirement so an update keeps it; `resolve_python_launcher` finds one in order of an explicit `ROCM_CLI_PYTHON`, `PATH`, the saved managed Python, then `ensure_managed_python`, which installs one through `uv` and records it in the managed-Python manifest; the resolver reads its environment through `PythonResolverEnv`, so tests steer it with a thread-local override (`OverridePythonResolverEnv`) rather than rewriting `PATH`; `wheel_compatibility_for_python` and `current_platform_wheel_tags` report the wheel tags an interpreter and platform accept (`WheelCompatibility`); `ensure_uv_venv` creates, or recreates when the interpreter tag no longer matches, the runtime's virtual environment. `plan_python_launcher` is the same lookup for a caller that must change nothing, an install preview or an update check: it returns a `PlannedPython`, either `Ready` with the interpreter a real install would pick or `WouldPrepareManaged` with the managed Python a real install would prepare and this caller did not, and it raises the refusals the real resolution raises before that step. `python_for_install` is the install's one choice between that and `resolve_python_launcher`, and prints the progress line that names the interpreter; `PlannedPython` also writes the `python_note:` line from the decision itself, `note` for an install preview and `update_note` for an update check, so a note cannot name a version the install will not prepare. `venv_python_path` stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The items `therock.rs` reaches, `plan_python_launcher` with `PlannedPython`'s `wheel_compatibility` and `update_note`, which `therock/update.rs` reads, and `python_requirement_for_tag`, which `therock/update.rs` reads, and `split_runtime_path`, which `therock/probe.rs` reads, are `pub(super)`; the rest is private, including `ensure_managed_python` and `resolve_python_launcher_in` (the resolver's entry point that takes its environment as an argument). Its Unix-only tests drive fake interpreters and `uv` scripts. -- [`therock/probe.rs`](../apps/rocm/src/therock/probe.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/process.rs` and `therock/python.rs` (split out of `therock.rs`): asking an installed runtime about itself through its own interpreter. `probe_rocm_sdk_runtime` runs `ROCM_SDK_PROBE_SCRIPT` and parses what `rocm_sdk` reports into the `RocmSdkPythonProbe` that [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) owns and validates; `probe_runtime_devices` runs `RUNTIME_DEVICE_PROBE_SCRIPT` to count the devices the runtime's torch can open and whether one can run a kernel (`RuntimeDeviceProbe`); `probe_torch_alignment` reads the installed torch and the one an engine pins from distribution metadata without importing torch (`TorchAlignmentProbe`); and `split_local_version`, `requirement_pinned_version` and `install_pinned_package` are the torch-pin helpers [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) uses to put the SDK's torch back after an engine install. The `pub(crate)` items are re-exported by `therock.rs` for [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) and [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs); `probe_rocm_sdk_runtime_for_target`, which `install_wheel_runtime` calls with the device payload it just chose, is `pub(super)`. -- [`therock/resolve.rs`](../apps/rocm/src/therock/resolve.rs) — a child of `therock.rs` that holds no logic (split out of `therock.rs`): only the `mod` declarations for the artifact-resolution modules under `therock/resolve/` and the `pub(super) use` lines through which `therock.rs` reads them. It is the parent the `resolve/` files hang from, so a module there is `pub(in crate::therock)` for the items `therock.rs` reaches and private otherwise. -- [`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/fetch.rs`, `therock/family.rs`, `therock/source.rs` and `therock/version.rs` (split out of `therock.rs`): resolving the SDK tarball a request installs. `resolve_tarball_artifact` (and `resolve_tarball_artifact_with_timeout`, which takes the metadata download timeout) resolves the family and source layout, downloads the catalog through the cached metadata fetch, and returns the `TarballArtifact` it chose; `parse_tarball_index_html` reads the catalog's embedded file list into `TarballIndexFile`s and `validate_tarball_file_name` refuses an entry that is not a plain file name; `select_tarball_candidate` picks the newest archive the request can install, with `tarball_family_token` spelling the family the way the next layout's catalog does. `platform_tarball_token`, which names the archives' platform, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. Only `resolve_tarball_artifact*` and `TarballArtifact` are visible beyond this file. -- [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/family.rs`, `therock/fetch.rs`, `therock/process.rs`, `therock/python.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for `WheelRuntimeComposition` (split out of `therock.rs`): resolving the wheel stack a request installs. `resolve_pip_runtime` (and `resolve_pip_runtime_with_timeout`, which takes the metadata download timeout and an optional source layout) resolves the family and the layout, reads the aggregate root, decides the device payload and returns a `PipRuntimeResolution`; on the canonical layout `select_matching_pip_package_versions` then takes the newest `rocm` whose `torch`, `torchvision` and `torchaudio` listings agree, and on the next layout `torchaudio_pin` pins a torchaudio first (the hardware-verified release when it is published, read from the vLLM engine's table) and `resolve_published_pip_package_versions` has `uv pip compile` choose the rest. That compile is the one step that may fetch `uv`, so who may is decided in one pure function, [`therock/resolve/uv_access.rs`](../apps/rocm/src/therock/resolve/uv_access.rs)'s `plan_version_resolution`, which takes the layout, a `UvAccess` and whether a `uv` is present, and answers scrape the indexes (canonical), compile with a `UvChoice` (acquire the managed `uv`, or use the present one) or skip. `resolve_pip_runtime` and `resolve_pip_runtime_with_timeout` (a real install and `rocm update`) are always `UvAccess::Acquire`, which never skips and never asks whether a `uv` is present; `preview_pip_runtime` is `UvAccess::PresentOnly`, which uses a present `uv` (`rocm_core::find_uv_binary`) and otherwise returns `PipRuntimePlan::NeedsUv` holding an `UnresolvedPipRuntime`: what was chosen without `uv` (the `rocm` version, the torchaudio pin, the requirements `uv` would be given) and no package versions, so nothing made from them can be built from it. `wheel.rs` acts on the answer; the real `find_uv_binary` and `ensure_uv_binary` reach it through a `UvPolicy` so that a test can count the calls. `wheel_runtime_composition` turns a resolution into the exact package specs (`therock_pip_package_specs`) an install gives `uv` and records in the manifest, `published_pip_requirements` is the matching requirement set for `uv pip compile`, and `canonical_auto_select_needs_next_python` peeks at the channel's own `rocm` listing so the interpreter can be picked before resolution. Beneath that, `parse_aggregate_package_links` and `parse_aggregate_device_targets` read the package links of the canonical aggregate root and the exact device targets it publishes, and `validate_aggregate_index_layout` refuses a root that lacks the expected packages or any device payload; `AggregateDeviceTarget::resolve` picks the one exact target a host gets, or records why it could not (`Undetermined`), and `AggregateDeviceTarget::prefer_recorded` is the one place a recorded target (an update apply's, or the one a runtime's manifest was built with) replaces the detected one, called by `therock.rs`, `therock/update.rs` and `therock/wheel_plan.rs`; `load_simple_index_versions` fetches a package's simple-index listing through the cached metadata download and `parse_simple_index_versions` reads the versions out of it, dropping wheels the interpreter's tags do not accept when given them (`wheel_stem_matches_compatibility` and the `wheel_*_tag_matches` helpers); `package_release_key` orders the PEP 440 versions found there (`PackageReleaseKey`). `slugify`, which keys the cached listing, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The functions and types `therock.rs` and `therock/update.rs` name are `pub(in crate::therock)` and reach them through `therock/resolve.rs`; `PipRuntimeResolution` and `TheRockPipPackageVersions` are `pub(in crate::therock)` with the fields they read, and `TorchaudioPin` with its `describe`, so they can use what `resolve_pip_runtime` returns without naming the types; the rest is private. -- [`therock/resolve/uv_access.rs`](../apps/rocm/src/therock/resolve/uv_access.rs) — full domain extraction, a leaf child of `therock/resolve.rs` that builds only on `therock/source.rs` for `SourceLayout` (split out of `therock/resolve/wheel.rs` to keep it within the module-size limit): who may fetch `uv` while a wheel stack is resolved. `UvAccess` says how far a resolution may go (`Acquire`, what a real install and `rocm update` pass, or `PresentOnly`, a preview's), `plan_version_resolution` turns that, the layout and whether a `uv` is present into a `VersionResolution` (scrape the indexes, compile with a `UvChoice`, or skip) without touching anything, and `uv_for_compile` hands the compile step the `uv` it runs, acquiring it only on `Acquire`, with the context a failed fetch has always carried. `UvPolicy` carries the access and the two real lookups (`find_uv_binary`, `ensure_uv_binary`) as closures so a test can count what a resolution asks for. Everything is `pub(super)` and read by `wheel.rs`; the state matrix over layout, access and presence lives in this module's tests. -- [`therock/consent.rs`](../apps/rocm/src/therock/consent.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/source.rs` and `therock/version.rs` and reaches the registry through [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) (split out of `therock.rs`): the consent gate for an install that would displace the active default runtime. `active_default_runtime_relation` says what the install would replace (an upgrade, downgrade or reinstall when it is the same family and channel, otherwise the different runtime it displaces) or `None` when nothing is the active default, and it fails closed, with a relation naming what could not be resolved, when the config names an active default the registry cannot resolve; `SdkInstallConsent` and `SdkInstallApprovalSource` say how consent is obtained (asked for, or already granted by `--yes`, `--approve-replacing-active-default` or `rocm update --apply`); `sdk_install_approval` turns those and whether a terminal is attached into proceed, prompt or refuse (`SdkInstallApproval`); `preapproved_install_line`, `fresh_install_line`, `refuse_non_interactive_message` and `confirm_overwrite_existing_sdk` are the wording of each outcome, and the prompt reads its answer through `prompt_yes_no` and the shared [`confirm.rs`](../crates/rocm-core/src/confirm.rs). `SdkInstallConsent`, `SdkInstallApprovalSource` and `preapproved_install_line` are re-exported by `therock.rs`; the other items `therock.rs` calls are `pub(super)`, as is `active_default_relation_text`, which the version property tests call, and the rest is private. -- [`therock/wheel_plan.rs`](../apps/rocm/src/therock/wheel_plan.rs) — full domain extraction, a leaf child of `therock.rs` (split out of `install_wheel_runtime`) that builds on `therock/python.rs` and `therock/resolve.rs` for the Python decision and the resolution it prints: the `sdk install` plan a wheel install prints, key by key. `WheelPlan` carries the facts, `write_wheel_plan` writes the lines a preview and a real install share, and `write_dry_run_tail` the lines only a preview adds (the `uv` commands it would run and the manifest path). `PlanStack` is the one place the plan differs: `Resolved` carries the package specs, runtime key, install folder and manifest path, and `NeedsUv` (a ROCm 10 preview on a host with no `uv`, see `UnresolvedPipRuntime` in `therock/resolve/wheel.rs`) prints those as `not resolved by this preview` and adds the `resolution_note:` line, so one writer serves both and a line the plan gains appears in both. `unresolved_wheel_preview` renders the second kind whole. `therock.rs` reads it through `pub(super)` items; it reads the provenance, host-note and `venv_python_path` helpers back from `therock.rs`. -- [`therock/update.rs`](../apps/rocm/src/therock/update.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/family.rs`, `therock/process.rs`, `therock/python.rs`, `therock/resolve.rs`, `therock/source.rs` and `therock/version.rs`, on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for the manifests and on rocm-core's [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs) for the startup-check record (split out of `therock.rs`): whether an installed runtime has something newer, and the bounded startup check that asks. `runtime_update_plan` resolves the latest source for one runtime, and `runtime_update_check` does the same for a caller that changes nothing (the report, the JSON, the startup check and an apply's preview): given a wheel runtime that records no usable Python, the plan prepares a managed Python (an apply needs one) while the check works the wheel tag out from the interpreter the layout requires and carries a `python_note` instead (`resolve_latest_for_manifest` re-resolves a wheel runtime through `resolve_pip_runtime_with_timeout` and a tarball one through `resolve_tarball_artifact_with_timeout`, on the layout `manifest_source_layout` reads back from the manifest) and `runtime_freshness` classifies it (`RuntimeFreshness`: up to date, update available, repair available when the installed composition is not the one a fresh install would record, or ahead of the index) into a `RuntimeUpdatePlan`. `render_update_report` and `render_update_json` (the form the dashboard's update check parses) present the plans, and `maybe_refresh_startup_update_check` keeps one `StartupUpdateCheckRecord` in the cache so the check runs at most once every twelve hours, under a two-second download timeout. `runtime_key` and `wheel_runtime_key`, which name the install a plan targets, stay in `therock.rs`; whether a replacement's root is installed is `rocm_core::install_root_has_payload`. `render_update_report`, `render_update_json`, `runtime_update_plan`, `runtime_update_check` and `maybe_refresh_startup_update_check` are `pub(crate)` and, with `RuntimeUpdatePlan`, which [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs) reads its verdict from, re-exported by `therock.rs`; `RuntimeFreshness`, `runtime_freshness` and `select_startup_update_manifest` are `pub(super)` for the version property tests, and the rest is private. -- [`therock/test_support.rs`](../apps/rocm/src/therock/test_support.rs) — test-only (`#[cfg(test)]`), a child of `therock.rs`: fixtures shared by the `therock` child modules' tests and the tests left in `therock.rs` (`test_paths`, `test_runtime_manifest`, `write_test_runtime_manifest`, `family_for_test`, and `RestoredEnv`, which sets or removes process environment variables for one test and puts them back on drop, so a caller holds `PROCESS_ENV_TEST_LOCK` for as long as it holds one). Separate from the crate-level [`test_support.rs`](../apps/rocm/src/test_support.rs), which holds the fixtures every module's tests share, such as `PROCESS_ENV_TEST_LOCK` and the background-helper fixtures `runtime_state` and `set_helper_facts`. -- [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs) — the chat assistant's tool-call policy: which `rocm` commands and bridge tools a model may request, which run immediately and which need the user's approval first. It owns `ChatRocmCommandAction` (read-only, or approval with the titles the approval prompt shows) and `ChatToolApprovalRequest`, the validators (`validate_chat_tool_call`, the `validate_chat_*_tool_call` family, `validate_required_chat_string`, `validate_optional_chat_integer`, `reject_control_characters_in_tool_arguments` (which refuses a model-supplied tool name or argument carrying a terminal control character, for every tool except `rocm_command`, whose argv `normalized_chat_rocm_command_args` screens entry by entry), `validate_serve_command_safety`, the four rules a model-proposed `serve` must satisfy (no public bind, no CPU device, a loopback host, `--managed` without `--foreground`), and `validate_chat_rocm_command_safety`, which applies them to a `serve` argv and also refuses a system install folder (`chat_install_prefix_is_system`)), the classifiers (`chat_rocm_command_action`, `chat_rocm_command_action_from_args`, `chat_install_driver_action`, `canonicalize_chat_rocm_command`, `normalized_chat_rocm_command_args`, `chat_tool_call_is_read_only`), `chat_tool_approval_request`, and the readers that turn a tool call into its argv and one-line command (`rocm_chat_tool_requested_args`, `rocm_chat_tool_requested_command`, with `push_optional_json_cli_arg` and `json_string`). It moved verbatim from `chat.rs` with the tests that exercise only these items. It depends on [`rocm_argv.rs`](../apps/rocm/src/rocm_argv.rs), `providers::ChatToolCall`, `service_launch::is_loopback_host`, `services_text::validate_service_id`, `shell_quote::has_terminal_control_character`, `therock::RuntimeVersionSelector` and `driver_install::host_install_driver_only_reports`, none of which imports `chat`, so `freeform_planner.rs` calls `validate_serve_command_safety` and `validate_chat_rocm_command_safety` here instead of through `chat`, and keeps no copy of the serve rules. `chat.rs`'s child modules call into it and `chat.rs` re-exports `validate_chat_tool_call`, `chat_tool_call_is_read_only` and `chat_tool_approval_request` (read by `dash_seam.rs`), and `ChatRocmCommandAction`, `chat_install_driver_action`, `chat_rocm_command_action_from_args` and `rocm_chat_tool_requested_args`, which only other modules' tests read as `crate::chat::` (`driver_plan.rs`, `system_packages.rs`). -- [`uninstall.rs`](../apps/rocm/src/uninstall.rs) — mechanical relocation, owns types: `uninstall()`, the refusal of the hidden `--force` (`reject_force`, which `main.rs` calls from the `uninstall` dispatch arm), plus the installer `PATH` undo, the removal of the fish completion script the Linux installer recorded writing (`plan_completion_removals`, which takes only a regular `completions/rocm.fish` whose first line is the installer's marker naming this install folder, tied to `install.sh` by a test; `execute_plan` rechecks the file before removing it and reports a removal failure as a warning instead of stopping, for the `SHELL_COMPLETIONS_KIND` plan entries it adds), and running-executable deletion. The shared plan type and its file-removal helpers live in [`uninstall_plan.rs`](../apps/rocm/src/uninstall_plan.rs) below instead, because [`storage.rs`](../apps/rocm/src/storage.rs) reuses them too. The two modules depend on each other: `uninstall_plan.rs` reads this module's `pub(crate)` `PathEdit`, `PATH_EDIT_RECORD`, `plan_path_edits`, `plan_is_empty`, `removal_count` and `render_extra_plan`. -- [`uninstall_plan.rs`](../apps/rocm/src/uninstall_plan.rs) — mechanical relocation, shares crate-visible types (Phase 6f, ROCMAI-212): the uninstall-plan types (`UninstallOptions`, `UninstallPlan`, `UninstallPlanEntry`), the `PlanAudience` a rendered plan is written for (a person at a terminal, a captured caller, or the assistant's preview), which decides what the dry-run footer says comes next, building the plan (`build_uninstall_plan`, `plan_installed_binaries`, and the installed-binary/shared-cache discovery helpers behind them), rendering it (`render_uninstall_dry_run`, which renders for the assistant, and `render_uninstall_plan`), the `[y/N]` confirmation prompt (`confirm_uninstall`), and the filesystem removal primitive both [`uninstall.rs`](../apps/rocm/src/uninstall.rs) and [`storage.rs`](../apps/rocm/src/storage.rs) call to carry a plan out (`remove_path`, and the entry-resolution helpers behind it). Kept separate from `uninstall.rs` rather than folded into it, since `uninstall.rs`'s own doc comment and name both describe `uninstall()`'s exclusive logic (the installer `PATH` undo and running-executable deletion), while this module's plan/render/removal helpers are shared with `storage.rs`. `main.rs` (`UninstallOptions`), `uninstall.rs` (which also imports `PlanAudience` and picks it from `interactive_terminal`), `storage.rs`, `runtimes_cmd.rs`, `chat/mcp_bridge.rs` (which calls `render_uninstall_dry_run` and does not import `PlanAudience`), and [`deletion_properties.rs`](../apps/rocm/src/deletion_properties.rs) (Unix-only property tests, which render as `PlanAudience::Captured`) each import the subset of these `pub(crate)` types and helpers they need; see this module's own doc comment for which symbol each one uses. -- [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types (Phase 6f, ROCMAI-210): `rocm update`'s command handler (`update()`, the body of the `update` arm of `dispatch()`) and its rendering/activation logic — the read-only status report (`render_update_text`, `append_update_surfaces`), the predicate deciding whether `update` should route into the mutating path instead of that report (`update_should_preview_or_apply`), applying a runtime update (`apply_runtime_update`, a thin wrapper that hands `apply_runtime_update_with` the check and the plan from `therock/update.rs`, so a unit test can run the choice between them on any platform; `append_update_activate_summary`), and the update-source/installed-runtime pickers behind it (`select_runtime_update_source`, `select_installed_update_runtime`). `const ROLLBACK_RECOVERY_HINT` stays in `main.rs` as a shared crate-root constant, because callers outside this module also use it ([`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs)'s `RuntimesCommand::Activate` handler and [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)'s `render_sdk_install_success`); this module reaches it via its `use crate::{...};` import, the same way `gpu_policy.rs`'s `device_policy_name` stays in `main.rs`. `update()` is `pub(crate)` and called from [`main.rs`](../apps/rocm/src/main.rs)'s `dispatch()` through a re-import (`use crate::update_cmd::update;`), and calls `update_should_preview_or_apply`, `apply_runtime_update` and `render_update_text` itself; `render_update_text` is also `pub(crate)` and read from [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs) (the read-only `rocm update` handling), while `apply_runtime_update` and `update_should_preview_or_apply` keep the `pub(crate)` they had when `dispatch()` called them directly, though only `update()` calls them now; `select_runtime_update_source` is also `pub(crate)`, read from [`therock_version_proptests.rs`](../apps/rocm/src/therock_version_proptests.rs)'s property tests via `crate::update_cmd::select_runtime_update_source`. `append_update_surfaces`, `append_update_activate_summary`, and `select_installed_update_runtime` have no callers outside this module and stay private. The cluster's regression tests live in `update_cmd.rs`'s own `mod tests`, reaching shared fixtures (`test_paths`, `test_runtime_manifest_for_update`, `write_test_pip_runtime`) through `crate::tests::`/`crate::test_support::` the same way other mechanically relocated modules do. - -Further `apps/rocm` modules, not part of the `main.rs` split: - -- [`advised_commands.rs`](../apps/rocm/src/advised_commands.rs) — test-only (`#[cfg(test)]`): checks that every `rocm …`/`rocmd …` command the repository advises — in `--help` text, production string literals, the markdown docs and skills, and the VHS tapes — exists and parses, by running it through the parser of the binary it names (`rocm`'s clap `Cli`, or `rocmd`'s `parse_args`). -- [`comfyui/install.rs`](../apps/rocm/src/comfyui/install.rs) — child module of [`comfyui.rs`](../apps/rocm/src/comfyui.rs): `rocm comfyui install`, including its dry run and the reinstall that replaces ComfyUI's code (through [`comfyui/source_swap.rs`](../apps/rocm/src/comfyui/source_swap.rs)) while refusing to do so under a running ComfyUI. It downloads and unpacks the source archive, installs ComfyUI's Python dependencies into the selected runtime with uv (filtering out and pinning the runtime's own torch stack, and streaming uv's output to the install log) and runs the AMD GPU check. The manifest, the install log paths and the GPU probe stay in `comfyui.rs`. It imports `runtime_env` and, for the running-ComfyUI guard, `process`; neither imports it. Its unit tests and the Unix-only `archive_properties` property tests for the source unpack live in the module; the fixtures they share with the tests left in `comfyui.rs` stay there. -- [`comfyui/process.rs`](../apps/rocm/src/comfyui/process.rs) — child module of [`comfyui.rs`](../apps/rocm/src/comfyui.rs): the lifecycle of the ComfyUI process this CLI launches. `start` checks the installed folder, runs the GPU check, launches ComfyUI in the background (a detached child on Linux, a hidden PowerShell launcher on Windows) and waits for its port; `stop` ends the saved process tree. `evaluate_running_state` tells a running, a still-loading and a stopped ComfyUI apart for `status`, and `running_from`, `refuse_while_running` and `running_advice` are the guard that refuses a reinstall while ComfyUI runs from the folder it would replace. The saved state and the types in it stay in `comfyui.rs`. Among the `comfyui` children it imports from [`comfyui/runtime_env.rs`](../apps/rocm/src/comfyui/runtime_env.rs) and uses [`comfyui/source_swap.rs`](../apps/rocm/src/comfyui/source_swap.rs) to check for an interrupted reinstall; neither imports it, so there is no cycle. -- [`comfyui/runtime_env.rs`](../apps/rocm/src/comfyui/runtime_env.rs) — child module of [`comfyui.rs`](../apps/rocm/src/comfyui.rs): choosing which installed ROCm runtime ComfyUI runs against (`select_runtime`, with the messages that tell the user how to pick one when none or several are ready) and building the `VIRTUAL_ENV`, `ROCM_PATH`, `PATH` and library-path environment a ComfyUI child process runs with. When no `--runtime-id`, active runtime or configured default says which runtime to use, `select_runtime` does not decide which runtimes count as ready itself: it asks [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs)'s `select_single_ready_runtime`, the same rule the engine paths use, and only words the answer (`single_ready_runtime_or_refusal`), so ComfyUI keeps its own remediation text. `select_runtime` takes the `SetupRecovery` to ask it with, which the install derives from `--dry-run`, so a preview does not write the registry entry the real run would restore. A choice that does name a runtime (`--runtime-id`, the active runtime, the configured default) is looked up in the registry first (`pick_from_registry`); only when the registry alone cannot answer is it looked up again among the registry plus the runtime `rocm setup` created, so the `--runtime-id` an install preview prints works from the state the preview left, and an unusable setup runtime leaves the registry's own refusal standing (with nothing chosen it is likewise set aside while the registry holds a ready runtime, and reported only when none does). The setup runtime is found and picked without writing, and a real run writes its entry back only for a pick it is going to use, so a registry that cannot take the entry is reported as that failure rather than as a missing runtime. The types it returns (`SelectedRuntime`, `ComfyUiRuntimeEnvironment`) stay in `comfyui.rs`, which the module imports from; it imports nothing from the other `comfyui` children. -- [`comfyui/source_swap.rs`](../apps/rocm/src/comfyui/source_swap.rs) — child module of [`comfyui.rs`](../apps/rocm/src/comfyui.rs): replacing ComfyUI's code in an existing `source/` folder on reinstall without touching anything else there. -- [`remote/mod.rs`](../apps/rocm/src/remote/mod.rs) — `rocm remote`: driving a remote GPU host from this machine, with SSH as the control channel and the remote's own service published onto the tailnet for inference traffic. Like [`bootstrap.rs`](../apps/rocm/src/bootstrap.rs), it owns its command enum (`RemoteCommand`) and dispatch fn (`run`). Its `pub(crate)` submodules: - - [`remote/bootstrap.rs`](../apps/rocm/src/remote/bootstrap.rs) — deciding whether a remote machine can host a model before asking it to. - - [`remote/doctor.rs`](../apps/rocm/src/remote/doctor.rs) — checking a remote machine's health from here. - - [`remote/install.rs`](../apps/rocm/src/remote/install.rs) — installing ROCm on an unattended remote machine. - - [`remote/provision.rs`](../apps/rocm/src/remote/provision.rs) — putting the ROCm CLI on a remote machine that does not have it. - - [`remote/publish.rs`](../apps/rocm/src/remote/publish.rs) — publishing a remote machine's loopback service onto the tailnet. - - [`remote/session.rs`](../apps/rocm/src/remote/session.rs) — local records of work running on other machines. - - [`remote/tailnet.rs`](../apps/rocm/src/remote/tailnet.rs) — reading the local tailnet: which machines exist, and how to address one. - - [`remote/transport.rs`](../apps/rocm/src/remote/transport.rs) — the SSH control channel to a remote GPU host. +The `rocm` binary: the clap command tree, a handler module for most commands, and the domains behind them (runtimes and TheRock installs, managed services, the chat assistant and freeform planner, ComfyUI, remote hosts). [`main.rs`](../apps/rocm/src/main.rs) is the crate root; the directory modules (`chat/`, `comfyui/`, `driver_plan/`, `providers/`, `remote/`, `runtime_install_finalize/`, `service_launch/`, `therock/`) are rows in the same table, sorted by path. + +| File | Responsibility | Class | +| --- | --- | --- | +| [`main.rs`](../apps/rocm/src/main.rs) | Crate root: `main` and `run`, `dispatch()` over the clap `Command` tree, the clap command builders, freeform-invocation routing, the `version` and bare-`rocm` handlers, and the few items several modules share. | flat | +| [`advised_commands.rs`](../apps/rocm/src/advised_commands.rs) | Test-only check that every `rocm ...`/`rocmd ...` command the repository advises (help text, string literals, docs, skills, VHS tapes) exists and parses with the flags it is given. | flat | +| [`automations.rs`](../apps/rocm/src/automations.rs) | `rocm automations` (`automations`) and the status and proposal text it prints, plus the `rocm daemon --status` summary (`render_daemon_text`). | relocation | +| [`background_helper.rs`](../apps/rocm/src/background_helper.rs) | What the CLI can tell about the background automation helper (`rocm daemon`): whether it is running, and the note shown about it after a service stop or in an uninstall plan. | relocation | +| [`bootstrap.rs`](../apps/rocm/src/bootstrap.rs) | `rocm bootstrap`: owns `BootstrapCommand` and its dispatch `run`, which opens the dashboard's setup flow in a terminal and otherwise prints how to run it. | domain | +| [`bridge_snapshot.rs`](../apps/rocm/src/bridge_snapshot.rs) | The host snapshot behind the internal bridge surface (`build_codex_bridge_snapshot`): examination, config, automation state, managed services, GPUs and the built-in engine list. | relocation | +| [`chat.rs`](../apps/rocm/src/chat.rs) | The chat assistant's entry points (`render_chat_text`, `render_chat_prompt_text`, `read_piped_prompt`), the sampling-flag value parsers, and the re-exports other modules reach `chat/` through. | flat | +| [`chat/intent.rs`](../apps/rocm/src/chat/intent.rs) | Prompt-intent heuristics: decides from the user's latest message alone which tool call the assistant proposes without the local model (`fallback_rocm_tool_call_for_prompt`) and when an install needs approval. | relocation | +| [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs) | The tool dispatch behind `rocm mcp-call`, the dash execution seam and the assistant's read-only tools (`run_internal_mcp_call`), and the in-process runner for read-only `rocm` commands. | relocation | +| [`chat/summaries.rs`](../apps/rocm/src/chat/summaries.rs) | Deterministic plain-language summaries of read-only tool output (`deterministic_chat_tool_summary`), shown instead of asking the local model to restate it. | domain | +| [`chat/turn.rs`](../apps/rocm/src/chat/turn.rs) | The chat turn loop and transcript (`render_chat_prompt_result_with_progress`): the system prompt, the provider call, running the read-only tools a reply requests, and rendering the reply. | relocation | +| [`chat_cmd.rs`](../apps/rocm/src/chat_cmd.rs) | `rocm chat` (`run_chat_command`): hands off to the dashboard chat in an interactive terminal with no `--prompt`, otherwise prints the one-shot reply or the status screen. | relocation | +| [`chat_host_facts.rs`](../apps/rocm/src/chat_host_facts.rs) | The OS, WSL and GPU facts the binary detects cheaply and renders as a plain-text block for the chat assistant's system prompt. | domain | +| [`cli.rs`](../apps/rocm/src/cli.rs) | The `rocm` clap definition: `Cli`, `Command`, the nested subcommand enums and `SUPPORTED_ENGINES`, and a re-export of the value enums behind flags such as `--provider` and `--device`, which [`cli_args.rs`](../apps/rocm/src/cli_args.rs) defines. | flat | +| [`cli_args.rs`](../apps/rocm/src/cli_args.rs) | The clap value enums behind `--provider`, `--device`, `--framework` and similar arguments (`Provider`, `DevicePolicyArg`, `FrameworkArg`, `InstallFormat`, `WatcherModeArg`, `TelemetryModeArg`, `SandboxToolArg`, `PermissionsModeArg`) and the conversions from a value enum to its domain type. [`cli.rs`](../apps/rocm/src/cli.rs) re-exports every one, so other modules keep reaching them as `crate::cli::Provider`; moved so `cli.rs`, which every new subcommand grows, stays under the module size limit. | relocation | +| [`cli_audit.rs`](../apps/rocm/src/cli_audit.rs) | The CLI audit and lifecycle log (`record_cli_audit_event`): one audit event, mirrored as a line in `logs/cli-lifecycle.log` and in a per-action file under `logs/cli/`. | relocation | +| [`cli_progress.rs`](../apps/rocm/src/cli_progress.rs) | Shared TTY-gated progress indicators on stderr: `Spinner`, advanced by the caller's loop, and `AnimatedSpinner`, which keeps animating between caller updates. | flat | +| [`cli_report.rs`](../apps/rocm/src/cli_report.rs) | Shared CLI output formatters: `ActionReport` (headline plus indented details), `write_marked_row` for marked listings, and `JsonOrText`/`print_json_or_text` for `--json` commands. | flat | +| [`comfyui.rs`](../apps/rocm/src/comfyui.rs) | `rocm comfyui`: the dispatch fn `run` (auditing each action), ComfyUI's types, paths, manifest and state files, the `status` and `logs` text, and the Python-child helpers. | domain | +| [`comfyui/install.rs`](../apps/rocm/src/comfyui/install.rs) | `rocm comfyui install`, dry run and reinstall included: fetching and unpacking the source, installing its Python dependencies into the chosen runtime with the torch stack pinned, and the GPU check. | domain | +| [`comfyui/process.rs`](../apps/rocm/src/comfyui/process.rs) | Starting, stopping and watching the ComfyUI process (`start`, `stop`, `evaluate_running_state`), and the guard that refuses a reinstall while ComfyUI runs from that folder. | domain | +| [`comfyui/runtime_env.rs`](../apps/rocm/src/comfyui/runtime_env.rs) | Choosing the ROCm runtime ComfyUI runs against (`select_runtime`) and building the virtualenv, ROCm and library-path environment its process needs. | domain | +| [`comfyui/source_swap.rs`](../apps/rocm/src/comfyui/source_swap.rs) | Replacing ComfyUI's code in an existing `source/` folder on reinstall while keeping the user's models, workflows, outputs and other files there. | domain | +| [`config_cmd.rs`](../apps/rocm/src/config_cmd.rs) | `rocm config` (`config`): applies each subcommand to the saved configuration, prompts for a provider API key, and renders `rocm config show`. | relocation | +| [`dash.rs`](../apps/rocm/src/dash.rs) | `rocm dash` and the other ways into the dashboard TUI (launcher, chat, bench, setup): builds the telemetry daemon options and starts an embedded daemon when none is listening. | domain | +| [`dash_seam.rs`](../apps/rocm/src/dash_seam.rs) | The binary's implementation of the dashboard's `RocmToolExecutor` seam, reusing the CLI's own command functions with plain data in and out. The seam exists because `rocm-dash-tui` (like `rocm-dash-core`) must not depend on `rocm-core`; `rocm-dash-collectors` and `rocm-dash-daemon` do depend on it. | domain | +| [`deletion_properties.rs`](../apps/rocm/src/deletion_properties.rs) | Unix-only property tests for the recursive deletions behind `rocm uninstall` and `rocm storage remove-downloads`, checked against a real sandbox filesystem. | flat | +| [`diagnose_cmd.rs`](../apps/rocm/src/diagnose_cmd.rs) | `rocm diagnose` and `rocm fix` (`diagnose`, `fix`), and the `--report` step that builds a report naming this build's leading version (`prepare_cli_report`), shows it and offers to deliver it. | relocation | +| [`diagnose_model.rs`](../apps/rocm/src/diagnose_model.rs) | The binary's side of `rocm diagnose --model`'s GGUF context estimate: the `--kv-cache-type` and model flags, the `--report` note, and the device-visibility-mask caveat. | domain | +| [`driver_install.rs`](../apps/rocm/src/driver_install.rs) | `rocm install driver` (`install_driver`, `reconcile_driver_install`): runs an approved plan's commands and persists the driver install state. It re-exports `host_install_driver_only_reports` from [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs) for its callers, [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs) and [`freeform_planner.rs`](../apps/rocm/src/freeform_planner.rs). | relocation | +| [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs) | The `rocm install driver` plan: its model, its printed text, and the per-distro builders (apt, dnf, zypper) from the host's examination and os-release. | domain | +| [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs) | The WSL2 rocDXG driver plan, which installs the digest-pinned `rocdxg-roct` package or refuses when the download cannot be authenticated. | domain | +| [`endpoint_keys.rs`](../apps/rocm/src/endpoint_keys.rs) | Per-service inference-endpoint API keys, stored in 0600 files under the services directory, keyed by service id. | relocation | +| [`engine_install_env.rs`](../apps/rocm/src/engine_install_env.rs) | Which runtime an engine installs into and where its environment lives (`engine_manages_own_runtime`, `env_root_for_engine_install`), shared by the engine and SDK install paths. | relocation | +| [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs) | Locating an engine's plugin binary, the engine request entry points (answering from the in-process built-in handler, or running the resolved engine binary with `stdio`), and the in-process built-in engine path. `engine_stdio_child_request` hands the child to the stdio client `rocm` shares with `rocmd`, [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs), and chooses what `rocm` asks of it: the app paths and engine environments root for the child, progress for an install, and the child's stderr forwarded to the terminal. | relocation | +| [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs) | Which runtime a `serve` or `engines install` resolves to (`resolve_engine_selection`), the argv and `ROCM_CLI_*` env of a managed child (over [`AppPaths::env_vars`](../crates/rocm-core/src/paths.rs)), and HTTP readiness polling of a launched service. | relocation | +| [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs) | `rocm engines` (`engines`), the readiness check `serve` runs for self-managed engines, and the environment root of a running service. | relocation | +| [`examine_cmd.rs`](../apps/rocm/src/examine_cmd.rs) | `rocm examine` (`examine`): the human report, or with `--json` the examination plus a summary of what only the CLI knows. | relocation | +| [`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs) | The `rocm examine` text reports, the bare-`rocm` launch summary, and the engine-inventory listing shared by `rocm engines` and `rocm examine`. | relocation | +| [`freeform_answer.rs`](../apps/rocm/src/freeform_answer.rs) | Answers a freeform request gets without running a command: a single approval-free `examine`, `comfyui status` or `comfyui logs` action. | relocation | +| [`freeform_execution.rs`](../apps/rocm/src/freeform_execution.rs) | Whether a freeform plan's next action may run and the consent flags it needs (`prepare_freeform_execution`), and the header printed before it runs. | relocation | +| [`freeform_planner.rs`](../apps/rocm/src/freeform_planner.rs) | The freeform natural-language planner: turns a prose request into a `StructuredRequestPlan` of `rocm` tool calls, deterministically or with a configured planner provider, and renders it. | domain | +| [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs) | `--device`/`--gpu` parsing, GPU selection under the managed-launch lock, per-GPU VRAM readings (`amd-smi`, with a DRM sysfs fallback) and the serve low-VRAM warning. | relocation | +| [`gpu_selection_proptests.rs`](../apps/rocm/src/gpu_selection_proptests.rs) | Property tests for `--gpu` auto-selection and explicit-index validation, declared from [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs). | flat | +| [`install_cmd.rs`](../apps/rocm/src/install_cmd.rs) | `rocm install` (`install`) for the `sdk` and `driver` targets, the `--version`/`--build-date` selector, and mapping `install sdk` arguments onto a `therock::SdkInstallRequest`. | relocation | +| [`logging.rs`](../apps/rocm/src/logging.rs) | Client-side structured logging: a file-only, non-blocking `tracing` subscriber for the CLI and dashboard process that never writes to stdout or stderr. | relocation | +| [`managed_service_status.rs`](../apps/rocm/src/managed_service_status.rs) | Managed-service liveness (`managed_service_is_live`, the duplicate-launch guard), loading service records, and the dashboard-sidebar status and counts. Service-record removal and pruning, the deferred key cleanup and the reconciliation to `stopped` here take a recorded process for gone only when `probe_process` confirms it: a process that cannot be queried counts as possibly running. When the deferred cleanup does complete it also forgets the recorded processes and reads the record as stopped, so a later stop cannot signal a recycled PID. An unconfirmed stop of a container-backed engine, decided by the engine `Stop`, is never completed or read as stopped from the supervisor's PID, and `container_stop_unresolved` makes the in-use check treat it as in use. | relocation | +| [`model_catalog_text.rs`](../apps/rocm/src/model_catalog_text.rs) | The `rocm model` catalog renderer: the curated list by hardware target, the `--verbose` per-recipe diagnostics, and `format_bytes`. | relocation | +| [`model_fit.rs`](../apps/rocm/src/model_fit.rs) | Whether this host can run a model, for `rocm diagnose --model` (`assess_model_on_this_host`), and the platform gate that rules an engine out (`engine_ruled_out_by_platform`). | relocation | +| [`prompt_text.rs`](../apps/rocm/src/prompt_text.rs) | Phrase matching and the install-folder, build-date, version and engine readers for a natural-language request, shared by the chat heuristics and the freeform planner. | flat | +| [`provider_keys.rs`](../apps/rocm/src/provider_keys.rs) | Cloud provider (OpenAI, Anthropic) API keys: read from the environment or the OS keyring, stored and removed in the keyring with no plaintext fallback, and their status label. | domain | +| [`providers.rs`](../apps/rocm/src/providers.rs) | Chat model providers: the request/response types, the `ProviderAdapter` dispatch, `LocalProvider` and `RemoteProvider`, local-service selection and the remote transport. | domain | +| [`providers/local_http.rs`](../apps/rocm/src/providers/local_http.rs) | The local provider's hand-rolled HTTP/1.1 transport: a blocking JSON POST and a streamed POST read in chunked, `Content-Length` or close-delimited framing. | domain | +| [`providers/local_http/proptests.rs`](../apps/rocm/src/providers/local_http/proptests.rs) | Property tests that re-chunk, truncate, stall and interrupt SSE bodies against the local transport's readers. | flat | +| [`providers/tool_schema.rs`](../apps/rocm/src/providers/tool_schema.rs) | The ROCm tool catalog advertised to a model, as OpenAI function definitions and reshaped for Anthropic's `tools` field. | domain | +| [`providers/wire.rs`](../apps/rocm/src/providers/wire.rs) | The OpenAI-compatible and Anthropic wire formats: request bodies (with the local-model defaults), non-streaming response parsers, and the SSE emitters. | domain | +| [`providers/wire/sse_emitter_proptests.rs`](../apps/rocm/src/providers/wire/sse_emitter_proptests.rs) | Split-invariance and panic-guard tests for the SSE emitters and line parsers in [`providers/wire.rs`](../apps/rocm/src/providers/wire.rs). | flat | +| [`remote/mod.rs`](../apps/rocm/src/remote/mod.rs) | `rocm remote`: owns `RemoteCommand` and its dispatch `run`, driving a remote GPU host over SSH while inference traffic goes to the remote's tailnet-published service. | domain | +| [`remote/bootstrap.rs`](../apps/rocm/src/remote/bootstrap.rs) | Deciding whether a remote machine can host a model (GPU stack, ROCm CLI, Tailscale, known platform), refusing up front when it cannot. | domain | +| [`remote/doctor.rs`](../apps/rocm/src/remote/doctor.rs) | Checking a remote machine's health: facts are gathered on the remote and scored here against the same failure-mode catalog the local command uses. | domain | +| [`remote/install.rs`](../apps/rocm/src/remote/install.rs) | Installing ROCm on an unattended remote machine, behind guards for a human not being present. | domain | +| [`remote/provision.rs`](../apps/rocm/src/remote/provision.rs) | Putting the ROCm CLI on a remote machine that lacks it by running the project's installer there, never by copying this machine's binary. | domain | +| [`remote/publish.rs`](../apps/rocm/src/remote/publish.rs) | Publishing a remote machine's loopback service onto the tailnet through the remote's own Tailscale daemon, so nothing stays running on this end. | domain | +| [`remote/session.rs`](../apps/rocm/src/remote/session.rs) | Local records of the model servers and tailnet publishes running on other machines, so a later `rocm remote status` or `rocm remote stop` can find them. | domain | +| [`remote/tailnet.rs`](../apps/rocm/src/remote/tailnet.rs) | Reading the local tailnet through the local Tailscale daemon only: which machines exist and how to address one. | domain | +| [`remote/transport.rs`](../apps/rocm/src/remote/transport.rs) | The control channel to a remote host: the `Transport` trait (run a command, copy a file) and `SshTransport`, which shells out to the system `ssh` and `scp`. | domain | +| [`rocm_argv.rs`](../apps/rocm/src/rocm_argv.rs) | Argv helpers shared by the chat code, [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs) and the freeform planner: option lookups, `ensure_flag`, the CPU-device check, and `format_structured_tool_call`. | flat | +| [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs) | Registering runtimes `rocm install sdk` did not install (import, adopt, recovering the `rocm setup` runtime) and the one ready-runtime rule (`select_single_ready_runtime`). | domain | +| [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) | Settling an engine onto a runtime after an SDK install (`finish_sdk_install`, `settle_engine_install`): engine-dependency and device checks and the post-install verdict. | relocation | +| [`runtime_install_finalize/torch_alignment.rs`](../apps/rocm/src/runtime_install_finalize/torch_alignment.rs) | Whether an engine install realigns the runtime's torch to the engine's pin or keeps it as an intended divergence, running and reporting that, and the manifest readers it uses. | domain | +| [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) | The installed-runtime registry: the manifest model, where manifests live, writing and loading them, selection and activation validation, and the active-runtime marker. | domain | +| [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs) | Reconciling running local servers with a runtime being activated or rolled back: classifying each, the report, and moving stale ones with `--restart-services`. | domain | +| [`runtime_uninstall.rs`](../apps/rocm/src/runtime_uninstall.rs) | `rocm runtimes uninstall`: planning, revalidating after the prompt, and applying the removal of a registered runtime, including clearing a Lemonade record inside its folder. | domain | +| [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) | `rocm runtimes` (`runtimes`): activation and rollback with the active-runtime marker write, and the runtime list. | relocation | +| [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) | `rocm serve` (`serve`): engine selection (`select_serve_engine`), the AIM pre-flight, and the GPU and device notes folded into the summary. | relocation | +| [`serve_port.rs`](../apps/rocm/src/serve_port.rs) | The `rocm serve` port policy: turns an automatic or explicit `--port` request into one leased port before any manifest, log, key or child exists. | domain | +| [`serve_recipe.rs`](../apps/rocm/src/serve_recipe.rs) | The pure transforms `serve()` applies to an engine's launch recipe hint: the catalog mapping, then `--tool-call-parser`, `--gpu-memory-utilization`, generation defaults and `--engine-env`. | relocation | +| [`serve_summary.rs`](../apps/rocm/src/serve_summary.rs) | The engine-agnostic `rocm serve` deployment summary: a status indicator while the server starts, an inference smoke test, and the endpoint and timing table. | domain | +| [`service_control.rs`](../apps/rocm/src/service_control.rs) | Stopping and restarting a managed local server (`rocm services stop` and `restart`, runtime moves) and the internal sandbox-tool runner (`run_internal_sandbox_tool`). Its stop path, `stop_recorded_processes`, hands the recorded PIDs to the routine [`proc_lifecycle.rs`](../crates/rocm-core/src/proc_lifecycle.rs) shares with `rocmd`. | relocation | +| [`service_hints.rs`](../apps/rocm/src/service_hints.rs) | The shared builder of the hint text that tells a user how to stop, restart or remove a service with `--yes`, plus the forced-removal hint (`service_forced_remove_hint`, `rocm services remove --force --yes`) and the command word, verb and past tense for a service tool. | flat | +| [`service_launch.rs`](../apps/rocm/src/service_launch.rs) | Front of the `service_launch/` children: their declarations and the `pub(crate) use` re-exports other modules call, with no code of its own. | relocation | +| [`service_launch/attach.rs`](../apps/rocm/src/service_launch/attach.rs) | The attached serve path (`--verbose`/`--foreground`): spawn the managed child and stream its log in the terminal until the user detaches or stops it. | relocation | +| [`service_launch/endpoint_auth.rs`](../apps/rocm/src/service_launch/endpoint_auth.rs) | Bind-host validation and the endpoint API key checks that gate a public bind (`validate_bind_host`, `resolve_endpoint_auth`), including on a respawn. | relocation | +| [`service_launch/helper_autostart.rs`](../apps/rocm/src/service_launch/helper_autostart.rs) | Starting the background automation helper when a watcher needs it, with the autostart claim that keeps concurrent callers from spawning two. | relocation | +| [`service_launch/launch_transaction.rs`](../apps/rocm/src/service_launch/launch_transaction.rs) | The locked launch decision: port allocation against live records and the OS, failed-launch cleanup, and whether a live service may answer a `serve` request. The cleanup terminates a spawned child through the same `rocm_core::terminate_recorded_pid_within` routine a stop uses, so on Windows its descendants are taken down too. A spawned child whose start token was not captured, on a host that records tokens (Linux, and Windows, which records the process creation time), is not signalled (`launch_cleanup_refusal`): it was gone before it could be captured and its pid may belong to another process. | relocation | +| [`service_launch/readiness.rs`](../apps/rocm/src/service_launch/readiness.rs) | Waiting on a launched or live managed service: the readiness budget, process liveness, how a wait ends, and the OOM fault-injection seam for end-to-end tests. | relocation | +| [`service_launch/spawn.rs`](../apps/rocm/src/service_launch/spawn.rs) | Spawning the detached managed engine child both serve paths share: process and stdio plumbing and the serialized spawn transaction (`spawn_managed_engine_child`). | relocation | +| [`service_launch/start.rs`](../apps/rocm/src/service_launch/start.rs) | The background launch path (`start_managed_service`) and the plain line-by-line rendering of its launch report. | relocation | +| [`service_launch/test_support.rs`](../apps/rocm/src/service_launch/test_support.rs) | Test fixtures shared by more than one `service_launch/` child. | flat | +| [`service_records.rs`](../apps/rocm/src/service_records.rs) | Removing a managed-service record and every file it owns, and the `rocm services prune` plan, render and apply steps with their age gate. `remove_managed_service_record_with` takes `--force` and the read of each recorded PID: `--force` removes a record only when none of its recorded processes is confirmed running, one could not be queried and a stop was requested, and reports which. | relocation | +| [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs) | `rocm services` (`services`) for `list`, `logs`, `stop`, `restart`, `remove` and `prune`, and the approval-gated stop and restart path. | relocation | +| [`services_text.rs`](../apps/rocm/src/services_text.rs) | Log rendering and the `rocm services` and `rocm logs` status, browser and `--follow` surfaces, managed-service record reads, and the `stop_server` answer shape. | relocation | +| [`setup_cmd.rs`](../apps/rocm/src/setup_cmd.rs) | `rocm setup` (`setup`): the `setup status` text and `setup reset`, which clears the saved first-time prompt state. | relocation | +| [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) | The CLI's one POSIX shell quoter (`shell_quote`, over `rocm-core`'s) and `has_terminal_control_character`, the predicate the chat tool-call guards refuse on. | flat | +| [`storage.rs`](../apps/rocm/src/storage.rs) | `rocm storage`: a read-only report of what runtimes, downloads and engine installs occupy on disk, and guarded removal of old installs and downloads. | domain | +| [`system_packages.rs`](../apps/rocm/src/system_packages.rs) | Host system-package installs for SDK and engine installs: the distro-aware OpenMPI, libatomic and libnuma plans, the consent decision, and running them without a shell. | domain | +| [`test_support.rs`](../apps/rocm/src/test_support.rs) | Test-only fixtures shared across the crate's module test suites, including the process-environment lock. | flat | +| [`therock.rs`](../apps/rocm/src/therock.rs) | TheRock SDK install orchestration (`install_sdk`, the wheel and tarball paths) and the helpers that name an install and its folders; parent of the `therock/` children. | domain | +| [`therock/consent.rs`](../apps/rocm/src/therock/consent.rs) | The consent gate for an install that would displace the active default runtime: what it would replace, and whether to proceed, prompt or refuse. | domain | +| [`therock/family.rs`](../apps/rocm/src/therock/family.rs) | Which TheRock package family a request targets (flag, environment, managed runtime or host GPU), refusing a GPU that has no ROCm build. | domain | +| [`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) | HTTP fetching for TheRock installs: the cached metadata GET (its signature check is opt-in until a production key is pinned), the streaming artifact download, and the tarball free-space preflight. | domain | +| [`therock/io.rs`](../apps/rocm/src/therock/io.rs) | Unique scratch directories for TheRock installs. | domain | +| [`therock/probe.rs`](../apps/rocm/src/therock/probe.rs) | Probing an installed runtime through its own interpreter: what `rocm_sdk` reports, which devices its torch opens, and the torch-pin helpers. | domain | +| [`therock/process.rs`](../apps/rocm/src/therock/process.rs) | Running and capturing child commands for TheRock installs, bounded waits, `--json`-aware progress lines, and unpacking the SDK tarball. | domain | +| [`therock/python.rs`](../apps/rocm/src/therock/python.rs) | The Python an install runs on: finding or provisioning an interpreter (`resolve_python_launcher`, `plan_python_launcher`), narrowing the requirement to an explicit `--python-version` or a runtime's recorded wheel tag, the wheel tags it accepts, and the runtime's virtual environment. | domain | +| [`therock/python_config_props.rs`](../apps/rocm/src/therock/python_config_props.rs) | Property tests for how the managed-Python step, a `config.json` writer, treats a `config.json` it cannot read (it never replaces one with defaults, and creates a missing one), and for the legacy rocm-dash tick migration that could produce one. Declared from [`therock/python.rs`](../apps/rocm/src/therock/python.rs). | flat | +| [`therock/resolve.rs`](../apps/rocm/src/therock/resolve.rs) | Module declarations and re-exports for artifact resolution under `therock/resolve/`; holds no logic. | domain | +| [`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs) | Resolving the SDK tarball a request installs from the catalog's index (`resolve_tarball_artifact`). | domain | +| [`therock/resolve/uv_access.rs`](../apps/rocm/src/therock/resolve/uv_access.rs) | Who may fetch `uv` while a wheel stack is resolved (`UvAccess`, `plan_version_resolution`), as a pure decision over layout, access and whether `uv` is present. | domain | +| [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs) | Resolving the wheel stack (`rocm`, `torch`, `torchvision`, `torchaudio`) and device payload a request installs (`resolve_pip_runtime`, `preview_pip_runtime`). | domain | +| [`therock/source.rs`](../apps/rocm/src/therock/source.rs) | Where an install reads from: channel, hosting layout and artifact bases (with the opt-in base override), plus the pinned version selector and the resolved family. | domain | +| [`therock/test_support.rs`](../apps/rocm/src/therock/test_support.rs) | Test-only fixtures shared by the `therock/` children's tests and the tests left in [`therock.rs`](../apps/rocm/src/therock.rs). | flat | +| [`therock/update.rs`](../apps/rocm/src/therock/update.rs) | Whether an installed runtime has something newer (`runtime_update_plan`, `runtime_update_check`), the update report and JSON, and the bounded startup check. | domain | +| [`therock/version.rs`](../apps/rocm/src/therock/version.rs) | Version grammar for TheRock runtimes: the strict install gate (`parse_version`), PEP 440 ordering, host-version parsing and the build-date helpers. | domain | +| [`therock/wheel_plan.rs`](../apps/rocm/src/therock/wheel_plan.rs) | The `sdk install` plan a wheel install prints, from one writer for a preview and a real install, resolved or not. | domain | +| [`therock_version_proptests.rs`](../apps/rocm/src/therock_version_proptests.rs) | Property tests for version ordering, update verdicts and update-source selection, declared from [`therock.rs`](../apps/rocm/src/therock.rs). | flat | +| [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs) | The chat assistant's tool-call policy: which `rocm` commands and bridge tools a model may request, which run at once, which need approval, and the validators that refuse unsafe calls. | flat | +| [`uninstall.rs`](../apps/rocm/src/uninstall.rs) | `rocm uninstall` (`uninstall`): what only uninstall does beyond removing files: undoing the installer's `PATH` change, removing the fish completion script the Linux installer recorded writing (`plan_completion_removals` takes only a regular `completions/rocm.fish` whose first line is the installer's marker naming this install folder, tied to [`install.sh`](../install.sh) by a test; `execute_plan` rechecks the file before removing it and reports a removal failure as a warning instead of stopping, for the `SHELL_COMPLETIONS_KIND` plan entries it adds), and deleting the running `rocm.exe` on Windows. | relocation | +| [`uninstall_plan.rs`](../apps/rocm/src/uninstall_plan.rs) | The uninstall plan shared with `rocm storage`: building it, rendering it for its audience, the `[y/N]` confirmation, and the `remove_path` primitive. | relocation | +| [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs) | `rocm update` (`update`): the read-only status report, whether to route into preview or apply, applying a runtime update, and the update-source pickers. | relocation | + +Boundaries: + +**Module layout** + +- Every module is a private `mod` in [`main.rs`](../apps/rocm/src/main.rs). Full-domain modules are typically reached by qualified path (`comfyui::run`); the dispatch-adjacent relocated clusters are reached unqualified through the `use crate::x::{...}` re-import block near the top of `main.rs`, which lists them. +- `engine_inventory` in [`main.rs`](../apps/rocm/src/main.rs) is the table of built-in engine ids. It, `status_for_readiness`, `device_policy_name` and `ROLLBACK_RECOVERY_HINT` stay at the crate root because modules across the crate use them. +- Most clap enums live in [`cli.rs`](../apps/rocm/src/cli.rs) and handlers in their domain or `*_cmd.rs` module; [`bootstrap.rs`](../apps/rocm/src/bootstrap.rs) and [`remote/mod.rs`](../apps/rocm/src/remote/mod.rs) are the exceptions that own their enum and dispatch fn. Declaration order in [`cli.rs`](../apps/rocm/src/cli.rs) sets the order of every nested `--help` list. + +**Chat and the freeform planner** + +- [`chat/turn.rs`](../apps/rocm/src/chat/turn.rs) is the top of the `chat/` call graph; `intent`, `mcp_bridge` and `summaries` never call back into it. +- `chat` calls the freeform planner, so [`freeform_planner.rs`](../apps/rocm/src/freeform_planner.rs), [`prompt_text.rs`](../apps/rocm/src/prompt_text.rs), [`rocm_argv.rs`](../apps/rocm/src/rocm_argv.rs) and [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs) must not import `chat`; [`chat_import_contract.rs`](../xtask/src/chat_import_contract.rs) enforces it. +- [`chat_cmd.rs`](../apps/rocm/src/chat_cmd.rs) stays outside [`chat.rs`](../apps/rocm/src/chat.rs) because it calls both [`chat.rs`](../apps/rocm/src/chat.rs) and [`dash.rs`](../apps/rocm/src/dash.rs), and [`dash.rs`](../apps/rocm/src/dash.rs) already calls [`chat.rs`](../apps/rocm/src/chat.rs). +- A freeform plan is built once and that value is executed, because a cloud planner provider may not be deterministic; `plan_freeform_request_with_context` does the same for the `natural_language_plan` tool. +- `validate_serve_command_safety` in [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs) holds the four rules a model-proposed `serve` must pass (no public bind, no CPU device, a loopback host, `--managed` without `--foreground`); the planner calls it and keeps no copy. + +**Runtimes** + +- [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) depends on neither [`therock.rs`](../apps/rocm/src/therock.rs) nor [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs), and [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs) and [`runtime_uninstall.rs`](../apps/rocm/src/runtime_uninstall.rs) do not depend on [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs), which re-exports their names. +- [`engine_install_env.rs`](../apps/rocm/src/engine_install_env.rs) imports [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs) and [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) directly: going through [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) would lead back to it via [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs). +- [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) does not import [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs). [`runtime_install_finalize/torch_alignment.rs`](../apps/rocm/src/runtime_install_finalize/torch_alignment.rs) is its child, not a sibling, because a sibling would form a cycle with the parent's device check. +- `select_single_ready_runtime` in [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs) is the one ready-runtime rule for the engine paths and ComfyUI; every runtime registration goes through `write_runtime_manifest` in [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs). +- The serde shapes of `InstalledRuntimeManifest` and `ActiveRuntimeMarker` are on-disk contracts. +- `PlannedPython` in [`therock/python.rs`](../apps/rocm/src/therock/python.rs) writes its `python_note:` text (`note` for an install preview, `update_note` for an update check) from the same decision the install branches on, so a note cannot name a version the install will not prepare. +- Whether an install root holds a payload is `rocm_core::install_root_has_payload`, and os-release is read only through `rocm_core::hardware_root::real_os_release`; a test in [`system_packages.rs`](../apps/rocm/src/system_packages.rs) fails when a source file of this binary calls `read_os_release(` or `identity_path_for_str` directly. + +**Services and uninstall** + +- `service_launch` does not import [`service_control.rs`](../apps/rocm/src/service_control.rs), which imports it (the Ctrl-C stop is passed into `run_attached_service`), and [`services_text.rs`](../apps/rocm/src/services_text.rs) does not call back into [`service_control.rs`](../apps/rocm/src/service_control.rs). +- [`background_helper.rs`](../apps/rocm/src/background_helper.rs) imports nothing from the service modules, so its helper note can be read without importing the spawner. +- [`uninstall.rs`](../apps/rocm/src/uninstall.rs) and [`uninstall_plan.rs`](../apps/rocm/src/uninstall_plan.rs) depend on each other; the plan half is separate because [`storage.rs`](../apps/rocm/src/storage.rs) shares it. +- [`service_launch/endpoint_auth.rs`](../apps/rocm/src/service_launch/endpoint_auth.rs)'s `ensure_public_bind_engine_supported` refuses a public bind with the managed Lemonade engine on Windows, because its endpoint API key cannot be enforced there; vLLM enforces its key on every platform, and a loopback bind needs none. + +**Shared sources and contracts** + +- [`service_hints.rs`](../apps/rocm/src/service_hints.rs) is the shared builder of the `rocm services stop|restart|remove --yes` hint text, so the callers that use it cannot drift apart. Those callers are [`remote/mod.rs`](../apps/rocm/src/remote/mod.rs), [`serve_port.rs`](../apps/rocm/src/serve_port.rs), [`serve_summary.rs`](../apps/rocm/src/serve_summary.rs), [`service_control.rs`](../apps/rocm/src/service_control.rs), [`service_records.rs`](../apps/rocm/src/service_records.rs), [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs), [`services_text.rs`](../apps/rocm/src/services_text.rs) and, under `service_launch/`, [`attach.rs`](../apps/rocm/src/service_launch/attach.rs) and [`spawn.rs`](../apps/rocm/src/service_launch/spawn.rs); the parent [`service_launch.rs`](../apps/rocm/src/service_launch.rs) does not call it. +- `DEFAULT_ENGINE_MARKER` in [`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs) is shared by both engine-inventory renderers and their legend line, so the rendered marker and the legend cannot drift apart. +- [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) is the CLI's quoter; `rocm-dash-tui` keeps a copy (`quote_display_arg`) because it may not depend on `rocm-core`, and a property test here holds the two equal. +- The local-model thinking rule [`providers/wire.rs`](../apps/rocm/src/providers/wire.rs) applies lives in `rocm-dash-core`'s [`chat_template.rs`](../crates/rocm-dash-core/src/chat_template.rs), because the dashboard's chat client must decide it identically. +- [`chat/turn.rs`](../apps/rocm/src/chat/turn.rs) compiles in [`SKILL.md`](../skills/rocm-cli-assistant/SKILL.md). +- `cargo xtask verify-pinned-keys` checks the metadata key in [`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) by path. +- `ROCDXG_PINNED_DIGESTS` in [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs) is the trust anchor of an unattended root install. +- `render_update_json` in [`therock/update.rs`](../apps/rocm/src/therock/update.rs) is the form the dashboard's update check parses. +- Saved property-test failures are keyed by the test's source file, so a moved property test takes its file in `apps/rocm/proptest-regressions/` along (see [Property tests](testing.md#property-tests)). ### `apps/rocmd` — background daemon -Modularized (ROCMAI-83, Phase 5 of ROCMAI-27's sequencing): - -- [`cli.rs`](../apps/rocmd/src/cli.rs) — the `Cli`/`Command` clap definitions, the bridge-snapshot diagnostic printer, the pretty-JSON printer for the subcommands that print a result (`print_json`), and the top-level dispatch in `run_cli`/`run_bin_cli`/`run_from_args`. -- [`anthropic_proxy.rs`](../apps/rocmd/src/anthropic_proxy.rs) — the Anthropic-compatible `/v1/messages` front for a served model: `spawn_alongside_engine` waits for the engine to list its model, then binds a translation proxy, even for an engine that has its own `/v1/messages` route because that route only accepts the served model's name (`anthropic_to_openai`, `openai_to_anthropic`, `StreamTranslator` for `stream: true` requests, with tool use translated both ways for non-streaming ones, an axum router over `/v1/messages` and `/v1/models`) on a port of its own, publishing the result in the engine state file for the service record to adopt. It is a library module, not a daemon task: `rocm`'s `run_builtin_engine_serve_http` in [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs) starts it on a thread of the process that owns the engine, so it lives and dies with the service. -- [`artifact_prefetch.rs`](../apps/rocmd/src/artifact_prefetch.rs) — the `prefetch_artifact` sandbox tool's artifact download: `prefetch_artifact_value_with_policy` decides from the recipe artifact's source policy and the approved `SandboxToolPolicy` whether the artifact may be fetched at all, and answers `source_policy_required`, `cached` or `blocked` without touching the network when it may not (no download approval, a cache marker already present, a manual-only or unsupported source policy, a gated or non-HTTP(S) source, a Hugging Face token that would leave HTTPS or a Hugging Face host, a missing sha256 or size, a size over the approved byte limit). Otherwise it streams the download through [`download.rs`](../crates/rocm-core/src/download.rs)'s `download_file_streaming` under `ARTIFACT_PREFETCH_TIMEOUT`, which enforces the recipe's size and sha256, and records the cache marker with [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs)'s `write_file_atomically`. It also holds the host-scoped URL checks (`is_huggingface_url`, `http_url_host`). [`sandbox.rs`](../apps/rocmd/src/sandbox.rs) is its only caller and this module does not import it back; it takes `SandboxToolArg` and `SandboxToolPolicy` from [`sandbox_tool.rs`](../apps/rocmd/src/sandbox_tool.rs). Its own `mod tests` holds the prefetch policy and download tests, the host-scoping test and the one-shot local HTTP server they download from, reaching `temp_app_paths` through `crate::test_support`. -- [`common.rs`](../apps/rocmd/src/common.rs) — helpers the other modules call into: the read-only `rocm update` message, the `rocm`-subprocess capture wrapper (`run_rocm_capture_for_paths`) the sandbox and MCP clusters both call (it only chooses the child's `ROCM_CLI_*_DIR` environment; `CommandCapture` and the spawn itself live in [`command_capture.rs`](../crates/rocm-core/src/command_capture.rs), shared with `rocm`'s chat tool bridge, and the bounded-execution half in [`process/bounded.rs`](../crates/rocm-core/src/process/bounded.rs)), and small arg/JSON-payload utilities (`payload_string`, for example, is read by the [`watchers/cache_warm.rs`](../apps/rocmd/src/watchers/cache_warm.rs), [`watchers/driver_upgrade.rs`](../apps/rocmd/src/watchers/driver_upgrade.rs) and [`watchers/gpu_thermal_protect.rs`](../apps/rocmd/src/watchers/gpu_thermal_protect.rs) handlers and by [`webhook.rs`](../apps/rocmd/src/webhook.rs)). -- [`daemon.rs`](../apps/rocmd/src/daemon.rs) — the foreground `rocmd run` loop (`run_daemon`: evaluate the watchers each tick, dispatch local webhook events, write the runtime state, stop on a signal; with no watcher enabled it exits by itself, deciding that under the autostart lock and publishing "stopped" and clearing its spawn claim before releasing it — `record_daemon_stop`, `release_own_autostart_claim`) and `rocmd status` (`print_status`), with the watcher tick interval, which `LoopHooks` makes injectable for tests. It uses [`watchers.rs`](../apps/rocmd/src/watchers.rs), [`webhook.rs`](../apps/rocmd/src/webhook.rs) and [`persistence.rs`](../apps/rocmd/src/persistence.rs); [`cli.rs`](../apps/rocmd/src/cli.rs) calls it. -- [`daemon_host.rs`](../apps/rocmd/src/daemon_host.rs) — which binary a daemon spawn runs. The daemon runs as the `rocmd` binary or embedded in `rocm` (`rocm daemon`, which enters through `run_from_args` and marks the process), and `supervise` is a command of `rocmd` alone. The hidden engine commands (`__engine-serve-http`, `__engine-stdio`) are `rocm`'s alone. `DaemonHost` holds the one executable path every choice and sibling lookup is made from (`rocm_core::sibling_binary_path_from`). `rocmd_binary` returns the current executable when the daemon is `rocmd` and the `rocmd` installed beside `rocm` when it is embedded; `rocm_binary` is the mirror, the current executable when embedded and the `rocm` installed beside `rocmd` when not. Each names what was missing when there is none. `detect` returns the real host. Under test it returns the test binary for both commands and looks for no sibling, and the two stand-in hosts (`test_binary_standing_in_for_rocm` and `test_binary_standing_in_for_rocmd`) name only the binary they stand in for and fail when asked for the other, so none of them can run a `rocm` or `rocmd` built beside the test binary; a test that needs another binary passes the code it exercises a host of its own. A leaf: it imports no other crate module. -- [`engine_ipc.rs`](../apps/rocmd/src/engine_ipc.rs) — talking to an engine and guarding its endpoint key: `engine_request` (the stdio request to an engine process, run through the same client `rocm` uses, [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs); `rocmd` chooses what to run, `__engine-stdio ` on the `rocm` binary that `DaemonHost::rocm_binary` finds, since `__engine-stdio` is `rocm`'s command, and what to ask of the client: its own app paths, the service's endpoint key file when it holds a usable key, and stderr kept for the error rather than forwarded), the healthcheck call and its readiness and recoverability checks, and the endpoint-key helpers `apply_endpoint_key_env` and `ensure_public_service_has_endpoint_key`. It uses no other module of the crate but [`daemon_host.rs`](../apps/rocmd/src/daemon_host.rs); [`service.rs`](../apps/rocmd/src/service.rs), [`supervise.rs`](../apps/rocmd/src/supervise.rs) and [`watchers/server_recover.rs`](../apps/rocmd/src/watchers/server_recover.rs) call it. -- [`host_snapshot.rs`](../apps/rocmd/src/host_snapshot.rs) — the host snapshot: `build_bridge_snapshot` (the bridge snapshot printed by `rocmd bridge-snapshot` and returned by the `bridge_snapshot` MCP tool, assembled from the examine summary, the GPU snapshot, the automation runtime state and recent events, the engine inventory and the managed services), the amd-smi GPU snapshot (`gather_gpu_snapshot_for_config`, which honours the telemetry setting, over time-bounded amd-smi probes) and `bridge_engine_inventory`. It uses only [`persistence.rs`](../apps/rocmd/src/persistence.rs); [`cli.rs`](../apps/rocmd/src/cli.rs), [`mcp.rs`](../apps/rocmd/src/mcp.rs) and [`watchers.rs`](../apps/rocmd/src/watchers.rs) call it. -- [`main.rs`](../apps/rocmd/src/main.rs) — the `rocmd` binary's entry point: a synchronous `main` that calls `rocmd::run_bin_cli()`, which builds the Tokio runtime itself (`run_bin_cli` is `#[tokio::main]`) and dispatches the parsed `Cli`, so the binary holds no logic of its own. -- [`mcp.rs`](../apps/rocmd/src/mcp.rs) — the MCP stdio server, tool schema table, tool dispatch, and the result-shaping helpers behind the MCP tools (the `rocm` subprocess itself is spawned through [`common.rs`](../apps/rocmd/src/common.rs), via `run_rocm_capture` here). The argument handling the dispatch calls is in [`mcp_argv.rs`](../apps/rocmd/src/mcp_argv.rs). -- [`mcp_argv.rs`](../apps/rocmd/src/mcp_argv.rs) — the argument handling for the MCP tools that spawn `rocm`: `normalized_rocm_command_args` and the read-only allowlist `ensure_rocm_command_is_read_only` behind the `rocm_command` tool, and the argv builders for `install_sdk`, `install_engine`, `launch_server` and `watcher_enable` (`build_install_sdk_args`, `build_install_engine_args`, `build_launch_server_args`, `build_watcher_enable_args`, with the public-bind and system-prefix acknowledgement checks they apply). Functions over the tool's JSON arguments: it uses no other module of the crate, spawns nothing and writes nothing, and [`mcp.rs`](../apps/rocmd/src/mcp.rs) is its only caller. Its own `mod tests` holds the allowlist and argv-builder tests. -- [`persistence.rs`](../apps/rocmd/src/persistence.rs) — `record_event`/`load_managed_services`/`load_service_record`, the automation-event/audit-log and managed-service-registry I/O shared across the daemon's sandbox, MCP, service-lifecycle, and watcher code. -- [`sandbox.rs`](../apps/rocmd/src/sandbox.rs) — bubblewrap/native sandbox execution, the sandbox-tool dispatch (`run_sandbox_tool`), and the sandbox-tool result shaping for `check_updates`/`driver_plan`/`stop_server`. For `prefetch_artifact` it resolves the artifact reference against the model recipe registry and hands the artifact to [`artifact_prefetch.rs`](../apps/rocmd/src/artifact_prefetch.rs), which does not import it back. The tests that drive that tool through `run_sandbox_tool` stay in this module's `mod tests`: a missing and an unknown artifact reference, and one that resolves a reference through a signed recipe index built in the test and checks both the recipe's model id and that the caller's policy reaches the download decision. -- [`sandbox_tool.rs`](../apps/rocmd/src/sandbox_tool.rs) — the sandbox-tool vocabulary: the `SandboxToolArg` value enum naming each sandbox tool, and `SandboxToolPolicy`, the artifact-download policy built from the `--allow-*` flags (including the Hugging Face token read from the environment when authenticated downloads are allowed). It uses no other module of the crate, so modules that need the vocabulary do not import [`cli.rs`](../apps/rocmd/src/cli.rs). -- [`service.rs`](../apps/rocmd/src/service.rs) — managed-service stop: the engine `Stop`, the manifest and endpoint-key writes, and the stop report (`stop_managed_service`, `stop_report_confirmed`) that the sandbox and MCP tools read. The termination of the recorded processes is the routine shared with `rocm services stop`, in [`proc_lifecycle.rs`](../crates/rocm-core/src/proc_lifecycle.rs); this module passes it `terminate_recorded_pid` and keeps no copy of it or of its grace constant. -- [`supervise.rs`](../apps/rocmd/src/supervise.rs) — launching and re-launching a managed service's supervisor: `supervise_service` (the `rocmd supervise` entry point: launch the engine child, record its identity, wait for readiness, record the exit) with the serve-log startup-phase polling and readiness wait it uses (its engine child runs on the `rocm` binary that `DaemonHost::rocm_binary` finds, before the first write, since `rocmd` has no engine commands, and it polls readiness through the same host), and `restart_managed_service` (the recovery respawn: re-launch `rocmd supervise` detached for a service and record the new supervisor; the binary that runs `supervise` comes from [`daemon_host.rs`](../apps/rocmd/src/daemon_host.rs), and a restart that cannot find it fails before it writes the record). Writes after a supervisor's first go through the private `update_supervised_record`, which re-reads the record and leaves a stop marker or another supervisor's record alone. Its production code uses only [`common.rs`](../apps/rocmd/src/common.rs), [`daemon_host.rs`](../apps/rocmd/src/daemon_host.rs), [`engine_ipc.rs`](../apps/rocmd/src/engine_ipc.rs), [`persistence.rs`](../apps/rocmd/src/persistence.rs) and `stop_requested` from [`watchers.rs`](../apps/rocmd/src/watchers.rs). [`cli.rs`](../apps/rocmd/src/cli.rs) calls `supervise_service`; [`watchers/server_recover.rs`](../apps/rocmd/src/watchers/server_recover.rs) (the server-recover handler) and [`sandbox.rs`](../apps/rocmd/src/sandbox.rs) (the `restart_server` tool) call `restart_managed_service`. -- [`watchers.rs`](../apps/rocmd/src/watchers.rs) — the module root of the built-in watchers: the registry (`reconcile_watcher_snapshots`) and the event collector and dispatcher (`evaluate_watchers`, `collect_automation_events_with_gpu_snapshot`, which takes the GPU snapshot as a closure so tests can inject one, and `evaluate_watchers_for_events`), which route each event to its watcher's handler. `find_recoverable_service` and `stop_requested` are re-exported from here because [`supervise.rs`](../apps/rocmd/src/supervise.rs)'s and [`service.rs`](../apps/rocmd/src/service.rs)'s tests reach them by the `crate::watchers::` path. Each watcher's handler lives in the child below that carries its name, together with the policy they share, and a child reaches only [`policy.rs`](../apps/rocmd/src/watchers/policy.rs) and, for the thermal-protect watcher, [`gpu_metrics.rs`](../apps/rocmd/src/watchers/gpu_metrics.rs) among the others. - - [`watchers/policy.rs`](../apps/rocmd/src/watchers/policy.rs) — what a watcher does in each mode and the proposals it queues: `WatcherPolicyAction` and `watcher_policy_action` (observe, queue a proposal or run contained, chosen by the watcher mode), `queue_proposal` and `queue_proposal_with_arguments` with the action-to-tool and action-to-arguments tables behind them, and `pending_proposal_exists`, the check the thermal-protect and server-recover handlers use so they do not queue a duplicate of a proposal that is still pending. It uses no other watcher module. - - [`watchers/server_recover.rs`](../apps/rocmd/src/watchers/server_recover.rs) — the `server-recover` watcher: finding a managed service that needs recovery (`find_recoverable_service`, from a failed or stale manifest, an unreachable endpoint or a failing engine healthcheck, skipping a service whose stop request still stands via `stop_requested`), the recovery event kinds and plain-language reasons, the backoff that spaces recovery attempts (`server_recover_due`), and the handler that restarts the service or queues a restart proposal by watcher mode. It uses [`policy.rs`](../apps/rocmd/src/watchers/policy.rs), [`engine_ipc.rs`](../apps/rocmd/src/engine_ipc.rs), [`persistence.rs`](../apps/rocmd/src/persistence.rs) and [`supervise.rs`](../apps/rocmd/src/supervise.rs)'s `restart_managed_service`. - - [`watchers/gpu_metrics.rs`](../apps/rocmd/src/watchers/gpu_metrics.rs) — the `gpu-metrics` watcher and the GPU readings it works from: the telemetry-event handler (`handle_gpu_metrics_event`, which records telemetry and takes no action), the interval check (`gpu_metrics_due`), the one-line snapshot summary, and the reading of amd-smi monitor entries into thermal-pressure and memory-pressure events (`gpu_pressure_events`, `gpu_pressure_event`) with the thresholds they use. It uses [`persistence.rs`](../apps/rocmd/src/persistence.rs) and no other watcher module, and [`gpu_thermal_protect.rs`](../apps/rocmd/src/watchers/gpu_thermal_protect.rs) reads its interval and thresholds. - - [`watchers/gpu_thermal_protect.rs`](../apps/rocmd/src/watchers/gpu_thermal_protect.rs) — the `gpu-thermal-protect` watcher: the pressure-event handler (`handle_gpu_thermal_protect_event`), which records the event and, outside observe mode, picks the one running managed service as the target and queues a reviewed stop request unless one is already pending, and the interval check (`gpu_thermal_protect_due`). It uses [`gpu_metrics.rs`](../apps/rocmd/src/watchers/gpu_metrics.rs) for the interval and thresholds, [`policy.rs`](../apps/rocmd/src/watchers/policy.rs), [`common.rs`](../apps/rocmd/src/common.rs) and [`persistence.rs`](../apps/rocmd/src/persistence.rs). - - [`watchers/therock_update.rs`](../apps/rocmd/src/watchers/therock_update.rs) — the `therock-update` watcher: the schedule check (`therock_update_due`, every six hours) and the handler, which in observe mode records a reminder, in propose mode also queues an update-check proposal, and in contained mode runs the read-only `check_updates` sandbox tool and records a notification when an update or repair is available, never applying one. It uses [`policy.rs`](../apps/rocmd/src/watchers/policy.rs), [`sandbox.rs`](../apps/rocmd/src/sandbox.rs), [`sandbox_tool.rs`](../apps/rocmd/src/sandbox_tool.rs), [`common.rs`](../apps/rocmd/src/common.rs) and [`persistence.rs`](../apps/rocmd/src/persistence.rs). - - [`watchers/driver_upgrade.rs`](../apps/rocmd/src/watchers/driver_upgrade.rs) — the `driver-upgrade` watcher: the handler for an available driver update, which ignores non-driver components, records the signal in observe mode, queues a reviewed driver-plan proposal in propose mode, and in contained mode runs the restricted read-only `driver_plan` sandbox tool, executing no driver command. It uses [`policy.rs`](../apps/rocmd/src/watchers/policy.rs), [`sandbox.rs`](../apps/rocmd/src/sandbox.rs), [`sandbox_tool.rs`](../apps/rocmd/src/sandbox_tool.rs), [`common.rs`](../apps/rocmd/src/common.rs) and [`persistence.rs`](../apps/rocmd/src/persistence.rs); its tests also use [`webhook.rs`](../apps/rocmd/src/webhook.rs)'s `local_webhook_event_from_request`. - - [`watchers/cache_warm.rs`](../apps/rocmd/src/watchers/cache_warm.rs) — the `cache-warm` watcher: the handler for a request to warm a recipe artifact. It checks the artifact against the model registry (the lookup is injectable for tests), records an unknown or unverifiable artifact without queueing anything, and otherwise records the request and, outside observe mode, queues a reviewed prefetch proposal; contained mode does too, because an artifact download needs explicit source-policy approval. It uses [`policy.rs`](../apps/rocmd/src/watchers/policy.rs), [`common.rs`](../apps/rocmd/src/common.rs) and [`persistence.rs`](../apps/rocmd/src/persistence.rs); its tests also use [`webhook.rs`](../apps/rocmd/src/webhook.rs)'s `local_webhook_event_from_request`. -- [`webhook.rs`](../apps/rocmd/src/webhook.rs) — the local webhook source: its axum routes, request validation, and watcher-kind allow-list. - -[`lib.rs`](../apps/rocmd/src/lib.rs) itself is now top-level glue: module declarations and the three externally-consumed entry points re-exported from [`cli.rs`](../apps/rocmd/src/cli.rs) (`run_bin_cli`/`run_from_args`, plus `parse_args`, which `apps/rocm`'s test-only [`advised_commands.rs`](../apps/rocm/src/advised_commands.rs) uses to check advised `rocmd` commands). +The `rocmd` binary and the daemon library `rocm daemon` embeds: the watcher loop and its built-in watchers, the managed-service supervisor, the MCP stdio server and its sandboxed tools, and the local webhook source. Its command tree lives in [`cli.rs`](../apps/rocmd/src/cli.rs). + +| File | Responsibility | Class | +| --- | --- | --- | +| [`lib.rs`](../apps/rocmd/src/lib.rs) | Crate root: module declarations and the entry points re-exported from [`cli.rs`](../apps/rocmd/src/cli.rs) (`run_bin_cli`, `run_from_args`, `parse_args`). | flat | +| [`main.rs`](../apps/rocmd/src/main.rs) | The `rocmd` binary's entry point: a synchronous `main` that calls `rocmd::run_bin_cli()`, which builds the Tokio runtime itself; it holds no logic of its own. | flat | +| [`anthropic_proxy.rs`](../apps/rocmd/src/anthropic_proxy.rs) | The Anthropic-compatible `/v1/messages` front for a served model: a translation proxy to the engine's OpenAI API, translating streaming requests and, for non-streaming ones, tool use both ways, on a port of its own, published in the engine state file (`spawn_alongside_engine`). | flat | +| [`artifact_prefetch.rs`](../apps/rocmd/src/artifact_prefetch.rs) | The `prefetch_artifact` sandbox tool's download: whether a recipe artifact may be fetched under the approved source policy (answering `source_policy_required`, `cached` or `blocked` without touching the network when it may not), the host-scoped Hugging Face URL checks that gate a token, and the streamed, sha256-verified download that records the cache marker. | flat | +| [`cli.rs`](../apps/rocmd/src/cli.rs) | The `Cli`/`Command` clap definitions, the bridge-snapshot and pretty-JSON printers, and the top-level dispatch (`run_cli`, `run_bin_cli`, `run_from_args`). | flat | +| [`common.rs`](../apps/rocmd/src/common.rs) | Small shared helpers: the read-only `rocm update` message, the `rocm`-subprocess capture wrapper (`run_rocm_capture_for_paths`), and argument and JSON-payload utilities such as `payload_string`. | flat | +| [`daemon.rs`](../apps/rocmd/src/daemon.rs) | The foreground `rocmd run` loop (`run_daemon`: evaluate watchers each tick, dispatch webhook events, write runtime state, stop on a signal or when no watcher is enabled) and `rocmd status`. | flat | +| [`daemon_host.rs`](../apps/rocmd/src/daemon_host.rs) | `DaemonHost`: which binary a daemon spawn runs, depending on whether the daemon is `rocmd` itself or embedded in `rocm` (`rocmd_binary`, `rocm_binary`). | flat | +| [`engine_ipc.rs`](../apps/rocmd/src/engine_ipc.rs) | Talking to an engine and guarding its endpoint key: the stdio request (`engine_request`), the healthcheck and its readiness checks, and the endpoint-key helpers. `engine_request` runs through the same client `rocm` uses, [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs): `rocmd` chooses what to run (`__engine-stdio ` on the `rocm` binary that `DaemonHost::rocm_binary` finds, since `__engine-stdio` is `rocm`'s command) and what to ask of the client: its own app paths, the service's endpoint key file when it holds a usable key, and stderr kept for the error rather than forwarded. | flat | +| [`host_snapshot.rs`](../apps/rocmd/src/host_snapshot.rs) | The host snapshot behind `rocmd bridge-snapshot` and the `bridge_snapshot` MCP tool (`build_bridge_snapshot`), the time-bounded amd-smi GPU snapshot, and the engine inventory. | flat | +| [`mcp.rs`](../apps/rocmd/src/mcp.rs) | The MCP stdio server: the tool schema table, tool dispatch, and the shaping of each tool's result. | flat | +| [`mcp_argv.rs`](../apps/rocmd/src/mcp_argv.rs) | Argument handling for the MCP tools that spawn `rocm`, spawning and writing nothing itself: the read-only allowlist for `rocm_command` and the argv builders with their acknowledgement checks. | flat | +| [`persistence.rs`](../apps/rocmd/src/persistence.rs) | Automation event and audit-log writes and managed-service registry reads (`record_event`, `load_managed_services`, `load_service_record`). | flat | +| [`sandbox.rs`](../apps/rocmd/src/sandbox.rs) | Running a sandbox tool under bubblewrap or natively, the sandbox-tool dispatch (`run_sandbox_tool`) and the result shaping for `check_updates`, `driver_plan` and `stop_server`. For `prefetch_artifact` it resolves the artifact reference against the model recipe registry and hands the artifact to [`artifact_prefetch.rs`](../apps/rocmd/src/artifact_prefetch.rs). | flat | +| [`sandbox_tool.rs`](../apps/rocmd/src/sandbox_tool.rs) | The sandbox-tool vocabulary: the `SandboxToolArg` enum and `SandboxToolPolicy`, the artifact-download policy built from the `--allow-*` flags. | flat | +| [`service.rs`](../apps/rocmd/src/service.rs) | Stopping a managed service: the engine `Stop`, the manifest and endpoint-key writes, and the stop report (`stop_managed_service`, `stop_report_confirmed`). The termination of the recorded processes is the routine shared with `rocm services stop`, in [`proc_lifecycle.rs`](../crates/rocm-core/src/proc_lifecycle.rs); this module passes it `terminate_recorded_pid` and keeps no copy of it or of its grace constant. | flat | +| [`supervise.rs`](../apps/rocmd/src/supervise.rs) | The `rocmd supervise` entry point (`supervise_service`: launch the engine child, record it, wait for readiness, record the exit) and the recovery respawn (`restart_managed_service`). | flat | +| [`test_support.rs`](../apps/rocmd/src/test_support.rs) | Test-only fixtures shared by the crate's module tests, including the workspace-local scratch `AppPaths` and `RecipeIndexEnv`, the guard that serialises tests over the model recipe registry environment variables. | flat | +| [`watchers.rs`](../apps/rocmd/src/watchers.rs) | Root of the built-in watchers: the registry (`reconcile_watcher_snapshots`) and the event collector and dispatcher (`evaluate_watchers`) that route each event to its watcher's handler. | flat | +| [`watchers/cache_warm.rs`](../apps/rocmd/src/watchers/cache_warm.rs) | The `cache-warm` watcher: checks a requested recipe artifact against the model registry and queues a reviewed prefetch proposal for a known one. | flat | +| [`watchers/driver_upgrade.rs`](../apps/rocmd/src/watchers/driver_upgrade.rs) | The `driver-upgrade` watcher: turns an available driver update into a reviewed driver-plan proposal, or a read-only plan in contained mode. | flat | +| [`watchers/gpu_metrics.rs`](../apps/rocmd/src/watchers/gpu_metrics.rs) | The `gpu-metrics` watcher: records GPU telemetry and reads amd-smi monitor entries into thermal- and memory-pressure events, with the interval and thresholds they use. | flat | +| [`watchers/gpu_thermal_protect.rs`](../apps/rocmd/src/watchers/gpu_thermal_protect.rs) | The `gpu-thermal-protect` watcher: on GPU pressure, picks the one running managed service and queues a reviewed stop request unless one is pending. | flat | +| [`watchers/policy.rs`](../apps/rocmd/src/watchers/policy.rs) | What a watcher does in each mode (`watcher_policy_action`: observe, propose or run contained) and the proposals it queues (`queue_proposal`, `pending_proposal_exists`). | flat | +| [`watchers/server_recover.rs`](../apps/rocmd/src/watchers/server_recover.rs) | The `server-recover` watcher: finds a managed service that needs recovery (`find_recoverable_service`), spaces attempts with a backoff, and restarts it or queues a restart proposal. | flat | +| [`watchers/therock_update.rs`](../apps/rocmd/src/watchers/therock_update.rs) | The `therock-update` watcher: the six-hourly update check, with a reminder, a proposal or a read-only contained run depending on mode. | flat | +| [`webhook.rs`](../apps/rocmd/src/webhook.rs) | The local webhook source: its axum routes, request validation and watcher-kind allow-list. | flat | + +Boundaries: + +- **Which binary runs what.** The daemon runs as `rocmd` or embedded in `rocm` (`rocm daemon`); `supervise` is `rocmd`'s alone and the hidden engine commands are `rocm`'s alone. A spawn of either takes its binary from [`daemon_host.rs`](../apps/rocmd/src/daemon_host.rs)'s `DaemonHost`, the one executable path these choices are made from. +- **The Anthropic proxy is not a daemon task.** [`anthropic_proxy.rs`](../apps/rocmd/src/anthropic_proxy.rs) is started by `rocm`'s `run_builtin_engine_serve_http` in [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs), on a thread of the process that owns the engine, so it lives and dies with the service. +- **Shared subprocess capture.** [`common.rs`](../apps/rocmd/src/common.rs) only chooses the child's `ROCM_CLI_*_DIR` environment; the capture and spawn are [`command_capture.rs`](../crates/rocm-core/src/command_capture.rs) in `rocm-core`, shared with `rocm`'s chat tool bridge. +- **Supervised-record writes.** After a supervisor's first write, every write to its record goes through `update_supervised_record`, which is `pub(crate)` in [`supervise.rs`](../apps/rocmd/src/supervise.rs); [`watchers/server_recover.rs`](../apps/rocmd/src/watchers/server_recover.rs) calls it directly to stamp `last_restart_unix_ms` after a failed restart. +- **Watcher re-exports.** [`watchers.rs`](../apps/rocmd/src/watchers.rs) re-exports `stop_requested` and `find_recoverable_service` from [`server_recover.rs`](../apps/rocmd/src/watchers/server_recover.rs). [`supervise.rs`](../apps/rocmd/src/supervise.rs) imports `stop_requested` in production code, and `find_recoverable_service` is called by `watchers.rs` itself and by `supervise.rs`'s tests; so neither re-export is test-only. +- **Deliberate re-export.** [`lib.rs`](../apps/rocmd/src/lib.rs) exports `parse_args` because `apps/rocm`'s test-only [`advised_commands.rs`](../apps/rocm/src/advised_commands.rs) checks advised `rocmd` commands with it. +- **Layering.** + - [`sandbox_tool.rs`](../apps/rocmd/src/sandbox_tool.rs) imports no other module of the crate, so modules that need the sandbox-tool vocabulary do not import [`cli.rs`](../apps/rocmd/src/cli.rs). + - [`artifact_prefetch.rs`](../apps/rocmd/src/artifact_prefetch.rs) is called only by [`sandbox.rs`](../apps/rocmd/src/sandbox.rs) and does not import it back; it takes `SandboxToolArg` and `SandboxToolPolicy` from [`sandbox_tool.rs`](../apps/rocmd/src/sandbox_tool.rs). + - A watcher child imports no sibling watcher module except [`watchers/policy.rs`](../apps/rocmd/src/watchers/policy.rs), and the thermal-protect watcher, which reads [`watchers/gpu_metrics.rs`](../apps/rocmd/src/watchers/gpu_metrics.rs)'s interval and thresholds. + - `pending_proposal_exists` in [`watchers/policy.rs`](../apps/rocmd/src/watchers/policy.rs) is the one duplicate-proposal check the thermal-protect and server-recover handlers share. +- **Three watchers stay reviewed or read-only in contained mode.** + - The `therock-update` watcher runs only the read-only `check_updates` sandbox tool and never applies an update. + - The `driver-upgrade` watcher runs only the restricted read-only `driver_plan` tool and executes no driver command. + - The `cache-warm` watcher queues a reviewed proposal even in contained mode, because an artifact download needs explicit source-policy approval. ### `crates/rocm-core` — core library -Already-extracted subsystem modules, following the same full-domain-extraction pattern (and several further siblings beyond these): - -- [`anthropic_endpoint.rs`](../crates/rocm-core/src/anthropic_endpoint.rs) — (ROCMAI-597) the Anthropic-compatible `/v1/messages` surface of a managed service: `AnthropicEndpointMode` (`rocm` fronts the OpenAI-speaking engine), and the readiness check and wait on the published endpoint. -- [`amd_smi.rs`](../crates/rocm-core/src/amd_smi.rs) — (ROCMAI-723) locating the `amd-smi` binary: `resolve_amd_smi_binary` (re-exported at the crate root) prefers the newest managed ROCm SDK runtime recorded in the registry, then the home-directory venv and legacy locations, then the bare name for a `PATH` lookup. It only reads the registry records [`managed_runtime.rs`](../crates/rocm-core/src/managed_runtime.rs) exposes and [`runtime.rs`](../crates/rocm-core/src/runtime.rs)'s data/home directory lookups. As of EAI-8457 it also owns the *launch*: `amd_smi_json` (also re-exported at the crate root) is the one supported way for a synchronous caller to run `amd-smi`, because it is the only place the mandatory `/dev/kfd` pre-flight runs (`KFD_DEVICE`, `preflight_kfd_device`, `kfd_readable`/`kfd_readable_with`, and the thread-bounded, budget-capped `device_readable`/`device_readable_within_budget` probe behind `KFD_OPEN_TIMEOUT`). A device that cannot be opened declines the spawn rather than letting `amd-smi` park in uninterruptible sleep, where no timeout can reach it. The spawn itself still goes through [`process.rs`](../crates/rocm-core/src/process.rs)'s `run_with_timeout`, and the non-zero-exit quote is bounded with that module's `MAX_QUOTED_OUTPUT_CHARS` rather than a second copy of the constant. Callers: [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs)'s `gpu_vram_usage_amd_smi`/`detect_gpu_count`, both through that module's own `amd_smi_probe_json` (which logs the discarded decline at `info`, since the default filter is `warn,rocm=info` and a decline on a healthy host is otherwise indistinguishable from "no GPU"), and `rocmd`'s [`host_snapshot.rs`](../apps/rocmd/src/host_snapshot.rs)`::capture_amd_smi_json`. That the list stays complete is enforced rather than asserted: [`amd_smi_launch_contract.rs`](../xtask/src/amd_smi_launch_contract.rs) is a static contract test failing any file outside its two-entry allowlist that calls `resolve_amd_smi_binary`, so a new probe cannot be spawned directly without a reviewed exemption. The `rocm dash` collectors keep their own pre-flight *decision* (`preflight_passes`), since they gate an async launch, but share this module's bounded device probe through the `pub fn device_readable_bounded` re-export — an allowlisted `rocm-dash-collectors -> rocm-core` edge recorded in [`crate_edges.rs`](../xtask/src/crate_edges.rs), so the one launch site outside this chokepoint cannot drift away from the bound and the budget. -- [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs) — the shared atomic file writer behind `rocm`, `rocmd`, this crate's own atomic replaces ([`config.rs`](../crates/rocm-core/src/config.rs)'s `RocmCliConfig::save`, the automation event and proposal stores in [`automation.rs`](../crates/rocm-core/src/automation.rs), the JSONL stores in [`jsonl_store.rs`](../crates/rocm-core/src/jsonl_store.rs), the service-record manifests in [`service_record.rs`](../crates/rocm-core/src/service_record.rs)) and the Lemonade engine's rewrite of `backend_versions.json` in [`install.rs`](../engines/lemonade/src/install.rs) (unique exclusive temp file, then rename, which on Windows falls back to `ReplaceFileW` only if the rename fails); durable as well as atomic: the temp file is flushed before it is published and, on Unix, the directory after it; on Unix it keeps the replaced file's permission bits, and `write_file_atomically` replaces a symlink's target rather than the link. Other hand-rolled temp-then-rename writers remain outside it, for example [`remote/session.rs`](../apps/rocm/src/remote/session.rs)'s session-file write, [`uninstall.rs`](../apps/rocm/src/uninstall.rs)'s profile replacement and `write_atomically` in [`comfyui/source_swap.rs`](../apps/rocm/src/comfyui/source_swap.rs). A new atomic write should call this module rather than add another copy. -- [`automation.rs`](../crates/rocm-core/src/automation.rs) — (ROCMAI-151) automation-daemon runtime state and its on-disk event/proposal/audit records, and the policy applied to each store (which are rotated, and the proposal compaction) — see the module's own doc comment for what it owns. The generic JSONL machinery under those stores lives in [`jsonl_store.rs`](../crates/rocm-core/src/jsonl_store.rs). The dependency runs one way: this module reads `WatcherMode` from [`config.rs`](../crates/rocm-core/src/config.rs), and [`config.rs`](../crates/rocm-core/src/config.rs) imports nothing from here, because the built-in watcher catalog (whose entries carry a default `WatcherMode`, and which `RocmCliConfig::watcher_enabled` and `effective_watcher_mode` take as an argument) lives in [`config.rs`](../crates/rocm-core/src/config.rs) beside `WatcherMode`. -- [`binary_paths.rs`](../crates/rocm-core/src/binary_paths.rs) — (ROCMAI-151, Phase 7d) locating `rocm-engine-` siblings, and the CLI binary itself (a sibling `rocm` only when running from a cargo `deps/` directory). -- [`codex_bridge.rs`](../crates/rocm-core/src/codex_bridge.rs) — (ROCMAI-662) the `CodexBridgeSnapshot`/`CodexBridgeGpuSnapshot`/`CodexBridgeEngine` host-snapshot DTOs. Plain serde data: `rocm` and `rocmd` each build their own snapshot of this shape, so the types live here rather than in either binary. -- [`command_capture.rs`](../crates/rocm-core/src/command_capture.rs) — (ROCMAI-720) running the `rocm` binary as a captured child: `CommandCapture`, `run_rocm_capture_with_env` and the `command_capture_text` formatter, shared by `rocmd`'s sandbox/MCP clusters and `rocm`'s chat tool bridge. Each caller passes the environment the child should get rather than this module choosing it; the bounded-execution half is [`process/bounded.rs`](../crates/rocm-core/src/process/bounded.rs)'s `run_with_timeout` (re-exported from [`process.rs`](../crates/rocm-core/src/process.rs)). `CommandCapture` is also the result carrier of that executor for the host probes ([`process/bounded.rs`](../crates/rocm-core/src/process/bounded.rs)'s `run_bounded`): besides the lossy text and the legacy `exit_status` it holds the raw bytes of both streams, a typed `CommandOutcome` (not found, spawn failed, timed out, wait failed, exited with a code, killed by a signal) and the status and error text the executor saw. A capture answered without a child is built with `CommandCapture::from_text`. -- [`config.rs`](../crates/rocm-core/src/config.rs) — (ROCMAI-151) the unified `RocmCliConfig` and its nested sections, including the persisted `WatcherMode` enum, the built-in watcher catalog (`BuiltinWatcherSpec`, `builtin_watchers`, `builtin_watcher`) and the rocm-dash dashboard sub-config — see the module's own doc comment for what it owns. -- [`confirm.rs`](../crates/rocm-core/src/confirm.rs) — (issue #769) the shared `[y/N]` prompt primitives: `parse_answer`, which sorts a typed line into `Answer::Yes`, `Answer::No` (`n`, `no` or an empty line) or `Answer::Unrecognized`, plus `print_prompt` and `read_answer` (each generic over the `Write`/`BufRead` stream so the sequence is unit-testable without a controlled terminal). `read_answer` takes the output stream as well: it ends the prompt line when the input ended without a newline (Ctrl-D, or piped input with no final newline) and says so when an answer is unrecognized and treated as no, showing at most the first 40 characters of the answer, best effort, so a failed write never replaces the verdict. Deduplicates the print-prompt/read-line/parse sequence that [`fix/consent.rs`](../crates/rocm-core/src/fix/consent.rs)'s `confirm()`, [`uninstall_plan.rs`](../apps/rocm/src/uninstall_plan.rs)'s `confirm_uninstall` and [`therock/consent.rs`](../apps/rocm/src/therock/consent.rs)'s `prompt_yes_no` each used to hand-roll. [`uninstall.rs`](../apps/rocm/src/uninstall.rs), [`storage.rs`](../apps/rocm/src/storage.rs) and [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) reach the prompt only through `confirm_uninstall`. `print_prompt` and `read_answer` stay separate rather than one bundled call because [`fix/consent.rs`](../crates/rocm-core/src/fix/consent.rs)'s `confirm()` attempts the read even when the prompt couldn't be written, while the other callers treat a failed write as fatal; [`fix/consent.rs`](../crates/rocm-core/src/fix/consent.rs)'s `confirm()` also keeps its own `--yes`/non-interactive short-circuit and refusal wording on top of these, since those are specific to the `fix` recipe flow. The module also holds `interactive_terminal`, whether stdin and stdout are both terminals, which callers check before they prompt, and `require_yes_or_interactive`, the `--yes`/terminal guard that [`uninstall.rs`](../apps/rocm/src/uninstall.rs), [`storage.rs`](../apps/rocm/src/storage.rs) and [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) put in front of that prompt; `interactive_terminal` is re-exported from `lib.rs` as `rocm_core::interactive_terminal` and from `host_gpu.rs` as `rocm_core::host_gpu::interactive_terminal`, the path it had before it moved here. -- [`crypto.rs`](../crates/rocm-core/src/crypto.rs) — (ROCMAI-152, Phase 7c) RSASSA-PKCS#1 v1.5/SHA-256 sign/verify, generic — not model-catalog-specific. -- [`diagnose.rs`](../crates/rocm-core/src/diagnose.rs) — `rocm diagnose`: matches an `Examination` and optional symptom text against the closed failure catalog and returns ranked findings. The module root keeps the public types (`Fix`, `Diagnosis`, `Route`, `DiagnoseReport`), the two score thresholds, `diagnose` itself, the two `vllm_*_symptom_is_diagnosable` classifiers the vLLM engine calls (they run the whole catalog, so they cannot live below it) and the re-exports that keep every `rocm_core::diagnose::` path resolving; everything else lives in child modules under `diagnose/`, with `diagnose.rs` kept as the module root so those paths and the links to it stay valid. The platform children do not import each other, and `catalog.rs` is the only module that names every checker. [`catalog.rs`](../crates/rocm-core/src/diagnose/catalog.rs) (the `CHECKERS` table that tags each check with the platform families it applies to, in catalog order, plus the platform-family resolution, applicability and the out-of-scope message), [`scoring.rs`](../crates/rocm-core/src/diagnose/scoring.rs) (every keyword table, the scoring helpers over them, and the small helpers that read an `Examination` or build a `Diagnosis`), [`report.rs`](../crates/rocm-core/src/diagnose/report.rs) (where an unmatched report is routed upstream, `upstream_route`, `route_when_no_match` and the tracker table behind them, and `render_report_text`, the human-facing view), [`linux.rs`](../crates/rocm-core/src/diagnose/linux.rs) (the checks that apply on Linux only: kernel and module, device-node access, package repositories and the repo-native install, plus the package-manager helpers and `dkms_driver_plan_is_supported`, which the driver planner calls), [`windows.rs`](../crates/rocm-core/src/diagnose/windows.rs) (the checks that apply on Windows only: the HIP SDK, the Adrenalin driver, the Visual C++ runtime and the display driver date, with the version comparison and scores only they use), [`wsl.rs`](../crates/rocm-core/src/diagnose/wsl.rs) (the checks that apply on WSL2 only: the DXCore handoff, the ROCDXG userspace, the distro floor, the Windows host driver and WSL 1), [`host.rs`](../crates/rocm-core/src/diagnose/host.rs) (the checks on the host's configuration that run on more than one platform: wheel architecture, the HSA override, `PATH`, the wheel's ROCm against the system's, an integrated GPU beside a discrete one, and GPUs ROCm does not support), [`engine.rs`](../crates/rocm-core/src/diagnose/engine.rs) (the checks on the engine runtime that run on Linux and WSL2: the vLLM out-of-memory and import failures, a second copy of the code object manager, and a `/dev/shm` too small for a serving workload, plus the two canonical symptom strings the vLLM engine falls back to) and [`test_support.rs`](../crates/rocm-core/src/diagnose/test_support.rs) (test-only: the `Examination` builders that the tests of more than one `diagnose` module share). -- [`download.rs`](../crates/rocm-core/src/download.rs) — streaming file downloads with resume and retry: `DownloadRequest`/`DownloadOutcome`, `download_file_streaming(_with_progress)` and the simpler `download_file_to_path(_with_progress)`, `Backoff`, and the retry policy (`DOWNLOAD_MAX_ATTEMPTS`). A download streams to a per-process `.part-` sibling, resumes with a `Range` request, and enforces the caller's size limit, expected length and SHA-256 digest before publishing the file. It uses `ureq`, not the loopback client in [`net.rs`](../crates/rocm-core/src/net.rs), and depends only on [`disk_space.rs`](../crates/rocm-core/src/disk_space.rs). The module is private and [`lib.rs`](../crates/rocm-core/src/lib.rs) re-exports its public names. -- [`endpoint_key.rs`](../crates/rocm-core/src/endpoint_key.rs) — (ROCMAI-662) the bearer key that guards a managed service's endpoint: the CSPRNG-drawn generator and its header-safety check. Split out of [`service_identity.rs`](../crates/rocm-core/src/service_identity.rs): an id and its endpoint key are made by unrelated mechanisms (readable/timestamp-based vs. CSPRNG) and meet only at the filesystem layer, where the key's sidecar is named after the id — not a reason to keep the two in one module. -- [`endpoint_readiness.rs`](../crates/rocm-core/src/endpoint_readiness.rs) — how far along a managed service's OpenAI-compatible endpoint is: `managed_service_endpoint_readiness` and `EndpointReadiness` (unreachable, listing the model, or serving a real single-token chat request), the lower-level `openai_chat_completion_probe`/`openai_chat_completion_status`/`openai_models_endpoint_has_model`, the shared inference-verified latch the engine adapters call (`engine_state_inference_verified`, `merge_json_state_file`) and the model-reference matching behind the model-listing check. It depends on [`net.rs`](../crates/rocm-core/src/net.rs), [`service_record.rs`](../crates/rocm-core/src/service_record.rs) and [`model_catalog.rs`](../crates/rocm-core/src/model_catalog.rs); [`net.rs`](../crates/rocm-core/src/net.rs) and [`service_record.rs`](../crates/rocm-core/src/service_record.rs) do not depend on it. The module is private and [`lib.rs`](../crates/rocm-core/src/lib.rs) re-exports its public names, so callers keep using `rocm_core::` paths. -- [`examine.rs`](../crates/rocm-core/src/examine.rs) — the host examination probe: the `Examination` document and its types, and `Examination::probe`, which runs the probes in order. The probes live in child modules under `examine/`, with `examine.rs` kept as the module root so the [`examine_driver_proptests.rs`](../crates/rocm-core/src/examine_driver_proptests.rs) `#[path]` attribute and the links to it stay valid: [`linux_gpus.rs`](../crates/rocm-core/src/examine/linux_gpus.rs) (Linux GPU enumeration from `lspci`, `rocminfo` and the kernel topology, with the marketing-name and APU classification they share), [`linux_driver.rs`](../crates/rocm-core/src/examine/linux_driver.rs) (kernel modules, device-node access and Secure Boot), [`rocm_install_probe.rs`](../crates/rocm-core/src/examine/rocm_install_probe.rs) (how ROCm was installed and which repository files configure it), [`library_copies.rs`](../crates/rocm-core/src/examine/library_copies.rs) (the loader library-copy search for comgr and the HIP runtime, and `comgr_matches_runtime`, which `diagnose/engine.rs` reads), [`framework.rs`](../crates/rocm-core/src/examine/framework.rs) (the PyTorch and llama.cpp probes), [`host_env.rs`](../crates/rocm-core/src/examine/host_env.rs) (the OS and distro, with the kernel release read through the summary stack's `detect_kernel_version`, the CPU fields recorded from the shared reader in `host_gpu/os_facts.rs`, tracked environment variables, shared memory, container check and kernel log), [`wsl.rs`](../crates/rocm-core/src/examine/wsl.rs) (the WSL probe, including the remote probe that reads a named distribution from the Windows host, and the distro-floor check) and [`windows.rs`](../crates/rocm-core/src/examine/windows.rs) (the native Windows probes: the GPU query, the HIP SDK, the Adrenalin driver and the MSVC redistributable, plus `parse_dotted_version`, which `diagnose/windows.rs` reads). -- [`gfx_target.rs`](../crates/rocm-core/src/gfx_target.rs) — gfx-target identification and the TheRock package-family tables, split out of [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) so [`managed_runtime.rs`](../crates/rocm-core/src/managed_runtime.rs) can read the family mapping without importing the module that probes the host: `extract_first_gfx_token`, `normalize_therock_family`/`known_therock_families`, `gfx_target_has_no_rocm_build`, the AMD PCI-device-id and marketing-name tables behind `gfx_target_from_pnp_device_id`, and the parsers for the Windows display text and the kernel's gfx-target version. The module is private; `lib.rs` re-exports four of the public names (all but `gfx_target_from_pnp_device_id`) and `host_gpu.rs`, as before, re-exports all five. -- [`gguf.rs`](../crates/rocm-core/src/gguf.rs) — reads the shape of a GGUF model (layers, KV heads, head width, parameter count, data offset) from its header over any `Read + Seek`, never touching the weights. -- [`gguf_fit.rs`](../crates/rocm-core/src/gguf_fit.rs) — pure arithmetic over that header: weights + KV cache at a context size and KV type + compute buffer + runtime reserve against dedicated VRAM, the largest context that fits, and what would make a model that does not fit, fit. -- [`gguf_source.rs`](../crates/rocm-core/src/gguf_source.rs) — where a header comes from: a local file, or a Hugging Face file, found by one repository-listing request (and a `HEAD` request for a file the listing does not size) and read by HTTP range requests (`HF_ENDPOINT` selects a mirror; redirects are followed by hand, up to five, and never from https to plain http). The only code in the estimate that reads a file or the network. -- [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) — (ROCMAI-85, Phase 7a of ROCMAI-27's sequencing) GPU/host hardware detection — see the module's own doc comment for what it owns. Its leaf concerns are child modules under `host_gpu/`, with `host_gpu.rs` kept as the module root: [`capture.rs`](../crates/rocm-core/src/host_gpu/capture.rs) (running an optional tool under a timeout, trying each spelling [`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs) gives for it), [`os_facts.rs`](../crates/rocm-core/src/host_gpu/os_facts.rs) (kernel version, distro name, installed RAM, and the CPU model and vendor, which one reader returns together for both the summary and `Examination::probe`: Linux from `/proc/cpuinfo`, Windows from the CPU row of the system inventory), [`linux.rs`](../crates/rocm-core/src/host_gpu/linux.rs) (the sysfs, KFD and DRM probes), [`gpu_visibility.rs`](../crates/rocm-core/src/host_gpu/gpu_visibility.rs) (which AMD GPUs this process may use, from the KFD/DRM counts and the `HIP_VISIBLE_DEVICES`/`ROCR_VISIBLE_DEVICES` masks, plus `windows_amd_gpu_listing`, the native-Windows adapter bound `rocm serve --gpu ` is checked against), [`windows_inventory.rs`](../crates/rocm-core/src/host_gpu/windows_inventory.rs) (the Windows display-adapter inventory and its parsers, including the AMD-adapter count behind `windows_amd_gpu_listing` and the system query whose CPU row the CPU reader in `os_facts.rs` takes), [`wsl.rs`](../crates/rocm-core/src/host_gpu/wsl.rs) (WSL detection, the librocdxg chain and the Windows host driver as seen from the guest), [`render.rs`](../crates/rocm-core/src/host_gpu/render.rs) (the `rocm examine` text of an `ExamineSummary`, as a second `impl` block), [`diagnostics.rs`](../crates/rocm-core/src/host_gpu/diagnostics.rs) (the GPU detection diagnostics text) and [`engine_default.rs`](../crates/rocm-core/src/host_gpu/engine_default.rs) (the default serve engine, and the vLLM preference for the TheRock families that serve through it). -- [`host-probing.md`](host-probing.md) — a design note, not a module: [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) and [`examine.rs`](../crates/rocm-core/src/examine.rs) are two separate host-probing stacks that read some of the same facts twice (the Windows GPU query, the marketing-name table and the subprocess runners). It proposes which of each pair should survive, how the two differ and the order in which they could converge, and records what each convergence decided; it changes no code itself. Three pairs are converged: the `PATH` lookup ([`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs)'s `which` is now the only copy) and the kernel release ([`os_facts.rs`](../crates/rocm-core/src/host_gpu/os_facts.rs)'s `detect_kernel_version` is now the only `uname -r` reader, which [`host_env.rs`](../crates/rocm-core/src/examine/host_env.rs)'s `probe_os` calls for `kernel_release`, and `rocm examine --json` runs it once: [`examine.rs`](../crates/rocm-core/src/examine.rs)'s `Examination::probe_with_summary` probes the host and hands the examination's kernel release to the summary), and the CPU model ([`os_facts.rs`](../crates/rocm-core/src/host_gpu/os_facts.rs) has one reader per platform for the model and vendor, which `probe_cpu_linux` and `probe_cpu_windows` record and the summary reads). The first step of the subprocess runners is delivered too: [`process/bounded.rs`](../crates/rocm-core/src/process/bounded.rs)'s `run_bounded` is the executor behind `run`, `capture_optional_command*` and the Windows diagnostic capture. It is a snapshot, to be retired when the convergence tickets close. -- [`jsonl_store.rs`](../crates/rocm-core/src/jsonl_store.rs) — the JSONL store engine behind the automation stores: the sibling `.lock` file (`jsonl_lock_path`, re-exported at the crate root), single-line appends, torn-tail repair, size-based rotation (`JsonlRotation`) and the tail-first readers that span rotated generations. It is generic over the record type; [`automation.rs`](../crates/rocm-core/src/automation.rs) supplies the record types and each store's policy, and nothing in this module depends on it, in production or in its own tests: those drive the engine with a small record type of their own. The module is private; its engine items are `pub(crate)`. -- [`managed_runtime.rs`](../crates/rocm-core/src/managed_runtime.rs) — (ROCMAI-85, Phase 7a) the TheRock managed-runtime-environment surface — see the module's own doc comment for what it owns. -- [`model_catalog.rs`](../crates/rocm-core/src/model_catalog.rs) — (ROCMAI-152, Phase 7c) the curated model catalog's types, built-in catalog JSON loading, signed external recipe indexes, and artifact cache-marker bookkeeping — see the module's own doc comment for what it owns. -- [`model_readiness.rs`](../crates/rocm-core/src/model_readiness.rs) — the `rocm diagnose --model` fit assessment: curated-recipe lookup against a host's measured GPU/RAM. `rocm model --verbose` renders its own fit labels in [`model_catalog_text.rs`](../apps/rocm/src/model_catalog_text.rs), which uses exactly two items from this module: `curated_alternatives`, called directly, and `recipe_display_ref`, reached through a private one-line wrapper of the same name in that file. For a GGUF outside the catalog it also attaches a context-size estimate (the three `gguf*` modules above). -- [`net.rs`](../crates/rocm-core/src/net.rs) — (ROCMAI-154) networking primitives: the default local host and port, URL/endpoint formatting and parsing, and the hand-rolled loopback HTTP/TCP client (`http_get_text*`, `http_post_json_with_auth`, `read_http_response_bounded`). It depends on no other service module: the managed-service readiness probes built on it live in [`endpoint_readiness.rs`](../crates/rocm-core/src/endpoint_readiness.rs) and the streaming downloads in [`download.rs`](../crates/rocm-core/src/download.rs). -- [`paths.rs`](../crates/rocm-core/src/paths.rs) — `AppPaths` and its filesystem-location primitives, including `AppPaths::env_vars`, the three `ROCM_CLI_*_DIR` variables that make a child process run on the same roots, and the constants that name the variables (`CONFIG_DIR_ENV`, `DATA_DIR_ENV`, `CACHE_DIR_ENV`, `ENGINE_ENVS_ROOT_ENV`). -- [`placeholder.rs`](../crates/rocm-core/src/placeholder.rs) — the `` placeholder rendered reports print for an empty value: `empty_as_unknown` (returns the value untouched) and `trimmed_or_unknown` (trims first), shared by `apps/rocm`'s driver-install plan and chat tool summaries and by [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs)'s Windows GPU diagnostics, replacing the copy those two `apps/rocm` callers shared in [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) and `host_gpu.rs`'s own trimming copy. -- [`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs) — the host probes' subprocess and file-read helpers, split out of [`examine.rs`](../crates/rocm-core/src/examine.rs) so `fix.rs`, `process/bounded.rs` and the child modules of [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) reach them without importing the module that owns the `Examination` document: `run`/`run_with_env`/`run_raw` (run a command under a timeout, as thin adapters over [`process/bounded.rs`](../crates/rocm-core/src/process/bounded.rs)'s `run_bounded`; `rc` is `127` when it cannot be spawned, `124` on timeout or a failure to wait and `-1` for a child killed by a signal), `run_utf16le`/`decode_utf16le` (for `wsl.exe`'s UTF-16LE output), `read_text`/`read_host_text`, `which` (the one `PATH` lookup, used by both host-probing stacks: it skips an empty `PATH` entry, searches a `PATH` that is not valid Unicode and follows `PATHEXT` on Windows) with `tool_path_candidates`, the spellings it tries and the capture runner in [`host_gpu/capture.rs`](../crates/rocm-core/src/host_gpu/capture.rs) starts in turn, the `SHORT`/`MEDIUM` timeouts and `truncate_to_chars`. All are `pub(crate)` except `run_raw`, which stays private to the module. The module itself is private to the crate and is not re-exported. -- [`process.rs`](../crates/rocm-core/src/process.rs) — (ROCMAI-154, Phase 7b) process-spawn/terminate primitives, including `FileLock`, plus a re-export of the bounded subprocess executor, `run_with_timeout` and `run_bounded`, which lives in [`process/bounded.rs`](../crates/rocm-core/src/process/bounded.rs) (split out of this file to keep it under the module size limit, with its tests, and re-exported here so every caller's path is unchanged). -- [`process/bounded.rs`](../crates/rocm-core/src/process/bounded.rs) — the bounded subprocess executor behind `run_with_timeout` and `run_bounded`, a private child of [`process.rs`](../crates/rocm-core/src/process.rs) whose items are re-exported from there. It drains both pipes on their own threads from the moment the child starts, so output size cannot stall a command into its own timeout, and it bounds how much of a timed-out child's output the error quotes, because that text reaches persisted automation logs. The same executor is also reachable as `run_bounded`, which returns the run as a [`command_capture.rs`](../crates/rocm-core/src/command_capture.rs) `CommandCapture` (raw bytes, a typed `CommandOutcome`, the partial output of a timed-out child) instead of an `Err`, and is what [`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs)'s `run_raw`, [`host_gpu/capture.rs`](../crates/rocm-core/src/host_gpu/capture.rs)'s `capture_optional_command_candidate_with_timeout` and the Windows-only `capture_diagnostic_command` in [`host_gpu/diagnostics.rs`](../crates/rocm-core/src/host_gpu/diagnostics.rs) now run on, so none of them waits for a descendant that holds a pipe beyond the 200 ms drain grace. Its wait loop starts at a few milliseconds and backs off to 50 ms, so a probe that exits at once is not charged the full interval. It is not yet the *only* such helper: [`therock/process.rs`](../apps/rocm/src/therock/process.rs)'s `wait_with_output_bounded` still joins its reader threads with no time limit, so a grandchild holding the pipe can outlast its timeout; converging it is the remaining part of the follow-up to ROCMAI-448 tracked in [#623](https://github.com/ROCm/rocm-cli/issues/623). -- [`quoting.rs`](../crates/rocm-core/src/quoting.rs) — (ROCMAI-727) argument-quoting helpers with real execution stakes (POSIX shell, PowerShell), consolidated out of `apps/rocm`-side near-duplicates — see the module's own doc comment for what it owns. `posix_shell_quote` also renders the command lines the CLI shows (through `apps/rocm`'s `shell_quote`); only `comfyui.rs`'s log-line quoter stays separate. -- [`report_rollup.rs`](../crates/rocm-core/src/report_rollup.rs) — (ROCMAI-492) counts read Doctor reports at every level of `Report::group_key`, with refused and unread reports kept apart. Pure, with no transport: the mailbox adapter that feeds it is maintainer tooling in `xtask`, behind `cargo xtask report-rollup`. -- [`report_trend.rs`](../crates/rocm-core/src/report_trend.rs) — (ROCMAI-745) the same reports counted per week, and the weeks in which a known problem rose sharply. Pure like the rollup: it is handed a `Week`, which is all a date reduces to, and holds no time finer than that. -- [`rocm_install.rs`](../crates/rocm-core/src/rocm_install.rs) — (ROCMAI-85, Phase 7a) unmanaged ("legacy") ROCm install discovery — see the module's own doc comment for what it owns. -- [`service_identity.rs`](../crates/rocm-core/src/service_identity.rs) — (ROCMAI-662) a managed service's identifier: the validated `ServiceId` and `generate_service_id`. The bearer key guarding a service's endpoint lives in [`endpoint_key.rs`](../crates/rocm-core/src/endpoint_key.rs) instead — see that entry for why. -- [`service_record.rs`](../crates/rocm-core/src/service_record.rs) — (ROCMAI-151) `ManagedServiceRecord`, the on-disk manifest for a managed inference service, and the engine state-file keys and probe retry interval (`INFERENCE_VERIFIED_STATE_KEY`, `INFERENCE_PROBE_ATTEMPTED_STATE_KEY`, `INFERENCE_PROBE_RETRY_INTERVAL`) that tie it to [`endpoint_readiness.rs`](../crates/rocm-core/src/endpoint_readiness.rs) — see the module's own doc comment for what it owns. It reads [`net.rs`](../crates/rocm-core/src/net.rs) only for `format_http_base_url`. -- [`vllm_oom.rs`](../crates/rocm-core/src/vllm_oom.rs) — the vLLM out-of-memory log-tail reader shared by `rocm-engine-vllm`'s post-failure hint and the `rocm serve` summary: segmenting a captured engine log tail, scoring each candidate with [`diagnose/engine.rs`](../crates/rocm-core/src/diagnose/engine.rs)'s own vLLM-OOM checker rule, selecting the user's proximate failing line, and rendering it for display. Also owns the `VLLM_OOM_DETECTED_PREFIX`/`VLLM_OOM_DIAGNOSE_COMMAND` markers `rocm-engine-vllm` and `apps/rocm` must agree on byte for byte. `VLLM_GPU_MEMORY_UTILIZATION_HINT` is *not* here — it predates this module, is consumed more widely, and stays in [`lib.rs`](../crates/rocm-core/src/lib.rs) as noted below. -- [`windows_driver.rs`](../crates/rocm-core/src/windows_driver.rs) — the Windows AMD display driver's version and date, and whether that date predates the first HIP SDK for Windows (an advice-only floor, not a compatibility check); `rocm examine`, `rocm diagnose` and `rocm install driver` all read their verdict from it. - -What else stays in [`lib.rs`](../crates/rocm-core/src/lib.rs), beside module declarations and re-exports, was left unclaimed by every phase-7 cluster and is now decided (ROCMAI-662), so a later cleanup pass places it by domain rather than by where it happens to sit in the file: - -- **Permanent crate-root primitives.** Each is consumed from more than one module or crate, and none belongs to a domain an existing module owns; a dedicated module would add a path segment and nothing else. - - `unix_time_millis` — the crate-wide clock helper, used across this crate's own modules and throughout `rocm` and `rocmd`. - - `require_nonempty` — non-empty field validation, used by this crate's automation, binary-path and model-catalog modules and by all three engine crates. - - `command_failure_detail` — picks the best detail string from a failed subprocess's output, used by [`process/bounded.rs`](../crates/rocm-core/src/process/bounded.rs), the vLLM engine, and the AIM engine's [`docker.rs`](../engines/aim/src/docker.rs). - - `sanitize_component` — the lowercase-alphanumeric slugger shared by [`service_identity.rs`](../crates/rocm-core/src/service_identity.rs)'s `generate_service_id` and [`model_catalog.rs`](../crates/rocm-core/src/model_catalog.rs)'s artifact cache-marker names. It is not model-catalog-specific, so it does not move there. - - `SDK_TORCH_STACK_PACKAGES` (the packages the opt-out spares, read by both the CLI and the vLLM engine) beside `TORCH_ALIGNMENT_DISABLED_ENV`/`torch_alignment_disabled` — the one read of the torch-alignment opt-out, shared by the CLI and the vLLM engine so the two cannot disagree. - - `VLLM_GPU_MEMORY_UTILIZATION_HINT` — a single wording contract between the CLI, the vLLM engine, and this crate's own `fix-16-vllm-oom` diagnosis; `rocm-core` is the only crate all of them can reach. - -[`lib.rs`](../crates/rocm-core/src/lib.rs) now holds only module declarations, re-exports, the crate-root primitives above, the private `use` shims that let sibling modules reach some `host_gpu`, `managed_runtime`, `rocm_install` and `runtime` items as `crate::` paths, and its test-only modules — the end state of the modularization effort for this crate (ROCMAI-27, planned last: highest fan-in, since every app and engine crate depends on it, but lowest novelty, since the sibling modules already prove the pattern). - -Further `rocm-core` modules, each with its own doc comment except where noted: - -- [`browser.rs`](../crates/rocm-core/src/browser.rs) — handing a URL to the user's browser, behind a trait so the opening can be replaced in tests. -- [`disk_space.rs`](../crates/rocm-core/src/disk_space.rs) — free-space preflight checks and out-of-space error reporting. -- [`fake_executable.rs`](../crates/rocm-core/src/fake_executable.rs) — writing stand-in executables that tests across the workspace then run. -- [`fix.rs`](../crates/rocm-core/src/fix.rs) — `rocm fix`: remediations for diagnosed failure modes. Its `RECIPES` list (in [`fix/catalog.rs`](../crates/rocm-core/src/fix/catalog.rs)), together with the checkers under `diagnose/` (their table is [`catalog.rs`](../crates/rocm-core/src/diagnose/catalog.rs)), is the authoritative failure catalog. [`fix.rs`](../crates/rocm-core/src/fix.rs) stays the module root, as [`examine.rs`](../crates/rocm-core/src/examine.rs) does for `examine/`, so links to it stay valid, with its children in `fix/`; it keeps the dispatch (`apply`, `Plan`, `plan_of`, `act_on`) and re-exports the names the rest of the crate and the apps use, so `crate::fix::exit`, `rocm_core::fix_exit`, `rocm_core::fix::FixClass` and the `crate::fix::` oracles that the tests under `diagnose/` call keep resolving. The children are private modules: [`fix/options.rs`](../crates/rocm-core/src/fix/options.rs) (the named exit codes, `FixOptions` and `FixClass`); [`fix/consent.rs`](../crates/rocm-core/src/fix/consent.rs) (the consent decision and `confirm`, the run and query timeouts, `current_os`, and the `fail!` helper, which it re-exports by path for its siblings); [`fix/runners.rs`](../crates/rocm-core/src/fix/runners.rs) (the host-mutating runners, one per auto-applicable fix, with their rc-file, PATH and device-pin helpers; only the four entry points the catalog names are visible to the root, and the `*_windows` variants are ordinary functions that every platform compiles); [`fix/catalog.rs`](../crates/rocm-core/src/fix/catalog.rs) (`FixRecipe`, the per-platform class table, `RECIPES`, the lookups by fix-id, and the `cfg(test)` oracles [`diagnose.rs`](../crates/rocm-core/src/diagnose.rs) and the e2e crate hold their own copies to); [`fix/render.rs`](../crates/rocm-core/src/fix/render.rs) (`list_recipes`, a recipe's plan and verify lines, `format_flags`, and the refusal for a diagnosis position passed as a fix-id); and [`fix/manifest.rs`](../crates/rocm-core/src/fix/manifest.rs) (the published JSON contract, `CATALOG_CONTRACT_VERSION` and `catalog_manifest`). `render` and `manifest` read `RECIPES` from `catalog`; nothing in `catalog` reads either. -- [`foreign_temp_probe.rs`](../crates/rocm-core/src/foreign_temp_probe.rs) — a test probe, compiled only for this crate's tests and under the `test-support` feature, that checks a writer leaves another writer's temp files alone; shared by this crate's tests and the tests of the crates that publish through `atomic_write.rs`. -- [`hardware_root.rs`](../crates/rocm-core/src/hardware_root.rs) — the root the hardware probes resolve host paths through (`host_path`): the real host in a normal build, a simulated host tree for the E2E suite in an `e2e-test-hooks` build. It also owns `read_os_release` (the `/etc/os-release` read with its `/usr/lib/os-release` fallback) and `real_os_release`, the one reader every package-manager plan and install hint uses, which always reads the real host even under a simulated root; the resolver it passes is private, so a second copy of that reader cannot be written outside this module. -- [`log_tail.rs`](../crates/rocm-core/src/log_tail.rs) — the one routine that reads the last lines of a log: `tail_lines` (UTF-8) and `tail_lines_decoded`, which takes a `LogDecode` (`PLAIN`, or `CONSOLE`: UTF-16 little-endian detected by a byte order mark or by zero bytes in every other position, plus ANSI sequences stripped by `strip_ansi_sequences`). The read is seek-bounded by the caller's byte budget (never past the file size it measured first, so a log that is still being written cannot pull it further), drops a partial leading line, and decodes invalid text lossily instead of failing, so a log view never refuses to show a log. A log that is truncated or recreated between that measurement and the read (a restarted service recreates its log) is not an error: the read measures it again and starts over, and a log that will not hold still reads as empty. `CONSOLE` does not count an unterminated final fragment made only of escape sequences (a colour reset after the last newline) as a line. `tail_log_decoded` returns the same lines as a `LogTail`, which also says how many bytes the budget left unread, so a view can tell an empty log from one whose newest line is longer than the budget (`newest_line_exceeds_the_read_bound`) and say which: `newest_line_exceeds_bound_notice` is the one wording of that clause, derived from `LOG_VIEW_MAX_TAIL_READ`, and `service_log_tool_summary` the one sentence the `service_logs` tool answers with (no output yet, newest line too long to show, or how many lines were read). The lemonade and vLLM adapters call it, and so do the log views: [`services_text.rs`](../apps/rocm/src/services_text.rs)'s `read_log_tail` (`rocm services logs`, `rocm logs`, and the CLI's own `service_logs` tool in [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs)), [`comfyui.rs`](../apps/rocm/src/comfyui.rs)'s `read_log_tail` (`rocm comfyui logs`, with `CONSOLE`) and [`mcp.rs`](../apps/rocmd/src/mcp.rs)'s `read_log_tail` (the daemon's `service_logs` tool). Those are thin adapters that choose a `LogDecode`, pass the shared `LOG_VIEW_MAX_TAIL_READ` budget and add their own error label, and none has a reader of its own. `rocmd` cannot depend on `rocm`, which is why the routine lives here. -- [`openmpi.rs`](../crates/rocm-core/src/openmpi.rs) — OpenMPI, libatomic and libnuma detection, the `libmpi_cxx` compatibility shim, and the per-library install plans (`build_openmpi_install_plan`, `build_libatomic_install_plan`, `build_libnuma_install_plan`) and hints, needed by vLLM's ROCm wheels. The distro-generic half of that planning lives in [`package_plan.rs`](../crates/rocm-core/src/package_plan.rs); [`openmpi.rs`](../crates/rocm-core/src/openmpi.rs) re-exports its public items, so `rocm_core::openmpi::running_as_root`, `plan_for_os_release_read` and the rest keep resolving, and `pub(crate)` re-exports `PackageManager` and `resolve_package_manager` for [`diagnose.rs`](../crates/rocm-core/src/diagnose.rs). -- [`os_release.rs`](../crates/rocm-core/src/os_release.rs) — the one `/etc/os-release` parser every reader of that file uses. -- [`package_plan.rs`](../crates/rocm-core/src/package_plan.rs) — the planning half of a system-package install that does not depend on which library is installed: `PackageManager` and `resolve_package_manager` (from an os-release `ID`/`ID_LIKE`), `SystemPackageInstallPlan` and `InstallCommand`, `plan_for_os_release_at`/`plan_for_os_release_read` (which take the per-library builder as an argument), `InstallHint`, the root and passwordless-`sudo` checks (`running_as_root`, `can_autoinstall`) and the `apt-get -s` helpers (`apt_simulate_argv`, `parse_apt_simulate_removals`, `is_protected_rocm_package`). It never runs anything and depends on no other module of this crate except [`os_release.rs`](../crates/rocm-core/src/os_release.rs) and [`hardware_root.rs`](../crates/rocm-core/src/hardware_root.rs), which it reads os-release through. The module is private; its public items are re-exported from [`openmpi.rs`](../crates/rocm-core/src/openmpi.rs). It is a different module from [`system_packages.rs`](../apps/rocm/src/system_packages.rs) in `apps/rocm`, which runs these plans with consent and `sudo`. -- [`proc_lifecycle.rs`](../crates/rocm-core/src/proc_lifecycle.rs) — verified, bounded termination of a process by persisted PID, refusing to signal a PID whose start-time identity no longer matches (`terminate_verified`), and the one managed-stop routine built on it that `rocm services stop` and `rocmd`'s `stop_server` both call: `terminate_recorded_service_pids` walks the processes a service record names (supervisor, then engine, each with its own start-time, the stopping process's own PID reported as `self` and never signalled) and returns one `RecordedPidStop` per PID (each caller, on a stop that confirms every one gone, then clears the record's recorded processes with `ManagedServiceRecord::clear_recorded_processes` in [`service_record.rs`](../crates/rocm-core/src/service_record.rs), so a repeated stop reaches no stale PID; an unconfirmed stop keeps them); `terminate_recorded_pid` terminates one of them, adding on Windows a `taskkill /T /F` of its descendants first, because `terminate_verified` cannot walk a process tree there, and only for a PID that passes the same identity check (`process_start_ticks` is the kernel start-time on Linux and the process creation time on Windows, so a recycled PID is refused before any `taskkill`; a record written before Windows recorded one cannot be refuted), holding the PID open on Windows from before that check until the stop ends so the PID cannot be reused in between (a PID that matches but cannot be held is reported unverified and not signalled), and treating a tree kill that did not complete, or did not finish within `MANAGED_STOP_GRACE` (the `taskkill` is killed and reaped at that deadline), as an unconfirmed stop (`descendants_unconfirmed` when the root itself was seen to exit, `timed_out` only when it outlived its deadline), except that a `taskkill` which found no such process is judged by the root's own re-read, so a root that exited by itself is `exited_before_tree_kill`, which the record-wide settling in `terminate_recorded_service_pids` turns into a stop only when another recorded process (the engine, which is visited as its own role and folded by both callers) is confirmed gone, and starting that `taskkill` from the system directory (`GetSystemDirectoryW`, not the `SystemRoot` variable) through `windows_system_tool`; a PID that cannot be queried at all, as against one that is gone, reads as unverifiable unless a readable recorded token differs, in which case that mismatch wins (`ProcessProbe` and `probe_process` in [`process.rs`](../crates/rocm-core/src/process.rs), whose `may_be_running` is the answer for any decision that must not take an unqueryable process for gone); `MANAGED_STOP_GRACE` is the one grace period. The termination is injectable, so a caller's test supplies outcomes it cannot construct and a test of the Windows step runs on every host. -- [`report.rs`](../crates/rocm-core/src/report.rs) — the content of a Doctor report and the rule deciding whether one may exist; it sends nothing. -- [`report_delivery.rs`](../crates/rocm-core/src/report_delivery.rs) — how a report leaves the machine: building its link and deciding whether a browser may be started. -- [`runtime.rs`](../crates/rocm-core/src/runtime.rs) — the host-platform layer: `RuntimePlatform`/`RuntimeHost`, OS-specific executable and Python-environment names (including `runtime_python_env_root_for_executable`, the one rule for finding an environment's folder from its interpreter's path: only an interpreter directly inside a `bin` or `Scripts` folder, in any case, has one, and everything else gets `None`; the adopt command, the ComfyUI runtime environment and the vLLM launch all call it rather than keeping a copy, since the engine crate cannot reach `apps/rocm`), default config/data/cache directories, path-text and path-list helpers, and `install_root_has_payload`, the one definition of a non-empty install root (dot-entries such as the runtime marker do not count; a path that does not exist holds nothing; a root that cannot be listed is an error) that tarball extraction, update repair detection and activation validation in `apps/rocm` all ask (no module doc comment). -- [`sigpipe.rs`](../crates/rocm-core/src/sigpipe.rs) — `with_sigpipe_ignored`, which turns a write to a pipe whose reader has gone into an ordinary error instead of a signal; `rocm` runs with SIGPIPE at its default action, so the engine stdio client wraps its write to the child, and each write forwarding the child's stderr to its own, in it. Guarded regions may overlap, across threads too; the disposition in force before the first is put back when the last ends. -- [`terminal.rs`](../crates/rocm-core/src/terminal.rs) — one ECMA-48 walk over untrusted terminal output, shared by every caller that has to quote or re-render it (`serve_summary.rs`, `vllm/startup_diagnostics.rs`, `vllm_oom.rs`, `diagnose/engine.rs`). -- [`user_path.rs`](../crates/rocm-core/src/user_path.rs) — removing the install directory from the per-user Windows `Path` that the installer added it to. -- [`uv.rs`](../crates/rocm-core/src/uv.rs) — acquiring the `uv` package manager into the managed cache, plus the argument/environment helpers `apps/rocm` and the vLLM engine share. - -### `crates/rocm-dash-core`, `rocm-dash-collectors`, `rocm-dash-daemon`, `rocm-dash-tui` — dashboard/telemetry - -The `rocm-dash-tui` lists below cover every production file in the crate: the top-level modules, the `agent/` and `app/` directories, and `ui/` with its `ui/tabs/` subdirectory. [`app/test_support.rs`](../crates/rocm-dash-tui/src/app/test_support.rs) holds only shared test helpers. The crate depends on `rocm-dash-core` and never on `rocm-core` (the edges are listed in [`crate_edges.rs`](../xtask/src/crate_edges.rs); `rocm-dash-collectors` is a dependency on Windows only), so anything that needs `rocm-core` data reaches it through the `tool_exec` and `registry_probe` seams or through values the `rocm` binary plumbs in on `ResolvedArgs`. - -The old agent.rs was split (mechanical relocation — the shared seam types stay in [`agent/mod.rs`](../crates/rocm-dash-tui/src/agent/mod.rs), reached from the split-out files via `super::`) into: - -- [`agent/mod.rs`](../crates/rocm-dash-tui/src/agent/mod.rs) — the `AgentClient` seam, `AgentError`, `StateSnapshot`, `InferenceParams`, `REQUEST_TIMEOUT`. -- [`agent/snapshot.rs`](../crates/rocm-dash-tui/src/agent/snapshot.rs) — pure JSON telemetry helpers with no `rig` dependency. -- [`agent/tools.rs`](../crates/rocm-dash-tui/src/agent/tools.rs) — the `rig::tool::Tool` wrappers for the four telemetry tools (`gpu_status`, `list_instances`, `bench_summary`, `tokens_per_watt`), their name table `TELEMETRY_TOOL_NAMES`, and the ROCm read/mutating tool dispatch. -- [`agent/clients.rs`](../crates/rocm-dash-tui/src/agent/clients.rs) — the `RigAgentClient`/`ChatGptAgentClient`/`AnthropicAgentClient`/`MockAgentClient` backends. - -[`app/mod.rs`](../crates/rocm-dash-tui/src/app/mod.rs) is modularized (ROCMAI-84, Phase 4 of ROCMAI-27's sequencing) into an `app/` directory. [`app/types.rs`](../crates/rocm-dash-tui/src/app/types.rs), [`app/event_loop.rs`](../crates/rocm-dash-tui/src/app/event_loop.rs), [`app/scrollbar.rs`](../crates/rocm-dash-tui/src/app/scrollbar.rs), and [`app/actions.rs`](../crates/rocm-dash-tui/src/app/actions.rs) follow full domain extraction. [`app/chat.rs`](../crates/rocm-dash-tui/src/app/chat.rs), [`app/slash.rs`](../crates/rocm-dash-tui/src/app/slash.rs), and [`app/summary.rs`](../crates/rocm-dash-tui/src/app/summary.rs) were extracted earlier via mechanical relocation, the same convention the `agent/` split above follows. `quit_confirm`, `tool_approval`, `overlays`, `scroll` and `chat_state` each hold a further `impl AppState` block for one cohesive group of reducer methods: - -- [`app/mod.rs`](../crates/rocm-dash-tui/src/app/mod.rs) — keeps `AppState` and its constructor, the theme picker, row selection, the `apply_event` reducer entry point and the handful of items that stay with it (`ProviderSwitch`, `HISTORY_CAP`, `BENCH_CAP`); the rest of `AppState`'s methods live in the child-module `impl` blocks listed below (`apply_action` itself is a free function in [`app/actions.rs`](../crates/rocm-dash-tui/src/app/actions.rs)) — the modularization effort's "reducer's reason to exist." `crate::app::*` paths for the public surface moved out are unchanged via re-exports (see the re-export block's comment for what counts as "public surface"). -- [`app/types.rs`](../crates/rocm-dash-tui/src/app/types.rs) — shared type/enum defs: `Focus`, `ResolvedArgs`, connection/tab/chat/replay state, `Modal`, `UpdateStatus`, `PaneFocus`, `ScrollTarget`, the slash/plan/approval payload types, and the Esc-menu, command-palette and options-panel navigation data (`MenuItem` and `MENU_ITEMS`, `PALETTE_DESTS`, `OPTIONS_TABS`) that `app/actions.rs` reads, and that [`ui/menu.rs`](../crates/rocm-dash-tui/src/ui/menu.rs) renders; the Esc menu's rows, their labels, the key handling's wrap bound and the height `draw_menu` reserves all come from the one `MENU_ITEMS` list; no `AppState` access. -- [`app/event_loop.rs`](../crates/rocm-dash-tui/src/app/event_loop.rs) — the tick loop that drives the dashboard: `run`, `event_loop`, the frame-draw shutdown gate and the registry-probe seeding. -- [`app/chat_runtime.rs`](../crates/rocm-dash-tui/src/app/chat_runtime.rs) — the live chat backend the tick loop owns, a leaf of `event_loop.rs`: `ChatRuntime` holds the agent the next submit is routed to plus the saved auto-detected local one that `/provider local` restores. `ChatRuntime::start` resolves the backend before the first frame, and `drain_provider_switch`, `drain_endpoint_rebuild` and `drain_dispatch` each consume one of `AppState`'s one-shot edges (`provider_switch`, `chat_endpoint_rebuild`, `chat_dispatch`). The detect and persist edges do not touch the backend and stay in `event_loop.rs`. -- [`app/terminal.rs`](../crates/rocm-dash-tui/src/app/terminal.rs) — terminal restoration and shutdown arbitration, a leaf of `event_loop.rs`: `restore_terminal` and its writer lock, the `SHUTTING_DOWN` latch, the termination-signal watcher (`spawn_termination_watcher`; its `TerminationSignals` has a `cfg(unix)` and a `cfg(windows)` variant) and the Ctrl+C key path (`is_ctrl_c`, `exit_on_ctrl_c`). `app/mod.rs` re-exports the items the rest of the crate and `apps/rocm` use. -- [`app/focus.rs`](../crates/rocm-dash-tui/src/app/focus.rs) — focused-host policy, a leaf of `event_loop.rs`: skipping the daemon client for a focused launch (`should_skip_daemon`), opening the one overlay it hosts (`open_overlay_for_focus`, `apply_startup_focus`) and swallowing the console keys that would kill a running job (`focused_close_key_blocked`). -- [`app/update_check.rs`](../crates/rocm-dash-tui/src/app/update_check.rs) — the background Updates-tile check, a leaf of `event_loop.rs`: the tick-driven `rocm update --json` job (`refresh_update_status`) and the reducer that folds its output into an `UpdateStatus` (`reduce_update_json`). -- [`app/scrollbar.rs`](../crates/rocm-dash-tui/src/app/scrollbar.rs) — mouse/scroll hit-testing: resolving a raw `MouseEvent` against recorded scrollbar tracks, the tab bar, and footer-legend chips into a `KeyAction`. -- [`app/actions.rs`](../crates/rocm-dash-tui/src/app/actions.rs) — `KeyAction` dispatch: translating a key press or resolved mouse hit into a `KeyAction` and applying it to reducer state. -- [`app/quit_confirm.rs`](../crates/rocm-dash-tui/src/app/quit_confirm.rs) — a further `impl AppState` block: the quit-confirm gates (`has_live_instance`, `has_stoppable_managed_instance_with`, the live registry read) and opening, answering and resolving the prompt (`open_quit_confirm`, `on_quit_confirm_key`, `quit_confirm_open_services_key`). The prompt is rendered from `ui/`. -- [`app/tool_approval.rs`](../crates/rocm-dash-tui/src/app/tool_approval.rs) — a further `impl AppState` block: handing a completed plan's action to the approval path (`on_plan_ready`), opening the approval modal (`open_approval`) and routing the verdict (`on_approval_key`, `take_approval`, `on_approval_declined`, `on_approval_result`). Not named `approval`, which would collide with [`ui/approval.rs`](../crates/rocm-dash-tui/src/ui/approval.rs). -- [`app/overlays.rs`](../crates/rocm-dash-tui/src/app/overlays.rs) — a further `impl AppState` block: which manager, console, approval or modal owns the keyboard, `close_overlays`, and the gating predicates the key handlers and renderer consult (`has_open_overlay`, `global_hotkeys_reachable`, `active_overlay_at_root`, `should_pane_back_out`, `focused_should_exit`). -- [`app/scroll.rs`](../crates/rocm-dash-tui/src/app/scroll.rs) — a further `impl AppState` block: the job-console, log-dock, chat and instance-detail scroll offsets (the console, dock and instance-detail clamp through its `ScrollState`) and the scrollbar tracks a mouse grab resolves against. Not named `scrollbar`, which is the mouse hit-testing module above. -- [`app/chat_state.rs`](../crates/rocm-dash-tui/src/app/chat_state.rs) — a further `impl AppState` block: chat consent, the local-endpoint detection offer, submitting a turn and applying the agent's reply or error (the config and agent-factory helpers stay in [`app/chat.rs`](../crates/rocm-dash-tui/src/app/chat.rs)). -- [`app/chat.rs`](../crates/rocm-dash-tui/src/app/chat.rs) — previously extracted from [`app/mod.rs`](../crates/rocm-dash-tui/src/app/mod.rs). -- [`app/slash.rs`](../crates/rocm-dash-tui/src/app/slash.rs) — previously extracted from [`app/mod.rs`](../crates/rocm-dash-tui/src/app/mod.rs). -- [`app/summary.rs`](../crates/rocm-dash-tui/src/app/summary.rs) — previously extracted from [`app/mod.rs`](../crates/rocm-dash-tui/src/app/mod.rs). - -The crate's remaining top-level modules, besides `agent/`, `app/` and `ui/`: - -- [`client.rs`](../crates/rocm-dash-tui/src/client.rs) — the connection task behind the dashboard's event stream, and `ClientMsg`, the one message type the app loop reads. `spawn` loops forever: it posts `Connecting`, runs `connect_and_run`, posts `Disconnected`, then sleeps for the next delay from [`reconnect.rs`](../crates/rocm-dash-tui/src/reconnect.rs) before trying again. On unix `connect_and_run` takes a `unix:/path` address (any other scheme is rejected), reads the daemon's `Welcome`, sends `Hello` and `Subscribe`, and forwards each event until `Bye` or EOF. On Windows there is no daemon socket, so the `cfg(windows)` arm collects host and GPU metrics in-process once a second through `rocm-dash-collectors` (the only use of that dependency) and posts them as `ClientMsg::HostGpuSnapshot`, which `AppState::push_host_gpu_snapshot` applies without treating its empty instance list as authoritative. Besides daemon events, `ClientMsg` carries the replay position and the TUI-internal chat, slash-command and approval results that [`replay.rs`](../crates/rocm-dash-tui/src/replay.rs) and the `agent/` and `app/` modules post. -- [`jobs.rs`](../crates/rocm-dash-tui/src/jobs.rs) — the one async process runner every operational screen shares. `run_effects` takes the `SideEffect`s the pure reducer in `rocm-dash-core` returns and starts a task for each `SideEffect::SpawnJob`. The task spawns the child with null stdin and piped stdout and stderr (`kill_on_drop`), posts each line as `StateEvent::JobLine` (keeping only the last `\r`-separated segment, so a progress bar that redraws in place reads as one line), and, once both pipes have closed, finishes with `JobDone` (the exit code, -1 when the child has none, as when a signal killed it) or `JobErr` for a wait failure; a spawn failure posts `JobErr` at once. It checks the shared cancel flag after every line and at least every 100 ms (`CANCEL_POLL`) while the child is idle, and kills the child when it flips; a cancelled job posts neither, because the reducer has already marked it `Cancelled`. Events go back over an unbounded channel on purpose: the reducer is synchronous and cannot apply backpressure, so output is bounded in the reducer instead (`JOB_OUTPUT_RING_CAP`). `app/event_loop.rs` owns the channel and folds the events into `AppState::jobs`; the screens in `ui/` start jobs only through `StateEvent::StartJob`. -- [`lib.rs`](../crates/rocm-dash-tui/src/lib.rs) — the library root: declares `agent`, `app`, `client`, `jobs`, `llm`, `reconnect`, `registry_probe`, `replay`, `tool_exec`, `transport` and `ui` as public modules, so `apps/rocm` runs the dashboard through `app::run` and the examples and integration tests drive the same modules in-process. -- [`llm.rs`](../crates/rocm-dash-tui/src/llm.rs) — chat endpoint configuration, with no HTTP client (the Rig-backed agents are in [`agent/clients.rs`](../crates/rocm-dash-tui/src/agent/clients.rs)). `resolve_llm_config` is a pure resolver: the base URL comes from the CLI, else the config, else the environment, else `DEFAULT_CHAT_BASE_URL` only if a TCP probe of it succeeded, and it returns `None` when none applies; the model comes from the CLI, else the config, else `DEFAULT_CHAT_MODEL`. `resolve_llm_config` strips the API key and custom auth header from a loopback base URL (`parse_host_port` handles bracketed IPv6, then `is_loopback_host`) and logs a warning when it discards one, so a configured local endpoint is never sent a gateway credential, and `LlmConfig`'s `Debug` redacts the key. `probe_endpoint(url, timeout)` is a TCP-only liveness check, and its callers pass `PROBE_TIMEOUT` (300 ms) for each resolved address, and `detect_local_endpoint` probes the Lemonade, vLLM and `rocm serve` default endpoints concurrently and returns the highest-priority one that answered; the last port is a literal copy of `rocm-core`'s default because this crate cannot depend on it. `pick_first_model` reads the first id of a `/v1/models` reply, which `apps/rocm`'s `dash.rs` also calls. The chat code in `app/chat_runtime.rs`, `app/chat.rs` and the Chat tab uses it. -- [`reconnect.rs`](../crates/rocm-dash-tui/src/reconnect.rs) — `Backoff`, the exponential delay `client.rs` sleeps between connection attempts: 250 ms, doubling up to 10 s, started over (a new `Backoff::default()`) after a connection that ended cleanly. -- [`registry_probe.rs`](../crates/rocm-dash-tui/src/registry_probe.rs) — the seam through which the dashboard reads the managed-service registry without depending on `rocm-core` or the daemon. `ManagedRegistryProbe::snapshot` returns a `ManagedRegistrySnapshot`: whether any record is live, and the ids `rocm services stop ` can reach. The binary implements it (`LiveManagedRegistryProbe` in `apps/rocm`'s `dash.rs`) and hands it in on `ResolvedArgs`. It is read live, at each quit attempt and each frame the quit-confirm prompt is open, rather than once at launch, so a model started mid-session and a Windows host with no instance snapshot are both seen; implementations must stay cheap (a local file read). It answers from each record's own status, so it can lag `rocm services list`, which also checks process liveness. `StaticManagedRegistrySnapshot` wraps an already-read snapshot for the launcher, which reads the registry once per menu pass. Compare [`tool_exec.rs`](../crates/rocm-dash-tui/src/tool_exec.rs), the same pattern for tool calls. -- [`replay.rs`](../crates/rocm-dash-tui/src/replay.rs) — the offline source behind `--replay`. `spawn` starts a task that posts `Connecting`, reads the whole session file up front (NDJSON `PersistedEntry` lines; a malformed line is skipped with a warning), posts `Connected`, and then posts the recorded events through the same `ClientMsg` channel as `client.rs`, so nothing downstream tells replay from a live daemon; it ends in `Disconnected` (the read error, or "end of recording"). `app/event_loop.rs` starts replay when `--replay` is given and the live client otherwise, except that a focused host without `--replay` starts neither. Between events it sleeps for the recorded gap capped at 2 s (`MAX_GAP_MS`) and then divided by the speed, with a 1 ms floor, so the cap bounds the recorded gap and not the wall-clock wait: at 0.25x a long gap sleeps 8 s. The returned `ReplayController` is what `app/actions.rs` drives: pause, resume, speed (`SPEED_STEPS`, 0.25x to 8x, stepped by `next_speed`/`prev_speed`) and jump. A forward jump emits the events it crosses at once; a backward jump posts `ClientMsg::ReplaySeek`, so the app drops state derived from past events, then re-emits from the start up to the new position. Every emitted event is followed by `ClientMsg::ReplayPosition` for the header's elapsed/total readout. -- [`tool_exec.rs`](../crates/rocm-dash-tui/src/tool_exec.rs) — the seam for chat tool calls that need `rocm-core`, in plain `serde_json` types. `RocmToolExecutor::execute` runs a read-only tool and returns `RocmToolOutcome::Result`, or returns `ApprovalRequired(ApprovalIntent)` for a mutating one without running it, or `Error`. `execute_approved` runs the same `(name, arguments)` only after the operator approves, re-validating first, and blocks, so callers run it off the async loop. The binary implements the trait (`BinToolExecutor` in `apps/rocm`'s `dash_seam.rs`); the dashboard holds it as `SharedRocmToolExecutor`, `None` under demo, replay and mock. The chat tools and slash commands use it; the operational screens in `ui/` do not, they spawn the `rocm` binary themselves through [`jobs.rs`](../crates/rocm-dash-tui/src/jobs.rs). -- [`transport.rs`](../crates/rocm-dash-tui/src/transport.rs) — newline-delimited JSON framing for `client.rs`: `write_line` serializes one value plus a newline and flushes, `read_line` returns `None` at EOF and an `InvalidData` error for a line that is not valid JSON for the requested type. The daemon's [`transport.rs`](../crates/rocm-dash-daemon/src/transport.rs) holds the same two functions, copied rather than shared so this crate does not depend on the daemon; the two sides serialize the `rocm-dash-core` protocol types. - -[`crates/rocm-dash-tui/src/ui/approval.rs`](../crates/rocm-dash-tui/src/ui/approval.rs) is the shared component for approval-state prompts — reuse it rather than hand-rolling new approval UI. - -The other shared `ui/` components the contributor rules in [`AGENTS.md`](../AGENTS.md) name — reuse these rather than hand-rolling a new console, box, spinner or status color (the overlays, widgets and tabs that use them are listed after the next list): - -- [`ui/job_console.rs`](../crates/rocm-dash-tui/src/ui/job_console.rs) — the shared "a job is running" surface: `draw_job_console` renders a job's status header, streamed output and key hints, and `on_console_key` handles its keys. -- [`ui/panel.rs`](../crates/rocm-dash-tui/src/ui/panel.rs) — the shared box chrome: bordered, titled panels (`bento`, `popup`), scrollbars, and the popup geometry and framing (`centered_rect`, `centered_width`, `draw_popup_frame`, `grey_overlay`) that [`ui/approval.rs`](../crates/rocm-dash-tui/src/ui/approval.rs), [`ui/job_console.rs`](../crates/rocm-dash-tui/src/ui/job_console.rs) and the `Modal::*` renderers ([`ui/help_modal.rs`](../crates/rocm-dash-tui/src/ui/help_modal.rs), [`ui/warnings_modal.rs`](../crates/rocm-dash-tui/src/ui/warnings_modal.rs), [`ui/theme_picker.rs`](../crates/rocm-dash-tui/src/ui/theme_picker.rs) and [`ui/menu.rs`](../crates/rocm-dash-tui/src/ui/menu.rs)) import. -- [`ui/exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs) — the helpers every operational screen uses to launch a `rocm` sub-command through the approval gate: `resolve_exe`, the approval-preview quoting (`display_args`, `quote_display_arg`), and the `rocm runtimes adopt` argv. `adopt_args` builds that argv for both the runtime manager's Adopt action and the onboarding wizard's Adopt-existing-folder path, with `--python` set to the Python executable inside the root (`Scripts\python.exe` on Windows, `bin/python` elsewhere, the layout `rocm-core` uses, kept here because the crate may not depend on `rocm-core`). Its unit tests reach both layouts through an injectable `windows` flag. -- [`ui/spinner.rs`](../crates/rocm-dash-tui/src/ui/spinner.rs) — pure helpers for the braille spinner frame (`spinner_frame`) and progress-percentage parsing (`parse_progress_pct`) that `job_console.rs` renders with. -- [`ui/theme.rs`](../crates/rocm-dash-tui/src/ui/theme.rs) — the semantic `Theme`, including the shared status-to-color mapping (`StatusTone` and `tone_color`, with `job_status_color` and `instance_status_color` for the job and instance status enums). -- [`ui/widgets.rs`](../crates/rocm-dash-tui/src/ui/widgets.rs) — small helpers shared across tabs, including `apply_char_key`/`apply_char_key_filtered`, the append-only text-field edit (`Char` appends, `Backspace` pops one char) that every form's key handler calls instead of writing its own `push`/`pop` arms. The Chat tab's input is the exception: its keys go through the `KeyAction` table in [`app/actions.rs`](../crates/rocm-dash-tui/src/app/actions.rs). A source-scan test in `xtask` ([`dash_text_edit_contract.rs`](../xtask/src/dash_text_edit_contract.rs)) fails if another dash-TUI file hand-rolls that `push`/`pop`. - -The `ui/` modules the split moved code out of or into, beyond the shared components above: - -- [`ui/quit_confirm.rs`](../crates/rocm-dash-tui/src/ui/quit_confirm.rs) — the quit-confirm prompt's content (title, body listing what is still served, the "press s" stop hint), split out of [`ui/mod.rs`](../crates/rocm-dash-tui/src/ui/mod.rs), which re-exports `quit_confirm_request` for the launcher. The gates that decide whether it opens are in [`app/quit_confirm.rs`](../crates/rocm-dash-tui/src/app/quit_confirm.rs). -- [`ui/header.rs`](../crates/rocm-dash-tui/src/ui/header.rs) — the dashboard header and its warning badge (`draw_header`), split out of `ui/mod.rs`. -- [`ui/footer.rs`](../crates/rocm-dash-tui/src/ui/footer.rs) — the footer legend and its clickable key chips (`draw_footer`), split out of `ui/mod.rs`. -- [`ui/instance_detail.rs`](../crates/rocm-dash-tui/src/ui/instance_detail.rs) — the instance Detail modal (`draw_detail`: summary strip, "recent throughput" panel, scrollable launch-args and env-vars panes, footer), split out of [`ui/tabs/instances.rs`](../crates/rocm-dash-tui/src/ui/tabs/instances.rs). It reads `sorted_instances`, `clamp_sel` and `status_meta` from `instances.rs`, which does not import it back. -- [`ui/modal.rs`](../crates/rocm-dash-tui/src/ui/modal.rs) — now only re-exports, so every item that was public at `ui::modal` before the split still resolves there: the popup geometry from [`ui/panel.rs`](../crates/rocm-dash-tui/src/ui/panel.rs) (`centered_rect`, `centered_width`, `draw_popup_frame`, `grey_overlay`) and the `Modal::*` renderers it used to hold, which are now in the four files below. -- [`ui/menu.rs`](../crates/rocm-dash-tui/src/ui/menu.rs) — the Esc main menu (`draw_menu`), the command palette (`draw_palette`) and the tabbed Options panel (`draw_options`), with the block-letter logo (`draw_logo`) and the settings row (`opt_row`) they compose, split out of [`ui/modal.rs`](../crates/rocm-dash-tui/src/ui/modal.rs). The palette destinations and options tabs it renders live in [`app/types.rs`](../crates/rocm-dash-tui/src/app/types.rs), so this file depends on those and not the reverse. -- [`ui/help_modal.rs`](../crates/rocm-dash-tui/src/ui/help_modal.rs) — the two Help modals, the contextual per-tab one (`draw_help`) and the global two-column keyboard reference (`draw_global_help`), split out of [`ui/modal.rs`](../crates/rocm-dash-tui/src/ui/modal.rs). Both size the popup to their wrapped content, through `popup_height_for`, which [`ui/warnings_modal.rs`](../crates/rocm-dash-tui/src/ui/warnings_modal.rs) also calls. -- [`ui/warnings_modal.rs`](../crates/rocm-dash-tui/src/ui/warnings_modal.rs) — the Warnings modal (`draw_warnings`: the text behind the header warning badge, with each multi-line warning cut to a few lines), split out of [`ui/modal.rs`](../crates/rocm-dash-tui/src/ui/modal.rs). It imports `popup_height_for` from [`ui/help_modal.rs`](../crates/rocm-dash-tui/src/ui/help_modal.rs), which does not import it back. -- [`ui/theme_picker.rs`](../crates/rocm-dash-tui/src/ui/theme_picker.rs) — the theme picker modal (`draw_theme_picker`: a scrollable list of the registered themes with a five-color swatch per entry, beside `draw_theme_preview`, a live preview of the highlighted theme), split out of [`ui/modal.rs`](../crates/rocm-dash-tui/src/ui/modal.rs). It imports the popup geometry from [`ui/panel.rs`](../crates/rocm-dash-tui/src/ui/panel.rs) and does not depend on `modal.rs`. - -Thirteen operational overlays share one lifecycle. Each has a state struct held as an `Option` on `AppState` (`None` is closed) and is opened by a `KeyAction::Open*` arm in [`app/actions.rs`](../crates/rocm-dash-tui/src/app/actions.rs), a slash command ([`app/slash.rs`](../crates/rocm-dash-tui/src/app/slash.rs)), the quit-confirm prompt's `s` key ([`app/quit_confirm.rs`](../crates/rocm-dash-tui/src/app/quit_confirm.rs)) or the startup focus ([`app/focus.rs`](../crates/rocm-dash-tui/src/app/focus.rs)), each of which first calls `close_overlays`, so at most one is open. `draw_active_manager` in [`ui/mod.rs`](../crates/rocm-dash-tui/src/ui/mod.rs) draws it into a centered card over a dimmed backdrop and shows the shared [job console](../crates/rocm-dash-tui/src/ui/job_console.rs) instead once the overlay's `active_job` is set. A screen's `on_key` mutates its own state and the shared job `State` and returns the reducer's `SideEffect`s, which `app/event_loop.rs` runs through [`jobs.rs`](../crates/rocm-dash-tui/src/jobs.rs). A mutating action stages an `ApprovalRequest` held in the screen's own state and shown by [`ui/approval.rs`](../crates/rocm-dash-tui/src/ui/approval.rs); the `rocm` path is resolved with `resolve_exe` when it is staged, the job starts only on Approve, and the CLI does the mutation, so the dashboard changes nothing itself. Read-only actions start their job directly. That is a separate path from a chat tool call's approval (`AppState::approval`, [`app/tool_approval.rs`](../crates/rocm-dash-tui/src/app/tool_approval.rs)). Exceptions are noted per screen. - -- [`ui/automations_manager.rs`](../crates/rocm-dash-tui/src/ui/automations_manager.rs) — lists the background checks from `AppState::automations` (`AutomationSummary`, plumbed in by the binary: id, summary, enabled, mode), refreshes with `rocm automations list`, and enables or disables the selected one through an approval. -- [`ui/bench_run.rs`](../crates/rocm-dash-tui/src/ui/bench_run.rs) — the form behind `rocm bench load`: endpoint (required; `https://` is rejected), optional model, a concurrency list or an auto-ramp toggle, and an output path that defaults to the daemon-tailed CSV (`bench_results_dir`) when there is one, so rows appear live in the Bench panel. Unlike the other overlays, submitting starts job `bench-run` directly, with no approval step, and closes the form. -- [`ui/command_screen.rs`](../crates/rocm-dash-tui/src/ui/command_screen.rs) — a freeform `rocm ...` runner. The input is split on whitespace (no quoting), and every command goes through approval showing the exact argv, since arbitrary subcommands cannot be classified as read-only; an argv containing key, token, secret or password adds a warning that arguments are visible in the process list and job log. -- [`ui/config_manager.rs`](../crates/rocm-dash-tui/src/ui/config_manager.rs) — `rocm config show` (read-only) plus approval-gated `rocm config enable-provider|disable-provider` for the fixed provider list (`PROVIDERS`: local, anthropic, openai). It has no key-entry field: provider keys come from the environment only. -- [`ui/engine_manager.rs`](../crates/rocm-dash-tui/src/ui/engine_manager.rs) — a fixed two-engine catalog (`ENGINE_CATALOG`: Lemonade and vLLM) with three approval-gated actions per engine: `rocm config set-default-engine `, `rocm engines install ` and the same with `--reinstall`. Job ids are `engine--`. -- [`ui/examine_manager.rs`](../crates/rocm-dash-tui/src/ui/examine_manager.rs) — runs `rocm examine`, read-only and streaming, with no approval; `open_running` starts it on open for the launcher's Diagnose host. It also prepares the Doctor report: `p` runs `rocm diagnose --report --json` (a preview that sends nothing) and `s` stages an approval whose body is the report, defaulting to Deny, after which `rocm diagnose --report --send` runs. Only a report whose output parsed as a JSON object with the `schema` number this build knows (`KNOWN_REPORT_SCHEMA`) can be sent; anything else is reported as unreadable and nothing is offered. That check looks only at the envelope because this crate cannot use `rocm-core`'s reader. -- [`ui/install_manager.rs`](../crates/rocm-dash-tui/src/ui/install_manager.rs) — the form behind `rocm install sdk`: channel, format (`wheel` or `tarball`), install prefix (typed or picked in the folder browser, then trimmed) and a dry-run toggle that is on by default. A dry run starts directly as job `install-sdk-dryrun`; a real install is approval-gated as `install-sdk` and adds `--approve-replacing-active-default` (not `--yes`, which would also approve `sudo` the dashboard's null-stdin child could not answer). -- [`ui/logs_view.rs`](../crates/rocm-dash-tui/src/ui/logs_view.rs) — `rocm logs`, optionally with `--search` terms from a search box; read-only, so no approval. A single job id means reopening re-attaches to the same console. -- [`ui/onboarding.rs`](../crates/rocm-dash-tui/src/ui/onboarding.rs) — the first-run flow, opened by `KeyAction::OpenOnboarding` (the `n` key on the Observe tab) and as the host for `Focus::Setup`; nothing auto-opens it at startup. Two paths, both approval-gated: install the ROCm SDK (a Configure step for the channel, Release or Nightly, an optional `--build-date` or `--version` pin and an optional prefix chosen in the folder browser, always `--format wheel` and `--approve-replacing-active-default`), or adopt an existing ROCm folder with the same `adopt_args` the runtime manager uses. -- [`ui/runtime_manager.rs`](../crates/rocm-dash-tui/src/ui/runtime_manager.rs) — lists the registered runtimes from `AppState::runtimes` (`RuntimeSummary`, plumbed in by the binary; the active default and the rollback target carry markers) and runs the `rocm runtimes` verbs: a read-only `list` refresh, and approval-gated activate, rollback, uninstall (which adds `--yes`), adopt (folder browser, argv from `adopt_args` in [`exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs)) and import (typed manifest path). One job id per verb. -- [`ui/serve_wizard.rs`](../crates/rocm-dash-tui/src/ui/serve_wizard.rs) — the Serve form. The default form is Model, an `Advanced settings` row and Launch; engine (`ENGINES`), host, port and managed/foreground sit behind the row, so the default invocation is exactly `rocm serve MODEL` and the CLI stays the authority for engine, GPU-required policy, host, port and managed mode. The model is typed, picked from [`model_picker.rs`](../crates/rocm-dash-tui/src/ui/model_picker.rs) (which fills only the id) or chosen as a local path in [`folder_browser.rs`](../crates/rocm-dash-tui/src/ui/folder_browser.rs). The host is limited to the loopback spellings in `LOOPBACK_HOSTS` and a custom host needs a custom port; a public bind is refused with a message pointing at the CLI's `--allow-public-bind`. Launch stages a `PendingServe` approval, then starts job `serve-`; a second launch of a model whose job is still running is refused with a message (the job id replaces every non-alphanumeric character in the model name with `-`, so names that differ only in punctuation share one). Unmanaged launches add `--foreground`. Its `is_loopback_host` accepts only the exact spellings in `LOOPBACK_HOSTS`, which is not the same function as the one in [`llm.rs`](../crates/rocm-dash-tui/src/llm.rs): that one decides whether to strip gateway credentials and also accepts any `127.*` address. -- [`ui/services_manager.rs`](../crates/rocm-dash-tui/src/ui/services_manager.rs) — lists the instances the daemon surfaces (`service_rows`, sorted by id: model, port, status, live generation throughput with a held-value marker) and stops or restarts one through an approval that runs `rocm services stop|restart --yes` as job `svc--`. It also shows a one-line note, from `AppState::services_past_attempts`, that records of servers no longer running exist and `rocm services list --all` shows them. -- [`ui/update_manager.rs`](../crates/rocm-dash-tui/src/ui/update_manager.rs) — wraps `rocm update` in four actions: check and `--apply --dry-run` preview start directly; `--apply` and `--apply --activate` go through approval. One job id per action. - -The remaining `ui/` files that are not overlays or tabs: - -- [`ui/core_bars.rs`](../crates/rocm-dash-tui/src/ui/core_bars.rs) — `CoreBars`, one braille column per CPU core filled from the bottom by utilization; cores that do not fit are dropped from the right edge. Used only by the Hardware panel. -- [`ui/dock.rs`](../crates/rocm-dash-tui/src/ui/dock.rs) — the rails of the wide layout, used when the terminal is at least `WIDE_COLS` x `WIDE_ROWS` (180 x 45; below that the dashboard stays single-column). `gpu_wall` is the left rail (`RAIL_W` 40): one instrument card per GPU from the latest snapshot. `draw_right_dock` is the right rail (`DOCK_W` 52): `logs_dock` (the recent output of every job in `AppState::jobs`, sorted by job id, scrolled by `dock_logs_scroll`) on the Observe, ROCm and Serving tabs, and `context_rail` (running services, GPU state, recent tools) on Home and Chat. Both rails are read-only; `ui/mod.rs`'s `wide_triptych` places them. -- [`ui/folder_browser.rs`](../crates/rocm-dash-tui/src/ui/folder_browser.rs) — the directory picker shared by the serve, install, runtime and onboarding screens: entries for use-current, new child, parent and sub-directories, with only `build_entries` touching the filesystem (an unreadable directory yields no children), and a `FolderOutcome` of chosen path or cancelled. -- [`ui/format.rs`](../crates/rocm-dash-tui/src/ui/format.rs) — pure value formatters every tab uses: memory in MiB promoted to GiB and TiB (`mib`, `mib_pair`, which never prints `1024.0`), `pct`, `si`, `bps`, `watts`, `celsius`, `mhz`, `duration`, and `-` or an em dash for missing values. The `*_cell` and `*_compact` variants (`gen_tps_cell`, `latency_cell`, `tokens_per_watt_cell`, ...) take the observation metadata and append `HELD_MARKER` to a value held over from a prior scrape window, with `HELD_LEGEND` for the footer. It also holds small shared list helpers: `running_instances` (serving first, then model and container id), `stage_text` and `overflow_line` (the "...and N more" line). -- [`ui/gradient.rs`](../crates/rocm-dash-tui/src/ui/gradient.rs) — `GradientGauge`, a horizontal gauge whose filled cells take their background from a three-stop ramp (ok, warn, err by default) across the bar's width, with the fill length tracking the ratio; and `lerp3_t`, the three-stop interpolation that [`sparkline.rs`](../crates/rocm-dash-tui/src/ui/sparkline.rs), [`core_bars.rs`](../crates/rocm-dash-tui/src/ui/core_bars.rs) and the menu's logo reuse. -- [`ui/launcher.rs`](../crates/rocm-dash-tui/src/ui/launcher.rs) — the bare-`rocm` front door, a synchronous screen with its own blocking key-read loop, not the dashboard's async event loop. `run_launcher` takes the running instances the binary read from the registry, shows a status strip over the menu (`ROWS`: set up, serve, diagnose and fix, chat, open the full dashboard, plus a display-only "Optimize a model" row with a `soon` badge) and returns a `LauncherChoice`, or `None` on quit. `apps/rocm`'s `dash.rs` (`launcher_route`) turns the choice into a focused host (Set up, Serve and Diagnose each open one overlay through `ui::draw_focused` and `app/focus.rs`), the chat, or the full dashboard. Quit goes through the same quit-confirm gate as the dashboard, with a `StaticManagedRegistrySnapshot` built from the instances it was given. -- [`ui/model_picker.rs`](../crates/rocm-dash-tui/src/ui/model_picker.rs) — a filterable list of model recipes for the Serve form: case-insensitive substring match over id and aliases, and a `PickerOutcome` of chosen, cancelled or none. `ModelRecipeSummary` is a flattened copy of the recipe fields it shows, built by `apps/rocm`'s `dash.rs` so the crate needs no `rocm-core`. It displays each recipe's `preferred_engine`; choosing one fills only the model id. -- [`ui/sparkline.rs`](../crates/rocm-dash-tui/src/ui/sparkline.rs) — `BrailleSparkline`, a history graph that packs two samples into each character column at four dot rows per cell, right-aligned so the newest samples show, optionally colored per column by the larger of its two samples. Used by Home, Observe, Hardware, Bench, the dock and the theme preview. - -The five tabs are drawn by `ui/mod.rs`'s `draw` into the folder-tab panel from [`tabs/mod.rs`](../crates/rocm-dash-tui/src/ui/tabs/mod.rs); the tabs only read `AppState` while drawing, except the Chat tab, which writes its measured scroll bounds back (`chat_max_scroll`, `chat_scroll`, `chat_follow`). The tabs list keeps `mod.rs` first, then the tabs alphabetically: - -- [`ui/tabs/mod.rs`](../crates/rocm-dash-tui/src/ui/tabs/mod.rs) — declares the tab modules and `TAB_LABELS` (Home 1, ROCm 2, Serving 3, Observe 4, Chat 5), and draws the outlined folder-tab panel (`draw_tab_panel`). `outlined_chip_spans` is the single source of tab geometry: the painter and `compute_chip_layout`, which `app/actions.rs` uses to turn a click into a tab, both go through it so they cannot drift. -- [`ui/tabs/bench.rs`](../crates/rocm-dash-tui/src/ui/tabs/bench.rs) — the Observe tab's benchmark panel: Pass^N and Pass@N rollups (`rollup_pass_n` from `rocm-dash-core`), a scrollable table of `AppState::bench_rows` with a pass/fail verdict per row, and a sparkline. With no rows it shows the `rocm bench load` command and the key that opens the bench-run form. -- [`ui/tabs/chat.rs`](../crates/rocm-dash-tui/src/ui/tabs/chat.rs) — the Chat tab's view of state the `app/` modules own. Until `chat_consent` is `Accepted` it shows the consent gate (the detected or configured endpoint, and the key to detect a local engine); afterwards a transcript that follows the tail until the user scrolls away (`ChatViewport`) over a three-row input line. While a reply is pending the input shows a static waiting line (a braille glyph with the wait reason, or "waiting for the agent"), and when the endpoint is a loopback address that matches a known instance (`chat_backend_wait_reason`, using `llm.rs`'s parsing) it says whether that model is still starting, stopped or in error. -- [`ui/tabs/hardware.rs`](../crates/rocm-dash-tui/src/ui/tabs/hardware.rs) — the Observe tab's host and GPU panel: CPU (aggregate sparkline plus per-core bars), memory and swap gauges, a disk and network throughput row, then one block per GPU. `plan_gpu_rows` chooses full bordered panels when every GPU fits at `FULL_PANEL_MIN_H` rows, otherwise one compact line per GPU, which scrolls (`scroll_to_show`) and reserves an overflow row only when the GPUs outnumber the rows. Shows "waiting for first snapshot" until a snapshot arrives. -- [`ui/tabs/home.rs`](../crates/rocm-dash-tui/src/ui/tabs/home.rs) — the landing view, three bands: a hero GPU gauge and sparkline with a VRAM, temperature and power cluster; Running, Health and Updates tiles (Updates reads the background update check's `UpdateStatus`); and an Activity feed of running services and recent jobs. Missing telemetry shows a placeholder with a hint at what would produce it, never a synthetic number, and the hero title keeps "Detecting GPU..." and "Unknown GPU" distinct. -- [`ui/tabs/observe.rs`](../crates/rocm-dash-tui/src/ui/tabs/observe.rs) — the serving-telemetry tab, stacked top to bottom: a hero band (node efficiency in tokens per watt with a trend, and node throughput with total power), the per-instance table (`tabs/instances.rs`), the Hardware panel and the Bench panel. A one-line banner shows when the daemon connection or the first snapshot is missing; simulated sessions are marked by the header chip, not here. -- [`ui/tabs/pane.rs`](../crates/rocm-dash-tui/src/ui/tabs/pane.rs) — the shared renderer for the ROCm and Serving tabs: an Actions list (46%) beside a `Details: ` pane (54%), from a `Verb` table (icon, label, `KeyAction`, summary, steps, underlying command, read-only flag, optional badge). `draw`, `hit_test` and `actions_rect` share one column split, so clicks resolve against what was painted. `live_lines` adds live data from the latest snapshot and `AppState::runtimes` to the Details pane for the install, engine, serve and services verbs only (for example the ROCm and driver versions, registered runtimes and running instances) and returns nothing for the others. -- [`ui/tabs/rocm.rs`](../crates/rocm-dash-tui/src/ui/tabs/rocm.rs) — the ROCm tab's verb table (`VERBS`): install, check for updates, diagnose and fix, runtimes, command runner, and a display-only Uninstall row (`KeyAction::Nothing`; the CLI does it). Each actionable row maps to a `KeyAction::Open*` for the overlay of the same name; rendering and hit-testing are in `pane.rs`. -- [`ui/tabs/serving.rs`](../crates/rocm-dash-tui/src/ui/tabs/serving.rs) — the Serving tab's verb table: serve a model, engines, running instances and services, providers and keys (the config manager), logs (marked read-only), and a display-only "Optimize a model" row with a `soon` badge. - -The other three dashboard crates each have a crate-level bullet, followed by a bullet for each source file the crate-level bullet does not already name: - -- [`rocm-dash-collectors`](../crates/rocm-dash-collectors/src/lib.rs) — the IO-heavy collector implementations behind `rocm-dash-core`'s traits (amd-smi, Docker, host metrics, Lemonade and vLLM scrapers, and on Windows the [`winperf.rs`](../crates/rocm-dash-collectors/src/winperf.rs) perf-counter/ADLX GPU collector) plus the benchmark load generator; used by `rocm-dash-daemon` and, on Windows, by `rocm-dash-tui` in-process. - - [`amd_smi.rs`](../crates/rocm-dash-collectors/src/amd_smi.rs) — the amd-smi collector. `AmdSmiCollector::detect_with_binary` returns `Some` only when a pre-flight passes and `amd-smi version` answers in time; its async methods (`metrics`, `power_limits`, `processes`, `system_info`) run `amd-smi ... --json` under a timeout with `kill_on_drop` and pass the output to pure parsers (`parse_metrics`, `parse_power_limits`, `parse_processes`, `parse_system_info`) that tolerate differences between amd-smi releases and return an empty or default value for a shape they do not recognise. The pre-flight exists because amd-smi can block in uninterruptible kernel sleep on a host with no readable `/dev/kfd`: unless the caller says the GPU is already known to be reachable without one (a verdict `apps/rocm` computes once, true only on WSL with a usable GPU, and hands to the daemon through `RunnerOptions`), it runs `rocm_core::device_readable_bounded` on the blocking pool. `detect_with_binary_skipping_device_preflight` exists for tests that point at a fake script. - - [`bench_load.rs`](../crates/rocm-dash-collectors/src/bench_load.rs) — the concurrency-sweep load generator behind `rocm bench load`, reached through `rocm_dash_daemon::bench_load`. `run_cell` sends `LoadSpec.requests` chat-completion requests at one concurrency and returns a `CellReport`: the `BenchmarkRow` plus attempted, succeeded and failed counts, the first error and an optional `EngineSplitNotice`. `run_and_append_csv` and `run_auto_ramp` (which walks `RAMP_SEQUENCE` and stops after the last level, on a throughput plateau against the previous cell, or when the queue is backed up, `should_stop_ramp`) append each cell to a CSV, taking an exclusive file lock for each row, and refuse a file whose first line differs from `CSV_HEADER` when the first row is appended. During a cell it scrapes the endpoint's Prometheus `/metrics` with a short timeout and sets the row's `engine` only when the scrape is recognisably vLLM; because `engine` is a rollup key, appending a row that carries an `engine` to a file that already holds blank-`engine` rows for that cell is reported, once per sweep, through `EngineSplitNotice` for the CLI to print, not printed here. - - [`bench_tail.rs`](../crates/rocm-dash-collectors/src/bench_tail.rs) — `CsvBenchTailer`, the `BenchTailer` the daemon runner uses on the configured benchmark CSV. Each `drain()` re-reads the whole file and returns only the rows past the count it has already returned, resets that count (and so re-emits every row) only when the file now has fewer rows than before, so a rewrite that is not shorter goes undetected, and returns nothing while the file does not exist; a row that fails to parse makes that drain return an error. Re-reading avoids tracking offsets and inodes, which is affordable because benchmark CSVs are small. - - [`cgroup.rs`](../crates/rocm-dash-collectors/src/cgroup.rs) — attributing GPU processes to containers. `parse_container_id_from_cgroup` is a pure scan of `/proc//cgroup` text for the first run of exactly 64 lowercase hex characters (cgroup v1, v2 and containerd layouts), `container_id_for_pid` reads that file (Linux only; a stub returns `None` elsewhere) and `is_container_id` tests the shape. amd-smi reports host PIDs and a tensor-parallel server's workers are descendants of the container's init process, so the join goes through the cgroup and not through PID equality; a managed `rocm serve` service id never has this shape, so such a service can never be a key of the per-container VRAM map. - - [`docker.rs`](../crates/rocm-dash-collectors/src/docker.rs) — `DockerDiscovery`, discovery through `bollard`. `detect` returns `Some` only when the local Docker daemon answers a ping within two seconds; `discover_async` lists running containers whose image matches the glob-style patterns (default `vllm/*` and `rocm/vllm*`, `*` being the only wildcard) and inspects each under a timeout; `parse_container` builds the `DiscoveredService` from the container's environment and command line: GPU ids from `HIP_VISIBLE_DEVICES` (unless it is empty or `all`), else the first non-empty of `AMD_VISIBLE_DEVICES`, `ROCR_VISIBLE_DEVICES` and `CUDA_VISIBLE_DEVICES`, tensor-parallel size, dtype, quantization (falling back to `--dtype`), model name and a published host port taken from an unordered map of bindings (so with several published ports which one is used is arbitrary; default 8000). Docker gives no readiness signal, so a discovered container is `InstanceStatus::Starting` with no phase. The sync `ServiceDiscovery::discover` returns `Unsupported`. - - [`engine_registry.rs`](../crates/rocm-dash-collectors/src/engine_registry.rs) — `EngineKind` (`Vllm`, `Lemonade`) maps an engine to its label, conventional port and sample parser: `label` and `from_label` (case-insensitive), `default_port` (a fallback only; a managed service's port comes from its registry record) and `parse_sample`, which dispatches to `vllm_prom::parse` or `lemonade::parse_stats`. In production only `label` and `from_label` are called: the daemon's `registry.rs` reaches `from_label` through `engine_kind_for` to leave managed records that are not vLLM out of the vLLM scrape, and `bench_load.rs` takes the `vllm` label so the CSV `engine` column cannot drift from the registry's spelling. `default_port` and `parse_sample` are exercised only by tests, since the runner builds its collectors directly. - - [`host.rs`](../crates/rocm-dash-collectors/src/host.rs) — `HostCollector`, CPU (overall and per core), memory and swap from `sysinfo`, sampled once per tick into `SystemMetrics`; the constructor primes the CPU counters because the first reading is meaningless. Disk and network rates are not collected yet and are always reported as zero. It is cross-platform, and `rocm-dash-tui` also runs it in-process on Windows, where there is no daemon socket. - - [`lemonade.rs`](../crates/rocm-dash-collectors/src/lemonade.rs) — the Lemonade Server collector. The parsers are pure: `parse_stats` maps `/api/v1/stats` `tokens_per_second` to `gen_tps` (Lemonade reports a rate, not a counter, and no KV-cache or request-queue figures) and `parse_health_model` reads the loaded model name from `/api/v1/health`; a body that is not a JSON object parses as empty. `LemonadeCollector::discover` builds a `DiscoveredService` (synthetic `lemonade--` id, status `Ready`) only when `/api/v1/health` answers, and `LEMONADE_PORT` (13305) is the fallback port. The daemon runs it only when `RunnerOptions::enable_lemonade` is set; it defaults to false and the embedded daemon that `rocm dash` starts leaves it off. - - [`parallel.rs`](../crates/rocm-dash-collectors/src/parallel.rs) — `parallel_scrape`, which runs an async closure against every target concurrently on a `JoinSet` and returns `(target, result)` pairs in completion order, not input order, leaving out a task that panics; the daemon runner uses it for the per-instance vLLM `/metrics` scrapes. - - [`vllm_prom.rs`](../crates/rocm-dash-collectors/src/vllm_prom.rs) — the vLLM `/metrics` scraper. `VllmPrometheusCollector::fetch_async` GETs `http://:/metrics` for a service's port and `parse` (crate-private; reached through `EngineKind::parse_sample` and by `bench_load.rs`) reads the running and waiting request gauges, KV-cache usage (rescaled from 0..1 to 0..100) and the cumulative generation-token counter and TTFT and TPOT histogram sums and counts, each from the first matching sample line (label sets are not summed). It leaves `gen_tps` empty because vLLM uses the counter path: the runner differences the counters into rates. The sync `InstanceMetrics::fetch` returns `Unsupported`. -- [`rocm-dash-core`](../crates/rocm-dash-core/src/lib.rs) — pure types, traits, schemas and the reducer, with no rendering dependencies. [`chat_template.rs`](../crates/rocm-dash-core/src/chat_template.rs) also holds the chat-template defaults a locally served model needs on a chat request (`local_model_should_disable_thinking`), kept here as the leaf crate both front ends already depend on so that `apps/rocm`'s [`providers/wire.rs`](../apps/rocm/src/providers/wire.rs) and the TUI's [`agent/clients.rs`](../crates/rocm-dash-tui/src/agent/clients.rs) cannot drift apart on it. - - [`bench_rollup.rs`](../crates/rocm-dash-core/src/bench_rollup.rs) — Pass^N / Pass@N rollups: `rollup_pass_n` groups rows into trial sets keyed by `(cell, model, engine, tp, dtype, concurrency)` and returns one `PassNRollup` per group, sorted by that key, with a strict verdict (all N trials passed), a lenient one (at least one passed) and mean prompt and generation throughput; `row_verdict` falls back from `pass_fail` to the judge verdict when the rollup is `Unknown`. Because `engine` is in the key, rows with a blank `engine` do not group with rows that have one. It is pure, and the Bench tab ([`ui/tabs/bench.rs`](../crates/rocm-dash-tui/src/ui/tabs/bench.rs)) and the agent's telemetry helpers ([`agent/snapshot.rs`](../crates/rocm-dash-tui/src/agent/snapshot.rs)) recompute it from the rows rather than reading the CSV's `pass_n_of_n` and `pass_at_n` columns. - - [`bench_schema.rs`](../crates/rocm-dash-core/src/bench_schema.rs) — `BenchmarkRow`, the one row type for a benchmark result (identity, platform, backend configuration, request statistics, throughput, latency, quality, rollup and provenance columns), and `PassFail`. Almost every field is an `Option` and the struct is `#[serde(default)]`, so a CSV or a recording that omits columns still deserializes. `CsvBenchTailer` deserializes CSV rows into it, `bench_load.rs` builds it, and the daemon forwards it in `Event::BenchmarkRowsAppended`. - - [`config.rs`](../crates/rocm-dash-core/src/config.rs) — the standalone dashboard configuration read from `/rocm-dash/config.toml` (`default_config_path`; a missing file means defaults and `Config::load` fails only on a read or parse error): `Config` with `DaemonConfig` (listen address, token, tick intervals, benchmark CSV path), `TuiConfig` (connect address, theme, chat endpoint, model and auth-header name) and per-engine `EngineConfig`. It is separate from the unified `rocm` configuration (the `dashboard` section of `rocm-core`'s `RocmCliConfig`, which `rocm dash` reads); in the tree only the TUI's chat-endpoint save (`persist_chat_endpoint` in [`app/chat.rs`](../crates/rocm-dash-tui/src/app/chat.rs)) loads and writes this file. Its default socket path (`$XDG_RUNTIME_DIR`, then `~/.rocm/data/telemetry`, then a user-named directory under the temp dir) is a copy of `rocm-core`'s on purpose, because this crate may have no first-party dependencies (`cargo xtask check-crate-edges` enforces that). - - [`efficiency.rs`](../crates/rocm-dash-core/src/efficiency.rs) — the pure join of throughput and power. `normalize_gpu_id` strips the `gpu-` prefix so the bare indices Docker discovery records in `Instance.gpu_ids` match amd-smi's `gpu-N` device ids; `attribute_power_w` splits each GPU's board power among the instances that occupy it, weighted by per-container VRAM, equally when any occupant has no reading, and yields `None` for an instance none of whose GPUs reported a positive power reading; `tokens_per_watt` divides generation throughput by that attributed power. `node_efficiency` returns the whole-node figure as a `NodeEfficiency` (Σ `gen_tps` over Σ board power, including GPUs no instance occupies) with a `held` flag that is set when any throughput behind it is held; it is the one implementation behind the Observe efficiency hero and its trend, the Hardware header, and the assistant's `tokens_per_watt` tool (the Home tab's tokens-per-watt figure is a separate sum of per-instance values). The daemon runner calls `attribute_power_w`, `tokens_per_watt` and `gpu_ids_overlap`, which it uses to warn when the id join finds nothing. - - [`metrics.rs`](../crates/rocm-dash-core/src/metrics.rs) — the live metric types every other dashboard crate shares: `Snapshot` (one tick: `SystemMetrics`, a `GpuMetrics` per GPU, an optional `GpuSystemInfo`, the `Instance` list and warnings), `Instance` with its `InstanceStatus` (`Starting` carries an optional `StartupPhase`; `is_serving`, `is_starting`, `counts_as_running` and `label` are the one definition of those predicates and chip labels) and `ObservationMetadata`/`ObservationFreshness`, which mark a throughput or latency value as freshly measured or held over from an earlier scrape. The optional fields added after the first recordings (`power_limit_w`, `gen_tps`, `tokens_per_watt`, `power_w`, `ttft_ms`, `tpot_ms` and the three `*_observation` fields) are `#[serde(default)]`, so older recordings still deserialize. - - [`observation.rs`](../crates/rocm-dash-core/src/observation.rs) — how a generation-throughput counter becomes a rate that stays honest. `GenerationObservationTracker` keeps a bounded window of counter samples, computes a rate over `rate_window(instance_tick)` (`clamp(5 x tick, 10 s, 30 s)`), reports the value as fresh or held for up to `observation_validity(instance_tick)` (`clamp(3 x tick, 6 s, 30 s)`), clears on a counter reset or on expiry, and accepts a rate an engine reports directly through `observe_direct`. All time is passed in, so the module reads no clock. The runner keeps one tracker per instance for throughput and one each for TTFT and TPOT; it drops them when a service is retired and calls `invalidate` when a service's port changes under the same id. - - [`partition.rs`](../crates/rocm-dash-core/src/partition.rs) — the `ComputePartitionMode` (`Spx`, `Dpx`, `Qpx`, `Cpx`) and `MemoryPartitionMode` (`Nps1`, `Nps2`, `Nps4`) enums, each defaulting to `Unknown` and serialized in upper case. `GpuSystemInfo` in `metrics.rs` holds them and `amd_smi.rs` parses them from amd-smi output. - - [`persist.rs`](../crates/rocm-dash-core/src/persist.rs) — `PersistedEntry`, one recorded `Event` plus its `ts_us` (microseconds since the epoch): the daemon stamps wall-clock time, the demo generator a fixed synthetic one. The daemon's [`persist.rs`](../crates/rocm-dash-daemon/src/persist.rs) writes one per NDJSON line, the demo generator emits the same format, and the TUI's [`replay.rs`](../crates/rocm-dash-tui/src/replay.rs) reads them back and paces playback by the `ts_us` gaps, each capped at 2 s and then divided by the playback speed. - - [`protocol.rs`](../crates/rocm-dash-core/src/protocol.rs) — the NDJSON wire protocol between the daemon and a TUI client: `Command` (client to daemon: `Hello`, `Subscribe`, `RequestSnapshot`, `RescanInstances`, `Pause`, `Resume`, `Goodbye`) and `Event` (daemon to client: `Welcome`, `Snapshot`, `InstanceDiscovered`, `InstanceGone`, `BenchmarkRowsAppended`, `Warning`, `Error`, `Bye`), both internally tagged with `kind`, and `PROTOCOL_VERSION`, which is bumped when the JSON shape of an existing variant changes. Internal tagging rejects a newtype variant that wraps a sequence, so every `Event` variant is a struct variant or wraps a struct, and a test round-trips each variant to hold that. - - [`state.rs`](../crates/rocm-dash-core/src/state.rs) — the pure reducer, `State::apply(StateEvent) -> Vec`, holding the latest snapshot, a bounded history (`SNAPSHOT_RING_CAP`), instances keyed by container id, bounded benchmark rows (`BENCH_RING_CAP`), the paused flag and the background-job table (`JobState`/`JobStatus`, output bounded by `JOB_OUTPUT_RING_CAP`), with no tokio or ratatui types. `JobStatus::glyph`, `label` and `legend_glyphs` are the one definition of how a job status is drawn. It has two kinds of user: the daemon runner applies `Tick`, `InstanceUpserted`, `InstanceRemoved` and `BenchmarkRows`, discards the returned effects and reads back only the instance map, and the TUI keeps one `State` for all of its jobs, `AppState::jobs`: `app/event_loop.rs` passes `&mut state.jobs` to the key handler of every screen that runs `rocm` commands (for example [`ui/update_manager.rs`](../crates/rocm-dash-tui/src/ui/update_manager.rs) and [`ui/runtime_manager.rs`](../crates/rocm-dash-tui/src/ui/runtime_manager.rs)), applies the job events that come back from [`jobs.rs`](../crates/rocm-dash-tui/src/jobs.rs) to that same instance, and runs the `SideEffect::SpawnJob`s the handlers return through `jobs.rs`. The table outlives any one overlay: closing a screen leaves its jobs in it. Only `SpawnJob` is interpreted: the `Persist` and `Broadcast*` effects are produced but nothing consumes them. - - [`traits.rs`](../crates/rocm-dash-core/src/traits.rs) — the collector-side contracts and the data they exchange: `DiscoveredService` (a found serving process or container), `InstanceSample` (one scrape's KV-cache usage, request counts, cumulative token counter and latency-histogram sums, or a rate the engine reports directly), `GpuProcess`, `CollectorError`, and `merge_instance`, which turns a service, a sample and VRAM figures into an `Instance`, copying a directly reported `gen_tps` and leaving `tokens_per_watt`, `power_w`, TTFT, TPOT and the freshness fields `None` for the runner to fill. The traits are synchronous, and the runner calls only `BenchTailer::drain`, on a concrete `CsvBenchTailer`; the Docker and vLLM-Prometheus implementations of `ServiceDiscovery` and `InstanceMetrics` return `CollectorError::Unsupported`, because their real API is the async inherent methods `discover_async` and `fetch_async`. - - [`vram.rs`](../crates/rocm-dash-core/src/vram.rs) — the pure VRAM attribution maths. `aggregate_process_vram` folds per-process readings into a per-container map through an injected PID-to-container resolver (the runner passes `cgroup::container_id_for_pid`), and `resolve_instance_vram` returns an instance's `(used, total)`: the per-container figure when there is one, otherwise the device-summed used over its GPUs, with `total` always device-summed and `(0, 0)` for an instance with no map entry and no matching GPU. It reuses `efficiency.rs`'s id matching and does no `/proc` or process I/O. -- [`rocm-dash-daemon`](../crates/rocm-dash-daemon/src/lib.rs) — the daemon library: [`runner.rs`](../crates/rocm-dash-daemon/src/runner.rs) drives the collectors on tick cadences and broadcasts snapshots, and [`server.rs`](../crates/rocm-dash-daemon/src/server.rs) streams them to TUI clients as NDJSON. [`registry.rs`](../crates/rocm-dash-daemon/src/registry.rs) reads the managed-service records `rocm serve` writes and tells a registry that is confirmed empty (no directory, or no records) from one that could not be read: the run loop retires a managed service that an empty registry lacks, but when a pass cannot read the registry in full (a directory that cannot be listed, or a record file that cannot be opened) it retires nothing: the known services and their data stay, as when Docker discovery errors, the records that did read still add and refresh their services, and the header warns until a read succeeds. `apps/rocm`'s [`dash.rs`](../apps/rocm/src/dash.rs) drives it. - - [`bench_ring.rs`](../crates/rocm-dash-daemon/src/bench_ring.rs) and [`snapshot_ring.rs`](../crates/rocm-dash-daemon/src/snapshot_ring.rs) — the daemon's two bounded histories for late-joining clients, `BenchRing` (200 rows) and `SnapshotRing` (30 snapshots), each a `VecDeque` that drops its oldest entry when full. On `Command::Subscribe`, `server.rs` replays the snapshot ring one `Snapshot` event at a time, then the benchmark ring as a single `BenchmarkRowsAppended` event (if it holds any rows), to that client before it sends live events. - - [`demo.rs`](../crates/rocm-dash-daemon/src/demo.rs) — the synthetic-session generator behind `rocm dash --demo`. `generate_to_writer` and `generate_file` write a recording as `PersistedEntry` lines (a `Welcome`, one `Snapshot` per simulated second, the instance discoveries on the first tick, scheduled benchmark rows and a closing `Bye`) of an 8-GPU node serving three vLLM containers, so the dashboard replays populated data with no GPU and no daemon. The same `DemoOptions` (seconds and seed) produce byte-identical output, from seeded jitter and a fixed wall-clock anchor; the file is created `0o600` on Unix (an existing file keeps its mode) and removed again if generation fails. - - [`persist.rs`](../crates/rocm-dash-daemon/src/persist.rs) — `SessionWriter`, the append-only session recorder. `server.rs` opens one `session-YYYYMMDD-HHMMSS.ndjson` for the daemon's lifetime when `RunnerOptions::persist_dir` is set, which `rocm dash` always does, to the `telemetry` directory under the data dir; if the file cannot be created, persistence is switched off with a warning. Every broadcast `Event` is appended as a `PersistedEntry` line and flushed to the OS (there is no fsync, and a failed write is logged and skipped), so a process crash loses at most the in-flight tick. There is no rotation or compression; the TUI's replay mode reads the file. - - [`transport.rs`](../crates/rocm-dash-daemon/src/transport.rs) — NDJSON framing for the daemon's socket: `write_line` serializes a value as one JSON line and flushes, `read_line` reads one line and returns `None` at end of input. [`rocm-dash-tui/src/transport.rs`](../crates/rocm-dash-tui/src/transport.rs) is a copy of it, because the TUI does not depend on the daemon crate, so a framing change must be made in both. +The library every first-party app and engine crate depends on. It holds host examination and diagnosis (`examine`, `host_gpu`, `diagnose`, `fix`), managed runtimes and service records, and the process, file, download and quoting primitives the binaries share. + +| File | Responsibility | Class | +| --- | --- | --- | +| [`lib.rs`](../crates/rocm-core/src/lib.rs) | Crate root: module declarations, the crate-root re-exports, and the small cross-crate primitives listed under Boundaries plus `unix_time_millis` and `require_nonempty`. | flat | +| [`amd_smi.rs`](../crates/rocm-core/src/amd_smi.rs) | Locates the `amd-smi` binary (newest managed SDK runtime first, then legacy locations, then `PATH`) and launches it through `amd_smi_json` after the `/dev/kfd` pre-flight. It reads the managed-runtime registry records from [`managed_runtime.rs`](../crates/rocm-core/src/managed_runtime.rs), the data and home directory lookups, `has_usable_amd_gpu`, `host_path` and `is_wsl_host`, and the spawn goes through [`process.rs`](../crates/rocm-core/src/process.rs)'s `run_with_timeout`. | domain | +| [`anthropic_endpoint.rs`](../crates/rocm-core/src/anthropic_endpoint.rs) | The Anthropic-compatible `/v1/messages` surface of a managed service: `AnthropicEndpointMode`, its state-file keys, and the readiness check and wait on the published proxy endpoint. | domain | +| [`archive_props.rs`](../crates/rocm-core/src/archive_props.rs) | Property-test generator and on-disk oracle for the archive extractors: nothing written outside the extraction root, no escaping links, no unsafe mode bits. | flat | +| [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs) | `write_file_atomically`: stages the bytes in a unique sibling temp file and publishes it over the destination in one step: durable as well as atomic, since the temp file is flushed before it is published and, on Unix, the directory after it; on Unix it keeps the replaced file's permission bits, and `write_file_atomically` replaces a symlink's target rather than the link. | domain | +| [`automation.rs`](../crates/rocm-core/src/automation.rs) | Automation-daemon runtime state and its JSONL event, audit and proposal stores, with each store's rotation and compaction policy. | domain | +| [`binary_paths.rs`](../crates/rocm-core/src/binary_paths.rs) | Locates the `rocm-engine-` sibling binaries and the `rocm` CLI binary itself. | domain | +| [`browser.rs`](../crates/rocm-core/src/browser.rs) | Hands a URL to the user's browser behind the `Opener` trait, so tests can replace the opening. | flat | +| [`codex_bridge.rs`](../crates/rocm-core/src/codex_bridge.rs) | The serde DTOs of the `rocmd-codex-bridge-v0` host snapshot, shared so `rocm` and `rocmd` emit the same shape. | domain | +| [`command_capture.rs`](../crates/rocm-core/src/command_capture.rs) | Runs the `rocm` CLI as a child process and captures what it printed (`CommandCapture`, `run_rocm_capture_with_env`, `command_capture_text`). `CommandCapture` is also what [`process/bounded.rs`](../crates/rocm-core/src/process/bounded.rs)'s `run_bounded` returns for the host probes: the lossy text and `exit_status`, the raw bytes of both streams, a typed `CommandOutcome` (not found, spawn failed, timed out, wait failed, exited with a code, killed by a signal) and the status and error text the executor saw; a capture answered without a child is built with `CommandCapture::from_text`. | domain | +| [`config.rs`](../crates/rocm-core/src/config.rs) | The unified `RocmCliConfig` and its sections, including `WatcherMode`, the built-in watcher catalog and the rocm-dash dashboard sub-config with its legacy-TOML migration. | domain | +| [`config_proptests.rs`](../crates/rocm-core/src/config_proptests.rs) | Property tests for the persisted `config.json` (`RocmCliConfig`) and its one-shot migration from the legacy rocm-dash `config.toml`: save and load round trips, and a save that never writes a file load rejects. Each property counts how often the generator reached the edge classes (absent optionals, empty and non-ASCII strings, non-finite floats) and fails a run that never did. Declared from [`config.rs`](../crates/rocm-core/src/config.rs). | flat | +| [`confirm.rs`](../crates/rocm-core/src/confirm.rs) | The shared `[y/N]` prompt (`print_prompt`, `read_answer`), `interactive_terminal`, and the `require_yes_or_interactive` guard for `--yes`-gated commands. | domain | +| [`crypto.rs`](../crates/rocm-core/src/crypto.rs) | Generic RSASSA-PKCS#1 v1.5 over SHA-256 sign and verify, with no external `openssl` process. | domain | +| [`diagnose.rs`](../crates/rocm-core/src/diagnose.rs) | Root of `rocm diagnose`: the public result types, the score thresholds, `diagnose` itself, and the vLLM symptom classifiers that run the whole catalog. | domain | +| [`diagnose/catalog.rs`](../crates/rocm-core/src/diagnose/catalog.rs) | The checker table: which check runs on which platform family and in what order, and how the family is resolved from an `Examination`. | domain | +| [`diagnose/engine.rs`](../crates/rocm-core/src/diagnose/engine.rs) | Engine-runtime checks on Linux and WSL2: vLLM out-of-memory and import failures, a second code object manager, an undersized `/dev/shm`. | domain | +| [`diagnose/host.rs`](../crates/rocm-core/src/diagnose/host.rs) | Host-configuration checks that run on more than one platform: wheel architecture, HSA override, `PATH`, wheel against system ROCm, mixed integrated and discrete GPUs, unsupported GPUs. | domain | +| [`diagnose/linux.rs`](../crates/rocm-core/src/diagnose/linux.rs) | Linux-only checks (kernel and amdgpu module, device-node access, package repositories, repo-native install) and the package-manager command helpers. | domain | +| [`diagnose/report.rs`](../crates/rocm-core/src/diagnose/report.rs) | Upstream routing for a failure nothing recognised (`upstream_route`) and the human-readable report (`render_report_text`). | domain | +| [`diagnose/scoring.rs`](../crates/rocm-core/src/diagnose/scoring.rs) | The keyword tables shared across platforms and the scoring over them, plus helpers that read an `Examination` or build a `Diagnosis`. | domain | +| [`diagnose/test_support.rs`](../crates/rocm-core/src/diagnose/test_support.rs) | Test-only `Examination` builders shared by the tests of several `diagnose` modules. | flat | +| [`diagnose/windows.rs`](../crates/rocm-core/src/diagnose/windows.rs) | Windows-only checks: the HIP SDK, the Adrenalin driver, the Visual C++ runtime and the display driver date. | domain | +| [`diagnose/wsl.rs`](../crates/rocm-core/src/diagnose/wsl.rs) | WSL2-only checks: the DXCore handoff, the ROCDXG userspace, the distro floor, the Windows host driver and WSL 1. | domain | +| [`disk_space.rs`](../crates/rocm-core/src/disk_space.rs) | Free-space preflight checks before large downloads and extractions, and the out-of-space error reporting. | flat | +| [`download.rs`](../crates/rocm-core/src/download.rs) | Streaming file downloads over `ureq` with resume, retry with backoff, and size, length and SHA-256 checks before the file is published. | domain | +| [`endpoint_key.rs`](../crates/rocm-core/src/endpoint_key.rs) | Generates the CSPRNG bearer key that guards a managed service's endpoint and checks that it is header-safe. | domain | +| [`endpoint_readiness.rs`](../crates/rocm-core/src/endpoint_readiness.rs) | How far a managed service's OpenAI-compatible endpoint has come (`EndpointReadiness`), the inference-verified latch the engine adapters share, and model-reference matching. | domain | +| [`examine.rs`](../crates/rocm-core/src/examine.rs) | The `Examination` document behind `rocm examine --json` (the field set the doctor skill's `examine.py` emits, plus a few CLI-only additions) and `Examination::probe`, which runs the probes in order; `Examination::probe_with_summary` probes the host once and hands the examination's kernel release to the summary, so `rocm examine --json` reads the kernel release once. | domain | +| [`examine/framework.rs`](../crates/rocm-core/src/examine/framework.rs) | The PyTorch probe (through the active runtime or `PATH`) and the llama.cpp probe. | domain | +| [`examine/host_env.rs`](../crates/rocm-core/src/examine/host_env.rs) | Host environment probes: OS and distro (with the kernel release read through the summary stack's `detect_kernel_version`), the CPU fields recorded from the shared reader in [`host_gpu/os_facts.rs`](../crates/rocm-core/src/host_gpu/os_facts.rs), tracked environment variables, shared memory, container check and kernel log. | domain | +| [`examine/library_copies.rs`](../crates/rocm-core/src/examine/library_copies.rs) | Finds every copy of the comgr and HIP runtime libraries the loader could pick, and which install owns each. | domain | +| [`examine/linux_driver.rs`](../crates/rocm-core/src/examine/linux_driver.rs) | Linux driver access: kernel modules (loaded or built in), device nodes and who may open them, and Secure Boot. | domain | +| [`examine/linux_gpus.rs`](../crates/rocm-core/src/examine/linux_gpus.rs) | Linux GPU enumeration from `lspci`, `rocminfo`, sysfs and the kernel topology, with the marketing-name and APU classification they share. | domain | +| [`examine/rocm_install_probe.rs`](../crates/rocm-core/src/examine/rocm_install_probe.rs) | How ROCm was installed and which live package-repository files configure it. | domain | +| [`examine/windows.rs`](../crates/rocm-core/src/examine/windows.rs) | Native Windows probes: the GPU query, the HIP SDK, the Adrenalin driver and the MSVC redistributable. | domain | +| [`examine/wsl.rs`](../crates/rocm-core/src/examine/wsl.rs) | The WSL2 guest probe, and the remote probe that reads the same facts from a named distribution when `rocm examine` runs on the Windows host. | domain | +| [`examine_driver_proptests.rs`](../crates/rocm-core/src/examine_driver_proptests.rs) | Property tests for `examine`'s driver-side text readers (WSL distro floor, device-node permissions, modprobe blacklist, `iommu=`) and gfx-family normalisation. | flat | +| [`fake_executable.rs`](../crates/rocm-core/src/fake_executable.rs) | `write_fake_executable`: writes a stand-in script for tests from a short-lived child, so running it does not fail with `ETXTBSY`. It is built into every build, without a `cfg(test)` gate, so dependent crates' tests can call it. | flat | +| [`fix.rs`](../crates/rocm-core/src/fix.rs) | Root of `rocm fix`: the dispatch (`apply`) that plans, confirms and runs a catalog remediation, and the re-exports of its children's public names. | flat | +| [`fix/catalog.rs`](../crates/rocm-core/src/fix/catalog.rs) | The closed remediation catalog: `FixRecipe`, the per-platform class table, `RECIPES`, the lookups by fix-id, and the test-only oracles. | flat | +| [`fix/consent.rs`](../crates/rocm-core/src/fix/consent.rs) | The consent decision and `confirm`, the timeouts the runners use, `current_os`, and output helpers that cannot panic on a closed pipe. | flat | +| [`fix/manifest.rs`](../crates/rocm-core/src/fix/manifest.rs) | The JSON catalog manifest `rocm fix --json` publishes, derived from `RECIPES` on every call. | flat | +| [`fix/options.rs`](../crates/rocm-core/src/fix/options.rs) | The vocabulary of `rocm fix`: the exit codes (`exit`), `FixOptions` and `FixClass`. | flat | +| [`fix/render.rs`](../crates/rocm-core/src/fix/render.rs) | Rendering the catalog for people: the listing, a recipe's plan and verify lines, the flag summary `rocm diagnose` shares, and the refusal of a diagnosis position as a fix-id. | flat | +| [`fix/runners.rs`](../crates/rocm-core/src/fix/runners.rs) | The host-mutating runners, one per auto-applicable fix, each printing the exact change, honouring `--dry-run` and asking consent first. | flat | +| [`foreign_temp_probe.rs`](../crates/rocm-core/src/foreign_temp_probe.rs) | Test probe that a writer publishing through `atomic_write` never touches another writer's temp file; built only for tests and the `test-support` feature. | flat | +| [`gfx_target.rs`](../crates/rocm-core/src/gfx_target.rs) | Pure gfx-target lookups: extracting a gfx token, mapping a target to its TheRock family, the AMD PCI-id and marketing-name tables, and kernel gfx-version decoding. | domain | +| [`gguf.rs`](../crates/rocm-core/src/gguf.rs) | Reads a GGUF model's shape (layers, heads, head width, parameter count, data offset) from its header, never the weights. | domain | +| [`gguf_fit.rs`](../crates/rocm-core/src/gguf_fit.rs) | Pure arithmetic on whether a GGUF model fits in GPU memory at a context size: weights, KV cache, compute buffer and reserve against VRAM. | domain | +| [`gguf_source.rs`](../crates/rocm-core/src/gguf_source.rs) | Where a GGUF header comes from: a local file, or a Hugging Face file read by HTTP range requests. | domain | +| [`hardware_root.rs`](../crates/rocm-core/src/hardware_root.rs) | `host_path`, the root the hardware probes resolve host paths through (a simulated tree in `e2e-test-hooks` builds), and the `/etc/os-release` read. | flat | +| [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) | Root of GPU and host hardware detection: the `ExamineSummary` aggregation and the driver-summary and gfx-target fallback chains behind it. | domain | +| [`host_gpu/capture.rs`](../crates/rocm-core/src/host_gpu/capture.rs) | Runs an optional host tool under a short timeout, trying each spelling of its name, and reads any failure as `None`; the run itself is [`process/bounded.rs`](../crates/rocm-core/src/process/bounded.rs)'s `run_bounded`. | domain | +| [`host_gpu/diagnostics.rs`](../crates/rocm-core/src/host_gpu/diagnostics.rs) | The text `rocm install sdk` prints when it cannot resolve a GPU, including the raw Windows inventory output, whose capture (`capture_diagnostic_command`) also runs on `run_bounded`. | domain | +| [`host_gpu/engine_default.rs`](../crates/rocm-core/src/host_gpu/engine_default.rs) | Which serve engine a host defaults to: the platform fallback and the vLLM preference for the TheRock families served through it. | domain | +| [`host_gpu/gpu_visibility.rs`](../crates/rocm-core/src/host_gpu/gpu_visibility.rs) | Which AMD GPUs this process may use: the usable-index probe and the `HIP_VISIBLE_DEVICES`/`ROCR_VISIBLE_DEVICES` mask arithmetic. | domain | +| [`host_gpu/linux.rs`](../crates/rocm-core/src/host_gpu/linux.rs) | Linux sysfs, KFD and DRM probes: the KFD topology, the DRM ip-discovery gfx target, the amdgpu device and driver version, the primary GPU name. | domain | +| [`host_gpu/os_facts.rs`](../crates/rocm-core/src/host_gpu/os_facts.rs) | Kernel version, distro name, installed RAM, and the CPU model and vendor for the host summary. One reader returns the CPU model and vendor together for both the summary and `Examination::probe`: Linux from `/proc/cpuinfo`, Windows from the CPU row of the system inventory. `detect_kernel_version` is now the only `uname -r` reader; [`examine/host_env.rs`](../crates/rocm-core/src/examine/host_env.rs)'s `probe_os` calls it for the examination's `kernel_release`. | domain | +| [`host_gpu/render.rs`](../crates/rocm-core/src/host_gpu/render.rs) | The `rocm examine` text rendering of an `ExamineSummary`. | domain | +| [`host_gpu/windows_inventory.rs`](../crates/rocm-core/src/host_gpu/windows_inventory.rs) | The Windows display-adapter inventory: the PowerShell queries, their parsers, and assembling one inventory from several sources, including the system query whose CPU row the CPU reader in [`os_facts.rs`](../crates/rocm-core/src/host_gpu/os_facts.rs) takes. | domain | +| [`host_gpu/wsl.rs`](../crates/rocm-core/src/host_gpu/wsl.rs) | WSL detection and the Windows host driver as seen from the guest: the WSL2 signals, the librocdxg chain and the host-driver probes. | domain | +| [`jsonl_store.rs`](../crates/rocm-core/src/jsonl_store.rs) | The generic append-only JSONL store engine: sibling `.lock` file, single-line appends, torn-tail repair, size rotation and tail-first reads. | domain | +| [`log_tail.rs`](../crates/rocm-core/src/log_tail.rs) | The one routine that reads the last lines of a log file (`tail_lines_decoded`, `tail_log_decoded`): seek-bounded, lossy, with plain or console decoding. | flat | +| [`managed_runtime.rs`](../crates/rocm-core/src/managed_runtime.rs) | The TheRock managed-runtime environment: `ManagedRuntimeEnvironment`, the active-runtime lookups, `prepend_runtime_paths`, and the registry and SDK probing behind them. | domain | +| [`model_catalog.rs`](../crates/rocm-core/src/model_catalog.rs) | The curated model catalog: recipe types, the built-in catalog JSON, signed external recipe indexes and artifact cache markers. | domain | +| [`model_readiness.rs`](../crates/rocm-core/src/model_readiness.rs) | Whether a model will run on this host, from its curated recipe and the host's measured GPU and RAM, without fetching weights (`rocm diagnose --model`). | domain | +| [`net.rs`](../crates/rocm-core/src/net.rs) | The default local host and port, URL formatting and parsing, and the hand-rolled loopback HTTP/TCP client the readiness probes use. | domain | +| [`openmpi.rs`](../crates/rocm-core/src/openmpi.rs) | OpenMPI, libatomic and libnuma detection, the `libmpi_cxx` compatibility shim, and the per-library install plans and hints vLLM's ROCm wheels need. | flat | +| [`os_release.rs`](../crates/rocm-core/src/os_release.rs) | The one `/etc/os-release` parser, reading the file as a POSIX shell sourcing it would. | flat | +| [`package_plan.rs`](../crates/rocm-core/src/package_plan.rs) | Distro-generic package install planning: `PackageManager` resolution, the plan types, the root and passwordless-`sudo` checks, and the `apt-get -s` safety helpers. It never executes a plan; the one process it starts is `sudo -n true`, behind `can_autoinstall`. | flat | +| [`paths.rs`](../crates/rocm-core/src/paths.rs) | `AppPaths` (config, data and cache roots and their per-engine and per-service subpaths), the managed-root override and engine plugin directories, and `AppPaths::env_vars`, the three `ROCM_CLI_*_DIR` variables that make a child process run on the same roots, with the constants that name them (`CONFIG_DIR_ENV`, `DATA_DIR_ENV`, `CACHE_DIR_ENV`, `ENGINE_ENVS_ROOT_ENV`). | domain | +| [`persisted_paths_props.rs`](../crates/rocm-core/src/persisted_paths_props.rs) | Property test that `RocmCliConfig::load` and `AppPaths::discover` agree about where the data dir is: a `config.json` that cannot be read makes discovery fail or still find the recorded managed root, never silently fall back to the default data dir. Declared from [`paths.rs`](../crates/rocm-core/src/paths.rs). | flat | +| [`placeholder.rs`](../crates/rocm-core/src/placeholder.rs) | The `` placeholder rendered reports print for an empty value (`empty_as_unknown`, `trimmed_or_unknown`). | domain | +| [`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs) | Subprocess and file-read helpers for the host probes: `run` under a timeout (`run`, `run_with_env` and `run_raw` are thin adapters over [`process/bounded.rs`](../crates/rocm-core/src/process/bounded.rs)'s `run_bounded`; `rc` is `127` when the program cannot be spawned, `124` on a timeout or a failure to wait and `-1` for a child killed by a signal), `which`, `read_text` and `read_host_text`. | domain | +| [`proc_lifecycle.rs`](../crates/rocm-core/src/proc_lifecycle.rs) | Verified, bounded termination of a process by persisted PID, refusing to signal a PID whose start-time identity no longer matches (`terminate_verified`), and the one managed-stop routine built on it that `rocm services stop` and `rocmd`'s `stop_server` both call. `terminate_recorded_service_pids` walks the processes a service record names (supervisor, then engine, each with its own start-time, the stopping process's own PID reported as `self` and never signalled) and returns one `RecordedPidStop` per PID; each caller, on a stop that confirms every one gone, then clears the record's recorded processes with `ManagedServiceRecord::clear_recorded_processes` in [`service_record.rs`](../crates/rocm-core/src/service_record.rs), so a repeated stop reaches no stale PID, and an unconfirmed stop keeps them. `terminate_recorded_pid` terminates one of them. On Windows it first runs `taskkill /T /F` on its descendants, because `terminate_verified` cannot walk a process tree there, and only for a PID that passes the same identity check (`process_start_ticks` is the kernel start-time on Linux and the process creation time on Windows, so a recycled PID is refused before any `taskkill`; a record written before Windows recorded one cannot be refuted). It holds the PID open on Windows from before that check until the stop ends, so the PID cannot be reused in between (a PID that matches but cannot be held is reported unverified and not signalled). A tree kill that did not complete, or did not finish within `MANAGED_STOP_GRACE` (the `taskkill` is killed and reaped at that deadline), is an unconfirmed stop: `descendants_unconfirmed` when the root itself was seen to exit, `timed_out` only when it outlived its deadline. A `taskkill` which found no such process is judged by the root's own re-read, so a root that exited by itself is `exited_before_tree_kill`, which the record-wide settling in `terminate_recorded_service_pids` turns into a stop only when another recorded process (the engine, which is visited as its own role and folded by both callers) is confirmed gone. The `taskkill` starts from the system directory (`GetSystemDirectoryW`, not the `SystemRoot` variable) through `windows_system_tool`. A PID that cannot be queried at all, as against one that is gone, reads as unverifiable unless a readable recorded token differs, in which case that mismatch wins (`ProcessProbe` and `probe_process` in [`process.rs`](../crates/rocm-core/src/process.rs), whose `may_be_running` is the answer for any decision that must not take an unqueryable process for gone). `MANAGED_STOP_GRACE` is the one grace period. The termination is injectable, so a caller's test supplies outcomes it cannot construct and a test of the Windows step runs on every host. | flat | +| [`process.rs`](../crates/rocm-core/src/process.rs) | Process spawn, run and terminate primitives: hidden-console and detached spawn, process-tree termination, `FileLock`, the re-export of the bounded subprocess executor's `run_with_timeout` and `run_bounded`, and `ProcessProbe`/`probe_process`, which tell a PID that is gone from one that cannot be queried (`may_be_running`), and `windows_system_tool`, which resolves a Windows tool from the system directory. | domain | +| [`process/bounded.rs`](../crates/rocm-core/src/process/bounded.rs) | The bounded subprocess executor behind `run_with_timeout` and `run_bounded`, a private child of [`process.rs`](../crates/rocm-core/src/process.rs) that re-exports it: a thread per pipe drains both streams from the moment the child starts, a reader that cannot finish is abandoned after a 200 ms grace rather than joined, and the error for a timeout quotes only a bounded head of the child's output. `run_bounded` returns the run as a `CommandCapture` instead of an `Err`. | domain | +| [`process_tree_properties.rs`](../crates/rocm-core/src/process_tree_properties.rs) | Property tests for the process-tree traversal that decides which PIDs a `KillScope::Tree` stop signals. | flat | +| [`quoting.rs`](../crates/rocm-core/src/quoting.rs) | Quoting whose output must read back as exactly the value given: POSIX shell (`posix_shell_quote`) and PowerShell (`powershell_quote`). | domain | +| [`report.rs`](../crates/rocm-core/src/report.rs) | The content of a Doctor report and the rule that decides whether one may be built at all, with no network or filesystem access. | flat | +| [`report_delivery.rs`](../crates/rocm-core/src/report_delivery.rs) | How a Doctor report leaves the machine: building its link and deciding whether a browser may be started, never sending it. | flat | +| [`report_rollup.rs`](../crates/rocm-core/src/report_rollup.rs) | Counts Doctor reports at every level of `Report::group_key`, keeping refused and unread reports apart. | domain | +| [`report_trend.rs`](../crates/rocm-core/src/report_trend.rs) | Weekly counts of Doctor reports, and the weeks in which a known problem rose sharply. | domain | +| [`rocm_install.rs`](../crates/rocm-core/src/rocm_install.rs) | Discovery of unmanaged ("legacy") ROCm installs: `LegacyRocmSummary`, the install-layout search and version ranking. | domain | +| [`runtime.rs`](../crates/rocm-core/src/runtime.rs) | The host-platform layer: `RuntimePlatform`/`RuntimeHost`, OS-specific executable and Python-environment names, default directories, path helpers and `install_root_has_payload`. | flat | +| [`service_identity.rs`](../crates/rocm-core/src/service_identity.rs) | `ServiceId`, the validator every per-service id should pass before it reaches a path builder, and `generate_service_id` for a new launch. | domain | +| [`service_record.rs`](../crates/rocm-core/src/service_record.rs) | `ManagedServiceRecord`, the on-disk manifest of a managed inference service, and the engine state-file keys that tie it to readiness probing. | domain | +| [`sigpipe.rs`](../crates/rocm-core/src/sigpipe.rs) | `with_sigpipe_ignored`, which turns a write to a pipe whose reader has gone into an ordinary error instead of a signal; `rocm` runs with SIGPIPE at its default action, so the engine stdio client wraps its write to the child, and each write forwarding the child's stderr to its own, in it. Guarded regions may overlap, across threads too; the disposition in force before the first is put back when the last ends. | domain | +| [`terminal.rs`](../crates/rocm-core/src/terminal.rs) | One ECMA-48 walk over untrusted terminal output, and the stripping, line-splitting and quotability decisions built on it. | flat | +| [`test_env.rs`](../crates/rocm-core/src/test_env.rs) | `RestoredEnvVar`: restores a process environment variable on drop, so a panicking test cannot leak it. | flat | +| [`test_support.rs`](../crates/rocm-core/src/test_support.rs) | Test fixtures for throwaway per-test `AppPaths` directories and for seeding the automation audit store. | flat | +| [`user_path.rs`](../crates/rocm-core/src/user_path.rs) | Removes the install directory from the per-user Windows `Path` that [`install.ps1`](../install.ps1) added it to. | flat | +| [`uv.rs`](../crates/rocm-core/src/uv.rs) | Downloads a standalone `uv` into the managed cache, plus the `uv` argument and environment helpers `apps/rocm` and the vLLM engine share. | flat | +| [`vllm_oom.rs`](../crates/rocm-core/src/vllm_oom.rs) | Picks and renders the user's failing vLLM out-of-memory line from a captured log tail, and owns the OOM marker strings. | domain | +| [`windows_driver.rs`](../crates/rocm-core/src/windows_driver.rs) | The Windows AMD display driver's version and date, and the one comparison that judges it old (advice only, not a compatibility check). | domain | + +Boundaries: + +- **Crate-root primitives.** The helpers in [`lib.rs`](../crates/rocm-core/src/lib.rs) stay at the crate root on purpose: each is used from more than one module or crate, and no module's domain owns it. Single sources among them: + - `TORCH_ALIGNMENT_DISABLED_ENV` and `torch_alignment_disabled`: the one read of the torch-alignment opt-out, so its readers cannot disagree. `SDK_TORCH_STACK_PACKAGES` lists the packages the opt-out spares, and both the CLI and the vLLM engine read it. The Lemonade engine does not: its backend alignment has an opt-out of its own, `ROCM_CLI_DISABLE_LEMONADE_BACKEND_ALIGNMENT`, read in [`backend_alignment.rs`](../engines/lemonade/src/backend_alignment.rs). + - `VLLM_GPU_MEMORY_UTILIZATION_HINT`: one wording for the CLI, the vLLM engine and the `fix-16-vllm-oom` diagnosis. + - `command_failure_detail` and `sanitize_component`: the shared failed-subprocess detail rule and the shared slugger for service ids and model cache-marker names. +- **Module fronts and privacy.** + - [`diagnose.rs`](../crates/rocm-core/src/diagnose.rs), [`examine.rs`](../crates/rocm-core/src/examine.rs), [`fix.rs`](../crates/rocm-core/src/fix.rs) and [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) front their directories instead of a `mod.rs`, so existing links and their `rocm_core::` paths keep resolving. + - The private top-level modules are reached through crate-root re-exports so callers keep `rocm_core::` paths; [`package_plan.rs`](../crates/rocm-core/src/package_plan.rs) is re-exported through [`openmpi.rs`](../crates/rocm-core/src/openmpi.rs) to keep `rocm_core::openmpi::` paths, and [`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs) is crate-internal. +- **Failure catalog.** + - `RECIPES` in [`fix/catalog.rs`](../crates/rocm-core/src/fix/catalog.rs) together with the `diagnose/` checkers is the authoritative failure catalog; the `diagnose` tests and the e2e crate hold their own copies to it through the catalog's test-only oracles. + - The platform children of `diagnose/` do not import each other, and [`diagnose/catalog.rs`](../crates/rocm-core/src/diagnose/catalog.rs) is the only module that names every checker. + - In `fix/`, the render and manifest modules read `RECIPES` from the catalog module, which reads neither. +- **Host probing.** + - [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) and [`examine.rs`](../crates/rocm-core/src/examine.rs) are two separate stacks that read some facts twice (the Windows GPU query, the marketing-name table and the subprocess runners); [`host-probing.md`](host-probing.md) proposes which copy of each should survive. Three pairs are converged: the `PATH` lookup between the two stacks ([`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs)'s `which` is the only copy there; other modules walk `PATH` for their own purposes, for example `find_mpirun_path` in [`openmpi.rs`](../crates/rocm-core/src/openmpi.rs) and the executable search in [`runtime.rs`](../crates/rocm-core/src/runtime.rs)), the kernel release ([`host_gpu/os_facts.rs`](../crates/rocm-core/src/host_gpu/os_facts.rs)'s `detect_kernel_version` is now the only `uname -r` reader) and the CPU model ([`host_gpu/os_facts.rs`](../crates/rocm-core/src/host_gpu/os_facts.rs) has one reader per platform for the model and vendor, which `probe_cpu_linux` and `probe_cpu_windows` record and the summary reads). The first step of the subprocess runners is delivered too: `run_bounded` is the executor behind `run`, `capture_optional_command*` and the Windows diagnostic capture. + - [`gfx_target.rs`](../crates/rocm-core/src/gfx_target.rs) is kept out of `host_gpu` so [`managed_runtime.rs`](../crates/rocm-core/src/managed_runtime.rs) reads the TheRock family mapping without importing the host probes. + - Hardware probes resolve host paths through [`hardware_root.rs`](../crates/rocm-core/src/hardware_root.rs)'s `host_path`, which the E2E suite re-roots; [`os_release.rs`](../crates/rocm-core/src/os_release.rs) is the one `/etc/os-release` parser. `hardware_root.rs`'s `real_os_release` is the one reader of the real host's os-release for the callers that build a package-manager plan, and the resolver it passes is private; `read_os_release` itself is `pub` and takes any resolver, which [`examine/host_env.rs`](../crates/rocm-core/src/examine/host_env.rs) and [`host_gpu/os_facts.rs`](../crates/rocm-core/src/host_gpu/os_facts.rs) use with the simulated-root one. Nothing in `rocm-core` stops another caller doing the same; a test in [`system_packages.rs`](../apps/rocm/src/system_packages.rs) keeps `apps/rocm` from naming it. +- **Single sources.** + - [`amd_smi.rs`](../crates/rocm-core/src/amd_smi.rs)'s `amd_smi_json` is the synchronous launch path for `amd-smi`, and the `/dev/kfd` pre-flight runs there; the dashboard collectors run their own pre-flight through the same bounded `rocm_core::device_readable_bounded` probe, over a `rocm-dash-collectors` to `rocm-core` edge that [`crate_edges.rs`](../xtask/src/crate_edges.rs) allows; [`amd_smi_launch_contract.rs`](../xtask/src/amd_smi_launch_contract.rs) fails any unlisted caller of `resolve_amd_smi_binary`. + - [`log_tail.rs`](../crates/rocm-core/src/log_tail.rs) is the only log-tail reader behind every log view, and lives here because `rocmd` cannot depend on `rocm`. + - A new atomic file write goes through [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs); a few older temp-then-rename writers in `apps/rocm` predate it. + - [`runtime.rs`](../crates/rocm-core/src/runtime.rs)'s `runtime_python_env_root_for_executable` and `install_root_has_payload` are the one definitions of those rules. + - [`vllm_oom.rs`](../crates/rocm-core/src/vllm_oom.rs)'s `VLLM_OOM_DETECTED_PREFIX` and `VLLM_OOM_DIAGNOSE_COMMAND` must match byte for byte in the vLLM engine and `apps/rocm`. +- **Dependency direction.** [`automation.rs`](../crates/rocm-core/src/automation.rs) reads `WatcherMode` from [`config.rs`](../crates/rocm-core/src/config.rs), which imports nothing back; the built-in watcher catalog sits beside `WatcherMode` in [`config.rs`](../crates/rocm-core/src/config.rs) to keep it that way. +- **Reader threads.** [`process/bounded.rs`](../crates/rocm-core/src/process/bounded.rs)'s `run_with_timeout` and `run_bounded` abandon a pipe reader that has not finished within a 200 ms grace after the child is gone, so a grandchild holding a pipe cannot keep a call past its deadline by more than that grace. `run`, `run_with_env` and `run_raw` in [`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs), the optional capture in [`host_gpu/capture.rs`](../crates/rocm-core/src/host_gpu/capture.rs) and the Windows diagnostic capture in [`host_gpu/diagnostics.rs`](../crates/rocm-core/src/host_gpu/diagnostics.rs) all run on it. [`therock/process.rs`](../apps/rocm/src/therock/process.rs)'s `wait_with_output_bounded` is the one runner that still joins its reader threads with no time limit, so a grandchild holding a pipe can outlast its timeout. + +### `crates/rocm-dash-core` — dashboard types and reducer + +The pure layer under the dashboard: telemetry, benchmark and protocol types, the collector traits, the derivations over them and the `State` reducer, with no rendering dependencies and no async types at the type boundary. It must have no first-party dependencies, which [`crate_edges.rs`](../xtask/src/crate_edges.rs) enforces. + +| File | Responsibility | Class | +| --- | --- | --- | +| [`lib.rs`](../crates/rocm-dash-core/src/lib.rs) | Crate root: module declarations, re-exports of the common types, and `AUTO_PORT_NOTE`, the wording for a serve port that is not yet resolved. | flat | +| [`bench_rollup.rs`](../crates/rocm-dash-core/src/bench_rollup.rs) | Pass^N and Pass@N rollups (`rollup_pass_n`): groups benchmark rows into trial sets and gives each a strict and a lenient verdict plus mean throughput. | flat | +| [`bench_schema.rs`](../crates/rocm-dash-core/src/bench_schema.rs) | `BenchmarkRow`, the one row type for a benchmark result, and `PassFail`, vendored from the instinct-agent-bench schema. | flat | +| [`chat_template.rs`](../crates/rocm-dash-core/src/chat_template.rs) | The chat-template defaults a locally served model needs on an OpenAI-compatible chat request (`local_model_should_disable_thinking`). | flat | +| [`config.rs`](../crates/rocm-dash-core/src/config.rs) | The standalone dashboard configuration in `rocm-dash/config.toml` under the config directory (daemon, TUI and per-engine sections) and the default daemon socket path. | flat | +| [`efficiency.rs`](../crates/rocm-dash-core/src/efficiency.rs) | The pure join of throughput and power: GPU-id normalisation, board power attributed to the instances on a GPU by VRAM share, and tokens per watt. `node_efficiency` returns the whole-node figure as a `NodeEfficiency` (Σ `gen_tps` over Σ board power, including GPUs no instance occupies) with a `held` flag set when any throughput behind it is held; it is the one implementation behind the Observe efficiency hero and its trend, the Hardware header, and the assistant's `tokens_per_watt` tool (the Home tab's tokens-per-watt figure is a separate sum of per-instance values). | flat | +| [`metrics.rs`](../crates/rocm-dash-core/src/metrics.rs) | The live metric types the dashboard crates share: `Snapshot`, `GpuMetrics`, `Instance` with its `InstanceStatus` predicates and labels, and the observation-freshness metadata. | flat | +| [`observation.rs`](../crates/rocm-dash-core/src/observation.rs) | Turns a generation-token counter into an honest rate: a bounded sample window, fresh-or-held reporting with expiry, and directly reported rates, with all time passed in. | flat | +| [`partition.rs`](../crates/rocm-dash-core/src/partition.rs) | The GPU compute-partition and memory-partition mode enums. | flat | +| [`persist.rs`](../crates/rocm-dash-core/src/persist.rs) | `PersistedEntry`, the on-disk session record: one `Event` plus the microsecond timestamp replay paces by. | flat | +| [`protocol.rs`](../crates/rocm-dash-core/src/protocol.rs) | The NDJSON wire protocol between the daemon and a TUI client: `Command`, `Event` and `PROTOCOL_VERSION`. | flat | +| [`state.rs`](../crates/rocm-dash-core/src/state.rs) | The pure reducer `State::apply(StateEvent) -> Vec`: latest snapshot, bounded histories, instances, benchmark rows and the background-job table. | flat | +| [`traits.rs`](../crates/rocm-dash-core/src/traits.rs) | The collector traits and the data they exchange (`DiscoveredService`, `InstanceSample`, `GpuProcess`, `CollectorError`), plus `merge_instance`, which builds an `Instance` from them. | flat | +| [`vram.rs`](../crates/rocm-dash-core/src/vram.rs) | Pure VRAM attribution: folds per-process readings into a per-container map and resolves an instance's `(used, total)`. | flat | + +Boundaries: + +- **Rules kept here so the front ends cannot drift.** + - [`chat_template.rs`](../crates/rocm-dash-core/src/chat_template.rs) is called by both the CLI's [`providers/wire.rs`](../apps/rocm/src/providers/wire.rs) and the TUI's [`agent/clients.rs`](../crates/rocm-dash-tui/src/agent/clients.rs); it lives in this leaf crate because both already depend on it. + - `InstanceStatus`'s predicates and labels in [`metrics.rs`](../crates/rocm-dash-core/src/metrics.rs) and `JobStatus::glyph`, `label` and `legend_glyphs` in [`state.rs`](../crates/rocm-dash-core/src/state.rs) hold the shared predicates and labels for those statuses; their colours are chosen in [`ui/theme.rs`](../crates/rocm-dash-tui/src/ui/theme.rs). + - [`vram.rs`](../crates/rocm-dash-core/src/vram.rs) reuses the GPU-id matching in [`efficiency.rs`](../crates/rocm-dash-core/src/efficiency.rs) instead of its own. +- **Recordings and the wire.** + - `PersistedEntry` is the one recording format: the daemon's [`persist.rs`](../crates/rocm-dash-daemon/src/persist.rs) writes it, [`demo.rs`](../crates/rocm-dash-daemon/src/demo.rs) generates it and the TUI's [`replay.rs`](../crates/rocm-dash-tui/src/replay.rs) reads it back. + - The metric fields added after the first recordings, and every `BenchmarkRow` field, are `#[serde(default)]` so that older recordings and CSVs that omit columns still deserialize. + - `PROTOCOL_VERSION` is bumped when the JSON of an existing variant changes. Internal tagging rejects a newtype variant over a sequence, so every `Event` variant is a struct variant or wraps a struct; a round-trip test holds that. +- **Reducer effects.** Only `SideEffect::SpawnJob` is interpreted, by the TUI's [`jobs.rs`](../crates/rocm-dash-tui/src/jobs.rs); `Persist` and the `Broadcast*` effects are produced but nothing consumes them, and the daemon runner discards the effects it gets back. +- **Configuration.** [`config.rs`](../crates/rocm-dash-core/src/config.rs) is separate from the unified `rocm` configuration (`rocm-core`'s `RocmCliConfig`, whose dashboard section `rocm dash` reads); only the TUI's chat-endpoint save loads and writes this file. Its default socket path copies `rocm-core`'s on purpose, because this crate may have no first-party dependencies. + +### `crates/rocm-dash-collectors` — telemetry collectors + +The I/O-heavy collector implementations behind `rocm-dash-core`'s traits (amd-smi, Docker, host metrics, the Lemonade and vLLM scrapers and the Windows performance-counter collector) and the benchmark load generator. The daemon uses it, and on Windows the TUI runs some of its collectors in-process. + +| File | Responsibility | Class | +| --- | --- | --- | +| [`lib.rs`](../crates/rocm-dash-collectors/src/lib.rs) | Crate root: declares the public collector modules. | flat | +| [`amd_smi.rs`](../crates/rocm-dash-collectors/src/amd_smi.rs) | The amd-smi collector: runs `amd-smi ... --json` under a timeout after the GPU-device pre-flight and parses metrics, power limits, processes and system info tolerantly. | flat | +| [`bench_load.rs`](../crates/rocm-dash-collectors/src/bench_load.rs) | The concurrency-sweep load generator behind `rocm bench load`: one aggregate `BenchmarkRow` per concurrency cell, appended to a CSV, with an optional auto-ramp. | flat | +| [`bench_tail.rs`](../crates/rocm-dash-collectors/src/bench_tail.rs) | `CsvBenchTailer`: re-reads a benchmark CSV on each drain and yields the rows it has not returned yet. | flat | +| [`cgroup.rs`](../crates/rocm-dash-collectors/src/cgroup.rs) | Attributes GPU processes to Docker containers by reading the 64-hex container id from `/proc//cgroup`. | flat | +| [`docker.rs`](../crates/rocm-dash-collectors/src/docker.rs) | `DockerDiscovery`: finds vLLM containers through `bollard` and builds a `DiscoveredService` from each container's environment and command line. | flat | +| [`engine_registry.rs`](../crates/rocm-dash-collectors/src/engine_registry.rs) | `EngineKind`: maps a serving engine (vLLM, Lemonade) to its label, conventional port and sample parser. | flat | +| [`host.rs`](../crates/rocm-dash-collectors/src/host.rs) | `HostCollector`: CPU, memory and swap from `sysinfo`, sampled once per tick into `SystemMetrics`. Disk and network rates are not collected yet and stay 0. | flat | +| [`lemonade.rs`](../crates/rocm-dash-collectors/src/lemonade.rs) | The Lemonade Server collector: pure parsers over its stats and health endpoints, and discovery of a running server. | flat | +| [`parallel.rs`](../crates/rocm-dash-collectors/src/parallel.rs) | `parallel_scrape`: runs an async scrape against many targets concurrently on a `JoinSet`. | flat | +| [`vllm_prom.rs`](../crates/rocm-dash-collectors/src/vllm_prom.rs) | The vLLM Prometheus `/metrics` scraper: request gauges, KV-cache usage, the generation-token counter and the latency histogram sums. | flat | +| [`winperf.rs`](../crates/rocm-dash-collectors/src/winperf.rs) | Live Windows GPU metrics from OS performance counters, with temperature, power and clocks from ADLX when the AMD driver's DLL is present. | flat | + +Boundaries: + +- **Async collectors.** The core traits are synchronous: the Docker and vLLM implementations of `ServiceDiscovery` and `InstanceMetrics` return `CollectorError::Unsupported`, and the daemon runner calls their async methods (`discover_async`, `fetch_async`) instead. The runner builds its collectors directly, so `EngineKind::parse_sample` and `default_port` are not on the live path. +- **amd-smi pre-flight.** The device pre-flight in [`amd_smi.rs`](../crates/rocm-dash-collectors/src/amd_smi.rs) is mandatory outside tests, because amd-smi can block in uninterruptible kernel sleep on a host with no readable `/dev/kfd`. Its one relaxation is the GPU-reachability verdict `apps/rocm` computes and passes in through the daemon's `RunnerOptions`. +- **vLLM throughput.** [`vllm_prom.rs`](../crates/rocm-dash-collectors/src/vllm_prom.rs) leaves `gen_tps` empty: the daemon runner turns the generation-token counter into a rate. +- **Engine label.** [`bench_load.rs`](../crates/rocm-dash-collectors/src/bench_load.rs) takes the `vllm` label from `EngineKind`, so the CSV `engine` column cannot drift from the registry's spelling. Because `engine` is a rollup key, a cell that mixes blank-engine and vLLM rows is reported through `EngineSplitNotice` for the CLI to print, not printed here. +- **Lemonade is off by default.** The daemon runs the Lemonade collector only when `RunnerOptions::enable_lemonade` is set; it defaults to false and the daemon `rocm dash` starts leaves it off. + +### `crates/rocm-dash-daemon` — telemetry daemon + +The daemon library: [`runner.rs`](../crates/rocm-dash-daemon/src/runner.rs) drives the collectors on tick cadences and [`server.rs`](../crates/rocm-dash-daemon/src/server.rs) streams snapshots and benchmark rows to TUI clients as NDJSON. `apps/rocm`'s [`dash.rs`](../apps/rocm/src/dash.rs) drives it. + +| File | Responsibility | Class | +| --- | --- | --- | +| [`lib.rs`](../crates/rocm-dash-daemon/src/lib.rs) | Crate root: module declarations, `DAEMON_VERSION` for the handshake, and re-exports of `RunnerOptions`, `run` and the collectors' `bench_load`. | flat | +| [`bench_ring.rs`](../crates/rocm-dash-daemon/src/bench_ring.rs) | `BenchRing`, the bounded benchmark-row history a late-joining client is sent when it subscribes. | flat | +| [`demo.rs`](../crates/rocm-dash-daemon/src/demo.rs) | The synthetic-session generator behind `rocm dash --demo`: a deterministic recording of an 8-GPU node serving three vLLM containers, written as `PersistedEntry` lines. | flat | +| [`persist.rs`](../crates/rocm-dash-daemon/src/persist.rs) | `SessionWriter`: appends every broadcast `Event` as a `PersistedEntry` line to one `session-*.ndjson` file per daemon session. | flat | +| [`registry.rs`](../crates/rocm-dash-daemon/src/registry.rs) | Reads the managed-service records `rocm serve` writes and turns the live ones into `DiscoveredService` scrape targets, telling a registry read in full, an empty or absent one included, from one that could not be read in full. | flat | +| [`runner.rs`](../crates/rocm-dash-daemon/src/runner.rs) | The owner task: drives the collectors on their tick cadences, reconciles discovered services, derives rates and efficiency, and broadcasts `Snapshot`s. | flat | +| [`server.rs`](../crates/rocm-dash-daemon/src/server.rs) | The listener, the per-client task loop and the broadcast from the runner to every client, including the history replay on subscribe. | flat | +| [`snapshot_ring.rs`](../crates/rocm-dash-daemon/src/snapshot_ring.rs) | `SnapshotRing`, the bounded snapshot history a late-joining client is sent when it subscribes. | flat | +| [`transport.rs`](../crates/rocm-dash-daemon/src/transport.rs) | NDJSON framing for the daemon's socket: `write_line` and `read_line`. | flat | + +Boundaries: + +- **A failed registry read retires nothing.** When a pass cannot read the registry in full, the runner retires no service; the records that did read still add and refresh their services, and the header warns until a read succeeds. A registry read in full, an empty one included, retires every known service it no longer holds and keeps the rest (a registry that goes from A and B to A retires B). +- **Framing is copied, not shared.** [`transport.rs`](../crates/rocm-dash-daemon/src/transport.rs) and the TUI's [`transport.rs`](../crates/rocm-dash-tui/src/transport.rs) hold the same two functions because the TUI does not depend on the daemon crate, so a framing change must be made in both. + +### `crates/rocm-dash-tui` — dashboard TUI + +The dashboard client: the event loop and reducer (`app/`), the chat agent (`agent/`), the screens (`ui/`), and the daemon client and replay source at the top level. The `rocm` binary runs it through `app::run`, and the modules are public so examples and tests drive them in-process. + +#### `src/` + +| File | Responsibility | Class | +| --- | --- | --- | +| [`lib.rs`](../crates/rocm-dash-tui/src/lib.rs) | Library root: declares every module public, so `apps/rocm` runs the dashboard through `app::run` and examples drive the same modules in-process. | flat | +| [`client.rs`](../crates/rocm-dash-tui/src/client.rs) | The connection task behind the event stream, and `ClientMsg`, the one message type the app loop reads: connect, handshake, forward events, reconnect with backoff. | flat | +| [`jobs.rs`](../crates/rocm-dash-tui/src/jobs.rs) | The one async process runner the operational screens share: runs each `SideEffect::SpawnJob`, streams its output as `StateEvent::JobLine` and kills the child on cancel. | flat | +| [`llm.rs`](../crates/rocm-dash-tui/src/llm.rs) | Chat endpoint configuration: the precedence resolver `resolve_llm_config`, a TCP-only liveness probe and local-engine endpoint detection, with no HTTP client. | flat | +| [`reconnect.rs`](../crates/rocm-dash-tui/src/reconnect.rs) | `Backoff`, the exponential delay the client sleeps between connection attempts. | flat | +| [`registry_probe.rs`](../crates/rocm-dash-tui/src/registry_probe.rs) | `ManagedRegistryProbe`, the seam through which the dashboard reads the managed-service registry without depending on `rocm-core` or the daemon. | flat | +| [`replay.rs`](../crates/rocm-dash-tui/src/replay.rs) | The offline source behind `--replay`: posts a session file's events through the live client's channel, with pause, speed and seek through `ReplayController`. | flat | +| [`tool_exec.rs`](../crates/rocm-dash-tui/src/tool_exec.rs) | `RocmToolExecutor`, the plain-data seam for chat tool calls that need `rocm-core`: a read-only `execute` and an approval-gated `execute_approved`. | flat | +| [`transport.rs`](../crates/rocm-dash-tui/src/transport.rs) | NDJSON framing for the client: `write_line` and `read_line`. | flat | + +#### `agent/` + +| File | Responsibility | Class | +| --- | --- | --- | +| [`agent/mod.rs`](../crates/rocm-dash-tui/src/agent/mod.rs) | The chat-agent seam: the `AgentClient` trait, `AgentError`, `StateSnapshot`, `InferenceParams` and `REQUEST_TIMEOUT`. | relocation | +| [`agent/clients.rs`](../crates/rocm-dash-tui/src/agent/clients.rs) | The `AgentClient` backends: Rig (OpenAI-compatible), ChatGPT (OAuth device code), Anthropic, and the in-memory `MockAgentClient`. | relocation | +| [`agent/snapshot.rs`](../crates/rocm-dash-tui/src/agent/snapshot.rs) | Pure JSON summaries of the cached telemetry snapshot for the agent's tools, with no `rig` dependency. | relocation | +| [`agent/tools.rs`](../crates/rocm-dash-tui/src/agent/tools.rs) | The Rig `Tool` wrappers: the telemetry tools over the cached snapshot, the read-only and mutating ROCm tools, and their registration on an agent builder. | relocation | + +#### `app/` + +| File | Responsibility | Class | +| --- | --- | --- | +| [`app/mod.rs`](../crates/rocm-dash-tui/src/app/mod.rs) | The reducer's front: `AppState` and its constructor, the theme picker, row selection, and `apply_event`, which folds daemon events into state. | flat | +| [`app/actions.rs`](../crates/rocm-dash-tui/src/app/actions.rs) | `KeyAction` dispatch: maps a key press or a resolved mouse hit to a `KeyAction` and applies it to reducer state (`apply_action`). | domain | +| [`app/chat.rs`](../crates/rocm-dash-tui/src/app/chat.rs) | Chat-backend construction, local-engine detection, and saving an accepted endpoint to the dashboard config. | relocation | +| [`app/chat_runtime.rs`](../crates/rocm-dash-tui/src/app/chat_runtime.rs) | `ChatRuntime`, the live chat backend the tick loop owns: which agent answers the next turn, and the drains for the provider-switch, endpoint-rebuild and dispatch edges. | flat | +| [`app/chat_state.rs`](../crates/rocm-dash-tui/src/app/chat_state.rs) | An `impl AppState` block for chat consent, the local-endpoint detection offer, submitting a turn, and applying the agent's reply or error. | flat | +| [`app/event_loop.rs`](../crates/rocm-dash-tui/src/app/event_loop.rs) | The tick loop: `run` (set up, run, tear down) and `event_loop`, with the frame-draw gate and the registry-probe seeding. | domain | +| [`app/focus.rs`](../crates/rocm-dash-tui/src/app/focus.rs) | Focused-host policy: what a dashboard launched for Setup, Serve or Examine does differently (no daemon client or chat, one overlay opened at start, console close keys swallowed). | flat | +| [`app/overlays.rs`](../crates/rocm-dash-tui/src/app/overlays.rs) | An `impl AppState` block for which overlay owns the keyboard, `close_overlays`, and the gating predicates the key handlers and the renderer consult. | flat | +| [`app/quit_confirm.rs`](../crates/rocm-dash-tui/src/app/quit_confirm.rs) | An `impl AppState` block for the quit-confirm prompt: the live-instance gates, and opening, answering and resolving it. | flat | +| [`app/scroll.rs`](../crates/rocm-dash-tui/src/app/scroll.rs) | An `impl AppState` block for scroll offsets and recorded scrollbar tracks, and `ScrollState`, the shared clamped signed-delta scroll for a `u16` offset with a known bound. | flat | +| [`app/scrollbar.rs`](../crates/rocm-dash-tui/src/app/scrollbar.rs) | Mouse hit-testing: resolves a raw `MouseEvent` against recorded scrollbar tracks, the tab bar and the footer chips into a `KeyAction`. | domain | +| [`app/slash.rs`](../crates/rocm-dash-tui/src/app/slash.rs) | Slash-command routing for the chat input (`handle_slash_command`): mutates state, raises a one-shot edge for the event loop, or pushes a usage turn, with no I/O. | relocation | +| [`app/summary.rs`](../crates/rocm-dash-tui/src/app/summary.rs) | Pure display helpers: bounded summaries of read-only slash-tool results, and the parser of a natural-language plan into a `PlannedAction`. | relocation | +| [`app/terminal.rs`](../crates/rocm-dash-tui/src/app/terminal.rs) | Terminal restoration and shutdown arbitration: `restore_terminal`, the `SHUTTING_DOWN` latch, the termination-signal watcher and the Ctrl+C path. | flat | +| [`app/test_support.rs`](../crates/rocm-dash-tui/src/app/test_support.rs) | Test-only helpers shared by the `app` and `ui` test modules. | flat | +| [`app/tool_approval.rs`](../crates/rocm-dash-tui/src/app/tool_approval.rs) | An `impl AppState` block for the chat tool-approval flow: handing a plan's action to approval, opening the modal for a mutating-tool intent, and routing the verdict. | flat | +| [`app/types.rs`](../crates/rocm-dash-tui/src/app/types.rs) | Shared reducer types (`Focus`, `ResolvedArgs`, `Modal`, tab, chat and replay state, the slash and approval payloads) and the Esc-menu, palette and options navigation data. | domain | +| [`app/update_check.rs`](../crates/rocm-dash-tui/src/app/update_check.rs) | The background Updates-tile check: the tick-driven `rocm update --json` job and the reducer that turns its output into an `UpdateStatus`. | flat | + +#### `ui/` + +| File | Responsibility | Class | +| --- | --- | --- | +| [`ui/mod.rs`](../crates/rocm-dash-tui/src/ui/mod.rs) | The renderer's front: `draw` and `draw_focused`, the layout including the wide triptych, and `draw_active_manager`, which draws the open overlay or its job console. | flat | +| [`ui/approval.rs`](../crates/rocm-dash-tui/src/ui/approval.rs) | The shared approval prompt: renders an `ApprovalRequest` and reports the user's `ApprovalVerdict`, leaving the action itself to the caller. | flat | +| [`ui/automations_manager.rs`](../crates/rocm-dash-tui/src/ui/automations_manager.rs) | The Automations overlay: lists the background watchers and enables or disables one through `rocm automations` behind an approval. | flat | +| [`ui/bench_run.rs`](../crates/rocm-dash-tui/src/ui/bench_run.rs) | The bench-run form: endpoint, optional model, concurrency or auto-ramp, and output path, submitted as a `rocm bench load` job. | flat | +| [`ui/command_screen.rs`](../crates/rocm-dash-tui/src/ui/command_screen.rs) | The freeform command runner: any `rocm ...` command, always behind an approval that shows the exact argv. | flat | +| [`ui/config_manager.rs`](../crates/rocm-dash-tui/src/ui/config_manager.rs) | The config and provider overlay: `rocm config show`, and enabling or disabling an assistant provider behind an approval. | flat | +| [`ui/core_bars.rs`](../crates/rocm-dash-tui/src/ui/core_bars.rs) | `CoreBars`: one braille column per CPU core, filled from the bottom by utilization. | flat | +| [`ui/dock.rs`](../crates/rocm-dash-tui/src/ui/dock.rs) | The rails of the wide layout: the left GPU wall and the read-only right dock (LOGS or CONTEXT). | flat | +| [`ui/engine_manager.rs`](../crates/rocm-dash-tui/src/ui/engine_manager.rs) | The Engines overlay: set the default engine, and install or reinstall Lemonade or vLLM, each behind an approval. | flat | +| [`ui/examine_manager.rs`](../crates/rocm-dash-tui/src/ui/examine_manager.rs) | The Examine overlay: runs `rocm examine` read-only, and previews a Doctor report and sends it after approval. | flat | +| [`ui/exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs) | Helpers for launching a `rocm` sub-command from an operational screen: binary resolution, approval-preview quoting and the `rocm runtimes adopt` argv. | flat | +| [`ui/folder_browser.rs`](../crates/rocm-dash-tui/src/ui/folder_browser.rs) | The shared directory picker: use-current, new-child, parent and sub-directory entries, with only `build_entries` touching the filesystem. | flat | +| [`ui/footer.rs`](../crates/rocm-dash-tui/src/ui/footer.rs) | The footer: the key-hint chips, the Esc chip's context-dependent label, and the chip regions mouse hit-testing resolves against. | flat | +| [`ui/format.rs`](../crates/rocm-dash-tui/src/ui/format.rs) | Pure value formatters every tab uses (memory, percentages, rates, power, temperature, durations), including the held-value marker. | flat | +| [`ui/gradient.rs`](../crates/rocm-dash-tui/src/ui/gradient.rs) | `GradientGauge`, a gauge whose fill sweeps a three-stop color ramp, and `lerp3_t`, the shared three-stop interpolation. | flat | +| [`ui/header.rs`](../crates/rocm-dash-tui/src/ui/header.rs) | The header: the title line, the connection state, and the warning badge with its click region. | flat | +| [`ui/help_modal.rs`](../crates/rocm-dash-tui/src/ui/help_modal.rs) | The Help modals (per-tab help and the global keyboard reference), and `popup_height_for`, the content-sized popup arithmetic. | flat | +| [`ui/install_manager.rs`](../crates/rocm-dash-tui/src/ui/install_manager.rs) | The Install overlay: builds a `rocm install sdk` invocation; a dry run starts directly and a real install goes through approval. | flat | +| [`ui/instance_detail.rs`](../crates/rocm-dash-tui/src/ui/instance_detail.rs) | The instance Detail modal: a summary strip, recent throughput, and scrollable launch-args and env-var panes over a dimmed backdrop. | flat | +| [`ui/job_console.rs`](../crates/rocm-dash-tui/src/ui/job_console.rs) | The shared "a job is running" surface: `draw_job_console` renders the status header, streamed output and key hints, and `on_console_key` handles its keys. | flat | +| [`ui/launcher.rs`](../crates/rocm-dash-tui/src/ui/launcher.rs) | The bare-`rocm` front door: a synchronous pre-dashboard screen with a status strip over the headline verbs, returning a `LauncherChoice`. | flat | +| [`ui/logs_view.rs`](../crates/rocm-dash-tui/src/ui/logs_view.rs) | The Logs overlay: `rocm logs`, optionally with search terms, read-only into the job console. | flat | +| [`ui/menu.rs`](../crates/rocm-dash-tui/src/ui/menu.rs) | The Esc main menu, the command palette and the tabbed Options panel, with the block-letter logo they share. | flat | +| [`ui/modal.rs`](../crates/rocm-dash-tui/src/ui/modal.rs) | Re-exports only, so every item that was public at `ui::modal` before its split still resolves there. | flat | +| [`ui/model_picker.rs`](../crates/rocm-dash-tui/src/ui/model_picker.rs) | A filterable list of model recipes the Serve form opens; choosing one fills only the model id. | flat | +| [`ui/onboarding.rs`](../crates/rocm-dash-tui/src/ui/onboarding.rs) | The onboarding wizard: install the ROCm SDK or adopt an existing ROCm folder, both behind an approval. | flat | +| [`ui/panel.rs`](../crates/rocm-dash-tui/src/ui/panel.rs) | The shared box chrome: `bento` and `popup` panels, scrollbars, and popup geometry and framing (`centered_rect`, `centered_width`, `draw_popup_frame`, `grey_overlay`). | flat | +| [`ui/quit_confirm.rs`](../crates/rocm-dash-tui/src/ui/quit_confirm.rs) | The quit-confirm prompt's content (`quit_confirm_request`): the title, the body listing what is still served, and the stop hint. | flat | +| [`ui/runtime_manager.rs`](../crates/rocm-dash-tui/src/ui/runtime_manager.rs) | The Runtimes overlay: lists the registered runtimes and runs the `rocm runtimes` verbs, the mutating ones behind an approval. | flat | +| [`ui/serve_wizard.rs`](../crates/rocm-dash-tui/src/ui/serve_wizard.rs) | The Serve form: builds a model-first `rocm serve` invocation and launches it as a job behind an approval. | flat | +| [`ui/services_manager.rs`](../crates/rocm-dash-tui/src/ui/services_manager.rs) | The Services overlay: lists the managed inference services with live throughput, and stops or restarts one behind an approval. | flat | +| [`ui/sparkline.rs`](../crates/rocm-dash-tui/src/ui/sparkline.rs) | `BrailleSparkline`, a history graph that packs two samples into each character column at four dot rows per cell. | flat | +| [`ui/spinner.rs`](../crates/rocm-dash-tui/src/ui/spinner.rs) | Pure helpers for the braille spinner frame (`spinner_frame`) and progress-percentage parsing (`parse_progress_pct`) the job console renders with. | flat | +| [`ui/theme.rs`](../crates/rocm-dash-tui/src/ui/theme.rs) | The semantic `Theme` and its catalogue, and the shared status-to-color mapping (`StatusTone`, `tone_color`, `job_status_color`, `instance_status_color`). | flat | +| [`ui/theme_picker.rs`](../crates/rocm-dash-tui/src/ui/theme_picker.rs) | The theme picker modal: the registered themes beside a live preview of the highlighted one. | flat | +| [`ui/update_manager.rs`](../crates/rocm-dash-tui/src/ui/update_manager.rs) | The Update overlay: the `rocm update` check and dry-run preview start directly; applying goes through an approval. | flat | +| [`ui/warnings_modal.rs`](../crates/rocm-dash-tui/src/ui/warnings_modal.rs) | The Warnings modal: the text behind the header's warning badge, content-sized like the Help modals. | flat | +| [`ui/widgets.rs`](../crates/rocm-dash-tui/src/ui/widgets.rs) | Small helpers shared across tabs, including `apply_char_key` and `apply_char_key_filtered`, the append-only text-field edit the form key handlers use. | flat | + +#### `ui/tabs/` + +| File | Responsibility | Class | +| --- | --- | --- | +| [`ui/tabs/mod.rs`](../crates/rocm-dash-tui/src/ui/tabs/mod.rs) | Declares the tab modules and `TAB_LABELS`, draws the folder-tab panel, and owns the tab-chip geometry (`compute_chip_layout`). | flat | +| [`ui/tabs/bench.rs`](../crates/rocm-dash-tui/src/ui/tabs/bench.rs) | The Observe tab's benchmark panel: Pass^N and Pass@N rollups, a scrollable table of rows with verdicts, and a sparkline. | flat | +| [`ui/tabs/chat.rs`](../crates/rocm-dash-tui/src/ui/tabs/chat.rs) | The Chat tab: the consent gate until an endpoint is accepted, then the transcript and the input line. | flat | +| [`ui/tabs/hardware.rs`](../crates/rocm-dash-tui/src/ui/tabs/hardware.rs) | The Observe tab's host and GPU panel: CPU sparkline and per-core bars, memory and swap gauges, and a panel or a line per GPU. | flat | +| [`ui/tabs/home.rs`](../crates/rocm-dash-tui/src/ui/tabs/home.rs) | The Home tab: the hero GPU gauge, the VRAM, temperature and power cluster, the Running, Health and Updates tiles and an activity feed, with honest placeholders. | flat | +| [`ui/tabs/instances.rs`](../crates/rocm-dash-tui/src/ui/tabs/instances.rs) | The per-instance metrics table of the Observe tab, and the sorting, selection and status helpers the Detail modal also reads. | flat | +| [`ui/tabs/observe.rs`](../crates/rocm-dash-tui/src/ui/tabs/observe.rs) | The Observe tab: an efficiency and throughput hero band over the instance table, the Hardware panel and the Bench panel. | flat | +| [`ui/tabs/pane.rs`](../crates/rocm-dash-tui/src/ui/tabs/pane.rs) | The shared Actions and Details renderer of the ROCm and Serving tabs, whose verb rows open the existing overlays through `KeyAction::Open*`. | flat | +| [`ui/tabs/rocm.rs`](../crates/rocm-dash-tui/src/ui/tabs/rocm.rs) | The ROCm tab's verb table: install, updates, diagnose, runtimes, the command runner, and a display-only Uninstall row. | flat | +| [`ui/tabs/serving.rs`](../crates/rocm-dash-tui/src/ui/tabs/serving.rs) | The Serving tab's verb table: serve, engines, services, providers, logs, and a display-only Optimize row. | flat | + +Boundaries: + +- **No `rocm-core`.** The crate depends on `rocm-dash-core` and must not depend on `rocm-core` ([`crate_edges.rs`](../xtask/src/crate_edges.rs)). + - `rocm-core` data reaches it through the [`tool_exec.rs`](../crates/rocm-dash-tui/src/tool_exec.rs) and [`registry_probe.rs`](../crates/rocm-dash-tui/src/registry_probe.rs) seams, which the `rocm` binary implements, or as values the binary plumbs in on `ResolvedArgs`. + - A few values that mirror `rocm-core` (the default `rocm serve` port in [`llm.rs`](../crates/rocm-dash-tui/src/llm.rs), the runtime Python layout in [`ui/exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs)) are literal copies kept because of that rule; a change to the original needs the copy changed too. + - `ManagedRegistryProbe` is read live, at each quit attempt and each frame the quit-confirm prompt is open, so an implementation must stay cheap (a local file read). +- **Windows.** There is no daemon socket on Windows: the `cfg(windows)` arm of [`client.rs`](../crates/rocm-dash-tui/src/client.rs) collects host and GPU metrics in-process through `rocm-dash-collectors`, the only use of that dependency, and the snapshot it posts does not replace the instance list. +- **Overlays and approvals.** + - Each operational overlay is an `Option` state struct on `AppState` (`None` is closed); every opener calls `close_overlays` first, so at most one is open, and `draw_active_manager` draws it or its job console. + - A mutating overlay action stages an `ApprovalRequest` in the overlay's own state; the job starts only on Approve and the `rocm` CLI does the mutation. Read-only actions start their job directly, and so does the bench-run form. + - A chat tool call is approved separately, through `AppState::approval` and `tool_exec`'s `execute_approved`, which blocks and so runs off the async loop; the overlays do not use `tool_exec`. +- **Jobs.** One `State` holds every job (`AppState::jobs`), so closing an overlay leaves its jobs in the table. [`jobs.rs`](../crates/rocm-dash-tui/src/jobs.rs) sends events over an unbounded channel on purpose, because the synchronous reducer cannot apply backpressure, and the reducer bounds the output instead. +- **Reuse the shared components.** + - A new screen reuses the approval prompt, job console, spinner, panel, theme tones, text-field edit and `ScrollState` that [`AGENTS.md`](../AGENTS.md) section 6 names, instead of hand-rolling its own. + - [`dash_text_edit_contract.rs`](../xtask/src/dash_text_edit_contract.rs) fails a hand-rolled `push`/`pop` text edit outside [`ui/widgets.rs`](../crates/rocm-dash-tui/src/ui/widgets.rs); the Chat tab's input is the one exception. +- **Layering in `app/` and `ui/`.** + - The modules split from [`app/event_loop.rs`](../crates/rocm-dash-tui/src/app/event_loop.rs) (`chat_runtime`, `focus`, `terminal`, `update_check`) are leaves: none calls back into it. + - [`app/mod.rs`](../crates/rocm-dash-tui/src/app/mod.rs) re-exports the public surface its children took over, so `crate::app::` paths keep resolving. + - The tabs only read `AppState` while drawing, except the Chat tab, which writes its measured scroll bounds back. +- **Single sources.** + - `MENU_ITEMS` in [`app/types.rs`](../crates/rocm-dash-tui/src/app/types.rs) gives the Esc menu's rows, their labels, the key handling's wrap bound and the height `draw_menu` reserves. + - `outlined_chip_spans` in [`ui/tabs/mod.rs`](../crates/rocm-dash-tui/src/ui/tabs/mod.rs) is the one tab geometry, behind both the painter and `compute_chip_layout`, which [`app/actions.rs`](../crates/rocm-dash-tui/src/app/actions.rs) uses to turn a click into a tab. +- **Endpoints and binds.** + - [`llm.rs`](../crates/rocm-dash-tui/src/llm.rs) strips the API key and custom auth header from a loopback base URL, so a local endpoint is never sent a gateway credential. + - [`ui/serve_wizard.rs`](../crates/rocm-dash-tui/src/ui/serve_wizard.rs) has its own stricter `is_loopback_host` (exact spellings only) for the bind host. Its default invocation is exactly `rocm serve MODEL`, so the CLI stays the authority for engine, GPU-required policy, host, port and managed mode. ### `crates/rocm-engine-protocol` — engine IPC protocol A contract surface: verify all impacted engines after any protocol change here (see [`AGENTS.md`](../AGENTS.md)). -- [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs) — the client side of the engine stdio protocol, the one implementation `rocm` and `rocmd` both run an engine child through: the request line, the child's environment (`EngineStdioOptions`: app paths, engine environments root, endpoint key file, progress request), stderr handling (kept for the error, optionally forwarded as it arrives), the SIGPIPE guard around the write and around each forward of the child's stderr, killing and reaping the child when its request cannot be written (the error then carries what it wrote to stderr) or its answer cannot be read, what a failing exit status or an unusable answer is reported as, and `decode_engine_response`. It sets no timeout, and does not bound the wait for the child's pipes after it exits (a grandchild holding one makes the request wait); its module comment states that limit. Each caller still chooses which program to run: `rocm` the resolved engine binary with `stdio` (or the built-in handler, with no child), `rocmd` the `rocm` executable with `__engine-stdio `. It adds no wire format; the envelope types are the ones in [`lib.rs`](../crates/rocm-engine-protocol/src/lib.rs). -- [`fake_engine.rs`](../crates/rocm-engine-protocol/src/fake_engine.rs) — test-only, behind the `test-support` feature the `rocm` and `rocmd` dev-dependencies turn on: a shell-script stand-in for an engine child that records its argv, environment and stdin and answers (or crashes) as a test asks, so both callers' tests run against the same fake. -- [`lib.rs`](../crates/rocm-engine-protocol/src/lib.rs) — the protocol contract: the protocol and recipe-contract version constants, the request/response envelopes and the per-method request and response types for the `EngineMethod` calls (`detect`, `install`, `capabilities`, `resolve_model`, `launch`, `healthcheck`, `endpoint`, `stop`, `logs`), the `DevicePolicy` and `GpuSelection` types with the GPU-visibility helpers engines apply to a child process, engine-plugin binary naming and discovery, and the endpoint API key file carrier (`ENDPOINT_API_KEY_FILE_ENV`, `resolve_endpoint_api_key`, `is_public_bind_host`) that `rocm` and `rocmd` share, and `optional_arg`, the `flag value` argument helper both binaries build child command lines with. +| File | Responsibility | Class | +| --- | --- | --- | +| [`lib.rs`](../crates/rocm-engine-protocol/src/lib.rs) | The protocol contract: protocol versions, the request/response envelopes and per-method types, device and GPU-selection policy, engine-plugin discovery, the endpoint API key file carrier shared by `rocm` and `rocmd`, and `optional_arg`, the `flag value` argument helper both binaries build child command lines with. | flat | +| [`fake_engine.rs`](../crates/rocm-engine-protocol/src/fake_engine.rs) | Test-only, behind the `test-support` feature the `rocm` and `rocmd` dev-dependencies turn on: a shell-script stand-in for an engine child that records its argv, environment and stdin and answers (or crashes) as a test asks, so both callers' tests run against the same fake. | flat | +| [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs) | The client side of the engine stdio protocol, the one implementation `rocm` and `rocmd` both run an engine child through: the request line, the child's environment (`EngineStdioOptions`: app paths, engine environments root, endpoint key file, progress request), stderr handling (kept for the error, optionally forwarded as it arrives), the SIGPIPE guard around the write and around each forward of the child's stderr, killing and reaping the child when its request cannot be written (the error then carries what it wrote to stderr) or its answer cannot be read, what a failing exit status or an unusable answer is reported as, and `decode_engine_response`. It sets no timeout, and does not bound the wait for the child's pipes after it exits (a grandchild holding one makes the request wait); its module comment states that limit. Each caller still chooses which program to run: `rocm` the resolved engine binary with `stdio` (or the built-in handler, with no child), `rocmd` the `rocm` executable with `__engine-stdio `. It adds no wire format; the envelope types are the ones in [`lib.rs`](../crates/rocm-engine-protocol/src/lib.rs). | flat | ### `crates/rocm-deps` -Pinned versions of the third-party runtimes rocm-cli manages (from workspace-root [`runtime-deps.toml`](../runtime-deps.toml), turned into constants by [`build.rs`](../crates/rocm-deps/build.rs)). Small and already single-purpose; not part of the modularization effort's target list. [`lib.rs`](../crates/rocm-deps/src/lib.rs) includes the generated constants and holds the helpers that derive Lemonade release names from them (`strip_v`, `lemonade_archive_name`, `lemonade_download_url`, `LEMONADE_GITHUB_REPO`). Only `rocm` and `rocm-engine-lemonade` depend on it; the dashboard TUI does not. +Pinned versions of the third-party runtimes rocm-cli manages, read from the workspace-root [`runtime-deps.toml`](../runtime-deps.toml) and turned into constants by [`build.rs`](../crates/rocm-deps/build.rs). Only `rocm` and `rocm-engine-lemonade` depend on it; the dashboard TUI does not. + +| File | Responsibility | Class | +| --- | --- | --- | +| [`lib.rs`](../crates/rocm-deps/src/lib.rs) | Includes the generated constants and derives Lemonade release names and download URLs from them. | flat | ### `crates/e2e-report` -Modularized (ROCMAI-60, Phase 1 of ROCMAI-27's sequencing): - -- [`command_coverage.rs`](../crates/e2e-report/src/command_coverage.rs) — (ROCMAI-486, Phase 1 of a staged further split of [`consolidated/mod.rs`](../crates/e2e-report/src/consolidated/mod.rs)) the CLI command-coverage audit table — which `rocm` commands were exercised and whether they passed — consumes `consolidated::PlatformReport` but shares no type with the `Grid`/reconciliation model itself. -- [`components.rs`](../crates/e2e-report/src/components.rs) — shared maud HTML fragment rendering, plus the CSS and timestamp helpers both generators use, depending only on [`parse.rs`](../crates/e2e-report/src/parse.rs) types to keep the module graph acyclic. -- [`consolidated/mod.rs`](../crates/e2e-report/src/consolidated/mod.rs) — the `PlatformReport` model (loading one platform's `report.json` together with its sidecars), the reconciled scenario × platform `Grid`, the `PlatformReports` bundle and `load_platform_reports`, which both renderers draw from, plus the scenario-reference map it builds, and the report text both renderers share so it cannot drift between them: `LEGEND_ENTRIES` (the grid legend) and the two phrases of the PR-gating policy, `MOCK_GATES_PR` and `OTHER_LANES_NON_BLOCKING`, which the markdown explanation paragraph and the HTML legend each build their own sentence around. Artifact-name parsing lives in [`consolidated/descriptor.rs`](../crates/e2e-report/src/consolidated/descriptor.rs), the `platform.json`/`commands.jsonl` schema and parsing in [`consolidated/sidecars.rs`](../crates/e2e-report/src/consolidated/sidecars.rs) (both reached through `use`), and the two renderers in [`consolidated/html.rs`](../crates/e2e-report/src/consolidated/html.rs) and [`consolidated/markdown.rs`](../crates/e2e-report/src/consolidated/markdown.rs), declared `pub(super) mod`. It is still the largest module in the crate, still holding the `Grid`/`PlatformReport` model and the bundle in one file; what remains of the split is optional: a `grid.rs` split and a relocation of [`command_coverage.rs`](../crates/e2e-report/src/command_coverage.rs). -- [`consolidated/descriptor.rs`](../crates/e2e-report/src/consolidated/descriptor.rs) — artifact-name identity: `Descriptor` and `parse_descriptor` (artifact/directory name to platform, OS, legacy known-bugs flag and channel), driven by one `KNOWN_PLATFORMS` table that also holds the `platform.json` `platform_slug`s of each lane, so the public `artifact_name_for_platform_slug` (what [`xtask`'s e2e report](../xtask/src/e2e_report.rs) uses to name a report downloaded without its artifact directory) is the inverse of the same rows rather than a second table, plus the one platform-label rule, `full_platform_label` (platform, OS and optional channel), which `PlatformReport::label`, `GridColumn::label` and the excluded-platform caption in `Grid::build` all call, and the helpers under it, `with_paren_suffix` (also used for the sdk_version leg in `parse_descriptor`) and `fallback_descriptor`. A leaf: it imports nothing from [`consolidated/mod.rs`](../crates/e2e-report/src/consolidated/mod.rs), which reaches it through `use descriptor::{...}`; its `parse_descriptor_*` tests sit beside it. -- [`consolidated/sidecars.rs`](../crates/e2e-report/src/consolidated/sidecars.rs) — sidecar schema and parsing: the `platform.json` manifest (`PlatformManifest`, `ManifestCapability`, `PlatformVersions` with its `summary`/`platform_stack` display strings, `ManifestExpectation`, `parse_platform_manifest`) and the `commands.jsonl` record (`CommandRecord`, `parse_commands`). A leaf that uses only serde, `serde_json` and `std` (no other module of the crate) and imports nothing from [`consolidated/mod.rs`](../crates/e2e-report/src/consolidated/mod.rs), which reaches it through `use sidecars::{...}`; `CommandRecord` stays `pub(crate)` because [`command_coverage.rs`](../crates/e2e-report/src/command_coverage.rs) reads it through `PlatformReport::commands`. The parsers have no direct unit tests; they are covered through `PlatformReport::load`. -- [`consolidated/html.rs`](../crates/e2e-report/src/consolidated/html.rs) — the HTML renderer: `RunMeta` and `generate_consolidated`, with the matrix table, legend, expectation grid (`expectation_grid_html`, `pub(super)` so the cross-renderer tests in [`consolidated/mod.rs`](../crates/e2e-report/src/consolidated/mod.rs) can call it) and per-platform sections it assembles. A child of [`consolidated/mod.rs`](../crates/e2e-report/src/consolidated/mod.rs) (declared `pub(super) mod html;`), so it reads the private `PlatformReport`, `Grid`, `CellOutcome` and `PlatformReports` items defined there without any of them being widened; no production code in the parent or in the markdown renderer calls into it (only the cross-renderer tests that stay in `consolidated/mod.rs` do). Its `generate_consolidated_*` and legend tests sit beside it. -- [`consolidated/markdown.rs`](../crates/e2e-report/src/consolidated/markdown.rs) — the markdown renderer: `consolidated_summary_markdown` (the table piped into `$GITHUB_STEP_SUMMARY`), `expectation_grid_markdown` and `scenario_reference_markdown`, and the call into [`command_coverage.rs`](../crates/e2e-report/src/command_coverage.rs)'s `command_coverage_markdown` for the command-coverage table. A child of [`consolidated/mod.rs`](../crates/e2e-report/src/consolidated/mod.rs) (declared `pub(super) mod markdown;`), so it reads the private `PlatformReport`, `Grid`, `CellOutcome`, `PlatformReports` and `ScenarioReference` items defined there without any of them being widened; it does not call the HTML renderer. The tests that assert on its output sit beside it; what stays in `consolidated/mod.rs` is the cross-renderer tests (HTML and markdown over one bundle), the command-coverage tests, and tests of the grid or `PlatformReport` that use the markdown only as a probe. -- [`consolidated/test_support.rs`](../crates/e2e-report/src/consolidated/test_support.rs) — `#[cfg(test)]` fixtures (`feature_json`, `write_report`, `write_platform`, `grid_order`) shared by the `consolidated/` tests, so each module extracted from [`consolidated/mod.rs`](../crates/e2e-report/src/consolidated/mod.rs) can keep its tests beside it. -- [`parse.rs`](../crates/e2e-report/src/parse.rs) — cucumber `report.json` data model, parsing, and `@expected-failure` xfail evaluation. -- [`single_report.rs`](../crates/e2e-report/src/single_report.rs) — single-platform HTML report generation. - -These modules are private `mod` declarations — [`lib.rs`](../crates/e2e-report/src/lib.rs) re-exports only the selected public API surface (`XfailReport`, `evaluate_xfail`, `scenario_results_by_id`, `generate`, `RunMeta`, `PlatformReports`, `load_platform_reports`, `artifact_name_for_platform_slug`, `generate_consolidated`, `consolidated_summary_markdown`) via `pub use` (`RunMeta` and `generate_consolidated` through `consolidated::html`, `consolidated_summary_markdown` through `consolidated::markdown`: the only child modules `lib.rs` reaches by path), so consumers reach it through the crate root rather than through module-qualified paths like `e2e_report::parse::...`. `generate_consolidated` and `consolidated_summary_markdown` take the opaque `PlatformReports` bundle [`load_platform_reports`](../crates/e2e-report/src/consolidated/mod.rs) returns (ROCMAI-484 / ROCm/rocm-cli#640) — bundling the parsed reports with the expectation `Grid` and scenario-reference map built from the same `inputs` means a caller producing both outputs can no longer pass them out of sync with each other. Building them there also means the grid is built once per run rather than once per report section that renders it (ROCMAI-660). `PlatformReport` itself went back to `pub(crate)` once the bundle was the only thing outside callers needed. This is a deliberate encapsulation choice tighter than the full-domain-extraction convention's `pub mod x;` + `pub use x::{...};` default described above — nothing outside this crate needs the module paths themselves, only the re-exported items. Unlike [`components.rs`](../crates/e2e-report/src/components.rs), which, as noted above, keeps the module graph acyclic by depending only on [`parse.rs`](../crates/e2e-report/src/parse.rs), [`command_coverage.rs`](../crates/e2e-report/src/command_coverage.rs) and the `consolidated` module as a whole depend on each other: [`consolidated/markdown.rs`](../crates/e2e-report/src/consolidated/markdown.rs) calls `command_coverage::command_coverage_markdown`, and [`command_coverage.rs`](../crates/e2e-report/src/command_coverage.rs) consumes `consolidated::PlatformReport` (via its `commands`, `label` and `scenario_pass_map()`), which is defined in [`consolidated/mod.rs`](../crates/e2e-report/src/consolidated/mod.rs). That chain between files (`markdown.rs` to `command_coverage.rs` to `consolidated/mod.rs`) is acyclic, and no production code in `consolidated/mod.rs` depends on `command_coverage.rs` any more (only its command-coverage tests import from it); viewed as the whole `consolidated` module, though, the two still depend on each other, which moving `command_coverage.rs` under `consolidated/` would remove. - -### `engines/lemonade`, `engines/vllm`, `engines/aim` — inference engine adapters - -`engines/vllm` follows full domain extraction: - -- [`discover_builds.rs`](../engines/vllm/src/discover_builds.rs) — the ROCm 10.x discovery table (`VLLM_ROCM_DISCOVER_BUILD_TABLE`, one row per supported `major.minor` line, with the `DiscoverVersion` series/exact constraint), the row lookup (`vllm_rocm_discover_build`) and the `major.minor` matcher it uses (`rocm_sdk_series_matches`). It is the single list of the ROCm SDK versions installed by discovery: install routing, the fail-closed static fallback and launch-time environment setup (`runtime_has_discover_build` in `runtime.rs`) all read these rows, and nothing keeps a second list in step with them. A leaf: it imports no other crate module, so `runtime.rs`, `wheel_builds.rs` and `install.rs` can all read it without importing one another's code. Its tests, including the one that pins which versions the table serves and in what order, live with it. -- [`install.rs`](../engines/vllm/src/install.rs) — ROCm/vLLM install execution: the static-pin and the ROCm 10.x discovery install routes, run through `uv`. It reads the static build table and target resolution from `wheel_builds.rs` and the discovery rows from `discover_builds.rs`, and asks `repair.rs` whether an already-resolvable environment still needs an install pass. -- [`process.rs`](../engines/vllm/src/process.rs) — the resolve-model, launch, serve and stop handlers (including engine-recipe validation and device-policy/GPU-index resolution), vLLM server spawn, launch environment and path setup, and readiness polling. The text appended to a "never became ready" failure comes from `startup_diagnostics.rs`. -- [`repair.rs`](../engines/vllm/src/repair.rs) — runtime-repair assessment: whether an already-resolvable managed vLLM environment violates vLLM's pinned dependencies and must be reinstalled (`assess_runtime_repair`, `RepairAssessment`), including the rule that treats the SDK's build of torch, and the torch stack (torch, torchvision, torchaudio, triton) the user chose with the alignment disabled, as intended rather than a defect. It imports `runtime.rs` and nothing from `install.rs`. -- [`runtime.rs`](../engines/vllm/src/runtime.rs) — TheRock/managed-runtime resolution and TheRock library/bin path derivation; the path derivation performs no filesystem writes. The launch path's compat-shim writes (a `libmpi_cxx` stub, stale-numa-shim removal) are this module's separate `ensure_therock_compat_shims`, called only from `process.rs`; the running-state payload, which never calls it, falls back to a plain directory listing instead. -- [`startup_diagnostics.rs`](../engines/vllm/src/startup_diagnostics.rs) — what a failed startup tells the user: the tail of the startup log, re-rendered line by line through `terminal::rendered_lines` (not stripped — stripping deletes line-break tokens with no separator, which welds a progress-bar repaint onto the next line), followed by the out-of-memory and engine-import-failure hints that point at `rocm diagnose`. Its single entry point is `startup_log_context`, which `process.rs` calls from `wait_for_vllm_ready`. It imports only `state.rs`, for the log-read cap. -- [`state.rs`](../engines/vllm/src/state.rs) — service state file I/O, log tailing, and health/inference probing. -- [`wheel_builds.rs`](../engines/vllm/src/wheel_builds.rs) — which vLLM wheels to install for a ROCm SDK version: the static build table (`VLLM_ROCM_BUILD_TABLE`), the install-route choice (`vllm_install_route`, which consults the discovery table in `discover_builds.rs`), target resolution including the `ROCM_CLI_VLLM_ROCM_INDEX_URL` override (`vllm_install_target`), and the static-table SDK-version matchers. It also holds `verified_torchaudio_release`, which the crate re-exports from `lib.rs` for the `rocm` binary. It imports only `discover_builds.rs` and runs no process. - -[`lib.rs`](../engines/vllm/src/lib.rs) keeps only CLI/envelope dispatch and the few items shared across those modules. [`main.rs`](../engines/vllm/src/main.rs) is the `rocm-engine-vllm` binary's entry point and only calls `rocm_engine_vllm::run_cli()`. - -`engines/lemonade` follows the same pattern: - -- [`archive_cache.rs`](../engines/lemonade/src/archive_cache.rs) — the cached embeddable-archive layer: SHA-256 verification, verified publication of a download into the cache, and the per-archive exclusion (an in-process set plus a cross-process file lock) that `ensure_cached_archive` returns as an `ArchiveCacheGuard` for the caller to hold while it relies on the verified bytes. A leaf: it imports no other crate module. Its tests, including the two-process lock test, live with it. -- [`archive_extract.rs`](../engines/lemonade/src/archive_extract.rs) — the hardened in-process extractor for the embeddable archive (tar.gz and zip: untrusted entry names are resolved component by component, links and special entries are rejected, modes are masked) and the containment-checked `copy_tree` that moves the extracted tree into the runtime directory. A leaf: it imports no other crate module. Its extraction tests and the tar/zip property tests live with it; the property-test support (`archive_props`) is included once at the crate root so both this module and `install.rs` reach it as `crate::archive_props`. -- [`backend_alignment.rs`](../engines/lemonade/src/backend_alignment.rs) — ROCm-SDK-to-llama.cpp-backend Tier 1/Tier 2/revert alignment, including the `backend_versions.json` pin handling and the set-aside/restore of ROCm backend directories around a forced reinstall. It uses `llamacpp_backend.rs`; that module does not import it back. -- [`device_policy.rs`](../engines/lemonade/src/device_policy.rs) — device-policy and GPU-selection handling: the GPU-required policy check (a CPU-only request is refused, never downgraded), `--device`/`--gpu` argument parsing, probing and resolving the GPU ordinal(s) to pin before a launch, the device availability reported by `detect`, and the device string reported for a loaded model. A leaf: it imports no other crate module. -- [`direct_llama.rs`](../engines/lemonade/src/direct_llama.rs) — Hugging Face checkpoint/GGUF resolution and the direct-llama-server serve path (`serve_direct_llama_server`, which runs a packaged `llama-server` on a GGUF and waits for `/v1/models` to report the model). It imports `process.rs`; `process.rs` no longer imports it. -- [`footprint.rs`](../engines/lemonade/src/footprint.rs) — what an install costs on disk: the pre-install notice and free-space check, plus the read-only view of Lemonade's install trees and record that `apps/rocm` uses for `rocm storage` and `rocm runtimes uninstall` (re-exported at the crate root). -- [`install.rs`](../engines/lemonade/src/install.rs) — embeddable-runtime download, extraction orchestration (the cache layer is in `archive_cache.rs`, the extractor in `archive_extract.rs`), and manifest persistence, plus the `LemonadeRuntime` handle and `resolve_runtime`, which wrap the persisted manifest (so `state.rs`, `process.rs` and `direct_llama.rs` reach it without importing `backend_alignment.rs`). -- [`llamacpp_backend.rs`](../engines/lemonade/src/llamacpp_backend.rs) — llama.cpp backend discovery and selection: asking `lemonade backends` what the host supports, choosing the best GPU backend (`rocm` before `vulkan`, never `cpu`), installing it with one retry, the `ROCM_LLAMACPP_BACKEND_DIRS` name list, and `find_llama_server_binary_for_backend`. It imports `direct_llama.rs` for `find_binary_in`; `direct_llama.rs` does not import it. With this module the engine's modules form no import cycle outside test code. -- [`process.rs`](../engines/lemonade/src/process.rs) — `lemond` spawn, env/path setup, readiness/health polling, and the background relaunch of the `serve-http` command (`serve_http_command_args`, `spawn_serve_http_background`). The direct `llama-server` serve loop is in `direct_llama.rs`. -- [`runtime_dir.rs`](../engines/lemonade/src/runtime_dir.rs) — `XDG_RUNTIME_DIR` tier1/2/3 hardening for the spawned child. -- [`state.rs`](../engines/lemonade/src/state.rs) — service state file I/O and port/endpoint helpers. - -[`lib.rs`](../engines/lemonade/src/lib.rs) keeps only CLI/envelope dispatch and the service-lifecycle orchestration that calls across those modules. [`main.rs`](../engines/lemonade/src/main.rs) is the `rocm-engine-lemonade` binary's entry point and only calls `rocm_engine_lemonade::run_cli()`. - -`engines/aim` runs models as Docker containers instead of a host process: - -- [`docker.rs`](../engines/aim/src/docker.rs) — thin wrapper around the `docker` CLI binary; no `bollard`/Docker API dependency. It also owns `container_name`, the deterministic Docker-name-sanitized container identity for a service (a leaf, so both `process.rs` and `state.rs` reach it here, and `state.rs` does not need to import `process.rs`). -- [`registry.rs`](../engines/aim/src/registry.rs) — AIM image metadata (`Env`/`Labels`): read from the local daemon once the image is pulled, which works for any registry, with a best-effort Docker Hub v2 lookup as a pre-pull hint (image ref normalization, tag/digest parsing). The hint is optional; its failure never blocks a launch. -- [`process.rs`](../engines/aim/src/process.rs) — container run/readiness/stop lifecycle. `serve_http` is the process rocmd supervises: it blocks for the container's lifetime and records how it ended (`failed` and a non-zero exit for a crash or a vanished container, so recovery runs). A stale container is removed before a re-run, and a stop removes the container so its name and downloaded weights are released. -- [`state.rs`](../engines/aim/src/state.rs) — service state file I/O, including the model name the container actually serves (`served_model_id`), which differs from the image reference, and `endpoint_url`, the `/v1` base URL for a host and port. `state.rs` uses no `process.rs` item: `process.rs` imports `state.rs` and the dependency does not run the other way. -- [`install.rs`](../engines/aim/src/install.rs) — much smaller than vLLM's/Lemonade's `install.rs`: there is no venv, wheel, or runtime archive to manage, only a Docker-reachability check. - -[`lib.rs`](../engines/aim/src/lib.rs) keeps only CLI/envelope dispatch (including the `builtin_*` entry points the `rocm` binary calls in-process), the detect and capabilities responses, and the few items shared across those modules. [`main.rs`](../engines/aim/src/main.rs) is the `rocm-engine-aim` binary's entry point and only calls `rocm_engine_aim::run_cli()`. +HTML and markdown reporting for the cucumber E2E suite, consumed only by `xtask` and `tests/e2e-cucumber`. It is in this map because `check-architecture-doc` covers every file under `crates/*/src`, although it is not part of the shipped CLI. + +| File | Responsibility | Class | +| --- | --- | --- | +| [`lib.rs`](../crates/e2e-report/src/lib.rs) | Crate root: module declarations and the public API re-exports. | flat | +| [`command_coverage.rs`](../crates/e2e-report/src/command_coverage.rs) | The CLI command-coverage audit table: which `rocm` commands a platform's run exercised and whether they passed. | domain | +| [`components.rs`](../crates/e2e-report/src/components.rs) | Shared maud HTML fragments plus the CSS and timestamp helpers both report generators use. | flat | +| [`consolidated/mod.rs`](../crates/e2e-report/src/consolidated/mod.rs) | The `PlatformReport` model, the reconciled scenario by platform `Grid`, the `PlatformReports` bundle and `load_platform_reports`, plus the report text both renderers share. | domain | +| [`consolidated/descriptor.rs`](../crates/e2e-report/src/consolidated/descriptor.rs) | Artifact-name identity: parses an artifact or directory name into platform, OS and channel, and owns the platform-label rule. | domain | +| [`consolidated/html.rs`](../crates/e2e-report/src/consolidated/html.rs) | The HTML renderer for the consolidated report. | domain | +| [`consolidated/markdown.rs`](../crates/e2e-report/src/consolidated/markdown.rs) | The markdown renderer, including the table piped into `$GITHUB_STEP_SUMMARY`. | domain | +| [`consolidated/sidecars.rs`](../crates/e2e-report/src/consolidated/sidecars.rs) | Schema and parsing for the `platform.json` manifest and the `commands.jsonl` record. | domain | +| [`consolidated/test_support.rs`](../crates/e2e-report/src/consolidated/test_support.rs) | Test-only fixtures shared by the `consolidated/` tests. | flat | +| [`parse.rs`](../crates/e2e-report/src/parse.rs) | The cucumber `report.json` data model, its parsing, and `@expected-failure` evaluation. | flat | +| [`single_report.rs`](../crates/e2e-report/src/single_report.rs) | Single-platform HTML report generation. | flat | + +Boundaries: + +- The modules are private; [`lib.rs`](../crates/e2e-report/src/lib.rs) re-exports only the selected API, so consumers reach everything through the crate root. This is tighter than the `pub mod` plus `pub use` default in the convention above, on purpose: nothing outside the crate needs the module paths. +- `load_platform_reports` returns one opaque `PlatformReports` bundle (parsed reports, the expectation grid and the scenario-reference map built from the same inputs), so a caller producing both outputs cannot pass them out of sync, and the grid is built once per run. +- [`consolidated/descriptor.rs`](../crates/e2e-report/src/consolidated/descriptor.rs) and [`consolidated/sidecars.rs`](../crates/e2e-report/src/consolidated/sidecars.rs) are leaves: neither imports [`consolidated/mod.rs`](../crates/e2e-report/src/consolidated/mod.rs). The two renderers are `pub(super)` children that read the parent's private types, and neither calls the other. +- [`components.rs`](../crates/e2e-report/src/components.rs) depends only on [`parse.rs`](../crates/e2e-report/src/parse.rs), which keeps that part of the module graph acyclic. [`command_coverage.rs`](../crates/e2e-report/src/command_coverage.rs) and `consolidated` depend on each other as modules ([`consolidated/markdown.rs`](../crates/e2e-report/src/consolidated/markdown.rs) calls it, and it reads `consolidated::PlatformReport`); the file-level chain is acyclic, and no production code in [`consolidated/mod.rs`](../crates/e2e-report/src/consolidated/mod.rs) uses [`command_coverage.rs`](../crates/e2e-report/src/command_coverage.rs). Moving [`command_coverage.rs`](../crates/e2e-report/src/command_coverage.rs) under `consolidated/` would remove the module-level dependency. + +### `engines/lemonade` + +The Lemonade engine adapter (`rocm-engine-lemonade`): installs the embeddable Lemonade runtime and serves models through `lemond` or a packaged `llama-server`. Its modules follow full domain extraction; [`lib.rs`](../engines/lemonade/src/lib.rs) keeps only dispatch and the service-lifecycle orchestration that calls across them. + +| File | Responsibility | Class | +| --- | --- | --- | +| [`lib.rs`](../engines/lemonade/src/lib.rs) | Crate root: CLI and envelope dispatch, the service-lifecycle orchestration that calls across the modules, and the crate-root re-exports `apps/rocm` uses. | flat | +| [`main.rs`](../engines/lemonade/src/main.rs) | The `rocm-engine-lemonade` binary's entry point; it only calls `rocm_engine_lemonade::run_cli()`. | flat | +| [`archive_cache.rs`](../engines/lemonade/src/archive_cache.rs) | The cached embeddable-archive layer: SHA-256 verification, verified publication into the cache, and the per-archive lock `ensure_cached_archive` returns as an `ArchiveCacheGuard` to hold while using the bytes. | domain | +| [`archive_extract.rs`](../engines/lemonade/src/archive_extract.rs) | The hardened in-process tar.gz and zip extractor for the embeddable archive, and the containment-checked `copy_tree` into the runtime directory. | domain | +| [`backend_alignment.rs`](../engines/lemonade/src/backend_alignment.rs) | Aligning the llama.cpp backend with the ROCm SDK (Tier 1, Tier 2, revert), including the `backend_versions.json` pin and setting ROCm backend directories aside around a forced reinstall. | domain | +| [`device_policy.rs`](../engines/lemonade/src/device_policy.rs) | Device policy and GPU selection: the GPU-required check, `--device`/`--gpu` parsing, the GPU ordinals to pin before a launch, and the device availability `detect` reports. | domain | +| [`direct_llama.rs`](../engines/lemonade/src/direct_llama.rs) | Hugging Face checkpoint and GGUF resolution, and the direct serve path that runs a packaged `llama-server` on a GGUF (`serve_direct_llama_server`). | domain | +| [`footprint.rs`](../engines/lemonade/src/footprint.rs) | What a Lemonade install costs on disk: the pre-install notice and free-space check, and the read-only view of Lemonade's install trees and record. | domain | +| [`install.rs`](../engines/lemonade/src/install.rs) | Embeddable-runtime download, extraction orchestration and manifest persistence, plus the `LemonadeRuntime` handle and `resolve_runtime` over the persisted manifest. | domain | +| [`llamacpp_backend.rs`](../engines/lemonade/src/llamacpp_backend.rs) | llama.cpp backend discovery and selection: asks `lemonade backends` what the host supports, picks and installs the best GPU backend, and finds its `llama-server`. | domain | +| [`process.rs`](../engines/lemonade/src/process.rs) | `lemond` spawn, environment and path setup, readiness and health polling, and the background relaunch of the `serve-http` command. | domain | +| [`runtime_dir.rs`](../engines/lemonade/src/runtime_dir.rs) | `XDG_RUNTIME_DIR` tier 1, 2 and 3 hardening for the spawned child. | domain | +| [`state.rs`](../engines/lemonade/src/state.rs) | Service state file I/O and port and endpoint helpers. | domain | +| [`test_support.rs`](../engines/lemonade/src/test_support.rs) | Test-only fixtures shared by the crate's module tests. | flat | + +Boundaries: + +- **GPU required, no CPU fallback.** [`device_policy.rs`](../engines/lemonade/src/device_policy.rs) refuses a CPU-only request rather than downgrading it, and [`llamacpp_backend.rs`](../engines/lemonade/src/llamacpp_backend.rs) prefers `rocm`, then `vulkan`, and never picks `cpu`. +- **Layering.** + - Outside test code the modules form no import cycle: [`backend_alignment.rs`](../engines/lemonade/src/backend_alignment.rs) uses [`llamacpp_backend.rs`](../engines/lemonade/src/llamacpp_backend.rs), which uses [`direct_llama.rs`](../engines/lemonade/src/direct_llama.rs), which uses [`process.rs`](../engines/lemonade/src/process.rs), and none of them imports back. + - [`install.rs`](../engines/lemonade/src/install.rs) owns `LemonadeRuntime` and `resolve_runtime` so that [`state.rs`](../engines/lemonade/src/state.rs), [`process.rs`](../engines/lemonade/src/process.rs) and [`direct_llama.rs`](../engines/lemonade/src/direct_llama.rs) reach the manifest without importing [`backend_alignment.rs`](../engines/lemonade/src/backend_alignment.rs). +- **Shared test support.** The archive property-test support (`archive_props`) is included once at the crate root, so [`archive_extract.rs`](../engines/lemonade/src/archive_extract.rs) and [`install.rs`](../engines/lemonade/src/install.rs) both reach it as `crate::archive_props`. +- **Exports for `apps/rocm`.** [`footprint.rs`](../engines/lemonade/src/footprint.rs)'s install-tree view is re-exported at the crate root for `rocm storage` and `rocm runtimes uninstall`. + +### `engines/vllm` + +The vLLM engine adapter (`rocm-engine-vllm`): installs vLLM into a managed TheRock runtime with `uv`, then launches, probes and stops the vLLM server. Its modules follow full domain extraction; [`lib.rs`](../engines/vllm/src/lib.rs) keeps only dispatch and the few items shared across them. + +| File | Responsibility | Class | +| --- | --- | --- | +| [`lib.rs`](../engines/vllm/src/lib.rs) | Crate root: CLI and envelope dispatch and the few items shared across the modules, including `verified_torchaudio_release` for the `rocm` binary, a `pub fn` here that delegates to the `pub(crate)` one in [`wheel_builds.rs`](../engines/vllm/src/wheel_builds.rs) (it is not a `pub use`). | flat | +| [`main.rs`](../engines/vllm/src/main.rs) | The `rocm-engine-vllm` binary's entry point; it only calls `rocm_engine_vllm::run_cli()`. | flat | +| [`discover_builds.rs`](../engines/vllm/src/discover_builds.rs) | The ROCm 10.x discovery table (`VLLM_ROCM_DISCOVER_BUILD_TABLE`, one row per supported `major.minor` line), its lookup and the series matcher. | domain | +| [`install.rs`](../engines/vllm/src/install.rs) | ROCm and vLLM install execution through `uv`, by the static-pin route or the ROCm 10.x discovery route. | domain | +| [`process.rs`](../engines/vllm/src/process.rs) | The resolve-model, launch, serve and stop handlers: recipe validation, device-policy and GPU-index resolution, the vLLM server spawn and launch environment, and readiness polling. | domain | +| [`repair.rs`](../engines/vllm/src/repair.rs) | Whether an already-resolvable managed vLLM environment violates vLLM's pinned dependencies and must be reinstalled (`assess_runtime_repair`), treating the SDK's torch build and a user-chosen torch stack (torch, torchvision, torchaudio, triton) with alignment disabled as intended. | domain | +| [`runtime.rs`](../engines/vllm/src/runtime.rs) | TheRock managed-runtime resolution and library and bin path derivation, plus the launch path's compat-shim writes (`ensure_therock_compat_shims`). | domain | +| [`startup_diagnostics.rs`](../engines/vllm/src/startup_diagnostics.rs) | What a failed startup tells the user (`startup_log_context`): the tail of the startup log, then the out-of-memory and import-failure hints that point at `rocm diagnose`. | domain | +| [`state.rs`](../engines/vllm/src/state.rs) | Service state file I/O, log tailing, and health and inference probing. | domain | +| [`wheel_builds.rs`](../engines/vllm/src/wheel_builds.rs) | Which vLLM wheels to install for a ROCm SDK version: the static build table, the install-route choice (`vllm_install_route`) and target resolution with the `ROCM_CLI_VLLM_ROCM_INDEX_URL` override. | domain | + +Boundaries: + +- **One discovery table.** [`discover_builds.rs`](../engines/vllm/src/discover_builds.rs) is the single list of the ROCm SDK versions installed by discovery: install routing, the fail-closed static fallback and launch-time environment setup all read its rows, and nothing keeps a second list in step with them. It is a leaf that imports no other module of the crate, which does not keep its readers apart: [`install.rs`](../engines/vllm/src/install.rs) imports [`runtime.rs`](../engines/vllm/src/runtime.rs) and [`wheel_builds.rs`](../engines/vllm/src/wheel_builds.rs), and all three read the table. +- **Layering.** [`install.rs`](../engines/vllm/src/install.rs) reads [`wheel_builds.rs`](../engines/vllm/src/wheel_builds.rs) and [`discover_builds.rs`](../engines/vllm/src/discover_builds.rs) and asks [`repair.rs`](../engines/vllm/src/repair.rs) whether an install pass is needed; none of them imports [`install.rs`](../engines/vllm/src/install.rs). +- **Path derivation writes nothing.** [`runtime.rs`](../engines/vllm/src/runtime.rs)'s path derivation performs no filesystem writes; the compat-shim writes are `ensure_therock_compat_shims`, called only from [`process.rs`](../engines/vllm/src/process.rs), and the running-state payload never calls it. +- **Rendered, not stripped.** [`startup_diagnostics.rs`](../engines/vllm/src/startup_diagnostics.rs) re-renders the log tail line by line through `terminal::rendered_lines` instead of stripping it, because stripping deletes line-break tokens and welds a progress-bar repaint onto the next line. + +### `engines/aim` + +The AIM engine adapter (`rocm-engine-aim`) runs models as Docker containers instead of a host process, so it has no venv, wheel or runtime archive to manage. + +| File | Responsibility | Class | +| --- | --- | --- | +| [`lib.rs`](../engines/aim/src/lib.rs) | Crate root: CLI and envelope dispatch, including the `builtin_*` entry points the `rocm` binary calls in-process, the detect and capabilities responses, and the items shared across the modules. | flat | +| [`main.rs`](../engines/aim/src/main.rs) | The `rocm-engine-aim` binary's entry point; it only calls `rocm_engine_aim::run_cli()`. | flat | +| [`docker.rs`](../engines/aim/src/docker.rs) | A thin wrapper around the `docker` CLI binary, with no Docker API client, and `container_name`, a service's deterministic Docker-safe container name. | flat | +| [`install.rs`](../engines/aim/src/install.rs) | Install for an engine whose images are self-contained: only a check that Docker is present and reachable. | flat | +| [`process.rs`](../engines/aim/src/process.rs) | The container run, readiness and stop lifecycle, including `serve_http`, which blocks for the container's lifetime and records how it ended. | flat | +| [`registry.rs`](../engines/aim/src/registry.rs) | AIM image metadata (`Env`/`Labels`), read from the local daemon once the image is pulled, with a best-effort Docker Hub v2 lookup as a pre-pull hint. | flat | +| [`state.rs`](../engines/aim/src/state.rs) | Service state file I/O, including the model name the container actually serves (`served_model_id`) and `endpoint_url`, the `/v1` base URL for a host and port. | flat | + +Boundaries: + +- **Supervised by `rocmd`.** [`process.rs`](../engines/aim/src/process.rs)'s `serve_http` is the process `rocmd` supervises: it records a crash or a vanished container as `failed` with a non-zero exit, so recovery runs. +- **The Docker Hub lookup is only a hint.** A failure of [`registry.rs`](../engines/aim/src/registry.rs)'s pre-pull lookup never blocks a launch. +- **Layering.** `container_name` lives in [`docker.rs`](../engines/aim/src/docker.rs) so that [`process.rs`](../engines/aim/src/process.rs) and [`state.rs`](../engines/aim/src/state.rs) both reach it there; [`process.rs`](../engines/aim/src/process.rs) imports [`state.rs`](../engines/aim/src/state.rs), and [`state.rs`](../engines/aim/src/state.rs) uses no [`process.rs`](../engines/aim/src/process.rs) item. + +### `xtask` — repository tooling (the `cargo xtask` command surface) + +Repository tasks, run through the workspace alias `cargo xtask `: release packaging and signing, generated-file checks, the pre-push and CI helpers, and the repository's source-scan contract tests. Nothing here ships in a release bundle. `cargo xtask check-architecture-doc` fails when a `.rs` file under `xtask/src` has no row here, with no helper exemption. + +| File | Responsibility | Class | +| --- | --- | --- | +| [`main.rs`](../xtask/src/main.rs) | The clap command tree and its dispatch: most `cargo xtask` commands dispatch to a module of their own. | flat | +| [`affected.rs`](../xtask/src/affected.rs) | `cargo xtask affected`: the crates a git range changes plus their transitive dependents, as cargo package flags, falling back to `--workspace` for any file it cannot attribute. | flat | +| [`amd_smi_launch_contract.rs`](../xtask/src/amd_smi_launch_contract.rs) | Source-scan test pinning which call sites may resolve the `amd-smi` binary, so every launch passes the `/dev/kfd` pre-flight. | flat | +| [`architecture_doc.rs`](../xtask/src/architecture_doc.rs) | `cargo xtask check-architecture-doc`: fails when a production source file under `apps/`, `crates/` or `engines/`, or a `.rs` file under `xtask/src`, `tests/e2e-cucumber/src` or `tests/e2e-cucumber/tests`, has no link in this document. | flat | +| [`ascii_output_contract.rs`](../xtask/src/ascii_output_contract.rs) | Source-scan test that a string literal able to reach a redirectable stream or an on-disk file is ASCII-only. | flat | +| [`catalog.rs`](../xtask/src/catalog.rs) | `cargo xtask catalog`: regenerates or checks the published Doctor catalog manifest, rendered from the compiled catalog in `rocm-core`. | flat | +| [`chat_import_contract.rs`](../xtask/src/chat_import_contract.rs) | Source-scan test that the freeform planner and the leaf modules it shares with [`chat.rs`](../apps/rocm/src/chat.rs) never import `chat` in production code. | flat | +| [`coverage.rs`](../xtask/src/coverage.rs) | `cargo xtask coverage`: checks every crate's line coverage against its floor in [`coverage-floors.toml`](../coverage-floors.toml), or rewrites the floors with `--bless`. | flat | +| [`crate_edges.rs`](../xtask/src/crate_edges.rs) | `cargo xtask check-crate-edges`: fails on any first-party normal or build dependency edge missing from its `ALLOWLIST`. | flat | +| [`dash_text_edit_contract.rs`](../xtask/src/dash_text_edit_contract.rs) | Source-scan test that dash-TUI text fields edit through `apply_char_key` in [`widgets.rs`](../crates/rocm-dash-tui/src/ui/widgets.rs), not hand-rolled `push`/`pop` code. | flat | +| [`demos.rs`](../xtask/src/demos.rs) | `cargo xtask demos`: builds the demo binaries, starts the mock environment before VHS runs, and renders the documentation GIFs. | flat | +| [`e2e.rs`](../xtask/src/e2e.rs) | `cargo xtask e2e`: builds release `rocm` and `rocmd` with the E2E test features and runs the cucumber suite, forwarding extra arguments to cucumber. | flat | +| [`e2e_prewarm.rs`](../xtask/src/e2e_prewarm.rs) | `cargo xtask e2e-prewarm`: prepares the shared managed runtime the GPU E2E lanes serve against, refreshing it when the channel index publishes something newer or the required packages differ. | flat | +| [`e2e_report.rs`](../xtask/src/e2e_report.rs) | `cargo xtask e2e-report`: merges per-platform `report.json` files into one HTML report and a step-summary matrix, one platform per artifact subdirectory. | flat | +| [`engine_stdio_client_contract.rs`](../xtask/src/engine_stdio_client_contract.rs) | Source-scan test that only the shared stdio client in [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs) puts a request on an engine child's stdin: a file that both pipes a child's stdin and names an engine envelope is reported unless it is a reviewed `ALLOWED` entry, and a stale entry fails too. | flat | +| [`env_mutation_contract.rs`](../xtask/src/env_mutation_contract.rs) | Source-scan test that every test which mutates the process environment serializes itself. | flat | +| [`eval_fixtures.rs`](../xtask/src/eval_fixtures.rs) | `cargo xtask eval-fixtures`: regenerates or checks the recorded `rocm` output the rocm-doctor skill evals replay, rendered from the compiled catalog. | flat | +| [`lychee.rs`](../xtask/src/lychee.rs) | `cargo xtask lychee`: runs lychee with [`lychee.toml`](../lychee.toml) over the working tree, the local counterpart of the `docs-links` CI job. | flat | +| [`manifest.rs`](../xtask/src/manifest.rs) | `cargo xtask manifest`: regenerates or checks the Cargo dependency table in [`MANIFEST.md`](../MANIFEST.md) from `cargo metadata`. | flat | +| [`module_size.rs`](../xtask/src/module_size.rs) | `cargo xtask check-module-size`: fails when a source file exceeds `MAX_PRODUCTION_LINES` production lines, or when a `.rs` file under a crate's `src/` is declared by no `mod`. | flat | +| [`package.rs`](../xtask/src/package.rs) | `cargo xtask package`: builds the release bundle directory from built binaries, its archive, the SHA-256 sidecar and, when a key is configured, a detached signature. | flat | +| [`paths.rs`](../xtask/src/paths.rs) | Workspace paths shared by the tasks: the workspace root, the active `target/` directory, release binary locations and platform executable names. | flat | +| [`powershell.rs`](../xtask/src/powershell.rs) | `cargo xtask powershell-lint`: runs PSScriptAnalyzer over `.ps1` files through `pwsh` or Windows PowerShell, which also reports syntax errors. | flat | +| [`prepush.rs`](../xtask/src/prepush.rs) | `cargo xtask pre-push-check`: runs one pre-push cargo step over only the crates the push affects, falling back to the whole workspace when that is unknown. | flat | +| [`prepush_stamp.rs`](../xtask/src/prepush_stamp.rs) | Pass stamps for `pre-push-check`: records a step that passed on a clean tree, keyed by tree hash, arguments, toolchain and environment, and skips it next time. | flat | +| [`proptest_regressions_contract.rs`](../xtask/src/proptest_regressions_contract.rs) | Source-scan test that every saved proptest seed file maps back to a source file that still holds a `proptest!` block. | flat | +| [`release_readiness.rs`](../xtask/src/release_readiness.rs) | `cargo xtask release-readiness`: the nightly GO/NO-GO verdict and status table from git, `gh`, job results and the E2E report, plus the facts the narrative step drafts from. | flat | +| [`report_mailbox.rs`](../xtask/src/report_mailbox.rs) | Reads Doctor reports out of exported `.eml` mail, keeping only the headers the rollup needs and reducing `Date` to a week. | flat | +| [`report_rollup.rs`](../xtask/src/report_rollup.rs) | `cargo xtask report-rollup`: counts received Doctor reports by problem group and week from exported mail or JSON bodies; it reads and prints, and sends nothing. | flat | +| [`rocm_releases.rs`](../xtask/src/rocm_releases.rs) | Checked-in table resolving the E2E `sdk_version` labels (`current`, `n-1`, `n-2`) to TheRock package versions, with no pin for `current`, updated by hand. | flat | +| [`rust_source.rs`](../xtask/src/rust_source.rs) | Lexical helpers for the source-scan tests, chiefly `strip_literals_and_comments`, so every contract skips literals and comments the same way. | flat | +| [`signing.rs`](../xtask/src/signing.rs) | The `keygen`, `sign` and `verify` commands: the file I/O layer over the RSA release-artifact signing in `rocm-core`. | flat | +| [`tpn.rs`](../xtask/src/tpn.rs) | `cargo xtask tpn`: regenerates or checks [`THIRD_PARTY_NOTICES.txt`](../THIRD_PARTY_NOTICES.txt) through cargo-about with the committed config and template. | flat | +| [`verify_commits.rs`](../xtask/src/verify_commits.rs) | `cargo xtask verify-commits`: checks that every commit in a range is signed and carries a DCO `Signed-off-by` trailer, or only that signing is configured. | flat | +| [`verify_pinned_keys.rs`](../xtask/src/verify_pinned_keys.rs) | `cargo xtask verify-pinned-keys`: checks that the public keys pinned in the installers and the CLI match the canonical keys under `docs/keys/`. | flat | +| [`workflow_contract.rs`](../xtask/src/workflow_contract.rs) | Source-scan tests over the GitHub workflow files and CI scripts: lane placement and concurrency groups, runner labels, timeouts, permissions and other CI invariants. | flat | + +Boundaries: + +- The eight `*_contract.rs` files define no command: each is one `#[cfg(test)]` module run by `cargo test -p xtask`, and [`rust_source.rs`](../xtask/src/rust_source.rs) is declared test-only in [`main.rs`](../xtask/src/main.rs). The pull-request test selection narrows to the crates a change touches, so a change confined to another crate may not select them there; pushes to `main` and the merge queue run the whole workspace. +- [`affected.rs`](../xtask/src/affected.rs) is the one crate selection used by both CI's affected-crates job and [`prepush.rs`](../xtask/src/prepush.rs), which only widens it with `CROSS_CRATE_READS`; a change to how files are attributed to crates changes both. +- [`paths.rs`](../xtask/src/paths.rs) defines the workspace root, the active target directory and binary file names, honouring `CARGO_TARGET_DIR` and a cross-compilation target; a new task uses it rather than recomputing them. + +### `tests/e2e-cucumber` — black-box end-to-end suite + +Gherkin `.feature` files under `features/` backed by Rust step functions that drive the real `rocm` (and, where a scenario needs it, `rocmd`) binary against a mock server or real GPU serving; see the crate [README](../tests/e2e-cucumber/README.md) and [testing.md](testing.md). The suite runs through `cargo xtask e2e`. `cargo xtask check-architecture-doc` fails when a `.rs` file under `src/` or `tests/` here has no row, with no helper exemption. + +#### `src/` + +| File | Responsibility | Class | +| --- | --- | --- | +| [`src/lib.rs`](../tests/e2e-cucumber/src/lib.rs) | Library root for the test targets and the demo binary: declares the helper modules, re-exports `e2e-report` as `report`, and holds small shared helpers such as `cli_failure_report`. | flat | +| [`src/binary_path.rs`](../tests/e2e-cucumber/src/binary_path.rs) | Pins a relative `ROCM_CLI_BINARY` path before a scenario runs the child from another directory, and leaves a bare name for `PATH` to resolve. | flat | +| [`src/capability.rs`](../tests/e2e-cucumber/src/capability.rs) | Host capability probe: runs `rocm examine` and `rocm engines list` once, and re-derives the serve engine the CLI would pick and the AMD GPU count. | flat | +| [`src/chat_request.rs`](../tests/e2e-cucumber/src/chat_request.rs) | The chat round trip against a served endpoint (model discovery, then one chat completion), run on its own task so its timeout measures the server. | flat | +| [`src/device_memory.rs`](../tests/e2e-cucumber/src/device_memory.rs) | Which device memory pool (VRAM, or GTT-backed memory on an APU) the drain-wait between serve scenarios judges, how it is sampled, and the free-memory floor. | flat | +| [`src/expectation.rs`](../tests/e2e-cucumber/src/expectation.rs) | Resolves each scenario on this host to expected-pass, expected-fail or skip from its tags, the capability probe and the [`expectations.toml`](../tests/e2e-cucumber/expectations.toml) matrix. | flat | +| [`src/fixture_binary.rs`](../tests/e2e-cucumber/src/fixture_binary.rs) | Locates a fake-subprocess `[[bin]]` of this crate next to the running test binary. | flat | +| [`src/harness_diagnostics.rs`](../tests/e2e-cucumber/src/harness_diagnostics.rs) | Records a panic that escapes the cucumber run, which cucumber's silenced panic hook would hide, and the state of the standard streams, to stderr and a results-dir log. | flat | +| [`src/http_server.rs`](../tests/e2e-cucumber/src/http_server.rs) | Shared `axum` test-server plumbing: bind an ephemeral loopback port, serve a router, shut down on drop. | flat | +| [`src/installer_fixture.rs`](../tests/e2e-cucumber/src/installer_fixture.rs) | `with_pinned_release_keys`: a copy of the PowerShell installer with its two pinned-key assignments replaced, failing on any shape it does not expect. | flat | +| [`src/lemonade_diagnostics.rs`](../tests/e2e-cucumber/src/lemonade_diagnostics.rs) | Read-only backend evidence for a failed Lemonade serve, read from disk before the service stops and probed with `llama-server` after. | flat | +| [`src/loopback_http.rs`](../tests/e2e-cucumber/src/loopback_http.rs) | Loopback file server (`tower_http`'s `ServeDir`) that install, artifact and release-index scenarios point the real installer or CLI at. | flat | +| [`src/mock_server.rs`](../tests/e2e-cucumber/src/mock_server.rs) | The mock OpenAI-compatible server (fixed, scripted, rejecting or metrics-serving) and the writer for planted managed-service records. | flat | +| [`src/model_id.rs`](../tests/e2e-cucumber/src/model_id.rs) | `model_ids_match`: whether the model id a server reports names the requested model, across Lemonade file names and vLLM repo ids. | flat | +| [`src/monotonic_clock.rs`](../tests/e2e-cucumber/src/monotonic_clock.rs) | Rebuilds a non-decreasing timeline from cucumber's wall-clock event stamps so the JSON and JUnit writers never panic on a clock that stepped back. | flat | +| [`src/paced_download.rs`](../tests/e2e-cucumber/src/paced_download.rs) | Loopback server that serves one named file in delayed chunks, so a PTY scenario can see intermediate download-progress frames. | flat | +| [`src/palette_rows.rs`](../tests/e2e-cucumber/src/palette_rows.rs) | Which destination rows of the dashboard's command palette a rendered screen still lacks. | flat | +| [`src/panic_capture.rs`](../tests/e2e-cucumber/src/panic_capture.rs) | Panic-message extraction and mutex-poison recovery for drivers that run background threads. | flat | +| [`src/planted_path.rs`](../tests/e2e-cucumber/src/planted_path.rs) | The `PATH` handed to the `rocm` child when a scenario plants its own `rocminfo`, dropping runner entries that hold one. | flat | +| [`src/polled_deadline.rs`](../tests/e2e-cucumber/src/polled_deadline.rs) | `PolledDeadline`: a retry-loop deadline that counts only the time the loop was polled, with a wall-clock cap. | flat | +| [`src/powershell_text_rule.rs`](../tests/e2e-cucumber/src/powershell_text_rule.rs) | The text rule for the Windows lines `rocm fix` and `rocm diagnose` print, a copy of the rule in `rocm-core` checked against a shared fixture table. | flat | +| [`src/quit_and_wait.rs`](../tests/e2e-cucumber/src/quit_and_wait.rs) | Retry loop for quitting a TUI that may open a quit-confirm prompt first. | flat | +| [`src/reader_failure.rs`](../tests/e2e-cucumber/src/reader_failure.rs) | Failure state shared between a background terminal reader and its waiters. | flat | +| [`src/runtime_root.rs`](../tests/e2e-cucumber/src/runtime_root.rs) | `check_runtime_root_not_nested`: judges the active runtime folder `rocm examine` prints and rejects a doubly nested `runtimes/wheel` path. | flat | +| [`src/send_until.rs`](../tests/e2e-cucumber/src/send_until.rs) | Retry loop for sending an idempotent terminal input until its effect appears. | flat | +| [`src/serve_log.rs`](../tests/e2e-cucumber/src/serve_log.rs) | Reads back a managed serve's service log and builds the failure report for a serve step, quoting the log tail. | flat | +| [`src/serve_plan.rs`](../tests/e2e-cucumber/src/serve_plan.rs) | Explains why a `rocm serve` run printed no `resolved model:` line by keeping stderr's refusal alongside stdout. | flat | +| [`src/shared_runtime.rs`](../tests/e2e-cucumber/src/shared_runtime.rs) | Picks which runtime a scenario activates out of the shared pre-warmed runtime tree, which may hold more than one. | flat | +| [`src/stand_in_uname.rs`](../tests/e2e-cucumber/src/stand_in_uname.rs) | The shell script a scenario plants as a stand-in `uname`: `-v` answers a fixed string, `-r` runs a fragment the scenario chooses, and every call is logged so a scenario can count how often the kernel release was asked for. | flat | +| [`src/stray_process.rs`](../tests/e2e-cucumber/src/stray_process.rs) | What scenario teardown does about a process a scenario started and recorded: only a process that is still the one recorded is ended, never one that has since exited or whose PID another process has taken. Decided apart from the system reads, so a table test covers each case on every host. | flat | +| [`src/tasklist.rs`](../tests/e2e-cucumber/src/tasklist.rs) | What `tasklist` says about one process, read so that a failed query cannot pass for an answer: the exit status is judged before the text, so a run that did not succeed gives no answer rather than "the process exited". Pure, so a table test covers every case on every host. | flat | +| [`src/terminal_size.rs`](../tests/e2e-cucumber/src/terminal_size.rs) | Validates a requested terminal size and applies it to the emulated screen before the real PTY. | flat | + +#### `src/bin/` + +| File | Responsibility | Class | +| --- | --- | --- | +| [`src/bin/fake-docker.rs`](../tests/e2e-cucumber/src/bin/fake-docker.rs) | A `docker` stand-in that always fails, optionally logging its arguments, for the AIM Docker-unavailable scenarios. | flat | +| [`src/bin/fake-python.rs`](../tests/e2e-cucumber/src/bin/fake-python.rs) | A stand-in for the runtime's Python that answers the ComfyUI install's torch-stack probe and post-install GPU check. | flat | +| [`src/bin/fake-tailscale.rs`](../tests/e2e-cucumber/src/bin/fake-tailscale.rs) | A Tailscale CLI stand-in that serves the status document named by `FAKE_TAILSCALE_STATUS`, for the `rocm remote` scenarios. | flat | +| [`src/bin/fake-uv.rs`](../tests/e2e-cucumber/src/bin/fake-uv.rs) | A `uv` stand-in whose output, exit code, argument log and stdin handling are set by `FAKE_UV_*` variables, for the ComfyUI scenarios. | flat | +| [`src/bin/rocm-demo-env.rs`](../tests/e2e-cucumber/src/bin/rocm-demo-env.rs) | Standalone mock environment for the VHS demos: starts the mock server, plants a service record and prints the env vars `cargo xtask demos` exports. | flat | + +#### `tests/` + +| File | Responsibility | Class | +| --- | --- | --- | +| [`tests/driver_host_guard.rs`](../tests/e2e-cucumber/tests/driver_host_guard.rs) | Ordinary test that the Windows driver-install steps run the host guard before calling the CLI, checked against the step source. | flat | +| [`tests/e2e.rs`](../tests/e2e-cucumber/tests/e2e.rs) | The cucumber test binary: the `E2eWorld` state and its cleanup on drop, the `run_rocm` helpers, the runner `main`, and reconciliation of results with expectations. | flat | +| [`tests/feature_naming.rs`](../tests/e2e-cucumber/tests/feature_naming.rs) | Drift guard, in the ordinary `cargo test` set, for the `-` scenario names and ids in the `.feature` files. | flat | +| [`tests/skill_reference.rs`](../tests/e2e-cucumber/tests/skill_reference.rs) | Drift guard, in the ordinary `cargo test` set, that the catalog table in [`reference.md`](../skills/rocm-doctor/reference.md) uses the vocabulary `rocm fix` prints. | flat | + +#### `tests/e2e/` + +| File | Responsibility | Class | +| --- | --- | --- | +| [`tests/e2e/artifact_steps.rs`](../tests/e2e-cucumber/tests/e2e/artifact_steps.rs) | Steps for [`artifact_prefetch.feature`](../tests/e2e-cucumber/features/artifact_prefetch.feature): a signed direct-download artifact, its approved prefetch, and a cache marker that cannot be published. | flat | +| [`tests/e2e/automations_steps.rs`](../tests/e2e-cucumber/tests/e2e/automations_steps.rs) | Steps for [`automations.feature`](../tests/e2e-cucumber/features/automations.feature): `rocm automations` enable, disable and listing, with the daemon planted as already running so none is spawned. | flat | +| [`tests/e2e/bench_steps.rs`](../tests/e2e-cucumber/tests/e2e/bench_steps.rs) | Steps for [`bench.feature`](../tests/e2e-cucumber/features/bench.feature): the chat route `rocm bench load` posts to, and an all-failed run reported as a failure. | flat | +| [`tests/e2e/bootstrap_steps.rs`](../tests/e2e-cucumber/tests/e2e/bootstrap_steps.rs) | Steps for [`bootstrap.feature`](../tests/e2e-cucumber/features/bootstrap.feature): the non-interactive fallback of `rocm bootstrap setup`, run piped. | flat | +| [`tests/e2e/chat_steps.rs`](../tests/e2e-cucumber/tests/e2e/chat_steps.rs) | Steps for [`chat.feature`](../tests/e2e-cucumber/features/chat.feature) and [`networking.feature`](../tests/e2e-cucumber/features/networking.feature): a served mock model, service listing, and chat requests through the API and the CLI. | flat | +| [`tests/e2e/comfyui_steps.rs`](../tests/e2e-cucumber/tests/e2e/comfyui_steps.rs) | Steps for [`comfyui.feature`](../tests/e2e-cucumber/features/comfyui.feature): `rocm comfyui install` against a planted runtime with the `fake-python` and `fake-uv` stand-ins, and runtime selection. | flat | +| [`tests/e2e/config_steps.rs`](../tests/e2e-cucumber/tests/e2e/config_steps.rs) | Steps for [`config.feature`](../tests/e2e-cucumber/features/config.feature): `rocm config` mutations against the scenario's isolated config dir. | flat | +| [`tests/e2e/dash_steps.rs`](../tests/e2e-cucumber/tests/e2e/dash_steps.rs) | Steps for [`dash.feature`](../tests/e2e-cucumber/features/dash.feature) and the TUI scenarios of other features: the dashboard and chat TUI driven through a pseudo-terminal. | flat | +| [`tests/e2e/dependency_guard_steps.rs`](../tests/e2e-cucumber/tests/e2e/dependency_guard_steps.rs) | Steps for [`dependency_guard.feature`](../tests/e2e-cucumber/features/dependency_guard.feature): a stand-in package manager proposes removing the ROCm stack, and the CLI must refuse. | flat | +| [`tests/e2e/diagnose_steps.rs`](../tests/e2e-cucumber/tests/e2e/diagnose_steps.rs) | Steps for [`diagnose.feature`](../tests/e2e-cucumber/features/diagnose.feature): `rocm diagnose` matches and `rocm fix` listings, previews, printed verify commands and failing fixes. | flat | +| [`tests/e2e/driver_steps.rs`](../tests/e2e-cucumber/tests/e2e/driver_steps.rs) | Steps for [`driver_install.feature`](../tests/e2e-cucumber/features/driver_install.feature): previewing and approving GPU driver installation plans on WSL, Linux and Windows hosts. | flat | +| [`tests/e2e/engines_steps.rs`](../tests/e2e-cucumber/tests/e2e/engines_steps.rs) | Steps for [`engine_shell.feature`](../tests/e2e-cucumber/features/engine_shell.feature): `rocm engines shell` under a pseudo-terminal, since the defect shows only in what the terminal renders. | flat | +| [`tests/e2e/examine_steps.rs`](../tests/e2e-cucumber/tests/e2e/examine_steps.rs) | Steps for [`examine.feature`](../tests/e2e-cucumber/features/examine.feature): `rocm examine`, version and help output, engine listing and the driver plan preview. | flat | +| [`tests/e2e/host_guard.rs`](../tests/e2e-cucumber/tests/e2e/host_guard.rs) | The host check the Windows driver-install steps run before any CLI call, kept free of the cucumber world so a separate test can include it. | flat | +| [`tests/e2e/lemonade_install_steps.rs`](../tests/e2e-cucumber/tests/e2e/lemonade_install_steps.rs) | Steps for [`lemonade_installs.feature`](../tests/e2e-cucumber/features/lemonade_installs.feature): what the user is told about the Lemonade copies on disk, from planted trees and install records. | flat | +| [`tests/e2e/lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/lifecycle_steps.rs) | Steps for [`install_lifecycle.feature`](../tests/e2e-cucumber/features/install_lifecycle.feature): `xtask package`, the root installer and the installed binaries, from install through uninstall. | flat | +| [`tests/e2e/logs_steps.rs`](../tests/e2e-cucumber/tests/e2e/logs_steps.rs) | Steps for [`logs.feature`](../tests/e2e-cucumber/features/logs.feature): `rocm logs` searches over command-log files planted inside the tail window it reads. | flat | +| [`tests/e2e/model_catalog_steps.rs`](../tests/e2e-cucumber/tests/e2e/model_catalog_steps.rs) | Steps for [`model_catalog.feature`](../tests/e2e-cucumber/features/model_catalog.feature): the verbose catalog's AIM entry, its Docker-unavailable flag and its staleness warning. | flat | +| [`tests/e2e/planner_steps.rs`](../tests/e2e-cucumber/tests/e2e/planner_steps.rs) | Steps for the planning-assistant scenarios in [`chat.feature`](../tests/e2e-cucumber/features/chat.feature), with a scripted mock proving a request is handed over once and its plan is the one shown. | flat | +| [`tests/e2e/remote_steps.rs`](../tests/e2e-cucumber/tests/e2e/remote_steps.rs) | Steps for [`remote.feature`](../tests/e2e-cucumber/features/remote.feature): `rocm remote` against the `fake-tailscale` stand-in and a status document the step writes. | flat | +| [`tests/e2e/runtime_lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs) | Steps for [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` activate, rollback, uninstall and import over planted read-only tarball runtimes. | flat | +| [`tests/e2e/runtime_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_steps.rs) | Steps for [`runtime_setup.feature`](../tests/e2e-cucumber/features/runtime_setup.feature): SDK install previews and installs, runtime folders reached through a link, and the managed runtime they leave active. | flat | +| [`tests/e2e/service_cleanup_steps.rs`](../tests/e2e-cucumber/tests/e2e/service_cleanup_steps.rs) | Steps for [`service_record_cleanup.feature`](../tests/e2e-cucumber/features/service_record_cleanup.feature): `rocm services remove` and `prune` over planted service records, asserting on the files that survive, and [`service_record_unqueryable.feature`](../tests/e2e-cucumber/features/service_record_unqueryable.feature): a record whose process cannot be queried (the `e2e-test-hooks` build reads `ROCM_E2E_UNQUERYABLE_PIDS`) is stopped as unverified, refused by `remove`, and cleared by `remove --force` only when no recorded process is confirmed running. | flat | +| [`tests/e2e/service_stop_steps.rs`](../tests/e2e-cucumber/tests/e2e/service_stop_steps.rs) | Steps for [`service_stop.feature`](../tests/e2e-cucumber/features/service_stop.feature) and [`engine_ipc.feature`](../tests/e2e-cucumber/features/engine_ipc.feature): `rocm services stop` and the daemon's `stop_server` tool against a planted service record, and how the daemon reads what an engine child prints, with a stand-in `rocm` staged beside a copy of `rocmd`; and the confirmed stop against a real recorded process, a recorded PID that now belongs to a different process, and a parent that has started a child. | flat | +| [`tests/e2e/service_unknown_id_steps.rs`](../tests/e2e-cucumber/tests/e2e/service_unknown_id_steps.rs) | Steps for [`service_unknown_id.feature`](../tests/e2e-cucumber/features/service_unknown_id.feature): commands that name a local server with no record, checked against the listing they point to. | flat | +| [`tests/e2e/serving_steps.rs`](../tests/e2e-cucumber/tests/e2e/serving_steps.rs) | Steps for [`model_serving.feature`](../tests/e2e-cucumber/features/model_serving.feature) and the serve steps other features reuse: `rocm serve` on each engine, ports, managed services and inference. | flat | +| [`tests/e2e/skill_steps.rs`](../tests/e2e-cucumber/tests/e2e/skill_steps.rs) | Steps for [`rocm_doctor_skill.feature`](../tests/e2e-cucumber/features/rocm_doctor_skill.feature): drive `rocm` through the sequence the rocm-doctor skill prescribes and check its literal claims. | flat | +| [`tests/e2e/storage_steps.rs`](../tests/e2e-cucumber/tests/e2e/storage_steps.rs) | Steps for [`storage.feature`](../tests/e2e-cucumber/features/storage.feature) and [`local_server_records.feature`](../tests/e2e-cucumber/features/local_server_records.feature): `rocm storage report` and the confirmation gate on `remove-downloads`. | flat | +| [`tests/e2e/therock_steps.rs`](../tests/e2e-cucumber/tests/e2e/therock_steps.rs) | Steps for [`therock_next_generation.feature`](../tests/e2e-cucumber/features/therock_next_generation.feature) and [`download_progress_pty.feature`](../tests/e2e-cucumber/features/download_progress_pty.feature): release layouts served from a loopback server, and one real GPU install. | flat | +| [`tests/e2e/tui_driver.rs`](../tests/e2e-cucumber/tests/e2e/tui_driver.rs) | Pseudo-terminal driver for the dash and chat TUI: spawns the real binary under `portable-pty`, sends keys and reads the emulated `vt100` screen. | flat | +| [`tests/e2e/uninstall_steps.rs`](../tests/e2e-cucumber/tests/e2e/uninstall_steps.rs) | Steps for [`uninstall.feature`](../tests/e2e-cucumber/features/uninstall.feature): `rocm uninstall` confined to the scenario root with `--keep-binaries` and redirected caches. | flat | +| [`tests/e2e/update_steps.rs`](../tests/e2e-cucumber/tests/e2e/update_steps.rs) | Steps for [`update.feature`](../tests/e2e-cucumber/features/update.feature): the report-only `rocm update`, its feed status, and a loopback catalog where runtimes are planted. | flat | + +Boundaries: + +- **Test targets.** The `e2e` target behaves differently from the rest: + - [`tests/e2e.rs`](../tests/e2e-cucumber/tests/e2e.rs) declares every `tests/e2e/` module in an inline `mod e2e`, and its target is `harness = false` and `test = false`, so the default test run skips it and `cargo xtask e2e` is how it normally runs. + - A plain `#[test]` inside that target never runs: pure logic that needs unit tests goes in `src/`, or is included by a separate test target through `#[path]`, as [`tests/driver_host_guard.rs`](../tests/e2e-cucumber/tests/driver_host_guard.rs) includes [`tests/e2e/host_guard.rs`](../tests/e2e-cucumber/tests/e2e/host_guard.rs). +- The library target depends on no product crate. `rocm-core` is a dev-dependency only, used by unit tests and the `e2e` target, so library code repeats what it needs (as `device_memory::bounded_stdout` does) rather than add an edge `cargo xtask check-crate-edges` would flag. +- The report generator lives in [`crates/e2e-report`](../crates/e2e-report/src/lib.rs) so `xtask` can use it without this crate's dependency tree; [`src/lib.rs`](../tests/e2e-cucumber/src/lib.rs) re-exports it as `report`. +- **Copies of product logic that drift.** A product change here means a change in the suite: + - [`src/capability.rs`](../tests/e2e-cucumber/src/capability.rs) re-implements the CLI's serve-engine choice and the AMD GPU count. + - [`src/powershell_text_rule.rs`](../tests/e2e-cucumber/src/powershell_text_rule.rs) copies the rule in [`fix/catalog.rs`](../crates/rocm-core/src/fix/catalog.rs); both are tested against [`powershell_text_rule_cases.txt`](../tests/e2e-cucumber/fixtures/powershell_text_rule_cases.txt). + - `cargo xtask demos` parses what [`src/bin/rocm-demo-env.rs`](../tests/e2e-cucumber/src/bin/rocm-demo-env.rs) prints. + +## History + +The crate roots (`apps/rocm`'s [`main.rs`](../apps/rocm/src/main.rs), `rocm-core`'s [`lib.rs`](../crates/rocm-core/src/lib.rs), `apps/rocmd`'s [`lib.rs`](../apps/rocmd/src/lib.rs) and others) once held most of their crate in one file and were split into the modules mapped above. Use `git log --follow ` for the history of a single module. This document describes only the current structure. diff --git a/docs/host-probing.md b/docs/host-probing.md index e98bf76b1..097a97025 100644 --- a/docs/host-probing.md +++ b/docs/host-probing.md @@ -8,7 +8,7 @@ SPDX-License-Identifier: MIT Status: proposal, with the first three pairs and the first step of the last delivered. This note changes no code and no behaviour itself, and what it proposes for a pair is decided by the change that converges that pair, which then records the decision here (the PATH lookup, pair 1, the kernel release, pair 2, and the CPU model, pair 3, have: see "PATH lookup", "Kernel version" and "CPU model"; the first step of the subprocess runners, pair 6, has: see "Decided and delivered, first step" under "Subprocess runners"). It lists the host facts that `rocm-core` reads twice (on the hosts each is read on, see "Which host reads which fact"), says how the two reads differ, and proposes which one should survive and in what order a later series of changes could remove the other. Each pair is meant to be a separate change with its own review. -This note is a snapshot of `main` at the time of writing, not maintained documentation. It is to be retired (the file deleted, together with its entry in [architecture.md](architecture.md)) when the convergence tickets for these pairs close, so the inventory does not keep pointing at a stale design record. +This note is a snapshot of `main` at the time of writing, not maintained documentation. It is to be retired when the convergence tickets for these pairs close, so the inventory does not keep pointing at a stale design record. Retiring it means deleting this file, removing the link to it from the host-probing bullet in the `crates/rocm-core` Boundaries of [architecture.md](architecture.md) (that bullet is the only entry it has; it is not a table row), and rewording the comments in `rocm-core` that cite it by name or as "the host-probing note" ([`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs), [`command_capture.rs`](../crates/rocm-core/src/command_capture.rs), [`host_gpu/capture.rs`](../crates/rocm-core/src/host_gpu/capture.rs), [`host_gpu/os_facts.rs`](../crates/rocm-core/src/host_gpu/os_facts.rs), [`process/bounded.rs`](../crates/rocm-core/src/process/bounded.rs), [`examine/host_env.rs`](../crates/rocm-core/src/examine/host_env.rs) and [`examine/wsl.rs`](../crates/rocm-core/src/examine/wsl.rs)). That list is a snapshot too, so start the retirement with a search of the whole repository for the file name (for example `git grep -n host-probing`) and reword every hit. How to read the claims below. Everything marked "verified" was read in the source on `main` at the time of writing, and the symbols named are the identity if a file moves. Nothing was executed on a Windows host. The one run on a WSL host is a single `rocm examine --json` with a local debug build of unrecorded revision, noted under "CPU model", and every count of runs or queries below comes from reading the call graph, not from measuring a process. Anything that depends on how a real machine behaves, rather than on what the code says, is marked UNCONFIRMED. diff --git a/docs/testing.md b/docs/testing.md index c30365f8a..baa36d079 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -61,7 +61,7 @@ cargo test -p xtask module_size ### Module map check -Every production source file must have an entry in [architecture.md](architecture.md). The +Every production source file, and every `.rs` file of `xtask` and the end-to-end harness, must have an entry in [architecture.md](architecture.md). The check runs in the `clippy` CI job and in the `architecture-doc` prek hook, and you can run it on its own: @@ -69,9 +69,12 @@ on its own: cargo xtask check-architecture-doc ``` -It fails on a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src` that the doc -does not link, and there is no exemption list; see -[architecture_doc.rs](../xtask/src/architecture_doc.rs). Test-only helpers need no entry. The +It fails on a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src`, or under +`xtask/src`, `tests/e2e-cucumber/src` or `tests/e2e-cucumber/tests`, that the doc does not +link, and there is no exemption list; see +[architecture_doc.rs](../xtask/src/architecture_doc.rs). Test-only helpers of a production +crate need no entry; a file in the `xtask` and `tests/e2e-cucumber` trees does, whatever its +name. The `lychee` check is complementary, not redundant: it confirms that links already in the doc resolve, and says nothing about a file the doc never mentions. diff --git a/xtask/src/architecture_doc.rs b/xtask/src/architecture_doc.rs index 9999970ac..336babb8c 100644 --- a/xtask/src/architecture_doc.rs +++ b/xtask/src/architecture_doc.rs @@ -2,7 +2,8 @@ // // SPDX-License-Identifier: MIT -//! Require every production source file to appear in `docs/architecture.md`. +//! Require every production source file, and every file of the repository's own +//! tooling and end-to-end harness, to appear in `docs/architecture.md`. //! //! `docs/architecture.md` is the contributor-facing module map and is meant to //! be "updated in the same PR as the code it documents". Nothing enforced that @@ -19,8 +20,18 @@ //! neither does a link missing its `[` or `)`, one with an escaped bracket, an //! image, or the outer brackets of a link that contains another link), //! or be a test-only helper (see [`is_test_helper`]). Out of scope: `build.rs` -//! files at a crate's root and the `tests/` and `examples/` trees, which sit -//! outside `/src`. +//! files at a crate's root and the `tests/` and `examples/` trees of those +//! crates, which sit outside `/src`. +//! +//! The same applies, without the helper exemption, to every tracked `.rs` file +//! under `xtask/src`, `tests/e2e-cucumber/src` and `tests/e2e-cucumber/tests` +//! (see [`HAND_KEPT_TREES`]): the tooling and the harness are not part of a +//! release, but their tables in the doc used to be kept current by hand, and +//! nothing noticed a file added without a row. The `tests/` tree of that +//! harness is its step definitions and its drift guards, so it is covered as +//! well as its `src/`. Every file in those trees needs a link, including a +//! file named like a helper, because a file added there is not shared test +//! support of a production crate. //! //! It reads the git index and the working tree, never a git diff, so the answer //! does not depend on a base ref. That is the same answer in CI and in the @@ -53,10 +64,22 @@ const DOC_DIR: &str = "docs"; /// Source roots whose `/src` trees are in scope. const SOURCE_ROOTS: [&str; 3] = ["apps", "crates", "engines"]; -/// Whether `path` is a tracked-file path this check covers: a `.rs` file under -/// `//src/` for one of the [`SOURCE_ROOTS`]. +/// The repository's own tooling and end-to-end harness: directory prefixes +/// whose `.rs` files are in scope with no helper exemption. +const HAND_KEPT_TREES: [&str; 3] = [ + "xtask/src/", + "tests/e2e-cucumber/src/", + "tests/e2e-cucumber/tests/", +]; + +/// Everything `git ls-files` is asked for: the [`SOURCE_ROOTS`] and the roots +/// the [`HAND_KEPT_TREES`] sit under. +const TRACKED_ROOTS: [&str; 5] = ["apps", "crates", "engines", "xtask", "tests/e2e-cucumber"]; + +/// Whether `path` is a `.rs` file under `//src/` for one of the +/// [`SOURCE_ROOTS`]. #[allow(clippy::case_sensitive_file_extension_comparisons)] // Rust sources are always lowercase `.rs` -fn in_scope(path: &str) -> bool { +fn in_product_scope(path: &str) -> bool { let parts: Vec<&str> = path.split('/').collect(); parts.len() >= 4 && SOURCE_ROOTS.contains(&parts[0]) @@ -64,6 +87,17 @@ fn in_scope(path: &str) -> bool { && path.ends_with(".rs") } +/// Whether `path` is a `.rs` file under one of the [`HAND_KEPT_TREES`]. +#[allow(clippy::case_sensitive_file_extension_comparisons)] // Rust sources are always lowercase `.rs` +fn in_hand_kept_scope(path: &str) -> bool { + path.ends_with(".rs") && HAND_KEPT_TREES.iter().any(|tree| path.starts_with(tree)) +} + +/// Whether `path` is a tracked-file path this check covers. +fn in_scope(path: &str) -> bool { + in_product_scope(path) || in_hand_kept_scope(path) +} + /// Whether `path` is a test-only helper that does not need an architecture /// entry: shared test support, or a property-test module. Matched on the file /// stem so a new helper of the same kind never needs an entry. @@ -389,7 +423,10 @@ fn check(tracked: &[String], cited: &BTreeSet) -> Vec { let mut violations = Vec::new(); for path in &in_tree { - if !cited.contains(*path) && !is_test_helper(path) { + // The helper exemption is for a production crate's shared test support; + // a file in the tooling or harness trees needs its row like any other. + let exempt = in_product_scope(path) && is_test_helper(path); + if !cited.contains(*path) && !exempt { violations.push(format!( "`{path}` is not cited in {DOC}: add an entry for it to the module map, as an \ inline `[text](path)` markdown link relative to docs/ (reference-style links, \ @@ -401,13 +438,13 @@ fn check(tracked: &[String], cited: &BTreeSet) -> Vec { violations } -/// Tracked files under the [`SOURCE_ROOTS`], as the index lists them. +/// Tracked files under the [`TRACKED_ROOTS`], as the index lists them. fn tracked_files(root: &Path) -> Result> { let output = Command::new("git") .arg("-C") .arg(root) .args(["ls-files", "-z", "--"]) - .args(SOURCE_ROOTS) + .args(TRACKED_ROOTS) .output() .context("failed to run `git ls-files`")?; if !output.status.success() { @@ -430,7 +467,7 @@ fn violations_in(root: &Path) -> Result> { Ok(check(&tracked_files(root)?, &cited_paths(&doc))) } -/// Fail if a production source file has no entry in `docs/architecture.md`. +/// Fail if a file in scope has no entry in `docs/architecture.md`. pub fn run() -> Result<()> { let root = paths::workspace_root()?; let violations = violations_in(&root)?; @@ -485,13 +522,66 @@ mod tests { "apps/rocm/tests/broken_pipe.rs", "apps/rocm/build.rs", "crates/rocm-dash-tui/examples/gen_cast.rs", - "xtask/src/anything.rs", "apps/rocm/src/data.json", - "tests/e2e-cucumber/src/lib.rs", + "xtask/build.rs", + "xtask/Cargo.toml", + "xtask/tests/anything.rs", + "tests/e2e-cucumber/build.rs", + "tests/e2e-cucumber/features/chat.feature", + "tests/e2e-cucumber/examples/anything.rs", + "tests/other-suite/src/lib.rs", + "tests/e2e-cucumber/srcs/anything.rs", ]); assert!(check(&tracked, &cites(&[])).is_empty()); } + #[test] + fn a_tooling_or_harness_file_with_no_entry_fails_and_is_named() { + for path in [ + "xtask/src/brand_new.rs", + "xtask/src/nested/brand_new.rs", + "tests/e2e-cucumber/src/brand_new.rs", + "tests/e2e-cucumber/src/bin/brand-new.rs", + "tests/e2e-cucumber/tests/e2e.rs", + "tests/e2e-cucumber/tests/e2e/brand_new_steps.rs", + ] { + let violations = check(&files(&[path]), &cites(&[])); + assert_eq!(violations.len(), 1, "{path} must need an entry"); + assert!(violations[0].contains(path)); + assert!(violations[0].contains("is not cited")); + } + } + + #[test] + fn a_tooling_or_harness_file_with_an_entry_passes() { + let paths = [ + "xtask/src/main.rs", + "tests/e2e-cucumber/src/lib.rs", + "tests/e2e-cucumber/tests/e2e/chat_steps.rs", + ]; + assert!(check(&files(&paths), &cites(&paths)).is_empty()); + } + + #[test] + fn a_citation_does_not_cover_the_same_name_in_the_other_tree() { + let violations = check( + &files(&["xtask/src/paths.rs", "tests/e2e-cucumber/src/paths.rs"]), + &cites(&["xtask/src/paths.rs"]), + ); + assert_eq!(violations.len(), 1); + assert!(violations[0].contains("tests/e2e-cucumber/src/paths.rs")); + } + + #[test] + fn a_file_named_like_a_helper_needs_an_entry_in_the_tooling_and_harness_trees() { + let tracked = files(&[ + "xtask/src/test_support.rs", + "tests/e2e-cucumber/src/world_props.rs", + "tests/e2e-cucumber/tests/chat_proptests.rs", + ]); + assert_eq!(check(&tracked, &cites(&[])).len(), 3); + } + #[test] fn nested_source_files_are_in_scope() { let tracked = files(&["crates/rocm-dash-tui/src/ui/tabs/home.rs"]); @@ -783,6 +873,26 @@ mod tests { ); } + #[test] + fn the_git_listing_includes_the_tooling_and_harness_trees() { + // `check` only sees what `tracked_files` lists, so a listing that stopped + // at the product roots would leave the new scope silently empty. + let root = Path::new(env!("CARGO_MANIFEST_DIR")) + .parent() + .expect("xtask crate has a parent directory"); + let listed = tracked_files(root).expect("git is readable in a checkout"); + for expected in [ + "xtask/src/architecture_doc.rs", + "tests/e2e-cucumber/src/lib.rs", + "tests/e2e-cucumber/tests/e2e.rs", + ] { + assert!( + listed.iter().any(|path| path == expected), + "{expected} is missing from the tracked-file listing" + ); + } + } + #[test] fn current_tree_matches_the_architecture_doc() { let root = Path::new(env!("CARGO_MANIFEST_DIR")) diff --git a/xtask/src/main.rs b/xtask/src/main.rs index dcb78067a..de9123f3e 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -159,7 +159,9 @@ pub(crate) enum Command { /// in `xtask/src/module_size.rs`. CheckModuleSize, /// Fail if a production source file (a `.rs` file under `apps/*/src`, - /// `crates/*/src` or `engines/*/src`) has no entry in `docs/architecture.md`. + /// `crates/*/src` or `engines/*/src`), or a `.rs` file under `xtask/src`, + /// `tests/e2e-cucumber/src` or `tests/e2e-cucumber/tests`, has no entry in + /// `docs/architecture.md`. CheckArchitectureDoc, /// Regenerate the published Doctor catalog manifest from the compiled catalog. Catalog {