fix(historian): #675 review follow-ups — SupportsReverseEvents capability, no catch-as-unsupported

- IHistorianDataSource.SupportsReverseEvents (default false; SqlServer/QuestDB true; Gateway/Null declare false).
  The node manager checks it BEFORE calling the source: an end-only capped events read becomes reverse only on
  a supporting backend (Gateway, the default, keeps the pre-#675 forward [MinValue, EndTime) paging), and an
  explicit reverse read on a non-supporting backend is BadHistoryOperationUnsupported without a call.
- Removed the broad catch (NotSupportedException) in the events path: a NotSupportedException from inside a
  backend is now logged as a backend fault (Error), not an 'unsupported' Warning.
- Null declares the reverse overload itself; guard test: every production IHistorianDataSource declares both
  the reverse overload and the capability (positive-control scan of all four backends).
- Conformance: capability reported + oversized reverse tie cluster (forward over-fetch reversed == reverse
  read order; capped reverse read stopping inside the cluster flags truncation) on SqlServer + QuestDB.
- docs/Historian.md: end-only capped events read is backward on SqlServer/QuestDB, forward on Gateway.

src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/Historian/IHistorianDataSource.cs

@@ -101,6 +101,16 @@ public interface IHistorianDataSource : IDisposable
         int maxEvents,
         CancellationToken cancellationToken);
 
+    /// <summary>
+    ///     Whether this backend can serve a reverse (newest-first) events read — the reverse overload of
+    ///     <see cref="ReadEventsAsync(string?, DateTime, DateTime, int, bool, CancellationToken)"/> (Gitea #675). The server
+    ///     checks it BEFORE calling the source: an explicit reverse read (<c>StartTime &gt; EndTime</c>) on a backend that
+    ///     cannot is answered <c>BadHistoryOperationUnsupported</c> without a call, and an end-only capped read, which Part 11
+    ///     reads backward, keeps its forward <c>[MinValue, EndTime)</c> meaning there. Default <c>false</c>; an
+    ///     implementation (or a wrapper) declares it itself — a guard test pins that.
+    /// </summary>
+    bool SupportsReverseEvents => false;
+
     /// <summary>
     ///     Read historical alarm / event records in a chosen direction — the overload the server's HistoryReadEvents
     ///     paging calls (Gitea #675).
@@ -118,8 +128,9 @@ public interface IHistorianDataSource : IDisposable
     ///     <para>
     ///         The default forwards a forward read to the five-argument overload and throws
     ///         <see cref="NotSupportedException"/> for a reverse one — a backend that cannot read newest-first (Gateway,
-    ///         Null) — which the server reports as <c>BadHistoryOperationUnsupported</c> rather than returning the
-    ///         earliest events in ascending order as if they were the answer.
+    ///         Null). The server never relies on that throw: it consults <see cref="SupportsReverseEvents"/> first and
+    ///         answers <c>BadHistoryOperationUnsupported</c> without calling, rather than returning the earliest events in
+    ///         ascending order as if they were the answer. A backend that serves reverse must override BOTH members.
     ///     </para>
     /// </remarks>
     /// <param name="sourceName">The source name to filter events, or null to return events from all sources.</param>

src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/Historian/NullHistorianDataSource.cs

@@ -55,6 +55,25 @@ public sealed class NullHistorianDataSource : IHistorianDataSource
         int maxEvents,
         CancellationToken cancellationToken) => Task.FromResult(EmptyEvents);
 
