fix(encode): harden loss-recovery correctness across host encoders (F1–F7)

Phases 1–4 of design/encoder-recovery-hardening.md — make the shipped RFI/ freeze-until-reanchor recovery honest and rebuild-safe across every backend. F1 — frame-index domain desync: the encode loop now owns a session-lifetime `au_seq`; `Encoder::submit_indexed(au_seq + inflight)` pins NVENC inputTimeStamp and AMF LTR slots to the WIRE frame index, so `invalidate_ref_frames` compares client frame numbers in the same domain and survives adaptive-bitrate rebuilds (an internal counter desynced on the first rebuild → RFI silently dead / an AMF force-ref onto a never-decoded frame). `FrameMsg.frame_index` → `Session::seal_frame_at`; GameStream gets the same via `VideoPacketizer:: packetize(.., Some(idx))`. F2 — Windows NVENC left the client frozen ~1s per loss: NVENC RFI was transparent (no anchor tag) while the session glue armed the 750ms IDR cooldown, so the freeze only lifted on the ~1s keyframe re-ask. NVENC now mirrors AMF — `pending_anchor` tags the first post-invalidate AU (the clean re-anchor P-frame) `recovery_anchor`, incl. the covering-range dedupe re-arm; the client lifts at ~RTT. F3 — speed-test probe filler burned video frame indexes: moved to its own index space (`Packetizer::alloc_probe_index` + `Session::submit_probe_frame`) with a second client reassembly window routed on FLAG_PROBE, gated on the new VIDEO_CAP_PROBE_SEQ Hello bit (mid-session probes declined for older clients). F4 — RFI range sanity cap: forward gaps wider than `packet::RFI_MAX_RANGE` (256) resync via keyframe instead of an out-of-range RFI, host- and client-side (client huge-gap → keyframe in `RfiRecovery::observe` + the pf-client-core pump). F5 — reset() parity: Windows NVENC (teardown + lazy re-init), Linux VAAPI (drop-inner), Linux NVENC (reopen from stored OpenArgs) now give the stall watchdog a heal lever instead of ending the session. F6 — sw.rs `pending: VecDeque` (was `Option`), killing the silent AU drop at capturer pipeline depth > 1. F7 — doc sweep on the RFI/anchor comments. Verified: punktfunk-core lib tests (macOS + Linux), full punktfunk-host suite on Linux (RTX 5070 Ti), Windows compile. Owed: the on-glass client matrix (F2 freeze A/B, AMF LTR spike across a bitrate rebuild). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-12 11:17:19 +02:00
parent 0dc414f197
commit fdda7144ed
15 changed files with 801 additions and 152 deletions
@@ -375,14 +375,29 @@ struct RfiRecovery {
    last_req: Option<Instant>,
 }

