dfederm · dfederm · Mar 7, 2026 · Mar 7, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -58,7 +58,7 @@ Both require `fetch-depth: 0` for Nerdbank.GitVersioning. There is no separate l
 The foundational layer contains Z-Wave domain types shared across all projects, all in `namespace ZWave;`:
 - **`CommandClassId`** — Enum of all Z-Wave command class IDs.
 - **`CommandClassInfo`** — Record struct with CC ID, supported/controlled flags.
-- **`ZWaveException`** / **`ZWaveErrorCode`** — Z-Wave-specific error types.
+- **`ZWaveException`** / **`ZWaveErrorCode`** — Z-Wave-specific error types. `ZWaveException` has private constructors; use the `[DoesNotReturn]` static `ZWaveException.Throw(errorCode, message)` helpers instead of `throw new ZWaveException(...)`. Use `ArgumentNullException.ThrowIfNull()` and `ArgumentException.ThrowIfNullOrEmpty()` for argument validation.
 - **`FrequentListeningMode`** / **`NodeType`** — Node classification enums.
 
 ### Serial API Layer (`src/ZWave.Serial/`)
@@ -116,7 +116,7 @@ Response structs that contain variable-length collections use count + indexer me
 - **No `var`** — explicit types preferred (`csharp_style_var_*` = `false`).
 - Allman-style braces (`csharp_new_line_before_open_brace = all`).
 - NuGet package versions are centrally managed in `Directory.Packages.props`. When adding a package, add the version there and reference it without a version in the `.csproj`.
-- `InternalsVisibleTo` is set: `ZWave.Serial` → `ZWave.Serial.Tests`, `ZWave.CommandClasses` → `ZWave` and `ZWave.CommandClasses.Tests`.
+- `InternalsVisibleTo` is set: `ZWave.Protocol` → `ZWave.Serial`, `ZWave.Serial` → `ZWave.Serial.Tests`, `ZWave.CommandClasses` → `ZWave` and `ZWave.CommandClasses.Tests`.
 
 ## Testing Patterns
 

diff --git a/.github/skills/zwave-implement-cc/SKILL.md b/.github/skills/zwave-implement-cc/SKILL.md
@@ -153,7 +153,7 @@ Validation is performed in the report command's static `Parse` method. The `Pars
 
 1. **Validates** the frame (e.g., minimum payload length, field value ranges)
 2. **Logs a warning** via the `ILogger` parameter describing what's wrong
-3. **Throws `ZWaveException(ZWaveErrorCode.InvalidPayload, ...)`** with a concise message
+3. **Calls `ZWaveException.Throw(ZWaveErrorCode.InvalidPayload, ...)`** with a concise message
 
 The base class handles exception propagation differently depending on the report path:
 
@@ -524,7 +524,7 @@ internal readonly struct {Name}ReportCommand : ICommand
         if (frame.CommandParameters.Length < 1)
         {
             logger.LogWarning("{Name} Report frame is too short ({Length} bytes)", frame.CommandParameters.Length);
-            throw new ZWaveException(ZWaveErrorCode.InvalidPayload, "{Name} Report frame is too short");
+            ZWaveException.Throw(ZWaveErrorCode.InvalidPayload, "{Name} Report frame is too short");
         }
 
         ReadOnlySpan<byte> span = frame.CommandParameters.Span;

diff --git a/src/Shared/BinaryExtensions.cs b/src/Shared/BinaryExtensions.cs
@@ -31,15 +31,30 @@ internal static class BinaryExtensions
     /// Read a signed big-endian integer from a span of 1, 2, or 4 bytes.
     /// </summary>
     public static int ReadSignedVariableSizeBE(this ReadOnlySpan<byte> bytes)
