docs: VM handoff — CLAUDE.md, Ubuntu bootstrap, headless-Sway setup for M0
Prepares the move to the NVIDIA-GPU Ubuntu VM where M0/M2 run (macOS can't drive the Wayland/GPU stack). The repo carries the context, since Claude Code sessions are machine-local and don't transfer. - CLAUDE.md: project state + design invariants + don't-regress security notes. Auto-loads every session, so a fresh session on the VM continues from here. - scripts/bootstrap-ubuntu.sh: verifies the (already-installed) NVIDIA/NVENC stack, installs rustup + PipeWire/portal/wlroots/Sway + DRM/EGL/GBM/VA dev deps; GATES the FFmpeg -dev headers so apt can't clobber a custom NVENC build; checks nvidia-drm.modeset. - scripts/headless/: headless-Sway + xdg-desktop-portal-wlr config templates, the NVIDIA-wlroots env workarounds, run-headless-sway.sh, and a wf-recorder->hevc_nvenc capture smoke test (proves capture->NVENC with no Rust). - docs/linux-setup.md: M0 walkthrough + verified gotchas (modeset, headless backend, vGPU NVENC licensing, dmabuf->NVENC CPU-copy fallback, FFmpeg-dev gate, crate versions). Ubuntu 24.04 package names/versions verified against the live archive; scripts pass shellcheck and `bash -n`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,77 @@
|
||||
# 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`](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`).
|
||||
- **The host backends are `#[cfg(target_os = "linux")]` stubs.** They compile everywhere
|
||||
but `bail!` until implemented. This is the next work (**M0**, then **M2**) and needs a
|
||||
real Linux GPU + Wayland stack — which is why this repo is being moved to the NVIDIA
|
||||
Ubuntu VM.
|
||||
|
||||
## Build / test / run
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
crates/lumen-core/ protocol · FEC · pacing · crypto — the C ABI (lib + cdylib + staticlib)
|
||||
crates/lumen-host/ Linux host: vdisplay · capture · encode · inject · web · pipeline (cfg-gated)
|
||||
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.
|
||||
|
||||
## Next: M0 (the pipeline spike) on this VM
|
||||
|
||||
**Start here on the NVIDIA Ubuntu VM:** [`docs/linux-setup.md`](docs/linux-setup.md), then
|
||||
run `bash scripts/bootstrap-ubuntu.sh` (verifies NVIDIA/NVENC, installs the Rust/PipeWire/
|
||||
wlroots/FFmpeg-dev deps) and bring up headless Sway with `scripts/headless/`.
|
||||
|
||||
Per plan §8/§12: drive a headless Sway/wlroots output → capture via PipeWire (ScreenCast
|
||||
portal, `ashpd` 0.13 + `pipewire` 0.10) → encode with NVENC (`ffmpeg-next` 7.x,
|
||||
`hevc_nvenc`) → write a playable H.265 file. Then wire that pipeline into a `lumen-core`
|
||||
host `Session` (M2). The module seams exist in
|
||||
`crates/lumen-host/src/{vdisplay,capture,encode,inject,pipeline}.rs`. **Budget for the
|
||||
CPU-copy fallback first** — dmabuf→NVENC zero-copy import is unreliable across NVIDIA
|
||||
driver versions (plan §9 risk); the setup doc covers it.
|
||||
|
||||
## 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`).
|
||||
Reference in New Issue
Block a user