chore: organize solution into module folders (Core/Server/Drivers/Client/Tooling)

Group all 69 projects into category subfolders under src/ and tests/ so the
Rider Solution Explorer mirrors the module structure. Folders: Core, Server,
Drivers (with a nested Driver CLIs subfolder), Client, Tooling.

- Move every project folder on disk with git mv (history preserved as renames).
- Recompute relative paths in 57 .csproj files: cross-category ProjectReferences,
  the lib/ HintPath+None refs in Driver.Historian.Wonderware, and the external
  mxaccessgw refs in Driver.Galaxy and its test project.
- Rebuild ZB.MOM.WW.OtOpcUa.slnx with nested solution folders.
- Re-prefix project paths in functional scripts (e2e, compliance, smoke SQL,
  integration, install).

Build green (0 errors); unit tests pass. Docs left for a separate pass.

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

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

@@ -0,0 +1,105 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using Serilog;
+using ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Ipc;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend
+{
+    /// <summary>
+    ///     IPC-side <see cref="IAlarmEventWriter"/> implementation that delegates to an
+    ///     <see cref="IAlarmHistorianWriteBackend"/> (production: aahClientManaged-bound)
+    ///     and maps the trinary <see cref="AlarmHistorianWriteOutcome"/> down to the
+    ///     <c>bool[]</c> the IPC reply contract carries. Per-event outcomes:
+    ///     <list type="bullet">
+    ///       <item><description><see cref="AlarmHistorianWriteOutcome.Ack"/> → <c>true</c> (drop from sender's queue).</description></item>
+    ///       <item><description><see cref="AlarmHistorianWriteOutcome.RetryPlease"/> → <c>false</c> (sender retries on next drain tick).</description></item>
+    ///       <item><description><see cref="AlarmHistorianWriteOutcome.PermanentFail"/> → <c>false</c> (sender's B.4 widens the IPC bool back into the trinary outcome by inspecting structured diagnostics; this slot intentionally collapses to "not-ok" at the wire).</description></item>
+    ///     </list>
+    /// </summary>
+    public sealed class AahClientManagedAlarmEventWriter : IAlarmEventWriter
+    {
+        private static readonly ILogger Log = Serilog.Log.ForContext<AahClientManagedAlarmEventWriter>();
+
+        private readonly IAlarmHistorianWriteBackend _backend;
+
+        public AahClientManagedAlarmEventWriter(IAlarmHistorianWriteBackend backend)
+        {
+            _backend = backend ?? throw new ArgumentNullException(nameof(backend));
+        }
+
+        public async Task<bool[]> WriteAsync(AlarmHistorianEventDto[] events, CancellationToken cancellationToken)
+        {
+            if (events is null || events.Length == 0)
+            {
+                return new bool[0];
+            }
+
+            AlarmHistorianWriteOutcome[] outcomes;
+            try
+            {
+                outcomes = await _backend.WriteBatchAsync(events, cancellationToken).ConfigureAwait(false);
+            }
+            catch (OperationCanceledException)
+            {
+                throw;
+            }
+            catch (Exception ex)
+            {
+                // Backend-level failure (cluster unreachable, transport error). Treat the
+                // whole batch as RetryPlease so the sender's queue holds the rows for
+                // the next drain tick — preferable to dropping them on a transient.
+                Log.Warning(ex,
+                    "Alarm historian backend WriteBatchAsync threw — marking entire {Count}-event batch RetryPlease.",
+                    events.Length);
+                var fallback = new bool[events.Length];
+                return fallback;
+            }
+
+            if (outcomes.Length != events.Length)
+            {
+                // Backend contract violation — defensive degrade so a bug in the backend
+                // doesn't desync the sender's queue accounting. Treat as RetryPlease.
+                Log.Warning(
+                    "Alarm historian backend returned {ReturnedCount} outcomes for a batch of {InputCount} events; degrading to RetryPlease for the whole batch.",
+                    outcomes.Length, events.Length);
+                return new bool[events.Length];
+            }
+
+            var perEventOk = new bool[outcomes.Length];
+            for (var i = 0; i < outcomes.Length; i++)
+            {
+                perEventOk[i] = outcomes[i] == AlarmHistorianWriteOutcome.Ack;
+            }
+            return perEventOk;
+        }
+
+        /// <summary>
+        ///     Translate the outcome of a single SDK call (raw HRESULT + diagnostic) into the
+        ///     trinary <see cref="AlarmHistorianWriteOutcome"/>. Exposed for the production
+        ///     <see cref="SdkAlarmHistorianWriteBackend"/> to share the mapping with tests.
+        /// </summary>
+        public static AlarmHistorianWriteOutcome MapOutcome(int hresult, bool isCommunicationError, bool isMalformedInput)
+        {
+            // Order matters: malformed input is permanent regardless of HRESULT pattern;
+            // communication-class errors are transient regardless of which specific
+            // HRESULT bit fired.
+            if (isMalformedInput)
+            {
+                return AlarmHistorianWriteOutcome.PermanentFail;
+            }
+            if (hresult == 0)
+            {
+                return AlarmHistorianWriteOutcome.Ack;
+            }
+            if (isCommunicationError)
+            {
+                return AlarmHistorianWriteOutcome.RetryPlease;
+            }
+            // Default: unknown HRESULT failure — be conservative and let the sender retry.
+            // The sender's drain worker has its own dead-letter cap so a permanently-broken
+            // event won't loop forever.
+            return AlarmHistorianWriteOutcome.RetryPlease;
+        }
+    }
+}

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

@@ -0,0 +1,19 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend
+{
+    /// <summary>
+    ///     Per-event outcome from <see cref="IAlarmHistorianWriteBackend.WriteBatchAsync"/>.
+    ///     Sidecar-local twin of <c>Core.AlarmHistorian.HistorianWriteOutcome</c> (the
+    ///     sidecar runs net48 and cannot reference the net10 Core project; the IPC
+    ///     contract narrows this to <c>bool</c> per slot, so the lmxopcua-side consumer
+    ///     widens that back into the trinary outcome at the IPC boundary in PR B.4).
+    /// </summary>
+    public enum AlarmHistorianWriteOutcome
+    {
+        /// <summary>Event accepted by the historian. Drop from the store-and-forward queue.</summary>
+        Ack,
+        /// <summary>Transient failure (server busy, disconnected, timeout). Leave queued; retry on next drain tick.</summary>
+        RetryPlease,
+        /// <summary>Permanent failure (malformed event, unrecoverable SDK error). Move to dead-letter on the lmxopcua side.</summary>
+        PermanentFail,
+    }
+}

src/Drivers/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/Drivers/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/Drivers/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/Drivers/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/Drivers/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/Drivers/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/Drivers/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/Drivers/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/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Backend/IAlarmHistorianWriteBackend.cs

