Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
9c0e78b
ROCMAI-768: restructure the architecture doc into per-crate tables
jussielo-amd Nov 10, 2026
549fa34
ROCMAI-768: use the ticket's three classes in the architecture doc
jussielo-amd Nov 10, 2026
5b4e34d
Merge origin/main into docs/architecture-per-crate-tables
jussielo-amd Nov 10, 2026
2b13197
docs(architecture): say the driver probe row covers built-in modules
jussielo-amd Nov 10, 2026
7d278e2
Merge origin/main into docs/architecture-per-crate-tables
jussielo-amd Nov 10, 2026
b4d22d6
Merge origin/main into docs/architecture-per-crate-tables
jussielo-amd Nov 10, 2026
d4b0d41
Merge origin/main into docs/architecture-per-crate-tables
jussielo-amd Nov 10, 2026
4013543
docs(architecture): correct the claims the old text got wrong
jussielo-amd Nov 10, 2026
df329a2
xtask: make check-architecture-doc cover xtask and the e2e harness
jussielo-amd Nov 10, 2026
4faa569
docs(rocm): drop pointers to a phase vocabulary the architecture doc …
jussielo-amd Nov 10, 2026
a889bdc
docs(host-probing): say what retiring the note takes
jussielo-amd Nov 10, 2026
fc57c55
docs(architecture): say a complete registry read retires what it lacks
jussielo-amd Nov 10, 2026
73e5424
Merge origin/main into docs/architecture-per-crate-tables
jussielo-amd Nov 10, 2026
8e61185
docs: link the source files this branch cites by name
jussielo-amd Nov 10, 2026
28eab84
docs(rocm): drop the last ticket key from the gpu_policy module comment
jussielo-amd Nov 11, 2026
3e3e629
docs(architecture): state the file-link rule as the document practise…
jussielo-amd Nov 11, 2026
2b79aab
docs(architecture): state the reader-thread behaviour as a plain fact
jussielo-amd Nov 11, 2026
057b42e
Merge origin/main into docs/architecture-per-crate-tables
jussielo-amd Nov 11, 2026
f48a2e5
docs(rocm): drop the remaining phase pointers from module comments
jussielo-amd Nov 11, 2026
029e3fb
Merge origin/main into docs/architecture-per-crate-tables
jussielo-amd Nov 11, 2026
896bd7b
Merge origin/main into docs/architecture-per-crate-tables
jussielo-amd Nov 11, 2026
8b61488
docs(host-probing): list every rocm-core comment that cites the note
jussielo-amd Nov 11, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,5 @@ SPDX-License-Identifier: MIT

- [ ] If this PR fixes a bug, searched `tests/e2e-cucumber/expectations.toml` for the fixed ticket ID and removed/narrowed any now-stale xfail rows.
- [ ] If this PR adds a new subcommand or subsystem, its domain implementation lives in its own file per `docs/architecture.md` (the clap declaration in `cli.rs` and the dispatch wiring in `main.rs`/`lib.rs` are expected, not a violation).
- [ ] If this PR adds, renames or removes a production source file, `docs/architecture.md` has the matching entry (`cargo xtask check-architecture-doc` fails otherwise), and the prose of any entry whose file changed role still describes it, which the check cannot verify.
- [ ] If this PR adds, renames or removes a production source file (or a `.rs` file under `xtask/src` or `tests/e2e-cucumber`), `docs/architecture.md` has the matching entry (`cargo xtask check-architecture-doc` fails otherwise), and the prose of any entry whose file changed role still describes it, which the check cannot verify.
- [ ] Every new or changed user-facing message was read against the code path that runs after it, and its test asserts the resulting state — not only the wording — per AGENTS.md §3. Covers claims of an outcome, remediation advice naming a command, and promises that something will *not* happen.
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -278,7 +278,7 @@ Guardrails:
- `crates/rocm-engine-protocol` is a contract surface; verify all impacted engines after protocol changes
- first-party crate-layering invariants (e.g. `rocmd` must never depend on `rocm`) are enforced by `cargo xtask check-crate-edges` (`xtask/src/crate_edges.rs`); a new first-party dependency edge failing that check means the edge needs review, not a bypass
- source file size is checked by `cargo xtask check-module-size` ([`module_size.rs`](xtask/src/module_size.rs)): no source file may exceed 1,500 production lines (test-gated items excluded), with one limit for every file and no exemption mechanism. A PR that would push a file past it splits the file in the same change; do not raise the limit or opt a file out. The check blocks merges: the `clippy` CI job, a required check that also runs on merge-queue runs, fails when any source file is over the limit, so a file over it is split before anything else merges. The `cargo-module-size` pre-commit hook is its local mirror: it runs the same check and refuses the commit, for anyone who installed the hooks; see `docs/architecture.md`
- every production source file (a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src`) has an entry in `docs/architecture.md`, enforced by `cargo xtask check-architecture-doc` ([architecture_doc.rs](xtask/src/architecture_doc.rs)) in the `clippy` CI job and in the `architecture-doc` prek hook at commit and push. Add the entry in the same change as the file. The check has no exemption list: document the file. The check reads no prose, so keeping an entry's description true is still on you
- every production source file (a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src`), and every `.rs` file under `xtask/src`, `tests/e2e-cucumber/src` and `tests/e2e-cucumber/tests`, has an entry in `docs/architecture.md`, enforced by `cargo xtask check-architecture-doc` ([architecture_doc.rs](xtask/src/architecture_doc.rs)) in the `clippy` CI job and in the `architecture-doc` prek hook at commit and push. Add the entry in the same change as the file. The check has no exemption list: document the file. The check reads no prose, so keeping an entry's description true is still on you
- preserve strict GPU-required behavior; do not introduce silent CPU fallback
- respect platform gates (for example, native Windows handling for vLLM)
- pin third-party GitHub Actions to a full commit SHA with a trailing `# vX.Y.Z` comment, never a moving tag (`@v2`, `@main`); a retagged or compromised action otherwise enters CI silently. Bump the SHA and comment together when upgrading
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ New subcommands and subsystems default to their own file from day one. Don't let

