Joseph Doherty
51a9dadf62
- Rename 16 kebab-case docs to PascalCase per StyleGuide - Move per-language client design docs from docs/ to clients/<lang>/ alongside their READMEs - Add ## Related Documentation sections to 15 docs that lacked one - Fix sentence-case violations in H3 headings (StyleGuide rule) - Update cross-references in gateway.md, client READMEs, scripts, and generate-proto.ps1 helpers to follow the new paths - Add CLAUDE.md with build/test commands, the source-update verification matrix, the parity-first contract, and pointers to MXAccess and Galaxy Repository analysis sources Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
# 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](./MxAccessWorkerInstanceDesign.md)
|
|
- [Protobuf Contracts](./Contracts.md)
|