feat(historian): #691 HistoryRead-Raw ReturnBounds — Part 11 bounding values on every backend

The node manager composes the start/end bounds from each backend's existing raw reads (one authority, HistoryBounds): at-or-before = a capped reverse read (native, or ReverseRawReader's walk-back on a forward-only backend — never AVEVA's synthetic boundary row), at-or-after = a capped forward read. Bounds count toward NumValuesPerNode, the start bound leads the first page, the end bound ends the last (carried in the continuation point). Missing bound = Bad_BoundNotFound (null, at the bound time; one-sided reads ±1 s from the previous value, Table 1 footnotes a/b). A modified read with ReturnBounds is Bad_InvalidArgument (Part 11 6.5.3.3). The .NET SDK's ReadRawModifiedDetails defaults ReturnBounds to TRUE; the existing tests built details without setting it and now set it false. Oracle: every row of Part 11 Table 1 over three backend shapes, plus paging concatenation, ties, Bad bounds, microsecond truncation; conformance pins the lookup primitives on SqlServer + QuestDB.
2026-10-12 16:25:00 -04:00
parent 88141d6ed5
commit 60febbf2dc
14 changed files with 918 additions and 11 deletions
@@ -0,0 +1,100 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Conformance;
+
+/// <summary>
+///     Gitea #691: the server composes Part 11 bounding values (HistoryRead-Raw <c>ReturnBounds</c>) from exactly these raw
+///     reads on a backend that reads newest-first natively (<c>HistoryBounds</c> in the OPC UA server) — so every backend must
+///     answer them precisely: "at or before T" = a reverse read of <c>(0, T]</c> capped at one, "at or after T" = a forward read
+///     of <c>[T, MaxValue)</c> capped at one, "strictly after T" = the same from <c>T + resolution</c>. A bound is a stored
+///     sample of any quality, so a Bad row or an outage marker comes back as the bound.
+/// </summary>
+public abstract class BoundingValueConformance : ConformanceBase
+{
+    private static readonly CancellationToken Ct = CancellationToken.None;
+    private static readonly DateTime Floor = new(0, DateTimeKind.Utc);
+    private static readonly DateTime Ceiling = new(DateTime.MaxValue.Ticks, DateTimeKind.Utc);
+
+    private async Task<DataValueSnapshot?> AtOrBeforeAsync(IHistorianDataSource src, string tag, DateTime t) =>
+        (await src.ReadRawAsync(tag, t, Floor, 1, Ct)).Samples.SingleOrDefault();
+
+    private async Task<DataValueSnapshot?> AtOrAfterAsync(IHistorianDataSource src, string tag, DateTime t) =>
+        (await src.ReadRawAsync(tag, t, Ceiling, 1, Ct)).Samples.SingleOrDefault();
+
+    [Fact]
+    public async Task The_sample_at_or_before_a_time_is_the_latest_one_on_or_before_it()
+    {
+        await ConformanceData.SeedAAsync(B);
+        var src = B.CreateDataSource();
+
+        (await AtOrBeforeAsync(src, "A", At(10)))!.Value.ShouldBe(20d);          // exactly on it
+        (await AtOrBeforeAsync(src, "A", At(15)))!.Value.ShouldBe(20d);          // between samples
+        (await AtOrBeforeAsync(src, "A", At(1000)))!.Value.ShouldBe(50d);        // past the last
+        (await AtOrBeforeAsync(src, "A", At(-1))).ShouldBeNull();                 // before the first: no bound
+        (await AtOrBeforeAsync(src, "A", At(15)))!.SourceTimestampUtc!.Value.Ticks.ShouldBe(B.Round(At(10)).Ticks);
+    }
+
+    [Fact]
+    public async Task The_sample_at_or_after_a_time_is_the_earliest_one_on_or_after_it()
+    {
+        await ConformanceData.SeedAAsync(B);
+        var src = B.CreateDataSource();
+
+        (await AtOrAfterAsync(src, "A", At(10)))!.Value.ShouldBe(20d);           // exactly on it
+        (await AtOrAfterAsync(src, "A", At(15)))!.Value.ShouldBe(30d);          // between samples
+        (await AtOrAfterAsync(src, "A", At(-100)))!.Value.ShouldBe(10d);         // before the first
+        (await AtOrAfterAsync(src, "A", At(41))).ShouldBeNull();                 // past the last: no bound
+    }
+
+    [Fact]
+    public async Task The_sample_strictly_after_a_time_starts_one_storage_resolution_later()
+    {
+        await ConformanceData.SeedAAsync(B);
+        var src = B.CreateDataSource();
+
+        (await AtOrAfterAsync(src, "A", At(10).AddTicks(B.ResolutionTicks)))!.Value.ShouldBe(30d);
+        (await AtOrAfterAsync(src, "A", At(40).AddTicks(B.ResolutionTicks))).ShouldBeNull();
+    }
+
+    [Fact]
+    public async Task A_time_between_storage_ticks_finds_the_sample_the_backend_stores_at_its_truncation()
+    {
+        // The server compares "on the bound" at the storage resolution, so the lookups must agree with the window reads:
+        // a time a fraction of a resolution step after a stored sample is that sample's instant on a coarse backend.
+        await ConformanceData.SeedAAsync(B);
+        var src = B.CreateDataSource();
+        var t = At(10).AddTicks(B.ResolutionTicks - 1); // == At(10) on a 1-tick backend
+
+        (await AtOrBeforeAsync(src, "A", t))!.Value.ShouldBe(20d);
+        var after = await AtOrAfterAsync(src, "A", t);
+        after!.SourceTimestampUtc!.Value.Ticks.ShouldBeGreaterThanOrEqualTo(B.Round(t).Ticks);
+        after.Value.ShouldBe(B.Round(t) == B.Round(At(10)) ? 20d : 30d);
+    }
+
+    [Fact]
+    public async Task A_bad_sample_or_an_outage_marker_is_a_bound_as_stored()
+    {
+        await B.SeedAsync("M",
+            (At(0), HistorianValue.FromDouble(10), Good),
+            (At(5), HistorianValue.Empty, BadNoCommunication),
+            (At(7), HistorianValue.FromDouble(99), Bad));
+        var src = B.CreateDataSource();
+
+        var before = await AtOrBeforeAsync(src, "M", At(6));
+        before!.Value.ShouldBeNull();
+        before.StatusCode.ShouldBe(0x80310000u);
+        var after = await AtOrAfterAsync(src, "M", At(6));
+        after!.Value.ShouldBe(99d);
+        after.StatusCode.ShouldBe(0x80000000u);
+    }
+
+    [Fact]
+    public async Task An_unknown_tag_has_no_bounds()
+    {
+        var src = B.CreateDataSource();
+        (await AtOrBeforeAsync(src, "nope", At(10))).ShouldBeNull();
+        (await AtOrAfterAsync(src, "nope", At(10))).ShouldBeNull();
+    }
+}
@@ -67,3 +67,10 @@ public sealed class QuestDbEventReadConformance(QuestDbFixture fx) : EventReadCo
    /// <inheritdoc/>
    protected override Task<IConformanceBackend> CreateBackendAsync() => QuestDbConformanceBackend.CreateAsync(fx);
 }
