Skip to content

ROCMAI-768: restructure docs/architecture.md into per-crate tables - #1016

Merged
jussielo-amd merged 22 commits into
mainfrom
docs/architecture-per-crate-tables
Nov 11, 2026
Merged

jussielo-amd merged 22 commits into
mainfrom
docs/architecture-per-crate-tables

Conversation

@jussielo-amd

@jussielo-amd jussielo-amd commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Closes ROCMAI-768.

Summary

docs/architecture.md was one long paragraph per file, mixing a one-line responsibility with phase history, ticket ids, caller lists and visibility notes, so finding where something lives meant reading several kilobytes of prose. This restructures it into one table per crate: a row per source file (file, one-line responsibility, how the file was extracted), with a short Boundaries list under each table for the facts a row cannot show (layering and leaf modules, deliberate privacy, single sources of truth). Four follow-ups the ticket left open are in the PR as one commit each, so a reviewer can drop one: the stale claims corrected, check-architecture-doc widened to xtask and the end-to-end harness, eleven module comments that pointed at a phase vocabulary the document no longer has, and the retirement note in docs/host-probing.md.

  • Size: 306 KB to 170 KB. Median line length 422 to 206 characters, 90th percentile 1758 to 323.
  • 512 rows: every production source file that cargo xtask check-architecture-doc covers keeps its row (403 files), and xtask and tests/e2e-cucumber have tables as well (109 rows). The check now covers those two trees as well, so every .rs file under xtask/src, tests/e2e-cucumber/src and tests/e2e-cucumber/tests needs a row; each of the 512 rows is the only row for its file.
  • No phase labels or ticket keys remain in the document. A short History section replaces them and points at git log --follow.
  • The module-organization convention is condensed. The proptest-regression paragraph is carried over word for word, and the file-size paragraph is taken word for word from main.
  • The Class column uses the ticket's three values: domain (full domain extraction), relocation (mechanical relocation) and flat (everything else, including crate roots and test-only support). It records how a file was extracted, not a rule a new file is judged by. 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.

No product behaviour changes

The restructuring and the corrections are documentation. The two code changes are xtask/src/architecture_doc.rs, repository tooling that no rocm user runs, and eleven module comments in apps/rocm/src (comments only, so cargo check -p rocm is the whole check). No Gherkin scenario is needed: nothing a user of the CLI can observe changes, no CLI output is printed or edited, and the behaviour claims in the document are carried over or corrected against the code rather than altered. The checker's new tests are unit tests in the xtask crate, which runs on the ordinary Linux and Windows test jobs; none is platform-gated and the subprocess and state-flag checklists do not apply. The tracked-file listing uses git ls-files, as the check always did.

How to review

The thing to check is information loss, so read the Boundaries lists first. The old text is git show d027ff8e3:docs/architecture.md, and the old line numbers below refer to it. Every entry main has changed since then is carried into its row: diagnose_cmd.rs (which now builds its report through prepare_cli_report), uninstall.rs (the removal of the fish completion script the Linux installer records, plan_completion_removals; the file grew by about 700 lines on main, almost all of it that feature's tests, so the row was re-read against the code and is otherwise unchanged), atomic_write.rs (durable as well as atomic, keeps permission bits, replaces a symlink's target), the single kernel-release read (examine.rs, examine/host_env.rs, host_gpu/os_facts.rs and the host-probing Boundaries bullet), the single CPU model-and-vendor read (examine/host_env.rs, host_gpu/os_facts.rs, host_gpu/windows_inventory.rs and the same Boundaries bullet, which now lists three converged pairs and no longer names the CPU model as a duplicated read), node_efficiency and NodeEfficiency with its held flag (efficiency.rs), and the shared engine stdio client (the rocm and rocmd engine_ipc.rs rows, AppPaths::env_vars in the paths.rs and engine_runtime_select.rs rows, optional_arg in the protocol lib.rs row, and the service_stop_steps.rs row, which now also serves engine_ipc.feature), and the shared managed-stop routine with its Windows identity and tree-kill handling and services remove --force (the proc_lifecycle.rs, process.rs, service_control.rs, launch_transaction.rs, managed_service_status.rs, service_records.rs and service_hints.rs rows, the rocmd service.rs row, and the service_cleanup_steps.rs and service_stop_steps.rs rows), and the bounded subprocess executor, now in crates/rocm-core/src/process/bounded.rs and re-exported from process.rs (the process.rs, command_capture.rs, probe_exec.rs, host_gpu/capture.rs and host_gpu/diagnostics.rs rows and the host-probing Boundaries bullet). Thirteen files main added have rows too: process/bounded.rs (the executor behind run_with_timeout and run_bounded), apps/rocmd/src/artifact_prefetch.rs (split out of sandbox.rs, whose row and the test_support.rs row are updated and which has a Boundaries bullet), config_proptests.rs, persisted_paths_props.rs and therock/python_config_props.rs (property tests), sigpipe.rs, stdio_client.rs and fake_engine.rs (the last two in rocm-engine-protocol), cli_args.rs (split out of cli.rs, whose row now only says it re-exports the value enums), and the hand-kept tests/e2e-cucumber/src/stand_in_uname.rs, stray_process.rs, tasklist.rs and xtask/src/engine_stdio_client_contract.rs (the contract test also moves the xtask Boundaries bullet from seven *_contract.rs files to eight). The file-size paragraph is main's current one. Every row was derived from the file's own //! header and checked against the code, and rows and Boundaries bullets were spot-checked independently against the source. Where the old text hedged a claim ("typically", "should pass"), the hedge is kept, because several of the sharper rewordings turned out to be false in the code.

Checks run

  • Merged with current main (6c84db9, which moves the artifact prefetch out of the rocmd sandbox module and is ported the same way; before that 8027e69, which includes the bounded-executor change: docs/architecture.md conflicted because main edited the old per-file entries, so this branch's tables were kept and the change ported into them; before that b4fff0b, which makes the module-size hook blocking; one textual conflict, in AGENTS.md, resolved by taking main's module-size wording and keeping this branch's wider architecture-entry line; docs/architecture.md merged cleanly with main's module-size paragraph intact, and the module_size.rs row, which still described the advisory form main removed, now describes the one check). An earlier merge (eb2a819) had one conflict, in docs/architecture.md, resolved by keeping this branch's tables and porting main's changed entries and new files; git merge-tree --write-tree origin/main HEAD is clean. cargo xtask check-architecture-doc, check-module-size and check-crate-edges pass, and cargo fmt --check is clean.
  • cargo xtask check-architecture-doc fails when a row is deleted, as expected, now also for xtask/src/eval_fixtures.rs and tests/e2e-cucumber/tests/e2e/bench_steps.rs (rows deleted by hand on the real tree, then restored).
  • The new checker tests were each shown red under a targeted break, then restored: in_scope not covering the two trees fails three of them (a missing row is reported for each tree, a same-named file in the other tree is not covered, a helper-named file still needs a row); applying the helper exemption in every tree fails the helper-name test; a git ls-files listing that stops at the product roots fails the listing test (without it the real-tree test passes on an empty scope, so it is the one that guards the listing); widening the scope to all of tests/ fails the out-of-scope test.
  • cargo xtask lychee and the lychee hook: pass. Pointing one link at a missing file makes it fail.
  • cargo test -p rocm --bin rocm advised_commands:: passes (20 passed, 1 ignored). It scans docs/**/*.md, which is why the services hint is written as stop|restart|remove rather than with a placeholder.
  • cargo test -p xtask: 786 passed. cargo clippy -p xtask --all-targets -- -D warnings is clean, cargo check -p rocm passes, and check-module-size reports 419 files, none over 1500 production lines (architecture_doc.rs is under 1000).
  • Every link target that the old document had still resolves. The 394 production-source links the old document had are all preserved, plus the nine production files main added (the three property-test files, sigpipe.rs, stdio_client.rs, fake_engine.rs, cli_args.rs, process/bounded.rs and artifact_prefetch.rs; 403 in all).
  • Prek hygiene hooks (whitespace, end of file, license header, signing configured) pass. Every commit is signed and carries a sign-off.
  • Leak scan over the diff against main: the only hits are public tool and hardware names (amd-smi, amdgpu) and ordinary words.
  • Not verified here: the full workspace test suite, Windows jobs and the GPU lanes, because only Markdown, repository tooling and comments changed. CI is the authority for them.

Claims dropped, moved and found stale

The ticket asks for every dropped or moved claim to be listed. The old text is about 300 KB, so the verbatim claims are in the old file at the SHA above. For the claims dropped by rule, counts are the intended level of detail: listing each one would reproduce the old file. d027ff8e3 is a commit on main (git merge-base --is-ancestor d027ff8e3 origin/main succeeds), so it stays reachable after this PR is squashed or rebased. What follows is the rule set, the claims moved to a new place, every claim dropped that a reader could not get from one file, and every claim found to be stale.

Dropped by rule. Caller enumerations, visibility lists (pub(crate) and pub(super) inventories), where tests live, per-function inventories, move or split history, phase labels, ticket and issue numbers, and status wording about unfinished work. Of the old per-file entries, roughly: apps/rocm about 60 caller lists, 65 visibility notes, 55 test-placement notes, 70 per-function inventories and 16 history references; the other crates follow the same pattern at smaller scale.

Dropped, and not obviously derivable from one file