Crate-layering invariants, such as `rocmd` never depending on `rocm`, are enforced by `cargo xtask check-crate-edges` (`xtask/src/crate_edges.rs`). File size is checked by `cargo xtask check-module-size` (`xtask/src/module_size.rs`): no source file may exceed 1,500 production lines, test code excluded, and a change that would cross the limit splits the file in the same change instead. The `clippy` CI job fails on a file over the limit, and the `cargo-module-size` pre-commit hook runs the same check locally and refuses the commit, so it is the local mirror of the CI step (it only runs if you installed the hooks). It measures the working tree, so it also fails on a Rust file under a crate's `src/` that no `mod` declares, even an untracked scratch file, and it refuses every intermediate commit of a split spread over several commits, where `SKIP=cargo-module-size git commit ...` commits those steps; `docs/architecture.md` has the details.

Every production source file, meaning a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src`, must have an entry in `docs/architecture.md`: a relative markdown link to it, which has to render as a link (a path inside an HTML comment, a code block or a code span does not count, and neither does a malformed link such as one missing its `)`, or an image). Use an inline `[text](path)` link with its text on one line; reference-style links, a `?query` suffix and root-relative paths are not recognised. `build.rs` files and the `tests/` and `examples/` trees are out of scope. `cargo xtask check-architecture-doc` (`xtask/src/architecture_doc.rs`) enforces that in the `clippy` CI job and in the `architecture-doc` prek hook, which runs on every commit and every push, over the whole tree. A file with no entry fails it, and there is no exemption list. This is the opposite direction to the `lychee` check below, which only confirms that links already in the doc still resolve. Test-only helpers (`test_support.rs`, `test_env.rs`, `*_proptests.rs`, `*_props.rs`, `*_properties.rs`) need no entry. The check does not read the prose of an entry, so keeping a description true when a file's role changes is still up to you.
Every production source file, meaning a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src`, must have an entry in `docs/architecture.md`: a relative markdown link to it, which has to render as a link (a path inside an HTML comment, a code block or a code span does not count, and neither does a malformed link such as one missing its `)`, or an image). Use an inline `[text](path)` link with its text on one line; reference-style links, a `?query` suffix and root-relative paths are not recognised. `build.rs` files and the `tests/` and `examples/` trees of those crates are out of scope. The same holds for every `.rs` file under `xtask/src`, `tests/e2e-cucumber/src` and `tests/e2e-cucumber/tests`, which also need an entry. `cargo xtask check-architecture-doc` (`xtask/src/architecture_doc.rs`) enforces that in the `clippy` CI job and in the `architecture-doc` prek hook, which runs on every commit and every push, over the whole tree. A file with no entry fails it, and there is no exemption list. This is the opposite direction to the `lychee` check below, which only confirms that links already in the doc still resolve. Test-only helpers (`test_support.rs`, `test_env.rs`, `*_proptests.rs`, `*_props.rs`, `*_properties.rs`) of those product crates need no entry; the `xtask` and `tests/e2e-cucumber` trees have no such exemption. The check does not read the prose of an entry, so keeping a description true when a file's role changes is still up to you.

