nvx-rs: check the public API that adapters build on by esaurez · Pull Request #630 · microsoft/nvx

Enrique Saurez (esaurez) · 2026-10-20T07:14:29Z

Adapters build on the nvx crate in three configurations: protocol-only, without features; host-only, with host; and guest-only, with guest, for x86_64-unknown-linux-musl. This pull request makes CI flag every change to the public API that they build on, and adds a pull request template that asks about the adapter contract.

scripts/check_public_api.py lists the public API of each configuration on each of its targets with a pinned cargo-public-api release, 0.52.0, from the rustdoc JSON of the oldest nightly toolchain that the release's tests run with, nightly-2026-02-16. It compares the listings with the snapshots in tests/public-api, which record the current API as the baseline: protocol.txt, 867 lines; host.txt, 2985; and guest.txt, 1037. They record the API of this pull request's base, including the NVXS session of nvx-rs: add an application-neutral NVXS session #627, the process references of nvx-rs: add verified process references with event-driven exit waits #625, the store of nvx-rs: add the sandbox store, launch journal, and runtime identity #628, and the guest spawn API of nvx-rs: add a neutral guest spawn API and launch managed workloads through it #629. It lists the protocol-only and host-only configurations for both x86_64-unknown-linux-gnu and x86_64-pc-windows-msvc, which list the same API today. Items that only some targets list go to a snapshot of their own, NAME.TARGET.txt, so a host-specific API, such as the descriptor and handle allowlists that nvx-rs: share the VMM supervisor and the sandbox store #620 plans, stays possible and shows in review. Blanket implementations are left out; auto-trait and derived implementations stay, because adapters rely on them. cargo-public-api drops the defaults of generic parameters, as in pub type nvx::Result<T, E> for Result<T, E = Error>, so the check appends a line for each default of a public item, read from the rustdoc JSON that the listing builds, with each item ID replaced by the item's qualified path so that a default that names another type through the same spelling changes the snapshot, and, because it also renders a required and a provided trait item alike, a line for each item of a public trait that says whether the trait provides it. The check fails with exit status 2 if that JSON reaches other modules than the listing.
The nvx-rs job runs the check on Linux through check-nvx-rs. cargo-public-api publishes no binaries, so the job builds it, and dev pushes cache the build under the hash of the script, as the other caches do. The check exits with 1 and annotates the snapshots when the API changed, and with 2 when it cannot list the API. The job summary reports the size of each listing.
.github/pull_request_template.md asks: "Does this change the adapter contract (public API, behavior, persisted formats or wire)? If so, add a migration note and conformance cases."
tests/public-api/README.md describes the snapshots, how to update them, and how to move the pins. doc/ci.md, doc/contribute.md, doc/project-structure.md, and the Copilot instructions describe the check and the template.

Why a committed cargo-public-api snapshot rather than cargo-semver-checks against a Git baseline:

A snapshot flags every change, additions included. cargo-semver-checks reports only the breaking changes that it has lints for, so an addition to the adapter-facing API would pass without review.
The snapshot's diff shows each change in the pull request, and the snapshot keeps the current API, the baseline of the next change, in the repository.
cargo-semver-checks accepts a deliberate breaking change only with a version bump, which nvx makes when it releases rather than in each change. Here, the reviewed snapshot update in the same pull request accepts it.
It needs neither Git history nor a second build of a baseline revision.

Its paths select neither the microVM nor the OpenVMM test suites (run-tests=false).

Part of #620. Refs #535.

Validation

