feat: M1 lumen-core (FEC/crypto/packet/session + C ABI) and workspace scaffold

Ground-up low-latency streaming stack per docs/implementation-plan.md. M1 is
complete and tested; Linux host backends are cfg-gated stubs to be filled in on
real hardware (M0/M2).

lumen-core (built + tested on macOS/aarch64 — 21 tests):
- fec: ErasureCoder over GF(2^8) (reed-solomon-erasure, Moonlight-compatible)
  and GF(2^16) Leopard-RS (reed-solomon-simd, the >1 Gbps wall-breaker); proptested
- packet: zero-copy #[repr(C)] framing, multi-block, FEC-aware reassembly
- crypto: AES-128-GCM with per-direction nonce salts + sequence-as-AAD
- session: host submit / client poll hot paths + input; loopback & UDP transports
- abi: opaque handles, versioned LumenConfig, panic guards; cbindgen-generated header
- acceptance: Rust loopback+proptest and a C harness that links the staticlib

Scaffold (compiles green on all platforms): lumen-host (vdisplay/capture/encode/
inject/web/pipeline seams under cfg(linux)), lumen-client-rs, tools/{loss-harness,
latency-probe}, Apple/Android client stubs, Gitea CI, docs.

Hardened against a multi-agent adversarial review (13 verified findings fixed,
regression-tested): reassembler memory-DoS bounds + block-consistency validation,
GCM nonce-reuse direction separation, ABI struct_size guard + range checks, FEC
shard-length guards, shard_payload datagram bound, key zeroization + Debug redaction.

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

crates/lumen-host/src/capture.rs

@@ -0,0 +1,32 @@
+//! Frame capture (plan §7). On Linux: a PipeWire ScreenCast portal stream delivering
+//! dmabuf frames with no copy to the CPU. The encoder imports the dmabuf directly.
+
+use anyhow::Result;
+
+/// A captured frame. For zero-copy the real type wraps a dmabuf fd + modifier; the CPU
+/// buffer is only a fallback path (plan §9 risk: per-GPU dmabuf import quirks).
+pub struct CapturedFrame {
+    pub width: u32,
+    pub height: u32,
+    pub pts_ns: u64,
+    /// Fallback CPU pixels (empty when a dmabuf is used).
+    pub cpu_bytes: Vec<u8>,
+}
+
+/// Produces frames from a captured output. Lives on its own thread, feeding the encoder
+/// over a bounded drop-oldest channel (never block the compositor).
+pub trait Capturer: Send {
+    fn next_frame(&mut self) -> Result<CapturedFrame>;
+}
+
+/// Open a capturer for a PipeWire node id (from the ScreenCast portal).
+pub fn open_pipewire(_node_id: u32) -> Result<Box<dyn Capturer>> {
+    #[cfg(target_os = "linux")]
+    {
+        anyhow::bail!("pipewire capture not yet implemented (M0)")
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        anyhow::bail!("capture requires Linux + PipeWire")
+    }
+}

crates/lumen-host/src/encode.rs

@@ -0,0 +1,40 @@
+//! Hardware video encode (plan §7). Binds FFmpeg (VAAPI / NVENC); never rewrites codecs.
+//! Low-latency preset, lookahead off, dmabuf import for zero-copy from [`crate::capture`].
+
+use crate::capture::CapturedFrame;
+use anyhow::Result;
+
+/// An encoded access unit (one NAL/AU) to hand to `lumen_core` for FEC + packetization.
+pub struct EncodedFrame {
+    pub data: Vec<u8>,
+    pub pts_ns: u64,
+    /// True for IDR/keyframes (sets the SOF/keyframe wire flags).
+    pub keyframe: bool,
+}
+
+/// Codec selection negotiated with the client.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Codec {
+    H264,
+    H265,
+    Av1,
+}
+
+/// A hardware encoder. One per session; runs on the encode thread.
+pub trait Encoder: Send {
+    fn submit(&mut self, frame: &CapturedFrame) -> Result<()>;
+    /// Pull the next encoded AU if one is ready.
+    fn poll(&mut self) -> Result<Option<EncodedFrame>>;
+}
+
+/// Open an encoder. `bitrate_bps` and `codec` come from session negotiation.
+pub fn open(_codec: Codec, _bitrate_bps: u64) -> Result<Box<dyn Encoder>> {
+    #[cfg(target_os = "linux")]
+    {
+        anyhow::bail!("VAAPI/NVENC encode not yet implemented (M0)")
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        anyhow::bail!("encode requires Linux (VAAPI/NVENC via FFmpeg)")
+    }
+}

crates/lumen-host/src/inject.rs