Every local (relative-path) Markdown link and `#anchor` fragment in the repository (outside `docs/rocm-docs/`, which `docs-build` covers instead, and hidden directories such as `.github/`, which neither check walks) is checked by the `docs-links` CI job and by the `lychee` prek hook above, both configured by `lychee.toml` (which lists the current exclusions). Both run offline only, so they don't catch broken external `https://` links.

Expand Down
7 changes: 3 additions & 4 deletions apps/rocm/src/automations.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,9 @@
//! Mechanically relocated from `main.rs` with no behavior change — the
//! `dispatch()` call site stays `automations(command)`, re-imported with
//! `render_daemon_text` via
//! `use crate::automations::{automations, render_daemon_text};`. As of
//! Phase 6f (ROCMAI-210, see `docs/architecture.md`) this module also owns the
//! rendering/classification
//! helpers behind `render_automations_text` (the `rocm automations` status
//! `use crate::automations::{automations, render_daemon_text};`. This
//! module also owns the rendering/classification helpers behind
//! `render_automations_text` (the `rocm automations` status
//! report: watcher status/policy lines, recent automation activity, and
//! plain-language proposal/audit summaries) and `render_daemon_text` (the
//! `rocm daemon --status` summary) — both folded in from `main.rs` alongside
Expand Down
16 changes: 7 additions & 9 deletions apps/rocm/src/engine_runtime_select.rs
Original file line number Diff line number Diff line change
Expand Up @@ -21,15 +21,13 @@
//! `service_model_gpu_ready`, `service_model_reports_rocm_backend`,
//! `service_model_names_match`).
//!
//! Mechanically relocated from `main.rs` with no behavior change — Phase 6f
//! (ROCMAI-215) of the `main.rs` modularization (see
//! `docs/architecture.md`). This is the last sub-phase of the `main.rs`
//! Phase 6f split that lands before the file's single shared
//! `#[cfg(test)] mod tests` block starts: the function immediately after this
//! cluster in the original file, `treat_as_natural_language`, is
//! dispatch-adjacent natural-language-invocation routing left over from an
//! earlier phase (ROCMAI-87) and stays in `main.rs` on purpose — it is not
//! part of this module and is not touched by this change.
//! Mechanically relocated from `main.rs` with no behavior change (the
//! `relocation` class in `docs/architecture.md`). The cluster ended where the
//! file's single shared `#[cfg(test)] mod tests` block starts: the function
//! immediately after it in the original file, `treat_as_natural_language`, is
//! dispatch-adjacent natural-language-invocation routing that stays in
//! `main.rs` on purpose — it is not part of this module and is not touched by
//! this change.
//!
//! One item physically interleaved in this span in `main.rs` stayed there
//! instead of moving: `const fn status_for_readiness` sits between
Expand Down
6 changes: 3 additions & 3 deletions apps/rocm/src/freeform_execution.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
//
// SPDX-License-Identifier: MIT

