Add bulk read/write command family across worker, gateway, and clients

Adds five new MXAccess command kinds (WriteBulk, Write2Bulk,
WriteSecuredBulk, WriteSecured2Bulk, ReadBulk) that ride the existing
"one round-trip, per-entry results" bulk shape used by AddItemBulk and
SubscribeBulk today. MXAccess COM has no native bulk API; the worker
runs each bulk operation as a sequential loop on its STA, returning
one BulkWriteResult / BulkReadResult per requested entry so per-item
MXAccess failures surface as was_successful=false rather than throwing.

ReadBulk has no MXAccess analogue. The worker satisfies it by:

  - Returning the last cached OnDataChange payload (was_cached=true)
    when the requested tag is already in the session''s item registry
    AND advised — the existing subscription is NOT touched, since the
    caller did not create it.
  - Otherwise taking the AddItem + Advise + wait-for-OnDataChange +
    UnAdvise + RemoveItem snapshot lifecycle itself (was_cached=false)
    and leaving the session exactly as it was. The wait pumps Windows
    messages on the STA so the inbound MXAccess event can dispatch
    while the executor still holds the thread.

The new MxAccessValueCache lives on each MxAccessSession, shared with
MxAccessBaseEventSink which populates it on every OnDataChange after
the event clears the outbound queue. Eviction on RemoveItem keeps
reused MXAccess handles from serving stale values from a previous
lifetime.

Gateway-side authorization wires WriteBulk/Write2Bulk to invoke:write,
WriteSecuredBulk/WriteSecured2Bulk to invoke:secure, ReadBulk to
invoke:read. The constraint-filter pipeline is refactored from a single
BulkConstraintPlan record into an abstract base plus three concretes
(SubscribeBulk, WriteBulk, ReadBulk), each owning its own denied-entry
merge so the dispatch site never branches on reply shape. A new
FilterWriteBulkAsync<TEntry> generic over the four write-entry shapes
runs CheckWriteHandleAsync per entry; denied entries surface as the
BulkWriteResult shape, preserving original-index order.

All five language clients (.NET, Go, Rust, Python, Java) gained the
five new methods following their existing bulk pattern, with regenerated
protobufs.

Tests added:
  - MxAccessValueCacheTests (6 cases) — Set/TryGet, Remove resets the
    version, TryWaitForUpdate signals on Set, pump step fires each poll.
  - MxAccessBaseEventSinkTests — OnDataChange populates the cache,
    ValueCache property exposes the bound instance.
  - MxAccessCommandExecutorTests — four bulk-write variants (per-entry
    success/failure, value+timestamp forwarding, secured user ids),
    ReadBulk snapshot lifecycle on uncached tag (timeout surfaces as
    was_successful=false), invalid-payload reply.
  - GatewayGrpcScopeResolverTests — five new MxCommandKind cases.
  - SessionManagerTests — WriteBulk and ReadBulk forwarding through
    FakeWorkerHarness; ReadBulk forwards timeout_ms.
  - Per-client (.NET, Go, Rust, Python, Java) — WriteBulk builds the
    right command and returns per-entry results, ReadBulk forwards the
    timeout and unpacks the was_cached flag.

Cross-language e2e CLI subcommands for the new bulks are deliberately
scoped out of this change (each of the five client CLIs would need
five new subcommands plus matching phases in
scripts/run-client-e2e-tests.ps1); coverage equivalent to the existing
bulk-subscribe coverage is provided by worker + gateway + per-client
unit tests.

Docs updated in the same commit: gateway.md (Public MXAccess Command
Surface), docs/DesignDecisions.md (new "Bulk Command Family" section
with the ReadBulk cache-then-snapshot rationale), and every client
README.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

clients/dotnet/MxGateway.Client.Tests/MxGatewayClientSessionTests.cs

@@ -184,6 +184,96 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal(["Area001.Pump001.Speed"], request.Command.SubscribeBulk.TagAddresses);
     }
 
