punktfunk/CLAUDE.md

CLAUDE.md — lumen

Low-latency desktop streaming stack, Linux-first, with a shared Rust protocol core (lumen-core) exposed over a C ABI and native clients per platform. Full design: docs/implementation-plan.md. Status table: README.md.

Where the work stands

• M1 (lumen-core + C ABI) is complete, tested, and hardened. It builds and its full suite passes (FEC recovery, loopback-under-loss, proptests, a C ABI harness). It was put through an adversarial review and 13 verified findings were fixed + regression-tested (commit a913042).
• M0 (the pipeline spike) is done and verified on the NVIDIA box (Ubuntu 25.10, RTX 5070 Ti, driver 595): lumen-host m0 captures a headless wlroots output via the ScreenCast portal + PipeWire, NVENC-encodes it, writes a playable H.265 file, and round-trips every access unit through a lumen_core host→client session (0 mismatches). See docs/linux-setup.md; the code is in crates/lumen-host/src/{m0,capture,encode}.rs (+ capture/linux.rs, encode/linux.rs).
• The remaining host backends are #[cfg(target_os = "linux")] stubs — KWin/Mutter virtual displays (vdisplay.rs), libei/uinput input (inject.rs), web/pairing (web.rs). They compile everywhere but bail! until implemented. This is M2.

Build / test / run

cargo build --workspace          # green on Linux and macOS
cargo test  --workspace          # unit + loopback + proptest + C ABI harness
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all --check

cargo run -p loss-harness        # FEC loss-resilience sweep (no network needed)
bash crates/lumen-core/tests/c/run.sh   # standalone C-ABI link + round-trip proof

include/lumen_core.h is generated from crates/lumen-core/src/abi.rs by cbindgen (build.rs) on every build and is checked in; CI fails if it drifts, so commit the regenerated header when the ABI changes. Same deal for the management API's OpenAPI document: docs/api/openapi.json is checked in for client codegen and a test fails if it drifts — regenerate with cargo run -p lumen-host -- openapi > docs/api/openapi.json (the spec lives in crates/lumen-host/src/mgmt.rs).

Layout

crates/lumen-core/   protocol · FEC · pacing · crypto — the C ABI (lib + cdylib + staticlib)
crates/lumen-host/   Linux host: vdisplay · capture · encode · inject · gamestream · mgmt · pipeline
docs/api/openapi.json   generated management-API spec (codegen input)
crates/lumen-client-rs/   reference client (M4)
tools/{loss-harness,latency-probe}/   measurement (plan §10)
clients/{apple,android}/   native client scaffolds (import lumen_core.h)
include/lumen_core.h   generated C header

Design invariants — do not regress

• One core, linked everywhere. Protocol/FEC/crypto/pacing live only in lumen-core, behind a stable, versioned C ABI (lumen_abi_version, LumenConfig.struct_size).
• No async on the hot path. The per-frame pipeline uses native threads only; tokio/quinn are gated behind the off-by-default quic feature (control plane only).
• FEC is the wall-breaker. GF(2⁸) (≤255 shards/block, Moonlight-compatible) and GF(2¹⁶) Leopard-RS (≤65535 shards/block, SIMD) — the latter removes the ~1 Gbps ceiling.
• Security hardening from the M1 review must stay intact: the reassembler bounds every attacker-controlled header field against negotiated limits before allocating (ReassemblerLimits in packet.rs); AES-GCM uses per-direction nonce salts + seq-as-AAD (crypto.rs); the ABI enforces struct_size and range-checks inputs. There are regression tests for these — keep them green.

Running the M0 spike on this box

docs/linux-setup.md is the reference. One-time: bash scripts/bootstrap-ubuntu.sh (verifies NVIDIA/NVENC, installs deps incl. libnvidia-gl, adds the render/video groups — re-login after). Then per run: bash scripts/headless/run-headless-sway.sh (shell 1) and bash scripts/headless/prepare-session.sh (shell 2), then cargo run -p lumen-host -- m0 --source portal --out /tmp/lumen-m0.h265. --source synthetic needs no capture session.

M0 uses the CPU-copy capture path (portal → PipeWire shm, packed RGB on wlroots → NVENC rgb0); dmabuf→NVENC zero-copy is deferred (plan §9). Pinned crate facts (the setup doc has the why): ashpd 0.13 (screencast feature, options-struct API, multi-thread tokio runtime) + pipewire 0.9 (must match ashpd's; not 0.10) + ffmpeg-next 8.x (binds the system FFmpeg 8.x / libavcodec 62 on Ubuntu 26.04; bumped from 7.x).

Next: M2 — P1 host to a stock Moonlight client

Wire M0's capture→encode pipeline (m0.rs / pipeline.rs) into a streaming host: KWin virtual output (vdisplay.rs, study KRdp), serverinfo/pairing/RTSP (web.rs) enough for a real Moonlight client, input via reis/uinput (inject.rs). The module seams exist and bail! today.

Conventions

• Rust 2021, rustfmt + clippy -D warnings clean before commit.
• Match the surrounding code's comment density and naming.
• Commit messages end with the Co-Authored-By trailer (see git log).