Add bulk MXAccess subscription commands

docs/Contracts.md

@@ -10,6 +10,19 @@ recreated by the contracts project build.
 `MxAccessGateway` gRPC service, command payloads, command replies, event DTOs,
 `MxValue`, `MxArray`, and `MxStatusProxy`.
 
+The public command model includes bulk subscription command kinds for
+`AddItemBulk`, `AdviseItemBulk`, `RemoveItemBulk`, `UnAdviseItemBulk`,
+`SubscribeBulk`, and `UnsubscribeBulk`. These commands are normal unary
+`Invoke` payloads. They do not add separate gRPC methods, and they return a
+`BulkSubscribeReply` containing per-item `SubscribeResult` records with
+`ServerHandle`, `TagAddress`, `ItemHandle`, `WasSuccessful`, and
+`ErrorMessage`.
+
+The gateway forwards each bulk command as one worker command. The worker runs
+the corresponding MXAccess `AddItem`, `Advise`, `UnAdvise`, and `RemoveItem`
+calls sequentially on the session STA and preserves input order in the result
+list.
+
 `src/MxGateway.Contracts/Protos/mxaccess_worker.proto` defines the named-pipe
 worker IPC envelope and control messages. It imports
 `mxaccess_gateway.proto` so the worker and gateway use the same command, reply,

docs/client-libraries-design.md

@@ -106,6 +106,26 @@ session.close()
 client.close()
 ```
 
+Each language should expose the gateway bulk subscription commands with
+idiomatic names:
+
+```text
+session.addItemBulk(serverHandle, tagAddresses)
+session.adviseItemBulk(serverHandle, itemHandles)
+session.removeItemBulk(serverHandle, itemHandles)
+session.unAdviseItemBulk(serverHandle, itemHandles)
+session.subscribeBulk(serverHandle, tagAddresses)
+session.unsubscribeBulk(serverHandle, itemHandles)
+```
+
+These methods send one `Invoke` request using the matching bulk command kind.
+They return the gateway `SubscribeResult` list without inventing client-only
+handles. `SubscribeBulk` performs `AddItem` then `Advise` per tag inside the
+worker session. `UnsubscribeBulk` performs `UnAdvise` then `RemoveItem` per item
+handle. Per-item failures are returned in `SubscribeResult`; transport,
+gateway, and cancellation failures still use each language's normal error
+surface.
+
 Each library should also expose lower-level calls:
 
 ```text

docs/clients-dotnet-csharp-design.md

@@ -83,6 +83,12 @@ public sealed class MxGatewaySession : IAsyncDisposable
     public Task<int> AddItem2Async(int serverHandle, string item, string context, CancellationToken ct = default);
     public Task AdviseAsync(int serverHandle, int itemHandle, CancellationToken ct = default);
     public Task UnAdviseAsync(int serverHandle, int itemHandle, CancellationToken ct = default);
+    public Task<IReadOnlyList<SubscribeResult>> AddItemBulkAsync(int serverHandle, IReadOnlyList<string> tagAddresses, CancellationToken ct = default);
+    public Task<IReadOnlyList<SubscribeResult>> AdviseItemBulkAsync(int serverHandle, IReadOnlyList<int> itemHandles, CancellationToken ct = default);
+    public Task<IReadOnlyList<SubscribeResult>> RemoveItemBulkAsync(int serverHandle, IReadOnlyList<int> itemHandles, CancellationToken ct = default);
+    public Task<IReadOnlyList<SubscribeResult>> UnAdviseItemBulkAsync(int serverHandle, IReadOnlyList<int> itemHandles, CancellationToken ct = default);
+    public Task<IReadOnlyList<SubscribeResult>> SubscribeBulkAsync(int serverHandle, IReadOnlyList<string> tagAddresses, CancellationToken ct = default);
+    public Task<IReadOnlyList<SubscribeResult>> UnsubscribeBulkAsync(int serverHandle, IReadOnlyList<int> itemHandles, CancellationToken ct = default);
     public Task WriteAsync(int serverHandle, int itemHandle, MxValue value, int userId, CancellationToken ct = default);
     public IAsyncEnumerable<MxEvent> StreamEventsAsync(CancellationToken ct = default);
     public Task CloseAsync(CancellationToken ct = default);

docs/clients-golang-design.md

@@ -74,6 +74,12 @@ func (s *Session) Unregister(ctx context.Context, serverHandle int32) error
 func (s *Session) AddItem(ctx context.Context, serverHandle int32, item string) (int32, error)
 func (s *Session) AddItem2(ctx context.Context, serverHandle int32, item, context string) (int32, error)
 func (s *Session) Advise(ctx context.Context, serverHandle, itemHandle int32) error