+    /// <summary>
+    /// Verifies that WriteBulk builds one command carrying the entry list verbatim
+    /// and returns the per-entry BulkWriteResult list without throwing on per-entry
+    /// failures.
+    /// </summary>
+    [Fact]
+    public async Task WriteBulkAsync_BuildsOneBulkCommandAndReturnsPerEntryResults()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.AddInvokeReply(new MxCommandReply
+        {
+            SessionId = "session-fixture",
+            Kind = MxCommandKind.WriteBulk,
+            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+            WriteBulk = new BulkWriteReply
+            {
+                Results =
+                {
+                    new BulkWriteResult { ServerHandle = 12, ItemHandle = 901, WasSuccessful = true },
+                    new BulkWriteResult { ServerHandle = 12, ItemHandle = 902, WasSuccessful = false, ErrorMessage = "Invalid handle" },
+                },
+            },
+        });
+        await using MxGatewayClient client = CreateClient(transport);
+        MxGatewaySession session = await client.OpenSessionAsync();
+
+        IReadOnlyList<BulkWriteResult> results = await session.WriteBulkAsync(
+            12,
+            new[]
+            {
+                new WriteBulkEntry { ItemHandle = 901, UserId = 5, Value = new MxValue { DataType = MxDataType.Integer, Int32Value = 11 } },
+                new WriteBulkEntry { ItemHandle = 902, UserId = 5, Value = new MxValue { DataType = MxDataType.Integer, Int32Value = 22 } },
+            });
+
+        Assert.Equal(2, results.Count);
+        Assert.True(results[0].WasSuccessful);
+        Assert.False(results[1].WasSuccessful);
+        MxCommandRequest request = Assert.Single(transport.InvokeCalls).Request;
+        Assert.Equal(MxCommandKind.WriteBulk, request.Command.Kind);
+        Assert.Equal(12, request.Command.WriteBulk.ServerHandle);
+        Assert.Equal(2, request.Command.WriteBulk.Entries.Count);
+        Assert.Equal(901, request.Command.WriteBulk.Entries[0].ItemHandle);
+    }
+
+    /// <summary>
+    /// Verifies that ReadBulk forwards the timeout to the gateway as milliseconds
+    /// and unpacks the BulkReadReply payload's was_cached / value fields.
+    /// </summary>
+    [Fact]
+    public async Task ReadBulkAsync_ForwardsTimeoutAndUnpacksCachedFlag()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.AddInvokeReply(new MxCommandReply
+        {
+            SessionId = "session-fixture",
+            Kind = MxCommandKind.ReadBulk,
+            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+            ReadBulk = new BulkReadReply
+            {
+                Results =
+                {
+                    new BulkReadResult
+                    {
+                        ServerHandle = 12,
+                        TagAddress = "Area001.Pump001.Speed",
+                        ItemHandle = 901,
+                        WasSuccessful = true,
+                        WasCached = true,
+                        Value = new MxValue { DataType = MxDataType.Integer, Int32Value = 99 },
+                    },
+                },
+            },
+        });
+        await using MxGatewayClient client = CreateClient(transport);
+        MxGatewaySession session = await client.OpenSessionAsync();
+
+        IReadOnlyList<BulkReadResult> results = await session.ReadBulkAsync(
+            12,
+            ["Area001.Pump001.Speed"],
+            TimeSpan.FromMilliseconds(750));
+
+        BulkReadResult result = Assert.Single(results);
+        Assert.True(result.WasCached);
+        Assert.Equal(99, result.Value.Int32Value);
+        MxCommandRequest request = Assert.Single(transport.InvokeCalls).Request;
+        Assert.Equal(MxCommandKind.ReadBulk, request.Command.Kind);
+        Assert.Equal(750u, request.Command.ReadBulk.TimeoutMs);
+        Assert.Equal(["Area001.Pump001.Speed"], request.Command.ReadBulk.TagAddresses);
+    }
+
     /// <summary>Verifies that stream events yields events in the order received from the gateway.</summary>
     [Fact]
     public async Task StreamEventsAsync_YieldsEventsInGatewayOrder()

clients/dotnet/MxGateway.Client/MxGatewaySession.cs

@@ -527,6 +527,142 @@ public sealed class MxGatewaySession : IAsyncDisposable
         return reply.UnsubscribeBulk?.Results.ToArray() ?? [];
     }
 
