fix(api): typed DeviceNotConnectedException from Core's connectivity guards (closes #395)

docs/DEVICE_INTERFACES.md

@@ -369,6 +369,53 @@ catch (OperationCanceledException)
 }
 ```
 
+#### Telling "the device went away" apart from a bug
+
+Every device operation opens with a connectivity guard. When it fails, it throws
+`DeviceNotConnectedException` — a typed exception, so a disconnect can be classified without
+matching on the exception message:
+
+```csharp
+using Daqifi.Core.Device;
+using Daqifi.Core.Device.SdCard;
+
+var sdCard = (ISdCardOperations)device;
+
+try
+{
+    IReadOnlyList<SdCardFileInfo> files = await sdCard.GetSdCardFilesAsync();
+}
+catch (DeviceNotConnectedException ex)
+{
+    // Ordinary and expected: the user pressed Disconnect mid-refresh, or WiFi dropped.
+    // Log at warning with reconnect guidance — do NOT raise an error-tracker issue.
+    logger.LogWarning(ex, ex.IsShuttingDown
+        ? "Device is disconnecting; skipping refresh."
+        : "Device is not connected. Reconnect and try again.");
+}
+catch (InvalidOperationException ex)
+{
+    // Everything else on this path really is a defect — e.g. calling a text command
+    // re-entrantly, or using a device constructed without a transport.
+    logger.LogError(ex, "Bug: invalid SD card operation.");
+}
+```
+
+Notes:
+
+- `DeviceNotConnectedException` derives from `InvalidOperationException`, which is what these
+  guards threw before, so existing `catch (InvalidOperationException)` blocks keep working. Order
+  the `catch` clauses most-specific-first, as above.
+- `IsShuttingDown` is `true` when the guard fired because a `Disconnect()` or `Dispose()` is in
+  flight (or already finished) rather than because the device was never connected. Both mean "the
+  device is unavailable"; the flag is there for callers that want to suppress a retry prompt when
+  the user initiated the disconnect themselves.
+- `TransportNotConnectedException` is its sibling, not its base: it reports that the underlying
+  stream is gone (a serial unplug, a dropped TCP socket) while the device still believed it was
+  connected. Catch `DeviceNotConnectedException` for the device-state case and
+  `TransportNotConnectedException` for the transport case — or both, since they classify the same
+  way for reporting purposes.
+
 ### Connection Status Monitoring
 
 ```csharp

src/Daqifi.Core.Tests/Device/Capabilities/DaqifiDeviceCapabilityDocumentTests.cs

@@ -35,7 +35,9 @@ public async Task ReadCapabilityDocumentAsync_WhenDisconnected_Throws()
     {
         var device = new TestableCapabilityDevice("BenchNq1");
 
-        await Assert.ThrowsAsync<InvalidOperationException>(
+        // Typed since #395; still an InvalidOperationException by inheritance, so a consumer's
+        // existing catch keeps working. ThrowsAsync matches exactly, hence the derived type here.
+        await Assert.ThrowsAsync<DeviceNotConnectedException>(
             () => device.ReadCapabilityDocumentAsync());
     }
 

src/Daqifi.Core.Tests/Device/DaqifiDeviceInitializeTests.cs

@@ -87,7 +87,7 @@ public async Task InitializeAsync_WhenDisconnected_Throws()
             // Not connected
 
             // Act & Assert
-            var ex = await Assert.ThrowsAsync<InvalidOperationException>(
+            var ex = await Assert.ThrowsAsync<DeviceNotConnectedException>(
                 () => device.InitializeAsync());
             Assert.Equal("Device must be connected before initialization.", ex.Message);
         }

src/Daqifi.Core.Tests/Device/DaqifiDeviceTests.cs

@@ -71,13 +71,13 @@ public void Disconnect_ChangesStatusAndRaisesEvent()
         }
 
         [Fact]
-        public void Send_WhenDisconnected_ThrowsInvalidOperationException()
+        public void Send_WhenDisconnected_ThrowsDeviceNotConnectedException()
         {
             // Arrange
             var device = new DaqifiDevice("TestDevice");
 
             // Act & Assert
-            Assert.Throws<System.InvalidOperationException>(() => device.Send(new Daqifi.Core.Communication.Messages.ScpiMessage("")));
+            Assert.Throws<DeviceNotConnectedException>(() => device.Send(new Daqifi.Core.Communication.Messages.ScpiMessage("")));
         }
 
         [Fact]

