feat(galaxy): handle the replay-gap sentinel and sparse-array values

Closes the two follow-ups left open by the MxGateway 0.2.0 bump. Reading the
gateway's own contract first changed what each of them is, and one of my earlier
claims was simply wrong -- both corrections are recorded below.

Replay gap
----------
A sentinel MxEvent carries family = UNSPECIFIED, so it fell through EventPump's
family switch into the default drop: we silently ignored a documented MUST ("you
missed events -- discard local state and re-snapshot"). It is now intercepted and
answered by re-issuing SubscribeBulk for every tracked subscription, since
MXAccess delivers an initial value per item on subscribe -- re-subscribing IS the
re-snapshot. It does not restart the event pump (the stream carrying the sentinel
is healthy, and the handler runs on that stream's own read loop, so disposing the
pump from there would deadlock on itself), it does not block the read loop, and
re-entry is gated so a burst collapses to one pass instead of a subscribe storm
per sentinel.

Handled on the READ loop, not in the dispatch loop, because everything past that
point is subject to newest-dropped channel pressure -- and "you missed events" is
the one signal whose loss is unrecoverable. Pinned by a test that fills the
channel and still expects the sentinel.

⚠️ This cannot fire in the shipped configuration, and I did not pretend otherwise
or paper over it by enabling resume. The gateway emits the sentinel only for a
stream opened with after_worker_sequence > 0; GatewayGalaxySubscriber passes 0,
which the gateway treats as "fresh stream, not a resume -- plain attach, no
replay, no sentinel". Enabling resume is a larger and genuinely delicate change:
the sequence is only meaningful within ONE gateway session, our reconnect
recreates the session, and replaying a remembered sequence against a fresh
session sets the server's live watermark ABOVE every event it is about to send --
silencing the stream instead of recovering it. That deserves its own change with
a live gate, which I cannot run from here.

Sparse arrays -- correcting the last commit message
---------------------------------------------------
I wrote that the bump "makes handling it possible" on the decode path. That is
wrong: MxSparseArray is documented write-only, the gateway expands it before
forwarding, and "the worker never receives or produces it". So the decode path
is unreachable by contract and the write path has no use for it either -- it is a
wire compaction for a WHOLE-array write, not a partial update (unmentioned
indices are RESET, deliberately, because the gateway cannot read-modify-write
without racing the provider). It is therefore the wrong primitive for an OPC UA
IndexRange write, which expects untouched elements preserved -- and WriteRequest
carries no IndexRange in the first place.

It is decoded anyway, as contract defence: the alternative if a future gateway
ever emits one is a silent null published under Good quality. Fill semantics
mirror the gateway's own SparseArrayExpander exactly (epoch for Time, empty
string, Integer widening to long[] when any element is int64) so a value that
round-trips through a write reads back as the same CLR array.

Also: the decoder is now total by contract, since it runs inside the dispatch
loop where an escaping exception kills dispatch for the life of the pump. A
malformed payload degrades instead of throwing.

A real defect found in the same code
------------------------------------
A stream the GATEWAY completes -- a closed or evicted session -- ends the RPC
without an error, so nothing threw, the supervisor was never notified, and the
pump exited silently. GetHealth() kept reporting Healthy, which also means the
#527 comms-loss watchdog could never trip, because it requires a non-Healthy
state. The driver went permanently deaf with no signal anywhere. This one is
live, unlike the two above. Now reported as a fault; the falsification control is
the existing CleanShutdown_DoesNotInvokeOnStreamFault, since our own disposal
also ends the stream and must NOT be reported.

Value kinds we cannot represent are now counted and warned once rather than
published as an indistinguishable null. The status is deliberately NOT downgraded
to Bad: nothing can reach that branch today, and changing what an OPC UA client
sees for a live shape is not a change to make without a gate. The counter exists
so the next person has evidence instead of a guess.

Verified: 330 Galaxy tests green (12 new), plus Galaxy.Browser 21, Runtime 558,
Core 351; full solution builds 0 errors with the warning census unchanged. Every
new test was falsified first -- disabling the gap interception reds 3 of 4 (the
throwing-callback test passes vacuously when the callback never runs, by
construction), disabling sparse decode plus the representability signal reds all
7 decoder tests, and both were restored and re-verified green.

Docs: the Galaxy.Performance invariant was stated as received = dispatched +
dropped + in-flight, which this breaks -- a sentinel is received but never enters
the channel -- so it now reads + replay_gaps. Galaxy.md gains the three
operational notes; DriverLifecycle.md records that "reaches a non-Healthy state"
is an obligation a driver can silently fail to meet, which is the general shape
of the clean-end bug.

docs/DriverLifecycle.md

@@ -260,6 +260,16 @@ Two consequences worth knowing:
 - **A device that accepts a connection but serves no data will cycle**, reconnecting once per threshold.
   That is the correct reading of a broken device, it is rate-limited, and it is visible in the health
   snapshot's error count — but do not mistake it for a bug when reading logs.
