PR 3.2 — Lift Wonderware Historian SDK code to sidecar

Move all historian implementation files from Driver.Galaxy.Host/Backend/Historian/
to Driver.Historian.Wonderware/Backend/. Sidecar now owns the aahClientManaged /
aahClientCommon SDK references; Galaxy.Host project-references the sidecar so
MxAccessGalaxyBackend keeps building until PR 7.2 retires Galaxy.Host entirely.

10 source files moved (preserving git history via git mv):
  IHistorianDataSource, HistorianDataSource, HistorianClusterEndpointPicker,
  HistorianClusterNodeState, HistorianConfiguration, HistorianEventDto,
  HistorianHealthSnapshot, HistorianQualityMapper, HistorianSample,
  IHistorianConnectionFactory.

2 historian tests moved alongside (HistorianClusterEndpointPickerTests,
HistorianQualityMapperTests). Sidecar test project now hosts 29 tests (1 PR 3.1
smoke + 28 moved historian tests, all passing).

Galaxy.Host's remaining 6 historian-flavored tests (HistorianWiringTests,
HistoryReadAtTimeTests, HistoryReadEventsTests, HistoryReadProcessedTests)
keep passing via the project reference — using directives updated to reach
the new namespace.

Sidecar deliberately speaks no Core.Abstractions — its surface is the legacy
List<HistorianSample> shape; PR 3.4's .NET 10 client translates to the
Core.Abstractions shapes added in PR 1.1.

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

src/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Backend/HistorianClusterEndpointPicker.cs

@@ -0,0 +1,129 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend
+{
+    /// <summary>
+    ///     Thread-safe, pure-logic endpoint picker for the Wonderware Historian cluster. Tracks which
+    ///     configured nodes are healthy, places failed nodes in a time-bounded cooldown, and hands
+    ///     out an ordered list of eligible candidates for the data source to try in sequence.
+    /// </summary>
+    internal sealed class HistorianClusterEndpointPicker
+    {
+        private readonly Func<DateTime> _clock;
+        private readonly TimeSpan _cooldown;
+        private readonly object _lock = new object();
+        private readonly List<NodeEntry> _nodes;
+
+        public HistorianClusterEndpointPicker(HistorianConfiguration config)
+            : this(config, () => DateTime.UtcNow) { }
+
+        internal HistorianClusterEndpointPicker(HistorianConfiguration config, Func<DateTime> clock)
+        {
+            _clock = clock ?? throw new ArgumentNullException(nameof(clock));
+            _cooldown = TimeSpan.FromSeconds(Math.Max(0, config.FailureCooldownSeconds));
+
+            var names = (config.ServerNames != null && config.ServerNames.Count > 0)
+                ? config.ServerNames
+                : new List<string> { config.ServerName };
+
+            _nodes = names
+                .Where(n => !string.IsNullOrWhiteSpace(n))
+                .Select(n => n.Trim())
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .Select(n => new NodeEntry { Name = n })
+                .ToList();
+        }
+
+        public int NodeCount
+        {
+            get { lock (_lock) return _nodes.Count; }
+        }
+
+        public IReadOnlyList<string> GetHealthyNodes()
+        {
+            lock (_lock)
+            {
+                var now = _clock();
+                return _nodes.Where(n => IsHealthyAt(n, now)).Select(n => n.Name).ToList();
+            }
+        }
+
+        public int HealthyNodeCount
+        {
+            get
+            {
+                lock (_lock)
+                {
+                    var now = _clock();
+                    return _nodes.Count(n => IsHealthyAt(n, now));
+                }
+            }
+        }
+
+        public void MarkFailed(string node, string? error)
+        {
+            lock (_lock)
+            {
+                var entry = FindEntry(node);
+                if (entry == null) return;
+
+                var now = _clock();
+                entry.FailureCount++;
+                entry.LastError = error;
+                entry.LastFailureTime = now;
+                entry.CooldownUntil = _cooldown.TotalMilliseconds > 0 ? now + _cooldown : (DateTime?)null;
+            }
+        }
+
+        public void MarkHealthy(string node)
+        {
+            lock (_lock)
+            {
+                var entry = FindEntry(node);
+                if (entry == null) return;
+                entry.CooldownUntil = null;
+            }
+        }
+
+        public List<HistorianClusterNodeState> SnapshotNodeStates()
+        {
+            lock (_lock)
+            {
+                var now = _clock();
+                return _nodes.Select(n => new HistorianClusterNodeState
+                {
+                    Name = n.Name,
+                    IsHealthy = IsHealthyAt(n, now),
+                    CooldownUntil = IsHealthyAt(n, now) ? null : n.CooldownUntil,
+                    FailureCount = n.FailureCount,
+                    LastError = n.LastError,
+                    LastFailureTime = n.LastFailureTime
+                }).ToList();
+            }
+        }
+
+        private static bool IsHealthyAt(NodeEntry entry, DateTime now)
+        {
+            return entry.CooldownUntil == null || entry.CooldownUntil <= now;
+        }
+
+        private NodeEntry? FindEntry(string node)
+        {
+            for (var i = 0; i < _nodes.Count; i++)
+                if (string.Equals(_nodes[i].Name, node, StringComparison.OrdinalIgnoreCase))
+                    return _nodes[i];
+            return null;
+        }
+
+        private sealed class NodeEntry
+        {
+            public string Name { get; set; } = "";
+            public DateTime? CooldownUntil { get; set; }
+            public int FailureCount { get; set; }
+            public string? LastError { get; set; }
+            public DateTime? LastFailureTime { get; set; }
+        }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Backend/HistorianClusterNodeState.cs

@@ -0,0 +1,18 @@
+using System;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend
+{
+    /// <summary>
+    ///     Point-in-time state of a single historian cluster node. One entry per configured node
+    ///     appears inside <see cref="HistorianHealthSnapshot"/>.
+    /// </summary>
+    public sealed class HistorianClusterNodeState
+    {
+        public string Name { get; set; } = "";
+        public bool IsHealthy { get; set; }
+        public DateTime? CooldownUntil { get; set; }
+        public int FailureCount { get; set; }
+        public string? LastError { get; set; }
+        public DateTime? LastFailureTime { get; set; }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Backend/HistorianConfiguration.cs

@@ -0,0 +1,38 @@
+using System.Collections.Generic;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend
+{
+    /// <summary>
+    ///     Wonderware Historian SDK configuration. Populated from environment variables at Host
+    ///     startup (see <c>Program.cs</c>) or from the Proxy's <c>DriverInstance.DriverConfig</c>
+    ///     section passed during OpenSession. Kept OPC-UA-free — the Proxy side owns UA translation.
+    /// </summary>
+    public sealed class HistorianConfiguration
+    {
+        public bool Enabled { get; set; } = false;
+
+        /// <summary>Single-node fallback when <see cref="ServerNames"/> is empty.</summary>
+        public string ServerName { get; set; } = "localhost";
+
+        /// <summary>
+        ///     Ordered cluster nodes. When non-empty, the data source tries each in order on connect,
+        ///     falling through to the next on failure. A failed node is placed in cooldown for
+        ///     <see cref="FailureCooldownSeconds"/> before being re-eligible.
+        /// </summary>
+        public List<string> ServerNames { get; set; } = new();
+
+        public int FailureCooldownSeconds { get; set; } = 60;
+        public bool IntegratedSecurity { get; set; } = true;
+        public string? UserName { get; set; }
+        public string? Password { get; set; }
+        public int Port { get; set; } = 32568;
+        public int CommandTimeoutSeconds { get; set; } = 30;
+        public int MaxValuesPerRead { get; set; } = 10000;
+
+        /// <summary>
+        ///     Outer safety timeout applied to sync-over-async Historian operations. Must be
+        ///     comfortably larger than <see cref="CommandTimeoutSeconds"/>.
+        /// </summary>
+        public int RequestTimeoutSeconds { get; set; } = 60;
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Backend/HistorianDataSource.cs

@@ -0,0 +1,621 @@
+using System;
+using System.Collections.Generic;
+using StringCollection = System.Collections.Specialized.StringCollection;
+using System.Threading;
+using System.Threading.Tasks;
+using ArchestrA;
+using Serilog;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend
+{
+    /// <summary>
+    ///     Reads historical data from the Wonderware Historian via the aahClientManaged SDK.
+    ///     OPC-UA-free — emits <see cref="HistorianSample"/>/<see cref="HistorianAggregateSample"/>
+    ///     which the Proxy maps to OPC UA <c>DataValue</c> on its side of the IPC.
+    /// </summary>
+    public sealed class HistorianDataSource : IHistorianDataSource
+    {
+        private static readonly ILogger Log = Serilog.Log.ForContext<HistorianDataSource>();
+
+        private readonly HistorianConfiguration _config;
+        private readonly object _connectionLock = new object();
+        private readonly object _eventConnectionLock = new object();
+        private readonly IHistorianConnectionFactory _factory;
+        private HistorianAccess? _connection;
+        private HistorianAccess? _eventConnection;
+        private bool _disposed;
+
+        private readonly object _healthLock = new object();
+        private long _totalSuccesses;
+        private long _totalFailures;
+        private int _consecutiveFailures;
+        private DateTime? _lastSuccessTime;
+        private DateTime? _lastFailureTime;
+        private string? _lastError;
+        private string? _activeProcessNode;
+        private string? _activeEventNode;
+
+        private readonly HistorianClusterEndpointPicker _picker;
+
+        public HistorianDataSource(HistorianConfiguration config)
+            : this(config, new SdkHistorianConnectionFactory(), null) { }
+
+        internal HistorianDataSource(
+            HistorianConfiguration config,
+            IHistorianConnectionFactory factory,
+            HistorianClusterEndpointPicker? picker = null)
+        {
+            _config = config;
+            _factory = factory;
+            _picker = picker ?? new HistorianClusterEndpointPicker(config);
+        }
+
+        private (HistorianAccess Connection, string Node) ConnectToAnyHealthyNode(HistorianConnectionType type)
+        {
+            var candidates = _picker.GetHealthyNodes();
+            if (candidates.Count == 0)
+            {
+                var total = _picker.NodeCount;
+                throw new InvalidOperationException(
+                    total == 0
+                        ? "No historian nodes configured"
+                        : $"All {total} historian nodes are in cooldown — no healthy endpoints to connect to");
+            }
+
+            Exception? lastException = null;
+            foreach (var node in candidates)
+            {
+                var attemptConfig = CloneConfigWithServerName(node);
+                try
+                {
+                    var conn = _factory.CreateAndConnect(attemptConfig, type);
+                    _picker.MarkHealthy(node);
+                    return (conn, node);
+                }
+                catch (Exception ex)
+                {
+                    _picker.MarkFailed(node, ex.Message);
+                    lastException = ex;
+                    Log.Warning(ex, "Historian node {Node} failed during connect attempt; trying next candidate", node);
+                }
+            }
+
+            var inner = lastException?.Message ?? "(no detail)";
+            throw new InvalidOperationException(
+                $"All {candidates.Count} healthy historian candidate(s) failed during connect: {inner}",
+                lastException);
+        }
+
+        private HistorianConfiguration CloneConfigWithServerName(string serverName)
+        {
+            return new HistorianConfiguration
+            {
+                Enabled = _config.Enabled,
+                ServerName = serverName,
+                ServerNames = _config.ServerNames,
+                FailureCooldownSeconds = _config.FailureCooldownSeconds,
+                IntegratedSecurity = _config.IntegratedSecurity,
+                UserName = _config.UserName,
+                Password = _config.Password,
+                Port = _config.Port,
+                CommandTimeoutSeconds = _config.CommandTimeoutSeconds,
+                MaxValuesPerRead = _config.MaxValuesPerRead
+            };
+        }
+
+        public HistorianHealthSnapshot GetHealthSnapshot()
+        {
+            var nodeStates = _picker.SnapshotNodeStates();
+            var healthyCount = 0;
+            foreach (var n in nodeStates)
+                if (n.IsHealthy) healthyCount++;
+
+            lock (_healthLock)
+            {
+                return new HistorianHealthSnapshot
+                {
+                    TotalQueries = _totalSuccesses + _totalFailures,
+                    TotalSuccesses = _totalSuccesses,
+                    TotalFailures = _totalFailures,
+                    ConsecutiveFailures = _consecutiveFailures,
+                    LastSuccessTime = _lastSuccessTime,
+                    LastFailureTime = _lastFailureTime,
+                    LastError = _lastError,
+                    ProcessConnectionOpen = Volatile.Read(ref _connection) != null,
+                    EventConnectionOpen = Volatile.Read(ref _eventConnection) != null,
+                    ActiveProcessNode = _activeProcessNode,
+                    ActiveEventNode = _activeEventNode,
+                    NodeCount = nodeStates.Count,
+                    HealthyNodeCount = healthyCount,
+                    Nodes = nodeStates
+                };
+            }
+        }
+
+        private void RecordSuccess()
+        {
+            lock (_healthLock)
+            {
+                _totalSuccesses++;
+                _lastSuccessTime = DateTime.UtcNow;
+                _consecutiveFailures = 0;
+                _lastError = null;
+            }
+        }
+
+        private void RecordFailure(string error)
+        {
+            lock (_healthLock)
+            {
+                _totalFailures++;
+                _lastFailureTime = DateTime.UtcNow;
+                _consecutiveFailures++;
+                _lastError = error;
+            }
+        }
+
+        private void EnsureConnected()
+        {
+            if (_disposed)
+                throw new ObjectDisposedException(nameof(HistorianDataSource));
+
+            if (Volatile.Read(ref _connection) != null) return;
+
+            var (conn, winningNode) = ConnectToAnyHealthyNode(HistorianConnectionType.Process);
+
+            lock (_connectionLock)
+            {
+                if (_disposed)
+                {
+                    conn.CloseConnection(out _);
+                    conn.Dispose();
+                    throw new ObjectDisposedException(nameof(HistorianDataSource));
+                }
+
+                if (_connection != null)
+                {
+                    conn.CloseConnection(out _);
+                    conn.Dispose();
+                    return;
+                }
+
+                _connection = conn;
+                lock (_healthLock) _activeProcessNode = winningNode;
+                Log.Information("Historian SDK connection opened to {Server}:{Port}", winningNode, _config.Port);
+            }
+        }
+
+        private void HandleConnectionError(Exception? ex = null)
+        {
+            lock (_connectionLock)
+            {
+                if (_connection == null) return;
+
+                try
+                {
+                    _connection.CloseConnection(out _);
+                    _connection.Dispose();
+                }
+                catch (Exception disposeEx)
+                {
+                    Log.Debug(disposeEx, "Error disposing Historian SDK connection during error recovery");
+                }
+
+                _connection = null;
+                string? failedNode;
+                lock (_healthLock)
+                {
+                    failedNode = _activeProcessNode;
+                    _activeProcessNode = null;
+                }
+
+                if (failedNode != null) _picker.MarkFailed(failedNode, ex?.Message ?? "mid-query failure");
+                Log.Warning(ex, "Historian SDK connection reset (node={Node})", failedNode ?? "(unknown)");
+            }
+        }
+
+        private void EnsureEventConnected()
+        {
+            if (_disposed)
+                throw new ObjectDisposedException(nameof(HistorianDataSource));
+
+            if (Volatile.Read(ref _eventConnection) != null) return;
+
+            var (conn, winningNode) = ConnectToAnyHealthyNode(HistorianConnectionType.Event);
+
+            lock (_eventConnectionLock)
+            {
+                if (_disposed)
+                {
+                    conn.CloseConnection(out _);
+                    conn.Dispose();
+                    throw new ObjectDisposedException(nameof(HistorianDataSource));
+                }
+
+                if (_eventConnection != null)
+                {
+                    conn.CloseConnection(out _);
+                    conn.Dispose();
+                    return;
+                }
+
+                _eventConnection = conn;
+                lock (_healthLock) _activeEventNode = winningNode;
+                Log.Information("Historian SDK event connection opened to {Server}:{Port}", winningNode, _config.Port);
+            }
+        }
+
+        private void HandleEventConnectionError(Exception? ex = null)
+        {
+            lock (_eventConnectionLock)
+            {
+                if (_eventConnection == null) return;
+
+                try
+                {
+                    _eventConnection.CloseConnection(out _);
+                    _eventConnection.Dispose();
+                }
+                catch (Exception disposeEx)
+                {
+                    Log.Debug(disposeEx, "Error disposing Historian SDK event connection during error recovery");
+                }
+
+                _eventConnection = null;
+                string? failedNode;
+                lock (_healthLock)
+                {
+                    failedNode = _activeEventNode;
+                    _activeEventNode = null;
+                }
+
+                if (failedNode != null) _picker.MarkFailed(failedNode, ex?.Message ?? "mid-query failure");
+                Log.Warning(ex, "Historian SDK event connection reset (node={Node})", failedNode ?? "(unknown)");
+            }
+        }
+
+        public Task<List<HistorianSample>> ReadRawAsync(
+            string tagName, DateTime startTime, DateTime endTime, int maxValues,
+            CancellationToken ct = default)
+        {
+            var results = new List<HistorianSample>();
+
+            try
+            {
+                EnsureConnected();
+
+                using var query = _connection!.CreateHistoryQuery();
+                var args = new HistoryQueryArgs
+                {
+                    TagNames = new StringCollection { tagName },
+                    StartDateTime = startTime,
+                    EndDateTime = endTime,
+                    RetrievalMode = HistorianRetrievalMode.Full
+                };
+
+                if (maxValues > 0)
+                    args.BatchSize = (uint)maxValues;
+                else if (_config.MaxValuesPerRead > 0)
+                    args.BatchSize = (uint)_config.MaxValuesPerRead;
+
+                if (!query.StartQuery(args, out var error))
+                {
+                    Log.Warning("Historian SDK raw query start failed for {Tag}: {Error}", tagName, error.ErrorCode);
+                    RecordFailure($"raw StartQuery: {error.ErrorCode}");
+                    HandleConnectionError();
+                    return Task.FromResult(results);
+                }
+
+                var count = 0;
+                var limit = maxValues > 0 ? maxValues : _config.MaxValuesPerRead;
+
+                while (query.MoveNext(out error))
+                {
+                    ct.ThrowIfCancellationRequested();
+
+                    var result = query.QueryResult;
+                    var timestamp = DateTime.SpecifyKind(result.StartDateTime, DateTimeKind.Utc);
+
+                    object? value;
+                    if (!string.IsNullOrEmpty(result.StringValue) && result.Value == 0)
+                        value = result.StringValue;
+                    else
+                        value = result.Value;
+
+                    results.Add(new HistorianSample
+                    {
+                        Value = value,
+                        TimestampUtc = timestamp,
+                        Quality = (byte)(result.OpcQuality & 0xFF),
+                    });
+
+                    count++;
+                    if (limit > 0 && count >= limit) break;
+                }
+
+                query.EndQuery(out _);
+                RecordSuccess();
+            }
+            catch (OperationCanceledException) { throw; }
+            catch (ObjectDisposedException) { throw; }
+            catch (Exception ex)
+            {
+                Log.Warning(ex, "HistoryRead raw failed for {Tag}", tagName);
+                RecordFailure($"raw: {ex.Message}");
+                HandleConnectionError(ex);
+            }
+
+            Log.Debug("HistoryRead raw: {Tag} returned {Count} values ({Start} to {End})",
+                tagName, results.Count, startTime, endTime);
+
+            return Task.FromResult(results);
+        }
+
+        public Task<List<HistorianAggregateSample>> ReadAggregateAsync(
+            string tagName, DateTime startTime, DateTime endTime,
+            double intervalMs, string aggregateColumn,
+            CancellationToken ct = default)
+        {
+            var results = new List<HistorianAggregateSample>();
+
+            try
+            {
+                EnsureConnected();
+
+                using var query = _connection!.CreateAnalogSummaryQuery();
+                var args = new AnalogSummaryQueryArgs
+                {
+                    TagNames = new StringCollection { tagName },
+                    StartDateTime = startTime,
+                    EndDateTime = endTime,
+                    Resolution = (ulong)intervalMs
+                };
+
+                if (!query.StartQuery(args, out var error))
+                {
+                    Log.Warning("Historian SDK aggregate query start failed for {Tag}: {Error}", tagName, error.ErrorCode);
+                    RecordFailure($"aggregate StartQuery: {error.ErrorCode}");
+                    HandleConnectionError();
+                    return Task.FromResult(results);
+                }
+
+                while (query.MoveNext(out error))
+                {
+                    ct.ThrowIfCancellationRequested();
+
+                    var result = query.QueryResult;
+                    var timestamp = DateTime.SpecifyKind(result.StartDateTime, DateTimeKind.Utc);
+                    var value = ExtractAggregateValue(result, aggregateColumn);
+
+                    results.Add(new HistorianAggregateSample
+                    {
+                        Value = value,
+                        TimestampUtc = timestamp,
+                    });
+                }
+
+                query.EndQuery(out _);
+                RecordSuccess();
+            }
+            catch (OperationCanceledException) { throw; }
+            catch (ObjectDisposedException) { throw; }
+            catch (Exception ex)
+            {
+                Log.Warning(ex, "HistoryRead aggregate failed for {Tag}", tagName);
+                RecordFailure($"aggregate: {ex.Message}");
+                HandleConnectionError(ex);
+            }
+
+            Log.Debug("HistoryRead aggregate ({Aggregate}): {Tag} returned {Count} values",
+                aggregateColumn, tagName, results.Count);
+
+            return Task.FromResult(results);
+        }
+
+        public Task<List<HistorianSample>> ReadAtTimeAsync(
+            string tagName, DateTime[] timestamps,
+            CancellationToken ct = default)
+        {
+            var results = new List<HistorianSample>();
+
+            if (timestamps == null || timestamps.Length == 0)
+                return Task.FromResult(results);
+
+            try
+            {
+                EnsureConnected();
+
+                foreach (var timestamp in timestamps)
+                {
+                    ct.ThrowIfCancellationRequested();
+
+                    using var query = _connection!.CreateHistoryQuery();
+                    var args = new HistoryQueryArgs
+                    {
+                        TagNames = new StringCollection { tagName },
+                        StartDateTime = timestamp,
+                        EndDateTime = timestamp,
+                        RetrievalMode = HistorianRetrievalMode.Interpolated,
+                        BatchSize = 1
+                    };
+
+                    if (!query.StartQuery(args, out var error))
+                    {
+                        results.Add(new HistorianSample
+                        {
+                            Value = null,
+                            TimestampUtc = DateTime.SpecifyKind(timestamp, DateTimeKind.Utc),
+                            Quality = 0, // Bad
+                        });
+                        continue;
+                    }
+
+                    if (query.MoveNext(out error))
+                    {
+                        var result = query.QueryResult;
+                        object? value;
+                        if (!string.IsNullOrEmpty(result.StringValue) && result.Value == 0)
+                            value = result.StringValue;
+                        else
+                            value = result.Value;
+
+                        results.Add(new HistorianSample
+                        {
+                            Value = value,
+                            TimestampUtc = DateTime.SpecifyKind(timestamp, DateTimeKind.Utc),
+                            Quality = (byte)(result.OpcQuality & 0xFF),
+                        });
+                    }
+                    else
+                    {
+                        results.Add(new HistorianSample
+                        {
+                            Value = null,
+                            TimestampUtc = DateTime.SpecifyKind(timestamp, DateTimeKind.Utc),
+                            Quality = 0,
+                        });
+                    }
+
+                    query.EndQuery(out _);
+                }
+                RecordSuccess();
+            }
+            catch (OperationCanceledException) { throw; }
+            catch (ObjectDisposedException) { throw; }
+            catch (Exception ex)
+            {
+                Log.Warning(ex, "HistoryRead at-time failed for {Tag}", tagName);
+                RecordFailure($"at-time: {ex.Message}");
+                HandleConnectionError(ex);
+            }
+
+            Log.Debug("HistoryRead at-time: {Tag} returned {Count} values for {Timestamps} timestamps",
+                tagName, results.Count, timestamps.Length);
+
+            return Task.FromResult(results);
+        }
+
+        public Task<List<HistorianEventDto>> ReadEventsAsync(
+            string? sourceName, DateTime startTime, DateTime endTime, int maxEvents,
+            CancellationToken ct = default)
+        {
+            var results = new List<HistorianEventDto>();
+
+            try
+            {
+                EnsureEventConnected();
+
+                using var query = _eventConnection!.CreateEventQuery();
+                var args = new EventQueryArgs
+                {
+                    StartDateTime = startTime,
+                    EndDateTime = endTime,
+                    EventCount = maxEvents > 0 ? (uint)maxEvents : (uint)_config.MaxValuesPerRead,
+                    QueryType = HistorianEventQueryType.Events,
+                    EventOrder = HistorianEventOrder.Ascending
+                };
+
+                if (!string.IsNullOrEmpty(sourceName))
+                {
+                    query.AddEventFilter("Source", HistorianComparisionType.Equal, sourceName, out _);
+                }
+
+                if (!query.StartQuery(args, out var error))
+                {
+                    Log.Warning("Historian SDK event query start failed: {Error}", error.ErrorCode);
+                    RecordFailure($"events StartQuery: {error.ErrorCode}");
+                    HandleEventConnectionError();
+                    return Task.FromResult(results);
+                }
+
+                var count = 0;
+                while (query.MoveNext(out error))
+                {
+                    ct.ThrowIfCancellationRequested();
+                    results.Add(ToDto(query.QueryResult));
+                    count++;
+                    if (maxEvents > 0 && count >= maxEvents) break;
+                }
+
+                query.EndQuery(out _);
+                RecordSuccess();
+            }
+            catch (OperationCanceledException) { throw; }
+            catch (ObjectDisposedException) { throw; }
+            catch (Exception ex)
+            {
+                Log.Warning(ex, "HistoryRead events failed for source {Source}", sourceName ?? "(all)");
+                RecordFailure($"events: {ex.Message}");
+                HandleEventConnectionError(ex);
+            }
+
+            Log.Debug("HistoryRead events: source={Source} returned {Count} events ({Start} to {End})",
+                sourceName ?? "(all)", results.Count, startTime, endTime);
+
+            return Task.FromResult(results);
+        }
+
+        private static HistorianEventDto ToDto(HistorianEvent evt)
+        {
+            // The ArchestrA SDK marks these properties obsolete but still returns them; their
+            // successors aren't wired in the version we bind against. Using them is the documented
+            // v1 behavior — suppressed locally instead of project-wide so any non-event use of
+            // deprecated SDK surface still surfaces as an error.
+#pragma warning disable CS0618
+            return new HistorianEventDto
+            {
+                Id = evt.Id,
+                Source = evt.Source,
+                EventTime = evt.EventTime,
+                ReceivedTime = evt.ReceivedTime,
+                DisplayText = evt.DisplayText,
+                Severity = (ushort)evt.Severity
+            };
+#pragma warning restore CS0618
+        }
+
+        internal static double? ExtractAggregateValue(AnalogSummaryQueryResult result, string column)
+        {
+            switch (column)
+            {
+                case "Average": return result.Average;
+                case "Minimum": return result.Minimum;
+                case "Maximum": return result.Maximum;
+                case "ValueCount": return result.ValueCount;
+                case "First": return result.First;
+                case "Last": return result.Last;
+                case "StdDev": return result.StdDev;
+                default: return null;
+            }
+        }
+
+        public void Dispose()
+        {
+            if (_disposed) return;
+            _disposed = true;
+
+            try
+            {
+                _connection?.CloseConnection(out _);
+                _connection?.Dispose();
+            }
+            catch (Exception ex)
+            {
+                Log.Warning(ex, "Error closing Historian SDK connection");
+            }
+
+            try
+            {
+                _eventConnection?.CloseConnection(out _);
+                _eventConnection?.Dispose();
+            }
+            catch (Exception ex)
+            {
+                Log.Warning(ex, "Error closing Historian SDK event connection");
+            }
+
+            _connection = null;
+            _eventConnection = null;
+        }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Backend/HistorianEventDto.cs

@@ -0,0 +1,18 @@
+using System;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend
+{
+    /// <summary>
+    ///     SDK-free representation of a Historian event record. Prevents ArchestrA types from
+    ///     leaking beyond <c>HistorianDataSource</c>.
+    /// </summary>
+    public sealed class HistorianEventDto
+    {
+        public Guid Id { get; set; }
+        public string? Source { get; set; }
+        public DateTime EventTime { get; set; }
+        public DateTime ReceivedTime { get; set; }
+        public string? DisplayText { get; set; }
+        public ushort Severity { get; set; }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Backend/HistorianHealthSnapshot.cs

@@ -0,0 +1,27 @@
+using System;
+using System.Collections.Generic;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend
+{
+    /// <summary>
+    ///     Point-in-time runtime health of the historian subsystem — consumed by the status dashboard
+    ///     via an IPC health query (not wired in PR #5; deferred).
+    /// </summary>
+    public sealed class HistorianHealthSnapshot
+    {
+        public long TotalQueries { get; set; }
+        public long TotalSuccesses { get; set; }
+        public long TotalFailures { get; set; }
+        public int ConsecutiveFailures { get; set; }
+        public DateTime? LastSuccessTime { get; set; }
+        public DateTime? LastFailureTime { get; set; }
+        public string? LastError { get; set; }
+        public bool ProcessConnectionOpen { get; set; }
+        public bool EventConnectionOpen { get; set; }
+        public string? ActiveProcessNode { get; set; }
+        public string? ActiveEventNode { get; set; }
+        public int NodeCount { get; set; }
+        public int HealthyNodeCount { get; set; }
+        public List<HistorianClusterNodeState> Nodes { get; set; } = new();
+    }
+}

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

@@ -0,0 +1,46 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend;
+
+/// <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.Historian.Wonderware/Backend/HistorianSample.cs

@@ -0,0 +1,30 @@
+using System;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend
+{
+    /// <summary>
+    ///     OPC-UA-free representation of a single historical data point. The Host returns these
+    ///     across the IPC boundary as <c>GalaxyDataValue</c>; the Proxy maps quality and value to
+    ///     OPC UA <c>DataValue</c>. Raw MX quality byte is preserved so the Proxy can use the same
+    ///     quality mapper it already uses for live reads.
+    /// </summary>
+    public sealed class HistorianSample
+    {
+        public object? Value { get; set; }
+
+        /// <summary>Raw OPC DA quality byte from the historian SDK (low 8 bits of OpcQuality).</summary>
+        public byte Quality { get; set; }
+
+        public DateTime TimestampUtc { get; set; }
+    }
+
+    /// <summary>
+    ///     Result of <see cref="IHistorianDataSource.ReadAggregateAsync"/>. When <see cref="Value"/> is
+    ///     null the aggregate is unavailable for that bucket (Proxy maps to <c>BadNoData</c>).
+    /// </summary>
+    public sealed class HistorianAggregateSample
+    {
+        public double? Value { get; set; }
+        public DateTime TimestampUtc { get; set; }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Backend/IHistorianConnectionFactory.cs

@@ -0,0 +1,73 @@
+using System;
+using System.Threading;
+using ArchestrA;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend
+{
+    /// <summary>
+    ///     Creates and opens Historian SDK connections. Extracted so tests can inject fakes that
+    ///     control connection success, failure, and timeout behavior.
+    /// </summary>
+    internal interface IHistorianConnectionFactory
+    {
+        HistorianAccess CreateAndConnect(HistorianConfiguration config, HistorianConnectionType type);
+    }
+
+    /// <summary>Production implementation — opens real Historian SDK connections.</summary>
+    internal sealed class SdkHistorianConnectionFactory : IHistorianConnectionFactory
+    {
+        public HistorianAccess CreateAndConnect(HistorianConfiguration config, HistorianConnectionType type)
+        {
+            var conn = new HistorianAccess();
+
+            var args = new HistorianConnectionArgs
+            {
+                ServerName = config.ServerName,
+                TcpPort = (ushort)config.Port,
+                IntegratedSecurity = config.IntegratedSecurity,
+                UseArchestrAUser = config.IntegratedSecurity,
+                ConnectionType = type,
+                ReadOnly = true,
+                PacketTimeout = (uint)(config.CommandTimeoutSeconds * 1000)
+            };
+
+            if (!config.IntegratedSecurity)
+            {
+                args.UserName = config.UserName ?? string.Empty;
+                args.Password = config.Password ?? string.Empty;
+            }
+
+            if (!conn.OpenConnection(args, out var error))
+            {
+                conn.Dispose();
+                throw new InvalidOperationException(
+                    $"Failed to open Historian SDK connection to {config.ServerName}:{config.Port}: {error.ErrorCode}");
+            }
+
+            var timeoutMs = config.CommandTimeoutSeconds * 1000;
+            var elapsed = 0;
+            while (elapsed < timeoutMs)
+            {
+                var status = new HistorianConnectionStatus();
+                conn.GetConnectionStatus(ref status);
+
+                if (status.ConnectedToServer)
+                    return conn;
+
+                if (status.ErrorOccurred)
+                {
+                    conn.Dispose();
+                    throw new InvalidOperationException(
+                        $"Historian SDK connection failed: {status.Error}");
+                }
+
+                Thread.Sleep(250);
+                elapsed += 250;
+            }
+
+            conn.Dispose();
+            throw new TimeoutException(
+                $"Historian SDK connection to {config.ServerName}:{config.Port} timed out after {config.CommandTimeoutSeconds}s");
+        }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Backend/IHistorianDataSource.cs

@@ -0,0 +1,34 @@
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend
+{
+    /// <summary>
+    ///     OPC-UA-free surface for the Wonderware Historian subsystem inside Galaxy.Host.
+    ///     Implementations read via the aahClient* SDK; the Proxy side maps returned samples
+    ///     to OPC UA <c>DataValue</c>.
+    /// </summary>
+    public interface IHistorianDataSource : IDisposable
+    {
+        Task<List<HistorianSample>> ReadRawAsync(
+            string tagName, DateTime startTime, DateTime endTime, int maxValues,
+            CancellationToken ct = default);
+
+        Task<List<HistorianAggregateSample>> ReadAggregateAsync(
+            string tagName, DateTime startTime, DateTime endTime,
+            double intervalMs, string aggregateColumn,
+            CancellationToken ct = default);
+
+        Task<List<HistorianSample>> ReadAtTimeAsync(
+            string tagName, DateTime[] timestamps,
+            CancellationToken ct = default);
+
+        Task<List<HistorianEventDto>> ReadEventsAsync(
+            string? sourceName, DateTime startTime, DateTime endTime, int maxEvents,
+            CancellationToken ct = default);
+
+        HistorianHealthSnapshot GetHealthSnapshot();
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.csproj

@@ -4,7 +4,7 @@
         <OutputType>Exe</OutputType>
         <TargetFramework>net48</TargetFramework>
         <!-- x86 to match the in-process bitness expectations of the Wonderware Historian SDK
-             that PR 3.2 will lift in. Mirrors Driver.Galaxy.Host's bitness for consistency. -->
+             that PR 3.2 lifted in. Mirrors Driver.Galaxy.Host's bitness for consistency. -->
         <PlatformTarget>x86</PlatformTarget>
         <Prefer32Bit>true</Prefer32Bit>
         <Nullable>enable</Nullable>
@@ -17,6 +17,10 @@
     </PropertyGroup>
 
     <ItemGroup>
+        <PackageReference Include="System.IO.Pipes.AccessControl" Version="5.0.0"/>
+        <PackageReference Include="System.Memory" Version="4.5.5"/>
+        <PackageReference Include="System.Threading.Tasks.Extensions" Version="4.5.4"/>
+        <PackageReference Include="System.Data.SqlClient" Version="4.9.0"/>
         <PackageReference Include="Serilog" Version="4.2.0"/>
         <PackageReference Include="Serilog.Sinks.File" Version="7.0.0"/>
     </ItemGroup>
@@ -25,4 +29,39 @@
         <InternalsVisibleTo Include="ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Tests"/>
     </ItemGroup>
 
+    <ItemGroup>
+        <!-- Wonderware Historian SDK — consumed by Backend/ for HistoryReadAsync.
+             Lifted from Driver.Galaxy.Host in PR 3.2 so the sidecar owns the SDK. -->
+        <Reference Include="aahClientManaged">
+            <HintPath>..\..\lib\aahClientManaged.dll</HintPath>
+            <EmbedInteropTypes>false</EmbedInteropTypes>
+        </Reference>
+        <Reference Include="aahClientCommon">
+            <HintPath>..\..\lib\aahClientCommon.dll</HintPath>
+            <EmbedInteropTypes>false</EmbedInteropTypes>
+        </Reference>
+    </ItemGroup>
+
+    <ItemGroup>
+        <!-- Historian SDK native and satellite DLLs — staged beside the host exe so the
+             aahClientManaged wrapper can P/Invoke into them without an AssemblyResolve hook. -->
+        <None Include="..\..\lib\aahClient.dll">
+            <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+        </None>
+        <None Include="..\..\lib\Historian.CBE.dll">
+            <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+        </None>
+        <None Include="..\..\lib\Historian.DPAPI.dll">
+            <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+        </None>
+        <None Include="..\..\lib\ArchestrA.CloudHistorian.Contract.dll">
+            <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+        </None>
+    </ItemGroup>
+
+    <ItemGroup>
+        <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-37gx-xxp4-5rgx"/>
+        <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-w3x6-4m5h-cxqf"/>
+    </ItemGroup>
+
 </Project>