src/Daqifi.Core.Tests/Device/DaqifiDeviceTextCommandLockTests.cs

@@ -40,23 +40,23 @@ public async Task ExecuteTextCommandAsync_WhenAlreadyInsideAsyncFlow_ThrowsInval
         }
 
         [Fact]
-        public async Task ExecuteTextCommandAsync_WhenDisposing_ThrowsInvalidOperation()
+        public async Task ExecuteTextCommandAsync_WhenDisposing_ThrowsDeviceNotConnected()
         {
             var device = new TextCommandTestableDevice("TestDevice");
             SetIsDisconnecting(device, true);
 
-            var ex = await Assert.ThrowsAsync<InvalidOperationException>(
+            var ex = await Assert.ThrowsAsync<DeviceNotConnectedException>(
                 () => device.CallExecuteTextCommandAsync(() => { }));
             Assert.Contains("disposing or disconnecting", ex.Message);
         }
 
         [Fact]
-        public async Task ExecuteTextCommandAsync_WhenDisposed_ThrowsInvalidOperation()
+        public async Task ExecuteTextCommandAsync_WhenDisposed_ThrowsDeviceNotConnected()
         {
             var device = new TextCommandTestableDevice("TestDevice");
             SetDisposed(device, true);
 
-            var ex = await Assert.ThrowsAsync<InvalidOperationException>(
+            var ex = await Assert.ThrowsAsync<DeviceNotConnectedException>(
                 () => device.CallExecuteTextCommandAsync(() => { }));
             Assert.Contains("disposing or disconnecting", ex.Message);
         }
@@ -70,12 +70,12 @@ public async Task ExecuteTextCommandAsync_ReleasesLockAfterValidationFailure()
             // not block on WaitAsync.
             var device = new TextCommandTestableDevice("TestDevice");
 
-            await Assert.ThrowsAsync<InvalidOperationException>(
+            await Assert.ThrowsAsync<DeviceNotConnectedException>(
                 () => device.CallExecuteTextCommandAsync(() => { }));
             // Second call: also throws, but ONLY if the lock was released.
             // If the lock leaked, this would deadlock and xunit's per-test
             // budget would time it out instead.
-            await Assert.ThrowsAsync<InvalidOperationException>(
+            await Assert.ThrowsAsync<DeviceNotConnectedException>(
                 () => device.CallExecuteTextCommandAsync(() => { }));
         }
 
@@ -87,7 +87,7 @@ public async Task ExecuteTextCommandAsync_AsyncLocalClearedAfterReturn()
             // the same flow doesn't false-positive the re-entrancy check.
             var device = new TextCommandTestableDevice("TestDevice");
 
-            await Assert.ThrowsAsync<InvalidOperationException>(
+            await Assert.ThrowsAsync<DeviceNotConnectedException>(
                 () => device.CallExecuteTextCommandAsync(() => { }));
 
             Assert.False(GetIsInsideTextExchange(device).Value);

src/Daqifi.Core.Tests/Device/DaqifiDeviceWithMessageProducerTests.cs

@@ -77,7 +77,7 @@ public void DaqifiDevice_SendMessage_WhenDisconnected_ShouldThrowException()
         using var device = new DaqifiDevice("Test Device", stream);
 
         // Act & Assert
-        Assert.Throws<InvalidOperationException>(() => device.Send(ScpiMessageProducer.GetDeviceInfo));
+        Assert.Throws<DeviceNotConnectedException>(() => device.Send(ScpiMessageProducer.GetDeviceInfo));
     }
 
     [Fact]

src/Daqifi.Core.Tests/Device/DaqifiDeviceWithTransportTests.cs

@@ -83,7 +83,7 @@ public void DaqifiDevice_SendMessage_WithoutConnection_ShouldThrowException()
         using var device = new DaqifiDevice("Test Device", transport);
 
         // Act & Assert
-        Assert.Throws<InvalidOperationException>(() => device.Send(ScpiMessageProducer.GetDeviceInfo));
+        Assert.Throws<DeviceNotConnectedException>(() => device.Send(ScpiMessageProducer.GetDeviceInfo));
     }
 
     [Fact]

src/Daqifi.Core.Tests/Device/DaqifiStreamingDeviceChannelManagementTests.cs

@@ -571,13 +571,13 @@ public void SetPwmFrequency_OutOfRange_ThrowsArgumentOutOfRangeException(int fre
         }
 
         [Fact]
-        public void SetPwmEnabled_WhenDisconnected_ThrowsInvalidOperationException()
+        public void SetPwmEnabled_WhenDisconnected_ThrowsDeviceNotConnectedException()
         {
             var device = CreateConnectedDevice(digitalChannels: 8);
             var channel = DigitalChannelAt(device, 4);
             device.Disconnect();
 
-            Assert.Throws<InvalidOperationException>(() => device.SetPwmEnabled(channel, true));
+            Assert.Throws<DeviceNotConnectedException>(() => device.SetPwmEnabled(channel, true));
         }
 
         [Fact]
@@ -688,7 +688,7 @@ public void DisableChannel_WithNullChannel_ThrowsArgumentNullException()
         }
 
         [Fact]
-        public void ChannelManagement_WhenDisconnected_ThrowsInvalidOperationException()
+        public void ChannelManagement_WhenDisconnected_ThrowsDeviceNotConnectedException()
         {
             // Populate channels but do not connect.
             var device = new TestableDaqifiStreamingDevice("TestDevice");
@@ -701,14 +701,14 @@ public void ChannelManagement_WhenDisconnected_ThrowsInvalidOperationException()
             var analog = AnalogChannelAt(device, 0);
             var digital = DigitalChannelAt(device, 0);
 
-            Assert.Throws<InvalidOperationException>(() => device.EnableChannel(analog));
-            Assert.Throws<InvalidOperationException>(() => device.EnableChannels(new[] { analog }));
-            Assert.Throws<InvalidOperationException>(() => device.DisableChannel(analog));
-            Assert.Throws<InvalidOperationException>(() => device.DisableAllChannels());
-            Assert.Throws<InvalidOperationException>(() => device.SetDioDirection(digital, ChannelDirection.Output));
-            Assert.Throws<InvalidOperationException>(() => device.SetDioValue(digital, true));
-            Assert.Throws<InvalidOperationException>(() => device.SetAnalogOutput(0, 1.0));
-            Assert.Throws<InvalidOperationException>(() => device.Reboot());
+            Assert.Throws<DeviceNotConnectedException>(() => device.EnableChannel(analog));
+            Assert.Throws<DeviceNotConnectedException>(() => device.EnableChannels(new[] { analog }));
+            Assert.Throws<DeviceNotConnectedException>(() => device.DisableChannel(analog));
+            Assert.Throws<DeviceNotConnectedException>(() => device.DisableAllChannels());
+            Assert.Throws<DeviceNotConnectedException>(() => device.SetDioDirection(digital, ChannelDirection.Output));
+            Assert.Throws<DeviceNotConnectedException>(() => device.SetDioValue(digital, true));
+            Assert.Throws<DeviceNotConnectedException>(() => device.SetAnalogOutput(0, 1.0));
+            Assert.Throws<DeviceNotConnectedException>(() => device.Reboot());
         }
 
         #endregion

src/Daqifi.Core.Tests/Device/DaqifiStreamingDeviceFriendlyNameTests.cs

@@ -36,7 +36,7 @@ public async Task SetFriendlyNameAsync_InvalidName_Throws(string name)
         public async Task SetFriendlyNameAsync_NotConnected_Throws()
         {
             var device = new CapturingStreamingDevice(); // not connected
-            await Assert.ThrowsAsync<InvalidOperationException>(() => device.SetFriendlyNameAsync("Lab Nq1"));
+            await Assert.ThrowsAsync<DeviceNotConnectedException>(() => device.SetFriendlyNameAsync("Lab Nq1"));
         }
 
         [Fact]

src/Daqifi.Core.Tests/Device/DaqifiStreamingDevicePwmFrequencyTests.cs

@@ -75,7 +75,7 @@ public void SetPwmFrequency_AfterReconnect_SendsAgainEvenIfUnchanged()
         public void SetPwmFrequency_NotConnected_ThrowsAndSendsNothing()
         {
             var device = new CapturingStreamingDevice(); // not connected
-            Assert.Throws<System.InvalidOperationException>(() => device.SetPwmFrequency(2000));
+            Assert.Throws<DeviceNotConnectedException>(() => device.SetPwmFrequency(2000));
             Assert.Empty(device.PwmFrequencySends);
         }
 

src/Daqifi.Core.Tests/Device/DaqifiStreamingDeviceTests.cs

@@ -133,24 +133,24 @@ public void StopStreaming_WhenConnected_SendsCorrectCommandAndSetsIsStreaming()
         }
 
         [Fact]
