[Pedro Henrique Penna (ppenna)]

Closes #897. Part of #896. Supersedes #909.

#909 and the follow-up: #909 fixed #897 independently in another session and was closed as a duplicate of this PR. This PR merged at 71a68acf, before its fold-in of #909's improvements was pushed. The fold-in follows in #919, which lists what it takes from #909:

• nvx-rs: make the host module's dependency graph acyclic #909's guard model: the whole crate, the imports of every module outside the children, the extern prelude, macro inputs and templates, and list elements;
• its report of the shortest cycle through each dependency, with the layers;
• its tests, beside a check that each of its 22 review findings, reproduced against the new guard, passes;
• its wording for the moved artifact checks, spawn, the layering of host, and the README's testing paragraph.

The red-on-dev output below is that of the guard that merged here; #919 shows the new report.

The direct children of nvx::host now depend on one another without cycles, and a std-only integration test, nvx-rs/tests/host_modules.rs, keeps them so. Three items move down, each re-exported at its old public path, so neither behavior nor the public API changes.

Commits

1. nvx-rs: move the handles that a VMM inherits into platform. Inherited, with its Borrowed alias and impls, moves from supervisor/child.rs into a new crate-visible host::platform::inherit, which the Linux, Windows, and other-host platform modules import. supervisor re-exports it, so nvx::host::supervisor::Inherited stays its only public path. This removes platform → supervisor.
2. nvx-rs: move the spawn of a VMM beneath the store. supervisor/child.rs moves, with git mv, to the private host::spawn. supervisor re-exports Launched, VmmCommand, and spawn, and store imports super::spawn::Launched. The doc link to supervisor::launch now uses a crate:: path, since super::launch would silently name the host::launch module from the new file (nvx-rs: break the host module into finer-grained modules #896, invariant 6). This removes store → supervisor.
3. nvx-rs: check for artifacts in the artifacts module. require_artifact and require_existing move from sandbox into artifacts as pub(crate). require_existing still spells a missing path with host::paths::normalized, so artifacts now imports the std-only paths module, which sits beneath both, and the sandbox tests import paths themselves. The public sandbox::require_file stays and calls artifacts::require_existing, and cli/run.rs and cli/sandbox/mod.rs import require_artifact from artifacts. This removes artifacts → sandbox.
4. nvx-rs: keep the host's module dependencies acyclic. This adds the guard, states the layering in host's module docs, and describes the test in the nvx-rs README and doc/ci.md.

The guard

tests/host_modules.rs reads src/lib.rs and the files under src/host/ as text, with std alone. It needs no new dependency, and it runs in check-nvx-rs's existing cargo test steps without a workflow change. It:

• blanks comments and literals: line, doc, and nested block comments, plain, byte, C, and raw strings, and character literals, but not lifetimes or labels;
• follows mod declarations and inline modules, and leaves out test-only code: code under a cfg that requires test (cfg(test) or cfg(all(test, unix)), but not cfg(not(test)) or cfg(any(test, feature = "cli"))), the files of the modules that such code declares, #[test] functions, and inline tests modules. It excludes guarded code only as far as bracket structure shows where that code ends: an item, with angle brackets tracked in its header; a statement ending in ;; a macro invocation; a block, if (with its else branches), match, or loop; or a field, parameter, variant, or arm of the list that declares it, where an arm whose expression has a block needs no comma. In ordinary code, only the start of the file or a {, }, or ; before the attributes shows that an item or statement starts. A scan for such an end stops at the start of another item, for example after an item kind the guard doesn't know. Other guarded code, such as a field of a struct expression, or a generic or closure parameter, counts. The guard may therefore report a dependency from test-only code, but it never misses one from production code;
• resolves every crate::, super::, and self:: path, in use trees and elsewhere, including attributes, such as a derive, and their strings, such as serde's with = "...", to the child of host that holds what it names, through the module-level imports of the crate root and host, such as crate::Artifacts. It reads those imports to a fixed point, since one may name what another imports, in either file and order, or rename what its own module imports by the name alone, and a name that cfgs import from several children, or that a module also has under other cfgs, depends on each of them. A macro that a child exports with #[macro_export], directly or through cfg_attr, and from its file or an inline module, is a crate-root item held by that child. An outer attribute's paths are test-only where what it applies to is, and an inner attribute's where its region is. A raw identifier, such as r#type, names what type would. cfg(unix) and cfg(windows) code both count.

A cycle fails the test with each strongly connected component and one reference for each dependency in it. The test also fails on code whose dependencies it cannot follow: a #[path] attribute, a file that no mod declares, an import of host or the crate root itself, including extern crate self as this;, a #[macro_use] attribute in host (directly or through cfg_attr), and a glob import from a child into either. This also covers #[path] and #[macro_use] in a host that the crate root declares inline.

Red on dev, with only the test file added:

artifacts, filesystem, launch, platform, process, sandbox, store, supervisor:
  artifacts -> platform: src/host/artifacts.rs:40 uses crate::host::platform
  artifacts -> sandbox: src/host/artifacts.rs:41 uses crate::host::sandbox::require_artifact
  artifacts -> store: src/host/artifacts.rs:42 uses crate::host::store::ArtifactIdentity
  filesystem -> platform: src/host/filesystem.rs:43 uses super::platform
  launch -> artifacts: src/host/launch.rs:12 uses super::artifacts::Artifacts
  launch -> filesystem: src/host/launch.rs:13 uses super::filesystem::ExportPlan
  platform -> supervisor: src/host/platform/linux.rs:12 uses crate::host::supervisor::Inherited
  process -> platform: src/host/process.rs:31 uses super::platform
  sandbox -> artifacts: src/host/sandbox/distro.rs:49 uses crate::host::artifacts::DISTRO_MANIFEST_SUFFIX
  sandbox -> filesystem: src/host/sandbox/mod.rs:69 uses crate::host::filesystem::ExportPlan
  sandbox -> platform: src/host/sandbox/mount.rs:36 uses crate::host::platform
  sandbox -> supervisor: src/host/sandbox/prepared.rs:67 uses crate::host::supervisor::Inherited
  store -> filesystem: src/host/store/files.rs:8 uses crate::host::filesystem
  store -> platform: src/host/store/files.rs:8 uses crate::host::platform
  store -> process: src/host/store/mod.rs:241 uses super::process::BootId
  store -> supervisor: src/host/store/mod.rs:242 uses super::supervisor::Launched
  supervisor -> launch: src/host/supervisor/mod.rs:107 uses super::launch::timeout_problem
  supervisor -> platform: src/host/supervisor/child.rs:24 uses crate::host::platform
  supervisor -> process: src/host/supervisor/child.rs:26 uses crate::host::process::POLL_INTERVAL
  supervisor -> store: src/host/supervisor/mod.rs:110 uses super::store::IdentityCheck

the_graph_holds_well_known_dependencies_of_the_sources fails there too, since dev has no host::spawn. After commit 1, the cycle shrinks to artifacts, launch, sandbox, store, supervisor; after commit 2, to artifacts, launch, sandbox, supervisor; after commit 3, it is gone, and all thirteen tests pass.

Resulting layers, lowest first, as the issue predicted:

Layer	Children
0	network, paths, report, seal, sys
1	platform
2	filesystem, nvxs, process
3	session, spawn
4	store
5	artifacts
6	launch
7	supervisor
8	instance, sandbox
9	cli

Coordination with the template stack

host::template, from the template and clone stack (#879 to #888), is not on dev yet. At the head of #888, store → template (template::Lease) and sandbox → template (template::BlockGeometry) would close a cycle again. If this PR lands first, the guard flags both edges, with a reference for each, when the stack rebases, and the stack resolves them as #897 describes.

Validation

I ran the checks locally on Windows 11 and on Linux under WSL 2 (Ubuntu 26.04, kernel 6.18), with Rust 1.95.0 and the 1.89 MSRV, on dev at 12b56130. No check needs a hypervisor.

Rebase: dev moved from ff3cedf6 to 12b56130, whose #911 deletes host::python and has sandbox::require_existing spell paths with a new std-only host::paths module. Commits 1 and 2 applied cleanly, and commit 4 needed only the README's list of tests merged. I redid commit 3 on the new code: require_pure_file is gone, so only require_artifact and require_existing move. On the new dev, the guard finds the same eight-child cycle with the same three back-edges, and the branch has the same layers, with paths in place of python. The graph now has 51 dependencies, since #911 also adds two downward ones, sandbox → platform and store → seal.

• Public API (nvx-rs: break the host module into finer-grained modules #896, invariant 1): I generated rustdoc JSON with all features (RUSTC_BOOTSTRAP=1 cargo rustdoc --lib --all-features -- -Z unstable-options --output-format json) for x86_64-pc-windows-msvc and x86_64-unknown-linux-gnu. I walked it from the crate root through public paths, re-exports, fields, variants, inherent methods, and trait impls, including synthetic and blanket ones. Each of the four commits has 0 differences from dev, over 9,632 entries on Windows and 13,779 on Linux. The moved items appear only at nvx::host::supervisor::{Inherited, Launched, VmmCommand, spawn} and nvx::host::sandbox::require_file; no platform::inherit or host::spawn path is public.
• Test names (nvx-rs: break the host module into finer-grained modules #896, invariant 2): I compared cargo test -- --list with dev, with all features and with default ones. On Windows, the only change is the thirteen new host_modules tests. On Linux, the moved module's four Linux-only tests are also renamed from host::supervisor::child::tests::* to host::spawn::tests::*. The artifacts bundling filter selects the same tests as before.
• check-nvx-rs, Windows steps: rustfmt; Clippy with -D warnings for all targets with all features, the lib, and the lib without default features; tests with all features (822 passed), default features (677), and the lib without default features (201); artifact bundling (18); rustdoc with -D warnings; the 1.89 check; and the runtime adapter's protocol-only (36) and host-only (76) configurations with their MSRV checks.
• check-nvx-rs, Linux steps: the same, with 1,396, 661, and 201 tests and bundling (19), plus the macOS cross-check, the guest binaries' lint and tests (820), their build and checks (33), and the runtime adapter's guest-only configuration (96).
• check-aci-edge-sandboxes: formatting, Clippy, tests (168 with all features and 89 with default features), agent bundling (4), rustdoc, and the MSRV check on both platforms, plus the macOS check on Linux.
• Each intermediate commit: Clippy with -D warnings for Windows and Linux, cargo check for macOS, and the Windows tests with all features (809) pass. The Linux library tests (1,237) pass at commits 1 and 2.
• Markdown link check: passed.

Test counts are each test binary's own test result totals. Some tests run their own binary again as a child, whose nested totals are not counted.

The hypervisor-backed tests are left to CI.

Review

Copilot's ten reviews found twenty-five ways for the guard to misread a reference. The guard commit now handles each one, with regression fixtures. Each fixture fails on the guard before the fix and passes now. No fix changes the graph of the real sources: 49 dependencies on the old base, and 51, in the same layers, on the new one.

First review, covered by imports_of_the_root_and_host_resolve_through_chains_and_every_alternative:

• Chained re-exports: host/mod.rs sorts before lib.rs, so a single pass dropped host's pub use crate::Item; of what the root imports from a child. The imports are now read to a fixed point.
• Conditional re-exports: #[cfg(unix)] pub use host::a::Thing; and #[cfg(windows)] pub use host::b::Thing; overwrote each other. Each imported name now keeps every child that it may come from, and a path through it depends on each one.

Second review:

• Bare-name aliases: the root's pub use Item as Alias; after pub use host::a::Item; was skipped, since Item is an imported name rather than a module. Imports may now start with a name that their module imports. The fixture, added to the test above, gave [] before the fix.
• Raw identifiers: super::r#b::X was split at r# and resolved outside host, and mod r#b; declared nothing. Raw identifiers are now single tokens that name what they would without r#. The new raw_identifiers_name_what_their_names_do test checks the cycle that such a path closes.
• Generic commas in test-only fields: #[cfg(test)] value: Result<super::b::X, super::b::Y>, ended at the comma inside <...>, so Y counted as production. A test-only named field or parameter now ends at the first comma outside its type's angle brackets, and an arrow's >, as in fn(u8) -> T, closes none. Cases in test_only_code_is_not_a_dependency cover fields and parameters. Before the fix, they gave a spurious a -> b.

Third review:

• A module and an import of the same name: with #[cfg(unix)] pub mod backend { ... } and #[cfg(windows)] pub use host::b as backend; in lib.rs, the module hid the import, so crate::backend::run() lost a -> b. The imports of the crate root and host along a path now count beside any module of the same name. A fixture in the import test covers that cycle. Before the fix, it gave only b -> a.
• else branches of a test-only if: the guard of #[cfg(test)] if ... { ... } else { ... } ended with the first block, so the else code counted as production. A } followed by else now keeps the guard for the next block. test_only_code_is_not_a_dependency covers an if, else if, and else chain, followed by a production call that still counts. Before the fix, it gave a spurious a -> b.

Fourth review: three findings showed the same weakness in the earlier field and else fixes. When the guard guessed where test-only code ends, a wrong guess could extend the exclusion over production code and hide a dependency. The guard now uses the extent rule above instead, so an exclusion can end too early but never too late:

• Struct-expression fields: Data { #[cfg(test)] debug: 1 < 2, value: super::b::helper() } hid value, because the earlier field fix read < as a generic bracket. A guarded field of a struct expression now counts.
• Qualified macros: #[cfg(test)] crate::make_tests! {} left the guard open over the next function. Macro invocations through a path now end after their arguments.
• Braces in generic arguments: #[cfg(test)] fn helper<T: Bound<{1}>>() { ... } ended at {1}. Items now end at the body after their generics. The other example, #[cfg(test)] if { true } { ... }, still ends at its block condition, so its if block counts. A new test, guarded_code_whose_end_the_tokens_do_not_show_counts, covers it and the struct-expression field. Taking the second block as the body would hide production code after if c { a } { b }.
• Generic tuple fields: pub struct S(#[cfg(test)] Result<X, Y>); ended at the generic comma. Fields and parameters of declared structs, unions, variants, and functions now end at a comma outside their type's angle brackets.
• Local imports: fn helper() { use crate::host::b::Item; } in lib.rs or host was treated as a re-export. Only module-level imports now name items for the crate root and host.

Each of the five cases failed on the guard before this round and passes now. All earlier fixtures still pass, and the real graph is unchanged. Fifth review: two more ways for an exclusion to end too late.

• Arms without commas: #[cfg(test)] 0 => loop { break } needs no comma, so the guard scanned to the comma of the next, production arm. An arm whose body is a block expression (a block, if, match, loop, or unsafe or const block) now ends after that block and any else chain. test_only_code_is_not_a_dependency covers a guarded loop arm before a production arm, which still counts.
• Brackets in discriminants: in enum E { A = Data { ... }.value, B = pick(...) }, the brackets after Data and pick were read as variant field lists. They now count as variant fields only when they follow a variant name that starts a variant, after {, ,, or an attribute. guarded_code_whose_end_the_tokens_do_not_show_counts covers both discriminants.

For defense in depth, scans for the end of an item header or an expression statement now stop at tokens that can only start another item or attribute, such as pub, struct, use, let, or #. Lifetimes and labels, such as 'static, are now single tokens, so -> &'static str doesn't stop a header scan. A guarded auto trait Marker {}, a kind the guard doesn't know, can no longer extend over the next function. A fixture covers it, along with a test-only function returning &'static str.

Sixth review:

• Async closures: async move || ... was taken for an async move { ... } block, so a guarded arm with such a closure ran to the next arm's block. A block now needs a { after async move.
• Generic parameters: in fn f<#[cfg(test)] 'a, T>() { ... }, the lifetime was taken for a label, and #[cfg(test)] const N: usize scanned to a later ;. Guarded code that follows a < or a , in ordinary code is a list element whose end the guard can't see, so it counts. guarded_code_whose_end_the_tokens_do_not_show_counts covers both, and the body and the following use still count.
• extern crate self as this;: this crate-root alias was ignored, so crate::this::host::b::... resolved outside host. It now fails the guard as an import of the crate root itself.

I also closed the remaining way for children to depend on one another without a path: macros. A #[macro_export] macro of a child, which is at the crate root, now resolves to that child, and #[macro_use] in host fails the guard. There are fixtures for both. host uses neither today. Expression-statement scans also stop at union and macro, which start items.

Seventh review:

• cfg_attr: #[cfg_attr(unix, macro_export)] and #[cfg_attr(unix, macro_use)] were ignored. Attribute checks now look inside cfg_attr under any predicate, as the #[path] check already did. The first form registers the export, and the second fails the guard.
• Inline children: an exported macro in mod a { ... } inside host/mod.rs was attributed to host, not to a. Each export now records the module that encloses it. I applied the same rule to #[macro_use] and #[path], which an inline host in lib.rs could otherwise bypass. Fixtures cover the inline cycle and both inline-host failures.

Eighth review:

• Paths in attributes: attributes were skipped whole, so #[derive(crate::host::b::Serialize)] in a, while b uses a's type, hid a -> b. The crate::, super::, and self:: paths in an attribute's tokens now count, and so do those in its strings, such as serde's with = "super::b::codec", which a derive turns into code. Each counts as what the attribute applies to does: an outer attribute's paths are test-only only where its item, field, or other code is, and an inner attribute's only where its region is. A new test, paths_in_attributes_count_where_what_the_attributes_apply_to_does, covers the derive cycle, cfg_attr, string paths with their lines, and test-only items, fields, and modules.
• Closure parameters: in |#[cfg(test)] _unused: ()| { super::b::helper(); };, the guard ran through the closure body to the statement's ;. Rather than adding | to the < and , that left guarded code counted, I inverted the rule: in ordinary code, a guard now leaves code out only after the start of the file or a {, }, or ;, where an item or statement starts. This also covers cfg_if!'s if #[cfg(test)] { ... } else { ... }, whose production else branch the guard had left out. guarded_code_whose_end_the_tokens_do_not_show_counts covers both.

Four of the five cases that I compared failed on the previous guard: the derive cycle, a serde string path, the closure, and cfg_if!. The fifth, a derive on a #[cfg(test)] item, passes on both, and checks that the new code doesn't count test-only attributes.

Ninth review:

• Documentation: #[doc = "[spawn](crate::host::supervisor::spawn)"] would add platform → supervisor, though the same link in a /// comment, which is blanked, adds nothing. The strings of a doc = ... value or a doc(...) list, also within cfg_attr, now name no dependency, while helper attributes' strings, such as serde's, still count.
• Escaped strings: "crate::host::\x62::codec" was read as crate::host. Strings that are not raw are now decoded first, with \x, \u{...}, the simple escapes, and line continuations, and each decoded byte keeps the line of its source.

Tenth review:

• Raw attribute names: #[r#path = "c.rs"], #[r#macro_use], and #[r#macro_export], also within cfg_attr, bypassed the attribute checks. They now compare names without r#, as do the test, cfg, and doc checks.
• Macro names: a macro named host, exported by a, shared the crate root's import map with the module host, so crate::host::b::h() in b gained b → a. Exports now register as NAME!, a path names a macro only with the ! and delimiter of an invocation, and an import takes its name in both namespaces.

Each case failed on the guard before its round: four of the five that I compared in the ninth, and five of the six in the tenth. The others pass on both, and check that serde paths beside a doc comment, and macro paths through host beside an X != 1 comparison, still resolve.

The counts above are from the rebased branch with every fix. CI was fully green on a1682c05; later heads were superseded before their runs finished.

[Copilot]

🟡 Changes recommended

The dependency guard can silently miss cycles through chained or conditional re-exports.

2 open issues

• Resolve chained re-exports to a fixed point · New
• Preserve all conditional re-export targets · New

What changed in this PR

This PR removes dependency cycles between nvx::host’s direct children, establishing the layering needed for the module refactoring in #896 while preserving existing public paths.

Changes:

• Moves inherited handles, VMM spawning, and artifact checks into lower-level modules.
• Adds a standard-library-only dependency guard with parser and cycle-detection tests.
• Documents the layering rule and its existing CI integration.

File	Description
nvx-rs/​tests/​host_modules.rs	Adds dependency analysis and cycle-detection tests.
nvx-rs/​src/​host/​supervisor/​mod.rs	Preserves public paths through re-exports.
nvx-rs/​src/​host/​store/​mod.rs	Imports Launched directly from spawn.
nvx-rs/​src/​host/​spawn.rs	Relocates VMM spawning and corrects its documentation link.
nvx-rs/​src/​host/​sandbox/​plan.rs	Uses artifact-module file validation.
nvx-rs/​src/​host/​sandbox/​mod.rs	Delegates file checks while retaining require_file.
nvx-rs/​src/​host/​platform/​windows.rs	Imports inherited handles from the platform layer.
nvx-rs/​src/​host/​platform/​other.rs	Uses the relocated inherited-handle type.
nvx-rs/​src/​host/​platform/​mod.rs	Declares the crate-visible inherit module.
nvx-rs/​src/​host/​platform/​linux.rs	Imports inherited descriptors from the platform layer.
nvx-rs/​src/​host/​platform/​inherit.rs	Holds inherited descriptor and handle abstractions.
nvx-rs/​src/​host/​mod.rs	Declares private spawning and documents layering.
nvx-rs/​src/​host/​cli/​sandbox/​mod.rs	Imports artifact checks from their new location.
nvx-rs/​src/​host/​cli/​run.rs	Uses the relocated artifact check.
nvx-rs/​src/​host/​artifacts.rs	Owns the shared artifact and file checks.
nvx-rs/​README.md	Describes the dependency guard.
doc/​ci.md	Documents the guard’s inclusion in CI.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The dependency guard can miss genuine cycles and report false cycles for valid Rust syntax.

3 open issues

• Resolve re-export aliases in module dependency analysis · New
• Normalize raw identifiers in module dependency paths · New
• Track generic nesting when parsing test-only fields · New

2 resolved since last review

• Preserve all conditional re-export targets
• Resolve chained re-exports to a fixed point

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The dependency guard can miss cycles through conditional aliases and falsely report cycles from test-only branches.

2 open issues

• Resolve module/import name conflicts to preserve Windows dependency edges · New
• Preserve cfg guards across if-else branches · New

3 resolved since last review

• Track generic nesting when parsing test-only fields
• Normalize raw identifiers in module dependency paths
• Resolve re-export aliases in module dependency analysis

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The new guard has parsing and scope-resolution errors that can hide production cycles or report false ones.

5 open issues

• Distinguish field initializers from types when tracking angles · New
• Recognize qualified macros before classifying separators · New
• Track syntax context to identify guarded function bodies · New
• Track generic nesting in tuple-field types · New
• Restrict import aliases by module-level scope · New

2 resolved since last review

• Preserve cfg guards across if-else branches
• Resolve module/import name conflicts to preserve Windows dependency edges

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Two parsing cases in the new guard can suppress production dependencies and allow module cycles to pass undetected.

2 open issues

• Handle guarded match arms without trailing commas · New
• Avoid misclassifying discriminant initializer fields · New

5 resolved since last review

• Restrict import aliases by module-level scope
• Track generic nesting in tuple-field types
• Track syntax context to identify guarded function bodies
• Recognize qualified macros before classifying separators
• Distinguish field initializers from types when tracking angles

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The dependency guard can still omit production dependencies and allow cycles to pass undetected.

3 open issues

• Avoid treating async closures as guarded blocks · New
• Preserve production references after guarded generic parameters · New
• Reject extern crate self aliases to prevent hidden cycles · New

2 resolved since last review

• Avoid misclassifying discriminant initializer fields
• Handle guarded match arms without trailing commas

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The dependency guard still misses macro dependencies from inline children and conditional attributes, allowing production cycles to pass undetected.

2 open issues

• Recursively inspect cfg_attr macro attributes · New
• Track macro export scope for inline child cycle detection · New

3 resolved since last review

• Reject extern crate self aliases to prevent hidden cycles
• Preserve production references after guarded generic parameters
• Avoid treating async closures as guarded blocks

_{Review effort: Balanced}