lmxopcua/docs/v2/Galaxy.ParityMatrix.md

Galaxy backend parity matrix

This document tracks the scenario × result matrix that the Driver.Galaxy.ParityTests suite drives against both Galaxy backends — the legacy out-of-process Galaxy.Host (.NET 4.8 x86 + MXAccess COM, fronted by GalaxyProxyDriver) and the new in-process mxgateway backend (GalaxyDriver, .NET 10 + gRPC against mxaccessgw).

Maintained alongside Phase 5 (PR 5.W). The Phase 7 default flip (PR 7.1) consumes this matrix as its go/no-go gate — every row must be either green or carry an explicit accepted-delta justification.

Reading the matrix

• Status: green — the scenario asserts strict parity and passes (or skips cleanly when the rig isn't up).
• Status: yellow — soft pin only (count or shape parity, not value parity) — acceptable when the underlying COM/gRPC stacks have known divergences in raw payloads but the surface presented to the DriverNodeManager is equivalent.
• Status: red — divergence detected. Row carries a fix or a follow-up task ID.

Scenarios

Last verified end-to-end on the dev parity rig: 2026-04-30 (legacy OtOpcUaGalaxyHost mxaccess backend; mxaccessgw v1.x at http://localhost:5120; sandbox OtOpcUaParityTest_001 deployed in the ZB galaxy; 13 passed / 1 skipped / 0 failed in 19 minutes).

PR	Test class	Scenario	Status	Notes
5.2	BrowseAndReadParityTests	Same variable set	green	symmetric set diff on full-reference set, after [] array-suffix workaround in GalaxyDiscoverer
5.2	BrowseAndReadParityTests	Same DataType / SecurityClass / IsHistorized	green	per-attribute meta triple parity
5.2	BrowseAndReadParityTests	Same StatusCode-class on a sampled read	yellow	pins status class (Bad/Uncertain/Good); CLR type intentionally not asserted — see "Accepted deltas" #6
5.3	SubscribeAndEventRateParityTests	Subscribe returns a handle on each backend	green	symmetric Unsubscribe cleanup
5.3	SubscribeAndEventRateParityTests	Event rate within ±50% over 3s	yellow	both backends fed by the same upstream MXAccess subscriptions; tolerance absorbs scheduler jitter
5.4	WriteByClassificationParityTests	FreeAccess / Operate write status-class parity	yellow	pins status class only; legacy flat-maps every failure to BadInternalError, mxgw distinguishes (BadCommunicationError, BadDeviceFailure, etc.) — see "Accepted deltas" #7
5.4	WriteByClassificationParityTests	Configure / Tune routes via secured-write	yellow	same status-class pin
5.5	AlarmTransitionParityTests	Same alarm-condition source-node-id set	green	one-way invariant on sub-attribute refs (legacy populated → mxgw matches; legacy null → mxgw free to populate per AlarmRefBuilder)
5.5	AlarmTransitionParityTests	IsAlarm-marked variable count parity	green	soft pin — count must match, doesn't have to be non-zero
5.6	HistoryReadParityTests	Same historized attribute set	green	what HistoryRouter consumes when routing to the Wonderware sidecar
5.6	HistoryReadParityTests	New mxgw GalaxyDriver does not implement IHistoryProvider	green	architectural pin from Phase 1 (PR 1.3) on the new path; legacy GalaxyProxyDriver keeps the interface for back-compat until PR 7.2 — see "Accepted deltas" #8
5.7	ReconnectParityTests	Reinitialize → both Healthy + reads succeed	green	recovery latency is not pinned (legacy: pipe + COM client; mxgw: re-Register gw session)
5.7	ReconnectParityTests	Health diverges only when one side recovers	yellow	soft pin until a toxiproxy-style fault injector lands
5.8	ScanStateProbeParityTests	Same per-platform host set	n/a — deferred	dev rig is licensed for one $WinPlatform only; multi-platform parity deferred to a customer rig (PR 4.7's unit tests pin the state-decoder + member-tracking logic)
5.8	ScanStateProbeParityTests	Same HostState per overlapping platform	n/a — deferred	same single-platform constraint

Accepted deltas

These are intentional differences between the two backends — the parity suite skips or tolerates them by design.

1. Transport-entry host name. The legacy backend's IHostConnectivityProbe surface includes a host entry named after the Galaxy.Host process identity; the mxgw backend uses the configured MxAccess.ClientName. The names differ, but both are correct for their respective sessions — the parity test compares only the platform-host subset.

2. Reconnect latency cadence. Legacy reconnect roundtrips an OS named pipe + an MxAccess COM client + a Galaxy.Host process restart if the host died. The mxgw reconnect re-Registers the gateway session over an existing gRPC channel. Sub-second vs multi-second recoveries are both correct for their own paths; only the eventual Healthy convergence is pinned.

3. Read-value drift. A read sampled twice on a live Galaxy can return different values legitimately. We pin StatusCode-class parity (Bad/Uncertain/Good); value equality is not pinned.

4. Event-rate variance. Both backends consume the same upstream MXAccess publish events but route them through different deserializers (LMXProxyServer COM events vs gRPC MxEvent protos). Scheduler jitter on either side can shift counts within a 3s window; we pin a ±50% ratio, not strict equality.

5. IHistoryProvider on the new path only. Phase 1 (PR 1.3) lifted history off the per-driver path onto the server-owned HistoryRouter for the new in-process GalaxyDriver. The legacy GalaxyProxyDriver still surfaces IHistoryProvider for back-compat with the legacy server bootstrap path — it's an accepted delta retired in PR 7.2 alongside the rest of the legacy projects. The pin we want to enforce is "the new path doesn't regress to per-driver history."

6. Read value-CLR-type. Legacy returns the raw VARIANT (e.g. Byte[]) for an attribute that hasn't received its first value cycle from MxAccess yet, while mxgw returns the typed value (Single, Int32, etc.). Once a real value is written or scanned, both converge. Pinning CLR-type equality across the uninitialized window adds noise without a real parity invariant — the StatusCode-class assertion already covers the "did the read succeed" question.

7. Write-failure StatusCode mapping. Legacy MxAccessGalaxyBackend.WriteValuesAsync flat-maps every failure to BadInternalError (0x80020000); mxgw GatewayGalaxyDataWriter.TranslateReply uses MxStatusProxy.RawDetectedBy to distinguish gw-layer faults (BadCommunicationError, 0x80050000) from MxAccess HRESULT faults (BadDeviceFailure, BadNotConnected, etc.). Both yield Bad-status — the parity invariant is the status class, not the exact code. Tighter mapping parity isn't worth investing in: the legacy mapping retires alongside GalaxyProxyDriver in PR 7.2.

8. Single-platform scope on the dev rig. Two ScanStateProbeParityTests scenarios are deferred to a customer rig with multiple deployed $WinPlatform instances; this dev box is licensed for one. PR 4.7's unit tests (PerPlatformProbeWatcherTests) pin the state-decoder + member-tracking logic at the seam level, so the runtime parity check becomes a customer-rig acceptance gate before that customer goes live, not a precondition for retiring the legacy projects on this dev box.

9. Workaround for the gw [] array-suffix bug. mxaccessgw/src/MxGateway.Server/Galaxy/GalaxyRepository.cs:173-175 appends [] to the full_tag_reference of array-typed attributes, which MxAccess COM IInstance.AddItem doesn't accept. The lmxopcua discoverer (GalaxyDiscoverer.StripArraySuffix) defensively strips the suffix. Tracked in mxaccessgw/requirements-array-suffix-fix.md; the workaround is removed when that gw fix lands.

Outstanding deltas

None as of 2026-04-30. Phase 7 (PR 7.1) flipped the default to mxgw; PR 7.2 retires the legacy projects after the soak run + a 2-week production pilot.

Running the matrix

# Both backends must be reachable for any row to run; rows skip
# cleanly when their backend is unavailable.
dotnet test tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.ParityTests/

Environment overrides for the mxgw backend:

Variable	Default	Purpose
OTOPCUA_PARITY_GW_ENDPOINT	http://localhost:5120	mxaccessgw gRPC endpoint
OTOPCUA_PARITY_GW_API_KEY	parity-suite-key	API key handed to MxGatewayClient
OTOPCUA_PARITY_CLIENT_NAME	OtOpcUa-Parity	MxAccess.ClientName for the session

The legacy backend reads ZB SQL on localhost:1433 and spawns OtOpcUa.Driver.Galaxy.Host.exe from src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host/bin/Debug/net48/ — both must exist for the legacy half to resolve.