@@ -0,0 +1,30 @@
+using System.Threading;
+using System.Threading.Tasks;
+using ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Ipc;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend
+{
+    /// <summary>
+    ///     The actual aahClientManaged-bound writer. Extracted so unit tests can
+    ///     substitute a fake without touching the SDK; the production
+    ///     implementation lives in <see cref="SdkAlarmHistorianWriteBackend"/>.
+    /// </summary>
+    /// <remarks>
+    ///     Implementations are responsible for connection management + cluster
+    ///     failover. The wrapping <see cref="AahClientManagedAlarmEventWriter"/>
+    ///     handles batch-level orchestration but delegates the per-event SDK call
+    ///     here so the unit tests can drive every documented MxStatus outcome
+    ///     without an installed AVEVA Historian.
+    /// </remarks>
+    public interface IAlarmHistorianWriteBackend
+    {
+        /// <summary>
+        ///     Persist the supplied events to the historian. Returns one outcome per
+        ///     input slot in the same order — must always return an array of the same
+        ///     length as <paramref name="events"/>.
+        /// </summary>
+        Task<AlarmHistorianWriteOutcome[]> WriteBatchAsync(
+            AlarmHistorianEventDto[] events,
+            CancellationToken cancellationToken);
+    }
+}

src/Drivers/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/Drivers/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/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Backend/SdkAlarmHistorianWriteBackend.cs

@@ -0,0 +1,73 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using Serilog;
+using ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Ipc;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend
+{
+    /// <summary>
+    ///     Production <see cref="IAlarmHistorianWriteBackend"/> backed by AVEVA Historian's
+    ///     <c>aahClientManaged</c> alarm-event write API. The exact SDK entry point is
+    ///     pinned during the live-rig smoke in PR D.1 — until that gate, this backend
+    ///     reports <see cref="AlarmHistorianWriteOutcome.RetryPlease"/> for every
+    ///     event with a structured diagnostic so the lmxopcua-side
+    ///     <c>SqliteStoreAndForwardSink</c> retains the queued events rather than dropping
+    ///     or hard-failing them.
+    /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         Cluster failover reuses <see cref="HistorianClusterEndpointPicker"/> via
+    ///         the shared <see cref="HistorianDataSource"/> connection pool — there is
+    ///         no second connection pool for writes. Wonderware Historian's alarm-event
+    ///         write surface accepts the same <c>HistorianAccess</c> session a read
+    ///         opens, so reusing the picker is parity-preserving with v1's
+    ///         <c>GalaxyHistorianWriter</c>.
+    ///     </para>
+    ///     <para>
+    ///         Once D.1 confirms the SDK entry point, this class swaps the placeholder
+    ///         body for the real call sequence. The mapping from raw HRESULT /
+    ///         <c>HistorianError</c> codes onto <see cref="AlarmHistorianWriteOutcome"/>
+    ///         is already shared via <see cref="AahClientManagedAlarmEventWriter.MapOutcome"/>
+    ///         so the smoke-pinned change stays minimal.
+    ///     </para>
+    /// </remarks>
+    public sealed class SdkAlarmHistorianWriteBackend : IAlarmHistorianWriteBackend
+    {
+        private static readonly ILogger Log = Serilog.Log.ForContext<SdkAlarmHistorianWriteBackend>();
+
+        private readonly HistorianConfiguration _config;
+
+        public SdkAlarmHistorianWriteBackend(HistorianConfiguration config)
+        {
+            _config = config ?? throw new ArgumentNullException(nameof(config));
+        }
+
+        public Task<AlarmHistorianWriteOutcome[]> WriteBatchAsync(
+            AlarmHistorianEventDto[] events,
+            CancellationToken cancellationToken)
+        {
+            if (events is null || events.Length == 0)
+            {
+                return Task.FromResult(new AlarmHistorianWriteOutcome[0]);
+            }
+
+            // Placeholder: pin the SDK entry point in PR D.1 against a live AVEVA
+            // Historian. Until then the call returns RetryPlease for every slot so
+            // the lmxopcua-side sink keeps the events queued rather than dropping
+            // them — same effect as the current NullAlarmHistorianSink fallback,
+            // but visible through the structured diagnostic + per-event outcome.
+            Log.Warning(
+                "Alarm historian SDK write path not yet pinned — returning RetryPlease for {Count} event(s) from server {Server}. PR D.1 swaps this for the live aahClientManaged call.",
+                events.Length,
+                _config.ServerName);
+
+            var outcomes = new AlarmHistorianWriteOutcome[events.Length];
+            for (var i = 0; i < outcomes.Length; i++)
+            {
+                outcomes[i] = AlarmHistorianWriteOutcome.RetryPlease;
+            }
+            return Task.FromResult(outcomes);
+        }
+    }
+}

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Ipc/Contracts.cs

