feat(devices): add DeviceReachability vocabulary (enum, readings, event)

Author: HandyS11

src/RustPlusBot.Abstractions/Connections/DeviceReachability.cs

@@ -0,0 +1,17 @@
+namespace RustPlusBot.Abstractions.Connections;
+
+/// <summary>Per-device reachability, independent of whole-server connection status.</summary>
+public enum DeviceReachability
+{
+    /// <summary>The device read/actuated successfully.</summary>
+    Reachable = 0,
+
+    /// <summary>The in-game entity no longer exists (was destroyed). Maps from <c>not_found</c>.</summary>
+    Removed = 1,
+
+    /// <summary>The active player lacks building privilege / token access. Maps from <c>access_denied</c>.</summary>
+    NoPrivilege = 2,
+
+    /// <summary>The device did not answer in time (timeout / unknown / other server error).</summary>
+    NoResponse = 3,
+}

src/RustPlusBot.Abstractions/Connections/DeviceReading.cs

@@ -0,0 +1,11 @@
+namespace RustPlusBot.Abstractions.Connections;
+
+/// <summary>A smart-switch/alarm read: on/off state plus reachability. <see cref="IsActive"/> is null unless <see cref="Reachability"/> is Reachable.</summary>
+/// <param name="IsActive">The device on/off state; null unless Reachable.</param>
+/// <param name="Reachability">The device reachability.</param>
+public readonly record struct DeviceReading(bool? IsActive, DeviceReachability Reachability);
+
+/// <summary>A storage-monitor read: contents plus reachability. <see cref="Contents"/> is null unless <see cref="Reachability"/> is Reachable.</summary>
+/// <param name="Contents">The storage contents snapshot; null unless Reachable.</param>
+/// <param name="Reachability">The device reachability.</param>
+public readonly record struct StorageReading(StorageContentsSnapshot? Contents, DeviceReachability Reachability);

src/RustPlusBot.Abstractions/Events/DeviceReachabilityChangedEvent.cs

@@ -0,0 +1,14 @@
+using RustPlusBot.Abstractions.Connections;
+
+namespace RustPlusBot.Abstractions.Events;
+
+/// <summary>Raised when a managed device's reachability changes. Device-agnostic; relays filter by entity ownership.</summary>
+/// <param name="GuildId">The owning guild snowflake.</param>
+/// <param name="ServerId">The server id.</param>
+/// <param name="EntityId">The in-game entity id.</param>
+/// <param name="Reachability">The new reachability.</param>
+public sealed record DeviceReachabilityChangedEvent(
+    ulong GuildId,
+    Guid ServerId,
+    ulong EntityId,
+    DeviceReachability Reachability);

tests/RustPlusBot.Abstractions.Tests/DeviceReachabilityVocabularyTests.cs

@@ -0,0 +1,30 @@
+using RustPlusBot.Abstractions.Connections;
+using RustPlusBot.Abstractions.Events;
+
+namespace RustPlusBot.Abstractions.Tests;
+
+public sealed class DeviceReachabilityVocabularyTests
+{
+    [Fact]
+    public void DeviceReachability_DefaultIsReachable() =>
+        Assert.Equal(DeviceReachability.Reachable, default);
+
+    [Fact]
+    public void DeviceReading_CarriesPayloadAndReachability()
+    {
+        var reading = new DeviceReading(IsActive: true, DeviceReachability.Reachable);
+        Assert.True(reading.IsActive);
+        Assert.Equal(DeviceReachability.Reachable, reading.Reachability);
+    }
+
+    [Fact]
+    public void Event_CarriesIdentityAndReachability()
+    {
+        var serverId = Guid.NewGuid();
+        var evt = new DeviceReachabilityChangedEvent(10UL, serverId, 99UL, DeviceReachability.Removed);
+        Assert.Equal(10UL, evt.GuildId);
+        Assert.Equal(serverId, evt.ServerId);
+        Assert.Equal(99UL, evt.EntityId);
+        Assert.Equal(DeviceReachability.Removed, evt.Reachability);
+    }
+}