docs: write-completion correlation configuration and semantics

2026-08-09 12:28:30 -04:00
parent 431a096cab
commit 2b468bd8fc
3 changed files with 60 additions and 0 deletions
@@ -431,6 +431,23 @@ Core commands:
 - `AuthenticateUser`
 - `ArchestrAUserToId`

+**Secured-write completion correlation.** MXAccess writes are fire-and-forget
+at the toolkit level — the per-item outcome only exists in the later
+`OnWriteComplete` callback. For `WriteSecured` and `WriteSecured2` the worker
+therefore holds the unary reply for a bounded window
+(`MxGateway:Worker:WriteCompletionWaitMilliseconds`, default 1.5 s, `0`
+disables) and, when the matching callback arrives, copies its status rows onto
+`MxCommandReply.statuses` — the reply then proves the MXAccess commit, not just
+command acceptance. `protocol_status`/`hresult` keep describing acceptance
+only; a real MXAccess write failure surfaces in `statuses[0]`, and a reply with
+empty `statuses` means unconfirmed (the callback missed the window), never
+failed. The `OnWriteComplete` event still flows on the event stream unchanged.
+Correlation is best-effort per `(server_handle, item_handle)` — the callback
+carries no transaction id, so concurrent writes to the same item within the
+window can swap rows. Plain `Write`/`Write2` and the bulk write commands stay
+fire-and-forget: waiting there would add a device round-trip of latency to
+high-rate supervisory write loops.
+
 Bulk variants (single gRPC round-trip carries the full list, the worker
 runs the per-item MXAccess calls sequentially on its STA, and the reply
 returns one result per requested entry — per-entry failures populate