Joseph Doherty
3.5 KiB
Parity Fixture Matrix
The parity fixture matrix defines the live-test scenarios used to compare direct MXAccess behavior with the gateway-backed worker. It is a planning and validation fixture, not a source of synthetic MXAccess behavior.
The matrix lives in
clients/proto/fixtures/parity/parity-fixture-matrix.json. It references the
local MXAccess capture set under
C:/Users/dohertj2/Desktop/mxaccess/captures and keeps capture paths relative
to that root so the repository does not copy raw capture artifacts.
Scope
The matrix covers every public LMXProxyServerClass method represented by the
gateway contract:
RegisterUnregisterAddItemAddItem2RemoveItemAdviseUnAdviseAdviseSupervisoryAddBufferedItemSetBufferedUpdateIntervalSuspendActivateWriteWrite2WriteSecuredWriteSecured2AuthenticateUserArchestrAUserToId
Each entry is either a planned_fixture or a documented_gap.
WriteSecured remains a documented gap because the current captures show
0x80004021 before MXAccess emits a value-bearing write body.
OperationComplete and public OnBufferedDataChange batches also remain
documented gaps because no capture in the current set proves those public event
payloads from native MXAccess.
Required Scenario Groups
The matrix pins the high-risk parity scenarios from the integration milestone:
| Scenario | Purpose |
|---|---|
invalid_handles |
Preserves invalid server, item, post-remove, and invalid-reference HRESULT/status behavior. |
write_statuses |
Compares successful writes, wrong-type writes, invalid references, arrays, and write-complete status arrays. |
secured_writes |
Covers observed WriteSecured rejection and authenticated WriteSecured2 paths without logging credential-bearing values. |
add_item_context |
Ensures AddItem2 and buffered registration pass context strings exactly as supplied. |
buffered_registration |
Tracks buffered item registration and interval setup separately from normal advice. |
Comparison Format
Each live parity fixture should record one direct MXAccess result and one gateway result for the same operation.
Direct MXAccess records include:
- method name,
- arguments after redaction,
- returned value,
- HRESULT,
- exception type,
MXSTATUS_PROXY[]values,- native event records in observed order.
Gateway records include:
MxCommandKind,ProtocolStatus,MxCommandReply.ReturnValue,MxCommandReply.Hresult,- repeated
MxCommandReply.Statuses, - safe diagnostic message,
- streamed
MxEventrecords in worker-sequence order.
Compare HRESULT, exception type, returned value, status array shape, raw status fields, event family order, event payload shape, value projection, and raw fallback metadata. The gateway must not convert an MXAccess command failure into a transport failure when the worker captured HRESULT or status details.
Validation
Run the parity fixture matrix tests after changing the matrix:
dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~ParityFixtureMatrixTests
Live MXAccess execution remains opt-in. The matrix defines which scenarios to run when the installed MXAccess COM component and provider state are available; normal unit tests only validate the repository fixture shape.