nvx-rs slimming 5.2.1: the library's guide, its design and the guest-agent guidelines #1130

Parent: #1090, in #1076. Needs: #1102, #1103, #1105, #1113, #1117, #1118, #1120, #1123, #1125, #1126, #1127. Unblocks: #1131, #1132. No PR of this group merges before the API-ready commit.

Goal. The docs describe the final public library: the root landing and slim nvx-rs/README.md; a library guide with compiled cold-boot, restore and reattach examples and caller obligations; host and snapshot design that separates the VMM, library and users; the default guest's design as nvx-init implements it; and doc/guest-agent-guidelines.md, with nvx-init's private space as quoted internal reference code, not public API.

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. SL6.10a: The library's guide describes only the final public library.

   • Objective: Library users get a short, accurate path from the repository landing page to the final nvx library and its common workflows. The guide states the caller-owned responsibilities that the library deliberately does not implement.
   • Contents: The root landing links; a slim nvx-rs/README.md; a short library guide in doc/; cold-boot, restore and reattach examples linked to compiled ones; the caller's obligations. It starts from today's README, which dev expanded, with its split platform, store and supervisor layout.
   • Scope:
     • Update the root README.md landing links and slim nvx-rs/README.md to the final public library.
     • Add one short library guide under doc/; this PR creates no other guide page.
     • Document cold boot, strict-snapshot restore and reattach, linking each workflow to the corresponding compiled example.
     • Document caller ownership of paths and image checks, durable state, locks, I/O, timing, recovery, outputs and process lifecycle.
     • Replace today's platform, store and supervisor description only where these three documents discuss the library.
   • Not in this PR:
     • CLI command reference material: SL6.10d owns doc/run.md and runtime doc/usage.md.
     • Host, snapshot or guest architecture rewrites: SL6.10b and SL6.10c own the named design pages.
     • A new tutorial set, cookbook or duplicate API reference beyond the one planned library guide.
     • Unrelated root README sections, build instructions or repository history.
     • Examples that are not cold boot, restore or reattach, or examples that are not checked as public-API doc tests or compile-only examples.
   • Approach: Start from the existing root and crate READMEs, remove descriptions of components that no longer belong to the public API, and link to one compact guide. Reuse the three public-API doc tests or compile-only examples instead of embedding divergent copies. State obligations as bounded lists; do not create a documentation framework or rewrite unrelated landing content.
   • Done when:
     • The root landing page, slim crate README and one library guide describe only the final public library.
     • Cold-boot, restore and reattach sections link to checked public-API doc tests or compile-only examples.
     • The guide names the caller obligations that replace removed stores, drivers and policies.
     • The repository Markdown-link check passes for the changed documents.
   • Needs: SL2.18b, in nvx-rs slimming 2.3.3: a VM restores from a snapshot, through a sans-I/O restore machine #1103; SL5.1a, in nvx-rs slimming 4.1.1: public-API tests, and smoke tests on real VMs #1118; SL6.8c, in nvx-rs slimming 4.3.3: the error codes are private #1126; SL6.11c, in nvx-rs slimming 4.2.1: the code that stays stops using what leaves #1120; SL6.12, in nvx-rs slimming 4.3.4: NVXC, the host's platform layer and the guest's space are private #1127.
   • Estimate: 0 core lines (docs), no counted files.