//! The freeform natural-language planner's plan-*execution*/consent cluster
//! (ROCMAI-726, a Phase 6e, ROCMAI-87 follow-up).
//! The freeform natural-language planner's plan-*execution*/consent cluster,
//! the half that `freeform_planner.rs` left behind.
//!
//! Mechanically relocated from `main.rs` with no behavior change — `main.rs`'s
//! `execute_freeform_next_action()` call sites stay byte-identical
Expand All @@ -18,7 +18,7 @@
//! to execute.
//!
//! This is the other half of the freeform-planner cluster that
//! `freeform_planner.rs` (Phase 6e, ROCMAI-87) deliberately left behind: that
//! `freeform_planner.rs` deliberately left behind: that
//! module builds a plan; this one reads/acts on its `FreeformPlanAction`
//! internals, grants it the consent the outer `--yes` already carries, and
//! computes planner-specific output text — a dispatch-adjacent concern
Expand Down
12 changes: 6 additions & 6 deletions apps/rocm/src/gpu_policy.rs
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,9 @@
//! --json`, with an amdgpu DRM sysfs fallback), and building the serve-plan
//! low-VRAM warning from it.
//!
//! Mechanically relocated from `main.rs` with no behavior change — Phase 6f
//! (ROCMAI-214) of the `main.rs` modularization (see
//! `docs/architecture.md`). `dispatch()` calls directly into this module at
//! one point — the `Command::EngineServeHttp` arm's
//! Mechanically relocated from `main.rs` with no behavior change (the
//! `relocation` class in `docs/architecture.md`). `dispatch()` calls directly
//! into this module at one point — the `Command::EngineServeHttp` arm's
//! `parse_gpu_indices_arg(gpu.as_deref())?` — re-imported via `use
//! crate::gpu_policy::parse_gpu_indices_arg;`; `dispatch()`'s own body is
//! otherwise unaffected.
Expand All @@ -32,8 +31,9 @@
//!
//! One item physically interleaved in this span in `main.rs` stayed there
//! instead of moving: `const fn device_policy_name` sits immediately after
//! `detect_gpu_count` and before the next cluster's (ROCMAI-215)
//! `EngineSelection`/`resolve_engine_selection`, but it already had callers
//! `detect_gpu_count` and before the engine-selection cluster's
//! `EngineSelection`/`resolve_engine_selection` (now in
//! `engine_runtime_select.rs`), but it already had callers
//! outside this cluster — `engine_ipc.rs` and `service_launch.rs` reach it
//! unqualified via `use crate::{...}`, same as `serve_cmd.rs` does — plus its
//! own test, so it is not part of this cluster's relocation.
Expand Down
8 changes: 4 additions & 4 deletions apps/rocm/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ mod update_cmd;
// for other root-level commands outside `dispatch()` that call it directly.
// `select_runtime_manifest` is no longer needed here:
// `single_ready_runtime_key`/`resolve_runtime_selector_to_exact_key` moved out
// to `engine_runtime_select.rs` in ROCMAI-215 (Phase 6f), reaching it via that
// to `engine_runtime_select.rs`, reaching it via that
// module's own grouped `use crate::runtimes_cmd::{...}` import instead.
// `update_cmd.rs`'s `apply_runtime_update`/`append_update_activate_summary`
// call into `runtimes_cmd` directly too, via their own imports rather than
Expand All @@ -105,9 +105,9 @@ mod update_cmd;
// `managed_service_process_command`, and
// `ensure_public_service_has_endpoint_key` are no longer needed here either:
// their only caller outside `dispatch()`, `restart_internal_managed_service`
// (and the endpoint-key check inside it), moved out to `services_text.rs` in
// ROCMAI-209 (Phase 6f) and has since moved on to `service_control.rs`, which
// reaches them via its own imports instead.
// (and the endpoint-key check inside it), moved out to `services_text.rs` and
// has since moved on to `service_control.rs`, which reaches them via its own
// imports instead.
// `record_cli_audit_event`, `cli_lifecycle_log_path` and `sanitize_log_value`
// (from `cli_audit.rs`) are re-imported so other modules keep reaching them as
// `crate::<name>`.
Expand Down
8 changes: 4 additions & 4 deletions apps/rocm/src/managed_service_status.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@
//! Managed-service liveness classification and the dashboard-sidebar
//! status/counts helpers derived from it.
//!
//! Mechanically relocated from `main.rs` with no behavior change — Phase 6f
//! (ROCMAI-211) of the `main.rs` modularization (see
//! `docs/architecture.md`). `dispatch()`'s call sites are unaffected: none of
//! this module's functions are called directly from `dispatch()`.
//! Mechanically relocated from `main.rs` with no behavior change (the
//! `relocation` class in `docs/architecture.md`). `dispatch()`'s call sites are
//! unaffected: none of this module's functions are called directly from
//! `dispatch()`.
//!
//! This module owns: reading and liveness-refreshing the on-disk managed-service
//! registry (`load_managed_services`, `refresh_managed_service_runtime_liveness`,
Expand Down
4 changes: 2 additions & 2 deletions apps/rocm/src/runtime_services.rs
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@
//! [`ServiceRuntimeState`], [`RuntimeServiceEntry`], [`FailedServiceRestart`],
//! [`RuntimeServiceReconciliation`] and [`ServiceRuntimePin`]. `RuntimesCommand`
//! lives in `cli.rs` (part of the `Command`/`Cli` clap definition); `fn
//! runtimes()` itself moved to `runtimes_cmd.rs` in Phase 6c (ROCMAI-89), which
//! calls back into this file via `crate::runtime_services`.
//! runtimes()` itself lives in `runtimes_cmd.rs`, which calls back into this
//! file via `crate::runtime_services`.

