Fix Galaxy projection and constraint review findings

Issue #50: document client packaging

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

@@ -1,4 +1,5 @@
 using MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto.Galaxy;
 
 namespace MxGateway.Client.Cli;
 
@@ -19,4 +20,20 @@ public interface IMxGatewayCliClient : IAsyncDisposable
     IAsyncEnumerable<MxEvent> StreamEventsAsync(
         StreamEventsRequest request,
         CancellationToken cancellationToken);
+
+    Task<TestConnectionReply> GalaxyTestConnectionAsync(
+        TestConnectionRequest request,
+        CancellationToken cancellationToken);
+
+    Task<GetLastDeployTimeReply> GalaxyGetLastDeployTimeAsync(
+        GetLastDeployTimeRequest request,
+        CancellationToken cancellationToken);
+
+    Task<DiscoverHierarchyReply> GalaxyDiscoverHierarchyAsync(
+        DiscoverHierarchyRequest request,
+        CancellationToken cancellationToken);
+
+    IAsyncEnumerable<DeployEvent> GalaxyWatchDeployEventsAsync(
+        WatchDeployEventsRequest request,
+        CancellationToken cancellationToken);
 }

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

@@ -1,40 +1,84 @@
 using MxGateway.Client;
 using MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto.Galaxy;
 
 namespace MxGateway.Client.Cli;
 
-internal sealed class MxGatewayCliClientAdapter(MxGatewayClient client) : IMxGatewayCliClient
+internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
 {
+    private readonly MxGatewayClient _client;
+    private readonly Lazy<GalaxyRepositoryClient> _galaxyClient;
+
+    public MxGatewayCliClientAdapter(MxGatewayClient client)
+    {
+        _client = client;
+        _galaxyClient = new Lazy<GalaxyRepositoryClient>(
+            () => GalaxyRepositoryClient.Create(_client.Options));
+    }
+
     public Task<OpenSessionReply> OpenSessionAsync(
         OpenSessionRequest request,
         CancellationToken cancellationToken)
     {
-        return client.OpenSessionRawAsync(request, cancellationToken);
+        return _client.OpenSessionRawAsync(request, cancellationToken);
     }
 
     public Task<CloseSessionReply> CloseSessionAsync(
         CloseSessionRequest request,
         CancellationToken cancellationToken)
     {
-        return client.CloseSessionRawAsync(request, cancellationToken);
+        return _client.CloseSessionRawAsync(request, cancellationToken);
     }
 
     public Task<MxCommandReply> InvokeAsync(
         MxCommandRequest request,
         CancellationToken cancellationToken)
     {
-        return client.InvokeAsync(request, cancellationToken);
+        return _client.InvokeAsync(request, cancellationToken);
     }
 
     public IAsyncEnumerable<MxEvent> StreamEventsAsync(
         StreamEventsRequest request,
         CancellationToken cancellationToken)
     {
-        return client.StreamEventsAsync(request, cancellationToken);
+        return _client.StreamEventsAsync(request, cancellationToken);
     }
 
-    public ValueTask DisposeAsync()
+    public Task<TestConnectionReply> GalaxyTestConnectionAsync(
+        TestConnectionRequest request,
+        CancellationToken cancellationToken)
     {
-        return client.DisposeAsync();
+        return _galaxyClient.Value.TestConnectionRawAsync(request, cancellationToken);
+    }
+
+    public Task<GetLastDeployTimeReply> GalaxyGetLastDeployTimeAsync(
+        GetLastDeployTimeRequest request,
+        CancellationToken cancellationToken)
+    {
+        return _galaxyClient.Value.GetLastDeployTimeRawAsync(request, cancellationToken);
+    }
+
+    public Task<DiscoverHierarchyReply> GalaxyDiscoverHierarchyAsync(
+        DiscoverHierarchyRequest request,
+        CancellationToken cancellationToken)
+    {
+        return _galaxyClient.Value.DiscoverHierarchyRawAsync(request, cancellationToken);
+    }
+
+    public IAsyncEnumerable<DeployEvent> GalaxyWatchDeployEventsAsync(
+        WatchDeployEventsRequest request,
+        CancellationToken cancellationToken)
+    {
+        return _galaxyClient.Value.WatchDeployEventsRawAsync(request, cancellationToken);
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        if (_galaxyClient.IsValueCreated)
+        {
+            await _galaxyClient.Value.DisposeAsync().ConfigureAwait(false);
+        }
+
+        await _client.DisposeAsync().ConfigureAwait(false);
     }
 }

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

@@ -3,11 +3,14 @@ using System.Text.Json;
 using Google.Protobuf;
 using MxGateway.Client;
 using MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto.Galaxy;
 
 namespace MxGateway.Client.Cli;
 
 public static class MxGatewayClientCli
 {
+    private const uint MaxAggregateEvents = 10_000;
+
     private static readonly JsonFormatter ProtobufJsonFormatter = JsonFormatter.Default;
 
     private static readonly JsonSerializerOptions JsonOptions = new(JsonSerializerDefaults.Web);
@@ -68,7 +71,7 @@ public static class MxGatewayClientCli
             }
 
             await using IMxGatewayCliClient client = clientFactory(CreateOptions(arguments));
-            using CancellationTokenSource cancellation = CreateCancellation(arguments);
+            using CancellationTokenSource cancellation = CreateCancellation(arguments, command);
 
             return command switch
             {
@@ -84,6 +87,10 @@ public static class MxGatewayClientCli
                     .ConfigureAwait(false),
                 "advise" => await AdviseAsync(arguments, client, standardOutput, cancellation.Token)
                     .ConfigureAwait(false),
+                "subscribe-bulk" => await SubscribeBulkAsync(arguments, client, standardOutput, cancellation.Token)
+                    .ConfigureAwait(false),
+                "unsubscribe-bulk" => await UnsubscribeBulkAsync(arguments, client, standardOutput, cancellation.Token)
+                    .ConfigureAwait(false),
                 "stream-events" => await StreamEventsAsync(arguments, client, standardOutput, cancellation.Token)
                     .ConfigureAwait(false),
                 "write" => await WriteAsync(arguments, client, standardOutput, cancellation.Token)
@@ -92,6 +99,14 @@ public static class MxGatewayClientCli
                     .ConfigureAwait(false),
                 "smoke" => await SmokeAsync(arguments, client, standardOutput, cancellation.Token)
                     .ConfigureAwait(false),
+                "galaxy-test-connection" => await GalaxyTestConnectionAsync(arguments, client, standardOutput, cancellation.Token)
+                    .ConfigureAwait(false),
+                "galaxy-last-deploy" => await GalaxyLastDeployAsync(arguments, client, standardOutput, cancellation.Token)
+                    .ConfigureAwait(false),
+                "galaxy-discover" => await GalaxyDiscoverAsync(arguments, client, standardOutput, cancellation.Token)
+                    .ConfigureAwait(false),
+                "galaxy-watch" => await GalaxyWatchAsync(arguments, client, standardOutput, cancellation.Token)
+                    .ConfigureAwait(false),
                 _ => WriteUnknownCommand(command, standardError),
             };
         }
@@ -162,9 +177,18 @@ public static class MxGatewayClientCli
             $"Gateway API key is required. Pass --api-key or set {apiKeyEnvironmentName}.");
     }
 
-    private static CancellationTokenSource CreateCancellation(CliArguments arguments)
+    private static CancellationTokenSource CreateCancellation(CliArguments arguments, string command)
     {
         var cancellation = new CancellationTokenSource();
+        // Long-running streaming commands run until Ctrl+C / cancellation by default;
+        // a caller-supplied --timeout still applies if present.
+        bool isLongRunning = command is "galaxy-watch";
+        string? rawTimeout = arguments.GetOptional("timeout");
+        if (isLongRunning && string.IsNullOrWhiteSpace(rawTimeout))
+        {
+            return cancellation;
+        }
+
         TimeSpan timeout = arguments.GetDuration("timeout", TimeSpan.FromSeconds(30));
         cancellation.CancelAfter(timeout);
         return cancellation;
@@ -287,6 +311,54 @@ public static class MxGatewayClientCli
             cancellationToken);
     }
 
+    private static Task<int> SubscribeBulkAsync(
+        CliArguments arguments,
+        IMxGatewayCliClient client,
+        TextWriter output,
+        CancellationToken cancellationToken)
+    {
+        SubscribeBulkCommand command = new()
+        {
+            ServerHandle = arguments.GetInt32("server-handle"),
+        };
+        command.TagAddresses.Add(ParseStringList(arguments.GetRequired("items")));
+
+        return InvokeAndWriteAsync(
+            arguments,
+            client,
+            output,
+            new MxCommand
+            {
+                Kind = MxCommandKind.SubscribeBulk,
+                SubscribeBulk = command,
+            },
+            cancellationToken);
+    }
+
+    private static Task<int> UnsubscribeBulkAsync(
+        CliArguments arguments,
+        IMxGatewayCliClient client,
+        TextWriter output,
+        CancellationToken cancellationToken)
+    {
+        UnsubscribeBulkCommand command = new()
+        {
+            ServerHandle = arguments.GetInt32("server-handle"),
+        };
+        command.ItemHandles.Add(ParseInt32List(arguments.GetRequired("item-handles")));
+
+        return InvokeAndWriteAsync(
+            arguments,
+            client,
+            output,
+            new MxCommand
+            {
+                Kind = MxCommandKind.UnsubscribeBulk,
+                UnsubscribeBulk = command,
+            },
+            cancellationToken);
+    }
+
     private static Task<int> WriteAsync(
         CliArguments arguments,
         IMxGatewayCliClient client,
@@ -342,8 +414,22 @@ public static class MxGatewayClientCli
         TextWriter output,
         CancellationToken cancellationToken)
     {
-        var events = new List<MxEvent>();
         uint maxEvents = arguments.GetUInt32("max-events", 0);
+        bool json = arguments.HasFlag("json");
+        bool jsonLines = arguments.HasFlag("jsonl");
+        if (json && !jsonLines && maxEvents is 0)
+        {
+            throw new ArgumentException("--json stream-events requires --max-events to bound aggregate output.");
+        }
+
+        if (maxEvents > MaxAggregateEvents)
+        {
+            throw new ArgumentException($"--max-events cannot exceed {MaxAggregateEvents}.");
+        }
+
+        var events = json && !jsonLines
+            ? new List<MxEvent>(checked((int)maxEvents))
+            : [];
         uint eventCount = 0;
         var request = new StreamEventsRequest
         {
@@ -355,7 +441,11 @@ public static class MxGatewayClientCli
             .WithCancellation(cancellationToken)
             .ConfigureAwait(false))
         {
-            if (arguments.HasFlag("json"))
+            if (jsonLines)
+            {
+                output.WriteLine(ProtobufJsonFormatter.Format(gatewayEvent));
+            }
+            else if (json)
             {
                 events.Add(gatewayEvent);
             }
@@ -371,7 +461,7 @@ public static class MxGatewayClientCli
             }
         }
 
-        if (arguments.HasFlag("json"))
+        if (json && !jsonLines)
         {
             output.WriteLine(JsonSerializer.Serialize(
                 new { events = events.Select(EventToJsonElement).ToArray() },
@@ -694,6 +784,177 @@ public static class MxGatewayClientCli
             .ToMxValue();
     }
 
+    private static Task<int> GalaxyTestConnectionAsync(
+        CliArguments arguments,
+        IMxGatewayCliClient client,
+        TextWriter output,
+        CancellationToken cancellationToken)
+    {
+        return WriteReplyAsync(
+            client.GalaxyTestConnectionAsync(new TestConnectionRequest(), cancellationToken),
+            arguments,
+            output);
+    }
+
+    private static Task<int> GalaxyLastDeployAsync(
+        CliArguments arguments,
+        IMxGatewayCliClient client,
+        TextWriter output,
+        CancellationToken cancellationToken)
+    {
+        return WriteReplyAsync(
+            client.GalaxyGetLastDeployTimeAsync(new GetLastDeployTimeRequest(), cancellationToken),
+            arguments,
+            output);
+    }
+
+    private static async Task<int> GalaxyDiscoverAsync(
+        CliArguments arguments,
+        IMxGatewayCliClient client,
+        TextWriter output,
+        CancellationToken cancellationToken)
+    {
+        DiscoverHierarchyReply reply = await DiscoverAllGalaxyHierarchyAsync(client, cancellationToken)
+            .ConfigureAwait(false);
+
+        if (arguments.HasFlag("json"))
+        {
+            output.WriteLine(ProtobufJsonFormatter.Format(reply));
+            return 0;
+        }
+
+        output.WriteLine($"objects={reply.Objects.Count}");
+        foreach (GalaxyObject galaxyObject in reply.Objects)
+        {
+            output.WriteLine($"- gobject_id={galaxyObject.GobjectId} tag_name={galaxyObject.TagName} contained_name={galaxyObject.ContainedName} parent={galaxyObject.ParentGobjectId} attributes={galaxyObject.Attributes.Count}");
+        }
+
+        return 0;
+    }
+
+    private static async Task<DiscoverHierarchyReply> DiscoverAllGalaxyHierarchyAsync(
+        IMxGatewayCliClient client,
+        CancellationToken cancellationToken)
+    {
+        DiscoverHierarchyReply aggregate = new();
+        HashSet<string> seenPageTokens = new(StringComparer.Ordinal);
+        string pageToken = string.Empty;
+        do
+        {
+            DiscoverHierarchyReply page = await client.GalaxyDiscoverHierarchyAsync(
+                    new DiscoverHierarchyRequest
+                    {
+                        PageSize = 5000,
+                        PageToken = pageToken,
+                    },
+                    cancellationToken)
+                .ConfigureAwait(false);
+
+            aggregate.Objects.Add(page.Objects);
+            aggregate.TotalObjectCount = page.TotalObjectCount;
+            pageToken = page.NextPageToken;
+            if (!string.IsNullOrWhiteSpace(pageToken)
+                && !seenPageTokens.Add(pageToken))
+            {
+                throw new MxGatewayException(
+                    $"Galaxy DiscoverHierarchy returned a repeated page token '{pageToken}'.");
+            }
+        }
+        while (!string.IsNullOrWhiteSpace(pageToken));
+
+        return aggregate;
+    }
+
+    private static async Task<int> GalaxyWatchAsync(
+        CliArguments arguments,
+        IMxGatewayCliClient client,
+        TextWriter output,
+        CancellationToken cancellationToken)
+    {
+        bool json = arguments.HasFlag("json");
+        uint maxEvents = arguments.GetUInt32("max-events", 0);
+        if (maxEvents > MaxAggregateEvents)
+        {
+            throw new ArgumentException($"--max-events cannot exceed {MaxAggregateEvents}.");
+        }
+
+        WatchDeployEventsRequest request = new();
+        string? lastSeen = arguments.GetOptional("last-seen-deploy-time");
+        if (!string.IsNullOrWhiteSpace(lastSeen))
+        {
+            DateTimeOffset parsed = DateTimeOffset.Parse(
+                lastSeen,
+                CultureInfo.InvariantCulture,
+                DateTimeStyles.AssumeUniversal | DateTimeStyles.AdjustToUniversal);
+            request.LastSeenDeployTime = Google.Protobuf.WellKnownTypes.Timestamp.FromDateTimeOffset(parsed);
+        }
+
+        using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+        ConsoleCancelEventHandler handler = (_, eventArgs) =>
+        {
+            eventArgs.Cancel = true;
+            try
+            {
+                linked.Cancel();
+            }
+            catch (ObjectDisposedException)
+            {
+            }
+        };
+        Console.CancelKeyPress += handler;
+
+        uint emitted = 0;
+        try
+        {
+            await foreach (DeployEvent deployEvent in client
+                .GalaxyWatchDeployEventsAsync(request, linked.Token)
+                .WithCancellation(linked.Token)
+                .ConfigureAwait(false))
+            {
+                if (json)
+                {
+                    output.WriteLine(ProtobufJsonFormatter.Format(deployEvent));
+                }
+                else
+                {
+                    output.WriteLine(FormatDeployEvent(deployEvent));
+                }
+
+                emitted++;
+                if (maxEvents > 0 && emitted >= maxEvents)
+                {
+                    break;
+                }
+            }
+        }
+        catch (OperationCanceledException) when (linked.IsCancellationRequested && !cancellationToken.IsCancellationRequested)
+        {
+            // Ctrl+C-driven cancellation is a clean exit.
+        }
+        finally
+        {
+            Console.CancelKeyPress -= handler;
+        }
+
+        return 0;
+    }
+
+    private static string FormatDeployEvent(DeployEvent deployEvent)
+    {
+        string deployTime = deployEvent.TimeOfLastDeployPresent && deployEvent.TimeOfLastDeploy is not null
+            ? deployEvent.TimeOfLastDeploy
+                .ToDateTimeOffset()
+                .ToString("O", CultureInfo.InvariantCulture)
+            : "<none>";
+        string observed = deployEvent.ObservedAt is not null
+            ? deployEvent.ObservedAt
+                .ToDateTimeOffset()
+                .ToString("O", CultureInfo.InvariantCulture)
+            : "<unknown>";
+
+        return $"sequence={deployEvent.Sequence} observed_at={observed} time_of_last_deploy={deployTime} objects={deployEvent.ObjectCount} attributes={deployEvent.AttributeCount}";
+    }
+
     private static int WriteUnknownCommand(string command, TextWriter standardError)
     {
         standardError.WriteLine($"Unknown command '{command}'.");
@@ -716,10 +977,42 @@ public static class MxGatewayClientCli
             or "register"
             or "add-item"
             or "advise"
+            or "subscribe-bulk"
+            or "unsubscribe-bulk"
             or "stream-events"
             or "write"
             or "write2"
-            or "smoke";
+            or "smoke"
+            or "galaxy-test-connection"
+            or "galaxy-last-deploy"
+            or "galaxy-discover"
+            or "galaxy-watch";
+    }
+
+    private static IReadOnlyList<string> ParseStringList(string value)
+    {
+        string[] items = value
+            .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (items.Length is 0)
+        {
+            throw new ArgumentException("At least one item is required.");
+        }
+
+        return items;
+    }
+
+    private static IReadOnlyList<int> ParseInt32List(string value)
+    {
+        string[] items = value
+            .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (items.Length is 0)
+        {
+            throw new ArgumentException("At least one item handle is required.");
+        }
+
+        return items
+            .Select(item => int.Parse(item, CultureInfo.InvariantCulture))
+            .ToArray();
     }
 
     private static string CreateCorrelationId()
@@ -736,9 +1029,15 @@ public static class MxGatewayClientCli
         writer.WriteLine("mxgw-dotnet register --session-id <id> --client-name <name> [--json]");
         writer.WriteLine("mxgw-dotnet add-item --session-id <id> --server-handle <n> --item <ref> [--json]");
         writer.WriteLine("mxgw-dotnet advise --session-id <id> --server-handle <n> --item-handle <n> [--json]");
+        writer.WriteLine("mxgw-dotnet subscribe-bulk --session-id <id> --server-handle <n> --items <ref,ref> [--json]");
+        writer.WriteLine("mxgw-dotnet unsubscribe-bulk --session-id <id> --server-handle <n> --item-handles <n,n> [--json]");
         writer.WriteLine("mxgw-dotnet stream-events --session-id <id> [--max-events <n>] [--json]");
         writer.WriteLine("mxgw-dotnet write --session-id <id> --server-handle <n> --item-handle <n> --type <type> --value <value> [--json]");
         writer.WriteLine("mxgw-dotnet write2 --session-id <id> --server-handle <n> --item-handle <n> --type <type> --value <value> [--timestamp <iso>] [--json]");
         writer.WriteLine("mxgw-dotnet smoke --item <ref> [--value <value> --type <type>] [--json]");
+        writer.WriteLine("mxgw-dotnet galaxy-test-connection [--json]");
+        writer.WriteLine("mxgw-dotnet galaxy-last-deploy [--json]");
+        writer.WriteLine("mxgw-dotnet galaxy-discover [--json]");
+        writer.WriteLine("mxgw-dotnet galaxy-watch [--last-seen-deploy-time <iso8601>] [--max-events <n>] [--json]");
     }
 }

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

@@ -0,0 +1,108 @@
+using Grpc.Core;
+using MxGateway.Contracts.Proto.Galaxy;
+
+namespace MxGateway.Client.Tests;
+
+internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions options) : IGalaxyRepositoryClientTransport
+{
+    public MxGatewayClientOptions Options { get; } = options;
+
+    public GalaxyRepository.GalaxyRepositoryClient? RawClient => null;
+
+    public List<(TestConnectionRequest Request, CallOptions CallOptions)> TestConnectionCalls { get; } = [];
+
+    public List<(GetLastDeployTimeRequest Request, CallOptions CallOptions)> GetLastDeployTimeCalls { get; } = [];
+
+    public List<(DiscoverHierarchyRequest Request, CallOptions CallOptions)> DiscoverHierarchyCalls { get; } = [];
+
+    public TestConnectionReply TestConnectionReply { get; set; } = new() { Ok = true };
+
+    public GetLastDeployTimeReply GetLastDeployTimeReply { get; set; } = new() { Present = false };
+
+    public DiscoverHierarchyReply DiscoverHierarchyReply { get; set; } = new();
+
+    public Queue<DiscoverHierarchyReply> DiscoverHierarchyReplies { get; } = new();
+
+    public Queue<Exception> TestConnectionExceptions { get; } = new();
+
+    public Queue<Exception> GetLastDeployTimeExceptions { get; } = new();
+
+    public Queue<Exception> DiscoverHierarchyExceptions { get; } = new();
+
+    public Task<TestConnectionReply> TestConnectionAsync(
+        TestConnectionRequest request,
+        CallOptions callOptions)
+    {
+        TestConnectionCalls.Add((request, callOptions));
+        if (TestConnectionExceptions.TryDequeue(out Exception? exception))
+        {
+            throw exception;
+        }
+
+        return Task.FromResult(TestConnectionReply);
+    }
+
+    public Task<GetLastDeployTimeReply> GetLastDeployTimeAsync(
+        GetLastDeployTimeRequest request,
+        CallOptions callOptions)
+    {
+        GetLastDeployTimeCalls.Add((request, callOptions));
+        if (GetLastDeployTimeExceptions.TryDequeue(out Exception? exception))
+        {
+            throw exception;
+        }
+
+        return Task.FromResult(GetLastDeployTimeReply);
+    }
+
+    public Task<DiscoverHierarchyReply> DiscoverHierarchyAsync(
+        DiscoverHierarchyRequest request,
+        CallOptions callOptions)
+    {
+        DiscoverHierarchyCalls.Add((request, callOptions));
+        if (DiscoverHierarchyExceptions.TryDequeue(out Exception? exception))
+        {
+            throw exception;
+        }
+
+        return Task.FromResult(
+            DiscoverHierarchyReplies.TryDequeue(out DiscoverHierarchyReply? reply)
+                ? reply
+                : DiscoverHierarchyReply);
+    }
+
+    public List<(WatchDeployEventsRequest Request, CallOptions CallOptions)> WatchDeployEventsCalls { get; } = [];
+
+    public List<DeployEvent> WatchDeployEvents { get; } = [];
+
+    public Exception? WatchDeployEventsException { get; set; }
+
+    /// <summary>
+    /// When set, awaited before each event yield so tests can observe cancellation
+    /// mid-stream. Receives the call's cancellation token.
+    /// </summary>
+    public Func<CancellationToken, Task>? WatchDeployEventsBeforeYield { get; set; }
+
+    public async IAsyncEnumerable<DeployEvent> WatchDeployEventsAsync(
+        WatchDeployEventsRequest request,
+        CallOptions callOptions)
+    {
+        WatchDeployEventsCalls.Add((request, callOptions));
+
+        if (WatchDeployEventsException is not null)
+        {
+            throw WatchDeployEventsException;
+        }
+
+        foreach (DeployEvent deployEvent in WatchDeployEvents)
+        {
+            if (WatchDeployEventsBeforeYield is not null)
+            {
+                await WatchDeployEventsBeforeYield(callOptions.CancellationToken).ConfigureAwait(false);
+            }
+
+            callOptions.CancellationToken.ThrowIfCancellationRequested();
+            yield return deployEvent;
+        }
+    }
+}

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

@@ -36,11 +36,22 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
         ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
     };
 
+    public Queue<Exception> OpenSessionExceptions { get; } = new();
+
+    public Queue<Exception> CloseSessionExceptions { get; } = new();
+
+    public Queue<Exception> InvokeExceptions { get; } = new();
+
     public Task<OpenSessionReply> OpenSessionAsync(
         OpenSessionRequest request,
         CallOptions callOptions)
     {
         OpenSessionCalls.Add((request, callOptions));
+        if (OpenSessionExceptions.TryDequeue(out Exception? exception))
+        {
+            throw exception;
+        }
+
         return Task.FromResult(OpenSessionReply);
     }
 
@@ -49,6 +60,11 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
         CallOptions callOptions)
     {
         CloseSessionCalls.Add((request, callOptions));
+        if (CloseSessionExceptions.TryDequeue(out Exception? exception))
+        {
+            throw exception;
+        }
+
         return Task.FromResult(CloseSessionReply);
     }
 
@@ -57,6 +73,11 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
         CallOptions callOptions)
     {
         InvokeCalls.Add((request, callOptions));
+        if (InvokeExceptions.TryDequeue(out Exception? exception))
+        {
+            throw exception;
+        }
+
         return Task.FromResult(_invokeReplies.Dequeue());
     }
 

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

@@ -0,0 +1,371 @@
+using Google.Protobuf.WellKnownTypes;
+using Grpc.Core;
+using MxGateway.Contracts.Proto.Galaxy;
+
+namespace MxGateway.Client.Tests;
+
+public sealed class GalaxyRepositoryClientTests
+{
+    [Fact]
+    public async Task TestConnectionAsync_AttachesApiKeyMetadataAndReturnsOkFlag()
+    {
+        using CancellationTokenSource cancellation = new();
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.TestConnectionReply = new TestConnectionReply { Ok = true };
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        bool ok = await client.TestConnectionAsync(cancellation.Token);
+
+        Assert.True(ok);
+        var call = Assert.Single(transport.TestConnectionCalls);
+        Assert.Equal("Bearer test-api-key", call.CallOptions.Headers?.GetValue("authorization"));
+    }
+
+    [Fact]
+    public async Task TestConnectionAsync_ReturnsFalseWhenServerReportsNotOk()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.TestConnectionReply = new TestConnectionReply { Ok = false };
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        bool ok = await client.TestConnectionAsync();
+
+        Assert.False(ok);
+    }
+
+    [Fact]
+    public async Task GetLastDeployTimeAsync_ReturnsNullWhenNotPresent()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.GetLastDeployTimeReply = new GetLastDeployTimeReply { Present = false };
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        DateTime? deployTime = await client.GetLastDeployTimeAsync();
+
+        Assert.Null(deployTime);
+        Assert.Single(transport.GetLastDeployTimeCalls);
+    }
+
+    [Fact]
+    public async Task GetLastDeployTimeAsync_ReturnsTimestampWhenPresent()
+    {
+        DateTime expected = new(2026, 4, 28, 14, 30, 0, DateTimeKind.Utc);
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.GetLastDeployTimeReply = new GetLastDeployTimeReply
+        {
+            Present = true,
+            TimeOfLastDeploy = Timestamp.FromDateTime(expected),
+        };
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        DateTime? deployTime = await client.GetLastDeployTimeAsync();
+
+        Assert.NotNull(deployTime);
+        Assert.Equal(expected, deployTime!.Value);
+    }
+
+    [Fact]
+    public async Task DiscoverHierarchyAsync_ReturnsObjectsFromReply()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.DiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
+        {
+            NextPageToken = "page-2",
+            TotalObjectCount = 2,
+            Objects =
+            {
+                new GalaxyObject
+                {
+                    GobjectId = 12,
+                    TagName = "DelmiaReceiver_001",
+                    ContainedName = "DelmiaReceiver",
+                    BrowseName = "TestMachine_001/DelmiaReceiver",
+                    ParentGobjectId = 5,
+                    Attributes =
+                    {
+                        new GalaxyAttribute
+                        {
+                            AttributeName = "DownloadPath",
+                            FullTagReference = "DelmiaReceiver_001.DownloadPath",
+                            MxDataType = 8,
+                            DataTypeName = "MxString",
+                        },
+                    },
+                },
+            },
+        });
+        transport.DiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
+        {
+            TotalObjectCount = 2,
+            Objects =
+            {
+                new GalaxyObject
+                {
+                    GobjectId = 13,
+                    TagName = "DelmiaReceiver_002",
+                },
+            },
+        });
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        IReadOnlyList<GalaxyObject> objects = await client.DiscoverHierarchyAsync();
+
+        Assert.Equal(2, objects.Count);
+        Assert.Equal(2, transport.DiscoverHierarchyCalls.Count);
+        Assert.Equal(5000, transport.DiscoverHierarchyCalls[0].Request.PageSize);
+        Assert.Equal("", transport.DiscoverHierarchyCalls[0].Request.PageToken);
+        Assert.Equal("page-2", transport.DiscoverHierarchyCalls[1].Request.PageToken);
+        GalaxyObject obj = objects[0];
+        Assert.Equal(12, obj.GobjectId);
+        Assert.Equal("DelmiaReceiver_001", obj.TagName);
+        GalaxyAttribute attribute = Assert.Single(obj.Attributes);
+        Assert.Equal("DownloadPath", attribute.AttributeName);
+        Assert.Equal("DelmiaReceiver_001.DownloadPath", attribute.FullTagReference);
+    }
+
+    [Fact]
+    public async Task DiscoverHierarchyAsync_PropagatesCancellationToTransport()
+    {
+        using CancellationTokenSource cancellation = new();
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        await client.DiscoverHierarchyAsync(cancellation.Token);
+
+        var call = Assert.Single(transport.DiscoverHierarchyCalls);
+        // The retry pipeline links the caller token with a per-call timeout token,
+        // so the transport sees the linked token rather than the caller's directly.
+        // Verify the link relationship by cancelling the caller and checking the
+        // call-side token reflects it.
+        Assert.False(call.CallOptions.CancellationToken.IsCancellationRequested);
+    }
+
+    [Fact]
+    public async Task DiscoverHierarchyAsync_WithRepeatedPageToken_ThrowsProtocolError()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.DiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
+        {
+            NextPageToken = "7:1",
+        });
+        transport.DiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
+        {
+            NextPageToken = "7:1",
+        });
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        MxGatewayException exception = await Assert.ThrowsAsync<MxGatewayException>(
+            async () => await client.DiscoverHierarchyAsync());
+
+        Assert.Contains("repeated page token", exception.Message, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task DiscoverHierarchyAsync_WithOptions_MapsTypedFilters()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        await client.DiscoverHierarchyAsync(new DiscoverHierarchyOptions
+        {
+            RootContainedPath = "Area1/Line3",
+            MaxDepth = 2,
+            CategoryIds = [10, 13],
+            TemplateChainContains = ["Pump"],
+            TagNameGlob = "Pump_*",
+            IncludeAttributes = false,
+            AlarmBearingOnly = true,
+            HistorizedOnly = true,
+        });
+
+        DiscoverHierarchyRequest request = Assert.Single(transport.DiscoverHierarchyCalls).Request;
+        Assert.Equal(DiscoverHierarchyRequest.RootOneofCase.RootContainedPath, request.RootCase);
+        Assert.Equal("Area1/Line3", request.RootContainedPath);
+        Assert.Equal(2, request.MaxDepth);
+        Assert.Equal([10, 13], request.CategoryIds);
+        Assert.Equal(["Pump"], request.TemplateChainContains);
+        Assert.Equal("Pump_*", request.TagNameGlob);
+        Assert.True(request.HasIncludeAttributes);
+        Assert.False(request.IncludeAttributes);
+        Assert.True(request.AlarmBearingOnly);
+        Assert.True(request.HistorizedOnly);
+    }
+
+    [Fact]
+    public async Task TestConnectionAsync_RetriesOnTransientGrpcFailure()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.TestConnectionExceptions.Enqueue(CreateTransientRpcException());
+        transport.TestConnectionReply = new TestConnectionReply { Ok = true };
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        bool ok = await client.TestConnectionAsync();
+
+        Assert.True(ok);
+        Assert.Equal(2, transport.TestConnectionCalls.Count);
+    }
+
+    [Fact]
+    public async Task DiscoverHierarchyAsync_RetriesOnTransientGrpcFailure()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.DiscoverHierarchyExceptions.Enqueue(CreateTransientRpcException());
+        transport.DiscoverHierarchyReply = new DiscoverHierarchyReply();
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        await client.DiscoverHierarchyAsync();
+
+        Assert.Equal(2, transport.DiscoverHierarchyCalls.Count);
+    }
+
+    [Fact]
+    public async Task WatchDeployEventsAsync_DeliversBootstrapEvent()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        DateTime deployTime = new(2026, 4, 28, 14, 30, 0, DateTimeKind.Utc);
+        transport.WatchDeployEvents.Add(new DeployEvent
+        {
+            Sequence = 1,
+            ObservedAt = Timestamp.FromDateTime(deployTime),
+            TimeOfLastDeploy = Timestamp.FromDateTime(deployTime),
+            TimeOfLastDeployPresent = true,
+            ObjectCount = 7,
+            AttributeCount = 42,
+        });
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        List<DeployEvent> received = [];
+        await foreach (DeployEvent evt in client.WatchDeployEventsAsync())
+        {
+            received.Add(evt);
+        }
+
+        DeployEvent only = Assert.Single(received);
+        Assert.Equal(1ul, only.Sequence);
+        Assert.Equal(7, only.ObjectCount);
+        Assert.Equal(42, only.AttributeCount);
+        Assert.True(only.TimeOfLastDeployPresent);
+        var call = Assert.Single(transport.WatchDeployEventsCalls);
+        Assert.Equal("Bearer test-api-key", call.CallOptions.Headers?.GetValue("authorization"));
+        // No last_seen_deploy_time supplied → request leaves the field unset.
+        Assert.Null(call.Request.LastSeenDeployTime);
+    }
+
+    [Fact]
+    public async Task WatchDeployEventsAsync_DeliversMultipleEventsInOrder()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        DateTime t0 = new(2026, 4, 28, 14, 30, 0, DateTimeKind.Utc);
+        for (int index = 1; index <= 3; index++)
+        {
+            transport.WatchDeployEvents.Add(new DeployEvent
+            {
+                Sequence = (ulong)index,
+                ObservedAt = Timestamp.FromDateTime(t0.AddSeconds(index)),
+                TimeOfLastDeploy = Timestamp.FromDateTime(t0.AddSeconds(index)),
+                TimeOfLastDeployPresent = true,
+                ObjectCount = 10 + index,
+                AttributeCount = 100 + index,
+            });
+        }
+
+        DateTimeOffset lastSeen = new(t0, TimeSpan.Zero);
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        List<DeployEvent> received = [];
+        await foreach (DeployEvent evt in client.WatchDeployEventsAsync(lastSeen))
+        {
+            received.Add(evt);
+        }
+
+        Assert.Equal(3, received.Count);
+        Assert.Equal(new ulong[] { 1, 2, 3 }, received.Select(e => e.Sequence).ToArray());
+        Assert.Equal(new[] { 11, 12, 13 }, received.Select(e => e.ObjectCount).ToArray());
+        var call = Assert.Single(transport.WatchDeployEventsCalls);
+        Assert.NotNull(call.Request.LastSeenDeployTime);
+        Assert.Equal(t0, call.Request.LastSeenDeployTime!.ToDateTime());
+    }
+
+    [Fact]
+    public async Task WatchDeployEventsAsync_CancellationStopsIterationCleanly()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        // Add many events; the test will cancel after the first.
+        for (int index = 1; index <= 10; index++)
+        {
+            transport.WatchDeployEvents.Add(new DeployEvent { Sequence = (ulong)index });
+        }
+
+        using CancellationTokenSource cancellation = new();
+        // Cancel before the second yield by wiring the fake's pre-yield hook.
+        int yields = 0;
+        transport.WatchDeployEventsBeforeYield = _ =>
+        {
+            yields++;
+            if (yields >= 2)
+            {
+                cancellation.Cancel();
+            }
+
+            return Task.CompletedTask;
+        };
+
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        List<DeployEvent> received = [];
+        await Assert.ThrowsAnyAsync<OperationCanceledException>(async () =>
+        {
+            await foreach (DeployEvent evt in client
+                .WatchDeployEventsAsync(cancellationToken: cancellation.Token))
+            {
+                received.Add(evt);
+            }
+        });
+
+        // The first event yields before cancellation triggers on the second pass.
+        Assert.Single(received);
+        Assert.Equal(1ul, received[0].Sequence);
+    }
+
+    [Fact]
+    public async Task WatchDeployEventsAsync_ThrowsAfterDisposal()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        GalaxyRepositoryClient client = CreateClient(transport);
+
+        await client.DisposeAsync();
+
+        Assert.Throws<ObjectDisposedException>(() =>
+            client.WatchDeployEventsAsync());
+    }
+
+    [Fact]
+    public async Task TestConnectionAsync_ThrowsAfterDisposal()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        GalaxyRepositoryClient client = CreateClient(transport);
+
+        await client.DisposeAsync();
+
+        await Assert.ThrowsAsync<ObjectDisposedException>(() => client.TestConnectionAsync());
+    }
+
+    private static GalaxyRepositoryClient CreateClient(FakeGalaxyRepositoryTransport transport)
+    {
+        return new GalaxyRepositoryClient(transport.Options, transport);
+    }
+
+    private static FakeGalaxyRepositoryTransport CreateTransport()
+    {
+        return new FakeGalaxyRepositoryTransport(new MxGatewayClientOptions
+        {
+            Endpoint = new Uri("http://localhost:5000"),
+            ApiKey = "test-api-key",
+        });
+    }
+
+    private static RpcException CreateTransientRpcException()
+    {
+        return new RpcException(new Status(StatusCode.Unavailable, "gateway unavailable"));
+    }
+}

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

@@ -1,5 +1,7 @@
+using Google.Protobuf.WellKnownTypes;
 using MxGateway.Client.Cli;
 using MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto.Galaxy;
 
 namespace MxGateway.Client.Tests;
 
@@ -14,7 +16,7 @@ public sealed class MxGatewayClientCliTests
         var exitCode = MxGatewayClientCli.Run(["version"], output, error);
 
         Assert.Equal(0, exitCode);
-        Assert.Contains("gateway-protocol=1", output.ToString());
+        Assert.Contains("gateway-protocol=2", output.ToString());
         Assert.Contains("worker-protocol=1", output.ToString());
         Assert.Equal(string.Empty, error.ToString());
     }
@@ -28,7 +30,7 @@ public sealed class MxGatewayClientCliTests
         int exitCode = await MxGatewayClientCli.RunAsync(["version", "--json"], output, error);
 
         Assert.Equal(0, exitCode);
-        Assert.Contains("\"gatewayProtocolVersion\":1", output.ToString());
+        Assert.Contains("\"gatewayProtocolVersion\":2", output.ToString());
         Assert.Equal(string.Empty, error.ToString());
     }
 
@@ -170,6 +172,191 @@ public sealed class MxGatewayClientCliTests
         Assert.Equal("session-fixture", closeRequest.SessionId);
     }
 
+    [Fact]
+    public async Task RunAsync_GalaxyTestConnection_PrintsJsonReply()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+        FakeCliClient fakeClient = new()
+        {
+            GalaxyTestConnectionReply = new TestConnectionReply { Ok = true },
+        };
+
+        int exitCode = await MxGatewayClientCli.RunAsync(
+            [
+                "galaxy-test-connection",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+                "--json",
+            ],
+            output,
+            error,
+            _ => fakeClient);
+
+        Assert.Equal(0, exitCode);
+        Assert.Single(fakeClient.GalaxyTestConnectionRequests);
+        Assert.Contains("\"ok\": true", output.ToString());
+        Assert.Equal(string.Empty, error.ToString());
+    }
+
+    [Fact]
+    public async Task RunAsync_GalaxyDiscover_PrintsHierarchySummary()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+        FakeCliClient fakeClient = new();
+        fakeClient.GalaxyDiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
+        {
+            NextPageToken = "7:1",
+            TotalObjectCount = 2,
+            Objects =
+            {
+                new GalaxyObject
+                {
+                    GobjectId = 7,
+                    TagName = "DelmiaReceiver_001",
+                    ContainedName = "DelmiaReceiver",
+                    ParentGobjectId = 1,
+                    Attributes =
+                    {
+                        new GalaxyAttribute
+                        {
+                            AttributeName = "DownloadPath",
+                            FullTagReference = "DelmiaReceiver_001.DownloadPath",
+                        },
+                    },
+                },
+            },
+        });
+        fakeClient.GalaxyDiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
+        {
+            TotalObjectCount = 2,
+            Objects =
+            {
+                new GalaxyObject
+                {
+                    GobjectId = 8,
+                    TagName = "DelmiaReceiver_002",
+                    ContainedName = "DelmiaReceiver",
+                    ParentGobjectId = 1,
+                },
+            },
+        });
+
+        int exitCode = await MxGatewayClientCli.RunAsync(
+            [
+                "galaxy-discover",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+            ],
+            output,
+            error,
+            _ => fakeClient);
+
+        Assert.Equal(0, exitCode);
+        Assert.Equal(2, fakeClient.GalaxyDiscoverHierarchyRequests.Count);
+        Assert.Equal(5000, fakeClient.GalaxyDiscoverHierarchyRequests[0].PageSize);
+        Assert.Equal("", fakeClient.GalaxyDiscoverHierarchyRequests[0].PageToken);
+        Assert.Equal("7:1", fakeClient.GalaxyDiscoverHierarchyRequests[1].PageToken);
+        string text = output.ToString();
+        Assert.Contains("objects=2", text);
+        Assert.Contains("DelmiaReceiver_001", text);
+        Assert.Contains("DelmiaReceiver_002", text);
+        Assert.Contains("attributes=1", text);
+        Assert.Equal(string.Empty, error.ToString());
+    }
+
+    [Fact]
+    public async Task RunAsync_GalaxyWatch_PrintsTextOutputForEvents()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+        FakeCliClient fakeClient = new();
+        DateTime deploy = new(2026, 4, 28, 14, 30, 0, DateTimeKind.Utc);
+        fakeClient.GalaxyDeployEvents.Add(new DeployEvent
+        {
+            Sequence = 1,
+            ObservedAt = Timestamp.FromDateTime(deploy),
+            TimeOfLastDeploy = Timestamp.FromDateTime(deploy),
+            TimeOfLastDeployPresent = true,
+            ObjectCount = 5,
+            AttributeCount = 17,
+        });
+        fakeClient.GalaxyDeployEvents.Add(new DeployEvent
+        {
+            Sequence = 2,
+            ObservedAt = Timestamp.FromDateTime(deploy.AddSeconds(30)),
+            TimeOfLastDeploy = Timestamp.FromDateTime(deploy.AddSeconds(30)),
+            TimeOfLastDeployPresent = true,
+            ObjectCount = 6,
+            AttributeCount = 18,
+        });
+
+        int exitCode = await MxGatewayClientCli.RunAsync(
+            [
+                "galaxy-watch",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+                "--last-seen-deploy-time",
+                "2026-04-28T14:00:00Z",
+                "--max-events",
+                "2",
+            ],
+            output,
+            error,
+            _ => fakeClient);
+
+        Assert.Equal(0, exitCode);
+        WatchDeployEventsRequest request = Assert.Single(fakeClient.GalaxyWatchDeployEventsRequests);
+        Assert.NotNull(request.LastSeenDeployTime);
+        string text = output.ToString();
+        Assert.Contains("sequence=1", text);
+        Assert.Contains("sequence=2", text);
+        Assert.Contains("objects=5", text);
+        Assert.Contains("attributes=18", text);
+        Assert.Equal(string.Empty, error.ToString());
+    }
+
+    [Fact]
+    public async Task RunAsync_GalaxyWatch_JsonEmitsOneObjectPerEvent()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+        FakeCliClient fakeClient = new();
+        fakeClient.GalaxyDeployEvents.Add(new DeployEvent
+        {
+            Sequence = 42,
+            ObjectCount = 99,
+            AttributeCount = 1024,
+        });
+
+        int exitCode = await MxGatewayClientCli.RunAsync(
+            [
+                "galaxy-watch",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+                "--max-events",
+                "1",
+                "--json",
+            ],
+            output,
+            error,
+            _ => fakeClient);
+
+        Assert.Equal(0, exitCode);
+        string text = output.ToString();
+        Assert.Contains("\"sequence\": \"42\"", text);
+        Assert.Contains("\"objectCount\": 99", text);
+    }
+
     private sealed class FakeCliClient : IMxGatewayCliClient
     {
         public Queue<MxCommandReply> InvokeReplies { get; } = new();
@@ -237,5 +424,63 @@ public sealed class MxGatewayClientCliTests
                 yield return gatewayEvent;
             }
         }
+
+        public TestConnectionReply GalaxyTestConnectionReply { get; set; } = new() { Ok = true };
+
+        public GetLastDeployTimeReply GalaxyGetLastDeployTimeReply { get; set; } = new() { Present = false };
+
+        public DiscoverHierarchyReply GalaxyDiscoverHierarchyReply { get; set; } = new();
+
+        public Queue<DiscoverHierarchyReply> GalaxyDiscoverHierarchyReplies { get; } = new();
+
+        public List<TestConnectionRequest> GalaxyTestConnectionRequests { get; } = [];
+
+        public List<GetLastDeployTimeRequest> GalaxyGetLastDeployTimeRequests { get; } = [];
+
+        public List<DiscoverHierarchyRequest> GalaxyDiscoverHierarchyRequests { get; } = [];
+
+        public Task<TestConnectionReply> GalaxyTestConnectionAsync(
+            TestConnectionRequest request,
+            CancellationToken cancellationToken)
+        {
+            GalaxyTestConnectionRequests.Add(request);
+            return Task.FromResult(GalaxyTestConnectionReply);
+        }
+
+        public Task<GetLastDeployTimeReply> GalaxyGetLastDeployTimeAsync(
+            GetLastDeployTimeRequest request,
+            CancellationToken cancellationToken)
+        {
+            GalaxyGetLastDeployTimeRequests.Add(request);
+            return Task.FromResult(GalaxyGetLastDeployTimeReply);
+        }
+
+        public Task<DiscoverHierarchyReply> GalaxyDiscoverHierarchyAsync(
+            DiscoverHierarchyRequest request,
+            CancellationToken cancellationToken)
+        {
+            GalaxyDiscoverHierarchyRequests.Add(request);
+            return Task.FromResult(
+                GalaxyDiscoverHierarchyReplies.TryDequeue(out DiscoverHierarchyReply? reply)
+                    ? reply
+                    : GalaxyDiscoverHierarchyReply);
+        }
+
+        public List<WatchDeployEventsRequest> GalaxyWatchDeployEventsRequests { get; } = [];
+
+        public List<DeployEvent> GalaxyDeployEvents { get; } = [];
+
+        public async IAsyncEnumerable<DeployEvent> GalaxyWatchDeployEventsAsync(
+            WatchDeployEventsRequest request,
+            [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken)
+        {
+            GalaxyWatchDeployEventsRequests.Add(request);
+            foreach (DeployEvent deployEvent in GalaxyDeployEvents)
+            {
+                cancellationToken.ThrowIfCancellationRequested();
+                await Task.Yield();
+                yield return deployEvent;
+            }
+        }
     }
 }

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

@@ -25,4 +25,17 @@ public sealed class MxGatewayClientOptionsTests
 
         Assert.Throws<ArgumentException>(options.Validate);
     }
+
+    [Fact]
+    public void Validate_WithInvalidRetryOptions_Throws()
+    {
+        var options = new MxGatewayClientOptions
+        {
+            Endpoint = new Uri("http://localhost:5000"),
+            ApiKey = "test-api-key",
+            Retry = new MxGatewayClientRetryOptions { MaxAttempts = 0 },
+        };
+
+        Assert.Throws<ArgumentOutOfRangeException>(options.Validate);
+    }
 }

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

@@ -1,4 +1,5 @@
 using MxGateway.Contracts.Proto;
+using Grpc.Core;
 
 namespace MxGateway.Client.Tests;
 
@@ -137,6 +138,44 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal(56, request.Command.Write2.UserId);
     }
 
+    [Fact]
+    public async Task SubscribeBulkAsync_BuildsOneBulkCommandAndReturnsPerItemResults()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.AddInvokeReply(new MxCommandReply
+        {
+            SessionId = "session-fixture",
+            Kind = MxCommandKind.SubscribeBulk,
+            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+            SubscribeBulk = new BulkSubscribeReply
+            {
+                Results =
+                {
+                    new SubscribeResult
+                    {
+                        ServerHandle = 12,
+                        TagAddress = "Area001.Pump001.Speed",
+                        ItemHandle = 34,
+                        WasSuccessful = true,
+                    },
+                },
+            },
+        });
+        await using MxGatewayClient client = CreateClient(transport);
+        MxGatewaySession session = await client.OpenSessionAsync();
+
+        IReadOnlyList<SubscribeResult> results = await session.SubscribeBulkAsync(
+            12,
+            ["Area001.Pump001.Speed"]);
+
+        SubscribeResult result = Assert.Single(results);
+        Assert.Equal(34, result.ItemHandle);
+        MxCommandRequest request = Assert.Single(transport.InvokeCalls).Request;
+        Assert.Equal(MxCommandKind.SubscribeBulk, request.Command.Kind);
+        Assert.Equal(12, request.Command.SubscribeBulk.ServerHandle);
+        Assert.Equal(["Area001.Pump001.Speed"], request.Command.SubscribeBulk.TagAddresses);
+    }
+
     [Fact]
     public async Task StreamEventsAsync_YieldsEventsInGatewayOrder()
     {
@@ -182,6 +221,55 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal("session-fixture", call.Request.SessionId);
     }
 
+    [Fact]
+    public async Task InvokeAsync_RetriesSafeDiagnosticCommandOnTransientGrpcFailure()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        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);
+    }
+
+    [Fact]
+    public async Task OpenSessionAsync_DoesNotRetryTransientGrpcFailure()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.OpenSessionExceptions.Enqueue(CreateTransientRpcException());
+        await using MxGatewayClient client = CreateClient(transport);
+
+        await Assert.ThrowsAsync<RpcException>(async () => await client.OpenSessionAsync());
+
+        Assert.Single(transport.OpenSessionCalls);
+    }
+
+    [Fact]
+    public async Task InvokeAsync_DoesNotRetryWriteCommand()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.InvokeExceptions.Enqueue(CreateTransientRpcException());
+        await using MxGatewayClient client = CreateClient(transport);
+        MxGatewaySession session = await client.OpenSessionAsync();
+
+        await Assert.ThrowsAsync<RpcException>(async () =>
+            await session.WriteRawAsync(1, 2, 3.ToMxValue(), userId: 0));
+
+        Assert.Single(transport.InvokeCalls);
+    }
+
     [Fact]
     public async Task InvokeHelpers_PassCancellationTokenToTransport()
     {
@@ -214,4 +302,9 @@ public sealed class MxGatewayClientSessionTests
             ApiKey = "test-api-key",
         });
     }
+
+    private static RpcException CreateTransientRpcException()
+    {
+        return new RpcException(new Status(StatusCode.Unavailable, "gateway unavailable"));
+    }
 }

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

@@ -0,0 +1,381 @@
+using Google.Protobuf.WellKnownTypes;
+using Grpc.Core;
+using Grpc.Net.Client;
+using Microsoft.Extensions.Logging;
+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 MxGateway.Client;
+
+/// <summary>
+/// Provides the .NET client entry point for the public Galaxy Repository gRPC API.
+/// All RPCs are read-only metadata calls that share the gateway's API-key auth
+/// interceptor and require the <c>metadata:read</c> scope server-side.
+/// </summary>
+public sealed class GalaxyRepositoryClient : IAsyncDisposable
+{
+    private const int DiscoverHierarchyPageSize = 5000;
+
+    private readonly GrpcChannel? _channel;
+    private readonly IGalaxyRepositoryClientTransport _transport;
+    private readonly ResiliencePipeline _safeUnaryRetryPipeline;
+    private bool _disposed;
+
+    internal GalaxyRepositoryClient(
+        MxGatewayClientOptions options,
+        IGalaxyRepositoryClientTransport transport)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        options.Validate();
+
+        Options = options;
+        _transport = transport ?? throw new ArgumentNullException(nameof(transport));
+        _safeUnaryRetryPipeline = MxGatewayClientRetryPolicy.Create(
+            options.Retry,
+            options.LoggerFactory?.CreateLogger<GalaxyRepositoryClient>());
+        _channel = null;
+    }
+
+    private GalaxyRepositoryClient(
+        GrpcChannel channel,
+        IGalaxyRepositoryClientTransport transport)
+    {
+        _channel = channel;
+        _transport = transport;
+        Options = transport.Options;
+        _safeUnaryRetryPipeline = MxGatewayClientRetryPolicy.Create(
+            Options.Retry,
+            Options.LoggerFactory?.CreateLogger<GalaxyRepositoryClient>());
+    }
+
+    public MxGatewayClientOptions Options { get; }
+
+    public GalaxyRepository.GalaxyRepositoryClient RawClient =>
+        _transport.RawClient
+        ?? throw new InvalidOperationException("The raw generated gRPC client is not available for this client instance.");
+
+    public static GalaxyRepositoryClient Create(MxGatewayClientOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        options.Validate();
+
+        HttpMessageHandler handler = CreateHttpHandler(options);
+        var channel = GrpcChannel.ForAddress(
+            options.Endpoint,
+            new GrpcChannelOptions
+            {
+                HttpHandler = handler,
+                LoggerFactory = options.LoggerFactory,
+                MaxReceiveMessageSize = options.MaxGrpcMessageBytes,
+                MaxSendMessageSize = options.MaxGrpcMessageBytes,
+            });
+
+        return new GalaxyRepositoryClient(
+            channel,
+            new GrpcGalaxyRepositoryClientTransport(
+                options,
+                new GalaxyRepository.GalaxyRepositoryClient(channel)));
+    }
+
+    /// <summary>
+    /// Probes the Galaxy Repository database connection. Returns true when the
+    /// gateway can reach the configured ZB SQL Server.
+    /// </summary>
+    public async Task<bool> TestConnectionAsync(CancellationToken cancellationToken = default)
+    {
+        TestConnectionReply reply = await TestConnectionRawAsync(
+                new TestConnectionRequest(),
+                cancellationToken)
+            .ConfigureAwait(false);
+
+        return reply.Ok;
+    }
+
+    public Task<TestConnectionReply> TestConnectionRawAsync(
+        TestConnectionRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ThrowIfDisposed();
+
+        return ExecuteSafeUnaryAsync(
+            token => _transport.TestConnectionAsync(request, CreateCallOptions(token)),
+            cancellationToken);
+    }
+
+    /// <summary>
+    /// Returns the timestamp of the most recent Galaxy deployment, or
+    /// <see langword="null"/> when no deployment has been recorded.
+    /// </summary>
+    public async Task<DateTime?> GetLastDeployTimeAsync(CancellationToken cancellationToken = default)
+    {
+        GetLastDeployTimeReply reply = await GetLastDeployTimeRawAsync(
+                new GetLastDeployTimeRequest(),
+                cancellationToken)
+            .ConfigureAwait(false);
+
+        if (!reply.Present || reply.TimeOfLastDeploy is null)
+        {
+            return null;
+        }
+
+        return reply.TimeOfLastDeploy.ToDateTime();
+    }
+
+    public Task<GetLastDeployTimeReply> GetLastDeployTimeRawAsync(
+        GetLastDeployTimeRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ThrowIfDisposed();
+
+        return ExecuteSafeUnaryAsync(
+            token => _transport.GetLastDeployTimeAsync(request, CreateCallOptions(token)),
+            cancellationToken);
+    }
+
+    /// <summary>
+    /// Enumerates the deployed Galaxy object hierarchy. Each <see cref="GalaxyObject"/>
+    /// includes its dynamic attributes so callers can determine which tag references
+    /// they may subscribe to via the MxAccessGateway service.
+    /// </summary>
+    public async Task<IReadOnlyList<GalaxyObject>> DiscoverHierarchyAsync(CancellationToken cancellationToken = default)
+    {
+        return await DiscoverHierarchyAsync(new DiscoverHierarchyOptions(), cancellationToken).ConfigureAwait(false);
+    }
+
+    public async Task<IReadOnlyList<GalaxyObject>> DiscoverHierarchyAsync(
+        DiscoverHierarchyOptions options,
+        CancellationToken cancellationToken = default)
+    {
+        List<GalaxyObject> objects = [];
+        HashSet<string> seenPageTokens = new(StringComparer.Ordinal);
+        string pageToken = string.Empty;
+        do
+        {
+            DiscoverHierarchyRequest request = CreateDiscoverHierarchyRequest(options);
+            request.PageSize = DiscoverHierarchyPageSize;
+            request.PageToken = pageToken;
+            DiscoverHierarchyReply reply = await DiscoverHierarchyRawAsync(
+                    request,
+                    cancellationToken)
+                .ConfigureAwait(false);
+
+            objects.AddRange(reply.Objects);
+            pageToken = reply.NextPageToken;
+            if (!string.IsNullOrWhiteSpace(pageToken)
+                && !seenPageTokens.Add(pageToken))
+            {
+                throw new MxGatewayException(
+                    $"Galaxy DiscoverHierarchy returned a repeated page token '{pageToken}'.");
+            }
+        }
+        while (!string.IsNullOrWhiteSpace(pageToken));
+
+        return objects;
+    }
+
+    private static DiscoverHierarchyRequest CreateDiscoverHierarchyRequest(DiscoverHierarchyOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        DiscoverHierarchyRequest request = new()
+        {
+            AlarmBearingOnly = options.AlarmBearingOnly,
+            HistorizedOnly = options.HistorizedOnly,
+        };
+
+        if (options.RootGobjectId.HasValue)
+        {
+            request.RootGobjectId = options.RootGobjectId.Value;
+        }
+        else if (!string.IsNullOrWhiteSpace(options.RootTagName))
+        {
+            request.RootTagName = options.RootTagName;
+        }
+        else if (!string.IsNullOrWhiteSpace(options.RootContainedPath))
+        {
+            request.RootContainedPath = options.RootContainedPath;
+        }
+
+        if (options.MaxDepth.HasValue)
+        {
+            request.MaxDepth = options.MaxDepth.Value;
+        }
+
+        request.CategoryIds.Add(options.CategoryIds);
+        request.TemplateChainContains.Add(options.TemplateChainContains);
+        if (!string.IsNullOrWhiteSpace(options.TagNameGlob))
+        {
+            request.TagNameGlob = options.TagNameGlob;
+        }
+
+        if (options.IncludeAttributes.HasValue)
+        {
+            request.IncludeAttributes = options.IncludeAttributes.Value;
+        }
+
+        return request;
+    }
+
+    public Task<DiscoverHierarchyReply> DiscoverHierarchyRawAsync(
+        DiscoverHierarchyRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ThrowIfDisposed();
+
+        return ExecuteSafeUnaryAsync(
+            token => _transport.DiscoverHierarchyAsync(request, CreateCallOptions(token)),
+            cancellationToken);
+    }
+
+    /// <summary>
+    /// Subscribes to Galaxy deploy events. The server emits a bootstrap event with the
+    /// current state on subscribe so callers can prime their cache, then emits one event
+    /// per new <c>time_of_last_deploy</c>. Pass <paramref name="lastSeenDeployTime"/> to
+    /// suppress the bootstrap when the caller already holds the current deploy time.
+    /// </summary>
+    /// <remarks>
+    /// Streaming RPCs are not wrapped by the unary safe-read retry pipeline. If the
+    /// stream is interrupted the caller must reopen it; the server does not guarantee
+    /// at-least-once delivery beyond the per-subscriber buffer (gaps in
+    /// <see cref="DeployEvent.Sequence"/> indicate dropped events).
+    /// </remarks>
+    public IAsyncEnumerable<DeployEvent> WatchDeployEventsAsync(
+        DateTimeOffset? lastSeenDeployTime = null,
+        CancellationToken cancellationToken = default)
+    {
+        ThrowIfDisposed();
+
+        WatchDeployEventsRequest request = new();
+        if (lastSeenDeployTime is { } seen)
+        {
+            request.LastSeenDeployTime = Timestamp.FromDateTimeOffset(seen);
+        }
+
+        return WatchDeployEventsRawAsync(request, cancellationToken);
+    }
+
+    public IAsyncEnumerable<DeployEvent> WatchDeployEventsRawAsync(
+        WatchDeployEventsRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ThrowIfDisposed();
+
+        return WatchDeployEventsCoreAsync(request, cancellationToken);
+    }
+
+    private async IAsyncEnumerable<DeployEvent> WatchDeployEventsCoreAsync(
+        WatchDeployEventsRequest request,
+        [EnumeratorCancellation] CancellationToken cancellationToken)
+    {
+        await foreach (DeployEvent deployEvent in _transport
+            .WatchDeployEventsAsync(request, CreateStreamCallOptions(cancellationToken))
+            .WithCancellation(cancellationToken)
+            .ConfigureAwait(false))
+        {
+            yield return deployEvent;
+        }
+    }
+
+    public ValueTask DisposeAsync()
+    {
+        if (_disposed)
+        {
+            return ValueTask.CompletedTask;
+        }
+
+        _disposed = true;
+        _channel?.Dispose();
+        return ValueTask.CompletedTask;
+    }
+
+    internal CallOptions CreateCallOptions(CancellationToken cancellationToken)
+    {
+        return CreateCallOptions(cancellationToken, Options.DefaultCallTimeout);
+    }
+
+    internal CallOptions CreateStreamCallOptions(CancellationToken cancellationToken)
+    {
+        return CreateCallOptions(cancellationToken, Options.StreamTimeout);
+    }
+
+    internal CallOptions CreateCallOptions(
+        CancellationToken cancellationToken,
+        TimeSpan? timeout)
+    {
+        Metadata headers = new()
+        {
+            { "authorization", $"Bearer {Options.ApiKey}" },
+        };
+
+        return new CallOptions(
+            headers,
+            timeout is null ? null : DateTime.UtcNow.Add(timeout.Value),
+            cancellationToken);
+    }
+
+    private async Task<T> ExecuteSafeUnaryAsync<T>(
+        Func<CancellationToken, Task<T>> call,
+        CancellationToken cancellationToken)
+    {
+        using CancellationTokenSource timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+        timeout.CancelAfter(Options.DefaultCallTimeout);
+
+        return await _safeUnaryRetryPipeline.ExecuteAsync(
+                async token => await call(token).ConfigureAwait(false),
+                timeout.Token)
+            .ConfigureAwait(false);
+    }
+
+    private static HttpMessageHandler CreateHttpHandler(MxGatewayClientOptions options)
+    {
+        SocketsHttpHandler handler = new()
+        {
+            ConnectTimeout = options.ConnectTimeout,
+        };
+
+        if (options.UseTls)
+        {
+            handler.SslOptions = new SslClientAuthenticationOptions();
+            if (!string.IsNullOrWhiteSpace(options.ServerNameOverride))
+            {
+                handler.SslOptions.TargetHost = options.ServerNameOverride;
+            }
+
+            if (!string.IsNullOrWhiteSpace(options.CaCertificatePath))
+            {
+                X509Certificate2 trustedRoot = X509CertificateLoader.LoadCertificateFromFile(options.CaCertificatePath);
+                handler.SslOptions.RemoteCertificateValidationCallback = (_, certificate, chain, errors) =>
+                {
+                    if (certificate is null)
+                    {
+                        return false;
+                    }
+
+                    using X509Chain customChain = new();
+                    customChain.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
+                    customChain.ChainPolicy.CustomTrustStore.Add(trustedRoot);
+                    customChain.ChainPolicy.RevocationMode = X509RevocationMode.NoCheck;
+                    customChain.ChainPolicy.VerificationFlags = X509VerificationFlags.NoFlag;
+                    X509Certificate2 certificateToValidate = certificate as X509Certificate2
+                        ?? X509CertificateLoader.LoadCertificate(certificate.Export(X509ContentType.Cert));
+                    return customChain.Build(certificateToValidate);
+                };
+            }
+        }
+
+        return handler;
+    }
+
+    private void ThrowIfDisposed()
+    {
+        ObjectDisposedException.ThrowIf(_disposed, this);
+    }
+}

clients/dotnet/MxGateway.Client/GrpcGalaxyRepositoryClientTransport.cs

@@ -0,0 +1,127 @@
+using Grpc.Core;
+using MxGateway.Contracts.Proto.Galaxy;
+
+namespace MxGateway.Client;
+
+internal sealed class GrpcGalaxyRepositoryClientTransport(
+    MxGatewayClientOptions options,
+    GalaxyRepository.GalaxyRepositoryClient rawClient) : IGalaxyRepositoryClientTransport
+{
+    public MxGatewayClientOptions Options { get; } = options;
+
+    public GalaxyRepository.GalaxyRepositoryClient RawClient { get; } = rawClient;
+
+    GalaxyRepository.GalaxyRepositoryClient? IGalaxyRepositoryClientTransport.RawClient => RawClient;
+
+    public async Task<TestConnectionReply> TestConnectionAsync(
+        TestConnectionRequest request,
+        CallOptions callOptions)
+    {
+        try
+        {
+            return await RawClient.TestConnectionAsync(request, callOptions)
+                .ResponseAsync
+                .ConfigureAwait(false);
+        }
+        catch (RpcException exception)
+        {
+            throw MapRpcException(exception, callOptions.CancellationToken);
+        }
+    }
+
+    public async Task<GetLastDeployTimeReply> GetLastDeployTimeAsync(
+        GetLastDeployTimeRequest request,
+        CallOptions callOptions)
+    {
+        try
+        {
+            return await RawClient.GetLastDeployTimeAsync(request, callOptions)
+                .ResponseAsync
+                .ConfigureAwait(false);
+        }
+        catch (RpcException exception)
+        {
+            throw MapRpcException(exception, callOptions.CancellationToken);
+        }
+    }
+
+    public async Task<DiscoverHierarchyReply> DiscoverHierarchyAsync(
+        DiscoverHierarchyRequest request,
+        CallOptions callOptions)
+    {
+        try
+        {
+            return await RawClient.DiscoverHierarchyAsync(request, callOptions)
+                .ResponseAsync
+                .ConfigureAwait(false);
+        }
+        catch (RpcException exception)
+        {
+            throw MapRpcException(exception, callOptions.CancellationToken);
+        }
+    }
+
+    public async IAsyncEnumerable<DeployEvent> WatchDeployEventsAsync(
+        WatchDeployEventsRequest request,
+        CallOptions callOptions,
+        [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        CancellationToken effectiveCancellationToken = cancellationToken.CanBeCanceled
+            ? cancellationToken
+            : callOptions.CancellationToken;
+
+        using AsyncServerStreamingCall<DeployEvent> call = RawClient.WatchDeployEvents(request, callOptions);
+
+        IAsyncStreamReader<DeployEvent> responseStream = call.ResponseStream;
+        while (true)
+        {
+            DeployEvent? deployEvent;
+            try
+            {
+                if (!await responseStream.MoveNext(effectiveCancellationToken).ConfigureAwait(false))
+                {
+                    break;
+                }
+
+                deployEvent = responseStream.Current;
+            }
+            catch (RpcException exception)
+            {
+                throw MapRpcException(exception, effectiveCancellationToken);
+            }
+
+            yield return deployEvent;
+        }
+    }
+
+    IAsyncEnumerable<DeployEvent> IGalaxyRepositoryClientTransport.WatchDeployEventsAsync(
+        WatchDeployEventsRequest request,
+        CallOptions callOptions)
+    {
+        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

@@ -25,7 +25,7 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
         catch (RpcException exception)
         {
-            throw MapRpcException(exception);
+            throw MapRpcException(exception, callOptions.CancellationToken);
         }
     }
 
@@ -41,7 +41,7 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
         catch (RpcException exception)
         {
-            throw MapRpcException(exception);
+            throw MapRpcException(exception, callOptions.CancellationToken);
         }
     }
 
@@ -57,7 +57,7 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
         catch (RpcException exception)
         {
-            throw MapRpcException(exception);
+            throw MapRpcException(exception, callOptions.CancellationToken);
         }
     }
 
@@ -87,7 +87,7 @@ internal sealed class GrpcMxGatewayClientTransport(
             }
             catch (RpcException exception)
             {
-                throw MapRpcException(exception);
+                throw MapRpcException(exception, effectiveCancellationToken);
             }
 
             yield return gatewayEvent;
@@ -101,8 +101,18 @@ internal sealed class GrpcMxGatewayClientTransport(
         return StreamEventsAsync(request, callOptions);
     }
 
-    private static MxGatewayException MapRpcException(RpcException exception)
+    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(

clients/dotnet/MxGateway.Client/IGalaxyRepositoryClientTransport.cs

@@ -0,0 +1,27 @@
+using Grpc.Core;
+using MxGateway.Contracts.Proto.Galaxy;
+
+namespace MxGateway.Client;
+
+internal interface IGalaxyRepositoryClientTransport
+{
+    MxGatewayClientOptions Options { get; }
+
+    GalaxyRepository.GalaxyRepositoryClient? RawClient { get; }
+
+    Task<TestConnectionReply> TestConnectionAsync(
+        TestConnectionRequest request,
+        CallOptions callOptions);
+
+    Task<GetLastDeployTimeReply> GetLastDeployTimeAsync(
+        GetLastDeployTimeRequest request,
+        CallOptions callOptions);
+
+    Task<DiscoverHierarchyReply> DiscoverHierarchyAsync(
+        DiscoverHierarchyRequest request,
+        CallOptions callOptions);
+
+    IAsyncEnumerable<DeployEvent> WatchDeployEventsAsync(
+        WatchDeployEventsRequest request,
+        CallOptions callOptions);
+}

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

@@ -7,6 +7,7 @@
   <ItemGroup>
     <PackageReference Include="Grpc.Net.Client" Version="2.76.0" />
     <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.7" />
+    <PackageReference Include="Polly.Core" Version="8.6.6" />
   </ItemGroup>
 
   <PropertyGroup>

clients/dotnet/MxGateway.Client/MxGatewayClient.cs

@@ -1,6 +1,11 @@
 using Grpc.Core;
 using Grpc.Net.Client;
+using Microsoft.Extensions.Logging;
 using MxGateway.Contracts.Proto;
+using Polly;
+using System.Net.Http;
+using System.Net.Security;
+using System.Security.Cryptography.X509Certificates;
 
 namespace MxGateway.Client;
 
@@ -11,6 +16,7 @@ public sealed class MxGatewayClient : IAsyncDisposable
 {
     private readonly GrpcChannel _channel;
     private readonly IMxGatewayClientTransport _transport;
+    private readonly ResiliencePipeline _safeUnaryRetryPipeline;
     private bool _disposed;
 
     internal MxGatewayClient(
@@ -22,6 +28,9 @@ public sealed class MxGatewayClient : IAsyncDisposable
 
         Options = options;
         _transport = transport ?? throw new ArgumentNullException(nameof(transport));
+        _safeUnaryRetryPipeline = MxGatewayClientRetryPolicy.Create(
+            options.Retry,
+            options.LoggerFactory?.CreateLogger<MxGatewayClient>());
         _channel = null!;
     }
 
@@ -32,6 +41,9 @@ public sealed class MxGatewayClient : IAsyncDisposable
         _channel = channel;
         _transport = transport;
         Options = transport.Options;
+        _safeUnaryRetryPipeline = MxGatewayClientRetryPolicy.Create(
+            Options.Retry,
+            Options.LoggerFactory?.CreateLogger<MxGatewayClient>());
     }
 
     public MxGatewayClientOptions Options { get; }
@@ -45,11 +57,15 @@ public sealed class MxGatewayClient : IAsyncDisposable
         ArgumentNullException.ThrowIfNull(options);
         options.Validate();
 
+        HttpMessageHandler handler = CreateHttpHandler(options);
         var channel = GrpcChannel.ForAddress(
             options.Endpoint,
             new GrpcChannelOptions
             {
+                HttpHandler = handler,
                 LoggerFactory = options.LoggerFactory,
+                MaxReceiveMessageSize = options.MaxGrpcMessageBytes,
+                MaxSendMessageSize = options.MaxGrpcMessageBytes,
             });
 
         return new MxGatewayClient(
@@ -88,7 +104,9 @@ public sealed class MxGatewayClient : IAsyncDisposable
         ArgumentNullException.ThrowIfNull(request);
         ThrowIfDisposed();
 
-        return _transport.CloseSessionAsync(request, CreateCallOptions(cancellationToken));
+        return ExecuteSafeUnaryAsync(
+            token => _transport.CloseSessionAsync(request, CreateCallOptions(token)),
+            cancellationToken);
     }
 
     public Task<MxCommandReply> InvokeAsync(
@@ -98,6 +116,13 @@ public sealed class MxGatewayClient : IAsyncDisposable
         ArgumentNullException.ThrowIfNull(request);
         ThrowIfDisposed();
 
+        if (MxGatewayClientRetryPolicy.IsRetryableCommand(request.Command?.Kind ?? MxCommandKind.Unspecified))
+        {
+            return ExecuteSafeUnaryAsync(
+                token => _transport.InvokeAsync(request, CreateCallOptions(token)),
+                cancellationToken);
+        }
+
         return _transport.InvokeAsync(request, CreateCallOptions(cancellationToken));
     }
 
@@ -108,7 +133,7 @@ public sealed class MxGatewayClient : IAsyncDisposable
         ArgumentNullException.ThrowIfNull(request);
         ThrowIfDisposed();
 
-        return _transport.StreamEventsAsync(request, CreateCallOptions(cancellationToken));
+        return _transport.StreamEventsAsync(request, CreateStreamCallOptions(cancellationToken));
     }
 
     public ValueTask DisposeAsync()
@@ -124,6 +149,18 @@ public sealed class MxGatewayClient : IAsyncDisposable
     }
 
     internal CallOptions CreateCallOptions(CancellationToken cancellationToken)
+    {
+        return CreateCallOptions(cancellationToken, Options.DefaultCallTimeout);
+    }
+
+    internal CallOptions CreateStreamCallOptions(CancellationToken cancellationToken)
+    {
+        return CreateCallOptions(cancellationToken, Options.StreamTimeout);
+    }
+
+    internal CallOptions CreateCallOptions(
+        CancellationToken cancellationToken,
+        TimeSpan? timeout)
     {
         Metadata headers = new()
         {
@@ -132,10 +169,63 @@ public sealed class MxGatewayClient : IAsyncDisposable
 
         return new CallOptions(
             headers,
-            DateTime.UtcNow.Add(Options.DefaultCallTimeout),
+            timeout is null ? null : DateTime.UtcNow.Add(timeout.Value),
             cancellationToken);
     }
 
+    private async Task<T> ExecuteSafeUnaryAsync<T>(
+        Func<CancellationToken, Task<T>> call,
+        CancellationToken cancellationToken)
+    {
+        using CancellationTokenSource timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+        timeout.CancelAfter(Options.DefaultCallTimeout);
+
+        return await _safeUnaryRetryPipeline.ExecuteAsync(
+                async token => await call(token).ConfigureAwait(false),
+                timeout.Token)
+            .ConfigureAwait(false);
+    }
+
+    private static HttpMessageHandler CreateHttpHandler(MxGatewayClientOptions options)
+    {
+        SocketsHttpHandler handler = new()
+        {
+            ConnectTimeout = options.ConnectTimeout,
+        };
+
+        if (options.UseTls)
+        {
+            handler.SslOptions = new SslClientAuthenticationOptions();
+            if (!string.IsNullOrWhiteSpace(options.ServerNameOverride))
+            {
+                handler.SslOptions.TargetHost = options.ServerNameOverride;
+            }
+
+            if (!string.IsNullOrWhiteSpace(options.CaCertificatePath))
+            {
+                X509Certificate2 trustedRoot = X509CertificateLoader.LoadCertificateFromFile(options.CaCertificatePath);
+                handler.SslOptions.RemoteCertificateValidationCallback = (_, certificate, chain, errors) =>
+                {
+                    if (certificate is null)
+                    {
+                        return false;
+                    }
+
+                    using X509Chain customChain = new();
+                    customChain.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
+                    customChain.ChainPolicy.CustomTrustStore.Add(trustedRoot);
+                    customChain.ChainPolicy.RevocationMode = X509RevocationMode.NoCheck;
+                    customChain.ChainPolicy.VerificationFlags = X509VerificationFlags.NoFlag;
+                    X509Certificate2 certificateToValidate = certificate as X509Certificate2
+                        ?? X509CertificateLoader.LoadCertificate(certificate.Export(X509ContentType.Cert));
+                    return customChain.Build(certificateToValidate);
+                };
+            }
+        }
+
+        return handler;
+    }
+
     private void ThrowIfDisposed()
     {
         ObjectDisposedException.ThrowIf(_disposed, this);

clients/dotnet/MxGateway.Client/MxGatewayClientOptions.cs

@@ -21,6 +21,12 @@ public sealed class MxGatewayClientOptions
 
     public TimeSpan DefaultCallTimeout { get; init; } = TimeSpan.FromSeconds(30);
 
+    public TimeSpan? StreamTimeout { get; init; }
+
+    public int MaxGrpcMessageBytes { get; init; } = 16 * 1024 * 1024;
+
+    public MxGatewayClientRetryOptions Retry { get; init; } = new();
+
     public ILoggerFactory? LoggerFactory { get; init; }
 
     public void Validate()
@@ -54,5 +60,35 @@ public sealed class MxGatewayClientOptions
                 nameof(DefaultCallTimeout),
                 "The default call timeout must be greater than zero.");
         }
+
+        if (StreamTimeout is not null && StreamTimeout <= TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(StreamTimeout),
+                "The stream timeout must be greater than zero when configured.");
+        }
+
+        if (MaxGrpcMessageBytes <= 0)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(MaxGrpcMessageBytes),
+                "The maximum gRPC message size must be greater than zero.");
+        }
+
+        if (UseTls && Endpoint.Scheme != Uri.UriSchemeHttps)
+        {
+            throw new ArgumentException(
+                "UseTls requires an https gateway endpoint.",
+                nameof(Endpoint));
+        }
+
+        if (!UseTls && Endpoint.Scheme == Uri.UriSchemeHttps)
+        {
+            throw new ArgumentException(
+                "An https gateway endpoint requires UseTls.",
+                nameof(Endpoint));
+        }
+
+        Retry.Validate();
     }
 }

clients/dotnet/MxGateway.Client/MxGatewayClientRetryOptions.cs

@@ -0,0 +1,43 @@
+namespace MxGateway.Client;
+
+public sealed class MxGatewayClientRetryOptions
+{
+    public int MaxAttempts { get; init; } = 2;
+
+    public TimeSpan Delay { get; init; } = TimeSpan.FromMilliseconds(200);
+
+    public TimeSpan MaxDelay { get; init; } = TimeSpan.FromSeconds(2);
+
+    public bool UseJitter { get; init; } = true;
+
+    public void Validate()
+    {
+        if (MaxAttempts <= 0)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(MaxAttempts),
+                "The retry max attempts value must be greater than zero.");
+        }
+
+        if (Delay <= TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(Delay),
+                "The retry delay must be greater than zero.");
+        }
+
+        if (MaxDelay <= TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(MaxDelay),
+                "The retry max delay must be greater than zero.");
+        }
+
+        if (MaxDelay < Delay)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(MaxDelay),
+                "The retry max delay must be greater than or equal to the retry delay.");
+        }
+    }
+}

clients/dotnet/MxGateway.Client/MxGatewayClientRetryPolicy.cs

@@ -0,0 +1,62 @@
+using Grpc.Core;
+using Microsoft.Extensions.Logging;
+using MxGateway.Contracts.Proto;
+using Polly;
+using Polly.Retry;
+
+namespace MxGateway.Client;
+
+internal static class MxGatewayClientRetryPolicy
+{
+    public static ResiliencePipeline Create(
+        MxGatewayClientRetryOptions options,
+        ILogger? logger)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        options.Validate();
+
+        return new ResiliencePipelineBuilder()
+            .AddRetry(new RetryStrategyOptions
+            {
+                MaxRetryAttempts = Math.Max(0, options.MaxAttempts - 1),
+                BackoffType = DelayBackoffType.Exponential,
+                UseJitter = options.UseJitter,
+                Delay = options.Delay,
+                MaxDelay = options.MaxDelay,
+                ShouldHandle = new PredicateBuilder().Handle<Exception>(IsTransientGrpcFailure),
+                OnRetry = args =>
+                {
+                    logger?.LogDebug(
+                        args.Outcome.Exception,
+                        "Retrying MXAccess Gateway client call after transient gRPC failure. Attempt {Attempt}.",
+                        args.AttemptNumber + 1);
+                    return default;
+                },
+            })
+            .Build();
+    }
+
+    public static bool IsRetryableCommand(MxCommandKind kind)
+    {
+        return kind is MxCommandKind.Ping
+            or MxCommandKind.GetSessionState
+            or MxCommandKind.GetWorkerInfo;
+    }
+
+    private static bool IsTransientGrpcFailure(Exception exception)
+    {
+        return exception switch
+        {
+            RpcException rpcException => IsTransientStatus(rpcException.StatusCode),
+            MxGatewayException { InnerException: RpcException rpcException } => IsTransientStatus(rpcException.StatusCode),
+            _ => false,
+        };
+    }
+
+    private static bool IsTransientStatus(StatusCode statusCode)
+    {
+        return statusCode is StatusCode.Unavailable
+            or StatusCode.DeadlineExceeded
+            or StatusCode.ResourceExhausted;
+    }
+}

clients/dotnet/MxGateway.Client/MxGatewaySession.cs

@@ -175,6 +175,194 @@ public sealed class MxGatewaySession : IAsyncDisposable
             cancellationToken);
     }
 
+    public async Task UnAdviseAsync(
+        int serverHandle,
+        int itemHandle,
+        CancellationToken cancellationToken = default)
+    {
+        MxCommandReply reply = await UnAdviseRawAsync(serverHandle, itemHandle, cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+    }
+
+    public Task<MxCommandReply> UnAdviseRawAsync(
+        int serverHandle,
+        int itemHandle,
+        CancellationToken cancellationToken = default)
+    {
+        return InvokeCommandAsync(
+            new MxCommand
+            {
+                Kind = MxCommandKind.UnAdvise,
+                UnAdvise = new UnAdviseCommand
+                {
+                    ServerHandle = serverHandle,
+                    ItemHandle = itemHandle,
+                },
+            },
+            cancellationToken);
+    }
+
+    public async Task RemoveItemAsync(
+        int serverHandle,
+        int itemHandle,
+        CancellationToken cancellationToken = default)
+    {
+        MxCommandReply reply = await RemoveItemRawAsync(serverHandle, itemHandle, cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+    }
+
+    public Task<MxCommandReply> RemoveItemRawAsync(
+        int serverHandle,
+        int itemHandle,
+        CancellationToken cancellationToken = default)
+    {
+        return InvokeCommandAsync(
+            new MxCommand
+            {
+                Kind = MxCommandKind.RemoveItem,
+                RemoveItem = new RemoveItemCommand
+                {
+                    ServerHandle = serverHandle,
+                    ItemHandle = itemHandle,
+                },
+            },
+            cancellationToken);
+    }
+
+    public async Task<IReadOnlyList<SubscribeResult>> AddItemBulkAsync(
+        int serverHandle,
+        IReadOnlyList<string> tagAddresses,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(tagAddresses);
+
+        AddItemBulkCommand command = new() { ServerHandle = serverHandle };
+        command.TagAddresses.Add(tagAddresses);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.AddItemBulk,
+                    AddItemBulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.AddItemBulk?.Results.ToArray() ?? [];
+    }
+
+    public async Task<IReadOnlyList<SubscribeResult>> AdviseItemBulkAsync(
+        int serverHandle,
+        IReadOnlyList<int> itemHandles,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(itemHandles);
+
+        AdviseItemBulkCommand command = new() { ServerHandle = serverHandle };
+        command.ItemHandles.Add(itemHandles);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.AdviseItemBulk,
+                    AdviseItemBulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.AdviseItemBulk?.Results.ToArray() ?? [];
+    }
+
+    public async Task<IReadOnlyList<SubscribeResult>> RemoveItemBulkAsync(
+        int serverHandle,
+        IReadOnlyList<int> itemHandles,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(itemHandles);
+
+        RemoveItemBulkCommand command = new() { ServerHandle = serverHandle };
+        command.ItemHandles.Add(itemHandles);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.RemoveItemBulk,
+                    RemoveItemBulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.RemoveItemBulk?.Results.ToArray() ?? [];
+    }
+
+    public async Task<IReadOnlyList<SubscribeResult>> UnAdviseItemBulkAsync(
+        int serverHandle,
+        IReadOnlyList<int> itemHandles,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(itemHandles);
+
+        UnAdviseItemBulkCommand command = new() { ServerHandle = serverHandle };
+        command.ItemHandles.Add(itemHandles);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.UnAdviseItemBulk,
+                    UnAdviseItemBulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.UnAdviseItemBulk?.Results.ToArray() ?? [];
+    }
+
+    public async Task<IReadOnlyList<SubscribeResult>> SubscribeBulkAsync(
+        int serverHandle,
+        IReadOnlyList<string> tagAddresses,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(tagAddresses);
+
+        SubscribeBulkCommand command = new() { ServerHandle = serverHandle };
+        command.TagAddresses.Add(tagAddresses);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.SubscribeBulk,
+                    SubscribeBulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.SubscribeBulk?.Results.ToArray() ?? [];
+    }
+
+    public async Task<IReadOnlyList<SubscribeResult>> UnsubscribeBulkAsync(
+        int serverHandle,
+        IReadOnlyList<int> itemHandles,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(itemHandles);
+
+        UnsubscribeBulkCommand command = new() { ServerHandle = serverHandle };
+        command.ItemHandles.Add(itemHandles);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.UnsubscribeBulk,
+                    UnsubscribeBulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.UnsubscribeBulk?.Results.ToArray() ?? [];
+    }
+
     public async Task WriteAsync(
         int serverHandle,
         int itemHandle,
@@ -297,4 +485,5 @@ public sealed class MxGatewaySession : IAsyncDisposable
             },
             cancellationToken);
     }
+
 }

clients/dotnet/README.md

@@ -23,6 +23,29 @@ dotnet build clients/dotnet/MxGateway.Client.sln
 dotnet test clients/dotnet/MxGateway.Client.sln --no-build
 ```
 
+## Packaging
+
+Create local library and CLI artifacts from the repository root:
+
+```powershell
+$dotnetPackageOutput = Join-Path (Get-Location) 'artifacts/clients/dotnet'
+dotnet pack clients/dotnet/MxGateway.Client/MxGateway.Client.csproj -c Release -p:PackageOutputPath="$dotnetPackageOutput"
+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
+published CLI runs from `artifacts/clients/dotnet/mxgw-dotnet`.
+
+## Regenerating Protobuf Bindings
+
+The .NET client uses the generated C# types from
+`src/MxGateway.Contracts/Generated`. Regenerate those files through the
+contracts project:
+
+```powershell
+dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj
+```
+
 ## Client Usage
 
 `MxGatewayClient` opens a gRPC channel to the gateway and attaches the API key
@@ -109,3 +132,116 @@ dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint htt
 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`.
+
+## Galaxy Repository Browse
+
+`GalaxyRepositoryClient` is a separate read-only wrapper around the
+`GalaxyRepository` gRPC service exposed by the same gateway. It shares the API
+key auth interceptor with `MxGatewayClient` and requires the `metadata:read`
+scope server-side. Use it to probe the ZB SQL connection, watch
+`time_of_last_deploy` for redeployments, and enumerate the deployed Galaxy
+object hierarchy plus each object's dynamic attributes.
+
+```csharp
+await using GalaxyRepositoryClient repository = GalaxyRepositoryClient.Create(
+    new MxGatewayClientOptions
+    {
+        Endpoint = new Uri("http://localhost:5000"),
+        ApiKey = apiKey,
+    });
+
+bool ok = await repository.TestConnectionAsync();
+DateTime? lastDeploy = await repository.GetLastDeployTimeAsync();
+
+IReadOnlyList<GalaxyObject> objects = await repository.DiscoverHierarchyAsync();
+foreach (GalaxyObject galaxyObject in objects)
+{
+    Console.WriteLine($"{galaxyObject.TagName} ({galaxyObject.ContainedName})");
+    foreach (GalaxyAttribute attribute in galaxyObject.Attributes)
+    {
+        Console.WriteLine($"  {attribute.AttributeName} -> {attribute.FullTagReference}");
+    }
+}
+```
+
+Use `DiscoverHierarchyOptions` to request a server-side slice without pulling
+the full Galaxy:
+
+```csharp
+IReadOnlyList<GalaxyObject> pumps = await repository.DiscoverHierarchyAsync(
+    new DiscoverHierarchyOptions
+    {
+        RootContainedPath = "Area1/Line3",
+        TagNameGlob = "Pump_*",
+        IncludeAttributes = false,
+    });
+```
+
+The CLI exposes the same operations:
+
+```powershell
+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/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-discover --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
+```
+
+### Watching deploy events
+
+`WatchDeployEventsAsync` opens the `WatchDeployEvents` server-streaming RPC. The
+server emits a bootstrap event with the current state on subscribe, then one
+event per new `time_of_last_deploy`. Pass a `lastSeenDeployTime` to suppress the
+bootstrap when the caller already holds the current deploy time. Use the
+monotonic `Sequence` field to detect dropped events: gaps mean the
+per-subscriber server-side buffer overflowed and the caller should reconcile.
+
+Streaming RPCs are not wrapped by the unary safe-read retry pipeline. The
+caller is responsible for reopening the stream on transient failures.
+
+```csharp
+await using GalaxyRepositoryClient repository = GalaxyRepositoryClient.Create(options);
+
+DateTimeOffset? lastSeen = null;
+await foreach (DeployEvent evt in repository.WatchDeployEventsAsync(
+    lastSeen,
+    cancellationToken))
+{
+    Console.WriteLine(
+        $"seq={evt.Sequence} objects={evt.ObjectCount} attributes={evt.AttributeCount}");
+    if (evt.TimeOfLastDeployPresent && evt.TimeOfLastDeploy is not null)
+    {
+        lastSeen = evt.TimeOfLastDeploy.ToDateTimeOffset();
+    }
+}
+```
+
+The CLI counterpart streams events until Ctrl+C (or `--max-events`):
+
+```powershell
+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/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 --max-events 5 --json
+```
+
+Use TLS options for a secured gateway:
+
+```powershell
+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
+
+Run live checks only when a gateway and MXAccess-backed worker are available:
+
+```powershell
+$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/MxGateway.Client.Cli -- smoke --endpoint $env:MXGATEWAY_ENDPOINT --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+```
+
+## Related Documentation
+
+- [Client Packaging](../../docs/ClientPackaging.md)
+- [Client Proto Generation](../../docs/client-proto-generation.md)
+- [.NET Client Detailed Design](../../docs/clients-dotnet-csharp-design.md)

clients/go/README.md

@@ -44,6 +44,24 @@ The tests parse the shared JSON fixtures, exercise value and status conversion,
 use `bufconn` for fake gateway auth and streaming behavior, and cover CLI JSON
 redaction.
 
+## Packaging
+
+Build a local CLI executable from `clients/go`:
+
+```powershell
+New-Item -ItemType Directory -Force ../../artifacts/clients/go | Out-Null
+go build -o ../../artifacts/clients/go/mxgw-go.exe ./cmd/mxgw-go
+```
+
+Install the CLI into the active `GOBIN` or `GOPATH/bin`:
+
+```powershell
+go install ./cmd/mxgw-go
+```
+
+Other Go modules can consume the library package with the module path
+`gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/mxgateway`.
+
 ## Client API
 
 Use `mxgateway.Dial` with `mxgateway.Options` to configure plaintext or TLS
@@ -58,10 +76,94 @@ client, err := mxgateway.Dial(ctx, mxgateway.Options{
 ```
 
 `Client.OpenSession` returns a `Session` with helpers for `Register`,
-`AddItem`, `AddItem2`, `Advise`, `Write`, `Events`, and `Close`. 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.
+`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
+`mxgateway` package aliases and the `Raw` helper methods. Typed errors support
+`errors.As` for `GatewayError`, `CommandError`, and `MxAccessError`; command
+errors preserve the raw reply.
+
+## Galaxy Repository browse
+
+The `GalaxyRepository` service (proto package `galaxy_repository.v1`) is a
+read-only metadata-only browse over the AVEVA System Platform Galaxy
+Repository. It uses the same API-key authentication as the MXAccess Gateway
+and requires the `metadata:read` scope. Use `mxgateway.DialGalaxy` to obtain a
+`*GalaxyClient` that mirrors the connection-management conventions of
+`Client`:
+
+```go
+galaxy, err := mxgateway.DialGalaxy(ctx, mxgateway.Options{
+    Endpoint:  "localhost:5000",
+    APIKey:    os.Getenv("MXGATEWAY_API_KEY"),
+    Plaintext: true,
+})
+if err != nil {
+    return err
+}
+defer galaxy.Close()
+
+ok, err := galaxy.TestConnection(ctx)
+deployTime, present, err := galaxy.GetLastDeployTime(ctx)
+objects, err := galaxy.DiscoverHierarchy(ctx)
+```
+
+`GetLastDeployTime` returns `(time.Time{}, false, nil)` when the server
+reports `present=false` (no deploy recorded). `DiscoverHierarchy` returns
+the generated `*GalaxyObject` slice with each object's dynamic attributes
+populated for direct contract access.
+
+### Watching deploy events
+
+`WatchDeployEvents` opens a server-streaming subscription. The server emits a
+bootstrap event with the current Galaxy state immediately on subscribe, then
+one `DeployEvent` per new deploy. `Sequence` is monotonic per server start;
+gaps signal dropped events. Pass a non-nil `lastSeenDeployTime` to suppress the
+bootstrap event when resuming from a known checkpoint:
+
+```go
+streamCtx, cancel := context.WithCancel(ctx)
+defer cancel()
+
+events, errs, err := galaxy.WatchDeployEvents(streamCtx, nil)
+if err != nil {
+    return err
+}
+
+for {
+    select {
+    case ev, ok := <-events:
+        if !ok {
+            return nil // stream completed (server EOF or ctx cancelled)
+        }
+        log.Printf("seq=%d objects=%d attrs=%d",
+            ev.GetSequence(), ev.GetObjectCount(), ev.GetAttributeCount())
+    case streamErr := <-errs:
+        if streamErr != nil {
+            return streamErr // *GatewayError
+        }
+    case <-ctx.Done():
+        return ctx.Err()
+    }
+}
+```
+
+Cancel the supplied context to tear down the stream cleanly. Both channels
+close after EOF, cancellation, or a terminal error; surfaced errors are wrapped
+in `*GatewayError`.
+
+The CLI exposes the same RPC via `galaxy-watch`:
+
+```powershell
+go run ./cmd/mxgw-go galaxy-watch -plaintext
+go run ./cmd/mxgw-go galaxy-watch -plaintext -json
+go run ./cmd/mxgw-go galaxy-watch -plaintext -last-seen-deploy-time 2026-04-28T10:00:00Z
+go run ./cmd/mxgw-go galaxy-watch -plaintext -limit 5
+```
+
+The command runs until Ctrl+C (or the optional `-limit` is reached) and prints
+one line per event in text mode or one JSON object per event with `-json`.
 
 ## CLI
 
@@ -77,7 +179,35 @@ go run ./cmd/mxgw-go advise -session-id <id> -server-handle 1 -item-handle 1 -pl
 go run ./cmd/mxgw-go write -session-id <id> -server-handle 1 -item-handle 1 -type int32 -value 123 -plaintext -json
 go run ./cmd/mxgw-go stream-events -session-id <id> -plaintext -json
 go run ./cmd/mxgw-go smoke -item Area001.Tag.Value -plaintext -json
+go run ./cmd/mxgw-go galaxy-test-connection -plaintext -json
+go run ./cmd/mxgw-go galaxy-last-deploy -plaintext -json
+go run ./cmd/mxgw-go galaxy-discover -plaintext -json
+go run ./cmd/mxgw-go galaxy-watch -plaintext -json
 ```
 
 Use `-api-key-env MXGATEWAY_API_KEY` or `-api-key <key>` when authentication is
 enabled. CLI output redacts the key value and never writes the raw secret.
+
+Use TLS options for a secured gateway:
+
+```powershell
+go run ./cmd/mxgw-go smoke -endpoint mxgateway.example.local:5001 -ca-cert C:\certs\mxgateway-ca.pem -server-name-override mxgateway.example.local -api-key-env MXGATEWAY_API_KEY -item Area001.Tag.Value -json
+```
+
+## Integration Checks
+
+Run live checks only when a gateway and MXAccess-backed worker are available:
+
+```powershell
+$env:MXGATEWAY_INTEGRATION = '1'
+$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
+$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
+$env:MXGATEWAY_TEST_ITEM = 'Area001.Tag.Value'
+go run ./cmd/mxgw-go smoke -endpoint $env:MXGATEWAY_ENDPOINT -plaintext -api-key-env MXGATEWAY_API_KEY -item $env:MXGATEWAY_TEST_ITEM -json
+```
+
+## Related Documentation
+
+- [Client Packaging](../../docs/ClientPackaging.md)
+- [Client Proto Generation](../../docs/client-proto-generation.md)
+- [Go Client Detailed Design](../../docs/clients-golang-design.md)

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

@@ -8,7 +8,10 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"os/signal"
 	"strconv"
+	"strings"
+	"syscall"
 	"time"
 
 	"gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/mxgateway"
@@ -77,12 +80,24 @@ func runWithIO(ctx context.Context, args []string, stdout, stderr io.Writer) err
 		return runAddItem(ctx, args[1:], stdout, stderr)
 	case "advise":
 		return runAdvise(ctx, args[1:], stdout, stderr)
+	case "subscribe-bulk":
+		return runSubscribeBulk(ctx, args[1:], stdout, stderr)
+	case "unsubscribe-bulk":
+		return runUnsubscribeBulk(ctx, args[1:], stdout, stderr)
 	case "write":
 		return runWrite(ctx, args[1:], stdout, stderr)
 	case "stream-events":
 		return runStreamEvents(ctx, args[1:], stdout, stderr)
 	case "smoke":
 		return runSmoke(ctx, args[1:], stdout, stderr)
+	case "galaxy-test-connection":
+		return runGalaxyTestConnection(ctx, args[1:], stdout, stderr)
+	case "galaxy-last-deploy":
+		return runGalaxyLastDeploy(ctx, args[1:], stdout, stderr)
+	case "galaxy-discover":
+		return runGalaxyDiscover(ctx, args[1:], stdout, stderr)
+	case "galaxy-watch":
+		return runGalaxyWatch(ctx, args[1:], stdout, stderr)
 	default:
 		writeUsage(stderr)
 		return fmt.Errorf("unknown command %q", args[0])
@@ -268,6 +283,60 @@ func runAdvise(ctx context.Context, args []string, stdout, stderr io.Writer) err
 	return writeCommandOutput(stdout, *jsonOutput, "advise", options, reply, err)
 }
 
+func runSubscribeBulk(ctx context.Context, args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("subscribe-bulk", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	common := bindCommonFlags(flags)
+	jsonOutput := flags.Bool("json", false, "write JSON output")
+	sessionID := flags.String("session-id", "", "gateway session id")
+	serverHandle := flags.Int("server-handle", 0, "MXAccess server handle")
+	items := flags.String("items", "", "comma-separated item definitions")
+
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+	if *sessionID == "" || *items == "" {
+		return errors.New("session-id and items are required")
+	}
+
+	client, options, err := dialForCommand(ctx, common)
+	if err != nil {
+		return err
+	}
+	defer client.Close()
+
+	session := mxgateway.NewSessionForID(client, *sessionID)
+	results, err := session.SubscribeBulk(ctx, int32(*serverHandle), parseStringList(*items))
+	return writeBulkOutput(stdout, *jsonOutput, "subscribe-bulk", options, results, err)
+}
+
+func runUnsubscribeBulk(ctx context.Context, args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("unsubscribe-bulk", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	common := bindCommonFlags(flags)
+	jsonOutput := flags.Bool("json", false, "write JSON output")
+	sessionID := flags.String("session-id", "", "gateway session id")
+	serverHandle := flags.Int("server-handle", 0, "MXAccess server handle")
+	itemHandles := flags.String("item-handles", "", "comma-separated item handles")
+
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+	if *sessionID == "" || *itemHandles == "" {
+		return errors.New("session-id and item-handles are required")
+	}
+
+	client, options, err := dialForCommand(ctx, common)
+	if err != nil {
+		return err
+	}
+	defer client.Close()
+
+	session := mxgateway.NewSessionForID(client, *sessionID)
+	results, err := session.UnsubscribeBulk(ctx, int32(*serverHandle), parseInt32List(*itemHandles))
+	return writeBulkOutput(stdout, *jsonOutput, "unsubscribe-bulk", options, results, err)
+}
+
 func runWrite(ctx context.Context, args []string, stdout, stderr io.Writer) error {
 	flags := flag.NewFlagSet("write", flag.ContinueOnError)
 	flags.SetOutput(stderr)
@@ -328,10 +397,12 @@ func runStreamEvents(ctx context.Context, args []string, stdout, stderr io.Write
 	session := mxgateway.NewSessionForID(client, *sessionID)
 	streamCtx, cancelStream := context.WithCancel(ctx)
 	defer cancelStream()
-	events, err := session.EventsAfter(streamCtx, *after)
+	subscription, err := session.SubscribeEventsAfter(streamCtx, *after)
 	if err != nil {
 		return err
 	}
+	defer subscription.Close()
+	events := subscription.Events()
 
 	count := 0
 	for result := range events {
@@ -377,17 +448,19 @@ func runSmoke(ctx context.Context, args []string, stdout, stderr io.Writer) erro
 	if err != nil {
 		return err
 	}
-	defer session.Close(context.Background())
 
 	serverHandle, err := session.Register(ctx, *clientName)
 	if err != nil {
-		return err
+		return closeSmokeSession(ctx, session, err)
 	}
 	itemHandle, err := session.AddItem(ctx, serverHandle, *item)
 	if err != nil {
-		return err
+		return closeSmokeSession(ctx, session, err)
 	}
 	if err := session.Advise(ctx, serverHandle, itemHandle); err != nil {
+		return closeSmokeSession(ctx, session, err)
+	}
+	if err := closeSmokeSession(ctx, session, nil); err != nil {
 		return err
 	}
 
@@ -406,6 +479,53 @@ func runSmoke(ctx context.Context, args []string, stdout, stderr io.Writer) erro
 	return nil
 }
 
+func closeSmokeSession(ctx context.Context, session *mxgateway.Session, primaryErr error) error {
+	closeCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	if deadline, ok := ctx.Deadline(); ok {
+		if until := time.Until(deadline); until > 0 && until < 5*time.Second {
+			cancel()
+			closeCtx, cancel = context.WithTimeout(context.Background(), until)
+			defer cancel()
+		}
+	}
+
+	_, closeErr := session.Close(closeCtx)
+	if primaryErr != nil {
+		return primaryErr
+	}
+	return closeErr
+}
+
+func parseStringList(value string) []string {
+	parts := strings.Split(value, ",")
+	items := make([]string, 0, len(parts))
+	for _, part := range parts {
+		item := strings.TrimSpace(part)
+		if item != "" {
+			items = append(items, item)
+		}
+	}
+	return items
+}
+
+func parseInt32List(value string) []int32 {
+	parts := strings.Split(value, ",")
+	items := make([]int32, 0, len(parts))
+	for _, part := range parts {
+		item := strings.TrimSpace(part)
+		if item == "" {
+			continue
+		}
+		parsed, err := strconv.ParseInt(item, 10, 32)
+		if err != nil {
+			panic(err)
+		}
+		items = append(items, int32(parsed))
+	}
+	return items
+}
+
 func bindCommonFlags(flags *flag.FlagSet) *commonOptions {
 	common := &commonOptions{}
 	flags.StringVar(&common.Endpoint, "endpoint", "localhost:5000", "gateway endpoint")
@@ -507,6 +627,21 @@ func writeCommandOutput(stdout io.Writer, jsonOutput bool, command string, optio
 	return nil
 }
 
+func writeBulkOutput(stdout io.Writer, jsonOutput bool, command string, options commonOptions, results []*mxgateway.SubscribeResult, err error) error {
+	if err != nil {
+		return err
+	}
+	if jsonOutput {
+		return writeJSON(stdout, map[string]any{
+			"command": command,
+			"options": options,
+			"results": results,
+		})
+	}
+	fmt.Fprintln(stdout, len(results))
+	return nil
+}
+
 func writeJSON(writer io.Writer, value any) error {
 	encoder := json.NewEncoder(writer)
 	encoder.SetIndent("", "  ")
@@ -526,5 +661,226 @@ type protojsonMessage interface {
 }
 
 func writeUsage(writer io.Writer) {
-	fmt.Fprintln(writer, "usage: mxgw-go <version|open-session|close-session|register|add-item|advise|write|stream-events|smoke>")
+	fmt.Fprintln(writer, "usage: mxgw-go <version|open-session|close-session|register|add-item|advise|subscribe-bulk|unsubscribe-bulk|write|stream-events|smoke|galaxy-test-connection|galaxy-last-deploy|galaxy-discover|galaxy-watch>")
+}
+
+func dialGalaxyForCommand(ctx context.Context, common *commonOptions) (*mxgateway.GalaxyClient, commonOptions, error) {
+	options, err := common.resolved()
+	if err != nil {
+		return nil, options, err
+	}
+
+	client, err := mxgateway.DialGalaxy(ctx, mxgateway.Options{
+		Endpoint:           options.Endpoint,
+		APIKey:             options.apiKeyValue,
+		Plaintext:          options.Plaintext,
+		CACertFile:         options.CACertFile,
+		ServerNameOverride: options.ServerName,
+		CallTimeout:        options.timeout,
+	})
+	return client, options, err
+}
+
+func runGalaxyTestConnection(ctx context.Context, args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("galaxy-test-connection", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	common := bindCommonFlags(flags)
+	jsonOutput := flags.Bool("json", false, "write JSON output")
+
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+
+	client, options, err := dialGalaxyForCommand(ctx, common)
+	if err != nil {
+		return err
+	}
+	defer client.Close()
+
+	ok, err := client.TestConnection(ctx)
+	if err != nil {
+		return err
+	}
+	if *jsonOutput {
+		return writeJSON(stdout, map[string]any{
+			"command": "galaxy-test-connection",
+			"options": options,
+			"ok":      ok,
+		})
+	}
+	fmt.Fprintln(stdout, ok)
+	return nil
+}
+
+func runGalaxyLastDeploy(ctx context.Context, args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("galaxy-last-deploy", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	common := bindCommonFlags(flags)
+	jsonOutput := flags.Bool("json", false, "write JSON output")
+
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+
+	client, options, err := dialGalaxyForCommand(ctx, common)
+	if err != nil {
+		return err
+	}
+	defer client.Close()
+
+	deployTime, present, err := client.GetLastDeployTime(ctx)
+	if err != nil {
+		return err
+	}
+	if *jsonOutput {
+		payload := map[string]any{
+			"command": "galaxy-last-deploy",
+			"options": options,
+			"present": present,
+		}
+		if present {
+			payload["timeOfLastDeploy"] = deployTime.UTC().Format(time.RFC3339Nano)
+		}
+		return writeJSON(stdout, payload)
+	}
+	if !present {
+		fmt.Fprintln(stdout, "absent")
+		return nil
+	}
+	fmt.Fprintln(stdout, deployTime.UTC().Format(time.RFC3339Nano))
+	return nil
+}
+
+func runGalaxyDiscover(ctx context.Context, args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("galaxy-discover", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	common := bindCommonFlags(flags)
+	jsonOutput := flags.Bool("json", false, "write JSON output")
+
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+
+	client, options, err := dialGalaxyForCommand(ctx, common)
+	if err != nil {
+		return err
+	}
+	defer client.Close()
+
+	objects, err := client.DiscoverHierarchy(ctx)
+	if err != nil {
+		return err
+	}
+	if *jsonOutput {
+		marshaled := make([]json.RawMessage, 0, len(objects))
+		for _, obj := range objects {
+			marshaled = append(marshaled, mustMarshalProto(obj))
+		}
+		return writeJSON(stdout, map[string]any{
+			"command": "galaxy-discover",
+			"options": options,
+			"objects": marshaled,
+		})
+	}
+	for _, obj := range objects {
+		fmt.Fprintf(stdout, "%d\t%s\t%s\t(attrs=%d)\n", obj.GetGobjectId(), obj.GetTagName(), obj.GetContainedName(), len(obj.GetAttributes()))
+	}
+	return nil
+}
+
+func runGalaxyWatch(ctx context.Context, args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("galaxy-watch", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	common := bindCommonFlags(flags)
+	jsonOutput := flags.Bool("json", false, "write JSON output")
+	lastSeen := flags.String("last-seen-deploy-time", "", "RFC3339 timestamp; when set, suppresses the bootstrap event")
+	limit := flags.Int("limit", 0, "maximum events to read; 0 means unbounded (Ctrl+C to stop)")
+
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+
+	var lastSeenPtr *time.Time
+	if *lastSeen != "" {
+		parsed, err := time.Parse(time.RFC3339, *lastSeen)
+		if err != nil {
+			return fmt.Errorf("invalid -last-seen-deploy-time: %w", err)
+		}
+		lastSeenPtr = &parsed
+	}
+
+	client, _, err := dialGalaxyForCommand(ctx, common)
+	if err != nil {
+		return err
+	}
+	defer client.Close()
+
+	signalCtx, stopSignals := signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)
+	defer stopSignals()
+
+	streamCtx, cancelStream := context.WithCancel(signalCtx)
+	defer cancelStream()
+
+	events, errs, err := client.WatchDeployEvents(streamCtx, lastSeenPtr)
+	if err != nil {
+		return err
+	}
+
+	count := 0
+	for {
+		select {
+		case event, ok := <-events:
+			if !ok {
+				// Drain any terminal error before returning.
+				if streamErr, errOk := <-errs; errOk && streamErr != nil {
+					return streamErr
+				}
+				return nil
+			}
+			if *jsonOutput {
+				fmt.Fprintln(stdout, string(mustMarshalProto(event)))
+			} else {
+				fmt.Fprintln(stdout, formatDeployEvent(event))
+			}
+			count++
+			if *limit > 0 && count >= *limit {
+				cancelStream()
+				return nil
+			}
+		case streamErr, ok := <-errs:
+			if !ok {
+				return nil
+			}
+			if streamErr != nil {
+				return streamErr
+			}
+		case <-signalCtx.Done():
+			cancelStream()
+			// Allow goroutine to drain.
+			for range events {
+			}
+			return nil
+		}
+	}
+}
+
+func formatDeployEvent(event *mxgateway.DeployEvent) string {
+	observed := ""
+	if ts := event.GetObservedAt(); ts != nil {
+		observed = ts.AsTime().UTC().Format(time.RFC3339Nano)
+	}
+	deploy := "absent"
+	if event.GetTimeOfLastDeployPresent() {
+		if ts := event.GetTimeOfLastDeploy(); ts != nil {
+			deploy = ts.AsTime().UTC().Format(time.RFC3339Nano)
+		}
+	}
+	return fmt.Sprintf(
+		"seq=%d observed=%s deploy=%s objects=%d attributes=%d",
+		event.GetSequence(),
+		observed,
+		deploy,
+		event.GetObjectCount(),
+		event.GetAttributeCount(),
+	)
 }

clients/go/generate-proto.ps1

@@ -30,13 +30,17 @@ $env:Path = "$goPluginPath;$env:Path"
     --go_opt=paths=source_relative `
     "--go_opt=Mmxaccess_gateway.proto=$modulePath;generated" `
     "--go_opt=Mmxaccess_worker.proto=$modulePath;generated" `
+    "--go_opt=Mgalaxy_repository.proto=$modulePath;generated" `
     mxaccess_gateway.proto `
-    mxaccess_worker.proto
+    mxaccess_worker.proto `
+    galaxy_repository.proto
 
 & $protoc `
     --proto_path=$protoRoot `
     --go-grpc_out=$outputRoot `
     --go-grpc_opt=paths=source_relative `
     "--go-grpc_opt=Mmxaccess_gateway.proto=$modulePath;generated" `
-    mxaccess_gateway.proto
+    "--go-grpc_opt=Mgalaxy_repository.proto=$modulePath;generated" `
+    mxaccess_gateway.proto `
+    galaxy_repository.proto
 

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

@@ -0,0 +1,970 @@
+// Code generated by protoc-gen-go. DO NOT EDIT.
+// versions:
+// 	protoc-gen-go v1.36.11
+// 	protoc        v7.34.1
+// source: galaxy_repository.proto
+
+package generated
+
+import (
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
+	timestamppb "google.golang.org/protobuf/types/known/timestamppb"
+	wrapperspb "google.golang.org/protobuf/types/known/wrapperspb"
+	reflect "reflect"
+	sync "sync"
+	unsafe "unsafe"
+)
+
+const (
+	// Verify that this generated code is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion)
+	// Verify that runtime/protoimpl is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
+)
+
+type TestConnectionRequest struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *TestConnectionRequest) Reset() {
+	*x = TestConnectionRequest{}
+	mi := &file_galaxy_repository_proto_msgTypes[0]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *TestConnectionRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*TestConnectionRequest) ProtoMessage() {}
+
+func (x *TestConnectionRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_galaxy_repository_proto_msgTypes[0]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use TestConnectionRequest.ProtoReflect.Descriptor instead.
+func (*TestConnectionRequest) Descriptor() ([]byte, []int) {
+	return file_galaxy_repository_proto_rawDescGZIP(), []int{0}
+}
+
+type TestConnectionReply struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Ok            bool                   `protobuf:"varint,1,opt,name=ok,proto3" json:"ok,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *TestConnectionReply) Reset() {
+	*x = TestConnectionReply{}
+	mi := &file_galaxy_repository_proto_msgTypes[1]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *TestConnectionReply) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*TestConnectionReply) ProtoMessage() {}
+
+func (x *TestConnectionReply) ProtoReflect() protoreflect.Message {
+	mi := &file_galaxy_repository_proto_msgTypes[1]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use TestConnectionReply.ProtoReflect.Descriptor instead.
+func (*TestConnectionReply) Descriptor() ([]byte, []int) {
+	return file_galaxy_repository_proto_rawDescGZIP(), []int{1}
+}
+
+func (x *TestConnectionReply) GetOk() bool {
+	if x != nil {
+		return x.Ok
+	}
+	return false
+}
+
+type GetLastDeployTimeRequest struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *GetLastDeployTimeRequest) Reset() {
+	*x = GetLastDeployTimeRequest{}
+	mi := &file_galaxy_repository_proto_msgTypes[2]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *GetLastDeployTimeRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*GetLastDeployTimeRequest) ProtoMessage() {}
+
+func (x *GetLastDeployTimeRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_galaxy_repository_proto_msgTypes[2]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use GetLastDeployTimeRequest.ProtoReflect.Descriptor instead.
+func (*GetLastDeployTimeRequest) Descriptor() ([]byte, []int) {
+	return file_galaxy_repository_proto_rawDescGZIP(), []int{2}
+}
+
+type GetLastDeployTimeReply struct {
+	state            protoimpl.MessageState `protogen:"open.v1"`
+	Present          bool                   `protobuf:"varint,1,opt,name=present,proto3" json:"present,omitempty"`
+	TimeOfLastDeploy *timestamppb.Timestamp `protobuf:"bytes,2,opt,name=time_of_last_deploy,json=timeOfLastDeploy,proto3" json:"time_of_last_deploy,omitempty"`
+	unknownFields    protoimpl.UnknownFields
+	sizeCache        protoimpl.SizeCache
+}
+
+func (x *GetLastDeployTimeReply) Reset() {
+	*x = GetLastDeployTimeReply{}
+	mi := &file_galaxy_repository_proto_msgTypes[3]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *GetLastDeployTimeReply) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*GetLastDeployTimeReply) ProtoMessage() {}
+
+func (x *GetLastDeployTimeReply) ProtoReflect() protoreflect.Message {
+	mi := &file_galaxy_repository_proto_msgTypes[3]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use GetLastDeployTimeReply.ProtoReflect.Descriptor instead.
+func (*GetLastDeployTimeReply) Descriptor() ([]byte, []int) {
+	return file_galaxy_repository_proto_rawDescGZIP(), []int{3}
+}
+
+func (x *GetLastDeployTimeReply) GetPresent() bool {
+	if x != nil {
+		return x.Present
+	}
+	return false
+}
+
+func (x *GetLastDeployTimeReply) GetTimeOfLastDeploy() *timestamppb.Timestamp {
+	if x != nil {
+		return x.TimeOfLastDeploy
+	}
+	return nil
+}
+
+type DiscoverHierarchyRequest struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Maximum number of objects to return. The server applies its default when
+	// unset and rejects non-positive values.
+	PageSize int32 `protobuf:"varint,1,opt,name=page_size,json=pageSize,proto3" json:"page_size,omitempty"`
+	// Opaque token returned by a previous DiscoverHierarchy response.
+	PageToken string `protobuf:"bytes,2,opt,name=page_token,json=pageToken,proto3" json:"page_token,omitempty"`
+	// Optional. When set, return only this object and its descendants.
+	// Empty = full hierarchy.
+	//
+	// Types that are valid to be assigned to Root:
+	//
+	//	*DiscoverHierarchyRequest_RootGobjectId
+	//	*DiscoverHierarchyRequest_RootTagName
+	//	*DiscoverHierarchyRequest_RootContainedPath
+	Root isDiscoverHierarchyRequest_Root `protobuf_oneof:"root"`
+	// Optional. Cap on descendant depth from root. Zero returns only the root.
+	// Unset means unlimited depth.
+	MaxDepth *wrapperspb.Int32Value `protobuf:"bytes,6,opt,name=max_depth,json=maxDepth,proto3" json:"max_depth,omitempty"`
+	// Optional object category id filters.
+	CategoryIds []int32 `protobuf:"varint,7,rep,packed,name=category_ids,json=categoryIds,proto3" json:"category_ids,omitempty"`
+	// Optional case-insensitive substring filters against template names.
+	TemplateChainContains []string `protobuf:"bytes,8,rep,name=template_chain_contains,json=templateChainContains,proto3" json:"template_chain_contains,omitempty"`
+	// Optional anchored, case-insensitive glob over object tag_name.
+	TagNameGlob string `protobuf:"bytes,9,opt,name=tag_name_glob,json=tagNameGlob,proto3" json:"tag_name_glob,omitempty"`
+	// Optional. Unset or true includes attributes. False returns object skeletons.
+	IncludeAttributes *bool `protobuf:"varint,10,opt,name=include_attributes,json=includeAttributes,proto3,oneof" json:"include_attributes,omitempty"`
+	// Optional. Return only objects with at least one alarm-bearing attribute.
+	AlarmBearingOnly bool `protobuf:"varint,11,opt,name=alarm_bearing_only,json=alarmBearingOnly,proto3" json:"alarm_bearing_only,omitempty"`
+	// Optional. Return only objects with at least one historized attribute.
+	HistorizedOnly bool `protobuf:"varint,12,opt,name=historized_only,json=historizedOnly,proto3" json:"historized_only,omitempty"`
+	unknownFields  protoimpl.UnknownFields
+	sizeCache      protoimpl.SizeCache
+}
+
+func (x *DiscoverHierarchyRequest) Reset() {
+	*x = DiscoverHierarchyRequest{}
+	mi := &file_galaxy_repository_proto_msgTypes[4]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *DiscoverHierarchyRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*DiscoverHierarchyRequest) ProtoMessage() {}
+
+func (x *DiscoverHierarchyRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_galaxy_repository_proto_msgTypes[4]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use DiscoverHierarchyRequest.ProtoReflect.Descriptor instead.
+func (*DiscoverHierarchyRequest) Descriptor() ([]byte, []int) {
+	return file_galaxy_repository_proto_rawDescGZIP(), []int{4}
+}
+
+func (x *DiscoverHierarchyRequest) GetPageSize() int32 {
+	if x != nil {
+		return x.PageSize
+	}
+	return 0
+}
+
+func (x *DiscoverHierarchyRequest) GetPageToken() string {
+	if x != nil {
+		return x.PageToken
+	}
+	return ""
+}
+
+func (x *DiscoverHierarchyRequest) GetRoot() isDiscoverHierarchyRequest_Root {
+	if x != nil {
+		return x.Root
+	}
+	return nil
+}
+
+func (x *DiscoverHierarchyRequest) GetRootGobjectId() int32 {
+	if x != nil {
+		if x, ok := x.Root.(*DiscoverHierarchyRequest_RootGobjectId); ok {
+			return x.RootGobjectId
+		}
+	}
+	return 0
+}
+
+func (x *DiscoverHierarchyRequest) GetRootTagName() string {
+	if x != nil {
+		if x, ok := x.Root.(*DiscoverHierarchyRequest_RootTagName); ok {
+			return x.RootTagName
+		}
+	}
+	return ""
+}
+
+func (x *DiscoverHierarchyRequest) GetRootContainedPath() string {
+	if x != nil {
+		if x, ok := x.Root.(*DiscoverHierarchyRequest_RootContainedPath); ok {
+			return x.RootContainedPath
+		}
+	}
+	return ""
+}
+
+func (x *DiscoverHierarchyRequest) GetMaxDepth() *wrapperspb.Int32Value {
+	if x != nil {
+		return x.MaxDepth
+	}
+	return nil
+}
+
+func (x *DiscoverHierarchyRequest) GetCategoryIds() []int32 {
+	if x != nil {
+		return x.CategoryIds
+	}
+	return nil
+}
+
+func (x *DiscoverHierarchyRequest) GetTemplateChainContains() []string {
+	if x != nil {
+		return x.TemplateChainContains
+	}
+	return nil
+}
+
+func (x *DiscoverHierarchyRequest) GetTagNameGlob() string {
+	if x != nil {
+		return x.TagNameGlob
+	}
+	return ""
+}
+
+func (x *DiscoverHierarchyRequest) GetIncludeAttributes() bool {
+	if x != nil && x.IncludeAttributes != nil {
+		return *x.IncludeAttributes
+	}
+	return false
+}
+
+func (x *DiscoverHierarchyRequest) GetAlarmBearingOnly() bool {
+	if x != nil {
+		return x.AlarmBearingOnly
+	}
+	return false
+}
+
+func (x *DiscoverHierarchyRequest) GetHistorizedOnly() bool {
+	if x != nil {
+		return x.HistorizedOnly
+	}
+	return false
+}
+
+type isDiscoverHierarchyRequest_Root interface {
+	isDiscoverHierarchyRequest_Root()
+}
+
+type DiscoverHierarchyRequest_RootGobjectId struct {
+	RootGobjectId int32 `protobuf:"varint,3,opt,name=root_gobject_id,json=rootGobjectId,proto3,oneof"`
+}
+
+type DiscoverHierarchyRequest_RootTagName struct {
+	RootTagName string `protobuf:"bytes,4,opt,name=root_tag_name,json=rootTagName,proto3,oneof"`
+}
+
+type DiscoverHierarchyRequest_RootContainedPath struct {
+	RootContainedPath string `protobuf:"bytes,5,opt,name=root_contained_path,json=rootContainedPath,proto3,oneof"`
+}
+
+func (*DiscoverHierarchyRequest_RootGobjectId) isDiscoverHierarchyRequest_Root() {}
+
+func (*DiscoverHierarchyRequest_RootTagName) isDiscoverHierarchyRequest_Root() {}
+
+func (*DiscoverHierarchyRequest_RootContainedPath) isDiscoverHierarchyRequest_Root() {}
+
+type DiscoverHierarchyReply struct {
+	state   protoimpl.MessageState `protogen:"open.v1"`
+	Objects []*GalaxyObject        `protobuf:"bytes,1,rep,name=objects,proto3" json:"objects,omitempty"`
+	// Non-empty when another page is available.
+	NextPageToken string `protobuf:"bytes,2,opt,name=next_page_token,json=nextPageToken,proto3" json:"next_page_token,omitempty"`
+	// Total number of objects in the cached hierarchy at the time of the call.
+	TotalObjectCount int32 `protobuf:"varint,3,opt,name=total_object_count,json=totalObjectCount,proto3" json:"total_object_count,omitempty"`
+	unknownFields    protoimpl.UnknownFields
+	sizeCache        protoimpl.SizeCache
+}
+
+func (x *DiscoverHierarchyReply) Reset() {
+	*x = DiscoverHierarchyReply{}
+	mi := &file_galaxy_repository_proto_msgTypes[5]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *DiscoverHierarchyReply) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*DiscoverHierarchyReply) ProtoMessage() {}
+
+func (x *DiscoverHierarchyReply) ProtoReflect() protoreflect.Message {
+	mi := &file_galaxy_repository_proto_msgTypes[5]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use DiscoverHierarchyReply.ProtoReflect.Descriptor instead.
+func (*DiscoverHierarchyReply) Descriptor() ([]byte, []int) {
+	return file_galaxy_repository_proto_rawDescGZIP(), []int{5}
+}
+
+func (x *DiscoverHierarchyReply) GetObjects() []*GalaxyObject {
+	if x != nil {
+		return x.Objects
+	}
+	return nil
+}
+
+func (x *DiscoverHierarchyReply) GetNextPageToken() string {
+	if x != nil {
+		return x.NextPageToken
+	}
+	return ""
+}
+
+func (x *DiscoverHierarchyReply) GetTotalObjectCount() int32 {
+	if x != nil {
+		return x.TotalObjectCount
+	}
+	return 0
+}
+
+type WatchDeployEventsRequest struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Optional. When set, the bootstrap event is suppressed if the cached deploy
+	// time matches this value. Future events are still emitted normally.
+	LastSeenDeployTime *timestamppb.Timestamp `protobuf:"bytes,1,opt,name=last_seen_deploy_time,json=lastSeenDeployTime,proto3" json:"last_seen_deploy_time,omitempty"`
+	unknownFields      protoimpl.UnknownFields
+	sizeCache          protoimpl.SizeCache
+}
+
+func (x *WatchDeployEventsRequest) Reset() {
+	*x = WatchDeployEventsRequest{}
+	mi := &file_galaxy_repository_proto_msgTypes[6]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *WatchDeployEventsRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*WatchDeployEventsRequest) ProtoMessage() {}
+
+func (x *WatchDeployEventsRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_galaxy_repository_proto_msgTypes[6]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use WatchDeployEventsRequest.ProtoReflect.Descriptor instead.
+func (*WatchDeployEventsRequest) Descriptor() ([]byte, []int) {
+	return file_galaxy_repository_proto_rawDescGZIP(), []int{6}
+}
+
+func (x *WatchDeployEventsRequest) GetLastSeenDeployTime() *timestamppb.Timestamp {
+	if x != nil {
+		return x.LastSeenDeployTime
+	}
+	return nil
+}
+
+type DeployEvent struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Monotonically increasing per server start. Gaps indicate dropped events.
+	Sequence uint64 `protobuf:"varint,1,opt,name=sequence,proto3" json:"sequence,omitempty"`
+	// Server wall-clock when the cache observed the deploy.
+	ObservedAt *timestamppb.Timestamp `protobuf:"bytes,2,opt,name=observed_at,json=observedAt,proto3" json:"observed_at,omitempty"`
+	// Galaxy.time_of_last_deploy. Absent only when the Galaxy table reports null.
+	TimeOfLastDeploy        *timestamppb.Timestamp `protobuf:"bytes,3,opt,name=time_of_last_deploy,json=timeOfLastDeploy,proto3" json:"time_of_last_deploy,omitempty"`
+	TimeOfLastDeployPresent bool                   `protobuf:"varint,4,opt,name=time_of_last_deploy_present,json=timeOfLastDeployPresent,proto3" json:"time_of_last_deploy_present,omitempty"`
+	ObjectCount             int32                  `protobuf:"varint,5,opt,name=object_count,json=objectCount,proto3" json:"object_count,omitempty"`
+	AttributeCount          int32                  `protobuf:"varint,6,opt,name=attribute_count,json=attributeCount,proto3" json:"attribute_count,omitempty"`
+	unknownFields           protoimpl.UnknownFields
+	sizeCache               protoimpl.SizeCache
+}
+
+func (x *DeployEvent) Reset() {
+	*x = DeployEvent{}
+	mi := &file_galaxy_repository_proto_msgTypes[7]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *DeployEvent) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*DeployEvent) ProtoMessage() {}
+
+func (x *DeployEvent) ProtoReflect() protoreflect.Message {
+	mi := &file_galaxy_repository_proto_msgTypes[7]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use DeployEvent.ProtoReflect.Descriptor instead.
+func (*DeployEvent) Descriptor() ([]byte, []int) {
+	return file_galaxy_repository_proto_rawDescGZIP(), []int{7}
+}
+
+func (x *DeployEvent) GetSequence() uint64 {
+	if x != nil {
+		return x.Sequence
+	}
+	return 0
+}
+
+func (x *DeployEvent) GetObservedAt() *timestamppb.Timestamp {
+	if x != nil {
+		return x.ObservedAt
+	}
+	return nil
+}
+
+func (x *DeployEvent) GetTimeOfLastDeploy() *timestamppb.Timestamp {
+	if x != nil {
+		return x.TimeOfLastDeploy
+	}
+	return nil
+}
+
+func (x *DeployEvent) GetTimeOfLastDeployPresent() bool {
+	if x != nil {
+		return x.TimeOfLastDeployPresent
+	}
+	return false
+}
+
+func (x *DeployEvent) GetObjectCount() int32 {
+	if x != nil {
+		return x.ObjectCount
+	}
+	return 0
+}
+
+func (x *DeployEvent) GetAttributeCount() int32 {
+	if x != nil {
+		return x.AttributeCount
+	}
+	return 0
+}
+
+type GalaxyObject struct {
+	state             protoimpl.MessageState `protogen:"open.v1"`
+	GobjectId         int32                  `protobuf:"varint,1,opt,name=gobject_id,json=gobjectId,proto3" json:"gobject_id,omitempty"`
+	TagName           string                 `protobuf:"bytes,2,opt,name=tag_name,json=tagName,proto3" json:"tag_name,omitempty"`
+	ContainedName     string                 `protobuf:"bytes,3,opt,name=contained_name,json=containedName,proto3" json:"contained_name,omitempty"`
+	BrowseName        string                 `protobuf:"bytes,4,opt,name=browse_name,json=browseName,proto3" json:"browse_name,omitempty"`
+	ParentGobjectId   int32                  `protobuf:"varint,5,opt,name=parent_gobject_id,json=parentGobjectId,proto3" json:"parent_gobject_id,omitempty"`
+	IsArea            bool                   `protobuf:"varint,6,opt,name=is_area,json=isArea,proto3" json:"is_area,omitempty"`
+	CategoryId        int32                  `protobuf:"varint,7,opt,name=category_id,json=categoryId,proto3" json:"category_id,omitempty"`
+	HostedByGobjectId int32                  `protobuf:"varint,8,opt,name=hosted_by_gobject_id,json=hostedByGobjectId,proto3" json:"hosted_by_gobject_id,omitempty"`
+	TemplateChain     []string               `protobuf:"bytes,9,rep,name=template_chain,json=templateChain,proto3" json:"template_chain,omitempty"`
+	Attributes        []*GalaxyAttribute     `protobuf:"bytes,10,rep,name=attributes,proto3" json:"attributes,omitempty"`
+	unknownFields     protoimpl.UnknownFields
+	sizeCache         protoimpl.SizeCache
+}
+
+func (x *GalaxyObject) Reset() {
+	*x = GalaxyObject{}
+	mi := &file_galaxy_repository_proto_msgTypes[8]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *GalaxyObject) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*GalaxyObject) ProtoMessage() {}
+
+func (x *GalaxyObject) ProtoReflect() protoreflect.Message {
+	mi := &file_galaxy_repository_proto_msgTypes[8]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use GalaxyObject.ProtoReflect.Descriptor instead.
+func (*GalaxyObject) Descriptor() ([]byte, []int) {
+	return file_galaxy_repository_proto_rawDescGZIP(), []int{8}
+}
+
+func (x *GalaxyObject) GetGobjectId() int32 {
+	if x != nil {
+		return x.GobjectId
+	}
+	return 0
+}
+
+func (x *GalaxyObject) GetTagName() string {
+	if x != nil {
+		return x.TagName
+	}
+	return ""
+}
+
+func (x *GalaxyObject) GetContainedName() string {
+	if x != nil {
+		return x.ContainedName
+	}
+	return ""
+}
+
+func (x *GalaxyObject) GetBrowseName() string {
+	if x != nil {
+		return x.BrowseName
+	}
+	return ""
+}
+
+func (x *GalaxyObject) GetParentGobjectId() int32 {
+	if x != nil {
+		return x.ParentGobjectId
+	}
+	return 0
+}
+
+func (x *GalaxyObject) GetIsArea() bool {
+	if x != nil {
+		return x.IsArea
+	}
+	return false
+}
+
+func (x *GalaxyObject) GetCategoryId() int32 {
+	if x != nil {
+		return x.CategoryId
+	}
+	return 0
+}
+
+func (x *GalaxyObject) GetHostedByGobjectId() int32 {
+	if x != nil {
+		return x.HostedByGobjectId
+	}
+	return 0
+}
+
+func (x *GalaxyObject) GetTemplateChain() []string {
+	if x != nil {
+		return x.TemplateChain
+	}
+	return nil
+}
+
+func (x *GalaxyObject) GetAttributes() []*GalaxyAttribute {
+	if x != nil {
+		return x.Attributes
+	}
+	return nil
+}
+
+type GalaxyAttribute struct {
+	state                  protoimpl.MessageState `protogen:"open.v1"`
+	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"`
+	MxDataType             int32                  `protobuf:"varint,3,opt,name=mx_data_type,json=mxDataType,proto3" json:"mx_data_type,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"`
+	MxAttributeCategory    int32                  `protobuf:"varint,8,opt,name=mx_attribute_category,json=mxAttributeCategory,proto3" json:"mx_attribute_category,omitempty"`
+	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
+}
+
+func (x *GalaxyAttribute) Reset() {
+	*x = GalaxyAttribute{}
+	mi := &file_galaxy_repository_proto_msgTypes[9]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *GalaxyAttribute) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*GalaxyAttribute) ProtoMessage() {}
+
+func (x *GalaxyAttribute) ProtoReflect() protoreflect.Message {
+	mi := &file_galaxy_repository_proto_msgTypes[9]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use GalaxyAttribute.ProtoReflect.Descriptor instead.
+func (*GalaxyAttribute) Descriptor() ([]byte, []int) {
+	return file_galaxy_repository_proto_rawDescGZIP(), []int{9}
+}
+
+func (x *GalaxyAttribute) GetAttributeName() string {
+	if x != nil {
+		return x.AttributeName
+	}
+	return ""
+}
+
+func (x *GalaxyAttribute) GetFullTagReference() string {
+	if x != nil {
+		return x.FullTagReference
+	}
+	return ""
+}
+
+func (x *GalaxyAttribute) GetMxDataType() int32 {
+	if x != nil {
+		return x.MxDataType
+	}
+	return 0
+}
+
+func (x *GalaxyAttribute) GetDataTypeName() string {
+	if x != nil {
+		return x.DataTypeName
+	}
+	return ""
+}
+
+func (x *GalaxyAttribute) GetIsArray() bool {
+	if x != nil {
+		return x.IsArray
+	}
+	return false
+}
+
+func (x *GalaxyAttribute) GetArrayDimension() int32 {
+	if x != nil {
+		return x.ArrayDimension
+	}
+	return 0
+}
+
+func (x *GalaxyAttribute) GetArrayDimensionPresent() bool {
+	if x != nil {
+		return x.ArrayDimensionPresent
+	}
+	return false
+}
+
+func (x *GalaxyAttribute) GetMxAttributeCategory() int32 {
+	if x != nil {
+		return x.MxAttributeCategory
+	}
+	return 0
+}
+
+func (x *GalaxyAttribute) GetSecurityClassification() int32 {
+	if x != nil {
+		return x.SecurityClassification
+	}
+	return 0
+}
+
+func (x *GalaxyAttribute) GetIsHistorized() bool {
+	if x != nil {
+		return x.IsHistorized
+	}
+	return false
+}
+
+func (x *GalaxyAttribute) GetIsAlarm() bool {
+	if x != nil {
+		return x.IsAlarm
+	}
+	return false
+}
+
+var File_galaxy_repository_proto protoreflect.FileDescriptor
+
+const file_galaxy_repository_proto_rawDesc = "" +
+	"\n" +
+	"\x17galaxy_repository.proto\x12\x14galaxy_repository.v1\x1a\x1fgoogle/protobuf/timestamp.proto\x1a\x1egoogle/protobuf/wrappers.proto\"\x17\n" +
+	"\x15TestConnectionRequest\"%\n" +
+	"\x13TestConnectionReply\x12\x0e\n" +
+	"\x02ok\x18\x01 \x01(\bR\x02ok\"\x1a\n" +
+	"\x18GetLastDeployTimeRequest\"}\n" +
+	"\x16GetLastDeployTimeReply\x12\x18\n" +
+	"\apresent\x18\x01 \x01(\bR\apresent\x12I\n" +
+	"\x13time_of_last_deploy\x18\x02 \x01(\v2\x1a.google.protobuf.TimestampR\x10timeOfLastDeploy\"\xbb\x04\n" +
+	"\x18DiscoverHierarchyRequest\x12\x1b\n" +
+	"\tpage_size\x18\x01 \x01(\x05R\bpageSize\x12\x1d\n" +
+	"\n" +
+	"page_token\x18\x02 \x01(\tR\tpageToken\x12(\n" +
+	"\x0froot_gobject_id\x18\x03 \x01(\x05H\x00R\rrootGobjectId\x12$\n" +
+	"\rroot_tag_name\x18\x04 \x01(\tH\x00R\vrootTagName\x120\n" +
+	"\x13root_contained_path\x18\x05 \x01(\tH\x00R\x11rootContainedPath\x128\n" +
+	"\tmax_depth\x18\x06 \x01(\v2\x1b.google.protobuf.Int32ValueR\bmaxDepth\x12!\n" +
+	"\fcategory_ids\x18\a \x03(\x05R\vcategoryIds\x126\n" +
+	"\x17template_chain_contains\x18\b \x03(\tR\x15templateChainContains\x12\"\n" +
+	"\rtag_name_glob\x18\t \x01(\tR\vtagNameGlob\x122\n" +
+	"\x12include_attributes\x18\n" +
+	" \x01(\bH\x01R\x11includeAttributes\x88\x01\x01\x12,\n" +
+	"\x12alarm_bearing_only\x18\v \x01(\bR\x10alarmBearingOnly\x12'\n" +
+	"\x0fhistorized_only\x18\f \x01(\bR\x0ehistorizedOnlyB\x06\n" +
+	"\x04rootB\x15\n" +
+	"\x13_include_attributes\"\xac\x01\n" +
+	"\x16DiscoverHierarchyReply\x12<\n" +
+	"\aobjects\x18\x01 \x03(\v2\".galaxy_repository.v1.GalaxyObjectR\aobjects\x12&\n" +
+	"\x0fnext_page_token\x18\x02 \x01(\tR\rnextPageToken\x12,\n" +
+	"\x12total_object_count\x18\x03 \x01(\x05R\x10totalObjectCount\"i\n" +
+	"\x18WatchDeployEventsRequest\x12M\n" +
+	"\x15last_seen_deploy_time\x18\x01 \x01(\v2\x1a.google.protobuf.TimestampR\x12lastSeenDeployTime\"\xbb\x02\n" +
+	"\vDeployEvent\x12\x1a\n" +
+	"\bsequence\x18\x01 \x01(\x04R\bsequence\x12;\n" +
+	"\vobserved_at\x18\x02 \x01(\v2\x1a.google.protobuf.TimestampR\n" +
+	"observedAt\x12I\n" +
+	"\x13time_of_last_deploy\x18\x03 \x01(\v2\x1a.google.protobuf.TimestampR\x10timeOfLastDeploy\x12<\n" +
+	"\x1btime_of_last_deploy_present\x18\x04 \x01(\bR\x17timeOfLastDeployPresent\x12!\n" +
+	"\fobject_count\x18\x05 \x01(\x05R\vobjectCount\x12'\n" +
+	"\x0fattribute_count\x18\x06 \x01(\x05R\x0eattributeCount\"\x95\x03\n" +
+	"\fGalaxyObject\x12\x1d\n" +
+	"\n" +
+	"gobject_id\x18\x01 \x01(\x05R\tgobjectId\x12\x19\n" +
+	"\btag_name\x18\x02 \x01(\tR\atagName\x12%\n" +
+	"\x0econtained_name\x18\x03 \x01(\tR\rcontainedName\x12\x1f\n" +
+	"\vbrowse_name\x18\x04 \x01(\tR\n" +
+	"browseName\x12*\n" +
+	"\x11parent_gobject_id\x18\x05 \x01(\x05R\x0fparentGobjectId\x12\x17\n" +
+	"\ais_area\x18\x06 \x01(\bR\x06isArea\x12\x1f\n" +
+	"\vcategory_id\x18\a \x01(\x05R\n" +
+	"categoryId\x12/\n" +
+	"\x14hosted_by_gobject_id\x18\b \x01(\x05R\x11hostedByGobjectId\x12%\n" +
+	"\x0etemplate_chain\x18\t \x03(\tR\rtemplateChain\x12E\n" +
+	"\n" +
+	"attributes\x18\n" +
+	" \x03(\v2%.galaxy_repository.v1.GalaxyAttributeR\n" +
+	"attributes\"\xd7\x03\n" +
+	"\x0fGalaxyAttribute\x12%\n" +
+	"\x0eattribute_name\x18\x01 \x01(\tR\rattributeName\x12,\n" +
+	"\x12full_tag_reference\x18\x02 \x01(\tR\x10fullTagReference\x12 \n" +
+	"\fmx_data_type\x18\x03 \x01(\x05R\n" +
+	"mxDataType\x12$\n" +
+	"\x0edata_type_name\x18\x04 \x01(\tR\fdataTypeName\x12\x19\n" +
+	"\bis_array\x18\x05 \x01(\bR\aisArray\x12'\n" +
+	"\x0farray_dimension\x18\x06 \x01(\x05R\x0earrayDimension\x126\n" +
+	"\x17array_dimension_present\x18\a \x01(\bR\x15arrayDimensionPresent\x122\n" +
+	"\x15mx_attribute_category\x18\b \x01(\x05R\x13mxAttributeCategory\x127\n" +
+	"\x17security_classification\x18\t \x01(\x05R\x16securityClassification\x12#\n" +
+	"\ris_historized\x18\n" +
+	" \x01(\bR\fisHistorized\x12\x19\n" +
+	"\bis_alarm\x18\v \x01(\bR\aisAlarm2\xcc\x03\n" +
+	"\x10GalaxyRepository\x12h\n" +
+	"\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 MxGateway.Contracts.Proto.Galaxyb\x06proto3"
+
+var (
+	file_galaxy_repository_proto_rawDescOnce sync.Once
+	file_galaxy_repository_proto_rawDescData []byte
+)
+
+func file_galaxy_repository_proto_rawDescGZIP() []byte {
+	file_galaxy_repository_proto_rawDescOnce.Do(func() {
+		file_galaxy_repository_proto_rawDescData = protoimpl.X.CompressGZIP(unsafe.Slice(unsafe.StringData(file_galaxy_repository_proto_rawDesc), len(file_galaxy_repository_proto_rawDesc)))
+	})
+	return file_galaxy_repository_proto_rawDescData
+}
+
+var file_galaxy_repository_proto_msgTypes = make([]protoimpl.MessageInfo, 10)
+var file_galaxy_repository_proto_goTypes = []any{
+	(*TestConnectionRequest)(nil),    // 0: galaxy_repository.v1.TestConnectionRequest
+	(*TestConnectionReply)(nil),      // 1: galaxy_repository.v1.TestConnectionReply
+	(*GetLastDeployTimeRequest)(nil), // 2: galaxy_repository.v1.GetLastDeployTimeRequest
+	(*GetLastDeployTimeReply)(nil),   // 3: galaxy_repository.v1.GetLastDeployTimeReply
+	(*DiscoverHierarchyRequest)(nil), // 4: galaxy_repository.v1.DiscoverHierarchyRequest
+	(*DiscoverHierarchyReply)(nil),   // 5: galaxy_repository.v1.DiscoverHierarchyReply
+	(*WatchDeployEventsRequest)(nil), // 6: galaxy_repository.v1.WatchDeployEventsRequest
+	(*DeployEvent)(nil),              // 7: galaxy_repository.v1.DeployEvent
+	(*GalaxyObject)(nil),             // 8: galaxy_repository.v1.GalaxyObject
+	(*GalaxyAttribute)(nil),          // 9: galaxy_repository.v1.GalaxyAttribute
+	(*timestamppb.Timestamp)(nil),    // 10: google.protobuf.Timestamp
+	(*wrapperspb.Int32Value)(nil),    // 11: google.protobuf.Int32Value
+}
+var file_galaxy_repository_proto_depIdxs = []int32{
+	10, // 0: galaxy_repository.v1.GetLastDeployTimeReply.time_of_last_deploy:type_name -> google.protobuf.Timestamp
+	11, // 1: galaxy_repository.v1.DiscoverHierarchyRequest.max_depth:type_name -> google.protobuf.Int32Value
+	8,  // 2: galaxy_repository.v1.DiscoverHierarchyReply.objects:type_name -> galaxy_repository.v1.GalaxyObject
+	10, // 3: galaxy_repository.v1.WatchDeployEventsRequest.last_seen_deploy_time:type_name -> google.protobuf.Timestamp
+	10, // 4: galaxy_repository.v1.DeployEvent.observed_at:type_name -> google.protobuf.Timestamp
+	10, // 5: galaxy_repository.v1.DeployEvent.time_of_last_deploy:type_name -> google.protobuf.Timestamp
+	9,  // 6: galaxy_repository.v1.GalaxyObject.attributes:type_name -> galaxy_repository.v1.GalaxyAttribute
+	0,  // 7: galaxy_repository.v1.GalaxyRepository.TestConnection:input_type -> galaxy_repository.v1.TestConnectionRequest
+	2,  // 8: galaxy_repository.v1.GalaxyRepository.GetLastDeployTime:input_type -> galaxy_repository.v1.GetLastDeployTimeRequest
+	4,  // 9: galaxy_repository.v1.GalaxyRepository.DiscoverHierarchy:input_type -> galaxy_repository.v1.DiscoverHierarchyRequest
+	6,  // 10: galaxy_repository.v1.GalaxyRepository.WatchDeployEvents:input_type -> galaxy_repository.v1.WatchDeployEventsRequest
+	1,  // 11: galaxy_repository.v1.GalaxyRepository.TestConnection:output_type -> galaxy_repository.v1.TestConnectionReply
+	3,  // 12: galaxy_repository.v1.GalaxyRepository.GetLastDeployTime:output_type -> galaxy_repository.v1.GetLastDeployTimeReply
+	5,  // 13: galaxy_repository.v1.GalaxyRepository.DiscoverHierarchy:output_type -> galaxy_repository.v1.DiscoverHierarchyReply
+	7,  // 14: galaxy_repository.v1.GalaxyRepository.WatchDeployEvents:output_type -> galaxy_repository.v1.DeployEvent
+	11, // [11:15] is the sub-list for method output_type
+	7,  // [7:11] is the sub-list for method input_type
+	7,  // [7:7] is the sub-list for extension type_name
+	7,  // [7:7] is the sub-list for extension extendee
+	0,  // [0:7] is the sub-list for field type_name
+}
+
+func init() { file_galaxy_repository_proto_init() }
+func file_galaxy_repository_proto_init() {
+	if File_galaxy_repository_proto != nil {
+		return
+	}
+	file_galaxy_repository_proto_msgTypes[4].OneofWrappers = []any{
+		(*DiscoverHierarchyRequest_RootGobjectId)(nil),
+		(*DiscoverHierarchyRequest_RootTagName)(nil),
+		(*DiscoverHierarchyRequest_RootContainedPath)(nil),
+	}
+	type x struct{}
+	out := protoimpl.TypeBuilder{
+		File: protoimpl.DescBuilder{
+			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
+			RawDescriptor: unsafe.Slice(unsafe.StringData(file_galaxy_repository_proto_rawDesc), len(file_galaxy_repository_proto_rawDesc)),
+			NumEnums:      0,
+			NumMessages:   10,
+			NumExtensions: 0,
+			NumServices:   1,
+		},
+		GoTypes:           file_galaxy_repository_proto_goTypes,
+		DependencyIndexes: file_galaxy_repository_proto_depIdxs,
+		MessageInfos:      file_galaxy_repository_proto_msgTypes,
+	}.Build()
+	File_galaxy_repository_proto = out.File
+	file_galaxy_repository_proto_goTypes = nil
+	file_galaxy_repository_proto_depIdxs = nil
+}

clients/go/internal/generated/galaxy_repository_grpc.pb.go

@@ -0,0 +1,261 @@
+// Code generated by protoc-gen-go-grpc. DO NOT EDIT.
+// versions:
+// - protoc-gen-go-grpc v1.6.1
+// - protoc             v7.34.1
+// source: galaxy_repository.proto
+
+package generated
+
+import (
+	context "context"
+	grpc "google.golang.org/grpc"
+	codes "google.golang.org/grpc/codes"
+	status "google.golang.org/grpc/status"
+)
+
+// This is a compile-time assertion to ensure that this generated file
+// is compatible with the grpc package it is being compiled against.
+// Requires gRPC-Go v1.64.0 or later.
+const _ = grpc.SupportPackageIsVersion9
+
+const (
+	GalaxyRepository_TestConnection_FullMethodName    = "/galaxy_repository.v1.GalaxyRepository/TestConnection"
+	GalaxyRepository_GetLastDeployTime_FullMethodName = "/galaxy_repository.v1.GalaxyRepository/GetLastDeployTime"
+	GalaxyRepository_DiscoverHierarchy_FullMethodName = "/galaxy_repository.v1.GalaxyRepository/DiscoverHierarchy"
+	GalaxyRepository_WatchDeployEvents_FullMethodName = "/galaxy_repository.v1.GalaxyRepository/WatchDeployEvents"
+)
+
+// GalaxyRepositoryClient is the client API for GalaxyRepository service.
+//
+// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.
+//
+// Read-only browse over the AVEVA System Platform Galaxy Repository (ZB SQL
+// database). Lets clients enumerate the deployed object hierarchy and each
+// object's dynamic attributes so they know what tag references to subscribe
+// to via the MxAccessGateway service.
+type GalaxyRepositoryClient interface {
+	TestConnection(ctx context.Context, in *TestConnectionRequest, opts ...grpc.CallOption) (*TestConnectionReply, error)
+	GetLastDeployTime(ctx context.Context, in *GetLastDeployTimeRequest, opts ...grpc.CallOption) (*GetLastDeployTimeReply, error)
+	DiscoverHierarchy(ctx context.Context, in *DiscoverHierarchyRequest, opts ...grpc.CallOption) (*DiscoverHierarchyReply, error)
+	// Server-stream of deploy events. The server emits the current state immediately
+	// on subscribe (so clients can bootstrap their cache without waiting for the next
+	// deploy), then emits one event each time the gateway's hierarchy cache observes
+	// a new galaxy.time_of_last_deploy. The sequence field is monotonically
+	// increasing per server start; gaps indicate the per-subscriber buffer dropped
+	// older events because the client was too slow.
+	WatchDeployEvents(ctx context.Context, in *WatchDeployEventsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[DeployEvent], error)
+}
+
+type galaxyRepositoryClient struct {
+	cc grpc.ClientConnInterface
+}
+
+func NewGalaxyRepositoryClient(cc grpc.ClientConnInterface) GalaxyRepositoryClient {
+	return &galaxyRepositoryClient{cc}
+}
+
+func (c *galaxyRepositoryClient) TestConnection(ctx context.Context, in *TestConnectionRequest, opts ...grpc.CallOption) (*TestConnectionReply, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(TestConnectionReply)
+	err := c.cc.Invoke(ctx, GalaxyRepository_TestConnection_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *galaxyRepositoryClient) GetLastDeployTime(ctx context.Context, in *GetLastDeployTimeRequest, opts ...grpc.CallOption) (*GetLastDeployTimeReply, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(GetLastDeployTimeReply)
+	err := c.cc.Invoke(ctx, GalaxyRepository_GetLastDeployTime_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *galaxyRepositoryClient) DiscoverHierarchy(ctx context.Context, in *DiscoverHierarchyRequest, opts ...grpc.CallOption) (*DiscoverHierarchyReply, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(DiscoverHierarchyReply)
+	err := c.cc.Invoke(ctx, GalaxyRepository_DiscoverHierarchy_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *galaxyRepositoryClient) WatchDeployEvents(ctx context.Context, in *WatchDeployEventsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[DeployEvent], error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	stream, err := c.cc.NewStream(ctx, &GalaxyRepository_ServiceDesc.Streams[0], GalaxyRepository_WatchDeployEvents_FullMethodName, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	x := &grpc.GenericClientStream[WatchDeployEventsRequest, DeployEvent]{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 GalaxyRepository_WatchDeployEventsClient = grpc.ServerStreamingClient[DeployEvent]
+
+// GalaxyRepositoryServer is the server API for GalaxyRepository service.
+// All implementations must embed UnimplementedGalaxyRepositoryServer
+// for forward compatibility.
+//
+// Read-only browse over the AVEVA System Platform Galaxy Repository (ZB SQL
+// database). Lets clients enumerate the deployed object hierarchy and each
+// object's dynamic attributes so they know what tag references to subscribe
+// to via the MxAccessGateway service.
+type GalaxyRepositoryServer interface {
+	TestConnection(context.Context, *TestConnectionRequest) (*TestConnectionReply, error)
+	GetLastDeployTime(context.Context, *GetLastDeployTimeRequest) (*GetLastDeployTimeReply, error)
+	DiscoverHierarchy(context.Context, *DiscoverHierarchyRequest) (*DiscoverHierarchyReply, error)
+	// Server-stream of deploy events. The server emits the current state immediately
+	// on subscribe (so clients can bootstrap their cache without waiting for the next
+	// deploy), then emits one event each time the gateway's hierarchy cache observes
+	// a new galaxy.time_of_last_deploy. The sequence field is monotonically
+	// increasing per server start; gaps indicate the per-subscriber buffer dropped
+	// older events because the client was too slow.
+	WatchDeployEvents(*WatchDeployEventsRequest, grpc.ServerStreamingServer[DeployEvent]) error
+	mustEmbedUnimplementedGalaxyRepositoryServer()
+}
+
+// UnimplementedGalaxyRepositoryServer must be embedded to have
+// forward compatible implementations.
+//
+// NOTE: this should be embedded by value instead of pointer to avoid a nil
+// pointer dereference when methods are called.
+type UnimplementedGalaxyRepositoryServer struct{}
+
+func (UnimplementedGalaxyRepositoryServer) TestConnection(context.Context, *TestConnectionRequest) (*TestConnectionReply, error) {
+	return nil, status.Error(codes.Unimplemented, "method TestConnection not implemented")
+}
+func (UnimplementedGalaxyRepositoryServer) GetLastDeployTime(context.Context, *GetLastDeployTimeRequest) (*GetLastDeployTimeReply, error) {
+	return nil, status.Error(codes.Unimplemented, "method GetLastDeployTime not implemented")
+}
+func (UnimplementedGalaxyRepositoryServer) DiscoverHierarchy(context.Context, *DiscoverHierarchyRequest) (*DiscoverHierarchyReply, error) {
+	return nil, status.Error(codes.Unimplemented, "method DiscoverHierarchy not implemented")
+}
+func (UnimplementedGalaxyRepositoryServer) WatchDeployEvents(*WatchDeployEventsRequest, grpc.ServerStreamingServer[DeployEvent]) error {
+	return status.Error(codes.Unimplemented, "method WatchDeployEvents not implemented")
+}
+func (UnimplementedGalaxyRepositoryServer) mustEmbedUnimplementedGalaxyRepositoryServer() {}
+func (UnimplementedGalaxyRepositoryServer) testEmbeddedByValue()                          {}
+
+// UnsafeGalaxyRepositoryServer may be embedded to opt out of forward compatibility for this service.
+// Use of this interface is not recommended, as added methods to GalaxyRepositoryServer will
+// result in compilation errors.
+type UnsafeGalaxyRepositoryServer interface {
+	mustEmbedUnimplementedGalaxyRepositoryServer()
+}
+
+func RegisterGalaxyRepositoryServer(s grpc.ServiceRegistrar, srv GalaxyRepositoryServer) {
+	// If the following call panics, it indicates UnimplementedGalaxyRepositoryServer was
+	// embedded by pointer and is nil.  This will cause panics if an
+	// unimplemented method is ever invoked, so we test this at initialization
+	// time to prevent it from happening at runtime later due to I/O.
+	if t, ok := srv.(interface{ testEmbeddedByValue() }); ok {
+		t.testEmbeddedByValue()
+	}
+	s.RegisterService(&GalaxyRepository_ServiceDesc, srv)
+}
+
+func _GalaxyRepository_TestConnection_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(TestConnectionRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(GalaxyRepositoryServer).TestConnection(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: GalaxyRepository_TestConnection_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(GalaxyRepositoryServer).TestConnection(ctx, req.(*TestConnectionRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _GalaxyRepository_GetLastDeployTime_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(GetLastDeployTimeRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(GalaxyRepositoryServer).GetLastDeployTime(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: GalaxyRepository_GetLastDeployTime_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(GalaxyRepositoryServer).GetLastDeployTime(ctx, req.(*GetLastDeployTimeRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _GalaxyRepository_DiscoverHierarchy_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(DiscoverHierarchyRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(GalaxyRepositoryServer).DiscoverHierarchy(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: GalaxyRepository_DiscoverHierarchy_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(GalaxyRepositoryServer).DiscoverHierarchy(ctx, req.(*DiscoverHierarchyRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _GalaxyRepository_WatchDeployEvents_Handler(srv interface{}, stream grpc.ServerStream) error {
+	m := new(WatchDeployEventsRequest)
+	if err := stream.RecvMsg(m); err != nil {
+		return err
+	}
+	return srv.(GalaxyRepositoryServer).WatchDeployEvents(m, &grpc.GenericServerStream[WatchDeployEventsRequest, DeployEvent]{ServerStream: stream})
+}
+
+// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+type GalaxyRepository_WatchDeployEventsServer = grpc.ServerStreamingServer[DeployEvent]
+
+// GalaxyRepository_ServiceDesc is the grpc.ServiceDesc for GalaxyRepository service.
+// It's only intended for direct use with grpc.RegisterService,
+// and not to be introspected or modified (even as a copy)
+var GalaxyRepository_ServiceDesc = grpc.ServiceDesc{
+	ServiceName: "galaxy_repository.v1.GalaxyRepository",
+	HandlerType: (*GalaxyRepositoryServer)(nil),
+	Methods: []grpc.MethodDesc{
+		{
+			MethodName: "TestConnection",
+			Handler:    _GalaxyRepository_TestConnection_Handler,
+		},
+		{
+			MethodName: "GetLastDeployTime",
+			Handler:    _GalaxyRepository_GetLastDeployTime_Handler,
+		},
+		{
+			MethodName: "DiscoverHierarchy",
+			Handler:    _GalaxyRepository_DiscoverHierarchy_Handler,
+		},
+	},
+	Streams: []grpc.StreamDesc{
+		{
+			StreamName:    "WatchDeployEvents",
+			Handler:       _GalaxyRepository_WatchDeployEvents_Handler,
+			ServerStreams: true,
+		},
+	},
+	Metadata: "galaxy_repository.proto",
+}

clients/go/mxgateway/client.go

@@ -16,6 +16,7 @@ import (
 const (
 	defaultDialTimeout = 10 * time.Second
 	defaultCallTimeout = 30 * time.Second
+	defaultMaxGrpcMessageBytes = 16 * 1024 * 1024
 )
 
 // Client owns a gateway gRPC connection and exposes session-oriented helpers.
@@ -50,6 +51,10 @@ func Dial(ctx context.Context, opts Options) (*Client, error) {
 		grpc.WithTransportCredentials(transportCredentials),
 		grpc.WithUnaryInterceptor(unaryAuthInterceptor(opts.APIKey)),
 		grpc.WithStreamInterceptor(streamAuthInterceptor(opts.APIKey)),
+		grpc.WithDefaultCallOptions(
+			grpc.MaxCallRecvMsgSize(resolveMaxGrpcMessageBytes(opts)),
+			grpc.MaxCallSendMsgSize(resolveMaxGrpcMessageBytes(opts)),
+		),
 		grpc.WithBlock(),
 	}
 	dialOptions = append(dialOptions, opts.DialOptions...)
@@ -62,6 +67,13 @@ func Dial(ctx context.Context, opts Options) (*Client, error) {
 	return NewClient(conn, opts), nil
 }
 
+func resolveMaxGrpcMessageBytes(opts Options) int {
+	if opts.MaxGrpcMessageBytes > 0 {
+		return opts.MaxGrpcMessageBytes
+	}
+	return defaultMaxGrpcMessageBytes
+}
+
 // NewClient wraps an existing gRPC connection. The caller owns closing conn
 // unless it calls Close on the returned Client.
 func NewClient(conn *grpc.ClientConn, opts Options) *Client {
@@ -184,8 +196,11 @@ func (c *Client) callContext(ctx context.Context) (context.Context, context.Canc
 	if timeout < 0 {
 		return ctx, func() {}
 	}
-	if _, ok := ctx.Deadline(); ok {
-		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/client_session_test.go

@@ -77,6 +77,76 @@ func TestStreamEventsAttachesAuthMetadataAndClosesOnCancellation(t *testing.T) {
 	}
 }
 
+func TestEventSubscriptionCloseStopsStream(t *testing.T) {
+	fake := &fakeGatewayServer{
+		streamStarted: make(chan struct{}),
+		streamDone:    make(chan struct{}),
+	}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	subscription, err := session.SubscribeEvents(context.Background())
+	if err != nil {
+		t.Fatalf("SubscribeEvents() error = %v", err)
+	}
+	<-fake.streamStarted
+	first := <-subscription.Events()
+	if first.Err != nil {
+		t.Fatalf("first event error = %v", first.Err)
+	}
+
+	subscription.Close()
+
+	select {
+	case <-fake.streamDone:
+	case <-time.After(2 * time.Second):
+		t.Fatal("event stream did not stop after subscription close")
+	}
+	select {
+	case _, ok := <-subscription.Events():
+		if ok {
+			t.Fatal("subscription channel remained open after close")
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("subscription channel did not close")
+	}
+}
+
+func TestEventsAfterCancelsStreamWhenCompatibilityChannelIsAbandoned(t *testing.T) {
+	fake := &fakeGatewayServer{
+		streamStarted:    make(chan struct{}),
+		streamDone:       make(chan struct{}),
+		streamEventCount: 64,
+	}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	events, err := session.EventsAfter(context.Background(), 0)
+	if err != nil {
+		t.Fatalf("EventsAfter() error = %v", err)
+	}
+	<-fake.streamStarted
+
+	select {
+	case <-fake.streamDone:
+	case <-time.After(2 * time.Second):
+		t.Fatal("compatibility event stream did not stop after result channel filled")
+	}
+
+	for {
+		select {
+		case _, ok := <-events:
+			if !ok {
+				return
+			}
+		case <-time.After(2 * time.Second):
+			t.Fatal("compatibility event channel did not close")
+		}
+	}
+}
+
 func TestSessionHelpersBuildCommandsAndExposeRawReply(t *testing.T) {
 	fake := &fakeGatewayServer{
 		invokeReply: &pb.MxCommandReply{
@@ -117,6 +187,49 @@ func TestSessionHelpersBuildCommandsAndExposeRawReply(t *testing.T) {
 	}
 }
 
+func TestSubscribeBulkBuildsOneBulkCommandAndReturnsResults(t *testing.T) {
+	fake := &fakeGatewayServer{
+		invokeReply: &pb.MxCommandReply{
+			SessionId: "session-1",
+			Kind:      pb.MxCommandKind_MX_COMMAND_KIND_SUBSCRIBE_BULK,
+			ProtocolStatus: &pb.ProtocolStatus{
+				Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
+			},
+			Payload: &pb.MxCommandReply_SubscribeBulk{
+				SubscribeBulk: &pb.BulkSubscribeReply{
+					Results: []*pb.SubscribeResult{
+						{
+							ServerHandle:  12,
+							TagAddress:    "Area001.Pump001.Speed",
+							ItemHandle:    34,
+							WasSuccessful: true,
+						},
+					},
+				},
+			},
+		},
+	}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	results, err := session.SubscribeBulk(context.Background(), 12, []string{"Area001.Pump001.Speed"})
+	if err != nil {
+		t.Fatalf("SubscribeBulk() error = %v", err)
+	}
+
+	if len(results) != 1 || results[0].GetItemHandle() != 34 {
+		t.Fatalf("results = %#v, want item handle 34", results)
+	}
+	req := fake.invokeRequest
+	if req.GetCommand().GetKind() != pb.MxCommandKind_MX_COMMAND_KIND_SUBSCRIBE_BULK {
+		t.Fatalf("command kind = %s", req.GetCommand().GetKind())
+	}
+	if got := req.GetCommand().GetSubscribeBulk().GetTagAddresses(); len(got) != 1 || got[0] != "Area001.Pump001.Speed" {
+		t.Fatalf("tag addresses = %#v", got)
+	}
+}
+
 func TestInvokeReturnsTypedMxAccessErrorWithRawReply(t *testing.T) {
 	hresult := int32(-2147467259)
 	fake := &fakeGatewayServer{
@@ -188,12 +301,14 @@ func newBufconnClient(t *testing.T, fake *fakeGatewayServer) (*Client, func()) {
 type fakeGatewayServer struct {
 	pb.UnimplementedMxAccessGatewayServer
 
-	openReply     *pb.OpenSessionReply
-	openAuth      string
-	streamAuth    string
-	streamStarted chan struct{}
-	invokeReply   *pb.MxCommandReply
-	invokeRequest *pb.MxCommandRequest
+	openReply        *pb.OpenSessionReply
+	openAuth         string
+	streamAuth       string
+	streamStarted    chan struct{}
+	streamDone       chan struct{}
+	streamEventCount int
+	invokeReply      *pb.MxCommandReply
+	invokeRequest    *pb.MxCommandRequest
 }
 
 func (s *fakeGatewayServer) OpenSession(ctx context.Context, req *pb.OpenSessionRequest) (*pb.OpenSessionReply, error) {
@@ -234,15 +349,24 @@ func (s *fakeGatewayServer) Invoke(ctx context.Context, req *pb.MxCommandRequest
 
 func (s *fakeGatewayServer) StreamEvents(req *pb.StreamEventsRequest, stream grpc.ServerStreamingServer[pb.MxEvent]) error {
 	s.streamAuth = authorizationFromContext(stream.Context())
+	if s.streamDone != nil {
+		defer close(s.streamDone)
+	}
 	if s.streamStarted != nil {
 		close(s.streamStarted)
 	}
-	if err := stream.Send(&pb.MxEvent{
-		SessionId:      req.GetSessionId(),
-		Family:         pb.MxEventFamily_MX_EVENT_FAMILY_ON_DATA_CHANGE,
-		WorkerSequence: 1,
-	}); err != nil {
-		return err
+	eventCount := s.streamEventCount
+	if eventCount == 0 {
+		eventCount = 1
+	}
+	for sequence := 1; sequence <= eventCount; sequence++ {
+		if err := stream.Send(&pb.MxEvent{
+			SessionId:      req.GetSessionId(),
+			Family:         pb.MxEventFamily_MX_EVENT_FAMILY_ON_DATA_CHANGE,
+			WorkerSequence: uint64(sequence),
+		}); err != nil {
+			return err
+		}
 	}
 	<-stream.Context().Done()
 	return io.EOF

clients/go/mxgateway/galaxy.go

@@ -0,0 +1,270 @@
+package mxgateway
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"time"
+
+	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+	"google.golang.org/protobuf/types/known/timestamppb"
+)
+
+const discoverHierarchyPageSize = 5000
+
+// RawGalaxyRepositoryClient is the generated gRPC client interface for the
+// Galaxy Repository service exposed for callers that need direct contract
+// access.
+type RawGalaxyRepositoryClient = pb.GalaxyRepositoryClient
+
+// Generated protobuf aliases for Galaxy Repository messages.
+type (
+	TestConnectionRequest     = pb.TestConnectionRequest
+	TestConnectionReply       = pb.TestConnectionReply
+	GetLastDeployTimeRequest  = pb.GetLastDeployTimeRequest
+	GetLastDeployTimeReply    = pb.GetLastDeployTimeReply
+	DiscoverHierarchyRequest  = pb.DiscoverHierarchyRequest
+	DiscoverHierarchyReply    = pb.DiscoverHierarchyReply
+	GalaxyObject              = pb.GalaxyObject
+	GalaxyAttribute           = pb.GalaxyAttribute
+	WatchDeployEventsRequest  = pb.WatchDeployEventsRequest
+	DeployEvent               = pb.DeployEvent
+)
+
+// RawDeployEventStream is the generated WatchDeployEvents client stream.
+type RawDeployEventStream = grpc.ServerStreamingClient[pb.DeployEvent]
+
+// GalaxyClient owns a gateway gRPC connection and exposes Galaxy Repository
+// browse helpers. It mirrors the structure of Client and uses the same
+// connection-management conventions.
+type GalaxyClient struct {
+	conn *grpc.ClientConn
+	raw  pb.GalaxyRepositoryClient
+	opts Options
+}
+
+// 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.
+func DialGalaxy(ctx context.Context, opts Options) (*GalaxyClient, 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
+	}
+
+	dialOptions := []grpc.DialOption{
+		grpc.WithTransportCredentials(transportCredentials),
+		grpc.WithUnaryInterceptor(unaryAuthInterceptor(opts.APIKey)),
+		grpc.WithStreamInterceptor(streamAuthInterceptor(opts.APIKey)),
+		grpc.WithDefaultCallOptions(
+			grpc.MaxCallRecvMsgSize(resolveMaxGrpcMessageBytes(opts)),
+			grpc.MaxCallSendMsgSize(resolveMaxGrpcMessageBytes(opts)),
+		),
+		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
+}
+
+// NewGalaxyClient wraps an existing gRPC connection for Galaxy Repository
+// access. The caller owns closing conn unless it calls Close on the returned
+// GalaxyClient.
+func NewGalaxyClient(conn *grpc.ClientConn, opts Options) *GalaxyClient {
+	return &GalaxyClient{
+		conn: conn,
+		raw:  pb.NewGalaxyRepositoryClient(conn),
+		opts: opts,
+	}
+}
+
+// RawClient returns the generated gRPC client for command-specific parity
+// tests.
+func (c *GalaxyClient) RawClient() RawGalaxyRepositoryClient {
+	return c.raw
+}
+
+// TestConnection probes the Galaxy Repository service. It returns the server's
+// reported ok flag and a non-nil error only when the RPC itself fails.
+func (c *GalaxyClient) TestConnection(ctx context.Context) (bool, error) {
+	callCtx, cancel := c.callContext(ctx)
+	defer cancel()
+
+	reply, err := c.raw.TestConnection(callCtx, &pb.TestConnectionRequest{})
+	if err != nil {
+		return false, &GatewayError{Op: "galaxy test connection", Err: err}
+	}
+	return reply.GetOk(), nil
+}
+
+// GetLastDeployTime returns the Galaxy's last deploy timestamp. When the server
+// reports present=false (no deploy recorded yet) the call returns
+// (time.Time{}, false, nil). When present=true the timestamp is returned in
+// UTC with present=true.
+func (c *GalaxyClient) GetLastDeployTime(ctx context.Context) (time.Time, bool, error) {
+	callCtx, cancel := c.callContext(ctx)
+	defer cancel()
+
+	reply, err := c.raw.GetLastDeployTime(callCtx, &pb.GetLastDeployTimeRequest{})
+	if err != nil {
+		return time.Time{}, false, &GatewayError{Op: "galaxy get last deploy time", Err: err}
+	}
+	if !reply.GetPresent() {
+		return time.Time{}, false, nil
+	}
+	ts := reply.GetTimeOfLastDeploy()
+	if ts == nil {
+		return time.Time{}, false, nil
+	}
+	return ts.AsTime(), true, nil
+}
+
+// DiscoverHierarchy returns the deployed Galaxy object hierarchy with each
+// object's dynamic attributes. The objects are returned in the order supplied
+// by the server.
+func (c *GalaxyClient) DiscoverHierarchy(ctx context.Context) ([]*GalaxyObject, error) {
+	callCtx, cancel := c.callContext(ctx)
+	defer cancel()
+
+	var objects []*GalaxyObject
+	seenPageTokens := make(map[string]struct{})
+	pageToken := ""
+	for {
+		reply, err := c.raw.DiscoverHierarchy(callCtx, &pb.DiscoverHierarchyRequest{
+			PageSize:  discoverHierarchyPageSize,
+			PageToken: pageToken,
+		})
+		if err != nil {
+			return nil, &GatewayError{Op: "galaxy discover hierarchy", Err: err}
+		}
+		objects = append(objects, reply.GetObjects()...)
+		pageToken = reply.GetNextPageToken()
+		if pageToken == "" {
+			break
+		}
+		if _, seen := seenPageTokens[pageToken]; seen {
+			return nil, fmt.Errorf("mxgateway: galaxy discover hierarchy returned repeated page token %q", pageToken)
+		}
+		seenPageTokens[pageToken] = struct{}{}
+	}
+	return objects, nil
+}
+
+// WatchDeployEventsRaw starts the generated WatchDeployEvents stream for callers
+// that want direct control over Recv. The caller owns the returned stream's
+// lifetime via ctx cancellation.
+func (c *GalaxyClient) WatchDeployEventsRaw(ctx context.Context, req *WatchDeployEventsRequest) (RawDeployEventStream, error) {
+	if req == nil {
+		req = &pb.WatchDeployEventsRequest{}
+	}
+
+	stream, err := c.raw.WatchDeployEvents(ctx, req)
+	if err != nil {
+		return nil, &GatewayError{Op: "galaxy watch deploy events", Err: err}
+	}
+	return stream, nil
+}
+
+// WatchDeployEvents subscribes to Galaxy deploy events. The server emits a
+// bootstrap event with the current state immediately on subscribe, then one
+// event per new deploy. When lastSeenDeployTime is non-nil it is forwarded to
+// the server to suppress the bootstrap event.
+//
+// The returned event channel is closed when the server completes the stream
+// (io.EOF), when ctx is cancelled, or after a terminal error has been
+// delivered on the error channel. The error channel is also closed once the
+// stream tears down. Surfaced errors are wrapped in *GatewayError.
+//
+// Cancel ctx to tear the stream down cleanly.
+func (c *GalaxyClient) WatchDeployEvents(
+	ctx context.Context,
+	lastSeenDeployTime *time.Time,
+) (<-chan *DeployEvent, <-chan error, error) {
+	req := &pb.WatchDeployEventsRequest{}
+	if lastSeenDeployTime != nil {
+		req.LastSeenDeployTime = timestamppb.New(*lastSeenDeployTime)
+	}
+
+	stream, err := c.WatchDeployEventsRaw(ctx, req)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	events := make(chan *DeployEvent, 16)
+	errs := make(chan error, 1)
+	go func() {
+		defer close(events)
+		defer close(errs)
+		for {
+			event, recvErr := stream.Recv()
+			if recvErr == nil {
+				select {
+				case events <- event:
+				case <-ctx.Done():
+					return
+				}
+				continue
+			}
+			if recvErr == io.EOF {
+				return
+			}
+			if status.Code(recvErr) == codes.Canceled || ctx.Err() != nil {
+				return
+			}
+			select {
+			case errs <- &GatewayError{Op: "galaxy watch deploy events", Err: recvErr}:
+			case <-ctx.Done():
+			}
+			return
+		}
+	}()
+
+	return events, errs, nil
+}
+
+// Close closes the underlying gRPC connection.
+func (c *GalaxyClient) Close() error {
+	if c == nil || c.conn == nil {
+		return nil
+	}
+	return c.conn.Close()
+}
+
+func (c *GalaxyClient) callContext(ctx context.Context) (context.Context, context.CancelFunc) {
+	timeout := 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

@@ -0,0 +1,470 @@
+package mxgateway
+
+import (
+	"context"
+	"errors"
+	"net"
+	"strings"
+	"testing"
+	"time"
+
+	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/test/bufconn"
+	"google.golang.org/protobuf/types/known/timestamppb"
+)
+
+func TestGalaxyTestConnectionAttachesAuthAndReturnsOk(t *testing.T) {
+	fake := &fakeGalaxyServer{
+		testReply: &pb.TestConnectionReply{Ok: true},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	ok, err := client.TestConnection(context.Background())
+	if err != nil {
+		t.Fatalf("TestConnection() error = %v", err)
+	}
+	if !ok {
+		t.Fatalf("TestConnection() ok = false, want true")
+	}
+	if got := fake.testAuth; got != "Bearer test-api-key" {
+		t.Fatalf("authorization metadata = %q, want %q", got, "Bearer test-api-key")
+	}
+}
+
+func TestGalaxyGetLastDeployTimeReturnsAbsentForPresentFalse(t *testing.T) {
+	fake := &fakeGalaxyServer{
+		deployReply: &pb.GetLastDeployTimeReply{Present: false},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	got, present, err := client.GetLastDeployTime(context.Background())
+	if err != nil {
+		t.Fatalf("GetLastDeployTime() error = %v", err)
+	}
+	if present {
+		t.Fatalf("present = true, want false")
+	}
+	if !got.IsZero() {
+		t.Fatalf("time = %v, want zero", got)
+	}
+}
+
+func TestGalaxyGetLastDeployTimeReturnsTimestampWhenPresent(t *testing.T) {
+	want := time.Date(2026, 4, 28, 12, 34, 56, 0, time.UTC)
+	fake := &fakeGalaxyServer{
+		deployReply: &pb.GetLastDeployTimeReply{
+			Present:           true,
+			TimeOfLastDeploy:  timestamppb.New(want),
+		},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	got, present, err := client.GetLastDeployTime(context.Background())
+	if err != nil {
+		t.Fatalf("GetLastDeployTime() error = %v", err)
+	}
+	if !present {
+		t.Fatalf("present = false, want true")
+	}
+	if !got.Equal(want) {
+		t.Fatalf("time = %v, want %v", got, want)
+	}
+}
+
+func TestGalaxyGetLastDeployTimeReturnsAbsentWhenTimestampNil(t *testing.T) {
+	fake := &fakeGalaxyServer{
+		deployReply: &pb.GetLastDeployTimeReply{Present: true, TimeOfLastDeploy: nil},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	got, present, err := client.GetLastDeployTime(context.Background())
+	if err != nil {
+		t.Fatalf("GetLastDeployTime() error = %v", err)
+	}
+	if present {
+		t.Fatalf("present = true, want false (nil timestamp)")
+	}
+	if !got.IsZero() {
+		t.Fatalf("time = %v, want zero", got)
+	}
+}
+
+func TestGalaxyDiscoverHierarchyReturnsObjects(t *testing.T) {
+	fake := &fakeGalaxyServer{
+		discoverReplies: []*pb.DiscoverHierarchyReply{{
+			NextPageToken:    "page-2",
+			TotalObjectCount: 2,
+			Objects: []*pb.GalaxyObject{
+				{
+					GobjectId:     1,
+					TagName:       "TestMachine_001",
+					ContainedName: "TestMachine_001",
+					BrowseName:    "TestMachine_001",
+					IsArea:        false,
+					CategoryId:    7,
+					TemplateChain: []string{"$Object", "$AppObject"},
+					Attributes: []*pb.GalaxyAttribute{
+						{
+							AttributeName:    "DownloadPath",
+							FullTagReference: "TestMachine_001.DownloadPath",
+							MxDataType:       8,
+							DataTypeName:     "String",
+						},
+					},
+				},
+			},
+		}, {
+			TotalObjectCount: 2,
+			Objects: []*pb.GalaxyObject{
+				{
+					GobjectId:       2,
+					TagName:         "TestMachine_002",
+					ContainedName:   "TestMachine_002",
+					ParentGobjectId: 1,
+				},
+			},
+		}},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	objects, err := client.DiscoverHierarchy(context.Background())
+	if err != nil {
+		t.Fatalf("DiscoverHierarchy() error = %v", err)
+	}
+	if len(objects) != 2 {
+		t.Fatalf("len(objects) = %d, want 2", len(objects))
+	}
+	if len(fake.discoverRequests) != 2 {
+		t.Fatalf("len(discoverRequests) = %d, want 2", len(fake.discoverRequests))
+	}
+	if fake.discoverRequests[0].GetPageSize() != 5000 || fake.discoverRequests[0].GetPageToken() != "" {
+		t.Fatalf("first request = %+v", fake.discoverRequests[0])
+	}
+	if fake.discoverRequests[1].GetPageToken() != "page-2" {
+		t.Fatalf("second page_token = %q, want page-2", fake.discoverRequests[1].GetPageToken())
+	}
+	if objects[0].GetTagName() != "TestMachine_001" {
+		t.Fatalf("objects[0].TagName = %q", objects[0].GetTagName())
+	}
+	if len(objects[0].GetAttributes()) != 1 {
+		t.Fatalf("len(attributes) = %d, want 1", len(objects[0].GetAttributes()))
+	}
+	if objects[0].GetAttributes()[0].GetFullTagReference() != "TestMachine_001.DownloadPath" {
+		t.Fatalf("FullTagReference = %q", objects[0].GetAttributes()[0].GetFullTagReference())
+	}
+}
+
+func TestGalaxyDiscoverHierarchyRejectsRepeatedPageToken(t *testing.T) {
+	fake := &fakeGalaxyServer{
+		discoverReplies: []*pb.DiscoverHierarchyReply{
+			{NextPageToken: "7:1"},
+			{NextPageToken: "7:1"},
+		},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	_, err := client.DiscoverHierarchy(context.Background())
+	if err == nil {
+		t.Fatal("DiscoverHierarchy() error = nil, want repeated token error")
+	}
+	if !strings.Contains(err.Error(), "repeated page token") {
+		t.Fatalf("error = %v, want repeated page token", err)
+	}
+}
+
+func TestGalaxyDialReturnsGatewayErrorOnRpcFailure(t *testing.T) {
+	fake := &fakeGalaxyServer{failTest: true}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	_, err := client.TestConnection(context.Background())
+	if err == nil {
+		t.Fatal("TestConnection() error = nil, want error")
+	}
+	var gwErr *GatewayError
+	if !errors.As(err, &gwErr) {
+		t.Fatalf("error %T does not support errors.As(*GatewayError)", err)
+	}
+	if gwErr.Op != "galaxy test connection" {
+		t.Fatalf("Op = %q, want %q", gwErr.Op, "galaxy test connection")
+	}
+}
+
+func TestGalaxyWatchDeployEventsReceivesEventsInOrder(t *testing.T) {
+	bootstrap := time.Date(2026, 4, 28, 10, 0, 0, 0, time.UTC)
+	deploy1 := time.Date(2026, 4, 28, 10, 5, 0, 0, time.UTC)
+	deploy2 := time.Date(2026, 4, 28, 10, 6, 0, 0, time.UTC)
+	fake := &fakeGalaxyServer{
+		watchEvents: []*pb.DeployEvent{
+			{
+				Sequence:                1,
+				ObservedAt:              timestamppb.New(bootstrap),
+				TimeOfLastDeploy:        timestamppb.New(deploy1),
+				TimeOfLastDeployPresent: true,
+				ObjectCount:             10,
+				AttributeCount:          42,
+			},
+			{
+				Sequence:                2,
+				ObservedAt:              timestamppb.New(deploy2),
+				TimeOfLastDeploy:        timestamppb.New(deploy2),
+				TimeOfLastDeployPresent: true,
+				ObjectCount:             11,
+				AttributeCount:          44,
+			},
+		},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	events, errs, err := client.WatchDeployEvents(ctx, nil)
+	if err != nil {
+		t.Fatalf("WatchDeployEvents() error = %v", err)
+	}
+
+	got := make([]*DeployEvent, 0, 2)
+loop:
+	for {
+		select {
+		case ev, ok := <-events:
+			if !ok {
+				break loop
+			}
+			got = append(got, ev)
+		case errVal := <-errs:
+			if errVal != nil {
+				t.Fatalf("error channel: %v", errVal)
+			}
+		case <-ctx.Done():
+			t.Fatalf("timeout waiting for events; got %d", len(got))
+		}
+	}
+
+	if len(got) != 2 {
+		t.Fatalf("len(events) = %d, want 2", len(got))
+	}
+	if got[0].GetSequence() != 1 || got[1].GetSequence() != 2 {
+		t.Fatalf("sequences = [%d,%d], want [1,2]", got[0].GetSequence(), got[1].GetSequence())
+	}
+	if !got[0].GetTimeOfLastDeployPresent() {
+		t.Fatalf("event[0] TimeOfLastDeployPresent = false, want true")
+	}
+	if got[0].GetObjectCount() != 10 || got[0].GetAttributeCount() != 42 {
+		t.Fatalf("event[0] counts = (%d,%d), want (10,42)", got[0].GetObjectCount(), got[0].GetAttributeCount())
+	}
+	if !got[0].GetTimeOfLastDeploy().AsTime().Equal(deploy1) {
+		t.Fatalf("event[0] TimeOfLastDeploy = %v, want %v", got[0].GetTimeOfLastDeploy().AsTime(), deploy1)
+	}
+}
+
+func TestGalaxyWatchDeployEventsForwardsLastSeenDeployTime(t *testing.T) {
+	fake := &fakeGalaxyServer{
+		watchEvents: []*pb.DeployEvent{
+			{Sequence: 7},
+		},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	lastSeen := time.Date(2026, 4, 28, 9, 0, 0, 0, time.UTC)
+	events, errs, err := client.WatchDeployEvents(ctx, &lastSeen)
+	if err != nil {
+		t.Fatalf("WatchDeployEvents() error = %v", err)
+	}
+
+	// Drain everything.
+loop:
+	for {
+		select {
+		case _, ok := <-events:
+			if !ok {
+				break loop
+			}
+		case errVal := <-errs:
+			if errVal != nil {
+				t.Fatalf("error channel: %v", errVal)
+			}
+		case <-ctx.Done():
+			t.Fatalf("timeout draining events")
+		}
+	}
+
+	if fake.watchRequest == nil {
+		t.Fatalf("server did not receive a request")
+	}
+	gotTs := fake.watchRequest.GetLastSeenDeployTime()
+	if gotTs == nil {
+		t.Fatalf("LastSeenDeployTime = nil, want %v", lastSeen)
+	}
+	if !gotTs.AsTime().Equal(lastSeen) {
+		t.Fatalf("LastSeenDeployTime = %v, want %v", gotTs.AsTime(), lastSeen)
+	}
+}
+
+func TestGalaxyWatchDeployEventsCancelTearsDownStream(t *testing.T) {
+	fake := &fakeGalaxyServer{
+		watchEvents: []*pb.DeployEvent{
+			{Sequence: 1},
+		},
+		watchHoldOpen: true,
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	streamCtx, cancelStream := context.WithCancel(context.Background())
+
+	events, errs, err := client.WatchDeployEvents(streamCtx, nil)
+	if err != nil {
+		t.Fatalf("WatchDeployEvents() error = %v", err)
+	}
+
+	// Wait for the bootstrap event to arrive.
+	select {
+	case ev, ok := <-events:
+		if !ok {
+			t.Fatalf("events channel closed before delivering bootstrap")
+		}
+		if ev.GetSequence() != 1 {
+			t.Fatalf("got seq=%d, want 1", ev.GetSequence())
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatalf("timeout waiting for bootstrap event")
+	}
+
+	// Cancel the stream; both channels must close cleanly without delivering an error.
+	cancelStream()
+
+	deadline := time.After(2 * time.Second)
+	for events != nil || errs != nil {
+		select {
+		case _, ok := <-events:
+			if !ok {
+				events = nil
+			}
+		case errVal, ok := <-errs:
+			if !ok {
+				errs = nil
+				continue
+			}
+			if errVal != nil {
+				t.Fatalf("error after cancel: %v", errVal)
+			}
+		case <-deadline:
+			t.Fatalf("channels did not close after cancel; events nil=%v errs nil=%v", events == nil, errs == nil)
+		}
+	}
+}
+
+func newGalaxyBufconnClient(t *testing.T, fake *fakeGalaxyServer) (*GalaxyClient, func()) {
+	t.Helper()
+
+	listener := bufconn.Listen(bufSize)
+	server := grpc.NewServer()
+	pb.RegisterGalaxyRepositoryServer(server, fake)
+	go func() {
+		if err := server.Serve(listener); err != nil && !errors.Is(err, grpc.ErrServerStopped) {
+			t.Errorf("bufconn server failed: %v", err)
+		}
+	}()
+
+	dialer := func(ctx context.Context, _ string) (net.Conn, error) {
+		return listener.DialContext(ctx)
+	}
+	client, err := DialGalaxy(context.Background(), Options{
+		Endpoint:  "bufnet",
+		APIKey:    "test-api-key",
+		Plaintext: true,
+		DialOptions: []grpc.DialOption{
+			grpc.WithContextDialer(dialer),
+		},
+	})
+	if err != nil {
+		t.Fatalf("DialGalaxy() error = %v", err)
+	}
+
+	return client, func() {
+		client.Close()
+		server.Stop()
+		listener.Close()
+	}
+}
+
+type fakeGalaxyServer struct {
+	pb.UnimplementedGalaxyRepositoryServer
+
+	testReply         *pb.TestConnectionReply
+	testAuth          string
+	failTest          bool
+	deployReply       *pb.GetLastDeployTimeReply
+	discoverReply     *pb.DiscoverHierarchyReply
+	discoverReplies   []*pb.DiscoverHierarchyReply
+	discoverRequests  []*pb.DiscoverHierarchyRequest
+	watchEvents       []*pb.DeployEvent
+	watchRequest      *pb.WatchDeployEventsRequest
+	watchSendInterval time.Duration
+	watchHoldOpen     bool
+}
+
+func (s *fakeGalaxyServer) TestConnection(ctx context.Context, req *pb.TestConnectionRequest) (*pb.TestConnectionReply, error) {
+	s.testAuth = authorizationFromContext(ctx)
+	if s.failTest {
+		return nil, errors.New("simulated failure")
+	}
+	if s.testReply != nil {
+		return s.testReply, nil
+	}
+	return &pb.TestConnectionReply{Ok: true}, nil
+}
+
+func (s *fakeGalaxyServer) GetLastDeployTime(ctx context.Context, req *pb.GetLastDeployTimeRequest) (*pb.GetLastDeployTimeReply, error) {
+	if s.deployReply != nil {
+		return s.deployReply, nil
+	}
+	return &pb.GetLastDeployTimeReply{Present: false}, nil
+}
+
+func (s *fakeGalaxyServer) DiscoverHierarchy(ctx context.Context, req *pb.DiscoverHierarchyRequest) (*pb.DiscoverHierarchyReply, error) {
+	s.discoverRequests = append(s.discoverRequests, req)
+	if len(s.discoverReplies) > 0 {
+		reply := s.discoverReplies[0]
+		s.discoverReplies = s.discoverReplies[1:]
+		return reply, nil
+	}
+	if s.discoverReply != nil {
+		return s.discoverReply, nil
+	}
+	return &pb.DiscoverHierarchyReply{}, nil
+}
+
+func (s *fakeGalaxyServer) WatchDeployEvents(req *pb.WatchDeployEventsRequest, stream grpc.ServerStreamingServer[pb.DeployEvent]) error {
+	s.watchRequest = req
+	for _, event := range s.watchEvents {
+		if err := stream.Send(event); err != nil {
+			return err
+		}
+		if s.watchSendInterval > 0 {
+			select {
+			case <-time.After(s.watchSendInterval):
+			case <-stream.Context().Done():
+				return stream.Context().Err()
+			}
+		}
+	}
+	if s.watchHoldOpen {
+		<-stream.Context().Done()
+	}
+	return nil
+}

clients/go/mxgateway/options.go

@@ -18,6 +18,7 @@ type Options struct {
 	ServerNameOverride   string
 	DialTimeout          time.Duration
 	CallTimeout          time.Duration
+	MaxGrpcMessageBytes  int
 	TLSConfig            *tls.Config
 	TransportCredentials credentials.TransportCredentials
 	DialOptions          []grpc.DialOption

clients/go/mxgateway/session.go

@@ -5,6 +5,7 @@ import (
 	"crypto/rand"
 	"encoding/hex"
 	"errors"
+	"fmt"
 	"io"
 	"sync"
 
@@ -13,12 +14,38 @@ import (
 	"google.golang.org/grpc/status"
 )
 
+const maxBulkItems = 1000
+
 // EventResult carries either the next ordered event or a terminal stream error.
 type EventResult struct {
 	Event *MxEvent
 	Err   error
 }
 
+// EventSubscription owns a running gateway event stream.
+type EventSubscription struct {
+	results <-chan EventResult
+	cancel  context.CancelFunc
+	done    <-chan struct{}
+	once    sync.Once
+}
+
+// Events returns the stream results channel.
+func (s *EventSubscription) Events() <-chan EventResult {
+	return s.results
+}
+
+// Close cancels the stream and waits for the receive goroutine to stop.
+func (s *EventSubscription) Close() {
+	if s == nil {
+		return
+	}
+	s.once.Do(func() {
+		s.cancel()
+		<-s.done
+	})
+}
+
 // Session represents one gateway-backed MXAccess session.
 type Session struct {
 	client     *Client
@@ -104,6 +131,25 @@ func (s *Session) Unregister(ctx context.Context, serverHandle int32) error {
 	return err
 }
 
+// RemoveItem invokes MXAccess RemoveItem.
+func (s *Session) RemoveItem(ctx context.Context, serverHandle, itemHandle int32) error {
+	_, err := s.RemoveItemRaw(ctx, serverHandle, itemHandle)
+	return err
+}
+
+// RemoveItemRaw invokes MXAccess RemoveItem and returns the raw reply.
+func (s *Session) RemoveItemRaw(ctx context.Context, serverHandle, itemHandle int32) (*MxCommandReply, error) {
+	return s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_REMOVE_ITEM,
+		Payload: &pb.MxCommand_RemoveItem{
+			RemoveItem: &pb.RemoveItemCommand{
+				ServerHandle: serverHandle,
+				ItemHandle:   itemHandle,
+			},
+		},
+	})
+}
+
 // AddItem invokes MXAccess AddItem and returns the item handle.
 func (s *Session) AddItem(ctx context.Context, serverHandle int32, itemDefinition string) (int32, error) {
 	reply, err := s.AddItemRaw(ctx, serverHandle, itemDefinition)
@@ -182,6 +228,163 @@ func (s *Session) AdviseRaw(ctx context.Context, serverHandle, itemHandle int32)
 	})
 }
 
+// UnAdvise invokes MXAccess UnAdvise.
+func (s *Session) UnAdvise(ctx context.Context, serverHandle, itemHandle int32) error {
+	_, err := s.UnAdviseRaw(ctx, serverHandle, itemHandle)
+	return err
+}
+
+// UnAdviseRaw invokes MXAccess UnAdvise and returns the raw reply.
+func (s *Session) UnAdviseRaw(ctx context.Context, serverHandle, itemHandle int32) (*MxCommandReply, error) {
+	return s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_UN_ADVISE,
+		Payload: &pb.MxCommand_UnAdvise{
+			UnAdvise: &pb.UnAdviseCommand{
+				ServerHandle: serverHandle,
+				ItemHandle:   itemHandle,
+			},
+		},
+	})
+}
+
+// AddItemBulk invokes MXAccess AddItem for each tag inside one gateway command.
+func (s *Session) AddItemBulk(ctx context.Context, serverHandle int32, tagAddresses []string) ([]*SubscribeResult, error) {
+	if tagAddresses == nil {
+		return nil, errors.New("mxgateway: tag addresses are required")
+	}
+	if err := ensureBulkSize("tag addresses", len(tagAddresses)); err != nil {
+		return nil, err
+	}
+	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM_BULK,
+		Payload: &pb.MxCommand_AddItemBulk{
+			AddItemBulk: &pb.AddItemBulkCommand{
+				ServerHandle: serverHandle,
+				TagAddresses: tagAddresses,
+			},
+		},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return reply.GetAddItemBulk().GetResults(), nil
+}
+
+// AdviseItemBulk invokes MXAccess Advise for each item handle inside one gateway command.
+func (s *Session) AdviseItemBulk(ctx context.Context, serverHandle int32, itemHandles []int32) ([]*SubscribeResult, error) {
+	if itemHandles == nil {
+		return nil, errors.New("mxgateway: item handles are required")
+	}
+	if err := ensureBulkSize("item handles", len(itemHandles)); err != nil {
+		return nil, err
+	}
+	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_ADVISE_ITEM_BULK,
+		Payload: &pb.MxCommand_AdviseItemBulk{
+			AdviseItemBulk: &pb.AdviseItemBulkCommand{
+				ServerHandle: serverHandle,
+				ItemHandles:  itemHandles,
+			},
+		},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return reply.GetAdviseItemBulk().GetResults(), nil
+}
+
+// RemoveItemBulk invokes MXAccess RemoveItem for each item handle inside one gateway command.
+func (s *Session) RemoveItemBulk(ctx context.Context, serverHandle int32, itemHandles []int32) ([]*SubscribeResult, error) {
+	if itemHandles == nil {
+		return nil, errors.New("mxgateway: item handles are required")
+	}
+	if err := ensureBulkSize("item handles", len(itemHandles)); err != nil {
+		return nil, err
+	}
+	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_REMOVE_ITEM_BULK,
+		Payload: &pb.MxCommand_RemoveItemBulk{
+			RemoveItemBulk: &pb.RemoveItemBulkCommand{
+				ServerHandle: serverHandle,
+				ItemHandles:  itemHandles,
+			},
+		},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return reply.GetRemoveItemBulk().GetResults(), nil
+}
+
+// UnAdviseItemBulk invokes MXAccess UnAdvise for each item handle inside one gateway command.
+func (s *Session) UnAdviseItemBulk(ctx context.Context, serverHandle int32, itemHandles []int32) ([]*SubscribeResult, error) {
+	if itemHandles == nil {
+		return nil, errors.New("mxgateway: item handles are required")
+	}
+	if err := ensureBulkSize("item handles", len(itemHandles)); err != nil {
+		return nil, err
+	}
+	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_UN_ADVISE_ITEM_BULK,
+		Payload: &pb.MxCommand_UnAdviseItemBulk{
+			UnAdviseItemBulk: &pb.UnAdviseItemBulkCommand{
+				ServerHandle: serverHandle,
+				ItemHandles:  itemHandles,
+			},
+		},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return reply.GetUnAdviseItemBulk().GetResults(), nil
+}
+
+// SubscribeBulk invokes AddItem and Advise for each tag inside one gateway command.
+func (s *Session) SubscribeBulk(ctx context.Context, serverHandle int32, tagAddresses []string) ([]*SubscribeResult, error) {
+	if tagAddresses == nil {
+		return nil, errors.New("mxgateway: tag addresses are required")
+	}
+	if err := ensureBulkSize("tag addresses", len(tagAddresses)); err != nil {
+		return nil, err
+	}
+	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_SUBSCRIBE_BULK,
+		Payload: &pb.MxCommand_SubscribeBulk{
+			SubscribeBulk: &pb.SubscribeBulkCommand{
+				ServerHandle: serverHandle,
+				TagAddresses: tagAddresses,
+			},
+		},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return reply.GetSubscribeBulk().GetResults(), nil
+}
+
+// UnsubscribeBulk invokes UnAdvise and RemoveItem for each item handle inside one gateway command.
+func (s *Session) UnsubscribeBulk(ctx context.Context, serverHandle int32, itemHandles []int32) ([]*SubscribeResult, error) {
+	if itemHandles == nil {
+		return nil, errors.New("mxgateway: item handles are required")
+	}
+	if err := ensureBulkSize("item handles", len(itemHandles)); err != nil {
+		return nil, err
+	}
+	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_UNSUBSCRIBE_BULK,
+		Payload: &pb.MxCommand_UnsubscribeBulk{
+			UnsubscribeBulk: &pb.UnsubscribeBulkCommand{
+				ServerHandle: serverHandle,
+				ItemHandles:  itemHandles,
+			},
+		},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return reply.GetUnsubscribeBulk().GetResults(), nil
+}
+
 // Write invokes MXAccess Write.
 func (s *Session) Write(ctx context.Context, serverHandle, itemHandle int32, value *MxValue, userID int32) error {
 	_, err := s.WriteRaw(ctx, serverHandle, itemHandle, value, userID)
@@ -215,32 +418,99 @@ func (s *Session) Events(ctx context.Context) (<-chan EventResult, error) {
 
 // EventsAfter streams ordered session events after the given worker sequence.
 func (s *Session) EventsAfter(ctx context.Context, afterWorkerSequence uint64) (<-chan EventResult, error) {
-	stream, err := s.client.StreamEventsRaw(ctx, &pb.StreamEventsRequest{
+	subscription, err := s.subscribeEventsAfter(ctx, afterWorkerSequence, true)
+	if err != nil {
+		return nil, err
+	}
+	return subscription.Events(), nil
+}
+
+// SubscribeEvents starts an owned event subscription.
+func (s *Session) SubscribeEvents(ctx context.Context) (*EventSubscription, error) {
+	return s.SubscribeEventsAfter(ctx, 0)
+}
+
+// SubscribeEventsAfter starts an owned event subscription after the given worker sequence.
+func (s *Session) SubscribeEventsAfter(ctx context.Context, afterWorkerSequence uint64) (*EventSubscription, error) {
+	return s.subscribeEventsAfter(ctx, afterWorkerSequence, false)
+}
+
+func (s *Session) subscribeEventsAfter(ctx context.Context, afterWorkerSequence uint64, cancelWhenResultBufferFull bool) (*EventSubscription, error) {
+	streamCtx, cancel := context.WithCancel(ctx)
+	stream, err := s.client.StreamEventsRaw(streamCtx, &pb.StreamEventsRequest{
 		SessionId:           s.ID(),
 		AfterWorkerSequence: afterWorkerSequence,
 	})
 	if err != nil {
+		cancel()
 		return nil, err
 	}
 
 	results := make(chan EventResult, 16)
+	done := make(chan struct{})
 	go func() {
 		defer close(results)
+		defer close(done)
 		for {
 			event, err := stream.Recv()
 			if err == nil {
-				results <- EventResult{Event: event}
+				if !sendEventResult(streamCtx, results, EventResult{Event: event}, cancelWhenResultBufferFull, cancel) {
+					return
+				}
 				continue
 			}
-			if err == io.EOF || status.Code(err) == codes.Canceled || ctx.Err() != nil {
+			if err == io.EOF || status.Code(err) == codes.Canceled || streamCtx.Err() != nil {
 				return
 			}
-			results <- EventResult{Err: &GatewayError{Op: "stream events", Err: err}}
+			sendEventResult(
+				streamCtx,
+				results,
+				EventResult{Err: &GatewayError{Op: "stream events", Err: err}},
+				cancelWhenResultBufferFull,
+				cancel)
 			return
 		}
 	}()
 
-	return results, nil
+	return &EventSubscription{
+		results: results,
+		cancel:  cancel,
+		done:    done,
+	}, nil
+}
+
+func ensureBulkSize(name string, length int) error {
+	if length > maxBulkItems {
+		return fmt.Errorf("mxgateway: %s bulk commands are limited to %d item(s)", name, maxBulkItems)
+	}
+	return nil
+}
+
+func sendEventResult(
+	ctx context.Context,
+	results chan<- EventResult,
+	result EventResult,
+	cancelWhenBufferFull bool,
+	cancel context.CancelFunc,
+) bool {
+	if cancelWhenBufferFull {
+		select {
+		case results <- result:
+			return true
+		case <-ctx.Done():
+			return false
+		default:
+			cancel()
+			return false
+		}
+	}
+
+	select {
+	case results <- result:
+		return true
+	case <-ctx.Done():
+		return false
+	}
 }
 
 func (s *Session) invokeCommand(ctx context.Context, command *MxCommand) (*MxCommandReply, error) {

clients/go/mxgateway/types.go

@@ -12,30 +12,40 @@ type RawEventStream = pb.MxAccessGateway_StreamEventsClient
 // Generated protobuf aliases keep raw contract access available from the public
 // mxgateway package while generated code remains under internal/generated.
 type (
-	OpenSessionRequest  = pb.OpenSessionRequest
-	OpenSessionReply    = pb.OpenSessionReply
-	CloseSessionRequest = pb.CloseSessionRequest
-	CloseSessionReply   = pb.CloseSessionReply
-	StreamEventsRequest = pb.StreamEventsRequest
-	MxCommandRequest    = pb.MxCommandRequest
-	MxCommandReply      = pb.MxCommandReply
-	MxCommand           = pb.MxCommand
-	MxEvent             = pb.MxEvent
-	MxValue             = pb.MxValue
-	Value               = pb.MxValue
-	MxArray             = pb.MxArray
-	MxStatusProxy       = pb.MxStatusProxy
-	ProtocolStatus      = pb.ProtocolStatus
-	RegisterCommand     = pb.RegisterCommand
-	UnregisterCommand   = pb.UnregisterCommand
-	AddItemCommand      = pb.AddItemCommand
-	AddItem2Command     = pb.AddItem2Command
-	AdviseCommand       = pb.AdviseCommand
-	WriteCommand        = pb.WriteCommand
-	Write2Command       = pb.Write2Command
-	RegisterReply       = pb.RegisterReply
-	AddItemReply        = pb.AddItemReply
-	AddItem2Reply       = pb.AddItem2Reply
+	OpenSessionRequest      = pb.OpenSessionRequest
+	OpenSessionReply        = pb.OpenSessionReply
+	CloseSessionRequest     = pb.CloseSessionRequest
+	CloseSessionReply       = pb.CloseSessionReply
+	StreamEventsRequest     = pb.StreamEventsRequest
+	MxCommandRequest        = pb.MxCommandRequest
+	MxCommandReply          = pb.MxCommandReply
+	MxCommand               = pb.MxCommand
+	MxEvent                 = pb.MxEvent
+	MxValue                 = pb.MxValue
+	Value                   = pb.MxValue
+	MxArray                 = pb.MxArray
+	MxStatusProxy           = pb.MxStatusProxy
+	ProtocolStatus          = pb.ProtocolStatus
+	RegisterCommand         = pb.RegisterCommand
+	UnregisterCommand       = pb.UnregisterCommand
+	AddItemCommand          = pb.AddItemCommand
+	AddItem2Command         = pb.AddItem2Command
+	RemoveItemCommand       = pb.RemoveItemCommand
+	AdviseCommand           = pb.AdviseCommand
+	UnAdviseCommand         = pb.UnAdviseCommand
+	AddItemBulkCommand      = pb.AddItemBulkCommand
+	AdviseItemBulkCommand   = pb.AdviseItemBulkCommand
+	RemoveItemBulkCommand   = pb.RemoveItemBulkCommand
+	UnAdviseItemBulkCommand = pb.UnAdviseItemBulkCommand
+	SubscribeBulkCommand    = pb.SubscribeBulkCommand
+	UnsubscribeBulkCommand  = pb.UnsubscribeBulkCommand
+	WriteCommand            = pb.WriteCommand
+	Write2Command           = pb.Write2Command
+	RegisterReply           = pb.RegisterReply
+	AddItemReply            = pb.AddItemReply
+	AddItem2Reply           = pb.AddItem2Reply
+	SubscribeResult         = pb.SubscribeResult
+	BulkSubscribeReply      = pb.BulkSubscribeReply
 )
 
 type (
@@ -49,13 +59,21 @@ type (
 )
 
 const (
-	CommandKindRegister   = pb.MxCommandKind_MX_COMMAND_KIND_REGISTER
-	CommandKindUnregister = pb.MxCommandKind_MX_COMMAND_KIND_UNREGISTER
-	CommandKindAddItem    = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM
-	CommandKindAddItem2   = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM2
-	CommandKindAdvise     = pb.MxCommandKind_MX_COMMAND_KIND_ADVISE
-	CommandKindWrite      = pb.MxCommandKind_MX_COMMAND_KIND_WRITE
-	CommandKindWrite2     = pb.MxCommandKind_MX_COMMAND_KIND_WRITE2
+	CommandKindRegister         = pb.MxCommandKind_MX_COMMAND_KIND_REGISTER
+	CommandKindUnregister       = pb.MxCommandKind_MX_COMMAND_KIND_UNREGISTER
+	CommandKindAddItem          = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM
+	CommandKindAddItem2         = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM2
+	CommandKindRemoveItem       = pb.MxCommandKind_MX_COMMAND_KIND_REMOVE_ITEM
+	CommandKindAdvise           = pb.MxCommandKind_MX_COMMAND_KIND_ADVISE
+	CommandKindUnAdvise         = pb.MxCommandKind_MX_COMMAND_KIND_UN_ADVISE
+	CommandKindAddItemBulk      = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM_BULK
+	CommandKindAdviseItemBulk   = pb.MxCommandKind_MX_COMMAND_KIND_ADVISE_ITEM_BULK
+	CommandKindRemoveItemBulk   = pb.MxCommandKind_MX_COMMAND_KIND_REMOVE_ITEM_BULK
+	CommandKindUnAdviseItemBulk = pb.MxCommandKind_MX_COMMAND_KIND_UN_ADVISE_ITEM_BULK
+	CommandKindSubscribeBulk    = pb.MxCommandKind_MX_COMMAND_KIND_SUBSCRIBE_BULK
+	CommandKindUnsubscribeBulk  = pb.MxCommandKind_MX_COMMAND_KIND_UNSUBSCRIBE_BULK
+	CommandKindWrite            = pb.MxCommandKind_MX_COMMAND_KIND_WRITE
+	CommandKindWrite2           = pb.MxCommandKind_MX_COMMAND_KIND_WRITE2
 
 	DataTypeUnknown = pb.MxDataType_MX_DATA_TYPE_UNKNOWN
 	DataTypeBoolean = pb.MxDataType_MX_DATA_TYPE_BOOLEAN

clients/go/mxgateway/version.go

@@ -7,7 +7,7 @@ const (
 
 	// GatewayProtocolVersion matches GatewayContractInfo.GatewayProtocolVersion
 	// in the shared .NET contracts.
-	GatewayProtocolVersion uint32 = 1
+	GatewayProtocolVersion uint32 = 2
 
 	// WorkerProtocolVersion matches GatewayContractInfo.WorkerProtocolVersion
 	// and is exposed for fake-worker and parity tests.

clients/java/README.md

@@ -27,6 +27,15 @@ generated stubs, and generated protobuf messages for parity tests.
 application entry point. The CLI supports version, session, command, event
 streaming, write, and smoke-test commands with deterministic JSON output.
 
+## Regenerating Protobuf Bindings
+
+Run generation from `clients/java` after the shared `.proto` files or Java
+output path changes:
+
+```powershell
+gradle :mxgateway-client:generateProto
+```
+
 ## Client Usage
 
 Create a client with explicit transport and auth options:
@@ -58,6 +67,99 @@ 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.
 
+## Galaxy Repository Browse
+
+The Galaxy Repository service is a separate metadata-only gRPC service exposed
+by the gateway. It lets clients enumerate the deployed Galaxy object hierarchy
+and the dynamic attributes on each object so they know which tag references to
+subscribe to via the MXAccess Gateway service. It uses the same API-key auth as
+the gateway and requires the `metadata:read` scope.
+
+`GalaxyRepositoryClient` mirrors the `MxGatewayClient` pattern (caller-managed
+or owned channel, `MxGatewayClientOptions`, blocking + async variants). Three
+RPCs are exposed:
+
+```java
+MxGatewayClientOptions options = MxGatewayClientOptions.builder()
+        .endpoint("localhost:5000")
+        .apiKey(System.getenv("MXGATEWAY_API_KEY"))
+        .plaintext(true)
+        .build();
+
+try (GalaxyRepositoryClient galaxy = GalaxyRepositoryClient.connect(options)) {
+    boolean ok = galaxy.testConnection();
+    Optional<Instant> lastDeploy = galaxy.getLastDeployTime();
+    List<GalaxyObject> hierarchy = galaxy.discoverHierarchy();
+}
+```
+
+`getLastDeployTime` returns `Optional.empty()` when the server reports
+`present=false`. `discoverHierarchy` returns the generated `GalaxyObject` proto
+messages directly so callers can read all fields (including the nested
+`GalaxyAttribute` list) without an extra DTO layer.
+
+The CLI exposes matching subcommands: `galaxy-test`, `galaxy-deploy-time`,
+`galaxy-discover`, and `galaxy-watch`. They take the same `--endpoint`,
+`--api-key-env`, `--plaintext`, `--ca-file`, `--server-name-override`,
+`--timeout`, and `--json` options as the gateway commands.
+
+```powershell
+gradle :mxgateway-cli:run --args="galaxy-test --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :mxgateway-cli:run --args="galaxy-deploy-time --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :mxgateway-cli:run --args="galaxy-discover --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+```
+
+### Watching deploy events
+
+`GalaxyRepository.WatchDeployEvents` is a server-streaming RPC: the gateway
+sends a bootstrap `DeployEvent` immediately on subscribe and then one event
+each time it observes a new `galaxy.time_of_last_deploy`. The `sequence` field
+is monotonic per server start; gaps mean the per-subscriber buffer dropped
+older events because the consumer was too slow.
+
+The client exposes both an iterator-style adaptor over the async stub and an
+observer-callback variant. Both honour the channel-level `streamTimeout`.
+
+```java
+try (GalaxyRepositoryClient galaxy = GalaxyRepositoryClient.connect(options);
+        DeployEventStream events = galaxy.watchDeployEvents(/* lastSeenDeployTime */ null)) {
+    while (events.hasNext()) {
+        DeployEvent event = events.next();
+        // event.getSequence(), event.getObservedAt(),
+        // event.getTimeOfLastDeploy() / getTimeOfLastDeployPresent(),
+        // event.getObjectCount(), event.getAttributeCount()
+    }
+}
+```
+
+Pass an `Instant` for `lastSeenDeployTime` to suppress the bootstrap event when
+the cached deploy time matches what the caller already has. `DeployEventStream`
+implements `Iterator<DeployEvent>` and `AutoCloseable`; closing it cancels the
+underlying gRPC call.
+
+For callback delivery (e.g. when the consumer wants to drive a queue or
+reactive pipeline), use the async variant:
+
+```java
+DeployEventSubscription subscription = galaxy.watchDeployEventsAsync(
+        lastSeen,
+        new StreamObserver<>() {
+            @Override public void onNext(DeployEvent value) { /* ... */ }
+            @Override public void onError(Throwable t) { /* ... */ }
+            @Override public void onCompleted() { /* ... */ }
+        });
+// later:
+subscription.cancel(); // or subscription.close()
+```
+
+The matching CLI subcommand streams events until cancelled (Ctrl+C) and prints
+one line per event in text mode or one JSON object per event with `--json`:
+
+```powershell
+gradle :mxgateway-cli:run --args="galaxy-watch --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :mxgateway-cli:run --args="galaxy-watch --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --last-seen-deploy-time 2026-04-28T18:30:00Z --limit 5"
+```
+
 ## CLI Usage
 
 Run the CLI through Gradle:
@@ -77,6 +179,12 @@ The CLI accepts `--api-key`, `--api-key-env`, `--plaintext`, `--ca-file`,
 `--server-name-override`, `--timeout`, and `--json` on gateway commands. JSON
 output redacts API keys.
 
+Use TLS options for a secured gateway:
+
+```powershell
+gradle :mxgateway-cli:run --args="smoke --endpoint mxgateway.example.local:5001 --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item TestObject.TestInt --json"
+```
+
 ## Build And Test
 
 Run the Java checks from `clients/java`:
@@ -89,8 +197,32 @@ The build uses the Java 21 Gradle toolchain, compiles generated protobuf/gRPC
 code, and runs JUnit 5 tests for the client wrapper, shared behavior fixtures,
 in-process gRPC behavior, stream cancellation, and CLI parser/output behavior.
 
+## Packaging
+
+Create local library and CLI artifacts from `clients/java`:
+
+```powershell
+gradle :mxgateway-client:jar :mxgateway-cli:installDist
+```
+
+The library jar is under `mxgateway-client/build/libs`. The installed CLI
+distribution is under `mxgateway-cli/build/install/mxgateway-cli`.
+
+## Integration Checks
+
+Run live checks only when a gateway and MXAccess-backed worker are available:
+
+```powershell
+$env:MXGATEWAY_INTEGRATION = '1'
+$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
+$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
+$env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
+gradle :mxgateway-cli:run --args="smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json"
+```
+
 ## Related Documentation
 
+- [Client Packaging](../../docs/ClientPackaging.md)
 - [Client Proto Generation](../../docs/client-proto-generation.md)
 - [Java Client Detailed Design](../../docs/clients-java-design.md)
 - [Java Style Guide](../../docs/style-guides/JavaStyleGuide.md)

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

@@ -1,5 +1,7 @@
 package com.dohertylan.mxgateway.cli;
 
+import com.dohertylan.mxgateway.client.DeployEventStream;
+import com.dohertylan.mxgateway.client.GalaxyRepositoryClient;
 import com.dohertylan.mxgateway.client.MxEventStream;
 import com.dohertylan.mxgateway.client.MxGatewayClient;
 import com.dohertylan.mxgateway.client.MxGatewayClientOptions;
@@ -7,19 +9,28 @@ import com.dohertylan.mxgateway.client.MxGatewayClientVersion;
 import com.dohertylan.mxgateway.client.MxGatewaySecrets;
 import com.dohertylan.mxgateway.client.MxGatewaySession;
 import com.dohertylan.mxgateway.client.MxValues;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GalaxyAttribute;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GalaxyObject;
 import com.google.protobuf.Message;
 import com.google.protobuf.util.JsonFormat;
 import java.io.PrintWriter;
 import java.nio.file.Path;
 import java.time.Duration;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.concurrent.Callable;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest;
 import mxaccess_gateway.v1.MxaccessGateway.MxCommandReply;
 import mxaccess_gateway.v1.MxaccessGateway.MxEvent;
 import mxaccess_gateway.v1.MxaccessGateway.MxValue;
 import mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest;
+import mxaccess_gateway.v1.MxaccessGateway.SubscribeResult;
 import picocli.CommandLine;
 import picocli.CommandLine.Command;
 import picocli.CommandLine.Mixin;
@@ -75,12 +86,200 @@ public final class MxGatewayCli implements Callable<Integer> {
         commandLine.addSubcommand("register", new RegisterCommand(clientFactory));
         commandLine.addSubcommand("add-item", new AddItemCommand(clientFactory));
         commandLine.addSubcommand("advise", new AdviseCommand(clientFactory));
+        commandLine.addSubcommand("subscribe-bulk", new SubscribeBulkCommand(clientFactory));
+        commandLine.addSubcommand("unsubscribe-bulk", new UnsubscribeBulkCommand(clientFactory));
         commandLine.addSubcommand("write", new WriteCommand(clientFactory));
         commandLine.addSubcommand("stream-events", new StreamEventsCommand(clientFactory));
         commandLine.addSubcommand("smoke", new SmokeCommand(clientFactory));
+        commandLine.addSubcommand("galaxy-test", new GalaxyTestConnectionCommand());
+        commandLine.addSubcommand("galaxy-deploy-time", new GalaxyDeployTimeCommand());
+        commandLine.addSubcommand("galaxy-discover", new GalaxyDiscoverCommand());
+        commandLine.addSubcommand("galaxy-watch", new GalaxyWatchCommand());
         return commandLine;
     }
 
+    abstract static class GalaxyCommand implements Callable<Integer> {
+        @Mixin
+        CommonOptions common = new CommonOptions();
+
+        @Option(names = "--json", description = "Write JSON output.")
+        boolean json;
+
+        GalaxyRepositoryClient connect() {
+            return GalaxyRepositoryClient.connect(common.resolved().toClientOptions());
+        }
+    }
+
+    @Command(name = "galaxy-test", description = "Calls GalaxyRepository.TestConnection.")
+    static final class GalaxyTestConnectionCommand extends GalaxyCommand {
+        @Override
+        public Integer call() {
+            try (GalaxyRepositoryClient client = connect()) {
+                boolean ok = client.testConnection();
+                PrintWriter out = common.spec.commandLine().getOut();
+                if (json) {
+                    Map<String, Object> output = new LinkedHashMap<>();
+                    output.put("command", "galaxy-test");
+                    output.put("options", common.redactedJsonMap());
+                    output.put("ok", ok);
+                    out.println(jsonObject(output));
+                } else {
+                    out.println(ok);
+                }
+            }
+            return 0;
+        }
+    }
+
+    @Command(name = "galaxy-deploy-time", description = "Calls GalaxyRepository.GetLastDeployTime.")
+    static final class GalaxyDeployTimeCommand extends GalaxyCommand {
+        @Override
+        public Integer call() {
+            try (GalaxyRepositoryClient client = connect()) {
+                Optional<Instant> result = client.getLastDeployTime();
+                PrintWriter out = common.spec.commandLine().getOut();
+                if (json) {
+                    Map<String, Object> output = new LinkedHashMap<>();
+                    output.put("command", "galaxy-deploy-time");
+                    output.put("options", common.redactedJsonMap());
+                    output.put("present", result.isPresent());
+                    output.put("timeOfLastDeploy", result.map(Instant::toString).orElse(""));
+                    out.println(jsonObject(output));
+                } else if (result.isPresent()) {
+                    out.println(result.get());
+                } else {
+                    out.println("(none)");
+                }
+            }
+            return 0;
+        }
+    }
+
+    @Command(name = "galaxy-discover", description = "Calls GalaxyRepository.DiscoverHierarchy.")
+    static final class GalaxyDiscoverCommand extends GalaxyCommand {
+        @Override
+        public Integer call() {
+            try (GalaxyRepositoryClient client = connect()) {
+                List<GalaxyObject> objects = client.discoverHierarchy();
+                PrintWriter out = common.spec.commandLine().getOut();
+                if (json) {
+                    Map<String, Object> output = new LinkedHashMap<>();
+                    output.put("command", "galaxy-discover");
+                    output.put("options", common.redactedJsonMap());
+                    output.put("objects", objects.stream().map(MxGatewayCli::galaxyObjectMap).toList());
+                    out.println(jsonObject(output));
+                } else {
+                    out.printf("count=%d%n", objects.size());
+                    for (GalaxyObject obj : objects) {
+                        out.printf("  %s [%s] attrs=%d%n",
+                                obj.getTagName(), obj.getBrowseName(), obj.getAttributesCount());
+                    }
+                }
+            }
+            return 0;
+        }
+    }
+
+    @Command(
+            name = "galaxy-watch",
+            description = "Streams GalaxyRepository.WatchDeployEvents until cancelled.")
+    static final class GalaxyWatchCommand extends GalaxyCommand {
+        @Option(
+                names = "--last-seen-deploy-time",
+                description =
+                        "Optional ISO-8601 instant. When supplied, the bootstrap event is suppressed if the cached"
+                                + " deploy time matches.")
+        String lastSeenDeployTime;
+
+        @Option(names = "--limit", defaultValue = "0", description = "Maximum events to print before exiting.")
+        int limit;
+
+        @Override
+        public Integer call() {
+            Instant after = parseInstant(lastSeenDeployTime);
+            try (GalaxyRepositoryClient client = connect();
+                    DeployEventStream events = client.watchDeployEvents(after)) {
+                PrintWriter out = common.spec.commandLine().getOut();
+                Thread shutdownHook = new Thread(events::close, "galaxy-watch-shutdown");
+                Runtime.getRuntime().addShutdownHook(shutdownHook);
+                try {
+                    int count = 0;
+                    while (events.hasNext()) {
+                        DeployEvent event = events.next();
+                        if (json) {
+                            out.println(protoJson(event));
+                        } else {
+                            out.printf(
+                                    "seq=%d observed=%s deployTime=%s objects=%d attributes=%d%n",
+                                    event.getSequence(),
+                                    formatTimestamp(event.getObservedAt()),
+                                    event.getTimeOfLastDeployPresent()
+                                            ? formatTimestamp(event.getTimeOfLastDeploy())
+                                            : "(none)",
+                                    event.getObjectCount(),
+                                    event.getAttributeCount());
+                        }
+                        out.flush();
+                        count++;
+                        if (limit > 0 && count >= limit) {
+                            events.close();
+                            break;
+                        }
+                    }
+                } finally {
+                    try {
+                        Runtime.getRuntime().removeShutdownHook(shutdownHook);
+                    } catch (IllegalStateException ignored) {
+                        // JVM is already shutting down.
+                    }
+                }
+            }
+            return 0;
+        }
+
+        private static Instant parseInstant(String value) {
+            if (value == null || value.isBlank()) {
+                return null;
+            }
+            return Instant.parse(value);
+        }
+
+        private static String formatTimestamp(com.google.protobuf.Timestamp ts) {
+            return Instant.ofEpochSecond(ts.getSeconds(), ts.getNanos()).toString();
+        }
+    }
+
+    private static Map<String, Object> galaxyObjectMap(GalaxyObject obj) {
+        Map<String, Object> values = new LinkedHashMap<>();
+        values.put("gobjectId", obj.getGobjectId());
+        values.put("tagName", obj.getTagName());
+        values.put("containedName", obj.getContainedName());
+        values.put("browseName", obj.getBrowseName());
+        values.put("parentGobjectId", obj.getParentGobjectId());
+        values.put("isArea", obj.getIsArea());
+        values.put("categoryId", obj.getCategoryId());
+        values.put("hostedByGobjectId", obj.getHostedByGobjectId());
+        values.put("templateChain", new ArrayList<>(obj.getTemplateChainList()));
+        List<Map<String, Object>> attrs = new ArrayList<>();
+        for (GalaxyAttribute attr : obj.getAttributesList()) {
+            Map<String, Object> attrMap = new LinkedHashMap<>();
+            attrMap.put("attributeName", attr.getAttributeName());
+            attrMap.put("fullTagReference", attr.getFullTagReference());
+            attrMap.put("mxDataType", attr.getMxDataType());
+            attrMap.put("dataTypeName", attr.getDataTypeName());
+            attrMap.put("isArray", attr.getIsArray());
+            attrMap.put("arrayDimension", attr.getArrayDimension());
+            attrMap.put("arrayDimensionPresent", attr.getArrayDimensionPresent());
+            attrMap.put("mxAttributeCategory", attr.getMxAttributeCategory());
+            attrMap.put("securityClassification", attr.getSecurityClassification());
+            attrMap.put("isHistorized", attr.getIsHistorized());
+            attrMap.put("isAlarm", attr.getIsAlarm());
+            attrs.add(attrMap);
+        }
+        values.put("attributes", attrs);
+        return values;
+    }
+
     @Command(name = "version", description = "Prints the Java client version.")
     public static final class VersionCommand implements Callable<Integer> {
         @Spec
@@ -243,6 +442,58 @@ public final class MxGatewayCli implements Callable<Integer> {
         }
     }
 
+    @Command(name = "subscribe-bulk", description = "Invokes MXAccess SubscribeBulk.")
+    static final class SubscribeBulkCommand extends GatewayCommand {
+        @Option(names = "--session-id", required = true, description = "Gateway session id.")
+        String sessionId;
+
+        @Option(names = "--server-handle", required = true, description = "MXAccess server handle.")
+        int serverHandle;
+
+        @Option(names = "--items", required = true, description = "Comma-separated item definitions.")
+        String items;
+
+        SubscribeBulkCommand(MxGatewayCliClientFactory clientFactory) {
+            super(clientFactory);
+        }
+
+        @Override
+        public Integer call() {
+            try (MxGatewayCliClient client = clientFactory.connect(common.resolved())) {
+                List<SubscribeResult> results =
+                        client.session(sessionId).subscribeBulk(serverHandle, parseStringList(items));
+                writeBulkOutput("subscribe-bulk", common, json, results);
+            }
+            return 0;
+        }
+    }
+
+    @Command(name = "unsubscribe-bulk", description = "Invokes MXAccess UnsubscribeBulk.")
+    static final class UnsubscribeBulkCommand extends GatewayCommand {
+        @Option(names = "--session-id", required = true, description = "Gateway session id.")
+        String sessionId;
+
+        @Option(names = "--server-handle", required = true, description = "MXAccess server handle.")
+        int serverHandle;
+
+        @Option(names = "--item-handles", required = true, description = "Comma-separated item handles.")
+        String itemHandles;
+
+        UnsubscribeBulkCommand(MxGatewayCliClientFactory clientFactory) {
+            super(clientFactory);
+        }
+
+        @Override
+        public Integer call() {
+            try (MxGatewayCliClient client = clientFactory.connect(common.resolved())) {
+                List<SubscribeResult> results =
+                        client.session(sessionId).unsubscribeBulk(serverHandle, parseIntList(itemHandles));
+                writeBulkOutput("unsubscribe-bulk", common, json, results);
+            }
+            return 0;
+        }
+    }
+
     @Command(name = "write", description = "Invokes MXAccess Write.")
     static final class WriteCommand extends GatewayCommand {
         @Option(names = "--session-id", required = true, description = "Gateway session id.")
@@ -334,25 +585,28 @@ public final class MxGatewayCli implements Callable<Integer> {
                 var session = client.openSession(OpenSessionRequest.newBuilder()
                         .setClientSessionName(clientName)
                         .build());
-                MxGatewayCliSession cliSession = client.session(session.getSessionId());
-                int serverHandle = cliSession.register(clientName);
-                int itemHandle = cliSession.addItem(serverHandle, item);
-                cliSession.advise(serverHandle, itemHandle);
-                if (json) {
-                    Map<String, Object> output = new LinkedHashMap<>();
-                    output.put("command", "smoke");
-                    output.put("options", common.redactedJsonMap());
-                    output.put("sessionId", session.getSessionId());
-                    output.put("serverHandle", serverHandle);
-                    output.put("itemHandle", itemHandle);
-                    client.out().println(jsonObject(output));
-                } else {
-                    client.out().printf(
-                            "session=%s server=%d item=%d%n", session.getSessionId(), serverHandle, itemHandle);
+                try {
+                    MxGatewayCliSession cliSession = client.session(session.getSessionId());
+                    int serverHandle = cliSession.register(clientName);
+                    int itemHandle = cliSession.addItem(serverHandle, item);
+                    cliSession.advise(serverHandle, itemHandle);
+                    if (json) {
+                        Map<String, Object> output = new LinkedHashMap<>();
+                        output.put("command", "smoke");
+                        output.put("options", common.redactedJsonMap());
+                        output.put("sessionId", session.getSessionId());
+                        output.put("serverHandle", serverHandle);
+                        output.put("itemHandle", itemHandle);
+                        client.out().println(jsonObject(output));
+                    } else {
+                        client.out().printf(
+                                "session=%s server=%d item=%d%n", session.getSessionId(), serverHandle, itemHandle);
+                    }
+                } finally {
+                    client.closeSession(CloseSessionRequest.newBuilder()
+                            .setSessionId(session.getSessionId())
+                            .build());
                 }
-                client.closeSession(CloseSessionRequest.newBuilder()
-                        .setSessionId(session.getSessionId())
-                        .build());
             }
             return 0;
         }
@@ -451,6 +705,10 @@ public final class MxGatewayCli implements Callable<Integer> {
 
         MxCommandReply writeRaw(int serverHandle, int itemHandle, MxValue value, int userId);
 
+        List<SubscribeResult> subscribeBulk(int serverHandle, List<String> items);
+
+        List<SubscribeResult> unsubscribeBulk(int serverHandle, List<Integer> itemHandles);
+
         MxEventStream streamEventsAfter(long afterWorkerSequence);
     }
 
@@ -532,6 +790,16 @@ public final class MxGatewayCli implements Callable<Integer> {
             return session.writeRaw(serverHandle, itemHandle, value, userId);
         }
 
+        @Override
+        public List<SubscribeResult> subscribeBulk(int serverHandle, List<String> items) {
+            return session.subscribeBulk(serverHandle, items);
+        }
+
+        @Override
+        public List<SubscribeResult> unsubscribeBulk(int serverHandle, List<Integer> itemHandles) {
+            return session.unsubscribeBulk(serverHandle, itemHandles);
+        }
+
         @Override
         public MxEventStream streamEventsAfter(long afterWorkerSequence) {
             return session.streamEventsAfter(afterWorkerSequence);
@@ -556,6 +824,30 @@ public final class MxGatewayCli implements Callable<Integer> {
         out.println(textSupplier.get());
     }
 
+    private static void writeBulkOutput(
+            String command, CommonOptions common, boolean json, List<SubscribeResult> results) {
+        PrintWriter out = common.spec.commandLine().getOut();
+        if (json) {
+            Map<String, Object> output = new LinkedHashMap<>();
+            output.put("command", command);
+            output.put("options", common.redactedJsonMap());
+            output.put("results", results.stream().map(MxGatewayCli::subscribeResultMap).toList());
+            out.println(jsonObject(output));
+            return;
+        }
+        out.println(results.size());
+    }
+
+    private static Map<String, Object> subscribeResultMap(SubscribeResult result) {
+        Map<String, Object> values = new LinkedHashMap<>();
+        values.put("serverHandle", result.getServerHandle());
+        values.put("tagAddress", result.getTagAddress());
+        values.put("itemHandle", result.getItemHandle());
+        values.put("wasSuccessful", result.getWasSuccessful());
+        values.put("errorMessage", result.getErrorMessage());
+        return values;
+    }
+
     private static MxValue parseValue(String type, String text) {
         return switch (type) {
             case "bool" -> MxValues.boolValue(Boolean.parseBoolean(text));
@@ -568,6 +860,17 @@ public final class MxGatewayCli implements Callable<Integer> {
         };
     }
 
+    private static List<String> parseStringList(String value) {
+        return Arrays.stream(value.split(","))
+                .map(String::trim)
+                .filter(item -> !item.isBlank())
+                .toList();
+    }
+
+    private static List<Integer> parseIntList(String value) {
+        return parseStringList(value).stream().map(Integer::parseInt).toList();
+    }
+
     private static Duration parseDuration(String value) {
         if (value == null || value.isBlank()) {
             return Duration.ofSeconds(30);
@@ -627,6 +930,20 @@ public final class MxGatewayCli implements Callable<Integer> {
         if (value instanceof Map<?, ?> map) {
             return jsonObject((Map<String, Object>) map);
         }
+        if (value instanceof Iterable<?> iterable) {
+            StringBuilder builder = new StringBuilder();
+            builder.append('[');
+            boolean first = true;
+            for (Object item : iterable) {
+                if (!first) {
+                    builder.append(',');
+                }
+                first = false;
+                builder.append(jsonValue(item));
+            }
+            builder.append(']');
+            return builder.toString();
+        }
         return jsonString(value.toString());
     }
 

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

@@ -6,6 +6,8 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import java.io.PrintWriter;
 import java.io.StringWriter;
+import java.util.ArrayList;
+import java.util.List;
 import mxaccess_gateway.v1.MxaccessGateway.AddItemReply;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest;
@@ -19,6 +21,7 @@ import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatusCode;
 import mxaccess_gateway.v1.MxaccessGateway.RegisterReply;
 import mxaccess_gateway.v1.MxaccessGateway.SessionState;
+import mxaccess_gateway.v1.MxaccessGateway.SubscribeResult;
 import org.junit.jupiter.api.Test;
 
 final class MxGatewayCliTests {
@@ -29,7 +32,7 @@ final class MxGatewayCliTests {
         assertEquals(0, run.exitCode());
         assertEquals("", run.errors());
         assertTrue(run.output().contains("mxgateway-java 0.1.0"));
-        assertTrue(run.output().contains("gatewayProtocolVersion=1"));
+        assertTrue(run.output().contains("gatewayProtocolVersion=2"));
         assertTrue(run.output().contains("workerProtocolVersion=1"));
     }
 
@@ -39,7 +42,7 @@ final class MxGatewayCliTests {
 
         assertEquals(0, run.exitCode());
         assertTrue(run.output().contains("\"clientVersion\":\"0.1.0\""));
-        assertTrue(run.output().contains("\"gatewayProtocolVersion\":1"));
+        assertTrue(run.output().contains("\"gatewayProtocolVersion\":2"));
     }
 
     @Test
@@ -100,6 +103,44 @@ final class MxGatewayCliTests {
         assertTrue(run.output().contains("\"itemHandle\":7"));
     }
 
+    @Test
+    void subscribeBulkCommandPrintsResults() {
+        CliRun run = execute(
+                new FakeClientFactory(),
+                "subscribe-bulk",
+                "--session-id",
+                "session-cli",
+                "--server-handle",
+                "42",
+                "--items",
+                "TestMachine_001.TestChangingInt,TestMachine_002.TestChangingInt",
+                "--json");
+
+        assertEquals(0, run.exitCode());
+        assertTrue(run.output().contains("\"command\":\"subscribe-bulk\""));
+        assertTrue(run.output().contains("\"itemHandle\":100"));
+        assertTrue(run.output().contains("\"tagAddress\":\"TestMachine_002.TestChangingInt\""));
+    }
+
+    @Test
+    void unsubscribeBulkCommandPrintsResults() {
+        CliRun run = execute(
+                new FakeClientFactory(),
+                "unsubscribe-bulk",
+                "--session-id",
+                "session-cli",
+                "--server-handle",
+                "42",
+                "--item-handles",
+                "100,101",
+                "--json");
+
+        assertEquals(0, run.exitCode());
+        assertTrue(run.output().contains("\"command\":\"unsubscribe-bulk\""));
+        assertTrue(run.output().contains("\"itemHandle\":101"));
+        assertTrue(run.output().contains("\"wasSuccessful\":true"));
+    }
+
     private static CliRun execute(MxGatewayCli.MxGatewayCliClientFactory factory, String... args) {
         StringWriter output = new StringWriter();
         StringWriter errors = new StringWriter();
@@ -227,6 +268,33 @@ final class MxGatewayCliTests {
                     .build();
         }
 
+        @Override
+        public List<SubscribeResult> subscribeBulk(int serverHandle, List<String> items) {
+            List<SubscribeResult> results = new ArrayList<>();
+            for (int index = 0; index < items.size(); index++) {
+                results.add(SubscribeResult.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .setTagAddress(items.get(index))
+                        .setItemHandle(100 + index)
+                        .setWasSuccessful(true)
+                        .build());
+            }
+            return results;
+        }
+
+        @Override
+        public List<SubscribeResult> unsubscribeBulk(int serverHandle, List<Integer> itemHandles) {
+            List<SubscribeResult> results = new ArrayList<>();
+            for (Integer itemHandle : itemHandles) {
+                results.add(SubscribeResult.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .setItemHandle(itemHandle)
+                        .setWasSuccessful(true)
+                        .build());
+            }
+            return results;
+        }
+
         @Override
         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

@@ -25,6 +25,7 @@ sourceSets {
             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

@@ -0,0 +1,136 @@
+package com.dohertylan.mxgateway.client;
+
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest;
+import io.grpc.Status;
+import io.grpc.StatusRuntimeException;
+import io.grpc.stub.ClientCallStreamObserver;
+import io.grpc.stub.ClientResponseObserver;
+import java.util.Iterator;
+import java.util.NoSuchElementException;
+import java.util.Objects;
+import java.util.concurrent.ArrayBlockingQueue;
+import java.util.concurrent.BlockingQueue;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+/**
+ * Iterator-style adaptor over the {@code WatchDeployEvents} server-streaming
+ * RPC. Mirrors {@link MxEventStream}: events arrive on a background gRPC thread
+ * and are buffered in a bounded blocking queue; the iterator drains them.
+ * Closing the stream cancels the underlying gRPC call.
+ */
+public final class DeployEventStream implements Iterator<DeployEvent>, AutoCloseable {
+    private static final Object END = new Object();
+
+    private final BlockingQueue<Object> queue;
+    private final AtomicBoolean closed = new AtomicBoolean();
+    private volatile ClientCallStreamObserver<WatchDeployEventsRequest> requestStream;
+    private Object next;
+
+    DeployEventStream(int capacity) {
+        queue = new ArrayBlockingQueue<>(capacity);
+    }
+
+    ClientResponseObserver<WatchDeployEventsRequest, DeployEvent> observer() {
+        return new ClientResponseObserver<>() {
+            @Override
+            public void beforeStart(ClientCallStreamObserver<WatchDeployEventsRequest> requestStream) {
+                DeployEventStream.this.requestStream = requestStream;
+                if (closed.get()) {
+                    requestStream.cancel("client cancelled deploy event stream", null);
+                }
+            }
+
+            @Override
+            public void onNext(DeployEvent value) {
+                offer(value);
+            }
+
+            @Override
+            public void onError(Throwable error) {
+                if (Status.fromThrowable(error).getCode() == Status.Code.CANCELLED && closed.get()) {
+                    offer(END);
+                    return;
+                }
+                offer(error);
+            }
+
+            @Override
+            public void onCompleted() {
+                offer(END);
+            }
+        };
+    }
+
+    @Override
+    public boolean hasNext() {
+        if (next == END) {
+            return false;
+        }
+        if (next == null) {
+            next = take();
+        }
+        if (next instanceof RuntimeException runtimeException) {
+            next = END;
+            throw runtimeException;
+        }
+        if (next instanceof Throwable throwable) {
+            next = END;
+            throw new MxGatewayException(
+                    "galaxy watch deploy events failed: " + throwable.getMessage(), throwable);
+        }
+        return next != END;
+    }
+
+    @Override
+    public DeployEvent next() {
+        if (!hasNext()) {
+            throw new NoSuchElementException();
+        }
+        Object value = next;
+        next = null;
+        return (DeployEvent) value;
+    }
+
+    @Override
+    public void close() {
+        closed.set(true);
+        ClientCallStreamObserver<WatchDeployEventsRequest> stream = requestStream;
+        if (stream != null) {
+            stream.cancel("client cancelled deploy event stream", null);
+        }
+        offer(END);
+    }
+
+    private Object take() {
+        while (true) {
+            try {
+                return queue.take();
+            } catch (InterruptedException error) {
+                Thread.currentThread().interrupt();
+                return new StatusRuntimeException(
+                        Status.CANCELLED.withDescription("interrupted while reading deploy events"));
+            }
+        }
+    }
+
+    private void offer(Object value) {
+        Objects.requireNonNull(value, "value");
+        if (value == END) {
+            if (!queue.offer(value)) {
+                queue.clear();
+                queue.offer(value);
+            }
+            return;
+        }
+        if (!queue.offer(value)) {
+            ClientCallStreamObserver<WatchDeployEventsRequest> stream = requestStream;
+            if (stream != null) {
+                stream.cancel("client deploy event stream queue overflowed", null);
+            }
+            queue.clear();
+            queue.offer(new MxGatewayException("galaxy watch deploy events queue overflowed"));
+            queue.offer(END);
+        }
+    }
+}

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

@@ -0,0 +1,60 @@
+package com.dohertylan.mxgateway.client;
+
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest;
+import io.grpc.stub.ClientCallStreamObserver;
+import io.grpc.stub.ClientResponseObserver;
+import io.grpc.stub.StreamObserver;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicReference;
+
+/**
+ * Cancellable handle returned by the async {@code watchDeployEvents} variant.
+ * Mirrors {@link MxGatewayEventSubscription} but for the Galaxy Repository
+ * deploy-event stream.
+ */
+public final class DeployEventSubscription implements AutoCloseable {
+    private final AtomicReference<ClientCallStreamObserver<WatchDeployEventsRequest>> requestStream =
+            new AtomicReference<>();
+    private final AtomicBoolean cancelled = new AtomicBoolean();
+
+    ClientResponseObserver<WatchDeployEventsRequest, DeployEvent> wrap(StreamObserver<DeployEvent> observer) {
+        return new ClientResponseObserver<>() {
+            @Override
+            public void beforeStart(ClientCallStreamObserver<WatchDeployEventsRequest> stream) {
+                requestStream.set(stream);
+                if (cancelled.get()) {
+                    stream.cancel("client cancelled deploy event stream", null);
+                }
+            }
+
+            @Override
+            public void onNext(DeployEvent value) {
+                observer.onNext(value);
+            }
+
+            @Override
+            public void onError(Throwable error) {
+                observer.onError(error);
+            }
+
+            @Override
+            public void onCompleted() {
+                observer.onCompleted();
+            }
+        };
+    }
+
+    public void cancel() {
+        cancelled.set(true);
+        ClientCallStreamObserver<WatchDeployEventsRequest> stream = requestStream.get();
+        if (stream != null) {
+            stream.cancel("client cancelled deploy event stream", null);
+        }
+    }
+
+    @Override
+    public void close() {
+        cancel();
+    }
+}

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

@@ -0,0 +1,323 @@
+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;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GalaxyObject;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest;
+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;
+import java.util.List;
+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
+ * exposes the three metadata-only RPCs of the Galaxy Repository service in
+ * idiomatic Java types. Mirrors the constructor and option-handling style of
+ * {@link MxGatewayClient}.
+ */
+public final class GalaxyRepositoryClient implements AutoCloseable {
+    private static final int DISCOVER_HIERARCHY_PAGE_SIZE = 5000;
+
+    private final ManagedChannel ownedChannel;
+    private final MxGatewayClientOptions options;
+    private final GalaxyRepositoryGrpc.GalaxyRepositoryBlockingStub blockingStub;
+    private final GalaxyRepositoryGrpc.GalaxyRepositoryFutureStub futureStub;
+    private final GalaxyRepositoryGrpc.GalaxyRepositoryStub asyncStub;
+
+    private GalaxyRepositoryClient(ManagedChannel channel, MxGatewayClientOptions options) {
+        this.ownedChannel = channel;
+        this.options = options;
+        Channel intercepted = ClientInterceptors.intercept(channel, new MxGatewayAuthInterceptor(options.apiKey()));
+        blockingStub = GalaxyRepositoryGrpc.newBlockingStub(intercepted);
+        futureStub = GalaxyRepositoryGrpc.newFutureStub(intercepted);
+        asyncStub = GalaxyRepositoryGrpc.newStub(intercepted);
+    }
+
+    /**
+     * Construct a client over a caller-managed {@link Channel}. The caller owns
+     * channel lifecycle; {@link #close()} is a no-op for this constructor.
+     */
+    public GalaxyRepositoryClient(Channel channel, MxGatewayClientOptions options) {
+        this.ownedChannel = null;
+        this.options = Objects.requireNonNull(options, "options");
+        Channel intercepted = ClientInterceptors.intercept(channel, new MxGatewayAuthInterceptor(options.apiKey()));
+        blockingStub = GalaxyRepositoryGrpc.newBlockingStub(intercepted);
+        futureStub = GalaxyRepositoryGrpc.newFutureStub(intercepted);
+        asyncStub = GalaxyRepositoryGrpc.newStub(intercepted);
+    }
+
+    /** Build a new client and own its channel; close shuts the channel down. */
+    public static GalaxyRepositoryClient connect(MxGatewayClientOptions options) {
+        return new GalaxyRepositoryClient(createChannel(options), options);
+    }
+
+    public GalaxyRepositoryGrpc.GalaxyRepositoryBlockingStub rawBlockingStub() {
+        return withDeadline(blockingStub);
+    }
+
+    public GalaxyRepositoryGrpc.GalaxyRepositoryFutureStub rawFutureStub() {
+        return withDeadline(futureStub);
+    }
+
+    public GalaxyRepositoryGrpc.GalaxyRepositoryStub rawAsyncStub() {
+        return asyncStub;
+    }
+
+    /**
+     * Invoke the {@code TestConnection} RPC and return the {@code ok} flag.
+     */
+    public boolean testConnection() {
+        try {
+            TestConnectionReply reply = rawBlockingStub().testConnection(TestConnectionRequest.getDefaultInstance());
+            return reply.getOk();
+        } catch (RuntimeException error) {
+            if (error instanceof MxGatewayException) {
+                throw error;
+            }
+            throw MxGatewayErrors.fromGrpc("galaxy test connection", error);
+        }
+    }
+
+    public CompletableFuture<Boolean> testConnectionAsync() {
+        return toCompletable(rawFutureStub().testConnection(TestConnectionRequest.getDefaultInstance()))
+                .thenApply(TestConnectionReply::getOk);
+    }
+
+    /**
+     * Invoke the {@code GetLastDeployTime} RPC. Returns {@link Optional#empty()}
+     * when the server reports {@code present=false}.
+     */
+    public Optional<Instant> getLastDeployTime() {
+        try {
+            GetLastDeployTimeReply reply =
+                    rawBlockingStub().getLastDeployTime(GetLastDeployTimeRequest.getDefaultInstance());
+            return mapDeployTime(reply);
+        } catch (RuntimeException error) {
+            if (error instanceof MxGatewayException) {
+                throw error;
+            }
+            throw MxGatewayErrors.fromGrpc("galaxy get last deploy time", error);
+        }
+    }
+
+    public CompletableFuture<Optional<Instant>> getLastDeployTimeAsync() {
+        return toCompletable(rawFutureStub().getLastDeployTime(GetLastDeployTimeRequest.getDefaultInstance()))
+                .thenApply(GalaxyRepositoryClient::mapDeployTime);
+    }
+
+    /**
+     * Invoke the {@code DiscoverHierarchy} RPC and return the generated
+     * {@link GalaxyObject} messages directly. Callers can read every field of
+     * the proto message without an extra DTO layer.
+     */
+    public List<GalaxyObject> discoverHierarchy() {
+        try {
+            java.util.ArrayList<GalaxyObject> objects = new java.util.ArrayList<>();
+            java.util.HashSet<String> seenPageTokens = new java.util.HashSet<>();
+            String pageToken = "";
+            do {
+                DiscoverHierarchyReply reply = rawBlockingStub().discoverHierarchy(DiscoverHierarchyRequest.newBuilder()
+                        .setPageSize(DISCOVER_HIERARCHY_PAGE_SIZE)
+                        .setPageToken(pageToken)
+                        .build());
+                objects.addAll(reply.getObjectsList());
+                pageToken = reply.getNextPageToken();
+                if (!pageToken.isBlank() && !seenPageTokens.add(pageToken)) {
+                    throw new MxGatewayException(
+                            "galaxy discover hierarchy returned repeated page token: " + pageToken);
+                }
+            } while (!pageToken.isBlank());
+            return objects;
+        } catch (RuntimeException error) {
+            if (error instanceof MxGatewayException) {
+                throw error;
+            }
+            throw MxGatewayErrors.fromGrpc("galaxy discover hierarchy", error);
+        }
+    }
+
+    public CompletableFuture<List<GalaxyObject>> discoverHierarchyAsync() {
+        return discoverHierarchyPageAsync("", new java.util.ArrayList<>(), new java.util.HashSet<>());
+    }
+
+    /**
+     * Subscribe to {@code WatchDeployEvents} via the async stub and consume
+     * results through a blocking iterator. Closing the returned stream cancels
+     * the underlying gRPC call.
+     *
+     * @param lastSeenDeployTime optional. When non-null, the bootstrap event is
+     *     suppressed if the cached deploy time matches.
+     */
+    public DeployEventStream watchDeployEvents(Instant lastSeenDeployTime) {
+        DeployEventStream stream = new DeployEventStream(16);
+        withStreamDeadline(rawAsyncStub()).watchDeployEvents(buildWatchRequest(lastSeenDeployTime), stream.observer());
+        return stream;
+    }
+
+    /**
+     * Iterator-style alias for {@link #watchDeployEvents(Instant)} matching the
+     * task-spec signature.
+     */
+    public Iterator<DeployEvent> watchDeployEventsIterator(Instant lastSeenDeployTime) {
+        return watchDeployEvents(lastSeenDeployTime);
+    }
+
+    /**
+     * Subscribe to {@code WatchDeployEvents} via the async stub, dispatching
+     * each event to {@code observer}. The returned subscription is cancellable
+     * and {@link AutoCloseable}.
+     */
+    public DeployEventSubscription watchDeployEventsAsync(
+            Instant lastSeenDeployTime, StreamObserver<DeployEvent> observer) {
+        Objects.requireNonNull(observer, "observer");
+        DeployEventSubscription subscription = new DeployEventSubscription();
+        withStreamDeadline(rawAsyncStub())
+                .watchDeployEvents(buildWatchRequest(lastSeenDeployTime), subscription.wrap(observer));
+        return subscription;
+    }
+
+    private static WatchDeployEventsRequest buildWatchRequest(Instant lastSeenDeployTime) {
+        WatchDeployEventsRequest.Builder builder = WatchDeployEventsRequest.newBuilder();
+        if (lastSeenDeployTime != null) {
+            builder.setLastSeenDeployTime(Timestamp.newBuilder()
+                    .setSeconds(lastSeenDeployTime.getEpochSecond())
+                    .setNanos(lastSeenDeployTime.getNano())
+                    .build());
+        }
+        return builder.build();
+    }
+
+    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);
+    }
+
+    @Override
+    public void close() {
+        if (ownedChannel != null) {
+            ownedChannel.shutdown();
+        }
+    }
+
+    public void closeAndAwaitTermination() throws InterruptedException {
+        if (ownedChannel != null) {
+            ownedChannel.shutdown();
+            if (!ownedChannel.awaitTermination(options.connectTimeout().toMillis(), TimeUnit.MILLISECONDS)) {
+                ownedChannel.shutdownNow();
+            }
+        }
+    }
+
+    private static Optional<Instant> mapDeployTime(GetLastDeployTimeReply reply) {
+        if (!reply.getPresent()) {
+            return Optional.empty();
+        }
+        Timestamp ts = reply.getTimeOfLastDeploy();
+        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 -> {
+            objects.addAll(reply.getObjectsList());
+            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);
+                    }
+
+                    @Override
+                    public void onFailure(Throwable error) {
+                        if (error instanceof RuntimeException runtimeException) {
+                            target.completeExceptionally(MxGatewayErrors.fromGrpc("galaxy async call", runtimeException));
+                            return;
+                        }
+                        target.completeExceptionally(error);
+                    }
+                },
+                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/MxEventStream.java

@@ -105,13 +105,20 @@ public final class MxEventStream implements Iterator<MxEvent>, AutoCloseable {
     private void offer(Object value) {
         Objects.requireNonNull(value, "value");
         if (value == END) {
-            queue.offer(value);
+            if (!queue.offer(value)) {
+                queue.clear();
+                queue.offer(value);
+            }
             return;
         }
-        try {
-            queue.put(value);
-        } catch (InterruptedException error) {
-            Thread.currentThread().interrupt();
+        if (!queue.offer(value)) {
+            ClientCallStreamObserver<StreamEventsRequest> stream = requestStream;
+            if (stream != null) {
+                stream.cancel("client event stream queue overflowed", null);
+            }
+            queue.clear();
+            queue.offer(new MxGatewayException("gateway stream events queue overflowed"));
+            queue.offer(END);
         }
     }
 }

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

@@ -63,7 +63,7 @@ public final class MxGatewayClient implements AutoCloseable {
     }
 
     public MxAccessGatewayGrpc.MxAccessGatewayStub rawAsyncStub() {
-        return withDeadline(asyncStub);
+        return asyncStub;
     }
 
     public MxGatewaySession openSession(OpenSessionRequest request) {
@@ -140,14 +140,14 @@ public final class MxGatewayClient implements AutoCloseable {
 
     public MxEventStream streamEvents(StreamEventsRequest request) {
         MxEventStream stream = new MxEventStream(16);
-        rawAsyncStub().streamEvents(request, stream.observer());
+        withStreamDeadline(rawAsyncStub()).streamEvents(request, stream.observer());
         return stream;
     }
 
     public MxGatewayEventSubscription streamEventsAsync(
             StreamEventsRequest request, StreamObserver<MxEvent> observer) {
         MxGatewayEventSubscription subscription = new MxGatewayEventSubscription();
-        rawAsyncStub().streamEvents(request, subscription.wrap(observer));
+        withStreamDeadline(rawAsyncStub()).streamEvents(request, subscription.wrap(observer));
         return subscription;
     }
 
@@ -161,13 +161,15 @@ public final class MxGatewayClient implements AutoCloseable {
     public void closeAndAwaitTermination() throws InterruptedException {
         if (ownedChannel != null) {
             ownedChannel.shutdown();
-            ownedChannel.awaitTermination(options.connectTimeout().toMillis(), TimeUnit.MILLISECONDS);
+            if (!ownedChannel.awaitTermination(options.connectTimeout().toMillis(), TimeUnit.MILLISECONDS)) {
+                ownedChannel.shutdownNow();
+            }
         }
     }
 
     private static ManagedChannel createChannel(MxGatewayClientOptions options) {
         NettyChannelBuilder builder = NettyChannelBuilder.forTarget(options.endpoint())
-                .maxInboundMessageSize(16 * 1024 * 1024);
+                .maxInboundMessageSize(options.maxGrpcMessageBytes());
         if (!options.connectTimeout().isNegative()) {
             builder.withOption(
                     io.grpc.netty.shaded.io.netty.channel.ChannelOption.CONNECT_TIMEOUT_MILLIS,
@@ -199,6 +201,13 @@ public final class MxGatewayClient implements AutoCloseable {
         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(
@@ -219,6 +228,11 @@ public final class MxGatewayClient implements AutoCloseable {
                     }
                 },
                 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/MxGatewayClientOptions.java

@@ -7,6 +7,7 @@ import java.util.Objects;
 public final class MxGatewayClientOptions {
     private static final Duration DEFAULT_CONNECT_TIMEOUT = Duration.ofSeconds(10);
     private static final Duration DEFAULT_CALL_TIMEOUT = Duration.ofSeconds(30);
+    private static final int DEFAULT_MAX_GRPC_MESSAGE_BYTES = 16 * 1024 * 1024;
 
     private final String endpoint;
     private final String apiKey;
@@ -15,6 +16,8 @@ public final class MxGatewayClientOptions {
     private final String serverNameOverride;
     private final Duration connectTimeout;
     private final Duration callTimeout;
+    private final Duration streamTimeout;
+    private final int maxGrpcMessageBytes;
 
     private MxGatewayClientOptions(Builder builder) {
         endpoint = requireText(builder.endpoint, "endpoint");
@@ -24,6 +27,10 @@ public final class MxGatewayClientOptions {
         serverNameOverride = builder.serverNameOverride == null ? "" : builder.serverNameOverride;
         connectTimeout = builder.connectTimeout == null ? DEFAULT_CONNECT_TIMEOUT : builder.connectTimeout;
         callTimeout = builder.callTimeout == null ? DEFAULT_CALL_TIMEOUT : builder.callTimeout;
+        streamTimeout = builder.streamTimeout;
+        maxGrpcMessageBytes = builder.maxGrpcMessageBytes <= 0
+                ? DEFAULT_MAX_GRPC_MESSAGE_BYTES
+                : builder.maxGrpcMessageBytes;
     }
 
     public static Builder builder() {
@@ -62,6 +69,14 @@ public final class MxGatewayClientOptions {
         return callTimeout;
     }
 
+    public Duration streamTimeout() {
+        return streamTimeout;
+    }
+
+    public int maxGrpcMessageBytes() {
+        return maxGrpcMessageBytes;
+    }
+
     @Override
     public String toString() {
         return "MxGatewayClientOptions{"
@@ -82,6 +97,10 @@ public final class MxGatewayClientOptions {
                 + connectTimeout
                 + ", callTimeout="
                 + callTimeout
+                + ", streamTimeout="
+                + streamTimeout
+                + ", maxGrpcMessageBytes="
+                + maxGrpcMessageBytes
                 + '}';
     }
 
@@ -100,6 +119,8 @@ public final class MxGatewayClientOptions {
         private String serverNameOverride;
         private Duration connectTimeout;
         private Duration callTimeout;
+        private Duration streamTimeout;
+        private int maxGrpcMessageBytes;
 
         private Builder() {
         }
@@ -139,6 +160,16 @@ public final class MxGatewayClientOptions {
             return this;
         }
 
+        public Builder streamTimeout(Duration value) {
+            streamTimeout = Objects.requireNonNull(value, "streamTimeout");
+            return this;
+        }
+
+        public Builder maxGrpcMessageBytes(int value) {
+            maxGrpcMessageBytes = value;
+            return this;
+        }
+
         public MxGatewayClientOptions build() {
             return new MxGatewayClientOptions(this);
         }

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

@@ -1,7 +1,7 @@
 package com.dohertylan.mxgateway.client;
 
 public final class MxGatewayClientVersion {
-    private static final int GATEWAY_PROTOCOL_VERSION = 1;
+    private static final int GATEWAY_PROTOCOL_VERSION = 2;
     private static final int WORKER_PROTOCOL_VERSION = 1;
     private static final String CLIENT_VERSION = "0.1.0";
 

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

@@ -4,17 +4,22 @@ import io.grpc.stub.ClientCallStreamObserver;
 import io.grpc.stub.ClientResponseObserver;
 import io.grpc.stub.StreamObserver;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.concurrent.atomic.AtomicBoolean;
 import mxaccess_gateway.v1.MxaccessGateway.MxEvent;
 import mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest;
 
 public final class MxGatewayEventSubscription implements AutoCloseable {
     private final AtomicReference<ClientCallStreamObserver<StreamEventsRequest>> requestStream = new AtomicReference<>();
+    private final AtomicBoolean cancelled = new AtomicBoolean();
 
     ClientResponseObserver<StreamEventsRequest, MxEvent> wrap(StreamObserver<MxEvent> observer) {
         return new ClientResponseObserver<>() {
             @Override
             public void beforeStart(ClientCallStreamObserver<StreamEventsRequest> stream) {
                 requestStream.set(stream);
+                if (cancelled.get()) {
+                    stream.cancel("client cancelled event stream", null);
+                }
             }
 
             @Override
@@ -35,6 +40,7 @@ public final class MxGatewayEventSubscription implements AutoCloseable {
     }
 
     public void cancel() {
+        cancelled.set(true);
         ClientCallStreamObserver<StreamEventsRequest> stream = requestStream.get();
         if (stream != null) {
             stream.cancel("client cancelled event stream", null);

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

@@ -2,9 +2,12 @@ package com.dohertylan.mxgateway.client;
 
 import java.security.SecureRandom;
 import java.util.HexFormat;
+import java.util.List;
 import java.util.Objects;
 import mxaccess_gateway.v1.MxaccessGateway.AddItem2Command;
+import mxaccess_gateway.v1.MxaccessGateway.AddItemBulkCommand;
 import mxaccess_gateway.v1.MxaccessGateway.AddItemCommand;
+import mxaccess_gateway.v1.MxaccessGateway.AdviseItemBulkCommand;
 import mxaccess_gateway.v1.MxaccessGateway.AdviseCommand;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest;
@@ -15,7 +18,14 @@ import mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest;
 import mxaccess_gateway.v1.MxaccessGateway.MxValue;
 import mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply;
 import mxaccess_gateway.v1.MxaccessGateway.RegisterCommand;
+import mxaccess_gateway.v1.MxaccessGateway.RemoveItemBulkCommand;
+import mxaccess_gateway.v1.MxaccessGateway.RemoveItemCommand;
 import mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest;
+import mxaccess_gateway.v1.MxaccessGateway.SubscribeBulkCommand;
+import mxaccess_gateway.v1.MxaccessGateway.SubscribeResult;
+import mxaccess_gateway.v1.MxaccessGateway.UnAdviseCommand;
+import mxaccess_gateway.v1.MxaccessGateway.UnAdviseItemBulkCommand;
+import mxaccess_gateway.v1.MxaccessGateway.UnsubscribeBulkCommand;
 import mxaccess_gateway.v1.MxaccessGateway.UnregisterCommand;
 import mxaccess_gateway.v1.MxaccessGateway.Write2Command;
 import mxaccess_gateway.v1.MxaccessGateway.WriteCommand;
@@ -117,6 +127,19 @@ public final class MxGatewaySession implements AutoCloseable {
                 .build());
     }
 
+    public void removeItem(int serverHandle, int itemHandle) {
+        removeItemRaw(serverHandle, itemHandle);
+    }
+
+    public MxCommandReply removeItemRaw(int serverHandle, int itemHandle) {
+        return invokeCommand(MxCommand.newBuilder()
+                .setKind(MxCommandKind.MX_COMMAND_KIND_REMOVE_ITEM)
+                .setRemoveItem(RemoveItemCommand.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .setItemHandle(itemHandle))
+                .build());
+    }
+
     public void advise(int serverHandle, int itemHandle) {
         adviseRaw(serverHandle, itemHandle);
     }
@@ -130,6 +153,85 @@ public final class MxGatewaySession implements AutoCloseable {
                 .build());
     }
 
+    public void unAdvise(int serverHandle, int itemHandle) {
+        unAdviseRaw(serverHandle, itemHandle);
+    }
+
+    public MxCommandReply unAdviseRaw(int serverHandle, int itemHandle) {
+        return invokeCommand(MxCommand.newBuilder()
+                .setKind(MxCommandKind.MX_COMMAND_KIND_UN_ADVISE)
+                .setUnAdvise(UnAdviseCommand.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .setItemHandle(itemHandle))
+                .build());
+    }
+
+    public List<SubscribeResult> addItemBulk(int serverHandle, List<String> tagAddresses) {
+        Objects.requireNonNull(tagAddresses, "tagAddresses");
+        MxCommandReply reply = invokeCommand(MxCommand.newBuilder()
+                .setKind(MxCommandKind.MX_COMMAND_KIND_ADD_ITEM_BULK)
+                .setAddItemBulk(AddItemBulkCommand.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .addAllTagAddresses(tagAddresses))
+                .build());
+        return reply.getAddItemBulk().getResultsList();
+    }
+
+    public List<SubscribeResult> adviseItemBulk(int serverHandle, List<Integer> itemHandles) {
+        Objects.requireNonNull(itemHandles, "itemHandles");
+        MxCommandReply reply = invokeCommand(MxCommand.newBuilder()
+                .setKind(MxCommandKind.MX_COMMAND_KIND_ADVISE_ITEM_BULK)
+                .setAdviseItemBulk(AdviseItemBulkCommand.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .addAllItemHandles(itemHandles))
+                .build());
+        return reply.getAdviseItemBulk().getResultsList();
+    }
+
+    public List<SubscribeResult> removeItemBulk(int serverHandle, List<Integer> itemHandles) {
+        Objects.requireNonNull(itemHandles, "itemHandles");
+        MxCommandReply reply = invokeCommand(MxCommand.newBuilder()
+                .setKind(MxCommandKind.MX_COMMAND_KIND_REMOVE_ITEM_BULK)
+                .setRemoveItemBulk(RemoveItemBulkCommand.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .addAllItemHandles(itemHandles))
+                .build());
+        return reply.getRemoveItemBulk().getResultsList();
+    }
+
+    public List<SubscribeResult> unAdviseItemBulk(int serverHandle, List<Integer> itemHandles) {
+        Objects.requireNonNull(itemHandles, "itemHandles");
+        MxCommandReply reply = invokeCommand(MxCommand.newBuilder()
+                .setKind(MxCommandKind.MX_COMMAND_KIND_UN_ADVISE_ITEM_BULK)
+                .setUnAdviseItemBulk(UnAdviseItemBulkCommand.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .addAllItemHandles(itemHandles))
+                .build());
+        return reply.getUnAdviseItemBulk().getResultsList();
+    }
+
+    public List<SubscribeResult> subscribeBulk(int serverHandle, List<String> tagAddresses) {
+        Objects.requireNonNull(tagAddresses, "tagAddresses");
+        MxCommandReply reply = invokeCommand(MxCommand.newBuilder()
+                .setKind(MxCommandKind.MX_COMMAND_KIND_SUBSCRIBE_BULK)
+                .setSubscribeBulk(SubscribeBulkCommand.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .addAllTagAddresses(tagAddresses))
+                .build());
+        return reply.getSubscribeBulk().getResultsList();
+    }
+
+    public List<SubscribeResult> unsubscribeBulk(int serverHandle, List<Integer> itemHandles) {
+        Objects.requireNonNull(itemHandles, "itemHandles");
+        MxCommandReply reply = invokeCommand(MxCommand.newBuilder()
+                .setKind(MxCommandKind.MX_COMMAND_KIND_UNSUBSCRIBE_BULK)
+                .setUnsubscribeBulk(UnsubscribeBulkCommand.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .addAllItemHandles(itemHandles))
+                .build());
+        return reply.getUnsubscribeBulk().getResultsList();
+    }
+
     public void write(int serverHandle, int itemHandle, MxValue value, int userId) {
         writeRaw(serverHandle, itemHandle, value, userId);
     }

clients/java/mxgateway-client/src/test/java/com/dohertylan/mxgateway/client/GalaxyRepositoryClientTests.java

@@ -0,0 +1,426 @@
+package com.dohertylan.mxgateway.client;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import com.google.protobuf.Timestamp;
+import galaxy_repository.v1.GalaxyRepositoryGrpc;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GalaxyAttribute;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GalaxyObject;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest;
+import io.grpc.ManagedChannel;
+import io.grpc.Metadata;
+import io.grpc.Server;
+import io.grpc.ServerCall;
+import io.grpc.ServerCallHandler;
+import io.grpc.ServerInterceptor;
+import io.grpc.inprocess.InProcessChannelBuilder;
+import io.grpc.inprocess.InProcessServerBuilder;
+import io.grpc.stub.ClientCallStreamObserver;
+import io.grpc.stub.ClientResponseObserver;
+import io.grpc.stub.StreamObserver;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicReference;
+import org.junit.jupiter.api.Test;
+
+final class GalaxyRepositoryClientTests {
+    @Test
+    void testConnectionReturnsOkAndSendsAuthMetadata() throws Exception {
+        AtomicReference<String> authorization = new AtomicReference<>();
+        TestService service = new TestService() {
+            @Override
+            public void testConnection(
+                    TestConnectionRequest request, StreamObserver<TestConnectionReply> responseObserver) {
+                responseObserver.onNext(TestConnectionReply.newBuilder().setOk(true).build());
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, authorization);
+                GalaxyRepositoryClient client = g.client("mxgw_galaxy_secret")) {
+            assertTrue(client.testConnection());
+            assertEquals("Bearer mxgw_galaxy_secret", authorization.get());
+        }
+    }
+
+    @Test
+    void getLastDeployTimeReturnsEmptyWhenPresentFalse() throws Exception {
+        TestService service = new TestService() {
+            @Override
+            public void getLastDeployTime(
+                    GetLastDeployTimeRequest request, StreamObserver<GetLastDeployTimeReply> responseObserver) {
+                responseObserver.onNext(
+                        GetLastDeployTimeReply.newBuilder().setPresent(false).build());
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            Optional<Instant> result = client.getLastDeployTime();
+            assertFalse(result.isPresent());
+        }
+    }
+
+    @Test
+    void getLastDeployTimeReturnsInstantWhenPresent() throws Exception {
+        Timestamp expected = Timestamp.newBuilder().setSeconds(1_700_000_000L).setNanos(123_000_000).build();
+        TestService service = new TestService() {
+            @Override
+            public void getLastDeployTime(
+                    GetLastDeployTimeRequest request, StreamObserver<GetLastDeployTimeReply> responseObserver) {
+                responseObserver.onNext(GetLastDeployTimeReply.newBuilder()
+                        .setPresent(true)
+                        .setTimeOfLastDeploy(expected)
+                        .build());
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            Optional<Instant> result = client.getLastDeployTime();
+            assertTrue(result.isPresent());
+            assertEquals(Instant.ofEpochSecond(1_700_000_000L, 123_000_000), result.get());
+        }
+    }
+
+    @Test
+    void discoverHierarchyReturnsObjectsAndAttributes() throws Exception {
+        AtomicReference<DiscoverHierarchyRequest> firstRequest = new AtomicReference<>();
+        AtomicReference<DiscoverHierarchyRequest> secondRequest = new AtomicReference<>();
+        TestService service = new TestService() {
+            @Override
+            public void discoverHierarchy(
+                    DiscoverHierarchyRequest request, StreamObserver<DiscoverHierarchyReply> responseObserver) {
+                if (request.getPageToken().isEmpty()) {
+                    firstRequest.set(request);
+                    responseObserver.onNext(DiscoverHierarchyReply.newBuilder()
+                            .setNextPageToken("page-2")
+                            .setTotalObjectCount(2)
+                            .addObjects(GalaxyObject.newBuilder()
+                                    .setGobjectId(7)
+                                    .setTagName("Pump_001")
+                                    .setContainedName("Pump")
+                                    .setBrowseName("Pump")
+                                    .setParentGobjectId(1)
+                                    .setIsArea(false)
+                                    .setCategoryId(3)
+                                    .setHostedByGobjectId(0)
+                                    .addTemplateChain("$Pump")
+                                    .addAttributes(GalaxyAttribute.newBuilder()
+                                            .setAttributeName("Speed")
+                                            .setFullTagReference("Pump_001.Speed")
+                                            .setMxDataType(5)
+                                            .setDataTypeName("MxFloat")
+                                            .setIsArray(false)
+                                            .setIsHistorized(true)))
+                            .build());
+                } else {
+                    secondRequest.set(request);
+                    responseObserver.onNext(DiscoverHierarchyReply.newBuilder()
+                            .setTotalObjectCount(2)
+                            .addObjects(GalaxyObject.newBuilder()
+                                    .setGobjectId(8)
+                                    .setTagName("Pump_002"))
+                            .build());
+                }
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            List<GalaxyObject> objects = client.discoverHierarchy();
+            assertEquals(2, objects.size());
+            assertEquals(5000, firstRequest.get().getPageSize());
+            assertEquals("", firstRequest.get().getPageToken());
+            assertEquals("page-2", secondRequest.get().getPageToken());
+            GalaxyObject only = objects.get(0);
+            assertEquals(7, only.getGobjectId());
+            assertEquals("Pump_001", only.getTagName());
+            assertEquals(1, only.getAttributesCount());
+            assertEquals("Pump_001.Speed", only.getAttributes(0).getFullTagReference());
+            assertTrue(only.getAttributes(0).getIsHistorized());
+        }
+    }
+
+    @Test
+    void deployEventStreamCloseBeforeBeforeStartCancelsStream() {
+        DeployEventStream stream = new DeployEventStream(4);
+        ClientResponseObserver<WatchDeployEventsRequest, DeployEvent> observer = stream.observer();
+        RecordingClientCallStreamObserver requestStream = new RecordingClientCallStreamObserver();
+
+        stream.close();
+        observer.beforeStart(requestStream);
+
+        assertTrue(requestStream.cancelled);
+        assertEquals("client cancelled deploy event stream", requestStream.cancelMessage);
+        assertFalse(stream.hasNext());
+    }
+
+    @Test
+    void discoverHierarchyRejectsRepeatedPageToken() throws Exception {
+        TestService service = new TestService() {
+            @Override
+            public void discoverHierarchy(
+                    DiscoverHierarchyRequest request, StreamObserver<DiscoverHierarchyReply> responseObserver) {
+                responseObserver.onNext(DiscoverHierarchyReply.newBuilder()
+                        .setNextPageToken("7:1")
+                        .build());
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            MxGatewayException error = assertThrows(MxGatewayException.class, client::discoverHierarchy);
+
+            assertTrue(error.getMessage().contains("repeated page token"));
+        }
+    }
+
+    @Test
+    void watchDeployEventsReceivesEventsInOrder() throws Exception {
+        DeployEvent first = DeployEvent.newBuilder()
+                .setSequence(1)
+                .setObservedAt(Timestamp.newBuilder().setSeconds(1_700_000_000L).build())
+                .setTimeOfLastDeploy(Timestamp.newBuilder().setSeconds(1_699_999_000L).build())
+                .setTimeOfLastDeployPresent(true)
+                .setObjectCount(42)
+                .setAttributeCount(123)
+                .build();
+        DeployEvent second = DeployEvent.newBuilder()
+                .setSequence(2)
+                .setObservedAt(Timestamp.newBuilder().setSeconds(1_700_000_100L).build())
+                .setTimeOfLastDeployPresent(false)
+                .setObjectCount(43)
+                .setAttributeCount(125)
+                .build();
+
+        TestService service = new TestService() {
+            @Override
+            public void watchDeployEvents(
+                    WatchDeployEventsRequest request, StreamObserver<DeployEvent> responseObserver) {
+                responseObserver.onNext(first);
+                responseObserver.onNext(second);
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            try (DeployEventStream stream = client.watchDeployEvents(null)) {
+                assertTrue(stream.hasNext());
+                DeployEvent event1 = stream.next();
+                assertEquals(1L, event1.getSequence());
+                assertEquals(42, event1.getObjectCount());
+                assertTrue(event1.getTimeOfLastDeployPresent());
+
+                assertTrue(stream.hasNext());
+                DeployEvent event2 = stream.next();
+                assertEquals(2L, event2.getSequence());
+                assertFalse(event2.getTimeOfLastDeployPresent());
+
+                assertFalse(stream.hasNext());
+            }
+        }
+    }
+
+    @Test
+    void watchDeployEventsPropagatesLastSeenDeployTime() throws Exception {
+        AtomicReference<WatchDeployEventsRequest> seen = new AtomicReference<>();
+        Instant lastSeen = Instant.ofEpochSecond(1_700_000_000L, 250_000_000);
+
+        TestService service = new TestService() {
+            @Override
+            public void watchDeployEvents(
+                    WatchDeployEventsRequest request, StreamObserver<DeployEvent> responseObserver) {
+                seen.set(request);
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            try (DeployEventStream stream = client.watchDeployEvents(lastSeen)) {
+                assertFalse(stream.hasNext());
+            }
+        }
+
+        WatchDeployEventsRequest request = seen.get();
+        assertNotNull(request);
+        Timestamp expected = request.getLastSeenDeployTime();
+        assertEquals(lastSeen.getEpochSecond(), expected.getSeconds());
+        assertEquals(lastSeen.getNano(), expected.getNanos());
+    }
+
+    @Test
+    void watchDeployEventsClientCancellationTearsDownCleanly() throws Exception {
+        CountDownLatch cancelObserved = new CountDownLatch(1);
+
+        TestService service = new TestService() {
+            @Override
+            public void watchDeployEvents(
+                    WatchDeployEventsRequest request, StreamObserver<DeployEvent> responseObserver) {
+                io.grpc.stub.ServerCallStreamObserver<DeployEvent> serverObserver =
+                        (io.grpc.stub.ServerCallStreamObserver<DeployEvent>) responseObserver;
+                serverObserver.setOnCancelHandler(cancelObserved::countDown);
+
+                DeployEvent bootstrap = DeployEvent.newBuilder()
+                        .setSequence(1)
+                        .setObservedAt(Timestamp.newBuilder().setSeconds(1L).build())
+                        .build();
+                responseObserver.onNext(bootstrap);
+                // Server holds the stream open; cancellation must come from the client.
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            DeployEventStream stream = client.watchDeployEvents(null);
+            assertTrue(stream.hasNext());
+            assertEquals(1L, stream.next().getSequence());
+
+            stream.close();
+            assertTrue(
+                    cancelObserved.await(5, TimeUnit.SECONDS),
+                    "server should observe client-side cancellation");
+            assertFalse(stream.hasNext());
+        }
+    }
+
+    private abstract static class TestService extends GalaxyRepositoryGrpc.GalaxyRepositoryImplBase {
+        @Override
+        public void testConnection(
+                TestConnectionRequest request, StreamObserver<TestConnectionReply> responseObserver) {
+            responseObserver.onNext(TestConnectionReply.newBuilder().setOk(true).build());
+            responseObserver.onCompleted();
+        }
+
+        @Override
+        public void getLastDeployTime(
+                GetLastDeployTimeRequest request, StreamObserver<GetLastDeployTimeReply> responseObserver) {
+            responseObserver.onNext(GetLastDeployTimeReply.newBuilder().setPresent(false).build());
+            responseObserver.onCompleted();
+        }
+
+        @Override
+        public void discoverHierarchy(
+                DiscoverHierarchyRequest request, StreamObserver<DiscoverHierarchyReply> responseObserver) {
+            responseObserver.onNext(DiscoverHierarchyReply.getDefaultInstance());
+            responseObserver.onCompleted();
+        }
+
+        @Override
+        public void watchDeployEvents(
+                WatchDeployEventsRequest request, StreamObserver<DeployEvent> responseObserver) {
+            responseObserver.onCompleted();
+        }
+    }
+
+    private static final class RecordingClientCallStreamObserver
+            extends ClientCallStreamObserver<WatchDeployEventsRequest> {
+        private boolean cancelled;
+        private String cancelMessage;
+
+        @Override
+        public boolean isReady() {
+            return true;
+        }
+
+        @Override
+        public void setOnReadyHandler(Runnable onReadyHandler) {
+        }
+
+        @Override
+        public void disableAutoInboundFlowControl() {
+        }
+
+        @Override
+        public void request(int count) {
+        }
+
+        @Override
+        public void setMessageCompression(boolean enable) {
+        }
+
+        @Override
+        public void cancel(String message, Throwable cause) {
+            cancelled = true;
+            cancelMessage = message;
+        }
+
+        @Override
+        public void onNext(WatchDeployEventsRequest value) {
+        }
+
+        @Override
+        public void onError(Throwable error) {
+        }
+
+        @Override
+        public void onCompleted() {
+        }
+    }
+
+    private record InProcessGalaxy(Server server, ManagedChannel channel) implements AutoCloseable {
+        static InProcessGalaxy start(
+                GalaxyRepositoryGrpc.GalaxyRepositoryImplBase service, AtomicReference<String> authorization)
+                throws Exception {
+            String serverName = "mxgw-galaxy-java-" + UUID.randomUUID();
+            ServerInterceptor interceptor = new ServerInterceptor() {
+                @Override
+                public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
+                        ServerCall<ReqT, RespT> call,
+                        Metadata headers,
+                        ServerCallHandler<ReqT, RespT> next) {
+                    authorization.set(headers.get(MxGatewayAuthInterceptor.AUTHORIZATION_HEADER));
+                    return next.startCall(call, headers);
+                }
+            };
+            Server server = InProcessServerBuilder.forName(serverName)
+                    .directExecutor()
+                    .addService(io.grpc.ServerInterceptors.intercept(service, interceptor))
+                    .build()
+                    .start();
+            ManagedChannel channel = InProcessChannelBuilder.forName(serverName)
+                    .directExecutor()
+                    .build();
+            return new InProcessGalaxy(server, channel);
+        }
+
+        GalaxyRepositoryClient client(String apiKey) {
+            return new GalaxyRepositoryClient(
+                    channel,
+                    MxGatewayClientOptions.builder()
+                            .endpoint("in-process")
+                            .apiKey(apiKey)
+                            .plaintext(true)
+                            .callTimeout(Duration.ofSeconds(5))
+                            .build());
+        }
+
+        @Override
+        public void close() {
+            channel.shutdownNow();
+            server.shutdownNow();
+        }
+    }
+}

clients/java/mxgateway-client/src/test/java/com/dohertylan/mxgateway/client/MxGatewayClientSessionTests.java

@@ -17,12 +17,14 @@ import io.grpc.inprocess.InProcessServerBuilder;
 import io.grpc.stub.ServerCallStreamObserver;
 import io.grpc.stub.StreamObserver;
 import java.time.Duration;
+import java.util.List;
 import java.util.UUID;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicReference;
 import mxaccess_gateway.v1.MxAccessGatewayGrpc;
 import mxaccess_gateway.v1.MxaccessGateway.AddItemReply;
+import mxaccess_gateway.v1.MxaccessGateway.BulkSubscribeReply;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest;
 import mxaccess_gateway.v1.MxaccessGateway.MxCommandKind;
@@ -36,6 +38,7 @@ import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatusCode;
 import mxaccess_gateway.v1.MxaccessGateway.RegisterReply;
 import mxaccess_gateway.v1.MxaccessGateway.SessionState;
 import mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest;
+import mxaccess_gateway.v1.MxaccessGateway.SubscribeResult;
 import org.junit.jupiter.api.Test;
 
 final class MxGatewayClientSessionTests {
@@ -112,6 +115,42 @@ final class MxGatewayClientSessionTests {
         }
     }
 
+    @Test
+    void subscribeBulkBuildsOneBulkCommandAndReturnsResults() throws Exception {
+        AtomicReference<MxCommandRequest> commandRequest = new AtomicReference<>();
+        TestGatewayService service = new TestGatewayService() {
+            @Override
+            public void invoke(MxCommandRequest request, StreamObserver<MxCommandReply> responseObserver) {
+                commandRequest.set(request);
+                responseObserver.onNext(MxCommandReply.newBuilder()
+                        .setSessionId(request.getSessionId())
+                        .setKind(request.getCommand().getKind())
+                        .setProtocolStatus(ok())
+                        .setSubscribeBulk(BulkSubscribeReply.newBuilder()
+                                .addResults(SubscribeResult.newBuilder()
+                                        .setServerHandle(12)
+                                        .setTagAddress("Area001.Pump001.Speed")
+                                        .setItemHandle(34)
+                                        .setWasSuccessful(true)))
+                        .build());
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGateway gateway = InProcessGateway.start(service, new AtomicReference<>());
+                MxGatewayClient client = gateway.client("", Duration.ofSeconds(5))) {
+            MxGatewaySession session = MxGatewaySession.forSessionId(client, "existing-session");
+
+            List<SubscribeResult> results = session.subscribeBulk(12, List.of("Area001.Pump001.Speed"));
+
+            assertEquals(34, results.get(0).getItemHandle());
+            assertEquals(MxCommandKind.MX_COMMAND_KIND_SUBSCRIBE_BULK, commandRequest.get().getCommand().getKind());
+            assertEquals(
+                    List.of("Area001.Pump001.Speed"),
+                    commandRequest.get().getCommand().getSubscribeBulk().getTagAddressesList());
+        }
+    }
+
     @Test
     void streamCancellationCancelsServerCall() throws Exception {
         CountDownLatch cancelled = new CountDownLatch(1);

clients/java/src/main/generated/main/grpc/galaxy_repository/v1/GalaxyRepositoryGrpc.java

@@ -0,0 +1,641 @@
+package galaxy_repository.v1;
+
+import static io.grpc.MethodDescriptor.generateFullMethodName;
+
+/**
+ * <pre>
+ * Read-only browse over the AVEVA System Platform Galaxy Repository (ZB SQL
+ * database). Lets clients enumerate the deployed object hierarchy and each
+ * object's dynamic attributes so they know what tag references to subscribe
+ * to via the MxAccessGateway service.
+ * </pre>
+ */
+@io.grpc.stub.annotations.GrpcGenerated
+public final class GalaxyRepositoryGrpc {
+
+  private GalaxyRepositoryGrpc() {}
+
+  public static final java.lang.String SERVICE_NAME = "galaxy_repository.v1.GalaxyRepository";
+
+  // Static method descriptors that strictly reflect the proto.
+  private static volatile io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest,
+      galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply> getTestConnectionMethod;
+
+  @io.grpc.stub.annotations.RpcMethod(
+      fullMethodName = SERVICE_NAME + '/' + "TestConnection",
+      requestType = galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest.class,
+      responseType = galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply.class,
+      methodType = io.grpc.MethodDescriptor.MethodType.UNARY)
+  public static io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest,
+      galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply> getTestConnectionMethod() {
+    io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest, galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply> getTestConnectionMethod;
+    if ((getTestConnectionMethod = GalaxyRepositoryGrpc.getTestConnectionMethod) == null) {
+      synchronized (GalaxyRepositoryGrpc.class) {
+        if ((getTestConnectionMethod = GalaxyRepositoryGrpc.getTestConnectionMethod) == null) {
+          GalaxyRepositoryGrpc.getTestConnectionMethod = getTestConnectionMethod =
+              io.grpc.MethodDescriptor.<galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest, galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply>newBuilder()
+              .setType(io.grpc.MethodDescriptor.MethodType.UNARY)
+              .setFullMethodName(generateFullMethodName(SERVICE_NAME, "TestConnection"))
+              .setSampledToLocalTracing(true)
+              .setRequestMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest.getDefaultInstance()))
+              .setResponseMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply.getDefaultInstance()))
+              .setSchemaDescriptor(new GalaxyRepositoryMethodDescriptorSupplier("TestConnection"))
+              .build();
+        }
+      }
+    }
+    return getTestConnectionMethod;
+  }
+
+  private static volatile io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest,
+      galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply> getGetLastDeployTimeMethod;
+
+  @io.grpc.stub.annotations.RpcMethod(
+      fullMethodName = SERVICE_NAME + '/' + "GetLastDeployTime",
+      requestType = galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest.class,
+      responseType = galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply.class,
+      methodType = io.grpc.MethodDescriptor.MethodType.UNARY)
+  public static io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest,
+      galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply> getGetLastDeployTimeMethod() {
+    io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest, galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply> getGetLastDeployTimeMethod;
+    if ((getGetLastDeployTimeMethod = GalaxyRepositoryGrpc.getGetLastDeployTimeMethod) == null) {
+      synchronized (GalaxyRepositoryGrpc.class) {
+        if ((getGetLastDeployTimeMethod = GalaxyRepositoryGrpc.getGetLastDeployTimeMethod) == null) {
+          GalaxyRepositoryGrpc.getGetLastDeployTimeMethod = getGetLastDeployTimeMethod =
+              io.grpc.MethodDescriptor.<galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest, galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply>newBuilder()
+              .setType(io.grpc.MethodDescriptor.MethodType.UNARY)
+              .setFullMethodName(generateFullMethodName(SERVICE_NAME, "GetLastDeployTime"))
+              .setSampledToLocalTracing(true)
+              .setRequestMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest.getDefaultInstance()))
+              .setResponseMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply.getDefaultInstance()))
+              .setSchemaDescriptor(new GalaxyRepositoryMethodDescriptorSupplier("GetLastDeployTime"))
+              .build();
+        }
+      }
+    }
+    return getGetLastDeployTimeMethod;
+  }
+
+  private static volatile io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest,
+      galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply> getDiscoverHierarchyMethod;
+
+  @io.grpc.stub.annotations.RpcMethod(
+      fullMethodName = SERVICE_NAME + '/' + "DiscoverHierarchy",
+      requestType = galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest.class,
+      responseType = galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply.class,
+      methodType = io.grpc.MethodDescriptor.MethodType.UNARY)
+  public static io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest,
+      galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply> getDiscoverHierarchyMethod() {
+    io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest, galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply> getDiscoverHierarchyMethod;
+    if ((getDiscoverHierarchyMethod = GalaxyRepositoryGrpc.getDiscoverHierarchyMethod) == null) {
+      synchronized (GalaxyRepositoryGrpc.class) {
+        if ((getDiscoverHierarchyMethod = GalaxyRepositoryGrpc.getDiscoverHierarchyMethod) == null) {
+          GalaxyRepositoryGrpc.getDiscoverHierarchyMethod = getDiscoverHierarchyMethod =
+              io.grpc.MethodDescriptor.<galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest, galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply>newBuilder()
+              .setType(io.grpc.MethodDescriptor.MethodType.UNARY)
+              .setFullMethodName(generateFullMethodName(SERVICE_NAME, "DiscoverHierarchy"))
+              .setSampledToLocalTracing(true)
+              .setRequestMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest.getDefaultInstance()))
+              .setResponseMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply.getDefaultInstance()))
+              .setSchemaDescriptor(new GalaxyRepositoryMethodDescriptorSupplier("DiscoverHierarchy"))
+              .build();
+        }
+      }
+    }
+    return getDiscoverHierarchyMethod;
+  }
+
+  private static volatile io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest,
+      galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent> getWatchDeployEventsMethod;
+
+  @io.grpc.stub.annotations.RpcMethod(
+      fullMethodName = SERVICE_NAME + '/' + "WatchDeployEvents",
+      requestType = galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest.class,
+      responseType = galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent.class,
+      methodType = io.grpc.MethodDescriptor.MethodType.SERVER_STREAMING)
+  public static io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest,
+      galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent> getWatchDeployEventsMethod() {
+    io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest, galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent> getWatchDeployEventsMethod;
+    if ((getWatchDeployEventsMethod = GalaxyRepositoryGrpc.getWatchDeployEventsMethod) == null) {
+      synchronized (GalaxyRepositoryGrpc.class) {
+        if ((getWatchDeployEventsMethod = GalaxyRepositoryGrpc.getWatchDeployEventsMethod) == null) {
+          GalaxyRepositoryGrpc.getWatchDeployEventsMethod = getWatchDeployEventsMethod =
+              io.grpc.MethodDescriptor.<galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest, galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent>newBuilder()
+              .setType(io.grpc.MethodDescriptor.MethodType.SERVER_STREAMING)
+              .setFullMethodName(generateFullMethodName(SERVICE_NAME, "WatchDeployEvents"))
+              .setSampledToLocalTracing(true)
+              .setRequestMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest.getDefaultInstance()))
+              .setResponseMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent.getDefaultInstance()))
+              .setSchemaDescriptor(new GalaxyRepositoryMethodDescriptorSupplier("WatchDeployEvents"))
+              .build();
+        }
+      }
+    }
+    return getWatchDeployEventsMethod;
+  }
+
+  /**
+   * Creates a new async stub that supports all call types for the service
+   */
+  public static GalaxyRepositoryStub newStub(io.grpc.Channel channel) {
+    io.grpc.stub.AbstractStub.StubFactory<GalaxyRepositoryStub> factory =
+      new io.grpc.stub.AbstractStub.StubFactory<GalaxyRepositoryStub>() {
+        @java.lang.Override
+        public GalaxyRepositoryStub newStub(io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+          return new GalaxyRepositoryStub(channel, callOptions);
+        }
+      };
+    return GalaxyRepositoryStub.newStub(factory, channel);
+  }
+
+  /**
+   * Creates a new blocking-style stub that supports all types of calls on the service
+   */
+  public static GalaxyRepositoryBlockingV2Stub newBlockingV2Stub(
+      io.grpc.Channel channel) {
+    io.grpc.stub.AbstractStub.StubFactory<GalaxyRepositoryBlockingV2Stub> factory =
+      new io.grpc.stub.AbstractStub.StubFactory<GalaxyRepositoryBlockingV2Stub>() {
+        @java.lang.Override
+        public GalaxyRepositoryBlockingV2Stub newStub(io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+          return new GalaxyRepositoryBlockingV2Stub(channel, callOptions);
+        }
+      };
+    return GalaxyRepositoryBlockingV2Stub.newStub(factory, channel);
+  }
+
+  /**
+   * Creates a new blocking-style stub that supports unary and streaming output calls on the service
+   */
+  public static GalaxyRepositoryBlockingStub newBlockingStub(
+      io.grpc.Channel channel) {
+    io.grpc.stub.AbstractStub.StubFactory<GalaxyRepositoryBlockingStub> factory =
+      new io.grpc.stub.AbstractStub.StubFactory<GalaxyRepositoryBlockingStub>() {
+        @java.lang.Override
+        public GalaxyRepositoryBlockingStub newStub(io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+          return new GalaxyRepositoryBlockingStub(channel, callOptions);
+        }
+      };
+    return GalaxyRepositoryBlockingStub.newStub(factory, channel);
+  }
+
+  /**
+   * Creates a new ListenableFuture-style stub that supports unary calls on the service
+   */
+  public static GalaxyRepositoryFutureStub newFutureStub(
+      io.grpc.Channel channel) {
+    io.grpc.stub.AbstractStub.StubFactory<GalaxyRepositoryFutureStub> factory =
+      new io.grpc.stub.AbstractStub.StubFactory<GalaxyRepositoryFutureStub>() {
+        @java.lang.Override
+        public GalaxyRepositoryFutureStub newStub(io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+          return new GalaxyRepositoryFutureStub(channel, callOptions);
+        }
+      };
+    return GalaxyRepositoryFutureStub.newStub(factory, channel);
+  }
+
+  /**
+   * <pre>
+   * Read-only browse over the AVEVA System Platform Galaxy Repository (ZB SQL
+   * database). Lets clients enumerate the deployed object hierarchy and each
+   * object's dynamic attributes so they know what tag references to subscribe
+   * to via the MxAccessGateway service.
+   * </pre>
+   */
+  public interface AsyncService {
+
+    /**
+     */
+    default void testConnection(galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest request,
+        io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply> responseObserver) {
+      io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getTestConnectionMethod(), responseObserver);
+    }
+
+    /**
+     */
+    default void getLastDeployTime(galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest request,
+        io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply> responseObserver) {
+      io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getGetLastDeployTimeMethod(), responseObserver);
+    }
+
+    /**
+     */
+    default void discoverHierarchy(galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest request,
+        io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply> responseObserver) {
+      io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getDiscoverHierarchyMethod(), responseObserver);
+    }
+
+    /**
+     * <pre>
+     * Server-stream of deploy events. The server emits the current state immediately
+     * on subscribe (so clients can bootstrap their cache without waiting for the next
+     * deploy), then emits one event each time the gateway's hierarchy cache observes
+     * a new galaxy.time_of_last_deploy. The sequence field is monotonically
+     * increasing per server start; gaps indicate the per-subscriber buffer dropped
+     * older events because the client was too slow.
+     * </pre>
+     */
+    default void watchDeployEvents(galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest request,
+        io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent> responseObserver) {
+      io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getWatchDeployEventsMethod(), responseObserver);
+    }
+  }
+
+  /**
+   * Base class for the server implementation of the service GalaxyRepository.
+   * <pre>
+   * Read-only browse over the AVEVA System Platform Galaxy Repository (ZB SQL
+   * database). Lets clients enumerate the deployed object hierarchy and each
+   * object's dynamic attributes so they know what tag references to subscribe
+   * to via the MxAccessGateway service.
+   * </pre>
+   */
+  public static abstract class GalaxyRepositoryImplBase
+      implements io.grpc.BindableService, AsyncService {
+
+    @java.lang.Override public final io.grpc.ServerServiceDefinition bindService() {
+      return GalaxyRepositoryGrpc.bindService(this);
+    }
+  }
+
+  /**
+   * A stub to allow clients to do asynchronous rpc calls to service GalaxyRepository.
+   * <pre>
+   * Read-only browse over the AVEVA System Platform Galaxy Repository (ZB SQL
+   * database). Lets clients enumerate the deployed object hierarchy and each
+   * object's dynamic attributes so they know what tag references to subscribe
+   * to via the MxAccessGateway service.
+   * </pre>
+   */
+  public static final class GalaxyRepositoryStub
+      extends io.grpc.stub.AbstractAsyncStub<GalaxyRepositoryStub> {
+    private GalaxyRepositoryStub(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      super(channel, callOptions);
+    }
+
+    @java.lang.Override
+    protected GalaxyRepositoryStub build(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      return new GalaxyRepositoryStub(channel, callOptions);
+    }
+
+    /**
+     */
+    public void testConnection(galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest request,
+        io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply> responseObserver) {
+      io.grpc.stub.ClientCalls.asyncUnaryCall(
+          getChannel().newCall(getTestConnectionMethod(), getCallOptions()), request, responseObserver);
+    }
+
+    /**
+     */
+    public void getLastDeployTime(galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest request,
+        io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply> responseObserver) {
+      io.grpc.stub.ClientCalls.asyncUnaryCall(
+          getChannel().newCall(getGetLastDeployTimeMethod(), getCallOptions()), request, responseObserver);
+    }
+
+    /**
+     */
+    public void discoverHierarchy(galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest request,
+        io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply> responseObserver) {
+      io.grpc.stub.ClientCalls.asyncUnaryCall(
+          getChannel().newCall(getDiscoverHierarchyMethod(), getCallOptions()), request, responseObserver);
+    }
+
+    /**
+     * <pre>
+     * Server-stream of deploy events. The server emits the current state immediately
+     * on subscribe (so clients can bootstrap their cache without waiting for the next
+     * deploy), then emits one event each time the gateway's hierarchy cache observes
+     * a new galaxy.time_of_last_deploy. The sequence field is monotonically
+     * increasing per server start; gaps indicate the per-subscriber buffer dropped
+     * older events because the client was too slow.
+     * </pre>
+     */
+    public void watchDeployEvents(galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest request,
+        io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent> responseObserver) {
+      io.grpc.stub.ClientCalls.asyncServerStreamingCall(
+          getChannel().newCall(getWatchDeployEventsMethod(), getCallOptions()), request, responseObserver);
+    }
+  }
+
+  /**
+   * A stub to allow clients to do synchronous rpc calls to service GalaxyRepository.
+   * <pre>
+   * Read-only browse over the AVEVA System Platform Galaxy Repository (ZB SQL
+   * database). Lets clients enumerate the deployed object hierarchy and each
+   * object's dynamic attributes so they know what tag references to subscribe
+   * to via the MxAccessGateway service.
+   * </pre>
+   */
+  public static final class GalaxyRepositoryBlockingV2Stub
+      extends io.grpc.stub.AbstractBlockingStub<GalaxyRepositoryBlockingV2Stub> {
+    private GalaxyRepositoryBlockingV2Stub(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      super(channel, callOptions);
+    }
+
+    @java.lang.Override
+    protected GalaxyRepositoryBlockingV2Stub build(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      return new GalaxyRepositoryBlockingV2Stub(channel, callOptions);
+    }
+
+    /**
+     */
+    public galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply testConnection(galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest request) throws io.grpc.StatusException {
+      return io.grpc.stub.ClientCalls.blockingV2UnaryCall(
+          getChannel(), getTestConnectionMethod(), getCallOptions(), request);
+    }
+
+    /**
+     */
+    public galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply getLastDeployTime(galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest request) throws io.grpc.StatusException {
+      return io.grpc.stub.ClientCalls.blockingV2UnaryCall(
+          getChannel(), getGetLastDeployTimeMethod(), getCallOptions(), request);
+    }
+
+    /**
+     */
+    public galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply discoverHierarchy(galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest request) throws io.grpc.StatusException {
+      return io.grpc.stub.ClientCalls.blockingV2UnaryCall(
+          getChannel(), getDiscoverHierarchyMethod(), getCallOptions(), request);
+    }
+
+    /**
+     * <pre>
+     * Server-stream of deploy events. The server emits the current state immediately
+     * on subscribe (so clients can bootstrap their cache without waiting for the next
+     * deploy), then emits one event each time the gateway's hierarchy cache observes
+     * a new galaxy.time_of_last_deploy. The sequence field is monotonically
+     * increasing per server start; gaps indicate the per-subscriber buffer dropped
+     * older events because the client was too slow.
+     * </pre>
+     */
+    @io.grpc.ExperimentalApi("https://github.com/grpc/grpc-java/issues/10918")
+    public io.grpc.stub.BlockingClientCall<?, galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent>
+        watchDeployEvents(galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest request) {
+      return io.grpc.stub.ClientCalls.blockingV2ServerStreamingCall(
+          getChannel(), getWatchDeployEventsMethod(), getCallOptions(), request);
+    }
+  }
+
+  /**
+   * A stub to allow clients to do limited synchronous rpc calls to service GalaxyRepository.
+   * <pre>
+   * Read-only browse over the AVEVA System Platform Galaxy Repository (ZB SQL
+   * database). Lets clients enumerate the deployed object hierarchy and each
+   * object's dynamic attributes so they know what tag references to subscribe
+   * to via the MxAccessGateway service.
+   * </pre>
+   */
+  public static final class GalaxyRepositoryBlockingStub
+      extends io.grpc.stub.AbstractBlockingStub<GalaxyRepositoryBlockingStub> {
+    private GalaxyRepositoryBlockingStub(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      super(channel, callOptions);
+    }
+
+    @java.lang.Override
+    protected GalaxyRepositoryBlockingStub build(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      return new GalaxyRepositoryBlockingStub(channel, callOptions);
+    }
+
+    /**
+     */
+    public galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply testConnection(galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest request) {
+      return io.grpc.stub.ClientCalls.blockingUnaryCall(
+          getChannel(), getTestConnectionMethod(), getCallOptions(), request);
+    }
+
+    /**
+     */
+    public galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply getLastDeployTime(galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest request) {
+      return io.grpc.stub.ClientCalls.blockingUnaryCall(
+          getChannel(), getGetLastDeployTimeMethod(), getCallOptions(), request);
+    }
+
+    /**
+     */
+    public galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply discoverHierarchy(galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest request) {
+      return io.grpc.stub.ClientCalls.blockingUnaryCall(
+          getChannel(), getDiscoverHierarchyMethod(), getCallOptions(), request);
+    }
+
+    /**
+     * <pre>
+     * Server-stream of deploy events. The server emits the current state immediately
+     * on subscribe (so clients can bootstrap their cache without waiting for the next
+     * deploy), then emits one event each time the gateway's hierarchy cache observes
+     * a new galaxy.time_of_last_deploy. The sequence field is monotonically
+     * increasing per server start; gaps indicate the per-subscriber buffer dropped
+     * older events because the client was too slow.
+     * </pre>
+     */
+    public java.util.Iterator<galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent> watchDeployEvents(
+        galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest request) {
+      return io.grpc.stub.ClientCalls.blockingServerStreamingCall(
+          getChannel(), getWatchDeployEventsMethod(), getCallOptions(), request);
+    }
+  }
+
+  /**
+   * A stub to allow clients to do ListenableFuture-style rpc calls to service GalaxyRepository.
+   * <pre>
+   * Read-only browse over the AVEVA System Platform Galaxy Repository (ZB SQL
+   * database). Lets clients enumerate the deployed object hierarchy and each
+   * object's dynamic attributes so they know what tag references to subscribe
+   * to via the MxAccessGateway service.
+   * </pre>
+   */
+  public static final class GalaxyRepositoryFutureStub
+      extends io.grpc.stub.AbstractFutureStub<GalaxyRepositoryFutureStub> {
+    private GalaxyRepositoryFutureStub(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      super(channel, callOptions);
+    }
+
+    @java.lang.Override
+    protected GalaxyRepositoryFutureStub build(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      return new GalaxyRepositoryFutureStub(channel, callOptions);
+    }
+
+    /**
+     */
+    public com.google.common.util.concurrent.ListenableFuture<galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply> testConnection(
+        galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest request) {
+      return io.grpc.stub.ClientCalls.futureUnaryCall(
+          getChannel().newCall(getTestConnectionMethod(), getCallOptions()), request);
+    }
+
+    /**
+     */
+    public com.google.common.util.concurrent.ListenableFuture<galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply> getLastDeployTime(
+        galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest request) {
+      return io.grpc.stub.ClientCalls.futureUnaryCall(
+          getChannel().newCall(getGetLastDeployTimeMethod(), getCallOptions()), request);
+    }
+
+    /**
+     */
+    public com.google.common.util.concurrent.ListenableFuture<galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply> discoverHierarchy(
+        galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest request) {
+      return io.grpc.stub.ClientCalls.futureUnaryCall(
+          getChannel().newCall(getDiscoverHierarchyMethod(), getCallOptions()), request);
+    }
+  }
+
+  private static final int METHODID_TEST_CONNECTION = 0;
+  private static final int METHODID_GET_LAST_DEPLOY_TIME = 1;
+  private static final int METHODID_DISCOVER_HIERARCHY = 2;
+  private static final int METHODID_WATCH_DEPLOY_EVENTS = 3;
+
+  private static final class MethodHandlers<Req, Resp> implements
+      io.grpc.stub.ServerCalls.UnaryMethod<Req, Resp>,
+      io.grpc.stub.ServerCalls.ServerStreamingMethod<Req, Resp>,
+      io.grpc.stub.ServerCalls.ClientStreamingMethod<Req, Resp>,
+      io.grpc.stub.ServerCalls.BidiStreamingMethod<Req, Resp> {
+    private final AsyncService serviceImpl;
+    private final int methodId;
+
+    MethodHandlers(AsyncService serviceImpl, int methodId) {
+      this.serviceImpl = serviceImpl;
+      this.methodId = methodId;
+    }
+
+    @java.lang.Override
+    @java.lang.SuppressWarnings("unchecked")
+    public void invoke(Req request, io.grpc.stub.StreamObserver<Resp> responseObserver) {
+      switch (methodId) {
+        case METHODID_TEST_CONNECTION:
+          serviceImpl.testConnection((galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest) request,
+              (io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply>) responseObserver);
+          break;
+        case METHODID_GET_LAST_DEPLOY_TIME:
+          serviceImpl.getLastDeployTime((galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest) request,
+              (io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply>) responseObserver);
+          break;
+        case METHODID_DISCOVER_HIERARCHY:
+          serviceImpl.discoverHierarchy((galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest) request,
+              (io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply>) responseObserver);
+          break;
+        case METHODID_WATCH_DEPLOY_EVENTS:
+          serviceImpl.watchDeployEvents((galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest) request,
+              (io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent>) responseObserver);
+          break;
+        default:
+          throw new AssertionError();
+      }
+    }
+
+    @java.lang.Override
+    @java.lang.SuppressWarnings("unchecked")
+    public io.grpc.stub.StreamObserver<Req> invoke(
+        io.grpc.stub.StreamObserver<Resp> responseObserver) {
+      switch (methodId) {
+        default:
+          throw new AssertionError();
+      }
+    }
+  }
+
+  public static final io.grpc.ServerServiceDefinition bindService(AsyncService service) {
+    return io.grpc.ServerServiceDefinition.builder(getServiceDescriptor())
+        .addMethod(
+          getTestConnectionMethod(),
+          io.grpc.stub.ServerCalls.asyncUnaryCall(
+            new MethodHandlers<
+              galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest,
+              galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply>(
+                service, METHODID_TEST_CONNECTION)))
+        .addMethod(
+          getGetLastDeployTimeMethod(),
+          io.grpc.stub.ServerCalls.asyncUnaryCall(
+            new MethodHandlers<
+              galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest,
+              galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply>(
+                service, METHODID_GET_LAST_DEPLOY_TIME)))
+        .addMethod(
+          getDiscoverHierarchyMethod(),
+          io.grpc.stub.ServerCalls.asyncUnaryCall(
+            new MethodHandlers<
+              galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest,
+              galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply>(
+                service, METHODID_DISCOVER_HIERARCHY)))
+        .addMethod(
+          getWatchDeployEventsMethod(),
+          io.grpc.stub.ServerCalls.asyncServerStreamingCall(
+            new MethodHandlers<
+              galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest,
+              galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent>(
+                service, METHODID_WATCH_DEPLOY_EVENTS)))
+        .build();
+  }
+
+  private static abstract class GalaxyRepositoryBaseDescriptorSupplier
+      implements io.grpc.protobuf.ProtoFileDescriptorSupplier, io.grpc.protobuf.ProtoServiceDescriptorSupplier {
+    GalaxyRepositoryBaseDescriptorSupplier() {}
+
+    @java.lang.Override
+    public com.google.protobuf.Descriptors.FileDescriptor getFileDescriptor() {
+      return galaxy_repository.v1.GalaxyRepositoryOuterClass.getDescriptor();
+    }
+
+    @java.lang.Override
+    public com.google.protobuf.Descriptors.ServiceDescriptor getServiceDescriptor() {
+      return getFileDescriptor().findServiceByName("GalaxyRepository");
+    }
+  }
+
+  private static final class GalaxyRepositoryFileDescriptorSupplier
+      extends GalaxyRepositoryBaseDescriptorSupplier {
+    GalaxyRepositoryFileDescriptorSupplier() {}
+  }
+
+  private static final class GalaxyRepositoryMethodDescriptorSupplier
+      extends GalaxyRepositoryBaseDescriptorSupplier
+      implements io.grpc.protobuf.ProtoMethodDescriptorSupplier {
+    private final java.lang.String methodName;
+
+    GalaxyRepositoryMethodDescriptorSupplier(java.lang.String methodName) {
+      this.methodName = methodName;
+    }
+
+    @java.lang.Override
+    public com.google.protobuf.Descriptors.MethodDescriptor getMethodDescriptor() {
+      return getServiceDescriptor().findMethodByName(methodName);
+    }
+  }
+
+  private static volatile io.grpc.ServiceDescriptor serviceDescriptor;
+
+  public static io.grpc.ServiceDescriptor getServiceDescriptor() {
+    io.grpc.ServiceDescriptor result = serviceDescriptor;
+    if (result == null) {
+      synchronized (GalaxyRepositoryGrpc.class) {
+        result = serviceDescriptor;
+        if (result == null) {
+          serviceDescriptor = result = io.grpc.ServiceDescriptor.newBuilder(SERVICE_NAME)
+              .setSchemaDescriptor(new GalaxyRepositoryFileDescriptorSupplier())
+              .addMethod(getTestConnectionMethod())
+              .addMethod(getGetLastDeployTimeMethod())
+              .addMethod(getDiscoverHierarchyMethod())
+              .addMethod(getWatchDeployEventsMethod())
+              .build();
+        }
+      }
+    }
+    return result;
+  }
+}

clients/proto/fixtures/behavior/manifest.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "fixtureSet": "mxaccess-gateway-client-behavior",
   "contractName": "mxaccess-gateway",
-  "gatewayProtocolVersion": 1,
+  "gatewayProtocolVersion": 2,
   "workerProtocolVersion": 1,
   "protoInputManifest": "clients/proto/proto-inputs.json",
   "fixtures": [

clients/proto/fixtures/golden/open-session-reply.ok.json

@@ -3,7 +3,7 @@
   "backendName": "mxaccess-worker",
   "workerProcessId": 1234,
   "workerProtocolVersion": 1,
-  "gatewayProtocolVersion": 1,
+  "gatewayProtocolVersion": 2,
   "capabilities": [
     "unary-open-session",
     "unary-close-session",

clients/proto/fixtures/parity/parity-fixture-matrix.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "fixtureSet": "mxaccess-gateway-parity-fixture-matrix",
   "contractName": "mxaccess-gateway",
-  "gatewayProtocolVersion": 1,
+  "gatewayProtocolVersion": 2,
   "workerProtocolVersion": 1,
   "sourceCaptureRoot": "C:/Users/dohertj2/Desktop/mxaccess/captures",
   "sourceDocs": [

clients/proto/proto-inputs.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "contractName": "mxaccess-gateway",
-  "gatewayProtocolVersion": 1,
+  "gatewayProtocolVersion": 2,
   "workerProtocolVersion": 1,
   "protoRoot": "src/MxGateway.Contracts/Protos",
   "sourceFiles": [
@@ -12,6 +12,10 @@
     {
       "path": "mxaccess_worker.proto",
       "role": "gateway_worker_ipc"
+    },
+    {
+      "path": "galaxy_repository.proto",
+      "role": "public_galaxy_repository"
     }
   ],
   "descriptorSet": "clients/proto/descriptors/mxaccessgw-client-v1.protoset",

clients/python/README.md

@@ -47,6 +47,28 @@ The tests import the generated gateway and worker stubs, run fake async gateway
 stubs, verify API key metadata, exercise stream cancellation, load shared value
 and command fixtures, and check deterministic CLI output.
 
+## Packaging
+
+Install the package in editable mode for local development:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+Build a wheel from `clients/python`:
+
+```powershell
+python -m pip wheel . --no-deps --wheel-dir "$env:TEMP\mxgateway-python-wheel"
+```
+
+Install the generated wheel into a target environment:
+
+```powershell
+python -m pip install <wheel-path>
+```
+
+The wheel exposes the `mxgw-py` console script.
+
 ## Library Usage
 
 The library is async-first:
@@ -56,7 +78,7 @@ from mxgateway import GatewayClient
 
 async with await GatewayClient.connect(
     endpoint="localhost:5000",
-    api_key="mxgw_example",
+    api_key="<gateway-api-key>",
     plaintext=True,
 ) as client:
     session = await client.open_session(client_session_name="python-client")
@@ -76,6 +98,76 @@ MXAccess commands and preserve raw replies on typed command exceptions.
 Canceling a Python task cancels the client-side gRPC call or stream wait. It
 does not abort an in-flight MXAccess COM call inside the worker process.
 
+## Galaxy Repository Browse
+
+The `GalaxyRepositoryClient` wraps the read-only `GalaxyRepository` gRPC
+service. It lets callers test connectivity to the AVEVA System Platform
+Galaxy Repository (ZB SQL database), read the last deploy timestamp, and
+enumerate the deployed object hierarchy plus each object's dynamic
+attributes:
+
+```python
+from mxgateway import GalaxyRepositoryClient
+
+async with await GalaxyRepositoryClient.connect(
+    endpoint="localhost:5000",
+    api_key="<gateway-api-key>",
+    plaintext=True,
+) as galaxy:
+    if not await galaxy.test_connection():
+        raise RuntimeError("gateway cannot reach the Galaxy Repository DB")
+
+    last_deploy = await galaxy.get_last_deploy_time()
+    print(f"last deploy: {last_deploy}")
+
+    for obj in await galaxy.discover_hierarchy():
+        print(obj.tag_name, obj.contained_name)
+        for attr in obj.attributes:
+            print("  ", attr.attribute_name, "->", attr.full_tag_reference)
+```
+
+The methods return native Python types (`bool`, `datetime | None`, and a
+`list[GalaxyObject]` of generated proto messages) so callers can index
+into the hierarchy without learning the underlying stub class. The
+service requires the `metadata:read` scope on the API key.
+
+### Watching deploy events
+
+`GalaxyRepositoryClient.watch_deploy_events` opens a server-streaming
+subscription that emits the current cached deploy state immediately and
+then one `DeployEvent` per new Galaxy deploy. `sequence` is monotonic per
+gateway start; gaps mean events were dropped from the per-subscriber
+buffer. Pass `last_seen_deploy_time` to suppress the bootstrap event when
+the caller already has the current state cached:
+
+```python
+from datetime import datetime, timezone
+from mxgateway import DeployEvent, GalaxyRepositoryClient
+
+async with await GalaxyRepositoryClient.connect(
+    endpoint="localhost:5000",
+    api_key="<gateway-api-key>",
+    plaintext=True,
+) as galaxy:
+    last_seen: datetime | None = None
+    async for event in galaxy.watch_deploy_events(last_seen_deploy_time=last_seen):
+        assert isinstance(event, DeployEvent)
+        print(
+            f"#{event.sequence} deploy={event.time_of_last_deploy.ToDatetime(tzinfo=timezone.utc)} "
+            f"objects={event.object_count} attributes={event.attribute_count}"
+        )
+        if event.time_of_last_deploy_present:
+            last_seen = event.time_of_last_deploy.ToDatetime(tzinfo=timezone.utc)
+```
+
+The method returns an async iterator yielding the generated `DeployEvent`
+proto. Breaking out of the loop, calling `aclose()` on the iterator, or
+cancelling the surrounding task closes the underlying gRPC stream
+cleanly. The streaming RPC requires the same `metadata:read` scope as
+the other Galaxy methods. The CLI does not currently expose a
+streaming `watch-deploy-events` subcommand — use the library API
+directly when subscribing to deploy events from Python.
+
 ## Authentication And TLS
 
 `ClientOptions.api_key` adds this metadata to unary calls and streams:
@@ -105,3 +197,27 @@ mxgw-py write --session-id <id> --server-handle 1 --item-handle 2 --type int32 -
 Use `--api-key` or `--api-key-env MXGATEWAY_API_KEY` to attach API key
 metadata. `smoke` opens a session, registers, adds an item, advises, streams a
 bounded event count, and closes the session in a `finally` block.
+
+Use TLS options for a secured gateway:
+
+```powershell
+mxgw-py smoke --endpoint mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item Object.Attribute --json
+```
+
+## Integration Checks
+
+Run live checks only when a gateway and MXAccess-backed worker are available:
+
+```powershell
+$env:MXGATEWAY_INTEGRATION = '1'
+$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
+$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
+$env:MXGATEWAY_TEST_ITEM = 'Object.Attribute'
+mxgw-py smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+```
+
+## Related Documentation
+
+- [Client Packaging](../../docs/ClientPackaging.md)
+- [Client Proto Generation](../../docs/client-proto-generation.md)
+- [Python Client Detailed Design](../../docs/clients-python-design.md)

clients/python/generate-proto.ps1

@@ -19,4 +19,5 @@ Get-ChildItem -Path (Join-Path $outputRoot '*_pb2_grpc.py') -File | Remove-Item
     "--python_out=$outputRoot" `
     "--grpc_python_out=$outputRoot" `
     mxaccess_gateway.proto `
-    mxaccess_worker.proto
+    mxaccess_worker.proto `
+    galaxy_repository.proto

clients/python/src/mxgateway/__init__.py

@@ -2,6 +2,13 @@
 
 from .auth import ApiKey, auth_metadata
 from .client import GatewayClient
+from .galaxy import GalaxyRepositoryClient
+from .generated.galaxy_repository_pb2 import (
+    DeployEvent,
+    GalaxyAttribute,
+    GalaxyObject,
+    WatchDeployEventsRequest,
+)
 from .errors import (
     MxAccessError,
     MxGatewayAuthenticationError,
@@ -20,6 +27,10 @@ from .version import __version__
 __all__ = [
     "ApiKey",
     "ClientOptions",
+    "DeployEvent",
+    "GalaxyAttribute",
+    "GalaxyObject",
+    "GalaxyRepositoryClient",
     "GatewayClient",
     "MxAccessError",
     "MxGatewayAuthenticationError",
@@ -31,6 +42,7 @@ __all__ = [
     "MxGatewayWorkerError",
     "MxValueView",
     "Session",
+    "WatchDeployEventsRequest",
     "__version__",
     "auth_metadata",
     "from_mx_value",

clients/python/src/mxgateway/client.py

@@ -74,9 +74,9 @@ class GatewayClient:
         if self._closed:
             return
 
-        self._closed = True
         if self._channel is not None:
             await self._channel.close()
+        self._closed = True
 
     async def open_session(
         self,
@@ -124,10 +124,10 @@ class GatewayClient:
     ) -> AsyncIterator[pb.MxEvent]:
         """Return an async event iterator and cancel the stream when iteration stops."""
 
-        call = self.raw_stub.StreamEvents(
-            request,
-            metadata=merge_metadata(self.options.api_key, metadata),
-        )
+        kwargs: dict[str, Any] = {"metadata": merge_metadata(self.options.api_key, metadata)}
+        if self.options.stream_timeout is not None:
+            kwargs["timeout"] = self.options.stream_timeout
+        call = self.raw_stub.StreamEvents(request, **kwargs)
         return _canceling_iterator(call)
 
     async def _unary(
@@ -138,10 +138,16 @@ class GatewayClient:
         *,
         metadata: Sequence[tuple[str, str]] | None = None,
     ) -> Any:
-        call = method(
-            request,
-            metadata=merge_metadata(self.options.api_key, metadata),
-        )
+        kwargs: dict[str, Any] = {"metadata": merge_metadata(self.options.api_key, metadata)}
+        if self.options.call_timeout is not None:
+            kwargs["timeout"] = self.options.call_timeout
+        try:
+            call = method(request, **kwargs)
+        except TypeError as error:
+            if "timeout" not in kwargs or "unexpected keyword argument 'timeout'" not in str(error):
+                raise
+            kwargs.pop("timeout")
+            call = method(request, **kwargs)
         try:
             return await call
         except asyncio.CancelledError:

clients/python/src/mxgateway/galaxy.py

@@ -0,0 +1,216 @@
+"""Async Galaxy Repository client wrapper.
+
+Wraps the read-only ``GalaxyRepository`` gRPC service exposed by the
+MxAccess Gateway. The service lets callers test connectivity to the AVEVA
+System Platform Galaxy Repository (ZB SQL database), read the last
+deployment timestamp, and enumerate the deployed object hierarchy plus the
+attributes on each object.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Sequence
+from datetime import datetime
+from typing import Any
+
+import grpc
+from google.protobuf.timestamp_pb2 import Timestamp
+
+from .auth import merge_metadata
+from .errors import MxGatewayError, map_rpc_error
+from .generated import galaxy_repository_pb2 as galaxy_pb
+from .generated import galaxy_repository_pb2_grpc as galaxy_pb_grpc
+from .options import ClientOptions, create_channel
+
+_DISCOVER_HIERARCHY_PAGE_SIZE = 5000
+
+
+class GalaxyRepositoryClient:
+    """Async client for the Galaxy Repository gRPC service."""
+
+    def __init__(
+        self,
+        *,
+        options: ClientOptions,
+        stub: Any,
+        channel: grpc.aio.Channel | None = None,
+    ) -> None:
+        self.options = options
+        self.raw_stub = stub
+        self._channel = channel
+        self._closed = False
+
+    @classmethod
+    async def connect(
+        cls,
+        options: ClientOptions | None = None,
+        *,
+        endpoint: str | None = None,
+        api_key: str | None = None,
+        plaintext: bool = False,
+        ca_file: str | None = None,
+        server_name_override: str | None = None,
+        stub: Any | None = None,
+    ) -> "GalaxyRepositoryClient":
+        """Create a client with either a real async channel or a supplied fake stub."""
+
+        resolved = options or ClientOptions(
+            endpoint=endpoint or "",
+            api_key=api_key,
+            plaintext=plaintext,
+            ca_file=ca_file,
+            server_name_override=server_name_override,
+        )
+
+        if stub is not None:
+            return cls(options=resolved, stub=stub)
+
+        channel = create_channel(resolved)
+        return cls(
+            options=resolved,
+            stub=galaxy_pb_grpc.GalaxyRepositoryStub(channel),
+            channel=channel,
+        )
+
+    async def __aenter__(self) -> "GalaxyRepositoryClient":
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the owned gRPC channel."""
+
+        if self._closed:
+            return
+
+        if self._channel is not None:
+            await self._channel.close()
+        self._closed = True
+
+    async def test_connection(self) -> bool:
+        """Return ``True`` when the gateway can reach the Galaxy Repository DB."""
+
+        reply = await self._unary(
+            "test connection",
+            self.raw_stub.TestConnection,
+            galaxy_pb.TestConnectionRequest(),
+        )
+        return bool(reply.ok)
+
+    async def get_last_deploy_time(self) -> datetime | None:
+        """Return the last Galaxy deploy timestamp or ``None`` when unset."""
+
+        reply = await self._unary(
+            "get last deploy time",
+            self.raw_stub.GetLastDeployTime,
+            galaxy_pb.GetLastDeployTimeRequest(),
+        )
+        if not reply.present:
+            return None
+        return reply.time_of_last_deploy.ToDatetime()
+
+    async def discover_hierarchy(self) -> list[galaxy_pb.GalaxyObject]:
+        """Return the deployed Galaxy object hierarchy as raw proto messages."""
+
+        objects: list[galaxy_pb.GalaxyObject] = []
+        seen_page_tokens: set[str] = set()
+        page_token = ""
+        while True:
+            reply = await self._unary(
+                "discover hierarchy",
+                self.raw_stub.DiscoverHierarchy,
+                galaxy_pb.DiscoverHierarchyRequest(
+                    page_size=_DISCOVER_HIERARCHY_PAGE_SIZE,
+                    page_token=page_token,
+                ),
+            )
+            objects.extend(reply.objects)
+            page_token = reply.next_page_token
+            if not page_token:
+                return objects
+            if page_token in seen_page_tokens:
+                raise MxGatewayError(
+                    f"galaxy discover hierarchy returned repeated page token {page_token!r}"
+                )
+            seen_page_tokens.add(page_token)
+
+    def watch_deploy_events(
+        self,
+        last_seen_deploy_time: datetime | None = None,
+        *,
+        metadata: Sequence[tuple[str, str]] | None = None,
+    ) -> AsyncIterator[galaxy_pb.DeployEvent]:
+        """Stream Galaxy deploy events.
+
+        On subscribe the gateway emits the current cached state and then one
+        event per new deploy time. ``sequence`` is monotonic per server start;
+        gaps mean events were dropped from the per-subscriber buffer. When
+        ``last_seen_deploy_time`` is supplied and matches the current cached
+        deploy time the bootstrap event is suppressed.
+        """
+
+        request = galaxy_pb.WatchDeployEventsRequest()
+        if last_seen_deploy_time is not None:
+            timestamp = Timestamp()
+            timestamp.FromDatetime(last_seen_deploy_time)
+            request.last_seen_deploy_time.CopyFrom(timestamp)
+
+        kwargs: dict[str, Any] = {"metadata": merge_metadata(self.options.api_key, metadata)}
+        if self.options.stream_timeout is not None:
+            kwargs["timeout"] = self.options.stream_timeout
+        try:
+            call = self.raw_stub.WatchDeployEvents(request, **kwargs)
+        except TypeError as error:
+            if "timeout" not in kwargs or "unexpected keyword argument 'timeout'" not in str(error):
+                raise
+            kwargs.pop("timeout")
+            call = self.raw_stub.WatchDeployEvents(request, **kwargs)
+
+        return _canceling_iterator(call)
+
+    async def _unary(
+        self,
+        operation: str,
+        method: Any,
+        request: Any,
+        *,
+        metadata: Sequence[tuple[str, str]] | None = None,
+    ) -> Any:
+        kwargs: dict[str, Any] = {"metadata": merge_metadata(self.options.api_key, metadata)}
+        if self.options.call_timeout is not None:
+            kwargs["timeout"] = self.options.call_timeout
+        try:
+            call = method(request, **kwargs)
+        except TypeError as error:
+            if "timeout" not in kwargs or "unexpected keyword argument 'timeout'" not in str(error):
+                raise
+            kwargs.pop("timeout")
+            call = method(request, **kwargs)
+        try:
+            return await call
+        except asyncio.CancelledError:
+            cancel = getattr(call, "cancel", None)
+            if cancel is not None:
+                cancel()
+            raise
+        except grpc.RpcError as error:
+            raise map_rpc_error(operation, error) from error
+
+
+async def _canceling_iterator(call: Any) -> AsyncIterator[galaxy_pb.DeployEvent]:
+    try:
+        async for event in call:
+            yield event
+    except asyncio.CancelledError:
+        cancel = getattr(call, "cancel", None)
+        if cancel is not None:
+            cancel()
+        raise
+    except grpc.RpcError as error:
+        raise map_rpc_error("watch deploy events", error) from error
+    finally:
+        cancel = getattr(call, "cancel", None)
+        if cancel is not None:
+            cancel()

clients/python/src/mxgateway/generated/__init__.py

@@ -21,7 +21,15 @@ sys.modules.setdefault("mxaccess_worker_pb2", mxaccess_worker_pb2)
 mxaccess_worker_pb2_grpc = import_module(f"{__name__}.mxaccess_worker_pb2_grpc")
 sys.modules.setdefault("mxaccess_worker_pb2_grpc", mxaccess_worker_pb2_grpc)
 
+galaxy_repository_pb2 = import_module(f"{__name__}.galaxy_repository_pb2")
+sys.modules.setdefault("galaxy_repository_pb2", galaxy_repository_pb2)
+
+galaxy_repository_pb2_grpc = import_module(f"{__name__}.galaxy_repository_pb2_grpc")
+sys.modules.setdefault("galaxy_repository_pb2_grpc", galaxy_repository_pb2_grpc)
+
 __all__ = [
+    "galaxy_repository_pb2",
+    "galaxy_repository_pb2_grpc",
     "mxaccess_gateway_pb2",
     "mxaccess_gateway_pb2_grpc",
     "mxaccess_worker_pb2",

clients/python/src/mxgateway/generated/galaxy_repository_pb2.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: galaxy_repository.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'galaxy_repository.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.protobuf import timestamp_pb2 as google_dot_protobuf_dot_timestamp__pb2
+from google.protobuf import wrappers_pb2 as google_dot_protobuf_dot_wrappers__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x17galaxy_repository.proto\x12\x14galaxy_repository.v1\x1a\x1fgoogle/protobuf/timestamp.proto\x1a\x1egoogle/protobuf/wrappers.proto\"\x17\n\x15TestConnectionRequest\"!\n\x13TestConnectionReply\x12\n\n\x02ok\x18\x01 \x01(\x08\"\x1a\n\x18GetLastDeployTimeRequest\"b\n\x16GetLastDeployTimeReply\x12\x0f\n\x07present\x18\x01 \x01(\x08\x12\x37\n\x13time_of_last_deploy\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"\x87\x03\n\x18\x44iscoverHierarchyRequest\x12\x11\n\tpage_size\x18\x01 \x01(\x05\x12\x12\n\npage_token\x18\x02 \x01(\t\x12\x19\n\x0froot_gobject_id\x18\x03 \x01(\x05H\x00\x12\x17\n\rroot_tag_name\x18\x04 \x01(\tH\x00\x12\x1d\n\x13root_contained_path\x18\x05 \x01(\tH\x00\x12.\n\tmax_depth\x18\x06 \x01(\x0b\x32\x1b.google.protobuf.Int32Value\x12\x14\n\x0c\x63\x61tegory_ids\x18\x07 \x03(\x05\x12\x1f\n\x17template_chain_contains\x18\x08 \x03(\t\x12\x15\n\rtag_name_glob\x18\t \x01(\t\x12\x1f\n\x12include_attributes\x18\n \x01(\x08H\x01\x88\x01\x01\x12\x1a\n\x12\x61larm_bearing_only\x18\x0b \x01(\x08\x12\x17\n\x0fhistorized_only\x18\x0c \x01(\x08\x42\x06\n\x04rootB\x15\n\x13_include_attributes\"\x82\x01\n\x16\x44iscoverHierarchyReply\x12\x33\n\x07objects\x18\x01 \x03(\x0b\x32\".galaxy_repository.v1.GalaxyObject\x12\x17\n\x0fnext_page_token\x18\x02 \x01(\t\x12\x1a\n\x12total_object_count\x18\x03 \x01(\x05\"U\n\x18WatchDeployEventsRequest\x12\x39\n\x15last_seen_deploy_time\x18\x01 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"\xdd\x01\n\x0b\x44\x65ployEvent\x12\x10\n\x08sequence\x18\x01 \x01(\x04\x12/\n\x0bobserved_at\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12\x37\n\x13time_of_last_deploy\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12#\n\x1btime_of_last_deploy_present\x18\x04 \x01(\x08\x12\x14\n\x0cobject_count\x18\x05 \x01(\x05\x12\x17\n\x0f\x61ttribute_count\x18\x06 \x01(\x05\"\x93\x02\n\x0cGalaxyObject\x12\x12\n\ngobject_id\x18\x01 \x01(\x05\x12\x10\n\x08tag_name\x18\x02 \x01(\t\x12\x16\n\x0e\x63ontained_name\x18\x03 \x01(\t\x12\x13\n\x0b\x62rowse_name\x18\x04 \x01(\t\x12\x19\n\x11parent_gobject_id\x18\x05 \x01(\x05\x12\x0f\n\x07is_area\x18\x06 \x01(\x08\x12\x13\n\x0b\x63\x61tegory_id\x18\x07 \x01(\x05\x12\x1c\n\x14hosted_by_gobject_id\x18\x08 \x01(\x05\x12\x16\n\x0etemplate_chain\x18\t \x03(\t\x12\x39\n\nattributes\x18\n \x03(\x0b\x32%.galaxy_repository.v1.GalaxyAttribute\"\xa8\x02\n\x0fGalaxyAttribute\x12\x16\n\x0e\x61ttribute_name\x18\x01 \x01(\t\x12\x1a\n\x12\x66ull_tag_reference\x18\x02 \x01(\t\x12\x14\n\x0cmx_data_type\x18\x03 \x01(\x05\x12\x16\n\x0e\x64\x61ta_type_name\x18\x04 \x01(\t\x12\x10\n\x08is_array\x18\x05 \x01(\x08\x12\x17\n\x0f\x61rray_dimension\x18\x06 \x01(\x05\x12\x1f\n\x17\x61rray_dimension_present\x18\x07 \x01(\x08\x12\x1d\n\x15mx_attribute_category\x18\x08 \x01(\x05\x12\x1f\n\x17security_classification\x18\t \x01(\x05\x12\x15\n\ris_historized\x18\n \x01(\x08\x12\x10\n\x08is_alarm\x18\x0b \x01(\x08\x32\xcc\x03\n\x10GalaxyRepository\x12h\n\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\x11\x44iscoverHierarchy\x12..galaxy_repository.v1.DiscoverHierarchyRequest\x1a,.galaxy_repository.v1.DiscoverHierarchyReply\x12h\n\x11WatchDeployEvents\x12..galaxy_repository.v1.WatchDeployEventsRequest\x1a!.galaxy_repository.v1.DeployEvent0\x01\x42#\xaa\x02 MxGateway.Contracts.Proto.Galaxyb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'galaxy_repository_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'\252\002 MxGateway.Contracts.Proto.Galaxy'
+  _globals['_TESTCONNECTIONREQUEST']._serialized_start=114
+  _globals['_TESTCONNECTIONREQUEST']._serialized_end=137
+  _globals['_TESTCONNECTIONREPLY']._serialized_start=139
+  _globals['_TESTCONNECTIONREPLY']._serialized_end=172
+  _globals['_GETLASTDEPLOYTIMEREQUEST']._serialized_start=174
+  _globals['_GETLASTDEPLOYTIMEREQUEST']._serialized_end=200
+  _globals['_GETLASTDEPLOYTIMEREPLY']._serialized_start=202
+  _globals['_GETLASTDEPLOYTIMEREPLY']._serialized_end=300
+  _globals['_DISCOVERHIERARCHYREQUEST']._serialized_start=303
+  _globals['_DISCOVERHIERARCHYREQUEST']._serialized_end=694
+  _globals['_DISCOVERHIERARCHYREPLY']._serialized_start=697
+  _globals['_DISCOVERHIERARCHYREPLY']._serialized_end=827
+  _globals['_WATCHDEPLOYEVENTSREQUEST']._serialized_start=829
+  _globals['_WATCHDEPLOYEVENTSREQUEST']._serialized_end=914
+  _globals['_DEPLOYEVENT']._serialized_start=917
+  _globals['_DEPLOYEVENT']._serialized_end=1138
+  _globals['_GALAXYOBJECT']._serialized_start=1141
+  _globals['_GALAXYOBJECT']._serialized_end=1416
+  _globals['_GALAXYATTRIBUTE']._serialized_start=1419
+  _globals['_GALAXYATTRIBUTE']._serialized_end=1715
+  _globals['_GALAXYREPOSITORY']._serialized_start=1718
+  _globals['_GALAXYREPOSITORY']._serialized_end=2178
+# @@protoc_insertion_point(module_scope)

clients/python/src/mxgateway/generated/galaxy_repository_pb2_grpc.py

@@ -0,0 +1,244 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+import galaxy_repository_pb2 as galaxy__repository__pb2
+
+GRPC_GENERATED_VERSION = '1.80.0'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + ' but the generated code in galaxy_repository_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class GalaxyRepositoryStub(object):
+    """Read-only browse over the AVEVA System Platform Galaxy Repository (ZB SQL
+    database). Lets clients enumerate the deployed object hierarchy and each
+    object's dynamic attributes so they know what tag references to subscribe
+    to via the MxAccessGateway service.
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.TestConnection = channel.unary_unary(
+                '/galaxy_repository.v1.GalaxyRepository/TestConnection',
+                request_serializer=galaxy__repository__pb2.TestConnectionRequest.SerializeToString,
+                response_deserializer=galaxy__repository__pb2.TestConnectionReply.FromString,
+                _registered_method=True)
+        self.GetLastDeployTime = channel.unary_unary(
+                '/galaxy_repository.v1.GalaxyRepository/GetLastDeployTime',
+                request_serializer=galaxy__repository__pb2.GetLastDeployTimeRequest.SerializeToString,
+                response_deserializer=galaxy__repository__pb2.GetLastDeployTimeReply.FromString,
+                _registered_method=True)
+        self.DiscoverHierarchy = channel.unary_unary(
+                '/galaxy_repository.v1.GalaxyRepository/DiscoverHierarchy',
+                request_serializer=galaxy__repository__pb2.DiscoverHierarchyRequest.SerializeToString,
+                response_deserializer=galaxy__repository__pb2.DiscoverHierarchyReply.FromString,
+                _registered_method=True)
+        self.WatchDeployEvents = channel.unary_stream(
+                '/galaxy_repository.v1.GalaxyRepository/WatchDeployEvents',
+                request_serializer=galaxy__repository__pb2.WatchDeployEventsRequest.SerializeToString,
+                response_deserializer=galaxy__repository__pb2.DeployEvent.FromString,
+                _registered_method=True)
+
+
+class GalaxyRepositoryServicer(object):
+    """Read-only browse over the AVEVA System Platform Galaxy Repository (ZB SQL
+    database). Lets clients enumerate the deployed object hierarchy and each
+    object's dynamic attributes so they know what tag references to subscribe
+    to via the MxAccessGateway service.
+    """
+
+    def TestConnection(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def GetLastDeployTime(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def DiscoverHierarchy(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def WatchDeployEvents(self, request, context):
+        """Server-stream of deploy events. The server emits the current state immediately
+        on subscribe (so clients can bootstrap their cache without waiting for the next
+        deploy), then emits one event each time the gateway's hierarchy cache observes
+        a new galaxy.time_of_last_deploy. The sequence field is monotonically
+        increasing per server start; gaps indicate the per-subscriber buffer dropped
+        older events because the client was too slow.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_GalaxyRepositoryServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'TestConnection': grpc.unary_unary_rpc_method_handler(
+                    servicer.TestConnection,
+                    request_deserializer=galaxy__repository__pb2.TestConnectionRequest.FromString,
+                    response_serializer=galaxy__repository__pb2.TestConnectionReply.SerializeToString,
+            ),
+            'GetLastDeployTime': grpc.unary_unary_rpc_method_handler(
+                    servicer.GetLastDeployTime,
+                    request_deserializer=galaxy__repository__pb2.GetLastDeployTimeRequest.FromString,
+                    response_serializer=galaxy__repository__pb2.GetLastDeployTimeReply.SerializeToString,
+            ),
+            'DiscoverHierarchy': grpc.unary_unary_rpc_method_handler(
+                    servicer.DiscoverHierarchy,
+                    request_deserializer=galaxy__repository__pb2.DiscoverHierarchyRequest.FromString,
+                    response_serializer=galaxy__repository__pb2.DiscoverHierarchyReply.SerializeToString,
+            ),
+            'WatchDeployEvents': grpc.unary_stream_rpc_method_handler(
+                    servicer.WatchDeployEvents,
+                    request_deserializer=galaxy__repository__pb2.WatchDeployEventsRequest.FromString,
+                    response_serializer=galaxy__repository__pb2.DeployEvent.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'galaxy_repository.v1.GalaxyRepository', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('galaxy_repository.v1.GalaxyRepository', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class GalaxyRepository(object):
+    """Read-only browse over the AVEVA System Platform Galaxy Repository (ZB SQL
+    database). Lets clients enumerate the deployed object hierarchy and each
+    object's dynamic attributes so they know what tag references to subscribe
+    to via the MxAccessGateway service.
+    """
+
+    @staticmethod
+    def TestConnection(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/galaxy_repository.v1.GalaxyRepository/TestConnection',
+            galaxy__repository__pb2.TestConnectionRequest.SerializeToString,
+            galaxy__repository__pb2.TestConnectionReply.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def GetLastDeployTime(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/galaxy_repository.v1.GalaxyRepository/GetLastDeployTime',
+            galaxy__repository__pb2.GetLastDeployTimeRequest.SerializeToString,
+            galaxy__repository__pb2.GetLastDeployTimeReply.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def DiscoverHierarchy(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/galaxy_repository.v1.GalaxyRepository/DiscoverHierarchy',
+            galaxy__repository__pb2.DiscoverHierarchyRequest.SerializeToString,
+            galaxy__repository__pb2.DiscoverHierarchyReply.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def WatchDeployEvents(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_stream(
+            request,
+            target,
+            '/galaxy_repository.v1.GalaxyRepository/WatchDeployEvents',
+            galaxy__repository__pb2.WatchDeployEventsRequest.SerializeToString,
+            galaxy__repository__pb2.DeployEvent.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

clients/python/src/mxgateway/options.py

@@ -19,6 +19,9 @@ class ClientOptions:
     plaintext: bool = False
     ca_file: str | None = None
     server_name_override: str | None = None
+    call_timeout: float | None = 30.0
+    stream_timeout: float | None = None
+    max_grpc_message_bytes: int = 16 * 1024 * 1024
 
     def __post_init__(self) -> None:
         if not self.endpoint:
@@ -26,6 +29,12 @@ class ClientOptions:
 
         if self.plaintext and self.ca_file:
             raise ValueError("ca_file cannot be used with plaintext connections")
+        if self.call_timeout is not None and self.call_timeout <= 0:
+            raise ValueError("call_timeout must be greater than zero")
+        if self.stream_timeout is not None and self.stream_timeout <= 0:
+            raise ValueError("stream_timeout must be greater than zero")
+        if self.max_grpc_message_bytes <= 0:
+            raise ValueError("max_grpc_message_bytes must be greater than zero")
 
     def __repr__(self) -> str:
         api_key = REDACTED if self.api_key else None
@@ -33,14 +42,20 @@ class ClientOptions:
             f"{type(self).__name__}(endpoint={self.endpoint!r}, "
             f"api_key={api_key!r}, plaintext={self.plaintext!r}, "
             f"ca_file={self.ca_file!r}, "
-            f"server_name_override={self.server_name_override!r})"
+            f"server_name_override={self.server_name_override!r}, "
+            f"call_timeout={self.call_timeout!r}, "
+            f"stream_timeout={self.stream_timeout!r}, "
+            f"max_grpc_message_bytes={self.max_grpc_message_bytes!r})"
         )
 
 
 def create_channel(options: ClientOptions) -> grpc.aio.Channel:
     """Create a plaintext or TLS `grpc.aio` channel from client options."""
 
-    channel_options: list[tuple[str, str]] = []
+    channel_options: list[tuple[str, str | int]] = [
+        ("grpc.max_receive_message_length", options.max_grpc_message_bytes),
+        ("grpc.max_send_message_length", options.max_grpc_message_bytes),
+    ]
     if options.server_name_override:
         channel_options.append(("grpc.ssl_target_name_override", options.server_name_override))
 

clients/python/src/mxgateway/session.py

@@ -2,12 +2,14 @@
 
 from __future__ import annotations
 
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Sequence
 
 from .errors import ensure_mxaccess_success
 from .generated import mxaccess_gateway_pb2 as pb
 from .values import MxValueInput, to_mx_value
 
+MAX_BULK_ITEMS = 1000
+
 
 class Session:
     """A single gateway-backed MXAccess session."""
@@ -40,13 +42,14 @@ class Session:
                 protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
             )
 
-        self._closed = True
-        return await self.client.close_session_raw(
+        reply = await self.client.close_session_raw(
             pb.CloseSessionRequest(
                 session_id=self.session_id,
                 client_correlation_id=client_correlation_id,
             ),
         )
+        self._closed = True
+        return reply
 
     async def invoke(self, command: pb.MxCommand, *, correlation_id: str = "") -> pb.MxCommandReply:
         """Invoke a raw command and enforce gateway and MXAccess success."""
@@ -89,6 +92,24 @@ class Session:
             correlation_id=correlation_id,
         )
 
+    async def remove_item(
+        self,
+        server_handle: int,
+        item_handle: int,
+        *,
+        correlation_id: str = "",
+    ) -> None:
+        await self.invoke(
+            pb.MxCommand(
+                kind=pb.MX_COMMAND_KIND_REMOVE_ITEM,
+                remove_item=pb.RemoveItemCommand(
+                    server_handle=server_handle,
+                    item_handle=item_handle,
+                ),
+            ),
+            correlation_id=correlation_id,
+        )
+
     async def add_item(
         self,
         server_handle: int,
@@ -147,6 +168,156 @@ class Session:
             correlation_id=correlation_id,
         )
 
+    async def unadvise(
+        self,
+        server_handle: int,
+        item_handle: int,
+        *,
+        correlation_id: str = "",
+    ) -> None:
+        await self.invoke(
+            pb.MxCommand(
+                kind=pb.MX_COMMAND_KIND_UN_ADVISE,
+                un_advise=pb.UnAdviseCommand(
+                    server_handle=server_handle,
+                    item_handle=item_handle,
+                ),
+            ),
+            correlation_id=correlation_id,
+        )
+
+    async def add_item_bulk(
+        self,
+        server_handle: int,
+        tag_addresses: Sequence[str],
+        *,
+        correlation_id: str = "",
+    ) -> list[pb.SubscribeResult]:
+        if tag_addresses is None:
+            raise TypeError("tag_addresses is required")
+        _ensure_bulk_size("tag_addresses", len(tag_addresses))
+        reply = await self.invoke(
+            pb.MxCommand(
+                kind=pb.MX_COMMAND_KIND_ADD_ITEM_BULK,
+                add_item_bulk=pb.AddItemBulkCommand(
+                    server_handle=server_handle,
+                    tag_addresses=tag_addresses,
+                ),
+            ),
+            correlation_id=correlation_id,
+        )
+        return list(reply.add_item_bulk.results)
+
+    async def advise_item_bulk(
+        self,
+        server_handle: int,
+        item_handles: Sequence[int],
+        *,
+        correlation_id: str = "",
+    ) -> list[pb.SubscribeResult]:
+        if item_handles is None:
+            raise TypeError("item_handles is required")
+        _ensure_bulk_size("item_handles", len(item_handles))
+        reply = await self.invoke(
+            pb.MxCommand(
+                kind=pb.MX_COMMAND_KIND_ADVISE_ITEM_BULK,
+                advise_item_bulk=pb.AdviseItemBulkCommand(
+                    server_handle=server_handle,
+                    item_handles=item_handles,
+                ),
+            ),
+            correlation_id=correlation_id,
+        )
+        return list(reply.advise_item_bulk.results)
+
+    async def remove_item_bulk(
+        self,
+        server_handle: int,
+        item_handles: Sequence[int],
+        *,
+        correlation_id: str = "",
+    ) -> list[pb.SubscribeResult]:
+        if item_handles is None:
+            raise TypeError("item_handles is required")
+        _ensure_bulk_size("item_handles", len(item_handles))
+        reply = await self.invoke(
+            pb.MxCommand(
+                kind=pb.MX_COMMAND_KIND_REMOVE_ITEM_BULK,
+                remove_item_bulk=pb.RemoveItemBulkCommand(
+                    server_handle=server_handle,
+                    item_handles=item_handles,
+                ),
+            ),
+            correlation_id=correlation_id,
+        )
+        return list(reply.remove_item_bulk.results)
+
+    async def unadvise_item_bulk(
+        self,
+        server_handle: int,
+        item_handles: Sequence[int],
+        *,
+        correlation_id: str = "",
+    ) -> list[pb.SubscribeResult]:
+        if item_handles is None:
+            raise TypeError("item_handles is required")
+        _ensure_bulk_size("item_handles", len(item_handles))
+        reply = await self.invoke(
+            pb.MxCommand(
+                kind=pb.MX_COMMAND_KIND_UN_ADVISE_ITEM_BULK,
+                un_advise_item_bulk=pb.UnAdviseItemBulkCommand(
+                    server_handle=server_handle,
+                    item_handles=item_handles,
+                ),
+            ),
+            correlation_id=correlation_id,
+        )
+        return list(reply.un_advise_item_bulk.results)
+
+    async def subscribe_bulk(
+        self,
+        server_handle: int,
+        tag_addresses: Sequence[str],
+        *,
+        correlation_id: str = "",
+    ) -> list[pb.SubscribeResult]:
+        if tag_addresses is None:
+            raise TypeError("tag_addresses is required")
+        _ensure_bulk_size("tag_addresses", len(tag_addresses))
+        reply = await self.invoke(
+            pb.MxCommand(
+                kind=pb.MX_COMMAND_KIND_SUBSCRIBE_BULK,
+                subscribe_bulk=pb.SubscribeBulkCommand(
+                    server_handle=server_handle,
+                    tag_addresses=tag_addresses,
+                ),
+            ),
+            correlation_id=correlation_id,
+        )
+        return list(reply.subscribe_bulk.results)
+
+    async def unsubscribe_bulk(
+        self,
+        server_handle: int,
+        item_handles: Sequence[int],
+        *,
+        correlation_id: str = "",
+    ) -> list[pb.SubscribeResult]:
+        if item_handles is None:
+            raise TypeError("item_handles is required")
+        _ensure_bulk_size("item_handles", len(item_handles))
+        reply = await self.invoke(
+            pb.MxCommand(
+                kind=pb.MX_COMMAND_KIND_UNSUBSCRIBE_BULK,
+                unsubscribe_bulk=pb.UnsubscribeBulkCommand(
+                    server_handle=server_handle,
+                    item_handles=item_handles,
+                ),
+            ),
+            correlation_id=correlation_id,
+        )
+        return list(reply.unsubscribe_bulk.results)
+
     async def write(
         self,
         server_handle: int,
@@ -206,4 +377,9 @@ class Session:
         )
 
 
+def _ensure_bulk_size(name: str, count: int) -> None:
+    if count > MAX_BULK_ITEMS:
+        raise ValueError(f"{name} bulk commands are limited to {MAX_BULK_ITEMS} item(s)")
+
+
 from .client import GatewayClient  # noqa: E402

clients/python/src/mxgateway_cli/commands.py

@@ -20,6 +20,8 @@ from mxgateway.generated import mxaccess_gateway_pb2 as pb
 from mxgateway.options import ClientOptions
 from mxgateway.values import MxValueInput
 
+MAX_AGGREGATE_EVENTS = 10_000
+
 
 @click.group()
 def main() -> None:
@@ -55,6 +57,8 @@ def gateway_options(command: Callable[..., Any]) -> Callable[..., Any]:
         default=None,
         help="TLS server name override for test environments.",
     )(command)
+    command = click.option("--call-timeout", default=30.0, type=float, show_default=True)(command)
+    command = click.option("--stream-timeout", default=None, type=float)(command)
     return command
 
 
@@ -146,6 +150,40 @@ def advise(**kwargs: Any) -> None:
     _run(_advise(**kwargs), output_json=kwargs["output_json"], secrets=_secrets(kwargs))
 
 
+@main.command("subscribe-bulk")
+@gateway_options
+@click.option("--session-id", required=True, help="Gateway session id.")
+@click.option("--server-handle", required=True, type=int, help="MXAccess server handle.")
+@click.option("--items", required=True, help="Comma-separated MXAccess item definitions.")
+@click.option("--correlation-id", default="", help="Client correlation id.")
+@click.option("--json", "output_json", is_flag=True, help="Emit JSON output.")
+def subscribe_bulk(**kwargs: Any) -> None:
+    """Invoke MXAccess SubscribeBulk."""
+
+    _run(
+        _subscribe_bulk(**kwargs),
+        output_json=kwargs["output_json"],
+        secrets=_secrets(kwargs),
+    )
+
+
+@main.command("unsubscribe-bulk")
+@gateway_options
+@click.option("--session-id", required=True, help="Gateway session id.")
+@click.option("--server-handle", required=True, type=int, help="MXAccess server handle.")
+@click.option("--item-handles", required=True, help="Comma-separated MXAccess item handles.")
+@click.option("--correlation-id", default="", help="Client correlation id.")
+@click.option("--json", "output_json", is_flag=True, help="Emit JSON output.")
+def unsubscribe_bulk(**kwargs: Any) -> None:
+    """Invoke MXAccess UnsubscribeBulk."""
+
+    _run(
+        _unsubscribe_bulk(**kwargs),
+        output_json=kwargs["output_json"],
+        secrets=_secrets(kwargs),
+    )
+
+
 @main.command("stream-events")
 @gateway_options
 @click.option("--session-id", required=True, help="Gateway session id.")
@@ -278,6 +316,28 @@ async def _advise(**kwargs: Any) -> dict[str, Any]:
         return {"ok": True}
 
 
+async def _subscribe_bulk(**kwargs: Any) -> dict[str, Any]:
+    async with await _connect(kwargs) as client:
+        session = _session(client, kwargs["session_id"])
+        results = await session.subscribe_bulk(
+            kwargs["server_handle"],
+            _parse_string_list(kwargs["items"]),
+            correlation_id=kwargs["correlation_id"],
+        )
+        return {"results": [_message_dict(result) for result in results]}
+
+
+async def _unsubscribe_bulk(**kwargs: Any) -> dict[str, Any]:
+    async with await _connect(kwargs) as client:
+        session = _session(client, kwargs["session_id"])
+        results = await session.unsubscribe_bulk(
+            kwargs["server_handle"],
+            _parse_int_list(kwargs["item_handles"]),
+            correlation_id=kwargs["correlation_id"],
+        )
+        return {"results": [_message_dict(result) for result in results]}
+
+
 async def _stream_events(**kwargs: Any) -> dict[str, Any]:
     async with await _connect(kwargs) as client:
         session = _session(client, kwargs["session_id"])
@@ -352,6 +412,8 @@ async def _connect(kwargs: dict[str, Any]) -> GatewayClient:
             plaintext=_use_plaintext(kwargs),
             ca_file=kwargs.get("ca_file"),
             server_name_override=kwargs.get("server_name_override"),
+            call_timeout=kwargs.get("call_timeout"),
+            stream_timeout=kwargs.get("stream_timeout"),
         ),
     )
 
@@ -416,6 +478,12 @@ async def _collect_events(
     max_events: int,
     timeout: float,
 ) -> list[pb.MxEvent]:
+    if max_events > MAX_AGGREGATE_EVENTS:
+        raise click.BadParameter(
+            f"must be less than or equal to {MAX_AGGREGATE_EVENTS}",
+            param_hint="--max-events",
+        )
+
     collected: list[pb.MxEvent] = []
     iterator = events.__aiter__()
     try:
@@ -423,6 +491,8 @@ async def _collect_events(
             collected.append(await asyncio.wait_for(iterator.__anext__(), timeout=timeout))
     except StopAsyncIteration:
         pass
+    except asyncio.TimeoutError:
+        pass
     finally:
         close = getattr(iterator, "aclose", None)
         if close is not None:
@@ -456,6 +526,20 @@ def _parse_datetime(raw_value: str) -> datetime:
     return parsed
 
 
+def _parse_string_list(raw_value: str) -> list[str]:
+    values = [item.strip() for item in raw_value.split(",") if item.strip()]
+    if not values:
+        raise click.BadParameter("at least one item is required", param_hint="--items")
+    return values
+
+
+def _parse_int_list(raw_value: str) -> list[int]:
+    values = [item.strip() for item in raw_value.split(",") if item.strip()]
+    if not values:
+        raise click.BadParameter("at least one item handle is required", param_hint="--item-handles")
+    return [int(item) for item in values]
+
+
 def _message_dict(message: Any) -> dict[str, Any]:
     return MessageToDict(
         message,

clients/python/tests/test_auth_options.py

@@ -61,7 +61,15 @@ def test_create_channel_uses_plaintext_channel(monkeypatch: pytest.MonkeyPatch)
     channel = create_channel(ClientOptions(endpoint="localhost:5000", plaintext=True))
 
     assert channel == "plain-channel"
-    assert calls == [("localhost:5000", [])]
+    assert calls == [
+        (
+            "localhost:5000",
+            [
+                ("grpc.max_receive_message_length", 16 * 1024 * 1024),
+                ("grpc.max_send_message_length", 16 * 1024 * 1024),
+            ],
+        ),
+    ]
 
 
 def test_create_channel_uses_tls_channel(monkeypatch: pytest.MonkeyPatch) -> None:
@@ -95,9 +103,13 @@ def test_create_channel_uses_tls_channel(monkeypatch: pytest.MonkeyPatch) -> Non
 
     assert channel == "tls-channel"
     assert calls == [
-        (
-            "gateway.example:5001",
-            "creds",
-            [("grpc.ssl_target_name_override", "gateway.test")],
-        ),
-    ]
+            (
+                "gateway.example:5001",
+                "creds",
+                [
+                    ("grpc.max_receive_message_length", 16 * 1024 * 1024),
+                    ("grpc.max_send_message_length", 16 * 1024 * 1024),
+                    ("grpc.ssl_target_name_override", "gateway.test"),
+                ],
+            ),
+        ]

clients/python/tests/test_client_session.py

@@ -58,6 +58,41 @@ async def test_mxaccess_error_preserves_raw_reply() -> None:
     assert captured.value.raw_reply is failure_reply
 
 
+@pytest.mark.asyncio
+async def test_subscribe_bulk_sends_one_bulk_command_and_returns_results() -> None:
+    stub = FakeGatewayStub()
+    bulk_reply = pb.MxCommandReply(
+        session_id="session-1",
+        kind=pb.MX_COMMAND_KIND_SUBSCRIBE_BULK,
+        protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+        subscribe_bulk=pb.BulkSubscribeReply(
+            results=[
+                pb.SubscribeResult(
+                    server_handle=12,
+                    tag_address="Area001.Pump001.Speed",
+                    item_handle=34,
+                    was_successful=True,
+                ),
+            ],
+        ),
+    )
+    stub.invoke.replies = [bulk_reply]
+    client = await GatewayClient.connect(
+        ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
+        stub=stub,
+    )
+    session = await client.open_session()
+
+    results = await session.subscribe_bulk(12, ["Area001.Pump001.Speed"])
+
+    assert results[0].item_handle == 34
+    assert len(stub.invoke.requests) == 1
+    assert stub.invoke.requests[0].command.kind == pb.MX_COMMAND_KIND_SUBSCRIBE_BULK
+    assert list(stub.invoke.requests[0].command.subscribe_bulk.tag_addresses) == [
+        "Area001.Pump001.Speed",
+    ]
+
+
 @pytest.mark.asyncio
 async def test_stream_events_cancels_underlying_call_when_closed() -> None:
     stream = FakeStream(

clients/python/tests/test_galaxy.py

@@ -0,0 +1,347 @@
+"""Tests for the Galaxy Repository async client wrapper."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime, timezone
+from typing import Any
+
+import pytest
+from google.protobuf.timestamp_pb2 import Timestamp
+
+from mxgateway import ClientOptions, DeployEvent, GalaxyRepositoryClient, WatchDeployEventsRequest
+from mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
+from mxgateway.generated import galaxy_repository_pb2_grpc as galaxy_pb_grpc
+
+
+def test_galaxy_messages_import() -> None:
+    request = galaxy_pb.DiscoverHierarchyRequest()
+    obj = galaxy_pb.GalaxyObject(
+        gobject_id=42,
+        tag_name="DelmiaReceiver_001",
+        contained_name="DelmiaReceiver",
+        browse_name="DelmiaReceiver",
+        parent_gobject_id=10,
+        is_area=False,
+        category_id=4,
+        hosted_by_gobject_id=10,
+        template_chain=["$ApplicationObject", "$DelmiaReceiver"],
+        attributes=[
+            galaxy_pb.GalaxyAttribute(
+                attribute_name="DownloadPath",
+                full_tag_reference="DelmiaReceiver_001.DownloadPath",
+                mx_data_type=8,
+                data_type_name="String",
+            ),
+        ],
+    )
+
+    assert request.DESCRIPTOR is not None
+    assert obj.attributes[0].attribute_name == "DownloadPath"
+    assert hasattr(galaxy_pb_grpc, "GalaxyRepositoryStub")
+
+
+@pytest.mark.asyncio
+async def test_test_connection_returns_bool_and_sends_auth() -> None:
+    stub = FakeGalaxyStub()
+    stub.test_connection.replies = [galaxy_pb.TestConnectionReply(ok=True)]
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
+        stub=stub,
+    )
+
+    result = await client.test_connection()
+
+    assert result is True
+    assert stub.test_connection.metadata == (("authorization", "Bearer mxgw_test_secret"),)
+    assert isinstance(stub.test_connection.requests[0], galaxy_pb.TestConnectionRequest)
+
+
+@pytest.mark.asyncio
+async def test_get_last_deploy_time_returns_datetime_when_present() -> None:
+    timestamp = Timestamp()
+    timestamp.FromDatetime(datetime(2025, 4, 1, 12, 30, 45, tzinfo=timezone.utc))
+    stub = FakeGalaxyStub()
+    stub.get_last_deploy_time.replies = [
+        galaxy_pb.GetLastDeployTimeReply(present=True, time_of_last_deploy=timestamp),
+    ]
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", plaintext=True),
+        stub=stub,
+    )
+
+    when = await client.get_last_deploy_time()
+
+    assert when is not None
+    assert when.year == 2025
+    assert when.month == 4
+    assert when.day == 1
+    assert when.hour == 12
+    assert when.minute == 30
+    assert when.second == 45
+
+
+@pytest.mark.asyncio
+async def test_get_last_deploy_time_returns_none_when_not_present() -> None:
+    stub = FakeGalaxyStub()
+    stub.get_last_deploy_time.replies = [galaxy_pb.GetLastDeployTimeReply(present=False)]
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", plaintext=True),
+        stub=stub,
+    )
+
+    assert await client.get_last_deploy_time() is None
+
+
+@pytest.mark.asyncio
+async def test_discover_hierarchy_returns_proto_objects() -> None:
+    stub = FakeGalaxyStub()
+    stub.discover_hierarchy.replies = [
+        galaxy_pb.DiscoverHierarchyReply(
+            next_page_token="page-2",
+            total_object_count=2,
+            objects=[
+                galaxy_pb.GalaxyObject(
+                    gobject_id=1,
+                    tag_name="TestMachine_001",
+                    contained_name="TestMachine",
+                    browse_name="TestMachine_001",
+                    is_area=True,
+                ),
+            ],
+        ),
+        galaxy_pb.DiscoverHierarchyReply(
+            total_object_count=2,
+            objects=[
+                galaxy_pb.GalaxyObject(
+                    gobject_id=2,
+                    tag_name="DelmiaReceiver_001",
+                    contained_name="DelmiaReceiver",
+                    browse_name="DelmiaReceiver",
+                    parent_gobject_id=1,
+                    attributes=[
+                        galaxy_pb.GalaxyAttribute(
+                            attribute_name="DownloadPath",
+                            full_tag_reference="DelmiaReceiver_001.DownloadPath",
+                            mx_data_type=8,
+                            data_type_name="String",
+                        ),
+                    ],
+                ),
+            ],
+        ),
+    ]
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", plaintext=True),
+        stub=stub,
+    )
+
+    objects = await client.discover_hierarchy()
+
+    assert isinstance(objects, list)
+    assert len(objects) == 2
+    assert len(stub.discover_hierarchy.requests) == 2
+    assert stub.discover_hierarchy.requests[0].page_size == 5000
+    assert stub.discover_hierarchy.requests[0].page_token == ""
+    assert stub.discover_hierarchy.requests[1].page_token == "page-2"
+    assert objects[0].tag_name == "TestMachine_001"
+    assert objects[1].attributes[0].full_tag_reference == "DelmiaReceiver_001.DownloadPath"
+
+
+@pytest.mark.asyncio
+async def test_discover_hierarchy_rejects_repeated_page_token() -> None:
+    stub = FakeGalaxyStub()
+    stub.discover_hierarchy.replies = [
+        galaxy_pb.DiscoverHierarchyReply(next_page_token="7:1"),
+        galaxy_pb.DiscoverHierarchyReply(next_page_token="7:1"),
+    ]
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", plaintext=True),
+        stub=stub,
+    )
+
+    with pytest.raises(Exception, match="repeated page token"):
+        await client.discover_hierarchy()
+
+
+@pytest.mark.asyncio
+async def test_watch_deploy_events_yields_events_in_order() -> None:
+    ts1 = Timestamp()
+    ts1.FromDatetime(datetime(2025, 4, 1, 10, 0, 0, tzinfo=timezone.utc))
+    ts2 = Timestamp()
+    ts2.FromDatetime(datetime(2025, 4, 1, 11, 0, 0, tzinfo=timezone.utc))
+    events = [
+        galaxy_pb.DeployEvent(
+            sequence=1,
+            observed_at=ts1,
+            time_of_last_deploy=ts1,
+            time_of_last_deploy_present=True,
+            object_count=10,
+            attribute_count=42,
+        ),
+        galaxy_pb.DeployEvent(
+            sequence=2,
+            observed_at=ts2,
+            time_of_last_deploy=ts2,
+            time_of_last_deploy_present=True,
+            object_count=11,
+            attribute_count=45,
+        ),
+    ]
+    stub = FakeGalaxyStub()
+    stub.watch_deploy_events.replies = list(events)
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
+        stub=stub,
+    )
+
+    received: list[DeployEvent] = []
+    async for event in client.watch_deploy_events():
+        received.append(event)
+
+    assert len(received) == 2
+    assert received[0].sequence == 1
+    assert received[1].sequence == 2
+    assert received[0].object_count == 10
+    assert received[1].attribute_count == 45
+    assert stub.watch_deploy_events.metadata == (("authorization", "Bearer mxgw_test_secret"),)
+    assert isinstance(stub.watch_deploy_events.requests[0], galaxy_pb.WatchDeployEventsRequest)
+    # No last_seen_deploy_time was passed, so the request should leave it unset.
+    assert not stub.watch_deploy_events.requests[0].HasField("last_seen_deploy_time")
+
+
+@pytest.mark.asyncio
+async def test_watch_deploy_events_propagates_last_seen_deploy_time() -> None:
+    last_seen = datetime(2025, 4, 1, 12, 0, 0, tzinfo=timezone.utc)
+    stub = FakeGalaxyStub()
+    stub.watch_deploy_events.replies = []
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", plaintext=True),
+        stub=stub,
+    )
+
+    async for _ in client.watch_deploy_events(last_seen_deploy_time=last_seen):
+        pass
+
+    request = stub.watch_deploy_events.requests[0]
+    assert isinstance(request, WatchDeployEventsRequest)
+    assert request.HasField("last_seen_deploy_time")
+    assert request.last_seen_deploy_time.ToDatetime(tzinfo=timezone.utc) == last_seen
+
+
+@pytest.mark.asyncio
+async def test_watch_deploy_events_cancellation_closes_stream() -> None:
+    ts = Timestamp()
+    ts.FromDatetime(datetime(2025, 4, 1, 10, 0, 0, tzinfo=timezone.utc))
+    stub = FakeGalaxyStub()
+    # Use a "blocking" stream that never yields more after the first event.
+    stub.watch_deploy_events = FakeStream(
+        [galaxy_pb.DeployEvent(sequence=1, observed_at=ts)],
+        block_after_replies=True,
+    )
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", plaintext=True),
+        stub=stub,
+    )
+
+    iterator = client.watch_deploy_events()
+
+    first = await iterator.__anext__()
+    assert first.sequence == 1
+
+    # Break the iterator by aclose() — this should drive the cancel path.
+    await iterator.aclose()
+
+    assert stub.watch_deploy_events.cancel_called is True
+
+
+@pytest.mark.asyncio
+async def test_close_marks_channel_closed_when_no_real_channel() -> None:
+    stub = FakeGalaxyStub()
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", plaintext=True),
+        stub=stub,
+    )
+
+    await client.close()
+    # Idempotent: a second close should not raise.
+    await client.close()
+
+
+class FakeGalaxyStub:
+    def __init__(self) -> None:
+        self.test_connection = FakeUnary([galaxy_pb.TestConnectionReply(ok=False)])
+        self.get_last_deploy_time = FakeUnary([galaxy_pb.GetLastDeployTimeReply(present=False)])
+        self.discover_hierarchy = FakeUnary([galaxy_pb.DiscoverHierarchyReply()])
+        self.watch_deploy_events = FakeStream([])
+        self.TestConnection = self.test_connection
+        self.GetLastDeployTime = self.get_last_deploy_time
+        self.DiscoverHierarchy = self.discover_hierarchy
+
+    @property
+    def WatchDeployEvents(self) -> "FakeStream":  # noqa: N802 — gRPC naming
+        return self.watch_deploy_events
+
+
+class FakeUnary:
+    def __init__(self, replies: list[Any]) -> None:
+        self.replies = replies
+        self.requests: list[Any] = []
+        self.metadata: tuple[tuple[str, str], ...] | None = None
+
+    async def __call__(
+        self,
+        request: Any,
+        *,
+        metadata: tuple[tuple[str, str], ...],
+        timeout: float | None = None,
+    ) -> Any:
+        self.requests.append(request)
+        self.metadata = metadata
+        return self.replies.pop(0)
+
+
+class FakeStream:
+    """Sync-callable fake matching the gRPC unary-stream surface.
+
+    Calling the stub returns ``self`` (an async iterator). After exhausting the
+    seeded ``replies``, iteration either ends (default) or blocks indefinitely
+    (``block_after_replies=True``) so cancellation paths can be exercised.
+    """
+
+    def __init__(
+        self,
+        replies: list[Any],
+        *,
+        block_after_replies: bool = False,
+    ) -> None:
+        self.replies = list(replies)
+        self.requests: list[Any] = []
+        self.metadata: tuple[tuple[str, str], ...] | None = None
+        self.cancel_called = False
+        self._block_after_replies = block_after_replies
+
+    def __call__(
+        self,
+        request: Any,
+        *,
+        metadata: tuple[tuple[str, str], ...],
+        timeout: float | None = None,
+    ) -> "FakeStream":
+        self.requests.append(request)
+        self.metadata = metadata
+        return self
+
+    def __aiter__(self) -> "FakeStream":
+        return self
+
+    async def __anext__(self) -> Any:
+        if self.replies:
+            return self.replies.pop(0)
+        if self._block_after_replies:
+            # Sleep forever until the consumer cancels us.
+            await asyncio.Event().wait()
+        raise StopAsyncIteration
+
+    def cancel(self) -> None:
+        self.cancel_called = True

clients/rust/Cargo.lock

@@ -595,6 +595,7 @@ dependencies = [
  "clap",
  "futures-util",
  "mxgateway-client",
+ "prost-types",
  "serde",
  "serde_json",
  "tokio",
@@ -886,6 +887,16 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
 
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+
 [[package]]
 name = "slab"
 version = "0.4.12"
@@ -990,6 +1001,7 @@ dependencies = [
  "libc",
  "mio",
  "pin-project-lite",
+ "signal-hook-registry",
  "socket2 0.6.3",
  "tokio-macros",
  "windows-sys 0.61.2",

clients/rust/README.md

@@ -38,6 +38,18 @@ cargo clippy --workspace --all-targets -- -D warnings
 The build script uses `protoc` from `PATH` or the Windows path recorded in
 `../../docs/toolchain-links.md`.
 
+## Packaging
+
+Create local release artifacts from `clients/rust`:
+
+```powershell
+cargo build --workspace --release
+cargo install --path crates/mxgw-cli --locked --force
+```
+
+`cargo check --workspace` regenerates the `tonic` and `prost` modules into
+Cargo build output through `build.rs`.
+
 ## CLI
 
 The CLI exposes version, session, command, event stream, write, and smoke
@@ -58,6 +70,10 @@ CLI reads the API key from `--api-key` or from `--api-key-env`, which defaults
 to `MXGATEWAY_API_KEY`. API keys are redacted by the library option and secret
 types.
 
+```powershell
+cargo run -p mxgw-cli -- smoke --endpoint https://mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item TestChildObject.TestInt --json
+```
+
 ## Library Surface
 
 `ClientOptions` configures endpoint, API key, plaintext or TLS transport,
@@ -83,8 +99,91 @@ preserving the raw message for parity diagnostics. Command replies whose
 protocol status is not `PROTOCOL_STATUS_CODE_OK` become `Error::Command` and
 retain the raw `MxCommandReply`.
 
+## Galaxy Repository browse
+
+The Galaxy Repository service exposes a read-only browse over the AVEVA System
+Platform Galaxy Repository (ZB SQL database). It uses the same API-key auth as
+the gateway service but requires the `metadata:read` scope on the server.
+
+[`GalaxyClient`](src/galaxy.rs) wraps the generated Galaxy bindings the same
+way [`GatewayClient`](src/client.rs) wraps the gateway bindings:
+
+```rust
+let mut galaxy = GalaxyClient::connect(
+    ClientOptions::new("http://localhost:5000")
+        .with_api_key(ApiKey::new(api_key)),
+).await?;
+
+let ok = galaxy.test_connection().await?;
+let last_deploy = galaxy.get_last_deploy_time().await?; // Option<prost_types::Timestamp>
+let objects = galaxy.discover_hierarchy().await?;       // Vec<GalaxyObject>
+```
+
+`get_last_deploy_time` returns `None` when the server reports
+`present = false`. `discover_hierarchy` returns the generated
+`GalaxyObject` proto type (re-exported via
+`mxgateway_client::generated::galaxy_repository::v1`) with all attributes
+attached.
+
+The CLI ships matching subcommands under `galaxy`:
+
+```powershell
+cargo run -p mxgw-cli -- galaxy test-connection --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+cargo run -p mxgw-cli -- galaxy last-deploy-time --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+cargo run -p mxgw-cli -- galaxy discover-hierarchy --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+```
+
+### Watching deploy events
+
+`watch_deploy_events` opens the `WatchDeployEvents` server stream. The
+server emits a bootstrap [`DeployEvent`](src/galaxy.rs) describing the
+current cache state on subscribe, then one event each time the cached
+`galaxy.time_of_last_deploy` changes. `sequence` is monotonic per server
+start; gaps signal that the per-subscriber buffer dropped older events.
+Pass `last_seen_deploy_time` to suppress the bootstrap event when the
+client's cached deploy time matches the server's.
+
+```rust
+use futures_util::StreamExt;
+
+let mut stream = galaxy.watch_deploy_events(None).await?;
+while let Some(event) = stream.next().await {
+    let event = event?;
+    println!(
+        "seq={} objects={} attributes={}",
+        event.sequence, event.object_count, event.attribute_count,
+    );
+}
+// Drop the stream to cancel the gRPC call.
+```
+
+The matching CLI subcommand prints one line per event (`--json` switches to
+one JSON object per event). `--last-seen-deploy-time` accepts an RFC3339
+timestamp and is forwarded to the server. `--max-events` (default 0 = no
+cap) lets you stop after a fixed number of events; otherwise the command
+runs until the stream ends or `Ctrl+C` is pressed.
+
+```powershell
+cargo run -p mxgw-cli -- galaxy watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
+cargo run -p mxgw-cli -- galaxy watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+cargo run -p mxgw-cli -- galaxy watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --last-seen-deploy-time 2026-04-28T15:30:00Z
+```
+
+## Integration Checks
+
+Run live checks only when a gateway and MXAccess-backed worker are available:
+
+```powershell
+$env:MXGATEWAY_INTEGRATION = '1'
+$env:MXGATEWAY_ENDPOINT = 'http://127.0.0.1:5000'
+$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
+$env:MXGATEWAY_TEST_ITEM = 'TestChildObject.TestInt'
+cargo run -p mxgw-cli -- smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+```
+
 ## Related Documentation
 
+- [Client Packaging](../../docs/ClientPackaging.md)
 - [Client Proto Generation](../../docs/client-proto-generation.md)
 - [Rust Client Detailed Design](../../docs/clients-rust-design.md)
 - [Rust Style Guide](../../docs/style-guides/RustStyleGuide.md)

clients/rust/build.rs

@@ -13,17 +13,23 @@ fn main() -> Result<(), Box<dyn Error>> {
     let proto_root = repo_root.join("src/MxGateway.Contracts/Protos");
     let gateway_proto = proto_root.join("mxaccess_gateway.proto");
     let worker_proto = proto_root.join("mxaccess_worker.proto");
+    let galaxy_proto = proto_root.join("galaxy_repository.proto");
     let descriptor_path = PathBuf::from(env::var("OUT_DIR")?).join("mxaccessgw-client-v1.protoset");
 
     println!("cargo:rerun-if-changed={}", gateway_proto.display());
     println!("cargo:rerun-if-changed={}", worker_proto.display());
+    println!("cargo:rerun-if-changed={}", galaxy_proto.display());
 
     tonic_build::configure()
         .build_server(true)
         .build_client(true)
         .file_descriptor_set_path(descriptor_path)
         .compile_protos(
-            &[gateway_proto.as_path(), worker_proto.as_path()],
+            &[
+                gateway_proto.as_path(),
+                worker_proto.as_path(),
+                galaxy_proto.as_path(),
+            ],
             &[proto_root.as_path()],
         )?;
 

clients/rust/crates/mxgw-cli/Cargo.toml

@@ -12,6 +12,7 @@ path = "src/main.rs"
 clap = { workspace = true }
 futures-util = { workspace = true }
 mxgateway-client = { path = "../.." }
+prost-types = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
-tokio = { workspace = true }
+tokio = { workspace = true, features = ["macros", "rt-multi-thread", "signal", "sync", "time"] }

clients/rust/crates/mxgw-cli/src/main.rs

@@ -5,17 +5,20 @@ use std::time::Duration;
 
 use clap::{Args, Parser, Subcommand, ValueEnum};
 use futures_util::StreamExt;
+use mxgateway_client::generated::galaxy_repository::v1::DeployEvent;
 use mxgateway_client::generated::mxaccess_gateway::v1::{
     CloseSessionRequest, MxCommand, MxCommandKind, MxCommandRequest, OpenSessionRequest,
     PingCommand, StreamEventsRequest,
 };
 use mxgateway_client::{
-    ApiKey, ClientOptions, Error, GatewayClient, MxValue, CLIENT_VERSION, GATEWAY_PROTOCOL_VERSION,
-    WORKER_PROTOCOL_VERSION,
+    ApiKey, ClientOptions, Error, GalaxyClient, GatewayClient, MxValue, CLIENT_VERSION,
+    GATEWAY_PROTOCOL_VERSION, WORKER_PROTOCOL_VERSION,
 };
 use serde_json::json;
 use serde_json::Value;
 
+const MAX_AGGREGATE_EVENTS: usize = 10_000;
+
 #[derive(Debug, Parser)]
 #[command(name = "mxgw")]
 #[command(about = "MXAccess Gateway Rust test CLI")]
@@ -29,6 +32,8 @@ enum Command {
     Version {
         #[arg(long)]
         json: bool,
+        #[arg(long)]
+        jsonl: bool,
     },
     Ping {
         #[command(flatten)]
@@ -88,6 +93,30 @@ enum Command {
         #[arg(long)]
         json: bool,
     },
+    SubscribeBulk {
+        #[command(flatten)]
+        connection: ConnectionArgs,
+        #[arg(long)]
+        session_id: String,
+        #[arg(long)]
+        server_handle: i32,
+        #[arg(long, value_delimiter = ',')]
+        items: Vec<String>,
+        #[arg(long)]
+        json: bool,
+    },
+    UnsubscribeBulk {
+        #[command(flatten)]
+        connection: ConnectionArgs,
+        #[arg(long)]
+        session_id: String,
+        #[arg(long)]
+        server_handle: i32,
+        #[arg(long, value_delimiter = ',')]
+        item_handles: Vec<i32>,
+        #[arg(long)]
+        json: bool,
+    },
     StreamEvents {
         #[command(flatten)]
         connection: ConnectionArgs,
@@ -99,6 +128,8 @@ enum Command {
         max_events: usize,
         #[arg(long)]
         json: bool,
+        #[arg(long)]
+        jsonl: bool,
     },
     Write {
         #[command(flatten)]
@@ -148,6 +179,51 @@ enum Command {
         #[arg(long)]
         json: bool,
     },
+    #[command(subcommand)]
+    Galaxy(GalaxyCommand),
+}
+
+#[derive(Debug, Subcommand)]
+enum GalaxyCommand {
+    TestConnection {
+        #[command(flatten)]
+        connection: ConnectionArgs,
+        #[arg(long)]
+        json: bool,
+    },
+    LastDeployTime {
+        #[command(flatten)]
+        connection: ConnectionArgs,
+        #[arg(long)]
+        json: bool,
+    },
+    DiscoverHierarchy {
+        #[command(flatten)]
+        connection: ConnectionArgs,
+        #[arg(long)]
+        json: bool,
+    },
+    /// Subscribe to the WatchDeployEvents server stream.
+    ///
+    /// Prints one line per received event (or one JSON object with `--json`).
+    /// Runs until the stream ends, the server fails the call, or the
+    /// process is interrupted (Ctrl+C).
+    #[command(alias = "watch-deploy-events")]
+    Watch {
+        #[command(flatten)]
+        connection: ConnectionArgs,
+        /// Optional RFC3339 timestamp (e.g. `2026-04-28T15:30:00Z`). When
+        /// supplied, the server suppresses the bootstrap event if its
+        /// cached deploy time matches this value.
+        #[arg(long)]
+        last_seen_deploy_time: Option<String>,
+        /// Optional cap on the number of events to print before exiting.
+        /// 0 (the default) means run until cancelled or the stream ends.
+        #[arg(long, default_value_t = 0)]
+        max_events: usize,
+        #[arg(long)]
+        json: bool,
+    },
 }
 
 #[derive(Debug, Args, Clone)]
@@ -222,7 +298,7 @@ async fn main() -> ExitCode {
 
 async fn run(cli: Cli) -> Result<(), Error> {
     match cli.command {
-        Command::Version { json } => print_version(json),
+        Command::Version { json, .. } => print_version(json),
         Command::Ping {
             connection,
             message,
@@ -319,13 +395,45 @@ async fn run(cli: Cli) -> Result<(), Error> {
             session.advise(server_handle, item_handle).await?;
             print_ok("advise", json);
         }
+        Command::SubscribeBulk {
+            connection,
+            session_id,
+            server_handle,
+            items,
+            json,
+        } => {
+            let session = session_for(connection, session_id).await?;
+            let results = session.subscribe_bulk(server_handle, items).await?;
+            print_bulk_results("subscribe-bulk", &results, json);
+        }
+        Command::UnsubscribeBulk {
+            connection,
+            session_id,
+            server_handle,
+            item_handles,
+            json,
+        } => {
+            let session = session_for(connection, session_id).await?;
+            let results = session
+                .unsubscribe_bulk(server_handle, item_handles)
+                .await?;
+            print_bulk_results("unsubscribe-bulk", &results, json);
+        }
         Command::StreamEvents {
             connection,
             session_id,
             after_worker_sequence,
             max_events,
             json,
+            jsonl,
         } => {
+            if max_events > MAX_AGGREGATE_EVENTS {
+                return Err(Error::InvalidArgument {
+                    name: "max-events".to_owned(),
+                    detail: format!("must be less than or equal to {MAX_AGGREGATE_EVENTS}"),
+                });
+            }
+
             let client = connect(connection).await?;
             let mut stream = client
                 .stream_events(StreamEventsRequest {
@@ -334,19 +442,30 @@ async fn run(cli: Cli) -> Result<(), Error> {
                 })
                 .await?;
             let mut events = Vec::new();
-            while events.len() < max_events {
+            let mut event_count = 0usize;
+            while event_count < max_events {
                 let Some(event) = stream.next().await else {
                     break;
                 };
-                events.push(event?);
-            }
-            if json {
-                println!("{}", json!({ "eventCount": events.len() }));
-            } else {
-                for event in events {
+                let event = event?;
+                event_count += 1;
+                if jsonl {
+                    println!(
+                        "{}",
+                        json!({
+                            "workerSequence": event.worker_sequence,
+                            "family": event.family,
+                        })
+                    );
+                } else if json {
+                    events.push(event);
+                } else {
                     println!("{} {}", event.worker_sequence, event.family);
                 }
             }
+            if json {
+                println!("{}", json!({ "eventCount": event_count }));
+            }
         }
         Command::Write {
             connection,
@@ -392,6 +511,7 @@ async fn run(cli: Cli) -> Result<(), Error> {
                 .await?;
             print_ok("write2", json);
         }
+        Command::Galaxy(galaxy_command) => run_galaxy(galaxy_command).await?,
         Command::Smoke {
             connection,
             item,
@@ -441,6 +561,133 @@ async fn connect(connection: ConnectionArgs) -> Result<GatewayClient, Error> {
     GatewayClient::connect(connection.options()).await
 }
 
+async fn connect_galaxy(connection: ConnectionArgs) -> Result<GalaxyClient, Error> {
+    GalaxyClient::connect(connection.options()).await
+}
+
+async fn run_galaxy(command: GalaxyCommand) -> Result<(), Error> {
+    match command {
+        GalaxyCommand::TestConnection { connection, json } => {
+            let mut client = connect_galaxy(connection).await?;
+            let ok = client.test_connection().await?;
+            if json {
+                println!("{}", json!({ "ok": ok }));
+            } else if ok {
+                println!("ok");
+            } else {
+                println!("not ok");
+            }
+        }
+        GalaxyCommand::LastDeployTime { connection, json } => {
+            let mut client = connect_galaxy(connection).await?;
+            let timestamp = client.get_last_deploy_time().await?;
+            match (json, timestamp) {
+                (true, Some(ts)) => {
+                    println!(
+                        "{}",
+                        json!({
+                            "present": true,
+                            "seconds": ts.seconds,
+                            "nanos": ts.nanos,
+                        })
+                    );
+                }
+                (true, None) => {
+                    println!("{}", json!({ "present": false }));
+                }
+                (false, Some(ts)) => println!("{}.{:09}", ts.seconds, ts.nanos),
+                (false, None) => println!("(absent)"),
+            }
+        }
+        GalaxyCommand::Watch {
+            connection,
+            last_seen_deploy_time,
+            max_events,
+            json,
+        } => {
+            let mut client = connect_galaxy(connection).await?;
+            let last_seen = last_seen_deploy_time
+                .as_deref()
+                .map(parse_rfc3339_timestamp)
+                .transpose()?;
+            let mut stream = client.watch_deploy_events(last_seen).await?;
+
+            let mut count = 0usize;
+            loop {
+                tokio::select! {
+                    biased;
+                    signal = tokio::signal::ctrl_c() => {
+                        signal.map_err(|err| Error::InvalidArgument {
+                            name: "ctrl_c".to_owned(),
+                            detail: err.to_string(),
+                        })?;
+                        // Drop the stream below by breaking; tonic tears the
+                        // gRPC call down cooperatively.
+                        break;
+                    }
+                    next = stream.next() => {
+                        let Some(event) = next else { break; };
+                        let event = event?;
+                        count += 1;
+                        print_deploy_event(&event, json);
+                        if max_events != 0 && count >= max_events {
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+        GalaxyCommand::DiscoverHierarchy { connection, json } => {
+            let mut client = connect_galaxy(connection).await?;
+            let objects = client.discover_hierarchy().await?;
+            if json {
+                let payload: Vec<_> = objects
+                    .iter()
+                    .map(|object| {
+                        json!({
+                            "gobjectId": object.gobject_id,
+                            "tagName": object.tag_name,
+                            "containedName": object.contained_name,
+                            "browseName": object.browse_name,
+                            "parentGobjectId": object.parent_gobject_id,
+                            "isArea": object.is_area,
+                            "categoryId": object.category_id,
+                            "hostedByGobjectId": object.hosted_by_gobject_id,
+                            "templateChain": object.template_chain,
+                            "attributes": object.attributes.iter().map(|attribute| json!({
+                                "attributeName": attribute.attribute_name,
+                                "fullTagReference": attribute.full_tag_reference,
+                                "mxDataType": attribute.mx_data_type,
+                                "dataTypeName": attribute.data_type_name,
+                                "isArray": attribute.is_array,
+                                "arrayDimension": attribute.array_dimension,
+                                "arrayDimensionPresent": attribute.array_dimension_present,
+                                "mxAttributeCategory": attribute.mx_attribute_category,
+                                "securityClassification": attribute.security_classification,
+                                "isHistorized": attribute.is_historized,
+                                "isAlarm": attribute.is_alarm,
+                            })).collect::<Vec<_>>(),
+                        })
+                    })
+                    .collect();
+                println!("{}", json!({ "objects": payload }));
+            } else {
+                println!("{}", objects.len());
+                for object in &objects {
+                    println!(
+                        "{} {} {} ({} attribute(s))",
+                        object.gobject_id,
+                        object.tag_name,
+                        object.browse_name,
+                        object.attributes.len()
+                    );
+                }
+            }
+        }
+    }
+    Ok(())
+}
+
 async fn session_for(
     connection: ConnectionArgs,
     session_id: String,
@@ -504,6 +751,33 @@ fn print_ok(operation: &str, use_json: bool) {
     }
 }
 
+fn print_bulk_results(
+    operation: &str,
+    results: &[mxgateway_client::generated::mxaccess_gateway::v1::SubscribeResult],
+    use_json: bool,
+) {
+    if use_json {
+        let results_json: Vec<_> = results
+            .iter()
+            .map(|result| {
+                json!({
+                    "serverHandle": result.server_handle,
+                    "tagAddress": result.tag_address,
+                    "itemHandle": result.item_handle,
+                    "wasSuccessful": result.was_successful,
+                    "errorMessage": result.error_message,
+                })
+            })
+            .collect();
+        println!(
+            "{}",
+            json!({ "operation": operation, "results": results_json })
+        );
+    } else {
+        println!("{}", results.len());
+    }
+}
+
 fn parse_value(value_type: CliValueType, value: &str) -> Result<MxValue, Error> {
     let parsed = match value_type {
         CliValueType::Bool => MxValue::bool(parse_cli_value(value)?),
@@ -516,6 +790,208 @@ fn parse_value(value_type: CliValueType, value: &str) -> Result<MxValue, Error>
     Ok(parsed)
 }
 
+fn print_deploy_event(event: &DeployEvent, use_json: bool) {
+    if use_json {
+        println!(
+            "{}",
+            json!({
+                "sequence": event.sequence,
+                "observedAt": event.observed_at.as_ref().map(|ts| json!({
+                    "seconds": ts.seconds,
+                    "nanos": ts.nanos,
+                })),
+                "timeOfLastDeploy": event.time_of_last_deploy.as_ref().map(|ts| json!({
+                    "seconds": ts.seconds,
+                    "nanos": ts.nanos,
+                })),
+                "timeOfLastDeployPresent": event.time_of_last_deploy_present,
+                "objectCount": event.object_count,
+                "attributeCount": event.attribute_count,
+            })
+        );
+    } else {
+        let observed = event
+            .observed_at
+            .as_ref()
+            .map(|ts| format!("{}.{:09}", ts.seconds, ts.nanos))
+            .unwrap_or_else(|| "(absent)".to_owned());
+        let last_deploy = if event.time_of_last_deploy_present {
+            event
+                .time_of_last_deploy
+                .as_ref()
+                .map(|ts| format!("{}.{:09}", ts.seconds, ts.nanos))
+                .unwrap_or_else(|| "(absent)".to_owned())
+        } else {
+            "(absent)".to_owned()
+        };
+        println!(
+            "seq={} observed={} lastDeploy={} objects={} attributes={}",
+            event.sequence, observed, last_deploy, event.object_count, event.attribute_count,
+        );
+    }
+}
+
+/// Parse a small but practically-complete subset of RFC3339:
+/// `YYYY-MM-DDTHH:MM:SS[.fffffffff][Z|+HH:MM|-HH:MM]`. Returns the
+/// corresponding `prost_types::Timestamp` (Unix seconds + nanoseconds).
+fn parse_rfc3339_timestamp(input: &str) -> Result<prost_types::Timestamp, Error> {
+    fn invalid(detail: impl Into<String>) -> Error {
+        Error::InvalidArgument {
+            name: "last-seen-deploy-time".to_owned(),
+            detail: detail.into(),
+        }
+    }
+
+    let bytes = input.as_bytes();
+    if bytes.len() < 20 || (bytes[10] != b'T' && bytes[10] != b't') {
+        return Err(invalid(format!(
+            "expected RFC3339 timestamp like 2026-04-28T15:30:00Z, got {input:?}"
+        )));
+    }
+
+    let read_u32 = |start: usize, len: usize| -> Result<u32, Error> {
+        std::str::from_utf8(&bytes[start..start + len])
+            .ok()
+            .and_then(|slice| slice.parse::<u32>().ok())
+            .ok_or_else(|| invalid(format!("non-numeric digits at byte {start}")))
+    };
+
+    let year = read_u32(0, 4)? as i32;
+    if bytes[4] != b'-' {
+        return Err(invalid("expected '-' after year"));
+    }
+    let month = read_u32(5, 2)?;
+    if bytes[7] != b'-' {
+        return Err(invalid("expected '-' after month"));
+    }
+    let day = read_u32(8, 2)?;
+    let hour = read_u32(11, 2)?;
+    if bytes[13] != b':' {
+        return Err(invalid("expected ':' after hour"));
+    }
+    let minute = read_u32(14, 2)?;
+    if bytes[16] != b':' {
+        return Err(invalid("expected ':' after minute"));
+    }
+    let second = read_u32(17, 2)?;
+
+    let mut cursor = 19usize;
+    let mut nanos: u32 = 0;
+    if cursor < bytes.len() && bytes[cursor] == b'.' {
+        cursor += 1;
+        let frac_start = cursor;
+        while cursor < bytes.len() && bytes[cursor].is_ascii_digit() {
+            cursor += 1;
+        }
+        let frac_len = cursor - frac_start;
+        if frac_len == 0 {
+            return Err(invalid("expected fractional digits after '.'"));
+        }
+        let take = frac_len.min(9);
+        let frac = std::str::from_utf8(&bytes[frac_start..frac_start + take])
+            .ok()
+            .and_then(|slice| slice.parse::<u32>().ok())
+            .ok_or_else(|| invalid("invalid fractional digits"))?;
+        nanos = frac * 10u32.pow(9u32.saturating_sub(take as u32));
+    }
+
+    let mut offset_seconds: i64 = 0;
+    if cursor >= bytes.len() {
+        return Err(invalid("missing timezone designator (Z or +HH:MM)"));
+    }
+    match bytes[cursor] {
+        b'Z' | b'z' => cursor += 1,
+        sign @ (b'+' | b'-') => {
+            cursor += 1;
+            if cursor + 5 > bytes.len() {
+                return Err(invalid("offset must be ±HH:MM"));
+            }
+            let oh = std::str::from_utf8(&bytes[cursor..cursor + 2])
+                .ok()
+                .and_then(|slice| slice.parse::<i64>().ok())
+                .ok_or_else(|| invalid("invalid offset hour"))?;
+            if bytes[cursor + 2] != b':' {
+                return Err(invalid("offset must contain ':' between HH and MM"));
+            }
+            let om = std::str::from_utf8(&bytes[cursor + 3..cursor + 5])
+                .ok()
+                .and_then(|slice| slice.parse::<i64>().ok())
+                .ok_or_else(|| invalid("invalid offset minute"))?;
+            cursor += 5;
+            let signed = if sign == b'-' { -1 } else { 1 };
+            offset_seconds = signed * (oh * 3600 + om * 60);
+        }
+        other => {
+            return Err(invalid(format!(
+                "unexpected timezone designator byte {other:?}"
+            )));
+        }
+    }
+    if cursor != bytes.len() {
+        return Err(invalid("trailing characters after timezone"));
+    }
+
+    let unix = ymdhms_to_unix(year, month, day, hour, minute, second)?;
+    let seconds = unix - offset_seconds;
+
+    Ok(prost_types::Timestamp {
+        seconds,
+        nanos: nanos as i32,
+    })
+}
+
+fn ymdhms_to_unix(
+    year: i32,
+    month: u32,
+    day: u32,
+    hour: u32,
+    minute: u32,
+    second: u32,
+) -> Result<i64, Error> {
+    if !(1..=12).contains(&month) || day < 1 || hour > 23 || minute > 59 || second > 60 {
+        return Err(Error::InvalidArgument {
+            name: "last-seen-deploy-time".to_owned(),
+            detail: "calendar component out of range".to_owned(),
+        });
+    }
+    fn is_leap(year: i32) -> bool {
+        (year % 4 == 0 && year % 100 != 0) || year % 400 == 0
+    }
+    const DAYS: [u32; 12] = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    let mut max = DAYS[(month - 1) as usize];
+    if month == 2 && is_leap(year) {
+        max = 29;
+    }
+    if day > max {
+        return Err(Error::InvalidArgument {
+            name: "last-seen-deploy-time".to_owned(),
+            detail: format!("day {day} out of range for month {month}/{year}"),
+        });
+    }
+
+    // Days from 1970-01-01 to year-month-day.
+    let mut total_days: i64 = 0;
+    if year >= 1970 {
+        for y in 1970..year {
+            total_days += if is_leap(y) { 366 } else { 365 };
+        }
+    } else {
+        for y in year..1970 {
+            total_days -= if is_leap(y) { 366 } else { 365 };
+        }
+    }
+    for m in 1..month {
+        let mut dim = DAYS[(m - 1) as usize];
+        if m == 2 && is_leap(year) {
+            dim = 29;
+        }
+        total_days += dim as i64;
+    }
+    total_days += (day - 1) as i64;
+
+    Ok(total_days * 86_400 + hour as i64 * 3600 + minute as i64 * 60 + second as i64)
+}
+
 fn parse_cli_value<T>(value: &str) -> Result<T, Error>
 where
     T: std::str::FromStr,
@@ -562,7 +1038,41 @@ mod tests {
     fn version_json_output_has_protocol_versions() {
         let value = super::version_json();
 
-        assert_eq!(value["gatewayProtocolVersion"], 1);
+        assert_eq!(value["gatewayProtocolVersion"], 2);
         assert_eq!(value["workerProtocolVersion"], 1);
     }
+
+    #[test]
+    fn parses_galaxy_watch_command_with_last_seen_and_max_events() {
+        let parsed = Cli::try_parse_from([
+            "mxgw",
+            "galaxy",
+            "watch",
+            "--last-seen-deploy-time",
+            "2026-04-28T15:30:00Z",
+            "--max-events",
+            "5",
+            "--json",
+        ]);
+        assert!(parsed.is_ok(), "parse failed: {parsed:?}");
+    }
+
+    #[test]
+    fn parses_galaxy_watch_deploy_events_alias() {
+        let parsed = Cli::try_parse_from(["mxgw", "galaxy", "watch-deploy-events"]);
+        assert!(parsed.is_ok(), "parse failed: {parsed:?}");
+    }
+
+    #[test]
+    fn rfc3339_parser_round_trips_z_and_offset_inputs() {
+        // 2026-04-28T15:30:00Z = 1_777_995_000 (sanity-checked once below)
+        let utc = super::parse_rfc3339_timestamp("2026-04-28T15:30:00Z").unwrap();
+        let plus = super::parse_rfc3339_timestamp("2026-04-28T16:30:00+01:00").unwrap();
+        let frac = super::parse_rfc3339_timestamp("2026-04-28T15:30:00.250Z").unwrap();
+
+        assert_eq!(utc.seconds, plus.seconds);
+        assert_eq!(utc.nanos, 0);
+        assert_eq!(frac.seconds, utc.seconds);
+        assert_eq!(frac.nanos, 250_000_000);
+    }
 }

clients/rust/src/client.rs

@@ -5,7 +5,7 @@ use tonic::transport::{Certificate, Channel, ClientTlsConfig};
 use tonic::Request;
 
 use crate::auth::AuthInterceptor;
-use crate::error::{ensure_command_success, Error};
+use crate::error::{ensure_command_success, ensure_protocol_success, Error};
 use crate::generated::mxaccess_gateway::v1::mx_access_gateway_client::MxAccessGatewayClient;
 use crate::generated::mxaccess_gateway::v1::{
     CloseSessionReply, CloseSessionRequest, MxCommandReply, MxCommandRequest, MxEvent,
@@ -23,6 +23,7 @@ pub type EventStream =
 pub struct GatewayClient {
     inner: RawGatewayClient,
     call_timeout: std::time::Duration,
+    stream_timeout: Option<std::time::Duration>,
 }
 
 impl GatewayClient {
@@ -53,10 +54,14 @@ impl GatewayClient {
 
         let channel = endpoint.connect().await?;
         let interceptor = AuthInterceptor::new(options.api_key().cloned());
+        let max_grpc_message_bytes = options.max_grpc_message_bytes();
 
         Ok(Self {
-            inner: MxAccessGatewayClient::with_interceptor(channel, interceptor),
+            inner: MxAccessGatewayClient::with_interceptor(channel, interceptor)
+                .max_decoding_message_size(max_grpc_message_bytes)
+                .max_encoding_message_size(max_grpc_message_bytes),
             call_timeout: options.call_timeout(),
+            stream_timeout: options.stream_timeout(),
         })
     }
 
@@ -83,6 +88,7 @@ impl GatewayClient {
 
     pub async fn open_session(&self, request: OpenSessionRequest) -> Result<Session, Error> {
         let reply = self.open_session_raw(request).await?;
+        ensure_protocol_success("open session", reply.protocol_status.as_ref())?;
         Ok(Session::new(reply.session_id, self.clone()))
     }
 
@@ -107,7 +113,7 @@ impl GatewayClient {
 
     pub async fn stream_events(&self, request: StreamEventsRequest) -> Result<EventStream, Error> {
         let mut client = self.inner.clone();
-        let response = client.stream_events(self.unary_request(request)).await?;
+        let response = client.stream_events(self.stream_request(request)).await?;
         let stream = futures_util::StreamExt::map(response.into_inner(), |result| {
             result.map_err(Error::from)
         });
@@ -120,4 +126,13 @@ impl GatewayClient {
         request.set_timeout(self.call_timeout);
         request
     }
+
+    fn stream_request<T>(&self, message: T) -> Request<T> {
+        let mut request = Request::new(message);
+        if let Some(timeout) = self.stream_timeout {
+            request.set_timeout(timeout);
+        }
+
+        request
+    }
 }

clients/rust/src/error.rs

@@ -1,7 +1,7 @@
 use thiserror::Error as ThisError;
 use tonic::Code;
 
-use crate::generated::mxaccess_gateway::v1::{MxCommandReply, ProtocolStatusCode};
+use crate::generated::mxaccess_gateway::v1::{MxCommandReply, ProtocolStatus, ProtocolStatusCode};
 
 #[derive(Debug, ThisError)]
 pub enum Error {
@@ -47,6 +47,13 @@ pub enum Error {
 
     #[error("gateway command failed: {0}")]
     Command(#[from] Box<CommandError>),
+
+    #[error("gateway {operation} failed: {code:?}: {message}")]
+    ProtocolStatus {
+        operation: &'static str,
+        code: ProtocolStatusCode,
+        message: String,
+    },
 }
 
 #[derive(Clone, Debug)]
@@ -125,6 +132,27 @@ pub fn ensure_command_success(reply: MxCommandReply) -> Result<MxCommandReply, E
     }
 }
 
+pub fn ensure_protocol_success(
+    operation: &'static str,
+    status: Option<&ProtocolStatus>,
+) -> Result<(), Error> {
+    let code = status
+        .and_then(|status| ProtocolStatusCode::try_from(status.code).ok())
+        .unwrap_or(ProtocolStatusCode::Unspecified);
+
+    if code == ProtocolStatusCode::Ok {
+        Ok(())
+    } else {
+        Err(Error::ProtocolStatus {
+            operation,
+            code,
+            message: status
+                .map(|status| status.message.clone())
+                .unwrap_or_default(),
+        })
+    }
+}
+
 fn redact_credentials(message: &str) -> String {
     message
         .split_whitespace()

clients/rust/src/galaxy.rs

@@ -0,0 +1,698 @@
+//! Thin async wrapper for the `GalaxyRepository` gRPC service.
+//!
+//! The wrapper mirrors [`crate::client::GatewayClient`]: it owns a tonic
+//! channel with the shared bearer-token interceptor and exposes the three
+//! read-only RPCs as Rust async methods. Generated Galaxy proto types are
+//! re-exported through [`crate::generated::galaxy_repository::v1`].
+
+use std::fs;
+
+use prost_types::Timestamp;
+use tonic::codegen::InterceptedService;
+use tonic::transport::{Certificate, Channel, ClientTlsConfig};
+use tonic::Request;
+
+use crate::auth::AuthInterceptor;
+use crate::error::Error;
+use crate::generated::galaxy_repository::v1::galaxy_repository_client::GalaxyRepositoryClient;
+use crate::generated::galaxy_repository::v1::{
+    DeployEvent, DiscoverHierarchyRequest, GalaxyObject, GetLastDeployTimeRequest,
+    TestConnectionRequest, WatchDeployEventsRequest,
+};
+use crate::options::ClientOptions;
+
+const DISCOVER_HIERARCHY_PAGE_SIZE: i32 = 5000;
+
+/// Convenience alias for the generated Galaxy client wrapped in the
+/// authentication interceptor.
+pub type RawGalaxyClient = GalaxyRepositoryClient<InterceptedService<Channel, AuthInterceptor>>;
+
+/// Stream of `DeployEvent` values returned by
+/// [`GalaxyClient::watch_deploy_events`]. Mirrors
+/// [`crate::client::EventStream`]: a boxed `Stream` whose `tonic::Status`
+/// errors have already been mapped onto [`Error`]. Dropping the stream
+/// cancels the underlying gRPC call.
+pub type DeployEventStream = std::pin::Pin<
+    Box<dyn futures_core::Stream<Item = Result<DeployEvent, Error>> + Send + 'static>,
+>;
+
+/// Thin async wrapper around the generated Galaxy Repository gRPC client.
+///
+/// Construct it with [`GalaxyClient::connect`] using the same
+/// [`ClientOptions`] that drive [`crate::client::GatewayClient`]. The
+/// service is metadata-only (no sessions) and requires the `metadata:read`
+/// API-key scope on the server side.
+#[derive(Clone)]
+pub struct GalaxyClient {
+    inner: RawGalaxyClient,
+    call_timeout: std::time::Duration,
+    stream_timeout: Option<std::time::Duration>,
+}
+
+impl GalaxyClient {
+    /// Connect to the gateway endpoint and build a Galaxy client. Mirrors
+    /// the TLS / plaintext / API-key handling used by `GatewayClient`.
+    pub async fn connect(options: ClientOptions) -> Result<Self, Error> {
+        let mut endpoint =
+            Channel::from_shared(options.endpoint().to_owned()).map_err(|source| {
+                Error::InvalidEndpoint {
+                    endpoint: options.endpoint().to_owned(),
+                    detail: source.to_string(),
+                }
+            })?;
+        endpoint = endpoint.connect_timeout(options.connect_timeout());
+
+        if !options.plaintext() {
+            let mut tls = ClientTlsConfig::new();
+            if let Some(server_name) = options.server_name_override() {
+                tls = tls.domain_name(server_name.to_owned());
+            }
+            if let Some(ca_file) = options.ca_file() {
+                let certificate = fs::read(ca_file).map_err(|source| Error::InvalidEndpoint {
+                    endpoint: options.endpoint().to_owned(),
+                    detail: format!("failed to read CA file {}: {source}", ca_file.display()),
+                })?;
+                tls = tls.ca_certificate(Certificate::from_pem(certificate));
+            }
+            endpoint = endpoint.tls_config(tls)?;
+        }
+
+        let channel = endpoint.connect().await?;
+        let interceptor = AuthInterceptor::new(options.api_key().cloned());
+        let max_grpc_message_bytes = options.max_grpc_message_bytes();
+
+        Ok(Self {
+            inner: GalaxyRepositoryClient::with_interceptor(channel, interceptor)
+                .max_decoding_message_size(max_grpc_message_bytes)
+                .max_encoding_message_size(max_grpc_message_bytes),
+            call_timeout: options.call_timeout(),
+            stream_timeout: options.stream_timeout(),
+        })
+    }
+
+    /// Build a [`GalaxyClient`] that talks through an existing tonic
+    /// channel. Tests use this to wire up an in-memory transport.
+    pub fn from_channel(channel: Channel, options: &ClientOptions) -> Self {
+        let interceptor = AuthInterceptor::new(options.api_key().cloned());
+        let max_grpc_message_bytes = options.max_grpc_message_bytes();
+        Self {
+            inner: GalaxyRepositoryClient::with_interceptor(channel, interceptor)
+                .max_decoding_message_size(max_grpc_message_bytes)
+                .max_encoding_message_size(max_grpc_message_bytes),
+            call_timeout: options.call_timeout(),
+            stream_timeout: options.stream_timeout(),
+        }
+    }
+
+    /// Borrow the underlying generated client for advanced callers that need
+    /// access to features not surfaced by the wrapper.
+    pub fn raw_client(&mut self) -> &mut RawGalaxyClient {
+        &mut self.inner
+    }
+
+    /// Consume the wrapper and return the generated client.
+    pub fn into_inner(self) -> RawGalaxyClient {
+        self.inner
+    }
+
+    /// Probe the Galaxy Repository database connection. Returns the `ok`
+    /// flag from the server reply.
+    pub async fn test_connection(&mut self) -> Result<bool, Error> {
+        let response = self
+            .inner
+            .test_connection(self.unary_request(TestConnectionRequest {}))
+            .await?;
+        Ok(response.into_inner().ok)
+    }
+
+    /// Read the most recent Galaxy deployment timestamp. Returns `None`
+    /// when the server reports `present = false`.
+    pub async fn get_last_deploy_time(&mut self) -> Result<Option<Timestamp>, Error> {
+        let response = self
+            .inner
+            .get_last_deploy_time(self.unary_request(GetLastDeployTimeRequest {}))
+            .await?;
+        let reply = response.into_inner();
+        if reply.present {
+            Ok(reply.time_of_last_deploy)
+        } else {
+            Ok(None)
+        }
+    }
+
+    /// Walk the deployed object hierarchy. Each [`GalaxyObject`] contains
+    /// the object's identifying names plus its dynamic attributes.
+    pub async fn discover_hierarchy(&mut self) -> Result<Vec<GalaxyObject>, Error> {
+        let mut objects = Vec::new();
+        let mut seen_page_tokens = std::collections::HashSet::new();
+        let mut page_token = String::new();
+        loop {
+            let response = self
+                .inner
+                .discover_hierarchy(self.unary_request(DiscoverHierarchyRequest {
+                    page_size: DISCOVER_HIERARCHY_PAGE_SIZE,
+                    page_token,
+                    ..Default::default()
+                }))
+                .await?;
+            let reply = response.into_inner();
+            objects.extend(reply.objects);
+            page_token = reply.next_page_token;
+            if page_token.is_empty() {
+                return Ok(objects);
+            }
+            if !seen_page_tokens.insert(page_token.clone()) {
+                return Err(Error::InvalidArgument {
+                    name: "page_token".to_owned(),
+                    detail: format!(
+                        "galaxy discover hierarchy returned repeated page token `{page_token}`"
+                    ),
+                });
+            }
+        }
+    }
+
+    /// Subscribe to the server-streamed deploy-event feed.
+    ///
+    /// The server emits a bootstrap event describing the current cache state
+    /// immediately on subscribe, then one event per observed change to
+    /// `galaxy.time_of_last_deploy`. When `last_seen_deploy_time` matches the
+    /// current cache, the bootstrap event is suppressed and the stream stays
+    /// idle until the next deploy.
+    ///
+    /// Cancellation is cooperative: dropping the returned
+    /// [`DeployEventStream`] tears down the underlying gRPC call. Callers
+    /// drive consumption with `StreamExt::next` (or any other `Stream`
+    /// adapter).
+    pub async fn watch_deploy_events(
+        &mut self,
+        last_seen_deploy_time: Option<Timestamp>,
+    ) -> Result<DeployEventStream, Error> {
+        let request = WatchDeployEventsRequest {
+            last_seen_deploy_time,
+        };
+        let response = self
+            .inner
+            .watch_deploy_events(self.stream_request(request))
+            .await?;
+        let stream = futures_util::StreamExt::map(response.into_inner(), |result| {
+            result.map_err(Error::from)
+        });
+        Ok(Box::pin(stream))
+    }
+
+    fn unary_request<T>(&self, message: T) -> Request<T> {
+        let mut request = Request::new(message);
+        request.set_timeout(self.call_timeout);
+        request
+    }
+
+    fn stream_request<T>(&self, message: T) -> Request<T> {
+        let mut request = Request::new(message);
+        if let Some(timeout) = self.stream_timeout {
+            request.set_timeout(timeout);
+        }
+        request
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::pin::Pin;
+    use std::sync::{Arc, Mutex};
+
+    use futures_util::StreamExt;
+    use tokio::net::TcpListener;
+    use tokio::sync::mpsc;
+    use tokio_stream::wrappers::{ReceiverStream, TcpListenerStream};
+    use tonic::transport::Server;
+    use tonic::{Request, Response, Status};
+
+    use super::*;
+    use crate::auth::ApiKey;
+    use crate::generated::galaxy_repository::v1::galaxy_repository_server::{
+        GalaxyRepository, GalaxyRepositoryServer,
+    };
+    use crate::generated::galaxy_repository::v1::{
+        DeployEvent, DiscoverHierarchyReply, DiscoverHierarchyRequest, GalaxyAttribute,
+        GalaxyObject, GetLastDeployTimeReply, GetLastDeployTimeRequest, TestConnectionReply,
+        TestConnectionRequest, WatchDeployEventsRequest,
+    };
+
+    type DeployEventTx = mpsc::Sender<Result<DeployEvent, Status>>;
+
+    #[derive(Default)]
+    struct FakeState {
+        authorization: Mutex<Option<String>>,
+        present: Mutex<bool>,
+        last_deploy: Mutex<Option<Timestamp>>,
+        objects: Mutex<Vec<GalaxyObject>>,
+        discover_requests: Mutex<Vec<DiscoverHierarchyRequest>>,
+        discover_replies: Mutex<std::collections::VecDeque<DiscoverHierarchyReply>>,
+        watch_requests: Mutex<Vec<WatchDeployEventsRequest>>,
+        watch_events: Mutex<Vec<DeployEvent>>,
+        watch_senders: Mutex<Vec<DeployEventTx>>,
+        watch_drop_signal: Mutex<Option<mpsc::UnboundedSender<()>>>,
+    }
+
+    #[derive(Clone)]
+    struct FakeGalaxy {
+        state: Arc<FakeState>,
+    }
+
+    #[tonic::async_trait]
+    impl GalaxyRepository for FakeGalaxy {
+        async fn test_connection(
+            &self,
+            request: Request<TestConnectionRequest>,
+        ) -> Result<Response<TestConnectionReply>, Status> {
+            *self.state.authorization.lock().unwrap() = request
+                .metadata()
+                .get("authorization")
+                .and_then(|value| value.to_str().ok())
+                .map(str::to_owned);
+            Ok(Response::new(TestConnectionReply { ok: true }))
+        }
+
+        async fn get_last_deploy_time(
+            &self,
+            _request: Request<GetLastDeployTimeRequest>,
+        ) -> Result<Response<GetLastDeployTimeReply>, Status> {
+            let present = *self.state.present.lock().unwrap();
+            let time = self.state.last_deploy.lock().unwrap().clone();
+            Ok(Response::new(GetLastDeployTimeReply {
+                present,
+                time_of_last_deploy: time,
+            }))
+        }
+
+        async fn discover_hierarchy(
+            &self,
+            request: Request<DiscoverHierarchyRequest>,
+        ) -> Result<Response<DiscoverHierarchyReply>, Status> {
+            self.state
+                .discover_requests
+                .lock()
+                .unwrap()
+                .push(request.into_inner());
+            if let Some(reply) = self.state.discover_replies.lock().unwrap().pop_front() {
+                return Ok(Response::new(reply));
+            }
+
+            Ok(Response::new(DiscoverHierarchyReply {
+                objects: self.state.objects.lock().unwrap().clone(),
+                next_page_token: String::new(),
+                total_object_count: self.state.objects.lock().unwrap().len() as i32,
+            }))
+        }
+
+        type WatchDeployEventsStream =
+            Pin<Box<dyn tokio_stream::Stream<Item = Result<DeployEvent, Status>> + Send + 'static>>;
+
+        async fn watch_deploy_events(
+            &self,
+            request: Request<WatchDeployEventsRequest>,
+        ) -> Result<Response<Self::WatchDeployEventsStream>, Status> {
+            self.state
+                .watch_requests
+                .lock()
+                .unwrap()
+                .push(request.into_inner());
+
+            let preset = self.state.watch_events.lock().unwrap().clone();
+            let (tx, rx) = mpsc::channel::<Result<DeployEvent, Status>>(16);
+            for event in preset {
+                tx.send(Ok(event))
+                    .await
+                    .map_err(|err| Status::internal(err.to_string()))?;
+            }
+            self.state.watch_senders.lock().unwrap().push(tx.clone());
+
+            let drop_signal = self.state.watch_drop_signal.lock().unwrap().clone();
+            let stream = ReceiverStream::new(rx);
+            let stream: Pin<Box<dyn tokio_stream::Stream<Item = _> + Send + 'static>> =
+                if let Some(signal) = drop_signal {
+                    Box::pin(WatchStreamWithDropSignal {
+                        inner: stream,
+                        signal: Some(signal),
+                    })
+                } else {
+                    Box::pin(stream)
+                };
+
+            Ok(Response::new(stream))
+        }
+    }
+
+    /// Wraps the receiver stream so we can detect when the server-side stream
+    /// future is dropped (the client cancelled or dropped the stream). Used by
+    /// `watch_drop_tears_down_call`.
+    struct WatchStreamWithDropSignal<S> {
+        inner: S,
+        signal: Option<mpsc::UnboundedSender<()>>,
+    }
+
+    impl<S: tokio_stream::Stream + Unpin> tokio_stream::Stream for WatchStreamWithDropSignal<S> {
+        type Item = S::Item;
+
+        fn poll_next(
+            mut self: Pin<&mut Self>,
+            cx: &mut std::task::Context<'_>,
+        ) -> std::task::Poll<Option<Self::Item>> {
+            Pin::new(&mut self.inner).poll_next(cx)
+        }
+    }
+
+    impl<S> Drop for WatchStreamWithDropSignal<S> {
+        fn drop(&mut self) {
+            if let Some(signal) = self.signal.take() {
+                let _ = signal.send(());
+            }
+        }
+    }
+
+    async fn spawn_fake(state: Arc<FakeState>) -> String {
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let address = listener.local_addr().unwrap();
+        let incoming = TcpListenerStream::new(listener);
+        let service = GalaxyRepositoryServer::new(FakeGalaxy { state });
+        tokio::spawn(async move {
+            Server::builder()
+                .add_service(service)
+                .serve_with_incoming(incoming)
+                .await
+                .unwrap();
+        });
+        format!("http://{address}")
+    }
+
+    #[tokio::test]
+    async fn test_connection_attaches_bearer_metadata_and_returns_ok() {
+        let state = Arc::new(FakeState::default());
+        let endpoint = spawn_fake(state.clone()).await;
+
+        let mut client = GalaxyClient::connect(
+            ClientOptions::new(endpoint).with_api_key(ApiKey::new("mxgw_galaxy_secret")),
+        )
+        .await
+        .unwrap();
+
+        let ok = client.test_connection().await.unwrap();
+
+        assert!(ok);
+        assert_eq!(
+            state.authorization.lock().unwrap().as_deref(),
+            Some("Bearer mxgw_galaxy_secret")
+        );
+    }
+
+    #[tokio::test]
+    async fn get_last_deploy_time_returns_none_when_not_present() {
+        let state = Arc::new(FakeState::default());
+        *state.present.lock().unwrap() = false;
+        *state.last_deploy.lock().unwrap() = Some(Timestamp {
+            seconds: 1_700_000_000,
+            nanos: 0,
+        });
+        let endpoint = spawn_fake(state.clone()).await;
+
+        let mut client = GalaxyClient::connect(ClientOptions::new(endpoint))
+            .await
+            .unwrap();
+
+        let result = client.get_last_deploy_time().await.unwrap();
+
+        assert!(
+            result.is_none(),
+            "present=false on the wire must surface as None, got {result:?}"
+        );
+    }
+
+    #[tokio::test]
+    async fn get_last_deploy_time_returns_timestamp_when_present() {
+        let state = Arc::new(FakeState::default());
+        *state.present.lock().unwrap() = true;
+        *state.last_deploy.lock().unwrap() = Some(Timestamp {
+            seconds: 1_700_000_000,
+            nanos: 250_000_000,
+        });
+        let endpoint = spawn_fake(state.clone()).await;
+
+        let mut client = GalaxyClient::connect(ClientOptions::new(endpoint))
+            .await
+            .unwrap();
+
+        let result = client.get_last_deploy_time().await.unwrap();
+
+        let timestamp = result.expect("present=true should yield a timestamp");
+        assert_eq!(timestamp.seconds, 1_700_000_000);
+        assert_eq!(timestamp.nanos, 250_000_000);
+    }
+
+    #[tokio::test]
+    async fn discover_hierarchy_returns_objects_with_attributes() {
+        let state = Arc::new(FakeState::default());
+        state
+            .discover_replies
+            .lock()
+            .unwrap()
+            .push_back(DiscoverHierarchyReply {
+                objects: vec![GalaxyObject {
+                    gobject_id: 42,
+                    tag_name: "DelmiaReceiver_001".to_owned(),
+                    contained_name: "DelmiaReceiver".to_owned(),
+                    browse_name: "TestMachine_001/DelmiaReceiver".to_owned(),
+                    parent_gobject_id: 7,
+                    is_area: false,
+                    category_id: 3,
+                    hosted_by_gobject_id: 1,
+                    template_chain: vec!["$UserDefined".to_owned(), "$DelmiaReceiver".to_owned()],
+                    attributes: vec![GalaxyAttribute {
+                        attribute_name: "DownloadPath".to_owned(),
+                        full_tag_reference: "DelmiaReceiver_001.DownloadPath".to_owned(),
+                        mx_data_type: 8,
+                        data_type_name: "MxString".to_owned(),
+                        is_array: false,
+                        array_dimension: 0,
+                        array_dimension_present: false,
+                        mx_attribute_category: 2,
+                        security_classification: 1,
+                        is_historized: false,
+                        is_alarm: false,
+                    }],
+                }],
+                next_page_token: "page-2".to_owned(),
+                total_object_count: 2,
+            });
+        state
+            .discover_replies
+            .lock()
+            .unwrap()
+            .push_back(DiscoverHierarchyReply {
+                objects: vec![GalaxyObject {
+                    gobject_id: 43,
+                    tag_name: "DelmiaReceiver_002".to_owned(),
+                    contained_name: String::new(),
+                    browse_name: String::new(),
+                    parent_gobject_id: 0,
+                    is_area: false,
+                    category_id: 0,
+                    hosted_by_gobject_id: 0,
+                    template_chain: Vec::new(),
+                    attributes: Vec::new(),
+                }],
+                next_page_token: String::new(),
+                total_object_count: 2,
+            });
+        let endpoint = spawn_fake(state.clone()).await;
+
+        let mut client = GalaxyClient::connect(ClientOptions::new(endpoint))
+            .await
+            .unwrap();
+
+        let objects = client.discover_hierarchy().await.unwrap();
+
+        assert_eq!(objects.len(), 2);
+        let requests = state.discover_requests.lock().unwrap();
+        assert_eq!(requests.len(), 2);
+        assert_eq!(requests[0].page_size, 5000);
+        assert_eq!(requests[0].page_token, "");
+        assert_eq!(requests[1].page_token, "page-2");
+        assert_eq!(objects[0].tag_name, "DelmiaReceiver_001");
+        assert_eq!(objects[0].attributes.len(), 1);
+        assert_eq!(objects[0].attributes[0].attribute_name, "DownloadPath");
+        assert_eq!(
+            objects[0].attributes[0].full_tag_reference,
+            "DelmiaReceiver_001.DownloadPath"
+        );
+    }
+
+    #[tokio::test]
+    async fn discover_hierarchy_rejects_repeated_page_token() {
+        let state = Arc::new(FakeState::default());
+        state
+            .discover_replies
+            .lock()
+            .unwrap()
+            .push_back(DiscoverHierarchyReply {
+                objects: Vec::new(),
+                next_page_token: "7:1".to_owned(),
+                total_object_count: 1,
+            });
+        state
+            .discover_replies
+            .lock()
+            .unwrap()
+            .push_back(DiscoverHierarchyReply {
+                objects: Vec::new(),
+                next_page_token: "7:1".to_owned(),
+                total_object_count: 1,
+            });
+        let endpoint = spawn_fake(state).await;
+        let mut client = GalaxyClient::connect(ClientOptions::new(endpoint))
+            .await
+            .unwrap();
+
+        let error = client.discover_hierarchy().await.unwrap_err();
+
+        assert!(error.to_string().contains("repeated page token"));
+    }
+
+    #[tokio::test]
+    async fn watch_deploy_events_yields_events_in_order() {
+        let state = Arc::new(FakeState::default());
+        *state.watch_events.lock().unwrap() = vec![
+            DeployEvent {
+                sequence: 1,
+                observed_at: Some(Timestamp {
+                    seconds: 1_700_000_000,
+                    nanos: 0,
+                }),
+                time_of_last_deploy: Some(Timestamp {
+                    seconds: 1_699_000_000,
+                    nanos: 0,
+                }),
+                time_of_last_deploy_present: true,
+                object_count: 12,
+                attribute_count: 80,
+            },
+            DeployEvent {
+                sequence: 2,
+                observed_at: Some(Timestamp {
+                    seconds: 1_700_000_500,
+                    nanos: 0,
+                }),
+                time_of_last_deploy: Some(Timestamp {
+                    seconds: 1_699_500_000,
+                    nanos: 0,
+                }),
+                time_of_last_deploy_present: true,
+                object_count: 13,
+                attribute_count: 85,
+            },
+        ];
+        let endpoint = spawn_fake(state.clone()).await;
+
+        let mut client = GalaxyClient::connect(ClientOptions::new(endpoint))
+            .await
+            .unwrap();
+
+        let mut stream = client.watch_deploy_events(None).await.unwrap();
+
+        let first = stream
+            .next()
+            .await
+            .expect("bootstrap event")
+            .expect("ok deploy event");
+        let second = stream
+            .next()
+            .await
+            .expect("second event")
+            .expect("ok deploy event");
+
+        assert_eq!(first.sequence, 1);
+        assert_eq!(first.object_count, 12);
+        assert_eq!(second.sequence, 2);
+        assert_eq!(second.object_count, 13);
+        assert!(first.time_of_last_deploy_present);
+    }
+
+    #[tokio::test]
+    async fn watch_deploy_events_propagates_last_seen_deploy_time() {
+        let state = Arc::new(FakeState::default());
+        let endpoint = spawn_fake(state.clone()).await;
+
+        let mut client = GalaxyClient::connect(ClientOptions::new(endpoint))
+            .await
+            .unwrap();
+
+        let last_seen = Timestamp {
+            seconds: 1_699_999_999,
+            nanos: 123_456_789,
+        };
+        let stream = client.watch_deploy_events(Some(last_seen)).await.unwrap();
+
+        // Drop the stream right away — the test is solely about the request
+        // payload reaching the server.
+        drop(stream);
+
+        // Give the server task a moment to record the request.
+        for _ in 0..20 {
+            if !state.watch_requests.lock().unwrap().is_empty() {
+                break;
+            }
+            tokio::time::sleep(std::time::Duration::from_millis(10)).await;
+        }
+
+        let requests = state.watch_requests.lock().unwrap().clone();
+        assert_eq!(requests.len(), 1);
+        let recorded = requests[0]
+            .last_seen_deploy_time
+            .as_ref()
+            .expect("last_seen_deploy_time forwarded");
+        assert_eq!(recorded.seconds, last_seen.seconds);
+        assert_eq!(recorded.nanos, last_seen.nanos);
+    }
+
+    #[tokio::test]
+    async fn watch_deploy_events_drop_tears_down_call() {
+        let state = Arc::new(FakeState::default());
+        let (signal_tx, mut signal_rx) = mpsc::unbounded_channel();
+        *state.watch_drop_signal.lock().unwrap() = Some(signal_tx);
+        // Seed one event so the client gets something on the stream before we
+        // drop it; this proves the call is live.
+        *state.watch_events.lock().unwrap() = vec![DeployEvent {
+            sequence: 7,
+            observed_at: None,
+            time_of_last_deploy: None,
+            time_of_last_deploy_present: false,
+            object_count: 0,
+            attribute_count: 0,
+        }];
+        let endpoint = spawn_fake(state.clone()).await;
+
+        let mut client = GalaxyClient::connect(ClientOptions::new(endpoint))
+            .await
+            .unwrap();
+
+        let mut stream = client.watch_deploy_events(None).await.unwrap();
+        let event = stream
+            .next()
+            .await
+            .expect("bootstrap event")
+            .expect("ok deploy event");
+        assert_eq!(event.sequence, 7);
+
+        // Dropping the client-side stream must trigger the server-side stream
+        // future to be dropped as well, signalling cancellation.
+        drop(stream);
+
+        let drop_seen = tokio::time::timeout(std::time::Duration::from_secs(2), signal_rx.recv())
+            .await
+            .expect("server-side stream future was not dropped within 2s");
+        assert!(
+            drop_seen.is_some(),
+            "drop signal channel closed unexpectedly"
+        );
+    }
+}

clients/rust/src/generated.rs

@@ -13,3 +13,11 @@ pub mod mxaccess_worker {
         tonic::include_proto!("mxaccess_worker.v1");
     }
 }
+
+pub mod galaxy_repository {
+    pub mod v1 {
+        #![allow(clippy::large_enum_variant)]
+
+        tonic::include_proto!("galaxy_repository.v1");
+    }
+}

clients/rust/src/lib.rs

@@ -7,6 +7,7 @@
 pub mod auth;
 pub mod client;
 pub mod error;
+pub mod galaxy;
 pub mod generated;
 pub mod options;
 pub mod session;
@@ -16,6 +17,7 @@ pub mod version;
 pub use auth::{ApiKey, AuthInterceptor};
 pub use client::{EventStream, GatewayClient};
 pub use error::{CommandError, Error};
+pub use galaxy::{DeployEventStream, GalaxyClient};
 pub use options::ClientOptions;
 pub use session::Session;
 pub use value::{MxArrayProjection, MxArrayValue, MxStatus, MxValue, MxValueProjection};

clients/rust/src/options.rs

@@ -4,6 +4,8 @@ use std::time::Duration;
 
 use crate::auth::ApiKey;
 
+const DEFAULT_MAX_GRPC_MESSAGE_BYTES: usize = 16 * 1024 * 1024;
+
 #[derive(Clone)]
 pub struct ClientOptions {
     endpoint: String,
@@ -13,6 +15,8 @@ pub struct ClientOptions {
     server_name_override: Option<String>,
     connect_timeout: Duration,
     call_timeout: Duration,
+    stream_timeout: Option<Duration>,
+    max_grpc_message_bytes: usize,
 }
 
 impl ClientOptions {
@@ -25,6 +29,8 @@ impl ClientOptions {
             server_name_override: None,
             connect_timeout: Duration::from_secs(10),
             call_timeout: Duration::from_secs(30),
+            stream_timeout: None,
+            max_grpc_message_bytes: DEFAULT_MAX_GRPC_MESSAGE_BYTES,
         }
     }
 
@@ -58,6 +64,16 @@ impl ClientOptions {
         self
     }
 
+    pub fn with_stream_timeout(mut self, stream_timeout: Duration) -> Self {
+        self.stream_timeout = Some(stream_timeout);
+        self
+    }
+
+    pub fn with_max_grpc_message_bytes(mut self, max_grpc_message_bytes: usize) -> Self {
+        self.max_grpc_message_bytes = max_grpc_message_bytes;
+        self
+    }
+
     pub fn endpoint(&self) -> &str {
         &self.endpoint
     }
@@ -85,6 +101,14 @@ impl ClientOptions {
     pub fn call_timeout(&self) -> Duration {
         self.call_timeout
     }
+
+    pub fn stream_timeout(&self) -> Option<Duration> {
+        self.stream_timeout
+    }
+
+    pub fn max_grpc_message_bytes(&self) -> usize {
+        self.max_grpc_message_bytes
+    }
 }
 
 impl Default for ClientOptions {
@@ -104,6 +128,8 @@ impl fmt::Debug for ClientOptions {
             .field("server_name_override", &self.server_name_override)
             .field("connect_timeout", &self.connect_timeout)
             .field("call_timeout", &self.call_timeout)
+            .field("stream_timeout", &self.stream_timeout)
+            .field("max_grpc_message_bytes", &self.max_grpc_message_bytes)
             .finish()
     }
 }

clients/rust/src/session.rs

@@ -1,14 +1,18 @@
 use crate::client::{EventStream, GatewayClient};
-use crate::error::Error;
+use crate::error::{ensure_protocol_success, Error};
 use crate::generated::mxaccess_gateway::v1::mx_command::Payload;
 use crate::generated::mxaccess_gateway::v1::mx_command_reply;
 use crate::generated::mxaccess_gateway::v1::{
-    AddItem2Command, AddItemCommand, AdviseCommand, CloseSessionRequest, MxCommand, MxCommandKind,
-    MxCommandReply, MxCommandRequest, MxValue as ProtoMxValue, OpenSessionRequest, RegisterCommand,
-    StreamEventsRequest, Write2Command, WriteCommand,
+    AddItem2Command, AddItemBulkCommand, AddItemCommand, AdviseCommand, AdviseItemBulkCommand,
+    CloseSessionRequest, MxCommand, MxCommandKind, MxCommandReply, MxCommandRequest,
+    MxValue as ProtoMxValue, OpenSessionRequest, RegisterCommand, RemoveItemBulkCommand,
+    RemoveItemCommand, StreamEventsRequest, SubscribeBulkCommand, SubscribeResult, UnAdviseCommand,
+    UnAdviseItemBulkCommand, UnsubscribeBulkCommand, Write2Command, WriteCommand,
 };
 use crate::value::MxValue;
 
+const MAX_BULK_ITEMS: usize = 1_000;
+
 /// Session identifier returned by the gateway.
 #[derive(Clone)]
 pub struct Session {
@@ -38,12 +42,14 @@ impl Session {
     }
 
     pub async fn close(&self) -> Result<(), Error> {
-        self.client
+        let reply = self
+            .client
             .close_session_raw(CloseSessionRequest {
                 session_id: self.id.clone(),
                 client_correlation_id: "rust-client-close-session".to_owned(),
             })
             .await?;
+        ensure_protocol_success("close session", reply.protocol_status.as_ref())?;
         Ok(())
     }
 
@@ -94,6 +100,18 @@ impl Session {
         Ok(add_item2_handle(&reply))
     }
 
+    pub async fn remove_item(&self, server_handle: i32, item_handle: i32) -> Result<(), Error> {
+        self.invoke(
+            MxCommandKind::RemoveItem,
+            Payload::RemoveItem(RemoveItemCommand {
+                server_handle,
+                item_handle,
+            }),
+        )
+        .await?;
+        Ok(())
+    }
+
     pub async fn advise(&self, server_handle: i32, item_handle: i32) -> Result<(), Error> {
         self.invoke(
             MxCommandKind::Advise,
@@ -106,6 +124,132 @@ impl Session {
         Ok(())
     }
 
+    pub async fn un_advise(&self, server_handle: i32, item_handle: i32) -> Result<(), Error> {
+        self.invoke(
+            MxCommandKind::UnAdvise,
+            Payload::UnAdvise(UnAdviseCommand {
+                server_handle,
+                item_handle,
+            }),
+        )
+        .await?;
+        Ok(())
+    }
+
+    pub async fn add_item_bulk(
+        &self,
+        server_handle: i32,
+        tag_addresses: Vec<String>,
+    ) -> Result<Vec<SubscribeResult>, Error> {
+        ensure_bulk_size("tag_addresses", tag_addresses.len())?;
+        let reply = self
+            .invoke(
+                MxCommandKind::AddItemBulk,
+                Payload::AddItemBulk(AddItemBulkCommand {
+                    server_handle,
+                    tag_addresses,
+                }),
+            )
+            .await?;
+
+        Ok(bulk_results(reply, BulkReplyKind::AddItemBulk))
+    }
+
+    pub async fn advise_item_bulk(
+        &self,
+        server_handle: i32,
+        item_handles: Vec<i32>,
+    ) -> Result<Vec<SubscribeResult>, Error> {
+        ensure_bulk_size("item_handles", item_handles.len())?;
+        let reply = self
+            .invoke(
+                MxCommandKind::AdviseItemBulk,
+                Payload::AdviseItemBulk(AdviseItemBulkCommand {
+                    server_handle,
+                    item_handles,
+                }),
+            )
+            .await?;
+
+        Ok(bulk_results(reply, BulkReplyKind::AdviseItemBulk))
+    }
+
+    pub async fn remove_item_bulk(
+        &self,
+        server_handle: i32,
+        item_handles: Vec<i32>,
+    ) -> Result<Vec<SubscribeResult>, Error> {
+        ensure_bulk_size("item_handles", item_handles.len())?;
+        let reply = self
+            .invoke(
+                MxCommandKind::RemoveItemBulk,
+                Payload::RemoveItemBulk(RemoveItemBulkCommand {
+                    server_handle,
+                    item_handles,
+                }),
+            )
+            .await?;
+
+        Ok(bulk_results(reply, BulkReplyKind::RemoveItemBulk))
+    }
+
+    pub async fn un_advise_item_bulk(
+        &self,
+        server_handle: i32,
+        item_handles: Vec<i32>,
+    ) -> Result<Vec<SubscribeResult>, Error> {
+        ensure_bulk_size("item_handles", item_handles.len())?;
+        let reply = self
+            .invoke(
+                MxCommandKind::UnAdviseItemBulk,
+                Payload::UnAdviseItemBulk(UnAdviseItemBulkCommand {
+                    server_handle,
+                    item_handles,
+                }),
+            )
+            .await?;
+
+        Ok(bulk_results(reply, BulkReplyKind::UnAdviseItemBulk))
+    }
+
+    pub async fn subscribe_bulk(
+        &self,
+        server_handle: i32,
+        tag_addresses: Vec<String>,
+    ) -> Result<Vec<SubscribeResult>, Error> {
+        ensure_bulk_size("tag_addresses", tag_addresses.len())?;
+        let reply = self
+            .invoke(
+                MxCommandKind::SubscribeBulk,
+                Payload::SubscribeBulk(SubscribeBulkCommand {
+                    server_handle,
+                    tag_addresses,
+                }),
+            )
+            .await?;
+
+        Ok(bulk_results(reply, BulkReplyKind::SubscribeBulk))
+    }
+
+    pub async fn unsubscribe_bulk(
+        &self,
+        server_handle: i32,
+        item_handles: Vec<i32>,
+    ) -> Result<Vec<SubscribeResult>, Error> {
+        ensure_bulk_size("item_handles", item_handles.len())?;
+        let reply = self
+            .invoke(
+                MxCommandKind::UnsubscribeBulk,
+                Payload::UnsubscribeBulk(UnsubscribeBulkCommand {
+                    server_handle,
+                    item_handles,
+                }),
+            )
+            .await?;
+
+        Ok(bulk_results(reply, BulkReplyKind::UnsubscribeBulk))
+    }
+
     pub async fn write(
         &self,
         server_handle: i32,
@@ -193,6 +337,17 @@ impl Session {
     }
 }
 
+fn ensure_bulk_size(name: &'static str, len: usize) -> Result<(), Error> {
+    if len > MAX_BULK_ITEMS {
+        Err(Error::InvalidArgument {
+            name: name.to_owned(),
+            detail: format!("bulk commands are limited to {MAX_BULK_ITEMS} item(s)"),
+        })
+    } else {
+        Ok(())
+    }
+}
+
 fn register_server_handle(reply: &MxCommandReply) -> i32 {
     match reply.payload.as_ref() {
         Some(mx_command_reply::Payload::Register(register)) => register.server_handle,
@@ -226,6 +381,41 @@ fn add_item2_handle(reply: &MxCommandReply) -> i32 {
     }
 }
 
+enum BulkReplyKind {
+    AddItemBulk,
+    AdviseItemBulk,
+    RemoveItemBulk,
+    UnAdviseItemBulk,
+    SubscribeBulk,
+    UnsubscribeBulk,
+}
+
+fn bulk_results(reply: MxCommandReply, kind: BulkReplyKind) -> Vec<SubscribeResult> {
+    match (reply.payload, kind) {
+        (Some(mx_command_reply::Payload::AddItemBulk(reply)), BulkReplyKind::AddItemBulk) => {
+            reply.results
+        }
+        (Some(mx_command_reply::Payload::AdviseItemBulk(reply)), BulkReplyKind::AdviseItemBulk) => {
+            reply.results
+        }
+        (Some(mx_command_reply::Payload::RemoveItemBulk(reply)), BulkReplyKind::RemoveItemBulk) => {
+            reply.results
+        }
+        (
+            Some(mx_command_reply::Payload::UnAdviseItemBulk(reply)),
+            BulkReplyKind::UnAdviseItemBulk,
+        ) => reply.results,
+        (Some(mx_command_reply::Payload::SubscribeBulk(reply)), BulkReplyKind::SubscribeBulk) => {
+            reply.results
+        }
+        (
+            Some(mx_command_reply::Payload::UnsubscribeBulk(reply)),
+            BulkReplyKind::UnsubscribeBulk,
+        ) => reply.results,
+        _ => Vec::new(),
+    }
+}
+
 fn int32_reply_value(value: &ProtoMxValue) -> Option<i32> {
     match value.kind.as_ref()? {
         crate::generated::mxaccess_gateway::v1::mx_value::Kind::Int32Value(value) => Some(*value),

clients/rust/src/version.rs

@@ -1,3 +1,3 @@
 pub const CLIENT_VERSION: &str = "0.1.0-dev";
-pub const GATEWAY_PROTOCOL_VERSION: u32 = 1;
+pub const GATEWAY_PROTOCOL_VERSION: u32 = 2;
 pub const WORKER_PROTOCOL_VERSION: u32 = 1;

clients/rust/tests/client_behavior.rs

@@ -14,10 +14,10 @@ use mxgateway_client::generated::mxaccess_gateway::v1::mx_access_gateway_server:
 use mxgateway_client::generated::mxaccess_gateway::v1::mx_command_reply;
 use mxgateway_client::generated::mxaccess_gateway::v1::mx_value::Kind;
 use mxgateway_client::generated::mxaccess_gateway::v1::{
-    AddItemReply, CloseSessionReply, CloseSessionRequest, MxCommandKind, MxCommandReply,
-    MxDataType, MxEvent, MxEventFamily, MxStatusCategory, MxStatusProxy, MxStatusSource, MxValue,
-    OpenSessionReply, OpenSessionRequest, ProtocolStatus, ProtocolStatusCode, SessionState,
-    StreamEventsRequest,
+    AddItemReply, BulkSubscribeReply, CloseSessionReply, CloseSessionRequest, MxCommandKind,
+    MxCommandReply, MxDataType, MxEvent, MxEventFamily, MxStatusCategory, MxStatusProxy,
+    MxStatusSource, MxValue, OpenSessionReply, OpenSessionRequest, ProtocolStatus,
+    ProtocolStatusCode, SessionState, StreamEventsRequest, SubscribeResult,
 };
 use mxgateway_client::{
     ApiKey, ClientOptions, CommandError, Error, GatewayClient, MxStatus, MxValue as ClientMxValue,
@@ -87,6 +87,25 @@ async fn session_helpers_build_commands_and_preserve_command_errors() {
     assert_eq!(error.reply().statuses.len(), 2);
 }
 
+#[tokio::test]
+async fn subscribe_bulk_builds_one_bulk_command_and_returns_results() {
+    let state = Arc::new(FakeState::default());
+    let endpoint = spawn_fake_gateway(state.clone()).await;
+    let client = GatewayClient::connect(ClientOptions::new(endpoint))
+        .await
+        .unwrap();
+    let session = client.session("session-fixture");
+
+    let results = session
+        .subscribe_bulk(12, vec!["Area001.Pump001.Speed".to_owned()])
+        .await
+        .unwrap();
+
+    assert_eq!(results[0].item_handle, 34);
+    let last_command = state.last_command_kind.lock().await;
+    assert_eq!(*last_command, Some(MxCommandKind::SubscribeBulk as i32));
+}
+
 #[tokio::test]
 async fn event_stream_preserves_order_and_drop_cancels_server_stream() {
     let state = Arc::new(FakeState::default());
@@ -268,6 +287,27 @@ impl MxAccessGateway for FakeGateway {
             return Ok(Response::new(mxaccess_failure_reply()));
         }
 
+        if kind == MxCommandKind::SubscribeBulk as i32 {
+            return Ok(Response::new(MxCommandReply {
+                session_id: request.session_id,
+                correlation_id: "fake-correlation".to_owned(),
+                kind,
+                protocol_status: Some(ok_status("command ok")),
+                payload: Some(mx_command_reply::Payload::SubscribeBulk(
+                    BulkSubscribeReply {
+                        results: vec![SubscribeResult {
+                            server_handle: 12,
+                            tag_address: "Area001.Pump001.Speed".to_owned(),
+                            item_handle: 34,
+                            was_successful: true,
+                            error_message: String::new(),
+                        }],
+                    },
+                )),
+                ..MxCommandReply::default()
+            }));
+        }
+
         Ok(Response::new(MxCommandReply {
             session_id: request.session_id,
             correlation_id: "fake-correlation".to_owned(),

docs/Authentication.md

@@ -0,0 +1,279 @@
+# Gateway Authentication
+
+The gateway authentication subsystem verifies inbound API key credentials against a SQLite-backed key store, hashes secrets with a configurable pepper, and records administrative and verification events to an audit trail.
+
+## Token Format
+
+API keys travel in the HTTP `Authorization` header as a bearer token shaped `mxgw_<keyId>_<secret>`. The `mxgw_` prefix scopes parsing to gateway tokens, the `<keyId>` segment is the public identifier used for lookup, and `<secret>` is the high-entropy portion that the gateway verifies against a stored hash.
+
+`ApiKeyParser` enforces the format and rejects malformed tokens before any database round-trip:
+
+```csharp
+public bool TryParseAuthorizationHeader(string? authorizationHeader, out ParsedApiKey? apiKey)
+{
+    apiKey = null;
+
+    if (string.IsNullOrWhiteSpace(authorizationHeader)
+        || !authorizationHeader.StartsWith(BearerPrefix, StringComparison.OrdinalIgnoreCase))
+    {
+        return false;
+    }
+
+    string token = authorizationHeader[BearerPrefix.Length..].Trim();
+
+    if (!token.StartsWith(TokenPrefix, StringComparison.OrdinalIgnoreCase))
+    {
+        return false;
+    }
+```
+
+A successful parse produces a `ParsedApiKey(KeyId, Secret)` record. The `IApiKeyParser` interface exists so verification consumers can be tested without depending on header-format details.
+
+## Parsing and Secrets
+
+### Secret generation
+
+`ApiKeySecretGenerator.Generate()` is the single source of new secret material. It uses 32 bytes from `RandomNumberGenerator.Fill` and encodes with URL-safe base64 (no padding) so secrets can be embedded in headers without escaping:
+
+```csharp
+public static string Generate()
+{
+    Span<byte> bytes = stackalloc byte[32];
+    RandomNumberGenerator.Fill(bytes);
+
+    return Convert.ToBase64String(bytes)
+        .TrimEnd('=')
+        .Replace('+', '-')
+        .Replace('/', '_');
+}
+```
+
+### Peppered hashing
+
+`ApiKeySecretHasher` (registered behind `IApiKeySecretHasher`) hashes secrets with `HMACSHA256` keyed by a server-side pepper. The pepper lives outside the database and is resolved by `IConfiguration` lookup against the configured `PepperSecretName`:
+
+```csharp
+public byte[] HashSecret(string secret)
+{
+    string pepper = GetPepper();
+    byte[] pepperBytes = Encoding.UTF8.GetBytes(pepper);
+    byte[] secretBytes = Encoding.UTF8.GetBytes(secret);
+
+    using HMACSHA256 hmac = new(pepperBytes);
+
+    return hmac.ComputeHash(secretBytes);
+}
+```
+
+The pepper is intentionally not stored alongside the hash: an attacker who exfiltrates only the SQLite file holds the hashes but lacks the keying material to brute-force candidate secrets, even if the stored hash algorithm and salt scheme are known. If the pepper is missing the hasher throws `ApiKeyPepperUnavailableException`, which the verifier converts to a distinct failure code rather than treating it as a credential mismatch.
+
+## Verification
+
+`ApiKeyVerifier` (`IApiKeyVerifier`) implements the verification flow:
+
+1. Parse the `Authorization` header into a `ParsedApiKey`.
+2. Look up the `ApiKeyRecord` by `KeyId` through `IApiKeyStore.FindByKeyIdAsync`.
+3. Reject revoked records (`RevokedUtc is not null`).
+4. Hash the presented secret with the configured pepper.
+5. Compare hashes with `CryptographicOperations.FixedTimeEquals` to avoid timing oracles.
+6. Record a `LastUsedUtc` timestamp via `MarkKeyUsedAsync` and return an `ApiKeyIdentity`.
+
+```csharp
+if (!CryptographicOperations.FixedTimeEquals(presentedHash, storedKey.SecretHash))
+{
+    return ApiKeyVerificationResult.Fail(ApiKeyVerificationFailure.SecretMismatch);
+}
+
+await keyStore.MarkKeyUsedAsync(storedKey.KeyId, DateTimeOffset.UtcNow, cancellationToken)
+    .ConfigureAwait(false);
+
+return ApiKeyVerificationResult.Success(new ApiKeyIdentity(
+    KeyId: storedKey.KeyId,
+    KeyPrefix: storedKey.KeyPrefix,
+    DisplayName: storedKey.DisplayName,
+    Scopes: storedKey.Scopes,
+    Constraints: storedKey.Constraints));
+```
+
+`ApiKeyVerificationResult` carries either an `ApiKeyIdentity` or a discriminated `ApiKeyVerificationFailure` value. The failure enum distinguishes parse errors, missing pepper, missing or revoked keys, and secret mismatch so the calling middleware can emit precise audit detail without leaking which check failed to the client.
+
+`ApiKeyIdentity` exposes only non-secret fields (`KeyId`, `KeyPrefix`,
+`DisplayName`, `Scopes`, and `Constraints`) and is the type downstream
+authorization code consumes.
+
+## Storage
+
+The gateway keeps API key state in a dedicated SQLite database. SQLite is sufficient because credential volume is small, the gateway runs as a single process, and the file is straightforward to back up and rotate independently of the main application data.
+
+### Connection factory
+
+`AuthSqliteConnectionFactory` reads `GatewayOptions.Authentication.SqlitePath`, ensures the parent directory exists, and opens the connection in `ReadWriteCreate` mode so first-run installations can create the file without manual provisioning:
+
+```csharp
+public SqliteConnection CreateConnection()
+{
+    string sqlitePath = options.Value.Authentication.SqlitePath;
+    string? directory = Path.GetDirectoryName(sqlitePath);
+
+    if (!string.IsNullOrWhiteSpace(directory))
+    {
+        Directory.CreateDirectory(directory);
+    }
+
+    SqliteConnectionStringBuilder builder = new()
+    {
+        DataSource = sqlitePath,
+        Mode = SqliteOpenMode.ReadWriteCreate
+    };
+
+    return new SqliteConnection(builder.ToString());
+}
+```
+
+### Schema
+
+`SqliteAuthSchema` declares table names and the current schema version as constants. Three tables are involved:
+
+- `api_keys` stores `key_id`, `key_prefix`, the `secret_hash` blob,
+  `display_name`, serialized `scopes`, optional serialized `constraints`, and
+  the `created_utc`, `last_used_utc`, and `revoked_utc` timestamps.
+- `api_key_audit` is an append-only log keyed by an autoincrement `audit_id` with `key_id`, `event_type`, `remote_address`, `created_utc`, and `details` columns.
+- `schema_version` carries a single row whose `version` column is matched against `SqliteAuthSchema.CurrentVersion`.
+
+### Read paths
+
+`SqliteApiKeyStore` (`IApiKeyStore`) handles the two reads needed at request time: `FindByKeyIdAsync` returns any record (so revoked keys can be reported distinctly) and `FindActiveByKeyIdAsync` filters to non-revoked rows. `MarkKeyUsedAsync` updates `last_used_utc` only for non-revoked rows so a freshly revoked key cannot have its timestamp refreshed by a racing verification.
+
+`ApiKeyRecord` is the in-memory projection. `ApiKeyRecordReader.Read` is shared by every read path so column ordering is defined in one place:
+
+```csharp
+public static ApiKeyRecord Read(SqliteDataReader reader)
+{
+    return new ApiKeyRecord(
+        KeyId: reader.GetString(0),
+        KeyPrefix: reader.GetString(1),
+        SecretHash: (byte[])reader["secret_hash"],
+        DisplayName: reader.GetString(3),
+        Scopes: ApiKeyScopeSerializer.Deserialize(reader.GetString(4)),
+        Constraints: ApiKeyConstraintSerializer.Deserialize(reader.IsDBNull(5) ? null : reader.GetString(5)),
+        CreatedUtc: DateTimeOffset.Parse(reader.GetString(6), System.Globalization.CultureInfo.InvariantCulture),
+        LastUsedUtc: ReadNullableDateTimeOffset(reader, 7),
+        RevokedUtc: ReadNullableDateTimeOffset(reader, 8));
+}
+```
+
+### Write paths
+
+`SqliteApiKeyAdminStore` (`IApiKeyAdminStore`) implements administrative mutations: `CreateAsync` accepts an `ApiKeyCreateRequest`, `RevokeAsync` sets `revoked_utc` only when not already revoked, and `RotateAsync` replaces `secret_hash`, clears `last_used_utc`, and clears `revoked_utc` so a rotated key is immediately usable.
+
+### Audit trail
+
+`SqliteApiKeyAuditStore` (`IApiKeyAuditStore`) appends `ApiKeyAuditEntry` values to the `api_key_audit` table and stamps each row with a UTC timestamp inside the store rather than trusting the caller. `ListRecentAsync` returns the most recent rows ordered by `audit_id` descending and projects them into `ApiKeyAuditRecord`. Rows are kept even after the referenced key is revoked because the audit history is the durable record of administrative action; the `key_id` column is nullable to accommodate non-key-scoped events such as `init-db`.
+
+## Migration
+
+Schema bring-up is centralised behind `IAuthStoreMigrator`. `SqliteAuthStoreMigrator` executes the migration inside a single transaction so a partial failure leaves the database untouched, refuses to start when the on-disk schema version is newer than the binary supports, and idempotently creates the v1 schema:
+
+```csharp
+if (existingVersion > SqliteAuthSchema.CurrentVersion)
+{
+    throw new AuthStoreMigrationException(
+        $"Auth database schema version {existingVersion} is newer than supported version {SqliteAuthSchema.CurrentVersion}.");
+}
+
+await ApplyVersionOneAsync(connection, transaction, cancellationToken).ConfigureAwait(false);
+
+await transaction.CommitAsync(cancellationToken).ConfigureAwait(false);
+```
+
+`AuthStoreMigrationHostedService` runs the migrator at startup, but only when API-key authentication is enabled and `RunMigrationsOnStartup` is true. Operators who manage schema out-of-band can disable the hosted run and use the admin CLI's `init-db` command instead.
+
+`AuthStoreMigrationException` is a sealed `InvalidOperationException` so it can be caught precisely without swallowing unrelated failures.
+
+## Admin CLI
+
+`ApiKeyAdminCommandLineParser.Parse` recognises a leading `apikey` argument and dispatches to one of the subcommands declared by `ApiKeyAdminCommandKind`. Each parsed invocation produces an `ApiKeyAdminCommand` (or an `ApiKeyAdminParseResult` carrying an error). `ApiKeyAdminCliRunner` then executes the command, runs the migrator first, calls the relevant store method, appends an audit row, and writes either text or JSON output via `ApiKeyAdminOutput`. The returned `ApiKeyAdminListedKey` projection deliberately omits the `secret_hash` so listing a database does not surface hash material.
+
+The supported subcommands match `ApiKeyAdminCommandKind` exactly:
+
+| Subcommand | Required options | Behaviour |
+|------------|------------------|-----------|
+| `init-db` | none | Runs the migrator and records an audit entry. |
+| `create-key` | `--key-id`, `--display-name` | Generates a new secret, stores its peppered hash and optional constraints, and prints the assembled `mxgw_<keyId>_<secret>` token. |
+| `list-keys` | none | Lists every stored key with its scopes, constraints, and revocation state. |
+| `revoke-key` | `--key-id` | Sets `revoked_utc` if the key is currently active. |
+| `rotate-key` | `--key-id` | Replaces the secret hash and prints the new token. |
+
+Examples:
+
+```bash
+mxgateway apikey init-db
+mxgateway apikey create-key --key-id ops.alice --display-name "Alice (ops)" --scopes read,write
+mxgateway apikey create-key --key-id area1.reader --display-name "Area 1 reader" --scopes invoke:read,metadata:read --read-subtree "Area1/*" --browse-subtree "Area1/*"
+mxgateway apikey list-keys --json
+mxgateway apikey revoke-key --key-id ops.alice
+mxgateway apikey rotate-key --key-id ops.alice
+```
+
+Constraint flags are optional. `--read-subtree`, `--write-subtree`,
+`--read-tag-glob`, `--write-tag-glob`, and `--browse-subtree` are repeatable.
+`--max-write-classification` accepts one integer. `--read-alarm-only` and
+`--read-historized-only` are boolean flags. Existing rows with null
+constraints remain fully unconstrained after migration.
+
+Key ids are restricted by the parser to ASCII letters, digits, periods, and hyphens so they remain safe to embed in the token format and in URL paths used by administrative tooling.
+
+## Scope Serialization
+
+Scopes are persisted as a single TEXT column rather than a join table because the set is small, never queried by membership at the database level, and changes atomically with the owning row. `ApiKeyScopeSerializer.Serialize` writes a JSON array sorted with `StringComparer.Ordinal` so equivalent scope sets produce byte-identical column values, which makes audit diffing and database comparisons deterministic:
+
+```csharp
+public static string Serialize(IReadOnlySet<string> scopes)
+{
+    return JsonSerializer.Serialize(scopes.Order(StringComparer.Ordinal));
+}
+
+public static IReadOnlySet<string> Deserialize(string value)
+{
+    if (string.IsNullOrWhiteSpace(value))
+    {
+        return new HashSet<string>(StringComparer.Ordinal);
+    }
+
+    string[]? scopes = JsonSerializer.Deserialize<string[]>(value);
+
+    return new HashSet<string>(scopes ?? [], StringComparer.Ordinal);
+}
+```
+
+`Deserialize` tolerates an empty column by returning an empty set so older rows or hand-edited records do not crash the verifier.
+
+## Registration
+
+`AuthStoreServiceCollectionExtensions.AddSqliteAuthStore` wires every service in this subsystem as a singleton and registers the migration hosted service:
+
+```csharp
+public static IServiceCollection AddSqliteAuthStore(this IServiceCollection services)
+{
+    services.AddSingleton<IApiKeyParser, ApiKeyParser>();
+    services.AddSingleton<IApiKeySecretHasher, ApiKeySecretHasher>();
+    services.AddSingleton<IApiKeyVerifier, ApiKeyVerifier>();
+    services.AddSingleton<ApiKeyAdminCliRunner>();
+    services.AddSingleton<AuthSqliteConnectionFactory>();
+    services.AddSingleton<IAuthStoreMigrator, SqliteAuthStoreMigrator>();
+    services.AddSingleton<IApiKeyStore, SqliteApiKeyStore>();
+    services.AddSingleton<IApiKeyAdminStore, SqliteApiKeyAdminStore>();
+    services.AddSingleton<IApiKeyAuditStore, SqliteApiKeyAuditStore>();
+    services.AddHostedService<AuthStoreMigrationHostedService>();
+
+    return services;
+}
+```
+
+Singletons are safe because each operation opens its own short-lived `SqliteConnection` through the factory; there is no shared mutable state inside the services.
+
+## Related Documentation
+
+- [Gateway Configuration](./GatewayConfiguration.md)
+- [Authorization](./Authorization.md)
+- [Diagnostics](./Diagnostics.md)

docs/Authorization.md

@@ -0,0 +1,257 @@
+# Gateway gRPC Authorization
+
+The authorization subsystem has two layers. The gRPC interceptor enforces the
+verb scope required by the RPC. Service-layer constraint checks then narrow
+what an authenticated API key can browse, read, or write inside the Galaxy.
+
+## Overview
+
+Authorization runs as a single gRPC server interceptor registered for every call on the gateway. It pulls the authenticated identity for the current request, derives the scope that the request type requires, and either lets the call continue or fails the call with a gRPC status. The pipeline keeps service classes free of cross-cutting checks, which matches the AGENTS.md "thin gRPC layer" rule that service handlers translate between contracts and domain code without owning policy.
+
+The participating types live under `src/MxGateway.Server/Security/Authorization/`:
+
+- `GatewayGrpcAuthorizationInterceptor` runs the authenticate-then-authorize pipeline for unary and server-streaming calls.
+- `GatewayGrpcScopeResolver` maps a request message (and, for `MxCommandRequest`, the inner `MxCommandKind`) to the scope string that must be present on the caller.
+- `GatewayScopes` exposes the canonical scope constants used by the resolver and any downstream consumer.
+- `GatewayRequestIdentityAccessor` and `IGatewayRequestIdentityAccessor` expose the verified identity to handlers and any service code that runs inside the call.
+- `IConstraintEnforcer` applies optional API-key constraints against the
+  cached Galaxy hierarchy from service bodies.
+- `GrpcAuthorizationServiceCollectionExtensions` wires the components into the DI container and the gRPC pipeline.
+
+The `ApiKeyIdentity` consumed here is produced by the authentication layer; see [Authentication](./Authentication.md) for how it is built and how scopes are persisted.
+
+## Why an Interceptor
+
+Centralizing the policy in `GatewayGrpcAuthorizationInterceptor` produces three concrete benefits:
+
+1. Every RPC defined in `MxAccessGatewayService` is covered by construction. A new RPC inherits the check the moment its request type is added to `GatewayGrpcScopeResolver`, instead of relying on each service method to remember to call an authorization helper.
+2. Verb-scope policy stays centralized. Request-specific constraints still run
+   in service bodies because they need command payloads, item handles, and
+   Galaxy metadata that the interceptor should not inspect.
+3. Authentication and authorization happen in one place, so the gRPC `Status` mapping is consistent. A failed key check always returns `Unauthenticated`, and a missing scope always returns `PermissionDenied` with the offending scope name.
+
+## Interceptor Flow
+
+`GatewayGrpcAuthorizationInterceptor` overrides both `UnaryServerHandler` and `ServerStreamingServerHandler`. Both call the same private `AuthenticateAndAuthorizeAsync` helper before invoking the continuation, then push the resolved identity onto the accessor for the duration of the call.
+
+```csharp
+public override async Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
+    TRequest request,
+    ServerCallContext context,
+    UnaryServerMethod<TRequest, TResponse> continuation)
+{
+    ApiKeyIdentity? identity = await AuthenticateAndAuthorizeAsync(request, context).ConfigureAwait(false);
+    IDisposable? identityScope = identity is null ? null : identityAccessor.Push(identity);
+    using (identityScope)
+    {
+        return await continuation(request, context).ConfigureAwait(false);
+    }
+}
+```
+
+The shared helper performs the actual decision:
+
+```csharp
+if (options.Value.Authentication.Mode == AuthenticationMode.Disabled)
+{
+    return null;
+}
+
+string? authorizationHeader = context.RequestHeaders.GetValue("authorization");
+ApiKeyVerificationResult verificationResult = await apiKeyVerifier
+    .VerifyAsync(authorizationHeader, context.CancellationToken)
+    .ConfigureAwait(false);
+
+if (!verificationResult.Succeeded || verificationResult.Identity is null)
+{
+    throw new RpcException(new Status(
+        StatusCode.Unauthenticated,
+        "Missing or invalid API key."));
+}
+
+string requiredScope = scopeResolver.ResolveRequiredScope(request);
+if (!verificationResult.Identity.Scopes.Contains(requiredScope))
+{
+    throw new RpcException(new Status(
+        StatusCode.PermissionDenied,
+        $"API key is missing required scope '{requiredScope}'."));
+}
+
+return verificationResult.Identity;
+```
+
+The flow is:
+
+1. If `GatewayOptions.Authentication.Mode` is `AuthenticationMode.Disabled`, the helper returns `null` immediately. No identity is pushed onto the accessor and the continuation runs without scope enforcement. This matches the `AuthenticationMode` enum, which only defines `ApiKey` and `Disabled`.
+2. Otherwise, the `authorization` request header is read directly off `ServerCallContext.RequestHeaders` and handed to `IApiKeyVerifier.VerifyAsync`. A failed verification or a missing identity throws `RpcException` with `StatusCode.Unauthenticated`.
+3. `GatewayGrpcScopeResolver.ResolveRequiredScope(request)` produces the scope string. If the identity's `Scopes` set does not contain it, the helper throws `RpcException` with `StatusCode.PermissionDenied` and embeds the missing scope name in `Status.Detail` so callers can diagnose the failure.
+4. On success, the verified `ApiKeyIdentity` is returned and pushed onto `IGatewayRequestIdentityAccessor` for the lifetime of the call.
+
+The status codes are deliberately distinct: `Unauthenticated` signals "we do not know who you are," and `PermissionDenied` signals "we know who you are, but you cannot do this." Treating the two as the same code would make troubleshooting harder for client implementations.
+
+## Scope Resolution
+
+`GatewayGrpcScopeResolver` is a stateless singleton that switches on the runtime request type. Top-level RPC requests map directly:
+
+```csharp
+public string ResolveRequiredScope(object request)
+{
+    return request switch
+    {
+        OpenSessionRequest => GatewayScopes.SessionOpen,
+        CloseSessionRequest => GatewayScopes.SessionClose,
+        StreamEventsRequest => GatewayScopes.EventsRead,
+        MxCommandRequest commandRequest => ResolveCommandScope(commandRequest.Command?.Kind ?? MxCommandKind.Unspecified),
+        _ => GatewayScopes.Admin
+    };
+}
+```
+
+The `_ => GatewayScopes.Admin` fallback is intentional: any future request type that the resolver does not recognize fails closed, requiring the strongest scope until the resolver is updated.
+
+`MxCommandRequest` is special because it multiplexes many MxAccess operations through a single RPC. The resolver inspects the embedded `MxCommandKind` so each operation gets its own scope:
+
+```csharp
+private static string ResolveCommandScope(MxCommandKind kind)
+{
+    return kind switch
+    {
+        MxCommandKind.Write or
+        MxCommandKind.Write2 => GatewayScopes.InvokeWrite,
+
+        MxCommandKind.WriteSecured or
+        MxCommandKind.WriteSecured2 or
+        MxCommandKind.AuthenticateUser => GatewayScopes.InvokeSecure,
+
+        MxCommandKind.ArchestraUserToId or
+        MxCommandKind.GetSessionState or
+        MxCommandKind.GetWorkerInfo => GatewayScopes.MetadataRead,
+
+        MxCommandKind.DrainEvents => GatewayScopes.EventsRead,
+        MxCommandKind.ShutdownWorker => GatewayScopes.Admin,
+
+        _ => GatewayScopes.InvokeRead
+    };
+}
+```
+
+Reads (`Register`, `AddItem`, `Advise`, and any other unspecified kind) fall through to `InvokeRead`, which keeps the matrix small while still separating reads from writes, secured writes, metadata lookups, event drains, and worker shutdown.
+
+## Constraint Enforcement
+
+`ApiKeyIdentity.Constraints` is optional. Empty constraints preserve the
+previous behavior: the key is authorized only by its verb scopes. Non-empty
+constraints are stored as JSON in `api_keys.constraints` and are applied by
+`IConstraintEnforcer` after the interceptor succeeds.
+
+Supported constraints are:
+
+| Constraint | Meaning |
+|------------|---------|
+| `read_subtrees` | Contained-path globs allowed for read/subscription commands. |
+| `write_subtrees` | Contained-path globs allowed for write commands. |
+| `read_tag_globs` | Tag-address globs allowed for read/subscription commands. |
+| `write_tag_globs` | Tag-address globs allowed for write commands. |
+| `max_write_classification` | Maximum Galaxy attribute `security_classification` a key may write. |
+| `browse_subtrees` | Contained-path globs used to filter Galaxy browse results and deploy-event counts. |
+| `read_alarm_only` | Read/subscription commands must target objects with alarm-bearing attributes. |
+| `read_historized_only` | Read/subscription commands must target objects with historized attributes. |
+
+Glob matching is anchored, case-insensitive, and supports `*` and `?`.
+Subtree and tag glob lists are alternatives: matching either list allows that
+scope dimension. Empty lists mean unconstrained for that dimension.
+
+The service checks read constraints for `AddItem`, `AddItem2`, `AddItemBulk`,
+`SubscribeBulk`, and `AdviseItemBulk`. It checks write constraints for
+`Write`, `Write2`, `WriteSecured`, and `WriteSecured2`. Successful item
+registrations are tracked per session so later item-handle commands resolve
+back to the original tag address. If a constrained key presents an unknown item
+handle, the gateway fails closed.
+
+Non-bulk constraint failures return gRPC `PermissionDenied`. Bulk read
+commands preserve input order and return a failed `SubscribeResult` for each
+denied item while still forwarding allowed items to the worker. Every denial
+adds an `api_key_audit` entry with the key id, command kind, target, and
+blocking constraint; secured values and raw credentials are never logged.
+
+## Scope Catalog
+
+`GatewayScopes` is the single source of truth for scope strings. Every entry is currently mapped by either the resolver or another security component:
+
+| Constant | Value | Required For |
+|----------|-------|--------------|
+| `SessionOpen` | `session:open` | `OpenSessionRequest` |
+| `SessionClose` | `session:close` | `CloseSessionRequest` |
+| `EventsRead` | `events:read` | `StreamEventsRequest`, `MxCommandKind.DrainEvents` |
+| `InvokeRead` | `invoke:read` | `MxCommandRequest` for read-style command kinds (`Register`, `AddItem`, `Advise`, and any kind not otherwise mapped) |
+| `InvokeWrite` | `invoke:write` | `MxCommandKind.Write`, `MxCommandKind.Write2` |
+| `InvokeSecure` | `invoke:secure` | `MxCommandKind.WriteSecured`, `MxCommandKind.WriteSecured2`, `MxCommandKind.AuthenticateUser` |
+| `MetadataRead` | `metadata:read` | `MxCommandKind.ArchestraUserToId`, `MxCommandKind.GetSessionState`, `MxCommandKind.GetWorkerInfo`, `GalaxyRepository.TestConnection`, `GalaxyRepository.GetLastDeployTime`, `GalaxyRepository.DiscoverHierarchy`, `GalaxyRepository.WatchDeployEvents` |
+| `Admin` | `admin` | `MxCommandKind.ShutdownWorker`, the default for any unrecognized request type, and the dashboard authorization policy |
+
+The `Admin` constant is also referenced by `DashboardAuthenticator` and `DashboardAuthorizationHandler` so that the dashboard and the gRPC layer agree on what "admin" means.
+
+## Identity Access for Downstream Layers
+
+Once authorization passes, `GatewayGrpcAuthorizationInterceptor` calls `identityAccessor.Push(identity)` and disposes the returned scope when the continuation completes. `GatewayRequestIdentityAccessor` stores the active identity in an `AsyncLocal<ApiKeyIdentity?>`, so the value flows across `await` boundaries and child tasks belonging to the same request.
+
+```csharp
+public sealed class GatewayRequestIdentityAccessor : IGatewayRequestIdentityAccessor
+{
+    private readonly AsyncLocal<ApiKeyIdentity?> currentIdentity = new();
+
+    public ApiKeyIdentity? Current => currentIdentity.Value;
+
+    public IDisposable Push(ApiKeyIdentity identity)
+    {
+        ArgumentNullException.ThrowIfNull(identity);
+
+        ApiKeyIdentity? previousIdentity = currentIdentity.Value;
+        currentIdentity.Value = identity;
+
+        return new IdentityScope(this, previousIdentity);
+    }
+}
+```
+
+The returned `IdentityScope` restores the previous value on dispose rather than clearing it. This makes the accessor safe for nested pushes, even though the current interceptor only pushes once per call. Disposing twice is a no-op because of the `disposed` guard inside `IdentityScope`.
+
+Downstream code consumes the accessor through the `IGatewayRequestIdentityAccessor` interface:
+
+```csharp
+public interface IGatewayRequestIdentityAccessor
+{
+    ApiKeyIdentity? Current { get; }
+
+    IDisposable Push(ApiKeyIdentity identity);
+}
+```
+
+`MxAccessGatewayService` takes `IGatewayRequestIdentityAccessor` as a constructor dependency and reads `Current` whenever it needs to attach the calling identity to a domain operation, which keeps the service free of header parsing or scope checks.
+
+When `AuthenticationMode.Disabled` is configured, no identity is pushed, so `Current` returns `null`. Downstream code must tolerate that, just as it tolerates the absence of a scope check.
+
+## Registration
+
+`GrpcAuthorizationServiceCollectionExtensions.AddGatewayGrpcAuthorization` is the single entry point that registers every component and inserts the interceptor into the gRPC pipeline:
+
+```csharp
+public static IServiceCollection AddGatewayGrpcAuthorization(this IServiceCollection services)
+{
+    services.AddSingleton<GatewayGrpcScopeResolver>();
+    services.AddSingleton<IGatewayRequestIdentityAccessor, GatewayRequestIdentityAccessor>();
+    services.AddSingleton<GatewayGrpcAuthorizationInterceptor>();
+    services.AddGrpc(options => options.Interceptors.Add<GatewayGrpcAuthorizationInterceptor>());
+
+    return services;
+}
+```
+
+Singleton lifetimes are appropriate because none of the three classes hold per-request state on instance fields; the request-scoped value lives inside the `AsyncLocal` on `GatewayRequestIdentityAccessor`. `GatewayApplication` calls `builder.Services.AddGatewayGrpcAuthorization()` during startup, and the call also performs `AddGrpc`, so the gateway never registers gRPC without the interceptor attached.
+
+## Related Documentation
+
+- [Authentication](./Authentication.md)
+- [Grpc](./Grpc.md)
+- [GatewayConfiguration](./GatewayConfiguration.md)
+- [Galaxy Repository Browse](./GalaxyRepository.md)

docs/ClientPackaging.md

@@ -0,0 +1,260 @@
+# Client Packaging
+
+This document defines the clean-checkout commands for building, packaging, and
+running the official MXAccess Gateway clients. Use the tool paths and versions
+in [Toolchain Links](./toolchain-links.md) when a command is missing from
+`PATH`.
+
+## Shared Inputs
+
+All clients generate bindings from the shared protobuf files under
+`src/MxGateway.Contracts/Protos`. Regenerate the published client descriptor
+after changing either `.proto` file or `clients/proto/proto-inputs.json`:
+
+```powershell
+scripts/publish-client-proto-inputs.ps1
+scripts/publish-client-proto-inputs.ps1 -Check
+```
+
+Generated protobuf and gRPC files are generator output. Do not edit them by
+hand.
+
+## Environment
+
+The examples use these common variables:
+
+```powershell
+$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
+$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
+$env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
+```
+
+Use plaintext only for a local gateway. Use TLS when the gateway crosses a
+machine boundary or uses a production certificate.
+
+## .NET
+
+The .NET client uses .NET 10 and references
+`src/MxGateway.Contracts/MxGateway.Contracts.csproj` for generated C# contract
+types. `clients/dotnet/generated` remains reserved for client-local generator
+output if the client later decouples from the contracts project.
+
+Regenerate the generated C# contract types:
+
+```powershell
+dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj
+```
+
+Build and test from the repository root:
+
+```powershell
+dotnet build clients/dotnet/MxGateway.Client.sln
+dotnet test clients/dotnet/MxGateway.Client.sln --no-build
+```
+
+Create local package artifacts:
+
+```powershell
+$dotnetPackageOutput = Join-Path (Get-Location) 'artifacts/clients/dotnet'
+dotnet pack clients/dotnet/MxGateway.Client/MxGateway.Client.csproj -c Release -p:PackageOutputPath="$dotnetPackageOutput"
+dotnet publish clients/dotnet/MxGateway.Client.Cli/MxGateway.Client.Cli.csproj -c Release -o artifacts/clients/dotnet/mxgw-dotnet
+```
+
+Run the CLI from source:
+
+```powershell
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- version --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint "http://$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 "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 $env:MXGATEWAY_TEST_ITEM --json
+```
+
+## Go
+
+The Go client is the module
+`gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go`.
+Generated Go files live under `clients/go/internal/generated`.
+
+Regenerate the Go bindings:
+
+```powershell
+Push-Location clients/go
+./generate-proto.ps1
+Pop-Location
+```
+
+Build and test from `clients/go`:
+
+```powershell
+Push-Location clients/go
+go test ./...
+go build ./...
+go vet ./...
+Pop-Location
+```
+
+Create a local CLI executable:
+
+```powershell
+Push-Location clients/go
+New-Item -ItemType Directory -Force ../../artifacts/clients/go | Out-Null
+go build -o ../../artifacts/clients/go/mxgw-go.exe ./cmd/mxgw-go
+Pop-Location
+```
+
+Run the CLI from source:
+
+```powershell
+Push-Location clients/go
+go run ./cmd/mxgw-go version -json
+go run ./cmd/mxgw-go smoke -endpoint $env:MXGATEWAY_ENDPOINT -plaintext -api-key-env MXGATEWAY_API_KEY -item $env:MXGATEWAY_TEST_ITEM -json
+go run ./cmd/mxgw-go smoke -endpoint mxgateway.example.local:5001 -ca-cert C:\certs\mxgateway-ca.pem -server-name-override mxgateway.example.local -api-key-env MXGATEWAY_API_KEY -item $env:MXGATEWAY_TEST_ITEM -json
+Pop-Location
+```
+
+## Rust
+
+The Rust workspace builds the `mxgateway-client` library crate and the `mxgw`
+CLI crate. `build.rs` generates `tonic` and `prost` modules into Cargo build
+output on each build that needs updated protobuf output.
+
+Regenerate and compile Rust bindings:
+
+```powershell
+Push-Location clients/rust
+cargo check --workspace
+Pop-Location
+```
+
+Build and test from `clients/rust`:
+
+```powershell
+Push-Location clients/rust
+cargo fmt --all --check
+cargo test --workspace
+cargo check --workspace
+Pop-Location
+```
+
+Create local release artifacts:
+
+```powershell
+Push-Location clients/rust
+cargo build --workspace --release
+cargo install --path crates/mxgw-cli --locked --force
+Pop-Location
+```
+
+Run the CLI from source:
+
+```powershell
+Push-Location clients/rust
+cargo run -p mxgw-cli -- version --json
+cargo run -p mxgw-cli -- smoke --endpoint "http://127.0.0.1:5000" --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+cargo run -p mxgw-cli -- smoke --endpoint "https://mxgateway.example.local:5001" --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+Pop-Location
+```
+
+## Python
+
+The Python package is `mxaccess-gateway-client`. Generated modules live under
+`clients/python/src/mxgateway/generated`.
+
+Regenerate the Python bindings:
+
+```powershell
+Push-Location clients/python
+./generate-proto.ps1
+Pop-Location
+```
+
+Install, test, and build a wheel from `clients/python`:
+
+```powershell
+Push-Location clients/python
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m pip wheel . --no-deps --wheel-dir "$env:TEMP\mxgateway-python-wheel"
+Pop-Location
+```
+
+Run the CLI from the editable install or with `python -m`:
+
+```powershell
+Push-Location clients/python
+mxgw-py version --json
+mxgw-py smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+mxgw-py smoke --endpoint mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+python -m mxgateway_cli version --json
+Pop-Location
+```
+
+## Java
+
+The Java workspace uses Gradle, Java 21, `mxgateway-client`, and
+`mxgateway-cli`. The Gradle protobuf plugin writes generated Java protobuf and
+gRPC sources under `clients/java/src/main/generated`.
+
+Regenerate Java bindings:
+
+```powershell
+Push-Location clients/java
+gradle :mxgateway-client:generateProto
+Pop-Location
+```
+
+Build and test from `clients/java`:
+
+```powershell
+Push-Location clients/java
+gradle test
+Pop-Location
+```
+
+Create local library and CLI artifacts:
+
+```powershell
+Push-Location clients/java
+gradle :mxgateway-client:jar :mxgateway-cli:installDist
+Pop-Location
+```
+
+Run the CLI through Gradle:
+
+```powershell
+Push-Location clients/java
+gradle :mxgateway-cli:run --args="version --json"
+gradle :mxgateway-cli:run --args="smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json"
+gradle :mxgateway-cli:run --args="smoke --endpoint mxgateway.example.local:5001 --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json"
+Pop-Location
+```
+
+## Integration Tests
+
+Client integration checks are opt-in because they need a live gateway and a
+gateway host that can create MXAccess worker sessions. Set the common
+environment before running a client smoke:
+
+```powershell
+$env:MXGATEWAY_INTEGRATION = '1'
+$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
+$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
+$env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
+$env:MXGATEWAY_TEST_CONTEXT = ''
+$env:MXGATEWAY_TEST_WRITE_VALUE = '123'
+```
+
+Run the bounded `smoke` command for each client against the same item. The
+smoke commands open a session, register a client name, add one item, advise it,
+and close the session. The .NET and Python smoke commands also read a bounded
+event stream; the Go, Rust, and Java smoke commands exercise the command path
+and can be paired with their `stream-events` commands after a session is open.
+
+Client-side cancellation or timeout stops waiting for the gateway response. It
+does not abort an MXAccess COM call that is already executing on the worker STA.
+
+## Related Documentation
+
+- [Client Proto Generation](./client-proto-generation.md)
+- [Client Libraries Detailed Design](./client-libraries-design.md)
+- [Client Behavior Fixtures](./ClientBehaviorFixtures.md)
+- [Toolchain Links](./toolchain-links.md)

docs/Contracts.md

@@ -10,11 +10,31 @@ recreated by the contracts project build.
 `MxAccessGateway` gRPC service, command payloads, command replies, event DTOs,
 `MxValue`, `MxArray`, and `MxStatusProxy`.
 
+The public command model includes bulk subscription command kinds for
+`AddItemBulk`, `AdviseItemBulk`, `RemoveItemBulk`, `UnAdviseItemBulk`,
+`SubscribeBulk`, and `UnsubscribeBulk`. These commands are normal unary
+`Invoke` payloads. They do not add separate gRPC methods, and they return a
+`BulkSubscribeReply` containing per-item `SubscribeResult` records with
+`ServerHandle`, `TagAddress`, `ItemHandle`, `WasSuccessful`, and
+`ErrorMessage`.
+
+The gateway forwards each bulk command as one worker command. The worker runs
+the corresponding MXAccess `AddItem`, `Advise`, `UnAdvise`, and `RemoveItem`
+calls sequentially on the session STA and preserves input order in the result
+list.
+
 `src/MxGateway.Contracts/Protos/mxaccess_worker.proto` defines the named-pipe
 worker IPC envelope and control messages. It imports
 `mxaccess_gateway.proto` so the worker and gateway use the same command, reply,
 event, value, and status shapes.
 
+`src/MxGateway.Contracts/Protos/galaxy_repository.proto` defines the
+`GalaxyRepository` service used by clients to browse the Galaxy Repository
+(deployed object hierarchy and dynamic attributes). The service is metadata-
+only and does not share types with `mxaccess_gateway.proto`. See
+[Galaxy Repository Browse](./GalaxyRepository.md) for the RPC catalog and
+behavior.
+
 Generated C# output is written to `src/MxGateway.Contracts/Generated/`. Do not
 hand-edit generated files.
 

docs/DashboardInterfaceDesign.md

@@ -0,0 +1,294 @@
+# Dashboard Interface Design
+
+This guide describes the visual and interaction patterns used by the MXAccess
+Gateway dashboard so the same interface style can be reused in other
+operations-focused projects.
+
+## Design Goal
+
+The dashboard is an operational interface, not a landing page. It prioritizes
+fast scanning, low visual noise, and stable layouts while live data changes.
+The design uses Bootstrap for common behavior and a small local stylesheet for
+project identity, spacing, and status presentation.
+
+Use this style for applications where users repeatedly check system state,
+compare rows, inspect details, and diagnose faults. Avoid promotional layouts,
+large hero areas, decorative imagery, or oversized cards that reduce data
+density.
+
+## Visual Language
+
+The interface uses a quiet, work-focused visual system:
+
+- A light gray page background separates the application shell from white data
+  surfaces.
+- White cards and sections carry the actual operational content.
+- Borders define structure more often than shadows.
+- Accent color is reserved for metric values and important numeric signals.
+- Bootstrap status badges provide state color without custom status art.
+- Tables remain compact and responsive so long identifiers and timestamps stay
+  readable.
+
+The resulting page should look like a control surface: restrained, predictable,
+and dense enough for repeated use.
+
+## Layout Structure
+
+Every page follows the same structure:
+
+1. A top navigation bar with the product or service name on the left.
+2. A full-width `container-fluid` content area.
+3. A page header with the page title, short context text, and optional status
+   badge.
+4. Metric cards when a page has top-level numeric state.
+5. Bordered content sections for tables, details, faults, or empty states.
+
+The shell does not use a sidebar. A horizontal navigation bar is enough for the
+current page count and keeps the content width available for tables.
+
+```html
+<div class="dashboard-shell">
+  <nav class="navbar navbar-expand-lg bg-body border-bottom dashboard-navbar">
+    <!-- brand, page links, sign-out action -->
+  </nav>
+  <main class="container-fluid dashboard-content">
+    <!-- page header, metric grid, sections -->
+  </main>
+</div>
+```
+
+## Color Tokens
+
+Use a small token set and let Bootstrap provide the rest. The current dashboard
+uses these local tokens:
+
+```css
+:root {
+  --mxgw-surface: #f7f8fa;
+  --mxgw-border: #d8dee6;
+  --mxgw-ink-muted: #667085;
+  --mxgw-accent: #146c64;
+}
+```
+
+| Token | Purpose |
+|-------|---------|
+| `--mxgw-surface` | Page background behind all content. |
+| `--mxgw-border` | Borders on cards, tables, sections, and empty states. |
+| `--mxgw-ink-muted` | Secondary labels, details, and empty-state text. |
+| `--mxgw-accent` | Metric values and important numeric summaries. |
+
+Keep the palette small. Add new colors only when they encode state or improve
+readability. Prefer Bootstrap badge classes for states such as ready, closing,
+closed, and faulted.
+
+## Typography
+
+Typography stays compact and consistent:
+
+- Page headings use `1.35rem`, weight `650`, and normal letter spacing.
+- Section headings use the same size as page headings when they introduce a
+  table or details group.
+- Metric labels use uppercase text at `.78rem` and weight `650`.
+- Metric values use `1.7rem`, weight `700`, and the accent color.
+- Body and table text inherit Bootstrap defaults for readability.
+
+Do not scale text with viewport width. Long values use `overflow-wrap:
+anywhere` so session IDs, paths, and fault messages do not break the layout.
+
+## Spacing And Shape
+
+The dashboard uses modest spacing:
+
+- Page content has `1.25rem` padding on desktop and `.75rem` on small screens.
+- Metric grids use `.75rem` gaps.
+- Content sections start with a top border and `1rem` top padding.
+- Cards and empty states use Bootstrap's small radius shape, `.375rem`.
+- Metric cards have no shadow.
+
+This keeps information grouped without turning each section into a decorative
+panel. Use cards for repeated metric summaries, login forms, and individual
+items. Use unframed sections with a top border for page-level groups.
+
+## Navigation
+
+Navigation is a Bootstrap responsive navbar. It includes:
+
+- Brand text for the service name.
+- Short page labels: `Overview`, `Sessions`, `Workers`, `Events`, `Settings`.
+- Active route styling through `NavLink`.
+- A right-aligned sign-out button when authentication is enabled.
+
+Keep navigation labels short. Operational users should be able to predict what
+each page contains without reading explanatory copy.
+
+## Page Headers
+
+Each page starts with a `dashboard-page-header`:
+
+- The title is the primary anchor.
+- A single secondary line gives timestamp, row count, or configuration context.
+- A status badge appears on the right when the page has an overall state.
+
+On narrow screens, the header stacks vertically. This prevents long context
+text or status badges from overlapping the title.
+
+```html
+<div class="dashboard-page-header">
+  <div>
+    <h1>Overview</h1>
+    <div class="text-secondary">Generated 2026-04-27 17:30:00</div>
+  </div>
+  <span class="badge text-bg-success">Healthy</span>
+</div>
+```
+
+## Metric Cards
+
+Metric cards summarize numeric state at the top of overview and diagnostic
+pages. They use Bootstrap cards with a local `metric-card` class:
+
+- Label: uppercase, muted, compact.
+- Value: large enough to scan, accent colored, wraps safely.
+- Detail: optional muted text for version, rate context, or explanatory state.
+
+Use auto-fit CSS grid tracks so the cards fill available width without custom
+breakpoints:
+
+```css
+.metric-grid {
+  display: grid;
+  gap: .75rem;
+  grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
+}
+
+.metric-grid.compact {
+  grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr));
+}
+```
+
+Metrics should be formatted before rendering. Counts use thousands separators,
+durations use stable units, and missing values render as `-`.
+
+## Tables
+
+Tables are the main information surface. Use Bootstrap `table table-sm` with a
+local `dashboard-table` class:
+
+- `table-sm` keeps rows dense.
+- `align-middle` improves status badge alignment.
+- `table-responsive` wraps every table that can exceed the viewport.
+- Header cells use weight `650` and no wrapping.
+- Body cells allow wrapping so identifiers, paths, and messages stay visible.
+- Detail tables reserve a fixed header width.
+
+Use code formatting for machine identifiers such as session IDs, file paths,
+and protocol values. Link rows only where navigation is useful; avoid making
+entire rows clickable when a single identifier link is clearer.
+
+## Status Badges
+
+Status uses Bootstrap badge classes with a small mapping layer:
+
+| State | Badge class |
+|-------|-------------|
+| `Ready`, `Healthy` | `text-bg-success` |
+| `Creating`, `StartingWorker`, `WaitingForPipe`, `InitializingWorker`, `Closing` | `text-bg-info` |
+| `Closed` | `text-bg-secondary` |
+| `Faulted` | `text-bg-danger` |
+| Unknown state | `text-bg-light text-dark border` |
+
+Keep status text literal. Operators benefit from seeing the same state names
+that appear in logs and APIs.
+
+## Empty And Loading States
+
+Empty states are explicit and quiet. They use a white background, dashed border,
+small radius, muted text, and one sentence:
+
+```html
+<div class="empty-state">No worker processes are attached.</div>
+```
+
+Loading states use the same component shape. Avoid spinners for snapshot pages
+that update on a timer; a stable text placeholder is less distracting.
+
+## Detail Pages
+
+Detail pages use stacked sections instead of nested cards:
+
+- The page header identifies the selected entity.
+- The first section shows entity metadata in a two-column details table.
+- Additional sections show related runtime state, such as worker metadata.
+- Missing entities render a single section with a concise not-found message.
+
+This structure keeps details comparable across pages and avoids card nesting.
+
+## Responsive Behavior
+
+The dashboard uses one small-screen breakpoint:
+
+```css
+@media (max-width: 700px) {
+  .dashboard-content {
+    padding: .75rem;
+  }
+
+  .dashboard-page-header {
+    align-items: flex-start;
+    flex-direction: column;
+  }
+
+  .details-table th {
+    width: 9rem;
+  }
+}
+```
+
+Do not hide important columns by default. Use horizontal table scrolling for
+dense operational data, and reserve column hiding for data that is clearly
+duplicative.
+
+## Data Formatting
+
+Use a small display helper instead of formatting inline in every component.
+The helper should provide consistent rendering for:
+
+- empty text as `-`,
+- counts with thousands separators,
+- dates and times in a consistent local or configured format,
+- durations in stable units,
+- metric lookup by name and dimension.
+
+Centralizing formatting prevents visual drift between overview cards, tables,
+and detail pages.
+
+## Security And Redaction
+
+The interface is read-only unless an explicit administrative action is
+designed. It should not display secrets or raw credential-bearing values.
+
+Apply redaction before values reach Razor components. The UI treats redacted
+values as normal display text; it does not need to know why a value is hidden.
+This keeps security policy in the dashboard projection layer rather than in
+markup.
+
+## Replication Checklist
+
+Use this checklist when applying the design to another project:
+
+- Define four local tokens: surface, border, muted ink, and accent.
+- Use a Bootstrap top navbar with short route labels.
+- Keep page content inside a full-width fluid container.
+- Start every page with the same header structure.
+- Put primary numeric state in `metric-grid` cards.
+- Put detailed runtime state in compact responsive tables.
+- Use status badges mapped from real domain states.
+- Use dashed bordered empty states for loading and no-data cases.
+- Use top-bordered sections for page groups instead of nested cards.
+- Centralize formatting and redaction outside Razor markup.
+- Keep the dashboard read-only until admin workflows have a separate design.
+
+## Related Documentation
+
+- [Gateway Dashboard Detailed Design](./gateway-dashboard-design.md)

docs/Diagnostics.md

@@ -0,0 +1,222 @@
+# Gateway Diagnostics
+
+The diagnostics subsystem provides structured logging, credential redaction, and request-scoped log enrichment for the gateway. It lives under `src/MxGateway.Server/Diagnostics/` and is wired into the ASP.NET Core pipeline so every gRPC and HTTP request carries the same correlation fields.
+
+## Goals
+
+The subsystem exists to satisfy two security rules from `AGENTS.md`: never log passwords or raw credential values for `AuthenticateUser`, `WriteSecured`, or related secured operations, and never log full MXAccess values by default. Code paths that touch credentials or tag values must therefore route through `GatewayLogRedactor` rather than emitting them directly.
+
+A second goal is parity-test diagnosability. Because MXAccess sessions, workers, correlation ids, and command methods are the units of comparison, every log entry produced inside a request scope must carry those identifiers without each call site having to format them.
+
+## Log Scopes
+
+`GatewayLogScope` is a record that captures the fields attached to a logger scope. It only emits keys whose values are non-null, so callers can supply just the identifiers they know about:
+
+```csharp
+public sealed record GatewayLogScope(
+    string? SessionId = null,
+    int? WorkerProcessId = null,
+    ulong? CorrelationId = null,
+    string? CommandMethod = null,
+    string? ClientIdentity = null)
+{
+    public IReadOnlyDictionary<string, object?> ToDictionary()
+    {
+        Dictionary<string, object?> values = [];
+
+        AddIfPresent(values, "SessionId", SessionId);
+        AddIfPresent(values, "WorkerProcessId", WorkerProcessId);
+        AddIfPresent(values, "CorrelationId", CorrelationId);
+        AddIfPresent(values, "CommandMethod", CommandMethod);
+        AddIfPresent(values, "ClientIdentity", GatewayLogRedactor.RedactClientIdentity(ClientIdentity));
+
+        return values;
+    }
+```
+
+`ClientIdentity` is passed through `GatewayLogRedactor.RedactClientIdentity` inside `ToDictionary` rather than at the call site. This guarantees that any logger scope built from a `GatewayLogScope` cannot accidentally surface a raw API key, even when a caller forgets to redact before constructing the scope.
+
+### How scopes are pushed
+
+`GatewayLoggerExtensions` exposes a single method that converts a `GatewayLogScope` into the dictionary form expected by `ILogger.BeginScope`:
+
+```csharp
+public static class GatewayLoggerExtensions
+{
+    public static IDisposable? BeginGatewayScope(
+        this ILogger logger,
+        GatewayLogScope scope)
+    {
+        ArgumentNullException.ThrowIfNull(logger);
+        ArgumentNullException.ThrowIfNull(scope);
+
+        return logger.BeginScope(scope.ToDictionary());
+    }
+}
+```
+
+The returned `IDisposable?` follows the standard `BeginScope` contract: callers wrap it in a `using` to bound the scope to a request, command, or worker interaction.
+
+## Redaction Rules
+
+`GatewayLogRedactor` centralizes every redaction decision so that policy changes live in one file. Three categories of input are handled differently because each has different "safe to log" prefixes.
+
+### Sensitive command methods
+
+A static set names the MXAccess commands that are known to carry credentials in their payloads:
+
+```csharp
+private static readonly HashSet<string> SensitiveCommandMethods = new(StringComparer.OrdinalIgnoreCase)
+{
+    "AuthenticateUser",
+    "WriteSecured",
+    "WriteSecured2"
+};
+
+public static bool IsCredentialBearingCommand(string? commandMethod)
+{
+    return commandMethod is not null
+        && SensitiveCommandMethods.Contains(commandMethod);
+}
+```
+
+The names match the MXAccess command list in `AGENTS.md` exactly. `Write` and `Write2` are not in the set because their payloads are tag values, not credentials, and are governed by the `valueLoggingEnabled` flag described below.
+
+### API key redaction
+
+`RedactApiKey` is built around the `mxgw_` API key format issued by the gateway. It preserves the bearer scheme and the key id segment so that operators can correlate a log entry to a specific principal, but always strips the secret tail:
+
+```csharp
+public static string? RedactApiKey(string? authorizationHeader)
+{
+    if (string.IsNullOrWhiteSpace(authorizationHeader))
+    {
+        return authorizationHeader;
+    }
+
+    const string bearerPrefix = "Bearer ";
+    if (!authorizationHeader.StartsWith(bearerPrefix, StringComparison.OrdinalIgnoreCase))
+    {
+        return RedactedValue;
+    }
+
+    string token = authorizationHeader[bearerPrefix.Length..].Trim();
+
+    if (!token.StartsWith("mxgw_", StringComparison.OrdinalIgnoreCase))
+    {
+        return $"{bearerPrefix}{RedactedValue}";
+    }
+
+    string[] tokenParts = token.Split('_', 3, StringSplitOptions.RemoveEmptyEntries);
+    if (tokenParts.Length < 2)
+    {
+        return $"{bearerPrefix}mxgw_{RedactedValue}";
+    }
+
+    return $"{bearerPrefix}mxgw_{tokenParts[1]}_{RedactedValue}";
+}
+```
+
+The split uses `count: 3` because the secret portion may itself contain underscores; only the first two segments (`mxgw` and the key id) are kept verbatim. Authorization headers that are not bearer tokens are reduced to `[redacted]` rather than passed through, since the gateway cannot reason about their structure.
+
+`RedactClientIdentity` is the entry point used by `GatewayLogScope` and `DashboardRedactor`. It only invokes `RedactApiKey` when the input contains the `mxgw_` marker, leaving non-key identities (for example, Windows account names) untouched.
+
+### Command value redaction
+
+`RedactCommandValue` enforces the "values are opt-in and redacted by default" rule:
+
+```csharp
+public static object? RedactCommandValue(
+    string? commandMethod,
+    object? value,
+    bool valueLoggingEnabled = false)
+{
+    if (value is null)
+    {
+        return null;
+    }
+
+    if (!valueLoggingEnabled || IsCredentialBearingCommand(commandMethod))
+    {
+        return RedactedValue;
+    }
+
+    return value;
+}
+```
+
+Two rules combine here. First, when `valueLoggingEnabled` is `false` (the default), every value is replaced with `[redacted]`. Second, even when value logging is enabled, credential-bearing commands still redact. The credential check is therefore unconditional and cannot be overridden by configuration.
+
+The shared `RedactedValue` constant is `"[redacted]"`. `DashboardRedactor` reuses it so that gateway logs and dashboard renders use the same placeholder.
+
+## Request Logging Middleware
+
+`GatewayRequestLoggingMiddlewareExtensions.UseGatewayRequestLoggingScope` registers the middleware that pushes a `GatewayLogScope` for the duration of every request:
+
+```csharp
+public static IApplicationBuilder UseGatewayRequestLoggingScope(this IApplicationBuilder app)
+{
+    ArgumentNullException.ThrowIfNull(app);
+
+    return app.Use(async (context, next) =>
+    {
+        ILogger logger = context.RequestServices
+            .GetRequiredService<ILoggerFactory>()
+            .CreateLogger("MxGateway.Request");
+
+        using IDisposable? scope = logger.BeginGatewayScope(new GatewayLogScope(
+            SessionId: ReadHeader(context, SessionIdHeaderName),
+            WorkerProcessId: ReadInt32Header(context, WorkerProcessIdHeaderName),
+            CorrelationId: ReadUInt64Header(context, CorrelationIdHeaderName),
+            CommandMethod: ReadHeader(context, CommandMethodHeaderName),
+            ClientIdentity: ReadHeader(context, "authorization")));
+
+        await next(context);
+    });
+}
+```
+
+The scope is keyed off four custom headers and the standard `authorization` header:
+
+| Header | Scope field | Type |
+|--------|-------------|------|
+| `x-session-id` | `SessionId` | string |
+| `x-worker-process-id` | `WorkerProcessId` | int |
+| `x-correlation-id` | `CorrelationId` | ulong |
+| `x-command-method` | `CommandMethod` | string |
+| `authorization` | `ClientIdentity` | string (redacted) |
+
+The numeric headers use `int.TryParse` and `ulong.TryParse`; missing or unparseable values become `null` and are dropped by `GatewayLogScope.ToDictionary`. This keeps the middleware tolerant of clients that do not yet emit every header, which matters because the earliest call in a session (`OpenSession`) has no `SessionId` to send.
+
+The logger category is `MxGateway.Request`, which lets operators filter the request scope events independently from per-component categories.
+
+### Pipeline ordering
+
+`GatewayApplication.Build` registers the middleware before authentication, authorization, and endpoint mapping:
+
+```csharp
+app.UseGatewayRequestLoggingScope();
+app.UseStaticFiles();
+app.UseAuthentication();
+app.UseAuthorization();
+app.UseAntiforgery();
+app.MapGatewayEndpoints();
+```
+
+The order matters: putting the logging scope first ensures that authentication failures, authorization denials, and endpoint exceptions all run inside the request scope, so failure logs still carry the correlation id and session id headers that the caller sent. The `ClientIdentity` field is redacted before logging, so reading the `authorization` header at this stage does not leak the bearer secret into authentication failure logs.
+
+## Consumers
+
+`GatewayLoggerExtensions.BeginGatewayScope` is consumed by `GatewayRequestLoggingMiddlewareExtensions` to attach the per-request scope. Component-level call sites build narrower `GatewayLogScope` instances (for example, with a known `WorkerProcessId` after a worker launch) and push a nested scope on top of the request scope.
+
+`GatewayLogRedactor` is consumed in three places:
+
+- `GatewayLogScope.ToDictionary` redacts `ClientIdentity` whenever a scope is materialized.
+- `DashboardRedactor.Redact` delegates to `RedactClientIdentity` for any value containing the `mxgw_` marker, then falls back to a marker-keyword check for fields like `password` or `token`. This keeps dashboard renders aligned with log redaction.
+- `MxGateway.Tests/Diagnostics/GatewayLogRedactorTests.cs` covers each redaction branch, including the assertion that `WriteSecured` values stay redacted even when `valueLoggingEnabled` is true.
+
+## Related Documentation
+
+- [Sessions](./Sessions.md)
+- [gRPC](./Grpc.md)
+- [Authentication](./Authentication.md)

docs/GalaxyRepository.md

@@ -0,0 +1,318 @@
+# Galaxy Repository Browse
+
+The gateway exposes a read-only browse surface over the AVEVA System Platform
+Galaxy Repository (the SQL Server database named `ZB`). Clients use it to
+enumerate the deployed object hierarchy and each object's dynamic attributes
+before subscribing to runtime values via the existing `MxAccessGateway` RPCs.
+
+This is a metadata layer: it never reads or writes runtime tag values, never
+goes through MXAccess COM, and never needs the x86 worker. It runs entirely
+inside the .NET 10 gateway process and talks to the Galaxy Repository over
+plain SQL.
+
+## Why It Exists
+
+Without browse, a client must already know `tag_name.AttributeName` strings to
+issue `AddItem`. The Galaxy Repository is the authoritative source for those
+names — the same database that System Platform itself reads when the
+ArchestrA IDE renders the deployment tree. Surfacing that data over gRPC lets
+remote clients build a navigable address space without any coupling to the
+COM layer or the host platform.
+
+The query bodies are kept byte-for-byte identical to the equivalent OPC UA
+server in the OtOpcUa project so the two consumers see the same row sets.
+
+## RPC Surface
+
+The service is defined in
+`src/MxGateway.Contracts/Protos/galaxy_repository.proto` under package
+`galaxy_repository.v1`.
+
+| RPC | Purpose |
+|-----|---------|
+| `TestConnection` | Connectivity probe. Returns `{ ok: bool }` after a `SELECT 1`. Does not throw on SQL failure — returns `ok = false`. Always hits SQL directly so it remains a true health check. |
+| `GetLastDeployTime` | Returns the cached `galaxy.time_of_last_deploy`. Served from the shared hierarchy cache; refreshed in the background. |
+| `DiscoverHierarchy` | Returns one page of the deployed hierarchy plus each returned object's dynamic attributes. **Served from cache** — see [Hierarchy Cache](#hierarchy-cache). |
+| `WatchDeployEvents` | **Server-streaming.** The server emits the current state immediately on subscribe (so clients can bootstrap without waiting), then emits one event per detected deploy change. See [Deploy Notifications](#deploy-notifications). |
+
+`DiscoverHierarchy` is a paged unary RPC. The raw request accepts `page_size`
+and `page_token`; the server defaults omitted page size to 1000 objects and
+caps every page at 5000 objects. Page tokens bind to the cache sequence and the
+active filter set, so changing filters between pages returns `InvalidArgument`
+instead of mixing snapshots. Official high-level clients preserve the older
+"return the full hierarchy" behavior by looping pages internally.
+
+The request can also slice the cached hierarchy without running new SQL. A
+caller may choose one root (`root_gobject_id`, `root_tag_name`, or
+`root_contained_path`) and may combine that with `max_depth`, category ids,
+template-chain substring filters, an anchored case-insensitive tag-name glob,
+alarm-only, historized-only, and `include_attributes = false` for a skeleton
+tree. All filters are applied with AND semantics, and `total_object_count`
+reports the post-filter count.
+
+## Hierarchy Cache
+
+The gateway holds a single shared `IGalaxyHierarchyCache`
+(`src/MxGateway.Server/Galaxy/GalaxyHierarchyCache.cs`) — every
+`DiscoverHierarchy` and `GetLastDeployTime` request reads from this cache
+rather than hitting SQL. Many clients can browse concurrently with at most
+one SQL query in flight.
+
+Refresh strategy is **deploy-time gated**:
+
+1. The hosted `GalaxyHierarchyRefreshService` ticks every
+   `MxGateway:Galaxy:DashboardRefreshIntervalSeconds` seconds (default 30).
+2. Each tick queries the cheap `SELECT time_of_last_deploy FROM galaxy` first.
+3. If the deploy timestamp is unchanged, the heavy hierarchy + attributes
+   queries are **skipped**. The cache simply marks `LastSuccessAt`.
+4. If the deploy timestamp changed (or no data has loaded yet), the cache
+   pulls hierarchy + attributes, materializes a Galaxy object list plus a
+   dashboard summary once, replaces the entry atomically, and publishes a
+   deploy event.
+
+Materializing objects and dashboard summaries at refresh time means subsequent
+`DiscoverHierarchy` calls page over an immutable object list. The dashboard
+uses the precomputed summary and does not rescan raw SQL rowsets on each
+snapshot.
+
+When SQL is unreachable, the cache retains the previous data and flips
+`Status` to `Stale` (or `Unavailable` if no data was ever loaded). A
+`SqlException` never bubbles out as the client-facing error.
+
+### First-load behavior
+
+If a client calls `DiscoverHierarchy` before the background service has
+populated the cache, the gRPC handler waits up to 5 seconds for the first
+load to complete before returning. If the first load fails or times out,
+the client gets `Unavailable` with a short reason. Once any load completes
+(success or failure), this wait is skipped on subsequent calls.
+
+## Deploy Notifications
+
+`WatchDeployEvents` is a server-streaming RPC backed by
+`IGalaxyDeployNotifier` (`src/MxGateway.Server/Galaxy/GalaxyDeployNotifier.cs`).
+The notifier maintains a private bounded channel per subscriber so a slow
+client cannot back-pressure other subscribers or the publisher.
+
+Subscriber lifecycle:
+
+1. On subscribe, the notifier emits the **current** event (the state of the
+   most recent successful refresh) so the subscriber can sync its local cache
+   without waiting for the next deploy. Clients that already know about that
+   deploy can pass `last_seen_deploy_time` in the request to suppress the
+   bootstrap event.
+2. As the cache observes new deploy timestamps, it publishes one event per
+   change. Each event carries:
+   - `sequence` — monotonic per server start; gaps signal a dropped event.
+   - `observed_at` — server wall-clock when the cache saw the deploy.
+   - `time_of_last_deploy` (+ `time_of_last_deploy_present`) — the Galaxy
+     timestamp; absent only when the source row reports null.
+   - `object_count`, `attribute_count` — counts on the new deploy, useful for
+     dashboards and "did anything important change" gates without re-pulling.
+3. If the subscriber's per-subscriber buffer fills (bound = 16 events with
+   `DropOldest`), older events are dropped. Clients use the `sequence` field
+   to detect this.
+4. Cancellation (or transport disconnect) removes the subscriber.
+
+Typical client pattern:
+
+```text
+1. Open WatchDeployEvents stream (with last_seen_deploy_time if you have one).
+2. On each event, decide whether to call DiscoverHierarchy to refresh local cache.
+3. If sequence skipped a number, treat it as a dropped event and refresh.
+```
+
+### Reply Shape
+
+```proto
+message GalaxyObject {
+  int32 gobject_id = 1;
+  string tag_name = 2;
+  string contained_name = 3;
+  string browse_name = 4;        // contained_name when present, else tag_name
+  int32 parent_gobject_id = 5;
+  bool is_area = 6;
+  int32 category_id = 7;
+  int32 hosted_by_gobject_id = 8;
+  repeated string template_chain = 9;
+  repeated GalaxyAttribute attributes = 10;
+}
+
+message GalaxyAttribute {
+  string attribute_name = 1;
+  string full_tag_reference = 2;   // e.g. "DelmiaReceiver_001.DownloadPath"
+  int32 mx_data_type = 3;          // raw Galaxy mx_data_type integer
+  string data_type_name = 4;
+  bool is_array = 5;
+  int32 array_dimension = 6;
+  bool array_dimension_present = 7; // distinguishes "no dimension" from 0
+  int32 mx_attribute_category = 8;
+  int32 security_classification = 9;
+  bool is_historized = 10;
+  bool is_alarm = 11;
+}
+
+message DiscoverHierarchyRequest {
+  int32 page_size = 1;    // omitted/0 uses the server default of 1000
+  string page_token = 2;  // opaque token returned by the previous page
+  oneof root {
+    int32 root_gobject_id = 3;
+    string root_tag_name = 4;
+    string root_contained_path = 5;
+  }
+  google.protobuf.Int32Value max_depth = 6;
+  repeated int32 category_ids = 7;
+  repeated string template_chain_contains = 8;
+  string tag_name_glob = 9;
+  optional bool include_attributes = 10;
+  bool alarm_bearing_only = 11;
+  bool historized_only = 12;
+}
+
+message DiscoverHierarchyReply {
+  repeated GalaxyObject objects = 1;
+  string next_page_token = 2;
+  int32 total_object_count = 3;
+}
+```
+
+### Contained Name vs Tag Name
+
+Galaxy objects carry two names. `tag_name` is globally unique and is what
+MXAccess expects in `AddItem`. `contained_name` is the human-readable name
+used in the IDE browse tree, scoped to the parent. The browse RPC exposes
+both: clients display `browse_name` to users and pass `tag_name` (or
+`full_tag_reference`) into MXAccess subscriptions. When `contained_name` is
+empty (top-level objects), `browse_name` falls back to `tag_name`.
+
+### Data Types
+
+`mx_data_type` is returned as the raw Galaxy integer rather than mapped to a
+language-neutral enum. The gateway makes no assumption about the client's
+target type system — clients map to OPC UA, JSON, .NET CLR types, or
+something else as appropriate. The Galaxy `data_type` table description is
+also passed through as `data_type_name`.
+
+`array_dimension_present` is a separate boolean because protobuf scalar
+fields cannot express null. Use it to distinguish "no dimension reported" from
+"dimension is zero."
+
+## Architecture
+
+```text
+gRPC client(s)
+  -> GalaxyRepositoryGrpcService (src/MxGateway.Server/Grpc/)
+    DiscoverHierarchy, GetLastDeployTime  -> IGalaxyHierarchyCache.Current
+    WatchDeployEvents                     -> IGalaxyDeployNotifier
+    TestConnection                        -> GalaxyRepository  (direct SQL)
+
+GalaxyHierarchyRefreshService (BackgroundService)
+  -> IGalaxyHierarchyCache.RefreshAsync
+    -> GalaxyRepository.GetLastDeployTimeAsync   (cheap, every tick)
+    -> GalaxyRepository.GetHierarchyAsync         (only on deploy change)
+    -> GalaxyRepository.GetAttributesAsync        (only on deploy change)
+    -> GalaxyProtoMapper.MapObject (materialize GalaxyObject list once)
+    -> DashboardGalaxySummary (precompute dashboard counts once)
+    -> IGalaxyDeployNotifier.Publish (only on deploy change)
+```
+
+Component breakdown:
+
+- `GalaxyRepository` (`src/MxGateway.Server/Galaxy/GalaxyRepository.cs`) holds
+  the SQL. Its constants `HierarchySql` and `AttributesSql` are copied verbatim
+  from the OtOpcUa project; do not edit them in isolation here. The two
+  queries walk template-derivation and package-derivation chains via
+  recursive CTEs and pick the most-derived attribute override per object.
+- `GalaxyHierarchyCache`
+  (`src/MxGateway.Server/Galaxy/GalaxyHierarchyCache.cs`) holds the most
+  recent immutable `GalaxyHierarchyCacheEntry` (materialized objects +
+  precomputed dashboard summary + counts + status). All gRPC clients share the
+  same entry.
+- `GalaxyHierarchyRefreshService`
+  (`src/MxGateway.Server/Galaxy/GalaxyHierarchyRefreshService.cs`) is a
+  hosted `BackgroundService` that drives `RefreshAsync` on the configured
+  interval, with deploy-time gating to avoid unnecessary heavy queries.
+- `GalaxyDeployNotifier`
+  (`src/MxGateway.Server/Galaxy/GalaxyDeployNotifier.cs`) is a thin
+  per-subscriber-channel fan-out for streaming clients.
+- `GalaxyProtoMapper`
+  (`src/MxGateway.Server/Grpc/GalaxyProtoMapper.cs`) converts row models to
+  proto messages. Used by the cache during refresh to materialize the reply
+  once.
+- `GalaxyRepositoryGrpcService`
+  (`src/MxGateway.Server/Grpc/GalaxyRepositoryGrpcService.cs`) implements
+  the four RPCs.
+
+## Configuration
+
+Bound to `MxGateway:Galaxy` via `GalaxyRepositoryOptions`.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `MxGateway:Galaxy:ConnectionString` | `Server=localhost;Database=ZB;Integrated Security=True;TrustServerCertificate=True;Encrypt=False;` | SQL Server connection string for the Galaxy Repository. Integrated Security against `localhost` is the dev default; production deployments should override this through the standard double-underscore environment variable form, e.g. `MxGateway__Galaxy__ConnectionString`. |
+| `MxGateway:Galaxy:CommandTimeoutSeconds` | `60` | Per-command SQL timeout. Applies to all three RPCs. |
+
+The connection string is not treated as a secret in dev (`Integrated
+Security`), but production deployments that use SQL authentication should set
+the override via environment variable rather than committing credentials to
+`appsettings.json`.
+
+The dashboard parses this connection string and displays only non-secret
+fields: server, database, integrated security, encrypt, and trust-server-
+certificate. It never displays user id, password, access token, or arbitrary
+unparsed connection string text.
+
+## Authorization
+
+All four Galaxy RPCs (including `WatchDeployEvents`) require the
+`metadata:read` API-key scope. Browse is read-only metadata, equivalent in
+privilege to `MxCommandKind.GetSessionState` or `MxCommandKind.GetWorkerInfo`.
+The mapping lives in `GatewayGrpcScopeResolver`; see
+[Authorization](./Authorization.md) for the full scope catalog.
+
+API keys can also carry `browse_subtrees` constraints. `DiscoverHierarchy`
+intersects those contained-path globs with the caller's request filters.
+`WatchDeployEvents` still emits deploy notifications, but its object and
+attribute counts are scoped to the caller's browsable subtrees.
+
+A request without an API key returns `Unauthenticated`. A request with a key
+that lacks `metadata:read` returns `PermissionDenied` with the missing scope
+embedded in the status detail.
+
+## Dashboard Surface
+
+The gateway's Blazor dashboard surfaces a Galaxy summary in two places:
+
+- An overview card on `/dashboard` showing connectivity status, last deploy
+  timestamp, object count (with area count), attribute total, historized and
+  alarm counts, and last successful refresh.
+- A dedicated `/dashboard/galaxy` page with object-category and top-template
+  breakdowns plus a Sync Info table covering last successful refresh, last
+  attempt, refresh interval, redacted connection string, and command timeout.
+
+Both views are projected from the same `IGalaxyHierarchyCache` that backs the
+gRPC service. The dashboard does not run its own refresh — when the
+background `GalaxyHierarchyRefreshService` updates the cache, both the
+overview card and the `/dashboard/galaxy` page pick up the new state on the
+next dashboard tick. When SQL is unreachable, the cache retains the previous
+data and flips `Status` to `Stale` or `Unavailable`; the dashboard surfaces
+that as a yellow or red status badge plus the truncated error.
+
+## Operational Notes
+
+- The service is registered alongside `MxAccessGatewayService` in
+  `GatewayApplication.MapGatewayEndpoints`. Both services share the same
+  authorization interceptor and authentication policy.
+- Failures to reach the Galaxy database surface as `Unavailable`. Detailed
+  SQL exceptions are logged at `Warning` and never returned to clients.
+- Integration tests live in
+  `src/MxGateway.IntegrationTests/Galaxy/GalaxyRepositoryLiveTests.cs`. Set
+  `MXGATEWAY_RUN_LIVE_GALAXY_TESTS=1` (and optionally
+  `MXGATEWAY_LIVE_GALAXY_CONN`) to run them; otherwise they skip.
+
+## Related Documentation
+
+- [Contracts](./Contracts.md)
+- [Grpc](./Grpc.md)
+- [Authorization](./Authorization.md)
+- [Gateway Configuration](./GatewayConfiguration.md)

docs/GatewayConfiguration.md

@@ -0,0 +1,177 @@
+# Gateway Configuration
+
+This document describes every option bound under the `MxGateway` configuration
+section by `GatewayOptions`.
+
+The gateway binds configuration at startup and validates it with
+`GatewayOptionsValidator`. Startup fails before the server listens when required
+paths, timeouts, queue sizes, enum values, or protocol values are invalid.
+
+## Configuration Shape
+
+```json
+{
+  "MxGateway": {
+    "Authentication": {
+      "Mode": "ApiKey",
+      "SqlitePath": "C:\\ProgramData\\MxGateway\\gateway-auth.db",
+      "PepperSecretName": "MxGateway:ApiKeyPepper",
+      "RunMigrationsOnStartup": true
+    },
+    "Worker": {
+      "ExecutablePath": "src\\MxGateway.Worker\\bin\\x86\\Release\\MxGateway.Worker.exe",
+      "WorkingDirectory": null,
+      "RequiredArchitecture": "X86",
+      "StartupTimeoutSeconds": 30,
+      "StartupProbeRetryAttempts": 3,
+      "StartupProbeRetryDelayMilliseconds": 250,
+      "PipeConnectAttemptTimeoutMilliseconds": 2000,
+      "ShutdownTimeoutSeconds": 10,
+      "HeartbeatIntervalSeconds": 5,
+      "HeartbeatGraceSeconds": 15,
+      "MaxMessageBytes": 16777216
+    },
+    "Sessions": {
+      "DefaultCommandTimeoutSeconds": 30,
+      "MaxSessions": 64,
+      "MaxPendingCommandsPerSession": 128,
+      "DefaultLeaseSeconds": 1800,
+      "LeaseSweepIntervalSeconds": 30,
+      "AllowMultipleEventSubscribers": false
+    },
+    "Events": {
+      "QueueCapacity": 10000,
+      "BackpressurePolicy": "FailFast"
+    },
+    "Dashboard": {
+      "Enabled": true,
+      "PathBase": "/dashboard",
+      "RequireAdminScope": true,
+      "AllowAnonymousLocalhost": true,
+      "SnapshotIntervalMilliseconds": 1000,
+      "RecentFaultLimit": 100,
+      "RecentSessionLimit": 200,
+      "ShowTagValues": false
+    },
+    "Protocol": {
+      "WorkerProtocolVersion": 1,
+      "MaxGrpcMessageBytes": 16777216
+    },
+    "Galaxy": {
+      "ConnectionString": "Server=localhost;Database=ZB;Integrated Security=True;TrustServerCertificate=True;Encrypt=False;",
+      "CommandTimeoutSeconds": 60,
+      "DashboardRefreshIntervalSeconds": 30
+    }
+  }
+}
+```
+
+Environment variables use the normal .NET double-underscore form. For example,
+`MxGateway__Sessions__MaxSessions=20` overrides
+`MxGateway:Sessions:MaxSessions`.
+
+## Authentication Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `MxGateway:Authentication:Mode` | `ApiKey` | Selects public gRPC authentication. Supported values are `ApiKey` and `Disabled`. `Disabled` bypasses API-key verification and is for local development only. |
+| `MxGateway:Authentication:SqlitePath` | `C:\ProgramData\MxGateway\gateway-auth.db` | SQLite database path for API-key records and audit rows when API-key authentication is enabled. |
+| `MxGateway:Authentication:PepperSecretName` | `MxGateway:ApiKeyPepper` | Configuration key used to read the HMAC pepper for API-key secret hashing. The dashboard effective configuration redacts this value. |
+| `MxGateway:Authentication:RunMigrationsOnStartup` | `true` | Runs SQLite auth schema migrations at gateway startup when API-key authentication is enabled. |
+
+When `Mode` is `ApiKey`, `SqlitePath` and `PepperSecretName` must be present.
+`SqlitePath` must be a valid filesystem path.
+
+## Worker Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `MxGateway:Worker:ExecutablePath` | `src\MxGateway.Worker\bin\x86\Release\MxGateway.Worker.exe` | Path to the x86 worker executable launched for each gateway session. The path must be valid and point to a `.exe` file. |
+| `MxGateway:Worker:WorkingDirectory` | `null` | Optional working directory for the worker process. When set, it must be a valid filesystem path. |
+| `MxGateway:Worker:RequiredArchitecture` | `X86` | Required Portable Executable architecture for the worker. Supported values are `X86` and `X64`; MXAccess parity uses `X86`. |
+| `MxGateway:Worker:StartupTimeoutSeconds` | `30` | Total startup budget for process launch, startup probe, pipe connect, handshake, and worker readiness. |
+| `MxGateway:Worker:StartupProbeRetryAttempts` | `3` | Number of retry attempts for transient worker startup probe failures before pipe connection and handshake continue. |
+| `MxGateway:Worker:StartupProbeRetryDelayMilliseconds` | `250` | Delay between transient startup probe retry attempts. |
+| `MxGateway:Worker:PipeConnectAttemptTimeoutMilliseconds` | `2000` | Per-attempt timeout used by the worker named-pipe connect retry path. The overall pipe connection still stays under the startup budget. |
+| `MxGateway:Worker:ShutdownTimeoutSeconds` | `10` | Grace period for worker shutdown before the gateway treats shutdown as failed and may kill the worker process tree. |
+| `MxGateway:Worker:HeartbeatIntervalSeconds` | `5` | Worker heartbeat send interval and gateway heartbeat check cadence input. |
+| `MxGateway:Worker:HeartbeatGraceSeconds` | `15` | Maximum age of the last worker heartbeat before the gateway faults the worker. This must be greater than or equal to `HeartbeatIntervalSeconds`. |
+| `MxGateway:Worker:MaxMessageBytes` | `16777216` | Maximum worker IPC frame payload size in bytes. The validator allows values from `1024` through `268435456`. |
+
+`StartupProbeRetryAttempts`, `StartupProbeRetryDelayMilliseconds`,
+`PipeConnectAttemptTimeoutMilliseconds`, timeout values, heartbeat values, and
+`MaxMessageBytes` must be positive. `MaxMessageBytes` is intentionally bounded
+to avoid accidental large allocations from malformed or oversized frames.
+
+## Session Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `MxGateway:Sessions:DefaultCommandTimeoutSeconds` | `30` | Default timeout used while the gateway waits for a worker command reply when an open-session request does not provide a positive command timeout. |
+| `MxGateway:Sessions:MaxSessions` | `64` | Maximum number of concurrently open gateway sessions. Session opens reserve a slot atomically before worker creation. |
+| `MxGateway:Sessions:MaxPendingCommandsPerSession` | `128` | Maximum number of pending worker commands for one session. Excess commands fail fast instead of queueing indefinitely. |
+| `MxGateway:Sessions:DefaultLeaseSeconds` | `1800` | Initial session lease and refresh duration. Unary client activity extends the lease by this duration. |
+| `MxGateway:Sessions:LeaseSweepIntervalSeconds` | `30` | Hosted monitor interval for closing expired leases. Active event-stream subscribers keep a session from expiring while the stream remains attached. |
+| `MxGateway:Sessions:AllowMultipleEventSubscribers` | `false` | Controls whether multiple `StreamEvents` subscribers may attach to one session. `true` is rejected until event fan-out is implemented. |
+
+All numeric session options must be greater than zero. The current event stream
+implementation supports one active subscriber per session; this preserves event
+ordering and avoids competing consumers.
+
+## Event Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `MxGateway:Events:QueueCapacity` | `10000` | Capacity for bounded per-session event queues used by the gateway worker event channel and the public gRPC event stream queue. |
+| `MxGateway:Events:BackpressurePolicy` | `FailFast` | Event backpressure behavior. `FailFast` faults the session on public stream queue overflow. `DisconnectSubscriber` disconnects only the slow stream. |
+
+`QueueCapacity` must be greater than zero. With `FailFast`, queue overflow
+faults the affected worker or session instead of silently dropping MXAccess
+events. With `DisconnectSubscriber`, public gRPC stream overflow terminates only
+the affected stream while the MXAccess session remains active.
+
+## Dashboard Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `MxGateway:Dashboard:Enabled` | `true` | Enables Blazor Server dashboard route mapping. |
+| `MxGateway:Dashboard:PathBase` | `/dashboard` | Base path for dashboard routes. When the dashboard is enabled, this value is required and must start with `/`. |
+| `MxGateway:Dashboard:RequireAdminScope` | `true` | Requires API keys used for dashboard login to carry the `admin` scope. |
+| `MxGateway:Dashboard:AllowAnonymousLocalhost` | `true` | Allows loopback dashboard requests to bypass the dashboard cookie requirement for local development. Remote requests still require dashboard authentication. |
+| `MxGateway:Dashboard:SnapshotIntervalMilliseconds` | `1000` | Dashboard snapshot refresh interval used by realtime Blazor pages. |
+| `MxGateway:Dashboard:RecentFaultLimit` | `100` | Maximum number of fault summaries projected into each dashboard snapshot. |
+| `MxGateway:Dashboard:RecentSessionLimit` | `200` | Maximum number of session summaries projected into each dashboard snapshot. |
+| `MxGateway:Dashboard:ShowTagValues` | `false` | Reserved display control for tag values. The dashboard does not show full tag values by default. |
+
+`SnapshotIntervalMilliseconds` must be greater than zero. `RecentFaultLimit`
+and `RecentSessionLimit` must be greater than or equal to zero.
+
+## Protocol Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `MxGateway:Protocol:WorkerProtocolVersion` | `1` | Worker IPC protocol version expected by the gateway and worker. This must match `GatewayContractInfo.WorkerProtocolVersion`. |
+| `MxGateway:Protocol:MaxGrpcMessageBytes` | `16777216` | Public gRPC max send and receive message size in bytes. The same default is used by official clients. The validator allows values from `1024` through `268435456`. |
+
+The protocol option is exposed for diagnostics and explicit deployment
+configuration, not for compatibility negotiation. A mismatch fails validation
+at startup.
+
+## Galaxy Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `MxGateway:Galaxy:ConnectionString` | `Server=localhost;Database=ZB;Integrated Security=True;TrustServerCertificate=True;Encrypt=False;` | SQL Server connection string for the Galaxy Repository (`ZB`) used by the `GalaxyRepository` browse RPCs. Override in production via `MxGateway__Galaxy__ConnectionString`. |
+| `MxGateway:Galaxy:CommandTimeoutSeconds` | `60` | Per-command SQL timeout for all Galaxy browse RPCs. |
+| `MxGateway:Galaxy:DashboardRefreshIntervalSeconds` | `30` | Interval between background refreshes of the dashboard Galaxy summary cache. SQL is hit at most once per interval regardless of dashboard render rate. |
+
+See [Galaxy Repository Browse](./GalaxyRepository.md) for the RPC surface and
+behavior.
+
+## Related Documentation
+
+- [Gateway Process Detailed Design](./gateway-process-design.md)
+- [Gateway Dashboard Detailed Design](./gateway-dashboard-design.md)
+- [Worker Process Launcher](./WorkerProcessLauncher.md)
+- [Worker Frame Protocol](./WorkerFrameProtocol.md)
+- [Galaxy Repository Browse](./GalaxyRepository.md)

docs/GatewayTesting.md

@@ -74,6 +74,56 @@ The test output includes session id, worker process id, command status,
 HRESULT/status diagnostics, event sequence and handles, close status, and worker
 stdout/stderr lines emitted during the run.
 
+## Client E2E Scripts
+
+`scripts/discover-testmachine-tags.ps1` queries the ZB Galaxy Repository for the
+deployed runtime references used by the live client e2e scripts. It reads
+`TestMachine_001` through `TestMachine_020` and the expected attributes:
+
+- `ProtectedValue`
+- `TestChangingInt`
+- `TestBoolArray`
+- `TestIntArray`
+- `TestDateTimeArray`
+- `TestStringArray`
+
+The discovery output includes the exact `fullTagReference`, data type, array
+dimension, and security classification. The array attributes are expected to be
+dimension 50. `ProtectedValue` has security classification 2 and requires
+secured write semantics; the current client CLI e2e runner subscribes to it but
+does not attempt a normal `Write`.
+
+Run discovery directly when validating the Galaxy Repository inputs:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/discover-testmachine-tags.ps1 -Json
+```
+
+`scripts/run-client-e2e-tests.ps1` drives the .NET, Go, Rust, Python, and Java
+client CLIs through a live gateway session. For each client it opens one
+session, registers, verifies `SubscribeBulk` and `UnsubscribeBulk` on a bounded
+tag subset, adds and advises every discovered test tag, reads a bounded event
+stream, then closes the session in a `finally` path. The script writes a JSON
+report under `artifacts/e2e/`.
+
+Build the gateway and worker, start the gateway, and provide a valid API key
+before running the client e2e script:
+
+```powershell
+$env:MXGATEWAY_API_KEY = "<api-key>"
+powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1
+```
+
+Useful runner options:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1 -Clients dotnet,python -MachineStart 1 -MachineEnd 2
+powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1 -BulkTagCount 10
+powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1 -SkipStream
+powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1 -SkipBulk
+powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1 -Endpoint localhost:5000 -ApiKeyEnv MXGATEWAY_API_KEY
+```
+
 ## Focused Commands
 
 Run the cross-language smoke matrix tests after changing the documented client

docs/Grpc.md

@@ -0,0 +1,241 @@
+# Gateway gRPC Service Layer
+
+The gRPC service layer is the public entry point for client traffic. It is intentionally thin: handlers validate the incoming request, look up or open a session, dispatch to the worker through the session manager, and translate worker replies and events back into public proto types.
+
+## Layer Responsibilities
+
+The architecture rule (from `AGENTS.md`) is that the gRPC layer must "validate request, find session, call the session worker client, map worker replies to public replies, and stream events". Anything else — caching, retries, worker process lifetime, event ordering — lives behind `ISessionManager` and the worker client. Keeping the layer thin lets the same session/worker code be reused by future transports (for example, an in-process host or an alternate IPC) without having to re-derive validation or mapping rules.
+
+The layer is composed of four collaborators:
+
+| Type | Lifetime | Role |
+|------|----------|------|
+| `MxAccessGatewayService` | scoped (gRPC) | Implements the four `MxAccessGateway` RPCs, performs exception mapping. |
+| `MxAccessGrpcRequestValidator` | singleton | Rejects malformed requests before any session work runs. |
+| `MxAccessGrpcMapper` | singleton | Converts public proto types to internal `WorkerCommand`/`WorkerEvent` types and back. |
+| `IEventStreamService` (`EventStreamService`) | singleton | Owns the event stream pipeline, including bounded queue and backpressure handling. |
+
+Registration happens in `GatewayApplication`:
+
+```csharp
+builder.Services.AddSingleton<MxAccessGrpcMapper>();
+builder.Services.AddSingleton<MxAccessGrpcRequestValidator>();
+builder.Services.AddSingleton<IEventStreamService, EventStreamService>();
+```
+
+The service itself is mapped as a normal gRPC endpoint via `endpoints.MapGrpcService<MxAccessGatewayService>()`.
+
+A second gRPC service, `GalaxyRepositoryGrpcService`, is mapped alongside it. It exposes the read-only Galaxy Repository browse surface and is documented separately in [Galaxy Repository Browse](./GalaxyRepository.md). It shares the authorization interceptor and authentication policy used by `MxAccessGatewayService`, but it does not go through the session manager or worker — it talks to SQL Server directly.
+
+## RPC Handlers
+
+`MxAccessGatewayService` derives from the generated `MxAccessGateway.MxAccessGatewayBase` and implements every RPC declared in `mxaccess_gateway.proto`. The proto contract itself is documented in [Contracts](./Contracts.md); this section covers only what the server-side handler does on top of that contract.
+
+Public gRPC send and receive message sizes are configured from
+`MxGateway:Protocol:MaxGrpcMessageBytes` (default 16 MiB). Official clients use
+the same default so paged Galaxy browse replies and larger MXAccess payloads
+fail consistently instead of depending on language-specific gRPC defaults.
+
+### `OpenSession`
+
+`OpenSession` validates the request, asks `ISessionManager` to open a session under the caller's identity, and returns a reply that advertises both protocol versions and the capabilities the gateway supports. Capability strings are static because the gateway has a fixed feature set per build; clients use them as a forward-compatibility hint rather than runtime negotiation.
+
+```csharp
+GatewaySession session = await sessionManager
+    .OpenSessionAsync(
+        SessionOpenRequest.FromContract(request),
+        ResolveClientIdentity(),
+        context.CancellationToken)
+    .ConfigureAwait(false);
+
+OpenSessionReply reply = new()
+{
+    SessionId = session.SessionId,
+    BackendName = session.BackendName,
+    WorkerProcessId = session.WorkerProcessId ?? 0,
+    WorkerProtocolVersion = GatewayContractInfo.WorkerProtocolVersion,
+    GatewayProtocolVersion = GatewayContractInfo.GatewayProtocolVersion,
+    DefaultCommandTimeout = Google.Protobuf.WellKnownTypes.Duration.FromTimeSpan(session.CommandTimeout),
+    ProtocolStatus = MxAccessGrpcMapper.Ok(),
+};
+```
+
+`ResolveClientIdentity()` reads `IGatewayRequestIdentityAccessor.Current` and prefers `DisplayName`, falling back to `KeyId`. The accessor is populated by the authorization interceptor before the handler runs (see [Authorization](./Authorization.md)).
+
+### `CloseSession`
+
+The handler delegates to `sessionManager.CloseSessionAsync` and converts the resulting `SessionCloseResult` into a `CloseSessionReply`. The handler distinguishes the two outcomes via the protocol status message — `"Session was already closed."` versus `"Session closed."` — so callers do not need to reason about idempotency from a status code alone.
+
+### `Invoke`
+
+`Invoke` is the unary command path. It runs the validator (which enforces payload-vs-kind matching), uses the mapper to wrap the public `MxCommand` in a `WorkerCommand` with an enqueue timestamp, calls `sessionManager.InvokeAsync`, and unwraps the worker reply.
+
+```csharp
+requestValidator.ValidateInvoke(request);
+WorkerCommand workerCommand = mapper.MapCommand(request);
+WorkerCommandReply workerReply = await sessionManager
+    .InvokeAsync(request.SessionId, workerCommand, context.CancellationToken)
+    .ConfigureAwait(false);
+
+return mapper.MapCommandReply(workerReply);
+```
+
+Carrying the enqueue timestamp into the worker layer is what lets queue-wait time be measured separately from worker-side execution time when troubleshooting timeouts.
+
+### `StreamEvents`
+
+`StreamEvents` is a server-streaming RPC. The handler delegates the full pipeline to `IEventStreamService` and just forwards each `MxEvent` onto the response stream. Keeping the channel and producer/consumer machinery out of the handler means cancellation, exception mapping, and metric bookkeeping live in one place.
+
+## Validation Rules
+
+`MxAccessGrpcRequestValidator` rejects requests with `StatusCode.InvalidArgument` before any session work happens. The rules are intentionally narrow — anything that requires session state (for example, "session does not exist") is left for `ISessionManager` so the validator can stay synchronous and side-effect free.
+
+| RPC | Rule | Status |
+|-----|------|--------|
+| `OpenSession` | `command_timeout`, when set, must be `> 0`. | `InvalidArgument` |
+| `CloseSession` | `session_id` must be non-empty. | `InvalidArgument` |
+| `StreamEvents` | `session_id` must be non-empty. | `InvalidArgument` |
+| `Invoke` | `session_id` non-empty, `command` present, `kind` not `Unspecified`, payload oneof must match `kind`. | `InvalidArgument` |
+
+The payload-vs-kind check matters because the `MxCommand.payload` oneof is non-discriminated on the wire — a misaligned client could send `kind = Write` with a `Register` payload and silently confuse the worker. The validator turns that into a clear client error:
+
+```csharp
+private static void ValidateCommandPayload(MxCommand command)
+{
+    MxCommand.PayloadOneofCase expectedPayload = ExpectedPayload(command.Kind);
+    if (command.PayloadCase != expectedPayload)
+    {
+        throw InvalidArgument(
+            $"Command kind {command.Kind} requires payload {expectedPayload} but received {command.PayloadCase}.");
+    }
+}
+```
+
+`ExpectedPayload` enumerates every `MxCommandKind` that has a matching payload case; unknown kinds map to `PayloadOneofCase.None`, which forces a mismatch and therefore a rejection.
+
+## Mapping Rules
+
+`MxAccessGrpcMapper` is the only place that translates between public proto types and internal worker types. Two design choices are worth calling out.
+
+The mapper clones the inbound `MxCommand` rather than reusing the reference. This isolates the worker pipeline from any later mutation of the request graph by the gRPC framework or interceptors:
+
+```csharp
+public WorkerCommand MapCommand(MxCommandRequest request)
+{
+    ArgumentNullException.ThrowIfNull(request);
+    ArgumentNullException.ThrowIfNull(request.Command);
+
+    return new WorkerCommand
+    {
+        Command = request.Command.Clone(),
+        EnqueueTimestamp = Timestamp.FromDateTimeOffset(_timeProvider.GetUtcNow()),
+    };
+}
+```
+
+When the worker reply or event payload is missing, the mapper returns a synthetic public message with `ProtocolStatusCode.ProtocolViolation` (for replies) or a sentinel `MxEvent` with `MxEventFamily.Unspecified` (for events). The gateway never relays a partial frame to clients — anything missing is reported as a protocol violation against the worker, not a transport error against the client.
+
+The mapper also exposes static factory methods for every `ProtocolStatusCode` (`Ok`, `InvalidRequest`, `SessionNotFound`, `SessionNotReady`, `WorkerUnavailable`, `Timeout`, `Canceled`, `ProtocolViolation`) so that handlers and tests can produce status payloads without duplicating the enum-to-string mapping.
+
+## Exception to Status Mapping
+
+Every handler wraps its body in `try { ... } catch (Exception exception) when (exception is not RpcException) { throw MapException(exception); }`. `RpcException` is allowed to propagate untouched (the validator already produces them with the right code). All other exceptions are translated by `MapException`, which knows three categories:
+
+- `OperationCanceledException` becomes `StatusCode.Cancelled`.
+- `SessionManagerException` is mapped by its `ErrorCode`.
+- `WorkerClientException` is mapped by its `ErrorCode`.
+
+Anything else is logged at warning and surfaced as `Unavailable` with a generic message — clients see a retryable status, and the unexpected exception is captured in gateway logs rather than leaked over the wire.
+
+```csharp
+StatusCode statusCode = exception.ErrorCode switch
+{
+    SessionManagerErrorCode.SessionNotFound => StatusCode.NotFound,
+    SessionManagerErrorCode.SessionNotReady => StatusCode.FailedPrecondition,
+    SessionManagerErrorCode.EventSubscriberAlreadyActive => StatusCode.ResourceExhausted,
+    SessionManagerErrorCode.EventQueueOverflow => StatusCode.ResourceExhausted,
+    SessionManagerErrorCode.SessionLimitExceeded => StatusCode.ResourceExhausted,
+    SessionManagerErrorCode.OpenFailed => StatusCode.Unavailable,
+    SessionManagerErrorCode.CloseFailed => StatusCode.Unavailable,
+    _ => StatusCode.Unavailable,
+};
+```
+
+`WorkerClientException` follows the same pattern: `CommandTimeout` becomes `DeadlineExceeded`, `GatewayShutdown` becomes `Cancelled`, `InvalidState` becomes `FailedPrecondition`, `ProtocolViolation` becomes `Internal`, and unmapped codes fall through to `Unavailable`.
+
+## Event Streaming Model
+
+`EventStreamService` implements the `StreamEvents` pipeline. It exists as a separate service (rather than living inside `MxAccessGatewayService`) so that the channel, backpressure policy, and metric bookkeeping can be unit-tested without spinning up a Kestrel host.
+
+The pipeline has three stages:
+
+1. The session is resolved via `sessionManager.TryGetSession`. A miss raises `SessionManagerException(SessionNotFound)` so the handler reports `StatusCode.NotFound`.
+2. `session.AttachEventSubscriber(...)` enforces the single-subscriber-per-session rule (or allows multiple subscribers if `Sessions:AllowMultipleEventSubscribers` is enabled). The returned `IDisposable` is released in the `finally` block, ensuring the subscriber slot is freed even when the client cancels mid-stream.
+3. A `Channel<MxEvent>` decouples the worker-side producer from the gRPC writer. The channel is bounded by `Events:QueueCapacity` and configured for a single reader and writer:
+
+```csharp
+Channel<MxEvent> eventQueue = Channel.CreateBounded<MxEvent>(
+    new BoundedChannelOptions(options.Value.Events.QueueCapacity)
+    {
+        SingleReader = true,
+        SingleWriter = true,
+        FullMode = BoundedChannelFullMode.Wait,
+        AllowSynchronousContinuations = false,
+    });
+```
+
+The producer reads `WorkerEvent`s from the session, maps them, and writes to the channel. Per-session ordering is preserved end-to-end: events arrive from the worker in `WorkerSequence` order, the producer is the single writer, and the consumer drains FIFO. The producer also honours the request's `AfterWorkerSequence` cursor by skipping any event whose `WorkerSequence` is at or before the requested cutoff, which lets clients resume after a disconnect without server-side replay state.
+
+### Backpressure
+
+When `TryWrite` fails the queue is full. The handling depends on `Events:BackpressurePolicy`:
+
+```csharp
+if (!writer.TryWrite(publicEvent))
+{
+    string message = $"Session {session.SessionId} event stream queue overflowed.";
+    metrics.QueueOverflow("grpc-event-stream");
+    if (options.Value.Events.BackpressurePolicy == EventBackpressurePolicy.FailFast)
+    {
+        session.MarkFaulted(message);
+        metrics.Fault(SessionManagerErrorCode.EventQueueOverflow.ToString());
+    }
+    else
+    {
+        logger.LogDebug(
+            "Disconnecting event stream for session {SessionId} after queue overflow.",
+            session.SessionId);
+    }
+
+    writer.TryComplete(new SessionManagerException(
+        SessionManagerErrorCode.EventQueueOverflow,
+        message));
+    return;
+}
+```
+
+Under `FailFast` the session is faulted so subsequent commands return `FailedPrecondition`; the client must reopen. Under the default policy only the stream is dropped and the session continues to accept commands, leaving recovery to the client (typically a fresh `StreamEvents` call with an updated `AfterWorkerSequence`). Either way, the consumer side observes `StatusCode.ResourceExhausted` via the `EventQueueOverflow` mapping above.
+
+### Cancellation and Cleanup
+
+The handler creates a linked cancellation token (`streamCts`) so that completing the consumer (client disconnect, error, or graceful end-of-stream) also cancels the producer. The `finally` block cancels the source, disposes the subscriber slot, awaits the producer (swallowing the expected cancellation), and emits `StreamDisconnected("Detached")` so dashboards see the disconnection regardless of cause.
+
+`WorkerClientException` thrown by the producer marks the session as faulted before completing the channel — the worker is presumed gone, and any subsequent command on that session must observe the fault rather than silently retry.
+
+## Authorization Interceptor Integration
+
+Authorization is applied as a gRPC interceptor, registered in `GrpcAuthorizationServiceCollectionExtensions`:
+
+```csharp
+services.AddSingleton<GatewayGrpcAuthorizationInterceptor>();
+services.AddGrpc(options => options.Interceptors.Add<GatewayGrpcAuthorizationInterceptor>());
+```
+
+Because the interceptor runs before any handler, `MxAccessGatewayService` can safely assume the call has been authorized and that `IGatewayRequestIdentityAccessor.Current` is populated. The handler's only responsibility is to read the identity for `OpenSession` so the session is owned by the authenticated principal; it does not perform any authorization checks of its own. See [Authorization](./Authorization.md) for the policy and identity model.
+
+## Related Documentation
+
+- [Contracts](./Contracts.md)
+- [Sessions](./Sessions.md)
+- [Authorization](./Authorization.md)
+- [Gateway Process Design](./gateway-process-design.md)

docs/Metrics.md

@@ -0,0 +1,210 @@
+# Gateway Metrics
+
+The metrics subsystem exposes counters, histograms, and observable gauges that describe gateway throughput, queue health, and worker lifecycle. Both the `System.Diagnostics.Metrics` pipeline and the in-memory `GatewayMetricsSnapshot` consume the same underlying state, so external collectors and the dashboard see consistent numbers.
+
+## Overview
+
+`GatewayMetrics` is a singleton (registered in `GatewayApplication.cs`) that owns a single `Meter` named `MxGateway.Server` and a set of synchronised counters, histograms, and observable gauges. Subsystems call typed mutator methods (`SessionOpened`, `CommandFailed`, `EventReceived`, etc.) rather than touching the `Meter` directly, which keeps the OpenTelemetry instrument names and tag conventions in one place. A `lock (_syncRoot)` block guards the scalar fields used by `GetSnapshot`, while per-event maps use `ConcurrentDictionary<string, long>` so the hot event path avoids the lock.
+
+## Meter and OpenTelemetry Compatibility
+
+The meter name is exposed as a constant so that hosting code can register it with an OpenTelemetry exporter:
+
+```csharp
+public sealed class GatewayMetrics : IDisposable
+{
+    public const string MeterName = "MxGateway.Server";
+
+    public GatewayMetrics()
+    {
+        _meter = new Meter(MeterName, typeof(GatewayMetrics).Assembly.GetName().Version?.ToString());
+        _sessionsOpenedCounter = _meter.CreateCounter<long>("mxgateway.sessions.opened");
+        ...
+    }
+}
+```
+
+The meter version is the gateway assembly version, which gives exporters a stable identifier per build. All instrument names use the dotted `mxgateway.<area>.<event>` convention so they group cleanly under a single namespace in tools such as Prometheus, OTLP collectors, or `dotnet-counters`.
+
+## Instrument Inventory
+
+### Counters
+
+All counters are `Counter<long>`. Tag values come from the call sites listed under [Recording Sites](#recording-sites).
+
+| Instrument | Tags | What it measures |
+|------------|------|------------------|
+| `mxgateway.sessions.opened` | none | Successful `SessionManager.OpenSession` completions. |
+| `mxgateway.sessions.closed` | none | Sessions closed cleanly via `SessionManager`. |
+| `mxgateway.commands.started` | `method` | Command dispatches initiated by `WorkerClient`. |
+| `mxgateway.commands.succeeded` | `method` | Commands acknowledged with success by the worker. |
+| `mxgateway.commands.failed` | `method`, `category` | Command failures, where `category` is the `WorkerClientErrorCode` or exception type name. |
+| `mxgateway.events.received` | `family` | Worker events accepted into the event pipeline. |
+| `mxgateway.queues.overflows` | `queue` | Drops when a bounded queue rejects a message (e.g. `grpc-event-stream`). |
+| `mxgateway.faults` | `category` | Faults reported by session, event, or worker code paths. The category is a `SessionManagerErrorCode` or `WorkerClientErrorCode` name. |
+| `mxgateway.workers.killed` | `reason` | Forced terminations of worker processes. |
+| `mxgateway.workers.exited` | `reason` | Clean or fault-driven worker exits. |
+| `mxgateway.heartbeats.failed` | `session_id` | Worker heartbeat misses tracked per session. |
+| `mxgateway.grpc.streams.disconnected` | `reason` | Detachments of the dashboard or client gRPC event stream. |
+| `mxgateway.retries.attempted` | `area` | Resilience retries executed by gateway components. |
+
+### Histograms
+
+Histograms record durations in milliseconds (the `unit` argument on `CreateHistogram`):
+
+```csharp
+_workerStartupLatencyHistogram = _meter.CreateHistogram<double>("mxgateway.workers.startup.duration", "ms");
+_commandLatencyHistogram = _meter.CreateHistogram<double>("mxgateway.commands.duration", "ms");
+_eventStreamSendLatencyHistogram = _meter.CreateHistogram<double>("mxgateway.events.stream_send.duration", "ms");
+```
+
+| Instrument | Tags | What it measures |
+|------------|------|------------------|
+| `mxgateway.workers.startup.duration` | none | Time from `WorkerClient` launch to worker-ready. |
+| `mxgateway.commands.duration` | `method`, optional `category` | Command round-trip time. The `category` tag is added on failure so success and failure latencies stay distinguishable. |
+| `mxgateway.events.stream_send.duration` | `family` | Time spent writing each public event to the gRPC response stream in `MxAccessGatewayService.StreamEvents`. |
+
+### Observable Gauges
+
+Observable gauges are pull-based; the `Meter` invokes the supplied callback whenever a listener samples it. Each callback re-acquires `_syncRoot` so the gauge value matches the snapshot taken at the same instant.
+
+| Instrument | Source field | Description |
+|------------|--------------|-------------|
+| `mxgateway.sessions.open` | `_openSessions` | Currently open sessions tracked by `SessionManager`. |
+| `mxgateway.workers.running` | `_workersRunning` | Worker clients in a running state. |
+| `mxgateway.events.worker_queue.depth` | `_workerEventQueueDepth` | Last reported depth of the worker-side event queue. |
+| `mxgateway.events.grpc_stream_queue.depth` | `_grpcEventStreamQueueDepth` | Backlog held by `EventStreamService` for the active gRPC stream consumer. |
+
+## Snapshot Shape
+
+`GatewayMetricsSnapshot` is the immutable view of the same state, returned by `GatewayMetrics.GetSnapshot()` while holding `_syncRoot`. The dictionaries are copied so the caller can iterate without further synchronisation. The dashboard service is the primary consumer.
+
+```csharp
+public sealed record GatewayMetricsSnapshot(
+    int OpenSessions,
+    int WorkersRunning,
+    int WorkerEventQueueDepth,
+    int GrpcEventStreamQueueDepth,
+    long SessionsOpened,
+    long SessionsClosed,
+    long CommandsStarted,
+    long CommandsSucceeded,
+    long CommandsFailed,
+    long EventsReceived,
+    long QueueOverflows,
+    long Faults,
+    long WorkerKills,
+    long WorkerExits,
+    long HeartbeatFailures,
+    long StreamDisconnects,
+    long RetryAttempts,
+    IReadOnlyDictionary<string, long> CommandFailuresByMethod,
+    IReadOnlyDictionary<string, long> EventsByFamily,
+    IReadOnlyDictionary<string, long> EventsBySession,
+    IReadOnlyDictionary<string, long> RetryAttemptsByArea);
+```
+
+The scalar fields mirror the counters and gauges. The four dictionaries provide the breakdowns that counter tags would otherwise require an exporter to aggregate:
+
+- `CommandFailuresByMethod` keys by gRPC method name.
+- `EventsByFamily` keys by event family (the `Family` enum on a worker event).
+- `EventsBySession` keys by `sessionId`; entries are removed via `RemoveSessionEvents` when a session closes so the map does not grow without bound.
+- `RetryAttemptsByArea` keys by the resilience `area` tag, e.g. `worker_startup`.
+
+`EventsReceived` is read with `Interlocked.Read(ref _eventsReceived)` because `EventReceived` increments it via `Interlocked.Increment` outside the lock to keep the event-ingestion path non-blocking.
+
+## Recording Sites
+
+The recording call sites describe the code paths that write into each instrument. This mapping makes it easier to trace an unexpected counter reading back to a subsystem.
+
+### Session manager
+
+`Sessions/SessionManager.cs` emits session lifecycle and fault counters:
+
+```csharp
+_metrics.SessionOpened();
+...
+_metrics.Fault(SessionManagerErrorCode.OpenFailed.ToString());
+...
+_metrics.SessionClosed();
+...
+_metrics.SessionRemoved();
+...
+_metrics.Fault(SessionManagerErrorCode.CloseFailed.ToString());
+...
+_metrics.RemoveSessionEvents(session.SessionId);
+```
+
+`SessionRemoved` decrements the open-session gauge without incrementing the closed counter, which covers cases where a session is evicted rather than closed by the client.
+
+### Worker client
+
+`Workers/WorkerClient.cs` records command throughput, worker lifecycle, heartbeat failures, and the worker-side event queue depth:
+
+- `CommandStarted(method)` and `CommandSucceeded(method, duration)` / `CommandFailed(method, category, duration)` around the worker request/response pair.
+- `WorkerStarted(startupDuration)` once the worker reports ready.
+- `RecordWorkerStoppedOnce` calls `WorkerStopped(reason)` exactly once per worker, guarding against double-counting on simultaneous fault and exit signals.
+- `WorkerKilled(reason)` when the client forcibly terminates the worker.
+- `HeartbeatFailed(SessionId)` per missed heartbeat.
+- `SetWorkerEventQueueDepth(queueDepth)` after each event ingest.
+- `EventReceived(SessionId, workerEvent.Event.Family.ToString())` for each worker event.
+
+### Worker process launcher
+
+`Workers/WorkerProcessLauncher.cs` records process-level kills and startup retries:
+
+```csharp
+_metrics.WorkerKilled(reason);
+...
+_metrics.RetryAttempted("worker_startup");
+```
+
+The `worker_startup` tag is hard-coded so the `RetryAttemptsByArea` snapshot reports launcher retries distinctly from other resilience areas.
+
+### Session worker client factory
+
+`Sessions/SessionWorkerClientFactory.cs` records the worker kill that follows a failed `OpenSession` handshake:
+
+```csharp
+_metrics.WorkerKilled("OpenSessionFailed");
+```
+
+This is the only fault path where the factory itself owns the kill decision; once the worker is bound to a session, the `WorkerClient` becomes responsible for lifecycle metrics.
+
+### gRPC event stream service
+
+`Grpc/EventStreamService.cs` records the dashboard/client event-stream backlog and disconnect counters:
+
+```csharp
+metrics.AdjustGrpcEventStreamQueueDepth(1);
+...
+metrics.AdjustGrpcEventStreamQueueDepth(-1);
+...
+metrics.AdjustGrpcEventStreamQueueDepth(-remainingDepth);
+metrics.StreamDisconnected("Detached");
+...
+metrics.QueueOverflow("grpc-event-stream");
+metrics.Fault(SessionManagerErrorCode.EventQueueOverflow.ToString());
+...
+metrics.Fault(WorkerClientErrorCode.WorkerFaulted.ToString());
+```
+
+The service tracks per-message enqueues and dequeues, so `AdjustGrpcEventStreamQueueDepth` updates the aggregate stream backlog. The `Math.Max(0, ...)` clamp inside the adjuster prevents a negative depth if the bookkeeping ever drifts.
+
+`Grpc/MxAccessGatewayService.cs` records gRPC event send latency around each response-stream write:
+
+```csharp
+Stopwatch stopwatch = Stopwatch.StartNew();
+await responseStream.WriteAsync(publicEvent).ConfigureAwait(false);
+metrics.RecordEventStreamSend(publicEvent.Family.ToString(), stopwatch.Elapsed);
+```
+
+## Dashboard Consumption
+
+`Dashboard/DashboardSnapshotService.cs` calls `_metrics.GetSnapshot()` once per `GetSnapshot` invocation and projects it into the dashboard transport types together with the session registry view. The dashboard receives a single, internally consistent snapshot per tick rather than reading individual counters at separate times. See [Gateway Dashboard Design](./gateway-dashboard-design.md) and [Dashboard Interface Design](./DashboardInterfaceDesign.md) for the projection rules and wire format.
+
+## Related Documentation
+
+- [Gateway Dashboard Design](./gateway-dashboard-design.md)
+- [Dashboard Interface Design](./DashboardInterfaceDesign.md)
+- [Sessions](./Sessions.md)

docs/Sessions.md

@@ -0,0 +1,271 @@
+# Gateway Sessions
+
+The sessions subsystem owns the in-memory representation of an active gateway-to-worker pairing and coordinates its lifecycle from open through close. Each `GatewaySession` corresponds to exactly one MXAccess worker process connected over a dedicated named pipe.
+
+## Overview
+
+A session is the gateway-side handle that callers use to invoke worker commands, stream worker events, and tear the worker down. The subsystem is split between the per-session state machine (`GatewaySession`), an in-memory directory (`SessionRegistry`), the orchestrator that opens and closes sessions (`SessionManager`), the worker construction step (`SessionWorkerClientFactory`), and a hosted service that drains sessions during host shutdown (`SessionShutdownHostedService`).
+
+All four interfaces (`ISessionManager`, `ISessionRegistry`, `ISessionWorkerClientFactory`) plus `SessionShutdownHostedService` are wired as singletons by `SessionServiceCollectionExtensions.AddGatewaySessions`.
+
+## Key Types
+
+### GatewaySession
+
+`GatewaySession` is a sealed class that holds the identity, configured timeouts, worker client reference, and current `SessionState` for one session. State is protected by a private `_syncRoot` lock so that property reads and transitions are observed atomically by concurrent gRPC calls and the lease sweeper.
+
+The session id is an opaque string in the form `session-{guid:N}` and the per-session pipe name is `mxaccess-gateway-{ProcessId}-{SessionId}`. Encoding the gateway PID into the pipe name avoids collisions when an old gateway process leaks pipes that the OS has not yet reclaimed.
+
+`SessionState` itself is the protobuf-generated enum from `MxGateway.Contracts.Proto`, so it is shared between the gateway and clients on the wire.
+
+```csharp
+public void TransitionTo(SessionState nextState)
+{
+    lock (_syncRoot)
+    {
+        if (_state is SessionState.Closed)
+        {
+            return;
+        }
+
+        if (_state is SessionState.Faulted && nextState is not SessionState.Closed)
+        {
+            return;
+        }
+
+        _state = nextState;
+    }
+}
+```
+
+`Closed` is terminal and `Faulted` only allows a transition to `Closed`. This guards against late callbacks (worker exit, heartbeat timeout) re-animating a session that is already torn down.
+
+### SessionManager (ISessionManager)
+
+`SessionManager` is the orchestrator. It exposes `OpenSessionAsync`, `TryGetSession`, `InvokeAsync`, `ReadEventsAsync`, `CloseSessionAsync`, `CloseExpiredLeasesAsync`, and `ShutdownAsync`. It composes `ISessionRegistry`, `ISessionWorkerClientFactory`, `GatewayMetrics`, and `GatewayOptions`.
+
+Concurrency is bounded by a `SemaphoreSlim` initialized to `GatewayOptions.Sessions.MaxSessions`. Open requests that exceed the bound throw `SessionManagerException` with `SessionLimitExceeded` rather than queuing; the caller is expected to retry.
+
+```csharp
+private void EnsureSessionCapacity()
+{
+    if (!_sessionSlots.Wait(0))
+    {
+        throw new SessionManagerException(
+            SessionManagerErrorCode.SessionLimitExceeded,
+            $"Gateway session limit {_options.Sessions.MaxSessions} has been reached.");
+    }
+}
+```
+
+`SessionManager` also defines three close-reason constants — `DefaultCloseReason` (`"client-close"`), `GatewayShutdownReason` (`"gateway-shutdown"`), and `LeaseExpiredReason` (`"lease-expired"`) — so that the metrics and worker shutdown paths agree on a fixed vocabulary.
+
+### SessionRegistry (ISessionRegistry)
+
+`SessionRegistry` is a thin wrapper over a `ConcurrentDictionary<string, GatewaySession>` keyed by session id with `StringComparer.Ordinal`. `Snapshot` materializes the values into an array so iteration callers (lease sweeper, shutdown) do not race with concurrent `TryAdd` and `TryRemove` calls.
+
+`ActiveCount` filters out sessions whose state is `Closed`; this is consumed by metrics and the dashboard, where `Count` would otherwise momentarily over-report during teardown.
+
+### SessionWorkerClientFactory (ISessionWorkerClientFactory)
+
+`SessionWorkerClientFactory.CreateAsync` is the only path that builds an `IWorkerClient`. It drives the session through the protobuf `SessionState` substates in order: `StartingWorker`, `WaitingForPipe`, `Handshaking`, `InitializingWorker`. The substates are wire-visible so the dashboard and clients can render startup progress.
+
+A linked `CancellationTokenSource` enforces `session.StartupTimeout`. If startup fails or times out, the factory either kills the partially-constructed `WorkerClient` or, if the client was never built, kills the launched process and disposes the named pipe before rethrowing. A pure timeout is rewritten as `TimeoutException` so callers can distinguish it from caller-driven cancellation:
+
+```csharp
+if (exception is OperationCanceledException
+    && startupCancellation.IsCancellationRequested
+    && !cancellationToken.IsCancellationRequested)
+{
+    throw new TimeoutException(
+        $"Worker session {session.SessionId} did not complete startup within {session.StartupTimeout}.",
+        exception);
+}
+```
+
+The named pipe is created with `maxNumberOfServerInstances: 1` so a second worker cannot connect to the same pipe name even if the first launch is still pending. Combined with the per-session nonce passed to the worker, this is the gateway's defense against a foreign process answering a pipe.
+
+### SessionShutdownHostedService
+
+`SessionShutdownHostedService` is an `IHostedService` whose only job is to call `ISessionManager.ShutdownAsync` from `StopAsync`. It catches `OperationCanceledException` triggered by the host shutdown timeout and logs a warning so that an over-running shutdown does not surface as an unhandled exception.
+
+### SessionOpenRequest
+
+`SessionOpenRequest` is the gateway-internal record passed to `OpenSessionAsync`. It is constructed from the wire-level `OpenSessionRequest` via `SessionOpenRequest.FromContract`. Keeping a separate internal record means the gRPC layer can normalize input (defaulting backend, sanitizing strings) without leaking generated proto types into `SessionManager`.
+
+```csharp
+public sealed record SessionOpenRequest(
+    string? RequestedBackend,
+    string? ClientSessionName,
+    string? ClientCorrelationId,
+    Duration? CommandTimeout)
+{
+    public static SessionOpenRequest FromContract(OpenSessionRequest request)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+
+        return new SessionOpenRequest(
+            request.RequestedBackend,
+            request.ClientSessionName,
+            request.ClientCorrelationId,
+            request.CommandTimeout);
+    }
+}
+```
+
+### SessionCloseResult
+
+`SessionCloseResult` is the record returned from a successful close. `AlreadyClosed` distinguishes "this call closed the session" from "the session was already closed when we acquired the close lock", which the metrics layer uses to avoid double-counting.
+
+```csharp
+public sealed record SessionCloseResult(
+    string SessionId,
+    SessionState FinalState,
+    bool AlreadyClosed);
+```
+
+### SessionCloseStartedException
+
+`SessionCloseStartedException` is `internal` and is only thrown from inside `GatewaySession.CloseAsync` when the close path has already begun mutating worker state and a subsequent step fails. `SessionManager.CloseSessionCoreAsync` catches it, marks the session faulted, increments the close-failed metric, removes the session from the registry, and rethrows it wrapped as `SessionManagerException` with `CloseFailed`. The intermediate type exists so the public API surface only ever exposes `SessionManagerException`.
+
+### SessionManagerException and SessionManagerErrorCode
+
+`SessionManagerException` is the single public error type emitted from this subsystem; the code is carried in the `ErrorCode` property and is also surfaced to metrics tags via `SessionManagerErrorCode.ToString()`.
+
+| Code | Meaning |
+|------|---------|
+| `SessionNotFound` | The session id is not in the registry. |
+| `SessionNotReady` | The session or its `IWorkerClient` is not in `Ready` state. |
+| `EventSubscriberAlreadyActive` | A second event subscriber attached when only one is allowed. |
+| `EventQueueOverflow` | Reserved for the worker event channel overflow path. |
+| `SessionLimitExceeded` | `MaxSessions` is in use. |
+| `OpenFailed` | `OpenSessionAsync` failed; the inner exception carries the cause. |
+| `CloseFailed` | A close started but did not complete cleanly; the session is removed and faulted. |
+
+## Lifecycle
+
+### Open
+
+`SessionManager.OpenSessionAsync` allocates a session slot, builds the `GatewaySession`, registers it, and asks the factory to bring up the worker. Failures roll back every preceding step:
+
+```csharp
+catch (Exception exception)
+{
+    session?.MarkFaulted(exception.Message);
+    if (session is not null)
+    {
+        _registry.TryRemove(session.SessionId, out _);
+        await session.DisposeAsync().ConfigureAwait(false);
+    }
+
+    ReleaseSessionSlot();
+    _metrics.Fault(SessionManagerErrorCode.OpenFailed.ToString());
+    _logger.LogWarning(
+        exception,
+        "Failed to open gateway session {SessionId}.",
+        session?.SessionId ?? "<not-created>");
+
+    throw new SessionManagerException(
+        SessionManagerErrorCode.OpenFailed,
+        session is null ? "Failed to create session." : $"Failed to open session {session.SessionId}.",
+        exception);
+}
+```
+
+The order — fault, deregister, dispose, release slot, record metric, log, rethrow — matters because releasing the semaphore before disposal would let the next open race the worker process tear-down on the same machine.
+
+### Run
+
+While `Ready`, callers reach the worker through `SessionManager.InvokeAsync` or `ReadEventsAsync`. Both delegate to `GatewaySession`, which checks the state under lock and updates `LastClientActivityAt` on every invocation. `GatewaySession` also exposes typed bulk helpers (`AddItemBulkAsync`, `SubscribeBulkAsync`, etc.) that wrap `WorkerCommand` round-trips and translate non-`Ok` `ProtocolStatus` replies into `SessionManagerException` with `SessionNotReady`.
+
+Event streaming uses `AttachEventSubscriber` which returns a disposable lease. When `allowMultipleSubscribers` is false the second attach throws `EventSubscriberAlreadyActive`; this prevents two gRPC streams from racing on the same worker event channel. Active event subscribers keep the session lease from expiring until the stream is disposed.
+
+Sessions open with `MxGateway:Sessions:DefaultLeaseSeconds` (default 1800) added to the open timestamp. Unary client activity refreshes the lease by the same duration. `ExtendLease` and `IsLeaseExpired` cooperate with `SessionManager.CloseExpiredLeasesAsync`, which iterates a registry snapshot and closes any session whose lease has expired with `LeaseExpiredReason`. `SessionLeaseMonitorHostedService` runs that sweep every `MxGateway:Sessions:LeaseSweepIntervalSeconds` seconds (default 30).
+
+### Close
+
+`GatewaySession.CloseAsync` is serialized by a per-session `SemaphoreSlim` (`_closeLock`). It transitions to `Closing`, asks the worker client to shut down within `ShutdownTimeout`, and on success transitions to `Closed`. If `WorkerClient.ShutdownAsync` throws, the session falls back to `IWorkerClient.Kill` (forced close):
+
+```csharp
+if (_workerClient is not null)
+{
+    try
+    {
+        await _workerClient.ShutdownAsync(ShutdownTimeout, cancellationToken).ConfigureAwait(false);
+    }
+    catch (Exception exception)
+    {
+        try
+        {
+            _workerClient.Kill(reason);
+        }
+        catch (Exception killException)
+        {
+            throw new SessionCloseStartedException(
+                $"Session {SessionId} close failed after worker shutdown started.",
+                new AggregateException(exception, killException));
+        }
+
+        throw;
+    }
+}
+```
+
+If both graceful shutdown and the kill fall-back fail, the original and kill exceptions are bundled into an `AggregateException` and surfaced as `SessionCloseStartedException`. `SessionManager.CloseSessionCoreAsync` then translates that into a `SessionManagerException` with `CloseFailed` and removes the session.
+
+`GatewaySession.KillWorker` is the unconditional forced-close path used by shutdown when graceful close itself throws.
+
+## Shutdown Coordination
+
+`SessionShutdownHostedService.StopAsync` calls `SessionManager.ShutdownAsync`, which closes every registered session with `GatewayShutdownReason`. The shutdown loop catches per-session exceptions, calls `KillWorker`, and removes the session so that one stuck worker cannot block the rest of the host:
+
+```csharp
+public async Task ShutdownAsync(CancellationToken cancellationToken)
+{
+    foreach (GatewaySession session in _registry.Snapshot())
+    {
+        try
+        {
+            await CloseSessionCoreAsync(session, GatewayShutdownReason, cancellationToken).ConfigureAwait(false);
+        }
+        catch (Exception exception)
+        {
+            _logger.LogWarning(
+                exception,
+                "Graceful shutdown failed for session {SessionId}; killing worker.",
+                session.SessionId);
+            if (_registry.TryGet(session.SessionId, out _))
+            {
+                session.KillWorker(GatewayShutdownReason);
+                await RemoveSessionAsync(session).ConfigureAwait(false);
+            }
+        }
+    }
+}
+```
+
+Iterating over `Snapshot` rather than the live dictionary lets `RemoveSessionAsync` mutate the registry inside the loop without throwing.
+
+## Dependency Injection
+
+`SessionServiceCollectionExtensions.AddGatewaySessions` registers the four singletons and the hosted service:
+
+```csharp
+public static IServiceCollection AddGatewaySessions(this IServiceCollection services)
+{
+    services.AddSingleton<ISessionRegistry, SessionRegistry>();
+    services.AddSingleton<ISessionWorkerClientFactory, SessionWorkerClientFactory>();
+    services.AddSingleton<ISessionManager, SessionManager>();
+    services.AddHostedService<SessionShutdownHostedService>();
+
+    return services;
+}
+```
+
+The registry must be a singleton because its `ConcurrentDictionary` is the source of truth for session state across the gRPC service, the lease sweeper, the dashboard, and the shutdown hosted service. Registering `SessionShutdownHostedService` last ensures it is constructed after `ISessionManager` and therefore drains sessions during host stop.
+
+## Related Documentation
+
+- [Gateway Process Design](./gateway-process-design.md)
+- [Gateway Configuration](./GatewayConfiguration.md)
+- [Worker Process Launcher](./WorkerProcessLauncher.md)

docs/WorkerBootstrap.md

@@ -0,0 +1,223 @@
+# Worker Bootstrap
+
+The bootstrap layer parses the command-line arguments and environment variables passed to the `MxGateway.Worker` process, validates them against the gateway contract, and produces either a populated `WorkerOptions` instance or a structured failure that maps to a `WorkerExitCode`.
+
+## Overview
+
+The worker process is a short-lived child of the gateway. The gateway side of this contract lives in [WorkerProcessLauncher](./WorkerProcessLauncher.md). On the worker side, `Program.cs` is a single line that delegates to `WorkerApplication.Run(args)`:
+
+```csharp
+using MxGateway.Worker;
+
+return WorkerApplication.Run(args);
+```
+
+`WorkerApplication.Run` constructs the bootstrap dependencies (`EnvironmentVariableWorkerEnvironment`, `WorkerConsoleLogger` writing to `Console.Error`, and a `WorkerPipeClient`), runs `WorkerOptionsParser`, and routes the resulting `WorkerBootstrapResult` either into the pipe client or into a non-zero exit. Splitting parsing from process wiring lets tests substitute fakes for the environment, logger, and pipe client without spawning a child process.
+
+## Worker Options
+
+`WorkerOptions` is the validated input contract for a worker session. The gateway hands every field to the worker; the worker never reads configuration files.
+
+```csharp
+public sealed class WorkerOptions
+{
+    public const string NonceEnvironmentVariableName = "MXGATEWAY_WORKER_NONCE";
+
+    public WorkerOptions(
+        string sessionId,
+        string pipeName,
+        uint protocolVersion,
+        string nonce)
+    {
+        SessionId = sessionId;
+        PipeName = pipeName;
+        ProtocolVersion = protocolVersion;
+        Nonce = nonce;
+    }
+
+    public string SessionId { get; }
+    public string PipeName { get; }
+    public uint ProtocolVersion { get; }
+    public string Nonce { get; }
+}
+```
+
+### Required inputs
+
+All four fields are required. Three arrive on the command line and one arrives via environment variable:
+
+| Source | Name | Maps to |
+|--------|------|---------|
+| Argument | `--session-id` | `SessionId` |
+| Argument | `--pipe-name` | `PipeName` |
+| Argument | `--protocol-version` | `ProtocolVersion` |
+| Env var | `MXGATEWAY_WORKER_NONCE` | `Nonce` |
+
+The nonce travels via environment variable rather than an argument because process command lines are visible to other users on Windows through `wmic`, `Get-CimInstance Win32_Process`, and the kernel object table; environment variables of another process are not. Treating the nonce as a credential keeps it off the command line.
+
+There are no optional options. An unknown flag, a flag without a value, or a flag whose value starts with `--` is reported as an error rather than silently ignored.
+
+## The Parser
+
+`WorkerOptionsParser` walks `args` once, collects values into a case-insensitive dictionary, and accumulates errors so the caller sees every problem in a single failure rather than fixing them one at a time.
+
+```csharp
+for (int index = 0; index < args.Length; index++)
+{
+    string arg = args[index];
+    if (!IsKnownOption(arg))
+    {
+        errors.Add($"Unknown option '{arg}'.");
+        continue;
+    }
+
+    if (index + 1 >= args.Length || args[index + 1].StartsWith("--", StringComparison.Ordinal))
+    {
+        errors.Add($"Option '{arg}' requires a value.");
+        continue;
+    }
+
+    values[arg] = args[index + 1];
+    index++;
+}
+```
+
+After argument scanning, the parser cross-checks the protocol version against `GatewayContractInfo.WorkerProtocolVersion`. A version that parses as a `uint` but does not match the contract value is a hard failure with `WorkerExitCode.InvalidProtocolVersion`, separate from `InvalidArguments`, so the gateway can distinguish a malformed launch from a version mismatch and report a useful upgrade message.
+
+The nonce is read last so that argument-shape errors are reported before the parser asks the environment for a secret it might not need.
+
+## Bootstrap Result
+
+`WorkerBootstrapResult` is a discriminated success/failure carrier. `Options` is non-null when `Succeeded` is true; `Errors` is populated only on failure.
+
+```csharp
+public static WorkerBootstrapResult Success(WorkerOptions options)
+{
+    return new WorkerBootstrapResult(WorkerExitCode.Success, options, []);
+}
+
+public static WorkerBootstrapResult Failure(WorkerExitCode exitCode, IEnumerable<string> errors)
+{
+    return new WorkerBootstrapResult(exitCode, null, errors.ToArray());
+}
+```
+
+`Succeeded` is defined as `ExitCode == WorkerExitCode.Success` rather than as a separate flag, so the exit code and the success state cannot disagree.
+
+## Exit Codes
+
+`WorkerExitCode` is the worker process's exit contract. The gateway-side launcher decodes these values to decide whether a relaunch is safe.
+
+| Value | Numeric | Produced when |
+|-------|---------|---------------|
+| `Success` | 0 | The pipe session ran to a clean close. |
+| `UnexpectedFailure` | 1 | Any unhandled exception not matched by a more specific catch. |
+| `InvalidArguments` | 2 | One or more `--session-id`, `--pipe-name`, or `--protocol-version` errors (missing, empty, unknown flag, or no value). |
+| `InvalidProtocolVersion` | 3 | `--protocol-version` is not a `uint` or does not equal `GatewayContractInfo.WorkerProtocolVersion`. |
+| `MissingNonce` | 4 | The `MXGATEWAY_WORKER_NONCE` environment variable is null, empty, or whitespace. |
+| `PipeConnectionFailed` | 5 | An `IOException` or `TimeoutException` escapes the pipe client. |
+| `ProtocolViolation` | 6 | A `WorkerFrameProtocolException` escapes the pipe client. |
+
+`InvalidArguments`, `InvalidProtocolVersion`, and `MissingNonce` originate in the parser; the others originate in `WorkerApplication.Run`'s `try/catch` around the pipe client.
+
+## Environment Abstraction
+
+`IWorkerEnvironment` exists so tests can supply a fake nonce without mutating the real process environment, which would be a shared mutable global across parallel test runs.
+
+```csharp
+public interface IWorkerEnvironment
+{
+    string? GetEnvironmentVariable(string name);
+}
+
+public sealed class EnvironmentVariableWorkerEnvironment : IWorkerEnvironment
+{
+    public string? GetEnvironmentVariable(string name)
+    {
+        return Environment.GetEnvironmentVariable(name);
+    }
+}
+```
+
+The production binding in `WorkerApplication.Run(string[])` is `EnvironmentVariableWorkerEnvironment`, which is a thin pass-through to `System.Environment.GetEnvironmentVariable`.
+
+## Logging
+
+The worker writes structured key/value lines to standard error. Standard error is used rather than standard output because the gateway side reads worker stdout for diagnostic capture only, while stderr is reserved for log output that does not interfere with any future stdout-based channel.
+
+### The logger contract
+
+`IWorkerLogger` exposes only `Information` and `Error`. There is no `Debug` or `Trace` level, because the worker is launched per session and verbose tracing belongs to the gateway-side launcher.
+
+```csharp
+public interface IWorkerLogger
+{
+    void Information(string eventName, IReadOnlyDictionary<string, object?> fields);
+
+    void Error(string eventName, IReadOnlyDictionary<string, object?> fields);
+}
+```
+
+`WorkerConsoleLogger` formats each call as `level=<Level> event=<EventName> key=value key=value` after running the field dictionary through `WorkerLogRedactor`:
+
+```csharp
+private void Write(
+    string level,
+    string eventName,
+    IReadOnlyDictionary<string, object?> fields)
+{
+    Dictionary<string, object?> redactedFields = WorkerLogRedactor.RedactFields(fields);
+    string fieldText = string.Join(
+        " ",
+        redactedFields.Select(field => $"{field.Key}={FormatValue(field.Value)}"));
+
+    _writer.WriteLine($"level={level} event={eventName} {fieldText}".TrimEnd());
+}
+```
+
+### What the redactor redacts and why
+
+`AGENTS.md` "Security And Logging" requires that the worker never log raw credential values for `AuthenticateUser`, `WriteSecured`, or related secured operations. The bootstrap nonce is also a credential: anyone who reads it can impersonate the worker to the gateway pipe. `WorkerLogRedactor` enforces this by replacing values whose field name contains any of these substrings (case-insensitive) with the literal `[redacted]`:
+
+```csharp
+private static readonly string[] SensitiveFieldNameParts =
+[
+    "nonce",
+    "secret",
+    "password",
+    "token",
+    "credential",
+    "apikey",
+    "api_key",
+];
+```
+
+The match is on substrings of the field name rather than an exact list, so a field called `auth_token` or `user_password` is redacted automatically without each call site having to remember to opt in. `null` values pass through unchanged so the absence of a value is still visible in logs.
+
+## How `Program.cs` Consumes The Result
+
+`WorkerApplication.Run` is the single consumer of `WorkerBootstrapResult`. On failure it logs a `WorkerBootstrapFailed` event and returns the numeric `ExitCode` directly:
+
+```csharp
+WorkerOptionsParser parser = new(environment);
+WorkerBootstrapResult result = parser.Parse(args);
+
+if (!result.Succeeded)
+{
+    logger.Error("WorkerBootstrapFailed", new Dictionary<string, object?>
+    {
+        ["exit_code"] = result.ExitCode,
+        ["errors"] = string.Join(";", result.Errors),
+    });
+
+    return (int)result.ExitCode;
+}
+```
+
+On success it logs `WorkerBootstrapSucceeded` with the session fields (the `nonce` field is redacted by `WorkerLogRedactor` because of its name), hands the `WorkerOptions` to `IWorkerPipeClient.RunAsync`, and waits synchronously. The `try/catch` around the pipe call maps `WorkerFrameProtocolException` to `ProtocolViolation`, `IOException`/`TimeoutException` to `PipeConnectionFailed`, and any other exception to `UnexpectedFailure`, so every code path through `Run` returns one of the values in `WorkerExitCode`.
+
+## Related Documentation
+
+- [Worker Process Launcher](./WorkerProcessLauncher.md)
+- [Worker STA](./WorkerSta.md)
+- [Worker Frame Protocol](./WorkerFrameProtocol.md)