Rebased onto dev at b47a9f8, after the package was renamed to nvx (#650): the crate is now named nvx in the script's output and the documentation, while the nvx-rs/ directory, the nvx-rs job, and check-nvx-rs keep their names. The snapshots were regenerated there; compared with the previous base they add nvx::host::store from #628 and nvx::guest::spawn from #629, and record the new field of SessionError::SequenceOverflow from #639. I ran the checks below again on the rebased commit.

Windows 11; nothing here boots a VM:

python scripts/check_public_api.py passes against the snapshots. Controls: a new public function fails the check with exit status 1 in all three configurations; a Windows-only public function fails it until --update writes protocol.x86_64-pc-windows-msvc.txt and host.x86_64-pc-windows-msvc.txt, leaving the shared snapshots unchanged; once the function is gone, the check reports both target snapshots as obsolete and --update removes them; a stray snapshot fails the check.
A default-only change fails the check: adding pub struct Control<T = u8>, updating the snapshots, and then changing only the default to u16 fails it in all three configurations, with a diff only on the default lines. Giving OutputSink::write a default body fails it with a diff only on that method's line.
The snapshot-format test passes with the snapshots converted to CRLF, as a checkout may convert them, and fails with one stray carriage return.
Ruff lint and format, Pyright strict against Linux and Windows (0 errors), and scripts/check_markdown_links.py.
python -m unittest scripts/test_public_api.py scripts/test_nvx_tools.py scripts/test_markdown_links.py scripts/test_tool_versions.py: 623 tests pass.
python scripts/nvx.py classify-ci-changes on this commit's paths: run-tests=false, run-workloads=true, both OpenVMM suites false, for pull requests and pushes.

WSL Ubuntu, Python 3.10.12, no hypervisor:

python3 scripts/check_public_api.py --install-tools --root DIR from scratch: the minimal nightly profile, the three targets, and the cargo-public-api build, in 86 s.
The check against the snapshots generated on Windows passes, including the cross-target x86_64-pc-windows-msvc listing, in under 40 s from a cold target directory and 14 s warm, and writes the job summary under GITHUB_ACTIONS and GITHUB_STEP_SUMMARY.
python3 -m unittest scripts/test_public_api.py: 31 tests pass.

Left to CI: the check on a GitHub-hosted Linux runner, which builds cargo-public-api because only dev pushes save its cache, and the rest of the matrix.

Adapter contract

Does this change the adapter contract (public API, behavior, persisted formats or wire)? If so, add a migration note and conformance cases.

No. This pull request records the current public API and adds the check; it changes no API, behavior, persisted format, or wire.

Copilot

🟡 Changes recommended

The snapshot format test rejects valid CRLF checkouts and breaks Windows validation when automatic line-ending conversion is enabled.

1 open issue

Normalize CRLF before validating snapshot format · New

What changed in this PR

Adds public-API snapshot checks for the nvx-rs configurations used by adapters, supporting the shared-runtime contract work in #620 and #535.

Changes:

Adds pinned API-listing tools, snapshots, tests, and CI integration.
Introduces an adapter-contract question and contributor guidance.
Includes the independent runtime adapter and CI hooks from stacked PR #626.

File	Description
`tests/runtime-adapter/tests/independent_build.rs`	Checks independent builds, feature isolation, and static linkage.
`tests/runtime-adapter/src/lib.rs`	Reports runtime contract versions.
`tests/runtime-adapter/src/bin/runtime-adapter-host.rs`	Adds the host skeleton.
`tests/runtime-adapter/src/bin/runtime-adapter-guest.rs`	Adds the guest skeleton.
`tests/runtime-adapter/README.md`	Documents adapter configurations and checks.
`tests/runtime-adapter/Cargo.toml`	Defines independent adapter features and dependencies.
`tests/runtime-adapter/Cargo.lock`	Locks adapter dependencies.
`tests/public-api/README.md`	Documents snapshot checks and updates.
`tests/public-api/protocol.txt`	Records the protocol API baseline.
`tests/public-api/guest.txt`	Records the guest API baseline.
`scripts/test_public_api.py`	Tests API checking and snapshot handling.
`scripts/test_nvx_tools.py`	Tests CI integration and change classification.
`scripts/nvx_tools/ci.py`	Classifies adapter changes as microVM test inputs.
`scripts/check_public_api.py`	Generates and compares API listings.
`doc/project-structure.md`	Describes new tools and test directories.
`doc/contribute.md`	Adds adapter-contract contribution guidance.
`doc/ci.md`	Documents adapter and public-API checks.
`.gitignore`	Excludes adapter build output.
`.github/workflows/run-nvx-microvm-tests.yml`	Adds adapter scenario hooks.
`.github/pull_request_template.md`	Asks about adapter-contract changes.
`.github/copilot-instructions.md`	Adds adapter and snapshot validation guidance.
`.github/actions/validate-nvx/action.yml`	Runs public-API unit tests.
`.github/actions/check-nvx-rs/action.yml`	Checks adapter configurations and API snapshots.

_{Review effort: Balanced}

Copilot

🟢 Approval recommended

No unresolved blocking defects were identified in the API checker, adapter validation, or CI integration.

No open issues 🎉

1 resolved since last review

Normalize CRLF before validating snapshot format

_{Review effort: Balanced}

Copilot

🟢 Approval recommended

No unresolved defects were identified in the checker, snapshots, tests, documentation, or CI integration.

No open issues 🎉

_{Review effort: Balanced}

Copilot

🟡 Changes recommended

The snapshot representation omits generic defaults, leaving adapter-facing API changes undetected.

1 open issue

Snapshots omit default generic arguments · New

_{Review effort: Balanced}

Copilot

🟡 Changes recommended

Generic-default normalization loses resolved type identity, allowing some API changes to pass undetected.

1 open issue

Resolve default type identities before removing IDs · New

1 resolved since last review

Snapshots omit default generic arguments

_{Review effort: Balanced}

Adapters build on the nvx crate in three configurations: protocol-only, host-only, and guest-only. The nvx-rs job now lists the public API of each configuration on each of its targets with a pinned cargo-public-api release and nightly toolchain, and compares the listings with snapshots committed in tests/public-api, so that every change to the API, additions included, shows in review. Items that only some targets list get a snapshot of their own, so that a host-specific API remains possible. The check runs on Linux, and dev pushes cache the build of cargo-public-api. A pull request template asks whether a change touches the adapter contract and, if it does, for a migration note and conformance cases. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: b901ceb9-fff0-4a76-9f55-a4b07d9c0633

cargo-public-api leaves out the defaults of generic parameters: it lists `pub type nvx::Result<T, E>` for `Result<T, E = Error>`, so a change to a default passed the check. The check now reads the rustdoc JSON that each listing builds, resolves the public path of each item from the crate root through its modules and re-exports, and appends a line for each default, with the default type as its rustdoc JSON without item IDs. It fails with a tooling error when that JSON reaches other modules than the listing, which would mean that it is stale. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: b901ceb9-fff0-4a76-9f55-a4b07d9c0633

A default records its type's rustdoc JSON, whose item IDs change between builds. Dropping them lost which item an imported name such as `Error` resolves to, so a change of the import alone passed the check. Each ID is now replaced by the item's qualified path: the first public path of an item of the crate, or the path that rustdoc records for any other. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: b901ceb9-fff0-4a76-9f55-a4b07d9c0633

Copilot

🟡 Changes recommended

The gate misses required-versus-provided trait-method changes that can break downstream implementations.

1 open issue

Track trait method body status in pinned renderer snapshots · New

1 resolved since last review

Resolve default type identities before removing IDs

_{Review effort: Balanced}

cargo-public-api renders a required and a provided trait item alike, so giving a trait method a default body, or removing one, which breaks the implementations that leave the method out, passed the check. For each item of a public trait, the check now records from the rustdoc JSON whether the trait provides it: a method with a body, or an associated constant or type with a default, together with that default. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: b901ceb9-fff0-4a76-9f55-a4b07d9c0633

Copilot

🟡 Changes recommended

The gate can miss changed trait-associated bindings and breaking changes to public-struct constructibility.

2 open issues

1 resolved since last review

Track trait method body status in pinned renderer snapshots

_{Review effort: Balanced}

+    items = {target: listings[target].splitlines() for target in configuration.targets}
+    first, *others = configuration.targets
+    shared = Counter(items[first])
+    for target in others:
+        shared &= Counter(items[target])


+            f"the rustdoc JSON for {target} does not match the {configuration.name} "
+            f"listing: its modules differ by {sorted(listed ^ reached)}"
+        )
+    return items + lines(generic_defaults(document) + trait_item_defaults(document))


