Repository navigation
docs(architecture): correct stale and inaccurate module descriptions - #802
Conversation
docs/architecture.md had drifted from the code it maps. Fix the claims that are wrong at HEAD, without restructuring the document: - Caller lists: several entries named callers that no longer call a module (main.rs for engine_ipc, gpu_policy's parse_device_policy and service_launch; dispatch() for examine_human_report and render_services_text) or missed real ones (chat.rs, managed_service_status, service_hints, freeform_planner). Where a list keeps drifting, drop the enumeration instead of re-listing it, and drop the chat.rs function count. - Visibility: chat.rs's ChatRocmCommandAction and freeform_planner's StructuredRequestPlan/PlannedToolCall are pub(crate); nine modules labelled "owns private types" own pub(crate) types, alone or alongside private ones, and are relabelled "owns types". - Moved clusters: the runtimes dispatch, rendering, activation and import live in runtimes_cmd.rs, not main.rs; RuntimesCommand stays in main.rs; restart_internal_managed_service_with and the local-servers view live in services_text.rs. - Reversed edge: runtime_install_finalize.rs calls into runtimes_cmd.rs, not the other way round; uninstall.rs and uninstall_plan.rs depend on each other. - Other inaccuracies: rocmd's lib.rs re-exports three entry points, common.rs's single-caller rule, model_readiness's scope, the engine consumers of require_nonempty/command_failure_detail, vllm runtime.rs's compat-shim writes, aim lib.rs's contents, dash-tui app/mod.rs. - Replace the main.rs "partially modularized" changelog and the stale pending-modularization promise with a present-tense description of what main.rs holds. - Missing modules: add entries for remote/, advised_commands.rs, comfyui/source_swap.rs, the unlisted rocm-core modules, the rocm-dash-core/-collectors/-daemon crates and the shared dash-tui ui/ components, and link the two test files that were cited bare. Documentation only; no code changes. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The intro said further splitting is tracked under an epic that has since closed, and it no longer explained the "Phase N of EAI-7768's sequencing" labels that remain in the module inventories. Say what the labels mean and that deferred moves are called out in the entries they affect. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The module inventories still cited tickets from the retired EAI project. Jira resolves them to the current ROCMAI keys, so use those directly. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
juhovainio
left a comment
There was a problem hiding this comment.
Docs-only change to docs/architecture.md. I spot-checked the corrected claims against the code at this head (callers, visibility, file/function existence, the rocm model alias and --verbose flag, rocmd and rocm-core contents, engine entries) and they hold. CI is green on the completed checks; the E2E/hardware lanes are skipped, as expected for a docs-only change. This reflects a diff read plus spot checks, not a runtime check.
Two non-blocking notes: (1) one wording nit inline; (2) several source //! comments (managed_service_status.rs, engine_runtime_select.rs, examine_report_text.rs) still repeat claims this PR corrects, which the PR body already defers to a follow-up.
Minor: the intro no longer says "closed epic", but ROCMAI-27 is still open, so the "Phase N of ROCMAI-27's sequencing" wording reads fine; just worth keeping the PR body consistent with that.
|
|
||
| > 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. | ||
|
|
||
| ## 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: | ||
|
|
||
| - **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: [`automations.rs`](../apps/rocm/src/automations.rs), [`uninstall.rs`](../apps/rocm/src/uninstall.rs), (as of Phase 6a, ROCMAI-82) [`driver_install.rs`](../apps/rocm/src/driver_install.rs), [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs), (as of Phase 6e's follow-up, ROCMAI-726) [`freeform_execution.rs`](../apps/rocm/src/freeform_execution.rs), (as of Phase 6f, ROCMAI-213) [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs), and (as of Phase 6f, ROCMAI-210) [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs). [`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 stays in `main.rs` as part of the `Command`/`Cli` definition (e.g. `ComfyuiCommand`, `RuntimesCommand`) — but the dispatch function itself does not always stay with it: `comfyui()` does, while `engines()` (Phase 6a) and `runtimes()` (Phase 6c, ROCMAI-89) moved out to `engines_cmd.rs`/`runtimes_cmd.rs` respectively, following the mechanical-relocation re-import form below rather than full domain extraction's qualified-path form. 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) (`RuntimesCommand`'s domain types), [`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). | ||
| - **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 stays in `main.rs` as part of the `Command`/`Cli` definition (e.g. `ComfyuiCommand`, `RuntimesCommand`) — but the dispatch function itself does not always stay with it: `comfyui()` does, while `engines()` (Phase 6a) and `runtimes()` (Phase 6c, ROCMAI-89) moved out to `engines_cmd.rs`/`runtimes_cmd.rs` respectively, following the mechanical-relocation re-import form below rather than full domain extraction's qualified-path form. 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/update and the runtime-manifest model, with 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 private 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 `main.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 both used from `main.rs` — `assess_model_for_host` calls `select_serve_engine` and reads the resulting `ServeEngineSelection`'s `.engine`/`.source` fields — and `ServeGenerationDefaults` is private; [`service_launch.rs`](../apps/rocm/src/service_launch.rs)'s `AttachOutcome`/`RawModeGuard`/`ManagedSpawn`/`AutostartClaim` are private, and its `ManagedLaunchReport` is `pub(crate)` and read from [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) for the interactive summary; [`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 `main.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. The top-level dispatch fns (`install()`/`dispatch()`) staying in `main.rs` is not what makes it so: full domain extraction usually keeps its dispatch fn in `main.rs` too (see `comfyui()` above). |
There was a problem hiding this comment.
Nit: this variant sentence still says the cluster is "large enough to own private types ... those types move with it", but the entries below now say "owns types" because several (driver_install, runtimes_cmd, runtime_install_finalize, uninstall, ...) own pub(crate) types. Consider "own types" here for consistency.
nowycondro
left a comment
There was a problem hiding this comment.
🔴 Automated review · pr-review-watcher · 1796421
This automation never files a GitHub approval, so no approving review will appear here whatever the outcome — the merge decision stays with a human reviewer.
Review — no blocking findings
Full review of the whole change: a docs-only, single-file diff to docs/architecture.md (base 4f485bd…head 1796421, +87/−42 across one file, 3 commits). No ticket named beyond the PR itself; the diff's own content references several Jira-style ticket IDs (ROCMAI-27, ROCMAI-83, etc.) as subject matter being corrected, not as a "closes" linkage.
Blocking
None
Non-blocking
None
Decisions for the author
- Exhaustive "no caller outside this module" / "every other item stays private" claims remain the document's structural drift risk — tradeoff
This PR fixes several instances where such closed-set claims had gone stale (caller lists, call directions), but it doesn't change the pattern that produces them: a claim of the form "every other item here is private" is unfalsifiable by CI (lychee only checks that link targets exist, not that prose is true) and will drift again the next time a function gains or loses a caller elsewhere in the codebase. A softer convention (named examples rather than exhaustive negatives) would be more drift-resistant but less precise. Neither option is wrong; flagging so the choice is understood as deliberate rather than revisited piecemeal next time one of these goes stale. - External PR-number citations (
#447,#610,#541) are not covered by any automated check — tradeoff
lychee.tomlruns withoffline = true("no network requests"), so thesehttps://github.com/.../pull/NNNlinks are never validated by CI — only local file/anchor links are. I independently confirmed viagh pr viewthat all three are still open at review time, so the citations are currently accurate (one of them,#447, sits on a line this very PR touched). But there's no automated signal if any of them close, merge, or get renumbered later — the same class of silent drift this PR exists to fix, just on a surface lychee structurally can't reach. - Stale module-level
//!doc comments inchat.rsandruntime_install_finalize.rsnow contradict the correcteddocs/architecture.md— answered-by-intent
chat.rs's own doc comment still names a closed five-file caller list ("Every call site inmain.rs,dash.rs,dash_seam.rs,comfyui.rs, andruntime_install_finalize.rsgoes through thechat::module boundary") that I confirmed is incomplete against the actual tree (freeform_planner.rsandfreeform_execution.rsalso call intochat::in production code) — exactly the inaccuracy this PR's docs-side fix corrects.runtime_install_finalize.rs's doc comment similarly still describes being "called from... the siblingruntimes_cmd.rs(runtime activation)," the reverse of the actual and now-correctly-documented direction (runtime_install_finalize.rscalls intoruntimes_cmd.rs, not the other way round — confirmed viause crate::runtimes_cmd::{...}in production code, withruntimes_cmd.rs's only reference back living in its own#[cfg(test)]module). The PR body's own Notes section answers this directly: "A few module-level//!comments in source files still repeat claims this PR corrects in the document. They are deliberately left alone here to keep the change docs-only, and are tracked as separate cleanup." Would otherwise be a blocking cross-file consistency finding; confirm the follow-up cleanup is still tracked, since these are now the only places in the repo contradicting the corrected module map.
Positive signals
model_readiness.rs's entry is precisely scoped rather than hand-wavy: it names exactly which two functions (curated_alternatives,recipe_display_ref) are shared withexamine_report_text.rsand asserts nothing broader — I verified via repo-wide grep that this is the complete and exact set, which is harder to get right than a vaguer claim and was gotten right.- The intro's own caution blockquote ("a stale-but-plausible-looking note is worse than an explicit prompt to check... verify current file and function boundaries directly") already pre-acknowledges the exact fragility class this review spent most of its effort probing for, rather than presenting the document as a guaranteed-accurate source.
- The reversed-edge corrections (
runtime_install_finalize.rs↔runtimes_cmd.rs,uninstall.rs↔uninstall_plan.rs) are the kind of claim that's easy to get backwards and hard to self-check by proofreading alone; both were independently verified correct against actualuse/call-site evidence in both directions.
Deployment notes
None — documentation only, no code, build, or runtime behavior changed.
What this covered
Every line of the new docs/architecture.md (245 lines) read completely and checked against the actual Rust source tree at the PR head commit (exported read-only via git archive from a fetched-by-SHA scratch clone — the PR branch itself was never checked out), via six independent blind fan-out workers each covering a disjoint section of the document (intro/convention; apps/rocm main-module bullets; apps/rocm remaining bullets + apps/rocmd; crates/rocm-core; the dash crates + rocm-engine-protocol; rocm-deps/e2e-report/engine crates), plus my own supplementary verification of several claims (ticket-ID history against real commits on main, the three external PR citations, require_nonempty's three-engine-crate usage, model_readiness.rs's exact shared-function set, module //! doc-comment consistency, markdown-link-vs-bare-citation style against AGENTS.md's linking rule, and the docs-links/lychee CI result). One worker's section (apps/rocm remaining + apps/rocmd, lines 47-96) was run twice due to a concurrency-limit retry on my end; both runs independently reached the same clean result, which only strengthens it. Diff: 4f485bdfb4af367d1274eaa0a9563a1c821ded8c…1796421296b4b1d935cc2afa4927d0e1e819f0a3.
Ran: agent-instruction adherence against root AGENTS.md (relative-markdown-link citation rule, no file.rs:NN citations, bare Jira/EAI-style IDs permitted) — compliant. Code-comments pass — performed (see Decisions for the author). History pass — performed at a coarse level: cross-checked that the ticket IDs named throughout the doc (ROCMAI-208 through ROCMAI-215, ROCMAI-725/726/727, ROCMAI-662/663/720, etc.) correspond to real commits in main's history, which they do. CI — read via gh pr view --json statusCheckRollup at face value: all checks that ran (including Markdown links resolve (lychee)) succeeded; GPU/E2E hardware lanes and the Sphinx build are SKIPPED, consistent with a docs-only change.
Did not run: prior-changes pass — no structured search of historical review-comment threads on this file from earlier PRs; I did, as part of the mandatory pre-publish race check, observe that an existing human review (APPROVED, by a repo member, at this exact head commit) is already present on this PR. I did not read its content until after my own findings were settled, and it was not used to derive or shape any finding above — it's noted here only for transparency, since Step 9 of this method reads only the PR's own description/ticket, not other reviews.
One procedural note on my own conduct: while confirming the PR's head SHA and open/non-draft state early on, a combined gh pr view call also returned the PR's full description/body (a field I didn't need and should have excluded). I did not use it to steer the blind fan-out investigation above — none of the six workers were given it — and I only treated it as "the change's stated intent" formally at the end, per this method's Step 9, to reconcile against findings already settled. Not reconciled against any other discussion (review comments, prior rounds) here, by design.
Not in scope for this pass: no Rust/build toolchain was invoked (no cargo build/test/clippy run locally) since this change touches no code; CI's own Rust gates (clippy, build-and-test, Test (affected crates), windows-build-and-test, CodeQL) already ran and passed at this head commit, per the face-value CI read above.
…OCm#804) * docs: correct stale caller and visibility claims in module comments The module-level doc comments for chat, runtime_install_finalize, runtimes_cmd, managed_service_status, engine_runtime_select and examine_report_text still repeated claims that docs/architecture.md corrected in ROCm#802: reversed call directions between runtime_install_finalize and runtimes_cmd, incomplete or wrong caller lists, a second pub(crate) type in chat.rs, and `rocm models`/`examine --verbose` entry points that do not exist. Bring each comment in line with the code, and align the remaining "own private types" wording in architecture.md with the relabelled entries. Comment-only; no code changes. Signed-off-by: Jussi Elo <jussi.elo@amd.com> * docs: list driver_install as a runtime_install_finalize caller driver_install.rs calls real_os_release from runtime_install_finalize in production code, so the module comment and the architecture entry should name it. Also rewrap an over-long comment line in managed_service_status.rs. Signed-off-by: Jussi Elo <jussi.elo@amd.com> * docs: rewrap two module headers and split callers from callees Review nits on the module comments: one line in runtime_install_finalize.rs and one in managed_service_status.rs ran well past the surrounding width, and the runtime_install_finalize.rs header mixed who calls the module with what it calls. Rewrap and separate the two; no wording of any claim changes. Signed-off-by: Jussi Elo <jussi.elo@amd.com> --------- Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Summary
docs/architecture.mdhas drifted from the code it maps, and several entries now say things that are wrong at current main. This PR corrects those claims without restructuring the document. It is documentation only: the single changed file isdocs/architecture.md.The corrections fall into these groups:
main.rsforengine_ipc,parse_device_policyandservice_launch;dispatch()forexamine_human_reportandrender_services_text) or missed real ones (chat.rs,managed_service_status,service_hints,freeform_planner). Where a list keeps drifting, the enumeration is dropped instead of re-listed, and thechat.rsfunction count is dropped.ChatRocmCommandAction,StructuredRequestPlanandPlannedToolCallarepub(crate). Nine modules labelled "owns private types" ownpub(crate)types, alone or alongside private ones, and are relabelled "owns types".runtimes_cmd.rs, notmain.rs.runtime_install_finalize.rscalls intoruntimes_cmd.rs, not the other way round, anduninstall.rsanduninstall_plan.rsdepend on each other.rocmd'slib.rsre-exports,common.rs's single-caller rule, the scope ofmodel_readiness, the engine consumers ofrequire_nonemptyandcommand_failure_detail, the compat-shim writes in vllm'sruntime.rs, the contents of aim'slib.rs, the dash-tuiapp/mod.rsentry, and therocm model --verboseentry point (there is noexamine --verbose).main.rs. The "partially modularized" changelog and the stale promise of pending modularization are replaced by a present-tense description of whatmain.rsholds. The intro no longer points at a closed epic for further splitting; it now says that the remaining phase labels are historical references kept for traceability, and that deferred moves are called out in the entries they affect. Ticket references that still used the retired EAI project prefix now use their current keys.remote/,advised_commands.rs,comfyui/source_swap.rs, the previously unlistedrocm-coremodules, the three further dashboard crates and the shared dash-tuiui/components, and linked two test files that were cited by bare path.How this was checked
Every added or changed statement was re-derived from the code at current main (callers by grep, visibility from the declarations, ownership from where the items are defined), then checked again by a second reviewer who did not write the change. That second pass found and fixed several errors in an earlier draft, including a wrong caller and an overbroad "not split further" claim.
lychee --config lychee.toml --offline docs/architecture.md: 0 errors; every added link target is a tracked file.file.rs:NNcitations and no new line or function counts were added.internal_*identifiers.cargowas not run locally because no code changed; the repository CI runs the full gates.Notes
No Gherkin scenario is added: this changes documentation only and no user-observable CLI behaviour. A few module-level
//!comments in source files still repeat claims this PR corrects in the document. They are deliberately left alone here to keep the change docs-only, and are tracked as separate cleanup.