Skip to content

nvx-rs: share one byte-level EXEC and MAPS decoder between the host and the guest #581

Description

Summary

nvx::protocol decodes the NVXC EXEC and MAPS payloads twice. decode_exec_payload and decode_maps_payload produce the host's UTF-8 types, and decode_guest_exec_payload and decode_guest_maps_payload, which #531 adds, produce the guest's byte strings. Each pair repeats the framing, flags, lengths, and field validation, so a later format or validation change can update one decoder and leave the other behind.

Found in the #531 review. #531 keeps a faithful port of the C agent, so this waits until the #358 series is done.

Proposal

Share the byte-oriented structural parsing, and keep the host's UTF-8 types behind conversions:

  • Keep the public host API and its diagnostics, and keep accepting non-UTF-8 guest arguments, paths, and environment entries.
  • Make intentional host and guest differences explicit rather than substituting one type for the other. For example, the two inherit_default_env fields differ when no explicit environment is supplied: the host's is true (flags & EXEC_ENVIRONMENT_PRESENT == 0 || flags & EXEC_INHERIT_DEFAULT_ENV != 0), and the guest's follows EXEC_INHERIT_DEFAULT_ENV alone.

#537 and #545 can then build on one parsing implementation rather than another pair of codecs.

Tasks

  • Share the structural parsing of EXEC and MAPS between the host and guest decoders, with the host API, its diagnostics, and the guest's acceptance unchanged.
  • Check the shared decoder against the C agent's parity fixtures, which nvx-rs: replace the guest C programs with Rust binaries #358 checks in before it removes the C agent. Their expected outcomes must not come from the new decoder.

Activity

  1. esaurez commented on Oct 20, 2026

    @esaurez
    Contributor

    #623 (A5) starts by finishing this (#603 merged, #616 open), then builds the shared credit and stdio engine on the single decoder. Tracked under #535.

  2. esaurez commented on Oct 23, 2026

    @esaurez
    Contributor

    Moved from #535 (A5 PR 1) to #816, which moves NVX's binaries and tools onto the shared libraries. What's left is EXEC's body: MAPS entries (#616) and EXEC's fixed header (#603) are already decoded once. It still comes before NVXC v2 (#821), which builds on one decoder. #623 now covers only the shared engine.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions