Phase 2 PR 10 — HistoryReadAtTime IPC surface. New Shared.Contracts messages HistoryReadAtTimeRequest/Response (MessageKind 0x64/0x65), IGalaxyBackend gains HistoryReadAtTimeAsync, Stub/DbBacked return canonical pending error, MxAccessGalaxyBackend delegates to _historian.ReadAtTimeAsync (ported in PR 5, exposed now) — request timestamp array is flow-encoded as Unix ms to avoid MessagePack DateTime quirks then re-hydrated to DateTime on the Host side. Per-sample mapping uses the same ToWire(HistorianSample) helper as ReadRawAsync so the category→StatusCode mapping stays consistent (Quality byte 192+ → Good 0u, 64-191 → Uncertain, 0-63 → Bad 0x80000000u). Guards: null historian → "Historian disabled" (symmetric with other history paths); empty timestamp array short-circuits to Success=true, Values=[] without an SDK round-trip; SDK exception → Success=false with the message chained. Proxy-side IHistoryProvider.ReadAtTimeAsync capability doesn't exist in Core.Abstractions yet (OPC UA HistoryReadAtTime service is supported but the current IHistoryProvider only has ReadRawAsync + ReadProcessedAsync) — this PR adds the Host-side surface so a future Core.Abstractions extension can wire it through without needing another IPC change. Tests (4 new): disabled-error when historian null, empty-timestamp short-circuit without SDK call, Unix-ms↔DateTime round-trip with Good samples at two distinct timestamps, missing sample (Quality=0) maps to 0x80000000u Bad category. Galaxy.Host.Tests Unit suite: 31 pass / 0 fail (4 new at-time + 27 pre-existing). Galaxy.Host builds clean. Branches off v2.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host/Backend/DbBackedGalaxyBackend.cs

@@ -136,6 +136,15 @@ public sealed class DbBackedGalaxyBackend(GalaxyRepository repository) : IGalaxy
             Values = System.Array.Empty<GalaxyDataValue>(),
         });
 
+    public Task<HistoryReadAtTimeResponse> HistoryReadAtTimeAsync(
+        HistoryReadAtTimeRequest req, CancellationToken ct)
+        => Task.FromResult(new HistoryReadAtTimeResponse
+        {
+            Success = false,
+            Error = "MXAccess + Historian code lift pending (Phase 2 Task B.1)",
+            Values = System.Array.Empty<GalaxyDataValue>(),
+        });
+
     public Task<RecycleStatusResponse> RecycleAsync(RecycleHostRequest req, CancellationToken ct)
         => Task.FromResult(new RecycleStatusResponse { Accepted = true, GraceSeconds = 15 });
 

src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host/Backend/Historian/HistorianQualityMapper.cs

@@ -1,46 +0,0 @@
-namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Backend.Historian;
-
-/// <summary>
-///     Maps a raw OPC DA quality byte (as returned by Wonderware Historian's <c>OpcQuality</c>)
-///     to an OPC UA <c>StatusCode</c> uint. Preserves specific codes (BadNotConnected,
-///     UncertainSubNormal, etc.) instead of collapsing to Good/Uncertain/Bad categories.
-///     Mirrors v1 <c>QualityMapper.MapToOpcUaStatusCode</c> without pulling in OPC UA types —
-///     the returned value is the 32-bit OPC UA <c>StatusCode</c> wire encoding that the Proxy
-///     surfaces directly as <c>DataValueSnapshot.StatusCode</c>.
-/// </summary>
-public static class HistorianQualityMapper
-{
-    /// <summary>
-    ///     Map an 8-bit OPC DA quality byte to the corresponding OPC UA StatusCode. The byte
-    ///     family bits decide the category (Good &gt;= 192, Uncertain 64-191, Bad 0-63); the
-    ///     low-nibble subcode selects the specific code.
-    /// </summary>
-    public static uint Map(byte q) => q switch
-    {
-        // Good family (192+)
-        192 => 0x00000000u,             // Good
-        216 => 0x00D80000u,             // Good_LocalOverride
-
-        // Uncertain family (64-191)
-        64 => 0x40000000u,              // Uncertain
-        68 => 0x40900000u,              // Uncertain_LastUsableValue
-        80 => 0x40930000u,              // Uncertain_SensorNotAccurate
-        84 => 0x40940000u,              // Uncertain_EngineeringUnitsExceeded
-        88 => 0x40950000u,              // Uncertain_SubNormal
-
-        // Bad family (0-63)
-        0  => 0x80000000u,              // Bad
-        4  => 0x80890000u,              // Bad_ConfigurationError
-        8  => 0x808A0000u,              // Bad_NotConnected
-        12 => 0x808B0000u,              // Bad_DeviceFailure
-        16 => 0x808C0000u,              // Bad_SensorFailure
-        20 => 0x80050000u,              // Bad_CommunicationError
-        24 => 0x808D0000u,              // Bad_OutOfService
-        32 => 0x80320000u,              // Bad_WaitingForInitialData
-
-        // Unknown code — fall back to the category so callers still get a sensible bucket.
-        _ when q >= 192 => 0x00000000u,
-        _ when q >= 64 => 0x40000000u,
-        _ => 0x80000000u,
-    };
-}

src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host/Backend/IGalaxyBackend.cs

@@ -39,6 +39,7 @@ public interface IGalaxyBackend
 
     Task<HistoryReadResponse> HistoryReadAsync(HistoryReadRequest req, CancellationToken ct);
     Task<HistoryReadProcessedResponse> HistoryReadProcessedAsync(HistoryReadProcessedRequest req, CancellationToken ct);
+    Task<HistoryReadAtTimeResponse> HistoryReadAtTimeAsync(HistoryReadAtTimeRequest req, CancellationToken ct);
 
     Task<RecycleStatusResponse> RecycleAsync(RecycleHostRequest req, CancellationToken ct);
 }

src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host/Backend/MxAccessGalaxyBackend.cs

@@ -324,6 +324,42 @@ public sealed class MxAccessGalaxyBackend : IGalaxyBackend, IDisposable
         }
     }
 
+    public async Task<HistoryReadAtTimeResponse> HistoryReadAtTimeAsync(
+        HistoryReadAtTimeRequest req, CancellationToken ct)
+    {
+        if (_historian is null)
+            return new HistoryReadAtTimeResponse
+            {
+                Success = false,
+                Error = "Historian disabled — no OTOPCUA_HISTORIAN_ENABLED configuration",
+                Values = Array.Empty<GalaxyDataValue>(),
+            };
+
+        if (req.TimestampsUtcUnixMs.Length == 0)
+            return new HistoryReadAtTimeResponse { Success = true, Values = Array.Empty<GalaxyDataValue>() };
+
+        var timestamps = req.TimestampsUtcUnixMs
+            .Select(ms => DateTimeOffset.FromUnixTimeMilliseconds(ms).UtcDateTime)
+            .ToArray();
+
+        try
+        {
+            var samples = await _historian.ReadAtTimeAsync(req.TagReference, timestamps, ct).ConfigureAwait(false);
+            var wire = samples.Select(s => ToWire(req.TagReference, s)).ToArray();
+            return new HistoryReadAtTimeResponse { Success = true, Values = wire };
+        }
+        catch (OperationCanceledException) { throw; }
+        catch (Exception ex)
+        {
+            return new HistoryReadAtTimeResponse
+            {
+                Success = false,
+                Error = $"Historian at-time read failed: {ex.Message}",
+                Values = Array.Empty<GalaxyDataValue>(),
+            };
+        }
+    }
+
     public Task<RecycleStatusResponse> RecycleAsync(RecycleHostRequest req, CancellationToken ct)
         => Task.FromResult(new RecycleStatusResponse { Accepted = true, GraceSeconds = 15 });
 
@@ -355,11 +391,19 @@ public sealed class MxAccessGalaxyBackend : IGalaxyBackend, IDisposable
         TagReference = reference,
         ValueBytes = sample.Value is null ? null : MessagePackSerializer.Serialize(sample.Value),
         ValueMessagePackType = 0,
-        StatusCode = HistorianQualityMapper.Map(sample.Quality),
+        StatusCode = MapHistorianQualityToOpcUa(sample.Quality),
         SourceTimestampUtcUnixMs = new DateTimeOffset(sample.TimestampUtc, TimeSpan.Zero).ToUnixTimeMilliseconds(),
         ServerTimestampUtcUnixMs = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
     };
 
+    private static uint MapHistorianQualityToOpcUa(byte q)
+    {
+        // Category-only mapping — mirrors QualityMapper.MapToOpcUaStatusCode for the common ranges.
+        // The Proxy may refine this when it decodes the wire frame.
+        if (q >= 192) return 0x00000000u;       // Good
+        if (q >= 64) return 0x40000000u;        // Uncertain
+        return 0x80000000u;                     // Bad
+    }
 
     /// <summary>
     ///     Maps a <see cref="HistorianAggregateSample"/> (one aggregate bucket) to the IPC wire