@@ -0,0 +1,168 @@
+using System;
+using MessagePack;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Ipc;
+
+// ============================================================================
+// Wire DTOs for the sidecar pipe protocol. The sidecar speaks its own legacy
+// shape (List<HistorianSample> etc.) — the .NET 10 client (PR 3.4) translates
+// to / from Core.Abstractions.DataValueSnapshot + HistoricalEvent.
+//
+// Timestamps cross the wire as DateTime ticks (long) to dodge MessagePack's
+// DateTime kind/timezone quirks; both sides convert with DateTime(ticks, Utc).
+// ============================================================================
+
+/// <summary>Single historical data point. Quality is the raw OPC DA byte; client maps to OPC UA StatusCode.</summary>
+[MessagePackObject]
+public sealed class HistorianSampleDto
+{
+    /// <summary>MessagePack-serialized value bytes. Client deserializes per the tag's mx_data_type.</summary>
+    [Key(0)] public byte[]? ValueBytes { get; set; }
+
+    /// <summary>Raw OPC DA quality byte from the historian SDK (low 8 bits of OpcQuality).</summary>
+    [Key(1)] public byte Quality { get; set; }
+
+    [Key(2)] public long TimestampUtcTicks { get; set; }
+}
+
+/// <summary>Aggregate bucket; <c>Value</c> is null when the aggregate is unavailable for the bucket.</summary>
+[MessagePackObject]
+public sealed class HistorianAggregateSampleDto
+{
+    [Key(0)] public double? Value { get; set; }
+    [Key(1)] public long TimestampUtcTicks { get; set; }
+}
+
+/// <summary>Historian event row.</summary>
+[MessagePackObject]
+public sealed class HistorianEventDto
+{
+    [Key(0)] public string EventId { get; set; } = string.Empty;
+    [Key(1)] public string? Source { get; set; }
+    [Key(2)] public long EventTimeUtcTicks { get; set; }
+    [Key(3)] public long ReceivedTimeUtcTicks { get; set; }
+    [Key(4)] public string? DisplayText { get; set; }
+    [Key(5)] public ushort Severity { get; set; }
+}
+
+/// <summary>Alarm event to persist back into the historian event store.</summary>
+[MessagePackObject]
+public sealed class AlarmHistorianEventDto
+{
+    [Key(0)] public string EventId { get; set; } = string.Empty;
+    [Key(1)] public string SourceName { get; set; } = string.Empty;
+    [Key(2)] public string? ConditionId { get; set; }
+    [Key(3)] public string AlarmType { get; set; } = string.Empty;
+    [Key(4)] public string? Message { get; set; }
+    [Key(5)] public ushort Severity { get; set; }
+    [Key(6)] public long EventTimeUtcTicks { get; set; }
+    [Key(7)] public string? AckComment { get; set; }
+}
+
+// ===== Read Raw =====
+
+[MessagePackObject]
+public sealed class ReadRawRequest
+{
+    [Key(0)] public string TagName { get; set; } = string.Empty;
+    [Key(1)] public long StartUtcTicks { get; set; }
+    [Key(2)] public long EndUtcTicks { get; set; }
+    [Key(3)] public int MaxValues { get; set; }
+    [Key(4)] public string CorrelationId { get; set; } = string.Empty;
+}
+
+[MessagePackObject]
+public sealed class ReadRawReply
+{
+    [Key(0)] public string CorrelationId { get; set; } = string.Empty;
+    [Key(1)] public bool Success { get; set; }
+    [Key(2)] public string? Error { get; set; }
+    [Key(3)] public HistorianSampleDto[] Samples { get; set; } = Array.Empty<HistorianSampleDto>();
+}
+
+// ===== Read Processed =====
+
+[MessagePackObject]
+public sealed class ReadProcessedRequest
+{
+    [Key(0)] public string TagName { get; set; } = string.Empty;
+    [Key(1)] public long StartUtcTicks { get; set; }
+    [Key(2)] public long EndUtcTicks { get; set; }
+    [Key(3)] public double IntervalMs { get; set; }
+
+    /// <summary>
+    ///     Wonderware AnalogSummary column name: "Average", "Minimum", "Maximum", "ValueCount".
+    ///     The .NET 10 client maps OPC UA aggregate enum → column.
+    /// </summary>
+    [Key(4)] public string AggregateColumn { get; set; } = string.Empty;
+    [Key(5)] public string CorrelationId { get; set; } = string.Empty;
+}
+
+[MessagePackObject]
+public sealed class ReadProcessedReply
+{
+    [Key(0)] public string CorrelationId { get; set; } = string.Empty;
+    [Key(1)] public bool Success { get; set; }
+    [Key(2)] public string? Error { get; set; }
+    [Key(3)] public HistorianAggregateSampleDto[] Buckets { get; set; } = Array.Empty<HistorianAggregateSampleDto>();
+}
+
+// ===== Read At-Time =====
+
+[MessagePackObject]
+public sealed class ReadAtTimeRequest
+{
+    [Key(0)] public string TagName { get; set; } = string.Empty;
+    [Key(1)] public long[] TimestampsUtcTicks { get; set; } = Array.Empty<long>();
+    [Key(2)] public string CorrelationId { get; set; } = string.Empty;
+}
+
+[MessagePackObject]
+public sealed class ReadAtTimeReply
+{
+    [Key(0)] public string CorrelationId { get; set; } = string.Empty;
+    [Key(1)] public bool Success { get; set; }
+    [Key(2)] public string? Error { get; set; }
+    [Key(3)] public HistorianSampleDto[] Samples { get; set; } = Array.Empty<HistorianSampleDto>();
+}
+
+// ===== Read Events =====
+
+[MessagePackObject]
+public sealed class ReadEventsRequest
+{
+    [Key(0)] public string? SourceName { get; set; }
+    [Key(1)] public long StartUtcTicks { get; set; }
+    [Key(2)] public long EndUtcTicks { get; set; }
+    [Key(3)] public int MaxEvents { get; set; }
+    [Key(4)] public string CorrelationId { get; set; } = string.Empty;
+}
+
+[MessagePackObject]
+public sealed class ReadEventsReply
+{
+    [Key(0)] public string CorrelationId { get; set; } = string.Empty;
+    [Key(1)] public bool Success { get; set; }
+    [Key(2)] public string? Error { get; set; }
+    [Key(3)] public HistorianEventDto[] Events { get; set; } = Array.Empty<HistorianEventDto>();
+}
+
+// ===== Write Alarm Events =====
+
+[MessagePackObject]
+public sealed class WriteAlarmEventsRequest
+{
+    [Key(0)] public AlarmHistorianEventDto[] Events { get; set; } = Array.Empty<AlarmHistorianEventDto>();
+    [Key(1)] public string CorrelationId { get; set; } = string.Empty;
+}
+
+[MessagePackObject]
+public sealed class WriteAlarmEventsReply
+{
+    [Key(0)] public string CorrelationId { get; set; } = string.Empty;
+    [Key(1)] public bool Success { get; set; }
+    [Key(2)] public string? Error { get; set; }
+
+    /// <summary>Per-event success flag, parallel to <see cref="WriteAlarmEventsRequest.Events"/>.</summary>
+    [Key(3)] public bool[] PerEventOk { get; set; } = Array.Empty<bool>();
+}

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Ipc/FrameReader.cs

@@ -0,0 +1,68 @@
+using System;
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
+using MessagePack;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Ipc;
+
+/// <summary>
+///     Reads length-prefixed, kind-tagged frames from a stream. Single-consumer — do not call
+///     <see cref="ReadFrameAsync"/> from multiple threads against the same instance. Mirror of
+///     Driver.Galaxy.Shared.FrameReader; sidecar carries its own copy so the deletion of
+///     Galaxy.Shared in PR 7.2 doesn't reach the sidecar.
+/// </summary>
+public sealed class FrameReader : IDisposable
+{
+    private readonly Stream _stream;
+    private readonly bool _leaveOpen;
+
+    public FrameReader(Stream stream, bool leaveOpen = false)
+    {
+        _stream = stream ?? throw new ArgumentNullException(nameof(stream));
+        _leaveOpen = leaveOpen;
+    }
+
+    public async Task<(MessageKind Kind, byte[] Body)?> ReadFrameAsync(CancellationToken ct)
+    {
+        var lengthPrefix = new byte[Framing.LengthPrefixSize];
+        if (!await ReadExactAsync(lengthPrefix, ct).ConfigureAwait(false))
+            return null; // clean EOF on frame boundary
+
+        var length = (lengthPrefix[0] << 24) | (lengthPrefix[1] << 16) | (lengthPrefix[2] << 8) | lengthPrefix[3];
+        if (length < 0 || length > Framing.MaxFrameBodyBytes)
+            throw new InvalidDataException($"Sidecar IPC frame length {length} out of range.");
+
+        var kindByte = _stream.ReadByte();
+        if (kindByte < 0) throw new EndOfStreamException("EOF after length prefix, before kind byte.");
+
+        var body = new byte[length];
+        if (!await ReadExactAsync(body, ct).ConfigureAwait(false))
+            throw new EndOfStreamException("EOF mid-frame.");
+
+        return ((MessageKind)(byte)kindByte, body);
+    }
+
+    public static T Deserialize<T>(byte[] body) => MessagePackSerializer.Deserialize<T>(body);
+
+    private async Task<bool> ReadExactAsync(byte[] buffer, CancellationToken ct)
+    {
+        var offset = 0;
+        while (offset < buffer.Length)
+        {
+            var read = await _stream.ReadAsync(buffer, offset, buffer.Length - offset, ct).ConfigureAwait(false);
+            if (read == 0)
+            {
+                if (offset == 0) return false;
+                throw new EndOfStreamException($"Stream ended after reading {offset} of {buffer.Length} bytes.");
+            }
+            offset += read;
+        }
+        return true;
+    }
+
+    public void Dispose()
+    {
+        if (!_leaveOpen) _stream.Dispose();
+    }
+}

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Ipc/FrameWriter.cs

