fix(client-rust): correct outer MxValue data_type and add end-to-end write_array_elements test

Fix the MxSparseArray type-defaults table in gateway.md to use the real MxDataType
enum member names (Integer, not Integer/LongInteger; Time, not Time/Timestamp) and
clarify the int64 note. Add a docstring sentence to write_array_elements in the
Python client noting that indices and total_length must be non-negative.

clients/go/README.md

@@ -153,6 +153,20 @@ integer `0`, float `0.0`, string `""`, time = Unix epoch). This is a **RESET**
 of unmentioned indices, not a preserve of existing values. Use the full-array
 form (read-modify-write) when existing element values must be preserved.
 
+```go
+// Set element [3] of a 10-element float array; all other indices reset to 0.0.
+err = session.WriteArrayElements(
+    ctx,
+    serverHandle, itemHandle,
+    mxgateway.DataTypeFloat,
+    10, // totalLength
+    map[uint32]*mxgateway.MxValue{
+        3: mxgateway.FloatValue(1.5),
+    },
+    userID,
+)
+```
+
 `AddItem` (and `AddItem2`) now auto-normalize a bare attribute name to the `[]`
 array address form expected by MXAccess, so callers do not need to append `[]`
 themselves. Both forms are accepted; duplicates are deduplicated by the gateway.

clients/go/mxgateway/client_session_test.go

