feat(core,host): CODEC_PYROWAVE negotiation — opt-in only, host dispatch wired

Phase 2a+2c of design/pyrowave-codec-plan.md.

Core: CODEC_PYROWAVE = 0x08 on Hello::video_codecs/Welcome::codec.
Deliberately absent from resolve_codec's precedence ladder (plan §3 —
a 100-400 Mbps codec must never win a negotiation by mere mutual
support): reachable exclusively through the client's explicit
preferred_codec. Invariant tests cover never-auto-selected (even as the
only shared codec), preferred-path selection, and graceful fallback.
ABI mirror PUNKTFUNK_CODEC_PYROWAVE + lockstep assert for the
Apple/Android embedders.

Host: Codec::PyroWave variant threaded through the wire mappings; a
negotiated PyroWave session routes straight to the backend ahead of the
PUNKTFUNK_ENCODER pref dispatch (which stays a lab override). The
advertisement bit rides host_wire_caps only when the capture side would
actually deliver ingestible frames — linux_zero_copy_is_vaapi(), i.e.
AMD/Intel auto or an explicit operator pref on NVIDIA; per-session
raw-dmabuf OutputFormat plumbing is recorded as the Phase-3 item. The
libavcodec name helpers are dispatch-guarded unreachable; the web
console gains ApiCodec::PyroWave (api/openapi.json regenerated).

Validated on .21: 308 host tests green with and without the feature,
145 core tests green with quic, clippy clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

crates/punktfunk-core/src/abi.rs

@@ -928,6 +928,10 @@ pub const PUNKTFUNK_CODEC_H264: u8 = 0x01;
 pub const PUNKTFUNK_CODEC_HEVC: u8 = 0x02;
 /// Codec bit: AV1. (Mirrors `quic::CODEC_AV1`.)
 pub const PUNKTFUNK_CODEC_AV1: u8 = 0x04;
+/// Codec bit: PyroWave — the opt-in wired-LAN intra-only wavelet codec. Never auto-selected:
+/// the host picks it ONLY when the client also passes it as `preferred_codec`
+/// (design/pyrowave-codec-plan.md §3). (Mirrors `quic::CODEC_PYROWAVE`.)
+pub const PUNKTFUNK_CODEC_PYROWAVE: u8 = 0x08;
 
 // Keep the ABI cap bits in lockstep with the wire constants (compile-time guard against drift).
 #[cfg(feature = "quic")]
@@ -938,6 +942,7 @@ const _: () = {
     assert!(PUNKTFUNK_CODEC_H264 == crate::quic::CODEC_H264);
     assert!(PUNKTFUNK_CODEC_HEVC == crate::quic::CODEC_HEVC);
     assert!(PUNKTFUNK_CODEC_AV1 == crate::quic::CODEC_AV1);
+    assert!(PUNKTFUNK_CODEC_PYROWAVE == crate::quic::CODEC_PYROWAVE);
 };
 
 // Keep the ABI gamepad constants in lockstep with the wire enum (compile-time guard against drift).

crates/punktfunk-core/src/quic/msgs.rs

@@ -151,15 +151,28 @@ pub const CODEC_H264: u8 = 0x01;
 pub const CODEC_HEVC: u8 = 0x02;
 /// [`Hello::video_codecs`] bit: the client can decode AV1.
 pub const CODEC_AV1: u8 = 0x04;
+/// [`Hello::video_codecs`] bit: the client can decode **PyroWave** — the opt-in wired-LAN
+/// intra-only wavelet codec (design/pyrowave-codec-plan.md; 100–400 Mbps class, 8-bit SDR,
+/// every frame independently decodable). Deliberately **absent from [`resolve_codec`]'s
+/// precedence ladder**: it is selected only when the client also names it
+/// [`Hello::preferred_codec`] (or the host operator forces the advertisement mask) — a codec
+/// that needs a wired-LAN bitrate must never win a negotiation just because both ends support
+/// it. The bit means "PyroWave bitstream as of the punktfunk-vendored pin"
+/// (`crates/pyrowave-sys/vendor/pyrowave/PUNKTFUNK-VENDOR.txt`): upstream has no bitstream
+/// version field, so a vendored bump that changes the bitstream bumps the punktfunk protocol
+/// version instead (plan §4.2).
+pub const CODEC_PYROWAVE: u8 = 0x08;
 
 /// Resolve which single codec the host will emit, from the client's advertised [`Hello::video_codecs`]
 /// bitfield (`0` = an older client, treated as HEVC-only) intersected with what the host's chosen
 /// encoder can produce (`host_capable`, also a bitfield). `preferred` is the client's soft preference
 /// ([`Hello::preferred_codec`], `0` = none): when it's in the shared set it wins; otherwise the tie is
 /// broken by **HEVC > AV1 > H.264** (HEVC is the established, best-tested path; H.264 is the
-/// compatibility / software floor). Returns the single-bit codec value, or `None` when client and host
-/// share nothing — the caller then refuses the session with a clear error rather than emitting a
-/// stream the client can't decode.
+/// compatibility / software floor). [`CODEC_PYROWAVE`] is intentionally NOT in that ladder — it can
+/// only be returned via the `preferred` path (plan §3: opt-in, pinned, honest). Returns the
+/// single-bit codec value, or `None` when client and host share nothing the ladder may pick — the
+/// caller then refuses the session with a clear error rather than emitting a stream the client
+/// can't decode.
 pub fn resolve_codec(client_codecs: u8, host_capable: u8, preferred: u8) -> Option<u8> {
     // An older client (no codec byte) decodes HEVC — the only codec every pre-negotiation build sent.
     let client = if client_codecs == 0 {

crates/punktfunk-core/src/quic/tests.rs

@@ -101,6 +101,30 @@ fn codec_negotiation_and_back_compat() {
     // A preference the host can't emit still can't rescue a no-shared-codec case.
     assert_eq!(resolve_codec(CODEC_HEVC, CODEC_H264, CODEC_HEVC), None);
 
+    // PyroWave is opt-in ONLY (plan §3): mutual support NEVER auto-selects it — the ladder
+    // ignores it entirely...
+    assert_eq!(
+        resolve_codec(CODEC_HEVC | CODEC_PYROWAVE, CODEC_HEVC | CODEC_PYROWAVE, 0),
+        Some(CODEC_HEVC)
+    );
+    // ...even when it is the ONLY shared codec (an all-intra 200 Mbps stream must never be a
+    // silent fallback)...
+    assert_eq!(resolve_codec(CODEC_PYROWAVE, CODEC_PYROWAVE, 0), None);
+    // ...it is reachable exclusively through the client's explicit preference.
+    assert_eq!(
+        resolve_codec(
+            CODEC_HEVC | CODEC_PYROWAVE,
+            CODEC_HEVC | CODEC_PYROWAVE,
+            CODEC_PYROWAVE
+        ),
+        Some(CODEC_PYROWAVE)
+    );
+    // A pyrowave preference against a host without the backend falls back to the ladder.
+    assert_eq!(
+        resolve_codec(CODEC_HEVC | CODEC_PYROWAVE, CODEC_HEVC, CODEC_PYROWAVE),
+        Some(CODEC_HEVC)
+    );
+
     // A Hello advertising codecs roundtrips, and the wire form of a codec-only Hello decodes on
     // a build that ignores the trailing byte (back-compat: extra bytes are skipped).
     let h = Hello {