@@ -0,0 +1,57 @@
+using System;
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
+using MessagePack;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Ipc;
+
+/// <summary>
+///     Writes length-prefixed, kind-tagged MessagePack frames to a stream. Thread-safe via
+///     <see cref="SemaphoreSlim"/> so concurrent producers (heartbeat + reply paths) get
+///     serialized writes. Mirror of Driver.Galaxy.Shared.FrameWriter; sidecar carries its
+///     own copy.
+/// </summary>
+public sealed class FrameWriter : IDisposable
+{
+    private readonly Stream _stream;
+    private readonly SemaphoreSlim _gate = new(1, 1);
+    private readonly bool _leaveOpen;
+
+    public FrameWriter(Stream stream, bool leaveOpen = false)
+    {
+        _stream = stream ?? throw new ArgumentNullException(nameof(stream));
+        _leaveOpen = leaveOpen;
+    }
+
+    public async Task WriteAsync<T>(MessageKind kind, T message, CancellationToken ct)
+    {
+        var body = MessagePackSerializer.Serialize(message, cancellationToken: ct);
+        if (body.Length > Framing.MaxFrameBodyBytes)
+            throw new InvalidOperationException(
+                $"Sidecar IPC frame body {body.Length} exceeds {Framing.MaxFrameBodyBytes} byte cap.");
+
+        var lengthPrefix = new byte[Framing.LengthPrefixSize];
+        // Big-endian — easy to read in hex dumps.
+        lengthPrefix[0] = (byte)((body.Length >> 24) & 0xFF);
+        lengthPrefix[1] = (byte)((body.Length >> 16) & 0xFF);
+        lengthPrefix[2] = (byte)((body.Length >> 8)  & 0xFF);
+        lengthPrefix[3] = (byte)( body.Length        & 0xFF);
+
+        await _gate.WaitAsync(ct).ConfigureAwait(false);
+        try
+        {
+            await _stream.WriteAsync(lengthPrefix, 0, lengthPrefix.Length, ct).ConfigureAwait(false);
+            _stream.WriteByte((byte)kind);
+            await _stream.WriteAsync(body, 0, body.Length, ct).ConfigureAwait(false);
+            await _stream.FlushAsync(ct).ConfigureAwait(false);
+        }
+        finally { _gate.Release(); }
+    }
+
+    public void Dispose()
+    {
+        _gate.Dispose();
+        if (!_leaveOpen) _stream.Dispose();
+    }
+}

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Ipc/Framing.cs

@@ -0,0 +1,48 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Ipc;
+
+/// <summary>
+///     Length-prefixed framing constants for the Wonderware historian sidecar pipe protocol.
+///     Each frame on the wire is:
+///     <c>[4-byte big-endian length][1-byte message kind][MessagePack body]</c>.
+///     Length is the body size only; the kind byte is not part of the prefixed length.
+/// </summary>
+/// <remarks>
+///     Mirrors the Galaxy.Shared framing exactly so the same FrameReader/FrameWriter pattern
+///     works on both sides. The sidecar's protocol is independent — both the .NET 4.8 server
+///     side and the .NET 10 client (PR 3.4) carry their own copies of these constants and
+///     stay in sync via the round-trip test matrix.
+/// </remarks>
+public static class Framing
+{
+    public const int LengthPrefixSize = 4;
+    public const int KindByteSize = 1;
+
+    /// <summary>16 MiB cap protects the receiver from a hostile or buggy peer.</summary>
+    public const int MaxFrameBodyBytes = 16 * 1024 * 1024;
+}
+
+/// <summary>
+///     Wire identifier for each historian sidecar message. Values are stable — never reorder;
+///     append new contracts at the end. The .NET 10 client and the .NET 4.8 sidecar must
+///     agree on every value here.
+/// </summary>
+public enum MessageKind : byte
+{
+    Hello                       = 0x01,
+    HelloAck                    = 0x02,
+
+    ReadRawRequest              = 0x10,
+    ReadRawReply                = 0x11,
+
+    ReadProcessedRequest        = 0x12,
+    ReadProcessedReply          = 0x13,
+
+    ReadAtTimeRequest           = 0x14,
+    ReadAtTimeReply             = 0x15,
+
+    ReadEventsRequest           = 0x16,
+    ReadEventsReply             = 0x17,
+
+    WriteAlarmEventsRequest     = 0x20,
+    WriteAlarmEventsReply       = 0x21,
+}

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Ipc/Hello.cs

@@ -0,0 +1,32 @@
+using MessagePack;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Ipc;
+
+/// <summary>
+///     First frame of every connection. Advertises the sidecar protocol version and the
+///     per-process shared secret the supervisor passed at spawn time.
+/// </summary>
+[MessagePackObject]
+public sealed class Hello
+{
+    public const int CurrentMajor = 1;
+    public const int CurrentMinor = 0;
+
+    [Key(0)] public int ProtocolMajor { get; set; } = CurrentMajor;
+    [Key(1)] public int ProtocolMinor { get; set; } = CurrentMinor;
+    [Key(2)] public string PeerName { get; set; } = string.Empty;
+
+    /// <summary>Per-process shared secret — verified against the value the supervisor passed at spawn time.</summary>
+    [Key(3)] public string SharedSecret { get; set; } = string.Empty;
+}
+
+[MessagePackObject]
+public sealed class HelloAck
+{
+    [Key(0)] public int ProtocolMajor { get; set; } = Hello.CurrentMajor;
+    [Key(1)] public int ProtocolMinor { get; set; } = Hello.CurrentMinor;
+
+    [Key(2)] public bool Accepted { get; set; }
+    [Key(3)] public string? RejectReason { get; set; }
+    [Key(4)] public string HostName { get; set; } = string.Empty;
+}

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Ipc/HistorianFrameHandler.cs

@@ -0,0 +1,250 @@
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using MessagePack;
+using Serilog;
+using ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Ipc;
+
+/// <summary>
+///     Sidecar-side dispatcher. Each post-Hello frame routes by <see cref="MessageKind"/> to
+///     the right historian operation and the result frame is written back through the same
+///     pipe. Per-call exceptions are caught and surfaced as <c>Success=false, Error=...</c>
+///     replies so a single bad request doesn't kill the connection.
+/// </summary>
+public sealed class HistorianFrameHandler : IFrameHandler
+{
+    private readonly IHistorianDataSource _historian;
+    private readonly IAlarmEventWriter? _alarmWriter;
+    private readonly ILogger _logger;
+
+    public HistorianFrameHandler(
+        IHistorianDataSource historian,
+        ILogger logger,
+        IAlarmEventWriter? alarmWriter = null)
+    {
+        _historian = historian ?? throw new ArgumentNullException(nameof(historian));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+        _alarmWriter = alarmWriter;
+    }
+
+    public Task HandleAsync(MessageKind kind, byte[] body, FrameWriter writer, CancellationToken ct)
+        => kind switch
+        {
+            MessageKind.ReadRawRequest => HandleReadRawAsync(body, writer, ct),
+            MessageKind.ReadProcessedRequest => HandleReadProcessedAsync(body, writer, ct),
+            MessageKind.ReadAtTimeRequest => HandleReadAtTimeAsync(body, writer, ct),
+            MessageKind.ReadEventsRequest => HandleReadEventsAsync(body, writer, ct),
+            MessageKind.WriteAlarmEventsRequest => HandleWriteAlarmEventsAsync(body, writer, ct),
+            _ => UnknownAsync(kind),
+        };
+
+    private Task UnknownAsync(MessageKind kind)
+    {
+        _logger.Warning("Sidecar received unsupported frame kind {Kind}; dropping", kind);
+        return Task.CompletedTask;
+    }
+
+    private async Task HandleReadRawAsync(byte[] body, FrameWriter writer, CancellationToken ct)
+    {
+        var req = MessagePackSerializer.Deserialize<ReadRawRequest>(body);
+        var reply = new ReadRawReply { CorrelationId = req.CorrelationId };
+        try
+        {
+            var samples = await _historian.ReadRawAsync(
+                req.TagName,
+                new DateTime(req.StartUtcTicks, DateTimeKind.Utc),
+                new DateTime(req.EndUtcTicks, DateTimeKind.Utc),
+                req.MaxValues,
+                ct).ConfigureAwait(false);
+
+            reply.Success = true;
+            reply.Samples = ToWire(samples);
+        }
+        catch (Exception ex)
+        {
+            _logger.Warning(ex, "Sidecar ReadRaw failed for {Tag}", req.TagName);
+            reply.Success = false;
+            reply.Error = ex.Message;
+        }
+
+        await writer.WriteAsync(MessageKind.ReadRawReply, reply, ct).ConfigureAwait(false);
+    }
+
+    private async Task HandleReadProcessedAsync(byte[] body, FrameWriter writer, CancellationToken ct)
+    {
+        var req = MessagePackSerializer.Deserialize<ReadProcessedRequest>(body);
+        var reply = new ReadProcessedReply { CorrelationId = req.CorrelationId };
+        try
+        {
+            var buckets = await _historian.ReadAggregateAsync(
+                req.TagName,
+                new DateTime(req.StartUtcTicks, DateTimeKind.Utc),
+                new DateTime(req.EndUtcTicks, DateTimeKind.Utc),
+                req.IntervalMs,
+                req.AggregateColumn,
+                ct).ConfigureAwait(false);
+
+            reply.Success = true;
+            reply.Buckets = ToWire(buckets);
+        }
+        catch (Exception ex)
+        {
+            _logger.Warning(ex, "Sidecar ReadProcessed failed for {Tag}", req.TagName);
+            reply.Success = false;
+            reply.Error = ex.Message;
+        }
+
+        await writer.WriteAsync(MessageKind.ReadProcessedReply, reply, ct).ConfigureAwait(false);
+    }
+
+    private async Task HandleReadAtTimeAsync(byte[] body, FrameWriter writer, CancellationToken ct)
+    {
+        var req = MessagePackSerializer.Deserialize<ReadAtTimeRequest>(body);
+        var reply = new ReadAtTimeReply { CorrelationId = req.CorrelationId };
+        try
+        {
+            var timestamps = new DateTime[req.TimestampsUtcTicks.Length];
+            for (var i = 0; i < timestamps.Length; i++)
+                timestamps[i] = new DateTime(req.TimestampsUtcTicks[i], DateTimeKind.Utc);
+
+            var samples = await _historian.ReadAtTimeAsync(req.TagName, timestamps, ct).ConfigureAwait(false);
+            reply.Success = true;
+            reply.Samples = ToWire(samples);
+        }
+        catch (Exception ex)
+        {
+            _logger.Warning(ex, "Sidecar ReadAtTime failed for {Tag}", req.TagName);
+            reply.Success = false;
+            reply.Error = ex.Message;
+        }
+
+        await writer.WriteAsync(MessageKind.ReadAtTimeReply, reply, ct).ConfigureAwait(false);
+    }
+
+    private async Task HandleReadEventsAsync(byte[] body, FrameWriter writer, CancellationToken ct)
+    {
+        var req = MessagePackSerializer.Deserialize<ReadEventsRequest>(body);
+        var reply = new ReadEventsReply { CorrelationId = req.CorrelationId };
+        try
+        {
+            var events = await _historian.ReadEventsAsync(
+                req.SourceName,
+                new DateTime(req.StartUtcTicks, DateTimeKind.Utc),
+                new DateTime(req.EndUtcTicks, DateTimeKind.Utc),
+                req.MaxEvents,
+                ct).ConfigureAwait(false);
+
+            reply.Success = true;
+            reply.Events = ToWire(events);
+        }
+        catch (Exception ex)
+        {
+            _logger.Warning(ex, "Sidecar ReadEvents failed for source {Source}", req.SourceName);
+            reply.Success = false;
+            reply.Error = ex.Message;
+        }
+
+        await writer.WriteAsync(MessageKind.ReadEventsReply, reply, ct).ConfigureAwait(false);
+    }
+
+    private async Task HandleWriteAlarmEventsAsync(byte[] body, FrameWriter writer, CancellationToken ct)
+    {
+        var req = MessagePackSerializer.Deserialize<WriteAlarmEventsRequest>(body);
+        var reply = new WriteAlarmEventsReply { CorrelationId = req.CorrelationId };
+
+        if (_alarmWriter is null)
+        {
+            reply.Success = false;
+            reply.Error = "Sidecar not configured with an alarm-event writer.";
+            reply.PerEventOk = new bool[req.Events.Length];
+            await writer.WriteAsync(MessageKind.WriteAlarmEventsReply, reply, ct).ConfigureAwait(false);
+            return;
+        }
+
+        try
+        {
+            var perEvent = await _alarmWriter.WriteAsync(req.Events, ct).ConfigureAwait(false);
+            reply.PerEventOk = perEvent;
+            reply.Success = true;
+            // Whole-batch Success stays true even when some events failed — per-event
+            // PerEventOk slots carry the granular result; the SQLite drain worker treats
+            // false slots as retry-please candidates.
+        }
+        catch (Exception ex)
+        {
+            _logger.Warning(ex, "Sidecar WriteAlarmEvents failed");
+            reply.Success = false;
+            reply.Error = ex.Message;
+            reply.PerEventOk = new bool[req.Events.Length];
+        }
+
+        await writer.WriteAsync(MessageKind.WriteAlarmEventsReply, reply, ct).ConfigureAwait(false);
+    }
+
+    private static HistorianSampleDto[] ToWire(List<HistorianSample> samples)
+    {
+        var dtos = new HistorianSampleDto[samples.Count];
+        for (var i = 0; i < samples.Count; i++)
+        {
+            var s = samples[i];
+            dtos[i] = new HistorianSampleDto
+            {
+                ValueBytes = s.Value is null ? null : MessagePackSerializer.Serialize(s.Value),
+                Quality = s.Quality,
+                TimestampUtcTicks = s.TimestampUtc.Ticks,
+            };
+        }
+        return dtos;
+    }
+
+    private static HistorianAggregateSampleDto[] ToWire(List<HistorianAggregateSample> samples)
+    {
+        var dtos = new HistorianAggregateSampleDto[samples.Count];
+        for (var i = 0; i < samples.Count; i++)
+        {
+            dtos[i] = new HistorianAggregateSampleDto
+            {
+                Value = samples[i].Value,
+                TimestampUtcTicks = samples[i].TimestampUtc.Ticks,
+            };
+        }
+        return dtos;
+    }
+
+    private static HistorianEventDto[] ToWire(List<Backend.HistorianEventDto> events)
+    {
+        var dtos = new HistorianEventDto[events.Count];
+        for (var i = 0; i < events.Count; i++)
+        {
+            var e = events[i];
+            dtos[i] = new HistorianEventDto
+            {
+                EventId = e.Id.ToString(),
+                Source = e.Source,
+                EventTimeUtcTicks = e.EventTime.Ticks,
+                ReceivedTimeUtcTicks = e.ReceivedTime.Ticks,
+                DisplayText = e.DisplayText,
+                Severity = e.Severity,
+            };
+        }
+        return dtos;
+    }
+}
+
+/// <summary>
+///     Strategy for persisting alarm events into the Wonderware Alarm &amp; Events log. PR 3.W
+///     supplies a real implementation that drives the aahClient SDK; PR 3.3 ships the
+///     contract + a default null implementation so the sidecar can boot without one.
+/// </summary>
+public interface IAlarmEventWriter
+{
+    /// <summary>
+    ///     Writes a batch of alarm events. Returns one boolean per input event indicating
+    ///     persisted vs. retry-please. The SQLite store-and-forward sink retries failed
+    ///     slots on the next drain tick.
+    /// </summary>
+    Task<bool[]> WriteAsync(AlarmHistorianEventDto[] events, CancellationToken cancellationToken);
+}

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Ipc/PipeAcl.cs