Behavioural invariants that the review listed as dropped. Each is still true and is stated in a comment or a test in its own source file:

  • The dash install form passes --approve-replacing-active-default and never --yes, because --yes would approve a sudo (ui/install_manager.rs).
  • The config overlay has no key-entry field (ui/config_manager.rs).
  • A --dry-run writes nothing (SetupRecovery::PreviewOnly in runtime_adopt.rs).
  • Runtime manifests are written registry-last, and owns_install_root gates folder deletion (runtime_registry.rs).
  • The rocDXG plan refuses when the download cannot be authenticated, unless ROCM_CLI_ROCDXG_ALLOW_UNVERIFIED is set.
  • The examine report has a fail-closed schema gate and a Deny default.
  • tool_exec::execute_approved re-validates before it runs a tool call.
  • tool_policy.rs refuses control characters and system-path prefixes.
  • serve_recipe's RESERVED_ENGINE_ENV_KEYS blocks overriding the engine's own environment.
  • gguf_source never follows a redirect from https to http.
  • active_default_runtime_relation fails closed.
  • run_internal_mcp_call refuses mutating commands.
  • The apt-get -s ROCm-removal refusal.
  • run_with_timeout bounds the output it quotes.
  • LlmConfig's Debug output redacts the key.

Per-crate lists the file-level reviewers produced follow.

These are true statements that were dropped to keep the Boundaries lists short, and a reader could not get them from one file or a grep. Many are also stated in the source file they describe. Say if any should come back as a Boundaries bullet.

apps/rocm

  • line 75: model_fit.rs is its own module (not part of the diagnose handler) so examine_report_text.rs and model_catalog_text.rs read the platform gate without depending on a command module.
  • line 71: sdk_install_request lives in install_cmd.rs rather than chat.rs because install_cmd.rs must not depend on chat.rs.
  • line 116: FamilyResolution lives in therock/source.rs, not therock/family.rs, to keep the source-to-family dependency one-way.
  • line 114: extract_tarball sits in therock/process.rs, not therock/io.rs, because it spawns tar and io.rs stays a leaf.
  • line 112: therock_version_proptests.rs is declared from therock.rs (not therock/version.rs) because it also reaches update, wheel and registry code.
  • line 111: five helpers (slugify, venv_python_path, platform_tarball_token, runtime_key, wheel_runtime_key) stay in therock.rs permanently because the children read them back from the parent.
  • line 122: AggregateDeviceTarget::prefer_recorded in therock/resolve/wheel.rs is the one place a recorded device target replaces the detected one (called from therock.rs, therock/update.rs, therock/wheel_plan.rs). Single-source; omitted for length.
  • line 98: no_usable_gpu_refusal words the no-usable-GPU refusal once for both serve's pre-flight and the spawn.
  • line 99: every failure after a record's first write must go through abandon_failed_managed_launch (why launch_managed_engine_child_locked is split out).
  • line 86: the registry entry is written last so a failed write never leaves a new entry; neither file is written atomically.
  • line 94: the CLI restart path shares rocm-core's lease primitives rather than serve_port.rs.
  • line 91: nothing in serve_recipe.rs calls back into serve_cmd.rs.
  • lines 104, 105: service_records.rs and services_cmd.rs are not called back by the modules they read.
  • line 99: on Windows managed_engine_startup_failure_detail is re-exported for test builds only, because services_text.rs's log-tail tests call it through crate::service_launch.
  • line 70: the vram/host_gpu test fixture builders are deliberately duplicated in the gpu_policy.rs and serve_cmd.rs tests rather than shared.
  • line 89: runtime_install_finalize.rs calls into runtimes_cmd.rs (activate_runtime and others), while runtimes_cmd.rs reaches it only from its tests.

crates/rocm-core

  • 215: apps/rocm/src/comfyui.rs's log-line quoter deliberately stays outside quoting.rs. quoting.rs's own header (line 35) says what is deliberately not there, so it is partly derivable, but a reader of comfyui.rs would not know.
  • 186: rocm's amd_smi_probe_json logs a declined launch at info because the default filter is warn,rocm=info. It is explained in a doc comment in apps/rocm/src/gpu_policy.rs, so derivable from that file, not from rocm-core.
  • 186: the dashboard collectors keep their own pre-flight decision (preflight_passes) because they gate an async launch. Partly kept: the bullet says they reuse the bounded probe through an allowlisted edge; the reason for a separate decision is in crate_edges.rs and amd_smi_launch_contract.rs's allowlist text.
  • 216: the Doctor report mailbox adapter lives in xtask (report_mailbox.rs, cargo xtask report-rollup). A grep finds it, but nothing in report_rollup.rs points there.

dashboard crates

  • 390: rocm dash always sets RunnerOptions::persist_dir (to the telemetry dir under the data dir), so every dashboard session is recorded. Visible only in [apps/rocm/src/dash.rs], not in the daemon crate.
  • 294: the registry probe answers from each record's own status, so it can lag rocm services list, which also checks process liveness; the implementation (LiveManagedRegistryProbe) lives in apps/rocm's dash.rs.
  • 296: the RocmToolExecutor implementation is BinToolExecutor in apps/rocm's dash_seam.rs, and the executor is None under demo, replay and mock.
  • 345: apps/rocm's launcher_route turns a LauncherChoice into a focused host, chat or the full dashboard; the launcher's quit goes through the same quit-confirm gate with a StaticManagedRegistrySnapshot.
  • 346: ModelRecipeSummary is built by apps/rocm's dash.rs so the crate needs no rocm-core (the general rule is kept; the specific plumbing point is not).
  • 322: the four ways an overlay is opened (KeyAction::Open*, a slash command, the quit-confirm s key, the startup focus). Cross-file, dropped as a caller list.
  • 315, 317, 319, 320: one-way imports among the split ui/ files (instance_detail reads instances.rs, which does not import it back; menu.rs depends on app/types.rs, not the reverse; warnings_modal imports popup_height_for from help_modal, not the reverse; theme_picker does not depend on modal.rs). The instance_detail direction is stated in its own header; the others need a grep of the other file.
  • 380: the runner keeps one observation tracker per instance (and one each for TTFT and TPOT), drops them when a service is retired and invalidates on a port change. Readable in runner.rs, but not from observation.rs.

apps/rocmd and the engines

  • 155: the proxy is bound even for an engine with its own /v1/messages route, because that route only accepts the served model's name. Checked: the anthropic_proxy.rs module header states it, so it is derivable from the file after all; listed here only because the table cell no longer hints at it.
  • 158: under test, DaemonHost::detect returns the test binary for both commands and looks for no sibling, so no unit test can run a rocm or rocmd built beside the test binary. Documented in daemon_host.rs, but a test author working elsewhere in the crate would not find it without opening that file.
  • 168: a recovery restart that cannot find the rocmd binary fails before it writes the record. In supervise.rs, not discoverable from the caller in server_recover.rs.
  • 424: the discovery table's own test pins which versions it serves and in what order (dropped as test placement; a reader editing the table will meet it as a failing test).

xtask and tests/e2e-cucumber

  • The README's directory tree and the step-file mapping: rows name the primary .feature file(s) of each step file, found by matching step phrases against features/. Many step files also serve one or two scenarios of other features (for example therock_steps.rs holds 32 step matches in runtime_setup.feature, serving_steps.rs serves steps reused by about ten features). Rows mention only the main one or two.

Dropped because the file itself states it

Accurate claims that were dropped from the map because the source file's own header or comments state them, so a reader of that file gets them. Old line numbers refer to the old file.

apps/rocm. The driver plan only reports on native Windows (58). therock/family.rs refuses a GPU with no ROCm build (117). The ComfyUI install pins the runtime's torch stack (136). The launch lock is held across resolve_managed_port_in_transaction, whose doc says callers must hold it (98). system_packages.rs is a leaf (110).

crates/rocm-core. download.rs uses ureq and imports only disk_space.rs (196). net.rs imports no other module, and endpoint_readiness.rs builds on net.rs, service_record.rs and model_catalog.rs (198, 210). jsonl_store.rs is generic and imports nothing from automation.rs (206). package_plan.rs only plans and never runs the plan, which its header says (247). The shared PATH lookup is described in docs/host-probing.md (205).

apps/rocmd and the engines. Leaf claims for daemon_host.rs, engine_ipc.rs (uses only daemon_host.rs), host_snapshot.rs (uses only persistence) and mcp_argv.rs (158-163), the production imports of supervise.rs (168), three Lemonade leaves (437, 438, 440), startup_diagnostics.rs (imports only state.rs, 429) and docker.rs (no bollard, 453). The DaemonHost test stand-ins (158). Every supervisor write after the first goes through update_supervised_record (168). Stale-container removal, and a stop removing the container, in the AIM engine (455).