+    /// <summary>
+    /// Bulk Write — sequential MXAccess Write per entry on the worker's STA.
+    /// Per-item failures appear as BulkWriteResult entries with
+    /// <c>WasSuccessful = false</c>; the call never throws on per-item errors.
+    /// Protocol-level failures still throw via EnsureProtocolSuccess.
+    /// </summary>
+    public async Task<IReadOnlyList<BulkWriteResult>> WriteBulkAsync(
+        int serverHandle,
+        IReadOnlyList<WriteBulkEntry> entries,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(entries);
+
+        WriteBulkCommand command = new() { ServerHandle = serverHandle };
+        command.Entries.Add(entries);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.WriteBulk,
+                    WriteBulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.WriteBulk?.Results.ToArray() ?? [];
+    }
+
+    /// <summary>Bulk Write2 — sequential MXAccess Write2 (timestamped) per entry.</summary>
+    public async Task<IReadOnlyList<BulkWriteResult>> Write2BulkAsync(
+        int serverHandle,
+        IReadOnlyList<Write2BulkEntry> entries,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(entries);
+
+        Write2BulkCommand command = new() { ServerHandle = serverHandle };
+        command.Entries.Add(entries);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.Write2Bulk,
+                    Write2Bulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.Write2Bulk?.Results.ToArray() ?? [];
+    }
+
+    /// <summary>
+    /// Bulk WriteSecured — sequential MXAccess WriteSecured per entry.
+    /// Credential-sensitive values must never reach logs; the client mirrors
+    /// the single-item WriteSecured redaction contract.
+    /// </summary>
+    public async Task<IReadOnlyList<BulkWriteResult>> WriteSecuredBulkAsync(
+        int serverHandle,
+        IReadOnlyList<WriteSecuredBulkEntry> entries,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(entries);
+
+        WriteSecuredBulkCommand command = new() { ServerHandle = serverHandle };
+        command.Entries.Add(entries);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.WriteSecuredBulk,
+                    WriteSecuredBulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.WriteSecuredBulk?.Results.ToArray() ?? [];
+    }
+
+    /// <summary>Bulk WriteSecured2 — sequential MXAccess WriteSecured2 (timestamped) per entry.</summary>
+    public async Task<IReadOnlyList<BulkWriteResult>> WriteSecured2BulkAsync(
+        int serverHandle,
+        IReadOnlyList<WriteSecured2BulkEntry> entries,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(entries);
+
+        WriteSecured2BulkCommand command = new() { ServerHandle = serverHandle };
+        command.Entries.Add(entries);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.WriteSecured2Bulk,
+                    WriteSecured2Bulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.WriteSecured2Bulk?.Results.ToArray() ?? [];
+    }
+
+    /// <summary>
+    /// Bulk Read — snapshot the current value for each requested tag.
+    /// Returns the cached OnDataChange value when the tag is already advised
+    /// (was_cached = true), otherwise the worker takes the full AddItem +
+    /// Advise + wait + UnAdvise + RemoveItem snapshot lifecycle. Per-tag
+    /// failures (timeout, invalid tag) appear as BulkReadResult entries with
+    /// <c>WasSuccessful = false</c>; the call never throws on per-tag errors.
+    /// </summary>
+    public async Task<IReadOnlyList<BulkReadResult>> ReadBulkAsync(
+        int serverHandle,
+        IReadOnlyList<string> tagAddresses,
+        TimeSpan timeout,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(tagAddresses);
+
+        ReadBulkCommand command = new()
+        {
+            ServerHandle = serverHandle,
+            TimeoutMs = timeout <= TimeSpan.Zero ? 0u : (uint)Math.Min(timeout.TotalMilliseconds, uint.MaxValue),
+        };
+        command.TagAddresses.Add(tagAddresses);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.ReadBulk,
+                    ReadBulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.ReadBulk?.Results.ToArray() ?? [];
+    }
+
     /// <summary>
     /// Writes a value to an item on the MXAccess server.
     /// </summary>

clients/dotnet/README.md

@@ -84,6 +84,48 @@ messages. `MxGatewaySession.OpenSessionReply` keeps the raw session-open reply
 available, and command helpers have `*RawAsync` variants when callers need the
 complete `MxCommandReply`.
 
+### Bulk Commands
+
+The session exposes bulk variants for every command family that has one
+upstream — they all carry a list of entries in one gRPC round-trip, 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
+`WasSuccessful = false` with the underlying HRESULT and never throw; only
+protocol-level failures throw via `EnsureProtocolSuccess`.
+
+```csharp
+// Subscribe + Unsubscribe to a batch of tags in one round-trip
+IReadOnlyList<SubscribeResult> subResults = await session.SubscribeBulkAsync(
+    serverHandle,
+    new[] { "Area001.Pump001.Speed", "Area001.Pump001.RunHours" });
+int[] itemHandles = subResults.Where(r => r.WasSuccessful).Select(r => r.ItemHandle).ToArray();
+await session.UnsubscribeBulkAsync(serverHandle, itemHandles);
+
+// Bulk Write — sequential MXAccess Write per entry.
+IReadOnlyList<BulkWriteResult> writeResults = await session.WriteBulkAsync(
+    serverHandle,
+    new[]
+    {
+        new WriteBulkEntry { ItemHandle = h1, UserId = 0, Value = 1.0.ToMxValue() },
+        new WriteBulkEntry { ItemHandle = h2, UserId = 0, Value = 2.0.ToMxValue() },
+    });
+foreach (BulkWriteResult r in writeResults.Where(r => !r.WasSuccessful))
+{
+    Console.Error.WriteLine($"item {r.ItemHandle}: {r.ErrorMessage}");
+}
+
+// Bulk Read — returns the cached OnDataChange value when the tag is already
+// advised (was_cached = true) or takes a one-shot snapshot otherwise.
+IReadOnlyList<BulkReadResult> readResults = await session.ReadBulkAsync(
+    serverHandle,
+    new[] { "Area001.Pump001.Speed", "Area001.Pump002.Speed" },
+    timeout: TimeSpan.FromMilliseconds(750));
+```
+
+`Write2BulkAsync`, `WriteSecuredBulkAsync`, and `WriteSecured2BulkAsync` follow
+the same shape; the secured variants additionally carry `CurrentUserId` and
+`VerifierUserId` per entry and require `invoke:secure` scope.
+
 `MxGatewaySession.CloseAsync` is explicit and idempotent. Repeated calls return
 the first `CloseSessionReply` instead of sending another close request.