2. SL6.10b: The host and snapshot design separates the VMM, the library and its users.

   • Objective: The host and lifecycle design identifies what the VMM provides, what the slim library validates or drives, and what callers must own. Snapshot and restore contracts remain precise without describing removed stores or supervisors.
   • Contents: Design 1.3–1.5, 2.1, 3.4–3.5 and 5.1–5.6: the snapshot directory and its envelope, the tiers as device configurations, runtime labels, Ready and the mapping table, and the caller's path, output and lock obligations. Restore packet 6, the order of a restore with a new network policy, and the host-clock correction in the time samples keep their place, and the mapping table's contract names the public MappingTable, which an init uses.
   • Scope:
     • Update doc/design/1.3-system-components-and-responsibilities.md, 1.4-trust-boundaries.md and 1.5-compatibility-and-versioning-model.md.
     • Update doc/design/2.1-machine-model-and-configuration.md, 3.4-block-storage.md and 3.5-network.md.
     • Update design 5.1 through 5.6 for boot, Ready, capture, the strict snapshot directory and envelope, restore and failure semantics.
     • Describe snapshot tiers only as device configurations, plus runtime labels, restore packet 6, the mapping-table contract and the restore order with a new network policy.
     • Preserve the host-clock correction in time samples and document caller ownership of paths, outputs and per-snapshot locks.
   • Not in this PR:
     • New design documents or a rewrite of design sections outside the named 1.3–1.5, 2.1, 3.4–3.5 and 5.1–5.6 pages.
     • CLI usage, build, CI or migration documentation: later documentation PRs own those topics.
     • New snapshot tiers, formats, packet fields or runtime behavior beyond the implemented final contracts.
     • Treating the tiers as public Rust types or describing removed stores and supervisors as library services.
     • Making the public MappingTable part of the private space; only its mapper belongs to that reference code.
   • Approach: Edit the named design pages in place, preserving still-valid packet, ordering and time material while changing component ownership around it. Use the final public type names and one consistent responsibility split. Do not create replacement architecture pages, speculative tier APIs or implementation narratives for removed code.
   • Done when:
     • The named design pages consistently separate VMM, library and caller responsibilities.
     • The strict snapshot directory, envelope, device-configuration tiers, runtime labels, Ready and public MappingTable contracts are documented.
     • Restore packet 6, the new-network-policy order and host-clock correction remain present and accurate.
     • The repository Markdown-link check passes for the changed design pages.
   • Needs: SL2.14, in nvx-rs slimming 2.3.2: snapshots have one strict format, and a capture finishes into it #1102; SL2.15, in nvx-rs slimming 2.3.3: a VM restores from a snapshot, through a sans-I/O restore machine #1103; SL2.16, in nvx-rs slimming 2.3.3: a VM restores from a snapshot, through a sans-I/O restore machine #1103; SL2.18b, in nvx-rs slimming 2.3.3: a VM restores from a snapshot, through a sans-I/O restore machine #1103; SL4.3, in nvx-rs slimming 3.2.1: NVXC asks for a capture and activates a restore, and a blocking driver restores #1113; SL6.5b, in nvx-rs slimming 4.3.2: path rules are private to the CLI, and the export holds paths only #1125; SL7.4b, in nvx-rs slimming 2.4.2: activation holds no fence, and a capture is one guest call #1105; SL7.7b, in nvx-rs slimming 3.3.3: nvx-init captures and restores, and boots the new launches' layered roots #1117.
   • Estimate: 0 core lines (docs), no counted files.

