Phase 2 PR 12 — richer historian quality mapping. Replace MxAccessGalaxyBackend's inline MapHistorianQualityToOpcUa category-only helper (192+→Good, 64-191→Uncertain, 0-63→Bad) with a new public HistorianQualityMapper.Map utility that preserves specific OPC DA subcodes — BadNotConnected(8)→0x808A0000u instead of generic Bad(0x80000000u), UncertainSubNormal(88)→0x40950000u instead of generic Uncertain, Good_LocalOverride(216)→0x00D80000u instead of generic Good, etc. Mirrors v1 QualityMapper.MapToOpcUaStatusCode byte-for-byte without pulling in OPC UA types — the function returns uint32 literals that are the canonical OPC UA StatusCode wire encoding, surfaced directly as DataValueSnapshot.StatusCode on the Proxy side with no additional translation. Unknown subcodes fall back to the family category (255→Good, 150→Uncertain, 50→Bad) so a future SDK change that adds a quality code we don't map yet still gets a sensible bucket. GalaxyDataValue wire shape unchanged (StatusCode stays uint) — this is a pure fidelity upgrade on the Host side. Downstream callers (Admin UI status dashboard, OPC UA clients receiving historian samples) can now distinguish e.g. a transport outage (BadNotConnected) from a sensor fault (BadSensorFailure) from a warm-up delay (BadWaitingForInitialData) without a second round-trip or dashboard heuristic. 21 new tests (HistorianQualityMapperTests): theory with 15 rows covering every specific mapping from the v1 QualityMapper table, plus 6 fallback tests verifying unknown-subcode codes in each family (Good/Uncertain/Bad) collapse to the family default. Galaxy.Host.Tests Unit suite 56/0 (21 new + 35 existing). Galaxy.Host builds clean (0/0). Branches off v2.

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

src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/DriverAttributeInfo.cs

@@ -19,10 +19,17 @@ namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;
 /// <param name="ArrayDim">Declared array length when <see cref="IsArray"/> is true; null otherwise.</param>
 /// <param name="SecurityClass">Write-authorization tier for this attribute.</param>
 /// <param name="IsHistorized">True when this attribute is expected to feed historian / HistoryRead.</param>
+/// <param name="IsAlarm">
+///     True when this attribute represents an alarm condition (Galaxy: has an
+///     <c>AlarmExtension</c> primitive). The generic node-manager enriches the variable with an
+///     OPC UA <c>AlarmConditionState</c> when true. Defaults to false so existing non-Galaxy
+///     drivers aren't forced to flow a flag they don't produce.
+/// </param>
 public sealed record DriverAttributeInfo(
     string FullName,
     DriverDataType DriverDataType,
     bool IsArray,
     uint? ArrayDim,
     SecurityClassification SecurityClass,
-    bool IsHistorized);
+    bool IsHistorized,
+    bool IsAlarm = false);

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

@@ -147,6 +147,7 @@ public sealed class DbBackedGalaxyBackend(GalaxyRepository repository) : IGalaxy
         ArrayDim = row.ArrayDimension is int d and > 0 ? (uint)d : null,
         SecurityClassification = row.SecurityClassification,
         IsHistorized = row.IsHistorized,
+        IsAlarm = row.IsAlarm,
     };
 
     /// <summary>

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

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

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

@@ -67,6 +67,13 @@ public sealed class MxAccessClient : IDisposable
     public int SubscriptionCount => _subscriptions.Count;
     public int ReconnectCount => _reconnectCount;
 
