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

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

Author: HandyS11

src/RustPlusBot.Features.Events/Classifying/MapEventKind.cs

@@ -0,0 +1,20 @@
+namespace RustPlusBot.Features.Events.Classifying;
+
+/// <summary>A classified live map event.</summary>
+public enum MapEventKind
+{
+    /// <summary>A cargo ship entered the map.</summary>
+    CargoEntered = 0,
+
+    /// <summary>A cargo ship left the map.</summary>
+    CargoLeft = 1,
+
+    /// <summary>A patrol helicopter entered the map.</summary>
+    HeliEntered = 2,
+
+    /// <summary>A patrol helicopter left the map.</summary>
+    HeliLeft = 3,
+
+    /// <summary>A Chinook spawned.</summary>
+    ChinookSpawned = 4,
+}

src/RustPlusBot.Features.Events/Classifying/MarkerEventClassifier.cs

@@ -0,0 +1,51 @@
+using RustPlusBot.Abstractions.Events;
+using RustPlusBot.Abstractions.Time;
+using RustPlusBot.Features.Connections.Listening;
+
+namespace RustPlusBot.Features.Events.Classifying;
+
+/// <summary>Maps raw marker add/remove deltas to domain map events.</summary>
+/// <param name="clock">Stamps each produced event.</param>
+internal sealed class MarkerEventClassifier(IClock clock)
+{
+    /// <summary>Classifies one marker-change delta into zero or more domain events.</summary>
+    /// <param name="evt">The marker-change delta.</param>
+    /// <returns>The classified events, in delta order (added first, then removed).</returns>
+    public IReadOnlyList<RustMapEvent> Classify(MapMarkersChangedEvent evt)
+    {
+        ArgumentNullException.ThrowIfNull(evt);
+        var now = clock.UtcNow;
+        var events = new List<RustMapEvent>();
+
+        foreach (var m in evt.Added)
+        {
+            MapEventKind? kind = m.Kind switch
+            {
+                MarkerKind.CargoShip => MapEventKind.CargoEntered,
+                MarkerKind.PatrolHelicopter => MapEventKind.HeliEntered,
+                MarkerKind.Chinook => MapEventKind.ChinookSpawned,
+                _ => null, // Crate/Other → no event (the game no longer sends crate markers).
+            };
+            if (kind is { } k)
+            {
+                events.Add(new RustMapEvent(k, m.X, m.Y, evt.Dimensions, now));
+            }
+        }
+
+        foreach (var m in evt.Removed)
+        {
+            MapEventKind? kind = m.Kind switch
+            {
+                MarkerKind.CargoShip => MapEventKind.CargoLeft,
+                MarkerKind.PatrolHelicopter => MapEventKind.HeliLeft,
+                _ => null, // Chinook/Crate removal is silent.
+            };
+            if (kind is { } k)
+            {
+                events.Add(new RustMapEvent(k, m.X, m.Y, evt.Dimensions, now));
+            }
+        }
+
+        return events;
+    }
+}

src/RustPlusBot.Features.Events/Classifying/RustMapEvent.cs

@@ -0,0 +1,11 @@
+using RustPlusBot.Features.Connections.Listening;
+
+namespace RustPlusBot.Features.Events.Classifying;
+
+/// <summary>A classified live map event with its location and time.</summary>
+/// <param name="Kind">The event kind.</param>
+/// <param name="X">World X coordinate.</param>
+/// <param name="Y">World Y coordinate.</param>
+/// <param name="Dimensions">Map dimensions for grid rendering, or null.</param>
+/// <param name="AtUtc">When the event was observed.</param>
+public sealed record RustMapEvent(MapEventKind Kind, float X, float Y, MapDimensions? Dimensions, DateTimeOffset AtUtc);

tests/RustPlusBot.Features.Events.Tests/Classifying/MarkerEventClassifierTests.cs