@@ -0,0 +1,36 @@
+using System;
+using System.IO.Pipes;
+using System.Security.AccessControl;
+using System.Security.Principal;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Ipc;
+
+/// <summary>
+///     Builds a strict <see cref="PipeSecurity"/> for the historian sidecar pipe — only the
+///     configured server-principal SID gets <c>ReadWrite | Synchronize</c>, LocalSystem is
+///     explicitly denied (unless it's the allowed principal itself), and the allowed SID owns
+///     the DACL. Mirrors the policy in Driver.Galaxy.Host's PipeAcl.
+/// </summary>
+public static class PipeAcl
+{
+    public static PipeSecurity Create(SecurityIdentifier allowedSid)
+    {
+        if (allowedSid is null) throw new ArgumentNullException(nameof(allowedSid));
+
+        var security = new PipeSecurity();
+
+        security.AddAccessRule(new PipeAccessRule(
+            allowedSid,
+            PipeAccessRights.ReadWrite | PipeAccessRights.Synchronize,
+            AccessControlType.Allow));
+
+        var localSystem = new SecurityIdentifier(WellKnownSidType.LocalSystemSid, null);
+        if (allowedSid != localSystem)
+            security.AddAccessRule(new PipeAccessRule(localSystem, PipeAccessRights.FullControl, AccessControlType.Deny));
+
+        // Owner = allowed SID so the deny rules can't be removed without write-DACL rights.
+        security.SetOwner(allowedSid);
+
+        return security;
+    }
+}

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Ipc/PipeServer.cs

