fix(housekeeping): unaligned read UB + recv-drop parity; dedup mmsghdr; doc fixes

From a bug-hunt + unsafe-audit pass (4 reviewers + adversarial verify). It
confirmed ZERO real bugs in the recent batched/paced data-plane work — these are
the surfaced cleanups + one genuine soundness fix:

- SOUNDNESS (reduce unsafe): inject/gamepad.rs::pump_ff did `ptr::read` of an
  InputEventRaw (align 8, holds a timeval) out of a 1-aligned [u8; N] buffer — UB
  per the reference (x86_64 tolerates it, but it can miscompile under LTO). Use
  ptr::read_unaligned + a SAFETY note. Zero behavior change.
- recv parity: recv_batch (recvmmsg) didn't drop an oversized/truncated datagram
  the way scalar recv does — poll_frame now skips a message whose len fills the
  buffer (> MAX_DATAGRAM_BYTES), matching recv's `n >= RECV_BUF` drop. (AEAD
  already rejected these on encrypted sessions; this restores the documented
  invariant on the batched path.)
- dedup unsafe FFI: factor the identical mmsghdr-from-iovec construction out of
  send_batch + recv_batch into one `mmsghdrs()` helper — the raw-pointer
  scaffolding + its lifetime SAFETY note now live in one place.
- docs: TARGET_SOCKBUF no longer calls paced sending future work (it landed,
  m3.rs::paced_submit); gamescope.rs input is no longer "(TODO)" (wired +
  live-validated); the PUNKTFUNK_PERF `wire_mbps` field is renamed `tx_mbps` and
  noted as attempted/sealed bytes (send_dropped shows what didn't reach the wire).

Full suite (35 + loopback round-trip + 6) + clippy + fmt green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

crates/punktfunk-host/src/inject/gamepad.rs

@@ -357,7 +357,11 @@ impl VirtualPad {
             if n != buf.len() as isize {
                 break; // EAGAIN / short read — queue drained
             }
-            let ev: InputEventRaw = unsafe { std::ptr::read(buf.as_ptr() as *const _) };
+            // SAFETY: `buf` is exactly `size_of::<InputEventRaw>()` bytes and fully written by the
+            // `read` above. `read_unaligned` (not `read`) because the `[u8]` buffer is 1-aligned but
+            // `InputEventRaw` needs 8 (it holds a `timeval`) — a plain `ptr::read` would be UB.
+            let ev: InputEventRaw =
+                unsafe { std::ptr::read_unaligned(buf.as_ptr() as *const InputEventRaw) };
             match (ev.type_, ev.code) {
                 (EV_UINPUT, UI_FF_UPLOAD) => {
                     let mut up: UinputFfUpload = unsafe { std::mem::zeroed() };

crates/punktfunk-host/src/m3.rs

@@ -1578,9 +1578,10 @@ fn virtual_stream(
         if perf && last_perf.elapsed() >= std::time::Duration::from_secs(2) {
             let s = session.stats();
             let secs = last_perf.elapsed().as_secs_f64();
-            let wire_mbps = (s.bytes_sent - last_bytes) as f64 * 8.0 / secs / 1_000_000.0;
+            // Attempted (sealed) transmit rate; `send_dropped` below is what didn't reach the wire.
+            let tx_mbps = (s.bytes_sent - last_bytes) as f64 * 8.0 / secs / 1_000_000.0;
             tracing::info!(
-                wire_mbps = format!("{wire_mbps:.0}"),
+                tx_mbps = format!("{tx_mbps:.0}"),
                 frames = sent,
                 send_dropped = s.packets_send_dropped - last_send_dropped,
                 send_dropped_total = s.packets_send_dropped,

crates/punktfunk-host/src/vdisplay/gamescope.rs

@@ -11,7 +11,8 @@
 //! Requirements: gamescope built with PipeWire + libei input emulation (distro packages are);
 //! a usable Vulkan device (the NVIDIA render node). Headless capture on the proprietary NVIDIA
 //! driver is plausible-by-architecture but not a well-trodden path — validate empirically.
-//! Input is a gamescope-specific libei/EIS socket (`LIBEI_SOCKET`), wired separately (TODO).
+//! Input uses gamescope's own libei/EIS socket (`LIBEI_SOCKET`), relayed to the libei backend (see
+//! `inject/libei.rs`) — wired and live-validated.
 
 use super::{Mode, VirtualDisplay, VirtualOutput};
 use anyhow::{anyhow, Context, Result};