docs(proto): document the correlated write-completion statuses contract

src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto

@@ -256,6 +256,9 @@ message Write2Command {
   int32 user_id = 5;
 }
 
+// The unary reply's statuses field carries the correlated OnWriteComplete
+// outcome when it arrives within the worker's bounded wait — see
+// MxCommandReply.statuses.
 message WriteSecuredCommand {
   int32 server_handle = 1;
   int32 item_handle = 2;
@@ -266,6 +269,9 @@ message WriteSecuredCommand {
   MxValue value = 5;
 }
 
+// The unary reply's statuses field carries the correlated OnWriteComplete
+// outcome when it arrives within the worker's bounded wait — see
+// MxCommandReply.statuses.
 message WriteSecured2Command {
   int32 server_handle = 1;
   int32 item_handle = 2;
@@ -525,6 +531,18 @@ message MxCommandReply {
   // transport failures.
   optional int32 hresult = 5;
   MxValue return_value = 6;
+  // Correlated per-item outcome rows. For WRITE_SECURED / WRITE_SECURED2
+  // replies the worker holds the reply for a bounded window (default 1.5 s,
+  // MXGATEWAY_WORKER_WRITE_COMPLETION_WAIT_MS) waiting for the matching
+  // MXAccess OnWriteComplete callback and copies its status rows here, so
+  // statuses[0] carries the real MXAccess commit outcome (success OR failure)
+  // while protocol_status/hresult still describe command acceptance only.
+  // Empty statuses on a write reply means the completion did not arrive
+  // within the window — the write is unconfirmed, not failed. Correlation is
+  // best-effort per (server_handle, item_handle): MXAccess's callback carries
+  // no transaction id, so concurrent writes to the same item within the
+  // window can swap rows. The OnWriteComplete event still flows on the event
+  // stream unchanged. Other command kinds leave this field as before.
   repeated MxStatusProxy statuses = 7;
   string diagnostic_message = 8;