[Enrique Saurez (esaurez)]

#619 makes the guest's role of the control session between the host and the guest usable by any guest agent, through nvx::guest::nvxs and with no NVXC dependency. Its G6 step covers NVX's managed agent (#639) and the runtime adapter's guest agent. This PR gives the runtime adapter from #626 its own application framing, and a guest agent that serves the host program with it over that session, through public APIs only. In #535's terms, it adds the guest's part of consumer-contract scenario C1, the control session with independent framing. The repository's docs describe these tests by what they check, without scenario IDs.

Part of #619
Refs #535

What changed

• runtime_adapter::frame, in every configuration: the adapter's framing, which its host program and guest agent exchange over the control session in place of NVXC.
  • A message is a 5-byte header, then a body. The header holds the body's length, a little-endian u32, then the message's kind: Ping, Pong, Echo (at most 256 KiB, what four of the session's largest records carry), Stop and Stopped.
  • Decoder reassembles messages that span records, or share one. It checks each header before it takes any byte of the body, and holds at most one partial message.
• runtime_adapter::guest, the guest agent, in the guest-only configuration: serve serves the host program over any stream to the guest's end of the session, through nvx::guest::nvxs::GuestConnection.
  • It acknowledges each reset with the smallest receive window, once it dropped the earlier epoch's partial message.
  • It credits each payload back once it holds it.
  • It answers Ping, Echo and Stop.
  • A session failure, a malformed message, or a message that only the guest sends ends it with an error.
• runtime-adapter-guest serve runs the guest agent on its standard input and output, such as a control console in raw mode. Without arguments, the binary still reports its contract, and anything else is still a usage error, as tests/independent_build.rs expects.
• Tests:
  • frame's unit tests: each kind's encoding, messages in pieces of any size and split at every byte, and the headers that it refuses.
  • tests/guest_session.rs, in the guest-only configuration. A test broker plays the broker's end of the guest's session over a Unix socket pair with nvx's public record API, for serve and for the static binary. It covers:
    • messages that span five records each way and fill the receive window;
    • a record whose bytes arrive one at a time;
    • resets in the middle of a message, to the instance's next epoch and to a new instance;
    • streams that end at and inside a record;
    • the records and messages that the guest agent refuses: sequence, epoch and instance errors, stale and identity-less resets, record lengths, bootstrap identity, ERROR payloads, header faults, and malformed messages.
  • Every wait on the guest is bounded by the broker's 30-second timeout: for its records, for the guest agent or its binary to end, and for the guest to read the broker's bytes. A guest that keeps serving or stops reading fails the test instead of hanging it, and a binary that is still running is killed and reaped first.
• Docs: the adapter's README, and its entries in doc/project-structure.md, doc/ci.md and doc/contribute.md. They describe the adapter by its parts' roles: the host program, the guest agent, and the control session between the host and the guest. They no longer refer to scenario IDs or later steps that only issues define. Neither do the adapter's comments in the check-nvx-rs action and the microVM workflow.

The host program's use of the session, and the hypervisor scenarios that run the adapter, come later in #620 and #535.

Validation

In tests/runtime-adapter, the steps that check-nvx-rs runs:

• Linux (Ubuntu, x86-64): every configuration, protocol-only, host-only, and guest-only for x86_64-unknown-linux-musl, with cargo fmt --all --check, Clippy with -D warnings, cargo build, cargo test and cargo +1.89 check.
• Linux (Ubuntu, x86-64), to check the bounds, with temporary cases outside the commits: a valid Ping through refused, one to the binary, and 16 MiB written to a guest that never reads. Each failed after 30 to 32 s instead of hanging.
• Windows 11: the protocol-only and host-only configurations, with the same commands.

Also on Windows 11:

• python scripts/check_markdown_links.py.
• python -m unittest scripts.test_nvx_tools, because the change edits comments in the check-nvx-rs action and the microVM workflow. In one of two full runs, a release-packaging test failed with "Access is denied" while it renamed a staging directory that it had just written. It passed in three runs on its own.

The adapter adds no dependency. No hypervisor scenario runs the adapter yet, so CI's microVM jobs only build it.

[Copilot]

🟢 Approval recommended

Source review identified no blocking issues in this scoped adapter change; validation was not rerun.

No open issues 🎉

What changed in this PR

Adds the runtime adapter’s guest-side NVXS session using public nvx-rs APIs and independent application framing, advancing the guest portion of consumer-contract scenario C1.

Changes:

• Adds bounded message framing and guest session handling.
• Adds runtime-adapter-guest serve and framing/session tests.
• Updates adapter and CI documentation; host integration remains deferred.

File	Description
tests/​runtime-adapter/​tests/​guest_session.rs	Tests guest sessions and binary behavior against a test broker.
tests/​runtime-adapter/​src/​lib.rs	Exposes framing and guest modules.
tests/​runtime-adapter/​src/​guest.rs	Implements guest session handling through public APIs.
tests/​runtime-adapter/​src/​frame.rs	Adds bounded framing, incremental decoding, and unit tests.
tests/​runtime-adapter/​src/​bin/​runtime-adapter-guest.rs	Adds serving over standard input and output.
tests/​runtime-adapter/​README.md	Documents framing, guest behavior, and tests.
doc/​project-structure.md	Updates the adapter’s structure and capabilities.
doc/​ci.md	Documents guest-side C1 coverage.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

Source review found no blocking issues in the isolated adapter changes; validation commands were not rerun.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

Static review identified no blocking issues in the framing, session integration, or contract tests; execution checks were not rerun.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No blocking issues were identified in the framing, session integration, binary behavior, tests, or documentation.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Rejection tests use unbounded termination waits that can hang CI when validation regresses.

1 open issue

• Bound rejection-test waits to prevent hangs on regressions · New

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No blocking issues remain, and the implementation includes focused protocol tests and fixes the previously reported unbounded termination waits.

No open issues 🎉

1 resolved since last review

• Bound rejection-test waits to prevent hangs on regressions

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No unresolved blocking findings remain, and the previously reported unbounded termination waits are addressed.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The scoped implementation and tests have no unresolved findings; tests were not executed during this review.

No open issues 🎉

_{Review effort: Balanced}