feat(quic): step 1 of RFC 9002 retransmit — RecoveryToken + SentPacket types

First step of `quic/plans/2026-05-04-control-frame-retransmit.md`.
Pure type definitions, no behavior change yet — sets up the data
shape the next steps will populate from the writer (step 2) and
drain from ACK / loss-detection paths (steps 3–6).

RecoveryToken: sealed class mirroring neqo's
neqo-transport/src/recovery/token.rs:21 StreamRecoveryToken.

  - Ack (singleton object): tracked but never retransmitted, so the
    sent-packet map invariant ("every retained entry has at least
    one token") holds for ACK-only packets too
  - MaxStreamsUni / MaxStreamsBidi: receive-side stream-id cap
    extension (RFC 9000 §19.11) — the frame whose loss tripped
    the moq-rs cliff
  - MaxData: connection-level data cap extension (§19.9)
  - MaxStreamData: per-stream data cap extension (§19.10)

SentPacket: data class mirroring neqo's
neqo-transport/src/recovery/sent.rs::Packet. Held in a per-pn-space
map on QuicConnection (step 2 wires this up). Carries packet number,
send time, ack-eliciting flag, on-wire size, and the token list to
dispatch on loss.

Tests: 6 token tests (data-class equality, sealed-hierarchy
exhaustiveness, Ack singleton-ness) + 6 SentPacket tests (equality
across fields, copy semantics, ACK-only-with-Ack-token convention,
multi-token packet shape). All pass; full :quic test suite still
passes — types are purely additive.

Out of scope as documented in the plan: STREAM data retransmit,
CRYPTO retransmit, RESET_STREAM/STOP_SENDING/etc, congestion control,
0-RTT. Those are separate follow-ups.

https://claude.ai/code/session_01PYYez8a6sjiakyjAxsfCEQ

quic/src/commonMain/kotlin/com/vitorpamplona/quic/connection/recovery/RecoveryToken.kt

@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quic.connection.recovery
+
+/**
+ * RFC 9002 §6 retransmit token. One token is recorded per ack-eliciting
+ * frame at send time; the [SentPacket] carrying it is held in
+ * [com.vitorpamplona.quic.connection.QuicConnection]'s sent-packet map
+ * keyed by packet number.
+ *
+ * On ACK, the carrying packet's tokens are dropped silently — the peer
+ * has confirmed receipt. On loss declaration, each token is dispatched
+ * to its `onLost` handler, which decides whether the frame still needs
+ * to be re-emitted (e.g. a `MAX_STREAMS_UNI` whose value has since
+ * been superseded by a higher extension is not re-sent).
+ *
+ * Mirrors Firefox neqo's `StreamRecoveryToken` enum at
+ * `neqo-transport/src/recovery/token.rs:21`. Scope (per
+ * `quic/plans/2026-05-04-control-frame-retransmit.md`) is the
+ * receive-side flow-control extensions that today silently wedge the
+ * connection on packet loss against moq-rs:
+ *
+ *   - `MAX_STREAMS_UNI` / `MAX_STREAMS_BIDI` (RFC 9000 §19.11)
+ *   - `MAX_DATA` (§19.9)
+ *   - `MAX_STREAM_DATA` (§19.10)
+ *
+ * [Ack] is tracked but never retransmitted — ACK frames are not
+ * ack-eliciting per RFC 9000 §13.2.1, so their loss is recovered by
+ * the peer's own ACK retransmission of newer ranges.
+ *
+ * Out of scope (separate follow-ups, see plan):
+ *   - STREAM data retransmit
+ *   - CRYPTO data retransmit
+ *   - RESET_STREAM, STOP_SENDING, NEW_CONNECTION_ID, etc.
+ */
+sealed class RecoveryToken {
+    /**
+     * Marks an ACK frame in the carrying packet. Recorded so the
+     * sent-packet map's invariant ("every retained packet has a
+     * non-empty `tokens` list") holds for ACK-only packets too, but
+     * never re-emitted on loss.
+     */
+    data object Ack : RecoveryToken()
+
+    /**
+     * `MAX_STREAMS_UNI` extension we sent. On loss, only re-emit if
+     * [maxStreams] still equals the connection's current
+     * `advertisedMaxStreamsUni` — otherwise a newer extension has
+     * already gone out and supersedes this one.
+     */
+    data class MaxStreamsUni(
+        val maxStreams: Long,
+    ) : RecoveryToken()
+
+    /** Bidi counterpart of [MaxStreamsUni]. */
+    data class MaxStreamsBidi(
+        val maxStreams: Long,
+    ) : RecoveryToken()
+
+    /**
+     * Connection-level `MAX_DATA` extension. On loss, only re-emit
+     * if [maxData] still equals the connection's current
+     * `advertisedMaxData` — same supersede semantics as
+     * [MaxStreamsUni].
+     */
+    data class MaxData(
+        val maxData: Long,
+    ) : RecoveryToken()
+
+    /**
+     * Per-stream `MAX_STREAM_DATA` extension. On loss, the dispatcher
+     * looks up the stream by [streamId]; if the stream has since been
+     * closed or its advertised cap has moved past [maxData], the
+     * token is dropped without re-emit.
+     */
+    data class MaxStreamData(
+        val streamId: Long,
+        val maxData: Long,
+    ) : RecoveryToken()
+}

quic/src/commonMain/kotlin/com/vitorpamplona/quic/connection/recovery/SentPacket.kt

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quic.connection.recovery
+
+/**
+ * Per-packet metadata retained from send time until the packet is
+ * either ACK'd or declared lost. Mirrors Firefox neqo's
+ * `recovery/sent.rs::Packet`.
+ *
+ * Held in a per-packet-number-space map on
+ * [com.vitorpamplona.quic.connection.QuicConnection], keyed by
+ * [packetNumber]. On ACK arrival the matching entry is removed and
+ * its tokens dropped silently. On loss-detection (RFC 9002 §6.1)
+ * the entry is removed and each token is dispatched to its `onLost`
+ * handler, which decides whether to re-emit.
+ *
+ * [ackEliciting] determines whether the packet's loss matters at all
+ * for retransmit — non-ack-eliciting packets (ACK-only, PADDING-only,
+ * CONNECTION_CLOSE) are never retransmitted per RFC 9000 §13.2.1.
+ * They're still tracked so the loss-detection algorithm has consistent
+ * timing data, but their tokens are limited to [RecoveryToken.Ack].
+ *
+ * [sizeBytes] is the on-wire encrypted packet size; used by congestion
+ * control to release in-flight bytes when the packet is ACK'd or lost.
+ * Recorded here even though `:quic` has no congestion controller today
+ * — the field lets a future CC pass plug in without changing the
+ * sent-packet schema.
+ */
+data class SentPacket(
+    /** Packet number assigned at encrypt time. Unique within its space. */
+    val packetNumber: Long,
+    /**
+     * Wall-clock epoch milliseconds at the moment the packet was
+     * handed to the UDP socket. Source is
+     * [com.vitorpamplona.quic.connection.QuicConnection.nowMillis], not
+     * `System.currentTimeMillis` — keeps unit tests deterministic.
+     */
+    val sentAtMillis: Long,
+    /**
+     * RFC 9000 §13.2.1: whether the packet contains a frame that elicits
+     * an ACK from the peer. Loss detection only fires for ack-eliciting
+     * packets; non-ack-eliciting packets (ACK-only, PADDING-only,
+     * CONNECTION_CLOSE) are never retransmitted.
+     */
+    val ackEliciting: Boolean,
+    /**
+     * Encrypted on-wire size in bytes, including AEAD tag and packet
+     * header. Used by congestion controllers to release in-flight
+     * bytes on ACK / loss.
+     */
+    val sizeBytes: Int,
+    /**
+     * Frames in this packet that need to be tracked for retransmit.
+     * Empty list is legal for non-ack-eliciting packets that have
+     * nothing retransmittable (e.g. ACK-only). Otherwise non-empty.
+     */
+    val tokens: List<RecoveryToken>,
+)

quic/src/commonTest/kotlin/com/vitorpamplona/quic/connection/recovery/RecoveryTokenTest.kt

@@ -0,0 +1,123 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quic.connection.recovery
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNotEquals
+import kotlin.test.assertTrue
+
+/**
+ * Type-level invariants for [RecoveryToken]: equality + hashCode
+ * correctness across data-class variants, the singleton [Ack] object,
+ * and the typed-token shape required by the dispatcher in step 6 of
+ * `quic/plans/2026-05-04-control-frame-retransmit.md`.
+ *
+ * No connection state is exercised here — these are unit tests on
+ * the type itself.
+ */
+class RecoveryTokenTest {
+    @Test
+    fun ack_isSingleton() {
+        val a: RecoveryToken = RecoveryToken.Ack
+        val b: RecoveryToken = RecoveryToken.Ack
+        // `data object Ack` ⇒ same reference, same hash.
+        assertTrue(a === b)
+        assertEquals(a, b)
+        assertEquals(a.hashCode(), b.hashCode())
+    }
+
+    @Test
+    fun maxStreamsUni_equalityByValue() {
+        val t1 = RecoveryToken.MaxStreamsUni(maxStreams = 150L)
+        val t2 = RecoveryToken.MaxStreamsUni(maxStreams = 150L)
+        val t3 = RecoveryToken.MaxStreamsUni(maxStreams = 200L)
+
+        assertEquals(t1, t2)
+        assertEquals(t1.hashCode(), t2.hashCode())
+        assertNotEquals(t1, t3)
+    }
+
+    @Test
+    fun maxStreamsBidi_distinctFromUni() {
+        val uni: RecoveryToken = RecoveryToken.MaxStreamsUni(maxStreams = 100L)
+        val bidi: RecoveryToken = RecoveryToken.MaxStreamsBidi(maxStreams = 100L)
+        assertNotEquals(uni, bidi)
+    }
+
+    @Test
+    fun maxData_equalityByValue() {
+        val t1 = RecoveryToken.MaxData(maxData = 1_000_000L)
+        val t2 = RecoveryToken.MaxData(maxData = 1_000_000L)
+        val t3 = RecoveryToken.MaxData(maxData = 2_000_000L)
+
+        assertEquals(t1, t2)
+        assertNotEquals(t1, t3)
+    }
+
+    @Test
+    fun maxStreamData_equalityByPair() {
+        val t1 = RecoveryToken.MaxStreamData(streamId = 0L, maxData = 1024L)
+        val t2 = RecoveryToken.MaxStreamData(streamId = 0L, maxData = 1024L)
+        val differentStream = RecoveryToken.MaxStreamData(streamId = 4L, maxData = 1024L)
+        val differentValue = RecoveryToken.MaxStreamData(streamId = 0L, maxData = 2048L)
+
+        assertEquals(t1, t2)
+        assertNotEquals(t1, differentStream)
+        assertNotEquals(t1, differentValue)
+    }
+
+    @Test
+    fun whenDispatch_isExhaustive() {
+        // Compile-time assertion that the sealed hierarchy is fixed and
+        // an exhaustive `when` actually compiles. If a new variant is
+        // added without updating the dispatcher, this test stops
+        // compiling — caught at build time, not at runtime.
+        val tokens: List<RecoveryToken> =
+            listOf(
+                RecoveryToken.Ack,
+                RecoveryToken.MaxStreamsUni(150L),
+                RecoveryToken.MaxStreamsBidi(150L),
+                RecoveryToken.MaxData(1_000_000L),
+                RecoveryToken.MaxStreamData(streamId = 0L, maxData = 1024L),
+            )
+        val labels =
+            tokens.map {
+                when (it) {
+                    RecoveryToken.Ack -> "ack"
+                    is RecoveryToken.MaxStreamsUni -> "msu:${it.maxStreams}"
+                    is RecoveryToken.MaxStreamsBidi -> "msb:${it.maxStreams}"
+                    is RecoveryToken.MaxData -> "md:${it.maxData}"
+                    is RecoveryToken.MaxStreamData -> "msd:${it.streamId}:${it.maxData}"
+                }
+            }
+        assertEquals(
+            listOf(
+                "ack",
+                "msu:150",
+                "msb:150",
+                "md:1000000",
+                "msd:0:1024",
+            ),
+            labels,
+        )
+    }
+}

quic/src/commonTest/kotlin/com/vitorpamplona/quic/connection/recovery/SentPacketTest.kt

@@ -0,0 +1,144 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quic.connection.recovery
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNotEquals
+import kotlin.test.assertTrue
+
+/**
+ * Schema-level invariants for [SentPacket]: data-class equality
+ * mirrors [RecoveryTokenTest], plus the convention that ACK-only
+ * packets carry a non-empty `tokens` list with `RecoveryToken.Ack`
+ * (so the sent-packet map's invariant — every retained entry has at
+ * least one token to dispatch — holds uniformly across packet types).
+ */
+class SentPacketTest {
+    @Test
+    fun equality_byAllFields() {
+        val a =
+            SentPacket(
+                packetNumber = 7L,
+                sentAtMillis = 1_700_000_000_000L,
+                ackEliciting = true,
+                sizeBytes = 128,
+                tokens = listOf(RecoveryToken.MaxStreamsUni(150L)),
+            )
+        val b =
+            SentPacket(
+                packetNumber = 7L,
+                sentAtMillis = 1_700_000_000_000L,
+                ackEliciting = true,
+                sizeBytes = 128,
+                tokens = listOf(RecoveryToken.MaxStreamsUni(150L)),
+            )
+        assertEquals(a, b)
+        assertEquals(a.hashCode(), b.hashCode())
+    }
+
+    @Test
+    fun equality_byPacketNumber() {
+        val a =
+            SentPacket(
+                packetNumber = 7L,
+                sentAtMillis = 0L,
+                ackEliciting = false,
+                sizeBytes = 16,
+                tokens = listOf(RecoveryToken.Ack),
+            )
+        val differentPn = a.copy(packetNumber = 8L)
+        assertNotEquals(a, differentPn)
+    }
+
+    @Test
+    fun equality_byTokenList() {
+        val a =
+            SentPacket(
+                packetNumber = 1L,
+                sentAtMillis = 0L,
+                ackEliciting = true,
+                sizeBytes = 64,
+                tokens = listOf(RecoveryToken.MaxData(1_000L), RecoveryToken.MaxStreamsUni(150L)),
+            )
+        val swapped = a.copy(tokens = listOf(RecoveryToken.MaxStreamsUni(150L), RecoveryToken.MaxData(1_000L)))
+        // List equality is order-sensitive — these are different.
+        assertNotEquals(a, swapped)
+    }
+
+    @Test
+    fun ackOnlyPacket_carriesAckToken() {
+        // ACK-only packet: not ack-eliciting (RFC 9000 §13.2.1) but
+        // we still record a single Ack token so the sent-packet map's
+        // "every entry has a token" invariant holds.
+        val ackOnly =
+            SentPacket(
+                packetNumber = 42L,
+                sentAtMillis = 0L,
+                ackEliciting = false,
+                sizeBytes = 24,
+                tokens = listOf(RecoveryToken.Ack),
+            )
+        assertTrue(ackOnly.tokens.isNotEmpty())
+        assertEquals(RecoveryToken.Ack, ackOnly.tokens.single())
+    }
+
+    @Test
+    fun ackEliciting_packetCanCarryMultipleControlTokens() {
+        // A real outbound packet that bumps both flow-control caps
+        // simultaneously (e.g. publisher session with sustained
+        // stream churn) carries two tokens. Loss declaration walks
+        // both; ACK drops both.
+        val multi =
+            SentPacket(
+                packetNumber = 100L,
+                sentAtMillis = 0L,
+                ackEliciting = true,
+                sizeBytes = 80,
+                tokens =
+                    listOf(
+                        RecoveryToken.MaxStreamsUni(maxStreams = 1_500_000L),
+                        RecoveryToken.MaxData(maxData = 64L * 1024L * 1024L),
+                    ),
+            )
+        assertEquals(2, multi.tokens.size)
+        assertEquals(RecoveryToken.MaxStreamsUni(1_500_000L), multi.tokens[0])
+        assertEquals(RecoveryToken.MaxData(64L * 1024L * 1024L), multi.tokens[1])
+    }
+
+    @Test
+    fun copy_preservesUntouchedFields() {
+        val base =
+            SentPacket(
+                packetNumber = 5L,
+                sentAtMillis = 1L,
+                ackEliciting = true,
+                sizeBytes = 100,
+                tokens = listOf(RecoveryToken.MaxStreamsUni(150L)),
+            )
+        val onlyTimeChanged = base.copy(sentAtMillis = 2L)
+        assertEquals(base.packetNumber, onlyTimeChanged.packetNumber)
+        assertEquals(base.ackEliciting, onlyTimeChanged.ackEliciting)
+        assertEquals(base.sizeBytes, onlyTimeChanged.sizeBytes)
+        assertEquals(base.tokens, onlyTimeChanged.tokens)
+        assertNotEquals(base.sentAtMillis, onlyTimeChanged.sentAtMillis)
+    }
+}