RioSerialLink: NAK-driven retransmit of the last command packet

The board ACK/NAKs every inbound packet; we were fire-and-forget, so
any corrupt arrival became a permanent state error (stuck-bright /
missed lamps at 62500, where ~6.5% of 4-byte lamp commands lose bytes
to RX-ISR overrun). Now a NAK control byte triggers a resend of the
most recent command packet, bounded by NakRetransmitLimit (default 2;
0 restores fire-and-forget).

Design notes: the wire has no sequence numbers, but every PC->RIO
command is idempotent (lamp state, analog request, reset), so resending
the latest command is safe even in the rare race where the NAK belonged
to an earlier packet. Single control-byte replies (our ACKs) never
participate. NakRetransmits counter surfaced in the mash summary.

6 new tests (retransmit, limit, budget reset, ACK no-op, control-byte
exclusion, disable switch); 281 green.

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

tests/RioJoy.Core.Tests/Serial/RioSerialLinkTests.cs

@@ -141,4 +141,160 @@ public class RioSerialLinkTests
         cts.Cancel();
         await run;
     }
+
+    // --- NAK retransmit (RioSerialLinkOptions.NakRetransmitLimit) ------------
+
+    [Fact]
+    public async Task Nak_RetransmitsLastCommand()
+    {
+        var fake = new FakeTransport();
+        var link = new RioSerialLink(fake, new RioSerialLinkOptions { AutoPollAnalog = false });
+
+        using var cts = new CancellationTokenSource();
+        Task run = link.RunAsync(cts.Token);
+
+        byte[] lamp = PacketBuilder.LampRequest(0x05, 0x02);
+        await link.SendAsync(lamp);
+        Assert.Equal(lamp, await fake.NextWriteAsync());
+
+        fake.Enqueue((byte)RioControl.Nak); // board: "that arrived corrupt"
+
+        Assert.Equal(lamp, await fake.NextWriteAsync()); // resent
+        Assert.Equal(1, link.NakRetransmits);
+
+        cts.Cancel();
+        await run;
+    }
+
+    [Fact]
+    public async Task Nak_RetransmitStopsAtLimit()
+    {
+        var fake = new FakeTransport();
+        var link = new RioSerialLink(fake, new RioSerialLinkOptions
+        {
+            AutoPollAnalog = false,
+            NakRetransmitLimit = 2,
+        });
+
+        using var cts = new CancellationTokenSource();
+        Task run = link.RunAsync(cts.Token);
+
+        byte[] lamp = PacketBuilder.LampRequest(0x05, 0x02);
+        await link.SendAsync(lamp);
+        await fake.NextWriteAsync(); // original
+
+        for (int i = 0; i < 4; i++)
+            fake.Enqueue((byte)RioControl.Nak);
+
+        Assert.Equal(lamp, await fake.NextWriteAsync()); // retry 1
+        Assert.Equal(lamp, await fake.NextWriteAsync()); // retry 2
+
+        // Budget spent: NAKs 3 and 4 must produce no further writes.
+        await Assert.ThrowsAnyAsync<OperationCanceledException>(
+            () => fake.NextWriteAsync(TimeSpan.FromMilliseconds(200)));
+        Assert.Equal(2, link.NakRetransmits);
+
+        cts.Cancel();
+        await run;
+    }
+
+    [Fact]
+    public async Task Ack_DoesNotRetransmit()
+    {
+        var fake = new FakeTransport();
+        var link = new RioSerialLink(fake, new RioSerialLinkOptions { AutoPollAnalog = false });
+
+        using var cts = new CancellationTokenSource();
+        Task run = link.RunAsync(cts.Token);
+
+        await link.SendAsync(PacketBuilder.LampRequest(0x05, 0x02));
+        await fake.NextWriteAsync();
+
+        fake.Enqueue((byte)RioControl.Ack);
+
+        await Assert.ThrowsAnyAsync<OperationCanceledException>(
+            () => fake.NextWriteAsync(TimeSpan.FromMilliseconds(200)));
+        Assert.Equal(0, link.NakRetransmits);
+
+        cts.Cancel();
+        await run;
+    }
+
+    [Fact]
+    public async Task NewCommand_ResetsRetryBudget()
+    {
+        var fake = new FakeTransport();
+        var link = new RioSerialLink(fake, new RioSerialLinkOptions
+        {
+            AutoPollAnalog = false,
+            NakRetransmitLimit = 1,
+        });
+
+        using var cts = new CancellationTokenSource();
+        Task run = link.RunAsync(cts.Token);
+
+        byte[] first = PacketBuilder.LampRequest(0x05, 0x02);
+        await link.SendAsync(first);
+        await fake.NextWriteAsync();
+        fake.Enqueue((byte)RioControl.Nak);
+        Assert.Equal(first, await fake.NextWriteAsync()); // budget of 'first' spent
+
+        byte[] second = PacketBuilder.LampRequest(0x06, 0x01);
+        await link.SendAsync(second);
+        Assert.Equal(second, await fake.NextWriteAsync());
+        fake.Enqueue((byte)RioControl.Nak);
+        Assert.Equal(second, await fake.NextWriteAsync()); // fresh budget applies
+
+        cts.Cancel();
+        await run;
+    }
+
+    [Fact]
+    public async Task OwnControlByteReplies_AreNeverRetransmitted()
+    {
+        var fake = new FakeTransport();
+        var link = new RioSerialLink(fake, new RioSerialLinkOptions { AutoPollAnalog = false });
+
+        using var cts = new CancellationTokenSource();
+        Task run = link.RunAsync(cts.Token);
+
+        // Inbound button packet -> the link replies with a 1-byte ACK. That ACK
+        // must not become "the last command" for retransmit purposes.
+        fake.Enqueue(PacketBuilder.Build(RioCommand.ButtonPressed, new byte[] { 0x05 }));
+        Assert.Equal(new byte[] { (byte)RioControl.Ack }, await fake.NextWriteAsync());
+
+        fake.Enqueue((byte)RioControl.Nak);
+
+        await Assert.ThrowsAnyAsync<OperationCanceledException>(
+            () => fake.NextWriteAsync(TimeSpan.FromMilliseconds(200)));
+        Assert.Equal(0, link.NakRetransmits);
+
+        cts.Cancel();
+        await run;
+    }
+
+    [Fact]
+    public async Task Retransmit_Disabled_IsFireAndForget()
+    {
+        var fake = new FakeTransport();
+        var link = new RioSerialLink(fake, new RioSerialLinkOptions
+        {
+            AutoPollAnalog = false,
+            NakRetransmitLimit = 0,
+        });
+
+        using var cts = new CancellationTokenSource();
+        Task run = link.RunAsync(cts.Token);
+
+        await link.SendAsync(PacketBuilder.LampRequest(0x05, 0x02));
+        await fake.NextWriteAsync();
+        fake.Enqueue((byte)RioControl.Nak);
+
+        await Assert.ThrowsAnyAsync<OperationCanceledException>(
+            () => fake.NextWriteAsync(TimeSpan.FromMilliseconds(200)));
+        Assert.Equal(0, link.NakRetransmits);
+
+        cts.Cancel();
+        await run;
+    }
 }