Subsystem 2a: live events poller + #events alerts + event !commands (#13)

* feat(2a): add map-marker snapshot, dimensions, and MapMarkersChangedEvent

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(2a): add GetMapMarkers/GetMapDimensions to the connection seam + fake

* feat(2a): poll map markers in the connected window and publish diffs

Adds MarkerPollInterval to ConnectionOptions (default 10s) and a
PollMarkersAsync loop to ConnectionSupervisor: fetches map dimensions
once on connect, polls markers on the configured interval, diffs each
result against the previous snapshot, and publishes MapMarkersChangedEvent
on the event bus. The first poll is a silent baseline; failed polls retain
the previous snapshot without producing a spurious diff. Three integration
tests verify the silent baseline, the added-marker publish, and the
failed-poll snapshot-retention contract.

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

* fix(2a): strengthen marker-poll baseline test + deterministic fake script

- FakeRustSocketSource: add source-level EnqueueMarkers that pre-stages
  marker lists and transfers them to FakeConnection at Create time,
  eliminating the setup race between test code and the poll loop.
- FakeConnection: add per-connection ConcurrentQueue<IReadOnlyList<
  MapMarkerSnapshot>> with "hold last" behaviour mirroring NextHeartbeat;
  EnqueueMarkers on the connection available for post-connect injection.
  Existing MarkersResult fallback preserved for Task-2 / no-script callers.
- First_marker_poll_is_a_silent_baseline: rewritten to script poll 1+2 with
  a CargoShip (baseline + no-change) and poll 3 with CargoShip+Heli; waits
  for the definite heli-added event as the race-free signal proving both
  baseline suppression and diff correctness.
- Marker_added_on_a_later_poll_publishes_changed_event: scripted via source
  queue before EnsureConnectionAsync; asserts exact MapDimensions(4000,4000,
  500) from the FakeConnection default.
- Failed_marker_poll_retains_previous_snapshot: polls 1+2 scripted via
  source queue; MarkersThrow used post-event for the throw/recover cycle;
  hold-last means recovery sees the same CargoShip → no spurious event.
- ConnectionOptions.MarkerPollInterval: init → set for IOptions binding.

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

* feat(2a): scaffold Features.Events project + GridReference helper

* feat(2a): add MarkerEventClassifier mapping deltas to domain events

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(2a): add in-memory EventStateStore + IEventState read-seam

* feat(2a): add EventEmbedRenderer + EN/FR event localization

Implements the pure event rendering layer: EventLocalizationCatalog with EN/FR
strings for cargo, helicopter, and Chinook events; IEventLocalizer/EventLocalizer
for localization; EventEmbedRenderer to build Discord embeds with grid references.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(2a): EventRelay, #events poster/locator, hosted service, DI + Workspace spec

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

* feat(2a): register Events feature + MarkerPollInterval option in the host

* feat(2a): add !cargo/!heli/!chinook/!events in-game command handlers

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

* docs(2a): document the #events channel

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

* fix(2a): derive grid row count from Height, not Width (final review)

GridReference computed the row count from Width and never read Height/
OceanMargin — correct only because Rust maps are square. Derive each axis
from its own dimension so the grid math is correct by construction.
Behavior-preserving for square maps; GridReference tests unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(2a): address Copilot review on PR #13

- EventEmbedRenderer + EventsCommandHandler: throw ArgumentOutOfRangeException
  on an unknown MapEventKind instead of silently falling back to the chinook
  key (fail-fast if a future kind is added).
- IRustServerConnection.GetMapMarkersAsync: correct the stale "all kinds /
  MarkerKind.Other" XML doc — the mapped facade only surfaces cargo/heli/chinook.
- RustPlusSocketSource.AddMarkers: skip markers with null X/Y instead of
  substituting (0,0), which would diff as a phantom spawn/despawn at the origin.
