fix(client/python): cap setuptools<77 so dist stays metadata 2.2 for Gitea PyPI feed; proprietary via classifier

Render Fallback:Mode=ForceSubtag as a cyan 'Subtag monitoring (forced)'
badge, distinct from the amber failover 'degraded' badge, so an intentional
configuration isn't shown as a fault. Distinguished by the shared
AlarmProviderReasons.ForcedSubtag reason carried on the provider-status feed.

.gitignore

@@ -147,3 +147,8 @@ generated-scratch/
 
 # Keep empty directories with .gitkeep files when needed
 !.gitkeep
+
+# Documentation review artifacts (CommentChecker output)
+*-docs-issues.md
+*-docs-fixed.md
+*-docs-final.md

CLAUDE.md

@@ -100,7 +100,7 @@ When source code changes, build and test the affected component before reporting
 ## Design Sources To Consult Before Non-Trivial Changes
 
 - `gateway.md` — top-level architecture, command/event surface, IPC envelope, STA thread model, fault handling.
-- `glauth.md` — local LDAP server (GLAuth on `localhost:3893`, base DN `dc=lmxopcua,dc=local`) used for dev authn. Pre-provisioned users (`admin/admin123`, `readonly/readonly123`, etc.) and the role→capability mapping live there.
+- `glauth.md` — shared GLAuth LDAP server (`10.100.0.35:3893`, base DN `dc=zb,dc=local`, source of truth `scadaproj/infra/glauth/`) used for dev authn. Dashboard test users (`multi-role`/`password` = Administrator, `gw-viewer`/`password` = Viewer) and the role→capability mapping live there.
 - `docs/DesignDecisions.md` — v1 choices (MXAccess COM target `LMXProxyServerClass` from `C:\Program Files (x86)\ArchestrA\Framework\Bin\ArchestrA.MXAccess.dll`, API-key-in-SQLite auth, fail-fast event backpressure, etc.).
 - `docs/GatewayProcessDesign.md`, `docs/MxAccessWorkerInstanceDesign.md`, `docs/WorkerFrameProtocol.md`, `docs/WorkerProcessLauncher.md` — detailed component designs.
 - `docs/GatewayConfiguration.md` — full `MxGateway:*` options bound by `GatewayOptions` and validated at startup by `GatewayOptionsValidator`.

clients/dotnet/Directory.Build.props

@@ -1,4 +1,17 @@
 <Project>
+  <PropertyGroup>
+    <!-- Build-quality enforcement floor, mirroring src/Directory.Build.props so the
+         .NET client tree is held to the same baseline CLAUDE.md mandates (warnings as
+         errors, code-style enforced at build, latest analyzers, deterministic builds). -->
+    <LangVersion>latest</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <AnalysisLevel>latest</AnalysisLevel>
+    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+    <Deterministic>true</Deterministic>
+  </PropertyGroup>
+
   <PropertyGroup>
     <!-- Shared package metadata for clients/dotnet/. Individual projects opt in via <IsPackable>true</IsPackable>. -->
     <Authors>Joseph Doherty</Authors>
@@ -10,11 +23,15 @@
     <PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/mxaccessgw</PackageProjectUrl>
     <PackageTags>mxaccess;mxgateway;grpc;client;archestra</PackageTags>
     <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
+    <!-- Proprietary/internal package, consistent with the Rust ("Proprietary") and
+         Python ("Proprietary") client license declarations. A LicenseRef SPDX expression
+         is rejected by the current NuGet toolset (NU5124), so the proprietary terms ship
+         as a packaged license file instead. -->
+    <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
     <!-- Versioning: bump per release. Symbols ship as snupkg. -->
-    <Version>0.1.0</Version>
+    <Version>0.1.1</Version>
     <IncludeSymbols>true</IncludeSymbols>
     <SymbolPackageFormat>snupkg</SymbolPackageFormat>
-    <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <!-- Default: do NOT pack. Each project opts in. -->
     <IsPackable>false</IsPackable>
   </PropertyGroup>

clients/dotnet/LICENSE.txt

@@ -0,0 +1,12 @@
+Proprietary License
+
+Copyright (c) ZB MOM WW. All rights reserved.
+
+This software and its source code are proprietary and confidential. They are
+licensed, not sold, for internal use within ZB MOM WW and its authorized
+partners only. No part of this package may be reproduced, distributed, or
+transmitted to third parties without the prior written permission of ZB MOM WW.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.

clients/dotnet/README.md

@@ -328,7 +328,7 @@ dotnet nuget add source https://gitea.dohertylan.com/api/packages/dohertj2/nuget
 Then add the package to your project:
 
 ````bash
-dotnet add package ZB.MOM.WW.MxGateway.Client --version 0.1.0
+dotnet add package ZB.MOM.WW.MxGateway.Client --version 0.1.1
 ````
 
 The `ZB.MOM.WW.MxGateway.Contracts` package is pulled in transitively.

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/FakeGalaxyRepositoryTransport.cs

@@ -135,25 +135,35 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
     /// <summary>Queue of exceptions to throw from BrowseChildren; dequeued in FIFO order.</summary>
     public Queue<Exception> BrowseChildrenExceptions { get; } = new();
 
+    /// <summary>
+    /// Optional hook awaited inside BrowseChildren before the reply is produced. Lets a
+    /// test hold an RPC mid-flight to exercise concurrent reads of the in-progress node.
+    /// </summary>
+    public Func<Task>? BrowseChildrenGate { get; set; }
+
     /// <summary>
     /// Records the request and either throws a queued exception or returns the configured reply.
     /// </summary>
     /// <param name="request">The BrowseChildrenRequest to process.</param>
     /// <param name="callOptions">Call options specifying RPC behavior.</param>
-    public Task<BrowseChildrenReply> BrowseChildrenAsync(
+    public async Task<BrowseChildrenReply> BrowseChildrenAsync(
         BrowseChildrenRequest request,
         CallOptions callOptions)
     {
         BrowseChildrenCalls.Add((request, callOptions));
         if (BrowseChildrenExceptions.TryDequeue(out Exception? exception))
         {
-            return Task.FromException<BrowseChildrenReply>(exception);
+            throw exception;
         }
 
-        return Task.FromResult(
-            BrowseChildrenReplies.TryDequeue(out BrowseChildrenReply? reply)
-                ? reply
-                : BrowseChildrenReply);
+        if (BrowseChildrenGate is { } gate)
+        {
+            await gate().ConfigureAwait(false);
+        }
+
+        return BrowseChildrenReplies.TryDequeue(out BrowseChildrenReply? reply)
+            ? reply
+            : BrowseChildrenReply;
     }
 
     /// <summary>

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/LazyBrowseNodeTests.cs

@@ -175,6 +175,96 @@ public sealed class LazyBrowseNodeTests
         Assert.Equal(2, transport.BrowseChildrenCalls.Count);
     }
 
+    /// <summary>
+    /// Verifies that reading Children/IsExpanded concurrently with an in-flight ExpandAsync
+    /// never throws (no torn enumeration of a mid-append list) and, once IsExpanded flips to
+    /// true, the published Children snapshot is fully populated. Pins the safe-publication
+    /// contract on the lock-free readers (Client.Dotnet-025).
+    /// </summary>
+    [Fact]
+    public async Task Expand_ConcurrentReadOfChildren_NeverTearsAndPublishesAtomically()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.BrowseChildrenReplies.Enqueue(BuildReply(
+            children: [BuildObject(1, "Plant", isArea: true)],
+            childHasChildren: [true],
+            cacheSequence: 1));
+
+        // Multi-page child set so the expand loop spends meaningful time appending,
+        // widening the window for a concurrent reader to observe a torn list.
+        BrowseChildrenReply childPage1 = BuildReply(
+            children: [BuildObject(10, "A"), BuildObject(11, "B"), BuildObject(12, "C")],
+            childHasChildren: [false, false, false],
+            cacheSequence: 1);
+        childPage1.NextPageToken = "1:p:3";
+        transport.BrowseChildrenReplies.Enqueue(childPage1);
+        transport.BrowseChildrenReplies.Enqueue(BuildReply(
+            children: [BuildObject(13, "D"), BuildObject(14, "E")],
+            childHasChildren: [false, false],
+            cacheSequence: 1));
+
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+        IReadOnlyList<LazyBrowseNode> roots = await client.BrowseAsync();
+        LazyBrowseNode node = roots[0];
+
+        // Gate the child-page RPCs so the expand stays mid-flight while the reader spins.
+        using SemaphoreSlim release = new(0, 1);
+        bool firstChildCall = true;
+        transport.BrowseChildrenGate = async () =>
+        {
+            if (firstChildCall)
+            {
+                firstChildCall = false;
+                await release.WaitAsync().ConfigureAwait(false);
+            }
+        };
+
+        using CancellationTokenSource readerStop = new();
+        Exception? readerFailure = null;
+        Task reader = Task.Run(() =>
+        {
+            try
+            {
+                while (!readerStop.IsCancellationRequested)
+                {
+                    bool expanded = node.IsExpanded;
+
+                    // Enumerate the snapshot; a torn/mid-append list would throw here.
+                    int count = 0;
+                    foreach (LazyBrowseNode _ in node.Children)
+                    {
+                        count++;
+                    }
+
+                    // If the node reports expanded, the published snapshot must be complete.
+                    if (expanded)
+                    {
+                        Assert.Equal(5, count);
+                    }
+                }
+            }
+            catch (Exception ex)
+            {
+                readerFailure = ex;
+            }
+        });
+
+        Task expand = node.ExpandAsync();
+        // Let the reader spin against the empty pre-publication snapshot for a moment.
+        await Task.Delay(50);
+        release.Release();
+        await expand;
+
+        // Let the reader observe the post-publication state, then stop it.
+        await Task.Delay(50);
+        readerStop.Cancel();
+        await reader;
+
+        Assert.Null(readerFailure);
+        Assert.True(node.IsExpanded);
+        Assert.Equal(5, node.Children.Count);
+    }
+
     /// <summary>
     /// Verifies that BrowseChildrenOptions filter fields are forwarded to the BrowseChildren request.
     /// </summary>

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

@@ -12,9 +12,14 @@ public sealed class LazyBrowseNode
 {
     private readonly GalaxyRepositoryClient _client;
     private readonly BrowseChildrenOptions _options;
-    private readonly List<LazyBrowseNode> _children = [];
     private readonly SemaphoreSlim _expandLock = new(1, 1);
-    private bool _isExpanded;
+
+    // Published once, under _expandLock, when expansion completes. Lock-free readers
+    // see either the empty pre-expansion snapshot or the fully-populated post-expansion
+    // snapshot — never a partially-filled list — because the snapshot is built in a local
+    // and handed off via Volatile.Write (release) paired with Volatile.Read (acquire).
+    private IReadOnlyList<LazyBrowseNode> _children = [];
+    private volatile bool _isExpanded;
 
     internal LazyBrowseNode(
         GalaxyRepositoryClient client,
@@ -35,7 +40,7 @@ public sealed class LazyBrowseNode
     public bool HasChildrenHint { get; }
 
     /// <summary>Direct children loaded by <see cref="ExpandAsync"/>; empty until then.</summary>
-    public IReadOnlyList<LazyBrowseNode> Children => _children;
+    public IReadOnlyList<LazyBrowseNode> Children => Volatile.Read(ref _children);
 
     /// <summary>True after the first <see cref="ExpandAsync"/> call completes.</summary>
     public bool IsExpanded => _isExpanded;
@@ -46,7 +51,13 @@ public sealed class LazyBrowseNode
     /// </summary>
     /// <remarks>
     ///     Thread-safe: concurrent callers see exactly one fetch; subsequent callers
-    ///     (after the first completes) return immediately.
+    ///     (after the first completes) return immediately. <see cref="Children"/> and
+    ///     <see cref="IsExpanded"/> may be read concurrently with an in-flight
+    ///     <see cref="ExpandAsync"/> on another thread; the populated children are
+    ///     published as an immutable snapshot under a release barrier, so a reader that
+    ///     observes <see cref="IsExpanded"/> as <see langword="true"/> always sees the
+    ///     fully-populated <see cref="Children"/>, and a reader never enumerates a
+    ///     partially-built list.
     /// </remarks>
     /// <param name="cancellationToken">Token to observe for cancellation.</param>
     public async Task ExpandAsync(CancellationToken cancellationToken = default)
@@ -64,6 +75,10 @@ public sealed class LazyBrowseNode
                 return;
             }
 
+            // Accumulate into a local list, never the published field, so a lock-free
+            // reader can never observe a half-populated collection or enumerate a list
+            // that is being mutated mid-append.
+            List<LazyBrowseNode> children = [];
             string pageToken = string.Empty;
             HashSet<string> seenPageTokens = new(StringComparer.Ordinal);
             do
@@ -79,7 +94,7 @@ public sealed class LazyBrowseNode
                 for (int i = 0; i < reply.Children.Count; i++)
                 {
                     bool hint = i < reply.ChildHasChildren.Count && reply.ChildHasChildren[i];
-                    _children.Add(new LazyBrowseNode(_client, reply.Children[i], hint, _options));
+                    children.Add(new LazyBrowseNode(_client, reply.Children[i], hint, _options));
                 }
 
                 pageToken = reply.NextPageToken;
@@ -91,6 +106,10 @@ public sealed class LazyBrowseNode
             }
             while (!string.IsNullOrWhiteSpace(pageToken));
 
+            // Publish the completed, immutable snapshot (release) before marking the node
+            // expanded (the volatile write below). A reader that observes IsExpanded == true
+            // is guaranteed to also observe the fully-populated Children.
+            Volatile.Write(ref _children, children);
             _isExpanded = true;
         }
         finally

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

@@ -21,10 +21,15 @@
     <PackageId>ZB.MOM.WW.MxGateway.Client</PackageId>
     <Description>.NET 10 gRPC client for the MxAccessGateway service. Provides typed wrappers, retry, and a lazy-browse walker over the Galaxy Repository hierarchy.</Description>
     <PackageReadmeFile>README.md</PackageReadmeFile>
+    <!-- Only the shipped library generates XML docs (matching src/Contracts). The Cli and
+         Tests projects are not packable and do not document their public surface, so this
+         stays out of the shared Directory.Build.props to avoid CS1591 on test classes. -->
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
   <ItemGroup>
     <None Include="..\README.md" Pack="true" PackagePath="\" />
+    <None Include="..\LICENSE.txt" Pack="true" PackagePath="\" />
   </ItemGroup>
 
   <ItemGroup>

clients/go/README.md

@@ -288,7 +288,7 @@ go run ./cmd/mxgw-go smoke -endpoint $env:MXGATEWAY_ENDPOINT -plaintext -api-key
 The module is resolved directly from the git repo — no package registry:
 
 ````bash
-go get gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go@v0.1.0
+go get gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go@v0.1.1
 ````
 
 Then import:
@@ -299,8 +299,11 @@ import "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/mxgateway"
 
 If your build environment cannot reach `gitea.dohertylan.com` directly,
 configure `GOPROXY` to point at an internal proxy that fronts the Gitea
-repo, or use `GONOSUMCHECK` + `GOPRIVATE` to bypass the checksum database
-for the internal module path.
+repo, or set `GOPRIVATE=gitea.dohertylan.com/*` to fetch the module
+straight from the VCS — this both bypasses the public module proxy and
+disables checksum-database (`sum.golang.org`) verification for that path.
+Add `GOINSECURE=gitea.dohertylan.com/*` if the host serves the module over
+plain HTTP rather than HTTPS.
 
 ## Releasing a new version
 

clients/java/README.md

@@ -128,18 +128,20 @@ gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-discover --endpoint localhost
 
 ### Browsing lazily
 
-For UI trees or OPC UA bridges, use `browseChildren` to walk one level at a
+For UI trees or OPC UA bridges, use `browseChildrenRaw` to walk one level at a
 time instead of loading the full hierarchy with `discoverHierarchy`. Pass a
 default request for root objects; subsequent calls set `parentGobjectId`,
 `parentTagName`, or `parentContainedPath`. Filter fields match
 `DiscoverHierarchy`. Each response pairs `getChildrenList()` with
 `getChildHasChildrenList()` so you know which nodes to expand. See
 [Galaxy Repository](../../docs/GalaxyRepository.md#browsechildren) for full
-request and filter semantics. This snippet documents the API as it appears once
-the Java client is regenerated on the Windows host.
+request and filter semantics. For most callers the high-level
+`browse()`/`LazyBrowseNode` walker below is the preferred surface;
+`browseChildrenRaw` exposes the single underlying RPC when you need direct
+control of paging.
 
 ```java
-BrowseChildrenReply reply = galaxy.browseChildren(
+BrowseChildrenReply reply = galaxy.browseChildrenRaw(
         BrowseChildrenRequest.newBuilder().build());
 
 List<GalaxyObject> children = reply.getChildrenList();
@@ -248,8 +250,11 @@ gradle :zb-mom-ww-mxgateway-cli:run --args="smoke --endpoint localhost:5000 --ap
 ```
 
 The CLI accepts `--api-key`, `--api-key-env`, `--plaintext`, `--ca-file`,
-`--server-name-override`, `--timeout`, and `--json` on gateway commands. JSON
-output redacts API keys.
+`--server-name-override`, `--require-certificate-validation`, `--timeout`, and
+`--json` on gateway commands. JSON output redacts API keys. TLS is lenient by
+default (the certificate is not verified unless you pin a CA with `--ca-file`);
+pass `--require-certificate-validation` to verify the server certificate against
+the JVM trust store without pinning.
 
 Use TLS options for a secured gateway:
 
@@ -311,7 +316,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.zb.mom.ww.mxgateway:zb-mom-ww-mxgateway-client:0.1.0'
+    implementation 'com.zb.mom.ww.mxgateway:zb-mom-ww-mxgateway-client:0.1.1'
 }
 ````
 

clients/java/build.gradle

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

clients/java/zb-mom-ww-mxgateway-cli/src/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java

@@ -37,6 +37,7 @@ import java.util.concurrent.atomic.AtomicReference;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest;
 import mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmProviderStatus;
 import mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage;
 import mxaccess_gateway.v1.MxaccessGateway.BulkReadResult;
 import mxaccess_gateway.v1.MxaccessGateway.BulkWriteResult;
@@ -1366,6 +1367,13 @@ public final class MxGatewayCli implements Callable<Integer> {
         @Option(names = "--server-name-override", description = "TLS server name override.")
         String serverNameOverride = "";
 
+        @Option(
+                names = "--require-certificate-validation",
+                description =
+                        "Verify the server certificate against the JVM trust store "
+                                + "(disables the lenient default; ignored with --plaintext or --ca-file pinning).")
+        boolean requireCertificateValidation;
+
         @Option(names = "--timeout", defaultValue = "30s", description = "Per-call timeout.")
         String timeout;
 
@@ -1388,6 +1396,7 @@ public final class MxGatewayCli implements Callable<Integer> {
                     .plaintext(plaintext)
                     .caCertificatePath(caFile)
                     .serverNameOverride(serverNameOverride)
+                    .requireCertificateValidation(requireCertificateValidation)
                     .callTimeout(resolvedTimeout)
                     .build();
         }
@@ -1400,6 +1409,7 @@ public final class MxGatewayCli implements Callable<Integer> {
             values.put("plaintext", plaintext);
             values.put("caFile", caFile == null ? "" : caFile.toString());
             values.put("serverNameOverride", serverNameOverride);
+            values.put("requireCertificateValidation", requireCertificateValidation);
             values.put("timeout", timeout);
             return values;
         }
@@ -1703,6 +1713,12 @@ public final class MxGatewayCli implements Callable<Integer> {
                         transition.getTransitionKind().name(),
                         transition.getSeverity());
             }
+            case PROVIDER_STATUS -> {
+                AlarmProviderStatus status = message.getProviderStatus();
+                yield String.format(
+                        "provider-status mode=%s degraded=%b reason=%s",
+                        status.getMode().name(), status.getDegraded(), status.getReason());
+            }
             case PAYLOAD_NOT_SET -> "unknown";
         };
     }

clients/java/zb-mom-ww-mxgateway-cli/src/test/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCliTests.java

@@ -5,6 +5,7 @@ import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import com.zb.mom.ww.mxgateway.client.MxGatewayAlarmFeedSubscription;
+import com.zb.mom.ww.mxgateway.client.MxGatewayClientOptions;
 import io.grpc.stub.StreamObserver;
 import java.io.ByteArrayInputStream;
 import java.io.InputStream;
@@ -289,6 +290,51 @@ final class MxGatewayCliTests {
         }
     }
 
+    @Test
+    void requireCertificateValidationFlagPropagatesThroughToClientOptions() {
+        // Client.Java-038 regression — the --require-certificate-validation
+        // CLI flag must reach MxGatewayClientOptions.requireCertificateValidation
+        // via CommonOptions.toClientOptions(), so CLI users can opt into strict
+        // JVM-trust verification without pinning a CA.
+        CapturingClientFactory factory = new CapturingClientFactory();
+        CliRun run = execute(
+                factory,
+                "acknowledge-alarm",
+                "--endpoint",
+                "localhost:5000",
+                "--api-key-env",
+                "MXGATEWAY_API_KEY",
+                "--require-certificate-validation",
+                "--reference",
+                "Tank01.Level.HiHi");
+
+        assertEquals(0, run.exitCode(), "errors:\n" + run.errors());
+        assertTrue(
+                factory.capturedClientOptions.requireCertificateValidation(),
+                "--require-certificate-validation did not propagate into MxGatewayClientOptions");
+    }
+
+    @Test
+    void requireCertificateValidationDefaultsToLenientWhenFlagAbsent() {
+        // Without the flag, the lenient-by-default trust posture must be
+        // preserved (requireCertificateValidation == false).
+        CapturingClientFactory factory = new CapturingClientFactory();
+        CliRun run = execute(
+                factory,
+                "acknowledge-alarm",
+                "--endpoint",
+                "localhost:5000",
+                "--api-key-env",
+                "MXGATEWAY_API_KEY",
+                "--reference",
+                "Tank01.Level.HiHi");
+
+        assertEquals(0, run.exitCode(), "errors:\n" + run.errors());
+        assertFalse(
+                factory.capturedClientOptions.requireCertificateValidation(),
+                "requireCertificateValidation should default to false (lenient)");
+    }
+
     @Test
     void streamAlarmsCommandFailsFastOnQueueOverflow() {
         // Client.Java-033 regression — the CLI's stream-alarms bounded queue
@@ -435,6 +481,23 @@ final class MxGatewayCliTests {
         }
     }
 
+    /**
+     * Factory that records the {@link MxGatewayClientOptions} produced by
+     * {@link MxGatewayCli.CommonOptions#toClientOptions()} so a test can assert
+     * how CLI flags map onto the library option surface. Wraps the standard
+     * {@link FakeClient} so the command body still completes. Used by the
+     * Client.Java-038 option-flow regression.
+     */
+    private static final class CapturingClientFactory implements MxGatewayCli.MxGatewayCliClientFactory {
+        private MxGatewayClientOptions capturedClientOptions;
+
+        @Override
+        public MxGatewayCli.MxGatewayCliClient connect(MxGatewayCli.CommonOptions options) {
+            capturedClientOptions = options.toClientOptions();
+            return new FakeClient(options.spec.commandLine().getOut());
+        }
+    }
+
     /**
      * Factory whose fake client floods the {@code streamAlarms} observer with
      * 2000 messages synchronously, exceeding the CLI's bounded 1024-element

clients/python/README.md

@@ -238,7 +238,11 @@ left `False`, the client fetches the gateway's presented certificate once
 to `localhost` (the generated certificate always carries a `localhost` SAN) when
 none was supplied. To verify instead, pass `ca_file` to verify against a specific
 CA, or set `require_certificate_validation=True` to verify against the system
-trust roots. See
+trust roots. The strict posture is reachable through every documented entry
+point: the `require_certificate_validation=True` keyword on
+`GatewayClient.connect(...)` / `GalaxyRepositoryClient.connect(...)`, the
+`ClientOptions(require_certificate_validation=True)` struct, and the
+`--require-certificate-validation` CLI flag. See
 [Gateway Configuration](../../docs/GatewayConfiguration.md#automatic-self-signed-certificate).
 
 ## CLI
@@ -267,6 +271,13 @@ Use TLS options for a secured gateway:
 mxgw-py smoke --endpoint mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item Object.Attribute --json
 ```
 
+To force certificate validation against the system trust store instead of the
+lenient trust-on-first-use default, add `--require-certificate-validation`:
+
+```powershell
+mxgw-py smoke --endpoint mxgateway.example.local:5001 --tls --require-certificate-validation --api-key-env MXGATEWAY_API_KEY --item Object.Attribute --json
+```
+
 ## Integration Checks
 
 Run live checks only when a gateway and MXAccess-backed worker are available:

clients/python/pyproject.toml

@@ -1,10 +1,12 @@
 [build-system]
-requires = ["setuptools>=69", "wheel"]
+# setuptools >=77 emits core-metadata 2.4 (PEP 639 License-Expression), which the
+# Gitea PyPI feed does not yet accept; cap below that so the dist stays <=2.3.
+requires = ["setuptools>=69,<77", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "zb-mom-ww-mxaccess-gateway-client"
-version = "0.1.0"
+version = "0.1.1"
 description = "Async Python client scaffold for MXAccess Gateway."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -16,11 +18,10 @@ dependencies = [
 authors = [
   { name = "Joseph Doherty" },
 ]
-license = { text = "Proprietary" }
 keywords = ["mxaccess", "mxgateway", "grpc", "client", "archestra"]
 classifiers = [
-  "Development Status :: 3 - Alpha",
   "License :: Other/Proprietary License",
+  "Development Status :: 3 - Alpha",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
@@ -54,3 +55,6 @@ where = ["src"]
 addopts = "-ra"
 pythonpath = ["src"]
 testpaths = ["tests"]
+markers = [
+  "tls: loopback TLS tests, opt-in via MXGATEWAY_RUN_TLS_TESTS=1",
+]

clients/python/src/zb_mom_ww_mxgateway/client.py

@@ -40,6 +40,7 @@ class GatewayClient:
         api_key: str | None = None,
         plaintext: bool = False,
         ca_file: str | None = None,
+        require_certificate_validation: bool = False,
         server_name_override: str | None = None,
         stub: Any | None = None,
     ) -> "GatewayClient":
@@ -50,13 +51,16 @@ class GatewayClient:
             api_key=api_key,
             plaintext=plaintext,
             ca_file=ca_file,
+            require_certificate_validation=require_certificate_validation,
             server_name_override=server_name_override,
         )
 
         if stub is not None:
             return cls(options=resolved, stub=stub)
 
-        channel = create_channel(resolved)
+        # create_channel may perform a blocking TLS certificate probe (TOFU
+        # default); run it off the event loop so connect never freezes the loop.
+        channel = await asyncio.to_thread(create_channel, resolved)
         return cls(
             options=resolved,
             stub=pb_grpc.MxAccessGatewayStub(channel),

clients/python/src/zb_mom_ww_mxgateway/galaxy.py

@@ -52,6 +52,7 @@ class GalaxyRepositoryClient:
         api_key: str | None = None,
         plaintext: bool = False,
         ca_file: str | None = None,
+        require_certificate_validation: bool = False,
         server_name_override: str | None = None,
         stub: Any | None = None,
     ) -> "GalaxyRepositoryClient":
@@ -62,13 +63,16 @@ class GalaxyRepositoryClient:
             api_key=api_key,
             plaintext=plaintext,
             ca_file=ca_file,
+            require_certificate_validation=require_certificate_validation,
             server_name_override=server_name_override,
         )
 
         if stub is not None:
             return cls(options=resolved, stub=stub)
 
-        channel = create_channel(resolved)
+        # create_channel may perform a blocking TLS certificate probe (TOFU
+        # default); run it off the event loop so connect never freezes the loop.
+        channel = await asyncio.to_thread(create_channel, resolved)
         return cls(
             options=resolved,
             stub=galaxy_pb_grpc.GalaxyRepositoryStub(channel),

clients/python/src/zb_mom_ww_mxgateway/options.py

@@ -12,6 +12,10 @@ import grpc
 from .auth import REDACTED, ApiKey
 from .errors import MxGatewayTransportError
 
+# Fallback bound for the TOFU certificate probe when no call_timeout is set, so a
+# black-holed host fails fast instead of hanging on the OS default connect timeout.
+_TOFU_PROBE_TIMEOUT_SECONDS = 10.0
+
 
 @dataclass(frozen=True)
 class ClientOptions:
@@ -88,8 +92,17 @@ def _split_authority(endpoint: str) -> tuple[str, int]:
         remainder = target[bracket_end + 1 :]  # ":5120" or ""
         port_str = remainder.lstrip(":")
         return (host, int(port_str) if port_str else 443)
-    host, _, port = target.rpartition(":")
-    return (host or "localhost", int(port) if port else 443)
+    host, sep, port = target.rpartition(":")
+    if not sep:
+        # No colon at all (e.g. a bare hostname "mygateway"): the whole target
+        # is the host; default the port rather than raising on int("mygateway").
+        return (target or "localhost", 443)
+    if not port.isdigit():
+        # A colon with a non-numeric / empty tail (e.g. a trailing ":") is not
+        # an explicit port — keep the left side as the host and default the
+        # port so a typo cannot raise an uncaught ValueError on the TOFU path.
+        return (host or "localhost", 443)
+    return (host or "localhost", int(port))
 
 
 def create_channel(options: ClientOptions) -> grpc.aio.Channel:
@@ -120,9 +133,15 @@ def create_channel(options: ClientOptions) -> grpc.aio.Channel:
     else:
         # Lenient default: grpc-python has no per-channel skip-verify, so fetch the
         # server's certificate (unverified) and pin it for this channel (TOFU).
+        # The probe opens a real blocking TCP+TLS socket, so it MUST be bounded —
+        # a black-holed / firewall-drop host would otherwise hang on the OS default
+        # connect timeout (minutes). Bound it by call_timeout (or a short fixed
+        # fallback) so the dial fails fast as a transport error. The async
+        # `connect` classmethods run this off the event loop (asyncio.to_thread).
         host, port = _split_authority(options.endpoint)
+        probe_timeout = options.call_timeout if options.call_timeout else _TOFU_PROBE_TIMEOUT_SECONDS
         try:
-            presented = ssl.get_server_certificate((host, port))
+            presented = ssl.get_server_certificate((host, port), timeout=probe_timeout)
         except OSError as error:
             raise MxGatewayTransportError(
                 f"failed to fetch TLS certificate from {options.endpoint}: {error}"

clients/python/src/zb_mom_ww_mxgateway_cli/commands.py

@@ -170,6 +170,13 @@ def gateway_options(command: Callable[..., Any]) -> Callable[..., Any]:
     command = click.option("--plaintext", is_flag=True, help="Use plaintext gRPC.")(command)
     command = click.option("--tls", "use_tls", is_flag=True, help="Use TLS gRPC.")(command)
     command = click.option("--ca-file", default=None, help="Custom root certificate file.")(command)
+    command = click.option(
+        "--require-certificate-validation",
+        "require_certificate_validation",
+        is_flag=True,
+        help="Verify the TLS certificate against the system trust store "
+        "instead of the lenient trust-on-first-use default.",
+    )(command)
     command = click.option(
         "--server-name-override",
         default=None,
@@ -923,6 +930,7 @@ async def _connect(kwargs: dict[str, Any]) -> GatewayClient:
             api_key=api_key,
             plaintext=_use_plaintext(kwargs),
             ca_file=kwargs.get("ca_file"),
+            require_certificate_validation=bool(kwargs.get("require_certificate_validation")),
             server_name_override=kwargs.get("server_name_override"),
             call_timeout=kwargs.get("call_timeout"),
             stream_timeout=kwargs.get("stream_timeout"),

clients/python/tests/test_auth_options.py

@@ -1,9 +1,12 @@
 """Tests for auth metadata and connection options."""
 
+import socket
+
 import pytest
 
 from zb_mom_ww_mxgateway.auth import REDACTED, ApiKey, auth_metadata, redact_secret
 from zb_mom_ww_mxgateway import options as options_module
+from zb_mom_ww_mxgateway.errors import MxGatewayTransportError
 from zb_mom_ww_mxgateway.options import ClientOptions, create_channel
 
 
@@ -80,7 +83,9 @@ def test_create_channel_uses_tls_channel_tofu_default(monkeypatch: pytest.Monkey
     _DUMMY_PEM = "-----BEGIN CERTIFICATE-----\nZmFrZQ==\n-----END CERTIFICATE-----\n"
     get_cert_calls: list[tuple[str, int]] = []
 
-    def fake_get_server_certificate(addr: tuple[str, int]) -> str:
+    def fake_get_server_certificate(
+        addr: tuple[str, int], *, timeout: float | None = None
+    ) -> str:
         get_cert_calls.append(addr)
         return _DUMMY_PEM
 
@@ -133,7 +138,7 @@ def test_create_channel_uses_tls_channel_tofu_respects_server_name_override(
     monkeypatch.setattr(
         options_module.ssl,
         "get_server_certificate",
-        lambda addr: _DUMMY_PEM,
+        lambda addr, *, timeout=None: _DUMMY_PEM,
     )
     cred_calls: list[object] = []
 
@@ -276,3 +281,46 @@ def test_create_channel_uses_tls_channel_ca_file(
             ],
         ),
     ]
+
+
+def test_tofu_probe_passes_a_bounded_timeout(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The TOFU cert pre-fetch must be bounded so a black-holed host fails fast."""
+    captured: dict[str, object] = {}
+
+    def fake_get_server_certificate(addr: object, *, timeout: float | None = None) -> str:
+        captured["timeout"] = timeout
+        return "-----BEGIN CERTIFICATE-----\nZmFrZQ==\n-----END CERTIFICATE-----\n"
+
+    monkeypatch.setattr(options_module.ssl, "get_server_certificate", fake_get_server_certificate)
+    monkeypatch.setattr(options_module.grpc, "ssl_channel_credentials", lambda **_: "creds")
+    monkeypatch.setattr(
+        options_module.grpc.aio,
+        "secure_channel",
+        lambda endpoint, credentials, *, options: "tls-channel",
+    )
+
+    create_channel(ClientOptions(endpoint="gateway.example:5001", call_timeout=7.5))
+
+    # A finite, positive timeout must be supplied (bounded by call_timeout here).
+    assert isinstance(captured["timeout"], (int, float))
+    assert 0 < captured["timeout"] <= 7.5
+
+
+@pytest.mark.parametrize(
+    "raised",
+    [socket.timeout("timed out"), TimeoutError("timed out"), OSError("connection refused")],
+)
+def test_tofu_probe_timeout_raises_transport_error(
+    monkeypatch: pytest.MonkeyPatch, raised: Exception
+) -> None:
+    """A timed-out / failed probe surfaces as MxGatewayTransportError, not a raw error."""
+
+    def fake_get_server_certificate(addr: object, *, timeout: float | None = None) -> str:
+        raise raised
+
+    monkeypatch.setattr(options_module.ssl, "get_server_certificate", fake_get_server_certificate)
+
+    options = ClientOptions(endpoint="gateway.example:5001")
+    with pytest.raises(MxGatewayTransportError) as excinfo:
+        create_channel(options)
+    assert options.endpoint in str(excinfo.value)

clients/python/tests/test_cli.py

@@ -2,14 +2,79 @@
 
 import json
 
+import pytest
 from click.testing import CliRunner
 
 from zb_mom_ww_mxgateway import __version__
+from zb_mom_ww_mxgateway_cli import commands as commands_module
 from zb_mom_ww_mxgateway_cli.commands import main
 
 _BATCH_EOR = "__MXGW_BATCH_EOR__"
 
 
+def test_require_certificate_validation_flag_flows_through_connect(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The --require-certificate-validation CLI flag must reach ClientOptions (Client.Python-027)."""
+    captured: dict[str, object] = {}
+
+    async def fake_connect(options, **_kwargs):
+        captured["options"] = options
+        # Return a minimal object that supports the async context-manager protocol
+        # used by every CLI command body (async with await _connect(...) as client).
+        return _FakeAsyncClient()
+
+    monkeypatch.setattr(commands_module.GatewayClient, "connect", fake_connect)
+
+    result = CliRunner().invoke(
+        main,
+        [
+            "open-session",
+            "--endpoint",
+            "gateway.example:5001",
+            "--require-certificate-validation",
+            "--json",
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert captured["options"].require_certificate_validation is True
+
+
+def test_require_certificate_validation_defaults_off(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Without the flag the strict-validation posture stays off (TOFU default)."""
+    captured: dict[str, object] = {}
+
+    async def fake_connect(options, **_kwargs):
+        captured["options"] = options
+        return _FakeAsyncClient()
+
+    monkeypatch.setattr(commands_module.GatewayClient, "connect", fake_connect)
+
+    result = CliRunner().invoke(
+        main,
+        ["open-session", "--endpoint", "gateway.example:5001", "--plaintext", "--json"],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert captured["options"].require_certificate_validation is False
+
+
+class _FakeAsyncClient:
+    """Minimal async-context-manager fake satisfying the open-session command body."""
+
+    async def __aenter__(self) -> "_FakeAsyncClient":
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        return None
+
+    async def open_session_raw(self, *_args, **_kwargs):
+        from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2 as pb
+
+        return pb.OpenSessionReply(session_id="cli-test-session")
+
+
 def test_version_json_is_deterministic() -> None:
     runner = CliRunner()
 

clients/python/tests/test_client_session.py

@@ -8,9 +8,107 @@ from typing import Any
 import pytest
 
 from zb_mom_ww_mxgateway import ClientOptions, GatewayClient, MxAccessError
+from zb_mom_ww_mxgateway import client as client_module
+from zb_mom_ww_mxgateway import galaxy as galaxy_module
+from zb_mom_ww_mxgateway.galaxy import GalaxyRepositoryClient
 from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2 as pb
 
 
+@pytest.mark.asyncio
+async def test_gateway_connect_forwards_require_certificate_validation(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The connect convenience kwarg must reach ClientOptions (Client.Python-027)."""
+    captured: dict[str, Any] = {}
+
+    def fake_create_channel(options: ClientOptions) -> object:
+        captured["options"] = options
+        return object()
+
+    monkeypatch.setattr(client_module, "create_channel", fake_create_channel)
+    monkeypatch.setattr(client_module.pb_grpc, "MxAccessGatewayStub", lambda channel: object())
+
+    await GatewayClient.connect(
+        endpoint="gateway.example:5001",
+        require_certificate_validation=True,
+    )
+
+    assert captured["options"].require_certificate_validation is True
+
+
+@pytest.mark.asyncio
+async def test_galaxy_connect_forwards_require_certificate_validation(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """GalaxyRepositoryClient.connect must thread the flag too (Client.Python-027)."""
+    captured: dict[str, Any] = {}
+
+    def fake_create_channel(options: ClientOptions) -> object:
+        captured["options"] = options
+        return object()
+
+    monkeypatch.setattr(galaxy_module, "create_channel", fake_create_channel)
+    monkeypatch.setattr(
+        galaxy_module.galaxy_pb_grpc, "GalaxyRepositoryStub", lambda channel: object()
+    )
+
+    await GalaxyRepositoryClient.connect(
+        endpoint="gateway.example:5001",
+        require_certificate_validation=True,
+    )
+
+    assert captured["options"].require_certificate_validation is True
+
+
+@pytest.mark.asyncio
+async def test_gateway_connect_runs_create_channel_off_the_event_loop(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """connect must run the blocking channel factory off the loop (Client.Python-028)."""
+    ran_in_thread: dict[str, bool] = {}
+
+    def fake_create_channel(options: ClientOptions) -> object:
+        # If this runs on the event loop thread, get_running_loop() succeeds.
+        try:
+            asyncio.get_running_loop()
+            ran_in_thread["off_loop"] = False
+        except RuntimeError:
+            ran_in_thread["off_loop"] = True
+        return object()
+
+    monkeypatch.setattr(client_module, "create_channel", fake_create_channel)
+    monkeypatch.setattr(client_module.pb_grpc, "MxAccessGatewayStub", lambda channel: object())
+
+    await GatewayClient.connect(endpoint="gateway.example:5001")
+
+    assert ran_in_thread["off_loop"] is True
+
+
+@pytest.mark.asyncio
+async def test_galaxy_connect_runs_create_channel_off_the_event_loop(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """GalaxyRepositoryClient.connect must also run the probe off the loop (Client.Python-028)."""
+    ran_in_thread: dict[str, bool] = {}
+
+    def fake_create_channel(options: ClientOptions) -> object:
+        try:
+            asyncio.get_running_loop()
+            ran_in_thread["off_loop"] = False
+        except RuntimeError:
+            ran_in_thread["off_loop"] = True
+        return object()
+
+    monkeypatch.setattr(galaxy_module, "create_channel", fake_create_channel)
+    monkeypatch.setattr(
+        galaxy_module.galaxy_pb_grpc, "GalaxyRepositoryStub", lambda channel: object()
+    )
+
+    await GalaxyRepositoryClient.connect(endpoint="gateway.example:5001")
+
+    assert ran_in_thread["off_loop"] is True
+
+
 @pytest.mark.asyncio
 async def test_session_helpers_send_auth_metadata_and_preserve_raw_replies() -> None:
     stub = FakeGatewayStub()

clients/python/tests/test_tls.py

@@ -134,6 +134,17 @@ def test_split_authority_parses_host_and_port() -> None:
     assert _split_authority(":5120") == ("localhost", 5120)
 
 
+def test_split_authority_defaults_port_for_portless_endpoint() -> None:
+    from zb_mom_ww_mxgateway.options import _split_authority
+
+    # A bare hostname (no ":port") must default to 443, not crash on int("mygateway").
+    assert _split_authority("mygateway") == ("mygateway", 443)
+    # Scheme-prefixed bare hostname behaves the same.
+    assert _split_authority("https://mygateway") == ("mygateway", 443)
+    # A non-numeric tail after a colon is treated as no explicit port.
+    assert _split_authority("mygateway:") == ("mygateway", 443)
+
+
 def test_split_authority_strips_ipv6_brackets() -> None:
     from zb_mom_ww_mxgateway.options import _split_authority
 

clients/rust/Cargo.lock

@@ -207,6 +207,22 @@ version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
 
+[[package]]
+name = "core-foundation"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
 [[package]]
 name = "either"
 version = "1.15.0"
@@ -574,7 +590,7 @@ checksum = "1d87ecb2933e8aeadb3e3a02b828fed80a7528047e68b4f424523a0981a3a084"
 
 [[package]]
 name = "mxgw-cli"
-version = "0.1.0"
+version = "0.1.1"
 dependencies = [
  "clap",
  "futures-util",
@@ -597,6 +613,12 @@ version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
 
+[[package]]
+name = "openssl-probe"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe"
+
 [[package]]
 name = "percent-encoding"
 version = "2.3.2"
@@ -796,6 +818,18 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "rustls-native-certs"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "612460d5f7bea540c490b2b6395d8e34a953e52b491accd6c86c8164c5932a63"
+dependencies = [
+ "openssl-probe",
+ "rustls-pki-types",
+ "schannel",
+ "security-framework",
+]
+
 [[package]]
 name = "rustls-pki-types"
 version = "1.14.1"
@@ -816,6 +850,38 @@ dependencies = [
  "untrusted",
 ]
 
+[[package]]
+name = "schannel"
+version = "0.1.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "891d81b926048e76efe18581bf793546b4c0eaf8448d72be8de2bbee5fd166e1"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "security-framework"
+version = "3.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
+dependencies = [
+ "bitflags",
+ "core-foundation",
+ "core-foundation-sys",
+ "libc",
+ "security-framework-sys",
+]
+
+[[package]]
+name = "security-framework-sys"
+version = "2.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
 [[package]]
 name = "semver"
 version = "1.0.28"
@@ -1056,6 +1122,7 @@ dependencies = [
  "percent-encoding",
  "pin-project",
  "prost",
+ "rustls-native-certs",
  "socket2 0.5.10",
  "tokio",
  "tokio-rustls",
@@ -1423,7 +1490,7 @@ dependencies = [
 
 [[package]]
 name = "zb-mom-ww-mxgateway-client"
-version = "0.1.0"
+version = "0.1.1"
 dependencies = [
  "futures-core",
  "futures-util",

clients/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "zb-mom-ww-mxgateway-client"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2021"
 authors = ["Joseph Doherty"]
 description = "Async Rust client for the MxAccessGateway gRPC service, including a lazy-browse walker over the Galaxy Repository hierarchy."
@@ -20,7 +20,7 @@ resolver = "2"
 
 [workspace.package]
 edition = "2021"
-version = "0.1.0"
+version = "0.1.1"
 authors = ["Joseph Doherty"]
 license = "Proprietary"
 repository = "https://gitea.dohertylan.com/dohertj2/mxaccessgw"
@@ -37,7 +37,7 @@ serde_json = "1.0.145"
 thiserror = "2.0.17"
 tokio = { version = "1.48.0", features = ["macros", "rt-multi-thread", "sync", "time"] }
 tokio-stream = { version = "0.1.17", features = ["net"] }
-tonic = { version = "0.13.1", features = ["transport", "tls-ring"] }
+tonic = { version = "0.13.1", features = ["transport", "tls-ring", "tls-native-roots"] }
 tonic-build = "0.13.1"
 
 [dependencies]

clients/rust/README.md

@@ -81,11 +81,19 @@ cargo run -p mxgw-cli -- smoke --endpoint https://mxgateway.example.local:5001 -
 The gateway can auto-generate its own self-signed certificate (it has no PKI).
 Unlike the other clients, the Rust client is **not** lenient: tonic 0.13.1
 exposes no public hook to inject a custom certificate verifier, so TLS over Rust
-is pin-only. A TLS connection requires either `--ca-file` /
-`ClientOptions::with_ca_file(...)` to pin a CA (export the gateway's self-signed
-certificate and pin it), or `--require-certificate-validation` /
-`with_require_certificate_validation(true)` to verify against the system trust
-roots. TLS with neither set fails `connect` with a clear, actionable error rather
+cannot accept an *arbitrary* self-signed certificate. A TLS connection requires
+one of two trust paths:
+
+- `--ca-file` / `ClientOptions::with_ca_file(...)` to pin a CA (export the
+  gateway's self-signed certificate and pin it). This is the path for a
+  self-signed gateway.
+- `--require-certificate-validation` / `with_require_certificate_validation(true)`
+  to verify against the operating system's trust roots (`tls-native-roots`). This
+  only succeeds for a certificate that chains to a root the host already trusts —
+  i.e. a gateway fronted by a publicly- or enterprise-CA-issued certificate, not a
+  bare self-signed one.
+
+TLS with neither set fails `connect` with a clear, actionable error rather
 than accepting the certificate. See
 [Gateway Configuration](../../docs/GatewayConfiguration.md#automatic-self-signed-certificate).
 
@@ -271,5 +279,5 @@ Then add the dependency:
 
 ```toml
 [dependencies]
-zb-mom-ww-mxgateway-client = { version = "0.1.0", registry = "dohertj2-gitea" }
+zb-mom-ww-mxgateway-client = { version = "0.1.1", registry = "dohertj2-gitea" }
 ```

clients/rust/RustClientDesign.md

@@ -162,12 +162,73 @@ impl GatewayClient {
 
 `stream_alarms` opens with one `active_alarm` per currently-active alarm
 (the ConditionRefresh snapshot), then a single `snapshot_complete`, then a
-`transition` for every subsequent raise / acknowledge / clear. The feed 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. `acknowledge_alarm` is idempotent at the
-MxAccess layer; the returned `AcknowledgeAlarmReply` carries the native
-MxStatus from the worker.
+`transition` for every subsequent raise / acknowledge / clear. A fourth
+`provider_status` oneof case (`AlarmProviderStatus`: `mode`, `degraded`,
+`reason`, `since`) is emitted once on stream open and again on every
+failover/failback so late joiners learn the current alarm-provider mode.
+The CLI renders all four cases in both its one-line summary and its
+protobuf-JSON output (`alarm_feed_message_summary` /
+`alarm_feed_message_to_json`). The feed 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.
+`acknowledge_alarm` is idempotent at the MxAccess layer; the returned
+`AcknowledgeAlarmReply` carries the native MxStatus from the worker.
+
+## Galaxy Repository
+
+`GalaxyClient` is a session-less metadata client (requires the
+`metadata:read` API-key scope). Alongside `test_connection`,
+`get_last_deploy_time`, `discover_hierarchy`, and `watch_deploy_events`, it
+exposes a lazy hierarchy walker built on the `BrowseChildren` RPC:
+
+```rust
+impl GalaxyClient {
+    pub async fn browse(&mut self, options: Option<BrowseChildrenOptions>) -> Result<Vec<LazyBrowseNode>, Error>;
+    pub async fn browse_children_raw(&mut self, request: BrowseChildrenRequest) -> Result<BrowseChildrenReply, Error>;
+}
+
+pub struct BrowseChildrenOptions {
+    pub category_ids: Vec<i32>,
+    pub template_chain_contains: Vec<String>,
+    pub tag_name_glob: Option<String>,
+    pub include_attributes: Option<bool>,
+    pub alarm_bearing_only: bool,
+    pub historized_only: bool,
+}
+
+impl LazyBrowseNode {
+    pub fn object(&self) -> &GalaxyObject;
+    pub fn has_children_hint(&self) -> bool;
+    pub async fn children(&self) -> Vec<LazyBrowseNode>;
+    pub async fn is_expanded(&self) -> bool;
+    pub async fn expand(&self) -> Result<(), Error>;
+}
+```
+
+- `browse(options)` returns the root objects as `LazyBrowseNode`s. The
+  supplied `BrowseChildrenOptions` filter is captured and reused when any
+  returned node is expanded, so a single filter set scopes the entire walk.
+- `BrowseChildrenOptions` mirrors the request-level filters on the wire and
+  combines them with **AND**: a child appears only when it satisfies every
+  populated criterion (`category_ids` membership, every
+  `template_chain_contains` substring, the `tag_name_glob`, plus the
+  `alarm_bearing_only` / `historized_only` flags). `include_attributes` is a
+  tri-state (`None` = server default). Empty/`None` fields impose no
+  restriction. See
+  [Galaxy Repository — BrowseChildren](../../docs/GalaxyRepository.md#browsechildren)
+  for the wire-level semantics.
+- `LazyBrowseNode` is cheap to clone — clones share state through an internal
+  `Arc`, so expanding one clone makes the children visible to every clone.
+  `has_children_hint()` exposes the server's `child_has_children` hint so a UI
+  can draw an expand affordance without issuing an RPC. `expand()` is
+  idempotent: the first call issues a paged `BrowseChildren` walk (page size
+  500) under an async mutex held across the await, sets the `is_expanded`
+  flag, and caches the children; subsequent calls are no-ops and re-hit
+  nothing. The internal paged loop guards against a server returning a
+  repeated `next_page_token` by failing with `Error::InvalidArgument` rather
+  than looping forever.
+- `browse_children_raw` issues a single `BrowseChildren` RPC and returns the
+  raw reply for callers that want to drive paging themselves.
 
 ## Authentication
 
@@ -200,13 +261,20 @@ Rust client is therefore **pin-only** — it requires either:
 - `ClientOptions::with_ca_file(...)` to pin a CA (the supported path for the
   gateway's self-signed certificate; export the certificate and pin it), or
 - `ClientOptions::with_require_certificate_validation(true)` to verify against the
-  system trust roots.
+  operating system's trust roots. This enables the `tonic` `tls-native-roots`
+  feature and calls `ClientTlsConfig::with_native_roots()`, so the handshake
+  validates a certificate that chains to a root the host already trusts. It does
+  **not** accept a bare self-signed gateway certificate — that still needs
+  `with_ca_file`.
 
-With TLS enabled (`with_plaintext(false)`), no pinned CA, and certificate
-validation not required, `GatewayClient::connect` rejects the connection with a
-clear, actionable error pointing at `with_ca_file` /
-`require_certificate_validation` rather than silently accepting the certificate.
-The CLI exposes `--ca-file` and `--require-certificate-validation`.
+`build_tls_config` computes the trust posture with the pure `tls_trust_decision`
+helper (`None` / `PinnedCa` / `SystemRoots` / `RejectNoCa`) so the posture is
+unit-testable without a live handshake. With TLS enabled (`with_plaintext(false)`),
+no pinned CA, and certificate validation not required (`RejectNoCa`),
+`GatewayClient::connect` rejects the connection with a clear, actionable error
+pointing at `with_ca_file` / `require_certificate_validation` rather than building
+a config with zero trust anchors. The CLI exposes `--ca-file` and
+`--require-certificate-validation`.
 
 ## Streaming
 

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

@@ -1726,7 +1726,7 @@ fn event_value_to_json(value: &ProtoMxValue) -> Value {
 }
 
 /// Render a streamed [`AlarmFeedMessage`] as a terse one-line summary that
-/// distinguishes the three `payload` oneof cases.
+/// distinguishes the four `payload` oneof cases.
 fn alarm_feed_message_summary(message: &AlarmFeedMessage) -> String {
     match &message.payload {
         Some(alarm_feed_message::Payload::ActiveAlarm(snapshot)) => {
@@ -1746,6 +1746,14 @@ fn alarm_feed_message_summary(message: &AlarmFeedMessage) -> String {
                 AlarmEnumName::transition_kind(transition.transition_kind)
             )
         }
+        Some(alarm_feed_message::Payload::ProviderStatus(status)) => {
+            format!(
+                "provider-status mode={} degraded={} reason={:?}",
+                AlarmEnumName::provider_mode(status.mode),
+                status.degraded,
+                status.reason
+            )
+        }
         None => "(empty)".to_owned(),
     }
 }
@@ -1784,6 +1792,17 @@ fn alarm_feed_message_to_json(message: &AlarmFeedMessage) -> Value {
                 "description": transition.description,
             }
         }),
+        Some(alarm_feed_message::Payload::ProviderStatus(status)) => json!({
+            "providerStatus": {
+                "mode": AlarmEnumName::provider_mode(status.mode),
+                "degraded": status.degraded,
+                "reason": status.reason,
+                "since": status.since.as_ref().map(|ts| json!({
+                    "seconds": ts.seconds,
+                    "nanos": ts.nanos,
+                })),
+            }
+        }),
         None => Value::Null,
     }
 }
@@ -1806,6 +1825,13 @@ impl AlarmEnumName {
             .map(|kind| kind.as_str_name().to_owned())
             .unwrap_or_else(|_| value.to_string())
     }
+
+    fn provider_mode(value: i32) -> String {
+        use zb_mom_ww_mxgateway_client::generated::mxaccess_gateway::v1::AlarmProviderMode;
+        AlarmProviderMode::try_from(value)
+            .map(|mode| mode.as_str_name().to_owned())
+            .unwrap_or_else(|_| value.to_string())
+    }
 }
 
 /// Render an [`AcknowledgeAlarmReply`] as a terse line or a JSON document.
@@ -2165,4 +2191,40 @@ mod tests {
         assert_eq!(frac.seconds, utc.seconds);
         assert_eq!(frac.nanos, 250_000_000);
     }
+
+    #[test]
+    fn alarm_feed_provider_status_renders_in_summary_and_json() {
+        use zb_mom_ww_mxgateway_client::generated::mxaccess_gateway::v1::{
+            alarm_feed_message, AlarmFeedMessage, AlarmProviderMode, AlarmProviderStatus,
+        };
+
+        let message = AlarmFeedMessage {
+            payload: Some(alarm_feed_message::Payload::ProviderStatus(
+                AlarmProviderStatus {
+                    mode: AlarmProviderMode::Subtag as i32,
+                    degraded: true,
+                    reason: "alarmmgr unavailable".to_owned(),
+                    since: Some(prost_types::Timestamp {
+                        seconds: 1_777_995_000,
+                        nanos: 0,
+                    }),
+                },
+            )),
+        };
+
+        let summary = super::alarm_feed_message_summary(&message);
+        assert!(summary.contains("provider-status"), "summary: {summary}");
+        assert!(
+            summary.contains("ALARM_PROVIDER_MODE_SUBTAG"),
+            "summary: {summary}"
+        );
+        assert!(summary.contains("degraded=true"), "summary: {summary}");
+
+        let value = super::alarm_feed_message_to_json(&message);
+        let provider = &value["providerStatus"];
+        assert_eq!(provider["mode"], "ALARM_PROVIDER_MODE_SUBTAG");
+        assert_eq!(provider["degraded"], true);
+        assert_eq!(provider["reason"], "alarmmgr unavailable");
+        assert_eq!(provider["since"]["seconds"], 1_777_995_000_i64);
+    }
 }

clients/rust/src/options.rs

@@ -74,16 +74,22 @@ impl ClientOptions {
     }
 
     /// Require TLS certificate verification even without a pinned CA. Default
-    /// false: the gateway's self-signed certificate is accepted (internal-tool
-    /// posture). Setting a CA file always verifies.
+    /// false. Setting a CA file always verifies against that CA.
     ///
     /// Note for Rust: tonic 0.13's `ClientTlsConfig` exposes no hook for a
-    /// custom rustls verifier, so the Rust client cannot accept an arbitrary
+    /// custom rustls verifier, so the Rust client cannot accept an *arbitrary*
     /// self-signed certificate the way the other clients do. With the default
     /// (false) and no pinned CA, [`crate::client::GatewayClient::connect`]
-    /// rejects the TLS connection and asks for a CA file. Either pin a CA via
-    /// [`ClientOptions::with_ca_file`] (the supported lenient path on Rust) or
-    /// set this `true` to verify against the system trust roots.
+    /// rejects the TLS connection and asks for a CA file. There are two
+    /// supported TLS paths:
+    ///
+    /// - Pin the gateway certificate with [`ClientOptions::with_ca_file`] (the
+    ///   lenient pin-only path; works for a self-signed gateway cert).
+    /// - Set this `true` to verify against the operating system's trust roots
+    ///   (`tls-native-roots`). This only succeeds for a certificate that chains
+    ///   to a root the host already trusts, so it is for gateways fronted by a
+    ///   publicly- or enterprise-CA-issued certificate, not a bare self-signed
+    ///   one.
     pub fn with_require_certificate_validation(mut self, require: bool) -> Self {
         self.require_certificate_validation = require;
         self
@@ -175,26 +181,63 @@ impl ClientOptions {
     }
 }
 
+/// Where the TLS handshake gets its trust anchors for a given set of options.
+/// Computed by [`tls_trust_decision`] and applied by [`build_tls_config`];
+/// split out so the trust posture is unit-testable without a live handshake.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum TlsTrustDecision {
+    /// Plaintext transport — no TLS, no trust anchors.
+    None,
+    /// Validate against the CA pinned with [`ClientOptions::with_ca_file`].
+    PinnedCa,
+    /// Validate against the operating system's trust roots
+    /// (`require_certificate_validation == true`, no pinned CA).
+    SystemRoots,
+    /// Reject up front: TLS requested with neither a pinned CA nor strict
+    /// verification (the Rust pin-only lenient default).
+    RejectNoCa,
+}
+
+/// Decide the TLS trust posture from `options` without touching the filesystem
+/// or the network.
+pub(crate) fn tls_trust_decision(options: &ClientOptions) -> TlsTrustDecision {
+    if options.plaintext() {
+        TlsTrustDecision::None
+    } else if options.ca_file().is_some() {
+        TlsTrustDecision::PinnedCa
+    } else if options.require_certificate_validation() {
+        TlsTrustDecision::SystemRoots
+    } else {
+        TlsTrustDecision::RejectNoCa
+    }
+}
+
 /// Build the [`ClientTlsConfig`] for a non-plaintext connection described by
 /// `options`, applying the lenient-default guard that is the **Rust
 /// pin-only exception**.
 ///
 /// Returns `Ok(None)` when `options.plaintext()` is `true` (no TLS needed).
-/// Returns `Ok(Some(tls))` when a valid TLS config can be assembled.
+/// Returns `Ok(Some(tls))` when a valid TLS config can be assembled — either
+/// pinned to the CA from [`ClientOptions::with_ca_file`], or, when
+/// `require_certificate_validation` is set with no pinned CA, verifying against
+/// the operating system's trust roots (`tls-native-roots`).
 /// Returns `Err(Error::InvalidEndpoint)` when TLS is requested but no pinned
 /// CA was provided and `require_certificate_validation` is `false`.
 ///
-/// # Why this guard exists
+/// # Why the no-CA guard exists
 ///
 /// `tonic` 0.13's `ClientTlsConfig` builds its rustls verifier inside a
 /// crate-private connector and exposes no hook for a custom
-/// `ServerCertVerifier`. The Rust client therefore cannot accept an arbitrary
+/// `ServerCertVerifier`. The Rust client therefore cannot accept an *arbitrary*
 /// self-signed certificate the way the other language clients do. Rather than
-/// silently falling back to system-root verification (which always fails
-/// against a self-signed gateway certificate), we reject the configuration
-/// early with an actionable error.
+/// silently falling back to a verifier with no trust anchors (which rejects
+/// every certificate with a confusing handshake error), the lenient default
+/// rejects the configuration early with an actionable error. The strict opt-in
+/// instead loads the system trust roots so a certificate chaining to an
+/// already-trusted root validates.
 pub(crate) fn build_tls_config(options: &ClientOptions) -> Result<Option<ClientTlsConfig>, Error> {
-    if options.plaintext() {
+    let decision = tls_trust_decision(options);
+    if decision == TlsTrustDecision::None {
         return Ok(None);
     }
 
@@ -202,37 +245,46 @@ pub(crate) fn build_tls_config(options: &ClientOptions) -> Result<Option<ClientT
     if let Some(server_name) = options.server_name_override() {
         tls = tls.domain_name(server_name.to_owned());
     }
-    if let Some(ca_file) = options.ca_file() {
-        let certificate = fs::read(ca_file).map_err(|source| Error::InvalidEndpoint {
-            endpoint: options.endpoint().to_owned(),
-            detail: format!("failed to read CA file {}: {source}", ca_file.display()),
-        })?;
-        tls = tls.ca_certificate(Certificate::from_pem(certificate));
-    } else if !options.require_certificate_validation() {
-        // Lenient-default fallback (Rust pin-only exception): tonic
-        // 0.13's `ClientTlsConfig` builds its rustls verifier inside a
-        // crate-private connector and exposes no hook for a custom
-        // `ServerCertVerifier`, so — unlike the other clients — the
-        // Rust client cannot accept an arbitrary self-signed cert. Pin
-        // the gateway's CA instead, or opt into strict verification
-        // against the system trust roots. We reject here rather than
-        // silently verifying against system roots (which would fail a
-        // self-signed gateway with a confusing handshake error).
-        //
-        // Note: a server-name override affects SNI (the hostname sent
-        // in the TLS ClientHello) but does NOT pin trust. Overriding
-        // the server name alone does not bypass certificate validation.
-        return Err(Error::InvalidEndpoint {
-            endpoint: options.endpoint().to_owned(),
-            detail: "TLS requested without a pinned CA. The Rust client cannot accept an \
-                     arbitrary self-signed certificate (tonic 0.13 exposes no custom \
-                     rustls verifier). Pin the gateway certificate with \
-                     ClientOptions::with_ca_file, or call \
-                     ClientOptions::with_require_certificate_validation(true) to verify \
-                     against the system trust roots. Note: a server-name override \
-                     affects SNI but does not pin trust."
-                .to_owned(),
-        });
+    match decision {
+        TlsTrustDecision::PinnedCa => {
+            let ca_file = options.ca_file().expect("PinnedCa implies a CA file");
+            let certificate = fs::read(ca_file).map_err(|source| Error::InvalidEndpoint {
+                endpoint: options.endpoint().to_owned(),
+                detail: format!("failed to read CA file {}: {source}", ca_file.display()),
+            })?;
+            tls = tls.ca_certificate(Certificate::from_pem(certificate));
+        }
+        TlsTrustDecision::SystemRoots => {
+            // Strict opt-in with no pinned CA: verify against the OS trust
+            // store. Without this the bare `ClientTlsConfig` carries zero
+            // trust anchors and rejects every certificate, so the documented
+            // "verify against the system trust roots" behaviour would be
+            // unreachable. Only a certificate chaining to an already-trusted
+            // root validates — a bare self-signed gateway cert still needs
+            // `with_ca_file`.
+            tls = tls.with_native_roots();
+        }
+        TlsTrustDecision::RejectNoCa => {
+            // Lenient-default fallback (Rust pin-only exception): the Rust
+            // client cannot accept an arbitrary self-signed cert. Pin the
+            // gateway's CA, or opt into strict verification against the
+            // system trust roots.
+            //
+            // Note: a server-name override affects SNI (the hostname sent in
+            // the TLS ClientHello) but does NOT pin trust.
+            return Err(Error::InvalidEndpoint {
+                endpoint: options.endpoint().to_owned(),
+                detail: "TLS requested without a pinned CA. The Rust client cannot accept an \
+                         arbitrary self-signed certificate (tonic 0.13 exposes no custom \
+                         rustls verifier). Pin the gateway certificate with \
+                         ClientOptions::with_ca_file, or call \
+                         ClientOptions::with_require_certificate_validation(true) to verify \
+                         against the system trust roots. Note: a server-name override \
+                         affects SNI but does not pin trust."
+                    .to_owned(),
+            });
+        }
+        TlsTrustDecision::None => unreachable!("handled above"),
     }
     Ok(Some(tls))
 }
@@ -269,6 +321,8 @@ mod tests {
     use super::ClientOptions;
     use crate::auth::ApiKey;
 
+    use super::{build_tls_config, tls_trust_decision, TlsTrustDecision};
+
     #[test]
     fn debug_redacts_api_key() {
         let options =
@@ -279,4 +333,47 @@ mod tests {
         assert!(debug.contains("<redacted>"));
         assert!(!debug.contains("mxgw_secret"));
     }
+
+    #[test]
+    fn plaintext_needs_no_tls() {
+        let options = ClientOptions::new("http://127.0.0.1:5000").with_plaintext(true);
+        assert_eq!(tls_trust_decision(&options), TlsTrustDecision::None);
+        assert!(build_tls_config(&options).unwrap().is_none());
+    }
+
+    #[test]
+    fn pinned_ca_uses_pinned_trust() {
+        let options = ClientOptions::new("https://127.0.0.1:5000")
+            .with_plaintext(false)
+            .with_ca_file("/some/ca.pem");
+        assert_eq!(tls_trust_decision(&options), TlsTrustDecision::PinnedCa);
+    }
+
+    #[test]
+    fn strict_without_ca_uses_system_roots() {
+        // Regression for Client.Rust-031: strict verification with no pinned CA
+        // must verify against the system trust roots, not produce a config with
+        // zero trust anchors. The trust decision proves roots are consulted; the
+        // build then succeeds (no no-CA guard error) and emits a config.
+        let options = ClientOptions::new("https://127.0.0.1:5000")
+            .with_plaintext(false)
+            .with_require_certificate_validation(true);
+
+        assert_eq!(
+            tls_trust_decision(&options),
+            TlsTrustDecision::SystemRoots,
+            "strict-no-CA must request the system trust roots"
+        );
+        assert!(
+            build_tls_config(&options).unwrap().is_some(),
+            "strict-no-CA must build a usable TLS config"
+        );
+    }
+
+    #[test]
+    fn lenient_without_ca_is_rejected() {
+        let options = ClientOptions::new("https://127.0.0.1:5000").with_plaintext(false);
+        assert_eq!(tls_trust_decision(&options), TlsTrustDecision::RejectNoCa);
+        assert!(build_tls_config(&options).is_err());
+    }
 }

code-reviews/Client.Dotnet/findings.md

@@ -4,8 +4,8 @@
 |---|---|
 | Module | `clients/dotnet` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |
 
@@ -383,6 +383,40 @@ Re-review pass at `42b0037`. Diff against `d692232` consists of four commits:
 | 9 | Testing coverage | No new issues — `RunAsync_StreamAlarms_*`, `RunAsync_AcknowledgeAlarm_*`, and `RunAsync_Batch_*` give the new surface unit coverage. `bench-read-bulk` is the same stress-harness-not-SDK shape called out in the prior re-review and is not flagged here. |
 | 10 | Documentation & comments | Issue found (this review): the README examples for the two new alarm CLI subcommands cite wrong flag names and a non-existent `--session-id` (Client.Dotnet-018). The new XML docs on `StreamAlarmsAsync` / `AcknowledgeAlarmAsync` and on the bulk SDK methods are accurate and complete. |
 
+#### 2026-06-15 re-review (commit 410acc9)
+
+Re-review pass at `410acc9`. The diff against `42b0037` is packaging/release metadata
+(NuGet/Gitea feed), a TLS trust-posture option (`RequireCertificateValidation` + a
+lenient accept-all default for the gateway's auto-generated self-signed cert), the
+Galaxy `BrowseChildren` RPC plumbing plus a `LazyBrowseNode` lazy-browse walker, and
+in-source resolutions of the prior pass's Client.Dotnet-018..021 (CLI flag-name README
+fix, `RequireRegisterServerHandle`, `ParseTimeoutMs` negative guard, steady-state OCE
+filter). The alarm-provider-fallback proto surface mentioned in the review brief is
+**not** present in this diff — no `AlarmProviderMode` / `AlarmProviderStatus` /
+`source_provider` / provider-mode-changed event reaches the .NET client here.
+
+Build is green (`dotnet build … .slnx` succeeds) and all 78 unit tests pass (1 skipped
+live smoke). The build now emits **10 CS1591 warnings** that do not break the build,
+because the `clients/dotnet/Directory.Build.props` enforcement floor recorded as
+resolved under Client.Dotnet-012 (`TreatWarningsAsErrors` / `EnforceCodeStyleInBuild` /
+`AnalysisLevel` / `Deterministic`) is **absent** from the history that reaches HEAD —
+the props file at HEAD is packaging-metadata-only (Client.Dotnet-022). `git merge-base
+--is-ancestor a020350 HEAD` is false: the 2026-05-20 review-sweep commit that resolved
+012 is not in this line of history.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | No new issues. The Galaxy `BrowseAsync` / `LazyBrowseNode.ExpandAsync` pagination correctly drains `next_page_token`, re-binds the same parent selector + filter set per page (matching the opaque-token contract), and guards against repeated tokens; the per-child `child_has_children` hint is read with an index-bounds check. The Client.Dotnet-019/021 in-source fixes (`RequireRegisterServerHandle`, `ParseTimeoutMs`) are correctly applied. |
+| 2 | mxaccessgw conventions | Issue found (this review): the `clients/dotnet/Directory.Build.props` enforcement floor (warnings-as-errors / code-style enforcement) mandated by CLAUDE.md and recorded resolved under Client.Dotnet-012 is missing at HEAD; the new props file carries only packaging metadata (Client.Dotnet-022). Consumes the shared contracts project, no forked proto, `authorization: Bearer` metadata correct. |
+| 3 | Concurrency & thread safety | Issue found (this review): `LazyBrowseNode.Children` and `IsExpanded` are read lock-free while `ExpandAsync` mutates `_children` and writes `_isExpanded` under `_expandLock`, with no release/acquire barrier to a concurrent reader (Client.Dotnet-025). `ExpandAsync`'s one-RPC dedup itself is correct (double-checked under the lock). |
+| 4 | Error handling & resilience | No new issues — `BrowseChildrenAsync` routes `RpcException` through the shared `MapRpcException`; the bench steady-state OCE filter (Client.Dotnet-020) is correctly applied. |
+| 5 | Security | No committed secret — the README Gitea-feed `dotnet nuget add source` example uses `<gitea-username>` / `<gitea-token-or-password>` placeholders. Note: TLS is lenient-by-default (accept-all callback when `UseTls` and no pinned CA), which disables certificate verification / MITM protection; this is an explicit, documented design choice for the gateway's auto-generated self-signed cert and is opt-out via `RequireCertificateValidation` or CA pinning, so not flagged as a finding. |
+| 6 | Performance & resource management | No issues found — `LazyBrowseNode` holds one `SemaphoreSlim` per node (never disposed, but it owns no unmanaged handle and the node lifetime is the tree's); browse paging caps at 500/page. |
+| 7 | Design-document adherence | No issues found — `BrowseChildren` / lazy-browse match `docs/GalaxyRepository.md#browsechildren`; the TLS posture matches `docs/GatewayConfiguration.md` (`RequireCertificateValidation` default `false`) and `DotnetClientDesign.md`. |
+| 8 | Code organization & conventions | Issue found (this review): Client.Dotnet-022 (lost enforcement props); the new `GenerateDocumentationFile=true` in the shared props also applies to the Cli and Tests projects, surfacing CS1591 on `IMxGatewayCliClient` and every test class (Client.Dotnet-023); the client (and Contracts) NuGet package ships with no `<license>` metadata despite setting `PackageRequireLicenseAcceptance=false` (Client.Dotnet-024). The nuspec correctly emits the transitive `ZB.MOM.WW.MxGateway.Contracts 0.1.0` dependency, so the README "pulled in transitively" claim holds. |
+| 9 | Testing coverage | No new issues — `LazyBrowseNodeTests` (7 cases incl. multi-page, concurrent-expand-one-RPC, filter forwarding), `MxGatewayClientTlsHandlerTests` / `GalaxyRepositoryClientTlsHandlerTests`, and the README-example parse tests give the new surface good coverage. |
+| 10 | Documentation & comments | No new issues — README NuGet-install / lazy-browse / TLS-trust sections are accurate, cross-doc anchors (`#automatic-self-signed-certificate`, `#browsechildren`) resolve, and the new XML docs on `BrowseAsync` / `LazyBrowseNode` / `RequireCertificateValidation` are complete. (The CS1591-surfaced missing docs are tracked under Client.Dotnet-023.) |
+
 ### Client.Dotnet-018
 
 | Field | Value |
@@ -507,3 +541,65 @@ uint timeoutMs = (uint)timeoutMsRaw;
 A single shared helper (e.g. `ParseTimeoutMs(CliArguments, string, int)`) on `MxGatewayClientCli` would cover both call sites and remove the duplication.
 
 **Resolution:** 2026-05-24 — Confirmed against source: both `ReadBulkAsync` (line 490) and `BenchReadBulkAsync` (line 715) cast `arguments.GetInt32("timeout-ms", ...)` straight to `uint`, so `--timeout-ms -1` silently wrapped to `0xFFFFFFFF` (~49.7 days). Added a single shared private helper `ParseTimeoutMs(CliArguments arguments, int defaultValue)` on `MxGatewayClientCli` that reads the int32, rejects negatives with a clear `ArgumentException` ("--timeout-ms must be a non-negative integer (use 0 for the gateway default)."), and returns the safe `(uint)`. Both call sites now route through the helper. Regression test `MxGatewayClientCliTests.RunAsync_TimeoutMs_NegativeValue_RejectsWithClearError` (xUnit `[Theory]` over `read-bulk` and `bench-read-bulk`) drives the CLI with `--timeout-ms -1` and asserts the exit code is non-zero, that stderr contains "timeout-ms", and that the "non-negative" guard text is present. Verified red against the original `(uint)arguments.GetInt32(...)` casts (the bench proceeded past the timeout parse and tripped a downstream "Queue empty" error rather than the descriptive guard message) and green after the helper landed.
+
+### Client.Dotnet-022
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | mxaccessgw conventions |
+| Location | `clients/dotnet/Directory.Build.props:1-21` |
+| Status | Resolved |
+
+**Description:** Client.Dotnet-012 was recorded resolved (2026-05-20, commit `a020350`) by adding `clients/dotnet/Directory.Build.props` mirroring `src/Directory.Build.props` — `TreatWarningsAsErrors=true`, `EnforceCodeStyleInBuild=true`, `AnalysisLevel=latest`, `Deterministic=true`, `LangVersion=latest`, `Nullable=enable`, `ImplicitUsings=enable` — to restore the build-quality floor that `CLAUDE.md` calls a baseline for the .NET client. That enforcement props file is **not present in the line of history that reaches HEAD**: `git merge-base --is-ancestor a020350 HEAD` is false (the 2026-05-20 review-sweep commit was dropped during the `ZB.MOM.WW` rename / history rebuild). At `42b0037` the file did not exist at all (`git show 42b0037:clients/dotnet/Directory.Build.props` fails), and at HEAD commit `523f944` introduced a **new** `clients/dotnet/Directory.Build.props` that carries only NuGet packaging metadata (Authors/Company/RepositoryUrl/Version/etc.) — none of the enforcement properties. None of the three client `.csproj` files set `TreatWarningsAsErrors` or `EnforceCodeStyleInBuild` independently (they set only `TargetFramework` and `Nullable`).
+
+Net effect at HEAD: `dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx` **succeeds with 10 CS1591 warnings** instead of failing. The mandated quality gate that would turn new warnings (missing docs, analyzer findings, code-style violations) into build breaks is gone for the entire client tree. This is a regression of the previously-closed Client.Dotnet-012; recorded as a fresh finding at the new commit per the re-review process.
+
+**Recommendation:** Restore the enforcement properties in `clients/dotnet/Directory.Build.props` alongside the packaging metadata (they can coexist in the same `<Project>`), or add a sibling `clients/dotnet/Directory.Build.props` import. Re-run `dotnet build …slnx` and confirm 0 warnings / 0 errors (which will require closing Client.Dotnet-023 too, since the CS1591 warnings would otherwise become errors). Add a guard so the floor is not silently dropped again — e.g. assert the property is set in a small build test or CI check.
+
+**Resolution:** 2026-06-15 — Confirmed at HEAD: `clients/dotnet/Directory.Build.props` carried only packaging metadata; none of the three client `.csproj` files set the enforcement properties, so `dotnet build …slnx` succeeded with 10 CS1591 warnings instead of failing. Restored the enforcement floor in `clients/dotnet/Directory.Build.props` mirroring `src/Directory.Build.props` (`LangVersion=latest`, `Nullable=enable`, `ImplicitUsings=enable`, `TreatWarningsAsErrors=true`, `AnalysisLevel=latest`, `EnforceCodeStyleInBuild=true`, `Deterministic=true`) in a second `<PropertyGroup>` alongside the existing packaging metadata. Resolved jointly with Client.Dotnet-023 (the CS1591 warnings would otherwise become errors under the restored `TreatWarningsAsErrors`). `dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx -t:Rebuild` now reports 0 Warning(s) / 0 Error(s).
+
+### Client.Dotnet-023
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `clients/dotnet/Directory.Build.props:17`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/IMxGatewayCliClient.cs:6`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/*.cs` |
+| Status | Resolved |
+
+**Description:** The new shared `clients/dotnet/Directory.Build.props` sets `GenerateDocumentationFile=true` at the directory level, so it applies to all three projects — including `ZB.MOM.WW.MxGateway.Client.Cli` and `ZB.MOM.WW.MxGateway.Client.Tests`, which are not packable and were not previously generating an XML doc file. Turning it on surfaces 10 CS1591 "missing XML comment" warnings: `IMxGatewayCliClient` (the public CLI interface, never documented at the type level — note Client.Dotnet-013's resolution claimed a type-level summary was added, but it is absent in the history reaching HEAD for the same reason as Client.Dotnet-022) plus every public xUnit test class (`GalaxyRepositoryClientTests`, `MxGatewayClientTlsHandlerTests`, `GalaxyRepositoryClientTlsHandlerTests`, and seven others). Today these are only warnings because the enforcement floor is missing (Client.Dotnet-022); once that floor is restored they become build-breaking errors.
+
+**Recommendation:** Scope `GenerateDocumentationFile=true` to the packable library project only (move it from the shared props into `ZB.MOM.WW.MxGateway.Client.csproj`, which is the only project that ships a `.nupkg`), or keep it directory-wide but suppress CS1591 on the non-public test/CLI assemblies (`<NoWarn>$(NoWarn);CS1591</NoWarn>` in those two `.csproj` files) and add the one-line type summary to `IMxGatewayCliClient`. The first option is cleaner and avoids documenting test classes.
+
+**Resolution:** 2026-06-15 — Confirmed via `-t:Rebuild`: the directory-wide `GenerateDocumentationFile=true` surfaced exactly 10 CS1591 warnings — `IMxGatewayCliClient` plus nine xUnit test classes (`GalaxyRepositoryClientTests`, `MxCommandReplyExtensionsTests`, `MxGatewayClientContractInfoTests`, `MxGatewayClientOptionsTests`, `MxGatewayClientTlsHandlerTests`, `GalaxyRepositoryClientTlsHandlerTests`, `MxGatewayGeneratedContractTests`, `MxStatusProxyExtensionsTests`, `MxValueExtensionsTests`); the shipped Client library itself emitted zero (its public surface was already fully documented). Took the first (cleaner) option, matching how `src/` handles this — only the packable `src/ZB.MOM.WW.MxGateway.Contracts.csproj` sets `GenerateDocumentationFile` directly. Removed `GenerateDocumentationFile=true` from the shared `clients/dotnet/Directory.Build.props` and moved it into the packable `ZB.MOM.WW.MxGateway.Client.csproj` only, so the Cli and Tests projects no longer generate doc files and CS1591 is not raised against them. No doc comments were added to test classes. With the Client.Dotnet-022 floor restored, the rebuild is clean (0 warnings / 0 errors).
+
+### Client.Dotnet-024
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `clients/dotnet/Directory.Build.props:12`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client/ZB.MOM.WW.MxGateway.Client.csproj:19-24` |
+| Status | Resolved |
+
+**Description:** The client package sets `PackageRequireLicenseAcceptance=false` but declares **no license at all** — there is no `PackageLicenseExpression` and no `PackageLicenseFile` in `clients/dotnet/Directory.Build.props` or in the packable `.csproj`. Confirmed by packing: the emitted `ZB.MOM.WW.MxGateway.Client.0.1.0.nuspec` has no `<license>` element, so the produced package carries no license metadata and a NuGet feed renders it as "License: not specified." The sibling `ZB.MOM.WW.MxGateway.Contracts` package (the transitive dependency) has the same gap. `dotnet pack` does not warn (a missing license is allowed), so the omission is silent. Setting `PackageRequireLicenseAcceptance=false` while shipping no license is internally inconsistent — that flag exists to control acceptance of a license that should be present.
+
+**Recommendation:** Add the intended license to `clients/dotnet/Directory.Build.props` (and to `ZB.MOM.WW.MxGateway.Contracts.csproj` for parity) — either `<PackageLicenseExpression>` with an SPDX id (e.g. a proprietary marker or the actual license) or `<PackageLicenseFile>` pointing at a committed `LICENSE`. If the package is intentionally unlicensed/internal-only, document that explicitly rather than leaving the field blank.
+
+**Resolution:** 2026-06-15 — Confirmed via pack: the emitted nuspec had no `<license>` element. Marked the package "Proprietary" consistent with the other clients' decision (Rust `license = "Proprietary"`, Python `license = { text = "Proprietary" }` + `License :: Other/Proprietary License`). A `<PackageLicenseExpression>LicenseRef-Proprietary</PackageLicenseExpression>` was tried first but the current NuGet toolset rejects `LicenseRef-*` (NU5124), which the restored `TreatWarningsAsErrors` escalates to a pack failure — so the proprietary terms ship as a committed license file instead: added `clients/dotnet/LICENSE.txt` (proprietary/internal-use terms), set `<PackageLicenseFile>LICENSE.txt</PackageLicenseFile>` in the shared `clients/dotnet/Directory.Build.props`, and packed it at the package root via a `<None Include="..\LICENSE.txt" Pack="true" PackagePath="\" />` item in the packable `ZB.MOM.WW.MxGateway.Client.csproj`. `dotnet pack` now succeeds and the nuspec carries `<license type="file">LICENSE.txt</license>` with `LICENSE.txt` present in the `.nupkg`. Scope was limited to Client.Dotnet per the constraints — the sibling `ZB.MOM.WW.MxGateway.Contracts` package has the same gap and is NOT touched here (it is a different module; flagging it for that module's review).
+
+### Client.Dotnet-025
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Concurrency & thread safety |
+| Location | `clients/dotnet/ZB.MOM.WW.MxGateway.Client/LazyBrowseNode.cs:38,41,54,82,94` |
+| Status | Resolved |
+
+**Description:** `LazyBrowseNode.ExpandAsync` is explicitly documented as thread-safe ("concurrent callers see exactly one fetch"), and its one-RPC dedup is correct: it double-checks `_isExpanded` under `_expandLock`. But the *readers* of the results are lock-free. `Children => _children` returns the live backing `List<LazyBrowseNode>` reference, and `IsExpanded => _isExpanded` reads the plain `bool` field — neither takes `_expandLock` nor uses `Volatile`. A thread that observes `IsExpanded == true` (or simply enumerates `Children`) concurrently with the writer thread inside `ExpandAsync` has no release/acquire barrier guaranteeing it sees the fully-populated `_children` contents that were appended under the lock. On x86/x64 the bool read and the list-reference read are atomic and the practical risk is low, but the published-state visibility is not guaranteed by the memory model, and a reader enumerating `Children` while a concurrent `ExpandAsync` is mid-append can throw `InvalidOperationException` ("collection was modified"). This is inconsistent with the type's own thread-safety claim.
+
+**Recommendation:** Either (a) tighten the documented contract to "ExpandAsync is safe to call concurrently, but Children/IsExpanded must only be read after the awaited ExpandAsync completes (no concurrent reader/expander)", or (b) make the publication safe: write `_isExpanded` via `Volatile.Write` and read via `Volatile.Read`, and return an immutable snapshot from `Children` (e.g. assign a completed `IReadOnlyList` under the lock and expose that field) so lock-free readers never observe a partially-populated list. Option (a) is the smallest change and matches the realistic usage (UI thread expands then renders).
+
+**Resolution:** 2026-06-15 — Confirmed against source: `Children => _children` returned the live mutable backing `List<LazyBrowseNode>` and `IsExpanded => _isExpanded` read a plain `bool`, while `ExpandAsync` appended to that same list under `_expandLock` with no release/acquire barrier to lock-free readers — so a concurrent reader could enumerate a mid-append list and throw `InvalidOperationException` ("collection was modified"). Applied option (b) (safe publication): `ExpandAsync` now accumulates children into a method-local `List<LazyBrowseNode>` and, only when fully drained across all pages, publishes it via `Volatile.Write(ref _children, children)` (release) immediately before setting the now-`volatile bool _isExpanded = true`. The `_children` field is an `IReadOnlyList<LazyBrowseNode>` read via `Volatile.Read` from the `Children` getter (acquire), so a reader that observes `IsExpanded == true` always sees the fully-populated snapshot and never enumerates a partially-built list. Updated the `ExpandAsync` `<remarks>` to document the strengthened concurrent-read guarantee. Regression test `LazyBrowseNodeTests.Expand_ConcurrentReadOfChildren_NeverTearsAndPublishesAtomically` gates the child-page RPCs (via a new `FakeGalaxyRepositoryTransport.BrowseChildrenGate` hook) to hold the expand mid-flight while a background reader spins enumerating `Children` and reading `IsExpanded`, asserting no exception escapes and that once `IsExpanded` is true the published snapshot has all five children. Verified red against the pre-fix code (the reader threw `InvalidOperationException: Collection was modified` deterministically across three runs) and green after the fix.

code-reviews/Client.Go/findings.md

@@ -4,8 +4,8 @@
 |---|---|
 | Module | `clients/go` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |
 
@@ -83,6 +83,39 @@ that earlier commit.
 | 9 | Testing coverage | New issue: the five new bulk SDK methods and `Client.StreamAlarms` have no unit tests in `mxgateway/` (Client.Go-024). |
 | 10 | Documentation & comments | No issues found in this diff. README documents the new `StreamAlarms`/`AcknowledgeAlarm` SDK calls; `Session.ReadBulk` documents the cached-vs-snapshot semantics and `timeout=0` default; `WriteSecuredBulk` flags credential sensitivity. |
 
+### 2026-06-15 re-review (commit 410acc9)
+
+Re-review pass at `410acc9`. The diff is larger than the brief suggested:
+`82996aa` resolved Client.Go-022..027 (already closed). On top of that,
+`fd2a0ac`/`4a19854`/`da3aa7b`/`92cc468`/`75610e3` added a `LazyBrowseNode`
+lazy-hierarchy walker (`Browse`/`Expand`/`BrowseChildrenRaw`) over the new
+`BrowseChildren` RPC and paginated `DiscoverHierarchy`; `c463b49`/`2eb8137`/
+`9bdb899` made the TLS path lenient-by-default (accept the gateway's
+self-signed cert unless `RequireCertificateValidation` or `CACertFile` is set);
+`6df373a` added the release docs + `scripts/tag-go-module.ps1`. `gofmt -l .`,
+`go vet ./...`, `go build ./...`, and `go test ./...` are all clean at HEAD.
+
+Two new low/medium issues in the release-helper and install docs. The
+lenient-TLS default is an intentional, documented project posture
+(`docs/GatewayConfiguration.md` "clients are lenient" to pair with the
+auto-generated self-signed cert) and the `//nolint:gosec` is correctly
+justified — not a finding. The `LazyBrowseNode` concurrency model
+(coalesced in-flight Expand, non-sticky failures, snapshot copies under
+`RWMutex`) is sound and well-tested, including a 10-goroutine race test.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | New issue: `tag-go-module.ps1`'s clean-tree guard is order-dependent and silently permits tagging with uncommitted tracked changes when an untracked path sorts first (Client.Go-028). `DiscoverHierarchy`/`browseChildrenInner` pagination, the `child_has_children` hint mapping, and the duplicate-page-token guard are all correct. |
+| 2 | mxaccessgw conventions | No issues found. `gofmt -l .` / `go vet ./...` clean; the `//nolint:gosec` on `InsecureSkipVerify` carries a narrow justified reason per the suppression convention. |
+| 3 | Concurrency & thread safety | No issues found — `LazyBrowseNode.Expand` runs the RPC outside both locks, coalesces concurrent callers onto one in-flight RPC, publishes the result before `close(done)`, and leaves failures retryable; verified by `TestGalaxyBrowseExpandConcurrentCallersOnlyFireOneRpc` (`-race`-shaped). |
+| 4 | Error handling & resilience | No issues found — `BrowseChildrenRaw` wraps transport failures in `*GatewayError`; both paginating loops guard against a repeated page token. |
+| 5 | Security | No issues found — no committed secrets (only `"test"` / `"test-api-key"` fixtures); the lenient-TLS default is the documented project posture with an opt-in strict mode (`RequireCertificateValidation`). |
+| 6 | Performance & resource management | No issues found — `DiscoverHierarchy` cancels each page's call context promptly inside the loop; `Children()` returns a defensive copy. |
+| 7 | Design-document adherence | No issues found — lazy browse matches `docs/GalaxyRepository.md#browsechildren`; lenient TLS matches `docs/GatewayConfiguration.md`. |
+| 8 | Code organization & conventions | No issues found — additive API (`Browse`/`BrowseChildrenOptions`/`RequireCertificateValidation`); `tlsConfigForOptions` cleanly extracted for testability. |
+| 9 | Testing coverage | No issues found — new walker, pagination, dup-token, filter-forwarding, and TLS-posture paths are all covered. |
+| 10 | Documentation & comments | New issue: README "Installing the Go client" recommends the `GONOSUMCHECK` env var, which was removed from the Go toolchain in 1.13 and is a no-op on Go 1.26 (Client.Go-029). |
+
 ## Findings
 
 ### Client.Go-001
@@ -625,3 +658,51 @@ The two cases the empty-line check seems to cover — (a) operator pressing Ente
 **Recommendation:** Change `if line == "" { break }` to `if line == "" { continue }` (alongside the existing `len(args) == 0` continue, which is then redundant — keep one, drop the other for clarity). Update the `runBatch` doc-comment to read "only stdin EOF ends the session" and drop the "or an empty line" clause. If the interactive ergonomic is genuinely wanted, gate it on `isatty(stdin)` so the batch-from-pipe case isn't affected.
 
 **Resolution:** 2026-05-24 — `runBatch` no longer treats a blank line as end-of-session. The `if line == "" { break }` early-exit was removed; blank or whitespace-only lines now fall through the existing `if len(args) == 0 { continue }` guard (kept as the single blank-line skip rule for clarity), so only stdin EOF ends the session. The doc-comment was updated to read "Blank lines are skipped; only stdin EOF ends the session." Regression test `TestRunBatchSkipsBlankLinesAndContinuesUntilEOF` in `cmd/mxgw-go/main_test.go` feeds `version --json\n\nversion --json\n` (a stray blank line between two commands) and asserts two EOR sentinels are emitted — pre-fix the test failed with "EOR sentinel count = 1, want 2" because the blank line broke the loop and the second command never ran; post-fix both commands run.
+
+### Client.Go-028
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Correctness & logic bugs |
+| Location | `scripts/tag-go-module.ps1:42-46` |
+| Status | Resolved |
+
+**Description:** The release helper's clean-working-tree guard is order-dependent and can silently let a release tag be created on top of uncommitted tracked changes — the exact thing it advertises it prevents (the README at `clients/go/README.md` says "The script ... refuses to tag with uncommitted tracked changes"). The check is:
+
+```powershell
+$status = (git status --porcelain) -join "`n"
+if ($status -and -not ($status -match '^\?\?')) {
+    throw "Working tree has tracked changes. Commit or stash before tagging."
+}
+```
+
+`git status --porcelain` emits one line per path (`XY path`), with untracked entries prefixed `??`. The lines are joined into a single string and matched against `'^\?\?'` with PowerShell `-match`, which by default is single-line (no `(?m)` multiline flag), so `^` anchors to the start of the *whole* joined string. The guard therefore inspects only the **first** status line: if that first line is an untracked file (`??`), the `-not (... -match '^\?\?')` clause is false and the throw is skipped — even when later lines are tracked modifications (` M file.go`, `A  file.go`, etc.). Because `git status --porcelain` orders entries by pathname, an untracked file whose name sorts ahead of a modified tracked file (e.g. an untracked `AAA-notes.md` alongside a modified `mxgateway/session.go`) puts the `??` line first and the tag is created from a dirty tree. This was confirmed empirically: with `"?? untracked.md\n M tracked.go"` the script allows the tag; with the tracked line first it correctly throws. The whole point of the guard — reproducible release tags that match a committed state — is defeated in this ordering.
+
+**Recommendation:** Test each status entry individually rather than the first line of a joined blob. For example, iterate the porcelain lines and throw if any line does **not** start with `??`:
+
+```powershell
+$dirty = (git status --porcelain) | Where-Object { $_ -and ($_ -notmatch '^\?\?') }
+if ($dirty) {
+    throw "Working tree has tracked changes. Commit or stash before tagging.`n$($dirty -join "`n")"
+}
+```
+
+(Equivalently, keep the joined string but use the multiline flag and negate per-line: `($status -split "`n") | ? { $_ -notmatch '^\?\?' }`.) Including the offending lines in the thrown message also helps the operator see what is dirty.
+
+**Resolution:** 2026-06-15 — Replaced the order-dependent joined-blob check in `tag-go-module.ps1` with a per-line filter (`git status --porcelain | Where-Object { $_ -and ($_ -notmatch '^\?\?') }`) that throws on any tracked change regardless of ordering, listing the offending lines. Verified under pwsh 7.5.4 that an untracked path sorting ahead of a modified tracked file is now correctly rejected, while untracked-only and clean trees are still allowed.
+
+### Client.Go-029
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `clients/go/README.md:300-303` |
+| Status | Resolved |
+
+**Description:** The "Installing the Go client" section advises, for build environments that cannot reach `gitea.dohertylan.com` directly, to "use `GONOSUMCHECK` + `GOPRIVATE` to bypass the checksum database for the internal module path." `GONOSUMCHECK` is a dead environment variable — it was removed from the Go toolchain in Go 1.13 (its short-lived successor `GONOSUMDB` was also removed), and on the Go 1.26 toolchain this client targets (`go.mod` says `go 1.26`) setting it has no effect. The actual mechanism is `GOPRIVATE` (or the finer-grained `GONOSUMCHECK`-replacement `GONOSUMDB`→now `GONOSUMCHECK` is gone) — `GOPRIVATE=gitea.dohertylan.com/*` alone already both skips the checksum database and bypasses the public proxy for matching module paths, so the `GONOSUMCHECK` half of the recommendation is inert and misleading. A reader who copies the advice and finds checksum-db verification still failing has no working escape hatch from this doc.
+
+**Recommendation:** Drop `GONOSUMCHECK` and document the current knobs: set `GOPRIVATE=gitea.dohertylan.com/*` (covers both sum-db bypass and direct VCS fetch), or for the checksum database specifically `GONOSUMCHECK`'s modern equivalent `GONOSUMDB` is also gone — use `GONOSUMCHECK`→`GOFLAGS=-insecure` only for plaintext, and `GONOSUMCHECK`. Concretely: "set `GOPRIVATE=gitea.dohertylan.com/*` (this disables both the checksum database and the public module proxy for that path); add `GOINSECURE=gitea.dohertylan.com/*` if the host serves the module over plain HTTP."
+
+**Resolution:** 2026-06-15 — Dropped the dead `GONOSUMCHECK` advice from the "Installing the Go client" section of `clients/go/README.md`; it now documents `GOPRIVATE=gitea.dohertylan.com/*` (which bypasses both the public module proxy and checksum-database verification for that path) plus `GOINSECURE=gitea.dohertylan.com/*` for plain-HTTP hosts.

code-reviews/Client.Java/findings.md

@@ -4,8 +4,8 @@
 |---|---|
 | Module | `clients/java` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |
 
@@ -77,6 +77,35 @@ Client.Java-001..031 are unchanged.
 | 9 | Testing coverage | Issue found: the new `MxGatewayClient.streamAlarms` SDK method has no library-side test in `zb-mom-ww-mxgateway-client/src/test/...` — only the CLI test exercises the path via a `FakeClient.streamAlarms` override that bypasses the production `subscription.wrap(observer)` glue (Client.Java-035). |
 | 10 | Documentation & comments | Issue found: README (`clients/java/README.md:182-183`) documents the new `stream-alarms` and `acknowledge-alarm` commands with `--session-id <id>` (neither command has that option) and `acknowledge-alarm --alarm-reference …` (actual flag is `--reference`) — every documented invocation fails at picocli parse time (Client.Java-032). |
 
+### 2026-06-15 re-review (commit 410acc9)
+
+Re-review pass at `410acc9`. Diff against `42b0037` is eleven commits touching
+`clients/java`: `d3cb311` (Client.Java-032..036 fixes — shared subscription
+base + batch tokenizer), `0d6193c`/`803a207`/`b4bc2df`/`4a19854`/`b244851`/
+`68f905a` (the `BrowseChildren` lazy-browse SDK surface: `GalaxyRepositoryClient.browse()`,
+`browse(BrowseChildrenOptions)`, `browseChildrenRaw`, `browseChildrenInner`,
+plus the `LazyBrowseNode` walker and `BrowseChildrenOptions`), `a276f46`/
+`ba82afe`/`2eb8137` (lenient-by-default TLS: new `requireCertificateValidation`
+option, `InsecureTrustManagerFactory` fallback, foojay toolchain resolver), and
+`fe44e3c` (maven-publish wiring for the Gitea Maven feed). Generated
+protobuf/gRPC Java is excluded. `gradle test` could not be run here — this macOS
+host has no Java runtime (the module builds on the Windows host per project
+memory); findings below are from source inspection. Prior findings
+Client.Java-001..036 are unchanged.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | No issues found in this diff. `LazyBrowseNode.expand()` leader/coalesce logic is correct (single in-flight future, slot cleared on failure for retry); `browseChildrenInner` pagination handles the empty/null next-page token and guards against repeated page tokens; the `child_has_children` parallel array is bounds-checked (`i < getChildHasChildrenCount()`), defaulting absent hints to false. |
+| 2 | mxaccessgw conventions | No issues found. No MXAccess COM, no synthesized events, generated code untouched. The lenient-TLS default is a documented repo-wide design decision (`docs/DesignDecisions.md` "TLS Auto-Certificate and Lenient Client Trust"), not a Java-specific deviation. |
+| 3 | Concurrency & thread safety | No issues found. `LazyBrowseNode` does not hold the `expandLock` monitor across the BrowseChildren RPC (fixed in `68f905a`); readers use a separate `ReentrantReadWriteLock` so `getChildren()`/`isExpanded()` never block on the in-flight RPC; `BrowseChildrenOptions` is immutable. The shared `MxGatewayStreamSubscription` base (Client.Java-036) is covered. |
+| 4 | Error handling & resilience | No issues found. `browseChildrenRaw` normalises non-`MxGatewayException` gRPC errors via `MxGatewayErrors.fromGrpc`; the non-leader `expand()` path rethrows the leader's `MxGatewayException`/`RuntimeException` and restores the interrupt flag on `InterruptedException`. |
+| 5 | Security | No issues found. maven-publish credentials come from `GITEA_USERNAME`/`GITEA_TOKEN` env vars with empty-string fallback — no committed secrets. The lenient-TLS `InsecureTrustManagerFactory` default is the documented, intentional design for this PKI-less internal tool; strict verification is reachable via `caCertificatePath` (pin) or `requireCertificateValidation(true)`, both tested in `MxGatewayClientTlsTests`. |
+| 6 | Performance & resource management | No issues found. |
+| 7 | Design-document adherence | No issues found. The browse surface matches `docs/GalaxyRepository.md#browsechildren` (cache-served lazy expand, `has_children` hint, repeated-page-token → error); the TLS posture matches `docs/GatewayConfiguration.md` and `JavaClientDesign.md`. |
+| 8 | Code organization & conventions | Issue found: the new `requireCertificateValidation` library option is not exposed or propagated by the CLI `CommonOptions.toClientOptions()`, so CLI users cannot opt into JVM-trust-store verification — same additive-surface gap pattern as the resolved Client.Java-025 (Client.Java-038). |
+| 9 | Testing coverage | No issues found. The browse surface has thorough library tests in `GalaxyRepositoryClientTests` (roots, expand-populates, idempotent-single-RPC, unknown-parent not-found, multi-page gather, concurrent-callers-one-RPC, filter forwarding, repeated-page-token rejection); TLS lenient/strict paths are covered by `MxGatewayClientTlsTests` against a real in-process TLS server. |
+| 10 | Documentation & comments | Issue found: the README "Browsing lazily" first code snippet calls `galaxy.browseChildren(BrowseChildrenRequest…)`, but no such method exists on `GalaxyRepositoryClient` — the raw single-RPC method is `browseChildrenRaw(BrowseChildrenRequest)`; the documented snippet does not compile (Client.Java-037). |
+
 ## Findings
 
 ### Client.Java-001
@@ -662,4 +691,56 @@ This is the same maintenance-hazard pattern Client.Java-009 / Client.Java-016 id
 
 **Resolution:** 2026-05-24 — Extracted a package-private abstract base `MxGatewayStreamSubscription<TRequest, TResponse> implements AutoCloseable` (new file `clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/MxGatewayStreamSubscription.java`). It holds the shared `AtomicReference<ClientCallStreamObserver<TRequest>>` and `AtomicBoolean cancelled` pair, the `wrap(StreamObserver<TResponse>)` factory that returns a `ClientResponseObserver` with the Client.Java-014 close-before-beforeStart fix baked in, the `cancel()` / `close()` implementation, and an immutable `cancelMessage` injected by the subclass constructor. The four prior 60-line near-clones (`MxGatewayEventSubscription`, `MxGatewayAlarmFeedSubscription`, `MxGatewayActiveAlarmsSubscription`, `DeployEventSubscription`) collapse to ~10-line subclasses that only declare their `<Request, Response>` type parameters and supply the cancel-message string to `super(...)`. Public API surface is preserved: each subclass remains a `public final class` with a public no-arg constructor (the constructor was implicit on the original classes; I made it explicit `public` on the subclasses so the existing CLI `FakeClient.streamAlarms` in a different package can still `new MxGatewayAlarmFeedSubscription()`). The `wrap(...)` method is `final` and package-private on the base — same accessibility the four subclasses had before — so production callers in `MxGatewayClient`/`GalaxyRepositoryClient` see no change. New test file `MxGatewayStreamSubscriptionContractTests` exercises the lifecycle/cancellation contract identically across all four subclasses (16 tests, four per scenario): (a) cancel-before-beforeStart eagerly cancels the stream once it attaches with the subclass-specific message, (b) cancel-after-beforeStart forwards directly to the stream, (c) `close()` delegates to `cancel()`, (d) the wrapped observer forwards `onNext`/`onError`/`onCompleted` verbatim, and a compile-time `typeBoundsCheck` helper that asserts each subclass still binds its `<Req, Resp>` parameters to the right proto types. TDD red phase confirmed: temporarily breaking one subclass's `super(...)` message to `"BROKEN MESSAGE"` made the contract test for that subclass fail with `expected: <client cancelled alarm feed> but was: <BROKEN MESSAGE>`; restoring the correct value turned all 16 contract tests green. Future fixes to the shared lifecycle now live in one place — the next Client.Java-014/021-style race fix cannot drift across the four classes.
 
+### Client.Java-037
 
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Documentation & comments |
+| Location | `clients/java/README.md:138-149` |
+| Status | Resolved |
+
+**Description:** The "Browsing lazily" section's first (low-level) code snippet documents a `browseChildren` method that does not exist on the public client surface:
+
+```java
+BrowseChildrenReply reply = galaxy.browseChildren(
+        BrowseChildrenRequest.newBuilder().build());
+```
+
+`GalaxyRepositoryClient` exposes only `browse()`, `browse(BrowseChildrenOptions)`, and the raw single-RPC method `browseChildrenRaw(BrowseChildrenRequest)` (verified at `GalaxyRepositoryClient.java:227,238,251`). There is no `browseChildren(BrowseChildrenRequest)`, so the documented snippet fails to compile — a user copy-pasting the primary low-level example hits a missing-symbol error immediately. The README hedges the snippet with "This snippet documents the API as it appears once the Java client is regenerated on the Windows host," but the discrepancy is not a regeneration artifact: the hand-written wrapper method is named `browseChildrenRaw`, not `browseChildren`. The adjacent "High-level walker" snippet (`galaxy.browse()`, `root.expand()`, `root.getChildren()`, `child.hasChildrenHint()`, `child.getObject().getTagName()`) is correct against the actual API; only the low-level snippet is wrong.
+
+**Recommendation:** Change `galaxy.browseChildren(` to `galaxy.browseChildrenRaw(` in the low-level snippet so it matches the real method name, or replace the low-level example with the `browse()`/`LazyBrowseNode` walker that the SDK actually intends as the primary surface. Drop the "as it appears once regenerated" caveat once the snippet compiles against the current source. Consider an `installDist`-based or compile-checked doc snippet test to prevent README API drift, mirroring the parse-only assertions added for Client.Java-032.
+
+**Resolution:** 2026-06-15 — Confirmed against source: `GalaxyRepositoryClient` (`zb-mom-ww-mxgateway-client/.../GalaxyRepositoryClient.java:227,238,251`) exposes only `browse()`, `browse(BrowseChildrenOptions)`, and the raw single-RPC `browseChildrenRaw(BrowseChildrenRequest)` — there is no `browseChildren(BrowseChildrenRequest)`, so the documented snippet did not compile. Fixed the README "Browsing lazily" low-level snippet at `clients/java/README.md` by renaming `galaxy.browseChildren(` to `galaxy.browseChildrenRaw(`; the surrounding accessors (`BrowseChildrenReply`/`BrowseChildrenRequest` types, `getChildrenList()`, `getChildHasChildrenList()`, `getTagName()`) are all valid proto accessors and were left unchanged. Replaced the misleading "as it appears once the Java client is regenerated on the Windows host" caveat (the discrepancy was a hand-written wrapper name, not a codegen artifact) with prose steering callers to the high-level `browse()`/`LazyBrowseNode` walker as the preferred surface and `browseChildrenRaw` as the direct-paging escape hatch. Documentation-only change; no test added (no compile-checked doc-snippet harness exists yet — left as the noted future enhancement).
+
+### Client.Java-038
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `clients/java/zb-mom-ww-mxgateway-cli/src/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java:1347-1393` |
+| Status | Resolved |
+
+**Description:** Commit `a276f46` added `requireCertificateValidation` to `MxGatewayClientOptions` as a first-class TLS-trust toggle (lenient-by-default; set `true` to verify against the JVM trust store without pinning a CA). The CLI `CommonOptions` exposes `--plaintext`, `--ca-file`, and `--server-name-override` and propagates them through `toClientOptions()`, but it neither declares a `--require-certificate-validation` option nor sets `builder.requireCertificateValidation(...)`. CLI users therefore have no way to request strict verification short of supplying a pinned CA via `--ca-file`; the lenient `InsecureTrustManagerFactory` default is forced on every non-pinned TLS CLI connection. This is the same additive-surface gap pattern as the resolved Client.Java-025 (`shutdownTimeout` not propagated to the CLI). `docs/CrossLanguageSmokeMatrix.md` documents `--require-certificate-validation` for the Rust CLI's pin-only stack but not Java, so this is not a direct README contradiction; it is a library-vs-CLI surface inconsistency. Severity is Low because the secure-by-pinning path (`--ca-file`) remains available and the lenient default is the documented intended behaviour for this internal tool.
+
+**Recommendation:** Add a `--require-certificate-validation` boolean option to `CommonOptions` (default unset/false to preserve the lenient default) and propagate it into `toClientOptions()` via `builder.requireCertificateValidation(value)`. Include the resolved value in `redactedJsonMap()` so `--json` output reflects the effective trust posture. Add a CLI parse-only assertion exercising the flag to keep the CLI surface tracking the library surface.
+
+**Resolution:** 2026-06-15 — Confirmed against source: `MxGatewayClientOptions` (`zb-mom-ww-mxgateway-client/.../MxGatewayClientOptions.java:108,260`) exposes `requireCertificateValidation()` and a `Builder.requireCertificateValidation(boolean)`, but the CLI `CommonOptions` in `MxGatewayCli.java` declared no flag and `toClientOptions()` never set it, forcing the lenient default on every non-pinned TLS CLI connection. Added a bare-boolean `@Option(names = "--require-certificate-validation")` field to `CommonOptions` (defaults to `false`, preserving the lenient default; mirrors the existing `--plaintext` flag-style option), propagated it through `toClientOptions()` via `.requireCertificateValidation(requireCertificateValidation)`, and added it to `redactedJsonMap()` so `--json` output reflects the effective trust posture. Documented the new flag and the lenient-by-default trust posture in `clients/java/README.md`. Note: the Client.Java-025 precedent (`shutdownTimeout`) was applied to the pre-rename `mxgateway-cli` module and is not present in this renamed `zb-mom-ww-mxgateway-cli` `toClientOptions()`; I mirrored the live `--ca-file`/`--server-name-override` TLS-option plumbing pattern instead, which is the correct precedent here. Regression tests in `MxGatewayCliTests`: `requireCertificateValidationFlagPropagatesThroughToClientOptions` (drives `acknowledge-alarm --require-certificate-validation` through a new `CapturingClientFactory` that records `options.toClientOptions()` and asserts `MxGatewayClientOptions.requireCertificateValidation()` is `true`) and `requireCertificateValidationDefaultsToLenientWhenFlagAbsent` (asserts the flag defaults to `false`). The capturing factory exercises the real `toClientOptions()` propagation, stronger than a parse-only check.
+
+
+
+### Client.Java-039
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Correctness & logic bugs |
+| Location | `clients/java/zb-mom-ww-mxgateway-cli/src/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java:1699` (origin: `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto`, `AlarmFeedMessage.payload` provider-status arm added in commit `1d85db7`) |
+| Status | Resolved |
+
+**Description:** The Java CLI does not compile at HEAD `410acc9`. `formatAlarmFeedMessage` switches over `message.getPayloadCase()` as an exhaustive switch *expression* with no `default`, covering only `ACTIVE_ALARM`, `SNAPSHOT_COMPLETE`, `TRANSITION`, and `PAYLOAD_NOT_SET`. The alarm-provider-fallback contract change `1d85db7` added a fourth `AlarmFeedMessage.payload` oneof arm (`AlarmProviderStatus provider_status`), so the generated `PayloadCase` enum now has a `PROVIDER_STATUS` value the switch does not handle — `javac` rejects it with "the switch expression does not cover all possible input values" and `gradle :zb-mom-ww-mxgateway-cli:compileJava` fails. This is the same class of cross-component contract-propagation break as Client.Rust-030 and IntegrationTests-026: a new contract field that left a downstream exhaustive consumer uncompilable. The original re-review (Client.Java-037/038) missed it because there is no JVM on the macOS review host and `gradle` could not be run; the break surfaced when the fixes were verified on the Windows host. Because the CLI is the cross-language e2e driver, the whole Java client artifact set cannot build and no Java e2e smoke can run.
+
+**Recommendation:** Add a `PROVIDER_STATUS` arm to `formatAlarmFeedMessage` that renders the provider status (mode / degraded / reason) consistently with the other alarm-feed arms — do not add a `default ->` that silently drops it, since the provider status is meaningful and the exhaustive switch is the compiler-enforced guard that catches exactly this kind of future contract drift.
+
+**Resolution:** 2026-06-15 — Confirmed via `gradle :zb-mom-ww-mxgateway-cli:compileJava` failing with "the switch expression does not cover all possible input values" at `MxGatewayCli.java:1699` on the Windows host. Added a `case PROVIDER_STATUS ->` arm to `formatAlarmFeedMessage` yielding `provider-status mode=%s degraded=%b reason=%s` (from `AlarmProviderStatus.getMode().name()` / `getDegraded()` / `getReason()`), plus the `import mxaccess_gateway.v1.MxaccessGateway.AlarmProviderStatus;`. No `default` arm — the exhaustive switch expression remains the compile-time guard against future `payload` oneof additions. Verified `gradle test` builds and passes on the Windows host (Java 21).

code-reviews/Client.Python/findings.md

@@ -4,16 +4,48 @@
 |---|---|
 | Module | `clients/python` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |
 
 ## Checklist coverage
 
+### 2026-06-15 re-review (commit 410acc9)
+
+Re-review pass at `410acc9`. The diff against the previous review base
+`42b0037` covers: PyPI metadata + Gitea PyPI-feed install instructions in
+`pyproject.toml` / `README.md`; a new lazy Galaxy browse surface
+(`GalaxyRepositoryClient.browse_children_raw` / `browse` / `_iter_browse_children`,
+the `LazyBrowseNode` walker, and `BrowseChildrenOptions`); a TLS
+trust-on-first-use (TOFU) default in `options.py` gated by a new
+`ClientOptions.require_certificate_validation` flag; the `_use_plaintext`
+TLS-default contract carried forward; and the `batch` `CliRunner`-removal
+follow-through. The new browse / TOFU surface is well tested
+(`tests/test_galaxy.py`, `tests/test_auth_options.py`, `tests/test_tls.py`).
+
+`python -m pytest` passes (80 passed, 1 skipped — the loopback-TLS test is
+opt-in via `MXGATEWAY_RUN_TLS_TESTS=1`). `python -m pip wheel .` builds the
+wheel cleanly against the installed setuptools 82.0.1.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issue found: `_split_authority` raises an uncaught `ValueError` for a port-less endpoint instead of a transport error (Client.Python-029). |
+| 2 | mxaccessgw conventions | No new issues found — secrets still redacted, generated code untouched, no committed tokens in the new Gitea feed URLs (placeholders only). |
+| 3 | Concurrency & thread safety | No new issues found — `LazyBrowseNode.expand` uses a per-node `asyncio.Lock` with a double-checked guard and is verified concurrent-safe by `test_browse_expand_concurrent_callers_only_fire_one_rpc`. |
+| 4 | Error handling & resilience | Issue found: the TOFU branch calls the blocking `ssl.get_server_certificate` with no timeout from inside the `async def connect` path, blocking the event loop and hanging indefinitely on a black-holed host (Client.Python-028). |
+| 5 | Security | Issue found: the new `require_certificate_validation` security flag is not reachable through the documented `connect(...)` convenience kwargs or any CLI flag, so callers using those paths are locked into TOFU and cannot force certificate validation (Client.Python-027). TOFU itself is design-sanctioned (`docs/GatewayConfiguration.md` line 470). |
+| 6 | Performance & resource management | No new issues found beyond the blocking TLS probe captured in Client.Python-028. |
+| 7 | Design-document adherence | No new issues found — TOFU default, `require_certificate_validation` naming, and the BrowseChildren surface match `docs/GatewayConfiguration.md` / `docs/GalaxyRepository.md`; both README doc anchors resolve. |
+| 8 | Code organization & conventions | Issue found: `pyproject.toml` uses the PEP 639-deprecated `license = { text = ... }` table form (Client.Python-030). pyproject metadata is otherwise correct and the wheel builds. |
+| 9 | Testing coverage | Issue found: the `tls` pytest mark used by `tests/test_tls.py` is not registered in `[tool.pytest.ini_options]`, emitting a `PytestUnknownMarkWarning` (Client.Python-031). New browse / TOFU paths are otherwise well covered. |
+| 10 | Documentation & comments | No new issues found — README TLS/browse/Gitea-feed prose matches the code; the alarm-CLI README examples corrected under Client.Python-022 remain correct. |
+
+### Prior coverage (commit a020350)
+
 A re-review at commit `a020350` over the same module. Prior findings
 (Client.Python-001 — Client.Python-017) remain closed and are kept as
-history. This section reflects categories evaluated in this pass.
+history. This section reflects categories evaluated in that pass.
 
 | # | Category | Result |
 |---|---|---|
@@ -1171,3 +1203,238 @@ scope; `test_commands_module_bench_read_bulk_does_not_use_bare_except_pass`
 greps the function source for the `except Exception:\n    pass` pattern
 and rejects it. Both tests failed against the pre-fix source and pass
 against the fix.
+
+### Client.Python-027
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Security |
+| Location | `clients/python/src/zb_mom_ww_mxgateway/client.py:36-54`, `clients/python/src/zb_mom_ww_mxgateway/galaxy.py:47-66`, `clients/python/src/zb_mom_ww_mxgateway_cli/commands.py:165-172,918-930` |
+| Status | Resolved |
+
+**Description:** This commit adds `ClientOptions.require_certificate_validation`
+(default `False`) so a caller can force system-trust certificate verification
+instead of the new lenient trust-on-first-use (TOFU) default. The flag is
+honoured inside `create_channel`, but it is not surfaced through either of the
+two documented ways a normal caller dials the gateway:
+
+1. `GatewayClient.connect(...)` and `GalaxyRepositoryClient.connect(...)` accept
+   the convenience kwargs `endpoint` / `api_key` / `plaintext` / `ca_file` /
+   `server_name_override` and build the `ClientOptions` internally, but do **not**
+   accept or forward `require_certificate_validation`. The README's high-level
+   examples (e.g. the lazy-browse walker) use exactly this kwarg form
+   (`GalaxyRepositoryClient.connect(endpoint=..., api_key=..., plaintext=True)`),
+   so the kwarg path is the primary documented entry point.
+2. The CLI exposes `--plaintext`, `--tls`, and `--ca-file` but no
+   `--require-certificate-validation` flag, and `_connect` constructs
+   `ClientOptions(...)` without setting the field. A CLI user connecting to a
+   TLS gateway is therefore locked into TOFU.
+
+The net effect is that the *only* way to opt into real certificate validation is
+to construct a `ClientOptions` instance directly and pass it as the positional
+`options=` argument — a path neither the README nor the CLI documents. A
+security-sensitive deployment that wants the strict (verify-against-system-trust)
+posture cannot select it through the documented surface, so it silently stays on
+TOFU. TOFU itself is design-sanctioned (`docs/GatewayConfiguration.md` line 470
+explicitly says "Python uses trust-on-first-use"), so this is an opt-in-to-strict
+reachability gap rather than an insecure default — hence Medium with a workaround.
+
+**Recommendation:** Add a `require_certificate_validation: bool = False` kwarg to
+both `GatewayClient.connect` and `GalaxyRepositoryClient.connect` and forward it
+into the constructed `ClientOptions`. Add a `--require-certificate-validation`
+(or `--verify-tls`) flag to the shared CLI option set and wire it through
+`_connect`. Add a test asserting the flag flows through to
+`ClientOptions.require_certificate_validation` and a README note documenting how
+to select the strict posture.
+
+**Resolution:** 2026-06-15 — Confirmed: `connect` built `ClientOptions` from a
+fixed kwarg set that omitted `require_certificate_validation`, and the CLI had no
+flag, so the strict posture was only reachable via a hand-built `options=`. Added
+a `require_certificate_validation: bool = False` kwarg to both
+`GatewayClient.connect` and `GalaxyRepositoryClient.connect` (forwarded into the
+constructed `ClientOptions`), a `--require-certificate-validation` flag to the
+shared `gateway_options` CLI option set, and wired it through `_connect`. README
+TLS section now documents the strict posture is reachable via the connect kwarg,
+the options struct, and the CLI flag. Tests:
+`tests/test_client_session.py::test_gateway_connect_forwards_require_certificate_validation`,
+`::test_galaxy_connect_forwards_require_certificate_validation`,
+`tests/test_cli.py::test_require_certificate_validation_flag_flows_through_connect`,
+`::test_require_certificate_validation_defaults_off` — all failed before the fix
+and pass after.
+
+### Client.Python-028
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `clients/python/src/zb_mom_ww_mxgateway/options.py:120-130`, `clients/python/src/zb_mom_ww_mxgateway/client.py:59`, `clients/python/src/zb_mom_ww_mxgateway/galaxy.py:71` |
+| Status | Resolved |
+
+**Description:** The TOFU branch of `create_channel` calls
+`ssl.get_server_certificate((host, port))` to pre-fetch the server certificate.
+`create_channel` is a synchronous function, but it is invoked exclusively from
+inside the `async def connect` classmethods of `GatewayClient` and
+`GalaxyRepositoryClient` (`client.py:59`, `galaxy.py:71`). `ssl.get_server_certificate`
+opens a real blocking TCP+TLS socket on the calling thread, so:
+
+1. It **blocks the asyncio event loop** for the full duration of the connect/handshake.
+   This is at odds with the rest of the client, which is fully `async`.
+2. It passes **no `timeout`** to `ssl.get_server_certificate`. The `test_tofu_connect_failure_raises_transport_error`
+   test only proves the *connection-refused* case (a closed port returns fast).
+   A black-holed / firewall-drop host (packets silently dropped) makes the
+   underlying `socket.create_connection` hang on the OS default connect timeout,
+   which can be minutes, with the event loop frozen the whole time. A caller that
+   wrapped `connect` in `asyncio.wait_for(...)` cannot cancel it because the block
+   is in synchronous C, not at an `await` point.
+
+The other TLS branches (`ca_file`, `require_certificate_validation`) build the
+channel lazily and return immediately, so only the lenient default — the most
+common path — has this hazard.
+
+**Recommendation:** Pass an explicit `timeout=` to `ssl.get_server_certificate`
+(it accepts one), bounded by `options.call_timeout` or a short fixed value, so a
+black-holed host fails fast as a `MxGatewayTransportError` instead of hanging.
+Better, run the synchronous probe off the event loop — make the TOFU pre-fetch
+path awaitable (e.g. wrap it in `asyncio.get_running_loop().run_in_executor(...)`
+from an `async` channel factory, or document that `connect` must not be called
+from a running loop). Add a regression test that asserts the probe honours a
+timeout.
+
+**Resolution:** 2026-06-15 — Confirmed: the TOFU branch called
+`ssl.get_server_certificate((host, port))` with no timeout from the synchronous
+`create_channel`, which both `connect` classmethods invoked directly on the event
+loop. Fix is two-part: (1) `create_channel` now passes
+`timeout=options.call_timeout` (falling back to a fixed
+`_TOFU_PROBE_TIMEOUT_SECONDS = 10.0` when no call_timeout is set) to
+`ssl.get_server_certificate`, and the existing `except OSError` wraps a
+timeout/connect failure into `MxGatewayTransportError` (TimeoutError/socket.timeout
+are OSError subclasses); (2) both `GatewayClient.connect` and
+`GalaxyRepositoryClient.connect` now run the blocking factory off the loop via
+`await asyncio.to_thread(create_channel, resolved)`, so the event loop is never
+frozen and a caller's `asyncio.wait_for` can cancel the connect. Tests:
+`tests/test_auth_options.py::test_tofu_probe_passes_a_bounded_timeout`,
+`::test_tofu_probe_timeout_raises_transport_error` (parametrized over
+socket.timeout / TimeoutError / OSError), and
+`tests/test_client_session.py::test_gateway_connect_runs_create_channel_off_the_event_loop`,
+`::test_galaxy_connect_runs_create_channel_off_the_event_loop`. The timeout and
+off-loop tests failed before the fix and pass after.
+
+### Client.Python-029
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `clients/python/src/zb_mom_ww_mxgateway/options.py:78-90` |
+| Status | Resolved |
+
+**Description:** `_split_authority` parses a non-bracketed target with
+`host, _, port = target.rpartition(":")` and returns
+`(host or "localhost", int(port) if port else 443)`. For a port-less endpoint
+such as `"mygateway"`, `rpartition(":")` returns `("", "", "mygateway")`, so
+`host` becomes `""` (→ `"localhost"`) and `port` becomes `"mygateway"`, and
+`int("mygateway")` raises an uncaught `ValueError: invalid literal for int()`.
+Because `_split_authority` is called *before* the `try/except OSError` guard in
+`create_channel`, the failure escapes as a raw `ValueError` rather than the
+intended `MxGatewayTransportError`, and the message does not name the endpoint.
+Verified at runtime:
+`_split_authority("mygateway")` → `ValueError: invalid literal for int() with base 10: 'mygateway'`.
+gRPC targets normally carry an explicit port (`host:port`), so impact is narrow,
+but a typo or a bare-hostname endpoint produces a confusing crash on the TOFU
+default path. The bracketed-IPv6 and `host:port` cases are covered by tests; the
+port-less case is not.
+
+**Recommendation:** Treat a non-numeric / missing port as the default (443) and
+keep the whole string as the host, e.g. detect a trailing `:<digits>` explicitly
+rather than assuming the `rpartition` tail is numeric, or wrap the `int(port)`
+conversion so a non-numeric tail falls back to host-only with the default port.
+Add a `_split_authority("mygateway")` case to `tests/test_tls.py`.
+
+**Resolution:** 2026-06-15 — Confirmed: `_split_authority("mygateway")` raised
+`ValueError: invalid literal for int() with base 10: 'mygateway'` because
+`rpartition(":")` put the whole string in the port slot. Rewrote the
+non-bracketed branch to inspect the `rpartition` separator and the tail: no colon
+→ whole target is the host with default port 443; a colon with a non-digit/empty
+tail → left side is the host with default port 443; a digit tail → parse the
+port. The bare-hostname case now returns `("mygateway", 443)` instead of raising,
+and the existing `":5120"` / `"localhost:5120"` / IPv6 cases are unchanged. Test:
+`tests/test_tls.py::test_split_authority_defaults_port_for_portless_endpoint`
+(covers `"mygateway"`, `"https://mygateway"`, and `"mygateway:"`) — failed before
+the fix and passes after.
+
+### Client.Python-030
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `clients/python/pyproject.toml:17` |
+| Status | Resolved |
+
+**Description:** This commit re-adds a `license` key to `pyproject.toml` as the
+table form `license = { text = "Proprietary" }`. Under PEP 639 (active in the
+installed setuptools 82.0.1), the `[project.license]` **table** forms (`text` and
+`file`) are deprecated in favour of the SPDX string expression, and a future
+setuptools major may reject them — the same class of regression that
+Client.Python-018 (the earlier `license = "Proprietary"` string, rejected because
+`Proprietary` is not a valid SPDX identifier) recorded for this exact field. The
+build currently succeeds (verified: `python -m pip wheel .` produces
+`zb_mom_ww_mxaccess_gateway_client-0.1.0-py3-none-any.whl` and the metadata
+carries `License: Proprietary` plus the `License :: Other/Proprietary License`
+classifier), so this is a forward-looking maintainability flag, not a present
+breakage. Note that pairing a `license` table with a `License ::` trove
+classifier is also flagged by PyPI/twine as redundant under the new metadata
+rules.
+
+**Recommendation:** Prefer the PEP 639 SPDX-string form with a `LicenseRef-*`
+custom identifier for an unlisted licence (`license = "LicenseRef-Proprietary"`)
+— this is the future-proof equivalent of the intent and avoids the deprecated
+table form — or drop the `license` key entirely and rely on the existing
+`License :: Other/Proprietary License` classifier (the Client.Python-018
+resolution chose this). The `tests/test_packaging.py::test_pip_wheel_build_succeeds`
+guard (added under Client.Python-020) will catch the day a setuptools upgrade
+turns the deprecation into a hard error.
+
+**Resolution:** 2026-06-15 — Switched the deprecated `license = { text =
+"Proprietary" }` table form to the PEP 639 SPDX-string form
+`license = "LicenseRef-Proprietary"` (the future-proof custom identifier for an
+unlisted/proprietary licence). Also removed the now-redundant
+`License :: Other/Proprietary License` trove classifier, which setuptools >= 77
+flags as conflicting when a `License-Expression` is present. The built wheel
+metadata now carries `License-Expression: LicenseRef-Proprietary` and no
+`Classifier: License ::` line. Verified by `python -m pip wheel . --no-deps`,
+which builds cleanly; the existing
+`tests/test_packaging.py::test_pip_wheel_build_succeeds` guard exercises the same
+build and passes.
+
+### Client.Python-031
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `clients/python/tests/test_tls.py:34`, `clients/python/pyproject.toml:53-56` |
+| Status | Resolved |
+
+**Description:** `tests/test_tls.py` applies a module-level
+`pytestmark = pytest.mark.tls`, but the `tls` marker is not registered in
+`[tool.pytest.ini_options]` (which declares only `addopts`, `pythonpath`, and
+`testpaths`). Every run emits a `PytestUnknownMarkWarning: Unknown
+pytest.mark.tls - is this a typo?`. The warning is benign today, but (a) it is
+exactly the kind of typo the warning exists to catch, so a future genuine
+mistyped marker would be lost in the noise, and (b) if the suite ever adopts
+`filterwarnings = ["error"]` (a common hardening step), the unregistered marker
+would turn into a hard collection failure.
+
+**Recommendation:** Register the marker, e.g.
+`markers = ["tls: loopback TLS tests, opt-in via MXGATEWAY_RUN_TLS_TESTS=1"]`
+under `[tool.pytest.ini_options]` in `clients/python/pyproject.toml`.
+
+**Resolution:** 2026-06-15 — Registered the `tls` marker by adding
+`markers = ["tls: loopback TLS tests, opt-in via MXGATEWAY_RUN_TLS_TESTS=1"]`
+under `[tool.pytest.ini_options]` in `clients/python/pyproject.toml`.
+`python -m pytest` now reports no `PytestUnknownMarkWarning` (full run: 91
+passed, 1 skipped, 0 warnings; previously 1 warning). The `tls`-marked
+`tests/test_tls.py` module is the guard — its run is now warning-free.

code-reviews/Client.Rust/findings.md

@@ -4,8 +4,8 @@
 |---|---|
 | Module | `clients/rust` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |
 
@@ -96,6 +96,25 @@ under review does not address them.
 | 9 | Testing coverage | Issue found: zero tests cover `stream_alarms` on `GatewayClient`, the new bulk read/write SDK methods, or the `BenchReadBulk` flow; the fake gateway's `stream_alarms` impl drops the sender immediately (Client.Rust-024). |
 | 10 | Documentation & comments | Issue found: `.cargo/config.toml`'s comment promises "Release builds are unaffected" but the `link-arg=/STACK:8388608` setting is unconditional under `cfg(windows)` and only applies to the MSVC linker (Client.Rust-027). |
 
+### 2026-06-15 re-review (commit 410acc9)
+
+Re-review pass at `410acc9`. The diff against `42b0037` (`git diff 42b0037..HEAD -- clients/rust/`) covers: Cargo metadata + Gitea alternative-registry config (`Cargo.toml`, `.cargo/config.toml`, README install section); a `[registries.dohertj2-gitea]` index entry and `publish = ["dohertj2-gitea"]` with `mxgw-cli` set `publish = false`; the resolution work for Client.Rust-022..029 (malformed-reply `Result` plumbing, `next_correlation_id` re-export, clippy fixes, `read_bulk<S: AsRef<str>>`); a **new** Galaxy lazy-browse walker (`browse`, `browse_children_raw`, `browse_children_inner`, `BrowseChildrenOptions`, `LazyBrowseNode`) with six unit tests; a **new** TLS pin-only guard (`build_tls_config` + `ClientOptions::with_require_certificate_validation` + `--require-certificate-validation` CLI flag) with a new `tests/tls.rs`; and the alarm-provider-fallback proto surface (`AlarmFeedMessage.provider_status`, added contracts-side in `1d85db7`).
+
+`cargo fmt --check` is clean. `cargo check -p zb-mom-ww-mxgateway-client`, `cargo test -p zb-mom-ww-mxgateway-client` (24 lib + integration, 4 proto-fixture, 4 tls — all pass), and the library half of the workspace are clean. **`cargo clippy --workspace --all-targets -- -D warnings` and `cargo check --workspace` both FAIL at HEAD** — not on a lint but on a hard `E0004` compile error: the `mxgw-cli` binary's two `match &message.payload` blocks (`crates/mxgw-cli/src/main.rs:1731,1757`) are non-exhaustive after the proto added `AlarmFeedMessage.payload::ProviderStatus` (Client.Rust-030). The library crate compiles and all its tests pass; the break is confined to the CLI binary. No committed registry tokens — `.cargo/config.toml` carries only the sparse index URL; the README documents the token living in `~/.cargo/credentials.toml`.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issue found: `mxgw-cli` fails to compile at HEAD — non-exhaustive `AlarmFeedMessage.payload` match missing the new `ProviderStatus` arm (Client.Rust-030). The library `read_bulk`/galaxy-walker/TLS-guard logic is correct and tested. |
+| 2 | mxaccessgw conventions | Issue found: `cargo clippy --workspace --all-targets -- -D warnings` / `cargo check --workspace` do not pass — CLAUDE.md mandates they do (Client.Rust-030). The prior 029 clippy regressions are resolved; this is a new build break from the alarm-provider proto change. |
+| 3 | Concurrency & thread safety | No issues found — `LazyBrowseNode` shares state via `Arc<…AsyncMutex<…>>`; `expand()` holds the mutex across the `browse_children_inner` await so concurrent expanders serialize and the idempotency check is race-free. `CORRELATION_SEQUENCE` is still `AtomicU64`/`Relaxed`. No `unsafe`. |
+| 4 | Error handling & resilience | Issue found: the strict TLS path (`require_certificate_validation(true)` with no CA) builds a `ClientTlsConfig` with zero trust roots (no `tls-native-roots`/`tls-webpki-roots` feature, no `.with_*_roots()` call), so it cannot validate any certificate — contradicting the documented "verify against the system trust roots" behaviour (Client.Rust-031). The galaxy page-token loop has a correct repeated-token guard. |
+| 5 | Security | No issues found in the registry/secret surface — `.cargo/config.toml` holds only the sparse index URL, no token; README puts the Bearer token in `~/.cargo/credentials.toml` (uncommitted). (See Client.Rust-031 for the strict-TLS validation gap, classified under error handling.) |
+| 6 | Performance & resource management | No issues found — `read_bulk` is now borrow-based (`&[S]`), the bench loop reuses `tags_ref` (Client.Rust-026 resolved). The walker clones the `GalaxyClient` channel handle per node, which is the intended cheap `Channel` clone. |
+| 7 | Design-document adherence | Issue found: `RustClientDesign.md` is not updated for the new Galaxy lazy-browse SDK surface (`browse` / `browse_children_raw` / `LazyBrowseNode` / `BrowseChildrenOptions`); CLAUDE.md requires docs to change with the source (Client.Rust-032). The TLS pin-only section pre-dates this diff but repeats the inaccurate "system trust roots" claim (cross-referenced from Client.Rust-031). |
+| 8 | Code organization & conventions | No issues found — Cargo metadata (name/version/license/repository/keywords/categories) is well-formed; `publish = ["dohertj2-gitea"]` on the library and `publish = false` on `mxgw-cli` is the right split. `license = "Proprietary"` is non-SPDX but cargo accepts it and it is a deliberate closed-source marker. |
+| 9 | Testing coverage | No issues found in the new surface — the walker has six unit tests (roots, expand, idempotency, NotFound, multi-page, filter-forwarding) and TLS has four. Gap noted: `tls_with_require_certificate_validation_does_not_short_circuit` connects to a dead address, so it only asserts the guard does not fire and never exercises a real handshake — which is why the no-trust-roots defect in Client.Rust-031 is not caught by a test. |
+| 10 | Documentation & comments | Issue found: the `alarm_feed_message_summary` / `alarm_feed_message_to_json` doc comments still say "three `payload` oneof cases" (`main.rs:1729,1755`) although the proto now has four; folded into Client.Rust-030's fix. The TLS doc inaccuracy is Client.Rust-031. |
+
 ## Findings
 
 ### Client.Rust-001
@@ -687,3 +706,59 @@ The third error (`BulkReplyKind` enum-variant-names) is also touched by the diff
 **Recommendation:** Re-apply Client.Rust-001 (add doc comments on `with_max_grpc_message_bytes` / `max_grpc_message_bytes` in `options.rs`), Client.Rust-002 (drop the `Bulk` suffix from `BulkReplyKind`'s variants so they become `AddItem` / `AdviseItem` / …, or add a narrowly-scoped `#[allow(clippy::enum_variant_names)]` with a reason comment), and Client.Rust-012 (replace `last_deploy.lock().unwrap().clone()` with `*last_deploy.lock().unwrap()` in `galaxy.rs:282`). Verify with `cargo clippy --workspace --all-targets -- -D warnings`. Consider adding a pre-commit / CI gate so the next reviewer never has to discover the regression by running clippy.
 
 **Resolution:** 2026-05-24 — Re-applied all three resolutions. `clients/rust/src/options.rs` now has `///` doc comments on `with_max_grpc_message_bytes` and `max_grpc_message_bytes`. `clients/rust/src/galaxy.rs:282` uses `*self.state.last_deploy.lock().unwrap()` instead of `.clone()`. `clients/rust/src/session.rs`'s `BulkReplyKind` variants are renamed to `AddItem` / `AdviseItem` / `RemoveItem` / `UnAdviseItem` / `Subscribe` / `Unsubscribe` (no shared `Bulk` suffix), with the call sites in `add_item_bulk` / `advise_item_bulk` / `remove_item_bulk` / `un_advise_item_bulk` / `subscribe_bulk` / `unsubscribe_bulk` updated accordingly. The sibling `BulkWriteReplyKind` already had non-suffix-sharing variants (`Write` / `Write2` / `WriteSecured` / `WriteSecured2`) and required no rename. `cargo clippy --workspace --all-targets -- -D warnings` is clean at HEAD.
+
+### Client.Rust-030
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Correctness & logic bugs |
+| Location | `clients/rust/crates/mxgw-cli/src/main.rs:1731,1757` (origin: `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto:909-924`, added in commit `1d85db7`) |
+| Status | Resolved |
+
+**Description:** The `mxgw-cli` binary does not compile at HEAD `410acc9`. `cargo check --workspace`, `cargo clippy --workspace --all-targets -- -D warnings`, `cargo build --workspace`, and `cargo test --workspace` all fail with a hard `E0004` (non-exhaustive patterns), so the entire documented Rust build/test/clippy workflow that CLAUDE.md mandates is broken:
+
+```
+error[E0004]: non-exhaustive patterns: `&Some(...alarm_feed_message::Payload::ProviderStatus(_))` not covered
+    --> crates/mxgw-cli/src/main.rs:1731:11
+error[E0004]: non-exhaustive patterns: `&Some(...alarm_feed_message::Payload::ProviderStatus(_))` not covered
+    --> crates/mxgw-cli/src/main.rs:1757:11
+```
+
+The alarm-provider-fallback contract change (`1d85db7`, within the reviewed range) added a fourth `AlarmFeedMessage.payload` oneof arm — `AlarmProviderStatus provider_status = 4`. tonic-build regenerates the Rust enum with the new `ProviderStatus` variant, but `alarm_feed_message_summary` (`main.rs:1731`) and `alarm_feed_message_to_json` (`main.rs:1757`) each `match &message.payload` exhaustively over only `ActiveAlarm` / `SnapshotComplete` / `Transition` / `None` with no wildcard arm. Because they are exhaustive matches on a now-larger enum, the binary fails to compile rather than silently mishandling the new variant. The library crate (`zb-mom-ww-mxgateway-client`) itself compiles cleanly and all 32 of its tests pass; the break is confined to the CLI — but the CLI is the cross-language e2e matrix driver, so the whole `clients/rust` workspace is unbuildable and no Rust e2e smoke can run against the gateway at this commit. This is the alarm-surface gap the review request asked to check: the `ProviderStatus` payload is unhandled in the only place the Rust client renders the alarm feed.
+
+**Recommendation:** Add a `Some(alarm_feed_message::Payload::ProviderStatus(status))` arm to both `alarm_feed_message_summary` and `alarm_feed_message_to_json` (render the provider-status fields — mode, degraded/provenance, reference — consistent with how the .NET/Go/Java/Python CLIs serialise it so the cross-language parity matcher recognises the payload). While there, update the two doc comments that still say "three `payload` oneof cases" (`main.rs:1729,1755`) to four. Verify with `cargo clippy --workspace --all-targets -- -D warnings` and `cargo test --workspace`. Consider a CI gate so a contract change that adds a oneof arm cannot leave the Rust CLI unbuildable again.
+
+**Resolution:** 2026-06-15 — Root cause confirmed: the contract's new fourth `AlarmFeedMessage.payload` oneof arm (`AlarmProviderStatus provider_status`, proto fields `mode`/`degraded`/`reason`/`since`) left both `match &message.payload` blocks non-exhaustive (`E0004`). Added a `Some(alarm_feed_message::Payload::ProviderStatus(status))` arm to both `alarm_feed_message_summary` (`mode`/`degraded`/`reason` one-liner) and `alarm_feed_message_to_json` (a `providerStatus` object with `mode`/`degraded`/`reason`/`since`), added an `AlarmEnumName::provider_mode` enum-name helper consistent with the existing `condition_state`/`transition_kind` renderers, and updated the summary doc comment to "four payload oneof cases". No `_ => {}` wildcard. Test: `alarm_feed_provider_status_renders_in_summary_and_json` (in `crates/mxgw-cli/src/main.rs`). All four cargo commands now pass.
+
+### Client.Rust-031
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `clients/rust/src/options.rs:196-240` (`build_tls_config`); `clients/rust/Cargo.toml:40` (tonic features); docs: `clients/rust/src/options.rs:76-101`, `clients/rust/README.md` (TLS trust section), `clients/rust/crates/mxgw-cli/src/main.rs:429-431`, `clients/rust/RustClientDesign.md:202` |
+| Status | Resolved |
+
+**Description:** The new strict-verification escape hatch does not do what it documents. `build_tls_config` only configures trust roots when a CA file is pinned: with `require_certificate_validation(true)` and no `ca_file`, it returns a bare `ClientTlsConfig::new()` and never calls `.with_native_roots()`, `.with_webpki_roots()`, or `.with_enabled_roots()`. The crate also enables only `tonic` feature `tls-ring` (`Cargo.toml:40`) — neither `tls-native-roots` nor `tls-webpki-roots` is on, so even if the code wanted to enable system roots the methods are feature-gated out. A `ClientTlsConfig` with zero trust anchors rejects every server certificate during the rustls handshake, so the strict path cannot connect to any TLS gateway — not even one whose certificate is genuinely chained to a system root. Yet `with_require_certificate_validation`'s doc comment (`options.rs:80-89`), the README "TLS trust (pin-only)" section, the `--require-certificate-validation` CLI flag help (`main.rs:429-431`), and `RustClientDesign.md:202` all tell the user this option will "verify against the system trust roots." The documented behaviour is unreachable; the only working TLS path is CA pinning (`with_ca_file`).
+
+This is masked by the tests: `tls_with_require_certificate_validation_does_not_short_circuit` (`tests/tls.rs`) dials a dead address (`https://127.0.0.1:1`) and only asserts the no-CA guard error does *not* fire — it never reaches a handshake, so the absent-roots defect is invisible to the suite.
+
+**Recommendation:** Either (a) make the strict path actually load system roots — add the `tls-native-roots` (and/or `tls-webpki-roots`) feature to the `tonic` dependency and call `tls = tls.with_native_roots()` (or `.with_enabled_roots()`) in the `require_certificate_validation == true && ca_file.is_none()` branch of `build_tls_config` — and add a test that pins a self-signed cert as a CA and asserts a system-root-only connection to that same server is *rejected* (proving roots are actually consulted); or (b) if loading system roots is intentionally out of scope for v1, correct every doc site (the `with_require_certificate_validation` doc comment, README, CLI flag help, and `RustClientDesign.md`) to state that the strict flag does not currently enable any trust roots and that CA pinning is the only supported TLS path. Option (a) is the better fix because the flag otherwise has no working effect.
+
+**Resolution:** 2026-06-15 — Took option (a). Root cause confirmed: strict-on/no-CA returned a bare `ClientTlsConfig::new()` with zero trust anchors and the crate only enabled tonic `tls-ring`, so the documented "verify against the system trust roots" path could never validate any certificate. Added `tls-native-roots` to the `tonic` features in `Cargo.toml` and refactored `build_tls_config` to compute the trust posture via a new pure `tls_trust_decision` helper returning `TlsTrustDecision::{None,PinnedCa,SystemRoots,RejectNoCa}`; the `SystemRoots` branch now calls `ClientTlsConfig::with_native_roots()` so a cert chaining to an OS-trusted root validates. Corrected every doc site to state the strict flag verifies against OS roots (not a bare self-signed cert, which still needs `with_ca_file`): the `with_require_certificate_validation` doc comment and `build_tls_config` docs (`options.rs`), README "TLS trust" section, and `RustClientDesign.md` "Trust posture"; the CLI flag help was already accurate. TDD: added failing-first unit tests then the fix — `strict_without_ca_uses_system_roots`, `lenient_without_ca_is_rejected`, `pinned_ca_uses_pinned_trust`, `plaintext_needs_no_tls` (in `src/options.rs`). All four cargo commands pass.
+
+### Client.Rust-032
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Design-document adherence |
+| Location | `clients/rust/RustClientDesign.md`; surface in `clients/rust/src/galaxy.rs:281-379` |
+| Status | Resolved |
+
+**Description:** The diff under review adds substantial new public Galaxy SDK surface — `GalaxyClient::browse`, `GalaxyClient::browse_children_raw`, the `BrowseChildrenOptions` filter struct, and the `LazyBrowseNode` lazy walker (`object`, `has_children_hint`, `children`, `is_expanded`, `expand`) — none of which is described in `RustClientDesign.md`. The README was updated with a "Browsing lazily" / "High-level walker" section, but CLAUDE.md requires the design docs to change in the same change as the public API. A reader consulting the detailed design to understand the Galaxy client surface will not learn that lazy browsing, sibling pagination, the `child_has_children` hint, or the idempotent `expand` contract exist.
+
+**Recommendation:** Add a "Lazy browse" subsection to the Galaxy section of `RustClientDesign.md` enumerating `browse`, `browse_children_raw`, `BrowseChildrenOptions` (its filter fields and AND semantics), and `LazyBrowseNode` (the `Arc`-shared clone semantics, the idempotent single-RPC `expand`, the `has_children_hint`, and the internal paged `BrowseChildren` loop with its repeated-page-token guard). Cross-reference `docs/GalaxyRepository.md#browsechildren` for the wire-level request/filter semantics the README already links.
+
+**Resolution:** 2026-06-15 — Confirmed by inspection that `RustClientDesign.md` had no Galaxy library-API coverage at all. Added a new "Galaxy Repository" section documenting `browse`, `browse_children_raw`, the `BrowseChildrenOptions` filter struct (all six fields, AND combination semantics, `include_attributes` tri-state), and `LazyBrowseNode` (`Arc`-shared clone semantics, `has_children_hint`, the idempotent single-RPC `expand` under an async mutex with page size 500, and the repeated-page-token `Error::InvalidArgument` guard), cross-referencing `docs/GalaxyRepository.md#browsechildren`. Also noted the fourth alarm `provider_status` oneof case in the Alarms section while resolving Client.Rust-030. Doc-only change verified by inspection; design-doc anchor target confirmed present.

code-reviews/Contracts/findings.md

@@ -4,8 +4,8 @@
 |---|---|
 | Module | `src/ZB.MOM.WW.MxGateway.Contracts` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |
 
@@ -50,6 +50,43 @@ Python and Go descriptors. No fields renumbered or repurposed.
 | 9 | Testing coverage | No issues found — `ProtobufContractRoundTripTests` and `GatewayContractInfoTests` continue to pin the protocol version; new `QueryActiveAlarmsRequest` lacks a round-trip test but the RPC type is generated and exercised end-to-end by the gRPC client tests in each language. |
 | 10 | Documentation & comments | Issues found: Contracts-017 (the `rpc QueryActiveAlarms` comment block does not mention the `alarm_filter_prefix` request field). |
 
+#### 2026-06-15 re-review (commit 410acc9)
+
+Re-review pass at `410acc9` scoped to the contract changes since `42b0037`
+(`git diff 42b0037..HEAD -- src/ZB.MOM.WW.MxGateway.Contracts/`). The window
+contains two unrelated additive contract features. The brief targets the
+**alarm-provider fallback** surface in `mxaccess_gateway.proto`: the new
+`AlarmProviderMode` enum (`UNSPECIFIED=0`/`ALARMMGR=1`/`SUBTAG=2`), the
+`AlarmSubtagTarget` watch-list message, `AlarmFailoverConfig`, the three new
+`SubscribeAlarmsCommand` fields (`forced_mode=2`, `watch_list=3`, `failover=4`),
+the `OnAlarmProviderModeChangedEvent` (`MxEvent.body` oneof tag 25,
+`MxEventFamily=6`), the `degraded=14`/`source_provider=15` provenance fields on
+`OnAlarmTransitionEvent` **and** `ActiveAlarmSnapshot`, and the
+`AlarmFeedMessage.provider_status=4` oneof case carrying `AlarmProviderStatus`.
+The same window also adds the Galaxy `BrowseChildren` lazy-browse RPC
+(`galaxy_repository.proto`) and three XML doc comments on `GatewayContractInfo`
+constants — both outside the brief's alarm focus but checked for additive-only
+hygiene (clean). `Generated/*.cs` is build output and was not reviewed as
+hand-written. `mxaccess_worker.proto` is unchanged (the alarm additions live in
+the gateway proto the worker imports — matches the design doc's Superseded note).
+
+Verified against `docs/plans/2026-06-13-alarm-subtag-fallback-design.md`,
+`docs/plans/2026-06-15-forced-subtag-mode-fix.md`, and the worker/gateway source
+(`AlarmDispatcher.cs:213`, `MxAccessEventMapper.cs:151`, `GatewayAlarmMonitor.cs`).
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | No issues found. Field semantics are correct against source: `AlarmProviderStatus.degraded`/`OnAlarmTransitionEvent.degraded` track `mode == SUBTAG` (worker `AlarmDispatcher.cs:213` sets `SourceProvider = Degraded ? Subtag : Alarmmgr`; gateway `GatewayAlarmMonitor._providerDegraded = toMode == Subtag`). `OnAlarmProviderModeChangedEvent.hresult` "0 on failback" matches the Auto-mode failover/failback path that emits it; forced mode is seeded gateway-side and emits no worker event, so the comment is not contradicted. |
+| 2 | mxaccessgw conventions | No issues found. The subtag fallback synthesizes events **inside the worker** and marks every synthesized transition `degraded`, satisfying the CLAUDE.md "gateway forwards only worker-emitted events; synthesizing is an explicit opt-in non-parity mode" rule. `snake_case` fields, `PascalCase` messages, the `ALARM_PROVIDER_MODE_`/`MX_EVENT_FAMILY_` enum-prefix discipline, and the top-of-file wire-compatibility policy block (Contracts-005) are all honoured. Generated code regenerated, not hand-edited. |
+| 3 | Concurrency & thread safety | N/A — pure contract definitions plus a static constants class. |
+| 4 | Error handling & resilience | No issues found. The degraded/provider-status surface lets clients distinguish the lower-fidelity subtag feed from the authoritative alarmmgr feed; `AlarmProviderStatus` is emitted on stream open and every switch so late joiners learn the mode. |
+| 5 | Security | No issues found — none of the new fields carry credentials or secrets. `AlarmSubtagTarget` carries only item-address strings. |
+| 6 | Performance & resource management | No issues found. `repeated AlarmSubtagTarget watch_list` is sent once at subscribe time, not per-event; provenance fields are scalars. No hot-path bloat. |
+| 7 | Design-document adherence | No drift. The shipped contract matches `docs/plans/2026-06-13-alarm-subtag-fallback-design.md` (including its Superseded notes: additions in the gateway proto, not the worker proto). |
+| 8 | Code organization & conventions | No issues found. Every addition uses a new, contiguous field number — `SubscribeAlarmsCommand` 2-4, `MxEvent.body` 25, `MxEventFamily` 6, `OnAlarmTransitionEvent`/`ActiveAlarmSnapshot` 14-15, `AlarmFeedMessage.payload` 4 — with no reuse, renumbering, or type narrowing of any existing field. Enum zero-values are `UNSPECIFIED`. Additive-only invariant preserved. |
+| 9 | Testing coverage | Issues found: Contracts-018 — `ProtobufContractRoundTripTests` covers the new `AlarmProviderStatus` (via `AlarmFeedMessage`) and the `OnAlarmTransitionEvent` `degraded`/`source_provider` fields, but has no round-trip coverage for the `ActiveAlarmSnapshot` provenance fields, the `SubscribeAlarmsCommand` extensions (`forced_mode`/`watch_list`/`failover`), or `OnAlarmProviderModeChangedEvent`. |
+| 10 | Documentation & comments | Issues found: Contracts-019 — the `ActiveAlarmSnapshot.degraded`/`source_provider` fields carry no in-proto comment while the byte-identical fields on `OnAlarmTransitionEvent` are documented; and the `AlarmProviderMode` enum doc explains `UNSPECIFIED` only for the `forced_mode` use, not for the provenance (`source_provider`) reuse. |
+
 ## Findings
 
 ### Contracts-001
@@ -341,3 +378,33 @@ additive-only with no reuse, renumbering, or type narrowing.
 Re-review: no new findings. Open finding count remains 0. All seventeen
 recorded Contracts findings (Contracts-001..017) remain closed
 (Resolved / Won't Fix).
+
+### Contracts-018
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `src/ZB.MOM.WW.MxGateway.Tests/Contracts/ProtobufContractRoundTripTests.cs:396` (`ActiveAlarmSnapshot_RoundTripsAllFields`) |
+| Status | Resolved |
+
+**Description:** The alarm-provider fallback feature added several new wire fields to `mxaccess_gateway.proto`. `ProtobufContractRoundTripTests` was extended with `AlarmFeedMessage_RoundTripsProviderStatus` (covers `AlarmProviderStatus` + the `provider_status` oneof case) and `Transition_RoundTripsDegradedProvenance` (covers `OnAlarmTransitionEvent.degraded`/`source_provider`), but three pieces of the new contract surface have no round-trip coverage: (a) `ActiveAlarmSnapshot.degraded` (14) / `source_provider` (15) — `ActiveAlarmSnapshot_RoundTripsAllFields` stops at `OperatorComment` (field 11) and never sets or asserts the two new provenance fields, so a future renumber/type change to them would not be caught; (b) the `SubscribeAlarmsCommand` extensions `forced_mode` (2), `watch_list` (3, `repeated AlarmSubtagTarget`), and `failover` (4, `AlarmFailoverConfig`) — no test exercises these, and the live `forced_mode` enum-drop concern that prompted the `2026-06-15-forced-subtag-mode-fix` investigation is exactly the kind of wire shape prior contract tests have been written to pin; (c) `OnAlarmProviderModeChangedEvent` (the `MxEvent.body` oneof tag 25 / `MxEventFamily=6` worker→gateway event). This is the same class of gap previously flagged for the bulk family (Contracts-007 / Contracts-010): new wire shapes shipped without round-trip pinning.
+
+**Recommendation:** Extend `ActiveAlarmSnapshot_RoundTripsAllFields` (or add a focused test) to set and assert `degraded = true` + `source_provider = AlarmProviderMode.Subtag`; add a round-trip test for `SubscribeAlarmsCommand` populating `forced_mode`, a `watch_list` entry (all six `AlarmSubtagTarget` string fields), and a `failover` `AlarmFailoverConfig`; and add a round-trip / `MxEvent` oneof-case test for `OnAlarmProviderModeChangedEvent` pinning `MxEvent.BodyCase == OnAlarmProviderModeChanged` for `MxEventFamily.OnAlarmProviderModeChanged`.
+
+**Resolution:** _(2026-06-15)_ Verified the three coverage gaps against the proto — `ActiveAlarmSnapshot.degraded`/`source_provider` (14/15), `SubscribeAlarmsCommand.forced_mode`/`watch_list`/`failover` (2/3/4), and the `MxEvent.body` oneof tag 25 / `MxEventFamily=6` `OnAlarmProviderModeChangedEvent` were all unpinned. Added three focused round-trip tests to `ProtobufContractRoundTripTests`: `ActiveAlarmSnapshot_RoundTripsDegradedProvenance` (sets/asserts `degraded = true` + `source_provider = AlarmProviderMode.Subtag`), `SubscribeAlarmsCommand_RoundTripsForcedModeWatchListAndFailover` (populates `forced_mode`, a `watch_list` entry with all six `AlarmSubtagTarget` string fields, and a `failover` `AlarmFailoverConfig`), and `MxEvent_RoundTripsOnAlarmProviderModeChangedBody` (pins `MxEvent.BodyCase == OnAlarmProviderModeChanged` + `Family == OnAlarmProviderModeChanged`). All fields round-trip — no contract bug found. The full `ProtobufContractRoundTrip` filter is 49/49 green.
+
+### Contracts-019
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto:850-851` (`ActiveAlarmSnapshot`), `:318-324` (`AlarmProviderMode`) |
+| Status | Resolved |
+
+**Description:** Two in-proto documentation gaps on the new alarm-provider surface. (1) `OnAlarmTransitionEvent.degraded` (line 805-808) and `source_provider` (809-810) carry clear comments ("True when this transition came from the subtag-monitoring fallback … synthesized from data changes, reduced fidelity"; "Which provider produced this transition."), but the byte-identical `ActiveAlarmSnapshot.degraded` (850) and `source_provider` (851) are declared bare with no comment. The two messages model the same provenance concept and a reader of `ActiveAlarmSnapshot` alone gets no signal that a non-`UNSPECIFIED` `source_provider` plus `degraded = true` means the snapshot came from the lower-fidelity subtag source. (2) The `AlarmProviderMode` enum comment (318-319) documents the zero value only for one use site — "UNSPECIFIED on a SubscribeAlarmsCommand means auto: alarmmgr primary with subtag fallback" — but the same enum is reused as a provenance field on `OnAlarmTransitionEvent.source_provider`, `ActiveAlarmSnapshot.source_provider`, `OnAlarmProviderModeChangedEvent.mode`, and `AlarmProviderStatus.mode`. The worker always sets `source_provider` to `ALARMMGR` or `SUBTAG` (never `UNSPECIFIED`; `MxAccessEventMapper.cs:151` defaults to `Alarmmgr`, `AlarmDispatcher.cs:213` picks `Subtag`/`Alarmmgr`), so `UNSPECIFIED` as a provenance value has no defined meaning and the comment does not say so. The ProtobufStyleGuide rule "comment fields carrying MXAccess parity / non-obvious semantics" applies — this is a non-parity provenance marker.
+
+**Recommendation:** (1) Add comments to `ActiveAlarmSnapshot.degraded` / `source_provider` mirroring the wording already on `OnAlarmTransitionEvent` (or a one-line cross-reference). (2) Extend the `AlarmProviderMode` enum comment to note that as a `source_provider` / `mode` provenance value the field is always `ALARMMGR` or `SUBTAG` on the wire and `UNSPECIFIED` should be treated as "unknown / not yet determined", so the zero value is unambiguous at every use site. Comment-only changes; no wire-format impact.
+
+**Resolution:** _(2026-06-15)_ Confirmed both gaps in `mxaccess_gateway.proto`: `ActiveAlarmSnapshot.degraded`/`source_provider` (14/15) were bare while the byte-identical `OnAlarmTransitionEvent` fields were documented, and the `AlarmProviderMode` enum comment only explained `UNSPECIFIED` for the `forced_mode` use. (1) Added comments to `ActiveAlarmSnapshot.degraded`/`source_provider` mirroring the `OnAlarmTransitionEvent` wording (subtag-fallback / reduced-fidelity, always ALARMMGR or SUBTAG, never UNSPECIFIED). (2) Extended the `AlarmProviderMode` enum comment to distinguish its two use sites: as `forced_mode`, `UNSPECIFIED` = auto; as a provenance value (`OnAlarmTransitionEvent.source_provider`, `ActiveAlarmSnapshot.source_provider`, `OnAlarmProviderModeChangedEvent.mode`, `AlarmProviderStatus.mode`) the worker always emits ALARMMGR/SUBTAG and `UNSPECIFIED` should be read as "unknown / not yet determined". Comment-only changes; no wire-format impact. NOTE: on this dev box the `csharp` protoc generator DOES emit proto leading comments into `Generated/MxaccessGateway.cs` `<summary>` XML doc (contrary to the brief's assumption), so the build regenerated `Generated/MxaccessGateway.cs` with the new doc comments only — diff is `///`-comment lines exclusively, zero code/wire/type changes. `dotnet build -f net10.0` succeeds with 0 warnings / 0 errors.

code-reviews/IntegrationTests/findings.md

@@ -4,8 +4,8 @@
 |---|---|
 | Module | `src/ZB.MOM.WW.MxGateway.IntegrationTests` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |
 
@@ -14,6 +14,34 @@
 A comprehensive review completes every category, recording "No issues found" where
 a category produced nothing rather than leaving it blank.
 
+### 2026-06-15 re-review (commit `410acc9`)
+
+Scope: `git diff 42b0037..HEAD -- src/ZB.MOM.WW.MxGateway.IntegrationTests/`
+(5 files). The substantive change is the `DashboardLdapLiveTests` cutover to the
+shared `ZB.MOM.WW.Auth.Ldap.LdapAuthService` + `DashboardGroupRoleMapper`
+(matching the production `DashboardAuthenticator` ctor split); plus the
+`ResolveRepositoryRoot` `stopBoundary` parameter and its new regression test
+(IntegrationTests-025 resolution), and XML-doc backfill on
+`LiveLdapFactAttribute` / `WorkerLiveMxAccessSmokeTests`. NOTE: the review
+brief's "live alarm-subtag smoke test(s)" do not exist in this diff — no new
+alarm-subtag tests landed here. Instead the in-window Server alarm-monitor
+evolution (`ebf1d95`/`9208225`/`410acc9`) changed `GatewayAlarmMonitor`'s
+constructor without updating its IntegrationTests caller, leaving the whole
+module non-compiling (IntegrationTests-026).
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issue found: IntegrationTests-026 (the entire IntegrationTests project fails to compile at HEAD — `WorkerLiveMxAccessSmokeTests` constructs `GatewayAlarmMonitor` with the stale 3-arg form `(sessionManager, options, logger)` while the production ctor now requires 5 args `(ISessionManager, IAlarmWatchListResolver, GatewayMetrics, IOptions<GatewayOptions>, ILogger)`; verified by `dotnet build` → CS7036). |
+| 2 | mxaccessgw conventions | No issues found. Live opt-in gating, `[Collection]`/`[Trait]` discipline, "no synthesized events", and the credential-redaction contract for the LDAP failure-path assertions are all preserved; the cutover keeps the existing skip-by-default behaviour. |
+| 3 | Concurrency & thread safety | No issues found in this diff. |
+| 4 | Error handling & resilience | No issues found. The `ServerUnreachable` test still asserts the connect failure is absorbed into a `Fail` result; the fail-closed contract now lives in the shared `LdapAuthService` and the test exercises it via `Port = 1`. |
+| 5 | Security | No issues found. The wrong-password / unknown-user / unreachable tests still assert no credential leak into `FailureMessage`; the cutover adds no new credential surface and writes no secrets to evidence/probe logs. |
+| 6 | Performance & resource management | No issues found. |
+| 7 | Design-document adherence | Issue found: IntegrationTests-028 (the live test hand-rolls a field-by-field `LibraryLdapOptions` from the gateway shadow `LdapOptions` defaults instead of binding `MxGateway:Ldap` the way production's `AddZbLdapAuth(configuration, "MxGateway:Ldap")` does, so the live test no longer exercises the production option-binding path and silently omits `ConnectionTimeoutMs` / `ServerCertificateValidationCallback`). |
+| 8 | Code organization & conventions | Issue found: IntegrationTests-027 (`DashboardLdapLiveTests` directly consumes `LdapAuthService` / `LdapOptions` from `ZB.MOM.WW.Auth.Ldap` but the IntegrationTests `.csproj` has no direct `PackageReference` — it compiles only via transitive flow through the Server `ProjectReference`). |
+| 9 | Testing coverage | No issues found beyond IntegrationTests-026 — the role-claim and stop-boundary assertions added in this window strengthen coverage; but the module cannot build, so none of the IntegrationTests run until IntegrationTests-026 is fixed. |
+| 10 | Documentation & comments | Issue found: IntegrationTests-029 (`docs/GatewayTesting.md` "Live LDAP" still describes the old in-`DashboardAuthenticator` branches — "rejected by the candidate bind", "yields no candidate" — that the library cutover moved into the shared `LdapAuthService`; the test comments were updated in this diff but the doc prose was not, contrary to CLAUDE.md's same-commit doc rule). |
+
 ### 2026-05-20 re-review (commit `a020350`)
 
 | # | Category | Result |
@@ -506,3 +534,77 @@ The current dev box layout (`C:\Users\dohertj2\Desktop\mxaccessgw`) is safe beca
 **Recommendation:** Isolate the walker from any ambient ancestor by either (a) constructing an `isolatedRoot` directly under a drive root and pointing the walker at a chain entirely under it (e.g. create `<isolatedRoot>\level1\level2\level3` and start the walk at `level3`, then assert the throw — the walker stops at the drive root regardless of what is on it), (b) refactoring `ResolveRepositoryRoot` to accept an injectable `stopBoundary` parameter for tests and pass `isolatedRoot` as the boundary, or (c) replacing the `Assert.Throws` shape with an explicit upward-walk check that the test owns. Option (a) is the smallest change: prepend a sentinel — e.g. create a dummy `<isolatedRoot>\sentinel-no-markers` and assert nothing about Temp ancestors — and pass the test only when the walker reaches that sentinel without finding a marker. The current shape is acceptable on the documented dev box but should not be the sole regression coverage for IntegrationTests-022.
 
 **Resolution:** Resolved 2026-05-24 — Took option (b) (inject a stop-boundary) because option (a) does not actually solve the leak: a sentinel chain under `Path.GetTempPath()` still leaves the walker free to ascend past it into Temp / AppData / Users / C:\, so any ambient ancestor with `src/` + `.git`/`.sln`/`.slnx` still wins. Added an optional `stopBoundary` parameter to `IntegrationTestEnvironment.ResolveRepositoryRoot(string startDirectory, string? stopBoundary = null)`. When supplied, the walker checks the boundary for markers and then stops, refusing to ascend past it; production callers (the `MXGATEWAY_LIVE_MXACCESS_WORKER_EXE` resolution path) continue to pass `null` so the walk to drive-root behavior is unchanged. Updated both existing tests (`ResolveRepositoryRoot_AcceptsGitWorktreeFile` and `ResolveRepositoryRoot_NoMarkers_ThrowsInvalidOperationExceptionNamingStartAndMarkers`) to pass their owned temp directory as the boundary, sealing the walker inside a chain the test fully controls. Added a new regression test `ResolveRepositoryRoot_StopBoundary_IsolatesWalkerFromAmbientAncestorMarkers` that deliberately constructs an outer marker-bearing ancestor (`outerRoot/src` + `outerRoot/.git`), an inner boundary, and an isolated start beneath the boundary; first asserts that without the boundary the walker leaks up to `outerRoot` (the precise IntegrationTests-025 failure mode), then asserts that *with* the boundary the same call throws — proving the boundary is the load-bearing isolation. TDD red/green confirmed: the new regression test fails against the pre-fix walker (`Assert.Throws() Failure: No exception was thrown`) and passes once the boundary handling is restored. Re-ran the full `IntegrationTestEnvironmentTests` slice with `TMP` / `TEMP` redirected under a deliberately constructed `<temp>\fake-repo-ancestor` directory carrying `src/` and a `.git` file — the original flake repro from the finding — and confirmed all 5 tests pass (the same redirection produced `Assert.Throws() Failure` on the pre-fix code). Build: 0 warnings / 0 errors.
+
+### IntegrationTests-026
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Correctness & logic bugs |
+| Location | `src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:1098-1101`, `src/ZB.MOM.WW.MxGateway.Server/Alarms/GatewayAlarmMonitor.cs:55-60` |
+| Status | Resolved |
+
+**Description:** The entire IntegrationTests project fails to compile at HEAD (`410acc9`). `GatewayServiceFixture` (in `WorkerLiveMxAccessSmokeTests.cs`) constructs the `GatewayAlarmMonitor` it passes into `MxAccessGatewayService` with the stale three-argument form:
+
+```csharp
+new ZB.MOM.WW.MxGateway.Server.Alarms.GatewayAlarmMonitor(
+    sessionManager,
+    options,
+    _loggerFactory.CreateLogger<...GatewayAlarmMonitor>())
+```
+
+but the production constructor (evolved in-window by `ebf1d95` "monitor resolves watch-list, sends ForcedMode/failover, reflects provider mode into feed + metrics", with later refinements in `9208225` and `410acc9`) now requires **five** parameters: `GatewayAlarmMonitor(ISessionManager sessionManager, IAlarmWatchListResolver watchListResolver, GatewayMetrics metrics, IOptions<GatewayOptions> options, ILogger<GatewayAlarmMonitor> logger)`. `dotnet build src/ZB.MOM.WW.MxGateway.IntegrationTests/...` fails with `CS7036: There is no argument given that corresponds to the required parameter 'options'`. Because this is the only `MxAccessGatewayService` assembly site in the fixture, the whole module — every live opt-in test *and* the non-live `IntegrationTestEnvironmentTests` — cannot build or run. This is a CLAUDE.md "Source Update Workflow" violation: a cross-component Server alarm-monitor change was not propagated to its IntegrationTests caller in the same commit, and "build each affected component" was not honored for the IntegrationTests project. It also silently masks the verification basis for IntegrationTests-022..025's "build is green" resolution claims at this HEAD.
+
+**Recommendation:** Update the `GatewayAlarmMonitor` construction in `GatewayServiceFixture` to the current 5-arg signature: supply an `IAlarmWatchListResolver` (a minimal test stub returning an empty/representative watch list, or the production resolver if cheap to construct), the existing `_metrics` (`GatewayMetrics`), the existing `options` wrapped as `IOptions<GatewayOptions>` (e.g. `Options.Create(...)`), and the logger. Then run `dotnet build src/ZB.MOM.WW.MxGateway.IntegrationTests/...` to confirm 0 errors and `dotnet test ... --filter FullyQualifiedName~IntegrationTestEnvironmentTests` to confirm the non-live tests pass and the live tests still skip cleanly when the env vars are unset. Add a build of the IntegrationTests project to the verification step whenever `GatewayAlarmMonitor` / `MxAccessGatewayService` constructors change.
+
+**Resolution:** Resolved 2026-06-15: Confirmed the project failed to build at HEAD (CS7036 on the stale 3-arg `GatewayAlarmMonitor` ctor call in `GatewayServiceFixture`). Updated the construction to the current 5-arg signature — added a new `TestSupport/EmptyAlarmWatchListResolver` singleton stub (`IAlarmWatchListResolver` returning an empty watch-list, avoiding the production resolver's `IGalaxyRepository` dependency), and passed the fixture's existing `_metrics` (`GatewayMetrics`) and `options` (`IOptions<GatewayOptions>`). `dotnet build` now succeeds with 0 errors/warnings; non-live tests pass (5) and all 15 live tests skip cleanly with the env vars unset.
+
+### IntegrationTests-027
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `src/ZB.MOM.WW.MxGateway.IntegrationTests/ZB.MOM.WW.MxGateway.IntegrationTests.csproj`, `src/ZB.MOM.WW.MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:4-5,134` |
+| Status | Resolved |
+
+**Description:** After the cutover, `DashboardLdapLiveTests` directly consumes `ZB.MOM.WW.Auth.Ldap.LdapAuthService` and `ZB.MOM.WW.Auth.Abstractions.Ldap.LdapOptions` (`using ZB.MOM.WW.Auth.Ldap; using ZB.MOM.WW.Auth.Abstractions.Ldap;` and `new LdapAuthService(ldapOptions)`). But the IntegrationTests `.csproj` declares no direct `PackageReference` to `ZB.MOM.WW.Auth.Ldap` or `ZB.MOM.WW.Auth.Abstractions` — it has only `ProjectReference`s to Contracts and Server. It compiles solely because the Server's `PackageReference`s to those packages flow transitively (the Server csproj sets no `PrivateAssets`). A project that directly references a library's public types should declare a direct dependency on it; the current shape means the build silently depends on the Server never marking those packages `PrivateAssets="compile"` and on the transitive compile-asset flow staying enabled. If either changes, the IntegrationTests build breaks with a confusing CS0246 far from the cause.
+
+**Recommendation:** Add explicit `<PackageReference Include="ZB.MOM.WW.Auth.Ldap" Version="0.1.2" />` and `<PackageReference Include="ZB.MOM.WW.Auth.Abstractions" Version="0.1.2" />` (matching the Server's pinned versions, ideally via a shared `Directory.Packages.props` if central package management is in use) to the IntegrationTests project so its direct use of those types is backed by a direct dependency.
+
+**Resolution:** Resolved 2026-06-15: Confirmed the csproj had only `ProjectReference`s and pulled `LdapAuthService`/`LdapOptions` transitively. Added direct `PackageReference`s `ZB.MOM.WW.Auth.Abstractions` and `ZB.MOM.WW.Auth.Ldap` at `0.1.2` (matching the Server's pinned versions; no central package management exists in this repo). Build remains clean. (The IntegrationTests-028 fix also added `Microsoft.Extensions.Configuration.Json`/`.Binder` at `10.0.7`, pinned to the resolved transitive version to avoid an NU1605 downgrade.)
+
+### IntegrationTests-028
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Design-document adherence |
+| Location | `src/ZB.MOM.WW.MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:120-161`, `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardServiceCollectionExtensions.cs:35` |
+| Status | Resolved |
+
+**Description:** Production wires the shared LDAP provider by binding the `MxGateway:Ldap` configuration section straight onto the shared `LdapOptions` via `AddZbLdapAuth(configuration, "MxGateway:Ldap")`. The live test instead hand-rolls a `LibraryLdapOptions` instance by copying the eleven fields of the gateway *shadow* `LdapOptions` defaults (the `LibraryOptions()` helper). Two consequences:
+
+1. The shared `LdapOptions` actually exposes **thirteen** settable properties — the hand-copy omits `ConnectionTimeoutMs` and `ServerCertificateValidationCallback` (verified by reflecting `ZB.MOM.WW.Auth.Abstractions` 0.1.2). `ConnectionTimeoutMs` has a non-zero default and directly governs the `AuthenticateAsync_ServerUnreachable_FailsWithoutThrowing` (`Port = 1`) test's timing, so the live test exercises the *shared default* timeout, not whatever an operator (or the gateway config) would set — diverging from the production-bound value.
+2. It adds a third manual copy of the shadow→shared field mapping on top of the documented "Review C2 DRIFT WARNING" seam in `Server/Configuration/LdapOptions.cs`. A field added to the shared type is silently dropped by this test until someone remembers to extend `LibraryOptions()`.
+
+The prior `DashboardAuthenticator` ctor took `IOptions<GatewayOptions>`, so the old test shared the same options object production used; the cutover lost that fidelity. CLAUDE.md treats the live tests as the parity check against the real seeded directory — they should bind options the way production does.
+
+**Recommendation:** Have the test build the shared `LdapOptions` the same way production does — bind it from the `MxGateway:Ldap` section (e.g. load the gateway `appsettings.json` / a minimal in-memory config and call the same `AddZbLdapAuth` binding path, or resolve the bound `IOptions<LdapOptions>` from a DI container that ran `AddZbLdapAuth`). At minimum, document why the two extra shared fields are intentionally left at their defaults, and add `ConnectionTimeoutMs` to the copy so the unreachable-server test's timeout matches production. Prefer eliminating the hand-copy so the shadow-drift surface does not grow.
+
+**Resolution:** Resolved 2026-06-15: Confirmed by reflecting `ZB.MOM.WW.Auth.Abstractions` 0.1.2 that the shared `LdapOptions` exposes 13 settable properties while the hand-copy populated only 11 (omitting `ConnectionTimeoutMs` and `ServerCertificateValidationCallback`). Eliminated the field-by-field hand-copy: `LibraryOptions()` now binds the real `MxGateway:Ldap` section from the Server's `appsettings.json` (resolved via `IntegrationTestEnvironment.ResolveRepositoryRoot`) onto the shared `LdapOptions` with `configuration.GetSection("MxGateway:Ldap").Get<LdapOptions>()` — the same section/binding path production's `AddZbLdapAuth(configuration, "MxGateway:Ldap")` uses. Verified the bind yields `ConnectionTimeoutMs=10000` (the shared default the unreachable-server test relies on) and the dev directory connection (localhost:3893, Transport=None, AllowInsecure). A new shared field is now picked up automatically rather than silently dropped.
+
+### IntegrationTests-029
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `docs/GatewayTesting.md:218-224` |
+| Status | Resolved |
+
+**Description:** The "Live LDAP" section of `docs/GatewayTesting.md` still describes the failure branches in terms of the old `DashboardAuthenticator` internals: "`admin` with a wrong password is rejected by the **candidate bind**" and "an unknown username yields **no candidate**". After the cutover in this diff, the bind/search mechanics (and therefore the "candidate bind" / "candidate is null" branches) live in the shared `LdapAuthService`, not in `DashboardAuthenticator` — which is exactly why the test comments in `DashboardLdapLiveTests.cs` were reworded in this same diff from "Exercises the `LdapException` branch" / "the `candidate is null` branch" to "user-bind-failure branch" / "user-not-found branch". The doc prose was not updated to match. CLAUDE.md requires docs that describe security/auth behavior to change in the same commit as the source; the comments moved but the doc did not, leaving the doc describing branches that no longer exist in `DashboardAuthenticator`.
+
+**Recommendation:** Reword the `docs/GatewayTesting.md` "Live LDAP" failure-branch sentences to describe observable behavior without referencing the now-internal "candidate bind" mechanics (e.g. "a wrong password is rejected without leaking the password", "an unknown username fails authentication"), and note that bind/search is delegated to the shared `ZB.MOM.WW.Auth.Ldap` provider so the prose stays accurate after the cutover.
+
+**Resolution:** Resolved 2026-06-15: Reworded the "Live LDAP" failure-branch prose to describe observable behavior ("fails authentication without leaking the password", "an unknown username fails authentication") instead of the now-internal "candidate bind" / "no candidate" mechanics, and added a sentence noting `DashboardAuthenticator` delegates the bind/search to the shared `ZB.MOM.WW.Auth.Ldap` provider (`LdapAuthService`) and only maps groups to roles — matching the in-source test-comment cutover. Verified by inspection.

code-reviews/README.md

@@ -10,17 +10,17 @@ Each module's `findings.md` is the source of truth; this file is generated from
 
 | Module | Reviewer | Date | Commit | Status | Open | Total |
 |---|---|---|---|---|---|---|
-| [Client.Dotnet](Client.Dotnet/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 21 |
-| [Client.Go](Client.Go/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 27 |
-| [Client.Java](Client.Java/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 36 |
-| [Client.Python](Client.Python/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 26 |
-| [Client.Rust](Client.Rust/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 29 |
-| [Contracts](Contracts/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 17 |
-| [IntegrationTests](IntegrationTests/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 25 |
-| [Server](Server/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 50 |
-| [Tests](Tests/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 31 |
-| [Worker](Worker/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 25 |
-| [Worker.Tests](Worker.Tests/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 30 |
+| [Client.Dotnet](Client.Dotnet/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 25 |
+| [Client.Go](Client.Go/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 29 |
+| [Client.Java](Client.Java/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 39 |
+| [Client.Python](Client.Python/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 31 |
+| [Client.Rust](Client.Rust/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 32 |
+| [Contracts](Contracts/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 19 |
+| [IntegrationTests](IntegrationTests/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 29 |
+| [Server](Server/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 53 |
+| [Tests](Tests/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 35 |
+| [Worker](Worker/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 28 |
+| [Worker.Tests](Worker.Tests/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 33 |
 
 ## Pending findings
 
@@ -38,6 +38,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Go-001 | High | Resolved | Correctness & logic bugs | `clients/go/mxgateway/errors.go:88-93`, `clients/go/mxgateway/errors.go:117-128` |
 | Client.Java-013 | High | Resolved | Testing coverage | `clients/java/mxgateway-cli/src/test/java/com/dohertylan/mxgateway/cli/MxGatewayCliTests.java:212-304`, `clients/java/mxgateway-cli/src/main/java/com/dohertylan/mxgateway/cli/MxGatewayCli.java:1214-1244` |
 | Client.Java-032 | High | Resolved | Documentation & comments | `clients/java/README.md:182-183` |
+| Client.Java-039 | High | Resolved | Correctness & logic bugs | `clients/java/zb-mom-ww-mxgateway-cli/src/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java:1699` (origin: `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto`, `AlarmFeedMessage.payload` provider-status arm added in commit `1d85db7`) |
 | Client.Python-018 | High | Resolved | Code organization & conventions | `clients/python/pyproject.toml:11` |
 | Client.Python-022 | High | Resolved | Documentation & comments | `clients/python/README.md:201-202`, `clients/python/src/zb_mom_ww_mxgateway_cli/commands.py:389-420` |
 | Client.Rust-001 | High | Resolved | mxaccessgw conventions | `clients/rust/src/options.rs:98,143` |
@@ -46,8 +47,10 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Rust-012 | High | Resolved | mxaccessgw conventions | `clients/rust/src/galaxy.rs:282` |
 | Client.Rust-013 | High | Resolved | mxaccessgw conventions | `src/MxGateway.Contracts/Protos/mxaccess_gateway.proto:414-424` (origin); `clients/rust/src/generated.rs:11-31` (suppression site) |
 | Client.Rust-029 | High | Resolved | mxaccessgw conventions | `clients/rust/src/options.rs:98,143`; `clients/rust/src/galaxy.rs:282`; `clients/rust/src/session.rs:664-671` |
+| Client.Rust-030 | High | Resolved | Correctness & logic bugs | `clients/rust/crates/mxgw-cli/src/main.rs:1731,1757` (origin: `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto:909-924`, added in commit `1d85db7`) |
 | IntegrationTests-001 | High | Resolved | Design-document adherence | `src/MxGateway.IntegrationTests/Galaxy/LiveGalaxyRepositoryFactAttribute.cs:7`, `src/MxGateway.IntegrationTests/Galaxy/GalaxyRepositoryLiveTests.cs` |
 | IntegrationTests-002 | High | Resolved | Design-document adherence | `src/MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:13`, `src/MxGateway.Server/Configuration/LdapOptions.cs:27` |
+| IntegrationTests-026 | High | Resolved | Correctness & logic bugs | `src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:1098-1101`, `src/ZB.MOM.WW.MxGateway.Server/Alarms/GatewayAlarmMonitor.cs:55-60` |
 | Server-003 | High | Resolved | Security | `src/MxGateway.Server/Dashboard/DashboardAuthorizationHandler.cs:39,54-59`, `src/MxGateway.Server/Dashboard/DashboardAuthenticator.cs:236-258` |
 | Server-017 | High | Resolved | Security | `src/MxGateway.Server/Security/Authorization/GatewayGrpcScopeResolver.cs:13-27`, `src/MxGateway.Server/Grpc/MxAccessGatewayService.cs:173-247`, `docs/Authorization.md:108-110` |
 | Tests-001 | High | Resolved | Testing coverage | `src/MxGateway.Tests/Gateway/Grpc/MxAccessGatewayServiceTests.cs:483-489` |
@@ -55,16 +58,19 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Worker-001 | High | Resolved | Concurrency & thread safety | `src/MxGateway.Worker/MxAccess/WnWrapAlarmConsumer.cs:204-207` |
 | Worker-002 | High | Resolved | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:545-549` |
 | Worker-003 | High | Resolved | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:399-403`, `:416-419` |
+| Worker-026 | High | Resolved | Concurrency & thread safety | `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/FailoverAlarmConsumer.cs:289-338`, `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs:307-320` |
 | Worker.Tests-001 | High | Resolved | Testing coverage | `src/MxGateway.Worker.Tests/Sta/` (no `StaMessagePumpTests.cs`) |
 | Worker.Tests-002 | High | Resolved | Testing coverage | `src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs`, `src/MxGateway.Worker.Tests/MxAccess/MxAccessEventMapperTests.cs` |
 | Client.Dotnet-001 | Medium | Resolved | Error handling & resilience | `clients/dotnet/MxGateway.Client/GrpcMxGatewayClientTransport.cs:190-199`, `clients/dotnet/MxGateway.Client/GrpcGalaxyRepositoryClientTransport.cs:131-140` |
 | Client.Dotnet-002 | Medium | Resolved | Testing coverage | `clients/dotnet/MxGateway.Client.Tests/FakeGatewayTransport.cs:145-148`, `clients/dotnet/MxGateway.Client.Tests/MxGatewayClientSessionTests.cs:236-256` |
 | Client.Dotnet-003 | Medium | Resolved | Concurrency & thread safety | `clients/dotnet/MxGateway.Client/MxGatewaySession.cs:659-663`, `clients/dotnet/MxGateway.Client/MxGatewayClient.cs:230-240` |
 | Client.Dotnet-018 | Medium | Resolved | Documentation & comments | `clients/dotnet/README.md:137-138` |
+| Client.Dotnet-022 | Medium | Resolved | mxaccessgw conventions | `clients/dotnet/Directory.Build.props:1-21` |
 | Client.Go-002 | Medium | Resolved | Error handling & resilience | `clients/go/mxgateway/session.go:440-516` |
 | Client.Go-003 | Medium | Resolved | Correctness & logic bugs | `clients/go/cmd/mxgw-go/main.go:517-532` |
 | Client.Go-022 | Medium | Resolved | Code organization & conventions | `clients/go/cmd/mxgw-go/main.go:398-412,417-519` |
 | Client.Go-023 | Medium | Resolved | Concurrency & thread safety | `clients/go/cmd/mxgw-go/main.go:604-606,616-632` |
+| Client.Go-028 | Medium | Resolved | Correctness & logic bugs | `scripts/tag-go-module.ps1:42-46` |
 | Client.Java-001 | Medium | Resolved | Security | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewaySecrets.java:30-32` |
 | Client.Java-002 | Medium | Resolved | Concurrency & thread safety | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxEventStream.java:31,66-92` |
 | Client.Java-003 | Medium | Resolved | mxaccessgw conventions | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:119-140` |
@@ -77,12 +83,15 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Java-028 | Medium | Resolved | Documentation & comments | `clients/java/JavaClientDesign.md:23-27` |
 | Client.Java-033 | Medium | Resolved | Correctness & logic bugs | `clients/java/zb-mom-ww-mxgateway-cli/src/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java:1078-1098` |
 | Client.Java-034 | Medium | Resolved | Correctness & logic bugs | `clients/java/zb-mom-ww-mxgateway-cli/src/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java:182-198` |
+| Client.Java-037 | Medium | Resolved | Documentation & comments | `clients/java/README.md:138-149` |
 | Client.Python-003 | Medium | Resolved | Error handling & resilience | `clients/python/src/mxgateway/client.py:125-137,155-173` |
 | Client.Python-005 | Medium | Resolved | Performance & resource management | `clients/python/src/mxgateway/galaxy.py:117-140` |
 | Client.Python-009 | Medium | Resolved | Testing coverage | `clients/python/tests/` |
 | Client.Python-013 | Medium | Resolved | Security | `clients/python/src/mxgateway_cli/commands.py:757-762` |
 | Client.Python-023 | Medium | Resolved | Security | `clients/python/src/zb_mom_ww_mxgateway_cli/commands.py:901-906` |
 | Client.Python-024 | Medium | Resolved | Code organization & conventions | `clients/python/src/zb_mom_ww_mxgateway_cli/commands.py:13,48-119` |
+| Client.Python-027 | Medium | Resolved | Security | `clients/python/src/zb_mom_ww_mxgateway/client.py:36-54`, `clients/python/src/zb_mom_ww_mxgateway/galaxy.py:47-66`, `clients/python/src/zb_mom_ww_mxgateway_cli/commands.py:165-172,918-930` |
+| Client.Python-028 | Medium | Resolved | Error handling & resilience | `clients/python/src/zb_mom_ww_mxgateway/options.py:120-130`, `clients/python/src/zb_mom_ww_mxgateway/client.py:59`, `clients/python/src/zb_mom_ww_mxgateway/galaxy.py:71` |
 | Client.Rust-005 | Medium | Resolved | Correctness & logic bugs | `clients/rust/src/session.rs:489-520` |
 | Client.Rust-006 | Medium | Resolved | Error handling & resilience | `clients/rust/src/session.rs:531-555` |
 | Client.Rust-015 | Medium | Resolved | Error handling & resilience | `clients/rust/crates/mxgw-cli/src/main.rs:1053-1070` |
@@ -90,6 +99,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Rust-018 | Medium | Resolved | Error handling & resilience | `clients/rust/crates/mxgw-cli/src/main.rs:1098-1170`; `scripts/bench-read-bulk.ps1:347-365`; siblings: `clients/go/cmd/mxgw-go/main.go:600-648`, `clients/python/src/mxgateway_cli/commands.py:614-662`, `clients/dotnet/MxGateway.Client.Cli/MxGatewayClientCli.cs:685-770`, `clients/java/mxgateway-cli/src/main/java/com/dohertylan/mxgateway/cli/MxGatewayCli.java:855-940` |
 | Client.Rust-022 | Medium | Resolved | Correctness & logic bugs | `clients/rust/src/session.rs:369-391,403-420,427-444,452-469,476-493,631-696,706-724` |
 | Client.Rust-024 | Medium | Resolved | Testing coverage | `clients/rust/tests/client_behavior.rs:405-415`; `clients/rust/src/session.rs:369-493`; `clients/rust/src/client.rs:265-291`; `clients/rust/crates/mxgw-cli/src/main.rs:1310-1505` |
+| Client.Rust-031 | Medium | Resolved | Error handling & resilience | `clients/rust/src/options.rs:196-240` (`build_tls_config`); `clients/rust/Cargo.toml:40` (tonic features); docs: `clients/rust/src/options.rs:76-101`, `clients/rust/README.md` (TLS trust section), `clients/rust/crates/mxgw-cli/src/main.rs:429-431`, `clients/rust/RustClientDesign.md:202` |
 | Contracts-002 | Medium | Resolved | Error handling & resilience | `src/MxGateway.Contracts/Protos/mxaccess_gateway.proto:384-385`, `:95` |
 | Contracts-009 | Medium | Resolved | Design-document adherence | `docs/Contracts.md:13-24` |
 | IntegrationTests-003 | Medium | Resolved | Correctness & logic bugs | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:89-97` |
@@ -113,6 +123,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | 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`) |
 | Server-038 | Medium | Resolved | Security | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Hubs/EventsHub.cs:23-44` |
 | Server-044 | Medium | Resolved | Correctness & logic bugs | `src/ZB.MOM.WW.MxGateway.Server/Sessions/SessionManager.cs:216-254` |
+| Server-051 | Medium | Resolved | Error handling & resilience | `src/ZB.MOM.WW.MxGateway.Server/Alarms/AlarmWatchListResolver.cs:64-78` |
 | 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` |
@@ -122,6 +133,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Tests-020 | Medium | Resolved | Testing coverage | `src/MxGateway.Tests/Gateway/Grpc/MxAccessGatewayServiceConstraintTests.cs:275-347`, `src/MxGateway.Server/Grpc/MxAccessGatewayService.cs:803-829` |
 | Tests-026 | Medium | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Grpc/EventStreamServiceTests.cs`, `src/ZB.MOM.WW.MxGateway.Server/Grpc/EventStreamService.cs:123-126` |
 | Tests-027 | Medium | Resolved | Concurrency & thread safety | `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Grpc/MxAccessGatewayServiceTests.cs:199-240`, `src/ZB.MOM.WW.MxGateway.Server/Metrics/GatewayMetrics.cs:8,73,246-251` |
+| Tests-032 | Medium | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Server/Alarms/GatewayAlarmMonitor.cs:435-441`, `src/ZB.MOM.WW.MxGateway.Tests/Alarms/GatewayAlarmMonitorProviderModeTests.cs`, `src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmFailoverEndToEndTests.cs` |
 | Worker-004 | Medium | Resolved | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:565-588` |
 | Worker-005 | Medium | Resolved | Error handling & resilience | `src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs:205-258` (production alarm poll loop) |
 | Worker-006 | Medium | Resolved | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:117-124`, `src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs:386-491` |
@@ -130,6 +142,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Worker-016 | Medium | Resolved | Concurrency & thread safety | `src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs:261-265` |
 | Worker-017 | Medium | Resolved | Error handling & resilience | `src/MxGateway.Worker/Sta/StaRuntime.cs:280-288`, `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:602-631` |
 | Worker-023 | Medium | Resolved | Error handling & resilience | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:610-668`, `src/MxGateway.Worker/MxAccess/MxAccessCommandExecutor.cs:124-153` |
+| Worker-027 | Medium | Resolved | Error handling & resilience | `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SyntheticAlarmGuid.cs:38-40` |
 | Worker.Tests-003 | Medium | Resolved | Concurrency & thread safety | `src/MxGateway.Worker.Tests/Sta/StaRuntimeTests.cs:46-48` |
 | Worker.Tests-004 | Medium | Resolved | Concurrency & thread safety | `src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs:281-329` |
 | Worker.Tests-005 | Medium | Resolved | Performance & resource management | `src/MxGateway.Worker.Tests/Ipc/WorkerFrameProtocolTests.cs:20-31,103-105`, `src/MxGateway.Worker.Tests/Ipc/WorkerPipeSessionTests.cs:28-31` |
@@ -138,6 +151,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Worker.Tests-016 | Medium | Resolved | Code organization & conventions | `src/MxGateway.Worker.Tests/MxAccess/AlarmCommandExecutorTests.cs:317-393` |
 | Worker.Tests-017 | Medium | Resolved | Testing coverage | `src/MxGateway.Worker.Tests/Ipc/WorkerPipeSessionTests.cs` |
 | Worker.Tests-018 | Medium | Resolved | Correctness & logic bugs | `src/MxGateway.Worker.Tests/MxAccess/MxAccessLiveComCreationTests.cs:18-31, 35-73, 75-145, 148-220, 222-342` |
+| Worker.Tests-031 | Medium | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/FailoverAlarmConsumerTests.cs` (all `FailoverSettings` constructions) |
 | Client.Dotnet-004 | Low | Resolved | Error handling & resilience | `clients/dotnet/MxGateway.Client/MxGatewayClient.cs:283-294`, `clients/dotnet/MxGateway.Client/GalaxyRepositoryClient.cs:392-403` |
 | Client.Dotnet-005 | Low | Resolved | Correctness & logic bugs | `clients/dotnet/MxGateway.Client/MxGatewaySession.cs:82,124,175` |
 | Client.Dotnet-006 | Low | Resolved | Code organization & conventions | `clients/dotnet/MxGateway.Client/MxGatewayClientOptions.cs:50`, `clients/dotnet/MxGateway.Client/MxGatewayClientContractInfo.cs:10-14` |
@@ -155,6 +169,9 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Dotnet-019 | Low | Resolved | Correctness & logic bugs | `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayClientCli.cs:745` |
 | Client.Dotnet-020 | Low | Resolved | Error handling & resilience | `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayClientCli.cs:792-810`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayClientCli.cs:774-780` |
 | Client.Dotnet-021 | Low | Resolved | Correctness & logic bugs | `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayClientCli.cs:487`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayClientCli.cs:715` |
+| Client.Dotnet-023 | Low | Resolved | Code organization & conventions | `clients/dotnet/Directory.Build.props:17`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/IMxGatewayCliClient.cs:6`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/*.cs` |
+| Client.Dotnet-024 | Low | Resolved | Code organization & conventions | `clients/dotnet/Directory.Build.props:12`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client/ZB.MOM.WW.MxGateway.Client.csproj:19-24` |
+| Client.Dotnet-025 | Low | Resolved | Concurrency & thread safety | `clients/dotnet/ZB.MOM.WW.MxGateway.Client/LazyBrowseNode.cs:38,41,54,82,94` |
 | Client.Go-004 | Low | Resolved | mxaccessgw conventions | `clients/go/mxgateway/alarms_test.go:153-154`, `clients/go/mxgateway/galaxy_test.go:58-59` |
 | Client.Go-005 | Low | Resolved | Design-document adherence | `clients/go/mxgateway/client.go:64,68`, `clients/go/mxgateway/galaxy.go:83,87` |
 | Client.Go-006 | Low | Resolved | Error handling & resilience | `clients/go/mxgateway/errors.go:9-130` |
@@ -177,6 +194,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Go-025 | Low | Resolved | Correctness & logic bugs | `clients/go/mxgateway/session.go:395-485,495-525` |
 | Client.Go-026 | Low | Resolved | Error handling & resilience | `clients/go/cmd/mxgw-go/main.go:1196-1222` |
 | Client.Go-027 | Low | Resolved | Code organization & conventions | `clients/go/cmd/mxgw-go/main.go:1195-1206` |
+| Client.Go-029 | Low | Resolved | Documentation & comments | `clients/go/README.md:300-303` |
 | Client.Java-006 | Low | Resolved | Performance & resource management | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:323-328`, `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/GalaxyRepositoryClient.java:279-284` |
 | Client.Java-007 | Low | Resolved | Testing coverage | `clients/java/mxgateway-client/src/test/java/com/dohertylan/mxgateway/client/` |
 | Client.Java-008 | Low | Resolved | Error handling & resilience | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:298-304` |
@@ -199,6 +217,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Java-031 | Low | Resolved | mxaccessgw conventions | `clients/java/README.md:13,17,26` |
 | Client.Java-035 | Low | Resolved | Testing coverage | `clients/java/zb-mom-ww-mxgateway-client/src/test/java/com/zb/mom/ww/mxgateway/client/MxGatewayClientSessionTests.java` |
 | Client.Java-036 | Low | Resolved | Code organization & conventions | `clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/MxGatewayAlarmFeedSubscription.java`, `MxGatewayEventSubscription.java`, `MxGatewayActiveAlarmsSubscription.java`, `DeployEventSubscription.java` |
+| Client.Java-038 | Low | Resolved | Code organization & conventions | `clients/java/zb-mom-ww-mxgateway-cli/src/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java:1347-1393` |
 | Client.Python-001 | Low | Resolved | Documentation & comments | `clients/python/pyproject.toml:8,25`, `clients/python/src/mxgateway_cli/commands.py:25` |
 | Client.Python-002 | Low | Resolved | Code organization & conventions | `clients/python/src/mxgateway/__init__.py:27` |
 | Client.Python-004 | Low | Resolved | Correctness & logic bugs | `clients/python/src/mxgateway_cli/commands.py:386,402-404` |
@@ -217,6 +236,9 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Python-021 | Low | Resolved | Documentation & comments | `clients/python/src/mxgateway_cli/commands.py`, `clients/python/README.md:235-258` |
 | Client.Python-025 | Low | Resolved | Testing coverage | `clients/python/tests/test_cli.py`, `clients/python/src/zb_mom_ww_mxgateway/{client.py,session.py}`, `clients/python/src/zb_mom_ww_mxgateway_cli/commands.py` |
 | Client.Python-026 | Low | Resolved | Correctness & logic bugs | `clients/python/src/zb_mom_ww_mxgateway_cli/commands.py:674-738` |
+| Client.Python-029 | Low | Resolved | Correctness & logic bugs | `clients/python/src/zb_mom_ww_mxgateway/options.py:78-90` |
+| Client.Python-030 | Low | Resolved | Code organization & conventions | `clients/python/pyproject.toml:17` |
+| Client.Python-031 | Low | Resolved | Testing coverage | `clients/python/tests/test_tls.py:34`, `clients/python/pyproject.toml:53-56` |
 | Client.Rust-004 | Low | Resolved | Documentation & comments | `clients/rust/src/version.rs:7` |
 | Client.Rust-007 | Low | Resolved | Design-document adherence | `clients/rust/RustClientDesign.md:14-55` |
 | Client.Rust-008 | Low | Resolved | Performance & resource management | `clients/rust/src/value.rs:161-261` |
@@ -233,6 +255,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Rust-026 | Low | Resolved | Performance & resource management | `clients/rust/crates/mxgw-cli/src/main.rs:1402-1406,1419-1423` |
 | Client.Rust-027 | Low | Resolved | Documentation & comments | `clients/rust/.cargo/config.toml:1-9` |
 | Client.Rust-028 | Low | Resolved | mxaccessgw conventions | `clients/rust/crates/mxgw-cli/src/main.rs:1126-1166` |
+| Client.Rust-032 | Low | Resolved | Design-document adherence | `clients/rust/RustClientDesign.md`; surface in `clients/rust/src/galaxy.rs:281-379` |
 | Contracts-001 | Low | Resolved | Design-document adherence | `docs/Grpc.md:13` (and `:3`, `:32`, `:39`) |
 | Contracts-003 | Low | Won't Fix | Code organization & conventions | `src/MxGateway.Contracts/MxGateway.Contracts.csproj:10` |
 | Contracts-004 | Low | Resolved | Documentation & comments | `src/MxGateway.Contracts/GatewayContractInfo.cs:3-6` |
@@ -248,6 +271,8 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Contracts-015 | Low | Resolved | Documentation & comments | `src/MxGateway.Contracts/Protos/mxaccess_gateway.proto:571-582` |
 | Contracts-016 | Low | Resolved | Code organization & conventions | `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto:31-41` (`QueryActiveAlarmsRequest`) |
 | Contracts-017 | Low | Resolved | Documentation & comments | `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto:23-29` (the `rpc QueryActiveAlarms` block) |
+| Contracts-018 | Low | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Tests/Contracts/ProtobufContractRoundTripTests.cs:396` (`ActiveAlarmSnapshot_RoundTripsAllFields`) |
+| Contracts-019 | Low | Resolved | Documentation & comments | `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto:850-851` (`ActiveAlarmSnapshot`), `:318-324` (`AlarmProviderMode`) |
 | IntegrationTests-007 | Low | Resolved | Concurrency & thread safety | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:20`, `src/MxGateway.IntegrationTests/Galaxy/GalaxyRepositoryLiveTests.cs:5`, `src/MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:9` |
 | IntegrationTests-008 | Low | Resolved | Code organization & conventions | `src/MxGateway.IntegrationTests/LiveLdapFactAttribute.cs`, `src/MxGateway.IntegrationTests/Galaxy/LiveGalaxyRepositoryFactAttribute.cs`, `src/MxGateway.IntegrationTests/LiveMxAccessFactAttribute.cs` |
 | IntegrationTests-009 | Low | Resolved | Documentation & comments | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:372-375` |
@@ -263,6 +288,9 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | IntegrationTests-023 | Low | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:14-29` |
 | IntegrationTests-024 | Low | Resolved | Code organization & conventions | `src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs` (`NullDashboardEventBroadcaster` private class at end of file) |
 | IntegrationTests-025 | Low | Resolved | Correctness & logic bugs | `src/ZB.MOM.WW.MxGateway.IntegrationTests/IntegrationTestEnvironmentTests.cs:57-84` (`ResolveRepositoryRoot_NoMarkers_ThrowsInvalidOperationExceptionNamingStartAndMarkers`) |
+| IntegrationTests-027 | Low | Resolved | Code organization & conventions | `src/ZB.MOM.WW.MxGateway.IntegrationTests/ZB.MOM.WW.MxGateway.IntegrationTests.csproj`, `src/ZB.MOM.WW.MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:4-5,134` |
+| IntegrationTests-028 | Low | Resolved | Design-document adherence | `src/ZB.MOM.WW.MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:120-161`, `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardServiceCollectionExtensions.cs:35` |
+| IntegrationTests-029 | Low | Resolved | Documentation & comments | `docs/GatewayTesting.md:218-224` |
 | Server-007 | Low | Resolved | Performance & resource management | `src/MxGateway.Server/Galaxy/GalaxyHierarchyProjector.cs:55-70` |
 | Server-008 | Low | Resolved | Performance & resource management | `src/MxGateway.Server/Grpc/GalaxyRepositoryGrpcService.cs:111-134,160-189` |
 | Server-009 | Low | Resolved | Error handling & resilience | `src/MxGateway.Server/Security/Authentication/AuthSqliteConnectionFactory.cs:15-32` |
@@ -297,6 +325,8 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Server-048 | Low | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Sessions/SessionManagerTests.cs:463-498` |
 | Server-049 | Low | Resolved | Documentation & comments | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/IDashboardSessionAdminService.cs:5-18`, `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSessionAdminService.cs:8-25` |
 | Server-050 | Low | Resolved | Error handling & resilience | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSessionAdminService.cs:42-75,92-125` |
+| Server-052 | Low | Resolved | Documentation & comments | `src/ZB.MOM.WW.MxGateway.Server/Alarms/IAlarmWatchListResolver.cs:24-30`, `src/ZB.MOM.WW.MxGateway.Server/Alarms/AlarmWatchListResolver.cs:101-114`, `docs/GatewayConfiguration.md:247` |
+| Server-053 | Low | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmWatchListResolverTests.cs`, `src/ZB.MOM.WW.MxGateway.Tests/Alarms/GatewayAlarmMonitorProviderModeTests.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` |
@@ -317,6 +347,9 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Tests-029 | Low | Resolved | Error handling & resilience | `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardSessionAdminServiceTests.cs:61-106,139-222`, `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSessionAdminService.cs:77-125` |
 | Tests-030 | Low | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardApiKeyManagementServiceTests.cs:115-163`, `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardApiKeyManagementService.cs:146-177` |
 | Tests-031 | Low | Resolved | Concurrency & thread safety | `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardSnapshotPublisherTests.cs:22-61` |
+| Tests-033 | Low | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardAlarmProviderStatus.cs`, `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardBrowseAndAlarmModelTests.cs:140-195` |
+| Tests-034 | Low | Resolved | mxaccessgw conventions | `src/ZB.MOM.WW.MxGateway.Tests/Diagnostics/GatewayLogRedactorSeamTests.cs:1-15` |
+| Tests-035 | Low | Resolved | Concurrency & thread safety | `src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmFailoverEndToEndTests.cs:315-329` |
 | Worker-009 | Low | Resolved | Performance & resource management | `src/MxGateway.Worker/Ipc/WorkerFrameReader.cs:31,49`, `src/MxGateway.Worker/Ipc/WorkerFrameWriter.cs:57-58` |
 | Worker-010 | Low | Resolved | Correctness & logic bugs | `src/MxGateway.Worker/Conversion/VariantConverter.cs:204-226` |
 | Worker-011 | Low | Resolved | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeClient.cs:169-171` |
@@ -331,6 +364,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Worker-022 | Low | Resolved | Code organization & conventions | `src/MxGateway.Worker/MxAccess/MxAlarmSnapshot.cs:12`, `:26`, `:49` |
 | Worker-024 | Low | Resolved | Concurrency & thread safety | `src/MxGateway.Worker/MxAccess/AlarmCommandHandler.cs:63-187`, `src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs:191-323` |
 | Worker-025 | Low | Resolved | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:111-117` |
+| Worker-028 | Low | Resolved | Code organization & conventions | `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SubtagAlarmStateMachine.cs:43-52`, `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SubtagAlarmConsumer.cs:70-75` |
 | Worker.Tests-008 | Low | Resolved | Documentation & comments | `src/MxGateway.Worker.Tests/Conversion/VariantConverterTests.cs:175-182` |
 | Worker.Tests-009 | Low | Resolved | Code organization & conventions | `src/MxGateway.Worker.Tests/MxAccess/AlarmCommandHandlerTests.cs`, `AlarmDispatcherTests.cs`, `AlarmCommandExecutorTests.cs`, `AlarmRecordTransitionMapperTests.cs`, `WnWrapAlarmConsumerXmlTests.cs` |
 | Worker.Tests-010 | Low | Resolved | Correctness & logic bugs | `src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs:230-258` |
@@ -351,3 +385,5 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Worker.Tests-028 | Low | Resolved | Design-document adherence | `docs/GatewayTesting.md`, `src/MxGateway.Worker.Tests/Probes/` |
 | Worker.Tests-029 | Low | Resolved | Code organization & conventions | `src/MxGateway.Worker.Tests/Probes/AlarmsLiveSmokeTests.cs:9`, `src/MxGateway.Worker.Tests/Probes/AlarmClientWmProbeTests.cs:14`, `src/MxGateway.Worker.Tests/Probes/WnWrapConsumerProbeTests.cs:10` |
 | Worker.Tests-030 | Low | Resolved | Documentation & comments | `src/MxGateway.Worker.Tests/Ipc/WorkerPipeSessionTests.cs:862-890` |
+| Worker.Tests-032 | Low | Resolved | Error handling & resilience | `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/FailoverAlarmConsumerTests.cs` |
+| Worker.Tests-033 | Low | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/SubtagAlarmStateMachineTests.cs` |

code-reviews/Server/findings.md

@@ -4,8 +4,8 @@
 |---|---|
 | Module | `src/ZB.MOM.WW.MxGateway.Server` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |
 
@@ -120,6 +120,38 @@ contention nor the bounded `_events` channel saw any changes in this wave.
 | 9 | Testing coverage | No issues found in this module — see Tests-026 in the Tests module for the missing EventsHub broadcast coverage. |
 | 10 | Documentation & comments | Issues found: Server-040, Server-043 (both documentation gaps). |
 
+### 2026-06-15 re-review (commit 410acc9)
+
+Re-review pass at `410acc9` over the `42b0037..HEAD` diff. The diff is large (~137 files)
+but the bulk is vendored theme/CSS/font asset swaps (`wwwroot`), generated code, and the
+shared-library auth refactor / TLS cert-autogen / lazy-browse / canonical-audit waves that
+each carry their own design+plan and were verified in passing only. This pass is scoped to
+the **alarm-provider subtag-fallback** wave the task called out: the central
+`GatewayAlarmMonitor` provider-mode seeding + failover/failback handling, the new
+`AlarmWatchListResolver` / `IAlarmWatchListResolver`, `AlarmFallbackOptions` /
+`AlarmDiscoveryOptions` / `AlarmSubtagNameOptions` and their `GatewayOptionsValidator`
+wiring, the `DashboardAlarmProviderStatus` badge + `AlarmsPage.razor` hub attach, the
+provider-mode gauge + `provider_switches` counter (`GatewayMetrics`,
+`AlarmProviderSwitchReason`), the Galaxy alarm-attribute discovery query
+(`GalaxyRepository.GetAlarmAttributesAsync` / `AlarmAttributesSql` / `GalaxyAlarmAttributeRow`),
+the `/auth/login` POST move + configurable `Dashboard:CookieName`, and the
+`BrowseChildrenRequest` scope-resolver entry. Prior findings Server-044 through Server-050
+are confirmed resolved by the SessionManager/GatewaySession changes in range and remain
+closed. New findings filed against this pass: Server-051..053.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issues found: Server-051 (`AlarmWatchListResolver.ResolveAsync`'s broad `catch (Exception)` swallows `OperationCanceledException`, contradicting the `IAlarmWatchListResolver` cancellation contract). |
+| 2 | mxaccessgw conventions | No issues found — file-scoped namespaces, `sealed`, `Async` suffix, Options pattern, MXAccess-aligned naming all hold; no UI component libraries (badge is Bootstrap-only); the alarm SQL is a parameterless constant; no secret/tag-value logging; well-known reason strings centralised in `AlarmProviderReasons`. |
+| 3 | Concurrency & thread safety | No issues found — `_providerMode`/`_providerDegraded`/`_providerReason`/`_providerSince` are read/written only under `_sync`; `BroadcastToAll` runs under `_sync`; the reconcile after a mode change is intentionally awaited outside `_sync` to avoid the documented self-deadlock; the provider-mode gauge is serialized on `GatewayMetrics._syncRoot`. |
+| 4 | Error handling & resilience | Issues found: Server-051 (cancellation swallowed in the resolver — also an error-handling/contract concern). |
+| 5 | Security | No issues found — `BrowseChildren` runs the same `ResolveBrowseSubtrees()` constraint scoping and `MetadataRead` scope as `DiscoverHierarchy`; the configurable `Dashboard:CookieName` falls back to the canonical default and cannot be blanked; the `/auth/login` POST keeps antiforgery + return-URL sanitisation. |
+| 6 | Performance & resource management | No issues found in the alarm-fallback code — discovery is a one-shot per subscribe lifecycle; the watch-list is composed once. |
+| 7 | Design-document adherence | No issues found — `docs/GatewayConfiguration.md`, `docs/Metrics.md`, `docs/GalaxyRepository.md`, and the `docs/plans/2026-06-13-alarm-subtag-fallback*` / `2026-06-15-forced-subtag-mode-fix.md` plans were landed in the same range and match the code. |
+| 8 | Code organization & conventions | No issues found — new alarm types live under `Alarms/`, options under `Configuration/`, metric helper under `Metrics/`, registered via `AddGatewayAlarms`. |
+| 9 | Testing coverage | Issues found: Server-053 (`AlarmWatchListResolver` `ExcludeAttributes`-vs-`IncludeAttributes` precedence and the resolver's cancellation contract are untested; no redundant-mode-change guard test). |
+| 10 | Documentation & comments | Issues found: Server-052 (`IAlarmWatchListResolver` XML contract claims cancellation propagates while the implementation swallows it; the `Discovery:ExcludeAttributes` doc says "Repository-derived watch-list" while the code also removes matching explicit `IncludeAttributes`). |
+
 ## Findings
 
 ### Server-001
@@ -929,3 +961,64 @@ Today neither call site has a Blazor error boundary, so an unhandled exception l
 **Recommendation:** Add a general `catch (Exception exception)` after the `SessionManagerException` catch in both `CloseSessionAsync` and `KillWorkerAsync`, log a warning (matching the SessionManagerException pattern), and return `DashboardSessionAdminResult.Fail($"{operation} failed unexpectedly. See the gateway log for details.")`. This makes the result type truly the only output the page sees. Add a regression test using a `ThrowingSessionManager` that throws e.g. `InvalidOperationException` from `KillWorkerAsync` and asserts the service returns a failing result rather than propagating.
 
 **Resolution:** 2026-05-24 — Added the recommended general `catch (Exception)` arms to both `DashboardSessionAdminService.CloseSessionAsync` and `KillWorkerAsync` (`src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSessionAdminService.cs`), placed after the `SessionManagerException` catches and behind a `catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) throw;` so caller cancellation still propagates cleanly. The new catches log a warning with actor + session id and return `DashboardSessionAdminResult.Fail("{Operation} failed unexpectedly for session {SessionId}. See the gateway log for details.")`, mirroring the SessionManagerException pattern. Regression tests in `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardSessionAdminServiceTests.cs`: `CloseSessionAsync_WhenManagerThrowsUnexpected_ReturnsFriendlyFail` (the `ISessionManager` throws `InvalidOperationException("unexpected")`) and `KillWorkerAsync_WhenManagerThrowsUnexpected_ReturnsFriendlyFail` (throws `IOException("pipe broken")`); both assert the service returns a failing result with a non-blank message rather than propagating. The fake's new `CloseThrowsUnexpected` / `KillThrowsUnexpected` properties hold the configured exception. Confirmed to fail before the fix (raw exception propagated) and pass after.
+
+### Server-051
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `src/ZB.MOM.WW.MxGateway.Server/Alarms/AlarmWatchListResolver.cs:64-78` |
+| Status | Resolved |
+
+**Description:** `AlarmWatchListResolver.ResolveAsync` wraps the Galaxy Repository discovery call in a bare `catch (Exception ex)` that logs a warning and continues with an empty (config-only) discovery set:
+
+```csharp
+try { rows = await _repository.GetAlarmAttributesAsync(cancellationToken)...; }
+catch (Exception ex) { _logger.LogWarning(ex, "...continuing with configuration-only watch-list."); rows = []; }
+```
+
+`OperationCanceledException` / `TaskCanceledException` derive from `Exception`, so a cancellation triggered while `GetAlarmAttributesAsync` is awaiting SQL is **swallowed**, not propagated. The resolver then returns a (config-only or empty) watch-list as though the call completed normally. This directly contradicts the `IAlarmWatchListResolver.ResolveAsync` XML contract, which states: *"Cancellation is the one exception: a triggered cancellationToken still propagates an OperationCanceledException."* In practice the resolver is called from `GatewayAlarmMonitor.SubscribeAlarmsAsync` on the monitor's lifecycle token; if the gateway is shutting down (or the monitor lifecycle is being torn down) mid-discovery, the resolver hides the cancellation and the monitor proceeds to issue `SubscribeAlarms` with a wrong (empty) watch-list instead of unwinding promptly. The `GalaxyRepository.GetAlarmAttributesAsync` SQL path does honour the token (`OpenAsync(ct)` / `ExecuteReaderAsync(ct)` / `ReadAsync(ct)`), so a real cancellation can land inside this catch.
+
+**Recommendation:** Add a `catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) { throw; }` ahead of the general catch (or filter the general catch with `when (ex is not OperationCanceledException)`), so cancellation propagates per the documented contract while genuine discovery failures still degrade to a config-only list. Add a regression test that cancels the token mid-`GetAlarmAttributesAsync` and asserts `OperationCanceledException` propagates.
+
+**Resolution:** Resolved 2026-06-15. Confirmed against source: the bare `catch (Exception ex)` swallowed `OperationCanceledException`. Filtered the catch with `when (ex is not OperationCanceledException)` so a real cancellation propagates per the `IAlarmWatchListResolver` contract while genuine discovery failures still degrade to a config-only list. Regression test: `AlarmWatchListResolverTests.ResolveAsync_RepositoryCancelled_PropagatesOperationCanceled` (failed before the fix, passes after).
+
+### Server-052
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `src/ZB.MOM.WW.MxGateway.Server/Alarms/IAlarmWatchListResolver.cs:24-30`, `src/ZB.MOM.WW.MxGateway.Server/Alarms/AlarmWatchListResolver.cs:101-114`, `docs/GatewayConfiguration.md:247` |
+| Status | Resolved |
+
+**Description:** Two prose-vs-code mismatches in the watch-list resolver:
+
+1. The `IAlarmWatchListResolver.ResolveAsync` XML `<returns>` promises that a triggered `cancellationToken` propagates an `OperationCanceledException`, but the implementation swallows it (see Server-051). Whichever way Server-051 is resolved, exactly one of the doc or the code is currently wrong; right now the doc over-promises.
+
+2. `AlarmDiscoveryOptions.ExcludeAttributes` and `docs/GatewayConfiguration.md:247` both describe `ExcludeAttributes` as removing entries from the **"Repository-derived"** watch-list. The implementation's `ordered.RemoveAll(e => excluded.Contains(e.Reference))` runs over the combined list — Galaxy-Repository rows **and** the explicit `Discovery:IncludeAttributes` entries appended just above it — so an exclude entry that matches an explicit include silently removes that include too. The behaviour is defensible (excludes win) but is not what the "Repository-derived" wording says, and an operator who adds an attribute via `IncludeAttributes` and also lists it in `ExcludeAttributes` would be surprised it disappears.
+
+**Recommendation:** For (1), align the `IAlarmWatchListResolver` doc with whatever Server-051 settles on. For (2), either restrict the exclude to GR-discovered rows (apply `RemoveAll` before appending the `IncludeAttributes` entries) or update the option XML doc and `GatewayConfiguration.md` to say excludes are applied to the merged GR-plus-include list and therefore also suppress matching explicit includes.
+
+**Resolution:** Resolved 2026-06-15. (1) No longer over-promises: the Server-051 fix makes the implementation propagate `OperationCanceledException`, so the `IAlarmWatchListResolver.ResolveAsync` `<returns>` doc is now accurate and was left unchanged. (2) Kept the "excludes win" code behaviour (excludes applied to the merged GR-plus-include list) and corrected the prose to match: `AlarmDiscoveryOptions.ExcludeAttributes` XML doc and `docs/GatewayConfiguration.md:247` now state the exclude runs after the GR rows and explicit `IncludeAttributes` are combined, so an exclude matching an explicit include suppresses it too. The "excludes win" precedence is pinned by `AlarmWatchListResolverTests.ResolveAsync_ExcludeAlsoSuppressesMatchingExplicitInclude`.
+
+### Server-053
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmWatchListResolverTests.cs`, `src/ZB.MOM.WW.MxGateway.Tests/Alarms/GatewayAlarmMonitorProviderModeTests.cs` |
+| Status | Resolved |
+
+**Description:** The new alarm-fallback surface is broadly well-tested (`AlarmWatchListResolverTests`, `GatewayAlarmMonitorProviderModeTests`, `DashboardBrowseAndAlarmModelTests`, `GalaxyAlarmAttributeMappingTests`, `GatewayOptionsValidatorTests`), but two behaviours that the diff introduced have no coverage:
+
+- **Resolver cancellation contract (Server-051):** no test cancels the token mid-discovery and asserts `OperationCanceledException` propagates. Because the existing `ResolveAsync_RepositoryThrows_LogsAndReturnsConfigOnlySet` asserts the swallow path, the cancellation regression is precisely the case that would catch the Server-051 bug — and its absence is why the contract violation went unnoticed.
+- **Exclude-vs-include precedence (Server-052 item 2):** no test exercises a `Discovery:IncludeAttributes` entry that also appears in `ExcludeAttributes`, so the "excludes also drop explicit includes" behaviour is unpinned and would silently change if the merge order were edited.
+
+Additionally, `GatewayAlarmMonitor.ApplyProviderModeChangeAsync` increments the `mxgateway.alarms.provider_switches` counter and resets `_providerSince` unconditionally on every `OnAlarmProviderModeChanged` event, with no guard for a redundant event whose `toMode` equals the current mode; there is no test asserting the from==to / no-op behaviour either way.
+
+**Recommendation:** Add resolver tests for (a) cancellation propagation and (b) an include that is also excluded; and a `GatewayAlarmMonitorProviderMode` test pinning the provider-switch counter behaviour for a same-mode repeat event (whichever semantics the team intends). These lock down the contracts the Server-051/052 findings expose.
+
+**Resolution:** Resolved 2026-06-15. Added all three missing tests: (a) `AlarmWatchListResolverTests.ResolveAsync_RepositoryCancelled_PropagatesOperationCanceled` (cancellation propagation, also covers Server-051); (b) `AlarmWatchListResolverTests.ResolveAsync_ExcludeAlsoSuppressesMatchingExplicitInclude` (exclude-vs-include precedence, also Server-052 item 2); and (c) `GatewayAlarmMonitorProviderModeTests.ProviderModeChange_RepeatedSameMode_RecordsASwitchForEachEvent`, which pins the existing semantics — each worker-reported `OnAlarmProviderModeChanged` event records a `provider_switches` increment (and resets `_providerSince`) even when `toMode` equals the current mode, since the worker is the authority on when a mode change occurred and the gateway does not synthesize or suppress it.

code-reviews/Tests/findings.md

@@ -4,13 +4,43 @@
 |---|---|
 | Module | `src/ZB.MOM.WW.MxGateway.Tests` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |
 
 ## Checklist coverage
 
+### 2026-06-15 re-review (commit `410acc9`)
+
+Re-review of the `42b0037..410acc9` diff (≈57 files), scoped to the alarm-provider
+fallback feature: the end-to-end failover/failback lifecycle test
+(`AlarmFailoverEndToEndTests`), the provider-mode/metric tests
+(`GatewayAlarmMonitorProviderModeTests`), the watch-list resolver tests
+(`AlarmWatchListResolverTests`), the validator additions
+(`GatewayOptionsValidatorTests` AlarmFallback block), the dashboard badge model
+(`DashboardBrowseAndAlarmModelTests`), the alarm metric tests
+(`GatewayMetricsTests`), the Galaxy alarm mapper (`GalaxyAlarmAttributeMappingTests`),
+and the new `provider_status` / degraded-provenance protobuf round-trips. The
+non-alarm churn in the diff (kill/shutdown SessionManager tests closing prior
+Tests-028/029, XML-doc-only additions to `SessionManagerBulkTests`/`GatewaySessionTests`,
+browse-tab and TLS tests) was walked but is not the review focus.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | No issues found in this diff. The lifecycle test correctly disambiguates the recovery `ProviderStatus` from the baseline by matching on `Reason == "recovered"`; the `ModeString_MapsToForcedProviderMode` `Assert.Empty(WatchList)` is weak (the stub resolver returns `[]` regardless of mode) but not wrong. |
+| 2 | mxaccessgw conventions | Issue found: Tests-034 (`GatewayLogRedactorSeamTests.cs` is in the global namespace with redundant `System.Collections.Generic`/`Xunit` usings, `var`, and a non-`sealed` `public class` — the same C# style drift family as the resolved Tests-008). |
+| 3 | Concurrency & thread safety | Issue found: Tests-035 (`AlarmFailoverEndToEndTests.DegradedTransition_*`'s second-subscriber `await foreach`-to-`SnapshotComplete` has no `WaitTimeout`, so a regression that never emits `SnapshotComplete` hangs the test instead of failing cleanly). The metric/feed reader races are correctly gated by `baselineReceived` TCS before emitting events. |
+| 4 | Error handling & resilience | No issues found in this diff. `AlarmWatchListResolverTests.ResolveAsync_RepositoryThrows_LogsAndReturnsConfigOnlySet` covers the discovery-unavailable degradation path; validator failure paths are well covered. |
+| 5 | Security | No issues found in this diff. The redaction seam assertion in `GatewayLogRedactorSeamTests` (despite its style drift) meaningfully pins API-key masking in `ClientIdentity`; secured-bulk credential round-trips are pinned. |
+| 6 | Performance & resource management | No issues found in this diff. Monitors/CTSs are disposed; `using GatewayMetrics`/`using GatewayAlarmMonitor` throughout. |
+| 7 | Design-document adherence | No issues found in this diff. Tests match the alarm-fallback plan and the forced-vs-failover-degraded badge distinction. |
+| 8 | Code organization & conventions | See Tests-034. The two alarm-monitor test files replicate (not share) the `FakeSessionManager`/`StubWatchListResolver` harness; the in-file remark documents this is deliberate to keep the sibling untouched — acceptable, not filed. |
+| 9 | Testing coverage | Issues found: Tests-032 (the monitor's `toMode`→`AlarmProviderSwitchReason` derivation — Subtag→Failover, Alarmmgr→Failback — is untested: `Failback` is asserted nowhere and the monitor tests check only the switch *count*, so a swapped/`Unknown` reason regression passes), Tests-033 (`DashboardAlarmProviderStatus.FromFeed` and its non-provider-status `ArgumentException` guard, the `SinceUtc` mapping, the `DegradedLabel` text, and the `Degraded && Mode==Alarmmgr` guard branch are all uncovered). |
+| 10 | Documentation & comments | No issues found in this diff. New alarm test files carry orienting class-level summaries; `GalaxyAlarmAttributeMappingTests`'s "derivation" framing slightly overstates the pass-through mapper but is harmless. |
+
+### 2026-05-24 re-review of the Tests-013–019 batch
+
 This pass (commit `a020350`) re-reviews the module after the Tests-013–019 batch was resolved alongside Server-017, Server-021, and Contracts-010.
 
 | # | Category | Result |
@@ -557,3 +587,63 @@ The cancellation tests for `WorkerClient` in `WorkerClientTests` *do* exercise t
 **Recommendation:** (a) The cheap fix: have `ThrowOnceThenYieldSnapshotService` record `_firstThrowAt = DateTimeOffset.UtcNow` immediately before the `throw`, and change the assertion to `secondSubscribeAt - firstThrowAt >= reconnectDelay - 10ms` — the gap then measures only the reconnect delay, eliminating the variable scheduling baseline. (b) The deeper fix: extend `DashboardSnapshotPublisher` to accept an `ITimeProvider`-style delay seam (or a virtual `DelayAsync` hook) so a `ManualTimeProvider` could advance time deterministically. (a) is preferred for now; (b) belongs as a follow-up if more reconnect-loop tests are added.
 
 **Resolution:** 2026-05-24 — Applied option (a). Added `FirstThrowAt` to `ThrowOnceThenYieldSnapshotService` and set it via `FirstThrowAt = DateTimeOffset.UtcNow;` immediately before the first-call `throw`. Removed the pre-`StartAsync` `startedAt` baseline; the assertion now reads `gap = secondSubscribeAt - firstThrowAt` (both timestamps captured inside the fake), and the 10 ms slack absorbs the Windows `Task.Delay` quantum without the variable `StartAsync` / scheduling overhead in the baseline. This is the same flake-isolation pattern Tests-006 / Tests-017 used (measuring only the production delay, not test-side setup). Suite green; the test passes deterministically across repeated runs.
+
+### Tests-032
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Testing coverage |
+| Location | `src/ZB.MOM.WW.MxGateway.Server/Alarms/GatewayAlarmMonitor.cs:435-441`, `src/ZB.MOM.WW.MxGateway.Tests/Alarms/GatewayAlarmMonitorProviderModeTests.cs`, `src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmFailoverEndToEndTests.cs` |
+| Status | Resolved |
+
+**Description:** `GatewayAlarmMonitor.HandleProviderModeChanged` derives the provider-switch reason from the target mode: `toMode switch { Subtag => Failover, Alarmmgr => Failback, _ => Unknown }` (lines 435-439), then calls `_metrics.AlarmProviderSwitched(fromModeInt, toModeInt, switchReason)`. No test in the diff asserts this derivation. `GatewayAlarmMonitorProviderModeTests.ProviderModeChange_BroadcastsDegradedStatus_AndIncrementsSwitchMetric` only asserts the switch *count* (`switchCount == 1`) — it never inspects the `from`/`to`/`reason` tags on the measurement. `AlarmFailoverEndToEndTests.ProviderFailoverAndFailback_FullLifecycle` drives both a failover (alarmmgr→subtag) and a failback (subtag→alarmmgr) but asserts only on feed `ProviderStatus` messages, not on the metric tags. The only place the `reason` tag is read is `GatewayMetricsTests.AlarmProviderSwitched_IncrementsCounterWithExpectedTags`, which passes `AlarmProviderSwitchReason.Failover` *explicitly* to the metrics layer — that pins the metrics-side tag formatting, not the monitor's `toMode→reason` mapping. `AlarmProviderSwitchReason.Failback` is asserted nowhere in the suite. A regression that swapped the Failover/Failback arms, or collapsed them to `Unknown`, would pass every existing test while emitting wrong dashboard/observability data for every failback.
+
+**Recommendation:** Extend `GatewayAlarmMonitorProviderModeTests` (or add a failback case) to capture the `reason` tag through a `MeterListener` and assert it equals `"failover"` on an alarmmgr→subtag change and `"failback"` on a subtag→alarmmgr change, mirroring the tag-capturing pattern already in `GatewayMetricsTests.AlarmProviderSwitched_IncrementsCounterWithExpectedTags`. This pins the monitor's `toMode→AlarmProviderSwitchReason` derivation, not just the count.
+
+**Resolution:** 2026-06-15 — Confirmed root cause: the existing monitor tests asserted only the switch *count*, and `Failback` was asserted nowhere in the suite, so a swapped/`Unknown` reason arm would pass. Added `GatewayAlarmMonitorProviderModeTests.ProviderModeChange_FailoverThenFailback_RecordsCorrectReasonTags`, which captures the `reason` tag off the `mxgateway.alarms.provider_switches` counter via a `MeterListener` and drives an alarmmgr→subtag change then a subtag→alarmmgr change, asserting the captured reasons are exactly `["failover", "failback"]`. This pins the monitor's `toMode→AlarmProviderSwitchReason` derivation (`ApplyProviderModeChangeAsync`). Test passes against current production code (no production change); no bug found.
+
+### Tests-033
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardAlarmProviderStatus.cs`, `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardBrowseAndAlarmModelTests.cs:140-195` |
+| Status | Resolved |
+
+**Description:** The three new badge-mapping tests cover `FromProviderStatus` for green (Alarmmgr/not-degraded), amber (Subtag/degraded), and cyan (Subtag/forced). Several adjacent behaviours of the same projection are uncovered: (1) `DashboardAlarmProviderStatus.FromFeed(AlarmFeedMessage)` — the public entry the dashboard SignalR snapshot path actually calls — and its `ArgumentException` thrown when the message is not a `ProviderStatus` payload have zero coverage in the suite (a grep for `FromFeed` across the test project returns no hits). (2) The `SinceUtc` field (`status.Since?.ToDateTimeOffset()`) is never asserted, so a regression dropping or mis-converting the badge timestamp would not be caught. (3) The `DegradedLabel` constant text ("Subtag monitoring (degraded)") is asserted nowhere — the amber test only checks the `bg-warning` CSS class, so a label swap would pass. (4) The `degraded = status.Degraded || status.Mode == AlarmProviderMode.Subtag` guard's second branch (`Degraded == true` while `Mode == Alarmmgr`) — an explicitly-degraded alarmmgr status — is untested, so the "guard against either being set independently" comment in the product code is unverified.
+
+**Recommendation:** Add `FromFeed_NonProviderStatusPayload_Throws` (asserting `ArgumentException`) and `FromFeed_ProviderStatusPayload_ProjectsBadge`; assert `SinceUtc` on a status carrying a `Since` timestamp; assert `model.Label == DashboardAlarmProviderStatus.DegradedLabel` in the amber test; and add a `Degraded=true, Mode=Alarmmgr` case asserting it maps to the degraded (amber) badge per the independent-flag guard.
+
+**Resolution:** 2026-06-15 — Confirmed the four coverage gaps against `DashboardAlarmProviderStatus`. Added to `DashboardBrowseAndAlarmModelTests`: `FromFeed_ProviderStatusPayload_ProjectsBadge` and `FromFeed_NonProviderStatusPayload_Throws` (the latter asserts `ArgumentException` for a `SnapshotComplete` feed message); `FromProviderStatus_WithSinceTimestamp_MapsSinceUtc` (pins `SinceUtc` round-trips the protobuf `Since` timestamp); `FromProviderStatus_Alarmmgr_DegradedFlagSet_WarningBadge` (the `Degraded && Mode==Alarmmgr` independent-flag branch maps to the amber degraded badge); and a `DegradedLabel` text assertion added to the existing amber `FromProviderStatus_Subtag_Degraded_WarningBadge`. All pass against current production code (no production change); no bug found.
+
+### Tests-034
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | mxaccessgw conventions |
+| Location | `src/ZB.MOM.WW.MxGateway.Tests/Diagnostics/GatewayLogRedactorSeamTests.cs:1-15` |
+| Status | Resolved |
+
+**Description:** `GatewayLogRedactorSeamTests.cs` diverges from the project's C# style guide and the rest of the test suite: it declares no file-scoped namespace (the class lands in the global namespace, unlike every other test file which sits under `ZB.MOM.WW.MxGateway.Tests.*`); it carries redundant explicit `using System.Collections.Generic;` and `using Xunit;` (both are implicit global usings in this project, enforced elsewhere — see the resolved Tests-008); it uses `var` for `redactor`/`props` where the suite uses explicit types per `docs/style-guides/CSharpStyleGuide.md`; and it declares `public class` rather than the project's `sealed`-by-default convention. The redaction assertion itself is sound (it meaningfully pins API-key masking in `ClientIdentity`), so this is purely the same style-drift family as the previously-filed-and-resolved Tests-008, not a correctness issue.
+
+**Recommendation:** Add `namespace ZB.MOM.WW.MxGateway.Tests.Diagnostics;` (file-scoped), drop the redundant `System.Collections.Generic`/`Xunit` usings, mark the class `public sealed class`, and replace the two `var` declarations with explicit types (`GatewayLogRedactorSeam` / `Dictionary<string, object?>`).
+
+**Resolution:** 2026-06-15 — Confirmed the style drift. Rewrote `GatewayLogRedactorSeamTests.cs` to add the file-scoped `namespace ZB.MOM.WW.MxGateway.Tests.Diagnostics;`, dropped the redundant `using System.Collections.Generic;`/`using Xunit;` (both implicit global usings), marked the class `public sealed class`, and replaced the two `var` declarations with explicit `GatewayLogRedactorSeam` / `Dictionary<string, object?>` types. The single `Redact_MasksApiKeyInClientIdentity` assertion is unchanged and still passes.
+
+### Tests-035
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Concurrency & thread safety |
+| Location | `src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmFailoverEndToEndTests.cs:315-329` |
+| Status | Resolved |
+
+**Description:** In `DegradedTransition_CachedThenReplayed_CarriesDegradedAndSourceProviderToNewSubscriber`, the second-subscriber loop iterates `monitor.StreamAsync(null, newStreamCts.Token)` with no timeout, breaking only when a `SnapshotComplete` payload arrives (lines 317-329). Every other wait in this file routes through `WaitForAsync(..., WaitTimeout)` or `Task.WaitAsync(WaitTimeout)`; this `await foreach` does not. If a regression caused the monitor to stop emitting `SnapshotComplete` for a new subscriber (e.g. a snapshot-replay path that throws before the terminal message), the test would hang on the `await foreach` rather than fail with a `TimeoutException`, relying on the xUnit `longRunningTestSeconds` warning or the CI hard-kill instead of a clean assertion failure. The first subscriber in the same test is correctly bounded by `WaitForAsync`.
+
+**Recommendation:** Bound the second-subscriber drain with the same `WaitTimeout` used elsewhere — e.g. link `newStreamCts` to a `CancellationTokenSource.CreateLinkedTokenSource` plus `CancelAfter(WaitTimeout)`, or wrap the drain in a `Task` awaited via `WaitAsync(WaitTimeout)` — so a missing `SnapshotComplete` surfaces as a deterministic failure rather than a hang.
+
+**Resolution:** 2026-06-15 — Confirmed the unbounded `await foreach` in `DegradedTransition_CachedThenReplayed_CarriesDegradedAndSourceProviderToNewSubscriber`. Bounded the second-subscriber drain with a `CancellationTokenSource.CreateLinkedTokenSource(newStreamCts.Token, drainTimeoutCts.Token)` where `drainTimeoutCts.CancelAfter(WaitTimeout)`, and wrapped the loop in a `try/catch (OperationCanceledException) when (drainTimeoutCts.IsCancellationRequested)` that rethrows a `TimeoutException`. A regression that never emits `SnapshotComplete` now fails cleanly instead of hanging. Test still passes.

code-reviews/Worker.Tests/findings.md

@@ -4,11 +4,48 @@
 |---|---|
 | Module | `src/ZB.MOM.WW.MxGateway.Worker.Tests` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |
 
+## 2026-06-15 re-review (commit `410acc9`)
+
+Re-review of the alarm-fallback test additions in `git diff 42b0037..HEAD --
+src/ZB.MOM.WW.MxGateway.Worker.Tests/`. New unit suites land for the subtag
+fallback (`SubtagAlarmConsumerTests`, `SubtagAlarmStateMachineTests`,
+`SyntheticAlarmGuidTests`, `LmxSubtagAlarmSourceTests`) and the auto-failover
+composite (`FailoverAlarmConsumerTests`); the existing alarm suites are updated
+for the `SubscribeAlarmsCommand`-based handler signature, the
+`(eq, affinity, comFactory)` handler-factory delegate, and the new
+degraded/source-provider fields. Most of the change is genuinely new coverage
+plus a large volume of XML-doc additions on existing test doubles (benign).
+
+Findings: the failover state-machine transitions (failover at threshold,
+failback after stable probes, intermittent-failure reset, before/after-switch
+forwarding, ack delegation, `ProbeOnce`-never-re-Subscribes) are all covered;
+the acked latch (`OutOfOrderAckThenClear_StillEmitsAckRtn`), the dup-address
+guard (`DuplicateActiveSubtag_Throws`), and the exact-match-vs-substring ack
+resolution (`AcknowledgeByName_PrefixNameDoesNotFalseMatch`,
+`AcknowledgeByGuid_*`) are all pinned. Three coverage gaps remain
+(Worker.Tests-031/032/033), all in new alarm-fallback code paths. The two
+newest files (`SyntheticAlarmGuidTests`, `LmxSubtagAlarmSourceTests`) omit an
+explicit `using Xunit;` but compile via the `<Using Include="Xunit" />` global
+using in the csproj, so that is not a finding.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | No issues found — failover/state-machine/ack tests assert meaningful post-conditions (mode, emitted state, target subtag address) and do not pass for the wrong reason; the prefix-name and unknown-guid negative cases pin the exact-match contract. |
+| 2 | mxaccessgw conventions | No issues found — new test methods follow `Method_Scenario_Expectation`; STA-affinity respected (state machine / consumer driven synchronously through internal seams). |
+| 3 | Concurrency & thread safety | No issues found — new failover/subtag suites are single-threaded and event-driven; no wall-clock floors or fixed sleeps were introduced (the `MxAccessValueCacheTests` change only deletes the old Worker.Tests-020 comment block). |
+| 4 | Error handling & resilience | Issues found: Worker.Tests-032 — the `RunPrimary` `when (ex is not OutOfMemoryException)` filter (the OOM-safe catch path) and the `FailoverSettings` clamp branches are untested. |
+| 5 | Security | No issues found — no secrets/credentials; ack-operator identity fields are sentinels. |
+| 6 | Performance & resource management | No issues found — `IDisposable` test subjects use `using`; the `LmxSubtagAlarmSource` dispose-idempotency / unadvise-only-advised-handles teardown is regression-tested. |
+| 7 | Design-document adherence | No issues found — tests mirror the alarm-fallback plan (degraded flag, synthetic GUID, subtag-ack via ack-comment, single-subscribe primary). |
+| 8 | Code organization & conventions | No issues found — new suites live under `MxAccess/`; test doubles are per-file (acceptable for these narrow fakes). |
+| 9 | Testing coverage | Issues found: Worker.Tests-031 (`ProbeIntervalSeconds` throttle-active branch never exercised — every test uses `probeIntervalSeconds: 0`), Worker.Tests-033 (`SubtagAlarmStateMachine` ack-while-inactive and priority-subtag branches uncovered). |
+| 10 | Documentation & comments | No issues found — test XML docs match assertions; no misleading names observed. |
+
 ## 2026-05-24 re-review (commit `42b0037`)
 
 **Re-review: no new findings.** `git diff --name-only d692232..42b0037 -- src/ZB.MOM.WW.MxGateway.Worker.Tests` returns empty — the Worker.Tests module has zero source changes since the previous review. All ten checklist categories therefore inherit "No issues found" from the `d692232` pass. The header is bumped to track the latest reviewed commit; Worker.Tests-001..030 remain closed.
@@ -533,3 +570,48 @@ findings (Worker.Tests-001 through -030) are unaffected.
 **Recommendation:** Either (a) reassign `CreateCancelEnvelope` to a sequence value `>` shutdown (or pass the sequence as a parameter, matching `CreateGatewayHelloEnvelope`'s parameter style), so the wire trace reads in ascending order; (b) add an XML-doc note on the cancel test stating that the worker has no inbound monotonicity check and the test ignores envelope sequence ordering; (c) parameterise all four helper methods so each test passes its desired sequence and the literal numbers stop carrying implicit meaning. Option (c) is the cleanest because `CreateGatewayHelloEnvelope` is already parameter-driven for nonce/version.
 
 **Resolution:** 2026-05-20 — Took option (c): parameterised `CreateGatewayHelloEnvelope`/`CreateCommandEnvelope`/`CreateCancelEnvelope`/`CreateShutdownEnvelope` with a `ulong sequence` argument (defaults 1/2/2/3 respectively, matching the typical Hello/Command/Cancel/Shutdown ordering), so the literal sequence values no longer carry implicit meaning. Updated the cancel-correlation test's wire trace to ascend (Hello=1, Cancel=2, Shutdown=3) and added a comment noting that the worker has no inbound monotonicity check — the parameter exists so multi-frame tests can pin the trace ordering explicitly when needed.
+
+### Worker.Tests-031
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Testing coverage |
+| Location | `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/FailoverAlarmConsumerTests.cs` (all `FailoverSettings` constructions) |
+| Status | Resolved |
+
+**Description:** Every `FailoverSettings` in `FailoverAlarmConsumerTests` is built with `probeIntervalSeconds: 0`, which deliberately *disables* the probe throttle. The throttle-active branch in `FailoverAlarmConsumer.ProbeOnce` (`src/ZB.MOM.WW.MxGateway.Worker/MxAccess/FailoverAlarmConsumer.cs:211-215`) — where a probe is *skipped* because fewer than `ProbeIntervalSeconds` have elapsed since `lastProbeAtUtc` — is therefore never exercised. This is a genuine production behaviour: the failback cadence is the only thing preventing a degraded worker from hammering the broken primary with a `PollOnce` on every timer tick, and `AlarmCommandHandlerTests.Subscribe_AutoModeWithWatchList_...` wires a real non-zero `FailbackProbeIntervalSeconds = 1` into the handler, so the throttle is on the live path. A regression that inverted the comparison (probing only *after* the interval became `>=` instead of skipping while `<`), dropped the `lastProbeAtUtc` update, or removed the throttle entirely would not be caught by any test. The task brief named "ProbeIntervalSeconds enforcement" as an explicit focus area.
+
+**Recommendation:** Add a test that constructs `FailoverSettings(threshold: 1, probeIntervalSeconds: <N>, stableProbes: 1)` with a non-zero interval, forces failover, makes the primary healthy, then calls `ProbeOnce()` twice in quick succession and asserts the second call did *not* probe (e.g. assert `primary.Polls` advanced by exactly one and `Mode` is still `Subtag`). Because the throttle reads `DateTime.UtcNow` directly, either accept a coarse same-wall-clock-instant assertion (two back-to-back calls reliably fall inside any interval ≥ 1s) or, preferably, refactor `ProbeOnce` to take an injectable clock so the throttle boundary can be pinned deterministically without wall-clock dependence (consistent with the Worker.Tests-020 manual-time-source approach).
+
+**Resolution:** 2026-06-15 — Took the coarse same-wall-clock-instant approach (no production-code clock injection needed). Added `FailoverAlarmConsumerTests.ProbeOnce_WithNonZeroInterval_ThrottlesSecondProbeWithinInterval`: builds `FailoverSettings(threshold: 1, probeIntervalSeconds: 3600, stableProbes: 5)`, forces failover to Subtag, makes the primary healthy, then calls `ProbeOnce()` twice back-to-back. The first probe re-polls the primary (`primary.Polls == 1`); the second falls inside the 3600s interval and is throttled, so `primary.Polls` is unchanged and `Mode` stays `Subtag`. `stableProbes: 5` keeps a single clean probe from failing back, so the throttled `ProbeOnce` path stays in scope. A 1-hour interval makes the two back-to-back calls reliably fall inside the window without any timing flakiness.
+
+### Worker.Tests-032
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Error handling & resilience |
+| Location | `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/FailoverAlarmConsumerTests.cs` |
+| Status | Resolved |
+
+**Description:** Two resilience branches of `FailoverAlarmConsumer` are uncovered by the new tests. (1) `RunPrimary` catches `Exception ex when (ex is not OutOfMemoryException)` (`FailoverAlarmConsumer.cs:295`) — the OOM-safe catch path the task brief explicitly called out. No test throws `OutOfMemoryException` from the primary to verify it *propagates* (rather than being swallowed and counted toward the failover threshold like every other exception); the `FlakyPrimary` fake throws only `COMException`. A regression that broadened the filter to swallow OOM would convert a fatal allocation failure into a silent failover. (2) The `FailoverSettings` constructor clamps `threshold < 1 → 1` and `stableProbes < 1 → 1` (`FailoverSettings.cs:38-40`); no test passes a sub-1 value to confirm the clamp, so a misconfigured `ConsecutiveFailureThreshold = 0` from the gateway could change failover semantics undetected.
+
+**Recommendation:** Add a `FlakyPrimary`-style fake (or a flag on the existing one) that throws `OutOfMemoryException` from `PollOnce`, and assert `sut.PollOnce()` rethrows it via `Assert.Throws<OutOfMemoryException>` and that no `ProviderModeChanged` fired. Add a small `FailoverSettings` fact (or `[Theory]`) asserting `new FailoverSettings(0, 0, 0).Threshold == 1` and `.StableProbes == 1` to pin the clamp.
+
+**Resolution:** 2026-06-15 — Added a `ThrowOutOfMemoryOnPoll` flag to the existing `FlakyPrimary` fake (its `PollOnce` throws `OutOfMemoryException` when set, checked before the `COMException` branch). Regression test `FailoverAlarmConsumerTests.RunPrimary_WhenPrimaryThrowsOutOfMemory_PropagatesAndDoesNotFailOver` drives `PollOnce` through the primary, asserts `Assert.Throws<OutOfMemoryException>`, and asserts no `ProviderModeChanged` fired and `Mode` stays `Alarmmgr` — pinning that the `when (ex is not OutOfMemoryException)` filter lets OOM propagate rather than swallowing it and counting it toward the failover threshold. The clamp is pinned by `FailoverSettings_ClampsSubMinimumValues` (a `[Theory]`): `(0,0,0)→(1,0,1)`, `(-5,-5,-5)→(1,0,1)`, and a pass-through `(3,7,2)→(3,7,2)` to confirm in-range values are not altered.
+
+### Worker.Tests-033
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/SubtagAlarmStateMachineTests.cs` |
+| Status | Resolved |
+
+**Description:** `SubtagAlarmStateMachineTests` covers the core transition matrix and the acked latch well, but two branches of the new state machine are unexercised. (1) The ack-while-inactive path in `SubtagAlarmStateMachine.ApplyAcked` (`src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SubtagAlarmStateMachine.cs:156-164`): when `.acked` flips true while the alarm is *not* active, the machine must emit nothing and must *not* set `AckedDuringEpisode` — otherwise a stale ack from a prior episode could mis-latch the next raise into a spurious `ACK_RTN`. No test drives an `.acked` change without a preceding active raise. (2) The priority-subtag path (`SubtagRole.Priority` → `state.Priority = CoerceInt(...)`, line 76-78): `SubtagAlarmConsumerTests.Subscribe_AdvisesAllSubtagsIncludingAckComment` confirms the priority subtag is *advised*, but no test raises a priority value change and asserts it flows into the emitted/snapshot record's `Priority`, so `CoerceInt` and the priority assignment are untested in the state-machine layer.
+
+**Recommendation:** Add (a) `AckedTrueWhileInactive_EmitsNothingAndDoesNotLatch` — apply `.acked=true` with no prior active raise, assert `Apply` returns empty, then raise active and clear and assert the clear emits `UnackRtn` (proving the stale ack did not latch); and (b) `PriorityChange_FlowsIntoEmittedRecord` — apply a priority value then an active raise and assert the emitted record's `Priority` equals the supplied value (and a `CoerceInt` string/garbage case falls back).
+
+**Resolution:** 2026-06-15 — Added both tests to `SubtagAlarmStateMachineTests`. `AckedTrueWhileInactive_EmitsNothingAndDoesNotLatch` applies `.acked=true` with no preceding active raise (asserts `Apply` returns empty), then drives a fresh raise→clear episode and asserts the clear emits `UnackRtn` — proving the stale inactive ack did not latch `AckedDuringEpisode`. `PriorityChange_FlowsIntoEmittedRecord` (the target now includes a `PrioritySubtag`) applies an `int` priority `750` (asserts the priority change emits nothing), raises active and asserts the emitted record's `Priority == 750` (exercising `CoerceInt`'s `int` path and the priority assignment), then applies a non-numeric `"not-a-number"` priority and asserts the snapshot `Priority` is still `750` (the `CoerceInt` string fallback keeps the prior value, not zero).

code-reviews/Worker/findings.md

@@ -4,11 +4,38 @@
 |---|---|
 | Module | `src/ZB.MOM.WW.MxGateway.Worker` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |
 
+## 2026-06-15 re-review (commit `410acc9`)
+
+Re-review of the `42b0037..410acc9` diff — the alarm-provider subtag-fallback
+feature (`git diff 42b0037..410acc9 -- src/ZB.MOM.WW.MxGateway.Worker/`). New
+substantive code: `SubtagAlarmConsumer`, `SubtagAlarmStateMachine`,
+`FailoverAlarmConsumer`, `LmxSubtagAlarmSource`, `SyntheticAlarmGuid`,
+`AlarmProviderModeChange`, `FailoverSettings`, `ISubtagAlarmSource` /
+`SubtagValueChange`, plus the degraded/`source_provider` propagation in
+`AlarmDispatcher` / `MxAccessAlarmEventSink` / `MxAccessEventMapper`, the
+`ForcedMode`/watch-list routing and STA-COM-factory threading in
+`AlarmCommandHandler` / `MxAccessStaSession`, and the `SubscribeAlarmsCommand`
+re-plumb in `MxAccessCommandExecutor`. Three new findings: **Worker-026** (High),
+**Worker-027** (Medium), **Worker-028** (Low). Worker-001..025 remain closed.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | No issues found. Subtag synthesis (`SubtagAlarmStateMachine` raise/ack/clear, `AckedDuringEpisode` latch, segment-boundary name derivation), exact-match ack resolution (`ResolveTargetByName` avoids the prefix false-positive), and `MapTransition`'s `Unspecified→*Alm` raise path are all sound. |
+| 2 | mxaccessgw conventions | No issues found. The synthesis is worker-side and every degraded record/event carries `degraded=true` + `source_provider=SUBTAG`, satisfying the explicit opt-in non-parity exception to the "never synthesize events" rule. The gateway never instantiates COM. net48 constraint respected — `AlarmProviderModeChange`/`FailoverSettings` are plain classes with get-only ctor-assigned props (no init/positional records); no `WriteRecord`-style init usage introduced. |
+| 3 | Concurrency & thread safety | Issue found: Worker-026 (an exception in the failover switch path — `SwitchToStandby`'s priming snapshot or either switch's `ProviderModeChanged` handler — escapes the state machine after `active` has already flipped, killing the STA alarm-poll loop with no mode-changed event). STA affinity itself is sound: `LmxSubtagAlarmSource` owns its own apartment-bound `LMXProxyServerClass`, all consumer calls are STA-confined via `AlarmCommandHandler`'s affinity guard, and `Dispose` UnAdvises before tearing handles down so a late pump callback cannot re-enter. |
+| 4 | Error handling & resilience | Issue found: Worker-027 (`SyntheticAlarmGuid` uses `MD5.Create()`, which throws on a net48 FIPS-policy host — breaking every subtag transition stamp and snapshot, and feeding Worker-026's poll-loop-kill path). `FailoverSettings` clamps tunables to safe minimums; `LmxSubtagAlarmSource` teardown is best-effort/idempotent. |
+| 5 | Security | No issues found. No secret/credential logging on the alarm path; ack comments are operator-supplied alarm metadata, not secrets. Synthetic GUID is non-cryptographic by design and not a security control. |
+| 6 | Performance & resource management | No issues found. `LmxSubtagAlarmSource` releases its COM object via `FinalReleaseComObject` and tracks advised-vs-added handles so `Dispose` only UnAdvises what it advised. The standby is armed once and gated-by-active rather than churning subscribe/unsubscribe per switch. |
+| 7 | Design-document adherence | No issues found. Implementation matches `docs/plans/2026-06-13-alarm-subtag-fallback-design.md` (auto-failover/failback, ack-comment-write ack, worker-side synthesis, additive proto fields). The probe re-polls the still-subscribed primary (single-subscribe constraint) as the design's "Superseded" notes describe. |
+| 8 | Code organization & conventions | Issue found: Worker-028 (the dup-subtag-address guard in `SubtagAlarmStateMachine.Bind` does not cover duplicate `AlarmFullReference` entries, which silently overwrite in `targetsByReference`/`_statesByReference`). One-public-type-per-file is otherwise respected for the new files. |
+| 9 | Testing coverage | No standalone finding. New unit suites exist for each major component (`SubtagAlarmConsumerTests`, `SubtagAlarmStateMachineTests`, `FailoverAlarmConsumerTests`, `LmxSubtagAlarmSourceTests`, `SyntheticAlarmGuidTests`), matching the design's test matrix. The switch-path exception fragility (Worker-026) and the dup-reference case (Worker-028) are untested edge cases noted in those findings. |
+| 10 | Documentation & comments | No issues found. The new types carry accurate XML docs; the net48-constraint rationale is documented inline on `FailoverSettings`/`AlarmProviderModeChange`; the "why PollOnce only, no re-Subscribe" and probe-throttle behaviour are documented on `FailoverAlarmConsumer.ProbeOnce`. |
+
 ## 2026-05-24 re-review (commit `42b0037`)
 
 **Re-review: no new findings.** `git diff --name-only d692232..42b0037 -- src/ZB.MOM.WW.MxGateway.Worker` returns empty — the Worker module has zero source changes since the previous review. All ten checklist categories therefore inherit "No issues found" from the `d692232` pass. The header is bumped to track the latest reviewed commit; Worker-001..025 remain closed.
@@ -464,3 +491,50 @@ _runtimeSession = _runtimeSessionFactory()
 Match the pattern `AlarmCommandHandler.Subscribe` already uses for `consumerFactory()` (`AlarmCommandHandler.cs:76-77`).
 
 **Resolution:** 2026-05-20 — `WorkerPipeSession.RunAsync` now uses `_runtimeSession = _runtimeSessionFactory() ?? throw new InvalidOperationException("Worker runtime session factory returned null.");`, matching the pattern `AlarmCommandHandler.Subscribe` uses for its `consumerFactory()`. A null factory return now produces a clear diagnostic exception at the call site instead of NRE-ing on the next dereference (and the `finally` block's `_runtimeSession?.Dispose()` silently no-oping on a half-initialized session). Regression test `WorkerPipeSessionTests.RunAsync_WhenRuntimeSessionFactoryReturnsNull_ThrowsDiagnosticException` drives `RunAsync` with `() => null!` and asserts the diagnostic `InvalidOperationException` is thrown with the expected message.
+
+### Worker-026
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Concurrency & thread safety |
+| Location | `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/FailoverAlarmConsumer.cs:289-338`, `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs:307-320` |
+| Status | Resolved |
+
+**Description:** `FailoverAlarmConsumer.SwitchToStandby` flips `active = Active.Standby` / `mode = Subtag` first, then calls `_ = standby.SnapshotActiveAlarms();` (the priming side-effect), and only then calls `RaiseModeChanged(...)`. If `standby.SnapshotActiveAlarms()` throws, the exception escapes `SwitchToStandby`, escapes the `catch` in `RunPrimary`, and escapes `FailoverAlarmConsumer.PollOnce`/`Subscribe`. The `SubtagAlarmConsumer.SnapshotActiveAlarms` path is not exception-free: it calls `StampSynthetic` → `SyntheticAlarmGuid.ForReference` (which throws on a FIPS host — see Worker-027) and walks live state. The same exposure exists for `RaiseModeChanged` itself: the attached `AlarmCommandHandler.OnProviderModeChanged` handler runs synchronously and calls `eventQueue.Enqueue(...)`, which throws `MxAccessEventQueueOverflowException` at capacity; that also propagates out of both `SwitchToStandby` and `SwitchToPrimary`.
+
+When this happens the consumer has **already** transitioned `active`/`mode` to Standby (or Primary) but the `ProviderModeChanged` event is never emitted — so the gateway never learns the feed went degraded. Worse, because the failover calls run on the worker's STA inside `RunAlarmPollLoopAsync`, the escaping exception lands in that loop's trailing `catch (Exception)` arm (`MxAccessStaSession.cs:307-320`), which records a single fault and **permanently stops the alarm poll loop**. The standby is then never pumped or probed again — i.e. a transient primary COM fault that should have produced a clean degraded-mode handoff instead produces a total, undetected alarm outage for the session, defeating the entire purpose of the fallback feature. There is no safe operator workaround short of restarting the session.
+
+**Recommendation:** Make the switch atomic and exception-isolated: raise `ProviderModeChanged` (and perform the priming snapshot) inside their own `try`/`catch` so a snapshot or handler failure cannot abort the switch or unwind into the poll loop. Order the state flip so the mode-changed notification is guaranteed to fire even if priming fails (e.g. flip state, raise mode-changed in a guarded block, then attempt the priming snapshot in a separate guarded block whose failure is logged/faulted but non-fatal). Add a regression test where the standby's `SnapshotActiveAlarms` throws on the first call after failover, asserting (a) `ProviderModeChanged` still fires and (b) `PollOnce` does not rethrow.
+
+**Resolution:** 2026-06-15 — Reordered and exception-isolated the failover switch in `FailoverAlarmConsumer`. `SwitchToStandby` now flips `active`/`mode`, then raises `ProviderModeChanged` FIRST (so the gateway always learns the feed went degraded), then primes the standby snapshot via a new `TryPrimeStandbySnapshot()` whose failure is swallowed (`catch when ex is not OutOfMemoryException`) — a priming failure can no longer abort the switch or unwind into the poll loop. `RaiseModeChanged` itself now wraps `ProviderModeChanged?.Invoke` in a `try`/`catch (when ex is not OutOfMemoryException)` so a subscriber handler exception (e.g. `AlarmCommandHandler.OnProviderModeChanged`'s `eventQueue.Enqueue` overflowing) cannot escape `SwitchToStandby`/`SwitchToPrimary` into `RunAlarmPollLoopAsync`'s trailing catch and permanently stop alarm polling. `OutOfMemoryException` is deliberately allowed to propagate. The MXAccessStaSession poll-loop arm is unchanged — the fix prevents the escape rather than catching it there. Regression tests in `FailoverAlarmConsumerTests`: `Failover_WhenStandbyPrimingSnapshotThrows_StillRaisesModeChangeAndDoesNotRethrow` (standby `SnapshotActiveAlarms` throws on the priming call → `ProviderModeChanged` still fires, `Mode` is Subtag, `Subscribe`/`PollOnce` do not rethrow) and `Failover_WhenModeChangedHandlerThrows_SwitchStillTakesEffectAndDoesNotRethrow` (a throwing `ProviderModeChanged` subscriber → switch still takes effect, no rethrow).
+
+### Worker-027
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SyntheticAlarmGuid.cs:38-40` |
+| Status | Resolved |
+
+**Description:** `SyntheticAlarmGuid.ForReference` derives the deterministic alarm GUID via `using MD5 md5 = MD5.Create();`. The worker targets .NET Framework 4.8, where `MD5.Create()` returns `MD5CryptoServiceProvider`. When the host has the Windows FIPS-compliance policy enabled (`Enabled=1` under `HKLM\System\CurrentControlSet\Control\Lsa\FIPSAlgorithmPolicy`), the non-validated `MD5CryptoServiceProvider` constructor throws `InvalidOperationException` ("This implementation is not part of the Windows Platform FIPS validated cryptographic algorithms."). `SyntheticAlarmGuid.ForReference` is on the hot path of the subtag fallback: `SubtagAlarmConsumer.StampSynthetic` calls it for **every** synthesized transition and **every** snapshot record. On a FIPS host the subtag fallback therefore throws on first use; combined with Worker-026 that exception kills the STA alarm-poll loop, so the fallback is not merely degraded but completely non-functional exactly when it is needed (after the primary alarmmgr provider has failed). The comment already notes MD5 is "never for security" — the issue is availability under FIPS policy, not cryptographic strength. The regulated deployment hosts (Zimmer) are a plausible FIPS environment.
+
+**Recommendation:** Replace `MD5.Create()` with a FIPS-agnostic non-cryptographic 128-bit hash that does not route through the crypto FIPS gate — e.g. compute the 16 GUID bytes from a stable hash that does not use `System.Security.Cryptography` (a fixed FNV-1a / xxHash-style derivation over the UTF-8 bytes), or use `SHA256` truncated to 16 bytes via the managed `SHA256Managed`/`IncrementalHash` only if confirmed FIPS-safe on net48 (it is not guaranteed — prefer the non-crypto route). The mapping only needs determinism and collision resistance for distinct references, not cryptographic properties. Add a test that exercises `ForReference` without depending on a crypto provider.
+
+**Resolution:** 2026-06-15 — Replaced the `MD5.Create()` derivation in `SyntheticAlarmGuid.ForReference` with a pure-managed FNV-1a hash: two independent 64-bit FNV-1a passes over the UTF-8 bytes (the high pass mixes the byte index into its accumulator to decorrelate the halves) fill the low/high 64 bits of the 128-bit GUID, and the input length is folded in so the empty string is non-degenerate (never `Guid.Empty`). The `using System.Security.Cryptography;` import is gone, so no FIPS-gated `MD5CryptoServiceProvider` is ever constructed — the subtag fallback no longer throws on a FIPS-policy host. The derivation stays deterministic and distinct-per-reference. The existing `SyntheticAlarmGuidTests` (`SameReference_SameGuid`, `DifferentReference_DifferentGuid`, `Reference_ProducesNonEmptyGuid`) pin only those properties — not a specific GUID literal — so they continue to pass unchanged; no test needed a value update. Added regression tests `SyntheticAlarmGuidTests.EmptyReference_ProducesNonEmptyGuid` (length-fold guard against a degenerate all-zero result) and `ForReference_UnderFipsEnforcement_DoesNotThrowAndStaysDeterministic` (sets the managed `UseLegacyFipsThrow` AppContext switch and asserts the derivation still succeeds deterministically; a regression reintroducing a FIPS-gated provider would throw here).
+
+### Worker-028
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SubtagAlarmStateMachine.cs:43-52`, `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SubtagAlarmConsumer.cs:70-75` |
+| Status | Resolved |
+
+**Description:** `SubtagAlarmStateMachine.Bind` throws `ArgumentException` on a duplicate subtag **item address** (the documented dup-address guard), but neither the state machine nor `SubtagAlarmConsumer` guards against a duplicate `AlarmFullReference` in the watch list. When two `AlarmSubtagTarget` entries share an `AlarmFullReference` but use different subtag addresses, `_statesByReference[target.AlarmFullReference] = state` and `targetsByReference[reference] = target` each silently overwrite the earlier entry, while the earlier target's subtag addresses are still bound to an orphaned `AlarmState`. The orphaned state is mutated by incoming value changes but is invisible to `SnapshotActive` (which iterates only the surviving `_statesByReference.Values`) and to ack resolution (which uses the surviving `targetsByReference`). The result is silently inconsistent synthesized state for that reference. This is a watch-list configuration error (the gateway resolves the watch list), so impact is limited, but the asymmetry — addresses are guarded, references are not — is surprising and silent.
+
+**Recommendation:** Add a duplicate-`AlarmFullReference` guard symmetric with the dup-address guard: throw a descriptive `ArgumentException` from the `SubtagAlarmStateMachine` (or `SubtagAlarmConsumer`) constructor when two watch-list entries share a reference, so a misconfigured watch list fails fast at subscribe time rather than producing silently inconsistent state. Cover it with a unit test.
+
+**Resolution:** 2026-06-15 — Added a duplicate-`AlarmFullReference` guard in the `SubtagAlarmStateMachine` constructor symmetric with the existing dup-address guard in `Bind`: before adding each target's `_statesByReference` entry it checks `ContainsKey` (the dictionary is `OrdinalIgnoreCase`, matching the consumer's `targetsByReference` lookup) and throws a descriptive `ArgumentException` ("Duplicate alarm full reference '{reference}' is bound to more than one alarm target."). Because `SubtagAlarmConsumer` constructs the state machine before populating its own `targetsByReference`, this guard fires before the consumer's silent overwrite too, covering both dictionaries from one canonical check. Regression test `SubtagAlarmStateMachineTests.DuplicateAlarmFullReference_Throws` (two targets sharing a reference but using distinct active subtags → `ArgumentException`).

docs/AlarmClientDiscovery.md

@@ -790,3 +790,159 @@ Post-ack transition: kind=Clear …
 
 10s cadence held throughout; full proto fields populated correctly;
 ack registered server-side without errors.
+
+## Subtag-monitoring fallback provider
+
+When the wnwrap alarm-manager source fails, the gateway worker switches to
+`SubtagAlarmConsumer` — a synthetic alarm source that advises each alarm
+attribute's subtags via the existing MXAccess `AddItem`/`Advise` pipeline and
+derives alarm transitions from the resulting value-change stream. This is a
+non-parity, degraded-mode source; every transition and snapshot it produces
+carries `degraded = true`.
+
+### Watch-list discovery
+
+`GatewayAlarmMonitor` resolves the subtag watch-list at subscribe time by
+calling `IAlarmWatchListResolver.GetAlarmAttributesAsync`. The resolver merges:
+
+1. Galaxy Repository SQL (`GetAlarmAttributesAsync`) — objects that have alarm
+   extensions in the configured area.
+2. Config overrides — `IncludeAttributes` adds explicit entries;
+   `ExcludeAttributes` removes Repository-derived ones. The config list takes
+   effect even when `UseGalaxyRepository` is `false`.
+
+The resolved list is a set of `AlarmSubtagTarget` messages sent to the worker
+inside `SubscribeAlarmsCommand.watch_list`. Each target carries the composed
+MXAccess item addresses for the `InAlarm`, `Acked`, `AckMsg`, and `Priority`
+subtags (confirmed AVEVA `AlarmExtension` field names, verified against the live
+ZB Galaxy `attribute_definition` rows). The gateway re-runs discovery on its
+reconcile cadence and pushes an updated watch-list when the model changes.
+
+Each target's canonical `AlarmFullReference` is composed as
+`Galaxy!{area}.{reference}` (literal `Galaxy` provider). The `{area}` is the
+alarm object's **real Galaxy area** — discovered per object via
+`gobject.area_gobject_id` (`GetAlarmAttributesAsync` projects it as `area_name`)
+— so the synthesized reference's group matches exactly the area the native
+alarmmgr (wnwrap) emits for the same alarm (e.g. `TestMachine_001` in `TestArea`
+yields `Galaxy!TestArea.TestMachine_001.TestAlarm001`). The configured
+`Discovery.Area` / `DefaultArea` is **only** the fallback for explicit
+`IncludeAttributes` entries, which carry no discovered area.
+
+### Subtag advise and `LmxSubtagAlarmSource`
+
+`LmxSubtagAlarmSource` (implements `ISubtagAlarmSource`) owns a separate
+`LMXProxyServerClass` instance on the worker STA — it does not share the
+session's main MXAccess object. For each watch-list target it calls
+`AddItem`/`Advise` on the configured subtag addresses. When a subtag value
+changes, it raises `ValueChanged` on the STA and `SubtagAlarmConsumer`
+forwards it to `SubtagAlarmStateMachine`.
+
+`PollOnce()` on the subtag consumer is a no-op — the path is event-driven
+through `Advise`, not poll-driven.
+
+### Synthesis rules
+
+`SubtagAlarmStateMachine` tracks `(active, acked)` per watch-list entry and
+emits `MxAlarmTransitionEvent` records on change:
+
+| Subtag change | Emitted transition | Notes |
+|---|---|---|
+| `InAlarm` false → true | Raise (`UNACK_ALM`) | `original_raise_timestamp` = first observed active time for this episode |
+| `Acked` false → true, while `InAlarm` | Acknowledge (`ACK_ALM`) | `AckedDuringEpisode` latch set |
+| `InAlarm` true → false | Clear | `AckRtn` if `AckedDuringEpisode` is set, else `UnackRtn` |
+| `Acked` true → false, while `InAlarm` | (none) | Latch is NOT cleared; the episode retains its acknowledged status at clear |
+
+The `AckedDuringEpisode` latch addresses out-of-order subtag delivery:
+MXAccess does not guarantee the `Acked = false` update arrives before the
+`InAlarm = false` update. The latch ensures a clear always emits `ACK_RTN`
+when the alarm was acknowledged at any point during the active episode.
+
+`SnapshotActive()` returns one `MxAlarmSnapshotRecord` per currently-active
+alarm. State mapping:
+
+- `InAlarm && !Acked` → `UNACK_ALM`
+- `InAlarm && Acked` → `ACK_ALM`
+- `!InAlarm` → not included in the snapshot
+
+### Synthetic GUID
+
+The alarmmgr provider supplies a native GUID per alarm record. The subtag
+provider has no native GUID. `SubtagAlarmConsumer` derives a deterministic
+GUID by hashing `alarm_full_reference` (via `SyntheticAlarmGuid.ForReference`).
+The same reference always produces the same GUID within a session, so
+GUID-based ack routing resolves correctly. The GUID is not stable across
+different alarm references or gateway restarts in the sense of matching any
+AVEVA-internal GUID.
+
+### Acknowledge in subtag mode
+
+`AlarmDispatcher` routes ack calls by active provider mode:
+
+- **Alarm-manager mode:** `AlarmAckByName` on `wwAlarmConsumerClass` (unchanged).
+- **Subtag mode:** `SubtagAlarmConsumer.AcknowledgeByName` resolves the
+  watch-list entry's `ack_comment_subtag` and issues a `Write(comment)` on
+  the STA via `LmxSubtagAlarmSource`. Writing the `AckMsg` subtag performs
+  the acknowledge in AVEVA (`AckMsg` is the confirmed `AlarmExtension` ack-comment
+  write target).
+
+If the alarm has no writable ack-comment subtag (`AckComment` config key is
+empty, or the entry's `ack_comment_subtag` field is empty), the ack call
+returns a failure code that the gateway surfaces as `FailedPrecondition`.
+`AcknowledgeByGuid` maps the synthetic GUID back to its reference via an
+internal dictionary, then calls the same write path.
+
+`SubtagAlarmConsumer.Subscribe` advises the ack-comment subtag alongside the
+observed ones (active/acked/priority). This is required: MXAccess rejects a
+write to an item that has been added but not advised with `E_INVALIDARG`
+("Value does not fall within the expected range"). Advising it at subscribe
+time makes it an active item so the later ack write succeeds — its value
+changes carry no transition (the state machine ignores unmapped addresses).
+
+### Live validation
+
+The subtag path was validated against live MXAccess on the dev rig
+(`DESKTOP-6JL3KKO`, Galaxy `DEV`, `TestMachine_001.TestAlarm001`):
+
+- `…​.InAlarm` → `True` (Boolean), `…​.Acked` → `False` (Boolean),
+  `…​.Priority` → `500` (Int32), `…​.AckMsg` → string — confirming the field
+  names **and** the runtime reference shape `<Object>.<AlarmAttr>.<field>`
+  with **no** intermediate alarm-condition segment.
+- `AcknowledgeByName` (AckMsg write) returned `0` once the ack-comment subtag
+  was advised — confirming the ack-by-comment-write mechanism end to end.
+
+### Fidelity limitations
+
+The following fields are not available or have lower quality in subtag mode:
+
+| Field | Subtag-mode behavior |
+|-------|---------------------|
+| `alarm_guid` | Synthetic deterministic GUID from `alarm_full_reference`; not an AVEVA-native GUID |
+| `original_raise_timestamp` | First observed `active = true` time; no AVEVA-native raise time |
+| `transition_timestamp` | `OnDataChange` source timestamp from MXAccess |
+| `severity` | From priority subtag if advised; 0 otherwise |
+| `category` / `description` | Not populated (no subtag for these) |
+| `current_value` / `limit_value` | Not populated unless corresponding subtags are in the watch-list |
+| `alarm_type_name` | Not populated |
+| `operator_user` / `operator_comment` | Not populated on synthesized raise/clear transitions |
+| `retrigger` transition | Not synthesized (no re-alarm counter subtag is observed) |
+
+Every transition and snapshot record carries `degraded = true` and
+`source_provider = ALARM_PROVIDER_MODE_SUBTAG`. Clients that require full
+fidelity must wait for failback to the alarm manager.
+
+### Provider mode reflection
+
+When `FailoverAlarmConsumer` switches between providers, it raises
+`ProviderModeChanged`. `AlarmDispatcher` enqueues an
+`OnAlarmProviderModeChangedEvent` (carried as an `MxEvent`), which the
+gateway receives and reflects into:
+
+- `AlarmFeedMessage.provider_status` emitted to every `StreamAlarms`
+  subscriber.
+- The `/hubs/alarms` SignalR hub for the dashboard.
+- Metrics: `mxgateway.alarms.provider_mode` gauge and
+  `mxgateway.alarms.provider_switches` counter.
+
+On every switch `GatewayAlarmMonitor` also forces a reconcile
+(`QueryActiveAlarms`) against the now-active provider so the gateway cache
+reflects the post-switch state without a spurious raise/clear storm.

docs/DesignDecisions.md

@@ -411,6 +411,58 @@ a per-channel skip-verify hook:
 See [Gateway Configuration — Automatic self-signed certificate](./GatewayConfiguration.md#automatic-self-signed-certificate)
 and the per-client READMEs for the as-built behavior.
 
+## Alarm-Manager to Subtag Fallback
+
+Decision: add a second alarm provider (subtag monitoring) that the worker
+activates automatically when the native wnwrap alarm manager fails, and fails
+back to automatically when the manager recovers.
+
+### Worker-side synthesis
+
+Synthesis of alarm transitions from subtag value changes happens entirely in
+the worker (`SubtagAlarmConsumer` / `SubtagAlarmStateMachine`). The gateway
+still forwards only events the worker emits and synthesizes nothing itself.
+This satisfies the parity rule even though the subtag path is inherently
+non-parity: the parity rule governs where synthesis lives, not whether
+synthesis is permitted when the native source is unavailable.
+
+### Degraded is explicit
+
+Every subtag-mode transition carries `degraded = true` on the
+`OnAlarmTransitionEvent` and `ActiveAlarmSnapshot` proto messages, and the
+`AlarmFeedMessage` feed carries an `AlarmProviderStatus` payload on stream
+open and on every switch. No client can mistake a subtag-mode alarm for an
+authoritative alarmmgr record. Subtag mode has lower fidelity: synthetic
+deterministic GUID (SHA-derived from the alarm reference), best-effort
+original-raise timestamp, narrower field set. Clients that need full fidelity
+must wait for failback.
+
+### Failover trigger
+
+The failover trigger is N consecutive wnwrap COM failures — a `COMException`
+thrown by `Subscribe` or `PollOnce`, or a failure HRESULT from
+`GetXmlCurrentAlarms2`. A single poll failure does not trigger a switch; the
+threshold (default 3, floored at 1) guards against transient COM hiccups. The
+counter resets on any clean poll so a flapping provider does not permanently
+latch in subtag mode.
+
+### Acknowledge via ack-comment write
+
+In subtag mode, `AcknowledgeAlarm` writes the operator comment to the alarm
+attribute's ack-comment subtag (`Fallback:Subtags:AckComment`). The write
+performs the native ack in AVEVA. This differs from alarmmgr mode, where
+`AlarmAckByName` on `wwAlarmConsumerClass` is called directly. The `AckComment`
+subtag name is empty by default; configuring it is required for ack to work in
+subtag mode. The exact AVEVA subtag names are not hard-coded — the `Subtags`
+config block exists precisely so names are not guessed without validation
+against the live MXAccess attribute set.
+
+### Related documentation
+
+- [Gateway Configuration — Alarm Fallback options](./GatewayConfiguration.md#alarm-fallback-options)
+- [Alarm Client Discovery — Subtag provider](./AlarmClientDiscovery.md)
+- [gRPC Contract — provider_status and degraded fields](./Grpc.md)
+
 ## Later Revisit Items
 
 These are explicit post-v1 revisit items, not open blockers:

docs/GatewayConfiguration.md

@@ -148,6 +148,7 @@ the affected stream while the MXAccess session remains active.
 | `MxGateway:Dashboard:Enabled` | `true` | Enables Blazor Server dashboard route mapping. The dashboard mounts at the host root (`/`); there is no separate path-base prefix. |
 | `MxGateway:Dashboard:AllowAnonymousLocalhost` | `true` | Allows loopback dashboard requests to bypass the dashboard cookie requirement for local development. Remote requests still require dashboard authentication. |
 | `MxGateway:Dashboard:RequireHttpsCookie` | `true` | Sets the dashboard auth cookie's secure policy. `true` keeps `CookieSecurePolicy.Always` — the cookie is only sent over HTTPS, which matches a production HTTPS deployment. Set to `false` for plain-HTTP dev deployments to use `CookieSecurePolicy.SameAsRequest`; the cookie is still flagged Secure on HTTPS requests, but it can round-trip over HTTP. Browsers drop Secure cookies set over HTTP from non-localhost hosts, so leaving this `true` while serving the dashboard over plain HTTP will break login from any remote browser. |
+| `MxGateway:Dashboard:CookieName` | `MxGatewayDashboard` | Dashboard auth cookie name. Leave unset (null/blank) to use the default. Override it to give a distinct name to a gateway that shares a hostname with another gateway instance: browser cookies are scoped by host+path but **not** by port, so two instances on the same host would otherwise clobber each other's dashboard session under a shared cookie name. Changing it signs out existing dashboard sessions on next deploy. |
 | `MxGateway:Dashboard:SnapshotIntervalMilliseconds` | `1000` | Dashboard snapshot refresh interval used by the snapshot SignalR hub and the pages that subscribe to it. |
 | `MxGateway:Dashboard:RecentFaultLimit` | `100` | Maximum number of fault summaries projected into each dashboard snapshot. |
 | `MxGateway:Dashboard:RecentSessionLimit` | `200` | Maximum number of session summaries projected into each dashboard snapshot. |
@@ -229,6 +230,75 @@ behavior.
 The alarm monitor is independent of client sessions: `AcknowledgeAlarm` and
 `StreamAlarms` are session-less RPCs served by the monitor.
 
+### Alarm fallback options
+
+The `Fallback` sub-section controls how the alarm feed selects between the
+native wnwrap alarm-manager provider and the subtag-monitoring fallback.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `MxGateway:Alarms:Fallback:Mode` | `Auto` | Provider selection mode. `Auto` uses the alarm manager as primary and fails over to subtag monitoring after consecutive COM failures, then fails back automatically. `ForceAlarmManager` disables failover. `ForceSubtag` forces subtag monitoring on from startup. Values are case-insensitive. |
+| `MxGateway:Alarms:Fallback:ConsecutiveFailureThreshold` | `3` | Number of consecutive wnwrap COM failures (`COMException` or failure HRESULT from `Subscribe` / `GetXmlCurrentAlarms2`) before the monitor switches to subtag mode. Floored at 1. |
+| `MxGateway:Alarms:Fallback:FailbackProbeIntervalSeconds` | `30` | While in subtag mode, how often (in seconds) the monitor probes the wnwrap provider to detect recovery. Floored at 1. |
+| `MxGateway:Alarms:Fallback:FailbackStableProbes` | `3` | Number of consecutive clean wnwrap probes required before the monitor switches back to the alarm manager. Floored at 1. |
+| `MxGateway:Alarms:Fallback:Discovery:UseGalaxyRepository` | `true` | When `true`, the monitor queries the Galaxy Repository SQL database to build the subtag watch-list for the configured area. |
+| `MxGateway:Alarms:Fallback:Discovery:Area` | _(empty)_ | Galaxy area to scope the Repository query to. Falls back to `MxGateway:Alarms:DefaultArea` when empty. Ignored when `UseGalaxyRepository` is `false`. This area is **not** used to compose a Repository-derived alarm's canonical `Galaxy!{area}.{reference}`: each discovered alarm uses its object's real Galaxy area (discovered via `gobject.area_gobject_id`), so the reference's group matches what the native alarmmgr emits. `Discovery:Area` / `DefaultArea` is used as the composition area only for explicit `IncludeAttributes` entries, which carry no discovered area. |
+| `MxGateway:Alarms:Fallback:Discovery:IncludeAttributes` | _(empty)_ | Explicit MXAccess attribute paths to add to the subtag watch-list, supplementing (or replacing, when `UseGalaxyRepository` is `false`) the Repository-derived list. |
+| `MxGateway:Alarms:Fallback:Discovery:ExcludeAttributes` | _(empty)_ | Attribute paths to remove from the merged watch-list (case-insensitive). The exclude is applied after the Repository-derived rows and the explicit `IncludeAttributes` entries are combined, so an exclude that matches an explicit include suppresses it too — excludes win. Ignored when `UseGalaxyRepository` is `false`. |
+| `MxGateway:Alarms:Fallback:Subtags:Active` | `InAlarm` | Subtag name for the in-alarm boolean. Confirmed AVEVA `AlarmExtension` field name. |
+| `MxGateway:Alarms:Fallback:Subtags:Acked` | `Acked` | Subtag name for the acknowledged boolean. Confirmed AVEVA `AlarmExtension` field name. |
+| `MxGateway:Alarms:Fallback:Subtags:AckComment` | `AckMsg` | Subtag name for the acknowledgement comment write target. Writing this subtag performs the acknowledge in AVEVA. Confirmed AVEVA `AlarmExtension` field name. When empty, the ack-comment write path is disabled. |
+| `MxGateway:Alarms:Fallback:Subtags:Priority` | `Priority` | Subtag name for the alarm priority / severity value. Confirmed AVEVA `AlarmExtension` field name. |
+
+Validation rules:
+
+- `Mode` must be `Auto`, `ForceAlarmManager`, or `ForceSubtag` (case-insensitive).
+- `Mode = ForceSubtag` with both `UseGalaxyRepository = false` and an empty
+  `IncludeAttributes` list produces a startup validation warning: the subtag
+  provider has no attributes to advise.
+- `ConsecutiveFailureThreshold`, `FailbackProbeIntervalSeconds`, and
+  `FailbackStableProbes` are floored at 1 by `GatewayOptionsValidator`.
+
+Full example with non-default fallback settings:
+
+```json
+{
+  "MxGateway": {
+    "Alarms": {
+      "Enabled": true,
+      "SubscriptionExpression": "\\\\SCADA01\\Galaxy!PlantArea",
+      "DefaultArea": "PlantArea",
+      "ReconcileIntervalSeconds": 30,
+      "Fallback": {
+        "Mode": "Auto",
+        "ConsecutiveFailureThreshold": 3,
+        "FailbackProbeIntervalSeconds": 30,
+        "FailbackStableProbes": 3,
+        "Discovery": {
+          "UseGalaxyRepository": true,
+          "Area": "",
+          "IncludeAttributes": [],
+          "ExcludeAttributes": []
+        },
+        "Subtags": {
+          "Active": "InAlarm",
+          "Acked": "Acked",
+          "AckComment": "AckMsg",
+          "Priority": "Priority"
+        }
+      }
+    }
+  }
+}
+```
+
+The defaults (`InAlarm`/`Acked`/`AckMsg`/`Priority`) are the confirmed AVEVA
+`AlarmExtension` primitive field names, verified by querying the live ZB Galaxy
+`attribute_definition` rows. The `Subtags` block exists so names can be
+overridden without a code change if a site's alarm template uses different
+attribute names. See `docs/AlarmClientDiscovery.md` for the synthesis rules that
+depend on these names.
+
 ## Host Endpoints and Transport Security (Kestrel)
 
 The listening endpoints are **not** part of the `MxGateway` section. The gateway

docs/GatewayTesting.md

@@ -215,13 +215,18 @@ beyond "LDAP is up." See the "Adding a gw-specific group" section of
 `glauth.md` for the provisioning step that adds `GwAdmin` and grants it to
 `admin`.
 
-The suite covers both the success path and the `DashboardAuthenticator` failure
-branches: `admin` whose LDAP groups resolve to the `Admin` role succeeds and
-emits the role claim; `readonly` is denied because no group in their `memberOf`
-appears in `GroupToRole`; `admin` with a wrong password is rejected by the
-candidate bind without leaking the password into `FailureMessage`; an unknown
-username yields no candidate; and an unreachable LDAP server is absorbed into a
-failed result rather than throwing.
+`DashboardAuthenticator` delegates the LDAP bind and group search to the shared
+`ZB.MOM.WW.Auth.Ldap` provider (`LdapAuthService`) and only maps the resulting
+groups to dashboard roles via `DashboardGroupRoleMapper`; the bind/search
+mechanics that decide each outcome live in that shared provider, not in
+`DashboardAuthenticator`.
+
+The suite covers both the success path and the failure outcomes: `admin` whose
+LDAP groups resolve to the `Admin` role succeeds and emits the role claim;
+`readonly` is denied because no group in their `memberOf` appears in
+`GroupToRole`; `admin` with a wrong password fails authentication without leaking
+the password into `FailureMessage`; an unknown username fails authentication; and
+an unreachable LDAP server is absorbed into a failed result rather than throwing.
 
 Run the LDAP live tests explicitly:
 

docs/Grpc.md

@@ -94,6 +94,73 @@ Carrying the enqueue timestamp into the worker layer is what lets queue-wait tim
 
 `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.
 
+#### Provider status on the alarm feed
+
+`AlarmFeedMessage` has a fourth `payload` case, `provider_status`, carrying
+an `AlarmProviderStatus` message:
+
+```protobuf
+message AlarmProviderStatus {
+  AlarmProviderMode mode = 1;
+  bool degraded = 2;       // true whenever mode == SUBTAG
+  string reason = 3;       // human-readable switch reason
+  google.protobuf.Timestamp since = 4;
+}
+```
+
+The gateway emits `provider_status` once when a client first subscribes
+(immediately after the initial snapshot and before the first live transition)
+and again on every failover or failback. A late-joining client therefore
+always learns the current provider mode without waiting for the next switch.
+
+`AlarmProviderMode` is an enum with three values:
+
+| Value | Meaning |
+|-------|---------|
+| `ALARM_PROVIDER_MODE_UNSPECIFIED` (0) | Default / unset |
+| `ALARM_PROVIDER_MODE_ALARMMGR` (1) | Native wnwrap alarm-manager source |
+| `ALARM_PROVIDER_MODE_SUBTAG` (2) | Subtag-monitoring fallback (degraded) |
+
+#### Degraded and source-provider fields on transitions and snapshots
+
+`OnAlarmTransitionEvent` and `ActiveAlarmSnapshot` both carry two new fields:
+
+- `bool degraded` (field 14) — `true` when the record came from the subtag
+  fallback, not the native alarmmgr.
+- `AlarmProviderMode source_provider` (field 15) — which provider produced
+  this record (`ALARMMGR` or `SUBTAG`).
+
+Both fields are proto3 defaults (`false` / `UNSPECIFIED`) in alarmmgr mode,
+so existing clients that do not read them continue to function without change.
+Clients that care about provenance — for example, an OPC UA server that
+applies different quality flags to degraded alarms — should inspect `degraded`
+before consuming the transition.
+
+Subtag-mode records are a non-parity source. They carry synthetic GUIDs,
+best-effort timestamps, and reduced field coverage. See
+`docs/AlarmClientDiscovery.md` for the full fidelity table.
+
+#### Provider-mode-changed event
+
+The worker emits `OnAlarmProviderModeChangedEvent` (family
+`MX_EVENT_FAMILY_ON_ALARM_PROVIDER_MODE_CHANGED`) on each switch between
+providers:
+
+```protobuf
+message OnAlarmProviderModeChangedEvent {
+  AlarmProviderMode mode = 1;
+  string reason = 2;
+  int32 hresult = 3;  // COM HRESULT that triggered failover; 0 on failback
+  google.protobuf.Timestamp at = 4;
+}
+```
+
+This event arrives on the `StreamEvents` stream of the alarm monitor's
+internal gateway session (not on client sessions). `GatewayAlarmMonitor`
+consumes it and reflects the new mode into the `StreamAlarms` feed's
+`provider_status`, the dashboard hub, and metrics. Client sessions do not
+receive this event directly.
+
 ## Validation Rules
 
 `MxAccessGrpcRequestValidator` rejects requests with `StatusCode.InvalidArgument` before any session work happens. The rules are intentionally narrow — anything that requires session state (for example, "session does not exist") is left for `ISessionManager` so the validator can stay synchronous and side-effect free.

docs/Metrics.md

@@ -4,7 +4,7 @@ The metrics subsystem exposes counters, histograms, and observable gauges that d
 
 ## Overview
 
-`GatewayMetrics` is a singleton (registered in `GatewayApplication.cs`) that owns a single `Meter` named `ZB.MOM.WW.MxGateway.Server` and a set of synchronised counters, histograms, and observable gauges. Subsystems call typed mutator methods (`SessionOpened`, `CommandFailed`, `EventReceived`, etc.) rather than touching the `Meter` directly, which keeps the OpenTelemetry instrument names and tag conventions in one place. A `lock (_syncRoot)` block guards the scalar fields used by `GetSnapshot`, while per-event maps use `ConcurrentDictionary<string, long>` so the hot event path avoids the lock.
+`GatewayMetrics` is a singleton (registered in `GatewayApplication.cs`) that owns a single `Meter` named `ZB.MOM.WW.MxGateway` and a set of synchronised counters, histograms, and observable gauges. Subsystems call typed mutator methods (`SessionOpened`, `CommandFailed`, `EventReceived`, etc.) rather than touching the `Meter` directly, which keeps the OpenTelemetry instrument names and tag conventions in one place. A `lock (_syncRoot)` block guards the scalar fields used by `GetSnapshot`, while per-event maps use `ConcurrentDictionary<string, long>` so the hot event path avoids the lock.
 
 ## Meter and OpenTelemetry Compatibility
 
@@ -13,7 +13,7 @@ The meter name is exposed as a constant so that hosting code can register it wit
 ```csharp
 public sealed class GatewayMetrics : IDisposable
 {
-    public const string MeterName = "ZB.MOM.WW.MxGateway.Server";
+    public const string MeterName = "ZB.MOM.WW.MxGateway";
 
     public GatewayMetrics()
     {
@@ -50,12 +50,12 @@ All counters are `Counter<long>`. Tag values come from the call sites listed und
 
 ### Histograms
 
-Histograms record durations in milliseconds (the `unit` argument on `CreateHistogram`):
+Histograms record durations in seconds (the `unit` argument on `CreateHistogram`):
 
 ```csharp
-_workerStartupLatencyHistogram = _meter.CreateHistogram<double>("mxgateway.workers.startup.duration", "ms");
-_commandLatencyHistogram = _meter.CreateHistogram<double>("mxgateway.commands.duration", "ms");
-_eventStreamSendLatencyHistogram = _meter.CreateHistogram<double>("mxgateway.events.stream_send.duration", "ms");
+_workerStartupLatencyHistogram = _meter.CreateHistogram<double>("mxgateway.workers.startup.duration", "s");
+_commandLatencyHistogram = _meter.CreateHistogram<double>("mxgateway.commands.duration", "s");
+_eventStreamSendLatencyHistogram = _meter.CreateHistogram<double>("mxgateway.events.stream_send.duration", "s");
 ```
 
 | Instrument | Tags | What it measures |

docs/plans/2026-06-13-alarm-subtag-fallback-design.md

@@ -0,0 +1,316 @@
+# Alarm Subtag-Monitoring Fallback — Design
+
+**Date:** 2026-06-13
+**Status:** Superseded by implementation (merged to `main`). This is the original
+brainstorming design; a few details below were refined during implementation —
+see the inline **Superseded** notes. The shipped behaviour is documented in
+`docs/AlarmClientDiscovery.md`, the client READMEs, and the contracts.
+**Branch:** `feat/alarm-subtag-fallback`
+
+## Problem
+
+The gateway's central alarm feed (`GatewayAlarmMonitor` → worker
+`WnWrapAlarmConsumer`) depends on the AVEVA wnwrap COM consumer
+(`WNWRAPCONSUMERLib.wwAlarmConsumerClass`), which polls `GetXmlCurrentAlarms2`
+on the worker STA. That provider can fail at the COM boundary (the older
+`aaAlarmManagedClient` crashed on FILETIME marshaling; wnwrap can still return
+failure HRESULTs or throw `COMException`). When it does, the gateway loses all
+alarm visibility.
+
+This design adds a **second alarm source** — direct monitoring of each alarm
+attribute's subtags (`.active`, `.acked`, …) via the existing MXAccess
+`AddItem`/`Advise` pipeline — and **fails over to it automatically when the
+wnwrap provider breaks, then fails back automatically when it recovers**. The
+subtag source can also be forced on by config.
+
+## Decisions (locked during brainstorming)
+
+| Decision | Choice |
+|---|---|
+| Failover model | **Auto-failover + auto-failback** (both directions, runtime) |
+| Watch-list source | **Galaxy Repository SQL discovery + config override** |
+| Acknowledge in subtag mode | **Write the operator comment to the alarm's ack-comment subtag** (the write performs the ack) |
+| Failure signal | **N consecutive wnwrap COM failures** (Subscribe / `GetXmlCurrentAlarms2` throws or returns a failure HRESULT) |
+| Degraded-state visibility | **Both** — explicit field in the gRPC contract **and** dashboard + metrics |
+| Synthesis location | **Worker-side** (`Approach A`) — keeps the parity rule "the gateway forwards only events the worker emits; it never synthesizes events" |
+
+## Core principle
+
+Subtag monitoring is, by definition, a **non-parity, lower-fidelity** alarm
+source: it synthesizes alarm transitions from raw data changes, has no native
+alarm GUID, no native original-raise timestamp, and a narrower field set. Per
+`CLAUDE.md`, synthesizing events is allowed only as an explicit opt-in
+non-parity mode. This design satisfies that by (a) doing the synthesis **inside
+the worker** (so the gateway still only forwards worker-emitted events) and
+(b) marking every degraded event and the whole feed as degraded so no client
+mistakes it for the authoritative alarmmgr feed.
+
+## Architecture
+
+```
+                          GATEWAY (.NET 10, x64)
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ GatewayAlarmMonitor (BackgroundService)                           │
+  │  • resolves watch-list: Galaxy Repository SQL + config override   │
+  │  • arms the worker with the watch-list at subscribe time          │
+  │  • consumes AlarmProviderModeChanged → reflects mode into feed,   │
+  │    /hubs/alarms dashboard hub, and metrics                        │
+  │  • forces a cache reconcile (QueryActiveAlarms) on every switch   │
+  └───────────────────────────────┬───────────────────────────────────┘
+                                   │ IPC (WorkerEnvelope frames)
+                                   │  · SubscribeAlarms{ watch_list, failover cfg }
+                                   │  · AlarmProviderModeChanged{ mode, reason, hresult }
+                                   │  · OnAlarmTransitionEvent (degraded flag set in subtag mode)
+                                   ▼
+                          WORKER (.NET FW 4.8, x86, STA)
+  ┌─────────────────────────────────────────────────────────────────┐
+  │ AlarmDispatcher → FailoverAlarmConsumer : IMxAccessAlarmConsumer  │
+  │   ├─ primary : WnWrapAlarmConsumer   (wnwrap COM poll, unchanged) │
+  │   └─ standby : SubtagAlarmConsumer   (AddItem/Advise on subtags)  │
+  │                                                                   │
+  │  FailoverAlarmConsumer owns the state machine:                    │
+  │   PrimaryActive ──(N consecutive wnwrap COM failures)──▶ Degraded │
+  │   Degraded ──(M consecutive clean wnwrap probe polls)──▶ Primary  │
+  │   on each switch: snapshot the now-active provider, hand off      │
+  └─────────────────────────────────────────────────────────────────┘
+```
+
+The failover state machine lives **worker-local** so the switch is instant — no
+IPC round-trip at the moment alarmmgr dies. The gateway *arms* the standby
+consumer up front (passes the watch-list at subscribe time) so it is ready
+before it is ever needed.
+
+## Components
+
+### Worker (`src/ZB.MOM.WW.MxGateway.Worker/MxAccess/`)
+
+**`SubtagAlarmConsumer : IMxAccessAlarmConsumer` (new)** — the standby provider.
+
+- On `Subscribe`, instead of wnwrap registration it `AddItem`/`Advise`s the
+  configured subtags for each watch-list entry on the existing STA (reuses the
+  worker's item-subscription machinery). Per attribute it advises at minimum
+  `.active` and `.acked`; optionally `.priority`/severity, `.descr`, value/limit
+  if present.
+- Converts each `OnDataChange` into the same `MxAlarmTransitionEvent` the wnwrap
+  consumer emits, via the synthesis rules below, and raises
+  `AlarmTransitionEmitted`. Marks each as **degraded**.
+- `SnapshotActiveAlarms()` returns the currently-active set computed from
+  last-known subtag values.
+- `AcknowledgeByName(...)` resolves the watch-list entry's ack-comment subtag and
+  issues a `Write(comment)` on the STA. `AcknowledgeByGuid(...)` maps the
+  synthetic GUID (see below) back to a reference, then does the same. If the
+  attribute exposes no writable ack-comment subtag, returns a failure code that
+  the gateway surfaces as `FailedPrecondition`.
+- `PollOnce()` is a no-op (subtag mode is event-driven via Advise).
+
+**`FailoverAlarmConsumer : IMxAccessAlarmConsumer` (new)** — composite + state
+machine. Owns the wnwrap consumer (primary) and the subtag consumer (standby),
+forwards `AlarmTransitionEmitted` from whichever child is active, and raises a
+new `ProviderModeChanged` event on every switch.
+
+- **Failure counting:** wraps `Subscribe`/`PollOnce` on the primary; a thrown
+  `COMException` or a failure HRESULT increments a consecutive-failure counter,
+  reset to zero on any clean poll.
+- **Failover** (`PrimaryActive → Degraded`): at `ConsecutiveFailureThreshold`
+  (default 3), ensures the standby is subscribed (it was armed at startup), sets
+  active = standby, snapshots the standby's active set for hand-off, and emits
+  `ProviderModeChanged(SUBTAG, reason, hresult)`.
+- **Failback probe** (`Degraded → PrimaryActive`): while degraded, every
+  `FailbackProbeIntervalSeconds` (default 30) it re-attempts wnwrap
+  `Subscribe`+`PollOnce` on the STA. After `FailbackStableProbes` (default 3)
+  consecutive clean polls it switches active = primary, returns the standby to
+  standby, and emits `ProviderModeChanged(ALARMMGR, "recovered")`.
+- **Hand-off:** on every switch it takes `SnapshotActiveAlarms()` from the
+  now-active provider so the gateway can reconcile and avoid spurious
+  raise/clear storms.
+
+**`AlarmDispatcher` / `MxAccessAlarmEventSink` / `AlarmCommandHandler`
+(changed, minimal)** — `AlarmDispatcher` holds a `FailoverAlarmConsumer` instead
+of a bare `WnWrapAlarmConsumer`; it subscribes to `ProviderModeChanged` and
+enqueues a mode-changed worker event. The ack path routes by active mode (native
+wnwrap ack in alarmmgr mode; ack-comment write in subtag mode), but that routing
+is entirely inside the consumer — the dispatcher just calls
+`AcknowledgeByName`/`AcknowledgeByGuid`.
+
+### Gateway (`src/ZB.MOM.WW.MxGateway.Server/`)
+
+**Galaxy Repository discovery (new query)** — alongside the existing GR SQL
+browse RPCs, a query "attributes that have alarms configured, with their
+ack-comment subtag and area", scoped to the configured area. Merged with the
+config override (explicit includes/excludes). Produces the watch-list of
+`AlarmSubtagTarget`s.
+
+**`GatewayAlarmMonitor` (changed)** — resolves the watch-list at subscribe time
+and passes it to the worker; consumes `AlarmProviderModeChanged` and reflects
+the current provider mode into (a) the `AlarmFeedMessage` provider-status,
+(b) the `/hubs/alarms` dashboard hub, and (c) metrics; forces a reconcile
+(`QueryActiveAlarms`) on every switch. Re-runs discovery on its existing
+reconcile cadence and pushes an updated watch-list when the model changes.
+
+**`AlarmsOptions` (extended)** — new `Fallback` sub-section (below).
+
+### Contract (`src/ZB.MOM.WW.MxGateway.Contracts/Protos/`)
+
+**`mxaccess_gateway.proto`:**
+
+- `enum AlarmProviderMode { ALARM_PROVIDER_MODE_UNSPECIFIED = 0; ALARMMGR = 1; SUBTAG = 2; }`
+- New `AlarmFeedMessage` oneof case `AlarmProviderStatus provider_status`,
+  carrying `{ AlarmProviderMode mode; bool degraded; string reason;
+  google.protobuf.Timestamp since; }`. Emitted on stream open and on every
+  change so a late-joining client immediately learns the mode.
+- Add `bool degraded` + `AlarmProviderMode source_provider` to
+  `OnAlarmTransitionEvent` **and** `ActiveAlarmSnapshot`, so per-item provenance
+  is visible even mid-stream. All additions are new field numbers — backward
+  compatible; existing clients ignore them and keep seeing alarms.
+
+**`mxaccess_worker.proto`:**
+
+> **Superseded:** these additions shipped in `mxaccess_gateway.proto`, not
+> `mxaccess_worker.proto` — the worker imports the gateway proto and the alarm
+> commands/events live there (`AlarmSubtagTarget`,
+> `OnAlarmProviderModeChangedEvent`, the extended subscribe command).
+
+- Extend the alarm-subscribe command with: `AlarmProviderMode forced_mode`
+  (`UNSPECIFIED` = auto), `int32 consecutive_failure_threshold`,
+  `int32 failback_probe_interval_seconds`, `int32 failback_stable_probes`, and
+  `repeated AlarmSubtagTarget watch_list`, where `AlarmSubtagTarget =
+  { string alarm_full_reference; string source_object_reference;
+  string active_subtag; string acked_subtag; string ack_comment_subtag;
+  string priority_subtag; }`.
+- New worker→gateway event `AlarmProviderModeChanged { AlarmProviderMode mode;
+  string reason; int32 hresult; google.protobuf.Timestamp at; }`.
+
+> Generated code under `Generated/` and `clients/*/generated*/` is rebuilt from
+> these `.proto` files — never hand-edited. Every generated client touched by
+> the contract is rebuilt per the source-update workflow.
+
+## Data flow
+
+### Subtag synthesis rules
+
+`SubtagAlarmConsumer` keeps last-known `(active, acked)` per watch-list entry and
+emits transitions on change:
+
+| Subtag change | Emitted transition | Notes |
+|---|---|---|
+| `active` false → true | `RAISE` (state `UNACK_ALM`) | `original_raise_timestamp` = first-observed active time |
+| `acked` false → true while `active` | `ACKNOWLEDGE` | `operator_user`/`operator_comment` from ack-comment subtag if advised |
+| `active` true → false | `CLEAR` | maps to `AckRtn` if acked at clear, else `UnackRtn` |
+| `active` stays true, re-alarm | `RETRIGGER` | **only** if a re-alarm counter subtag exists; otherwise not synthesized (documented limitation) |
+
+Snapshot state mapping for `ActiveAlarmSnapshot.current_state`:
+`active && !acked → ACTIVE`, `active && acked → ACTIVE_ACKED`,
+`!active → INACTIVE`.
+
+Field degradation in subtag mode:
+- `alarm_full_reference` — from the watch-list entry (stable, drives ack-by-ref).
+- Synthetic, deterministic GUID derived by hashing `alarm_full_reference` so
+  GUID-based ack still resolves; flagged `degraded = true`.
+- `severity` — from the priority subtag if advised, else 0.
+- `original_raise_timestamp` — first-observed active time (best effort).
+- `transition_timestamp` — the `OnDataChange` timestamp.
+- `category`/`description`/`current_value`/`limit_value` — populated only if the
+  corresponding subtag is advised; otherwise empty.
+
+### Acknowledge
+
+`AcknowledgeAlarm`/`AcknowledgeAlarmByName` are unchanged at the RPC surface.
+`AlarmDispatcher` routes by active provider mode:
+- **alarmmgr mode:** native wnwrap `AlarmAckByName`/`AlarmAckByGUID` (unchanged).
+- **subtag mode:** resolve the target's `ack_comment_subtag`, `Write` the
+  operator comment via the existing worker write path on the STA. No writable
+  ack-comment subtag → `FailedPrecondition`.
+
+### Provider-mode reflection
+
+Worker `AlarmProviderModeChanged` → `GatewayAlarmMonitor` → (a) emit/refresh
+`AlarmFeedMessage.provider_status` to every `StreamAlarms` subscriber, (b) push
+to `/hubs/alarms`, (c) update metrics, (d) force a reconcile.
+
+## Error handling
+
+- **Both providers down** (subtag advise also failing): the monitor stays
+  faulted and keeps retrying both; acknowledge returns `Unavailable`. No silent
+  data loss — the feed reports degraded with reason.
+- **Empty watch-list in subtag mode** (GR SQL unavailable, no config override):
+  log + metric `alarm_fallback_watchlist_empty`; the feed reports degraded +
+  empty; the gateway keeps re-running discovery on its reconcile cadence and
+  pushes an updated watch-list when one becomes available.
+- **Switch hand-off:** every switch snapshots the now-active provider and
+  reconciles against the gateway cache to avoid a raise/clear storm.
+- **STA affinity:** all subtag advise/write and wnwrap probe calls run on the
+  worker STA (reuse the existing affinity guard) to satisfy
+  `ThreadingModel=Apartment`.
+
+### Metrics
+
+- `mxgateway_alarm_provider_mode` (gauge: 1 = alarmmgr, 2 = subtag)
+- `mxgateway_alarm_provider_switch_total{from,to,reason}` (counter)
+- `mxgateway_alarm_fallback_watchlist_size` (gauge)
+
+> **Superseded:** the shipped meter names are `mxgateway.alarms.provider_mode`
+> (gauge) and `mxgateway.alarms.provider_switches{from,to,reason}` (counter,
+> `reason` bounded to `failover`/`failback`/`unknown`). The watch-list-size /
+> watch-list-empty gauges were not implemented; an empty watch-list is surfaced
+> via a warning log and the feed's degraded `ProviderStatus` instead.
+
+## Configuration
+
+```jsonc
+"MxGateway": {
+  "Alarms": {
+    "Enabled": true,
+    "SubscriptionExpression": "\\\\DESKTOP-6JL3KKO\\Galaxy!DEV",
+    "DefaultArea": "DEV",
+    "ReconcileIntervalSeconds": 30,
+    "Fallback": {
+      "Mode": "Auto",                      // Auto | ForceAlarmManager | ForceSubtag
+      "ConsecutiveFailureThreshold": 3,
+      "FailbackProbeIntervalSeconds": 30,
+      "FailbackStableProbes": 3,
+      "Discovery": {
+        "UseGalaxyRepository": true,
+        "Area": "",                        // defaults to Alarms.DefaultArea
+        "IncludeAttributes": [],           // explicit additions
+        "ExcludeAttributes": []
+      },
+      "Subtags": {
+        "Active": "active",
+        "Acked": "acked",
+        "AckComment": "",                  // verified against MXAccess analysis
+        "Priority": "priority"
+      }
+    }
+  }
+}
+```
+
+`GatewayOptionsValidator` additions: `Mode = ForceSubtag` with empty discovery
+result and no explicit `IncludeAttributes` → startup validation warning;
+threshold/interval/probe values floored at sane minimums.
+
+## Open item to confirm during implementation
+
+The exact AVEVA subtag names (`.active`, `.acked`, the ack-comment attribute,
+priority) must be confirmed against the MXAccess analysis project
+(`C:\Users\dohertj2\Desktop\mxaccess`, `docs/MXAccess-Public-API.md`) and the
+live Galaxy before wiring `SubtagAlarmConsumer`. The config `Subtags` block
+exists precisely so the resolved names are not hard-coded.
+
+## Testing
+
+| Layer | Tests |
+|---|---|
+| Worker unit (`MxGateway.Worker.Tests`, x86) | `SubtagAlarmConsumer` synthesis — feed `OnDataChange` sequences, assert raise/ack/clear transitions, snapshot states, degraded flag, synthetic-GUID stability, ack-comment write routing |
+| Worker unit | `FailoverAlarmConsumer` state machine — fake wnwrap throwing after K polls: assert switch at threshold, failback after stable probes, `ProviderModeChanged` emitted, no duplicate transitions across switch (hand-off reconcile) |
+| Gateway unit (`MxGateway.Tests`, fake worker) | discovery + config-override merge; `GatewayAlarmMonitor` reflects mode into feed + hub; metrics increment on switch |
+| Contract | proto round-trip for new fields; existing alarm tests unchanged (alarmmgr-mode regression — parity preserved) |
+| Live (opt-in, `MXGATEWAY_RUN_LIVE_MXACCESS_TESTS=1`) | real subtag advise + ack-comment write against a live alarm; GR SQL discovery query against the `ZB` DB (gated like existing GR tests) |
+
+## Docs to update in the same change
+
+`gateway.md` (alarm provider section), `docs/DesignDecisions.md` (record the
+fallback decision), `docs/GatewayConfiguration.md` (the `Fallback` block),
+`docs/AlarmClientDiscovery.md` (subtag provider + synthesis rules),
+`docs/Grpc.md` (the new `provider_status` / `degraded` fields), and any client
+READMEs whose generated alarm types gain fields.

docs/plans/2026-06-13-alarm-subtag-fallback.md

@@ -0,0 +1,860 @@
+# Alarm Subtag-Monitoring Fallback — Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans (or subagent-driven-development) to implement this plan task-by-task.
+
+**Goal:** Add a second alarm source — direct MXAccess subtag monitoring — that the gateway auto-fails-over to when the wnwrap alarmmgr provider breaks, auto-fails-back to when it recovers, and can be forced on by config.
+
+**Architecture:** Worker-side synthesis (parity rule preserved). A new `SubtagAlarmConsumer` (own `LMXProxyServerClass`, `AddItem`/`Advise` on alarm subtags) and a `FailoverAlarmConsumer` composite (state machine over the wnwrap primary + subtag standby) both implement the existing `IMxAccessAlarmConsumer` seam. The gateway resolves the subtag watch-list (Galaxy Repository SQL + config override), arms the worker at subscribe time, and reflects the live provider mode into the gRPC alarm feed, the dashboard hub, and metrics.
+
+**Tech Stack:** .NET 10 (gateway, x64) + .NET Framework 4.8 (worker, x86, STA), protobuf/gRPC, `Microsoft.Data.SqlClient` (Galaxy Repository), SignalR (dashboard), `System.Diagnostics.Metrics`, xUnit (plain `Assert`, no FluentAssertions).
+
+**Design source:** `docs/plans/2026-06-13-alarm-subtag-fallback-design.md`
+
+**Branch:** `feat/alarm-subtag-fallback` (already created)
+
+---
+
+## Conventions for every task
+
+- **TDD:** write the failing test, run it red, implement, run it green, commit.
+- **xUnit, plain `Assert.*`**, naming `Subject_Condition_Expected`. Worker fakes are sealed private nested classes that raise events.
+- **Build/test commands:**
+  - Contracts regen: `dotnet build src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj`
+  - Gateway: `dotnet build src/ZB.MOM.WW.MxGateway.Server` ; `dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj`
+  - Worker (x86): `dotnet build src/ZB.MOM.WW.MxGateway.Worker/ZB.MOM.WW.MxGateway.Worker.csproj -p:Platform=x86` ; `dotnet test src/ZB.MOM.WW.MxGateway.Worker.Tests/ZB.MOM.WW.MxGateway.Worker.Tests.csproj -p:Platform=x86`
+  - Single test: append `--filter FullyQualifiedName~<ClassOrMethod>`
+- **Build is strict:** `TreatWarningsAsErrors=true`, nullable enabled. Add XML doc comments on public members (the repo runs a doc checker).
+- **Generated code** under `Generated/` is never hand-edited — rebuild the contracts project to regenerate.
+- **Namespaces:** worker MxAccess types live in `ZB.MOM.WW.MxGateway.Worker.MxAccess`; proto C# types in `ZB.MOM.WW.MxGateway.Contracts.Proto`.
+
+---
+
+## Phase 0 — Contracts
+
+### Task 1: Worker proto — subtag watch-list, failover config, provider-mode enum
+
+**Classification:** high-risk
+**Estimated implement time:** ~4 min
+**Parallelizable with:** none (Task 2 imports these types)
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto` (real `SubscribeAlarmsCommand` at ~line 324; `MxCommand` references it at 123-125)
+
+> **CORRECTION (execution):** The alarm command messages and `MxCommand` live in **`mxaccess_gateway.proto`**, not the worker proto. `mxaccess_worker.proto` *imports* the gateway proto (`WorkerCommand.command` is `mxaccess_gateway.v1.MxCommand`), so the gateway proto is the base and the worker proto needs **no** change. `AlarmProviderMode` and the new types are added to the gateway proto and are visible to worker code as `mxaccess_gateway.v1` types. Tasks 1 and 2 are executed as a single combined edit on this one file.
+
+**Step 1: Add the enum and messages.** In `mxaccess_gateway.proto`, extend the existing `SubscribeAlarmsCommand` message (line 324) and add the new types after it:
+
+```protobuf
+// Provider selection / current provider for the alarm feed. Defined here in
+// the worker contract because the worker SubscribeAlarmsCommand references it;
+// mxaccess_gateway.proto imports this file and reuses the same enum.
+enum AlarmProviderMode {
+  ALARM_PROVIDER_MODE_UNSPECIFIED = 0;  // auto: alarmmgr primary, subtag fallback
+  ALARM_PROVIDER_MODE_ALARMMGR = 1;
+  ALARM_PROVIDER_MODE_SUBTAG = 2;
+}
+
+message SubscribeAlarmsCommand {
+  string subscription_expression = 1;  // existing field — keep
+  // UNSPECIFIED = auto-failover/failback. ALARMMGR/SUBTAG force one provider.
+  AlarmProviderMode forced_mode = 2;
+  // Subtag watch-list resolved by the gateway (GR SQL + config). Empty in pure
+  // alarmmgr mode; in subtag mode it bounds what the consumer can observe.
+  repeated AlarmSubtagTarget watch_list = 3;
+  AlarmFailoverConfig failover = 4;
+}
+
+// One alarm attribute the subtag consumer advises. Addresses are full MXAccess
+// item references the worker passes straight to AddItem.
+message AlarmSubtagTarget {
+  string alarm_full_reference = 1;     // e.g. "Galaxy!Area.Tank01.Level.HiHi"
+  string source_object_reference = 2;  // e.g. "Tank01"
+  string active_subtag = 3;            // item address of the in-alarm boolean
+  string acked_subtag = 4;             // item address of the acknowledged boolean
+  string ack_comment_subtag = 5;       // writable ack-comment attribute (ack write target)
+  string priority_subtag = 6;          // optional severity source; empty if absent
+}
+
+message AlarmFailoverConfig {
+  int32 consecutive_failure_threshold = 1;   // wnwrap COM failures before switching (>=1)
+  int32 failback_probe_interval_seconds = 2; // probe cadence while degraded (>=1)
+  int32 failback_stable_probes = 3;          // clean probes before switching back (>=1)
+}
+```
+
+`UnsubscribeAlarmsCommand` and `AcknowledgeAlarmCommand` are unchanged.
+
+**Step 2: Regenerate & verify it compiles.**
+Run: `dotnet build src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj`
+Expected: build succeeds; generated `AlarmProviderMode`, `AlarmSubtagTarget`, `AlarmFailoverConfig` types appear.
+
+**Step 3: Commit.**
+```bash
+git add src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_worker.proto
+git commit -m "contracts(worker): subtag watch-list + failover config + AlarmProviderMode"
+```
+
+---
+
+### Task 2: Gateway proto — provider status on the feed, degraded provenance, mode-changed event
+
+**Classification:** high-risk
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (depends on Task 1; Task 3 tests both)
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto` (`OnAlarmTransitionEvent` ~719-771, `ActiveAlarmSnapshot` ~783-803, `AlarmFeedMessage` ~860-870, `MxEvent` family enum + body oneof, `MxEventFamily` enum)
+
+**Step 1: Add degraded provenance to the two alarm payloads.** Append to `OnAlarmTransitionEvent` (next free field 14):
+
+```protobuf
+  // True when this transition came from the subtag-monitoring fallback rather
+  // than the native alarmmgr provider — i.e. it was synthesized from data
+  // changes and carries reduced fidelity (synthetic GUID, no native raise time).
+  bool degraded = 14;
+  // Which provider produced this transition.
+  AlarmProviderMode source_provider = 15;
+```
+
+Append the identical two fields to `ActiveAlarmSnapshot` (next free field 14):
+```protobuf
+  bool degraded = 14;
+  AlarmProviderMode source_provider = 15;
+```
+
+**Step 2: Add provider status to the feed oneof.** Add a new oneof case to `AlarmFeedMessage` (next free field 4) and a new message:
+
+```protobuf
+message AlarmFeedMessage {
+  oneof payload {
+    ActiveAlarmSnapshot active_alarm = 1;
+    bool snapshot_complete = 2;
+    OnAlarmTransitionEvent transition = 3;
+    // Provider-mode status. Emitted once on stream open and again on every
+    // failover/failback so late joiners learn the current mode immediately.
+    AlarmProviderStatus provider_status = 4;
+  }
+}
+
+message AlarmProviderStatus {
+  AlarmProviderMode mode = 1;
+  bool degraded = 2;            // true whenever mode == SUBTAG
+  string reason = 3;            // human-readable switch reason
+  google.protobuf.Timestamp since = 4;
+}
+```
+
+**Step 3: Add the worker→gateway mode-changed event to `MxEvent`.** Find the `MxEventFamily` enum and the `MxEvent` body oneof. Add a family member and a body message + oneof case (use the next free family value and the next free `MxEvent` body field number — check the file):
+
+```protobuf
+// in MxEventFamily enum:
+  MX_EVENT_FAMILY_ON_ALARM_PROVIDER_MODE_CHANGED = <next>;
+
+// new message near OnAlarmTransitionEvent:
+message OnAlarmProviderModeChangedEvent {
+  AlarmProviderMode mode = 1;
+  string reason = 2;
+  int32 hresult = 3;   // COM HRESULT that triggered failover; 0 on failback
+  google.protobuf.Timestamp at = 4;
+}
+
+// in MxEvent body oneof:
+  OnAlarmProviderModeChangedEvent on_alarm_provider_mode_changed = <next>;
+```
+
+`AlarmProviderMode` is defined in `mxaccess_worker.proto`; confirm `mxaccess_gateway.proto` already has `import "mxaccess_worker.proto";` (it references `SubscribeAlarmsCommand`, so it does) and reference the enum unqualified or via its package as the existing references do.
+
+**Step 4: Regenerate & verify.**
+Run: `dotnet build src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj`
+Expected: build succeeds.
+
+**Step 5: Commit.**
+```bash
+git add src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto
+git commit -m "contracts(gateway): AlarmProviderStatus feed case, degraded provenance, mode-changed event"
+```
+
+---
+
+### Task 3: Proto round-trip tests for the new alarm fields
+
+**Classification:** small
+**Estimated implement time:** ~3 min
+**Parallelizable with:** none (depends on Tasks 1-2)
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Tests/Contracts/ProtobufContractRoundTripTests.cs`
+
+**Step 1: Add tests** mirroring the existing `Event_RoundTripsOnAlarmTransitionWithFullPayload` style:
+
+```csharp
+[Fact]
+public void Feed_RoundTripsProviderStatus()
+{
+    var since = Timestamp.FromDateTime(new DateTime(2026, 6, 13, 9, 0, 0, DateTimeKind.Utc));
+    var original = new AlarmFeedMessage
+    {
+        ProviderStatus = new AlarmProviderStatus
+        {
+            Mode = AlarmProviderMode.Subtag,
+            Degraded = true,
+            Reason = "wnwrap poll failed 3x (HRESULT 0x80004005)",
+            Since = since,
+        },
+    };
+
+    var parsed = AlarmFeedMessage.Parser.ParseFrom(original.ToByteArray());
+
+    Assert.Equal(original, parsed);
+    Assert.Equal(AlarmFeedMessage.PayloadOneofCase.ProviderStatus, parsed.PayloadCase);
+    Assert.True(parsed.ProviderStatus.Degraded);
+    Assert.Equal(AlarmProviderMode.Subtag, parsed.ProviderStatus.Mode);
+}
+
+[Fact]
+public void Transition_RoundTripsDegradedProvenance()
+{
+    var t = new OnAlarmTransitionEvent
+    {
+        AlarmFullReference = "Galaxy!Area.Tank01.Level.HiHi",
+        TransitionKind = AlarmTransitionKind.Raise,
+        Degraded = true,
+        SourceProvider = AlarmProviderMode.Subtag,
+    };
+
+    var parsed = OnAlarmTransitionEvent.Parser.ParseFrom(t.ToByteArray());
+
+    Assert.True(parsed.Degraded);
+    Assert.Equal(AlarmProviderMode.Subtag, parsed.SourceProvider);
+}
+```
+
+**Step 2: Run red→green.**
+Run: `dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~ProtobufContractRoundTripTests`
+Expected: PASS.
+
+**Step 3: Commit.**
+```bash
+git add src/ZB.MOM.WW.MxGateway.Tests/Contracts/ProtobufContractRoundTripTests.cs
+git commit -m "test(contracts): round-trip provider status + degraded provenance"
+```
+
+---
+
+## Phase 1 — Worker: subtag consumer + failover
+
+### Task 4: Subtag value-source abstraction + synthesis state holder
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (Task 5 builds on it)
+
+A testable seam so synthesis logic is unit-tested without COM. The COM wiring lands in Task 6.
+
+**Files:**
+- Create: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/ISubtagAlarmSource.cs`
+- Create: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SubtagAlarmStateMachine.cs`
+- Test: `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/SubtagAlarmStateMachineTests.cs`
+
+**Step 1: Define the source abstraction.** `ISubtagAlarmSource` advises subtag addresses and raises a normalized value-change callback on the STA:
+
+```csharp
+namespace ZB.MOM.WW.MxGateway.Worker.MxAccess;
+
+/// <summary>A change in one advised subtag value, normalized off the COM boundary.</summary>
+public sealed class SubtagValueChange
+{
+    /// <summary>The full item address that changed (matches an AlarmSubtagTarget subtag).</summary>
+    public string ItemAddress { get; init; } = string.Empty;
+    /// <summary>The new value (boolean for .active/.acked, numeric for priority).</summary>
+    public object? Value { get; init; }
+    /// <summary>The change timestamp in UTC.</summary>
+    public DateTime TimestampUtc { get; init; }
+}
+
+/// <summary>
+///     Advises a set of MXAccess subtag addresses and surfaces value changes.
+///     The production implementation (Task 6) owns its own LMXProxyServerClass;
+///     tests substitute a fake that pushes <see cref="SubtagValueChange"/>s.
+/// </summary>
+public interface ISubtagAlarmSource : IDisposable
+{
+    /// <summary>Raised on the STA when an advised subtag's value changes.</summary>
+    event EventHandler<SubtagValueChange>? ValueChanged;
+
+    /// <summary>Advises every subtag in the supplied addresses; idempotent per address.</summary>
+    void Advise(IReadOnlyCollection<string> itemAddresses);
+
+    /// <summary>Writes a value to an item address (used for the ack-comment write).</summary>
+    void Write(string itemAddress, object? value);
+}
+```
+
+**Step 2: Write the state-machine tests first.** `SubtagAlarmStateMachine` maps `(active, acked)` changes per target to `MxAlarmTransitionEvent`s. Test the four core transitions:
+
+```csharp
+namespace ZB.MOM.WW.MxGateway.Worker.Tests.MxAccess;
+
+public sealed class SubtagAlarmStateMachineTests
+{
+    private static AlarmSubtagTarget Target() => new()
+    {
+        AlarmFullReference = "Galaxy!Area.Tank01.Level.HiHi",
+        SourceObjectReference = "Tank01",
+        ActiveSubtag = "Tank01.Level.HiHi.active",
+        AckedSubtag = "Tank01.Level.HiHi.acked",
+        AckCommentSubtag = "Tank01.Level.HiHi.ackmsg",
+    };
+
+    [Fact]
+    public void ActiveFalseToTrue_EmitsRaise_FlaggedDegraded()
+    {
+        var sm = new SubtagAlarmStateMachine(new[] { Target() });
+        var ts = new DateTime(2026, 6, 13, 9, 0, 0, DateTimeKind.Utc);
+
+        var events = sm.Apply("Tank01.Level.HiHi.active", true, ts);
+
+        var e = Assert.Single(events);
+        Assert.Equal(MxAlarmStateKind.UnackAlm, e.Record.State);
+        Assert.Equal(MxAlarmStateKind.Unspecified, e.PreviousState);
+        Assert.Equal("Tank01.Level.HiHi", e.Record.TagName); // reference minus provider/area
+    }
+
+    [Fact]
+    public void AckedTrueWhileActive_EmitsAckTransition()
+    {
+        var sm = new SubtagAlarmStateMachine(new[] { Target() });
+        var ts = new DateTime(2026, 6, 13, 9, 0, 0, DateTimeKind.Utc);
+        sm.Apply("Tank01.Level.HiHi.active", true, ts);
+
+        var events = sm.Apply("Tank01.Level.HiHi.acked", true, ts.AddSeconds(5));
+
+        var e = Assert.Single(events);
+        Assert.Equal(MxAlarmStateKind.AckAlm, e.Record.State);
+        Assert.Equal(MxAlarmStateKind.UnackAlm, e.PreviousState);
+    }
+
+    [Fact]
+    public void ActiveTrueToFalse_WhileUnacked_EmitsUnackRtn()
+    {
+        var sm = new SubtagAlarmStateMachine(new[] { Target() });
+        var ts = new DateTime(2026, 6, 13, 9, 0, 0, DateTimeKind.Utc);
+        sm.Apply("Tank01.Level.HiHi.active", true, ts);
+
+        var events = sm.Apply("Tank01.Level.HiHi.active", false, ts.AddSeconds(10));
+
+        var e = Assert.Single(events);
+        Assert.Equal(MxAlarmStateKind.UnackRtn, e.Record.State);
+    }
+
+    [Fact]
+    public void Snapshot_ReflectsActiveAndAckedState()
+    {
+        var sm = new SubtagAlarmStateMachine(new[] { Target() });
+        var ts = new DateTime(2026, 6, 13, 9, 0, 0, DateTimeKind.Utc);
+        sm.Apply("Tank01.Level.HiHi.active", true, ts);
+        sm.Apply("Tank01.Level.HiHi.acked", true, ts);
+
+        var snap = Assert.Single(sm.SnapshotActive());
+        Assert.Equal(MxAlarmStateKind.AckAlm, snap.State);
+    }
+}
+```
+
+Run: `dotnet test ...Worker.Tests... -p:Platform=x86 --filter FullyQualifiedName~SubtagAlarmStateMachineTests` → FAIL (type missing).
+
+**Step 3: Implement `SubtagAlarmStateMachine`.** Build an address→target index (active/acked/priority/comment addresses), hold per-reference `(bool active, bool acked, DateTime firstRaiseUtc, int priority)`, and emit on change:
+- active `false→true` ⇒ `UnackAlm`, set `firstRaiseUtc`, `PreviousState` from prior state.
+- acked `false→true` while active ⇒ `AckAlm`.
+- active `true→false` ⇒ `AckRtn` if currently acked else `UnackRtn`; then reset acked.
+- priority change ⇒ update stored priority, no transition.
+- `TagName` = `alarm_full_reference` with any `Provider!Area.` prefix stripped (match `WnWrapAlarmConsumer`'s reference shape so `GatewayAlarmMonitor` keys align). Set `ProviderName`, `Group`, `Priority`, `AlarmComment` from the target/last values. Mark a `Degraded`/source flag (carried via a new field — see Task 5 wiring).
+- `SnapshotActive()` returns `MxAlarmSnapshotRecord` for references whose active is true.
+
+**Step 4: Run green.** Expected: PASS.
+
+**Step 5: Commit.**
+```bash
+git add src/ZB.MOM.WW.MxGateway.Worker/MxAccess/ISubtagAlarmSource.cs \
+        src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SubtagAlarmStateMachine.cs \
+        src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/SubtagAlarmStateMachineTests.cs
+git commit -m "worker(alarms): subtag value-source seam + synthesis state machine"
+```
+
+---
+
+### Task 5: `SubtagAlarmConsumer` over the source seam (no COM yet)
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (depends on Task 4)
+
+**Files:**
+- Create: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SubtagAlarmConsumer.cs`
+- Test: `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/SubtagAlarmConsumerTests.cs`
+
+**Step 1: Test with a fake `ISubtagAlarmSource`.** Drive value changes through the source, assert `AlarmTransitionEmitted` fires with synthesized records and that ack writes the comment to the ack-comment subtag:
+
+```csharp
+public sealed class SubtagAlarmConsumerTests
+{
+    private sealed class FakeSource : ISubtagAlarmSource
+    {
+        public event EventHandler<SubtagValueChange>? ValueChanged;
+        public List<string> Advised { get; } = new();
+        public (string Address, object? Value)? LastWrite { get; private set; }
+        public void Advise(IReadOnlyCollection<string> a) => Advised.AddRange(a);
+        public void Write(string a, object? v) => LastWrite = (a, v);
+        public void Raise(string addr, object? val, DateTime ts) =>
+            ValueChanged?.Invoke(this, new SubtagValueChange { ItemAddress = addr, Value = val, TimestampUtc = ts });
+        public void Dispose() { }
+    }
+
+    private static AlarmSubtagTarget Target() => new()
+    {
+        AlarmFullReference = "Galaxy!Area.Tank01.Level.HiHi",
+        ActiveSubtag = "Tank01.Level.HiHi.active",
+        AckedSubtag = "Tank01.Level.HiHi.acked",
+        AckCommentSubtag = "Tank01.Level.HiHi.ackmsg",
+    };
+
+    [Fact]
+    public void Subscribe_AdvisesAllSubtags()
+    {
+        var src = new FakeSource();
+        using var c = new SubtagAlarmConsumer(src, new[] { Target() });
+        c.Subscribe("ignored-in-subtag-mode");
+        Assert.Contains("Tank01.Level.HiHi.active", src.Advised);
+        Assert.Contains("Tank01.Level.HiHi.acked", src.Advised);
+    }
+
+    [Fact]
+    public void ValueChange_RaisesSynthesizedTransition()
+    {
+        var src = new FakeSource();
+        using var c = new SubtagAlarmConsumer(src, new[] { Target() });
+        c.Subscribe("x");
+        MxAlarmTransitionEvent? seen = null;
+        c.AlarmTransitionEmitted += (_, e) => seen = e;
+
+        src.Raise("Tank01.Level.HiHi.active", true, new DateTime(2026, 6, 13, 9, 0, 0, DateTimeKind.Utc));
+
+        Assert.NotNull(seen);
+        Assert.Equal(MxAlarmStateKind.UnackAlm, seen!.Record.State);
+    }
+
+    [Fact]
+    public void AcknowledgeByName_WritesCommentToAckCommentSubtag()
+    {
+        var src = new FakeSource();
+        using var c = new SubtagAlarmConsumer(src, new[] { Target() });
+        c.Subscribe("x");
+
+        int rc = c.AcknowledgeByName("Tank01.Level.HiHi", "Galaxy", "Area",
+            "ack from HMI", "op1", "node", "dom", "Op One");
+
+        Assert.Equal(0, rc);
+        Assert.Equal(("Tank01.Level.HiHi.ackmsg", (object?)"ack from HMI"), src.LastWrite);
+    }
+}
+```
+
+**Step 2: Implement `SubtagAlarmConsumer : IMxAccessAlarmConsumer`.**
+- Constructor `(ISubtagAlarmSource source, IReadOnlyList<AlarmSubtagTarget> watchList)`; build a `SubtagAlarmStateMachine`; index `alarm_full_reference`→target for ack routing.
+- `Subscribe(_)`: call `source.Advise(<all subtag addresses>)`; subscribe to `source.ValueChanged`, feed each into the state machine, and re-raise each produced `MxAlarmTransitionEvent` via `AlarmTransitionEmitted` (mark degraded).
+- `AcknowledgeByName(alarmName, …, comment, …)`: resolve the target by reference; if no `AckCommentSubtag`, return a non-zero failure code; else `source.Write(target.AckCommentSubtag, comment)` and return 0.
+- `AcknowledgeByGuid(guid, …)`: map the synthetic GUID (deterministic hash of reference — see Task 8 helper, or a local copy) back to a reference, then delegate to the name path; unknown GUID ⇒ non-zero.
+- `SnapshotActiveAlarms()`: from the state machine.
+- `PollOnce()`: no-op.
+- `Dispose()`: unsubscribe + dispose source.
+
+**Step 3: Run green.** `dotnet test ...Worker.Tests... -p:Platform=x86 --filter FullyQualifiedName~SubtagAlarmConsumerTests`.
+
+**Step 4: Commit.**
+```bash
+git add src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SubtagAlarmConsumer.cs \
+        src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/SubtagAlarmConsumerTests.cs
+git commit -m "worker(alarms): SubtagAlarmConsumer synthesizing transitions over the source seam"
+```
+
+---
+
+### Task 6: COM-backed `LmxSubtagAlarmSource` (own LMXProxyServerClass)
+
+**Classification:** high-risk
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none
+
+The only piece that touches live COM. Like `WnWrapAlarmConsumer`, it owns its own MXAccess server object so the subtag source is self-contained and isolated from the session's item pipeline. Logic stays thin (advise/write/marshal); real verification is the live smoke test in Task 17.
+
+**Files:**
+- Create: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/LmxSubtagAlarmSource.cs`
+- Test: `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/LmxSubtagAlarmSourceTests.cs` (constructor/guard tests only; COM path is live-gated)
+
+**Step 1: Implement `LmxSubtagAlarmSource : ISubtagAlarmSource`.**
+- Own an `LMXProxyServerClass` (reuse the worker's `IMxAccessServer`/`MxAccessComServer` wrapper + `IMxAccessComObjectFactory` so it is fakeable; constructor takes the factory).
+- `Advise(addresses)`: `RegisterServer` (topic) once; per address `AddItem`→`itemHandle`, `Advise`, and record `itemHandle→address`. Subscribe to the proxy's `OnDataChange`; in the handler, look up the address by `phItemHandle`, normalize `pvItemValue` (VARIANT→bool/double) and `pftItemTimeStamp`→UTC, and raise `ValueChanged`. All calls run on the STA (the worker STA pumps messages, so `OnDataChange` delivers).
+- `Write(address, value)`: resolve/create the item handle, `server.Write(serverHandle, itemHandle, value, userId: 0)`.
+- `Dispose()`: `UnAdvise`/`RemoveItem`/`Unregister`/release COM.
+
+**Step 2: Tests** — only the non-COM guards (null factory throws; `Write` before `Advise` resolves a handle or throws a clear error). Mark the COM round-trip `[LiveMxAccessFact]` and `Skip` per the `AlarmsLiveSmokeTests` precedent.
+
+**Step 3: Build x86 + run unit tests.**
+`dotnet build src/ZB.MOM.WW.MxGateway.Worker/ZB.MOM.WW.MxGateway.Worker.csproj -p:Platform=x86`
+`dotnet test ...Worker.Tests... -p:Platform=x86 --filter FullyQualifiedName~LmxSubtagAlarmSourceTests`
+
+**Step 4: Commit.**
+```bash
+git add src/ZB.MOM.WW.MxGateway.Worker/MxAccess/LmxSubtagAlarmSource.cs \
+        src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/LmxSubtagAlarmSourceTests.cs
+git commit -m "worker(alarms): COM-backed LmxSubtagAlarmSource advising alarm subtags"
+```
+
+---
+
+### Task 7: `FailoverAlarmConsumer` state machine
+
+**Classification:** high-risk
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (depends on Task 5)
+
+**Files:**
+- Create: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/FailoverAlarmConsumer.cs`
+- Create: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/AlarmProviderModeChange.cs` (small EventArgs)
+- Test: `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/FailoverAlarmConsumerTests.cs`
+
+**Step 1: Test the switch/failback with a fake primary that throws.**
+
+```csharp
+public sealed class FailoverAlarmConsumerTests
+{
+    private sealed class FlakyPrimary : IMxAccessAlarmConsumer
+    {
+        public event EventHandler<MxAlarmTransitionEvent>? AlarmTransitionEmitted;
+        public int PollsUntilHeal = int.MaxValue;   // becomes healthy after N polls while degraded
+        public bool ThrowOnPoll = true;
+        private int _polls;
+        public void Subscribe(string s) { if (ThrowOnPoll) throw new COMException("boom", unchecked((int)0x80004005)); }
+        public void PollOnce()
+        {
+            _polls++;
+            if (ThrowOnPoll && _polls < PollsUntilHeal) throw new COMException("boom", unchecked((int)0x80004005));
+        }
+        public int AcknowledgeByGuid(Guid g, string c, string a, string b, string d, string e) => 0;
+        public int AcknowledgeByName(string n, string p, string gr, string c, string a, string b, string d, string e) => 0;
+        public IReadOnlyList<MxAlarmSnapshotRecord> SnapshotActiveAlarms() => Array.Empty<MxAlarmSnapshotRecord>();
+        public void Dispose() { }
+    }
+
+    private sealed class StubStandby : IMxAccessAlarmConsumer { /* records Subscribe, no-op rest */ }
+
+    [Fact]
+    public void Primary_FailsThresholdTimes_SwitchesToSubtagAndEmitsModeChange()
+    {
+        var primary = new FlakyPrimary();
+        var standby = new StubStandby();
+        using var c = new FailoverAlarmConsumer(primary, standby,
+            new FailoverSettings(threshold: 3, probeIntervalSeconds: 30, stableProbes: 3));
+        AlarmProviderModeChange? change = null;
+        c.ProviderModeChanged += (_, e) => change = e;
+
+        c.Subscribe("\\\\host\\Galaxy!Area");     // primary.Subscribe throws -> counts as failure 1
+        c.PollOnce();                              // failure 2
+        c.PollOnce();                              // failure 3 -> switch
+
+        Assert.NotNull(change);
+        Assert.Equal(AlarmProviderMode.Subtag, change!.Mode);
+    }
+
+    [Fact]
+    public void WhileDegraded_PrimaryHeals_FailsBackAfterStableProbes()
+    {
+        var primary = new FlakyPrimary { PollsUntilHeal = 0 }; // will heal once we stop throwing
+        var standby = new StubStandby();
+        using var c = new FailoverAlarmConsumer(primary, standby,
+            new FailoverSettings(threshold: 1, probeIntervalSeconds: 0, stableProbes: 2));
+        var modes = new List<AlarmProviderMode>();
+        c.ProviderModeChanged += (_, e) => modes.Add(e.Mode);
+
+        c.Subscribe("x");          // failure -> switch to subtag
+        primary.ThrowOnPoll = false;
+        c.ProbeOnce();             // clean probe 1
+        c.ProbeOnce();             // clean probe 2 -> failback
+
+        Assert.Equal(AlarmProviderMode.Subtag, modes[0]);
+        Assert.Equal(AlarmProviderMode.Alarmmgr, modes[^1]);
+    }
+}
+```
+
+**Step 2: Implement.**
+- `record FailoverSettings(int threshold, int probeIntervalSeconds, int stableProbes)`; `AlarmProviderModeChange : EventArgs { AlarmProviderMode Mode; string Reason; int HResult; DateTime AtUtc; }`.
+- Constructor `(IMxAccessAlarmConsumer primary, IMxAccessAlarmConsumer standby, FailoverSettings settings)`; forced-mode variants handled in Task 9 wiring (forced ⇒ skip the other consumer).
+- Forward `AlarmTransitionEmitted` from the **active** child only (swap the subscription on switch).
+- Wrap `Subscribe`/`PollOnce` on the primary: on `COMException` (or a failure HRESULT) while `PrimaryActive`, increment a counter; at `threshold`, ensure standby `Subscribe`d, set active=standby, snapshot standby for hand-off, raise `ProviderModeChanged(Subtag, reason, hresult, now)`. Reset counter on any clean primary poll.
+- `ProbeOnce()` (driven by the poll loop while degraded, gated by `probeIntervalSeconds`): try primary `Subscribe`+`PollOnce`; count consecutive clean probes; at `stableProbes`, set active=primary, return standby to standby, raise `ProviderModeChanged(Alarmmgr, "recovered", 0, now)`.
+- `Acknowledge*` / `SnapshotActiveAlarms` delegate to the **active** child.
+- `PollOnce()` drives the active child's poll, and—while degraded—also drives the failback probe cadence.
+
+**Step 3: Run green** (x86 filter `FailoverAlarmConsumerTests`).
+
+**Step 4: Commit.**
+```bash
+git add src/ZB.MOM.WW.MxGateway.Worker/MxAccess/FailoverAlarmConsumer.cs \
+        src/ZB.MOM.WW.MxGateway.Worker/MxAccess/AlarmProviderModeChange.cs \
+        src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/FailoverAlarmConsumerTests.cs
+git commit -m "worker(alarms): FailoverAlarmConsumer auto-failover/failback state machine"
+```
+
+---
+
+### Task 8: Synthetic-GUID helper + degraded flag on the event sink path
+
+**Classification:** standard
+**Estimated implement time:** ~4 min
+**Parallelizable with:** Task 9
+
+Carry `degraded` + `source_provider` from the worker synthesis into the emitted `OnAlarmTransitionEvent`.
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAlarmSnapshot.cs` (add `bool Degraded`)
+- Modify: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessAlarmEventSink.cs` (`EnqueueTransition` carries degraded)
+- Modify: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessEventMapper.cs` (`CreateOnAlarmTransition` sets `Degraded`/`SourceProvider`)
+- Create: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SyntheticAlarmGuid.cs`
+- Test: add cases to `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/AlarmDispatcherTests.cs` and a new `SyntheticAlarmGuidTests.cs`
+
+**Step 1: `SyntheticAlarmGuid.ForReference(string reference)`** — deterministic GUID from a stable hash (e.g. MD5 of the UTF-8 reference → `new Guid(bytes)`), so subtag-mode acks resolve by GUID. Test determinism + difference:
+
+```csharp
+[Fact] public void SameReference_SameGuid() =>
+    Assert.Equal(SyntheticAlarmGuid.ForReference("A.B.C"), SyntheticAlarmGuid.ForReference("A.B.C"));
+[Fact] public void DifferentReference_DifferentGuid() =>
+    Assert.NotEqual(SyntheticAlarmGuid.ForReference("A.B.C"), SyntheticAlarmGuid.ForReference("A.B.D"));
+```
+
+**Step 2: Thread `degraded`** through `MxAlarmSnapshotRecord.Degraded`, `EnqueueTransition(... bool degraded)`, and `CreateOnAlarmTransition(... bool degraded, AlarmProviderMode sourceProvider)`. Default `degraded=false`, `sourceProvider=Alarmmgr` so the wnwrap path is unchanged (regression: existing `AlarmDispatcherTests` still pass with `Degraded=false`).
+
+**Step 3: Tests** — extend `AlarmDispatcherTests` with a subtag-style transition asserting `body.Degraded == true` and `SourceProvider == Subtag`.
+
+**Step 4: Build x86 + run** worker tests for `AlarmDispatcherTests`, `SyntheticAlarmGuidTests`.
+
+**Step 5: Commit.**
+```bash
+git add src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAlarmSnapshot.cs \
+        src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessAlarmEventSink.cs \
+        src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessEventMapper.cs \
+        src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SyntheticAlarmGuid.cs \
+        src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/
+git commit -m "worker(alarms): synthetic GUID + degraded provenance on emitted transitions"
+```
+
+---
+
+### Task 9: Wire watch-list + failover config through `AlarmCommandHandler`; emit mode-changed event
+
+**Classification:** high-risk
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (depends on Tasks 5, 7, 8)
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/AlarmCommandHandler.cs`
+- Modify: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/IAlarmCommandHandler.cs`
+- Modify: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessCommandExecutor.cs` (`ExecuteSubscribeAlarms`, ~lines 588-616)
+- Modify: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs` (consumer factory wiring; mode-change → event queue)
+- Test: `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/AlarmCommandHandlerTests.cs` (extend or create)
+
+**Step 1: Carry the subscribe payload.** Change the alarm subscribe entry point from `Subscribe(string subscription)` to `Subscribe(SubscribeAlarmsCommand command)` (the command now has `ForcedMode`, `WatchList`, `Failover`). In `AlarmCommandHandler.Subscribe`:
+- Build the active provider per `ForcedMode`:
+  - `ALARMMGR` ⇒ `WnWrapAlarmConsumer` only.
+  - `SUBTAG` ⇒ `SubtagAlarmConsumer(new LmxSubtagAlarmSource(factory), watchList)` only.
+  - `UNSPECIFIED` ⇒ `FailoverAlarmConsumer(primary: wnwrap, standby: subtag, settings-from-Failover)`.
+- Use the existing `consumerFactory` seam but widen it to `Func<SubscribeAlarmsCommand, IMxAccessAlarmConsumer>` so tests inject fakes and production builds the failover composite. Subscribe to `FailoverAlarmConsumer.ProviderModeChanged` and enqueue an `OnAlarmProviderModeChangedEvent` MxEvent via the event queue (new mapper method `CreateOnAlarmProviderModeChanged`).
+
+**Step 2: Executor + STA wiring.** `ExecuteSubscribeAlarms` passes the full `SubscribeAlarmsCommand` (not just the expression). In `MxAccessStaSession`, the `alarmCommandHandlerFactory` must give the handler access to the `IMxAccessComObjectFactory` so the subtag source can create its own proxy server on the STA; keep the `EnsureOnAlarmConsumerThread` affinity guard on every path.
+
+**Step 3: Test** — fake consumer factory; assert that a `SUBTAG` forced command builds the subtag consumer and advises; that an auto command building a fake failover composite, when it raises `ProviderModeChanged`, enqueues an `OnAlarmProviderModeChangedEvent` on the queue.
+
+**Step 4: Build x86 + worker tests.**
+
+**Step 5: Commit.**
+```bash
+git add src/ZB.MOM.WW.MxGateway.Worker/MxAccess/ src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/
+git commit -m "worker(alarms): route watch-list/failover config; emit provider-mode-changed event"
+```
+
+---
+
+## Phase 2 — Gateway: discovery, options, monitor, metrics, dashboard
+
+### Task 10: `AlarmsOptions.Fallback` + validation
+
+**Classification:** standard
+**Estimated implement time:** ~4 min
+**Parallelizable with:** Task 11, Task 13
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Server/Configuration/AlarmsOptions.cs`
+- Create: `src/ZB.MOM.WW.MxGateway.Server/Configuration/AlarmFallbackOptions.cs`
+- Modify: `src/ZB.MOM.WW.MxGateway.Server/Configuration/GatewayOptionsValidator.cs` (`ValidateAlarms`, ~lines 234-258)
+- Test: `src/ZB.MOM.WW.MxGateway.Tests/Configuration/GatewayOptionsValidatorTests.cs` (extend)
+
+**Step 1:** Add `AlarmFallbackOptions Fallback { get; init; } = new();` to `AlarmsOptions`. `AlarmFallbackOptions`: `string Mode = "Auto"` (`Auto|ForceAlarmManager|ForceSubtag`), `int ConsecutiveFailureThreshold = 3`, `int FailbackProbeIntervalSeconds = 30`, `int FailbackStableProbes = 3`, a `Discovery` sub-object (`bool UseGalaxyRepository = true`, `string Area = ""`, `string[] IncludeAttributes = []`, `string[] ExcludeAttributes = []`), and a `Subtags` sub-object (`Active="active"`, `Acked="acked"`, `AckComment=""`, `Priority="priority"`).
+
+**Step 2:** In `ValidateAlarms`, when `Enabled` and `Mode == "ForceSubtag"` and `Discovery.UseGalaxyRepository == false` and `IncludeAttributes` empty ⇒ add a validation error ("ForceSubtag requires Galaxy Repository discovery or an explicit IncludeAttributes list"). Floor the three numeric values at 1. Validate `Mode` is one of the three literals.
+
+**Step 3-5:** Test the new validation cases (red→green), build the server, commit.
+
+---
+
+### Task 11: Galaxy Repository "alarm attributes" discovery query
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 10, Task 13
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Server/Galaxy/GalaxyRepository.cs` (add `GetAlarmAttributesAsync` + SQL constant, following `GetAttributesAsync` ~lines 86-115 and `AttributesSql` ~line 176)
+- Modify: `src/ZB.MOM.WW.MxGateway.Server/Galaxy/IGalaxyRepository.cs`
+- Create: `src/ZB.MOM.WW.MxGateway.Server/Galaxy/GalaxyAlarmAttributeRow.cs`
+- Test: `src/ZB.MOM.WW.MxGateway.Tests/Galaxy/` (projection unit test; live SQL gated)
+
+**Step 1:** `GalaxyAlarmAttributeRow { string FullTagReference; string SourceObjectReference; string AckCommentSubtag; }` (and any priority subtag). `GetAlarmAttributesAsync` reuses the existing `is_alarm` detection (the `AlarmExtension` primitive join already in `AttributesSql`) filtered to `is_alarm = 1`, projecting the alarm reference + its ack-comment attribute. Follow the exact `SqlConnection`/`SqlCommand`/`SqlDataReader` pattern from `GetAttributesAsync`.
+
+**Step 2:** Unit-test the row→`AlarmSubtagTarget` mapping (a pure mapper function); gate any live-DB test like the existing Galaxy live tests (or `Skip` with a note, matching `AlarmsLiveSmokeTests`).
+
+**Step 3-5:** red→green, build server, commit.
+
+---
+
+### Task 12: Watch-list resolver (GR SQL + config override → `AlarmSubtagTarget[]`)
+
+**Classification:** standard
+**Estimated implement time:** ~4 min
+**Parallelizable with:** none (depends on Tasks 10, 11)
+
+**Files:**
+- Create: `src/ZB.MOM.WW.MxGateway.Server/Alarms/AlarmWatchListResolver.cs`
+- Create: `src/ZB.MOM.WW.MxGateway.Server/Alarms/IAlarmWatchListResolver.cs`
+- Test: `src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmWatchListResolverTests.cs`
+
+**Step 1: Test the merge** with a fake `IGalaxyRepository`:
+- discovery rows + `IncludeAttributes` are unioned; `ExcludeAttributes` removed; each becomes an `AlarmSubtagTarget` with `.active`/`.acked`/`.ackmsg` addresses composed from the configured `Subtags` names (`<reference>.<Active>`, etc.); empty config subtag names fall back to defaults; GR unavailable + no includes ⇒ empty list + a logged warning flag.
+
+**Step 2: Implement** `ResolveAsync(AlarmsOptions, CancellationToken) → IReadOnlyList<AlarmSubtagTarget>`.
+
+**Step 3-5:** red→green, build, commit.
+
+---
+
+### Task 13: Gateway metrics — provider-mode gauge + switch counter
+
+**Classification:** small
+**Estimated implement time:** ~3 min
+**Parallelizable with:** Task 10, Task 11
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Server/Metrics/GatewayMetrics.cs` (ctor ~lines 55-79; add counter + observable gauge following the existing pattern)
+- Test: `src/ZB.MOM.WW.MxGateway.Tests/Metrics/GatewayMetricsTests.cs` (if present; else assert via a `MeterListener`)
+
+**Step 1:** Add `mxgateway.alarms.provider_switches` counter (tagged `from`,`to`,`reason`) and `mxgateway.alarms.provider_mode` observable gauge (1=alarmmgr, 2=subtag), plus `AlarmProviderSwitched(int from, int to, string reason)` and a private `GetAlarmProviderMode()` (lock on `_syncRoot` like the others).
+
+**Step 2-4:** test, build, commit.
+
+---
+
+### Task 14: `GatewayAlarmMonitor` — arm watch-list, reflect provider mode, reconcile on switch
+
+**Classification:** high-risk
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (depends on Tasks 9, 12, 13)
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Server/Alarms/GatewayAlarmMonitor.cs` (ctor ~41-49; `SubscribeAlarmsAsync` ~210-233; event-drain loop; `StreamAsync` ~386-434)
+- Test: `src/ZB.MOM.WW.MxGateway.Tests/Alarms/GatewayAlarmMonitorProviderModeTests.cs` (new, using `FakeWorkerHarness`)
+
+**Step 1:** Inject `IAlarmWatchListResolver` and `GatewayMetrics`. In `SubscribeAlarmsAsync`, resolve the watch-list and build the `SubscribeAlarmsCommand` with `ForcedMode` (from `Fallback.Mode`), `WatchList`, and `Failover` populated from options — instead of the bare `{ SubscriptionExpression }`.
+
+**Step 2:** In the worker-event drain path, handle `OnAlarmProviderModeChangedEvent`: update a `_providerStatus` field (mode/degraded/reason/since), `Broadcast(new AlarmFeedMessage { ProviderStatus = … })` to every subscriber, call `metrics.AlarmProviderSwitched(...)`, and force a `ReconcileAsync` so the cache re-seeds from the now-active provider (avoids raise/clear storms).
+
+**Step 3:** In `StreamAsync`, emit the current `provider_status` as the **first** message (before the snapshot) so a late joiner immediately knows the mode.
+
+**Step 4: Test** — stand up the monitor with `FakeWorkerHarness`; emit an `OnAlarmProviderModeChangedEvent(Subtag)`; assert a `StreamAsync` subscriber receives a `ProviderStatus{ Mode=Subtag, Degraded=true }` and that the switch counter incremented. Also assert a transition emitted in subtag mode flows through with `Degraded=true`.
+
+**Step 5:** build server, run the new test, commit.
+
+---
+
+### Task 15: Dashboard — push provider status to `/hubs/alarms` + UI indicator
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (depends on Task 14)
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Hubs/AlarmsHubPublisher.cs` (forward `ProviderStatus` messages — they already flow through `StreamAsync`, so confirm the existing `SendAsync(AlarmMessage, message)` carries them; add a dedicated `"ProviderModeChanged"` client method if the dashboard needs a distinct channel)
+- Modify: the alarms dashboard page/component (Bootstrap-only badge: green "alarmmgr" / amber "degraded — subtag") — find under `src/ZB.MOM.WW.MxGateway.Server/Dashboard/`
+- Test: `src/ZB.MOM.WW.MxGateway.Tests/` dashboard model test (e.g. a `DashboardAlarmProviderStatus.FromFeed` mapper, mirroring `DashboardActiveAlarm.FromSnapshot`)
+
+**Constraint:** Bootstrap CSS/JS only — no MudBlazor/Radzen/FluentUI.
+
+**Steps:** TDD the model mapper, wire the publisher + badge, build, commit.
+
+---
+
+## Phase 3 — Integration, docs, live smoke
+
+### Task 16: End-to-end fake-worker failover test
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 18
+
+**Files:**
+- Test: `src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmFailoverEndToEndTests.cs`
+
+Drive the full gateway path with `FakeWorkerHarness`: subscribe (assert the `SubscribeAlarmsCommand` carries a watch-list), emit a wnwrap-style transition (assert `Degraded=false`), emit `OnAlarmProviderModeChangedEvent(Subtag)`, emit a synthesized transition (assert `Degraded=true`, `SourceProvider=Subtag`), then `OnAlarmProviderModeChangedEvent(Alarmmgr)` and assert the feed reports recovery. Build, run, commit.
+
+---
+
+### Task 17: Live subtag smoke test (opt-in)
+
+**Classification:** small
+**Estimated implement time:** ~4 min
+**Parallelizable with:** Task 18
+
+**Files:**
+- Test: `src/ZB.MOM.WW.MxGateway.IntegrationTests/...AlarmSubtagLiveSmokeTests.cs` (or the worker live suite)
+
+A `[LiveMxAccessFact]`, `Skip`-by-default test (per `AlarmsLiveSmokeTests` precedent) that, against a live Galaxy + alarm flip script: advises the real `.active`/`.acked` subtags via `LmxSubtagAlarmSource`, asserts a synthesized raise/clear, and performs an ack via the ack-comment write. Document the exact subtag names discovered (resolves the design's open item). Commit.
+
+---
+
+### Task 18: Documentation
+
+**Classification:** trivial
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 16, Task 17
+
+**Files:**
+- Modify: `gateway.md` (alarm provider section: dual provider + auto-failover/failback)
+- Modify: `docs/DesignDecisions.md` (record the fallback decision + parity rationale)
+- Modify: `docs/GatewayConfiguration.md` (the `MxGateway:Alarms:Fallback` block)
+- Modify: `docs/AlarmClientDiscovery.md` (subtag provider, synthesis rules, ack-comment write)
+- Modify: `docs/Grpc.md` (new `provider_status` feed case + `degraded`/`source_provider` fields)
+
+Follow `StyleGuide.md` (PascalCase filenames, present tense, explain *why*). No code; commit.
+
+---
+
+## Execution order & parallelism summary
+
+- **Serial spine:** 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8/9 → 10/11 → 12 → 13 → 14 → 15 → 16 → 17/18.
+- **Parallelizable clusters:** {8, 9 partially}, {10, 11, 13}, {16, 17, 18}.
+- **High-risk tasks** (full review chain): 1, 2, 6, 7, 9, 14. **Standard:** 4, 5, 8, 10, 11, 12, 15, 16. **Small/trivial:** 3, 13, 17, 18.
+
+## Risk notes for the executor
+
+- **Field-number collisions:** Task 2 must read the live `MxEvent`/`MxEventFamily` numbers before adding — the agent map gave alarm-payload maxima but not `MxEvent`'s. Verify before editing.
+- **STA discipline:** every COM call in `LmxSubtagAlarmSource` and every consumer swap runs on the worker STA; keep the `EnsureOnAlarmConsumerThread` guard. The worker STA already pumps Windows messages, which is required for the subtag `OnDataChange` to deliver.
+- **Parity regression:** alarmmgr-mode output must be byte-for-byte unchanged. Existing `AlarmDispatcherTests` and `ProtobufContractRoundTripTests` are the guardrail — they must stay green with `Degraded=false` defaults.
+- **Subtag names unverified:** the design leaves exact AVEVA subtag names (`.active`, `.acked`, ack-comment) to confirm against `C:\Users\dohertj2\Desktop\mxaccess` + a live Galaxy (Task 17). The config `Subtags` block exists so names are not hard-coded.

docs/plans/2026-06-13-alarm-subtag-fallback.md.tasks.json

@@ -0,0 +1,147 @@
+{
+  "planPath": "docs/plans/2026-06-13-alarm-subtag-fallback.md",
+  "tasks": [
+    {
+      "id": 54,
+      "subject": "Task 1: Worker proto \u2014 watch-list, failover config, AlarmProviderMode",
+      "status": "completed"
+    },
+    {
+      "id": 55,
+      "subject": "Task 2: Gateway proto \u2014 provider status, degraded provenance, mode-changed event",
+      "status": "completed",
+      "blockedBy": [
+        54
+      ]
+    },
+    {
+      "id": 56,
+      "subject": "Task 3: Proto round-trip tests for new alarm fields",
+      "status": "completed",
+      "blockedBy": [
+        54,
+        55
+      ]
+    },
+    {
+      "id": 57,
+      "subject": "Task 4: Subtag value-source abstraction + synthesis state machine",
+      "status": "completed",
+      "blockedBy": [
+        54
+      ]
+    },
+    {
+      "id": 58,
+      "subject": "Task 5: SubtagAlarmConsumer over the source seam",
+      "status": "completed",
+      "blockedBy": [
+        57
+      ]
+    },
+    {
+      "id": 59,
+      "subject": "Task 6: COM-backed LmxSubtagAlarmSource",
+      "status": "completed",
+      "blockedBy": [
+        57
+      ]
+    },
+    {
+      "id": 60,
+      "subject": "Task 7: FailoverAlarmConsumer state machine",
+      "status": "completed",
+      "blockedBy": [
+        58
+      ]
+    },
+    {
+      "id": 61,
+      "subject": "Task 8: Synthetic GUID + degraded flag on event sink path",
+      "status": "completed",
+      "blockedBy": [
+        55
+      ]
+    },
+    {
+      "id": 62,
+      "subject": "Task 9: Wire watch-list/failover through AlarmCommandHandler; emit mode-changed",
+      "status": "completed",
+      "blockedBy": [
+        58,
+        60,
+        61
+      ]
+    },
+    {
+      "id": 63,
+      "subject": "Task 10: AlarmsOptions.Fallback + validation",
+      "status": "completed"
+    },
+    {
+      "id": 64,
+      "subject": "Task 11: Galaxy Repository alarm-attributes discovery query",
+      "status": "completed"
+    },
+    {
+      "id": 65,
+      "subject": "Task 12: Watch-list resolver (GR SQL + config override)",
+      "status": "completed",
+      "blockedBy": [
+        54,
+        63,
+        64
+      ]
+    },
+    {
+      "id": 66,
+      "subject": "Task 13: Metrics \u2014 provider-mode gauge + switch counter",
+      "status": "completed"
+    },
+    {
+      "id": 67,
+      "subject": "Task 14: GatewayAlarmMonitor \u2014 arm watch-list, reflect mode, reconcile on switch",
+      "status": "completed",
+      "blockedBy": [
+        55,
+        62,
+        65,
+        66
+      ]
+    },
+    {
+      "id": 68,
+      "subject": "Task 15: Dashboard \u2014 push provider status + UI badge",
+      "status": "completed",
+      "blockedBy": [
+        67
+      ]
+    },
+    {
+      "id": 69,
+      "subject": "Task 16: End-to-end fake-worker failover test",
+      "status": "completed",
+      "blockedBy": [
+        67
+      ]
+    },
+    {
+      "id": 70,
+      "subject": "Task 17: Live subtag smoke test (opt-in)",
+      "status": "completed",
+      "blockedBy": [
+        59,
+        62
+      ]
+    },
+    {
+      "id": 71,
+      "subject": "Task 18: Documentation",
+      "status": "completed",
+      "blockedBy": [
+        67
+      ]
+    }
+  ],
+  "lastUpdated": "2026-06-13T13:30:00Z"
+}

docs/plans/2026-06-14-deferred-followups.md

@@ -0,0 +1,270 @@
+# Deferred Follow-ups Implementation Plan
+
+**Date:** 2026-06-14
+**Status:** Plan only — NOT yet executed. Saved for review.
+**Context:** After the alarm-subtag-fallback cleanup (merged `5976770`) and its redeploy to
+windev (10.100.0.48), five items remain deferred. This plan handles all five. They are
+independent — execute in any order, or cherry-pick. Items D1–D2 are code (branch off `main`);
+D3 is a dev-rig validation; D4–D5 are ops on the deployed hosts (no code).
+
+Source of the deferred list: the post-deploy review on 2026-06-14. See also memory
+`project_deploy_mechanics`, `project_wonder_deployment`, `project_alarm_subtag_fallback`,
+`project_rig_alarms_object_driven`.
+
+---
+
+## D1 — Surface `AlarmProviderSwitchCount` on the dashboard metric list
+
+**Classification:** small · **Est:** ~10 min · **Where:** Server (net10), build+test on macOS
+**Why deferred:** the dashboard reads provider *state* from the feed's `ProviderStatus` badge,
+not the metrics snapshot, so the snapshot field (added in B1) and the OTEL counter were enough.
+This makes the cumulative switch count visible in the dashboard's metric table too.
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSnapshotService.cs` (`CreateMetricSummaries`, ~line 178–198)
+- Test: `src/ZB.MOM.WW.MxGateway.Tests/Dashboard/DashboardSnapshotServiceTests.cs` (or the existing snapshot test file)
+
+**Steps:**
+1. In `CreateMetricSummaries`, add to the `metrics` list (near the other counters):
+   `new("mxgateway.alarms.provider_switches", snapshot.AlarmProviderSwitchCount),`
+   Also consider adding the current mode as a gauge row if useful:
+   the snapshot does not carry the mode int (only the feed does), so DO NOT invent one —
+   only add the switch count, which the snapshot already exposes.
+2. Add/extend a unit test asserting the summary list contains a
+   `mxgateway.alarms.provider_switches` row equal to the snapshot's `AlarmProviderSwitchCount`
+   after calling `metrics.AlarmProviderSwitched(...)`.
+3. Verify: `dotnet build src/ZB.MOM.WW.MxGateway.Server` (macOS) and
+   `dotnet test src/ZB.MOM.WW.MxGateway.Tests --filter FullyQualifiedName~DashboardSnapshot`.
+4. Commit.
+
+**Rollback:** revert the one-line list addition.
+
+---
+
+## D2 — Reproduce and fix the `AmbiguousMatchException` on `GET /`
+
+**Classification:** standard · **Est:** ~30–45 min (repro + fix) · **Where:** Server (net10)
+**Why deferred:** observed only in *old* (06/05, Development) logs:
+`AmbiguousMatchException: The request matched multiple endpoints. Matches: / (/) / (/)`.
+Unauthenticated `GET /` safely 302s to `/login`; the ambiguity would only throw for an
+*authenticated* request that reaches routing. Pre-existing and unrelated to the alarm work,
+but it would surface as a dashboard-home 500. Confirm it still reproduces before fixing.
+
+**Root-cause candidates (the two endpoints both matching `/`):**
+- `DashboardHome.razor` (`@page "/"`) mapped by `MapRazorComponents<App>()`
+  (`Dashboard/DashboardEndpointRouteBuilderExtensions.cs:92`).
+- `MapStaticAssets(...)` (`GatewayApplication.cs:190`) — in .NET 8–10 the static-assets
+  endpoint can register a fingerprinted root that collides with the home page.
+
+**Step 0 — Reproduce (do this first; if it does NOT repro, downgrade to a documentation note):**
+1. Log into the dashboard as `multi-role`/`password` (Administrator) at
+   `http://10.100.0.48:5130/login`.
+2. Navigate to `http://10.100.0.48:5130/` (the "Dashboard" home).
+3. If it renders the Overview page → not a live bug on this build; record that and stop
+   (the dev error-page throw was a Development-only artifact). If it 500s with
+   `AmbiguousMatchException` → proceed to fix.
+
+**Fix (only if it reproduces):**
+- Files: `src/ZB.MOM.WW.MxGateway.Server/GatewayApplication.cs` (endpoint mapping order/region),
+  `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardEndpointRouteBuilderExtensions.cs`,
+  `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/DashboardHome.razor`.
+- Candidate fixes, in order of preference:
+  1. Inspect the actual two matched endpoint display names at runtime (the exception lists
+     them) — temporarily enable detailed errors or read the stderr `Matches:` block — to learn
+     exactly which two collide.
+  2. If `MapStaticAssets` owns the second `/`: it must run, but confirm it isn't double-mapping
+     the home route; if it is, move `MapStaticAssets` ordering or scope it so it doesn't claim
+     the literal `/` content path. (Do NOT remove `MapStaticAssets` — Blazor needs it.)
+  3. If two component pages both declare `@page "/"`: give the non-home one a distinct route.
+  4. Last resort: give `DashboardHome` an explicit route (e.g. `@page "/overview"`) and add a
+     trivial `MapGet("/", () => Results.Redirect("/overview"))` with `.RequireAuthorization(...)`.
+- Add a test that exercises the root route once resolved (a WebApplicationFactory-based
+  integration test asserting authenticated `GET /` returns 200, if the dashboard test harness
+  supports auth; otherwise a routing-uniqueness assertion).
+- Verify: `dotnet build src/ZB.MOM.WW.MxGateway.Server`; re-run the authenticated `GET /` repro.
+
+**Rollback:** revert the routing change; the home page returns to its prior (ambiguous) state.
+
+**Note:** this fix ships only via a Server redeploy (D-deploy applies, see D5/windev redeploy
+procedure in `project_deploy_mechanics`). Decide whether to bundle it with the next redeploy.
+
+---
+
+## D3 — Validate the failover path end-to-end on the dev rig (ForceSubtag)
+
+**Classification:** standard (validation, no production code) · **Est:** ~30–45 min · **Where:** dev rig / windev
+**Why deferred:** `provider_mode 1` (healthy alarmmgr) is verified in production, but the actual
+alarmmgr→subtag **failover**, the **degraded badge**, the synthesized subtag alarms, and the
+`provider_switches{from,to,reason}` counter (with the new bounded `failover`/`failback`/`unknown`
+tag) have never fired live — a healthy system never switches, and the rig's alarms can't be made
+to fail COM on demand. Use the explicit `ForceSubtag` config mode to exercise the degraded path
+deterministically without an alarmmgr fault.
+
+**Approach:** run a *temporary* gateway instance (NOT the production service) in `ForceSubtag`
+mode against the dev Galaxy, drive it with the operator/IDE alarm toggle, and confirm the
+degraded surface. Do this on windev in a throwaway run so production stays on `Auto`.
+
+**Steps:**
+1. On windev, from a build worktree at `main`, run the Server locally (or a second instance on
+   alt ports) with `MxGateway:Alarms:Fallback:Mode=ForceSubtag` (env
+   `MxGateway__Alarms__Fallback__Mode=ForceSubtag`), pointed at the dev Galaxy
+   (`\\DESKTOP-6JL3KKO\Galaxy!DEV`). Use distinct Kestrel ports to avoid clashing with the
+   production service on 5120/5130.
+2. Subscribe an alarm client (or open the dashboard alarms page for that instance) and confirm:
+   - The provider badge shows **"Subtag monitoring (degraded)"** (amber `bg-warning`).
+   - `curl .../metrics` shows `mxgateway_alarms_provider_mode 2`.
+   - Active alarms appear with `degraded=true` and a synthetic (MD5-derived) GUID, with the
+     reference shape `Galaxy!<realArea>.<object>.<attr>` (e.g. `Galaxy!TestArea.TestMachine_001.TestAlarm001`).
+3. Drive a transition: have the operator/IDE toggle a `TestMachine_NNN.TestAlarmNNN` true→false
+   (external MXAccess writes are ignored — see `project_rig_alarms_object_driven`); confirm a
+   synthesized Raise then Clear, and an `AckMsg` write via AcknowledgeByName returns 0.
+4. (Optional, to exercise the switch counter) run in `Auto` and induce a primary fault if a safe
+   way exists; otherwise document that the counter is unit-tested only and `ForceSubtag` covers
+   the degraded surface. Note: `ForceSubtag` may not increment `provider_switches` (no runtime
+   switch) — that counter's live exercise remains the one gap; record it explicitly rather than
+   claiming coverage.
+5. Tear down the temporary instance. Production service is untouched (stays `Auto`).
+6. Record results in `project_alarm_subtag_fallback` memory (degraded badge + synthesized
+   subtag alarms now live-validated; switch-counter still unit-test-only if not exercised).
+
+**Rollback:** none — temporary instance only; nothing in production changes.
+
+---
+
+## D4 — Prune stale deploy backups on windev
+
+**Classification:** trivial (ops) · **Est:** ~10 min · **Where:** windev (10.100.0.48), no code
+**Why deferred:** backups accumulate on every deploy; harmless but cluttering
+`C:\publish\mxaccessgw\`.
+
+**Current backups observed (2026-06-14):**
+- `Server.bak-20260526T143341`, `Server.bak-20260529T090320`, `Server.bak529.20260604T122616`,
+  `Server.bak-theme030-20260605-053056`, `Server.bak-theme031-20260605-083410`,
+  `Server.bak-20260614-prefallback` (today's), `Worker.bak-20260614-prefallback` (today's).
+- Inside `Server\`: `ZB.MOM.WW.MxGateway.Server.dll.bak-20260604-loginfix`,
+  `appsettings.json.bak-20260604-{glauth35,ldapkeys}`.
+
+**Steps:**
+1. **Keep** `Server.bak-20260614-prefallback` and `Worker.bak-20260614-prefallback` — the
+   immediate rollback for the current deploy. Keep until the new build has soaked (e.g. a few
+   days / one business cycle).
+2. Delete the clearly-superseded older backups: the `Server.bak-2026052*`, `Server.bak529.*`,
+   and `Server.bak-theme03*` dirs. Confirm each is a Server dir (not something live) before
+   `rmdir /s /q`.
+3. Optionally remove the in-`Server` `.bak-*` sidecar files (`*.dll.bak-*`,
+   `appsettings.json.bak-*`) — but FIRST confirm the live `appsettings.json` is correct (it is,
+   post-deploy) so the `.bak` ldap/glauth copies aren't the only record of a needed value.
+4. Verify the service is unaffected: `Get-Service MxAccessGw` Running, `/health/ready` 200.
+
+**Rollback:** none needed (deletions only; the current-deploy backup is retained). If unsure
+about any single dir, skip it.
+
+---
+
+## D5 — Redeploy the wonder host to bring it to parity
+
+**Classification:** high-risk (separate production-ish box, fiddly access, divergent build) · **Est:** ~1–2 h · **Where:** wonder-app-vd03.zmr.zimmer.com (10.220.157.247)
+**Why deferred:** wonder still runs the pre-feature build — it lacks the entire alarm-fallback
+feature and the cleanup. Bring it to `5976770` if parity is wanted. This box is materially
+different from windev (read `project_wonder_deployment` fully before starting).
+
+**Key differences from windev (do NOT reuse the windev recipe blindly):**
+- Access: no usable `ssh host "cmd"` exec. Port 22 OpenSSH (PowerShell) was observed CLOSED
+  2026-05-26; the reliable path is **servecli on port 2222** (cmd.exe PTY + SFTP only) using the
+  base64-`-EncodedCommand` pattern in `project_wonder_deployment` / `~/Desktop/servecli/instructions.md`.
+  Re-test port 22 first; if up, prefer it.
+- Build shape: wonder runs a **self-contained single-file win-x64** Server (~118 MB), renamed to
+  `MxGateway.Server.exe` for the NSSM path `E:\ApiInstall\MxGateway\Server\MxGateway.Server.exe`.
+  So publish must be `-r win-x64 --self-contained -p:PublishSingleFile=true` (NOT the
+  framework-dependent windev recipe), then rename the exe to `MxGateway.Server.exe`.
+- Static assets quirk: ship BOTH `ZB.MOM.WW.MxGateway.Server.staticwebassets.endpoints.json` and
+  `MxGateway.Server.staticwebassets.endpoints.json` next to the exe (the ZB-named one is used).
+- Config: wonder's `appsettings.json` carries HTTP-switched Kestrel (`http://0.0.0.0:5130`),
+  `Dashboard.GroupToRole` = `{ SCADA-Admins/Designers/Deploy-All → Admin }`,
+  `Dashboard.RequireHttpsCookie:false`, LDAP base `dc=scadalink,dc=local`. **Preserve wonder's
+  appsettings.json** exactly like windev (do not ship the repo default). Note: wonder's
+  GroupToRole values are `"Admin"` — VERIFY the current build's validator accepts `"Admin"` (the
+  windev crash showed it requires `'Administrator'`/`'Viewer'`). **If the validator rejects
+  `"Admin"`, wonder's appsettings GroupToRole values must be updated to `Administrator` BEFORE/with
+  the deploy or the new build will crash-loop.** This is the single biggest risk — resolve it first.
+- Worker: wonder's x86 worker is the original; the alarm-fallback adds new subscribe fields. To
+  use subtag fallback on wonder, the **x86 worker must also be redeployed** (publish x86, rename
+  if needed). If only the Server is updated, confirm worker IPC protobuf compat (contracts changed
+  for alarms — a stale worker may not understand the extended SubscribeAlarms). Safer to deploy
+  both Server and Worker together.
+
+**Steps (high level — expand against the runbook before executing):**
+1. Confirm parity is actually wanted on wonder, and whether the dashboard (disabled there) and
+   the alarm monitor are even in scope for that box. If alarms/dashboard are off on wonder, this
+   may reduce to "Server binary parity only."
+2. Resolve the **GroupToRole value compatibility** question (Admin vs Administrator) — inspect
+   the current build's `GatewayOptionsValidator` and decide whether to patch wonder's appsettings.
+3. Build self-contained Server (`-r win-x64 --self-contained -p:PublishSingleFile=true`) and x86
+   Worker from `main` (`5976770`).
+4. Transfer via SFTP (servecli) to a staging dir on `E:\ApiInstall\MxGateway\`.
+5. Stop `MxAccessGw`; back up `Server` → `Server.bak.<ts>` and `Worker` → `Worker.bak.<ts>`;
+   swap in the new build; **restore wonder's `appsettings.json`** (+ patched GroupToRole if
+   needed); ensure both staticwebassets manifests are present; rename Server exe to
+   `MxGateway.Server.exe`.
+6. Start `MxAccessGw` (no dependents). Verify stderr line count does not grow (no crash loop),
+   `curl -k https://...:5130/health/live` (or HTTP per current config) Healthy, gRPC 5120 up.
+7. Verify the new metric is present if the metrics endpoint is exposed there.
+
+**Rollback (documented in memory):** stop service,
+`Move-Item Server Server.failed; Move-Item Server.bak.<ts> Server`, restore appsettings from the
+backup, start.
+
+---
+
+## Suggested order
+
+1. **D2 repro** (5 min — just log in and hit `/`): decides whether D2 is a real fix or a no-op.
+2. **D1** (small code) + **D2 fix if needed** — bundle into one Server branch; they ship together
+   on the next Server redeploy.
+3. **D4** (prune windev backups) — quick ops, independent.
+4. **D3** (ForceSubtag validation) — exercises the degraded surface; do before/after the D1+D2
+   redeploy so you also confirm the new Server build is healthy.
+5. **D5** (wonder) — largest and riskiest; do last, only if parity is wanted, and resolve the
+   GroupToRole-value compatibility question first.
+
+## Execution note
+
+This plan is intentionally NOT executed. When ready, execute on a branch off `main`
+(`feat/deferred-followups` or per-item branches) — do not commit to `main` directly. D1/D2 need a
+Server redeploy to take effect; D4/D5 are host operations; D3 touches nothing permanent.
+
+---
+
+## D2 — Resolution (2026-06-14)
+
+Static source determination on build `5976770` (runtime repro out of scope). What was checked:
+
+- **Razor `@page "/"` count:** exactly ONE — `Dashboard/Components/Pages/DashboardHome.razor`.
+  All other pages declare distinct routes (`/login`, `/sessions`, `/galaxy`, `/browse`,
+  `/apikeys`, `/workers`, `/events`, `/alarms`, `/settings`, `/sessions/{SessionId}`).
+- **No root index.html:** `src/ZB.MOM.WW.MxGateway.Server/wwwroot/` contains only `css/` and
+  `lib/` subdirectories; no `index.html` anywhere under `wwwroot/`.
+- **No `UseDefaultFiles` / no `MapFallback`:** neither appears anywhere in the Server project.
+- **`MapStaticAssets` mapped once** (`GatewayApplication.cs:190`) and `UseStaticFiles()` once
+  (`:41`); the static-assets manifest serves fingerprinted CSS/JS assets, not a literal `/`.
+- **No `MapGet("/")`:** the dashboard endpoint builder
+  (`Dashboard/DashboardEndpointRouteBuilderExtensions.cs`) maps only `/auth/login`, `/logout`,
+  `/denied`, `/hubs/{snapshot,alarms,events}`, `/hubs/token`, then `MapRazorComponents<App>()`.
+  None use pattern `/`.
+- **`MapZbHealth` / `MapZbMetrics`** come from the external `ZB.MOM.WW.Health` shared library
+  (not in this repo) and map health/metrics paths, not `/`.
+
+**Root cause of the 2026-06-05 log:** `code-reviews/Server/findings.md` (re-review at `42b0037`,
+2026-05-24) records that commit `de7639a` **removed the legacy `MapGet("/", ...)` redirect that
+was colliding with the Blazor `@page "/"` (a real 500)**. That legacy registration was the source
+of the `AmbiguousMatchException`. It is gone on the current build, so the second `/` endpoint no
+longer exists.
+
+**Conclusion:** No duplicate `/` endpoint on build `5976770`. The AmbiguousMatchException is not
+reproducible from source — it was a stale Development-only artifact from before `de7639a` reached
+the deployed instance. **No source change made** (no-op).
+
+**Residual:** A 100% confirmation still requires an authenticated runtime `GET /` against a
+deployed instance (the only path that exercises routing past the unauthenticated 302-to-`/login`).
+Recommend a spot-check of authenticated `GET /` after the next Server redeploy; if it returns 200
+(not 500), this item can be fully closed.

docs/plans/2026-06-15-forced-subtag-mode-fix.md

@@ -0,0 +1,116 @@
+# ForceSubtag Mode Fix Implementation Plan
+
+> Fixes the two defects surfaced by the D3 live validation (2026-06-15): forced-subtag
+> doesn't actually run subtag (#1), and the gateway never reflects a forced provider mode
+> into the gauge/feed (#2).
+
+**Goal:** Make `MxGateway:Alarms:Fallback:Mode=ForceSubtag` actually serve degraded subtag
+alarms AND have the gateway advertise `provider_mode=2` / degraded badge.
+
+**Evidence:** Live ForceSubtag run returned alarmmgr-sourced active alarms (May raise
+timestamps, `degraded=false`) and `provider_mode` stuck at 1, despite ForceSubtag binding
+(proven by invalid-value crash) and the deployed worker containing the ForcedMode routing
+(`3f5e5fc` ∈ `5976770`, worker dated 2026-06-14).
+
+---
+
+## Defect #2 (CONFIRMED code defect) — gateway never reflects forced mode
+
+**Root cause:** `GatewayAlarmMonitor.RunMonitorAsync` hard-baselines `_providerMode=Alarmmgr`
+and sets the gauge to 1, ignoring `_options.Fallback.Mode`. `_providerMode` only advances on a
+worker `OnAlarmProviderModeChanged` event, which is raised ONLY by `FailoverAlarmConsumer`
+(Auto mode). Forced-subtag builds `SubtagAlarmConsumer` directly → no event → gauge/feed stay
+Alarmmgr forever.
+
+### Task 2: Seed provider mode from configured forced mode (gateway, net10)
+**Classification:** small · **Parallelizable with:** none (precedes the diagnostic build)
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Server/Alarms/GatewayAlarmMonitor.cs` (`RunMonitorAsync`, ~lines 160-172; add a permanent observability log in `SubscribeAlarmsAsync` ~line 257)
+- Test: `src/ZB.MOM.WW.MxGateway.Tests/Alarms/GatewayAlarmMonitorProviderModeTests.cs`
+
+**Change:** in `RunMonitorAsync`, compute `initialMode = MapForcedMode(_options.Fallback.Mode)`
+mapped as `Subtag→Subtag`, `Alarmmgr→Alarmmgr`, `Unspecified→Alarmmgr` (Auto starts on the
+alarmmgr primary). Set `_providerMode/_providerDegraded(=Subtag)/_providerReason/_providerSince`
+and `_metrics.SetAlarmProviderMode(ModeToInt(initialMode))` — using the existing no-switch gauge
+seam so `provider_switches` does NOT increment. Add a log in `SubscribeAlarmsAsync`:
+`"Alarm subscribe forcedMode={ForcedMode} (configMode={ConfigMode}) watchList={Count}"`.
+
+**Tests (fake-worker, no MXAccess):** with `Fallback:Mode=ForceSubtag` assert (a) first
+`StreamAlarms` message is `ProviderStatus{Mode=Subtag,Degraded=true}`; (b) gauge==2; (c)
+`provider_switches`==0. Add `ForceAlarmManager`→gauge 1 and `Auto`→gauge 1 baseline cases.
+
+**Verify:** `dotnet build src/ZB.MOM.WW.MxGateway.Server`; `dotnet test src/ZB.MOM.WW.MxGateway.Tests --filter FullyQualifiedName~GatewayAlarmMonitorProviderMode`.
+
+---
+
+## Defect #1 (runtime bug — needs diagnosis) — ForceSubtag runs alarmmgr
+
+The HEAD source path (gateway `MapForcedMode` → `SubscribeAlarmsCommand.ForcedMode=Subtag` →
+IPC → worker `AlarmCommandHandler.BuildConsumer` → `SubtagAlarmConsumer`) is statically correct,
+yet the runtime ran alarmmgr. A runtime diagnostic must locate where `forcedMode` becomes
+`Unspecified`.
+
+### Task 1: Add worker BuildConsumer observability log (worker, net48 x86)
+**Classification:** small (net48 — no init-only props) · **Parallelizable with:** Task 2
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/AlarmCommandHandler.cs` (`BuildConsumer`, ~line 206)
+
+**Change:** log at entry of `BuildConsumer`:
+`"BuildConsumer forcedMode={ForcedMode} watchList={Count}"`. This is permanent observability.
+
+**Verify (windev only):** `dotnet build src/ZB.MOM.WW.MxGateway.Worker -p:Platform=x86`.
+
+### Task 3: Diagnostic run — capture the real forcedMode
+**Classification:** standard (ops/diagnostic on windev) · **Parallelizable with:** none
+**Steps:** rebuild worker (x86) + server from the branch, stand up the D3-style temp ForceSubtag
+instance (alt ports 5122/5132, isolated `.D3` worker name, WMI-detached, Http2, Development env
+for file logs), trigger the always-on monitor, and read the two new log lines:
+- Gateway `Alarm subscribe forcedMode=...` — what the gateway SENDS.
+- Worker `BuildConsumer forcedMode=...` — what the worker RECEIVES.
+
+Decision matrix:
+- Gateway logs `Subtag`, worker logs `Unspecified` → IPC/serialization drops the enum → fix the
+  send/translation path (likely a worker-proto vs gateway-proto `SubscribeAlarmsCommand` mismatch
+  in the named-pipe envelope).
+- Worker logs `Subtag` but alarmmgr data appears → bug in `BuildStandby`/`SubtagAlarmConsumer`/
+  `AlarmDispatcher` snapshot path.
+- Gateway logs `Unspecified` despite config ForceSubtag → gateway config/options read.
+
+### Task 4: Fix #1 per Task 3 diagnosis
+**Classification:** standard/high-risk (depends on where the defect is) · the exact change is
+determined by Task 3. Add a regression test at the identified layer (worker unit test for
+BuildConsumer→SubtagAlarmConsumer, or a contract/IPC round-trip test if the enum is dropped).
+
+---
+
+## Final: build, test, redeploy, re-validate
+- Build gateway (macOS) + worker (windev x86); run gateway + worker test suites.
+- Redeploy windev Server (and Worker if Task 4 changed it) per `project_deploy_mechanics`,
+  preserving appsettings.
+- Re-validate live with the temp ForceSubtag instance: active alarms `degraded=true` /
+  `source_provider=SUBTAG` with recent timestamps, `provider_mode 2`. Tear down temp instance;
+  production untouched.
+
+## Execution note
+Branch off `main`. #2 is the clean confirmed fix; #1 is diagnose-then-fix. Net48 worker
+constraints apply (no init-only props/positional records). Do NOT increment `provider_switches`
+on an initial forced-mode set.
+
+---
+
+## Resolution (2026-06-15)
+
+**#1 was NOT a bug — it was a grpcurl proto-mismatch artifact.** End-to-end instrumentation
+proved: the gateway sends `forcedMode=Subtag`, the worker's `BuildConsumer` builds the
+`SubtagAlarmConsumer`, and the worker `QueryActive` + gateway `ApplyReconcile`/`StreamAlarms`
+all carry `degraded=true` / `source_provider=SUBTAG`. The original "degraded=false" observation
+came from running grpcurl against the host checkout's proto (branch `feat/lazy-browse-children`),
+which predates the feature and lacks the `degraded`/`source_provider` fields — grpcurl silently
+dropped them. With the matching proto, every active alarm shows `degraded=true`. No code change.
+Tasks 1/3/4 (worker diagnostics + #1 fix) were dropped; the temporary diagnostics were reverted.
+
+**#2 was a real defect — fixed.** Gateway now seeds `_providerMode`/gauge/feed from the configured
+forced mode (`fix: gateway reflects configured forced provider mode`). Verified live:
+`provider_mode=2`, first `ProviderStatus` = `Mode=Subtag, degraded=true,
+reason="Forced subtag mode (configuration)"`. Auto mode unchanged → windev production (Auto)
+unaffected; no redeploy required. Gateway tests: 163 passed.

gateway.md

@@ -143,6 +143,67 @@ session if the worker faults. Gated by `MxGateway:Alarms:Enabled` — see
 `docs/DesignDecisions.md` for why this reverses the v1 single-subscriber rule
 for the alarm subsystem.
 
+### Alarm providers and failover
+
+The alarm feed has two providers, both implemented worker-side:
+
+- **Alarm manager (primary):** `WnWrapAlarmConsumer` polls
+  `wwAlarmConsumerClass.GetXmlCurrentAlarms2` on the worker STA. This is the
+  authoritative native source.
+- **Subtag monitoring (standby):** `SubtagAlarmConsumer` advises each alarm
+  attribute's subtags (`.active`, `.acked`, optionally `.priority`) via the
+  existing `AddItem`/`Advise` pipeline through `LmxSubtagAlarmSource` and
+  synthesizes alarm transitions with `SubtagAlarmStateMachine`. This is a
+  non-parity, lower-fidelity source — synthetic GUIDs, no native raise
+  timestamps, narrower fields.
+
+`FailoverAlarmConsumer` wraps both and owns the state machine:
+
+- **Auto-failover:** after `ConsecutiveFailureThreshold` (default 3)
+  consecutive wnwrap COM failures — `Subscribe` or `PollOnce` throws or
+  returns a failure HRESULT — it activates the standby. The standby is armed
+  (subscribed and adviseing) from the start so its state is warm at the moment
+  of switch.
+- **Auto-failback:** while degraded, every `FailbackProbeIntervalSeconds`
+  (default 30) it re-probes the still-subscribed primary. After
+  `FailbackStableProbes` (default 3) consecutive clean polls it switches back
+  to the alarm manager.
+- **On every switch:** the consumer snapshots the now-active provider and
+  emits `OnAlarmProviderModeChangedEvent` so the gateway can reconcile its
+  cache without a raise/clear storm.
+
+Synthesis is worker-side. This preserves the parity rule — the gateway
+forwards only events the worker emits and never synthesizes transitions
+itself. The synthesis rules are documented in
+`docs/AlarmClientDiscovery.md`.
+
+**Acknowledge in subtag mode:** the ack-by-name path writes the operator
+comment to the alarm attribute's ack-comment subtag. The write performs the
+ack. If the attribute has no writable ack-comment subtag configured, the RPC
+returns `FailedPrecondition`. In alarm-manager mode, `AlarmAckByName` is
+used as before.
+
+**Degraded state visibility:** every subtag-mode transition carries
+`degraded = true` and `source_provider = ALARM_PROVIDER_MODE_SUBTAG` on the
+`OnAlarmTransitionEvent` and `ActiveAlarmSnapshot` proto fields. The
+`AlarmFeedMessage` feed emits an `AlarmProviderStatus` message (the
+`provider_status` oneof case) on stream open and on every switch. The
+dashboard shows a Bootstrap badge: green ("Alarm Manager") when healthy, amber
+("Subtag monitoring (degraded)") on an unexpected failover, and cyan ("Subtag
+monitoring (forced)") when subtag mode is the configured `Fallback:Mode=ForceSubtag`
+— the latter distinguished by the well-known `AlarmProviderStatus.reason`
+(`AlarmProviderReasons.ForcedSubtag`) so an intentional configuration is not shown
+as a fault. Metrics: `mxgateway.alarms.provider_mode` gauge (1 = alarmmgr,
+2 = subtag) and `mxgateway.alarms.provider_switches` counter.
+
+Forced modes are available via `MxGateway:Alarms:Fallback:Mode`:
+`ForceAlarmManager` disables failover; `ForceSubtag` forces the standby
+on from startup; `Auto` (default) enables failover and failback. Watch-list
+discovery for the subtag provider uses Galaxy Repository SQL with config
+overrides. See `docs/GatewayConfiguration.md` for the full `Fallback` option
+block and `docs/AlarmClientDiscovery.md` for synthesis rules and fidelity
+limitations.
+
 Dashboard authentication is LDAP-backed (distinct from the API-key model on
 the gRPC API). `/login` accepts username and password in a form body, binds
 against `MxGateway:Ldap`, maps the user's LDAP groups to `Admin` or `Viewer`

glauth.md

@@ -1,28 +1,37 @@
 # GLAuth — LDAP authn reference for mxaccessgw
 
-GLAuth is a lightweight LDAP server installed on this dev box at
-`C:\publish\glauth\` and run as a Windows service via NSSM. It already
-backs the LmxOpcUa OPC UA server's UserName-token authn and the LmxOpcUa
-Admin UI's cookie login; this doc captures everything mxaccessgw needs
-to consume the same directory so a single set of dev credentials covers
-both stacks.
+> **UPDATED 2026-06-04 — mxaccessgw no longer uses a per-box GLAuth at `C:\publish\glauth`.
+> Dev/test LDAP is now the SHARED GLAuth on `10.100.0.35:3893` (`dc=zb,dc=local`);
+> the single source of truth is `scadaproj/infra/glauth/` (`config.toml` + `README`).
+> The localhost/NSSM/`glauth.cfg` procedures below are RETIRED, kept for reference/rollback.**
 
-The authoritative copy of LmxOpcUa's reference lives at
-`C:\publish\glauth\auth.md`. This doc is a redistilled view tailored to
-mxaccessgw — what users + groups are already provisioned, how to bind
-against them, and what's needed to add a gw-specific role.
+GLAuth is a lightweight LDAP server. It already backs all three sister apps (MxAccessGateway,
+OtOpcUa, ScadaBridge) through a **shared container** (`zb-shared-glauth`) running on the Linux
+docker host at **`10.100.0.35:3893`**. This doc captures everything mxaccessgw needs to consume
+that directory so a single set of dev credentials covers all stacks.
+
+~~GLAuth is installed on this dev box at `C:\publish\glauth\` and run as a Windows service via
+NSSM.~~ *(RETIRED — the per-box Windows service has been stopped and set to Manual startup;
+kept only as a rollback option. Do not edit or restart it for new work.)*
+
+The single source of truth for the shared GLAuth is
+**`~/Desktop/scadaproj/infra/glauth/config.toml`** (deploy/verify runbook:
+`scadaproj/infra/glauth/README.md`). This doc is a redistilled view tailored to mxaccessgw —
+what users + groups are provisioned, how to bind against them, and what's needed to add a
+gw-specific role.
 
 ## Connection details
 
 | Setting | Value |
 |---|---|
 | Protocol | LDAP (unencrypted) |
-| Host | `localhost` |
+| Host | **`10.100.0.35`** (shared docker host — ~~`localhost`~~ retired) |
 | Port | `3893` |
-| LDAPS | disabled in dev (set `[ldaps]` block to enable) |
-| Base DN | `dc=lmxopcua,dc=local` |
-| Bind DN format | `cn={username},dc=lmxopcua,dc=local` |
-| Group OU | `ou=<groupname>,ou=groups,dc=lmxopcua,dc=local` |
+| LDAPS | disabled in dev (`Transport=None`, `AllowInsecure=true`) |
+| Base DN | `dc=zb,dc=local` |
+| Bind DN format | `cn={username},dc=zb,dc=local` |
+| Service account DN | `cn=serviceaccount,dc=zb,dc=local` / `serviceaccount123` |
+| Group OU | `ou=<groupname>,ou=groups,dc=zb,dc=local` |
 | Failed-bind throttle | 3 fails → 10-minute IP lockout (per `[behaviors]`) |
 
 ## Pre-existing groups (LmxOpcUa role taxonomy)
@@ -33,11 +42,11 @@ LmxOpcUa write rights doesn't need a second account for the gw.
 
 | Group | GID | DN | LmxOpcUa meaning | Suggested mxgw mapping |
 |---|---|---|---|---|
-| ReadOnly | 5501 | `ou=ReadOnly,ou=groups,dc=lmxopcua,dc=local` | Browse + read OPC UA nodes | `Browse` + `Subscribe` (read paths only) |
-| WriteOperate | 5502 | `ou=WriteOperate,ou=groups,dc=lmxopcua,dc=local` | Write FreeAccess / Operate attrs | `Write` (plain) |
-| WriteTune | 5504 | `ou=WriteTune,ou=groups,dc=lmxopcua,dc=local` | Write Tune attrs | `WriteSecured` (Tune only) |
-| WriteConfigure | 5505 | `ou=WriteConfigure,ou=groups,dc=lmxopcua,dc=local` | Write Configure attrs | `WriteSecured` (Configure) |
-| AlarmAck | 5503 | `ou=AlarmAck,ou=groups,dc=lmxopcua,dc=local` | Acknowledge alarms | gw alarm-ack RPC, when added |
+| ReadOnly | 5501 | `ou=ReadOnly,ou=groups,dc=zb,dc=local` | Browse + read OPC UA nodes | `Browse` + `Subscribe` (read paths only) |
+| WriteOperate | 5502 | `ou=WriteOperate,ou=groups,dc=zb,dc=local` | Write FreeAccess / Operate attrs | `Write` (plain) |
+| WriteTune | 5504 | `ou=WriteTune,ou=groups,dc=zb,dc=local` | Write Tune attrs | `WriteSecured` (Tune only) |
+| WriteConfigure | 5505 | `ou=WriteConfigure,ou=groups,dc=zb,dc=local` | Write Configure attrs | `WriteSecured` (Configure) |
+| AlarmAck | 5503 | `ou=AlarmAck,ou=groups,dc=zb,dc=local` | Acknowledge alarms | gw alarm-ack RPC, when added |
 
 **A user can be in multiple groups** — `othergroups = [...]` in the
 config is a list. `admin` is the canonical example (in every role
@@ -59,20 +68,26 @@ For mxaccessgw dev, `admin` covers every gw-side capability test;
 `readonly` is the right "negative" case for proving Browse-OK /
 Write-denied.
 
-The gateway dashboard adds one role beyond this LmxOpcUa taxonomy:
-`GwAdmin`. `LdapOptions.RequiredGroup` defaults to `GwAdmin`, so the
-dashboard login and `DashboardLdapLiveTests` require `admin` to be a
-member of a `GwAdmin` group. `GwAdmin` is **not** in the baseline
-GLAuth config — it must be provisioned before dashboard authn or the
-LDAP live tests work. See [Provisioning the GwAdmin
-group](#provisioning-the-gwadmin-group) below.
+The gateway dashboard uses two gateway-specific groups beyond the LmxOpcUa taxonomy:
+`GwAdmin` (gid 5610 → role `Administrator`) and `GwReader` (gid 5611 → role `Viewer`).
+These are already provisioned in the shared `scadaproj/infra/glauth/config.toml`.
+The dashboard test users are **`multi-role`/`password`** (Administrator) and
+**`gw-viewer`/`password`** (Viewer). `LdapOptions.RequiredGroup` defaults to `GwAdmin`.
+See [Provisioning the GwAdmin group](#provisioning-the-gwadmin-group) below for the
+(now-retired) per-box procedure and for the shared-config equivalent.
+
+> **Dashboard role value (Task 1.7):** the LDAP `GwAdmin` group now maps to
+> the canonical dashboard role **`Administrator`** (was `Admin`); `GwReader`
+> maps to `Viewer`. This is a pure value rename via
+> `MxGateway:Dashboard:GroupToRole` — same operations are authorized. (This
+> dashboard role is distinct from the lowercase gRPC `admin` *API-key scope*.)
 
 ## Two bind patterns
 
 ### 1. Direct bind (simplest)
 
 ```
-DN:       cn=admin,dc=lmxopcua,dc=local
+DN:       cn=admin,dc=zb,dc=local
 Password: admin123
 ```
 
@@ -84,9 +99,9 @@ by `sAMAccountName`, not `cn`. Use this only for dev convenience.
 ### 2. Bind-then-search (production-grade)
 
 ```
-1. Bind as the service account (cn=serviceaccount,dc=lmxopcua,dc=local
+1. Bind as the service account (cn=serviceaccount,dc=zb,dc=local
    / serviceaccount123).
-2. Search under dc=lmxopcua,dc=local with filter
+2. Search under dc=zb,dc=local with filter
    (uid=<entered-username>) — or any attribute the deployment
    identifies users by. GLAuth populates uid + cn.
 3. Read the returned entry's DN + memberOf list (groups).
@@ -112,12 +127,12 @@ record:
 ```yaml
 ldap:
   enabled: true
-  server: localhost
+  server: 10.100.0.35     # shared GLAuth on docker host (was localhost)
   port: 3893
   useTls: false
   allowInsecureLdap: true       # dev only
-  searchBase: "dc=lmxopcua,dc=local"
-  serviceAccountDn: "cn=serviceaccount,dc=lmxopcua,dc=local"
+  searchBase: "dc=zb,dc=local"
+  serviceAccountDn: "cn=serviceaccount,dc=zb,dc=local"
   serviceAccountPassword: "serviceaccount123"
   userNameAttribute: "uid"      # GLAuth populates this; AD uses sAMAccountName
   displayNameAttribute: "cn"
@@ -131,19 +146,35 @@ ldap:
 ```
 
 `groupAttribute` returns full DNs like
-`ou=ReadOnly,ou=groups,dc=lmxopcua,dc=local` — the authenticator
+`ou=ReadOnly,ou=groups,dc=zb,dc=local` — the authenticator
 should strip the leading `ou=` (or `cn=` against AD) RDN value and
 look that up in `groupToRole`.
 
 ## Provisioning the GwAdmin group
 
+> **UPDATED 2026-06-04 — RETIRED per-box procedure.** `GwAdmin` (gid 5610) and `GwReader`
+> (gid 5611) are already present in the shared GLAuth. To add or modify users/groups,
+> edit **`~/Desktop/scadaproj/infra/glauth/config.toml`** on host `10.100.0.35` and run:
+>
+> ```bash
+> cd ~/Desktop/scadaproj/infra/glauth
+> docker compose up -d --force-recreate
+> ```
+>
+> The per-box `C:\publish\glauth\glauth.cfg` + NSSM procedure below is kept for
+> rollback reference only — do not use it for new provisioning.
+
 `GwAdmin` is the gateway-specific dashboard-admin role. It is the
 default `LdapOptions.RequiredGroup`, so the dashboard cookie login and
 `DashboardLdapLiveTests` (`MXGATEWAY_RUN_LIVE_LDAP_TESTS=1`) reject
-`admin` until a `GwAdmin` group exists and `admin` is a member.
-GLAuth's baseline config ships only the five LmxOpcUa role groups, so
-`GwAdmin` must be added to GLAuth rather than run from a separate LDAP
-server:
+logins unless the user is a member of `GwAdmin`.
+The `GwAdmin` (gid 5610) and `GwReader` (gid 5611) groups already exist in the shared
+config at `scadaproj/infra/glauth/config.toml`. Dashboard test users are
+`multi-role`/`password` (Administrator) and `gw-viewer`/`password` (Viewer).
+
+---
+
+**RETIRED — per-box provisioning (reference/rollback only):**
 
 1. Edit `C:\publish\glauth\glauth.cfg`
 2. Append the group:
@@ -172,7 +203,7 @@ server:
 4. `nssm restart GLAuth`
 
 After the restart, `admin`'s `memberOf` includes
-`ou=GwAdmin,ou=groups,dc=lmxopcua,dc=local`, which the authenticator
+`ou=GwAdmin,ou=groups,dc=zb,dc=local`, which the authenticator
 strips to `GwAdmin` and matches against `RequiredGroup`. The same
 pattern applies to any future permission that doesn't fit the existing
 five roles.
@@ -193,15 +224,16 @@ echo -n "yourpassword" | openssl dgst -sha256
 
 ## Quick verification
 
-From mxaccessgw's dev box, prove the directory is reachable:
+From mxaccessgw's dev box, prove the shared directory is reachable:
 
 ```powershell
 # Plain bind via PowerShell + System.DirectoryServices.Protocols
-$ldap = New-Object System.DirectoryServices.Protocols.LdapConnection("localhost:3893")
+# (shared GLAuth on 10.100.0.35 — was localhost, now the docker host)
+$ldap = New-Object System.DirectoryServices.Protocols.LdapConnection("10.100.0.35:3893")
 $ldap.AuthType = [System.DirectoryServices.Protocols.AuthType]::Basic
 $ldap.SessionOptions.ProtocolVersion = 3
 $ldap.SessionOptions.SecureSocketLayer = $false
-$cred = New-Object System.Net.NetworkCredential("cn=admin,dc=lmxopcua,dc=local","admin123")
+$cred = New-Object System.Net.NetworkCredential("cn=multi-role,dc=zb,dc=local","password")
 $ldap.Bind($cred)
 "Bind OK"
 ```
@@ -209,17 +241,32 @@ $ldap.Bind($cred)
 Or via `ldapsearch` if you have OpenLDAP CLI tools:
 
 ```bash
-ldapsearch -x -H ldap://localhost:3893 \
-  -D "cn=admin,dc=lmxopcua,dc=local" -w admin123 \
-  -b "dc=lmxopcua,dc=local" "(uid=admin)"
+ldapsearch -x -H ldap://10.100.0.35:3893 \
+  -D "cn=serviceaccount,dc=zb,dc=local" -w serviceaccount123 \
+  -b "dc=zb,dc=local" "(uid=multi-role)"
 ```
 
-The response should list `admin`'s entry with `memberOf` populated for
-all five role groups — plus `GwAdmin` once the gateway-specific group
-is provisioned.
+The response should list `multi-role`'s entry with `memberOf` including
+`ou=GwAdmin,ou=groups,dc=zb,dc=local`.
 
 ## Service management
 
+> **RETIRED — per-box NSSM service (reference/rollback only).** The shared GLAuth is
+> managed via `docker compose` on `10.100.0.35` (`scadaproj/infra/glauth/`). The
+> Windows NSSM `GLAuth` service on the dev box has been stopped and set to
+> `StartupType=Manual`; only restart it if you need to roll back to a local directory.
+>
+> **Active (shared) management:**
+> ```bash
+> ssh 10.100.0.35
+> cd ~/Desktop/scadaproj/infra/glauth
+> docker compose ps                      # check container status
+> docker compose up -d --force-recreate  # apply config.toml changes
+> docker compose logs -f                 # tail logs
+> ```
+
+**RETIRED — per-box NSSM commands (rollback reference):**
+
 ```powershell
 # Status / start / stop / restart
 nssm status  GLAuth
@@ -253,12 +300,12 @@ applies to mxaccessgw verbatim. Keys that change:
 
 | Field | GLAuth dev value | AD production value |
 |---|---|---|
-| `Server` | `localhost` | a domain controller FQDN, or the domain itself |
+| `Server` | `10.100.0.35` (shared docker host) | a domain controller FQDN, or the domain itself |
 | `Port` | `3893` | `636` (LDAPS) — AD increasingly rejects plain bind under LDAP-signing enforcement |
 | `UseTls` | `false` | `true` |
 | `AllowInsecureLdap` | `true` | `false` |
-| `SearchBase` | `dc=lmxopcua,dc=local` | `DC=corp,DC=example,DC=com` |
-| `ServiceAccountDn` | `cn=serviceaccount,dc=lmxopcua,dc=local` | `CN=MxGwSvc,OU=Service Accounts,DC=corp,...` |
+| `SearchBase` | `dc=zb,dc=local` | `DC=corp,DC=example,DC=com` |
+| `ServiceAccountDn` | `cn=serviceaccount,dc=zb,dc=local` | `CN=MxGwSvc,OU=Service Accounts,DC=corp,...` |
 | `UserNameAttribute` | `uid` | `sAMAccountName` (or `userPrincipalName`) |
 | `GroupAttribute` | `memberOf` (unchanged) | `memberOf` (unchanged) |
 
@@ -269,12 +316,12 @@ add a `tokenGroups` query as an enhancement.
 
 ## Security notes for production
 
-- **Plaintext passwords in `glauth.cfg` are dev-only.** The config is
-  unencrypted on disk; anyone with read access to `C:\publish\glauth\`
-  can SHA256-rainbow-table the entries. Treat the dev creds as
-  throwaway. Production LDAP is Active Directory.
+- **Plaintext passwords in `config.toml` are dev-only.** The shared config is in
+  `scadaproj/infra/glauth/config.toml` (unencrypted); restrict filesystem access on
+  `10.100.0.35` accordingly. Treat the dev creds as throwaway. Production LDAP is Active
+  Directory. *(The retired per-box `C:\publish\glauth\glauth.cfg` has the same caveat.)*
 - The 3-fail / 10-minute lockout is per source IP, not per user — a
   shared NAT can lock out a whole office. Tunable in `[behaviors]`.
 - LDAPS isn't enabled in dev; binding sends passwords cleartext on the
-  wire. Fine for `localhost`, never expose port 3893 off-box without
-  enabling TLS first.
+  wire. The shared GLAuth listens only on the LAN (`10.100.0.35`); never
+  expose port 3893 externally without enabling TLS first.

nuget.config

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <packageSources>
+    <clear />
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+    <add key="dohertj2-gitea" value="https://gitea.dohertylan.com/api/packages/dohertj2/nuget/index.json" />
+  </packageSources>
+  <!-- nuget.org serves everything; the Gitea feed serves only the ZB.MOM.WW.* shared libs.
+       Credentials are NOT committed: they are provided per-developer at the user level. -->
+  <packageSourceMapping>
+    <packageSource key="nuget.org">
+      <package pattern="*" />
+    </packageSource>
+    <packageSource key="dohertj2-gitea">
+      <package pattern="ZB.MOM.WW.Health" />
+      <package pattern="ZB.MOM.WW.Health.*" />
+      <package pattern="ZB.MOM.WW.Telemetry" />
+      <package pattern="ZB.MOM.WW.Telemetry.*" />
+      <package pattern="ZB.MOM.WW.Configuration" />
+      <package pattern="ZB.MOM.WW.Auth" />
+      <package pattern="ZB.MOM.WW.Auth.*" />
+      <package pattern="ZB.MOM.WW.Audit" />
+      <package pattern="ZB.MOM.WW.Theme" />
+    </packageSource>
+  </packageSourceMapping>
+</configuration>

scripts/tag-go-module.ps1

@@ -39,10 +39,14 @@ if ($Version -notmatch '^v\d+\.\d+\.\d+(-[A-Za-z0-9.-]+)?$') {
 $tag = "clients/go/$Version"
 Write-Host "Creating Go-module tag: $tag" -ForegroundColor Cyan
 
-# Verify we're on a clean checkout — refuse to tag with uncommitted changes.
-$status = (git status --porcelain) -join "`n"
-if ($status -and -not ($status -match '^\?\?')) {
-    throw "Working tree has tracked changes. Commit or stash before tagging."
+# Verify we're on a clean checkout — refuse to tag with uncommitted tracked
+# changes. Test each porcelain line individually: any entry that is not an
+# untracked file (`??`) is a tracked change, regardless of how the entries
+# happen to sort. Joining and anchoring `^\?\?` against the whole blob would
+# only inspect the first line and miss tracked changes behind an untracked one.
+$dirty = (git status --porcelain) | Where-Object { $_ -and ($_ -notmatch '^\?\?') }
+if ($dirty) {
+    throw "Working tree has tracked changes. Commit or stash before tagging.`n$($dirty -join "`n")"
 }
 
 # Verify the tag doesn't already exist.

src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto

@@ -315,6 +315,21 @@ message SubscribeBulkCommand {
   repeated string tag_addresses = 2;
 }
 
+// Provider selection / current provider for the alarm feed. The zero value
+// has two distinct meanings depending on the use site:
+//   - As SubscribeAlarmsCommand.forced_mode, UNSPECIFIED means auto: alarmmgr
+//     primary with subtag fallback.
+//   - As a provenance value (OnAlarmTransitionEvent.source_provider,
+//     ActiveAlarmSnapshot.source_provider, OnAlarmProviderModeChangedEvent.mode,
+//     AlarmProviderStatus.mode), the worker always emits ALARMMGR or SUBTAG and
+//     never UNSPECIFIED; clients should treat a UNSPECIFIED provenance value as
+//     "unknown / not yet determined".
+enum AlarmProviderMode {
+  ALARM_PROVIDER_MODE_UNSPECIFIED = 0;
+  ALARM_PROVIDER_MODE_ALARMMGR = 1;
+  ALARM_PROVIDER_MODE_SUBTAG = 2;
+}
+
 // Subscribe the worker's alarm consumer to an AVEVA alarm provider.
 // Subscription expression follows the canonical
 // `\\<machine>\Galaxy!<area>` format (literal "Galaxy" provider). The
@@ -323,6 +338,12 @@ message SubscribeBulkCommand {
 // SubscribeAlarms to reconfigure).
 message SubscribeAlarmsCommand {
   string subscription_expression = 1;
+  // UNSPECIFIED = auto-failover/failback. ALARMMGR/SUBTAG force one provider.
+  AlarmProviderMode forced_mode = 2;
+  // Subtag watch-list resolved by the gateway (GR SQL + config). Empty in pure
+  // alarmmgr mode; in subtag mode it bounds what the consumer can observe.
+  repeated AlarmSubtagTarget watch_list = 3;
+  AlarmFailoverConfig failover = 4;
 }
 
 // Tear down the worker's alarm consumer. No-op if no subscription is
@@ -330,6 +351,23 @@ message SubscribeAlarmsCommand {
 message UnsubscribeAlarmsCommand {
 }
 
+// One alarm attribute the subtag fallback consumer advises. Addresses are full
+// MXAccess item references the worker passes straight to AddItem.
+message AlarmSubtagTarget {
+  string alarm_full_reference = 1;     // e.g. "Galaxy!Area.Tank01.Level.HiHi"
+  string source_object_reference = 2;  // e.g. "Tank01"
+  string active_subtag = 3;            // item address of the in-alarm boolean
+  string acked_subtag = 4;             // item address of the acknowledged boolean
+  string ack_comment_subtag = 5;       // writable ack-comment attribute (ack write target)
+  string priority_subtag = 6;          // optional severity source; empty if absent
+}
+
+message AlarmFailoverConfig {
+  int32 consecutive_failure_threshold = 1;   // wnwrap COM failures before switching (>=1)
+  int32 failback_probe_interval_seconds = 2; // probe cadence while degraded (>=1)
+  int32 failback_stable_probes = 3;          // clean probes before switching back (>=1)
+}
+
 // Acknowledge a single alarm by its GUID. Operator identity fields are
 // recorded atomically with the ack transition in the alarm-history log.
 // The reply's hresult / native_status surfaces AVEVA's
@@ -684,6 +722,7 @@ message MxEvent {
     OperationCompleteEvent operation_complete = 22;
     OnBufferedDataChangeEvent on_buffered_data_change = 23;
     OnAlarmTransitionEvent on_alarm_transition = 24;
+    OnAlarmProviderModeChangedEvent on_alarm_provider_mode_changed = 25;
   }
 }
 
@@ -694,6 +733,7 @@ enum MxEventFamily {
   MX_EVENT_FAMILY_OPERATION_COMPLETE = 3;
   MX_EVENT_FAMILY_ON_BUFFERED_DATA_CHANGE = 4;
   MX_EVENT_FAMILY_ON_ALARM_TRANSITION = 5;
+  MX_EVENT_FAMILY_ON_ALARM_PROVIDER_MODE_CHANGED = 6;
 }
 
 message OnDataChangeEvent {
@@ -768,6 +808,20 @@ message OnAlarmTransitionEvent {
   // Limit/threshold value that triggered the transition for limit alarms.
   // Optional; populated for AnalogLimitAlarm-family transitions.
   MxValue limit_value = 13;
+
+  // True when this transition came from the subtag-monitoring fallback rather
+  // than the native alarmmgr provider — synthesized from data changes, reduced
+  // fidelity (synthetic GUID, no native raise time).
+  bool degraded = 14;
+  // Which provider produced this transition.
+  AlarmProviderMode source_provider = 15;
+}
+
+message OnAlarmProviderModeChangedEvent {
+  AlarmProviderMode mode = 1;
+  string reason = 2;
+  int32 hresult = 3;   // COM HRESULT that triggered failover; 0 on failback
+  google.protobuf.Timestamp at = 4;
 }
 
 enum AlarmTransitionKind {
@@ -800,6 +854,15 @@ message ActiveAlarmSnapshot {
   string operator_comment = 11;
   MxValue current_value = 12;
   MxValue limit_value = 13;
+  // True when this snapshot came from the subtag-monitoring fallback rather
+  // than the native alarmmgr provider — synthesized from data changes, reduced
+  // fidelity (synthetic GUID, no native raise time). Mirrors
+  // OnAlarmTransitionEvent.degraded.
+  bool degraded = 14;
+  // Which provider produced this snapshot. Mirrors
+  // OnAlarmTransitionEvent.source_provider; always ALARMMGR or SUBTAG on the
+  // wire (never UNSPECIFIED).
+  AlarmProviderMode source_provider = 15;
 }
 
 enum AlarmConditionState {
@@ -866,9 +929,19 @@ message AlarmFeedMessage {
     bool snapshot_complete = 2;
     // A live alarm state change (raise / acknowledge / clear).
     OnAlarmTransitionEvent transition = 3;
+    // Provider-mode status. Emitted once on stream open and again on every
+    // failover/failback so late joiners learn the current mode immediately.
+    AlarmProviderStatus provider_status = 4;
   }
 }
 
+message AlarmProviderStatus {
+  AlarmProviderMode mode = 1;
+  bool degraded = 2;            // true whenever mode == SUBTAG
+  string reason = 3;            // human-readable switch reason
+  google.protobuf.Timestamp since = 4;
+}
+
 message MxStatusProxy {
   // Mirrors the `success` member of the MXAccess MXSTATUS_PROXY struct
   // (a 16-bit signed value in the COM struct, widened to int32 on the

src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj

@@ -7,7 +7,7 @@
   <PropertyGroup>
     <IsPackable>true</IsPackable>
     <PackageId>ZB.MOM.WW.MxGateway.Contracts</PackageId>
-    <Version>0.1.0</Version>
+    <Version>0.1.1</Version>
     <Authors>Joseph Doherty</Authors>
     <Company>ZB MOM WW</Company>
     <Copyright>Copyright (c) ZB MOM WW. All rights reserved.</Copyright>

src/ZB.MOM.WW.MxGateway.IntegrationTests/DashboardLdapLiveTests.cs

@@ -1,8 +1,12 @@
 using System.Security.Claims;
+using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.Logging.Abstractions;
 using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Auth.Abstractions.Ldap;
+using ZB.MOM.WW.Auth.Ldap;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
 using ZB.MOM.WW.MxGateway.Server.Dashboard;
+using LibraryLdapOptions = ZB.MOM.WW.Auth.Abstractions.Ldap.LdapOptions;
 
 namespace ZB.MOM.WW.MxGateway.IntegrationTests;
 
@@ -28,12 +32,11 @@ public sealed class DashboardLdapLiveTests
             claim.Type == DashboardAuthenticationDefaults.LdapGroupClaimType
             && claim.Value.Contains("GwAdmin", StringComparison.OrdinalIgnoreCase));
 
-        // IntegrationTests-023: DashboardAuthenticator.CreatePrincipal emits a
-        // ClaimTypes.Role claim derived from MapGroupsToRoles. The seeded
-        // GroupToRole map (GwAdmin -> Admin) means the admin principal must
-        // carry Role=Admin alongside the raw LDAP-group claim. A regression in
-        // MapGroupsToRoles (returning an empty list, missing the RDN fallback)
-        // would silently pass without this assertion.
+        // IntegrationTests-023: DashboardAuthenticator builds the principal with a
+        // ClaimTypes.Role claim resolved from the LDAP groups via the
+        // DashboardGroupRoleMapper. The seeded GroupToRole map (GwAdmin -> Admin)
+        // means the admin principal must carry Role=Admin alongside the raw LDAP-group
+        // claim. A regression in the group→role mapping would fail this assertion.
         Assert.Contains(result.Principal.Claims, claim =>
             claim.Type == ClaimTypes.Role
             && claim.Value == DashboardRoles.Admin);
@@ -59,7 +62,7 @@ public sealed class DashboardLdapLiveTests
     [LiveLdapFact]
     public async Task AuthenticateAsync_AdminWithWrongPassword_FailsWithoutLeakingPassword()
     {
-        // Exercises the LdapException branch: the user exists and the service
+        // Exercises the user-bind-failure branch: the user exists and the service
         // account search succeeds, but the candidate bind is rejected.
         const string wrongPassword = "definitely-not-the-admin-password";
         DashboardAuthenticator authenticator = CreateAuthenticator();
@@ -78,8 +81,8 @@ public sealed class DashboardLdapLiveTests
     [LiveLdapFact]
     public async Task AuthenticateAsync_UnknownUsername_Fails()
     {
-        // Exercises the `candidate is null` branch: the service-account search
-        // returns no entry, so no candidate bind is attempted.
+        // Exercises the user-not-found branch: the service-account search returns no
+        // entry, so no candidate bind is attempted.
         DashboardAuthenticator authenticator = CreateAuthenticator();
 
         DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
@@ -96,18 +99,13 @@ public sealed class DashboardLdapLiveTests
     public async Task AuthenticateAsync_ServerUnreachable_FailsWithoutThrowing()
     {
         // Exercises the connect-failure path: a closed loopback port produces a
-        // connection error that DashboardAuthenticator must absorb into a Fail
+        // connection error that the shared LdapAuthService must absorb into a Fail
         // result rather than propagating an exception to the dashboard.
-        DashboardAuthenticator authenticator = new(
-            Options.Create(new GatewayOptions
-            {
-                Ldap = new LdapOptions
-                {
-                    // 1 is a reserved port number that no LDAP server listens on.
-                    Port = 1,
-                },
-            }),
-            NullLogger<DashboardAuthenticator>.Instance);
+        DashboardAuthenticator authenticator = CreateAuthenticator(LibraryOptions() with
+        {
+            // 1 is a reserved port number that no LDAP server listens on.
+            Port = 1,
+        });
 
         DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
             "admin",
@@ -118,19 +116,57 @@ public sealed class DashboardLdapLiveTests
         Assert.Null(result.Principal);
     }
 
-    private static DashboardAuthenticator CreateAuthenticator()
+    private static DashboardAuthenticator CreateAuthenticator() => CreateAuthenticator(LibraryOptions());
+
+    private static DashboardAuthenticator CreateAuthenticator(LibraryLdapOptions ldapOptions)
     {
-        return new DashboardAuthenticator(
-            Options.Create(new GatewayOptions
+        GatewayOptions gatewayOptions = new()
+        {
+            Dashboard = new DashboardOptions
             {
-                Dashboard = new DashboardOptions
+                GroupToRole = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
                 {
-                    GroupToRole = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
-                    {
-                        ["GwAdmin"] = DashboardRoles.Admin,
-                    },
+                    ["GwAdmin"] = DashboardRoles.Admin,
                 },
-            }),
+            },
+        };
+
+        return new DashboardAuthenticator(
+            new LdapAuthService(ldapOptions),
+            new DashboardGroupRoleMapper(Options.Create(gatewayOptions)),
             NullLogger<DashboardAuthenticator>.Instance);
     }
+
+    /// <summary>
+    /// Builds the shared library <see cref="LibraryLdapOptions"/> by binding the real
+    /// <c>MxGateway:Ldap</c> configuration section the same way production does in
+    /// <c>AddZbLdapAuth(configuration, "MxGateway:Ldap")</c>, rather than hand-copying the
+    /// gateway shadow <c>LdapOptions</c> defaults field by field (IntegrationTests-028).
+    /// Binding the section directly onto the shared type means the live tests exercise the
+    /// exact option-binding path production uses, pick up every shared field (including
+    /// <see cref="LibraryLdapOptions.ConnectionTimeoutMs"/>, which governs the
+    /// unreachable-server test's timing) at whatever value the operator configured, and
+    /// cannot silently drop a field added to the shared type. The gateway's
+    /// <c>appsettings.json</c> seeds the dev directory connection (localhost:3893,
+    /// plaintext, AllowInsecure).
+    /// </summary>
+    private static LibraryLdapOptions LibraryOptions()
+    {
+        string repositoryRoot = IntegrationTestEnvironment.ResolveRepositoryRoot(AppContext.BaseDirectory);
+        string appSettingsPath = Path.Combine(
+            repositoryRoot,
+            "src",
+            "ZB.MOM.WW.MxGateway.Server",
+            "appsettings.json");
+
+        IConfiguration configuration = new ConfigurationBuilder()
+            .AddJsonFile(appSettingsPath, optional: false)
+            .Build();
+
+        // Same section production binds in AddZbLdapAuth(configuration, "MxGateway:Ldap").
+        // Get<T> returns null only when the section is absent; appsettings.json always
+        // carries it, so fall back to shared defaults defensively rather than throw.
+        return configuration.GetSection("MxGateway:Ldap").Get<LibraryLdapOptions>()
+            ?? new LibraryLdapOptions();
+    }
 }

src/ZB.MOM.WW.MxGateway.IntegrationTests/TestSupport/EmptyAlarmWatchListResolver.cs

@@ -0,0 +1,35 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Server.Alarms;
+using ZB.MOM.WW.MxGateway.Server.Configuration;
+
+namespace ZB.MOM.WW.MxGateway.IntegrationTests.TestSupport;
+
+/// <summary>
+/// No-op <see cref="IAlarmWatchListResolver"/> for integration tests that
+/// construct a <see cref="GatewayAlarmMonitor"/> only to satisfy the
+/// <see cref="ZB.MOM.WW.MxGateway.Server.Grpc.MxAccessGatewayService"/>
+/// constructor. The live MXAccess smoke tests never exercise the alarm
+/// monitor, so the resolver always yields an empty watch-list rather than
+/// touching the Galaxy Repository the production
+/// <see cref="AlarmWatchListResolver"/> requires. Singleton because the type
+/// holds no state — every consumer can share <see cref="Instance"/>.
+/// </summary>
+public sealed class EmptyAlarmWatchListResolver : IAlarmWatchListResolver
+{
+    /// <summary>Shared no-op instance.</summary>
+    public static readonly EmptyAlarmWatchListResolver Instance = new();
+
+    private static readonly IReadOnlyList<AlarmSubtagTarget> Empty = [];
+
+    private EmptyAlarmWatchListResolver()
+    {
+    }
+
+    /// <inheritdoc />
+    public Task<IReadOnlyList<AlarmSubtagTarget>> ResolveAsync(
+        AlarmsOptions options,
+        CancellationToken cancellationToken = default)
+    {
+        return Task.FromResult(Empty);
+    }
+}

src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs

@@ -1097,6 +1097,8 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
                 _loggerFactory.CreateLogger<MxAccessGatewayService>(),
                 new ZB.MOM.WW.MxGateway.Server.Alarms.GatewayAlarmMonitor(
                     sessionManager,
+                    EmptyAlarmWatchListResolver.Instance,
+                    _metrics,
                     options,
                     _loggerFactory.CreateLogger<ZB.MOM.WW.MxGateway.Server.Alarms.GatewayAlarmMonitor>()));
         }

src/ZB.MOM.WW.MxGateway.IntegrationTests/ZB.MOM.WW.MxGateway.IntegrationTests.csproj

@@ -12,6 +12,22 @@
     <PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
   </ItemGroup>
 
+  <!--
+    DashboardLdapLiveTests directly references the shared LDAP provider's public
+    types (LdapAuthService / LdapOptions), so declare direct dependencies rather
+    than rely on the transitive flow through the Server ProjectReference
+    (IntegrationTests-027). Versions match the Server's pinned 0.1.2. The
+    configuration packages back the production-fidelity MxGateway:Ldap binding the
+    live-test fixture uses in place of the old field-by-field hand-copy
+    (IntegrationTests-028).
+  -->
+  <ItemGroup>
+    <PackageReference Include="ZB.MOM.WW.Auth.Abstractions" Version="0.1.2" />
+    <PackageReference Include="ZB.MOM.WW.Auth.Ldap" Version="0.1.2" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.7" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.7" />
+  </ItemGroup>
+
   <ItemGroup>
     <Using Include="Xunit" />
   </ItemGroup>

src/ZB.MOM.WW.MxGateway.Server/Alarms/AlarmProviderReasons.cs

@@ -0,0 +1,18 @@
+namespace ZB.MOM.WW.MxGateway.Server.Alarms;
+
+/// <summary>
+///     Well-known <c>reason</c> strings carried on the alarm feed's
+///     <c>AlarmProviderStatus</c> message. Shared between the producer
+///     (<see cref="GatewayAlarmMonitor" />) and consumers (e.g. the dashboard
+///     provider badge) so the two cannot drift on a magic string.
+/// </summary>
+public static class AlarmProviderReasons
+{
+    /// <summary>
+    ///     Reason set when the monitor starts in subtag mode because
+    ///     <c>MxGateway:Alarms:Fallback:Mode</c> is <c>ForceSubtag</c> — a
+    ///     deliberate configuration, not a runtime failover. Lets the dashboard
+    ///     distinguish a forced subtag mode from an unexpected degraded failover.
+    /// </summary>
+    public const string ForcedSubtag = "Forced subtag mode (configuration)";
+}

src/ZB.MOM.WW.MxGateway.Server/Alarms/AlarmWatchListResolver.cs

@@ -0,0 +1,180 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Server.Configuration;
+using ZB.MOM.WW.MxGateway.Server.Galaxy;
+
+namespace ZB.MOM.WW.MxGateway.Server.Alarms;
+
+/// <summary>
+///     Default <see cref="IAlarmWatchListResolver"/>. Merges Galaxy Repository
+///     alarm-attribute discovery with the configured include/exclude overrides
+///     and composes the per-attribute subtag item addresses from the configured
+///     subtag names.
+/// </summary>
+// NOTE: The exact subtag names and the canonical AlarmFullReference shape
+// ("Galaxy!{area}.{reference}") are validated against a live Galaxy in the
+// Task 17 live smoke test. The config Subtags block exists precisely so these
+// names are not hard-coded here. The {area} is the alarm object's REAL Galaxy
+// area discovered via gobject.area_gobject_id (the alarm group the native
+// alarmmgr emits), giving exact reference parity with wnwrap. The configured
+// Discovery.Area/DefaultArea is only the fallback for explicit IncludeAttributes
+// entries, which carry no discovered area.
+public sealed class AlarmWatchListResolver : IAlarmWatchListResolver
+{
+    private const string ProviderLiteral = "Galaxy";
+    private const string DefaultActiveSubtag = "InAlarm";
+    private const string DefaultAckedSubtag = "Acked";
+
+    private readonly IGalaxyRepository _repository;
+    private readonly ILogger<AlarmWatchListResolver> _logger;
+
+    /// <summary>Initializes the watch-list resolver.</summary>
+    /// <param name="repository">Galaxy Repository used for alarm-attribute discovery.</param>
+    /// <param name="logger">Diagnostic logger.</param>
+    public AlarmWatchListResolver(
+        IGalaxyRepository repository,
+        ILogger<AlarmWatchListResolver> logger)
+    {
+        _repository = repository ?? throw new ArgumentNullException(nameof(repository));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<AlarmSubtagTarget>> ResolveAsync(
+        AlarmsOptions options,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        AlarmDiscoveryOptions discovery = options.Fallback.Discovery;
+
+        // Config fallback area used only for explicit IncludeAttributes entries (which
+        // carry no discovered area): discovery area, else the default area (may be empty).
+        string configFallbackArea = string.IsNullOrEmpty(discovery.Area) ? options.DefaultArea : discovery.Area;
+
+        // 1. Build the ordered, de-duplicated attribute reference set.
+        //    Each entry carries the reference, the source-object reference, and the
+        //    per-entry area used to compose the canonical reference. GR rows contribute
+        //    the object's real Galaxy area; config includes contribute the config
+        //    fallback area (Discovery.Area else DefaultArea).
+        List<(string Reference, string SourceObject, string Area)> ordered = [];
+        HashSet<string> seen = new(StringComparer.OrdinalIgnoreCase);
+
+        if (discovery.UseGalaxyRepository)
+        {
+            List<GalaxyAlarmAttributeRow> rows;
+            try
+            {
+                rows = await _repository.GetAlarmAttributesAsync(cancellationToken).ConfigureAwait(false);
+            }
+            catch (Exception ex) when (ex is not OperationCanceledException)
+            {
+                // Discovery being unavailable must not crash the resolver: log and
+                // continue with an empty discovery set. The caller decides what to
+                // do with the (possibly config-only) result. Cancellation is the one
+                // exception — an OperationCanceledException propagates per the
+                // IAlarmWatchListResolver contract so the caller unwinds promptly.
+                _logger.LogWarning(
+                    ex,
+                    "Galaxy Repository alarm-attribute discovery failed; continuing with configuration-only watch-list.");
+                rows = [];
+            }
+
+            foreach (GalaxyAlarmAttributeRow row in rows)
+            {
+                if (string.IsNullOrEmpty(row.FullTagReference) || !seen.Add(row.FullTagReference))
+                {
+                    continue;
+                }
+
+                ordered.Add((row.FullTagReference, row.SourceObjectReference, row.Area));
+            }
+        }
+
+        foreach (string include in discovery.IncludeAttributes)
+        {
+            if (string.IsNullOrEmpty(include) || !seen.Add(include))
+            {
+                continue;
+            }
+
+            ordered.Add((include, DeriveSourceObject(include), configFallbackArea));
+        }
+
+        // Remove excluded references (case-insensitive), but only when GR discovery
+        // is active. ExcludeAttributes is documented as "Ignored when
+        // UseGalaxyRepository is false" (AlarmDiscoveryOptions.ExcludeAttributes).
+        // Whitespace-only entries are skipped, consistent with the include guard above.
+        if (discovery.UseGalaxyRepository)
+        {
+            HashSet<string> excluded = new(
+                discovery.ExcludeAttributes.Where(e => !string.IsNullOrWhiteSpace(e)),
+                StringComparer.OrdinalIgnoreCase);
+            if (excluded.Count > 0)
+            {
+                ordered.RemoveAll(e => excluded.Contains(e.Reference));
+            }
+        }
+
+        // 2. Resolve subtag names with safe fallbacks.
+        string active = string.IsNullOrEmpty(options.Fallback.Subtags.Active)
+            ? DefaultActiveSubtag
+            : options.Fallback.Subtags.Active;
+        string acked = string.IsNullOrEmpty(options.Fallback.Subtags.Acked)
+            ? DefaultAckedSubtag
+            : options.Fallback.Subtags.Acked;
+        string priority = options.Fallback.Subtags.Priority;
+        string ackComment = options.Fallback.Subtags.AckComment;
+
+        // 3. Compose one target per reference, using the PER-ENTRY area: the GR row's
+        //    real Galaxy area (matching the alarmmgr group), or the config fallback for
+        //    explicit includes.
+        List<AlarmSubtagTarget> targets = new(ordered.Count);
+        foreach ((string reference, string sourceObject, string area) in ordered)
+        {
+            targets.Add(new AlarmSubtagTarget
+            {
+                AlarmFullReference = ComposeFullReference(area, reference),
+                SourceObjectReference = sourceObject,
+                ActiveSubtag = $"{reference}.{active}",
+                AckedSubtag = $"{reference}.{acked}",
+                PrioritySubtag = string.IsNullOrEmpty(priority) ? string.Empty : $"{reference}.{priority}",
+                AckCommentSubtag = string.IsNullOrEmpty(ackComment) ? string.Empty : $"{reference}.{ackComment}",
+            });
+        }
+
+        // 4. Report the resolved count; warn when subtag mode was expected to cover
+        //    something (GR enabled, or explicit includes were configured) but resolved
+        //    to nothing. Only emit the Debug line when there is at least one target,
+        //    to avoid a confusing "0 target(s)" noise line.
+        if (targets.Count == 0 && (discovery.UseGalaxyRepository || discovery.IncludeAttributes.Length > 0))
+        {
+            _logger.LogWarning(
+                "Alarm subtag watch-list resolved to zero targets; subtag-polling fallback will cover no alarms.");
+        }
+        else if (targets.Count > 0)
+        {
+            _logger.LogDebug("Resolved alarm subtag watch-list with {TargetCount} target(s).", targets.Count);
+        }
+
+        return targets;
+    }
+
+    /// <summary>
+    ///     Derives the source-object reference for a configuration entry: the
+    ///     substring before the first '.', or the whole string when there is no dot.
+    /// </summary>
+    private static string DeriveSourceObject(string reference)
+    {
+        int dot = reference.IndexOf('.', StringComparison.Ordinal);
+        return dot < 0 ? reference : reference[..dot];
+    }
+
+    /// <summary>
+    ///     Composes the canonical alarm full reference: <c>Galaxy!{area}.{reference}</c>
+    ///     when an area is set, otherwise <c>Galaxy!{reference}</c>.
+    /// </summary>
+    private static string ComposeFullReference(string area, string reference) =>
+        string.IsNullOrEmpty(area)
+            ? $"{ProviderLiteral}!{reference}"
+            : $"{ProviderLiteral}!{area}.{reference}";
+}

src/ZB.MOM.WW.MxGateway.Server/Alarms/AlarmsServiceCollectionExtensions.cs

@@ -13,6 +13,7 @@ public static class AlarmsServiceCollectionExtensions
     /// <returns>The service collection for chaining.</returns>
     public static IServiceCollection AddGatewayAlarms(this IServiceCollection services)
     {
+        services.AddSingleton<IAlarmWatchListResolver, AlarmWatchListResolver>();
         services.AddSingleton<GatewayAlarmMonitor>();
         services.AddSingleton<IGatewayAlarmService>(provider => provider.GetRequiredService<GatewayAlarmMonitor>());
         services.AddHostedService(provider => provider.GetRequiredService<GatewayAlarmMonitor>());

src/ZB.MOM.WW.MxGateway.Server/Alarms/GatewayAlarmMonitor.cs

@@ -1,7 +1,9 @@
 using System.Threading.Channels;
+using Google.Protobuf.WellKnownTypes;
 using Microsoft.Extensions.Options;
 using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
+using ZB.MOM.WW.MxGateway.Server.Metrics;
 using ZB.MOM.WW.MxGateway.Server.Sessions;
 
 namespace ZB.MOM.WW.MxGateway.Server.Alarms;
@@ -23,6 +25,8 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic
     private static readonly TimeSpan StartupGrace = TimeSpan.FromSeconds(2);
 
     private readonly ISessionManager _sessionManager;
+    private readonly IAlarmWatchListResolver _watchListResolver;
+    private readonly GatewayMetrics _metrics;
     private readonly AlarmsOptions _options;
     private readonly ILogger<GatewayAlarmMonitor> _logger;
 
@@ -30,20 +34,34 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic
     private readonly Dictionary<string, ActiveAlarmSnapshot> _alarms = new(StringComparer.Ordinal);
     private readonly List<Subscriber> _subscribers = [];
 
+    // Current provider status (mode + degraded + reason + since), guarded by _sync.
+    // Initialized to the alarm-manager, not-degraded baseline so a late joiner sees
+    // a sensible status even before any OnAlarmProviderModeChanged event arrives.
+    private AlarmProviderMode _providerMode = AlarmProviderMode.Alarmmgr;
+    private bool _providerDegraded;
+    private string _providerReason = string.Empty;
+    private DateTimeOffset _providerSince = DateTimeOffset.UtcNow;
+
     private volatile GatewayAlarmMonitorState _state = GatewayAlarmMonitorState.Disabled;
     private volatile string? _lastError;
     private GatewaySession? _session;
 
     /// <summary>Initializes the gateway alarm monitor.</summary>
     /// <param name="sessionManager">Gateway session manager.</param>
+    /// <param name="watchListResolver">Resolver for the subtag-fallback watch-list.</param>
+    /// <param name="metrics">Gateway metrics sink.</param>
     /// <param name="options">Gateway options carrying the alarm configuration.</param>
     /// <param name="logger">Diagnostic logger.</param>
     public GatewayAlarmMonitor(
         ISessionManager sessionManager,
+        IAlarmWatchListResolver watchListResolver,
+        GatewayMetrics metrics,
         IOptions<GatewayOptions> options,
         ILogger<GatewayAlarmMonitor> logger)
     {
         _sessionManager = sessionManager ?? throw new ArgumentNullException(nameof(sessionManager));
+        _watchListResolver = watchListResolver ?? throw new ArgumentNullException(nameof(watchListResolver));
+        _metrics = metrics ?? throw new ArgumentNullException(nameof(metrics));
         _options = (options ?? throw new ArgumentNullException(nameof(options))).Value.Alarms;
         _logger = logger ?? throw new ArgumentNullException(nameof(logger));
     }
@@ -139,6 +157,49 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic
     private async Task RunMonitorAsync(string subscription, CancellationToken stoppingToken)
     {
         _state = GatewayAlarmMonitorState.Starting;
+
+        // Derive the lifecycle baseline from the configured forced mode so a
+        // ForceSubtag / ForceAlarmManager start advertises the correct mode even
+        // though no OnAlarmProviderModeChanged event is raised in those modes
+        // (only Auto/failover produces that event). ForceSubtag starts degraded.
+        AlarmProviderMode initialMode;
+        bool initialDegraded;
+        string initialReason;
+        switch (MapForcedMode(_options.Fallback.Mode))
+        {
+            case AlarmProviderMode.Subtag:
+                initialMode = AlarmProviderMode.Subtag;
+                initialDegraded = true;
+                initialReason = AlarmProviderReasons.ForcedSubtag;
+                break;
+            case AlarmProviderMode.Alarmmgr:
+                initialMode = AlarmProviderMode.Alarmmgr;
+                initialDegraded = false;
+                initialReason = string.Empty;
+                break;
+            default:
+                // Unspecified (Auto): the failover consumer starts on the
+                // alarm-manager primary and only degrades to subtag on failure.
+                initialMode = AlarmProviderMode.Alarmmgr;
+                initialDegraded = false;
+                initialReason = string.Empty;
+                break;
+        }
+
+        lock (_sync)
+        {
+            // Re-baseline the provider status for this lifecycle so a restarted
+            // monitor advertises the configured mode until told otherwise.
+            _providerMode = initialMode;
+            _providerDegraded = initialDegraded;
+            _providerReason = initialReason;
+            _providerSince = DateTimeOffset.UtcNow;
+        }
+
+        // Align the observable gauge with the lifecycle baseline without recording
+        // a switch — the gauge was 0 (unknown) from construction until now.
+        _metrics.SetAlarmProviderMode(ModeToInt(initialMode));
+
         GatewaySession session = await _sessionManager.OpenSessionAsync(
                 new SessionOpenRequest(BackendName, MonitorClientName, Guid.NewGuid().ToString("N"), CommandTimeout: null),
                 MonitorClientName,
@@ -173,6 +234,15 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic
                     {
                         ApplyTransition(mxEvent.OnAlarmTransition);
                     }
+                    else if (mxEvent is { BodyCase: MxEvent.BodyOneofCase.OnAlarmProviderModeChanged }
+                        && mxEvent.OnAlarmProviderModeChanged is not null)
+                    {
+                        await ApplyProviderModeChangeAsync(
+                                session.SessionId,
+                                mxEvent.OnAlarmProviderModeChanged,
+                                linked.Token)
+                            .ConfigureAwait(false);
+                    }
                 }
             }
             finally
@@ -209,6 +279,33 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic
 
     private async Task SubscribeAlarmsAsync(string sessionId, string subscription, CancellationToken cancellationToken)
     {
+        IReadOnlyList<AlarmSubtagTarget> watchList = await _watchListResolver
+            .ResolveAsync(_options, cancellationToken)
+            .ConfigureAwait(false);
+
+        AlarmProviderMode forcedMode = MapForcedMode(_options.Fallback.Mode);
+
+        _logger.LogInformation(
+            "Alarm subscribe: forcedMode={ForcedMode} configMode={ConfigMode} watchList={WatchListCount}.",
+            forcedMode, _options.Fallback.Mode, watchList.Count);
+
+        // When the forced mode is Unspecified (the "Auto" case) and the resolved
+        // watch-list is empty — the common alarmmgr-only deployment — the command
+        // is identical-in-effect to the historical SubscribeAlarms (wnwrap only):
+        // the worker builds the wnwrap consumer and no subtag watch-list.
+        SubscribeAlarmsCommand command = new()
+        {
+            SubscriptionExpression = subscription,
+            ForcedMode = forcedMode,
+            Failover = new AlarmFailoverConfig
+            {
+                ConsecutiveFailureThreshold = _options.Fallback.ConsecutiveFailureThreshold,
+                FailbackProbeIntervalSeconds = _options.Fallback.FailbackProbeIntervalSeconds,
+                FailbackStableProbes = _options.Fallback.FailbackStableProbes,
+            },
+        };
+        command.WatchList.AddRange(watchList);
+
         WorkerCommandReply reply = await _sessionManager.InvokeAsync(
                 sessionId,
                 new WorkerCommand
@@ -216,7 +313,7 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic
                     Command = new MxCommand
                     {
                         Kind = MxCommandKind.SubscribeAlarms,
-                        SubscribeAlarms = new SubscribeAlarmsCommand { SubscriptionExpression = subscription },
+                        SubscribeAlarms = command,
                     },
                 },
                 cancellationToken)
@@ -310,6 +407,104 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic
         }
     }
 
+    // Handles the worker's provider-mode-change event: updates the stored provider
+    // status, broadcasts it to every subscriber (provider status is global, not
+    // alarm-scoped), records the switch metric, and forces a cache reconcile so the
+    // active-alarm set reflects whatever the new mode reports.
+    private async Task ApplyProviderModeChangeAsync(
+        string sessionId,
+        OnAlarmProviderModeChangedEvent change,
+        CancellationToken cancellationToken)
+    {
+        AlarmProviderMode toMode = change.Mode;
+        string reason = change.Reason ?? string.Empty;
+
+        AlarmProviderStatus status;
+        int fromModeInt;
+        lock (_sync)
+        {
+            fromModeInt = ModeToInt(_providerMode);
+            _providerMode = toMode;
+            _providerDegraded = toMode == AlarmProviderMode.Subtag;
+            _providerReason = reason;
+            _providerSince = DateTimeOffset.UtcNow;
+            status = BuildProviderStatus();
+            BroadcastToAll(new AlarmFeedMessage { ProviderStatus = status });
+        }
+
+        AlarmProviderSwitchReason switchReason = toMode switch
+        {
+            AlarmProviderMode.Subtag => AlarmProviderSwitchReason.Failover,
+            AlarmProviderMode.Alarmmgr => AlarmProviderSwitchReason.Failback,
+            _ => AlarmProviderSwitchReason.Unknown,
+        };
+        _metrics.AlarmProviderSwitched(fromModeInt, ModeToInt(toMode), switchReason);
+
+        _logger.LogInformation(
+            "Alarm provider mode changed to {Mode} (degraded={Degraded}): {Reason}",
+            toMode,
+            status.Degraded,
+            reason);
+
+        try
+        {
+            // Intentionally awaited OUTSIDE _sync: ReconcileAsync acquires _sync itself,
+            // so holding it across the await here would deadlock. Subscribers therefore
+            // see the ProviderStatus push (above) slightly before the cache is re-seeded
+            // by the reconcile — an accepted brief inconsistency.
+            await ReconcileAsync(sessionId, cancellationToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException)
+        {
+            throw;
+        }
+        catch (Exception exception)
+        {
+            _logger.LogDebug(
+                exception,
+                "Reconcile after alarm provider mode change failed; keeping the current cache.");
+        }
+    }
+
+    // Caller holds _sync. Builds an AlarmProviderStatus snapshot of the current state.
+    private AlarmProviderStatus BuildProviderStatus()
+    {
+        return new AlarmProviderStatus
+        {
+            Mode = _providerMode,
+            Degraded = _providerDegraded,
+            Reason = _providerReason,
+            Since = Timestamp.FromDateTimeOffset(_providerSince),
+        };
+    }
+
+    // Maps the configured fallback mode string to the forced provider mode the
+    // worker honours. Case-insensitive; anything other than the two force values
+    // (including the default "Auto") yields Unspecified ("let the worker decide").
+    private static AlarmProviderMode MapForcedMode(string? mode)
+    {
+        if (string.Equals(mode, "ForceAlarmManager", StringComparison.OrdinalIgnoreCase))
+        {
+            return AlarmProviderMode.Alarmmgr;
+        }
+
+        if (string.Equals(mode, "ForceSubtag", StringComparison.OrdinalIgnoreCase))
+        {
+            return AlarmProviderMode.Subtag;
+        }
+
+        return AlarmProviderMode.Unspecified;
+    }
+
+    // Maps the provider-mode enum to the integer the metric expects
+    // (alarmmgr=1, subtag=2, unknown/unspecified=0).
+    private static int ModeToInt(AlarmProviderMode mode) => mode switch
+    {
+        AlarmProviderMode.Alarmmgr => 1,
+        AlarmProviderMode.Subtag => 2,
+        _ => 0,
+    };
+
     // Replaces the cache with the worker's authoritative snapshot, broadcasting
     // a synthetic transition for any alarm the live stream missed.
     private void ApplyReconcile(IEnumerable<ActiveAlarmSnapshot> snapshots)
@@ -374,6 +569,23 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic
         }
     }
 
+    // Caller holds _sync. Pushes a feed message to every subscriber regardless of
+    // its alarm-filter prefix. Used for provider-status messages, which are global
+    // rather than scoped to a single alarm reference.
+    private void BroadcastToAll(AlarmFeedMessage message)
+    {
+        for (int index = _subscribers.Count - 1; index >= 0; index--)
+        {
+            Subscriber subscriber = _subscribers[index];
+            if (!subscriber.Channel.Writer.TryWrite(message))
+            {
+                subscriber.Channel.Writer.TryComplete(new InvalidOperationException(
+                    "Alarm feed subscriber fell behind and was dropped; reconnect to re-snapshot."));
+                _subscribers.RemoveAt(index);
+            }
+        }
+    }
+
     private void ClearCache()
     {
         lock (_sync)
@@ -398,11 +610,14 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic
         Subscriber subscriber = new(channel, prefix);
 
         ActiveAlarmSnapshot[] snapshot;
+        AlarmProviderStatus providerStatus;
         lock (_sync)
         {
-            // Register before snapshotting under the same lock so no transition
-            // can slip between the snapshot and the live stream.
+            // Register before snapshotting under the same lock so neither a
+            // transition nor a provider-mode change can slip between the snapshot
+            // and the live stream.
             _subscribers.Add(subscriber);
+            providerStatus = BuildProviderStatus();
             snapshot = _alarms.Values
                 .Where(alarm => prefix.Length == 0
                     || alarm.AlarmFullReference.StartsWith(prefix, StringComparison.Ordinal))
@@ -412,6 +627,10 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic
 
         try
         {
+            // Emit the current provider status first so a late joiner immediately
+            // learns the mode (and whether the feed is degraded) before any alarms.
+            yield return new AlarmFeedMessage { ProviderStatus = providerStatus };
+
             foreach (ActiveAlarmSnapshot alarm in snapshot)
             {
                 yield return new AlarmFeedMessage { ActiveAlarm = alarm };
@@ -624,6 +843,8 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic
             Description = transition.Description,
             OperatorUser = transition.OperatorUser,
             OperatorComment = transition.OperatorComment,
+            Degraded = transition.Degraded,
+            SourceProvider = transition.SourceProvider,
         };
         if (transition.OriginalRaiseTimestamp is not null)
         {
@@ -660,6 +881,8 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic
             Description = snapshot.Description,
             OperatorUser = snapshot.OperatorUser,
             OperatorComment = snapshot.OperatorComment,
+            Degraded = snapshot.Degraded,
+            SourceProvider = snapshot.SourceProvider,
         };
         if (snapshot.OriginalRaiseTimestamp is not null)
         {

src/ZB.MOM.WW.MxGateway.Server/Alarms/IAlarmWatchListResolver.cs

@@ -0,0 +1,30 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Server.Configuration;
+
+namespace ZB.MOM.WW.MxGateway.Server.Alarms;
+
+/// <summary>
+///     Resolves the subtag watch-list the gateway sends to the worker when the
+///     central alarm monitor operates in subtag-polling fallback mode. Merges
+///     Galaxy Repository alarm-attribute discovery with the configured
+///     include/exclude overrides and composes the per-attribute subtag item
+///     addresses from the configured subtag names.
+/// </summary>
+public interface IAlarmWatchListResolver
+{
+    /// <summary>
+    ///     Builds the subtag watch-list for the supplied alarm configuration.
+    /// </summary>
+    /// <param name="options">Alarm configuration carrying discovery and subtag-name settings.</param>
+    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
+    /// <returns>
+    ///     The resolved <see cref="AlarmSubtagTarget"/> watch-list, possibly empty.
+    ///     Discovery being unavailable never throws — it yields an empty (or
+    ///     config-only) list and the caller decides what to do with it. Cancellation
+    ///     is the one exception: a triggered <paramref name="cancellationToken"/>
+    ///     still propagates an <see cref="OperationCanceledException"/>.
+    /// </returns>
+    Task<IReadOnlyList<AlarmSubtagTarget>> ResolveAsync(
+        AlarmsOptions options,
+        CancellationToken cancellationToken = default);
+}

src/ZB.MOM.WW.MxGateway.Server/Configuration/AlarmFallbackOptions.cs

@@ -0,0 +1,134 @@
+namespace ZB.MOM.WW.MxGateway.Server.Configuration;
+
+/// <summary>
+///     Controls how the central alarm monitor selects between the MXAccess
+///     alarm-manager subscription and the subtag-polling fallback, and
+///     governs the failure-detection thresholds used when switching.
+/// </summary>
+public sealed class AlarmFallbackOptions
+{
+    /// <summary>
+    ///     Selects the operating mode for the alarm-manager ↔ subtag fallback
+    ///     mechanism. Accepted values (case-insensitive):
+    ///     <list type="bullet">
+    ///         <item><c>Auto</c> — use the alarm manager; switch to subtag polling
+    ///         automatically when <see cref="ConsecutiveFailureThreshold"/> failures
+    ///         are detected, and probe for failback.</item>
+    ///         <item><c>ForceAlarmManager</c> — always use the alarm manager;
+    ///         never fall back.</item>
+    ///         <item><c>ForceSubtag</c> — always use subtag polling;
+    ///         never try the alarm manager.</item>
+    ///     </list>
+    ///     Default is <c>Auto</c>.
+    /// </summary>
+    public string Mode { get; init; } = "Auto";
+
+    /// <summary>
+    ///     Number of consecutive alarm-manager failures before the monitor
+    ///     switches to subtag-polling fallback. Must be at least 1. Default 3.
+    /// </summary>
+    public int ConsecutiveFailureThreshold { get; init; } = 3;
+
+    /// <summary>
+    ///     How often (in seconds) the monitor sends a probe to the alarm manager
+    ///     while operating in subtag-polling fallback mode, to detect recovery.
+    ///     Must be at least 1. Default 30.
+    /// </summary>
+    public int FailbackProbeIntervalSeconds { get; init; } = 30;
+
+    /// <summary>
+    ///     Number of consecutive successful probes required before the monitor
+    ///     considers the alarm manager recovered and switches back. Must be at
+    ///     least 1. Default 3.
+    /// </summary>
+    public int FailbackStableProbes { get; init; } = 3;
+
+    /// <summary>
+    ///     Controls how the monitor discovers the set of objects to poll when
+    ///     operating in subtag-polling fallback mode.
+    /// </summary>
+    public AlarmDiscoveryOptions Discovery { get; init; } = new();
+
+    /// <summary>
+    ///     Configures the subtag names the monitor reads when polling alarm state
+    ///     in subtag-fallback mode.
+    /// </summary>
+    public AlarmSubtagNameOptions Subtags { get; init; } = new();
+}
+
+/// <summary>
+///     Governs how the alarm monitor discovers objects to include in subtag-polling
+///     fallback mode. Either the Galaxy Repository query (when
+///     <see cref="UseGalaxyRepository"/> is <c>true</c>) or an explicit
+///     <see cref="IncludeAttributes"/> list must be supplied when
+///     <c>MxGateway:Alarms:Fallback:Mode</c> is <c>ForceSubtag</c>.
+/// </summary>
+public sealed class AlarmDiscoveryOptions
+{
+    /// <summary>
+    ///     When <c>true</c> the monitor queries the Galaxy Repository SQL database
+    ///     to enumerate alarm objects for the configured area. Default <c>true</c>.
+    /// </summary>
+    public bool UseGalaxyRepository { get; init; } = true;
+
+    /// <summary>
+    ///     Galaxy area to scope the Repository query to. When empty the monitor
+    ///     falls back to <see cref="AlarmsOptions.DefaultArea"/>. Ignored when
+    ///     <see cref="UseGalaxyRepository"/> is <c>false</c>.
+    /// </summary>
+    public string Area { get; init; } = string.Empty;
+
+    /// <summary>
+    ///     Explicit list of MXAccess attribute paths to include in subtag polling,
+    ///     supplementing (or replacing, when <see cref="UseGalaxyRepository"/> is
+    ///     <c>false</c>) the Repository-derived list. Default empty.
+    /// </summary>
+    public string[] IncludeAttributes { get; init; } = Array.Empty<string>();
+
+    /// <summary>
+    ///     Attribute paths to remove from the merged poll list (case-insensitive).
+    ///     The exclude runs after the Repository-derived rows and the explicit
+    ///     <see cref="IncludeAttributes"/> entries are combined, so an exclude that
+    ///     matches an explicit include suppresses it too — excludes win.
+    ///     Ignored when <see cref="UseGalaxyRepository"/> is <c>false</c>.
+    ///     Default empty.
+    /// </summary>
+    public string[] ExcludeAttributes { get; init; } = Array.Empty<string>();
+}
+
+/// <summary>
+///     Configures the subtag names read by the alarm monitor when it is operating
+///     in subtag-polling fallback mode. Names are matched against MXAccess item
+///     handles; validation against the live MXAccess attribute list occurs at
+///     runtime, not at startup.
+///     Defaults are the confirmed AVEVA <c>AlarmExtension</c> primitive field names,
+///     verified against the live ZB Galaxy <c>attribute_definition</c> rows.
+/// </summary>
+public sealed class AlarmSubtagNameOptions
+{
+    /// <summary>
+    ///     Subtag name for the in-alarm boolean. Confirmed AVEVA <c>AlarmExtension</c>
+    ///     field name. Default <c>InAlarm</c>.
+    /// </summary>
+    public string Active { get; init; } = "InAlarm";
+
+    /// <summary>
+    ///     Subtag name for the acknowledged boolean. Confirmed AVEVA <c>AlarmExtension</c>
+    ///     field name. Default <c>Acked</c>.
+    /// </summary>
+    public string Acked { get; init; } = "Acked";
+
+    /// <summary>
+    ///     Subtag name for the acknowledgement comment write target. Writing this subtag
+    ///     performs the acknowledge in AVEVA. Confirmed AVEVA <c>AlarmExtension</c>
+    ///     field name. When empty the ack-comment write path is disabled.
+    ///     Default <c>AckMsg</c>.
+    /// </summary>
+    public string AckComment { get; init; } = "AckMsg";
+
+    /// <summary>
+    ///     Subtag name for the alarm priority / severity. Confirmed AVEVA
+    ///     <c>AlarmExtension</c> field name. Default <c>Priority</c>.
+    /// </summary>
+    public string Priority { get; init; } = "Priority";
+}

src/ZB.MOM.WW.MxGateway.Server/Configuration/AlarmsOptions.cs

@@ -45,4 +45,12 @@ public sealed class AlarmsOptions
     ///     the monitor floors it at 5 seconds.
     /// </summary>
     public int ReconcileIntervalSeconds { get; init; } = 30;
+
+    /// <summary>
+    ///     Configuration for the alarm-manager ↔ subtag fallback mechanism:
+    ///     operating mode, failure-detection thresholds, discovery, and subtag
+    ///     names. Defaults (Mode = "Auto") preserve behaviour when the section is
+    ///     omitted from configuration.
+    /// </summary>
+    public AlarmFallbackOptions Fallback { get; init; } = new();
 }

src/ZB.MOM.WW.MxGateway.Server/Configuration/DashboardOptions.cs

@@ -21,6 +21,17 @@ public sealed class DashboardOptions
     /// </summary>
     public bool RequireHttpsCookie { get; init; } = true;
 
+    /// <summary>
+    /// Dashboard auth cookie name. When null/blank (the default) the canonical
+    /// <see cref="ZB.MOM.WW.MxGateway.Server.Dashboard.DashboardAuthenticationDefaults.CookieName"/>
+    /// is used. Override it (<c>MxGateway:Dashboard:CookieName</c>) to give a distinct name to a
+    /// gateway that shares a hostname with another gateway instance — browser cookies are scoped
+    /// by host+path but NOT by port, so two instances on the same host would otherwise clobber
+    /// each other's dashboard session under a shared cookie name. Changing this signs out
+    /// existing dashboard sessions on next deploy.
+    /// </summary>
+    public string? CookieName { get; init; }
+
     /// <summary>Gets the dashboard snapshot update interval in milliseconds.</summary>
     public int SnapshotIntervalMilliseconds { get; init; } = 1_000;
 

src/ZB.MOM.WW.MxGateway.Server/Configuration/EffectiveLdapConfiguration.cs

@@ -4,8 +4,8 @@ public sealed record EffectiveLdapConfiguration(
     bool Enabled,
     string Server,
     int Port,
-    bool UseTls,
-    bool AllowInsecureLdap,
+    string Transport,
+    bool AllowInsecure,
     string SearchBase,
     string ServiceAccountDn,
     string ServiceAccountPassword,

src/ZB.MOM.WW.MxGateway.Server/Configuration/GatewayConfigurationProvider.cs

@@ -23,8 +23,8 @@ public sealed class GatewayConfigurationProvider(IOptions<GatewayOptions> option
                 Enabled: value.Ldap.Enabled,
                 Server: value.Ldap.Server,
                 Port: value.Ldap.Port,
-                UseTls: value.Ldap.UseTls,
-                AllowInsecureLdap: value.Ldap.AllowInsecureLdap,
+                Transport: value.Ldap.Transport.ToString(),
+                AllowInsecure: value.Ldap.AllowInsecure,
                 SearchBase: value.Ldap.SearchBase,
                 ServiceAccountDn: value.Ldap.ServiceAccountDn,
                 ServiceAccountPassword: RedactedValue,

src/ZB.MOM.WW.MxGateway.Server/Configuration/GatewayConfigurationServiceCollectionExtensions.cs

@@ -1,4 +1,5 @@
-using Microsoft.Extensions.Options;
+using Microsoft.Extensions.Configuration;
+using ZB.MOM.WW.Configuration;
 
 namespace ZB.MOM.WW.MxGateway.Server.Configuration;
 
@@ -6,15 +7,14 @@ public static class GatewayConfigurationServiceCollectionExtensions
 {
     /// <summary>Registers gateway configuration services in the dependency injection container.</summary>
     /// <param name="services">The service collection.</param>
+    /// <param name="configuration">The configuration to bind gateway options from.</param>
     /// <returns>The service collection for chaining.</returns>
-    public static IServiceCollection AddGatewayConfiguration(this IServiceCollection services)
+    public static IServiceCollection AddGatewayConfiguration(
+        this IServiceCollection services, IConfiguration configuration)
     {
-        services
-            .AddOptions<GatewayOptions>()
-            .BindConfiguration(GatewayOptions.SectionName)
-            .ValidateOnStart();
+        services.AddValidatedOptions<GatewayOptions, GatewayOptionsValidator>(
+            configuration, GatewayOptions.SectionName);
 
-        services.AddSingleton<IValidateOptions<GatewayOptions>, GatewayOptionsValidator>();
         services.AddSingleton<IGatewayConfigurationProvider, GatewayConfigurationProvider>();
 
         return services;

src/ZB.MOM.WW.MxGateway.Server/Configuration/GatewayOptionsValidator.cs

@@ -1,9 +1,10 @@
-using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Auth.Abstractions.Ldap;
+using ZB.MOM.WW.Configuration;
 using ZB.MOM.WW.MxGateway.Contracts;
 
 namespace ZB.MOM.WW.MxGateway.Server.Configuration;
 
-public sealed class GatewayOptionsValidator : IValidateOptions<GatewayOptions>
+public sealed class GatewayOptionsValidator : OptionsValidatorBase<GatewayOptions>
 {
     private const int MinimumMaxMessageBytes = 1024;
     private const int MaximumMaxMessageBytes = 256 * 1024 * 1024;
@@ -11,33 +12,26 @@ public sealed class GatewayOptionsValidator : IValidateOptions<GatewayOptions>
     /// <summary>
     /// Validates gateway configuration options.
     /// </summary>
-    /// <param name="name">Options name.</param>
+    /// <param name="builder">The accumulator to record failures on.</param>
     /// <param name="options">Gateway options to validate.</param>
-    /// <returns>Validation result.</returns>
-    public ValidateOptionsResult Validate(string? name, GatewayOptions options)
+    protected override void Validate(ValidationBuilder builder, GatewayOptions options)
     {
-        List<string> failures = [];
-
-        ValidateAuthentication(options.Authentication, failures);
-        ValidateLdap(options.Ldap, failures);
-        ValidateWorker(options.Worker, failures);
-        ValidateSessions(options.Sessions, failures);
-        ValidateEvents(options.Events, failures);
-        ValidateDashboard(options.Dashboard, failures);
-        ValidateProtocol(options.Protocol, failures);
-        ValidateAlarms(options.Alarms, failures);
-        ValidateTls(options.Tls, failures);
-
-        return failures.Count == 0
-            ? ValidateOptionsResult.Success
-            : ValidateOptionsResult.Fail(failures);
+        ValidateAuthentication(options.Authentication, builder);
+        ValidateLdap(options.Ldap, builder);
+        ValidateWorker(options.Worker, builder);
+        ValidateSessions(options.Sessions, builder);
+        ValidateEvents(options.Events, builder);
+        ValidateDashboard(options.Dashboard, builder);
+        ValidateProtocol(options.Protocol, builder);
+        ValidateAlarms(options.Alarms, builder);
+        ValidateTls(options.Tls, builder);
     }
 
-    private static void ValidateAuthentication(AuthenticationOptions options, List<string> failures)
+    private static void ValidateAuthentication(AuthenticationOptions options, ValidationBuilder builder)
     {
         if (!Enum.IsDefined(options.Mode))
         {
-            failures.Add("MxGateway:Authentication:Mode must be a supported authentication mode.");
+            builder.Add("MxGateway:Authentication:Mode must be a supported authentication mode.");
             return;
         }
 
@@ -46,67 +40,67 @@ public sealed class GatewayOptionsValidator : IValidateOptions<GatewayOptions>
             AddIfBlank(
                 options.SqlitePath,
                 "MxGateway:Authentication:SqlitePath is required when API-key authentication is enabled.",
-                failures);
+                builder);
             AddIfInvalidPath(
                 options.SqlitePath,
                 "MxGateway:Authentication:SqlitePath must be a valid filesystem path.",
-                failures);
+                builder);
             AddIfBlank(
                 options.PepperSecretName,
                 "MxGateway:Authentication:PepperSecretName is required when API-key authentication is enabled.",
-                failures);
+                builder);
         }
     }
 
-    private static void ValidateLdap(LdapOptions options, List<string> failures)
+    private static void ValidateLdap(LdapOptions options, ValidationBuilder builder)
     {
         if (!options.Enabled)
         {
             return;
         }
 
-        AddIfBlank(options.Server, "MxGateway:Ldap:Server is required when LDAP login is enabled.", failures);
-        AddIfBlank(options.SearchBase, "MxGateway:Ldap:SearchBase is required when LDAP login is enabled.", failures);
+        AddIfBlank(options.Server, "MxGateway:Ldap:Server is required when LDAP login is enabled.", builder);
+        AddIfBlank(options.SearchBase, "MxGateway:Ldap:SearchBase is required when LDAP login is enabled.", builder);
         AddIfBlank(
             options.ServiceAccountDn,
             "MxGateway:Ldap:ServiceAccountDn is required when LDAP login is enabled.",
-            failures);
+            builder);
         AddIfBlank(
             options.ServiceAccountPassword,
             "MxGateway:Ldap:ServiceAccountPassword is required when LDAP login is enabled.",
-            failures);
+            builder);
         AddIfBlank(
             options.UserNameAttribute,
             "MxGateway:Ldap:UserNameAttribute is required when LDAP login is enabled.",
-            failures);
+            builder);
         AddIfBlank(
             options.DisplayNameAttribute,
             "MxGateway:Ldap:DisplayNameAttribute is required when LDAP login is enabled.",
-            failures);
+            builder);
         AddIfBlank(
             options.GroupAttribute,
             "MxGateway:Ldap:GroupAttribute is required when LDAP login is enabled.",
-            failures);
-        AddIfNotPositive(options.Port, "MxGateway:Ldap:Port must be greater than zero.", failures);
+            builder);
+        builder.Port(options.Port, "MxGateway:Ldap:Port");
 
-        if (!options.UseTls && !options.AllowInsecureLdap)
+        if (options.Transport == LdapTransport.None && !options.AllowInsecure)
         {
-            failures.Add("MxGateway:Ldap:AllowInsecureLdap must be true when UseTls is false.");
+            builder.Add("MxGateway:Ldap:AllowInsecure must be true when Transport is None (plaintext).");
         }
     }
 
-    private static void ValidateWorker(WorkerOptions options, List<string> failures)
+    private static void ValidateWorker(WorkerOptions options, ValidationBuilder builder)
     {
-        AddIfBlank(options.ExecutablePath, "MxGateway:Worker:ExecutablePath is required.", failures);
+        AddIfBlank(options.ExecutablePath, "MxGateway:Worker:ExecutablePath is required.", builder);
         AddIfInvalidPath(
             options.ExecutablePath,
             "MxGateway:Worker:ExecutablePath must be a valid filesystem path.",
-            failures);
+            builder);
 
         if (!string.IsNullOrWhiteSpace(options.ExecutablePath)
             && !string.Equals(Path.GetExtension(options.ExecutablePath), ".exe", StringComparison.OrdinalIgnoreCase))
         {
-            failures.Add("MxGateway:Worker:ExecutablePath must point to a .exe file.");
+            builder.Add("MxGateway:Worker:ExecutablePath must point to a .exe file.");
         }
 
         if (!string.IsNullOrWhiteSpace(options.WorkingDirectory))
@@ -114,94 +108,94 @@ public sealed class GatewayOptionsValidator : IValidateOptions<GatewayOptions>
             AddIfInvalidPath(
                 options.WorkingDirectory,
                 "MxGateway:Worker:WorkingDirectory must be a valid filesystem path.",
-                failures);
+                builder);
         }
 
         if (!Enum.IsDefined(options.RequiredArchitecture))
         {
-            failures.Add("MxGateway:Worker:RequiredArchitecture must be a supported worker architecture.");
+            builder.Add("MxGateway:Worker:RequiredArchitecture must be a supported worker architecture.");
         }
 
         AddIfNotPositive(
             options.StartupTimeoutSeconds,
             "MxGateway:Worker:StartupTimeoutSeconds must be greater than zero.",
-            failures);
+            builder);
         AddIfNotPositive(
             options.StartupProbeRetryAttempts,
             "MxGateway:Worker:StartupProbeRetryAttempts must be greater than zero.",
-            failures);
+            builder);
         AddIfNotPositive(
             options.StartupProbeRetryDelayMilliseconds,
             "MxGateway:Worker:StartupProbeRetryDelayMilliseconds must be greater than zero.",
-            failures);
+            builder);
         AddIfNotPositive(
             options.PipeConnectAttemptTimeoutMilliseconds,
             "MxGateway:Worker:PipeConnectAttemptTimeoutMilliseconds must be greater than zero.",
-            failures);
+            builder);
         AddIfNotPositive(
             options.ShutdownTimeoutSeconds,
             "MxGateway:Worker:ShutdownTimeoutSeconds must be greater than zero.",
-            failures);
+            builder);
         AddIfNotPositive(
             options.HeartbeatIntervalSeconds,
             "MxGateway:Worker:HeartbeatIntervalSeconds must be greater than zero.",
-            failures);
+            builder);
         AddIfNotPositive(
             options.HeartbeatGraceSeconds,
             "MxGateway:Worker:HeartbeatGraceSeconds must be greater than zero.",
-            failures);
+            builder);
 
         if (options.HeartbeatGraceSeconds < options.HeartbeatIntervalSeconds)
         {
-            failures.Add(
+            builder.Add(
                 "MxGateway:Worker:HeartbeatGraceSeconds must be greater than or equal to HeartbeatIntervalSeconds.");
         }
 
         if (options.MaxMessageBytes is < MinimumMaxMessageBytes or > MaximumMaxMessageBytes)
         {
-            failures.Add(
+            builder.Add(
                 $"MxGateway:Worker:MaxMessageBytes must be between {MinimumMaxMessageBytes} and {MaximumMaxMessageBytes}.");
         }
     }
 
-    private static void ValidateSessions(SessionOptions options, List<string> failures)
+    private static void ValidateSessions(SessionOptions options, ValidationBuilder builder)
     {
         AddIfNotPositive(
             options.DefaultCommandTimeoutSeconds,
             "MxGateway:Sessions:DefaultCommandTimeoutSeconds must be greater than zero.",
-            failures);
-        AddIfNotPositive(options.MaxSessions, "MxGateway:Sessions:MaxSessions must be greater than zero.", failures);
+            builder);
+        AddIfNotPositive(options.MaxSessions, "MxGateway:Sessions:MaxSessions must be greater than zero.", builder);
         AddIfNotPositive(
             options.MaxPendingCommandsPerSession,
             "MxGateway:Sessions:MaxPendingCommandsPerSession must be greater than zero.",
-            failures);
+            builder);
         AddIfNotPositive(
             options.DefaultLeaseSeconds,
             "MxGateway:Sessions:DefaultLeaseSeconds must be greater than zero.",
-            failures);
+            builder);
         AddIfNotPositive(
             options.LeaseSweepIntervalSeconds,
             "MxGateway:Sessions:LeaseSweepIntervalSeconds must be greater than zero.",
-            failures);
+            builder);
 
         if (options.AllowMultipleEventSubscribers)
         {
-            failures.Add(
+            builder.Add(
                 "MxGateway:Sessions:AllowMultipleEventSubscribers is not supported until event fan-out is implemented.");
         }
     }
 
-    private static void ValidateEvents(EventOptions options, List<string> failures)
+    private static void ValidateEvents(EventOptions options, ValidationBuilder builder)
     {
-        AddIfNotPositive(options.QueueCapacity, "MxGateway:Events:QueueCapacity must be greater than zero.", failures);
+        AddIfNotPositive(options.QueueCapacity, "MxGateway:Events:QueueCapacity must be greater than zero.", builder);
 
         if (!Enum.IsDefined(options.BackpressurePolicy))
         {
-            failures.Add("MxGateway:Events:BackpressurePolicy must be a supported backpressure policy.");
+            builder.Add("MxGateway:Events:BackpressurePolicy must be a supported backpressure policy.");
         }
     }
 
-    private static void ValidateDashboard(DashboardOptions options, List<string> failures)
+    private static void ValidateDashboard(DashboardOptions options, ValidationBuilder builder)
     {
         // GroupToRole shape is validated even when the dashboard is disabled so
         // misconfiguration surfaces at startup; emptiness is allowed, with the
@@ -212,13 +206,13 @@ public sealed class GatewayOptionsValidator : IValidateOptions<GatewayOptions>
         {
             if (string.IsNullOrWhiteSpace(entry.Key))
             {
-                failures.Add("MxGateway:Dashboard:GroupToRole keys (LDAP group names) must be non-blank.");
+                builder.Add("MxGateway:Dashboard:GroupToRole keys (LDAP group names) must be non-blank.");
             }
 
             if (!string.Equals(entry.Value, Dashboard.DashboardRoles.Admin, StringComparison.Ordinal)
                 && !string.Equals(entry.Value, Dashboard.DashboardRoles.Viewer, StringComparison.Ordinal))
             {
-                failures.Add(
+                builder.Add(
                     $"MxGateway:Dashboard:GroupToRole['{entry.Key}'] must be '{Dashboard.DashboardRoles.Admin}' or '{Dashboard.DashboardRoles.Viewer}'.");
             }
         }
@@ -226,18 +220,20 @@ public sealed class GatewayOptionsValidator : IValidateOptions<GatewayOptions>
         AddIfNotPositive(
             options.SnapshotIntervalMilliseconds,
             "MxGateway:Dashboard:SnapshotIntervalMilliseconds must be greater than zero.",
-            failures);
+            builder);
         AddIfNegative(
             options.RecentFaultLimit,
             "MxGateway:Dashboard:RecentFaultLimit must be greater than or equal to zero.",
-            failures);
+            builder);
         AddIfNegative(
             options.RecentSessionLimit,
             "MxGateway:Dashboard:RecentSessionLimit must be greater than or equal to zero.",
-            failures);
+            builder);
     }
 
-    private static void ValidateAlarms(AlarmsOptions options, List<string> failures)
+    private static readonly string[] ValidAlarmFallbackModes = ["Auto", "ForceAlarmManager", "ForceSubtag"];
+
+    private static void ValidateAlarms(AlarmsOptions options, ValidationBuilder builder)
     {
         if (!options.Enabled)
         {
@@ -251,26 +247,66 @@ public sealed class GatewayOptionsValidator : IValidateOptions<GatewayOptions>
         if (string.IsNullOrWhiteSpace(options.SubscriptionExpression)
             && string.IsNullOrWhiteSpace(options.DefaultArea))
         {
-            failures.Add(
+            builder.Add(
                 "MxGateway:Alarms requires either a non-blank SubscriptionExpression or a non-blank DefaultArea when Enabled is true.");
         }
 
         if (!string.IsNullOrWhiteSpace(options.SubscriptionExpression)
             && !options.SubscriptionExpression.StartsWith(@"\\", StringComparison.Ordinal))
         {
-            failures.Add(
+            builder.Add(
                 @"MxGateway:Alarms:SubscriptionExpression must start with '\\' (canonical \\<host>\Galaxy!<area> shape).");
         }
+
+        ValidateAlarmFallback(options.Fallback, builder);
+    }
+
+    private static void ValidateAlarmFallback(AlarmFallbackOptions fallback, ValidationBuilder builder)
+    {
+        // Validate Mode is one of the recognised values (case-insensitive).
+        bool modeValid = Array.Exists(
+            ValidAlarmFallbackModes,
+            m => string.Equals(m, fallback.Mode, StringComparison.OrdinalIgnoreCase));
+
+        if (!modeValid)
+        {
+            builder.Add(
+                $"MxGateway:Alarms:Fallback:Mode must be one of: {string.Join(", ", ValidAlarmFallbackModes)} (was '{fallback.Mode}').");
+        }
+
+        // ForceSubtag requires either Galaxy Repository discovery or an explicit IncludeAttributes list.
+        if (modeValid
+            && string.Equals(fallback.Mode, "ForceSubtag", StringComparison.OrdinalIgnoreCase)
+            && !fallback.Discovery.UseGalaxyRepository
+            && fallback.Discovery.IncludeAttributes.Length == 0)
+        {
+            builder.Add(
+                "MxGateway:Alarms:Fallback ForceSubtag requires Galaxy Repository discovery or a non-empty Discovery:IncludeAttributes list.");
+        }
+
+        // Floor validation: numeric thresholds must be at least 1.
+        AddIfNotPositive(
+            fallback.ConsecutiveFailureThreshold,
+            "MxGateway:Alarms:Fallback:ConsecutiveFailureThreshold must be greater than zero.",
+            builder);
+        AddIfNotPositive(
+            fallback.FailbackProbeIntervalSeconds,
+            "MxGateway:Alarms:Fallback:FailbackProbeIntervalSeconds must be greater than zero.",
+            builder);
+        AddIfNotPositive(
+            fallback.FailbackStableProbes,
+            "MxGateway:Alarms:Fallback:FailbackStableProbes must be greater than zero.",
+            builder);
     }
 
     private const int MinimumCertValidityYears = 1;
     private const int MaximumCertValidityYears = 100;
 
-    private static void ValidateTls(TlsOptions options, List<string> failures)
+    private static void ValidateTls(TlsOptions options, ValidationBuilder builder)
     {
         if (options.ValidityYears is < MinimumCertValidityYears or > MaximumCertValidityYears)
         {
-            failures.Add(
+            builder.Add(
                 $"MxGateway:Tls:ValidityYears must be between {MinimumCertValidityYears} and {MaximumCertValidityYears}.");
         }
 
@@ -278,61 +314,52 @@ public sealed class GatewayOptionsValidator : IValidateOptions<GatewayOptions>
         AddIfBlank(
             options.SelfSignedCertPath,
             "MxGateway:Tls:SelfSignedCertPath must not be blank.",
-            failures);
+            builder);
         AddIfInvalidPath(
             options.SelfSignedCertPath,
             "MxGateway:Tls:SelfSignedCertPath must be a valid filesystem path.",
-            failures);
+            builder);
 
         foreach (string dns in options.AdditionalDnsNames)
         {
             if (string.IsNullOrWhiteSpace(dns))
             {
-                failures.Add("MxGateway:Tls:AdditionalDnsNames entries must be non-blank.");
+                builder.Add("MxGateway:Tls:AdditionalDnsNames entries must be non-blank.");
             }
         }
     }
 
-    private static void ValidateProtocol(ProtocolOptions options, List<string> failures)
+    private static void ValidateProtocol(ProtocolOptions options, ValidationBuilder builder)
     {
         if (options.WorkerProtocolVersion != GatewayContractInfo.WorkerProtocolVersion)
         {
-            failures.Add(
+            builder.Add(
                 $"MxGateway:Protocol:WorkerProtocolVersion must be {GatewayContractInfo.WorkerProtocolVersion}.");
         }
 
         if (options.MaxGrpcMessageBytes is < MinimumMaxMessageBytes or > MaximumMaxMessageBytes)
         {
-            failures.Add(
+            builder.Add(
                 $"MxGateway:Protocol:MaxGrpcMessageBytes must be between {MinimumMaxMessageBytes} and {MaximumMaxMessageBytes}.");
         }
     }
 
-    private static void AddIfBlank(string? value, string message, List<string> failures)
+    private static void AddIfBlank(string? value, string message, ValidationBuilder builder)
     {
-        if (string.IsNullOrWhiteSpace(value))
-        {
-            failures.Add(message);
-        }
+        builder.RequireThat(!string.IsNullOrWhiteSpace(value), message);
     }
 
-    private static void AddIfNotPositive(int value, string message, List<string> failures)
+    private static void AddIfNotPositive(int value, string message, ValidationBuilder builder)
     {
-        if (value <= 0)
-        {
-            failures.Add(message);
-        }
+        builder.RequireThat(value > 0, message);
     }
 
-    private static void AddIfNegative(int value, string message, List<string> failures)
+    private static void AddIfNegative(int value, string message, ValidationBuilder builder)
     {
-        if (value < 0)
-        {
-            failures.Add(message);
-        }
+        builder.RequireThat(value >= 0, message);
     }
 
-    private static void AddIfInvalidPath(string? value, string message, List<string> failures)
+    private static void AddIfInvalidPath(string? value, string message, ValidationBuilder builder)
     {
         if (string.IsNullOrWhiteSpace(value))
         {
@@ -345,15 +372,19 @@ public sealed class GatewayOptionsValidator : IValidateOptions<GatewayOptions>
         }
         catch (ArgumentException)
         {
-            failures.Add(message);
+            builder.Add(message);
         }
         catch (NotSupportedException)
         {
-            failures.Add(message);
+            builder.Add(message);
         }
         catch (PathTooLongException)
         {
-            failures.Add(message);
+            builder.Add(message);
+        }
+        catch (IOException)
+        {
+            builder.Add(message);
         }
     }
 }

src/ZB.MOM.WW.MxGateway.Server/Configuration/LdapOptions.cs

@@ -1,5 +1,32 @@
+using ZB.MOM.WW.Auth.Abstractions.Ldap;
+
 namespace ZB.MOM.WW.MxGateway.Server.Configuration;
 
+/// <summary>
+/// Gateway-side view of the <c>MxGateway:Ldap</c> section. This is a SHADOW of the
+/// shared <see cref="ZB.MOM.WW.Auth.Abstractions.Ldap.LdapOptions"/> type and is NOT
+/// used to perform LDAP authentication at runtime — runtime bind/search is done by the
+/// shared <c>ZB.MOM.WW.Auth.Ldap</c> provider, whose options are bound directly from the
+/// same <c>MxGateway:Ldap</c> section by <c>AddZbLdapAuth</c> (see
+/// <see cref="ZB.MOM.WW.MxGateway.Server.Dashboard.DashboardServiceCollectionExtensions"/>).
+/// <para>
+/// This shadow exists for three things only: (1) startup validation via
+/// <see cref="GatewayOptionsValidator"/>; (2) the redacted effective-config display
+/// (<see cref="EffectiveLdapConfiguration"/> / <see cref="GatewayConfigurationProvider"/>);
+/// and (3) it is the single home of the gateway's dev/default LDAP values, which the
+/// integration live-test helper copies onto the shared options.
+/// </para>
+/// <para>
+/// Review C2 — DRIFT WARNING: this class MUST stay field-compatible with the shared
+/// <see cref="ZB.MOM.WW.Auth.Abstractions.Ldap.LdapOptions"/> so the one config section
+/// binds cleanly onto both. The two are intentionally NOT merged because their defaults
+/// differ on purpose: this shadow ships dev-friendly defaults (plaintext localhost,
+/// <c>AllowInsecure=true</c>, populated <c>SearchBase</c>/<c>ServiceAccount*</c>), whereas
+/// the shared type is secure-by-default (<c>Transport=Ldaps</c>, <c>AllowInsecure=false</c>,
+/// empty DN fields). If you add/rename/remove a field on the shared type, mirror it here
+/// (and in the validator + effective-config) so the section keeps binding to both.
+/// </para>
+/// </summary>
 public sealed class LdapOptions
 {
     /// <summary>Gets a value indicating whether LDAP authentication is enabled.</summary>
@@ -11,17 +38,24 @@ public sealed class LdapOptions
     /// <summary>Gets the LDAP server port.</summary>
     public int Port { get; init; } = 3893;
 
-    /// <summary>Gets a value indicating whether TLS is required for the connection.</summary>
-    public bool UseTls { get; init; }
+    /// <summary>
+    /// Gets the transport/TLS mode for the LDAP connection. Replaces the former
+    /// boolean <c>UseTls</c> (true ≈ <see cref="LdapTransport.Ldaps"/>, false =
+    /// <see cref="LdapTransport.None"/>). <see cref="LdapTransport.StartTls"/> upgrades
+    /// a plaintext connection to TLS. Matches the shared
+    /// <see cref="ZB.MOM.WW.Auth.Abstractions.Ldap.LdapOptions.Transport"/> field so the
+    /// <c>MxGateway:Ldap</c> section binds straight onto the shared options.
+    /// </summary>
+    public LdapTransport Transport { get; init; } = LdapTransport.None;
 
-    /// <summary>Gets a value indicating whether insecure LDAP connections are allowed.</summary>
-    public bool AllowInsecureLdap { get; init; } = true;
+    /// <summary>Gets a value indicating whether insecure (plaintext) LDAP connections are allowed.</summary>
+    public bool AllowInsecure { get; init; } = true;
 
     /// <summary>Gets the LDAP search base distinguished name.</summary>
-    public string SearchBase { get; init; } = "dc=lmxopcua,dc=local";
+    public string SearchBase { get; init; } = "dc=zb,dc=local";
 
     /// <summary>Gets the service account distinguished name.</summary>
-    public string ServiceAccountDn { get; init; } = "cn=serviceaccount,dc=lmxopcua,dc=local";
+    public string ServiceAccountDn { get; init; } = "cn=serviceaccount,dc=zb,dc=local";
 
     /// <summary>Gets the service account password.</summary>
     public string ServiceAccountPassword { get; init; } = "serviceaccount123";

src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/App.razor

@@ -5,14 +5,14 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <base href="/" />
     <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css" />
-    <link rel="stylesheet" href="/css/theme.css" />
+    <ThemeHead />
     <link rel="stylesheet" href="/css/site.css" />
     <HeadOutlet @rendermode="InteractiveServer" />
 </head>
 <body class="dashboard-body">
     <Routes @rendermode="InteractiveServer" />
     <script src="/lib/bootstrap/js/bootstrap.bundle.min.js"></script>
-    <script src="/js/nav-state.js"></script>
+    <ThemeScripts />
     <script src="/_framework/blazor.web.js"></script>
 </body>
 </html>

src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Layout/LoginLayout.razor

@@ -0,0 +1,6 @@
+@inherits LayoutComponentBase
+
+@* Minimal layout for the login page: no side rail, no brand block. The page
+   renders its own centred card via the shared kit's <LoginCard>. Mirrors
+   OtOpcUa AdminUI's LoginLayout. *@
+@Body

src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Layout/MainLayout.razor

@@ -1,210 +1,40 @@
-@using System.Linq
-@using Microsoft.AspNetCore.Components.Routing
-@using Microsoft.JSInterop
-@implements IDisposable
 @inherits LayoutComponentBase
-@inject NavigationManager Navigation
-@inject IJSRuntime JS
 
-<div class="d-flex flex-column flex-lg-row" style="min-height: 100vh;">
-    @* Hamburger toggle: visible only on viewports <lg. Bootstrap collapse JS
-       lives in bootstrap.bundle.min.js (loaded in App.razor). *@
-    <button class="btn btn-outline-secondary btn-sm d-lg-none m-2 align-self-start"
-            type="button"
-            data-bs-toggle="collapse"
-            data-bs-target="#sidebar-collapse"
-            aria-controls="sidebar-collapse"
-            aria-expanded="false"
-            aria-label="Toggle navigation">
-        &#9776;
-    </button>
-
-    <div class="collapse d-lg-block" id="sidebar-collapse">
-        <nav class="sidebar d-flex flex-column">
-            <a class="brand" href="/"><span class="mark">&#9646;</span> MXAccess Gateway</a>
-
-            <div style="overflow-y:auto; flex:1 1 auto; min-height:0;">
-                <ul class="nav flex-column">
-                    <li class="nav-item">
-                        <NavLink class="nav-link" href="/" Match="NavLinkMatch.All">Dashboard</NavLink>
-                    </li>
-
-                    <NavSection Title="Runtime"
-                                Expanded="@_expanded.Contains("runtime")"
-                                OnToggle="@(() => ToggleAsync("runtime"))">
-                        <li class="nav-item">
-                            <NavLink class="nav-link" href="/sessions" Match="NavLinkMatch.Prefix">Sessions</NavLink>
-                        </li>
-                        <li class="nav-item">
-                            <NavLink class="nav-link" href="/workers" Match="NavLinkMatch.Prefix">Workers</NavLink>
-                        </li>
-                        <li class="nav-item">
-                            <NavLink class="nav-link" href="/events" Match="NavLinkMatch.Prefix">Events</NavLink>
-                        </li>
-                        <li class="nav-item">
-                            <NavLink class="nav-link" href="/alarms" Match="NavLinkMatch.Prefix">Alarms</NavLink>
-                        </li>
-                    </NavSection>
-
-                    <NavSection Title="Galaxy"
-                                Expanded="@_expanded.Contains("galaxy")"
-                                OnToggle="@(() => ToggleAsync("galaxy"))">
-                        <li class="nav-item">
-                            <NavLink class="nav-link" href="/galaxy" Match="NavLinkMatch.Prefix">Repository</NavLink>
-                        </li>
-                        <li class="nav-item">
-                            <NavLink class="nav-link" href="/browse" Match="NavLinkMatch.Prefix">Browse</NavLink>
-                        </li>
-                    </NavSection>
-
-                    <NavSection Title="Admin"
-                                Expanded="@_expanded.Contains("admin")"
-                                OnToggle="@(() => ToggleAsync("admin"))">
-                        <li class="nav-item">
-                            <NavLink class="nav-link" href="/apikeys" Match="NavLinkMatch.Prefix">API Keys</NavLink>
-                        </li>
-                        <li class="nav-item">
-                            <NavLink class="nav-link" href="/settings" Match="NavLinkMatch.Prefix">Settings</NavLink>
-                        </li>
-                    </NavSection>
-                </ul>
-            </div>
-
-            <AuthorizeView>
-                <Authorized Context="authState">
-                    <div class="border-top px-3 py-2">
-                        <div class="d-flex justify-content-between align-items-center">
-                            <span class="text-body-secondary small">@authState.User.Identity?.Name</span>
-                            <form method="post" action="/logout" data-enhance="false">
-                                <AntiforgeryToken />
-                                <button type="submit" class="btn btn-outline-secondary btn-sm py-0 px-2">Sign Out</button>
-                            </form>
-                        </div>
-                    </div>
-                </Authorized>
-                <NotAuthorized>
-                    <div class="border-top px-3 py-2">
-                        <a href="/login" class="btn btn-outline-secondary btn-sm py-0 px-2 w-100">Sign In</a>
-                    </div>
-                </NotAuthorized>
-            </AuthorizeView>
-        </nav>
-    </div>
-
-    <main class="page flex-grow-1">
-        @Body
-    </main>
-</div>
-
-@code {
-    // Sections whose collapsed/expanded state we persist. Acts as the allow-list
-    // when parsing the cookie so stale or attacker-supplied ids are ignored.
-    private static readonly string[] SectionIds = { "runtime", "galaxy", "admin" };
-
-    // The currently-expanded sections. Populated from the cookie on first
-    // render; mutated by ToggleAsync and by navigating into a section.
-    private readonly HashSet<string> _expanded = new(StringComparer.Ordinal);
-
-    protected override void OnInitialized()
-    {
-        Navigation.LocationChanged += OnLocationChanged;
-    }
-
-    protected override async Task OnAfterRenderAsync(bool firstRender)
-    {
-        if (!firstRender)
-        {
-            return;
-        }
-
-        // Hydrate from the cookie. Until this completes the sidebar paints
-        // collapsed, matching the CentralUI behaviour.
-        string saved;
-        try
-        {
-            saved = await JS.InvokeAsync<string>("navState.get") ?? string.Empty;
-        }
-        catch (JSDisconnectedException)
-        {
-            return;
-        }
-
-        foreach (var id in saved.Split(
-            ',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
-        {
-            if (Array.IndexOf(SectionIds, id) >= 0)
-            {
-                _expanded.Add(id);
-            }
-        }
-
-        // The section of the page we loaded on is always expanded.
-        if (EnsureCurrentSectionExpanded())
-        {
-            await PersistAsync();
-        }
-
-        StateHasChanged();
-    }
-
-    private void OnLocationChanged(object? sender, LocationChangedEventArgs e)
-    {
-        if (EnsureCurrentSectionExpanded())
-        {
-            _ = PersistAsync();
-            _ = InvokeAsync(StateHasChanged);
-        }
-    }
-
-    private async Task ToggleAsync(string id)
-    {
-        if (!_expanded.Remove(id))
-        {
-            _expanded.Add(id);
-        }
-
-        await PersistAsync();
-    }
-
-    // Adds the current page's section to _expanded; returns true if it changed.
-    private bool EnsureCurrentSectionExpanded()
-    {
-        var section = CurrentSection();
-        return section is not null && _expanded.Add(section);
-    }
-
-    // Maps the current URL's first path segment to a section id, or null for
-    // sectionless pages (Dashboard, Login).
-    private string? CurrentSection()
-    {
-        var relative = Navigation.ToBaseRelativePath(Navigation.Uri);
-        var firstSegment = relative.Split('?', '#')[0]
-            .Split('/', StringSplitOptions.RemoveEmptyEntries)
-            .FirstOrDefault();
-
-        return firstSegment switch
-        {
-            "sessions" or "workers" or "events" or "alarms" => "runtime",
-            "galaxy" or "browse" => "galaxy",
-            "apikeys" or "settings" => "admin",
-            _ => null,
-        };
-    }
-
-    private async Task PersistAsync()
-    {
-        try
-        {
-            await JS.InvokeVoidAsync("navState.set", string.Join(',', _expanded));
-        }
-        catch (JSDisconnectedException)
-        {
-            // The circuit is gone — nothing to persist to.
-        }
-    }
-
-    public void Dispose()
-    {
-        Navigation.LocationChanged -= OnLocationChanged;
-    }
-}
+@* Thin layout: delegates the side-rail chassis (hamburger, brand, responsive
+   collapse) to the shared ZB.MOM.WW.Theme <ThemeShell>. The nav is reproduced
+   with the kit's NavRailSection / NavRailItem; section expand-state persistence
+   is owned by the kit's <details> + ThemeScripts (no JS interop here). *@
+<ThemeShell Product="MXAccess Gateway" Accent="#2f5fd0">
+    <Nav>
+        <NavRailItem Href="/" Text="Dashboard" Match="NavLinkMatch.All" />
+        <NavRailSection Title="Runtime" Key="runtime">
+            <NavRailItem Href="/sessions" Text="Sessions" />
+            <NavRailItem Href="/workers" Text="Workers" />
+            <NavRailItem Href="/events" Text="Events" />
+            <NavRailItem Href="/alarms" Text="Alarms" />
+        </NavRailSection>
+        <NavRailSection Title="Galaxy" Key="galaxy">
+            <NavRailItem Href="/galaxy" Text="Repository" />
+            <NavRailItem Href="/browse" Text="Browse" />
+        </NavRailSection>
+        <NavRailSection Title="Admin" Key="admin">
+            <NavRailItem Href="/apikeys" Text="API Keys" />
+            <NavRailItem Href="/settings" Text="Settings" />
+        </NavRailSection>
+    </Nav>
+    <RailFooter>
+        <AuthorizeView>
+            <Authorized Context="authState">
+                <span class="rail-user">@authState.User.Identity?.Name</span>
+                <form method="post" action="/logout" data-enhance="false">
+                    <AntiforgeryToken />
+                    <button class="rail-btn" type="submit">Sign Out</button>
+                </form>
+            </Authorized>
+            <NotAuthorized>
+                <a class="rail-btn" href="/login">Sign In</a>
+            </NotAuthorized>
+        </AuthorizeView>
+    </RailFooter>
+    <ChildContent>@Body</ChildContent>
+</ThemeShell>

src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Layout/NavSection.razor

@@ -1,35 +0,0 @@
-@* A collapsible sidebar nav section. The header is a full-width button that
-   toggles ChildContent visibility. Pattern lifted from ScadaLink CentralUI
-   (Components/Layout/NavSection.razor) — see [[project-deployed-service]]. *@
-
-<li class="nav-item">
-    <button type="button"
-            class="nav-section-toggle"
-            @onclick="OnToggle"
-            aria-expanded="@(Expanded ? "true" : "false")">
-        <span class="chevron" aria-hidden="true">@(Expanded ? "▾" : "▸")</span>
-        <span>@Title</span>
-    </button>
-</li>
-@if (Expanded)
-{
-    @ChildContent
-}
-
-@code {
-    /// <summary>Section label shown in the header (e.g. "Runtime").</summary>
-    [Parameter, EditorRequired]
-    public string Title { get; set; } = string.Empty;
-
-    /// <summary>Whether the section is expanded — its items rendered.</summary>
-    [Parameter]
-    public bool Expanded { get; set; }
-
-    /// <summary>Raised when the header button is clicked.</summary>
-    [Parameter]
-    public EventCallback OnToggle { get; set; }
-
-    /// <summary>The section's nav items, rendered only while expanded.</summary>
-    [Parameter]
-    public RenderFragment? ChildContent { get; set; }
-}

src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/AlarmsPage.razor

@@ -1,7 +1,10 @@
 @page "/alarms"
 @implements IAsyncDisposable
+@using Microsoft.AspNetCore.SignalR.Client
+@using ZB.MOM.WW.MxGateway.Server.Dashboard.Hubs
 @inject IDashboardLiveDataService LiveData
 @inject IOptions<GatewayOptions> GatewayOptions
+@inject DashboardHubConnectionFactory HubFactory
 
 <PageTitle>Dashboard Alarms</PageTitle>
 
@@ -10,6 +13,12 @@
         <h1>Alarms</h1>
         <div class="text-secondary">@HeaderLine()</div>
     </div>
+    <div class="d-flex align-items-center gap-2">
+        <span class="badge @_providerStatus.BadgeCssClass"
+              title="@ProviderStatusTitle()">
+            @_providerStatus.Label
+        </span>
+    </div>
 </div>
 
 @if (!GatewayOptions.Value.Alarms.Enabled)
@@ -163,10 +172,44 @@
     private readonly CancellationTokenSource _cts = new();
     private Task? _pollTask;
 
+    private DashboardAlarmProviderStatus _providerStatus = DashboardAlarmProviderStatus.Healthy;
+    private HubConnection? _alarmsHub;
+
     /// <inheritdoc />
     protected override void OnInitialized()
     {
         _pollTask = PollLoopAsync();
+        _ = AttachAlarmsHubAsync();
+    }
+
+    private string? ProviderStatusTitle()
+    {
+        return _providerStatus.IsDegraded && !string.IsNullOrWhiteSpace(_providerStatus.Reason)
+            ? _providerStatus.Reason
+            : null;
+    }
+
+    private async Task AttachAlarmsHubAsync()
+    {
+        _alarmsHub = HubFactory.Create("/hubs/alarms");
+        _alarmsHub.On<AlarmFeedMessage>(AlarmsHub.AlarmMessage, async message =>
+        {
+            if (message.PayloadCase == AlarmFeedMessage.PayloadOneofCase.ProviderStatus)
+            {
+                _providerStatus = DashboardAlarmProviderStatus.FromFeed(message);
+                await InvokeAsync(StateHasChanged).ConfigureAwait(false);
+            }
+        });
+
+        try
+        {
+            await _alarmsHub.StartAsync(_cts.Token).ConfigureAwait(false);
+        }
+        catch
+        {
+            // The badge is best-effort; it stays at the healthy default until
+            // the hub reconnects and delivers a fresh provider-status message.
+        }
     }
 
     private string HeaderLine()
@@ -268,6 +311,19 @@
     public async ValueTask DisposeAsync()
     {
         await _cts.CancelAsync();
+
+        if (_alarmsHub is not null)
+        {
+            try
+            {
+                await _alarmsHub.DisposeAsync();
+            }
+            catch
+            {
+                // Disposal-time errors are best-effort.
+            }
+        }
+
         if (_pollTask is not null)
         {
             try

src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/Login.razor

@@ -0,0 +1,33 @@
+@page "/login"
+@layout LoginLayout
+@using Microsoft.AspNetCore.Authorization
+@* Login MUST stay anonymously reachable — [AllowAnonymous] overrides the
+   RequireAuthorization(ViewerPolicy) that MapRazorComponents<App>() applies, so the
+   cookie scheme's LoginPath="/login" redirect lands here for unauthenticated users.
+
+   The card is the shared kit's <LoginCard>: it renders a NATIVE static
+   <form method="post" action="/auth/login"> (username/password + hidden returnUrl). A native
+   form submit is not a Blazor event, so it reaches the minimal-API POST /auth/login endpoint
+   regardless of this app's InteractiveServer render mode. <AntiforgeryToken/> supplies the
+   token that PostLoginAsync's antiforgery.ValidateRequestAsync checks.
+
+   NOTE: the POST target is /auth/login, NOT /login. This @page lives at "/login" and the
+   Razor Components endpoint matches ALL methods, so a POST to /login collided with the
+   minimal-API MapPost("/login") and threw AmbiguousMatchException (HTTP 500). Posting to a
+   distinct /auth/login path (mirroring ScadaBridge) keeps the GET page and POST handler from
+   sharing a route. *@
+@attribute [AllowAnonymous]
+
+<LoginCard Product="MXAccess Gateway" Action="/auth/login" ReturnUrl="@ReturnUrl" Error="@Error">
+    <AntiforgeryToken />
+</LoginCard>
+
+@code {
+    /// <summary>Original protected URL the operator was bounced from; round-tripped to POST /login.</summary>
+    [SupplyParameterFromQuery(Name = "returnUrl")]
+    private string? ReturnUrl { get; set; }
+
+    /// <summary>Failure message surfaced by POST /login after a failed authentication.</summary>
+    [SupplyParameterFromQuery(Name = "error")]
+    private string? Error { get; set; }
+}

src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/SettingsPage.razor

@@ -26,7 +26,7 @@ else
                     <tr><th scope="row">Run migrations</th><td>@Snapshot.Configuration.Authentication.RunMigrationsOnStartup</td></tr>
                     <tr><th scope="row">LDAP enabled</th><td>@Snapshot.Configuration.Ldap.Enabled</td></tr>
                     <tr><th scope="row">LDAP server</th><td>@Snapshot.Configuration.Ldap.Server:@Snapshot.Configuration.Ldap.Port</td></tr>
-                    <tr><th scope="row">LDAP TLS</th><td>@Snapshot.Configuration.Ldap.UseTls</td></tr>
+                    <tr><th scope="row">LDAP transport</th><td>@Snapshot.Configuration.Ldap.Transport</td></tr>
                     <tr><th scope="row">LDAP search base</th><td><code>@Snapshot.Configuration.Ldap.SearchBase</code></td></tr>
                     <tr><th scope="row">LDAP service account</th><td><code>@Snapshot.Configuration.Ldap.ServiceAccountDn</code></td></tr>
                     <tr><th scope="row">LDAP service password</th><td>@Snapshot.Configuration.Ldap.ServiceAccountPassword</td></tr>

src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/StatusBadge.razor

@@ -1,16 +1,16 @@
-<span class="chip @CssClass">@Text</span>
-
+@* Thin adapter: maps MxGateway runtime state text → kit StatusPill state.
+   The bespoke .chip rendering now lives in the kit; only the app's domain
+   text→state vocabulary remains here. Call sites (<StatusBadge Text="..."/>) unchanged. *@
+<StatusPill State="MapState(Text)">@Text</StatusPill>
 @code {
-    [Parameter]
-    public string? Text { get; set; }
+    [Parameter] public string? Text { get; set; }
 
-    private string CssClass => Text switch
+    private static StatusState MapState(string? text) => text switch
     {
-        "Ready" or "Healthy" or "Active" => "chip-ok",
-        "Creating" or "StartingWorker" or "WaitingForPipe" or "InitializingWorker" or "Closing" => "chip-warn",
-        "Stale" or "Degraded" => "chip-warn",
-        "Faulted" or "Unavailable" => "chip-bad",
-        "Closed" or "Revoked" or "Unknown" => "chip-idle",
-        _ => "chip-idle"
+        "Ready" or "Healthy" or "Active" => StatusState.Ok,
+        "Creating" or "StartingWorker" or "WaitingForPipe" or "InitializingWorker" or "Closing"
+            or "Stale" or "Degraded" => StatusState.Warn,
+        "Faulted" or "Unavailable" => StatusState.Bad,
+        _ => StatusState.Idle,
     };
 }

src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/_Imports.razor

@@ -10,4 +10,5 @@
 @using ZB.MOM.WW.MxGateway.Server.Dashboard.Components.Shared
 @using ZB.MOM.WW.MxGateway.Server.Security.Authorization
 @using ZB.MOM.WW.MxGateway.Server.Workers
+@using ZB.MOM.WW.Theme
 @using static Microsoft.AspNetCore.Components.Web.RenderMode

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardAlarmProviderStatus.cs

@@ -0,0 +1,101 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Server.Alarms;
+
+namespace ZB.MOM.WW.MxGateway.Server.Dashboard;
+
+/// <summary>
+///     Dashboard projection of an <see cref="AlarmProviderStatus" /> message
+///     carried on the alarm feed. Maps the protobuf provider mode / degraded
+///     flag into Bootstrap-only display fields so the Alarms page can render a
+///     status badge without touching protobuf types.
+/// </summary>
+public sealed record DashboardAlarmProviderStatus(
+    AlarmProviderMode Mode,
+    bool IsDegraded,
+    string Label,
+    string BadgeCssClass,
+    string Reason,
+    DateTimeOffset? SinceUtc)
+{
+    /// <summary>Badge label shown when the alarm-manager provider is healthy.</summary>
+    public const string AlarmManagerLabel = "Alarm Manager";
+
+    /// <summary>Badge label shown when the feed has fallen back to subtag monitoring.</summary>
+    public const string DegradedLabel = "Subtag monitoring (degraded)";
+
+    /// <summary>
+    ///     Badge label shown when the feed is in subtag monitoring because it was
+    ///     deliberately configured (<c>Fallback:Mode=ForceSubtag</c>), as opposed
+    ///     to an unexpected failover. A stable, intended state rather than a fault.
+    /// </summary>
+    public const string ForcedSubtagLabel = "Subtag monitoring (forced)";
+
+    private const string HealthyBadge = "bg-success";
+    private const string DegradedBadge = "bg-warning text-dark";
+
+    // Cyan/info badge: visually distinct from the amber failover-degraded badge —
+    // forced subtag is an intentional configuration, not an alarm-manager fault.
+    private const string ForcedSubtagBadge = "bg-info text-dark";
+
+    /// <summary>
+    ///     The default status assumed before the first provider-status message
+    ///     arrives: healthy alarm-manager mode.
+    /// </summary>
+    public static DashboardAlarmProviderStatus Healthy { get; } = new(
+        Mode: AlarmProviderMode.Alarmmgr,
+        IsDegraded: false,
+        Label: AlarmManagerLabel,
+        BadgeCssClass: HealthyBadge,
+        Reason: string.Empty,
+        SinceUtc: null);
+
+    /// <summary>Projects an alarm-feed provider-status payload into a dashboard badge model.</summary>
+    /// <param name="status">The provider-status payload from an <see cref="AlarmFeedMessage" />.</param>
+    /// <returns>The projected dashboard status.</returns>
+    public static DashboardAlarmProviderStatus FromProviderStatus(AlarmProviderStatus status)
+    {
+        ArgumentNullException.ThrowIfNull(status);
+
+        // Treat the explicit degraded flag and the SUBTAG mode as equivalent;
+        // the contract sets degraded=true whenever mode == SUBTAG, but guard
+        // against either being set independently.
+        bool degraded = status.Degraded || status.Mode == AlarmProviderMode.Subtag;
+        string reason = status.Reason ?? string.Empty;
+
+        // A configured ForceSubtag start carries the well-known forced reason and
+        // is a deliberate mode, not a failover — render it distinctly so an
+        // operator isn't alarmed by a "(degraded)" badge for an intended config.
+        bool forced = degraded
+            && status.Mode == AlarmProviderMode.Subtag
+            && string.Equals(reason, AlarmProviderReasons.ForcedSubtag, StringComparison.Ordinal);
+
+        string label = !degraded ? AlarmManagerLabel : forced ? ForcedSubtagLabel : DegradedLabel;
+        string badge = !degraded ? HealthyBadge : forced ? ForcedSubtagBadge : DegradedBadge;
+
+        return new DashboardAlarmProviderStatus(
+            Mode: status.Mode,
+            IsDegraded: degraded,
+            Label: label,
+            BadgeCssClass: badge,
+            Reason: reason,
+            SinceUtc: status.Since?.ToDateTimeOffset());
+    }
+
+    /// <summary>Projects an alarm-feed message into a dashboard badge model.</summary>
+    /// <param name="message">An alarm-feed message whose payload is a provider status.</param>
+    /// <returns>The projected dashboard status.</returns>
+    /// <exception cref="ArgumentException">The message does not carry a provider-status payload.</exception>
+    public static DashboardAlarmProviderStatus FromFeed(AlarmFeedMessage message)
+    {
+        ArgumentNullException.ThrowIfNull(message);
+
+        if (message.PayloadCase != AlarmFeedMessage.PayloadOneofCase.ProviderStatus)
+        {
+            throw new ArgumentException(
+                "Alarm-feed message does not carry a provider-status payload.",
+                nameof(message));
+        }
+
+        return FromProviderStatus(message.ProviderStatus);
+    }
+}

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardApiKeyManagementService.cs

@@ -1,5 +1,10 @@
 using System.Security.Claims;
+using System.Text.Json;
 using Microsoft.Data.Sqlite;
+using ZB.MOM.WW.Audit;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
+using ZB.MOM.WW.Auth.ApiKeys.Admin;
+using ZB.MOM.WW.MxGateway.Server.Security.Audit;
 using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
 using ZB.MOM.WW.MxGateway.Server.Security.Authorization;
 
@@ -7,12 +12,13 @@ namespace ZB.MOM.WW.MxGateway.Server.Dashboard;
 
 public sealed class DashboardApiKeyManagementService(
     DashboardApiKeyAuthorization authorization,
+    ApiKeyAdminCommands adminCommands,
     IApiKeyAdminStore adminStore,
-    IApiKeyAuditStore auditStore,
-    IApiKeySecretHasher hasher,
+    IAuditWriter auditWriter,
     IHttpContextAccessor httpContextAccessor) : IDashboardApiKeyManagementService
 {
     private const string UnauthorizedMessage = "Sign in with an authorized LDAP account to manage API keys.";
+    private const string PepperUnavailableMarker = "pepper unavailable";
 
     /// <summary>Determines whether the user can manage API keys.</summary>
     /// <param name="user">The authenticated user principal.</param>
@@ -42,28 +48,31 @@ public sealed class DashboardApiKeyManagementService(
         }
 
         string keyId = request.KeyId.Trim();
-        string secret = ApiKeySecretGenerator.Generate();
-        string apiKey = FormatApiKey(keyId, secret);
 
         try
         {
-            await adminStore.CreateAsync(
-                    new ApiKeyCreateRequest(
-                        KeyId: keyId,
-                        KeyPrefix: $"mxgw_{keyId}",
-                        SecretHash: hasher.HashSecret(secret),
-                        DisplayName: request.DisplayName.Trim(),
-                        Scopes: request.Scopes,
-                        Constraints: request.Constraints,
-                        CreatedUtc: DateTimeOffset.UtcNow),
+            // The shared command set generates the secret, hashes it with the pepper, persists the
+            // record and assembles the mxgw_<id>_<secret> token (shown once). It also appends its own
+            // "create-key" audit entry (now canonicalized through the IApiKeyAuditStore->IAuditWriter
+            // adapter); the dashboard layers a richer "dashboard-create-key" canonical AuditEvent
+            // (Target + CorrelationId + remote address) on top via IAuditWriter to preserve the
+            // dashboard audit vocabulary — both rows land in the canonical audit_event store.
+            CreateKeyResult created = await adminCommands.CreateKeyAsync(
+                    keyId,
+                    request.DisplayName.Trim(),
+                    request.Scopes,
+                    ApiKeyConstraintSerializer.Serialize(request.Constraints),
+                    RemoteAddress(),
                     cancellationToken)
                 .ConfigureAwait(false);
 
-            await AppendAuditAsync(keyId, "dashboard-create-key", null, cancellationToken).ConfigureAwait(false);
+            await WriteDashboardAuditAsync(user, keyId, "dashboard-create-key", null, cancellationToken).ConfigureAwait(false);
 
-            return DashboardApiKeyManagementResult.Success("API key created. Copy the key now; it will not be shown again.", apiKey);
+            return DashboardApiKeyManagementResult.Success(
+                "API key created. Copy the key now; it will not be shown again.",
+                created.Token);
         }
-        catch (ApiKeyPepperUnavailableException)
+        catch (InvalidOperationException exception) when (IsPepperUnavailable(exception))
         {
             return DashboardApiKeyManagementResult.Fail("API key pepper is not configured.");
         }
@@ -94,18 +103,19 @@ public sealed class DashboardApiKeyManagementService(
         }
 
         string normalizedKeyId = keyId.Trim();
-        bool revoked = await adminStore
-            .RevokeAsync(normalizedKeyId, DateTimeOffset.UtcNow, cancellationToken)
+        KeyActionResult result = await adminCommands
+            .RevokeKeyAsync(normalizedKeyId, RemoteAddress(), cancellationToken)
             .ConfigureAwait(false);
 
-        await AppendAuditAsync(
+        await WriteDashboardAuditAsync(
+                user,
                 normalizedKeyId,
                 "dashboard-revoke-key",
-                revoked ? "revoked" : "not-found-or-already-revoked",
+                result.Succeeded ? "revoked" : "not-found-or-already-revoked",
                 cancellationToken)
             .ConfigureAwait(false);
 
-        return revoked
+        return result.Succeeded
             ? DashboardApiKeyManagementResult.Success("API key revoked.")
             : DashboardApiKeyManagementResult.Fail("API key was not found or is already revoked.");
     }
@@ -131,27 +141,30 @@ public sealed class DashboardApiKeyManagementService(
         }
 
         string normalizedKeyId = keyId.Trim();
-        string secret = ApiKeySecretGenerator.Generate();
-        string apiKey = FormatApiKey(normalizedKeyId, secret);
 
         try
         {
-            bool rotated = await adminStore
-                .RotateAsync(normalizedKeyId, hasher.HashSecret(secret), DateTimeOffset.UtcNow, cancellationToken)
+            CreateKeyResult rotated = await adminCommands
+                .RotateKeyAsync(normalizedKeyId, RemoteAddress(), cancellationToken)
                 .ConfigureAwait(false);
 
-            await AppendAuditAsync(
+            bool succeeded = rotated.Token is not null;
+
+            await WriteDashboardAuditAsync(
+                    user,
                     normalizedKeyId,
                     "dashboard-rotate-key",
-                    rotated ? "rotated" : "not-found",
+                    succeeded ? "rotated" : "not-found",
                     cancellationToken)
                 .ConfigureAwait(false);
 
-            return rotated
-                ? DashboardApiKeyManagementResult.Success("API key rotated. Copy the key now; it will not be shown again.", apiKey)
+            return succeeded
+                ? DashboardApiKeyManagementResult.Success(
+                    "API key rotated. Copy the key now; it will not be shown again.",
+                    rotated.Token)
                 : DashboardApiKeyManagementResult.Fail("API key was not found.");
         }
-        catch (ApiKeyPepperUnavailableException)
+        catch (InvalidOperationException exception) when (IsPepperUnavailable(exception))
         {
             return DashboardApiKeyManagementResult.Fail("API key pepper is not configured.");
         }
@@ -182,7 +195,8 @@ public sealed class DashboardApiKeyManagementService(
             .DeleteAsync(normalizedKeyId, cancellationToken)
             .ConfigureAwait(false);
 
-        await AppendAuditAsync(
+        await WriteDashboardAuditAsync(
+                user,
                 normalizedKeyId,
                 "dashboard-delete-key",
                 deleted ? "deleted" : "not-found-or-active",
@@ -194,22 +208,92 @@ public sealed class DashboardApiKeyManagementService(
             : DashboardApiKeyManagementResult.Fail("API key was not found, or is still active. Revoke it before deleting.");
     }
 
-    private async Task AppendAuditAsync(
-        string? keyId,
-        string eventType,
-        string? details,
+    private string? RemoteAddress() =>
+        httpContextAccessor.HttpContext?.Connection.RemoteIpAddress?.ToString();
+
+    /// <summary>
+    /// Resolves the operator's username from the authenticated dashboard principal.
+    /// </summary>
+    /// <remarks>
+    /// The passed <paramref name="user"/> is preferred over the ambient HTTP context because it
+    /// is already in scope at every call site (the callers gate on <see cref="CanManage"/> using
+    /// it) and is unambiguous. Falls back to <see cref="IAuditActorAccessor.CurrentActor"/> for
+    /// defensive coverage, then to <c>"unknown"</c> when neither is available.
+    /// </remarks>
+    private static string ResolveOperatorActor(ClaimsPrincipal user)
+    {
+        // ZbClaimTypes.Username = "zb:username" — the canonical LDAP login name.
+        string? username = user.FindFirstValue(ZB.MOM.WW.Auth.AspNetCore.ZbClaimTypes.Username);
+        if (!string.IsNullOrWhiteSpace(username))
+        {
+            return username;
+        }
+
+        // Framework fallback: Identity.Name is driven by the nameClaimType on the ClaimsIdentity
+        // (set to ZbClaimTypes.Name = ClaimTypes.Name by DashboardAuthenticator → display name).
+        string? identityName = user.Identity?.Name;
+        if (!string.IsNullOrWhiteSpace(identityName))
+        {
+            return identityName;
+        }
+
+        return "unknown";
+    }
+
+    /// <summary>
+    /// Emits the dashboard's own canonical <see cref="AuditEvent"/> for a <c>dashboard-*</c> op
+    /// directly through the best-effort <see cref="IAuditWriter"/> (Task 2.3 #6). This is in
+    /// addition to the <c>create/revoke/rotate-key</c> event that <see cref="ApiKeyAdminCommands"/>
+    /// emits via the canonical-forwarding <c>IApiKeyAuditStore</c> adapter — the doubled-audit
+    /// behaviour is preserved, both rows now land in the canonical <c>audit_event</c> store.
+    /// </summary>
+    /// <remarks>
+    /// Phase 3 (Actor = operator principal): <c>Actor</c> is the LDAP operator who performed the
+    /// action (resolved from the <paramref name="user"/> principal); <c>Target</c> is the managed
+    /// API key id. This fixes the pre-Phase-3 semantic gap where both fields held the keyId.
+    /// </remarks>
+    private async Task WriteDashboardAuditAsync(
+        ClaimsPrincipal user,
+        string keyId,
+        string action,
+        string? detail,
         CancellationToken cancellationToken)
     {
-        await auditStore.AppendAsync(
-                new ApiKeyAuditEntry(
-                    KeyId: keyId,
-                    EventType: eventType,
-                    RemoteAddress: httpContextAccessor.HttpContext?.Connection.RemoteIpAddress?.ToString(),
-                    Details: details),
-                cancellationToken)
-            .ConfigureAwait(false);
+        AuditEvent auditEvent = new()
+        {
+            EventId = Guid.NewGuid(),
+            OccurredAtUtc = DateTimeOffset.UtcNow,
+            Actor = ResolveOperatorActor(user),
+            Action = action,
+            Outcome = AuditOutcome.Success,
+            Category = CanonicalForwardingApiKeyAuditStore.ApiKeyCategory,
+            Target = keyId,
+            SourceNode = RemoteAddress(),
+            CorrelationId = ParseCorrelationId(),
+            DetailsJson = WrapDetail(detail),
+        };
+
+        await auditWriter.WriteAsync(auditEvent, cancellationToken).ConfigureAwait(false);
     }
 
+    /// <summary>
+    /// Derives a correlation id from the ASP.NET Core request trace identifier when it is a
+    /// well-formed GUID; otherwise null (the default <c>HttpContext.TraceIdentifier</c> is the
+    /// connection:request form, not a GUID, so it correlates to null rather than fabricating one).
+    /// </summary>
+    private Guid? ParseCorrelationId() =>
+        Guid.TryParse(httpContextAccessor.HttpContext?.TraceIdentifier, out Guid correlationId)
+            ? correlationId
+            : null;
+
+    private static string? WrapDetail(string? detail) =>
+        detail is null
+            ? null
+            : JsonSerializer.Serialize(new Dictionary<string, string> { ["detail"] = detail });
+
+    private static bool IsPepperUnavailable(InvalidOperationException exception) =>
+        exception.Message.Contains(PepperUnavailableMarker, StringComparison.OrdinalIgnoreCase);
+
     private static string? ValidateCreateRequest(DashboardApiKeyManagementRequest request)
     {
         string? keyIdValidation = ValidateKeyId(request.KeyId);
@@ -248,9 +332,4 @@ public sealed class DashboardApiKeyManagementService(
             ? null
             : "API key id may contain only letters, numbers, periods, and hyphens.";
     }
-
-    private static string FormatApiKey(string keyId, string secret)
-    {
-        return $"mxgw_{keyId}_{secret}";
-    }
 }

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardAuthenticator.cs

@@ -1,14 +1,26 @@
 using System.Security.Claims;
-using System.Text;
-using Microsoft.Extensions.Options;
-using ZB.MOM.WW.MxGateway.Server.Configuration;
-using ZB.MOM.WW.MxGateway.Server.Security.Authorization;
-using Novell.Directory.Ldap;
+using ZB.MOM.WW.Auth.Abstractions.Ldap;
+using ZB.MOM.WW.Auth.Abstractions.Roles;
+using ZB.MOM.WW.Auth.AspNetCore;
 
 namespace ZB.MOM.WW.MxGateway.Server.Dashboard;
 
+/// <summary>
+/// Authenticates interactive dashboard logins against LDAP. The bind/search
+/// mechanics are delegated to the shared <see cref="ILdapAuthService"/>
+/// (<c>ZB.MOM.WW.Auth.Ldap</c>), which performs bind-then-search, fails closed,
+/// and never throws — returning the user's display name and LDAP groups on
+/// success. This class keeps the dashboard-specific policy: groups are resolved
+/// to dashboard roles via <see cref="IGroupRoleMapper{TRole}"/>, a login with no
+/// matching role is denied, and the resulting <see cref="ClaimsPrincipal"/> is
+/// shaped exactly as before (see <see cref="CreatePrincipal"/>).
+/// </summary>
+/// <param name="ldapAuthService">Shared LDAP bind-then-search provider.</param>
+/// <param name="roleMapper">Maps LDAP groups to dashboard roles (Task 1.1 seam).</param>
+/// <param name="logger">Logger for diagnostic, credential-free login outcomes.</param>
 public sealed class DashboardAuthenticator(
-    IOptions<GatewayOptions> options,
+    ILdapAuthService ldapAuthService,
+    IGroupRoleMapper<string> roleMapper,
     ILogger<DashboardAuthenticator> logger) : IDashboardAuthenticator
 {
     private const string GenericFailureMessage = "The username or password is invalid, or the user is not authorized.";
@@ -19,240 +31,72 @@ public sealed class DashboardAuthenticator(
         string? password,
         CancellationToken cancellationToken)
     {
-        LdapOptions ldapOptions = options.Value.Ldap;
-        DashboardOptions dashboardOptions = options.Value.Dashboard;
-        if (!ldapOptions.Enabled
-            || string.IsNullOrWhiteSpace(username)
-            || string.IsNullOrWhiteSpace(password))
-        {
-            return DashboardAuthenticationResult.Fail(GenericFailureMessage);
-        }
-
-        if (!ldapOptions.UseTls && !ldapOptions.AllowInsecureLdap)
+        if (string.IsNullOrWhiteSpace(username) || string.IsNullOrWhiteSpace(password))
         {
             return DashboardAuthenticationResult.Fail(GenericFailureMessage);
         }
 
         string normalizedUsername = username.Trim();
 
-        try
+        // The shared service owns connect/bind/search and the fail-closed contract:
+        // it returns Fail(Disabled) when LDAP is off, enforces TLS-or-AllowInsecure via
+        // its startup validator, and never throws. We only translate its outcome into a
+        // dashboard principal here.
+        LdapAuthResult ldapResult = await ldapAuthService
+            .AuthenticateAsync(normalizedUsername, password, cancellationToken)
+            .ConfigureAwait(false);
+
+        if (!ldapResult.Succeeded)
         {
-            using LdapConnection connection = new();
-            connection.SecureSocketLayer = ldapOptions.UseTls;
-
-            await Task.Run(
-                    () => connection.Connect(ldapOptions.Server, ldapOptions.Port),
-                    cancellationToken)
-                .ConfigureAwait(false);
-
-            await BindServiceAccountAsync(connection, ldapOptions, cancellationToken).ConfigureAwait(false);
-            LdapEntry? candidate = await SearchUserAsync(
-                    connection,
-                    ldapOptions,
-                    normalizedUsername,
-                    cancellationToken)
-                .ConfigureAwait(false);
-
-            if (candidate is null)
-            {
-                return DashboardAuthenticationResult.Fail(GenericFailureMessage);
-            }
-
-            await Task.Run(
-                    () => connection.Bind(candidate.Dn, password),
-                    cancellationToken)
-                .ConfigureAwait(false);
-
-            await BindServiceAccountAsync(connection, ldapOptions, cancellationToken).ConfigureAwait(false);
-            LdapEntry? authenticatedEntry = await SearchUserAsync(
-                    connection,
-                    ldapOptions,
-                    normalizedUsername,
-                    cancellationToken)
-                .ConfigureAwait(false);
-
-            if (authenticatedEntry is null)
-            {
-                return DashboardAuthenticationResult.Fail(GenericFailureMessage);
-            }
-
-            string displayName = ReadAttribute(authenticatedEntry, ldapOptions.DisplayNameAttribute)
-                ?? normalizedUsername;
-            IReadOnlyList<string> groups = ReadAttributeValues(authenticatedEntry, ldapOptions.GroupAttribute);
-
-            IReadOnlyList<string> roles = MapGroupsToRoles(groups, dashboardOptions.GroupToRole);
-            if (roles.Count == 0)
-            {
-                logger.LogInformation(
-                    "LDAP dashboard login denied for user {User}: no GroupToRole mapping matched their LDAP groups.",
-                    normalizedUsername);
-
-                return DashboardAuthenticationResult.Fail(GenericFailureMessage);
-            }
-
-            return DashboardAuthenticationResult.Success(CreatePrincipal(
-                normalizedUsername,
-                displayName,
-                groups,
-                roles));
+            return DashboardAuthenticationResult.Fail(GenericFailureMessage);
         }
-        catch (OperationCanceledException)
-        {
-            throw;
-        }
-        catch (LdapException ex)
+
+        GroupRoleMapping<string> mapping = await roleMapper
+            .MapAsync(ldapResult.Groups, cancellationToken)
+            .ConfigureAwait(false);
+
+        IReadOnlyList<string> roles = mapping.Roles;
+        if (roles.Count == 0)
         {
+            // Preserve the long-standing "no roles matched -> login denied" rule.
             logger.LogInformation(
-                "LDAP dashboard login rejected for user {User}: result code {ResultCode}.",
-                normalizedUsername,
-                ex.ResultCode);
+                "LDAP dashboard login denied for user {User}: no GroupToRole mapping matched their LDAP groups.",
+                ldapResult.Username);
 
             return DashboardAuthenticationResult.Fail(GenericFailureMessage);
         }
-        catch (Exception ex)
-        {
-            logger.LogError(ex, "Unexpected LDAP dashboard login error for user {User}.", normalizedUsername);
 
-            return DashboardAuthenticationResult.Fail(GenericFailureMessage);
-        }
-    }
-
-    /// <summary>Escapes special characters in LDAP filter strings.</summary>
-    /// <param name="value">The string value to escape.</param>
-    internal static string EscapeLdapFilter(string value)
-    {
-        StringBuilder builder = new(value.Length);
-        foreach (char character in value)
-        {
-            builder.Append(character switch
-            {
-                '\\' => @"\5c",
-                '*' => @"\2a",
-                '(' => @"\28",
-                ')' => @"\29",
-                '\0' => @"\00",
-                _ => character.ToString()
-            });
-        }
-
-        return builder.ToString();
+        return DashboardAuthenticationResult.Success(CreatePrincipal(
+            ldapResult.Username,
+            ldapResult.DisplayName,
+            ldapResult.Groups,
+            roles));
     }
 
     /// <summary>
-    /// Maps the user's LDAP groups to dashboard roles. A user can pick up
-    /// multiple roles; Admin and Viewer are the only legal values. Returns
-    /// an empty list when no group matches (caller rejects the login).
+    /// Builds the dashboard <see cref="ClaimsPrincipal"/> from the LDAP outcome.
     /// </summary>
-    /// <param name="groups">The collection of LDAP groups the user belongs to.</param>
-    /// <param name="groupToRole">The mapping from group names to dashboard role names.</param>
-    internal static IReadOnlyList<string> MapGroupsToRoles(
-        IEnumerable<string> groups,
-        IReadOnlyDictionary<string, string> groupToRole)
-    {
-        if (groupToRole.Count == 0)
-        {
-            return [];
-        }
-
-        HashSet<string> roles = new(StringComparer.Ordinal);
-        foreach (string group in groups)
-        {
-            string normalizedGroup = group.Trim();
-
-            // Lookup precedence (Server-040): the full literal group string is
-            // tried first; only if that misses do we fall back to the leading
-            // RDN value (e.g. "GwAdmin" extracted from
-            // "ou=GwAdmin,ou=groups,..."). The map's comparer is
-            // OrdinalIgnoreCase (see DashboardOptions.GroupToRole), so e.g.
-            // "GwAdmin" and "gwadmin" both match.
-            if (groupToRole.TryGetValue(normalizedGroup, out string? mapped)
-                || groupToRole.TryGetValue(ExtractFirstRdnValue(normalizedGroup), out mapped))
-            {
-                roles.Add(mapped);
-            }
-        }
-
-        return [.. roles];
-    }
-
-    /// <summary>Extracts the first RDN value from a distinguished name.</summary>
-    /// <param name="distinguishedName">The LDAP distinguished name.</param>
-    internal static string ExtractFirstRdnValue(string distinguishedName)
-    {
-        int equalsIndex = distinguishedName.IndexOf('=');
-        if (equalsIndex < 0)
-        {
-            return distinguishedName;
-        }
-
-        int valueStart = equalsIndex + 1;
-        int commaIndex = distinguishedName.IndexOf(',', valueStart);
-
-        return commaIndex > valueStart
-            ? distinguishedName[valueStart..commaIndex]
-            : distinguishedName[valueStart..];
-    }
-
-    private static Task BindServiceAccountAsync(
-        LdapConnection connection,
-        LdapOptions ldapOptions,
-        CancellationToken cancellationToken)
-    {
-        return Task.Run(
-            () => connection.Bind(ldapOptions.ServiceAccountDn, ldapOptions.ServiceAccountPassword),
-            cancellationToken);
-    }
-
-    private static async Task<LdapEntry?> SearchUserAsync(
-        LdapConnection connection,
-        LdapOptions ldapOptions,
-        string username,
-        CancellationToken cancellationToken)
-    {
-        string filter = $"({ldapOptions.UserNameAttribute}={EscapeLdapFilter(username)})";
-        ILdapSearchResults results = await Task.Run(
-                () => connection.Search(
-                    ldapOptions.SearchBase,
-                    LdapConnection.ScopeSub,
-                    filter,
-                    attrs: null,
-                    typesOnly: false),
-                cancellationToken)
-            .ConfigureAwait(false);
-
-        LdapEntry? entry = null;
-        while (results.HasMore())
-        {
-            LdapEntry next = results.Next();
-            if (entry is not null)
-            {
-                return null;
-            }
-
-            entry = next;
-        }
-
-        return entry;
-    }
-
-    private static string? ReadAttribute(LdapEntry entry, string attributeName)
-    {
-        return ReadLdapAttribute(entry, attributeName)?.StringValue;
-    }
-
-    private static IReadOnlyList<string> ReadAttributeValues(LdapEntry entry, string attributeName)
-    {
-        LdapAttribute? attribute = ReadLdapAttribute(entry, attributeName);
-        return attribute?.StringValueArray ?? [];
-    }
-
-    private static LdapAttribute? ReadLdapAttribute(LdapEntry entry, string attributeName)
-    {
-        return entry.GetAttribute(attributeName)
-            ?? entry.GetAttribute(attributeName.ToLowerInvariant())
-            ?? entry.GetAttribute(attributeName.ToUpperInvariant());
-    }
-
+    /// <param name="username">
+    /// The (trimmed) login name. Emitted as <see cref="ClaimTypes.NameIdentifier"/> (kept for
+    /// back-compat reads) and as the canonical <see cref="ZbClaimTypes.Username"/> ("zb:username").
+    /// </param>
+    /// <param name="displayName">
+    /// The user's display name. Emitted as <see cref="ZbClaimTypes.Name"/> (= <see cref="ClaimTypes.Name"/>
+    /// so <c>Identity.Name</c> resolves) and as <see cref="ZbClaimTypes.DisplayName"/> ("zb:displayname")
+    /// for cross-app consistency.
+    /// </param>
+    /// <param name="groups">
+    /// The user's LDAP groups, as returned by <see cref="ILdapAuthService"/>. NOTE
+    /// (review C1): these are <b>already-normalized short RDN names</b> (e.g.
+    /// <c>GwAdmin</c>), not raw distinguished names. The shared
+    /// <c>ZB.MOM.WW.Auth.Ldap</c> provider strips each group DN to its first RDN
+    /// value before returning it, so the <see cref="DashboardAuthenticationDefaults.LdapGroupClaimType"/>
+    /// claim carries the short name. This differs from the pre-cutover behaviour,
+    /// which surfaced the raw <c>memberOf</c> values (full DNs) on the claim; the
+    /// claim is informational only (no policy or UI reads its value — authorization
+    /// is role-based), so the shape change is non-breaking for dashboard consumers.
+    /// </param>
+    /// <param name="roles">The dashboard roles resolved from <paramref name="groups"/>.</param>
     private static ClaimsPrincipal CreatePrincipal(
         string username,
         string displayName,
@@ -261,11 +105,21 @@ public sealed class DashboardAuthenticator(
     {
         List<Claim> claims =
         [
+            // Keep NameIdentifier so any existing read-site that uses it continues to work.
             new Claim(ClaimTypes.NameIdentifier, username),
-            new Claim(ClaimTypes.Name, displayName),
+            // Canonical login-username claim (Task 1.5).
+            new Claim(ZbClaimTypes.Username, username),
+            // ZbClaimTypes.Name == ClaimTypes.Name — drives Identity.Name resolution.
+            new Claim(ZbClaimTypes.Name, displayName),
+            // Canonical display-name claim for cross-app consistency (Task 1.5).
+            new Claim(ZbClaimTypes.DisplayName, displayName),
         ];
 
-        claims.AddRange(roles.Select(role => new Claim(ClaimTypes.Role, role)));
+        // ZbClaimTypes.Role == ClaimTypes.Role — drives IsInRole and [Authorize(Roles=...)].
+        claims.AddRange(roles.Select(role => new Claim(ZbClaimTypes.Role, role)));
+        // Groups are short RDN names from ILdapAuthService (see param doc above), so
+        // this claim value is the short group name, not the original DN.
+        // LdapGroupClaimType is MxGateway-specific ("mxgateway:ldap_group") — no ZbClaimType for groups.
         claims.AddRange(groups.Select(group => new Claim(
             DashboardAuthenticationDefaults.LdapGroupClaimType,
             group)));
@@ -273,8 +127,8 @@ public sealed class DashboardAuthenticator(
         ClaimsIdentity claimsIdentity = new(
             claims,
             DashboardAuthenticationDefaults.AuthenticationScheme,
-            ClaimTypes.Name,
-            ClaimTypes.Role);
+            ZbClaimTypes.Name,
+            ZbClaimTypes.Role);
 
         return new ClaimsPrincipal(claimsIdentity);
     }

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardEndpointRouteBuilderExtensions.cs

@@ -1,7 +1,6 @@
 using System.Text.Encodings.Web;
 using Microsoft.AspNetCore.Antiforgery;
 using Microsoft.AspNetCore.Authentication;
-using Microsoft.AspNetCore.Http.HttpResults;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
 using ZB.MOM.WW.MxGateway.Server.Dashboard.Components;
 using ZB.MOM.WW.MxGateway.Server.Dashboard.Hubs;
@@ -25,14 +24,19 @@ public static class DashboardEndpointRouteBuilderExtensions
             return endpoints;
         }
 
-        endpoints.MapGet(
-                "/login",
-                (HttpContext httpContext, IAntiforgery antiforgery) => GetLoginAsync(httpContext, antiforgery))
-            .AllowAnonymous()
-            .WithName("DashboardLogin");
-
+        // GET /login is served by the [AllowAnonymous] Blazor <Login> component
+        // (Components/Pages/Login.razor → @page "/login"), which renders the shared
+        // kit's <LoginCard>. Its [AllowAnonymous] attribute overrides the
+        // RequireAuthorization(ViewerPolicy) that MapRazorComponents<App>() applies,
+        // so the cookie scheme's LoginPath="/login" redirect resolves for anonymous users.
+        //
+        // The credential POST is mapped to /auth/login, NOT /login. The @page "/login"
+        // Razor Components endpoint matches ALL HTTP methods, so a MapPost("/login") shared
+        // the "/login" route with it and every POST threw AmbiguousMatchException (HTTP 500).
+        // A distinct /auth/login path (as ScadaBridge does) keeps the GET page and the POST
+        // handler on separate routes. The <LoginCard Action="/auth/login"> form posts here.
         endpoints.MapPost(
-                "/login",
+                "/auth/login",
                 (HttpContext httpContext, IAntiforgery antiforgery, IDashboardAuthenticator authenticator) =>
                     PostLoginAsync(httpContext, antiforgery, authenticator))
             .AllowAnonymous()
@@ -92,17 +96,6 @@ public static class DashboardEndpointRouteBuilderExtensions
         return endpoints;
     }
 
-    private static Task<ContentHttpResult> GetLoginAsync(
-        HttpContext httpContext,
-        IAntiforgery antiforgery)
-    {
-        string returnUrl = SanitizeReturnUrl(httpContext.Request.Query["returnUrl"].ToString());
-
-        return Task.FromResult(TypedResults.Content(
-            RenderLoginPage(httpContext, antiforgery, returnUrl, failureMessage: null),
-            "text/html"));
-    }
-
     private static async Task<IResult> PostLoginAsync(
         HttpContext httpContext,
         IAntiforgery antiforgery,
@@ -124,10 +117,13 @@ public static class DashboardEndpointRouteBuilderExtensions
 
         if (!result.Succeeded || result.Principal is null)
         {
-            return TypedResults.Content(
-                RenderLoginPage(httpContext, antiforgery, returnUrl, result.FailureMessage),
-                "text/html",
-                statusCode: StatusCodes.Status401Unauthorized);
+            // Round-trip the failure back to the anonymous Blazor /login page, carrying
+            // the (sanitized) returnUrl so a successful retry still lands on the target.
+            string failureMessage = result.FailureMessage
+                ?? "The username or password is invalid, or the user is not authorized.";
+            return Results.Redirect(
+                $"/login?error={Uri.EscapeDataString(failureMessage)}"
+                + $"&returnUrl={Uri.EscapeDataString(returnUrl)}");
         }
 
         await httpContext
@@ -158,42 +154,6 @@ public static class DashboardEndpointRouteBuilderExtensions
         return Results.LocalRedirect("/login");
     }
 
-    private static string RenderLoginPage(
-        HttpContext httpContext,
-        IAntiforgery antiforgery,
-        string returnUrl,
-        string? failureMessage)
-    {
-        AntiforgeryTokenSet tokens = antiforgery.GetAndStoreTokens(httpContext);
-        string requestToken = tokens.RequestToken ?? string.Empty;
-        string alert = string.IsNullOrWhiteSpace(failureMessage)
-            ? string.Empty
-            : $"<p class=\"alert alert-danger\" role=\"alert\">{HtmlEncoder.Default.Encode(failureMessage)}</p>";
-
-        string body = $"""
-            <section class="dashboard-login">
-                {alert}
-                <form method="post" action="/login" class="card login-card">
-                    <div class="card-body">
-                        <input name="{tokens.FormFieldName}" type="hidden" value="{HtmlEncoder.Default.Encode(requestToken)}" />
-                        <input name="returnUrl" type="hidden" value="{HtmlEncoder.Default.Encode(returnUrl)}" />
-                        <div class="mb-3">
-                            <label for="username" class="form-label">Username</label>
-                            <input id="username" name="username" type="text" autocomplete="username" class="form-control" />
-                        </div>
-                        <div class="mb-3">
-                            <label for="password" class="form-label">Password</label>
-                            <input id="password" name="password" type="password" autocomplete="current-password" class="form-control" />
-                        </div>
-                        <button type="submit" class="btn btn-primary">Sign in</button>
-                    </div>
-                </form>
-            </section>
-            """;
-
-        return RenderPage("Dashboard Sign In", heading: null, body);
-    }
-
     private static string RenderPage(string title, string body)
         => RenderPage(title, heading: title, body);
 
@@ -215,7 +175,8 @@ public static class DashboardEndpointRouteBuilderExtensions
                 <meta name="viewport" content="width=device-width, initial-scale=1" />
                 <title>{HtmlEncoder.Default.Encode(title)}</title>
                 <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css" />
-                <link rel="stylesheet" href="/css/theme.css" />
+                <link rel="stylesheet" href="/_content/ZB.MOM.WW.Theme/css/theme.css" />
+                <link rel="stylesheet" href="/_content/ZB.MOM.WW.Theme/css/layout.css" />
                 <link rel="stylesheet" href="/css/site.css" />
             </head>
             <body class="dashboard-body">

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardGroupRoleMapper.cs

@@ -0,0 +1,31 @@
+using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Auth.Abstractions.Roles;
+using ZB.MOM.WW.MxGateway.Server.Configuration;
+
+namespace ZB.MOM.WW.MxGateway.Server.Dashboard;
+
+/// <summary>
+/// Shared-Auth <see cref="IGroupRoleMapper{TRole}"/> seam over the dashboard's
+/// LDAP-group → role mapping. Roles are plain strings
+/// (<see cref="DashboardRoles.Admin"/> / <see cref="DashboardRoles.Viewer"/>),
+/// so <c>TRole</c> is <see cref="string"/>. The mapping rules (full-DN first,
+/// leading-RDN fallback, case-insensitive) live in
+/// <see cref="DashboardGroupRoleMapping"/>, shared with
+/// <see cref="DashboardAuthenticator"/> so behaviour stays identical.
+/// </summary>
+/// <param name="options">Gateway options supplying the dashboard GroupToRole map.</param>
+public sealed class DashboardGroupRoleMapper(IOptions<GatewayOptions> options)
+    : IGroupRoleMapper<string>
+{
+    /// <inheritdoc />
+    public Task<GroupRoleMapping<string>> MapAsync(
+        IReadOnlyList<string> groups,
+        CancellationToken ct)
+    {
+        IReadOnlyList<string> roles = DashboardGroupRoleMapping.MapGroupsToRoles(
+            groups,
+            options.Value.Dashboard.GroupToRole);
+
+        return Task.FromResult(new GroupRoleMapping<string>(roles, Scope: null));
+    }
+}

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardGroupRoleMapping.cs

@@ -0,0 +1,79 @@
+namespace ZB.MOM.WW.MxGateway.Server.Dashboard;
+
+/// <summary>
+/// Single source of truth for mapping a user's LDAP groups to dashboard roles.
+/// Both <see cref="DashboardAuthenticator"/> (the existing login flow) and
+/// <see cref="DashboardGroupRoleMapper"/> (the shared-Auth
+/// <see cref="ZB.MOM.WW.Auth.Abstractions.Roles.IGroupRoleMapper{TRole}"/> seam)
+/// delegate here so the precedence and case rules stay identical.
+/// </summary>
+internal static class DashboardGroupRoleMapping
+{
+    /// <summary>
+    /// Maps the user's LDAP groups to dashboard roles. A user can pick up
+    /// multiple roles; Admin and Viewer are the only legal values. Returns
+    /// an empty list when no group matches (caller rejects the login).
+    /// </summary>
+    /// <param name="groups">The collection of LDAP groups the user belongs to.</param>
+    /// <param name="groupToRole">The mapping from group names to dashboard role names.</param>
+    internal static IReadOnlyList<string> MapGroupsToRoles(
+        IEnumerable<string> groups,
+        IReadOnlyDictionary<string, string> groupToRole)
+    {
+        if (groupToRole.Count == 0)
+        {
+            return [];
+        }
+
+        HashSet<string> roles = new(StringComparer.Ordinal);
+        foreach (string group in groups)
+        {
+            string normalizedGroup = group.Trim();
+
+            // Lookup precedence (Server-040): the full literal group string is
+            // tried first; only if that misses do we fall back to the leading
+            // RDN value (e.g. "GwAdmin" extracted from
+            // "ou=GwAdmin,ou=groups,..."). The map's comparer is
+            // OrdinalIgnoreCase (see DashboardOptions.GroupToRole), so e.g.
+            // "GwAdmin" and "gwadmin" both match.
+            //
+            // Review C1: with the shared ZB.MOM.WW.Auth.Ldap provider, groups
+            // arrive here already stripped to short RDN names (the library calls
+            // FirstRdnValue before returning them). So through the live login path
+            // the full-string branch only ever sees short names and the RDN
+            // fallback is effectively a no-op — they collapse to the same key.
+            // The fallback is retained because this mapping is also reachable
+            // directly via the IGroupRoleMapper<string> seam (DashboardGroupRoleMapper),
+            // where a caller could still pass a full DN. CONSEQUENCE: configuring a
+            // full-DN GroupToRole *key* (e.g. "ou=GwAdmin,ou=groups,...") is
+            // UNSUPPORTED with the shared library — the incoming group is a short
+            // name, so it will never equal a full-DN key. Keep GroupToRole keys as
+            // short group names.
+            if (groupToRole.TryGetValue(normalizedGroup, out string? mapped)
+                || groupToRole.TryGetValue(ExtractFirstRdnValue(normalizedGroup), out mapped))
+            {
+                roles.Add(mapped);
+            }
+        }
+
+        return [.. roles];
+    }
+
+    /// <summary>Extracts the first RDN value from a distinguished name.</summary>
+    /// <param name="distinguishedName">The LDAP distinguished name.</param>
+    internal static string ExtractFirstRdnValue(string distinguishedName)
+    {
+        int equalsIndex = distinguishedName.IndexOf('=');
+        if (equalsIndex < 0)
+        {
+            return distinguishedName;
+        }
+
+        int valueStart = equalsIndex + 1;
+        int commaIndex = distinguishedName.IndexOf(',', valueStart);
+
+        return commaIndex > valueStart
+            ? distinguishedName[valueStart..commaIndex]
+            : distinguishedName[valueStart..];
+    }
+}

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardRoles.cs

@@ -8,8 +8,10 @@ public static class DashboardRoles
 {
     /// <summary>
     /// Read-write access: API-key CRUD, settings, any state-changing UI.
+    /// Canonical role value (Task 1.7); formerly <c>"Admin"</c> — pure value
+    /// rename, the operations this role authorizes are unchanged.
     /// </summary>
-    public const string Admin = "Admin";
+    public const string Admin = "Administrator";
 
     /// <summary>
     /// Read-only access: all pages render but write affordances are hidden.

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardServiceCollectionExtensions.cs

@@ -1,8 +1,12 @@
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.AspNetCore.Authentication.Cookies;
 using Microsoft.AspNetCore.Authorization;
+using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Auth.Abstractions.Roles;
+using ZB.MOM.WW.Auth.AspNetCore;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
+using ZB.MOM.WW.MxGateway.Server.Security.Audit;
 
 namespace ZB.MOM.WW.MxGateway.Server.Dashboard;
 
@@ -15,11 +19,25 @@ public static class DashboardServiceCollectionExtensions
     /// Registers all dashboard services, authentication, and Razor components.
     /// </summary>
     /// <param name="services">Service collection to register services.</param>
-    public static IServiceCollection AddGatewayDashboard(this IServiceCollection services)
+    /// <param name="configuration">
+    /// Application configuration, used to bind the shared LDAP provider's options
+    /// from the <c>MxGateway:Ldap</c> section.
+    /// </param>
+    public static IServiceCollection AddGatewayDashboard(
+        this IServiceCollection services,
+        IConfiguration configuration)
     {
+        // Dashboard logins delegate bind/search to the shared ZB.MOM.WW.Auth.Ldap
+        // provider. Its LdapOptions bind straight from MxGateway:Ldap (the gateway's
+        // LdapOptions field names match the shared options: Transport / AllowInsecure /
+        // SearchBase / ServiceAccount* / *Attribute). AddZbLdapAuth also adds a
+        // ValidateOnStart() so an insecure-transport misconfiguration fails fast at boot.
+        services.AddZbLdapAuth(configuration, "MxGateway:Ldap");
+
         services.AddSingleton<IDashboardSnapshotService, DashboardSnapshotService>();
         services.AddSingleton<IDashboardLiveDataService, DashboardLiveDataService>();
         services.AddSingleton<IDashboardAuthenticator, DashboardAuthenticator>();
+        services.AddSingleton<IGroupRoleMapper<string>, DashboardGroupRoleMapper>();
         services.AddSingleton<DashboardApiKeyAuthorization>();
         services.AddSingleton<IDashboardApiKeyManagementService, DashboardApiKeyManagementService>();
         services.AddSingleton<IDashboardSessionAdminService, DashboardSessionAdminService>();
@@ -30,6 +48,7 @@ public static class DashboardServiceCollectionExtensions
         services.AddHostedService<Hubs.DashboardSnapshotPublisher>();
         services.AddHostedService<Hubs.AlarmsHubPublisher>();
         services.AddHttpContextAccessor();
+        services.AddSingleton<IAuditActorAccessor, HttpAuditActorAccessor>();
         services.AddAntiforgery();
         services.AddCascadingAuthenticationState();
         services.AddRazorComponents()
@@ -40,29 +59,42 @@ public static class DashboardServiceCollectionExtensions
             .AddAuthentication(DashboardAuthenticationDefaults.AuthenticationScheme)
             .AddCookie(DashboardAuthenticationDefaults.AuthenticationScheme, cookieOptions =>
             {
+                // Hardened defaults (HttpOnly, SameSite=Strict, SecurePolicy, SlidingExpiration,
+                // ExpireTimeSpan) via the shared ZbCookieDefaults.Apply. requireHttps is set to
+                // its default (true / Always) here and overridden per-environment by the
+                // PostConfigure below; the 8-hour idle timeout is preserved (not the 30-min default).
+                ZbCookieDefaults.Apply(cookieOptions, requireHttps: true, idleTimeout: TimeSpan.FromHours(8));
+                // Cookie name, path, and redirect paths are MxGateway-specific — set after Apply
+                // so they are never overwritten by the shared helper (Apply intentionally skips name).
+                // This is the canonical default; it is overridden per-environment from
+                // DashboardOptions.CookieName by the PostConfigure below.
                 cookieOptions.Cookie.Name = DashboardAuthenticationDefaults.CookieName;
-                cookieOptions.Cookie.HttpOnly = true;
-                cookieOptions.Cookie.SameSite = SameSiteMode.Strict;
-                // SecurePolicy is bound via PostConfigure below so it can honour
-                // DashboardOptions.RequireHttpsCookie (default Always; dev HTTP
-                // deployments set RequireHttpsCookie=false to use SameAsRequest).
                 cookieOptions.Cookie.Path = "/";
                 cookieOptions.LoginPath = "/login";
                 cookieOptions.LogoutPath = "/logout";
                 cookieOptions.AccessDeniedPath = "/denied";
-                cookieOptions.ExpireTimeSpan = TimeSpan.FromHours(8);
-                cookieOptions.SlidingExpiration = true;
             })
             .AddScheme<AuthenticationSchemeOptions, HubTokenAuthenticationHandler>(
                 DashboardAuthenticationDefaults.HubAuthenticationScheme,
                 _ => { });
 
+        // Honour DashboardOptions.RequireHttpsCookie (default true / Always; set false for dev
+        // HTTP deployments → SameAsRequest) and the optional per-environment cookie-name
+        // override. Both run after the inline AddCookie config above, so they win.
         services.AddOptions<CookieAuthenticationOptions>(DashboardAuthenticationDefaults.AuthenticationScheme)
             .Configure<IOptions<GatewayOptions>>((cookieOptions, gatewayOptions) =>
             {
                 cookieOptions.Cookie.SecurePolicy = gatewayOptions.Value.Dashboard.RequireHttpsCookie
                     ? CookieSecurePolicy.Always
                     : CookieSecurePolicy.SameAsRequest;
+
+                // Config-driven cookie name (MxGateway:Dashboard:CookieName). Null/blank keeps
+                // the canonical default set above, so a misconfiguration cannot unname the cookie.
+                var cookieName = gatewayOptions.Value.Dashboard.CookieName;
+                if (!string.IsNullOrWhiteSpace(cookieName))
+                {
+                    cookieOptions.Cookie.Name = cookieName;
+                }
             });
 
         services.AddAuthorization(authorization =>

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSnapshotService.cs

@@ -2,6 +2,7 @@ using System.Runtime.CompilerServices;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Logging.Abstractions;
 using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
 using ZB.MOM.WW.MxGateway.Server.Galaxy;
 using ZB.MOM.WW.MxGateway.Server.Metrics;
@@ -194,6 +195,7 @@ public sealed class DashboardSnapshotService : IDashboardSnapshotService
             new("mxgateway.workers.exited", snapshot.WorkerExits),
             new("mxgateway.heartbeats.failed", snapshot.HeartbeatFailures),
             new("mxgateway.grpc.streams.disconnected", snapshot.StreamDisconnects),
+            new("mxgateway.alarms.provider_switches", snapshot.AlarmProviderSwitchCount),
         ];
 
         metrics.AddRange(snapshot.CommandFailuresByMethod
@@ -242,7 +244,7 @@ public sealed class DashboardSnapshotService : IDashboardSnapshotService
                     KeyId: key.KeyId,
                     DisplayName: key.DisplayName,
                     Scopes: key.Scopes,
-                    Constraints: key.Constraints,
+                    Constraints: ApiKeyConstraintSerializer.Deserialize(key.ConstraintsJson),
                     CreatedUtc: key.CreatedUtc,
                     LastUsedUtc: key.LastUsedUtc,
                     RevokedUtc: key.RevokedUtc))

src/ZB.MOM.WW.MxGateway.Server/Diagnostics/AuthStoreHealthCheck.cs

@@ -0,0 +1,40 @@
+using Microsoft.Data.Sqlite;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
+
+namespace ZB.MOM.WW.MxGateway.Server.Diagnostics;
+
+/// <summary>
+/// Readiness probe: verifies the SQLite authentication store is reachable. The gateway
+/// authenticates every gRPC call against this store, so its reachability gates readiness.
+/// </summary>
+public sealed class AuthStoreHealthCheck : IHealthCheck
+{
+    private readonly AuthSqliteConnectionFactory _connectionFactory;
+
+    public AuthStoreHealthCheck(AuthSqliteConnectionFactory connectionFactory) =>
+        _connectionFactory = connectionFactory ?? throw new ArgumentNullException(nameof(connectionFactory));
+
+    public async Task<HealthCheckResult> CheckHealthAsync(
+        HealthCheckContext context,
+        CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using SqliteConnection connection =
+                await _connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
+            await using SqliteCommand command = connection.CreateCommand();
+            command.CommandText = "SELECT 1;";
+            await command.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false);
+            return HealthCheckResult.Healthy("Auth store is reachable.");
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            return HealthCheckResult.Unhealthy("Auth store is unreachable.", ex);
+        }
+    }
+}

src/ZB.MOM.WW.MxGateway.Server/Diagnostics/GatewayLogRedactorSeam.cs

@@ -0,0 +1,28 @@
+using ZB.MOM.WW.Telemetry.Serilog;
+
+namespace ZB.MOM.WW.MxGateway.Server.Diagnostics;
+
+/// <summary>
+/// Adapts the static <see cref="GatewayLogRedactor"/> to the shared <see cref="ILogRedactor"/> seam
+/// so the telemetry RedactionEnricher masks API-key/credential material on every log event.
+/// </summary>
+public sealed class GatewayLogRedactorSeam : ILogRedactor
+{
+    private static readonly string[] IdentityKeys = ["ClientIdentity", "authorization", "Authorization"];
+
+    /// <summary>
+    /// Masks API-key/credential material in known identity-bearing log properties.
+    /// </summary>
+    /// <param name="properties">The log event property dictionary to redact in place.</param>
+    public void Redact(IDictionary<string, object?> properties)
+    {
+        ArgumentNullException.ThrowIfNull(properties);
+        foreach (var key in IdentityKeys)
+        {
+            if (properties.TryGetValue(key, out var value) && value is string s)
+            {
+                properties[key] = GatewayLogRedactor.RedactClientIdentity(s);
+            }
+        }
+    }
+}

src/ZB.MOM.WW.MxGateway.Server/Galaxy/GalaxyAlarmAttributeRow.cs

@@ -0,0 +1,48 @@
+namespace ZB.MOM.WW.MxGateway.Server.Galaxy;
+
+/// <summary>
+///     One alarm-bearing attribute discovered by
+///     <see cref="GalaxyRepository.GetAlarmAttributesAsync"/>: an attribute whose owning
+///     object configures an <c>AlarmExtension</c> primitive (the same
+///     <c>is_alarm</c> detection used by <see cref="GalaxyRepository.GetAttributesAsync"/>).
+///     Used to build the subtag-fallback watch-list.
+/// </summary>
+public sealed class GalaxyAlarmAttributeRow
+{
+    /// <summary>
+    ///     Gets the alarm-bearing attribute reference (e.g. <c>Tank01.Level.HiHi</c>),
+    ///     matching the <c>full_tag_reference</c> projection of
+    ///     <see cref="GalaxyRepository.GetAttributesAsync"/>.
+    /// </summary>
+    public string FullTagReference { get; init; } = string.Empty;
+
+    /// <summary>
+    ///     Gets the owning object reference (e.g. <c>Tank01</c>). This is the Galaxy
+    ///     <c>tag_name</c> — the segment that precedes the first attribute dot in
+    ///     <see cref="FullTagReference"/>.
+    /// </summary>
+    public string SourceObjectReference { get; init; } = string.Empty;
+
+    /// <summary>
+    ///     Gets the owning object's Galaxy area (e.g. <c>TestArea</c>) — the alarm group.
+    ///     <para>
+    ///     Resolved via <c>gobject.area_gobject_id</c> in <c>AlarmAttributesSql</c>. The
+    ///     watch-list resolver composes the canonical <c>Galaxy!{area}.{reference}</c> from
+    ///     this so the synthesized reference's group matches the native alarmmgr (wnwrap)
+    ///     for reference parity. May be <see cref="string.Empty"/> when the object has no
+    ///     area; the resolver then falls back to the configured area.
+    ///     </para>
+    /// </summary>
+    public string Area { get; init; } = string.Empty;
+
+    /// <summary>
+    ///     Gets the writable ack-comment attribute address.
+    ///     <para>
+    ///     The Galaxy Repository schema does not expose an ack-comment subtag address
+    ///     directly, so this is always <see cref="string.Empty"/> here. The watch-list
+    ///     resolver (a later task) composes the concrete address from configuration plus
+    ///     <see cref="SourceObjectReference"/> / <see cref="FullTagReference"/>.
+    ///     </para>
+    /// </summary>
+    public string AckCommentSubtag { get; init; } = string.Empty;
+}

src/ZB.MOM.WW.MxGateway.Server/Galaxy/GalaxyRepository.cs

@@ -114,6 +114,64 @@ public sealed class GalaxyRepository(GalaxyRepositoryOptions options) : IGalaxyR
         return rows;
     }
 
+    /// <summary>
+    ///     Retrieves only the alarm-bearing attributes for the subtag-fallback watch-list.
+    ///     Alarm detection is identical to <see cref="GetAttributesAsync"/>: a row is
+    ///     alarm-bearing when its owning object configures an <c>AlarmExtension</c>
+    ///     primitive (the same <c>is_alarm</c> projection, here applied as a SQL filter).
+    /// </summary>
+    /// <param name="ct">Token to cancel the asynchronous operation.</param>
+    public async Task<List<GalaxyAlarmAttributeRow>> GetAlarmAttributesAsync(CancellationToken ct = default)
+    {
+        List<GalaxyAlarmAttributeRow> rows = new();
+
+        using SqlConnection conn = new(options.ConnectionString);
+        await conn.OpenAsync(ct).ConfigureAwait(false);
+
+        using SqlCommand cmd = new(AlarmAttributesSql, conn) { CommandTimeout = options.CommandTimeoutSeconds };
+        using SqlDataReader reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
+
+        while (await reader.ReadAsync(ct).ConfigureAwait(false))
+        {
+            rows.Add(MapAlarmRow(
+                fullTagReference: reader.GetString(0),
+                sourceObjectReference: reader.GetString(1),
+                area: reader.GetString(2)));
+        }
+        return rows;
+    }
+
+    /// <summary>
+    ///     Maps a raw alarm-attribute reader row to a <see cref="GalaxyAlarmAttributeRow"/>.
+    ///     <para>
+    ///     <paramref name="sourceObjectReference"/> is the Galaxy <c>tag_name</c> (the
+    ///     owning object), and <paramref name="fullTagReference"/> is
+    ///     <c>tag_name + '.' + attribute_name</c> — the same composition the
+    ///     <c>full_tag_reference</c> projection of <see cref="AttributesSql"/> produces.
+    ///     <see cref="GalaxyAlarmAttributeRow.AckCommentSubtag"/> is left empty here; the
+    ///     schema does not expose an ack-comment address and the watch-list resolver
+    ///     composes it later.
+    ///     </para>
+    ///     <paramref name="area"/> is the owning object's real Galaxy area (its alarm
+    ///     group), resolved via <c>gobject.area_gobject_id</c>; the watch-list resolver
+    ///     composes the canonical reference from it so the synthesized reference's group
+    ///     matches what the native alarmmgr (wnwrap) emits.
+    ///     Exposed internally so the derivation can be unit-tested without a database.
+    /// </summary>
+    /// <param name="fullTagReference">The alarm-bearing attribute reference.</param>
+    /// <param name="sourceObjectReference">The owning object reference (tag name).</param>
+    /// <param name="area">The owning object's Galaxy area (the alarm group).</param>
+    internal static GalaxyAlarmAttributeRow MapAlarmRow(
+        string fullTagReference,
+        string sourceObjectReference,
+        string area) => new()
+        {
+            FullTagReference = fullTagReference,
+            SourceObjectReference = sourceObjectReference,
+            Area = area,
+            AckCommentSubtag = string.Empty,
+        };
+
     private const string HierarchySql = @"
 ;WITH template_chain AS (
     SELECT g.gobject_id AS instance_gobject_id, t.gobject_id AS template_gobject_id,
@@ -248,5 +306,62 @@ SELECT
 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";
+
+    // Alarm-only discovery for the subtag-fallback watch-list. This reuses the candidate/ranked
+    // CTE shape and the same `AlarmExtension`-based detection as AttributesSql. Unlike
+    // AttributesSql it keeps only the user-attribute (dynamic_attribute) candidate branch: an
+    // alarm anchor is always a user attribute, so the primitive-instance branch AttributesSql
+    // carries would be filtered out here anyway — a row qualifies only when its user attribute
+    // anchors an `AlarmExtension` primitive on the owning object. It projects just what the
+    // watch-list needs — full_tag_reference (tag_name +
+    // '.' + attribute_name, matching AttributesSql) and the owning object's tag_name as
+    // source_object_reference. The array `[]` suffix is intentionally omitted: an
+    // alarm-bearing attribute is a scalar anchor, not an array body. It also projects the
+    // owning object's real Galaxy area (via gobject.area_gobject_id) as area_name so the
+    // watch-list resolver composes a reference whose group matches the native alarmmgr.
+    private const string AlarmAttributesSql = @"
+;WITH deployed_package_chain AS (
+    SELECT g.gobject_id, p.package_id, p.derived_from_package_id, 0 AS depth
+    FROM gobject g
+    INNER JOIN package p ON p.package_id = g.deployed_package_id
+    WHERE g.is_template = 0 AND g.deployed_package_id <> 0
+    UNION ALL
+    SELECT dpc.gobject_id, p.package_id, p.derived_from_package_id, dpc.depth + 1
+    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
+),
+candidate AS (
+    SELECT
+        dpc.gobject_id, g.tag_name, da.attribute_name, dpc.depth
+    FROM deployed_package_chain dpc
+    INNER JOIN dynamic_attribute da ON da.package_id = dpc.package_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 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 AS (
+    SELECT c.*, ROW_NUMBER() OVER (
+        PARTITION BY c.gobject_id, c.attribute_name ORDER BY c.depth) AS rn
+    FROM candidate c
+)
+SELECT
+    r.tag_name + '.' + r.attribute_name AS full_tag_reference,
+    r.tag_name AS source_object_reference,
+    ISNULL(area.tag_name, '') AS area_name
+FROM ranked r
+INNER JOIN gobject g ON g.gobject_id = r.gobject_id
+LEFT JOIN gobject area ON area.gobject_id = g.area_gobject_id
+WHERE r.rn = 1
+    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
+    )
 ORDER BY r.tag_name, r.attribute_name";
 }

src/ZB.MOM.WW.MxGateway.Server/Galaxy/IGalaxyRepository.cs

@@ -27,4 +27,12 @@ public interface IGalaxyRepository
     /// <summary>Retrieves all attributes for Galaxy objects from the repository.</summary>
     /// <param name="ct">Token to cancel the asynchronous operation.</param>
     Task<List<GalaxyAttributeRow>> GetAttributesAsync(CancellationToken ct = default);
+
+    /// <summary>
+    ///     Retrieves only the alarm-bearing attributes (those whose owning object
+    ///     configures an <c>AlarmExtension</c> primitive) for building the
+    ///     subtag-fallback watch-list.
+    /// </summary>
+    /// <param name="ct">Token to cancel the asynchronous operation.</param>
+    Task<List<GalaxyAlarmAttributeRow>> GetAlarmAttributesAsync(CancellationToken ct = default);
 }