+    /// <inheritdoc />
+    /// <remarks><c>false</c> (Gitea #675): there is no history to read in either direction, and an explicit reverse read
+    /// is answered <c>BadHistoryOperationUnsupported</c> like any backend that cannot read newest-first.</remarks>
+    public bool SupportsReverseEvents => false;
+
+    /// <inheritdoc />
+    /// <remarks>Forward ⇒ the empty result; reverse ⇒ <see cref="NotSupportedException"/>, the interface contract for a
+    /// backend without <see cref="SupportsReverseEvents"/>.</remarks>
+    public Task<HistoricalEventsResult> ReadEventsAsync(
+        string? sourceName,
+        DateTime startUtc,
+        DateTime endUtc,
+        int maxEvents,
+        bool reverse,
+        CancellationToken cancellationToken) =>
+        reverse
+            ? throw new NotSupportedException("The null historian cannot read events newest-first (reverse).")
+            : Task.FromResult(EmptyEvents);
+
     /// <inheritdoc />
     public HistorianHealthSnapshot GetHealthSnapshot() => new(
         TotalQueries: 0,

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

@@ -125,6 +125,13 @@ public sealed class GatewayHistorianDataSource : IHistorianDataSource, IAsyncDis
         }
     }
 
+    /// <inheritdoc />
+    /// <remarks>
+    ///     <c>false</c>: the gateway's <c>ReadEvents</c> streams ascending only (Gitea #675). The server therefore refuses an
+    ///     explicit reverse events read without calling, and keeps an end-only capped read forward.
+    /// </remarks>
+    public bool SupportsReverseEvents => false;
+
     /// <inheritdoc />
     /// <remarks>
     ///     A reverse (newest-first) read is refused with <see cref="NotSupportedException"/> — the server reports

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.QuestDb/QuestDbHistorianDataSource.cs

@@ -354,6 +354,11 @@ public sealed class QuestDbHistorianDataSource : IHistorianDataSource
 
     // ------------------------------------------------------------------------------------------ Events
 
+    /// <inheritdoc />
+    /// <remarks>Reverse events reads are served natively (<c>ORDER BY … DESC</c>, Gitea #675).</remarks>
+    public bool SupportsReverseEvents => true;
+
+
     /// <inheritdoc />
     /// <remarks>
     ///     <c>[start, end)</c> by event time (a reversed window is swapped), ordered by <c>(ts, event_id)</c> ascending.

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianDataSource.cs

@@ -311,6 +311,11 @@ public sealed class SqlServerHistorianDataSource : IHistorianDataSource
 
     // ------------------------------------------------------------------------------------------ Events
 
+    /// <inheritdoc />
+    /// <remarks>Reverse events reads are served natively (<c>ORDER BY … DESC</c>, Gitea #675).</remarks>
+    public bool SupportsReverseEvents => true;
+
+
     /// <inheritdoc />
     /// <remarks>
     ///     <c>[start, end)</c> by <c>EventTimeUtc</c> (a reversed window is swapped), ordered by

src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs

@@ -5189,6 +5189,8 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
     {
         var inboundCp = nodesToRead[handle.Index].ContinuationPoint;
         var resumed = inboundCp is { Length: > 0 };
+        // One snapshot of the (hot-swappable) source for the whole read: the capability check and every call must agree.
+        var source = _historianDataSource;
         try
         {
             var startUtc = details.StartTime;
@@ -5224,17 +5226,30 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
                 // Part 11: with one bound unset, an unset EndTime (MinValue) with a StartTime means "page FORWARD from
                 // StartTime" — normalise it to an open upper bound, or the cursor would store MinValue and the read would
                 // look reversed. An unset StartTime with an EndTime and a count cap means "page BACKWARD from EndTime"
-                // (#675, mirroring raw): the reverse window (MinValue, EndTime]. Without a count cap an end-only read
-                // keeps its historical forward [MinValue, EndTime) meaning.
+                // (#675, mirroring raw): the reverse window (MinValue, EndTime] — but only on a backend that can read
+                // newest-first. Elsewhere (Gateway, the default backend) and without a count cap an end-only read keeps its
+                // historical forward [MinValue, EndTime) meaning rather than becoming a refused reverse read.
                 if (endUtc == DateTime.MinValue && startUtc != DateTime.MinValue)
                     endUtc = new DateTime(DateTime.MaxValue.Ticks, DateTimeKind.Utc); // Utc kind: a proto Timestamp conversion rejects Unspecified
-                else if (numValuesPerNode > 0 && startUtc == DateTime.MinValue && endUtc != DateTime.MinValue)
+                else if (numValuesPerNode > 0 && startUtc == DateTime.MinValue && endUtc != DateTime.MinValue
+                         && source.SupportsReverseEvents)
                     (startUtc, endUtc) = (endUtc, new DateTime(0, DateTimeKind.Utc));
 
                 // Part 11: StartTime later than EndTime is a reverse read — events newest-first over (end, start].
                 reverse = startUtc > endUtc;
             }
 
+            // An explicit reverse read (or a reverse cursor resumed after the source was swapped) on a backend that cannot
+            // read newest-first: refuse it BEFORE calling the source — never the earliest events in ascending order as if
+            // they were the answer. Checked here rather than by catching an exception, so a NotSupportedException thrown
+            // from inside a backend (a driver library, the projection) stays a backend fault.
+            if (reverse && !source.SupportsReverseEvents)
+            {
+                errors[handle.Index] = StatusCodes.BadHistoryOperationUnsupported;
+                results[handle.Index] = new SdkHistoryReadResult { StatusCode = StatusCodes.BadHistoryOperationUnsupported };
+                return;
+            }
+
             // NOT under the node-manager Lock — awaiting the async source is safe here.
             // NumValuesPerNode==0 means "no limit — return ALL values" per OPC UA Part 4/11, so it is translated
             // to UNBOUNDED (EventMaxEvents) rather than the backend's <=0 default-cap sentinel. A resumed page re-reads its
@@ -5243,7 +5258,7 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
             var fetch = EventMaxEvents(numValuesPerNode);
             if (numValuesPerNode > 0 && boundarySkip > 0)
                 fetch = (int)Math.Min(int.MaxValue - 1L, (long)fetch + boundarySkip);
-            var sourceResult = await _historianDataSource.ReadEventsAsync(
+            var sourceResult = await source.ReadEventsAsync(
                 sourceName, startUtc, endUtc, fetch, reverse, ct).ConfigureAwait(false);
 
             // Truncation is the SOURCE's word (non-null continuation point) — never inferred from the count, so a
@@ -5278,9 +5293,9 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
                 // Oversized tie cluster: more events share startUtc than the page cap, so (time, skip) alone
                 // cannot advance. Over-fetch the whole cluster over the half-open [T, T+resolution) window
                 // with an explicit bounded cap and page WITHIN it (same scheme as raw).
-                var resolution = Math.Max(1L, _historianDataSource.TimestampResolutionTicks);
+                var resolution = Math.Max(1L, source.TimestampResolutionTicks);
                 var overfetchCap = (int)Math.Min(int.MaxValue - 1L, (long)Math.Max(1, MaxTieClusterOverfetch) + 1);
-                IReadOnlyList<HistoricalEvent> cluster = (await _historianDataSource.ReadEventsAsync(
+                IReadOnlyList<HistoricalEvent> cluster = (await source.ReadEventsAsync(
                     sourceName, startUtc, startUtc.AddTicks(resolution), overfetchCap, reverse: false, ct)
                     .ConfigureAwait(false)).Events;
 
@@ -5345,15 +5360,6 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
             errors[handle.Index] = StatusCodes.BadTimeout;
             results[handle.Index] = new SdkHistoryReadResult { StatusCode = StatusCodes.BadTimeout };
         }
-        catch (NotSupportedException ex)
-        {
-            // The backend cannot serve this read's shape — today a reverse (newest-first) read on Gateway / Null
-            // (#675). A client request the backend refuses, not a backend fault: Warning, not Error.
-            _logger.LogWarning("OtOpcUaNodeManager: HistoryReadEvents for node {NodeId} is not supported by the historian backend: {Reason}",
-                handle.NodeId, ex.Message);
-            errors[handle.Index] = StatusCodes.BadHistoryOperationUnsupported;
-            results[handle.Index] = new SdkHistoryReadResult { StatusCode = StatusCodes.BadHistoryOperationUnsupported };
-        }
         catch (Exception ex)
         {
             // One node's backend failure must not throw out of the batch — surface Bad for THIS node