tests: launch the runtime adapter's VMs with a layered root

.github/workflows/run-nvx-microvm-tests.yml

@@ -1250,14 +1250,17 @@ jobs:
 
       # The runtime adapter's hypervisor scenarios on this backend: the ignored
       # tests of its host-only configuration, which read the backend through
-      # `nvx::Hypervisor::from_env_or_default`. Its host program launches a VM
+      # `nvx::Hypervisor::from_env_or_default`. Its host program launches VMs
       # of the artifacts above, with the runtime identity that their build
       # provenance gives, whose initramfs runs the adapter's guest agent in
-      # place of NVX's managed agent. Later processes of the host program
-      # reattach to the VM, as after a restart of the orchestrator, and stop
-      # it. The guest agent is a static musl executable: Linux builds it, and
-      # Windows takes the one that distro-artifacts builds on Linux, as it
-      # takes the Ubuntu and Azure Linux images.
+      # place of NVX's agents. Later processes of the host program reattach to
+      # a VM, as after a restart of the orchestrator, and stop it. The layered
+      # scenarios boot the Ubuntu EROFS image over a copy of the scratch
+      # template, from the guest artifacts, as the sandbox steps above do, and
+      # the guest agent's worker assembles the root outside PID 1. The guest
+      # agent is a static musl executable: Linux builds it, and Windows takes
+      # the one that distro-artifacts builds on Linux, as it takes the Ubuntu
+      # and Azure Linux images.
       - name: Build the runtime adapter's guest agent on Linux
         if: runner.os != 'Windows' && inputs.guests-and-sandboxes && !inputs.debug-kernel
         shell: bash

doc/ci.md

@@ -1305,8 +1305,11 @@ guest-only configuration, that its guest agent serves the session, also on a
 tty that it puts in raw mode. Each runs against a test broker that sends it
 messages that span records, resets, disconnects, and malformed records. The
 host-only tests also check the initramfs that runs the guest agent in place of
-NVX's managed agent, and the runtime identity that the host program takes from
-NVX's identity of its artifacts.
+NVX's agents, the runtime identity that the host program takes from NVX's
+identity of its artifacts, and the plan, OpenVMM arguments, and record of a
+launch with a layered root. The guest-only tests also run the guest agent's
+worker of a layered root against a fake root: its root configuration, the
+failure of each stage of the root, which it reports, and its teardown.
 
 The development release job depends on `aci-edge-sandboxes` and `nvx-rs` and
 requires their combined Linux/Windows results to be successful; failed,
@@ -1330,15 +1333,20 @@ The same jobs build the runtime adapter's host-only configuration on their
 backend and run its ignored tests, its VM scenarios, with `NVX_HYPERVISOR`
 naming the backend. Through NVX's supervisor, the adapter's host program
 launches a VM of the job's artifacts, whose initramfs runs the adapter's guest
-agent in place of NVX's managed agent, with the runtime identity that the
-artifacts' build provenance gives. Later processes reattach to the VM, as after
-a restart of the orchestrator, find it mismatched under another runtime
-identity without signaling it, and stop it. The Linux jobs build the guest
-agent, a static musl executable, first, and the Windows job takes the one that
-`distro-artifacts` builds on Linux, as it takes the Ubuntu and Azure Linux
-images. The adapter's other tests, including those of its guest agent, run in
-the `nvx-rs` job. Changes under `tests/runtime-adapter/` therefore trigger the
-NVX microVM test matrix too.
+agent in place of NVX's agents, with the runtime identity that the artifacts'
+build provenance gives. Later processes reattach to the VM, as after a restart
+of the orchestrator, find it mismatched under another runtime identity without
+signaling it, and stop it. The adapter's layered scenarios boot the Ubuntu
+EROFS image over a copy of the scratch template, from the guest artifacts,
+where the guest agent's worker, outside PID 1, assembles the root through
+`nvx::guest::root`. They check the root, and that a failed assembly, an
+invalid root configuration, and a failed teardown each reach the host program
+with the stage that failed, and still end the VM cleanly. The Linux jobs build
+the guest agent, a static musl executable, first, and the Windows job takes the
+one that `distro-artifacts` builds on Linux, as it takes the Ubuntu and Azure
+Linux images. The adapter's other tests, including those of its guest agent,
+run in the `nvx-rs` job. Changes under `tests/runtime-adapter/` therefore
+trigger the NVX microVM test matrix too.
 
 ## Adversarial campaigns
 

doc/project-structure.md

@@ -344,9 +344,11 @@ independent adapter's does. Its host program and its guest agent exchange the
 adapter's own framing over the control session between the host and the
 guest, and its tests check each of them against a test broker. Its host
 program also runs the guest agent in VMs of NVX's artifacts through NVX's
-supervisor, and reattaches to them from other processes, which its ignored
-tests check on each backend in CI. See its
-[README](../tests/runtime-adapter/README.md).
+supervisor, and reattaches to them from other processes. In VMs with a
+layered root, the guest agent's worker assembles the root through
+`nvx::guest::root`, outside PID 1, and the host program checks it with probes,
+in a table of scenarios. Its ignored tests check the VMs on each backend in CI.
+See its [README](../tests/runtime-adapter/README.md).
 
 ## Root files
 

tests/runtime-adapter/Cargo.toml

@@ -15,13 +15,25 @@ publish = false
 # does. Without features, the adapter builds against the protocol-only `nvx`.
 default = []
 # The host program: the host API of `nvx` and the `runtime-adapter-host` binary.
-host = ["nvx/host"]
+host = ["nvx/host", "dep:serde_json"]
 # The guest agent: the guest API of `nvx` and the `runtime-adapter-guest` binary, which builds as a
 # static `x86_64-unknown-linux-musl` executable.
-guest = ["nvx/guest"]
+guest = ["nvx/guest", "dep:nix"]
 
 [dependencies]
 nvx = { path = "../../nvx-rs", default-features = false }
+# The host program records each launch in the sandbox's store as JSON, with the persisted form of
+# its plan. The host side of `nvx` depends on the same release.
+serde_json = { version = "1.0.120", optional = true }
+
+# The guest agent's PID 1 collects the status of every child and ends the unrelated one, whose
+# system calls `nvx` leaves to the caller. The guest side of `nvx` depends on the same release,
+# with these features among its own.
+[target.'cfg(target_os = "linux")'.dependencies]
+nix = { version = "0.31.3", default-features = false, features = [
+    "process",
+    "signal",
+], optional = true }
 
 # The guest agent's tests open pseudo-terminals. The guest side of `nvx` depends on the same
 # release, with this feature among its own.