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

docs/DriverLifecycle.md

@@ -176,6 +176,33 @@ calls `Publish` when a driver's health transitions. The published snapshot is
 consumed AdminUI-side and surfaced through the driver-status panel (read
 in-process by the AdminUI bridge rather than dialing its own hub).
 
+### Writing health around a teardown (Gitea #517)
+
+Two rules, and the second is the counter-intuitive one:
+
+1. **`GetHealth()` must report actual state, never a constant.** A hard-coded `Healthy` reports a
+   healthy driver before initialize and after shutdown alike. `CalculationDriver` did exactly this —
+   it was the fleet's one driver reporting Healthy with its timers stopped, deterministically rather
+   than as a race. A driver with no transport still has a running / not-running distinction.
+
+2. **Land the terminal health value *after* the teardown — and, where the window is observable, write
+   it *before* as well.** #517's original suggestion was to move the write earlier so the race window
+   leans conservative. Moving it is wrong: teardown drains in-flight poll/probe loops, and those loops
+   write health as they unwind, so a driver that only wrote first could have a late loop overwrite the
+   shutdown state with `Healthy` and leave *that* as the resting value — with every connection closed.
+   The safe shape is a **bracket**: conservative value before, terminal value after.
+
+Where the window is actually observable is worth knowing before adding brackets everywhere:
+
+| Path | Caller | Can `GetHealth()` land mid-teardown? |
+|---|---|---|
+| `ShutdownAsync` | `DriverInstanceActor.PostStop` | **No** — actor thread, after the mailbox drains, so the health poll is serialised against it. |
+| `InitializeAsync` failure | `DriverInstanceActor.InitializeAsync` | **Yes** — invoked on a fire-and-forget `Task.Run`, so the health-poll tick keeps calling `GetHealth()` throughout. |
+
+So a driver whose `InitializeAsync` disposes anything on its failure path must bracket; only
+`MTConnectDriver` does today, because it is the only one that tears down inside a `catch`. The
+shutdown paths deliberately keep the single trailing write.
+
 ---
 
 ## IDriverConfigEditor — custom AdminUI config editor (plug-point)

docs/ReadWriteOperations.md

@@ -28,6 +28,25 @@ invoker is real, but it lives on the **driver-actor** side wrapping the poll/sub
 
 1. The SDK resolves the NodeId in the Raw (`ns=2`) or UNS (`ns=3`) namespace.
 2. It returns the cached `DataValue` — value, `StatusCode` and source timestamp as last pushed.
+
+### Status codes reach the client intact (Gitea #519)
+
+The driver's OPC UA status code — **sub-code included** — is what a client reads. A driver that maps
+an unreachable device to `BadNoCommunication` surfaces exactly that, distinguishable from
+`BadTypeMismatch` or `BadNotSupported`.
+
+This was not always true. Until #519 the publish path projected the driver's `uint` onto a 3-state
+`Good`/`Uncertain`/`Bad` enum in `DriverInstanceActor`, and `OtOpcUaNodeManager` re-expanded `Bad` to
+a bare `StatusCodes.Bad` (`0x80000000`). Every driver's diagnostic intent survived in logs only —
+including the 16 status constants #497 had just corrected across six drivers. The value path now
+carries the raw `uint` end to end (`AttributeValuePublished` → `AttributeValueUpdate` →
+`IOpcUaAddressSpaceSink.WriteValue`), and severity classification is a helper
+(`OpcUaStatus.IsGood`/`IsUncertain`/`IsBad`) rather than a lossy projection.
+
+**Writing a status code in engine code:** use a named constant on
+`ZB.MOM.WW.OtOpcUa.Commons.OpcUa.OpcUaStatus`, never an inline literal. Commons and Runtime are
+deliberately SDK-free, so nothing but `StatusCodeParityTests` checks a literal against the name it is
+commented with — and that guard works by reflection, so it can only see a **named** constant.
 3. **No authorization check runs.** Not a per-node ACL, not a role check, nothing. Any admitted
    session — including an Anonymous one — can read every node in the address space. The only gating is
    the `AccessLevels` bitmask set at materialization, which is a per-node *capability* declaration, not