[Pedro Henrique Penna (ppenna)]

Part of #1131 (SL6.10h, "Users know what the release breaks"). Parent #1090, umbrella #1076.

What and why

The release of #1076 is not backward compatible with nvx 0.1.0-alpha.7, which crates.io published from e42b1795, and nothing told its users how to cross it. This PR adds only doc/migrate-from-alpha.7.md, one bounded, task-oriented guide, in SL6.10h's Scope:

• Upgrade: seven steps, each linking its section.
• Install pins: the exact Cargo requirement for the host's and the guest's sides, and the guest tools' install from the crate with the guest profile, as distribution.md#the-guest-tools documents it; and, since bundled is gone, how a program pins the runtime that the crate no longer bundles: a release whose SOURCE-MANIFEST.json passes contract::manifest_mismatches, labelled from its SHA256SUMS.
• Features and entry points: alpha.7's and the release's features (bundled removed with its build script, links and variables; cli and testing add only a hidden main; serde adds net::Ipv4Cidr; guest gains nvx-init), and the hidden main of each of the 12 binaries, as nvx-rs/public-api/linux.txt lists them.
• API crosswalk: 11 tables, from every alpha.7 item that the release removes, hides, makes private or changes, by its alpha.7 path, to its replacement, the caller's responsibility, or its removal. "No longer public" covers both an item that the release deleted and one that it keeps private for NVX's programs, which the review showed a reader cannot tell apart and need not.
• What the caller owns: durable state, paths and images, locking, I/O, timing, recovery, and the guest's space and executions, each against what alpha.7 did, linking library.md#what-the-caller-owns.
• Incompatible state: alpha.7's stores and records, template keys and snapshots, activation record v1, NVXC v1 and FEATURES, and the CLI's sandbox configurations (formats 1, 7 and 8, against format 10 with export_pins) and runtime records are refused, never converted; fresh state, linking run.md#upgrades and design 1.5.2 and 1.5.4. It also says how to remove a restored sandbox of an earlier build, which deprovision refuses (host: keep the export's pins in the CLI and paths only in ExportPlan (SL6.5b) #1549).
• Guests: /init's tokens (nvx_identity= and nvx_mode=; nvx_lifecycle= ignored; OpenVMM's identity tokens fail closed with NVX-WORKLOAD-ERROR, status 125, unless nvx_identity= agrees: SL6.3, host: delete the old config types and launch paths (SL6.3) #1530, and its design note on nvx-rs slimming 4.2.3: the old configs, the old launch code and bundled are gone #1122), nvx-init and the removed nvx-init-agent, plain-process executions, and the guest kernel (CONFIG_MAGIC_SYSRQ, SL6.11b, guest: delete the process modules and cgroups (SL6.11b) #1542, and the feature inventory).
• The nvx-rs CLI: the removed restore and cgroup options, the refused raw restores, the exec lock, streamed output, and the removed and added error codes.

It links the final library, CLI, build, distribution and design documents rather than repeat them.

Sources. The crosswalk comes from facts, not memory:

• alpha.7's public API: the crate that crates.io serves as nvx-0.1.0-alpha.7, whose .cargo_vcs_info.json records e42b17959360c1738a99cb3036137dfbf3d5bf96, listed with scripts/public_api.py's lister from its rustdoc JSON (Rust 1.95.0, --features cli,guest,host,serde,testing; bundled left out, since its build script downloads a release, and its one item, Artifacts::bundled, read from the source), diffed with nvx-rs/public-api/ at f5cc2aacfbf: 485 top-level items removed on Linux, 28 members removed from kept containers, and 14 signatures changed among the items that both keep (Process::wait, Process::open, report::read, HostConnection's methods, Activation::new, RootLayout::tokens, and the activation record's variants), each of which a row names.
• Both manifests, alpha.7's Cargo.toml.orig and the final nvx-rs/Cargo.toml; the alpha.7 and final sources for every disposition (removed or private) and for the CLI's formats, /init's tokens, the kernel configuration and the error codes.
• The group issues of nvx-rs slimming workstream: make nvx a library of mechanisms and value types #1076's phases 1 to 5 and their checkpoint and closing comments, among them nvx-rs slimming, phase 1.2: the guest tools and the managed agent leave the library #1078, nvx-rs slimming 1.1.2: one Cargo workspace, and the new crates' empty shells #1092–nvx-rs slimming 1.2.2: the managed agent lives in nvx-init #1096, nvx-rs slimming 3.1.1: the old CLI moves into nvx-cli unchanged #1106 and nvx-rs slimming 3.1.2: the cli feature is gone #1107, which the one-crate design superseded, so that the guide lists none of their crates.

