Merge master into feat/677-aggregates

# Conflicts:
#	docs/Historian.md

tests/Drivers/Historian.Conformance/EventReadConformance.cs

@@ -0,0 +1,106 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Conformance;
+
+/// <summary>
+///     The direction-aware event read (Gitea #675): forward is <c>[lo, hi)</c> ascending by <c>(EventTimeUtc, EventId)</c>;
+///     reverse is the Part 11 reverse window <c>(lo, hi]</c> DESCENDING by the same key, so a capped reverse read returns the
+///     LATEST events and flags truncation. Paging a reverse read the way the server does — resume at the last returned
+///     time inclusive and drop the boundary ties already emitted — must visit every event exactly once, newest-first,
+///     through a same-timestamp tie cluster.
+/// </summary>
+public abstract class EventReadConformance : ConformanceBase
+{
+    private static readonly CancellationToken Ct = CancellationToken.None;
+
+    /// <summary>e0@0, e1@1, then the ties t0..t4@2, then e5@3 and e6@4 (all source "s"), plus o0@2 from another source.</summary>
+    private async Task<IHistorianDataSource> SeedAsync()
+    {
+        await B.SeedEventsAsync(
+            (At(0), "e0", "s"), (At(1), "e1", "s"),
+            (At(2), "t0", "s"), (At(2), "t1", "s"), (At(2), "t2", "s"), (At(2), "t3", "s"), (At(2), "t4", "s"),
+            (At(3), "e5", "s"), (At(4), "e6", "s"),
+            (At(2), "o0", "other"));
+        return B.CreateDataSource();
+    }
+
+    private static readonly string[] NewestFirst = ["e6", "e5", "t4", "t3", "t2", "t1", "t0", "e1", "e0"];
+
+    [Fact]
+    public async Task Reverse_read_is_newest_first_by_time_then_EventId_descending()
+    {
+        using var src = await SeedAsync();
+        var r = await src.ReadEventsAsync("s", At(-1), At(10), 0, reverse: true, Ct);
+        r.Events.Select(e => e.EventId).ShouldBe(NewestFirst);
+        r.ContinuationPoint.ShouldBeNull();
+    }
+
+    [Fact]
+    public async Task Reverse_window_is_end_exclusive_start_inclusive_whichever_order_the_bounds_come_in()
+    {
+        using var src = await SeedAsync();
+        // (At(1), At(3)]: e1 at the lower bound is excluded, e5 at the upper bound included.
+        (await src.ReadEventsAsync("s", At(3), At(1), 0, reverse: true, Ct)).Events.Select(e => e.EventId)
+            .ShouldBe(["e5", "t4", "t3", "t2", "t1", "t0"]);
+        (await src.ReadEventsAsync("s", At(1), At(3), 0, reverse: true, Ct)).Events.Select(e => e.EventId)
+            .ShouldBe(["e5", "t4", "t3", "t2", "t1", "t0"]);
+        // Forward is unchanged: [At(1), At(3)) ascending.
+        (await src.ReadEventsAsync("s", At(1), At(3), 0, reverse: false, Ct)).Events.Select(e => e.EventId)
+            .ShouldBe(["e1", "t0", "t1", "t2", "t3", "t4"]);
+    }
+
+    [Fact]
+    public async Task A_capped_reverse_read_keeps_the_LATEST_events_and_flags_truncation()
+    {
+        using var src = await SeedAsync();
+        var r = await src.ReadEventsAsync("s", At(10), At(-1), 3, reverse: true, Ct);
+        r.Events.Select(e => e.EventId).ShouldBe(["e6", "e5", "t4"]);
+        r.ContinuationPoint.ShouldNotBeNull();
+        // An exact fit is complete.
+        (await src.ReadEventsAsync("s", At(10), At(-1), 9, reverse: true, Ct)).ContinuationPoint.ShouldBeNull();
+    }
+
+    [Fact]
+    public async Task Paging_a_reverse_read_through_a_tie_cluster_visits_every_event_once_newest_first()
+    {
+        using var src = await SeedAsync();
+        foreach (var cap in new[] { 1, 2, 3, 4 })
+        {
+            var all = new List<string>();
+            var lo = At(-1);
+            var from = At(10);
+            var skip = 0;
+            for (var page = 0; ; page++)
+            {
+                page.ShouldBeLessThan(40, "paging must terminate");
+                var r = await src.ReadEventsAsync("s", from, lo, cap + skip, reverse: true, Ct);
+                var events = r.Events.ToList();
+                var drop = 0;
+                while (drop < skip && drop < events.Count && events[drop].EventTimeUtc == from) drop++;
+                events = events.Skip(drop).ToList();
+                // The server asks for cap + skip rows (it re-reads the boundary ties it then drops), so a page is never
+                // emptied by the trim while more remains.
+                if (r.ContinuationPoint is not null) events.Count.ShouldBe(cap);
+
+                all.AddRange(events.Select(e => e.EventId));
+                if (r.ContinuationPoint is null) break;
+                var boundary = events[^1].EventTimeUtc;
+                var ties = events.AsEnumerable().Reverse().TakeWhile(e => e.EventTimeUtc == boundary).Count();
+                skip = boundary == from ? skip + ties : ties;
+                from = boundary;
+            }
+
+            all.SequenceEqual(NewestFirst).ShouldBeTrue($"cap {cap}: {string.Join(",", all)}");
+        }
+    }
+
+    [Fact]
+    public async Task Reverse_read_with_a_null_source_spans_every_source()
+    {
+        using var src = await SeedAsync();
+        var r = await src.ReadEventsAsync(null, At(2.5), At(1.5), 0, reverse: true, Ct);
+        r.Events.Select(e => e.EventId).ShouldBe(["t4", "t3", "t2", "t1", "t0", "o0"]);
+    }
+}

tests/Drivers/Historian.Conformance/IConformanceBackend.cs

@@ -41,6 +41,13 @@ public interface IConformanceBackend : IAsyncDisposable
     /// <param name="samples">The rows to store.</param>
     Task SeedAsync(string tag, params (DateTime T, HistorianValue V, uint Status)[] samples);
 
+    /// <summary>
+    ///     Writes historical events directly in the backend's event table (never through the alarm writer): event id,
+    ///     source and time as given (rounded to the storage resolution), severity 500, received time = event time.
+    /// </summary>
+    /// <param name="events">The events to store.</param>
+    Task SeedEventsAsync(params (DateTime T, string Id, string Source)[] events);
+
     /// <summary>
     ///     Live (non-deleted) rows for a tag, ascending by time, read directly from storage. The status is returned
     ///     VERBATIM as stored — there is no read-side clamp (an Empty row stored non-Bad reads back non-Bad here).