@@ -0,0 +1,30 @@
+//! Input injection (plan §4): turn client [`lumen_core::input::InputEvent`]s into host
+//! input. Wayland-native via libei (`reis`) first; uinput as the universal fallback.
+
+use anyhow::Result;
+use lumen_core::input::InputEvent;
+
+/// Injects input events into the host session.
+pub trait InputInjector: Send {
+    fn inject(&mut self, event: &InputEvent) -> Result<()>;
+}
+
+/// Preferred injection backend.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Backend {
+    /// libei via `reis` — Wayland-native (RemoteDesktop portal).
+    Libei,
+    /// `/dev/uinput` — universal fallback, always available.
+    Uinput,
+}
+
+pub fn open(_backend: Backend) -> Result<Box<dyn InputInjector>> {
+    #[cfg(target_os = "linux")]
+    {
+        anyhow::bail!("libei/uinput injection not yet implemented (M2)")
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        anyhow::bail!("input injection requires Linux (libei/uinput)")
+    }
+}

crates/lumen-host/src/main.rs

@@ -0,0 +1,61 @@
+//! `lumen-host` — the Linux streaming host (plan §2, §6, §7).
+//!
+//! Creates a client-sized virtual display, captures it via PipeWire, encodes with
+//! VAAPI/NVENC, and hands encoded access units to `lumen_core` for FEC + packetization +
+//! pacing + send. Input flows back via libei/uinput. The platform backends are
+//! `#[cfg(target_os = "linux")]`; the crate compiles everywhere so the workspace builds
+//! on non-Linux dev machines — it just can't run the pipeline there.
+//!
+//! Status: scaffold. M0 wires capture→encode→file; M2 wires the full P1 host that a
+//! stock Moonlight client connects to.
+
+// Scaffold: trait methods and config paths are defined ahead of their backends.
+#![allow(dead_code)]
+
+mod capture;
+mod encode;
+mod inject;
+mod pipeline;
+mod vdisplay;
+mod web;
+
+use vdisplay::{Compositor, Mode};
+
+fn main() {
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()),
+        )
+        .init();
+
+    tracing::info!(
+        "lumen-host scaffold (lumen_core ABI v{})",
+        lumen_core::ABI_VERSION
+    );
+
+    // The intended startup sequence (each step is a separate, pluggable subsystem):
+    //   1. negotiate mode + codec + FEC scheme over the control plane (web::WebConfig)
+    //   2. vdisplay::open(compositor).create(mode)  -> client-sized virtual output
+    //   3. capture::open_pipewire(node) ; encode::open(codec, bitrate)
+    //   4. build a lumen_core::Session (host role) over a UDP transport to the client
+    //   5. loop pipeline::pump_once(..)  until disconnect, then destroy the output
+    let target_mode = Mode {
+        width: 2560,
+        height: 1440,
+        refresh_hz: 240,
+    };
+    let compositor = Compositor::Kwin; // MVP target
+
+    if cfg!(target_os = "linux") {
+        tracing::info!(
+            ?compositor,
+            ?target_mode,
+            "would create a virtual output and start streaming (backends pending M0/M2)"
+        );
+    } else {
+        tracing::warn!(
+            "this is a Linux host; on {} only the shared lumen_core builds and is testable",
+            std::env::consts::OS
+        );
+    }
+}

crates/lumen-host/src/pipeline.rs

@@ -0,0 +1,39 @@
+//! The host hot path (plan §7), wiring the platform stages to `lumen_core`:
+//!
+//! ```text
+//! capture(dmabuf) → encode(NVENC/VAAPI) → core[FEC+packetize+pace+send]
+//! ```
+//!
+//! Each stage runs on its own native OS thread, connected by bounded SPSC channels with
+//! drop-oldest on overflow so the encoder is never blocked. No async runtime here.
+
+use crate::capture::Capturer;
+use crate::encode::{EncodedFrame, Encoder};
+use anyhow::Result;
+use lumen_core::packet::{FLAG_PIC, FLAG_SOF};
+use lumen_core::Session;
+
+/// Drive one capture→encode→submit step. The real pipeline spawns threads and uses
+/// bounded channels; this documents the data flow and the `lumen_core` submit contract.
+pub fn pump_once(
+    capturer: &mut dyn Capturer,
+    encoder: &mut dyn Encoder,
+    session: &mut Session,
+) -> Result<()> {
+    let frame = capturer.next_frame()?;
+    encoder.submit(&frame)?;
+    while let Some(EncodedFrame {
+        data,
+        pts_ns,
+        keyframe,
+    }) = encoder.poll()?
+    {
+        let mut flags = FLAG_PIC as u32;
+        if keyframe {
+            flags |= FLAG_SOF as u32;
+        }
+        // core does FEC + packetize + pace + send.
+        session.submit_frame(&data, pts_ns, flags)?;
+    }
+    Ok(())
+}

crates/lumen-host/src/vdisplay.rs

