fix(opcua,drivers): carry driver status sub-codes to clients (#519) + health-write ordering (#517)

#519 — a driver's OPC UA status code now reaches a client with its sub-code intact.
DriverInstanceActor projected the driver's uint onto a 3-state Good/Uncertain/Bad enum
and OtOpcUaNodeManager re-expanded Bad to a bare 0x80000000, so BadNoCommunication,
BadTypeMismatch and BadNotSupported were indistinguishable on the wire and every
driver's status constants (incl. the 16 #497 had just corrected) were diagnostic in
logs only. Resolved by option (b): the raw uint rides AttributeValuePublished ->
AttributeValueUpdate -> IOpcUaAddressSpaceSink.WriteValue, OpcUaQuality is deleted, and
severity classification is a helper (OpcUaStatus.IsGood/IsUncertain/IsBad).

The surface was wider than the issue costed (41 files, not "the sink and 3
implementations"): OpcUaQuality had non-driver producers with no uint to carry.
Each got its natural code — BadInternalError for a failed virtual-tag script,
BadNoCommunication for driver comms loss — and ScriptedAlarmHostActor's pair of
mutually-inverse uint<->enum mappers is deleted, having round-tripped a code the
engine already held. AddressSpaceApplier's removal writes deliberately keep the
generic Bad: not losing a code the driver had is this issue; inventing one for the
deploy path is a separate call.

Behaviour change: WriteAlarmQuality fires its Part 9 event on a status-code change
rather than a severity-bucket change. While the annotation was 3-state those were the
same predicate; now a move between two Bad reasons changes what a subscriber reads.

New SDK-free named constants live on Commons.OpcUa.OpcUaStatus, and
StatusCodeParityTests is widened to cover them — that guard is reflection-driven, so
it can only see a named constant, never an inline literal.

#517 — the symptom is real but the issue named the wrong path and its fix was unsafe.
ShutdownAsync cannot race: DriverInstanceActor calls it from PostStop, after the
mailbox drains. (Core/Hosting/DriverHost, the one class with a concurrent GetHealth,
has no production call site.) InitializeAsync can: it runs on a fire-and-forget
Task.Run, and MTConnectDriver writes Healthy then starts loops that can throw into a
catch which disposes the client before writing Faulted.

Moving the write earlier, as suggested, inverts the terminal state — teardown drains
in-flight loops that write health as they unwind, so a late loop could leave Healthy at
rest with every connection closed. The fix is a bracket (conservative before, terminal
after), applied to MTConnect's init-failure path only; shutdown keeps its single
trailing write, and the rule plus the reachability table are documented on
IDriver.ShutdownAsync.

CalculationDriver.GetHealth returned a hard-coded Healthy that consulted nothing —
Healthy before initialize, after shutdown and after dispose. Now derived from _running.
Its test, named Health_is_always_Connected, asserted the defect and is replaced.

Every new guard was falsified by breaking the production code and watching it go red.
The two sub-code tests each assert two different Bad codes, since a single-code
assertion could pass against a hard-coded constant under the old projection.

Pre-existing failures, verified unchanged on a stashed tree and not chased: 4 in
Driver.AbLegacy.IntegrationTests (slc500/micrologix/plc5 fixtures not up) and 3 in
Host.IntegrationTests.

Closes #517
Closes #519

Claude-Session: https://claude.ai/code/session_015p7wGqy3YpZNCpDzTpGMKo

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Calculation.Tests/CalculationDriverTests.cs

@@ -158,12 +158,10 @@ public sealed class CalculationDriverTests
         after[0].Value.ShouldBe(6.0);
     }
 
-    [Fact]
-    public void Health_is_always_Connected()
-    {
-        var (driver, _, _) = Build(CalcTag("calc/e/x", "return 1.0;"));
-        driver.GetHealth().State.ShouldBe(DriverState.Healthy);
-    }
+    // REMOVED (Gitea #517): `Health_is_always_Connected` asserted that a driver which had never been
+    // initialized still reported Healthy — a characterization test of the defect, not of a requirement.
+    // Its valid half (a running Calculation driver has no transport to be Degraded about, so it is simply
+    // Healthy) is covered by GetHealth_tracks_the_lifecycle_rather_than_reporting_a_constant below.
 
     private static async Task<bool> WaitUntil(Func<bool> predicate, TimeSpan timeout)
     {
@@ -176,6 +174,41 @@ public sealed class CalculationDriverTests
         return predicate();
     }
 
+    // ── health lifecycle (Gitea #517) ─────────────────────────────────────────────────────────
+
+    /// <summary>
+    ///     Gitea #517 — <c>GetHealth()</c> must not report Healthy for a driver that is not running.
+    ///     <para>This driver returned a hard-coded <see cref="DriverState.Healthy"/> that consulted
+    ///     nothing, which made it the fleet's only driver reporting Healthy with its timers stopped —
+    ///     deterministically, not as a race window. Every other driver reads a <c>_health</c> field that
+    ///     shutdown lands on <see cref="DriverState.Unknown"/>.</para>
+    ///     <para>The pre-initialize leg is what makes this falsifiable against the old code: a test that
+    ///     only checked post-shutdown could be satisfied by a driver that happened to write Unknown once,
+    ///     whereas asserting BOTH ends pins the value to the lifecycle flag.</para>
+    /// </summary>
+    [Fact]
+    public async Task GetHealth_tracks_the_lifecycle_rather_than_reporting_a_constant()
+    {
+        var (driver, _, _) = Build(CalcTag("calc/e/x", "return 1.0;"));
+
+        // Constructed but never initialized — nothing is computing, so Healthy would be a lie.
+        driver.GetHealth().State.ShouldBe(DriverState.Unknown);
+
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        driver.GetHealth().State.ShouldBe(DriverState.Healthy);
+
+        await driver.ShutdownAsync(TestContext.Current.CancellationToken);
+        driver.GetHealth().State.ShouldBe(DriverState.Unknown,
+            "timers are stopped and _running is false — the driver computes nothing");
+
+        // Re-initialize brings it back, so the flag is genuinely read each call rather than latched once.
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        driver.GetHealth().State.ShouldBe(DriverState.Healthy);
+
+        driver.Dispose();
+        driver.GetHealth().State.ShouldBe(DriverState.Unknown);
+    }
+
     private sealed class CapturingPublisher(List<ScriptLogEntry> sink) : IScriptLogPublisher
     {
         private readonly object _lock = new();

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Tests/CannedAgentClient.cs

@@ -434,6 +434,13 @@ internal sealed class CannedAgentClient : IMTConnectAgentClient, IDisposable
     ///         to release anything a test cares about.
     ///     </para>
     /// </remarks>
+    /// <summary>
+    ///     Invoked on the first <see cref="Dispose"/> only. Lets a test observe driver state at the exact
+    ///     instant the client becomes unusable — the window Gitea #517 is about, which is otherwise
+    ///     invisible because it has closed again by the time <c>InitializeAsync</c> returns.
+    /// </summary>
+    public Action? OnFirstDispose { get; set; }
+
     public void Dispose()
     {
         if (Interlocked.Increment(ref _disposeCount) > 1)
@@ -441,6 +448,7 @@ internal sealed class CannedAgentClient : IMTConnectAgentClient, IDisposable
             return;
         }
 
+        OnFirstDispose?.Invoke();
         _disposeCts.Cancel();
         Volatile.Read(ref _chunks).Writer.TryComplete();
     }

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Tests/MTConnectDriverLifecycleTests.cs

@@ -161,6 +161,41 @@ public sealed class MTConnectDriverLifecycleTests
         client.IsDisposed.ShouldBeTrue();
     }
 