@@ -742,7 +742,7 @@ func TestWriteArrayElementsSendsWriteCommandWithSparseOneof(t *testing.T) {
 		DataTypeFloat,
 		10,
 		map[uint32]*MxValue{3: FloatValue(1.5)},
-		0,
+		42,
 	)
 	if err != nil {
 		t.Fatalf("WriteArrayElements() error = %v", err)
@@ -752,7 +752,20 @@ func TestWriteArrayElementsSendsWriteCommandWithSparseOneof(t *testing.T) {
 	if cmd.GetKind() != pb.MxCommandKind_MX_COMMAND_KIND_WRITE {
 		t.Fatalf("command kind = %s, want WRITE", cmd.GetKind())
 	}
-	val := cmd.GetWrite().GetValue()
+	w := cmd.GetWrite()
+	if w.GetServerHandle() != 1 {
+		t.Fatalf("server handle = %d, want 1", w.GetServerHandle())
+	}
+	if w.GetItemHandle() != 2 {
+		t.Fatalf("item handle = %d, want 2", w.GetItemHandle())
+	}
+	if w.GetUserId() == 0 {
+		t.Fatal("user id = 0, want non-zero")
+	}
+	if w.GetUserId() != 42 {
+		t.Fatalf("user id = %d, want 42", w.GetUserId())
+	}
+	val := w.GetValue()
 	sa, ok := val.Kind.(*pb.MxValue_SparseArrayValue)
 	if !ok {
 		t.Fatalf("value kind is %T, want *pb.MxValue_SparseArrayValue", val.Kind)
@@ -763,4 +776,14 @@ func TestWriteArrayElementsSendsWriteCommandWithSparseOneof(t *testing.T) {
 	if sa.SparseArrayValue.GetElementDataType() != DataTypeFloat {
 		t.Errorf("ElementDataType = %v, want DataTypeFloat", sa.SparseArrayValue.GetElementDataType())
 	}
+	if len(sa.SparseArrayValue.GetElements()) != 1 {
+		t.Fatalf("len(Elements) = %d, want 1", len(sa.SparseArrayValue.GetElements()))
+	}
+	elem := sa.SparseArrayValue.GetElements()[0]
+	if elem.GetIndex() != 3 {
+		t.Errorf("element index = %d, want 3", elem.GetIndex())
+	}
+	if elem.GetValue().GetFloatValue() != 1.5 {
+		t.Errorf("element float value = %v, want 1.5", elem.GetValue().GetFloatValue())
+	}
 }

clients/python/src/zb_mom_ww_mxgateway/session.py

@@ -516,6 +516,10 @@ class Session:
                 element type of the target array attribute.
             total_length: Total number of elements in the written array.  Must
                 be > 0 and large enough to contain every index in *elements*.
+                Both *total_length* and all keys in *elements* must be
+                non-negative; the gateway rejects negative or out-of-range
+                values with ``InvalidArgument`` (the proto fields are
+                ``uint32``).
             elements: Mapping of zero-based element index to scalar value.
                 Values are converted with :func:`~zb_mom_ww_mxgateway.values.to_mx_value`.
             user_id: Galaxy user id to stamp on the write (requires a prior

clients/rust/src/session.rs

@@ -584,8 +584,6 @@ impl Session {
             .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,

clients/rust/tests/client_behavior.rs

@@ -17,6 +17,7 @@ use tonic::{Request, Response, Status};
 use zb_mom_ww_mxgateway_client::generated::mxaccess_gateway::v1::mx_access_gateway_server::{
     MxAccessGateway, MxAccessGatewayServer,
 };
+use zb_mom_ww_mxgateway_client::generated::mxaccess_gateway::v1::mx_command;
 use zb_mom_ww_mxgateway_client::generated::mxaccess_gateway::v1::mx_command_reply;
 use zb_mom_ww_mxgateway_client::generated::mxaccess_gateway::v1::mx_value::Kind;
 use zb_mom_ww_mxgateway_client::generated::mxaccess_gateway::v1::{
@@ -27,8 +28,8 @@ use zb_mom_ww_mxgateway_client::generated::mxaccess_gateway::v1::{
     MxEventFamily, MxSparseArray, MxSparseElement, MxStatusCategory, MxStatusProxy, MxStatusSource,
     MxValue, OnAlarmTransitionEvent, OpenSessionReply, OpenSessionRequest, ProtocolStatus,
     ProtocolStatusCode, QueryActiveAlarmsRequest, RegisterReply, SessionState, StreamAlarmsRequest,
-    StreamEventsRequest, SubscribeResult, Write2BulkEntry, WriteBulkEntry, WriteSecured2BulkEntry,
-    WriteSecuredBulkEntry,
+    StreamEventsRequest, SubscribeResult, Write2BulkEntry, WriteBulkEntry, WriteCommand,
+    WriteSecured2BulkEntry, WriteSecuredBulkEntry,
 };
 use zb_mom_ww_mxgateway_client::{
     next_correlation_id, ApiKey, ClientOptions, CommandError, Error, GatewayClient, MxStatus,
@@ -659,6 +660,9 @@ struct FakeState {
     authorization: Mutex<Option<String>>,
     last_command_kind: Mutex<Option<i32>>,
     last_correlation_id: Mutex<Option<String>>,
+    /// Captures the last `WriteCommand` payload received, populated when the
+    /// `WriteOk` override is active. Used by `write_array_elements` e2e test.
+    last_write_command: Mutex<Option<WriteCommand>>,
     stream_dropped: Arc<AtomicBool>,
     /// Optional per-test override that pins the fake's `Invoke` handler to
     /// a specific reply shape (or `Err(Status)`). The default of `None`
@@ -683,6 +687,10 @@ enum InvokeOverride {
     /// Fail the unary call with `Status::unavailable(...)` so the client's
     /// `Code::Unavailable` -> `Error::Unavailable` mapping is exercised.
     Unavailable(String),
+    /// Accept a `Write` command (return `protocol_status = Ok`, no payload)
+    /// and capture the decoded `WriteCommand` in
+    /// `FakeState::last_write_command` for inspection.
+    WriteOk,
 }
 
 #[derive(Clone)]
@@ -764,6 +772,23 @@ impl MxAccessGateway for FakeGateway {
                     ..MxCommandReply::default()
                 })),
                 InvokeOverride::Unavailable(message) => Err(Status::unavailable(message)),
+                InvokeOverride::WriteOk => {
+                    // Extract and capture the WriteCommand payload so the test
+                    // can assert on server_handle, item_handle, user_id, and value.
+                    if let Some(mx_command::Payload::Write(write_cmd)) =
+                        request.command.and_then(|c| c.payload)
+                    {
+                        *self.state.last_write_command.lock().await = Some(write_cmd);
+                    }
+                    Ok(Response::new(MxCommandReply {
+                        session_id: request.session_id,
+                        correlation_id: "fake-correlation".to_owned(),
+                        kind,
+                        protocol_status: Some(ok_status("write ok")),
+                        payload: None,
+                        ..MxCommandReply::default()
+                    }))
+                }
             };
         }
 
@@ -1092,6 +1117,77 @@ fn case_by_id<'a>(cases: &'a [Value], id: &str) -> &'a Value {
         .unwrap_or_else(|| panic!("missing fixture case {id}"))
 }
 
+// ---------------------------------------------------------------------------
+// write_array_elements — end-to-end fake-server test
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn write_array_elements_routes_sparse_array_write_through_fake_gateway() {
+    // Arrange: stand up the fake gateway with WriteOk so the Write command
+    // succeeds and the sent WriteCommand is captured for inspection.
+    let state = Arc::new(FakeState::default());
+    *state.invoke_override.lock().await = Some(InvokeOverride::WriteOk);
+    let endpoint = spawn_fake_gateway(state.clone()).await;
+    let client = GatewayClient::connect(ClientOptions::new(endpoint))
+        .await
+        .unwrap();
+    let session = client.session("session-fixture");
+
+    // Act: call the public write_array_elements helper.
+    session
+        .write_array_elements(
+            12,
+            34,
+            MxDataType::Integer,
+            10,
+            [(2u32, ClientMxValue::int32(42))],
+            7,
+        )
+        .await
+        .unwrap();
+
+    // Assert: the fake captured a Write command with the expected handles and
+    // a SparseArrayValue whose total_length and element index/value are correct.
+    let captured = state
+        .last_write_command
+        .lock()
+        .await
+        .take()
+        .expect("fake should have captured a WriteCommand");
+
+    assert_eq!(captured.server_handle, 12, "server_handle must round-trip");
+    assert_eq!(captured.item_handle, 34, "item_handle must round-trip");
+    assert_eq!(captured.user_id, 7, "user_id must round-trip");
+
+    let value = captured.value.expect("WriteCommand must carry a value");
+    assert_eq!(
+        value.data_type, 0,
+        "outer MxValue.data_type must be Unspecified (0), not the element type"
+    );
+
+    let Kind::SparseArrayValue(ref sparse) = value.kind.as_ref().unwrap() else {
+        panic!(
+            "expected SparseArrayValue kind on the outer MxValue, got {:?}",
+            value.kind
+        );
+    };
+    assert_eq!(
+        sparse.element_data_type,
+        MxDataType::Integer as i32,
+        "element_data_type must carry the element type"
+    );
+    assert_eq!(sparse.total_length, 10, "total_length must round-trip");
+    assert_eq!(sparse.elements.len(), 1, "one element supplied");
+
+    let elem = &sparse.elements[0];
+    assert_eq!(elem.index, 2, "element index must round-trip");
+    assert_eq!(
+        elem.value.as_ref().unwrap().kind,
+        Some(Kind::Int32Value(42)),
+        "element value must round-trip"
+    );
+}
+
 // ---------------------------------------------------------------------------
 // write_array_elements — proto shape unit tests
 // ---------------------------------------------------------------------------

gateway.md

@@ -512,10 +512,10 @@ Default values by element type:
 | Element type | Default |
 |---|---|
 | `Boolean` | `false` |
-| `Integer` / `LongInteger` | `0` |
+| `Integer` | `0` (int32, or int64 when an element value is 64-bit) |
 | `Float` / `Double` | `0` |
 | `String` | `""` |
-| `Time` / `Timestamp` | Unix epoch (1970-01-01T00:00:00Z) |
+| `Time` | Unix epoch (1970-01-01T00:00:00Z) |
 
 Unmentioned indices take the element type's default — this is a **reset**, not a
 preserve. There is no read-modify-write merge: adding that would introduce cache

src/ZB.MOM.WW.MxGateway.Server/Sessions/GatewaySession.cs

@@ -38,6 +38,7 @@ public sealed class GatewaySession
     private Task? _dashboardMirrorTask;
     private CancellationTokenSource? _dashboardMirrorCts;
     private readonly Dictionary<(int ServerHandle, int ItemHandle), SessionItemRegistration> _items = [];
+    private readonly ArrayAddressNormalizer? _addressNormalizer;
 
     /// <summary>
     /// Initializes a gateway session with session metadata and timeout configuration.
@@ -133,6 +134,12 @@ public sealed class GatewaySession
     ///     fast immediately. <see cref="TimeSpan.Zero"/> (the default) disables the wait and
     ///     preserves the original fail-fast behavior byte-for-byte.
     /// </param>
+    /// <param name="addressNormalizer">
+    ///     Rewrites bare array <c>AddItem</c>/<c>AddItem2</c> addresses to their writable <c>[]</c>
+    ///     form using Galaxy metadata at the outbound choke point (and on registration tracking).
+    ///     When <see langword="null"/> (legacy unit-construction paths that do not exercise Galaxy
+    ///     metadata), addresses pass through unchanged.
+    /// </param>
     public GatewaySession(
         string sessionId,
         string backendName,
@@ -149,7 +156,8 @@ public sealed class GatewaySession
         DateTimeOffset openedAt,
         SessionEventStreaming? eventStreaming = null,
         TimeSpan detachGrace = default,
-        TimeSpan workerReadyWaitTimeout = default)
+        TimeSpan workerReadyWaitTimeout = default,
+        ArrayAddressNormalizer? addressNormalizer = null)
     {
         if (string.IsNullOrWhiteSpace(sessionId))
         {
@@ -189,6 +197,7 @@ public sealed class GatewaySession
         _eventStreaming = eventStreaming ?? SessionEventStreaming.Default;
         _detachGrace = detachGrace > TimeSpan.Zero ? detachGrace : TimeSpan.Zero;
         _workerReadyWaitTimeout = workerReadyWaitTimeout > TimeSpan.Zero ? workerReadyWaitTimeout : TimeSpan.Zero;
+        _addressNormalizer = addressNormalizer;
     }
 
     /// <summary>
@@ -948,12 +957,95 @@ public sealed class GatewaySession
         WorkerCommand command,
         CancellationToken cancellationToken)
     {
+        ArgumentNullException.ThrowIfNull(command);
+        if (command.Command is not null)
+        {
+            NormalizeOutboundCommand(command.Command);
+        }
+
         IWorkerClient workerClient = await GetReadyWorkerClientAsync(cancellationToken).ConfigureAwait(false);
         TouchClientActivity(_eventStreaming.TimeProvider.GetUtcNow());
 
         return await workerClient.InvokeAsync(command, CommandTimeout, cancellationToken).ConfigureAwait(false);
     }
 
+    // Single outbound choke point for the two array-write ergonomics shims (Task 3):
+    //   1. AddItem/AddItem2 array addresses gain the writable "[]" suffix when Galaxy metadata
+    //      reports them as arrays, so the worker registers a write-capable handle. The mutation
+    //      lands on the same MxCommand instance forwarded to the worker.
+    //   2. Sparse array write values are expanded to whole-array values, because MXAccess has no
+    //      partial-array write primitive — the worker only ever sees a full MxArray.
+    // SparseArrayExpander.Expand throws RpcException(InvalidArgument) for an invalid sparse payload;
+    // that propagates out of InvokeAsync as the desired client-facing error and is deliberately not
+    // caught here.
+    private void NormalizeOutboundCommand(MxCommand command)
+    {
+        switch (command.PayloadCase)
+        {
+            case MxCommand.PayloadOneofCase.AddItem:
+                command.AddItem.ItemDefinition = NormalizeAddress(command.AddItem.ItemDefinition);
+                break;
+            case MxCommand.PayloadOneofCase.AddItem2:
+                command.AddItem2.ItemDefinition = NormalizeAddress(command.AddItem2.ItemDefinition);
+                break;
+            case MxCommand.PayloadOneofCase.Write:
+                ExpandValue(command.Write.Value);
+                break;
+            case MxCommand.PayloadOneofCase.WriteSecured:
+                ExpandValue(command.WriteSecured.Value);
+                break;
+            case MxCommand.PayloadOneofCase.Write2:
+                ExpandValue(command.Write2.Value);
+                break;
+            case MxCommand.PayloadOneofCase.WriteSecured2:
+                ExpandValue(command.WriteSecured2.Value);
+                break;
+            case MxCommand.PayloadOneofCase.WriteBulk:
+                foreach (WriteBulkEntry entry in command.WriteBulk.Entries)
+                {
+                    ExpandValue(entry.Value);
+                }
+
+                break;
+            case MxCommand.PayloadOneofCase.Write2Bulk:
+                foreach (Write2BulkEntry entry in command.Write2Bulk.Entries)
+                {
+                    ExpandValue(entry.Value);
+                }
+
+                break;
+            case MxCommand.PayloadOneofCase.WriteSecuredBulk:
+                foreach (WriteSecuredBulkEntry entry in command.WriteSecuredBulk.Entries)
+                {
+                    ExpandValue(entry.Value);
+                }
+
+                break;
+            case MxCommand.PayloadOneofCase.WriteSecured2Bulk:
+                foreach (WriteSecured2BulkEntry entry in command.WriteSecured2Bulk.Entries)
+                {
+                    ExpandValue(entry.Value);
+                }
+
+                break;
+        }
+    }
+
+    // Best-effort array-suffix rewrite; the normalizer is null in legacy unit-construction paths
+    // that do not exercise Galaxy metadata, in which case the address passes through unchanged.
+    private string NormalizeAddress(string address) =>
+        _addressNormalizer?.Normalize(address) ?? address;
+
+    // MXAccess writes replace the whole array; expand a sparse value in place so the worker only
+    // ever receives a whole-array MxValue. No-op for null or non-sparse values.
+    private static void ExpandValue(MxValue? value)
+    {
+        if (value is not null)
+        {
+            SparseArrayExpander.Expand(value);
+        }
+    }
+
     /// <summary>Gets the item registration for a server and item handle pair.</summary>
     /// <param name="serverHandle">The MXAccess server handle.</param>
     /// <param name="itemHandle">The MXAccess item handle.</param>
@@ -985,11 +1077,16 @@ public sealed class GatewaySession
         {
             switch (command.Kind)
             {
+                // The public reply is tracked from the pre-mapping MxCommand instance, which is a
+                // separate copy from the one mutated at the InvokeAsync choke point (the gRPC mapper
+                // deep-clones before forwarding). Re-apply the array-suffix normalization here so the
+                // registration's TagAddress matches the address the worker actually registered.
+                // Normalize is idempotent for an already-suffixed address.
                 case MxCommandKind.AddItem when reply.AddItem is not null:
-                    TrackItem(command.AddItem.ServerHandle, reply.AddItem.ItemHandle, command.AddItem.ItemDefinition);
+                    TrackItem(command.AddItem.ServerHandle, reply.AddItem.ItemHandle, NormalizeAddress(command.AddItem.ItemDefinition));
                     break;
                 case MxCommandKind.AddItem2 when reply.AddItem2 is not null:
-                    TrackItem(command.AddItem2.ServerHandle, reply.AddItem2.ItemHandle, command.AddItem2.ItemDefinition);
+                    TrackItem(command.AddItem2.ServerHandle, reply.AddItem2.ItemHandle, NormalizeAddress(command.AddItem2.ItemDefinition));
                     break;
                 case MxCommandKind.AddBufferedItem when reply.AddBufferedItem is not null:
                     TrackItem(command.AddBufferedItem.ServerHandle, reply.AddBufferedItem.ItemHandle, command.AddBufferedItem.ItemDefinition);

src/ZB.MOM.WW.MxGateway.Server/Sessions/SessionManager.cs

@@ -29,6 +29,7 @@ public sealed class SessionManager : ISessionManager
     private readonly Grpc.MxAccessGrpcMapper _eventMapper;
     private readonly ILogger<SessionEventDistributor> _distributorLogger;
     private readonly Dashboard.Hubs.IDashboardEventBroadcaster? _dashboardEventBroadcaster;
+    private readonly ArrayAddressNormalizer? _addressNormalizer;
 
     /// <summary>
     /// Initializes a new instance of <see cref="SessionManager"/>.
@@ -47,6 +48,11 @@ public sealed class SessionManager : ISessionManager
     ///     dashboard receives events regardless of whether a gRPC client is streaming. Null in
     ///     unit tests that do not exercise the dashboard mirror.
     /// </param>
+    /// <param name="addressNormalizer">
+    ///     Rewrites bare array AddItem addresses to their writable <c>[]</c> form using Galaxy
+    ///     metadata; handed to each session so the normalization runs at the outbound choke point.
+    ///     Null in unit tests that do not exercise array-write ergonomics.
+    /// </param>
     public SessionManager(
         ISessionRegistry registry,
         ISessionWorkerClientFactory workerClientFactory,
@@ -56,7 +62,8 @@ public sealed class SessionManager : ISessionManager
         ILogger<SessionManager>? logger = null,
         Grpc.MxAccessGrpcMapper? eventMapper = null,
         ILogger<SessionEventDistributor>? distributorLogger = null,
-        Dashboard.Hubs.IDashboardEventBroadcaster? dashboardEventBroadcaster = null)
+        Dashboard.Hubs.IDashboardEventBroadcaster? dashboardEventBroadcaster = null,
+        ArrayAddressNormalizer? addressNormalizer = null)
     {
         _registry = registry ?? throw new ArgumentNullException(nameof(registry));
         _workerClientFactory = workerClientFactory ?? throw new ArgumentNullException(nameof(workerClientFactory));
@@ -67,6 +74,7 @@ public sealed class SessionManager : ISessionManager
         _eventMapper = eventMapper ?? new Grpc.MxAccessGrpcMapper();
         _distributorLogger = distributorLogger ?? NullLogger<SessionEventDistributor>.Instance;
         _dashboardEventBroadcaster = dashboardEventBroadcaster;
+        _addressNormalizer = addressNormalizer;
         _options = options.Value;
         _sessionSlots = new SemaphoreSlim(_options.Sessions.MaxSessions, _options.Sessions.MaxSessions);
     }
@@ -506,7 +514,8 @@ public sealed class SessionManager : ISessionManager
             openedAt,
             eventStreaming,
             TimeSpan.FromSeconds(Math.Max(0, _options.Sessions.DetachGraceSeconds)),
-            TimeSpan.FromMilliseconds(Math.Max(0, _options.Sessions.WorkerReadyWaitTimeoutMs)));
+            TimeSpan.FromMilliseconds(Math.Max(0, _options.Sessions.WorkerReadyWaitTimeoutMs)),
+            _addressNormalizer);
     }
 
     private static string CreateClientCorrelationId(

src/ZB.MOM.WW.MxGateway.Server/Sessions/SessionServiceCollectionExtensions.cs

@@ -8,6 +8,9 @@ public static class SessionServiceCollectionExtensions
     /// <returns>The service collection for chaining.</returns>
     public static IServiceCollection AddGatewaySessions(this IServiceCollection services)
     {
+        // Lifetime consistent with IGalaxyHierarchyCache (singleton); the normalizer reads the
+        // cache's current snapshot per call, so it holds no per-session or per-request state.
+        services.AddSingleton<ArrayAddressNormalizer>();
         services.AddSingleton<ISessionRegistry, SessionRegistry>();
         services.AddSingleton<ISessionWorkerClientFactory, SessionWorkerClientFactory>();
         services.AddSingleton<ISessionManager, SessionManager>();

src/ZB.MOM.WW.MxGateway.Tests/Gateway/Sessions/GatewayArrayWriteWiringTests.cs

@@ -0,0 +1,267 @@
+using System.Runtime.CompilerServices;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Server.Galaxy;
+using ZB.MOM.WW.MxGateway.Server.Sessions;
+using ZB.MOM.WW.MxGateway.Server.Workers;
+
+namespace ZB.MOM.WW.MxGateway.Tests.Gateway.Sessions;
+
+/// <summary>
+///     Integration coverage for the single outbound choke point
+///     (<see cref="GatewaySession.InvokeAsync(WorkerCommand, System.Threading.CancellationToken)"/>):
+///     array <c>AddItem</c> addresses gain the writable <c>[]</c> suffix and sparse array writes are
+///     expanded to whole-array values before any command reaches the worker.
+/// </summary>
+public sealed class GatewayArrayWriteWiringTests
+{
+    /// <summary>
+    ///     A bare array <c>AddItem</c> address is normalized to its writable array form on the wire,
+    ///     and the normalized address lands in the tracked <see cref="SessionItemRegistration"/>.
+    /// </summary>
+    [Fact]
+    public async Task AddItem_BareArrayAddress_NormalizedOnWireAndInRegistration()
+    {
+        CapturingWorkerClient worker = new();
+        GatewaySession session = CreateReadySession(worker);
+
+        WorkerCommand command = new()
+        {
+            Command = new MxCommand
+            {
+                Kind = MxCommandKind.AddItem,
+                AddItem = new AddItemCommand
+                {
+                    ServerHandle = 1,
+                    ItemDefinition = "Obj.Arr",
+                },
+            },
+        };
+
+        worker.NextReply = new WorkerCommandReply
+        {
+            Reply = new MxCommandReply
+            {
+                Kind = MxCommandKind.AddItem,
+                ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+                AddItem = new AddItemReply { ItemHandle = 42 },
+            },
+        };
+
+        await session.InvokeAsync(command, CancellationToken.None);
+
+        Assert.NotNull(worker.LastCommand);
+        Assert.Equal("Obj.Arr[]", worker.LastCommand!.Command.AddItem.ItemDefinition);
+
+        // Track the reply through the same path the gRPC service uses; the registration must carry
+        // the normalized address even though the public reply is tracked from a separate command copy.
+        MxCommand trackingCopy = new()
+        {
+            Kind = MxCommandKind.AddItem,
+            AddItem = new AddItemCommand
+            {
+                ServerHandle = 1,
+                ItemDefinition = "Obj.Arr",
+            },
+        };
+        session.TrackCommandReply(trackingCopy, worker.NextReply.Reply);
+
+        Assert.True(session.TryGetItemRegistration(1, 42, out SessionItemRegistration registration));
+        Assert.Equal("Obj.Arr[]", registration.TagAddress);
+    }
+
+    /// <summary>A bare scalar <c>AddItem</c> address is forwarded unchanged.</summary>
+    [Fact]
+    public async Task AddItem_ScalarAddress_ForwardedUnchanged()
+    {
+        CapturingWorkerClient worker = new();
+        GatewaySession session = CreateReadySession(worker);
+
+        WorkerCommand command = new()
+        {
+            Command = new MxCommand
+            {
+                Kind = MxCommandKind.AddItem,
+                AddItem = new AddItemCommand
+                {
+                    ServerHandle = 1,
+                    ItemDefinition = "Obj.Scalar",
+                },
+            },
+        };
+
+        await session.InvokeAsync(command, CancellationToken.None);
+
+        Assert.Equal("Obj.Scalar", worker.LastCommand!.Command.AddItem.ItemDefinition);
+    }
+
+    /// <summary>
+    ///     A sparse-array <see cref="WriteCommand"/> value is expanded to a full, default-filled
+    ///     <see cref="MxArray"/> before reaching the worker; no sparse value is ever forwarded.
+    /// </summary>
+    [Fact]
+    public async Task Write_SparseArrayValue_ExpandedBeforeReachingWorker()
+    {
+        CapturingWorkerClient worker = new();
+        GatewaySession session = CreateReadySession(worker);
+
+        WorkerCommand command = new()
+        {
+            Command = new MxCommand
+            {
+                Kind = MxCommandKind.Write,
+                Write = new WriteCommand
+                {
+                    ServerHandle = 1,
+                    ItemHandle = 42,
+                    Value = new MxValue
+                    {
+                        SparseArrayValue = new MxSparseArray
+                        {
+                            ElementDataType = MxDataType.Integer,
+                            TotalLength = 4,
+                            Elements =
+                            {
+                                new MxSparseElement
+                                {
+                                    Index = 1,
+                                    Value = new MxValue { Int32Value = 7 },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        };
+
+        await session.InvokeAsync(command, CancellationToken.None);
+
+        MxValue forwarded = worker.LastCommand!.Command.Write.Value;
+        Assert.Equal(MxValue.KindOneofCase.ArrayValue, forwarded.KindCase);
+        Assert.Equal(new[] { 0, 7, 0, 0 }, forwarded.ArrayValue.Int32Values.Values);
+    }
+
+    private static GatewaySession CreateReadySession(IWorkerClient workerClient)
+    {
+        GatewaySession session = new(
+            sessionId: "session-array-write-wiring",
+            backendName: "mxaccess",
+            pipeName: "mxaccess-gateway-1-session-array-write-wiring",
+            nonce: "nonce",
+            clientIdentity: "client-1",
+            ownerKeyId: null,
+            clientSessionName: "test-session",
+            clientCorrelationId: "client-correlation-1",
+            commandTimeout: TimeSpan.FromSeconds(5),
+            startupTimeout: TimeSpan.FromSeconds(5),
+            shutdownTimeout: TimeSpan.FromSeconds(5),
+            leaseDuration: TimeSpan.FromMinutes(30),
+            openedAt: DateTimeOffset.UtcNow,
+            addressNormalizer: CreateNormalizer());
+        session.AttachWorkerClient(workerClient);
+        session.MarkReady();
+        return session;
+    }
+
+    private static ArrayAddressNormalizer CreateNormalizer()
+    {
+        IReadOnlyList<GalaxyObject> objects =
+        [
+            new GalaxyObject
+            {
+                GobjectId = 1,
+                TagName = "Obj",
+                ContainedName = "Obj",
+                Attributes =
+                {
+                    new GalaxyAttribute
+                    {
+                        AttributeName = "Arr",
+                        FullTagReference = "Obj.Arr[]",
+                        IsArray = true,
+                    },
+                    new GalaxyAttribute
+                    {
+                        AttributeName = "Scalar",
+                        FullTagReference = "Obj.Scalar",
+                        IsArray = false,
+                    },
+                },
+            },
+        ];
+
+        GalaxyHierarchyCacheEntry entry = GalaxyHierarchyCacheEntry.Empty with
+        {
+            Status = GalaxyCacheStatus.Healthy,
+            Objects = objects,
+            Index = GalaxyHierarchyIndex.Build(objects),
+        };
+
+        return new ArrayAddressNormalizer(new StubGalaxyHierarchyCache(entry));
+    }
+
+    private sealed class StubGalaxyHierarchyCache(GalaxyHierarchyCacheEntry current) : IGalaxyHierarchyCache
+    {
+        /// <summary>Gets the current cache entry.</summary>
+        public GalaxyHierarchyCacheEntry Current { get; } = current;
+
+        /// <inheritdoc />
+        public Task RefreshAsync(CancellationToken cancellationToken) => Task.CompletedTask;
+
+        /// <inheritdoc />
+        public Task WaitForFirstLoadAsync(CancellationToken cancellationToken) => Task.CompletedTask;
+    }
+
+    private sealed class CapturingWorkerClient : IWorkerClient
+    {
+        /// <summary>Gets the most recent command forwarded to the worker.</summary>
+        public WorkerCommand? LastCommand { get; private set; }
+
+        /// <summary>Gets or sets the reply returned by the next invocation.</summary>
+        public WorkerCommandReply NextReply { get; set; } = new();
+
+        /// <summary>Gets the session identifier.</summary>
+        public string SessionId { get; } = "session-array-write-wiring";
+
+        /// <summary>Gets the worker process identifier.</summary>
+        public int? ProcessId { get; } = 1234;
+
+        /// <summary>Gets the worker client state.</summary>
+        public WorkerClientState State { get; } = WorkerClientState.Ready;
+
+        /// <summary>Gets the last recorded heartbeat timestamp.</summary>
+        public DateTimeOffset LastHeartbeatAt { get; } = DateTimeOffset.UtcNow;
+
+        /// <inheritdoc />
+        public Task StartAsync(CancellationToken cancellationToken) => Task.CompletedTask;
+
+        /// <inheritdoc />
+        public Task<WorkerCommandReply> InvokeAsync(
+            WorkerCommand command,
+            TimeSpan timeout,
+            CancellationToken cancellationToken)
+        {
+            LastCommand = command;
+            return Task.FromResult(NextReply);
+        }
+
+        /// <inheritdoc />
+        public async IAsyncEnumerable<WorkerEvent> ReadEventsAsync(
+            [EnumeratorCancellation] CancellationToken cancellationToken)
+        {
+            await Task.CompletedTask.ConfigureAwait(false);
+            yield break;
+        }
+
+        /// <inheritdoc />
+        public Task ShutdownAsync(TimeSpan timeout, CancellationToken cancellationToken) => Task.CompletedTask;
+
+        /// <inheritdoc />
+        public void Kill(string reason)
+        {
+        }
+
+        /// <inheritdoc />
+        public ValueTask DisposeAsync() => ValueTask.CompletedTask;
+    }
+}