Encode RDMA tokens little-endian explicitly and test the wire layout

[derobins]

encodeRdmaTokenHex() and decodeRdmaTokenHex() copied each field with memcpy at a hand-tracked offset, so integers went on the wire in the host's byte order, and the sizes 4, 8, and 2 were written out by hand. docs/interop.rst defines the integers as little-endian, which only matched because every supported host is little-endian.

• Add TokenWriter and TokenReader, which write and read the token's binary form front to back over a std::span. Integers are encoded little-endian with shifts, so the bytes don't depend on the host, and each call advances the span, which replaces the offset bookkeeping. With _GLIBCXX_ASSERTIONS, an overrun aborts.
• Derive kTokenBinaryLen from the sizes of RdmaToken's fields, so a field type change fails the static_assert against kRdmaTokenHexLen instead of silently changing the wire format.
• Add golden-vector tests that encode and decode a token with a different value in every byte against the full 88-character string from the layout in docs/interop.rst. The existing round-trip tests pass with any self-consistent layout, so they couldn't catch swapped fields, changed widths, or the wrong byte order.
• docs/interop.rst now says the fields are packed with no padding and the integers are little-endian whatever the host's byte order. RdmaToken's comment points at that layout.

The bytes on the wire are unchanged on every supported platform, so there's no changelog entry.

[Copilot]

🟢 Approval recommended

The implementation matches the documented layout and is covered by encoding and decoding golden-vector tests.

0 open findings

What changed in this PR

This PR makes RDMA token serialization explicitly little-endian and verifies the documented wire format.

Changes:

• Adds span-based token readers and writers.
• Adds golden-vector encoding and decoding tests.
• Clarifies wire-layout documentation.

File	Description
src/​rdma/​token.cpp	Implements explicit little-endian serialization.
src/​rdma/​token.h	Documents the token’s wire-layout relationship.
test/​unit/​test-rdma-token.cpp	Adds golden wire-format tests.
docs/​interop.rst	Clarifies packing and byte order.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.