- DiscordEventChannelPoster: forward the CancellationToken via
  RequestOptions.CancelToken (and rethrow OperationCanceledException so a
  shutdown cancel isn't logged as a post failure).
- running-locally.md: chinook only alerts on spawn (cargo/heli on enter+leave) —
  reword the #events description to match actual behavior.
- EventStateStoreTests: rename the un-alerted-removal test for clarity
  (behavior was already correct).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: HandyS11

RustPlusBot.slnx

@@ -8,6 +8,7 @@
     <Project Path="src/RustPlusBot.Features.Connections/RustPlusBot.Features.Connections.csproj" />
     <Project Path="src/RustPlusBot.Features.Pairing/RustPlusBot.Features.Pairing.csproj" />
     <Project Path="src/RustPlusBot.Features.Chat/RustPlusBot.Features.Chat.csproj" />
+    <Project Path="src/RustPlusBot.Features.Events/RustPlusBot.Features.Events.csproj" />
     <Project Path="src/RustPlusBot.Features.Workspace/RustPlusBot.Features.Workspace.csproj" />
     <Project Path="src/RustPlusBot.Persistence/RustPlusBot.Persistence.csproj" />
   </Folder>
@@ -18,6 +19,7 @@
     <Project Path="tests/RustPlusBot.Features.Pairing.Tests/RustPlusBot.Features.Pairing.Tests.csproj" />
     <Project Path="tests/RustPlusBot.Features.Workspace.Tests/RustPlusBot.Features.Workspace.Tests.csproj" />
     <Project Path="tests/RustPlusBot.Features.Chat.Tests/RustPlusBot.Features.Chat.Tests.csproj" />
+    <Project Path="tests/RustPlusBot.Features.Events.Tests/RustPlusBot.Features.Events.Tests.csproj" />
     <Project Path="tests/RustPlusBot.Persistence.Tests/RustPlusBot.Persistence.Tests.csproj" />
   </Folder>
 </Solution>

docs/development/running-locally.md

@@ -63,3 +63,9 @@ overwritten on every startup, so a normal run after the reset leaves only the cu
 5. In Development (`Workspace:EnableDangerCommands = true`), use
    `/workspace simulate-server name:<n> ip:<host> port:<port>` to create a server category, and
    `/workspace reset` to delete the whole workspace.
+
+Each provisioned server category also includes an `#events` channel, which receives live alerts when a
+**cargo ship** or **patrol helicopter** enters or leaves the map and when a **chinook** spawns. No new
+Discord gateway intent is required — event markers are detected by polling the Rust+ socket, not the
+Discord gateway; only the existing **Send Messages** and **Embed Links** permissions on the provisioned
+channel are used.

src/RustPlusBot.Abstractions/Connections/MapDimensions.cs

@@ -0,0 +1,7 @@
+namespace RustPlusBot.Features.Connections.Listening;
+
+/// <summary>The static-per-wipe map size needed to convert world coordinates to a grid reference.</summary>
+/// <param name="Width">Map image width.</param>
+/// <param name="Height">Map image height.</param>
+/// <param name="OceanMargin">The ocean margin around the playable area.</param>
+public sealed record MapDimensions(uint Width, uint Height, int OceanMargin);

src/RustPlusBot.Abstractions/Connections/MapMarkerSnapshot.cs

@@ -0,0 +1,9 @@
+namespace RustPlusBot.Features.Connections.Listening;
+
+/// <summary>One map marker observed in a <c>GetMapMarkers</c> poll.</summary>
+/// <param name="Id">The stable marker id (used to diff polls).</param>
+/// <param name="Kind">The classified marker kind.</param>
+/// <param name="X">World X coordinate.</param>
+/// <param name="Y">World Y coordinate.</param>
+/// <param name="Name">The marker name, if any.</param>
+public sealed record MapMarkerSnapshot(ulong Id, MarkerKind Kind, float X, float Y, string? Name);

src/RustPlusBot.Abstractions/Connections/MarkerKind.cs

@@ -0,0 +1,20 @@
+namespace RustPlusBot.Features.Connections.Listening;
+
+/// <summary>The subset of Rust map-marker types this bot reasons about; everything else is <see cref="Other"/>.</summary>
+public enum MarkerKind
+{
+    /// <summary>A marker type the bot does not classify (player, vending, explosion, generic radius, vendor).</summary>
+    Other = 0,
+
+    /// <summary>A cargo ship.</summary>
+    CargoShip = 1,
+
+    /// <summary>A patrol helicopter.</summary>
+    PatrolHelicopter = 2,
+
+    /// <summary>A Chinook (CH-47).</summary>
+    Chinook = 3,
+
+    /// <summary>A locked crate.</summary>
+    Crate = 4,
+}

src/RustPlusBot.Abstractions/Events/MapMarkersChangedEvent.cs

@@ -0,0 +1,16 @@
+using RustPlusBot.Features.Connections.Listening;
+
+namespace RustPlusBot.Abstractions.Events;
+
+/// <summary>Published when a marker poll detects markers that appeared or disappeared since the previous poll.</summary>
+/// <param name="GuildId">The owning guild snowflake.</param>
+/// <param name="ServerId">The target server id.</param>
+/// <param name="Dimensions">Map dimensions for grid-reference rendering, or null if unavailable.</param>
+/// <param name="Added">Markers present now that were absent in the previous poll.</param>
+/// <param name="Removed">Markers absent now that were present in the previous poll.</param>
+public sealed record MapMarkersChangedEvent(
+    ulong GuildId,
+    Guid ServerId,
+    MapDimensions? Dimensions,
+    IReadOnlyList<MapMarkerSnapshot> Added,
+    IReadOnlyList<MapMarkerSnapshot> Removed);

src/RustPlusBot.Features.Commands/CommandServiceCollectionExtensions.cs

@@ -38,6 +38,10 @@ public static IServiceCollection AddCommands(this IServiceCollection services)
         services.AddScoped<ICommandHandler, SteamIdCommandHandler>();
         services.AddScoped<ICommandHandler, AliveCommandHandler>();
         services.AddScoped<ICommandHandler, ProxCommandHandler>();
+        services.AddScoped<ICommandHandler, CargoCommandHandler>();
+        services.AddScoped<ICommandHandler, HeliCommandHandler>();
+        services.AddScoped<ICommandHandler, ChinookCommandHandler>();
+        services.AddScoped<ICommandHandler, EventsCommandHandler>();
 
         services.AddScoped<CommandDispatcher>();
         services.AddHostedService<CommandsHostedService>();

src/RustPlusBot.Features.Commands/Handlers/CargoCommandHandler.cs

@@ -0,0 +1,36 @@
+using RustPlusBot.Abstractions.Time;
+using RustPlusBot.Features.Commands.Dispatching;
+using RustPlusBot.Features.Commands.Formatting;
+using RustPlusBot.Features.Commands.Localization;
+using RustPlusBot.Features.Connections.Listening;
+using RustPlusBot.Features.Events.Formatting;
+using RustPlusBot.Features.Events.State;
+
+namespace RustPlusBot.Features.Commands.Handlers;
+
+/// <summary>!cargo — reports the cargo ship's current grid position, if any.</summary>
+/// <param name="state">The live event state.</param>
+/// <param name="localizer">The reply localizer.</param>
+/// <param name="clock">For "how long ago".</param>
+internal sealed class CargoCommandHandler(IEventState state, ICommandLocalizer localizer, IClock clock)
+    : ICommandHandler
+{
+    /// <inheritdoc />
+    public string Name => "cargo";
+
+    /// <inheritdoc />
+    public Task<string?> ExecuteAsync(CommandContext context, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+        var markers = state.GetActiveMarkers(context.GuildId, context.ServerId, MarkerKind.CargoShip);
+        if (markers.Count == 0)
+        {
+            return Task.FromResult<string?>(localizer.Get("command.cargo.none", context.Culture));
+        }
+
+        var m = markers[0];
+        var grid = GridReference.From(m.X, m.Y, m.Dimensions);
+        var ago = DurationFormat.Compact(clock.UtcNow - m.SeenAtUtc);
+        return Task.FromResult<string?>(localizer.Get("command.cargo.ok", context.Culture, grid, ago));
+    }
+}

src/RustPlusBot.Features.Commands/Handlers/ChinookCommandHandler.cs

@@ -0,0 +1,36 @@
+using RustPlusBot.Abstractions.Time;
+using RustPlusBot.Features.Commands.Dispatching;
+using RustPlusBot.Features.Commands.Formatting;
+using RustPlusBot.Features.Commands.Localization;
+using RustPlusBot.Features.Connections.Listening;
+using RustPlusBot.Features.Events.Formatting;
+using RustPlusBot.Features.Events.State;
+
+namespace RustPlusBot.Features.Commands.Handlers;
+
+/// <summary>!chinook — reports the Chinook helicopter's current grid position, if any.</summary>
+/// <param name="state">The live event state.</param>
+/// <param name="localizer">The reply localizer.</param>
+/// <param name="clock">For "how long ago".</param>
+internal sealed class ChinookCommandHandler(IEventState state, ICommandLocalizer localizer, IClock clock)
+    : ICommandHandler
+{
+    /// <inheritdoc />
+    public string Name => "chinook";
+
+    /// <inheritdoc />
+    public Task<string?> ExecuteAsync(CommandContext context, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+        var markers = state.GetActiveMarkers(context.GuildId, context.ServerId, MarkerKind.Chinook);
+        if (markers.Count == 0)
+        {
+            return Task.FromResult<string?>(localizer.Get("command.chinook.none", context.Culture));
+        }
+
+        var m = markers[0];
+        var grid = GridReference.From(m.X, m.Y, m.Dimensions);
+        var ago = DurationFormat.Compact(clock.UtcNow - m.SeenAtUtc);
+        return Task.FromResult<string?>(localizer.Get("command.chinook.ok", context.Culture, grid, ago));
+    }
+}

src/RustPlusBot.Features.Commands/Handlers/EventsCommandHandler.cs

@@ -0,0 +1,46 @@
+using RustPlusBot.Features.Commands.Dispatching;
+using RustPlusBot.Features.Commands.Localization;
+using RustPlusBot.Features.Events.Classifying;
+using RustPlusBot.Features.Events.Formatting;
+using RustPlusBot.Features.Events.State;
+
+namespace RustPlusBot.Features.Commands.Handlers;
+
+/// <summary>!events — lists the most recent live events.</summary>
+/// <param name="state">The live event state.</param>
+/// <param name="localizer">The reply localizer.</param>
+internal sealed class EventsCommandHandler(IEventState state, ICommandLocalizer localizer) : ICommandHandler
+{
+    /// <inheritdoc />
+    public string Name => "events";
+
+    /// <inheritdoc />
+    /// <exception cref="ArgumentOutOfRangeException">A recent event has an unsupported <see cref="MapEventKind"/>.</exception>
+    public Task<string?> ExecuteAsync(CommandContext context, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+        var events = state.GetRecentEvents(context.GuildId, context.ServerId);
+        if (events.Count == 0)
+        {
+            return Task.FromResult<string?>(localizer.Get("command.events.none", context.Culture));
+        }
+
+        var parts = events.Select(e =>
+        {
+            var grid = GridReference.From(e.X, e.Y, e.Dimensions);
+            var key = e.Kind switch
+            {
+                MapEventKind.CargoEntered => "command.event.cargoentered",
+                MapEventKind.CargoLeft => "command.event.cargoleft",
+                MapEventKind.HeliEntered => "command.event.helientered",
+                MapEventKind.HeliLeft => "command.event.helileft",
+                MapEventKind.ChinookSpawned => "command.event.chinookspawned",
+                _ => throw new ArgumentOutOfRangeException(nameof(e), e.Kind, "Unsupported map event kind."),
+            };
+            return localizer.Get(key, context.Culture, grid);
+        });
+
+        return Task.FromResult<string?>(
+            localizer.Get("command.events.ok", context.Culture, string.Join(", ", parts)));
+    }
+}