+- ⚠️ **"Reaches a non-Healthy state" is an obligation on each driver, and a driver can fail to meet it
+  without failing anything.** Galaxy's entry in the survey above is "via its reconnect supervisor" — which
+  holds only for the paths that actually *reach* the supervisor. Its event stream could also end the way a
+  closed or evicted gateway session ends it: the gRPC call completes **without an error**, so nothing
+  throws, the supervisor was never told, health stayed `Healthy` — and a `Healthy` driver can never satisfy
+  conjunct 1, so the watchdog could not fire either. The driver went permanently deaf with nothing
+  reporting it anywhere (fixed in `EventPump`; see [Galaxy.md](drivers/Galaxy.md) §Operational Notes).
+  The general shape is worth carrying to the next driver: this watchdog only covers failures a driver
+  **notices**, so a silent-success termination path — a stream that ends cleanly, a poll loop that exits
+  without throwing — bypasses it entirely.
 
 **The reconnect retry now tears down before re-initialising.** `Reconnecting`'s `RetryConnect` calls
 `ShutdownAsync` before `InitializeAsync` — the sequence every driver's own `ReinitializeAsync` already

docs/drivers/Galaxy.md

@@ -109,3 +109,7 @@ The session-less alarm feed (`GatewayGalaxyAlarmFeed`) and alarm acknowledger (`
 - **MXAccess `ClientName` collisions**: two OtOpcUa instances sharing a `ClientName` cause the older Wonderware session to lose subscription state. Redundancy pairs (decision #149) enforce uniqueness via install scripts.
 - **Channel saturation**: `galaxy.events.dropped > 0` indicates `EventPump` is back-pressured. Raise `EventPumpChannelCapacity` or investigate downstream slowness in the server-side fan-out.
 - **Connectivity surface**: per-platform probe state is exposed through `IHostConnectivityProbe` and aggregated by the server's connectivity bus — there is no driver-private dashboard surface anymore. The Admin UI's Host Status panel is the consumer.
+- **A stream the gateway ends cleanly is treated as a fault.** A closed or evicted gateway session completes the `StreamEvents` RPC *without an error*, so nothing throws. `EventPump` reports that to the `ReconnectSupervisor` exactly as it reports a transport fault. Before this it exited silently: the supervisor was never told, `GetHealth()` kept reporting `Healthy`, and because the [comms-loss watchdog](../DriverLifecycle.md) requires a **non-Healthy** state to trip, it never fired either — the driver went permanently deaf with no signal anywhere. Nothing else in the system can observe this, so do not remove the notification on the grounds that "a clean end isn't an error".
+- **Replay gaps** (`galaxy.events.replay_gaps`): the gateway signals that events were evicted from its replay ring before we could read them. The driver responds by re-issuing `SubscribeBulk` for every tracked subscription — MXAccess delivers an initial value per item on subscribe, so re-subscribing *is* the re-snapshot the contract asks for. It does **not** restart the event pump (the stream carrying the sentinel is healthy) and it honours `Reconnect:ReplayOnSessionLost=false` by logging and standing down, on the grounds that an operator who delegated recovery to the gateway did not ask for a re-subscribe on a different trigger.
+  ⚠️ This cannot currently fire: the sentinel is only emitted on a stream opened with `after_worker_sequence > 0`, and the driver opens with `0`, which the gateway treats as "fresh stream, not a resume". Enabling resume is a bigger change than it looks — the sequence is only meaningful **within one gateway session**, and the reconnect path recreates the session, so a remembered sequence replayed against a fresh session would set the server's live watermark *above* every event it is about to send, silencing the stream rather than recovering it.
+- **Undecodable values** (`galaxy.events.undecodable`): a value kind this driver has no CLR representation for is published as a **null under the event's own quality**, not as Bad. The status is deliberately left alone — nothing can reach this branch today, so the counter exists to produce evidence before anyone changes what an OPC UA client sees.

docs/v2/Galaxy.Performance.md

@@ -38,14 +38,35 @@ the metrics surface instead.
 | `galaxy.events.received` | `{event}` | MxEvents read from the gateway StreamEvents stream |
 | `galaxy.events.dispatched` | `{event}` | MxEvents that made it through the bounded channel into `OnDataChange` |
 | `galaxy.events.dropped` | `{event}` | MxEvents discarded because the bounded channel was full (newest-dropped) |
+| `galaxy.events.replay_gaps` | `{gap}` | Replay-gap sentinels received — the gateway evicted events we can never see |
+| `galaxy.events.undecodable` | `{event}` | Data-change events carrying a value kind this driver cannot represent |
 
-The invariant is `received = dispatched + dropped + (in-flight in the
-channel)`. Watch the dropped counter — it is the leading indicator of
+The invariant is `received = dispatched + dropped + replay_gaps +
+(in-flight in the channel)`. A replay-gap sentinel is counted as
+received but never enters the channel — it is a control signal with no
+item payload, handled on the read loop precisely so channel pressure
+can never drop it.
+
+Watch the dropped counter — it is the leading indicator of
 listener back-pressure. A non-zero dropped rate means a downstream
 consumer (DriverNodeManager → UA notification queue → client) is
 slower than the gw event stream; investigate that consumer before
 raising `EventPump` channel capacity.
 
+`galaxy.events.replay_gaps` should be flat at zero, for a structural
+reason rather than a healthy one: the gateway only emits the sentinel on
+a stream opened with `after_worker_sequence > 0`, and the driver opens
+with `0` ("fresh stream, not a resume"). A non-zero value therefore means
+the resume path was enabled — each gap costs a full re-subscribe of every
+tag on the driver, so a climbing counter is a sizing problem, not just an
+observation.
+
+`galaxy.events.undecodable` should likewise be flat at zero: every
+`MxValue` kind the contract declares decodes today. Non-zero means the
+gateway shipped a new wire type and those readings are being published as
+**nulls under the event's own quality** — the status is deliberately not
+downgraded, so this counter is the only signal that it is happening.
+
 ### Bounded channel design
 
 The pump runs two background tasks: