fix(historian): #693 re-review — AtTime read cap 64 + 16 per time (bursty tags need ~6)

A time inside a gap of a bursty tag costs a 64-row jump read landing in the next
burst plus a bisection back across the gap (~6 reads), so the 64 + 4/time cap
refused a 1 h/day 1 Hz tag asked at noon on 30/100/300 consecutive days
(186/606/1,806 reads) that AVEVA's own AtTime served. The cap is a runaway guard
(HistoryReadDeadline bounds wall clock): now 64 + 16 per distinct time.
Regression tests for x30/x100/x300 (each <= 7 reads a time, values checked).
Docs: DateTime-hinted nodes are stepped but keep the gateway's Double (the
Gateway never historizes DateTime nodes; the SQL backends return DateTime).

docs/Historian.md

@@ -794,8 +794,11 @@ data.
   a 10-minute gap 6 reads (< 10k rows). (Before the review fix a full segment reset the width and a full whole-remainder read was
   discarded, so a dense tag that stopped weeks ago gave up after 65 reads.) More than 1,024 stored samples within one millisecond
   fail the node `BadTooManyOperations` (not counted as a backend failure).
-- **Bounded.** One request takes at most **64 + 4 × distinct times** raw reads; past it the node fails `BadTooManyOperations`
-  ("needed more than N raw reads", naming a small strict-gateway ceiling when one bounded the reads). A strict gateway whose ceiling is
+- **Bounded.** One request takes at most **64 + 16 × distinct times** raw reads; past it the node fails `BadTooManyOperations`
+  ("needed more than N raw reads", naming a small strict-gateway ceiling when one bounded the reads). It is a runaway guard, not a
+  budget (`HistoryReadDeadline` bounds the wall clock): a time inside a gap of a bursty tag legitimately costs a jump read plus a
+  bisection back across the gap, ≈ 6 reads — a 1 h/day 1 Hz tag asked at noon on 30 / 100 / 300 consecutive days takes 186 / 606 /
+  1,806 reads, which the first cut's 64 + 4 per time refused although AVEVA's own AtTime served it. A strict gateway whose ceiling is
   below 4 rows is refused up front with a message naming the ceiling; a small one (e.g. 10) is served by paging within the cap.
 - **Wire shape.** Every request bound is a whole millisecond and a row counts only **strictly inside** its request, so AVEVA's synthetic
   boundary row at the query start (#687) — and any row at the query end — is never taken for a stored sample. A Bad row is value-less
@@ -809,7 +812,10 @@ data.
   **before** the shared evaluator runs, so its own type rules apply exactly as on the SQL backends: a **Boolean** node
   (value ≠ 0) is **stepped** — never 0.5; an **integer** node is interpolated, rounded half away from zero and returned as the
   node's own integer type (`Int32` ⇒ `int`); Float / Double interpolate as Double (as the SQL backends return them). With no
-  hint (an unknown node) every numeric tag interpolates as Double. A **DateTime** node is stepped. Under an integer hint a NaN, ±∞ or
+  hint (an unknown node) every numeric tag interpolates as Double. A **DateTime** node is stepped, but its value stays the
+  gateway's Double: the Gateway never historizes a DateTime node (`HistorianTypeMapper` skips it at provisioning and the recorder drops
+  non-numeric values), so such a node only has history if something else wrote that AVEVA tag, and the numeric encoding is not known
+  here — the SQL backends store DateTime as its own kind and return a `DateTime`. Under an integer hint a NaN, ±∞ or
   out-of-Int64-range stored value is no integer: it is treated as unusable (as `BadNoData`), so a neighbour like that is never
   interpolated or saturated into a Good value.
 - **What differs between backends (by design, not changed by #693).** Only the **Gateway** converts an AtTime result to the node's

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway/GatewayAtTimeReader.cs

@@ -41,7 +41,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway;
 ///         2 ms the segment is the whole stretch from the known row (never a 100 ns step).
 ///     </para>
 ///     <para>
-///         <b>Bounded.</b> One request may take at most <c>64 + 4 × distinct times</c> raw reads (<see cref="BaseReads"/>,
+///         <b>Bounded.</b> One request may take at most <c>64 + 16 × distinct times</c> raw reads (<see cref="BaseReads"/>,
 ///         <see cref="ReadsPerTime"/>); past it — or with a strict-gateway ceiling below <see cref="MinBudget"/> rows — the
 ///         node fails <c>BadTooManyOperations</c> with a message naming the limit. A jump read (to a time far past the previous
 ///         read) asks for only <see cref="JumpRows"/> rows, so a thousand times spread over ten years cost about a thousand
@@ -82,8 +82,12 @@ internal static class GatewayAtTimeReader
     /// <summary>Raw reads one request may always take …</summary>
     internal const int BaseReads = 64;
 
-    /// <summary>… plus this many per distinct requested time.</summary>
-    internal const int ReadsPerTime = 4;
+    /// <summary>
+    ///     … plus this many per distinct requested time. A runaway guard, not a budget (<c>HistoryReadDeadline</c> bounds the
+    ///     wall clock): a time inside a gap of a bursty tag legitimately costs a jump read plus a bisection back across the gap
+    ///     (≈ 6 reads — a 1 h/day tag asked at noon on consecutive days), so 4 refused requests AVEVA's own AtTime served.
+    /// </summary>
+    internal const int ReadsPerTime = 16;
 
     /// <summary>The first walk-back segment's width when the window read showed no density.</summary>
     internal static readonly TimeSpan InitialWalkWidth = TimeSpan.FromMinutes(1);

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway.Tests/GatewayAtTimeTests.cs

@@ -575,6 +575,81 @@ public sealed class GatewayAtTimeTests
         ex.Message.ShouldContain("row ceiling (2");
     }
 