@@ -0,0 +1,96 @@
+//! Virtual display orchestration (plan §6) — the project's differentiator.
+//!
+//! A [`VirtualDisplay`] creates a client-sized output on demand, to be captured and
+//! streamed, then torn down on disconnect. Two deployment models exist (Model A: attach
+//! to the running session; Model B: dedicated headless session); both sit behind this
+//! trait so compositors are pluggable and a stuck one never blocks the project.
+//!
+//! Backends are `#[cfg(target_os = "linux")]` and currently stubs (see the per-backend
+//! modules). The MVP target is KWin; a wlroots spike validates the pipeline first.
+
+use anyhow::Result;
+pub use lumen_core::Mode;
+
+/// Opaque handle to a created virtual output, returned by [`VirtualDisplay::create`].
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct OutputHandle(pub u64);
+
+/// Pluggable virtual-output creation, per compositor.
+pub trait VirtualDisplay: Send {
+    /// Human-readable backend name (e.g. `"kwin"`, `"wlroots"`, `"mutter"`).
+    fn name(&self) -> &'static str;
+    /// Create a virtual output of the given mode.
+    fn create(&mut self, mode: Mode) -> Result<OutputHandle>;
+    /// Destroy a previously created output.
+    fn destroy(&mut self, handle: OutputHandle) -> Result<()>;
+}
+
+/// Compositors lumen knows how to drive (plan §6).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Compositor {
+    /// KWin / Plasma 6 — MVP target (matches the CachyOS/KDE daily driver).
+    Kwin,
+    /// wlroots (Sway/Hyprland) — fastest to prototype the pipeline.
+    Wlroots,
+    /// Mutter / GNOME — headless backend + Mutter DBus.
+    Mutter,
+}
+
+/// Detect or select a backend and return its driver.
+pub fn open(compositor: Compositor) -> Result<Box<dyn VirtualDisplay>> {
+    #[cfg(target_os = "linux")]
+    {
+        match compositor {
+            Compositor::Kwin => Ok(Box::new(linux::kwin::KwinDisplay::new()?)),
+            Compositor::Wlroots => Ok(Box::new(linux::wlroots::WlrootsDisplay::new()?)),
+            Compositor::Mutter => Ok(Box::new(linux::mutter::MutterDisplay::new()?)),
+        }
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        let _ = compositor;
+        anyhow::bail!("virtual displays require Linux (Wayland compositor)")
+    }
+}
+
+#[cfg(target_os = "linux")]
+mod linux {
+    //! Linux backends. TODO(M2): drive KWin via DBus (study KRdp's source for the
+    //! virtual-output path); wlroots via `create_output` on the headless backend;
+    //! Mutter via `org.gnome.Mutter.*`.
+    macro_rules! stub_backend {
+        ($modname:ident, $ty:ident, $name:literal) => {
+            pub mod $modname {
+                use super::super::{Mode, OutputHandle, VirtualDisplay};
+                use anyhow::Result;
+
+                pub struct $ty;
+                impl $ty {
+                    pub fn new() -> Result<Self> {
+                        Ok($ty)
+                    }
+                }
+                impl VirtualDisplay for $ty {
+                    fn name(&self) -> &'static str {
+                        $name
+                    }
+                    fn create(&mut self, _mode: Mode) -> Result<OutputHandle> {
+                        anyhow::bail!(concat!(
+                            $name,
+                            " virtual-output creation not yet implemented"
+                        ))
+                    }
+                    fn destroy(&mut self, _handle: OutputHandle) -> Result<()> {
+                        anyhow::bail!(concat!(
+                            $name,
+                            " virtual-output destroy not yet implemented"
+                        ))
+                    }
+                }
+            }
+        };
+    }
+    stub_backend!(kwin, KwinDisplay, "kwin");
+    stub_backend!(wlroots, WlrootsDisplay, "wlroots");
+    stub_backend!(mutter, MutterDisplay, "mutter");
+}

crates/lumen-host/src/web.rs

@@ -0,0 +1,24 @@
+//! Web config / pairing API (plan §4) — control plane only. This is where `tokio`/`axum`
+//! are permitted; the per-frame pipeline never touches them. Serves pairing, client
+//! identity/permissions, and surfaces [`lumen_core::Stats`] for the measurement UI (M3).
+
+use anyhow::Result;
+
+/// Control-plane configuration server. Stub until the pairing/RTSP surface is scoped
+/// (plan §12 action 4: confirm exactly which serverinfo/RTSP/pairing messages a current
+/// Moonlight client needs for P1).
+pub struct WebConfig {
+    pub bind: String,
+}
+
+impl WebConfig {
+    pub fn new(bind: impl Into<String>) -> Self {
+        WebConfig { bind: bind.into() }
+    }
+
+    /// Run the control-plane server. TODO(M2): axum + tokio; GameStream `serverinfo`,
+    /// pairing handshake, RTSP SETUP with the `lumen/1` capability flag for negotiation.
+    pub fn run(&self) -> Result<()> {
+        anyhow::bail!("web/pairing control plane not yet implemented (M2)")
+    }
+}