@@ -0,0 +1,165 @@
+using System;
+using System.IO.Pipes;
+using System.Security.Principal;
+using System.Threading;
+using System.Threading.Tasks;
+using MessagePack;
+using Serilog;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Ipc;
+
+/// <summary>
+///     Accepts one client connection at a time on a named pipe with the strict ACL from
+///     <see cref="PipeAcl"/>. Verifies the peer SID and the per-process shared secret before
+///     any frame is dispatched. Mirrors Driver.Galaxy.Host's PipeServer; the sidecar carries
+///     its own copy so the deletion of Galaxy.Host in PR 7.2 leaves the sidecar self-contained.
+/// </summary>
+public sealed class PipeServer : IDisposable
+{
+    private readonly string _pipeName;
+    private readonly SecurityIdentifier _allowedSid;
+    private readonly string _sharedSecret;
+    private readonly ILogger _logger;
+    private readonly CancellationTokenSource _cts = new();
+    private NamedPipeServerStream? _current;
+
+    public PipeServer(string pipeName, SecurityIdentifier allowedSid, string sharedSecret, ILogger logger)
+    {
+        _pipeName = pipeName ?? throw new ArgumentNullException(nameof(pipeName));
+        _allowedSid = allowedSid ?? throw new ArgumentNullException(nameof(allowedSid));
+        _sharedSecret = sharedSecret ?? throw new ArgumentNullException(nameof(sharedSecret));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    /// <summary>
+    ///     Accepts one connection, performs Hello handshake, then dispatches frames to
+    ///     <paramref name="handler"/> until EOF or cancel. Returns when the client disconnects.
+    /// </summary>
+    public async Task RunOneConnectionAsync(IFrameHandler handler, CancellationToken ct)
+    {
+        using var linked = CancellationTokenSource.CreateLinkedTokenSource(_cts.Token, ct);
+        var acl = PipeAcl.Create(_allowedSid);
+
+        _current = new NamedPipeServerStream(
+            _pipeName,
+            PipeDirection.InOut,
+            maxNumberOfServerInstances: 1,
+            PipeTransmissionMode.Byte,
+            PipeOptions.Asynchronous,
+            inBufferSize: 64 * 1024,
+            outBufferSize: 64 * 1024,
+            pipeSecurity: acl);
+
+        try
+        {
+            await _current.WaitForConnectionAsync(linked.Token).ConfigureAwait(false);
+
+            using var reader = new FrameReader(_current, leaveOpen: true);
+            using var writer = new FrameWriter(_current, leaveOpen: true);
+
+            // First frame must be Hello with the correct shared secret. Reading it before
+            // the caller-SID impersonation check satisfies Windows' ERROR_CANNOT_IMPERSONATE
+            // rule — ImpersonateNamedPipeClient fails until at least one frame has been read.
+            var first = await reader.ReadFrameAsync(linked.Token).ConfigureAwait(false);
+            if (first is null || first.Value.Kind != MessageKind.Hello)
+            {
+                _logger.Warning("Sidecar IPC first frame was not Hello; dropping");
+                return;
+            }
+
+            if (!VerifyCaller(_current, out var reason))
+            {
+                _logger.Warning("Sidecar IPC caller rejected: {Reason}", reason);
+                _current.Disconnect();
+                return;
+            }
+
+            var hello = MessagePackSerializer.Deserialize<Hello>(first.Value.Body);
+            if (!string.Equals(hello.SharedSecret, _sharedSecret, StringComparison.Ordinal))
+            {
+                await writer.WriteAsync(MessageKind.HelloAck,
+                    new HelloAck { Accepted = false, RejectReason = "shared-secret-mismatch" },
+                    linked.Token).ConfigureAwait(false);
+                _logger.Warning("Sidecar IPC Hello rejected: shared-secret-mismatch");
+                return;
+            }
+
+            if (hello.ProtocolMajor != Hello.CurrentMajor)
+            {
+                await writer.WriteAsync(MessageKind.HelloAck,
+                    new HelloAck { Accepted = false, RejectReason = $"major-version-mismatch-peer={hello.ProtocolMajor}-server={Hello.CurrentMajor}" },
+                    linked.Token).ConfigureAwait(false);
+                _logger.Warning("Sidecar IPC Hello rejected: major mismatch peer={Peer} server={Server}",
+                    hello.ProtocolMajor, Hello.CurrentMajor);
+                return;
+            }
+
+            await writer.WriteAsync(MessageKind.HelloAck,
+                new HelloAck { Accepted = true, HostName = Environment.MachineName },
+                linked.Token).ConfigureAwait(false);
+
+            while (!linked.Token.IsCancellationRequested)
+            {
+                var frame = await reader.ReadFrameAsync(linked.Token).ConfigureAwait(false);
+                if (frame is null) break;
+
+                await handler.HandleAsync(frame.Value.Kind, frame.Value.Body, writer, linked.Token).ConfigureAwait(false);
+            }
+        }
+        finally
+        {
+            _current.Dispose();
+            _current = null;
+        }
+    }
+
+    /// <summary>
+    ///     Runs the server continuously, handling one connection at a time. When a connection
+    ///     ends (clean or error), accepts the next.
+    /// </summary>
+    public async Task RunAsync(IFrameHandler handler, CancellationToken ct)
+    {
+        while (!ct.IsCancellationRequested)
+        {
+            try { await RunOneConnectionAsync(handler, ct).ConfigureAwait(false); }
+            catch (OperationCanceledException) { break; }
+            catch (Exception ex) { _logger.Error(ex, "Sidecar IPC connection loop error — accepting next"); }
+        }
+    }
+
+    private bool VerifyCaller(NamedPipeServerStream pipe, out string reason)
+    {
+        try
+        {
+            pipe.RunAsClient(() =>
+            {
+                using var wi = WindowsIdentity.GetCurrent();
+                if (wi.User is null)
+                    throw new InvalidOperationException("GetCurrent().User is null — cannot verify caller");
+                if (wi.User != _allowedSid)
+                    throw new UnauthorizedAccessException(
+                        $"caller SID {wi.User.Value} does not match allowed {_allowedSid.Value}");
+            });
+            reason = string.Empty;
+            return true;
+        }
+        catch (Exception ex) { reason = ex.Message; return false; }
+    }
+
+    public void Dispose()
+    {
+        _cts.Cancel();
+        _current?.Dispose();
+        _cts.Dispose();
+    }
+}
+
+/// <summary>
+///     Strategy for handling each post-Hello frame the pipe server reads. Implementations
+///     deserialize the body per the <see cref="MessageKind"/>, dispatch to the historian, and
+///     write the corresponding reply through the supplied <see cref="FrameWriter"/>.
+/// </summary>
+public interface IFrameHandler
+{
+    Task HandleAsync(MessageKind kind, byte[] body, FrameWriter writer, CancellationToken ct);
+}

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Program.cs

@@ -0,0 +1,153 @@
+using System;
+using System.Security.Principal;
+using System.Threading;
+using Serilog;
+using ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend;
+using ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Ipc;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware;
+
+/// <summary>
+///     Entry point for the Wonderware Historian sidecar. Reads pipe name, allowed-SID,
+///     shared secret, and historian connection config from environment (the supervisor
+///     passes them at spawn time per <c>driver-stability.md</c>). Hosts a named-pipe server
+///     dispatching the five sidecar contracts (PR 3.3) to the Wonderware Historian SDK.
+/// </summary>
+public static class Program
+{
+    public static int Main(string[] args)
+    {
+        Log.Logger = new LoggerConfiguration()
+            .MinimumLevel.Information()
+            .WriteTo.File(
+                @"%ProgramData%\OtOpcUa\historian-wonderware-.log".Replace("%ProgramData%", Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData)),
+                rollingInterval: RollingInterval.Day)
+            .CreateLogger();
+
+        try
+        {
+            var pipeName = Environment.GetEnvironmentVariable("OTOPCUA_HISTORIAN_PIPE")
+                ?? throw new InvalidOperationException("OTOPCUA_HISTORIAN_PIPE not set — supervisor must pass the sidecar pipe name");
+            var allowedSidValue = Environment.GetEnvironmentVariable("OTOPCUA_ALLOWED_SID")
+                ?? throw new InvalidOperationException("OTOPCUA_ALLOWED_SID not set — supervisor must pass the server principal SID");
+            var sharedSecret = Environment.GetEnvironmentVariable("OTOPCUA_HISTORIAN_SECRET")
+                ?? throw new InvalidOperationException("OTOPCUA_HISTORIAN_SECRET not set — supervisor must pass the per-process secret at spawn time");
+
+            var allowedSid = new SecurityIdentifier(allowedSidValue);
+
+            using var cts = new CancellationTokenSource();
+            Console.CancelKeyPress += (_, e) => { e.Cancel = true; cts.Cancel(); };
+
+            // Sidecar can boot in "pipe-only" mode (no real Wonderware Historian SDK
+            // initialization) for smoke + IPC tests. Production sets ENABLED=true so the
+            // SDK opens its connection up front.
+            var historianEnabled = string.Equals(
+                Environment.GetEnvironmentVariable("OTOPCUA_HISTORIAN_ENABLED"),
+                "true", StringComparison.OrdinalIgnoreCase);
+
+            if (!historianEnabled)
+            {
+                Log.Information("Wonderware historian sidecar starting in pipe-only mode (OTOPCUA_HISTORIAN_ENABLED!=true) — pipe={Pipe} allowedSid={Sid}", pipeName, allowedSidValue);
+                cts.Token.WaitHandle.WaitOne();
+                Log.Information("Wonderware historian sidecar stopping cleanly");
+                return 0;
+            }
+
+            using var historian = BuildHistorian();
+            var alarmWriter = BuildAlarmWriter();
+            var handler = new HistorianFrameHandler(historian, Log.Logger, alarmWriter);
+            using var server = new PipeServer(pipeName, allowedSid, sharedSecret, Log.Logger);
+
+            Log.Information("Wonderware historian sidecar serving — pipe={Pipe} allowedSid={Sid}", pipeName, allowedSidValue);
+            try { server.RunAsync(handler, cts.Token).GetAwaiter().GetResult(); }
+            catch (OperationCanceledException) { /* clean shutdown via Ctrl-C */ }
+
+            Log.Information("Wonderware historian sidecar stopped cleanly");
+            return 0;
+        }
+        catch (Exception ex)
+        {
+            Log.Fatal(ex, "Wonderware historian sidecar fatal");
+            return 2;
+        }
+        finally { Log.CloseAndFlush(); }
+    }
+
+    /// <summary>
+    ///     Builds the Wonderware Historian data source from environment variables. Mirrors
+    ///     the env-var contract that <c>Driver.Galaxy.Host</c> used in v1; PR 3.W reaffirms
+    ///     this contract in install scripts.
+    /// </summary>
+    private static HistorianDataSource BuildHistorian()
+    {
+        var cfg = new HistorianConfiguration
+        {
+            Enabled = true,
+            ServerName = Environment.GetEnvironmentVariable("OTOPCUA_HISTORIAN_SERVER") ?? "localhost",
+            Port = TryParseInt("OTOPCUA_HISTORIAN_PORT", 32568),
+            IntegratedSecurity = !string.Equals(Environment.GetEnvironmentVariable("OTOPCUA_HISTORIAN_INTEGRATED"), "false", StringComparison.OrdinalIgnoreCase),
+            UserName = Environment.GetEnvironmentVariable("OTOPCUA_HISTORIAN_USER"),
+            Password = Environment.GetEnvironmentVariable("OTOPCUA_HISTORIAN_PASS"),
+            CommandTimeoutSeconds = TryParseInt("OTOPCUA_HISTORIAN_TIMEOUT_SEC", 30),
+            MaxValuesPerRead = TryParseInt("OTOPCUA_HISTORIAN_MAX_VALUES", 10000),
+            FailureCooldownSeconds = TryParseInt("OTOPCUA_HISTORIAN_COOLDOWN_SEC", 60),
+        };
+
+        var servers = Environment.GetEnvironmentVariable("OTOPCUA_HISTORIAN_SERVERS");
+        if (!string.IsNullOrWhiteSpace(servers))
+            cfg.ServerNames = new System.Collections.Generic.List<string>(
+                servers.Split(new[] { ',' }, StringSplitOptions.RemoveEmptyEntries));
+
+        Log.Information("Sidecar Historian config — {NodeCount} node(s), port={Port}",
+            cfg.ServerNames.Count > 0 ? cfg.ServerNames.Count : 1, cfg.Port);
+        return new HistorianDataSource(cfg);
+    }
+
+    private static int TryParseInt(string envName, int defaultValue)
+    {
+        var raw = Environment.GetEnvironmentVariable(envName);
+        return int.TryParse(raw, out var parsed) ? parsed : defaultValue;
+    }
+
+    /// <summary>
+    ///     Constructs the alarm-event writer when the alarm-write toggle is on, otherwise
+    ///     returns <c>null</c> so <see cref="HistorianFrameHandler"/> falls back to the
+    ///     "not configured" reply for any incoming <c>WriteAlarmEvents</c> frame.
+    ///     Default is <c>true</c> when <c>OTOPCUA_HISTORIAN_ENABLED=true</c>; explicitly
+    ///     set <c>OTOPCUA_HISTORIAN_ALARM_WRITE_ENABLED=false</c> to keep a read-only
+    ///     deployment that still loads the SDK for reads.
+    /// </summary>
+    internal static IAlarmEventWriter? BuildAlarmWriter()
+    {
+        var raw = Environment.GetEnvironmentVariable("OTOPCUA_HISTORIAN_ALARM_WRITE_ENABLED");
+        var enabled = string.IsNullOrWhiteSpace(raw)
+            ? true
+            : !string.Equals(raw, "false", StringComparison.OrdinalIgnoreCase);
+
+        if (!enabled)
+        {
+            Log.Information("Alarm-event writer disabled (OTOPCUA_HISTORIAN_ALARM_WRITE_ENABLED=false); historian sidecar will reject WriteAlarmEvents frames.");
+            return null;
+        }
+
+        var cfg = BuildAlarmWriterConfig();
+        var backend = new SdkAlarmHistorianWriteBackend(cfg);
+        Log.Information("Alarm-event writer enabled — backend=SdkAlarmHistorianWriteBackend server={Server}", cfg.ServerName);
+        return new AahClientManagedAlarmEventWriter(backend);
+    }
+
+    private static HistorianConfiguration BuildAlarmWriterConfig()
+    {
+        return new HistorianConfiguration
+        {
+            Enabled = true,
+            ServerName = Environment.GetEnvironmentVariable("OTOPCUA_HISTORIAN_SERVER") ?? "localhost",
+            Port = TryParseInt("OTOPCUA_HISTORIAN_PORT", 32568),
+            IntegratedSecurity = !string.Equals(Environment.GetEnvironmentVariable("OTOPCUA_HISTORIAN_INTEGRATED"), "false", StringComparison.OrdinalIgnoreCase),
+            UserName = Environment.GetEnvironmentVariable("OTOPCUA_HISTORIAN_USER"),
+            Password = Environment.GetEnvironmentVariable("OTOPCUA_HISTORIAN_PASS"),
+            CommandTimeoutSeconds = TryParseInt("OTOPCUA_HISTORIAN_TIMEOUT_SEC", 30),
+            FailureCooldownSeconds = TryParseInt("OTOPCUA_HISTORIAN_COOLDOWN_SEC", 60),
+        };
+    }
+}

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

@@ -0,0 +1,71 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <OutputType>Exe</OutputType>
+        <TargetFramework>net48</TargetFramework>
+        <!-- x64 — AVEVA Historian 2020 ships an x64 build of aahClientManaged + the native
+             aahClient.dll under the Historian install's x64\ subfolder. The other three
+             SDK assemblies (Historian.CBE / DPAPI / ArchestrA.CloudHistorian.Contract) are
+             pure-managed AnyCPU and load fine in either bitness. The earlier x86 default
+             was inherited from v1's Galaxy.Host bitness (MXAccess COM, retired in PR 7.2)
+             and didn't reflect any constraint of the Historian SDK itself. -->
+        <PlatformTarget>x64</PlatformTarget>
+        <Nullable>enable</Nullable>
+        <LangVersion>latest</LangVersion>
+        <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
+        <NoWarn>$(NoWarn);CS1591</NoWarn>
+        <RootNamespace>ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware</RootNamespace>
+        <AssemblyName>OtOpcUa.Driver.Historian.Wonderware</AssemblyName>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="MessagePack" Version="2.5.187"/>
+        <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>
+
+    <ItemGroup>
+        <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>