[Enrique Saurez (esaurez)]

Stacked on #869; this PR retargets to dev when it merges.

Part of #822: PR 4 of 11, the framing.

It lands after #822's PRs 1 to 3 (#863, #867, and #869), in #822's order.

What changed and why

The runtime adapter's guest answered a root configuration with an empty RootReady, and the adapter's framing had no message to hand the guest a mapping table or to tell it to start the sandbox's workloads. This PR adds that framing. The guest's order (#822's PR 6) and the host's order (PR 7) build on it.

• RootReady (kind 7) becomes Ready, whose body, root::Ready, carries the guest agent's build: its length, one byte, then 1 to 255 printable ASCII characters without a space. The length prefix lets later fields, such as the activation that nvx-rs: the restricted control state and Activate after a restore, in the guest library and the test adapter's framing #843 adds, follow the build.

• New kinds:

  Kind	Message	From	Body
  22	Maps	host	a part of the mapping table: a MAPS payload of nvx::protocol, at most 256 KiB
  23	Mapped	guest	none
  24	MapFailed	guest	root::MapFailure: how many mappings the guest applied, a u32, then the problem, at most 4 KiB
  25	Start	host	none
  26	Started	guest	none

  root::encode_maps splits a table into parts with encode_maps_payloads, and an empty table into none. root::decode_maps reads a part with decode_guest_maps_payload, and also refuses a part without a mapping, or one that would end the table past 4,096 mappings.

• The root configuration gains mapping-count, RootConfig::mapping_count: the number of mappings of the table, at most 4,096, and absent for none.

• The worker answers Ready with GUEST_BUILD, the crate's version, which moves from the host-only runtime module to the crate root so that the guest can report it. host::Client::configure_root returns the decoded Ready, and the client refuses Maps and Start from the guest, as it refuses the other messages that only the host sends.

• The README and the module docs describe the new kinds, their bodies, and the new field.

The worker doesn't apply mapping tables or wait for Start yet, and the host doesn't check the build yet: those are #822's PRs 6 and 7.

Validation

At this head, rebased onto #869:

• Windows, locally: cargo fmt --all --check; Clippy with -D warnings, the build, and the tests in the protocol-only and host-only configurations; cargo +1.89 check --locked --all-targets in both; python scripts/check_markdown_links.py.
• Linux: the same in the protocol-only, host-only, and guest-only configurations (--features guest --target x86_64-unknown-linux-musl), the minimum Rust version included.
• The adapter's VM scenarios, cargo test --locked --features host -- --ignored (25 layered, 2 restart, and 3 step scenarios), with the release that python scripts/nvx.py download installs for this branch, the scratch template, and the guest agent built from this branch: on WHP, on Windows, and on MSHV, on Linux, as root and with --cpu-profile host, since no built-in CPU profile supports that host's CPU. All pass.
• CI passed on dev at the head before the rebase. Left to CI, once this PR targets dev: the KVM runs, and the rest of the matrix.

[Copilot]

🟢 Approval recommended

Static review identified no blocking issues in the scoped framing changes, updated callers, or regression coverage; tests were not executed during this review.

No open issues 🎉

What changed in this PR

Adds the framing foundation for runtime-adapter cold sandbox startup in #822. Mapping application, startup ordering, and host build checks remain for later PRs.

Changes:

• Replaces RootReady with Ready, carrying the guest build, and adds mapping-table and startup messages.
• Adds mapping-count validation, mapping payload helpers, and structured mapping failures.
• Updates host/guest integration, protocol documentation, and framing and session regression tests.

File	Description
tests/​runtime-adapter/​tests/​runtime.rs	Updates the shared build constant import.
tests/​runtime-adapter/​tests/​host_session.rs	Tests readiness decoding and message rejection.
tests/​runtime-adapter/​tests/​guest_session.rs	Updates readiness expectations and refusal cases.
tests/​runtime-adapter/​src/​worker.rs	Reports the guest build in Ready.
tests/​runtime-adapter/​src/​runtime.rs	Moves the build constant out of the host-only module.
tests/​runtime-adapter/​src/​root.rs	Adds readiness, mapping payloads, mapping counts, and failure codecs with tests.
tests/​runtime-adapter/​src/​lib.rs	Exposes the build constant across configurations.
tests/​runtime-adapter/​src/​host.rs	Decodes readiness and rejects host-only mapping and startup messages.
tests/​runtime-adapter/​src/​frame.rs	Defines new message kinds, limits, and framing tests.
tests/​runtime-adapter/​src/​bin/​runtime-adapter-host.rs	Handles the readiness payload while preserving launch output.
tests/​runtime-adapter/​README.md	Documents the protocol additions and test coverage.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The codecs, framing limits, caller updates, and tests are consistent with the framing-only scope, with no blocking issues identified.

No open issues 🎉

_{Review effort: Balanced}