feat(client-rust): add write_array_elements default-fill helper and document semantics

Handles the new MxSparseArray wire type (proto field 19 on MxValue::Kind):
- value.rs: map SparseArrayValue to MxValueProjection::Unset (write-only; never emitted on read path)
- session.rs: add write_array_elements() that builds the sparse proto value and delegates to write()
- tests: three unit tests asserting proto shape, empty-elements case, and read-path Unset projection
- README: document write_array_elements default-fill semantics and bare-name [] normalisation

clients/rust/src/session.rs

@@ -17,12 +17,12 @@ use crate::generated::mxaccess_gateway::v1::mx_command_reply;
 use crate::generated::mxaccess_gateway::v1::{
     AddItem2Command, AddItemBulkCommand, AddItemCommand, AdviseCommand, AdviseItemBulkCommand,
     BulkReadResult, BulkWriteResult, CloseSessionRequest, MxCommand, MxCommandKind, MxCommandReply,
-    MxCommandRequest, MxValue as ProtoMxValue, OpenSessionRequest, ReadBulkCommand,
-    RegisterCommand, RemoveItemBulkCommand, RemoveItemCommand, StreamEventsRequest,
-    SubscribeBulkCommand, SubscribeResult, UnAdviseCommand, UnAdviseItemBulkCommand,
-    UnsubscribeBulkCommand, Write2BulkCommand, Write2BulkEntry, Write2Command, WriteBulkCommand,
-    WriteBulkEntry, WriteCommand, WriteSecured2BulkCommand, WriteSecured2BulkEntry,
-    WriteSecuredBulkCommand, WriteSecuredBulkEntry,
+    MxCommandRequest, MxDataType, MxSparseArray, MxSparseElement, MxValue as ProtoMxValue,
+    OpenSessionRequest, ReadBulkCommand, RegisterCommand, RemoveItemBulkCommand, RemoveItemCommand,
+    StreamEventsRequest, SubscribeBulkCommand, SubscribeResult, UnAdviseCommand,
+    UnAdviseItemBulkCommand, UnsubscribeBulkCommand, Write2BulkCommand, Write2BulkEntry,
+    Write2Command, WriteBulkCommand, WriteBulkEntry, WriteCommand, WriteSecured2BulkCommand,
+    WriteSecured2BulkEntry, WriteSecuredBulkCommand, WriteSecuredBulkEntry,
 };
 use crate::value::MxValue;
 
@@ -547,6 +547,62 @@ impl Session {
         Ok(())
     }
 
+    /// Write a sparse, default-filled array: only the given elements
+    /// (index → scalar value) are set; every unmentioned index up to
+    /// `total_length` is written as the element type's default (a reset,
+    /// **not** a preserve). The gateway expands the sparse representation into
+    /// a whole-array write before forwarding to the worker.
+    ///
+    /// This is a convenience wrapper around [`Session::write`] that builds the
+    /// `MxSparseArray` wire value for you. Call [`Session::write`] directly
+    /// if you need to pass a pre-built [`MxValue`] carrying a full
+    /// `MxArray`.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Error::InvalidArgument`] (propagated from the gateway) if
+    /// `total_length` is zero, exceeds the gateway's maximum array length, or
+    /// any element index is out of range. Returns [`Error::Command`] for
+    /// non-OK worker statuses, plus the usual transport/status errors.
+    pub async fn write_array_elements(
+        &self,
+        server_handle: i32,
+        item_handle: i32,
+        element_data_type: MxDataType,
+        total_length: u32,
+        elements: impl IntoIterator<Item = (u32, MxValue)>,
+        user_id: i32,
+    ) -> Result<(), Error> {
+        use crate::generated::mxaccess_gateway::v1::mx_value::Kind;
+
+        let sparse_elements: Vec<MxSparseElement> = elements
+            .into_iter()
+            .map(|(index, value)| MxSparseElement {
+                index,
+                value: Some(value.into_proto()),
+            })
+            .collect();
+
+        let sparse_value = ProtoMxValue {
+            data_type: element_data_type as i32,
+            variant_type: String::new(),
+            kind: Some(Kind::SparseArrayValue(MxSparseArray {
+                element_data_type: element_data_type as i32,
+                total_length,
+                elements: sparse_elements,
+            })),
+            ..ProtoMxValue::default()
+        };
+
+        self.write(
+            server_handle,
+            item_handle,
+            MxValue::from_proto(sparse_value),
+            user_id,
+        )
+        .await
+    }
+
     /// Run MXAccess `Write2` (single-value with caller-supplied timestamp).
     ///
     /// # Errors