Merge fix/669-event-continuation: event HistoryRead continuation points + open-ended reads (#669)

2026-10-11 08:37:39 -04:00
parent 91434e7f61 50b504d293
commit d803e0eab4
7 changed files with 719 additions and 20 deletions
@@ -0,0 +1,107 @@
+using Opc.Ua;
+using Opc.Ua.Client;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using CoreHistoryReadResult = ZB.MOM.WW.OtOpcUa.Core.Abstractions.HistoryReadResult;
+using static ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests.ServerEventRig;
+
+namespace ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests;
+
+/// <summary>
+///     Gitea #669 over a real SDK client session: an event HistoryRead capped below the available events pages
+///     through the PRODUCTION session-bound continuation store (<c>SessionHistoryContinuationStore</c>) — the
+///     path the session-less unit tests cannot reach — and the union of pages is every event exactly once.
+/// </summary>
+public sealed class EventHistoryPagingOverTheWireTests
+{
+    private static readonly DateTime Epoch = new(2026, 10, 1, 0, 0, 0, DateTimeKind.Utc);
+
+    [Fact]
+    public async Task A_capped_event_read_pages_through_the_session_store_exactly_once()
+    {
+        var ct = TestContext.Current.CancellationToken;
+        var rig = await StartAsync("EvtPagingWire", encrypted: false, ct);
+        try
+        {
+            // Source installed BEFORE the alarm materialises so the folder is promoted with the HistoryRead bit.
+            var events = Enumerable.Range(0, 25)
+                .Select(i => new HistoricalEvent($"e{i:00}", "src", Epoch.AddSeconds(i / 2), Epoch, "m", 500))
+                .ToList(); // pairs share a timestamp, so page boundaries cut through ties
+            rig.Nm.HistorianDataSource = new SqlLikeEventSource(events);
+            rig.MaterialiseNative();
+            rig.Enforce(false, [Key()]);
+
+            using var session = await rig.ConnectAsync(anonymous: true, ct);
+            var node = new NodeId(RawDeviceFolder, (ushort)session.NamespaceUris.GetIndex(V3NodeIds.RawNamespaceUri));
+
+            var collected = new List<string>();
+            byte[]? cp = null;
+            var pages = 0;
+            do
+            {
+                var (ids, next) = await ReadPageAsync(session, node, cp, ct);
+                collected.AddRange(ids);
+                cp = next;
+                (++pages).ShouldBeLessThan(30, "paging must terminate");
+            }
+            while (cp is not null);
+
+            pages.ShouldBeGreaterThan(2, "25 events at a cap of 10 must page over the wire");
+            collected.ShouldBe(events.Select(e => e.EventId));
+        }
+        finally { await rig.DisposeAsync(); }
+    }
+
+    private static async Task<(List<string> Ids, byte[]? Cp)> ReadPageAsync(
+        ISession session, NodeId node, byte[]? cp, CancellationToken ct)
+    {
+        var filter = new EventFilter();
+        filter.SelectClauses.Add(new SimpleAttributeOperand(ObjectTypeIds.BaseEventType, new QualifiedName("EventId"))
+        {
+            AttributeId = Attributes.Value,
+        });
+        var details = new ReadEventDetails
+        {
+            StartTime = Epoch.AddDays(-1),
+            EndTime = Epoch.AddDays(1),
+            NumValuesPerNode = 10,
+            Filter = filter,
+        };
+        var response = await session.HistoryReadAsync(
+            null, new ExtensionObject(details), TimestampsToReturn.Both, false,
+            new HistoryReadValueIdCollection { new HistoryReadValueId { NodeId = node, ContinuationPoint = cp } }, ct);
+        var result = response.Results.ShouldHaveSingleItem();
+        StatusCode.IsBad(result.StatusCode).ShouldBeFalse($"HistoryRead failed: {result.StatusCode}");
+        var he = (HistoryEvent)ExtensionObject.ToEncodeable(result.HistoryData);
+        var ids = he.Events.Select(e => System.Text.Encoding.UTF8.GetString((byte[])e.EventFields[0].Value)).ToList();
+        return (ids, result.ContinuationPoint is { Length: > 0 } c ? c : null);
+    }
+
+    /// <summary>(time, id) order, [start, end), cap + truncation flag — the SQL backends' contract.</summary>
+    private sealed class SqlLikeEventSource(List<HistoricalEvent> events) : IHistorianDataSource
+    {
+        private readonly List<HistoricalEvent> _all =
+            events.OrderBy(e => e.EventTimeUtc).ThenBy(e => e.EventId, StringComparer.Ordinal).ToList();
+
+        public async Task<HistoricalEventsResult> ReadEventsAsync(
+            string? sourceName, DateTime startUtc, DateTime endUtc, int maxEvents, CancellationToken ct)
+        {
+            await Task.Delay(1, ct).ConfigureAwait(false); // complete on a pool thread, like a real backend
+            var window = _all.Where(e => e.EventTimeUtc >= startUtc && e.EventTimeUtc < endUtc).ToList();
+            var cap = maxEvents <= 0 ? 1000 : maxEvents;
+            return new HistoricalEventsResult(window.Take(cap).ToList(), window.Count > cap ? new byte[] { 1 } : null);
+        }
+
+        public Task<CoreHistoryReadResult> ReadRawAsync(string r, DateTime s, DateTime e, uint m, CancellationToken ct) =>
+            NullHistorianDataSource.Instance.ReadRawAsync(r, s, e, m, ct);
+        public Task<CoreHistoryReadResult> ReadProcessedAsync(
+            string r, DateTime s, DateTime e, TimeSpan i, HistoryAggregateType a, CancellationToken ct) =>
+            NullHistorianDataSource.Instance.ReadProcessedAsync(r, s, e, i, a, ct);
+        public Task<CoreHistoryReadResult> ReadAtTimeAsync(string r, IReadOnlyList<DateTime> t, CancellationToken ct) =>
+            NullHistorianDataSource.Instance.ReadAtTimeAsync(r, t, ct);
+        public HistorianHealthSnapshot GetHealthSnapshot() => NullHistorianDataSource.Instance.GetHealthSnapshot();
+        public void Dispose() { }
+    }
+}
@@ -0,0 +1,382 @@
+using Microsoft.Extensions.Logging.Abstractions;
+using Opc.Ua;
+using Opc.Ua.Server;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using HistorianRead = ZB.MOM.WW.OtOpcUa.Core.Abstractions.HistoryReadResult;
+using SdkHistoryReadResult = Opc.Ua.HistoryReadResult;
+
+namespace ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests;
+
+/// <summary>
+///     Gitea #669 — server-side continuation-point paging for HistoryRead-Events. Same harness as
+///     <see cref="NodeManagerHistoryReadPagingTests"/>: a real SDK server, a session-less in-process
+///     HistoryRead and an <see cref="InMemoryHistoryContinuationStore"/>, over a fake source that behaves like
+///     the SQL backends (ordered by (time, id), half-open window, cap + truncation flag).
+/// </summary>
+public sealed class NodeManagerHistoryReadEventsPagingTests : IDisposable
+{
+    private static CancellationToken Ct => TestContext.Current.CancellationToken;
+    private static readonly DateTime Epoch = new(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+    private readonly string _pkiRoot = Path.Combine(Path.GetTempPath(), $"otopcua-eventpaging-{Guid.NewGuid():N}");
+
+    [Fact]
+    public async Task Events_page_across_continuation_points_exactly_once_in_order()
+    {
+        var (host, nm, node, src) = await SetupAsync(Distinct(250));
+        var ids = DrainAsync(nm, node, max: 100);
+        ids.ShouldBe(src.All.Select(e => e.EventId));
+        src.Calls.ShouldBeGreaterThan(2);
+        await host.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Events_tie_at_page_boundary_is_neither_duplicated_nor_skipped()
+    {
+        // Indices 2,3,4 share a timestamp; cap 4 cuts through the cluster.
+        var events = new List<HistoricalEvent>
+        {
+            Ev("e0", 0), Ev("e1", 1), Ev("e2", 2), Ev("e3", 2), Ev("e4", 2), Ev("e5", 3),
+        };
+        var (host, nm, node, _) = await SetupAsync(events);
+        DrainAsync(nm, node, max: 4).ShouldBe(["e0", "e1", "e2", "e3", "e4", "e5"]);
+        await host.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Events_tie_cluster_larger_than_the_cap_pages_within_the_cluster()
+    {
+        var events = new List<HistoricalEvent> { Ev("a0", 0) };
+        for (var i = 0; i < 7; i++) events.Add(Ev($"t{i}", 5));
+        events.Add(Ev("z0", 9));
+        var (host, nm, node, _) = await SetupAsync(events);
+        DrainAsync(nm, node, max: 3).ShouldBe(
+            ["a0", "t0", "t1", "t2", "t3", "t4", "t5", "t6", "z0"]);
+        await host.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Events_tie_cluster_beyond_the_overfetch_bound_fails_loudly()
+    {
+        var events = new List<HistoricalEvent>();
+        for (var i = 0; i < 10; i++) events.Add(Ev($"t{i:00}", 5));
+        var (host, nm, node, _) = await SetupAsync(events);
+        nm.MaxTieClusterOverfetch = 4;
+
+        var p1 = ReadEvents(nm, node, max: 3, inboundCp: null);
+        p1.Cp.ShouldNotBeNull();
+        var p2 = ReadEvents(nm, node, max: 3, inboundCp: p1.Cp);
+        p2.Error.StatusCode.Code.ShouldBe(StatusCodes.BadHistoryOperationUnsupported);
+        await host.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Events_unknown_continuation_point_is_BadContinuationPointInvalid()
+    {
+        var (host, nm, node, _) = await SetupAsync(Distinct(5));
+        var r = ReadEvents(nm, node, max: 2, inboundCp: Guid.NewGuid().ToByteArray());
+        r.Error.StatusCode.Code.ShouldBe(StatusCodes.BadContinuationPointInvalid);
+        await host.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Events_release_drops_the_cursor()
+    {
+        var (host, nm, node, _) = await SetupAsync(Distinct(10));
+        var p1 = ReadEvents(nm, node, max: 4, inboundCp: null);
+        p1.Cp.ShouldNotBeNull();
+        InvokeRelease(nm, node, p1.Cp!);
+        ReadEvents(nm, node, max: 4, inboundCp: p1.Cp).Error.StatusCode.Code
+            .ShouldBe(StatusCodes.BadContinuationPointInvalid);
+        await host.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Events_cap_sized_complete_page_emits_no_continuation_point()
+    {
+        var (host, nm, node, _) = await SetupAsync(Distinct(4));
+        var r = ReadEvents(nm, node, max: 4, inboundCp: null);
+        r.Ids.Count.ShouldBe(4);
+        r.Cp.ShouldBeNull("the source did not flag truncation, so a cap-sized page is not a paged one");
+        await host.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Events_unbounded_request_never_pages()
+    {
+        var (host, nm, node, _) = await SetupAsync(Distinct(300));
+        var r = ReadEvents(nm, node, max: 0, inboundCp: null);
+        r.Ids.Count.ShouldBe(300);
+        r.Cp.ShouldBeNull();
+        await host.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task A_raw_cursor_presented_to_an_events_read_is_invalid()
+    {
+        var (host, nm, node, _) = await SetupAsync(Distinct(10));
+        var raw = nm.HistoryContinuationStore.Save(null, new HistoryContinuationState("t", Epoch, Epoch.AddDays(1), 0, 4));
+        ReadEvents(nm, node, max: 4, inboundCp: raw).Error.StatusCode.Code
+            .ShouldBe(StatusCodes.BadContinuationPointInvalid);
+        await host.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Events_open_ended_forward_read_pages_without_duplicates()
+    {
+        // EndTime unset (MinValue) + a StartTime = "page forward from StartTime" (Part 11).
+        var (host, nm, node, src) = await SetupAsync(Distinct(25));
+        DrainAsync(nm, node, max: 10, end: DateTime.MinValue).ShouldBe(src.All.Select(e => e.EventId));
+        await host.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Events_cursor_is_bound_to_its_node()
+    {
+        var (host, nm, node, _) = await SetupAsync(Distinct(10));
+        var other = SecondNode(nm);
+        var p1 = ReadEvents(nm, node, max: 4, inboundCp: null);
+        p1.Cp.ShouldNotBeNull();
+        ReadEvents(nm, other, max: 4, inboundCp: p1.Cp).Error.StatusCode.Code
+            .ShouldBe(StatusCodes.BadContinuationPointInvalid);
+        await host.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Raw_cursor_is_bound_to_its_node()
+    {
+        var (host, nm, _, _) = await SetupAsync(Distinct(1));
+        nm.HistorianDataSource = new RawSeriesSource();
+        nm.EnsureVariable("eq-1/a", null, "A", "Double", false, historianTagname: "WW.A", realm: AddressSpaceRealm.Uns);
+        nm.EnsureVariable("eq-1/b", null, "B", "Double", false, historianTagname: "WW.B", realm: AddressSpaceRealm.Uns);
+        var a = nm.TryGetVariable("eq-1/a")!.NodeId;
+        var b = nm.TryGetVariable("eq-1/b")!.NodeId;
+
+        byte[] RawRead(NodeId n, byte[]? cp, out ServiceResult err)
+        {
+            var ctx = new OperationContext(new RequestHeader(), secureChannelContext: null, RequestType.HistoryRead, identity: null);
+            var res = new List<SdkHistoryReadResult> { null! };
+            var errs = new List<ServiceResult> { null! };
+            nm.HistoryRead(ctx, new ReadRawModifiedDetails { StartTime = Epoch, EndTime = Epoch.AddHours(1), NumValuesPerNode = 2, IsReadModified = false },
+                TimestampsToReturn.Both, false,
+                new List<HistoryReadValueId> { new() { NodeId = n, ContinuationPoint = cp } }, res, errs);
+            err = errs[0];
+            return res[0]?.ContinuationPoint!;
+        }
+
+        var cp = RawRead(a, null, out var err0);
+        err0.StatusCode.Code.ShouldBe(StatusCodes.Good, err0.ToString());
+        cp.ShouldNotBeNull();
+        RawRead(b, cp, out var err);
+        err.StatusCode.Code.ShouldBe(StatusCodes.BadContinuationPointInvalid);
+        await host.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Events_tie_cluster_pages_on_a_coarse_resolution_backend()
+    {
+        const long res = 10; // QuestDB-like: inputs truncate to 10 ticks
+        var events = new List<HistoricalEvent>();
+        DateTime At(int slot) => Epoch.AddTicks(slot * res);
+        events.Add(new("a0", "s", At(0), Epoch, "m", 500));
+        for (var i = 0; i < 7; i++) events.Add(new($"t{i}", "s", At(3), Epoch, "m", 500));
+        events.Add(new("z0", "s", At(8), Epoch, "m", 500));
+        var (host, nm, node, _) = await SetupAsync(events, res);
+        DrainAsync(nm, node, max: 3).ShouldBe(["a0", "t0", "t1", "t2", "t3", "t4", "t5", "t6", "z0"]);
+        await host.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Events_batch_one_node_failing_does_not_disturb_another_that_pages()
+    {
+        var (host, nm, node, src) = await SetupAsync(Distinct(10));
+        var other = SecondNode(nm);
+        var good1 = ReadBatch(nm, 4, null, (node, null), (other, null));
+        good1[0].Cp.ShouldNotBeNull();
+        good1[1].Cp.ShouldNotBeNull();
+
+        var mixed = ReadBatch(nm, 4, null, (node, good1[0].Cp), (other, Guid.NewGuid().ToByteArray()));
+        mixed[0].Error.StatusCode.Code.ShouldBe(StatusCodes.Good);
+        mixed[0].Ids.ShouldBe(src.All.Skip(4).Take(3).Select(e => e.EventId));
+        mixed[1].Error.StatusCode.Code.ShouldBe(StatusCodes.BadContinuationPointInvalid);
+        await host.DisposeAsync();
+    }
+
+    private sealed class RawSeriesSource : IHistorianDataSource
+    {
+        public Task<HistorianRead> ReadRawAsync(string r, DateTime s, DateTime e, uint m, CancellationToken ct)
+        {
+            var rows = Enumerable.Range(0, 10).Select(i => new DataValueSnapshot((double)i, StatusCodes.Good,
+                Epoch.AddSeconds(i), Epoch.AddSeconds(i))).Where(v => v.SourceTimestampUtc >= s && v.SourceTimestampUtc <= e)
+                .Take((int)m).ToList();
+            return Task.FromResult(new HistorianRead(rows, null));
+        }
+        public Task<HistorianRead> ReadProcessedAsync(string r, DateTime s, DateTime e, TimeSpan i, HistoryAggregateType a, CancellationToken ct) =>
+            NullHistorianDataSource.Instance.ReadProcessedAsync(r, s, e, i, a, ct);
+        public Task<HistorianRead> ReadAtTimeAsync(string r, IReadOnlyList<DateTime> t, CancellationToken ct) =>
+            NullHistorianDataSource.Instance.ReadAtTimeAsync(r, t, ct);
+        public Task<HistoricalEventsResult> ReadEventsAsync(string? n, DateTime s, DateTime e, int m, CancellationToken ct) =>
+            NullHistorianDataSource.Instance.ReadEventsAsync(n, s, e, m, ct);
+        public HistorianHealthSnapshot GetHealthSnapshot() => NullHistorianDataSource.Instance.GetHealthSnapshot();
+        public void Dispose() { }
+    }
+
+    // --- helpers ---------------------------------------------------------------------------------
+
+    private static HistoricalEvent Ev(string id, int seconds) =>
+        new(id, "src", Epoch.AddSeconds(seconds), Epoch.AddSeconds(seconds), "m", 500);
+
+    private static List<HistoricalEvent> Distinct(int n) =>
+        Enumerable.Range(0, n).Select(i => Ev($"e{i:0000}", i)).ToList();
+
+    private static NodeId SecondNode(OtOpcUaNodeManager nm)
+    {
+        nm.EnsureFolder("eq-evt2", parentNodeId: null, displayName: "Equipment2", realm: AddressSpaceRealm.Uns);
+        nm.MaterialiseAlarmCondition("alarm-2", "eq-evt2", "HighTemp", "OffNormalAlarm", severity: 700, realm: AddressSpaceRealm.Uns);
+        return nm.TryGetFolder("eq-evt2")!.NodeId;
+    }
+
+    private async Task<(OpcUaApplicationHost Host, OtOpcUaNodeManager Nm, NodeId Node, SqlLikeEventSource Src)> SetupAsync(
+        List<HistoricalEvent> events, long resolution = 1)
+    {
+        var applicationUri = $"urn:OtOpcUa.EventPagingTest:{Guid.NewGuid():N}";
+        var started = await OpcUaHostStart.StartAsync(
+            port => new OpcUaApplicationHost(
+                new OpcUaApplicationHostOptions
+                {
+                    ApplicationName = "OtOpcUa.EventPagingTest",
+                    ApplicationUri = applicationUri,
+                    OpcUaPort = port,
+                    PublicHostname = "localhost",
+                    PkiStoreRoot = _pkiRoot,
+                },
+                NullLogger<OpcUaApplicationHost>.Instance),
+            () => new OtOpcUaSdkServer(), Ct);
+        var nm = started.Server.NodeManager!;
+        nm.HistoryContinuationStore = new InMemoryHistoryContinuationStore();
+        var src = new SqlLikeEventSource(events, resolution);
+        nm.HistorianDataSource = src;
+
+        const string equipmentId = "eq-evt";
+        nm.EnsureFolder(equipmentId, parentNodeId: null, displayName: "Equipment", realm: AddressSpaceRealm.Uns);
+        nm.MaterialiseAlarmCondition("alarm-1", equipmentId, "HighTemp", "OffNormalAlarm", severity: 700, realm: AddressSpaceRealm.Uns);
+        return (started.Host, nm, nm.TryGetFolder(equipmentId)!.NodeId, src);
+    }
+
+    private static List<string> DrainAsync(OtOpcUaNodeManager nm, NodeId node, uint max, DateTime? end = null)
+    {
+        var all = new List<string>();
+        byte[]? cp = null;
+        var pages = 0;
+        do
+        {
+            var r = ReadEvents(nm, node, max, cp, end);
+            r.Error.StatusCode.Code.ShouldBe(StatusCodes.Good);
+            all.AddRange(r.Ids);
+            cp = r.Cp;
+            (++pages).ShouldBeLessThan(60, "paging must terminate");
+        }
+        while (cp is not null);
+        return all;
+    }
+
+    private static (List<string> Ids, ServiceResult Error, byte[]? Cp) ReadEvents(
+        OtOpcUaNodeManager nm, NodeId node, uint max, byte[]? inboundCp, DateTime? end = null) =>
+        ReadBatch(nm, max, end, (node, inboundCp))[0];
+
+    private static List<(List<string> Ids, ServiceResult Error, byte[]? Cp)> ReadBatch(
+        OtOpcUaNodeManager nm, uint max, DateTime? end, params (NodeId Node, byte[]? Cp)[] reads)
+    {
+        var context = new OperationContext(
+            new RequestHeader(), secureChannelContext: null, RequestType.HistoryRead, identity: null);
+        var filter = new EventFilter();
+        filter.SelectClauses.Add(new SimpleAttributeOperand(ObjectTypeIds.BaseEventType, new QualifiedName("EventId"))
+        {
+            AttributeId = Attributes.Value,
+        });
+        var details = new ReadEventDetails
+        {
+            StartTime = Epoch.AddDays(-1),
+            EndTime = end ?? Epoch.AddDays(1),
+            NumValuesPerNode = max,
+            Filter = filter,
+        };
+        var nodesToRead = reads.Select(r => new HistoryReadValueId { NodeId = r.Node, ContinuationPoint = r.Cp }).ToList();
+        var results = reads.Select(_ => (SdkHistoryReadResult)null!).ToList();
+        var errors = reads.Select(_ => (ServiceResult)null!).ToList();
+        nm.HistoryRead(context, details, TimestampsToReturn.Both, false, nodesToRead, results, errors);
+
+        var all = new List<(List<string>, ServiceResult, byte[]?)>();
+        for (var i = 0; i < reads.Length; i++)
+        {
+            var ids = new List<string>();
+            if (results[i]?.HistoryData is { } ho && !ExtensionObject.IsNull(ho))
+            {
+                var he = (HistoryEvent)ExtensionObject.ToEncodeable(ho);
+                foreach (var e in he.Events)
+                    ids.Add(System.Text.Encoding.UTF8.GetString((byte[])e.EventFields[0].Value));
+            }
+
+            all.Add((ids, errors[i], results[i]?.ContinuationPoint));
+        }
+
+        return all;
+    }
+
+    private static void InvokeRelease(OtOpcUaNodeManager nm, NodeId node, byte[] cp)
+    {
+        var context = new OperationContext(
+            new RequestHeader(), secureChannelContext: null, RequestType.HistoryRead, identity: null);
+        var nodesToRead = new List<HistoryReadValueId> { new() { NodeId = node, ContinuationPoint = cp } };
+        var results = new List<SdkHistoryReadResult> { null! };
+        var errors = new List<ServiceResult> { null! };
+        nm.HistoryRead(context, new ReadEventDetails { StartTime = Epoch, EndTime = Epoch.AddDays(1), NumValuesPerNode = 4 },
+            TimestampsToReturn.Both, true, nodesToRead, results, errors);
+    }
+
+    /// <summary>Behaves like the SqlServer/QuestDB event reads: (time, id) order, [start, end), cap, truncation flag.</summary>
+    private sealed class SqlLikeEventSource(List<HistoricalEvent> events, long resolution = 1) : IHistorianDataSource
+    {
+        public long TimestampResolutionTicks => resolution;
+        private DateTime Trunc(DateTime d) => d.AddTicks(-(d.Ticks % resolution));
+
+        public IReadOnlyList<HistoricalEvent> All { get; } =
+            events.OrderBy(e => e.EventTimeUtc).ThenBy(e => e.EventId, StringComparer.Ordinal).ToList();
+        public int Calls { get; private set; }
+
+        public Task<HistoricalEventsResult> ReadEventsAsync(
+            string? sourceName, DateTime startUtc, DateTime endUtc, int maxEvents, CancellationToken ct)
+        {
+            Calls++;
+            // Like the SQL backends: a reversed window is swapped, inputs truncate to the storage resolution.
+            if (startUtc > endUtc) (startUtc, endUtc) = (endUtc, startUtc);
+            startUtc = Trunc(startUtc);
+            endUtc = Trunc(endUtc);
+            var window = All.Where(e => e.EventTimeUtc >= startUtc && e.EventTimeUtc < endUtc).ToList();
+            var cap = maxEvents <= 0 ? 1000 : maxEvents;
+            var truncated = window.Count > cap;
+            return Task.FromResult(new HistoricalEventsResult(
+                window.Take(cap).ToList(), truncated ? new byte[] { 1 } : null));
+        }
+
+        public Task<HistorianRead> ReadRawAsync(string r, DateTime s, DateTime e, uint m, CancellationToken ct) =>
+            NullHistorianDataSource.Instance.ReadRawAsync(r, s, e, m, ct);
+        public Task<HistorianRead> ReadProcessedAsync(
+            string r, DateTime s, DateTime e, TimeSpan i, HistoryAggregateType a, CancellationToken ct) =>
+            NullHistorianDataSource.Instance.ReadProcessedAsync(r, s, e, i, a, ct);
+        public Task<HistorianRead> ReadAtTimeAsync(string r, IReadOnlyList<DateTime> t, CancellationToken ct) =>
+            NullHistorianDataSource.Instance.ReadAtTimeAsync(r, t, ct);
+        public HistorianHealthSnapshot GetHealthSnapshot() => NullHistorianDataSource.Instance.GetHealthSnapshot();
+        public void Dispose() { }
+    }
+
+    public void Dispose()
+    {
+        if (Directory.Exists(_pkiRoot))
+        {
+            try { Directory.Delete(_pkiRoot, recursive: true); } catch { /* best effort */ }
+        }
+    }
+}
@@ -73,6 +73,65 @@ public sealed class NodeManagerHistoryReadPagingTests : IDisposable
        await host.DisposeAsync();
    }

+    /// <summary>Part 11: only a StartTime (EndTime unset = MinValue) with a cap pages FORWARD to an open upper bound —
+    /// it must not be mistaken for a reverse read, and the stored cursor must not carry MinValue as its end.</summary>
+    [Fact]
+    public async Task Raw_open_ended_forward_read_pages_ascending_exactly_once()
+    {
+        var (host, server) = await BootAsync();
+        var nm = server.NodeManager!;
+        nm.HistoryContinuationStore = new InMemoryHistoryContinuationStore();
+        nm.HistorianDataSource = new SeriesHistorianDataSource(MakeSeries(count: 250, stepSeconds: 1));
+        nm.EnsureVariable("eq-1/open", parentFolderNodeId: null, displayName: "Open", dataType: "Double",
+            writable: false, historianTagname: "WW.Open", realm: AddressSpaceRealm.Uns);
+        var nodeId = nm.TryGetVariable("eq-1/open")!.NodeId;
+
+        var collected = new List<double>();
+        byte[]? cp = null;
+        var pages = 0;
+        do
+        {
+            var (values, error, next) = ReadRaw(nm, nodeId, Epoch, DateTime.MinValue, max: 100, inboundCp: cp);
+            error.StatusCode.Code.ShouldBe(StatusCodes.Good);
+            collected.AddRange(values);
+            cp = next;
+            (++pages).ShouldBeLessThan(20);
+        }
+        while (cp is not null);
+
+        collected.ShouldBe(Enumerable.Range(0, 250).Select(i => (double)i));
+        await host.DisposeAsync();
+    }
+
+    /// <summary>Part 11: only an EndTime (StartTime unset = MinValue) with a cap reads BACKWARD from the EndTime.</summary>
+    [Fact]
+    public async Task Raw_end_only_read_pages_descending_from_the_end_time()
+    {
+        var (host, server) = await BootAsync();
+        var nm = server.NodeManager!;
+        nm.HistoryContinuationStore = new InMemoryHistoryContinuationStore();
+        nm.HistorianDataSource = new SeriesHistorianDataSource(MakeSeries(count: 250, stepSeconds: 1));
+        nm.EnsureVariable("eq-1/endonly", parentFolderNodeId: null, displayName: "EndOnly", dataType: "Double",
+            writable: false, historianTagname: "WW.EndOnly", realm: AddressSpaceRealm.Uns);
+        var nodeId = nm.TryGetVariable("eq-1/endonly")!.NodeId;
+
+        var collected = new List<double>();
+        byte[]? cp = null;
+        var pages = 0;
+        do
+        {
+            var (values, error, next) = ReadRaw(nm, nodeId, DateTime.MinValue, Epoch.AddHours(1), max: 100, inboundCp: cp);
+            error.StatusCode.Code.ShouldBe(StatusCodes.Good);
+            collected.AddRange(values);
+            cp = next;
+            (++pages).ShouldBeLessThan(20);
+        }
+        while (cp is not null);
+
+        collected.ShouldBe(Enumerable.Range(0, 250).Reverse().Select(i => (double)i));
+        await host.DisposeAsync();
+    }
+
    /// <summary>An exactly-full series whose total is a multiple of the cap pages to a trailing
    /// EMPTY page (GoodNoData, no CP) — the server can't know the prior page was the last until it reads
    /// past the end.</summary>