use std::fmt::Write as _;

Expand Down
6 changes: 3 additions & 3 deletions apps/rocm/src/serve_cmd.rs
Original file line number Diff line number Diff line change
Expand Up @@ -28,16 +28,16 @@
//! `parse_device_policy`, `parse_gpu_selection`,
//! `select_gpu_indices_under_launch_lock`, `serve_gpu_low_memory_warning`,
//! and `validate_pinned_gpu_index` moved out of `main.rs` into
//! `gpu_policy.rs` in ROCMAI-214 (Phase 6f); `resolve_engine_selection` and
//! `gpu_policy.rs`; `resolve_engine_selection` and
//! `validate_engine_selection_runtime` moved out of `main.rs` into
//! `engine_runtime_select.rs` in ROCMAI-215 (Phase 6f); this file's `use`
//! `engine_runtime_select.rs`; this file's `use`
//! list below points to both now instead of at the crate root. The
//! managed-service-spawning tail this file calls into — `start_managed_service`,
//! `run_attached_service`, `resolve_endpoint_auth`,
//! `ensure_public_bind_engine_supported`,
//! `drop_orphaned_endpoint_key_on_already_running`, `print_managed_launch_plain`,
//! `validate_bind_host`, `ensure_background_helper_running_quiet` — was relocated
//! to `service_launch.rs` in ROCMAI-91 (Phase 6b), along with its test module;
//! to `service_launch.rs`, along with its test module;
//! this file's `use` list below points there now instead of at the crate root.

use anyhow::{Context as _, Result, bail};
Expand Down
4 changes: 2 additions & 2 deletions apps/rocm/src/service_launch.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@
//! Relocated from `main.rs`, since extended with the port-allocation and
//! launch-lock transaction. This module
//! is the managed-service-spawning tail that was deliberately deferred out of
//! the Phase 6a (ROCMAI-82) split: `start_managed_service`,
//! the earlier relocation of the service-record code: `start_managed_service`,
//! `run_attached_service`, `spawn_managed_engine_child`, `stream_attached_logs`,
//! and the rest of what was then a single file. It was entangled with crate-root launch helpers
//! — `record_cli_audit_event`, `existing_live_managed_service_in`, and the stop
//! action of the service-record-management cluster (this module reaches only
//! stop, via `AttachOutcome::Stop`; restart/remove/prune are not called here)
//! — and this later pass (ROCMAI-91, Phase 6b) separates the spawning tail out
//! — and this later pass separates the spawning tail out
//! from them; see below for where they live now.
//!
//! `dispatch()`'s call sites are unaffected: `Command::Services { command } =>
Expand Down
4 changes: 2 additions & 2 deletions apps/rocm/src/uninstall_plan.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@
//! The uninstall plan: what would be removed, how that plan is rendered for
//! review, and the filesystem-removal primitive used to carry it out.
//!
//! Mechanically relocated from `main.rs` with no behavior change — Phase 6f
//! (ROCMAI-212) of the `main.rs` modularization (see `docs/architecture.md`).
//! Mechanically relocated from `main.rs` with no behavior change (the
//! `relocation` class in `docs/architecture.md`).
//! `dispatch()`'s call sites are unaffected: none of this module's functions
//! are called directly from `dispatch()`.
//!
Expand Down
4 changes: 2 additions & 2 deletions apps/rocm/src/update_cmd.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@
//! update-source/installed-runtime pickers behind it
//! (`select_runtime_update_source`, `select_installed_update_runtime`).
//!
//! Mechanically relocated from `main.rs` with no behavior change — Phase 6f
//! (ROCMAI-210) of the `main.rs` modularization (see `docs/architecture.md`).
//! Mechanically relocated from `main.rs` with no behavior change (the
//! `relocation` class in `docs/architecture.md`).
//! The `update` command arm of `dispatch()` calls `update`, the handler whose
//! body was that arm's own and which was relocated here verbatim, re-imported
//! via `use crate::update_cmd::update;`; `update` in turn calls
Expand Down
Loading
Loading