Repository navigation
ROCMAI-768: restructure docs/architecture.md into per-crate tables - #1016
Conversation
Security scan found no critical or high findings on lines changed by this pull requestView the security scan run for complete reports. “New” means the finding is located in a changed file on an added or modified line; it is not a base-versus-head findings delta. |
juhovainio
left a comment
There was a problem hiding this comment.
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 sharedDEFAULT_ENGINE_MARKERconstant, andPlannedPython'spython_note/update_notebeing 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.
|
|
||
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
There was a problem hiding this comment.
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.
|
|
||
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Fixed in ebf02f6: reworded to "may have a row but need none", which matches both the check and the tables.
There was a problem hiding this comment.
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.
90cbf41 to
ebf02f6
Compare
|
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 |
nowycondro
left a comment
There was a problem hiding this comment.
🤖 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 privateenum Planplusapply/plan_of/act_on), while its Boundaries-grouped "module front" siblingsdiagnose.rs,examine.rsandhost_gpu.rs(alldomain) each own severalpub struct/pub enumtypes — 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-cucumberrows are hand-kept with nocheck-architecture-doccoverage — 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 (extendingin_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 inapps/rocmd/src/supervise.rs, the autostart-lock release ordering indaemon.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>
ebf02f6 to
9c0e78b
Compare
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>
nowycondro
left a comment
There was a problem hiding this comment.
🤖 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 directgit merge-tree origin/main pr/1016both confirmCONFLICT (content): Merge conflict in docs/architecture.md. Cause: this branch's last main-merge commit only incorporatedmainup to6e7cdf53;mainhas since gained commitbcea1525("configure fish even when it is not the login shell", #816), which added a sentence to theuninstall.rsentry — the Linux installer's fish-completion-script removal (plan_completion_removals) — that this branch's restructureduninstall.rsrow doesn't reflect (its current text is only "...undoing the installer'sPATHchange and deleting the runningrocm.exeon Windows"). The PR body's own "Checks run" section states "Merged with current main...;git merge-tree --write-tree origin/main HEADis clean" — true when written, false now. This is the second time in this PR's life thatmainhas 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.mdis, by its own history, touched by nearly every merged PR, so a long-lived restructuring branch is structurally exposed to this.
Confidence 100 (rangit merge-treedirectly; cross-checked live GitHub mergeability).
Fix: rebase/mergeorigin/mainagain, fold the fish-completion-removal behavior into theuninstall.rsrow (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-cucumberrows are hand-kept with nocheck-architecture-doccoverage — 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
mainrespectively (diffed directly, not sampled). - Full row/file coverage with zero gaps and zero duplicates, independently counted crate-by-crate:
apps/rocm118/118,apps/rocmd26/26,rocm-core92/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'spython_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 inservice_launch/endpoint_auth.rs, theROCDXG_PINNED_DIGESTStrust-anchor claim, the by-construction-sharedvllm_oommarker constants, and thediagnose/platform-checkers' mutual independence. - Link-citation convention (this repo's
AGENTS.md§5) fully complied with: zerofile.rs:42-style line-number leaks, zero reference-style link definitions, zero query-suffix or root-relative link targets; every bare-backtick.rsmention checked is a genuinely generic reference (main.rs,lib.rs,mod.rs,build.rs, or a non-uniquetest_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
left a comment
There was a problem hiding this comment.
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>
nowycondro
left a comment
There was a problem hiding this comment.
🤖 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 onRECIPES/fix/catalog.rs)
The bullet says "thediagnosetests and the e2e crate hold their own copies to it through the catalog's test-only oracles." The oracles (is_catalog_idand siblings) are declaredpub(crate)incrates/rocm-core/src/fix/catalog.rsand re-exportedpub(crate)fromfix.rs, so they are invisible outside therocm-corecrate regardless oftests/e2e-cucumber'sCargo.tomldependency on it.tests/e2e-cucumber/src/lib.rsin fact defines its own, independentis_catalog_id(id.starts_with("fix-") || id.starts_with("info-")) with no structural tie back toRECIPES— 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 thediagnosetests 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 privateenum Plan) vs. its "module front" siblingsdiagnose.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-cucumberrows with nocheck-architecture-doccoverage — tradeoff, already raised by the PR body. Verified exactly complete (every.rsfile 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, andtests/e2e-cucumbereach show an exact 1:1 match between table rows and real.rsfiles 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, zerofile.rs:NNline-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-blockingclippygate, 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.rsfish-completion removal, the converged kernel-release reader,atomic_write.rs's durability/symlink semantics, anddiagnose_cmd.rs'sprepare_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>
juhovainio
left a comment
There was a problem hiding this comment.
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.
| - [`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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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>
nowycondro
left a comment
There was a problem hiding this comment.
🤖 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, andservice_launch.rsstill reference a "Phase 6a/6b/6c/6e/6f" vocabulary and point readers atdocs/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_sourcenever 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 intoHistory) for long-term discoverability. - Every row in the
xtaskandtests/e2e-cucumbertables is classedflat— 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, orupdate_cmd.rs. - The new
xtask/src/architecture_doc.rsscope-widening logic is correct and well-tested: the new tree-scoping and helper-exemption logic were traced by hand against edge cases (prefix confusion likextask/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>
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>
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>

Closes ROCMAI-768.
Summary
docs/architecture.mdwas 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-docwidened toxtaskand the end-to-end harness, eleven module comments that pointed at a phase vocabulary the document no longer has, and the retirement note indocs/host-probing.md.cargo xtask check-architecture-doccovers keeps its row (403 files), andxtaskandtests/e2e-cucumberhave tables as well (109 rows). The check now covers those two trees as well, so every.rsfile underxtask/src,tests/e2e-cucumber/srcandtests/e2e-cucumber/testsneeds a row; each of the 512 rows is the only row for its file.git log --follow.domain(full domain extraction),relocation(mechanical relocation) andflat(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. Thextaskandtests/e2e-cucumbertables areflatthroughout, 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 norocmuser runs, and eleven module comments inapps/rocm/src(comments only, socargo check -p rocmis 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 thextaskcrate, 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 usesgit 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 throughprepare_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.rsand 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.rsand the same Boundaries bullet, which now lists three converged pairs and no longer names the CPU model as a duplicated read),node_efficiencyandNodeEfficiencywith itsheldflag (efficiency.rs), and the shared engine stdio client (therocmandrocmdengine_ipc.rsrows,AppPaths::env_varsin thepaths.rsandengine_runtime_select.rsrows,optional_argin the protocollib.rsrow, and theservice_stop_steps.rsrow, which now also servesengine_ipc.feature), and the shared managed-stop routine with its Windows identity and tree-kill handling andservices remove --force(theproc_lifecycle.rs,process.rs,service_control.rs,launch_transaction.rs,managed_service_status.rs,service_records.rsandservice_hints.rsrows, therocmdservice.rsrow, and theservice_cleanup_steps.rsandservice_stop_steps.rsrows), and the bounded subprocess executor, now incrates/rocm-core/src/process/bounded.rsand re-exported fromprocess.rs(theprocess.rs,command_capture.rs,probe_exec.rs,host_gpu/capture.rsandhost_gpu/diagnostics.rsrows and the host-probing Boundaries bullet). Thirteen files main added have rows too:process/bounded.rs(the executor behindrun_with_timeoutandrun_bounded),apps/rocmd/src/artifact_prefetch.rs(split out ofsandbox.rs, whose row and thetest_support.rsrow are updated and which has a Boundaries bullet),config_proptests.rs,persisted_paths_props.rsandtherock/python_config_props.rs(property tests),sigpipe.rs,stdio_client.rsandfake_engine.rs(the last two inrocm-engine-protocol),cli_args.rs(split out ofcli.rs, whose row now only says it re-exports the value enums), and the hand-kepttests/e2e-cucumber/src/stand_in_uname.rs,stray_process.rs,tasklist.rsandxtask/src/engine_stdio_client_contract.rs(the contract test also moves the xtask Boundaries bullet from seven*_contract.rsfiles 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
rocmdsandbox module and is ported the same way; before that 8027e69, which includes the bounded-executor change:docs/architecture.mdconflicted 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, inAGENTS.md, resolved by taking main's module-size wording and keeping this branch's wider architecture-entry line;docs/architecture.mdmerged cleanly with main's module-size paragraph intact, and themodule_size.rsrow, which still described the advisory form main removed, now describes the one check). An earlier merge (eb2a819) had one conflict, indocs/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 HEADis clean.cargo xtask check-architecture-doc,check-module-sizeandcheck-crate-edgespass, andcargo fmt --checkis clean.cargo xtask check-architecture-docfails when a row is deleted, as expected, now also forxtask/src/eval_fixtures.rsandtests/e2e-cucumber/tests/e2e/bench_steps.rs(rows deleted by hand on the real tree, then restored).in_scopenot 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; agit ls-fileslisting 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 oftests/fails the out-of-scope test.cargo xtask lycheeand thelycheehook: 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 scansdocs/**/*.md, which is why the services hint is written asstop|restart|removerather than with a placeholder.cargo test -p xtask: 786 passed.cargo clippy -p xtask --all-targets -- -D warningsis clean,cargo check -p rocmpasses, andcheck-module-sizereports 419 files, none over 1500 production lines (architecture_doc.rsis under 1000).sigpipe.rs,stdio_client.rs,fake_engine.rs,cli_args.rs,process/bounded.rsandartifact_prefetch.rs; 403 in all).amd-smi,amdgpu) and ordinary words.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.
d027ff8e3is a commit on main (git merge-base --is-ancestor d027ff8e3 origin/mainsucceeds), 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)andpub(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/rocmabout 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:
--approve-replacing-active-defaultand never--yes, because--yeswould approve asudo(ui/install_manager.rs).ui/config_manager.rs).--dry-runwrites nothing (SetupRecovery::PreviewOnlyinruntime_adopt.rs).owns_install_rootgates folder deletion (runtime_registry.rs).ROCM_CLI_ROCDXG_ALLOW_UNVERIFIEDis set.tool_exec::execute_approvedre-validates before it runs a tool call.tool_policy.rsrefuses control characters and system-path prefixes.serve_recipe'sRESERVED_ENGINE_ENV_KEYSblocks overriding the engine's own environment.gguf_sourcenever follows a redirect from https to http.active_default_runtime_relationfails closed.run_internal_mcp_callrefuses mutating commands.apt-get -sROCm-removal refusal.run_with_timeoutbounds the output it quotes.LlmConfig'sDebugoutput 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
model_fit.rsis its own module (not part of the diagnose handler) soexamine_report_text.rsandmodel_catalog_text.rsread the platform gate without depending on a command module.sdk_install_requestlives ininstall_cmd.rsrather thanchat.rsbecauseinstall_cmd.rsmust not depend onchat.rs.FamilyResolutionlives intherock/source.rs, nottherock/family.rs, to keep the source-to-family dependency one-way.extract_tarballsits intherock/process.rs, nottherock/io.rs, because it spawnstarandio.rsstays a leaf.therock_version_proptests.rsis declared fromtherock.rs(nottherock/version.rs) because it also reaches update, wheel and registry code.slugify,venv_python_path,platform_tarball_token,runtime_key,wheel_runtime_key) stay intherock.rspermanently because the children read them back from the parent.AggregateDeviceTarget::prefer_recordedintherock/resolve/wheel.rsis 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.no_usable_gpu_refusalwords the no-usable-GPU refusal once for bothserve's pre-flight and the spawn.abandon_failed_managed_launch(whylaunch_managed_engine_child_lockedis split out).serve_port.rs.serve_recipe.rscalls back intoserve_cmd.rs.service_records.rsandservices_cmd.rsare not called back by the modules they read.managed_engine_startup_failure_detailis re-exported for test builds only, because services_text.rs's log-tail tests call it throughcrate::service_launch.vram/host_gputest fixture builders are deliberately duplicated in the gpu_policy.rs and serve_cmd.rs tests rather than shared.runtime_install_finalize.rscalls intoruntimes_cmd.rs(activate_runtimeand others), whileruntimes_cmd.rsreaches it only from its tests.crates/rocm-core
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.amd_smi_probe_jsonlogs a declined launch atinfobecause the default filter iswarn,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.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.cargo xtask report-rollup). A grep finds it, but nothing in report_rollup.rs points there.dashboard crates
rocm dashalways setsRunnerOptions::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.rocm services list, which also checks process liveness; the implementation (LiveManagedRegistryProbe) lives inapps/rocm'sdash.rs.RocmToolExecutorimplementation isBinToolExecutorinapps/rocm'sdash_seam.rs, and the executor isNoneunder demo, replay and mock.apps/rocm'slauncher_routeturns aLauncherChoiceinto a focused host, chat or the full dashboard; the launcher's quit goes through the same quit-confirm gate with aStaticManagedRegistrySnapshot.ModelRecipeSummaryis built byapps/rocm'sdash.rsso the crate needs norocm-core(the general rule is kept; the specific plumbing point is not).KeyAction::Open*, a slash command, the quit-confirmskey, the startup focus). Cross-file, dropped as a caller list.ui/files (instance_detailreadsinstances.rs, which does not import it back;menu.rsdepends onapp/types.rs, not the reverse;warnings_modalimportspopup_height_forfromhelp_modal, not the reverse;theme_pickerdoes not depend onmodal.rs). Theinstance_detaildirection is stated in its own header; the others need a grep of the other file.runner.rs, but not fromobservation.rs.apps/rocmd and the engines
/v1/messagesroute, 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.DaemonHost::detectreturns the test binary for both commands and looks for no sibling, so no unit test can run arocmorrocmdbuilt 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.rocmdbinary fails before it writes the record. In supervise.rs, not discoverable from the caller in server_recover.rs.xtask and tests/e2e-cucumber
.featurefile(s) of each step file, found by matching step phrases againstfeatures/. Many step files also serve one or two scenarios of other features (for exampletherock_steps.rsholds 32 step matches inruntime_setup.feature,serving_steps.rsserves 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.rsrefuses a GPU with no ROCm build (117). The ComfyUI install pins the runtime's torch stack (136). The launch lock is held acrossresolve_managed_port_in_transaction, whose doc says callers must hold it (98).system_packages.rsis a leaf (110).crates/rocm-core.
download.rsusesureqand imports onlydisk_space.rs(196).net.rsimports no other module, andendpoint_readiness.rsbuilds onnet.rs,service_record.rsandmodel_catalog.rs(198, 210).jsonl_store.rsis generic and imports nothing fromautomation.rs(206).package_plan.rsonly plans and never runs the plan, which its header says (247). The shared PATH lookup is described indocs/host-probing.md(205).apps/rocmd and the engines. Leaf claims for
daemon_host.rs,engine_ipc.rs(uses onlydaemon_host.rs),host_snapshot.rs(uses only persistence) andmcp_argv.rs(158-163), the production imports ofsupervise.rs(168), three Lemonade leaves (437, 438, 440),startup_diagnostics.rs(imports onlystate.rs, 429) anddocker.rs(nobollard, 453). TheDaemonHosttest stand-ins (158). Every supervisor write after the first goes throughupdate_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, incgroup.rs). The launcher has its own blocking key loop (345). Dock dimensions (341). Ring sizes and replay order on subscribe (388, inserver.rs). Demo determinism and file mode (389), and no fsync or rotation in the session writer (390). Whytool_approvalandscrollare 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-outROCM_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 thedash_seam.rsheader (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: thedriver_install.rsrow namestool_policy.rsandfreeform_planner.rsfor the re-export; theservice_hints.rsBoundaries bullet lists its real callers and says the parentservice_launch.rsis not one; thedash_seam.rsrow says why the seam exists and which dash crates may depend onrocm-core; thewhichclaim is scoped to the two host-probing stacks and names the twoPATHwalkers elsewhere (find_mpirun_path, theruntime.rsexecutable search); thepackage_plan.rsrow says it never executes a plan and runs onlysudo -n true; thehardware_root.rs/os-release claim says the resolver is private butread_os_releaseispuband used by two other readers, with the test insystem_packages.rsguardingapps/rocmonly; theamd_smi.rsrow lists what it imports and that the spawn goes throughprocess.rs; theapps/rocmdBoundaries sayupdate_supervised_recordispub(crate)and called byserver_recover.rsand that thewatchers.rsre-exports are used in production (stop_requestedbysupervise.rs,find_recoverable_servicebywatchers.rs;supervise.rstests use the latter as well); the vLLM Boundaries saydiscover_builds.rsis a leaf but its readers do import one another; the vLLMlib.rsrow saysverified_torchaudio_releaseis a delegatingpub fn, not apub use. What was found, as listed before the correction:apps/rocm
driver_install.rsre-exportshost_install_driver_only_reports"for chat.rs and freeform_planner.rs". Today the callers aretool_policy.rs(crate::driver_install::host_install_driver_only_reports) andfreeform_planner.rs;chat.rsdoes not call it. Caller list dropped anyway.service_hints.rscaller list namesservice_launch.rsand omitsserve_port.rsandservice_control.rs, which call it (grepservice_hints::); the callers are theservice_launch/children, not the parent file. The kept claim (one builder for every hint) is true; only the list was stale.dash_seam.rs(not the old doc): "The dash crates stay free ofrocm-core" is not true of every dash crate;crates/rocm-dash-daemon/Cargo.tomldepends onrocm-core. The Boundaries bullet (from old line 108) speaks ofrocm-dash-tuionly. Fixing the header is out of scope.crates/rocm-core
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").which(the onePATHlookup ...)". Across the crate this is false: openmpi.rs'sfind_mpirun_pathand runtime.rs's executable search (aroundstd::env::split_paths(&path_var)) walkPATHthemselves. It is true only between the two host-probing stacks, which is how the bullet scopes it.sudo_noninteractive_availablerunssudo -n true(behindcan_autoinstall). It never executes a plan, which is what the bullet says.hardware_root::read_os_releaseispuband accepts any resolver closure, so a caller outside the module can still read os-release with its own resolver. Dropped.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
update_supervised_record": it ispub(crate)(apps/rocmd/src/supervise.rs,update_supervised_record), andwatchers/server_recover.rscalls it directly (crate::supervise::update_supervised_record, stampinglast_restart_unix_msafter a failed restart). Old 171's list of what server_recover.rs uses also omits this.find_recoverable_serviceandstop_requestedare re-exported from here because supervise.rs's and service.rs's tests reach them by thecrate::watchers::path": supervise.rs's production code importscrate::watchers::stop_requested(top-levelusein supervise.rs, which old 168 itself says), so the re-export is not test-only. Dropped.crate::runtimeandcrate::wheel_buildsin production (uselines at the top of engines/vllm/src/install.rs). The single-list claim was kept; this half was dropped.verified_torchaudio_release, which the crate re-exports from lib.rs": not apub use; engines/vllm/src/lib.rs defines apub fn verified_torchaudio_releasethat delegates to thepub(crate)one in wheel_builds.rs (used by apps/rocm/src/therock/resolve/wheel.rs). The row says "for therocmbinary", which is true; minor wording only.Source headers that disagree with their code (reported, not changed)
xtask/src/main.rs//!: lists only signing, the MANIFEST.md generator, third-party notices, commit-trust verification, PowerShell linting and markdown-link checking. TheCommandenum also hasaffected,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-readinessandverify-pinned-keys.xtask/src/main.rs, theE2evariant's doc comment (--helptext, not a//!header): "Build the releaserocmbinary".e2e.rsbuilds-p rocm -p rocmd, as its own header says.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.shand more; the header describes only the first contract.tests/e2e-cucumber/src/capability.rs//!: "The suite is black-box (it never imports rocm-cli crates)". Thee2etarget importsrocm_core(AppPaths,ProcessIdentity,fake_executable::write_fake_executableintests/e2e.rsandtests/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.tests/e2e-cucumber/src/powershell_text_rule.rs//!: "this crate does not depend on rocm-core". True of the library target only;Cargo.tomllistsrocm-coreas a dev-dependency.tests/e2e-cucumber/src/panic_capture.rs//!: "Shared by black-box drivers (currentlytests/e2e/tui_driver.rs)".src/harness_diagnostics.rsalso callscrate::panic_capture::panic_message.tests/e2e-cucumber/src/fixture_binary.rs//!namesfake-tailscale,fake-uv,fake-pythonas the stand-ins;fake-dockeris located the same way (install_fixture_binary("fake-docker", ..)inmodel_catalog_steps.rs). Minor: the list reads as examples.src/files.src/lib.rs,src/mock_server.rs,src/model_id.rs,src/runtime_root.rs,tests/e2e.rs, andtests/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 (pubitems, step attributes, matching.featurefiles).Moved to Boundaries
Every claim kept as a Boundaries bullet, by its line in the old file.
apps/rocm (25)
modfor every module; qualified path vs theuse crate::x::{...}re-import blockengine_inventorysingle table;status_for_readiness,device_policy_name,ROLLBACK_RECOVERY_HINTstay at root for cross-module callersvalidate_serve_command_safetyholds the serve rules; planner keeps no copyselect_single_ready_runtimeone rule;write_runtime_manifestone routineActiveRuntimeMarkerserde shapes are on-disk contractsinstall_root_has_payloadone rule; os-release only viareal_os_release, scan testcargo xtask verify-pinned-keysROCDXG_PINNED_DIGESTStrust anchorrender_update_jsonis what the dashboard's update check parsescrates/rocm-core (19)
TORCH_ALIGNMENT_DISABLED_ENV/torch_alignment_disabledis the one read of the opt-outVLLM_GPU_MEMORY_UTILIZATION_HINTis one wording (CLI, vLLM engine, fix-16 diagnosis)command_failure_detaildetail rule andsanitize_componentslugger are sharedrocm_core::paths; package_plan through openmpi.rs; probe_exec not re-exportedPATHlookup and the kernel release, as main's change to this note states them)host_path(E2E re-roots it); os_release.rs the one parseramd_smi_jsonthe one synchronous amd-smi launch path (kfd pre-flight); enforced by amd_smi_launch_contract.rsruntime_python_env_root_for_executableandinstall_root_has_payloadare the one definitionsprocess/bounded.rsabandons 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)
chat_templatelives in the leaf crate soproviders/wire.rsandagent/clients.rscannot driftInstanceStatuspredicates/labels andJobStatus::glyph/label/legend_glyphsare the one definitionvram.rsreusesefficiency.rs's id matchingPersistedEntrywritten by daemon persist, generated by demo, read by replay#[serde(default)]so older recordings and partial CSVs deserializePROTOCOL_VERSIONbump rule; everyEventvariant struct-shaped, held by a testSpawnJobinterpreted;Persist/Broadcast*unconsumed; daemon discards effectsRocmCliConfig; only the TUI chat save touches it; socket path copied from rocm-core on purposecheck-crate-edges)Unsupported; runner uses async methodsparse_sample/default_portnot on the live path; runner builds collectors directly/dev/kfd); reachability verdict fromapps/rocmviaRunnerOptionsvllm_promleavesgen_tpsempty; runner turns the counter into a ratebench_loadtakes thevllmlabel fromEngineKind;EngineSplitNoticereported for the CLI to printenable_lemonade, default false, off inrocm dash's daemontransport.rsfiles are copies; change bothapps/rocm'sdash.rsdrives the daemontool_exec/registry_probeorResolvedArgsllm.rs's default port andexec.rs's Python layout are copies of rocm-core'sOptionstate onAppState; openers callclose_overlays;draw_active_managerApprovalRequest; job only on Approve; CLI mutates; read-only direct; bench-run exceptionexecute_approvedblocks; overlays do not usetool_execStatefor all jobs, outlives an overlay; unbounded channel on purpose, bounded in the reducerui/componentsdash_text_edit_contract.rsenforces the text-edit helper; Chat input exceptedchat_runtime,terminal,focus,update_checkare leaves ofevent_loop.rsapp/mod.rsre-exports keepcrate::app::*pathsAppStatewhile drawing, except Chat writes scroll bounds backMENU_ITEMSis the one source for menu rows, labels, wrap bound and reserved heightoutlined_chip_spansis the one tab geometry for painter and click resolutionllm.rsstrips credentials from a loopback base URLserve_wizard'sis_loopback_hostis a different, stricter function; default invocationrocm serve MODELkeeps the CLI the authority (incl. GPU-required policy)apps/rocmd and the engines (22)
xtask and tests/e2e-cucumber (8)
*_contract.rsfiles define no command"affected.rsis the one crate selection"paths.rsis the single definition"crates/e2e-report"Decisions for the reviewer
check-architecture-docnow coversxtask/src,tests/e2e-cucumber/srcandtests/e2e-cucumber/tests, so the 109 hand-kept rows hold by construction. The helper exemption (test_support.rs,*_props.rsand 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.mdanddocs/architecture.mdsay 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.git log --follow. Say if it should go entirely.Follow-ups, not done here
//!headers listed under "Source headers that disagree with their code" are reported, not changed, including thedash_seam.rsheader that says the dash crates stay free ofrocm-core. Fixing a header is a code-comment change in the file's own crate and is not part of this ticket.rocm-corethat citedocs/host-probing.mdby 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
config_proptests.rs,persisted_paths_props.rs,therock/python_config_props.rs,sigpipe.rs,stdio_client.rs,fake_engine.rsandcli_args.rs, came in with main and have rows).cargo xtask check-architecture-docpasses, and every row's description was written from the file's own header and checked against the code.--helptext ofcargo xtask check-architecture-docnow names the three added trees; norocmcommand is affected.AGENTS.mdchanges only the list of trees the check covers, one clause in the architecture-check bullet, and the pull-request template likewise.