+    /// <summary>
+    ///     Gitea #517 — the failed state must be published BEFORE the client is disposed, not after.
+    ///     <para>Every other test in this file asserts the state <em>once InitializeAsync has returned</em>,
+    ///     by which time the window has closed. That is why the defect survived: the terminal value was
+    ///     always right, and only the ordering was wrong. This samples <c>GetHealth()</c> from inside the
+    ///     client's Dispose, which is the moment the driver stops being able to serve anything.</para>
+    ///     <para>The window is reachable in production, which is what makes this worth pinning rather than
+    ///     a theoretical tidy-up: <c>DriverInstanceActor</c> runs <c>InitializeAsync</c> on a
+    ///     fire-and-forget <c>Task.Run</c>, so its health-poll tick keeps calling <c>GetHealth()</c> on the
+    ///     actor thread for the whole duration of the teardown.</para>
+    ///     <para>Falsifiable: remove the pre-teardown <c>WriteHealth</c> and the observed state reverts to
+    ///     <see cref="DriverState.Initializing"/> — the stale value written on entry.</para>
+    /// </summary>
+    [Fact]
+    public async Task Initialize_publishes_the_failed_state_before_disposing_the_client()
+    {
+        var (driver, client) = NewDriver();
+        client.ProbeFailure = new HttpRequestException("agent unreachable");
+
+        DriverState? stateAtDisposal = null;
+        client.OnFirstDispose = () => stateAtDisposal = driver.GetHealth().State;
+
+        await Should.ThrowAsync<HttpRequestException>(
+            () => driver.InitializeAsync("{}", CancellationToken.None));
+
+        client.IsDisposed.ShouldBeTrue("the test is vacuous unless the disposal actually happened");
+        stateAtDisposal.ShouldNotBeNull();
+        stateAtDisposal.ShouldBe(DriverState.Faulted,
+            "health must already report the failure when the client goes away — a caller polling " +
+            "GetHealth() during the teardown must never see a state that outlives the transport");
+
+        // And the terminal write still lands, so the resting state is right too.
+        driver.GetHealth().State.ShouldBe(DriverState.Faulted);
+    }
+
     [Fact]
     public async Task Initialize_faults_when_probe_succeeds_but_the_priming_current_fails()
     {