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

Author: HandyS11

src/RustPlusBot.Features.Events/State/ActiveMarker.cs

@@ -0,0 +1,18 @@
+using RustPlusBot.Features.Connections.Listening;
+
+namespace RustPlusBot.Features.Events.State;
+
+/// <summary>A marker currently present on a server's map.</summary>
+/// <param name="Id">The marker id.</param>
+/// <param name="Kind">The marker 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="SeenAtUtc">When the marker was first seen.</param>
+public sealed record ActiveMarker(
+    ulong Id,
+    MarkerKind Kind,
+    float X,
+    float Y,
+    MapDimensions? Dimensions,
+    DateTimeOffset SeenAtUtc);

src/RustPlusBot.Features.Events/State/EventStateStore.cs

@@ -0,0 +1,93 @@
+using System.Collections.Concurrent;
+using RustPlusBot.Abstractions.Events;
+using RustPlusBot.Abstractions.Time;
+using RustPlusBot.Features.Connections.Listening;
+using RustPlusBot.Features.Events.Classifying;
+
+namespace RustPlusBot.Features.Events.State;
+
+/// <summary>In-memory per-(guild, server) active markers and a bounded recent-event ring. Cleared on disconnect.</summary>
+/// <param name="clock">Stamps when markers become active.</param>
+internal sealed class EventStateStore(IClock clock) : IEventState
+{
+    private const int RecentCapacity = 10;
+    private readonly ConcurrentDictionary<(ulong Guild, Guid Server), ServerState> _byServer = new();
+
+    /// <inheritdoc />
+    public IReadOnlyList<ActiveMarker> GetActiveMarkers(ulong guildId, Guid serverId, MarkerKind kind)
+    {
+        if (!_byServer.TryGetValue((guildId, serverId), out var state))
+        {
+            return [];
+        }
+
+        lock (state.Gate)
+        {
+            return state.Active.Values
+                .Where(m => m.Kind == kind)
+                .OrderByDescending(m => m.SeenAtUtc)
+                .ToList();
+        }
+    }
+
+    /// <inheritdoc />
+    public IReadOnlyList<RustMapEvent> GetRecentEvents(ulong guildId, Guid serverId)
+    {
+        if (!_byServer.TryGetValue((guildId, serverId), out var state))
+        {
+            return [];
+        }
+
+        lock (state.Gate)
+        {
+            return state.Recent.ToList(); // already newest-first
+        }
+    }
+
+    /// <summary>Applies one marker-change delta and its classified events.</summary>
+    /// <param name="delta">The raw marker delta (drives the active set).</param>
+    /// <param name="events">The classified events (pushed onto the recent ring).</param>
+    public void Apply(MapMarkersChangedEvent delta, IReadOnlyList<RustMapEvent> events)
+    {
+        ArgumentNullException.ThrowIfNull(delta);
+        ArgumentNullException.ThrowIfNull(events);
+        var state = _byServer.GetOrAdd((delta.GuildId, delta.ServerId), static _ => new ServerState());
+        var now = clock.UtcNow;
+        lock (state.Gate)
+        {
+            foreach (var m in delta.Added)
+            {
+                state.Active[m.Id] = new ActiveMarker(m.Id, m.Kind, m.X, m.Y, delta.Dimensions, now);
+            }
+
+            foreach (var m in delta.Removed)
+            {
+                state.Active.Remove(m.Id);
+            }
+
+            foreach (var e in events)
+            {
+                state.Recent.Insert(0, e);
+            }
+
+            if (state.Recent.Count > RecentCapacity)
+            {
+                state.Recent.RemoveRange(RecentCapacity, state.Recent.Count - RecentCapacity);
+            }
+        }
+    }
+
+    /// <summary>Clears all state for a server (called when its connection drops).</summary>
+    /// <param name="guildId">The owning guild snowflake.</param>
+    /// <param name="serverId">The target server id.</param>
+    public void Clear(ulong guildId, Guid serverId) => _byServer.TryRemove((guildId, serverId), out _);
+
+    private sealed class ServerState
+    {
+        public object Gate { get; } = new();
+
+        public Dictionary<ulong, ActiveMarker> Active { get; } = [];
+
+        public List<RustMapEvent> Recent { get; } = [];
+    }
+}

src/RustPlusBot.Features.Events/State/IEventState.cs

@@ -0,0 +1,21 @@
+using RustPlusBot.Features.Connections.Listening;
+using RustPlusBot.Features.Events.Classifying;
+
+namespace RustPlusBot.Features.Events.State;
+
+/// <summary>Read access to current map markers and recent events (consumed by in-game command handlers).</summary>
+public interface IEventState
+{
+    /// <summary>Gets the currently-active markers of a kind for a server (empty if none/unknown).</summary>
+    /// <param name="guildId">The owning guild snowflake.</param>
+    /// <param name="serverId">The target server id.</param>
+    /// <param name="kind">The marker kind to filter by.</param>
+    /// <returns>The active markers of that kind, newest-first.</returns>
+    IReadOnlyList<ActiveMarker> GetActiveMarkers(ulong guildId, Guid serverId, MarkerKind kind);
+
+    /// <summary>Gets the recent events for a server, newest-first (empty if none/unknown).</summary>
+    /// <param name="guildId">The owning guild snowflake.</param>
+    /// <param name="serverId">The target server id.</param>
+    /// <returns>The recent events, newest-first.</returns>
+    IReadOnlyList<RustMapEvent> GetRecentEvents(ulong guildId, Guid serverId);
+}

tests/RustPlusBot.Features.Events.Tests/State/EventStateStoreTests.cs

@@ -0,0 +1,91 @@
+using NSubstitute;
+using RustPlusBot.Abstractions.Events;
+using RustPlusBot.Abstractions.Time;
+using RustPlusBot.Features.Connections.Listening;
+using RustPlusBot.Features.Events.Classifying;
+using RustPlusBot.Features.Events.State;
+
+namespace RustPlusBot.Features.Events.Tests.State;
+
+public sealed class EventStateStoreTests
+{
+    private const ulong Guild = 1UL;
+    private static readonly Guid Server = Guid.NewGuid();
+    private static readonly DateTimeOffset Now = new(2026, 6, 17, 12, 0, 0, TimeSpan.Zero);
+
+    private static EventStateStore Build()
+    {
+        var clock = Substitute.For<IClock>();
+        clock.UtcNow.Returns(Now);
+        return new EventStateStore(clock);
+    }
+
+    private static MapMarkersChangedEvent Delta(
+        IReadOnlyList<MapMarkerSnapshot> added,
+        IReadOnlyList<MapMarkerSnapshot> removed) =>
+        new(Guild, Server, null, added, removed);
+
+    private static MapMarkersChangedEvent DeltaWithDims(
+        IReadOnlyList<MapMarkerSnapshot> added,
+        IReadOnlyList<MapMarkerSnapshot> removed,
+        MapDimensions? dims) =>
+        new(Guild, Server, dims, added, removed);
+
+    [Fact]
+    public void Added_marker_becomes_active_and_carries_dimensions()
+    {
+        var store = Build();
+        var dims = new MapDimensions(4000u, 4000u, 500);
+        store.Apply(
+            DeltaWithDims([new MapMarkerSnapshot(1, MarkerKind.CargoShip, 10f, 20f, null)], [], dims),
+            [new RustMapEvent(MapEventKind.CargoEntered, 10f, 20f, dims, Now)]);
+
+        var active = store.GetActiveMarkers(Guild, Server, MarkerKind.CargoShip);
+        Assert.Single(active);
+        Assert.Equal(10f, active[0].X);
+        Assert.Equal(dims, active[0].Dimensions);
+        Assert.Equal(Now, active[0].SeenAtUtc);
+    }
+
+    [Fact]
+    public void Removed_marker_leaves_active_even_when_unalerted()
+    {
+        var store = Build();
+        // A Crate marker produces NO classified event (core-3), but is still tracked in the active set...
+        store.Apply(Delta([new MapMarkerSnapshot(4, MarkerKind.Crate, 0f, 0f, null)], []), []);
+        Assert.Single(store.GetActiveMarkers(Guild, Server, MarkerKind.Crate));
+        // ...and its (un-alerted) removal must still clear it.
+        store.Apply(Delta([], [new MapMarkerSnapshot(4, MarkerKind.Crate, 0f, 0f, null)]), []);
+
+        Assert.Empty(store.GetActiveMarkers(Guild, Server, MarkerKind.Crate));
+    }
+
+    [Fact]
+    public void Recent_events_are_newest_first_and_bounded_to_ten()
+    {
+        var store = Build();
+        for (var i = 0; i < 12; i++)
+        {
+            store.Apply(
+                Delta([new MapMarkerSnapshot((ulong)i, MarkerKind.CargoShip, i, 0f, null)], []),
+                [new RustMapEvent(MapEventKind.CargoEntered, i, 0f, null, Now.AddMinutes(i))]);
+        }
+
+        var recent = store.GetRecentEvents(Guild, Server);
+        Assert.Equal(10, recent.Count);
+        Assert.Equal(Now.AddMinutes(11), recent[0].AtUtc); // newest first
+    }
+
+    [Fact]
+    public void Clear_drops_active_and_recent_for_that_server()
+    {
+        var store = Build();
+        store.Apply(Delta([new MapMarkerSnapshot(1, MarkerKind.CargoShip, 0f, 0f, null)], []),
+            [new RustMapEvent(MapEventKind.CargoEntered, 0f, 0f, null, Now)]);
+
+        store.Clear(Guild, Server);
+
+        Assert.Empty(store.GetActiveMarkers(Guild, Server, MarkerKind.CargoShip));
+        Assert.Empty(store.GetRecentEvents(Guild, Server));
+    }
+}