+    /// <summary>
+    ///     Wonderware client identity used when registering with the LMXProxyServer. Surfaced so
+    ///     <see cref="Backend.MxAccessGalaxyBackend"/> can tag its <c>OnHostStatusChanged</c> IPC
+    ///     pushes with a stable gateway name per PR 8.
+    /// </summary>
+    public string ClientName => _clientName;
+
     /// <summary>Connects on the STA thread. Idempotent. Starts the reconnect monitor on first call.</summary>
     public async Task<int> ConnectAsync()
     {

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

@@ -34,16 +34,34 @@ public sealed class MxAccessGalaxyBackend : IGalaxyBackend, IDisposable
         _refToSubs = new(System.StringComparer.OrdinalIgnoreCase);
 
     public event System.EventHandler<OnDataChangeNotification>? OnDataChange;
-#pragma warning disable CS0067 // event not yet raised — alarm + host-status wire-up in PR #4 follow-up
+#pragma warning disable CS0067 // alarm wire-up deferred to PR 9
     public event System.EventHandler<GalaxyAlarmEvent>? OnAlarmEvent;
-    public event System.EventHandler<HostConnectivityStatus>? OnHostStatusChanged;
 #pragma warning restore CS0067
+    public event System.EventHandler<HostConnectivityStatus>? OnHostStatusChanged;
+
+    private readonly System.EventHandler<bool> _onConnectionStateChanged;
 
     public MxAccessGalaxyBackend(GalaxyRepository repository, MxAccessClient mx, IHistorianDataSource? historian = null)
     {
         _repository = repository;
         _mx = mx;
         _historian = historian;
+
+        // PR 8: gateway-level host-status push. When the MXAccess COM proxy transitions
+        // connected↔disconnected, raise OnHostStatusChanged with a synthetic host entry named
+        // after the Wonderware client identity so the Admin UI surfaces top-level transport
+        // health even before per-platform/per-engine probing lands (deferred to a later PR that
+        // ports v1's GalaxyRuntimeProbeManager with ScanState subscriptions).
+        _onConnectionStateChanged = (_, connected) =>
+        {
+            OnHostStatusChanged?.Invoke(this, new HostConnectivityStatus
+            {
+                HostName = _mx.ClientName,
+                RuntimeStatus = connected ? "Running" : "Stopped",
+                LastObservedUtcUnixMs = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
+            });
+        };
+        _mx.ConnectionStateChanged += _onConnectionStateChanged;
     }
 
     public async Task<OpenSessionResponse> OpenSessionAsync(OpenSessionRequest req, CancellationToken ct)
@@ -309,7 +327,11 @@ public sealed class MxAccessGalaxyBackend : IGalaxyBackend, IDisposable
     public Task<RecycleStatusResponse> RecycleAsync(RecycleHostRequest req, CancellationToken ct)
         => Task.FromResult(new RecycleStatusResponse { Accepted = true, GraceSeconds = 15 });
 
-    public void Dispose() => _historian?.Dispose();
+    public void Dispose()
+    {
+        _mx.ConnectionStateChanged -= _onConnectionStateChanged;
+        _historian?.Dispose();
+    }
 
     private static GalaxyDataValue ToWire(string reference, Vtq vtq) => new()
     {
@@ -333,19 +355,11 @@ public sealed class MxAccessGalaxyBackend : IGalaxyBackend, IDisposable
         TagReference = reference,
         ValueBytes = sample.Value is null ? null : MessagePackSerializer.Serialize(sample.Value),
         ValueMessagePackType = 0,
-        StatusCode = MapHistorianQualityToOpcUa(sample.Quality),
+        StatusCode = HistorianQualityMapper.Map(sample.Quality),
         SourceTimestampUtcUnixMs = new DateTimeOffset(sample.TimestampUtc, TimeSpan.Zero).ToUnixTimeMilliseconds(),
         ServerTimestampUtcUnixMs = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
     };
 
-    private static uint MapHistorianQualityToOpcUa(byte q)
-    {
-        // Category-only mapping — mirrors QualityMapper.MapToOpcUaStatusCode for the common ranges.
-        // The Proxy may refine this when it decodes the wire frame.
-        if (q >= 192) return 0x00000000u;       // Good
-        if (q >= 64) return 0x40000000u;        // Uncertain
-        return 0x80000000u;                     // Bad
-    }
 
     /// <summary>
     ///     Maps a <see cref="HistorianAggregateSample"/> (one aggregate bucket) to the IPC wire
@@ -370,6 +384,7 @@ public sealed class MxAccessGalaxyBackend : IGalaxyBackend, IDisposable
         ArrayDim = row.ArrayDimension is int d and > 0 ? (uint)d : null,
         SecurityClassification = row.SecurityClassification,
         IsHistorized = row.IsHistorized,
+        IsAlarm = row.IsAlarm,
     };
 
     private static string MapCategory(int categoryId) => categoryId switch

src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Proxy/GalaxyProxyDriver.cs

@@ -123,7 +123,8 @@ public sealed class GalaxyProxyDriver(GalaxyProxyOptions options)
                         IsArray: attr.IsArray,
                         ArrayDim: attr.ArrayDim,
                         SecurityClass: MapSecurity(attr.SecurityClassification),
