docs: rework client/crate READMEs, add missing ones

Rework the client READMEs to be accurate and inviting to first-time visitors, and fill in the gaps where crates and tools had none. - Rewrite clients/{apple,android,decky} READMEs (features-first, trim dense internal narrative; drop the stale "one session at a time" / "renegotiation not implemented" section from the Apple README). - Add READMEs for clients/{linux,windows,probe}, which had none. - Add crate READMEs for punktfunk-host, punktfunk-core, pf-driver-proto. - Add brief READMEs for tools/{loss-harness,latency-probe}. - Fix packaging/README duplicate "Option B" heading (bootc -> Option C). - Fix docs-site/README stale docs/ -> design/ reference. - De-stale packaging/windows/drivers/pf-dualsense README (drop "M0 spike" / external-checkout framing; reflect in-tree workspace + shipped + installer-bundled + multi-pad), keeping the driver-authoring lore. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-01 19:31:06 +00:00
parent 7975a95cd6
commit d6596ff81b
14 changed files with 624 additions and 585 deletions
@@ -0,0 +1,61 @@
+# punktfunk-core
+
+The **shared protocol core** — the one place where punktfunk's transport, forward error correction,
+and crypto live. It's linked into the [host](../punktfunk-host/README.md) and every native client, so
+there's exactly one implementation of the wire format everywhere.
+
+Written in Rust with **no async on the per-frame path** (native threads only). It exposes both a
+normal Rust API and a **stable, versioned C ABI**, so the Swift and Kotlin clients — and any C
+embedder — link the same code as the Rust ones.
+
+## What's in here
+
+- **Transport & session** (`session.rs`, `transport/`, `packet.rs`) — the `punktfunk/1` data plane
+  over raw UDP: packetization, reassembly (with attacker-bounded limits), pacing, and socket tuning.
+- **FEC** (`fec/`) — the wall-breaker. Two codes:
+  - **GF(2⁸)** classic Reed–Solomon with the *Cauchy* generator matrix — byte-identical to the
+    `nanors` library Moonlight uses, so our parity is decodable by a stock Moonlight client.
+  - **GF(2¹⁶) Leopard-RS** (SIMD, O(n log n)) — up to 65535 shards/block, which removes the ~1 Gbps
+    FEC ceiling. `punktfunk/1` negotiates this one.
+- **Crypto** (`crypto.rs`) — AES-128-GCM session encryption with per-direction nonce salts and
+  sequence-as-AAD; SPAKE2 PIN pairing lives behind the `quic` feature.
+- **QUIC control plane** (`quic.rs`, `client.rs`, feature `quic`) — the Hello/Welcome/Start handshake,
+  cert pinning/TOFU, reverse audio, and the embeddable `NativeClient` connector. This is the **only**
+  place `tokio`/`quinn` are allowed; the feature is **off by default** so the core stays runtime-free.
+- **C ABI** (`abi.rs`) — the versioned surface (`punktfunk_abi_version()`, `PunktfunkConfig` carrying
+  its own `struct_size`) that generates [`include/punktfunk_core.h`](../../include/punktfunk_core.h)
+  via cbindgen at build time.
+
+## Build outputs
+
+The crate builds three ways at once (`crate-type = ["lib", "cdylib", "staticlib"]`):
+
+| Output | Used by |
+|--------|---------|
+| `lib` (rlib) | the host, probe, and tools link it as a normal Rust crate |
+| `cdylib` (`.so`/`.dylib`) | the Swift / Kotlin clients via the C ABI |
+| `staticlib` (`.a`) | the C test harness and static embedding |
+
+## Test
+
+```sh
+cargo test -p punktfunk-core                 # unit + proptest + loopback
+cargo run  -p loss-harness                   # FEC loss-resilience sweep (no network needed)
+bash crates/punktfunk-core/tests/c/run.sh    # standalone C-ABI link + round-trip proof
+```
+
+## Design invariants (do not regress)
+
+- **One core, linked everywhere** — protocol/FEC/crypto live only here, behind the stable C ABI.
+- **No async on the hot path** — the per-frame pipeline is native threads only; `quic` (tokio/quinn)
+  is control-plane only, feature-gated, off by default.
+- **Security hardening stays intact** — the reassembler bounds attacker-controlled fields before
+  allocating; AES-GCM keeps per-direction nonce salts + seq-as-AAD; the ABI checks `struct_size`.
+  Regression tests exist — keep them green.
+
+## Related
+
+- **[`punktfunk-host`](../punktfunk-host/README.md)** — the streaming host built on this core
+- **[Clients](../../clients/)** — the apps that link this core over the C ABI (or directly, in Rust)
+- **[`design/implementation-plan.md`](../../design/implementation-plan.md)** — why GF(2¹⁶) FEC, the
+  latency budget, and the architecture thesis