Dashboard crates. With several published ports the chosen one is arbitrary (368). A rewrite that is not shorter goes undetected (366). The Doctor report check looks only at the envelope (329, in ui/examine_manager.rs's header). A managed service id never has the 64-hex shape (367, in cgroup.rs). The launcher has its own blocking key loop (345). Dock dimensions (341). Ring sizes and replay order on subscribe (388, in server.rs). Demo determinism and file mode (389), and no fsync or rotation in the session writer (390). Why tool_approval and scroll are named as they are (279, 281).

Found stale in the old text (re-derived from the code and corrected)

Each claim below was dropped by the restructuring because it was false or no longer true. They are now re-derived from the code as it stands (call sites grepped again, not taken from the list) and the true statement is in the row or Boundaries bullet it belongs to. Two did not turn out as listed: the torch-alignment claim (the list said Lemonade also reads torch_alignment_disabled; it does not, it has its own opt-out ROCM_CLI_DISABLE_LEMONADE_BACKEND_ALIGNMENT, so the document's "the CLI and the vLLM engine" was already right and now also says what Lemonade does), and the dash_seam.rs header (still false, but it is a source comment and the document's claim was already true; the header is not changed here). The rest were still stale in the old text and are corrected: the driver_install.rs row names tool_policy.rs and freeform_planner.rs for the re-export; the service_hints.rs Boundaries bullet lists its real callers and says the parent service_launch.rs is not one; the dash_seam.rs row says why the seam exists and which dash crates may depend on rocm-core; the which claim is scoped to the two host-probing stacks and names the two PATH walkers elsewhere (find_mpirun_path, the runtime.rs executable search); the package_plan.rs row says it never executes a plan and runs only sudo -n true; the hardware_root.rs/os-release claim says the resolver is private but read_os_release is pub and used by two other readers, with the test in system_packages.rs guarding apps/rocm only; the amd_smi.rs row lists what it imports and that the spawn goes through process.rs; the apps/rocmd Boundaries say update_supervised_record is pub(crate) and called by server_recover.rs and that the watchers.rs re-exports are used in production (stop_requested by supervise.rs, find_recoverable_service by watchers.rs; supervise.rs tests use the latter as well); the vLLM Boundaries say discover_builds.rs is a leaf but its readers do import one another; the vLLM lib.rs row says verified_torchaudio_release is a delegating pub fn, not a pub use. What was found, as listed before the correction:

apps/rocm

  • line 57: says driver_install.rs re-exports host_install_driver_only_reports "for chat.rs and freeform_planner.rs". Today the callers are tool_policy.rs (crate::driver_install::host_install_driver_only_reports) and freeform_planner.rs; chat.rs does not call it. Caller list dropped anyway.
  • line 95: the service_hints.rs caller list names service_launch.rs and omits serve_port.rs and service_control.rs, which call it (grep service_hints::); the callers are the service_launch/ children, not the parent file. The kept claim (one builder for every hint) is true; only the list was stale.
  • Module header of dash_seam.rs (not the old doc): "The dash crates stay free of rocm-core" is not true of every dash crate; crates/rocm-dash-daemon/Cargo.toml depends on rocm-core. The Boundaries bullet (from old line 108) speaks of rocm-dash-tui only. Fixing the header is out of scope.

crates/rocm-core

  • 231 (and lib.rs's own doc comment on torch_alignment_disabled): "shared by the CLI and the vLLM engine". The Lemonade engine also reads it (engines/lemonade/src/backend_alignment.rs). The bullet now names no consumers ("so its readers cannot disagree").
  • 213: "which (the one PATH lookup ...)". Across the crate this is false: openmpi.rs's find_mpirun_path and runtime.rs's executable search (around std::env::split_paths(&path_var)) walk PATH themselves. It is true only between the two host-probing stacks, which is how the bullet scopes it.
  • 247: package_plan.rs "never runs anything". sudo_noninteractive_available runs sudo -n true (behind can_autoinstall). It never executes a plan, which is what the bullet says.
  • 243: "the resolver it passes is private, so a second copy of that reader cannot be written outside this module". hardware_root::read_os_release is pub and accepts any resolver closure, so a caller outside the module can still read os-release with its own resolver. Dropped.
  • 186: amd_smi.rs "only reads the registry records managed_runtime.rs exposes and runtime.rs's data/home directory lookups". It also imports has_usable_amd_gpu, host_path, is_wsl_host, and calls process.rs and probe_exec.rs. Dropped (it was a dependency list anyway).

apps/rocmd and the engines

  • old 168, "Writes after a supervisor's first go through the private update_supervised_record": it is pub(crate) (apps/rocmd/src/supervise.rs, update_supervised_record), and watchers/server_recover.rs calls it directly (crate::supervise::update_supervised_record, stamping last_restart_unix_ms after a failed restart). Old 171's list of what server_recover.rs uses also omits this.
  • old 169, "find_recoverable_service and stop_requested are re-exported from here because supervise.rs's and service.rs's tests reach them by the crate::watchers:: path": supervise.rs's production code imports crate::watchers::stop_requested (top-level use in supervise.rs, which old 168 itself says), so the re-export is not test-only. Dropped.
  • old 424, "so runtime.rs, wheel_builds.rs and install.rs can all read it without importing one another's code": install.rs imports crate::runtime and crate::wheel_builds in production (use lines at the top of engines/vllm/src/install.rs). The single-list claim was kept; this half was dropped.
  • old 431, "verified_torchaudio_release, which the crate re-exports from lib.rs": not a pub use; engines/vllm/src/lib.rs defines a pub fn verified_torchaudio_release that delegates to the pub(crate) one in wheel_builds.rs (used by apps/rocm/src/therock/resolve/wheel.rs). The row says "for the rocm binary", which is true; minor wording only.

Source headers that disagree with their code (reported, not changed)

  1. xtask/src/main.rs //!: lists only signing, the MANIFEST.md generator, third-party notices, commit-trust verification, PowerShell linting and markdown-link checking. The Command enum also has affected, pre-push-check, check-crate-edges, check-module-size, check-architecture-doc, catalog, eval-fixtures, coverage, demos, package, e2e, e2e-prewarm, e2e-report, report-rollup, release-readiness and verify-pinned-keys.
  2. xtask/src/main.rs, the E2e variant's doc comment (--help text, not a //! header): "Build the release rocm binary". e2e.rs builds -p rocm -p rocmd, as its own header says.
  3. xtask/src/workflow_contract.rs //!: "Static contract tests for the CI workflow split." The file (about 9.7k lines, 145 tests) now also covers job timeouts, runner labels, permissions, the dependabot workflow, release-build pins, .github/scripts/gpu-preflight.sh and more; the header describes only the first contract.
  4. tests/e2e-cucumber/src/capability.rs //!: "The suite is black-box (it never imports rocm-cli crates)". The e2e target imports rocm_core (AppPaths, ProcessIdentity, fake_executable::write_fake_executable in tests/e2e.rs and tests/e2e/diagnose_steps.rs) through the dev-dependency. Behaviourally black-box, but the import claim is false for the test targets. The crate README's "no imports from the rocm-cli codebase" has the same issue.
  5. tests/e2e-cucumber/src/powershell_text_rule.rs //!: "this crate does not depend on rocm-core". True of the library target only; Cargo.toml lists rocm-core as a dev-dependency.
  6. tests/e2e-cucumber/src/panic_capture.rs //!: "Shared by black-box drivers (currently tests/e2e/tui_driver.rs)". src/harness_diagnostics.rs also calls crate::panic_capture::panic_message.
  7. tests/e2e-cucumber/src/fixture_binary.rs //! names fake-tailscale, fake-uv, fake-python as the stand-ins; fake-docker is located the same way (install_fixture_binary("fake-docker", ..) in model_catalog_steps.rs). Minor: the list reads as examples.
  8. Not a header, for the record: the crate README's directory tree lists 5 of 32 features, 6 of 32 step files and 4 of 29 src/ files.
  9. Missing headers (not stale): src/lib.rs, src/mock_server.rs, src/model_id.rs, src/runtime_root.rs, tests/e2e.rs, and tests/e2e/ artifact_steps.rs, chat_steps.rs, diagnose_steps.rs, driver_steps.rs, examine_steps.rs, model_catalog_steps.rs, runtime_steps.rs, serving_steps.rs. Their rows come from the code (pub items, step attributes, matching .feature files).

Moved to Boundaries

Every claim kept as a Boundaries bullet, by its line in the old file.

apps/rocm (25)
Old line Claim
34 (with the convention at 19 it cites) private mod for every module; qualified path vs the use crate::x::{...} re-import block
39, 34, 63, 70, 131 engine_inventory single table; status_for_readiness, device_policy_name, ROLLBACK_RECOVERY_HINT stay at root for cross-module callers
47, 38, 140 enums in cli.rs; bootstrap.rs and remote/mod.rs own enum + dispatch; declaration order sets nested help order
40, 41 turn.rs top of chat graph; intent/mcp_bridge/summaries never call back
69, 76, 82, 128 planner and prompt_text/rocm_argv/tool_policy must not import chat; xtask chat_import_contract.rs
45 chat_cmd.rs separate: calls chat.rs and dash.rs, dash.rs calls chat.rs
68, 69 freeform plan built once (cloud planner not deterministic); same guarantee for the MCP tool
69, 128 validate_serve_command_safety holds the serve rules; planner keeps no copy
86, 83, 88 registry depends on neither therock nor runtimes_cmd; adopt/uninstall do not depend on runtimes_cmd
61, 89 engine_install_env imports adopt/registry directly to avoid a cycle via runtime_services
84, 85 finalize does not import engines_cmd; torch_alignment is a child to avoid a cycle
83, 86 select_single_ready_runtime one rule; write_runtime_manifest one routine
86 manifest and ActiveRuntimeMarker serde shapes are on-disk contracts
111, 110 install_root_has_payload one rule; os-release only via real_os_release, scan test
96, 93 service_launch does not import service_control (Ctrl-C stop passed in); services_text does not call back
37 background_helper is a leaf so the note is readable without the spawner
129, 130 uninstall.rs and uninstall_plan.rs depend on each other; plan shared with storage.rs
95 service_hints builds every hint so they cannot drift
108 dash-tui copy of the quoter (crate-edge reason) held equal by property test
81 thinking rule lives in rocm-dash-core so the dashboard decides identically
41 chat/turn.rs compiles in the assistant skill
115 pinned metadata key path checked by cargo xtask verify-pinned-keys
59 ROCDXG_PINNED_DIGESTS trust anchor
126 render_update_json is what the dashboard's update check parses
74 proptest regression files keyed by source path
crates/rocm-core (19)
Old line Claim
226 crate-root primitives stay in lib.rs on purpose (multi-consumer, no owning domain)
231 TORCH_ALIGNMENT_DISABLED_ENV/torch_alignment_disabled is the one read of the opt-out
232 VLLM_GPU_MEMORY_UTILIZATION_HINT is one wording (CLI, vLLM engine, fix-16 diagnosis)
229, 230 command_failure_detail detail rule and sanitize_component slugger are shared
195, 199, 241 diagnose.rs / examine.rs / fix.rs / host_gpu.rs kept as fronts so links and paths stay valid; children private
196, 198, 213, 245, 247 private modules re-exported so callers keep rocm_core:: paths; package_plan through openmpi.rs; probe_exec not re-exported
241 RECIPES plus diagnose checkers is the authoritative failure catalog; diagnose and the e2e crate hold copies to it via test-only oracles
195 diagnose platform children do not import each other; catalog.rs the only module naming every checker
241 fix render and manifest read RECIPES from catalog, which reads neither
205 host_gpu.rs and examine.rs are two stacks reading some facts twice; host-probing.md proposes survivors (now with the two converged pairs, the PATH lookup and the kernel release, as main's change to this note states them)
200 gfx_target.rs kept out of host_gpu so managed_runtime reads the family mapping without the probes
243, 246 probes resolve through host_path (E2E re-roots it); os_release.rs the one parser
186 amd_smi_json the one synchronous amd-smi launch path (kfd pre-flight); enforced by amd_smi_launch_contract.rs
244 log_tail.rs the one log-tail reader; lives here because rocmd cannot depend on rocm
187 new atomic writes go through atomic_write.rs; older hand-rolled writers predate it
251 runtime_python_env_root_for_executable and install_root_has_payload are the one definitions
221 vllm_oom markers must match byte for byte between the vLLM engine and apps/rocm
188 automation.rs reads WatcherMode from config.rs, config.rs imports nothing back; watcher catalog in config.rs for that reason
214 the bounded executor in process/bounded.rs abandons a lagging reader, the probe runners (run, the optional capture, the Windows diagnostic capture) now run on it, and only the TheRock install runner joins its readers with no time limit (verified against current main; issue link dropped; stated as a present-tense fact, not as work still to do)
dashboard crates (36)
Old line Claim
374 chat_template lives in the leaf crate so providers/wire.rs and agent/clients.rs cannot drift
379, 384 InstanceStatus predicates/labels and JobStatus::glyph/label/legend_glyphs are the one definition
386 vram.rs reuses efficiency.rs's id matching
382, 389 PersistedEntry written by daemon persist, generated by demo, read by replay
376, 379 #[serde(default)] so older recordings and partial CSVs deserialize
383 PROTOCOL_VERSION bump rule; every Event variant struct-shaped, held by a test
384 only SpawnJob interpreted; Persist/Broadcast* unconsumed; daemon discards effects
377 dash config separate from RocmCliConfig; only the TUI chat save touches it; socket path copied from rocm-core on purpose
377 dash-core may have no first-party deps (check-crate-edges)
385, 368, 373 traits sync; Docker and vLLM sync impls return Unsupported; runner uses async methods
369 parse_sample/default_port not on the live path; runner builds collectors directly
364 amd-smi pre-flight reason (uninterruptible sleep without /dev/kfd); reachability verdict from apps/rocm via RunnerOptions
373 vllm_prom leaves gen_tps empty; runner turns the counter into a rate
369, 365 bench_load takes the vllm label from EngineKind; EngineSplitNotice reported for the CLI to print
371 Lemonade collector only with enable_lemonade, default false, off in rocm dash's daemon
363 collectors used by the daemon and on Windows by the TUI in-process
387 a registry pass that cannot read in full retires nothing; a read in full, empty or not, retires what it no longer holds
391, 297 the two transport.rs files are copies; change both
387 apps/rocm's dash.rs drives the daemon
258 TUI depends on dash-core, never on rocm-core; rocm-core data through tool_exec/registry_probe or ResolvedArgs
292, 305 llm.rs's default port and exec.rs's Python layout are copies of rocm-core's
294 registry probe read live at each quit attempt and frame; implementations must stay cheap
289 no daemon socket on Windows; in-process collection, the only use of the collectors dependency; snapshot does not replace the instance list
322 overlays are Option state on AppState; openers call close_overlays; draw_active_manager
322, 325 mutating action stages ApprovalRequest; job only on Approve; CLI mutates; read-only direct; bench-run exception
322, 296 chat tool approval is a separate path; execute_approved blocks; overlays do not use tool_exec
384, 290 one State for all jobs, outlives an overlay; unbounded channel on purpose, bounded in the reducer
299, 301, 303-308 reuse the shared ui/ components
308 dash_text_edit_contract.rs enforces the text-edit helper; Chat input excepted
272-275 chat_runtime, terminal, focus, update_check are leaves of event_loop.rs
269 app/mod.rs re-exports keep crate::app::* paths
349 tabs only read AppState while drawing, except Chat writes scroll bounds back
270 MENU_ITEMS is the one source for menu rows, labels, wrap bound and reserved height
351 outlined_chip_spans is the one tab geometry for painter and click resolution
292 llm.rs strips credentials from a loopback base URL
334 serve_wizard's is_loopback_host is a different, stricter function; default invocation rocm serve MODEL keeps the CLI the authority (incl. GPU-required policy)
apps/rocmd and the engines (22)
Old line Claim
158, 159, 168 daemon runs as rocmd or embedded in rocm; supervise is rocmd's, engine commands rocm's; DaemonHost holds the one exe path
155 anthropic_proxy is a library module started by rocm's run_builtin_engine_serve_http on a thread of the engine-owning process
156 common.rs only chooses the child env; capture/spawn are rocm-core command_capture.rs, shared with rocm's chat tool bridge
179 parse_args exported because apps/rocm's test-only advised_commands.rs uses it
166 sandbox_tool.rs imports nothing in the crate so vocabulary users do not import cli.rs
169, 172 a watcher child reaches only policy.rs among siblings, and gpu_metrics.rs for thermal-protect
170 pending_proposal_exists is the check thermal-protect and server-recover use against duplicate proposals
174 therock-update contained mode is read-only, never applies an update
175 driver-upgrade contained mode executes no driver command
176 cache-warm queues even in contained mode (source-policy approval)
440, 444 GPU-required: CPU-only refused not downgraded; rocm before vulkan, never cpu
439, 441, 444 lemonade modules form no import cycle outside test code (backend_alignment -> llamacpp_backend -> direct_llama -> process, none back)
443 LemonadeRuntime/resolve_runtime in install.rs so state/process/direct_llama avoid importing backend_alignment
438 archive_props included once at the crate root for archive_extract.rs and install.rs
442 footprint re-exported at crate root for rocm storage / rocm runtimes uninstall
424 discover_builds.rs is the single list of discovery ROCm SDK versions; install routing, static fallback, launch env all read it
425, 427, 431 install reads wheel_builds/discover_builds and asks repair; repair imports nothing from install; wheel_builds imports only discover_builds
428 runtime path derivation writes nothing; compat-shim writes only via ensure_therock_compat_shims from process.rs; running-state payload never calls it
429 startup log re-rendered through terminal::rendered_lines, not stripped (stripping welds progress-bar repaints)
455 aim serve_http is what rocmd supervises; crash or vanished container recorded failed with non-zero exit so recovery runs
454 Docker Hub lookup is only a hint; failure never blocks a launch
453, 456 container_name in docker.rs so process.rs and state.rs both reach it; state.rs uses no process.rs item
xtask and tests/e2e-cucumber (8)
Old line Claim
Crate Bullet (first words)
xtask "The seven *_contract.rs files define no command"
xtask "affected.rs is the one crate selection"
xtask "paths.rs is the single definition"
e2e-cucumber "Test targets" (lead-in, 2 sub-bullets)
e2e-cucumber "The library target depends on no product crate"
e2e-cucumber "The report generator lives in crates/e2e-report"
e2e-cucumber "Copies of product logic that drift" (lead-in, 3 sub-bullets)

Decisions for the reviewer

  • Checker scope. check-architecture-doc now covers xtask/src, tests/e2e-cucumber/src and tests/e2e-cucumber/tests, so the 109 hand-kept rows hold by construction. The helper exemption (test_support.rs, *_props.rs and so on) applies only to the product crates; in those two trees every file needs a row whatever its name, because nothing there is shared test support of a production crate. AGENTS.md, CONTRIBUTING.md, the pull-request template, docs/testing.md and docs/architecture.md say which trees are covered. The CI step name still reads "Every production source file has an entry", which stays true, and I left the workflow file alone.
  • History note. It is one sentence plus a pointer to git log --follow. Say if it should go entirely.

Follow-ups, not done here

  • The //! headers listed under "Source headers that disagree with their code" are reported, not changed, including the dash_seam.rs header that says the dash crates stay free of rocm-core. Fixing a header is a code-comment change in the file's own crate and is not part of this ticket.
  • The comments in rocm-core that cite docs/host-probing.md by name are reworded when that note is retired, as the note now says: it lists the seven files that cite it today and says the list is a snapshot, so retiring it starts with a repository-wide search for the file name.

Checklist

  • Bug-fix xfail rows: not applicable, this is not a bug fix.
  • New subcommand or subsystem: not applicable, nothing is added.
  • Production source files: none added, renamed or removed by this PR (the seven new ones, config_proptests.rs, persisted_paths_props.rs, therock/python_config_props.rs, sigpipe.rs, stdio_client.rs, fake_engine.rs and cli_args.rs, came in with main and have rows). cargo xtask check-architecture-doc passes, and every row's description was written from the file's own header and checked against the code.
  • User-facing messages: not applicable, no CLI output changes. The --help text of cargo xtask check-architecture-doc now names the three added trees; no rocm command is affected.
  • Instruction files: AGENTS.md changes only the list of trees the check covers, one clause in the architecture-check bullet, and the pull-request template likewise.

@github-actions

github-actions Bot commented Nov 10, 2026 •

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

View the security scan run for complete reports.

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

@jussielo-amd
jussielo-amd requested a balanced review from Copilot November 10, 2026 11:46

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot wasn't able to review any files in this pull request. Copilot's per-file or total diff limits were exceeded. Try reducing the changed content or splitting the changes into smaller pull requests, then request a review from Copilot again.

@jussielo-amd
jussielo-amd marked this pull request as ready for review November 10, 2026 11:47
@jussielo-amd
jussielo-amd requested a review from a team as a code owner November 10, 2026 11:47
@jussielo-amd
jussielo-amd requested review from volen-silo and a balanced review from Copilot November 10, 2026 11:47

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot wasn't able to review any files in this pull request. Copilot's per-file or total diff limits were exceeded. Try reducing the changed content or splitting the changes into smaller pull requests, then request a review from Copilot again.

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Nice restructure, and the PR body's old-line-to-Boundaries mapping made this easy to check. One thing needs fixing before merge, plus a few smaller points.

Blocking

  • The PR is in conflict with main. Main's #1010 rewrote the module-size paragraph to say the gate now blocks merges (the clippy CI job fails; only the pre-commit hook still just reports). This PR still carries the old "advisory until no file is over the limit" wording, so resolving the conflict in favour of this side would put a claim back that AGENTS.md now contradicts. Please rebase, take main's wording for that paragraph, and update the "carried over word for word" note in the PR body. Since main has moved, the ticket's "reviewed against current main" criterion also needs a re-check after the rebase.

Non-blocking

  • Some accurate claims were dropped without appearing in the PR body's dropped list, which the ticket asks for: ensure_public_bind_engine_supported (refuses a public bind with Windows managed Lemonade, whose key can't be enforced; this one is security-relevant, so I'd restore it as a Boundaries bullet), the shared DEFAULT_ENGINE_MARKER constant, and PlannedPython's python_note/update_note being derived from the decision.
  • The header says test-only helpers need no row, but the tables give them rows (inline comment).
  • The Class column has six values where the ticket names three. You already flag this as your call, so just noting it.
  • The 105 xtask and e2e-cucumber rows are hand-kept with no check behind them, as the PR body says.

CI is green apart from the conflict. I checked structure (499 rows, no duplicates, consistent columns, old link targets still linked) but not that each row's description matches the code.

Comment thread docs/architecture.md Outdated

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 (`<crate>/src/<path>.rs` reads `<crate>/proptest-regressions/<path>.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).

A flat size limit backs this convention: `cargo xtask check-module-size` ([`module_size.rs`](../xtask/src/module_size.rs)) reports every source file with more than 1,500 production lines, and there is one limit for every file, with no per-file ceilings, baseline or exemption. Production lines exclude test-gated items (inline `#[cfg(test)]` modules and the like), and test-only files are not source files; the exact definition is at the top of that file. Today the check is advisory: the `clippy` CI job and the `cargo-module-size` pre-commit hook print the offenders without failing, until the files over the limit have been split. A PR that would push a file past 1,500 production lines splits it in the same change (a pure move, the tests moving with the code, this document updated in the same PR); raising the limit or exempting a file is not an option for a feature PR. A change that merely edits a file that is already over the limit does not by itself have to split it: those files are split under their own tickets, and the check becomes blocking only once none is left. `too_many_lines = "allow"` in the workspace `Cargo.toml` stays a deliberate function-level choice; this gate is about files.
A flat size limit backs this convention: `cargo xtask check-module-size` ([`module_size.rs`](../xtask/src/module_size.rs)) reports every source file with more than 1,500 production lines, and there is one limit for every file, with no per-file ceilings, baseline or exemption. Production lines exclude test-gated items (inline `#[cfg(test)]` modules and the like), and test-only files are not source files; the exact definition is at the top of that file. Today the check is advisory: the `clippy` CI job and the `cargo-module-size` pre-commit hook print the offenders without failing, until the files over the limit have been split. A PR that would push a file past 1,500 production lines splits it in the same change (a pure move, the tests moving with the code, this document updated in the same PR); raising the limit or exempting a file is not an option for a feature PR. A change that merely edits a file that is already over the limit does not by itself have to split it: those files are split under their own tickets, and the check becomes blocking only once none is left. `too_many_lines = "allow"` in the workspace [`Cargo.toml`](../Cargo.toml) stays a deliberate function-level choice; this gate is about files.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

This paragraph still says the module-size check is advisory and becomes blocking only once no file is over the limit. Main (#1010) now documents it as blocking in the clippy CI job, with the hook still only reporting, and this is what causes the merge conflict. Please rebase onto main and take its wording here; the PR body's "carried over word for word" note needs the same update.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in ebf02f6: rebased onto main (1530f6b) and took its module-size paragraph word for word, so it now says the gate blocks merges and only the hook still reports. The "carried over word for word" note in the PR body now says the paragraph is taken from main.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Main has moved again since the last push (the version-reporting change touched diagnose_cmd.rs's entry), so the branch now carries a merge of current main. The only conflict was in this file, and it is resolved by keeping this branch's tables and carrying the one entry main changed (diagnose_cmd.rs, which now builds its report through prepare_cli_report) into its row. The module-size paragraph is byte-identical to main's current one (the check blocks merges through the clippy CI job; the cargo-module-size hook still only reports), and the PR body's "carried over word for word" note says the same. check-architecture-doc, check-module-size, check-crate-edges, manifest --check and the full xtask tests pass on the merged head, and git merge-tree against main is clean.

Comment thread docs/architecture.md Outdated

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; `<path>` 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. 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; `<path>` 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`, `*_proptests.rs`, `*_props.rs`, `*_properties.rs`) need no row. There is no exemption list: a production file 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. It does not cover the `xtask` and `tests/e2e-cucumber` tables, which are kept current by hand.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

This says test-only helpers need no row, but the tables below give them rows (test_support.rs, archive_props.rs, process_tree_properties.rs, ...). Reword to "may have a row" so the doc doesn't contradict itself.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in ebf02f6: reworded to "may have a row but need none", which matches both the check and the tables.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

The wording is "may have a row but need none", which matches both the check (test_support, test_env, proptests and the *_proptests, *_props and *_properties stems are out of scope for the link requirement) and the tables, which give those files rows. It is unchanged by the merge with main.

@jussielo-amd
jussielo-amd force-pushed the docs/architecture-per-crate-tables branch from 90cbf41 to ebf02f6 Compare November 10, 2026 12:57
@jussielo-amd

Copy link
Copy Markdown
Collaborator Author

Thanks for the careful read. Pushed ebf02f6, rebased onto main (1530f6b). Blocking: the module-size paragraph is now main's wording, and the same rebase picked up main's change to the therock/python.rs entry. Non-blocking: ensure_public_bind_engine_supported, DEFAULT_ENGINE_MARKER and the PlannedPython notes are now Boundaries bullets, and the PR body lists the other claims dropped because the file itself states them. The Class column's six values and the 105 hand-kept rows are left as the body describes them, for you to decide.

@nowycondro nowycondro left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

🤖 Automated review · review-code · head ebf02f6f

Review — no blocking findings

Full review of the whole change (one file, docs/architecture.md, 820 insertions / 417 deletions). Implements ROCMAI-768's documented scope: restructuring the architecture doc into per-crate tables with Boundaries lists; ticket named but not retrieved here (kept out of a public review) — judged only against the PR description's own stated intent, which this change matches (see below).

Blocking

None

Non-blocking

None

Decisions for the author

  • Class column: six values where the ticket names three — tradeoff, already raised by the PR body itself. Verified the distinction is at least internally defensible: fix.rs (flat) owns no public types of its own (only a private enum Plan plus apply/plan_of/act_on), while its Boundaries-grouped "module front" siblings diagnose.rs, examine.rs and host_gpu.rs (all domain) each own several pub struct/pub enum types — so the Class axis (extraction pattern) and the Boundaries grouping (directory-fronting for link stability) are legitimately answering different questions, not contradicting each other. No better taxonomy surfaced; the author's open question stands as asked.
  • 105 xtask/tests/e2e-cucumber rows are hand-kept with no check-architecture-doc coverage — tradeoff, already raised by the PR body. Row count verified exactly (105, matching file-for-file against both trees) and nothing in this pass suggests the hand-kept tables are currently wrong; the risk is only that they can drift silently later, which is the same risk the author names as a possible follow-up (extending in_scope()).
  • History section: keep vs. drop — tradeoff, already raised by the PR body. No issue found with keeping it as written.

Positive signals

  • Self-verification claims in the PR body check out exactly rather than approximately: 499 table data rows (independently counted), 105 hand-kept rows (29+5+4+32 e2e-cucumber + 35 xtask), the two paragraphs claimed "word for word" from the old doc / from main are byte-identical diffs, and file sizes (156,226 / 303,411 bytes) match the claimed ~152 KB / ~295 KB.
  • Every one of 537 production source files across all ten crates has exactly one table row, with zero missing files and zero duplicate file-links across the whole document — all independently counted, not sampled.
  • Several safety/behavioral invariants that the restructuring's one-line rows no longer state (e.g. update_supervised_record's never-clobber-another-supervisor's-record guarantee in apps/rocmd/src/supervise.rs, the autostart-lock release ordering in daemon.rs) remain fully stated in those files' own doc/inline comments — the "push invariants into the file, trim the table" discipline the PR body describes was followed consistently everywhere this pass sampled.

Deployment notes

No production code or test changed (confirmed: 1 file changed). GitHub currently reports mergeable_state: blocked with mergeable: true — merge-base against main is exactly main's current tip (no textual conflict), and CI is green. This most likely reflects an outstanding "changes requested" review from an earlier commit (90cbf41) that hasn't been re-reviewed: diffing that commit against the current head shows every point from that review (module-size paragraph wording vs. AGENTS.md, the three dropped-claims additions, the test-helper-row wording) already addressed verbatim in the current head.

What this covered

Full text of docs/architecture.md at both 1530f6b1 (merge-base/main) and ebf02f6f (head), read completely across six independent blind workers split by crate-table section plus one front-matter/whole-document structural pass, each cross-checking rows and Boundaries bullets against the actual Rust source tree and (for the front-matter pass) AGENTS.md. Four candidate findings surfaced by workers were checked against primary sources in consolidation and did not survive: three claimed "unrecoverable" dropped guarantees in apps/rocmd turned out to be stated in the relevant files' own doc/inline comments, and one claimed Class-taxonomy inconsistency (fix.rs) turned out to be a defensible distinction under the PR's own stated Class definitions.

Did not run: no test suite (nothing to execute for a docs-only change); CI read from GitHub's check-rollup rather than re-derived (all green, two jobs still in-progress and non-blocking). History and prior-changes passes used git log --follow on this file; the only prior precedent (#1010, already on main) is already reconciled in this head. Design review treated the PR body's own three open questions (Class taxonomy, hand-kept tables, History section) as tradeoffs rather than re-litigating them.

One disclosure: the claim-check step mandated before this review (confirming no duplicate review existed yet) required fetching full review text, which surfaced one prior human review's content to this consolidating context before scoring — the fan-out workers that produced the raw findings never saw it. Where that review's content overlapped with this pass's own checks (the module-size paragraph, the three dropped-claims additions), this report verified them independently against primary sources (byte-level diffs, grep against the current source tree) rather than taking the prior review's word for it; it is noted here rather than silently treated as a blind result. Not otherwise reconciled against PR discussion.


Not a human review. This is an automated code review; please verify findings independently before acting on them.

docs/architecture.md was one long paragraph per file, mixing a one-line
responsibility with phase history, ticket ids, caller lists and
visibility notes, so finding where something lives meant reading
several kilobytes of prose.

Each crate now has a table with a row per source file (file, one-line
responsibility, how the file was extracted), and a short Boundaries
list keeps some of the facts a row cannot show: layering and leaf
modules, deliberate privacy, and shared sources of truth. Caller
enumerations, visibility lists, test placement, per-function
inventories and phase or ticket history are dropped. The
module-organization convention is condensed, and a short history note
replaces the phase labels.

xtask and tests/e2e-cucumber get tables too; check-architecture-doc
does not cover them, so those rows are kept current by hand. A citation
of a specific file is a relative link, so lychee checks it.

The rewrite restates the old claims in a shorter form. Claims found to
be stale while rewriting were left out instead of being corrected here,
and the services hint is written as stop|restart|remove so the
advised-commands test that scans docs/ still parses it.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd
jussielo-amd force-pushed the docs/architecture-per-crate-tables branch from ebf02f6 to 9c0e78b Compare November 10, 2026 13:44
The Class column had six values, where the ticket names three (full
domain extraction, mechanical relocation, flat module). The extra
values, root, child and test helper, carried nothing a row does not
already show: the roots are main.rs or lib.rs, children are visible
from their paths, and test-only files say so in their description.

Fold them into flat, keep domain and relocation as they were, and say
in the module-map introduction what flat covers.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Main's amdgpu and kfd probe now answers for a module that is built into the
kernel as well as one that is loaded; the linux_driver.rs row said only
"kernel modules".

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd
jussielo-amd requested a balanced review from Copilot November 10, 2026 14:18

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot wasn't able to review any files in this pull request. Copilot's per-file or total diff limits were exceeded. Try reducing the changed content or splitting the changes into smaller pull requests, then request a review from Copilot again.

@nowycondro nowycondro left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

🤖 Automated review · review-code · head 2b13197b

Review — needs work

Full review of the whole change (one file, docs/architecture.md, 820 insertions / 417 deletions, merge-base 6e7cdf53 → head 2b13197b). Implements ROCMAI-768's documented scope: restructuring the architecture doc into per-crate tables with Boundaries lists; ticket named but not retrieved here (kept out of a public review) — judged only against the PR description's own stated intent, which this change matches.

Blocking

  • The PR currently has a real, live merge conflict with main — the "merged cleanly" claim in the PR body is no longer true — docs/architecture.md
    GitHub's live state (mergeStateStatus: DIRTY, mergeable: CONFLICTING) and a direct git merge-tree origin/main pr/1016 both confirm CONFLICT (content): Merge conflict in docs/architecture.md. Cause: this branch's last main-merge commit only incorporated main up to 6e7cdf53; main has since gained commit bcea1525 ("configure fish even when it is not the login shell", #816), which added a sentence to the uninstall.rs entry — the Linux installer's fish-completion-script removal (plan_completion_removals) — that this branch's restructured uninstall.rs row doesn't reflect (its current text is only "...undoing the installer's PATH change and deleting the running rocm.exe on Windows"). The PR body's own "Checks run" section states "Merged with current main...; git merge-tree --write-tree origin/main HEAD is clean" — true when written, false now. This is the second time in this PR's life that main has drifted out from under it this same way (the first instance, already fixed in this head, was PR #1010's module-size-paragraph wording) — docs/architecture.md is, by its own history, touched by nearly every merged PR, so a long-lived restructuring branch is structurally exposed to this.
    Confidence 100 (ran git merge-tree directly; cross-checked live GitHub mergeability).
    Fix: rebase/merge origin/main again, fold the fish-completion-removal behavior into the uninstall.rs row (or add it to this PR's own "dropped claims" list per its stated methodology), and re-confirm the "reviewed against current main" claim afterward.

Non-blocking

None

Decisions for the author

  • 105 xtask/tests/e2e-cucumber rows are hand-kept with no check-architecture-doc coverage — tradeoff, already raised by the PR body. Row count verified exactly (35 xtask + 29+5+4+32 e2e-cucumber = 105), and every file in both trees has exactly one row with no gaps or duplicates; the only risk is future silent drift, which the PR body itself names as a possible follow-up.
  • History section: keep vs. drop — tradeoff, already raised by the PR body. No defect found with it as written (one sentence, points at git log --follow, carries no phase labels or ticket IDs).

Positive signals

  • Every quantitative self-verification claim in the PR body checks out exactly: 499 table rows, 394 production-file links, 105 hand-kept rows, and the proptest-regression and module-size paragraphs are byte-identical to the old doc / current main respectively (diffed directly, not sampled).
  • Full row/file coverage with zero gaps and zero duplicates, independently counted crate-by-crate: apps/rocm 118/118, apps/rocmd 26/26, rocm-core 92/92, the four dashboard crates 114/114, the three engine crates 31/31.
  • The non-blocking gaps and wording nitpick an earlier human review round on this PR raised (ensure_public_bind_engine_supported, DEFAULT_ENGINE_MARKER, PlannedPython's python_note/update_note, and the self-contradicting "need no row" wording) are all now present and correct in the current head, verified against source rather than taken on trust.
  • A sample of security/safety-relevant Boundaries claims traced directly against source and confirmed accurate: the GPU-required no-CPU-fallback refusal in engines/lemonade/src/device_policy.rs, the Windows/Lemonade public-bind refusal in service_launch/endpoint_auth.rs, the ROCDXG_PINNED_DIGESTS trust-anchor claim, the by-construction-shared vllm_oom marker constants, and the diagnose/ platform-checkers' mutual independence.
  • Link-citation convention (this repo's AGENTS.md §5) fully complied with: zero file.rs:42-style line-number leaks, zero reference-style link definitions, zero query-suffix or root-relative link targets; every bare-backtick .rs mention checked is a genuinely generic reference (main.rs, lib.rs, mod.rs, build.rs, or a non-unique test_support.rs), never a dodge around a real, specific, linkable file.

Deployment notes

Docs-only change: no production source or test file touched (confirmed: 1 file changed). Every CI check that ran for this commit is green. The only thing standing between this PR and merge-readiness is the live merge conflict above.

What this covered

Read the whole of docs/architecture.md at the current head against its merge-base with main, plus the Rust source tree it describes (apps/rocm, apps/rocmd, crates/rocm-core, the four rocm-dash-* crates, the three engine crates, crates/rocm-engine-protocol, crates/rocm-deps, crates/e2e-report, xtask, tests/e2e-cucumber) and the root AGENTS.md.

Fan-out was partially degraded: a shared sub-agent pool serving concurrent, unrelated work on this host repeatedly returned "concurrent subagent limit reached," and two of the sub-workers that did get spawned (covering apps/rocm's full row set, and a dashboard-crates re-run) terminated with a one-line placeholder instead of findings. Only one sub-worker — a blind pass over this file's git history and its link-citation-convention compliance — completed with independent findings (folded in above). Every other section (apps/rocm, apps/rocmd + the three engine crates, crates/rocm-core, the four dashboard crates, xtask/tests/e2e-cucumber/the remaining small crates) was instead read and verified directly by this consolidating context rather than by a separate blind worker. These sections are not independent of each other, though every claim reported above was traced against primary source (file headers, grep, diff) rather than asserted; the row/file-count and byte-identity checks are exhaustive, but per-row prose-accuracy checking across apps/rocm and the dashboard crates in particular was a sample, not an exhaustive per-row re-derivation.

Did not run: no test suite (nothing to execute for a docs-only change); CI read from GitHub's live check-rollup rather than re-derived. Design review treated the PR body's own two open questions (hand-kept tables, History section) as tradeoffs rather than re-litigating them.

One disclosure from the mandated pre-review duplicate check: fetching this PR's review list to confirm no review already existed at this exact head necessarily surfaced the full text of one earlier human review round and one earlier automated review round (both at earlier commits) to this consolidating context before any findings were produced. Where this pass's conclusions overlap with points those rounds raised (the merge-conflict pattern, the previously-flagged non-blocking gaps), this report re-derived each one independently against primary sources rather than taking the earlier rounds' word for it; the live merge-conflict finding above is new relative to both of them, since main has drifted again since the most recent of those rounds. Not otherwise reconciled against PR discussion.


Not a human review. This is an automated code review; please verify findings independently before acting on them.

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Blocking

  • The PR is CONFLICTING with main. Main commits cf20ee1 (#990, kernel-release read; examine/host_env, host_gpu/os_facts, examine/wsl) and bcea152 (#816, fish install) touched docs/architecture.md after this branch's base, and their claims need carrying into the new per-crate rows since the old rows are gone. Main also added tests/e2e-cucumber/src/stand_in_uname.rs, which needs a hand-kept row because check-architecture-doc doesn't cover that crate, and uninstall.rs grew by ~700 lines on main, so its row may need rewording. CI ran against the PR head without the merge, so please rerun after resolving, and the ticket's "reviewed against current main" criterion needs a re-check after that.

Non-blocking

  • The ticket asks for every dropped or moved claim to be listed. The body lists moved claims and the non-derivable drops, but for claims dropped by rule it gives only counts and points at d027ff8. Please confirm that SHA stays reachable after squash/rebase, or say explicitly that counts are the intended level of detail.
  • Known-stale claims were dropped rather than corrected; fine for this scope, but a follow-up PR is needed so those rows don't silently omit them.

Checked and clean: all 394 production .rs files under apps//src, crates//src, engines/*/src are linked, plus 105 xtask/e2e-cucumber files (499 rows, matching the body); no dead ../ links; no phase labels or ticket keys remain; leak scan clean; Class column uses the three ticket values. Row prose was not verified against source file by file.

Keeps this branch's per-crate tables and carries main's changes to docs/architecture.md into them: the fish completion removal in the uninstall.rs row, the durable atomic write, the single kernel-release read, and rows for the four production and test files main added.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd
jussielo-amd requested a balanced review from Copilot November 10, 2026 15:55

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot wasn't able to review any files in this pull request. Copilot's per-file or total diff limits were exceeded. Try reducing the changed content or splitting the changes into smaller pull requests, then request a review from Copilot again.

@nowycondro nowycondro left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

🤖 Automated review · review-code · head 7d278e2f

Review — no blocking findings

Full review of the whole change (one file, docs/architecture.md, 824 insertions / 417 deletions). Implements ROCMAI-768's documented scope (restructuring the architecture doc into per-crate tables with Boundaries lists); ticket not retrieved here (internal tracker, kept out of a public review) — judged only against the PR description's own stated intent, which this change matches.

Blocking

None

Non-blocking

  • "Failure catalog" Boundaries bullet overclaims the e2e crate's tie to the catalog — docs/architecture.md:362 (the bullet on RECIPES/fix/catalog.rs)
    The bullet says "the diagnose tests and the e2e crate hold their own copies to it through the catalog's test-only oracles." The oracles (is_catalog_id and siblings) are declared pub(crate) in crates/rocm-core/src/fix/catalog.rs and re-exported pub(crate) from fix.rs, so they are invisible outside the rocm-core crate regardless of tests/e2e-cucumber's Cargo.toml dependency on it. tests/e2e-cucumber/src/lib.rs in fact defines its own, independent is_catalog_id (id.starts_with("fix-") || id.starts_with("info-")) with no structural tie back to RECIPES — exactly the kind of silent-drift risk this Boundaries section exists to rule out. This is a pre-existing inaccuracy carried over verbatim from the old document (old line 241, itself listed in this PR's own "Moved to Boundaries" table), not introduced or worsened by this restructuring, so it is not blocking — but since the PR's explicit method is independent spot-checking of every Boundaries claim against source, it's worth fixing in this pass or filing alongside the other "found stale" items already tracked in the PR body.
    Confidence 85 · mechanical · Fix: reword to say the e2e crate keeps its own independent heuristic (not a copy reached through the oracles), or restrict the claim to the diagnose tests only.

Decisions for the author

  • Class column: six-reduced-to-three values vs. Boundaries grouping — tradeoff, already raised by the PR body. No new objection; fix.rs (flat, owns no public types beyond a private enum Plan) vs. its "module front" siblings diagnose.rs/examine.rs/host_gpu.rs (domain, each owning public types) shows the Class axis and the Boundaries grouping are legitimately answering different questions.
  • 105–106 hand-kept xtask/tests/e2e-cucumber rows with no check-architecture-doc coverage — tradeoff, already raised by the PR body. Verified exactly complete (every .rs file in both trees has exactly one row, zero gaps, zero duplicates); the only risk is future silent drift, which the author already names as a possible follow-up.
  • History section: keep vs. drop — tradeoff, already raised by the PR body. No issue with it as written.

Positive signals

  • Every row/file-count claim is exactly right, independently verified crate-by-crate (not sampled): all ten crates, xtask, and tests/e2e-cucumber each show an exact 1:1 match between table rows and real .rs files at the PR head, with zero missing files, zero duplicate rows, and zero stale rows anywhere in 503 total rows.
  • A broad, safety-weighted sample of rows and Boundaries claims (GPU-required no-CPU-fallback refusals in both Lemonade and vLLM, the Lemonade archive extractor's path-traversal containment, the rocDXG pinned-digest trust anchor, the AIM supervision/failure-recording contract, atomic-write durability/permission/symlink semantics, the single kernel-release reader, import-direction claims across apps/rocm's chat/runtime/service layering and all four dashboard crates) traced correctly against the actual source in every case checked.
  • No stray phase labels or ticket identifiers remain anywhere in the document (verified by grepping the whole file), matching the PR's stated goal.
  • Link-citation convention (this repo's AGENTS.md §5) fully complied with: every specific file citation is a relative markdown link, zero file.rs:NN line-locators, bare backtick mentions are only the explicitly-allowed generic names (main.rs, lib.rs, mod.rs, test-helper patterns).
  • The module-size paragraph's wording exactly matches AGENTS.md's current post-#1010 text (merge-blocking clippy gate, advisory-only pre-commit hook) — the staleness a previous review round on this PR flagged against an earlier commit is confirmed fixed in this head.
  • All four of the PR's self-described "entries main changed since the base merge" (the uninstall.rs fish-completion removal, the converged kernel-release reader, atomic_write.rs's durability/symlink semantics, and diagnose_cmd.rs's prepare_cli_report) are independently confirmed present and accurate in the current head's rows.

Deployment notes

Docs-only change (confirmed: 1 file changed, no production source or test touched). All CI checks for this head (7d278e2f858d762c56c42575a9a4ce64ee75f54c) are green or skipped-as-expected for a docs-only change.

GitHub reports mergeable_state: blocked, but a direct git fetch + git merge-tree against the current origin/main tip (two commits ahead of this branch's last main-merge, f573ba0/9d404f5 — neither touches docs/architecture.md or adds/removes a production source file) completes with no conflict. The recurring merge-conflict problem flagged in earlier rounds on this PR is resolved as of this head; the blocked state most likely reflects the still-open CHANGES_REQUESTED review from an earlier commit that hasn't been dismissed/re-reviewed on GitHub, whose substantive concern (the conflict with main) is independently verified fixed here.

What this covered

All ten crate tables, the xtask and tests/e2e-cucumber tables, the front matter and the History section — every line of docs/architecture.md at the PR head, read completely. Coverage was split six ways by crate grouping: three ran as independent background workers (apps/rocm; apps/rocmd + the three engines/* crates; crates/rocm-core), each cross-checking its rows and Boundaries bullets against the real source tree via git show/git ls-tree at the fetched PR-head ref and against AGENTS.md. The other three groups (the four dashboard crates; the small crates + xtask; tests/e2e-cucumber + History) were read and verified directly by this consolidating context after a shared subagent pool repeatedly returned "concurrent subagent limit reached" — a re-spawn was attempted once for each before falling back, so these three passes are not independent of this report's own judgment, disclosed here per the method's rule on absorbed worker losses.

Mergeability was checked by fetching the PR head and current main read-only into a scratch repo and running git merge-tree directly, not by trusting GitHub's cached mergeable_state alone. CI was read from GitHub's check-rollup (45 checks, all green or intentionally skipped) rather than re-derived.

Did not run: no test suite (nothing to execute for a docs-only change). Design review treated the PR body's own three open questions as tradeoffs rather than re-litigating them.

One disclosure: the mandated pre-review duplicate-head check required fetching the full review list and the current PR body, which necessarily surfaced prior review rounds' content and the author's own description to this consolidating context before scoring. The one finding reported above was verified independently against primary source (Rust visibility modifiers and the actual, differing implementations in both crates) rather than taken from any prior round — no earlier round on this PR flagged it. Not otherwise reconciled against PR discussion.


Not a human review. This is an automated code review; please verify findings independently before acting on them.

Keeps this branch's per-crate tables and carries main's changes to docs/architecture.md into them: the single CPU model-and-vendor read in the host_env.rs, os_facts.rs and windows_inventory.rs rows and the host-probing note, and node_efficiency in the efficiency.rs row. Main added no production source file in this range.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd
jussielo-amd requested a balanced review from Copilot November 10, 2026 17:48

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot wasn't able to review any files in this pull request. Copilot's per-file or total diff limits were exceeded. Try reducing the changed content or splitting the changes into smaller pull requests, then request a review from Copilot again.

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I went through the restructure and found nothing blocking. The per-crate tables are consistent with the tree: every in-scope source file has exactly one row, relative links resolve, the backticked identifiers I checked exist, and a sample of the content claims (including the six comment-edited rows) matched the code. CI is green on the current head.

A few non-blocking notes:

  • Scope: the ticket says no production code or test changes, but this PR also touches the xtask checker (with new unit tests), six module comments in apps/rocm, AGENTS.md, CONTRIBUTING.md, the PR template and docs/testing.md. The description discloses all of it and the commits are separate, so I'm fine with it, but it is worth noting against the acceptance criteria.
  • The PR description says "nine module comments" in the summary and "six" further down; the diff touches six.
  • One inline comment on the "Unbounded readers" bullet, which reads as status about unfinished work.

I did not check every one of the ~480 remaining row descriptions line by line, nor information loss against the previous version of the doc.

Comment thread docs/architecture.md Outdated
- [`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). 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_catal

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

This bullet is status wording about unfinished work ("not yet the only bounded runner ... still join their reader threads with no time limit"), which the PR description says was dropped by rule because it drifts. Consider dropping it or stating it as a plain present-tense fact about the code.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Agreed, that bullet read as status about unfinished work. 2b79aab rewrites it as a plain present-tense fact and drops the "not yet" framing and the "Unbounded readers" label. It now says that run_with_timeout abandons a pipe reader that has not finished shortly after the child is gone, so a grandchild holding a pipe cannot outlast its timeout, and that therock/process.rs, probe_exec's run_raw and the host_gpu capture helpers join their reader threads with no time limit, so there a grandchild can outlast the timeout. I re-read each of those runners against the sentence before keeping it, and kept the fact rather than dropping it because it is the one thing a reader choosing a runner cannot see from the file table.

The module comment still named a ticket for the cluster that follows the one it describes, which the architecture document does not define. It now names that cluster by what it holds and says where it lives.

Comment-only; no code changes.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…s it

The intro said every citation of a specific file is a relative link, but the tables and Boundaries link a file at its first mention in a row or bullet and leave later mentions in that row or bullet bare. It now says that, and names the exceptions the document already makes: generic names, runtime and generated files, and files not tracked in this repository.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The bullet described which runners were not yet the bounded one, which reads as unfinished work and drifts. It now says what run_with_timeout does with a reader that has not finished and what the other runners do with theirs, checked against process.rs, probe_exec.rs, host_gpu/capture.rs and therock/process.rs.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟢 Approval recommended

No active review issues are recorded for the expanded architecture-checker coverage and aligned documentation.

No open issues 🎉

Review effort: Balanced

@nowycondro nowycondro left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

🤖 Automated review · review-code · head 2b79aabf

Review — no blocking findings

Full review of the whole change. Closes ROCMAI-768 (an internal tracker identifier; per this review's own instructions it is named but not fetched or guessed at, since this is a public repository).

Blocking

None

Non-blocking

None

Decisions for the author

  • Stale "Phase N" vocabulary survives in five untouched sibling files — pre-existing, pattern-relevant
    apps/rocm/src/main.rs, freeform_execution.rs, serve_cmd.rs, runtime_services.rs, and service_launch.rs still reference a "Phase 6a/6b/6c/6e/6f" vocabulary and point readers at docs/architecture.md, which no longer explains it (the PR's own six-file comment cleanup didn't reach these). Out of this PR's explicitly stated scope ("six module comments"), so not blocking, but worth a fast follow-up so those comments don't send a reader chasing a vocabulary the doc has dropped.
  • The doc-coverage checker verifies row presence, not row content — tradeoff
    check-architecture-doc (and its newly widened scope) guarantees every in-scope file has exactly one row, but nothing automated catches a row that drifts out of accuracy after this merges — the same limitation the old prose had. The restructuring makes a missing row far easier to notice (one line per file instead of paragraphs), but accuracy still rests on the next editor rereading the source. Not a defect in this PR; flagging so the author can confirm this is the accepted tradeoff rather than an assumed-but-unstated guarantee.
  • The detailed "claims dropped and not derivable from one file" inventory lives only in the PR description — tradeoff
    The description's apps/rocm / rocm-core / dashboard / rocmd-and-engines lists of true-but-dropped behavioural invariants (e.g. "gguf_source never follows a redirect from https to http") are a genuinely useful cross-reference, but they exist only on the GitHub PR page, not in the repository tree. Each invariant is independently documented in its own source file (per the author's own text), so nothing is lost from the code itself — but the aggregated map of where to look is not committed anywhere and will not survive outside GitHub's PR history. Worth the author's own call on whether any part of that index belongs in-repo (e.g. folded into History) for long-term discoverability.
  • Every row in the xtask and tests/e2e-cucumber tables is classed flat — non-blocking-improvement
    Uniformly true per the Class column's own definition (tooling/test files, not domain-extracted subsystems), so not wrong, but the column carries zero discriminating information across those 109 rows. A future revision could consider whether the Class column is worth including at all for these two trees, or document the 100%-flat expectation explicitly so a reviewer doesn't wonder whether it was actually checked per-row.

Positive signals

  • The restructuring's headline numbers check out exactly. Independently recomputing the production-source file count across all 13 product crates (counting only each crate's src/ tree, which is what the checker actually requires rows for) gives 401 files, and the two hand-kept trees (xtask/src, tests/e2e-cucumber/{src,tests}) give 109 — summing to 510, matching the PR description's claimed row count exactly.
  • The Class column's non-evaluative caveat is stated in the document itself ("records how a file came to be, not a rule a new file is judged by"), not only in the PR description, so a reader of the doc alone gets the correct framing without needing the PR history.
  • The six apps/rocm/src comment-only diffs are genuinely comment-only — verified line-by-line that no executable code changed in automations.rs, engine_runtime_select.rs, gpu_policy.rs, managed_service_status.rs, uninstall_plan.rs, or update_cmd.rs.
  • The new xtask/src/architecture_doc.rs scope-widening logic is correct and well-tested: the new tree-scoping and helper-exemption logic were traced by hand against edge cases (prefix confusion like xtask/src-backup/, scope leakage between product and hand-kept trees, Windows path-separator risk), and each new test was checked against the "would it still fail if the guarded behaviour were reverted" standard — all five did.

Deployment notes

GitHub currently reports this PR's mergeable_state as dirty (conflicts with main, which has moved since the PR's last merge) as of this review. That doesn't affect anything reviewed at the exact head SHA above, but the PR will need a rebase or conflict resolution before it can land.

What this covered

Full diff between base eb2a8194a (main tip) and head 2b79aabf, all 14 changed files, read completely. Split into five independent fan-out workers grouped by coupling: (A) xtask/src/architecture_doc.rs + xtask/src/main.rs — the PR's only code-logic change; (B) docs/architecture.md's apps/rocm table + the six apps/rocm/src comment-only diffs; (C) docs/architecture.md's crates/rocm-core, apps/rocmd, engines/{lemonade,vllm,aim} tables + docs/host-probing.md; (D) docs/architecture.md's dashboard-crate tables (rocm-dash-{core,collectors,daemon,tui}, rocm-engine-protocol, rocm-deps, e2e-report); (E) docs/architecture.md's xtask/tests/e2e-cucumber tables, its Module organization convention/History sections, and docs/testing.md/AGENTS.md/CONTRIBUTING.md/.github/pull_request_template.md. Each worker read its assigned sections of the old and new docs/architecture.md in full and spot-checked 15–30 source files per group against their table rows (100+ spot checks across the 510 rows in total). All five reported directly to me (resumed and re-confirmed individually, not taken on trust from a relayed summary) with no findings at confidence ≥70.

I independently re-verified the single most load-bearing completeness claim myself (the 510/401/109 row counts, recomputed from git ls-files against each crate's src/ tree) rather than relying only on the workers' counts, and fetched live CI (get_check_runs): all 40 check runs are green or correctly skipped, nothing failing.

Did not run: no Rust/cargo toolchain was available anywhere in this sandbox, so none of the PR's own cited commands (cargo xtask check-architecture-doc, the new unit tests, cargo test, cargo clippy, cargo fmt --check) could be independently executed — all conclusions rest on static reading of the diff and source files, capped at confidence 70 unless a claim was directly and textually confirmed against the cited file (up to 85). The "history" (git blame/log on modified regions) and "prior-changes" (do earlier review comments on these files still apply) passes were not run as separate dedicated passes beyond the git log/diff context each worker already had. Per this review's own instructions, this PR's existing review threads and comments were never read for content, only their metadata (for an earlier duplicate-review check) — so this report is not reconciled against any prior round's discussion.


Not a human review. This is an automated code review; please verify findings independently before acting on them.

AGENTS.md conflicted on the module-size line and on the line listing which files need an architecture entry: the module-size wording is taken from main, where the pre-commit hook is now blocking, and the entry line keeps this branch's wider scope (xtask and the end-to-end harness).

docs/architecture.md merged without a textual conflict, with main's module-size paragraph intact. The module_size.rs row still described an advisory form that main removed, so it now describes the one check, including the error for a Rust file no mod declares.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Five more apps/rocm module comments (main.rs, freeform_execution.rs, serve_cmd.rs, runtime_services.rs, service_launch.rs) named a numbered phase and a ticket key of the main.rs split and sent the reader to a vocabulary docs/architecture.md no longer defines. They now name the module that holds each item, which is what a reader can still find. Comment-only; no executable line changes.

docs/architecture.md also says in the Class column explanation that the xtask and tests/e2e-cucumber tables are flat throughout, so the column carries no information there.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
docs/architecture.md conflicted because main's bounded-executor change edited the old per-file entries that this branch replaces with per-crate tables. The branch's tables are kept and the change is ported into them: a row for the new crates/rocm-core/src/process/bounded.rs, the process.rs, command_capture.rs, probe_exec.rs, host_gpu/capture.rs and host_gpu/diagnostics.rs rows, the host-probing Boundaries bullet, and the reader-threads bullet, which now says that the probe runners run on the bounded executor and that only the TheRock install runner still joins its reader threads without a time limit.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
docs/architecture.md conflicted because main's move of the artifact prefetch out of sandbox.rs edited the old per-file entries that this branch replaces with per-crate tables. The branch's tables are kept and the change is ported into the apps/rocmd table: a row for the new artifact_prefetch.rs, the corrected sandbox.rs row, the test_support.rs row (it now also holds the guard that serialises tests over the model recipe registry environment variables), and a Boundaries bullet saying artifact_prefetch.rs is called only by sandbox.rs and does not import it back.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

The retirement checklist omits current references and includes a stale entry, so following it would leave dangling references after the note is deleted.

1 open issue

Review effort: Balanced

Comment thread docs/host-probing.md Resolved
The retirement sentence named four files, but seven rocm-core comments cite the note: command_capture.rs, host_gpu/capture.rs and process/bounded.rs were missing, and examine/wsl.rs still refers to it as the host-probing note. The list now names all seven and says it is itself a snapshot, so retiring the note starts with a repository-wide search for its file name.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟢 Approval recommended

No active review issues are reported for the expanded architecture-checker scope and related documentation and comment updates.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@jussielo-amd
jussielo-amd added this pull request to the merge queue Nov 11, 2026
Merged via the queue into main with commit f04b785 Nov 11, 2026
41 checks passed
@jussielo-amd
jussielo-amd deleted the docs/architecture-per-crate-tables branch November 11, 2026 12:05
rominf added a commit that referenced this pull request Nov 13, 2026
Resolve docs/architecture.md against the per-crate table layout from
#1016: serve_progress.rs gets a row, and the service_hints.rs,
service_launch/readiness.rs, service_launch/start.rs and
watchers/server_recover.rs rows carry this branch's changes.

Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants