feat: v2.21.0 — L2 (native Ethernet) transport + UDP Annex J conformance fix

[SoundMatt]

Summary

ROADMAP.md milestone 65. Adds a real Layer-2 (raw Ethernet) transport alongside a corrected UDP transport — both are permanent, first-class, equally supported options; neither deprecates the other.

Provenance caveat (applies to every Annex J detail below): this codebase has no verified access to the paywalled IEEE 1722-2016 standard text. The Annex J details here rest on two independent public secondary sources: a Wireshark issue tracker discussion of the real Annex J wire text, and the COVESA Open1722 open-source reference implementation's Avtp_Udp_t header (include/avtp/Udp.h, BSD-3-Clause, github.com/COVESA/Open1722). "Annex J conformant" below means conformant with these two sources' reading, not verified against the primary standard.

1. rcp/udp.hpp Annex J conformance fix

• Both secondary sources agree an Annex J UDP payload begins with a 4-byte big-endian encapsulation sequence number before the AVTPDU — udp::Frame/MultiFrame never had this. New encode_annexj_datagram/decode_annexj_datagram are the pure codec for that envelope; Server/Client now transparently prepend/strip it around the existing AVTPDU encode/decode path. Both track and expose the value they send/receive (Client::last_sent_encap_seq/last_recv_encap_seq, Server::last_recv_encap_seq(client)) for a future caller's own use (e.g. loss detection) — no such detection is implemented, and the field's exact intended semantics are not claimed as verified.
• Standard destination UDP ports are 17220 (Continuous/streaming) and 17221 (Discrete/control). RCP request/response/acknowledge traffic is control-plane, so udp::kAnnexJControlPort (17221) is now the default port via a defaulted constructor parameter, while the explicit-port constructor form is unchanged for back-compat/testing.

2. rcp/l2.hpp (new): native IEEE 1722-over-Ethernet transport

The transport udp.hpp's own header comment always named as the alternative to Annex J but never implemented, now built:

• Wire frame: destination MAC (6) + source MAC (6, auto-read from the caller-specified interface via SIOCGIFHWADDR) + EtherType 0x22F0 (2) + the AVTPDU directly — no encapsulation sequence number (that field is Annex J/UDP-specific, not part of native L2 framing).
• l2::Server/l2::Client are structurally parallel to udp::Server/udp::Client — same method names, same Handler signature, same request/response correlation strategy — with no new Transport interface introduced (this codebase has none today; matching shapes without formal inheritance matches its existing style).
• Linux-only (AF_PACKET/SOCK_RAW, needs CAP_NET_RAW or root — documented in the header). Every other platform gets the same "compiles cleanly, every operation returns std::errc::function_not_supported" stub udp.hpp's own Windows branch already established as precedent.
• Deliberate structural deviation from udp.hpp: the pure Ethernet-header/Frame/MultiFrame codec is available unconditionally on every platform (not gated behind the socket-availability guard), specifically so tests/test_l2.cpp can exercise it everywhere with no privileges and no Linux requirement — documented explicitly in the header comment.
• The caller supplies the destination MAC (unicast or multicast) — this header does not derive or allocate a multicast MAC itself; that mapping (if IEEE 1722 defines one) lives in the base standard, not available here.

3. Tests

• tests/test_udp.cpp: new pure tests for encode_annexj_datagram/decode_annexj_datagram (round-trip, rejects short buffer, monotonic increment), a real Client/Server integration test proving the sequence number increments across successive requests and the Server observes it, a default-port test, plus the existing raw-socket multi-datagram test updated to speak the new encapsulated wire format.
• tests/test_l2.cpp (new): pure EthHeader/Frame/MultiFrame/combined-L2-frame codec tests — no socket, runs on every platform (macOS/Windows exercise the stub instead).
• tests/l2_veth_roundtrip.cpp (new): standalone (non-ctest) program driving a real l2::Server/l2::Client pair over a real Linux interface pair. Built by tests/CMakeLists.txt but deliberately not registered via add_test — needs CAP_NET_RAW/root and real interfaces, neither of which the normal ctest run has or should require.
• New l2-veth CI job (.github/workflows/ci.yml): creates a real veth pair with sudo, builds l2_veth_roundtrip, and runs it against veth0/veth1, asserting a real frame round-trips byte-for-byte.

4. Docs/requirements

• ROADMAP.md milestone 65 (GA renumbered [cpp-RCP-N2-02] write_whole_map accepts mismatched vector sizes and never resizes endpoint_owner_ #65 → [cpp-RCP-N2-03] E2E CRC coverage omits ACF_GBB message_timestamp, mismatching the transmitted bytes #66 accordingly), and the udp.hpp header comment's own prior "no additional encapsulation header" claim is corrected.
• .fusa-reqs.json gains REQ-UDP-013/REQ-UDP-014 and REQ-L2-001..008, tagged in the new/changed code via // fusa:req/// fusa:test comments matching this repo's existing convention.

Self-verification (real bytes, not just "tests pass")

• macOS (native, this environment): full build (Debug + Release, RELAY_BUILD_CLI=ON) and ctest — 53/53 suites pass (up from 52; test_l2 is new), 116 assertions in test_udp, 43 in test_l2 (macOS exercises the L2 stub).
• Linux (Docker, ubuntu:22.04, GCC 11 and Clang 14, C++17 and C++20): full build clean, ctest 53/53 pass; test_l2 runs the real (non-stub) pure-codec path (40 assertions, no socket).
• Real veth round trip (Linux container with --cap-add=NET_ADMIN --cap-add=NET_RAW): created a real veth0/veth1 pair, ran l2_veth_roundtrip with an 8-byte payload — exit 0, payload round-tripped byte-for-byte, confirmed clean shutdown, and repeated 3x with no flakiness. This surfaced and fixed a real bug during development: AF_PACKET sockets don't support shutdown() on Linux (silent no-op, unlike udp.hpp's AF_INET sockets), so close() was hanging forever after a successful round trip — fixed with a 200ms SO_RCVTIMEO poll loop (detail::set_recv_timeout).
• Privilege/graceful-failure check: ran the same harness as a non-root user with no CAP_NET_RAW — failed cleanly with a clear diagnostic and exit code 1, no crash/hang, confirming the documented CAP_NET_RAW/root requirement and the "construct, then check ok()" contract.
• One pre-existing -Wnonnull GCC warning under -DCMAKE_BUILD_TYPE=Release on this environment's specific GCC 16.1.0 toolchain was traced back and confirmed (via git stash) to already exist on unmodified main, unrelated to this change — not something this PR introduced or needed to fix (no -Werror for GCC/Clang in this repo; only MSVC's /WX and clang-tidy's own --warnings-as-errors gate, neither of which this warning affects).

Not merging — leaving for review per repo process.