-        public void StartStreaming_WhenDisconnected_ThrowsInvalidOperationException()
+        public void StartStreaming_WhenDisconnected_ThrowsDeviceNotConnectedException()
         {
             // Arrange
             var device = new DaqifiStreamingDevice("TestDevice");
 
             // Act & Assert
-            var exception = Assert.Throws<System.InvalidOperationException>(() => device.StartStreaming());
+            var exception = Assert.Throws<DeviceNotConnectedException>(() => device.StartStreaming());
             Assert.Equal("Device is not connected.", exception.Message);
         }
 
         [Fact]
-        public void StopStreaming_WhenDisconnected_ThrowsInvalidOperationException()
+        public void StopStreaming_WhenDisconnected_ThrowsDeviceNotConnectedException()
         {
             // Arrange
             var device = new DaqifiStreamingDevice("TestDevice");
 
             // Act & Assert
-            var exception = Assert.Throws<System.InvalidOperationException>(() => device.StopStreaming());
+            var exception = Assert.Throws<DeviceNotConnectedException>(() => device.StopStreaming());
             Assert.Equal("Device is not connected.", exception.Message);
         }
 
@@ -201,14 +201,14 @@ public void NvmPersistence_WhenConnected_SendsCorrectCommand(string methodName,
 
         [Theory]
         [MemberData(nameof(NvmPersistenceCommands))]
-        public void NvmPersistence_WhenDisconnected_ThrowsInvalidOperationException(string methodName, string expectedCommand)
+        public void NvmPersistence_WhenDisconnected_ThrowsDeviceNotConnectedException(string methodName, string expectedCommand)
         {
             // Arrange
             _ = expectedCommand;
             var device = new DaqifiStreamingDevice("TestDevice");
 
             // Act & Assert
-            var exception = Assert.Throws<System.InvalidOperationException>(() => InvokeNvmMethod(device, methodName));
+            var exception = Assert.Throws<DeviceNotConnectedException>(() => InvokeNvmMethod(device, methodName));
             Assert.Equal("Device is not connected.", exception.Message);
         }
 
@@ -264,26 +264,26 @@ public void UseAdcCalibration_WhenConnected_SendsCorrectCommand(int bank)
         }
 
         [Fact]
