Skip to content

nvx-rs slimming 1.2.2: the managed agent lives in nvx-init #1096

Closed as not planned

Description

Parent: #1078, in #1076. Needs: #1092, #1093, #1095. Unblocks: #1115, #1116, #1131.

Goal. The managed agent (guest::managed_agent and nvx-managed-agent) first stops using nvx's crate-private mapping and process operations and its test-only fakes, then moves into nvx-init. It reaches NVXC and the guest's space through local alias modules, nvxc and space, until they move in #1127. Its direct mode and shared loop stop using the guest's process modules in #1116; its sandbox mode keeps using guest::{exec, spawn, process, cgroup, entry} until #1123 deletes it with the old layered init. Before the move, nvx's own tests stop using the agent's test helper.

PRs, in order. Each PR has one goal, leaves dev green, and names in its description each old test of its area as kept, rewritten or retired, with each change that check_test_changes.py reports. Its tests follow the repository's test layout: a module's unit tests, and the code that only they use, sit in its tests.rs or tests/ and move with it. The estimates count core lines (code, not comments, docs or tests) and counted files; each PR records its measured values. Each PR does what its Scope says and no more: a case, input or layout that its Scope doesn't name, and whatever "Not in this PR" lists, is out of scope. Address every review comment within the scope, and ask before acting on one that asks for more. A PR whose measured core lines pass the stop that its Estimate names (twice the estimate, at most 600) stops and asks before continuing.

  1. SL1.4a: The managed agent uses only public mapping and process operations.

    • Objective: The managed agent must stop depending on nvx crate internals and test-only fakes before it can move crates. It keeps the same mapping order, failure latch, entry accounting, teardown diagnostics and process behavior using public operations and an agent-owned test seam.
    • Contents: managed_agent::{mappings, seam} use Mapper::{apply, teardown} and the public TargetRoot operations instead of the crate-private Kernel, SystemKernel, Mapper::{apply_with, unmount_with} and TargetRoot::{open_with, add_mount_with}, with a test seam of the agent's own instead of nvx's private fakes. Its exec uses Spawned::id and Child::new instead of the crate-private Spawned::process and Child::from_process. Its launch and seam tests stop using nvx's test-only Prepared::simulated and Command::{prepare, simulate_credentials}: they use the agent's own seam, and the simulation tests that need those stay in nvx, beside their owners. No mapping or process internal becomes public. The agent's account of the host's mapping table stays on the public MappingTable: its order, its latch after a failure, its entry numbers and its teardown's diagnostics.
    • Scope:
      • Change guest/managed_agent/mappings.rs to use Mapper::{apply, teardown} and public TargetRoot operations instead of mapping kernel hooks and *_with methods.
      • Keep the host mapping account on public MappingTable, preserving ordered parts, entry numbers, the failure latch and teardown diagnostics.
      • Change managed-agent exec to use Spawned::id and Child::new instead of crate-private process access and construction.
      • Replace managed-agent uses of Prepared::simulated from guest/entry/tests.rs and Command's test methods from guest/spawn/tests.rs; put the replacement system and spawners in managed_agent/seam/tests.rs, leaving owner-specific simulation tests in nvx.
    • Not in this PR:
      • Making any mapping, spawn, command or child internal public: the move must use the existing public operations.
      • Changing mapping order, refusal behavior, failure latching, entry numbering, teardown diagnostics or launch results.
      • Moving the managed agent to nvx-init; SL1.4b does that after this dependency cleanup.
      • Redesigning the mapping table, process model or test framework beyond the seam needed by this module.
    • Approach: Route production code through the existing public mapper, root and process methods. Add the smallest local seam needed to drive the same mapping and launch failures in tests, and relocate only tests that belong to private nvx operations; do not expose internals or build a general mocking framework.
    • Done when:
      • Managed-agent mapping tests run on its own seam and preserve ordering, latching, entry numbers and teardown diagnostics.
      • The failed entry stage of sandbox_launch_reports_a_simulated_stage_without_privileges retains its coverage without Prepared::simulated or credential simulation.
      • Simulation tests that exercise entry or spawn alone remain beside those implementations in nvx.
      • No managed-agent production or test code uses the named crate-private mapping and process operations.
    • Needs: SL0.3b, in nvx-rs slimming 1.1.3: the guest's and the host's OS layers live in nvx-sys #1093.
    • Estimate: 280 core lines, 3 counted files. Past 560 core lines, stop and ask before continuing.
  2. SL1.4b: The managed agent lives in nvx-init.

    • Objective: The managed agent and nvx-managed-agent become owned by nvx-init, without changing their command line, diagnostics or execution modes. Temporary local aliases keep their current protocol, space and process dependencies available until later slimming PRs replace or remove them.
    • Contents: git mv of guest::managed_agent (2.0K core lines), with its diagnostics, and of nvx-managed-agent. It reaches NVXC through a local nvxc module, which re-exports by name the flat protocol exports that it uses, until SL6.12b moves NVXC, and the guest's space through a local space module, declared inline beside it, until SL6.13b moves the space; its direct mode and shared loop use the guest's process modules until SL7.6a and SL7.6b; its sandbox mode keeps its root entry, barrier and cgroup placement, and its uses of guest::{exec, spawn, process, cgroup, entry}, until SL7.8b deletes it with the old layered init. Before the move, the nvx tests that call the agent's isolate_process_test (in guest::{entry, exec, root, clone::repair} and guest::spawn) get a process-isolation helper of their own; the moved agent keeps its own. No cfg(test) item crosses a crate. The agent's host mapping table moves with it, and takes MappingTable from nvx, not through space.
    • Scope:
      • Move nvx-rs/src/guest/managed_agent/, including its tests.rs, submodule tests.rs files and tests/loopback.rs tree, its diagnostics, binary entry point and six integration cases into crates/nvx-init.
      • Add a local nvxc module that re-exports by name only the flat protocol items the moved code uses until SL6.12b.
      • Add an inline local space module for the guest-space imports until SL6.13b; import MappingTable directly from nvx, not through that alias.
      • Keep direct mode, the shared loop and sandbox mode on their current guest process modules; sandbox mode retains root entry, barrier and cgroup placement.
      • Before the move, copy isolate_process_test from managed_agent/tests.rs into nvx-rs/src/tests.rs for entry, exec, root, clone repair and spawn tests; the moved agent keeps it, PROCESS_TEST_LOCK, AgentConfig::for_test and the loopback harness in its own tests tree.
    • Not in this PR:
      • Behavior changes, renames, diagnostics cleanup or managed-agent redesign: this PR is the move and the edits the crate boundary forces.
      • Moving NVXC or the guest's space; SL6.12b and SL6.13b do those later.
      • Rewriting direct mode or the shared loop onto the new exec core; SL7.6a and SL7.6b do that.
      • Deleting sandbox mode or its process, cgroup and entry dependencies; SL7.8b removes it with the old layered init.
      • Sharing a cfg(test) helper across crates: each owner keeps its own process-isolation helper.
    • Approach: Use git mv for the agent, binary and tests. Satisfy the crate boundary with two narrow local alias modules and duplicated test isolation, preserving existing imports and modes until their named follow-up PRs; do not redesign the agent or move its providers early.
    • Done when:
      • All six managed-agent integration cases run from nvx-init and retain their environment, working-directory, descriptor, syntax, status and diagnostics assertions.
      • The moved unit tests use the agent's own process-isolation helper, and nvx tests use their new local helper.
      • Guest checks and staged-binary tests find nvx-managed-agent in nvx-init, and the image still stages it at /sbin/nvx-managed-agent.
      • No cfg(test) item crosses the crate boundary.
    • Needs: SL1.4a, above; SL1.1a, in nvx-rs slimming 1.2.1: the guest helper binaries ship from nvx-guest-tools #1095; SL0.2c, in nvx-rs slimming 1.1.2: one Cargo workspace, and the new crates' empty shells #1092.
    • Estimate: 300 core lines, 5 counted files. Past 600 core lines, stop and ask before continuing.

