Repository navigation
guest: hide the guest's space as internal reference code - #1262
Conversation
This pull request changes existing testsIt modifies or removes 2 existing test asset(s), listed below. Review each with care: a change to a test can hide a regression that the test caught. See doc/contribute.md#changes-to-existing-tests. Test code
Relocated unchanged: 68; added: 2. Compared the merge base |
There was a problem hiding this comment.
🟢 Approval recommended
There are no active review issues requiring resolution before approval.
No open issues 🎉
What changed in this PR
Implements SL7.0 of #1104 by separating NVX’s internal guest-space reference code from its documented public API. Existing paths remain usable, while mapping values and MappingTable stay publicly documented.
Changes:
- Moves the mapper and its tests into a hidden submodule, preserving existing paths through re-exports.
- Hides root, guest GPT, and activation-application APIs without changing their implementations.
- Updates documentation and the Linux API snapshot to reflect the supported public surface.
| File | Description |
|---|---|
nvx-rs/src/lib.rs |
Distinguishes public guest APIs from internal reference code. |
nvx-rs/src/guest/root/share.rs |
Removes a documentation link to the hidden root API. |
nvx-rs/src/guest/root.rs |
Documents internal status and clarifies bootstrap links. |
nvx-rs/src/guest/mod.rs |
Hides root and GPT modules and describes the public surface. |
nvx-rs/src/guest/mappings/table.rs |
Updates documentation and examples to avoid hidden APIs. |
nvx-rs/src/guest/mappings/mapper/tests/privileged.rs |
Relocates privileged tests and updates imports and run instructions. |
nvx-rs/src/guest/mappings/mapper/tests.rs |
Relocates mapper tests and adjusts imports. |
nvx-rs/src/guest/mappings/mapper.rs |
Houses the moved mapper as internal reference code. |
nvx-rs/src/guest/mappings.rs |
Keeps public mapping contracts and hidden compatibility re-exports. |
nvx-rs/src/guest/gpt.rs |
Documents the guest GPT module’s internal status. |
nvx-rs/src/guest/entry.rs |
Removes documentation links to hidden guest-space APIs. |
nvx-rs/src/guest/clone/activation/apply.rs |
Hides application APIs while keeping constants documented. |
nvx-rs/src/guest/clone/activation.rs |
Removes documentation links to hidden activation application. |
nvx-rs/src/guest/clone.rs |
Separates hidden application exports from public activation APIs. |
nvx-rs/README.md |
Explains public contracts and internal guest-space boundaries. |
nvx-rs/public-api/linux.txt |
Records hidden items and the new hidden mapper paths. |
Review effort: Balanced
ab4c02a to
83da90b
Compare
The guest's space, the root that an init assembles and what it mounts
in it, is each init's own. NVX's space stays usable for its current
users, but stops presenting itself as supported public API.
guest::mappings splits: the mapper moves with its tests to the hidden
guest::mappings::mapper, whose public items keep their paths through
hidden re-exports, and the module keeps its docs, the mapping values
and MappingTable, which stay public. guest::{root, gpt} and the
activation's application (apply, Applied, RootTemplate, ApplyError,
AppliedTeardownError, NetworkError) become hidden too. Each says that
it is unstable internal reference code, which becomes crate-private
once nothing outside NVX uses it, and the public docs stop linking to
hidden items. Nothing else changes.
Part of #1104.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 52656ee0-ecc4-4cfd-987b-9b71e72f0f50
Copilot-Session: 383380be-1df9-4f25-bf77-97c24b2eb591
83da90b to
6c6b40f
Compare
|
Neuro-formal verification (NFV) selects nontrivial properties from PR intent and source, tries verification, then tries refutation. NFV: 0 refuted, 8 verified in PR #1262PR head These are results for translated models under their stated assumptions, not proofs of source-code correctness or confirmed source bugs. refuted: 0 · verified: 8 · resources exhausted: 0 · type-check/audit failure: 2 P1Intended property: Invalid proposed property Outcome: type-check/audit failure DiagnosticInferred property lacks an exact captured-source quote P2Inferred property: For any mappings slice, apply_with attempts mappings in order; it returns Ok for an empty slice or after all attachments succeed, but stops at the first attachment failure and returns ApplyError containing that mapping’s zero-based index and error without attempting later mappings. Outcome: verified The property was verified for the translated model. Verification detailsCaptured source (inferred property): for (entry, mapping) in mappings.iter().enumerate() Assumptions: No additional input restrictions. Environment models: Models one attach_with call using an abstract Result token: zero is success and a nonzero token identifies the returned MappingError. Checked property: ensures (|attachmentResults| == 0 ==> ok && |attempted| == 0) && |attempted| == |attachmentResults| && (ok <==> (forall k :: 0 <= k < |attachmentResults| ==> attachmentResults[k] == 0)) && (ok ==> (forall k :: 0 <= k < |attempted| ==> attempted[k])) && (!ok ==> 0 <= errorEntry < |attachmentResults| && error == attachmentResults[errorEntry] && error != 0 && (forall k :: 0 <= k < errorEntry ==> attachmentResults[k] == 0) && (forall k :: 0 <= k < |attempted| ==> attempted[k] == (k <= errorEntry)))Evidence: The full verified Dafny is retained in the linked run artifact. P3Inferred property: For any sequence returned by unmount_with, teardown_with returns Ok exactly when the sequence is empty; otherwise it returns TeardownError containing every UnmountFailure in the same order, with only the associated indices discarded. Outcome: verified The property was verified for the translated model. Verification detailsCaptured source (inferred property): if failures.is_empty() { Assumptions: The two input sequences encode the index and failure components of the same sequence of pairs returned by unmount_with. Environment models: Represents the environment-dependent sequence returned by unmount_with using explicit index and UnmountFailure-token inputs. Checked property: ensures (ok <==> |unmountFailures| == 0) && (|unmountFailures| != 0 ==> !ok && teardownFailures == unmountFailures)Evidence: The full verified Dafny is retained in the linked run artifact. P4Inferred property: For any result from attach, bind_with returns a Mapped containing that successful mount ID and an owned copy of mapping's target; on failure, it returns the failure's MappingError. Outcome: verified The property was verified for the translated model. Verification detailsCaptured source (inferred property): .map(|mount| Mapped { Assumptions: When attach succeeds, its mount ID is representable as Rust's u64. Environment models: Represents attach's supplied Result outcome, preserving its successful u64 mount ID or its failure's MappingError.; Returns an owned sequence with the same contents as mapping.target().to_path_buf(). Checked property: ensures (attachSucceeded ==> (resultSucceeded && resultMount == attachMount && resultTarget == mappingTarget)) && (!attachSucceeded ==> (!resultSucceeded && resultError == attachFailureError))Evidence: The full verified Dafny is retained in the linked run artifact. P5Inferred property: For any attachment attempt, if the mapper is already latched it returns Latched without attempting or recording the mapping. Otherwise, success appends the target and returned mount to the tracked mappings; any target refusal or attachment failure latches the mapper, returns that error, and records the failed attachment as stray exactly when the failure supplies a stray tree. Outcome: verified The property was verified for the translated model. Verification detailsCaptured source (inferred property): unless the mapper is latched; a refusal or failure latches it, and the mapper Assumptions: The parallel target and mount sequences represent the same tracked mapping records.; There is one target-containment result for each existing mapping.; Existing and newly returned mount identifiers fit Rust's u64 type. Environment models: Refuses a reserved target or a target contained within an earlier mapping, and otherwise succeeds.; Returns an explicitly supplied normal attachment outcome, including the mount on success or the error and optional stray tree on failure. Checked property: ensures (initialLatched ==> !resultOk && resultError == -1 && latched && !attachAttempted && mappedTargetsOut == mappedTargets && mappedMountsOut == mappedMounts && hasStray == initialHasStray && strayTarget == initialStrayTarget && strayTree == initialStrayTree) && (!initialLatched && !reservedHolds && (forall i | 0 <= i < |within| :: !within[i]) && attachOk ==> resultOk && !latched && attachAttempted && mappedTargetsOut == mappedTargets + [target] && mappedMountsOut == mappedMounts + [attachMount] && hasStray == initialHasStray && strayTarget == initialStrayTarget && strayTree == initialStrayTree) && (!initialLatched && (reservedHolds || (exists i | 0 <= i < |within| :: within[i])) ==> !resultOk && resultError == checkError && latched && !attachAttempted && mappedTargetsOut == mappedTargets && mappedMountsOut == mappedMounts && !hasStray) && (!initialLatched && !reservedHolds && (forall i | 0 <= i < |within| :: !within[i]) && !attachOk ==> !resultOk && resultError == attachError && latched && attachAttempted && mappedTargetsOut == mappedTargets && mappedMountsOut == mappedMounts && hasStray == attachHasStray && (attachHasStray ==> strayTarget == target && strayTree == attachTree))Evidence: The full verified Dafny is retained in the linked run artifact. P6Inferred property: For any mapper state, unmount_with first attempts to detach an existing stray mapping, then attempts every mapped mount in reverse attachment order; it clears both stored collections regardless of failures and returns exactly the failures in attempt order, assigning the stray index mapped.len() and each ordinary failure its original attachment index. Outcome: verified The property was verified for the translated model. Verification detailsCaptured source (inferred property): Detaches the mapping that a rename moved, if the mapper failed to detach it, then unmounts Assumptions: There is one abstract unmount outcome, returned error, and absolute target for each stored mapping. Environment models: Produces mapped indices in reverse attachment order for the modeled loop interval.; Selects failed mapped indices in reverse attempt order.; Selects the absolute targets belonging to failed mapped unmount attempts.; Selects the errors belonging to failed mapped unmount attempts.; Represents the environment-dependent result of attempting to detach the stray tree.; Represents whether the captured unmount operation succeeds and, on failure, which MappingError it returns.; Represents the uncaptured absolute-path conversion used when constructing an UnmountFailure.; Represents wrapping a detach error as a system error for the Unmount step. Checked property: ensures attemptIndices == (if hasStray then [|mapped|] else []) + ReverseAttemptRange(|mapped|, 0) && mappedRemaining == [] && !strayRemaining && failureIndices == (if hasStray && detachFails then [|mapped|] else []) + FailureIndexRange(ordinaryFails, |mapped|, 0) && failureTargets == (if hasStray && detachFails then [absoluteStrayTarget] else []) + FailureTargetRange(ordinaryFails, absoluteMappedTargets, |mapped|, 0) && failureErrors == (if hasStray && detachFails then [straySystemError] else []) + FailureErrorRange(ordinaryFails, ordinaryErrors, |mapped|, 0)Evidence: The full verified Dafny is retained in the linked run artifact. P7Inferred property: After moving the tree succeeds, `attach` returns its mount ID only when locating the target reports that same ID as a mount root. Otherwise it attempts detachment: successful detachment reports `Moved { mounted: false }`, while failed detachment reports `Moved { mounted: true }` and preserves the tree as a stray. Outcome: verified The property was verified for the translated model. Verification detailsCaptured source (inferred property): // The tree keeps the mount busy, so only a detach takes it off wherever it went. Assumptions: The mount ID obtained from the tree status is a Rust u64 value.; The mount ID reported while locating the target is a Rust u64 value. Environment models: Supplies whether open_source succeeds; its descriptor and kind are irrelevant to the selected property.; Supplies source-status success, mount-root status, and whether its kind converts to a mapping kind.; Supplies whether walk returns a destination.; Supplies whether the kernel opens or clones the source tree.; Supplies whether setting the requested tree attributes succeeds.; Supplies whether tree status succeeds and the mount ID it reports.; Supplies whether moving the tree to the destination succeeds.; Supplies locate's success and the mount ID and mount-root flag from the located target status.; Supplies whether detaching the moved tree succeeds. Checked property: ensures moved ==> ((outcome == 0 ==> returnedMount == mountInput && locateOkInput && locateMountInput == mountInput && locateMountRootInput) && (!(locateOkInput && locateMountInput == mountInput && locateMountRootInput) ==> detachAttempted && ((detachOkInput && outcome == 3 && !mounted && !stray) || (!detachOkInput && outcome == 4 && mounted && stray))))Evidence: The full verified Dafny is retained in the linked run artifact. P8Inferred property: For any relative target, check_target returns Reserved when the target is reserved; otherwise it returns Overlap naming the first existing mapped target equal to or beneath that target, and returns success if no such mapping exists. Outcome: verified The property was verified for the translated model. Verification detailsCaptured source (inferred property): if self.reserved.holds(target) { Assumptions: The encoded mapping boundary sequence contains an initial boundary.; The first mapped target starts at the beginning of mappedBytes.; The final mapping boundary is the end of mappedBytes.; Every encoded mapping boundary lies within mappedBytes.; Mapping boundaries are ordered according to Mapper.mapped.; Each target element represents an unsigned path byte.; Each stored target element represents an unsigned path byte.; The supplied target is represented as a relative byte path.; Each nonempty stored mapped target is represented as a relative byte path. Environment models: Returns the Unix byte representation supplied for a path without changing it.; Returns true exactly when inner equals outer or begins with outer followed by a slash.; Represents absolute(&mapped.target) by prefixing the stored relative target bytes with '/'. Checked property: ensures (reservedHolds ==> resultStatus == 1) && (!reservedHolds ==> ((resultStatus == 0 && overlapIndex == -1 && overlapTarget == [] && (forall i | 0 <= i && i + 1 < |mappedEnds| :: !WithinSpec(mappedBytes[mappedEnds[i]..mappedEnds[i + 1]], target))) || (resultStatus == 2 && 0 <= overlapIndex && overlapIndex + 1 < |mappedEnds| && overlapTarget == AbsoluteBytes(mappedBytes[mappedEnds[overlapIndex]..mappedEnds[overlapIndex + 1]]) && WithinSpec(mappedBytes[mappedEnds[overlapIndex]..mappedEnds[overlapIndex + 1]], target) && (forall j | 0 <= j && j < overlapIndex :: !WithinSpec(mappedBytes[mappedEnds[j]..mappedEnds[j + 1]], target)))))Evidence: The full verified Dafny is retained in the linked run artifact. P9Inferred property: For any source and path, open_source treats an empty path as "." and otherwise uses the supplied path, opens it beneath the source without crossing mounts, obtains its status, and returns the descriptor with the corresponding directory/file Kind; path conversion, opening, or status failures become System errors at Step::Source, while any other file kind yields SourceKind. Outcome: verified The property was verified for the translated model. Verification detailsCaptured source (inferred property): `openat2` resolves no empty path, so the root itself is `.` beneath it Assumptions: No additional input restrictions. Environment models: Path conversion preserves the selected path when successful; its success and error are explicit environment inputs.; The beneath-open operation uses its supplied arguments; its descriptor or error is an explicit environment result.; Status queries the opened descriptor and returns an explicit success, file-kind, or error result.; Directory and regular-file status kinds map to the corresponding Kind; every other status kind is rejected.; A system-call error is represented as MappingError::System at Step::Source with the same modeled error value. Checked property: ensures usedPath == (if |path| == 0 then [46] else path) && conversionCalled && openCalled == conversionOkIn && statusCalled == (conversionOkIn && openOkIn) && (openCalled ==> openDirectory == source && openPath == usedPath && openFlags == 1 && openMode == 0 && !crossMounts) && (statusCalled ==> statusDescriptor == openedDescriptorIn) && (!conversionOkIn ==> resultTag == 1 && resultStep == 0 && resultError == conversionErrorIn) && (conversionOkIn && !openOkIn ==> resultTag == 1 && resultStep == 0 && resultError == openErrorIn) && (conversionOkIn && openOkIn && !statusOkIn ==> resultTag == 1 && resultStep == 0 && resultError == statusErrorIn) && (conversionOkIn && openOkIn && statusOkIn && (statusKindIn == 0 || statusKindIn == 1) ==> resultTag == 0 && resultDescriptor == openedDescriptorIn && resultKind == statusKindIn) && (conversionOkIn && openOkIn && statusOkIn && statusKindIn != 0 && statusKindIn != 1 ==> resultTag == 2)Evidence: The full verified Dafny is retained in the linked run artifact. P10Inferred property: For terminating tree and path iterators, `new` succeeds exactly when every input is a valid canonical absolute target; on success it stores both sequences in order with the leading root removed, and if any input is invalid it returns `InvalidMapping::Target` instead of a `Reserved` value. Outcome: type-check/audit failure Diagnostic'NoneType' object is not iterable
Add this agentic workflow to your repoTo install this agentic workflow, run |
Part of #1104: SL7.0, the guest's space becomes NVX's internal reference code, not public API. Stacked on #1261, which adds the public-API snapshots.
What changes
The guest's space stays usable for its current users, but stops presenting itself as supported public API:
guest/mappings.rsmoves withgit mvtoguest/mappings/mapper.rs, which keeps the mapper:Mapper,TargetRoot,SourceRoot,Reserved,bind,Step,MappingError,ApplyError,UnmountFailure,TeardownErrorand its kernel seam. The moved file changes only in its imports, visibility and doc links;git diff -B -Mor--color-movedshows the move. Its tests move with it, frommappings/tests.rsandmappings/tests/privileged.rstomappings/mapper/tests.rsandmappings/mapper/tests/privileged.rs, with the fake kernel thatguest::root::testsre-exports and their test-onlyMappedandTeardownErrormethods.guest/mappings.rsfacade takes back the module's docs and the mapping values,Mapping,Access,Kind,InvalidMappingandMAX_PATH_BYTES, withMappingTable,TableErrorandRefusal, which stay public and documented. It re-exports the mapper's public items under#[doc(hidden)], so their paths keep working.guest::{root, gpt},guest::mappings::mapperand the activation'sapply,Applied,RootTemplate,ApplyError,AppliedTeardownErrorandNetworkErrorare#[doc(hidden)], and each says that it is unstable internal reference code that becomes crate-private once nothing outside NVX uses it.guestmodule's docs list the public guest surface, and the public docs stop linking to hidden items:MappingTable's example mounts its mappings through a function of the caller's instead of the hidden mapper.Everything else stays as it was, visible and unchanged:
guest::entry; the activation inguest::clone,Activationand its states, withMACHINE_ID_FILEandRESOLVER_FILE; and the mapping values withMappingTable,TableErrorandRefusal.No implementation changes: nvx-init, the runtime adapter and users pinned to the API-ready commit compile and behave as before.
Size
Against the base, #1261's head:
nvxa library of mechanisms and value types #1076's rule: 146 core lines in 1 counted file: the new facade's 143 and the moved mapper's 3 import lines. The files that only hide items,clone.rs(5),clone/activation/apply.rs(6) andguest/mod.rs(2), count like a move: markers, hidden re-exports and the imports that they force.git diff -B -Mdoes: 159 core lines in 5 files, under the 600-line limit and at the five-file cap, before the rule leaves out the files that only hide items. A plain line count gives 807 core lines in the same 5 files, since it reads the new facade at the old path as a rewrite of the whole old file.git diff -B -M --stat:nvx-rs/src/guest/{mappings.rs => mappings/mapper.rs} | 245 ++----The issue estimates 350 core lines in 4 counted files, with a stop at 600.
Public API snapshot
python scripts/public_api.py --updatechangednvx-rs/public-api/linux.txtonly;windows.txtis unchanged, andpython scripts/public_api.pypasses.The supported public API is unchanged: no path is removed, no visible line is added, and 3096 of the base's 3426 lines stay as they were, among them the 50 of the mapping values,
MappingTable,TableErrorandRefusal. Every other change marks an item of the families that this change hides on purpose, the space's reference code:330 lines gain
(hidden): 215 ofnvx::guest::root, 9 ofnvx::guest::gpt, 52 of the activation's application innvx::guest::clone, and 54 of the mapper's items at their oldnvx::guest::mappingspaths, which hidden re-exports keep. For example:55 lines are new, all hidden: the
nvx::guest::mappings::mapperpath and its items.The 55 new lines
Tests
Every test of the area is kept: none is rewritten or retired. The mapper's 23 tests and 10 privileged tests move with it, and change only in their imports, which gain the 3 items that the mapper no longer brings into scope, and in the privileged tests' run command, in their module's docs, which names their new path. The mapping table's 10 tests stay in
mappings/table/tests.rs.check_test_changes.pyreports 2 changes to existing tests, hencetests-modified: the import blocks ofguest::mappings::tests(mappings/tests.rs:8) andguest::mappings::tests::privileged(mappings/tests/privileged.rs:15), which it lists as removed, since those modules moved toguest::mappings::mapper::testsandguest::mappings::mapper::tests::privileged. Its 2 added entries are their import blocks at the new path, and the 68 entries that it relocates unchanged are the moved tests and their helpers.Validation
The Linux and Windows gates ran at
36200473, this change on #1261's earlier head058a6146. #1261's final head differs from that one only inscripts/public_api.py, whose rustdoc no longer enables default features and which now lists re-exported enum variants, and in that script's test. The range-diff shows this change's patch unchanged, and at this headpython scripts/public_api.pypasses andcheck_test_changes.pyreports the same changes.--binsconfigurations andscripts/public_api.py, pass. As root, the mapper's privileged tests pass 10 of 10 before the move, asguest::mappings::tests::privileged, and after it, asguest::mappings::mapper::tests::privileged.py-unittestwith 1796 tests (74 skipped), except fortest_adversarial.py's full runs under two Pythons:test_contained_*(2 failures and 2 errors in 84 tests), as it does at the base.b9869dea, this change before its rebase onto ci: check nvx's public API against committed snapshots #1261, with the guest artifacts built from that commit (guest-binary source identity84efc161): the sixtest-microvmscenarios, four of them on public sandboxes, andtest-runtime-adapterpass on WHP (Intel Alder Lake) and on MSHV (AMD Genoa). On MSHV, that pass is the fifth run: the first two failed most oftest-runtime-adapter, whose sockets' paths a long temporary directory made longer than Linux's 108 bytes, and with a shorter one, the next two each lost one of its tests to the time contract's 100 µs sample limit while builds loaded the host. Fromb9869deato this head, the range-diff adds only the snapshot update to this change, andgit diff --stattouches 10 files, none of them a runtime input: ci: check nvx's public API against committed snapshots #1261's two CI actions, three documents, its section ofnvx-rs/README.md,scripts/public_api.pyand its test, and the two snapshots, the Linux one with this change's update.