Mark code-review findings Server-033..037 resolved

Records the resolutions for the five Galaxy snapshot-persistence findings
fixed in bdccdbf, and regenerates the code-reviews index. Server open
findings drop from 7 to 2 (Server-031, Server-032 remain — unrelated
event-channel backpressure findings).

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

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

@@ -51,6 +51,27 @@ public interface IMxGatewayCliClient : IAsyncDisposable
         StreamEventsRequest request,
         CancellationToken cancellationToken);
 
+    /// <summary>
+    /// Acknowledges an active MXAccess alarm condition through the gateway.
+    /// </summary>
+    /// <param name="request">The acknowledge request — alarm reference, comment, operator user.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>The acknowledge reply with protocol + native MxStatus.</returns>
+    Task<AcknowledgeAlarmReply> AcknowledgeAlarmAsync(
+        AcknowledgeAlarmRequest request,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Attaches to the gateway's central alarm feed — the current active-alarm
+    /// snapshot followed by live transitions.
+    /// </summary>
+    /// <param name="request">The stream request, optionally scoped by alarm-reference prefix.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>An async enumerable of alarm feed messages.</returns>
+    IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
+        StreamAlarmsRequest request,
+        CancellationToken cancellationToken);
+
     /// <summary>
     /// Tests connection to the Galaxy Repository.
     /// </summary>

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

@@ -52,6 +52,22 @@ internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
         return _client.StreamEventsAsync(request, cancellationToken);
     }
 
+    /// <inheritdoc />
+    public Task<AcknowledgeAlarmReply> AcknowledgeAlarmAsync(
+        AcknowledgeAlarmRequest request,
+        CancellationToken cancellationToken)
+    {
+        return _client.AcknowledgeAlarmAsync(request, cancellationToken);
+    }
+
+    /// <inheritdoc />
+    public IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
+        StreamAlarmsRequest request,
+        CancellationToken cancellationToken)
+    {
+        return _client.StreamAlarmsAsync(request, cancellationToken);
+    }
+
     /// <inheritdoc />
     public Task<TestConnectionReply> GalaxyTestConnectionAsync(
         TestConnectionRequest request,

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

@@ -130,6 +130,10 @@ public static class MxGatewayClientCli
                     .ConfigureAwait(false),
                 "stream-events" => await StreamEventsAsync(arguments, client, standardOutput, cancellation.Token)
                     .ConfigureAwait(false),
+                "stream-alarms" => await StreamAlarmsAsync(arguments, client, standardOutput, cancellation.Token)
+                    .ConfigureAwait(false),
+                "acknowledge-alarm" => await AcknowledgeAlarmAsync(arguments, client, standardOutput, cancellation.Token)
+                    .ConfigureAwait(false),
                 "write" => await WriteAsync(arguments, client, standardOutput, cancellation.Token)
                     .ConfigureAwait(false),
                 "write2" => await Write2Async(arguments, client, standardOutput, cancellation.Token)
@@ -1353,6 +1357,124 @@ public static class MxGatewayClientCli
         return 0;
     }
 
+    private static async Task<int> StreamAlarmsAsync(
+        CliArguments arguments,
+        IMxGatewayCliClient client,
+        TextWriter output,
+        CancellationToken cancellationToken)
+    {
+        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-alarms requires --max-events to bound aggregate output.");
+        }
+
+        if (maxEvents > MaxAggregateEvents)
+        {
+            throw new ArgumentException($"--max-events cannot exceed {MaxAggregateEvents}.");
+        }
+
+        var messages = json && !jsonLines
+            ? new List<AlarmFeedMessage>(checked((int)maxEvents))
+            : [];
+        uint messageCount = 0;
+        var request = new StreamAlarmsRequest
+        {
+            ClientCorrelationId = CreateCorrelationId(),
+            AlarmFilterPrefix = arguments.GetOptional("filter-prefix") ?? string.Empty,
+        };
+
+        try
+        {
+            await foreach (AlarmFeedMessage feedMessage in client.StreamAlarmsAsync(request, cancellationToken)
+                .WithCancellation(cancellationToken)
+                .ConfigureAwait(false))
+            {
+                if (jsonLines)
+                {
+                    output.WriteLine(ProtobufJsonFormatter.Format(feedMessage));
+                }
+                else if (json)
+                {
+                    messages.Add(feedMessage);
+                }
+                else
+                {
+                    output.WriteLine(FormatAlarmFeedMessage(feedMessage));
+                }
+
+                messageCount++;
+                if (maxEvents > 0 && messageCount >= maxEvents)
+                {
+                    break;
+                }
+            }
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            // Mirrors stream-events (Client.Dotnet-017): the supplied token covers
+            // the user's --timeout wall-clock budget and external Ctrl+C / parent
+            // CTS cancellation. All are graceful completion modes for a
+            // finite-window alarm-feed collector: emit what arrived and exit 0.
+        }
+
+        if (json && !jsonLines)
+        {
+            output.WriteLine(JsonSerializer.Serialize(
+                new { alarms = messages.Select(AlarmFeedMessageToJsonElement).ToArray() },
+                JsonOptions));
+        }
+
+        return 0;
+    }
+
+    private static Task<int> AcknowledgeAlarmAsync(
+        CliArguments arguments,
+        IMxGatewayCliClient client,
+        TextWriter output,
+        CancellationToken cancellationToken)
+    {
+        var request = new AcknowledgeAlarmRequest
+        {
+            ClientCorrelationId = CreateCorrelationId(),
+            AlarmFullReference = arguments.GetRequired("reference"),
+            Comment = arguments.GetOptional("comment") ?? string.Empty,
+            OperatorUser = arguments.GetOptional("operator") ?? string.Empty,
+        };
+
+        return WriteReplyAsync(
+            client.AcknowledgeAlarmAsync(request, cancellationToken),
+            arguments,
+            output);
+    }
+
+    /// <summary>
+    /// Renders one <see cref="AlarmFeedMessage"/> for the human-readable
+    /// (non-JSON) stream-alarms output, distinguishing the <c>payload</c> oneof
+    /// arms: a snapshot active alarm, the snapshot-complete sentinel, or a live
+    /// transition.
+    /// </summary>
+    private static string FormatAlarmFeedMessage(AlarmFeedMessage feedMessage)
+    {
+        return feedMessage.PayloadCase switch
+        {
+            AlarmFeedMessage.PayloadOneofCase.ActiveAlarm =>
+                $"active-alarm {ProtobufJsonFormatter.Format(feedMessage.ActiveAlarm)}",
+            AlarmFeedMessage.PayloadOneofCase.SnapshotComplete =>
+                $"snapshot-complete {feedMessage.SnapshotComplete}",
+            AlarmFeedMessage.PayloadOneofCase.Transition =>
+                $"transition {ProtobufJsonFormatter.Format(feedMessage.Transition)}",
+            _ => $"unknown-payload {feedMessage.PayloadCase}",
+        };
+    }
+
+    private static JsonElement AlarmFeedMessageToJsonElement(AlarmFeedMessage feedMessage)
+    {
+        return JsonDocument.Parse(ProtobufJsonFormatter.Format(feedMessage)).RootElement.Clone();
+    }
+
     private static async Task<int> SmokeAsync(
         CliArguments arguments,
         IMxGatewayCliClient client,
@@ -1908,6 +2030,8 @@ public static class MxGatewayClientCli
             or "bench-read-bulk"
             or "bench-stream-events"
             or "stream-events"
+            or "stream-alarms"
+            or "acknowledge-alarm"
             or "write"
             or "write2"
             or "smoke"
@@ -1966,6 +2090,8 @@ public static class MxGatewayClientCli
         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 stream-alarms [--filter-prefix <ref>] [--max-events <n>] [--json] [--jsonl]");
+        writer.WriteLine("mxgw-dotnet acknowledge-alarm --reference <ref> [--comment <text>] [--operator <user>] [--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]");

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

@@ -248,6 +248,87 @@ public sealed class MxGatewayClientCliTests
     }
 
 
+    /// <summary>Verifies that stream-alarms with --max-events stops output and distinguishes payload cases.</summary>
+    [Fact]
+    public async Task RunAsync_StreamAlarms_WithMaxEventsStopsAndDistinguishesPayloadCases()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+        FakeCliClient fakeClient = new();
+        fakeClient.AlarmFeedMessages.Add(new AlarmFeedMessage
+        {
+            ActiveAlarm = new ActiveAlarmSnapshot { AlarmFullReference = "Tank01.Level.HiHi" },
+        });
+        fakeClient.AlarmFeedMessages.Add(new AlarmFeedMessage { SnapshotComplete = true });
+
+        int exitCode = await MxGatewayClientCli.RunAsync(
+            [
+                "stream-alarms",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+                "--filter-prefix",
+                "Tank01",
+                "--max-events",
+                "1",
+            ],
+            output,
+            error,
+            _ => fakeClient);
+
+        Assert.Equal(0, exitCode);
+        StreamAlarmsRequest request = Assert.Single(fakeClient.StreamAlarmsRequests);
+        Assert.Equal("Tank01", request.AlarmFilterPrefix);
+        string text = output.ToString();
+        Assert.Contains("active-alarm", text);
+        Assert.Contains("Tank01.Level.HiHi", text);
+        Assert.DoesNotContain("snapshot-complete", text);
+        Assert.Equal(string.Empty, error.ToString());
+    }
+
+    /// <summary>Verifies that acknowledge-alarm builds a request and prints the JSON reply.</summary>
+    [Fact]
+    public async Task RunAsync_AcknowledgeAlarm_BuildsRequestAndPrintsJsonReply()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+        FakeCliClient fakeClient = new();
+        fakeClient.AcknowledgeAlarmReplies.Enqueue(new AcknowledgeAlarmReply
+        {
+            CorrelationId = "ack-fixture",
+            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+            Hresult = 0,
+        });
+
+        int exitCode = await MxGatewayClientCli.RunAsync(
+            [
+                "acknowledge-alarm",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+                "--reference",
+                "Tank01.Level.HiHi",
+                "--comment",
+                "ack from cli",
+                "--operator",
+                "operator1",
+                "--json",
+            ],
+            output,
+            error,
+            _ => fakeClient);
+
+        Assert.Equal(0, exitCode);
+        AcknowledgeAlarmRequest request = Assert.Single(fakeClient.AcknowledgeAlarmRequests);
+        Assert.Equal("Tank01.Level.HiHi", request.AlarmFullReference);
+        Assert.Equal("ack from cli", request.Comment);
+        Assert.Equal("operator1", request.OperatorUser);
+        Assert.Contains("ack-fixture", output.ToString());
+        Assert.Equal(string.Empty, error.ToString());
+    }
+
     /// <summary>Verifies that smoke command closes opened session when a command fails.</summary>
     [Fact]
     public async Task RunAsync_Smoke_WhenCommandFails_ClosesOpenedSession()
@@ -695,6 +776,41 @@ public sealed class MxGatewayClientCliTests
             }
         }
 
+        /// <summary>Queue of acknowledge-alarm replies to return.</summary>
+        public Queue<AcknowledgeAlarmReply> AcknowledgeAlarmReplies { get; } = new();
+
+        /// <summary>List of received acknowledge-alarm requests.</summary>
+        public List<AcknowledgeAlarmRequest> AcknowledgeAlarmRequests { get; } = [];
+
+        /// <summary>List of received stream-alarms requests.</summary>
+        public List<StreamAlarmsRequest> StreamAlarmsRequests { get; } = [];
+
+        /// <summary>List of alarm feed messages to yield when streaming alarms.</summary>
+        public List<AlarmFeedMessage> AlarmFeedMessages { get; } = [];
+
+        /// <inheritdoc />
+        public Task<AcknowledgeAlarmReply> AcknowledgeAlarmAsync(
+            AcknowledgeAlarmRequest request,
+            CancellationToken cancellationToken)
+        {
+            AcknowledgeAlarmRequests.Add(request);
+            return Task.FromResult(AcknowledgeAlarmReplies.Dequeue());
+        }
+
+        /// <inheritdoc />
+        public async IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
+            StreamAlarmsRequest request,
+            [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken)
+        {
+            StreamAlarmsRequests.Add(request);
+            foreach (AlarmFeedMessage feedMessage in AlarmFeedMessages)
+            {
+                cancellationToken.ThrowIfCancellationRequested();
+                await Task.Yield();
+                yield return feedMessage;
+            }
+        }
+
         /// <summary>Galaxy test connection reply to return.</summary>
         public TestConnectionReply GalaxyTestConnectionReply { get; set; } = new() { Ok = true };
 

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

@@ -107,6 +107,10 @@ func runWithIO(ctx context.Context, args []string, stdout, stderr io.Writer) err
 		return runWrite(ctx, args[1:], stdout, stderr)
 	case "stream-events":
 		return runStreamEvents(ctx, args[1:], stdout, stderr)
+	case "stream-alarms":
+		return runStreamAlarms(ctx, args[1:], stdout, stderr)
+	case "acknowledge-alarm":
+		return runAcknowledgeAlarm(ctx, args[1:], stdout, stderr)
 	case "smoke":
 		return runSmoke(ctx, args[1:], stdout, stderr)
 	case "galaxy-test-connection":
@@ -816,6 +820,119 @@ func runStreamEvents(ctx context.Context, args []string, stdout, stderr io.Write
 	return nil
 }
 
+func runStreamAlarms(ctx context.Context, args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("stream-alarms", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	common := bindCommonFlags(flags)
+	jsonOutput := flags.Bool("json", false, "write JSON output")
+	filterPrefix := flags.String("filter-prefix", "", "alarm-reference prefix scoping the feed; empty means unscoped")
+	limit := flags.Int("limit", 0, "maximum feed messages to read; 0 means unbounded")
+
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+
+	client, _, err := dialForCommand(ctx, common)
+	if err != nil {
+		return err
+	}
+	defer client.Close()
+
+	// Mirror runStreamEvents so Ctrl+C on a long-running stream-alarms command
+	// cancels the gRPC stream cleanly (the gateway sees codes.Canceled rather
+	// than a torn TCP connection) and the deferred client.Close() actually runs.
+	signalCtx, stopSignals := signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)
+	defer stopSignals()
+
+	streamCtx, cancelStream := context.WithCancel(signalCtx)
+	defer cancelStream()
+	stream, err := client.StreamAlarms(streamCtx, &mxgateway.StreamAlarmsRequest{AlarmFilterPrefix: *filterPrefix})
+	if err != nil {
+		return err
+	}
+
+	count := 0
+	for {
+		message, err := stream.Recv()
+		if errors.Is(err, io.EOF) {
+			return nil
+		}
+		if err != nil {
+			return err
+		}
+		if *jsonOutput {
+			fmt.Fprintln(stdout, string(mustMarshalProto(message)))
+		} else {
+			fmt.Fprintln(stdout, formatAlarmFeedMessage(message))
+		}
+		count++
+		if *limit > 0 && count >= *limit {
+			cancelStream()
+			return nil
+		}
+	}
+}
+
+// formatAlarmFeedMessage renders one AlarmFeedMessage in the CLI's plain-text
+// output style, distinguishing the active-alarm snapshot, snapshot-complete
+// sentinel, and transition cases of the message's payload oneof.
+func formatAlarmFeedMessage(message *mxgateway.AlarmFeedMessage) string {
+	switch {
+	case message.GetActiveAlarm() != nil:
+		alarm := message.GetActiveAlarm()
+		return fmt.Sprintf("active-alarm %s state=%s severity=%d", alarm.GetAlarmFullReference(), alarm.GetCurrentState(), alarm.GetSeverity())
+	case message.GetSnapshotComplete():
+		return "snapshot-complete"
+	case message.GetTransition() != nil:
+		transition := message.GetTransition()
+		return fmt.Sprintf("transition %s kind=%s severity=%d", transition.GetAlarmFullReference(), transition.GetTransitionKind(), transition.GetSeverity())
+	default:
+		return "unknown"
+	}
+}
+
+func runAcknowledgeAlarm(ctx context.Context, args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("acknowledge-alarm", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	common := bindCommonFlags(flags)
+	jsonOutput := flags.Bool("json", false, "write JSON output")
+	reference := flags.String("reference", "", "full alarm reference to acknowledge")
+	comment := flags.String("comment", "", "operator acknowledge comment")
+	operator := flags.String("operator", "", "operator user performing the acknowledge")
+
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+	if *reference == "" {
+		return errors.New("reference is required")
+	}
+
+	client, options, err := dialForCommand(ctx, common)
+	if err != nil {
+		return err
+	}
+	defer client.Close()
+
+	reply, err := client.AcknowledgeAlarm(ctx, &mxgateway.AcknowledgeAlarmRequest{
+		AlarmFullReference: *reference,
+		Comment:            *comment,
+		OperatorUser:       *operator,
+	})
+	if err != nil {
+		return err
+	}
+	if *jsonOutput {
+		return writeJSON(stdout, commandReplyOutput{
+			Command: "acknowledge-alarm",
+			Options: options,
+			Reply:   mustMarshalProto(reply),
+		})
+	}
+
+	fmt.Fprintln(stdout, reply.GetHresult())
+	return nil
+}
+
 func runSmoke(ctx context.Context, args []string, stdout, stderr io.Writer) error {
 	flags := flag.NewFlagSet("smoke", flag.ContinueOnError)
 	flags.SetOutput(stderr)
@@ -1120,7 +1237,7 @@ func runBatch(ctx context.Context, in io.Reader, stdout, stderr io.Writer) error
 }
 
 func writeUsage(writer io.Writer) {
-	fmt.Fprintln(writer, "usage: mxgw-go <version|open-session|close-session|register|add-item|advise|subscribe-bulk|unsubscribe-bulk|read-bulk|write-bulk|write2-bulk|write-secured-bulk|write-secured2-bulk|bench-read-bulk|write|stream-events|smoke|galaxy-test-connection|galaxy-last-deploy|galaxy-discover|galaxy-watch|batch>")
+	fmt.Fprintln(writer, "usage: mxgw-go <version|open-session|close-session|register|add-item|advise|subscribe-bulk|unsubscribe-bulk|read-bulk|write-bulk|write2-bulk|write-secured-bulk|write-secured2-bulk|bench-read-bulk|write|stream-events|stream-alarms|acknowledge-alarm|smoke|galaxy-test-connection|galaxy-last-deploy|galaxy-discover|galaxy-watch|batch>")
 }
 
 func dialGalaxyForCommand(ctx context.Context, common *commonOptions) (*mxgateway.GalaxyClient, commonOptions, error) {

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

@@ -690,12 +690,26 @@ 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"`
+	// Raw Galaxy SQL `dbo.data_type` identifier, passed through unchanged.
+	// This is NOT a member of `mxaccess_gateway.v1.MxDataType` — Galaxy's
+	// type enumeration is distinct from MXAccess's wire data-type enum and
+	// the two must not be cast or compared. The GalaxyRepository service is
+	// metadata-only and deliberately does not share types with
+	// mxaccess_gateway.proto. See docs/GalaxyRepository.md.
 	MxDataType int32 `protobuf:"varint,3,opt,name=mx_data_type,json=mxDataType,proto3" json:"mx_data_type,omitempty"`
+	// Human-readable name from Galaxy's `dbo.data_type` table (e.g. "Float",
+	// "Integer", "Boolean"). Free-form Galaxy text; not a stable enum.
 	DataTypeName          string `protobuf:"bytes,4,opt,name=data_type_name,json=dataTypeName,proto3" json:"data_type_name,omitempty"`
 	IsArray               bool   `protobuf:"varint,5,opt,name=is_array,json=isArray,proto3" json:"is_array,omitempty"`
 	ArrayDimension        int32  `protobuf:"varint,6,opt,name=array_dimension,json=arrayDimension,proto3" json:"array_dimension,omitempty"`
 	ArrayDimensionPresent bool   `protobuf:"varint,7,opt,name=array_dimension_present,json=arrayDimensionPresent,proto3" json:"array_dimension_present,omitempty"`
+	// Raw Galaxy SQL attribute-category identifier, passed through unchanged.
+	// Galaxy-specific; not mapped to any gateway enum. See
+	// docs/GalaxyRepository.md.
 	MxAttributeCategory int32 `protobuf:"varint,8,opt,name=mx_attribute_category,json=mxAttributeCategory,proto3" json:"mx_attribute_category,omitempty"`
+	// Raw Galaxy SQL security-classification identifier, passed through
+	// unchanged. Galaxy-specific; not mapped to any gateway enum. See
+	// docs/GalaxyRepository.md.
 	SecurityClassification int32 `protobuf:"varint,9,opt,name=security_classification,json=securityClassification,proto3" json:"security_classification,omitempty"`
 	IsHistorized           bool  `protobuf:"varint,10,opt,name=is_historized,json=isHistorized,proto3" json:"is_historized,omitempty"`
 	IsAlarm                bool  `protobuf:"varint,11,opt,name=is_alarm,json=isAlarm,proto3" json:"is_alarm,omitempty"`

clients/go/internal/generated/mxaccess_gateway.pb.go

@@ -3792,6 +3792,8 @@ type WriteSecuredBulkEntry struct {
 	ItemHandle     int32                  `protobuf:"varint,1,opt,name=item_handle,json=itemHandle,proto3" json:"item_handle,omitempty"`
 	CurrentUserId  int32                  `protobuf:"varint,2,opt,name=current_user_id,json=currentUserId,proto3" json:"current_user_id,omitempty"`
 	VerifierUserId int32                  `protobuf:"varint,3,opt,name=verifier_user_id,json=verifierUserId,proto3" json:"verifier_user_id,omitempty"`
+	// Credential-sensitive write value. Implementations must not log this field
+	// unless an explicit redacted value-logging path is enabled.
 	Value         *MxValue `protobuf:"bytes,4,opt,name=value,proto3" json:"value,omitempty"`
 	unknownFields protoimpl.UnknownFields
 	sizeCache     protoimpl.SizeCache
@@ -3914,6 +3916,8 @@ type WriteSecured2BulkEntry struct {
 	ItemHandle     int32                  `protobuf:"varint,1,opt,name=item_handle,json=itemHandle,proto3" json:"item_handle,omitempty"`
 	CurrentUserId  int32                  `protobuf:"varint,2,opt,name=current_user_id,json=currentUserId,proto3" json:"current_user_id,omitempty"`
 	VerifierUserId int32                  `protobuf:"varint,3,opt,name=verifier_user_id,json=verifierUserId,proto3" json:"verifier_user_id,omitempty"`
+	// Credential-sensitive write value. Implementations must not log this field
+	// unless an explicit redacted value-logging path is enabled.
 	Value          *MxValue `protobuf:"bytes,4,opt,name=value,proto3" json:"value,omitempty"`
 	TimestampValue *MxValue `protobuf:"bytes,5,opt,name=timestamp_value,json=timestampValue,proto3" json:"timestamp_value,omitempty"`
 	unknownFields  protoimpl.UnknownFields
@@ -3987,6 +3991,7 @@ func (x *WriteSecured2BulkEntry) GetTimestampValue() *MxValue {
 
 // Bulk Read — snapshot the current value for each requested tag. MXAccess COM
 // has no synchronous Read; the worker implements ReadBulk as:
+//
 //   - If the tag is already in the session's item registry AND that item is
 //     currently advised AND the worker has a cached OnDataChange for it, the
 //     reply returns the cached value WITHOUT modifying the existing
@@ -5245,9 +5250,11 @@ func (x *BulkSubscribeReply) GetResults() []*SubscribeResult {
 
 // Per-item result for the four bulk write families. `item_handle` mirrors the
 // request entry's item_handle so callers can correlate inputs to outputs even
-// when the gateway's tag-allowlist filter dropped some entries before reaching
+// when the gateway's per-entry `IConstraintEnforcer.CheckWriteHandleAsync`
-// the worker. Per-item failures populate `error_message` + `hresult` and never
+// filter (see `MxAccessGatewayService.ReplaceWriteBulkEntries` and
-// raise — callers iterate and inspect each entry.
+// `docs/Authorization.md`) dropped some entries before reaching the worker.
+// Per-item failures populate `error_message` + `hresult` and never raise —
+// callers iterate and inspect each entry.
 type BulkWriteResult struct {
 	state         protoimpl.MessageState `protogen:"open.v1"`
 	ServerHandle  int32                  `protobuf:"varint,1,opt,name=server_handle,json=serverHandle,proto3" json:"server_handle,omitempty"`
@@ -5380,6 +5387,20 @@ func (x *BulkWriteReply) GetResults() []*BulkWriteResult {
 // an existing live subscription's last OnDataChange (the worker did not touch
 // the subscription); false when the worker took the AddItem + Advise + wait +
 // UnAdvise + RemoveItem snapshot lifecycle itself.
+//
+// On `was_successful = true`, `value`, `quality`, `source_timestamp`, and
+// `statuses` carry the read data (from the cached subscription or the snapshot
+// lifecycle, depending on `was_cached`) and `error_message` is empty. On
+// `was_successful = false`, only `server_handle`, `tag_address`, `item_handle`
+// (when allocated), `was_cached`, and `error_message` are populated; `value`,
+// `quality`, `source_timestamp`, and `statuses` are left at their proto3
+// defaults (null / 0 / null / empty) and must not be read as data — they are
+// wire-indistinguishable from "value is null with quality bad" data and serve
+// only as absent markers. ReadBulk has no `hresult` field by design (its
+// outcomes are timeout / cache / lifecycle states, not MXAccess COM return
+// codes — see `docs/DesignDecisions.md` "Bulk Command Family"). Per-tag
+// failures populate `error_message` and never raise — callers iterate and
+// inspect each entry.
 type BulkReadResult struct {
 	state           protoimpl.MessageState `protogen:"open.v1"`
 	ServerHandle    int32                  `protobuf:"varint,1,opt,name=server_handle,json=serverHandle,proto3" json:"server_handle,omitempty"`
@@ -6528,7 +6549,6 @@ func (x *ActiveAlarmSnapshot) GetLimitValue() *MxValue {
 
 type AcknowledgeAlarmRequest struct {
 	state               protoimpl.MessageState `protogen:"open.v1"`
-	SessionId           string                 `protobuf:"bytes,1,opt,name=session_id,json=sessionId,proto3" json:"session_id,omitempty"`
 	ClientCorrelationId string                 `protobuf:"bytes,2,opt,name=client_correlation_id,json=clientCorrelationId,proto3" json:"client_correlation_id,omitempty"`
 	// Fully-qualified alarm reference matching OnAlarmTransitionEvent.alarm_full_reference.
 	AlarmFullReference string `protobuf:"bytes,3,opt,name=alarm_full_reference,json=alarmFullReference,proto3" json:"alarm_full_reference,omitempty"`
@@ -6571,13 +6591,6 @@ func (*AcknowledgeAlarmRequest) Descriptor() ([]byte, []int) {
 	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{77}
 }
 
-func (x *AcknowledgeAlarmRequest) GetSessionId() string {
-	if x != nil {
-		return x.SessionId
-	}
-	return ""
-}
-
 func (x *AcknowledgeAlarmRequest) GetClientCorrelationId() string {
 	if x != nil {
 		return x.ClientCorrelationId
@@ -6608,7 +6621,6 @@ func (x *AcknowledgeAlarmRequest) GetOperatorUser() string {
 
 type AcknowledgeAlarmReply struct {
 	state          protoimpl.MessageState `protogen:"open.v1"`
-	SessionId      string                 `protobuf:"bytes,1,opt,name=session_id,json=sessionId,proto3" json:"session_id,omitempty"`
 	CorrelationId  string                 `protobuf:"bytes,2,opt,name=correlation_id,json=correlationId,proto3" json:"correlation_id,omitempty"`
 	ProtocolStatus *ProtocolStatus        `protobuf:"bytes,3,opt,name=protocol_status,json=protocolStatus,proto3" json:"protocol_status,omitempty"`
 	// Native ack return code echoed from the worker. The worker carries the
@@ -6659,13 +6671,6 @@ func (*AcknowledgeAlarmReply) Descriptor() ([]byte, []int) {
 	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{78}
 }
 
-func (x *AcknowledgeAlarmReply) GetSessionId() string {
-	if x != nil {
-		return x.SessionId
-	}
-	return ""
-}
-
 func (x *AcknowledgeAlarmReply) GetCorrelationId() string {
 	if x != nil {
 		return x.CorrelationId
@@ -6701,31 +6706,31 @@ func (x *AcknowledgeAlarmReply) GetDiagnosticMessage() string {
 	return ""
 }
 
-type QueryActiveAlarmsRequest struct {
+// Request to attach to the gateway's central alarm feed (StreamAlarms).
+type StreamAlarmsRequest struct {
 	state               protoimpl.MessageState `protogen:"open.v1"`
-	SessionId           string                 `protobuf:"bytes,1,opt,name=session_id,json=sessionId,proto3" json:"session_id,omitempty"`
+	ClientCorrelationId string                 `protobuf:"bytes,1,opt,name=client_correlation_id,json=clientCorrelationId,proto3" json:"client_correlation_id,omitempty"`
-	ClientCorrelationId string                 `protobuf:"bytes,2,opt,name=client_correlation_id,json=clientCorrelationId,proto3" json:"client_correlation_id,omitempty"`
+	// Optional alarm-reference prefix scoping the feed to an equipment
-	// Optional alarm-reference prefix used to scope a partial ConditionRefresh
+	// sub-tree. Empty streams every active alarm.
-	// (e.g. equipment sub-tree). Empty means full refresh.
+	AlarmFilterPrefix string `protobuf:"bytes,2,opt,name=alarm_filter_prefix,json=alarmFilterPrefix,proto3" json:"alarm_filter_prefix,omitempty"`
-	AlarmFilterPrefix string `protobuf:"bytes,3,opt,name=alarm_filter_prefix,json=alarmFilterPrefix,proto3" json:"alarm_filter_prefix,omitempty"`
 	unknownFields     protoimpl.UnknownFields
 	sizeCache         protoimpl.SizeCache
 }
 
-func (x *QueryActiveAlarmsRequest) Reset() {
+func (x *StreamAlarmsRequest) Reset() {
-	*x = QueryActiveAlarmsRequest{}
+	*x = StreamAlarmsRequest{}
 	mi := &file_mxaccess_gateway_proto_msgTypes[79]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
 
-func (x *QueryActiveAlarmsRequest) String() string {
+func (x *StreamAlarmsRequest) String() string {
 	return protoimpl.X.MessageStringOf(x)
 }
 
-func (*QueryActiveAlarmsRequest) ProtoMessage() {}
+func (*StreamAlarmsRequest) ProtoMessage() {}
 
-func (x *QueryActiveAlarmsRequest) ProtoReflect() protoreflect.Message {
+func (x *StreamAlarmsRequest) ProtoReflect() protoreflect.Message {
 	mi := &file_mxaccess_gateway_proto_msgTypes[79]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
@@ -6737,32 +6742,130 @@ func (x *QueryActiveAlarmsRequest) ProtoReflect() protoreflect.Message {
 	return mi.MessageOf(x)
 }
 
-// Deprecated: Use QueryActiveAlarmsRequest.ProtoReflect.Descriptor instead.
+// Deprecated: Use StreamAlarmsRequest.ProtoReflect.Descriptor instead.
-func (*QueryActiveAlarmsRequest) Descriptor() ([]byte, []int) {
+func (*StreamAlarmsRequest) Descriptor() ([]byte, []int) {
 	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{79}
 }
 
-func (x *QueryActiveAlarmsRequest) GetSessionId() string {
+func (x *StreamAlarmsRequest) GetClientCorrelationId() string {
-	if x != nil {
-		return x.SessionId
-	}
-	return ""
-}
-
-func (x *QueryActiveAlarmsRequest) GetClientCorrelationId() string {
 	if x != nil {
 		return x.ClientCorrelationId
 	}
 	return ""
 }
 
-func (x *QueryActiveAlarmsRequest) GetAlarmFilterPrefix() string {
+func (x *StreamAlarmsRequest) GetAlarmFilterPrefix() string {
 	if x != nil {
 		return x.AlarmFilterPrefix
 	}
 	return ""
 }
 
+// One message on the StreamAlarms feed. The stream opens with one
+// `active_alarm` per currently-active alarm, then a single
+// `snapshot_complete`, then a `transition` for every subsequent change.
+type AlarmFeedMessage struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Types that are valid to be assigned to Payload:
+	//
+	//	*AlarmFeedMessage_ActiveAlarm
+	//	*AlarmFeedMessage_SnapshotComplete
+	//	*AlarmFeedMessage_Transition
+	Payload       isAlarmFeedMessage_Payload `protobuf_oneof:"payload"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *AlarmFeedMessage) Reset() {
+	*x = AlarmFeedMessage{}
+	mi := &file_mxaccess_gateway_proto_msgTypes[80]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *AlarmFeedMessage) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*AlarmFeedMessage) ProtoMessage() {}
+
+func (x *AlarmFeedMessage) ProtoReflect() protoreflect.Message {
+	mi := &file_mxaccess_gateway_proto_msgTypes[80]
+	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 AlarmFeedMessage.ProtoReflect.Descriptor instead.
+func (*AlarmFeedMessage) Descriptor() ([]byte, []int) {
+	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{80}
+}
+
+func (x *AlarmFeedMessage) GetPayload() isAlarmFeedMessage_Payload {
+	if x != nil {
+		return x.Payload
+	}
+	return nil
+}
+
+func (x *AlarmFeedMessage) GetActiveAlarm() *ActiveAlarmSnapshot {
+	if x != nil {
+		if x, ok := x.Payload.(*AlarmFeedMessage_ActiveAlarm); ok {
+			return x.ActiveAlarm
+		}
+	}
+	return nil
+}
+
+func (x *AlarmFeedMessage) GetSnapshotComplete() bool {
+	if x != nil {
+		if x, ok := x.Payload.(*AlarmFeedMessage_SnapshotComplete); ok {
+			return x.SnapshotComplete
+		}
+	}
+	return false
+}
+
+func (x *AlarmFeedMessage) GetTransition() *OnAlarmTransitionEvent {
+	if x != nil {
+		if x, ok := x.Payload.(*AlarmFeedMessage_Transition); ok {
+			return x.Transition
+		}
+	}
+	return nil
+}
+
+type isAlarmFeedMessage_Payload interface {
+	isAlarmFeedMessage_Payload()
+}
+
+type AlarmFeedMessage_ActiveAlarm struct {
+	// Part of the initial active-alarm snapshot (ConditionRefresh).
+	ActiveAlarm *ActiveAlarmSnapshot `protobuf:"bytes,1,opt,name=active_alarm,json=activeAlarm,proto3,oneof"`
+}
+
+type AlarmFeedMessage_SnapshotComplete struct {
+	// Sentinel: the initial snapshot is fully delivered and `transition`
+	// messages follow. Always true when present.
+	SnapshotComplete bool `protobuf:"varint,2,opt,name=snapshot_complete,json=snapshotComplete,proto3,oneof"`
+}
+
+type AlarmFeedMessage_Transition struct {
+	// A live alarm state change (raise / acknowledge / clear).
+	Transition *OnAlarmTransitionEvent `protobuf:"bytes,3,opt,name=transition,proto3,oneof"`
+}
+
+func (*AlarmFeedMessage_ActiveAlarm) isAlarmFeedMessage_Payload() {}
+
+func (*AlarmFeedMessage_SnapshotComplete) isAlarmFeedMessage_Payload() {}
+
+func (*AlarmFeedMessage_Transition) isAlarmFeedMessage_Payload() {}
+
 type MxStatusProxy struct {
 	state protoimpl.MessageState `protogen:"open.v1"`
 	// Mirrors the `success` member of the MXAccess MXSTATUS_PROXY struct
@@ -6787,7 +6890,7 @@ type MxStatusProxy struct {
 
 func (x *MxStatusProxy) Reset() {
 	*x = MxStatusProxy{}
-	mi := &file_mxaccess_gateway_proto_msgTypes[80]
+	mi := &file_mxaccess_gateway_proto_msgTypes[81]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -6799,7 +6902,7 @@ func (x *MxStatusProxy) String() string {
 func (*MxStatusProxy) ProtoMessage() {}
 
 func (x *MxStatusProxy) ProtoReflect() protoreflect.Message {
-	mi := &file_mxaccess_gateway_proto_msgTypes[80]
+	mi := &file_mxaccess_gateway_proto_msgTypes[81]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -6812,7 +6915,7 @@ func (x *MxStatusProxy) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use MxStatusProxy.ProtoReflect.Descriptor instead.
 func (*MxStatusProxy) Descriptor() ([]byte, []int) {
-	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{80}
+	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{81}
 }
 
 func (x *MxStatusProxy) GetSuccess() int32 {
@@ -6889,7 +6992,7 @@ type MxValue struct {
 
 func (x *MxValue) Reset() {
 	*x = MxValue{}
-	mi := &file_mxaccess_gateway_proto_msgTypes[81]
+	mi := &file_mxaccess_gateway_proto_msgTypes[82]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -6901,7 +7004,7 @@ func (x *MxValue) String() string {
 func (*MxValue) ProtoMessage() {}
 
 func (x *MxValue) ProtoReflect() protoreflect.Message {
-	mi := &file_mxaccess_gateway_proto_msgTypes[81]
+	mi := &file_mxaccess_gateway_proto_msgTypes[82]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -6914,7 +7017,7 @@ func (x *MxValue) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use MxValue.ProtoReflect.Descriptor instead.
 func (*MxValue) Descriptor() ([]byte, []int) {
-	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{81}
+	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{82}
 }
 
 func (x *MxValue) GetDataType() MxDataType {
@@ -7122,7 +7225,7 @@ type MxArray struct {
 
 func (x *MxArray) Reset() {
 	*x = MxArray{}
-	mi := &file_mxaccess_gateway_proto_msgTypes[82]
+	mi := &file_mxaccess_gateway_proto_msgTypes[83]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -7134,7 +7237,7 @@ func (x *MxArray) String() string {
 func (*MxArray) ProtoMessage() {}
 
 func (x *MxArray) ProtoReflect() protoreflect.Message {
-	mi := &file_mxaccess_gateway_proto_msgTypes[82]
+	mi := &file_mxaccess_gateway_proto_msgTypes[83]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -7147,7 +7250,7 @@ func (x *MxArray) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use MxArray.ProtoReflect.Descriptor instead.
 func (*MxArray) Descriptor() ([]byte, []int) {
-	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{82}
+	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{83}
 }
 
 func (x *MxArray) GetElementDataType() MxDataType {
@@ -7325,7 +7428,7 @@ type BoolArray struct {
 
 func (x *BoolArray) Reset() {
 	*x = BoolArray{}
-	mi := &file_mxaccess_gateway_proto_msgTypes[83]
+	mi := &file_mxaccess_gateway_proto_msgTypes[84]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -7337,7 +7440,7 @@ func (x *BoolArray) String() string {
 func (*BoolArray) ProtoMessage() {}
 
 func (x *BoolArray) ProtoReflect() protoreflect.Message {
-	mi := &file_mxaccess_gateway_proto_msgTypes[83]
+	mi := &file_mxaccess_gateway_proto_msgTypes[84]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -7350,7 +7453,7 @@ func (x *BoolArray) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use BoolArray.ProtoReflect.Descriptor instead.
 func (*BoolArray) Descriptor() ([]byte, []int) {
-	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{83}
+	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{84}
 }
 
 func (x *BoolArray) GetValues() []bool {
@@ -7369,7 +7472,7 @@ type Int32Array struct {
 
 func (x *Int32Array) Reset() {
 	*x = Int32Array{}
-	mi := &file_mxaccess_gateway_proto_msgTypes[84]
+	mi := &file_mxaccess_gateway_proto_msgTypes[85]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -7381,7 +7484,7 @@ func (x *Int32Array) String() string {
 func (*Int32Array) ProtoMessage() {}
 
 func (x *Int32Array) ProtoReflect() protoreflect.Message {
-	mi := &file_mxaccess_gateway_proto_msgTypes[84]
+	mi := &file_mxaccess_gateway_proto_msgTypes[85]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -7394,7 +7497,7 @@ func (x *Int32Array) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use Int32Array.ProtoReflect.Descriptor instead.
 func (*Int32Array) Descriptor() ([]byte, []int) {
-	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{84}
+	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{85}
 }
 
 func (x *Int32Array) GetValues() []int32 {
@@ -7413,7 +7516,7 @@ type Int64Array struct {
 
 func (x *Int64Array) Reset() {
 	*x = Int64Array{}
-	mi := &file_mxaccess_gateway_proto_msgTypes[85]
+	mi := &file_mxaccess_gateway_proto_msgTypes[86]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -7425,7 +7528,7 @@ func (x *Int64Array) String() string {
 func (*Int64Array) ProtoMessage() {}
 
 func (x *Int64Array) ProtoReflect() protoreflect.Message {
-	mi := &file_mxaccess_gateway_proto_msgTypes[85]
+	mi := &file_mxaccess_gateway_proto_msgTypes[86]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -7438,7 +7541,7 @@ func (x *Int64Array) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use Int64Array.ProtoReflect.Descriptor instead.
 func (*Int64Array) Descriptor() ([]byte, []int) {
-	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{85}
+	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{86}
 }
 
 func (x *Int64Array) GetValues() []int64 {
@@ -7457,7 +7560,7 @@ type FloatArray struct {
 
 func (x *FloatArray) Reset() {
 	*x = FloatArray{}
-	mi := &file_mxaccess_gateway_proto_msgTypes[86]
+	mi := &file_mxaccess_gateway_proto_msgTypes[87]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -7469,7 +7572,7 @@ func (x *FloatArray) String() string {
 func (*FloatArray) ProtoMessage() {}
 
 func (x *FloatArray) ProtoReflect() protoreflect.Message {
-	mi := &file_mxaccess_gateway_proto_msgTypes[86]
+	mi := &file_mxaccess_gateway_proto_msgTypes[87]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -7482,7 +7585,7 @@ func (x *FloatArray) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use FloatArray.ProtoReflect.Descriptor instead.
 func (*FloatArray) Descriptor() ([]byte, []int) {
-	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{86}
+	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{87}
 }
 
 func (x *FloatArray) GetValues() []float32 {
@@ -7501,7 +7604,7 @@ type DoubleArray struct {
 
 func (x *DoubleArray) Reset() {
 	*x = DoubleArray{}
-	mi := &file_mxaccess_gateway_proto_msgTypes[87]
+	mi := &file_mxaccess_gateway_proto_msgTypes[88]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -7513,7 +7616,7 @@ func (x *DoubleArray) String() string {
 func (*DoubleArray) ProtoMessage() {}
 
 func (x *DoubleArray) ProtoReflect() protoreflect.Message {
-	mi := &file_mxaccess_gateway_proto_msgTypes[87]
+	mi := &file_mxaccess_gateway_proto_msgTypes[88]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -7526,7 +7629,7 @@ func (x *DoubleArray) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use DoubleArray.ProtoReflect.Descriptor instead.
 func (*DoubleArray) Descriptor() ([]byte, []int) {
-	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{87}
+	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{88}
 }
 
 func (x *DoubleArray) GetValues() []float64 {
@@ -7545,7 +7648,7 @@ type StringArray struct {
 
 func (x *StringArray) Reset() {
 	*x = StringArray{}
-	mi := &file_mxaccess_gateway_proto_msgTypes[88]
+	mi := &file_mxaccess_gateway_proto_msgTypes[89]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -7557,7 +7660,7 @@ func (x *StringArray) String() string {
 func (*StringArray) ProtoMessage() {}
 
 func (x *StringArray) ProtoReflect() protoreflect.Message {
-	mi := &file_mxaccess_gateway_proto_msgTypes[88]
+	mi := &file_mxaccess_gateway_proto_msgTypes[89]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -7570,7 +7673,7 @@ func (x *StringArray) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use StringArray.ProtoReflect.Descriptor instead.
 func (*StringArray) Descriptor() ([]byte, []int) {
-	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{88}
+	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{89}
 }
 
 func (x *StringArray) GetValues() []string {
@@ -7589,7 +7692,7 @@ type TimestampArray struct {
 
 func (x *TimestampArray) Reset() {
 	*x = TimestampArray{}
-	mi := &file_mxaccess_gateway_proto_msgTypes[89]
+	mi := &file_mxaccess_gateway_proto_msgTypes[90]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -7601,7 +7704,7 @@ func (x *TimestampArray) String() string {
 func (*TimestampArray) ProtoMessage() {}
 
 func (x *TimestampArray) ProtoReflect() protoreflect.Message {
-	mi := &file_mxaccess_gateway_proto_msgTypes[89]
+	mi := &file_mxaccess_gateway_proto_msgTypes[90]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -7614,7 +7717,7 @@ func (x *TimestampArray) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use TimestampArray.ProtoReflect.Descriptor instead.
 func (*TimestampArray) Descriptor() ([]byte, []int) {
-	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{89}
+	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{90}
 }
 
 func (x *TimestampArray) GetValues() []*timestamppb.Timestamp {
@@ -7633,7 +7736,7 @@ type RawArray struct {
 
 func (x *RawArray) Reset() {
 	*x = RawArray{}
-	mi := &file_mxaccess_gateway_proto_msgTypes[90]
+	mi := &file_mxaccess_gateway_proto_msgTypes[91]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -7645,7 +7748,7 @@ func (x *RawArray) String() string {
 func (*RawArray) ProtoMessage() {}
 
 func (x *RawArray) ProtoReflect() protoreflect.Message {
-	mi := &file_mxaccess_gateway_proto_msgTypes[90]
+	mi := &file_mxaccess_gateway_proto_msgTypes[91]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -7658,7 +7761,7 @@ func (x *RawArray) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use RawArray.ProtoReflect.Descriptor instead.
 func (*RawArray) Descriptor() ([]byte, []int) {
-	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{90}
+	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{91}
 }
 
 func (x *RawArray) GetValues() [][]byte {
@@ -7678,7 +7781,7 @@ type ProtocolStatus struct {
 
 func (x *ProtocolStatus) Reset() {
 	*x = ProtocolStatus{}
-	mi := &file_mxaccess_gateway_proto_msgTypes[91]
+	mi := &file_mxaccess_gateway_proto_msgTypes[92]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -7690,7 +7793,7 @@ func (x *ProtocolStatus) String() string {
 func (*ProtocolStatus) ProtoMessage() {}
 
 func (x *ProtocolStatus) ProtoReflect() protoreflect.Message {
-	mi := &file_mxaccess_gateway_proto_msgTypes[91]
+	mi := &file_mxaccess_gateway_proto_msgTypes[92]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -7703,7 +7806,7 @@ func (x *ProtocolStatus) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use ProtocolStatus.ProtoReflect.Descriptor instead.
 func (*ProtocolStatus) Descriptor() ([]byte, []int) {
-	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{91}
+	return file_mxaccess_gateway_proto_rawDescGZIP(), []int{92}
 }
 
 func (x *ProtocolStatus) GetCode() ProtocolStatusCode {
@@ -8155,29 +8258,32 @@ const file_mxaccess_gateway_proto_rawDesc = "" +
 	"\x10operator_comment\x18\v \x01(\tR\x0foperatorComment\x12A\n" +
 	"\rcurrent_value\x18\f \x01(\v2\x1c.mxaccess_gateway.v1.MxValueR\fcurrentValue\x12=\n" +
 	"\vlimit_value\x18\r \x01(\v2\x1c.mxaccess_gateway.v1.MxValueR\n" +
-	"limitValue\"\xdd\x01\n" +
+	"limitValue\"\xd0\x01\n" +
-	"\x17AcknowledgeAlarmRequest\x12\x1d\n" +
+	"\x17AcknowledgeAlarmRequest\x122\n" +
-	"\n" +
-	"session_id\x18\x01 \x01(\tR\tsessionId\x122\n" +
 	"\x15client_correlation_id\x18\x02 \x01(\tR\x13clientCorrelationId\x120\n" +
 	"\x14alarm_full_reference\x18\x03 \x01(\tR\x12alarmFullReference\x12\x18\n" +
 	"\acomment\x18\x04 \x01(\tR\acomment\x12#\n" +
-	"\roperator_user\x18\x05 \x01(\tR\foperatorUser\"\xc1\x02\n" +
+	"\roperator_user\x18\x05 \x01(\tR\foperatorUserJ\x04\b\x01\x10\x02R\n" +
-	"\x15AcknowledgeAlarmReply\x12\x1d\n" +
+	"session_id\"\xb4\x02\n" +
-	"\n" +
+	"\x15AcknowledgeAlarmReply\x12%\n" +
-	"session_id\x18\x01 \x01(\tR\tsessionId\x12%\n" +
 	"\x0ecorrelation_id\x18\x02 \x01(\tR\rcorrelationId\x12L\n" +
 	"\x0fprotocol_status\x18\x03 \x01(\v2#.mxaccess_gateway.v1.ProtocolStatusR\x0eprotocolStatus\x12\x1d\n" +
 	"\ahresult\x18\x04 \x01(\x05H\x00R\ahresult\x88\x01\x01\x12:\n" +
 	"\x06status\x18\x05 \x01(\v2\".mxaccess_gateway.v1.MxStatusProxyR\x06status\x12-\n" +
 	"\x12diagnostic_message\x18\x06 \x01(\tR\x11diagnosticMessageB\n" +
 	"\n" +
-	"\b_hresult\"\x9d\x01\n" +
+	"\b_hresultJ\x04\b\x01\x10\x02R\n" +
-	"\x18QueryActiveAlarmsRequest\x12\x1d\n" +
+	"session_id\"y\n" +
+	"\x13StreamAlarmsRequest\x122\n" +
+	"\x15client_correlation_id\x18\x01 \x01(\tR\x13clientCorrelationId\x12.\n" +
+	"\x13alarm_filter_prefix\x18\x02 \x01(\tR\x11alarmFilterPrefix\"\xea\x01\n" +
+	"\x10AlarmFeedMessage\x12M\n" +
+	"\factive_alarm\x18\x01 \x01(\v2(.mxaccess_gateway.v1.ActiveAlarmSnapshotH\x00R\vactiveAlarm\x12-\n" +
+	"\x11snapshot_complete\x18\x02 \x01(\bH\x00R\x10snapshotComplete\x12M\n" +
 	"\n" +
-	"session_id\x18\x01 \x01(\tR\tsessionId\x122\n" +
+	"transition\x18\x03 \x01(\v2+.mxaccess_gateway.v1.OnAlarmTransitionEventH\x00R\n" +
-	"\x15client_correlation_id\x18\x02 \x01(\tR\x13clientCorrelationId\x12.\n" +
+	"transitionB\t\n" +
-	"\x13alarm_filter_prefix\x18\x03 \x01(\tR\x11alarmFilterPrefix\"\xbe\x02\n" +
+	"\apayload\"\xbe\x02\n" +
 	"\rMxStatusProxy\x12\x18\n" +
 	"\asuccess\x18\x01 \x01(\x05R\asuccess\x12A\n" +
 	"\bcategory\x18\x02 \x01(\x0e2%.mxaccess_gateway.v1.MxStatusCategoryR\bcategory\x12D\n" +
@@ -8377,14 +8483,14 @@ const file_mxaccess_gateway_proto_rawDesc = "" +
 	"\x13SESSION_STATE_READY\x10\x06\x12\x19\n" +
 	"\x15SESSION_STATE_CLOSING\x10\a\x12\x18\n" +
 	"\x14SESSION_STATE_CLOSED\x10\b\x12\x19\n" +
-	"\x15SESSION_STATE_FAULTED\x10\t2\xe0\x04\n" +
+	"\x15SESSION_STATE_FAULTED\x10\t2\xd3\x04\n" +
 	"\x0fMxAccessGateway\x12]\n" +
 	"\vOpenSession\x12'.mxaccess_gateway.v1.OpenSessionRequest\x1a%.mxaccess_gateway.v1.OpenSessionReply\x12`\n" +
 	"\fCloseSession\x12(.mxaccess_gateway.v1.CloseSessionRequest\x1a&.mxaccess_gateway.v1.CloseSessionReply\x12T\n" +
 	"\x06Invoke\x12%.mxaccess_gateway.v1.MxCommandRequest\x1a#.mxaccess_gateway.v1.MxCommandReply\x12X\n" +
 	"\fStreamEvents\x12(.mxaccess_gateway.v1.StreamEventsRequest\x1a\x1c.mxaccess_gateway.v1.MxEvent0\x01\x12l\n" +
-	"\x10AcknowledgeAlarm\x12,.mxaccess_gateway.v1.AcknowledgeAlarmRequest\x1a*.mxaccess_gateway.v1.AcknowledgeAlarmReply\x12n\n" +
+	"\x10AcknowledgeAlarm\x12,.mxaccess_gateway.v1.AcknowledgeAlarmRequest\x1a*.mxaccess_gateway.v1.AcknowledgeAlarmReply\x12a\n" +
-	"\x11QueryActiveAlarms\x12-.mxaccess_gateway.v1.QueryActiveAlarmsRequest\x1a(.mxaccess_gateway.v1.ActiveAlarmSnapshot0\x01B\x1c\xaa\x02\x19MxGateway.Contracts.Protob\x06proto3"
+	"\fStreamAlarms\x12(.mxaccess_gateway.v1.StreamAlarmsRequest\x1a%.mxaccess_gateway.v1.AlarmFeedMessage0\x01B\x1c\xaa\x02\x19MxGateway.Contracts.Protob\x06proto3"
 
 var (
 	file_mxaccess_gateway_proto_rawDescOnce sync.Once
@@ -8399,7 +8505,7 @@ func file_mxaccess_gateway_proto_rawDescGZIP() []byte {
 }
 
 var file_mxaccess_gateway_proto_enumTypes = make([]protoimpl.EnumInfo, 9)
-var file_mxaccess_gateway_proto_msgTypes = make([]protoimpl.MessageInfo, 92)
+var file_mxaccess_gateway_proto_msgTypes = make([]protoimpl.MessageInfo, 93)
 var file_mxaccess_gateway_proto_goTypes = []any{
 	(MxCommandKind)(0),                       // 0: mxaccess_gateway.v1.MxCommandKind
 	(MxEventFamily)(0),                       // 1: mxaccess_gateway.v1.MxEventFamily
@@ -8489,28 +8595,29 @@ var file_mxaccess_gateway_proto_goTypes = []any{
 	(*ActiveAlarmSnapshot)(nil),              // 85: mxaccess_gateway.v1.ActiveAlarmSnapshot
 	(*AcknowledgeAlarmRequest)(nil),          // 86: mxaccess_gateway.v1.AcknowledgeAlarmRequest
 	(*AcknowledgeAlarmReply)(nil),            // 87: mxaccess_gateway.v1.AcknowledgeAlarmReply
-	(*QueryActiveAlarmsRequest)(nil),         // 88: mxaccess_gateway.v1.QueryActiveAlarmsRequest
+	(*StreamAlarmsRequest)(nil),              // 88: mxaccess_gateway.v1.StreamAlarmsRequest
-	(*MxStatusProxy)(nil),                    // 89: mxaccess_gateway.v1.MxStatusProxy
+	(*AlarmFeedMessage)(nil),                 // 89: mxaccess_gateway.v1.AlarmFeedMessage
-	(*MxValue)(nil),                          // 90: mxaccess_gateway.v1.MxValue
+	(*MxStatusProxy)(nil),                    // 90: mxaccess_gateway.v1.MxStatusProxy
-	(*MxArray)(nil),                          // 91: mxaccess_gateway.v1.MxArray
+	(*MxValue)(nil),                          // 91: mxaccess_gateway.v1.MxValue
-	(*BoolArray)(nil),                        // 92: mxaccess_gateway.v1.BoolArray
+	(*MxArray)(nil),                          // 92: mxaccess_gateway.v1.MxArray
-	(*Int32Array)(nil),                       // 93: mxaccess_gateway.v1.Int32Array
+	(*BoolArray)(nil),                        // 93: mxaccess_gateway.v1.BoolArray
-	(*Int64Array)(nil),                       // 94: mxaccess_gateway.v1.Int64Array
+	(*Int32Array)(nil),                       // 94: mxaccess_gateway.v1.Int32Array
-	(*FloatArray)(nil),                       // 95: mxaccess_gateway.v1.FloatArray
+	(*Int64Array)(nil),                       // 95: mxaccess_gateway.v1.Int64Array
-	(*DoubleArray)(nil),                      // 96: mxaccess_gateway.v1.DoubleArray
+	(*FloatArray)(nil),                       // 96: mxaccess_gateway.v1.FloatArray
-	(*StringArray)(nil),                      // 97: mxaccess_gateway.v1.StringArray
+	(*DoubleArray)(nil),                      // 97: mxaccess_gateway.v1.DoubleArray
-	(*TimestampArray)(nil),                   // 98: mxaccess_gateway.v1.TimestampArray
+	(*StringArray)(nil),                      // 98: mxaccess_gateway.v1.StringArray
-	(*RawArray)(nil),                         // 99: mxaccess_gateway.v1.RawArray
+	(*TimestampArray)(nil),                   // 99: mxaccess_gateway.v1.TimestampArray
-	(*ProtocolStatus)(nil),                   // 100: mxaccess_gateway.v1.ProtocolStatus
+	(*RawArray)(nil),                         // 100: mxaccess_gateway.v1.RawArray
-	(*durationpb.Duration)(nil),              // 101: google.protobuf.Duration
+	(*ProtocolStatus)(nil),                   // 101: mxaccess_gateway.v1.ProtocolStatus
-	(*timestamppb.Timestamp)(nil),            // 102: google.protobuf.Timestamp
+	(*durationpb.Duration)(nil),              // 102: google.protobuf.Duration
+	(*timestamppb.Timestamp)(nil),            // 103: google.protobuf.Timestamp
 }
 var file_mxaccess_gateway_proto_depIdxs = []int32{
-	101, // 0: mxaccess_gateway.v1.OpenSessionRequest.command_timeout:type_name -> google.protobuf.Duration
+	102, // 0: mxaccess_gateway.v1.OpenSessionRequest.command_timeout:type_name -> google.protobuf.Duration
-	101, // 1: mxaccess_gateway.v1.OpenSessionReply.default_command_timeout:type_name -> google.protobuf.Duration
+	102, // 1: mxaccess_gateway.v1.OpenSessionReply.default_command_timeout:type_name -> google.protobuf.Duration
-	100, // 2: mxaccess_gateway.v1.OpenSessionReply.protocol_status:type_name -> mxaccess_gateway.v1.ProtocolStatus
+	101, // 2: mxaccess_gateway.v1.OpenSessionReply.protocol_status:type_name -> mxaccess_gateway.v1.ProtocolStatus
 	8,   // 3: mxaccess_gateway.v1.CloseSessionReply.final_state:type_name -> mxaccess_gateway.v1.SessionState
-	100, // 4: mxaccess_gateway.v1.CloseSessionReply.protocol_status:type_name -> mxaccess_gateway.v1.ProtocolStatus
+	101, // 4: mxaccess_gateway.v1.CloseSessionReply.protocol_status:type_name -> mxaccess_gateway.v1.ProtocolStatus
 	15,  // 5: mxaccess_gateway.v1.MxCommandRequest.command:type_name -> mxaccess_gateway.v1.MxCommand
 	0,   // 6: mxaccess_gateway.v1.MxCommand.kind:type_name -> mxaccess_gateway.v1.MxCommandKind
 	16,  // 7: mxaccess_gateway.v1.MxCommand.register:type_name -> mxaccess_gateway.v1.RegisterCommand
@@ -8552,27 +8659,27 @@ var file_mxaccess_gateway_proto_depIdxs = []int32{
 	56,  // 43: mxaccess_gateway.v1.MxCommand.get_worker_info:type_name -> mxaccess_gateway.v1.GetWorkerInfoCommand
 	57,  // 44: mxaccess_gateway.v1.MxCommand.drain_events:type_name -> mxaccess_gateway.v1.DrainEventsCommand
 	58,  // 45: mxaccess_gateway.v1.MxCommand.shutdown_worker:type_name -> mxaccess_gateway.v1.ShutdownWorkerCommand
-	90,  // 46: mxaccess_gateway.v1.WriteCommand.value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 46: mxaccess_gateway.v1.WriteCommand.value:type_name -> mxaccess_gateway.v1.MxValue
-	90,  // 47: mxaccess_gateway.v1.Write2Command.value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 47: mxaccess_gateway.v1.Write2Command.value:type_name -> mxaccess_gateway.v1.MxValue
-	90,  // 48: mxaccess_gateway.v1.Write2Command.timestamp_value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 48: mxaccess_gateway.v1.Write2Command.timestamp_value:type_name -> mxaccess_gateway.v1.MxValue
-	90,  // 49: mxaccess_gateway.v1.WriteSecuredCommand.value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 49: mxaccess_gateway.v1.WriteSecuredCommand.value:type_name -> mxaccess_gateway.v1.MxValue
-	90,  // 50: mxaccess_gateway.v1.WriteSecured2Command.value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 50: mxaccess_gateway.v1.WriteSecured2Command.value:type_name -> mxaccess_gateway.v1.MxValue
-	90,  // 51: mxaccess_gateway.v1.WriteSecured2Command.timestamp_value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 51: mxaccess_gateway.v1.WriteSecured2Command.timestamp_value:type_name -> mxaccess_gateway.v1.MxValue
 	46,  // 52: mxaccess_gateway.v1.WriteBulkCommand.entries:type_name -> mxaccess_gateway.v1.WriteBulkEntry
-	90,  // 53: mxaccess_gateway.v1.WriteBulkEntry.value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 53: mxaccess_gateway.v1.WriteBulkEntry.value:type_name -> mxaccess_gateway.v1.MxValue
 	48,  // 54: mxaccess_gateway.v1.Write2BulkCommand.entries:type_name -> mxaccess_gateway.v1.Write2BulkEntry
-	90,  // 55: mxaccess_gateway.v1.Write2BulkEntry.value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 55: mxaccess_gateway.v1.Write2BulkEntry.value:type_name -> mxaccess_gateway.v1.MxValue
-	90,  // 56: mxaccess_gateway.v1.Write2BulkEntry.timestamp_value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 56: mxaccess_gateway.v1.Write2BulkEntry.timestamp_value:type_name -> mxaccess_gateway.v1.MxValue
 	50,  // 57: mxaccess_gateway.v1.WriteSecuredBulkCommand.entries:type_name -> mxaccess_gateway.v1.WriteSecuredBulkEntry
-	90,  // 58: mxaccess_gateway.v1.WriteSecuredBulkEntry.value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 58: mxaccess_gateway.v1.WriteSecuredBulkEntry.value:type_name -> mxaccess_gateway.v1.MxValue
 	52,  // 59: mxaccess_gateway.v1.WriteSecured2BulkCommand.entries:type_name -> mxaccess_gateway.v1.WriteSecured2BulkEntry
-	90,  // 60: mxaccess_gateway.v1.WriteSecured2BulkEntry.value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 60: mxaccess_gateway.v1.WriteSecured2BulkEntry.value:type_name -> mxaccess_gateway.v1.MxValue
-	90,  // 61: mxaccess_gateway.v1.WriteSecured2BulkEntry.timestamp_value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 61: mxaccess_gateway.v1.WriteSecured2BulkEntry.timestamp_value:type_name -> mxaccess_gateway.v1.MxValue
-	101, // 62: mxaccess_gateway.v1.ShutdownWorkerCommand.grace_period:type_name -> google.protobuf.Duration
+	102, // 62: mxaccess_gateway.v1.ShutdownWorkerCommand.grace_period:type_name -> google.protobuf.Duration
 	0,   // 63: mxaccess_gateway.v1.MxCommandReply.kind:type_name -> mxaccess_gateway.v1.MxCommandKind
-	100, // 64: mxaccess_gateway.v1.MxCommandReply.protocol_status:type_name -> mxaccess_gateway.v1.ProtocolStatus
+	101, // 64: mxaccess_gateway.v1.MxCommandReply.protocol_status:type_name -> mxaccess_gateway.v1.ProtocolStatus
-	90,  // 65: mxaccess_gateway.v1.MxCommandReply.return_value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 65: mxaccess_gateway.v1.MxCommandReply.return_value:type_name -> mxaccess_gateway.v1.MxValue
-	89,  // 66: mxaccess_gateway.v1.MxCommandReply.statuses:type_name -> mxaccess_gateway.v1.MxStatusProxy
+	90,  // 66: mxaccess_gateway.v1.MxCommandReply.statuses:type_name -> mxaccess_gateway.v1.MxStatusProxy
 	60,  // 67: mxaccess_gateway.v1.MxCommandReply.register:type_name -> mxaccess_gateway.v1.RegisterReply
 	61,  // 68: mxaccess_gateway.v1.MxCommandReply.add_item:type_name -> mxaccess_gateway.v1.AddItemReply
 	62,  // 69: mxaccess_gateway.v1.MxCommandReply.add_item2:type_name -> mxaccess_gateway.v1.AddItem2Reply
@@ -8597,77 +8704,79 @@ var file_mxaccess_gateway_proto_depIdxs = []int32{
 	74,  // 88: mxaccess_gateway.v1.MxCommandReply.session_state:type_name -> mxaccess_gateway.v1.SessionStateReply
 	75,  // 89: mxaccess_gateway.v1.MxCommandReply.worker_info:type_name -> mxaccess_gateway.v1.WorkerInfoReply
 	76,  // 90: mxaccess_gateway.v1.MxCommandReply.drain_events:type_name -> mxaccess_gateway.v1.DrainEventsReply
-	89,  // 91: mxaccess_gateway.v1.SuspendReply.status:type_name -> mxaccess_gateway.v1.MxStatusProxy
+	90,  // 91: mxaccess_gateway.v1.SuspendReply.status:type_name -> mxaccess_gateway.v1.MxStatusProxy
-	89,  // 92: mxaccess_gateway.v1.ActivateReply.status:type_name -> mxaccess_gateway.v1.MxStatusProxy
+	90,  // 92: mxaccess_gateway.v1.ActivateReply.status:type_name -> mxaccess_gateway.v1.MxStatusProxy
 	68,  // 93: mxaccess_gateway.v1.BulkSubscribeReply.results:type_name -> mxaccess_gateway.v1.SubscribeResult
-	89,  // 94: mxaccess_gateway.v1.BulkWriteResult.statuses:type_name -> mxaccess_gateway.v1.MxStatusProxy
+	90,  // 94: mxaccess_gateway.v1.BulkWriteResult.statuses:type_name -> mxaccess_gateway.v1.MxStatusProxy
 	70,  // 95: mxaccess_gateway.v1.BulkWriteReply.results:type_name -> mxaccess_gateway.v1.BulkWriteResult
-	90,  // 96: mxaccess_gateway.v1.BulkReadResult.value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 96: mxaccess_gateway.v1.BulkReadResult.value:type_name -> mxaccess_gateway.v1.MxValue
-	102, // 97: mxaccess_gateway.v1.BulkReadResult.source_timestamp:type_name -> google.protobuf.Timestamp
+	103, // 97: mxaccess_gateway.v1.BulkReadResult.source_timestamp:type_name -> google.protobuf.Timestamp
-	89,  // 98: mxaccess_gateway.v1.BulkReadResult.statuses:type_name -> mxaccess_gateway.v1.MxStatusProxy
+	90,  // 98: mxaccess_gateway.v1.BulkReadResult.statuses:type_name -> mxaccess_gateway.v1.MxStatusProxy
 	72,  // 99: mxaccess_gateway.v1.BulkReadReply.results:type_name -> mxaccess_gateway.v1.BulkReadResult
 	8,   // 100: mxaccess_gateway.v1.SessionStateReply.state:type_name -> mxaccess_gateway.v1.SessionState
 	79,  // 101: mxaccess_gateway.v1.DrainEventsReply.events:type_name -> mxaccess_gateway.v1.MxEvent
 	85,  // 102: mxaccess_gateway.v1.QueryActiveAlarmsReplyPayload.snapshots:type_name -> mxaccess_gateway.v1.ActiveAlarmSnapshot
 	1,   // 103: mxaccess_gateway.v1.MxEvent.family:type_name -> mxaccess_gateway.v1.MxEventFamily
-	90,  // 104: mxaccess_gateway.v1.MxEvent.value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 104: mxaccess_gateway.v1.MxEvent.value:type_name -> mxaccess_gateway.v1.MxValue
-	102, // 105: mxaccess_gateway.v1.MxEvent.source_timestamp:type_name -> google.protobuf.Timestamp
+	103, // 105: mxaccess_gateway.v1.MxEvent.source_timestamp:type_name -> google.protobuf.Timestamp
-	89,  // 106: mxaccess_gateway.v1.MxEvent.statuses:type_name -> mxaccess_gateway.v1.MxStatusProxy
+	90,  // 106: mxaccess_gateway.v1.MxEvent.statuses:type_name -> mxaccess_gateway.v1.MxStatusProxy
-	102, // 107: mxaccess_gateway.v1.MxEvent.worker_timestamp:type_name -> google.protobuf.Timestamp
+	103, // 107: mxaccess_gateway.v1.MxEvent.worker_timestamp:type_name -> google.protobuf.Timestamp
-	102, // 108: mxaccess_gateway.v1.MxEvent.gateway_receive_timestamp:type_name -> google.protobuf.Timestamp
+	103, // 108: mxaccess_gateway.v1.MxEvent.gateway_receive_timestamp:type_name -> google.protobuf.Timestamp
 	80,  // 109: mxaccess_gateway.v1.MxEvent.on_data_change:type_name -> mxaccess_gateway.v1.OnDataChangeEvent
 	81,  // 110: mxaccess_gateway.v1.MxEvent.on_write_complete:type_name -> mxaccess_gateway.v1.OnWriteCompleteEvent
 	82,  // 111: mxaccess_gateway.v1.MxEvent.operation_complete:type_name -> mxaccess_gateway.v1.OperationCompleteEvent
 	83,  // 112: mxaccess_gateway.v1.MxEvent.on_buffered_data_change:type_name -> mxaccess_gateway.v1.OnBufferedDataChangeEvent
 	84,  // 113: mxaccess_gateway.v1.MxEvent.on_alarm_transition:type_name -> mxaccess_gateway.v1.OnAlarmTransitionEvent
 	6,   // 114: mxaccess_gateway.v1.OnBufferedDataChangeEvent.data_type:type_name -> mxaccess_gateway.v1.MxDataType
-	91,  // 115: mxaccess_gateway.v1.OnBufferedDataChangeEvent.quality_values:type_name -> mxaccess_gateway.v1.MxArray
+	92,  // 115: mxaccess_gateway.v1.OnBufferedDataChangeEvent.quality_values:type_name -> mxaccess_gateway.v1.MxArray
-	91,  // 116: mxaccess_gateway.v1.OnBufferedDataChangeEvent.timestamp_values:type_name -> mxaccess_gateway.v1.MxArray
+	92,  // 116: mxaccess_gateway.v1.OnBufferedDataChangeEvent.timestamp_values:type_name -> mxaccess_gateway.v1.MxArray
 	2,   // 117: mxaccess_gateway.v1.OnAlarmTransitionEvent.transition_kind:type_name -> mxaccess_gateway.v1.AlarmTransitionKind
-	102, // 118: mxaccess_gateway.v1.OnAlarmTransitionEvent.original_raise_timestamp:type_name -> google.protobuf.Timestamp
+	103, // 118: mxaccess_gateway.v1.OnAlarmTransitionEvent.original_raise_timestamp:type_name -> google.protobuf.Timestamp
-	102, // 119: mxaccess_gateway.v1.OnAlarmTransitionEvent.transition_timestamp:type_name -> google.protobuf.Timestamp
+	103, // 119: mxaccess_gateway.v1.OnAlarmTransitionEvent.transition_timestamp:type_name -> google.protobuf.Timestamp
-	90,  // 120: mxaccess_gateway.v1.OnAlarmTransitionEvent.current_value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 120: mxaccess_gateway.v1.OnAlarmTransitionEvent.current_value:type_name -> mxaccess_gateway.v1.MxValue
-	90,  // 121: mxaccess_gateway.v1.OnAlarmTransitionEvent.limit_value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 121: mxaccess_gateway.v1.OnAlarmTransitionEvent.limit_value:type_name -> mxaccess_gateway.v1.MxValue
-	102, // 122: mxaccess_gateway.v1.ActiveAlarmSnapshot.original_raise_timestamp:type_name -> google.protobuf.Timestamp
+	103, // 122: mxaccess_gateway.v1.ActiveAlarmSnapshot.original_raise_timestamp:type_name -> google.protobuf.Timestamp
 	3,   // 123: mxaccess_gateway.v1.ActiveAlarmSnapshot.current_state:type_name -> mxaccess_gateway.v1.AlarmConditionState
-	102, // 124: mxaccess_gateway.v1.ActiveAlarmSnapshot.last_transition_timestamp:type_name -> google.protobuf.Timestamp
+	103, // 124: mxaccess_gateway.v1.ActiveAlarmSnapshot.last_transition_timestamp:type_name -> google.protobuf.Timestamp
-	90,  // 125: mxaccess_gateway.v1.ActiveAlarmSnapshot.current_value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 125: mxaccess_gateway.v1.ActiveAlarmSnapshot.current_value:type_name -> mxaccess_gateway.v1.MxValue
-	90,  // 126: mxaccess_gateway.v1.ActiveAlarmSnapshot.limit_value:type_name -> mxaccess_gateway.v1.MxValue
+	91,  // 126: mxaccess_gateway.v1.ActiveAlarmSnapshot.limit_value:type_name -> mxaccess_gateway.v1.MxValue
-	100, // 127: mxaccess_gateway.v1.AcknowledgeAlarmReply.protocol_status:type_name -> mxaccess_gateway.v1.ProtocolStatus
+	101, // 127: mxaccess_gateway.v1.AcknowledgeAlarmReply.protocol_status:type_name -> mxaccess_gateway.v1.ProtocolStatus
-	89,  // 128: mxaccess_gateway.v1.AcknowledgeAlarmReply.status:type_name -> mxaccess_gateway.v1.MxStatusProxy
+	90,  // 128: mxaccess_gateway.v1.AcknowledgeAlarmReply.status:type_name -> mxaccess_gateway.v1.MxStatusProxy
-	4,   // 129: mxaccess_gateway.v1.MxStatusProxy.category:type_name -> mxaccess_gateway.v1.MxStatusCategory
+	85,  // 129: mxaccess_gateway.v1.AlarmFeedMessage.active_alarm:type_name -> mxaccess_gateway.v1.ActiveAlarmSnapshot
-	5,   // 130: mxaccess_gateway.v1.MxStatusProxy.detected_by:type_name -> mxaccess_gateway.v1.MxStatusSource
+	84,  // 130: mxaccess_gateway.v1.AlarmFeedMessage.transition:type_name -> mxaccess_gateway.v1.OnAlarmTransitionEvent
-	6,   // 131: mxaccess_gateway.v1.MxValue.data_type:type_name -> mxaccess_gateway.v1.MxDataType
+	4,   // 131: mxaccess_gateway.v1.MxStatusProxy.category:type_name -> mxaccess_gateway.v1.MxStatusCategory
-	102, // 132: mxaccess_gateway.v1.MxValue.timestamp_value:type_name -> google.protobuf.Timestamp
+	5,   // 132: mxaccess_gateway.v1.MxStatusProxy.detected_by:type_name -> mxaccess_gateway.v1.MxStatusSource
-	91,  // 133: mxaccess_gateway.v1.MxValue.array_value:type_name -> mxaccess_gateway.v1.MxArray
+	6,   // 133: mxaccess_gateway.v1.MxValue.data_type:type_name -> mxaccess_gateway.v1.MxDataType
-	6,   // 134: mxaccess_gateway.v1.MxArray.element_data_type:type_name -> mxaccess_gateway.v1.MxDataType
+	103, // 134: mxaccess_gateway.v1.MxValue.timestamp_value:type_name -> google.protobuf.Timestamp
-	92,  // 135: mxaccess_gateway.v1.MxArray.bool_values:type_name -> mxaccess_gateway.v1.BoolArray
+	92,  // 135: mxaccess_gateway.v1.MxValue.array_value:type_name -> mxaccess_gateway.v1.MxArray
-	93,  // 136: mxaccess_gateway.v1.MxArray.int32_values:type_name -> mxaccess_gateway.v1.Int32Array
+	6,   // 136: mxaccess_gateway.v1.MxArray.element_data_type:type_name -> mxaccess_gateway.v1.MxDataType
-	94,  // 137: mxaccess_gateway.v1.MxArray.int64_values:type_name -> mxaccess_gateway.v1.Int64Array
+	93,  // 137: mxaccess_gateway.v1.MxArray.bool_values:type_name -> mxaccess_gateway.v1.BoolArray
-	95,  // 138: mxaccess_gateway.v1.MxArray.float_values:type_name -> mxaccess_gateway.v1.FloatArray
+	94,  // 138: mxaccess_gateway.v1.MxArray.int32_values:type_name -> mxaccess_gateway.v1.Int32Array
-	96,  // 139: mxaccess_gateway.v1.MxArray.double_values:type_name -> mxaccess_gateway.v1.DoubleArray
+	95,  // 139: mxaccess_gateway.v1.MxArray.int64_values:type_name -> mxaccess_gateway.v1.Int64Array
-	97,  // 140: mxaccess_gateway.v1.MxArray.string_values:type_name -> mxaccess_gateway.v1.StringArray
+	96,  // 140: mxaccess_gateway.v1.MxArray.float_values:type_name -> mxaccess_gateway.v1.FloatArray
-	98,  // 141: mxaccess_gateway.v1.MxArray.timestamp_values:type_name -> mxaccess_gateway.v1.TimestampArray
+	97,  // 141: mxaccess_gateway.v1.MxArray.double_values:type_name -> mxaccess_gateway.v1.DoubleArray
-	99,  // 142: mxaccess_gateway.v1.MxArray.raw_values:type_name -> mxaccess_gateway.v1.RawArray
+	98,  // 142: mxaccess_gateway.v1.MxArray.string_values:type_name -> mxaccess_gateway.v1.StringArray
-	102, // 143: mxaccess_gateway.v1.TimestampArray.values:type_name -> google.protobuf.Timestamp
+	99,  // 143: mxaccess_gateway.v1.MxArray.timestamp_values:type_name -> mxaccess_gateway.v1.TimestampArray
-	7,   // 144: mxaccess_gateway.v1.ProtocolStatus.code:type_name -> mxaccess_gateway.v1.ProtocolStatusCode
+	100, // 144: mxaccess_gateway.v1.MxArray.raw_values:type_name -> mxaccess_gateway.v1.RawArray
-	9,   // 145: mxaccess_gateway.v1.MxAccessGateway.OpenSession:input_type -> mxaccess_gateway.v1.OpenSessionRequest
+	103, // 145: mxaccess_gateway.v1.TimestampArray.values:type_name -> google.protobuf.Timestamp
-	11,  // 146: mxaccess_gateway.v1.MxAccessGateway.CloseSession:input_type -> mxaccess_gateway.v1.CloseSessionRequest
+	7,   // 146: mxaccess_gateway.v1.ProtocolStatus.code:type_name -> mxaccess_gateway.v1.ProtocolStatusCode
-	14,  // 147: mxaccess_gateway.v1.MxAccessGateway.Invoke:input_type -> mxaccess_gateway.v1.MxCommandRequest
+	9,   // 147: mxaccess_gateway.v1.MxAccessGateway.OpenSession:input_type -> mxaccess_gateway.v1.OpenSessionRequest
-	13,  // 148: mxaccess_gateway.v1.MxAccessGateway.StreamEvents:input_type -> mxaccess_gateway.v1.StreamEventsRequest
+	11,  // 148: mxaccess_gateway.v1.MxAccessGateway.CloseSession:input_type -> mxaccess_gateway.v1.CloseSessionRequest
-	86,  // 149: mxaccess_gateway.v1.MxAccessGateway.AcknowledgeAlarm:input_type -> mxaccess_gateway.v1.AcknowledgeAlarmRequest
+	14,  // 149: mxaccess_gateway.v1.MxAccessGateway.Invoke:input_type -> mxaccess_gateway.v1.MxCommandRequest
-	88,  // 150: mxaccess_gateway.v1.MxAccessGateway.QueryActiveAlarms:input_type -> mxaccess_gateway.v1.QueryActiveAlarmsRequest
+	13,  // 150: mxaccess_gateway.v1.MxAccessGateway.StreamEvents:input_type -> mxaccess_gateway.v1.StreamEventsRequest
-	10,  // 151: mxaccess_gateway.v1.MxAccessGateway.OpenSession:output_type -> mxaccess_gateway.v1.OpenSessionReply
+	86,  // 151: mxaccess_gateway.v1.MxAccessGateway.AcknowledgeAlarm:input_type -> mxaccess_gateway.v1.AcknowledgeAlarmRequest
-	12,  // 152: mxaccess_gateway.v1.MxAccessGateway.CloseSession:output_type -> mxaccess_gateway.v1.CloseSessionReply
+	88,  // 152: mxaccess_gateway.v1.MxAccessGateway.StreamAlarms:input_type -> mxaccess_gateway.v1.StreamAlarmsRequest
-	59,  // 153: mxaccess_gateway.v1.MxAccessGateway.Invoke:output_type -> mxaccess_gateway.v1.MxCommandReply
+	10,  // 153: mxaccess_gateway.v1.MxAccessGateway.OpenSession:output_type -> mxaccess_gateway.v1.OpenSessionReply
-	79,  // 154: mxaccess_gateway.v1.MxAccessGateway.StreamEvents:output_type -> mxaccess_gateway.v1.MxEvent
+	12,  // 154: mxaccess_gateway.v1.MxAccessGateway.CloseSession:output_type -> mxaccess_gateway.v1.CloseSessionReply
-	87,  // 155: mxaccess_gateway.v1.MxAccessGateway.AcknowledgeAlarm:output_type -> mxaccess_gateway.v1.AcknowledgeAlarmReply
+	59,  // 155: mxaccess_gateway.v1.MxAccessGateway.Invoke:output_type -> mxaccess_gateway.v1.MxCommandReply
-	85,  // 156: mxaccess_gateway.v1.MxAccessGateway.QueryActiveAlarms:output_type -> mxaccess_gateway.v1.ActiveAlarmSnapshot
+	79,  // 156: mxaccess_gateway.v1.MxAccessGateway.StreamEvents:output_type -> mxaccess_gateway.v1.MxEvent
-	151, // [151:157] is the sub-list for method output_type
+	87,  // 157: mxaccess_gateway.v1.MxAccessGateway.AcknowledgeAlarm:output_type -> mxaccess_gateway.v1.AcknowledgeAlarmReply
-	145, // [145:151] is the sub-list for method input_type
+	89,  // 158: mxaccess_gateway.v1.MxAccessGateway.StreamAlarms:output_type -> mxaccess_gateway.v1.AlarmFeedMessage
-	145, // [145:145] is the sub-list for extension type_name
+	153, // [153:159] is the sub-list for method output_type
-	145, // [145:145] is the sub-list for extension extendee
+	147, // [147:153] is the sub-list for method input_type
-	0,   // [0:145] is the sub-list for field type_name
+	147, // [147:147] is the sub-list for extension type_name
+	147, // [147:147] is the sub-list for extension extendee
+	0,   // [0:147] is the sub-list for field type_name
 }
 
 func init() { file_mxaccess_gateway_proto_init() }
@@ -8751,7 +8860,12 @@ func file_mxaccess_gateway_proto_init() {
 		(*MxEvent_OnAlarmTransition)(nil),
 	}
 	file_mxaccess_gateway_proto_msgTypes[78].OneofWrappers = []any{}
-	file_mxaccess_gateway_proto_msgTypes[81].OneofWrappers = []any{
+	file_mxaccess_gateway_proto_msgTypes[80].OneofWrappers = []any{
+		(*AlarmFeedMessage_ActiveAlarm)(nil),
+		(*AlarmFeedMessage_SnapshotComplete)(nil),
+		(*AlarmFeedMessage_Transition)(nil),
+	}
+	file_mxaccess_gateway_proto_msgTypes[82].OneofWrappers = []any{
 		(*MxValue_BoolValue)(nil),
 		(*MxValue_Int32Value)(nil),
 		(*MxValue_Int64Value)(nil),
@@ -8762,7 +8876,7 @@ func file_mxaccess_gateway_proto_init() {
 		(*MxValue_ArrayValue)(nil),
 		(*MxValue_RawValue)(nil),
 	}
-	file_mxaccess_gateway_proto_msgTypes[82].OneofWrappers = []any{
+	file_mxaccess_gateway_proto_msgTypes[83].OneofWrappers = []any{
 		(*MxArray_BoolValues)(nil),
 		(*MxArray_Int32Values)(nil),
 		(*MxArray_Int64Values)(nil),
@@ -8778,7 +8892,7 @@ func file_mxaccess_gateway_proto_init() {
 			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
 			RawDescriptor: unsafe.Slice(unsafe.StringData(file_mxaccess_gateway_proto_rawDesc), len(file_mxaccess_gateway_proto_rawDesc)),
 			NumEnums:      9,
-			NumMessages:   92,
+			NumMessages:   93,
 			NumExtensions: 0,
 			NumServices:   1,
 		},

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

@@ -24,7 +24,7 @@ const (
 	MxAccessGateway_Invoke_FullMethodName           = "/mxaccess_gateway.v1.MxAccessGateway/Invoke"
 	MxAccessGateway_StreamEvents_FullMethodName     = "/mxaccess_gateway.v1.MxAccessGateway/StreamEvents"
 	MxAccessGateway_AcknowledgeAlarm_FullMethodName = "/mxaccess_gateway.v1.MxAccessGateway/AcknowledgeAlarm"
-	MxAccessGateway_QueryActiveAlarms_FullMethodName = "/mxaccess_gateway.v1.MxAccessGateway/QueryActiveAlarms"
+	MxAccessGateway_StreamAlarms_FullMethodName     = "/mxaccess_gateway.v1.MxAccessGateway/StreamAlarms"
 )
 
 // MxAccessGatewayClient is the client API for MxAccessGateway service.
@@ -38,7 +38,12 @@ type MxAccessGatewayClient interface {
 	Invoke(ctx context.Context, in *MxCommandRequest, opts ...grpc.CallOption) (*MxCommandReply, error)
 	StreamEvents(ctx context.Context, in *StreamEventsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[MxEvent], error)
 	AcknowledgeAlarm(ctx context.Context, in *AcknowledgeAlarmRequest, opts ...grpc.CallOption) (*AcknowledgeAlarmReply, error)
-	QueryActiveAlarms(ctx context.Context, in *QueryActiveAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[ActiveAlarmSnapshot], error)
+	// Session-less central alarm feed. The stream opens with the current
+	// active-alarm snapshot (one `active_alarm` per alarm), then a single
+	// `snapshot_complete`, then a `transition` for every subsequent change.
+	// Served by the gateway's always-on alarm monitor; any number of clients
+	// fan out from the single monitor without opening a worker session.
+	StreamAlarms(ctx context.Context, in *StreamAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[AlarmFeedMessage], error)
 }
 
 type mxAccessGatewayClient struct {
@@ -108,13 +113,13 @@ func (c *mxAccessGatewayClient) AcknowledgeAlarm(ctx context.Context, in *Acknow
 	return out, nil
 }
 
-func (c *mxAccessGatewayClient) QueryActiveAlarms(ctx context.Context, in *QueryActiveAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[ActiveAlarmSnapshot], error) {
+func (c *mxAccessGatewayClient) StreamAlarms(ctx context.Context, in *StreamAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[AlarmFeedMessage], error) {
 	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
-	stream, err := c.cc.NewStream(ctx, &MxAccessGateway_ServiceDesc.Streams[1], MxAccessGateway_QueryActiveAlarms_FullMethodName, cOpts...)
+	stream, err := c.cc.NewStream(ctx, &MxAccessGateway_ServiceDesc.Streams[1], MxAccessGateway_StreamAlarms_FullMethodName, cOpts...)
 	if err != nil {
 		return nil, err
 	}
-	x := &grpc.GenericClientStream[QueryActiveAlarmsRequest, ActiveAlarmSnapshot]{ClientStream: stream}
+	x := &grpc.GenericClientStream[StreamAlarmsRequest, AlarmFeedMessage]{ClientStream: stream}
 	if err := x.ClientStream.SendMsg(in); err != nil {
 		return nil, err
 	}
@@ -125,7 +130,7 @@ func (c *mxAccessGatewayClient) QueryActiveAlarms(ctx context.Context, in *Query
 }
 
 // This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
-type MxAccessGateway_QueryActiveAlarmsClient = grpc.ServerStreamingClient[ActiveAlarmSnapshot]
+type MxAccessGateway_StreamAlarmsClient = grpc.ServerStreamingClient[AlarmFeedMessage]
 
 // MxAccessGatewayServer is the server API for MxAccessGateway service.
 // All implementations must embed UnimplementedMxAccessGatewayServer
@@ -138,7 +143,12 @@ type MxAccessGatewayServer interface {
 	Invoke(context.Context, *MxCommandRequest) (*MxCommandReply, error)
 	StreamEvents(*StreamEventsRequest, grpc.ServerStreamingServer[MxEvent]) error
 	AcknowledgeAlarm(context.Context, *AcknowledgeAlarmRequest) (*AcknowledgeAlarmReply, error)
-	QueryActiveAlarms(*QueryActiveAlarmsRequest, grpc.ServerStreamingServer[ActiveAlarmSnapshot]) error
+	// Session-less central alarm feed. The stream opens with the current
+	// active-alarm snapshot (one `active_alarm` per alarm), then a single
+	// `snapshot_complete`, then a `transition` for every subsequent change.
+	// Served by the gateway's always-on alarm monitor; any number of clients
+	// fan out from the single monitor without opening a worker session.
+	StreamAlarms(*StreamAlarmsRequest, grpc.ServerStreamingServer[AlarmFeedMessage]) error
 	mustEmbedUnimplementedMxAccessGatewayServer()
 }
 
@@ -164,8 +174,8 @@ func (UnimplementedMxAccessGatewayServer) StreamEvents(*StreamEventsRequest, grp
 func (UnimplementedMxAccessGatewayServer) AcknowledgeAlarm(context.Context, *AcknowledgeAlarmRequest) (*AcknowledgeAlarmReply, error) {
 	return nil, status.Error(codes.Unimplemented, "method AcknowledgeAlarm not implemented")
 }
-func (UnimplementedMxAccessGatewayServer) QueryActiveAlarms(*QueryActiveAlarmsRequest, grpc.ServerStreamingServer[ActiveAlarmSnapshot]) error {
+func (UnimplementedMxAccessGatewayServer) StreamAlarms(*StreamAlarmsRequest, grpc.ServerStreamingServer[AlarmFeedMessage]) error {
-	return status.Error(codes.Unimplemented, "method QueryActiveAlarms not implemented")
+	return status.Error(codes.Unimplemented, "method StreamAlarms not implemented")
 }
 func (UnimplementedMxAccessGatewayServer) mustEmbedUnimplementedMxAccessGatewayServer() {}
 func (UnimplementedMxAccessGatewayServer) testEmbeddedByValue()                         {}
@@ -271,16 +281,16 @@ func _MxAccessGateway_AcknowledgeAlarm_Handler(srv interface{}, ctx context.Cont
 	return interceptor(ctx, in, info, handler)
 }
 
-func _MxAccessGateway_QueryActiveAlarms_Handler(srv interface{}, stream grpc.ServerStream) error {
+func _MxAccessGateway_StreamAlarms_Handler(srv interface{}, stream grpc.ServerStream) error {
-	m := new(QueryActiveAlarmsRequest)
+	m := new(StreamAlarmsRequest)
 	if err := stream.RecvMsg(m); err != nil {
 		return err
 	}
-	return srv.(MxAccessGatewayServer).QueryActiveAlarms(m, &grpc.GenericServerStream[QueryActiveAlarmsRequest, ActiveAlarmSnapshot]{ServerStream: stream})
+	return srv.(MxAccessGatewayServer).StreamAlarms(m, &grpc.GenericServerStream[StreamAlarmsRequest, AlarmFeedMessage]{ServerStream: stream})
 }
 
 // This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
-type MxAccessGateway_QueryActiveAlarmsServer = grpc.ServerStreamingServer[ActiveAlarmSnapshot]
+type MxAccessGateway_StreamAlarmsServer = grpc.ServerStreamingServer[AlarmFeedMessage]
 
 // MxAccessGateway_ServiceDesc is the grpc.ServiceDesc for MxAccessGateway service.
 // It's only intended for direct use with grpc.RegisterService,
@@ -313,8 +323,8 @@ var MxAccessGateway_ServiceDesc = grpc.ServiceDesc{
 			ServerStreams: true,
 		},
 		{
-			StreamName:    "QueryActiveAlarms",
+			StreamName:    "StreamAlarms",
-			Handler:       _MxAccessGateway_QueryActiveAlarms_Handler,
+			Handler:       _MxAccessGateway_StreamAlarms_Handler,
 			ServerStreams: true,
 		},
 	},

clients/go/mxgateway/alarms.go

@@ -31,22 +31,24 @@ func (c *Client) AcknowledgeAlarm(ctx context.Context, req *AcknowledgeAlarmRequ
 	return reply, nil
 }
 
-// QueryActiveAlarms streams a snapshot of all alarms currently Active or
+// StreamAlarms attaches to the gateway's central alarm feed. The stream opens
-// ActiveAcked — the gateway's ConditionRefresh equivalent. Used after reconnect
+// with one AlarmFeedMessage per currently-active alarm (the ConditionRefresh
-// to seed local Part 9 state, or to reconcile alarms that may have been missed
+// snapshot), then a single snapshot-complete sentinel, then a transition for
-// during a transport blip.
+// every subsequent raise / acknowledge / clear. It is served by the gateway's
+// always-on alarm monitor — no worker session is opened — so any number of
+// clients may attach.
 //
 // The returned stream is owned by the caller; cancel ctx to release it.
 // Optional alarm-reference prefix scoping (req.AlarmFilterPrefix) limits the
 // stream to a sub-tree.
-func (c *Client) QueryActiveAlarms(ctx context.Context, req *QueryActiveAlarmsRequest) (QueryActiveAlarmsClient, error) {
+func (c *Client) StreamAlarms(ctx context.Context, req *StreamAlarmsRequest) (StreamAlarmsClient, error) {
 	if req == nil {
-		return nil, errors.New("mxgateway: query active alarms request is required")
+		return nil, errors.New("mxgateway: stream alarms request is required")
 	}
 
-	stream, err := c.raw.QueryActiveAlarms(ctx, req)
+	stream, err := c.raw.StreamAlarms(ctx, req)
 	if err != nil {
-		return nil, &GatewayError{Op: "query active alarms", Err: err}
+		return nil, &GatewayError{Op: "stream alarms", Err: err}
 	}
 
 	return stream, nil

clients/go/mxgateway/alarms_test.go

@@ -14,13 +14,11 @@ import (
 	"google.golang.org/grpc/test/bufconn"
 )
 
-// PR E.4 — pins the Go SDK surface for the new alarm RPCs:
+// Pins the Go SDK surface for the alarm RPCs: AcknowledgeAlarm + StreamAlarms.
-// AcknowledgeAlarm + QueryActiveAlarms.
 
 func TestAcknowledgeAlarmSendsRequestAndReturnsReply(t *testing.T) {
 	fake := &fakeGatewayWithAlarms{
 		acknowledgeReply: &pb.AcknowledgeAlarmReply{
-			SessionId:     "session-1",
 			CorrelationId: "corr-1",
 			ProtocolStatus: &pb.ProtocolStatus{
 				Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
@@ -35,7 +33,6 @@ func TestAcknowledgeAlarmSendsRequestAndReturnsReply(t *testing.T) {
 	defer cleanup()
 
 	reply, err := client.AcknowledgeAlarm(context.Background(), &pb.AcknowledgeAlarmRequest{
-		SessionId:           "session-1",
 		ClientCorrelationId: "corr-1",
 		AlarmFullReference:  "Tank01.Level.HiHi",
 		Comment:             "investigating",
@@ -77,7 +74,6 @@ func TestAcknowledgeAlarmMapsUnauthenticated(t *testing.T) {
 	defer cleanup()
 
 	_, err := client.AcknowledgeAlarm(context.Background(), &pb.AcknowledgeAlarmRequest{
-		SessionId:          "session-1",
 		AlarmFullReference: "Tank01.Level.HiHi",
 		OperatorUser:       "alice",
 	})
@@ -93,7 +89,7 @@ func TestAcknowledgeAlarmMapsUnauthenticated(t *testing.T) {
 	}
 }
 
-func TestQueryActiveAlarmsStreamsSnapshots(t *testing.T) {
+func TestStreamAlarmsStreamsSnapshotThenSnapshotComplete(t *testing.T) {
 	fake := &fakeGatewayWithAlarms{
 		activeSnapshots: []*pb.ActiveAlarmSnapshot{
 			{
@@ -111,46 +107,46 @@ func TestQueryActiveAlarmsStreamsSnapshots(t *testing.T) {
 	client, cleanup := newBufconnClientWithAlarms(t, fake)
 	defer cleanup()
 
-	stream, err := client.QueryActiveAlarms(context.Background(), &pb.QueryActiveAlarmsRequest{
+	stream, err := client.StreamAlarms(context.Background(), &pb.StreamAlarmsRequest{})
-		SessionId: "session-1",
-	})
 	if err != nil {
-		t.Fatalf("QueryActiveAlarms() error = %v", err)
+		t.Fatalf("StreamAlarms() error = %v", err)
 	}
 
-	var received []*pb.ActiveAlarmSnapshot
+	var received []*pb.AlarmFeedMessage
 	for {
-		snap, err := stream.Recv()
+		msg, err := stream.Recv()
 		if errors.Is(err, io.EOF) {
 			break
 		}
 		if err != nil {
 			t.Fatalf("stream.Recv() error = %v", err)
 		}
-		received = append(received, snap)
+		received = append(received, msg)
 	}
-	if len(received) != 2 {
+	if len(received) != 3 {
-		t.Fatalf("snapshot count = %d, want 2", len(received))
+		t.Fatalf("message count = %d, want 3", len(received))
 	}
-	if received[0].GetAlarmFullReference() != "Tank01.Level.HiHi" {
+	if received[0].GetActiveAlarm().GetAlarmFullReference() != "Tank01.Level.HiHi" {
-		t.Fatalf("snapshot[0] ref = %q", received[0].GetAlarmFullReference())
+		t.Fatalf("message[0] ref = %q", received[0].GetActiveAlarm().GetAlarmFullReference())
 	}
-	if received[1].GetCurrentState() != pb.AlarmConditionState_ALARM_CONDITION_STATE_ACTIVE_ACKED {
+	if received[1].GetActiveAlarm().GetCurrentState() != pb.AlarmConditionState_ALARM_CONDITION_STATE_ACTIVE_ACKED {
-		t.Fatalf("snapshot[1] state = %v", received[1].GetCurrentState())
+		t.Fatalf("message[1] state = %v", received[1].GetActiveAlarm().GetCurrentState())
+	}
+	if !received[2].GetSnapshotComplete() {
+		t.Fatalf("final message is not snapshot_complete")
 	}
 }
 
-func TestQueryActiveAlarmsPassesFilterPrefix(t *testing.T) {
+func TestStreamAlarmsPassesFilterPrefix(t *testing.T) {
 	fake := &fakeGatewayWithAlarms{}
 	client, cleanup := newBufconnClientWithAlarms(t, fake)
 	defer cleanup()
 
-	stream, err := client.QueryActiveAlarms(context.Background(), &pb.QueryActiveAlarmsRequest{
+	stream, err := client.StreamAlarms(context.Background(), &pb.StreamAlarmsRequest{
-		SessionId:         "session-1",
 		AlarmFilterPrefix: "Tank01.",
 	})
 	if err != nil {
-		t.Fatalf("QueryActiveAlarms() error = %v", err)
+		t.Fatalf("StreamAlarms() error = %v", err)
 	}
 	for {
 		_, err := stream.Recv()
@@ -162,7 +158,7 @@ func TestQueryActiveAlarmsPassesFilterPrefix(t *testing.T) {
 		}
 	}
 
-	if got := fake.queryRequest.GetAlarmFilterPrefix(); got != "Tank01." {
+	if got := fake.streamRequest.GetAlarmFilterPrefix(); got != "Tank01." {
 		t.Fatalf("captured filter prefix = %q", got)
 	}
 }
@@ -175,7 +171,7 @@ type fakeGatewayWithAlarms struct {
 	acknowledgeError   error
 	acknowledgeAuth    string
 
-	queryRequest    *pb.QueryActiveAlarmsRequest
+	streamRequest   *pb.StreamAlarmsRequest
 	activeSnapshots []*pb.ActiveAlarmSnapshot
 }
 
@@ -189,21 +185,24 @@ func (s *fakeGatewayWithAlarms) AcknowledgeAlarm(ctx context.Context, req *pb.Ac
 		return s.acknowledgeReply, nil
 	}
 	return &pb.AcknowledgeAlarmReply{
-		SessionId: req.GetSessionId(),
 		ProtocolStatus: &pb.ProtocolStatus{
 			Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
 		},
 	}, nil
 }
 
-func (s *fakeGatewayWithAlarms) QueryActiveAlarms(req *pb.QueryActiveAlarmsRequest, stream grpc.ServerStreamingServer[pb.ActiveAlarmSnapshot]) error {
+func (s *fakeGatewayWithAlarms) StreamAlarms(req *pb.StreamAlarmsRequest, stream grpc.ServerStreamingServer[pb.AlarmFeedMessage]) error {
-	s.queryRequest = req
+	s.streamRequest = req
 	for _, snap := range s.activeSnapshots {
-		if err := stream.Send(snap); err != nil {
+		if err := stream.Send(&pb.AlarmFeedMessage{
+			Payload: &pb.AlarmFeedMessage_ActiveAlarm{ActiveAlarm: snap},
+		}); err != nil {
 			return err
 		}
 	}
-	return nil
+	return stream.Send(&pb.AlarmFeedMessage{
+		Payload: &pb.AlarmFeedMessage_SnapshotComplete{SnapshotComplete: true},
+	})
 }
 
 func newBufconnClientWithAlarms(t *testing.T, fake *fakeGatewayWithAlarms) (*Client, func()) {

clients/go/mxgateway/types.go

@@ -110,9 +110,12 @@ type (
 	AcknowledgeAlarmRequest = pb.AcknowledgeAlarmRequest
 	// AcknowledgeAlarmReply is the gateway AcknowledgeAlarm reply message.
 	AcknowledgeAlarmReply = pb.AcknowledgeAlarmReply
-	// QueryActiveAlarmsRequest is the gateway QueryActiveAlarms request message.
+	// StreamAlarmsRequest is the gateway StreamAlarms request message.
-	QueryActiveAlarmsRequest = pb.QueryActiveAlarmsRequest
+	StreamAlarmsRequest = pb.StreamAlarmsRequest
-	// ActiveAlarmSnapshot is one row in a ConditionRefresh stream.
+	// AlarmFeedMessage is one message on the StreamAlarms feed — an
+	// active-alarm snapshot row, a snapshot-complete sentinel, or a transition.
+	AlarmFeedMessage = pb.AlarmFeedMessage
+	// ActiveAlarmSnapshot is one currently-active alarm in the feed snapshot.
 	ActiveAlarmSnapshot = pb.ActiveAlarmSnapshot
 	// OnAlarmTransitionEvent is the body carried by alarm-transition MxEvents.
 	OnAlarmTransitionEvent = pb.OnAlarmTransitionEvent
@@ -126,9 +129,9 @@ type AlarmTransitionKind = pb.AlarmTransitionKind
 // ConditionRefresh snapshot.
 type AlarmConditionState = pb.AlarmConditionState
 
-// QueryActiveAlarmsClient is the generated server-streaming client for the
+// StreamAlarmsClient is the generated server-streaming client for the
-// QueryActiveAlarms RPC.
+// StreamAlarms RPC.
-type QueryActiveAlarmsClient = pb.MxAccessGateway_QueryActiveAlarmsClient
+type StreamAlarmsClient = pb.MxAccessGateway_StreamAlarmsClient
 
 // Enumerations from the generated contract re-exported for client callers.
 type (

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

@@ -3,6 +3,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.MxGatewayAlarmFeedSubscription;
 import com.dohertylan.mxgateway.client.MxGatewayClient;
 import com.dohertylan.mxgateway.client.MxGatewayClientOptions;
 import com.dohertylan.mxgateway.client.MxGatewayClientVersion;
@@ -28,14 +29,23 @@ import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
+import java.util.concurrent.ArrayBlockingQueue;
+import java.util.concurrent.BlockingQueue;
 import java.util.concurrent.Callable;
+import io.grpc.stub.StreamObserver;
+import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply;
+import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest;
+import mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage;
 import mxaccess_gateway.v1.MxaccessGateway.BulkReadResult;
 import mxaccess_gateway.v1.MxaccessGateway.BulkWriteResult;
 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.OnAlarmTransitionEvent;
 import mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest;
+import mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest;
 import mxaccess_gateway.v1.MxaccessGateway.SubscribeResult;
 import mxaccess_gateway.v1.MxaccessGateway.Write2BulkEntry;
 import mxaccess_gateway.v1.MxaccessGateway.WriteBulkEntry;
@@ -127,6 +137,8 @@ public final class MxGatewayCli implements Callable<Integer> {
         commandLine.addSubcommand("bench-read-bulk", new BenchReadBulkCommand(clientFactory));
         commandLine.addSubcommand("write", new WriteCommand(clientFactory));
         commandLine.addSubcommand("stream-events", new StreamEventsCommand(clientFactory));
+        commandLine.addSubcommand("stream-alarms", new StreamAlarmsCommand(clientFactory));
+        commandLine.addSubcommand("acknowledge-alarm", new AcknowledgeAlarmCommand(clientFactory));
         commandLine.addSubcommand("smoke", new SmokeCommand(clientFactory));
         commandLine.addSubcommand("galaxy-test", new GalaxyTestConnectionCommand());
         commandLine.addSubcommand("galaxy-deploy-time", new GalaxyDeployTimeCommand());
@@ -139,6 +151,9 @@ public final class MxGatewayCli implements Callable<Integer> {
     /** Sentinel written to stdout after every command result in batch mode. */
     static final String BATCH_EOR = "__MXGW_BATCH_EOR__";
 
+    /** Sentinel queued by {@code stream-alarms} to mark a clean end of the alarm feed. */
+    private static final Object ALARM_FEED_END = new Object();
+
     /**
      * Reads one CLI invocation per stdin line, executes each via a fresh
      * {@link CommandLine}, and writes {@value #BATCH_EOR} to stdout after
@@ -1155,6 +1170,115 @@ public final class MxGatewayCli implements Callable<Integer> {
         }
     }
 
+    @Command(name = "stream-alarms", description = "Streams the gateway central alarm feed.")
+    static final class StreamAlarmsCommand extends GatewayCommand {
+        @Option(names = "--filter-prefix", description = "Alarm-reference prefix scoping the feed; empty means unscoped.")
+        String filterPrefix = "";
+
+        @Option(names = "--limit", defaultValue = "0", description = "Maximum feed messages to print.")
+        int limit;
+
+        StreamAlarmsCommand(MxGatewayCliClientFactory clientFactory) {
+            super(clientFactory);
+        }
+
+        @Override
+        public Integer call() {
+            try (MxGatewayCliClient client = clientFactory.connect(common.resolved())) {
+                // The async alarm feed delivers on a background gRPC thread; buffer
+                // messages in a bounded queue and drain them on this thread so the
+                // --limit termination mirrors stream-events. 1024 absorbs the
+                // gateway's initial active-alarm snapshot burst.
+                BlockingQueue<Object> queue = new ArrayBlockingQueue<>(1024);
+                StreamAlarmsRequest request = StreamAlarmsRequest.newBuilder()
+                        .setAlarmFilterPrefix(filterPrefix)
+                        .build();
+                MxGatewayAlarmFeedSubscription subscription =
+                        client.streamAlarms(request, new StreamObserver<>() {
+                            @Override
+                            public void onNext(AlarmFeedMessage value) {
+                                queue.offer(value);
+                            }
+
+                            @Override
+                            public void onError(Throwable error) {
+                                queue.offer(error);
+                            }
+
+                            @Override
+                            public void onCompleted() {
+                                queue.offer(ALARM_FEED_END);
+                            }
+                        });
+                try {
+                    int count = 0;
+                    while (true) {
+                        Object item = queue.take();
+                        if (item == ALARM_FEED_END) {
+                            break;
+                        }
+                        if (item instanceof Throwable error) {
+                            throw new IllegalStateException(
+                                    "gateway stream alarms failed: " + error.getMessage(), error);
+                        }
+                        AlarmFeedMessage message = (AlarmFeedMessage) item;
+                        if (json) {
+                            client.out().println(protoJson(message));
+                        } else {
+                            client.out().println(formatAlarmFeedMessage(message));
+                        }
+                        client.out().flush();
+                        count++;
+                        if (limit > 0 && count >= limit) {
+                            subscription.cancel();
+                            break;
+                        }
+                    }
+                } catch (InterruptedException error) {
+                    Thread.currentThread().interrupt();
+                    subscription.cancel();
+                } finally {
+                    subscription.cancel();
+                }
+            }
+            return 0;
+        }
+    }
+
+    @Command(name = "acknowledge-alarm", description = "Acknowledges an active MXAccess alarm.")
+    static final class AcknowledgeAlarmCommand extends GatewayCommand {
+        @Option(names = "--reference", required = true, description = "Full alarm reference to acknowledge.")
+        String reference;
+
+        @Option(names = "--comment", description = "Operator acknowledge comment.")
+        String comment = "";
+
+        @Option(names = "--operator", description = "Operator user performing the acknowledge.")
+        String operator = "";
+
+        AcknowledgeAlarmCommand(MxGatewayCliClientFactory clientFactory) {
+            super(clientFactory);
+        }
+
+        @Override
+        public Integer call() {
+            try (MxGatewayCliClient client = clientFactory.connect(common.resolved())) {
+                AcknowledgeAlarmReply reply = client.acknowledgeAlarm(AcknowledgeAlarmRequest.newBuilder()
+                        .setAlarmFullReference(reference)
+                        .setComment(comment)
+                        .setOperatorUser(operator)
+                        .build());
+                writeOutput(
+                        "acknowledge-alarm",
+                        common,
+                        json,
+                        reply,
+                        () -> Integer.toString(reply.getHresult()));
+            }
+            return 0;
+        }
+    }
+
     @Command(name = "smoke", description = "Runs a bounded open/register/add/advise flow.")
     static final class SmokeCommand extends GatewayCommand {
         @Option(names = "--client-name", defaultValue = "mxgw-java-smoke", description = "MXAccess client name.")
@@ -1329,6 +1453,11 @@ public final class MxGatewayCli implements Callable<Integer> {
 
         MxGatewayCliSession session(String sessionId);
 
+        AcknowledgeAlarmReply acknowledgeAlarm(AcknowledgeAlarmRequest request);
+
+        MxGatewayAlarmFeedSubscription streamAlarms(
+                StreamAlarmsRequest request, StreamObserver<AlarmFeedMessage> observer);
+
         @Override
         void close();
     }
@@ -1401,6 +1530,17 @@ public final class MxGatewayCli implements Callable<Integer> {
             return new GrpcMxGatewayCliSession(MxGatewaySession.forSessionId(client, sessionId));
         }
 
+        @Override
+        public AcknowledgeAlarmReply acknowledgeAlarm(AcknowledgeAlarmRequest request) {
+            return client.acknowledgeAlarm(request);
+        }
+
+        @Override
+        public MxGatewayAlarmFeedSubscription streamAlarms(
+                StreamAlarmsRequest request, StreamObserver<AlarmFeedMessage> observer) {
+            return client.streamAlarms(request, observer);
+        }
+
         @Override
         public void close() {
             client.close();
@@ -1576,6 +1716,32 @@ public final class MxGatewayCli implements Callable<Integer> {
         return values;
     }
 
+    /**
+     * Renders one {@link AlarmFeedMessage} in the CLI's plain-text output
+     * style, distinguishing the active-alarm snapshot, snapshot-complete
+     * sentinel, and transition cases of the message's {@code payload} oneof.
+     */
+    private static String formatAlarmFeedMessage(AlarmFeedMessage message) {
+        return switch (message.getPayloadCase()) {
+            case ACTIVE_ALARM -> {
+                ActiveAlarmSnapshot alarm = message.getActiveAlarm();
+                yield String.format(
+                        "active-alarm %s state=%s severity=%d",
+                        alarm.getAlarmFullReference(), alarm.getCurrentState().name(), alarm.getSeverity());
+            }
+            case SNAPSHOT_COMPLETE -> "snapshot-complete";
+            case TRANSITION -> {
+                OnAlarmTransitionEvent transition = message.getTransition();
+                yield String.format(
+                        "transition %s kind=%s severity=%d",
+                        transition.getAlarmFullReference(),
+                        transition.getTransitionKind().name(),
+                        transition.getSeverity());
+            }
+            case PAYLOAD_NOT_SET -> "unknown";
+        };
+    }
+
     private static MxValue parseValue(String type, String text) {
         return switch (type) {
             case "bool" -> MxValues.boolValue(Boolean.parseBoolean(text));

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

@@ -8,10 +8,18 @@ import java.io.ByteArrayInputStream;
 import java.io.InputStream;
 import java.io.PrintWriter;
 import java.io.StringWriter;
+import com.dohertylan.mxgateway.client.MxGatewayAlarmFeedSubscription;
+import io.grpc.stub.StreamObserver;
 import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
 import java.util.List;
+import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply;
+import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest;
+import mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot;
 import mxaccess_gateway.v1.MxaccessGateway.AddItemReply;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmConditionState;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmTransitionKind;
 import mxaccess_gateway.v1.MxaccessGateway.BulkReadResult;
 import mxaccess_gateway.v1.MxaccessGateway.BulkWriteResult;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply;
@@ -20,9 +28,11 @@ import mxaccess_gateway.v1.MxaccessGateway.MxCommandKind;
 import mxaccess_gateway.v1.MxaccessGateway.MxCommandReply;
 import mxaccess_gateway.v1.MxaccessGateway.MxEvent;
 import mxaccess_gateway.v1.MxaccessGateway.MxValue;
+import mxaccess_gateway.v1.MxaccessGateway.OnAlarmTransitionEvent;
 import mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply;
 import mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest;
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
+import mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest;
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatusCode;
 import mxaccess_gateway.v1.MxaccessGateway.RegisterReply;
 import mxaccess_gateway.v1.MxaccessGateway.SessionState;
@@ -389,6 +399,70 @@ final class MxGatewayCliTests {
         assertTrue(output.contains("TestMachine_002.TestChangingInt"), output);
     }
 
+    // ---- stream-alarms / acknowledge-alarm subcommands ----
+
+    @Test
+    void streamAlarmsCommandForwardsFilterPrefixAndPrintsFeedMessages() {
+        FakeClientFactory factory = new FakeClientFactory();
+        CliRun run = execute(factory, "stream-alarms", "--filter-prefix", "Tank01");
+
+        assertEquals(0, run.exitCode());
+        assertEquals("Tank01", factory.client.lastStreamAlarmsRequest.getAlarmFilterPrefix());
+        String out = run.output();
+        assertTrue(out.contains("active-alarm Tank01.Level.HiHi"), out);
+        assertTrue(out.contains("snapshot-complete"), out);
+        assertTrue(out.contains("transition Tank01.Level.HiHi"), out);
+    }
+
+    @Test
+    void streamAlarmsCommandHonoursLimit() {
+        FakeClientFactory factory = new FakeClientFactory();
+        CliRun run = execute(factory, "stream-alarms", "--limit", "1");
+
+        assertEquals(0, run.exitCode());
+        long lines = run.output().lines().filter(line -> !line.isBlank()).count();
+        assertEquals(1, lines, "expected exactly one feed message with --limit 1, got: " + run.output());
+    }
+
+    @Test
+    void streamAlarmsCommandPrintsJson() {
+        FakeClientFactory factory = new FakeClientFactory();
+        CliRun run = execute(factory, "stream-alarms", "--json");
+
+        assertEquals(0, run.exitCode());
+        assertTrue(run.output().contains("\"activeAlarm\""), run.output());
+        assertTrue(run.output().contains("\"snapshotComplete\""), run.output());
+    }
+
+    @Test
+    void acknowledgeAlarmCommandForwardsOptionsAndPrintsReply() {
+        FakeClientFactory factory = new FakeClientFactory();
+        CliRun run = execute(
+                factory,
+                "acknowledge-alarm",
+                "--reference",
+                "Tank01.Level.HiHi",
+                "--comment",
+                "checked",
+                "--operator",
+                "operator1",
+                "--json");
+
+        assertEquals(0, run.exitCode());
+        assertEquals("Tank01.Level.HiHi", factory.client.lastAcknowledgeAlarmRequest.getAlarmFullReference());
+        assertEquals("checked", factory.client.lastAcknowledgeAlarmRequest.getComment());
+        assertEquals("operator1", factory.client.lastAcknowledgeAlarmRequest.getOperatorUser());
+        assertTrue(run.output().contains("\"command\":\"acknowledge-alarm\""), run.output());
+    }
+
+    @Test
+    void acknowledgeAlarmCommandRequiresReference() {
+        CliRun run = execute(new FakeClientFactory(), "acknowledge-alarm", "--comment", "checked");
+
+        assertFalse(run.exitCode() == 0, "expected non-zero exit without --reference");
+        assertTrue(run.errors().contains("--reference"), run.errors());
+    }
+
     // ---- Client.Java-027: batch subcommand ----
 
     @Test
@@ -501,6 +575,8 @@ final class MxGatewayCliTests {
         private final PrintWriter out;
         private final FakeSession session = new FakeSession();
         private boolean closeCalled;
+        private AcknowledgeAlarmRequest lastAcknowledgeAlarmRequest;
+        private StreamAlarmsRequest lastStreamAlarmsRequest;
 
         private FakeClient(PrintWriter out) {
             this.out = out;
@@ -534,6 +610,40 @@ final class MxGatewayCliTests {
             return session;
         }
 
+        @Override
+        public AcknowledgeAlarmReply acknowledgeAlarm(AcknowledgeAlarmRequest request) {
+            lastAcknowledgeAlarmRequest = request;
+            return AcknowledgeAlarmReply.newBuilder()
+                    .setCorrelationId(request.getClientCorrelationId())
+                    .setProtocolStatus(ok())
+                    .setHresult(0)
+                    .build();
+        }
+
+        @Override
+        public MxGatewayAlarmFeedSubscription streamAlarms(
+                StreamAlarmsRequest request, StreamObserver<AlarmFeedMessage> observer) {
+            lastStreamAlarmsRequest = request;
+            // Replay a deterministic active-alarm snapshot, snapshot-complete
+            // sentinel, transition, then complete the feed so the CLI command
+            // drains a bounded stream without contacting a live gateway.
+            observer.onNext(AlarmFeedMessage.newBuilder()
+                    .setActiveAlarm(ActiveAlarmSnapshot.newBuilder()
+                            .setAlarmFullReference("Tank01.Level.HiHi")
+                            .setCurrentState(AlarmConditionState.ALARM_CONDITION_STATE_ACTIVE)
+                            .setSeverity(700))
+                    .build());
+            observer.onNext(AlarmFeedMessage.newBuilder().setSnapshotComplete(true).build());
+            observer.onNext(AlarmFeedMessage.newBuilder()
+                    .setTransition(OnAlarmTransitionEvent.newBuilder()
+                            .setAlarmFullReference("Tank01.Level.HiHi")
+                            .setTransitionKind(AlarmTransitionKind.ALARM_TRANSITION_KIND_ACKNOWLEDGE)
+                            .setSeverity(700))
+                    .build());
+            observer.onCompleted();
+            return new MxGatewayAlarmFeedSubscription();
+        }
+
         @Override
         public void close() {
         }

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

@@ -5,33 +5,33 @@ import io.grpc.stub.ClientResponseObserver;
 import io.grpc.stub.StreamObserver;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicReference;
-import mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage;
-import mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest;
+import mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest;
 
 /**
- * Cancellable handle returned by {@code queryActiveAlarms}.
+ * Cancellable handle returned by {@code streamAlarms}.
  *
  * <p>Wraps a caller-supplied {@link StreamObserver} and exposes a
  * {@link #cancel()} entry point that aborts the underlying gRPC call. The
  * subscription also implements {@link AutoCloseable} so it can participate in
  * try-with-resources blocks.
  */
-public final class MxGatewayActiveAlarmsSubscription implements AutoCloseable {
+public final class MxGatewayAlarmFeedSubscription implements AutoCloseable {
-    private final AtomicReference<ClientCallStreamObserver<QueryActiveAlarmsRequest>> requestStream = new AtomicReference<>();
+    private final AtomicReference<ClientCallStreamObserver<StreamAlarmsRequest>> requestStream = new AtomicReference<>();
     private final AtomicBoolean cancelled = new AtomicBoolean();
 
-    ClientResponseObserver<QueryActiveAlarmsRequest, ActiveAlarmSnapshot> wrap(StreamObserver<ActiveAlarmSnapshot> observer) {
+    ClientResponseObserver<StreamAlarmsRequest, AlarmFeedMessage> wrap(StreamObserver<AlarmFeedMessage> observer) {
         return new ClientResponseObserver<>() {
             @Override
-            public void beforeStart(ClientCallStreamObserver<QueryActiveAlarmsRequest> stream) {
+            public void beforeStart(ClientCallStreamObserver<StreamAlarmsRequest> stream) {
                 requestStream.set(stream);
                 if (cancelled.get()) {
-                    stream.cancel("client cancelled active-alarms query", null);
+                    stream.cancel("client cancelled alarm feed", null);
                 }
             }
 
             @Override
-            public void onNext(ActiveAlarmSnapshot value) {
+            public void onNext(AlarmFeedMessage value) {
                 observer.onNext(value);
             }
 
@@ -54,9 +54,9 @@ public final class MxGatewayActiveAlarmsSubscription implements AutoCloseable {
      */
     public void cancel() {
         cancelled.set(true);
-        ClientCallStreamObserver<QueryActiveAlarmsRequest> stream = requestStream.get();
+        ClientCallStreamObserver<StreamAlarmsRequest> stream = requestStream.get();
         if (stream != null) {
-            stream.cancel("client cancelled active-alarms query", null);
+            stream.cancel("client cancelled alarm feed", null);
         }
     }
 

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

@@ -10,7 +10,7 @@ import java.util.concurrent.CompletableFuture;
 import mxaccess_gateway.v1.MxAccessGatewayGrpc;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest;
-import mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest;
 import mxaccess_gateway.v1.MxaccessGateway.MxCommandReply;
@@ -19,7 +19,7 @@ import mxaccess_gateway.v1.MxaccessGateway.MxEvent;
 import mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply;
 import mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest;
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatusCode;
-import mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest;
+import mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest;
 import mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest;
 
 /**
@@ -328,20 +328,24 @@ public final class MxGatewayClient implements AutoCloseable {
     }
 
     /**
-     * Streams a snapshot of all alarms currently Active or ActiveAcked — the
+     * Attaches to the gateway's central alarm feed. The stream opens with one
-     * gateway's ConditionRefresh equivalent. Used after reconnect to seed
+     * {@code AlarmFeedMessage} per currently-active alarm (the ConditionRefresh
-     * local Part 9 state.
+     * snapshot), then a single {@code snapshot_complete}, then a
+     * {@code transition} for every subsequent raise / acknowledge / clear.
      *
-     * @param request the {@code QueryActiveAlarmsRequest}, optionally scoped by
+     * <p>Served by the gateway's always-on alarm monitor — no worker session is
+     * opened — so any number of clients may attach.
+     *
+     * @param request the {@code StreamAlarmsRequest}, optionally scoped by
      *                alarm-reference prefix
-     * @param observer caller-supplied observer that receives snapshots and completion
+     * @param observer caller-supplied observer that receives feed messages and completion
      * @return a cancellable subscription handle
      */
-    public MxGatewayActiveAlarmsSubscription queryActiveAlarms(
+    public MxGatewayAlarmFeedSubscription streamAlarms(
-            QueryActiveAlarmsRequest request, StreamObserver<ActiveAlarmSnapshot> observer) {
+            StreamAlarmsRequest request, StreamObserver<AlarmFeedMessage> observer) {
-        MxGatewayActiveAlarmsSubscription subscription = new MxGatewayActiveAlarmsSubscription();
+        MxGatewayAlarmFeedSubscription subscription = new MxGatewayAlarmFeedSubscription();
         MxGatewayChannels.withStreamDeadline(rawAsyncStub(), options)
-                .queryActiveAlarms(request, subscription.wrap(observer));
+                .streamAlarms(request, subscription.wrap(observer));
         return subscription;
     }
 

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

@@ -30,10 +30,11 @@ import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest;
 import mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot;
 import mxaccess_gateway.v1.MxaccessGateway.AlarmConditionState;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage;
 import mxaccess_gateway.v1.MxaccessGateway.MxEvent;
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatusCode;
-import mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest;
+import mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest;
 import mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest;
 import org.junit.jupiter.api.Test;
 
@@ -57,7 +58,6 @@ final class MxGatewayLowFindingsTests {
                     AcknowledgeAlarmRequest request, StreamObserver<AcknowledgeAlarmReply> responseObserver) {
                 seen.set(request);
                 responseObserver.onNext(AcknowledgeAlarmReply.newBuilder()
-                        .setSessionId(request.getSessionId())
                         .setProtocolStatus(ok())
                         .setDiagnosticMessage("acked")
                         .build());
@@ -67,7 +67,6 @@ final class MxGatewayLowFindingsTests {
 
         try (Harness harness = Harness.start(service, "mxgw_keyid_secret", authorization)) {
             AcknowledgeAlarmReply reply = harness.client().acknowledgeAlarm(AcknowledgeAlarmRequest.newBuilder()
-                    .setSessionId("s-1")
                     .setAlarmFullReference("Area1.Pump.PV.HiHi")
                     .setComment("operator note")
                     .build());
@@ -84,7 +83,6 @@ final class MxGatewayLowFindingsTests {
             public void acknowledgeAlarm(
                     AcknowledgeAlarmRequest request, StreamObserver<AcknowledgeAlarmReply> responseObserver) {
                 responseObserver.onNext(AcknowledgeAlarmReply.newBuilder()
-                        .setSessionId(request.getSessionId())
                         .setProtocolStatus(ProtocolStatus.newBuilder()
                                 .setCode(ProtocolStatusCode.PROTOCOL_STATUS_CODE_SESSION_NOT_FOUND))
                         .build());
@@ -96,7 +94,7 @@ final class MxGatewayLowFindingsTests {
             assertThrows(
                     MxGatewayException.class,
                     () -> harness.client().acknowledgeAlarm(AcknowledgeAlarmRequest.newBuilder()
-                            .setSessionId("missing")
+                            .setAlarmFullReference("Area1.Pump.PV.HiHi")
                             .build()));
         }
     }
@@ -108,7 +106,6 @@ final class MxGatewayLowFindingsTests {
             public void acknowledgeAlarm(
                     AcknowledgeAlarmRequest request, StreamObserver<AcknowledgeAlarmReply> responseObserver) {
                 responseObserver.onNext(AcknowledgeAlarmReply.newBuilder()
-                        .setSessionId(request.getSessionId())
                         .setProtocolStatus(ok())
                         .setDiagnosticMessage("async-acked")
                         .build());
@@ -118,7 +115,9 @@ final class MxGatewayLowFindingsTests {
 
         try (Harness harness = Harness.start(service)) {
             CompletableFuture<AcknowledgeAlarmReply> future = harness.client()
-                    .acknowledgeAlarmAsync(AcknowledgeAlarmRequest.newBuilder().setSessionId("s-2").build());
+                    .acknowledgeAlarmAsync(AcknowledgeAlarmRequest.newBuilder()
+                            .setAlarmFullReference("Area1.Pump.PV.HiHi")
+                            .build());
             assertEquals("async-acked", future.get(5, TimeUnit.SECONDS).getDiagnosticMessage());
         }
     }
@@ -135,39 +134,45 @@ final class MxGatewayLowFindingsTests {
 
         try (Harness harness = Harness.start(service)) {
             CompletableFuture<AcknowledgeAlarmReply> future = harness.client()
-                    .acknowledgeAlarmAsync(AcknowledgeAlarmRequest.newBuilder().setSessionId("s-3").build());
+                    .acknowledgeAlarmAsync(AcknowledgeAlarmRequest.newBuilder()
+                            .setAlarmFullReference("Area1.Pump.PV.HiHi")
+                            .build());
             ExecutionException error = assertThrows(
                     ExecutionException.class, () -> future.get(5, TimeUnit.SECONDS));
             assertTrue(error.getCause() instanceof MxGatewayException, () -> String.valueOf(error.getCause()));
         }
     }
 
-    // --- Client.Java-007: QueryActiveAlarms RPC + subscription coverage ---
+    // --- Client.Java-007: StreamAlarms RPC + subscription coverage ---
 
     @Test
-    void queryActiveAlarmsDeliversSnapshotsToObserver() throws Exception {
+    void streamAlarmsDeliversFeedMessagesToObserver() throws Exception {
-        ActiveAlarmSnapshot snapshot = ActiveAlarmSnapshot.newBuilder()
+        AlarmFeedMessage active = AlarmFeedMessage.newBuilder()
+                .setActiveAlarm(ActiveAlarmSnapshot.newBuilder()
                         .setAlarmFullReference("Area1.Tank.Level.Hi")
                         .setSeverity(800)
-                .setCurrentState(AlarmConditionState.ALARM_CONDITION_STATE_ACTIVE)
+                        .setCurrentState(AlarmConditionState.ALARM_CONDITION_STATE_ACTIVE))
                 .build();
+        AlarmFeedMessage snapshotComplete =
+                AlarmFeedMessage.newBuilder().setSnapshotComplete(true).build();
         TestService service = new TestService() {
             @Override
-            public void queryActiveAlarms(
+            public void streamAlarms(
-                    QueryActiveAlarmsRequest request, StreamObserver<ActiveAlarmSnapshot> responseObserver) {
+                    StreamAlarmsRequest request, StreamObserver<AlarmFeedMessage> responseObserver) {
-                responseObserver.onNext(snapshot);
+                responseObserver.onNext(active);
+                responseObserver.onNext(snapshotComplete);
                 responseObserver.onCompleted();
             }
         };
 
         try (Harness harness = Harness.start(service)) {
-            List<ActiveAlarmSnapshot> received = new ArrayList<>();
+            List<AlarmFeedMessage> received = new ArrayList<>();
             CountDownLatch done = new CountDownLatch(1);
-            harness.client().queryActiveAlarms(
+            harness.client().streamAlarms(
-                    QueryActiveAlarmsRequest.newBuilder().setSessionId("s-4").build(),
+                    StreamAlarmsRequest.newBuilder().build(),
                     new StreamObserver<>() {
                         @Override
-                        public void onNext(ActiveAlarmSnapshot value) {
+                        public void onNext(AlarmFeedMessage value) {
                             received.add(value);
                         }
 
@@ -182,18 +187,19 @@ final class MxGatewayLowFindingsTests {
                         }
                     });
             assertTrue(done.await(5, TimeUnit.SECONDS), "stream should complete");
-            assertEquals(1, received.size());
+            assertEquals(2, received.size());
-            assertEquals("Area1.Tank.Level.Hi", received.get(0).getAlarmFullReference());
+            assertEquals("Area1.Tank.Level.Hi", received.get(0).getActiveAlarm().getAlarmFullReference());
+            assertTrue(received.get(1).getSnapshotComplete());
         }
     }
 
     @Test
-    void activeAlarmsSubscriptionCancelBeforeBeforeStartCancelsStream() {
+    void alarmFeedSubscriptionCancelBeforeBeforeStartCancelsStream() {
-        MxGatewayActiveAlarmsSubscription subscription = new MxGatewayActiveAlarmsSubscription();
+        MxGatewayAlarmFeedSubscription subscription = new MxGatewayAlarmFeedSubscription();
-        ClientResponseObserver<QueryActiveAlarmsRequest, ActiveAlarmSnapshot> observer =
+        ClientResponseObserver<StreamAlarmsRequest, AlarmFeedMessage> observer =
                 subscription.wrap(new StreamObserver<>() {
                     @Override
-                    public void onNext(ActiveAlarmSnapshot value) {
+                    public void onNext(AlarmFeedMessage value) {
                     }
 
                     @Override
@@ -204,13 +210,13 @@ final class MxGatewayLowFindingsTests {
                     public void onCompleted() {
                     }
                 });
-        RecordingActiveAlarmsRequestStream requestStream = new RecordingActiveAlarmsRequestStream();
+        RecordingAlarmFeedRequestStream requestStream = new RecordingAlarmFeedRequestStream();
 
         subscription.cancel();
         observer.beforeStart(requestStream);
 
         assertTrue(requestStream.cancelled);
-        assertEquals("client cancelled active-alarms query", requestStream.cancelMessage);
+        assertEquals("client cancelled alarm feed", requestStream.cancelMessage);
     }
 
     // --- Client.Java-007: async streamEvents + subscription cancellation ---
@@ -456,8 +462,8 @@ final class MxGatewayLowFindingsTests {
         }
     }
 
-    private static final class RecordingActiveAlarmsRequestStream
+    private static final class RecordingAlarmFeedRequestStream
-            extends ClientCallStreamObserver<QueryActiveAlarmsRequest> {
+            extends ClientCallStreamObserver<StreamAlarmsRequest> {
         private boolean cancelled;
         private String cancelMessage;
 
@@ -489,7 +495,7 @@ final class MxGatewayLowFindingsTests {
         }
 
         @Override
-        public void onNext(QueryActiveAlarmsRequest value) {
+        public void onNext(StreamAlarmsRequest value) {
         }
 
         @Override

clients/java/src/main/generated/main/grpc/mxaccess_gateway/v1/MxAccessGatewayGrpc.java

@@ -170,35 +170,35 @@ public final class MxAccessGatewayGrpc {
     return getAcknowledgeAlarmMethod;
   }
 
-  private static volatile io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest,
+  private static volatile io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest,
-      mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot> getQueryActiveAlarmsMethod;
+      mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage> getStreamAlarmsMethod;
 
   @io.grpc.stub.annotations.RpcMethod(
-      fullMethodName = SERVICE_NAME + '/' + "QueryActiveAlarms",
+      fullMethodName = SERVICE_NAME + '/' + "StreamAlarms",
-      requestType = mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest.class,
+      requestType = mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest.class,
-      responseType = mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot.class,
+      responseType = mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage.class,
       methodType = io.grpc.MethodDescriptor.MethodType.SERVER_STREAMING)
-  public static io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest,
+  public static io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest,
-      mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot> getQueryActiveAlarmsMethod() {
+      mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage> getStreamAlarmsMethod() {
-    io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest, mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot> getQueryActiveAlarmsMethod;
+    io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest, mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage> getStreamAlarmsMethod;
-    if ((getQueryActiveAlarmsMethod = MxAccessGatewayGrpc.getQueryActiveAlarmsMethod) == null) {
+    if ((getStreamAlarmsMethod = MxAccessGatewayGrpc.getStreamAlarmsMethod) == null) {
       synchronized (MxAccessGatewayGrpc.class) {
-        if ((getQueryActiveAlarmsMethod = MxAccessGatewayGrpc.getQueryActiveAlarmsMethod) == null) {
+        if ((getStreamAlarmsMethod = MxAccessGatewayGrpc.getStreamAlarmsMethod) == null) {
-          MxAccessGatewayGrpc.getQueryActiveAlarmsMethod = getQueryActiveAlarmsMethod =
+          MxAccessGatewayGrpc.getStreamAlarmsMethod = getStreamAlarmsMethod =
-              io.grpc.MethodDescriptor.<mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest, mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot>newBuilder()
+              io.grpc.MethodDescriptor.<mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest, mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage>newBuilder()
               .setType(io.grpc.MethodDescriptor.MethodType.SERVER_STREAMING)
-              .setFullMethodName(generateFullMethodName(SERVICE_NAME, "QueryActiveAlarms"))
+              .setFullMethodName(generateFullMethodName(SERVICE_NAME, "StreamAlarms"))
               .setSampledToLocalTracing(true)
               .setRequestMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
-                  mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest.getDefaultInstance()))
+                  mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest.getDefaultInstance()))
               .setResponseMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
-                  mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot.getDefaultInstance()))
+                  mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage.getDefaultInstance()))
-              .setSchemaDescriptor(new MxAccessGatewayMethodDescriptorSupplier("QueryActiveAlarms"))
+              .setSchemaDescriptor(new MxAccessGatewayMethodDescriptorSupplier("StreamAlarms"))
               .build();
         }
       }
     }
-    return getQueryActiveAlarmsMethod;
+    return getStreamAlarmsMethod;
   }
 
   /**
@@ -303,10 +303,17 @@ public final class MxAccessGatewayGrpc {
     }
 
     /**
+     * <pre>
+     * Session-less central alarm feed. The stream opens with the current
+     * active-alarm snapshot (one `active_alarm` per alarm), then a single
+     * `snapshot_complete`, then a `transition` for every subsequent change.
+     * Served by the gateway's always-on alarm monitor; any number of clients
+     * fan out from the single monitor without opening a worker session.
+     * </pre>
      */
-    default void queryActiveAlarms(mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest request,
+    default void streamAlarms(mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest request,
-        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot> responseObserver) {
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage> responseObserver) {
-      io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getQueryActiveAlarmsMethod(), responseObserver);
+      io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getStreamAlarmsMethod(), responseObserver);
     }
   }
 
@@ -384,11 +391,18 @@ public final class MxAccessGatewayGrpc {
     }
 
     /**
+     * <pre>
+     * Session-less central alarm feed. The stream opens with the current
+     * active-alarm snapshot (one `active_alarm` per alarm), then a single
+     * `snapshot_complete`, then a `transition` for every subsequent change.
+     * Served by the gateway's always-on alarm monitor; any number of clients
+     * fan out from the single monitor without opening a worker session.
+     * </pre>
      */
-    public void queryActiveAlarms(mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest request,
+    public void streamAlarms(mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest request,
-        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot> responseObserver) {
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage> responseObserver) {
       io.grpc.stub.ClientCalls.asyncServerStreamingCall(
-          getChannel().newCall(getQueryActiveAlarmsMethod(), getCallOptions()), request, responseObserver);
+          getChannel().newCall(getStreamAlarmsMethod(), getCallOptions()), request, responseObserver);
     }
   }
 
@@ -449,12 +463,19 @@ public final class MxAccessGatewayGrpc {
     }
 
     /**
+     * <pre>
+     * Session-less central alarm feed. The stream opens with the current
+     * active-alarm snapshot (one `active_alarm` per alarm), then a single
+     * `snapshot_complete`, then a `transition` for every subsequent change.
+     * Served by the gateway's always-on alarm monitor; any number of clients
+     * fan out from the single monitor without opening a worker session.
+     * </pre>
      */
     @io.grpc.ExperimentalApi("https://github.com/grpc/grpc-java/issues/10918")
-    public io.grpc.stub.BlockingClientCall<?, mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot>
+    public io.grpc.stub.BlockingClientCall<?, mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage>
-        queryActiveAlarms(mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest request) {
+        streamAlarms(mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest request) {
       return io.grpc.stub.ClientCalls.blockingV2ServerStreamingCall(
-          getChannel(), getQueryActiveAlarmsMethod(), getCallOptions(), request);
+          getChannel(), getStreamAlarmsMethod(), getCallOptions(), request);
     }
   }
 
@@ -514,11 +535,18 @@ public final class MxAccessGatewayGrpc {
     }
 
     /**
+     * <pre>
+     * Session-less central alarm feed. The stream opens with the current
+     * active-alarm snapshot (one `active_alarm` per alarm), then a single
+     * `snapshot_complete`, then a `transition` for every subsequent change.
+     * Served by the gateway's always-on alarm monitor; any number of clients
+     * fan out from the single monitor without opening a worker session.
+     * </pre>
      */
-    public java.util.Iterator<mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot> queryActiveAlarms(
+    public java.util.Iterator<mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage> streamAlarms(
-        mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest request) {
+        mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest request) {
       return io.grpc.stub.ClientCalls.blockingServerStreamingCall(
-          getChannel(), getQueryActiveAlarmsMethod(), getCallOptions(), request);
+          getChannel(), getStreamAlarmsMethod(), getCallOptions(), request);
     }
   }
 
@@ -579,7 +607,7 @@ public final class MxAccessGatewayGrpc {
   private static final int METHODID_INVOKE = 2;
   private static final int METHODID_STREAM_EVENTS = 3;
   private static final int METHODID_ACKNOWLEDGE_ALARM = 4;
-  private static final int METHODID_QUERY_ACTIVE_ALARMS = 5;
+  private static final int METHODID_STREAM_ALARMS = 5;
 
   private static final class MethodHandlers<Req, Resp> implements
       io.grpc.stub.ServerCalls.UnaryMethod<Req, Resp>,
@@ -618,9 +646,9 @@ public final class MxAccessGatewayGrpc {
           serviceImpl.acknowledgeAlarm((mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest) request,
               (io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply>) responseObserver);
           break;
-        case METHODID_QUERY_ACTIVE_ALARMS:
+        case METHODID_STREAM_ALARMS:
-          serviceImpl.queryActiveAlarms((mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest) request,
+          serviceImpl.streamAlarms((mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest) request,
-              (io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot>) responseObserver);
+              (io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage>) responseObserver);
           break;
         default:
           throw new AssertionError();
@@ -676,12 +704,12 @@ public final class MxAccessGatewayGrpc {
               mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply>(
                 service, METHODID_ACKNOWLEDGE_ALARM)))
         .addMethod(
-          getQueryActiveAlarmsMethod(),
+          getStreamAlarmsMethod(),
           io.grpc.stub.ServerCalls.asyncServerStreamingCall(
             new MethodHandlers<
-              mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest,
+              mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest,
-              mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot>(
+              mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage>(
-                service, METHODID_QUERY_ACTIVE_ALARMS)))
+                service, METHODID_STREAM_ALARMS)))
         .build();
   }
 
@@ -735,7 +763,7 @@ public final class MxAccessGatewayGrpc {
               .addMethod(getInvokeMethod())
               .addMethod(getStreamEventsMethod())
               .addMethod(getAcknowledgeAlarmMethod())
-              .addMethod(getQueryActiveAlarmsMethod())
+              .addMethod(getStreamAlarmsMethod())
               .build();
         }
       }

clients/python/src/mxgateway/client.py

@@ -166,25 +166,27 @@ class GatewayClient:
         ensure_protocol_success("acknowledge alarm", reply.protocol_status, reply)
         return reply
 
-    def query_active_alarms(
+    def stream_alarms(
         self,
-        request: pb.QueryActiveAlarmsRequest,
+        request: pb.StreamAlarmsRequest,
         *,
         metadata: Sequence[tuple[str, str]] | None = None,
-    ) -> AsyncIterator[pb.ActiveAlarmSnapshot]:
+    ) -> AsyncIterator[pb.AlarmFeedMessage]:
-        """Stream a snapshot of all alarms currently Active or ActiveAcked.
+        """Attach to the gateway's central alarm feed.
 
-        The gateway's ConditionRefresh equivalent. Use after reconnect to seed
+        The stream opens with one ``AlarmFeedMessage`` per currently-active
-        local Part 9 state, or to reconcile alarms that may have been missed
+        alarm (the ConditionRefresh snapshot), then a single
-        during a transport blip. Optionally scoped by alarm-reference prefix
+        ``snapshot_complete``, then a ``transition`` for every subsequent
-        (``request.alarm_filter_prefix``) so a partial refresh can target an
+        raise / acknowledge / clear. Served by the gateway's always-on alarm
-        equipment sub-tree.
+        monitor — no worker session is opened — so any number of clients may
+        attach. Optionally scoped by alarm-reference prefix
+        (``request.alarm_filter_prefix``).
         """
         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 = _open_stream(self.raw_stub.QueryActiveAlarms, request, kwargs)
+        call = _open_stream(self.raw_stub.StreamAlarms, request, kwargs)
-        return _canceling_iterator(call, "query active alarms")
+        return _canceling_iterator(call, "stream alarms")
 
     async def _unary(
         self,

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

@@ -30,8 +30,7 @@ class MxAccessGatewayStub(object):
     additively only. Never renumber or repurpose an existing field number or
     enum value. When a field or enum value is removed, add a `reserved` range
     (and `reserved` name) covering it in the same change so a future editor
-    cannot accidentally reuse the retired tag. There are no `reserved`
+    cannot accidentally reuse the retired tag.
-    declarations today because no field or enum value has ever been removed.
 
     Public client API for MXAccess sessions hosted by the gateway.
     """
@@ -67,10 +66,10 @@ class MxAccessGatewayStub(object):
                 request_serializer=mxaccess__gateway__pb2.AcknowledgeAlarmRequest.SerializeToString,
                 response_deserializer=mxaccess__gateway__pb2.AcknowledgeAlarmReply.FromString,
                 _registered_method=True)
-        self.QueryActiveAlarms = channel.unary_stream(
+        self.StreamAlarms = channel.unary_stream(
-                '/mxaccess_gateway.v1.MxAccessGateway/QueryActiveAlarms',
+                '/mxaccess_gateway.v1.MxAccessGateway/StreamAlarms',
-                request_serializer=mxaccess__gateway__pb2.QueryActiveAlarmsRequest.SerializeToString,
+                request_serializer=mxaccess__gateway__pb2.StreamAlarmsRequest.SerializeToString,
-                response_deserializer=mxaccess__gateway__pb2.ActiveAlarmSnapshot.FromString,
+                response_deserializer=mxaccess__gateway__pb2.AlarmFeedMessage.FromString,
                 _registered_method=True)
 
 
@@ -79,8 +78,7 @@ class MxAccessGatewayServicer(object):
     additively only. Never renumber or repurpose an existing field number or
     enum value. When a field or enum value is removed, add a `reserved` range
     (and `reserved` name) covering it in the same change so a future editor
-    cannot accidentally reuse the retired tag. There are no `reserved`
+    cannot accidentally reuse the retired tag.
-    declarations today because no field or enum value has ever been removed.
 
     Public client API for MXAccess sessions hosted by the gateway.
     """
@@ -115,8 +113,13 @@ class MxAccessGatewayServicer(object):
         context.set_details('Method not implemented!')
         raise NotImplementedError('Method not implemented!')
 
-    def QueryActiveAlarms(self, request, context):
+    def StreamAlarms(self, request, context):
-        """Missing associated documentation comment in .proto file."""
+        """Session-less central alarm feed. The stream opens with the current
+        active-alarm snapshot (one `active_alarm` per alarm), then a single
+        `snapshot_complete`, then a `transition` for every subsequent change.
+        Served by the gateway's always-on alarm monitor; any number of clients
+        fan out from the single monitor without opening a worker session.
+        """
         context.set_code(grpc.StatusCode.UNIMPLEMENTED)
         context.set_details('Method not implemented!')
         raise NotImplementedError('Method not implemented!')
@@ -149,10 +152,10 @@ def add_MxAccessGatewayServicer_to_server(servicer, server):
                     request_deserializer=mxaccess__gateway__pb2.AcknowledgeAlarmRequest.FromString,
                     response_serializer=mxaccess__gateway__pb2.AcknowledgeAlarmReply.SerializeToString,
             ),
-            'QueryActiveAlarms': grpc.unary_stream_rpc_method_handler(
+            'StreamAlarms': grpc.unary_stream_rpc_method_handler(
-                    servicer.QueryActiveAlarms,
+                    servicer.StreamAlarms,
-                    request_deserializer=mxaccess__gateway__pb2.QueryActiveAlarmsRequest.FromString,
+                    request_deserializer=mxaccess__gateway__pb2.StreamAlarmsRequest.FromString,
-                    response_serializer=mxaccess__gateway__pb2.ActiveAlarmSnapshot.SerializeToString,
+                    response_serializer=mxaccess__gateway__pb2.AlarmFeedMessage.SerializeToString,
             ),
     }
     generic_handler = grpc.method_handlers_generic_handler(
@@ -167,8 +170,7 @@ class MxAccessGateway(object):
     additively only. Never renumber or repurpose an existing field number or
     enum value. When a field or enum value is removed, add a `reserved` range
     (and `reserved` name) covering it in the same change so a future editor
-    cannot accidentally reuse the retired tag. There are no `reserved`
+    cannot accidentally reuse the retired tag.
-    declarations today because no field or enum value has ever been removed.
 
     Public client API for MXAccess sessions hosted by the gateway.
     """
@@ -309,7 +311,7 @@ class MxAccessGateway(object):
             _registered_method=True)
 
     @staticmethod
-    def QueryActiveAlarms(request,
+    def StreamAlarms(request,
             target,
             options=(),
             channel_credentials=None,
@@ -322,9 +324,9 @@ class MxAccessGateway(object):
         return grpc.experimental.unary_stream(
             request,
             target,
-            '/mxaccess_gateway.v1.MxAccessGateway/QueryActiveAlarms',
+            '/mxaccess_gateway.v1.MxAccessGateway/StreamAlarms',
-            mxaccess__gateway__pb2.QueryActiveAlarmsRequest.SerializeToString,
+            mxaccess__gateway__pb2.StreamAlarmsRequest.SerializeToString,
-            mxaccess__gateway__pb2.ActiveAlarmSnapshot.FromString,
+            mxaccess__gateway__pb2.AlarmFeedMessage.FromString,
             options,
             channel_credentials,
             insecure,

clients/python/src/mxgateway_cli/commands.py

@@ -404,6 +404,40 @@ def stream_events(**kwargs: Any) -> None:
     )
 
 
+@main.command("stream-alarms")
+@gateway_options
+@click.option("--filter-prefix", default="", help="Alarm-reference prefix filter.")
+@click.option("--max-messages", default=1, type=int, show_default=True)
+@click.option("--timeout", default=5.0, type=float, show_default=True)
+@click.option("--correlation-id", default="", help="Client correlation id.")
+@click.option("--json", "output_json", is_flag=True, help="Emit JSON output.")
+def stream_alarms(**kwargs: Any) -> None:
+    """Stream a bounded number of messages from the gateway's central alarm feed."""
+
+    _run(
+        _stream_alarms(**kwargs),
+        output_json=kwargs["output_json"],
+        secrets=_secrets(kwargs),
+    )
+
+
+@main.command("acknowledge-alarm")
+@gateway_options
+@click.option("--reference", required=True, help="Alarm full reference to acknowledge.")
+@click.option("--comment", default="", help="Acknowledgement comment.")
+@click.option("--operator", default="", help="Operator user name.")
+@click.option("--correlation-id", default="", help="Client correlation id.")
+@click.option("--json", "output_json", is_flag=True, help="Emit JSON output.")
+def acknowledge_alarm(**kwargs: Any) -> None:
+    """Acknowledge an active MXAccess alarm condition (session-less)."""
+
+    _run(
+        _acknowledge_alarm(**kwargs),
+        output_json=kwargs["output_json"],
+        secrets=_secrets(kwargs),
+    )
+
+
 @main.command()
 @gateway_options
 @click.option("--session-id", required=True, help="Gateway session id.")
@@ -779,6 +813,34 @@ async def _stream_events(**kwargs: Any) -> dict[str, Any]:
         return {"events": [_message_dict(event) for event in events]}
 
 
+async def _stream_alarms(**kwargs: Any) -> dict[str, Any]:
+    async with await _connect(kwargs) as client:
+        messages = await _collect_alarm_messages(
+            client.stream_alarms(
+                pb.StreamAlarmsRequest(
+                    client_correlation_id=kwargs["correlation_id"],
+                    alarm_filter_prefix=kwargs["filter_prefix"],
+                ),
+            ),
+            max_messages=kwargs["max_messages"],
+            timeout=kwargs["timeout"],
+        )
+        return {"messages": [_message_dict(message) for message in messages]}
+
+
+async def _acknowledge_alarm(**kwargs: Any) -> dict[str, Any]:
+    async with await _connect(kwargs) as client:
+        reply = await client.acknowledge_alarm(
+            pb.AcknowledgeAlarmRequest(
+                client_correlation_id=kwargs["correlation_id"],
+                alarm_full_reference=kwargs["reference"],
+                comment=kwargs["comment"],
+                operator_user=kwargs["operator"],
+            ),
+        )
+        return {"rawReply": _message_dict(reply)}
+
+
 async def _write(**kwargs: Any) -> dict[str, Any]:
     value = _parse_value(kwargs["value"], kwargs["value_type"])
     async with await _connect(kwargs) as client:
@@ -936,6 +998,34 @@ async def _collect_events(
     return collected
 
 
+async def _collect_alarm_messages(
+    messages: Any,
+    *,
+    max_messages: int,
+    timeout: float,
+) -> list[pb.AlarmFeedMessage]:
+    if max_messages > MAX_AGGREGATE_EVENTS:
+        raise click.BadParameter(
+            f"must be less than or equal to {MAX_AGGREGATE_EVENTS}",
+            param_hint="--max-messages",
+        )
+
+    collected: list[pb.AlarmFeedMessage] = []
+    iterator = messages.__aiter__()
+    try:
+        while len(collected) < max_messages:
+            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:
+            await close()
+    return collected
+
+
 def _parse_value(raw_value: str, value_type: str) -> MxValueInput:
     normalized = value_type.lower()
     if normalized == "bool":

clients/python/tests/test_alarms.py

@@ -1,8 +1,7 @@
-"""Tests for the AcknowledgeAlarm + QueryActiveAlarms client surface (PR E.3)."""
+"""Tests for the AcknowledgeAlarm + StreamAlarms client surface."""
 
 from __future__ import annotations
 
-import asyncio
 from typing import Any
 
 import grpc
@@ -18,7 +17,6 @@ async def test_acknowledge_alarm_sends_request_and_returns_reply() -> None:
     stub = FakeGatewayStub()
     stub.acknowledge_alarm.replies = [
         pb.AcknowledgeAlarmReply(
-            session_id="session-1",
             correlation_id="corr-7",
             protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
             status=pb.MxStatusProxy(success=1, category=pb.MX_STATUS_CATEGORY_OK),
@@ -31,7 +29,6 @@ async def test_acknowledge_alarm_sends_request_and_returns_reply() -> None:
 
     reply = await client.acknowledge_alarm(
         pb.AcknowledgeAlarmRequest(
-            session_id="session-1",
             client_correlation_id="corr-7",
             alarm_full_reference="Tank01.Level.HiHi",
             comment="investigating",
@@ -61,7 +58,6 @@ async def test_acknowledge_alarm_unauthenticated_raises_typed_error() -> None:
     with pytest.raises(MxGatewayAuthenticationError):
         await client.acknowledge_alarm(
             pb.AcknowledgeAlarmRequest(
-                session_id="session-1",
                 alarm_full_reference="Tank01.Level.HiHi",
                 comment="",
                 operator_user="alice",
@@ -81,7 +77,6 @@ async def test_acknowledge_alarm_permission_denied_raises_typed_error() -> None:
     with pytest.raises(MxGatewayAuthorizationError):
         await client.acknowledge_alarm(
             pb.AcknowledgeAlarmRequest(
-                session_id="session-1",
                 alarm_full_reference="Tank01.Level.HiHi",
                 comment="",
                 operator_user="alice",
@@ -90,84 +85,90 @@ async def test_acknowledge_alarm_permission_denied_raises_typed_error() -> None:
 
 
 @pytest.mark.asyncio
-async def test_query_active_alarms_streams_snapshots() -> None:
+async def test_stream_alarms_streams_snapshot_then_snapshot_complete() -> None:
-    snapshots = [
+    messages = [
-        pb.ActiveAlarmSnapshot(
+        pb.AlarmFeedMessage(
+            active_alarm=pb.ActiveAlarmSnapshot(
                 alarm_full_reference="Tank01.Level.HiHi",
                 current_state=pb.ALARM_CONDITION_STATE_ACTIVE,
                 severity=750,
             ),
-        pb.ActiveAlarmSnapshot(
+        ),
+        pb.AlarmFeedMessage(
+            active_alarm=pb.ActiveAlarmSnapshot(
                 alarm_full_reference="Tank02.Level.HiHi",
                 current_state=pb.ALARM_CONDITION_STATE_ACTIVE_ACKED,
                 severity=750,
             ),
+        ),
+        pb.AlarmFeedMessage(snapshot_complete=True),
     ]
-    stream = FakeSnapshotStream(snapshots)
+    stream = FakeAlarmFeedStream(messages)
-    stub = FakeGatewayStub(snapshot_stream=stream)
+    stub = FakeGatewayStub(alarm_feed_stream=stream)
     client = await GatewayClient.connect(
         ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
         stub=stub,
     )
 
-    received: list[pb.ActiveAlarmSnapshot] = []
+    received: list[pb.AlarmFeedMessage] = []
-    async for snapshot in client.query_active_alarms(
+    async for message in client.stream_alarms(pb.StreamAlarmsRequest()):
-        pb.QueryActiveAlarmsRequest(session_id="session-1"),
+        received.append(message)
-    ):
-        received.append(snapshot)
 
-    assert len(received) == 2
+    assert len(received) == 3
-    assert received[0].alarm_full_reference == "Tank01.Level.HiHi"
+    assert received[0].active_alarm.alarm_full_reference == "Tank01.Level.HiHi"
-    assert received[0].current_state == pb.ALARM_CONDITION_STATE_ACTIVE
+    assert received[0].active_alarm.current_state == pb.ALARM_CONDITION_STATE_ACTIVE
-    assert received[1].current_state == pb.ALARM_CONDITION_STATE_ACTIVE_ACKED
+    assert received[1].active_alarm.current_state == pb.ALARM_CONDITION_STATE_ACTIVE_ACKED
-    assert stub.query_metadata == (("authorization", "Bearer mxgw_test_secret"),)
+    assert received[2].snapshot_complete is True
+    assert stub.stream_metadata == (("authorization", "Bearer mxgw_test_secret"),)
 
 
 @pytest.mark.asyncio
-async def test_query_active_alarms_passes_filter_prefix() -> None:
+async def test_stream_alarms_passes_filter_prefix() -> None:
-    stream = FakeSnapshotStream([])
+    stream = FakeAlarmFeedStream([])
-    stub = FakeGatewayStub(snapshot_stream=stream)
+    stub = FakeGatewayStub(alarm_feed_stream=stream)
     client = await GatewayClient.connect(
         ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
         stub=stub,
     )
 
-    iterator = client.query_active_alarms(
+    iterator = client.stream_alarms(
-        pb.QueryActiveAlarmsRequest(session_id="session-1", alarm_filter_prefix="Tank01."),
+        pb.StreamAlarmsRequest(alarm_filter_prefix="Tank01."),
     )
     # Drain to trigger the stub call.
     async for _ in iterator:
         pass
 
-    assert stub.query_request is not None
+    assert stub.stream_request is not None
-    assert stub.query_request.alarm_filter_prefix == "Tank01."
+    assert stub.stream_request.alarm_filter_prefix == "Tank01."
 
 
 @pytest.mark.asyncio
-async def test_query_active_alarms_cancels_underlying_stream_on_close() -> None:
+async def test_stream_alarms_cancels_underlying_stream_on_close() -> None:
-    snapshots = [
+    messages = [
-        pb.ActiveAlarmSnapshot(
+        pb.AlarmFeedMessage(
+            active_alarm=pb.ActiveAlarmSnapshot(
                 alarm_full_reference="Tank01.Level.HiHi",
                 current_state=pb.ALARM_CONDITION_STATE_ACTIVE,
             ),
+        ),
     ]
-    stream = FakeSnapshotStream(snapshots)
+    stream = FakeAlarmFeedStream(messages)
-    stub = FakeGatewayStub(snapshot_stream=stream)
+    stub = FakeGatewayStub(alarm_feed_stream=stream)
     client = await GatewayClient.connect(
         ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
         stub=stub,
     )
 
-    iterator = client.query_active_alarms(pb.QueryActiveAlarmsRequest(session_id="session-1"))
+    iterator = client.stream_alarms(pb.StreamAlarmsRequest())
     first = await anext(iterator)
     await iterator.aclose()
 
-    assert first.alarm_full_reference == "Tank01.Level.HiHi"
+    assert first.active_alarm.alarm_full_reference == "Tank01.Level.HiHi"
     assert stream.cancelled
 
 
 class FakeGatewayStub:
-    def __init__(self, snapshot_stream: "FakeSnapshotStream | None" = None) -> None:
+    def __init__(self, alarm_feed_stream: "FakeAlarmFeedStream | None" = None) -> None:
         self.open_session = FakeUnary(
             [
                 pb.OpenSessionReply(
@@ -179,19 +180,19 @@ class FakeGatewayStub:
         self.acknowledge_alarm = FakeUnary([])
         self.OpenSession = self.open_session
         self.AcknowledgeAlarm = self.acknowledge_alarm
-        self._snapshot_stream = snapshot_stream or FakeSnapshotStream([])
+        self._alarm_feed_stream = alarm_feed_stream or FakeAlarmFeedStream([])
-        self.query_request: pb.QueryActiveAlarmsRequest | None = None
+        self.stream_request: pb.StreamAlarmsRequest | None = None
-        self.query_metadata: tuple[tuple[str, str], ...] | None = None
+        self.stream_metadata: tuple[tuple[str, str], ...] | None = None
 
-    def QueryActiveAlarms(
+    def StreamAlarms(
         self,
-        request: pb.QueryActiveAlarmsRequest,
+        request: pb.StreamAlarmsRequest,
         *,
         metadata: tuple[tuple[str, str], ...],
-    ) -> "FakeSnapshotStream":
+    ) -> "FakeAlarmFeedStream":
-        self.query_request = request
+        self.stream_request = request
-        self.query_metadata = metadata
+        self.stream_metadata = metadata
-        return self._snapshot_stream
+        return self._alarm_feed_stream
 
 
 class FakeUnary:
@@ -214,18 +215,18 @@ class FakeUnary:
         return self.replies.pop(0)
 
 
-class FakeSnapshotStream:
+class FakeAlarmFeedStream:
-    def __init__(self, snapshots: list[pb.ActiveAlarmSnapshot]) -> None:
+    def __init__(self, messages: list[pb.AlarmFeedMessage]) -> None:
-        self._snapshots = list(snapshots)
+        self._messages = list(messages)
         self.cancelled = False
 
-    def __aiter__(self) -> "FakeSnapshotStream":
+    def __aiter__(self) -> "FakeAlarmFeedStream":
         return self
 
-    async def __anext__(self) -> pb.ActiveAlarmSnapshot:
+    async def __anext__(self) -> pb.AlarmFeedMessage:
-        if not self._snapshots:
+        if not self._messages:
             raise StopAsyncIteration
-        return self._snapshots.pop(0)
+        return self._messages.pop(0)
 
     def cancel(self) -> None:
         self.cancelled = True

clients/python/tests/test_cli.py

@@ -52,6 +52,28 @@ def test_write_parser_rejects_unknown_value_type() -> None:
     assert "unsupported value type" in result.output
 
 
+def test_stream_alarms_is_registered() -> None:
+    runner = CliRunner()
+
+    result = runner.invoke(main, ["stream-alarms", "--help"])
+
+    assert result.exit_code == 0
+    assert "--filter-prefix" in result.output
+    assert "--max-messages" in result.output
+
+
+def test_acknowledge_alarm_requires_reference() -> None:
+    runner = CliRunner()
+
+    result = runner.invoke(
+        main,
+        ["acknowledge-alarm", "--api-key", "mxgw_test_secret", "--json"],
+    )
+
+    assert result.exit_code != 0
+    assert "--reference" in result.output
+
+
 def test_cli_error_output_redacts_api_key() -> None:
     runner = CliRunner()
 

clients/python/tests/test_stream_timeout_fallback.py

@@ -1,6 +1,6 @@
 """Regression tests for Client.Python-003: stream timeout-kwarg fallback.
 
-`stream_events_raw` and `query_active_alarms` must tolerate a fake/older stub
+`stream_events_raw` and `stream_alarms` must tolerate a fake/older stub
 that does not accept a ``timeout`` keyword argument, matching the fallback
 already present in `galaxy.watch_deploy_events` and the unary `_unary` helper.
 """
@@ -51,9 +51,9 @@ class _NoTimeoutStubStreamEvents:
         self.StreamEvents = stream
 
 
-class _NoTimeoutStubQueryAlarms:
+class _NoTimeoutStubStreamAlarms:
     def __init__(self, stream: _NoTimeoutStream) -> None:
-        self.QueryActiveAlarms = stream
+        self.StreamAlarms = stream
 
 
 @pytest.mark.asyncio
@@ -78,24 +78,30 @@ async def test_stream_events_raw_falls_back_when_stub_rejects_timeout() -> None:
 
 
 @pytest.mark.asyncio
-async def test_query_active_alarms_falls_back_when_stub_rejects_timeout() -> None:
+async def test_stream_alarms_falls_back_when_stub_rejects_timeout() -> None:
     stream = _NoTimeoutStream(
-        [pb.ActiveAlarmSnapshot(alarm_full_reference="Tank01.Level.HiHi")],
+        [
+            pb.AlarmFeedMessage(
+                active_alarm=pb.ActiveAlarmSnapshot(
+                    alarm_full_reference="Tank01.Level.HiHi",
+                ),
+            ),
+        ],
     )
     client = await GatewayClient.connect(
         ClientOptions(endpoint="fake", plaintext=True, stream_timeout=5.0),
-        stub=_NoTimeoutStubQueryAlarms(stream),
+        stub=_NoTimeoutStubStreamAlarms(stream),
     )
 
     received = [
-        snapshot
+        message
-        async for snapshot in client.query_active_alarms(
+        async for message in client.stream_alarms(
-            pb.QueryActiveAlarmsRequest(session_id="session-1"),
+            pb.StreamAlarmsRequest(),
         )
     ]
 
     assert len(received) == 1
-    assert received[0].alarm_full_reference == "Tank01.Level.HiHi"
+    assert received[0].active_alarm.alarm_full_reference == "Tank01.Level.HiHi"
 
 
 @pytest.mark.asyncio

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

@@ -18,8 +18,9 @@ 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, MxEvent, MxEventFamily,
+    alarm_feed_message, AcknowledgeAlarmRequest, AlarmFeedMessage, CloseSessionRequest, MxCommand,
-    MxValue as ProtoMxValue, OpenSessionRequest, PingCommand, StreamEventsRequest, Write2BulkEntry,
+    MxCommandKind, MxCommandRequest, MxEvent, MxEventFamily, MxValue as ProtoMxValue,
+    OpenSessionRequest, PingCommand, StreamAlarmsRequest, StreamEventsRequest, Write2BulkEntry,
     WriteBulkEntry, WriteSecured2BulkEntry, WriteSecuredBulkEntry,
 };
 use mxgateway_client::{
@@ -272,6 +273,24 @@ enum Command {
         #[arg(long)]
         jsonl: bool,
     },
+    /// Attach to the gateway's session-less central alarm feed. The stream
+    /// opens with one `active_alarm` per currently-active alarm, then a
+    /// single `snapshot_complete`, then a `transition` for every subsequent
+    /// raise / acknowledge / clear.
+    StreamAlarms {
+        #[command(flatten)]
+        connection: ConnectionArgs,
+        /// Optional alarm-reference prefix scoping the feed to an equipment
+        /// sub-tree. Omit to stream every active alarm.
+        #[arg(long)]
+        filter_prefix: Option<String>,
+        #[arg(long, default_value_t = 1)]
+        max_events: usize,
+        #[arg(long)]
+        json: bool,
+        #[arg(long)]
+        jsonl: bool,
+    },
     Write {
         #[command(flatten)]
         connection: ConnectionArgs,
@@ -310,6 +329,20 @@ enum Command {
         #[arg(long)]
         json: bool,
     },
+    /// Acknowledge an active MXAccess alarm condition through the gateway's
+    /// session-less AcknowledgeAlarm RPC.
+    AcknowledgeAlarm {
+        #[command(flatten)]
+        connection: ConnectionArgs,
+        #[arg(long)]
+        reference: String,
+        #[arg(long, default_value = "")]
+        comment: String,
+        #[arg(long, default_value = "")]
+        operator: String,
+        #[arg(long)]
+        json: bool,
+    },
     Smoke {
         #[command(flatten)]
         connection: ConnectionArgs,
@@ -432,13 +465,32 @@ enum CliValueType {
     String,
 }
 
-#[tokio::main]
+/// Entry point. The real work runs on a dedicated thread with a large stack:
-async fn main() -> ExitCode {
+/// clap's derive-generated argument parser is deeply recursive, and in debug
+/// builds (no inlining) parsing the `Command` enum can exhaust the default
+/// 8 MiB main-thread stack as the enum grows. A 32 MiB worker stack keeps the
+/// CLI robust regardless of build profile or future subcommand growth.
+fn main() -> ExitCode {
+    let worker = std::thread::Builder::new()
+        .name("mxgw-cli".to_owned())
+        .stack_size(32 * 1024 * 1024)
+        .spawn(run)
+        .expect("failed to spawn the CLI worker thread");
+    worker.join().expect("the CLI worker thread panicked")
+}
+
+fn run() -> ExitCode {
     let cli = Cli::parse();
-    let result = match cli.command {
+    let runtime = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .expect("failed to build the Tokio runtime");
+    let result = runtime.block_on(async {
+        match cli.command {
             Command::Batch => run_batch().await,
             command => dispatch(command).await,
-    };
+        }
+    });
     match result {
         Ok(()) => ExitCode::SUCCESS,
         Err(error) => {
@@ -788,6 +840,52 @@ async fn dispatch(command: Command) -> Result<(), Error> {
                 println!("{}", json!({ "eventCount": event_count, "events": events }));
             }
         }
+        Command::StreamAlarms {
+            connection,
+            filter_prefix,
+            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_alarms(StreamAlarmsRequest {
+                    client_correlation_id: mxgateway_client::next_correlation_id(
+                        "cli-stream-alarms",
+                    ),
+                    alarm_filter_prefix: filter_prefix.unwrap_or_default(),
+                })
+                .await?;
+            let mut messages: Vec<Value> = Vec::new();
+            let mut message_count = 0usize;
+            while message_count < max_events {
+                let Some(message) = stream.next().await else {
+                    break;
+                };
+                let message = message?;
+                message_count += 1;
+                if jsonl {
+                    println!("{}", alarm_feed_message_to_json(&message));
+                } else if json {
+                    messages.push(alarm_feed_message_to_json(&message));
+                } else {
+                    println!("{}", alarm_feed_message_summary(&message));
+                }
+            }
+            if json {
+                println!(
+                    "{}",
+                    json!({ "messageCount": message_count, "messages": messages })
+                );
+            }
+        }
         Command::Write {
             connection,
             session_id,
@@ -832,6 +930,26 @@ async fn dispatch(command: Command) -> Result<(), Error> {
                 .await?;
             print_ok("write2", json);
         }
+        Command::AcknowledgeAlarm {
+            connection,
+            reference,
+            comment,
+            operator,
+            json,
+        } => {
+            let client = connect(connection).await?;
+            let reply = client
+                .acknowledge_alarm(AcknowledgeAlarmRequest {
+                    client_correlation_id: mxgateway_client::next_correlation_id(
+                        "cli-acknowledge-alarm",
+                    ),
+                    alarm_full_reference: reference,
+                    comment,
+                    operator_user: operator,
+                })
+                .await?;
+            print_acknowledge_alarm_reply(&reply, json);
+        }
         Command::Galaxy(galaxy_command) => run_galaxy(galaxy_command).await?,
         Command::Smoke {
             connection,
@@ -1533,6 +1651,113 @@ fn print_deploy_event(event: &DeployEvent, use_json: bool) {
     }
 }
 
+/// Render a streamed [`AlarmFeedMessage`] as a terse one-line summary that
+/// distinguishes the three `payload` oneof cases.
+fn alarm_feed_message_summary(message: &AlarmFeedMessage) -> String {
+    match &message.payload {
+        Some(alarm_feed_message::Payload::ActiveAlarm(snapshot)) => {
+            format!(
+                "active-alarm {} state={}",
+                snapshot.alarm_full_reference,
+                AlarmEnumName::condition_state(snapshot.current_state)
+            )
+        }
+        Some(alarm_feed_message::Payload::SnapshotComplete(complete)) => {
+            format!("snapshot-complete {complete}")
+        }
+        Some(alarm_feed_message::Payload::Transition(transition)) => {
+            format!(
+                "transition {} kind={}",
+                transition.alarm_full_reference,
+                AlarmEnumName::transition_kind(transition.transition_kind)
+            )
+        }
+        None => "(empty)".to_owned(),
+    }
+}
+
+/// Render a streamed [`AlarmFeedMessage`] as a JSON object whose single
+/// top-level key names the active `payload` oneof case, mirroring the
+/// protobuf-JSON the .NET/Go/Java/Python CLIs emit.
+fn alarm_feed_message_to_json(message: &AlarmFeedMessage) -> Value {
+    match &message.payload {
+        Some(alarm_feed_message::Payload::ActiveAlarm(snapshot)) => json!({
+            "activeAlarm": {
+                "alarmFullReference": snapshot.alarm_full_reference,
+                "sourceObjectReference": snapshot.source_object_reference,
+                "alarmTypeName": snapshot.alarm_type_name,
+                "severity": snapshot.severity,
+                "currentState": AlarmEnumName::condition_state(snapshot.current_state),
+                "category": snapshot.category,
+                "description": snapshot.description,
+                "operatorUser": snapshot.operator_user,
+                "operatorComment": snapshot.operator_comment,
+            }
+        }),
+        Some(alarm_feed_message::Payload::SnapshotComplete(complete)) => json!({
+            "snapshotComplete": complete,
+        }),
+        Some(alarm_feed_message::Payload::Transition(transition)) => json!({
+            "transition": {
+                "alarmFullReference": transition.alarm_full_reference,
+                "sourceObjectReference": transition.source_object_reference,
+                "alarmTypeName": transition.alarm_type_name,
+                "transitionKind": AlarmEnumName::transition_kind(transition.transition_kind),
+                "severity": transition.severity,
+                "operatorUser": transition.operator_user,
+                "operatorComment": transition.operator_comment,
+                "category": transition.category,
+                "description": transition.description,
+            }
+        }),
+        None => Value::Null,
+    }
+}
+
+/// Tiny namespace for alarm-enum name lookups used by the alarm-feed
+/// renderers; keeps the proto-enum imports off the `main.rs` top level.
+struct AlarmEnumName;
+
+impl AlarmEnumName {
+    fn condition_state(value: i32) -> String {
+        use mxgateway_client::generated::mxaccess_gateway::v1::AlarmConditionState;
+        AlarmConditionState::try_from(value)
+            .map(|state| state.as_str_name().to_owned())
+            .unwrap_or_else(|_| value.to_string())
+    }
+
+    fn transition_kind(value: i32) -> String {
+        use mxgateway_client::generated::mxaccess_gateway::v1::AlarmTransitionKind;
+        AlarmTransitionKind::try_from(value)
+            .map(|kind| kind.as_str_name().to_owned())
+            .unwrap_or_else(|_| value.to_string())
+    }
+}
+
+/// Render an [`AcknowledgeAlarmReply`] as a terse line or a JSON document.
+fn print_acknowledge_alarm_reply(
+    reply: &mxgateway_client::generated::mxaccess_gateway::v1::AcknowledgeAlarmReply,
+    use_json: bool,
+) {
+    if use_json {
+        println!(
+            "{}",
+            json!({
+                "operation": "acknowledge-alarm",
+                "correlationId": reply.correlation_id,
+                "protocolStatus": reply.protocol_status.as_ref().map(|status| json!({
+                    "code": status.code,
+                    "message": status.message,
+                })),
+                "hresult": reply.hresult,
+                "diagnosticMessage": reply.diagnostic_message,
+            })
+        );
+    } else {
+        println!("acknowledge-alarm completed");
+    }
+}
+
 /// Render a streamed [`MxEvent`] as a JSON object. The scalar value is
 /// projected into protojson-style `*Value` keys so the cross-language e2e
 /// matrix can extract and compare event values uniformly across all five
@@ -1793,6 +2018,47 @@ mod tests {
         );
     }
 
+    #[test]
+    fn parses_stream_alarms_command() {
+        let parsed = Cli::try_parse_from([
+            "mxgw",
+            "stream-alarms",
+            "--filter-prefix",
+            "Tank01",
+            "--max-events",
+            "3",
+            "--json",
+        ]);
+        assert!(parsed.is_ok(), "parse failed: {parsed:?}");
+    }
+
+    #[test]
+    fn parses_stream_alarms_command_without_filter_prefix() {
+        let parsed = Cli::try_parse_from(["mxgw", "stream-alarms"]);
+        assert!(parsed.is_ok(), "parse failed: {parsed:?}");
+    }
+
+    #[test]
+    fn parses_acknowledge_alarm_command() {
+        let parsed = Cli::try_parse_from([
+            "mxgw",
+            "acknowledge-alarm",
+            "--reference",
+            "Tank01.Level.HiHi",
+            "--comment",
+            "ack from cli",
+            "--operator",
+            "operator1",
+        ]);
+        assert!(parsed.is_ok(), "parse failed: {parsed:?}");
+    }
+
+    #[test]
+    fn acknowledge_alarm_requires_reference() {
+        let parsed = Cli::try_parse_from(["mxgw", "acknowledge-alarm"]);
+        assert!(parsed.is_err());
+    }
+
     #[test]
     fn parses_galaxy_watch_command_with_last_seen_and_max_events() {
         let parsed = Cli::try_parse_from([

clients/rust/src/client.rs

@@ -16,9 +16,9 @@ use crate::auth::AuthInterceptor;
 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::{
-    AcknowledgeAlarmReply, AcknowledgeAlarmRequest, ActiveAlarmSnapshot, CloseSessionReply,
+    AcknowledgeAlarmReply, AcknowledgeAlarmRequest, AlarmFeedMessage, CloseSessionReply,
     CloseSessionRequest, MxCommandReply, MxCommandRequest, MxEvent, OpenSessionReply,
-    OpenSessionRequest, QueryActiveAlarmsRequest, StreamEventsRequest,
+    OpenSessionRequest, StreamAlarmsRequest, StreamEventsRequest,
 };
 use crate::options::ClientOptions;
 use crate::session::Session;
@@ -33,11 +33,11 @@ pub type RawGatewayClient = MxAccessGatewayClient<InterceptedService<Channel, Au
 pub type EventStream =
     std::pin::Pin<Box<dyn futures_core::Stream<Item = Result<MxEvent, Error>> + Send + 'static>>;
 
-/// Pinned, boxed [`ActiveAlarmSnapshot`] stream returned by
+/// Pinned, boxed [`AlarmFeedMessage`] stream returned by
-/// [`GatewayClient::query_active_alarms`]. Errors are pre-mapped from
+/// [`GatewayClient::stream_alarms`]. Errors are pre-mapped from
 /// `tonic::Status` to [`Error`]; dropping the stream cancels the call.
-pub type ActiveAlarmStream = std::pin::Pin<
+pub type AlarmFeedStream = std::pin::Pin<
-    Box<dyn futures_core::Stream<Item = Result<ActiveAlarmSnapshot, Error>> + Send + 'static>,
+    Box<dyn futures_core::Stream<Item = Result<AlarmFeedMessage, Error>> + Send + 'static>,
 >;
 
 /// Thin async wrapper around the generated gateway client.
@@ -227,26 +227,27 @@ impl GatewayClient {
         Ok(reply)
     }
 
-    /// Open the server-streaming `QueryActiveAlarms` RPC — the gateway's
+    /// Attach to the gateway's central `StreamAlarms` feed.
-    /// ConditionRefresh equivalent.
     ///
-    /// The returned [`ActiveAlarmStream`] yields one [`ActiveAlarmSnapshot`]
+    /// The returned [`AlarmFeedStream`] opens with one [`AlarmFeedMessage`]
-    /// per currently-active alarm. Dropping the stream cancels the gRPC call
+    /// per currently-active alarm (the ConditionRefresh snapshot), then a
-    /// cooperatively. Optional alarm-reference prefix scoping
+    /// single `snapshot_complete`, then a `transition` for every subsequent
-    /// (`request.alarm_filter_prefix`) limits the stream to a sub-tree.
+    /// raise / acknowledge / clear. It is served by the gateway's always-on
+    /// alarm monitor — no worker session is opened — so any number of clients
+    /// may attach. Dropping the stream cancels the gRPC call cooperatively.
+    /// Optional alarm-reference prefix scoping (`request.alarm_filter_prefix`)
+    /// limits the stream to a sub-tree.
     ///
     /// # Errors
     ///
     /// Returns the `tonic::Status` mapped through [`Error::from`] if the
     /// server rejects the request.
-    pub async fn query_active_alarms(
+    pub async fn stream_alarms(
         &self,
-        request: QueryActiveAlarmsRequest,
+        request: StreamAlarmsRequest,
-    ) -> Result<ActiveAlarmStream, Error> {
+    ) -> Result<AlarmFeedStream, Error> {
         let mut client = self.inner.clone();
-        let response = client
+        let response = client.stream_alarms(self.stream_request(request)).await?;
-            .query_active_alarms(self.stream_request(request))
-            .await?;
         let stream = futures_util::StreamExt::map(response.into_inner(), |result| {
             result.map_err(Error::from)
         });

clients/rust/tests/client_behavior.rs

@@ -8,6 +8,7 @@ use std::time::Duration;
 
 use futures_core::Stream;
 use futures_util::StreamExt;
+use mxgateway_client::generated::mxaccess_gateway::v1::alarm_feed_message;
 use mxgateway_client::generated::mxaccess_gateway::v1::mx_access_gateway_server::{
     MxAccessGateway, MxAccessGatewayServer,
 };
@@ -16,12 +17,12 @@ 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::{
     AcknowledgeAlarmReply, AcknowledgeAlarmRequest, ActiveAlarmSnapshot, AddItemReply,
-    BulkReadReply, BulkReadResult, BulkSubscribeReply, BulkWriteReply, BulkWriteResult,
+    AlarmFeedMessage, BulkReadReply, BulkReadResult, BulkSubscribeReply, BulkWriteReply,
-    CloseSessionReply, CloseSessionRequest, MxCommandKind, MxCommandReply, MxDataType, MxEvent,
+    BulkWriteResult, CloseSessionReply, CloseSessionRequest, MxCommandKind, MxCommandReply,
-    MxEventFamily, MxStatusCategory, MxStatusProxy, MxStatusSource, MxValue, OpenSessionReply,
+    MxDataType, MxEvent, MxEventFamily, MxStatusCategory, MxStatusProxy, MxStatusSource, MxValue,
-    OpenSessionRequest, ProtocolStatus, ProtocolStatusCode, QueryActiveAlarmsRequest, SessionState,
+    OpenSessionReply, OpenSessionRequest, ProtocolStatus, ProtocolStatusCode, SessionState,
-    StreamEventsRequest, SubscribeResult, Write2BulkEntry, WriteBulkEntry, WriteSecured2BulkEntry,
+    StreamAlarmsRequest, StreamEventsRequest, SubscribeResult, Write2BulkEntry, WriteBulkEntry,
-    WriteSecuredBulkEntry,
+    WriteSecured2BulkEntry, WriteSecuredBulkEntry,
 };
 use mxgateway_client::{
     ApiKey, ClientOptions, CommandError, Error, GatewayClient, MxStatus, MxValue as ClientMxValue,
@@ -208,7 +209,6 @@ async fn acknowledge_alarm_returns_reply_with_native_status() {
 
     let reply = client
         .acknowledge_alarm(AcknowledgeAlarmRequest {
-            session_id: "session-fixture".to_owned(),
             client_correlation_id: "corr-1".to_owned(),
             alarm_full_reference: "Tank01.Level.HiHi".to_owned(),
             comment: "investigating".to_owned(),
@@ -225,7 +225,7 @@ async fn acknowledge_alarm_returns_reply_with_native_status() {
 }
 
 #[tokio::test]
-async fn query_active_alarms_streams_snapshot_rows() {
+async fn stream_alarms_streams_snapshot_then_complete() {
     let state = Arc::new(FakeState::default());
     let endpoint = spawn_fake_gateway(state.clone()).await;
     let client = GatewayClient::connect(ClientOptions::new(endpoint))
@@ -233,15 +233,23 @@ async fn query_active_alarms_streams_snapshot_rows() {
         .unwrap();
 
     let mut stream = client
-        .query_active_alarms(QueryActiveAlarmsRequest {
+        .stream_alarms(StreamAlarmsRequest::default())
-            session_id: "session-fixture".to_owned(),
-            ..QueryActiveAlarmsRequest::default()
-        })
         .await
         .unwrap();
 
     let first = stream.next().await.unwrap().unwrap();
-    assert_eq!(first.alarm_full_reference, "Tank01.Level.HiHi");
+    match first.payload {
+        Some(alarm_feed_message::Payload::ActiveAlarm(snapshot)) => {
+            assert_eq!(snapshot.alarm_full_reference, "Tank01.Level.HiHi");
+        }
+        other => panic!("expected an active-alarm snapshot, got {other:?}"),
+    }
+
+    let second = stream.next().await.unwrap().unwrap();
+    assert_eq!(
+        second.payload,
+        Some(alarm_feed_message::Payload::SnapshotComplete(true)),
+    );
 }
 
 #[test]
@@ -907,7 +915,6 @@ impl MxAccessGateway for FakeGateway {
         _request: Request<AcknowledgeAlarmRequest>,
     ) -> Result<Response<AcknowledgeAlarmReply>, Status> {
         Ok(Response::new(AcknowledgeAlarmReply {
-            session_id: "session-fixture".to_owned(),
             correlation_id: "corr-1".to_owned(),
             protocol_status: Some(ok_status("ack ok")),
             status: Some(MxStatusProxy {
@@ -920,18 +927,28 @@ impl MxAccessGateway for FakeGateway {
         }))
     }
 
-    type QueryActiveAlarmsStream =
+    type StreamAlarmsStream =
-        Pin<Box<dyn Stream<Item = Result<ActiveAlarmSnapshot, Status>> + Send + 'static>>;
+        Pin<Box<dyn Stream<Item = Result<AlarmFeedMessage, Status>> + Send + 'static>>;
 
-    async fn query_active_alarms(
+    async fn stream_alarms(
         &self,
-        _request: Request<QueryActiveAlarmsRequest>,
+        _request: Request<StreamAlarmsRequest>,
-    ) -> Result<Response<Self::QueryActiveAlarmsStream>, Status> {
+    ) -> Result<Response<Self::StreamAlarmsStream>, Status> {
         let (sender, receiver) = mpsc::channel(4);
         sender
-            .send(Ok(ActiveAlarmSnapshot {
+            .send(Ok(AlarmFeedMessage {
+                payload: Some(alarm_feed_message::Payload::ActiveAlarm(
+                    ActiveAlarmSnapshot {
                         alarm_full_reference: "Tank01.Level.HiHi".to_owned(),
                         ..ActiveAlarmSnapshot::default()
+                    },
+                )),
+            }))
+            .await
+            .unwrap();
+        sender
+            .send(Ok(AlarmFeedMessage {
+                payload: Some(alarm_feed_message::Payload::SnapshotComplete(true)),
             }))
             .await
             .unwrap();

code-reviews/README.md

@@ -17,7 +17,7 @@ Each module's `findings.md` is the source of truth; this file is generated from
 | [Client.Rust](Client.Rust/findings.md) | Claude Code | 2026-05-20 | `a020350` | Reviewed | 0 | 20 |
 | [Contracts](Contracts/findings.md) | Claude Code | 2026-05-20 | `a020350` | Reviewed | 0 | 15 |
 | [IntegrationTests](IntegrationTests/findings.md) | Claude Code | 2026-05-20 | `a020350` | Reviewed | 0 | 21 |
-| [Server](Server/findings.md) | Claude Code | 2026-05-20 | `a020350` | Reviewed | 0 | 30 |
+| [Server](Server/findings.md) | Claude Code | 2026-05-22 | `fa491c7` | Reviewed | 2 | 37 |
 | [Tests](Tests/findings.md) | Claude Code | 2026-05-20 | `a020350` | Reviewed | 0 | 24 |
 | [Worker](Worker/findings.md) | Claude Code | 2026-05-20 | `a020350` | Reviewed | 0 | 25 |
 | [Worker.Tests](Worker.Tests/findings.md) | Claude Code | 2026-05-20 | `a020350` | Reviewed | 0 | 30 |
@@ -26,7 +26,10 @@ Each module's `findings.md` is the source of truth; this file is generated from
 
 Findings with status `Open` or `In Progress`, ordered by severity.
 
-_No pending findings._
+| ID | Severity | Category | Location | Description |
+|---|---|---|---|---|
+| Server-031 | Medium | Concurrency & thread safety | `src/MxGateway.Server/Workers/WorkerClient.cs:392-422` (gateway-side heartbeat watchdog); `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:588-617` (worker-side heartbeat loop); `src/MxGateway.Worker/Ipc/WorkerFrameWriter.cs:14,67-76` (shared `_writeLock`) | Surfaced during the 2026-05-20 cross-language e2e re-run against gateway `b794c46`. The .NET phase succeeded through `open-session`/`register`/`bulk-subscribe`/`bulk-read`/`bulk-unsubscribe`/`stream-events`/`write` but then failed on its t… |
+| Server-032 | Medium | Error handling & resilience | `src/MxGateway.Server/Workers/WorkerClient.cs:70-77,463-484` (gateway-side `_events` channel); `src/MxGateway.Server/Configuration/EventOptions.cs:8` (default capacity 10,000); `src/MxGateway.Server/Grpc/EventStreamService.cs` (consumer) | Surfaced during the 2026-05-20 cross-language e2e re-run against gateway `b794c46`. The Java phase advised ~55 items (`item-handle 63`) before failing on the next `advise` call with the Server-030 diagnostic `Session ... is not ready. Sess… |
 
 ## Closed findings
 
@@ -94,6 +97,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Server-016 | Medium | Resolved | Error handling & resilience | `src/MxGateway.Server/Sessions/GatewaySession.cs:790-797`, `src/MxGateway.Server/Sessions/SessionManager.cs:237-258` |
 | Server-021 | Medium | Resolved | Testing coverage | `src/MxGateway.Server/Grpc/MxAccessGatewayService.cs:266-664`, `src/MxGateway.Tests/Gateway/Grpc/MxAccessGatewayServiceTests.cs` |
 | Server-030 | Medium | Resolved | Error handling & resilience | `src/MxGateway.Server/Sessions/GatewaySession.cs:952-980` |
+| Server-033 | Medium | Resolved | Error handling & resilience | `src/MxGateway.Server/Galaxy/GalaxyHierarchyCache.cs:265-323` (`TryRestoreFromDiskAsync`), `:84-99` (`_firstLoad` / `WaitForFirstLoadAsync`); `src/MxGateway.Server/Grpc/GalaxyRepositoryGrpcService.cs:141-163` (`WaitForCacheBootstrap`) |
 | Tests-003 | Medium | Resolved | Performance & resource management | `src/MxGateway.Tests/Security/Authentication/SqliteAuthStoreTests.cs:170-176`, `src/MxGateway.Tests/Security/Authentication/ApiKeyAdminCliRunnerTests.cs:252-258` |
 | Tests-004 | Medium | Resolved | Testing coverage | `src/MxGateway.Tests/Security/Authorization/GatewayGrpcAuthorizationInterceptorTests.cs` |
 | Tests-005 | Medium | Resolved | Testing coverage | `src/MxGateway.Tests/Gateway/Grpc/EventStreamServiceTests.cs:239-261`, `src/MxGateway.Tests/Gateway/Sessions/SessionManagerTests.cs` |
@@ -235,6 +239,10 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Server-027 | Low | Resolved | Design-document adherence | `docs/Authorization.md:120-141,176-181` |
 | Server-028 | Low | Resolved | Testing coverage | `src/MxGateway.Tests/Security/Authorization/GatewayGrpcScopeResolverTests.cs:13-20`, `src/MxGateway.Tests/Gateway/Sessions/GatewaySessionTests.cs` |
 | Server-029 | Low | Resolved | Documentation & comments | `src/MxGateway.Server/Grpc/MxAccessGatewayService.cs:52-58` |
+| Server-034 | Low | Resolved | Error handling & resilience | `src/MxGateway.Server/Galaxy/GalaxyHierarchySnapshotStore.cs:87-115` (`TryLoadAsync`) |
+| Server-035 | Low | Resolved | Performance & resource management | `src/MxGateway.Server/Galaxy/GalaxyHierarchyCache.cs:176` (call site), `:327-352` (`PersistSnapshotAsync`) |
+| Server-036 | Low | Resolved | Error handling & resilience | `src/MxGateway.Server/Galaxy/GalaxyHierarchyCache.cs:345-348` (`PersistSnapshotAsync` catch) |
+| Server-037 | Low | Resolved | Testing coverage | `src/MxGateway.Tests/Galaxy/GalaxyHierarchySnapshotStoreTests.cs`, `src/MxGateway.Tests/Galaxy/GalaxyHierarchyCacheTests.cs` |
 | Tests-007 | Low | Resolved | Code organization & conventions | `src/MxGateway.Tests/Gateway/Grpc/MxAccessGatewayServiceTests.cs:682`, `src/MxGateway.Tests/Gateway/Grpc/GalaxyRepositoryGrpcServiceTests.cs:324`, `src/MxGateway.Tests/Gateway/GatewayEndToEndFakeWorkerSmokeTests.cs:460`, `src/MxGateway.Tests/Security/Authorization/GatewayGrpcAuthorizationInterceptorTests.cs:233` |
 | Tests-008 | Low | Resolved | mxaccessgw conventions | `src/MxGateway.Tests/Gateway/Sessions/WorkerAlarmRpcDispatcherTests.cs:1-9`, `src/MxGateway.Tests/Gateway/Sessions/NotWiredAlarmRpcDispatcherTests.cs:1-3`, `src/MxGateway.Tests/Gateway/Sessions/SessionManagerAlarmAutoSubscribeTests.cs:1` |
 | Tests-009 | Low | Resolved | Documentation & comments | `src/MxGateway.Tests/Gateway/Sessions/SessionManagerTests.cs:36-37,99,365` |

code-reviews/Server/findings.md

@@ -4,10 +4,10 @@
 |---|---|
 | Module | `src/MxGateway.Server` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-20 |
+| Review date | 2026-05-22 |
-| Commit reviewed | `a020350` |
+| Commit reviewed | `fa491c7` |
 | Status | Reviewed |
-| Open findings | 0 |
+| Open findings | 2 |
 
 ## Checklist coverage
 
@@ -47,6 +47,28 @@ Re-review pass at `a020350` — the cross-module sweep that resolved Server-015
 | 9 | Testing coverage | Issues found: Server-028 (`GatewayGrpcScopeResolverTests` does not exercise `WatchDeployEventsRequest` or `MxCommandKind.ReadBulk`; no `GatewaySessionTests` case asserts a `MarkFaulted` during in-flight Close). |
 | 10 | Documentation & comments | Issues found: Server-023 (`NotWiredAlarmRpcDispatcher` class XML doc still says "PR A.6/A.7 — default … shipped while the worker-side AlarmClient event subscription is gated on dev-rig validation"; contradicts the cleanup that Server-014/Server-022 applied to the interface, gateway service, and `WorkerAlarmRpcDispatcher`). Issues found: Server-029 (`OpenSession` capability list advertises `bulk-subscribe-commands` but not the now-shipping bulk-read or bulk-write families — clients that gate on capability strings have no signal that those families exist). |
 
+### 2026-05-22 review (commit fa491c7)
+
+Re-review pass at `fa491c7`, scoped to the Galaxy hierarchy snapshot-persistence
+change: the new `GalaxyHierarchySnapshot`, `IGalaxyHierarchySnapshotStore` /
+`GalaxyHierarchySnapshotStore`, the restore / persist paths added to
+`GalaxyHierarchyCache`, the two new `GalaxyRepositoryOptions`, and the
+`docs/GalaxyRepository.md` / `docs/GatewayConfiguration.md` updates. Prior
+findings (Server-001 through Server-032) are unchanged by this pass.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | No issues found — restore/save sequencing and the shared `BuildEntry` materialization are sound. |
+| 2 | mxaccessgw conventions | No issues found — file-scoped namespaces, `sealed`, `Async` suffixes, Options pattern, and XML docs all conform; the snapshot persists Galaxy metadata (names/types), not tag values or secrets. |
+| 3 | Concurrency & thread safety | No issues found — `_restoreAttempted` and `_current` are touched only under `_refreshGate`; `_current` is published via `Volatile.Write`; the store serializes its file I/O on a private `SemaphoreSlim`. |
+| 4 | Error handling & resilience | Issues found: Server-033 (restore never completes `_firstLoad`, so a cold-start browse waits the full 5s bootstrap budget), Server-034 (`TryLoadAsync` throws on a corrupt file despite the `Try` prefix), Server-036 (a save cancelled at shutdown logs a misleading warning). |
+| 5 | Security | No issues found — the snapshot holds non-secret Galaxy metadata, is written under `C:\ProgramData\MxGateway` alongside the auth DB, and restored rows flow the same materialization path as live SQL with no injection surface. |
+| 6 | Performance & resource management | Issues found: Server-035 (the snapshot write is awaited on the refresh critical path under `_refreshGate` with no timeout). |
+| 7 | Design-document adherence | No issues found — `docs/GalaxyRepository.md` and `docs/GatewayConfiguration.md` were updated in the same commit; `docs/DesignDecisions.md` already defers to `GalaxyRepository.md` as the Galaxy authority. |
+| 8 | Code organization & conventions | No issues found — the new options live on `GalaxyRepositoryOptions`, the store is a registered singleton, and the on-disk envelope (`PersistedFile`) is a private nested record. |
+| 9 | Testing coverage | Issues found: Server-037 (no test for the corrupt-snapshot restore path or for `PersistSnapshot = false` at the cache level). |
+| 10 | Documentation & comments | No issues found — XML docs match behavior; the `GalaxyRepository.md` "On-disk snapshot" section documents the Stale-on-restore lifecycle. |
+
 ## Findings
 
 ### Server-001
@@ -568,3 +590,78 @@ The diagnostic `"Worker event channel rejected an event."` also does not name th
 Add a regression test that advises N items without an active `StreamEvents` consumer, lets the channel fill, and asserts the produced fault message contains the channel-depth diagnostic (#2) — gated so that #3 is not required.
 
 **Resolution:** _(empty until closed; on close, record the fixing commit SHA, the date, and a one-line description of the fix)_
+
+### Server-033
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `src/MxGateway.Server/Galaxy/GalaxyHierarchyCache.cs:265-323` (`TryRestoreFromDiskAsync`), `:84-99` (`_firstLoad` / `WaitForFirstLoadAsync`); `src/MxGateway.Server/Grpc/GalaxyRepositoryGrpcService.cs:141-163` (`WaitForCacheBootstrap`) |
+| Status | Resolved |
+
+**Description:** `TryRestoreFromDiskAsync` populates `_current` with the on-disk snapshot (status `Stale`, `HasData == true`) but never completes the `_firstLoad` `TaskCompletionSource` — only the live-query paths (cheap / heavy / catch) in `RefreshCoreAsync` do. A `DiscoverHierarchy` or `GetLastDeployTime` call that arrives after gateway start but before the first refresh tick finishes sees `cache.Current` as `Empty` (status `Unknown`) when `WaitForCacheBootstrap` runs its initial check, so it falls through to `await WaitForFirstLoadAsync` with a 5-second budget. Restore then completes within milliseconds and makes the data available, but `_firstLoad` stays pending until the live query returns or fails. When the Galaxy database is unreachable — the exact scenario the snapshot feature exists for — the SQL connect attempt outlasts the 5s budget, so the caller waits the full 5 seconds before the budget elapses and the handler falls through to read the (already-restored) data. The result is correct, but the first browse calls after a cold offline start incur a needless ~5s latency, undercutting the feature's purpose.
+
+**Recommendation:** Call `_firstLoad.TrySetResult()` at the end of `TryRestoreFromDiskAsync` once the restored entry is published — restored data is a valid completed first load. Add a regression test: a cache with a throwing repository plus a populated snapshot store should have `WaitForFirstLoadAsync` complete promptly after `RefreshAsync`, not block on the live query.
+
+**Resolution:** Resolved in `bdccdbf` (2026-05-22): `TryRestoreFromDiskAsync` calls `_firstLoad.TrySetResult()` immediately after publishing the restored entry, so a restored snapshot satisfies the bootstrap gate without waiting on the live query. New test `GalaxyHierarchyCacheTests.RefreshAsync_RestoredSnapshotCompletesFirstLoadBeforeLiveQueryReturns` blocks the repository's deploy-time query and asserts `WaitForFirstLoadAsync` still completes from the snapshot.
+
+### Server-034
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Error handling & resilience |
+| Location | `src/MxGateway.Server/Galaxy/GalaxyHierarchySnapshotStore.cs:87-115` (`TryLoadAsync`) |
+| Status | Resolved |
+
+**Description:** `TryLoadAsync` carries the `Try` prefix and its XML doc says it returns `null` "when none exists, persistence is disabled, or the on-disk file uses an unrecognized schema version." But a corrupt or partially written JSON file makes `JsonSerializer.DeserializeAsync` throw `JsonException`, and an unreadable file (locked, denied ACL) throws `IOException` / `UnauthorizedAccessException` — none of which the method catches. End-to-end behavior is still safe because the sole caller, `GalaxyHierarchyCache.TryRestoreFromDiskAsync`, wraps the call in a `catch (Exception)`; but the store's own `Try`-prefixed contract is violated, and any future caller would be surprised by the throw.
+
+**Recommendation:** Catch `JsonException` and `IOException` (the latter covers the `UnauthorizedAccessException` family) inside `TryLoadAsync`, log a warning, and return `null` — consistent with the unrecognized-schema-version branch already present and with the `Try` naming. A corrupt cache file is an expected failure mode for a disk cache.
+
+**Resolution:** Resolved in `bdccdbf` (2026-05-22): `TryLoadAsync` now has a `catch (Exception) when (exception is JsonException or IOException or UnauthorizedAccessException)` that logs a warning and returns `null`. New test `GalaxyHierarchySnapshotStoreTests.TryLoadAsync_WhenFileIsCorruptJson_ReturnsNull`.
+
+### Server-035
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Performance & resource management |
+| Location | `src/MxGateway.Server/Galaxy/GalaxyHierarchyCache.cs:176` (call site), `:327-352` (`PersistSnapshotAsync`) |
+| Status | Resolved |
+
+**Description:** After a heavy refresh, `RefreshCoreAsync` `await`s `PersistSnapshotAsync` while still holding `_refreshGate`, and the `SaveAsync` write has no timeout. The only caller of `RefreshAsync` is the sequential `GalaxyHierarchyRefreshService` loop, so a write that hangs — e.g. a `SnapshotCachePath` pointed at an unresponsive network share — blocks the gate and stalls all subsequent cache refreshes until gateway shutdown. Impact is bounded: clients keep being served the last entry (which flips to `Stale` after the 5-minute threshold), so this is a degradation rather than an outage, and the default `C:\ProgramData` path is local disk where a hang is unlikely.
+
+**Recommendation:** Bound the snapshot write with a timeout — a linked `CancellationTokenSource` cancelling after, say, the SQL `CommandTimeoutSeconds` budget — so a stuck write fails fast and logs rather than pinning the refresh loop. Moving the write off the gate is an alternative but would need its own write-serialization.
+
+**Resolution:** Resolved in `bdccdbf` (2026-05-22): `SaveAsync` wraps the write in a `CancellationTokenSource.CreateLinkedTokenSource(cancellationToken)` cancelled after `Math.Max(1, CommandTimeoutSeconds)` seconds, so a stuck write fails fast instead of pinning the refresh loop. The timeout-expiry path itself is not unit-tested — exercising it would require a genuinely hanging filesystem.
+
+### Server-036
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Error handling & resilience |
+| Location | `src/MxGateway.Server/Galaxy/GalaxyHierarchyCache.cs:345-348` (`PersistSnapshotAsync` catch) |
+| Status | Resolved |
+
+**Description:** `PersistSnapshotAsync` passes the refresh `CancellationToken` to `SaveAsync` and catches every exception — including the `OperationCanceledException` thrown when that token is cancelled at gateway shutdown — in its general `catch (Exception)`, logging it as `Warning: "Failed to persist the Galaxy hierarchy snapshot to disk."`. A snapshot write interrupted by a normal shutdown is not a failure, but it surfaces as a misleading warning every time the gateway stops mid-write.
+
+**Recommendation:** Let a cancellation-driven `OperationCanceledException` pass without the warning — e.g. add `catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) { }` before the general catch — matching the cancellation handling already used in `RefreshCoreAsync` and `TryRestoreFromDiskAsync`.
+
+**Resolution:** Resolved in `bdccdbf` (2026-05-22): `PersistSnapshotAsync` has a `catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)` ahead of the general catch, so a save aborted by gateway shutdown is silent while a genuine failure (including a write timeout) still logs. New test `GalaxyHierarchyCacheTests.RefreshAsync_WhenSnapshotSaveCancelledAtShutdown_DoesNotLogPersistFailure`.
+
+### Server-037
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `src/MxGateway.Tests/Galaxy/GalaxyHierarchySnapshotStoreTests.cs`, `src/MxGateway.Tests/Galaxy/GalaxyHierarchyCacheTests.cs` |
+| Status | Resolved |
+
+**Description:** The new snapshot tests cover the round-trip, missing-file, persistence-disabled, unrecognized-schema, and overwrite cases for the store, and the persist / restore-when-unreachable / promote-on-matching-deploy cases for the cache. Two resilience paths are untested: (1) `GalaxyHierarchyCache.TryRestoreFromDiskAsync`'s `catch` path when the snapshot file is corrupt — the cache must come up `Unavailable` rather than throwing; (2) the cache restore path when `PersistSnapshot = false` (the store yields `null` and the cache stays `Unavailable`). Both are the failure modes most likely to matter operationally.
+
+**Recommendation:** Add a cache test that writes a corrupt snapshot file and asserts `RefreshAsync` with an unreachable repository leaves the cache `Unavailable` without throwing, and a test that confirms a `PersistSnapshot = false` store neither restores nor persists. If Server-034 is fixed, the corrupt-file test also pins the store's null-return.
+
+**Resolution:** Resolved in `bdccdbf` (2026-05-22): added `GalaxyHierarchyCacheTests.RefreshAsync_WhenSnapshotFileCorrupt_ComesUpUnavailableWithoutThrowing` and `RefreshAsync_WhenPersistDisabled_DoesNotRestoreFromDisk`, plus the `TryLoadAsync_WhenFileIsCorruptJson_ReturnsNull` store test added for Server-034.

docs/AlarmClientDiscovery.md

@@ -1,828 +0,0 @@
-# aaAlarmManagedClient discovery — public surface, 2026-05-01
-
-Result of running
-`MxGateway.Worker.Tests.AlarmClientDiscoveryTests.DumpAlarmClientPublicSurface`
-against the deployed AVEVA assembly:
-
-- File:
-  `C:\Program Files (x86)\ArchestrA\Framework\Bin\ViewAppFramework\Content\MA\aaAlarmManagedClient.dll`
-- Assembly identity: `aaAlarmManagedClient, Version=1.0.7368.41290,
-  Culture=neutral, PublicKeyToken=7ebd82b507d9e10c`
-
-## Public types
-
-- `aaAlarmManagedClient.AlarmClient` (class)
-- `aaAlarmManagedClient.PriorityData` (class)
-
-That's the entire exported surface — two types, no interfaces, no
-delegates.
-
-## `AlarmClient` events
-
-**None.** The class has no public events at all. The reflection probe's
-`GetEvents(BindingFlags.Public | Instance | Static)` returned an empty
-list.
-
-## `AlarmClient` methods (relevant subset)
-
-- **Lifecycle:**
-  `RegisterConsumer(int hWnd, string szProductName, string
-  szApplicationName, string szVersion, bool bRetainHiddenAlarms) → int`,
-  `DeregisterConsumer() → int`,
-  `InitializeConsumer(string szApplicationName) → int`,
-  `UninitializeConsumer() → int`,
-  `Dispose()`.
-- **Subscription:**
-  `Subscribe(string szSubscription, short wFromPri, short wToPri,
-  eQueryType QueryType, eSortFlags SortFlags, eAlarmFilterState
-  FilterMask, eAlarmFilterState FilterSpecification) → int`.
-- **Change enumeration (pull on poke):**
-  `GetStatistics(out int lPercentQuery, out int lTotalAlarms, out int
-  lActiveAlarms, out int lSuppressedAlarms, out int lSuppressedFilters,
-  out int lNewAlarms, out int lChangesCount, out int[] ChangeCodes,
-  out int[] ChangePos, out int[] hAlarm) → int`.
-- **Record fetch:**
-  `GetAlarmExtendedRec(int lIndex, out AlarmRecord almRec) → int`,
-  `GetAlarmExtendedRec2(...)`,
-  `GetHighPriAlarm(out AlarmRecord almRec) → int`.
-- **Selection model** (used by ack-selected-* family):
-  `DeselectAll`, `SelectAlaramEntry(short select, int from, int to)`,
-  `SelectByGUID(Guid)`, `SelectAlarmCount(int from, int to)`.
-- **Acknowledge:**
-  `AlarmAckByGUID(Guid alarmGuid, string ackComment, string ackOprName,
-  string ackOprNode, string ackOprDomain, string ackOprFullName) → int`
-  is the per-alarm full-fidelity native ack.
-  `AlarmAckSelected(string ackComment, string ackOprName, string
-  ackOprNode, string ackOprDomain, string ackOprFullName) → int`
-  acks whatever the selection model currently has selected.
-  Several `AckSelected*Group/Tag/Priority/All/Visible*Alarms_Ex(...)`
-  variants exist for bulk ack scoped to a group / tag / priority range.
-- **Suppress / shelve:** `SupressSelected*` and `ShelveSelected*`
-  families plus `DoAlarmShelveAction(...)`. Out of scope for the v1
-  alarm path.
-- **Snapshot/filter** (`SF*` prefix): `SFSetSortA / SFSetFilterA /
-  SFCreateSnapshot / SFGetListCount / SFDeleteSnapshot / SFRefreshAlarm /
-  SFGetStatistics`. Snapshot-style query API, distinct from the
-  consumer-subscription path. Not currently used.
-
-## What this means
-
-The architecture comment on
-`src/MxGateway.Worker/MxAccess/AlarmClientConsumer.cs` (PR A.5) is
-**wrong against this deployed assembly**:
-
-> "The AVEVA alarm-manager surface (`IAlarmMgrDataProvider`) exposes
-> the events we need as plain .NET events — no Windows message pump
-> required."
-
-There is no managed event surface. `AlarmClient.RegisterConsumer`
-takes an `hWnd` because **WM_APP messaging is the actual notification
-mechanism**: AVEVA's alarm provider WM_APP-pokes the registered window,
-and the consumer is expected to call `GetStatistics` on each poke to
-pull `ChangeCodes` / `ChangePos` / `hAlarm` arrays, then
-`GetAlarmExtendedRec(pos, …)` per index to fetch each changed record.
-
-`AlarmClientConsumer.AlarmRecordReceived` has no production callers as
-a result — `RaiseAlarmRecordReceived` is `internal` for tests and
-never gets invoked at runtime. Until A.2 lands a WM_APP pump,
-`MX_EVENT_FAMILY_ON_ALARM_TRANSITION` cannot carry events.
-
-## Live runtime probe — 2026-05-01
-
-`MxGateway.Worker.Tests.AlarmClientWmProbeTests.ProbeAlarmClientWmMessages`
-is a Skip-gated runtime probe that creates a real message-only
-window, calls `AlarmClient.RegisterConsumer(hWnd, …)` +
-`Subscribe(@"\Galaxy!", …)`, and pumps for 20s while logging every
-window message that arrives. Run results below — this turned the
-"WM_APP pump" design assumption upside down.
-
-**`RegisterConsumer` and `Subscribe` both returned 0 (success).** The
-calls are valid against the deployed assembly; no parameter pinning
-needed.
-
-**A registered-message-class WM (ID `0xC275` in this OS session)
-fired every ~1s after `Subscribe` completed.** Constant
-`wParam = 0x00001100`, constant `lParam = 0x079E46D8` (looks like a
-stable pointer into AVEVA-internal state) for all 20 hits. The
-constant payload across hits with no Galaxy alarm being fired
-suggests this is a **heartbeat/keepalive**, not a per-change
-notification.
-
-**Critically: this WM is delivered to AVEVA's own internal window
-(`hwnd=0x18032E`) — NOT to the consumer's `hWnd` we passed in.** The
-consumer window's `WndProc` received only the standard creation
-sequence (`WM_GETMINMAXINFO`, `WM_NCCREATE`, `WM_NCCALCSIZE`,
-`WM_CREATE`) and the destruction sequence (`WM_NCDESTROY`,
-`WM_DESTROY`, `WM_NCCALCSIZE`) — nothing in between. AVEVA's
-notification path runs entirely against AVEVA's internal window;
-it never forwards to the user-supplied hWnd.
-
-The message ID itself is dynamic (a `RegisterWindowMessage`
-allocation in the >= 0xC000 range), so it cannot be hard-coded —
-each consumer process must call `RegisterWindowMessage` with the
-correct *string* and use whatever ID the OS returns.
-
-## What this means for A.2
-
-The "WM_APP pump on the user hWnd" design — what the original plan
-banner described and what the previous version of this doc
-recommended — does not match how AVEVA actually delivers
-notifications. The hWnd parameter to `RegisterConsumer` does not
-appear to receive any of AVEVA's alarm traffic; it's likely used
-only as a registration identity (and perhaps as a parent for modal
-dialogs).
-
-Two viable A.2 designs given the probe data:
-
-1. **Polling.** Just call `GetStatistics` on a timer (e.g. every
-   500ms in the worker's STA) and react to the change set it
-   reports. No window plumbing needed. Trade-off: latency floor =
-   poll period; modest CPU floor because the call is cheap. Matches
-   the heartbeat-style WM 0xC275 semantics — AVEVA itself runs a
-   poll loop internally.
-2. **Hook AVEVA's internal window.** Discover AVEVA's own window
-   (`hwnd=0x18032E` in the probe), `SetWindowsHookEx` or
-   `SetWindowSubclass` on it, and intercept WM 0xC275 on AVEVA's
-   thread. Higher fidelity, near-zero latency, but invasive,
-   fragile across AVEVA upgrades, and requires running on the same
-   process / thread as the AVEVA window. Probably a non-starter
-   without further AVEVA documentation.
-
-**Recommendation:** the polling path (option 1) is cheaper to
-implement, more robust against AVEVA-internal change, and
-acceptable for a typical alarm cadence. The worker's existing STA
-already provides a thread-affinitized timer surface. The unanswered
-question is whether `GetStatistics` can be safely called outside
-AVEVA's own message-pump thread — confirmable by extending the
-probe to fire `GetStatistics` on its own thread and check the
-result.
-
-## Alarm-provider visibility — third probe run, 2026-05-01
-
-Extended the probe to call `AlarmClient.GetProviders` after
-`RegisterConsumer`. Result on this rig:
-
-```
-GetProviders -> rc=0 count=0 list=[]
-```
-
-**Zero alarm providers visible to the consumer process.** This
-explains every preceding probe run: no providers means no alarm
-events, regardless of how many times any value (including a
-bool with an `$Alarm` extension) flips. `Subscribe(@"\Galaxy!")`
-returns 0 (success) but matches nothing because the alarm-manager
-chain that provides the matching feed doesn't expose any provider
-to this consumer.
-
-A System Platform script flipping `TestMachine_001.TestAlarm001`
-every 10s during this probe run produced no observable
-`GetStatistics` transitions, no `positions[]` / `handles[]`
-entries, no change in any field — confirms the silence is not
-about subscription-scope / message-pump but about provider
-absence.
-
-### Possible causes
-
-1. **No `$Alarm` extension on the test bool.** If
-   `TestMachine_001.TestAlarm001` is a regular UDA without a
-   `BoolAlarm` extension wired to it, flipping the value just
-   writes a new value — no alarm fires.
-2. **Alarm manager service not running.** AVEVA's `aaAlarmMgr`
-   (or the equivalent on this rig's Platform version) needs to
-   be running for providers to register.
-3. **Process security context.** A consumer running under a
-   normal user account may not see providers that registered
-   under `LocalSystem` / a Platform service identity. The
-   gateway-worker installation runs under a service account
-   that may have access where `dotnet test` doesn't.
-
-## InitializeConsumer required — fourth probe run, 2026-05-01
-
-Adding `InitializeConsumer("AlarmProbe.Tests")` before
-`RegisterConsumer` made `\Galaxy!` appear in `GetProviders`
-(count=1, status 0 → 100 within 500ms). So #2 and #3 above are
-NOT the cause — the consumer can see the alarm provider once it
-calls Initialize. That's a missing API-call ordering, not a
-permission or service issue.
-
-```
-InitializeConsumer -> 0
-RegisterConsumer -> 0
-GetProviders [after Register] -> rc=0 count=0 list=[]
-Subscribe('\Galaxy!') -> 0
-GetProviders [after Subscribe] -> rc=0 count=1 list=[  0 \Galaxy!]
-GetProviders [poll #1] -> rc=0 count=1 list=[100 \Galaxy!]
-```
-
-Despite the provider being visible at "100% query complete" for
-the entire 60s window, `GetStatistics` continued to report
-`total=0 active=0 codes=[7]` — no alarm transitions reached the
-consumer even with a System Platform script flipping the test
-boolean every 10s during the run.
-
-That isolates the remaining unknown to whether the test bool's
-alarm extension is actually generating MxAccess alarm-provider
-events when its value flips. The probe has confirmed every link
-in the consumer chain works (Initialize → Register → Subscribe →
-provider visible at 100%) — what's missing is alarm traffic from
-the producer side. ObjectViewer or another live consumer running
-alongside the script is the next discriminator: does it visibly
-see the alarm fire?
-
-API-ordering finding: `InitializeConsumer` MUST precede
-`RegisterConsumer` (or at least, must be called before
-`GetProviders` returns anything). PR A.5's `AlarmClientConsumer`
-omits `InitializeConsumer` entirely — that's a bug fix to apply
-even before A.2 lands, since without it the provider chain never
-becomes visible.
-
-## Subscribe-parameter sweep — fifth probe run, 2026-05-01
-
-Even with `InitializeConsumer` + provider visible at status 100,
-no alarm transitions arrived during a 60s window with the user's
-script flipping the test bool every 10s. Tried:
-
-- `qtSummary` and `qtHistory` (the only `eQueryType` values).
-- Priority 1..999 and 0..32767.
-- `eAlarmFilterState.asNone` and `asAlarmActiveNow` for both
-  `FilterMask` and `FilterSpecification`.
-
-`eAlarmFilterState` is single-state-valued (asNone=0,
-asAlarmActiveNow=1, asAlarmAcked=2, asShelved=3), not flag bits.
-None of these knobs surfaced any alarm activity.
-
-User confirmation 2026-05-01: the test bool does have a
-`BoolAlarm` extension on it; in `aaObjectViewer` the
-`$Alarm.InAlarm` sub-attribute flips true/false in lockstep with
-the script's writes. So the alarm extension is **evaluating**
-its condition, just not visibly producing transitions on the
-`aaAlarmManagedClient` consumer stream.
-
-## Multi-channel + multi-subscription probe — sixth run, 2026-05-01
-
-Extended the probe to try every consumer-side approach in
-parallel:
-
-- **Subscription expressions** (sequential): `\Galaxy!`,
-  `\Galaxy!*`, `\\Galaxy!`, `\Galaxy!TestArea`, `\\.\Galaxy!`.
-  All Subscribe calls returned rc=0; the last one
-  (`\\.\Galaxy!`) is reflected in `GetProviders` (count=1).
-- **Read channels** polled at 500ms cadence: `GetStatistics`,
-  `GetHighPriAlarm`, `SFCreateSnapshot` + `SFGetStatistics`.
-- **Filter+sort**: priority 0..32767, `qtSummary`,
-  state=`asAlarmActiveNow`, sort=`sfReturnNewestFirst`.
-- **AlarmRecord init** (worked around `Not a valid Win32
-  FileTime` exception): all DateTime fields pre-set to FILETIME
-  epoch (1601-01-01 UTC) before the call, since
-  `default(DateTime)` is outside FILETIME range and trips the
-  interop marshaler.
-
-Result of the 60s run with `TestMachine_001.TestAlarm001` being
-flipped every 10s:
-
-```
-Subscribe('\Galaxy!') -> 0
-Subscribe('\Galaxy!*') -> 0
-Subscribe('\\Galaxy!') -> 0
-Subscribe('\Galaxy!TestArea') -> 0
-Subscribe('\\.\Galaxy!') -> 0
-GetProviders [after Subscribe-multi] -> count=1 list=[  0 \\.\Galaxy!]
-GetStatistics #1: total=0 active=0 changes=1 codes=[7] positions=[] handles=[]
-GetHighPriAlarm #1: rc=0 {  }
-SF channel #1: SFCreate=0 numAlarms=0 SFStats=0 unackRet=0 unackAlm=0 ackAlm=0 others=0 events=0 idxNewest=-1
-```
-
-**No further "(changed)" entries for the entire 60s window.**
-Every read API returned the same empty result on every poll.
-
-User confirms the alarm IS firing — `aaObjectViewer` sees
-`$Alarm.InAlarm` flip in lockstep with the script. Historian
-records exist (per user — needs verification by querying the
-historian directly).
-
-## Conclusion of consumer-side probing
-
-`aaAlarmManagedClient.AlarmClient` is **not** the receive
-surface AVEVA's alarm pipeline routes to in this Galaxy
-configuration. The consumer chain is verified end-to-end:
-
-- `InitializeConsumer` + `RegisterConsumer` + `Subscribe` all
-  succeed (rc=0).
-- `GetProviders` finds `\Galaxy!` once Initialize is called.
-- All read APIs (`GetStatistics`, `GetHighPriAlarm`,
-  `SFCreateSnapshot`/`SFGetStatistics`) return empty even with
-  every documented filter combination.
-- The consumer's hWnd receives zero AVEVA messages between
-  `WM_CREATE` and `WM_DESTROY`; AVEVA's traffic goes to its own
-  internal hwnd.
-
-The next investigation directions are not consumer-side:
-
-1. **Inspect `aaObjectViewer`'s alarm SDK** to see what library
-   it uses to read alarms. If different from
-   `aaAlarmManagedClient`, switch the worker over.
-2. **Query the historian directly** (`aahEventStorage` /
-   `aahEventSvc`) to confirm alarms are recorded — and use the
-   same path for v2 alarm capture.
-3. **Inspect AVEVA's alarm-routing config** for this Galaxy in
-   System Platform IDE — area assignments, alarm provider
-   bindings, "publish alarm events to" settings on the platform.
-
-For A.2 implementation: the `aaAlarmManagedClient` path the
-gateway-worker is currently architected around may be a
-dead-end on customer Galaxies configured this way. If the
-alarms truly only flow through the historian event-storage path,
-A.2 needs to consume from `aahEventStorage` instead — a
-fundamental architecture pivot.
-
-## BREAKTHROUGH — seventh probe run, 2026-05-01
-
-Two changes finally produced a signal:
-
-1. **Subscription scope:** `\\<MachineName>\Galaxy!<TopArea>` is the
-   canonical AlarmClient subscription format (per ArchestrA Alarm
-   Client docs at `archestra6.rssing.com/chan-12008125/article13.html`):
-   `\\Node\Provider!Area!Filter`, where Node is the *machine* name,
-   Provider is **literally `Galaxy`**, and Area is a hosted area
-   object. For this rig (`\\DESKTOP-6JL3KKO\Galaxy!DEV`) the DEV
-   area — the platform's primary area — is the right scope. Earlier
-   `\Galaxy!`, `\Galaxy!TestArea`, `\\.\Galaxy!`, etc., all returned
-   rc=0 but matched no traffic — they were not the canonical form.
-2. **`InitializeConsumer` before `RegisterConsumer`** — already
-   discovered earlier; bug-fix for PR A.5's `AlarmClientConsumer`.
-
-With both in place, `GetHighPriAlarm` returned a record on every
-poll for 60s straight (117/117 calls), but threw
-`ArgumentOutOfRangeException: Not a valid Win32 FileTime` instead
-of returning successfully — the AlarmRecord struct contains five
-DateTime fields (`ar_Time`, `ar_OrigTime`, `ar_AckTime`,
-`ar_RtnTime`, `ar_SubTime`) and AVEVA writes sentinel/invalid
-FILETIME values for unset ones (e.g., `ar_AckTime` for an
-unacknowledged alarm). The .NET interop that AVEVA ships
-(`aaAlarmManagedClient.dll`) auto-converts FILETIME→DateTime and
-rejects out-of-range values.
-
-`GetStatistics` continues to report `total=0 active=0` even with
-GetHighPriAlarm returning records — those two API surfaces have
-genuinely different views in AVEVA's data model.
-
-So: **alarms flow through `aaAlarmManagedClient.AlarmClient` once
-the subscription expression is canonical**. The blocking issue is
-extracting the payload past the .NET interop's DateTime
-auto-marshaling.
-
-## Remaining work to capture alarm payloads
-
-Define a custom COM interop that uses `long` (FILETIME-as-int64)
-instead of `DateTime` for the timestamp fields. Approach options:
-
-1. **Patch the AVEVA-shipped `aaAlarmManagedClient.dll`** — ildasm
-   the assembly, replace `DateTime` with `long` on AlarmRecord's
-   timestamp fields, ilasm back. Brittle across AVEVA upgrades.
-2. **Write our own `[ComImport]` interface** — declare
-   `IRawAlarmConsumer` ourselves with safe-blittable types,
-   discover the underlying COM IID (via reflection on
-   `AlarmClient`'s `[Guid]` attribute), and `(IRawAlarmConsumer)
-   alarmClient` cast. Cleaner; requires the IID.
-3. **Use `IDispatch` late binding** — dispatch-Invoke bypasses
-   strong-typed marshaling. Verbose but doesn't need IIDs.
-
-For PR A.2's worker integration, option 2 is the least
-disruptive. Once the interop is custom, `AlarmClient.Subscribe` +
-`GetHighPriAlarm` + `GetAlarmExtendedRec` form a viable
-polling-style alarm consumer.
-
-**REVISED 2026-05-01 — option 1 not directly applicable.**
-Reflection on `aaAlarmManagedClient.AlarmClient` shows it
-implements only `IDisposable` (no `[ComImport]` interface, no
-class GUID). It has a single field `CwwAlarmConsumer*
-m_almUnmanaged` — meaning `AlarmClient` is a **C++/CLI managed
-wrapper around a native C++ class**, NOT a COM-interop class.
-The DateTime conversion happens inside the AVEVA wrapper's IL,
-not at a .NET-to-COM marshaling boundary. There is no separate
-COM interface IID we can QI to.
-
-Revised approach options:
-
-A. **Switch to `wnwrapConsumer.dll`** — a separate standalone
-   COM library AVEVA ships at
-   `C:\Program Files (x86)\Common Files\ArchestrA\wnwrapConsumer.dll`
-   exposing `WNWRAPCONSUMERLib.wwAlarmConsumerClass` with
-   `SetXmlAlarmQuery` / `GetXmlCurrentAlarms`. XML-string output
-   bypasses FILETIME marshaling entirely.
-B. **Patch `aaAlarmManagedClient.dll` IL** — wrap the unsafe
-   `DateTime.FromFileTime` calls with a safe variant. Direct
-   fix but modifies a vendor binary.
-C. **Reflect into `m_almUnmanaged` and call native vtable** —
-   get the IntPtr, walk the MSVC C++ vtable, call
-   `__thiscall` methods via `Marshal.GetDelegateForFunctionPointer`.
-   Doable but requires reverse-engineering the C++ class layout.
-
-Option A is the best fit: real COM-based, self-contained in
-our code, conventional production-grade approach (the WIN-911
-consumer pattern referenced in AVEVA support forums uses it).
-
-The polling-vs-WM_APP-callback question from earlier is now
-moot: `GetStatistics`'s `positions[]/handles[]` arrays remained
-empty even when alarms were demonstrably present. The active
-read API for current alarms is `GetHighPriAlarm`, not
-`GetStatistics`'s change array.
-
-### Implications for A.2 implementation
-
-The A.2 PR's value is unmeasurable until at least one alarm
-provider is visible. The choice between polling-via-`GetStatistics`
-and the callback path can only be decided by observing what
-populates first when a real alarm fires. Without a provider,
-both paths return the same "nothing happening" answer.
-
-Until that's resolved, A.2 implementation work is genuinely
-blocked on a dev-rig configuration issue — not on architectural
-choice or code structure.
-
-## GetStatistics polling — second probe run, 2026-05-01
-
-Extended the probe to call `GetStatistics` every ~2s alongside the
-WM logger. Key findings:
-
-- **`GetStatistics` is safely callable from the same thread that
-  did `RegisterConsumer` + `Subscribe`.** Every poll returned rc=0
-  with no exceptions over 9 polls / 20s window.
-- **The deployed Galaxy currently has zero active alarms.** Every
-  poll reported `total=0 active=0 suppressed=0 newAlarms=0`. The
-  `positions[]` and `handles[]` arrays were empty.
-- **`changes=1 codes=[7]` was constant across all polls**, matching
-  the constant 1 Hz WM 0xC275 cadence. Code 7 is consistent with a
-  "heartbeat / subscription healthy" sentinel — same semantics as
-  the WM but reported through the pull-side API.
-- `percent=100` (query-complete percentage) was constant — the
-  subscription is steady-state.
-
-This confirms the polling design (option 1 in the previous section)
-is mechanically viable. The remaining open question is whether
-`GetStatistics` populates `positions[] / handles[]` with real
-entries when an alarm transition actually fires — proving that
-requires firing an alarm.
-
-## Open follow-up probes
-
-Each can be added to `AlarmClientWmProbeTests` as a separate
-Skip-gated test:
-
-1. **Fire a real Galaxy alarm during the pump window.** The cleanest
-   programmatic trigger is an MxAccess write that flips a
-   `$Alarm`-extended boolean to true (alarm in) and back to false
-   (alarm out). Pinning the exact tag reference is pending — needs
-   either a documented test-fixture tag or an interactive selection
-   in System Platform IDE. Once the trigger fires, this resolves
-   whether AVEVA's pulled change set arrives via `GetStatistics`
-   `positions[] / handles[]` (per-change polling works) or only via
-   the AVEVA-internal window (callback path needed).
-2. **Hook AVEVA's internal window** to log what WMs it actually
-   processes — only relevant if probe 1 shows `GetStatistics` does
-   NOT report per-change activity.
-3. **Decompile `aaAlarmManagedClient.dll`'s IL** for the
-   `RegisterConsumer` method to find what `RegisterWindowMessage`
-   string is used and whether there's a callback-registration
-   surface on `WNAL_Register` that the managed client wraps. The
-   alarmlst.dll strings (`WNAL_CallBack`, "Invalid callbacks" error)
-   suggest the underlying C API takes callbacks, but the managed
-   wrapper exposes none of them.
-
-PR A.5's `Subscribe` / `AcknowledgeByGuid` / `SnapshotActiveAlarms`
-are correct — they're pull-style and don't depend on the
-notification mechanism.
-
-## Option A — captured, 2026-05-01
-
-`wnwrapConsumer.dll` (`C:\Program Files (x86)\Common Files\
-ArchestrA\wnwrapConsumer.dll`) hosts the standalone COM class
-`WNWRAPCONSUMERLib.wwAlarmConsumerClass`. Type library imports
-cleanly via `tlbimp` (output stored under `mxaccessgw/lib/
-Interop.WNWRAPCONSUMERLib.dll`). The COM class is registered in
-`HKLM:\SOFTWARE\WOW6432Node\Classes\CLSID\
-{7AB52E5F-36B2-4A30-AE46-952A746F667C}` with `ThreadingModel=
-Apartment` — `new wwAlarmConsumerClass()` succeeds via
-`CoCreateInstance`.
-
-The probe `MxGateway.Worker.Tests/WnWrapConsumerProbeTests.cs`
-(Skip-gated, archival) drove the captured run. Lifecycle:
-
-1. `new wwAlarmConsumerClass()` — instantiated.
-2. `InitializeConsumer("MxGatewayProbe.WnWrap")` -> 0.
-3. `RegisterConsumer(hWnd: 0, productName, applicationName,
-   version)` -> 0. **Note:** wnwrap's `RegisterConsumer` is
-   4-arg (no `bRetainHiddenAlarms`); `aaAlarmManagedClient`'s
-   is 5-arg. Different surface.
-4. `Subscribe(@"\\<machine>\Galaxy!DEV", priLow=1, priHigh=999,
-   qtSummary, sfReturnNewestFirst, asAlarmActiveNow,
-   asAlarmActiveNow)` -> 0. Same canonical scope that worked
-   for `aaAlarmManagedClient`.
-5. `SetXmlAlarmQuery(...)` was called too but the round-trip
-   `GetXmlAlarmQuery` returned a mangled echo (NODE became
-   `DESKTOP-6JL3KKO\Galaxy!DEV`, PROVIDER became `Galaxy!DEV`,
-   ALARM_STATE shortened to `All`, DISPLAY_MODE truncated to
-   `Sum`). The XML-query path looks broken in this build; rely
-   on `Subscribe` for the filter and skip `SetXmlAlarmQuery` in
-   production. Confirming "Subscribe alone is sufficient" is
-   one follow-up probe (call `Subscribe` and read XML, no
-   `SetXmlAlarmQuery`) — out of scope for the breakthrough run
-   but easy to verify.
-
-### Captured XML (60 polls over 30s, 500ms cadence)
-
-`GetXmlCurrentAlarms2(maxAlmCnt: 100, out vartCurrentXmlAlarms)`
-returned BSTR XML cleanly on every call — 60/60 ok, zero throws.
-`GetXmlCurrentAlarms` (the v1 method) returned identical content
-on the same cadence; either method is viable.
-
-Empty state:
-
-```xml
-<?xml version="1.0"?><ALARM_RECORDS COUNT="0"></ALARM_RECORDS>
-```
-
-With alarm active (`UNACK_ALM`, value=true after the flip
-script set the bool true):
-
-```xml
-<?xml version="1.0"?>
-<ALARM_RECORDS COUNT="1">
-  <ALARM>
-    <GUID>BCC4705395424D65BDAABCDEA6A32A73</GUID>
-    <DATE>2026/5/1</DATE>
-    <TIME>13:26:14.709</TIME>
-    <GMTOFFSET>240</GMTOFFSET>
-    <DSTADJUST>0</DSTADJUST>
-    <PROVIDER_NODE>DESKTOP-6JL3KKO</PROVIDER_NODE>
-    <PROVIDER_NAME>Galaxy</PROVIDER_NAME>
-    <GROUP>TestArea</GROUP>
-    <TAGNAME>TestMachine_001.TestAlarm001</TAGNAME>
-    <TYPE>DSC</TYPE>
-    <VALUE>true</VALUE>
-    <LIMIT>true</LIMIT>
-    <PRIORITY>500</PRIORITY>
-    <STATE>UNACK_ALM</STATE>
-    <OPERATOR_NODE></OPERATOR_NODE>
-    <OPERATOR_NAME></OPERATOR_NAME>
-    <ALARM_COMMENT>Test alarm #1</ALARM_COMMENT>
-  </ALARM>
-</ALARM_RECORDS>
-```
-
-After the script set the bool false (`UNACK_RTN`, value=false):
-
-```xml
-<?xml version="1.0"?>
-<ALARM_RECORDS COUNT="1">
-  <ALARM>
-    <GUID>BCC4705395424D65BDAABCDEA6A32A73</GUID>
-    <DATE>2026/5/1</DATE>
-    <TIME>13:26:24.710</TIME>
-    ...
-    <VALUE>false</VALUE>
-    <STATE>UNACK_RTN</STATE>
-    ...
-  </ALARM>
-</ALARM_RECORDS>
-```
-
-The 10s cadence between transitions matches the System Platform
-script's flip frequency exactly. **GUID is stable across the
-in→out cycle** (`BCC4705…` carried through both states), so the
-XML stream represents the alarm record's lifecycle, not separate
-event records — this is "current alarms snapshot," not
-"transition stream." For an OPC UA `AlarmConditionService`
-adapter this is fine: condition-state changes per-snapshot is
-the supported model.
-
-`STATE` enum values observed: `UNACK_RTN` (the alarm has
-returned to normal but is unacknowledged — i.e., visible in the
-"current alarms" list because operator hasn't acked it yet) and
-`UNACK_ALM` (the alarm is currently active and unacknowledged).
-The other states from `eAlmState` (`ACK_RTN`, `ACK_ALM`) would
-appear when an ack is performed — `wwAlarmConsumerClass.AlarmAckByGUID`
-is the method to call.
-
-### `GetStatistics` AV — unrelated quirk
-
-Every `GetStatistics` call threw `AccessViolationException` in
-the probe. Cause: the wnwrap interop signature uses `IntPtr` for
-the three array out-parameters (`pChangeCode`, `pChangePos`,
-`phAlarm`); passing `IntPtr.Zero` is wrong — the COM impl is
-writing into the buffer pointer without null-checking. Pre-
-allocate three int-arrays and pass pinned pointers (or use
-`Marshal.AllocCoTaskMem`) to fix. Not required for the
-production path — the XML methods give us everything we need.
-
-### Implications for PR A.2 worker integration
-
-Replacing `aaAlarmManagedClient.AlarmClient` with
-`WNWRAPCONSUMERLib.wwAlarmConsumerClass` in the worker's
-alarm-consumer surface unblocks A.2 fully. Outline:
-
-1. **Reference path:** drop `aaAlarmManagedClient.dll` reference
-   from `MxGateway.Worker.csproj`; add `Interop.WNWRAPCONSUMERLib.dll`
-   reference from `mxaccessgw/lib/`. (Or commit the interop dll
-   in-tree under `lib/` and reference relatively.)
-2. **`AlarmClientConsumer` → `WnWrapAlarmConsumer`:** rewrite
-   the consumer wrapper to:
-   - `new wwAlarmConsumerClass()` on the worker's STA thread.
-   - `InitializeConsumer(applicationName)` then
-     `RegisterConsumer(hWnd: 0, …)`.
-   - `Subscribe(@"\\<node>\Galaxy!<area>", …)` per configured
-     area. The `<node>` and `<area>` are configurable (default
-     `Environment.MachineName` + the platform's primary area).
-   - Poll `GetXmlCurrentAlarms2(maxAlmCnt, out xml)` on a
-     timer (500ms-1s cadence is comfortable). Parse XML
-     payload; diff against the previous snapshot (keyed by
-     `GUID`); emit `MX_EVENT_FAMILY_ON_ALARM_TRANSITION`
-     events for added/changed/removed records.
-   - `AlarmAckByGUID(VBGUID, comment, oprName, node, domain,
-     fullName)` for client-driven acknowledgements (matches
-     PR A.5's `AlarmAckCommand` payload).
-   - Lifecycle teardown: `DeregisterConsumer` +
-     `UninitializeConsumer` + `Marshal.FinalReleaseComObject`.
-3. **Conversion layer:** map XML record fields to
-   `MxAlarmConditionRecord` proto:
-   - `GUID` → `condition_id` (canonicalize the no-dashes hex
-     to a UUID string).
-   - `STATE` enum → `inAlarm` + `acked` booleans
-     (`UNACK_ALM` → in_alarm=true, acked=false;
-     `UNACK_RTN` → in_alarm=false, acked=false;
-     `ACK_ALM` → in_alarm=true, acked=true;
-     `ACK_RTN` → in_alarm=false, acked=true).
-   - `DATE + TIME + GMTOFFSET + DSTADJUST` → reassemble UTC
-     timestamp; matches the worker's existing `Timestamp`
-     wire format.
-   - `PRIORITY` → severity (already 1-1000-ish range).
-   - `TAGNAME` → reference; `PROVIDER_NAME` + `GROUP` for
-     scope metadata.
-4. **PR A.5 fix carry-over:** `InitializeConsumer` MUST be
-   called before `RegisterConsumer` (rediscovered with
-   `aaAlarmManagedClient`, also true here). The existing
-   `AlarmClientConsumer` skips Initialize entirely; the new
-   `WnWrapAlarmConsumer` includes it from day one.
-5. **Test reuse:** PR A.5's snapshot/ack contract tests can
-   stay — they don't touch the underlying COM API. Add a new
-   integration test against the wnwrap surface (live-AVEVA-only,
-   Skip-gated like the probe).
-
-### Settled API-ordering and surface knowledge
-
-- `InitializeConsumer` first, then `RegisterConsumer` — both
-  on `aaAlarmManagedClient.AlarmClient` and
-  `wwAlarmConsumerClass`.
-- `RegisterConsumer` arity differs:
-  `aaAlarmManagedClient.AlarmClient.RegisterConsumer(hWnd,
-  product, app, version, bRetainHiddenAlarms)` — 5 args;
-  `wwAlarmConsumerClass.RegisterConsumer(hWnd, product, app,
-  version)` — 4 args. The wnwrap class has no
-  `bRetainHiddenAlarms` parameter at all.
-- Subscription expression format: `\\<machine>\Galaxy!<area>`
-  (literal `Galaxy` provider) for both libraries.
-- Native ack: `AlarmAckByGUID(VBGUID guid, comment, oprName,
-  node, domain, fullName)` on the v2 surface; ID 5-arg
-  variant on the legacy `IwwAlarmConsumer` interface.
-
-These findings retire the open follow-up probes from the
-"polling-vs-pump" debate above — `wwAlarmConsumerClass` plus
-poll-on-timer is the implementation.
-
-## Live smoke-test discoveries — 2026-05-01
-
-The Skip-gated `AlarmsLiveSmokeTests.Alarms_full_pipeline_round_trip`
-ran the full
-`WnWrapAlarmConsumer` + `AlarmDispatcher` + `MxAccessAlarmEventSink`
-pipeline against the dev rig with the flip script running. End-to-end
-verified: 6 real transitions captured on the 10s cadence, ack-by-name
-returned rc=0, pipeline stayed healthy through 5 more transitions
-afterwards. Three production-relevant quirks surfaced and were fixed
-in the consumer:
-
-### 1. `SetXmlAlarmQuery` is mandatory for reads despite the mangled echo
-
-Without `SetXmlAlarmQuery`, the first `GetXmlCurrentAlarms2` call
-fails with `E_FAIL` (HRESULT `0x80004005`). The discovery doc above
-flagged the round-trip echo as mangled and recommended skipping the
-call — that recommendation is **wrong**. The echo *is* mangled (AVEVA
-parses NODE/PROVIDER/ALARM_STATE/DISPLAY_MODE incorrectly), but the
-call itself is required as some kind of subscription enabler. Even
-the Subscribe call setting the actual filter doesn't avoid the need
-for `SetXmlAlarmQuery`.
-
-`WnWrapAlarmConsumer.ComposeXmlAlarmQuery(subscription)` decomposes
-the canonical `\\<machine>\Galaxy!<area>` form into the XML's
-NODE/PROVIDER/GROUP fields. Mangled or not, the call enables reads.
-
-### 2. Two consumers required: read-side vs. ack-side
-
-`SetXmlAlarmQuery` enables reads but **breaks `AlarmAckByName` on
-the same consumer instance**. With SetXml applied, AlarmAckByName
-returns -55 even with valid name+provider+group+operator. Without
-SetXml, AlarmAckByName succeeds with rc=0.
-
-The production consumer therefore provisions **two** wnwrap COM
-instances:
-- Primary consumer (`client`): runs full lifecycle including
-  `SetXmlAlarmQuery` for `GetXmlCurrentAlarms2` polls.
-- Ack-only consumer (`ackClient`): runs Initialize → Register →
-  Subscribe via the v1-prefixed methods, **no SetXmlAlarmQuery**.
-  All `AcknowledgeByName` calls dispatch through this instance.
-
-Both consumers subscribe to the same expression. Disposal cleans up
-both via a shared `ReleaseConsumerCom` helper.
-
-### 3. `AlarmAckByName` v2 8-arg vs. v1 6-arg
-
-`wwAlarmConsumerClass` exposes two `AlarmAckByName` overloads:
-- `IwwAlarmConsumer2` v2: 8 args (`name, provider, group, comment,
-  oprName, node, domainName, oprFullName`).
-- `IwwAlarmConsumer` v1: 6 args (no domain, no full-name).
-
-The v2 8-arg method returns -55 on this AVEVA build regardless of
-operator-identity inputs — looks like a stub. The v1 6-arg method
-works. Production `WnWrapAlarmConsumer.AcknowledgeByName` calls the
-6-arg overload and discards the proto's `domain` + `full_name` fields.
-The proto contract keeps the 8 fields for forward compatibility if
-AVEVA fixes the v2 method later.
-
-### 4. `AlarmAckByGUID` is not implemented
-
-The v2 `AlarmAckByGUID(VBGUID, …)` throws `NotImplementedException`
-(COM `E_NOTIMPL`) on `wwAlarmConsumerClass` against this AVEVA
-build. The reference→GUID lookup that we initially planned to wire
-through `AlarmAckByGUID` is therefore not viable on wnwrap; all acks
-must go through `AlarmAckByName`.
-
-The proto `AcknowledgeAlarmCommand` (GUID-based) and the worker's
-`MxAccessCommandExecutor.ExecuteAcknowledgeAlarm` switch arm remain
-in the codebase for the forward-compat shape, but the gateway-side
-`WorkerAlarmRpcDispatcher.AcknowledgeAsync` now always routes through
-`AcknowledgeAlarmByName` when the public RPC supplies a recognizable
-`Provider!Group.Tag` reference.
-
-**Command/reply payload reuse.** `MxCommand.payload` has a dedicated
-`acknowledge_alarm_by_name_command` field, but `MxCommandReply.payload`
-intentionally has **no** by-name-specific case. The by-name ack carries
-no outcome detail beyond the native return code, so the worker's
-`ExecuteAcknowledgeAlarmByName` sets the same `acknowledge_alarm`
-(`AcknowledgeAlarmReplyPayload`) reply case used by the GUID arm, with
-`native_status` = the `AlarmAckByName` return code (also echoed into the
-top-level `MxCommandReply.hresult`). Reply consumers must dispatch on
-`MxCommandReply.kind` (`MX_COMMAND_KIND_ACKNOWLEDGE_ALARM` vs.
-`MX_COMMAND_KIND_ACKNOWLEDGE_ALARM_BY_NAME`), not on the payload oneof
-case, to distinguish the two acks. `WorkerAlarmRpcDispatcher` reads only
-the top-level `hresult`/`protocol_status`, so it handles both arms
-without unpacking the payload.
-
-**Worker `native_status` → public `AcknowledgeAlarmReply` mapping.** The
-worker carries the ack outcome as a single `int32`
-(`AcknowledgeAlarmReplyPayload.native_status`, the `AlarmAckByName` /
-`AlarmAckByGUID` return code; `0` = success), also mirrored into the
-worker `MxCommandReply.hresult`. The public `AcknowledgeAlarmReply` has
-two outcome-shaped fields, but only one is populated:
-
-- `AcknowledgeAlarmReply.hresult` — `WorkerAlarmRpcDispatcher` copies the
-  worker's `MxCommandReply.hresult` (the native return code) into this
-  field. **This is the authoritative ack-outcome field**; `0` means the
-  ack succeeded. It is absent only when the worker reply omitted the
-  value, which is a protocol violation surfaced in `protocol_status`.
-- `AcknowledgeAlarmReply.status` (`MxStatusProxy`) — the worker by-name /
-  by-GUID ack path produces only the `int32` return code, never a
-  populated `MXSTATUS_PROXY` struct, so `WorkerAlarmRpcDispatcher` leaves
-  this field **unset on every reply**. It is reserved for a future
-  structured view of the ack outcome. Clients must not depend on it.
-
-Client authors should therefore branch on `protocol_status` first (for
-transport/session-level failures) and then on `hresult` (`0` = ack
-accepted by MXAccess) — never on `status`.
-
-### 5. STA / threading — production fix needed
-
-The wnwrap COM is `ThreadingModel=Apartment`. The consumer's
-internal `Timer` fires on threadpool threads and would block forever
-on cross-apartment marshaling unless the host STA pumps Win32
-messages. The smoke test sidesteps this by setting
-`pollIntervalMilliseconds=0` (Timer disabled) and driving `PollOnce`
-manually from the test's STA. Production hosting will route polls
-through the worker's `StaRuntime` in a follow-up — the consumer's
-`PollOnce` is `public` and idempotent so the wire-up is mechanical.
-
-### Capture summary
-
-```
-Transition: kind=Clear  ref='Galaxy!TestArea.TestMachine_001.TestAlarm001' …
-Transition: kind=Raise  ref='Galaxy!TestArea.TestMachine_001.TestAlarm001' …
-SnapshotActiveAlarms count=1
-  active: ref='Galaxy!TestArea.TestMachine_001.TestAlarm001' state=Active
-AcknowledgeByName(real identity) -> rc=0
-Post-ack transition: kind=Clear …
-+1: kind=Raise … (10s after ack)
-+2: kind=Clear … (20s)
-+3: kind=Raise … (30s)
-+4: kind=Clear … (40s)
-```
-
-10s cadence held throughout; full proto fields populated correctly;
-ack registered server-side without errors.

docs/Authorization.md

@@ -103,7 +103,7 @@ public string ResolveRequiredScope(object request)
         StreamEventsRequest => GatewayScopes.EventsRead,
         MxCommandRequest commandRequest => ResolveCommandScope(commandRequest.Command?.Kind ?? MxCommandKind.Unspecified),
         AcknowledgeAlarmRequest => GatewayScopes.InvokeWrite,
-        QueryActiveAlarmsRequest => GatewayScopes.EventsRead,
+        StreamAlarmsRequest => GatewayScopes.EventsRead,
         TestConnectionRequest or
         GetLastDeployTimeRequest or
         DiscoverHierarchyRequest or
@@ -113,7 +113,7 @@ public string ResolveRequiredScope(object request)
 }
 ```
 
-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. `AcknowledgeAlarm` is treated as a write — it mutates alarm state, mirroring `MxCommandKind.Write*` — and `QueryActiveAlarms` shares the alarm/event surface with `StreamEvents` and `MxCommandKind.DrainEvents`, so it carries `events:read`.
+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. `AcknowledgeAlarm` is treated as a write — it mutates alarm state, mirroring `MxCommandKind.Write*` — and `StreamAlarms` shares the alarm/event surface with `StreamEvents` and `MxCommandKind.DrainEvents`, so it carries `events:read`. Both alarm RPCs are session-less: the scope check is the only authorization gate, since there is no per-session ownership to enforce.
 
 `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:
 
@@ -205,7 +205,7 @@ blocking constraint; secured values and raw credentials are never logged.
 |----------|-------|--------------|
 | `SessionOpen` | `session:open` | `OpenSessionRequest` |
 | `SessionClose` | `session:close` | `CloseSessionRequest` |
-| `EventsRead` | `events:read` | `StreamEventsRequest`, `QueryActiveAlarmsRequest`, `MxCommandKind.DrainEvents` |
+| `EventsRead` | `events:read` | `StreamEventsRequest`, `StreamAlarmsRequest`, `MxCommandKind.DrainEvents` |
 | `InvokeRead` | `invoke:read` | `MxCommandRequest` for read-style command kinds (`Register`, `AddItem`, `Advise`, `ReadBulk`, and any kind not otherwise mapped) |
 | `InvokeWrite` | `invoke:write` | `AcknowledgeAlarmRequest`, `MxCommandKind.Write`, `MxCommandKind.Write2`, `MxCommandKind.WriteBulk`, `MxCommandKind.Write2Bulk` |
 | `InvokeSecure` | `invoke:secure` | `MxCommandKind.WriteSecured`, `MxCommandKind.WriteSecured2`, `MxCommandKind.WriteSecuredBulk`, `MxCommandKind.WriteSecured2Bulk`, `MxCommandKind.AuthenticateUser` |

docs/GalaxyRepository.md

@@ -2,7 +2,7 @@
 
 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
+enumerate the deployed object hierarchy and each object's 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
@@ -19,8 +19,10 @@ 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
+`HierarchySql` is the object-hierarchy query originally ported from the
-server in the OtOpcUa project so the two consumers see the same row sets.
+equivalent OPC UA server in the OtOpcUa project. `AttributesSql` has since
+diverged from OtOpcUa — see [Built-in vs configured attributes](#built-in-vs-configured-attributes)
+— and is no longer kept in sync with it.
 
 ## RPC Surface
 
@@ -32,7 +34,7 @@ The service is defined in
 |-----|---------|
 | `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). |
+| `DiscoverHierarchy` | Returns one page of the deployed hierarchy plus each returned object's attributes (configured and built-in — see [Built-in vs configured attributes](#built-in-vs-configured-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`
@@ -87,6 +89,36 @@ 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.
 
+### On-disk snapshot
+
+The gateway may lose connectivity to the Galaxy database — and the database is
+often unreachable right when the gateway itself restarts. To keep browse
+working across that gap, the cache persists its dataset to disk:
+
+- After every successful **heavy** refresh (a deploy change), the raw
+  hierarchy and attribute rowsets are written to
+  `MxGateway:Galaxy:SnapshotCachePath`
+  (default `C:\ProgramData\MxGateway\galaxy-snapshot.json`). The write is
+  atomic — a temp file plus rename — so a crash mid-write cannot corrupt the
+  snapshot. Cheap no-change ticks write nothing; the file is already current.
+- On the **first** refresh after startup, before any SQL runs, the cache
+  reloads that file. The restored data is served with `Stale` status —
+  it is last-known data, not live — so clients can browse immediately even
+  when the Galaxy database is unreachable.
+- The first live query then reconciles: if it observes the **same**
+  `time_of_last_deploy` the snapshot was saved at, the entry is promoted to
+  `Healthy` with no heavy re-query (the snapshot is provably current); if it
+  observes a newer deploy, the heavy queries run and replace the snapshot; if
+  the database is still unreachable, the entry stays `Stale`.
+
+`is_alarm` / `is_historized` filters, paging, and the dashboard summary all
+work against a restored snapshot exactly as against a live pull — the restore
+path runs the same materialization. Persistence is disabled by setting
+`MxGateway:Galaxy:PersistSnapshot` to `false`; the snapshot file is then
+neither written nor read, and a cold start with an unreachable database comes
+up `Unavailable` as before. The on-disk file is a cache, not a system of
+record: deleting it only forces the next cold start to wait for live SQL.
+
 ## Deploy Notifications
 
 `WatchDeployEvents` is a server-streaming RPC backed by
@@ -176,6 +208,43 @@ message DiscoverHierarchyReply {
 }
 ```
 
+### Built-in vs configured attributes
+
+Each `GalaxyObject` carries two kinds of attribute, both surfaced the same way
+in the `attributes` list:
+
+- **Configured (dynamic) attributes** — attributes added in the ArchestrA IDE
+  attribute editor. Stored in the Galaxy `dynamic_attribute` table.
+- **Built-in attributes** — attributes every object inherits from its
+  primitives: the object framework, the engine/platform primitives, and the
+  per-attribute extensions (Alarm, History, Boolean, …). Stored in
+  `attribute_definition` and reached through `primitive_instance`.
+
+Built-in attributes are why an `AppEngine` or `WinPlatform` object reports its
+`Engine.*` and `Alarm*` attributes, and why an alarmed attribute such as
+`TestAlarm001` reports its extension leaves `TestAlarm001.Acked`,
+`TestAlarm001.AckMsg`, `TestAlarm001.ActiveAlarmState`, and so on. An earlier
+version of the browse query returned only configured attributes, so those
+objects came back empty or partial; including built-ins makes the browse
+surface match what System Platform's own Object Viewer shows. Expect roughly
+seven times as many attributes as configured-only — the dashboard attribute
+count reflects this.
+
+Two rules govern the built-in rows:
+
+- **No category filter.** `attribute_definition` uses a different
+  `mx_attribute_category` numbering than `dynamic_attribute`, so only the
+  `_`-prefixed-name and `.Description` exclusions apply to built-ins. (The
+  configured-attribute category allow-list is unchanged.)
+- **`is_historized` / `is_alarm` are always `false` for built-in rows.** Those
+  flags identify a configured attribute that *anchors* a history or alarm
+  extension (e.g. `TestAlarm001`), not the extension's machinery leaves
+  (`TestAlarm001.Acked`). `alarm_bearing_only` and `historized_only` therefore
+  still select the anchor attributes, not their built-in children.
+
+When a configured attribute and a built-in attribute resolve to the same
+reference, the configured attribute wins.
+
 ### Contained name vs tag name
 
 Galaxy objects carry two names. `tag_name` is globally unique and is what
@@ -219,10 +288,11 @@ GalaxyHierarchyRefreshService (BackgroundService)
 Component breakdown:
 
 - `GalaxyRepository` (`src/MxGateway.Server/Galaxy/GalaxyRepository.cs`) holds
-  the SQL. Its constants `HierarchySql` and `AttributesSql` are copied verbatim
+  the SQL. Both `HierarchySql` and `AttributesSql` walk template-derivation and
-  from the OtOpcUa project; do not edit them in isolation here. The two
+  package-derivation chains via recursive CTEs and pick the most-derived
-  queries walk template-derivation and package-derivation chains via
+  override per object. `HierarchySql` still matches the OtOpcUa original;
-  recursive CTEs and pick the most-derived attribute override per object.
+  `AttributesSql` does not — it additionally enumerates built-in primitive
+  attributes (see [Built-in vs configured attributes](#built-in-vs-configured-attributes)).
 - `GalaxyHierarchyCache`
   (`src/MxGateway.Server/Galaxy/GalaxyHierarchyCache.cs`) holds the most
   recent immutable `GalaxyHierarchyCacheEntry` (materialized objects +
@@ -251,6 +321,8 @@ Bound to `MxGateway:Galaxy` via `GalaxyRepositoryOptions`.
 |--------|---------|-------------|
 | `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. |
+| `MxGateway:Galaxy:PersistSnapshot` | `true` | Persists each successful browse dataset to disk and reloads it at startup. See [On-disk snapshot](#on-disk-snapshot). |
+| `MxGateway:Galaxy:SnapshotCachePath` | `C:\ProgramData\MxGateway\galaxy-snapshot.json` | File path for the persisted browse snapshot. Ignored when `PersistSnapshot` is `false`. |
 
 The connection string is not treated as a secret in dev (`Integrated
 Security`), but production deployments that use SQL authentication should set

docs/GatewayConfiguration.md

@@ -60,7 +60,15 @@ paths, timeouts, queue sizes, enum values, or protocol values are invalid.
     "Galaxy": {
       "ConnectionString": "Server=localhost;Database=ZB;Integrated Security=True;TrustServerCertificate=True;Encrypt=False;",
       "CommandTimeoutSeconds": 60,
-      "DashboardRefreshIntervalSeconds": 30
+      "DashboardRefreshIntervalSeconds": 30,
+      "PersistSnapshot": true,
+      "SnapshotCachePath": "C:\\ProgramData\\MxGateway\\galaxy-snapshot.json"
+    },
+    "Alarms": {
+      "Enabled": false,
+      "SubscriptionExpression": "",
+      "DefaultArea": "",
+      "ReconcileIntervalSeconds": 30
     }
   }
 }
@@ -164,10 +172,24 @@ at startup.
 | `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. |
+| `MxGateway:Galaxy:PersistSnapshot` | `true` | Persists the latest successful Galaxy browse dataset to disk. When `true`, the cache reloads that snapshot at startup so clients can still browse last-known data while the Galaxy database is unreachable. The restored data is served with `Stale` status until a live query confirms it. |
+| `MxGateway:Galaxy:SnapshotCachePath` | `C:\ProgramData\MxGateway\galaxy-snapshot.json` | File path for the persisted Galaxy browse snapshot. Ignored when `PersistSnapshot` is `false`. The snapshot is written atomically (temp file plus rename). |
 
 See [Galaxy Repository Browse](./GalaxyRepository.md) for the RPC surface and
 behavior.
 
+## Alarm Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `MxGateway:Alarms:Enabled` | `false` | Gates the gateway's always-on central alarm monitor. When `true`, the gateway opens one gateway-owned worker session dedicated to alarms, caches the active-alarm set, and fans it out to every client through the `StreamAlarms` RPC — no client opens its own session to see alarms. |
+| `MxGateway:Alarms:SubscriptionExpression` | _(empty)_ | AVEVA alarm-subscription expression the monitor subscribes on startup, in canonical `\\<machine>\Galaxy!<area>` form. The literal `Galaxy` provider is correct regardless of the Galaxy database name. When empty and `Enabled` is `true`, the gateway falls back to `\\<MachineName>\Galaxy!<DefaultArea>` if `DefaultArea` is set. |
+| `MxGateway:Alarms:DefaultArea` | _(empty)_ | Area name used to compose a default subscription when `SubscriptionExpression` is empty. If both are empty while `Enabled` is `true`, the monitor faults with a configuration diagnostic. |
+| `MxGateway:Alarms:ReconcileIntervalSeconds` | `30` | How often the monitor reconciles its in-process alarm cache against the worker's authoritative active-alarm snapshot, catching transitions the live poll-and-diff feed missed. Floored at 5 seconds. |
+
+The alarm monitor is independent of client sessions: `AcknowledgeAlarm` and
+`StreamAlarms` are session-less RPCs served by the monitor.
+
 ## Related Documentation
 
 - [Gateway Process Detailed Design](./GatewayProcessDesign.md)

docs/GatewayDashboardDesign.md

@@ -274,28 +274,32 @@ diagnostic session/worker views.
 
 ### Alarms page
 
-`/dashboard/alarms` lists the alarms the dashboard session's worker currently
+`/dashboard/alarms` lists the alarms the gateway's central alarm monitor
-reports as Active or ActiveAcked, refreshed every three seconds. It defaults to
+currently holds as Active or ActiveAcked, refreshed every three seconds. It
-showing unacknowledged `Active` alarms; filters add acknowledged alarms and
+defaults to showing unacknowledged `Active` alarms; filters add acknowledged
-narrow by area, severity range, and a reference/source/description text search.
+alarms and narrow by area, severity range, and a reference/source/description
-Cleared alarms are not retained — the gateway holds no alarm-history store, so
+text search. Cleared alarms are not retained — the gateway holds no
-the page reflects only the live active set. The page is read-only; it does not
+alarm-history store, so the page reflects only the live active set. The page is
-acknowledge alarms. If `MxGateway:Alarms:Enabled` is false the session is never
+read-only; it does not acknowledge alarms. If `MxGateway:Alarms:Enabled` is
-subscribed to an alarm provider, and the page says so instead of showing an
+false the central monitor never starts, and the page says so instead of showing
-empty list with no explanation.
+an empty list with no explanation.
 
 ### Live data source
 
 Both the Browse subscription panel and the Alarms page read live MXAccess data
-through `IDashboardLiveDataService` (`DashboardLiveDataService`). It owns one
+through `IDashboardLiveDataService` (`DashboardLiveDataService`). For tag data
-shared gateway session for the whole dashboard, opened lazily on first use via
+it owns one shared gateway session for the whole dashboard, opened lazily on
-`ISessionManager` and re-opened transparently when it faults or its lease
+first use via `ISessionManager` and re-opened transparently when it faults or
-expires. One session means one worker process backs every dashboard circuit;
+its lease expires. One session means one worker process backs every dashboard
-all access is serialised so the worker sees one in-flight command at a time.
+circuit; all access is serialised so the worker sees one in-flight command at a
-Tag reads go through `GatewaySession.SubscribeBulkAsync` / `ReadBulkAsync`;
+time. Tag reads go through `GatewaySession.SubscribeBulkAsync` / `ReadBulkAsync`.
-alarm queries go through `IAlarmRpcDispatcher`. Alarm subscription is the
+
-gateway's existing auto-subscribe-on-open hook, so the dashboard session is
+The Alarms page does **not** use the dashboard session: alarm data comes from
-alarm-subscribed only when `MxGateway:Alarms:Enabled` is set.
+the gateway's always-on central monitor. `QueryAlarmsAsync` reads
+`IGatewayAlarmService.CurrentAlarms` — the monitor's in-process cache — so the
+dashboard sees the same active-alarm set as every `StreamAlarms` client, with
+no per-dashboard alarm subscription. When `MxGateway:Alarms:Enabled` is false
+the monitor never starts and the cache stays empty.
 
 ### API keys page
 

docs/GatewayTesting.md

@@ -293,6 +293,18 @@ path and writes a JSON report under `artifacts/e2e/`:
    write command is rejected — e.g. against a gateway whose worker predates
    write support (`MxAccessCommandExecutor` returning `InvalidRequest` for
    `Write`/`Write2`/`WriteSecured`/`WriteSecured2`).
+8. **Alarm feed + acknowledge** — *opt-in (`-VerifyAlarms`).* Runs after the
+   stream phase. Exercises the two session-less alarm subcommands against the
+   gateway's central alarm monitor: `stream-alarms` reads a bounded slice of
+   the feed (`-AlarmStreamMax`, default 1 — the feed's first message always
+   arrives immediately, whereas later ones depend on live transitions) and
+   asserts at least one `AlarmFeedMessage`; `acknowledge-alarm` acknowledges
+   `-AlarmReference` (default `Galaxy!TestArea.TestMachine_001.TestAlarm001`)
+   and asserts the RPC round-trips. The native ack outcome is not asserted —
+   it depends on whether that alarm is currently active.
+
+   It is opt-in because it depends on the gateway's central alarm monitor
+   being enabled (`MxGateway:Alarms:Enabled`) and a live alarm provider.
 
 Each client CLI is driven through one long-lived `batch` process. Every CLI
 exposes a `batch` subcommand: a process that reads one command line from stdin,
@@ -329,6 +341,8 @@ powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1 -SkipB
 # Write round-trip (opt-in): point at a writable scalar attribute and its
 # value type.
 powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1 -VerifyWrite -WriteAttribute TestChangingInt -WriteType int32
+# Alarm feed + acknowledge (opt-in): needs MxGateway:Alarms:Enabled on the gateway.
+powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1 -VerifyAlarms -AlarmReference "Galaxy!TestArea.TestMachine_001.TestAlarm001"
 # Auth rejection: also assert an insufficient-scope key is denied.
 powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1 -RejectScopeApiKeyEnv MXGATEWAY_READONLY_API_KEY
 # Run all five clients concurrently as isolated child processes.

docs/Grpc.md

@@ -29,7 +29,7 @@ A second gRPC service, `GalaxyRepositoryGrpcService`, is mapped alongside it. It
 
 ## RPC Handlers
 
-`MxAccessGatewayService` derives from the generated `MxAccessGateway.MxAccessGatewayBase` and implements every RPC declared in `mxaccess_gateway.proto` — six in total: `OpenSession`, `CloseSession`, `Invoke`, `StreamEvents`, `AcknowledgeAlarm`, and `QueryActiveAlarms`. 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.
+`MxAccessGatewayService` derives from the generated `MxAccessGateway.MxAccessGatewayBase` and implements every RPC declared in `mxaccess_gateway.proto` — six in total: `OpenSession`, `CloseSession`, `Invoke`, `StreamEvents`, `AcknowledgeAlarm`, and `StreamAlarms`. 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
@@ -88,11 +88,11 @@ Carrying the enqueue timestamp into the worker layer is what lets queue-wait tim
 
 ### `AcknowledgeAlarm`
 
-`AcknowledgeAlarm` is a unary RPC that acknowledges a single alarm. The handler validates `session_id` and `alarm_full_reference` inline (it does not run through `MxAccessGrpcRequestValidator`, because the alarm surface routes through `IAlarmRpcDispatcher` rather than the generic `Invoke` path), resolves the session, then delegates to the registered `IAlarmRpcDispatcher`. The production `WorkerAlarmRpcDispatcher` routes the ack over the worker IPC by GUID (`AcknowledgeAlarmCommand`) when the reference parses as a canonical GUID, or by `Provider!Group.Tag` reference (`AcknowledgeAlarmByNameCommand`) otherwise. The handler-level RPC behaviour and the alarm contract itself are documented in [Alarm Client Discovery](./AlarmClientDiscovery.md).
+`AcknowledgeAlarm` is a unary, **session-less** RPC that acknowledges a single alarm. The handler validates `alarm_full_reference` inline (it does not run through `MxAccessGrpcRequestValidator`) and delegates to `IGatewayAlarmService.AcknowledgeAsync`. The always-on `GatewayAlarmMonitor` routes the ack over its own gateway-managed worker session — clients no longer open a session to acknowledge an alarm. A reference that parses as a canonical GUID forwards to `AcknowledgeAlarmCommand`; a `Provider!Group.Tag` reference forwards to `AcknowledgeAlarmByNameCommand`.
 
-### `QueryActiveAlarms`
+### `StreamAlarms`
 
-`QueryActiveAlarms` is a server-streaming RPC that returns an `ActiveAlarmSnapshot` per currently active alarm. The handler validates `session_id` inline, resolves the session, and delegates to `IAlarmRpcDispatcher`; `WorkerAlarmRpcDispatcher` issues a `QueryActiveAlarmsCommand` over the worker IPC and streams each snapshot from the worker reply.
+`StreamAlarms` is a server-streaming, **session-less** RPC that attaches to the gateway's central alarm feed. The handler delegates to `IGatewayAlarmService.StreamAsync`. The stream opens with one `AlarmFeedMessage` carrying an `active_alarm` per currently-active alarm (the ConditionRefresh snapshot), then a single `snapshot_complete`, then a `transition` for every subsequent raise / acknowledge / clear. It is served by the always-on `GatewayAlarmMonitor`, which owns a single gateway-managed worker session and fans out to every attached client — clients no longer open a session of their own. `alarm_filter_prefix`, when set, scopes the stream to a sub-tree.
 
 ## Validation Rules
 
@@ -104,8 +104,8 @@ Carrying the enqueue timestamp into the worker layer is what lets queue-wait tim
 | `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` |
-| `AcknowledgeAlarm` | `session_id` and `alarm_full_reference` must be non-empty. Validated inline in the handler, not by `MxAccessGrpcRequestValidator`. | `InvalidArgument` |
+| `AcknowledgeAlarm` | `alarm_full_reference` must be non-empty. Validated inline in the handler, not by `MxAccessGrpcRequestValidator`. | `InvalidArgument` |
-| `QueryActiveAlarms` | `session_id` must be non-empty. Validated inline in the handler, not by `MxAccessGrpcRequestValidator`. | `InvalidArgument` |
+| `StreamAlarms` | No required fields — `alarm_filter_prefix` is optional. | — |
 
 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:
 

scripts/run-client-e2e-tests.ps1

@@ -7,7 +7,9 @@ Drives the .NET, Go, Rust, Python, and Java client CLIs against a running
 gateway + worker. For each language the script exercises session open/close,
 register, bulk subscribe/unsubscribe, per-tag add-item/advise, event
 streaming, a write round-trip with value assertion, error-path (parity)
-checks, and API-key auth rejection.
+checks, and API-key auth rejection. With -VerifyAlarms it also exercises the
+session-less stream-alarms and acknowledge-alarm subcommands against the
+gateway's central alarm monitor.
 
 Each client CLI is driven through one long-lived `batch` process: the harness
 writes one command line to its stdin and reads the JSON result back, so the
@@ -60,6 +62,18 @@ param(
     [string]$WriteType = "int32",
     [int]$WriteValueBase = 424200,
     [int]$WriteEchoMaxEvents = 200,
+    # Alarm feed + acknowledge coverage. Opt-in because it depends on the
+    # gateway's central alarm monitor being enabled (MxGateway:Alarms:Enabled)
+    # and a live alarm provider: stream-alarms reads the monitor's snapshot and
+    # acknowledge-alarm acknowledges -AlarmReference. Both RPCs are session-less
+    # — they exercise the gateway's always-on monitor, not a client session.
+    [switch]$VerifyAlarms,
+    [string]$AlarmReference = "Galaxy!TestArea.TestMachine_001.TestAlarm001",
+    # Messages to read from the central alarm feed. 1 is enough to confirm the
+    # subcommand round-trips: the feed's first message (an active-alarm
+    # snapshot, or snapshot-complete when no alarms are active) always arrives
+    # immediately, whereas later messages depend on live alarm transitions.
+    [int]$AlarmStreamMax = 1,
     # Error-path (parity) checks.
     [switch]$SkipParity,
     # API-key auth rejection checks.
@@ -118,6 +132,10 @@ if ($WriteEchoMaxEvents -lt 1) {
     throw "WriteEchoMaxEvents must be greater than zero."
 }
 
+if ($AlarmStreamMax -lt 1) {
+    throw "AlarmStreamMax must be greater than zero."
+}
+
 foreach ($client in $Clients) {
     if ($validClients -notcontains $client) {
         throw "Unsupported client '$client'. Supported clients: $($validClients -join ', ')."
@@ -327,6 +345,25 @@ function Get-StreamEvents {
     }
 }
 
+# Counts the messages in a stream-alarms reply. The CLIs shape the aggregate
+# JSON differently: .NET nests them under `alarms`, Rust under `messages` with
+# a `messageCount`, Python under `messages`; Go and Java emit one AlarmFeedMessage
+# object per line (Read-JsonObject collapses NDJSON into a bare array).
+function Get-AlarmMessageCount {
+    param(
+        [string]$Client,
+        [object]$Json
+    )
+
+    switch ($Client) {
+        "dotnet" { return @($Json.alarms).Count }
+        "go" { return @($Json).Count }
+        "rust" { return [int]$Json.messageCount }
+        "python" { return @($Json.messages).Count }
+        "java" { return @($Json).Count }
+    }
+}
+
 function Get-PropertyValue {
     param(
         [object]$Object,
@@ -564,6 +601,13 @@ function Get-ClientCommand {
                 $arguments += @("--session-id", $Values.sessionId, "--server-handle", "$($Values.serverHandle)", "--item-handle", "$($Values.itemHandle)", "--type", $Values.valueType, "--value", $Values.value)
             } elseif ($Operation -eq "stream-events") {
                 $arguments += @("--session-id", $Values.sessionId, "--max-events", "$streamMaxEvents")
+            } elseif ($Operation -eq "stream-alarms") {
+                $arguments += @("--max-events", "$streamMaxEvents")
+                if ($Values.ContainsKey("filterPrefix")) { $arguments += @("--filter-prefix", $Values.filterPrefix) }
+            } elseif ($Operation -eq "acknowledge-alarm") {
+                $arguments += @("--reference", $Values.alarmReference)
+                if ($Values.ContainsKey("comment")) { $arguments += @("--comment", $Values.comment) }
+                if ($Values.ContainsKey("operator")) { $arguments += @("--operator", $Values.operator) }
             } elseif ($Operation -eq "close-session") {
                 $arguments += @("--session-id", $Values.sessionId)
             }
@@ -600,6 +644,13 @@ function Get-ClientCommand {
                 $arguments += @("-session-id", $Values.sessionId, "-server-handle", "$($Values.serverHandle)", "-item-handle", "$($Values.itemHandle)", "-type", $Values.valueType, "-value", $Values.value)
             } elseif ($Operation -eq "stream-events") {
                 $arguments += @("-session-id", $Values.sessionId, "-limit", "$streamMaxEvents")
+            } elseif ($Operation -eq "stream-alarms") {
+                $arguments += @("-limit", "$streamMaxEvents")
+                if ($Values.ContainsKey("filterPrefix")) { $arguments += @("-filter-prefix", $Values.filterPrefix) }
+            } elseif ($Operation -eq "acknowledge-alarm") {
+                $arguments += @("-reference", $Values.alarmReference)
+                if ($Values.ContainsKey("comment")) { $arguments += @("-comment", $Values.comment) }
+                if ($Values.ContainsKey("operator")) { $arguments += @("-operator", $Values.operator) }
             } elseif ($Operation -eq "close-session") {
                 $arguments += @("-session-id", $Values.sessionId)
             }
@@ -637,6 +688,13 @@ function Get-ClientCommand {
                 $arguments += @("--session-id", $Values.sessionId, "--server-handle", "$($Values.serverHandle)", "--item-handle", "$($Values.itemHandle)", "--value-type", $Values.valueType, "--value", $Values.value)
             } elseif ($Operation -eq "stream-events") {
                 $arguments += @("--session-id", $Values.sessionId, "--max-events", "$streamMaxEvents")
+            } elseif ($Operation -eq "stream-alarms") {
+                $arguments += @("--max-events", "$streamMaxEvents")
+                if ($Values.ContainsKey("filterPrefix")) { $arguments += @("--filter-prefix", $Values.filterPrefix) }
+            } elseif ($Operation -eq "acknowledge-alarm") {
+                $arguments += @("--reference", $Values.alarmReference)
+                if ($Values.ContainsKey("comment")) { $arguments += @("--comment", $Values.comment) }
+                if ($Values.ContainsKey("operator")) { $arguments += @("--operator", $Values.operator) }
             } elseif ($Operation -eq "close-session") {
                 $arguments += @("--session-id", $Values.sessionId)
             }
@@ -673,6 +731,13 @@ function Get-ClientCommand {
                 $arguments += @("--session-id", $Values.sessionId, "--server-handle", "$($Values.serverHandle)", "--item-handle", "$($Values.itemHandle)", "--type", $Values.valueType, "--value", $Values.value)
             } elseif ($Operation -eq "stream-events") {
                 $arguments += @("--session-id", $Values.sessionId, "--max-events", "$streamMaxEvents", "--timeout", "$pythonStreamTimeout")
+            } elseif ($Operation -eq "stream-alarms") {
+                $arguments += @("--max-messages", "$streamMaxEvents", "--timeout", "$pythonStreamTimeout")
+                if ($Values.ContainsKey("filterPrefix")) { $arguments += @("--filter-prefix", $Values.filterPrefix) }
+            } elseif ($Operation -eq "acknowledge-alarm") {
+                $arguments += @("--reference", $Values.alarmReference)
+                if ($Values.ContainsKey("comment")) { $arguments += @("--comment", $Values.comment) }
+                if ($Values.ContainsKey("operator")) { $arguments += @("--operator", $Values.operator) }
             } elseif ($Operation -eq "close-session") {
                 $arguments += @("--session-id", $Values.sessionId)
             }
@@ -712,6 +777,13 @@ function Get-ClientCommand {
                 $cliArgs += @("--session-id", $Values.sessionId, "--server-handle", "$($Values.serverHandle)", "--item-handle", "$($Values.itemHandle)", "--type", $Values.valueType, "--value", $Values.value)
             } elseif ($Operation -eq "stream-events") {
                 $cliArgs += @("--session-id", $Values.sessionId, "--limit", "$streamMaxEvents")
+            } elseif ($Operation -eq "stream-alarms") {
+                $cliArgs += @("--limit", "$streamMaxEvents")
+                if ($Values.ContainsKey("filterPrefix")) { $cliArgs += @("--filter-prefix", $Values.filterPrefix) }
+            } elseif ($Operation -eq "acknowledge-alarm") {
+                $cliArgs += @("--reference", $Values.alarmReference)
+                if ($Values.ContainsKey("comment")) { $cliArgs += @("--comment", $Values.comment) }
+                if ($Values.ContainsKey("operator")) { $cliArgs += @("--operator", $Values.operator) }
             } elseif ($Operation -eq "close-session") {
                 $cliArgs += @("--session-id", $Values.sessionId)
             }
@@ -801,6 +873,36 @@ function Get-DryRunReply {
                 default { return [pscustomobject]@{ events = $events } }
             }
         }
+        "stream-alarms" {
+            # Synthesize an active-alarm snapshot followed by the
+            # snapshot-complete sentinel. The reply is shaped per client:
+            # Go and Java emit one message object per line (Read-JsonObject
+            # collapses NDJSON to a bare array), Rust aggregates under
+            # `messages` with a `messageCount`, Python under `messages`, and
+            # .NET under `alarms`.
+            $activeAlarm = [pscustomobject]@{
+                activeAlarm = [pscustomobject]@{
+                    alarmFullReference = "Galaxy!TestArea.TestMachine_001.TestAlarm001"
+                    currentState = "ALARM_CONDITION_STATE_ACTIVE"
+                    severity = 500
+                }
+            }
+            $snapshotComplete = [pscustomobject]@{ snapshotComplete = $true }
+            $messages = @($activeAlarm, $snapshotComplete)
+            switch ($Client) {
+                "go" { return ,$messages }
+                "java" { return ,$messages }
+                "rust" { return [pscustomobject]@{ messageCount = $messages.Count; messages = $messages } }
+                "dotnet" { return [pscustomobject]@{ alarms = $messages } }
+                default { return [pscustomobject]@{ messages = $messages } }
+            }
+        }
+        "acknowledge-alarm" {
+            return [pscustomobject]@{
+                rawReply = [pscustomobject]@{ hresult = 0; diagnosticMessage = "dry-run ack" }
+                reply = [pscustomobject]@{ hresult = 0 }
+            }
+        }
         default { return [pscustomobject]@{ ok = $true; reply = [pscustomobject]@{} } }
     }
 }
@@ -1053,6 +1155,7 @@ function Invoke-ClientFlow {
         addedItems = @()
         eventCount = 0
         write = $null
+        alarms = $null
         parity = @()
         auth = @()
         closed = $false
@@ -1285,6 +1388,35 @@ function Invoke-ClientFlow {
             }
         }
 
+        # --- Alarm feed + acknowledge -------------------------------------
+        # Session-less RPCs against the gateway's always-on central alarm
+        # monitor. Opt-in (-VerifyAlarms) because it needs the monitor enabled
+        # (MxGateway:Alarms:Enabled) and a live alarm provider.
+        if ($VerifyAlarms) {
+            $alarmStreamJson = Invoke-ClientOperation -Client $Client -Operation "stream-alarms" -Values @{
+                maxEvents = $AlarmStreamMax
+            }
+            $alarmMessageCount = Get-AlarmMessageCount -Client $Client -Json $alarmStreamJson
+            if ($alarmMessageCount -lt 1) {
+                throw "The $Client stream-alarms command returned no alarm-feed messages."
+            }
+
+            # The acknowledge round-trips against the central monitor; the
+            # native ack outcome depends on whether the referenced alarm is
+            # currently active, so only the RPC's success is asserted here.
+            Invoke-ClientOperation -Client $Client -Operation "acknowledge-alarm" -Values @{
+                alarmReference = $AlarmReference
+                comment = "e2e-matrix"
+                operator = "mxgw-e2e"
+            } | Out-Null
+
+            $clientResult.alarms = [ordered]@{
+                streamMessageCount = $alarmMessageCount
+                acknowledgeReference = $AlarmReference
+                acknowledged = $true
+            }
+        }
+
         # --- Error-path (parity) checks -----------------------------------
         # MXAccess parity: an invalid item handle and an unknown session must
         # both be rejected rather than silently succeeding.
@@ -1391,6 +1523,8 @@ function Get-ChildArgumentList {
         "-WriteType", $WriteType,
         "-WriteValueBase", "$WriteValueBase",
         "-WriteEchoMaxEvents", "$WriteEchoMaxEvents",
+        "-AlarmReference", $AlarmReference,
+        "-AlarmStreamMax", "$AlarmStreamMax",
         "-ReportPath", $ChildReportPath,
         "-EmitReport"
     )
@@ -1400,6 +1534,7 @@ function Get-ChildArgumentList {
     if ($SkipStream) { $childArgs += "-SkipStream" }
     if ($SkipBulk) { $childArgs += "-SkipBulk" }
     if ($VerifyWrite) { $childArgs += "-VerifyWrite" }
+    if ($VerifyAlarms) { $childArgs += "-VerifyAlarms" }
     if ($SkipParity) { $childArgs += "-SkipParity" }
     if ($SkipAuth) { $childArgs += "-SkipAuth" }
     if ($DryRun) { $childArgs += "-DryRun" }
@@ -1479,6 +1614,7 @@ if ($Parallel -and $Clients.Count -gt 1) {
         skipStream = [bool]$SkipStream
         skipBulk = [bool]$SkipBulk
         verifyWrite = [bool]$VerifyWrite
+        verifyAlarms = [bool]$VerifyAlarms
         skipParity = [bool]$SkipParity
         skipAuth = [bool]$SkipAuth
         writeAttribute = $WriteAttribute
@@ -1540,6 +1676,7 @@ $run = [ordered]@{
     skipStream = [bool]$SkipStream
     skipBulk = [bool]$SkipBulk
     verifyWrite = [bool]$VerifyWrite
+    verifyAlarms = [bool]$VerifyAlarms
     skipParity = [bool]$SkipParity
     skipAuth = [bool]$SkipAuth
     writeAttribute = $WriteAttribute

src/MxGateway.Server/Galaxy/GalaxyHierarchyCache.cs

@@ -12,6 +12,10 @@ namespace MxGateway.Server.Galaxy;
 ///     refresh and reused across requests. Refreshes are deploy-time gated: every tick
 ///     queries <c>galaxy.time_of_last_deploy</c> (cheap), and the heavy hierarchy +
 ///     attributes rowsets are pulled only when that timestamp has advanced.
+///     Each successful heavy refresh is persisted to disk through
+///     <see cref="IGalaxyHierarchySnapshotStore"/>; the first refresh restores that
+///     snapshot (as <see cref="GalaxyCacheStatus.Stale"/>) so clients can browse
+///     last-known data when the Galaxy database is unreachable on a cold start.
 /// </summary>
 public sealed class GalaxyHierarchyCache : IGalaxyHierarchyCache
 {
@@ -19,27 +23,35 @@ public sealed class GalaxyHierarchyCache : IGalaxyHierarchyCache
 
     private readonly IGalaxyRepository _repository;
     private readonly IGalaxyDeployNotifier _notifier;
+    private readonly IGalaxyHierarchySnapshotStore? _snapshotStore;
     private readonly TimeProvider _timeProvider;
     private readonly ILogger<GalaxyHierarchyCache>? _logger;
     private readonly TaskCompletionSource _firstLoad = new(TaskCreationOptions.RunContinuationsAsynchronously);
     private readonly SemaphoreSlim _refreshGate = new(1, 1);
     private GalaxyHierarchyCacheEntry _current = GalaxyHierarchyCacheEntry.Empty;
+    private bool _restoreAttempted;
 
     /// <summary>Initializes a new instance of the <see cref="GalaxyHierarchyCache"/> class.</summary>
     /// <param name="repository">Galaxy Repository client for SQL queries.</param>
     /// <param name="notifier">Galaxy deploy event notifier.</param>
     /// <param name="timeProvider">Provider for current time; defaults to system time.</param>
     /// <param name="logger">Optional logger for diagnostic output.</param>
+    /// <param name="snapshotStore">
+    ///     Optional on-disk snapshot store. When supplied, the cache persists each
+    ///     successful refresh and restores the last snapshot on first load.
+    /// </param>
     public GalaxyHierarchyCache(
         IGalaxyRepository repository,
         IGalaxyDeployNotifier notifier,
         TimeProvider? timeProvider = null,
-        ILogger<GalaxyHierarchyCache>? logger = null)
+        ILogger<GalaxyHierarchyCache>? logger = null,
+        IGalaxyHierarchySnapshotStore? snapshotStore = null)
     {
         _repository = repository;
         _notifier = notifier;
         _timeProvider = timeProvider ?? TimeProvider.System;
         _logger = logger;
+        _snapshotStore = snapshotStore;
     }
 
     /// <summary>Gets the current Galaxy hierarchy cache entry with projected status.</summary>
@@ -88,6 +100,15 @@ public sealed class GalaxyHierarchyCache : IGalaxyHierarchyCache
 
     private async Task RefreshCoreAsync(CancellationToken cancellationToken)
     {
+        // First refresh only: seed the cache from the on-disk snapshot before
+        // querying SQL, so a cold start with an unreachable Galaxy database can
+        // still serve last-known browse data. Runs under the refresh gate.
+        if (!_restoreAttempted)
+        {
+            _restoreAttempted = true;
+            await TryRestoreFromDiskAsync(cancellationToken).ConfigureAwait(false);
+        }
+
         GalaxyHierarchyCacheEntry previous = Volatile.Read(ref _current);
         DateTimeOffset queriedAt = _timeProvider.GetUtcNow();
 
@@ -130,41 +151,17 @@ public sealed class GalaxyHierarchyCache : IGalaxyHierarchyCache
 
             List<GalaxyHierarchyRow> hierarchy = hierarchyTask.Result;
             List<GalaxyAttributeRow> attributes = attributesTask.Result;
-            IReadOnlyList<GalaxyObject> objects = BuildObjects(hierarchy, attributes);
-            GalaxyHierarchyIndex index = GalaxyHierarchyIndex.Build(objects);
 
-            int areaCount = hierarchy.Count(row => row.IsArea);
+            long nextSequence = previous.Sequence + 1;
-            int historized = attributes.Count(row => row.IsHistorized);
+            GalaxyHierarchyCacheEntry next = BuildEntry(
-            int alarms = attributes.Count(row => row.IsAlarm);
-            DashboardGalaxySummary dashboardSummary = BuildDashboardSummary(
                 status: GalaxyCacheStatus.Healthy,
+                sequence: nextSequence,
                 lastQueriedAt: queriedAt,
                 lastSuccessAt: queriedAt,
                 lastDeployTime: deployTime,
                 lastError: null,
                 hierarchy: hierarchy,
-                objectCount: hierarchy.Count,
+                attributes: attributes);
-                areaCount: areaCount,
-                attributeCount: attributes.Count,
-                historizedAttributeCount: historized,
-                alarmAttributeCount: alarms);
-
-            long nextSequence = previous.Sequence + 1;
-            GalaxyHierarchyCacheEntry next = new(
-                Status: GalaxyCacheStatus.Healthy,
-                Sequence: nextSequence,
-                LastQueriedAt: queriedAt,
-                LastSuccessAt: queriedAt,
-                LastDeployTime: deployTime,
-                LastError: null,
-                Objects: objects,
-                Index: index,
-                DashboardSummary: dashboardSummary,
-                ObjectCount: hierarchy.Count,
-                AreaCount: areaCount,
-                AttributeCount: attributes.Count,
-                HistorizedAttributeCount: historized,
-                AlarmAttributeCount: alarms);
 
             Volatile.Write(ref _current, next);
             _firstLoad.TrySetResult();
@@ -175,6 +172,8 @@ public sealed class GalaxyHierarchyCache : IGalaxyHierarchyCache
                 TimeOfLastDeploy: deployTime,
                 ObjectCount: hierarchy.Count,
                 AttributeCount: attributes.Count));
+
+            await PersistSnapshotAsync(deployTime, queriedAt, hierarchy, attributes, cancellationToken).ConfigureAwait(false);
         }
         catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
         {
@@ -205,6 +204,161 @@ public sealed class GalaxyHierarchyCache : IGalaxyHierarchyCache
         }
     }
 
+    /// <summary>
+    ///     Materializes a complete <see cref="GalaxyHierarchyCacheEntry"/> from raw
+    ///     hierarchy and attribute rowsets. Shared by the live refresh path and the
+    ///     on-disk restore path so both produce an identical object list, index, and
+    ///     dashboard summary.
+    /// </summary>
+    private static GalaxyHierarchyCacheEntry BuildEntry(
+        GalaxyCacheStatus status,
+        long sequence,
+        DateTimeOffset? lastQueriedAt,
+        DateTimeOffset? lastSuccessAt,
+        DateTimeOffset? lastDeployTime,
+        string? lastError,
+        IReadOnlyList<GalaxyHierarchyRow> hierarchy,
+        IReadOnlyList<GalaxyAttributeRow> attributes)
+    {
+        IReadOnlyList<GalaxyObject> objects = BuildObjects(hierarchy, attributes);
+        GalaxyHierarchyIndex index = GalaxyHierarchyIndex.Build(objects);
+
+        int areaCount = hierarchy.Count(row => row.IsArea);
+        int historized = attributes.Count(row => row.IsHistorized);
+        int alarms = attributes.Count(row => row.IsAlarm);
+        DashboardGalaxySummary dashboardSummary = BuildDashboardSummary(
+            status: status,
+            lastQueriedAt: lastQueriedAt,
+            lastSuccessAt: lastSuccessAt,
+            lastDeployTime: lastDeployTime,
+            lastError: lastError,
+            hierarchy: hierarchy,
+            objectCount: hierarchy.Count,
+            areaCount: areaCount,
+            attributeCount: attributes.Count,
+            historizedAttributeCount: historized,
+            alarmAttributeCount: alarms);
+
+        return new GalaxyHierarchyCacheEntry(
+            Status: status,
+            Sequence: sequence,
+            LastQueriedAt: lastQueriedAt,
+            LastSuccessAt: lastSuccessAt,
+            LastDeployTime: lastDeployTime,
+            LastError: lastError,
+            Objects: objects,
+            Index: index,
+            DashboardSummary: dashboardSummary,
+            ObjectCount: hierarchy.Count,
+            AreaCount: areaCount,
+            AttributeCount: attributes.Count,
+            HistorizedAttributeCount: historized,
+            AlarmAttributeCount: alarms);
+    }
+
+    /// <summary>
+    ///     Seeds the cache from the on-disk snapshot when no live data has loaded yet.
+    ///     The restored entry is marked <see cref="GalaxyCacheStatus.Stale"/> — it is
+    ///     last-known data, not live. A later refresh that observes the same deploy
+    ///     time promotes it to healthy; one that observes a newer deploy replaces it.
+    /// </summary>
+    private async Task TryRestoreFromDiskAsync(CancellationToken cancellationToken)
+    {
+        if (_snapshotStore is null)
+        {
+            return;
+        }
+
+        if (Volatile.Read(ref _current).HasData)
+        {
+            return;
+        }
+
+        GalaxyHierarchySnapshot? snapshot;
+        try
+        {
+            snapshot = await _snapshotStore.TryLoadAsync(cancellationToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw;
+        }
+        catch (Exception exception)
+        {
+            _logger?.LogWarning(exception, "Failed to restore the Galaxy hierarchy from the on-disk snapshot.");
+            return;
+        }
+
+        if (snapshot is null)
+        {
+            return;
+        }
+
+        long sequence = Volatile.Read(ref _current).Sequence + 1;
+        GalaxyHierarchyCacheEntry restored = BuildEntry(
+            status: GalaxyCacheStatus.Stale,
+            sequence: sequence,
+            lastQueriedAt: snapshot.SavedAt,
+            lastSuccessAt: snapshot.SavedAt,
+            lastDeployTime: snapshot.LastDeployTime,
+            lastError: null,
+            hierarchy: snapshot.Hierarchy,
+            attributes: snapshot.Attributes);
+        Volatile.Write(ref _current, restored);
+
+        // Restored data is a valid completed first load: unblock callers waiting on
+        // the bootstrap gate immediately, rather than making them wait out the full
+        // wait budget for a live query that — when the database is unreachable, the
+        // scenario this restore exists for — may not return for seconds.
+        _firstLoad.TrySetResult();
+
+        _notifier.Publish(new GalaxyDeployEventInfo(
+            Sequence: sequence,
+            ObservedAt: _timeProvider.GetUtcNow(),
+            TimeOfLastDeploy: snapshot.LastDeployTime,
+            ObjectCount: snapshot.Hierarchy.Count,
+            AttributeCount: snapshot.Attributes.Count));
+
+        _logger?.LogInformation(
+            "Restored Galaxy hierarchy from on-disk snapshot saved {SavedAt:o}: {ObjectCount} objects, {AttributeCount} attributes (status Stale until the Galaxy database confirms).",
+            snapshot.SavedAt,
+            snapshot.Hierarchy.Count,
+            snapshot.Attributes.Count);
+    }
+
+    /// <summary>
+    ///     Persists a successful refresh to disk. Persistence failures are logged and
+    ///     swallowed — a cache that cannot write its backup is still fully usable.
+    /// </summary>
+    private async Task PersistSnapshotAsync(
+        DateTimeOffset? deployTime,
+        DateTimeOffset savedAt,
+        IReadOnlyList<GalaxyHierarchyRow> hierarchy,
+        IReadOnlyList<GalaxyAttributeRow> attributes,
+        CancellationToken cancellationToken)
+    {
+        if (_snapshotStore is null)
+        {
+            return;
+        }
+
+        try
+        {
+            await _snapshotStore.SaveAsync(
+                new GalaxyHierarchySnapshot(deployTime, savedAt, hierarchy, attributes),
+                cancellationToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            // The refresh was cancelled (gateway shutdown) before the write finished.
+            // That is not a persistence failure — do not log it as a warning.
+        }
+        catch (Exception exception)
+        {
+            _logger?.LogWarning(exception, "Failed to persist the Galaxy hierarchy snapshot to disk.");
+        }
+    }
+
     private static IReadOnlyList<GalaxyObject> BuildObjects(
         IReadOnlyList<GalaxyHierarchyRow> hierarchy,
         IReadOnlyList<GalaxyAttributeRow> attributes)

src/MxGateway.Server/Galaxy/GalaxyHierarchySnapshot.cs

@@ -0,0 +1,24 @@
+namespace MxGateway.Server.Galaxy;
+
+/// <summary>
+///     A serializable point-in-time copy of the Galaxy Repository browse data.
+///     Holds the raw hierarchy and attribute rowsets — not the materialized
+///     protobuf objects — so the restore path runs the exact same
+///     materialization as a live refresh. Persisted by
+///     <see cref="IGalaxyHierarchySnapshotStore"/> after a successful refresh
+///     and reloaded at startup when the Galaxy database is unreachable.
+/// </summary>
+/// <param name="LastDeployTime">
+///     The <c>galaxy.time_of_last_deploy</c> the rowsets were pulled at, or
+///     <see langword="null"/> when the Galaxy table reported no deploy. A later
+///     live refresh that observes this same timestamp can promote the restored
+///     entry to healthy without re-running the heavy queries.
+/// </param>
+/// <param name="SavedAt">UTC wall-clock when the snapshot was written to disk.</param>
+/// <param name="Hierarchy">The persisted object-hierarchy rowset.</param>
+/// <param name="Attributes">The persisted attribute rowset.</param>
+public sealed record GalaxyHierarchySnapshot(
+    DateTimeOffset? LastDeployTime,
+    DateTimeOffset SavedAt,
+    IReadOnlyList<GalaxyHierarchyRow> Hierarchy,
+    IReadOnlyList<GalaxyAttributeRow> Attributes);

src/MxGateway.Server/Galaxy/GalaxyHierarchySnapshotStore.cs

@@ -0,0 +1,141 @@
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+
+namespace MxGateway.Server.Galaxy;
+
+/// <summary>
+///     JSON-file implementation of <see cref="IGalaxyHierarchySnapshotStore"/>.
+///     Writes the on-disk snapshot atomically (temp file + rename) so a crash
+///     mid-write can never leave a torn file, and ignores files whose schema
+///     version it does not recognize. When
+///     <see cref="GalaxyRepositoryOptions.PersistSnapshot"/> is <see langword="false"/>
+///     both operations are no-ops.
+/// </summary>
+public sealed class GalaxyHierarchySnapshotStore : IGalaxyHierarchySnapshotStore
+{
+    /// <summary>
+    ///     On-disk format version. Bump this whenever the persisted shape changes
+    ///     in a way an older or newer gateway cannot read; a mismatched file is
+    ///     ignored rather than misparsed.
+    /// </summary>
+    private const int CurrentSchemaVersion = 1;
+
+    private static readonly JsonSerializerOptions SerializerOptions = new()
+    {
+        WriteIndented = false,
+    };
+
+    private readonly string? _path;
+    private readonly TimeSpan _writeTimeout;
+    private readonly ILogger<GalaxyHierarchySnapshotStore>? _logger;
+    private readonly SemaphoreSlim _ioGate = new(1, 1);
+
+    /// <summary>Initializes a new instance of the <see cref="GalaxyHierarchySnapshotStore"/> class.</summary>
+    /// <param name="options">Galaxy repository options carrying the snapshot path and enable flag.</param>
+    /// <param name="logger">Optional logger for diagnostic output.</param>
+    public GalaxyHierarchySnapshotStore(
+        IOptions<GalaxyRepositoryOptions> options,
+        ILogger<GalaxyHierarchySnapshotStore>? logger = null)
+    {
+        GalaxyRepositoryOptions value = options.Value;
+        _path = value.PersistSnapshot && !string.IsNullOrWhiteSpace(value.SnapshotCachePath)
+            ? value.SnapshotCachePath
+            : null;
+        _writeTimeout = TimeSpan.FromSeconds(Math.Max(1, value.CommandTimeoutSeconds));
+        _logger = logger;
+    }
+
+    /// <inheritdoc />
+    public async Task SaveAsync(GalaxyHierarchySnapshot snapshot, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(snapshot);
+        if (_path is null)
+        {
+            return;
+        }
+
+        PersistedFile file = new(CurrentSchemaVersion, snapshot);
+
+        await _ioGate.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            // Bound the write so a stuck disk — e.g. a SnapshotCachePath on an
+            // unresponsive network share — cannot stall the caller. On the cache
+            // refresh path that would otherwise pin the whole refresh loop.
+            using CancellationTokenSource writeCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+            writeCts.CancelAfter(_writeTimeout);
+
+            string? directory = Path.GetDirectoryName(_path);
+            if (!string.IsNullOrEmpty(directory))
+            {
+                Directory.CreateDirectory(directory);
+            }
+
+            string tempPath = _path + ".tmp";
+            await using (FileStream stream = new(tempPath, FileMode.Create, FileAccess.Write, FileShare.None))
+            {
+                await JsonSerializer.SerializeAsync(stream, file, SerializerOptions, writeCts.Token).ConfigureAwait(false);
+            }
+
+            File.Move(tempPath, _path, overwrite: true);
+            _logger?.LogDebug(
+                "Persisted Galaxy hierarchy snapshot to {Path} ({ObjectCount} objects, {AttributeCount} attributes).",
+                _path,
+                snapshot.Hierarchy.Count,
+                snapshot.Attributes.Count);
+        }
+        finally
+        {
+            _ioGate.Release();
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task<GalaxyHierarchySnapshot?> TryLoadAsync(CancellationToken cancellationToken)
+    {
+        if (_path is null || !File.Exists(_path))
+        {
+            return null;
+        }
+
+        await _ioGate.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            PersistedFile? file;
+            await using (FileStream stream = new(_path, FileMode.Open, FileAccess.Read, FileShare.Read))
+            {
+                file = await JsonSerializer.DeserializeAsync<PersistedFile>(
+                    stream, SerializerOptions, cancellationToken).ConfigureAwait(false);
+            }
+
+            if (file is null || file.SchemaVersion != CurrentSchemaVersion || file.Snapshot is null)
+            {
+                _logger?.LogWarning(
+                    "Ignoring Galaxy hierarchy snapshot at {Path}: unrecognized or empty schema version.",
+                    _path);
+                return null;
+            }
+
+            return file.Snapshot;
+        }
+        catch (Exception exception) when (exception is JsonException or IOException or UnauthorizedAccessException)
+        {
+            // A corrupt, truncated, locked, or access-denied snapshot file is an
+            // expected failure mode for a disk cache — honor the Try contract and
+            // return null rather than throwing.
+            _logger?.LogWarning(
+                exception,
+                "Ignoring Galaxy hierarchy snapshot at {Path}: the file is unreadable or not valid JSON.",
+                _path);
+            return null;
+        }
+        finally
+        {
+            _ioGate.Release();
+        }
+    }
+
+    /// <summary>On-disk envelope: a schema version plus the snapshot payload.</summary>
+    private sealed record PersistedFile(int SchemaVersion, GalaxyHierarchySnapshot? Snapshot);
+}

src/MxGateway.Server/Galaxy/GalaxyRepository.cs

@@ -3,10 +3,15 @@ using Microsoft.Data.SqlClient;
 namespace MxGateway.Server.Galaxy;
 
 /// <summary>
-///     SQL access to the AVEVA System Platform Galaxy Repository (ZB) database. Ported from
+///     SQL access to the AVEVA System Platform Galaxy Repository (ZB) database.
-///     the OtOpcUa project so the row sets stay byte-for-byte identical between the two
+///     <para>
-///     consumers — the same SQL drives the OPC UA server's address space and this gateway's
+///     <see cref="HierarchySql" /> is still the query originally ported from the OtOpcUa
-///     gRPC browse surface.
+///     project. <see cref="AttributesSql" /> has diverged: it additionally enumerates the
+///     built-in attributes contributed by each object's primitives (from
+///     <c>attribute_definition</c> via <c>primitive_instance</c>), so engine/platform objects
+///     and extension sub-attributes (e.g. <c>TestAlarm001.Acked</c>) are surfaced. The
+///     OtOpcUa query is not kept in sync — see docs/GalaxyRepository.md.
+///     </para>
 /// </summary>
 public sealed class GalaxyRepository(GalaxyRepositoryOptions options) : IGalaxyRepository
 {
@@ -158,6 +163,16 @@ WHERE td.category_id IN (1, 3, 4, 10, 11, 13, 17, 24, 26)
     AND g.deployed_package_id <> 0
 ORDER BY parent_gobject_id, g.tag_name";
 
+    // Unlike HierarchySql, this query has diverged from the OtOpcUa original. It returns two
+    // kinds of attribute: user-configured dynamic attributes (the original `dynamic_attribute`
+    // body, src_pri 0) and the built-in attributes every object inherits from its primitives
+    // (`attribute_definition` joined through `primitive_instance`, src_pri 1). Built-in
+    // attributes are why engine/platform objects and extension sub-attributes such as
+    // `TestAlarm001.Acked` show up at all. Built-in rows carry no category filter (the
+    // `attribute_definition` category numbering differs from `dynamic_attribute`'s — only the
+    // `_`-prefix and `.Description` name exclusions apply) and are never flagged
+    // `is_historized`/`is_alarm`: those flags describe a user attribute that anchors an
+    // extension, not the extension's machinery leaves. See docs/GalaxyRepository.md.
     private const string AttributesSql = @"
 ;WITH deployed_package_chain AS (
     SELECT g.gobject_id, p.package_id, p.derived_from_package_id, 0 AS depth
@@ -169,58 +184,69 @@ ORDER BY parent_gobject_id, g.tag_name";
     FROM deployed_package_chain dpc
     INNER JOIN package p ON p.package_id = dpc.derived_from_package_id
     WHERE dpc.derived_from_package_id <> 0 AND dpc.depth < 10
-)
+),
-SELECT gobject_id, tag_name, attribute_name, full_tag_reference,
+candidate AS (
-    mx_data_type, data_type_name, is_array, array_dimension,
-    mx_attribute_category, security_classification, is_historized, is_alarm
-FROM (
     SELECT
-        dpc.gobject_id,
+        dpc.gobject_id, g.tag_name, da.attribute_name, da.mx_data_type, da.is_array,
-        g.tag_name,
-        da.attribute_name,
-        g.tag_name + '.' + da.attribute_name
-            + CASE WHEN da.is_array = 1 THEN '[]' ELSE '' END
-            AS full_tag_reference,
-        da.mx_data_type,
-        dt.description AS data_type_name,
-        da.is_array,
         CASE WHEN da.is_array = 1
              THEN CONVERT(int, CONVERT(varbinary(2),
                   SUBSTRING(da.mx_value, 15, 2) + SUBSTRING(da.mx_value, 13, 2), 2))
-             ELSE NULL
+             ELSE NULL END AS array_dimension,
-        END AS array_dimension,
+        da.mx_attribute_category, da.security_classification, dpc.depth, 0 AS src_pri
-        da.mx_attribute_category,
-        da.security_classification,
-        CASE WHEN EXISTS (
-            SELECT 1 FROM deployed_package_chain dpc2
-            INNER JOIN primitive_instance pi ON pi.package_id = dpc2.package_id AND pi.primitive_name = da.attribute_name
-            INNER JOIN primitive_definition pd ON pd.primitive_definition_id = pi.primitive_definition_id AND pd.primitive_name = 'HistoryExtension'
-            WHERE dpc2.gobject_id = dpc.gobject_id
-        ) THEN 1 ELSE 0 END AS is_historized,
-        CASE WHEN EXISTS (
-            SELECT 1 FROM deployed_package_chain dpc2
-            INNER JOIN primitive_instance pi ON pi.package_id = dpc2.package_id AND pi.primitive_name = da.attribute_name
-            INNER JOIN primitive_definition pd ON pd.primitive_definition_id = pi.primitive_definition_id AND pd.primitive_name = 'AlarmExtension'
-            WHERE dpc2.gobject_id = dpc.gobject_id
-        ) THEN 1 ELSE 0 END AS is_alarm,
-        ROW_NUMBER() OVER (
-            PARTITION BY dpc.gobject_id, da.attribute_name
-            ORDER BY dpc.depth
-        ) AS rn
     FROM deployed_package_chain dpc
-    INNER JOIN dynamic_attribute da
+    INNER JOIN dynamic_attribute da ON da.package_id = dpc.package_id
-        ON da.package_id = dpc.package_id
+    INNER JOIN gobject g ON g.gobject_id = dpc.gobject_id
-    INNER JOIN gobject g
+    INNER JOIN template_definition td ON td.template_definition_id = g.template_definition_id
-        ON g.gobject_id = dpc.gobject_id
-    INNER JOIN template_definition td
-        ON td.template_definition_id = g.template_definition_id
-    LEFT JOIN data_type dt
-        ON dt.mx_data_type = da.mx_data_type
     WHERE td.category_id IN (1, 3, 4, 10, 11, 13, 17, 24, 26)
         AND da.attribute_name NOT LIKE '[_]%'
         AND da.attribute_name NOT LIKE '%.Description'
         AND da.mx_attribute_category IN (2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 24)
-) ranked
+    UNION ALL
-WHERE rn = 1
+    SELECT
-ORDER BY tag_name, attribute_name";
+        dpc.gobject_id, g.tag_name,
+        CASE WHEN pi.primitive_name IS NULL OR pi.primitive_name = ''
+             THEN ad.attribute_name
+             ELSE pi.primitive_name + '.' + ad.attribute_name END AS attribute_name,
+        ad.mx_data_type, ad.is_array,
+        CASE WHEN ad.is_array = 1
+             THEN CONVERT(int, CONVERT(varbinary(2),
+                  SUBSTRING(ad.mx_value, 15, 2) + SUBSTRING(ad.mx_value, 13, 2), 2))
+             ELSE NULL END AS array_dimension,
+        ad.mx_attribute_category, ad.security_classification, dpc.depth, 1 AS src_pri
+    FROM deployed_package_chain dpc
+    INNER JOIN primitive_instance pi ON pi.package_id = dpc.package_id
+    INNER JOIN attribute_definition ad ON ad.primitive_definition_id = pi.primitive_definition_id
+    INNER JOIN gobject g ON g.gobject_id = dpc.gobject_id
+    INNER JOIN template_definition td ON td.template_definition_id = g.template_definition_id
+    WHERE td.category_id IN (1, 3, 4, 10, 11, 13, 17, 24, 26)
+        AND ad.attribute_name NOT LIKE '[_]%'
+        AND ad.attribute_name NOT LIKE '%.Description'
+),
+ranked AS (
+    SELECT c.*, ROW_NUMBER() OVER (
+        PARTITION BY c.gobject_id, c.attribute_name ORDER BY c.src_pri, c.depth) AS rn
+    FROM candidate c
+)
+SELECT
+    r.gobject_id, r.tag_name, r.attribute_name,
+    r.tag_name + '.' + r.attribute_name
+        + CASE WHEN r.is_array = 1 THEN '[]' ELSE '' END AS full_tag_reference,
+    r.mx_data_type, dt.description AS data_type_name, r.is_array, r.array_dimension,
+    r.mx_attribute_category, r.security_classification,
+    CASE WHEN r.src_pri = 0 AND EXISTS (
+        SELECT 1 FROM deployed_package_chain dpc2
+        INNER JOIN primitive_instance pi ON pi.package_id = dpc2.package_id AND pi.primitive_name = r.attribute_name
+        INNER JOIN primitive_definition pd ON pd.primitive_definition_id = pi.primitive_definition_id AND pd.primitive_name = 'HistoryExtension'
+        WHERE dpc2.gobject_id = r.gobject_id
+    ) THEN 1 ELSE 0 END AS is_historized,
+    CASE WHEN r.src_pri = 0 AND EXISTS (
+        SELECT 1 FROM deployed_package_chain dpc2
+        INNER JOIN primitive_instance pi ON pi.package_id = dpc2.package_id AND pi.primitive_name = r.attribute_name
+        INNER JOIN primitive_definition pd ON pd.primitive_definition_id = pi.primitive_definition_id AND pd.primitive_name = 'AlarmExtension'
+        WHERE dpc2.gobject_id = r.gobject_id
+    ) THEN 1 ELSE 0 END AS is_alarm
+FROM ranked r
+LEFT JOIN data_type dt ON dt.mx_data_type = r.mx_data_type
+WHERE r.rn = 1
+ORDER BY r.tag_name, r.attribute_name";
 }

src/MxGateway.Server/Galaxy/GalaxyRepositoryOptions.cs

@@ -27,4 +27,21 @@ public sealed class GalaxyRepositoryOptions
     ///     cache. SQL is hit at most once per interval regardless of dashboard render rate.
     /// </summary>
     public int DashboardRefreshIntervalSeconds { get; init; } = 30;
+
+    /// <summary>Default on-disk path for the persisted Galaxy browse snapshot.</summary>
+    public const string DefaultSnapshotCachePath =
+        @"C:\ProgramData\MxGateway\galaxy-snapshot.json";
+
+    /// <summary>
+    ///     Whether the gateway persists the latest successful Galaxy browse dataset to
+    ///     disk. When enabled, the cache reloads that snapshot at startup so clients can
+    ///     still browse last-known data while the Galaxy database is unreachable.
+    /// </summary>
+    public bool PersistSnapshot { get; init; } = true;
+
+    /// <summary>
+    ///     File path for the persisted Galaxy browse snapshot. Ignored when
+    ///     <see cref="PersistSnapshot"/> is <see langword="false"/>.
+    /// </summary>
+    public string SnapshotCachePath { get; init; } = DefaultSnapshotCachePath;
 }

src/MxGateway.Server/Galaxy/GalaxyRepositoryServiceCollectionExtensions.cs

@@ -19,6 +19,7 @@ public static class GalaxyRepositoryServiceCollectionExtensions
         services.AddSingleton<IGalaxyRepository>(sp => sp.GetRequiredService<GalaxyRepository>());
 
         services.AddSingleton<IGalaxyDeployNotifier, GalaxyDeployNotifier>();
+        services.AddSingleton<IGalaxyHierarchySnapshotStore, GalaxyHierarchySnapshotStore>();
         services.AddSingleton<IGalaxyHierarchyCache, GalaxyHierarchyCache>();
         services.AddHostedService<GalaxyHierarchyRefreshService>();
 

src/MxGateway.Server/Galaxy/IGalaxyHierarchySnapshotStore.cs

@@ -0,0 +1,28 @@
+namespace MxGateway.Server.Galaxy;
+
+/// <summary>
+///     Persists the latest Galaxy Repository browse dataset to disk and reloads
+///     it at startup. Lets <see cref="GalaxyHierarchyCache"/> serve last-known
+///     browse data when the Galaxy database is unreachable on a cold start.
+/// </summary>
+public interface IGalaxyHierarchySnapshotStore
+{
+    /// <summary>
+    ///     Writes <paramref name="snapshot"/> to disk, replacing any previous
+    ///     snapshot atomically. A no-op when snapshot persistence is disabled.
+    /// </summary>
+    /// <param name="snapshot">The browse dataset to persist.</param>
+    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
+    Task SaveAsync(GalaxyHierarchySnapshot snapshot, CancellationToken cancellationToken);
+
+    /// <summary>
+    ///     Reads the persisted Galaxy browse dataset.
+    /// </summary>
+    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
+    /// <returns>
+    ///     The persisted snapshot, or <see langword="null"/> when none exists,
+    ///     persistence is disabled, or the on-disk file uses an unrecognized
+    ///     schema version.
+    /// </returns>
+    Task<GalaxyHierarchySnapshot?> TryLoadAsync(CancellationToken cancellationToken);
+}

src/MxGateway.Server/appsettings.json

@@ -65,7 +65,9 @@
     "Galaxy": {
       "ConnectionString": "Server=localhost;Database=ZB;Integrated Security=True;TrustServerCertificate=True;Encrypt=False;",
       "CommandTimeoutSeconds": 60,
-      "DashboardRefreshIntervalSeconds": 30
+      "DashboardRefreshIntervalSeconds": 30,
+      "PersistSnapshot": true,
+      "SnapshotCachePath": "C:\\ProgramData\\MxGateway\\galaxy-snapshot.json"
     },
     "Alarms": {
       "Enabled": true,

src/MxGateway.Tests/Galaxy/GalaxyHierarchyCacheTests.cs

@@ -1,11 +1,15 @@
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
 using MxGateway.Server.Galaxy;
 using MxGateway.Contracts.Proto.Galaxy;
 using MxGateway.Tests.TestSupport;
 
 namespace MxGateway.Tests.Galaxy;
 
-public sealed class GalaxyHierarchyCacheTests
+public sealed class GalaxyHierarchyCacheTests : IDisposable
 {
+    private readonly List<string> _tempPaths = [];
+
     /// <summary>
     /// Verifies cache returns empty entry before any refresh occurs.
     /// </summary>
@@ -121,6 +125,345 @@ public sealed class GalaxyHierarchyCacheTests
         Assert.Same(root, index.ObjectViewsById[1].Object);
     }
 
+    /// <summary>
+    ///     Verifies a successful refresh writes the browse dataset to the on-disk
+    ///     snapshot store so a later cold start can restore it.
+    /// </summary>
+    [Fact]
+    public async Task RefreshAsync_WhenSuccessful_PersistsSnapshotToDisk()
+    {
+        GalaxyDeployNotifier notifier = new();
+        StubGalaxyRepository repository = new(
+            deployTime: new DateTime(2026, 5, 20, 9, 0, 0, DateTimeKind.Utc),
+            hierarchy: [SampleHierarchyRow()],
+            attributes: [SampleAttributeRow()]);
+        GalaxyHierarchySnapshotStore store = CreateStore();
+        GalaxyHierarchyCache cache = new(repository, notifier, new ManualTimeProvider(), snapshotStore: store);
+
+        await cache.RefreshAsync(CancellationToken.None);
+
+        Assert.Equal(GalaxyCacheStatus.Healthy, cache.Current.Status);
+        GalaxyHierarchySnapshot? persisted = await store.TryLoadAsync(CancellationToken.None);
+        Assert.NotNull(persisted);
+        Assert.Equal(99, Assert.Single(persisted.Hierarchy).GobjectId);
+        Assert.Equal("PV", Assert.Single(persisted.Attributes).AttributeName);
+    }
+
+    /// <summary>
+    ///     Verifies that when the Galaxy database is unreachable on first refresh but a
+    ///     snapshot exists on disk, the cache serves that data with <c>Stale</c> status
+    ///     rather than coming up empty.
+    /// </summary>
+    [Fact]
+    public async Task RefreshAsync_WhenDatabaseUnreachableButSnapshotOnDisk_RestoresStaleData()
+    {
+        GalaxyHierarchySnapshotStore store = CreateStore();
+        await store.SaveAsync(
+            new GalaxyHierarchySnapshot(
+                LastDeployTime: new DateTimeOffset(2026, 5, 20, 9, 0, 0, TimeSpan.Zero),
+                SavedAt: new DateTimeOffset(2026, 5, 20, 9, 1, 0, TimeSpan.Zero),
+                Hierarchy: [SampleHierarchyRow()],
+                Attributes: [SampleAttributeRow()]),
+            CancellationToken.None);
+
+        GalaxyDeployNotifier notifier = new();
+        ThrowingGalaxyRepository repository = new(new InvalidOperationException("Galaxy repository unreachable"));
+        GalaxyHierarchyCache cache = new(repository, notifier, new ManualTimeProvider(), snapshotStore: store);
+
+        await cache.RefreshAsync(CancellationToken.None);
+
+        Assert.Equal(GalaxyCacheStatus.Stale, cache.Current.Status);
+        Assert.True(cache.Current.HasData);
+        Assert.Equal(1, cache.Current.ObjectCount);
+        Assert.Equal(1, cache.Current.AttributeCount);
+        Assert.NotNull(notifier.Latest);
+    }
+
+    /// <summary>
+    ///     Verifies that when the disk snapshot's deploy time still matches the live
+    ///     Galaxy database, the cache promotes the restored data to <c>Healthy</c>
+    ///     without re-running the heavy hierarchy and attribute queries.
+    /// </summary>
+    [Fact]
+    public async Task RefreshAsync_WhenSnapshotDeployMatchesLive_PromotesToHealthyWithoutHeavyQuery()
+    {
+        DateTime deployTime = new(2026, 5, 20, 9, 0, 0, DateTimeKind.Utc);
+        GalaxyHierarchySnapshotStore store = CreateStore();
+        await store.SaveAsync(
+            new GalaxyHierarchySnapshot(
+                LastDeployTime: new DateTimeOffset(deployTime, TimeSpan.Zero),
+                SavedAt: new DateTimeOffset(2026, 5, 20, 9, 1, 0, TimeSpan.Zero),
+                Hierarchy: [SampleHierarchyRow()],
+                Attributes: [SampleAttributeRow()]),
+            CancellationToken.None);
+
+        GalaxyDeployNotifier notifier = new();
+        StubGalaxyRepository repository = new(deployTime);
+        GalaxyHierarchyCache cache = new(repository, notifier, new ManualTimeProvider(), snapshotStore: store);
+
+        await cache.RefreshAsync(CancellationToken.None);
+
+        Assert.Equal(GalaxyCacheStatus.Healthy, cache.Current.Status);
+        Assert.Equal(1, cache.Current.ObjectCount);
+        Assert.Equal(0, repository.GetHierarchyCount);
+        Assert.Equal(0, repository.GetAttributesCount);
+    }
+
+    /// <summary>
+    ///     Verifies that a restored on-disk snapshot completes the first-load gate
+    ///     immediately, so a browse call racing the first refresh is not blocked for
+    ///     the full bootstrap budget while the live Galaxy query is still running.
+    ///     Regression test for Server-033.
+    /// </summary>
+    [Fact]
+    public async Task RefreshAsync_RestoredSnapshotCompletesFirstLoadBeforeLiveQueryReturns()
+    {
+        GalaxyHierarchySnapshotStore store = CreateStore();
+        await store.SaveAsync(
+            new GalaxyHierarchySnapshot(
+                LastDeployTime: new DateTimeOffset(2026, 5, 20, 9, 0, 0, TimeSpan.Zero),
+                SavedAt: new DateTimeOffset(2026, 5, 20, 9, 1, 0, TimeSpan.Zero),
+                Hierarchy: [SampleHierarchyRow()],
+                Attributes: [SampleAttributeRow()]),
+            CancellationToken.None);
+
+        GalaxyDeployNotifier notifier = new();
+        BlockingGalaxyRepository repository = new();
+        GalaxyHierarchyCache cache = new(repository, notifier, new ManualTimeProvider(), snapshotStore: store);
+
+        Task refresh = cache.RefreshAsync(CancellationToken.None);
+
+        // The live query is blocked inside the repository; first-load must still
+        // complete — from the restored snapshot — well within the wait budget.
+        await cache.WaitForFirstLoadAsync(CancellationToken.None).WaitAsync(TimeSpan.FromSeconds(5));
+        Assert.True(cache.Current.HasData);
+        Assert.Equal(GalaxyCacheStatus.Stale, cache.Current.Status);
+
+        repository.Release();
+        await refresh.WaitAsync(TimeSpan.FromSeconds(5));
+    }
+
+    /// <summary>
+    ///     Verifies a corrupt on-disk snapshot does not crash startup: the cache
+    ///     ignores the unreadable file and comes up Unavailable when the database is
+    ///     also unreachable. Regression test for Server-037.
+    /// </summary>
+    [Fact]
+    public async Task RefreshAsync_WhenSnapshotFileCorrupt_ComesUpUnavailableWithoutThrowing()
+    {
+        string path = CreateTempPath();
+        await File.WriteAllTextAsync(path, "{ this is not valid json");
+        GalaxyHierarchySnapshotStore store = CreateStore(path);
+
+        GalaxyDeployNotifier notifier = new();
+        ThrowingGalaxyRepository repository = new(new InvalidOperationException("Galaxy repository unreachable"));
+        GalaxyHierarchyCache cache = new(repository, notifier, new ManualTimeProvider(), snapshotStore: store);
+
+        await cache.RefreshAsync(CancellationToken.None);
+
+        Assert.Equal(GalaxyCacheStatus.Unavailable, cache.Current.Status);
+        Assert.False(cache.Current.HasData);
+    }
+
+    /// <summary>
+    ///     Verifies that with snapshot persistence disabled the cache does not
+    ///     restore from disk — an unreachable database leaves it Unavailable.
+    ///     Regression test for Server-037.
+    /// </summary>
+    [Fact]
+    public async Task RefreshAsync_WhenPersistDisabled_DoesNotRestoreFromDisk()
+    {
+        GalaxyHierarchySnapshotStore store = CreateStore(CreateTempPath(), persist: false);
+
+        GalaxyDeployNotifier notifier = new();
+        ThrowingGalaxyRepository repository = new(new InvalidOperationException("Galaxy repository unreachable"));
+        GalaxyHierarchyCache cache = new(repository, notifier, new ManualTimeProvider(), snapshotStore: store);
+
+        await cache.RefreshAsync(CancellationToken.None);
+
+        Assert.Equal(GalaxyCacheStatus.Unavailable, cache.Current.Status);
+        Assert.False(cache.Current.HasData);
+    }
+
+    /// <summary>
+    ///     Verifies that a snapshot save aborted because the gateway is shutting down
+    ///     (the refresh token is cancelled) is not logged as a persistence failure.
+    ///     Regression test for Server-036.
+    /// </summary>
+    [Fact]
+    public async Task RefreshAsync_WhenSnapshotSaveCancelledAtShutdown_DoesNotLogPersistFailure()
+    {
+        using CancellationTokenSource cts = new();
+        GalaxyDeployNotifier notifier = new();
+        StubGalaxyRepository repository = new(
+            deployTime: new DateTime(2026, 5, 20, 9, 0, 0, DateTimeKind.Utc),
+            hierarchy: [SampleHierarchyRow()],
+            attributes: [SampleAttributeRow()]);
+        CancellingSaveStore store = new(cts);
+        RecordingLogger<GalaxyHierarchyCache> logger = new();
+        GalaxyHierarchyCache cache = new(repository, notifier, new ManualTimeProvider(), logger, store);
+
+        await cache.RefreshAsync(cts.Token);
+
+        Assert.DoesNotContain(
+            logger.Entries,
+            entry => entry.Level == LogLevel.Warning
+                && entry.Message.Contains("persist", StringComparison.OrdinalIgnoreCase));
+    }
+
+    private static GalaxyHierarchyRow SampleHierarchyRow() => new()
+    {
+        GobjectId = 99,
+        TagName = "Pump_001",
+        ContainedName = "Pump",
+        BrowseName = "Pump",
+        CategoryId = 10,
+        TemplateChain = ["AppPump"],
+    };
+
+    private static GalaxyAttributeRow SampleAttributeRow() => new()
+    {
+        GobjectId = 99,
+        TagName = "Pump_001",
+        AttributeName = "PV",
+        FullTagReference = "Pump_001.PV",
+        MxDataType = 5,
+        DataTypeName = "Float",
+    };
+
+    private string CreateTempPath()
+    {
+        string path = Path.Combine(
+            Path.GetTempPath(),
+            $"mxgw-galaxy-cache-test-{Guid.NewGuid():N}.json");
+        _tempPaths.Add(path);
+        return path;
+    }
+
+    private GalaxyHierarchySnapshotStore CreateStore() => CreateStore(CreateTempPath());
+
+    private static GalaxyHierarchySnapshotStore CreateStore(string path, bool persist = true)
+    {
+        GalaxyRepositoryOptions options = new()
+        {
+            PersistSnapshot = persist,
+            SnapshotCachePath = path,
+        };
+        return new GalaxyHierarchySnapshotStore(Options.Create(options));
+    }
+
+    /// <summary><see cref="IGalaxyRepository"/> whose deploy-time query blocks until released.</summary>
+    private sealed class BlockingGalaxyRepository : IGalaxyRepository
+    {
+        private readonly TaskCompletionSource _release = new(TaskCreationOptions.RunContinuationsAsynchronously);
+
+        public void Release() => _release.TrySetResult();
+
+        public Task<bool> TestConnectionAsync(CancellationToken ct = default) => Task.FromResult(false);
+
+        public async Task<DateTime?> GetLastDeployTimeAsync(CancellationToken ct = default)
+        {
+            await _release.Task.WaitAsync(ct).ConfigureAwait(false);
+            throw new InvalidOperationException("Galaxy repository unreachable");
+        }
+
+        public Task<List<GalaxyHierarchyRow>> GetHierarchyAsync(CancellationToken ct = default)
+            => throw new InvalidOperationException("GetHierarchyAsync should not be reached");
+
+        public Task<List<GalaxyAttributeRow>> GetAttributesAsync(CancellationToken ct = default)
+            => throw new InvalidOperationException("GetAttributesAsync should not be reached");
+    }
+
+    /// <summary>Snapshot store whose <see cref="SaveAsync"/> cancels the token mid-save.</summary>
+    private sealed class CancellingSaveStore(CancellationTokenSource cts) : IGalaxyHierarchySnapshotStore
+    {
+        public Task<GalaxyHierarchySnapshot?> TryLoadAsync(CancellationToken cancellationToken)
+            => Task.FromResult<GalaxyHierarchySnapshot?>(null);
+
+        public Task SaveAsync(GalaxyHierarchySnapshot snapshot, CancellationToken cancellationToken)
+        {
+            cts.Cancel();
+            cancellationToken.ThrowIfCancellationRequested();
+            return Task.CompletedTask;
+        }
+    }
+
+    /// <summary>Minimal <see cref="ILogger{T}"/> that records every emitted log entry.</summary>
+    private sealed class RecordingLogger<T> : ILogger<T>
+    {
+        public List<(LogLevel Level, string Message)> Entries { get; } = [];
+
+        public IDisposable BeginScope<TState>(TState state)
+            where TState : notnull => NullScope.Instance;
+
+        public bool IsEnabled(LogLevel logLevel) => true;
+
+        public void Log<TState>(
+            LogLevel logLevel,
+            EventId eventId,
+            TState state,
+            Exception? exception,
+            Func<TState, Exception?, string> formatter)
+        {
+            Entries.Add((logLevel, formatter(state, exception)));
+        }
+
+        private sealed class NullScope : IDisposable
+        {
+            public static readonly NullScope Instance = new();
+
+            public void Dispose()
+            {
+            }
+        }
+    }
+
+    /// <summary>In-memory <see cref="IGalaxyRepository"/> that returns fixed rowsets.</summary>
+    private sealed class StubGalaxyRepository(
+        DateTime? deployTime,
+        List<GalaxyHierarchyRow>? hierarchy = null,
+        List<GalaxyAttributeRow>? attributes = null) : IGalaxyRepository
+    {
+        private readonly List<GalaxyHierarchyRow> _hierarchy = hierarchy ?? [];
+        private readonly List<GalaxyAttributeRow> _attributes = attributes ?? [];
+
+        public int GetHierarchyCount { get; private set; }
+
+        public int GetAttributesCount { get; private set; }
+
+        public Task<bool> TestConnectionAsync(CancellationToken ct = default) => Task.FromResult(true);
+
+        public Task<DateTime?> GetLastDeployTimeAsync(CancellationToken ct = default) => Task.FromResult(deployTime);
+
+        public Task<List<GalaxyHierarchyRow>> GetHierarchyAsync(CancellationToken ct = default)
+        {
+            GetHierarchyCount++;
+            return Task.FromResult(_hierarchy);
+        }
+
+        public Task<List<GalaxyAttributeRow>> GetAttributesAsync(CancellationToken ct = default)
+        {
+            GetAttributesCount++;
+            return Task.FromResult(_attributes);
+        }
+    }
+
+    public void Dispose()
+    {
+        foreach (string path in _tempPaths)
+        {
+            try
+            {
+                File.Delete(path);
+                File.Delete(path + ".tmp");
+            }
+            catch (IOException)
+            {
+                // Best-effort cleanup of test scratch files.
+            }
+        }
+    }
+
     private sealed class ThrowingGalaxyRepository(Exception toThrow) : IGalaxyRepository
     {
         /// <summary>Gets the number of times <see cref="GetLastDeployTimeAsync"/> was called.</summary>

src/MxGateway.Tests/Galaxy/GalaxyHierarchySnapshotStoreTests.cs

@@ -0,0 +1,177 @@
+using Microsoft.Extensions.Options;
+using MxGateway.Server.Galaxy;
+
+namespace MxGateway.Tests.Galaxy;
+
+/// <summary>
+///     Covers <see cref="GalaxyHierarchySnapshotStore"/>: the on-disk persistence
+///     that lets the Galaxy browse cache survive a cold start while the Galaxy
+///     database is unreachable.
+/// </summary>
+public sealed class GalaxyHierarchySnapshotStoreTests : IDisposable
+{
+    private readonly List<string> _tempPaths = [];
+
+    [Fact]
+    public async Task SaveAsync_ThenTryLoadAsync_RoundTripsRows()
+    {
+        string path = CreateTempPath();
+        GalaxyHierarchySnapshotStore store = CreateStore(path);
+        GalaxyHierarchySnapshot snapshot = SampleSnapshot();
+
+        await store.SaveAsync(snapshot, CancellationToken.None);
+        GalaxyHierarchySnapshot? loaded = await store.TryLoadAsync(CancellationToken.None);
+
+        Assert.NotNull(loaded);
+        Assert.Equal(snapshot.LastDeployTime, loaded.LastDeployTime);
+        Assert.Equal(snapshot.SavedAt, loaded.SavedAt);
+
+        GalaxyHierarchyRow row = Assert.Single(loaded.Hierarchy);
+        Assert.Equal(7, row.GobjectId);
+        Assert.Equal("Pump_001", row.TagName);
+        Assert.Equal(["AppPump", "Pump"], row.TemplateChain);
+
+        Assert.Equal(2, loaded.Attributes.Count);
+        GalaxyAttributeRow withDimension = loaded.Attributes[0];
+        Assert.Equal("PV", withDimension.AttributeName);
+        Assert.Equal(8, withDimension.ArrayDimension);
+        Assert.True(withDimension.IsAlarm);
+        Assert.Null(loaded.Attributes[1].ArrayDimension);
+    }
+
+    [Fact]
+    public async Task TryLoadAsync_WhenNoFileExists_ReturnsNull()
+    {
+        GalaxyHierarchySnapshotStore store = CreateStore(CreateTempPath());
+
+        Assert.Null(await store.TryLoadAsync(CancellationToken.None));
+    }
+
+    [Fact]
+    public async Task SaveAsync_WhenPersistenceDisabled_WritesNothing()
+    {
+        string path = CreateTempPath();
+        GalaxyHierarchySnapshotStore store = CreateStore(path, persist: false);
+
+        await store.SaveAsync(SampleSnapshot(), CancellationToken.None);
+
+        Assert.False(File.Exists(path));
+        Assert.Null(await store.TryLoadAsync(CancellationToken.None));
+    }
+
+    [Fact]
+    public async Task TryLoadAsync_WhenFileIsCorruptJson_ReturnsNull()
+    {
+        string path = CreateTempPath();
+        await File.WriteAllTextAsync(path, "{ this is not valid json");
+        GalaxyHierarchySnapshotStore store = CreateStore(path);
+
+        Assert.Null(await store.TryLoadAsync(CancellationToken.None));
+    }
+
+    [Fact]
+    public async Task TryLoadAsync_WhenSchemaVersionUnrecognized_ReturnsNull()
+    {
+        string path = CreateTempPath();
+        await File.WriteAllTextAsync(path, """{"SchemaVersion":999,"Snapshot":null}""");
+        GalaxyHierarchySnapshotStore store = CreateStore(path);
+
+        Assert.Null(await store.TryLoadAsync(CancellationToken.None));
+    }
+
+    [Fact]
+    public async Task SaveAsync_OverwritesAnEarlierSnapshot()
+    {
+        string path = CreateTempPath();
+        GalaxyHierarchySnapshotStore store = CreateStore(path);
+
+        await store.SaveAsync(SampleSnapshot(), CancellationToken.None);
+        GalaxyHierarchySnapshot second = SampleSnapshot() with
+        {
+            Hierarchy = [],
+            Attributes = [],
+        };
+        await store.SaveAsync(second, CancellationToken.None);
+
+        GalaxyHierarchySnapshot? loaded = await store.TryLoadAsync(CancellationToken.None);
+        Assert.NotNull(loaded);
+        Assert.Empty(loaded.Hierarchy);
+        Assert.Empty(loaded.Attributes);
+    }
+
+    private static GalaxyHierarchySnapshot SampleSnapshot() => new(
+        LastDeployTime: new DateTimeOffset(2026, 5, 20, 9, 30, 0, TimeSpan.Zero),
+        SavedAt: new DateTimeOffset(2026, 5, 20, 9, 31, 0, TimeSpan.Zero),
+        Hierarchy:
+        [
+            new GalaxyHierarchyRow
+            {
+                GobjectId = 7,
+                TagName = "Pump_001",
+                ContainedName = "Pump",
+                BrowseName = "Pump",
+                CategoryId = 10,
+                TemplateChain = ["AppPump", "Pump"],
+            },
+        ],
+        Attributes:
+        [
+            new GalaxyAttributeRow
+            {
+                GobjectId = 7,
+                TagName = "Pump_001",
+                AttributeName = "PV",
+                FullTagReference = "Pump_001.PV[]",
+                MxDataType = 5,
+                DataTypeName = "Float",
+                IsArray = true,
+                ArrayDimension = 8,
+                IsAlarm = true,
+            },
+            new GalaxyAttributeRow
+            {
+                GobjectId = 7,
+                TagName = "Pump_001",
+                AttributeName = "Mode",
+                FullTagReference = "Pump_001.Mode",
+                MxDataType = 3,
+                DataTypeName = "Integer",
+                ArrayDimension = null,
+            },
+        ]);
+
+    private static GalaxyHierarchySnapshotStore CreateStore(string path, bool persist = true)
+    {
+        GalaxyRepositoryOptions options = new()
+        {
+            PersistSnapshot = persist,
+            SnapshotCachePath = path,
+        };
+        return new GalaxyHierarchySnapshotStore(Options.Create(options));
+    }
+
+    private string CreateTempPath()
+    {
+        string path = Path.Combine(
+            Path.GetTempPath(),
+            $"mxgw-galaxy-snapshot-{Guid.NewGuid():N}.json");
+        _tempPaths.Add(path);
+        return path;
+    }
+
+    public void Dispose()
+    {
+        foreach (string path in _tempPaths)
+        {
+            try
+            {
+                File.Delete(path);
+                File.Delete(path + ".tmp");
+            }
+            catch (IOException)
+            {
+                // Best-effort cleanup of test scratch files.
+            }
+        }
+    }
+}