2 Commits

Author	SHA1	Message	Date
Joseph Doherty	c51c59987b	fix(galaxy): publish an unrepresentable value as BadTypeMismatch, not a good null ... Reverses the conservative call from the previous commit at the user's direction, and they were right: "surface it on a counter first" left the wire lying. An MXAccess event can carry Good quality while its payload is a kind MxValueDecoder has no mapping for, so the old behaviour published null-under-Good — which a client cannot tell apart from a genuine null reading. A value the gateway DID send would be consumed as a value it did not, with the only evidence in a log nobody is tailing. Bad data is the honest wire representation of lost data. BadTypeMismatch is an existing StatusCodeMap constant, deliberately reused rather than written inline: StatusCodeParityTests finds status constants by reflecting over Good/Uncertain/Bad-prefixed uint fields and checking them against the pinned SDK, so an inline literal would be invisible to that guard (Gitea #497, where 16 wrong constants had accumulated across 6 drivers exactly this way). Logging is now once per DISTINCT value kind rather than once per pump. The set is bounded by the MxValue oneof enum so a broken producer still cannot flood, but a second unrepresentable kind appearing later gets its own line — warn-once-per-pump would have silently swallowed it, which is the same class of bug as the null this commit fixes. The test's fixture matters more than its assertion: the undecodable event carries Quality = 192 (OPC DA Good), so a decoder that gave up silently would publish Good and fail. Paired with a positive control — a decodable value at the same quality must still publish Good — so it cannot be satisfied by a pump that marks everything Bad. Falsified by reverting the status to Good: the test reds, and only that test. Verified: 331 Galaxy tests green, Core.Abstractions 298 (the parity guard), solution builds 0 errors. Docs corrected in the two places that recorded the old decision as deliberate.	2026-08-12 03:03:51 -04:00
Joseph Doherty	4769044f88	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.	2026-08-12 02:56:17 -04:00