fix(gateway): resolve 2026-06-18 array-write review findings

- Server-057: extend []-suffix normalization to AddItemBulk/AddBufferedItem so bulk-added
  array tags bind write-capable handles (authz check, worker bind, and registration kept
  consistent); update gateway.md + client READMEs. Tests: AddItemBulk/AddBufferedItem wiring.
- Server-058: assert []-fallback-resolved bare array names are still denied when out of
  read/write scope and that MaxWriteClassification is enforced on suffixed array registrations.
- Contracts-023/024/025: round-trip + field-19 descriptor pin for MxSparseArray; document
  MxSparseArray in docs/Contracts.md; enumerate it in the protocol-version-3 test summary.
- Tests-040: add wiring tests for the six uncovered sparse-write arms (WriteSecured, Write2,
  WriteSecured2, Write2Bulk, WriteSecuredBulk, WriteSecured2Bulk).

dotnet build + targeted tests green (184 passed).
This commit is contained in:
Joseph Doherty
2026-06-18 10:58:42 -04:00
parent 6c853b43af
commit 2671639250
10 changed files with 718 additions and 30 deletions
+18 -1
View File
@@ -8,7 +8,24 @@ recreated by the contracts project build.
`src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto` defines the public
`MxAccessGateway` gRPC service, command payloads, command replies, event DTOs,
`MxValue`, `MxArray`, and `MxStatusProxy`.
`MxValue`, `MxArray`, `MxSparseArray`, and `MxStatusProxy`.
`MxValue` carries a `kind` oneof with arms for all scalar and array types. One
arm is `sparse_array_value = 19` (field number 19), which carries an
`MxSparseArray`. `MxSparseArray` is a write-only value type: the gateway accepts
it on every write variant (`Write`, `Write2`, `WriteSecured`, `WriteSecured2`,
and the corresponding `*BulkEntry` shapes), expands it into a full,
default-filled `MxArray` before forwarding to the worker, and rejects it on
read or event paths. The worker never receives or produces it.
`MxSparseArray` has three fields: `element_data_type` (1, the `MxDataType` of
every element), `total_length` (2, the length of the expanded full array), and
`elements` (3, `repeated MxSparseElement`). Each `MxSparseElement` has `index`
(1, zero-based position in the expanded array) and `value` (2, a scalar
`MxValue`). Indices not mentioned in `elements` take the element type's default
value — they are reset, not preserved. See `gateway.md` section
"MxSparseArray — default-fill partial array writes" for the expansion rules,
validation constraints, and the scope requirements per write variant.
The public command model includes bulk subscription command kinds for
`AddItemBulk`, `AdviseItemBulk`, `RemoveItemBulk`, `UnAdviseItemBulk`,