# 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:

- `Register`
- `Unregister`
- `AddItem`
- `AddItem2`
- `RemoveItem`
- `Advise`
- `UnAdvise`
- `AdviseSupervisory`
- `AddBufferedItem`
- `SetBufferedUpdateInterval`
- `Suspend`
- `Activate`
- `Write`
- `Write2`
- `WriteSecured`
- `WriteSecured2`
- `AuthenticateUser`
- `ArchestrAUserToId`

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 `MxEvent` records 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:

```bash
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.

## Related Documentation

- [Gateway Testing](./GatewayTesting.md)
- [MXAccess Worker Instance Detailed Design](./mxaccess-worker-instance-design.md)
- [Protobuf Contracts](./Contracts.md)