The release version is 0.2.0-alpha.1, the first of a new series, as #1132 decided (#1132 (comment)). The guide pins it exactly: nvx = "=0.2.0-alpha.1", and default-features = false, features = ["guest"] with the same version for a guest init, since a caret requirement such as nvx = "0.2.0-alpha.1" also accepts every later pre-release of 0.2.0, which cargo update takes; and cargo install nvx --version 0.2.0-alpha.1, which cargo install reads as exactly that version. It also says that no requirement of alpha.7's selects the new series. Checked with Cargo: nvx = "0.1.0-alpha.7" resolves to 0.1.0-alpha.16 and nvx = "=0.1.0-alpha.7" to 0.1.0-alpha.7, and cargo install nvx --version 0.2.0-alpha.1 looks for =0.2.0-alpha.1 (which crates.io doesn't hold yet).

Coordination. The guide links documents and anchors that the other docs slices add, on their branches as of this PR: doc/library.md (SL6.10a, #1555), design 1.5.2 and 1.5.4 (SL6.10b, #1553), run.md#upgrades (SL6.10d, #1556), and distribution.md#the-guest-tools and build.md#release-packages (SL6.10e, #1546). So the link check fails on this branch alone until they merge, and passes with their documents (Validation). This PR merges after them, and rechecks every link then.

Size

	Core lines	Counted files
Estimate (#1131)	0 (docs)	none
Measured	0	0

Only Markdown: one new file, doc/migrate-from-alpha.7.md, 364 lines.

Old tests of the area

None changes: the PR changes no test, CI step or doc test, and the case matrix keeps every row.

Test changes

python scripts\check_test_changes.py --base origin/feature/nvx-refactor: 0 change(s) to existing tests, so no tests-modified.

Validation

local_gates.py --files doc/migrate-from-alpha.7.md (from dev, since this branch has no copy) selects test-changes, markdown-links, test-layout and nvx-cli (validate-nvx). I ran them from this branch's definitions on Windows:

Gate	Command	Result
test-changes	python scripts\check_test_changes.py --base origin/feature/nvx-refactor	Passed: 0 changes
test-layout	python scripts\check_test_layout.py	Passed
markdown-links	python scripts\check_markdown_links.py, on this branch alone	Failed, as expected: 10 links to the documents and anchors above, which the other docs slices add
markdown-links	python scripts\check_markdown_links.py --root <scratch worktree>: this commit with the documents of #1555, #1553, #1550, #1556, #1546 and #1540 at their current heads	Passed; a deliberately broken anchor in the guide failed it, so the check covers the guide's links
nvx-cli	The Windows step of validate-nvx (compileall, the unittest list, test_adversarial.py, test_hosts.py, and nvx.py ... --help), without its pip install	Passed: 1803 tests OK (73 skipped), 84 OK (11 skipped), 4 OK, and every --help

A code-review subagent checked every crosswalk row against the alpha.7 and final API listings, the diffs and both sources, and every other claim against the code and the linked documents. It found no omission. Its findings, folded into the commit: items that the release keeps private were marked removed, and the reverse (now "No longer public", defined once); /init stops a mismatched identity before it starts a workload or a guest agent, not before anything, since it has run nvx-time boot; NVX's executions model is nvx-init's, not every init's; and the programs are private but for their hidden entry points. Its remark that doc/usage.md and nvx-rs/README.md on the SL6.10a and SL6.10d branches still list the error codes that SL6.8c (#1552) deleted concerns those branches' rebases, not this guide, which follows the code.

Copilot's review asked the Locking row of What the caller owns to keep the snapshot's lock around the removal of a restore's openvmm/ view, and through a verified restore-ready event or exit; fixed in db5edc4. Its review of e787da2 asked the capture row to say that finish_capture writes key.bin and snapshot.json beside openvmm/ and returns only the checked key, and that the caller moves those three entries, not a CapturedSnapshot; fixed in 0c38d1c, and its review of that head has no open issue.

No VM or hypervisor gate applies to a documentation-only change; CI runs the rest once this PR is Ready.

[Copilot]

🟡 Changes recommended

The migration guide omits the requirement to hold the Linux snapshot lock through restore-view cleanup, which can interfere with concurrent restores’ file checks.

1 open issue

• Hold the snapshot lock through restore view cleanup · New

What changed in this PR

Adds a migration guide for alpha.7 users moving to NVX’s breaking library refactor, explaining API replacements and responsibilities transferred to callers.

Changes:

• Provides an upgrade checklist, version-pinning examples, and runtime artifact guidance.
• Maps changed APIs and features to replacements or caller-owned behavior.
• Documents incompatible state, fresh-state requirements, and guest and CLI changes.

File	Description
doc/​migrate-from-alpha.7.md	Adds the alpha.7 migration guide, linking to detailed library, runtime, and distribution documentation.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The migration-guide change has no active review issues.

No open issues 🎉

1 resolved since last review

• Hold the snapshot lock through restore view cleanup

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The migration guide incorrectly describes moving the whole VM directory; it should specify moving only key.bin, snapshot.json, and openvmm/ into a separate private snapshot directory to avoid outputs that Snapshot::open rejects.

1 open issue

• Store snapshot artifacts in a dedicated directory · New

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues remain for the documentation-only migration guide.

No open issues 🎉

1 resolved since last review

• Store snapshot artifacts in a dedicated directory

_{Review effort: Balanced}