Enrique Saurez (esaurez) · 2026-10-21T00:42:23Z

Closing: the public-API gate is being dropped from the plan.

Copilot AI balanced review requested due to automatic review settings October 20, 2026 07:14

Enrique Saurez (esaurez) mentioned this pull request Oct 20, 2026

tests: add the runtime adapter and run its checks in CI #626

Merged

Copilot started reviewing on behalf of Enrique Saurez (esaurez) October 20, 2026 07:15

View session

Copilot AI reviewed Oct 20, 2026

View reviewed changes

Comment thread scripts/test_public_api.py Outdated

Copilot AI balanced review requested due to automatic review settings October 20, 2026 07:21

Enrique Saurez (esaurez) force-pushed the esaurez/a1-api-gate-20261019 branch from e8a050c to 09f0167 Compare October 20, 2026 07:21

Copilot started reviewing on behalf of Enrique Saurez (esaurez) October 20, 2026 07:22

View session

Copilot AI reviewed Oct 20, 2026

View reviewed changes

Enrique Saurez (esaurez) marked this pull request as ready for review October 20, 2026 07:29

Pedro Henrique Penna (ppenna) mentioned this pull request Oct 20, 2026

nvx-rs: run the guest-binary tests' nvx-time hooks with one helper #637

Merged

