Subsystem 4e: Per-device unreachable status (switches/alarms/storage, inline) (#36)

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

* feat(devices): persist per-device Reachability (+ migration, store mutators)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(devices): pure RustPlusErrorCode -> DeviceReachability mapper

* refactor(devices): widen connection reads/actuation to carry DeviceReachability

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(devices): connect-prime publishes per-device reachability

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(devices): collapse deliberation comment in SwitchPrimingTests

* feat(devices): periodic reachability poll publishes on change

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(switches): inline per-device reachability (relay + renderer + EN/FR)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(alarms): inline per-device reachability (relay + renderer + EN/FR)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(storage): inline per-device reachability (relay + renderer + EN/FR)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(switches): surface actuation reachability reason + update embed

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

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/Connections/IRustServerQuery.cs

@@ -79,28 +79,28 @@ Task<IReadOnlyList<MonumentSnapshot>> GetMonumentsAsync(
         ulong entityId,
         CancellationToken cancellationToken);
 
-    /// <summary>Sets a smart switch on/off; returns false when there is no live socket or the call fails.</summary>
+    /// <summary>Sets a smart switch on/off; returns the reachability reason when the call fails or there is no live socket.</summary>
     /// <param name="guildId">The owning guild snowflake.</param>
     /// <param name="serverId">The target server id.</param>
     /// <param name="entityId">The in-game smart-switch entity id.</param>
     /// <param name="value">True to turn on, false to turn off.</param>
     /// <param name="cancellationToken">A cancellation token.</param>
-    /// <returns>True on success; false when unavailable or the call fails.</returns>
-    Task<bool> SetSmartSwitchAsync(ulong guildId,
+    /// <returns><see cref="DeviceReachability.Reachable"/> on success; the failure reason otherwise.</returns>
+    Task<DeviceReachability> SetSmartSwitchAsync(ulong guildId,
         Guid serverId,
         ulong entityId,
         bool value,
         CancellationToken cancellationToken);
 
-    /// <summary>Strobes a smart switch; returns false when there is no live socket or the call fails.</summary>
+    /// <summary>Strobes a smart switch; returns the reachability reason when the call fails or there is no live socket.</summary>
     /// <param name="guildId">The owning guild snowflake.</param>
     /// <param name="serverId">The target server id.</param>
     /// <param name="entityId">The in-game smart-switch entity id.</param>
     /// <param name="timeoutMs">The in-game strobe duration in milliseconds.</param>
     /// <param name="value">The terminal value after strobing.</param>
     /// <param name="cancellationToken">A cancellation token.</param>
-    /// <returns>True on success; false when unavailable or the call fails.</returns>
-    Task<bool> StrobeSmartSwitchAsync(ulong guildId,
+    /// <returns><see cref="DeviceReachability.Reachable"/> on success; the failure reason otherwise.</returns>
+    Task<DeviceReachability> StrobeSmartSwitchAsync(ulong guildId,
         Guid serverId,
         ulong entityId,
         int timeoutMs,

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);

src/RustPlusBot.Domain/Alarms/SmartAlarm.cs

@@ -1,3 +1,5 @@
+using RustPlusBot.Abstractions.Connections;
+
 namespace RustPlusBot.Domain.Alarms;
 
 /// <summary>A paired Smart Alarm the bot manages, surviving restarts. Guild- and server-scoped. Driven by the live socket (primed on connect, reacts to SmartDeviceTriggered) — the entity id is the switch-vs-alarm discriminant.</summary>
@@ -38,4 +40,7 @@ public sealed class SmartAlarm
 
     /// <summary>When the alarm most recently went active (UTC), or null if never triggered.</summary>
     public DateTimeOffset? LastTriggeredUtc { get; set; }
+
+    /// <summary>Per-device reachability; defaults to Reachable. Orthogonal to whole-server connection status.</summary>
+    public DeviceReachability Reachability { get; set; } = DeviceReachability.Reachable;
 }

src/RustPlusBot.Domain/StorageMonitors/SmartStorageMonitor.cs

@@ -1,3 +1,5 @@
+using RustPlusBot.Abstractions.Connections;
+
 namespace RustPlusBot.Domain.StorageMonitors;
 
 /// <summary>A paired Smart Storage Monitor the bot manages, surviving restarts. Guild- and server-scoped.</summary>
@@ -26,4 +28,7 @@ public sealed class SmartStorageMonitor
 
     /// <summary>When the monitor was accepted (UTC).</summary>
     public DateTimeOffset CreatedUtc { get; set; }
+
+    /// <summary>Per-device reachability; defaults to Reachable. Orthogonal to whole-server connection status.</summary>
+    public DeviceReachability Reachability { get; set; } = DeviceReachability.Reachable;
 }

src/RustPlusBot.Domain/Switches/SmartSwitch.cs

@@ -1,3 +1,5 @@
+using RustPlusBot.Abstractions.Connections;
+
 namespace RustPlusBot.Domain.Switches;
 
 /// <summary>A paired Smart Switch the bot manages, surviving restarts. Guild- and server-scoped.</summary>
@@ -29,4 +31,7 @@ public sealed class SmartSwitch
 
     /// <summary>When the switch was accepted (UTC).</summary>
     public DateTimeOffset CreatedUtc { get; set; }
+
+    /// <summary>Per-device reachability; defaults to Reachable. Orthogonal to whole-server connection status.</summary>
+    public DeviceReachability Reachability { get; set; } = DeviceReachability.Reachable;
 }