+func (s *Session) AddItemBulk(ctx context.Context, serverHandle int32, tagAddresses []string) ([]*pb.SubscribeResult, error)
+func (s *Session) AdviseItemBulk(ctx context.Context, serverHandle int32, itemHandles []int32) ([]*pb.SubscribeResult, error)
+func (s *Session) RemoveItemBulk(ctx context.Context, serverHandle int32, itemHandles []int32) ([]*pb.SubscribeResult, error)
+func (s *Session) UnAdviseItemBulk(ctx context.Context, serverHandle int32, itemHandles []int32) ([]*pb.SubscribeResult, error)
+func (s *Session) SubscribeBulk(ctx context.Context, serverHandle int32, tagAddresses []string) ([]*pb.SubscribeResult, error)
+func (s *Session) UnsubscribeBulk(ctx context.Context, serverHandle int32, itemHandles []int32) ([]*pb.SubscribeResult, error)
 func (s *Session) Write(ctx context.Context, serverHandle, itemHandle int32, value Value, userID int32) error
 func (s *Session) Events(ctx context.Context) (<-chan EventResult, error)
 func (s *Session) Close(ctx context.Context) error

docs/clients-java-design.md

@@ -64,6 +64,12 @@ public final class MxGatewaySession implements AutoCloseable {
     public int addItem(int serverHandle, String item);
     public int addItem2(int serverHandle, String item, String context);
     public void advise(int serverHandle, int itemHandle);
+    public List<SubscribeResult> addItemBulk(int serverHandle, List<String> tagAddresses);
+    public List<SubscribeResult> adviseItemBulk(int serverHandle, List<Integer> itemHandles);
+    public List<SubscribeResult> removeItemBulk(int serverHandle, List<Integer> itemHandles);
+    public List<SubscribeResult> unAdviseItemBulk(int serverHandle, List<Integer> itemHandles);
+    public List<SubscribeResult> subscribeBulk(int serverHandle, List<String> tagAddresses);
+    public List<SubscribeResult> unsubscribeBulk(int serverHandle, List<Integer> itemHandles);
     public void write(int serverHandle, int itemHandle, MxValue value, int userId);
     public Iterator<MxEvent> streamEvents();
     public void streamEventsAsync(StreamObserver<MxEvent> observer);

docs/clients-python-design.md

@@ -82,6 +82,12 @@ class Session:
     async def add_item(self, server_handle: int, item: str) -> int: ...
     async def add_item2(self, server_handle: int, item: str, context: str) -> int: ...
     async def advise(self, server_handle: int, item_handle: int) -> None: ...
+    async def add_item_bulk(self, server_handle: int, tag_addresses: Sequence[str]) -> list[SubscribeResult]: ...
+    async def advise_item_bulk(self, server_handle: int, item_handles: Sequence[int]) -> list[SubscribeResult]: ...
+    async def remove_item_bulk(self, server_handle: int, item_handles: Sequence[int]) -> list[SubscribeResult]: ...
+    async def unadvise_item_bulk(self, server_handle: int, item_handles: Sequence[int]) -> list[SubscribeResult]: ...
+    async def subscribe_bulk(self, server_handle: int, tag_addresses: Sequence[str]) -> list[SubscribeResult]: ...
+    async def unsubscribe_bulk(self, server_handle: int, item_handles: Sequence[int]) -> list[SubscribeResult]: ...
     async def write(self, server_handle: int, item_handle: int, value: MxValueInput, user_id: int = 0) -> None: ...
     async def stream_events(self) -> AsyncIterator[MxEvent]: ...
     async def close(self) -> None: ...

docs/clients-rust-design.md

@@ -81,6 +81,12 @@ impl Session {
     pub async fn add_item(&self, server_handle: i32, item: &str) -> Result<i32, Error>;
     pub async fn add_item2(&self, server_handle: i32, item: &str, context: &str) -> Result<i32, Error>;
     pub async fn advise(&self, server_handle: i32, item_handle: i32) -> Result<(), Error>;
+    pub async fn add_item_bulk(&self, server_handle: i32, tag_addresses: Vec<String>) -> Result<Vec<SubscribeResult>, Error>;
+    pub async fn advise_item_bulk(&self, server_handle: i32, item_handles: Vec<i32>) -> Result<Vec<SubscribeResult>, Error>;
+    pub async fn remove_item_bulk(&self, server_handle: i32, item_handles: Vec<i32>) -> Result<Vec<SubscribeResult>, Error>;
+    pub async fn un_advise_item_bulk(&self, server_handle: i32, item_handles: Vec<i32>) -> Result<Vec<SubscribeResult>, Error>;
+    pub async fn subscribe_bulk(&self, server_handle: i32, tag_addresses: Vec<String>) -> Result<Vec<SubscribeResult>, Error>;
+    pub async fn unsubscribe_bulk(&self, server_handle: i32, item_handles: Vec<i32>) -> Result<Vec<SubscribeResult>, Error>;
     pub async fn write(&self, server_handle: i32, item_handle: i32, value: MxValue, user_id: i32) -> Result<(), Error>;
     pub async fn events(&self) -> Result<impl Stream<Item = Result<MxEvent, Error>>, Error>;
     pub async fn close(&self) -> Result<(), Error>;