[Pedro Henrique Penna (ppenna)]

Part of #1130 (SL6.10c, "The default guest's design matches what it does"). Parent #1090, umbrella #1076.

What and why

Design 4 still described execution machinery that earlier slices deleted: the old layered init's (nvx-init-agent) per-execution mount, PID and UTS namespaces; its sibling guest-agent and workload cgroups, with their memory protection, limits, placement barrier and charging of a RAM upper; its containment-failed category; the one-shot sandbox's boot-time shares (SL7.8c's Alpine helpers); and the managed agent's sandbox mode (SL7.8b), which unmounted its mappings at stop. It also said that the layered root assembles only EROFS images for trusted lowers and creates no accounts, which no longer holds for nvx-init. This PR does SL6.10c's Scope and no more: it revises the existing overview and 4.1–4.4 in place around nvx-init's final behavior, as the code on feature/nvx-refactor has it.

• One root and a VM-wide hostname (4, 4.1.1, 4.3.2): nvx-init assembles the root from either image format (EROFS, or a GPT disk's ext4 layers), over either upper, with either overlay mode, mounts the export and the runtime file systems, applies one VM-wide view (hostname, machine ID, resolver file), and switches once; a restore builds the same root from its activation record over a fresh upper.
• Credentials per execution (4.2.1, 4.3.1): one workload identity for the VM, resolved, or created on request, once (by nvx-init in its root before the switch, by the blockless /init before the managed agent or the one-shot workload), and taken by each execution's child, with no groups, no capabilities and no_new_privs.
• Init and helper priority; helpers before the switch (new 4.2.3; 4.3.3, renamed "Priority and Resources"): the time daemon and the announcer run from the initramfs and start before the switch (the early boot starts them and hands them over; a restore forks its announcer from PID 1), run with PID 1's out-of-memory score adjustment of -1000 and nice value of -10, and end the VM when either ends; each execution's child resets both to 0 before it takes its credentials. Figure 4.2 shows the helpers.
• One process group per execution (4, 4.2.2, 4.4.3): its end, cancellation, timeout and a session reset kill it, and none of its output reaches the session after a reset. CANCEL names the group.
• No cgroups and no per-execution limits (4.1, 4.3.3): the RAM upper's cap is the one limit that nvx-init sets within the VM, and it does not cover the runtime's own tmpfs mounts, such as /dev/shm; an execution's timeout ends it rather than limit its resources.
• The space and MappingTable (4, 4.1.1, 4.1.3, 4.2, 4.4.1): the space is NVX's internal reference code that nvx-init implements, crate-private since SL6.13b; the public MappingTable keeps the account of the host's table, refuses an empty source, and hands its ordered mappings to the reference space's mapper. The text names no item that SL6.11d deleted.
• Live shares (4.1.2): the blockless /init's boot binds and nvx-init's boot-named shares replace the one-shot sandbox's; the CLI's run and sandbox commands refuse overlapping and reserved targets, as the host chain left them.
• NVXC version 2 only (4.4): the page keeps SL4.4c's and SL4.4d's v2 text (no FEATURES, no output cap, the streamed standard input, the vectors paragraph, the Shutdown row) and adds to it: the operations point to the guidelines for nvx-init's capture and activation; the error paragraph adds BUSY, which carries no status or category, so Table 4.4 drops busy and containment-failed; 4.4.3 says what a running execution takes (its standard input, a cancellation, a shutdown) and what gets BUSY, that the cancelled execution's exit report precedes a shutdown's acknowledgement, and what a reset does; 4.4.2 says that nvx-init and the managed agent serve the session through one dispatcher.

Procedures stay in doc/guest-agent-guidelines.md, which these pages link. The headings whose anchors other documents use (4.1.1–4.1.3, 4.4.1, 4.4.2) are unchanged.

Not in this PR, per #1130: new design pages; host, device or lifecycle chapters (SL6.10b); the library guide (SL6.10a), build (SL6.10e) and CI (SL6.10f) docs; making the space public; per-execution roots, cgroups, namespaces or limits; a second hostname or an alternate helper lifecycle; the init contract and its examples (SL7.9).

Rebase. At its merge turn, rebased with git -c rerere.enabled=false rebase --onto origin/feature/nvx-refactor c1198c70356 onto e6c65b95f63, which holds SL4.4c and SL4.4d (NVXC v2 only), SL6.11d, SL6.13b, the host chain, SL6.10e and SL6.10f. 4.3 and 4.4 conflicted with SL4.4c's and SL4.4d's text; the resolution keeps their v2-only facts and this PR's structure. rebase_check verify passed.

Size. 0 core lines and 0 counted files (estimate 0): five design pages. BOOT_CONTRACT_VERSION, CONTROL_CONTRACT_REVISION and the public API are unchanged.

Validation

scripts/local_gates.py is not on feature/nvx-refactor's tip, so these are the documentation steps of check-quality and the whole of validate-nvx, from the tip's action definitions, run on Windows at c6dc0192c99:

Check	Result
python scripts/check_markdown_links.py	Passed
python scripts/check_test_layout.py	Passed
python scripts/check_test_changes.py --base origin/feature/nvx-refactor (e6c65b95f63)	0 changes to existing tests
validate-nvx (Windows): python -m compileall -q scripts, the unittest list (test_markdown_links.py and test_module_diagrams.py included), test_adversarial.py, test_hosts.py, the nvx.py ... --help calls	Passed: 1803 unittests (73 skipped), 84 adversarial tests (11 skipped), 4 host tests, every --help call
Claims review	Code-review agents checked the pages' statements against nvx-init, the managed agent's dispatcher and execution loop, guest::{root, view, mappings, activation}, sys::spawn, the shell /init, nvx-hostmount, the v2 protocol and the CLI's share checks. The first review's three findings (the RAM upper's lifetime, the export's children, share tokens per bind) and Copilot's two (the RAM cap does not cover /dev/shm; the overlap refusal is the CLI commands') are folded, and so is the second review's (output that the send queue held goes out before a reset's acknowledgement, so none reaches the new session). The third review, at c6dc0192c99, found no issues