src/RustPlusBot.Features.Alarms/Hosting/AlarmsHostedService.cs

@@ -6,10 +6,10 @@
 
 namespace RustPlusBot.Features.Alarms.Hosting;
 
-/// <summary>Runs the alarm-pairing loop, the alarm-triggered relay loop, and the connection-status relay loop.</summary>
+/// <summary>Runs the alarm-pairing loop, the alarm-triggered relay loop, the connection-status relay loop, and the per-device reachability loop.</summary>
 /// <param name="eventBus">The in-process event bus.</param>
 /// <param name="coordinator">Handles paired alarms.</param>
-/// <param name="relay">Re-renders alarms on trigger/connection changes.</param>
+/// <param name="relay">Re-renders alarms on trigger/connection/reachability changes.</param>
 /// <param name="logger">The logger.</param>
 internal sealed partial class AlarmsHostedService(
     IEventBus eventBus,
@@ -19,6 +19,7 @@ internal sealed partial class AlarmsHostedService(
 {
     private readonly CancellationTokenSource _cts = new();
     private Task? _pairedLoop;
+    private Task? _reachabilityLoop;
     private Task? _statusLoop;
     private Task? _triggeredLoop;
 
@@ -31,6 +32,7 @@ public Task StartAsync(CancellationToken cancellationToken)
         _pairedLoop = Task.Run(() => ConsumePairedAsync(_cts.Token), CancellationToken.None);
         _triggeredLoop = Task.Run(() => ConsumeTriggeredAsync(_cts.Token), CancellationToken.None);
         _statusLoop = Task.Run(() => ConsumeStatusAsync(_cts.Token), CancellationToken.None);
+        _reachabilityLoop = Task.Run(() => ConsumeReachabilityChangedAsync(_cts.Token), CancellationToken.None);
         return Task.CompletedTask;
     }
 
@@ -40,7 +42,7 @@ public async Task StopAsync(CancellationToken cancellationToken)
         await _cts.CancelAsync().ConfigureAwait(false);
         foreach (var loop in new[]
                  {
-                     _pairedLoop, _triggeredLoop, _statusLoop
+                     _pairedLoop, _triggeredLoop, _statusLoop, _reachabilityLoop
                  }.Where(t => t is not null))
         {
             try
@@ -122,6 +124,28 @@ private async Task ConsumeStatusAsync(CancellationToken cancellationToken)
         }
     }
 
+    private async Task ConsumeReachabilityChangedAsync(CancellationToken cancellationToken)
+    {
+        try
+        {
+            await foreach (var evt in eventBus.SubscribeAsync<DeviceReachabilityChangedEvent>(cancellationToken)
+                               .ConfigureAwait(false))
+            {
+                await relay.HandleReachabilityChangedAsync(evt, cancellationToken).ConfigureAwait(false);
+            }
+        }
+        catch (OperationCanceledException)
+        {
+            // Shutting down.
+        }
+#pragma warning disable CA1031 // Broad catch: a faulting consumer must not crash the host.
+        catch (Exception ex)
+#pragma warning restore CA1031
+        {
+            LogReachabilityLoopFaulted(logger, ex);
+        }
+    }
+
     [LoggerMessage(Level = LogLevel.Error, Message = "Alarm pairing loop faulted.")]
     private static partial void LogPairedLoopFaulted(ILogger logger, Exception exception);
 
@@ -130,4 +154,7 @@ private async Task ConsumeStatusAsync(CancellationToken cancellationToken)
 
     [LoggerMessage(Level = LogLevel.Error, Message = "Alarm connection-status relay loop faulted.")]
     private static partial void LogStatusLoopFaulted(ILogger logger, Exception exception);
+
+    [LoggerMessage(Level = LogLevel.Error, Message = "Alarm reachability relay loop faulted.")]
+    private static partial void LogReachabilityLoopFaulted(ILogger logger, Exception exception);
 }

src/RustPlusBot.Features.Alarms/Relaying/AlarmStateRelay.cs

@@ -10,6 +10,7 @@
 using RustPlusBot.Localization;
 using RustPlusBot.Persistence.Alarms;
 using RustPlusBot.Persistence.Connections;
+using RustPlusBot.Abstractions.Connections;
 using RustPlusBot.Persistence.Workspace;
 
 namespace RustPlusBot.Features.Alarms.Relaying;
@@ -134,6 +135,39 @@ public async Task HandleConnectionStatusAsync(ConnectionStatusChangedEvent evt,
         }
     }
 