Tests. SL1.4a runs the mapping tests in guest/managed_agent/mappings/tests.rs on an agent-owned seam, without exposing any mapping internal, and rewrites the launch and seam tests that use Prepared::simulated or Command::{prepare, simulate_credentials} on the agent's own seam: the failed entry stage of sandbox_launch_reports_a_simulated_stage_without_privileges keeps its coverage, and the simulation tests of entry and spawn alone stay in nvx. SL1.4b moves the agent's unit tests, and splits its six integration cases out of nvx-rs/tests/guest_tools.rs into nvx-init (managed_agent_helper_applies_inherited_exact_and_layered_environments, managed_agent_helper_accepts_large_exact_environment, managed_agent_helper_defensively_rejects_bad_configuration, managed_agent_helper_runs_the_workload_in_its_own_directory, managed_agent_helper_closes_its_internal_descriptor and managed_agent_bad_helper_syntax_exits_125); they still check the same command line, environment, working directory, descriptor closure, exit status and diagnostics. The nvx tests that isolated their processes with the agent's helper use their own. The guest build, its checks and the staged binaries' tests take the agent and its six integration cases from nvx-init, and the image still stages /sbin/nvx-managed-agent.

Done when: every PR above has merged, with dev green.

Activity

  1. esaurez commented on Nov 3, 2026

    @esaurez
    ContributorAuthor

    Closing as not planned: the plan in #1076 changed. nvx stays the only crate, with no Cargo workspace and no new crates. NVX's own programs, its control protocol and the OS layers stay in nvx, private to it, and CI checks the public API against committed snapshots (#1091). The managed agent stays under guest::managed_agent, and #1091 hides its entry point; nvx-init's code goes under guest::init.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions