Regenerate stale Java client protobuf code

The checked-in generated Java sources under clients/java/src/main/generated/
were out of sync with both the .proto contracts and the configured
protobuf 4.33.1 toolchain: they were missing the alarm command kinds
(MX_COMMAND_KIND_SUBSCRIBE_ALARMS..ACKNOWLEDGE_ALARM_BY_NAME, 25-29), the
alarm/galaxy message additions, and the protobuf 4.x generated-code layout.
Regenerated via `gradle generateProto`; `gradle test` passes against the
refreshed sources. No hand edits — pure protoc/protoc-gen-grpc-java output.

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

CLAUDE.md

@@ -32,7 +32,7 @@ dotnet test src/MxGateway.Worker.Tests/MxGateway.Worker.Tests.csproj -p:Platform
 dotnet run --project src/MxGateway.Server/MxGateway.Server.csproj
 
 # API-key admin CLI (same exe, "apikey" subcommand)
-dotnet run --project src/MxGateway.Server/MxGateway.Server.csproj -- apikey create --display-name "dev" --scopes session,invoke,event,metadata,admin
+dotnet run --project src/MxGateway.Server/MxGateway.Server.csproj -- apikey create --display-name "dev" --scopes session:open,session:close,invoke:read,invoke:write,invoke:secure,events:read,metadata:read,admin
 ```
 
 Single test by name (xUnit `--filter`):
@@ -114,9 +114,9 @@ External analysis sources referenced by design docs:
 
 ## Authentication
 
-Gateway gRPC clients authenticate with an API key in metadata: `authorization: Bearer mxgw_<key-id>_<secret>`. Keys are stored hashed (with a peppered SHA) in a gateway-owned SQLite DB (default `C:\ProgramData\MxGateway\gateway-auth.db`). Scopes (`session`, `invoke`, `event`, `metadata`, `admin`) gate specific RPCs; missing → `Unauthenticated`, insufficient → `PermissionDenied`. The `apikey` subcommand on the server exe manages keys; see `src/MxGateway.Server/Security/Authentication/`.
+Gateway gRPC clients authenticate with an API key in metadata: `authorization: Bearer mxgw_<key-id>_<secret>`. Keys are stored hashed (with a peppered SHA) in a gateway-owned SQLite DB (default `C:\ProgramData\MxGateway\gateway-auth.db`). Scopes (`session:open`, `session:close`, `invoke:read`, `invoke:write`, `invoke:secure`, `events:read`, `metadata:read`, `admin`) gate specific RPCs; missing → `Unauthenticated`, insufficient → `PermissionDenied`. The `apikey` subcommand on the server exe manages keys; see `src/MxGateway.Server/Security/Authentication/`.
 
-Dashboard auth is LDAP-backed (separate from the gRPC API-key model). `/login` binds against `MxGateway:Ldap` and maps the user's LDAP groups to `Admin` or `Viewer` via `MxGateway:Dashboard:GroupToRole`, then issues an HTTP-only secure `__Host-MxGatewayDashboard` cookie. SignalR hubs at `/hubs/{snapshot,alarms,events}` accept either the cookie or a 30-minute bearer minted at `/hubs/token`. `Dashboard:AllowAnonymousLocalhost` bypasses auth on loopback when enabled.
+Dashboard auth uses the same verifier but exchanges the API key for an HTTP-only secure cookie at `/dashboard/login`. `Dashboard:AllowAnonymousLocalhost` bypasses cookie auth on loopback when explicitly enabled.
 
 ## Process / Platform Notes
 

REVIEW-PROCESS.md

@@ -0,0 +1,140 @@
+# Code Review Process
+
+This document describes how to perform a comprehensive, per-module code review of
+the `mxaccessgw` codebase and how to track findings to resolution.
+
+A **module** is one buildable project under `src/` (e.g. `src/MxGateway.Worker`)
+or one language client under `clients/` (e.g. `clients/rust`). Each module has
+its own folder under `code-reviews/` containing a single `findings.md`.
+
+## 1. Before you start
+
+1. Pick the module to review. Its folder is `code-reviews/<Module>/`:
+   - For a `src/` project, `<Module>` is the project name with the `MxGateway.`
+     prefix stripped — `src/MxGateway.Server` is reviewed in `code-reviews/Server/`.
+   - For a language client, `<Module>` is `Client.<Lang>` — `clients/rust` is
+     reviewed in `code-reviews/Client.Rust/`.
+2. Identify the design context for the module:
+   - `gateway.md` — top-level architecture, command/event surface, IPC envelope,
+     STA thread model, fault handling.
+   - The relevant component design docs under `docs/` (e.g.
+     `docs/MxAccessWorkerInstanceDesign.md`, `docs/GatewayProcessDesign.md`,
+     `docs/Sessions.md`, `docs/Authentication.md`, `docs/GalaxyRepository.md`).
+   - `docs/DesignDecisions.md` for the v1 design choices.
+   - The **Repository-Specific Conventions** and **Process / Platform Notes** in
+     `CLAUDE.md`.
+3. Record the exact commit being reviewed: `git rev-parse --short HEAD`. Every
+   review is a snapshot — a finding only means something relative to a known
+   commit.
+4. Open `code-reviews/<Module>/findings.md` and fill in the header table
+   (reviewer, date, commit SHA, status).
+
+## 2. Review checklist
+
+Work through **every** category below for the module. A comprehensive review
+means the checklist is completed even where it produces no findings — record
+"No issues found" for a category rather than leaving it ambiguous.
+
+1. **Correctness & logic bugs** — off-by-one, null handling, incorrect
+   conditionals, misuse of APIs, broken edge cases.
+2. **mxaccessgw conventions** — the rules in `CLAUDE.md` and the style guides
+   under `docs/style-guides/`: the gateway never instantiates MXAccess COM
+   directly; all MXAccess COM calls run on the worker's dedicated STA thread and
+   the STA loop pumps Windows messages; IPC uses one bidirectional named pipe per
+   worker carrying length-prefixed `WorkerEnvelope` protobuf frames; MXAccess
+   parity is the contract (don't "fix" surprising MXAccess behaviour, never
+   synthesize events); one worker and one event subscriber per session; the
+   gateway terminates orphan workers on startup and does not reattach; C# style
+   (file-scoped namespaces, `sealed` by default, `Async` suffix, MXAccess-aligned
+   names); no Blazor UI component libraries; no logging of secrets or full tag
+   values; generated code is never hand-edited.
+3. **Concurrency & thread safety** — shared mutable state, STA affinity, race
+   conditions, correct use of `async`/`await`, locking, disposal races.
+4. **Error handling & resilience** — exception paths, worker crash / reconnect
+   handling, fail-fast event backpressure, transient vs permanent error
+   classification, graceful degradation, correct gRPC status codes.
+5. **Security** — authentication/authorization checks, API-key scope enforcement,
+   input validation, SQL injection in the Galaxy Repository RPCs, secret
+   handling, the dashboard anonymous-localhost bypass, logging of sensitive data.
+6. **Performance & resource management** — `IDisposable` disposal, pipe / stream
+   / COM lifetimes, buffering and back-pressure, unnecessary allocations on hot
+   paths, N+1 queries.
+7. **Design-document adherence** — does the code match `gateway.md`, the relevant
+   `docs/` component designs, `docs/DesignDecisions.md`, and `CLAUDE.md`? Flag
+   both code that drifts from the design and design docs that are now stale.
+8. **Code organization & conventions** — namespace hierarchy, project layout, the
+   Options pattern, separation of concerns, additive-only contract evolution.
+9. **Testing coverage** — are the module's behaviours covered by tests
+   (`src/MxGateway.Tests`, `src/MxGateway.Worker.Tests`,
+   `src/MxGateway.IntegrationTests`)? Note untested critical paths and missing
+   edge-case tests.
+10. **Documentation & comments** — XML doc accuracy, misleading or stale comments,
+    undocumented non-obvious behaviour.
+
+## 3. Recording findings
+
+Add one entry per finding to the `## Findings` section of the module's
+`findings.md`, using the entry format in
+[`_template/findings.md`](code-reviews/_template/findings.md).
+
+- **Finding ID** — `<Module>-NNN`, numbered sequentially within the module and
+  never reused (e.g. `Worker-001`). IDs are permanent even after resolution.
+- **Severity:**
+  - **Critical** — data loss, security breach, crash/deadlock, or outage.
+  - **High** — incorrect behaviour with significant impact; no safe workaround.
+  - **Medium** — incorrect or risky behaviour with limited impact or a workaround.
+  - **Low** — minor issues, style, maintainability, documentation.
+- **Category** — one of the 10 checklist categories above.
+- **Location** — `file:line` (clickable), or a list of locations.
+- **Description** — what is wrong and why it matters.
+- **Recommendation** — concrete suggested fix.
+
+After recording findings, update the module header table (status, open-finding
+count) and regenerate the base README (step 5).
+
+## 4. Marking an item resolved
+
+Findings are **never deleted** — they are an audit trail. To close one, change
+its **Status** and complete the **Resolution** field:
+
+- `Open` — newly recorded, not yet addressed.
+- `In Progress` — a fix is actively being worked on.
+- `Resolved` — fixed. The Resolution field must state the fixing commit SHA, the
+  date, and a one-line description of the fix.
+- `Won't Fix` — intentionally not fixed. The Resolution field must justify why.
+- `Deferred` — valid but postponed. The Resolution field must say what it is
+  waiting on (e.g. a tracked issue or a later milestone).
+
+`Resolved`, `Won't Fix`, and `Deferred` findings are all considered **closed**.
+`Open` and `In Progress` are **pending** and appear in the base README's Pending
+Findings table.
+
+## 5. Updating the base README
+
+`code-reviews/README.md` holds the single cross-module view (the Module Status
+table and the Pending / Closed Findings tables). It is **generated** from the
+per-module `findings.md` files — do not edit it by hand.
+
+After any review or status change, regenerate it:
+
+```
+python code-reviews/regen-readme.py
+```
+
+`regen-readme.py --check` exits non-zero if `README.md` is stale, if a module
+header's `Open findings` count disagrees with its finding statuses, or if a
+finding carries an unrecognised Status value. The PowerShell wrapper
+`scripts/check-code-reviews-readme.ps1` runs that check and is the intended hook
+for CI or a pre-commit step.
+
+> The repo's installed `python` is the real interpreter; the bare `python3`
+> alias resolves to the Windows Store stub and fails. Use `python`.
+
+The per-module `findings.md` files are the source of truth; `README.md` is the
+aggregated index and must always agree with them — which the script guarantees.
+
+## 6. Re-reviewing a module
+
+Re-reviews append to the same `findings.md`. Update the header to the new commit
+and date, continue the finding numbering from the last used ID, and leave prior
+findings (including closed ones) in place as history.

clients/dotnet/DotnetClientDesign.md

@@ -16,9 +16,9 @@ Recommended layout:
 
 ```text
 clients/dotnet/
-  ZB.MOM.WW.MxGateway.Client.slnx
+  MxGateway.Client.sln
-  ZB.MOM.WW.MxGateway.Client/
+  MxGateway.Client/
-    ZB.MOM.WW.MxGateway.Client.csproj
+    MxGateway.Client.csproj
     GatewayClient.cs
     MxGatewaySession.cs
     MxGatewayClientOptions.cs
@@ -26,14 +26,14 @@ clients/dotnet/
     Conversion/
     Errors/
     Generated/
-  ZB.MOM.WW.MxGateway.Client.Cli/
+  MxGateway.Client.Cli/
-    ZB.MOM.WW.MxGateway.Client.Cli.csproj
+    MxGateway.Client.Cli.csproj
     Program.cs
     Commands/
-  ZB.MOM.WW.MxGateway.Client.Tests/
+  MxGateway.Client.Tests/
-    ZB.MOM.WW.MxGateway.Client.Tests.csproj
+    MxGateway.Client.Tests.csproj
-  ZB.MOM.WW.MxGateway.Client.IntegrationTests/
+  MxGateway.Client.IntegrationTests/
-    ZB.MOM.WW.MxGateway.Client.IntegrationTests.csproj
+    MxGateway.Client.IntegrationTests.csproj
 ```
 
 Target framework:
@@ -43,7 +43,7 @@ Target framework:
 ```
 
 The scaffold uses a project reference to
-`src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj` for generated protobuf and
+`src/MxGateway.Contracts/MxGateway.Contracts.csproj` for generated protobuf and
 gRPC types. `clients/dotnet/generated` remains reserved for client-local
 generator output if the .NET client later needs to decouple from the contracts
 project.
@@ -166,7 +166,7 @@ reply.EnsureMxAccessSuccess();
 
 ## Test CLI
 
-Project: `ZB.MOM.WW.MxGateway.Client.Cli`.
+Project: `MxGateway.Client.Cli`.
 
 Command examples:
 

clients/dotnet/MxGateway.Client.Cli/CliArguments.cs

@@ -1,6 +1,6 @@
 using System.Globalization;
 
-namespace ZB.MOM.WW.MxGateway.Client.Cli;
+namespace MxGateway.Client.Cli;
 
 /// <summary>Parses command-line arguments into flags and named values.</summary>
 internal sealed class CliArguments

clients/dotnet/MxGateway.Client.Cli/IMxGatewayCliClient.cs

@@ -1,7 +1,7 @@
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
-using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+using MxGateway.Contracts.Proto.Galaxy;
 
-namespace ZB.MOM.WW.MxGateway.Client.Cli;
+namespace MxGateway.Client.Cli;
 
 public interface IMxGatewayCliClient : IAsyncDisposable
 {

clients/dotnet/MxGateway.Client.Cli/MxGateway.Client.Cli.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <ItemGroup>
-    <ProjectReference Include="..\ZB.MOM.WW.MxGateway.Client\ZB.MOM.WW.MxGateway.Client.csproj" />
+    <ProjectReference Include="..\MxGateway.Client\MxGateway.Client.csproj" />
   </ItemGroup>
 
   <PropertyGroup>

clients/dotnet/MxGateway.Client.Cli/MxGatewayCliClientAdapter.cs

@@ -1,8 +1,8 @@
-using ZB.MOM.WW.MxGateway.Client;
+using MxGateway.Client;
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
-using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+using MxGateway.Contracts.Proto.Galaxy;
 
-namespace ZB.MOM.WW.MxGateway.Client.Cli;
+namespace MxGateway.Client.Cli;
 
 internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
 {

clients/dotnet/MxGateway.Client.Cli/MxGatewayCliSecretRedactor.cs

@@ -1,4 +1,4 @@
-namespace ZB.MOM.WW.MxGateway.Client.Cli;
+namespace MxGateway.Client.Cli;
 
 /// <summary>Utility to redact API keys from error messages for safe output.</summary>
 internal static class MxGatewayCliSecretRedactor

clients/dotnet/MxGateway.Client.Cli/MxGatewayClientCli.cs

@@ -1,11 +1,11 @@
 using System.Globalization;
 using System.Text.Json;
 using Google.Protobuf;
-using ZB.MOM.WW.MxGateway.Client;
+using MxGateway.Client;
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
-using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+using MxGateway.Contracts.Proto.Galaxy;
 
-namespace ZB.MOM.WW.MxGateway.Client.Cli;
+namespace MxGateway.Client.Cli;
 
 /// <summary>Command-line interface for the MXAccess Gateway client, supporting session and command operations.</summary>
 public static class MxGatewayClientCli
@@ -122,7 +122,10 @@ public static class MxGatewayClientCli
         }
         catch (Exception exception) when (exception is not OperationCanceledException)
         {
-            string? apiKey = arguments.GetOptional("api-key");
+            // Redact the effective API key — whether it came from --api-key or from
+            // the (documented default) --api-key-env environment variable — so a
+            // transport error message that echoes the bearer token is never printed.
+            string? apiKey = TryResolveApiKey(arguments);
             string message = MxGatewayCliSecretRedactor.Redact(exception.Message, apiKey);
 
             if (arguments.HasFlag("json"))
@@ -167,6 +170,27 @@ public static class MxGatewayClientCli
     }
 
     private static string ResolveApiKey(CliArguments arguments)
+    {
+        string? apiKey = TryResolveApiKey(arguments);
+        if (!string.IsNullOrWhiteSpace(apiKey))
+        {
+            return apiKey;
+        }
+
+        string apiKeyEnvironmentName = arguments.GetOptional("api-key-env")
+            ?? "MXGATEWAY_API_KEY";
+
+        throw new ArgumentException(
+            $"Gateway API key is required. Pass --api-key or set {apiKeyEnvironmentName}.");
+    }
+
+    /// <summary>
+    /// Resolves the effective API key from <c>--api-key</c> or, failing that, the
+    /// environment variable named by <c>--api-key-env</c> (default
+    /// <c>MXGATEWAY_API_KEY</c>). Returns <see langword="null"/> when no key is
+    /// configured; used for redaction where a missing key must not throw.
+    /// </summary>
+    private static string? TryResolveApiKey(CliArguments arguments)
     {
         string? apiKey = arguments.GetOptional("api-key");
         if (!string.IsNullOrWhiteSpace(apiKey))
@@ -177,14 +201,7 @@ public static class MxGatewayClientCli
         string apiKeyEnvironmentName = arguments.GetOptional("api-key-env")
             ?? "MXGATEWAY_API_KEY";
 
-        apiKey = Environment.GetEnvironmentVariable(apiKeyEnvironmentName);
+        return Environment.GetEnvironmentVariable(apiKeyEnvironmentName);
-        if (!string.IsNullOrWhiteSpace(apiKey))
-        {
-            return apiKey;
-        }
-
-        throw new ArgumentException(
-            $"Gateway API key is required. Pass --api-key or set {apiKeyEnvironmentName}.");
     }
 
     private static CancellationTokenSource CreateCancellation(CliArguments arguments, string command)

clients/dotnet/MxGateway.Client.Cli/Program.cs

@@ -1,3 +1,3 @@
-using ZB.MOM.WW.MxGateway.Client.Cli;
+using MxGateway.Client.Cli;
 
 return await MxGatewayClientCli.RunAsync(args, Console.Out, Console.Error);

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

@@ -1,7 +1,7 @@
 using Grpc.Core;
-using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+using MxGateway.Contracts.Proto.Galaxy;
 
-namespace ZB.MOM.WW.MxGateway.Client.Tests;
+namespace MxGateway.Client.Tests;
 
 /// <summary>
 /// Fake Galaxy Repository client transport for testing.

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

@@ -1,7 +1,7 @@
 using Grpc.Core;
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client.Tests;
+namespace MxGateway.Client.Tests;
 
 /// <summary>
 /// Fake implementation of IMxGatewayClientTransport for testing.
@@ -91,6 +91,19 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
     /// </summary>
     public Queue<Exception> CloseSessionExceptions { get; } = new();
 
+    /// <summary>
+    /// Gets or sets a value indicating whether thrown <see cref="RpcException"/>s are mapped
+    /// to <see cref="MxGatewayException"/> the way the production gRPC transport does. Lets
+    /// retry tests exercise the wrapped-exception predicate branch that runs in production.
+    /// </summary>
+    public bool MapTransportExceptions { get; set; }
+
+    /// <summary>
+    /// Gets or sets an optional hook awaited inside CloseSessionAsync after the call is
+    /// recorded; lets tests pause a close mid-flight to observe concurrent dispose.
+    /// </summary>
+    public Func<Task>? CloseSessionHook { get; set; }
+
     /// <summary>
     /// Gets the queue of exceptions to throw from InvokeAsync.
     /// </summary>
@@ -108,7 +121,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
         OpenSessionCalls.Add((request, callOptions));
         if (OpenSessionExceptions.TryDequeue(out Exception? exception))
         {
-            throw exception;
+            throw Translate(exception, callOptions);
         }
 
         return Task.FromResult(OpenSessionReply);
@@ -119,17 +132,23 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
     /// </summary>
     /// <param name="request">The CloseSessionRequest to process.</param>
     /// <param name="callOptions">Call options specifying RPC behavior.</param>
-    public Task<CloseSessionReply> CloseSessionAsync(
+    public async Task<CloseSessionReply> CloseSessionAsync(
         CloseSessionRequest request,
         CallOptions callOptions)
     {
         CloseSessionCalls.Add((request, callOptions));
-        if (CloseSessionExceptions.TryDequeue(out Exception? exception))
+
+        if (CloseSessionHook is not null)
         {
-            throw exception;
+            await CloseSessionHook().ConfigureAwait(false);
         }
 
-        return Task.FromResult(CloseSessionReply);
+        if (CloseSessionExceptions.TryDequeue(out Exception? exception))
+        {
+            throw Translate(exception, callOptions);
+        }
+
+        return CloseSessionReply;
     }
 
     /// <summary>
@@ -144,7 +163,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
         InvokeCalls.Add((request, callOptions));
         if (InvokeExceptions.TryDequeue(out Exception? exception))
         {
-            throw exception;
+            throw Translate(exception, callOptions);
         }
 
         return Task.FromResult(_invokeReplies.Dequeue());
@@ -204,6 +223,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
             ? _acknowledgeReplies.Dequeue()
             : new AcknowledgeAlarmReply
             {
+                SessionId = request.SessionId,
                 CorrelationId = request.ClientCorrelationId,
                 ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
                 Status = new MxStatusProxy { Success = 1, Category = MxStatusCategory.Ok },
@@ -238,4 +258,18 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
     {
         _activeAlarmSnapshots.Add(snapshot);
     }
+
+    /// <summary>
+    /// Maps a queued exception the way the production gRPC transport does when
+    /// <see cref="MapTransportExceptions"/> is set; otherwise returns it unchanged.
+    /// </summary>
+    private Exception Translate(Exception exception, CallOptions callOptions)
+    {
+        if (MapTransportExceptions && exception is RpcException rpcException)
+        {
+            return RpcExceptionMapper.Map(rpcException, callOptions.CancellationToken);
+        }
+
+        return exception;
+    }
 }

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

@@ -1,8 +1,8 @@
 using Google.Protobuf.WellKnownTypes;
 using Grpc.Core;
-using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+using MxGateway.Contracts.Proto.Galaxy;
 
-namespace ZB.MOM.WW.MxGateway.Client.Tests;
+namespace MxGateway.Client.Tests;
 
 public sealed class GalaxyRepositoryClientTests
 {

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

@@ -1,8 +1,8 @@
 using Google.Protobuf;
-using ZB.MOM.WW.MxGateway.Client;
+using MxGateway.Client;
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client.Tests;
+namespace MxGateway.Client.Tests;
 
 public sealed class MxCommandReplyExtensionsTests
 {

clients/dotnet/MxGateway.Client.Tests/MxGateway.Client.Tests.csproj

@@ -19,8 +19,8 @@
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\ZB.MOM.WW.MxGateway.Client\ZB.MOM.WW.MxGateway.Client.csproj" />
+    <ProjectReference Include="..\MxGateway.Client\MxGateway.Client.csproj" />
-    <ProjectReference Include="..\ZB.MOM.WW.MxGateway.Client.Cli\ZB.MOM.WW.MxGateway.Client.Cli.csproj" />
+    <ProjectReference Include="..\MxGateway.Client.Cli\MxGateway.Client.Cli.csproj" />
   </ItemGroup>
 
 </Project>

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

@@ -1,8 +1,8 @@
 using Google.Protobuf.WellKnownTypes;
 using Grpc.Core;
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client.Tests;
+namespace MxGateway.Client.Tests;
 
 /// <summary>
 ///     PR E.2 — pins the .NET SDK surface for the new alarm RPCs:
@@ -17,6 +17,7 @@ public sealed class MxGatewayClientAlarmsTests
         FakeGatewayTransport transport = CreateTransport();
         transport.AddAcknowledgeReply(new AcknowledgeAlarmReply
         {
+            SessionId = "session-fixture",
             CorrelationId = "corr-1",
             ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
             Status = new MxStatusProxy
@@ -30,6 +31,7 @@ public sealed class MxGatewayClientAlarmsTests
 
         AcknowledgeAlarmReply reply = await client.AcknowledgeAlarmAsync(new AcknowledgeAlarmRequest
         {
+            SessionId = "session-fixture",
             ClientCorrelationId = "corr-1",
             AlarmFullReference = "Tank01.Level.HiHi",
             Comment = "investigating",
@@ -62,6 +64,7 @@ public sealed class MxGatewayClientAlarmsTests
             client.AcknowledgeAlarmAsync(
                 new AcknowledgeAlarmRequest
                 {
+                    SessionId = "session-fixture",
                     AlarmFullReference = "Tank01.Level.HiHi",
                     Comment = string.Empty,
                     OperatorUser = "alice",
@@ -86,6 +89,7 @@ public sealed class MxGatewayClientAlarmsTests
         var ex = await Assert.ThrowsAsync<RpcException>(
             () => client.AcknowledgeAlarmAsync(new AcknowledgeAlarmRequest
             {
+                SessionId = "session-fixture",
                 AlarmFullReference = "Tank01.Level.HiHi",
                 Comment = string.Empty,
                 OperatorUser = "alice",

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

@@ -1,9 +1,9 @@
 using Google.Protobuf.WellKnownTypes;
-using ZB.MOM.WW.MxGateway.Client.Cli;
+using MxGateway.Client.Cli;
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
-using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+using MxGateway.Contracts.Proto.Galaxy;
 
-namespace ZB.MOM.WW.MxGateway.Client.Tests;
+namespace MxGateway.Client.Tests;
 
 /// <summary>Tests for the CLI command interface.</summary>
 public sealed class MxGatewayClientCliTests
@@ -106,6 +106,43 @@ public sealed class MxGatewayClientCliTests
         Assert.Contains("[redacted]", error.ToString());
     }
 
+    /// <summary>
+    /// Verifies that error output redacts the API key even when it was sourced from
+    /// the <c>--api-key-env</c> environment variable rather than passed via
+    /// <c>--api-key</c> — the documented default credential path.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_ErrorOutput_RedactsApiKey_WhenSourcedFromEnvironmentVariable()
+    {
+        const string environmentVariableName = "MXGATEWAY_TEST_API_KEY_REDACT";
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+
+        Environment.SetEnvironmentVariable(environmentVariableName, "env-secret-api-key");
+        try
+        {
+            int exitCode = await MxGatewayClientCli.RunAsync(
+                [
+                    "open-session",
+                    "--endpoint",
+                    "http://localhost:5000",
+                    "--api-key-env",
+                    environmentVariableName,
+                ],
+                output,
+                error,
+                _ => throw new InvalidOperationException("boom env-secret-api-key"));
+
+            Assert.Equal(1, exitCode);
+            Assert.DoesNotContain("env-secret-api-key", error.ToString());
+            Assert.Contains("[redacted]", error.ToString());
+        }
+        finally
+        {
+            Environment.SetEnvironmentVariable(environmentVariableName, null);
+        }
+    }
+
     /// <summary>Verifies that stream-events with max-events limit stops output in non-JSON format.</summary>
     [Fact]
     public async Task RunAsync_StreamEvents_WithMaxEventsStopsNonJsonOutput()

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

@@ -1,6 +1,6 @@
-using ZB.MOM.WW.MxGateway.Contracts;
+using MxGateway.Contracts;
 
-namespace ZB.MOM.WW.MxGateway.Client.Tests;
+namespace MxGateway.Client.Tests;
 
 public sealed class MxGatewayClientContractInfoTests
 {

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

@@ -1,4 +1,4 @@
-namespace ZB.MOM.WW.MxGateway.Client.Tests;
+namespace MxGateway.Client.Tests;
 
 public sealed class MxGatewayClientOptionsTests
 {

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

@@ -1,7 +1,7 @@
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 using Grpc.Core;
 
-namespace ZB.MOM.WW.MxGateway.Client.Tests;
+namespace MxGateway.Client.Tests;
 
 /// <summary>Tests for MxGatewaySession and client command behavior.</summary>
 public sealed class MxGatewayClientSessionTests
@@ -231,6 +231,52 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal("session-fixture", call.Request.SessionId);
     }
 
+    /// <summary>
+    /// Verifies that disposing a session while other callers are concurrently inside
+    /// <see cref="MxGatewaySession.CloseAsync"/> — one holding the close lock and one
+    /// parked on it — never throws <see cref="ObjectDisposedException"/> into those
+    /// callers. The close lock must outlive every pending close.
+    /// </summary>
+    [Fact]
+    public async Task DisposeAsync_DoesNotRaceConcurrentCloseAsync()
+    {
+        for (int iteration = 0; iteration < 100; iteration++)
+        {
+            FakeGatewayTransport transport = CreateTransport();
+            using SemaphoreSlim firstCloseEntered = new(0, 1);
+            using SemaphoreSlim releaseFirstClose = new(0, 1);
+
+            // The first CloseAsync to reach the transport parks here while holding the
+            // session's close lock; later callers queue on the lock behind it.
+            transport.CloseSessionHook = async () =>
+            {
+                firstCloseEntered.Release();
+                await releaseFirstClose.WaitAsync().ConfigureAwait(false);
+                transport.CloseSessionHook = null;
+            };
+
+            await using MxGatewayClient client = CreateClient(transport);
+            MxGatewaySession session = await client.OpenSessionAsync();
+
+            // Holder enters CloseAsync, acquires the lock, and parks in the hook.
+            Task holder = Task.Run(() => session.CloseAsync());
+            await firstCloseEntered.WaitAsync();
+
+            // Waiter is parked on the close lock behind the holder.
+            Task waiter = Task.Run(() => session.CloseAsync());
+
+            // DisposeAsync runs concurrently; it must wait out both callers before
+            // disposing the close lock rather than tearing it down underneath them.
+            Task dispose = session.DisposeAsync().AsTask();
+
+            releaseFirstClose.Release();
+
+            await holder;
+            await waiter;
+            await dispose;
+        }
+    }
+
     /// <summary>Verifies that invoke retries safe diagnostic commands on transient RPC failure.</summary>
     [Fact]
     public async Task InvokeAsync_RetriesSafeDiagnosticCommandOnTransientGrpcFailure()
@@ -255,6 +301,35 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal(2, transport.InvokeCalls.Count);
     }
 
+    /// <summary>
+    /// Verifies that the retry pipeline still retries when the transport maps the raw
+    /// <see cref="RpcException"/> to an <see cref="MxGatewayException"/> before it reaches
+    /// the retry predicate — the wrapped-exception shape that production always produces.
+    /// </summary>
+    [Fact]
+    public async Task InvokeAsync_RetriesSafeDiagnosticCommand_WhenTransportMapsRpcException()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.MapTransportExceptions = true;
+        transport.InvokeExceptions.Enqueue(CreateTransientRpcException());
+        transport.AddInvokeReply(new MxCommandReply
+        {
+            SessionId = "session-fixture",
+            Kind = MxCommandKind.Ping,
+            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+        });
+        await using MxGatewayClient client = CreateClient(transport);
+        MxGatewaySession session = await client.OpenSessionAsync();
+
+        await session.InvokeAsync(new MxCommandRequest
+        {
+            SessionId = session.SessionId,
+            Command = new MxCommand { Kind = MxCommandKind.Ping, Ping = new PingCommand() },
+        });
+
+        Assert.Equal(2, transport.InvokeCalls.Count);
+    }
+
     /// <summary>Verifies that open session does not retry on transient RPC failure.</summary>
     [Fact]
     public async Task OpenSessionAsync_DoesNotRetryTransientGrpcFailure()
@@ -303,6 +378,84 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal(cancellation.Token, Assert.Single(transport.InvokeCalls).CallOptions.CancellationToken);
     }
 
+    /// <summary>
+    /// Verifies that a client-imposed <see cref="StatusCode.DeadlineExceeded"/> is not
+    /// retried. The deadline budget is shared across the whole safe-unary operation, so
+    /// an immediate retry would only fail again — the call must surface the failure.
+    /// </summary>
+    [Fact]
+    public async Task InvokeAsync_DoesNotRetrySafeDiagnosticCommand_OnDeadlineExceeded()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.InvokeExceptions.Enqueue(
+            new RpcException(new Status(StatusCode.DeadlineExceeded, "deadline exceeded")));
+        transport.AddInvokeReply(new MxCommandReply
+        {
+            SessionId = "session-fixture",
+            Kind = MxCommandKind.Ping,
+            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+        });
+        await using MxGatewayClient client = CreateClient(transport);
+        MxGatewaySession session = await client.OpenSessionAsync();
+
+        await Assert.ThrowsAsync<RpcException>(async () => await session.InvokeAsync(
+            new MxCommandRequest
+            {
+                SessionId = session.SessionId,
+                Command = new MxCommand { Kind = MxCommandKind.Ping, Ping = new PingCommand() },
+            }));
+
+        Assert.Single(transport.InvokeCalls);
+    }
+
+    /// <summary>
+    /// Verifies that a successful register reply missing the typed <c>register</c>
+    /// payload throws a descriptive <see cref="MxGatewayException"/> rather than
+    /// silently returning a zero server handle.
+    /// </summary>
+    [Fact]
+    public async Task RegisterAsync_Throws_WhenSuccessfulReplyMissingPayload()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.AddInvokeReply(new MxCommandReply
+        {
+            SessionId = "session-fixture",
+            Kind = MxCommandKind.Register,
+            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+        });
+        await using MxGatewayClient client = CreateClient(transport);
+        MxGatewaySession session = await client.OpenSessionAsync();
+
+        MxGatewayException exception = await Assert.ThrowsAsync<MxGatewayException>(
+            async () => await session.RegisterAsync("client-name"));
+
+        Assert.Contains("register", exception.Message, StringComparison.Ordinal);
+    }
+
+    /// <summary>
+    /// Verifies that a successful add-item reply missing the typed <c>add_item</c>
+    /// payload throws a descriptive <see cref="MxGatewayException"/> rather than
+    /// silently returning a zero item handle.
+    /// </summary>
+    [Fact]
+    public async Task AddItemAsync_Throws_WhenSuccessfulReplyMissingPayload()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.AddInvokeReply(new MxCommandReply
+        {
+            SessionId = "session-fixture",
+            Kind = MxCommandKind.AddItem,
+            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+        });
+        await using MxGatewayClient client = CreateClient(transport);
+        MxGatewaySession session = await client.OpenSessionAsync();
+
+        MxGatewayException exception = await Assert.ThrowsAsync<MxGatewayException>(
+            async () => await session.AddItemAsync(1, "Area.Pump.Speed"));
+
+        Assert.Contains("add_item", exception.Message, StringComparison.Ordinal);
+    }
+
     private static MxGatewayClient CreateClient(FakeGatewayTransport transport)
     {
         return new MxGatewayClient(transport.Options, transport);

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

@@ -1,4 +1,4 @@
-namespace ZB.MOM.WW.MxGateway.Client.Tests;
+namespace MxGateway.Client.Tests;
 
 public sealed class MxGatewayGeneratedContractTests
 {

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

@@ -1,9 +1,9 @@
 using System.Text.Json;
 using Google.Protobuf;
-using ZB.MOM.WW.MxGateway.Client;
+using MxGateway.Client;
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client.Tests;
+namespace MxGateway.Client.Tests;
 
 public sealed class MxStatusProxyExtensionsTests
 {

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

@@ -1,9 +1,9 @@
 using System.Text.Json;
 using Google.Protobuf;
-using ZB.MOM.WW.MxGateway.Client;
+using MxGateway.Client;
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client.Tests;
+namespace MxGateway.Client.Tests;
 
 public sealed class MxValueExtensionsTests
 {

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

@@ -0,0 +1,76 @@
+using Grpc.Core;
+
+namespace MxGateway.Client.Tests;
+
+/// <summary>Tests for the shared gRPC-to-native exception mapping used by the transports.</summary>
+public sealed class RpcExceptionMapperTests
+{
+    /// <summary>Verifies that an unauthenticated status maps to the authentication exception.</summary>
+    [Fact]
+    public void Map_UnauthenticatedStatus_ProducesAuthenticationException()
+    {
+        RpcException rpc = new(new Status(StatusCode.Unauthenticated, "no key"));
+
+        Exception mapped = RpcExceptionMapper.Map(rpc, CancellationToken.None);
+
+        MxGatewayAuthenticationException authentication =
+            Assert.IsType<MxGatewayAuthenticationException>(mapped);
+        Assert.Equal(StatusCode.Unauthenticated, authentication.StatusCode);
+    }
+
+    /// <summary>Verifies that a permission-denied status maps to the authorization exception.</summary>
+    [Fact]
+    public void Map_PermissionDeniedStatus_ProducesAuthorizationException()
+    {
+        RpcException rpc = new(new Status(StatusCode.PermissionDenied, "missing scope"));
+
+        Exception mapped = RpcExceptionMapper.Map(rpc, CancellationToken.None);
+
+        MxGatewayAuthorizationException authorization =
+            Assert.IsType<MxGatewayAuthorizationException>(mapped);
+        Assert.Equal(StatusCode.PermissionDenied, authorization.StatusCode);
+    }
+
+    /// <summary>Verifies that a cancelled status maps to OperationCanceledException.</summary>
+    [Fact]
+    public void Map_CancelledStatus_ProducesOperationCanceledException()
+    {
+        RpcException rpc = new(new Status(StatusCode.Cancelled, "cancelled"));
+
+        Exception mapped = RpcExceptionMapper.Map(rpc, CancellationToken.None);
+
+        Assert.IsType<OperationCanceledException>(mapped);
+    }
+
+    /// <summary>
+    /// Verifies that non-auth statuses surface the originating gRPC status code on the
+    /// mapped exception so callers can distinguish transient from permanent failures
+    /// without reflecting into InnerException.
+    /// </summary>
+    [Theory]
+    [InlineData(StatusCode.NotFound)]
+    [InlineData(StatusCode.InvalidArgument)]
+    [InlineData(StatusCode.ResourceExhausted)]
+    [InlineData(StatusCode.FailedPrecondition)]
+    [InlineData(StatusCode.Unavailable)]
+    [InlineData(StatusCode.Internal)]
+    public void Map_NonAuthStatus_CarriesStatusCodeOnMxGatewayException(StatusCode statusCode)
+    {
+        RpcException rpc = new(new Status(statusCode, "boom"));
+
+        Exception mapped = RpcExceptionMapper.Map(rpc, CancellationToken.None);
+
+        MxGatewayException gatewayException = Assert.IsType<MxGatewayException>(mapped);
+        Assert.Equal(statusCode, gatewayException.StatusCode);
+        Assert.Same(rpc, gatewayException.InnerException);
+    }
+
+    /// <summary>Verifies that an MxGatewayException built without a gRPC status reports a null StatusCode.</summary>
+    [Fact]
+    public void StatusCode_IsNull_WhenNoGrpcStatusProvided()
+    {
+        MxGatewayException gatewayException = new("plain failure");
+
+        Assert.Null(gatewayException.StatusCode);
+    }
+}

clients/dotnet/MxGateway.Client.sln

@@ -0,0 +1,76 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.31903.59
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Client", "MxGateway.Client\MxGateway.Client.csproj", "{7CF9ED88-1F32-4040-BEB1-D0902E304C70}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Contracts", "..\..\src\MxGateway.Contracts\MxGateway.Contracts.csproj", "{9AB807A8-0469-40F7-A000-D240F36B6E5D}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Client.Cli", "MxGateway.Client.Cli\MxGateway.Client.Cli.csproj", "{EB061E77-2475-4322-9257-3F2456DD141C}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Client.Tests", "MxGateway.Client.Tests\MxGateway.Client.Tests.csproj", "{B77B5A8E-0C53-4419-9BCD-227C9753A074}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Debug|x64 = Debug|x64
+		Debug|x86 = Debug|x86
+		Release|Any CPU = Release|Any CPU
+		Release|x64 = Release|x64
+		Release|x86 = Release|x86
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x64.Build.0 = Debug|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x86.Build.0 = Debug|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|Any CPU.Build.0 = Release|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x64.ActiveCfg = Release|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x64.Build.0 = Release|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x86.ActiveCfg = Release|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x86.Build.0 = Release|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x64.Build.0 = Debug|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x86.Build.0 = Debug|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|Any CPU.Build.0 = Release|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x64.ActiveCfg = Release|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x64.Build.0 = Release|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x86.ActiveCfg = Release|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x86.Build.0 = Release|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x64.Build.0 = Debug|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x86.Build.0 = Debug|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|Any CPU.Build.0 = Release|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x64.ActiveCfg = Release|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x64.Build.0 = Release|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x86.ActiveCfg = Release|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x86.Build.0 = Release|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x64.Build.0 = Debug|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x86.Build.0 = Debug|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x64.ActiveCfg = Release|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x64.Build.0 = Release|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x86.ActiveCfg = Release|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x86.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+EndGlobal

clients/dotnet/MxGateway.Client/DiscoverHierarchyOptions.cs

@@ -0,0 +1,24 @@
+namespace MxGateway.Client;
+
+public sealed record DiscoverHierarchyOptions
+{
+    public int? RootGobjectId { get; init; }
+
+    public string? RootTagName { get; init; }
+
+    public string? RootContainedPath { get; init; }
+
+    public int? MaxDepth { get; init; }
+
+    public IReadOnlyList<int> CategoryIds { get; init; } = Array.Empty<int>();
+
+    public IReadOnlyList<string> TemplateChainContains { get; init; } = Array.Empty<string>();
+
+    public string? TagNameGlob { get; init; }
+
+    public bool? IncludeAttributes { get; init; }
+
+    public bool AlarmBearingOnly { get; init; }
+
+    public bool HistorizedOnly { get; init; }
+}

clients/dotnet/MxGateway.Client/GalaxyRepositoryClient.cs

@@ -2,14 +2,14 @@ using Google.Protobuf.WellKnownTypes;
 using Grpc.Core;
 using Grpc.Net.Client;
 using Microsoft.Extensions.Logging;
-using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+using MxGateway.Contracts.Proto.Galaxy;
 using Polly;
 using System.Net.Http;
 using System.Net.Security;
 using System.Runtime.CompilerServices;
 using System.Security.Cryptography.X509Certificates;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>
 /// Provides the .NET client entry point for the public Galaxy Repository gRPC API.

clients/dotnet/MxGateway.Client/GrpcGalaxyRepositoryClientTransport.cs

@@ -1,7 +1,7 @@
 using Grpc.Core;
-using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+using MxGateway.Contracts.Proto.Galaxy;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>
 /// gRPC implementation of IGalaxyRepositoryClientTransport.
@@ -36,7 +36,7 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
         }
         catch (RpcException exception)
         {
-            throw MapRpcException(exception, callOptions.CancellationToken);
+            throw RpcExceptionMapper.Map(exception, callOptions.CancellationToken);
         }
     }
 
@@ -53,7 +53,7 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
         }
         catch (RpcException exception)
         {
-            throw MapRpcException(exception, callOptions.CancellationToken);
+            throw RpcExceptionMapper.Map(exception, callOptions.CancellationToken);
         }
     }
 
@@ -70,7 +70,7 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
         }
         catch (RpcException exception)
         {
-            throw MapRpcException(exception, callOptions.CancellationToken);
+            throw RpcExceptionMapper.Map(exception, callOptions.CancellationToken);
         }
     }
 
@@ -101,7 +101,7 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
             }
             catch (RpcException exception)
             {
-                throw MapRpcException(exception, effectiveCancellationToken);
+                throw RpcExceptionMapper.Map(exception, effectiveCancellationToken);
             }
 
             yield return deployEvent;
@@ -115,28 +115,4 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
     {
         return WatchDeployEventsAsync(request, callOptions);
     }
-
-    private static Exception MapRpcException(
-        RpcException exception,
-        CancellationToken cancellationToken)
-    {
-        if (cancellationToken.IsCancellationRequested || exception.StatusCode == StatusCode.Cancelled)
-        {
-            return new OperationCanceledException(
-                exception.Status.Detail,
-                exception,
-                cancellationToken);
-        }
-
-        return exception.StatusCode switch
-        {
-            StatusCode.Unauthenticated => new MxGatewayAuthenticationException(
-                exception.Status.Detail,
-                innerException: exception),
-            StatusCode.PermissionDenied => new MxGatewayAuthorizationException(
-                exception.Status.Detail,
-                innerException: exception),
-            _ => new MxGatewayException(exception.Status.Detail, exception),
-        };
-    }
 }

clients/dotnet/MxGateway.Client/GrpcMxGatewayClientTransport.cs

@@ -1,7 +1,7 @@
 using Grpc.Core;
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>
 /// gRPC implementation of IMxGatewayClientTransport.
@@ -36,7 +36,7 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
         catch (RpcException exception)
         {
-            throw MapRpcException(exception, callOptions.CancellationToken);
+            throw RpcExceptionMapper.Map(exception, callOptions.CancellationToken);
         }
     }
 
@@ -53,7 +53,7 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
         catch (RpcException exception)
         {
-            throw MapRpcException(exception, callOptions.CancellationToken);
+            throw RpcExceptionMapper.Map(exception, callOptions.CancellationToken);
         }
     }
 
@@ -70,7 +70,7 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
         catch (RpcException exception)
         {
-            throw MapRpcException(exception, callOptions.CancellationToken);
+            throw RpcExceptionMapper.Map(exception, callOptions.CancellationToken);
         }
     }
 
@@ -101,7 +101,7 @@ internal sealed class GrpcMxGatewayClientTransport(
             }
             catch (RpcException exception)
             {
-                throw MapRpcException(exception, effectiveCancellationToken);
+                throw RpcExceptionMapper.Map(exception, effectiveCancellationToken);
             }
 
             yield return gatewayEvent;
@@ -129,7 +129,7 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
         catch (RpcException exception)
         {
-            throw MapRpcException(exception, callOptions.CancellationToken);
+            throw RpcExceptionMapper.Map(exception, callOptions.CancellationToken);
         }
     }
 
@@ -160,7 +160,7 @@ internal sealed class GrpcMxGatewayClientTransport(
             }
             catch (RpcException exception)
             {
-                throw MapRpcException(exception, effectiveCancellationToken);
+                throw RpcExceptionMapper.Map(exception, effectiveCancellationToken);
             }
 
             yield return snapshot;
@@ -174,28 +174,4 @@ internal sealed class GrpcMxGatewayClientTransport(
     {
         return QueryActiveAlarmsAsync(request, callOptions);
     }
-
-    private static Exception MapRpcException(
-        RpcException exception,
-        CancellationToken cancellationToken)
-    {
-        if (cancellationToken.IsCancellationRequested || exception.StatusCode == StatusCode.Cancelled)
-        {
-            return new OperationCanceledException(
-                exception.Status.Detail,
-                exception,
-                cancellationToken);
-        }
-
-        return exception.StatusCode switch
-        {
-            StatusCode.Unauthenticated => new MxGatewayAuthenticationException(
-                exception.Status.Detail,
-                innerException: exception),
-            StatusCode.PermissionDenied => new MxGatewayAuthorizationException(
-                exception.Status.Detail,
-                innerException: exception),
-            _ => new MxGatewayException(exception.Status.Detail, exception),
-        };
-    }
 }

clients/dotnet/MxGateway.Client/IGalaxyRepositoryClientTransport.cs

@@ -1,7 +1,7 @@
 using Grpc.Core;
-using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+using MxGateway.Contracts.Proto.Galaxy;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>Transport layer for Galaxy Repository gRPC operations.</summary>
 internal interface IGalaxyRepositoryClientTransport

clients/dotnet/MxGateway.Client/IMxGatewayClientTransport.cs

@@ -1,7 +1,7 @@
 using Grpc.Core;
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 internal interface IMxGatewayClientTransport
 {

clients/dotnet/MxGateway.Client/MxAccessException.cs

@@ -1,6 +1,6 @@
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>Exception thrown when an MXAccess command fails with a non-zero HResult or failing status.</summary>
 public sealed class MxAccessException : MxGatewayCommandException

clients/dotnet/MxGateway.Client/MxCommandReplyExtensions.cs

@@ -1,6 +1,6 @@
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>Extension methods for checking MxCommandReply success conditions.</summary>
 public static class MxCommandReplyExtensions

clients/dotnet/MxGateway.Client/MxGateway.Client.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\src\ZB.MOM.WW.MxGateway.Contracts\ZB.MOM.WW.MxGateway.Contracts.csproj" />
+    <ProjectReference Include="..\..\..\src\MxGateway.Contracts\MxGateway.Contracts.csproj" />
   </ItemGroup>
 
   <ItemGroup>

clients/dotnet/MxGateway.Client/MxGatewayAuthenticationException.cs

@@ -1,6 +1,7 @@
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using Grpc.Core;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>Exception thrown when an API key is invalid, expired, or malformed.</summary>
 public sealed class MxGatewayAuthenticationException : MxGatewayException
@@ -13,6 +14,7 @@ public sealed class MxGatewayAuthenticationException : MxGatewayException
     /// <param name="hResult">The HResult code, if available.</param>
     /// <param name="statuses">The MXAccess statuses, if available.</param>
     /// <param name="innerException">The underlying exception, if any.</param>
+    /// <param name="statusCode">The gRPC status code reported by the failed call, if available.</param>
     public MxGatewayAuthenticationException(
         string message,
         string? sessionId = null,
@@ -20,7 +22,8 @@ public sealed class MxGatewayAuthenticationException : MxGatewayException
         ProtocolStatus? protocolStatus = null,
         int? hResult = null,
         IReadOnlyList<MxStatusProxy>? statuses = null,
-        Exception? innerException = null)
+        Exception? innerException = null,
+        StatusCode? statusCode = null)
         : base(
             message,
             sessionId,
@@ -28,7 +31,8 @@ public sealed class MxGatewayAuthenticationException : MxGatewayException
             protocolStatus,
             hResult,
             statuses ?? [],
-            innerException)
+            innerException,
+            statusCode)
     {
     }
 }

clients/dotnet/MxGateway.Client/MxGatewayAuthorizationException.cs

@@ -1,6 +1,7 @@
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using Grpc.Core;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>Exception thrown when the API key lacks required scopes for an operation.</summary>
 public sealed class MxGatewayAuthorizationException : MxGatewayException
@@ -13,6 +14,7 @@ public sealed class MxGatewayAuthorizationException : MxGatewayException
     /// <param name="hResult">The HResult code, if available.</param>
     /// <param name="statuses">The MXAccess statuses, if available.</param>
     /// <param name="innerException">The underlying exception, if any.</param>
+    /// <param name="statusCode">The gRPC status code reported by the failed call, if available.</param>
     public MxGatewayAuthorizationException(
         string message,
         string? sessionId = null,
@@ -20,7 +22,8 @@ public sealed class MxGatewayAuthorizationException : MxGatewayException
         ProtocolStatus? protocolStatus = null,
         int? hResult = null,
         IReadOnlyList<MxStatusProxy>? statuses = null,
-        Exception? innerException = null)
+        Exception? innerException = null,
+        StatusCode? statusCode = null)
         : base(
             message,
             sessionId,
@@ -28,7 +31,8 @@ public sealed class MxGatewayAuthorizationException : MxGatewayException
             protocolStatus,
             hResult,
             statuses ?? [],
-            innerException)
+            innerException,
+            statusCode)
     {
     }
 }

clients/dotnet/MxGateway.Client/MxGatewayClient.cs

@@ -1,13 +1,13 @@
 using Grpc.Core;
 using Grpc.Net.Client;
 using Microsoft.Extensions.Logging;
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 using Polly;
 using System.Net.Http;
 using System.Net.Security;
 using System.Security.Cryptography.X509Certificates;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>
 /// Provides the .NET client entry point for the public MXAccess Gateway gRPC API.
@@ -17,7 +17,7 @@ public sealed class MxGatewayClient : IAsyncDisposable
     private readonly GrpcChannel _channel;
     private readonly IMxGatewayClientTransport _transport;
     private readonly ResiliencePipeline _safeUnaryRetryPipeline;
-    private bool _disposed;
+    private int _disposed;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="MxGatewayClient"/> with given options and transport.
@@ -184,9 +184,10 @@ public sealed class MxGatewayClient : IAsyncDisposable
 
     /// <summary>
     /// Acknowledges an active MXAccess alarm condition through the gateway. The
-    /// gateway authenticates the request against the API key's <c>invoke:alarm-ack</c>
+    /// gateway authorizes <see cref="AcknowledgeAlarmRequest"/> against the API
-    /// scope and forwards the acknowledge to the worker's MXAccess session;
+    /// key's <c>admin</c> scope (there is no finer-grained alarm-ack sub-scope)
-    /// the resulting <see cref="MxStatusProxy"/> is returned in the reply.
+    /// and forwards the acknowledge to the worker's MXAccess session; the
+    /// resulting <see cref="MxStatusProxy"/> is returned in the reply.
     /// </summary>
     /// <param name="request">The acknowledge request — alarm reference, comment, operator user.</param>
     /// <param name="cancellationToken">Cancellation token for the operation.</param>
@@ -229,12 +230,11 @@ public sealed class MxGatewayClient : IAsyncDisposable
     /// </summary>
     public ValueTask DisposeAsync()
     {
-        if (_disposed)
+        if (Interlocked.Exchange(ref _disposed, 1) != 0)
         {
             return ValueTask.CompletedTask;
         }
 
-        _disposed = true;
         _channel?.Dispose();
         return ValueTask.CompletedTask;
     }
@@ -335,6 +335,6 @@ public sealed class MxGatewayClient : IAsyncDisposable
 
     private void ThrowIfDisposed()
     {
-        ObjectDisposedException.ThrowIf(_disposed, this);
+        ObjectDisposedException.ThrowIf(Volatile.Read(ref _disposed) != 0, this);
     }
 }

clients/dotnet/MxGateway.Client/MxGatewayClientContractInfo.cs

@@ -0,0 +1,25 @@
+using MxGateway.Contracts;
+
+namespace MxGateway.Client;
+
+/// <summary>
+/// Exposes the protocol versions compiled into this client package.
+/// </summary>
+public static class MxGatewayClientContractInfo
+{
+    /// <summary>
+    /// Gets the gateway gRPC protocol version compiled into this client package.
+    /// A client and gateway are wire-compatible only when this value matches the
+    /// gateway's advertised gateway protocol version.
+    /// </summary>
+    public const uint GatewayProtocolVersion =
+        GatewayContractInfo.GatewayProtocolVersion;
+
+    /// <summary>
+    /// Gets the worker frame protocol version compiled into this client package.
+    /// Exposed for diagnostics so callers can report the worker protocol the
+    /// shared contracts were generated against.
+    /// </summary>
+    public const uint WorkerProtocolVersion =
+        GatewayContractInfo.WorkerProtocolVersion;
+}

clients/dotnet/MxGateway.Client/MxGatewayClientOptions.cs

@@ -1,6 +1,6 @@
 using Microsoft.Extensions.Logging;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>
 /// Configures the gRPC channel used by the .NET MXAccess Gateway client.
@@ -38,7 +38,12 @@ public sealed class MxGatewayClientOptions
     public TimeSpan ConnectTimeout { get; init; } = TimeSpan.FromSeconds(10);
 
     /// <summary>
-    /// Gets the default timeout for unary gRPC calls.
+    /// Gets the timeout budget for a unary gRPC operation. This is both the gRPC
+    /// deadline stamped on each individual attempt and the overall budget for the
+    /// whole safe-unary operation: for retryable calls the initial attempt, every
+    /// retry, and the backoff delays between them all share this single budget.
+    /// It is therefore an upper bound on the total wall-clock time a safe-unary
+    /// call can take, not a fresh per-retry allowance.
     /// </summary>
     public TimeSpan DefaultCallTimeout { get; init; } = TimeSpan.FromSeconds(30);
 
@@ -47,6 +52,11 @@ public sealed class MxGatewayClientOptions
     /// </summary>
     public TimeSpan? StreamTimeout { get; init; }
 
+    /// <summary>
+    /// Gets the maximum size, in bytes, of a single gRPC message the client will
+    /// send or receive. Applied to both the send and receive limits of the
+    /// underlying channel. Defaults to 16 MiB.
+    /// </summary>
     public int MaxGrpcMessageBytes { get; init; } = 16 * 1024 * 1024;
 
     /// <summary>

clients/dotnet/MxGateway.Client/MxGatewayClientRetryOptions.cs

@@ -1,4 +1,4 @@
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>Configuration for automatic retry behavior on transient gRPC call failures.</summary>
 public sealed class MxGatewayClientRetryOptions

clients/dotnet/MxGateway.Client/MxGatewayClientRetryPolicy.cs

@@ -1,10 +1,10 @@
 using Grpc.Core;
 using Microsoft.Extensions.Logging;
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 using Polly;
 using Polly.Retry;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>Factory and helpers for exponential-backoff retry policies on transient gRPC failures.</summary>
 internal static class MxGatewayClientRetryPolicy
@@ -61,8 +61,13 @@ internal static class MxGatewayClientRetryPolicy
 
     private static bool IsTransientStatus(StatusCode statusCode)
     {
+        // DeadlineExceeded is intentionally NOT treated as transient. The deadline
+        // on every unary call is client-imposed (CreateCallOptions stamps the
+        // DefaultCallTimeout budget), and that same budget is shared across the
+        // initial attempt plus all retries plus backoff. A DeadlineExceeded means
+        // the shared budget is exhausted, so an immediate retry would only fail
+        // again — burning the remaining budget on a call that cannot succeed.
         return statusCode is StatusCode.Unavailable
-            or StatusCode.DeadlineExceeded
             or StatusCode.ResourceExhausted;
     }
 }

clients/dotnet/MxGateway.Client/MxGatewayCommandException.cs

@@ -1,6 +1,6 @@
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>Exception thrown when a gateway command fails due to an unclassified protocol error.</summary>
 public class MxGatewayCommandException : MxGatewayException

clients/dotnet/MxGateway.Client/MxGatewayException.cs

@@ -1,6 +1,7 @@
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using Grpc.Core;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>
 /// Exception thrown when a gateway RPC call fails or returns an error status.
@@ -28,6 +29,20 @@ public class MxGatewayException : Exception
         Statuses = [];
     }
 
+    /// <summary>
+    /// Initializes a new instance of the MxGatewayException class carrying the originating
+    /// gRPC status code so callers can distinguish transient from permanent failures.
+    /// </summary>
+    /// <param name="message">Diagnostic message describing the failure.</param>
+    /// <param name="statusCode">The gRPC status code reported by the failed call.</param>
+    /// <param name="innerException">Underlying exception that caused this failure.</param>
+    public MxGatewayException(string message, StatusCode statusCode, Exception? innerException)
+        : base(message, innerException)
+    {
+        StatusCode = statusCode;
+        Statuses = [];
+    }
+
     /// <summary>
     /// Initializes a new instance of the MxGatewayException class with full diagnostic information.
     /// </summary>
@@ -38,6 +53,7 @@ public class MxGatewayException : Exception
     /// <param name="hResult">HRESULT code returned by the worker or MXAccess, if available.</param>
     /// <param name="statuses">List of MXAccess status codes returned by the operation.</param>
     /// <param name="innerException">Underlying exception that caused this failure.</param>
+    /// <param name="statusCode">The gRPC status code reported by the failed call, if available.</param>
     public MxGatewayException(
         string message,
         string? sessionId,
@@ -45,7 +61,8 @@ public class MxGatewayException : Exception
         ProtocolStatus? protocolStatus,
         int? hResult,
         IReadOnlyList<MxStatusProxy> statuses,
-        Exception? innerException = null)
+        Exception? innerException = null,
+        StatusCode? statusCode = null)
         : base(message, innerException)
     {
         SessionId = sessionId;
@@ -53,6 +70,7 @@ public class MxGatewayException : Exception
         ProtocolStatus = protocolStatus;
         HResultCode = hResult;
         Statuses = statuses;
+        StatusCode = statusCode;
     }
 
     /// <summary>
@@ -79,4 +97,15 @@ public class MxGatewayException : Exception
     /// Gets the list of MXAccess status codes returned by the operation.
     /// </summary>
     public IReadOnlyList<MxStatusProxy> Statuses { get; }
+
+    /// <summary>
+    /// Gets the gRPC status code reported by the failed call, if the failure originated
+    /// from a gRPC <see cref="RpcException"/>. <see langword="null"/> when the exception
+    /// was not produced from a gRPC status (for example, a protocol-level reply failure).
+    /// Callers can inspect this to distinguish a transient outage
+    /// (<see cref="Grpc.Core.StatusCode.Unavailable"/>) from a permanent error
+    /// (<see cref="Grpc.Core.StatusCode.InvalidArgument"/>) without downcasting
+    /// <see cref="Exception.InnerException"/>.
+    /// </summary>
+    public StatusCode? StatusCode { get; }
 }

clients/dotnet/MxGateway.Client/MxGatewaySession.cs

@@ -1,6 +1,6 @@
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>
 /// Represents one gateway-backed MXAccess session.
@@ -9,7 +9,10 @@ public sealed class MxGatewaySession : IAsyncDisposable
 {
     private readonly MxGatewayClient _client;
     private readonly SemaphoreSlim _closeLock = new(1, 1);
+    private readonly object _disposeGate = new();
     private CloseSessionReply? _closeReply;
+    private int _activeCloseCount;
+    private bool _closeLockDisposed;
 
     /// <summary>
     /// Initializes a new session backed by the given MXAccess gateway client.
@@ -46,23 +49,42 @@ public sealed class MxGatewaySession : IAsyncDisposable
             return _closeReply;
         }
 
-        await _closeLock.WaitAsync(cancellationToken).ConfigureAwait(false);
+        // Register as an in-flight closer under the dispose gate. DisposeAsync waits for
+        // _activeCloseCount to drain before disposing the close lock, so the semaphore is
+        // guaranteed to outlive every WaitAsync started here.
+        lock (_disposeGate)
+        {
+            ObjectDisposedException.ThrowIf(_closeLockDisposed, this);
+            _activeCloseCount++;
+        }
+
         try
         {
-            if (_closeReply is not null)
+            await _closeLock.WaitAsync(cancellationToken).ConfigureAwait(false);
+            try
             {
+                if (_closeReply is not null)
+                {
+                    return _closeReply;
+                }
+
+                _closeReply = await _client.CloseSessionRawAsync(
+                        new CloseSessionRequest { SessionId = SessionId },
+                        cancellationToken)
+                    .ConfigureAwait(false);
                 return _closeReply;
             }
-
+            finally
-            _closeReply = await _client.CloseSessionRawAsync(
+            {
-                    new CloseSessionRequest { SessionId = SessionId },
+                _closeLock.Release();
-                    cancellationToken)
+            }
-                .ConfigureAwait(false);
-            return _closeReply;
         }
         finally
         {
-            _closeLock.Release();
+            lock (_disposeGate)
+            {
+                _activeCloseCount--;
+            }
         }
     }
 
@@ -79,7 +101,8 @@ public sealed class MxGatewaySession : IAsyncDisposable
         MxCommandReply reply = await RegisterRawAsync(clientName, cancellationToken)
             .ConfigureAwait(false);
         reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
-        return reply.Register?.ServerHandle ?? reply.ReturnValue.Int32Value;
+        return reply.Register?.ServerHandle
+            ?? throw CreateMissingPayloadException(reply, "register");
     }
 
     /// <summary>
@@ -121,7 +144,8 @@ public sealed class MxGatewaySession : IAsyncDisposable
                 cancellationToken)
             .ConfigureAwait(false);
         reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
-        return reply.AddItem?.ItemHandle ?? reply.ReturnValue.Int32Value;
+        return reply.AddItem?.ItemHandle
+            ?? throw CreateMissingPayloadException(reply, "add_item");
     }
 
     /// <summary>
@@ -172,7 +196,8 @@ public sealed class MxGatewaySession : IAsyncDisposable
                 cancellationToken)
             .ConfigureAwait(false);
         reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
-        return reply.AddItem2?.ItemHandle ?? reply.ReturnValue.Int32Value;
+        return reply.AddItem2?.ItemHandle
+            ?? throw CreateMissingPayloadException(reply, "add_item2");
     }
 
     /// <summary>
@@ -658,7 +683,32 @@ public sealed class MxGatewaySession : IAsyncDisposable
     /// </summary>
     public async ValueTask DisposeAsync()
     {
+        lock (_disposeGate)
+        {
+            if (_closeLockDisposed)
+            {
+                return;
+            }
+        }
+
         await CloseAsync().ConfigureAwait(false);
+
+        // Wait for every concurrent CloseAsync caller to leave the close lock before
+        // disposing it; once _closeReply is set those callers return without awaiting.
+        while (true)
+        {
+            lock (_disposeGate)
+            {
+                if (_activeCloseCount == 0)
+                {
+                    _closeLockDisposed = true;
+                    break;
+                }
+            }
+
+            await Task.Yield();
+        }
+
         _closeLock.Dispose();
     }
 
@@ -676,4 +726,21 @@ public sealed class MxGatewaySession : IAsyncDisposable
             cancellationToken);
     }
 
+    /// <summary>
+    /// Builds the exception thrown when a command reply passed protocol and
+    /// MXAccess success checks but is missing the typed handle-bearing payload
+    /// the command contract requires. Surfacing this as a clear error avoids
+    /// silently handing a zero handle to the caller (it would otherwise fall
+    /// through to <see cref="MxCommandReply.ReturnValue"/>, which is 0 when the
+    /// reply carries no return value).
+    /// </summary>
+    private static MxGatewayException CreateMissingPayloadException(
+        MxCommandReply reply,
+        string expectedPayload)
+    {
+        return new MxGatewayException(
+            $"Gateway reply for command kind={reply.Kind} reported success but is missing "
+            + $"the required '{expectedPayload}' payload; cannot resolve a handle. "
+            + $"session={reply.SessionId}; correlation={reply.CorrelationId}");
+    }
 }

clients/dotnet/MxGateway.Client/MxGatewaySessionException.cs

@@ -1,6 +1,6 @@
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>Exception thrown when a session is not found, not ready, or invalid.</summary>
 public sealed class MxGatewaySessionException : MxGatewayException

clients/dotnet/MxGateway.Client/MxGatewayWorkerException.cs

@@ -1,6 +1,6 @@
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>Exception thrown when the worker process is unavailable or fails to process a command.</summary>
 public sealed class MxGatewayWorkerException : MxGatewayException

clients/dotnet/MxGateway.Client/MxStatusProxyExtensions.cs

@@ -1,6 +1,6 @@
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>Extension methods for MxStatusProxy values.</summary>
 public static class MxStatusProxyExtensions

clients/dotnet/MxGateway.Client/MxValueExtensions.cs

@@ -1,8 +1,8 @@
 using Google.Protobuf;
 using Google.Protobuf.WellKnownTypes;
-using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto;
 
-namespace ZB.MOM.WW.MxGateway.Client;
+namespace MxGateway.Client;
 
 /// <summary>
 /// Creates and projects gateway MXAccess values without hiding the raw

clients/dotnet/MxGateway.Client/Properties/AssemblyInfo.cs

@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("MxGateway.Client.Tests")]

clients/dotnet/MxGateway.Client/RpcExceptionMapper.cs

@@ -0,0 +1,55 @@
+using Grpc.Core;
+
+namespace MxGateway.Client;
+
+/// <summary>
+/// Maps low-level <see cref="RpcException"/>s raised by the gRPC stack to the client's
+/// native exception hierarchy. Shared by every gateway and Galaxy Repository transport
+/// so the gRPC-to-native translation has exactly one implementation.
+/// </summary>
+internal static class RpcExceptionMapper
+{
+    /// <summary>
+    /// Translates a <see cref="RpcException"/> into the most specific native exception type.
+    /// </summary>
+    /// <param name="exception">The gRPC exception to translate.</param>
+    /// <param name="cancellationToken">
+    /// The cancellation token of the originating call; used to distinguish a caller-driven
+    /// cancellation from a server-side <see cref="StatusCode.Cancelled"/> status.
+    /// </param>
+    /// <returns>
+    /// An <see cref="OperationCanceledException"/> when the call was cancelled, a typed
+    /// authentication/authorization exception for auth statuses, or an
+    /// <see cref="MxGatewayException"/> carrying the originating gRPC <see cref="StatusCode"/>.
+    /// </returns>
+    public static Exception Map(
+        RpcException exception,
+        CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(exception);
+
+        if (cancellationToken.IsCancellationRequested || exception.StatusCode == StatusCode.Cancelled)
+        {
+            return new OperationCanceledException(
+                exception.Status.Detail,
+                exception,
+                cancellationToken);
+        }
+
+        return exception.StatusCode switch
+        {
+            StatusCode.Unauthenticated => new MxGatewayAuthenticationException(
+                exception.Status.Detail,
+                statusCode: exception.StatusCode,
+                innerException: exception),
+            StatusCode.PermissionDenied => new MxGatewayAuthorizationException(
+                exception.Status.Detail,
+                statusCode: exception.StatusCode,
+                innerException: exception),
+            _ => new MxGatewayException(
+                exception.Status.Detail,
+                exception.StatusCode,
+                exception),
+        };
+    }
+}

clients/dotnet/README.md

@@ -7,11 +7,11 @@ CLI, and unit tests.
 
 | Project | Purpose |
 |---------|---------|
-| `ZB.MOM.WW.MxGateway.Client` | .NET 10 library entry point, raw gRPC calls, and session helpers. |
+| `MxGateway.Client` | .NET 10 library entry point, raw gRPC calls, and session helpers. |
-| `ZB.MOM.WW.MxGateway.Client.Cli` | Test CLI for smoke and diagnostic commands. |
+| `MxGateway.Client.Cli` | Test CLI for smoke and diagnostic commands. |
-| `ZB.MOM.WW.MxGateway.Client.Tests` | Unit tests for client options, generated contract wiring, auth metadata, session helpers, cancellation, and event streaming. |
+| `MxGateway.Client.Tests` | Unit tests for client options, generated contract wiring, auth metadata, session helpers, cancellation, and event streaming. |
 
-The projects reference `src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj` so
+The projects reference `src/MxGateway.Contracts/MxGateway.Contracts.csproj` so
 the client compiles against the same generated protobuf and gRPC types as the
 gateway. `clients/dotnet/generated` remains reserved for generator output if a
 future client build switches to client-local `Grpc.Tools` generation.
@@ -19,8 +19,8 @@ future client build switches to client-local `Grpc.Tools` generation.
 ## Build And Test
 
 ```powershell
-dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx
+dotnet build clients/dotnet/MxGateway.Client.sln
-dotnet test clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx --no-build
+dotnet test clients/dotnet/MxGateway.Client.sln --no-build
 ```
 
 ## Packaging
@@ -29,8 +29,8 @@ Create local library and CLI artifacts from the repository root:
 
 ```powershell
 $dotnetPackageOutput = Join-Path (Get-Location) 'artifacts/clients/dotnet'
-dotnet pack clients/dotnet/ZB.MOM.WW.MxGateway.Client/ZB.MOM.WW.MxGateway.Client.csproj -c Release -p:PackageOutputPath="$dotnetPackageOutput"
+dotnet pack clients/dotnet/MxGateway.Client/MxGateway.Client.csproj -c Release -p:PackageOutputPath="$dotnetPackageOutput"
-dotnet publish clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/ZB.MOM.WW.MxGateway.Client.Cli.csproj -c Release -o artifacts/clients/dotnet/mxgw-dotnet
+dotnet publish clients/dotnet/MxGateway.Client.Cli/MxGateway.Client.Cli.csproj -c Release -o artifacts/clients/dotnet/mxgw-dotnet
 ```
 
 The library package references the shared contracts project at build time. The
@@ -39,11 +39,11 @@ published CLI runs from `artifacts/clients/dotnet/mxgw-dotnet`.
 ## Regenerating Protobuf Bindings
 
 The .NET client uses the generated C# types from
-`src/ZB.MOM.WW.MxGateway.Contracts/Generated`. Regenerate those files through the
+`src/MxGateway.Contracts/Generated`. Regenerate those files through the
 contracts project:
 
 ```powershell
-dotnet build src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj
+dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj
 ```
 
 ## Client Usage
@@ -112,26 +112,38 @@ can keep the full `MxCommandReply`, HRESULT, and status array when MXAccess
 itself rejects a command. `MxAccessException.Reply` contains the raw generated
 reply.
 
+When a gRPC call itself fails, the transport maps the underlying
+`RpcException` to a native exception: `Unauthenticated` becomes
+`MxGatewayAuthenticationException`, `PermissionDenied` becomes
+`MxGatewayAuthorizationException`, a cancelled call becomes
+`OperationCanceledException`, and every other status becomes a base
+`MxGatewayException`. `MxGatewayException.StatusCode` carries the originating
+gRPC `Grpc.Core.StatusCode` (non-null whenever the failure came from a gRPC
+status), so callers can distinguish a transient outage (`Unavailable`) from a
+permanent error (`InvalidArgument`, `NotFound`) without downcasting
+`InnerException`.
+
 ## CLI Usage
 
 The test CLI supports deterministic JSON output for automation:
 
 ```powershell
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- version --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- version --json
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- open-session --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- open-session --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- register --session-id <id> --client-name mxgw-dotnet-cli --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- register --session-id <id> --client-name mxgw-dotnet-cli --json
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- add-item --session-id <id> --server-handle 1 --item Area001.Pump001.Speed --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- add-item --session-id <id> --server-handle 1 --item Area001.Pump001.Speed --json
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- advise --session-id <id> --server-handle 1 --item-handle 1 --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- advise --session-id <id> --server-handle 1 --item-handle 1 --json
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- write --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- write --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --json
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- write2 --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --timestamp 2026-01-01T00:00:00Z --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- write2 --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --timestamp 2026-01-01T00:00:00Z --json
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- stream-events --session-id <id> --max-events 1 --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- stream-events --session-id <id> --max-events 1 --json
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- smoke --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json
 ```
 
 `smoke` opens a session, registers a client, adds one item, advises it,
 optionally writes a value when `--type` and `--value` are supplied, reads a
 bounded event stream, and closes the session in a `finally` block. CLI error
-output redacts API keys supplied through `--api-key`.
+output redacts the effective API key, whether it was supplied through
+`--api-key` or resolved from the `--api-key-env` environment variable.
 
 ## Galaxy Repository Browse
 
@@ -180,9 +192,9 @@ IReadOnlyList<GalaxyObject> pumps = await repository.DiscoverHierarchyAsync(
 The CLI exposes the same operations:
 
 ```powershell
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-test-connection --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-test-connection --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-last-deploy --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-last-deploy --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-discover --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-discover --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
 ```
 
 ### Watching deploy events
@@ -217,15 +229,15 @@ await foreach (DeployEvent evt in repository.WatchDeployEventsAsync(
 The CLI counterpart streams events until Ctrl+C (or `--max-events`):
 
 ```powershell
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --last-seen-deploy-time 2026-04-28T14:30:00Z --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --last-seen-deploy-time 2026-04-28T14:30:00Z --json
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --max-events 5 --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --max-events 5 --json
 ```
 
 Use TLS options for a secured gateway:
 
 ```powershell
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- smoke --endpoint https://ZB.MOM.WW.MxGateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name ZB.MOM.WW.MxGateway.example.local --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint https://mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json
 ```
 
 ## Integration Checks
@@ -237,7 +249,7 @@ $env:MXGATEWAY_INTEGRATION = '1'
 $env:MXGATEWAY_ENDPOINT = 'http://localhost:5000'
 $env:MXGATEWAY_API_KEY = '<gateway-api-key>'
 $env:MXGATEWAY_TEST_ITEM = 'Area001.Pump001.Speed'
-dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- smoke --endpoint $env:MXGATEWAY_ENDPOINT --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint $env:MXGATEWAY_ENDPOINT --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
 ```
 
 ## Related Documentation

clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx

@@ -1,11 +0,0 @@
-<Solution>
-  <Configurations>
-    <Platform Name="Any CPU" />
-    <Platform Name="x64" />
-    <Platform Name="x86" />
-  </Configurations>
-  <Project Path="../../src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj" />
-  <Project Path="ZB.MOM.WW.MxGateway.Client.Cli/ZB.MOM.WW.MxGateway.Client.Cli.csproj" />
-  <Project Path="ZB.MOM.WW.MxGateway.Client.Tests/ZB.MOM.WW.MxGateway.Client.Tests.csproj" />
-  <Project Path="ZB.MOM.WW.MxGateway.Client/ZB.MOM.WW.MxGateway.Client.csproj" />
-</Solution>

clients/dotnet/ZB.MOM.WW.MxGateway.Client/DiscoverHierarchyOptions.cs

@@ -1,43 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Client;
-
-/// <summary>
-/// Filters and shape options for <see cref="GalaxyRepositoryClient.DiscoverHierarchyAsync(DiscoverHierarchyOptions, System.Threading.CancellationToken)"/>.
-/// </summary>
-/// <remarks>
-/// Hand-written ergonomic wrapper around the generated
-/// <c>DiscoverHierarchyRequest</c>: lets callers express a Galaxy-browse
-/// slice with .NET-friendly nullable scalars and collection initializers,
-/// without touching the protobuf message's <c>oneof root</c> directly.
-/// </remarks>
-public sealed class DiscoverHierarchyOptions
-{
-    /// <summary>Restrict to the subtree rooted at this Galaxy <c>gobject_id</c>.</summary>
-    public int? RootGobjectId { get; init; }
-
-    /// <summary>Restrict to the subtree rooted at the object with this tag name.</summary>
-    public string? RootTagName { get; init; }
-
-    /// <summary>Restrict to the subtree rooted at this <c>contained_name</c> path.</summary>
-    public string? RootContainedPath { get; init; }
-
-    /// <summary>Maximum traversal depth, measured from the chosen root.</summary>
-    public int? MaxDepth { get; init; }
-
-    /// <summary>Restrict to objects whose Galaxy category is in this set.</summary>
-    public IReadOnlyList<int> CategoryIds { get; init; } = [];
-
-    /// <summary>Restrict to objects whose template chain contains any of these tokens.</summary>
-    public IReadOnlyList<string> TemplateChainContains { get; init; } = [];
-
-    /// <summary>Optional glob-style filter on <c>tag_name</c>.</summary>
-    public string? TagNameGlob { get; init; }
-
-    /// <summary>Whether to populate each <c>GalaxyObject.Attributes</c>. Null leaves the server default.</summary>
-    public bool? IncludeAttributes { get; init; }
-
-    /// <summary>Restrict to objects that bear at least one alarm attribute.</summary>
-    public bool AlarmBearingOnly { get; init; }
-
-    /// <summary>Restrict to objects that have at least one historized attribute.</summary>
-    public bool HistorizedOnly { get; init; }
-}

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewayClientContractInfo.cs

@@ -1,15 +0,0 @@
-using ZB.MOM.WW.MxGateway.Contracts;
-
-namespace ZB.MOM.WW.MxGateway.Client;
-
-/// <summary>
-/// Exposes the protocol versions compiled into this client package.
-/// </summary>
-public static class MxGatewayClientContractInfo
-{
-    public const uint GatewayProtocolVersion =
-        GatewayContractInfo.GatewayProtocolVersion;
-
-    public const uint WorkerProtocolVersion =
-        GatewayContractInfo.WorkerProtocolVersion;
-}

clients/dotnet/ZB.MOM.WW.MxGateway.Client/Properties/AssemblyInfo.cs

@@ -1,3 +0,0 @@
-using System.Runtime.CompilerServices;
-
-[assembly: InternalsVisibleTo("ZB.MOM.WW.MxGateway.Client.Tests")]

clients/go/README.md

@@ -79,11 +79,30 @@ client, err := mxgateway.Dial(ctx, mxgateway.Options{
 `AddItem`, `AddItem2`, `Advise`, `Write`, `Events`, and `Close`. Prefer
 `SubscribeEvents` or `SubscribeEventsAfter` for long-running streams because the
 returned subscription owns cancellation and exposes `Close` for deterministic
-goroutine cleanup. Raw protobuf messages remain available through the
+goroutine cleanup. `Events` and `EventsAfter` are a compatibility shim with a
+bounded internal buffer: if the consumer drains too slowly the buffer fills,
+the underlying stream is cancelled, and a terminal `EventResult` carrying
+`ErrEventBufferOverflow` is delivered as the channel's last item before it
+closes — so a slow consumer can distinguish dropped events from a normal
+end-of-stream. `SubscribeEvents` blocks instead of dropping, so use it when no
+events may be lost. Raw protobuf messages remain available through the
 `mxgateway` package aliases and the `Raw` helper methods. Typed errors support
 `errors.As` for `GatewayError`, `CommandError`, and `MxAccessError`; command
 errors preserve the raw reply.
 
+`Dial` and `DialGalaxy` create the connection lazily (`grpc.NewClient`): a
+gateway that is briefly unavailable no longer turns into a hard error — the
+connection recovers once the gateway comes up. To keep fail-fast behavior,
+both run a readiness probe bounded by `DialTimeout` (default 10s, or the
+context deadline when sooner) and return a `*GatewayError` if the gateway
+cannot be reached in that window.
+
+For retry, timeout, and auth handling, `GatewayError.Code()` exposes the
+wrapped gRPC `codes.Code`, and `mxgateway.IsTransient(err)` reports whether a
+failure (`Unavailable`, `DeadlineExceeded`, `ResourceExhausted`, `Aborted`)
+may succeed on retry — so callers do not have to unwrap the error and call
+`status.Code` themselves.
+
 ## Galaxy Repository browse
 
 The `GalaxyRepository` service (proto package `galaxy_repository.v1`) is a

clients/go/cmd/mxgw-go/main.go

@@ -331,6 +331,11 @@ func runUnsubscribeBulk(ctx context.Context, args []string, stdout, stderr io.Wr
 		return errors.New("session-id and item-handles are required")
 	}
 
+	handles, err := parseInt32List(*itemHandles)
+	if err != nil {
+		return err
+	}
+
 	client, options, err := dialForCommand(ctx, common)
 	if err != nil {
 		return err
@@ -338,7 +343,7 @@ func runUnsubscribeBulk(ctx context.Context, args []string, stdout, stderr io.Wr
 	defer client.Close()
 
 	session := mxgateway.NewSessionForID(client, *sessionID)
-	results, err := session.UnsubscribeBulk(ctx, int32(*serverHandle), parseInt32List(*itemHandles))
+	results, err := session.UnsubscribeBulk(ctx, int32(*serverHandle), handles)
 	return writeBulkOutput(stdout, *jsonOutput, "unsubscribe-bulk", options, results, err)
 }
 
@@ -514,7 +519,7 @@ func parseStringList(value string) []string {
 	return items
 }
 
-func parseInt32List(value string) []int32 {
+func parseInt32List(value string) ([]int32, error) {
 	parts := strings.Split(value, ",")
 	items := make([]int32, 0, len(parts))
 	for _, part := range parts {
@@ -524,11 +529,11 @@ func parseInt32List(value string) []int32 {
 		}
 		parsed, err := strconv.ParseInt(item, 10, 32)
 		if err != nil {
-			panic(err)
+			return nil, fmt.Errorf("invalid item handle %q: %w", item, err)
 		}
 		items = append(items, int32(parsed))
 	}
-	return items
+	return items, nil
 }
 
 func bindCommonFlags(flags *flag.FlagSet) *commonOptions {

clients/go/cmd/mxgw-go/main_test.go

@@ -56,3 +56,32 @@ func TestParseValueBuildsTypedValue(t *testing.T) {
 		t.Fatalf("int32 value = %d, want 123", got)
 	}
 }
+
+func TestParseInt32ListParsesValidTokens(t *testing.T) {
+	items, err := parseInt32List("1, 2 ,3")
+	if err != nil {
+		t.Fatalf("parseInt32List() error = %v", err)
+	}
+	want := []int32{1, 2, 3}
+	if len(items) != len(want) {
+		t.Fatalf("parseInt32List() = %v, want %v", items, want)
+	}
+	for i := range want {
+		if items[i] != want[i] {
+			t.Fatalf("parseInt32List()[%d] = %d, want %d", i, items[i], want[i])
+		}
+	}
+}
+
+func TestParseInt32ListReturnsErrorOnMalformedToken(t *testing.T) {
+	items, err := parseInt32List("1,foo")
+	if err == nil {
+		t.Fatalf("parseInt32List() error = nil, want a parse error; items = %v", items)
+	}
+	if items != nil {
+		t.Fatalf("parseInt32List() items = %v, want nil on error", items)
+	}
+	if !strings.Contains(err.Error(), "foo") {
+		t.Fatalf("parseInt32List() error = %q, want it to name the bad token", err.Error())
+	}
+}

clients/go/generate-proto.ps1

@@ -2,7 +2,7 @@ Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
 
 $repoRoot = Resolve-Path (Join-Path $PSScriptRoot '..\..')
-$protoRoot = Join-Path $repoRoot 'src\ZB.MOM.WW.MxGateway.Contracts\Protos'
+$protoRoot = Join-Path $repoRoot 'src\MxGateway.Contracts\Protos'
 $outputRoot = Join-Path $PSScriptRoot 'internal\generated'
 $modulePath = 'gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated'
 $protoc = 'C:\Users\dohertj2\AppData\Local\Microsoft\WinGet\Packages\Google.Protobuf_Microsoft.Winget.Source_8wekyb3d8bbwe\bin\protoc.exe'

clients/go/internal/generated/galaxy_repository.pb.go

@@ -687,32 +687,18 @@ func (x *GalaxyObject) GetAttributes() []*GalaxyAttribute {
 }
 
 type GalaxyAttribute struct {
-	state            protoimpl.MessageState `protogen:"open.v1"`
+	state                  protoimpl.MessageState `protogen:"open.v1"`
-	AttributeName    string                 `protobuf:"bytes,1,opt,name=attribute_name,json=attributeName,proto3" json:"attribute_name,omitempty"`
+	AttributeName          string                 `protobuf:"bytes,1,opt,name=attribute_name,json=attributeName,proto3" json:"attribute_name,omitempty"`
-	FullTagReference string                 `protobuf:"bytes,2,opt,name=full_tag_reference,json=fullTagReference,proto3" json:"full_tag_reference,omitempty"`
+	FullTagReference       string                 `protobuf:"bytes,2,opt,name=full_tag_reference,json=fullTagReference,proto3" json:"full_tag_reference,omitempty"`
-	// Raw Galaxy SQL `dbo.data_type` identifier, passed through unchanged.
+	MxDataType             int32                  `protobuf:"varint,3,opt,name=mx_data_type,json=mxDataType,proto3" json:"mx_data_type,omitempty"`
-	// This is NOT a member of `mxaccess_gateway.v1.MxDataType` — Galaxy's
+	DataTypeName           string                 `protobuf:"bytes,4,opt,name=data_type_name,json=dataTypeName,proto3" json:"data_type_name,omitempty"`
-	// type enumeration is distinct from MXAccess's wire data-type enum and
+	IsArray                bool                   `protobuf:"varint,5,opt,name=is_array,json=isArray,proto3" json:"is_array,omitempty"`
-	// the two must not be cast or compared. The GalaxyRepository service is
+	ArrayDimension         int32                  `protobuf:"varint,6,opt,name=array_dimension,json=arrayDimension,proto3" json:"array_dimension,omitempty"`
-	// metadata-only and deliberately does not share types with
+	ArrayDimensionPresent  bool                   `protobuf:"varint,7,opt,name=array_dimension_present,json=arrayDimensionPresent,proto3" json:"array_dimension_present,omitempty"`
-	// mxaccess_gateway.proto. See docs/GalaxyRepository.md.
+	MxAttributeCategory    int32                  `protobuf:"varint,8,opt,name=mx_attribute_category,json=mxAttributeCategory,proto3" json:"mx_attribute_category,omitempty"`
-	MxDataType int32 `protobuf:"varint,3,opt,name=mx_data_type,json=mxDataType,proto3" json:"mx_data_type,omitempty"`
+	SecurityClassification int32                  `protobuf:"varint,9,opt,name=security_classification,json=securityClassification,proto3" json:"security_classification,omitempty"`
-	// Human-readable name from Galaxy's `dbo.data_type` table (e.g. "Float",
+	IsHistorized           bool                   `protobuf:"varint,10,opt,name=is_historized,json=isHistorized,proto3" json:"is_historized,omitempty"`
-	// "Integer", "Boolean"). Free-form Galaxy text; not a stable enum.
+	IsAlarm                bool                   `protobuf:"varint,11,opt,name=is_alarm,json=isAlarm,proto3" json:"is_alarm,omitempty"`
-	DataTypeName          string `protobuf:"bytes,4,opt,name=data_type_name,json=dataTypeName,proto3" json:"data_type_name,omitempty"`
-	IsArray               bool   `protobuf:"varint,5,opt,name=is_array,json=isArray,proto3" json:"is_array,omitempty"`
-	ArrayDimension        int32  `protobuf:"varint,6,opt,name=array_dimension,json=arrayDimension,proto3" json:"array_dimension,omitempty"`
-	ArrayDimensionPresent bool   `protobuf:"varint,7,opt,name=array_dimension_present,json=arrayDimensionPresent,proto3" json:"array_dimension_present,omitempty"`
-	// Raw Galaxy SQL attribute-category identifier, passed through unchanged.
-	// Galaxy-specific; not mapped to any gateway enum. See
-	// docs/GalaxyRepository.md.
-	MxAttributeCategory int32 `protobuf:"varint,8,opt,name=mx_attribute_category,json=mxAttributeCategory,proto3" json:"mx_attribute_category,omitempty"`
-	// Raw Galaxy SQL security-classification identifier, passed through
-	// unchanged. Galaxy-specific; not mapped to any gateway enum. See
-	// docs/GalaxyRepository.md.
-	SecurityClassification int32 `protobuf:"varint,9,opt,name=security_classification,json=securityClassification,proto3" json:"security_classification,omitempty"`
-	IsHistorized           bool  `protobuf:"varint,10,opt,name=is_historized,json=isHistorized,proto3" json:"is_historized,omitempty"`
-	IsAlarm                bool  `protobuf:"varint,11,opt,name=is_alarm,json=isAlarm,proto3" json:"is_alarm,omitempty"`
 	unknownFields          protoimpl.UnknownFields
 	sizeCache              protoimpl.SizeCache
 }
@@ -902,7 +888,7 @@ const file_galaxy_repository_proto_rawDesc = "" +
 	"\x0eTestConnection\x12+.galaxy_repository.v1.TestConnectionRequest\x1a).galaxy_repository.v1.TestConnectionReply\x12q\n" +
 	"\x11GetLastDeployTime\x12..galaxy_repository.v1.GetLastDeployTimeRequest\x1a,.galaxy_repository.v1.GetLastDeployTimeReply\x12q\n" +
 	"\x11DiscoverHierarchy\x12..galaxy_repository.v1.DiscoverHierarchyRequest\x1a,.galaxy_repository.v1.DiscoverHierarchyReply\x12h\n" +
-	"\x11WatchDeployEvents\x12..galaxy_repository.v1.WatchDeployEventsRequest\x1a!.galaxy_repository.v1.DeployEvent0\x01B-\xaa\x02*ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxyb\x06proto3"
+	"\x11WatchDeployEvents\x12..galaxy_repository.v1.WatchDeployEventsRequest\x1a!.galaxy_repository.v1.DeployEvent0\x01B#\xaa\x02 MxGateway.Contracts.Proto.Galaxyb\x06proto3"
 
 var (
 	file_galaxy_repository_proto_rawDescOnce sync.Once

clients/go/internal/generated/mxaccess_gateway_grpc.pb.go

@@ -24,7 +24,6 @@ const (
 	MxAccessGateway_Invoke_FullMethodName            = "/mxaccess_gateway.v1.MxAccessGateway/Invoke"
 	MxAccessGateway_StreamEvents_FullMethodName      = "/mxaccess_gateway.v1.MxAccessGateway/StreamEvents"
 	MxAccessGateway_AcknowledgeAlarm_FullMethodName  = "/mxaccess_gateway.v1.MxAccessGateway/AcknowledgeAlarm"
-	MxAccessGateway_StreamAlarms_FullMethodName      = "/mxaccess_gateway.v1.MxAccessGateway/StreamAlarms"
 	MxAccessGateway_QueryActiveAlarms_FullMethodName = "/mxaccess_gateway.v1.MxAccessGateway/QueryActiveAlarms"
 )
 
@@ -39,17 +38,6 @@ type MxAccessGatewayClient interface {
 	Invoke(ctx context.Context, in *MxCommandRequest, opts ...grpc.CallOption) (*MxCommandReply, error)
 	StreamEvents(ctx context.Context, in *StreamEventsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[MxEvent], error)
 	AcknowledgeAlarm(ctx context.Context, in *AcknowledgeAlarmRequest, opts ...grpc.CallOption) (*AcknowledgeAlarmReply, error)
-	// Session-less central alarm feed. The stream opens with the current
-	// active-alarm snapshot (one `active_alarm` per alarm), then a single
-	// `snapshot_complete`, then a `transition` for every subsequent change.
-	// Served by the gateway's always-on alarm monitor; any number of clients
-	// fan out from the single monitor without opening a worker session.
-	StreamAlarms(ctx context.Context, in *StreamAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[AlarmFeedMessage], error)
-	// Point-in-time snapshot of the currently-active alarm set served from the
-	// gateway's always-on alarm monitor cache (session-less). Used after a
-	// reconnect to seed Part 9 client state, or to reconcile alarms that may
-	// have been missed during a transport blip. Streamed so callers can
-	// begin processing without buffering the full set.
 	QueryActiveAlarms(ctx context.Context, in *QueryActiveAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[ActiveAlarmSnapshot], error)
 }
 
@@ -120,28 +108,9 @@ func (c *mxAccessGatewayClient) AcknowledgeAlarm(ctx context.Context, in *Acknow
 	return out, nil
 }
 
-func (c *mxAccessGatewayClient) StreamAlarms(ctx context.Context, in *StreamAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[AlarmFeedMessage], error) {
-	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
-	stream, err := c.cc.NewStream(ctx, &MxAccessGateway_ServiceDesc.Streams[1], MxAccessGateway_StreamAlarms_FullMethodName, cOpts...)
-	if err != nil {
-		return nil, err
-	}
-	x := &grpc.GenericClientStream[StreamAlarmsRequest, AlarmFeedMessage]{ClientStream: stream}
-	if err := x.ClientStream.SendMsg(in); err != nil {
-		return nil, err
-	}
-	if err := x.ClientStream.CloseSend(); err != nil {
-		return nil, err
-	}
-	return x, nil
-}
-
-// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
-type MxAccessGateway_StreamAlarmsClient = grpc.ServerStreamingClient[AlarmFeedMessage]
-
 func (c *mxAccessGatewayClient) QueryActiveAlarms(ctx context.Context, in *QueryActiveAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[ActiveAlarmSnapshot], error) {
 	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
-	stream, err := c.cc.NewStream(ctx, &MxAccessGateway_ServiceDesc.Streams[2], MxAccessGateway_QueryActiveAlarms_FullMethodName, cOpts...)
+	stream, err := c.cc.NewStream(ctx, &MxAccessGateway_ServiceDesc.Streams[1], MxAccessGateway_QueryActiveAlarms_FullMethodName, cOpts...)
 	if err != nil {
 		return nil, err
 	}
@@ -169,17 +138,6 @@ type MxAccessGatewayServer interface {
 	Invoke(context.Context, *MxCommandRequest) (*MxCommandReply, error)
 	StreamEvents(*StreamEventsRequest, grpc.ServerStreamingServer[MxEvent]) error
 	AcknowledgeAlarm(context.Context, *AcknowledgeAlarmRequest) (*AcknowledgeAlarmReply, error)
-	// Session-less central alarm feed. The stream opens with the current
-	// active-alarm snapshot (one `active_alarm` per alarm), then a single
-	// `snapshot_complete`, then a `transition` for every subsequent change.
-	// Served by the gateway's always-on alarm monitor; any number of clients
-	// fan out from the single monitor without opening a worker session.
-	StreamAlarms(*StreamAlarmsRequest, grpc.ServerStreamingServer[AlarmFeedMessage]) error
-	// Point-in-time snapshot of the currently-active alarm set served from the
-	// gateway's always-on alarm monitor cache (session-less). Used after a
-	// reconnect to seed Part 9 client state, or to reconcile alarms that may
-	// have been missed during a transport blip. Streamed so callers can
-	// begin processing without buffering the full set.
 	QueryActiveAlarms(*QueryActiveAlarmsRequest, grpc.ServerStreamingServer[ActiveAlarmSnapshot]) error
 	mustEmbedUnimplementedMxAccessGatewayServer()
 }
@@ -206,9 +164,6 @@ func (UnimplementedMxAccessGatewayServer) StreamEvents(*StreamEventsRequest, grp
 func (UnimplementedMxAccessGatewayServer) AcknowledgeAlarm(context.Context, *AcknowledgeAlarmRequest) (*AcknowledgeAlarmReply, error) {
 	return nil, status.Error(codes.Unimplemented, "method AcknowledgeAlarm not implemented")
 }
-func (UnimplementedMxAccessGatewayServer) StreamAlarms(*StreamAlarmsRequest, grpc.ServerStreamingServer[AlarmFeedMessage]) error {
-	return status.Error(codes.Unimplemented, "method StreamAlarms not implemented")
-}
 func (UnimplementedMxAccessGatewayServer) QueryActiveAlarms(*QueryActiveAlarmsRequest, grpc.ServerStreamingServer[ActiveAlarmSnapshot]) error {
 	return status.Error(codes.Unimplemented, "method QueryActiveAlarms not implemented")
 }
@@ -316,17 +271,6 @@ func _MxAccessGateway_AcknowledgeAlarm_Handler(srv interface{}, ctx context.Cont
 	return interceptor(ctx, in, info, handler)
 }
 
-func _MxAccessGateway_StreamAlarms_Handler(srv interface{}, stream grpc.ServerStream) error {
-	m := new(StreamAlarmsRequest)
-	if err := stream.RecvMsg(m); err != nil {
-		return err
-	}
-	return srv.(MxAccessGatewayServer).StreamAlarms(m, &grpc.GenericServerStream[StreamAlarmsRequest, AlarmFeedMessage]{ServerStream: stream})
-}
-
-// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
-type MxAccessGateway_StreamAlarmsServer = grpc.ServerStreamingServer[AlarmFeedMessage]
-
 func _MxAccessGateway_QueryActiveAlarms_Handler(srv interface{}, stream grpc.ServerStream) error {
 	m := new(QueryActiveAlarmsRequest)
 	if err := stream.RecvMsg(m); err != nil {
@@ -368,11 +312,6 @@ var MxAccessGateway_ServiceDesc = grpc.ServiceDesc{
 			Handler:       _MxAccessGateway_StreamEvents_Handler,
 			ServerStreams: true,
 		},
-		{
-			StreamName:    "StreamAlarms",
-			Handler:       _MxAccessGateway_StreamAlarms_Handler,
-			ServerStreams: true,
-		},
 		{
 			StreamName:    "QueryActiveAlarms",
 			Handler:       _MxAccessGateway_QueryActiveAlarms_Handler,

clients/go/internal/generated/mxaccess_worker.pb.go

@@ -1179,7 +1179,7 @@ const file_mxaccess_worker_proto_rawDesc = "" +
 	"\x1eWORKER_FAULT_CATEGORY_STA_HUNG\x10\t\x12(\n" +
 	"$WORKER_FAULT_CATEGORY_QUEUE_OVERFLOW\x10\n" +
 	"\x12*\n" +
-	"&WORKER_FAULT_CATEGORY_SHUTDOWN_TIMEOUT\x10\vB&\xaa\x02#ZB.MOM.WW.MxGateway.Contracts.Protob\x06proto3"
+	"&WORKER_FAULT_CATEGORY_SHUTDOWN_TIMEOUT\x10\vB\x1c\xaa\x02\x19MxGateway.Contracts.Protob\x06proto3"
 
 var (
 	file_mxaccess_worker_proto_rawDescOnce sync.Once

clients/go/mxgateway/alarms_test.go

@@ -20,6 +20,7 @@ import (
 func TestAcknowledgeAlarmSendsRequestAndReturnsReply(t *testing.T) {
 	fake := &fakeGatewayWithAlarms{
 		acknowledgeReply: &pb.AcknowledgeAlarmReply{
+			SessionId:     "session-1",
 			CorrelationId: "corr-1",
 			ProtocolStatus: &pb.ProtocolStatus{
 				Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
@@ -34,6 +35,7 @@ func TestAcknowledgeAlarmSendsRequestAndReturnsReply(t *testing.T) {
 	defer cleanup()
 
 	reply, err := client.AcknowledgeAlarm(context.Background(), &pb.AcknowledgeAlarmRequest{
+		SessionId:           "session-1",
 		ClientCorrelationId: "corr-1",
 		AlarmFullReference:  "Tank01.Level.HiHi",
 		Comment:             "investigating",
@@ -79,6 +81,7 @@ func TestAcknowledgeAlarmMapsUnauthenticated(t *testing.T) {
 	defer cleanup()
 
 	_, err := client.AcknowledgeAlarm(context.Background(), &pb.AcknowledgeAlarmRequest{
+		SessionId:          "session-1",
 		AlarmFullReference: "Tank01.Level.HiHi",
 		OperatorUser:       "alice",
 	})
@@ -147,8 +150,8 @@ func TestQueryActiveAlarmsPassesFilterPrefix(t *testing.T) {
 	defer cleanup()
 
 	stream, err := client.QueryActiveAlarms(context.Background(), &pb.QueryActiveAlarmsRequest{
-		SessionId:          "session-1",
+		SessionId:         "session-1",
-		AlarmFilterPrefix:  "Tank01.",
+		AlarmFilterPrefix: "Tank01.",
 	})
 	if err != nil {
 		t.Fatalf("QueryActiveAlarms() error = %v", err)
@@ -190,7 +193,7 @@ func (s *fakeGatewayWithAlarms) AcknowledgeAlarm(ctx context.Context, req *pb.Ac
 		return s.acknowledgeReply, nil
 	}
 	return &pb.AcknowledgeAlarmReply{
-		CorrelationId: req.GetClientCorrelationId(),
+		SessionId: req.GetSessionId(),
 		ProtocolStatus: &pb.ProtocolStatus{
 			Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
 		},
@@ -218,8 +221,10 @@ func newBufconnClientWithAlarms(t *testing.T, fake *fakeGatewayWithAlarms) (*Cli
 	dialer := func(ctx context.Context, _ string) (net.Conn, error) {
 		return listener.DialContext(ctx)
 	}
+	// grpc.NewClient defaults to the dns scheme; use passthrough so the
+	// bufconn fake target reaches the context dialer unresolved.
 	client, err := Dial(context.Background(), Options{
-		Endpoint:    "bufnet",
+		Endpoint:    "passthrough:///bufnet",
 		APIKey:      "test-api-key",
 		Plaintext:   true,
 		DialOptions: []grpc.DialOption{grpc.WithContextDialer(dialer)},

clients/go/mxgateway/client.go

@@ -19,6 +19,7 @@ import (
 
 	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
 	"google.golang.org/grpc"
+	"google.golang.org/grpc/connectivity"
 	"google.golang.org/grpc/credentials"
 	"google.golang.org/grpc/credentials/insecure"
 	"google.golang.org/protobuf/types/known/durationpb"
@@ -36,22 +37,36 @@ type Client struct {
 	opts Options
 }
 
-// Dial opens a gRPC connection to the gateway and configures auth metadata,
+// Dial opens a gRPC connection to the gateway and configures auth metadata
-// transport security, and blocking dial cancellation from ctx.
+// and transport security.
+//
+// The connection is created lazily with grpc.NewClient: the channel is not
+// established until the first RPC (or the readiness probe below) needs it, so
+// a gateway that is briefly unavailable at Dial time no longer turns into a
+// hard error — the connection recovers when the gateway comes up. To preserve
+// fail-fast behavior, Dial then runs an explicit readiness probe bounded by
+// DialTimeout (default 10s, or ctx's deadline when sooner): it triggers the
+// initial connect and waits for the channel to reach Ready, returning a
+// *GatewayError if the gateway cannot be reached in that window. Cancelling
+// ctx aborts the probe.
 func Dial(ctx context.Context, opts Options) (*Client, error) {
+	conn, err := dial(ctx, opts)
+	if err != nil {
+		return nil, err
+	}
+
+	return NewClient(conn, opts), nil
+}
+
+// dial builds the shared gRPC connection used by both Client and GalaxyClient:
+// it resolves transport credentials, assembles dial options, creates a lazy
+// connection with grpc.NewClient, and runs the DialTimeout-bounded readiness
+// probe so callers still fail fast when the gateway is unreachable.
+func dial(ctx context.Context, opts Options) (*grpc.ClientConn, error) {
 	if opts.Endpoint == "" {
 		return nil, errors.New("mxgateway: endpoint is required")
 	}
 
-	dialCtx := ctx
-	cancel := func() {}
-	if opts.DialTimeout > 0 {
-		dialCtx, cancel = context.WithTimeout(ctx, opts.DialTimeout)
-	} else if _, ok := ctx.Deadline(); !ok {
-		dialCtx, cancel = context.WithTimeout(ctx, defaultDialTimeout)
-	}
-	defer cancel()
-
 	transportCredentials, err := resolveTransportCredentials(opts)
 	if err != nil {
 		return nil, err
@@ -61,16 +76,46 @@ func Dial(ctx context.Context, opts Options) (*Client, error) {
 		grpc.WithTransportCredentials(transportCredentials),
 		grpc.WithUnaryInterceptor(unaryAuthInterceptor(opts.APIKey)),
 		grpc.WithStreamInterceptor(streamAuthInterceptor(opts.APIKey)),
-		grpc.WithBlock(),
 	}
 	dialOptions = append(dialOptions, opts.DialOptions...)
 
-	conn, err := grpc.DialContext(dialCtx, opts.Endpoint, dialOptions...)
+	conn, err := grpc.NewClient(opts.Endpoint, dialOptions...)
 	if err != nil {
 		return nil, &GatewayError{Op: "dial", Err: err}
 	}
 
-	return NewClient(conn, opts), nil
+	if err := waitForReady(ctx, conn, opts.DialTimeout); err != nil {
+		_ = conn.Close()
+		return nil, &GatewayError{Op: "dial", Err: err}
+	}
+
+	return conn, nil
+}
+
+// waitForReady triggers the initial connect on conn and blocks until the
+// channel reaches connectivity.Ready, the timeout elapses, or ctx is
+// cancelled. The wait is bounded by dialTimeout when positive, otherwise by
+// ctx's existing deadline, otherwise by defaultDialTimeout.
+func waitForReady(ctx context.Context, conn *grpc.ClientConn, dialTimeout time.Duration) error {
+	probeCtx := ctx
+	cancel := func() {}
+	if dialTimeout > 0 {
+		probeCtx, cancel = context.WithTimeout(ctx, dialTimeout)
+	} else if _, ok := ctx.Deadline(); !ok {
+		probeCtx, cancel = context.WithTimeout(ctx, defaultDialTimeout)
+	}
+	defer cancel()
+
+	conn.Connect()
+	for {
+		state := conn.GetState()
+		if state == connectivity.Ready {
+			return nil
+		}
+		if !conn.WaitForStateChange(probeCtx, state) {
+			return probeCtx.Err()
+		}
+	}
 }
 
 // NewClient wraps an existing gRPC connection. The caller owns closing conn
@@ -188,7 +233,15 @@ func (c *Client) Close() error {
 }
 
 func (c *Client) callContext(ctx context.Context) (context.Context, context.CancelFunc) {
-	timeout := c.opts.CallTimeout
+	return callContext(ctx, c.opts.CallTimeout)
+}
+
+// callContext derives a per-RPC context from ctx, applying callTimeout: zero
+// uses defaultCallTimeout, a negative value disables the bound entirely, and a
+// caller-supplied deadline that is already sooner than the derived timeout is
+// kept as-is rather than being lengthened.
+func callContext(ctx context.Context, callTimeout time.Duration) (context.Context, context.CancelFunc) {
+	timeout := callTimeout
 	if timeout == 0 {
 		timeout = defaultCallTimeout
 	}

clients/go/mxgateway/client_session_test.go

@@ -117,7 +117,7 @@ func TestEventsAfterCancelsStreamWhenCompatibilityChannelIsAbandoned(t *testing.
 	fake := &fakeGatewayServer{
 		streamStarted:    make(chan struct{}),
 		streamDone:       make(chan struct{}),
-		streamEventCount: 64,
+		streamEventCount: 256,
 	}
 	client, cleanup := newBufconnClient(t, fake)
 	defer cleanup()
@@ -135,12 +135,25 @@ func TestEventsAfterCancelsStreamWhenCompatibilityChannelIsAbandoned(t *testing.
 		t.Fatal("compatibility event stream did not stop after result channel filled")
 	}
 
+	// A slow consumer that abandons the buffer must still receive an explicit
+	// terminal overflow error before the channel closes, so it can tell
+	// "events dropped" apart from "stream ended normally".
+	var sawOverflow bool
 	for {
 		select {
-		case _, ok := <-events:
+		case result, ok := <-events:
 			if !ok {
+				if !sawOverflow {
+					t.Fatal("compatibility event channel closed without an ErrEventBufferOverflow result")
+				}
 				return
 			}
+			if result.Err != nil {
+				if !errors.Is(result.Err, ErrEventBufferOverflow) {
+					t.Fatalf("terminal result error = %v, want ErrEventBufferOverflow", result.Err)
+				}
+				sawOverflow = true
+			}
 		case <-time.After(2 * time.Second):
 			t.Fatal("compatibility event channel did not close")
 		}
@@ -279,8 +292,11 @@ func newBufconnClient(t *testing.T, fake *fakeGatewayServer) (*Client, func()) {
 	dialer := func(ctx context.Context, _ string) (net.Conn, error) {
 		return listener.DialContext(ctx)
 	}
+	// grpc.NewClient defaults the target scheme to dns; the bufconn fake name
+	// is not DNS-resolvable, so use the passthrough scheme to hand the target
+	// straight to the context dialer.
 	client, err := Dial(context.Background(), Options{
-		Endpoint:  "bufnet",
+		Endpoint:  "passthrough:///bufnet",
 		APIKey:    "test-api-key",
 		Plaintext: true,
 		DialOptions: []grpc.DialOption{

clients/go/mxgateway/coverage_test.go

@@ -0,0 +1,401 @@
+package mxgateway
+
+import (
+	"context"
+	"crypto/tls"
+	"errors"
+	"net"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/credentials/insecure"
+	"google.golang.org/grpc/status"
+	"google.golang.org/protobuf/types/known/timestamppb"
+)
+
+// --- Client.Go-008: resolveTransportCredentials precedence -----------------
+
+// TestResolveTransportCredentialsPrecedence covers every branch of
+// resolveTransportCredentials, which previously only had the Plaintext path
+// exercised.
+func TestResolveTransportCredentialsPrecedence(t *testing.T) {
+	custom := insecure.NewCredentials()
+
+	t.Run("TransportCredentialsWins", func(t *testing.T) {
+		creds, err := resolveTransportCredentials(Options{
+			TransportCredentials: custom,
+			Plaintext:            true, // must be ignored
+		})
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if creds != custom {
+			t.Fatal("expected the explicit TransportCredentials to be returned as-is")
+		}
+	})
+
+	t.Run("Plaintext", func(t *testing.T) {
+		creds, err := resolveTransportCredentials(Options{Plaintext: true})
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got := creds.Info().SecurityProtocol; got != "insecure" {
+			t.Fatalf("expected insecure credentials, got security protocol %q", got)
+		}
+	})
+
+	t.Run("CACertFileMissingErrors", func(t *testing.T) {
+		_, err := resolveTransportCredentials(Options{CACertFile: "does-not-exist.pem"})
+		if err == nil {
+			t.Fatal("expected an error for a missing CA cert file")
+		}
+	})
+
+	t.Run("TLSConfigWithServerNameOverride", func(t *testing.T) {
+		creds, err := resolveTransportCredentials(Options{
+			TLSConfig:          &tls.Config{MinVersion: tls.VersionTLS13},
+			ServerNameOverride: "gateway.internal",
+		})
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got := creds.Info().ServerName; got != "gateway.internal" {
+			t.Fatalf("expected ServerName override to be applied, got %q", got)
+		}
+	})
+
+	t.Run("DefaultTLSFloor", func(t *testing.T) {
+		creds, err := resolveTransportCredentials(Options{ServerNameOverride: "host"})
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got := creds.Info().SecurityProtocol; got != "tls" {
+			t.Fatalf("expected the default TLS credentials, got %q", got)
+		}
+	})
+}
+
+// TestResolveTransportCredentialsDoesNotMutateTLSConfig confirms the supplied
+// TLSConfig is cloned, not mutated, when ServerNameOverride is applied.
+func TestResolveTransportCredentialsDoesNotMutateTLSConfig(t *testing.T) {
+	cfg := &tls.Config{MinVersion: tls.VersionTLS12}
+	if _, err := resolveTransportCredentials(Options{
+		TLSConfig:          cfg,
+		ServerNameOverride: "override",
+	}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if cfg.ServerName != "" {
+		t.Fatalf("resolveTransportCredentials mutated the caller's TLSConfig (ServerName=%q)", cfg.ServerName)
+	}
+}
+
+// --- Client.Go-008: callContext deadline arithmetic ------------------------
+
+// TestCallContextDeadlineArithmetic covers the shared callContext deadline
+// logic, including the negative-timeout disable case and the
+// caller-deadline-is-sooner case.
+func TestCallContextDeadlineArithmetic(t *testing.T) {
+	t.Run("ZeroUsesDefault", func(t *testing.T) {
+		ctx, cancel := callContext(context.Background(), 0)
+		defer cancel()
+		deadline, ok := ctx.Deadline()
+		if !ok {
+			t.Fatal("expected a deadline for the default timeout")
+		}
+		remaining := time.Until(deadline)
+		if remaining <= 0 || remaining > defaultCallTimeout+time.Second {
+			t.Fatalf("default deadline out of range: %v", remaining)
+		}
+	})
+
+	t.Run("NegativeDisablesBound", func(t *testing.T) {
+		base := context.Background()
+		ctx, cancel := callContext(base, -1)
+		defer cancel()
+		if _, ok := ctx.Deadline(); ok {
+			t.Fatal("a negative timeout must disable the deadline entirely")
+		}
+		if ctx != base {
+			t.Fatal("a negative timeout must return the caller context unchanged")
+		}
+	})
+
+	t.Run("PositiveAppliesTimeout", func(t *testing.T) {
+		ctx, cancel := callContext(context.Background(), 5*time.Second)
+		defer cancel()
+		deadline, ok := ctx.Deadline()
+		if !ok {
+			t.Fatal("expected a deadline")
+		}
+		remaining := time.Until(deadline)
+		if remaining <= 0 || remaining > 5*time.Second+time.Second {
+			t.Fatalf("deadline out of range: %v", remaining)
+		}
+	})
+
+	t.Run("CallerDeadlineSoonerIsKept", func(t *testing.T) {
+		base, baseCancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+		defer baseCancel()
+		ctx, cancel := callContext(base, 30*time.Second)
+		defer cancel()
+		if ctx != base {
+			t.Fatal("a caller deadline sooner than the timeout must be kept as-is")
+		}
+	})
+
+	t.Run("CallerDeadlineLaterIsShortened", func(t *testing.T) {
+		base, baseCancel := context.WithTimeout(context.Background(), time.Hour)
+		defer baseCancel()
+		ctx, cancel := callContext(base, time.Second)
+		defer cancel()
+		deadline, ok := ctx.Deadline()
+		if !ok {
+			t.Fatal("expected a deadline")
+		}
+		if remaining := time.Until(deadline); remaining > 2*time.Second {
+			t.Fatalf("expected the shorter timeout to win, got %v remaining", remaining)
+		}
+	})
+}
+
+// --- Client.Go-008: NativeValue / NativeArray edge branches ----------------
+
+// TestNativeValueEdgeKinds covers the array, raw-bytes, null, and
+// nil-input branches of NativeValue.
+func TestNativeValueEdgeKinds(t *testing.T) {
+	t.Run("NilInput", func(t *testing.T) {
+		got, err := NativeValue(nil)
+		if err != nil || got != nil {
+			t.Fatalf("NativeValue(nil) = (%v, %v), want (nil, nil)", got, err)
+		}
+	})
+
+	t.Run("ExplicitNull", func(t *testing.T) {
+		got, err := NativeValue(&pb.MxValue{IsNull: true})
+		if err != nil || got != nil {
+			t.Fatalf("NativeValue(null) = (%v, %v), want (nil, nil)", got, err)
+		}
+	})
+
+	t.Run("RawBytes", func(t *testing.T) {
+		raw := []byte{0x01, 0x02, 0x03}
+		got, err := NativeValue(&pb.MxValue{Kind: &pb.MxValue_RawValue{RawValue: raw}})
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		gotBytes, ok := got.([]byte)
+		if !ok || !reflect.DeepEqual(gotBytes, raw) {
+			t.Fatalf("NativeValue raw = %v, want %v", got, raw)
+		}
+		// The result must be a copy, not aliasing the protobuf field.
+		gotBytes[0] = 0xFF
+		if raw[0] != 0x01 {
+			t.Fatal("NativeValue raw result aliases the protobuf backing array")
+		}
+	})
+
+	t.Run("ArrayValue", func(t *testing.T) {
+		value := &pb.MxValue{Kind: &pb.MxValue_ArrayValue{
+			ArrayValue: &pb.MxArray{Values: &pb.MxArray_Int32Values{
+				Int32Values: &pb.Int32Array{Values: []int32{7, 8}},
+			}},
+		}}
+		got, err := NativeValue(value)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if !reflect.DeepEqual(got, []int32{7, 8}) {
+			t.Fatalf("NativeValue array = %v, want [7 8]", got)
+		}
+	})
+}
+
+// TestNativeArrayEdgeKinds covers the nil, raw-bytes, timestamp-with-nil, and
+// unsupported-kind branches of NativeArray.
+func TestNativeArrayEdgeKinds(t *testing.T) {
+	t.Run("NilInput", func(t *testing.T) {
+		got, err := NativeArray(nil)
+		if err != nil || got != nil {
+			t.Fatalf("NativeArray(nil) = (%v, %v), want (nil, nil)", got, err)
+		}
+	})
+
+	t.Run("RawValues", func(t *testing.T) {
+		got, err := NativeArray(&pb.MxArray{Values: &pb.MxArray_RawValues{
+			RawValues: &pb.RawArray{Values: [][]byte{{0x0A}, {0x0B}}},
+		}})
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		want := [][]byte{{0x0A}, {0x0B}}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("NativeArray raw = %v, want %v", got, want)
+		}
+	})
+
+	t.Run("TimestampWithNilEntry", func(t *testing.T) {
+		got, err := NativeArray(&pb.MxArray{Values: &pb.MxArray_TimestampValues{
+			TimestampValues: &pb.TimestampArray{Values: []*timestamppb.Timestamp{nil}},
+		}})
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		times, ok := got.([]time.Time)
+		if !ok || len(times) != 1 || !times[0].IsZero() {
+			t.Fatalf("NativeArray timestamp-with-nil = %v, want [zero-time]", got)
+		}
+	})
+
+	t.Run("UnsupportedKind", func(t *testing.T) {
+		// An MxArray with no oneof set hits the default branch.
+		_, err := NativeArray(&pb.MxArray{})
+		if err == nil {
+			t.Fatal("expected an error for an MxArray with no values set")
+		}
+		if !strings.Contains(err.Error(), "unsupported array value kind") {
+			t.Fatalf("unexpected error text: %v", err)
+		}
+	})
+}
+
+// TestNativeValueUnsupportedKind covers the default branch of NativeValue.
+func TestNativeValueUnsupportedKind(t *testing.T) {
+	// An MxValue with no oneof Kind set and IsNull false hits the default.
+	_, err := NativeValue(&pb.MxValue{})
+	if err == nil {
+		t.Fatal("expected an error for an MxValue with no kind set")
+	}
+	if !strings.Contains(err.Error(), "unsupported value kind") {
+		t.Fatalf("unexpected error text: %v", err)
+	}
+}
+
+// --- Client.Go-005: dial migration -----------------------------------------
+
+// TestDialFailsFastWhenGatewayUnreachable confirms that after the migration to
+// grpc.NewClient the DialTimeout-bounded readiness probe still fails fast (and
+// wraps the failure in *GatewayError) when the gateway cannot be reached.
+func TestDialFailsFastWhenGatewayUnreachable(t *testing.T) {
+	dialer := func(ctx context.Context, _ string) (net.Conn, error) {
+		return nil, errors.New("connection refused")
+	}
+	start := time.Now()
+	client, err := Dial(context.Background(), Options{
+		Endpoint:    "passthrough:///unreachable",
+		APIKey:      "k",
+		Plaintext:   true,
+		DialTimeout: 500 * time.Millisecond,
+		DialOptions: []grpc.DialOption{grpc.WithContextDialer(dialer)},
+	})
+	elapsed := time.Since(start)
+	if err == nil {
+		client.Close()
+		t.Fatal("expected Dial to fail for an unreachable gateway")
+	}
+	var gwErr *GatewayError
+	if !errors.As(err, &gwErr) || gwErr.Op != "dial" {
+		t.Fatalf("expected a *GatewayError with Op=dial, got %#v", err)
+	}
+	if elapsed > 5*time.Second {
+		t.Fatalf("Dial did not honor DialTimeout: took %v", elapsed)
+	}
+}
+
+// TestDialReadinessProbeReachesReady confirms the readiness probe succeeds
+// against a live (bufconn) gateway, i.e. the lazy grpc.NewClient connection is
+// driven to Ready before Dial returns.
+func TestDialReadinessProbeReachesReady(t *testing.T) {
+	client, cleanup := newBufconnClient(t, &fakeGatewayServer{
+		openReply: &pb.OpenSessionReply{},
+	})
+	defer cleanup()
+	if client == nil {
+		t.Fatal("expected a connected client")
+	}
+}
+
+// --- Client.Go-006: error taxonomy ----------------------------------------
+
+// TestGatewayErrorCode confirms GatewayError.Code surfaces the wrapped gRPC
+// status code without the caller unwrapping it.
+func TestGatewayErrorCode(t *testing.T) {
+	var nilErr *GatewayError
+	if got := nilErr.Code(); got != codes.OK {
+		t.Fatalf("nil GatewayError.Code() = %v, want OK", got)
+	}
+
+	gwErr := &GatewayError{Op: "invoke", Err: status.Error(codes.Unavailable, "down")}
+	if got := gwErr.Code(); got != codes.Unavailable {
+		t.Fatalf("GatewayError.Code() = %v, want Unavailable", got)
+	}
+
+	plain := &GatewayError{Op: "dial", Err: errors.New("boom")}
+	if got := plain.Code(); got != codes.Unknown {
+		t.Fatalf("GatewayError.Code() for a non-status error = %v, want Unknown", got)
+	}
+}
+
+// TestIsTransient verifies the transient/permanent classification including
+// the unwrap-through-GatewayError path.
+func TestIsTransient(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{name: "nil", err: nil, want: false},
+		{name: "unavailable wrapped", err: &GatewayError{Op: "invoke", Err: status.Error(codes.Unavailable, "x")}, want: true},
+		{name: "deadline wrapped", err: &GatewayError{Op: "invoke", Err: status.Error(codes.DeadlineExceeded, "x")}, want: true},
+		{name: "resource exhausted", err: &GatewayError{Err: status.Error(codes.ResourceExhausted, "x")}, want: true},
+		{name: "unauthenticated permanent", err: &GatewayError{Err: status.Error(codes.Unauthenticated, "x")}, want: false},
+		{name: "invalid argument permanent", err: &GatewayError{Err: status.Error(codes.InvalidArgument, "x")}, want: false},
+		{name: "bare status unavailable", err: status.Error(codes.Unavailable, "x"), want: true},
+		{name: "plain error", err: errors.New("nope"), want: false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := IsTransient(tt.err); got != tt.want {
+				t.Fatalf("IsTransient(%v) = %v, want %v", tt.err, got, tt.want)
+			}
+		})
+	}
+}
+
+// --- Client.Go-007: correlation id fallback --------------------------------
+
+// TestNewCorrelationIDUsesRandEntropy confirms the happy path yields a
+// 32-hex-character id.
+func TestNewCorrelationIDUsesRandEntropy(t *testing.T) {
+	id := newCorrelationID()
+	if len(id) != 32 {
+		t.Fatalf("expected a 32-char hex id, got %q (len %d)", id, len(id))
+	}
+}
+
+// TestNewCorrelationIDFallsBackOnRandFailure reproduces Client.Go-007: when
+// crypto/rand fails, newCorrelationID must not return an empty string but a
+// unique, non-empty fallback id so the command stays traceable.
+func TestNewCorrelationIDFallsBackOnRandFailure(t *testing.T) {
+	original := randRead
+	randRead = func([]byte) (int, error) { return 0, errors.New("entropy unavailable") }
+	defer func() { randRead = original }()
+
+	first := newCorrelationID()
+	second := newCorrelationID()
+
+	if first == "" || second == "" {
+		t.Fatal("newCorrelationID returned an empty id on rand failure")
+	}
+	if !strings.HasPrefix(first, "fallback-") {
+		t.Fatalf("expected a fallback- prefixed id, got %q", first)
+	}
+	if first == second {
+		t.Fatalf("fallback correlation ids must be unique, got %q twice", first)
+	}
+}

clients/go/mxgateway/errors.go

@@ -1,11 +1,22 @@
 package mxgateway
 
 import (
+	"errors"
 	"fmt"
 
 	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
 )
 
+// ErrEventBufferOverflow is the terminal error delivered on the compatibility
+// event channel returned by Session.Events / Session.EventsAfter when a slow
+// consumer lets the bounded result buffer fill. It signals that the stream was
+// cancelled and events were dropped, so a consumer can tell an overflow apart
+// from a normal end-of-stream. Use Session.SubscribeEvents to block instead of
+// dropping.
+var ErrEventBufferOverflow = errors.New("mxgateway: event buffer overflow; compatibility stream cancelled and events dropped")
+
 // GatewayError wraps transport-level gRPC failures.
 type GatewayError struct {
 	// Op names the operation that failed (for example "dial" or "invoke").
@@ -33,6 +44,45 @@ func (e *GatewayError) Unwrap() error {
 	return e.Err
 }
 
+// Code returns the gRPC status code of the wrapped transport error. It returns
+// codes.OK when the error is nil and codes.Unknown when the wrapped error does
+// not carry a gRPC status. Callers can use it to write retry, timeout, and
+// auth handling without manually unwrapping and re-parsing the error.
+func (e *GatewayError) Code() codes.Code {
+	if e == nil || e.Err == nil {
+		return codes.OK
+	}
+	return status.Code(e.Err)
+}
+
+// IsTransient reports whether err is a transport failure that may succeed on
+// retry — for example a gateway that is briefly Unavailable or a call that
+// hit a DeadlineExceeded. Permanent failures (Unauthenticated, PermissionDenied,
+// InvalidArgument, NotFound, and similar) return false. It unwraps through
+// *GatewayError and any other error chain carrying a gRPC status, so callers
+// do not need to call status.Code themselves.
+func IsTransient(err error) bool {
+	if err == nil {
+		return false
+	}
+	switch transientCode(err) {
+	case codes.Unavailable, codes.DeadlineExceeded, codes.ResourceExhausted, codes.Aborted:
+		return true
+	default:
+		return false
+	}
+}
+
+// transientCode extracts a gRPC status code from err, preferring a wrapped
+// *GatewayError's Code and otherwise falling back to status.Code on the chain.
+func transientCode(err error) codes.Code {
+	var gatewayErr *GatewayError
+	if errors.As(err, &gatewayErr) {
+		return gatewayErr.Code()
+	}
+	return status.Code(err)
+}
+
 // CommandError reports a non-OK gateway protocol status and keeps the raw
 // command reply when one exists.
 type CommandError struct {
@@ -85,8 +135,12 @@ func (e *MxAccessError) Error() string {
 }
 
 // Unwrap returns the wrapped CommandError, when one is present.
+//
+// When Command is nil (the HRESULT / MxStatusProxy path) it returns an
+// untyped nil rather than a typed-nil *CommandError, so errors.As does not
+// bind a nil pointer that a caller would then panic on.
 func (e *MxAccessError) Unwrap() error {
-	if e == nil {
+	if e == nil || e.Command == nil {
 		return nil
 	}
 	return e.Command

clients/go/mxgateway/errors_test.go

@@ -0,0 +1,42 @@
+package mxgateway
+
+import (
+	"errors"
+	"testing"
+)
+
+// TestMxAccessErrorUnwrapHResultPathNoTypedNilCommandError reproduces
+// Client.Go-001: an MxAccessError built via the HRESULT / MxStatusProxy path
+// leaves Command nil. Unwrap must not hand back a typed-nil *CommandError,
+// because errors.As would then succeed while binding a nil pointer and a
+// caller dereferencing it would panic.
+func TestMxAccessErrorUnwrapHResultPathNoTypedNilCommandError(t *testing.T) {
+	hresult := int32(-2147467259) // 0x80004005, a failing HRESULT.
+	reply := &MxCommandReply{Hresult: &hresult}
+
+	err := EnsureMxAccessSuccess("invoke", reply)
+	if err == nil {
+		t.Fatal("expected MxAccessError for a failing HRESULT, got nil")
+	}
+
+	var ce *CommandError
+	if errors.As(err, &ce) {
+		t.Fatalf("errors.As bound *CommandError from an HRESULT-only MxAccessError (ce=%v); "+
+			"a caller dereferencing ce.Status would panic", ce)
+	}
+}
+
+// TestMxAccessErrorUnwrapPopulatedCommand confirms the non-nil Command path
+// still unwraps to the wrapped *CommandError.
+func TestMxAccessErrorUnwrapPopulatedCommand(t *testing.T) {
+	command := &CommandError{Op: "invoke"}
+	err := &MxAccessError{Command: command}
+
+	var ce *CommandError
+	if !errors.As(err, &ce) {
+		t.Fatal("errors.As failed to bind the populated *CommandError")
+	}
+	if ce != command {
+		t.Fatalf("errors.As bound an unexpected *CommandError: got %v want %v", ce, command)
+	}
+}

clients/go/mxgateway/galaxy.go

@@ -2,7 +2,6 @@ package mxgateway
 
 import (
 	"context"
-	"errors"
 	"io"
 	"time"
 
@@ -56,39 +55,13 @@ type GalaxyClient struct {
 
 // DialGalaxy opens a gRPC connection to the gateway for the Galaxy Repository
 // service. It applies the same authentication metadata, transport security,
-// and dial-timeout behavior as Dial.
+// lazy connection, and DialTimeout-bounded readiness probe as Dial.
 func DialGalaxy(ctx context.Context, opts Options) (*GalaxyClient, error) {
-	if opts.Endpoint == "" {
+	conn, err := dial(ctx, opts)
-		return nil, errors.New("mxgateway: endpoint is required")
-	}
-
-	dialCtx := ctx
-	cancel := func() {}
-	if opts.DialTimeout > 0 {
-		dialCtx, cancel = context.WithTimeout(ctx, opts.DialTimeout)
-	} else if _, ok := ctx.Deadline(); !ok {
-		dialCtx, cancel = context.WithTimeout(ctx, defaultDialTimeout)
-	}
-	defer cancel()
-
-	transportCredentials, err := resolveTransportCredentials(opts)
 	if err != nil {
 		return nil, err
 	}
 
-	dialOptions := []grpc.DialOption{
-		grpc.WithTransportCredentials(transportCredentials),
-		grpc.WithUnaryInterceptor(unaryAuthInterceptor(opts.APIKey)),
-		grpc.WithStreamInterceptor(streamAuthInterceptor(opts.APIKey)),
-		grpc.WithBlock(),
-	}
-	dialOptions = append(dialOptions, opts.DialOptions...)
-
-	conn, err := grpc.DialContext(dialCtx, opts.Endpoint, dialOptions...)
-	if err != nil {
-		return nil, &GatewayError{Op: "dial", Err: err}
-	}
-
 	return NewGalaxyClient(conn, opts), nil
 }
 
@@ -239,18 +212,5 @@ func (c *GalaxyClient) Close() error {
 }
 
 func (c *GalaxyClient) callContext(ctx context.Context) (context.Context, context.CancelFunc) {
-	timeout := c.opts.CallTimeout
+	return callContext(ctx, c.opts.CallTimeout)
-	if timeout == 0 {
-		timeout = defaultCallTimeout
-	}
-	if timeout < 0 {
-		return ctx, func() {}
-	}
-	if deadline, ok := ctx.Deadline(); ok {
-		timeoutDeadline := time.Now().Add(timeout)
-		if deadline.Before(timeoutDeadline) {
-			return ctx, func() {}
-		}
-	}
-	return context.WithTimeout(ctx, timeout)
 }

clients/go/mxgateway/galaxy_test.go

@@ -55,8 +55,8 @@ func TestGalaxyGetLastDeployTimeReturnsTimestampWhenPresent(t *testing.T) {
 	want := time.Date(2026, 4, 28, 12, 34, 56, 0, time.UTC)
 	fake := &fakeGalaxyServer{
 		deployReply: &pb.GetLastDeployTimeReply{
-			Present:           true,
+			Present:          true,
-			TimeOfLastDeploy:  timestamppb.New(want),
+			TimeOfLastDeploy: timestamppb.New(want),
 		},
 	}
 	client, cleanup := newGalaxyBufconnClient(t, fake)
@@ -348,8 +348,10 @@ func newGalaxyBufconnClient(t *testing.T, fake *fakeGalaxyServer) (*GalaxyClient
 	dialer := func(ctx context.Context, _ string) (net.Conn, error) {
 		return listener.DialContext(ctx)
 	}
+	// grpc.NewClient defaults to the dns scheme; use passthrough so the
+	// bufconn fake target reaches the context dialer unresolved.
 	client, err := DialGalaxy(context.Background(), Options{
-		Endpoint:  "bufnet",
+		Endpoint:  "passthrough:///bufnet",
 		APIKey:    "test-api-key",
 		Plaintext: true,
 		DialOptions: []grpc.DialOption{

clients/go/mxgateway/session.go

@@ -8,6 +8,8 @@ import (
 	"fmt"
 	"io"
 	"sync"
+	"sync/atomic"
+	"time"
 
 	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
 	"google.golang.org/grpc/codes"
@@ -490,7 +492,7 @@ func ensureBulkSize(name string, length int) error {
 
 func sendEventResult(
 	ctx context.Context,
-	results chan<- EventResult,
+	results chan EventResult,
 	result EventResult,
 	cancelWhenBufferFull bool,
 	cancel context.CancelFunc,
@@ -502,7 +504,12 @@ func sendEventResult(
 		case <-ctx.Done():
 			return false
 		default:
+			// The bounded compatibility buffer is full. Cancel the stream and
+			// deliver an explicit terminal overflow error so a slow consumer
+			// can tell dropped events apart from a normal end-of-stream,
+			// rather than seeing the channel close silently.
 			cancel()
+			deliverTerminalResult(results, EventResult{Err: ErrEventBufferOverflow})
 			return false
 		}
 	}
@@ -515,6 +522,25 @@ func sendEventResult(
 	}
 }
 
+// deliverTerminalResult places result on a full buffered channel by evicting
+// one of the oldest buffered events to make room. The caller closes results
+// afterwards, so the terminal result becomes the consumer's last item.
+func deliverTerminalResult(results chan EventResult, result EventResult) {
+	for {
+		select {
+		case results <- result:
+			return
+		default:
+		}
+		select {
+		case <-results:
+		default:
+			// Another receiver drained the channel between the send and
+			// receive attempts; retry the send.
+		}
+	}
+}
+
 func (s *Session) invokeCommand(ctx context.Context, command *MxCommand) (*MxCommandReply, error) {
 	return s.client.Invoke(ctx, &pb.MxCommandRequest{
 		SessionId:           s.ID(),
@@ -523,10 +549,25 @@ func (s *Session) invokeCommand(ctx context.Context, command *MxCommand) (*MxCom
 	})
 }
 
+// correlationIDCounter backs the deterministic fallback id used when
+// crypto/rand is unavailable, so every command still carries a unique,
+// traceable correlation id.
+var correlationIDCounter atomic.Uint64
+
+// randRead is the entropy source for newCorrelationID. It is a package
+// variable solely so tests can simulate a crypto/rand failure.
+var randRead = rand.Read
+
+// newCorrelationID returns a unique correlation id for an MxCommandRequest.
+// It prefers 16 bytes of crypto/rand entropy; if rand.Read fails (rare) it
+// falls back to a "fallback-" prefixed id built from the current time and a
+// process-wide monotonic counter rather than returning an empty string, which
+// would leave the command untraceable in gateway logs.
 func newCorrelationID() string {
 	var buffer [16]byte
-	if _, err := rand.Read(buffer[:]); err != nil {
+	if _, err := randRead(buffer[:]); err != nil {
-		return ""
+		return fmt.Sprintf("fallback-%x-%x",
+			time.Now().UnixNano(), correlationIDCounter.Add(1))
 	}
 	return hex.EncodeToString(buffer[:])
 }

clients/java/JavaClientDesign.md

@@ -18,11 +18,11 @@ clients/java/
   settings.gradle
   build.gradle
   src/main/generated/
-  zb-mom-ww-mxgateway-client/
+  mxgateway-client/
     build.gradle
     src/main/java/com/dohertylan/mxgateway/client/
     src/test/java/com/dohertylan/mxgateway/client/
-  zb-mom-ww-mxgateway-cli/
+  mxgateway-cli/
     build.gradle
     src/main/java/com/dohertylan/mxgateway/cli/
 ```

clients/java/README.md

@@ -10,12 +10,12 @@ clients/java/
   settings.gradle
   build.gradle
   src/main/generated/
-  zb-mom-ww-mxgateway-client/
+  mxgateway-client/
-  zb-mom-ww-mxgateway-cli/
+  mxgateway-cli/
 ```
 
 `mxgateway-client` generates Java protobuf and gRPC sources from
-`../../src/ZB.MOM.WW.MxGateway.Contracts/Protos`. The Gradle protobuf plugin writes those
+`../../src/MxGateway.Contracts/Protos`. The Gradle protobuf plugin writes those
 generated sources under `src/main/generated`, which matches the client proto
 manifest in `../proto/proto-inputs.json`. Do not edit generated files by hand.
 
@@ -62,10 +62,37 @@ underlying protobuf messages. `MxGatewayCommandException` and
 `MxAccessException` preserve the raw `MxCommandReply` when the gateway returns a
 data-bearing MXAccess failure.
 
+`openSession` verifies the gateway's reported `gateway_protocol_version` against
+the version this client was generated for and throws `MxGatewayException` on a
+mismatch, so an incompatible client fails fast with a clear message instead of
+issuing commands that fail downstream. A gateway that does not populate the
+field is accepted unchanged.
+
+`MxGatewaySession` implements `AutoCloseable`. The try-with-resources `close()`
+performs a `CloseSession` network RPC but swallows (and logs) any failure of
+that RPC so a close-time error never replaces the exception a try-with-resources
+body is already propagating. Call `closeRaw()` explicitly when you need to
+observe the close result or handle a close-time failure.
+
+`MxGatewayClient` and `GalaxyRepositoryClient` implement `AutoCloseable`. For a
+client that owns its channel (built with `connect`), the try-with-resources
+`close()` shuts the channel down and waits up to the configured connect timeout
+for termination, forcibly shutting it down on timeout, so in-flight calls and
+Netty event-loop threads are not left running after the block exits. If the
+calling thread is interrupted while waiting, the channel is forcibly shut down
+and the interrupt flag is restored. `closeAndAwaitTermination()` does the same
+but throws `InterruptedException` for callers that want a checked,
+blocking-aware shutdown. `close()` is a no-op for a caller-managed channel.
+
 `MxEventStream` implements `Iterator<MxEvent>` and `AutoCloseable`. Closing it
 cancels the underlying gRPC stream. Canceling or timing out a Java client call
 only stops the client from waiting; it does not abort an in-flight MXAccess COM
-call on the worker STA.
+call on the worker STA. The event stream uses gRPC's default auto-inbound flow
+control with a fixed 16-element buffer and no client-side flow control: this is
+the gateway's documented fail-fast event-backpressure model, so a consumer that
+stalls long enough to fill the buffer triggers an overflow that cancels the
+subscription and surfaces an `MxGatewayException` from the next `next()` call.
+Drain events promptly and be prepared to resubscribe with a resume cursor.
 
 ## Galaxy Repository Browse
 
@@ -205,8 +232,8 @@ Create local library and CLI artifacts from `clients/java`:
 gradle :mxgateway-client:jar :mxgateway-cli:installDist
 ```
 
-The library jar is under `zb-mom-ww-mxgateway-client/build/libs`. The installed CLI
+The library jar is under `mxgateway-client/build/libs`. The installed CLI
-distribution is under `zb-mom-ww-mxgateway-cli/build/install/mxgateway-cli`.
+distribution is under `mxgateway-cli/build/install/mxgateway-cli`.
 
 ## Integration Checks
 

clients/java/build.gradle

@@ -12,7 +12,7 @@ ext {
 }
 
 subprojects {
-    group = 'com.zb.mom.ww.mxgateway'
+    group = 'com.dohertylan.mxgateway'
     version = '0.1.0'
 
     pluginManager.withPlugin('java') {

clients/java/mxgateway-cli/build.gradle

@@ -3,11 +3,11 @@ plugins {
 }
 
 dependencies {
-    implementation project(':zb-mom-ww-mxgateway-client')
+    implementation project(':mxgateway-client')
     implementation "com.google.protobuf:protobuf-java-util:${protobufVersion}"
     implementation "info.picocli:picocli:${picocliVersion}"
 }
 
 application {
-    mainClass = 'com.zb.mom.ww.mxgateway.cli.MxGatewayCli'
+    mainClass = 'com.dohertylan.mxgateway.cli.MxGatewayCli'
 }

clients/java/mxgateway-cli/src/main/java/com/dohertylan/mxgateway/cli/MxGatewayCli.java

@@ -1,14 +1,14 @@
-package com.zb.mom.ww.mxgateway.cli;
+package com.dohertylan.mxgateway.cli;
 
-import com.zb.mom.ww.mxgateway.client.DeployEventStream;
+import com.dohertylan.mxgateway.client.DeployEventStream;
-import com.zb.mom.ww.mxgateway.client.GalaxyRepositoryClient;
+import com.dohertylan.mxgateway.client.GalaxyRepositoryClient;
-import com.zb.mom.ww.mxgateway.client.MxEventStream;
+import com.dohertylan.mxgateway.client.MxEventStream;
-import com.zb.mom.ww.mxgateway.client.MxGatewayClient;
+import com.dohertylan.mxgateway.client.MxGatewayClient;
-import com.zb.mom.ww.mxgateway.client.MxGatewayClientOptions;
+import com.dohertylan.mxgateway.client.MxGatewayClientOptions;
-import com.zb.mom.ww.mxgateway.client.MxGatewayClientVersion;
+import com.dohertylan.mxgateway.client.MxGatewayClientVersion;
-import com.zb.mom.ww.mxgateway.client.MxGatewaySecrets;
+import com.dohertylan.mxgateway.client.MxGatewaySecrets;
-import com.zb.mom.ww.mxgateway.client.MxGatewaySession;
+import com.dohertylan.mxgateway.client.MxGatewaySession;
-import com.zb.mom.ww.mxgateway.client.MxValues;
+import com.dohertylan.mxgateway.client.MxValues;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.GalaxyAttribute;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.GalaxyObject;
@@ -661,33 +661,60 @@ public final class MxGatewayCli implements Callable<Integer> {
         @Option(names = "--timeout", defaultValue = "30s", description = "Per-call timeout.")
         String timeout;
 
-        private String resolvedApiKey = "";
+        /**
-        private Duration resolvedTimeout = Duration.ofSeconds(30);
+         * Returns this options object unchanged.
-
+         *
+         * <p>Retained as a no-op for call sites that read more naturally as
+         * {@code common.resolved()}. Resolution of the API key and timeout is
+         * computed lazily on demand by {@link #resolvedApiKey()} and
+         * {@link #resolvedTimeout()}, so {@link #toClientOptions()} and
+         * {@link #redactedJsonMap()} produce correct output regardless of
+         * whether this method was ever called.
+         *
+         * @return this options object
+         */
         CommonOptions resolved() {
-            resolvedApiKey = apiKey == null || apiKey.isBlank() ? System.getenv(apiKeyEnv) : apiKey;
-            if (resolvedApiKey == null) {
-                resolvedApiKey = "";
-            }
-            resolvedTimeout = parseDuration(timeout);
             return this;
         }
 
+        /**
+         * Resolves the effective API key: the explicit {@code --api-key} value
+         * when non-blank, otherwise the value of the {@code --api-key-env}
+         * environment variable, otherwise an empty string. Computed on each
+         * call so there is no stale cached state.
+         *
+         * @return the resolved API key, never {@code null}
+         */
+        String resolvedApiKey() {
+            String resolved = apiKey == null || apiKey.isBlank() ? System.getenv(apiKeyEnv) : apiKey;
+            return resolved == null ? "" : resolved;
+        }
+
+        /**
+         * Resolves the effective per-call timeout from the {@code --timeout}
+         * option. Computed on each call so there is no stale cached state.
+         *
+         * @return the resolved call timeout
+         */
+        Duration resolvedTimeout() {
+            return parseDuration(timeout);
+        }
+
         MxGatewayClientOptions toClientOptions() {
             return MxGatewayClientOptions.builder()
                     .endpoint(endpoint)
-                    .apiKey(resolvedApiKey)
+                    .apiKey(resolvedApiKey())
                     .plaintext(plaintext)
                     .caCertificatePath(caFile)
                     .serverNameOverride(serverNameOverride)
-                    .callTimeout(resolvedTimeout)
+                    .callTimeout(resolvedTimeout())
                     .build();
         }
 
         Map<String, Object> redactedJsonMap() {
             Map<String, Object> values = new LinkedHashMap<>();
             values.put("endpoint", endpoint);
-            values.put("apiKey", MxGatewaySecrets.redactApiKey(resolvedApiKey));
+            values.put("apiKey", MxGatewaySecrets.redactApiKey(resolvedApiKey()));
             values.put("apiKeyEnv", apiKeyEnv);
             values.put("plaintext", plaintext);
             values.put("caFile", caFile == null ? "" : caFile.toString());

clients/java/mxgateway-cli/src/test/java/com/dohertylan/mxgateway/cli/MxGatewayCliTests.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.cli;
+package com.dohertylan.mxgateway.cli;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
@@ -62,8 +62,10 @@ final class MxGatewayCliTests {
         assertEquals(0, run.exitCode());
         assertTrue(run.output().contains("\"command\":\"open-session\""));
         assertTrue(run.output().contains("\"sessionId\":\"session-cli\""));
-        assertTrue(run.output().contains("mxgw***********cret"));
+        // Only the non-secret mxgw_<key-id>_ prefix survives; the secret is fully masked.
+        assertTrue(run.output().contains("mxgw_visible_***"));
         assertFalse(run.output().contains("visible_secret"));
+        assertFalse(run.output().contains("cret"));
     }
 
     @Test
@@ -296,7 +298,7 @@ final class MxGatewayCliTests {
         }
 
         @Override
-        public com.zb.mom.ww.mxgateway.client.MxEventStream streamEventsAfter(long afterWorkerSequence) {
+        public com.dohertylan.mxgateway.client.MxEventStream streamEventsAfter(long afterWorkerSequence) {
             throw new UnsupportedOperationException("stream-events is covered by client tests");
         }
     }

clients/java/mxgateway-client/build.gradle

@@ -22,7 +22,7 @@ dependencies {
 sourceSets {
     main {
         proto {
-            srcDir rootProject.file('../../src/ZB.MOM.WW.MxGateway.Contracts/Protos')
+            srcDir rootProject.file('../../src/MxGateway.Contracts/Protos')
             include 'mxaccess_gateway.proto'
             include 'mxaccess_worker.proto'
             include 'galaxy_repository.proto'

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/DeployEventStream.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest;

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/DeployEventSubscription.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest;

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/GalaxyRepositoryClient.java

@@ -1,8 +1,5 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
-import com.google.common.util.concurrent.FutureCallback;
-import com.google.common.util.concurrent.Futures;
-import com.google.common.util.concurrent.MoreExecutors;
 import galaxy_repository.v1.GalaxyRepositoryGrpc;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply;
@@ -17,8 +14,6 @@ import com.google.protobuf.Timestamp;
 import io.grpc.Channel;
 import io.grpc.ClientInterceptors;
 import io.grpc.ManagedChannel;
-import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
-import io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder;
 import io.grpc.stub.StreamObserver;
 import java.time.Instant;
 import java.util.Iterator;
@@ -27,7 +22,6 @@ import java.util.Objects;
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.TimeUnit;
-import javax.net.ssl.SSLException;
 
 /**
  * Thin wrapper around the generated {@link GalaxyRepositoryGrpc} stubs that
@@ -78,7 +72,8 @@ public final class GalaxyRepositoryClient implements AutoCloseable {
      * @return a connected client
      */
     public static GalaxyRepositoryClient connect(MxGatewayClientOptions options) {
-        return new GalaxyRepositoryClient(createChannel(options), options);
+        return new GalaxyRepositoryClient(
+                MxGatewayChannels.createChannel(options, "failed to configure galaxy repository TLS"), options);
     }
 
     /**
@@ -87,7 +82,7 @@ public final class GalaxyRepositoryClient implements AutoCloseable {
      * @return the blocking stub
      */
     public GalaxyRepositoryGrpc.GalaxyRepositoryBlockingStub rawBlockingStub() {
-        return withDeadline(blockingStub);
+        return MxGatewayChannels.withDeadline(blockingStub, options);
     }
 
     /**
@@ -96,7 +91,7 @@ public final class GalaxyRepositoryClient implements AutoCloseable {
      * @return the future stub
      */
     public GalaxyRepositoryGrpc.GalaxyRepositoryFutureStub rawFutureStub() {
-        return withDeadline(futureStub);
+        return MxGatewayChannels.withDeadline(futureStub, options);
     }
 
     /**
@@ -133,7 +128,9 @@ public final class GalaxyRepositoryClient implements AutoCloseable {
      *         exceptionally with {@link MxGatewayException} on failure
      */
     public CompletableFuture<Boolean> testConnectionAsync() {
-        return toCompletable(rawFutureStub().testConnection(TestConnectionRequest.getDefaultInstance()))
+        return MxGatewayChannels.toCompletable(
+                        rawFutureStub().testConnection(TestConnectionRequest.getDefaultInstance()),
+                        "galaxy test connection")
                 .thenApply(TestConnectionReply::getOk);
     }
 
@@ -165,8 +162,11 @@ public final class GalaxyRepositoryClient implements AutoCloseable {
      *         completed exceptionally with {@link MxGatewayException} on failure
      */
     public CompletableFuture<Optional<Instant>> getLastDeployTimeAsync() {
-        return toCompletable(rawFutureStub().getLastDeployTime(GetLastDeployTimeRequest.getDefaultInstance()))
+        return MxGatewayChannels.toCompletable(
-                .thenApply(GalaxyRepositoryClient::mapDeployTime);
+                        rawFutureStub().getLastDeployTime(GetLastDeployTimeRequest.getDefaultInstance()),
+                        "galaxy get last deploy time")
+                .thenApply(MxGatewayChannels.normalisingValidator(
+                        "galaxy get last deploy time", GalaxyRepositoryClient::mapDeployTime));
     }
 
     /**
@@ -224,7 +224,8 @@ public final class GalaxyRepositoryClient implements AutoCloseable {
      */
     public DeployEventStream watchDeployEvents(Instant lastSeenDeployTime) {
         DeployEventStream stream = new DeployEventStream(16);
-        withStreamDeadline(rawAsyncStub()).watchDeployEvents(buildWatchRequest(lastSeenDeployTime), stream.observer());
+        MxGatewayChannels.withStreamDeadline(rawAsyncStub(), options)
+                .watchDeployEvents(buildWatchRequest(lastSeenDeployTime), stream.observer());
         return stream;
     }
 
@@ -253,7 +254,7 @@ public final class GalaxyRepositoryClient implements AutoCloseable {
             Instant lastSeenDeployTime, StreamObserver<DeployEvent> observer) {
         Objects.requireNonNull(observer, "observer");
         DeployEventSubscription subscription = new DeployEventSubscription();
-        withStreamDeadline(rawAsyncStub())
+        MxGatewayChannels.withStreamDeadline(rawAsyncStub(), options)
                 .watchDeployEvents(buildWatchRequest(lastSeenDeployTime), subscription.wrap(observer));
         return subscription;
     }
@@ -269,17 +270,31 @@ public final class GalaxyRepositoryClient implements AutoCloseable {
         return builder.build();
     }
 
-    private <T extends io.grpc.stub.AbstractStub<T>> T withStreamDeadline(T stub) {
+    /**
-        if (options.streamTimeout() == null || options.streamTimeout().isNegative()) {
+     * Shuts the owned channel down and awaits termination so try-with-resources
-            return stub;
+     * callers do not leave in-flight calls or Netty event-loop threads running
-        }
+     * after the block exits.
-        return stub.withDeadlineAfter(options.streamTimeout().toNanos(), TimeUnit.NANOSECONDS);
+     *
-    }
+     * <p>Waits up to the configured connect timeout for graceful termination
-
+     * and forcibly shuts the channel down on timeout. If the calling thread is
+     * interrupted while waiting, the channel is forcibly shut down and the
+     * thread's interrupt flag is restored. No-op for clients that do not own
+     * their channel. For an explicitly checked, blocking-aware shutdown call
+     * {@link #closeAndAwaitTermination()}.
+     */
     @Override
     public void close() {
-        if (ownedChannel != null) {
+        if (ownedChannel == null) {
-            ownedChannel.shutdown();
+            return;
+        }
+        ownedChannel.shutdown();
+        try {
+            if (!ownedChannel.awaitTermination(options.connectTimeout().toMillis(), TimeUnit.MILLISECONDS)) {
+                ownedChannel.shutdownNow();
+            }
+        } catch (InterruptedException error) {
+            ownedChannel.shutdownNow();
+            Thread.currentThread().interrupt();
         }
     }
 
@@ -307,86 +322,26 @@ public final class GalaxyRepositoryClient implements AutoCloseable {
         return Optional.of(Instant.ofEpochSecond(ts.getSeconds(), ts.getNanos()));
     }
 
-    private static ManagedChannel createChannel(MxGatewayClientOptions options) {
-        NettyChannelBuilder builder = NettyChannelBuilder.forTarget(options.endpoint())
-                .maxInboundMessageSize(options.maxGrpcMessageBytes());
-        if (!options.connectTimeout().isNegative()) {
-            builder.withOption(
-                    io.grpc.netty.shaded.io.netty.channel.ChannelOption.CONNECT_TIMEOUT_MILLIS,
-                    Math.toIntExact(options.connectTimeout().toMillis()));
-        }
-        if (options.plaintext()) {
-            builder.usePlaintext();
-        } else if (options.caCertificatePath() != null) {
-            try {
-                builder.sslContext(GrpcSslContexts.forClient()
-                        .trustManager(options.caCertificatePath().toFile())
-                        .build());
-            } catch (SSLException error) {
-                throw new MxGatewayException("failed to configure galaxy repository TLS", error);
-            }
-        } else {
-            builder.useTransportSecurity();
-        }
-        if (!options.serverNameOverride().isBlank()) {
-            builder.overrideAuthority(options.serverNameOverride());
-        }
-        return builder.build();
-    }
-
-    private <T extends io.grpc.stub.AbstractStub<T>> T withDeadline(T stub) {
-        if (options.callTimeout().isNegative()) {
-            return stub;
-        }
-        return stub.withDeadlineAfter(options.callTimeout().toNanos(), TimeUnit.NANOSECONDS);
-    }
-
     private CompletableFuture<List<GalaxyObject>> discoverHierarchyPageAsync(
             String pageToken, java.util.ArrayList<GalaxyObject> objects, java.util.HashSet<String> seenPageTokens) {
         DiscoverHierarchyRequest request = DiscoverHierarchyRequest.newBuilder()
                 .setPageSize(DISCOVER_HIERARCHY_PAGE_SIZE)
                 .setPageToken(pageToken)
                 .build();
-        return toCompletable(rawFutureStub().discoverHierarchy(request)).thenCompose(reply -> {
+        return MxGatewayChannels.toCompletable(rawFutureStub().discoverHierarchy(request), "galaxy discover hierarchy")
-            objects.addAll(reply.getObjectsList());
+                .thenCompose(reply -> {
-            if (reply.getNextPageToken().isBlank()) {
+                    objects.addAll(reply.getObjectsList());
-                return CompletableFuture.completedFuture(objects);
+                    if (reply.getNextPageToken().isBlank()) {
-            }
+                        return CompletableFuture.completedFuture(objects);
-            if (!seenPageTokens.add(reply.getNextPageToken())) {
-                CompletableFuture<List<GalaxyObject>> failed = new CompletableFuture<>();
-                failed.completeExceptionally(new MxGatewayException(
-                        "galaxy discover hierarchy returned repeated page token: " + reply.getNextPageToken()));
-                return failed;
-            }
-            return discoverHierarchyPageAsync(reply.getNextPageToken(), objects, seenPageTokens);
-        });
-    }
-
-    private static <T> CompletableFuture<T> toCompletable(com.google.common.util.concurrent.ListenableFuture<T> source) {
-        CompletableFuture<T> target = new CompletableFuture<>();
-        Futures.addCallback(
-                source,
-                new FutureCallback<>() {
-                    @Override
-                    public void onSuccess(T result) {
-                        target.complete(result);
                     }
-
+                    if (!seenPageTokens.add(reply.getNextPageToken())) {
-                    @Override
+                        CompletableFuture<List<GalaxyObject>> failed = new CompletableFuture<>();
-                    public void onFailure(Throwable error) {
+                        failed.completeExceptionally(new MxGatewayException(
-                        if (error instanceof RuntimeException runtimeException) {
+                                "galaxy discover hierarchy returned repeated page token: "
-                            target.completeExceptionally(MxGatewayErrors.fromGrpc("galaxy async call", runtimeException));
+                                        + reply.getNextPageToken()));
-                            return;
+                        return failed;
-                        }
-                        target.completeExceptionally(error);
                     }
-                },
+                    return discoverHierarchyPageAsync(reply.getNextPageToken(), objects, seenPageTokens);
-                MoreExecutors.directExecutor());
+                });
-        target.whenComplete((ignoredResult, ignoredError) -> {
-            if (target.isCancelled()) {
-                source.cancel(true);
-            }
-        });
-        return target;
     }
 }

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxAccessException.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 import mxaccess_gateway.v1.MxaccessGateway.MxCommandReply;
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxEventStream.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 import io.grpc.Status;
 import io.grpc.StatusRuntimeException;
@@ -21,13 +21,35 @@ import mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest;
  * stream cancels the underlying gRPC call. If the queue overflows the call is
  * cancelled and a follow-up call to {@link #next()} throws
  * {@link MxGatewayException}.
+ *
+ * <p><strong>Backpressure (fail-fast):</strong> this adaptor relies on gRPC's
+ * default auto-inbound flow control — the async stub auto-requests messages, so
+ * the gateway can push events faster than the consumer drains the bounded
+ * 16-element buffer. There is intentionally <em>no</em> real client flow
+ * control: a consumer that stalls long enough to let the buffer fill triggers
+ * an immediate overflow that cancels the subscription and surfaces an
+ * {@link MxGatewayException} on the next {@link #next()} call. This matches the
+ * gateway's documented fail-fast event-backpressure design — a slow consumer
+ * loses its subscription rather than silently dropping events. Consumers that
+ * cannot keep up must drain {@link #next()} promptly (e.g. hand events to their
+ * own larger queue) and be prepared to resubscribe with a resume cursor.
+ *
+ * <p><strong>Threading:</strong> the iterator methods ({@link #hasNext()} and
+ * {@link #next()}) are <em>not</em> thread-safe and must be driven by a single
+ * consumer thread. {@link #close()} may be called from any thread. Terminal
+ * state transitions (queue overflow, server completion, and {@code close()})
+ * are serialised so that the first terminal condition wins deterministically:
+ * once an overflow exception has been observed it is never silently replaced
+ * by an end-of-stream marker.
  */
 public final class MxEventStream implements Iterator<MxEvent>, AutoCloseable {
     private static final Object END = new Object();
 
     private final BlockingQueue<Object> queue;
+    private final Object terminalLock = new Object();
     private volatile ClientCallStreamObserver<StreamEventsRequest> requestStream;
     private volatile boolean closed;
+    private boolean terminated;
     private Object next;
 
     MxEventStream(int capacity) {
@@ -98,7 +120,7 @@ public final class MxEventStream implements Iterator<MxEvent>, AutoCloseable {
         if (stream != null) {
             stream.cancel("client cancelled event stream", null);
         }
-        offer(END);
+        terminate(null);
     }
 
     private Object take() {
@@ -115,10 +137,7 @@ public final class MxEventStream implements Iterator<MxEvent>, AutoCloseable {
     private void offer(Object value) {
         Objects.requireNonNull(value, "value");
         if (value == END) {
-            if (!queue.offer(value)) {
+            terminate(null);
-                queue.clear();
-                queue.offer(value);
-            }
             return;
         }
         if (!queue.offer(value)) {
@@ -126,9 +145,38 @@ public final class MxEventStream implements Iterator<MxEvent>, AutoCloseable {
             if (stream != null) {
                 stream.cancel("client event stream queue overflowed", null);
             }
-            queue.clear();
+            terminate(new MxGatewayException("gateway stream events queue overflowed"));
-            queue.offer(new MxGatewayException("gateway stream events queue overflowed"));
+        }
-            queue.offer(END);
+    }
+
+    /**
+     * Drives the single terminal transition. The first caller wins: a later
+     * end-of-stream or {@code close()} cannot overwrite or discard an overflow
+     * exception that has already been published to the consumer.
+     *
+     * @param fault the fault to surface to the consumer, or {@code null} for a
+     *     clean end-of-stream
+     */
+    private void terminate(MxGatewayException fault) {
+        synchronized (terminalLock) {
+            if (terminated) {
+                return;
+            }
+            terminated = true;
+            if (fault != null) {
+                // Make room for the fault marker; the consumer only needs the
+                // terminal signal, queued data events are no longer relevant.
+                queue.clear();
+                queue.offer(fault);
+                queue.offer(END);
+                return;
+            }
+            // Clean end-of-stream: ensure the END marker is delivered even when
+            // the queue is currently full of undrained data events.
+            if (!queue.offer(END)) {
+                queue.clear();
+                queue.offer(END);
+            }
         }
     }
 }

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayActiveAlarmsSubscription.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 import io.grpc.stub.ClientCallStreamObserver;
 import io.grpc.stub.ClientResponseObserver;

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayAuthInterceptor.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 import io.grpc.CallOptions;
 import io.grpc.Channel;

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayAuthenticationException.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 /**
  * Thrown when the gateway rejects a call because the supplied API key is

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayAuthorizationException.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 /**
  * Thrown when the gateway accepts an API key but rejects a call because the

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayChannels.java

@@ -0,0 +1,164 @@
+package com.dohertylan.mxgateway.client;
+
+import com.google.common.util.concurrent.FutureCallback;
+import com.google.common.util.concurrent.Futures;
+import com.google.common.util.concurrent.ListenableFuture;
+import com.google.common.util.concurrent.MoreExecutors;
+import io.grpc.ManagedChannel;
+import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
+import io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder;
+import io.grpc.stub.AbstractStub;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.TimeUnit;
+import java.util.function.Function;
+import javax.net.ssl.SSLException;
+
+/**
+ * Shared channel-builder and future-adaptor helpers used by both
+ * {@link MxGatewayClient} and {@link GalaxyRepositoryClient}.
+ *
+ * <p>Extracted so transport construction, per-call deadlines, and the
+ * {@link ListenableFuture}-to-{@link CompletableFuture} bridge live in one
+ * place instead of being duplicated verbatim across the two clients.
+ */
+final class MxGatewayChannels {
+    private MxGatewayChannels() {
+    }
+
+    /**
+     * Builds a Netty managed channel from the supplied options, applying the
+     * connect timeout, message-size limit, and the configured transport
+     * security mode (plaintext, custom CA trust, or system trust).
+     *
+     * @param options the client options carrying endpoint and transport config
+     * @param tlsErrorPrefix a human-readable prefix for the {@link MxGatewayException}
+     *     thrown when a custom CA certificate cannot be loaded
+     * @return a new managed channel; the caller owns its lifecycle
+     */
+    static ManagedChannel createChannel(MxGatewayClientOptions options, String tlsErrorPrefix) {
+        NettyChannelBuilder builder = NettyChannelBuilder.forTarget(options.endpoint())
+                .maxInboundMessageSize(options.maxGrpcMessageBytes());
+        if (!options.connectTimeout().isNegative()) {
+            builder.withOption(
+                    io.grpc.netty.shaded.io.netty.channel.ChannelOption.CONNECT_TIMEOUT_MILLIS,
+                    Math.toIntExact(options.connectTimeout().toMillis()));
+        }
+        if (options.plaintext()) {
+            builder.usePlaintext();
+        } else if (options.caCertificatePath() != null) {
+            try {
+                builder.sslContext(GrpcSslContexts.forClient()
+                        .trustManager(options.caCertificatePath().toFile())
+                        .build());
+            } catch (SSLException | RuntimeException error) {
+                // SSLException covers handshake-context failures; RuntimeException
+                // (IllegalArgumentException wrapping CertificateException) covers a
+                // missing or unreadable CA file. Either way callers see one typed
+                // failure instead of a raw, unwrapped exception leaking out.
+                throw new MxGatewayException(tlsErrorPrefix, error);
+            }
+        } else {
+            builder.useTransportSecurity();
+        }
+        if (!options.serverNameOverride().isBlank()) {
+            builder.overrideAuthority(options.serverNameOverride());
+        }
+        return builder.build();
+    }
+
+    /**
+     * Applies the configured per-call deadline to a unary stub.
+     *
+     * @param stub the stub to decorate
+     * @param options the client options carrying the call timeout
+     * @param <T> the concrete stub type
+     * @return the stub with the call deadline applied, or the stub unchanged
+     *     when the call timeout is negative (disabled)
+     */
+    static <T extends AbstractStub<T>> T withDeadline(T stub, MxGatewayClientOptions options) {
+        if (options.callTimeout().isNegative()) {
+            return stub;
+        }
+        return stub.withDeadlineAfter(options.callTimeout().toNanos(), TimeUnit.NANOSECONDS);
+    }
+
+    /**
+     * Applies the configured streaming deadline to a streaming stub.
+     *
+     * @param stub the stub to decorate
+     * @param options the client options carrying the stream timeout
+     * @param <T> the concrete stub type
+     * @return the stub with the stream deadline applied, or the stub unchanged
+     *     when the stream timeout is unset or negative (disabled)
+     */
+    static <T extends AbstractStub<T>> T withStreamDeadline(T stub, MxGatewayClientOptions options) {
+        if (options.streamTimeout() == null || options.streamTimeout().isNegative()) {
+            return stub;
+        }
+        return stub.withDeadlineAfter(options.streamTimeout().toNanos(), TimeUnit.NANOSECONDS);
+    }
+
+    /**
+     * Bridges a Guava {@link ListenableFuture} to a {@link CompletableFuture},
+     * normalising any failure through {@link MxGatewayErrors#fromGrpc} so the
+     * async error surface matches the synchronous methods. Cancelling the
+     * returned future cancels the source RPC.
+     *
+     * @param source the gRPC future-stub result
+     * @param operation the operation name used in normalised error messages
+     * @param <T> the reply type
+     * @return a completable future mirroring the source
+     */
+    static <T> CompletableFuture<T> toCompletable(ListenableFuture<T> source, String operation) {
+        CompletableFuture<T> target = new CompletableFuture<>();
+        Futures.addCallback(
+                source,
+                new FutureCallback<>() {
+                    @Override
+                    public void onSuccess(T result) {
+                        target.complete(result);
+                    }
+
+                    @Override
+                    public void onFailure(Throwable error) {
+                        if (error instanceof RuntimeException runtimeException) {
+                            target.completeExceptionally(MxGatewayErrors.fromGrpc(operation, runtimeException));
+                            return;
+                        }
+                        target.completeExceptionally(error);
+                    }
+                },
+                MoreExecutors.directExecutor());
+        target.whenComplete((ignoredResult, ignoredError) -> {
+            if (target.isCancelled()) {
+                source.cancel(true);
+            }
+        });
+        return target;
+    }
+
+    /**
+     * Adapts a reply-validating function for use inside {@code thenApply} so
+     * any non-{@link MxGatewayException} {@link RuntimeException} it raises is
+     * routed through {@link MxGatewayErrors#fromGrpc}. This keeps the async
+     * error surface consistent with the synchronous methods, which normalise
+     * failures with a {@code try/catch}.
+     *
+     * @param operation the operation name used in normalised error messages
+     * @param validator the validating/transforming function applied to the reply
+     * @param <T> the reply type
+     * @param <R> the result type
+     * @return a function suitable for {@link CompletableFuture#thenApply}
+     */
+    static <T, R> Function<T, R> normalisingValidator(String operation, Function<T, R> validator) {
+        return reply -> {
+            try {
+                return validator.apply(reply);
+            } catch (MxGatewayException error) {
+                throw error;
+            } catch (RuntimeException error) {
+                throw MxGatewayErrors.fromGrpc(operation, error);
+            }
+        };
+    }
+}

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java

@@ -1,19 +1,13 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
-import com.google.common.util.concurrent.FutureCallback;
-import com.google.common.util.concurrent.Futures;
-import com.google.common.util.concurrent.MoreExecutors;
 import com.google.protobuf.Duration;
 import io.grpc.Channel;
 import io.grpc.ClientInterceptors;
 import io.grpc.ManagedChannel;
-import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
-import io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder;
 import io.grpc.stub.StreamObserver;
 import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.TimeUnit;
-import javax.net.ssl.SSLException;
 import mxaccess_gateway.v1.MxAccessGatewayGrpc;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest;
@@ -79,7 +73,8 @@ public final class MxGatewayClient implements AutoCloseable {
      * @return a connected client
      */
     public static MxGatewayClient connect(MxGatewayClientOptions options) {
-        return new MxGatewayClient(createChannel(options), options);
+        return new MxGatewayClient(
+                MxGatewayChannels.createChannel(options, "failed to configure gateway TLS"), options);
     }
 
     /**
@@ -88,7 +83,7 @@ public final class MxGatewayClient implements AutoCloseable {
      * @return the blocking stub
      */
     public MxAccessGatewayGrpc.MxAccessGatewayBlockingStub rawBlockingStub() {
-        return withDeadline(blockingStub);
+        return MxGatewayChannels.withDeadline(blockingStub, options);
     }
 
     /**
@@ -97,7 +92,7 @@ public final class MxGatewayClient implements AutoCloseable {
      * @return the future stub
      */
     public MxAccessGatewayGrpc.MxAccessGatewayFutureStub rawFutureStub() {
-        return withDeadline(futureStub);
+        return MxGatewayChannels.withDeadline(futureStub, options);
     }
 
     /**
@@ -150,6 +145,7 @@ public final class MxGatewayClient implements AutoCloseable {
         try {
             OpenSessionReply reply = rawBlockingStub().openSession(request);
             MxGatewayErrors.ensureProtocolSuccess("open session", reply.getProtocolStatus(), null);
+            ensureGatewayProtocolCompatible(reply);
             return reply;
         } catch (RuntimeException error) {
             if (error instanceof MxGatewayException) {
@@ -159,6 +155,24 @@ public final class MxGatewayClient implements AutoCloseable {
         }
     }
 
+    /**
+     * Verifies that the gateway speaks the protocol version this client was
+     * generated against. A gateway that leaves {@code gateway_protocol_version}
+     * unset (value {@code 0}, e.g. an older gateway) is accepted unchanged.
+     *
+     * @param reply the {@code OpenSessionReply} returned by the gateway
+     * @throws MxGatewayException if the gateway reports an incompatible protocol version
+     */
+    private static void ensureGatewayProtocolCompatible(OpenSessionReply reply) {
+        int gatewayVersion = reply.getGatewayProtocolVersion();
+        int clientVersion = MxGatewayClientVersion.gatewayProtocolVersion();
+        if (gatewayVersion != 0 && gatewayVersion != clientVersion) {
+            throw new MxGatewayException("gateway protocol version mismatch: gateway reports "
+                    + gatewayVersion + " but this client was built for " + clientVersion
+                    + "; upgrade the client or gateway so the protocol versions match");
+        }
+    }
+
     /**
      * Invokes {@code OpenSession} asynchronously.
      *
@@ -167,11 +181,13 @@ public final class MxGatewayClient implements AutoCloseable {
      *         with {@link MxGatewayException} on failure
      */
     public CompletableFuture<OpenSessionReply> openSessionAsync(OpenSessionRequest request) {
-        CompletableFuture<OpenSessionReply> future = toCompletable(rawFutureStub().openSession(request));
+        CompletableFuture<OpenSessionReply> future =
-        return future.thenApply(reply -> {
+                MxGatewayChannels.toCompletable(rawFutureStub().openSession(request), "open session");
+        return future.thenApply(MxGatewayChannels.normalisingValidator("open session", reply -> {
             MxGatewayErrors.ensureProtocolSuccess("open session", reply.getProtocolStatus(), null);
+            ensureGatewayProtocolCompatible(reply);
             return reply;
-        });
+        }));
     }
 
     /**
@@ -206,12 +222,13 @@ public final class MxGatewayClient implements AutoCloseable {
      *         on failure
      */
     public CompletableFuture<MxCommandReply> invokeAsync(MxCommandRequest request) {
-        CompletableFuture<MxCommandReply> future = toCompletable(rawFutureStub().invoke(request));
+        CompletableFuture<MxCommandReply> future =
-        return future.thenApply(reply -> {
+                MxGatewayChannels.toCompletable(rawFutureStub().invoke(request), "invoke");
+        return future.thenApply(MxGatewayChannels.normalisingValidator("invoke", reply -> {
             MxGatewayErrors.ensureProtocolSuccess("invoke", reply.getProtocolStatus(), reply);
             MxGatewayErrors.ensureMxAccessSuccess("invoke", reply);
             return reply;
-        });
+        }));
     }
 
     /**
@@ -244,7 +261,7 @@ public final class MxGatewayClient implements AutoCloseable {
      */
     public MxEventStream streamEvents(StreamEventsRequest request) {
         MxEventStream stream = new MxEventStream(16);
-        withStreamDeadline(rawAsyncStub()).streamEvents(request, stream.observer());
+        MxGatewayChannels.withStreamDeadline(rawAsyncStub(), options).streamEvents(request, stream.observer());
         return stream;
     }
 
@@ -259,15 +276,17 @@ public final class MxGatewayClient implements AutoCloseable {
     public MxGatewayEventSubscription streamEventsAsync(
             StreamEventsRequest request, StreamObserver<MxEvent> observer) {
         MxGatewayEventSubscription subscription = new MxGatewayEventSubscription();
-        withStreamDeadline(rawAsyncStub()).streamEvents(request, subscription.wrap(observer));
+        MxGatewayChannels.withStreamDeadline(rawAsyncStub(), options)
+                .streamEvents(request, subscription.wrap(observer));
         return subscription;
     }
 
     /**
      * Acknowledges an active MXAccess alarm condition through the gateway.
      *
-     * <p>The gateway authenticates the request against the API key's
+     * <p>The gateway authorizes this request against the API key's
-     * {@code invoke:alarm-ack} scope and forwards the acknowledge to the
+     * {@code admin} scope (the gateway scope resolver maps alarm RPCs to the
+     * default {@code admin} scope) and forwards the acknowledge to the
      * worker's MXAccess session; the resulting native MxStatus is returned
      * in the reply. Acks are idempotent at the MxAccess layer.
      *
@@ -296,11 +315,12 @@ public final class MxGatewayClient implements AutoCloseable {
      *         with {@link MxGatewayException} on failure
      */
     public CompletableFuture<AcknowledgeAlarmReply> acknowledgeAlarmAsync(AcknowledgeAlarmRequest request) {
-        CompletableFuture<AcknowledgeAlarmReply> future = toCompletable(rawFutureStub().acknowledgeAlarm(request));
+        CompletableFuture<AcknowledgeAlarmReply> future =
-        return future.thenApply(reply -> {
+                MxGatewayChannels.toCompletable(rawFutureStub().acknowledgeAlarm(request), "acknowledge alarm");
+        return future.thenApply(MxGatewayChannels.normalisingValidator("acknowledge alarm", reply -> {
             MxGatewayErrors.ensureProtocolSuccess("acknowledge alarm", reply.getProtocolStatus(), null);
             return reply;
-        });
+        }));
     }
 
     /**
@@ -316,14 +336,36 @@ public final class MxGatewayClient implements AutoCloseable {
     public MxGatewayActiveAlarmsSubscription queryActiveAlarms(
             QueryActiveAlarmsRequest request, StreamObserver<ActiveAlarmSnapshot> observer) {
         MxGatewayActiveAlarmsSubscription subscription = new MxGatewayActiveAlarmsSubscription();
-        withStreamDeadline(rawAsyncStub()).queryActiveAlarms(request, subscription.wrap(observer));
+        MxGatewayChannels.withStreamDeadline(rawAsyncStub(), options)
+                .queryActiveAlarms(request, subscription.wrap(observer));
         return subscription;
     }
 
+    /**
+     * Shuts the owned channel down and awaits termination so try-with-resources
+     * callers do not leave in-flight calls or Netty event-loop threads running
+     * after the block exits.
+     *
+     * <p>Waits up to the configured connect timeout for graceful termination
+     * and forcibly shuts the channel down on timeout. If the calling thread is
+     * interrupted while waiting, the channel is forcibly shut down and the
+     * thread's interrupt flag is restored. No-op for clients that do not own
+     * their channel. For an explicitly checked, blocking-aware shutdown call
+     * {@link #closeAndAwaitTermination()}.
+     */
     @Override
     public void close() {
-        if (ownedChannel != null) {
+        if (ownedChannel == null) {
-            ownedChannel.shutdown();
+            return;
+        }
+        ownedChannel.shutdown();
+        try {
+            if (!ownedChannel.awaitTermination(options.connectTimeout().toMillis(), TimeUnit.MILLISECONDS)) {
+                ownedChannel.shutdownNow();
+            }
+        } catch (InterruptedException error) {
+            ownedChannel.shutdownNow();
+            Thread.currentThread().interrupt();
         }
     }
 
@@ -343,75 +385,6 @@ public final class MxGatewayClient implements AutoCloseable {
         }
     }
 
-    private static ManagedChannel createChannel(MxGatewayClientOptions options) {
-        NettyChannelBuilder builder = NettyChannelBuilder.forTarget(options.endpoint())
-                .maxInboundMessageSize(options.maxGrpcMessageBytes());
-        if (!options.connectTimeout().isNegative()) {
-            builder.withOption(
-                    io.grpc.netty.shaded.io.netty.channel.ChannelOption.CONNECT_TIMEOUT_MILLIS,
-                    Math.toIntExact(options.connectTimeout().toMillis()));
-        }
-        if (options.plaintext()) {
-            builder.usePlaintext();
-        } else if (options.caCertificatePath() != null) {
-            try {
-                builder.sslContext(GrpcSslContexts.forClient()
-                        .trustManager(options.caCertificatePath().toFile())
-                        .build());
-            } catch (SSLException error) {
-                throw new MxGatewayException("failed to configure gateway TLS", error);
-            }
-        } else {
-            builder.useTransportSecurity();
-        }
-        if (!options.serverNameOverride().isBlank()) {
-            builder.overrideAuthority(options.serverNameOverride());
-        }
-        return builder.build();
-    }
-
-    private <T extends io.grpc.stub.AbstractStub<T>> T withDeadline(T stub) {
-        if (options.callTimeout().isNegative()) {
-            return stub;
-        }
-        return stub.withDeadlineAfter(options.callTimeout().toNanos(), TimeUnit.NANOSECONDS);
-    }
-
-    private <T extends io.grpc.stub.AbstractStub<T>> T withStreamDeadline(T stub) {
-        if (options.streamTimeout() == null || options.streamTimeout().isNegative()) {
-            return stub;
-        }
-        return stub.withDeadlineAfter(options.streamTimeout().toNanos(), TimeUnit.NANOSECONDS);
-    }
-
-    private static <T> CompletableFuture<T> toCompletable(com.google.common.util.concurrent.ListenableFuture<T> source) {
-        CompletableFuture<T> target = new CompletableFuture<>();
-        Futures.addCallback(
-                source,
-                new FutureCallback<>() {
-                    @Override
-                    public void onSuccess(T result) {
-                        target.complete(result);
-                    }
-
-                    @Override
-                    public void onFailure(Throwable error) {
-                        if (error instanceof RuntimeException runtimeException) {
-                            target.completeExceptionally(MxGatewayErrors.fromGrpc("async call", runtimeException));
-                            return;
-                        }
-                        target.completeExceptionally(error);
-                    }
-                },
-                MoreExecutors.directExecutor());
-        target.whenComplete((ignoredResult, ignoredError) -> {
-            if (target.isCancelled()) {
-                source.cancel(true);
-            }
-        });
-        return target;
-    }
-
     static ProtocolStatusCode okStatusCode() {
         return ProtocolStatusCode.PROTOCOL_STATUS_CODE_OK;
     }

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClientOptions.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 import java.nio.file.Path;
 import java.time.Duration;

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClientVersion.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 /**
  * Reports the client and protocol version numbers compiled into this build.

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayCommandException.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 import mxaccess_gateway.v1.MxaccessGateway.MxCommandReply;
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayErrors.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 import io.grpc.Status;
 import io.grpc.StatusRuntimeException;

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayEventSubscription.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 import io.grpc.stub.ClientCallStreamObserver;
 import io.grpc.stub.ClientResponseObserver;

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayException.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 /**
  * Base unchecked exception thrown by the MXAccess Gateway Java client.

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewaySecrets.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 /**
  * Helpers for redacting secrets such as gateway API keys from log output.
@@ -11,25 +11,35 @@ public final class MxGatewaySecrets {
     }
 
     /**
-     * Redacts the body of an API key, leaving only short prefix and suffix
+     * Redacts the secret portion of an API key, leaving only the non-secret
-     * windows so it remains comparable in logs.
+     * key identifier visible so the value remains comparable in logs.
+     *
+     * <p>A gateway API key has the form {@code mxgw_<key-id>_<secret>}. Only the
+     * {@code mxgw_<key-id>_} prefix is non-secret; everything after the second
+     * underscore is the secret and is masked entirely &mdash; no leading or
+     * trailing characters of the secret are echoed. Tokens that do not match
+     * the gateway shape are masked completely as {@code "<redacted>"}.
      *
      * @param apiKey the API key to redact, may be {@code null} or empty
      * @return an empty string for {@code null}/empty input, {@code "<redacted>"}
-     *         for keys eight characters or shorter, or a masked form preserving
+     *         for non-gateway-shaped tokens, or {@code mxgw_<key-id>_***} with the
-     *         the leading and trailing four characters
+     *         secret masked for gateway-shaped keys
      */
     public static String redactApiKey(String apiKey) {
         if (apiKey == null || apiKey.isEmpty()) {
             return "";
         }
-        if (apiKey.length() <= 8) {
+
-            return "<redacted>";
+        // Gateway keys are mxgw_<key-id>_<secret>; keep only the non-secret prefix.
+        if (apiKey.startsWith("mxgw_")) {
+            int secretSeparator = apiKey.indexOf('_', "mxgw_".length());
+            if (secretSeparator >= 0 && secretSeparator < apiKey.length() - 1) {
+                return apiKey.substring(0, secretSeparator + 1) + "***";
+            }
         }
 
-        return apiKey.substring(0, 4)
+        // Anything else is treated as wholly secret — reveal nothing.
-                + "*".repeat(apiKey.length() - 8)
+        return "<redacted>";
-                + apiKey.substring(apiKey.length() - 4);
     }
 
     /**

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewaySession.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 import java.security.SecureRandom;
 import java.util.HexFormat;
@@ -40,6 +40,7 @@ import mxaccess_gateway.v1.MxaccessGateway.WriteCommand;
  */
 public final class MxGatewaySession implements AutoCloseable {
     private static final SecureRandom RANDOM = new SecureRandom();
+    private static final System.Logger LOGGER = System.getLogger(MxGatewaySession.class.getName());
 
     private final MxGatewayClient client;
     private final OpenSessionReply openReply;
@@ -99,9 +100,26 @@ public final class MxGatewaySession implements AutoCloseable {
         return closeReply;
     }
 
+    /**
+     * Closes the session as part of try-with-resources.
+     *
+     * <p>This performs a {@code CloseSession} network RPC. Unlike
+     * {@link #closeRaw()}, any failure of that RPC is swallowed (and recorded
+     * as a suppressed exception when the JVM permits) rather than thrown: a
+     * close-time transport or protocol failure must not replace the exception
+     * that a try-with-resources body is already propagating. Callers that need
+     * to observe the close result should call {@link #closeRaw()} explicitly.
+     */
     @Override
     public void close() {
-        closeRaw();
+        try {
+            closeRaw();
+        } catch (MxGatewayException error) {
+            LOGGER.log(
+                    System.Logger.Level.WARNING,
+                    () -> "ignoring close-time failure for session " + sessionId(),
+                    error);
+        }
     }
 
     /**
@@ -116,7 +134,11 @@ public final class MxGatewaySession implements AutoCloseable {
         if (reply.hasRegister()) {
             return reply.getRegister().getServerHandle();
         }
-        return reply.getReturnValue().getInt32Value();
+        if (reply.hasReturnValue()) {
+            return reply.getReturnValue().getInt32Value();
+        }
+        throw new MxGatewayException(
+                "gateway register reply carried neither a register payload nor a return value");
     }
 
     /**
@@ -159,7 +181,11 @@ public final class MxGatewaySession implements AutoCloseable {
         if (reply.hasAddItem()) {
             return reply.getAddItem().getItemHandle();
         }
-        return reply.getReturnValue().getInt32Value();
+        if (reply.hasReturnValue()) {
+            return reply.getReturnValue().getInt32Value();
+        }
+        throw new MxGatewayException(
+                "gateway addItem reply carried neither an add-item payload nor a return value");
     }
 
     /**
@@ -193,7 +219,11 @@ public final class MxGatewaySession implements AutoCloseable {
         if (reply.hasAddItem2()) {
             return reply.getAddItem2().getItemHandle();
         }
-        return reply.getReturnValue().getInt32Value();
+        if (reply.hasReturnValue()) {
+            return reply.getReturnValue().getInt32Value();
+        }
+        throw new MxGatewayException(
+                "gateway addItem2 reply carried neither an add-item payload nor a return value");
     }
 
     /**

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewaySessionException.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
 

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayWorkerException.java

@@ -1,4 +1,4 @@
-package com.zb.mom.ww.mxgateway.client;
+package com.dohertylan.mxgateway.client;
 
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;