-        public void SetAdcCalibrationSlope_WhenDisconnected_ThrowsInvalidOperationException()
+        public void SetAdcCalibrationSlope_WhenDisconnected_ThrowsDeviceNotConnectedException()
         {
             var device = new DaqifiStreamingDevice("TestDevice");
-            var exception = Assert.Throws<System.InvalidOperationException>(() => device.SetAdcCalibrationSlope(0, 1.0));
+            var exception = Assert.Throws<DeviceNotConnectedException>(() => device.SetAdcCalibrationSlope(0, 1.0));
             Assert.Equal("Device is not connected.", exception.Message);
         }
 
         [Fact]
-        public void SetAdcCalibrationOffset_WhenDisconnected_ThrowsInvalidOperationException()
+        public void SetAdcCalibrationOffset_WhenDisconnected_ThrowsDeviceNotConnectedException()
         {
             var device = new DaqifiStreamingDevice("TestDevice");
-            var exception = Assert.Throws<System.InvalidOperationException>(() => device.SetAdcCalibrationOffset(0, 1.0));
+            var exception = Assert.Throws<DeviceNotConnectedException>(() => device.SetAdcCalibrationOffset(0, 1.0));
             Assert.Equal("Device is not connected.", exception.Message);
         }
 
         [Fact]
-        public void UseAdcCalibration_WhenDisconnected_ThrowsInvalidOperationException()
+        public void UseAdcCalibration_WhenDisconnected_ThrowsDeviceNotConnectedException()
         {
             var device = new DaqifiStreamingDevice("TestDevice");
-            var exception = Assert.Throws<System.InvalidOperationException>(() => device.UseAdcCalibration(1));
+            var exception = Assert.Throws<DeviceNotConnectedException>(() => device.UseAdcCalibration(1));
             Assert.Equal("Device is not connected.", exception.Message);
         }