+    /// <summary>A bursty tag: 1 Hz for the first hour of every day (value = seconds since <paramref name="from"/>).</summary>
+    private sealed class BurstStore(DateTime from, int days)
+    {
+        public long RowsStreamed;
+        private const long Burst = 3600 * TimeSpan.TicksPerSecond;
+
+        private DateTime? FirstAtOrAfter(DateTime t)
+        {
+            if (t <= from) return from;
+            var d = (t - from).Ticks / TimeSpan.TicksPerDay;
+            var inDay = (t - from).Ticks % TimeSpan.TicksPerDay;
+            var r = inDay >= Burst
+                ? from.AddDays(d + 1)
+                : from.AddTicks(d * TimeSpan.TicksPerDay + (inDay + TimeSpan.TicksPerSecond - 1) / TimeSpan.TicksPerSecond * TimeSpan.TicksPerSecond);
+            if ((r - from).Ticks % TimeSpan.TicksPerDay >= Burst) r = from.AddDays(d + 1);
+            return r < from.AddDays(days) ? r : null;
+        }
+
+        private DateTime? LastBefore(DateTime t)
+        {
+            if (t <= from) return null;
+            var x = (t - from).Ticks - 1;
+            var d = x / TimeSpan.TicksPerDay;
+            var inDay = x % TimeSpan.TicksPerDay;
+            var r = inDay >= Burst - TimeSpan.TicksPerSecond
+                ? from.AddTicks(d * TimeSpan.TicksPerDay + Burst - TimeSpan.TicksPerSecond)
+                : from.AddTicks(d * TimeSpan.TicksPerDay + inDay / TimeSpan.TicksPerSecond * TimeSpan.TicksPerSecond);
+            var last = from.AddDays(days - 1).AddTicks(Burst - TimeSpan.TicksPerSecond);
+            return r > last ? last : r;
+        }
+
+        private HistorianSample Row(DateTime t, uint quality = 0, DateTime? at = null) => new()
+        {
+            Tag = "T", Timestamp = Timestamp.FromDateTime(at ?? t), NumericValue = (t - from).Ticks / TimeSpan.TicksPerSecond,
+            OpcQuality = 192, Quality = quality,
+        };
+
+        public FakeHistorianGatewayClient Client() => new() { RawSource = Serve };
+
+        private IEnumerable<HistorianSample> Serve(DateTime start, DateTime end, int max)
+        {
+            if (max <= 0 || end < start || end > Now.AddDays(2)
+                || start.Ticks % TimeSpan.TicksPerMillisecond != 0 || end.Ticks % TimeSpan.TicksPerMillisecond != 0)
+                throw new Grpc.Core.RpcException(new Grpc.Core.Status(Grpc.Core.StatusCode.InvalidArgument, "refused"));
+            var rows = new List<HistorianSample>();
+            if (FirstAtOrAfter(start) != start)
+                rows.Add(LastBefore(start) is { } p
+                    ? Row(p, 133, start)
+                    : new HistorianSample { Tag = "T", Timestamp = Timestamp.FromDateTime(start), OpcQuality = 0, Quality = 1 });
+            for (var t = FirstAtOrAfter(start); t is { } u && u <= end && rows.Count < max; t = FirstAtOrAfter(u.AddTicks(1)))
+                rows.Add(Row(u));
+            RowsStreamed += rows.Count;
+            return rows;
+        }
+    }
+
+    [Theory] // re-review: every time in a gap of a bursty tag costs a jump read + a bisection — the cap must allow that
+    [InlineData(30)]
+    [InlineData(100)]
+    [InlineData(300)]
+    public async Task A_bursty_tag_asked_at_noon_on_consecutive_days_is_served(int days)
+    {
+        var from = Now.Date.AddDays(-days - 1);
+        var fake = new BurstStore(from, days + 1).Client();
+        var times = Enumerable.Range(0, days).Select(d => from.AddDays(d).AddHours(12)).ToArray();
+        var s = await AtTime(fake, times);
+        for (var d = 0; d < days; d++)
+        {
+            double prev = d * 86400 + 3599, next = (d + 1) * 86400;
+            ((double)s[d].Value!).ShouldBe(prev + (next - prev) * (12 * 3600 - 3599.0) / (86400 - 3599.0), 1e-6);
+            s[d].StatusCode.ShouldBe(GoodInterpolated);
+        }
+        fake.ReadRawCallCount.ShouldBeLessThanOrEqualTo(7 * days); // ≈ 6 a time; the cap is 64 + 16 a time
+    }
+
     [Fact] // L1: a small ceiling is served (paging), within the read cap
     public async Task A_small_ceiling_is_served_within_the_read_cap()
     {
@@ -596,10 +671,10 @@ public sealed class GatewayAtTimeTests
         fake.RawStreamsCompleted.ShouldBe(3);
     }
 
-    [Fact] // the default cap scales with the request: 64 + 4 per distinct time
+    [Fact] // the default cap scales with the request: 64 + 16 per distinct time (a runaway guard; a bursty tag needs ≈ 6)
     public async Task The_default_read_cap_is_64_plus_4_per_distinct_time()
     {
-        (GatewayAtTimeReader.BaseReads, GatewayAtTimeReader.ReadsPerTime).ShouldBe((64, 4));
+        (GatewayAtTimeReader.BaseReads, GatewayAtTimeReader.ReadsPerTime).ShouldBe((64, 16));
         await Task.CompletedTask;
     }