[Enrique Saurez (esaurez)]

Part of #1103

SL2.18a: extract the ordered restore rules into
host::restore::RestoreMachine, which callers drive without I/O or a clock.
This builds on activation record v2 in #1311; the restore-ready listener from
#1297 is already merged. No combined foundation branch or additional PR is
required.

The machine sends the same canonical record in every session, validates
Ready's transaction echo, and offers Connect after SessionLost. Explicit
operation failures retain their phase, evidence and original source; expiry,
cancellation and verified exit fail every pending phase. ActivateSent
distinguishes a completed write from the Ready wait, while a caller that
combines those operations may report GuestReady directly.

Success ends at Ready, without mappings or Start. The caller retains its
session, process and storage. The existing peer-verified listener is
unchanged. RestoreError initially carries only phase, evidence and source;
SL2.18b adds the remaining failure facts.

Tests

No existing tests are modified, relocated or retired. Six new pure transition
tests and three helpers cover identical bytes across retries, transaction
refusal, completed and combined writes, loss before an activation action is
taken, original source identity, and every pending-phase terminal input.

All existing listener tests are kept:

• the_held_vm_process_is_accepted_even_after_its_client_closed
• a_different_real_process_cannot_supply_the_event
• an_exited_held_process_cannot_supply_even_an_already_queued_event
• a_queued_peer_cannot_be_the_vm_that_reuses_its_pid
• the_receiver_fails_closed_without_original_peer_pidfds
• the_expected_process_cannot_change_after_acceptance
• a_native_listener_transfer_keeps_the_endpoint_usable_after_an_empty_receive
• the_socket_is_owner_only_even_when_the_umask_clears_owner_write
• the_pipe_is_a_fresh_owner_only_protected_first_instance

The legacy clone restore and post-Ready integration tests remain unchanged.

API and size

Adds RestoreMachine, RestoreInput, RestoreAction, RestorePhase,
RestoreEvidence, and the minimal RestoreError. Both generated public API
snapshots record the same 47 added items.

The entire four-commit owned range above
02d4219ff07e74622fe3178ad9e7f5b7d1ea3975 measures 213 core lines in
1 counted file, 6 raw files, with no ownership or visibility discounts.
The three original patches are preserved; the fourth addresses independent
review findings.

Validation

At ddb5336242656a412d66d9bf979c2d6b47a88ed6:

Check	Windows	Linux
Complete restore module	12 passed	14 passed
Full all-feature Cargo tests	Passed; library 1,222 passed, 6 ignored	Passed; library 1,969 passed, 33 ignored
Full default-feature Cargo tests	Passed; library 1,059 passed, 6 ignored	Passed; library 1,029 passed, 6 ignored
Protocol-only build and tests	273 tests passed	273 tests passed
Warning-denied Clippy, all five feature configurations	Passed	Passed
All-feature documentation and Rust 1.89 check	Passed	Passed
Generated Linux and Windows API comparison	Passed	Passed
Runtime adapter protocol/host lint, build, tests, docs and minimum Rust	Passed	Passed
Bundled-artifact fixture and formatting	Passed	Passed
Source verification, test layout and Markdown links	Passed	Passed

The macOS all-target/all-feature check also passed. An initial Linux full-test
attempt refused overlong fixture socket paths; using a shorter temporary
directory fixed the environment, and the complete command was rerun
successfully without changing source, assertions or deadlines.

Independent read-only review of this exact head has no remaining findings.
Native builds and VM runs are not needed for this pure host mechanism; no
native, guest, launch-argument or peer-check implementation changes are made.
Existing ignored runtime tests are not claimed as executed, and CI is not
claimed as passed.

[Copilot]

🟢 Approval recommended

No active review issues are reported for the caller-driven restore state machine.

No open issues 🎉

What changed in this PR

Adds a caller-driven RestoreMachine that sequences snapshot restoration through Ready without performing I/O or reading a clock. This advances #1103 using activation record v2 while leaving the existing peer-verified listener unchanged.

Changes:

• Adds restore inputs, actions, phases and errors, with canonical activation retries and transaction validation.
• Adds six transition tests covering retries, ordering, failure details and terminal inputs.
• Documents the caller-owned lifecycle and records 47 new public API items on Linux and Windows.

File	Description
nvx-rs/​src/​host/​restore/​tests.rs	Adds pure state-machine transition tests and helpers.
nvx-rs/​src/​host/​restore.rs	Implements restore sequencing, retry actions and failure reporting.
nvx-rs/​src/​host/​mod.rs	Updates the restore module’s documentation summary.
nvx-rs/​README.md	Documents machine usage and caller responsibilities.
nvx-rs/​public-api/​windows.txt	Records the new restore API on Windows.
nvx-rs/​public-api/​linux.txt	Records the new restore API on Linux.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are reported for the caller-driven restore state machine.

No open issues 🎉

_{Review effort: Balanced}