-        => bytes.Length switch
+    {
+        switch (bytes.Length)
         {
-            1 => unchecked((sbyte)bytes[0]),
-            2 => BinaryPrimitives.ReadInt16BigEndian(bytes),
-            4 => BinaryPrimitives.ReadInt32BigEndian(bytes),
-            _ => throw new ZWaveException(
-                ZWaveErrorCode.InvalidPayload,
-                $"Invalid value size {bytes.Length}. Expected 1, 2, or 4."),
-        };
+            case 1:
+            {
+                return unchecked((sbyte)bytes[0]);
+            }
+            case 2:
+            {
+                return BinaryPrimitives.ReadInt16BigEndian(bytes);
+            }
+            case 4:
+            {
+                return BinaryPrimitives.ReadInt32BigEndian(bytes);
+            }
+            default:
+            {
+                ZWaveException.Throw(
+                    ZWaveErrorCode.InvalidPayload,
+                    $"Invalid value size {bytes.Length}. Expected 1, 2, or 4.");
+                return default;
+            }
+        }
+    }
 
     /// <summary>
     /// Get the minimum number of bytes (1, 2, or 4) needed to represent a signed integer.

diff --git a/src/ZWave.CommandClasses/AssociationCommandClass.Report.cs b/src/ZWave.CommandClasses/AssociationCommandClass.Report.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -144,7 +144,7 @@ public static (byte MaxNodesSupported, byte ReportsToFollow) ParseInto(
                 logger.LogWarning(
                     "Association Report frame is too short ({Length} bytes)",
                     frame.CommandParameters.Length);
-                throw new ZWaveException(
+                ZWaveException.Throw(
                     ZWaveErrorCode.InvalidPayload,
                     "Association Report frame is too short");
             }

diff --git a/src/ZWave.CommandClasses/AssociationCommandClass.SpecificGroup.cs b/src/ZWave.CommandClasses/AssociationCommandClass.SpecificGroup.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -72,7 +72,7 @@ public static byte Parse(CommandClassFrame frame, ILogger logger)
                 logger.LogWarning(
                     "Association Specific Group Report frame is too short ({Length} bytes)",
                     frame.CommandParameters.Length);
-                throw new ZWaveException(
+                ZWaveException.Throw(
                     ZWaveErrorCode.InvalidPayload,
                     "Association Specific Group Report frame is too short");
             }

diff --git a/src/ZWave.CommandClasses/AssociationCommandClass.SupportedGroupings.cs b/src/ZWave.CommandClasses/AssociationCommandClass.SupportedGroupings.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -69,7 +69,7 @@ public static byte Parse(CommandClassFrame frame, ILogger logger)
                 logger.LogWarning(
                     "Association Supported Groupings Report frame is too short ({Length} bytes)",
                     frame.CommandParameters.Length);
-                throw new ZWaveException(
+                ZWaveException.Throw(
                     ZWaveErrorCode.InvalidPayload,
                     "Association Supported Groupings Report frame is too short");
             }

diff --git a/src/ZWave.CommandClasses/AssociationGroupInformationCommandClass.CommandList.cs b/src/ZWave.CommandClasses/AssociationGroupInformationCommandClass.CommandList.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -139,7 +139,7 @@ public static (byte GroupingIdentifier, IReadOnlyList<AssociationGroupCommand> C
                 logger.LogWarning(
                     "Association Group Command List Report frame is too short ({Length} bytes)",
                     frame.CommandParameters.Length);
-                throw new ZWaveException(
+                ZWaveException.Throw(
                     ZWaveErrorCode.InvalidPayload,
                     "Association Group Command List Report frame is too short");
             }
@@ -154,7 +154,7 @@ public static (byte GroupingIdentifier, IReadOnlyList<AssociationGroupCommand> C
                     "Association Group Command List Report frame is too short for declared list length ({DeclaredLength} bytes, but only {Available} available)",
                     listLength,
                     frame.CommandParameters.Length - 2);
-                throw new ZWaveException(
+                ZWaveException.Throw(
                     ZWaveErrorCode.InvalidPayload,
                     "Association Group Command List Report frame is too short for declared list length");
             }

diff --git a/src/ZWave.CommandClasses/AssociationGroupInformationCommandClass.GroupInfo.cs b/src/ZWave.CommandClasses/AssociationGroupInformationCommandClass.GroupInfo.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -162,7 +162,7 @@ public async Task<AssociationGroupInfo> GetGroupInfoAsync(byte groupingIdentifie
             Logger.LogWarning(
                 "Association Group Info Report for group {GroupId} contained no group entries",
                 groupingIdentifier);
-            throw new ZWaveException(
+            ZWaveException.Throw(
                 ZWaveErrorCode.InvalidPayload,
                 "Association Group Info Report contained no group entries");
         }
@@ -263,7 +263,7 @@ public static (bool DynamicInfo, List<AssociationGroupInfo> Groups) Parse(Comman
                 logger.LogWarning(
                     "Association Group Info Report frame is too short ({Length} bytes)",
                     frame.CommandParameters.Length);
-                throw new ZWaveException(
+                ZWaveException.Throw(
                     ZWaveErrorCode.InvalidPayload,
                     "Association Group Info Report frame is too short");
             }
@@ -286,7 +286,7 @@ public static (bool DynamicInfo, List<AssociationGroupInfo> Groups) Parse(Comman
                     groupCount,
                     requiredLength,
                     frame.CommandParameters.Length);
-                throw new ZWaveException(
+                ZWaveException.Throw(
                     ZWaveErrorCode.InvalidPayload,
                     "Association Group Info Report frame is too short for declared group count");
             }

diff --git a/src/ZWave.CommandClasses/AssociationGroupInformationCommandClass.GroupName.cs b/src/ZWave.CommandClasses/AssociationGroupInformationCommandClass.GroupName.cs
@@ -1,4 +1,4 @@
-using System.Text;
+using System.Text;
 using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
@@ -88,7 +88,7 @@ public static (byte GroupingIdentifier, string Name) Parse(CommandClassFrame fra
                 logger.LogWarning(
                     "Association Group Name Report frame is too short ({Length} bytes)",
                     frame.CommandParameters.Length);
-                throw new ZWaveException(
+                ZWaveException.Throw(
                     ZWaveErrorCode.InvalidPayload,
                     "Association Group Name Report frame is too short");
             }
@@ -103,7 +103,7 @@ public static (byte GroupingIdentifier, string Name) Parse(CommandClassFrame fra
                     "Association Group Name Report frame is too short for declared name length ({DeclaredLength} bytes, but only {Available} available)",
                     nameLength,
                     frame.CommandParameters.Length - 2);
-                throw new ZWaveException(
+                ZWaveException.Throw(
                     ZWaveErrorCode.InvalidPayload,
                     "Association Group Name Report frame is too short for declared name length");
             }

diff --git a/src/ZWave.CommandClasses/BarrierOperatorCommandClass.EventSignal.cs b/src/ZWave.CommandClasses/BarrierOperatorCommandClass.EventSignal.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -136,7 +136,7 @@ public static BarrierOperatorEventSignalReport Parse(CommandClassFrame frame, IL
                 logger.LogWarning(
                     "Barrier Operator Event Signaling Report frame is too short ({Length} bytes)",
                     frame.CommandParameters.Length);
-                throw new ZWaveException(
+                ZWaveException.Throw(
                     ZWaveErrorCode.InvalidPayload,
                     "Barrier Operator Event Signaling Report frame is too short");
             }

diff --git a/src/ZWave.CommandClasses/BarrierOperatorCommandClass.Report.cs b/src/ZWave.CommandClasses/BarrierOperatorCommandClass.Report.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -146,7 +146,7 @@ public static BarrierOperatorReport Parse(CommandClassFrame frame, ILogger logge
             if (frame.CommandParameters.Length < 1)
             {
                 logger.LogWarning("Barrier Operator Report frame is too short ({Length} bytes)", frame.CommandParameters.Length);
-                throw new ZWaveException(ZWaveErrorCode.InvalidPayload, "Barrier Operator Report frame is too short");
+                ZWaveException.Throw(ZWaveErrorCode.InvalidPayload, "Barrier Operator Report frame is too short");
             }
 
             byte stateValue = frame.CommandParameters.Span[0];

diff --git a/src/ZWave.CommandClasses/BarrierOperatorCommandClass.SignalingCapabilities.cs b/src/ZWave.CommandClasses/BarrierOperatorCommandClass.SignalingCapabilities.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -68,7 +68,7 @@ public static IReadOnlySet<BarrierOperatorSignalingSubsystemType> Parse(CommandC
                 logger.LogWarning(
                     "Barrier Operator Signal Supported Report frame is too short ({Length} bytes)",
                     frame.CommandParameters.Length);
-                throw new ZWaveException(
+                ZWaveException.Throw(
                     ZWaveErrorCode.InvalidPayload,
                     "Barrier Operator Signal Supported Report frame is too short");
             }

diff --git a/src/ZWave.CommandClasses/BasicCommandClass.cs b/src/ZWave.CommandClasses/BasicCommandClass.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -171,7 +171,7 @@ public static BasicReport Parse(CommandClassFrame frame, ILogger logger)
             if (frame.CommandParameters.Length < 1)
             {
                 logger.LogWarning("Basic Report frame is too short ({Length} bytes)", frame.CommandParameters.Length);
-                throw new ZWaveException(ZWaveErrorCode.InvalidPayload, "Basic Report frame is too short");
+                ZWaveException.Throw(ZWaveErrorCode.InvalidPayload, "Basic Report frame is too short");
             }
 
             GenericValue currentValue = frame.CommandParameters.Span[0];

diff --git a/src/ZWave.CommandClasses/BatteryCommandClass.Health.cs b/src/ZWave.CommandClasses/BatteryCommandClass.Health.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -85,7 +85,7 @@ public static BatteryHealth Parse(CommandClassFrame frame, ILogger logger)
             if (frame.CommandParameters.Length < 2)
             {
                 logger.LogWarning("Battery Health Report frame is too short ({Length} bytes)", frame.CommandParameters.Length);
-                throw new ZWaveException(ZWaveErrorCode.InvalidPayload, "Battery Health Report frame is too short");
+                ZWaveException.Throw(ZWaveErrorCode.InvalidPayload, "Battery Health Report frame is too short");
             }
 
             // 0xff means unknown.
@@ -109,7 +109,7 @@ BatteryTemperatureScale batteryTemperatureScale
                 if (valueSize != 1 && valueSize != 2 && valueSize != 4)
                 {
                     logger.LogWarning("Battery Health Report has invalid Size value ({Size}). Expected 0, 1, 2, or 4", valueSize);
-                    throw new ZWaveException(ZWaveErrorCode.InvalidPayload, "Battery Health Report has invalid Size value");
+                    ZWaveException.Throw(ZWaveErrorCode.InvalidPayload, "Battery Health Report has invalid Size value");
                 }
 
                 if (frame.CommandParameters.Length < 2 + valueSize)
@@ -118,7 +118,7 @@ BatteryTemperatureScale batteryTemperatureScale
                         "Battery Health Report frame value size ({ValueSize}) exceeds remaining bytes ({Remaining})",
                         valueSize,
                         frame.CommandParameters.Length - 2);
-                    throw new ZWaveException(ZWaveErrorCode.InvalidPayload, "Battery Health Report frame is too short for declared value size");
+                    ZWaveException.Throw(ZWaveErrorCode.InvalidPayload, "Battery Health Report frame is too short for declared value size");
                 }
 
                 ReadOnlySpan<byte> valueBytes = frame.CommandParameters.Span.Slice(2, valueSize);

diff --git a/src/ZWave.CommandClasses/BatteryCommandClass.Report.cs b/src/ZWave.CommandClasses/BatteryCommandClass.Report.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -115,7 +115,7 @@ public static BatteryReport Parse(CommandClassFrame frame, ILogger logger)
             if (frame.CommandParameters.Length < 1)
             {
                 logger.LogWarning("Battery Report frame is too short ({Length} bytes)", frame.CommandParameters.Length);
-                throw new ZWaveException(ZWaveErrorCode.InvalidPayload, "Battery Report frame is too short");
+                ZWaveException.Throw(ZWaveErrorCode.InvalidPayload, "Battery Report frame is too short");
             }
 
             BatteryLevel batteryLevel = frame.CommandParameters.Span[0];

diff --git a/src/ZWave.CommandClasses/BinarySensorCommandClass.Report.cs b/src/ZWave.CommandClasses/BinarySensorCommandClass.Report.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -115,7 +115,7 @@ public static BinarySensorReport Parse(CommandClassFrame frame, ILogger logger)
             if (frame.CommandParameters.Length < 1)
             {
                 logger.LogWarning("Binary Sensor Report frame is too short ({Length} bytes)", frame.CommandParameters.Length);
-                throw new ZWaveException(ZWaveErrorCode.InvalidPayload, "Binary Sensor Report frame is too short");
+                ZWaveException.Throw(ZWaveErrorCode.InvalidPayload, "Binary Sensor Report frame is too short");
             }
 
             bool sensorValue = frame.CommandParameters.Span[0] == 0xff;

diff --git a/src/ZWave.CommandClasses/BinarySensorCommandClass.SupportedSensor.cs b/src/ZWave.CommandClasses/BinarySensorCommandClass.SupportedSensor.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -75,7 +75,7 @@ public static IReadOnlySet<BinarySensorType> Parse(CommandClassFrame frame, ILog
             if (frame.CommandParameters.Length < 1)
             {
                 logger.LogWarning("Binary Sensor Supported Report frame is too short ({Length} bytes)", frame.CommandParameters.Length);
-                throw new ZWaveException(ZWaveErrorCode.InvalidPayload, "Binary Sensor Supported Report frame is too short");
+                ZWaveException.Throw(ZWaveErrorCode.InvalidPayload, "Binary Sensor Supported Report frame is too short");
             }
 
             return BitMaskHelper.ParseBitMask<BinarySensorType>(frame.CommandParameters.Span);

diff --git a/src/ZWave.CommandClasses/BinarySwitchCommandClass.cs b/src/ZWave.CommandClasses/BinarySwitchCommandClass.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -177,7 +177,7 @@ public static BinarySwitchReport Parse(CommandClassFrame frame, ILogger logger)
             if (frame.CommandParameters.Length < 1)
             {
                 logger.LogWarning("Binary Switch Report frame is too short ({Length} bytes)", frame.CommandParameters.Length);
-                throw new ZWaveException(ZWaveErrorCode.InvalidPayload, "Binary Switch Report frame is too short");
+                ZWaveException.Throw(ZWaveErrorCode.InvalidPayload, "Binary Switch Report frame is too short");
             }
 
             GenericValue currentValue = frame.CommandParameters.Span[0];

diff --git a/src/ZWave.CommandClasses/ClockCommandClass.cs b/src/ZWave.CommandClasses/ClockCommandClass.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -225,7 +225,7 @@ public static ClockReport Parse(CommandClassFrame frame, ILogger logger)
             if (frame.CommandParameters.Length < 2)
             {
                 logger.LogWarning("Clock Report frame is too short ({Length} bytes)", frame.CommandParameters.Length);
-                throw new ZWaveException(ZWaveErrorCode.InvalidPayload, "Clock Report frame is too short");
+                ZWaveException.Throw(ZWaveErrorCode.InvalidPayload, "Clock Report frame is too short");
             }
 
             ReadOnlySpan<byte> span = frame.CommandParameters.Span;
@@ -240,7 +240,8 @@ public static ClockReport Parse(CommandClassFrame frame, ILogger logger)
             catch (ArgumentOutOfRangeException)
             {
                 logger.LogWarning("Clock Report has invalid time values (hour={Hour}, minute={Minute})", hour, minute);
-                throw new ZWaveException(ZWaveErrorCode.InvalidPayload, "Clock Report has invalid time values");
+                ZWaveException.Throw(ZWaveErrorCode.InvalidPayload, "Clock Report has invalid time values");
+                return default;
             }
         }
     }

diff --git a/src/ZWave.CommandClasses/ColorSwitchCommandClass.Report.cs b/src/ZWave.CommandClasses/ColorSwitchCommandClass.Report.cs
@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 
 namespace ZWave.CommandClasses;
 
@@ -112,7 +112,7 @@ public static ColorSwitchReport Parse(CommandClassFrame frame, ILogger logger)
             if (frame.CommandParameters.Length < 2)
             {
                 logger.LogWarning("Color Switch Report frame is too short ({Length} bytes)", frame.CommandParameters.Length);
-                throw new ZWaveException(ZWaveErrorCode.InvalidPayload, "Color Switch Report frame is too short");
+                ZWaveException.Throw(ZWaveErrorCode.InvalidPayload, "Color Switch Report frame is too short");
             }
 
             ReadOnlySpan<byte> span = frame.CommandParameters.Span;