3. SL6.10c: The default guest's design matches what it does.

   • Objective: The guest-runtime design matches nvx-init's final, intentionally small execution model. Readers can distinguish public guest contracts from NVX's internal reference space that nvx-init implements and understand the VM-wide isolation and process rules.
   • Contents: Design 4.*: one root, a VM-wide hostname, credentials per exec, init and helper priority, with no cgroups and no per-exec limits (the one limit is the RAM upper's cap), one process group per exec, which its end, cancellation, timeout and reset kill, helpers before the switch; the space as NVX's internal reference code that nvx-init implements. The mapping table's account is public (MappingTable), and the reference space's mapper binds the mappings that it hands out.
   • Scope:
     • Update only the existing doc/design/4-* guest-runtime overview and its 4.1–4.4 pages.
     • Describe one root and VM-wide hostname, credentials per execution, and one process group per execution.
     • Document init and helper priority, helpers starting before the root switch, and process-group termination on end, cancellation, timeout and reset.
     • State that there are no cgroups or per-execution limits; the RAM upper's cap is the sole limit.
     • Identify the space as NVX's internal reference code that nvx-init implements, while the public MappingTable supplies ordered mappings that its mapper binds.
   • Not in this PR:
     • New guest design pages or rewrites of host, device or lifecycle design chapters.
     • Making nvx-init's space interface public nvx API.
     • Per-execution roots, cgroups, namespaces, quotas or resource-control schemes: the final guest does not use them.
     • A second hostname, execution-specific network namespace or alternate helper lifecycle: no final caller needs them.
     • The detailed init-agent contract and worked examples: SL7.9 owns the guidelines.
   • Approach: Revise the existing design 4 pages in place around the final nvx-init behavior and remove descriptions of deleted execution machinery. Keep architectural boundaries here and leave procedural guidance to doc/guest-agent-guidelines.md. Use the public MappingTable name and call the mapper part of the internal reference space; do not invent generalized isolation abstractions.
   • Done when:
     • Design 4 describes the one-root, VM-wide-hostname and plain-process execution model.
     • Priority, helper ordering, credentials, process-group cleanup and the RAM-upper-only limit are stated consistently.
     • The pages distinguish public MappingTable from NVX's internal space and mapper that nvx-init implements.
     • The repository Markdown-link check passes for the changed design pages.
   • Needs: SL7.8b, in nvx-rs slimming 4.2.4: the exec engine, the process modules and the old layered init are gone #1123; SL6.11b, in nvx-rs slimming 4.2.4: the exec engine, the process modules and the old layered init are gone #1123; SL6.13b, in nvx-rs slimming 4.3.4: NVXC, the host's platform layer and the guest's space are private #1127.
   • Estimate: 0 core lines (docs), no counted files.

4. SL7.9: Init agents have guidelines.

   • Objective: Authors of init agents get one bounded contract for building a guest space, running executions, coordinating capture and completing restore. nvx-init serves as the worked example without turning its internal space implementation into public library API.
   • Contents: doc/guest-agent-guidelines.md. It opens with the split: nvx parses the contracts, captures the guest and drives a restore's activation, but builds no space and runs no executions; each init agent does both, and nvx enforces none of these obligations. The one exception is the time daemon, which TimeAbi::start_daemon forks. With nvx-init as the worked example, it covers the space; executions, whose children reset their priority, set their credentials, change to their working directory and exec, each in its own process group, which end, cancellation, timeout and reset kill; and priority, not limits (no cgroups and no per-exec limits; the one limit is the RAM upper's cap). For an init with concurrent executions, it gives the workspace contract: freeze(deadline) refuses new executions and stops those that run; a failure says whether it undid its work (undone), and the VM ends when it didn't; several workspaces freeze in order, all or nothing, and thaw in reverse: after a failure with undone, those already frozen thaw, and without it the VM ends and nothing thaws; and after_restore() renews what the executions need before Ready. nvx-init has no workspace: it refuses a capture while an execution runs, or kills the process groups and sweeps when the host asks. The transport rule: answer the capture request, then send nothing until capture returns; after Restored, take the session's reset and attach again; after Continued or Resumed, thaw the workspaces in reverse, where they exist, and report on the same session. The restore order: Activation::new, the space (apply, runtime filesystems, announcer, switch), after_restore where a workspace exists, complete, thaw where a workspace exists, then Ready. Failures: after Resumed, thaw and report; after MustEnd, start nothing and power off with its status. The replay rules forbid capturing live external connections or other state that can't be reused safely, and repeating irreversible effects, and require a runtime to repair its own randomness before it accepts work after a restore. It labels the space as NVX's internal reference code that nvx-init implements, not public API, and documents its inputs and rules: the root, the runtime filesystems, the view, the mappings, the helpers and the one switch. Its general snippets compile as public-API doc tests or examples; its space-interface snippets compile as a unit test of the private space, which the guidelines quote; the rustdoc of guest, snapshot and activation links to it; design 4.2 and 4.3 keep only the architecture and its boundaries. The mappings part gives MappingTable's contract: parts in order, a latch after a failure, and a complete table before any workload. The restore order includes the restore's own network policy, whose DNS and listeners the init applies, and whose announcer it starts and owns before Ready.
   • Scope:
     • Add only doc/guest-agent-guidelines.md, covering the rules listed in Contents and no others; state that nvx builds no space, runs no executions and enforces none of these obligations.
     • State the one exception, TimeAbi::start_daemon, and that there are no cgroups or per-execution limits; only the RAM upper is capped.
     • Trim doc/design/4.2-guest-agents-and-workload-model.md and doc/design/4.3-isolation-and-resource-model.md to architecture and boundaries.
     • Link the guidelines from the rustdoc of guest, snapshot and activation.
     • Compile general snippets as public-API doc tests or examples, and compile quoted space-interface snippets in a unit test of the private space.
   • Not in this PR:
     • Additional guideline documents, a workspace trait in nvx or enforcement code in the library.
     • Publishing the space module as stable API; it remains NVX's internal reference code that nvx-init implements.
     • Cgroups, namespaces, per-execution roots or limits other than the RAM upper's cap.
     • A new example harness: general snippets use public-API doc tests or examples, and a private-space unit test checks quoted snippets.
     • Rewriting design 4.2 and 4.3 beyond retaining architecture and boundaries.
   • Approach: Write one guideline page organized by ownership, space construction, executions, capture coordination, transport, restore, failures and replay. Use nvx-init as the single worked example and quote its private space signatures rather than abstracting them into traits. Keep snippets small and check them through public doc tests or examples and the space's unit test; do not add a documentation runner.
   • Done when:
     • doc/guest-agent-guidelines.md covers every rule listed in Contents, and design 4.2 and 4.3 retain only architecture and boundaries.
     • General snippets compile as public-API doc tests or examples, and a private-space unit test compiles the quoted space-interface snippets.
     • The rustdoc of guest, snapshot and activation links to the guidelines.
     • The repository Markdown-link check passes.
   • Needs: SL7.7b, in nvx-rs slimming 3.3.3: nvx-init captures and restores, and boots the new launches' layered roots #1117; SL5.1a, in nvx-rs slimming 4.1.1: public-API tests, and smoke tests on real VMs #1118.
   • Estimate: 0 core lines (docs), no counted files.

Tests. The guide's examples and the guidelines' general snippets compile as public-API doc tests or examples. A unit test compiles the private space-interface snippets quoted by the guidelines.

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