-                        IsHistorized: attr.IsHistorized));
+                        IsHistorized: attr.IsHistorized,
+                        IsAlarm: attr.IsAlarm));
             }
         }
     }

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

@@ -30,6 +30,15 @@ public sealed class GalaxyAttributeInfo
     [Key(3)] public uint? ArrayDim { get; set; }
     [Key(4)] public int SecurityClassification { get; set; }
     [Key(5)] public bool IsHistorized { get; set; }
+
+    /// <summary>
+    ///     True when the attribute has an AlarmExtension primitive in the Galaxy repository
+    ///     (<c>primitive_definition.primitive_name = 'AlarmExtension'</c>). The generic
+    ///     node-manager uses this to enrich the variable's OPC UA node with an
+    ///     <c>AlarmConditionState</c> during address-space build. Added in PR 9 as the
+    ///     discovery-side foundation for the alarm event wire-up that follows in PR 10+.
+    /// </summary>
+    [Key(6)] public bool IsAlarm { get; set; }
 }
 
 [MessagePackObject]

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

@@ -0,0 +1,84 @@
+using System;
+using MessagePack;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Shared.Contracts;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests;
+
+[Trait("Category", "Unit")]
+public sealed class AlarmDiscoveryTests
+{
+    /// <summary>
+    ///     PR 9 — IsAlarm must survive the MessagePack round-trip at Key=6 position.
+    ///     Regression guard: any reorder of keys in GalaxyAttributeInfo would silently corrupt
+    ///     the flag in the wire payload since MessagePack encodes by key number, not field name.
+    /// </summary>
+    [Fact]
+    public void GalaxyAttributeInfo_IsAlarm_round_trips_true_through_MessagePack()
+    {
+        var input = new GalaxyAttributeInfo
+        {
+            AttributeName = "TankLevel",
+            MxDataType = 2,
+            IsArray = false,
+            ArrayDim = null,
+            SecurityClassification = 1,
+            IsHistorized = true,
+            IsAlarm = true,
+        };
+
+        var bytes = MessagePackSerializer.Serialize(input);
+        var decoded = MessagePackSerializer.Deserialize<GalaxyAttributeInfo>(bytes);
+
+        decoded.IsAlarm.ShouldBeTrue();
+        decoded.IsHistorized.ShouldBeTrue();
+        decoded.AttributeName.ShouldBe("TankLevel");
+    }
+
+    [Fact]
+    public void GalaxyAttributeInfo_IsAlarm_round_trips_false_through_MessagePack()
+    {
+        var input = new GalaxyAttributeInfo { AttributeName = "ColorRgb", IsAlarm = false };
+        var bytes = MessagePackSerializer.Serialize(input);
+        var decoded = MessagePackSerializer.Deserialize<GalaxyAttributeInfo>(bytes);
+        decoded.IsAlarm.ShouldBeFalse();
+    }
+
+    /// <summary>
+    ///     Wire-compat guard: payloads serialized before PR 9 (which omit Key=6) must still
+    ///     deserialize cleanly — MessagePack treats missing keys as default. This lets a newer
+    ///     Proxy talk to an older Host during a rolling upgrade without a crash.
+    /// </summary>
+    [Fact]
+    public void Pre_PR9_payload_without_IsAlarm_key_deserializes_with_default_false()
+    {
+        // Build a 6-field payload (keys 0..5) matching the pre-PR9 shape by serializing a
+        // stand-in class with the same key layout but no Key=6.
+        var pre = new PrePR9Shape
+        {
+            AttributeName = "Legacy",
+            MxDataType = 1,
+            IsArray = false,
+            ArrayDim = null,
+            SecurityClassification = 0,
+            IsHistorized = false,
+        };
+        var bytes = MessagePackSerializer.Serialize(pre);
+
+        var decoded = MessagePackSerializer.Deserialize<GalaxyAttributeInfo>(bytes);
+        decoded.AttributeName.ShouldBe("Legacy");
+        decoded.IsAlarm.ShouldBeFalse();
+    }
+
+    [MessagePackObject]
+    public sealed class PrePR9Shape
+    {
+        [Key(0)] public string AttributeName { get; set; } = string.Empty;
+        [Key(1)] public int MxDataType { get; set; }
+        [Key(2)] public bool IsArray { get; set; }
+        [Key(3)] public uint? ArrayDim { get; set; }
+        [Key(4)] public int SecurityClassification { get; set; }
+        [Key(5)] public bool IsHistorized { get; set; }
+    }
+}

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

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

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