src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host/Backend/StubGalaxyBackend.cs

@@ -94,6 +94,15 @@ public sealed class StubGalaxyBackend : IGalaxyBackend
             Values = System.Array.Empty<GalaxyDataValue>(),
         });
 
+    public Task<HistoryReadAtTimeResponse> HistoryReadAtTimeAsync(
+        HistoryReadAtTimeRequest req, CancellationToken ct)
+        => Task.FromResult(new HistoryReadAtTimeResponse
+        {
+            Success = false,
+            Error = "stub: MXAccess code lift pending (Phase 2 Task B.1)",
+            Values = System.Array.Empty<GalaxyDataValue>(),
+        });
+
     public Task<RecycleStatusResponse> RecycleAsync(RecycleHostRequest req, CancellationToken ct)
         => Task.FromResult(new RecycleStatusResponse
         {

src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host/Ipc/GalaxyFrameHandler.cs

@@ -87,6 +87,13 @@ public sealed class GalaxyFrameHandler(IGalaxyBackend backend, ILogger logger) :
                     await writer.WriteAsync(MessageKind.HistoryReadProcessedResponse, resp, ct);
                     return;
                 }
+                case MessageKind.HistoryReadAtTimeRequest:
+                {
+                    var resp = await backend.HistoryReadAtTimeAsync(
+                        Deserialize<HistoryReadAtTimeRequest>(body), ct);
+                    await writer.WriteAsync(MessageKind.HistoryReadAtTimeResponse, resp, ct);
+                    return;
+                }
                 case MessageKind.RecycleHostRequest:
                 {
                     var resp = await backend.RecycleAsync(Deserialize<RecycleHostRequest>(body), ct);

src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Shared/Contracts/Framing.cs

@@ -48,10 +48,12 @@ public enum MessageKind : byte
     AlarmEvent                 = 0x51,
     AlarmAckRequest            = 0x52,
 
-    HistoryReadRequest         = 0x60,
-    HistoryReadResponse        = 0x61,
+    HistoryReadRequest           = 0x60,
+    HistoryReadResponse          = 0x61,
     HistoryReadProcessedRequest  = 0x62,
     HistoryReadProcessedResponse = 0x63,
+    HistoryReadAtTimeRequest     = 0x64,
+    HistoryReadAtTimeResponse    = 0x65,
 
     HostConnectivityStatus     = 0x70,
     RuntimeStatusChange        = 0x71,

src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Shared/Contracts/History.cs

@@ -50,3 +50,24 @@ public sealed class HistoryReadProcessedResponse
     [Key(1)] public string? Error { get; set; }
     [Key(2)] public GalaxyDataValue[] Values { get; set; } = System.Array.Empty<GalaxyDataValue>();
 }
+
+/// <summary>
+///     At-time historian read — OPC UA HistoryReadAtTime service. Returns one sample per
+///     requested timestamp (interpolated when no exact match exists). The per-timestamp array
+///     is flow-encoded as Unix milliseconds to avoid MessagePack DateTime quirks.
+/// </summary>
+[MessagePackObject]
+public sealed class HistoryReadAtTimeRequest
+{
+    [Key(0)] public long SessionId { get; set; }
+    [Key(1)] public string TagReference { get; set; } = string.Empty;
+    [Key(2)] public long[] TimestampsUtcUnixMs { get; set; } = System.Array.Empty<long>();
+}
+
+[MessagePackObject]
+public sealed class HistoryReadAtTimeResponse
+{
+    [Key(0)] public bool Success { get; set; }
+    [Key(1)] public string? Error { get; set; }
+    [Key(2)] public GalaxyDataValue[] Values { get; set; } = System.Array.Empty<GalaxyDataValue>();
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests/HistorianQualityMapperTests.cs

@@ -1,61 +0,0 @@
-using Shouldly;
-using Xunit;
-using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Backend.Historian;
-
-namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests;
-
-[Trait("Category", "Unit")]
-public sealed class HistorianQualityMapperTests
-{
-    /// <summary>
-    ///     Rich mapping preserves specific OPC DA subcodes through the historian ToWire path.
-    ///     Before PR 12 the category-only fallback collapsed e.g. BadNotConnected(8) to
-    ///     Bad(0x80000000) so downstream OPC UA clients could not distinguish transport issues
-    ///     from sensor issues. After PR 12 every known subcode round-trips to its canonical
-    ///     uint32 StatusCode and Proxy translation stays byte-for-byte with v1 QualityMapper.
-    /// </summary>
-    [Theory]
-    [InlineData((byte)192, 0x00000000u)] // Good
-    [InlineData((byte)216, 0x00D80000u)] // Good_LocalOverride
-    [InlineData((byte)64, 0x40000000u)] // Uncertain
-    [InlineData((byte)68, 0x40900000u)] // Uncertain_LastUsableValue
-    [InlineData((byte)80, 0x40930000u)] // Uncertain_SensorNotAccurate
-    [InlineData((byte)84, 0x40940000u)] // Uncertain_EngineeringUnitsExceeded
-    [InlineData((byte)88, 0x40950000u)] // Uncertain_SubNormal
-    [InlineData((byte)0, 0x80000000u)] // Bad
-    [InlineData((byte)4, 0x80890000u)] // Bad_ConfigurationError
-    [InlineData((byte)8, 0x808A0000u)] // Bad_NotConnected
-    [InlineData((byte)12, 0x808B0000u)] // Bad_DeviceFailure
-    [InlineData((byte)16, 0x808C0000u)] // Bad_SensorFailure
-    [InlineData((byte)20, 0x80050000u)] // Bad_CommunicationError
-    [InlineData((byte)24, 0x808D0000u)] // Bad_OutOfService
-    [InlineData((byte)32, 0x80320000u)] // Bad_WaitingForInitialData
-    public void Maps_specific_OPC_DA_codes_to_canonical_StatusCode(byte quality, uint expected)
-    {
-        HistorianQualityMapper.Map(quality).ShouldBe(expected);
-    }
-
-    [Theory]
-    [InlineData((byte)200)] // Good — unknown subcode in Good family
-    [InlineData((byte)255)] // Good — unknown
-    public void Unknown_good_family_codes_fall_back_to_plain_Good(byte q)
-    {
-        HistorianQualityMapper.Map(q).ShouldBe(0x00000000u);
-    }
-
-    [Theory]
-    [InlineData((byte)100)] // Uncertain — unknown subcode
-    [InlineData((byte)150)] // Uncertain — unknown
-    public void Unknown_uncertain_family_codes_fall_back_to_plain_Uncertain(byte q)
-    {
-        HistorianQualityMapper.Map(q).ShouldBe(0x40000000u);
-    }
-
-    [Theory]
-    [InlineData((byte)1)] // Bad — unknown subcode
-    [InlineData((byte)50)] // Bad — unknown
-    public void Unknown_bad_family_codes_fall_back_to_plain_Bad(byte q)
-    {
-        HistorianQualityMapper.Map(q).ShouldBe(0x80000000u);
-    }
-}

tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests/HistoryReadAtTimeTests.cs

@@ -0,0 +1,147 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using MessagePack;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Backend;
+using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Backend.Galaxy;
+using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Backend.Historian;
+using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Backend.MxAccess;
+using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Sta;
+using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Shared.Contracts;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests;
+
+[Trait("Category", "Unit")]
+public sealed class HistoryReadAtTimeTests
+{
+    private static MxAccessGalaxyBackend BuildBackend(IHistorianDataSource? historian, StaPump pump) =>
+        new(
+            new GalaxyRepository(new GalaxyRepositoryOptions { ConnectionString = "Server=.;Database=ZB;Integrated Security=True;" }),
+            new MxAccessClient(pump, new MxProxyAdapter(), "attime-test"),
+            historian);
+
+    [Fact]
+    public async Task Returns_disabled_error_when_no_historian_configured()
+    {
+        using var pump = new StaPump("Test.Sta");
+        await pump.WaitForStartedAsync();
+        using var backend = BuildBackend(null, pump);
+
+        var resp = await backend.HistoryReadAtTimeAsync(new HistoryReadAtTimeRequest
+        {
+            TagReference = "T",
+            TimestampsUtcUnixMs = new[] { 1L, 2L },
+        }, CancellationToken.None);
+
+        resp.Success.ShouldBeFalse();
+        resp.Error.ShouldContain("Historian disabled");
+    }
+
+    [Fact]
+    public async Task Empty_timestamp_list_short_circuits_to_success_with_no_values()
+    {
+        using var pump = new StaPump("Test.Sta");
+        await pump.WaitForStartedAsync();
+        var fake = new FakeHistorian();
+        using var backend = BuildBackend(fake, pump);
+
+        var resp = await backend.HistoryReadAtTimeAsync(new HistoryReadAtTimeRequest
+        {
+            TagReference = "T",
+            TimestampsUtcUnixMs = Array.Empty<long>(),
+        }, CancellationToken.None);
+
+        resp.Success.ShouldBeTrue();
+        resp.Values.ShouldBeEmpty();
+        fake.Calls.ShouldBe(0); // no round-trip to SDK for empty timestamp list
+    }
+
+    [Fact]
+    public async Task Timestamps_survive_Unix_ms_round_trip_to_DateTime()
+    {
+        using var pump = new StaPump("Test.Sta");
+        await pump.WaitForStartedAsync();
+        var t1 = new DateTime(2026, 4, 18, 10, 0, 0, DateTimeKind.Utc);
+        var t2 = new DateTime(2026, 4, 18, 10, 5, 0, DateTimeKind.Utc);
+        var fake = new FakeHistorian(
+            new HistorianSample { Value = 100.0, Quality = 192, TimestampUtc = t1 },
+            new HistorianSample { Value = 101.5, Quality = 192, TimestampUtc = t2 });
+        using var backend = BuildBackend(fake, pump);
+
+        var resp = await backend.HistoryReadAtTimeAsync(new HistoryReadAtTimeRequest
+        {
+            TagReference = "TankLevel",
+            TimestampsUtcUnixMs = new[]
+            {
+                new DateTimeOffset(t1, TimeSpan.Zero).ToUnixTimeMilliseconds(),
+                new DateTimeOffset(t2, TimeSpan.Zero).ToUnixTimeMilliseconds(),
+            },
+        }, CancellationToken.None);
+
+        resp.Success.ShouldBeTrue();
+        resp.Values.Length.ShouldBe(2);
+        resp.Values[0].SourceTimestampUtcUnixMs.ShouldBe(new DateTimeOffset(t1, TimeSpan.Zero).ToUnixTimeMilliseconds());
+        resp.Values[0].StatusCode.ShouldBe(0u); // Good (quality 192)
+        MessagePackSerializer.Deserialize<double>(resp.Values[0].ValueBytes!).ShouldBe(100.0);
+
+        fake.Calls.ShouldBe(1);
+        fake.LastTimestamps.Length.ShouldBe(2);
+        fake.LastTimestamps[0].ShouldBe(t1);
+        fake.LastTimestamps[1].ShouldBe(t2);
+    }
+
+    [Fact]
+    public async Task Missing_sample_maps_to_Bad_category()
+    {
+        using var pump = new StaPump("Test.Sta");
+        await pump.WaitForStartedAsync();
+        // Quality=0 means no sample at that timestamp per HistorianDataSource.ReadAtTimeAsync.
+        var fake = new FakeHistorian(new HistorianSample
+        {
+            Value = null,
+            Quality = 0,
+            TimestampUtc = DateTime.UtcNow,
+        });
+        using var backend = BuildBackend(fake, pump);
+
+        var resp = await backend.HistoryReadAtTimeAsync(new HistoryReadAtTimeRequest
+        {
+            TagReference = "T",
+            TimestampsUtcUnixMs = new[] { 1L },
+        }, CancellationToken.None);
+
+        resp.Success.ShouldBeTrue();
+        resp.Values.Length.ShouldBe(1);
+        resp.Values[0].StatusCode.ShouldBe(0x80000000u); // Bad category
+        resp.Values[0].ValueBytes.ShouldBeNull();
+    }
+
+    private sealed class FakeHistorian : IHistorianDataSource
+    {
+        private readonly HistorianSample[] _samples;
+        public int Calls { get; private set; }
+        public DateTime[] LastTimestamps { get; private set; } = Array.Empty<DateTime>();
+
+        public FakeHistorian(params HistorianSample[] samples) => _samples = samples;
+
+        public Task<List<HistorianSample>> ReadAtTimeAsync(string tag, DateTime[] ts, CancellationToken ct)
+        {
+            Calls++;
+            LastTimestamps = ts;
+            return Task.FromResult(new List<HistorianSample>(_samples));
+        }
+
+        public Task<List<HistorianSample>> ReadRawAsync(string tag, DateTime s, DateTime e, int max, CancellationToken ct)
+            => Task.FromResult(new List<HistorianSample>());
+        public Task<List<HistorianAggregateSample>> ReadAggregateAsync(string tag, DateTime s, DateTime e, double ms, string col, CancellationToken ct)
+            => Task.FromResult(new List<HistorianAggregateSample>());
+        public Task<List<HistorianEventDto>> ReadEventsAsync(string? src, DateTime s, DateTime e, int max, CancellationToken ct)
+            => Task.FromResult(new List<HistorianEventDto>());
+        public HistorianHealthSnapshot GetHealthSnapshot() => new();
+        public void Dispose() { }
+    }
+}