refactor(modbus-rtu): distinct CrcMismatch/UnitMismatch desync reasons

The RTU framer overloaded DesyncReason.TruncatedFrame for three distinct
failures — a genuine short read, a CRC-16 validation failure, and a
CRC-valid reply from the wrong RS-485 slave. Split the latter two into
dedicated CrcMismatch / UnitMismatch enum members so a future .Reason
consumer (metrics, operator diagnostics) can tell a wiring/EMI CRC fault
apart from a mis-addressed multi-drop reply. Behaviour is unchanged — all
three still throw ModbusTransportDesyncException and tear the socket down.

Framing tests now assert the specific Reason on each path.

Follow-up #12 from the Modbus RTU-over-TCP plan.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus/ModbusRtuFraming.cs

@@ -137,7 +137,7 @@ public static class ModbusRtuFraming
         var actual = (ushort)(frame[^2] | (frame[^1] << 8));
         if (actual != expected)
             throw new ModbusTransportDesyncException(
-                ModbusTransportDesyncException.DesyncReason.TruncatedFrame,
+                ModbusTransportDesyncException.DesyncReason.CrcMismatch,
                 $"Modbus RTU CRC mismatch: computed {expected:X4} got {actual:X4}");
 
         // Unit-address validation runs only AFTER the CRC passes: a corrupt frame is a CRC/desync
@@ -146,7 +146,7 @@ public static class ModbusRtuFraming
         var addr = frame[0];
         if (addr != expectedUnit)
             throw new ModbusTransportDesyncException(
-                ModbusTransportDesyncException.DesyncReason.TruncatedFrame,
+                ModbusTransportDesyncException.DesyncReason.UnitMismatch,
                 $"Modbus RTU unit mismatch: expected {expectedUnit} got {addr}");
 
         // Bare PDU = frame minus leading addr and trailing CRC.

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus/ModbusTransportDesyncException.cs

@@ -1,9 +1,10 @@
 namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus;
 
 /// <summary>
-///     Raised when a Modbus TCP transaction leaves the single-flight socket in an unknown /
+///     Raised when a Modbus transaction leaves the single-flight socket in an unknown /
 ///     desynchronized state — a per-op response timeout, or a framing violation (transaction-id
-///     mismatch or truncated MBAP length). Unlike a Modbus <em>exception PDU</em> (a well-formed
+///     mismatch, truncated frame, RTU CRC mismatch, or RTU unit-address mismatch). Unlike a Modbus
+///     <em>exception PDU</em> (a well-formed
 ///     protocol-level error where the socket is still coherent and the request must simply
 ///     propagate), a desync means bytes may still be in flight or half-read, so the socket is
 ///     unusable and MUST be torn down before this is thrown.
@@ -27,8 +28,20 @@ public sealed class ModbusTransportDesyncException : IOException
         /// <summary>The response MBAP transaction id did not match the request's.</summary>
         TxIdMismatch,
 
-        /// <summary>The response MBAP length field was below the mandatory minimum (truncated frame).</summary>
+        /// <summary>
+        ///     The frame ended before it was complete — the MBAP length field was below the mandatory
+        ///     minimum (TCP), or the stream closed mid-frame while reading a length-less RTU frame.
+        /// </summary>
         TruncatedFrame,
+
+        /// <summary>The RTU frame's trailing CRC-16 did not validate over the received bytes.</summary>
+        CrcMismatch,
+
+        /// <summary>
+        ///     A CRC-valid RTU frame carried a slave/unit address other than the one addressed — on an
+        ///     RS-485 multi-drop bus, a reply from the wrong slave.
+        /// </summary>
+        UnitMismatch,
     }
 
     /// <summary>Gets the reason the socket was classified desynchronized.</summary>

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ModbusRtuFramingTests.cs

@@ -43,8 +43,9 @@ public sealed class ModbusRtuFramingTests
         var frame = ModbusCrc.Append(new byte[] { 0x01, 0x03, 0x02, 0x00, 0x0A });
         frame[^1] ^= 0xFF; // corrupt CRC high byte
         await using var s = Canned(frame);
-        await Should.ThrowAsync<ModbusTransportDesyncException>(
+        var ex = await Should.ThrowAsync<ModbusTransportDesyncException>(
             ModbusRtuFraming.ReadResponsePduAsync(s, 0x01, TestContext.Current.CancellationToken));
+        ex.Reason.ShouldBe(ModbusTransportDesyncException.DesyncReason.CrcMismatch);
     }
 
     [Fact]
@@ -63,8 +64,9 @@ public sealed class ModbusRtuFramingTests
         // CRC-valid FC03 frame addressed to unit 0x02, but we asked for 0x01 -> unit-mismatch desync.
         var frame = ModbusCrc.Append(new byte[] { 0x02, 0x03, 0x02, 0x00, 0x0A });
         await using var s = Canned(frame);
-        await Should.ThrowAsync<ModbusTransportDesyncException>(
+        var ex = await Should.ThrowAsync<ModbusTransportDesyncException>(
             ModbusRtuFraming.ReadResponsePduAsync(s, 0x01, TestContext.Current.CancellationToken));
+        ex.Reason.ShouldBe(ModbusTransportDesyncException.DesyncReason.UnitMismatch);
     }
 
     [Fact]
@@ -86,8 +88,9 @@ public sealed class ModbusRtuFramingTests
         var frame = ModbusCrc.Append(new byte[] { 0x01, 0x03, 0x02, 0x00, 0x0A });
         var truncated = frame[..4];
         await using var s = new DribbleStream(truncated, chunk: 2);
-        await Should.ThrowAsync<ModbusTransportDesyncException>(
+        var ex = await Should.ThrowAsync<ModbusTransportDesyncException>(
             ModbusRtuFraming.ReadResponsePduAsync(s, 0x01, TestContext.Current.CancellationToken));
+        ex.Reason.ShouldBe(ModbusTransportDesyncException.DesyncReason.TruncatedFrame);
     }
 
     /// <summary>