+/// What a forward gap should ask the host for: a precise RFI for a recoverable range, a plain
+/// keyframe for a range wider than any encoder's reference history
+/// ([`crate::packet::RFI_MAX_RANGE`] — a seconds-long outage, or a phantom index jump such as an
+/// old host's speed-test burst consuming video indexes), or nothing (contiguous / straggler /
+/// throttled).
+#[derive(Debug, PartialEq, Eq)]
+enum RecoveryAsk {
+    None,
+    Rfi(u32, u32),
+    Keyframe,
+}
+
 impl RfiRecovery {
    /// Pure decision behind [`NativeClient::note_frame_index`]: fold one received `frame_index` (in
-    /// receive order) observed at `now`, advancing the expectation and returning
-    /// `(gap, rfi_range)`. `gap` is whether this frame revealed a forward gap; `rfi_range` is
-    /// `Some((first_missing, last_missing))` when a (throttled) RFI should fire for the lost span, or
-    /// `None` when contiguous, a straggler, or throttled. Split out from the connection so the wrapping
-    /// arithmetic + [`RFI_THROTTLE`] are unit-testable without a live session (see the tests below).
-    fn observe(&mut self, frame_index: u32, now: Instant) -> (bool, Option<(u32, u32)>) {
+    /// receive order) observed at `now`, advancing the expectation and returning `(gap, ask)`.
+    /// `gap` is whether this frame revealed a forward gap (the embedder arms its post-loss display
+    /// freeze on it); `ask` is the (throttled) recovery request to fire — an RFI naming the exact
+    /// lost span, or a keyframe when the span exceeds [`crate::packet::RFI_MAX_RANGE`] (RFI is
+    /// hopeless there: no encoder holds references that old, and a huge jump is more likely a
+    /// resync — e.g. the first real AU after an old host's speed test — than a real loss). Split
+    /// out from the connection so the wrapping arithmetic + [`RFI_THROTTLE`] are unit-testable
+    /// without a live session (see the tests below).
+    fn observe(&mut self, frame_index: u32, now: Instant) -> (bool, RecoveryAsk) {
        match self.next_expected {
            Some(exp) => {
                // Wrapping split at the half-space: a small positive delta is a forward gap
@@ -390,10 +405,10 @@ impl RfiRecovery {
                let ahead = frame_index.wrapping_sub(exp);
                if ahead == 0 {
                    self.next_expected = Some(frame_index.wrapping_add(1)); // contiguous
-                    (false, None)
+                    (false, RecoveryAsk::None)
                } else if ahead < u32::MAX / 2 {
                    // Forward gap: [exp, frame_index-1] lost. Advance past this frame so the same
-                    // gap isn't re-detected, then fire a throttled RFI for the lost range.
+                    // gap isn't re-detected, then fire a throttled recovery ask for the lost range.
                    self.next_expected = Some(frame_index.wrapping_add(1));
                    let send = self
                        .last_req
@@ -401,15 +416,22 @@ impl RfiRecovery {
                    if send {
                        self.last_req = Some(now);
                    }
-                    let range = send.then(|| (exp, frame_index.wrapping_sub(1)));
-                    (true, range)
+                    let ask = if !send {
+                        RecoveryAsk::None
+                    } else if ahead > crate::packet::RFI_MAX_RANGE {
+                        RecoveryAsk::Keyframe
+                    } else {
+                        RecoveryAsk::Rfi(exp, frame_index.wrapping_sub(1))
+                    };
+                    (true, ask)
                } else {
-                    (false, None) // straggler behind the delivery point — leave the expectation
+                    // Straggler behind the delivery point — leave the expectation.
+                    (false, RecoveryAsk::None)
                }
            }
            None => {
                self.next_expected = Some(frame_index.wrapping_add(1));
-                (false, None)
+                (false, RecoveryAsk::None)
            }
        }
    }
@@ -970,13 +992,21 @@ impl NativeClient {
    /// signal and shares one throttle across RFI + keyframe requests.)
    pub fn note_frame_index(&self, frame_index: u32) -> bool {
        // Decide (and update state) under the lock; fire the request after releasing it.
-        let (gap, rfi_range) = self
+        let (gap, ask) = self
            .rfi
            .lock()
            .unwrap()
            .observe(frame_index, Instant::now());
-        if let Some((first, last)) = rfi_range {
-            let _ = self.request_rfi(first, last);
+        match ask {
+            RecoveryAsk::Rfi(first, last) => {
+                let _ = self.request_rfi(first, last);
+            }
+            // A gap wider than any encoder's reference history (RFI_MAX_RANGE) — a seconds-long
+            // outage or a phantom index jump: RFI can't repair it, resync on a keyframe instead.
+            RecoveryAsk::Keyframe => {
+                let _ = self.request_keyframe();
+            }
+            RecoveryAsk::None => {}
        }
        gap
    }
@@ -1410,7 +1440,12 @@ async fn worker_main(args: WorkerArgs) {
                // when the matching bit is set, so `0` stays an 8-bit BT.709 stream. HOST_TIMING is
                // OR'd in unconditionally: every NativeClient build demuxes the 0xCF plane, and the
                // bit only asks the host for observability datagrams (never changes the encode).
-                video_caps: video_caps | crate::quic::VIDEO_CAP_HOST_TIMING,
+                // PROBE_SEQ likewise: the shared reassembler keeps probe filler in its own window
+                // (every embedder inherits it), so the host may burst speed tests without consuming
+                // video frame indexes.
+                video_caps: video_caps
+                    | crate::quic::VIDEO_CAP_HOST_TIMING
+                    | crate::quic::VIDEO_CAP_PROBE_SEQ,
                // Requested surround channel count; the host echoes the resolved value in Welcome.
                audio_channels,
                // The codecs this client can decode + its soft preference (0 = auto). The host
@@ -2071,7 +2106,7 @@ mod rfi_recovery_tests {
    //! The client-side loss-range detector shared by every embedder (Android, the C-ABI Apple
    //! client, the Windows shell pump). `observe` is pure over `(frame_index, now)`, so the wrapping
    //! frame arithmetic and the RFI throttle are exercised here without a live session.
-    use super::{RfiRecovery, RFI_THROTTLE};
+    use super::{RecoveryAsk, RfiRecovery, RFI_THROTTLE};
    use std::time::{Duration, Instant};

    // A fixed base instant; offsets model the throttle window deterministically (no sleeping).
@@ -2083,7 +2118,7 @@ mod rfi_recovery_tests {
    fn first_frame_arms_without_a_gap() {
        let mut r = RfiRecovery::default();
        // The opening frame only seeds the expectation — there is no prior frame to be missing.
-        assert_eq!(r.observe(100, base()), (false, None));
+        assert_eq!(r.observe(100, base()), (false, RecoveryAsk::None));
        assert_eq!(r.next_expected, Some(101));
    }

@@ -2092,9 +2127,9 @@ mod rfi_recovery_tests {
        let mut r = RfiRecovery::default();
        let t = base();
        r.observe(100, t);
-        assert_eq!(r.observe(101, t), (false, None));
-        assert_eq!(r.observe(102, t), (false, None));
-        assert_eq!(r.observe(103, t), (false, None));
+        assert_eq!(r.observe(101, t), (false, RecoveryAsk::None));
+        assert_eq!(r.observe(102, t), (false, RecoveryAsk::None));
+        assert_eq!(r.observe(103, t), (false, RecoveryAsk::None));
        assert_eq!(r.next_expected, Some(104));
    }

@@ -2104,7 +2139,7 @@ mod rfi_recovery_tests {
        let t = base();
        r.observe(100, t); // expecting 101 next
                           // 101..=104 were lost; 105 arrived. The RFI must name exactly the missing span.
-        assert_eq!(r.observe(105, t), (true, Some((101, 104))));
+        assert_eq!(r.observe(105, t), (true, RecoveryAsk::Rfi(101, 104)));
        // The expectation advances past the delivered frame so the same gap can't re-fire.
        assert_eq!(r.next_expected, Some(106));
    }
@@ -2115,7 +2150,7 @@ mod rfi_recovery_tests {
        let t = base();
        r.observe(100, t);
        // Exactly one frame (101) lost → range is the single index [101, 101].
-        assert_eq!(r.observe(102, t), (true, Some((101, 101))));
+        assert_eq!(r.observe(102, t), (true, RecoveryAsk::Rfi(101, 101)));
    }

    #[test]
@@ -2124,13 +2159,16 @@ mod rfi_recovery_tests {
        let t0 = base();
        r.observe(100, t0);
        // First gap fires the request and stamps the throttle.
-        assert_eq!(r.observe(105, t0), (true, Some((101, 104))));
+        assert_eq!(r.observe(105, t0), (true, RecoveryAsk::Rfi(101, 104)));
        // A second gap 50 ms later is still a gap, but the request is throttled away.
-        assert_eq!(r.observe(110, t0 + Duration::from_millis(50)), (true, None));
+        assert_eq!(
+            r.observe(110, t0 + Duration::from_millis(50)),
+            (true, RecoveryAsk::None)
+        );
        // Past the window, the request re-opens for the still-accurate lost span.
        assert_eq!(
            r.observe(120, t0 + RFI_THROTTLE + Duration::from_millis(1)),
-            (true, Some((111, 119)))
+            (true, RecoveryAsk::Rfi(111, 119))
        );
    }

@@ -2142,7 +2180,7 @@ mod rfi_recovery_tests {
        r.observe(105, t); // expecting 106 next
                           // A reordered late arrival (103, well behind 106) is neither a gap nor a request, and it
                           // must not rewind the expectation — otherwise the next in-order frame would false-gap.
-        assert_eq!(r.observe(103, t), (false, None));
+        assert_eq!(r.observe(103, t), (false, RecoveryAsk::None));
        assert_eq!(r.next_expected, Some(106));
    }

@@ -2151,9 +2189,9 @@ mod rfi_recovery_tests {
        let mut r = RfiRecovery::default();
        let t = base();
        r.observe(u32::MAX - 1, t); // expecting u32::MAX next
-        assert_eq!(r.observe(u32::MAX, t), (false, None)); // contiguous, expectation wraps to 0
+        assert_eq!(r.observe(u32::MAX, t), (false, RecoveryAsk::None)); // contiguous, wraps to 0
        assert_eq!(r.next_expected, Some(0));
-        assert_eq!(r.observe(0, t), (false, None)); // still contiguous across the wrap
+        assert_eq!(r.observe(0, t), (false, RecoveryAsk::None)); // still contiguous across the wrap
        assert_eq!(r.next_expected, Some(1));
    }

@@ -2163,9 +2201,29 @@ mod rfi_recovery_tests {
        let t = base();
        r.observe(u32::MAX - 1, t); // expecting u32::MAX next
                                    // u32::MAX was lost and 1 arrived → the lost span wraps: [u32::MAX, 0].
-        assert_eq!(r.observe(1, t), (true, Some((u32::MAX, 0))));
+        assert_eq!(r.observe(1, t), (true, RecoveryAsk::Rfi(u32::MAX, 0)));
        assert_eq!(r.next_expected, Some(2));
    }
+
+    #[test]
+    fn huge_gap_resyncs_via_keyframe_not_rfi() {
+        let mut r = RfiRecovery::default();
+        let t = base();
+        r.observe(100, t); // expecting 101 next
+                           // A jump wider than any encoder's reference history (RFI_MAX_RANGE): no valid
+                           // reference exists for an RFI, and the jump may be a phantom (an old host's
+                           // speed-test burst consuming video indexes) — ask for the IDR resync instead.
+        let jump = 100 + crate::packet::RFI_MAX_RANGE + 2;
+        assert_eq!(r.observe(jump, t), (true, RecoveryAsk::Keyframe));
+        // The expectation still advances past the delivered frame (no re-fire on the next one).
+        assert_eq!(r.next_expected, Some(jump + 1));
+        assert_eq!(r.observe(jump + 1, t), (false, RecoveryAsk::None));
+        // A huge gap consumes the shared throttle too — an immediate follow-up gap stays quiet.
+        assert_eq!(
+            r.observe(jump + 10, t + Duration::from_millis(1)),
+            (true, RecoveryAsk::None)
+        );
+    }
 }

 #[cfg(test)]
@@ -54,6 +54,15 @@ pub const USER_FLAG_RECOVERY_POINT: u32 = 0x10;
 /// `AV_FRAME_FLAG_KEY` — this host flag is the only signal.
 pub const USER_FLAG_RECOVERY_ANCHOR: u32 = 0x20;

+/// Widest lost-frame range (frames, wrapping `last - first`) a reference-frame-invalidation
+/// recovery may be asked to repair; anything wider goes straight to the keyframe path on BOTH
+/// ends. RFI can only re-reference history the encoder still holds — NVENC keeps a 5-frame DPB,
+/// AMD LTR ~1 s of marks — and a genuine loss this wide (>1 s even at 240 fps) has no valid
+/// reference anywhere, so an RFI request for it is either hopeless or (worse) a phantom range
+/// from a desynced counter. Shared by the host's RFI dispatch (range → keyframe fallback) and the
+/// client-side gap detectors (huge gap → resync + keyframe request, no RFI).
+pub const RFI_MAX_RANGE: u32 = 256;
+
 /// Crypto framing overhead [`Session`](crate::session::Session) adds when encrypting:
 /// an 8-byte sequence prefix plus the GCM tag.
 pub const CRYPTO_OVERHEAD: usize = 8 + crate::crypto::TAG_LEN;
@@ -117,8 +126,18 @@ const _: () = assert!(HEADER_LEN == 40, "PacketHeader must be 40 bytes / unpadde
 // ---------------------------------------------------------------------------

 /// Splits encoded access units into FEC-protected shard packets. Host-side only.
+///
+/// Frame numbering: a caller can pass an **explicit** `frame_index` to
+/// [`packetize_each`](Self::packetize_each) (the punktfunk/1 encode loop owns the video numbering
+/// so the encoder's reference-frame-invalidation bookkeeping stays 1:1 with the wire across
+/// encoder rebuilds/resets), or pass `None` to draw from the internal counter (the legacy path —
+/// synthetic/spike/ABI sessions where no encoder cares). Speed-test probe filler draws from a
+/// **separate** index space ([`alloc_probe_index`](Self::alloc_probe_index)) so a burst never
+/// consumes video indexes — see [`crate::quic::VIDEO_CAP_PROBE_SEQ`].
 pub struct Packetizer {
    next_frame_index: u32,
+    /// Probe-space frame counter (see [`alloc_probe_index`](Self::alloc_probe_index)).
+    next_probe_index: u32,
    next_seq: u32,
    shard_payload: usize,
    fec: crate::config::FecConfig,
@@ -134,6 +153,7 @@ impl Packetizer {
    pub fn new(config: &Config) -> Self {
        Packetizer {
            next_frame_index: 0,
+            next_probe_index: 0,
            next_seq: 0,
            shard_payload: config.shard_payload,
            fec: config.fec,
@@ -142,6 +162,17 @@ impl Packetizer {
        }
    }

+    /// Allocate the next **probe-space** frame index (speed-test filler). A separate counter from
+    /// the video `frame_index`es so a multi-thousand-AU probe burst never advances the video
+    /// numbering — the client routes [`FLAG_PROBE`]-flagged shards into its own reassembly window
+    /// (see [`Reassembler`]), so the two spaces never collide. Only used against clients that
+    /// advertise [`crate::quic::VIDEO_CAP_PROBE_SEQ`].
+    pub fn alloc_probe_index(&mut self) -> u32 {
+        let i = self.next_probe_index;
+        self.next_probe_index = i.wrapping_add(1);
+        i
+    }
+
    /// Live-adjust the FEC recovery percentage (adaptive FEC). Takes effect on the next
    /// [`packetize`](Self::packetize); the wire is self-describing (each packet carries its block's
    /// data/recovery counts), so the receiver needs no notification. Clamped to ≤ 90.
@@ -165,7 +196,7 @@ impl Packetizer {
        coder: &dyn ErasureCoder,
    ) -> Result<Vec<Vec<u8>>> {
        let mut packets = Vec::new();
-        self.packetize_each(frame, pts_ns, user_flags, coder, |hdr, body| {
+        self.packetize_each(frame, pts_ns, user_flags, None, coder, |hdr, body| {
            let mut pkt = Vec::with_capacity(HEADER_LEN + body.len());
            pkt.extend_from_slice(hdr.as_bytes());
            pkt.extend_from_slice(body);
@@ -181,17 +212,27 @@ impl Packetizer {
    /// shard straight into a pooled wire buffer and seal in place
    /// ([`Session::seal_frame`](crate::session::Session::seal_frame)). An `emit` error aborts
    /// the frame mid-way (packet numbering has already advanced — callers treat it as fatal).
+    ///
+    /// `frame_index`: `Some(i)` stamps the AU with the caller's index — the punktfunk/1 encode
+    /// loop numbers video AUs itself so the encoder's RFI bookkeeping (LTR marks, DPB timestamps)
+    /// is 1:1 with what the client sees, surviving encoder rebuilds/resets that restart internal
+    /// counters. `None` draws from the internal counter (the legacy/self-numbering path). A
+    /// session must not mix the two styles for the same index space.
    pub fn packetize_each(
        &mut self,
        frame: &[u8],
        pts_ns: u64,
        user_flags: u32,
+        frame_index: Option<u32>,
        coder: &dyn ErasureCoder,
        mut emit: impl FnMut(&PacketHeader, &[u8]) -> Result<()>,
    ) -> Result<()> {
        let payload = self.shard_payload;
-        let frame_index = self.next_frame_index;
-        self.next_frame_index = self.next_frame_index.wrapping_add(1);
+        let frame_index = frame_index.unwrap_or_else(|| {
+            let i = self.next_frame_index;
+            self.next_frame_index = i.wrapping_add(1);
+            i
+        });

        // At least one (zero-padded) data shard even for an empty frame.
        let total_data = frame.len().div_ceil(payload).max(1);
@@ -343,10 +384,13 @@ impl ReassemblerLimits {
    }
 }

-/// Buffers incoming shards, recovers lost ones via FEC, and emits whole access units.
-/// Client-side only.
-pub struct Reassembler {
-    limits: ReassemblerLimits,
+/// One frame-index space's reassembly state: the in-flight frames, the recently-emitted memory,
+/// and the loss-window anchor. The [`Reassembler`] keeps two — video and speed-test probe filler —
+/// because the two ride **separate index counters** on a [`VIDEO_CAP_PROBE_SEQ`]-aware host
+/// (a probe burst must neither advance the video loss window nor be dropped as "stale" against
+/// it). [`VIDEO_CAP_PROBE_SEQ`]: crate::quic::VIDEO_CAP_PROBE_SEQ
+#[derive(Default)]
+struct ReassemblyWindow {
    frames: HashMap<u32, FrameBuf>,
    /// Recently-emitted frames, so stray/late shards can't resurrect them. Pruned to
    /// the reorder window alongside `frames`.
@@ -357,13 +401,27 @@ pub struct Reassembler {
    newest_frame: Option<(u32, u64)>,
 }

+/// Buffers incoming shards, recovers lost ones via FEC, and emits whole access units.
+/// Client-side only.
+pub struct Reassembler {
+    limits: ReassemblerLimits,
+    /// The video stream's window — its aged-out incomplete frames count into `frames_dropped`
+    /// (the client's loss-recovery trigger).
+    video: ReassemblyWindow,
+    /// Speed-test probe filler ([`FLAG_PROBE`] in `user_flags`). Routed by the flag, so it also
+    /// captures an OLD host's probe frames (which still carry video-space indexes — they complete
+    /// fine here, and keeping them out of the video window means a burst can no longer advance the
+    /// video loss anchor). Aged-out probe frames are NOT `frames_dropped` — probe loss is measured
+    /// bytes-wise by the probe accumulator and must not fire video recovery.
+    probe: ReassemblyWindow,
+}
+
 impl Reassembler {
    pub fn new(limits: ReassemblerLimits) -> Self {
        Reassembler {
            limits,
-            frames: HashMap::new(),
-            completed: HashSet::new(),
-            newest_frame: None,
+            video: ReassemblyWindow::default(),
+            probe: ReassemblyWindow::default(),
        }
    }

@@ -424,18 +482,28 @@ impl Reassembler {
        }
        let payload = pkt[HEADER_LEN..HEADER_LEN + shard_bytes].to_vec();

-        self.advance_window(hdr.frame_index, hdr.pts_ns, stats);
+        // Route by index space: speed-test probe filler (FLAG_PROBE in user_flags) reassembles in
+        // its own window so its indexes never interact with the video loss window — a probe burst
+        // can neither advance the video anchor nor be dropped as stale against it (and its aged-out
+        // frames never count as `frames_dropped`, which would fire video loss recovery).
+        let is_probe = hdr.user_flags & (FLAG_PROBE as u32) != 0;
+        let win = if is_probe {
+            &mut self.probe
+        } else {
+            &mut self.video
+        };
+        win.advance_window(hdr.frame_index, hdr.pts_ns, stats, !is_probe);

        // Drop shards for frames we've already emitted (e.g. the recovery shards of a
        // frame that completed early via the all-originals-present fast path) or that
        // have fallen out of the loss window.
-        if self.completed.contains(&hdr.frame_index) || self.is_stale(hdr.frame_index, hdr.pts_ns) {
+        if win.completed.contains(&hdr.frame_index) || win.is_stale(hdr.frame_index, hdr.pts_ns) {
            drop(stats);
            return Ok(None);
        }

        // First packet of a frame establishes its geometry; later packets must agree.
-        let frame = self
+        let frame = win
            .frames
            .entry(hdr.frame_index)
            .or_insert_with(|| FrameBuf {
@@ -521,8 +589,8 @@ impl Reassembler {

        // Whole frame ready?
        if frame.block_data.len() == frame.block_count {
-            let frame = self.frames.remove(&hdr.frame_index).unwrap();
-            self.completed.insert(hdr.frame_index);
+            let frame = win.frames.remove(&hdr.frame_index).unwrap();
+            win.completed.insert(hdr.frame_index);
            // Reserve based on the bytes we actually hold, not the (already-bounded but
            // still caller-supplied) frame_bytes, so a small frame can't over-reserve.
            let actual: usize = frame.block_data.values().map(|b| b.len()).sum();
@@ -541,11 +609,30 @@ impl Reassembler {
        Ok(None)
    }

+    /// Drop all in-flight state — every partially-assembled frame and the completed/abandoned
+    /// index memory, in both index spaces — as if the session just started. Used by the client's
+    /// backlog flush ([`Session::flush_backlog`](crate::session::Session::flush_backlog)): after
+    /// the socket backlog is discarded wholesale, the partial frames here can never complete
+    /// (their remaining shards were just thrown away) and the window anchors (`newest_frame`)
+    /// point into the discarded past.
+    pub fn reset(&mut self) {
+        self.video = ReassemblyWindow::default();
+        self.probe = ReassemblyWindow::default();
+    }
+}
+
+impl ReassemblyWindow {
    /// Track the newest frame, declare incomplete frames that fell out of the loss window
-    /// ([`LOSS_WINDOW_NS`] behind the newest pts, or [`HARD_LOSS_WINDOW`] indices) lost — counting
-    /// them dropped, which is what drives the client's recovery-keyframe request — and prune the
-    /// completed-index memory to [`REORDER_WINDOW`].
-    fn advance_window(&mut self, frame_index: u32, pts_ns: u64, stats: &StatsCounters) {
+    /// ([`LOSS_WINDOW_NS`] behind the newest pts, or [`HARD_LOSS_WINDOW`] indices) lost — for the
+    /// video window (`count_drops`) counting them dropped, which is what drives the client's
+    /// recovery-keyframe request — and prune the completed-index memory to [`REORDER_WINDOW`].
+    fn advance_window(
+        &mut self,
+        frame_index: u32,
+        pts_ns: u64,
+        stats: &StatsCounters,
+        count_drops: bool,
+    ) {
        let (newest, newest_pts) = match self.newest_frame {
            // `frame_index` is newer iff it's within the forward half of the index space.
            Some((n, p)) if frame_index.wrapping_sub(n) > u32::MAX / 2 => (n, p),
@@ -567,29 +654,17 @@ impl Reassembler {
            keep
        });
        let pruned = before - self.frames.len();
-        if pruned > 0 {
+        if pruned > 0 && count_drops {
            StatsCounters::add(&stats.frames_dropped, pruned as u64);
        }
        self.completed
            .retain(|&idx| newest.wrapping_sub(idx) <= REORDER_WINDOW);
    }

-    /// Drop all in-flight state — every partially-assembled frame and the completed/abandoned
-    /// index memory — as if the session just started. Used by the client's backlog flush
-    /// ([`Session::flush_backlog`](crate::session::Session::flush_backlog)): after the socket
-    /// backlog is discarded wholesale, the partial frames here can never complete (their remaining
-    /// shards were just thrown away) and the window anchor (`newest_frame`) points into the
-    /// discarded past.
-    pub fn reset(&mut self) {
-        self.frames.clear();
-        self.completed.clear();
-        self.newest_frame = None;
-    }
-
    /// True if this packet's frame lies outside the loss window (behind the newest frame by more
    /// than [`LOSS_WINDOW_NS`] of capture time or [`HARD_LOSS_WINDOW`] indices) — its shards
    /// arrive too late to be useful, and accepting one would only create a frame buffer the next
-    /// [`advance_window`] immediately declares lost.
+    /// [`advance_window`](Self::advance_window) immediately declares lost.
    fn is_stale(&self, frame_index: u32, pts_ns: u64) -> bool {
        match self.newest_frame {
            Some((n, newest_pts)) => {
@@ -769,6 +844,119 @@ mod tests {
        assert_eq!(stats.snapshot().frames_dropped, 1, "no double-count");
    }

+    /// The explicit-index path stamps the caller's `frame_index` and leaves the internal video
+    /// counter untouched — the punktfunk/1 encode loop owns the numbering, and mixing must not
+    /// perturb the legacy self-numbering path (tests/ABI/synthetic).
+    #[test]
+    fn explicit_frame_index_is_stamped_and_internal_counter_untouched() {
+        use crate::config::{FecConfig, FecScheme, ProtocolPhase, Role};
+        let cfg = Config {
+            role: Role::Host,
+            phase: ProtocolPhase::P2Punktfunk,
+            fec: FecConfig {
+                scheme: FecScheme::Gf16,
+                fec_percent: 0,
+                max_data_per_block: 8,
+            },
+            shard_payload: 16,
+            max_frame_bytes: 4096,
+            encrypt: false,
+            key: [0u8; 16],
+            salt: [0u8; 4],
+            loopback_drop_period: 0,
+        };
+        let coder = coder_for(FecScheme::Gf16);
+        let mut pk = Packetizer::new(&cfg);
+        let mut seen = Vec::new();
+        pk.packetize_each(&[1u8; 16], 0, 0, Some(4242), coder.as_ref(), |hdr, _| {
+            seen.push(hdr.frame_index);
+            Ok(())
+        })
+        .unwrap();
+        assert_eq!(seen, vec![4242]);
+        // The legacy wrapper still numbers from the untouched internal counter.
+        let pkts = pk.packetize(&[1u8; 16], 0, 0, coder.as_ref()).unwrap();
+        let hdr = PacketHeader::read_from_bytes(&pkts[0][..HEADER_LEN]).unwrap();
+        assert_eq!(hdr.frame_index, 0);
+        // The probe space is a third, independent counter.
+        assert_eq!(pk.alloc_probe_index(), 0);
+        assert_eq!(pk.alloc_probe_index(), 1);
+    }
+
+    /// Probe filler (FLAG_PROBE in user_flags) reassembles in its OWN window: a probe frame whose
+    /// index is far behind the video stream's completes anyway (an old client's single window
+    /// would drop it as stale), and video frames complete undisturbed around it.
+    #[test]
+    fn probe_frames_reassemble_in_their_own_window() {
+        let mut r = Reassembler::new(limits());
+        let coder = coder_for(FecScheme::Gf8);
+        let stats = StatsCounters::default();
+
+        // Establish a video stream far into its index space.
+        let mut v = base_header();
+        v.frame_index = 100_000;
+        v.pts_ns = 1_000_000_000;
+        assert!(r
+            .push(&packet(v), coder.as_ref(), &stats)
+            .unwrap()
+            .is_some());
+
+        // A probe frame at index 0 — 100k "behind" the video window — must still complete.
+        let mut p = base_header();
+        p.frame_index = 0;
+        p.pts_ns = 1_000_000_100;
+        p.user_flags = FLAG_PROBE as u32;
+        let got = r.push(&packet(p), coder.as_ref(), &stats).unwrap();
+        assert!(got.is_some(), "probe frame must complete in its own window");
+        assert_eq!(got.unwrap().flags & FLAG_PROBE as u32, FLAG_PROBE as u32);
+
+        // The probe burst must not have advanced the VIDEO window: the next video frame is
+        // contiguous and completes, with nothing counted dropped.
+        let mut v2 = base_header();
+        v2.frame_index = 100_001;
+        v2.pts_ns = 1_000_000_200;
+        assert!(r
+            .push(&packet(v2), coder.as_ref(), &stats)
+            .unwrap()
+            .is_some());
+        assert_eq!(stats.snapshot().frames_dropped, 0);
+    }
+
+    /// An incomplete probe frame aging out of the probe window is NOT a video `frames_dropped`
+    /// (which would fire the client's loss recovery) — probe loss is measured bytes-wise by the
+    /// probe accumulator.
+    #[test]
+    fn aged_out_probe_frames_do_not_count_as_dropped() {
+        let mut r = Reassembler::new(limits());
+        let coder = coder_for(FecScheme::Gf8);
+        let stats = StatsCounters::default();
+
+        // Probe frame 0: one of two shards — incomplete.
+        let mut p = base_header();
+        p.user_flags = FLAG_PROBE as u32;
+        p.data_shards = 2;
+        p.frame_bytes = 32;
+        assert!(r
+            .push(&packet(p), coder.as_ref(), &stats)
+            .unwrap()
+            .is_none());
+
+        // A much newer probe frame ages it out of the probe window.
+        let mut p2 = base_header();
+        p2.user_flags = FLAG_PROBE as u32;
+        p2.frame_index = 1;
+        p2.pts_ns = LOSS_WINDOW_NS + 1;
+        assert!(r
+            .push(&packet(p2), coder.as_ref(), &stats)
+            .unwrap()
+            .is_some());
+        assert_eq!(
+            stats.snapshot().frames_dropped,
+            0,
+            "probe-window drops must not fire video loss recovery"
+        );
+    }
+
    #[test]
    fn rejects_wrong_shard_bytes_and_oversized_frame() {
        let coder = coder_for(FecScheme::Gf8);
@@ -107,6 +107,18 @@ pub const VIDEO_CAP_444: u8 = 0x04;
 /// host ignores it and simply never sends any); a client that doesn't set it keeps the combined
 /// stage. Purely observability — never changes what the host encodes.
 pub const VIDEO_CAP_HOST_TIMING: u8 = 0x08;
+/// [`Hello::video_caps`] bit: the client's reassembler keeps **speed-test probe filler in its own
+/// frame-index space** (a second reassembly window keyed on the [`crate::packet::FLAG_PROBE`]
+/// user-flag), so probe bursts no longer consume video `frame_index`es. Without this, a mid-session
+/// speed test burns thousands of video indexes that are invisible to every client-side gap detector
+/// (probe frames are filtered before the pump sees them) — the first real AU afterwards reads as a
+/// phantom multi-thousand-frame loss (spurious freeze + a nonsense RFI). It also lets the host's
+/// encode loop own the video numbering outright (the wire-index contract
+/// [`crate::packet::Packetizer::packetize_each`] documents), which reference-frame invalidation
+/// depends on. The host runs mid-session probe bursts ONLY against clients that set this bit — an
+/// older client gets a declined (zeroed) [`ProbeResult`] instead of a measurement its single-window
+/// reassembler would silently drop as stale.
+pub const VIDEO_CAP_PROBE_SEQ: u8 = 0x10;

 /// QUIC application error code a punktfunk/1 client closes the control connection with on a
 /// **deliberate quit** (a user "stop", not a network drop). The host reads it off the connection's
@@ -161,6 +161,31 @@ impl Session {
        data: &[u8],
        pts_ns: u64,
        user_flags: u32,
+    ) -> Result<Vec<Vec<u8>>> {
+        self.seal_frame_inner(data, pts_ns, user_flags, None)
+    }
+
+    /// [`seal_frame`](Self::seal_frame) with the caller's **explicit** `frame_index` instead of the
+    /// packetizer's internal counter. The punktfunk/1 encode loop owns the video numbering (one
+    /// session-lifetime counter, stamped per AU) so the encoder's reference-frame-invalidation
+    /// bookkeeping stays 1:1 with the wire across encoder rebuilds/resets — see
+    /// [`Packetizer::packetize_each`]. A session must use ONE numbering style per index space.
+    pub fn seal_frame_at(
+        &mut self,
+        data: &[u8],
+        pts_ns: u64,
+        user_flags: u32,
+        frame_index: u32,
+    ) -> Result<Vec<Vec<u8>>> {
+        self.seal_frame_inner(data, pts_ns, user_flags, Some(frame_index))
+    }
+
+    fn seal_frame_inner(
+        &mut self,
+        data: &[u8],
+        pts_ns: u64,
+        user_flags: u32,
+        frame_index: Option<u32>,
    ) -> Result<Vec<Vec<u8>>> {
        if self.config.role != Role::Host {
            return Err(PunktfunkError::InvalidArg(
@@ -184,35 +209,36 @@ impl Session {
        } = self;
        let mut wires = std::mem::take(wire_pool);
        let mut used = 0usize;
-        let result = packetizer.packetize_each(data, pts_ns, user_flags, coder.as_ref(), {
-            let wires = &mut wires;
-            let used = &mut used;
-            move |hdr, body| {
-                if *used == wires.len() {
-                    wires.push(Vec::new());
-                }
-                let wire = &mut wires[*used];
-                *used += 1;
-                let seq = *next_seq;
-                *next_seq = next_seq.wrapping_add(1);
-                wire.clear();
-                match crypto {
-                    Some(c) => {
-                        // seq(8) ‖ header(40) ‖ shard ‖ tag scratch(16), sealed over [8..].
-                        wire.extend_from_slice(&seq.to_be_bytes());
-                        wire.extend_from_slice(hdr.as_bytes());
-                        wire.extend_from_slice(body);
-                        wire.resize(wire.len() + crate::crypto::TAG_LEN, 0);
-                        c.seal_in_place(seq, &mut wire[8..])?;
+        let result =
+            packetizer.packetize_each(data, pts_ns, user_flags, frame_index, coder.as_ref(), {
+                let wires = &mut wires;
+                let used = &mut used;
+                move |hdr, body| {
+                    if *used == wires.len() {
+                        wires.push(Vec::new());
                    }
-                    None => {
-                        wire.extend_from_slice(hdr.as_bytes());
-                        wire.extend_from_slice(body);
+                    let wire = &mut wires[*used];
+                    *used += 1;
+                    let seq = *next_seq;
+                    *next_seq = next_seq.wrapping_add(1);
+                    wire.clear();
+                    match crypto {
+                        Some(c) => {
+                            // seq(8) ‖ header(40) ‖ shard ‖ tag scratch(16), sealed over [8..].
+                            wire.extend_from_slice(&seq.to_be_bytes());
+                            wire.extend_from_slice(hdr.as_bytes());
+                            wire.extend_from_slice(body);
+                            wire.resize(wire.len() + crate::crypto::TAG_LEN, 0);
+                            c.seal_in_place(seq, &mut wire[8..])?;
+                        }
+                        None => {
+                            wire.extend_from_slice(hdr.as_bytes());
+                            wire.extend_from_slice(body);
+                        }
                    }
+                    Ok(())
                }
-                Ok(())
-            }
-        });
+            });
        result?;
        // A smaller frame uses fewer buffers than the pool holds: drop the unused tail, same
        // as the previous `resize_with(packets.len(), ..)` did.
@@ -258,6 +284,23 @@ impl Session {
        r.map(|_| ())
    }

+    /// Host: seal + send one **speed-test probe filler** access unit in the probe index space
+    /// (its own frame counter + the [`crate::packet::FLAG_PROBE`] user-flag) so a burst never
+    /// consumes video `frame_index`es — the client reassembles probe frames in a separate window
+    /// and its gap detectors never see them. Only call this against a client that advertised
+    /// [`crate::quic::VIDEO_CAP_PROBE_SEQ`]; an older client's single-window reassembler would
+    /// drop probe-space indexes as stale against the video stream.
+    pub fn submit_probe_frame(&mut self, data: &[u8], pts_ns: u64) -> Result<()> {
+        let idx = self.packetizer.alloc_probe_index();
+        let wires =
+            self.seal_frame_inner(data, pts_ns, crate::packet::FLAG_PROBE as u32, Some(idx))?;
+        let refs: Vec<&[u8]> = wires.iter().map(|w| w.as_slice()).collect();
+        let r = self.send_sealed(&refs);
+        drop(refs);
+        self.reclaim_wires(wires);
+        r.map(|_| ())
+    }
+
    /// Host: live-adjust the FEC recovery percentage (adaptive FEC). Affects the next
    /// [`submit_frame`](Self::submit_frame)/[`seal_frame`](Self::seal_frame); the receiver needs no
    /// notification (each packet's header carries its block's data/recovery shard counts).