+
+[Collection(QuestDbCollection.Name)]
+public sealed class QuestDbBoundingValueConformance(QuestDbFixture fx) : BoundingValueConformance
+{
+    /// <inheritdoc/>
+    protected override Task<IConformanceBackend> CreateBackendAsync() => QuestDbConformanceBackend.CreateAsync(fx);
+}
@@ -67,3 +67,10 @@ public sealed class SqlServerEventReadConformance(SqlHistorianFixture fx) : Even
    /// <inheritdoc/>
    protected override Task<IConformanceBackend> CreateBackendAsync() => SqlServerConformanceBackend.CreateAsync(fx);
 }
+
+[Collection(SqlHistorianCollection.Name)]
+public sealed class SqlServerBoundingValueConformance(SqlHistorianFixture fx) : BoundingValueConformance
+{
+    /// <inheritdoc/>
+    protected override Task<IConformanceBackend> CreateBackendAsync() => SqlServerConformanceBackend.CreateAsync(fx);
+}
@@ -97,6 +97,7 @@ public sealed class HistoryUpdateOverTheWireTests

            var details = new ReadRawModifiedDetails
            {
+                ReturnBounds = false,
                StartTime = T1.AddHours(-1), EndTime = T1.AddHours(1), NumValuesPerNode = 100, IsReadModified = true,
            };
            var response = await session.HistoryReadAsync(
@@ -384,6 +384,7 @@ public sealed class NodeManagerAclEnforcementTests : IDisposable
            context,
            new ReadRawModifiedDetails
            {
+                ReturnBounds = false,
                StartTime = DateTime.UtcNow.AddHours(-1),
                EndTime = DateTime.UtcNow,
                NumValuesPerNode = 10,
@@ -0,0 +1,450 @@
+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>Boots ONE real SDK server for the whole bounds suite (the cases swap the historian source per read).</summary>
+public sealed class BoundsServerFixture : IAsyncLifetime
+{
+    private readonly string _pkiRoot = Path.Combine(Path.GetTempPath(), $"otopcua-bounds-{Guid.NewGuid():N}");
+    private OpcUaApplicationHost? _host;
+
+    /// <summary>The node manager under test.</summary>
+    public OtOpcUaNodeManager Nm { get; private set; } = null!;
+
+    /// <summary>The historized variable every case reads.</summary>
+    public NodeId NodeId { get; private set; } = null!;
+
+    /// <summary>Serialises the cases (they share the node manager's source).</summary>
+    public SemaphoreSlim Gate { get; } = new(1, 1);
+
+    public async ValueTask InitializeAsync()
+    {
+        var started = await OpcUaHostStart.StartAsync(
+            port => new OpcUaApplicationHost(
+                new OpcUaApplicationHostOptions
+                {
+                    ApplicationName = "OtOpcUa.BoundsTest",
+                    ApplicationUri = $"urn:OtOpcUa.BoundsTest:{Guid.NewGuid():N}",
+                    OpcUaPort = port,
+                    PublicHostname = "localhost",
+                    PkiStoreRoot = _pkiRoot,
+                },
+                NullLogger<OpcUaApplicationHost>.Instance),
+            () => new OtOpcUaSdkServer(), CancellationToken.None);
+        _host = started.Host;
+        Nm = started.Server.NodeManager!;
+        Nm.HistoryContinuationStore = new InMemoryHistoryContinuationStore();
+        Nm.EnsureVariable("eq-1/bounds", parentFolderNodeId: null, displayName: "Bounds", dataType: "Double",
+            writable: false, historianTagname: "WW.Bounds", realm: AddressSpaceRealm.Uns);
+        NodeId = Nm.TryGetVariable("eq-1/bounds")!.NodeId;
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        if (_host is not null) await _host.DisposeAsync();
+        if (Directory.Exists(_pkiRoot))
+        {
+            try { Directory.Delete(_pkiRoot, recursive: true); }
+            catch { /* best-effort */ }
+        }
+    }
+}
+
+/// <summary>
+///     Gitea #691: HistoryRead-Raw <c>ReturnBounds</c> (OPC UA Part 11 §4.6 bounding values, §6.5.3.2). The oracle is Part 11
+///     Table 1 itself — every row, over its data set (samples at 5:00, 5:02, 5:03, 5:05, 5:06) — run against three backend
+///     shapes: one that reads newest-first natively (SqlServer-like), one that reads forward only (Gateway-like, walked back
+///     by <see cref="ReverseRawReader"/>) and a microsecond one (QuestDB-like,
+///     truncating its window bounds).
+/// </summary>
+public sealed class NodeManagerHistoryReadBoundsTests(BoundsServerFixture fx) : IClassFixture<BoundsServerFixture>
+{
+    private static readonly DateTime Day = new(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+    private static readonly DateTime Unspecified = DateTime.MinValue;
+
+    private static DateTime T(string hhmm)
+    {
+        var parts = hhmm.Split(':');
+        return Day.AddHours(int.Parse(parts[0])).AddMinutes(int.Parse(parts[1]));
+    }
+
+    /// <summary>Part 11 Table 1's data: value = minutes past 5:00.</summary>
+    private static DataValueSnapshot[] TableData() =>
+        new[] { "5:00", "5:02", "5:03", "5:05", "5:06" }
+            .Select(s => new DataValueSnapshot((double)(T(s) - T("5:00")).TotalMinutes, StatusCodes.Good, T(s), T(s)))
+            .ToArray();
+
+    public enum Shape { Reverse, ForwardOnly, Microsecond }
+
+    private static IHistorianDataSource Source(Shape shape, IReadOnlyList<DataValueSnapshot> series) => shape switch
+    {
+        Shape.Reverse => new SeriesSource(series, reverse: true, inclusiveForwardEnd: false, resolution: 1),
+        Shape.ForwardOnly => new SeriesSource(series, reverse: false, inclusiveForwardEnd: false, resolution: 1),
+        _ => new SeriesSource(series, reverse: true, inclusiveForwardEnd: false, resolution: 10),
+    };
+
+    /// <summary>
+    ///     Part 11 Table 1, every row, verbatim. "FIRST"/"LAST" are <c>Bad_BoundNotFound</c> placeholders (null value) at the
+    ///     StartTime/EndTime; a/b footnotes: one second after/before the previous returned value when that side is unspecified.
+    /// </summary>
+    public static TheoryData<string, string, uint, bool, string> Table1 => new()
+    {
+        { "5:00", "5:05", 0, true, "5:00, 5:02, 5:03, 5:05" },
+        { "5:00", "5:05", 0, false, "5:00, 5:02, 5:03" },
+        { "5:01", "5:04", 0, true, "5:00, 5:02, 5:03, 5:05" },
+        { "5:01", "5:04", 0, false, "5:02, 5:03" },
+        { "5:05", "5:00", 0, true, "5:05, 5:03, 5:02, 5:00" },
+        { "5:05", "5:00", 0, false, "5:05, 5:03, 5:02" },
+        { "5:04", "5:01", 0, true, "5:05, 5:03, 5:02, 5:00" },
+        { "5:04", "5:01", 0, false, "5:03, 5:02" },
+        { "4:59", "5:05", 0, true, "FIRST, 5:00, 5:02, 5:03, 5:05" },
+        { "4:59", "5:05", 0, false, "5:00, 5:02, 5:03" },
+        { "5:01", "5:07", 0, true, "5:00, 5:02, 5:03, 5:05, 5:06, LAST" },
+        { "5:01", "5:07", 0, false, "5:02, 5:03, 5:05, 5:06" },
+        { "5:00", "5:05", 3, true, "5:00, 5:02, 5:03" },
+        { "5:00", "5:05", 3, false, "5:00, 5:02, 5:03" },
+        { "5:01", "5:04", 3, true, "5:00, 5:02, 5:03" },
+        { "5:01", "5:04", 3, false, "5:02, 5:03" },
+        { "5:05", "5:00", 3, true, "5:05, 5:03, 5:02" },
+        { "5:05", "5:00", 3, false, "5:05, 5:03, 5:02" },
+        { "5:04", "5:01", 3, true, "5:05, 5:03, 5:02" },
+        { "5:04", "5:01", 3, false, "5:03, 5:02" },
+        { "4:59", "5:05", 3, true, "FIRST, 5:00, 5:02" },
+        { "4:59", "5:05", 3, false, "5:00, 5:02, 5:03" },
+        { "5:01", "5:07", 3, true, "5:00, 5:02, 5:03" },
+        { "5:01", "5:07", 3, false, "5:02, 5:03, 5:05" },
+        { "5:00", "", 3, true, "5:00, 5:02, 5:03" },
+        { "5:00", "", 3, false, "5:00, 5:02, 5:03" },
+        { "5:00", "", 6, true, "5:00, 5:02, 5:03, 5:05, 5:06, LAST+" },
+        { "5:00", "", 6, false, "5:00, 5:02, 5:03, 5:05, 5:06" },
+        { "5:07", "", 6, true, "5:06, LAST+" },
+        { "5:07", "", 6, false, "" },
+        { "", "5:06", 3, true, "5:06, 5:05, 5:03" },
+        { "", "5:06", 3, false, "5:06, 5:05, 5:03" },
+        { "", "5:06", 6, true, "5:06, 5:05, 5:03, 5:02, 5:00, FIRST-" },
+        { "", "5:06", 6, false, "5:06, 5:05, 5:03, 5:02, 5:00" },
+        { "", "4:48", 6, true, "5:00, FIRST-" },
+        { "", "4:48", 6, false, "" },
+        { "4:48", "4:48", 0, true, "FIRST, 5:00" },
+        { "4:48", "4:48", 0, false, "" },
+        { "4:48", "4:48", 1, true, "FIRST" },
+        { "4:48", "4:48", 1, false, "" },
+        { "4:48", "4:48", 2, true, "FIRST, 5:00" },
+        { "5:00", "5:00", 0, true, "5:00, 5:02" },
+        { "5:00", "5:00", 0, false, "5:00" },
+        { "5:00", "5:00", 1, true, "5:00" },
+        { "5:00", "5:00", 1, false, "5:00" },
+        { "5:01", "5:01", 0, true, "5:00, 5:02" },
+        { "5:01", "5:01", 0, false, "" },
+        { "5:01", "5:01", 1, true, "5:00" },
+        { "5:01", "5:01", 1, false, "" },
+    };
+
+    [Theory]
+    [MemberData(nameof(Table1))]
+    public async Task Part11_table1_first_page_on_a_reverse_capable_backend(string start, string end, uint max, bool bounds, string expected) =>
+        await AssertFirstPage(Shape.Reverse, start, end, max, bounds, expected);
+
+    [Theory]
+    [MemberData(nameof(Table1))]
+    public async Task Part11_table1_first_page_on_a_forward_only_backend(string start, string end, uint max, bool bounds, string expected) =>
+        await AssertFirstPage(Shape.ForwardOnly, start, end, max, bounds, expected);
+
+    [Theory]
+    [MemberData(nameof(Table1))]
+    public async Task Part11_table1_first_page_on_a_microsecond_backend(string start, string end, uint max, bool bounds, string expected) =>
+        await AssertFirstPage(Shape.Microsecond, start, end, max, bounds, expected);
+
+    private async Task AssertFirstPage(Shape shape, string start, string end, uint max, bool bounds, string expected)
+    {
+        var s = start.Length == 0 ? Unspecified : T(start);
+        var e = end.Length == 0 ? Unspecified : T(end);
+        var source = Source(shape, TableData());
+        var (values, error, _) = await ReadAsync(source, s, e, max, bounds, cp: null);
+
+        error.StatusCode.Code.ShouldBe(StatusCodes.Good);
+        Render(values, s, e).ShouldBe(expected);
+        (source as SeriesSource)?.ReverseWindowsOnForwardOnly.ShouldBe(0);
+    }
+
+    /// <summary>
+    ///     Part 11: bounds count toward NumValuesPerNode, the start bound comes with the first page and the end bound with the
+    ///     last — so paging a bounded two-sided read at any page size concatenates to the unpaged (N = 0) answer.
+    /// </summary>
+    [Theory]
+    [InlineData(Shape.Reverse)]
+    [InlineData(Shape.ForwardOnly)]
+    [InlineData(Shape.Microsecond)]
+    public async Task Paging_a_bounded_read_concatenates_to_the_unpaged_answer(Shape shape)
+    {
+        var windows = new[]
+        {
+            ("5:00", "5:05"), ("5:01", "5:04"), ("5:05", "5:00"), ("5:04", "5:01"), ("4:59", "5:05"), ("5:01", "5:07"),
+            ("4:48", "4:48"), ("5:00", "5:00"), ("5:01", "5:01"), ("5:07", "4:00"), ("5:06", "5:06"),
+        };
+        foreach (var (start, end) in windows)
+        {
+            var source = Source(shape, TableData());
+            var all = await ReadAsync(source, T(start), T(end), 0, true, cp: null);
+            all.Cp.ShouldBeNull();
+            var expected = Render(all.Values, T(start), T(end));
+            for (uint n = 1; n <= 6; n++)
+            {
+                var paged = await DrainAsync(source, T(start), T(end), n, bounds: true);
+                Render(paged, T(start), T(end)).ShouldBe(expected, $"{start}->{end} paged by {n}");
+            }
+        }
+    }
+
+    /// <summary>One-sided reads page to the open placeholder exactly once (footnotes a/b), never past it.</summary>
+    [Theory]
+    [InlineData(Shape.Reverse)]
+    [InlineData(Shape.ForwardOnly)]
+    [InlineData(Shape.Microsecond)]
+    public async Task Paging_a_one_sided_bounded_read_ends_with_the_open_placeholder(Shape shape)
+    {
+        for (uint n = 1; n <= 7; n++)
+        {
+            var fwd = await DrainAsync(Source(shape, TableData()), T("5:01"), Unspecified, n, bounds: true);
+            Render(fwd, T("5:01"), Unspecified).ShouldBe("5:00, 5:02, 5:03, 5:05, 5:06, LAST+", $"forward by {n}");
+            var rev = await DrainAsync(Source(shape, TableData()), Unspecified, T("5:04"), n, bounds: true);
+            Render(rev, Unspecified, T("5:04")).ShouldBe("5:05, 5:03, 5:02, 5:00, FIRST-", $"reverse by {n}");
+        }
+    }
+
+    /// <summary>A bound is a stored sample of any quality: a Bad sample before StartTime is the start bound, as stored.</summary>
+    [Theory]
+    [InlineData(Shape.Reverse)]
+    [InlineData(Shape.ForwardOnly)]
+    [InlineData(Shape.Microsecond)]
+    public async Task A_bad_sample_is_returned_as_the_bound_as_stored(Shape shape)
+    {
+        var series = TableData();
+        series[0] = new DataValueSnapshot(null, StatusCodes.BadNoCommunication, T("5:00"), T("5:00"));
+        var (values, _, _) = await ReadAsync(Source(shape, series), T("5:01"), T("5:04"), 0, true, cp: null);
+
+        values[0].StatusCode.Code.ShouldBe(StatusCodes.BadNoCommunication);
+        values[0].SourceTimestamp.ShouldBe(T("5:00"));
+        values.Count.ShouldBe(4);
+    }
+
+    /// <summary>
+    ///     Ties on a bound: the start bound before a forward window is the LAST of a tie cluster (the sample immediately
+    ///     before StartTime in the read's order); the end bound after it is the FIRST of one; and ties ON StartTime are all
+    ///     data (the bound is the first of them, so nothing extra is added).
+    /// </summary>
+    [Theory]
+    [InlineData(Shape.Reverse)]
+    [InlineData(Shape.ForwardOnly)]
+    [InlineData(Shape.Microsecond)]
+    public async Task Tie_clusters_on_either_side_yield_one_bound_each(Shape shape)
+    {
+        var series = new List<DataValueSnapshot>();
+        void Add(string t, double v) => series.Add(new DataValueSnapshot(v, StatusCodes.Good, T(t), T(t)));
+        Add("5:00", 1); Add("5:00", 2); Add("5:00", 3);
+        Add("5:02", 4);
+        Add("5:05", 5); Add("5:05", 6);
+
+        var (fwd, _, _) = await ReadAsync(Source(shape, series), T("5:01"), T("5:04"), 0, true, cp: null);
+        fwd.Select(v => (double)v.Value).ShouldBe([3d, 4d, 5d]);
+
+        var (rev, _, _) = await ReadAsync(Source(shape, series), T("5:04"), T("5:01"), 0, true, cp: null);
+        rev.Select(v => (double)v.Value).ShouldBe([5d, 4d, 3d]);
+
+        var (onStart, _, _) = await ReadAsync(Source(shape, series), T("5:00"), T("5:03"), 0, true, cp: null);
+        onStart.Select(v => (double)v.Value).ShouldBe([1d, 2d, 3d, 4d, 5d]);
+    }
+
+    /// <summary>
+    ///     QuestDB truncates the window bounds it is sent to the microsecond: a sample at ⌊StartTime⌋ is inside a window that
+    ///     starts a few ticks later, so it is data — never returned a second time as the start bound.
+    /// </summary>
+    [Fact]
+    public async Task A_microsecond_backend_does_not_return_a_sample_at_the_truncated_start_twice()
+    {
+        var series = TableData();
+        var (values, _, _) = await ReadAsync(Source(Shape.Microsecond, series), T("5:00").AddTicks(7), T("5:04"), 0, true, cp: null);
+
+        values.Select(v => (double)v.Value).ShouldBe([0d, 2d, 3d, 5d]);
+    }
+
+    /// <summary>
+    ///     A backend whose forward end is inclusive (the gateway's own <c>ReadRaw</c>), or a resumed read that steps onto
+    ///     EndTime, returns the sample AT EndTime as data — it must come back once, as the end bound.
+    /// </summary>
+    [Theory]
+    [InlineData(0u)]
+    [InlineData(1u)]
+    [InlineData(2u)]
+    [InlineData(3u)]
+    public async Task An_inclusive_forward_end_does_not_return_the_end_bound_twice(uint max)
+    {
+        var source = new SeriesSource(TableData(), reverse: false, inclusiveForwardEnd: true, resolution: 1);
+        var values = await DrainAsync(source, T("5:00"), T("5:05"), max, bounds: true);
+        Render(values, T("5:00"), T("5:05")).ShouldBe("5:00, 5:02, 5:03, 5:05");
+    }
+
+    /// <summary>Part 11 §6.5.3.3: a modified read with ReturnBounds is <c>Bad_InvalidArgument</c>.</summary>
+    [Fact]
+    public async Task A_modified_read_with_return_bounds_is_an_invalid_argument()
+    {
+        await fx.Gate.WaitAsync(TestContext.Current.CancellationToken);
+        try
+        {
+            fx.Nm.HistorianDataSource = Source(Shape.Reverse, TableData());
+            var (_, error, cp) = Read(T("5:00"), T("5:05"), 0, bounds: true, cp: null, modified: true);
+            error.StatusCode.Code.ShouldBe(StatusCodes.BadInvalidArgument);
+            cp.ShouldBeNull();
+        }
+        finally { fx.Gate.Release(); }
+    }
+
+    // --- helpers --------------------------------------------------------------------------------
+
+    private static string Render(IReadOnlyList<DataValue> values, DateTime start, DateTime end)
+    {
+        var parts = new List<string>();
+        for (var i = 0; i < values.Count; i++)
+        {
+            var v = values[i];
+            if (v.StatusCode.Code != StatusCodes.BadBoundNotFound)
+            {
+                v.Value.ShouldNotBeNull();
+                parts.Add($"{v.SourceTimestamp.Hour}:{v.SourceTimestamp.Minute:00}");
+                continue;
+            }
+
+            v.Value.ShouldBeNull("a missing bound carries a null value");
+            var isFirst = i == 0 && start != Unspecified && v.SourceTimestamp == start;
+            var isLast = end != Unspecified && v.SourceTimestamp == end;
+            if (isFirst) { parts.Add("FIRST"); continue; }
+            if (isLast) { parts.Add("LAST"); continue; }
+            // Open side (footnotes a/b): one second from the previous returned value.
+            i.ShouldBeGreaterThan(0);
+            var prev = values[i - 1].SourceTimestamp;
+            if (v.SourceTimestamp == prev.AddSeconds(1)) parts.Add("LAST+");
+            else if (v.SourceTimestamp == prev.AddSeconds(-1)) parts.Add("FIRST-");
+            else parts.Add($"?{v.SourceTimestamp:O}");
+        }
+
+        return string.Join(", ", parts);
+    }
+
+    private async Task<List<DataValue>> DrainAsync(IHistorianDataSource source, DateTime start, DateTime end, uint max, bool bounds)
+    {
+        var all = new List<DataValue>();
+        byte[]? cp = null;
+        var pages = 0;
+        do
+        {
+            var (values, error, next) = await ReadAsync(source, start, end, max, bounds, cp);
+            error.StatusCode.Code.ShouldBe(StatusCodes.Good);
+            if (max > 0) values.Count.ShouldBeLessThanOrEqualTo((int)max, "bounds count toward NumValuesPerNode");
+            all.AddRange(values);
+            cp = next;
+            (++pages).ShouldBeLessThan(50, "paging must terminate");
+        }
+        while (cp is not null);
+
+        return all;
+    }
+
+    private async Task<(IReadOnlyList<DataValue> Values, ServiceResult Error, byte[]? Cp)> ReadAsync(
+        IHistorianDataSource source, DateTime start, DateTime end, uint max, bool bounds, byte[]? cp)
+    {
+        await fx.Gate.WaitAsync(TestContext.Current.CancellationToken);
+        try
+        {
+            fx.Nm.HistorianDataSource = source;
+            return Read(start, end, max, bounds, cp, modified: false);
+        }
+        finally { fx.Gate.Release(); }
+    }
+
+    private (IReadOnlyList<DataValue> Values, ServiceResult Error, byte[]? Cp) Read(
+        DateTime start, DateTime end, uint max, bool bounds, byte[]? cp, bool modified)
+    {
+        var context = new OperationContext(new RequestHeader(), secureChannelContext: null, RequestType.HistoryRead, identity: null);
+        var details = new ReadRawModifiedDetails
+        {
+            StartTime = start, EndTime = end, NumValuesPerNode = max, ReturnBounds = bounds, IsReadModified = modified,
+        };
+        var nodesToRead = new List<HistoryReadValueId> { new() { NodeId = fx.NodeId, ContinuationPoint = cp } };
+        var results = new List<SdkHistoryReadResult> { null! };
+        var errors = new List<ServiceResult> { null! };
+        fx.Nm.HistoryRead(context, details, TimestampsToReturn.Both, releaseContinuationPoints: false, nodesToRead, results, errors);
+
+        var values = new List<DataValue>();
+        if (results[0]?.HistoryData is { } ho && !ExtensionObject.IsNull(ho))
+            values.AddRange(((HistoryData)ExtensionObject.ToEncodeable(ho)).DataValues);
+        return (values, errors[0], results[0]?.ContinuationPoint);
+    }
+
+    /// <summary>
+    ///     A series-backed historian. <paramref name="reverse"/>: serves <c>start &gt; end</c> as <c>(end, start]</c>
+    ///     newest-first (SqlServer/QuestDB); otherwise rejects it (the Gateway) and counts that. The forward read is
+    ///     <c>[start, end)</c>, or <c>[start, end]</c> when <paramref name="inclusiveForwardEnd"/> (the gateway's own end);
+    ///     a point read is the instant. <paramref name="resolution"/> &gt; 1 truncates every window bound to it first (QuestDB
+    ///     µs); the series must already be stored at that resolution.
+    /// </summary>
+    private sealed class SeriesSource(IReadOnlyList<DataValueSnapshot> series, bool reverse, bool inclusiveForwardEnd, long resolution)
+        : IHistorianDataSource
+    {
+        public int ReverseWindowsOnForwardOnly;
+
+        public bool SupportsReverseRaw => reverse;
+
+        public long TimestampResolutionTicks => resolution;
+
+        private DateTime Trunc(DateTime t) => new(t.Ticks - t.Ticks % resolution, DateTimeKind.Utc);
+
+        public Task<HistorianRead> ReadRawAsync(
+            string fullReference, DateTime startUtc, DateTime endUtc, uint maxValuesPerNode, CancellationToken cancellationToken)
+        {
+            static DateTime Ts(DataValueSnapshot s) => s.SourceTimestampUtc ?? DateTime.MinValue;
+            startUtc = Trunc(startUtc);
+            endUtc = Trunc(endUtc);
+            List<DataValueSnapshot> window;
+            if (startUtc > endUtc)
+            {
+                if (!reverse)
+                {
+                    Interlocked.Increment(ref ReverseWindowsOnForwardOnly);
+                    throw new InvalidOperationException("start_time must be less than or equal to end_time. (InvalidArgument)");
+                }
+
+                window = series.Where(s => Ts(s) > endUtc && Ts(s) <= startUtc).Reverse().ToList();
+            }
+            else if (startUtc == endUtc) window = series.Where(s => Ts(s) == startUtc).ToList();
+            else window = series.Where(s => Ts(s) >= startUtc && (inclusiveForwardEnd ? Ts(s) <= endUtc : Ts(s) < endUtc)).ToList();
+
+            var page = maxValuesPerNode == 0 ? window : window.Take((int)maxValuesPerNode).ToList();
+            return Task.FromResult(new HistorianRead(page, null));
+        }
+
+        public Task<HistorianRead> ReadProcessedAsync(
+            string fullReference, DateTime startUtc, DateTime endUtc, TimeSpan interval,
+            HistoryAggregateType aggregate, CancellationToken cancellationToken) =>
+            Task.FromResult(new HistorianRead(Array.Empty<DataValueSnapshot>(), null));
+
+        public Task<HistorianRead> ReadAtTimeAsync(
+            string fullReference, IReadOnlyList<DateTime> timestampsUtc, CancellationToken cancellationToken) =>
+            Task.FromResult(new HistorianRead(Array.Empty<DataValueSnapshot>(), null));
+
+        public Task<HistoricalEventsResult> ReadEventsAsync(
+            string? sourceName, DateTime startUtc, DateTime endUtc, int maxEvents, CancellationToken cancellationToken) =>
+            Task.FromResult(new HistoricalEventsResult(Array.Empty<HistoricalEvent>(), null));
+
+        public HistorianHealthSnapshot GetHealthSnapshot() => NullHistorianDataSource.Instance.GetHealthSnapshot();
+
+        public void Dispose() { }
+    }
+}
@@ -45,6 +45,7 @@ public sealed class NodeManagerHistoryReadConcurrencyTests : IDisposable

        var details = new ReadRawModifiedDetails
        {
+            ReturnBounds = false,
            StartTime = DateTime.UtcNow.AddHours(-1),
            EndTime = DateTime.UtcNow,
            NumValuesPerNode = 10,
@@ -78,6 +79,7 @@ public sealed class NodeManagerHistoryReadConcurrencyTests : IDisposable
        var nodeIds = MaterializeHistorizedNodes(nm, count: 12);
        var details = new ReadRawModifiedDetails
        {
+            ReturnBounds = false,
            StartTime = DateTime.UtcNow.AddHours(-1),
            EndTime = DateTime.UtcNow,
            NumValuesPerNode = 10,
@@ -115,6 +117,7 @@ public sealed class NodeManagerHistoryReadConcurrencyTests : IDisposable
        var nodeIds = MaterializeHistorizedNodes(nm, count: 8);
        var details = new ReadRawModifiedDetails
        {
+            ReturnBounds = false,
            StartTime = DateTime.UtcNow.AddHours(-1),
            EndTime = DateTime.UtcNow,
            NumValuesPerNode = 10,
@@ -157,6 +160,7 @@ public sealed class NodeManagerHistoryReadConcurrencyTests : IDisposable
        var nodeIds = MaterializeHistorizedNodes(nm, count: 4);
        var details = new ReadRawModifiedDetails
        {
+            ReturnBounds = false,
            StartTime = DateTime.UtcNow.AddHours(-1),
            EndTime = DateTime.UtcNow,
            NumValuesPerNode = 10,
@@ -190,6 +194,7 @@ public sealed class NodeManagerHistoryReadConcurrencyTests : IDisposable
        var ids = MaterializeHistorizedNodes(nm, count: 2);
        var details = new ReadRawModifiedDetails
        {
+            ReturnBounds = false,
            StartTime = DateTime.UtcNow.AddHours(-1),
            EndTime = DateTime.UtcNow,
            NumValuesPerNode = 10,
@@ -160,7 +160,7 @@ public sealed class NodeManagerHistoryReadEventsPagingTests : IDisposable
            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 },
+            nm.HistoryRead(ctx, new ReadRawModifiedDetails { ReturnBounds = false, 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];
@@ -271,7 +271,7 @@ public sealed class NodeManagerHistoryReadModifiedTests : IDisposable
        var results = new List<SdkHistoryReadResult> { null! };
        var errors = new List<ServiceResult> { null! };
        nm.HistoryRead(context,
-            new ReadRawModifiedDetails { StartTime = start, EndTime = end, NumValuesPerNode = max, IsReadModified = modified },
+            new ReadRawModifiedDetails { ReturnBounds = false, StartTime = start, EndTime = end, NumValuesPerNode = max, IsReadModified = modified },
            TimestampsToReturn.Both, false,
            new List<HistoryReadValueId> { new() { NodeId = node, ContinuationPoint = cp } }, results, errors);

@@ -967,6 +967,7 @@ public sealed class NodeManagerHistoryReadPagingTests : IDisposable

        var details = new ReadRawModifiedDetails
        {
+            ReturnBounds = false,
            StartTime = start,
            EndTime = end,
            NumValuesPerNode = max,
@@ -1000,6 +1001,7 @@ public sealed class NodeManagerHistoryReadPagingTests : IDisposable
            new RequestHeader(), secureChannelContext: null, RequestType.HistoryRead, identity: null);
        var details = new ReadRawModifiedDetails
        {
+            ReturnBounds = false,
            StartTime = Epoch, EndTime = Epoch.AddHours(1), NumValuesPerNode = 100, IsReadModified = false,
        };
        var nodesToRead = new List<HistoryReadValueId> { new() { NodeId = nodeId, ContinuationPoint = cp } };
@@ -52,6 +52,7 @@ public sealed class NodeManagerHistoryReadTests : IDisposable
        var end = DateTime.UtcNow;
        var details = new ReadRawModifiedDetails
        {
+            ReturnBounds = false,
            StartTime = start,
            EndTime = end,
            NumValuesPerNode = 100,
@@ -97,6 +98,7 @@ public sealed class NodeManagerHistoryReadTests : IDisposable

        var details = new ReadRawModifiedDetails
        {
+            ReturnBounds = false,
            StartTime = DateTime.UtcNow.AddHours(-1),
            EndTime = DateTime.UtcNow,
            NumValuesPerNode = 10,
@@ -129,6 +131,7 @@ public sealed class NodeManagerHistoryReadTests : IDisposable

        var details = new ReadRawModifiedDetails
        {
+            ReturnBounds = false,
            StartTime = DateTime.UtcNow.AddHours(-1),
            EndTime = DateTime.UtcNow,
            NumValuesPerNode = 10,
@@ -162,6 +165,7 @@ public sealed class NodeManagerHistoryReadTests : IDisposable

        var details = new ReadRawModifiedDetails
        {
+            ReturnBounds = false,
            StartTime = DateTime.UtcNow.AddHours(-1),
            EndTime = DateTime.UtcNow,
            NumValuesPerNode = 10,
@@ -195,6 +199,7 @@ public sealed class NodeManagerHistoryReadTests : IDisposable

        var details = new ReadRawModifiedDetails
        {
+            ReturnBounds = false,
            StartTime = DateTime.UtcNow.AddHours(-1),
            EndTime = DateTime.UtcNow,
            NumValuesPerNode = 10,
@@ -613,6 +618,7 @@ public sealed class NodeManagerHistoryReadTests : IDisposable

        var details = new ReadRawModifiedDetails
        {
+            ReturnBounds = false,
            StartTime = DateTime.UtcNow.AddHours(-1),
            EndTime   = DateTime.UtcNow,
            NumValuesPerNode = 10,
@@ -658,6 +664,7 @@ public sealed class NodeManagerHistoryReadTests : IDisposable

        var details = new ReadRawModifiedDetails
        {
+            ReturnBounds = false,
            StartTime = DateTime.UtcNow.AddHours(-1),
            EndTime = DateTime.UtcNow,
            NumValuesPerNode = 10,