@@ -0,0 +1,91 @@
+using System;
+using System.Collections.Concurrent;
+using System.Threading;
+using System.Threading.Tasks;
+using ArchestrA.MxAccess;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Backend;
+using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Backend.Galaxy;
+using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Backend.MxAccess;
+using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Sta;
+using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Shared.Contracts;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests;
+
+[Trait("Category", "Unit")]
+public sealed class HostStatusPushTests
+{
+    /// <summary>
+    ///     PR 8 — when MxAccessClient.ConnectionStateChanged fires false→true→false,
+    ///     MxAccessGalaxyBackend raises OnHostStatusChanged once per transition with
+    ///     HostName=ClientName, RuntimeStatus="Running"/"Stopped", and a timestamp.
+    ///     This is the gateway-level signal; per-platform ScanState probes are deferred.
+    /// </summary>
+    [Fact]
+    public async Task ConnectionStateChanged_raises_OnHostStatusChanged_with_gateway_name()
+    {
+        using var pump = new StaPump("Test.Sta");
+        await pump.WaitForStartedAsync();
+        var proxy = new FakeProxy();
+        var mx = new MxAccessClient(pump, proxy, "GatewayClient", new MxAccessClientOptions { AutoReconnect = false });
+        using var backend = new MxAccessGalaxyBackend(
+            new GalaxyRepository(new GalaxyRepositoryOptions { ConnectionString = "Server=.;Database=ZB;Integrated Security=True;" }),
+            mx,
+            historian: null);
+
+        var notifications = new ConcurrentQueue<HostConnectivityStatus>();
+        backend.OnHostStatusChanged += (_, s) => notifications.Enqueue(s);
+
+        await mx.ConnectAsync();
+        await mx.DisconnectAsync();
+
+        notifications.Count.ShouldBe(2);
+        notifications.TryDequeue(out var first).ShouldBeTrue();
+        first!.HostName.ShouldBe("GatewayClient");
+        first.RuntimeStatus.ShouldBe("Running");
+        first.LastObservedUtcUnixMs.ShouldBeGreaterThan(0);
+
+        notifications.TryDequeue(out var second).ShouldBeTrue();
+        second!.HostName.ShouldBe("GatewayClient");
+        second.RuntimeStatus.ShouldBe("Stopped");
+    }
+
+    [Fact]
+    public async Task Dispose_unsubscribes_so_post_dispose_state_changes_do_not_fire_events()
+    {
+        using var pump = new StaPump("Test.Sta");
+        await pump.WaitForStartedAsync();
+        var proxy = new FakeProxy();
+        var mx = new MxAccessClient(pump, proxy, "GatewayClient", new MxAccessClientOptions { AutoReconnect = false });
+        var backend = new MxAccessGalaxyBackend(
+            new GalaxyRepository(new GalaxyRepositoryOptions { ConnectionString = "Server=.;Database=ZB;Integrated Security=True;" }),
+            mx,
+            historian: null);
+
+        var count = 0;
+        backend.OnHostStatusChanged += (_, _) => Interlocked.Increment(ref count);
+
+        await mx.ConnectAsync();
+        count.ShouldBe(1);
+
+        backend.Dispose();
+        await mx.DisconnectAsync();
+
+        count.ShouldBe(1); // no second notification after Dispose
+    }
+
+    private sealed class FakeProxy : IMxProxy
+    {
+        private int _next = 1;
+        public int Register(string _) => 42;
+        public void Unregister(int _) { }
+        public int AddItem(int _, string __) => Interlocked.Increment(ref _next);
+        public void RemoveItem(int _, int __) { }
+        public void AdviseSupervisory(int _, int __) { }
+        public void UnAdviseSupervisory(int _, int __) { }
+        public void Write(int _, int __, object ___, int ____) { }
+        public event MxDataChangeHandler? OnDataChange { add { } remove { } }
+        public event MxWriteCompleteHandler? OnWriteComplete { add { } remove { } }
+    }
+}