Copilot AI balanced review requested due to automatic review settings October 20, 2026 15:39

Enrique Saurez (esaurez) force-pushed the esaurez/a1-api-gate-20261019 branch from 09f0167 to b0884b2 Compare October 20, 2026 15:39

Copilot started reviewing on behalf of Enrique Saurez (esaurez) October 20, 2026 15:39

View session

Copilot AI reviewed Oct 20, 2026

View reviewed changes

Enrique Saurez (esaurez) requested a review from Pedro Henrique Penna (ppenna) October 20, 2026 15:59

Pedro Henrique Penna (ppenna) assigned Enrique Saurez (esaurez) Oct 20, 2026

This was referenced Oct 20, 2026

nvx-rs: add a guest mapping API with explicit export and target roots #652

Merged

nvx-rs: add caller-owned guest cgroup and child-status APIs #655

Merged

Copilot AI balanced review requested due to automatic review settings October 20, 2026 23:33

Enrique Saurez (esaurez) force-pushed the esaurez/a1-api-gate-20261019 branch from b0884b2 to 367b6da Compare October 20, 2026 23:33

Copilot started reviewing on behalf of Enrique Saurez (esaurez) October 20, 2026 23:34

View session

Copilot AI reviewed Oct 20, 2026

View reviewed changes

Comment thread scripts/check_public_api.py

Copilot AI balanced review requested due to automatic review settings October 20, 2026 23:52

Copilot started reviewing on behalf of Enrique Saurez (esaurez) October 20, 2026 23:52

View session

Copilot AI reviewed Oct 20, 2026

View reviewed changes

Comment thread scripts/check_public_api.py Outdated

Enrique Saurez and others added 3 commits October 20, 2026 17:00

Copilot AI balanced review requested due to automatic review settings October 21, 2026 00:04

Enrique Saurez (esaurez) force-pushed the esaurez/a1-api-gate-20261019 branch from f2973d6 to d942e15 Compare October 21, 2026 00:04

Copilot started reviewing on behalf of Enrique Saurez (esaurez) October 21, 2026 00:04

View session

Copilot AI reviewed Oct 21, 2026

View reviewed changes

Comment thread scripts/check_public_api.py Outdated

Copilot AI balanced review requested due to automatic review settings October 21, 2026 00:20

Copilot started reviewing on behalf of Enrique Saurez (esaurez) October 21, 2026 00:21

View session

Copilot AI reviewed Oct 21, 2026

View reviewed changes

Enrique Saurez (esaurez) closed this Oct 21, 2026

Enrique Saurez (esaurez) deleted the esaurez/a1-api-gate-20261019 branch October 21, 2026 00:44

This was referenced Oct 21, 2026

ci: classify microVM tests, benchmarks, and artifact builds separately #712

Merged

ci: classify the microVM tests, benchmarks, guest artifacts, and OpenVMM binaries separately #698

Closed

Navigation Menu

Repository navigation

nvx-rs: check the public API that adapters build on - #630

nvx-rs: check the public API that adapters build on#630
Enrique Saurez (esaurez) wants to merge 4 commits into
devfrom
esaurez/a1-api-gate-20261019

Enrique Saurez (esaurez) commented Oct 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Enrique Saurez (esaurez) commented Oct 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Enrique Saurez (esaurez) commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Validation

Adapter contract

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Enrique Saurez (esaurez) commented Oct 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Enrique Saurez (esaurez) commented Oct 20, 2026 •

edited

Loading