Documentation only, so no build, host or microVM run.

[Copilot]

🟡 Changes recommended

The documentation overstates the RAM-upper cap’s scope because memory-backed files in the separate, world-writable /dev/shm tmpfs are not covered by it.

1 open issue

• Clarify RAM cap excludes files in /dev/shm · New

What changed in this PR

This documentation-only PR updates the guest runtime design to match nvx-init’s current behavior, supporting the broader effort to separate NVX’s internal programs from its public library.

Changes:

• Describes one VM-wide root, supported image formats, live shares, and mapping-table handling.
• Replaces removed namespace and cgroup machinery with workload credentials, process-group cleanup, and helper supervision.
• Updates control-protocol features, cancellation, and session-reset behavior.

File	Description
doc/​design/​4.4-host-guest-control-interface.md	Updates operations, feature announcements, errors, and reset semantics.
doc/​design/​4.3-isolation-and-resource-model.md	Describes credentials, shared namespaces, priority, and resource boundaries.
doc/​design/​4.2-guest-agents-and-workload-model.md	Explains execution lifecycles, process groups, and helper supervision.
doc/​design/​4.1-guest-filesystem-and-image-model.md	Revises root assembly, restore, live shares, and mapping-table behavior.
doc/​design/​4-guest-runtime-architecture.md	Aligns the overview with nvx-init and the internal reference space.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The documentation incorrectly states that all overlapping guest targets are rejected, overlooking supported nested mappings such as a read-only directory with a writable subdirectory.

1 open issue

• Clarify permitted nested target overlaps · New

1 resolved since last review

• Clarify RAM cap excludes files in /dev/shm

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are recorded for this documentation-only update to the guest-runtime design.

No open issues 🎉

1 resolved since last review

• Clarify permitted nested target overlaps

_{Review effort: Balanced}

[github-actions]

This pull request changes no existing test

Relocated unchanged: 0; added: 0. Compared the merge base e6c65b95f631 with c6dc0192c998.

[Copilot]

🟢 Approval recommended

No active review issues are reported for the guest-runtime documentation update.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are reported for this documentation-only update to the guest runtime design.

No open issues 🎉

_{Review effort: Balanced}