@@ -0,0 +1,90 @@
+using NSubstitute;
+using RustPlusBot.Abstractions.Events;
+using RustPlusBot.Abstractions.Time;
+using RustPlusBot.Features.Connections.Listening;
+using RustPlusBot.Features.Events.Classifying;
+
+namespace RustPlusBot.Features.Events.Tests.Classifying;
+
+public sealed class MarkerEventClassifierTests
+{
+    private static readonly Guid Server = Guid.NewGuid();
+    private static readonly DateTimeOffset Now = new(2026, 6, 17, 12, 0, 0, TimeSpan.Zero);
+
+    private static MarkerEventClassifier Build()
+    {
+        var clock = Substitute.For<IClock>();
+        clock.UtcNow.Returns(Now);
+        return new MarkerEventClassifier(clock);
+    }
+
+    private static MapMarkersChangedEvent Evt(
+        IReadOnlyList<MapMarkerSnapshot> added,
+        IReadOnlyList<MapMarkerSnapshot> removed) =>
+        new(1UL, Server, new MapDimensions(4000u, 4000u, 500), added, removed);
+
+    [Fact]
+    public void Cargo_added_is_CargoEntered()
+    {
+        var result = Build().Classify(Evt(
+            [new MapMarkerSnapshot(1, MarkerKind.CargoShip, 10f, 20f, null)], []));
+
+        var e = Assert.Single(result);
+        Assert.Equal(MapEventKind.CargoEntered, e.Kind);
+        Assert.Equal(Now, e.AtUtc);
+        Assert.NotNull(e.Dimensions);
+    }
+
+    [Fact]
+    public void Cargo_removed_is_CargoLeft()
+    {
+        var result = Build().Classify(Evt([],
+            [new MapMarkerSnapshot(1, MarkerKind.CargoShip, 10f, 20f, null)]));
+        Assert.Equal(MapEventKind.CargoLeft, Assert.Single(result).Kind);
+    }
+
+    [Fact]
+    public void Heli_added_and_removed_map_to_entered_and_left()
+    {
+        Assert.Equal(MapEventKind.HeliEntered, Assert.Single(Build().Classify(
+            Evt([new MapMarkerSnapshot(2, MarkerKind.PatrolHelicopter, 0f, 0f, null)], []))).Kind);
+        Assert.Equal(MapEventKind.HeliLeft, Assert.Single(Build().Classify(
+            Evt([], [new MapMarkerSnapshot(2, MarkerKind.PatrolHelicopter, 0f, 0f, null)]))).Kind);
+    }
+
+    [Fact]
+    public void Chinook_added_is_spawned_but_removal_is_silent()
+    {
+        Assert.Equal(MapEventKind.ChinookSpawned, Assert.Single(Build().Classify(
+            Evt([new MapMarkerSnapshot(3, MarkerKind.Chinook, 0f, 0f, null)], []))).Kind);
+        Assert.Empty(Build().Classify(
+            Evt([], [new MapMarkerSnapshot(3, MarkerKind.Chinook, 0f, 0f, null)])));
+    }
+
+    [Fact]
+    public void Crate_and_other_markers_produce_nothing()
+    {
+        // The game no longer sends crate markers; MarkerKind.Crate (and Other) classify to nothing.
+        Assert.Empty(Build().Classify(Evt(
+            [
+                new MapMarkerSnapshot(4, MarkerKind.Crate, 0f, 0f, null),
+                new MapMarkerSnapshot(5, MarkerKind.Other, 0f, 0f, null)
+            ],
+            [
+                new MapMarkerSnapshot(6, MarkerKind.Crate, 0f, 0f, null),
+                new MapMarkerSnapshot(7, MarkerKind.Other, 0f, 0f, null)
+            ])));
+    }
+
+    [Fact]
+    public void Multiple_deltas_produce_multiple_events()
+    {
+        var result = Build().Classify(Evt(
+            [
+                new MapMarkerSnapshot(1, MarkerKind.CargoShip, 0f, 0f, null),
+                new MapMarkerSnapshot(3, MarkerKind.Chinook, 0f, 0f, null)
+            ],
+            [new MapMarkerSnapshot(2, MarkerKind.PatrolHelicopter, 0f, 0f, null)]));
+        Assert.Equal(3, result.Count);
+    }
+}