+    /// <summary>
+    /// Handles a per-device reachability change: if the entity belongs to a managed alarm, persists the new
+    /// reachability and triggers a refresh. Foreign entities are silently ignored.
+    /// </summary>
+    /// <param name="evt">The device-reachability-changed event.</param>
+    /// <param name="cancellationToken">A cancellation token.</param>
+    /// <returns>A task that completes when the embed has been re-rendered (or the entity was ignored).</returns>
+    public async Task HandleReachabilityChangedAsync(
+        DeviceReachabilityChangedEvent evt,
+        CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(evt);
+        var scope = scopeFactory.CreateAsyncScope();
+        await using (scope.ConfigureAwait(false))
+        {
+            var store = scope.ServiceProvider.GetRequiredService<IAlarmStore>();
+            if (!await store.ExistsAsync(evt.GuildId, evt.ServerId, evt.EntityId, cancellationToken)
+                    .ConfigureAwait(false))
+            {
+                return; // not an alarm this relay manages — ignore.
+            }
+
+            await store.SetReachabilityAsync(evt.GuildId, evt.ServerId, evt.EntityId, evt.Reachability,
+                    cancellationToken)
+                .ConfigureAwait(false);
+        }
+
+        // The refresher re-loads + renders; server-down 'unreachable' stays false here — the connection-status
+        // path owns that flag. The renderer reads alarm.Reachability for the per-device reason.
+        await refresher.RefreshAsync(evt.GuildId, evt.ServerId, evt.EntityId, unreachable: false, cancellationToken)
+            .ConfigureAwait(false);
+    }
+
     private async Task RelayToTeamChatSafeAsync(SmartDeviceTriggeredEvent evt, string name, CancellationToken ct)
     {
         try

src/RustPlusBot.Features.Alarms/Rendering/AlarmEmbedRenderer.cs

@@ -1,5 +1,6 @@
 using System.Globalization;
 using Discord;
+using RustPlusBot.Abstractions.Connections;
 using RustPlusBot.Abstractions.Time;
 using RustPlusBot.Domain.Alarms;
 using RustPlusBot.Localization;
@@ -22,7 +23,19 @@ internal sealed class AlarmEmbedRenderer(ILocalizer localizer, IClock clock)
 
         string statusKey;
 #pragma warning disable IDE0045 // Collapsing to a nested ternary trips RCS1238/S3358 (nested conditional); the if/else chain is intentional.
-        if (unreachable)
+        if (alarm.Reachability == DeviceReachability.Removed)
+        {
+            statusKey = "alarm.status.removed";
+        }
+        else if (alarm.Reachability == DeviceReachability.NoPrivilege)
+        {
+            statusKey = "alarm.status.noprivilege";
+        }
+        else if (alarm.Reachability == DeviceReachability.NoResponse)
+        {
+            statusKey = "alarm.status.noresponse";
+        }
+        else if (unreachable)
         {
             statusKey = "alarm.status.unreachable";
         }
@@ -36,6 +49,11 @@ internal sealed class AlarmEmbedRenderer(ILocalizer localizer, IClock clock)
         }
 #pragma warning restore IDE0045
 
+        // Removed and NoPrivilege disable controls (device is gone or locked); NoResponse leaves them enabled
+        // so the user can still interact while the device is temporarily unresponsive.
+        var blocked = alarm.Reachability is DeviceReachability.Removed or DeviceReachability.NoPrivilege;
+        var disableButtons = unreachable || blocked;
+
         var triggered = alarm.LastTriggeredUtc is { } t
             ? localizer.Get("alarm.embed.lasttriggered", culture, CompactDuration(clock.UtcNow - t))
             : localizer.Get("alarm.embed.nevertriggered", culture);
@@ -51,11 +69,11 @@ internal sealed class AlarmEmbedRenderer(ILocalizer localizer, IClock clock)
         var relayKey = alarm.RelayToTeamChat ? "alarm.button.relay.on" : "alarm.button.relay.off";
         var components = new ComponentBuilder()
             .WithButton(localizer.Get(pingKey, culture), AlarmComponentIds.PingTogglePrefix + tail,
-                alarm.PingEveryone ? ButtonStyle.Success : ButtonStyle.Secondary, disabled: unreachable)
+                alarm.PingEveryone ? ButtonStyle.Success : ButtonStyle.Secondary, disabled: disableButtons)
             .WithButton(localizer.Get(relayKey, culture), AlarmComponentIds.RelayTogglePrefix + tail,
-                alarm.RelayToTeamChat ? ButtonStyle.Success : ButtonStyle.Secondary, disabled: unreachable)
+                alarm.RelayToTeamChat ? ButtonStyle.Success : ButtonStyle.Secondary, disabled: disableButtons)
             .WithButton(localizer.Get("alarm.button.rename", culture), AlarmComponentIds.RenamePrefix + tail,
-                ButtonStyle.Secondary, disabled: unreachable)
+                ButtonStyle.Secondary, disabled: disableButtons)
             .Build();
 
         return (embed, components);