code-reviews: mark Client.Java-049/050/051 windev-verified (gradle test green, JDK 21)

- Server-057: extend []-suffix normalization to AddItemBulk/AddBufferedItem so bulk-added
  array tags bind write-capable handles (authz check, worker bind, and registration kept
  consistent); update gateway.md + client READMEs. Tests: AddItemBulk/AddBufferedItem wiring.
- Server-058: assert []-fallback-resolved bare array names are still denied when out of
  read/write scope and that MaxWriteClassification is enforced on suffixed array registrations.
- Contracts-023/024/025: round-trip + field-19 descriptor pin for MxSparseArray; document
  MxSparseArray in docs/Contracts.md; enumerate it in the protocol-version-3 test summary.
- Tests-040: add wiring tests for the six uncovered sparse-write arms (WriteSecured, Write2,
  WriteSecured2, Write2Bulk, WriteSecuredBulk, WriteSecured2Bulk).

dotnet build + targeted tests green (184 passed).

.gitignore

@@ -45,6 +45,7 @@ build/
 out/
 tmp/
 temp/
+install/
 
 # .NET
 **/bin/
@@ -146,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

@@ -8,10 +8,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 The architecture is a two-process design — read `gateway.md` before making structural changes:
 
-- **Gateway** (`src/MxGateway.Server`, .NET 10, x64): ASP.NET Core gRPC server. Owns the public API, sessions, auth, the Blazor dashboard, and the Galaxy Repository SQL browse RPCs. **Never instantiates MXAccess COM directly.**
-- **Worker** (`src/MxGateway.Worker`, .NET Framework 4.8, **x86**): one process per session. Owns one MXAccess COM instance on a dedicated STA, pumps Windows messages, and converts COM events to protobuf.
+- **Gateway** (`src/ZB.MOM.WW.MxGateway.Server`, .NET 10, x64): ASP.NET Core gRPC server. Owns the public API, sessions, auth, the Blazor dashboard, and the Galaxy Repository SQL browse RPCs. **Never instantiates MXAccess COM directly.**
+- **Worker** (`src/ZB.MOM.WW.MxGateway.Worker`, .NET Framework 4.8, **x86**): one process per session. Owns one MXAccess COM instance on a dedicated STA, pumps Windows messages, and converts COM events to protobuf.
 - **IPC**: gateway↔worker uses one bidirectional named pipe per worker (`mxaccess-gateway-{gatewayPid}-{sessionId}`) with length-prefixed `WorkerEnvelope` protobuf frames. Gateway hosts the pipe server and launches the worker. **gRPC is not used inside the worker** — .NET Framework 4.8 doesn't have a first-class gRPC stack.
-- **Contracts** (`src/MxGateway.Contracts`): multi-targets `net10.0;net48` and owns the `.proto` files (`mxaccess_gateway.proto`, `mxaccess_worker.proto`, `galaxy_repository.proto`). All other projects consume the generated types from here. Do not hand-edit anything under `Generated/`.
+- **Contracts** (`src/ZB.MOM.WW.MxGateway.Contracts`): multi-targets `net10.0;net48` and owns the `.proto` files (`mxaccess_gateway.proto`, `mxaccess_worker.proto`, `galaxy_repository.proto`). All other projects consume the generated types from here. Do not hand-edit anything under `Generated/`.
 
 The worker must do all MXAccess COM calls on its dedicated STA thread, and the STA loop must pump Windows messages (`MsgWaitForMultipleObjectsEx` + `PeekMessage`/`DispatchMessage`) so MXAccess events deliver. A plain blocking queue on an STA is not enough.
 
@@ -19,42 +19,42 @@ The worker must do all MXAccess COM calls on its dedicated STA thread, and the S
 
 ```powershell
 # Full solution build (gateway, worker, contracts, tests)
-dotnet build src/MxGateway.sln
+dotnet build src/ZB.MOM.WW.MxGateway.slnx
 
-# Worker must be built x86 — the gateway looks for MxGateway.Worker.exe under bin\x86
-dotnet build src/MxGateway.Worker/MxGateway.Worker.csproj -p:Platform=x86
+# Worker must be built x86 — the gateway looks for ZB.MOM.WW.MxGateway.Worker.exe under bin\x86
+dotnet build src/ZB.MOM.WW.MxGateway.Worker/ZB.MOM.WW.MxGateway.Worker.csproj -p:Platform=x86
 
 # Gateway tests (no MXAccess required — uses FakeWorkerHarness)
-dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj
-dotnet test src/MxGateway.Worker.Tests/MxGateway.Worker.Tests.csproj -p:Platform=x86
+dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj
+dotnet test src/ZB.MOM.WW.MxGateway.Worker.Tests/ZB.MOM.WW.MxGateway.Worker.Tests.csproj -p:Platform=x86
 
-# Run gateway locally (defaults bound under MxGateway:* in src/MxGateway.Server/appsettings.json)
-dotnet run --project src/MxGateway.Server/MxGateway.Server.csproj
+# Run gateway locally (defaults bound under MxGateway:* in src/ZB.MOM.WW.MxGateway.Server/appsettings.json)
+dotnet run --project src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj
 
 # API-key admin CLI (same exe, "apikey" subcommand)
-dotnet run --project src/MxGateway.Server/MxGateway.Server.csproj -- apikey create --display-name "dev" --scopes session,invoke,event,metadata,admin
+dotnet run --project src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj -- apikey create --display-name "dev" --scopes session,invoke,event,metadata,admin
 ```
 
 Single test by name (xUnit `--filter`):
 
 ```powershell
-dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~GatewayEndToEndFakeWorkerSmokeTests
+dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~GatewayEndToEndFakeWorkerSmokeTests
 ```
 
 Live MXAccess integration tests are **opt-in** because they need installed MXAccess COM and live provider state:
 
 ```powershell
 $env:MXGATEWAY_RUN_LIVE_MXACCESS_TESTS = "1"
-dotnet test src/MxGateway.IntegrationTests/MxGateway.IntegrationTests.csproj --filter FullyQualifiedName~WorkerLiveMxAccessSmokeTests
+dotnet test src/ZB.MOM.WW.MxGateway.IntegrationTests/ZB.MOM.WW.MxGateway.IntegrationTests.csproj --filter FullyQualifiedName~WorkerLiveMxAccessSmokeTests
 ```
 
 Live LDAP tests use `MXGATEWAY_RUN_LIVE_LDAP_TESTS=1`. See `docs/GatewayTesting.md` for the full opt-in matrix and `LiveMxAccessFactAttribute` / `LiveLdapFactAttribute` for the gating logic.
 
 ## Clients
 
-Each language client is in `clients/<lang>/` with its own README. They all consume the shared `.proto` files in `src/MxGateway.Contracts/Protos`:
+Each language client is in `clients/<lang>/` with its own README. They all consume the shared `.proto` files in `src/ZB.MOM.WW.MxGateway.Contracts/Protos`:
 
-- `clients/dotnet`: `dotnet build clients/dotnet/MxGateway.Client.sln`
+- `clients/dotnet`: `dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx`
 - `clients/python`: `python -m pip install -e ".[dev]"; python -m pytest`
 - `clients/rust`: `cargo test --workspace; cargo clippy --workspace --all-targets -- -D warnings`
 - `clients/java`: `gradle test` (Java 21)
@@ -73,11 +73,11 @@ powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1
 - **Style guides** in `docs/style-guides/` are authoritative. Follow `CSharpStyleGuide.md` for gateway/worker/.NET-client code: file-scoped namespaces, `sealed` by default, `Async` suffix on Task-returning methods, MXAccess-aligned names (`MxStatusProxy`, `ServerHandle`, `ItemHandle`, `HResult`).
 - **MXAccess parity is the contract.** Don't "fix" surprising MXAccess behavior (e.g., `WriteSecured` failing before a value-bearing NMX body, distinct `OperationComplete` semantics, invalid-handle exceptions) unless the client explicitly opts into a non-parity mode. The installed MXAccess COM component is the baseline.
 - **Don't synthesize events.** The gateway forwards only events the worker emits; it never invents `OperationComplete` from write completion or command replies.
-- **One worker per session, one event subscriber per session** (v1). Multi-subscriber fan-out and reconnectable sessions are explicitly out of scope — see `docs/DesignDecisions.md`.
+- **One worker per session** (invariant). Multi-subscriber event fan-out and reconnect-with-replay have shipped and are config-gated: `AllowMultipleEventSubscribers` (default `false`) enables fan-out up to `MaxEventSubscribersPerSession` (default `8`); `DetachGraceSeconds` (default `30`) retains a session after its last subscriber drops so clients can reconnect; `ReplayBufferCapacity` / `ReplayRetentionSeconds` control how much event history the replay ring keeps. Default config preserves the original single-subscriber, no-retention behavior. See `docs/DesignDecisions.md` and `docs/Sessions.md`.
 - **Gateway restart does not reattach orphan workers.** The first version terminates orphaned workers on startup; do not design code paths that assume reattachment.
 - **No Blazor UI component libraries.** Dashboard uses local Bootstrap CSS/JS only — do not introduce MudBlazor, Radzen, FluentUI, etc.
 - **Don't log secrets or full tag values by default.** API keys, passwords, `WriteSecured` payloads, and `AuthenticateUser` credentials must never reach logs. Value logging is opt-in and redacted.
-- **Generated code** under `src/MxGateway.Contracts/Generated/`, `clients/*/generated*/`, `clients/python/src/mxgateway/generated/`, etc., is build output. Don't hand-edit. To regenerate, build the contracts project (`dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj`) or run the per-client generation step in that client's README.
+- **Generated code** under `src/ZB.MOM.WW.MxGateway.Contracts/Generated/`, `clients/*/generated*/`, `clients/python/src/mxgateway/generated/`, etc., is build output. Don't hand-edit. To regenerate, build the contracts project (`dotnet build src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj`) or run the per-client generation step in that client's README.
 - **Documentation style** (`StyleGuide.md`): PascalCase filenames, no marketing language, present tense, explain *why* not *what*.
 - **Update docs in the same change as the source.** When public APIs, contracts, configuration, build steps, security behavior, event shapes, value conversion, status mapping, or lifecycle rules change, the affected docs (`gateway.md`, `docs/`, client READMEs, design docs) must change in the same commit. Don't leave stale prose describing old behavior.
 
@@ -85,12 +85,14 @@ powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1
 
 When source code changes, build and test the affected component before reporting work done. If the change crosses component boundaries, build each affected component — don't rely on a single top-level build:
 
+**Run targeted tests per task, never the full suite each time.** When executing a plan task-by-task, run only the tests that exercise the code that task touched (`dotnet test --filter "FullyQualifiedName~<TestClass>"`, or the per-task test named in the plan). The full gateway suite is slow and leaves orphaned testhost processes — run it at most once per phase (after a related batch of tasks lands), not after every task.
+
 | Changed area | Required verification |
 |---|---|
 | Contracts or `.proto` files | regenerate generated code, then build gateway, worker, and every generated client touched by the contract |
-| Gateway server, sessions, workers, gRPC, dashboard, metrics | `dotnet build src/MxGateway.Server` and run affected gateway / fake-worker tests |
-| Worker IPC, STA, MXAccess, conversion | `dotnet build src/MxGateway.Worker -p:Platform=x86` and run worker tests |
-| .NET client | `dotnet build clients/dotnet/MxGateway.Client.sln` and run its tests |
+| Gateway server, sessions, workers, gRPC, dashboard, metrics | `dotnet build src/ZB.MOM.WW.MxGateway.Server` and run affected gateway / fake-worker tests |
+| Worker IPC, STA, MXAccess, conversion | `dotnet build src/ZB.MOM.WW.MxGateway.Worker -p:Platform=x86` and run worker tests |
+| .NET client | `dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx` and run its tests |
 | Go client | `gofmt`, `go build ./...`, `go test ./...` from `clients/go` |
 | Rust client | `cargo fmt`, `cargo check --workspace`, `cargo test --workspace`, `cargo clippy --all-targets -- -D warnings` from `clients/rust` |
 | Python client | `python -m pytest` from `clients/python` |
@@ -100,7 +102,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`.
@@ -114,9 +116,9 @@ External analysis sources referenced by design docs:
 
 ## Authentication
 
-Gateway gRPC clients authenticate with an API key in metadata: `authorization: Bearer mxgw_<key-id>_<secret>`. Keys are stored hashed (with a peppered SHA) in a gateway-owned SQLite DB (default `C:\ProgramData\MxGateway\gateway-auth.db`). Scopes (`session`, `invoke`, `event`, `metadata`, `admin`) gate specific RPCs; missing → `Unauthenticated`, insufficient → `PermissionDenied`. The `apikey` subcommand on the server exe manages keys; see `src/MxGateway.Server/Security/Authentication/`.
+Gateway gRPC clients authenticate with an API key in metadata: `authorization: Bearer mxgw_<key-id>_<secret>`. Keys are stored hashed (with a peppered SHA) in a gateway-owned SQLite DB (default `C:\ProgramData\MxGateway\gateway-auth.db`). Scopes (`session`, `invoke`, `event`, `metadata`, `admin`) gate specific RPCs; missing → `Unauthenticated`, insufficient → `PermissionDenied`. The `apikey` subcommand on the server exe manages keys; see `src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/`.
 
-Dashboard auth is LDAP-backed (separate from the gRPC API-key model). `/login` binds against `MxGateway:Ldap` and maps the user's LDAP groups to `Admin` or `Viewer` via `MxGateway:Dashboard:GroupToRole`, then issues an HTTP-only secure `__Host-MxGatewayDashboard` cookie. SignalR hubs at `/hubs/{snapshot,alarms,events}` accept either the cookie or a 30-minute bearer minted at `/hubs/token`. `Dashboard:AllowAnonymousLocalhost` bypasses auth on loopback when enabled.
+Dashboard auth is LDAP-backed (separate from the gRPC API-key model). `/login` binds against `MxGateway:Ldap` and maps the user's LDAP groups to `Admin` or `Viewer` via `MxGateway:Dashboard:GroupToRole`, then issues an HTTP-only secure `__Host-MxGatewayDashboard` cookie. SignalR hubs at `/hubs/{snapshot,alarms,events}` accept either the cookie or a 30-minute bearer minted at `/hubs/token`. `Dashboard:AllowAnonymousLocalhost` bypasses auth on loopback when enabled. `Dashboard:DisableLogin` (default `false`) auto-authenticates every dashboard request — including remote browsers — as `Dashboard:AutoLoginUser` (default `multi-role`) with both Admin and Viewer roles; dev/test only, never enable in production.
 
 ## Process / Platform Notes
 

REVIEW-PROCESS.md

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

clients/dotnet/Directory.Build.props

@@ -0,0 +1,38 @@
+<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>
+    <Company>ZB MOM WW</Company>
+    <Copyright>Copyright (c) ZB MOM WW. All rights reserved.</Copyright>
+    <Product>MxAccessGateway Client</Product>
+    <RepositoryUrl>https://gitea.dohertylan.com/dohertj2/mxaccessgw</RepositoryUrl>
+    <RepositoryType>git</RepositoryType>
+    <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.2</Version>
+    <IncludeSymbols>true</IncludeSymbols>
+    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
+    <!-- Default: do NOT pack. Each project opts in. -->
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+</Project>

clients/dotnet/DotnetClientDesign.md

@@ -107,6 +107,7 @@ public sealed class MxGatewayClientOptions
     public required string ApiKey { get; init; }
     public bool UseTls { get; init; }
     public string? CaCertificatePath { get; init; }
+    public bool RequireCertificateValidation { get; init; }
     public string? ServerNameOverride { get; init; }
     public TimeSpan ConnectTimeout { get; init; } = TimeSpan.FromSeconds(10);
     public TimeSpan DefaultCallTimeout { get; init; } = TimeSpan.FromSeconds(30);
@@ -124,6 +125,24 @@ or subscription changes because those calls can partially succeed in MXAccess.
 API key may be loaded from `MXGATEWAY_API_KEY` by the CLI, not implicitly by the
 library constructor unless a helper explicitly says it does that.
 
+### TLS trust posture
+
+The gateway can serve a self-signed certificate it generates itself (it has no
+PKI). To make that usable, TLS is **lenient by default**: when `UseTls` is set
+and `CaCertificatePath` is empty, `CreateHttpHandler` installs a
+`RemoteCertificateValidationCallback` that returns `true`, so the gateway's
+self-signed certificate is accepted without verification.
+
+To verify the gateway instead:
+
+- set `CaCertificatePath` to pin a CA — validated via a `CustomRootTrust`
+  `X509Chain` against that root, and the callback additionally rejects a
+  hostname/SAN mismatch (`RemoteCertificateNameMismatch`); or
+- set `RequireCertificateValidation` to `true` to keep the default OS/system-trust
+  verification on a connection with no pinned CA.
+
+Pinning a CA always wins over the lenient default.
+
 ## Auth Interceptor
 
 Use a gRPC call credentials/interceptor layer to attach:

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

@@ -84,6 +84,15 @@ messages. `MxGatewaySession.OpenSessionReply` keeps the raw session-open reply
 available, and command helpers have `*RawAsync` variants when callers need the
 complete `MxCommandReply`.
 
+For alarms, the client exposes `QueryActiveAlarmsAsync` (one-shot snapshot of
+the active alarms the gateway's central monitor currently holds),
+`StreamAlarmsAsync` (server-streaming feed of alarm-state-change messages
+keyed by the same monitor), and `AcknowledgeAlarmAsync` (ack by alarm
+reference, optional comment, ack target). All three accept a cancellation
+token and pass through the `MxGateway:Alarms` configuration on the
+server — when alarms are disabled, the gateway returns an empty list / empty
+stream rather than failing.
+
 `MxGatewaySession.CloseAsync` is explicit and idempotent. Repeated calls return
 the first `CloseSessionReply` instead of sending another close request.
 
@@ -112,6 +121,78 @@ can keep the full `MxCommandReply`, HRESULT, and status array when MXAccess
 itself rejects a command. `MxAccessException.Reply` contains the raw generated
 reply.
 
+## Write Semantics And Common Pitfalls
+
+These are MXAccess parity behaviors that surprise new callers. The gateway
+forwards them unchanged — it does not paper over them.
+
+### Attributing a write to a user without `AuthenticateUser`
+
+MXAccess only stamps a plain `Write`/`Write2` with a Galaxy user id when the
+item carries an active *supervisory* advise. If you are **not** using the
+verified/secured path (`AuthenticateUser` → `WriteSecured`/`WriteSecured2`) but
+still need the write attributed to a user id, you must first advise the item
+supervisory and then pass that user id on the write. Without the supervisory
+advise the `userId` on a plain write is ignored.
+
+The library exposes `Advise`/`UnAdvise` as named helpers but not supervisory
+advise, so send it through the generic command channel:
+
+```csharp
+await session.InvokeAsync(new MxCommandRequest
+{
+    SessionId = session.SessionId,
+    Command = new MxCommand
+    {
+        Kind = MxCommandKind.AdviseSupervisory,
+        AdviseSupervisory = new AdviseSupervisoryCommand
+        {
+            ServerHandle = serverHandle,
+            ItemHandle = itemHandle,
+        },
+    },
+});
+
+await session.WriteAsync(serverHandle, itemHandle, value.ToMxValue(), userId);
+```
+
+The CLI exposes the same command as `advise-supervisory`, and `write` /
+`write2` take `--user-id`.
+
+### Array writes replace the whole array
+
+A write to an array attribute **replaces the entire array**; it is not an
+element-wise patch. To change a subset of elements, send the full array with
+the unchanged elements included. For example, to change 2 elements of a
+20-element array, build the `MxValue` from all 20 values (the 18 unchanged plus
+the 2 new ones). Sending only the 2 changed values overwrites the attribute
+with a 2-element array.
+
+When only a few indices need changing and the rest should be reset to the
+element type's default, use `WriteArrayElementsAsync` instead of building the
+full array manually:
+
+```csharp
+await session.WriteArrayElementsAsync(
+    serverHandle, itemHandle,
+    elementDataType: MxDataType.Integer,
+    totalLength: 20,
+    elements: new Dictionary<uint, MxValue>
+    {
+        [2] = 42.ToMxValue(),
+        [7] = 99.ToMxValue(),
+    });
+```
+
+The gateway expands the sparse descriptor into a full `totalLength`-element
+array before forwarding to the worker. Indices not listed in `elements` are
+written as the element type's default — this is a **reset**, not a preserve;
+current values at those positions are discarded. `totalLength` is required and
+must match the declared length of the array attribute. Bare-name array items
+(`Area001.Pump001.Speed`) are auto-normalized to the `[]` form across the whole
+add family — `AddItem`, `AddItem2`, `AddItemBulk`, and `AddBufferedItem` — so the
+array attribute accepts the write.
+
 ## CLI Usage
 
 The test CLI supports deterministic JSON output for automation:
@@ -125,6 +206,8 @@ dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- advise --s
 dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- write --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --json
 dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- write2 --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --timestamp 2026-01-01T00:00:00Z --json
 dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- stream-events --session-id <id> --max-events 1 --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- stream-alarms --filter-prefix Area001 --max-events 1 --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- acknowledge-alarm --reference "\\Galaxy\Area001.Pump001.PumpFault" --comment "ack from cli" --operator operator1 --json
 dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- smoke --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json
 ```
 
@@ -185,6 +268,67 @@ dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-las
 dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-discover --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
 ```
 
+### Browsing lazily
+
+For UI trees or OPC UA bridges, use `BrowseChildrenAsync` to walk one level at a
+time instead of paging the full hierarchy. Pass an empty request for root objects;
+subsequent calls supply `ParentGobjectId`, `ParentTagName`, or
+`ParentContainedPath`. Each child's `ChildHasChildren[i]` tells you whether to
+draw an expand triangle. Filter fields match `DiscoverHierarchy`. See
+[Galaxy Repository](../../docs/GalaxyRepository.md#browsechildren) for full
+request and filter semantics.
+
+```csharp
+BrowseChildrenReply roots = await repository.BrowseChildrenAsync(
+    new BrowseChildrenRequest());
+
+for (int i = 0; i < roots.Children.Count; i++)
+{
+    GalaxyObject child = roots.Children[i];
+    bool hasChildren = roots.ChildHasChildren[i];
+    Console.WriteLine($"{child.TagName} expand={hasChildren}");
+}
+```
+
+#### High-level walker
+
+For UI trees, the client provides a `LazyBrowseNode` walker that handles
+sibling pagination and the `child_has_children` hint for you:
+
+```csharp
+await using GalaxyRepositoryClient repository = GalaxyRepositoryClient.Create(
+    new MxGatewayClientOptions { Endpoint = new Uri("http://localhost:5000"), ApiKey = apiKey });
+IReadOnlyList<LazyBrowseNode> roots = await repository.BrowseAsync();
+foreach (LazyBrowseNode root in roots)
+{
+    if (root.HasChildrenHint)
+    {
+        await root.ExpandAsync();
+    }
+    foreach (LazyBrowseNode child in root.Children)
+    {
+        Console.WriteLine($"{child.Object.TagName} ({(child.HasChildrenHint ? "has children" : "leaf")})");
+    }
+}
+```
+
+`ExpandAsync` is idempotent — calling it twice fires only one RPC,
+and is safe under concurrent callers. To refresh after a Galaxy redeploy, call
+`BrowseAsync` again from the root.
+
+The CLI counterpart is `galaxy-browse`. Without `--parent` it walks the root
+objects and eagerly expands `--depth` further levels into an indented tree; with
+`--parent <gobject-id>` it fetches exactly one level of children for that object
+(`--depth` is ignored there). Filter flags map onto `BrowseChildrenOptions`:
+`--category-ids` and `--template-contains` are comma-separated lists,
+`--tag-name-glob` / `--alarm-bearing-only` / `--historized-only` are scalar, and
+`--include-attributes` overrides the server default for attribute population.
+
+```powershell
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-browse --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --depth 1
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-browse --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --parent 42 --json
+```
+
 ### Watching deploy events
 
 `WatchDeployEventsAsync` opens the `WatchDeployEvents` server-streaming RPC. The
@@ -228,6 +372,17 @@ Use TLS options for a secured gateway:
 dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- smoke --endpoint https://ZB.MOM.WW.MxGateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name ZB.MOM.WW.MxGateway.example.local --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json
 ```
 
+### TLS trust
+
+The gateway can auto-generate its own self-signed certificate (it has no PKI), so
+the client is **lenient by default**: a TLS connection (`UseTls` / `--tls`) with
+no pinned CA accepts whatever certificate the gateway presents. To verify
+instead, pin a CA with `CaCertificatePath` / `--ca-file` (this path also enforces
+the certificate hostname/SAN match), or set `RequireCertificateValidation` to
+force OS/system-trust verification without pinning. Use `ServerNameOverride` /
+`--server-name` when the dialed host differs from the certificate SAN. See
+[Gateway Configuration](../../docs/GatewayConfiguration.md#automatic-self-signed-certificate).
+
 ## Integration Checks
 
 Run live checks only when a gateway and MXAccess-backed worker are available:
@@ -240,6 +395,29 @@ $env:MXGATEWAY_TEST_ITEM = 'Area001.Pump001.Speed'
 dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- smoke --endpoint $env:MXGATEWAY_ENDPOINT --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
 ```
 
+## Installing as a NuGet Package
+
+The client publishes to the internal Gitea NuGet feed at
+`https://gitea.dohertylan.com/api/packages/dohertj2/nuget/index.json`.
+
+Add the feed once:
+
+````bash
+dotnet nuget add source https://gitea.dohertylan.com/api/packages/dohertj2/nuget/index.json \
+    --name dohertj2-gitea \
+    --username <gitea-username> \
+    --password <gitea-token-or-password> \
+    --store-password-in-clear-text
+````
+
+Then add the package to your project:
+
+````bash
+dotnet add package ZB.MOM.WW.MxGateway.Client --version 0.1.1
+````
+
+The `ZB.MOM.WW.MxGateway.Contracts` package is pulled in transitively.
+
 ## Related Documentation
 
 - [Client Packaging](../../docs/ClientPackaging.md)

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/IMxGatewayCliClient.cs

@@ -3,6 +3,13 @@ using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
 
 namespace ZB.MOM.WW.MxGateway.Client.Cli;
 
+/// <summary>
+///     Transport seam used by the CLI to drive gateway and Galaxy Repository
+///     RPCs, exposing only the operations the command surface needs. The
+///     production binding is <see cref="MxGatewayCliClientAdapter"/> (wrapping a
+///     real <c>MxGatewayClient</c>); tests substitute an in-memory fake so the
+///     command routing can be exercised without a live gateway.
+/// </summary>
 public interface IMxGatewayCliClient : IAsyncDisposable
 {
     /// <summary>
@@ -45,6 +52,27 @@ public interface IMxGatewayCliClient : IAsyncDisposable
         StreamEventsRequest request,
         CancellationToken cancellationToken);
 
+    /// <summary>
+    /// Acknowledges an active MXAccess alarm condition through the gateway.
+    /// </summary>
+    /// <param name="request">The acknowledge request — alarm reference, comment, operator user.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>The acknowledge reply with protocol + native MxStatus.</returns>
+    Task<AcknowledgeAlarmReply> AcknowledgeAlarmAsync(
+        AcknowledgeAlarmRequest request,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Attaches to the gateway's central alarm feed — the current active-alarm
+    /// snapshot followed by live transitions.
+    /// </summary>
+    /// <param name="request">The stream request, optionally scoped by alarm-reference prefix.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>An async enumerable of alarm feed messages.</returns>
+    IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
+        StreamAlarmsRequest request,
+        CancellationToken cancellationToken);
+
     /// <summary>
     /// Tests connection to the Galaxy Repository.
     /// </summary>
@@ -84,4 +112,16 @@ public interface IMxGatewayCliClient : IAsyncDisposable
     IAsyncEnumerable<DeployEvent> GalaxyWatchDeployEventsAsync(
         WatchDeployEventsRequest request,
         CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Fetches one page of direct children of a Galaxy parent (or the root
+    /// objects when the parent selector is unset), the primitive that backs the
+    /// lazy-browse helper.
+    /// </summary>
+    /// <param name="request">The browse-children request.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>The browse-children reply.</returns>
+    Task<BrowseChildrenReply> GalaxyBrowseChildrenAsync(
+        BrowseChildrenRequest request,
+        CancellationToken cancellationToken);
 }

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayCliClientAdapter.cs

@@ -52,6 +52,22 @@ internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
         return _client.StreamEventsAsync(request, cancellationToken);
     }
 
+    /// <inheritdoc />
+    public Task<AcknowledgeAlarmReply> AcknowledgeAlarmAsync(
+        AcknowledgeAlarmRequest request,
+        CancellationToken cancellationToken)
+    {
+        return _client.AcknowledgeAlarmAsync(request, cancellationToken);
+    }
+
+    /// <inheritdoc />
+    public IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
+        StreamAlarmsRequest request,
+        CancellationToken cancellationToken)
+    {
+        return _client.StreamAlarmsAsync(request, cancellationToken);
+    }
+
     /// <inheritdoc />
     public Task<TestConnectionReply> GalaxyTestConnectionAsync(
         TestConnectionRequest request,
@@ -84,6 +100,14 @@ internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
         return _galaxyClient.Value.WatchDeployEventsRawAsync(request, cancellationToken);
     }
 
+    /// <inheritdoc />
+    public Task<BrowseChildrenReply> GalaxyBrowseChildrenAsync(
+        BrowseChildrenRequest request,
+        CancellationToken cancellationToken)
+    {
+        return _galaxyClient.Value.BrowseChildrenRawAsync(request, cancellationToken);
+    }
+
     /// <inheritdoc />
     public async ValueTask DisposeAsync()
     {

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

@@ -0,0 +1,34 @@
+using Grpc.Core;
+using Grpc.Net.Client;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
+
+/// <summary>
+/// Live smoke tests for the BrowseChildren RPC. Skipped by default; set
+/// MXGATEWAY_API_KEY and MXGATEWAY_ENDPOINT to run against a real gateway.
+/// </summary>
+public sealed class BrowseChildrenSmokeTests
+{
+    /// <summary>
+    /// Verifies that BrowseChildren returns a non-zero cache sequence and
+    /// a consistent children/child-has-children count from a live gateway.
+    /// </summary>
+    [Fact(Skip = "Set MXGATEWAY_API_KEY and MXGATEWAY_ENDPOINT to enable.")]
+    public async Task BrowseChildren_LiveGateway_ReturnsRootsWithCacheSequence()
+    {
+        string? apiKey = Environment.GetEnvironmentVariable("MXGATEWAY_API_KEY");
+        string endpoint = Environment.GetEnvironmentVariable("MXGATEWAY_ENDPOINT") ?? "http://localhost:5120";
+
+        Assert.False(string.IsNullOrEmpty(apiKey), "MXGATEWAY_API_KEY must be set.");
+
+        using GrpcChannel channel = GrpcChannel.ForAddress(endpoint);
+        GalaxyRepository.GalaxyRepositoryClient client = new(channel);
+
+        Metadata headers = new() { { "authorization", $"Bearer {apiKey}" } };
+        BrowseChildrenReply reply = await client.BrowseChildrenAsync(new BrowseChildrenRequest(), headers);
+
+        Assert.True(reply.CacheSequence > 0UL);
+        Assert.Equal(reply.Children.Count, reply.ChildHasChildren.Count);
+    }
+}

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

@@ -48,6 +48,7 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
     /// </summary>
     public DiscoverHierarchyReply DiscoverHierarchyReply { get; set; } = new();
 
+    /// <summary>Gets the queue of discover hierarchy replies; dequeued in FIFO order.</summary>
     public Queue<DiscoverHierarchyReply> DiscoverHierarchyReplies { get; } = new();
 
     /// <summary>
@@ -122,6 +123,49 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
                 : DiscoverHierarchyReply);
     }
 
+    /// <summary>Records BrowseChildren RPC calls made by the client.</summary>
+    public List<(BrowseChildrenRequest Request, CallOptions CallOptions)> BrowseChildrenCalls { get; } = [];
+
+    /// <summary>Default reply returned from BrowseChildren when the queue is empty.</summary>
+    public BrowseChildrenReply BrowseChildrenReply { get; set; } = new();
+
+    /// <summary>Queue of replies returned from BrowseChildren; dequeued in FIFO order.</summary>
+    public Queue<BrowseChildrenReply> BrowseChildrenReplies { get; } = new();
+
+    /// <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 async Task<BrowseChildrenReply> BrowseChildrenAsync(
+        BrowseChildrenRequest request,
+        CallOptions callOptions)
+    {
+        BrowseChildrenCalls.Add((request, callOptions));
+        if (BrowseChildrenExceptions.TryDequeue(out Exception? exception))
+        {
+            throw exception;
+        }
+
+        if (BrowseChildrenGate is { } gate)
+        {
+            await gate().ConfigureAwait(false);
+        }
+
+        return BrowseChildrenReplies.TryDequeue(out BrowseChildrenReply? reply)
+            ? reply
+            : BrowseChildrenReply;
+    }
+
     /// <summary>
     /// Gets the list of WatchDeployEvents RPC calls made by the client.
     /// </summary>

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

@@ -51,6 +51,11 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
     /// </summary>
     public List<(QueryActiveAlarmsRequest Request, CallOptions CallOptions)> QueryActiveAlarmsCalls { get; } = [];
 
+    /// <summary>
+    /// Gets the list of captured StreamAlarmsAsync calls.
+    /// </summary>
+    public List<(StreamAlarmsRequest Request, CallOptions CallOptions)> StreamAlarmsCalls { get; } = [];
+
     /// <summary>
     /// Gets the queue of exceptions to throw from AcknowledgeAlarmAsync.
     /// </summary>
@@ -58,6 +63,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
 
     private readonly Queue<AcknowledgeAlarmReply> _acknowledgeReplies = new();
     private readonly List<ActiveAlarmSnapshot> _activeAlarmSnapshots = [];
+    private readonly List<AlarmFeedMessage> _alarmFeedMessages = [];
 
     /// <summary>
     /// Gets or sets the reply to return from OpenSessionAsync.
@@ -190,6 +196,8 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
     /// <summary>
     /// Records the acknowledge call and returns the next enqueued reply (or default).
     /// </summary>
+    /// <param name="request">The acknowledge alarm request.</param>
+    /// <param name="callOptions">Call options specifying RPC behavior.</param>
     public Task<AcknowledgeAlarmReply> AcknowledgeAlarmAsync(
         AcknowledgeAlarmRequest request,
         CallOptions callOptions)
@@ -213,6 +221,8 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
     /// <summary>
     /// Records the query call and yields each enqueued snapshot.
     /// </summary>
+    /// <param name="request">The query active alarms request.</param>
+    /// <param name="callOptions">Call options specifying RPC behavior.</param>
     public async IAsyncEnumerable<ActiveAlarmSnapshot> QueryActiveAlarmsAsync(
         QueryActiveAlarmsRequest request,
         CallOptions callOptions)
@@ -228,14 +238,42 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
     }
 
     /// <summary>Enqueues an acknowledge reply.</summary>
+    /// <param name="reply">The acknowledge reply to enqueue.</param>
     public void AddAcknowledgeReply(AcknowledgeAlarmReply reply)
     {
         _acknowledgeReplies.Enqueue(reply);
     }
 
     /// <summary>Enqueues a snapshot to be yielded from QueryActiveAlarmsAsync.</summary>
+    /// <param name="snapshot">The snapshot to enqueue.</param>
     public void AddActiveAlarmSnapshot(ActiveAlarmSnapshot snapshot)
     {
         _activeAlarmSnapshots.Add(snapshot);
     }
+
+    /// <summary>
+    /// Records the stream-alarms call and yields each enqueued feed message.
+    /// </summary>
+    /// <param name="request">The stream alarms request.</param>
+    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    public async IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
+        StreamAlarmsRequest request,
+        CallOptions callOptions)
+    {
+        StreamAlarmsCalls.Add((request, callOptions));
+
+        foreach (AlarmFeedMessage message in _alarmFeedMessages)
+        {
+            callOptions.CancellationToken.ThrowIfCancellationRequested();
+            await Task.Yield();
+            yield return message;
+        }
+    }
+
+    /// <summary>Enqueues an alarm feed message to be yielded from StreamAlarmsAsync.</summary>
+    /// <param name="message">The alarm feed message to enqueue.</param>
+    public void AddAlarmFeedMessage(AlarmFeedMessage message)
+    {
+        _alarmFeedMessages.Add(message);
+    }
 }

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

@@ -181,6 +181,9 @@ public sealed class GalaxyRepositoryClientTests
         Assert.Contains("repeated page token", exception.Message, StringComparison.Ordinal);
     }
 
+    /// <summary>
+    /// Verifies that DiscoverHierarchyAsync maps typed filter options correctly to the request.
+    /// </summary>
     [Fact]
     public async Task DiscoverHierarchyAsync_WithOptions_MapsTypedFilters()
     {
@@ -212,6 +215,9 @@ public sealed class GalaxyRepositoryClientTests
         Assert.True(request.HistorizedOnly);
     }
 
+    /// <summary>
+    /// Verifies that TestConnectionAsync retries on transient gRPC failures.
+    /// </summary>
     [Fact]
     public async Task TestConnectionAsync_RetriesOnTransientGrpcFailure()
     {

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

@@ -0,0 +1,311 @@
+using Grpc.Core;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
+
+/// <summary>
+/// Tests for the <see cref="LazyBrowseNode"/> walker over the BrowseChildren RPC.
+/// </summary>
+public sealed class LazyBrowseNodeTests
+{
+    /// <summary>
+    /// Verifies that calling BrowseAsync with no parent returns the root nodes
+    /// from the first BrowseChildren reply and surfaces the per-child has-children hint.
+    /// </summary>
+    [Fact]
+    public async Task Browse_NoParent_ReturnsRoots()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.BrowseChildrenReplies.Enqueue(BuildReply(
+            children: [BuildObject(1, "Plant", isArea: true), BuildObject(2, "Other")],
+            childHasChildren: [true, false],
+            cacheSequence: 1));
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        IReadOnlyList<LazyBrowseNode> roots = await client.BrowseAsync();
+
+        Assert.Equal(2, roots.Count);
+        Assert.Equal("Plant", roots[0].Object.TagName);
+        Assert.True(roots[0].HasChildrenHint);
+        Assert.False(roots[0].IsExpanded);
+        Assert.Equal("Other", roots[1].Object.TagName);
+        Assert.False(roots[1].HasChildrenHint);
+        Assert.False(roots[1].IsExpanded);
+    }
+
+    /// <summary>
+    /// Verifies that ExpandAsync populates Children and marks the node expanded after one RPC.
+    /// </summary>
+    [Fact]
+    public async Task Expand_PopulatesChildrenAndMarksExpanded()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.BrowseChildrenReplies.Enqueue(BuildReply(
+            children: [BuildObject(1, "Plant", isArea: true)],
+            childHasChildren: [true],
+            cacheSequence: 1));
+        transport.BrowseChildrenReplies.Enqueue(BuildReply(
+            children: [BuildObject(10, "Line1")],
+            childHasChildren: [false],
+            cacheSequence: 1));
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        IReadOnlyList<LazyBrowseNode> roots = await client.BrowseAsync();
+        await roots[0].ExpandAsync();
+
+        Assert.True(roots[0].IsExpanded);
+        Assert.Single(roots[0].Children);
+        Assert.Equal("Line1", roots[0].Children[0].Object.TagName);
+        Assert.Equal(2, transport.BrowseChildrenCalls.Count);
+    }
+
+    /// <summary>
+    /// Verifies that a second ExpandAsync call is a no-op and issues no additional RPC.
+    /// </summary>
+    [Fact]
+    public async Task Expand_CalledTwice_NoSecondRpc()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.BrowseChildrenReplies.Enqueue(BuildReply(
+            children: [BuildObject(1, "Plant", isArea: true)],
+            childHasChildren: [true],
+            cacheSequence: 1));
+        transport.BrowseChildrenReplies.Enqueue(BuildReply(
+            children: [BuildObject(10, "Line1")],
+            childHasChildren: [false],
+            cacheSequence: 1));
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        IReadOnlyList<LazyBrowseNode> roots = await client.BrowseAsync();
+        await roots[0].ExpandAsync();
+        await roots[0].ExpandAsync();
+
+        Assert.Equal(2, transport.BrowseChildrenCalls.Count);
+    }
+
+    /// <summary>
+    /// Verifies that an RPC failure (NotFound) during expand is wrapped in MxGatewayException.
+    /// </summary>
+    [Fact]
+    public async Task Expand_UnknownParent_ThrowsMxGatewayException()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.BrowseChildrenReplies.Enqueue(BuildReply(
+            children: [BuildObject(1, "Plant", isArea: true)],
+            childHasChildren: [true],
+            cacheSequence: 1));
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        IReadOnlyList<LazyBrowseNode> roots = await client.BrowseAsync();
+
+        // Queue the failure for the upcoming ExpandAsync call so it consumes
+        // the exception on its first RPC rather than the BrowseAsync above.
+        transport.BrowseChildrenExceptions.Enqueue(
+            new MxGatewayException(
+                "Parent not found",
+                new RpcException(new Status(StatusCode.NotFound, "Parent not found"))));
+
+        await Assert.ThrowsAsync<MxGatewayException>(async () => await roots[0].ExpandAsync());
+        Assert.False(roots[0].IsExpanded);
+        Assert.Empty(roots[0].Children);
+    }
+
+    /// <summary>
+    /// Verifies that ExpandAsync drains multi-page sibling replies and forwards the page token.
+    /// </summary>
+    [Fact]
+    public async Task Expand_MultiPageSiblings_GathersAllPages()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        // Roots
+        transport.BrowseChildrenReplies.Enqueue(BuildReply(
+            children: [BuildObject(7, "Plant", isArea: true)],
+            childHasChildren: [true],
+            cacheSequence: 1));
+        // First child page (2 children) with a next token
+        BrowseChildrenReply childPage1 = BuildReply(
+            children: [BuildObject(70, "ChildA"), BuildObject(71, "ChildB")],
+            childHasChildren: [false, false],
+            cacheSequence: 1);
+        childPage1.NextPageToken = "7:abc:2";
+        transport.BrowseChildrenReplies.Enqueue(childPage1);
+        // Second child page (1 child) with no next token
+        transport.BrowseChildrenReplies.Enqueue(BuildReply(
+            children: [BuildObject(72, "ChildC")],
+            childHasChildren: [false],
+            cacheSequence: 1));
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        IReadOnlyList<LazyBrowseNode> roots = await client.BrowseAsync();
+        await roots[0].ExpandAsync();
+
+        Assert.Equal(3, roots[0].Children.Count);
+        Assert.Equal(3, transport.BrowseChildrenCalls.Count);
+        Assert.Equal("7:abc:2", transport.BrowseChildrenCalls[2].Request.PageToken);
+    }
+
+    /// <summary>
+    /// Verifies that ten concurrent ExpandAsync calls issue exactly one RPC, not ten.
+    /// </summary>
+    [Fact]
+    public async Task Expand_CalledConcurrently_OnlyFiresOneRpc()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.BrowseChildrenReplies.Enqueue(BuildReply(
+            children: [BuildObject(1, "Plant", isArea: true)],
+            childHasChildren: [true],
+            cacheSequence: 7));
+        transport.BrowseChildrenReplies.Enqueue(BuildReply(
+            children: [BuildObject(2, "Mixer_001")],
+            childHasChildren: [false],
+            cacheSequence: 7));
+
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+        IReadOnlyList<LazyBrowseNode> roots = await client.BrowseAsync();
+
+        // Fire ten concurrent expands of the same node.
+        Task[] tasks = Enumerable.Range(0, 10)
+            .Select(_ => roots[0].ExpandAsync())
+            .ToArray();
+        await Task.WhenAll(tasks);
+
+        Assert.True(roots[0].IsExpanded);
+        Assert.Single(roots[0].Children);
+        // 1 roots fetch + exactly 1 expand fetch = 2 total
+        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>
+    [Fact]
+    public async Task Browse_WithFilter_ForwardsToRequest()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        await client.BrowseAsync(new BrowseChildrenOptions
+        {
+            TagNameGlob = "Mixer*",
+            AlarmBearingOnly = true,
+        });
+
+        BrowseChildrenRequest request = Assert.Single(transport.BrowseChildrenCalls).Request;
+        Assert.Equal("Mixer*", request.TagNameGlob);
+        Assert.True(request.AlarmBearingOnly);
+    }
+
+    private static GalaxyObject BuildObject(int id, string tag, bool isArea = false)
+        => new() { GobjectId = id, TagName = tag, BrowseName = tag, IsArea = isArea };
+
+    private static BrowseChildrenReply BuildReply(
+        IReadOnlyList<GalaxyObject> children,
+        IReadOnlyList<bool> childHasChildren,
+        ulong cacheSequence)
+    {
+        BrowseChildrenReply reply = new() { TotalChildCount = children.Count, CacheSequence = cacheSequence };
+        reply.Children.AddRange(children);
+        reply.ChildHasChildren.AddRange(childHasChildren);
+        return reply;
+    }
+
+    private static GalaxyRepositoryClient CreateClient(FakeGalaxyRepositoryTransport transport)
+        => new(transport.Options, transport);
+
+    private static FakeGalaxyRepositoryTransport CreateTransport()
+        => new(new MxGatewayClientOptions
+        {
+            Endpoint = new Uri("http://localhost:5000"),
+            ApiKey = "test-api-key",
+        });
+}

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

@@ -11,6 +11,7 @@ namespace ZB.MOM.WW.MxGateway.Client.Tests;
 /// </summary>
 public sealed class MxGatewayClientAlarmsTests
 {
+    /// <summary>AcknowledgeAlarmAsync records request and returns reply.</summary>
     [Fact]
     public async Task AcknowledgeAlarmAsync_RecordsRequestShapeAndReturnsReply()
     {
@@ -46,6 +47,7 @@ public sealed class MxGatewayClientAlarmsTests
         Assert.Equal("Bearer test-api-key", call.CallOptions.Headers?.GetValue("authorization"));
     }
 
+    /// <summary>AcknowledgeAlarmAsync honors cancellation.</summary>
     [Fact]
     public async Task AcknowledgeAlarmAsync_HonorsCancellation()
     {
@@ -69,6 +71,7 @@ public sealed class MxGatewayClientAlarmsTests
                 cancellation.Token));
     }
 
+    /// <summary>AcknowledgeAlarmAsync maps unauthenticated RPC exception to typed exception.</summary>
     [Fact]
     public async Task AcknowledgeAlarmAsync_MapsUnauthenticated_RpcException_ToTypedException()
     {
@@ -93,6 +96,7 @@ public sealed class MxGatewayClientAlarmsTests
         Assert.Equal(StatusCode.Unauthenticated, ex.StatusCode);
     }
 
+    /// <summary>QueryActiveAlarmsAsync streams enqueued snapshots.</summary>
     [Fact]
     public async Task QueryActiveAlarmsAsync_StreamsEnqueuedSnapshots()
     {
@@ -117,6 +121,7 @@ public sealed class MxGatewayClientAlarmsTests
         Assert.Single(transport.QueryActiveAlarmsCalls);
     }
 
+    /// <summary>QueryActiveAlarmsAsync passes filter prefix.</summary>
     [Fact]
     public async Task QueryActiveAlarmsAsync_PassesFilterPrefix()
     {
@@ -136,6 +141,7 @@ public sealed class MxGatewayClientAlarmsTests
         Assert.Equal("Tank01.", call.Request.AlarmFilterPrefix);
     }
 
+    /// <summary>QueryActiveAlarmsAsync honors cancellation during enumeration.</summary>
     [Fact]
     public async Task QueryActiveAlarmsAsync_HonorsCancellationDuringEnumeration()
     {

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

@@ -82,6 +82,53 @@ public sealed class MxGatewayClientCliTests
         Assert.Equal(string.Empty, error.ToString());
     }
 
+    /// <summary>
+    /// Client.Dotnet-030: <c>advise-supervisory</c> was present in the command
+    /// dispatch table but absent from <see cref="MxGatewayClientCli"/>'s
+    /// <c>IsKnownGatewayCommand</c> guard, so the guard intercepted it first and
+    /// returned exit code 2 "Unknown command" before dispatch could run. This
+    /// test asserts the command is recognized (exit ≠ 2, stderr contains no
+    /// "Unknown command") and reaches the dispatch handler (exit 0, reply written
+    /// to stdout).
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_AdviseSupervisory_IsRecognizedAndReachesDispatch()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+        FakeCliClient fakeClient = new();
+        fakeClient.InvokeReplies.Enqueue(new MxCommandReply
+        {
+            SessionId = "session-fixture",
+            Kind = MxCommandKind.AdviseSupervisory,
+            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+        });
+
+        int exitCode = await MxGatewayClientCli.RunAsync(
+            [
+                "advise-supervisory",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+                "--session-id",
+                "session-fixture",
+                "--server-handle",
+                "12",
+                "--item-handle",
+                "34",
+                "--json",
+            ],
+            output,
+            error,
+            _ => fakeClient);
+
+        Assert.DoesNotContain("Unknown command", error.ToString());
+        Assert.Equal(0, exitCode);
+        Assert.Contains("MX_COMMAND_KIND_ADVISE_SUPERVISORY", output.ToString());
+        Assert.Equal(string.Empty, error.ToString());
+    }
+
     /// <summary>Verifies that error output redacts sensitive API key values.</summary>
     [Fact]
     public async Task RunAsync_ErrorOutput_RedactsApiKey()
@@ -106,6 +153,48 @@ public sealed class MxGatewayClientCliTests
         Assert.Contains("[redacted]", error.ToString());
     }
 
+    /// <summary>
+    /// Client.Dotnet-028: when the API key is sourced from the env var
+    /// (<c>--api-key-env</c> path, no <c>--api-key</c> flag), the error-redaction
+    /// catch block must still resolve and redact the effective key. Regression
+    /// guard for the catch block reverting to <c>GetOptional("api-key")</c> only,
+    /// which is null on the env-var path and leaves the key unredacted.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_ErrorOutput_RedactsApiKey_WhenSourcedFromEnvironmentVariable()
+    {
+        const string envName = "MXGATEWAY_TEST_API_KEY_028";
+        const string secret = "env-sourced-secret-key";
+        string? previousKey = Environment.GetEnvironmentVariable(envName);
+        Environment.SetEnvironmentVariable(envName, secret);
+
+        try
+        {
+            using var output = new StringWriter();
+            using var error = new StringWriter();
+
+            int exitCode = await MxGatewayClientCli.RunAsync(
+                [
+                    "open-session",
+                    "--endpoint",
+                    "http://localhost:5000",
+                    "--api-key-env",
+                    envName,
+                ],
+                output,
+                error,
+                _ => throw new InvalidOperationException($"boom {secret}"));
+
+            Assert.Equal(1, exitCode);
+            Assert.DoesNotContain(secret, error.ToString());
+            Assert.Contains("[redacted]", error.ToString());
+        }
+        finally
+        {
+            Environment.SetEnvironmentVariable(envName, previousKey);
+        }
+    }
+
     /// <summary>Verifies that stream-events with max-events limit stops output in non-JSON format.</summary>
     [Fact]
     public async Task RunAsync_StreamEvents_WithMaxEventsStopsNonJsonOutput()
@@ -148,6 +237,87 @@ public sealed class MxGatewayClientCliTests
     }
 
 
+    /// <summary>Verifies that stream-alarms with --max-events stops output and distinguishes payload cases.</summary>
+    [Fact]
+    public async Task RunAsync_StreamAlarms_WithMaxEventsStopsAndDistinguishesPayloadCases()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+        FakeCliClient fakeClient = new();
+        fakeClient.AlarmFeedMessages.Add(new AlarmFeedMessage
+        {
+            ActiveAlarm = new ActiveAlarmSnapshot { AlarmFullReference = "Tank01.Level.HiHi" },
+        });
+        fakeClient.AlarmFeedMessages.Add(new AlarmFeedMessage { SnapshotComplete = true });
+
+        int exitCode = await MxGatewayClientCli.RunAsync(
+            [
+                "stream-alarms",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+                "--filter-prefix",
+                "Tank01",
+                "--max-events",
+                "1",
+            ],
+            output,
+            error,
+            _ => fakeClient);
+
+        Assert.Equal(0, exitCode);
+        StreamAlarmsRequest request = Assert.Single(fakeClient.StreamAlarmsRequests);
+        Assert.Equal("Tank01", request.AlarmFilterPrefix);
+        string text = output.ToString();
+        Assert.Contains("active-alarm", text);
+        Assert.Contains("Tank01.Level.HiHi", text);
+        Assert.DoesNotContain("snapshot-complete", text);
+        Assert.Equal(string.Empty, error.ToString());
+    }
+
+    /// <summary>Verifies that acknowledge-alarm builds a request and prints the JSON reply.</summary>
+    [Fact]
+    public async Task RunAsync_AcknowledgeAlarm_BuildsRequestAndPrintsJsonReply()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+        FakeCliClient fakeClient = new();
+        fakeClient.AcknowledgeAlarmReplies.Enqueue(new AcknowledgeAlarmReply
+        {
+            CorrelationId = "ack-fixture",
+            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+            Hresult = 0,
+        });
+
+        int exitCode = await MxGatewayClientCli.RunAsync(
+            [
+                "acknowledge-alarm",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+                "--reference",
+                "Tank01.Level.HiHi",
+                "--comment",
+                "ack from cli",
+                "--operator",
+                "operator1",
+                "--json",
+            ],
+            output,
+            error,
+            _ => fakeClient);
+
+        Assert.Equal(0, exitCode);
+        AcknowledgeAlarmRequest request = Assert.Single(fakeClient.AcknowledgeAlarmRequests);
+        Assert.Equal("Tank01.Level.HiHi", request.AlarmFullReference);
+        Assert.Equal("ack from cli", request.Comment);
+        Assert.Equal("operator1", request.OperatorUser);
+        Assert.Contains("ack-fixture", output.ToString());
+        Assert.Equal(string.Empty, error.ToString());
+    }
+
     /// <summary>Verifies that smoke command closes opened session when a command fails.</summary>
     [Fact]
     public async Task RunAsync_Smoke_WhenCommandFails_ClosesOpenedSession()
@@ -279,6 +449,146 @@ public sealed class MxGatewayClientCliTests
         Assert.Equal(string.Empty, error.ToString());
     }
 
+    /// <summary>
+    /// Verifies galaxy-browse walks root objects and eagerly expands one further
+    /// level when --depth 1 is passed, printing an indented tree.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_GalaxyBrowse_TextTreeExpandsToDepth()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+        FakeCliClient fakeClient = new();
+        // Root level (parent 0): one area with a child hint.
+        fakeClient.GalaxyBrowseChildrenReplies[0] = new Queue<BrowseChildrenReply>(
+        [
+            new BrowseChildrenReply
+            {
+                Children = { new GalaxyObject { GobjectId = 10, TagName = "Area_001", BrowseName = "Area" } },
+                ChildHasChildren = { true },
+            },
+        ]);
+        // Children of gobject 10.
+        fakeClient.GalaxyBrowseChildrenReplies[10] = new Queue<BrowseChildrenReply>(
+        [
+            new BrowseChildrenReply
+            {
+                Children = { new GalaxyObject { GobjectId = 20, TagName = "Tank_001", BrowseName = "Tank" } },
+            },
+        ]);
+
+        int exitCode = await MxGatewayClientCli.RunAsync(
+            [
+                "galaxy-browse",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+                "--depth",
+                "1",
+            ],
+            output,
+            error,
+            _ => fakeClient);
+
+        Assert.Equal(0, exitCode);
+        string text = output.ToString();
+        Assert.Contains("Area_001", text);
+        Assert.Contains("Tank_001", text);
+        // Children are indented beneath their parent (two-space indent per level).
+        Assert.Matches(@"\n  \d+\tTank_001", text);
+        // Root fetched with the parent oneof unset; child fetch used parent 10.
+        Assert.Contains(
+            fakeClient.GalaxyBrowseChildrenRequests,
+            request => request.ParentCase == BrowseChildrenRequest.ParentOneofCase.ParentGobjectId
+                && request.ParentGobjectId == 10);
+        Assert.Equal(string.Empty, error.ToString());
+    }
+
+    /// <summary>
+    /// Verifies galaxy-browse --json emits a nested JSON document and forwards
+    /// the filter flags onto the BrowseChildren request.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_GalaxyBrowse_JsonForwardsFilters()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+        FakeCliClient fakeClient = new();
+        fakeClient.GalaxyBrowseChildrenReplies[0] = new Queue<BrowseChildrenReply>(
+        [
+            new BrowseChildrenReply
+            {
+                Children = { new GalaxyObject { GobjectId = 10, TagName = "Area_001", BrowseName = "Area" } },
+            },
+        ]);
+
+        int exitCode = await MxGatewayClientCli.RunAsync(
+            [
+                "galaxy-browse",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+                "--tag-name-glob",
+                "Area*",
+                "--alarm-bearing-only",
+                "--json",
+            ],
+            output,
+            error,
+            _ => fakeClient);
+
+        Assert.Equal(0, exitCode);
+        using System.Text.Json.JsonDocument document = System.Text.Json.JsonDocument.Parse(output.ToString());
+        Assert.Equal("galaxy-browse", document.RootElement.GetProperty("command").GetString());
+        Assert.True(document.RootElement.GetProperty("nodes").GetArrayLength() >= 1);
+        BrowseChildrenRequest request = Assert.Single(fakeClient.GalaxyBrowseChildrenRequests);
+        Assert.Equal("Area*", request.TagNameGlob);
+        Assert.True(request.AlarmBearingOnly);
+        Assert.Equal(string.Empty, error.ToString());
+    }
+
+    /// <summary>
+    /// Verifies galaxy-browse --parent fetches exactly one level of children for
+    /// the supplied gobject id via a parent-scoped BrowseChildren request.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_GalaxyBrowse_ParentFetchesSingleLevel()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+        FakeCliClient fakeClient = new();
+        fakeClient.GalaxyBrowseChildrenReplies[10] = new Queue<BrowseChildrenReply>(
+        [
+            new BrowseChildrenReply
+            {
+                Children = { new GalaxyObject { GobjectId = 20, TagName = "Tank_001", BrowseName = "Tank" } },
+            },
+        ]);
+
+        int exitCode = await MxGatewayClientCli.RunAsync(
+            [
+                "galaxy-browse",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+                "--parent",
+                "10",
+            ],
+            output,
+            error,
+            _ => fakeClient);
+
+        Assert.Equal(0, exitCode);
+        Assert.Contains("Tank_001", output.ToString());
+        BrowseChildrenRequest request = Assert.Single(fakeClient.GalaxyBrowseChildrenRequests);
+        Assert.Equal(BrowseChildrenRequest.ParentOneofCase.ParentGobjectId, request.ParentCase);
+        Assert.Equal(10, request.ParentGobjectId);
+        Assert.Equal(string.Empty, error.ToString());
+    }
+
     /// <summary>Verifies that galaxy-watch command prints text output for deploy events.</summary>
     [Fact]
     public async Task RunAsync_GalaxyWatch_PrintsTextOutputForEvents()
@@ -428,6 +738,356 @@ public sealed class MxGatewayClientCliTests
         Assert.Contains("gateway-protocol=", text);
     }
 
+    /// <summary>
+    /// Client.Dotnet-018: the README CLI examples for the alarm subcommands at
+    /// `clients/dotnet/README.md` must drive cleanly through the production
+    /// CLI argument parser. The previous text used non-existent flags
+    /// (`--session-id`, `--max-messages`, `--alarm-reference`) that would
+    /// fail with "Unknown command" / "Missing required option --reference".
+    /// Each documented example is extracted from the README, parsed via the
+    /// production <see cref="MxGatewayClientCli.RunAsync"/>, and asserted
+    /// against exit code 0.
+    /// </summary>
+    /// <param name="command">The alarm subcommand to validate (e.g. "stream-alarms", "acknowledge-alarm").</param>
+    [Theory]
+    [InlineData("stream-alarms")]
+    [InlineData("acknowledge-alarm")]
+    public async Task RunAsync_ReadmeExamples_ForAlarmCommands_ParseSuccessfully(string command)
+    {
+        string readme = LocateClientReadme();
+        string[] commandLine = ExtractReadmeCommandLine(readme, command);
+        // The documented examples do not include --api-key (the README assumes
+        // the env var path documented elsewhere). Inject an API key via the
+        // standard env var so CreateOptions succeeds and the parser fully
+        // exercises the documented flag shape.
+        string? previousKey = Environment.GetEnvironmentVariable("MXGATEWAY_API_KEY");
+        Environment.SetEnvironmentVariable("MXGATEWAY_API_KEY", "test-api-key");
+
+        try
+        {
+            using var output = new StringWriter();
+            using var error = new StringWriter();
+            FakeCliClient fakeClient = new();
+            fakeClient.AlarmFeedMessages.Add(new AlarmFeedMessage
+            {
+                ActiveAlarm = new ActiveAlarmSnapshot { AlarmFullReference = "fixture" },
+            });
+            fakeClient.AcknowledgeAlarmReplies.Enqueue(new AcknowledgeAlarmReply
+            {
+                CorrelationId = "ack-fixture",
+                ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+            });
+
+            int exitCode = await MxGatewayClientCli.RunAsync(
+                commandLine,
+                output,
+                error,
+                _ => fakeClient);
+
+            Assert.True(
+                exitCode == 0,
+                $"README example for '{command}' exited {exitCode}; stderr=<<{error}>>");
+            Assert.DoesNotContain("Unknown command", error.ToString());
+            Assert.DoesNotContain("Missing required option", error.ToString());
+        }
+        finally
+        {
+            Environment.SetEnvironmentVariable("MXGATEWAY_API_KEY", previousKey);
+        }
+    }
+
+    /// <summary>
+    /// Client.Dotnet-019: `BenchReadBulkAsync` previously fell back to
+    /// <c>reply.ReturnValue.Int32Value</c> when the register reply had no
+    /// typed <c>Register</c> payload, silently driving the rest of the bench
+    /// against a zero server handle. The fix must fail loudly with a
+    /// descriptive <see cref="MxGatewayException"/>.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_BenchReadBulk_WhenRegisterReplyMissingTypedPayload_FailsLoudly()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+        FakeCliClient fakeClient = new();
+        // Successful protocol + MX status but no typed `Register` payload.
+        // Before the Client.Dotnet-019 fix this silently became serverHandle=0
+        // and the bench proceeded through SubscribeBulk / warmup / steady-state
+        // against an invalid handle, producing a misleading zero-result summary.
+        fakeClient.InvokeReplies.Enqueue(new MxCommandReply
+        {
+            SessionId = "session-fixture",
+            Kind = MxCommandKind.Register,
+            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+        });
+
+        int exitCode = await MxGatewayClientCli.RunAsync(
+            [
+                "bench-read-bulk",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+                "--duration-seconds",
+                "1",
+                "--warmup-seconds",
+                "0",
+                "--bulk-size",
+                "1",
+            ],
+            output,
+            error,
+            _ => fakeClient);
+
+        Assert.Equal(1, exitCode);
+        // Descriptive message that names the missing typed payload.
+        string err = error.ToString();
+        Assert.Contains("Register", err);
+        // The bench must not produce any aggregate stats JSON.
+        Assert.DoesNotContain("bench-read-bulk", output.ToString());
+    }
+
+    /// <summary>
+    /// Client.Dotnet-020: the steady-state loop in `BenchReadBulkAsync` had a
+    /// bare `catch { failedCalls++; continue; }` that swallowed
+    /// <see cref="OperationCanceledException"/>, so token-driven cancellation
+    /// kept spinning until <c>--duration-seconds</c> elapsed. After the fix
+    /// the bench must exit promptly when the supplied token cancels.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_BenchReadBulk_WhenSteadyStateLoopReceivesCancellation_ExitsPromptly()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+
+        int invokeCount = 0;
+        FakeCliClient fakeClient = new()
+        {
+            InvokeHandler = (request, ct) =>
+            {
+                int n = Interlocked.Increment(ref invokeCount);
+
+                // Reply 1 = Register (success with typed payload).
+                if (request.Command.Kind == MxCommandKind.Register)
+                {
+                    return Task.FromResult(new MxCommandReply
+                    {
+                        SessionId = "session-fixture",
+                        Kind = MxCommandKind.Register,
+                        ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+                        Register = new RegisterReply { ServerHandle = 1 },
+                    });
+                }
+
+                // Reply 2 = SubscribeBulk (success).
+                if (request.Command.Kind == MxCommandKind.SubscribeBulk)
+                {
+                    var subscribeReply = new MxCommandReply
+                    {
+                        SessionId = "session-fixture",
+                        Kind = MxCommandKind.SubscribeBulk,
+                        ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+                        SubscribeBulk = new BulkSubscribeReply(),
+                    };
+                    return Task.FromResult(subscribeReply);
+                }
+
+                // ReadBulk reply 1 = success (so the steady-state loop enters
+                // and starts iterating). Reply 2+ = simulated cancellation.
+                if (request.Command.Kind == MxCommandKind.ReadBulk && n <= 3)
+                {
+                    return Task.FromResult(new MxCommandReply
+                    {
+                        SessionId = "session-fixture",
+                        Kind = MxCommandKind.ReadBulk,
+                        ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+                        ReadBulk = new BulkReadReply(),
+                    });
+                }
+
+                // From here on every ReadBulk throws OCE — the steady-state
+                // loop must exit promptly rather than spinning until
+                // --duration-seconds elapses.
+                throw new OperationCanceledException();
+            },
+        };
+
+        var sw = System.Diagnostics.Stopwatch.StartNew();
+        await Assert.ThrowsAsync<OperationCanceledException>(async () =>
+            await MxGatewayClientCli.RunAsync(
+                [
+                    "bench-read-bulk",
+                    "--endpoint",
+                    "http://localhost:5000",
+                    "--api-key",
+                    "test-api-key",
+                    "--duration-seconds",
+                    "30",
+                    "--warmup-seconds",
+                    "0",
+                    "--bulk-size",
+                    "1",
+                ],
+                output,
+                error,
+                _ => fakeClient));
+        sw.Stop();
+
+        // Without the fix the loop swallows OCE and continues until the 30 s
+        // steady-state deadline expires. With the fix it exits as soon as OCE
+        // surfaces. Generous 10 s ceiling to keep the test stable under load.
+        Assert.True(
+            sw.Elapsed < TimeSpan.FromSeconds(10),
+            $"Bench did not exit promptly on cancellation; took {sw.Elapsed}.");
+    }
+
+    /// <summary>
+    /// Client.Dotnet-021: both `ReadBulkAsync` and `BenchReadBulkAsync` cast
+    /// the user-supplied <c>--timeout-ms</c> to <see cref="uint"/> without
+    /// bounds checking, so a negative value (e.g. <c>-1</c>) silently wraps
+    /// to ~49.7 days. The fix must reject negatives with a clear error.
+    /// </summary>
+    /// <param name="command">The bulk-read subcommand to validate (e.g. "read-bulk", "bench-read-bulk").</param>
+    [Theory]
+    [InlineData("read-bulk")]
+    [InlineData("bench-read-bulk")]
+    public async Task RunAsync_TimeoutMs_NegativeValue_RejectsWithClearError(string command)
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+        FakeCliClient fakeClient = new();
+
+        string[] args = command is "read-bulk"
+            ? [
+                "read-bulk",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+                "--session-id",
+                "session-fixture",
+                "--server-handle",
+                "1",
+                "--items",
+                "Area001.Pump001.Speed",
+                "--timeout-ms",
+                "-1",
+            ]
+            : [
+                "bench-read-bulk",
+                "--endpoint",
+                "http://localhost:5000",
+                "--api-key",
+                "test-api-key",
+                "--duration-seconds",
+                "1",
+                "--warmup-seconds",
+                "0",
+                "--bulk-size",
+                "1",
+                "--timeout-ms",
+                "-1",
+            ];
+
+        int exitCode = await MxGatewayClientCli.RunAsync(
+            args,
+            output,
+            error,
+            _ => fakeClient);
+
+        Assert.NotEqual(0, exitCode);
+        string err = error.ToString();
+        Assert.Contains("timeout-ms", err);
+        Assert.Contains("non-negative", err);
+    }
+
+    /// <summary>
+    /// Locates the .NET client README by walking up from the test assembly's
+    /// base directory until <c>clients/dotnet/README.md</c> is found. Keeps
+    /// the regression test independent of the current working directory.
+    /// </summary>
+    private static string LocateClientReadme()
+    {
+        string? directory = AppContext.BaseDirectory;
+        while (!string.IsNullOrEmpty(directory))
+        {
+            string candidate = Path.Combine(directory, "clients", "dotnet", "README.md");
+            if (File.Exists(candidate))
+            {
+                return candidate;
+            }
+
+            directory = Path.GetDirectoryName(directory);
+        }
+
+        throw new FileNotFoundException("clients/dotnet/README.md not found above test assembly base directory.");
+    }
+
+    /// <summary>
+    /// Extracts the documented CLI invocation for the requested subcommand
+    /// from the README, returning only the arguments after the
+    /// <c>mxgw-dotnet</c>-equivalent prefix so they can be passed straight
+    /// to <see cref="MxGatewayClientCli.RunAsync"/>.
+    /// </summary>
+    private static string[] ExtractReadmeCommandLine(string readmePath, string command)
+    {
+        string[] lines = File.ReadAllLines(readmePath);
+        // Look for the documented `dotnet run ... -- <command> ...` line.
+        foreach (string line in lines)
+        {
+            int dashes = line.IndexOf("-- " + command, StringComparison.Ordinal);
+            if (dashes < 0)
+            {
+                continue;
+            }
+
+            string after = line[(dashes + 3)..].Trim();
+            // Tokenize by whitespace, respecting "..." quoted segments.
+            return TokenizeCommandLine(after);
+        }
+
+        throw new InvalidOperationException(
+            $"README at '{readmePath}' has no documented example for subcommand '{command}'.");
+    }
+
+    /// <summary>
+    /// Splits a single command-line string into argv tokens, honouring
+    /// double-quoted segments so paths with embedded spaces survive intact.
+    /// </summary>
+    private static string[] TokenizeCommandLine(string input)
+    {
+        var tokens = new List<string>();
+        var current = new System.Text.StringBuilder();
+        bool inQuotes = false;
+
+        foreach (char ch in input)
+        {
+            if (ch == '"')
+            {
+                inQuotes = !inQuotes;
+                continue;
+            }
+
+            if (!inQuotes && char.IsWhiteSpace(ch))
+            {
+                if (current.Length > 0)
+                {
+                    tokens.Add(current.ToString());
+                    current.Clear();
+                }
+                continue;
+            }
+
+            current.Append(ch);
+        }
+
+        if (current.Length > 0)
+        {
+            tokens.Add(current.ToString());
+        }
+
+        return tokens.ToArray();
+    }
+
     /// <summary>Fake CLI client for testing.</summary>
     private sealed class FakeCliClient : IMxGatewayCliClient
     {
@@ -446,6 +1106,9 @@ public sealed class MxGatewayClientCliTests
         /// <summary>Exception to throw on invoke, if any.</summary>
         public Exception? InvokeFailure { get; init; }
 
+        /// <summary>Optional per-call handler that overrides queue-based behaviour.</summary>
+        public Func<MxCommandRequest, CancellationToken, Task<MxCommandReply>>? InvokeHandler { get; init; }
+
         /// <inheritdoc />
         public ValueTask DisposeAsync()
         {
@@ -491,6 +1154,11 @@ public sealed class MxGatewayClientCliTests
                 throw InvokeFailure;
             }
 
+            if (InvokeHandler is not null)
+            {
+                return InvokeHandler(request, cancellationToken);
+            }
+
             return Task.FromResult(InvokeReplies.Dequeue());
         }
 
@@ -507,6 +1175,41 @@ public sealed class MxGatewayClientCliTests
             }
         }
 
+        /// <summary>Queue of acknowledge-alarm replies to return.</summary>
+        public Queue<AcknowledgeAlarmReply> AcknowledgeAlarmReplies { get; } = new();
+
+        /// <summary>List of received acknowledge-alarm requests.</summary>
+        public List<AcknowledgeAlarmRequest> AcknowledgeAlarmRequests { get; } = [];
+
+        /// <summary>List of received stream-alarms requests.</summary>
+        public List<StreamAlarmsRequest> StreamAlarmsRequests { get; } = [];
+
+        /// <summary>List of alarm feed messages to yield when streaming alarms.</summary>
+        public List<AlarmFeedMessage> AlarmFeedMessages { get; } = [];
+
+        /// <inheritdoc />
+        public Task<AcknowledgeAlarmReply> AcknowledgeAlarmAsync(
+            AcknowledgeAlarmRequest request,
+            CancellationToken cancellationToken)
+        {
+            AcknowledgeAlarmRequests.Add(request);
+            return Task.FromResult(AcknowledgeAlarmReplies.Dequeue());
+        }
+
+        /// <inheritdoc />
+        public async IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
+            StreamAlarmsRequest request,
+            [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken)
+        {
+            StreamAlarmsRequests.Add(request);
+            foreach (AlarmFeedMessage feedMessage in AlarmFeedMessages)
+            {
+                cancellationToken.ThrowIfCancellationRequested();
+                await Task.Yield();
+                yield return feedMessage;
+            }
+        }
+
         /// <summary>Galaxy test connection reply to return.</summary>
         public TestConnectionReply GalaxyTestConnectionReply { get; set; } = new() { Ok = true };
 
@@ -516,6 +1219,7 @@ public sealed class MxGatewayClientCliTests
         /// <summary>Galaxy discover hierarchy reply to return.</summary>
         public DiscoverHierarchyReply GalaxyDiscoverHierarchyReply { get; set; } = new();
 
+        /// <summary>Queue of galaxy discover hierarchy replies to return.</summary>
         public Queue<DiscoverHierarchyReply> GalaxyDiscoverHierarchyReplies { get; } = new();
 
         /// <summary>List of received galaxy test connection requests.</summary>
@@ -576,5 +1280,33 @@ public sealed class MxGatewayClientCliTests
                 yield return deployEvent;
             }
         }
+
+        /// <summary>List of received galaxy browse-children requests, in call order.</summary>
+        public List<BrowseChildrenRequest> GalaxyBrowseChildrenRequests { get; } = [];
+
+        /// <summary>
+        /// Per-parent browse-children replies keyed by <c>parent_gobject_id</c>
+        /// (0 = root). Each parent's queue is dequeued in page order; an absent
+        /// or exhausted queue yields an empty reply.
+        /// </summary>
+        public Dictionary<int, Queue<BrowseChildrenReply>> GalaxyBrowseChildrenReplies { get; } = [];
+
+        /// <inheritdoc />
+        public Task<BrowseChildrenReply> GalaxyBrowseChildrenAsync(
+            BrowseChildrenRequest request,
+            CancellationToken cancellationToken)
+        {
+            GalaxyBrowseChildrenRequests.Add(request);
+            int parentId = request.ParentCase == BrowseChildrenRequest.ParentOneofCase.ParentGobjectId
+                ? request.ParentGobjectId
+                : 0;
+            if (GalaxyBrowseChildrenReplies.TryGetValue(parentId, out Queue<BrowseChildrenReply>? queue)
+                && queue.TryDequeue(out BrowseChildrenReply? reply))
+            {
+                return Task.FromResult(reply);
+            }
+
+            return Task.FromResult(new BrowseChildrenReply());
+        }
     }
 }

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

@@ -303,6 +303,69 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal(cancellation.Token, Assert.Single(transport.InvokeCalls).CallOptions.CancellationToken);
     }
 
+    /// <summary>Verifies that BuildSparseArray produces a SparseArrayValue MxValue with the correct total length and elements.</summary>
+    [Fact]
+    public void BuildSparseArray_ProducesSparseArrayValueWithCorrectTotalLengthAndElements()
+    {
+        MxValue element0 = 42.ToMxValue();
+        MxValue element3 = 99.ToMxValue();
+        Dictionary<uint, MxValue> elements = new()
+        {
+            [0u] = element0,
+            [3u] = element3,
+        };
+
+        MxValue result = MxGatewaySession.BuildSparseArray(MxDataType.Integer, totalLength: 10, elements);
+
+        Assert.Equal(MxValue.KindOneofCase.SparseArrayValue, result.KindCase);
+        Assert.Equal(10u, result.SparseArrayValue.TotalLength);
+        Assert.Equal(MxDataType.Integer, result.SparseArrayValue.ElementDataType);
+        Assert.Equal(2, result.SparseArrayValue.Elements.Count);
+
+        MxSparseElement el0 = Assert.Single(result.SparseArrayValue.Elements, e => e.Index == 0u);
+        Assert.Same(element0, el0.Value);
+
+        MxSparseElement el3 = Assert.Single(result.SparseArrayValue.Elements, e => e.Index == 3u);
+        Assert.Same(element3, el3.Value);
+    }
+
+    /// <summary>Verifies that WriteArrayElementsAsync builds a write command whose value is a SparseArrayValue.</summary>
+    [Fact]
+    public async Task WriteArrayElementsAsync_BuildsWriteCommandWithSparseArrayValue()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.AddInvokeReply(new MxCommandReply
+        {
+            SessionId = "session-fixture",
+            Kind = MxCommandKind.Write,
+            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+        });
+        await using MxGatewayClient client = CreateClient(transport);
+        MxGatewaySession session = await client.OpenSessionAsync();
+        Dictionary<uint, MxValue> elements = new() { [1u] = 7.ToMxValue() };
+
+        await session.WriteArrayElementsAsync(
+            serverHandle: 12,
+            itemHandle: 34,
+            elementDataType: MxDataType.Integer,
+            totalLength: 5,
+            elements: elements,
+            userId: 56);
+
+        MxCommandRequest request = Assert.Single(transport.InvokeCalls).Request;
+        Assert.Equal(MxCommandKind.Write, request.Command.Kind);
+        Assert.Equal(12, request.Command.Write.ServerHandle);
+        Assert.Equal(34, request.Command.Write.ItemHandle);
+        Assert.Equal(56, request.Command.Write.UserId);
+        MxValue written = request.Command.Write.Value;
+        Assert.Equal(MxValue.KindOneofCase.SparseArrayValue, written.KindCase);
+        Assert.Equal(5u, written.SparseArrayValue.TotalLength);
+        Assert.Equal(MxDataType.Integer, written.SparseArrayValue.ElementDataType);
+        MxSparseElement el = Assert.Single(written.SparseArrayValue.Elements);
+        Assert.Equal(1u, el.Index);
+        Assert.Equal(7, el.Value.Int32Value);
+    }
+
     private static MxGatewayClient CreateClient(FakeGatewayTransport transport)
     {
         return new MxGatewayClient(transport.Options, transport);

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

@@ -0,0 +1,85 @@
+using System.Net.Http;
+using System.Net.Security;
+using ZB.MOM.WW.MxGateway.Client;
+
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
+
+public sealed class MxGatewayClientTlsHandlerTests
+{
+    /// <summary>
+    /// Verifies that when TLS is used with no pinned CA and RequireCertificateValidation is false (default),
+    /// the handler installs an accept-all callback so the gateway's self-signed cert is trusted.
+    /// The callback must return true regardless of chain errors.
+    /// </summary>
+    [Fact]
+    public void Handler_SkipsVerification_WhenTlsAndNoCaPinned()
+    {
+        MxGatewayClientOptions options = new()
+        {
+            Endpoint = new Uri("https://localhost:5120"),
+            ApiKey = "k",
+            UseTls = true,
+        };
+        using SocketsHttpHandler handler = MxGatewayClient.CreateHttpHandlerForTests(options);
+        Assert.NotNull(handler.SslOptions.RemoteCertificateValidationCallback);
+        Assert.True(handler.SslOptions.RemoteCertificateValidationCallback!(null!, null!, null, SslPolicyErrors.RemoteCertificateChainErrors));
+    }
+
+    /// <summary>
+    /// Verifies that when RequireCertificateValidation is true, the callback is left null
+    /// so the OS trust store performs validation.
+    /// </summary>
+    [Fact]
+    public void Handler_KeepsDefaultVerification_WhenRequireCertificateValidation()
+    {
+        MxGatewayClientOptions options = new()
+        {
+            Endpoint = new Uri("https://localhost:5120"),
+            ApiKey = "k",
+            UseTls = true,
+            RequireCertificateValidation = true,
+        };
+        using SocketsHttpHandler handler = MxGatewayClient.CreateHttpHandlerForTests(options);
+        Assert.Null(handler.SslOptions.RemoteCertificateValidationCallback);
+    }
+}
+
+public sealed class GalaxyRepositoryClientTlsHandlerTests
+{
+    /// <summary>
+    /// Verifies that when TLS is used with no pinned CA and RequireCertificateValidation is false (default),
+    /// the Galaxy client handler installs an accept-all callback so the gateway's self-signed cert is trusted.
+    /// The callback must return true regardless of chain errors.
+    /// </summary>
+    [Fact]
+    public void Handler_SkipsVerification_WhenTlsAndNoCaPinned()
+    {
+        MxGatewayClientOptions options = new()
+        {
+            Endpoint = new Uri("https://localhost:5120"),
+            ApiKey = "k",
+            UseTls = true,
+        };
+        using SocketsHttpHandler handler = GalaxyRepositoryClient.CreateHttpHandlerForTests(options);
+        Assert.NotNull(handler.SslOptions.RemoteCertificateValidationCallback);
+        Assert.True(handler.SslOptions.RemoteCertificateValidationCallback!(null!, null!, null, SslPolicyErrors.RemoteCertificateChainErrors));
+    }
+
+    /// <summary>
+    /// Verifies that when RequireCertificateValidation is true, the Galaxy client callback is left null
+    /// so the OS trust store performs validation.
+    /// </summary>
+    [Fact]
+    public void Handler_KeepsDefaultVerification_WhenRequireCertificateValidation()
+    {
+        MxGatewayClientOptions options = new()
+        {
+            Endpoint = new Uri("https://localhost:5120"),
+            ApiKey = "k",
+            UseTls = true,
+            RequireCertificateValidation = true,
+        };
+        using SocketsHttpHandler handler = GalaxyRepositoryClient.CreateHttpHandlerForTests(options);
+        Assert.Null(handler.SslOptions.RemoteCertificateValidationCallback);
+    }
+}

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

@@ -0,0 +1,26 @@
+namespace ZB.MOM.WW.MxGateway.Client;
+
+/// <summary>
+///     Filters and shape options for <see cref="GalaxyRepositoryClient.BrowseAsync(BrowseChildrenOptions, System.Threading.CancellationToken)"/>.
+///     Mirror of <see cref="DiscoverHierarchyOptions"/> for the lazy-browse path.
+/// </summary>
+public sealed class BrowseChildrenOptions
+{
+    /// <summary>Restrict to children whose Galaxy category is in this set.</summary>
+    public IReadOnlyList<int> CategoryIds { get; init; } = [];
+
+    /// <summary>Restrict to children whose template chain contains any of these tokens.</summary>
+    public IReadOnlyList<string> TemplateChainContains { get; init; } = [];
+
+    /// <summary>Optional glob-style filter on <c>tag_name</c>.</summary>
+    public string? TagNameGlob { get; init; }
+
+    /// <summary>Whether to populate each <c>GalaxyObject.Attributes</c>. Null leaves the server default.</summary>
+    public bool? IncludeAttributes { get; init; }
+
+    /// <summary>Restrict to children that bear at least one alarm attribute.</summary>
+    public bool AlarmBearingOnly { get; init; }
+
+    /// <summary>Restrict to children that have at least one historized attribute.</summary>
+    public bool HistorizedOnly { get; init; }
+}

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

@@ -19,6 +19,7 @@ namespace ZB.MOM.WW.MxGateway.Client;
 public sealed class GalaxyRepositoryClient : IAsyncDisposable
 {
     private const int DiscoverHierarchyPageSize = 5000;
+    private const int BrowseChildrenPageSize = 500;
 
     private readonly GrpcChannel? _channel;
     private readonly IGalaxyRepositoryClientTransport _transport;
@@ -182,6 +183,10 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
         return await DiscoverHierarchyAsync(new DiscoverHierarchyOptions(), cancellationToken).ConfigureAwait(false);
     }
 
+    /// <summary>Discovers the Galaxy object hierarchy.</summary>
+    /// <param name="options">Client configuration options.</param>
+    /// <param name="cancellationToken">Token to observe for cancellation.</param>
+    /// <returns>The collection of Galaxy objects in the hierarchy.</returns>
     public async Task<IReadOnlyList<GalaxyObject>> DiscoverHierarchyAsync(
         DiscoverHierarchyOptions options,
         CancellationToken cancellationToken = default)
@@ -274,6 +279,89 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
             cancellationToken);
     }
 
+    /// <summary>Returns root-level browse nodes (objects with no parent).</summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The list of root <see cref="LazyBrowseNode"/> instances.</returns>
+    public Task<IReadOnlyList<LazyBrowseNode>> BrowseAsync(CancellationToken cancellationToken = default)
+        => BrowseAsync(null, cancellationToken);
+
+    /// <summary>Returns root-level browse nodes filtered by the given options.</summary>
+    /// <param name="options">Browse filter options. Null applies no filter.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The list of root <see cref="LazyBrowseNode"/> instances.</returns>
+    public async Task<IReadOnlyList<LazyBrowseNode>> BrowseAsync(
+        BrowseChildrenOptions? options,
+        CancellationToken cancellationToken = default)
+    {
+        BrowseChildrenOptions effective = options ?? new BrowseChildrenOptions();
+        List<LazyBrowseNode> roots = [];
+        string pageToken = string.Empty;
+        HashSet<string> seenPageTokens = new(StringComparer.Ordinal);
+        do
+        {
+            BrowseChildrenRequest request = BuildBrowseChildrenRequest(effective);
+            request.PageToken = pageToken;
+            BrowseChildrenReply reply = await BrowseChildrenRawAsync(request, cancellationToken).ConfigureAwait(false);
+
+            for (int i = 0; i < reply.Children.Count; i++)
+            {
+                bool hint = i < reply.ChildHasChildren.Count && reply.ChildHasChildren[i];
+                roots.Add(new LazyBrowseNode(this, reply.Children[i], hint, effective));
+            }
+
+            pageToken = reply.NextPageToken;
+            if (!string.IsNullOrWhiteSpace(pageToken) && !seenPageTokens.Add(pageToken))
+            {
+                throw new MxGatewayException(
+                    $"Galaxy BrowseChildren returned a repeated page token '{pageToken}'.");
+            }
+        }
+        while (!string.IsNullOrWhiteSpace(pageToken));
+
+        return roots;
+    }
+
+    /// <summary>Issues a raw BrowseChildren RPC without result wrapping.</summary>
+    /// <param name="request">The browse-children request.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The raw server reply.</returns>
+    public Task<BrowseChildrenReply> BrowseChildrenRawAsync(
+        BrowseChildrenRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ThrowIfDisposed();
+
+        return ExecuteSafeUnaryAsync(
+            token => _transport.BrowseChildrenAsync(request, CreateCallOptions(token)),
+            cancellationToken);
+    }
+
+    internal static BrowseChildrenRequest BuildBrowseChildrenRequest(BrowseChildrenOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        BrowseChildrenRequest request = new()
+        {
+            PageSize = BrowseChildrenPageSize,
+            AlarmBearingOnly = options.AlarmBearingOnly,
+            HistorizedOnly = options.HistorizedOnly,
+        };
+        request.CategoryIds.Add(options.CategoryIds);
+        request.TemplateChainContains.Add(options.TemplateChainContains);
+        if (!string.IsNullOrWhiteSpace(options.TagNameGlob))
+        {
+            request.TagNameGlob = options.TagNameGlob;
+        }
+
+        if (options.IncludeAttributes.HasValue)
+        {
+            request.IncludeAttributes = options.IncludeAttributes.Value;
+        }
+
+        return request;
+    }
+
     /// <summary>
     /// Subscribes to Galaxy deploy events. The server emits a bootstrap event with the
     /// current state on subscribe so callers can prime their cache, then emits one event
@@ -402,7 +490,10 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
             .ConfigureAwait(false);
     }
 
-    private static HttpMessageHandler CreateHttpHandler(MxGatewayClientOptions options)
+    private static HttpMessageHandler CreateHttpHandler(MxGatewayClientOptions options) =>
+        CreateHttpHandlerForTests(options);
+
+    internal static SocketsHttpHandler CreateHttpHandlerForTests(MxGatewayClientOptions options)
     {
         SocketsHttpHandler handler = new()
         {
@@ -422,6 +513,11 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
                 X509Certificate2 trustedRoot = X509CertificateLoader.LoadCertificateFromFile(options.CaCertificatePath);
                 handler.SslOptions.RemoteCertificateValidationCallback = (_, certificate, chain, errors) =>
                 {
+                    if ((errors & System.Net.Security.SslPolicyErrors.RemoteCertificateNameMismatch) != 0)
+                    {
+                        return false;
+                    }
+
                     if (certificate is null)
                     {
                         return false;
@@ -437,6 +533,10 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
                     return customChain.Build(certificateToValidate);
                 };
             }
+            else if (!options.RequireCertificateValidation)
+            {
+                handler.SslOptions.RemoteCertificateValidationCallback = (_, _, _, _) => true;
+            }
         }
 
         return handler;

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

@@ -74,6 +74,23 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
         }
     }
 
+    /// <inheritdoc />
+    public async Task<BrowseChildrenReply> BrowseChildrenAsync(
+        BrowseChildrenRequest request,
+        CallOptions callOptions)
+    {
+        try
+        {
+            return await RawClient.BrowseChildrenAsync(request, callOptions)
+                .ResponseAsync
+                .ConfigureAwait(false);
+        }
+        catch (RpcException exception)
+        {
+            throw MapRpcException(exception, callOptions.CancellationToken);
+        }
+    }
+
     /// <inheritdoc />
     public async IAsyncEnumerable<DeployEvent> WatchDeployEventsAsync(
         WatchDeployEventsRequest request,

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

@@ -175,6 +175,48 @@ internal sealed class GrpcMxGatewayClientTransport(
         return QueryActiveAlarmsAsync(request, callOptions);
     }
 
+    /// <inheritdoc />
+    public async IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
+        StreamAlarmsRequest request,
+        CallOptions callOptions,
+        [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        CancellationToken effectiveCancellationToken = cancellationToken.CanBeCanceled
+            ? cancellationToken
+            : callOptions.CancellationToken;
+
+        using AsyncServerStreamingCall<AlarmFeedMessage> call = RawClient.StreamAlarms(request, callOptions);
+
+        IAsyncStreamReader<AlarmFeedMessage> responseStream = call.ResponseStream;
+        while (true)
+        {
+            AlarmFeedMessage? message;
+            try
+            {
+                if (!await responseStream.MoveNext(effectiveCancellationToken).ConfigureAwait(false))
+                {
+                    break;
+                }
+
+                message = responseStream.Current;
+            }
+            catch (RpcException exception)
+            {
+                throw MapRpcException(exception, effectiveCancellationToken);
+            }
+
+            yield return message;
+        }
+    }
+
+    /// <inheritdoc />
+    IAsyncEnumerable<AlarmFeedMessage> IMxGatewayClientTransport.StreamAlarmsAsync(
+        StreamAlarmsRequest request,
+        CallOptions callOptions)
+    {
+        return StreamAlarmsAsync(request, callOptions);
+    }
+
     private static Exception MapRpcException(
         RpcException exception,
         CancellationToken cancellationToken)

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

@@ -33,6 +33,13 @@ internal interface IGalaxyRepositoryClientTransport
         DiscoverHierarchyRequest request,
         CallOptions callOptions);
 
+    /// <summary>Returns direct children of a parent in the Galaxy hierarchy.</summary>
+    /// <param name="request">The browse children request.</param>
+    /// <param name="callOptions">gRPC call options (timeout, cancellation, etc.).</param>
+    Task<BrowseChildrenReply> BrowseChildrenAsync(
+        BrowseChildrenRequest request,
+        CallOptions callOptions);
+
     /// <summary>Watches for deployment events from the Galaxy Repository server.</summary>
     /// <param name="request">The watch deploy events request.</param>
     /// <param name="callOptions">gRPC call options (timeout, cancellation, etc.).</param>

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

@@ -75,4 +75,15 @@ internal interface IMxGatewayClientTransport
     IAsyncEnumerable<ActiveAlarmSnapshot> QueryActiveAlarmsAsync(
         QueryActiveAlarmsRequest request,
         CallOptions callOptions);
+
+    /// <summary>
+    /// Attaches to the gateway's central alarm feed — the current active-alarm
+    /// snapshot followed by live transitions.
+    /// </summary>
+    /// <param name="request">The stream request, optionally scoped by alarm-reference prefix.</param>
+    /// <param name="callOptions">gRPC call options.</param>
+    /// <returns>An async enumerable of alarm feed messages.</returns>
+    IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
+        StreamAlarmsRequest request,
+        CallOptions callOptions);
 }

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

@@ -0,0 +1,126 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+
+namespace ZB.MOM.WW.MxGateway.Client;
+
+/// <summary>
+///     One node in a lazy-loaded Galaxy browse tree. Holds the underlying
+///     <see cref="GalaxyObject"/> and exposes <see cref="ExpandAsync"/> to fetch
+///     its direct children on demand. Expansion is one-shot: a second call is a
+///     no-op. Pagination of large sibling sets is handled internally.
+/// </summary>
+public sealed class LazyBrowseNode
+{
+    private readonly GalaxyRepositoryClient _client;
+    private readonly BrowseChildrenOptions _options;
+    // Client.Dotnet-027 (Won't Fix): this gate is used only via WaitAsync/Release and
+    // never via AvailableWaitHandle, so SemaphoreSlim allocates no kernel wait handle —
+    // it holds no unmanaged/OS handle to leak. It is pure managed memory whose lifetime
+    // is the node's, so the type is intentionally not IDisposable: making it disposable
+    // would push per-node disposal onto every tree consumer (thousands of nodes) for no
+    // resource benefit.
+    private readonly SemaphoreSlim _expandLock = new(1, 1);
+
+    // 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,
+        GalaxyObject @object,
+        bool hasChildrenHint,
+        BrowseChildrenOptions options)
+    {
+        _client = client;
+        Object = @object;
+        HasChildrenHint = hasChildrenHint;
+        _options = options;
+    }
+
+    /// <summary>The underlying Galaxy object for this node.</summary>
+    public GalaxyObject Object { get; }
+
+    /// <summary>True when the server reports this node has at least one matching descendant.</summary>
+    public bool HasChildrenHint { get; }
+
+    /// <summary>Direct children loaded by <see cref="ExpandAsync"/>; empty until then.</summary>
+    public IReadOnlyList<LazyBrowseNode> Children => Volatile.Read(ref _children);
+
+    /// <summary>True after the first <see cref="ExpandAsync"/> call completes.</summary>
+    public bool IsExpanded => _isExpanded;
+
+    /// <summary>
+    ///     Fetches direct children from the gateway and populates <see cref="Children"/>.
+    ///     Idempotent: subsequent calls are no-ops.
+    /// </summary>
+    /// <remarks>
+    ///     Thread-safe: concurrent callers see exactly one fetch; subsequent callers
+    ///     (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)
+    {
+        if (_isExpanded)
+        {
+            return;
+        }
+
+        await _expandLock.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            if (_isExpanded)
+            {
+                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
+            {
+                BrowseChildrenRequest request = GalaxyRepositoryClient.BuildBrowseChildrenRequest(_options);
+                request.ParentGobjectId = Object.GobjectId;
+                request.PageToken = pageToken;
+
+                BrowseChildrenReply reply = await _client
+                    .BrowseChildrenRawAsync(request, cancellationToken)
+                    .ConfigureAwait(false);
+
+                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));
+                }
+
+                pageToken = reply.NextPageToken;
+                if (!string.IsNullOrWhiteSpace(pageToken) && !seenPageTokens.Add(pageToken))
+                {
+                    throw new MxGatewayException(
+                        $"Galaxy BrowseChildren returned a repeated page token '{pageToken}'.");
+                }
+            }
+            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
+        {
+            _expandLock.Release();
+        }
+    }
+}

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

@@ -224,6 +224,28 @@ public sealed class MxGatewayClient : IAsyncDisposable
         return _transport.QueryActiveAlarmsAsync(request, CreateStreamCallOptions(cancellationToken));
     }
 
+    /// <summary>
+    /// Attaches to the gateway's central alarm feed. The stream opens with one
+    /// <see cref="AlarmFeedMessage"/> per currently-active alarm (the
+    /// ConditionRefresh snapshot), then a single <c>snapshot_complete</c>, then a
+    /// <c>transition</c> for every subsequent raise / acknowledge / clear. Served
+    /// by the gateway's always-on alarm monitor — no worker session is opened, so
+    /// any number of clients may attach. Optionally scoped by alarm-reference
+    /// prefix (<see cref="StreamAlarmsRequest.AlarmFilterPrefix"/>).
+    /// </summary>
+    /// <param name="request">The stream request, optionally scoped by alarm-reference prefix.</param>
+    /// <param name="cancellationToken">Cancellation token for the stream.</param>
+    /// <returns>An async enumerable of alarm feed messages.</returns>
+    public IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
+        StreamAlarmsRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ThrowIfDisposed();
+
+        return _transport.StreamAlarmsAsync(request, CreateStreamCallOptions(cancellationToken));
+    }
+
     /// <summary>
     /// Disposes the client and releases all resources.
     /// </summary>
@@ -293,7 +315,10 @@ public sealed class MxGatewayClient : IAsyncDisposable
             .ConfigureAwait(false);
     }
 
-    private static HttpMessageHandler CreateHttpHandler(MxGatewayClientOptions options)
+    private static HttpMessageHandler CreateHttpHandler(MxGatewayClientOptions options) =>
+        CreateHttpHandlerForTests(options);
+
+    internal static SocketsHttpHandler CreateHttpHandlerForTests(MxGatewayClientOptions options)
     {
         SocketsHttpHandler handler = new()
         {
@@ -313,6 +338,11 @@ public sealed class MxGatewayClient : IAsyncDisposable
                 X509Certificate2 trustedRoot = X509CertificateLoader.LoadCertificateFromFile(options.CaCertificatePath);
                 handler.SslOptions.RemoteCertificateValidationCallback = (_, certificate, chain, errors) =>
                 {
+                    if ((errors & System.Net.Security.SslPolicyErrors.RemoteCertificateNameMismatch) != 0)
+                    {
+                        return false;
+                    }
+
                     if (certificate is null)
                     {
                         return false;
@@ -328,6 +358,10 @@ public sealed class MxGatewayClient : IAsyncDisposable
                     return customChain.Build(certificateToValidate);
                 };
             }
+            else if (!options.RequireCertificateValidation)
+            {
+                handler.SslOptions.RemoteCertificateValidationCallback = (_, _, _, _) => true;
+            }
         }
 
         return handler;

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

@@ -7,9 +7,11 @@ namespace ZB.MOM.WW.MxGateway.Client;
 /// </summary>
 public static class MxGatewayClientContractInfo
 {
+    /// <inheritdoc cref="GatewayContractInfo.GatewayProtocolVersion"/>
     public const uint GatewayProtocolVersion =
         GatewayContractInfo.GatewayProtocolVersion;
 
+    /// <inheritdoc cref="GatewayContractInfo.WorkerProtocolVersion"/>
     public const uint WorkerProtocolVersion =
         GatewayContractInfo.WorkerProtocolVersion;
 }

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

@@ -27,6 +27,14 @@ public sealed class MxGatewayClientOptions
     /// </summary>
     public string? CaCertificatePath { get; init; }
 
+    /// <summary>
+    /// When true, TLS connections without a pinned <see cref="CaCertificatePath"/>
+    /// use the OS trust store. When false (default), the gateway certificate is
+    /// accepted without verification — appropriate for this internal tool's
+    /// auto-generated self-signed certificate. Pinning a CA always verifies.
+    /// </summary>
+    public bool RequireCertificateValidation { get; init; }
+
     /// <summary>
     /// Gets the server name override for SNI during TLS handshake.
     /// </summary>
@@ -47,6 +55,9 @@ public sealed class MxGatewayClientOptions
     /// </summary>
     public TimeSpan? StreamTimeout { get; init; }
 
+    /// <summary>
+    /// Gets the maximum size in bytes for gRPC messages.
+    /// </summary>
     public int MaxGrpcMessageBytes { get; init; } = 16 * 1024 * 1024;
 
     /// <summary>

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

@@ -502,6 +502,171 @@ public sealed class MxGatewaySession : IAsyncDisposable
         return reply.UnsubscribeBulk?.Results.ToArray() ?? [];
     }
 
+    /// <summary>
+    /// Bulk Write — sequential MXAccess Write per entry on the worker's STA.
+    /// Per-item failures appear as <see cref="BulkWriteResult"/> entries with
+    /// <c>WasSuccessful = false</c>; the call never throws on per-item errors.
+    /// Protocol-level failures still throw via EnsureProtocolSuccess.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="entries">Per-item write entries; each carries the item handle, value, and user id.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>One <see cref="BulkWriteResult"/> per requested entry, in request order.</returns>
+    public async Task<IReadOnlyList<BulkWriteResult>> WriteBulkAsync(
+        int serverHandle,
+        IReadOnlyList<WriteBulkEntry> entries,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(entries);
+
+        WriteBulkCommand command = new() { ServerHandle = serverHandle };
+        command.Entries.Add(entries);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.WriteBulk,
+                    WriteBulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.WriteBulk?.Results.ToArray() ?? [];
+    }
+
+    /// <summary>
+    /// Bulk Write2 — sequential MXAccess Write2 (timestamped) per entry.
+    /// Per-item failures appear as <see cref="BulkWriteResult"/> entries with
+    /// <c>WasSuccessful = false</c>; the call never throws on per-item errors.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="entries">Per-item write entries; each carries the item handle, value, timestamp, and user id.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>One <see cref="BulkWriteResult"/> per requested entry, in request order.</returns>
+    public async Task<IReadOnlyList<BulkWriteResult>> Write2BulkAsync(
+        int serverHandle,
+        IReadOnlyList<Write2BulkEntry> entries,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(entries);
+
+        Write2BulkCommand command = new() { ServerHandle = serverHandle };
+        command.Entries.Add(entries);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.Write2Bulk,
+                    Write2Bulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.Write2Bulk?.Results.ToArray() ?? [];
+    }
+
+    /// <summary>
+    /// Bulk WriteSecured — sequential MXAccess WriteSecured per entry.
+    /// Credential-sensitive values must never reach logs; the client mirrors
+    /// the single-item WriteSecured redaction contract.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="entries">Per-item write entries; each carries the item handle, value, current user id, and verifier user id.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>One <see cref="BulkWriteResult"/> per requested entry, in request order.</returns>
+    public async Task<IReadOnlyList<BulkWriteResult>> WriteSecuredBulkAsync(
+        int serverHandle,
+        IReadOnlyList<WriteSecuredBulkEntry> entries,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(entries);
+
+        WriteSecuredBulkCommand command = new() { ServerHandle = serverHandle };
+        command.Entries.Add(entries);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.WriteSecuredBulk,
+                    WriteSecuredBulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.WriteSecuredBulk?.Results.ToArray() ?? [];
+    }
+
+    /// <summary>
+    /// Bulk WriteSecured2 — sequential MXAccess WriteSecured2 (timestamped) per entry.
+    /// Same redaction rules as <see cref="WriteSecuredBulkAsync"/>.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="entries">Per-item write entries; each carries the item handle, value, timestamp, current user id, and verifier user id.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>One <see cref="BulkWriteResult"/> per requested entry, in request order.</returns>
+    public async Task<IReadOnlyList<BulkWriteResult>> WriteSecured2BulkAsync(
+        int serverHandle,
+        IReadOnlyList<WriteSecured2BulkEntry> entries,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(entries);
+
+        WriteSecured2BulkCommand command = new() { ServerHandle = serverHandle };
+        command.Entries.Add(entries);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.WriteSecured2Bulk,
+                    WriteSecured2Bulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.WriteSecured2Bulk?.Results.ToArray() ?? [];
+    }
+
+    /// <summary>
+    /// Bulk Read — snapshot the current value for each requested tag.
+    /// Returns the cached OnDataChange value when the tag is already advised
+    /// (<c>WasCached = true</c>), otherwise the worker takes the full AddItem +
+    /// Advise + wait + UnAdvise + RemoveItem snapshot lifecycle. Per-tag
+    /// failures (timeout, invalid tag) appear as <see cref="BulkReadResult"/>
+    /// entries with <c>WasSuccessful = false</c>; the call never throws on
+    /// per-tag errors.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="tagAddresses">Tag addresses to read (one per result).</param>
+    /// <param name="timeout">Per-call timeout for the snapshot lifecycle path; <see cref="TimeSpan.Zero"/> uses the gateway default.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>One <see cref="BulkReadResult"/> per requested tag, in request order.</returns>
+    public async Task<IReadOnlyList<BulkReadResult>> ReadBulkAsync(
+        int serverHandle,
+        IReadOnlyList<string> tagAddresses,
+        TimeSpan timeout,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(tagAddresses);
+
+        ReadBulkCommand command = new()
+        {
+            ServerHandle = serverHandle,
+            TimeoutMs = timeout <= TimeSpan.Zero ? 0u : (uint)Math.Min(timeout.TotalMilliseconds, uint.MaxValue),
+        };
+        command.TagAddresses.Add(tagAddresses);
+
+        MxCommandReply reply = await InvokeCommandAsync(
+                new MxCommand
+                {
+                    Kind = MxCommandKind.ReadBulk,
+                    ReadBulk = command,
+                },
+                cancellationToken)
+            .ConfigureAwait(false);
+        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        return reply.ReadBulk?.Results.ToArray() ?? [];
+    }
+
     /// <summary>
     /// Writes a value to an item on the MXAccess server.
     /// </summary>
@@ -522,6 +687,63 @@ public sealed class MxGatewaySession : IAsyncDisposable
         reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
     }
 
+    /// <summary>
+    /// Writes specific array indices to an item using default-fill semantics.
+    /// </summary>
+    /// <remarks>
+    /// The gateway expands the sparse descriptor into a full <c>totalLength</c>-element array
+    /// before forwarding to the worker. Indices not listed in <paramref name="elements"/> are
+    /// written as the element type's default value — this is a RESET, not a preserve. The
+    /// current values at those positions are discarded. <paramref name="totalLength"/> is
+    /// required and must match the declared length of the array attribute.
+    /// </remarks>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandle">The ItemHandle from add-item.</param>
+    /// <param name="elementDataType">The MXAccess data type of each element.</param>
+    /// <param name="totalLength">The total declared length of the target array attribute.</param>
+    /// <param name="elements">Map of zero-based array index to scalar <see cref="MxValue"/>.</param>
+    /// <param name="userId">User ID context for the write.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    public Task WriteArrayElementsAsync(
+        int serverHandle,
+        int itemHandle,
+        MxDataType elementDataType,
+        uint totalLength,
+        IReadOnlyDictionary<uint, MxValue> elements,
+        int userId = 0,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(elements);
+        MxValue value = BuildSparseArray(elementDataType, totalLength, elements);
+        return WriteAsync(serverHandle, itemHandle, value, userId, cancellationToken);
+    }
+
+    /// <summary>
+    /// Builds an <see cref="MxValue"/> whose <see cref="MxValue.SparseArrayValue"/> describes a
+    /// default-fill partial array write.
+    /// </summary>
+    /// <param name="elementDataType">The MXAccess data type of each element.</param>
+    /// <param name="totalLength">The total declared length of the target array attribute.</param>
+    /// <param name="elements">Map of zero-based array index to scalar <see cref="MxValue"/>.</param>
+    /// <returns>An <see cref="MxValue"/> with <see cref="MxValue.KindOneofCase.SparseArrayValue"/> set.</returns>
+    internal static MxValue BuildSparseArray(
+        MxDataType elementDataType,
+        uint totalLength,
+        IReadOnlyDictionary<uint, MxValue> elements)
+    {
+        MxSparseArray sparse = new()
+        {
+            ElementDataType = elementDataType,
+            TotalLength = totalLength,
+        };
+        foreach (KeyValuePair<uint, MxValue> kv in elements)
+        {
+            sparse.Elements.Add(new MxSparseElement { Index = kv.Key, Value = kv.Value });
+        }
+
+        return new MxValue { SparseArrayValue = sparse };
+    }
+
     /// <summary>
     /// Writes a value to an item on the MXAccess server without error checking.
     /// </summary>

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

@@ -16,4 +16,26 @@
     <Nullable>enable</Nullable>
   </PropertyGroup>
 
+  <PropertyGroup>
+    <IsPackable>true</IsPackable>
+    <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>
+    <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
+      <_Parameter1>ZB.MOM.WW.MxGateway.Client.Tests</_Parameter1>
+    </AssemblyAttribute>
+  </ItemGroup>
+
 </Project>

clients/go/GoClientDesign.md

@@ -104,6 +104,23 @@ Support:
 - `credentials.NewClientTLSFromFile`,
 - custom `tls.Config` for advanced callers.
 
+### Trust posture
+
+The gateway can serve a self-signed certificate it generates itself (it has no
+PKI). To make that usable, TLS is **lenient by default**: when `Plaintext` is
+`false` and no `CACertFile`/`TLSConfig`/`TransportCredentials` is supplied,
+`buildCredentials` dials with `tls.Config{InsecureSkipVerify: true}` (carrying
+`ServerNameOverride` as the SNI when set), so the gateway's self-signed
+certificate is accepted without verification.
+
+To verify the gateway instead:
+
+- set `CACertFile` to pin a CA (full verification against that root), or
+- set `RequireCertificateValidation: true` to verify against the OS/system trust
+  roots without pinning.
+
+Pinning a CA always wins over the lenient default.
+
 ## Streaming
 
 `Events(ctx)` should return a receive channel of:

clients/go/README.md

@@ -75,6 +75,14 @@ client, err := mxgateway.Dial(ctx, mxgateway.Options{
 })
 ```
 
+The gateway can auto-generate its own self-signed certificate (it has no PKI), so
+the client is **lenient by default**: a TLS connection (`Plaintext: false`) with
+no `CACertFile`/`TLSConfig` accepts whatever certificate the gateway presents
+(`InsecureSkipVerify`, with `ServerNameOverride` as the SNI when set). To verify
+instead, set `CACertFile` to pin a CA, or set `RequireCertificateValidation:
+true` to verify against the OS/system trust roots without pinning. See
+[Gateway Configuration](../../docs/GatewayConfiguration.md#automatic-self-signed-certificate).
+
 `Client.OpenSession` returns a `Session` with helpers for `Register`,
 `AddItem`, `AddItem2`, `Advise`, `Write`, `Events`, and `Close`. Prefer
 `SubscribeEvents` or `SubscribeEventsAfter` for long-running streams because the
@@ -84,6 +92,86 @@ goroutine cleanup. Raw protobuf messages remain available through the
 `errors.As` for `GatewayError`, `CommandError`, and `MxAccessError`; command
 errors preserve the raw reply.
 
+For alarms, the package exposes `Client.QueryActiveAlarms` for one-shot
+snapshots, `Client.StreamAlarms` for the server-streaming feed, and
+`Client.AcknowledgeAlarm` to ack an alarm by full reference. The streaming
+call returns a `StreamAlarmsClient`; cancel its context to terminate the
+stream. All three pass straight through to the gateway's central alarm
+monitor.
+
+## Write Semantics And Common Pitfalls
+
+These are MXAccess parity behaviors that surprise new callers. The gateway
+forwards them unchanged — it does not paper over them.
+
+### Attributing a write to a user without `AuthenticateUser`
+
+MXAccess only stamps a plain `Write`/`Write2` with a Galaxy user id when the
+item carries an active *supervisory* advise. If you are **not** using the
+verified/secured path (`AuthenticateUser` → `WriteSecured`/`WriteSecured2`) but
+still need the write attributed to a user id, you must first advise the item
+supervisory and then pass that user id on the write. Without the supervisory
+advise the `userID` on a plain write is ignored.
+
+The session exposes `Advise`/`UnAdvise` but not supervisory advise, so send it
+through the generic command channel:
+
+```go
+_, err := client.Invoke(ctx, &pb.MxCommandRequest{
+    SessionId: session.ID(),
+    Command: &pb.MxCommand{
+        Kind: pb.MxCommandKind_MX_COMMAND_KIND_ADVISE_SUPERVISORY,
+        Payload: &pb.MxCommand_AdviseSupervisory{
+            AdviseSupervisory: &pb.AdviseSupervisoryCommand{
+                ServerHandle: serverHandle,
+                ItemHandle:   itemHandle,
+            },
+        },
+    },
+})
+
+err = session.Write(ctx, serverHandle, itemHandle, value, userID)
+```
+
+The CLI exposes the same command as `advise-supervisory`, and `write`
+takes `-user-id`.
+
+### Array writes replace the whole array
+
+A write to an array attribute **replaces the entire array**; it is not an
+element-wise patch. To change a subset of elements, send the full array with
+the unchanged elements included. For example, to change 2 elements of a
+20-element array, build the `MxValue` from all 20 values (the 18 unchanged plus
+the 2 new ones). Sending only the 2 changed values overwrites the attribute
+with a 2-element array.
+
+`Session.WriteArrayElements` offers a default-fill shorthand: pass only the
+indices you want to set along with a `totalLength`. The gateway expands the
+sparse representation into a full array before forwarding to MXAccess — every
+unmentioned index receives the element type's zero value (boolean `false`,
+integer `0`, float `0.0`, string `""`, time = Unix epoch). This is a **RESET**
+of unmentioned indices, not a preserve of existing values. Use the full-array
+form (read-modify-write) when existing element values must be preserved.
+
+```go
+// Set element [3] of a 10-element float array; all other indices reset to 0.0.
+err = session.WriteArrayElements(
+    ctx,
+    serverHandle, itemHandle,
+    mxgateway.DataTypeFloat,
+    10, // totalLength
+    map[uint32]*mxgateway.MxValue{
+        3: mxgateway.FloatValue(1.5),
+    },
+    userID,
+)
+```
+
+`AddItem`, `AddItem2`, `AddItemBulk`, and `AddBufferedItem` auto-normalize a
+bare array attribute name to the `[]` array address form expected by MXAccess,
+so callers do not need to append `[]` themselves. Both forms are accepted;
+duplicates are deduplicated by the gateway.
+
 ## Galaxy Repository browse
 
 The `GalaxyRepository` service (proto package `galaxy_repository.v1`) is a
@@ -114,6 +202,68 @@ reports `present=false` (no deploy recorded). `DiscoverHierarchy` returns
 the generated `*GalaxyObject` slice with each object's dynamic attributes
 populated for direct contract access.
 
+### Browsing lazily
+
+For UI trees or OPC UA bridges, use `BrowseChildren` to walk one level at a
+time instead of loading the full hierarchy. Pass an empty request for root
+objects; subsequent calls set `ParentGobjectId`, `ParentTagName`, or
+`ParentContainedPath`. Filter fields match `DiscoverHierarchy`. Each response
+pairs `Children` with `ChildHasChildren` so you know which nodes to expand. See
+[Galaxy Repository](../../docs/GalaxyRepository.md#browsechildren) for full
+request and filter semantics.
+
+```go
+import pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated/galaxy_repository/v1"
+
+reply, err := galaxy.BrowseChildren(ctx, &pb.BrowseChildrenRequest{})
+if err != nil {
+    return err
+}
+for i, child := range reply.GetChildren() {
+    fmt.Printf("%s expand=%v\n", child.GetTagName(), reply.GetChildHasChildren()[i])
+}
+```
+
+#### High-level walker
+
+For UI trees, the client provides a `LazyBrowseNode` walker that handles
+sibling pagination and the `child_has_children` hint for you:
+
+```go
+galaxy, err := mxgateway.DialGalaxy(ctx, mxgateway.Options{
+    Endpoint:  "localhost:5000",
+    APIKey:    os.Getenv("MXGATEWAY_API_KEY"),
+    Plaintext: true,
+})
+if err != nil {
+    log.Fatal(err)
+}
+defer galaxy.Close()
+
+roots, err := galaxy.Browse(ctx, nil)
+if err != nil {
+    log.Fatal(err)
+}
+for _, root := range roots {
+    if root.HasChildrenHint() {
+        if err := root.Expand(ctx); err != nil {
+            log.Fatal(err)
+        }
+    }
+    for _, child := range root.Children() {
+        kind := "leaf"
+        if child.HasChildrenHint() {
+            kind = "has children"
+        }
+        fmt.Printf("%s (%s)\n", child.Object().GetTagName(), kind)
+    }
+}
+```
+
+`Expand` is idempotent — calling it twice fires only one RPC,
+and is safe under concurrent callers. To refresh after a Galaxy redeploy, call
+`Browse` again from the root.
+
 ### Watching deploy events
 
 `WatchDeployEvents` opens a server-streaming subscription. The server emits a
@@ -170,24 +320,79 @@ one line per event in text mode or one JSON object per event with `-json`.
 The `mxgw-go` CLI emits JSON with redacted API keys for commands that connect to
 the gateway:
 
+### Subcommand reference
+
+Every subcommand wired into the CLI. All accept the common flags
+(`-endpoint`, `-plaintext`, `-api-key` / `-api-key-env`, `-ca-cert`,
+`-server-name-override`, `-call-timeout`) and most accept `-json`.
+
+| Command | Purpose |
+|---|---|
+| `version` | Print client/contract versions. |
+| `open-session` | Open a gateway session and print its id. |
+| `close-session` | Close a session by id. |
+| `ping` | Round-trip a `PING` command (`-session-id`, `-message`). |
+| `register` | Register a client name on a session (`-session-id`, `-client-name`). |
+| `add-item` | Add an item handle (`-session-id`, `-server-handle`, `-item`). |
+| `advise` | Advise (subscribe) one item (`-session-id`, `-server-handle`, `-item-handle`). |
+| `advise-supervisory` | Advise one item supervisory — required before a user-id-attributed plain `write`. |
+| `subscribe-bulk` | Advise many items in one call. |
+| `unsubscribe-bulk` | Unadvise many item handles in one call. |
+| `read-bulk` | Read snapshots for many item handles in one call. |
+| `write` | Write one value (`-type`, `-value`). |
+| `write-bulk` | Write many values (`-item-handles`, `-values`, counts must match). |
+| `write2-bulk` | `write-bulk` with a shared `-timestamp-value` (RFC 3339). |
+| `write-secured-bulk` | Secured bulk write (`-current-user-id`, `-verifier-user-id`). |
+| `write-secured2-bulk` | Secured bulk write with a shared timestamp. |
+| `bench-read-bulk` | Throughput benchmark (`-duration-seconds`, `-warmup-seconds`, `-bulk-size`). |
+| `stream-events` | Stream item-value events for a session (`-session-id`, `-limit`). |
+| `stream-alarms` | Stream the alarm feed (`-filter-prefix`, `-limit`). |
+| `acknowledge-alarm` | Acknowledge an alarm reference. |
+| `smoke` | End-to-end smoke workflow against one item. |
+| `galaxy-test-connection` | Probe the Galaxy Repository RPC connection. |
+| `galaxy-last-deploy` | Print the most recent deploy event. |
+| `galaxy-discover` | Discover deployed objects. |
+| `galaxy-watch` | Stream deploy events until Ctrl+C or `-limit`. |
+| `galaxy-browse` | Lazy/eager browse of the Galaxy object tree. |
+| `batch` | Read commands from stdin (see below). |
+
 ```powershell
 go run ./cmd/mxgw-go version -json
 go run ./cmd/mxgw-go open-session -endpoint localhost:5000 -plaintext -json
+go run ./cmd/mxgw-go ping -session-id <id> -plaintext -json
 go run ./cmd/mxgw-go register -session-id <id> -client-name mxgw-go -plaintext -json
 go run ./cmd/mxgw-go add-item -session-id <id> -server-handle 1 -item Area001.Tag.Value -plaintext -json
 go run ./cmd/mxgw-go advise -session-id <id> -server-handle 1 -item-handle 1 -plaintext -json
 go run ./cmd/mxgw-go write -session-id <id> -server-handle 1 -item-handle 1 -type int32 -value 123 -plaintext -json
+go run ./cmd/mxgw-go write-bulk -session-id <id> -server-handle 1 -item-handles 1,2 -values 10,20 -type int32 -plaintext -json
+go run ./cmd/mxgw-go read-bulk -session-id <id> -item-handles 1,2 -plaintext -json
 go run ./cmd/mxgw-go stream-events -session-id <id> -plaintext -json
+go run ./cmd/mxgw-go stream-alarms -plaintext -json
 go run ./cmd/mxgw-go smoke -item Area001.Tag.Value -plaintext -json
 go run ./cmd/mxgw-go galaxy-test-connection -plaintext -json
 go run ./cmd/mxgw-go galaxy-last-deploy -plaintext -json
 go run ./cmd/mxgw-go galaxy-discover -plaintext -json
 go run ./cmd/mxgw-go galaxy-watch -plaintext -json
+go run ./cmd/mxgw-go galaxy-browse -plaintext -json
 ```
 
 Use `-api-key-env MXGATEWAY_API_KEY` or `-api-key <key>` when authentication is
 enabled. CLI output redacts the key value and never writes the raw secret.
 
+### `batch` mode
+
+`batch` reads one command line at a time from stdin and dispatches each through
+the same routing as the standalone subcommands; it is the interface the
+cross-language E2E harness drives. After every command's output it writes the
+end-of-result sentinel line `__MXGW_BATCH_EOR__` to stdout and flushes, so the
+harness can frame each result. Blank/whitespace-only lines are skipped; only
+stdin EOF ends the session. Command errors are serialised as a JSON object
+(`{"error":...,"type":"error"}`) to stdout (not stderr) and still followed by the
+sentinel, so a failing command does not abort the batch. The input scanner
+buffer is widened to 16 MiB so a single long command line (e.g. a bulk write with
+thousands of handles) does not trip bufio's default 64 KiB token-too-long limit;
+a line that still exceeds 16 MiB surfaces as a framed error and ends the session.
+
 Use TLS options for a secured gateway:
 
 ```powershell
@@ -206,6 +411,41 @@ $env:MXGATEWAY_TEST_ITEM = 'Area001.Tag.Value'
 go run ./cmd/mxgw-go smoke -endpoint $env:MXGATEWAY_ENDPOINT -plaintext -api-key-env MXGATEWAY_API_KEY -item $env:MXGATEWAY_TEST_ITEM -json
 ```
 
+## Installing the Go client
+
+The module is resolved directly from the git repo — no package registry:
+
+````bash
+go get gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go@v0.1.1
+````
+
+Then import:
+
+````go
+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 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
+
+Go modules in monorepo subdirectories use prefixed tags. To tag a release
+from this repo:
+
+````bash
+pwsh scripts/tag-go-module.ps1 -Version v0.1.1 -Push
+````
+
+The script validates semver, refuses to tag with uncommitted tracked
+changes, creates an annotated tag `clients/go/v0.1.1`, and (with `-Push`)
+pushes it to origin.
+
 ## Related Documentation
 
 - [Client Packaging](../../docs/ClientPackaging.md)

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

@@ -2,9 +2,15 @@ package main
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
+	"net"
 	"strings"
 	"testing"
+	"time"
+
+	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
+	"google.golang.org/grpc"
 )
 
 func TestRunVersionJSON(t *testing.T) {
@@ -84,3 +90,500 @@ func TestParseValueBuildsTypedValue(t *testing.T) {
 		t.Fatalf("int32 value = %d, want 123", got)
 	}
 }
+
+// TestRunWriteBulkVariantGatesSecuredFlags pins the Client.Go-022 fix:
+// secured-only flags must be unavailable on non-secured variants, and
+// vice-versa, so a wrong-variant flag fails with a clean "flag provided
+// but not defined" error instead of silently no-op'ing.
+func TestRunWriteBulkVariantGatesSecuredFlags(t *testing.T) {
+	cases := []struct {
+		name string
+		args []string
+	}{
+		{
+			name: "write-bulk-rejects-current-user-id",
+			args: []string{"write-bulk", "-current-user-id", "5", "-item-handles", "1", "-values", "1"},
+		},
+		{
+			name: "write-bulk-rejects-verifier-user-id",
+			args: []string{"write-bulk", "-verifier-user-id", "5", "-item-handles", "1", "-values", "1"},
+		},
+		{
+			name: "write2-bulk-rejects-current-user-id",
+			args: []string{"write2-bulk", "-current-user-id", "5", "-item-handles", "1", "-values", "1"},
+		},
+		{
+			name: "write-secured-bulk-rejects-user-id",
+			args: []string{"write-secured-bulk", "-user-id", "5", "-item-handles", "1", "-values", "1"},
+		},
+		{
+			name: "write-secured2-bulk-rejects-user-id",
+			args: []string{"write-secured2-bulk", "-user-id", "5", "-item-handles", "1", "-values", "1"},
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			err := runWithIO(t.Context(), tc.args, &stdout, &stderr)
+			if err == nil {
+				t.Fatalf("runWithIO(%v) returned no error", tc.args)
+			}
+			if !strings.Contains(err.Error(), "flag provided but not defined") {
+				t.Fatalf("runWithIO(%v) error = %v; want 'flag provided but not defined'", tc.args, err)
+			}
+		})
+	}
+}
+
+// TestRunBenchReadBulkRespectsContextCancellation pins the Client.Go-023
+// fix: the warm-up and steady-state wall-clock loops must honour ctx.Err()
+// so an external cancel (Ctrl+C, parent-cancel from a cross-language bench
+// driver) short-circuits the bench instead of spinning failing ReadBulk
+// calls until the wall-clock deadline elapses.
+func TestRunBenchReadBulkRespectsContextCancellation(t *testing.T) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	server := grpc.NewServer()
+	fake := &benchFakeGateway{}
+	pb.RegisterMxAccessGatewayServer(server, fake)
+	go func() {
+		_ = server.Serve(listener)
+	}()
+	defer server.Stop()
+	defer listener.Close()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	// Long warm-up + duration, so if the ctx.Err() guard were missing the
+	// loops would run for ~10s. With the guard, the cancel below short-
+	// circuits both loops within ~one ReadBulk iteration.
+	args := []string{
+		"bench-read-bulk",
+		"-endpoint", listener.Addr().String(),
+		"-plaintext",
+		"-api-key", "test",
+		"-warmup-seconds", "5",
+		"-duration-seconds", "5",
+		"-bulk-size", "1",
+		"-timeout-ms", "100",
+	}
+
+	// Cancel after a brief delay — far less than warmup+duration (10s).
+	go func() {
+		time.Sleep(150 * time.Millisecond)
+		cancel()
+	}()
+
+	var stdout, stderr bytes.Buffer
+	start := time.Now()
+	err = runWithIO(ctx, args, &stdout, &stderr)
+	elapsed := time.Since(start)
+
+	// With the ctx.Err() guard, the loops exit well before the wall-clock
+	// deadlines (warmup=5s + duration=5s = 10s). Allow generous slack for
+	// CI noise but assert clearly less than the un-guarded worst case.
+	if elapsed > 4*time.Second {
+		t.Fatalf("bench-read-bulk took %s after ctx cancel; want <4s (ctx.Err() guard missing?). err=%v stderr=%s", elapsed, err, stderr.String())
+	}
+}
+
+// TestRunPingPlainText verifies the ping subcommand round-trips through the
+// fake gateway and prints the echo (diagnostic_message) in plain-text mode.
+func TestRunPingPlainText(t *testing.T) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	server := grpc.NewServer()
+	fake := &pingFakeGateway{}
+	pb.RegisterMxAccessGatewayServer(server, fake)
+	go func() { _ = server.Serve(listener) }()
+	defer server.Stop()
+	defer listener.Close()
+
+	var stdout, stderr bytes.Buffer
+	args := []string{
+		"ping",
+		"-endpoint", listener.Addr().String(),
+		"-plaintext",
+		"-api-key", "test",
+		"-session-id", "test-session",
+		"-message", "hello",
+	}
+	if err := runWithIO(t.Context(), args, &stdout, &stderr); err != nil {
+		t.Fatalf("runWithIO() error = %v; stderr = %s", err, stderr.String())
+	}
+	got := strings.TrimSpace(stdout.String())
+	if got != "pong:hello" {
+		t.Fatalf("ping plain-text output = %q, want %q", got, "pong:hello")
+	}
+}
+
+// TestRunPingJSON verifies the ping subcommand emits valid JSON in --json mode.
+func TestRunPingJSON(t *testing.T) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	server := grpc.NewServer()
+	fake := &pingFakeGateway{}
+	pb.RegisterMxAccessGatewayServer(server, fake)
+	go func() { _ = server.Serve(listener) }()
+	defer server.Stop()
+	defer listener.Close()
+
+	var stdout, stderr bytes.Buffer
+	args := []string{
+		"ping",
+		"-endpoint", listener.Addr().String(),
+		"-plaintext",
+		"-api-key", "test",
+		"-session-id", "test-session",
+		"-message", "hello",
+		"-json",
+	}
+	if err := runWithIO(t.Context(), args, &stdout, &stderr); err != nil {
+		t.Fatalf("runWithIO() error = %v; stderr = %s", err, stderr.String())
+	}
+	var out commandReplyOutput
+	if err := json.Unmarshal(stdout.Bytes(), &out); err != nil {
+		t.Fatalf("parse JSON: %v\noutput: %s", err, stdout.String())
+	}
+	if out.Command != "ping" {
+		t.Fatalf("command = %q, want %q", out.Command, "ping")
+	}
+	// The fake gateway echoes "pong:<message>" in diagnostic_message; verify the
+	// echo appears in the serialised reply so a future regression that wired
+	// PingRaw to the wrong proto field would be caught here.
+	replyStr := string(out.Reply)
+	if !strings.Contains(replyStr, "pong:hello") {
+		t.Fatalf("ping JSON reply missing echoed message %q; reply = %s", "pong:hello", replyStr)
+	}
+}
+
+// TestRunPingRequiresSessionID verifies the ping subcommand rejects missing session-id.
+func TestRunPingRequiresSessionID(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	err := runWithIO(t.Context(), []string{"ping", "-plaintext", "-api-key", "test"}, &stdout, &stderr)
+	if err == nil {
+		t.Fatalf("runWithIO(ping without --session-id) returned no error")
+	}
+	if !strings.Contains(err.Error(), "session-id is required") {
+		t.Fatalf("error = %v; want 'session-id is required'", err)
+	}
+}
+
+// pingFakeGateway handles Invoke for MX_COMMAND_KIND_PING by echoing the
+// message back in the diagnostic_message field so the CLI plain-text path
+// has a deterministic, non-empty string to assert on.
+type pingFakeGateway struct {
+	pb.UnimplementedMxAccessGatewayServer
+}
+
+func (g *pingFakeGateway) Invoke(_ context.Context, req *pb.MxCommandRequest) (*pb.MxCommandReply, error) {
+	echo := "pong:" + req.GetCommand().GetPing().GetMessage()
+	return &pb.MxCommandReply{
+		SessionId:         req.GetSessionId(),
+		Kind:              pb.MxCommandKind_MX_COMMAND_KIND_PING,
+		DiagnosticMessage: echo,
+		ProtocolStatus:    &pb.ProtocolStatus{Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK},
+	}, nil
+}
+
+// benchFakeGateway is a minimal MxAccessGatewayServer that satisfies the
+// bench-read-bulk session-setup sequence (OpenSession + Invoke for Register
+// / SubscribeBulk / ReadBulk / UnsubscribeBulk / CloseSession).
+type benchFakeGateway struct {
+	pb.UnimplementedMxAccessGatewayServer
+}
+
+func (g *benchFakeGateway) OpenSession(_ context.Context, _ *pb.OpenSessionRequest) (*pb.OpenSessionReply, error) {
+	return &pb.OpenSessionReply{
+		SessionId:      "bench-session",
+		ProtocolStatus: &pb.ProtocolStatus{Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK},
+	}, nil
+}
+
+func (g *benchFakeGateway) CloseSession(_ context.Context, req *pb.CloseSessionRequest) (*pb.CloseSessionReply, error) {
+	return &pb.CloseSessionReply{
+		SessionId:      req.GetSessionId(),
+		ProtocolStatus: &pb.ProtocolStatus{Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK},
+	}, nil
+}
+
+func (g *benchFakeGateway) Invoke(_ context.Context, req *pb.MxCommandRequest) (*pb.MxCommandReply, error) {
+	kind := req.GetCommand().GetKind()
+	reply := &pb.MxCommandReply{
+		SessionId:      req.GetSessionId(),
+		Kind:           kind,
+		ProtocolStatus: &pb.ProtocolStatus{Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK},
+	}
+	switch kind {
+	case pb.MxCommandKind_MX_COMMAND_KIND_REGISTER:
+		reply.Payload = &pb.MxCommandReply_Register{Register: &pb.RegisterReply{ServerHandle: 1}}
+	case pb.MxCommandKind_MX_COMMAND_KIND_SUBSCRIBE_BULK:
+		reply.Payload = &pb.MxCommandReply_SubscribeBulk{SubscribeBulk: &pb.BulkSubscribeReply{
+			Results: []*pb.SubscribeResult{{ServerHandle: 1, ItemHandle: 1, WasSuccessful: true}},
+		}}
+	case pb.MxCommandKind_MX_COMMAND_KIND_READ_BULK:
+		reply.Payload = &pb.MxCommandReply_ReadBulk{ReadBulk: &pb.BulkReadReply{
+			Results: []*pb.BulkReadResult{{ItemHandle: 1, WasSuccessful: true, WasCached: true}},
+		}}
+	case pb.MxCommandKind_MX_COMMAND_KIND_UNSUBSCRIBE_BULK:
+		reply.Payload = &pb.MxCommandReply_UnsubscribeBulk{UnsubscribeBulk: &pb.BulkSubscribeReply{}}
+	}
+	return reply, nil
+}
+
+// TestRunBenchReadBulkRejectsNonPositiveBulkSize pins the Client.Go-023-adjacent
+// positivity checks so they cannot drift while resolving the cancellation finding.
+func TestRunBenchReadBulkRejectsNonPositiveBulkSize(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	err := runWithIO(t.Context(), []string{"bench-read-bulk", "-bulk-size", "0"}, &stdout, &stderr)
+	if err == nil || !strings.Contains(err.Error(), "bulk-size must be positive") {
+		t.Fatalf("bench-read-bulk -bulk-size 0 error = %v", err)
+	}
+}
+
+// browseFakeGalaxy implements BrowseChildren for the galaxy-browse subcommand
+// tests. It returns two root objects when no parent is supplied (the first
+// flagged as having children), and one child when the first root's gobject id
+// is supplied as the parent. The recorded last request lets a test assert the
+// CLI forwarded the parent and filter fields onto the wire.
+type browseFakeGalaxy struct {
+	pb.UnimplementedGalaxyRepositoryServer
+	lastRequest *pb.BrowseChildrenRequest
+}
+
+func (g *browseFakeGalaxy) BrowseChildren(_ context.Context, req *pb.BrowseChildrenRequest) (*pb.BrowseChildrenReply, error) {
+	g.lastRequest = req
+	if req.GetParentGobjectId() == 10 {
+		return &pb.BrowseChildrenReply{
+			Children: []*pb.GalaxyObject{
+				{GobjectId: 11, TagName: "Area1.Tank", BrowseName: "Tank"},
+			},
+			ChildHasChildren: []bool{false},
+		}, nil
+	}
+	return &pb.BrowseChildrenReply{
+		Children: []*pb.GalaxyObject{
+			{GobjectId: 10, TagName: "Area1", BrowseName: "Area1"},
+			{GobjectId: 20, TagName: "Area2", BrowseName: "Area2"},
+		},
+		ChildHasChildren: []bool{true, false},
+	}, nil
+}
+
+func startBrowseFakeGalaxy(t *testing.T) (addr string, fake *browseFakeGalaxy) {
+	t.Helper()
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	server := grpc.NewServer()
+	fake = &browseFakeGalaxy{}
+	pb.RegisterGalaxyRepositoryServer(server, fake)
+	go func() { _ = server.Serve(listener) }()
+	t.Cleanup(func() {
+		server.Stop()
+		_ = listener.Close()
+	})
+	return listener.Addr().String(), fake
+}
+
+// TestRunGalaxyBrowseTextTree verifies the galaxy-browse subcommand issues
+// BrowseChildren for the root walk, eagerly expands one level when --depth is
+// set, and renders an indented tree.
+func TestRunGalaxyBrowseTextTree(t *testing.T) {
+	addr, _ := startBrowseFakeGalaxy(t)
+
+	var stdout, stderr bytes.Buffer
+	args := []string{
+		"galaxy-browse",
+		"-endpoint", addr,
+		"-plaintext",
+		"-api-key", "test",
+		"-depth", "1",
+	}
+	if err := runWithIO(t.Context(), args, &stdout, &stderr); err != nil {
+		t.Fatalf("runWithIO() error = %v; stderr = %s", err, stderr.String())
+	}
+	out := stdout.String()
+	// Both roots present; the first root's eagerly-expanded child appears
+	// indented beneath it.
+	for _, want := range []string{"Area1", "Area2", "Tank"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("galaxy-browse text output missing %q; got:\n%s", want, out)
+		}
+	}
+	if !strings.Contains(out, "  ") {
+		t.Fatalf("galaxy-browse text output not indented for children; got:\n%s", out)
+	}
+}
+
+// TestRunGalaxyBrowseJSON verifies the galaxy-browse subcommand emits valid
+// nested JSON and forwards filter options onto the BrowseChildren request.
+func TestRunGalaxyBrowseJSON(t *testing.T) {
+	addr, fake := startBrowseFakeGalaxy(t)
+
+	var stdout, stderr bytes.Buffer
+	args := []string{
+		"galaxy-browse",
+		"-endpoint", addr,
+		"-plaintext",
+		"-api-key", "test",
+		"-depth", "1",
+		"-tag-name-glob", "Area%",
+		"-alarm-bearing-only",
+		"-json",
+	}
+	if err := runWithIO(t.Context(), args, &stdout, &stderr); err != nil {
+		t.Fatalf("runWithIO() error = %v; stderr = %s", err, stderr.String())
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
+		t.Fatalf("parse JSON: %v\noutput: %s", err, stdout.String())
+	}
+	if payload["command"] != "galaxy-browse" {
+		t.Fatalf("command = %v, want galaxy-browse", payload["command"])
+	}
+	nodes, ok := payload["nodes"].([]any)
+	if !ok || len(nodes) != 2 {
+		t.Fatalf("nodes = %v, want 2 root nodes", payload["nodes"])
+	}
+	// Filter fields must have reached the wire.
+	if got := fake.lastRequest.GetTagNameGlob(); got != "Area%" {
+		t.Fatalf("BrowseChildren TagNameGlob = %q, want %q", got, "Area%")
+	}
+	if !fake.lastRequest.GetAlarmBearingOnly() {
+		t.Fatalf("BrowseChildren AlarmBearingOnly = false, want true")
+	}
+}
+
+// TestRunGalaxyBrowseParentSingleLevel verifies that passing --parent fetches a
+// single level of children for that parent via the parent-scoped request.
+func TestRunGalaxyBrowseParentSingleLevel(t *testing.T) {
+	addr, fake := startBrowseFakeGalaxy(t)
+
+	var stdout, stderr bytes.Buffer
+	args := []string{
+		"galaxy-browse",
+		"-endpoint", addr,
+		"-plaintext",
+		"-api-key", "test",
+		"-parent", "10",
+	}
+	if err := runWithIO(t.Context(), args, &stdout, &stderr); err != nil {
+		t.Fatalf("runWithIO() error = %v; stderr = %s", err, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "Tank") {
+		t.Fatalf("galaxy-browse -parent output missing child %q; got:\n%s", "Tank", stdout.String())
+	}
+	if got := fake.lastRequest.GetParentGobjectId(); got != 10 {
+		t.Fatalf("BrowseChildren ParentGobjectId = %d, want 10", got)
+	}
+}
+
+// TestRunBatchSkipsBlankLinesAndContinuesUntilEOF pins the Client.Go-027 fix:
+// a blank line in the middle of a batch session must NOT terminate the loop —
+// only stdin EOF ends the session.
+func TestRunBatchSkipsBlankLinesAndContinuesUntilEOF(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+
+	// version -> blank -> version (a stray blank line in the middle of a
+	// programmatic session).
+	in := strings.NewReader("version --json\n\nversion --json\n")
+	if err := runBatch(t.Context(), in, &stdout, &stderr); err != nil {
+		t.Fatalf("runBatch() error = %v; stderr = %s", err, stderr.String())
+	}
+
+	out := stdout.String()
+	// Both version commands must have produced a result before the EOR sentinel.
+	if count := strings.Count(out, batchEOR); count != 2 {
+		t.Fatalf("EOR sentinel count = %d, want 2 (one per command, blank line skipped); out = %q", count, out)
+	}
+}
+
+// TestRunBatchHandlesLongCommandLine pins the Client.Go-026 fix: a command
+// line longer than the default bufio.Scanner token size (64 KiB) must not
+// abort the batch session.
+func TestRunBatchHandlesLongCommandLine(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+
+	// Build a single command line larger than 64 KiB. The command itself is
+	// invalid (no real session) but runBatch must still emit an EOR sentinel
+	// and continue to the next command rather than dropping the line on the
+	// floor with a bufio.ErrTooLong from the outer return.
+	huge := strings.Repeat("tag-with-a-reasonably-long-name-and-suffix,", 2000) + "trailing"
+	line := "subscribe-bulk -session-id none -items " + huge
+	if len(line) <= 64*1024 {
+		t.Fatalf("test setup error: long line length = %d, want > 64KiB", len(line))
+	}
+	in := strings.NewReader(line + "\nversion --json\n")
+
+	if err := runBatch(t.Context(), in, &stdout, &stderr); err != nil {
+		t.Fatalf("runBatch() error = %v; stderr = %s", err, stderr.String())
+	}
+
+	out := stdout.String()
+	// Both commands must produce an EOR sentinel — the long line should be a
+	// per-command error (still emitted with EOR), then the version command
+	// should run normally.
+	if count := strings.Count(out, batchEOR); count != 2 {
+		t.Fatalf("EOR sentinel count = %d, want 2 (one per command, even when first is too long); out length = %d", count, len(out))
+	}
+}
+
+// TestRunBenchReadBulkRejectsNonPositiveDuration pins the -duration-seconds
+// positivity guard so the bench window cannot be configured to zero/negative.
+func TestRunBenchReadBulkRejectsNonPositiveDuration(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	err := runWithIO(t.Context(), []string{"bench-read-bulk", "-duration-seconds", "0"}, &stdout, &stderr)
+	if err == nil || !strings.Contains(err.Error(), "duration-seconds must be positive") {
+		t.Fatalf("bench-read-bulk -duration-seconds 0 error = %v", err)
+	}
+}
+
+// TestRunStreamEventsRequiresSessionID pins the session-id guard so stream-events
+// fails fast before dialing when no session id is supplied.
+func TestRunStreamEventsRequiresSessionID(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	err := runWithIO(t.Context(), []string{"stream-events", "-plaintext", "-api-key", "test"}, &stdout, &stderr)
+	if err == nil || !strings.Contains(err.Error(), "session-id is required") {
+		t.Fatalf("stream-events without -session-id error = %v", err)
+	}
+}
+
+// TestRunAdviseSupervisoryRequiresSessionID pins the session-id guard so
+// advise-supervisory fails fast before dialing when no session id is supplied.
+func TestRunAdviseSupervisoryRequiresSessionID(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	err := runWithIO(t.Context(), []string{"advise-supervisory", "-plaintext", "-api-key", "test"}, &stdout, &stderr)
+	if err == nil || !strings.Contains(err.Error(), "session-id is required") {
+		t.Fatalf("advise-supervisory without -session-id error = %v", err)
+	}
+}
+
+// TestRunWriteBulkVariantRejectsMismatchedHandlesAndValues pins the len-mismatch
+// guard so a write-bulk with unequal item-handles / values counts fails fast
+// before any dial.
+func TestRunWriteBulkVariantRejectsMismatchedHandlesAndValues(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	err := runWithIO(t.Context(), []string{
+		"write-bulk",
+		"-session-id", "s1",
+		"-server-handle", "1",
+		"-item-handles", "1,2",
+		"-values", "10",
+		"-type", "int32",
+		"-plaintext",
+		"-api-key", "test",
+	}, &stdout, &stderr)
+	if err == nil || !strings.Contains(err.Error(), "does not match values count") {
+		t.Fatalf("write-bulk mismatched handles/values error = %v", err)
+	}
+}

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

@@ -824,6 +824,260 @@ func (x *GalaxyAttribute) GetIsAlarm() bool {
 	return false
 }
 
+type BrowseChildrenRequest struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Parent selector. Empty oneof returns root objects (parent_gobject_id == 0).
+	//
+	// Types that are valid to be assigned to Parent:
+	//
+	//	*BrowseChildrenRequest_ParentGobjectId
+	//	*BrowseChildrenRequest_ParentTagName
+	//	*BrowseChildrenRequest_ParentContainedPath
+	Parent isBrowseChildrenRequest_Parent `protobuf_oneof:"parent"`
+	// Maximum number of direct children to return. Server default 500; cap 5000.
+	PageSize int32 `protobuf:"varint,4,opt,name=page_size,json=pageSize,proto3" json:"page_size,omitempty"`
+	// Opaque token returned by a previous BrowseChildren response. Bound to the
+	// cache sequence, parent selector, and the filter set; a mismatch returns
+	// InvalidArgument.
+	PageToken string `protobuf:"bytes,5,opt,name=page_token,json=pageToken,proto3" json:"page_token,omitempty"`
+	// --- Filter parity with DiscoverHierarchy. AND-combined. ---
+	CategoryIds           []int32  `protobuf:"varint,6,rep,packed,name=category_ids,json=categoryIds,proto3" json:"category_ids,omitempty"`
+	TemplateChainContains []string `protobuf:"bytes,7,rep,name=template_chain_contains,json=templateChainContains,proto3" json:"template_chain_contains,omitempty"`
+	TagNameGlob           string   `protobuf:"bytes,8,opt,name=tag_name_glob,json=tagNameGlob,proto3" json:"tag_name_glob,omitempty"`
+	IncludeAttributes     *bool    `protobuf:"varint,9,opt,name=include_attributes,json=includeAttributes,proto3,oneof" json:"include_attributes,omitempty"`
+	AlarmBearingOnly      bool     `protobuf:"varint,10,opt,name=alarm_bearing_only,json=alarmBearingOnly,proto3" json:"alarm_bearing_only,omitempty"`
+	HistorizedOnly        bool     `protobuf:"varint,11,opt,name=historized_only,json=historizedOnly,proto3" json:"historized_only,omitempty"`
+	unknownFields         protoimpl.UnknownFields
+	sizeCache             protoimpl.SizeCache
+}
+
+func (x *BrowseChildrenRequest) Reset() {
+	*x = BrowseChildrenRequest{}
+	mi := &file_galaxy_repository_proto_msgTypes[10]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *BrowseChildrenRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*BrowseChildrenRequest) ProtoMessage() {}
+
+func (x *BrowseChildrenRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_galaxy_repository_proto_msgTypes[10]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use BrowseChildrenRequest.ProtoReflect.Descriptor instead.
+func (*BrowseChildrenRequest) Descriptor() ([]byte, []int) {
+	return file_galaxy_repository_proto_rawDescGZIP(), []int{10}
+}
+
+func (x *BrowseChildrenRequest) GetParent() isBrowseChildrenRequest_Parent {
+	if x != nil {
+		return x.Parent
+	}
+	return nil
+}
+
+func (x *BrowseChildrenRequest) GetParentGobjectId() int32 {
+	if x != nil {
+		if x, ok := x.Parent.(*BrowseChildrenRequest_ParentGobjectId); ok {
+			return x.ParentGobjectId
+		}
+	}
+	return 0
+}
+
+func (x *BrowseChildrenRequest) GetParentTagName() string {
+	if x != nil {
+		if x, ok := x.Parent.(*BrowseChildrenRequest_ParentTagName); ok {
+			return x.ParentTagName
+		}
+	}
+	return ""
+}
+
+func (x *BrowseChildrenRequest) GetParentContainedPath() string {
+	if x != nil {
+		if x, ok := x.Parent.(*BrowseChildrenRequest_ParentContainedPath); ok {
+			return x.ParentContainedPath
+		}
+	}
+	return ""
+}
+
+func (x *BrowseChildrenRequest) GetPageSize() int32 {
+	if x != nil {
+		return x.PageSize
+	}
+	return 0
+}
+
+func (x *BrowseChildrenRequest) GetPageToken() string {
+	if x != nil {
+		return x.PageToken
+	}
+	return ""
+}
+
+func (x *BrowseChildrenRequest) GetCategoryIds() []int32 {
+	if x != nil {
+		return x.CategoryIds
+	}
+	return nil
+}
+
+func (x *BrowseChildrenRequest) GetTemplateChainContains() []string {
+	if x != nil {
+		return x.TemplateChainContains
+	}
+	return nil
+}
+
+func (x *BrowseChildrenRequest) GetTagNameGlob() string {
+	if x != nil {
+		return x.TagNameGlob
+	}
+	return ""
+}
+
+func (x *BrowseChildrenRequest) GetIncludeAttributes() bool {
+	if x != nil && x.IncludeAttributes != nil {
+		return *x.IncludeAttributes
+	}
+	return false
+}
+
+func (x *BrowseChildrenRequest) GetAlarmBearingOnly() bool {
+	if x != nil {
+		return x.AlarmBearingOnly
+	}
+	return false
+}
+
+func (x *BrowseChildrenRequest) GetHistorizedOnly() bool {
+	if x != nil {
+		return x.HistorizedOnly
+	}
+	return false
+}
+
+type isBrowseChildrenRequest_Parent interface {
+	isBrowseChildrenRequest_Parent()
+}
+
+type BrowseChildrenRequest_ParentGobjectId struct {
+	ParentGobjectId int32 `protobuf:"varint,1,opt,name=parent_gobject_id,json=parentGobjectId,proto3,oneof"`
+}
+
+type BrowseChildrenRequest_ParentTagName struct {
+	ParentTagName string `protobuf:"bytes,2,opt,name=parent_tag_name,json=parentTagName,proto3,oneof"`
+}
+
+type BrowseChildrenRequest_ParentContainedPath struct {
+	ParentContainedPath string `protobuf:"bytes,3,opt,name=parent_contained_path,json=parentContainedPath,proto3,oneof"`
+}
+
+func (*BrowseChildrenRequest_ParentGobjectId) isBrowseChildrenRequest_Parent() {}
+
+func (*BrowseChildrenRequest_ParentTagName) isBrowseChildrenRequest_Parent() {}
+
+func (*BrowseChildrenRequest_ParentContainedPath) isBrowseChildrenRequest_Parent() {}
+
+type BrowseChildrenReply struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Direct children matching the filter, sorted areas-first then by
+	// case-insensitive display name (same order as the dashboard tree).
+	Children []*GalaxyObject `protobuf:"bytes,1,rep,name=children,proto3" json:"children,omitempty"`
+	// Non-empty when another page of siblings is available.
+	NextPageToken string `protobuf:"bytes,2,opt,name=next_page_token,json=nextPageToken,proto3" json:"next_page_token,omitempty"`
+	// Total matching direct children of the parent (post-filter).
+	TotalChildCount int32 `protobuf:"varint,3,opt,name=total_child_count,json=totalChildCount,proto3" json:"total_child_count,omitempty"`
+	// Parallel array, indexed with `children`. True when the child has at least
+	// one matching descendant under the same filter set. Lets a UI choose
+	// whether to draw an expand triangle without an extra round trip.
+	ChildHasChildren []bool `protobuf:"varint,4,rep,packed,name=child_has_children,json=childHasChildren,proto3" json:"child_has_children,omitempty"`
+	// Cache sequence this reply was projected from. Clients may pass it back as
+	// part of the page_token contract. Mismatch on the next page -> InvalidArgument.
+	CacheSequence uint64 `protobuf:"varint,5,opt,name=cache_sequence,json=cacheSequence,proto3" json:"cache_sequence,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *BrowseChildrenReply) Reset() {
+	*x = BrowseChildrenReply{}
+	mi := &file_galaxy_repository_proto_msgTypes[11]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *BrowseChildrenReply) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*BrowseChildrenReply) ProtoMessage() {}
+
+func (x *BrowseChildrenReply) ProtoReflect() protoreflect.Message {
+	mi := &file_galaxy_repository_proto_msgTypes[11]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use BrowseChildrenReply.ProtoReflect.Descriptor instead.
+func (*BrowseChildrenReply) Descriptor() ([]byte, []int) {
+	return file_galaxy_repository_proto_rawDescGZIP(), []int{11}
+}
+
+func (x *BrowseChildrenReply) GetChildren() []*GalaxyObject {
+	if x != nil {
+		return x.Children
+	}
+	return nil
+}
+
+func (x *BrowseChildrenReply) GetNextPageToken() string {
+	if x != nil {
+		return x.NextPageToken
+	}
+	return ""
+}
+
+func (x *BrowseChildrenReply) GetTotalChildCount() int32 {
+	if x != nil {
+		return x.TotalChildCount
+	}
+	return 0
+}
+
+func (x *BrowseChildrenReply) GetChildHasChildren() []bool {
+	if x != nil {
+		return x.ChildHasChildren
+	}
+	return nil
+}
+
+func (x *BrowseChildrenReply) GetCacheSequence() uint64 {
+	if x != nil {
+		return x.CacheSequence
+	}
+	return 0
+}
+
 var File_galaxy_repository_proto protoreflect.FileDescriptor
 
 const file_galaxy_repository_proto_rawDesc = "" +
@@ -897,12 +1151,35 @@ const file_galaxy_repository_proto_rawDesc = "" +
 	"\x17security_classification\x18\t \x01(\x05R\x16securityClassification\x12#\n" +
 	"\ris_historized\x18\n" +
 	" \x01(\bR\fisHistorized\x12\x19\n" +
-	"\bis_alarm\x18\v \x01(\bR\aisAlarm2\xcc\x03\n" +
+	"\bis_alarm\x18\v \x01(\bR\aisAlarm\"\x8c\x04\n" +
+	"\x15BrowseChildrenRequest\x12,\n" +
+	"\x11parent_gobject_id\x18\x01 \x01(\x05H\x00R\x0fparentGobjectId\x12(\n" +
+	"\x0fparent_tag_name\x18\x02 \x01(\tH\x00R\rparentTagName\x124\n" +
+	"\x15parent_contained_path\x18\x03 \x01(\tH\x00R\x13parentContainedPath\x12\x1b\n" +
+	"\tpage_size\x18\x04 \x01(\x05R\bpageSize\x12\x1d\n" +
+	"\n" +
+	"page_token\x18\x05 \x01(\tR\tpageToken\x12!\n" +
+	"\fcategory_ids\x18\x06 \x03(\x05R\vcategoryIds\x126\n" +
+	"\x17template_chain_contains\x18\a \x03(\tR\x15templateChainContains\x12\"\n" +
+	"\rtag_name_glob\x18\b \x01(\tR\vtagNameGlob\x122\n" +
+	"\x12include_attributes\x18\t \x01(\bH\x01R\x11includeAttributes\x88\x01\x01\x12,\n" +
+	"\x12alarm_bearing_only\x18\n" +
+	" \x01(\bR\x10alarmBearingOnly\x12'\n" +
+	"\x0fhistorized_only\x18\v \x01(\bR\x0ehistorizedOnlyB\b\n" +
+	"\x06parentB\x15\n" +
+	"\x13_include_attributes\"\xfe\x01\n" +
+	"\x13BrowseChildrenReply\x12>\n" +
+	"\bchildren\x18\x01 \x03(\v2\".galaxy_repository.v1.GalaxyObjectR\bchildren\x12&\n" +
+	"\x0fnext_page_token\x18\x02 \x01(\tR\rnextPageToken\x12*\n" +
+	"\x11total_child_count\x18\x03 \x01(\x05R\x0ftotalChildCount\x12,\n" +
+	"\x12child_has_children\x18\x04 \x03(\bR\x10childHasChildren\x12%\n" +
+	"\x0ecache_sequence\x18\x05 \x01(\x04R\rcacheSequence2\xb6\x04\n" +
 	"\x10GalaxyRepository\x12h\n" +
 	"\x0eTestConnection\x12+.galaxy_repository.v1.TestConnectionRequest\x1a).galaxy_repository.v1.TestConnectionReply\x12q\n" +
 	"\x11GetLastDeployTime\x12..galaxy_repository.v1.GetLastDeployTimeRequest\x1a,.galaxy_repository.v1.GetLastDeployTimeReply\x12q\n" +
 	"\x11DiscoverHierarchy\x12..galaxy_repository.v1.DiscoverHierarchyRequest\x1a,.galaxy_repository.v1.DiscoverHierarchyReply\x12h\n" +
-	"\x11WatchDeployEvents\x12..galaxy_repository.v1.WatchDeployEventsRequest\x1a!.galaxy_repository.v1.DeployEvent0\x01B-\xaa\x02*ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxyb\x06proto3"
+	"\x11WatchDeployEvents\x12..galaxy_repository.v1.WatchDeployEventsRequest\x1a!.galaxy_repository.v1.DeployEvent0\x01\x12h\n" +
+	"\x0eBrowseChildren\x12+.galaxy_repository.v1.BrowseChildrenRequest\x1a).galaxy_repository.v1.BrowseChildrenReplyB-\xaa\x02*ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxyb\x06proto3"
 
 var (
 	file_galaxy_repository_proto_rawDescOnce sync.Once
@@ -916,7 +1193,7 @@ func file_galaxy_repository_proto_rawDescGZIP() []byte {
 	return file_galaxy_repository_proto_rawDescData
 }
 
-var file_galaxy_repository_proto_msgTypes = make([]protoimpl.MessageInfo, 10)
+var file_galaxy_repository_proto_msgTypes = make([]protoimpl.MessageInfo, 12)
 var file_galaxy_repository_proto_goTypes = []any{
 	(*TestConnectionRequest)(nil),    // 0: galaxy_repository.v1.TestConnectionRequest
 	(*TestConnectionReply)(nil),      // 1: galaxy_repository.v1.TestConnectionReply
@@ -928,30 +1205,35 @@ var file_galaxy_repository_proto_goTypes = []any{
 	(*DeployEvent)(nil),              // 7: galaxy_repository.v1.DeployEvent
 	(*GalaxyObject)(nil),             // 8: galaxy_repository.v1.GalaxyObject
 	(*GalaxyAttribute)(nil),          // 9: galaxy_repository.v1.GalaxyAttribute
-	(*timestamppb.Timestamp)(nil),    // 10: google.protobuf.Timestamp
-	(*wrapperspb.Int32Value)(nil),    // 11: google.protobuf.Int32Value
+	(*BrowseChildrenRequest)(nil),    // 10: galaxy_repository.v1.BrowseChildrenRequest
+	(*BrowseChildrenReply)(nil),      // 11: galaxy_repository.v1.BrowseChildrenReply
+	(*timestamppb.Timestamp)(nil),    // 12: google.protobuf.Timestamp
+	(*wrapperspb.Int32Value)(nil),    // 13: google.protobuf.Int32Value
 }
 var file_galaxy_repository_proto_depIdxs = []int32{
-	10, // 0: galaxy_repository.v1.GetLastDeployTimeReply.time_of_last_deploy:type_name -> google.protobuf.Timestamp
-	11, // 1: galaxy_repository.v1.DiscoverHierarchyRequest.max_depth:type_name -> google.protobuf.Int32Value
+	12, // 0: galaxy_repository.v1.GetLastDeployTimeReply.time_of_last_deploy:type_name -> google.protobuf.Timestamp
+	13, // 1: galaxy_repository.v1.DiscoverHierarchyRequest.max_depth:type_name -> google.protobuf.Int32Value
 	8,  // 2: galaxy_repository.v1.DiscoverHierarchyReply.objects:type_name -> galaxy_repository.v1.GalaxyObject
-	10, // 3: galaxy_repository.v1.WatchDeployEventsRequest.last_seen_deploy_time:type_name -> google.protobuf.Timestamp
-	10, // 4: galaxy_repository.v1.DeployEvent.observed_at:type_name -> google.protobuf.Timestamp
-	10, // 5: galaxy_repository.v1.DeployEvent.time_of_last_deploy:type_name -> google.protobuf.Timestamp
+	12, // 3: galaxy_repository.v1.WatchDeployEventsRequest.last_seen_deploy_time:type_name -> google.protobuf.Timestamp
+	12, // 4: galaxy_repository.v1.DeployEvent.observed_at:type_name -> google.protobuf.Timestamp
+	12, // 5: galaxy_repository.v1.DeployEvent.time_of_last_deploy:type_name -> google.protobuf.Timestamp
 	9,  // 6: galaxy_repository.v1.GalaxyObject.attributes:type_name -> galaxy_repository.v1.GalaxyAttribute
-	0,  // 7: galaxy_repository.v1.GalaxyRepository.TestConnection:input_type -> galaxy_repository.v1.TestConnectionRequest
-	2,  // 8: galaxy_repository.v1.GalaxyRepository.GetLastDeployTime:input_type -> galaxy_repository.v1.GetLastDeployTimeRequest
-	4,  // 9: galaxy_repository.v1.GalaxyRepository.DiscoverHierarchy:input_type -> galaxy_repository.v1.DiscoverHierarchyRequest
-	6,  // 10: galaxy_repository.v1.GalaxyRepository.WatchDeployEvents:input_type -> galaxy_repository.v1.WatchDeployEventsRequest
-	1,  // 11: galaxy_repository.v1.GalaxyRepository.TestConnection:output_type -> galaxy_repository.v1.TestConnectionReply
-	3,  // 12: galaxy_repository.v1.GalaxyRepository.GetLastDeployTime:output_type -> galaxy_repository.v1.GetLastDeployTimeReply
-	5,  // 13: galaxy_repository.v1.GalaxyRepository.DiscoverHierarchy:output_type -> galaxy_repository.v1.DiscoverHierarchyReply
-	7,  // 14: galaxy_repository.v1.GalaxyRepository.WatchDeployEvents:output_type -> galaxy_repository.v1.DeployEvent
-	11, // [11:15] is the sub-list for method output_type
-	7,  // [7:11] is the sub-list for method input_type
-	7,  // [7:7] is the sub-list for extension type_name
-	7,  // [7:7] is the sub-list for extension extendee
-	0,  // [0:7] is the sub-list for field type_name
+	8,  // 7: galaxy_repository.v1.BrowseChildrenReply.children:type_name -> galaxy_repository.v1.GalaxyObject
+	0,  // 8: galaxy_repository.v1.GalaxyRepository.TestConnection:input_type -> galaxy_repository.v1.TestConnectionRequest
+	2,  // 9: galaxy_repository.v1.GalaxyRepository.GetLastDeployTime:input_type -> galaxy_repository.v1.GetLastDeployTimeRequest
+	4,  // 10: galaxy_repository.v1.GalaxyRepository.DiscoverHierarchy:input_type -> galaxy_repository.v1.DiscoverHierarchyRequest
+	6,  // 11: galaxy_repository.v1.GalaxyRepository.WatchDeployEvents:input_type -> galaxy_repository.v1.WatchDeployEventsRequest
+	10, // 12: galaxy_repository.v1.GalaxyRepository.BrowseChildren:input_type -> galaxy_repository.v1.BrowseChildrenRequest
+	1,  // 13: galaxy_repository.v1.GalaxyRepository.TestConnection:output_type -> galaxy_repository.v1.TestConnectionReply
+	3,  // 14: galaxy_repository.v1.GalaxyRepository.GetLastDeployTime:output_type -> galaxy_repository.v1.GetLastDeployTimeReply
+	5,  // 15: galaxy_repository.v1.GalaxyRepository.DiscoverHierarchy:output_type -> galaxy_repository.v1.DiscoverHierarchyReply
+	7,  // 16: galaxy_repository.v1.GalaxyRepository.WatchDeployEvents:output_type -> galaxy_repository.v1.DeployEvent
+	11, // 17: galaxy_repository.v1.GalaxyRepository.BrowseChildren:output_type -> galaxy_repository.v1.BrowseChildrenReply
+	13, // [13:18] is the sub-list for method output_type
+	8,  // [8:13] is the sub-list for method input_type
+	8,  // [8:8] is the sub-list for extension type_name
+	8,  // [8:8] is the sub-list for extension extendee
+	0,  // [0:8] is the sub-list for field type_name
 }
 
 func init() { file_galaxy_repository_proto_init() }
@@ -964,13 +1246,18 @@ func file_galaxy_repository_proto_init() {
 		(*DiscoverHierarchyRequest_RootTagName)(nil),
 		(*DiscoverHierarchyRequest_RootContainedPath)(nil),
 	}
+	file_galaxy_repository_proto_msgTypes[10].OneofWrappers = []any{
+		(*BrowseChildrenRequest_ParentGobjectId)(nil),
+		(*BrowseChildrenRequest_ParentTagName)(nil),
+		(*BrowseChildrenRequest_ParentContainedPath)(nil),
+	}
 	type x struct{}
 	out := protoimpl.TypeBuilder{
 		File: protoimpl.DescBuilder{
 			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
 			RawDescriptor: unsafe.Slice(unsafe.StringData(file_galaxy_repository_proto_rawDesc), len(file_galaxy_repository_proto_rawDesc)),
 			NumEnums:      0,
-			NumMessages:   10,
+			NumMessages:   12,
 			NumExtensions: 0,
 			NumServices:   1,
 		},

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

@@ -1,6 +1,6 @@
 // Code generated by protoc-gen-go-grpc. DO NOT EDIT.
 // versions:
-// - protoc-gen-go-grpc v1.6.1
+// - protoc-gen-go-grpc v1.6.2
 // - protoc             v7.34.1
 // source: galaxy_repository.proto
 
@@ -23,6 +23,7 @@ const (
 	GalaxyRepository_GetLastDeployTime_FullMethodName = "/galaxy_repository.v1.GalaxyRepository/GetLastDeployTime"
 	GalaxyRepository_DiscoverHierarchy_FullMethodName = "/galaxy_repository.v1.GalaxyRepository/DiscoverHierarchy"
 	GalaxyRepository_WatchDeployEvents_FullMethodName = "/galaxy_repository.v1.GalaxyRepository/WatchDeployEvents"
+	GalaxyRepository_BrowseChildren_FullMethodName    = "/galaxy_repository.v1.GalaxyRepository/BrowseChildren"
 )
 
 // GalaxyRepositoryClient is the client API for GalaxyRepository service.
@@ -44,6 +45,11 @@ type GalaxyRepositoryClient interface {
 	// increasing per server start; gaps indicate the per-subscriber buffer dropped
 	// older events because the client was too slow.
 	WatchDeployEvents(ctx context.Context, in *WatchDeployEventsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[DeployEvent], error)
+	// Returns the direct children of a parent object (or the root objects when
+	// `parent` is unset). Designed for OPC UA-style lazy expand: clients walk
+	// one level at a time instead of paging the full hierarchy. Filters mirror
+	// DiscoverHierarchy exactly. Backed by the same shared hierarchy cache.
+	BrowseChildren(ctx context.Context, in *BrowseChildrenRequest, opts ...grpc.CallOption) (*BrowseChildrenReply, error)
 }
 
 type galaxyRepositoryClient struct {
@@ -103,6 +109,16 @@ func (c *galaxyRepositoryClient) WatchDeployEvents(ctx context.Context, in *Watc
 // This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
 type GalaxyRepository_WatchDeployEventsClient = grpc.ServerStreamingClient[DeployEvent]
 
+func (c *galaxyRepositoryClient) BrowseChildren(ctx context.Context, in *BrowseChildrenRequest, opts ...grpc.CallOption) (*BrowseChildrenReply, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(BrowseChildrenReply)
+	err := c.cc.Invoke(ctx, GalaxyRepository_BrowseChildren_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 // GalaxyRepositoryServer is the server API for GalaxyRepository service.
 // All implementations must embed UnimplementedGalaxyRepositoryServer
 // for forward compatibility.
@@ -122,6 +138,11 @@ type GalaxyRepositoryServer interface {
 	// increasing per server start; gaps indicate the per-subscriber buffer dropped
 	// older events because the client was too slow.
 	WatchDeployEvents(*WatchDeployEventsRequest, grpc.ServerStreamingServer[DeployEvent]) error
+	// Returns the direct children of a parent object (or the root objects when
+	// `parent` is unset). Designed for OPC UA-style lazy expand: clients walk
+	// one level at a time instead of paging the full hierarchy. Filters mirror
+	// DiscoverHierarchy exactly. Backed by the same shared hierarchy cache.
+	BrowseChildren(context.Context, *BrowseChildrenRequest) (*BrowseChildrenReply, error)
 	mustEmbedUnimplementedGalaxyRepositoryServer()
 }
 
@@ -144,6 +165,9 @@ func (UnimplementedGalaxyRepositoryServer) DiscoverHierarchy(context.Context, *D
 func (UnimplementedGalaxyRepositoryServer) WatchDeployEvents(*WatchDeployEventsRequest, grpc.ServerStreamingServer[DeployEvent]) error {
 	return status.Error(codes.Unimplemented, "method WatchDeployEvents not implemented")
 }
+func (UnimplementedGalaxyRepositoryServer) BrowseChildren(context.Context, *BrowseChildrenRequest) (*BrowseChildrenReply, error) {
+	return nil, status.Error(codes.Unimplemented, "method BrowseChildren not implemented")
+}
 func (UnimplementedGalaxyRepositoryServer) mustEmbedUnimplementedGalaxyRepositoryServer() {}
 func (UnimplementedGalaxyRepositoryServer) testEmbeddedByValue()                          {}
 
@@ -230,6 +254,24 @@ func _GalaxyRepository_WatchDeployEvents_Handler(srv interface{}, stream grpc.Se
 // This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
 type GalaxyRepository_WatchDeployEventsServer = grpc.ServerStreamingServer[DeployEvent]
 
+func _GalaxyRepository_BrowseChildren_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(BrowseChildrenRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(GalaxyRepositoryServer).BrowseChildren(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: GalaxyRepository_BrowseChildren_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(GalaxyRepositoryServer).BrowseChildren(ctx, req.(*BrowseChildrenRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
 // GalaxyRepository_ServiceDesc is the grpc.ServiceDesc for GalaxyRepository service.
 // It's only intended for direct use with grpc.RegisterService,
 // and not to be introspected or modified (even as a copy)
@@ -249,6 +291,10 @@ var GalaxyRepository_ServiceDesc = grpc.ServiceDesc{
 			MethodName: "DiscoverHierarchy",
 			Handler:    _GalaxyRepository_DiscoverHierarchy_Handler,
 		},
+		{
+			MethodName: "BrowseChildren",
+			Handler:    _GalaxyRepository_BrowseChildren_Handler,
+		},
 	},
 	Streams: []grpc.StreamDesc{
 		{

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

@@ -1,6 +1,6 @@
 // Code generated by protoc-gen-go-grpc. DO NOT EDIT.
 // versions:
-// - protoc-gen-go-grpc v1.6.1
+// - protoc-gen-go-grpc v1.6.2
 // - protoc             v7.34.1
 // source: mxaccess_gateway.proto
 
@@ -50,6 +50,9 @@ type MxAccessGatewayClient interface {
 	// reconnect to seed Part 9 client state, or to reconcile alarms that may
 	// have been missed during a transport blip. Streamed so callers can
 	// begin processing without buffering the full set.
+	// `QueryActiveAlarmsRequest.alarm_filter_prefix` optionally narrows the
+	// snapshot to alarms whose `alarm_full_reference` starts with the given
+	// prefix; an empty prefix returns the full set.
 	QueryActiveAlarms(ctx context.Context, in *QueryActiveAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[ActiveAlarmSnapshot], error)
 }
 
@@ -180,6 +183,9 @@ type MxAccessGatewayServer interface {
 	// reconnect to seed Part 9 client state, or to reconcile alarms that may
 	// have been missed during a transport blip. Streamed so callers can
 	// begin processing without buffering the full set.
+	// `QueryActiveAlarmsRequest.alarm_filter_prefix` optionally narrows the
+	// snapshot to alarms whose `alarm_full_reference` starts with the given
+	// prefix; an empty prefix returns the full set.
 	QueryActiveAlarms(*QueryActiveAlarmsRequest, grpc.ServerStreamingServer[ActiveAlarmSnapshot]) error
 	mustEmbedUnimplementedMxAccessGatewayServer()
 }

clients/go/mxgateway/alarms.go

@@ -51,3 +51,26 @@ func (c *Client) QueryActiveAlarms(ctx context.Context, req *QueryActiveAlarmsRe
 
 	return stream, nil
 }
+
+// StreamAlarms attaches to the gateway's central alarm feed. The stream opens
+// with one AlarmFeedMessage per currently-active alarm (the ConditionRefresh
+// snapshot), then a single snapshot-complete sentinel, then a transition for
+// every subsequent raise / acknowledge / clear. It is served by the gateway's
+// always-on alarm monitor — no worker session is opened — so any number of
+// clients may attach.
+//
+// The returned stream is owned by the caller; cancel ctx to release it.
+// Optional alarm-reference prefix scoping (req.AlarmFilterPrefix) limits the
+// stream to a sub-tree.
+func (c *Client) StreamAlarms(ctx context.Context, req *StreamAlarmsRequest) (StreamAlarmsClient, error) {
+	if req == nil {
+		return nil, errors.New("mxgateway: stream alarms request is required")
+	}
+
+	stream, err := c.raw.StreamAlarms(ctx, req)
+	if err != nil {
+		return nil, &GatewayError{Op: "stream alarms", Err: err}
+	}
+
+	return stream, nil
+}

clients/go/mxgateway/alarms_test.go

@@ -147,8 +147,8 @@ func TestQueryActiveAlarmsPassesFilterPrefix(t *testing.T) {
 	defer cleanup()
 
 	stream, err := client.QueryActiveAlarms(context.Background(), &pb.QueryActiveAlarmsRequest{
-		SessionId:          "session-1",
-		AlarmFilterPrefix:  "Tank01.",
+		SessionId:         "session-1",
+		AlarmFilterPrefix: "Tank01.",
 	})
 	if err != nil {
 		t.Fatalf("QueryActiveAlarms() error = %v", err)
@@ -168,6 +168,66 @@ func TestQueryActiveAlarmsPassesFilterPrefix(t *testing.T) {
 	}
 }
 
+func TestStreamAlarmsPassesFilterPrefixAndReceivesFeedMessages(t *testing.T) {
+	fake := &fakeGatewayWithAlarms{
+		feedMessages: []*pb.AlarmFeedMessage{
+			{
+				Payload: &pb.AlarmFeedMessage_ActiveAlarm{
+					ActiveAlarm: &pb.ActiveAlarmSnapshot{
+						AlarmFullReference: "Tank01.Level.HiHi",
+						CurrentState:       pb.AlarmConditionState_ALARM_CONDITION_STATE_ACTIVE,
+					},
+				},
+			},
+			{
+				Payload: &pb.AlarmFeedMessage_SnapshotComplete{
+					SnapshotComplete: true,
+				},
+			},
+		},
+	}
+	client, cleanup := newBufconnClientWithAlarms(t, fake)
+	defer cleanup()
+
+	stream, err := client.StreamAlarms(context.Background(), &pb.StreamAlarmsRequest{
+		AlarmFilterPrefix: "Tank01.",
+	})
+	if err != nil {
+		t.Fatalf("StreamAlarms() error = %v", err)
+	}
+
+	var received []*pb.AlarmFeedMessage
+	for {
+		msg, err := stream.Recv()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			t.Fatalf("stream.Recv() error = %v", err)
+		}
+		received = append(received, msg)
+	}
+	if len(received) != 2 {
+		t.Fatalf("received count = %d, want 2", len(received))
+	}
+	if got := fake.streamRequest.GetAlarmFilterPrefix(); got != "Tank01." {
+		t.Fatalf("captured filter prefix = %q", got)
+	}
+	if got := fake.streamAuth; got != "Bearer test-api-key" {
+		t.Fatalf("stream authorization metadata = %q", got)
+	}
+}
+
+func TestStreamAlarmsRejectsNilRequest(t *testing.T) {
+	fake := &fakeGatewayWithAlarms{}
+	client, cleanup := newBufconnClientWithAlarms(t, fake)
+	defer cleanup()
+
+	if _, err := client.StreamAlarms(context.Background(), nil); err == nil {
+		t.Fatal("StreamAlarms(nil) returned no error")
+	}
+}
+
 type fakeGatewayWithAlarms struct {
 	pb.UnimplementedMxAccessGatewayServer
 
@@ -178,6 +238,10 @@ type fakeGatewayWithAlarms struct {
 
 	queryRequest    *pb.QueryActiveAlarmsRequest
 	activeSnapshots []*pb.ActiveAlarmSnapshot
+
+	streamRequest *pb.StreamAlarmsRequest
+	feedMessages  []*pb.AlarmFeedMessage
+	streamAuth    string
 }
 
 func (s *fakeGatewayWithAlarms) AcknowledgeAlarm(ctx context.Context, req *pb.AcknowledgeAlarmRequest) (*pb.AcknowledgeAlarmReply, error) {
@@ -207,6 +271,17 @@ func (s *fakeGatewayWithAlarms) QueryActiveAlarms(req *pb.QueryActiveAlarmsReque
 	return nil
 }
 
+func (s *fakeGatewayWithAlarms) StreamAlarms(req *pb.StreamAlarmsRequest, stream grpc.ServerStreamingServer[pb.AlarmFeedMessage]) error {
+	s.streamRequest = req
+	s.streamAuth = authorizationFromContext(stream.Context())
+	for _, msg := range s.feedMessages {
+		if err := stream.Send(msg); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
 func newBufconnClientWithAlarms(t *testing.T, fake *fakeGatewayWithAlarms) (*Client, func()) {
 	t.Helper()
 	listener := bufconn.Listen(bufSize)

clients/go/mxgateway/client.go

@@ -222,10 +222,22 @@ func resolveTransportCredentials(opts Options) (credentials.TransportCredentials
 		return credentials.NewTLS(cfg), nil
 	}
 
-	return credentials.NewTLS(&tls.Config{
-		MinVersion: tls.VersionTLS12,
-		ServerName: opts.ServerNameOverride,
-	}), nil
+	return credentials.NewTLS(tlsConfigForOptions(opts)), nil
+}
+
+// tlsConfigForOptions returns the *tls.Config for the no-CA, no-custom-config TLS path.
+// It returns nil when the caller should use a different credentials path (CA file or custom TLSConfig).
+// Exposed as an internal helper so unit tests can assert the InsecureSkipVerify posture.
+func tlsConfigForOptions(opts Options) *tls.Config {
+	// CA file and custom TLSConfig take their own paths in resolveTransportCredentials.
+	if opts.CACertFile != "" || opts.TLSConfig != nil {
+		return nil
+	}
+	return &tls.Config{
+		MinVersion:         tls.VersionTLS12,
+		ServerName:         opts.ServerNameOverride,
+		InsecureSkipVerify: !opts.RequireCertificateValidation, //nolint:gosec // internal tool; self-signed gateway cert expected; opt-in strict via RequireCertificateValidation
+	}
 }
 
 // OpenSessionOptions describes fields used to create an OpenSessionRequest.

clients/go/mxgateway/client_session_test.go

@@ -230,6 +230,289 @@ func TestSubscribeBulkBuildsOneBulkCommandAndReturnsResults(t *testing.T) {
 	}
 }
 
+func TestWriteBulkBuildsOneBulkCommandAndReturnsPerEntryResults(t *testing.T) {
+	fake := &fakeGatewayServer{
+		invokeReply: &pb.MxCommandReply{
+			SessionId: "session-1",
+			Kind:      pb.MxCommandKind_MX_COMMAND_KIND_WRITE_BULK,
+			ProtocolStatus: &pb.ProtocolStatus{
+				Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
+			},
+			Payload: &pb.MxCommandReply_WriteBulk{
+				WriteBulk: &pb.BulkWriteReply{
+					Results: []*pb.BulkWriteResult{
+						{ItemHandle: 10, WasSuccessful: true},
+						{ItemHandle: 11, WasSuccessful: true},
+					},
+				},
+			},
+		},
+	}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	entries := []*WriteBulkEntry{
+		{ItemHandle: 10, Value: Int32Value(7), UserId: 100},
+		{ItemHandle: 11, Value: Int32Value(8), UserId: 100},
+	}
+	results, err := session.WriteBulk(context.Background(), 12, entries)
+	if err != nil {
+		t.Fatalf("WriteBulk() error = %v", err)
+	}
+	if len(results) != 2 {
+		t.Fatalf("results len = %d, want 2", len(results))
+	}
+	req := fake.invokeRequest
+	if req.GetCommand().GetKind() != pb.MxCommandKind_MX_COMMAND_KIND_WRITE_BULK {
+		t.Fatalf("command kind = %s", req.GetCommand().GetKind())
+	}
+	if got := req.GetCommand().GetWriteBulk().GetEntries(); len(got) != 2 {
+		t.Fatalf("entry count = %d, want 2", len(got))
+	}
+}
+
+func TestWriteBulkRejectsNilEntries(t *testing.T) {
+	fake := &fakeGatewayServer{}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	if _, err := session.WriteBulk(context.Background(), 12, nil); err == nil {
+		t.Fatal("WriteBulk(nil) returned no error")
+	}
+	if _, err := session.Write2Bulk(context.Background(), 12, nil); err == nil {
+		t.Fatal("Write2Bulk(nil) returned no error")
+	}
+	if _, err := session.WriteSecuredBulk(context.Background(), 12, nil); err == nil {
+		t.Fatal("WriteSecuredBulk(nil) returned no error")
+	}
+	if _, err := session.WriteSecured2Bulk(context.Background(), 12, nil); err == nil {
+		t.Fatal("WriteSecured2Bulk(nil) returned no error")
+	}
+	if _, err := session.ReadBulk(context.Background(), 12, nil, 0); err == nil {
+		t.Fatal("ReadBulk(nil) returned no error")
+	}
+}
+
+func TestBulkMethodsShortCircuitOnEmptySliceWithoutRoundTrip(t *testing.T) {
+	fake := &fakeGatewayServer{
+		invokeReply: &pb.MxCommandReply{
+			ProtocolStatus: &pb.ProtocolStatus{
+				Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
+			},
+		},
+	}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	results, err := session.WriteBulk(context.Background(), 12, []*WriteBulkEntry{})
+	if err != nil {
+		t.Fatalf("WriteBulk(empty) error = %v", err)
+	}
+	if len(results) != 0 {
+		t.Fatalf("WriteBulk(empty) results len = %d, want 0", len(results))
+	}
+	if fake.invokeRequest != nil {
+		t.Fatal("WriteBulk(empty) sent a round trip; expected short-circuit")
+	}
+
+	results2, err := session.Write2Bulk(context.Background(), 12, []*Write2BulkEntry{})
+	if err != nil {
+		t.Fatalf("Write2Bulk(empty) error = %v", err)
+	}
+	if len(results2) != 0 {
+		t.Fatalf("Write2Bulk(empty) results len = %d, want 0", len(results2))
+	}
+	if fake.invokeRequest != nil {
+		t.Fatal("Write2Bulk(empty) sent a round trip; expected short-circuit")
+	}
+
+	results3, err := session.WriteSecuredBulk(context.Background(), 12, []*WriteSecuredBulkEntry{})
+	if err != nil {
+		t.Fatalf("WriteSecuredBulk(empty) error = %v", err)
+	}
+	if len(results3) != 0 {
+		t.Fatalf("WriteSecuredBulk(empty) results len = %d, want 0", len(results3))
+	}
+	if fake.invokeRequest != nil {
+		t.Fatal("WriteSecuredBulk(empty) sent a round trip; expected short-circuit")
+	}
+
+	results4, err := session.WriteSecured2Bulk(context.Background(), 12, []*WriteSecured2BulkEntry{})
+	if err != nil {
+		t.Fatalf("WriteSecured2Bulk(empty) error = %v", err)
+	}
+	if len(results4) != 0 {
+		t.Fatalf("WriteSecured2Bulk(empty) results len = %d, want 0", len(results4))
+	}
+	if fake.invokeRequest != nil {
+		t.Fatal("WriteSecured2Bulk(empty) sent a round trip; expected short-circuit")
+	}
+
+	readResults, err := session.ReadBulk(context.Background(), 12, []string{}, 0)
+	if err != nil {
+		t.Fatalf("ReadBulk(empty) error = %v", err)
+	}
+	if len(readResults) != 0 {
+		t.Fatalf("ReadBulk(empty) results len = %d, want 0", len(readResults))
+	}
+	if fake.invokeRequest != nil {
+		t.Fatal("ReadBulk(empty) sent a round trip; expected short-circuit")
+	}
+}
+
+func TestWrite2BuildsCommandWithTimestampAndReturnsNoError(t *testing.T) {
+	fake := &fakeGatewayServer{
+		invokeReply: &pb.MxCommandReply{
+			SessionId: "session-1",
+			Kind:      pb.MxCommandKind_MX_COMMAND_KIND_WRITE2,
+			ProtocolStatus: &pb.ProtocolStatus{
+				Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
+			},
+		},
+	}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	val := Int32Value(99)
+	ts := Int32Value(77)
+	err := session.Write2(context.Background(), 12, 34, val, ts, 100)
+	if err != nil {
+		t.Fatalf("Write2() error = %v", err)
+	}
+
+	req := fake.invokeRequest
+	if req.GetCommand().GetKind() != pb.MxCommandKind_MX_COMMAND_KIND_WRITE2 {
+		t.Fatalf("command kind = %s, want WRITE2", req.GetCommand().GetKind())
+	}
+	w2 := req.GetCommand().GetWrite2()
+	if w2.GetServerHandle() != 12 {
+		t.Fatalf("server handle = %d, want 12", w2.GetServerHandle())
+	}
+	if w2.GetItemHandle() != 34 {
+		t.Fatalf("item handle = %d, want 34", w2.GetItemHandle())
+	}
+	if w2.GetValue().GetInt32Value() != 99 {
+		t.Fatalf("value int32 = %d, want 99", w2.GetValue().GetInt32Value())
+	}
+	if w2.GetTimestampValue().GetInt32Value() != 77 {
+		t.Fatalf("timestamp value int32 = %d, want 77", w2.GetTimestampValue().GetInt32Value())
+	}
+	if w2.GetUserId() != 100 {
+		t.Fatalf("user id = %d, want 100", w2.GetUserId())
+	}
+}
+
+func TestWrite2RawReturnsRawReply(t *testing.T) {
+	fake := &fakeGatewayServer{
+		invokeReply: &pb.MxCommandReply{
+			SessionId: "session-1",
+			Kind:      pb.MxCommandKind_MX_COMMAND_KIND_WRITE2,
+			ProtocolStatus: &pb.ProtocolStatus{
+				Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
+			},
+		},
+	}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	reply, err := session.Write2Raw(context.Background(), 12, 34, Int32Value(1), Int32Value(0), 0)
+	if err != nil {
+		t.Fatalf("Write2Raw() error = %v", err)
+	}
+	if reply == nil {
+		t.Fatal("Write2Raw() returned nil reply")
+	}
+	if reply.GetKind() != pb.MxCommandKind_MX_COMMAND_KIND_WRITE2 {
+		t.Fatalf("reply kind = %s, want WRITE2", reply.GetKind())
+	}
+}
+
+func TestWrite2RejectsNilValue(t *testing.T) {
+	fake := &fakeGatewayServer{}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	if err := session.Write2(context.Background(), 12, 34, nil, Int32Value(0), 0); err == nil {
+		t.Fatal("Write2(nil value) returned no error")
+	}
+	if err := session.Write2(context.Background(), 12, 34, Int32Value(1), nil, 0); err == nil {
+		t.Fatal("Write2(nil timestampValue) returned no error")
+	}
+}
+
+func TestReadBulkForwardsTimeoutAndUnpacksCachedFlag(t *testing.T) {
+	fake := &fakeGatewayServer{
+		invokeReply: &pb.MxCommandReply{
+			SessionId: "session-1",
+			Kind:      pb.MxCommandKind_MX_COMMAND_KIND_READ_BULK,
+			ProtocolStatus: &pb.ProtocolStatus{
+				Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
+			},
+			Payload: &pb.MxCommandReply_ReadBulk{
+				ReadBulk: &pb.BulkReadReply{
+					Results: []*pb.BulkReadResult{
+						{TagAddress: "Tank01.Level", WasSuccessful: true, WasCached: true},
+						{TagAddress: "Tank02.Level", WasSuccessful: true, WasCached: false},
+					},
+				},
+			},
+		},
+	}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	results, err := session.ReadBulk(context.Background(), 12, []string{"Tank01.Level", "Tank02.Level"}, 250*time.Millisecond)
+	if err != nil {
+		t.Fatalf("ReadBulk() error = %v", err)
+	}
+	if len(results) != 2 {
+		t.Fatalf("results len = %d, want 2", len(results))
+	}
+	if !results[0].GetWasCached() || results[1].GetWasCached() {
+		t.Fatalf("WasCached flags = [%v %v], want [true false]", results[0].GetWasCached(), results[1].GetWasCached())
+	}
+	req := fake.invokeRequest
+	if req.GetCommand().GetKind() != pb.MxCommandKind_MX_COMMAND_KIND_READ_BULK {
+		t.Fatalf("command kind = %s", req.GetCommand().GetKind())
+	}
+	if got := req.GetCommand().GetReadBulk().GetTimeoutMs(); got != 250 {
+		t.Fatalf("timeout ms = %d, want 250", got)
+	}
+}
+
+func TestReadBulkSaturatesTimeoutAboveMaxUint32(t *testing.T) {
+	fake := &fakeGatewayServer{
+		invokeReply: &pb.MxCommandReply{
+			SessionId: "session-1",
+			Kind:      pb.MxCommandKind_MX_COMMAND_KIND_READ_BULK,
+			ProtocolStatus: &pb.ProtocolStatus{
+				Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
+			},
+		},
+	}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	// 100 days in milliseconds exceeds MaxUint32 (~49.7 days).
+	hugeTimeout := 100 * 24 * time.Hour
+	_, err := session.ReadBulk(context.Background(), 12, []string{"Tank01.Level"}, hugeTimeout)
+	if err != nil {
+		t.Fatalf("ReadBulk() error = %v", err)
+	}
+	got := fake.invokeRequest.GetCommand().GetReadBulk().GetTimeoutMs()
+	if got != ^uint32(0) {
+		t.Fatalf("timeout ms = %d, want %d (MaxUint32)", got, ^uint32(0))
+	}
+}
+
 func TestInvokeReturnsTypedMxAccessErrorWithRawReply(t *testing.T) {
 	hresult := int32(-2147467259)
 	fake := &fakeGatewayServer{
@@ -383,3 +666,124 @@ func authorizationFromContext(ctx context.Context) string {
 	}
 	return values[0]
 }
+
+// ---------------------------------------------------------------------------
+// WriteArrayElements / buildSparseArrayValue unit tests
+// ---------------------------------------------------------------------------
+
+func TestBuildSparseArrayValueSetsSparseOneof(t *testing.T) {
+	elements := map[uint32]*MxValue{
+		2: Int32Value(99),
+		0: Int32Value(10),
+	}
+	v := buildSparseArrayValue(DataTypeInteger, 5, elements)
+
+	sa, ok := v.Kind.(*pb.MxValue_SparseArrayValue)
+	if !ok {
+		t.Fatalf("Kind is %T, want *pb.MxValue_SparseArrayValue", v.Kind)
+	}
+	got := sa.SparseArrayValue
+	if got.GetElementDataType() != DataTypeInteger {
+		t.Errorf("ElementDataType = %v, want DataTypeInteger", got.GetElementDataType())
+	}
+	if got.GetTotalLength() != 5 {
+		t.Errorf("TotalLength = %d, want 5", got.GetTotalLength())
+	}
+	if len(got.GetElements()) != 2 {
+		t.Fatalf("len(Elements) = %d, want 2", len(got.GetElements()))
+	}
+	// Elements must be sorted by index (ascending).
+	if got.GetElements()[0].GetIndex() != 0 {
+		t.Errorf("Elements[0].Index = %d, want 0", got.GetElements()[0].GetIndex())
+	}
+	if got.GetElements()[0].GetValue().GetInt32Value() != 10 {
+		t.Errorf("Elements[0].Value = %v, want 10", got.GetElements()[0].GetValue())
+	}
+	if got.GetElements()[1].GetIndex() != 2 {
+		t.Errorf("Elements[1].Index = %d, want 2", got.GetElements()[1].GetIndex())
+	}
+	if got.GetElements()[1].GetValue().GetInt32Value() != 99 {
+		t.Errorf("Elements[1].Value = %v, want 99", got.GetElements()[1].GetValue())
+	}
+}
+
+func TestBuildSparseArrayValueEmptyMapProducesEmptyElements(t *testing.T) {
+	v := buildSparseArrayValue(DataTypeBoolean, 4, map[uint32]*MxValue{})
+
+	sa, ok := v.Kind.(*pb.MxValue_SparseArrayValue)
+	if !ok {
+		t.Fatalf("Kind is %T, want *pb.MxValue_SparseArrayValue", v.Kind)
+	}
+	if len(sa.SparseArrayValue.GetElements()) != 0 {
+		t.Errorf("len(Elements) = %d, want 0", len(sa.SparseArrayValue.GetElements()))
+	}
+	if sa.SparseArrayValue.GetTotalLength() != 4 {
+		t.Errorf("TotalLength = %d, want 4", sa.SparseArrayValue.GetTotalLength())
+	}
+}
+
+func TestWriteArrayElementsSendsWriteCommandWithSparseOneof(t *testing.T) {
+	fake := &fakeGatewayServer{
+		invokeReply: &pb.MxCommandReply{
+			SessionId: "session-1",
+			Kind:      pb.MxCommandKind_MX_COMMAND_KIND_WRITE,
+			ProtocolStatus: &pb.ProtocolStatus{
+				Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
+			},
+		},
+	}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	err := session.WriteArrayElements(
+		context.Background(),
+		1, 2,
+		DataTypeFloat,
+		10,
+		map[uint32]*MxValue{3: FloatValue(1.5)},
+		42,
+	)
+	if err != nil {
+		t.Fatalf("WriteArrayElements() error = %v", err)
+	}
+
+	cmd := fake.invokeRequest.GetCommand()
+	if cmd.GetKind() != pb.MxCommandKind_MX_COMMAND_KIND_WRITE {
+		t.Fatalf("command kind = %s, want WRITE", cmd.GetKind())
+	}
+	w := cmd.GetWrite()
+	if w.GetServerHandle() != 1 {
+		t.Fatalf("server handle = %d, want 1", w.GetServerHandle())
+	}
+	if w.GetItemHandle() != 2 {
+		t.Fatalf("item handle = %d, want 2", w.GetItemHandle())
+	}
+	if w.GetUserId() == 0 {
+		t.Fatal("user id = 0, want non-zero")
+	}
+	if w.GetUserId() != 42 {
+		t.Fatalf("user id = %d, want 42", w.GetUserId())
+	}
+	val := w.GetValue()
+	sa, ok := val.Kind.(*pb.MxValue_SparseArrayValue)
+	if !ok {
+		t.Fatalf("value kind is %T, want *pb.MxValue_SparseArrayValue", val.Kind)
+	}
+	if sa.SparseArrayValue.GetTotalLength() != 10 {
+		t.Errorf("TotalLength = %d, want 10", sa.SparseArrayValue.GetTotalLength())
+	}
+	if sa.SparseArrayValue.GetElementDataType() != DataTypeFloat {
+		t.Errorf("ElementDataType = %v, want DataTypeFloat", sa.SparseArrayValue.GetElementDataType())
+	}
+	if len(sa.SparseArrayValue.GetElements()) != 1 {
+		t.Fatalf("len(Elements) = %d, want 1", len(sa.SparseArrayValue.GetElements()))
+	}
+	elem := sa.SparseArrayValue.GetElements()[0]
+	if elem.GetIndex() != 3 {
+		t.Errorf("element index = %d, want 3", elem.GetIndex())
+	}
+	if elem.GetValue().GetFloatValue() != 1.5 {
+		t.Errorf("element float value = %v, want 1.5", elem.GetValue().GetFloatValue())
+	}
+}

clients/go/mxgateway/client_tls_test.go

@@ -0,0 +1,59 @@
+package mxgateway
+
+import (
+	"crypto/tls"
+	"testing"
+)
+
+// tlsConfigFromOptions is the internal helper under test.
+// It extracts the *tls.Config from the no-CA TLS path of resolveTransportCredentials.
+// We exercise it directly to avoid needing a real dial target.
+
+func TestTLSInsecureSkipVerify_DefaultTrue(t *testing.T) {
+	cfg := tlsConfigForOptions(Options{
+		Endpoint: "localhost:5120",
+	})
+	if cfg == nil {
+		t.Fatal("expected non-nil tls.Config")
+	}
+	if !cfg.InsecureSkipVerify {
+		t.Error("InsecureSkipVerify should be true by default when no CA is pinned")
+	}
+}
+
+func TestTLSInsecureSkipVerify_FalseWhenRequireCertificateValidation(t *testing.T) {
+	cfg := tlsConfigForOptions(Options{
+		Endpoint:                     "localhost:5120",
+		RequireCertificateValidation: true,
+	})
+	if cfg == nil {
+		t.Fatal("expected non-nil tls.Config")
+	}
+	if cfg.InsecureSkipVerify {
+		t.Error("InsecureSkipVerify should be false when RequireCertificateValidation is true")
+	}
+}
+
+func TestTLSInsecureSkipVerify_FalseWhenCACertFileSet(t *testing.T) {
+	// When a CA file is pinned, the CA-verification path is taken instead.
+	// tlsConfigForOptions should return nil (the CA path does not use our helper).
+	cfg := tlsConfigForOptions(Options{
+		Endpoint:   "localhost:5120",
+		CACertFile: "/some/ca.pem",
+	})
+	if cfg != nil {
+		t.Error("expected nil tls.Config when CACertFile is set (CA path taken)")
+	}
+}
+
+func TestTLSInsecureSkipVerify_FalseWhenCustomTLSConfig(t *testing.T) {
+	// When TLSConfig is supplied explicitly, our default skip-verify must not overwrite it.
+	custom := &tls.Config{MinVersion: tls.VersionTLS13}
+	cfg := tlsConfigForOptions(Options{
+		Endpoint:  "localhost:5120",
+		TLSConfig: custom,
+	})
+	if cfg != nil {
+		t.Error("expected nil tls.Config when TLSConfig is already set (custom config path taken)")
+	}
+}

clients/go/mxgateway/galaxy.go

@@ -3,7 +3,9 @@ package mxgateway
 import (
 	"context"
 	"errors"
+	"fmt"
 	"io"
+	"sync"
 	"time"
 
 	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
@@ -13,6 +15,14 @@ import (
 	"google.golang.org/protobuf/types/known/timestamppb"
 )
 
+// browseChildrenPageSize is the per-request page size used by the lazy walker.
+const browseChildrenPageSize = 500
+
+// discoverHierarchyPageSize is the per-request page size used by DiscoverHierarchy.
+// Mirrors the .NET client constant so large galaxies are not silently truncated
+// by the server's default page cap.
+const discoverHierarchyPageSize = 5000
+
 // RawGalaxyRepositoryClient is the generated gRPC client interface for the
 // Galaxy Repository service exposed for callers that need direct contract
 // access.
@@ -40,6 +50,15 @@ type (
 	WatchDeployEventsRequest = pb.WatchDeployEventsRequest
 	// DeployEvent is one Galaxy Repository deploy event.
 	DeployEvent = pb.DeployEvent
+	// BrowseChildrenRequest is the request for BrowseChildren.
+	BrowseChildrenRequest = pb.BrowseChildrenRequest
+	// BrowseChildrenReply is the reply for BrowseChildren.
+	BrowseChildrenReply = pb.BrowseChildrenReply
+	// BrowseChildrenRequest_ParentGobjectId selects the parent-by-gobject-id
+	// variant of the BrowseChildrenRequest parent oneof. Exposed so callers
+	// (e.g. the mxgw-go CLI) can issue a parent-scoped single-level browse
+	// without reaching into the generated package.
+	BrowseChildrenRequest_ParentGobjectId = pb.BrowseChildrenRequest_ParentGobjectId //nolint:revive,staticcheck // mirrors generated proto oneof name
 )
 
 // RawDeployEventStream is the generated WatchDeployEvents client stream.
@@ -146,16 +165,35 @@ func (c *GalaxyClient) GetLastDeployTime(ctx context.Context) (time.Time, bool,
 
 // DiscoverHierarchy returns the deployed Galaxy object hierarchy with each
 // object's dynamic attributes. The objects are returned in the order supplied
-// by the server.
+// by the server. The call pages over the server's NextPageToken until the
+// server signals it has no more results, matching the .NET client.
 func (c *GalaxyClient) DiscoverHierarchy(ctx context.Context) ([]*GalaxyObject, error) {
-	callCtx, cancel := c.callContext(ctx)
-	defer cancel()
-
-	reply, err := c.raw.DiscoverHierarchy(callCtx, &pb.DiscoverHierarchyRequest{})
-	if err != nil {
-		return nil, &GatewayError{Op: "galaxy discover hierarchy", Err: err}
+	var objects []*GalaxyObject
+	pageToken := ""
+	seen := map[string]struct{}{}
+	for {
+		callCtx, cancel := c.callContext(ctx)
+		reply, err := c.raw.DiscoverHierarchy(callCtx, &pb.DiscoverHierarchyRequest{
+			PageSize:  discoverHierarchyPageSize,
+			PageToken: pageToken,
+		})
+		cancel()
+		if err != nil {
+			return nil, &GatewayError{Op: "galaxy discover hierarchy", Err: err}
+		}
+		objects = append(objects, reply.GetObjects()...)
+		pageToken = reply.GetNextPageToken()
+		if pageToken == "" {
+			return objects, nil
+		}
+		if _, dup := seen[pageToken]; dup {
+			return nil, &GatewayError{
+				Op:  "galaxy discover hierarchy",
+				Err: fmt.Errorf("repeated page token %q", pageToken),
+			}
+		}
+		seen[pageToken] = struct{}{}
 	}
-	return reply.GetObjects(), nil
 }
 
 // WatchDeployEventsRaw starts the generated WatchDeployEvents stream for callers
@@ -238,6 +276,206 @@ func (c *GalaxyClient) Close() error {
 	return c.conn.Close()
 }
 
+// LazyBrowseNode is one node in a lazy Galaxy hierarchy walk produced by
+// (*GalaxyClient).Browse. Children are not fetched until Expand is called.
+// The node is safe for concurrent use; concurrent Expand calls coalesce onto
+// a single in-flight RPC and do not block snapshot accessors.
+type LazyBrowseNode struct {
+	client          *GalaxyClient
+	object          *pb.GalaxyObject
+	hasChildrenHint bool
+	options         BrowseChildrenOptions
+
+	// expandLock gates inspection and mutation of expand-coordination state
+	// (expanding, expandDone, expandErr). It is held only briefly; the BrowseChildren
+	// RPC itself runs outside this lock so concurrent readers and waiters are not blocked.
+	expandLock sync.Mutex
+	expanding  bool
+	expandDone chan struct{}
+	expandErr  error
+
+	// mu protects the children snapshot and isExpanded flag for concurrent
+	// Children() / IsExpanded() readers.
+	mu         sync.RWMutex
+	children   []*LazyBrowseNode
+	isExpanded bool
+}
+
+// Object returns the underlying GalaxyObject describing this node.
+func (n *LazyBrowseNode) Object() *pb.GalaxyObject { return n.object }
+
+// HasChildrenHint reports the server-supplied hint on whether this node has
+// matching descendants under the current filter set.
+func (n *LazyBrowseNode) HasChildrenHint() bool { return n.hasChildrenHint }
+
+// Children returns a snapshot copy of the currently-loaded child nodes. Returns
+// an empty slice when Expand has not yet been called.
+func (n *LazyBrowseNode) Children() []*LazyBrowseNode {
+	n.mu.RLock()
+	defer n.mu.RUnlock()
+	out := make([]*LazyBrowseNode, len(n.children))
+	copy(out, n.children)
+	return out
+}
+
+// IsExpanded reports whether Expand has completed successfully on this node.
+func (n *LazyBrowseNode) IsExpanded() bool {
+	n.mu.RLock()
+	defer n.mu.RUnlock()
+	return n.isExpanded
+}
+
+// Expand fetches this node's direct children via BrowseChildren when they have
+// not yet been loaded. Subsequent calls after a successful Expand are a no-op
+// and do not issue another RPC.
+//
+// Expand is safe to call concurrently from multiple goroutines: callers that
+// arrive while an expansion is in flight wait on the active RPC and share its
+// result instead of issuing a second RPC. The RPC itself runs without holding
+// the snapshot mutex, so concurrent Children() and IsExpanded() callers are
+// not blocked for the duration of the network round trip.
+//
+// Failure semantics: a failed expansion surfaces the same error to every
+// in-flight waiter, but the node is left in its pre-call state (isExpanded =
+// false, no in-flight expansion). The next Expand call therefore retries with
+// a fresh RPC; failures are not sticky.
+func (n *LazyBrowseNode) Expand(ctx context.Context) error {
+	// Fast path: already expanded.
+	n.mu.RLock()
+	if n.isExpanded {
+		n.mu.RUnlock()
+		return nil
+	}
+	n.mu.RUnlock()
+
+	// Either start a new expansion or wait on an existing one.
+	n.expandLock.Lock()
+	n.mu.RLock()
+	alreadyExpanded := n.isExpanded
+	n.mu.RUnlock()
+	if alreadyExpanded {
+		n.expandLock.Unlock()
+		return nil
+	}
+	if n.expanding {
+		done := n.expandDone
+		n.expandLock.Unlock()
+		select {
+		case <-done:
+			n.expandLock.Lock()
+			err := n.expandErr
+			n.expandLock.Unlock()
+			return err
+		case <-ctx.Done():
+			return ctx.Err()
+		}
+	}
+	n.expanding = true
+	n.expandDone = make(chan struct{})
+	done := n.expandDone
+	n.expandLock.Unlock()
+
+	// Issue the RPC outside any lock so concurrent readers/waiters are not blocked.
+	parentID := n.object.GetGobjectId()
+	children, err := n.client.browseChildrenInner(ctx, &parentID, n.options)
+
+	if err == nil {
+		n.mu.Lock()
+		n.children = children
+		n.isExpanded = true
+		n.mu.Unlock()
+	}
+
+	// Publish result to waiters and clear the in-flight marker so a failed
+	// expansion can be retried by the next Expand call.
+	n.expandLock.Lock()
+	n.expandErr = err
+	n.expanding = false
+	close(done)
+	n.expandLock.Unlock()
+
+	return err
+}
+
+// Browse returns the root nodes of the Galaxy hierarchy. The returned nodes
+// have only their server-supplied hints populated; call Expand on each node to
+// fetch its direct children. When opts is nil the server defaults apply.
+func (c *GalaxyClient) Browse(ctx context.Context, opts *BrowseChildrenOptions) ([]*LazyBrowseNode, error) {
+	effective := BrowseChildrenOptions{}
+	if opts != nil {
+		effective = *opts
+	}
+	return c.browseChildrenInner(ctx, nil, effective)
+}
+
+// BrowseChildrenRaw issues a single BrowseChildren RPC and returns the raw
+// reply for callers that need direct page-token control. Transport-level
+// failures are wrapped in *GatewayError to match the rest of the client.
+func (c *GalaxyClient) BrowseChildrenRaw(ctx context.Context, req *pb.BrowseChildrenRequest) (*pb.BrowseChildrenReply, error) {
+	callCtx, cancel := c.callContext(ctx)
+	defer cancel()
+	reply, err := c.raw.BrowseChildren(callCtx, req)
+	if err != nil {
+		return nil, &GatewayError{Op: "galaxy browse children", Err: err}
+	}
+	return reply, nil
+}
+
+func (c *GalaxyClient) browseChildrenInner(
+	ctx context.Context,
+	parentGobjectID *int32,
+	opts BrowseChildrenOptions,
+) ([]*LazyBrowseNode, error) {
+	var nodes []*LazyBrowseNode
+	pageToken := ""
+	seen := map[string]struct{}{}
+	for {
+		req := &pb.BrowseChildrenRequest{
+			PageSize:              browseChildrenPageSize,
+			PageToken:             pageToken,
+			CategoryIds:           opts.CategoryIds,
+			TemplateChainContains: opts.TemplateChainContains,
+			TagNameGlob:           opts.TagNameGlob,
+			AlarmBearingOnly:      opts.AlarmBearingOnly,
+			HistorizedOnly:        opts.HistorizedOnly,
+		}
+		if parentGobjectID != nil {
+			req.Parent = &pb.BrowseChildrenRequest_ParentGobjectId{ParentGobjectId: *parentGobjectID}
+		}
+		if opts.IncludeAttributes != nil {
+			req.IncludeAttributes = opts.IncludeAttributes
+		}
+
+		reply, err := c.BrowseChildrenRaw(ctx, req)
+		if err != nil {
+			return nil, err
+		}
+
+		for i, child := range reply.GetChildren() {
+			hasChildren := reply.GetChildHasChildren()
+			hint := i < len(hasChildren) && hasChildren[i]
+			nodes = append(nodes, &LazyBrowseNode{
+				client:          c,
+				object:          child,
+				hasChildrenHint: hint,
+				options:         opts,
+			})
+		}
+
+		pageToken = reply.GetNextPageToken()
+		if pageToken == "" {
+			return nodes, nil
+		}
+		if _, dup := seen[pageToken]; dup {
+			return nil, &GatewayError{
+				Op:  "galaxy browse children",
+				Err: fmt.Errorf("repeated page token %q", pageToken),
+			}
+		}
+		seen[pageToken] = struct{}{}
+	}
+}
+
 func (c *GalaxyClient) callContext(ctx context.Context) (context.Context, context.CancelFunc) {
 	timeout := c.opts.CallTimeout
 	if timeout == 0 {

clients/go/mxgateway/galaxy_test.go

@@ -4,11 +4,14 @@ import (
 	"context"
 	"errors"
 	"net"
+	"sync"
 	"testing"
 	"time"
 
 	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
 	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
 	"google.golang.org/grpc/test/bufconn"
 	"google.golang.org/protobuf/types/known/timestamppb"
 )
@@ -55,8 +58,8 @@ func TestGalaxyGetLastDeployTimeReturnsTimestampWhenPresent(t *testing.T) {
 	want := time.Date(2026, 4, 28, 12, 34, 56, 0, time.UTC)
 	fake := &fakeGalaxyServer{
 		deployReply: &pb.GetLastDeployTimeReply{
-			Present:           true,
-			TimeOfLastDeploy:  timestamppb.New(want),
+			Present:          true,
+			TimeOfLastDeploy: timestamppb.New(want),
 		},
 	}
 	client, cleanup := newGalaxyBufconnClient(t, fake)
@@ -144,6 +147,47 @@ func TestGalaxyDiscoverHierarchyReturnsObjects(t *testing.T) {
 	}
 }
 
+func TestGalaxyDiscoverHierarchyPaginatesAcrossMultiplePages(t *testing.T) {
+	page1 := &pb.DiscoverHierarchyReply{
+		Objects: []*pb.GalaxyObject{
+			{GobjectId: 1, TagName: "A"},
+			{GobjectId: 2, TagName: "B"},
+		},
+		NextPageToken:    "page-2",
+		TotalObjectCount: 3,
+	}
+	page2 := &pb.DiscoverHierarchyReply{
+		Objects: []*pb.GalaxyObject{
+			{GobjectId: 3, TagName: "C"},
+		},
+		TotalObjectCount: 3,
+	}
+	fake := &fakeGalaxyServer{
+		discoverHierarchyReplies: []*pb.DiscoverHierarchyReply{page1, page2},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	objs, err := client.DiscoverHierarchy(context.Background())
+	if err != nil {
+		t.Fatalf("DiscoverHierarchy: %v", err)
+	}
+	if got, want := len(objs), 3; got != want {
+		t.Fatalf("len(objs) = %d, want %d", got, want)
+	}
+	if len(fake.discoverHierarchyCalls) != 2 {
+		t.Fatalf("expected 2 RPC calls, got %d", len(fake.discoverHierarchyCalls))
+	}
+	if fake.discoverHierarchyCalls[0].GetPageSize() != discoverHierarchyPageSize {
+		t.Fatalf("first call PageSize = %d, want %d",
+			fake.discoverHierarchyCalls[0].GetPageSize(), discoverHierarchyPageSize)
+	}
+	if fake.discoverHierarchyCalls[1].GetPageToken() != "page-2" {
+		t.Fatalf("second call page token = %q, want %q",
+			fake.discoverHierarchyCalls[1].GetPageToken(), "page-2")
+	}
+}
+
 func TestGalaxyDialReturnsGatewayErrorOnRpcFailure(t *testing.T) {
 	fake := &fakeGalaxyServer{failTest: true}
 	client, cleanup := newGalaxyBufconnClient(t, fake)
@@ -370,15 +414,20 @@ func newGalaxyBufconnClient(t *testing.T, fake *fakeGalaxyServer) (*GalaxyClient
 type fakeGalaxyServer struct {
 	pb.UnimplementedGalaxyRepositoryServer
 
-	testReply         *pb.TestConnectionReply
-	testAuth          string
-	failTest          bool
-	deployReply       *pb.GetLastDeployTimeReply
-	discoverReply     *pb.DiscoverHierarchyReply
-	watchEvents       []*pb.DeployEvent
-	watchRequest      *pb.WatchDeployEventsRequest
-	watchSendInterval time.Duration
-	watchHoldOpen     bool
+	testReply                *pb.TestConnectionReply
+	testAuth                 string
+	failTest                 bool
+	deployReply              *pb.GetLastDeployTimeReply
+	discoverReply            *pb.DiscoverHierarchyReply
+	discoverHierarchyCalls   []*pb.DiscoverHierarchyRequest
+	discoverHierarchyReplies []*pb.DiscoverHierarchyReply
+	watchEvents              []*pb.DeployEvent
+	watchRequest             *pb.WatchDeployEventsRequest
+	watchSendInterval        time.Duration
+	watchHoldOpen            bool
+	browseChildrenCalls      []*pb.BrowseChildrenRequest
+	browseChildrenReplies    []*pb.BrowseChildrenReply
+	browseChildrenError      error
 }
 
 func (s *fakeGalaxyServer) TestConnection(ctx context.Context, req *pb.TestConnectionRequest) (*pb.TestConnectionReply, error) {
@@ -400,6 +449,12 @@ func (s *fakeGalaxyServer) GetLastDeployTime(ctx context.Context, req *pb.GetLas
 }
 
 func (s *fakeGalaxyServer) DiscoverHierarchy(ctx context.Context, req *pb.DiscoverHierarchyRequest) (*pb.DiscoverHierarchyReply, error) {
+	s.discoverHierarchyCalls = append(s.discoverHierarchyCalls, req)
+	if len(s.discoverHierarchyReplies) > 0 {
+		reply := s.discoverHierarchyReplies[0]
+		s.discoverHierarchyReplies = s.discoverHierarchyReplies[1:]
+		return reply, nil
+	}
 	if s.discoverReply != nil {
 		return s.discoverReply, nil
 	}
@@ -425,3 +480,385 @@ func (s *fakeGalaxyServer) WatchDeployEvents(req *pb.WatchDeployEventsRequest, s
 	}
 	return nil
 }
+
+func (s *fakeGalaxyServer) BrowseChildren(ctx context.Context, req *pb.BrowseChildrenRequest) (*pb.BrowseChildrenReply, error) {
+	s.browseChildrenCalls = append(s.browseChildrenCalls, req)
+	if s.browseChildrenError != nil {
+		err := s.browseChildrenError
+		s.browseChildrenError = nil
+		return nil, err
+	}
+	if len(s.browseChildrenReplies) == 0 {
+		return &pb.BrowseChildrenReply{}, nil
+	}
+	reply := s.browseChildrenReplies[0]
+	s.browseChildrenReplies = s.browseChildrenReplies[1:]
+	return reply, nil
+}
+
+func obj(id int32, tag string, isArea bool) *pb.GalaxyObject {
+	return &pb.GalaxyObject{
+		GobjectId:  id,
+		TagName:    tag,
+		BrowseName: tag,
+		IsArea:     isArea,
+	}
+}
+
+func buildBrowseReply(children []*pb.GalaxyObject, hasChildren []bool, seq uint64) *pb.BrowseChildrenReply {
+	return &pb.BrowseChildrenReply{
+		TotalChildCount:  int32(len(children)),
+		CacheSequence:    seq,
+		Children:         children,
+		ChildHasChildren: hasChildren,
+	}
+}
+
+func TestGalaxyBrowseNoParentReturnsRoots(t *testing.T) {
+	fake := &fakeGalaxyServer{
+		browseChildrenReplies: []*pb.BrowseChildrenReply{
+			buildBrowseReply(
+				[]*pb.GalaxyObject{obj(1, "Plant", true), obj(99, "Other", false)},
+				[]bool{true, false},
+				7,
+			),
+		},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	roots, err := client.Browse(context.Background(), nil)
+	if err != nil {
+		t.Fatalf("Browse: %v", err)
+	}
+	if got, want := len(roots), 2; got != want {
+		t.Fatalf("len(roots) = %d, want %d", got, want)
+	}
+	if roots[0].Object().GetTagName() != "Plant" {
+		t.Fatalf("roots[0].TagName = %q", roots[0].Object().GetTagName())
+	}
+	if !roots[0].HasChildrenHint() {
+		t.Fatal("roots[0].HasChildrenHint = false, want true")
+	}
+	if roots[0].IsExpanded() {
+		t.Fatal("roots[0].IsExpanded = true, want false")
+	}
+	if roots[1].HasChildrenHint() {
+		t.Fatal("roots[1].HasChildrenHint = true, want false")
+	}
+	if len(fake.browseChildrenCalls) != 1 {
+		t.Fatalf("BrowseChildren calls = %d, want 1", len(fake.browseChildrenCalls))
+	}
+	if fake.browseChildrenCalls[0].GetParent() != nil {
+		t.Fatalf("root browse should not set Parent oneof, got %T", fake.browseChildrenCalls[0].GetParent())
+	}
+}
+
+func TestGalaxyBrowseExpandPopulatesChildrenAndMarksExpanded(t *testing.T) {
+	fake := &fakeGalaxyServer{
+		browseChildrenReplies: []*pb.BrowseChildrenReply{
+			buildBrowseReply(
+				[]*pb.GalaxyObject{obj(1, "Plant", true)},
+				[]bool{true},
+				1,
+			),
+			buildBrowseReply(
+				[]*pb.GalaxyObject{obj(10, "Area1", true), obj(11, "Tank1", false)},
+				[]bool{true, false},
+				1,
+			),
+		},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	roots, err := client.Browse(context.Background(), nil)
+	if err != nil {
+		t.Fatalf("Browse: %v", err)
+	}
+	if len(roots) != 1 {
+		t.Fatalf("len(roots) = %d, want 1", len(roots))
+	}
+	plant := roots[0]
+	if plant.IsExpanded() {
+		t.Fatal("plant.IsExpanded = true before Expand, want false")
+	}
+	if err := plant.Expand(context.Background()); err != nil {
+		t.Fatalf("Expand: %v", err)
+	}
+	if !plant.IsExpanded() {
+		t.Fatal("plant.IsExpanded = false after Expand, want true")
+	}
+	children := plant.Children()
+	if len(children) != 2 {
+		t.Fatalf("len(children) = %d, want 2", len(children))
+	}
+	if children[0].Object().GetTagName() != "Area1" {
+		t.Fatalf("children[0].TagName = %q, want Area1", children[0].Object().GetTagName())
+	}
+	if !children[0].HasChildrenHint() {
+		t.Fatal("children[0].HasChildrenHint = false, want true")
+	}
+	if children[1].HasChildrenHint() {
+		t.Fatal("children[1].HasChildrenHint = true, want false")
+	}
+	if len(fake.browseChildrenCalls) != 2 {
+		t.Fatalf("BrowseChildren calls = %d, want 2", len(fake.browseChildrenCalls))
+	}
+	parent := fake.browseChildrenCalls[1].GetParent()
+	parentGobj, ok := parent.(*pb.BrowseChildrenRequest_ParentGobjectId)
+	if !ok {
+		t.Fatalf("Parent oneof = %T, want *BrowseChildrenRequest_ParentGobjectId", parent)
+	}
+	if parentGobj.ParentGobjectId != 1 {
+		t.Fatalf("ParentGobjectId = %d, want 1", parentGobj.ParentGobjectId)
+	}
+}
+
+func TestGalaxyBrowseExpandIdempotentNoSecondRpc(t *testing.T) {
+	fake := &fakeGalaxyServer{
+		browseChildrenReplies: []*pb.BrowseChildrenReply{
+			buildBrowseReply(
+				[]*pb.GalaxyObject{obj(1, "Plant", true)},
+				[]bool{true},
+				1,
+			),
+			buildBrowseReply(
+				[]*pb.GalaxyObject{obj(10, "Area1", true)},
+				[]bool{false},
+				1,
+			),
+		},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	roots, err := client.Browse(context.Background(), nil)
+	if err != nil {
+		t.Fatalf("Browse: %v", err)
+	}
+	plant := roots[0]
+	if err := plant.Expand(context.Background()); err != nil {
+		t.Fatalf("Expand #1: %v", err)
+	}
+	callsAfterFirst := len(fake.browseChildrenCalls)
+	if callsAfterFirst != 2 {
+		t.Fatalf("BrowseChildren calls after first Expand = %d, want 2", callsAfterFirst)
+	}
+	if err := plant.Expand(context.Background()); err != nil {
+		t.Fatalf("Expand #2: %v", err)
+	}
+	if got := len(fake.browseChildrenCalls); got != callsAfterFirst {
+		t.Fatalf("BrowseChildren calls after second Expand = %d, want %d (no extra RPC)", got, callsAfterFirst)
+	}
+}
+
+func TestGalaxyBrowseExpandUnknownParentReturnsNotFoundError(t *testing.T) {
+	fake := &fakeGalaxyServer{
+		browseChildrenReplies: []*pb.BrowseChildrenReply{
+			buildBrowseReply(
+				[]*pb.GalaxyObject{obj(1, "Plant", true)},
+				[]bool{true},
+				1,
+			),
+		},
+		browseChildrenError: status.Error(codes.NotFound, "parent not found"),
+	}
+	// The first Browse() consumes the first reply; the next call (Expand) will
+	// then hit browseChildrenError. We need the error to fire only on the second
+	// call, so seed the reply first and let the call sequence consume them in
+	// order. Because BrowseChildren in the fake consumes browseChildrenError
+	// before falling through to replies, swap the strategy: keep the root reply
+	// but have BrowseChildren return the error on the second call. We do this by
+	// emptying the reply list after the first Browse.
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	// First call returns the error (because browseChildrenError takes precedence).
+	// To avoid that, clear it for the root call by performing a manual setup: we
+	// pre-stage replies first, then set the error after the first call. Easiest:
+	// pre-Browse() with error=nil, then set error before Expand.
+	fake.browseChildrenError = nil
+	roots, err := client.Browse(context.Background(), nil)
+	if err != nil {
+		t.Fatalf("Browse: %v", err)
+	}
+	if len(roots) != 1 {
+		t.Fatalf("len(roots) = %d, want 1", len(roots))
+	}
+	fake.browseChildrenError = status.Error(codes.NotFound, "parent not found")
+
+	err = roots[0].Expand(context.Background())
+	if err == nil {
+		t.Fatal("Expand: error = nil, want NotFound")
+	}
+	if status.Code(err) != codes.NotFound {
+		t.Fatalf("status.Code = %s, want NotFound", status.Code(err))
+	}
+	if roots[0].IsExpanded() {
+		t.Fatal("roots[0].IsExpanded = true after failed Expand, want false")
+	}
+}
+
+func TestGalaxyBrowseExpandMultiPageGathersAllPages(t *testing.T) {
+	firstPage := buildBrowseReply(
+		[]*pb.GalaxyObject{obj(1, "Plant", true)},
+		[]bool{true},
+		7,
+	)
+
+	pageA := buildBrowseReply(
+		[]*pb.GalaxyObject{obj(10, "Child1", false), obj(11, "Child2", false)},
+		[]bool{false, false},
+		7,
+	)
+	pageA.NextPageToken = "7:abc:2"
+	pageB := buildBrowseReply(
+		[]*pb.GalaxyObject{obj(12, "Child3", false)},
+		[]bool{false},
+		7,
+	)
+
+	fake := &fakeGalaxyServer{
+		browseChildrenReplies: []*pb.BrowseChildrenReply{firstPage, pageA, pageB},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	roots, err := client.Browse(context.Background(), nil)
+	if err != nil {
+		t.Fatalf("Browse: %v", err)
+	}
+	if err := roots[0].Expand(context.Background()); err != nil {
+		t.Fatalf("Expand: %v", err)
+	}
+	children := roots[0].Children()
+	if len(children) != 3 {
+		t.Fatalf("len(children) = %d, want 3", len(children))
+	}
+	if len(fake.browseChildrenCalls) != 3 {
+		t.Fatalf("BrowseChildren calls = %d, want 3", len(fake.browseChildrenCalls))
+	}
+	if got := fake.browseChildrenCalls[2].GetPageToken(); got != "7:abc:2" {
+		t.Fatalf("third call PageToken = %q, want %q", got, "7:abc:2")
+	}
+}
+
+func TestGalaxyBrowseWithFilterForwardsToRequest(t *testing.T) {
+	fake := &fakeGalaxyServer{
+		browseChildrenReplies: []*pb.BrowseChildrenReply{
+			buildBrowseReply(nil, nil, 1),
+		},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	include := true
+	opts := &BrowseChildrenOptions{
+		CategoryIds:           []int32{7, 9},
+		TemplateChainContains: []string{"$AppObject"},
+		TagNameGlob:           "Tank*",
+		IncludeAttributes:     &include,
+		AlarmBearingOnly:      true,
+		HistorizedOnly:        true,
+	}
+	if _, err := client.Browse(context.Background(), opts); err != nil {
+		t.Fatalf("Browse: %v", err)
+	}
+	if len(fake.browseChildrenCalls) != 1 {
+		t.Fatalf("BrowseChildren calls = %d, want 1", len(fake.browseChildrenCalls))
+	}
+	got := fake.browseChildrenCalls[0]
+	if want := []int32{7, 9}; len(got.GetCategoryIds()) != 2 || got.GetCategoryIds()[0] != want[0] || got.GetCategoryIds()[1] != want[1] {
+		t.Fatalf("CategoryIds = %v, want %v", got.GetCategoryIds(), want)
+	}
+	if want := []string{"$AppObject"}; len(got.GetTemplateChainContains()) != 1 || got.GetTemplateChainContains()[0] != want[0] {
+		t.Fatalf("TemplateChainContains = %v, want %v", got.GetTemplateChainContains(), want)
+	}
+	if got.GetTagNameGlob() != "Tank*" {
+		t.Fatalf("TagNameGlob = %q, want %q", got.GetTagNameGlob(), "Tank*")
+	}
+	if !got.GetIncludeAttributes() {
+		t.Fatal("IncludeAttributes = false, want true")
+	}
+	if !got.GetAlarmBearingOnly() {
+		t.Fatal("AlarmBearingOnly = false, want true")
+	}
+	if !got.GetHistorizedOnly() {
+		t.Fatal("HistorizedOnly = false, want true")
+	}
+}
+
+func TestGalaxyBrowseExpandConcurrentCallersOnlyFireOneRpc(t *testing.T) {
+	fake := &fakeGalaxyServer{
+		browseChildrenReplies: []*pb.BrowseChildrenReply{
+			// roots
+			buildBrowseReply([]*pb.GalaxyObject{obj(1, "Plant", true)}, []bool{true}, 7),
+			// one expand: one child
+			buildBrowseReply([]*pb.GalaxyObject{obj(2, "Mixer", false)}, []bool{false}, 7),
+		},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	ctx := context.Background()
+	roots, err := client.Browse(ctx, nil)
+	if err != nil {
+		t.Fatalf("Browse: %v", err)
+	}
+
+	var wg sync.WaitGroup
+	errs := make(chan error, 10)
+	for i := 0; i < 10; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			errs <- roots[0].Expand(ctx)
+		}()
+	}
+	wg.Wait()
+	close(errs)
+	for err := range errs {
+		if err != nil {
+			t.Fatalf("concurrent Expand: %v", err)
+		}
+	}
+
+	if !roots[0].IsExpanded() {
+		t.Fatal("IsExpanded() = false after 10 concurrent expands")
+	}
+	if got, want := len(roots[0].Children()), 1; got != want {
+		t.Fatalf("len(children) = %d, want %d", got, want)
+	}
+	// 1 roots fetch + exactly 1 expand fetch.
+	if got, want := len(fake.browseChildrenCalls), 2; got != want {
+		t.Fatalf("RPC count = %d, want %d", got, want)
+	}
+}
+
+func TestGalaxyBrowseChildrenRejectsRepeatedPageToken(t *testing.T) {
+	// Build a reply that carries a non-empty NextPageToken so browseChildrenInner
+	// will request a second page. Queue the same reply twice so the second response
+	// returns the same page token, triggering the duplicate-token guard.
+	page := buildBrowseReply(
+		[]*pb.GalaxyObject{obj(1, "Plant", true)},
+		[]bool{true},
+		1,
+	)
+	page.NextPageToken = "1:abc:1"
+
+	fake := &fakeGalaxyServer{
+		browseChildrenReplies: []*pb.BrowseChildrenReply{page, page},
+	}
+	client, cleanup := newGalaxyBufconnClient(t, fake)
+	defer cleanup()
+
+	_, err := client.Browse(context.Background(), nil)
+	if err == nil {
+		t.Fatal("Browse: error = nil, want repeated-page-token error")
+	}
+	var gwErr *GatewayError
+	if !errors.As(err, &gwErr) {
+		t.Fatalf("error type = %T, want *GatewayError; err = %v", err, err)
+	}
+}

clients/go/mxgateway/options.go

@@ -34,6 +34,32 @@ type Options struct {
 	TransportCredentials credentials.TransportCredentials
 	// DialOptions are appended to the gRPC dial options after the defaults.
 	DialOptions []grpc.DialOption
+	// RequireCertificateValidation forces TLS certificate verification even when
+	// no CACertFile is pinned. Default false: the gateway's self-signed cert is
+	// accepted without verification (internal-tool posture).
+	RequireCertificateValidation bool
+}
+
+// BrowseChildrenOptions configures lazy Galaxy hierarchy walks performed by
+// (*GalaxyClient).Browse and (*LazyBrowseNode).Expand. All fields are optional;
+// the zero value matches the dashboard default (no filters, all attributes per
+// the server default).
+type BrowseChildrenOptions struct {
+	// CategoryIds restricts results to the listed Galaxy category ids when set.
+	CategoryIds []int32
+	// TemplateChainContains restricts results to objects whose template chain
+	// contains any of the listed template tag names.
+	TemplateChainContains []string
+	// TagNameGlob restricts results to objects whose tag name matches the glob
+	// pattern when non-empty.
+	TagNameGlob string
+	// IncludeAttributes overrides the server default for attribute inclusion when
+	// non-nil. The pointer form mirrors the proto's optional field.
+	IncludeAttributes *bool
+	// AlarmBearingOnly limits results to alarm-bearing objects when true.
+	AlarmBearingOnly bool
+	// HistorizedOnly limits results to historized objects when true.
+	HistorizedOnly bool
 }
 
 // RedactedAPIKey returns a display-safe representation of the configured API

clients/go/mxgateway/session.go

@@ -7,7 +7,9 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"sort"
 	"sync"
+	"time"
 
 	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
 	"google.golang.org/grpc/codes"
@@ -387,6 +389,173 @@ func (s *Session) UnsubscribeBulk(ctx context.Context, serverHandle int32, itemH
 	return reply.GetUnsubscribeBulk().GetResults(), nil
 }
 
+// WriteBulk invokes MXAccess Write sequentially for each entry inside one gateway command.
+// Per-entry failures appear as BulkWriteResult entries with WasSuccessful=false; the call
+// never returns an error for per-entry MXAccess failures (it returns an error only for
+// protocol-level failures or transport errors).
+//
+// A non-nil but empty entries slice is treated as a no-op and returns an empty result
+// without a wire round-trip; pass nil to surface a clear "entries are required" error.
+func (s *Session) WriteBulk(ctx context.Context, serverHandle int32, entries []*WriteBulkEntry) ([]*BulkWriteResult, error) {
+	if entries == nil {
+		return nil, errors.New("mxgateway: write bulk entries are required")
+	}
+	if err := ensureBulkSize("write bulk entries", len(entries)); err != nil {
+		return nil, err
+	}
+	if len(entries) == 0 {
+		return []*BulkWriteResult{}, nil
+	}
+	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_WRITE_BULK,
+		Payload: &pb.MxCommand_WriteBulk{
+			WriteBulk: &pb.WriteBulkCommand{
+				ServerHandle: serverHandle,
+				Entries:      entries,
+			},
+		},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return reply.GetWriteBulk().GetResults(), nil
+}
+
+// Write2Bulk invokes MXAccess Write2 (timestamped) for each entry inside one gateway command.
+//
+// A non-nil but empty entries slice is treated as a no-op and returns an empty result
+// without a wire round-trip; pass nil to surface a clear "entries are required" error.
+func (s *Session) Write2Bulk(ctx context.Context, serverHandle int32, entries []*Write2BulkEntry) ([]*BulkWriteResult, error) {
+	if entries == nil {
+		return nil, errors.New("mxgateway: write2 bulk entries are required")
+	}
+	if err := ensureBulkSize("write2 bulk entries", len(entries)); err != nil {
+		return nil, err
+	}
+	if len(entries) == 0 {
+		return []*BulkWriteResult{}, nil
+	}
+	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_WRITE2_BULK,
+		Payload: &pb.MxCommand_Write2Bulk{
+			Write2Bulk: &pb.Write2BulkCommand{
+				ServerHandle: serverHandle,
+				Entries:      entries,
+			},
+		},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return reply.GetWrite2Bulk().GetResults(), nil
+}
+
+// WriteSecuredBulk invokes MXAccess WriteSecured for each entry. Credential-sensitive
+// values must not be logged by callers; mirrors the single-item WriteSecured contract.
+//
+// A non-nil but empty entries slice is treated as a no-op and returns an empty result
+// without a wire round-trip; pass nil to surface a clear "entries are required" error.
+func (s *Session) WriteSecuredBulk(ctx context.Context, serverHandle int32, entries []*WriteSecuredBulkEntry) ([]*BulkWriteResult, error) {
+	if entries == nil {
+		return nil, errors.New("mxgateway: write-secured bulk entries are required")
+	}
+	if err := ensureBulkSize("write-secured bulk entries", len(entries)); err != nil {
+		return nil, err
+	}
+	if len(entries) == 0 {
+		return []*BulkWriteResult{}, nil
+	}
+	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_WRITE_SECURED_BULK,
+		Payload: &pb.MxCommand_WriteSecuredBulk{
+			WriteSecuredBulk: &pb.WriteSecuredBulkCommand{
+				ServerHandle: serverHandle,
+				Entries:      entries,
+			},
+		},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return reply.GetWriteSecuredBulk().GetResults(), nil
+}
+
+// WriteSecured2Bulk invokes MXAccess WriteSecured2 (timestamped) for each entry.
+//
+// A non-nil but empty entries slice is treated as a no-op and returns an empty result
+// without a wire round-trip; pass nil to surface a clear "entries are required" error.
+func (s *Session) WriteSecured2Bulk(ctx context.Context, serverHandle int32, entries []*WriteSecured2BulkEntry) ([]*BulkWriteResult, error) {
+	if entries == nil {
+		return nil, errors.New("mxgateway: write-secured2 bulk entries are required")
+	}
+	if err := ensureBulkSize("write-secured2 bulk entries", len(entries)); err != nil {
+		return nil, err
+	}
+	if len(entries) == 0 {
+		return []*BulkWriteResult{}, nil
+	}
+	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_WRITE_SECURED2_BULK,
+		Payload: &pb.MxCommand_WriteSecured2Bulk{
+			WriteSecured2Bulk: &pb.WriteSecured2BulkCommand{
+				ServerHandle: serverHandle,
+				Entries:      entries,
+			},
+		},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return reply.GetWriteSecured2Bulk().GetResults(), nil
+}
+
+// ReadBulk snapshots the current value of each requested tag.
+//
+// MXAccess COM has no synchronous Read; the worker satisfies this by returning the
+// most recent cached OnDataChange value when the tag is already advised (WasCached=true),
+// or by taking a full AddItem + Advise + wait + UnAdvise + RemoveItem snapshot lifecycle
+// otherwise. timeout bounds the wait per tag in the snapshot case; pass zero to use the
+// worker default. Per-tag failures (timeout, invalid tag) appear as BulkReadResult entries
+// with WasSuccessful=false; the call never returns an error for per-tag MXAccess failures.
+//
+// A non-nil but empty tagAddresses slice is treated as a no-op and returns an empty
+// result without a wire round-trip; pass nil to surface a clear "tag addresses are
+// required" error.
+func (s *Session) ReadBulk(ctx context.Context, serverHandle int32, tagAddresses []string, timeout time.Duration) ([]*BulkReadResult, error) {
+	if tagAddresses == nil {
+		return nil, errors.New("mxgateway: tag addresses are required")
+	}
+	if err := ensureBulkSize("tag addresses", len(tagAddresses)); err != nil {
+		return nil, err
+	}
+	if len(tagAddresses) == 0 {
+		return []*BulkReadResult{}, nil
+	}
+	var timeoutMs uint32
+	if timeout > 0 {
+		ms := timeout.Milliseconds()
+		if ms > int64(^uint32(0)) {
+			timeoutMs = ^uint32(0)
+		} else {
+			timeoutMs = uint32(ms)
+		}
+	}
+	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_READ_BULK,
+		Payload: &pb.MxCommand_ReadBulk{
+			ReadBulk: &pb.ReadBulkCommand{
+				ServerHandle: serverHandle,
+				TagAddresses: tagAddresses,
+				TimeoutMs:    timeoutMs,
+			},
+		},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return reply.GetReadBulk().GetResults(), nil
+}
+
 // Write invokes MXAccess Write.
 func (s *Session) Write(ctx context.Context, serverHandle, itemHandle int32, value *MxValue, userID int32) error {
 	_, err := s.WriteRaw(ctx, serverHandle, itemHandle, value, userID)
@@ -412,6 +581,97 @@ func (s *Session) WriteRaw(ctx context.Context, serverHandle, itemHandle int32,
 	})
 }
 
+// WriteArrayElements writes a sparse, default-filled array: only the given
+// elements (index → scalar value) are set; every unmentioned index up to
+// totalLength is written as the element type's default (false / 0 / "" / Unix
+// epoch for time). The gateway expands the sparse representation into a full
+// array write before forwarding to MXAccess — this is a RESET of unmentioned
+// indices, not a preserve. Neither RESET semantics nor the original array
+// content are retained.
+//
+// elementDataType must be a scalar MXAccess type (Boolean, Integer, Float,
+// Double, String, or Time). totalLength must be at least as large as the
+// highest index in elements plus one.
+func (s *Session) WriteArrayElements(
+	ctx context.Context,
+	serverHandle, itemHandle int32,
+	elementDataType MxDataType,
+	totalLength uint32,
+	elements map[uint32]*MxValue,
+	userID int32,
+) error {
+	return s.Write(ctx, serverHandle, itemHandle, buildSparseArrayValue(elementDataType, totalLength, elements), userID)
+}
+
+// buildSparseArrayValue constructs the MxValue carrying an MxSparseArray oneof
+// arm from a map of index → scalar MxValue. Keys are visited in ascending
+// order so the produced slice is deterministic (important for test assertions).
+func buildSparseArrayValue(elementDataType MxDataType, totalLength uint32, elements map[uint32]*MxValue) *MxValue {
+	indices := make([]uint32, 0, len(elements))
+	for idx := range elements {
+		indices = append(indices, idx)
+	}
+	sort.Slice(indices, func(i, j int) bool { return indices[i] < indices[j] })
+
+	sparseElements := make([]*MxSparseElement, 0, len(elements))
+	for _, idx := range indices {
+		sparseElements = append(sparseElements, &MxSparseElement{
+			Index: idx,
+			Value: elements[idx],
+		})
+	}
+
+	return &MxValue{
+		Kind: &pb.MxValue_SparseArrayValue{
+			SparseArrayValue: &MxSparseArray{
+				ElementDataType: elementDataType,
+				TotalLength:     totalLength,
+				Elements:        sparseElements,
+			},
+		},
+	}
+}
+
+// PingRaw sends a diagnostic PING command and returns the raw reply.
+// The message is echoed back by the gateway in the reply's DiagnosticMessage field.
+func (s *Session) PingRaw(ctx context.Context, message string) (*MxCommandReply, error) {
+	return s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_PING,
+		Payload: &pb.MxCommand_Ping{
+			Ping: &pb.PingCommand{Message: message},
+		},
+	})
+}
+
+// Write2 invokes MXAccess Write2 (timestamped single-item write).
+func (s *Session) Write2(ctx context.Context, serverHandle, itemHandle int32, value, timestampValue *MxValue, userID int32) error {
+	_, err := s.Write2Raw(ctx, serverHandle, itemHandle, value, timestampValue, userID)
+	return err
+}
+
+// Write2Raw invokes MXAccess Write2 (timestamped single-item write) and returns the raw reply.
+func (s *Session) Write2Raw(ctx context.Context, serverHandle, itemHandle int32, value, timestampValue *MxValue, userID int32) (*MxCommandReply, error) {
+	if value == nil {
+		return nil, errors.New("mxgateway: write2 value is required")
+	}
+	if timestampValue == nil {
+		return nil, errors.New("mxgateway: write2 timestamp value is required")
+	}
+
+	return s.invokeCommand(ctx, &pb.MxCommand{
+		Kind: pb.MxCommandKind_MX_COMMAND_KIND_WRITE2,
+		Payload: &pb.MxCommand_Write2{
+			Write2: &pb.Write2Command{
+				ServerHandle:   serverHandle,
+				ItemHandle:     itemHandle,
+				Value:          value,
+				TimestampValue: timestampValue,
+				UserId:         userID,
+			},
+		},
+	})
+}
+
 // Events streams ordered session events until the server ends the stream,
 // context cancellation stops Recv, or a terminal error is sent.
 func (s *Session) Events(ctx context.Context) (<-chan EventResult, error) {

clients/go/mxgateway/types.go

@@ -36,6 +36,13 @@ type (
 	Value = pb.MxValue
 	// MxArray is the protobuf representation of an MXAccess array value.
 	MxArray = pb.MxArray
+	// MxSparseArray is the write-only protobuf type for default-fill partial
+	// array writes. The gateway expands it to a full array before forwarding
+	// to MXAccess: unmentioned indices receive the element type's default value
+	// (boolean false, integer 0, float 0.0, string "", time = Unix epoch).
+	MxSparseArray = pb.MxSparseArray
+	// MxSparseElement is one index/value pair inside an MxSparseArray.
+	MxSparseElement = pb.MxSparseElement
 	// MxStatusProxy mirrors the MXAccess MXSTATUS_PROXY structure.
 	MxStatusProxy = pb.MxStatusProxy
 	// ProtocolStatus is the gateway-level status carried on every reply.
@@ -70,6 +77,32 @@ type (
 	WriteCommand = pb.WriteCommand
 	// Write2Command is the payload of an MXAccess Write2 command.
 	Write2Command = pb.Write2Command
+	// WriteBulkCommand is the payload of a bulk Write command.
+	WriteBulkCommand = pb.WriteBulkCommand
+	// WriteBulkEntry is one entry inside a WriteBulkCommand.
+	WriteBulkEntry = pb.WriteBulkEntry
+	// Write2BulkCommand is the payload of a bulk Write2 (timestamped) command.
+	Write2BulkCommand = pb.Write2BulkCommand
+	// Write2BulkEntry is one entry inside a Write2BulkCommand.
+	Write2BulkEntry = pb.Write2BulkEntry
+	// WriteSecuredBulkCommand is the payload of a bulk WriteSecured command.
+	WriteSecuredBulkCommand = pb.WriteSecuredBulkCommand
+	// WriteSecuredBulkEntry is one entry inside a WriteSecuredBulkCommand.
+	WriteSecuredBulkEntry = pb.WriteSecuredBulkEntry
+	// WriteSecured2BulkCommand is the payload of a bulk WriteSecured2 (timestamped) command.
+	WriteSecured2BulkCommand = pb.WriteSecured2BulkCommand
+	// WriteSecured2BulkEntry is one entry inside a WriteSecured2BulkCommand.
+	WriteSecured2BulkEntry = pb.WriteSecured2BulkEntry
+	// ReadBulkCommand is the payload of a bulk Read snapshot command.
+	ReadBulkCommand = pb.ReadBulkCommand
+	// BulkWriteReply aggregates BulkWriteResult entries for a bulk write command.
+	BulkWriteReply = pb.BulkWriteReply
+	// BulkWriteResult is one entry in a bulk write reply list.
+	BulkWriteResult = pb.BulkWriteResult
+	// BulkReadReply aggregates BulkReadResult entries for a bulk read command.
+	BulkReadReply = pb.BulkReadReply
+	// BulkReadResult is one entry in a bulk read reply list.
+	BulkReadResult = pb.BulkReadResult
 	// RegisterReply carries the ServerHandle returned by Register.
 	RegisterReply = pb.RegisterReply
 	// AddItemReply carries the ItemHandle returned by AddItem.
@@ -86,6 +119,11 @@ type (
 	AcknowledgeAlarmReply = pb.AcknowledgeAlarmReply
 	// QueryActiveAlarmsRequest is the gateway QueryActiveAlarms request message.
 	QueryActiveAlarmsRequest = pb.QueryActiveAlarmsRequest
+	// StreamAlarmsRequest is the gateway StreamAlarms request message.
+	StreamAlarmsRequest = pb.StreamAlarmsRequest
+	// AlarmFeedMessage is one message on the StreamAlarms feed — an
+	// active-alarm snapshot row, a snapshot-complete sentinel, or a transition.
+	AlarmFeedMessage = pb.AlarmFeedMessage
 	// ActiveAlarmSnapshot is one row in a ConditionRefresh stream.
 	ActiveAlarmSnapshot = pb.ActiveAlarmSnapshot
 	// OnAlarmTransitionEvent is the body carried by alarm-transition MxEvents.
@@ -104,6 +142,10 @@ type AlarmConditionState = pb.AlarmConditionState
 // QueryActiveAlarms RPC.
 type QueryActiveAlarmsClient = pb.MxAccessGateway_QueryActiveAlarmsClient
 
+// StreamAlarmsClient is the generated server-streaming client for the
+// StreamAlarms RPC.
+type StreamAlarmsClient = pb.MxAccessGateway_StreamAlarmsClient
+
 // Enumerations from the generated contract re-exported for client callers.
 type (
 	// MxCommandKind discriminates which MXAccess command an MxCommand carries.

clients/java/JavaClientDesign.md

@@ -112,6 +112,23 @@ Support:
 - custom CA certificate file,
 - server name override for test environments.
 
+### Trust posture
+
+The gateway can serve a self-signed certificate it generates itself (it has no
+PKI). To make that usable, TLS is **lenient by default**: when the channel is not
+plaintext and no `caCertificatePath` is set, the client builds
+`GrpcSslContexts.forClient().trustManager(InsecureTrustManagerFactory.INSTANCE)`
+(grpc-netty-shaded), so the gateway's self-signed certificate is accepted without
+verification.
+
+To verify the gateway instead:
+
+- set `caCertificatePath` to pin a CA (full verification against that root), or
+- set `requireCertificateValidation` to `true` to verify against the JVM trust
+  store without pinning.
+
+Pinning a CA always wins over the lenient default.
+
 ## Streaming
 
 Support both:

clients/java/README.md

@@ -57,6 +57,16 @@ try (MxGatewayClient client = MxGatewayClient.connect(options);
 }
 ```
 
+The gateway can auto-generate its own self-signed certificate (it has no PKI), so
+the client is **lenient by default**: a TLS connection (`plaintext(false)`) with
+no `caCertificatePath` accepts whatever certificate the gateway presents (via
+grpc-netty-shaded's `InsecureTrustManagerFactory`). To verify instead, set
+`caCertificatePath` to pin a CA, or set `requireCertificateValidation(true)` to
+verify against the JVM trust store without pinning. Use `serverNameOverride` /
+`--server-name-override` when the dialed host differs from the certificate SAN.
+See
+[Gateway Configuration](../../docs/GatewayConfiguration.md#automatic-self-signed-certificate).
+
 Use `rawBlockingStub`, `rawFutureStub`, `rawAsyncStub`, `openSessionRaw`,
 `closeSessionRaw`, `invoke`, and raw session helper methods when tests need the
 underlying protobuf messages. `MxGatewayCommandException` and
@@ -68,6 +78,76 @@ cancels the underlying gRPC stream. Canceling or timing out a Java client call
 only stops the client from waiting; it does not abort an in-flight MXAccess COM
 call on the worker STA.
 
+For alarms, `MxGatewayClient` exposes `queryActiveAlarms` (one-shot snapshot),
+`streamAlarms` (returns an `MxGatewayAlarmFeedSubscription` whose iterator
+yields alarm-feed messages from the gateway's central monitor), and
+`acknowledgeAlarm` (ack by full alarm reference with an optional comment and
+ack target). Close the subscription to cancel the underlying gRPC stream.
+
+## Write Semantics And Common Pitfalls
+
+These are MXAccess parity behaviors that surprise new callers. The gateway
+forwards them unchanged — it does not paper over them.
+
+### Attributing a write to a user without `authenticateUser`
+
+MXAccess only stamps a plain `write`/`write2` with a Galaxy user id when the
+item carries an active *supervisory* advise. If you are **not** using the
+verified/secured path (`authenticateUser` → `writeSecured`/`writeSecured2`) but
+still need the write attributed to a user id, you must first advise the item
+supervisory and then pass that user id on the write. Without the supervisory
+advise the `userId` on a plain write is ignored.
+
+The session exposes `advise`/`unAdvise` but not supervisory advise, so send it
+through the generic command channel:
+
+```java
+session.invokeCommand(MxCommand.newBuilder()
+        .setKind(MxCommandKind.MX_COMMAND_KIND_ADVISE_SUPERVISORY)
+        .setAdviseSupervisory(AdviseSupervisoryCommand.newBuilder()
+                .setServerHandle(serverHandle)
+                .setItemHandle(itemHandle))
+        .build());
+
+session.write(serverHandle, itemHandle, value, userId);
+```
+
+The CLI exposes the same command as `advise-supervisory`, and `write` /
+`write2` take `--user-id`.
+
+### Array writes replace the whole array
+
+A write to an array attribute **replaces the entire array**; it is not an
+element-wise patch. To change a subset of elements, send the full array with
+the unchanged elements included. For example, to change 2 elements of a
+20-element array, build the `MxValue` from all 20 values (the 18 unchanged plus
+the 2 new ones). Sending only the 2 changed values overwrites the attribute
+with a 2-element array.
+
+When only a few indices need changing and the rest should be reset to the
+element type's default, use `writeArrayElements` instead of building the full
+array manually:
+
+```java
+session.writeArrayElements(
+        serverHandle, itemHandle,
+        MxDataType.MX_DATA_TYPE_INTEGER,
+        20, // totalLength
+        Map.of(
+                2, MxValues.int32Value(42),
+                7, MxValues.int32Value(99)),
+        userId);
+```
+
+The gateway expands the sparse descriptor into a full `totalLength`-element
+array before forwarding to the worker. Indices not listed in the map are
+written as the element type's default — this is a **reset**, not a preserve;
+current values at those positions are discarded. `totalLength` is required and
+must match the declared length of the array attribute. Bare-name array items
+(`Area001.Pump001.Speed`) are auto-normalized to the `[]` form across the whole
+add family — `AddItem`, `AddItem2`, `AddItemBulk`, and `AddBufferedItem` — so the
+array attribute accepts the write.
+
 ## Galaxy Repository Browse
 
 The Galaxy Repository service is a separate metadata-only gRPC service exposed
@@ -99,17 +179,88 @@ try (GalaxyRepositoryClient galaxy = GalaxyRepositoryClient.connect(options)) {
 messages directly so callers can read all fields (including the nested
 `GalaxyAttribute` list) without an extra DTO layer.
 
-The CLI exposes matching subcommands: `galaxy-test`, `galaxy-deploy-time`,
-`galaxy-discover`, and `galaxy-watch`. They take the same `--endpoint`,
-`--api-key-env`, `--plaintext`, `--ca-file`, `--server-name-override`,
-`--timeout`, and `--json` options as the gateway commands.
+The CLI exposes matching subcommands: `galaxy-test-connection`,
+`galaxy-last-deploy`, `galaxy-discover`, `galaxy-browse`, and `galaxy-watch`.
+The short names `galaxy-test` and `galaxy-deploy-time` remain as deprecated
+aliases for `galaxy-test-connection` and `galaxy-last-deploy` so existing
+scripts keep working. They take the same `--endpoint`, `--api-key-env`,
+`--plaintext`, `--ca-file`, `--server-name-override`, `--timeout`, and `--json`
+options as the gateway commands.
 
 ```powershell
-gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-test --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
-gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-deploy-time --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-test-connection --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-last-deploy --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
 gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-discover --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
 ```
 
+`galaxy-browse` walks the hierarchy via `BrowseChildren`. Without `--parent` it
+returns the root nodes and eagerly expands `--depth` further levels; with
+`--parent <gobject-id>` it returns exactly one level of children for that
+parent. The filter flags (`--category-ids`, `--template-contains`,
+`--tag-name-glob`, `--alarm-bearing-only`, `--historized-only`,
+`--include-attributes`) match `galaxy-discover`. The `--json` node shape is the
+cross-client browse surface: the flattened object fields plus a
+`hasChildrenHint` flag and a nested `children` array.
+
+```powershell
+gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-browse --depth 1 --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+```
+
+### Browsing lazily
+
+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. 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.browseChildrenRaw(
+        BrowseChildrenRequest.newBuilder().build());
+
+List<GalaxyObject> children = reply.getChildrenList();
+List<Boolean> hasChildren = reply.getChildHasChildrenList();
+for (int i = 0; i < children.size(); i++) {
+    System.out.printf("%s expand=%b%n", children.get(i).getTagName(), hasChildren.get(i));
+}
+```
+
+#### High-level walker
+
+For UI trees, the client provides a `LazyBrowseNode` walker that handles
+sibling pagination and the `child_has_children` hint for you:
+
+```java
+MxGatewayClientOptions options = MxGatewayClientOptions.builder()
+        .endpoint("localhost:5000")
+        .apiKey(System.getenv("MXGATEWAY_API_KEY"))
+        .plaintext(true)
+        .build();
+
+try (GalaxyRepositoryClient galaxy = GalaxyRepositoryClient.connect(options)) {
+    List<LazyBrowseNode> roots = galaxy.browse();
+    for (LazyBrowseNode root : roots) {
+        if (root.hasChildrenHint()) {
+            root.expand();
+        }
+        for (LazyBrowseNode child : root.getChildren()) {
+            String kind = child.hasChildrenHint() ? "has children" : "leaf";
+            System.out.println(child.getObject().getTagName() + " (" + kind + ")");
+        }
+    }
+}
+```
+
+`expand` is idempotent — calling it twice fires only one RPC,
+and is safe under concurrent callers. To refresh after a Galaxy redeploy, call
+`browse` again from the root.
+
 ### Watching deploy events
 
 `GalaxyRepository.WatchDeployEvents` is a server-streaming RPC: the gateway
@@ -168,17 +319,23 @@ Run the CLI through Gradle:
 ```powershell
 gradle :zb-mom-ww-mxgateway-cli:run --args="version --json"
 gradle :zb-mom-ww-mxgateway-cli:run --args="open-session --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --client-session-name java-cli --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="ping --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --message hello --json"
 gradle :zb-mom-ww-mxgateway-cli:run --args="register --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --client-name java-cli --json"
 gradle :zb-mom-ww-mxgateway-cli:run --args="add-item --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item TestObject.TestInt --json"
 gradle :zb-mom-ww-mxgateway-cli:run --args="advise --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item-handle 1 --json"
 gradle :zb-mom-ww-mxgateway-cli:run --args="write --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --json"
 gradle :zb-mom-ww-mxgateway-cli:run --args="stream-events --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --limit 1 --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="stream-alarms --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --filter-prefix Galaxy --limit 1 --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="acknowledge-alarm --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --reference \"\\Galaxy\Area001.Pump001.PumpFault\" --json"
 gradle :zb-mom-ww-mxgateway-cli:run --args="smoke --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --item TestObject.TestInt --json"
 ```
 
 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:
 
@@ -221,6 +378,37 @@ $env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
 gradle :zb-mom-ww-mxgateway-cli:run --args="smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json"
 ```
 
+## Installing from the Gitea Maven repository
+
+The client publishes to the internal Gitea Maven repository at
+`https://gitea.dohertylan.com/api/packages/dohertj2/maven`.
+
+In your consumer project's `build.gradle`:
+
+````groovy
+repositories {
+    maven {
+        url 'https://gitea.dohertylan.com/api/packages/dohertj2/maven'
+        credentials {
+            username = System.getenv('GITEA_USERNAME')
+            password = System.getenv('GITEA_TOKEN')
+        }
+    }
+}
+
+dependencies {
+    implementation 'com.zb.mom.ww.mxgateway:zb-mom-ww-mxgateway-client:0.1.2'
+}
+````
+
+To publish a new version from this repo:
+
+````bash
+export GITEA_USERNAME=dohertj2
+export GITEA_TOKEN=<your-gitea-token>
+gradle :zb-mom-ww-mxgateway-client:publish
+````
+
 ## Related Documentation
 
 - [Client Packaging](../../docs/ClientPackaging.md)

clients/java/build.gradle

@@ -13,7 +13,7 @@ ext {
 
 subprojects {
     group = 'com.zb.mom.ww.mxgateway'
-    version = '0.1.0'
+    version = '0.1.2'
 
     pluginManager.withPlugin('java') {
         java {
@@ -37,4 +37,44 @@ subprojects {
             testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
         }
     }
+
+    pluginManager.withPlugin('maven-publish') {
+        publishing {
+            publications {
+                maven(MavenPublication) {
+                    from components.java
+                    pom {
+                        url = 'https://gitea.dohertylan.com/dohertj2/mxaccessgw'
+                        description = 'MxAccessGateway Java client'
+                        scm {
+                            url = 'https://gitea.dohertylan.com/dohertj2/mxaccessgw'
+                            connection = 'scm:git:https://gitea.dohertylan.com/dohertj2/mxaccessgw.git'
+                        }
+                        developers {
+                            developer {
+                                id = 'dohertj2'
+                                name = 'Joseph Doherty'
+                            }
+                        }
+                        licenses {
+                            license {
+                                name = 'Proprietary'
+                                distribution = 'repo'
+                            }
+                        }
+                    }
+                }
+            }
+            repositories {
+                maven {
+                    name = 'GiteaPackages'
+                    url = 'https://gitea.dohertylan.com/api/packages/dohertj2/maven'
+                    credentials {
+                        username = System.getenv('GITEA_USERNAME') ?: ''
+                        password = System.getenv('GITEA_TOKEN') ?: ''
+                    }
+                }
+            }
+        }
+    }
 }

clients/java/settings.gradle

@@ -9,6 +9,10 @@ pluginManagement {
     }
 }
 
+plugins {
+    id 'org.gradle.toolchains.foojay-resolver-convention' version '1.0.0'
+}
+
 dependencyResolutionManagement {
     repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
     repositories {

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

@@ -142,6 +142,37 @@ public final class GalaxyRepositoryGrpc {
     return getWatchDeployEventsMethod;
   }
 
+  private static volatile io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest,
+      galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply> getBrowseChildrenMethod;
+
+  @io.grpc.stub.annotations.RpcMethod(
+      fullMethodName = SERVICE_NAME + '/' + "BrowseChildren",
+      requestType = galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest.class,
+      responseType = galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply.class,
+      methodType = io.grpc.MethodDescriptor.MethodType.UNARY)
+  public static io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest,
+      galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply> getBrowseChildrenMethod() {
+    io.grpc.MethodDescriptor<galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest, galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply> getBrowseChildrenMethod;
+    if ((getBrowseChildrenMethod = GalaxyRepositoryGrpc.getBrowseChildrenMethod) == null) {
+      synchronized (GalaxyRepositoryGrpc.class) {
+        if ((getBrowseChildrenMethod = GalaxyRepositoryGrpc.getBrowseChildrenMethod) == null) {
+          GalaxyRepositoryGrpc.getBrowseChildrenMethod = getBrowseChildrenMethod =
+              io.grpc.MethodDescriptor.<galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest, galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply>newBuilder()
+              .setType(io.grpc.MethodDescriptor.MethodType.UNARY)
+              .setFullMethodName(generateFullMethodName(SERVICE_NAME, "BrowseChildren"))
+              .setSampledToLocalTracing(true)
+              .setRequestMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest.getDefaultInstance()))
+              .setResponseMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply.getDefaultInstance()))
+              .setSchemaDescriptor(new GalaxyRepositoryMethodDescriptorSupplier("BrowseChildren"))
+              .build();
+        }
+      }
+    }
+    return getBrowseChildrenMethod;
+  }
+
   /**
    * Creates a new async stub that supports all call types for the service
    */
@@ -246,6 +277,19 @@ public final class GalaxyRepositoryGrpc {
         io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent> responseObserver) {
       io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getWatchDeployEventsMethod(), responseObserver);
     }
+
+    /**
+     * <pre>
+     * Returns the direct children of a parent object (or the root objects when
+     * `parent` is unset). Designed for OPC UA-style lazy expand: clients walk
+     * one level at a time instead of paging the full hierarchy. Filters mirror
+     * DiscoverHierarchy exactly. Backed by the same shared hierarchy cache.
+     * </pre>
+     */
+    default void browseChildren(galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest request,
+        io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply> responseObserver) {
+      io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getBrowseChildrenMethod(), responseObserver);
+    }
   }
 
   /**
@@ -326,6 +370,20 @@ public final class GalaxyRepositoryGrpc {
       io.grpc.stub.ClientCalls.asyncServerStreamingCall(
           getChannel().newCall(getWatchDeployEventsMethod(), getCallOptions()), request, responseObserver);
     }
+
+    /**
+     * <pre>
+     * Returns the direct children of a parent object (or the root objects when
+     * `parent` is unset). Designed for OPC UA-style lazy expand: clients walk
+     * one level at a time instead of paging the full hierarchy. Filters mirror
+     * DiscoverHierarchy exactly. Backed by the same shared hierarchy cache.
+     * </pre>
+     */
+    public void browseChildren(galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest request,
+        io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply> responseObserver) {
+      io.grpc.stub.ClientCalls.asyncUnaryCall(
+          getChannel().newCall(getBrowseChildrenMethod(), getCallOptions()), request, responseObserver);
+    }
   }
 
   /**
@@ -387,6 +445,19 @@ public final class GalaxyRepositoryGrpc {
       return io.grpc.stub.ClientCalls.blockingV2ServerStreamingCall(
           getChannel(), getWatchDeployEventsMethod(), getCallOptions(), request);
     }
+
+    /**
+     * <pre>
+     * Returns the direct children of a parent object (or the root objects when
+     * `parent` is unset). Designed for OPC UA-style lazy expand: clients walk
+     * one level at a time instead of paging the full hierarchy. Filters mirror
+     * DiscoverHierarchy exactly. Backed by the same shared hierarchy cache.
+     * </pre>
+     */
+    public galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply browseChildren(galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest request) throws io.grpc.StatusException {
+      return io.grpc.stub.ClientCalls.blockingV2UnaryCall(
+          getChannel(), getBrowseChildrenMethod(), getCallOptions(), request);
+    }
   }
 
   /**
@@ -447,6 +518,19 @@ public final class GalaxyRepositoryGrpc {
       return io.grpc.stub.ClientCalls.blockingServerStreamingCall(
           getChannel(), getWatchDeployEventsMethod(), getCallOptions(), request);
     }
+
+    /**
+     * <pre>
+     * Returns the direct children of a parent object (or the root objects when
+     * `parent` is unset). Designed for OPC UA-style lazy expand: clients walk
+     * one level at a time instead of paging the full hierarchy. Filters mirror
+     * DiscoverHierarchy exactly. Backed by the same shared hierarchy cache.
+     * </pre>
+     */
+    public galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply browseChildren(galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest request) {
+      return io.grpc.stub.ClientCalls.blockingUnaryCall(
+          getChannel(), getBrowseChildrenMethod(), getCallOptions(), request);
+    }
   }
 
   /**
@@ -494,12 +578,27 @@ public final class GalaxyRepositoryGrpc {
       return io.grpc.stub.ClientCalls.futureUnaryCall(
           getChannel().newCall(getDiscoverHierarchyMethod(), getCallOptions()), request);
     }
+
+    /**
+     * <pre>
+     * Returns the direct children of a parent object (or the root objects when
+     * `parent` is unset). Designed for OPC UA-style lazy expand: clients walk
+     * one level at a time instead of paging the full hierarchy. Filters mirror
+     * DiscoverHierarchy exactly. Backed by the same shared hierarchy cache.
+     * </pre>
+     */
+    public com.google.common.util.concurrent.ListenableFuture<galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply> browseChildren(
+        galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest request) {
+      return io.grpc.stub.ClientCalls.futureUnaryCall(
+          getChannel().newCall(getBrowseChildrenMethod(), getCallOptions()), request);
+    }
   }
 
   private static final int METHODID_TEST_CONNECTION = 0;
   private static final int METHODID_GET_LAST_DEPLOY_TIME = 1;
   private static final int METHODID_DISCOVER_HIERARCHY = 2;
   private static final int METHODID_WATCH_DEPLOY_EVENTS = 3;
+  private static final int METHODID_BROWSE_CHILDREN = 4;
 
   private static final class MethodHandlers<Req, Resp> implements
       io.grpc.stub.ServerCalls.UnaryMethod<Req, Resp>,
@@ -534,6 +633,10 @@ public final class GalaxyRepositoryGrpc {
           serviceImpl.watchDeployEvents((galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest) request,
               (io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent>) responseObserver);
           break;
+        case METHODID_BROWSE_CHILDREN:
+          serviceImpl.browseChildren((galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest) request,
+              (io.grpc.stub.StreamObserver<galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply>) responseObserver);
+          break;
         default:
           throw new AssertionError();
       }
@@ -580,6 +683,13 @@ public final class GalaxyRepositoryGrpc {
               galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest,
               galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent>(
                 service, METHODID_WATCH_DEPLOY_EVENTS)))
+        .addMethod(
+          getBrowseChildrenMethod(),
+          io.grpc.stub.ServerCalls.asyncUnaryCall(
+            new MethodHandlers<
+              galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest,
+              galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply>(
+                service, METHODID_BROWSE_CHILDREN)))
         .build();
   }
 
@@ -632,6 +742,7 @@ public final class GalaxyRepositoryGrpc {
               .addMethod(getGetLastDeployTimeMethod())
               .addMethod(getDiscoverHierarchyMethod())
               .addMethod(getWatchDeployEventsMethod())
+              .addMethod(getBrowseChildrenMethod())
               .build();
         }
       }

clients/java/zb-mom-ww-mxgateway-cli/build.gradle

@@ -6,6 +6,9 @@ dependencies {
     implementation project(':zb-mom-ww-mxgateway-client')
     implementation "com.google.protobuf:protobuf-java-util:${protobufVersion}"
     implementation "info.picocli:picocli:${picocliVersion}"
+
+    testImplementation "io.grpc:grpc-inprocess:${grpcVersion}"
+    testImplementation "io.grpc:grpc-testing:${grpcVersion}"
 }
 
 application {

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

@@ -0,0 +1,232 @@
+package com.zb.mom.ww.mxgateway.cli;
+
+import com.zb.mom.ww.mxgateway.client.GalaxyRepositoryClient;
+import com.zb.mom.ww.mxgateway.client.MxGatewayClient;
+import com.zb.mom.ww.mxgateway.client.MxGatewayClientOptions;
+import galaxy_repository.v1.GalaxyRepositoryGrpc;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GalaxyObject;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest;
+import io.grpc.ManagedChannel;
+import io.grpc.Server;
+import io.grpc.inprocess.InProcessChannelBuilder;
+import io.grpc.inprocess.InProcessServerBuilder;
+import io.grpc.stub.StreamObserver;
+import java.io.IOException;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+import java.util.concurrent.CopyOnWriteArrayList;
+import mxaccess_gateway.v1.MxAccessGatewayGrpc;
+import mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply;
+import mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest;
+import mxaccess_gateway.v1.MxaccessGateway.MxEvent;
+import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
+import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatusCode;
+import mxaccess_gateway.v1.MxaccessGateway.SessionState;
+
+/**
+ * Test fixture that stands up an in-process gRPC server hosting scripted fake
+ * {@code MxAccessGateway} and {@code GalaxyRepository} service implementations,
+ * so the real Java client types ({@link MxGatewayClient} /
+ * {@link GalaxyRepositoryClient}) can be driven over a real channel.
+ *
+ * <p>The real streaming wrappers ({@code MxEventStream} /
+ * {@code DeployEventStream}) have package-private constructors and
+ * {@link GalaxyRepositoryClient} is {@code final}, so the streaming and galaxy
+ * CLI commands cannot be exercised through the lightweight {@code FakeSession}
+ * seam. Driving the real client over an in-process channel against scripted
+ * services is the clean alternative; Tasks 5 and 6 add the CLI assertions on
+ * top of this fixture.
+ *
+ * <p>Scripted payloads are settable via constructor args or setters. Each
+ * instance uses a unique server name so harnesses do not collide. The
+ * {@code directExecutor()} wiring keeps all dispatch on the calling thread, so
+ * no background threads are leaked.
+ *
+ * <p><strong>Implemented RPCs.</strong> The scripted services override only the
+ * RPCs the CLI tests currently exercise:
+ *
+ * <ul>
+ *   <li>{@code MxAccessGateway}: {@code streamEvents}, {@code closeSession}.</li>
+ *   <li>{@code GalaxyRepository}: {@code discoverHierarchy},
+ *       {@code watchDeployEvents}.</li>
+ * </ul>
+ *
+ * Every other RPC (e.g. {@code openSession}, {@code invoke}, {@code register},
+ * {@code streamAlarms}, {@code queryActiveAlarms}, {@code browseChildren}) is
+ * left at the generated {@code *ImplBase} default and therefore returns gRPC
+ * {@code UNIMPLEMENTED} by design. A future test that needs one of those paths
+ * must add the corresponding scripted override here first — otherwise the call
+ * fails with {@code UNIMPLEMENTED} rather than the behaviour under test.
+ */
+final class InProcessGatewayHarness implements AutoCloseable {
+    private final String serverName;
+    private final Server server;
+    private final ManagedChannel channel;
+    private final FakeGatewayService fakeGateway;
+    private final FakeGalaxyService fakeGalaxy;
+
+    /** Starts a harness with empty scripted payloads; populate via setters. */
+    InProcessGatewayHarness() {
+        this(List.of(), List.of(), List.of());
+    }
+
+    /**
+     * Starts a harness with the supplied scripted payloads.
+     *
+     * @param scriptedEvents events {@code streamEvents} pushes before completing
+     * @param scriptedObjects objects {@code discoverHierarchy} returns (single page)
+     * @param scriptedDeployEvents events {@code watchDeployEvents} streams before completing
+     */
+    InProcessGatewayHarness(
+            List<MxEvent> scriptedEvents,
+            List<GalaxyObject> scriptedObjects,
+            List<DeployEvent> scriptedDeployEvents) {
+        this.serverName = "mxgw-cli-harness-" + UUID.randomUUID();
+        this.fakeGateway = new FakeGatewayService(scriptedEvents);
+        this.fakeGalaxy = new FakeGalaxyService(scriptedObjects, scriptedDeployEvents);
+        try {
+            this.server = InProcessServerBuilder.forName(serverName)
+                    .directExecutor()
+                    .addService(fakeGateway)
+                    .addService(fakeGalaxy)
+                    .build()
+                    .start();
+        } catch (IOException error) {
+            throw new IllegalStateException("failed to start in-process gateway harness", error);
+        }
+        this.channel = InProcessChannelBuilder.forName(serverName).directExecutor().build();
+    }
+
+    /** Replaces the scripted {@code streamEvents} payload. */
+    void setScriptedEvents(List<MxEvent> events) {
+        fakeGateway.scriptedEvents.clear();
+        fakeGateway.scriptedEvents.addAll(events);
+    }
+
+    /** Replaces the scripted {@code discoverHierarchy} payload. */
+    void setScriptedObjects(List<GalaxyObject> objects) {
+        fakeGalaxy.scriptedObjects.clear();
+        fakeGalaxy.scriptedObjects.addAll(objects);
+    }
+
+    /** Replaces the scripted {@code watchDeployEvents} payload. */
+    void setScriptedDeployEvents(List<DeployEvent> deployEvents) {
+        fakeGalaxy.scriptedDeployEvents.clear();
+        fakeGalaxy.scriptedDeployEvents.addAll(deployEvents);
+    }
+
+    /**
+     * Returns the in-process channel into the scripted services.
+     *
+     * @return the managed channel; lifecycle owned by the harness
+     */
+    ManagedChannel channel() {
+        return channel;
+    }
+
+    /**
+     * Builds a real {@link MxGatewayClient} over the in-process channel.
+     *
+     * @return a client borrowing the harness channel
+     */
+    MxGatewayClient gatewayClient() {
+        return new MxGatewayClient(channel, testOptions());
+    }
+
+    /**
+     * Builds a real {@link GalaxyRepositoryClient} over the in-process channel.
+     *
+     * @return a client borrowing the harness channel
+     */
+    GalaxyRepositoryClient galaxyClient() {
+        return new GalaxyRepositoryClient(channel, testOptions());
+    }
+
+    private static MxGatewayClientOptions testOptions() {
+        return MxGatewayClientOptions.builder()
+                .endpoint("in-process")
+                .apiKey("mxgw_test_secret")
+                .plaintext(true)
+                .callTimeout(Duration.ofSeconds(5))
+                .build();
+    }
+
+    @Override
+    public void close() {
+        channel.shutdownNow();
+        server.shutdownNow();
+    }
+
+    private static ProtocolStatus ok() {
+        return ProtocolStatus.newBuilder()
+                .setCode(ProtocolStatusCode.PROTOCOL_STATUS_CODE_OK)
+                .build();
+    }
+
+    /** Scripted fake of the {@code MxAccessGateway} service. */
+    private static final class FakeGatewayService extends MxAccessGatewayGrpc.MxAccessGatewayImplBase {
+        private final List<MxEvent> scriptedEvents = new CopyOnWriteArrayList<>();
+
+        FakeGatewayService(List<MxEvent> scriptedEvents) {
+            this.scriptedEvents.addAll(scriptedEvents);
+        }
+
+        @Override
+        public void streamEvents(
+                mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest request,
+                StreamObserver<MxEvent> responseObserver) {
+            for (MxEvent event : scriptedEvents) {
+                responseObserver.onNext(event);
+            }
+            responseObserver.onCompleted();
+        }
+
+        @Override
+        public void closeSession(
+                CloseSessionRequest request, StreamObserver<CloseSessionReply> responseObserver) {
+            responseObserver.onNext(CloseSessionReply.newBuilder()
+                    .setSessionId(request.getSessionId())
+                    .setFinalState(SessionState.SESSION_STATE_CLOSED)
+                    .setProtocolStatus(ok())
+                    .build());
+            responseObserver.onCompleted();
+        }
+    }
+
+    /** Scripted fake of the {@code GalaxyRepository} service. */
+    private static final class FakeGalaxyService extends GalaxyRepositoryGrpc.GalaxyRepositoryImplBase {
+        private final List<GalaxyObject> scriptedObjects = new CopyOnWriteArrayList<>();
+        private final List<DeployEvent> scriptedDeployEvents = new CopyOnWriteArrayList<>();
+
+        FakeGalaxyService(List<GalaxyObject> scriptedObjects, List<DeployEvent> scriptedDeployEvents) {
+            this.scriptedObjects.addAll(scriptedObjects);
+            this.scriptedDeployEvents.addAll(scriptedDeployEvents);
+        }
+
+        @Override
+        public void discoverHierarchy(
+                DiscoverHierarchyRequest request, StreamObserver<DiscoverHierarchyReply> responseObserver) {
+            List<GalaxyObject> snapshot = new ArrayList<>(scriptedObjects);
+            responseObserver.onNext(DiscoverHierarchyReply.newBuilder()
+                    .setTotalObjectCount(snapshot.size())
+                    .addAllObjects(snapshot)
+                    .setNextPageToken("")
+                    .build());
+            responseObserver.onCompleted();
+        }
+
+        @Override
+        public void watchDeployEvents(
+                WatchDeployEventsRequest request, StreamObserver<DeployEvent> responseObserver) {
+            for (DeployEvent event : scriptedDeployEvents) {
+                responseObserver.onNext(event);
+            }
+            responseObserver.onCompleted();
+        }
+    }
+}

clients/java/zb-mom-ww-mxgateway-client/build.gradle

@@ -1,6 +1,7 @@
 plugins {
     id 'java-library'
     id 'com.google.protobuf'
+    id 'maven-publish'
 }
 
 dependencies {
@@ -30,6 +31,11 @@ sourceSets {
     }
 }
 
+java {
+    withSourcesJar()
+    withJavadocJar()
+}
+
 protobuf {
     protoc {
         artifact = "com.google.protobuf:protoc:${protobufVersion}"

clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/BrowseChildrenOptions.java

@@ -0,0 +1,105 @@
+package com.zb.mom.ww.mxgateway.client;
+
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Filters and shape options for {@link GalaxyRepositoryClient#browse(BrowseChildrenOptions)}.
+ * Mirror of the existing DiscoverHierarchy options for the lazy-browse path.
+ *
+ * <p>All filter fields are AND-combined server-side. Empty / unset fields disable
+ * that filter. The {@code includeAttributes} tri-state uses {@code null} to mean
+ * "let the server use its default"; non-{@code null} forwards the explicit flag.
+ */
+public final class BrowseChildrenOptions {
+    private final List<Integer> categoryIds;
+    private final List<String> templateChainContains;
+    private final String tagNameGlob;
+    private final Boolean includeAttributes;
+    private final boolean alarmBearingOnly;
+    private final boolean historizedOnly;
+
+    private BrowseChildrenOptions(Builder b) {
+        this.categoryIds = List.copyOf(b.categoryIds);
+        this.templateChainContains = List.copyOf(b.templateChainContains);
+        this.tagNameGlob = b.tagNameGlob;
+        this.includeAttributes = b.includeAttributes;
+        this.alarmBearingOnly = b.alarmBearingOnly;
+        this.historizedOnly = b.historizedOnly;
+    }
+
+    /** @return immutable list of category IDs to include; empty disables this filter. */
+    public List<Integer> getCategoryIds() { return categoryIds; }
+
+    /** @return immutable list of template names that must appear in each child's template chain. */
+    public List<String> getTemplateChainContains() { return templateChainContains; }
+
+    /** @return SQL-LIKE-style glob applied to {@code tag_name}; empty disables. */
+    public String getTagNameGlob() { return tagNameGlob; }
+
+    /** @return tri-state override for {@code include_attributes}; {@code null} keeps the server default. */
+    public Boolean getIncludeAttributes() { return includeAttributes; }
+
+    /** @return restrict to alarm-bearing objects. */
+    public boolean isAlarmBearingOnly() { return alarmBearingOnly; }
+
+    /** @return restrict to objects with at least one historized attribute. */
+    public boolean isHistorizedOnly() { return historizedOnly; }
+
+    /** @return a fresh builder. */
+    public static Builder builder() { return new Builder(); }
+
+    /** @return options with every filter disabled and {@code includeAttributes} unset. */
+    public static BrowseChildrenOptions empty() { return builder().build(); }
+
+    /** Fluent builder for {@link BrowseChildrenOptions}. */
+    public static final class Builder {
+        private List<Integer> categoryIds = Collections.emptyList();
+        private List<String> templateChainContains = Collections.emptyList();
+        private String tagNameGlob = "";
+        private Boolean includeAttributes = null;
+        private boolean alarmBearingOnly = false;
+        private boolean historizedOnly = false;
+
+        /** Sets the category-id filter. */
+        public Builder categoryIds(List<Integer> v) {
+            this.categoryIds = v == null ? Collections.emptyList() : v;
+            return this;
+        }
+
+        /** Sets the template-chain-contains filter. */
+        public Builder templateChainContains(List<String> v) {
+            this.templateChainContains = v == null ? Collections.emptyList() : v;
+            return this;
+        }
+
+        /** Sets the tag-name glob. */
+        public Builder tagNameGlob(String v) {
+            this.tagNameGlob = v == null ? "" : v;
+            return this;
+        }
+
+        /** Sets the tri-state {@code includeAttributes} override; {@code null} keeps the server default. */
+        public Builder includeAttributes(Boolean v) {
+            this.includeAttributes = v;
+            return this;
+        }
+
+        /** Toggles the alarm-bearing-only filter. */
+        public Builder alarmBearingOnly(boolean v) {
+            this.alarmBearingOnly = v;
+            return this;
+        }
+
+        /** Toggles the historized-only filter. */
+        public Builder historizedOnly(boolean v) {
+            this.historizedOnly = v;
+            return this;
+        }
+
+        /** Builds the immutable options. */
+        public BrowseChildrenOptions build() {
+            return new BrowseChildrenOptions(this);
+        }
+    }
+}

clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/DeployEventSubscription.java

@@ -2,64 +2,19 @@ package com.zb.mom.ww.mxgateway.client;
 
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest;
-import io.grpc.stub.ClientCallStreamObserver;
-import io.grpc.stub.ClientResponseObserver;
 import io.grpc.stub.StreamObserver;
-import java.util.concurrent.atomic.AtomicBoolean;
-import java.util.concurrent.atomic.AtomicReference;
 
 /**
  * Cancellable handle returned by the async {@code watchDeployEvents} variant.
  * Mirrors {@link MxGatewayEventSubscription} but for the Galaxy Repository
  * deploy-event stream.
+ *
+ * <p>All lifecycle / cancellation behaviour is inherited from
+ * {@link MxGatewayStreamSubscription} (Client.Java-036).
  */
-public final class DeployEventSubscription implements AutoCloseable {
-    private final AtomicReference<ClientCallStreamObserver<WatchDeployEventsRequest>> requestStream =
-            new AtomicReference<>();
-    private final AtomicBoolean cancelled = new AtomicBoolean();
-
-    ClientResponseObserver<WatchDeployEventsRequest, DeployEvent> wrap(StreamObserver<DeployEvent> observer) {
-        return new ClientResponseObserver<>() {
-            @Override
-            public void beforeStart(ClientCallStreamObserver<WatchDeployEventsRequest> stream) {
-                requestStream.set(stream);
-                if (cancelled.get()) {
-                    stream.cancel("client cancelled deploy event stream", null);
-                }
-            }
-
-            @Override
-            public void onNext(DeployEvent value) {
-                observer.onNext(value);
-            }
-
-            @Override
-            public void onError(Throwable error) {
-                observer.onError(error);
-            }
-
-            @Override
-            public void onCompleted() {
-                observer.onCompleted();
-            }
-        };
-    }
-
-    /**
-     * Cancels the underlying gRPC call. Safe to invoke before the call has
-     * started; cancellation is recorded and applied as soon as the stream
-     * attaches.
-     */
-    public void cancel() {
-        cancelled.set(true);
-        ClientCallStreamObserver<WatchDeployEventsRequest> stream = requestStream.get();
-        if (stream != null) {
-            stream.cancel("client cancelled deploy event stream", null);
-        }
-    }
-
-    @Override
-    public void close() {
-        cancel();
+public final class DeployEventSubscription
+        extends MxGatewayStreamSubscription<WatchDeployEventsRequest, DeployEvent> {
+    public DeployEventSubscription() {
+        super("client cancelled deploy event stream");
     }
 }

clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/GalaxyRepositoryClient.java

@@ -4,6 +4,8 @@ import com.google.common.util.concurrent.FutureCallback;
 import com.google.common.util.concurrent.Futures;
 import com.google.common.util.concurrent.MoreExecutors;
 import galaxy_repository.v1.GalaxyRepositoryGrpc;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest;
@@ -37,6 +39,7 @@ import javax.net.ssl.SSLException;
  */
 public final class GalaxyRepositoryClient implements AutoCloseable {
     private static final int DISCOVER_HIERARCHY_PAGE_SIZE = 5000;
+    private static final int BROWSE_CHILDREN_PAGE_SIZE = 500;
 
     private final ManagedChannel ownedChannel;
     private final MxGatewayClientOptions options;
@@ -213,6 +216,98 @@ public final class GalaxyRepositoryClient implements AutoCloseable {
         return discoverHierarchyPageAsync("", new java.util.ArrayList<>(), new java.util.HashSet<>());
     }
 
+    /**
+     * Lazy-browse entry point: fetches the root layer of the Galaxy hierarchy.
+     * Each returned {@link LazyBrowseNode} can be expanded on demand via
+     * {@link LazyBrowseNode#expand()} to load its direct children.
+     *
+     * @return the root nodes (no parent selector) with default options
+     * @throws MxGatewayException on transport or protocol failure
+     */
+    public List<LazyBrowseNode> browse() {
+        return browse(null);
+    }
+
+    /**
+     * Lazy-browse entry point with caller-supplied filters / shape.
+     *
+     * @param options filter and shape options; {@code null} means {@link BrowseChildrenOptions#empty()}
+     * @return the root nodes matching the options
+     * @throws MxGatewayException on transport or protocol failure
+     */
+    public List<LazyBrowseNode> browse(BrowseChildrenOptions options) {
+        BrowseChildrenOptions effective = options == null ? BrowseChildrenOptions.empty() : options;
+        return browseChildrenInner(null, effective);
+    }
+
+    /**
+     * Issues a single {@code BrowseChildren} RPC and returns the raw reply.
+     * Callers wanting full control over pagination can drive the loop themselves.
+     *
+     * @param request the request to send
+     * @return the reply
+     * @throws MxGatewayException on transport or protocol failure
+     */
+    public BrowseChildrenReply browseChildrenRaw(BrowseChildrenRequest request) {
+        try {
+            return rawBlockingStub().browseChildren(request);
+        } catch (RuntimeException error) {
+            if (error instanceof MxGatewayException) {
+                throw error;
+            }
+            throw MxGatewayErrors.fromGrpc("galaxy browse children", error);
+        }
+    }
+
+    /**
+     * Drives the BrowseChildren paging loop for a single parent (or roots when
+     * {@code parentGobjectId} is {@code null}). Detects repeated page tokens to
+     * avoid infinite loops on a buggy server.
+     */
+    List<LazyBrowseNode> browseChildrenInner(Integer parentGobjectId, BrowseChildrenOptions options) {
+        java.util.ArrayList<LazyBrowseNode> nodes = new java.util.ArrayList<>();
+        java.util.HashSet<String> seenPageTokens = new java.util.HashSet<>();
+        String pageToken = "";
+        while (true) {
+            BrowseChildrenRequest.Builder builder = BrowseChildrenRequest.newBuilder()
+                    .setPageSize(BROWSE_CHILDREN_PAGE_SIZE)
+                    .setPageToken(pageToken)
+                    .setAlarmBearingOnly(options.isAlarmBearingOnly())
+                    .setHistorizedOnly(options.isHistorizedOnly());
+            if (parentGobjectId != null) {
+                builder.setParentGobjectId(parentGobjectId.intValue());
+            }
+            if (!options.getCategoryIds().isEmpty()) {
+                builder.addAllCategoryIds(options.getCategoryIds());
+            }
+            if (!options.getTemplateChainContains().isEmpty()) {
+                builder.addAllTemplateChainContains(options.getTemplateChainContains());
+            }
+            if (!options.getTagNameGlob().isEmpty()) {
+                builder.setTagNameGlob(options.getTagNameGlob());
+            }
+            if (options.getIncludeAttributes() != null) {
+                builder.setIncludeAttributes(options.getIncludeAttributes());
+            }
+
+            BrowseChildrenReply reply = browseChildrenRaw(builder.build());
+
+            for (int i = 0; i < reply.getChildrenCount(); i++) {
+                boolean hint = i < reply.getChildHasChildrenCount() && reply.getChildHasChildren(i);
+                nodes.add(new LazyBrowseNode(this, reply.getChildren(i), hint, options));
+            }
+
+            pageToken = reply.getNextPageToken();
+            if (pageToken == null || pageToken.isEmpty()) {
+                return nodes;
+            }
+            if (!seenPageTokens.add(pageToken)) {
+                throw new MxGatewayException(
+                        "galaxy browse children returned repeated page token: " + pageToken);
+            }
+        }
+    }
+
     /**
      * Subscribes to {@code WatchDeployEvents} via the async stub and consumes
      * results through a blocking iterator. Closing the returned stream cancels

clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/LazyBrowseNode.java

@@ -0,0 +1,150 @@
+package com.zb.mom.ww.mxgateway.client;
+
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GalaxyObject;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.locks.ReentrantReadWriteLock;
+
+/**
+ * One node in a lazy-loaded Galaxy browse tree. Holds the underlying
+ * {@link GalaxyObject} and exposes {@link #expand()} to fetch its direct
+ * children on demand. Expansion is one-shot: a second call is a no-op.
+ * Pagination of large sibling sets is handled internally by the client.
+ */
+public final class LazyBrowseNode {
+    private final GalaxyRepositoryClient client;
+    private final GalaxyObject object;
+    private final boolean hasChildrenHint;
+    private final BrowseChildrenOptions options;
+
+    // expandLock gates the start of a new expand AND the publish of the in-flight
+    // future. Readers (getChildren / isExpanded) use a separate read-write lock so
+    // they never block on the gRPC call.
+    private final Object expandLock = new Object();
+    private CompletableFuture<Void> inFlight;
+
+    private final ReentrantReadWriteLock readWriteLock = new ReentrantReadWriteLock();
+    private List<LazyBrowseNode> children = Collections.emptyList();
+    private boolean isExpanded;
+
+    LazyBrowseNode(
+            GalaxyRepositoryClient client,
+            GalaxyObject object,
+            boolean hasChildrenHint,
+            BrowseChildrenOptions options) {
+        this.client = client;
+        this.object = object;
+        this.hasChildrenHint = hasChildrenHint;
+        this.options = options;
+    }
+
+    /** @return the underlying Galaxy object proto for this node. */
+    public GalaxyObject getObject() {
+        return object;
+    }
+
+    /** @return {@code true} when the server reports this node has at least one matching descendant. */
+    public boolean hasChildrenHint() {
+        return hasChildrenHint;
+    }
+
+    /** @return a snapshot of direct children loaded by {@link #expand()}; empty until then. */
+    public List<LazyBrowseNode> getChildren() {
+        readWriteLock.readLock().lock();
+        try {
+            return List.copyOf(children);
+        } finally {
+            readWriteLock.readLock().unlock();
+        }
+    }
+
+    /** @return {@code true} after the first {@link #expand()} call completes. */
+    public boolean isExpanded() {
+        readWriteLock.readLock().lock();
+        try {
+            return isExpanded;
+        } finally {
+            readWriteLock.readLock().unlock();
+        }
+    }
+
+    /**
+     * Fetches direct children from the gateway and populates {@link #getChildren()}.
+     * Idempotent: subsequent calls are no-ops and do not issue a second RPC.
+     *
+     * <p>Concurrent callers coalesce onto a single in-flight RPC: the first caller
+     * (the "leader") issues the gRPC call, while any other thread that calls
+     * {@code expand()} during that window blocks on the leader's future and sees
+     * the same result (or the same exception). On failure the in-flight slot is
+     * cleared so a subsequent call can retry.
+     *
+     * <p>Readers ({@link #getChildren()} / {@link #isExpanded()}) take a separate
+     * read lock and are never blocked for the duration of the RPC.
+     *
+     * @throws MxGatewayException on transport or protocol failure
+     */
+    public void expand() {
+        if (isExpanded()) {
+            return;
+        }
+
+        CompletableFuture<Void> future;
+        boolean iAmTheLeader;
+        synchronized (expandLock) {
+            if (isExpanded()) {
+                return;
+            }
+            if (inFlight != null) {
+                future = inFlight;
+                iAmTheLeader = false;
+            } else {
+                future = new CompletableFuture<>();
+                inFlight = future;
+                iAmTheLeader = true;
+            }
+        }
+
+        if (iAmTheLeader) {
+            try {
+                List<LazyBrowseNode> loaded =
+                        client.browseChildrenInner(object.getGobjectId(), options);
+                readWriteLock.writeLock().lock();
+                try {
+                    this.children = loaded;
+                    this.isExpanded = true;
+                } finally {
+                    readWriteLock.writeLock().unlock();
+                }
+                synchronized (expandLock) {
+                    inFlight = null;
+                }
+                future.complete(null);
+            } catch (RuntimeException ex) {
+                synchronized (expandLock) {
+                    inFlight = null;
+                }
+                future.completeExceptionally(ex);
+                throw ex;
+            }
+        } else {
+            try {
+                future.get();
+            } catch (InterruptedException ie) {
+                Thread.currentThread().interrupt();
+                throw new MxGatewayException("Interrupted waiting for browse-children expand.", ie);
+            } catch (ExecutionException ee) {
+                Throwable cause = ee.getCause();
+                if (cause instanceof MxGatewayException me) {
+                    throw me;
+                }
+                if (cause instanceof RuntimeException re) {
+                    throw re;
+                }
+                throw new MxGatewayException("BrowseChildren expand failed.", cause);
+            }
+        }
+    }
+}

clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/MxGatewayActiveAlarmsSubscription.java

@@ -1,10 +1,6 @@
 package com.zb.mom.ww.mxgateway.client;
 
-import io.grpc.stub.ClientCallStreamObserver;
-import io.grpc.stub.ClientResponseObserver;
 import io.grpc.stub.StreamObserver;
-import java.util.concurrent.atomic.AtomicBoolean;
-import java.util.concurrent.atomic.AtomicReference;
 import mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot;
 import mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest;
 
@@ -15,53 +11,13 @@ import mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest;
  * {@link #cancel()} entry point that aborts the underlying gRPC call. The
  * subscription also implements {@link AutoCloseable} so it can participate in
  * try-with-resources blocks.
+ *
+ * <p>All lifecycle / cancellation behaviour is inherited from
+ * {@link MxGatewayStreamSubscription} (Client.Java-036).
  */
-public final class MxGatewayActiveAlarmsSubscription implements AutoCloseable {
-    private final AtomicReference<ClientCallStreamObserver<QueryActiveAlarmsRequest>> requestStream = new AtomicReference<>();
-    private final AtomicBoolean cancelled = new AtomicBoolean();
-
-    ClientResponseObserver<QueryActiveAlarmsRequest, ActiveAlarmSnapshot> wrap(StreamObserver<ActiveAlarmSnapshot> observer) {
-        return new ClientResponseObserver<>() {
-            @Override
-            public void beforeStart(ClientCallStreamObserver<QueryActiveAlarmsRequest> stream) {
-                requestStream.set(stream);
-                if (cancelled.get()) {
-                    stream.cancel("client cancelled active-alarms query", null);
-                }
-            }
-
-            @Override
-            public void onNext(ActiveAlarmSnapshot value) {
-                observer.onNext(value);
-            }
-
-            @Override
-            public void onError(Throwable error) {
-                observer.onError(error);
-            }
-
-            @Override
-            public void onCompleted() {
-                observer.onCompleted();
-            }
-        };
-    }
-
-    /**
-     * Cancels the underlying gRPC call. Safe to invoke before the call has
-     * started; cancellation is recorded and applied as soon as the stream
-     * attaches.
-     */
-    public void cancel() {
-        cancelled.set(true);
-        ClientCallStreamObserver<QueryActiveAlarmsRequest> stream = requestStream.get();
-        if (stream != null) {
-            stream.cancel("client cancelled active-alarms query", null);
-        }
-    }
-
-    @Override
-    public void close() {
-        cancel();
+public final class MxGatewayActiveAlarmsSubscription
+        extends MxGatewayStreamSubscription<QueryActiveAlarmsRequest, ActiveAlarmSnapshot> {
+    public MxGatewayActiveAlarmsSubscription() {
+        super("client cancelled active-alarms query");
     }
 }

clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/MxGatewayAlarmFeedSubscription.java

@@ -0,0 +1,23 @@
+package com.zb.mom.ww.mxgateway.client;
+
+import io.grpc.stub.StreamObserver;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage;
+import mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest;
+
+/**
+ * Cancellable handle returned by {@code streamAlarms}.
+ *
+ * <p>Wraps a caller-supplied {@link StreamObserver} and exposes a
+ * {@link #cancel()} entry point that aborts the underlying gRPC call. The
+ * subscription also implements {@link AutoCloseable} so it can participate in
+ * try-with-resources blocks.
+ *
+ * <p>All lifecycle / cancellation behaviour is inherited from
+ * {@link MxGatewayStreamSubscription} (Client.Java-036).
+ */
+public final class MxGatewayAlarmFeedSubscription
+        extends MxGatewayStreamSubscription<StreamAlarmsRequest, AlarmFeedMessage> {
+    public MxGatewayAlarmFeedSubscription() {
+        super("client cancelled alarm feed");
+    }
+}

clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/MxGatewayClient.java

@@ -18,6 +18,7 @@ import mxaccess_gateway.v1.MxAccessGatewayGrpc;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest;
 import mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest;
 import mxaccess_gateway.v1.MxaccessGateway.MxCommandReply;
@@ -27,6 +28,7 @@ import mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply;
 import mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest;
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatusCode;
 import mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest;
+import mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest;
 import mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest;
 
 /**
@@ -320,6 +322,27 @@ public final class MxGatewayClient implements AutoCloseable {
         return subscription;
     }
 
+    /**
+     * Attaches to the gateway's central alarm feed. The stream opens with one
+     * {@code AlarmFeedMessage} per currently-active alarm (the ConditionRefresh
+     * snapshot), then a single {@code snapshot_complete}, then a
+     * {@code transition} for every subsequent raise / acknowledge / clear.
+     *
+     * <p>Served by the gateway's always-on alarm monitor — no worker session is
+     * opened — so any number of clients may attach.
+     *
+     * @param request the {@code StreamAlarmsRequest}, optionally scoped by
+     *                alarm-reference prefix
+     * @param observer caller-supplied observer that receives feed messages and completion
+     * @return a cancellable subscription handle
+     */
+    public MxGatewayAlarmFeedSubscription streamAlarms(
+            StreamAlarmsRequest request, StreamObserver<AlarmFeedMessage> observer) {
+        MxGatewayAlarmFeedSubscription subscription = new MxGatewayAlarmFeedSubscription();
+        withStreamDeadline(rawAsyncStub()).streamAlarms(request, subscription.wrap(observer));
+        return subscription;
+    }
+
     @Override
     public void close() {
         if (ownedChannel != null) {
@@ -361,6 +384,15 @@ public final class MxGatewayClient implements AutoCloseable {
             } catch (SSLException error) {
                 throw new MxGatewayException("failed to configure gateway TLS", error);
             }
+        } else if (!options.requireCertificateValidation()) {
+            try {
+                builder.sslContext(GrpcSslContexts.forClient()
+                        .trustManager(io.grpc.netty.shaded.io.netty.handler.ssl.util
+                                .InsecureTrustManagerFactory.INSTANCE)
+                        .build());
+            } catch (SSLException error) {
+                throw new MxGatewayException("failed to configure lenient gateway TLS", error);
+            }
         } else {
             builder.useTransportSecurity();
         }
@@ -370,6 +402,19 @@ public final class MxGatewayClient implements AutoCloseable {
         return builder.build();
     }
 
+    /**
+     * Package-visible test seam — creates a raw {@link ManagedChannel} from the
+     * given options without attaching auth interceptors. Used by TLS fixture
+     * tests to verify channel construction behaviour without a full
+     * {@link MxGatewayClient} wrapper.
+     *
+     * @param options the client options
+     * @return a new {@link ManagedChannel}
+     */
+    static ManagedChannel createChannelForTests(MxGatewayClientOptions options) {
+        return createChannel(options);
+    }
+
     private <T extends io.grpc.stub.AbstractStub<T>> T withDeadline(T stub) {
         if (options.callTimeout().isNegative()) {
             return stub;

clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/MxGatewayClientOptions.java

@@ -20,6 +20,7 @@ public final class MxGatewayClientOptions {
     private final String apiKey;
     private final boolean plaintext;
     private final Path caCertificatePath;
+    private final boolean requireCertificateValidation;
     private final String serverNameOverride;
     private final Duration connectTimeout;
     private final Duration callTimeout;
@@ -31,6 +32,7 @@ public final class MxGatewayClientOptions {
         apiKey = builder.apiKey == null ? "" : builder.apiKey;
         plaintext = builder.plaintext;
         caCertificatePath = builder.caCertificatePath;
+        requireCertificateValidation = builder.requireCertificateValidation;
         serverNameOverride = builder.serverNameOverride == null ? "" : builder.serverNameOverride;
         connectTimeout = builder.connectTimeout == null ? DEFAULT_CONNECT_TIMEOUT : builder.connectTimeout;
         callTimeout = builder.callTimeout == null ? DEFAULT_CALL_TIMEOUT : builder.callTimeout;
@@ -95,6 +97,18 @@ public final class MxGatewayClientOptions {
         return caCertificatePath;
     }
 
+    /**
+     * Returns whether TLS certificate verification is required even when no CA is pinned.
+     * When {@code false} (default), the gateway's self-signed certificate is accepted
+     * without verification. When {@code true}, the OS trust store is used.
+     * Pinning a CA via {@link #caCertificatePath()} always verifies regardless of this flag.
+     *
+     * @return {@code true} if strict certificate verification is required
+     */
+    public boolean requireCertificateValidation() {
+        return requireCertificateValidation;
+    }
+
     /**
      * Returns the TLS server-name override, or an empty string when none was supplied.
      *
@@ -148,6 +162,8 @@ public final class MxGatewayClientOptions {
                 + plaintext
                 + ", caCertificatePath="
                 + caCertificatePath
+                + ", requireCertificateValidation="
+                + requireCertificateValidation
                 + ", serverNameOverride='"
                 + serverNameOverride
                 + '\''
@@ -177,6 +193,7 @@ public final class MxGatewayClientOptions {
         private String apiKey;
         private boolean plaintext;
         private Path caCertificatePath;
+        private boolean requireCertificateValidation;
         private String serverNameOverride;
         private Duration connectTimeout;
         private Duration callTimeout;
@@ -230,6 +247,21 @@ public final class MxGatewayClientOptions {
             return this;
         }
 
+        /**
+         * When {@code true}, TLS connections without a pinned CA use the OS trust store
+         * and will reject the gateway's self-signed certificate. When {@code false}
+         * (default), the gateway certificate is accepted without verification —
+         * appropriate for this internal tool's auto-generated self-signed certificate.
+         * Pinning a CA via {@link #caCertificatePath(Path)} always verifies.
+         *
+         * @param value {@code true} to require certificate validation, {@code false} to accept any cert
+         * @return this builder
+         */
+        public Builder requireCertificateValidation(boolean value) {
+            requireCertificateValidation = value;
+            return this;
+        }
+
         /**
          * Overrides the TLS server name used during the handshake.
          *

clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/MxGatewayClientVersion.java

@@ -9,7 +9,7 @@ package com.zb.mom.ww.mxgateway.client;
 public final class MxGatewayClientVersion {
     private static final int GATEWAY_PROTOCOL_VERSION = 3;
     private static final int WORKER_PROTOCOL_VERSION = 1;
-    private static final String CLIENT_VERSION = "0.1.0";
+    private static final String CLIENT_VERSION = "0.1.2";
 
     private MxGatewayClientVersion() {
     }

clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/MxGatewayEventSubscription.java

@@ -1,10 +1,6 @@
 package com.zb.mom.ww.mxgateway.client;
 
-import io.grpc.stub.ClientCallStreamObserver;
-import io.grpc.stub.ClientResponseObserver;
 import io.grpc.stub.StreamObserver;
-import java.util.concurrent.atomic.AtomicReference;
-import java.util.concurrent.atomic.AtomicBoolean;
 import mxaccess_gateway.v1.MxaccessGateway.MxEvent;
 import mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest;
 
@@ -15,53 +11,13 @@ import mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest;
  * {@link #cancel()} entry point that aborts the underlying gRPC call. The
  * subscription also implements {@link AutoCloseable} so it can participate in
  * try-with-resources blocks.
+ *
+ * <p>All lifecycle / cancellation behaviour is inherited from
+ * {@link MxGatewayStreamSubscription} (Client.Java-036).
  */
-public final class MxGatewayEventSubscription implements AutoCloseable {
-    private final AtomicReference<ClientCallStreamObserver<StreamEventsRequest>> requestStream = new AtomicReference<>();
-    private final AtomicBoolean cancelled = new AtomicBoolean();
-
-    ClientResponseObserver<StreamEventsRequest, MxEvent> wrap(StreamObserver<MxEvent> observer) {
-        return new ClientResponseObserver<>() {
-            @Override
-            public void beforeStart(ClientCallStreamObserver<StreamEventsRequest> stream) {
-                requestStream.set(stream);
-                if (cancelled.get()) {
-                    stream.cancel("client cancelled event stream", null);
-                }
-            }
-
-            @Override
-            public void onNext(MxEvent value) {
-                observer.onNext(value);
-            }
-
-            @Override
-            public void onError(Throwable error) {
-                observer.onError(error);
-            }
-
-            @Override
-            public void onCompleted() {
-                observer.onCompleted();
-            }
-        };
-    }
-
-    /**
-     * Cancels the underlying gRPC call. Safe to invoke before the call has
-     * started; cancellation is recorded and applied as soon as the stream
-     * attaches.
-     */
-    public void cancel() {
-        cancelled.set(true);
-        ClientCallStreamObserver<StreamEventsRequest> stream = requestStream.get();
-        if (stream != null) {
-            stream.cancel("client cancelled event stream", null);
-        }
-    }
-
-    @Override
-    public void close() {
-        cancel();
+public final class MxGatewayEventSubscription
+        extends MxGatewayStreamSubscription<StreamEventsRequest, MxEvent> {
+    public MxGatewayEventSubscription() {
+        super("client cancelled event stream");
     }
 }

clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/MxGatewaySession.java

@@ -1,22 +1,31 @@
 package com.zb.mom.ww.mxgateway.client;
 
 import java.security.SecureRandom;
+import java.time.Duration;
 import java.util.HexFormat;
 import java.util.List;
+import java.util.Map;
 import java.util.Objects;
+import java.util.TreeMap;
 import mxaccess_gateway.v1.MxaccessGateway.AddItem2Command;
 import mxaccess_gateway.v1.MxaccessGateway.AddItemBulkCommand;
 import mxaccess_gateway.v1.MxaccessGateway.AddItemCommand;
 import mxaccess_gateway.v1.MxaccessGateway.AdviseItemBulkCommand;
 import mxaccess_gateway.v1.MxaccessGateway.AdviseCommand;
+import mxaccess_gateway.v1.MxaccessGateway.BulkReadResult;
+import mxaccess_gateway.v1.MxaccessGateway.BulkWriteResult;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest;
 import mxaccess_gateway.v1.MxaccessGateway.MxCommand;
 import mxaccess_gateway.v1.MxaccessGateway.MxCommandKind;
 import mxaccess_gateway.v1.MxaccessGateway.MxCommandReply;
 import mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest;
+import mxaccess_gateway.v1.MxaccessGateway.MxDataType;
+import mxaccess_gateway.v1.MxaccessGateway.MxSparseArray;
+import mxaccess_gateway.v1.MxaccessGateway.MxSparseElement;
 import mxaccess_gateway.v1.MxaccessGateway.MxValue;
 import mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply;
+import mxaccess_gateway.v1.MxaccessGateway.ReadBulkCommand;
 import mxaccess_gateway.v1.MxaccessGateway.RegisterCommand;
 import mxaccess_gateway.v1.MxaccessGateway.RemoveItemBulkCommand;
 import mxaccess_gateway.v1.MxaccessGateway.RemoveItemCommand;
@@ -27,8 +36,16 @@ import mxaccess_gateway.v1.MxaccessGateway.UnAdviseCommand;
 import mxaccess_gateway.v1.MxaccessGateway.UnAdviseItemBulkCommand;
 import mxaccess_gateway.v1.MxaccessGateway.UnsubscribeBulkCommand;
 import mxaccess_gateway.v1.MxaccessGateway.UnregisterCommand;
+import mxaccess_gateway.v1.MxaccessGateway.Write2BulkCommand;
+import mxaccess_gateway.v1.MxaccessGateway.Write2BulkEntry;
 import mxaccess_gateway.v1.MxaccessGateway.Write2Command;
+import mxaccess_gateway.v1.MxaccessGateway.WriteBulkCommand;
+import mxaccess_gateway.v1.MxaccessGateway.WriteBulkEntry;
 import mxaccess_gateway.v1.MxaccessGateway.WriteCommand;
+import mxaccess_gateway.v1.MxaccessGateway.WriteSecured2BulkCommand;
+import mxaccess_gateway.v1.MxaccessGateway.WriteSecured2BulkEntry;
+import mxaccess_gateway.v1.MxaccessGateway.WriteSecuredBulkCommand;
+import mxaccess_gateway.v1.MxaccessGateway.WriteSecuredBulkEntry;
 
 /**
  * Typed handle for a single MXAccess gateway session.
@@ -421,6 +438,142 @@ public final class MxGatewaySession implements AutoCloseable {
         return reply.getUnsubscribeBulk().getResultsList();
     }
 
+    /**
+     * Bulk {@code Write} — sequential MXAccess Write per entry on the worker's STA.
+     *
+     * <p>Per-entry failures appear as {@link BulkWriteResult} entries with
+     * {@code wasSuccessful == false}; this method does not throw for per-entry
+     * MXAccess failures (it still throws {@link MxGatewayException} on transport
+     * or protocol-level failures).
+     *
+     * @param serverHandle the {@code ServerHandle} owning the items
+     * @param entries the per-item (handle, value, user id) tuples
+     * @return a per-entry {@link BulkWriteResult} list
+     * @throws MxGatewayException on transport or protocol failure
+     * @throws NullPointerException if {@code entries} is {@code null}
+     */
+    public List<BulkWriteResult> writeBulk(int serverHandle, List<WriteBulkEntry> entries) {
+        Objects.requireNonNull(entries, "entries");
+        MxCommandReply reply = invokeCommand(MxCommand.newBuilder()
+                .setKind(MxCommandKind.MX_COMMAND_KIND_WRITE_BULK)
+                .setWriteBulk(WriteBulkCommand.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .addAllEntries(entries))
+                .build());
+        return reply.getWriteBulk().getResultsList();
+    }
+
+    /**
+     * Bulk {@code Write2} — sequential MXAccess Write2 (timestamped) per entry.
+     *
+     * <p>Per-entry semantics mirror {@link #writeBulk(int, List)}.
+     *
+     * @param serverHandle the {@code ServerHandle} owning the items
+     * @param entries the per-item (handle, value, timestamp, user id) tuples
+     * @return a per-entry {@link BulkWriteResult} list
+     * @throws MxGatewayException on transport or protocol failure
+     * @throws NullPointerException if {@code entries} is {@code null}
+     */
+    public List<BulkWriteResult> write2Bulk(int serverHandle, List<Write2BulkEntry> entries) {
+        Objects.requireNonNull(entries, "entries");
+        MxCommandReply reply = invokeCommand(MxCommand.newBuilder()
+                .setKind(MxCommandKind.MX_COMMAND_KIND_WRITE2_BULK)
+                .setWrite2Bulk(Write2BulkCommand.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .addAllEntries(entries))
+                .build());
+        return reply.getWrite2Bulk().getResultsList();
+    }
+
+    /**
+     * Bulk {@code WriteSecured} — credential-sensitive values must not be logged
+     * by callers; mirrors the single-item write-secured redaction contract.
+     *
+     * <p>Per-entry semantics mirror {@link #writeBulk(int, List)}.
+     *
+     * @param serverHandle the {@code ServerHandle} owning the items
+     * @param entries the per-item (handle, value, current+verifier user id) tuples
+     * @return a per-entry {@link BulkWriteResult} list
+     * @throws MxGatewayException on transport or protocol failure
+     * @throws NullPointerException if {@code entries} is {@code null}
+     */
+    public List<BulkWriteResult> writeSecuredBulk(int serverHandle, List<WriteSecuredBulkEntry> entries) {
+        Objects.requireNonNull(entries, "entries");
+        MxCommandReply reply = invokeCommand(MxCommand.newBuilder()
+                .setKind(MxCommandKind.MX_COMMAND_KIND_WRITE_SECURED_BULK)
+                .setWriteSecuredBulk(WriteSecuredBulkCommand.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .addAllEntries(entries))
+                .build());
+        return reply.getWriteSecuredBulk().getResultsList();
+    }
+
+    /**
+     * Bulk {@code WriteSecured2} — sequential timestamped + verified write per entry.
+     *
+     * <p>Per-entry semantics mirror {@link #writeBulk(int, List)}.
+     *
+     * @param serverHandle the {@code ServerHandle} owning the items
+     * @param entries the per-item (handle, value, timestamp, current+verifier user id) tuples
+     * @return a per-entry {@link BulkWriteResult} list
+     * @throws MxGatewayException on transport or protocol failure
+     * @throws NullPointerException if {@code entries} is {@code null}
+     */
+    public List<BulkWriteResult> writeSecured2Bulk(int serverHandle, List<WriteSecured2BulkEntry> entries) {
+        Objects.requireNonNull(entries, "entries");
+        MxCommandReply reply = invokeCommand(MxCommand.newBuilder()
+                .setKind(MxCommandKind.MX_COMMAND_KIND_WRITE_SECURED2_BULK)
+                .setWriteSecured2Bulk(WriteSecured2BulkCommand.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .addAllEntries(entries))
+                .build());
+        return reply.getWriteSecured2Bulk().getResultsList();
+    }
+
+    /**
+     * Bulk {@code Read} — snapshot the current value of each requested tag.
+     *
+     * <p>MXAccess COM has no synchronous read; the worker returns the cached
+     * {@code OnDataChange} value for any tag that is already advised
+     * ({@code wasCached == true}) without modifying the existing subscription,
+     * and falls back to a full AddItem + Advise + wait + UnAdvise + RemoveItem
+     * snapshot lifecycle otherwise. The supplied {@code timeout} bounds the
+     * per-tag wait in the snapshot case; pass {@link Duration#ZERO} (or
+     * {@code null}) to use the worker default (1000 ms). Per-tag failures
+     * appear as {@link BulkReadResult} entries with {@code wasSuccessful == false};
+     * this method does not throw for per-tag MXAccess failures.
+     *
+     * @param serverHandle the {@code ServerHandle} owning the items
+     * @param tagAddresses the tag addresses to read
+     * @param timeout per-tag snapshot timeout (zero or null = worker default)
+     * @return a per-tag {@link BulkReadResult} list
+     * @throws MxGatewayException on transport or protocol failure
+     * @throws NullPointerException if {@code tagAddresses} is {@code null}
+     * @throws IllegalArgumentException if {@code timeout} is negative or exceeds {@link Integer#MAX_VALUE} milliseconds
+     */
+    public List<BulkReadResult> readBulk(int serverHandle, List<String> tagAddresses, Duration timeout) {
+        Objects.requireNonNull(tagAddresses, "tagAddresses");
+        int timeoutMs = 0;
+        if (timeout != null) {
+            if (timeout.isNegative()) {
+                throw new IllegalArgumentException("timeout must be non-negative");
+            }
+            long millis = timeout.toMillis();
+            if (millis > Integer.MAX_VALUE) {
+                throw new IllegalArgumentException("timeout exceeds Integer.MAX_VALUE milliseconds");
+            }
+            timeoutMs = (int) millis;
+        }
+        MxCommandReply reply = invokeCommand(MxCommand.newBuilder()
+                .setKind(MxCommandKind.MX_COMMAND_KIND_READ_BULK)
+                .setReadBulk(ReadBulkCommand.newBuilder()
+                        .setServerHandle(serverHandle)
+                        .addAllTagAddresses(tagAddresses)
+                        .setTimeoutMs(timeoutMs))
+                .build());
+        return reply.getReadBulk().getResultsList();
+    }
+
     /**
      * Invokes MXAccess {@code Write}.
      *
@@ -455,6 +608,73 @@ public final class MxGatewaySession implements AutoCloseable {
                 .build());
     }
 
+    /**
+     * Writes a subset of an array's elements using MXAccess {@code Write}, building a
+     * write-only {@link MxSparseArray} value that the gateway expands into a full,
+     * default-filled array before forwarding to the worker.
+     *
+     * <p><strong>Default-fill semantics:</strong> only the indices supplied in
+     * {@code elements} are written; every unmentioned index is <em>reset</em> to the
+     * element type's default (for example {@code 0}, {@code false}, or an empty string),
+     * <em>not</em> preserved from the array's current contents. Use a full
+     * {@link MxValue} array write when you need to keep existing element values.
+     *
+     * <p>{@code totalLength} is required and defines the length of the expanded array;
+     * supplied indices must be within {@code [0, totalLength)}. Elements are iterated in
+     * ascending index order so the produced command is deterministic.
+     *
+     * <p>Because the proto fields {@code MxSparseArray.total_length} and
+     * {@code MxSparseElement.index} are {@code uint32}, passing a negative Java {@code int}
+     * would silently sign-extend to a large unsigned value on the wire. This method
+     * therefore rejects negative {@code totalLength} and negative element indices with
+     * {@link IllegalArgumentException} rather than allowing a hard-to-diagnose gateway error.
+     *
+     * @param serverHandle the {@code ServerHandle} owning the item
+     * @param itemHandle the {@code ItemHandle} to write
+     * @param elementDataType the {@link MxDataType} of the array's elements
+     * @param totalLength the total length of the expanded array; must be &gt; 0
+     * @param elements the indices to write mapped to their scalar values; each index must
+     *     be in {@code [0, totalLength)}; unmentioned indices are reset to the element
+     *     type default
+     * @param userId the MXAccess user id used for security checks
+     * @throws IllegalArgumentException if {@code totalLength} is not positive, or if any
+     *     element index is negative or &ge; {@code totalLength}
+     * @throws MxGatewayException on transport or protocol failure
+     */
+    public void writeArrayElements(
+            int serverHandle,
+            int itemHandle,
+            MxDataType elementDataType,
+            int totalLength,
+            Map<Integer, MxValue> elements,
+            int userId) {
+        Objects.requireNonNull(elementDataType, "elementDataType");
+        Objects.requireNonNull(elements, "elements");
+        if (totalLength <= 0) {
+            throw new IllegalArgumentException("totalLength must be > 0, got " + totalLength);
+        }
+        for (Map.Entry<Integer, MxValue> entry : elements.entrySet()) {
+            int idx = entry.getKey();
+            if (idx < 0 || idx >= totalLength) {
+                throw new IllegalArgumentException(
+                        "element index " + idx + " is out of range [0, " + totalLength + ")");
+            }
+        }
+        MxSparseArray.Builder sparse = MxSparseArray.newBuilder()
+                .setElementDataType(elementDataType)
+                .setTotalLength(totalLength);
+        // Iterate in ascending index order so the built command is deterministic.
+        for (Map.Entry<Integer, MxValue> entry : new TreeMap<>(elements).entrySet()) {
+            sparse.addElements(MxSparseElement.newBuilder()
+                    .setIndex(entry.getKey())
+                    .setValue(Objects.requireNonNull(entry.getValue(), "elements value")));
+        }
+        MxValue value = MxValue.newBuilder()
+                .setSparseArrayValue(sparse)
+                .build();
+        writeRaw(serverHandle, itemHandle, value, userId);
+    }
+
     /**
      * Invokes MXAccess {@code Write2}, which carries an explicit timestamp.
      *

clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/MxGatewayStreamSubscription.java

@@ -0,0 +1,89 @@
+package com.zb.mom.ww.mxgateway.client;
+
+import io.grpc.stub.ClientCallStreamObserver;
+import io.grpc.stub.ClientResponseObserver;
+import io.grpc.stub.StreamObserver;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicReference;
+
+/**
+ * Shared base for the cancellable subscription handles returned by the
+ * async-style server-streaming RPCs ({@code streamEvents}, {@code streamAlarms},
+ * {@code queryActiveAlarms}, {@code watchDeployEvents}).
+ *
+ * <p>All four subscription classes share the same lifecycle and cancellation
+ * contract:
+ *
+ * <ul>
+ *   <li>{@link #wrap(StreamObserver)} returns a {@link ClientResponseObserver}
+ *       that captures the underlying {@link ClientCallStreamObserver} in
+ *       {@code beforeStart}. If {@link #cancel()} was called before the gRPC
+ *       call attached, the stream is cancelled eagerly inside
+ *       {@code beforeStart} (the Client.Java-014 close-before-beforeStart
+ *       fix).</li>
+ *   <li>{@link #cancel()} is idempotent. It records the cancellation flag and
+ *       forwards {@code cancel(message, cause)} to the underlying stream when
+ *       one is attached; otherwise the flag is checked in {@code beforeStart}
+ *       once the stream attaches.</li>
+ *   <li>{@link #close()} delegates to {@link #cancel()} so the handle can be
+ *       used with try-with-resources.</li>
+ * </ul>
+ *
+ * <p>Subclasses supply only the cancel-message string used by {@code cancel()}.
+ * Refactor introduced for Client.Java-036 — the four prior subscription
+ * classes were structural near-clones (~60 lines each).
+ */
+abstract class MxGatewayStreamSubscription<TRequest, TResponse> implements AutoCloseable {
+    private final AtomicReference<ClientCallStreamObserver<TRequest>> requestStream = new AtomicReference<>();
+    private final AtomicBoolean cancelled = new AtomicBoolean();
+    private final String cancelMessage;
+
+    MxGatewayStreamSubscription(String cancelMessage) {
+        this.cancelMessage = cancelMessage;
+    }
+
+    final ClientResponseObserver<TRequest, TResponse> wrap(StreamObserver<TResponse> observer) {
+        return new ClientResponseObserver<>() {
+            @Override
+            public void beforeStart(ClientCallStreamObserver<TRequest> stream) {
+                requestStream.set(stream);
+                if (cancelled.get()) {
+                    stream.cancel(cancelMessage, null);
+                }
+            }
+
+            @Override
+            public void onNext(TResponse value) {
+                observer.onNext(value);
+            }
+
+            @Override
+            public void onError(Throwable error) {
+                observer.onError(error);
+            }
+
+            @Override
+            public void onCompleted() {
+                observer.onCompleted();
+            }
+        };
+    }
+
+    /**
+     * Cancels the underlying gRPC call. Safe to invoke before the call has
+     * started; cancellation is recorded and applied as soon as the stream
+     * attaches.
+     */
+    public final void cancel() {
+        cancelled.set(true);
+        ClientCallStreamObserver<TRequest> stream = requestStream.get();
+        if (stream != null) {
+            stream.cancel(cancelMessage, null);
+        }
+    }
+
+    @Override
+    public final void close() {
+        cancel();
+    }
+}

clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/MxValues.java

@@ -153,6 +153,9 @@ public final class MxValues {
             case TIMESTAMP_VALUE -> instant(value.getTimestampValue());
             case ARRAY_VALUE -> nativeArray(value.getArrayValue());
             case RAW_VALUE -> value.getRawValue().toByteArray();
+            // Write-only sparse descriptor: never produced by a read/decoded
+            // value, so it has no native representation.
+            case SPARSE_ARRAY_VALUE -> null;
             case KIND_NOT_SET -> null;
         };
     }

clients/java/zb-mom-ww-mxgateway-client/src/test/java/com/zb/mom/ww/mxgateway/client/GalaxyRepositoryClientTests.java

@@ -8,6 +8,8 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import com.google.protobuf.Timestamp;
 import galaxy_repository.v1.GalaxyRepositoryGrpc;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest;
@@ -24,6 +26,7 @@ import io.grpc.Server;
 import io.grpc.ServerCall;
 import io.grpc.ServerCallHandler;
 import io.grpc.ServerInterceptor;
+import io.grpc.Status;
 import io.grpc.inprocess.InProcessChannelBuilder;
 import io.grpc.inprocess.InProcessServerBuilder;
 import io.grpc.stub.ClientCallStreamObserver;
@@ -31,11 +34,20 @@ import io.grpc.stub.ClientResponseObserver;
 import io.grpc.stub.StreamObserver;
 import java.time.Duration;
 import java.time.Instant;
+import java.util.ArrayDeque;
+import java.util.Collections;
 import java.util.List;
 import java.util.Optional;
+import java.util.Queue;
 import java.util.UUID;
+import java.util.ArrayList;
+import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
 import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicReference;
 import org.junit.jupiter.api.Test;
 
@@ -196,6 +208,27 @@ final class GalaxyRepositoryClientTests {
         }
     }
 
+    @Test
+    void browseChildrenRejectsRepeatedPageToken() throws Exception {
+        // Queue the same BrowseChildrenReply twice with a non-empty NextPageToken.
+        // The client will request a second page and detect that the token repeats.
+        BrowseChildrenService service = new BrowseChildrenService();
+        BrowseChildrenReply repeatedReply = browseReply(
+                List.of(obj(1, "Plant", true)),
+                List.of(true),
+                1L,
+                "1:abc:1");
+        service.replies.add(repeatedReply);
+        service.replies.add(repeatedReply);
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            MxGatewayException error = assertThrows(MxGatewayException.class, client::browse);
+
+            assertTrue(error.getMessage().contains("repeated page token"));
+        }
+    }
+
     @Test
     void watchDeployEventsReceivesEventsInOrder() throws Exception {
         DeployEvent first = DeployEvent.newBuilder()
@@ -306,6 +339,294 @@ final class GalaxyRepositoryClientTests {
         }
     }
 
+    @Test
+    void browseNoParentReturnsRoots() throws Exception {
+        BrowseChildrenService service = new BrowseChildrenService();
+        service.replies.add(browseReply(
+                List.of(obj(1, "Plant", true), obj(2, "Other", false)),
+                List.of(true, false),
+                1L,
+                ""));
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            List<LazyBrowseNode> roots = client.browse();
+
+            assertEquals(2, roots.size());
+            assertEquals("Plant", roots.get(0).getObject().getTagName());
+            assertTrue(roots.get(0).hasChildrenHint());
+            assertFalse(roots.get(0).isExpanded());
+            assertEquals("Other", roots.get(1).getObject().getTagName());
+            assertFalse(roots.get(1).hasChildrenHint());
+            assertFalse(roots.get(1).isExpanded());
+            assertEquals(1, service.calls.size());
+            assertFalse(service.calls.get(0).hasParentGobjectId());
+        }
+    }
+
+    @Test
+    void browseExpandPopulatesChildrenAndMarksExpanded() throws Exception {
+        BrowseChildrenService service = new BrowseChildrenService();
+        service.replies.add(browseReply(
+                List.of(obj(1, "Plant", true)),
+                List.of(true),
+                1L,
+                ""));
+        service.replies.add(browseReply(
+                List.of(obj(10, "Line1", false)),
+                List.of(false),
+                1L,
+                ""));
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            List<LazyBrowseNode> roots = client.browse();
+            roots.get(0).expand();
+
+            assertTrue(roots.get(0).isExpanded());
+            assertEquals(1, roots.get(0).getChildren().size());
+            assertEquals("Line1", roots.get(0).getChildren().get(0).getObject().getTagName());
+            assertEquals(2, service.calls.size());
+            assertTrue(service.calls.get(1).hasParentGobjectId());
+            assertEquals(1, service.calls.get(1).getParentGobjectId());
+        }
+    }
+
+    @Test
+    void browseExpandIdempotentNoSecondRpc() throws Exception {
+        BrowseChildrenService service = new BrowseChildrenService();
+        service.replies.add(browseReply(
+                List.of(obj(1, "Plant", true)),
+                List.of(true),
+                1L,
+                ""));
+        service.replies.add(browseReply(
+                List.of(obj(10, "Line1", false)),
+                List.of(false),
+                1L,
+                ""));
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            List<LazyBrowseNode> roots = client.browse();
+            roots.get(0).expand();
+            roots.get(0).expand();
+
+            assertEquals(2, service.calls.size());
+            assertEquals(1, roots.get(0).getChildren().size());
+        }
+    }
+
+    @Test
+    void browseExpandUnknownParentThrowsGalaxyNotFound() throws Exception {
+        BrowseChildrenService service = new BrowseChildrenService();
+        service.replies.add(browseReply(
+                List.of(obj(1, "Plant", true)),
+                List.of(true),
+                1L,
+                ""));
+        service.errors.add(Status.NOT_FOUND.withDescription("Parent not found").asRuntimeException());
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            List<LazyBrowseNode> roots = client.browse();
+
+            MxGatewayException error = assertThrows(MxGatewayException.class, () -> roots.get(0).expand());
+            assertTrue(
+                    error.getMessage().toLowerCase().contains("not found"),
+                    "expected message to mention 'not found', got: " + error.getMessage());
+        }
+    }
+
+    @Test
+    void browseExpandMultiPageGathersAllPages() throws Exception {
+        BrowseChildrenService service = new BrowseChildrenService();
+        // Roots
+        service.replies.add(browseReply(
+                List.of(obj(7, "Plant", true)),
+                List.of(true),
+                1L,
+                ""));
+        // First child page with a next token
+        service.replies.add(browseReply(
+                List.of(obj(70, "ChildA", false), obj(71, "ChildB", false)),
+                List.of(false, false),
+                1L,
+                "7:abc:2"));
+        // Second child page closes the loop
+        service.replies.add(browseReply(
+                List.of(obj(72, "ChildC", false)),
+                List.of(false),
+                1L,
+                ""));
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            List<LazyBrowseNode> roots = client.browse();
+            roots.get(0).expand();
+
+            assertEquals(3, roots.get(0).getChildren().size());
+            assertEquals(3, service.calls.size());
+            assertEquals("7:abc:2", service.calls.get(2).getPageToken());
+        }
+    }
+
+    @Test
+    void browseExpandConcurrentCallersOnlyFireOneRpc() throws Exception {
+        // Verifies that concurrent expand() calls coalesce onto a single in-flight
+        // BrowseChildren RPC and that readers (isExpanded/getChildren) are not
+        // blocked for the full RPC duration.
+        BrowseChildrenReply rootsReply = browseReply(
+                List.of(obj(1, "Plant", true)),
+                List.of(true),
+                7L,
+                "");
+        BrowseChildrenReply childrenReply = browseReply(
+                List.of(obj(2, "Mixer_001", false)),
+                List.of(false),
+                7L,
+                "");
+
+        // Gate the child fetch behind a latch so multiple expanders can pile up.
+        CountDownLatch release = new CountDownLatch(1);
+        AtomicInteger childCalls = new AtomicInteger();
+        BrowseChildrenService service = new BrowseChildrenService() {
+            @Override
+            public void browseChildren(
+                    BrowseChildrenRequest request, StreamObserver<BrowseChildrenReply> responseObserver) {
+                calls.add(request);
+                BrowseChildrenReply reply;
+                if (!request.hasParentGobjectId()) {
+                    reply = rootsReply;
+                } else {
+                    // Block the leader until the followers have arrived.
+                    try {
+                        assertTrue(release.await(5, TimeUnit.SECONDS), "release latch never tripped");
+                    } catch (InterruptedException ie) {
+                        Thread.currentThread().interrupt();
+                        responseObserver.onError(Status.CANCELLED.asRuntimeException());
+                        return;
+                    }
+                    childCalls.incrementAndGet();
+                    reply = childrenReply;
+                }
+                responseObserver.onNext(reply);
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            List<LazyBrowseNode> roots = client.browse();
+            LazyBrowseNode root = roots.get(0);
+
+            int parallelism = 10;
+            ExecutorService pool = Executors.newFixedThreadPool(parallelism);
+            try {
+                CountDownLatch ready = new CountDownLatch(parallelism);
+                List<Future<Void>> futures = new ArrayList<>();
+                for (int i = 0; i < parallelism; i++) {
+                    futures.add(pool.submit(() -> {
+                        ready.countDown();
+                        root.expand();
+                        return null;
+                    }));
+                }
+                // Wait for all callers to be in flight, then release the leader.
+                assertTrue(ready.await(5, TimeUnit.SECONDS), "expander threads did not start");
+                // Readers must not be blocked by an in-flight expand; this should not deadlock
+                // and should return the pre-expand state.
+                assertFalse(root.isExpanded());
+                assertEquals(0, root.getChildren().size());
+                release.countDown();
+
+                for (Future<Void> f : futures) {
+                    f.get(10, TimeUnit.SECONDS);
+                }
+            } finally {
+                pool.shutdownNow();
+            }
+
+            assertTrue(root.isExpanded());
+            assertEquals(1, root.getChildren().size());
+            // Exactly one expand RPC was issued even though many callers raced.
+            assertEquals(1, childCalls.get());
+            // 1 roots fetch + exactly 1 expand fetch.
+            assertEquals(2, service.calls.size());
+        }
+    }
+
+    @Test
+    void browseWithFilterForwardsToRequest() throws Exception {
+        BrowseChildrenService service = new BrowseChildrenService();
+        // Default reply is empty; only the request shape matters here.
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            client.browse(BrowseChildrenOptions.builder()
+                    .tagNameGlob("Mixer*")
+                    .alarmBearingOnly(true)
+                    .build());
+        }
+
+        assertEquals(1, service.calls.size());
+        BrowseChildrenRequest request = service.calls.get(0);
+        assertEquals("Mixer*", request.getTagNameGlob());
+        assertTrue(request.getAlarmBearingOnly());
+    }
+
+    private static GalaxyObject obj(int id, String tag, boolean isArea) {
+        return GalaxyObject.newBuilder()
+                .setGobjectId(id)
+                .setTagName(tag)
+                .setBrowseName(tag)
+                .setIsArea(isArea)
+                .build();
+    }
+
+    private static BrowseChildrenReply browseReply(
+            List<GalaxyObject> children,
+            List<Boolean> childHasChildren,
+            long cacheSequence,
+            String nextPageToken) {
+        BrowseChildrenReply.Builder b = BrowseChildrenReply.newBuilder()
+                .setTotalChildCount(children.size())
+                .setCacheSequence(cacheSequence)
+                .setNextPageToken(nextPageToken);
+        b.addAllChildren(children);
+        b.addAllChildHasChildren(childHasChildren);
+        return b.build();
+    }
+
+    private static class BrowseChildrenService extends TestService {
+        final List<BrowseChildrenRequest> calls =
+                Collections.synchronizedList(new CopyOnWriteArrayList<>());
+        final Queue<BrowseChildrenReply> replies = new ArrayDeque<>();
+        final Queue<Throwable> errors = new ArrayDeque<>();
+
+        @Override
+        public void browseChildren(
+                BrowseChildrenRequest request, StreamObserver<BrowseChildrenReply> responseObserver) {
+            calls.add(request);
+            BrowseChildrenReply reply;
+            Throwable err;
+            synchronized (this) {
+                // Prefer queued replies first; once they're exhausted, fall through to any
+                // queued error. This matches the .NET fake's ordering used by parity tests.
+                reply = replies.poll();
+                err = reply == null ? errors.poll() : null;
+            }
+            if (err != null) {
+                responseObserver.onError(err);
+                return;
+            }
+            if (reply == null) {
+                reply = BrowseChildrenReply.getDefaultInstance();
+            }
+            responseObserver.onNext(reply);
+            responseObserver.onCompleted();
+        }
+    }
+
     private abstract static class TestService extends GalaxyRepositoryGrpc.GalaxyRepositoryImplBase {
         @Override
         public void testConnection(

clients/java/zb-mom-ww-mxgateway-client/src/test/java/com/zb/mom/ww/mxgateway/client/MxGatewayClientSessionTests.java

@@ -19,6 +19,7 @@ import io.grpc.stub.ServerCallStreamObserver;
 import io.grpc.stub.StreamObserver;
 import java.time.Duration;
 import java.util.List;
+import java.util.Map;
 import java.util.UUID;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
@@ -27,13 +28,19 @@ import mxaccess_gateway.v1.MxAccessGatewayGrpc;
 import mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot;
 import mxaccess_gateway.v1.MxaccessGateway.AddItemReply;
 import mxaccess_gateway.v1.MxaccessGateway.AlarmConditionState;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmTransitionKind;
 import mxaccess_gateway.v1.MxaccessGateway.BulkSubscribeReply;
+import mxaccess_gateway.v1.MxaccessGateway.OnAlarmTransitionEvent;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply;
 import mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest;
 import mxaccess_gateway.v1.MxaccessGateway.MxCommandKind;
 import mxaccess_gateway.v1.MxaccessGateway.MxCommandReply;
 import mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest;
+import mxaccess_gateway.v1.MxaccessGateway.MxDataType;
 import mxaccess_gateway.v1.MxaccessGateway.MxEvent;
+import mxaccess_gateway.v1.MxaccessGateway.MxSparseElement;
+import mxaccess_gateway.v1.MxaccessGateway.MxValue;
 import mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply;
 import mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest;
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
@@ -41,6 +48,7 @@ import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatusCode;
 import mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest;
 import mxaccess_gateway.v1.MxaccessGateway.RegisterReply;
 import mxaccess_gateway.v1.MxaccessGateway.SessionState;
+import mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest;
 import mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest;
 import mxaccess_gateway.v1.MxaccessGateway.SubscribeResult;
 import org.junit.jupiter.api.Test;
@@ -268,6 +276,100 @@ final class MxGatewayClientSessionTests {
         }
     }
 
+    @Test
+    void streamAlarmsForwardsRequestAndStreamsAlarmFeedMessages() throws Exception {
+        AtomicReference<StreamAlarmsRequest> streamRequest = new AtomicReference<>();
+        CountDownLatch serverCancelled = new CountDownLatch(1);
+        TestGatewayService service = new TestGatewayService() {
+            @Override
+            public void streamAlarms(
+                    StreamAlarmsRequest request, StreamObserver<AlarmFeedMessage> responseObserver) {
+                streamRequest.set(request);
+                ServerCallStreamObserver<AlarmFeedMessage> server =
+                        (ServerCallStreamObserver<AlarmFeedMessage>) responseObserver;
+                server.setOnCancelHandler(serverCancelled::countDown);
+                // Active-alarm snapshot, snapshot-complete sentinel, then a
+                // transition — mirrors the shape of a real alarm feed open.
+                server.onNext(AlarmFeedMessage.newBuilder()
+                        .setActiveAlarm(ActiveAlarmSnapshot.newBuilder()
+                                .setAlarmFullReference("Tank01.Level.HiHi")
+                                .setCurrentState(AlarmConditionState.ALARM_CONDITION_STATE_ACTIVE)
+                                .setSeverity(700))
+                        .build());
+                server.onNext(AlarmFeedMessage.newBuilder().setSnapshotComplete(true).build());
+                server.onNext(AlarmFeedMessage.newBuilder()
+                        .setTransition(OnAlarmTransitionEvent.newBuilder()
+                                .setAlarmFullReference("Tank01.Level.HiHi")
+                                .setTransitionKind(AlarmTransitionKind.ALARM_TRANSITION_KIND_ACKNOWLEDGE)
+                                .setSeverity(700))
+                        .build());
+                // Note: we deliberately do NOT call onCompleted() so the call
+                // remains open for the cancellation assertion below.
+            }
+        };
+
+        try (InProcessGateway gateway = InProcessGateway.start(service, new AtomicReference<>());
+                MxGatewayClient client = gateway.client("", Duration.ofSeconds(5))) {
+            java.util.List<AlarmFeedMessage> received = new java.util.ArrayList<>();
+            AtomicReference<Throwable> errorRef = new AtomicReference<>();
+            CountDownLatch threeReceived = new CountDownLatch(3);
+
+            StreamAlarmsRequest request = StreamAlarmsRequest.newBuilder()
+                    .setAlarmFilterPrefix("Tank01")
+                    .build();
+
+            MxGatewayAlarmFeedSubscription subscription = client.streamAlarms(
+                    request,
+                    new StreamObserver<>() {
+                        @Override
+                        public void onNext(AlarmFeedMessage value) {
+                            received.add(value);
+                            threeReceived.countDown();
+                        }
+
+                        @Override
+                        public void onError(Throwable t) {
+                            errorRef.set(t);
+                        }
+
+                        @Override
+                        public void onCompleted() {
+                        }
+                    });
+
+            assertTrue(threeReceived.await(5, TimeUnit.SECONDS),
+                    "expected three alarm feed messages within 5s");
+
+            // The request shape (filter prefix in particular) must reach the
+            // server — proves MxGatewayClient.streamAlarms calls the production
+            // subscription.wrap(observer) glue and not a CLI override.
+            assertNotNull(streamRequest.get());
+            assertEquals("Tank01", streamRequest.get().getAlarmFilterPrefix());
+
+            // Order and payload-case must be preserved (the wrapping observer
+            // is just a pass-through).
+            assertEquals(3, received.size());
+            assertEquals(AlarmFeedMessage.PayloadCase.ACTIVE_ALARM, received.get(0).getPayloadCase());
+            assertEquals(
+                    "Tank01.Level.HiHi",
+                    received.get(0).getActiveAlarm().getAlarmFullReference());
+            assertEquals(AlarmFeedMessage.PayloadCase.SNAPSHOT_COMPLETE, received.get(1).getPayloadCase());
+            assertEquals(AlarmFeedMessage.PayloadCase.TRANSITION, received.get(2).getPayloadCase());
+            assertEquals(
+                    AlarmTransitionKind.ALARM_TRANSITION_KIND_ACKNOWLEDGE,
+                    received.get(2).getTransition().getTransitionKind());
+
+            // No error expected before cancellation — proves the wrapping
+            // observer forwarded only data, not a synthetic error.
+            assertNull(errorRef.get(), "no error expected before cancellation");
+
+            // Cancellation must propagate to the underlying gRPC call.
+            subscription.cancel();
+            assertTrue(serverCancelled.await(5, TimeUnit.SECONDS),
+                    "server should observe RPC cancellation after subscription.cancel()");
+        }
+    }
+
     @Test
     void commandFailureKeepsRawReply() throws Exception {
         TestGatewayService service = new TestGatewayService() {
@@ -298,6 +400,115 @@ final class MxGatewayClientSessionTests {
         }
     }
 
+    @Test
+    void writeArrayElementsBuildsSparseArrayWriteCommand() throws Exception {
+        AtomicReference<MxCommandRequest> commandRequest = new AtomicReference<>();
+        TestGatewayService service = new TestGatewayService() {
+            @Override
+            public void invoke(MxCommandRequest request, StreamObserver<MxCommandReply> responseObserver) {
+                commandRequest.set(request);
+                responseObserver.onNext(MxCommandReply.newBuilder()
+                        .setSessionId(request.getSessionId())
+                        .setKind(request.getCommand().getKind())
+                        .setProtocolStatus(ok())
+                        .build());
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGateway gateway = InProcessGateway.start(service, new AtomicReference<>());
+                MxGatewayClient client = gateway.client("", Duration.ofSeconds(5))) {
+            MxGatewaySession session = MxGatewaySession.forSessionId(client, "sparse-session");
+
+            // Supply indices out of order to prove deterministic ascending iteration.
+            Map<Integer, MxValue> elements = Map.of(
+                    3, MxValues.int32Value(99),
+                    1, MxValues.int32Value(7));
+
+            session.writeArrayElements(12, 34, MxDataType.MX_DATA_TYPE_INTEGER, 5, elements, 56);
+
+            MxCommandRequest request = commandRequest.get();
+            assertNotNull(request);
+            assertEquals(MxCommandKind.MX_COMMAND_KIND_WRITE, request.getCommand().getKind());
+            assertEquals(12, request.getCommand().getWrite().getServerHandle());
+            assertEquals(34, request.getCommand().getWrite().getItemHandle());
+            assertEquals(56, request.getCommand().getWrite().getUserId());
+
+            MxValue written = request.getCommand().getWrite().getValue();
+            assertEquals(MxValue.KindCase.SPARSE_ARRAY_VALUE, written.getKindCase());
+            assertEquals(5, written.getSparseArrayValue().getTotalLength());
+            assertEquals(
+                    MxDataType.MX_DATA_TYPE_INTEGER,
+                    written.getSparseArrayValue().getElementDataType());
+
+            List<MxSparseElement> sparse = written.getSparseArrayValue().getElementsList();
+            assertEquals(2, sparse.size());
+            // Ascending index order is guaranteed by the helper.
+            assertEquals(1, sparse.get(0).getIndex());
+            assertEquals(7, sparse.get(0).getValue().getInt32Value());
+            assertEquals(3, sparse.get(1).getIndex());
+            assertEquals(99, sparse.get(1).getValue().getInt32Value());
+        }
+    }
+
+    @Test
+    void writeArrayElementsRejectsNonPositiveTotalLength() throws Exception {
+        // Client.Java-051: negative/zero totalLength silently sign-extends to a
+        // large uint32 on the wire; the client must reject it with
+        // IllegalArgumentException before building the proto message (before any
+        // network call is issued).
+        try (InProcessGateway gateway = InProcessGateway.start(
+                new TestGatewayService() {}, new AtomicReference<>());
+                MxGatewayClient client = gateway.client("", Duration.ofSeconds(5))) {
+            MxGatewaySession session = MxGatewaySession.forSessionId(client, "guard-session");
+
+            assertThrows(
+                    IllegalArgumentException.class,
+                    () -> session.writeArrayElements(
+                            1, 2, MxDataType.MX_DATA_TYPE_INTEGER, -1, Map.of(), 0),
+                    "negative totalLength must throw");
+
+            assertThrows(
+                    IllegalArgumentException.class,
+                    () -> session.writeArrayElements(
+                            1, 2, MxDataType.MX_DATA_TYPE_INTEGER, 0, Map.of(), 0),
+                    "zero totalLength must throw");
+        }
+    }
+
+    @Test
+    void writeArrayElementsRejectsOutOfRangeIndex() throws Exception {
+        // Client.Java-051: a negative index silently sign-extends to a large
+        // uint32 on the wire; an index >= totalLength exceeds the declared
+        // array bounds. Both must be caught before the network call.
+        try (InProcessGateway gateway = InProcessGateway.start(
+                new TestGatewayService() {}, new AtomicReference<>());
+                MxGatewayClient client = gateway.client("", Duration.ofSeconds(5))) {
+            MxGatewaySession session = MxGatewaySession.forSessionId(client, "guard-session");
+
+            assertThrows(
+                    IllegalArgumentException.class,
+                    () -> session.writeArrayElements(
+                            1, 2, MxDataType.MX_DATA_TYPE_INTEGER, 5,
+                            Map.of(-1, MxValues.int32Value(7)), 0),
+                    "negative index must throw");
+
+            assertThrows(
+                    IllegalArgumentException.class,
+                    () -> session.writeArrayElements(
+                            1, 2, MxDataType.MX_DATA_TYPE_INTEGER, 5,
+                            Map.of(5, MxValues.int32Value(7)), 0),
+                    "index equal to totalLength must throw");
+
+            assertThrows(
+                    IllegalArgumentException.class,
+                    () -> session.writeArrayElements(
+                            1, 2, MxDataType.MX_DATA_TYPE_INTEGER, 5,
+                            Map.of(10, MxValues.int32Value(7)), 0),
+                    "index above totalLength must throw");
+        }
+    }
+
     private static ProtocolStatus ok() {
         return ProtocolStatus.newBuilder()
                 .setCode(ProtocolStatusCode.PROTOCOL_STATUS_CODE_OK)

clients/java/zb-mom-ww-mxgateway-client/src/test/java/com/zb/mom/ww/mxgateway/client/MxGatewayClientTlsTests.java

@@ -0,0 +1,198 @@
+package com.zb.mom.ww.mxgateway.client;
+
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import io.grpc.ManagedChannel;
+import io.grpc.Server;
+import io.grpc.StatusRuntimeException;
+import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
+import io.grpc.netty.shaded.io.grpc.netty.NettyServerBuilder;
+import io.grpc.stub.StreamObserver;
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.net.InetSocketAddress;
+import java.nio.file.Files;
+import java.security.KeyStore;
+import java.security.PrivateKey;
+import java.security.cert.Certificate;
+import java.security.cert.X509Certificate;
+import java.time.Duration;
+import java.util.Base64;
+import java.util.concurrent.TimeUnit;
+import javax.net.ssl.SSLException;
+import mxaccess_gateway.v1.MxAccessGatewayGrpc;
+import mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply;
+import mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest;
+import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
+import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatusCode;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Verifies that the Java client connects to a Netty TLS server with a
+ * self-signed certificate when no CA is pinned (lenient default), and that
+ * setting {@code requireCertificateValidation(true)} causes a TLS failure.
+ *
+ * <p>A self-signed certificate is generated using {@code keytool} (always
+ * available in the JDK) to avoid dependencies on internal JDK APIs or
+ * BouncyCastle, and so the test works on all JDK versions used by the project.
+ */
+final class MxGatewayClientTlsTests {
+
+    private Server server;
+    private int port;
+    private File certPemFile;
+    private File keyPemFile;
+    private File keystoreFile;
+
+    @BeforeEach
+    void startTlsServer() throws Exception {
+        keystoreFile = File.createTempFile("gw-test-ks", ".p12");
+        certPemFile = File.createTempFile("gw-test-cert", ".pem");
+        keyPemFile = File.createTempFile("gw-test-key", ".pem");
+
+        // keytool refuses to write to a pre-existing (even empty) file; delete it first.
+        keystoreFile.delete();
+
+        // Use keytool to generate a self-signed PKCS12 keystore.
+        String keytool = ProcessHandle.current().info().command()
+                .map(cmd -> cmd.replace("java", "keytool"))
+                .orElse("keytool");
+        // Fall back to just "keytool" on PATH if the resolved path doesn't exist.
+        if (!new File(keytool).exists()) {
+            keytool = "keytool";
+        }
+        Process p = new ProcessBuilder(
+                keytool,
+                "-genkeypair",
+                "-alias", "server",
+                "-keyalg", "RSA",
+                "-keysize", "2048",
+                "-sigalg", "SHA256withRSA",
+                "-validity", "1",
+                "-dname", "CN=localhost",
+                "-storetype", "PKCS12",
+                "-storepass", "changeit",
+                "-keypass", "changeit",
+                "-keystore", keystoreFile.getAbsolutePath())
+                .redirectErrorStream(true)
+                .start();
+        int exit = p.waitFor();
+        if (exit != 0) {
+            String out = new String(p.getInputStream().readAllBytes());
+            throw new IllegalStateException("keytool failed (exit " + exit + "): " + out);
+        }
+
+        // Export cert and private key from the PKCS12 keystore to PEM files.
+        KeyStore ks = KeyStore.getInstance("PKCS12");
+        try (var is = Files.newInputStream(keystoreFile.toPath())) {
+            ks.load(is, "changeit".toCharArray());
+        }
+        X509Certificate cert = (X509Certificate) ks.getCertificate("server");
+        PrivateKey privateKey = (PrivateKey) ks.getKey("server", "changeit".toCharArray());
+
+        try (FileOutputStream out = new FileOutputStream(certPemFile)) {
+            out.write("-----BEGIN CERTIFICATE-----\n".getBytes());
+            out.write(Base64.getMimeEncoder(64, new byte[]{'\n'}).encode(cert.getEncoded()));
+            out.write("\n-----END CERTIFICATE-----\n".getBytes());
+        }
+        try (FileOutputStream out = new FileOutputStream(keyPemFile)) {
+            out.write("-----BEGIN PRIVATE KEY-----\n".getBytes());
+            out.write(Base64.getMimeEncoder(64, new byte[]{'\n'}).encode(privateKey.getEncoded()));
+            out.write("\n-----END PRIVATE KEY-----\n".getBytes());
+        }
+
+        server = NettyServerBuilder
+                .forAddress(new InetSocketAddress("127.0.0.1", 0))
+                .sslContext(GrpcSslContexts.forServer(certPemFile, keyPemFile).build())
+                .addService(new MinimalGatewayService())
+                .build()
+                .start();
+        port = server.getPort();
+    }
+
+    @AfterEach
+    void stopTlsServer() throws InterruptedException {
+        if (server != null) {
+            server.shutdown();
+            server.awaitTermination(5, TimeUnit.SECONDS);
+        }
+        if (certPemFile != null) {
+            certPemFile.delete();
+        }
+        if (keyPemFile != null) {
+            keyPemFile.delete();
+        }
+        if (keystoreFile != null) {
+            keystoreFile.delete();
+        }
+    }
+
+    @Test
+    void connectsToSelfSignedServer_WhenRequireCertificateValidationIsFalse() throws SSLException {
+        // Default options — requireCertificateValidation defaults to false.
+        MxGatewayClientOptions options = MxGatewayClientOptions.builder()
+                .endpoint("127.0.0.1:" + port)
+                .apiKey("test-key")
+                .connectTimeout(Duration.ofSeconds(5))
+                .callTimeout(Duration.ofSeconds(5))
+                .build();
+
+        ManagedChannel channel = MxGatewayClient.createChannelForTests(options);
+        try {
+            MxAccessGatewayGrpc.MxAccessGatewayBlockingStub stub =
+                    MxAccessGatewayGrpc.newBlockingStub(channel);
+            OpenSessionReply reply = stub.openSession(
+                    OpenSessionRequest.newBuilder()
+                            .setClientSessionName("tls-test")
+                            .build());
+            assertTrue(reply.getProtocolStatus().getCode()
+                    == ProtocolStatusCode.PROTOCOL_STATUS_CODE_OK);
+        } finally {
+            channel.shutdownNow();
+        }
+    }
+
+    @Test
+    void failsToConnect_WhenRequireCertificateValidationIsTrue() throws SSLException {
+        MxGatewayClientOptions options = MxGatewayClientOptions.builder()
+                .endpoint("127.0.0.1:" + port)
+                .apiKey("test-key")
+                .requireCertificateValidation(true)
+                .connectTimeout(Duration.ofSeconds(5))
+                .callTimeout(Duration.ofSeconds(5))
+                .build();
+
+        ManagedChannel channel = MxGatewayClient.createChannelForTests(options);
+        try {
+            MxAccessGatewayGrpc.MxAccessGatewayBlockingStub stub =
+                    MxAccessGatewayGrpc.newBlockingStub(channel);
+            assertThrows(StatusRuntimeException.class, () ->
+                    stub.openSession(OpenSessionRequest.newBuilder()
+                            .setClientSessionName("tls-strict-test")
+                            .build()));
+        } finally {
+            channel.shutdownNow();
+        }
+    }
+
+    /** Minimal gateway stub that succeeds any OpenSession call. */
+    private static final class MinimalGatewayService
+            extends MxAccessGatewayGrpc.MxAccessGatewayImplBase {
+        @Override
+        public void openSession(
+                OpenSessionRequest request,
+                StreamObserver<OpenSessionReply> responseObserver) {
+            responseObserver.onNext(OpenSessionReply.newBuilder()
+                    .setSessionId("tls-test-session")
+                    .setProtocolStatus(ProtocolStatus.newBuilder()
+                            .setCode(ProtocolStatusCode.PROTOCOL_STATUS_CODE_OK)
+                            .build())
+                    .build());
+            responseObserver.onCompleted();
+        }
+    }
+}

clients/java/zb-mom-ww-mxgateway-client/src/test/java/com/zb/mom/ww/mxgateway/client/MxGatewayStreamSubscriptionContractTests.java

@@ -0,0 +1,275 @@
+package com.zb.mom.ww.mxgateway.client;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest;
+import io.grpc.stub.ClientCallStreamObserver;
+import io.grpc.stub.ClientResponseObserver;
+import io.grpc.stub.StreamObserver;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.atomic.AtomicReference;
+import mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage;
+import mxaccess_gateway.v1.MxaccessGateway.MxEvent;
+import mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest;
+import mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest;
+import mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Lifecycle / cancellation contract tests applied uniformly to each of the
+ * four subscription classes that extend {@link MxGatewayStreamSubscription}.
+ *
+ * <p>Locks in the Client.Java-036 refactor: every subclass must exhibit the
+ * same behaviour for (a) cancel-before-beforeStart eagerly cancelling the
+ * stream once it attaches, (b) cancel-after-beforeStart forwarding directly
+ * to the stream, (c) the cancel message matching the subclass's documented
+ * value, (d) {@code close()} delegating to {@code cancel()}, and (e) the
+ * wrapping observer forwarding {@code onNext}/{@code onError}/{@code onCompleted}
+ * to the caller's observer.
+ */
+final class MxGatewayStreamSubscriptionContractTests {
+
+    @Test
+    void cancelBeforeBeforeStartCancelsStreamWhenItAttaches_eventSubscription() {
+        runCancelBeforeBeforeStartTest(new MxGatewayEventSubscription(), "client cancelled event stream");
+    }
+
+    @Test
+    void cancelBeforeBeforeStartCancelsStreamWhenItAttaches_alarmFeedSubscription() {
+        runCancelBeforeBeforeStartTest(
+                new MxGatewayAlarmFeedSubscription(), "client cancelled alarm feed");
+    }
+
+    @Test
+    void cancelBeforeBeforeStartCancelsStreamWhenItAttaches_activeAlarmsSubscription() {
+        runCancelBeforeBeforeStartTest(
+                new MxGatewayActiveAlarmsSubscription(), "client cancelled active-alarms query");
+    }
+
+    @Test
+    void cancelBeforeBeforeStartCancelsStreamWhenItAttaches_deployEventSubscription() {
+        runCancelBeforeBeforeStartTest(
+                new DeployEventSubscription(), "client cancelled deploy event stream");
+    }
+
+    @Test
+    void cancelAfterBeforeStartForwardsToStream_eventSubscription() {
+        runCancelAfterBeforeStartTest(new MxGatewayEventSubscription(), "client cancelled event stream");
+    }
+
+    @Test
+    void cancelAfterBeforeStartForwardsToStream_alarmFeedSubscription() {
+        runCancelAfterBeforeStartTest(
+                new MxGatewayAlarmFeedSubscription(), "client cancelled alarm feed");
+    }
+
+    @Test
+    void cancelAfterBeforeStartForwardsToStream_activeAlarmsSubscription() {
+        runCancelAfterBeforeStartTest(
+                new MxGatewayActiveAlarmsSubscription(), "client cancelled active-alarms query");
+    }
+
+    @Test
+    void cancelAfterBeforeStartForwardsToStream_deployEventSubscription() {
+        runCancelAfterBeforeStartTest(
+                new DeployEventSubscription(), "client cancelled deploy event stream");
+    }
+
+    @Test
+    void closeDelegatesToCancel_eventSubscription() {
+        runCloseDelegatesToCancelTest(new MxGatewayEventSubscription());
+    }
+
+    @Test
+    void closeDelegatesToCancel_alarmFeedSubscription() {
+        runCloseDelegatesToCancelTest(new MxGatewayAlarmFeedSubscription());
+    }
+
+    @Test
+    void closeDelegatesToCancel_activeAlarmsSubscription() {
+        runCloseDelegatesToCancelTest(new MxGatewayActiveAlarmsSubscription());
+    }
+
+    @Test
+    void closeDelegatesToCancel_deployEventSubscription() {
+        runCloseDelegatesToCancelTest(new DeployEventSubscription());
+    }
+
+    @Test
+    void wrappedObserverForwardsOnNextOnErrorOnCompleted_eventSubscription() {
+        MxEvent event = MxEvent.newBuilder().setWorkerSequence(7L).build();
+        runForwardingTest(new MxGatewayEventSubscription(), event);
+    }
+
+    @Test
+    void wrappedObserverForwardsOnNextOnErrorOnCompleted_alarmFeedSubscription() {
+        AlarmFeedMessage msg = AlarmFeedMessage.newBuilder().setSnapshotComplete(true).build();
+        runForwardingTest(new MxGatewayAlarmFeedSubscription(), msg);
+    }
+
+    @Test
+    void wrappedObserverForwardsOnNextOnErrorOnCompleted_activeAlarmsSubscription() {
+        ActiveAlarmSnapshot snap = ActiveAlarmSnapshot.newBuilder()
+                .setAlarmFullReference("ref")
+                .setSeverity(500)
+                .build();
+        runForwardingTest(new MxGatewayActiveAlarmsSubscription(), snap);
+    }
+
+    @Test
+    void wrappedObserverForwardsOnNextOnErrorOnCompleted_deployEventSubscription() {
+        DeployEvent ev = DeployEvent.newBuilder().setSequence(1L).build();
+        runForwardingTest(new DeployEventSubscription(), ev);
+    }
+
+    private static <Req, Resp> void runCancelBeforeBeforeStartTest(
+            MxGatewayStreamSubscription<Req, Resp> subscription, String expectedMessage) {
+        ClientResponseObserver<Req, Resp> wrapped = subscription.wrap(new NoopObserver<>());
+        RecordingClientCallStreamObserver<Req> stream = new RecordingClientCallStreamObserver<>();
+
+        subscription.cancel();
+        wrapped.beforeStart(stream);
+
+        assertTrue(stream.cancelled, "stream should have been cancelled by beforeStart after prior cancel()");
+        assertEquals(expectedMessage, stream.cancelMessage);
+    }
+
+    private static <Req, Resp> void runCancelAfterBeforeStartTest(
+            MxGatewayStreamSubscription<Req, Resp> subscription, String expectedMessage) {
+        ClientResponseObserver<Req, Resp> wrapped = subscription.wrap(new NoopObserver<>());
+        RecordingClientCallStreamObserver<Req> stream = new RecordingClientCallStreamObserver<>();
+
+        wrapped.beforeStart(stream);
+        assertFalse(stream.cancelled, "stream should not be cancelled before cancel() is called");
+        subscription.cancel();
+
+        assertTrue(stream.cancelled, "stream should have been cancelled by direct cancel()");
+        assertEquals(expectedMessage, stream.cancelMessage);
+    }
+
+    private static <Req, Resp> void runCloseDelegatesToCancelTest(
+            MxGatewayStreamSubscription<Req, Resp> subscription) {
+        ClientResponseObserver<Req, Resp> wrapped = subscription.wrap(new NoopObserver<>());
+        RecordingClientCallStreamObserver<Req> stream = new RecordingClientCallStreamObserver<>();
+
+        wrapped.beforeStart(stream);
+        subscription.close();
+
+        assertTrue(stream.cancelled, "close() should delegate to cancel()");
+    }
+
+    private static <Req, Resp> void runForwardingTest(
+            MxGatewayStreamSubscription<Req, Resp> subscription, Resp value) {
+        List<Resp> received = new ArrayList<>();
+        AtomicReference<Throwable> errorRef = new AtomicReference<>();
+        AtomicReference<Boolean> completed = new AtomicReference<>(false);
+
+        StreamObserver<Resp> caller = new StreamObserver<>() {
+            @Override
+            public void onNext(Resp v) {
+                received.add(v);
+            }
+
+            @Override
+            public void onError(Throwable t) {
+                errorRef.set(t);
+            }
+
+            @Override
+            public void onCompleted() {
+                completed.set(true);
+            }
+        };
+
+        ClientResponseObserver<Req, Resp> wrapped = subscription.wrap(caller);
+        RecordingClientCallStreamObserver<Req> stream = new RecordingClientCallStreamObserver<>();
+        wrapped.beforeStart(stream);
+
+        wrapped.onNext(value);
+        IllegalStateException boom = new IllegalStateException("boom");
+        wrapped.onError(boom);
+        wrapped.onCompleted();
+
+        assertEquals(1, received.size());
+        assertEquals(value, received.get(0));
+        assertNotNull(errorRef.get());
+        assertEquals(boom, errorRef.get());
+        assertTrue(completed.get());
+    }
+
+    private static final class NoopObserver<T> implements StreamObserver<T> {
+        @Override
+        public void onNext(T value) {
+        }
+
+        @Override
+        public void onError(Throwable t) {
+        }
+
+        @Override
+        public void onCompleted() {
+        }
+    }
+
+    private static final class RecordingClientCallStreamObserver<T> extends ClientCallStreamObserver<T> {
+        boolean cancelled;
+        String cancelMessage;
+
+        @Override
+        public boolean isReady() {
+            return true;
+        }
+
+        @Override
+        public void setOnReadyHandler(Runnable onReadyHandler) {
+        }
+
+        @Override
+        public void disableAutoInboundFlowControl() {
+        }
+
+        @Override
+        public void request(int count) {
+        }
+
+        @Override
+        public void setMessageCompression(boolean enable) {
+        }
+
+        @Override
+        public void cancel(String message, Throwable cause) {
+            cancelled = true;
+            cancelMessage = message;
+        }
+
+        @Override
+        public void onNext(T value) {
+        }
+
+        @Override
+        public void onError(Throwable error) {
+        }
+
+        @Override
+        public void onCompleted() {
+        }
+    }
+
+    // Compile-time guarantee that the parameter types still match the
+    // generic bounds — catches a regression where a subclass changes its
+    // request/response types out from under the shared base.
+    @SuppressWarnings("unused")
+    private static void typeBoundsCheck() {
+        MxGatewayStreamSubscription<StreamEventsRequest, MxEvent> a = new MxGatewayEventSubscription();
+        MxGatewayStreamSubscription<StreamAlarmsRequest, AlarmFeedMessage> b = new MxGatewayAlarmFeedSubscription();
+        MxGatewayStreamSubscription<QueryActiveAlarmsRequest, ActiveAlarmSnapshot> c =
+                new MxGatewayActiveAlarmsSubscription();
+        MxGatewayStreamSubscription<WatchDeployEventsRequest, DeployEvent> d = new DeployEventSubscription();
+    }
+}

clients/python/PythonClientDesign.md

@@ -112,6 +112,28 @@ Support:
 - TLS channel with default roots,
 - custom root certificate file.
 
+### Trust posture (trust-on-first-use)
+
+The gateway can serve a self-signed certificate it generates itself (it has no
+PKI). grpc-python exposes no per-channel skip-verify hook, so the client cannot
+"accept any certificate" the way the other clients do. Instead, when the channel
+is not plaintext and neither `ca_file` nor `require_certificate_validation` is
+set, the TLS default is **trust-on-first-use**: the client fetches the server's
+presented certificate once via `ssl.get_server_certificate` (an unverified
+probe), pins it as the channel's only trust root, and — because the generated
+certificate always carries a `localhost` SAN — defaults
+`grpc.ssl_target_name_override` to `localhost` when no `server_name_override` was
+supplied (tolerating dial-by-IP or a hostname mismatch). A failed probe is
+surfaced as a transport error naming the endpoint.
+
+To verify the gateway instead:
+
+- set `ca_file` to verify against a specific CA, or
+- set `require_certificate_validation=True` to verify against the system trust
+  roots.
+
+Both bypass the TOFU path.
+
 ## Streaming
 
 Expose `stream_events` as an async iterator. Canceling the task should cancel

clients/python/README.md

@@ -95,9 +95,87 @@ async with await GatewayClient.connect(
 events available for parity tests. `Session` helpers call the method-specific
 MXAccess commands and preserve raw replies on typed command exceptions.
 
+For alarms, the client exposes `GatewayClient.query_active_alarms` (one-shot
+snapshot), `GatewayClient.stream_alarms` (async generator yielding alarm-feed
+messages from the gateway's central monitor), and
+`GatewayClient.acknowledge_alarm` (ack by alarm reference, optional comment
+and ack target). Cancel the surrounding task or `aclose()` the iterator to
+terminate the stream.
+
 Canceling a Python task cancels the client-side gRPC call or stream wait. It
 does not abort an in-flight MXAccess COM call inside the worker process.
 
+## Write Semantics And Common Pitfalls
+
+These are MXAccess parity behaviors that surprise new callers. The gateway
+forwards them unchanged — it does not paper over them.
+
+### Attributing a write to a user without `authenticate_user`
+
+MXAccess only stamps a plain `write`/`write2` with a Galaxy user id when the
+item carries an active *supervisory* advise. If you are **not** using the
+verified/secured path (`authenticate_user` → `write_secured`/`write_secured2`)
+but still need the write attributed to a user id, you must first advise the
+item supervisory and then pass that user id on the write. Without the
+supervisory advise the `user_id` on a plain write is ignored.
+
+The session exposes `advise`/`unadvise` but not supervisory advise, so send it
+through the generic command channel:
+
+```python
+await session.invoke(
+    pb.MxCommand(
+        kind=pb.MX_COMMAND_KIND_ADVISE_SUPERVISORY,
+        advise_supervisory=pb.AdviseSupervisoryCommand(
+            server_handle=server_handle,
+            item_handle=item_handle,
+        ),
+    )
+)
+
+await session.write(server_handle, item_handle, value, user_id=user_id)
+```
+
+The CLI exposes the same command as `advise-supervisory`, and `write` /
+`write2` take `--user-id`.
+
+### Array writes replace the whole array
+
+A write to an array attribute **replaces the entire array**; it is not an
+element-wise patch. To change a subset of elements, send the full array with
+the unchanged elements included. For example, to change 2 elements of a
+20-element array, build the `MxValue` from all 20 values (the 18 unchanged plus
+the 2 new ones). Sending only the 2 changed values overwrites the attribute
+with a 2-element array.
+
+### Default-fill partial array writes
+
+`Session.write_array_elements` lets you write only the indices you care about.
+The gateway fills every unmentioned position with the type default for the
+declared `element_data_type` (0, `False`, `""`, Unix epoch for timestamps).
+The previous value at those positions is **not** preserved — the gateway expands
+the sparse map to a full array before forwarding the write to MXAccess, so this
+is still a full replacement:
+
+```python
+# Write indices 0 and 5 of a 10-element integer array.
+# Positions 1-4 and 6-9 become 0, not their previous values.
+await session.write_array_elements(
+    server_handle=server_handle,
+    item_handle=item_handle,
+    element_data_type=pb.MX_DATA_TYPE_INTEGER,
+    total_length=10,
+    elements={0: 100, 5: 500},
+)
+```
+
+Bare-name array items (e.g. `Object.ArrayAttr` without an index suffix) added
+via `add_item`, `add_item2`, `add_item_bulk`, or `add_buffered_item`
+auto-normalize to `[]` — they refer to the whole array, not a single element.
+Writes through such handles must cover the full array or use
+`write_array_elements` to supply `total_length` and let the gateway fill
+defaults for the rest.
+
 ## Galaxy Repository Browse
 
 The `GalaxyRepositoryClient` wraps the read-only `GalaxyRepository` gRPC
@@ -131,6 +209,51 @@ The methods return native Python types (`bool`, `datetime | None`, and a
 into the hierarchy without learning the underlying stub class. The
 service requires the `metadata:read` scope on the API key.
 
+### Browsing lazily
+
+For UI trees or OPC UA bridges, use `browse_children_raw` to walk one level at a
+time instead of loading the full hierarchy with `discover_hierarchy`. Pass an
+empty request for root objects; subsequent calls set `parent_gobject_id`,
+`parent_tag_name`, or `parent_contained_path`. Filter fields match
+`DiscoverHierarchy`. Each response pairs `children` with `child_has_children` so
+you know which nodes to expand. Most callers should prefer the higher-level
+`browse()` / `LazyBrowseNode` walker below; `browse_children_raw` is the
+low-level escape hatch for direct page-token control. See
+[Galaxy Repository](../../docs/GalaxyRepository.md#browsechildren) for full
+request and filter semantics.
+
+```python
+from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb2
+
+reply = await galaxy.browse_children_raw(galaxy_pb2.BrowseChildrenRequest())
+for child, has_children in zip(reply.children, reply.child_has_children):
+    print(child.tag_name, "expand=" + str(has_children))
+```
+
+#### High-level walker
+
+For UI trees, the client provides a `LazyBrowseNode` walker that handles
+sibling pagination and the `child_has_children` hint for you:
+
+```python
+async with await GalaxyRepositoryClient.connect(
+    endpoint="localhost:5000",
+    api_key="<gateway-api-key>",
+    plaintext=True,
+) as galaxy:
+    roots = await galaxy.browse()
+    for root in roots:
+        if root.has_children_hint:
+            await root.expand()
+        for child in root.children:
+            kind = "has children" if child.has_children_hint else "leaf"
+            print(f"{child.object.tag_name} ({kind})")
+```
+
+`expand` is idempotent — calling it twice fires only one RPC,
+and is safe under concurrent callers. To refresh after a Galaxy redeploy, call
+`browse` again from the root.
+
 ### Watching deploy events
 
 `GalaxyRepositoryClient.watch_deploy_events` opens a server-streaming
@@ -164,9 +287,33 @@ The method returns an async iterator yielding the generated `DeployEvent`
 proto. Breaking out of the loop, calling `aclose()` on the iterator, or
 cancelling the surrounding task closes the underlying gRPC stream
 cleanly. The streaming RPC requires the same `metadata:read` scope as
-the other Galaxy methods. The CLI does not currently expose a
-streaming `watch-deploy-events` subcommand — use the library API
-directly when subscribing to deploy events from Python.
+the other Galaxy methods.
+
+The CLI exposes the Galaxy Repository RPCs through five subcommands that
+mirror the other clients:
+
+```bash
+mxgw-py galaxy-test-connection --plaintext --json
+mxgw-py galaxy-last-deploy --plaintext --json
+mxgw-py galaxy-discover --plaintext --json
+mxgw-py galaxy-browse --plaintext --json
+mxgw-py galaxy-watch --plaintext --json
+```
+
+`galaxy-watch` is bounded by `--max-events` (default `1`) and `--timeout`
+(seconds) so it always terminates; pass `--last-seen-deploy-time` (an
+ISO-8601 timestamp) to suppress the bootstrap event when it matches the
+current cached deploy time.
+
+`galaxy-browse` wraps the lazy `LazyBrowseNode` walker. Without `--depth`
+it lists only the root objects; `--depth N` eagerly expands `N` further
+levels before printing. Text output is a node count followed by an indented
+tree (`+`/`-` marks the server's has-children hint); `--json` emits nested
+`{..., "hasChildrenHint": bool, "children": [...]}` nodes that match the
+`galaxy-discover` object shape. The `BrowseChildrenRequest` filters are
+exposed as `--category-id` (repeatable), `--template-chain-contains`
+(repeatable), `--tag-name-glob`, `--include-attributes`,
+`--alarm-bearing-only`, and `--historized-only`, all AND-combined.
 
 ## Authentication And TLS
 
@@ -180,6 +327,21 @@ The client supports plaintext channels for local development, TLS with system
 roots, TLS with a custom `ca_file`, and an optional test server name override.
 API keys are redacted from option repr output and CLI error output.
 
+The gateway can auto-generate its own self-signed certificate (it has no PKI).
+grpc-python has no per-channel skip-verify, so the lenient TLS default is
+**trust-on-first-use**: with no `ca_file` and `require_certificate_validation`
+left `False`, the client fetches the gateway's presented certificate once
+(unverified) and pins it for the channel, defaulting the SNI/target-name override
+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. 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
 
 The CLI emits deterministic JSON for automation:
@@ -191,6 +353,8 @@ mxgw-py register --session-id <id> --client-name python-client --json
 mxgw-py add-item --session-id <id> --server-handle 1 --item Object.Attribute --json
 mxgw-py advise --session-id <id> --server-handle 1 --item-handle 2 --json
 mxgw-py stream-events --session-id <id> --max-events 1 --json
+mxgw-py stream-alarms --max-messages 1 --json
+mxgw-py acknowledge-alarm --reference "\\Galaxy\Area001.Pump001.PumpFault" --json
 mxgw-py write --session-id <id> --server-handle 1 --item-handle 2 --type int32 --value 123 --json
 ```
 
@@ -204,6 +368,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:
@@ -216,6 +387,19 @@ $env:MXGATEWAY_TEST_ITEM = 'Object.Attribute'
 mxgw-py smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
 ```
 
+## Installing from the Gitea PyPI Feed
+
+The client publishes to the internal Gitea PyPI feed:
+
+````bash
+pip install \
+    --index-url https://gitea.dohertylan.com/api/packages/dohertj2/pypi/simple/ \
+    zb-mom-ww-mxaccess-gateway-client
+````
+
+If you need authentication (private feed), use `--extra-index-url` and either
+a `~/.netrc` entry or `PIP_INDEX_URL=https://<user>:<token>@gitea.dohertylan.com/...`.
+
 ## Related Documentation
 
 - [Client Packaging](../../docs/ClientPackaging.md)

clients/python/pyproject.toml

@@ -1,11 +1,13 @@
 [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"
-description = "Async Python client scaffold for MXAccess Gateway."
+version = "0.1.2"
+description = "Async Python client for MXAccess Gateway."
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
@@ -13,12 +15,34 @@ dependencies = [
   "grpcio>=1.80,<2",
   "protobuf>=6.33,<7",
 ]
+authors = [
+  { name = "Joseph Doherty" },
+]
+keywords = ["mxaccess", "mxgateway", "grpc", "client", "archestra"]
+classifiers = [
+  "License :: Other/Proprietary License",
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: System :: Distributed Computing",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://gitea.dohertylan.com/dohertj2/mxaccessgw"
+Repository = "https://gitea.dohertylan.com/dohertj2/mxaccessgw"
+Issues = "https://gitea.dohertylan.com/dohertj2/mxaccessgw/issues"
 
 [project.optional-dependencies]
 dev = [
   "grpcio-tools>=1.80,<2",
   "pytest>=9,<10",
   "pytest-asyncio>=1.3,<2",
+  "build>=1.2,<2",
+  "twine>=5,<6",
 ]
 
 [project.scripts]
@@ -31,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/__init__.py

@@ -2,7 +2,7 @@
 
 from .auth import ApiKey, auth_metadata
 from .client import GatewayClient
-from .galaxy import GalaxyRepositoryClient
+from .galaxy import GalaxyRepositoryClient, LazyBrowseNode
 from .generated.galaxy_repository_pb2 import (
     DeployEvent,
     GalaxyAttribute,
@@ -19,19 +19,21 @@ from .errors import (
     MxGatewayTransportError,
     MxGatewayWorkerError,
 )
-from .options import ClientOptions
+from .options import BrowseChildrenOptions, ClientOptions
 from .session import Session
 from .values import MxValueView, from_mx_value, to_mx_value
 from .version import __version__
 
 __all__ = [
     "ApiKey",
+    "BrowseChildrenOptions",
     "ClientOptions",
     "DeployEvent",
     "GalaxyAttribute",
     "GalaxyObject",
     "GalaxyRepositoryClient",
     "GatewayClient",
+    "LazyBrowseNode",
     "MxAccessError",
     "MxGatewayAuthenticationError",
     "MxGatewayAuthorizationError",

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),
@@ -172,6 +176,28 @@ class GatewayClient:
         call = self.raw_stub.QueryActiveAlarms(request, **kwargs)
         return _canceling_active_alarms_iterator(call)
 
+    def stream_alarms(
+        self,
+        request: pb.StreamAlarmsRequest,
+        *,
+        metadata: Sequence[tuple[str, str]] | None = None,
+    ) -> AsyncIterator[pb.AlarmFeedMessage]:
+        """Attach to the gateway's central alarm feed.
+
+        The stream opens with one ``AlarmFeedMessage`` per currently-active
+        alarm (the ConditionRefresh snapshot), then a single
+        ``snapshot_complete``, then a ``transition`` for every subsequent
+        raise / acknowledge / clear. Served by the gateway's always-on alarm
+        monitor — no worker session is opened — so any number of clients may
+        attach. Optionally scoped by alarm-reference prefix
+        (``request.alarm_filter_prefix``).
+        """
+        kwargs: dict[str, Any] = {"metadata": merge_metadata(self.options.api_key, metadata)}
+        if self.options.stream_timeout is not None:
+            kwargs["timeout"] = self.options.stream_timeout
+        call = self.raw_stub.StreamAlarms(request, **kwargs)
+        return _canceling_alarm_feed_iterator(call)
+
     async def _unary(
         self,
         operation: str,
@@ -223,3 +249,15 @@ async def _canceling_active_alarms_iterator(call: Any) -> AsyncIterator[pb.Activ
         cancel = getattr(call, "cancel", None)
         if cancel is not None:
             cancel()
+
+
+async def _canceling_alarm_feed_iterator(call: Any) -> AsyncIterator[pb.AlarmFeedMessage]:
+    try:
+        async for message in call:
+            yield message
+    except grpc.RpcError as error:
+        raise map_rpc_error("stream alarms", error) from error
+    finally:
+        cancel = getattr(call, "cancel", None)
+        if cancel is not None:
+            cancel()

clients/python/src/zb_mom_ww_mxgateway/galaxy.py

@@ -21,9 +21,10 @@ from .auth import merge_metadata
 from .errors import MxGatewayError, map_rpc_error
 from .generated import galaxy_repository_pb2 as galaxy_pb
 from .generated import galaxy_repository_pb2_grpc as galaxy_pb_grpc
-from .options import ClientOptions, create_channel
+from .options import BrowseChildrenOptions, ClientOptions, create_channel
 
 _DISCOVER_HIERARCHY_PAGE_SIZE = 5000
+_BROWSE_CHILDREN_PAGE_SIZE = 500
 
 
 class GalaxyRepositoryClient:
@@ -51,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":
@@ -61,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),
@@ -139,6 +144,89 @@ class GalaxyRepositoryClient:
                 )
             seen_page_tokens.add(page_token)
 
+    async def browse_children_raw(
+        self, request: galaxy_pb.BrowseChildrenRequest
+    ) -> galaxy_pb.BrowseChildrenReply:
+        """Issue one BrowseChildren RPC and return the raw reply.
+
+        Lower-level escape hatch for callers that need direct page-token control
+        or do not want LazyBrowseNode wrapping. Most callers should use
+        :py:meth:`browse` and :py:meth:`LazyBrowseNode.expand` instead.
+        """
+
+        return await self._unary(
+            "browse children",
+            self.raw_stub.BrowseChildren,
+            request,
+        )
+
+    async def browse(
+        self,
+        options: BrowseChildrenOptions | None = None,
+    ) -> list["LazyBrowseNode"]:
+        """Return the root browse nodes for lazy hierarchy traversal.
+
+        Each returned ``LazyBrowseNode`` wraps a Galaxy object whose direct
+        children can be loaded on demand by ``await node.expand()``.
+        """
+
+        effective = options or BrowseChildrenOptions()
+        return [
+            node
+            async for node in self._iter_browse_children(
+                parent_gobject_id=None,
+                options=effective,
+            )
+        ]
+
+    async def _iter_browse_children(
+        self,
+        *,
+        parent_gobject_id: int | None,
+        options: BrowseChildrenOptions,
+    ) -> AsyncIterator["LazyBrowseNode"]:
+        page_token = ""
+        seen_page_tokens: set[str] = set()
+        while True:
+            request = galaxy_pb.BrowseChildrenRequest(
+                page_size=_BROWSE_CHILDREN_PAGE_SIZE,
+                page_token=page_token,
+                alarm_bearing_only=options.alarm_bearing_only,
+                historized_only=options.historized_only,
+            )
+            if parent_gobject_id is not None:
+                request.parent_gobject_id = parent_gobject_id
+            if options.category_ids:
+                request.category_ids.extend(options.category_ids)
+            if options.template_chain_contains:
+                request.template_chain_contains.extend(options.template_chain_contains)
+            if options.tag_name_glob:
+                request.tag_name_glob = options.tag_name_glob
+            if options.include_attributes is not None:
+                request.include_attributes = options.include_attributes
+
+            reply = await self._unary(
+                "browse children",
+                self.raw_stub.BrowseChildren,
+                request,
+            )
+
+            for index, obj in enumerate(reply.children):
+                hint = (
+                    index < len(reply.child_has_children)
+                    and bool(reply.child_has_children[index])
+                )
+                yield LazyBrowseNode(self, obj, hint, options)
+
+            page_token = reply.next_page_token
+            if not page_token:
+                return
+            if page_token in seen_page_tokens:
+                raise MxGatewayError(
+                    f"galaxy browse children returned repeated page token {page_token!r}"
+                )
+            seen_page_tokens.add(page_token)
+
     def watch_deploy_events(
         self,
         last_seen_deploy_time: datetime | None = None,
@@ -202,6 +290,67 @@ class GalaxyRepositoryClient:
             raise map_rpc_error(operation, error) from error
 
 
+class LazyBrowseNode:
+    """One node in a lazy-loaded Galaxy browse tree.
+
+    Calling ``expand`` once fetches direct children (paginating as needed)
+    and populates ``children``. Subsequent calls are no-ops so callers can
+    drive UI expand toggles without de-duping.
+    """
+
+    def __init__(
+        self,
+        client: "GalaxyRepositoryClient",
+        obj: galaxy_pb.GalaxyObject,
+        has_children_hint: bool,
+        options: BrowseChildrenOptions,
+    ) -> None:
+        """Initialize a node bound to its owning client and filter set."""
+        self._client = client
+        self._object = obj
+        self._has_children_hint = has_children_hint
+        self._options = options
+        self._children: list[LazyBrowseNode] = []
+        self._is_expanded = False
+        self._expand_lock = asyncio.Lock()
+
+    @property
+    def object(self) -> galaxy_pb.GalaxyObject:
+        """Return the underlying ``GalaxyObject`` proto for this node."""
+        return self._object
+
+    @property
+    def has_children_hint(self) -> bool:
+        """Return the server hint about whether this node has children."""
+        return self._has_children_hint
+
+    @property
+    def children(self) -> list["LazyBrowseNode"]:
+        """Return a copy of the loaded child nodes (empty until expanded)."""
+        return list(self._children)
+
+    @property
+    def is_expanded(self) -> bool:
+        """Return whether ``expand`` has already populated ``children``."""
+        return self._is_expanded
+
+    async def expand(self) -> None:
+        """Fetch direct children of this node; no-op on subsequent calls."""
+        if self._is_expanded:
+            return
+        async with self._expand_lock:
+            if self._is_expanded:
+                return
+            new_children: list[LazyBrowseNode] = []
+            async for child in self._client._iter_browse_children(
+                parent_gobject_id=self._object.gobject_id,
+                options=self._options,
+            ):
+                new_children.append(child)
+            self._children.extend(new_children)
+            self._is_expanded = True
+
+
 async def _canceling_iterator(call: Any) -> AsyncIterator[galaxy_pb.DeployEvent]:
     try:
         async for event in call:

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

@@ -26,7 +26,7 @@ from google.protobuf import timestamp_pb2 as google_dot_protobuf_dot_timestamp__
 from google.protobuf import wrappers_pb2 as google_dot_protobuf_dot_wrappers__pb2
 
 
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x17galaxy_repository.proto\x12\x14galaxy_repository.v1\x1a\x1fgoogle/protobuf/timestamp.proto\x1a\x1egoogle/protobuf/wrappers.proto\"\x17\n\x15TestConnectionRequest\"!\n\x13TestConnectionReply\x12\n\n\x02ok\x18\x01 \x01(\x08\"\x1a\n\x18GetLastDeployTimeRequest\"b\n\x16GetLastDeployTimeReply\x12\x0f\n\x07present\x18\x01 \x01(\x08\x12\x37\n\x13time_of_last_deploy\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"\x87\x03\n\x18\x44iscoverHierarchyRequest\x12\x11\n\tpage_size\x18\x01 \x01(\x05\x12\x12\n\npage_token\x18\x02 \x01(\t\x12\x19\n\x0froot_gobject_id\x18\x03 \x01(\x05H\x00\x12\x17\n\rroot_tag_name\x18\x04 \x01(\tH\x00\x12\x1d\n\x13root_contained_path\x18\x05 \x01(\tH\x00\x12.\n\tmax_depth\x18\x06 \x01(\x0b\x32\x1b.google.protobuf.Int32Value\x12\x14\n\x0c\x63\x61tegory_ids\x18\x07 \x03(\x05\x12\x1f\n\x17template_chain_contains\x18\x08 \x03(\t\x12\x15\n\rtag_name_glob\x18\t \x01(\t\x12\x1f\n\x12include_attributes\x18\n \x01(\x08H\x01\x88\x01\x01\x12\x1a\n\x12\x61larm_bearing_only\x18\x0b \x01(\x08\x12\x17\n\x0fhistorized_only\x18\x0c \x01(\x08\x42\x06\n\x04rootB\x15\n\x13_include_attributes\"\x82\x01\n\x16\x44iscoverHierarchyReply\x12\x33\n\x07objects\x18\x01 \x03(\x0b\x32\".galaxy_repository.v1.GalaxyObject\x12\x17\n\x0fnext_page_token\x18\x02 \x01(\t\x12\x1a\n\x12total_object_count\x18\x03 \x01(\x05\"U\n\x18WatchDeployEventsRequest\x12\x39\n\x15last_seen_deploy_time\x18\x01 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"\xdd\x01\n\x0b\x44\x65ployEvent\x12\x10\n\x08sequence\x18\x01 \x01(\x04\x12/\n\x0bobserved_at\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12\x37\n\x13time_of_last_deploy\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12#\n\x1btime_of_last_deploy_present\x18\x04 \x01(\x08\x12\x14\n\x0cobject_count\x18\x05 \x01(\x05\x12\x17\n\x0f\x61ttribute_count\x18\x06 \x01(\x05\"\x93\x02\n\x0cGalaxyObject\x12\x12\n\ngobject_id\x18\x01 \x01(\x05\x12\x10\n\x08tag_name\x18\x02 \x01(\t\x12\x16\n\x0e\x63ontained_name\x18\x03 \x01(\t\x12\x13\n\x0b\x62rowse_name\x18\x04 \x01(\t\x12\x19\n\x11parent_gobject_id\x18\x05 \x01(\x05\x12\x0f\n\x07is_area\x18\x06 \x01(\x08\x12\x13\n\x0b\x63\x61tegory_id\x18\x07 \x01(\x05\x12\x1c\n\x14hosted_by_gobject_id\x18\x08 \x01(\x05\x12\x16\n\x0etemplate_chain\x18\t \x03(\t\x12\x39\n\nattributes\x18\n \x03(\x0b\x32%.galaxy_repository.v1.GalaxyAttribute\"\xa8\x02\n\x0fGalaxyAttribute\x12\x16\n\x0e\x61ttribute_name\x18\x01 \x01(\t\x12\x1a\n\x12\x66ull_tag_reference\x18\x02 \x01(\t\x12\x14\n\x0cmx_data_type\x18\x03 \x01(\x05\x12\x16\n\x0e\x64\x61ta_type_name\x18\x04 \x01(\t\x12\x10\n\x08is_array\x18\x05 \x01(\x08\x12\x17\n\x0f\x61rray_dimension\x18\x06 \x01(\x05\x12\x1f\n\x17\x61rray_dimension_present\x18\x07 \x01(\x08\x12\x1d\n\x15mx_attribute_category\x18\x08 \x01(\x05\x12\x1f\n\x17security_classification\x18\t \x01(\x05\x12\x15\n\ris_historized\x18\n \x01(\x08\x12\x10\n\x08is_alarm\x18\x0b \x01(\x08\x32\xcc\x03\n\x10GalaxyRepository\x12h\n\x0eTestConnection\x12+.galaxy_repository.v1.TestConnectionRequest\x1a).galaxy_repository.v1.TestConnectionReply\x12q\n\x11GetLastDeployTime\x12..galaxy_repository.v1.GetLastDeployTimeRequest\x1a,.galaxy_repository.v1.GetLastDeployTimeReply\x12q\n\x11\x44iscoverHierarchy\x12..galaxy_repository.v1.DiscoverHierarchyRequest\x1a,.galaxy_repository.v1.DiscoverHierarchyReply\x12h\n\x11WatchDeployEvents\x12..galaxy_repository.v1.WatchDeployEventsRequest\x1a!.galaxy_repository.v1.DeployEvent0\x01\x42-\xaa\x02*ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxyb\x06proto3')
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x17galaxy_repository.proto\x12\x14galaxy_repository.v1\x1a\x1fgoogle/protobuf/timestamp.proto\x1a\x1egoogle/protobuf/wrappers.proto\"\x17\n\x15TestConnectionRequest\"!\n\x13TestConnectionReply\x12\n\n\x02ok\x18\x01 \x01(\x08\"\x1a\n\x18GetLastDeployTimeRequest\"b\n\x16GetLastDeployTimeReply\x12\x0f\n\x07present\x18\x01 \x01(\x08\x12\x37\n\x13time_of_last_deploy\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"\x87\x03\n\x18\x44iscoverHierarchyRequest\x12\x11\n\tpage_size\x18\x01 \x01(\x05\x12\x12\n\npage_token\x18\x02 \x01(\t\x12\x19\n\x0froot_gobject_id\x18\x03 \x01(\x05H\x00\x12\x17\n\rroot_tag_name\x18\x04 \x01(\tH\x00\x12\x1d\n\x13root_contained_path\x18\x05 \x01(\tH\x00\x12.\n\tmax_depth\x18\x06 \x01(\x0b\x32\x1b.google.protobuf.Int32Value\x12\x14\n\x0c\x63\x61tegory_ids\x18\x07 \x03(\x05\x12\x1f\n\x17template_chain_contains\x18\x08 \x03(\t\x12\x15\n\rtag_name_glob\x18\t \x01(\t\x12\x1f\n\x12include_attributes\x18\n \x01(\x08H\x01\x88\x01\x01\x12\x1a\n\x12\x61larm_bearing_only\x18\x0b \x01(\x08\x12\x17\n\x0fhistorized_only\x18\x0c \x01(\x08\x42\x06\n\x04rootB\x15\n\x13_include_attributes\"\x82\x01\n\x16\x44iscoverHierarchyReply\x12\x33\n\x07objects\x18\x01 \x03(\x0b\x32\".galaxy_repository.v1.GalaxyObject\x12\x17\n\x0fnext_page_token\x18\x02 \x01(\t\x12\x1a\n\x12total_object_count\x18\x03 \x01(\x05\"U\n\x18WatchDeployEventsRequest\x12\x39\n\x15last_seen_deploy_time\x18\x01 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"\xdd\x01\n\x0b\x44\x65ployEvent\x12\x10\n\x08sequence\x18\x01 \x01(\x04\x12/\n\x0bobserved_at\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12\x37\n\x13time_of_last_deploy\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12#\n\x1btime_of_last_deploy_present\x18\x04 \x01(\x08\x12\x14\n\x0cobject_count\x18\x05 \x01(\x05\x12\x17\n\x0f\x61ttribute_count\x18\x06 \x01(\x05\"\x93\x02\n\x0cGalaxyObject\x12\x12\n\ngobject_id\x18\x01 \x01(\x05\x12\x10\n\x08tag_name\x18\x02 \x01(\t\x12\x16\n\x0e\x63ontained_name\x18\x03 \x01(\t\x12\x13\n\x0b\x62rowse_name\x18\x04 \x01(\t\x12\x19\n\x11parent_gobject_id\x18\x05 \x01(\x05\x12\x0f\n\x07is_area\x18\x06 \x01(\x08\x12\x13\n\x0b\x63\x61tegory_id\x18\x07 \x01(\x05\x12\x1c\n\x14hosted_by_gobject_id\x18\x08 \x01(\x05\x12\x16\n\x0etemplate_chain\x18\t \x03(\t\x12\x39\n\nattributes\x18\n \x03(\x0b\x32%.galaxy_repository.v1.GalaxyAttribute\"\xa8\x02\n\x0fGalaxyAttribute\x12\x16\n\x0e\x61ttribute_name\x18\x01 \x01(\t\x12\x1a\n\x12\x66ull_tag_reference\x18\x02 \x01(\t\x12\x14\n\x0cmx_data_type\x18\x03 \x01(\x05\x12\x16\n\x0e\x64\x61ta_type_name\x18\x04 \x01(\t\x12\x10\n\x08is_array\x18\x05 \x01(\x08\x12\x17\n\x0f\x61rray_dimension\x18\x06 \x01(\x05\x12\x1f\n\x17\x61rray_dimension_present\x18\x07 \x01(\x08\x12\x1d\n\x15mx_attribute_category\x18\x08 \x01(\x05\x12\x1f\n\x17security_classification\x18\t \x01(\x05\x12\x15\n\ris_historized\x18\n \x01(\x08\x12\x10\n\x08is_alarm\x18\x0b \x01(\x08\"\xdc\x02\n\x15\x42rowseChildrenRequest\x12\x1b\n\x11parent_gobject_id\x18\x01 \x01(\x05H\x00\x12\x19\n\x0fparent_tag_name\x18\x02 \x01(\tH\x00\x12\x1f\n\x15parent_contained_path\x18\x03 \x01(\tH\x00\x12\x11\n\tpage_size\x18\x04 \x01(\x05\x12\x12\n\npage_token\x18\x05 \x01(\t\x12\x14\n\x0c\x63\x61tegory_ids\x18\x06 \x03(\x05\x12\x1f\n\x17template_chain_contains\x18\x07 \x03(\t\x12\x15\n\rtag_name_glob\x18\x08 \x01(\t\x12\x1f\n\x12include_attributes\x18\t \x01(\x08H\x01\x88\x01\x01\x12\x1a\n\x12\x61larm_bearing_only\x18\n \x01(\x08\x12\x17\n\x0fhistorized_only\x18\x0b \x01(\x08\x42\x08\n\x06parentB\x15\n\x13_include_attributes\"\xb3\x01\n\x13\x42rowseChildrenReply\x12\x34\n\x08\x63hildren\x18\x01 \x03(\x0b\x32\".galaxy_repository.v1.GalaxyObject\x12\x17\n\x0fnext_page_token\x18\x02 \x01(\t\x12\x19\n\x11total_child_count\x18\x03 \x01(\x05\x12\x1a\n\x12\x63hild_has_children\x18\x04 \x03(\x08\x12\x16\n\x0e\x63\x61\x63he_sequence\x18\x05 \x01(\x04\x32\xb6\x04\n\x10GalaxyRepository\x12h\n\x0eTestConnection\x12+.galaxy_repository.v1.TestConnectionRequest\x1a).galaxy_repository.v1.TestConnectionReply\x12q\n\x11GetLastDeployTime\x12..galaxy_repository.v1.GetLastDeployTimeRequest\x1a,.galaxy_repository.v1.GetLastDeployTimeReply\x12q\n\x11\x44iscoverHierarchy\x12..galaxy_repository.v1.DiscoverHierarchyRequest\x1a,.galaxy_repository.v1.DiscoverHierarchyReply\x12h\n\x11WatchDeployEvents\x12..galaxy_repository.v1.WatchDeployEventsRequest\x1a!.galaxy_repository.v1.DeployEvent0\x01\x12h\n\x0e\x42rowseChildren\x12+.galaxy_repository.v1.BrowseChildrenRequest\x1a).galaxy_repository.v1.BrowseChildrenReplyB-\xaa\x02*ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxyb\x06proto3')
 
 _globals = globals()
 _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
@@ -54,6 +54,10 @@ if not _descriptor._USE_C_DESCRIPTORS:
   _globals['_GALAXYOBJECT']._serialized_end=1416
   _globals['_GALAXYATTRIBUTE']._serialized_start=1419
   _globals['_GALAXYATTRIBUTE']._serialized_end=1715
-  _globals['_GALAXYREPOSITORY']._serialized_start=1718
-  _globals['_GALAXYREPOSITORY']._serialized_end=2178
+  _globals['_BROWSECHILDRENREQUEST']._serialized_start=1718
+  _globals['_BROWSECHILDRENREQUEST']._serialized_end=2066
+  _globals['_BROWSECHILDRENREPLY']._serialized_start=2069
+  _globals['_BROWSECHILDRENREPLY']._serialized_end=2248
+  _globals['_GALAXYREPOSITORY']._serialized_start=2251
+  _globals['_GALAXYREPOSITORY']._serialized_end=2817
 # @@protoc_insertion_point(module_scope)

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

@@ -65,6 +65,11 @@ class GalaxyRepositoryStub(object):
                 request_serializer=galaxy__repository__pb2.WatchDeployEventsRequest.SerializeToString,
                 response_deserializer=galaxy__repository__pb2.DeployEvent.FromString,
                 _registered_method=True)
+        self.BrowseChildren = channel.unary_unary(
+                '/galaxy_repository.v1.GalaxyRepository/BrowseChildren',
+                request_serializer=galaxy__repository__pb2.BrowseChildrenRequest.SerializeToString,
+                response_deserializer=galaxy__repository__pb2.BrowseChildrenReply.FromString,
+                _registered_method=True)
 
 
 class GalaxyRepositoryServicer(object):
@@ -111,6 +116,16 @@ class GalaxyRepositoryServicer(object):
         context.set_details('Method not implemented!')
         raise NotImplementedError('Method not implemented!')
 
+    def BrowseChildren(self, request, context):
+        """Returns the direct children of a parent object (or the root objects when
+        `parent` is unset). Designed for OPC UA-style lazy expand: clients walk
+        one level at a time instead of paging the full hierarchy. Filters mirror
+        DiscoverHierarchy exactly. Backed by the same shared hierarchy cache.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
 
 def add_GalaxyRepositoryServicer_to_server(servicer, server):
     rpc_method_handlers = {
@@ -134,6 +149,11 @@ def add_GalaxyRepositoryServicer_to_server(servicer, server):
                     request_deserializer=galaxy__repository__pb2.WatchDeployEventsRequest.FromString,
                     response_serializer=galaxy__repository__pb2.DeployEvent.SerializeToString,
             ),
+            'BrowseChildren': grpc.unary_unary_rpc_method_handler(
+                    servicer.BrowseChildren,
+                    request_deserializer=galaxy__repository__pb2.BrowseChildrenRequest.FromString,
+                    response_serializer=galaxy__repository__pb2.BrowseChildrenReply.SerializeToString,
+            ),
     }
     generic_handler = grpc.method_handlers_generic_handler(
             'galaxy_repository.v1.GalaxyRepository', rpc_method_handlers)
@@ -263,3 +283,30 @@ class GalaxyRepository(object):
             timeout,
             metadata,
             _registered_method=True)
+
+    @staticmethod
+    def BrowseChildren(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/galaxy_repository.v1.GalaxyRepository/BrowseChildren',
+            galaxy__repository__pb2.BrowseChildrenRequest.SerializeToString,
+            galaxy__repository__pb2.BrowseChildrenReply.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

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

@@ -135,6 +135,9 @@ class MxAccessGatewayServicer(object):
         reconnect to seed Part 9 client state, or to reconcile alarms that may
         have been missed during a transport blip. Streamed so callers can
         begin processing without buffering the full set.
+        `QueryActiveAlarmsRequest.alarm_filter_prefix` optionally narrows the
+        snapshot to alarms whose `alarm_full_reference` starts with the given
+        prefix; an empty prefix returns the full set.
         """
         context.set_code(grpc.StatusCode.UNIMPLEMENTED)
         context.set_details('Method not implemented!')

clients/python/src/zb_mom_ww_mxgateway/options.py

@@ -2,12 +2,19 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+import ssl
+from collections.abc import Sequence
+from dataclasses import dataclass, field
 from pathlib import Path
 
 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)
@@ -18,6 +25,7 @@ class ClientOptions:
     api_key: str | ApiKey | None = None
     plaintext: bool = False
     ca_file: str | None = None
+    require_certificate_validation: bool = False
     server_name_override: str | None = None
     call_timeout: float | None = 30.0
     stream_timeout: float | None = None
@@ -44,6 +52,7 @@ class ClientOptions:
             f"{type(self).__name__}(endpoint={self.endpoint!r}, "
             f"api_key={api_key!r}, plaintext={self.plaintext!r}, "
             f"ca_file={self.ca_file!r}, "
+            f"require_certificate_validation={self.require_certificate_validation!r}, "
             f"server_name_override={self.server_name_override!r}, "
             f"call_timeout={self.call_timeout!r}, "
             f"stream_timeout={self.stream_timeout!r}, "
@@ -51,8 +60,60 @@ class ClientOptions:
         )
 
 
+@dataclass(frozen=True)
+class BrowseChildrenOptions:
+    """Filters and shape options for ``GalaxyRepositoryClient.browse``.
+
+    Mirrors the AND-combined filter set on ``BrowseChildrenRequest`` so a
+    single instance can be re-used across an entire lazy browse session
+    (the filter set is part of the page-token contract).
+    """
+
+    category_ids: Sequence[int] = field(default_factory=tuple)
+    template_chain_contains: Sequence[str] = field(default_factory=tuple)
+    tag_name_glob: str | None = None
+    include_attributes: bool | None = None
+    alarm_bearing_only: bool = False
+    historized_only: bool = False
+
+
+def _split_authority(endpoint: str) -> tuple[str, int]:
+    """Split a gRPC target (optionally scheme-prefixed) into (host, port).
+
+    Handles bracketed IPv6 literals (e.g. ``[::1]:5120`` or bare ``[::1]``),
+    returning the host without brackets so it is safe to pass to
+    ``ssl.get_server_certificate``.
+    """
+    target = endpoint.split("://", 1)[-1]
+    if target.startswith("["):
+        # Bracketed IPv6: "[::1]:5120" or "[::1]"
+        bracket_end = target.find("]")
+        host = target[1:bracket_end]  # strip surrounding brackets
+        remainder = target[bracket_end + 1 :]  # ":5120" or ""
+        port_str = remainder.lstrip(":")
+        return (host, int(port_str) if port_str 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:
-    """Create a plaintext or TLS `grpc.aio` channel from client options."""
+    """Create a plaintext or TLS `grpc.aio` channel from client options.
+
+    The TLS default is lenient: grpc-python has no per-channel skip-verify, so
+    the server's presented certificate is fetched once (unverified) and pinned
+    as the channel's only trust root (trust-on-first-use). Set
+    `require_certificate_validation=True` to force system-trust verification, or
+    pass `ca_file` to verify against a specific CA — both bypass the TOFU path.
+    """
 
     channel_options: list[tuple[str, str | int]] = [
         ("grpc.max_receive_message_length", options.max_grpc_message_bytes),
@@ -64,11 +125,34 @@ def create_channel(options: ClientOptions) -> grpc.aio.Channel:
     if options.plaintext:
         return grpc.aio.insecure_channel(options.endpoint, options=channel_options)
 
-    root_certificates = None
     if options.ca_file:
         root_certificates = Path(options.ca_file).read_bytes()
+        credentials = grpc.ssl_channel_credentials(root_certificates=root_certificates)
+    elif options.require_certificate_validation:
+        credentials = grpc.ssl_channel_credentials()
+    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), timeout=probe_timeout)
+        except OSError as error:
+            raise MxGatewayTransportError(
+                f"failed to fetch TLS certificate from {options.endpoint}: {error}"
+            ) from error
+        credentials = grpc.ssl_channel_credentials(root_certificates=presented.encode("ascii"))
+        # The gateway self-signed cert always carries a "localhost" SAN, so default
+        # the SNI/target-name override to it when none was supplied, tolerating
+        # dial-by-IP or hostname mismatch.
+        if not options.server_name_override:
+            channel_options.append(("grpc.ssl_target_name_override", "localhost"))
 
-    credentials = grpc.ssl_channel_credentials(root_certificates=root_certificates)
     return grpc.aio.secure_channel(
         options.endpoint,
         credentials,

clients/python/src/zb_mom_ww_mxgateway/session.py

@@ -334,6 +334,138 @@ class Session:
         )
         return list(reply.unsubscribe_bulk.results)
 
+    async def write_bulk(
+        self,
+        server_handle: int,
+        entries: Sequence[pb.WriteBulkEntry],
+        *,
+        correlation_id: str = "",
+    ) -> list[pb.BulkWriteResult]:
+        """Invoke MXAccess `WriteBulk` and return one BulkWriteResult per entry.
+
+        Per-entry MXAccess failures appear as results with ``was_successful = False``
+        and a populated ``error_message`` / ``hresult``; this method does not raise
+        on per-entry failure, mirroring the existing add/advise bulk surface.
+        """
+        if entries is None:
+            raise TypeError("entries is required")
+        _ensure_bulk_size("entries", len(entries))
+        reply = await self.invoke(
+            pb.MxCommand(
+                kind=pb.MX_COMMAND_KIND_WRITE_BULK,
+                write_bulk=pb.WriteBulkCommand(
+                    server_handle=server_handle,
+                    entries=entries,
+                ),
+            ),
+            correlation_id=correlation_id,
+        )
+        return list(reply.write_bulk.results)
+
+    async def write2_bulk(
+        self,
+        server_handle: int,
+        entries: Sequence[pb.Write2BulkEntry],
+        *,
+        correlation_id: str = "",
+    ) -> list[pb.BulkWriteResult]:
+        """Invoke MXAccess `Write2Bulk` (timestamped) and return per-entry results."""
+        if entries is None:
+            raise TypeError("entries is required")
+        _ensure_bulk_size("entries", len(entries))
+        reply = await self.invoke(
+            pb.MxCommand(
+                kind=pb.MX_COMMAND_KIND_WRITE2_BULK,
+                write2_bulk=pb.Write2BulkCommand(
+                    server_handle=server_handle,
+                    entries=entries,
+                ),
+            ),
+            correlation_id=correlation_id,
+        )
+        return list(reply.write2_bulk.results)
+
+    async def write_secured_bulk(
+        self,
+        server_handle: int,
+        entries: Sequence[pb.WriteSecuredBulkEntry],
+        *,
+        correlation_id: str = "",
+    ) -> list[pb.BulkWriteResult]:
+        """Invoke MXAccess `WriteSecuredBulk` — credential-sensitive values must not be logged."""
+        if entries is None:
+            raise TypeError("entries is required")
+        _ensure_bulk_size("entries", len(entries))
+        reply = await self.invoke(
+            pb.MxCommand(
+                kind=pb.MX_COMMAND_KIND_WRITE_SECURED_BULK,
+                write_secured_bulk=pb.WriteSecuredBulkCommand(
+                    server_handle=server_handle,
+                    entries=entries,
+                ),
+            ),
+            correlation_id=correlation_id,
+        )
+        return list(reply.write_secured_bulk.results)
+
+    async def write_secured2_bulk(
+        self,
+        server_handle: int,
+        entries: Sequence[pb.WriteSecured2BulkEntry],
+        *,
+        correlation_id: str = "",
+    ) -> list[pb.BulkWriteResult]:
+        """Invoke MXAccess `WriteSecured2Bulk` (timestamped + verified)."""
+        if entries is None:
+            raise TypeError("entries is required")
+        _ensure_bulk_size("entries", len(entries))
+        reply = await self.invoke(
+            pb.MxCommand(
+                kind=pb.MX_COMMAND_KIND_WRITE_SECURED2_BULK,
+                write_secured2_bulk=pb.WriteSecured2BulkCommand(
+                    server_handle=server_handle,
+                    entries=entries,
+                ),
+            ),
+            correlation_id=correlation_id,
+        )
+        return list(reply.write_secured2_bulk.results)
+
+    async def read_bulk(
+        self,
+        server_handle: int,
+        tag_addresses: Sequence[str],
+        *,
+        timeout_ms: int = 0,
+        correlation_id: str = "",
+    ) -> list[pb.BulkReadResult]:
+        """Invoke `ReadBulk` — snapshot the current value of each requested tag.
+
+        MXAccess COM has no synchronous read; the worker returns the cached
+        ``OnDataChange`` value for any tag that is already advised (``was_cached =
+        True``) without modifying the existing subscription, and falls back to
+        a full AddItem + Advise + wait + UnAdvise + RemoveItem snapshot lifecycle
+        otherwise. ``timeout_ms`` bounds the per-tag wait in the snapshot case;
+        pass ``0`` to use the worker default (1000 ms).
+        """
+        if tag_addresses is None:
+            raise TypeError("tag_addresses is required")
+        _ensure_bulk_size("tag_addresses", len(tag_addresses))
+        if timeout_ms < 0:
+            raise ValueError("timeout_ms must be non-negative")
+        reply = await self.invoke(
+            pb.MxCommand(
+                kind=pb.MX_COMMAND_KIND_READ_BULK,
+                read_bulk=pb.ReadBulkCommand(
+                    server_handle=server_handle,
+                    tag_addresses=tag_addresses,
+                    timeout_ms=timeout_ms,
+                ),
+            ),
+            correlation_id=correlation_id,
+        )
+        return list(reply.read_bulk.results)
+
     async def write(
         self,
         server_handle: int,
@@ -357,6 +489,60 @@ class Session:
             correlation_id=correlation_id,
         )
 
+    async def write_array_elements(
+        self,
+        server_handle: int,
+        item_handle: int,
+        element_data_type: "pb.MxDataType.ValueType",
+        total_length: int,
+        elements: dict[int, MxValueInput],
+        *,
+        user_id: int = 0,
+        correlation_id: str = "",
+    ) -> None:
+        """Write a partial array by specifying only the indices you want to set.
+
+        The gateway expands the sparse representation into a full ``total_length``
+        array before forwarding the write to MXAccess.  Indices not listed in
+        *elements* are filled with the type default for *element_data_type* (0,
+        False, empty string, Unix epoch for timestamps, etc.).  The previous
+        value at those positions is **not** preserved — this is a full array
+        replacement, not a patch.
+
+        Args:
+            server_handle: Handle returned by :meth:`register`.
+            item_handle: Handle returned by :meth:`add_item`.
+            element_data_type: ``pb.MX_DATA_TYPE_*`` enum value for the scalar
+                element type of the target array attribute.
+            total_length: Total number of elements in the written array.  Must
+                be > 0 and large enough to contain every index in *elements*.
+                Both *total_length* and all keys in *elements* must be
+                non-negative; the gateway rejects negative or out-of-range
+                values with ``InvalidArgument`` (the proto fields are
+                ``uint32``).
+            elements: Mapping of zero-based element index to scalar value.
+                Values are converted with :func:`~zb_mom_ww_mxgateway.values.to_mx_value`.
+            user_id: Galaxy user id to stamp on the write (requires a prior
+                supervisory advise to take effect — see README).
+            correlation_id: Optional client-supplied correlation token echoed
+                in the command reply.
+        """
+        sparse = pb.MxSparseArray(
+            element_data_type=element_data_type,
+            total_length=total_length,
+            elements=[
+                pb.MxSparseElement(index=idx, value=to_mx_value(val))
+                for idx, val in elements.items()
+            ],
+        )
+        await self.write(
+            server_handle,
+            item_handle,
+            pb.MxValue(sparse_array_value=sparse),
+            user_id=user_id,
+            correlation_id=correlation_id,
+        )
+
     async def write2(
         self,
         server_handle: int,

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
 
 
@@ -72,27 +75,85 @@ def test_create_channel_uses_plaintext_channel(monkeypatch: pytest.MonkeyPatch)
     ]
 
 
-def test_create_channel_uses_tls_channel(monkeypatch: pytest.MonkeyPatch) -> None:
-    calls: list[tuple[str, object, object]] = []
+def test_create_channel_uses_tls_channel_tofu_default(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Default TLS (no ca_file, no require_certificate_validation) uses TOFU:
+    fetches the server cert unverified, pins it as root_certificates, and adds
+    grpc.ssl_target_name_override = "localhost" automatically.
+    """
+    _DUMMY_PEM = "-----BEGIN CERTIFICATE-----\nZmFrZQ==\n-----END CERTIFICATE-----\n"
+    get_cert_calls: list[tuple[str, int]] = []
 
-    def fake_credentials(*, root_certificates: object) -> str:
-        assert root_certificates is None
+    def fake_get_server_certificate(
+        addr: tuple[str, int], *, timeout: float | None = None
+    ) -> str:
+        get_cert_calls.append(addr)
+        return _DUMMY_PEM
+
+    cred_calls: list[object] = []
+
+    def fake_credentials(*, root_certificates: object = None) -> str:
+        cred_calls.append(root_certificates)
         return "creds"
 
+    channel_calls: list[tuple[str, object, object]] = []
+
     def fake_secure_channel(endpoint: str, credentials: object, *, options: object) -> str:
-        calls.append((endpoint, credentials, options))
+        channel_calls.append((endpoint, credentials, options))
         return "tls-channel"
 
-    monkeypatch.setattr(
-        options_module.grpc,
-        "ssl_channel_credentials",
-        fake_credentials,
+    monkeypatch.setattr(options_module.ssl, "get_server_certificate", fake_get_server_certificate)
+    monkeypatch.setattr(options_module.grpc, "ssl_channel_credentials", fake_credentials)
+    monkeypatch.setattr(options_module.grpc.aio, "secure_channel", fake_secure_channel)
+
+    channel = create_channel(
+        ClientOptions(endpoint="gateway.example:5001"),
     )
+
+    assert channel == "tls-channel"
+    # TOFU: should have fetched the cert from the server (host, port)
+    assert get_cert_calls == [("gateway.example", 5001)]
+    # Pinned the fetched PEM bytes as root_certificates
+    assert cred_calls == [_DUMMY_PEM.encode("ascii")]
+    # Auto-injected localhost override (no server_name_override supplied)
+    assert channel_calls == [
+        (
+            "gateway.example:5001",
+            "creds",
+            [
+                ("grpc.max_receive_message_length", 16 * 1024 * 1024),
+                ("grpc.max_send_message_length", 16 * 1024 * 1024),
+                ("grpc.ssl_target_name_override", "localhost"),
+            ],
+        ),
+    ]
+
+
+def test_create_channel_uses_tls_channel_tofu_respects_server_name_override(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """When server_name_override is set, TOFU still runs but does NOT add the
+    auto-localhost override (the explicit override is already in channel_options).
+    """
+    _DUMMY_PEM = "-----BEGIN CERTIFICATE-----\nZmFrZQ==\n-----END CERTIFICATE-----\n"
     monkeypatch.setattr(
-        options_module.grpc.aio,
-        "secure_channel",
-        fake_secure_channel,
+        options_module.ssl,
+        "get_server_certificate",
+        lambda addr, *, timeout=None: _DUMMY_PEM,
     )
+    cred_calls: list[object] = []
+
+    def fake_credentials(*, root_certificates: object = None) -> str:
+        cred_calls.append(root_certificates)
+        return "creds"
+
+    channel_calls: list[tuple[str, object, object]] = []
+
+    def fake_secure_channel(endpoint: str, credentials: object, *, options: object) -> str:
+        channel_calls.append((endpoint, credentials, options))
+        return "tls-channel"
+
+    monkeypatch.setattr(options_module.grpc, "ssl_channel_credentials", fake_credentials)
+    monkeypatch.setattr(options_module.grpc.aio, "secure_channel", fake_secure_channel)
 
     channel = create_channel(
         ClientOptions(
@@ -102,14 +163,164 @@ def test_create_channel_uses_tls_channel(monkeypatch: pytest.MonkeyPatch) -> Non
     )
 
     assert channel == "tls-channel"
-    assert calls == [
-            (
-                "gateway.example:5001",
-                "creds",
-                [
-                    ("grpc.max_receive_message_length", 16 * 1024 * 1024),
-                    ("grpc.max_send_message_length", 16 * 1024 * 1024),
-                    ("grpc.ssl_target_name_override", "gateway.test"),
-                ],
-            ),
-        ]
+    assert cred_calls == [_DUMMY_PEM.encode("ascii")]
+    assert channel_calls == [
+        (
+            "gateway.example:5001",
+            "creds",
+            [
+                ("grpc.max_receive_message_length", 16 * 1024 * 1024),
+                ("grpc.max_send_message_length", 16 * 1024 * 1024),
+                # Explicit override from ClientOptions — not the auto-localhost one
+                ("grpc.ssl_target_name_override", "gateway.test"),
+            ],
+        ),
+    ]
+
+
+def test_create_channel_uses_tls_channel_require_cert_validation(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """require_certificate_validation=True uses system trust (no TOFU, no root_certificates)."""
+    get_cert_called = False
+
+    def fake_get_server_certificate(addr: object) -> str:  # pragma: no cover
+        nonlocal get_cert_called
+        get_cert_called = True
+        return "SHOULD_NOT_BE_CALLED"
+
+    cred_calls: list[object] = []
+
+    def fake_credentials(**kwargs: object) -> str:
+        cred_calls.append(kwargs)
+        return "creds"
+
+    channel_calls: list[tuple[str, object, object]] = []
+
+    def fake_secure_channel(endpoint: str, credentials: object, *, options: object) -> str:
+        channel_calls.append((endpoint, credentials, options))
+        return "tls-channel"
+
+    monkeypatch.setattr(options_module.ssl, "get_server_certificate", fake_get_server_certificate)
+    monkeypatch.setattr(options_module.grpc, "ssl_channel_credentials", fake_credentials)
+    monkeypatch.setattr(options_module.grpc.aio, "secure_channel", fake_secure_channel)
+
+    channel = create_channel(
+        ClientOptions(
+            endpoint="gateway.example:5001",
+            require_certificate_validation=True,
+        ),
+    )
+
+    assert channel == "tls-channel"
+    # Must NOT call TOFU prefetch
+    assert not get_cert_called
+    # ssl_channel_credentials() called with NO keyword args (system trust)
+    assert cred_calls == [{}]
+    assert channel_calls == [
+        (
+            "gateway.example:5001",
+            "creds",
+            [
+                ("grpc.max_receive_message_length", 16 * 1024 * 1024),
+                ("grpc.max_send_message_length", 16 * 1024 * 1024),
+            ],
+        ),
+    ]
+
+
+def test_create_channel_uses_tls_channel_ca_file(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: pytest.TempPathFactory,
+) -> None:
+    """ca_file path: reads the PEM file, passes bytes as root_certificates, skips TOFU."""
+    ca_pem = b"-----BEGIN CERTIFICATE-----\nY2FkYXRh\n-----END CERTIFICATE-----\n"
+    ca_file = tmp_path / "ca.pem"
+    ca_file.write_bytes(ca_pem)
+
+    get_cert_called = False
+
+    def fake_get_server_certificate(addr: object) -> str:  # pragma: no cover
+        nonlocal get_cert_called
+        get_cert_called = True
+        return "SHOULD_NOT_BE_CALLED"
+
+    cred_calls: list[object] = []
+
+    def fake_credentials(*, root_certificates: object = None) -> str:
+        cred_calls.append(root_certificates)
+        return "creds"
+
+    channel_calls: list[tuple[str, object, object]] = []
+
+    def fake_secure_channel(endpoint: str, credentials: object, *, options: object) -> str:
+        channel_calls.append((endpoint, credentials, options))
+        return "tls-channel"
+
+    monkeypatch.setattr(options_module.ssl, "get_server_certificate", fake_get_server_certificate)
+    monkeypatch.setattr(options_module.grpc, "ssl_channel_credentials", fake_credentials)
+    monkeypatch.setattr(options_module.grpc.aio, "secure_channel", fake_secure_channel)
+
+    channel = create_channel(
+        ClientOptions(
+            endpoint="gateway.example:5001",
+            ca_file=str(ca_file),
+        ),
+    )
+
+    assert channel == "tls-channel"
+    assert not get_cert_called
+    assert cred_calls == [ca_pem]
+    assert channel_calls == [
+        (
+            "gateway.example:5001",
+            "creds",
+            [
+                ("grpc.max_receive_message_length", 16 * 1024 * 1024),
+                ("grpc.max_send_message_length", 16 * 1024 * 1024),
+            ],
+        ),
+    ]
+
+
+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()
 
@@ -50,6 +115,28 @@ def test_write_parser_rejects_unknown_value_type() -> None:
     assert "unsupported value type" in result.output
 
 
+def test_stream_alarms_is_registered() -> None:
+    runner = CliRunner()
+
+    result = runner.invoke(main, ["stream-alarms", "--help"])
+
+    assert result.exit_code == 0
+    assert "--filter-prefix" in result.output
+    assert "--max-messages" in result.output
+
+
+def test_acknowledge_alarm_requires_reference() -> None:
+    runner = CliRunner()
+
+    result = runner.invoke(
+        main,
+        ["acknowledge-alarm", "--api-key", "mxgw_test_secret", "--json"],
+    )
+
+    assert result.exit_code != 0
+    assert "--reference" in result.output
+
+
 def test_cli_error_output_redacts_api_key() -> None:
     runner = CliRunner()
 
@@ -124,3 +211,437 @@ def test_batch_continues_after_error_line() -> None:
     # Second block: successful version JSON.
     version_payload = json.loads(blocks[1].strip())
     assert version_payload["version"] == __version__
+
+
+class _FakeGalaxyClient:
+    """Minimal async-context-manager fake satisfying the galaxy command bodies."""
+
+    def __init__(
+        self,
+        *,
+        ok: bool = True,
+        objects=None,
+        last_deploy=None,
+        events=None,
+        browse_roots=None,
+        browse_children_pages=None,
+    ) -> None:
+        self._ok = ok
+        self._objects = objects or []
+        self._last_deploy = last_deploy
+        self._events = events or []
+        self._browse_roots = browse_roots or []
+        # List of BrowseChildrenReply-like objects to serve in order (paged).
+        self._browse_children_pages = browse_children_pages or []
+        self._browse_children_calls: list = []
+        self.browse_options = None
+
+    async def __aenter__(self) -> "_FakeGalaxyClient":
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        return None
+
+    async def test_connection(self) -> bool:
+        return self._ok
+
+    async def discover_hierarchy(self):
+        return self._objects
+
+    async def browse(self, options=None):
+        self.browse_options = options
+        return self._browse_roots
+
+    async def browse_children_raw(self, request):
+        """Return the next queued BrowseChildrenReply page; raises if queue empty."""
+        self._browse_children_calls.append(request)
+        if not self._browse_children_pages:
+            raise AssertionError("browse_children_raw called but no pages queued")
+        return self._browse_children_pages.pop(0)
+
+    async def get_last_deploy_time(self):
+        # Mirrors galaxy.py: protobuf ToDatetime() yields a timezone-NAIVE UTC datetime.
+        return self._last_deploy
+
+    def watch_deploy_events(self, _last_seen_deploy_time=None):
+        events = self._events
+
+        async def _iter():
+            for event in events:
+                yield event
+
+        return _iter()
+
+
+def _patch_galaxy_connect(monkeypatch: pytest.MonkeyPatch, fake: _FakeGalaxyClient) -> None:
+    async def fake_connect(options, **_kwargs):
+        return fake
+
+    monkeypatch.setattr(commands_module.GalaxyRepositoryClient, "connect", fake_connect)
+
+
+def test_galaxy_test_connection_emits_ok(monkeypatch: pytest.MonkeyPatch) -> None:
+    _patch_galaxy_connect(monkeypatch, _FakeGalaxyClient(ok=True))
+
+    result = CliRunner().invoke(
+        main,
+        ["galaxy-test-connection", "--plaintext", "--json"],
+    )
+
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload == {"command": "galaxy-test-connection", "ok": True}
+
+
+def test_galaxy_discover_serializes_objects(monkeypatch: pytest.MonkeyPatch) -> None:
+    from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
+
+    objects = [
+        galaxy_pb.GalaxyObject(gobject_id=7, tag_name="Area001", contained_name="Area001"),
+        galaxy_pb.GalaxyObject(gobject_id=8, tag_name="Pump001", contained_name="Pump001"),
+    ]
+    _patch_galaxy_connect(monkeypatch, _FakeGalaxyClient(objects=objects))
+
+    result = CliRunner().invoke(
+        main,
+        ["galaxy-discover", "--plaintext", "--json"],
+    )
+
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["command"] == "galaxy-discover"
+    assert len(payload["objects"]) == 2
+    assert payload["objects"][0]["tagName"] == "Area001"
+    assert payload["objects"][1]["gobjectId"] == 8
+
+
+def test_galaxy_last_deploy_emits_utc_iso(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The naive-UTC deploy time from the library must be emitted as unambiguous UTC ISO-8601."""
+    from datetime import datetime
+
+    naive_utc = datetime(2025, 6, 15, 12, 0, 0)  # noqa: DTZ001 -- mirrors protobuf ToDatetime()
+    _patch_galaxy_connect(monkeypatch, _FakeGalaxyClient(last_deploy=naive_utc))
+
+    result = CliRunner().invoke(
+        main,
+        ["galaxy-last-deploy", "--plaintext", "--json"],
+    )
+
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["command"] == "galaxy-last-deploy"
+    assert payload["present"] is True
+    assert payload["timeOfLastDeploy"].endswith(("+00:00", "Z"))
+
+
+def test_galaxy_watch_serializes_deploy_events(monkeypatch: pytest.MonkeyPatch) -> None:
+    from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
+
+    events = [galaxy_pb.DeployEvent(sequence=1)]
+    _patch_galaxy_connect(monkeypatch, _FakeGalaxyClient(events=events))
+
+    result = CliRunner().invoke(
+        main,
+        ["galaxy-watch", "--plaintext", "--max-events", "1", "--json"],
+    )
+
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["command"] == "galaxy-watch"
+    assert len(payload["events"]) == 1
+
+
+class _FakeBrowseNode:
+    """Minimal stand-in for LazyBrowseNode covering the CLI render path."""
+
+    def __init__(self, obj, *, has_children_hint=False, children=None) -> None:
+        self._object = obj
+        self._has_children_hint = has_children_hint
+        self._children = list(children or [])
+        self._is_expanded = bool(children)
+        self.expand_calls = 0
+
+    @property
+    def object(self):
+        return self._object
+
+    @property
+    def has_children_hint(self) -> bool:
+        return self._has_children_hint
+
+    @property
+    def children(self):
+        return list(self._children)
+
+    @property
+    def is_expanded(self) -> bool:
+        return self._is_expanded
+
+    async def expand(self) -> None:
+        self.expand_calls += 1
+        self._is_expanded = True
+
+
+def test_galaxy_browse_serializes_nested_nodes(monkeypatch: pytest.MonkeyPatch) -> None:
+    from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
+
+    child = _FakeBrowseNode(
+        galaxy_pb.GalaxyObject(gobject_id=8, tag_name="Pump001", contained_name="Pump001"),
+        has_children_hint=False,
+    )
+    root = _FakeBrowseNode(
+        galaxy_pb.GalaxyObject(gobject_id=7, tag_name="Area001", contained_name="Area001"),
+        has_children_hint=True,
+        children=[child],
+    )
+    _patch_galaxy_connect(monkeypatch, _FakeGalaxyClient(browse_roots=[root]))
+
+    result = CliRunner().invoke(
+        main,
+        ["galaxy-browse", "--plaintext", "--json"],
+    )
+
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert "_text" not in payload
+    assert payload["command"] == "galaxy-browse"
+    assert len(payload["nodes"]) == 1
+    node = payload["nodes"][0]
+    assert node["tagName"] == "Area001"
+    assert node["hasChildrenHint"] is True
+    assert len(node["children"]) == 1
+    assert node["children"][0]["gobjectId"] == 8
+    assert node["children"][0]["children"] == []
+
+
+def test_galaxy_browse_renders_indented_text_tree(monkeypatch: pytest.MonkeyPatch) -> None:
+    from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
+
+    child = _FakeBrowseNode(
+        galaxy_pb.GalaxyObject(gobject_id=8, tag_name="Pump001", browse_name="Pump001"),
+    )
+    root = _FakeBrowseNode(
+        galaxy_pb.GalaxyObject(gobject_id=7, tag_name="Area001", browse_name="Area001"),
+        has_children_hint=True,
+        children=[child],
+    )
+    _patch_galaxy_connect(monkeypatch, _FakeGalaxyClient(browse_roots=[root]))
+
+    result = CliRunner().invoke(
+        main,
+        ["galaxy-browse", "--plaintext"],
+    )
+
+    assert result.exit_code == 0, result.output
+    lines = result.output.splitlines()
+    assert lines[0] == "1"
+    assert lines[1] == "+ Area001 Area001 (gobject 7)"
+    assert lines[2] == "  - Pump001 Pump001 (gobject 8)"
+
+
+def test_galaxy_browse_forwards_filter_options(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = _FakeGalaxyClient(browse_roots=[])
+    _patch_galaxy_connect(monkeypatch, fake)
+
+    result = CliRunner().invoke(
+        main,
+        [
+            "galaxy-browse",
+            "--plaintext",
+            "--category-id",
+            "10",
+            "--category-id",
+            "12",
+            "--template-chain-contains",
+            "$Pump",
+            "--tag-name-glob",
+            "Area*",
+            "--include-attributes",
+            "--alarm-bearing-only",
+            "--historized-only",
+            "--json",
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    options = fake.browse_options
+    assert tuple(options.category_ids) == (10, 12)
+    assert tuple(options.template_chain_contains) == ("$Pump",)
+    assert options.tag_name_glob == "Area*"
+    assert options.include_attributes is True
+    assert options.alarm_bearing_only is True
+    assert options.historized_only is True
+
+
+def test_galaxy_browse_expands_to_depth(monkeypatch: pytest.MonkeyPatch) -> None:
+    from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
+
+    root = _FakeBrowseNode(
+        galaxy_pb.GalaxyObject(gobject_id=7, tag_name="Area001"),
+        has_children_hint=True,
+    )
+    _patch_galaxy_connect(monkeypatch, _FakeGalaxyClient(browse_roots=[root]))
+
+    result = CliRunner().invoke(
+        main,
+        ["galaxy-browse", "--plaintext", "--depth", "2", "--json"],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert root.expand_calls == 1
+
+
+def test_galaxy_commands_are_registered() -> None:
+    runner = CliRunner()
+    for command in (
+        "galaxy-test-connection",
+        "galaxy-last-deploy",
+        "galaxy-discover",
+        "galaxy-watch",
+        "galaxy-browse",
+    ):
+        result = runner.invoke(main, [command, "--help"])
+        assert result.exit_code == 0, result.output
+        assert "--endpoint" in result.output
+
+
+@pytest.mark.parametrize("depth_arg", ["99", "-1"])
+def test_galaxy_browse_rejects_out_of_range_depth(
+    monkeypatch: pytest.MonkeyPatch,
+    depth_arg: str,
+) -> None:
+    """--depth values outside [0, 50] must be rejected with a non-zero exit."""
+    _patch_galaxy_connect(monkeypatch, _FakeGalaxyClient(browse_roots=[]))
+
+    result = CliRunner().invoke(
+        main,
+        ["galaxy-browse", "--plaintext", "--depth", depth_arg, "--json"],
+    )
+
+    assert result.exit_code != 0
+    assert "--depth must be between 0 and 50" in result.output
+
+
+# ---------------------------------------------------------------------------
+# --parent-gobject-id drill-down tests
+# ---------------------------------------------------------------------------
+
+
+def _fake_browse_children_reply(children_and_hints, *, next_page_token=""):
+    """Build a minimal fake BrowseChildrenReply-like object."""
+    from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
+
+    reply = galaxy_pb.BrowseChildrenReply()
+    for obj, hint in children_and_hints:
+        reply.children.append(obj)
+        reply.child_has_children.append(hint)
+    reply.next_page_token = next_page_token
+    return reply
+
+
+def test_galaxy_browse_parent_fetches_one_level_json(monkeypatch: pytest.MonkeyPatch) -> None:
+    """--parent-gobject-id N calls browse_children_raw and renders one-level JSON."""
+    from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
+
+    child_a = galaxy_pb.GalaxyObject(gobject_id=10, tag_name="PumpA", browse_name="PumpA")
+    child_b = galaxy_pb.GalaxyObject(gobject_id=11, tag_name="PumpB", browse_name="PumpB")
+    page = _fake_browse_children_reply([(child_a, True), (child_b, False)])
+    fake = _FakeGalaxyClient(browse_children_pages=[page])
+    _patch_galaxy_connect(monkeypatch, fake)
+
+    result = CliRunner().invoke(
+        main,
+        ["galaxy-browse", "--plaintext", "--parent-gobject-id", "7", "--json"],
+    )
+
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+
+    # One BrowseChildren RPC was issued with the correct parent id.
+    assert len(fake._browse_children_calls) == 1
+    call_req = fake._browse_children_calls[0]
+    assert call_req.parent_gobject_id == 7
+
+    # JSON shape mirrors the lazy-browse node shape.
+    assert payload["command"] == "galaxy-browse"
+    nodes = payload["nodes"]
+    assert len(nodes) == 2
+    assert nodes[0]["tagName"] == "PumpA"
+    assert nodes[0]["hasChildrenHint"] is True
+    assert nodes[0]["children"] == []
+    assert nodes[1]["gobjectId"] == 11
+    assert nodes[1]["hasChildrenHint"] is False
+    assert nodes[1]["children"] == []
+
+
+def test_galaxy_browse_parent_renders_text_tree(monkeypatch: pytest.MonkeyPatch) -> None:
+    """--parent-gobject-id N text output: count line then marker lines (no indent)."""
+    from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
+
+    child = galaxy_pb.GalaxyObject(gobject_id=10, tag_name="PumpA", browse_name="PumpA")
+    page = _fake_browse_children_reply([(child, False)])
+    fake = _FakeGalaxyClient(browse_children_pages=[page])
+    _patch_galaxy_connect(monkeypatch, fake)
+
+    result = CliRunner().invoke(
+        main,
+        ["galaxy-browse", "--plaintext", "--parent-gobject-id", "7"],
+    )
+
+    assert result.exit_code == 0, result.output
+    lines = result.output.splitlines()
+    assert lines[0] == "1"
+    assert lines[1] == "- PumpA PumpA (gobject 10)"
+
+
+def test_galaxy_browse_parent_pages_correctly(monkeypatch: pytest.MonkeyPatch) -> None:
+    """--parent-gobject-id loops on next_page_token until exhausted."""
+    from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
+
+    child_a = galaxy_pb.GalaxyObject(gobject_id=10, tag_name="PumpA", browse_name="PumpA")
+    child_b = galaxy_pb.GalaxyObject(gobject_id=11, tag_name="PumpB", browse_name="PumpB")
+    page1 = _fake_browse_children_reply([(child_a, False)], next_page_token="tok1")
+    page2 = _fake_browse_children_reply([(child_b, True)])
+    fake = _FakeGalaxyClient(browse_children_pages=[page1, page2])
+    _patch_galaxy_connect(monkeypatch, fake)
+
+    result = CliRunner().invoke(
+        main,
+        ["galaxy-browse", "--plaintext", "--parent-gobject-id", "7", "--json"],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert len(fake._browse_children_calls) == 2
+    # Second call must carry the page token from the first reply.
+    assert fake._browse_children_calls[1].page_token == "tok1"
+    payload = json.loads(result.output)
+    assert len(payload["nodes"]) == 2
+
+
+def test_galaxy_browse_parent_warns_when_depth_also_set(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """When both --parent-gobject-id and --depth>0 are supplied a warning is emitted."""
+    from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
+
+    child = galaxy_pb.GalaxyObject(gobject_id=10, tag_name="PumpA", browse_name="PumpA")
+    page = _fake_browse_children_reply([(child, False)])
+    fake = _FakeGalaxyClient(browse_children_pages=[page])
+    _patch_galaxy_connect(monkeypatch, fake)
+
+    # CliRunner mixes stderr into output in this Click version.
+    result = CliRunner().invoke(
+        main,
+        ["galaxy-browse", "--plaintext", "--parent-gobject-id", "7", "--depth", "2", "--json"],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert "--depth is ignored" in result.output
+
+
+def test_galaxy_browse_help_shows_parent_gobject_id() -> None:
+    """--parent-gobject-id appears in the galaxy-browse --help output."""
+    result = CliRunner().invoke(main, ["galaxy-browse", "--help"])
+
+    assert result.exit_code == 0
+    assert "--parent-gobject-id" in result.output

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_galaxy.py

@@ -6,12 +6,16 @@ import asyncio
 from datetime import datetime, timezone
 from typing import Any
 
+import grpc
 import pytest
 from google.protobuf.timestamp_pb2 import Timestamp
 
 from zb_mom_ww_mxgateway import ClientOptions, DeployEvent, GalaxyRepositoryClient, WatchDeployEventsRequest
+from zb_mom_ww_mxgateway.errors import MxGatewayError
+from zb_mom_ww_mxgateway.galaxy import LazyBrowseNode
 from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
 from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2_grpc as galaxy_pb_grpc
+from zb_mom_ww_mxgateway.options import BrowseChildrenOptions
 
 
 def test_galaxy_messages_import() -> None:
@@ -268,15 +272,281 @@ async def test_close_marks_channel_closed_when_no_real_channel() -> None:
     await client.close()
 
 
+def _obj(gid: int, tag: str, is_area: bool = False) -> galaxy_pb.GalaxyObject:
+    return galaxy_pb.GalaxyObject(
+        gobject_id=gid, tag_name=tag, browse_name=tag, is_area=is_area,
+    )
+
+
+def _build_browse_reply(
+    children: list[galaxy_pb.GalaxyObject],
+    child_has_children: list[bool],
+    cache_sequence: int,
+    next_page_token: str = "",
+) -> galaxy_pb.BrowseChildrenReply:
+    reply = galaxy_pb.BrowseChildrenReply(
+        total_child_count=len(children),
+        cache_sequence=cache_sequence,
+        next_page_token=next_page_token,
+    )
+    reply.children.extend(children)
+    reply.child_has_children.extend(child_has_children)
+    return reply
+
+
+def _fake_aio_rpc_error(code: grpc.StatusCode, details: str) -> grpc.aio.AioRpcError:
+    return grpc.aio.AioRpcError(
+        code=code,
+        initial_metadata=grpc.aio.Metadata(),
+        trailing_metadata=grpc.aio.Metadata(),
+        details=details,
+    )
+
+
+@pytest.mark.asyncio
+async def test_browse_no_parent_returns_roots() -> None:
+    stub = FakeGalaxyStub()
+    stub.browse_children.replies = [
+        _build_browse_reply(
+            children=[_obj(1, "Area_A", is_area=True), _obj(2, "Area_B", is_area=True)],
+            child_has_children=[True, False],
+            cache_sequence=7,
+        ),
+    ]
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", plaintext=True),
+        stub=stub,
+    )
+
+    roots = await client.browse()
+
+    assert len(roots) == 2
+    assert all(isinstance(node, LazyBrowseNode) for node in roots)
+    assert roots[0].object.tag_name == "Area_A"
+    assert roots[0].has_children_hint is True
+    assert roots[1].has_children_hint is False
+    assert roots[0].is_expanded is False
+    request = stub.browse_children.requests[0]
+    assert request.WhichOneof("parent") is None
+    assert request.page_size == 500
+    assert request.page_token == ""
+
+
+@pytest.mark.asyncio
+async def test_browse_expand_populates_children_and_marks_expanded() -> None:
+    stub = FakeGalaxyStub()
+    stub.browse_children.replies = [
+        _build_browse_reply(
+            children=[_obj(1, "Area_A", is_area=True)],
+            child_has_children=[True],
+            cache_sequence=1,
+        ),
+        _build_browse_reply(
+            children=[_obj(11, "Child_A"), _obj(12, "Child_B")],
+            child_has_children=[False, False],
+            cache_sequence=1,
+        ),
+    ]
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", plaintext=True),
+        stub=stub,
+    )
+
+    roots = await client.browse()
+    await roots[0].expand()
+
+    assert roots[0].is_expanded is True
+    assert [n.object.tag_name for n in roots[0].children] == ["Child_A", "Child_B"]
+    assert len(stub.browse_children.requests) == 2
+    expand_request = stub.browse_children.requests[1]
+    assert expand_request.WhichOneof("parent") == "parent_gobject_id"
+    assert expand_request.parent_gobject_id == 1
+
+
+@pytest.mark.asyncio
+async def test_browse_expand_idempotent_no_second_rpc() -> None:
+    stub = FakeGalaxyStub()
+    stub.browse_children.replies = [
+        _build_browse_reply(
+            children=[_obj(1, "Area_A", is_area=True)],
+            child_has_children=[True],
+            cache_sequence=1,
+        ),
+        _build_browse_reply(
+            children=[_obj(11, "Child_A")],
+            child_has_children=[False],
+            cache_sequence=1,
+        ),
+    ]
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", plaintext=True),
+        stub=stub,
+    )
+
+    roots = await client.browse()
+    await roots[0].expand()
+    await roots[0].expand()
+
+    assert len(stub.browse_children.requests) == 2
+    assert len(roots[0].children) == 1
+
+
+@pytest.mark.asyncio
+async def test_browse_expand_concurrent_callers_only_fire_one_rpc() -> None:
+    stub = FakeGalaxyStub()
+    stub.browse_children.replies = [
+        _build_browse_reply([_obj(1, "Plant", is_area=True)], [True], 7),
+        _build_browse_reply([_obj(2, "Mixer_001")], [False], 7),
+    ]
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", plaintext=True),
+        stub=stub,
+    )
+
+    roots = await client.browse()
+    # Ten concurrent expand calls on the same node should issue exactly one RPC.
+    await asyncio.gather(*(roots[0].expand() for _ in range(10)))
+
+    assert roots[0].is_expanded
+    assert len(roots[0].children) == 1
+    # 1 roots fetch + exactly 1 expand fetch = 2 total
+    assert len(stub.browse_children.requests) == 2
+
+
+@pytest.mark.asyncio
+async def test_browse_expand_unknown_parent_raises_mxgateway_error() -> None:
+    stub = FakeGalaxyStub()
+    stub.browse_children.replies = [
+        _build_browse_reply(
+            children=[_obj(99, "Stale_Parent", is_area=True)],
+            child_has_children=[True],
+            cache_sequence=1,
+        ),
+    ]
+    stub.browse_children.exceptions = [
+        None,
+        _fake_aio_rpc_error(grpc.StatusCode.NOT_FOUND, "parent not found"),
+    ]
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", plaintext=True),
+        stub=stub,
+    )
+
+    roots = await client.browse()
+    with pytest.raises(MxGatewayError):
+        await roots[0].expand()
+
+
+@pytest.mark.asyncio
+async def test_browse_expand_multi_page_gathers_all_pages() -> None:
+    stub = FakeGalaxyStub()
+    stub.browse_children.replies = [
+        _build_browse_reply(
+            children=[_obj(7, "Area_Big", is_area=True)],
+            child_has_children=[True],
+            cache_sequence=2,
+        ),
+        _build_browse_reply(
+            children=[_obj(71, "Child_1"), _obj(72, "Child_2")],
+            child_has_children=[False, False],
+            cache_sequence=2,
+            next_page_token="7:abc:2",
+        ),
+        _build_browse_reply(
+            children=[_obj(73, "Child_3")],
+            child_has_children=[False],
+            cache_sequence=2,
+        ),
+    ]
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", plaintext=True),
+        stub=stub,
+    )
+
+    roots = await client.browse()
+    await roots[0].expand()
+
+    assert [n.object.tag_name for n in roots[0].children] == ["Child_1", "Child_2", "Child_3"]
+    assert len(stub.browse_children.requests) == 3
+    assert stub.browse_children.requests[2].page_token == "7:abc:2"
+    assert stub.browse_children.requests[2].parent_gobject_id == 7
+
+
+@pytest.mark.asyncio
+async def test_browse_with_filter_forwards_to_request() -> None:
+    stub = FakeGalaxyStub()
+    stub.browse_children.replies = [
+        _build_browse_reply(
+            children=[_obj(1, "Area_A", is_area=True)],
+            child_has_children=[False],
+            cache_sequence=3,
+        ),
+    ]
+    client = await GalaxyRepositoryClient.connect(
+        ClientOptions(endpoint="fake", plaintext=True),
+        stub=stub,
+    )
+    options = BrowseChildrenOptions(
+        category_ids=(4, 5),
+        template_chain_contains=("$DelmiaReceiver",),
+        tag_name_glob="Area_*",
+        include_attributes=True,
+        alarm_bearing_only=True,
+        historized_only=True,
+    )
+
+    await client.browse(options)
+
+    request = stub.browse_children.requests[0]
+    assert list(request.category_ids) == [4, 5]
+    assert list(request.template_chain_contains) == ["$DelmiaReceiver"]
+    assert request.tag_name_glob == "Area_*"
+    assert request.HasField("include_attributes")
+    assert request.include_attributes is True
+    assert request.alarm_bearing_only is True
+    assert request.historized_only is True
+
+
+@pytest.mark.asyncio
+async def test_browse_children_raw_returns_reply_unwrapped() -> None:
+    """browse_children_raw forwards the request to the stub and returns the raw reply."""
+    stub = FakeGalaxyStub()
+    expected = _build_browse_reply(
+        children=[_obj(1, "Plant", is_area=True)],
+        child_has_children=[True],
+        cache_sequence=42,
+    )
+    stub.browse_children.replies = [expected]
+
+    async with await GalaxyRepositoryClient.connect(
+        endpoint="fake",
+        plaintext=True,
+        stub=stub,
+    ) as client:
+        request = galaxy_pb.BrowseChildrenRequest(
+            page_size=10,
+            tag_name_glob="Plant*",
+        )
+        reply = await client.browse_children_raw(request)
+
+    assert reply.cache_sequence == 42
+    assert len(reply.children) == 1
+    assert reply.children[0].tag_name == "Plant"
+    assert len(stub.browse_children.requests) == 1
+    assert stub.browse_children.requests[0].tag_name_glob == "Plant*"
+
+
 class FakeGalaxyStub:
     def __init__(self) -> None:
         self.test_connection = FakeUnary([galaxy_pb.TestConnectionReply(ok=False)])
         self.get_last_deploy_time = FakeUnary([galaxy_pb.GetLastDeployTimeReply(present=False)])
         self.discover_hierarchy = FakeUnary([galaxy_pb.DiscoverHierarchyReply()])
+        self.browse_children = FakeUnary([galaxy_pb.BrowseChildrenReply()])
         self.watch_deploy_events = FakeStream([])
         self.TestConnection = self.test_connection
         self.GetLastDeployTime = self.get_last_deploy_time
         self.DiscoverHierarchy = self.discover_hierarchy
+        self.BrowseChildren = self.browse_children
 
     @property
     def WatchDeployEvents(self) -> "FakeStream":  # noqa: N802 — gRPC naming
@@ -287,6 +557,8 @@ class FakeUnary:
     def __init__(self, replies: list[Any]) -> None:
         self.replies = replies
         self.requests: list[Any] = []
+        # None entries mean "no exception on this call"; aligns with the replies queue index-by-index.
+        self.exceptions: list[BaseException | None] = []
         self.metadata: tuple[tuple[str, str], ...] | None = None
 
     async def __call__(
@@ -298,6 +570,10 @@ class FakeUnary:
     ) -> Any:
         self.requests.append(request)
         self.metadata = metadata
+        if self.exceptions:
+            exc = self.exceptions.pop(0)
+            if exc is not None:
+                raise exc
         return self.replies.pop(0)
 
 

clients/python/tests/test_review_findings_022_to_026.py

@@ -0,0 +1,789 @@
+"""Regression tests for Client.Python-022..026.
+
+Each test corresponds to a finding from the latest re-review. Tests are
+TDD-first — they failed against the pre-fix source and pass against the
+fixed source.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time as _time_module_ref
+from pathlib import Path
+from typing import Any
+
+import pytest
+from click.testing import CliRunner
+
+from zb_mom_ww_mxgateway import ClientOptions, GatewayClient
+from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2 as pb
+from zb_mom_ww_mxgateway_cli import commands as cli_commands
+from zb_mom_ww_mxgateway_cli.commands import _use_plaintext, main
+
+_BATCH_EOR = "__MXGW_BATCH_EOR__"
+
+
+# ---------------------------------------------------------------------------
+# Client.Python-022 — README CLI examples must parse against the implementation.
+# ---------------------------------------------------------------------------
+
+
+def _readme_path() -> Path:
+    return Path(__file__).resolve().parent.parent / "README.md"
+
+
+def _extract_mxgw_py_examples() -> list[list[str]]:
+    """Return the README's ``mxgw-py ...`` example lines as click arg lists.
+
+    Replaces angle-bracket placeholders (``<id>``) with safe stub values and
+    leaves real flag names untouched. The returned arg lists drop the
+    ``mxgw-py`` prefix.
+    """
+
+    text = _readme_path().read_text(encoding="utf-8")
+    args: list[list[str]] = []
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line.startswith("mxgw-py "):
+            continue
+        # Strip the leading "mxgw-py " token.
+        body = line[len("mxgw-py ") :]
+        # Replace common placeholders so click does not error on the placeholder.
+        body = body.replace("<id>", "session-1")
+        # Backtick-quoted hostnames in the TLS example are not represented
+        # in CLI; safe to leave as-is.
+        tokens = _split_cli_tokens(body)
+        # Keep only examples that exercise a real subcommand. Skip TLS
+        # multi-flag example (we only need the README CLI examples added in
+        # commits 8738735 — stream-alarms / acknowledge-alarm).
+        args.append(tokens)
+    return args
+
+
+def _split_cli_tokens(body: str) -> list[str]:
+    """Split a CLI body into argv tokens, honouring double-quoted strings."""
+
+    tokens: list[str] = []
+    pattern = re.compile(r'"([^"]*)"|(\S+)')
+    for match in pattern.finditer(body):
+        quoted, plain = match.group(1), match.group(2)
+        tokens.append(quoted if quoted is not None else plain)
+    return tokens
+
+
+def test_readme_alarm_examples_parse_against_cli() -> None:
+    """README `stream-alarms` / `acknowledge-alarm` examples must parse without
+    triggering Click's ``no such option`` error.
+
+    Drives every README ``mxgw-py`` example through Click's ``--help`` style
+    parser by re-invoking the documented argv with a trailing ``--help`` flag so
+    only the parser runs (no RPC is attempted). If a documented flag does not
+    exist on the subcommand, Click prints ``no such option: --<flag>`` and
+    exits 2 — that is the regression we want to catch.
+    """
+
+    runner = CliRunner()
+    examples = _extract_mxgw_py_examples()
+    assert any(
+        "stream-alarms" in args for args in examples
+    ), "README must include a stream-alarms example."
+    assert any(
+        "acknowledge-alarm" in args for args in examples
+    ), "README must include an acknowledge-alarm example."
+
+    for argv in examples:
+        # Strip "--json" (already a real flag) and any value-bearing flag that
+        # requires a host/file/value, then append --help so we exercise the
+        # parser only.
+        # We just append --help — Click parses all options up to --help and
+        # then prints help; an unknown option still errors out first.
+        result = runner.invoke(main, [*argv, "--help"])
+        # Either help text printed (exit 0) or some other parser issue (exit 2);
+        # we only want to assert NO "no such option" error.
+        assert "no such option" not in result.output.lower(), (
+            f"README example failed Click parsing: argv={argv!r}\n"
+            f"output={result.output!r}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Client.Python-023 — REGRESSION of Client.Python-013. _use_plaintext must
+# not silently auto-downgrade on localhost / 127.0.0.1.
+# ---------------------------------------------------------------------------
+
+
+def test_use_plaintext_does_not_auto_downgrade_for_localhost_endpoint() -> None:
+    """A bare ``localhost:...`` endpoint with no flags must default to TLS."""
+
+    assert _use_plaintext({
+        "endpoint": "localhost:5001",
+        "plaintext": False,
+        "use_tls": False,
+    }) is False
+
+
+def test_use_plaintext_does_not_auto_downgrade_for_loopback_ipv4_endpoint() -> None:
+    """A bare ``127.0.0.1:...`` endpoint with no flags must default to TLS."""
+
+    assert _use_plaintext({
+        "endpoint": "127.0.0.1:5001",
+        "plaintext": False,
+        "use_tls": False,
+    }) is False
+
+
+def test_use_plaintext_requires_explicit_plaintext_flag() -> None:
+    """``--plaintext`` is the only way to opt in."""
+
+    assert _use_plaintext({
+        "endpoint": "localhost:5001",
+        "plaintext": True,
+        "use_tls": False,
+    }) is True
+
+
+def test_use_plaintext_tls_flag_explicitly_disables_plaintext() -> None:
+    """``--tls`` is accepted as an explicit affirmation of the default."""
+
+    assert _use_plaintext({
+        "endpoint": "localhost:5001",
+        "plaintext": False,
+        "use_tls": True,
+    }) is False
+
+
+def test_use_plaintext_rejects_plaintext_and_tls_combined() -> None:
+    """``--plaintext`` and ``--tls`` together must be rejected as ambiguous."""
+
+    import click as _click
+
+    with pytest.raises(_click.UsageError):
+        _use_plaintext({
+            "endpoint": "localhost:5001",
+            "plaintext": True,
+            "use_tls": True,
+        })
+
+
+def test_cli_localhost_endpoint_with_no_flags_uses_tls_channel(monkeypatch) -> None:
+    """End-to-end CLI: against ``localhost:...`` with no flags, the resolved
+    ``ClientOptions.plaintext`` flowing into ``GatewayClient.connect`` must be
+    ``False`` (TLS), so the API key bearer cannot leak over plaintext.
+    """
+
+    captured: dict[str, Any] = {}
+
+    class _FakeStub:
+        def __init__(self) -> None:
+            pass
+
+        async def OpenSession(self, request: Any, *, metadata: tuple[Any, ...]) -> Any:
+            captured["metadata"] = metadata
+            return pb.OpenSessionReply(
+                session_id="session-1",
+                protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+            )
+
+    real_connect = GatewayClient.connect
+
+    @classmethod
+    async def _spy_connect(cls, options: ClientOptions, **kwargs: Any) -> GatewayClient:
+        captured["options"] = options
+        return await real_connect(options, stub=_FakeStub())
+
+    monkeypatch.setattr(GatewayClient, "connect", _spy_connect)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        main,
+        [
+            "open-session",
+            "--endpoint",
+            "localhost:5000",
+            "--api-key",
+            "mxgw_test_secret",
+            "--json",
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert "options" in captured
+    assert captured["options"].plaintext is False, (
+        "localhost endpoint without --plaintext must NOT auto-downgrade to plaintext"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Client.Python-024 — `batch` must not use CliRunner from production code,
+# and a recursive `batch` line must not silently re-enter.
+# ---------------------------------------------------------------------------
+
+
+def test_batch_command_does_not_use_clirunner_in_production() -> None:
+    """`commands.py` must not import or instantiate the test-only CliRunner helper.
+
+    Docstring references explaining what the module deliberately avoids are
+    permitted; what is forbidden is an actual ``import`` of ``click.testing``
+    or an actual ``CliRunner()`` instantiation in executable code.
+    """
+
+    source = Path(cli_commands.__file__).read_text(encoding="utf-8")
+    assert "from click.testing" not in source, (
+        "click.testing is a test-only helper and must not be used by production code"
+    )
+    assert "import click.testing" not in source, (
+        "click.testing is a test-only helper and must not be used by production code"
+    )
+    # `CliRunner()` (instantiation) must not appear in production code.
+    assert "CliRunner(" not in source, (
+        "CliRunner() must not be instantiated in production code"
+    )
+
+
+def test_batch_recursive_batch_line_is_bounded() -> None:
+    """A `batch` line nested inside `batch` stdin must not be silently spawned.
+
+    The pre-fix implementation re-invoked the test runner with empty stdin,
+    so `batch` inside `batch` exited cleanly with no error. The fix either
+    rejects the nested invocation or surfaces it as an error block so the
+    behaviour is auditable.
+    """
+
+    runner = CliRunner()
+    result = runner.invoke(
+        main,
+        ["batch"],
+        input="batch\nversion --json\n",
+    )
+
+    # Outer batch must still exit 0 and process both lines.
+    assert result.exit_code == 0
+    assert result.output.count(_BATCH_EOR) == 2
+
+    blocks = [block for block in result.output.split(_BATCH_EOR + "\n") if block]
+    # The first block — the recursive `batch` line — must surface an error
+    # JSON. (Either an explicit rejection, or some non-empty error block —
+    # NOT a silently empty block.)
+    first_block = blocks[0].strip()
+    assert first_block, "recursive batch line must not be silently swallowed"
+    payload = json.loads(first_block.splitlines()[-1])
+    assert "error" in payload, (
+        f"recursive batch line should surface an error: got {payload!r}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Client.Python-025 — Behavioural tests for new bulk SDK methods,
+# stream_alarms, and the new CLI subcommands.
+# ---------------------------------------------------------------------------
+
+
+class _AlarmFakeStream:
+    def __init__(self, messages: list[pb.AlarmFeedMessage]) -> None:
+        self._messages = list(messages)
+        self.cancelled = False
+
+    def __aiter__(self) -> "_AlarmFakeStream":
+        return self
+
+    async def __anext__(self) -> pb.AlarmFeedMessage:
+        if not self._messages:
+            raise StopAsyncIteration
+        return self._messages.pop(0)
+
+    def cancel(self) -> None:
+        self.cancelled = True
+
+
+class _BulkFakeUnary:
+    def __init__(self, replies: list[Any]) -> None:
+        self.replies = replies
+        self.requests: list[Any] = []
+        self.metadata: tuple[tuple[str, str], ...] | None = None
+
+    async def __call__(self, request: Any, *, metadata: tuple[tuple[str, str], ...]) -> Any:
+        self.requests.append(request)
+        self.metadata = metadata
+        return self.replies.pop(0)
+
+
+class _BulkFakeStub:
+    def __init__(self) -> None:
+        self.open_session = _BulkFakeUnary(
+            [
+                pb.OpenSessionReply(
+                    session_id="session-1",
+                    protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+                ),
+            ],
+        )
+        self.invoke = _BulkFakeUnary([])
+        self.OpenSession = self.open_session
+        self.Invoke = self.invoke
+        self.stream_alarms_metadata: tuple[tuple[str, str], ...] | None = None
+        self._alarm_stream = _AlarmFakeStream([])
+
+    def set_invoke_replies(self, replies: list[Any]) -> None:
+        self.invoke.replies = replies
+
+    def set_alarm_stream(self, stream: _AlarmFakeStream) -> None:
+        self._alarm_stream = stream
+
+    def StreamAlarms(self, request: Any, *, metadata: tuple[tuple[str, str], ...]) -> Any:
+        self.stream_alarms_request = request
+        self.stream_alarms_metadata = metadata
+        return self._alarm_stream
+
+
+@pytest.mark.asyncio
+async def test_session_read_bulk_sends_expected_request_shape() -> None:
+    stub = _BulkFakeStub()
+    stub.set_invoke_replies(
+        [
+            pb.MxCommandReply(
+                session_id="session-1",
+                kind=pb.MX_COMMAND_KIND_READ_BULK,
+                protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+                read_bulk=pb.BulkReadReply(
+                    results=[
+                        pb.BulkReadResult(
+                            tag_address="Tank01.Level",
+                            was_successful=True,
+                        ),
+                    ],
+                ),
+            ),
+        ],
+    )
+    client = await GatewayClient.connect(
+        ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
+        stub=stub,
+    )
+    session = await client.open_session()
+
+    results = await session.read_bulk(12, ["Tank01.Level"], timeout_ms=1500)
+
+    assert len(results) == 1
+    assert results[0].tag_address == "Tank01.Level"
+    request = stub.invoke.requests[0]
+    assert request.command.kind == pb.MX_COMMAND_KIND_READ_BULK
+    assert request.command.read_bulk.server_handle == 12
+    assert list(request.command.read_bulk.tag_addresses) == ["Tank01.Level"]
+    assert request.command.read_bulk.timeout_ms == 1500
+
+
+@pytest.mark.asyncio
+async def test_session_write_bulk_sends_expected_request_shape() -> None:
+    stub = _BulkFakeStub()
+    stub.set_invoke_replies(
+        [
+            pb.MxCommandReply(
+                session_id="session-1",
+                kind=pb.MX_COMMAND_KIND_WRITE_BULK,
+                protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+                write_bulk=pb.BulkWriteReply(
+                    results=[pb.BulkWriteResult(was_successful=True)],
+                ),
+            ),
+        ],
+    )
+    client = await GatewayClient.connect(
+        ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
+        stub=stub,
+    )
+    session = await client.open_session()
+
+    from zb_mom_ww_mxgateway.values import to_mx_value
+
+    entries = [
+        pb.WriteBulkEntry(item_handle=34, user_id=99, value=to_mx_value(123)),
+    ]
+    results = await session.write_bulk(12, entries)
+
+    assert results[0].was_successful is True
+    cmd = stub.invoke.requests[0].command
+    assert cmd.kind == pb.MX_COMMAND_KIND_WRITE_BULK
+    assert cmd.write_bulk.server_handle == 12
+    assert cmd.write_bulk.entries[0].item_handle == 34
+    assert cmd.write_bulk.entries[0].user_id == 99
+
+
+@pytest.mark.asyncio
+async def test_session_write2_bulk_sends_expected_request_shape() -> None:
+    stub = _BulkFakeStub()
+    stub.set_invoke_replies(
+        [
+            pb.MxCommandReply(
+                session_id="session-1",
+                kind=pb.MX_COMMAND_KIND_WRITE2_BULK,
+                protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+                write2_bulk=pb.BulkWriteReply(
+                    results=[pb.BulkWriteResult(was_successful=True)],
+                ),
+            ),
+        ],
+    )
+    client = await GatewayClient.connect(
+        ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
+        stub=stub,
+    )
+    session = await client.open_session()
+
+    from zb_mom_ww_mxgateway.values import to_mx_value
+
+    entries = [
+        pb.Write2BulkEntry(
+            item_handle=34,
+            user_id=99,
+            value=to_mx_value(123),
+            timestamp_value=to_mx_value(1.5),
+        ),
+    ]
+    results = await session.write2_bulk(12, entries)
+
+    assert results[0].was_successful is True
+    cmd = stub.invoke.requests[0].command
+    assert cmd.kind == pb.MX_COMMAND_KIND_WRITE2_BULK
+    assert cmd.write2_bulk.server_handle == 12
+    assert cmd.write2_bulk.entries[0].item_handle == 34
+
+
+@pytest.mark.asyncio
+async def test_session_write_secured_bulk_sends_expected_request_shape() -> None:
+    stub = _BulkFakeStub()
+    stub.set_invoke_replies(
+        [
+            pb.MxCommandReply(
+                session_id="session-1",
+                kind=pb.MX_COMMAND_KIND_WRITE_SECURED_BULK,
+                protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+                write_secured_bulk=pb.BulkWriteReply(
+                    results=[pb.BulkWriteResult(was_successful=True)],
+                ),
+            ),
+        ],
+    )
+    client = await GatewayClient.connect(
+        ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
+        stub=stub,
+    )
+    session = await client.open_session()
+
+    from zb_mom_ww_mxgateway.values import to_mx_value
+
+    entries = [
+        pb.WriteSecuredBulkEntry(
+            item_handle=34,
+            current_user_id=42,
+            verifier_user_id=43,
+            value=to_mx_value("secret"),
+        ),
+    ]
+    results = await session.write_secured_bulk(12, entries)
+
+    assert results[0].was_successful is True
+    cmd = stub.invoke.requests[0].command
+    assert cmd.kind == pb.MX_COMMAND_KIND_WRITE_SECURED_BULK
+    assert cmd.write_secured_bulk.server_handle == 12
+    assert cmd.write_secured_bulk.entries[0].current_user_id == 42
+    assert cmd.write_secured_bulk.entries[0].verifier_user_id == 43
+
+
+@pytest.mark.asyncio
+async def test_session_write_secured2_bulk_sends_expected_request_shape() -> None:
+    stub = _BulkFakeStub()
+    stub.set_invoke_replies(
+        [
+            pb.MxCommandReply(
+                session_id="session-1",
+                kind=pb.MX_COMMAND_KIND_WRITE_SECURED2_BULK,
+                protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+                write_secured2_bulk=pb.BulkWriteReply(
+                    results=[pb.BulkWriteResult(was_successful=True)],
+                ),
+            ),
+        ],
+    )
+    client = await GatewayClient.connect(
+        ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
+        stub=stub,
+    )
+    session = await client.open_session()
+
+    from zb_mom_ww_mxgateway.values import to_mx_value
+
+    entries = [
+        pb.WriteSecured2BulkEntry(
+            item_handle=34,
+            current_user_id=42,
+            verifier_user_id=43,
+            value=to_mx_value("secret"),
+            timestamp_value=to_mx_value(1.5),
+        ),
+    ]
+    results = await session.write_secured2_bulk(12, entries)
+
+    assert results[0].was_successful is True
+    cmd = stub.invoke.requests[0].command
+    assert cmd.kind == pb.MX_COMMAND_KIND_WRITE_SECURED2_BULK
+    assert cmd.write_secured2_bulk.entries[0].current_user_id == 42
+
+
+@pytest.mark.asyncio
+async def test_stream_alarms_yields_feed_messages_and_cancels_on_close() -> None:
+    transitions = [
+        pb.AlarmFeedMessage(
+            transition=pb.OnAlarmTransitionEvent(
+                alarm_full_reference="Tank01.Level.HiHi",
+                transition_kind=pb.ALARM_TRANSITION_KIND_RAISE,
+            ),
+        ),
+    ]
+    stream = _AlarmFakeStream(transitions)
+    stub = _BulkFakeStub()
+    stub.set_alarm_stream(stream)
+    client = await GatewayClient.connect(
+        ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
+        stub=stub,
+    )
+
+    iterator = client.stream_alarms(pb.StreamAlarmsRequest(alarm_filter_prefix="Tank01."))
+    first = await anext(iterator)
+    await iterator.aclose()
+
+    assert first.transition.alarm_full_reference == "Tank01.Level.HiHi"
+    assert stream.cancelled
+    assert stub.stream_alarms_metadata == (("authorization", "Bearer mxgw_test_secret"),)
+    assert stub.stream_alarms_request.alarm_filter_prefix == "Tank01."
+
+
+# ---- CLI happy-path coverage for the new subcommands ----
+
+
+def _install_fake_connect(monkeypatch, stub: Any) -> dict[str, Any]:
+    """Patch `GatewayClient.connect` so the CLI uses the supplied fake stub."""
+
+    captured: dict[str, Any] = {}
+    real_connect = GatewayClient.connect
+
+    @classmethod
+    async def _spy_connect(cls, options: ClientOptions, **kwargs: Any) -> GatewayClient:
+        captured["options"] = options
+        return await real_connect(options, stub=stub)
+
+    monkeypatch.setattr(GatewayClient, "connect", _spy_connect)
+    return captured
+
+
+def test_cli_read_bulk_happy_path(monkeypatch) -> None:
+    stub = _BulkFakeStub()
+    stub.set_invoke_replies(
+        [
+            pb.MxCommandReply(
+                session_id="session-1",
+                kind=pb.MX_COMMAND_KIND_READ_BULK,
+                protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+                read_bulk=pb.BulkReadReply(
+                    results=[
+                        pb.BulkReadResult(
+                            tag_address="Tank01.Level",
+                            was_successful=True,
+                        ),
+                    ],
+                ),
+            ),
+        ],
+    )
+    _install_fake_connect(monkeypatch, stub)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        main,
+        [
+            "read-bulk",
+            "--endpoint",
+            "localhost:5000",
+            "--plaintext",
+            "--session-id",
+            "session-1",
+            "--server-handle",
+            "12",
+            "--items",
+            "Tank01.Level",
+            "--timeout-ms",
+            "1500",
+            "--json",
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["results"][0]["tagAddress"] == "Tank01.Level"
+
+
+def test_cli_write_bulk_happy_path(monkeypatch) -> None:
+    stub = _BulkFakeStub()
+    stub.set_invoke_replies(
+        [
+            pb.MxCommandReply(
+                session_id="session-1",
+                kind=pb.MX_COMMAND_KIND_WRITE_BULK,
+                protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+                write_bulk=pb.BulkWriteReply(
+                    results=[pb.BulkWriteResult(was_successful=True)],
+                ),
+            ),
+        ],
+    )
+    _install_fake_connect(monkeypatch, stub)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        main,
+        [
+            "write-bulk",
+            "--endpoint",
+            "localhost:5000",
+            "--plaintext",
+            "--session-id",
+            "session-1",
+            "--server-handle",
+            "12",
+            "--item-handles",
+            "34",
+            "--values",
+            "123",
+            "--type",
+            "int32",
+            "--json",
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["results"][0]["wasSuccessful"] is True
+    cmd = stub.invoke.requests[0].command
+    assert cmd.kind == pb.MX_COMMAND_KIND_WRITE_BULK
+
+
+def test_cli_stream_alarms_happy_path(monkeypatch) -> None:
+    transitions = [
+        pb.AlarmFeedMessage(
+            transition=pb.OnAlarmTransitionEvent(
+                alarm_full_reference="Tank01.Level.HiHi",
+                transition_kind=pb.ALARM_TRANSITION_KIND_RAISE,
+            ),
+        ),
+    ]
+    stream = _AlarmFakeStream(transitions)
+    stub = _BulkFakeStub()
+    stub.set_alarm_stream(stream)
+    _install_fake_connect(monkeypatch, stub)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        main,
+        [
+            "stream-alarms",
+            "--endpoint",
+            "localhost:5000",
+            "--plaintext",
+            "--max-messages",
+            "1",
+            "--timeout",
+            "5.0",
+            "--filter-prefix",
+            "Tank01.",
+            "--json",
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["messages"][0]["transition"]["alarmFullReference"] == "Tank01.Level.HiHi"
+
+
+def test_cli_acknowledge_alarm_happy_path(monkeypatch) -> None:
+    stub = _BulkFakeStub()
+    stub.acknowledge_alarm = _BulkFakeUnary(
+        [
+            pb.AcknowledgeAlarmReply(
+                correlation_id="corr-1",
+                protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+                status=pb.MxStatusProxy(success=1, category=pb.MX_STATUS_CATEGORY_OK),
+            ),
+        ],
+    )
+    stub.AcknowledgeAlarm = stub.acknowledge_alarm
+    _install_fake_connect(monkeypatch, stub)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        main,
+        [
+            "acknowledge-alarm",
+            "--endpoint",
+            "localhost:5000",
+            "--plaintext",
+            "--reference",
+            "Tank01.Level.HiHi",
+            "--comment",
+            "investigating",
+            "--operator",
+            "alice",
+            "--json",
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    captured_request = stub.acknowledge_alarm.requests[0]
+    assert captured_request.alarm_full_reference == "Tank01.Level.HiHi"
+    assert captured_request.comment == "investigating"
+    assert captured_request.operator_user == "alice"
+
+
+# ---------------------------------------------------------------------------
+# Client.Python-026 — `import time` at module scope; tighter cleanup excepts.
+# ---------------------------------------------------------------------------
+
+
+def test_commands_module_imports_time_at_module_scope() -> None:
+    """`time` must be imported at module scope, not inside `_bench_read_bulk`.
+
+    `inspect.getsource(_bench_read_bulk)` must not contain a function-local
+    ``import time`` statement.
+    """
+
+    import inspect
+
+    source = inspect.getsource(cli_commands._bench_read_bulk)
+    # The function body must NOT contain a function-local `import time` line.
+    for line in source.splitlines():
+        stripped = line.strip()
+        assert stripped != "import time", (
+            f"_bench_read_bulk must not have function-local `import time`: {line!r}"
+        )
+
+    # And the module-level `time` attribute must be present.
+    assert hasattr(cli_commands, "time"), (
+        "`time` must be imported at module scope on commands.py"
+    )
+    assert cli_commands.time is _time_module_ref
+
+
+def test_commands_module_bench_read_bulk_does_not_use_bare_except_pass() -> None:
+    """The two `except Exception: pass` cleanup blocks in `_bench_read_bulk`
+    must be removed in favour of either logging or a narrower exception class.
+    """
+
+    import inspect
+
+    source = inspect.getsource(cli_commands._bench_read_bulk)
+    # Reject the bare `except Exception:` followed by `pass` pattern in
+    # `_bench_read_bulk`. We tolerate `except Exception as <name>:` because the
+    # fix logs the exception.
+    pattern = re.compile(r"except\s+Exception\s*:\s*\n\s*pass\b")
+    assert not pattern.search(source), (
+        "_bench_read_bulk cleanup blocks must log or narrow the except clause"
+    )

clients/python/tests/test_review_findings_032_to_036.py

@@ -0,0 +1,131 @@
+"""Regression tests for Client.Python-032..036.
+
+Each test corresponds to a finding from the 2026-06-16 re-review. Tests are
+TDD-first — they fail against the pre-fix source and pass against the fixed
+source.
+"""
+
+from __future__ import annotations
+
+import inspect
+import re
+from pathlib import Path
+
+import click
+import pytest
+
+from zb_mom_ww_mxgateway_cli import commands as cli_commands
+from zb_mom_ww_mxgateway_cli.commands import _parse_int_list, _parse_string_list
+
+
+# ---------------------------------------------------------------------------
+# Client.Python-032 — `_smoke` must not carry the dead `closed` guard variable.
+# ---------------------------------------------------------------------------
+
+
+def test_smoke_does_not_carry_dead_closed_guard() -> None:
+    """`_smoke` must not reintroduce the dead `closed = False` / `if not closed`
+    guard removed by Client.Python-004. The variable is never reassigned, so the
+    guard misleads readers into expecting an early-close path that never exists.
+    """
+
+    source = inspect.getsource(cli_commands._smoke)
+    assert "closed = False" not in source, (
+        "_smoke must not reintroduce the dead `closed = False` variable"
+    )
+    assert "if not closed:" not in source, (
+        "_smoke must not reintroduce the dead `if not closed:` guard"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Client.Python-033 — `_parse_string_list` param_hint must reflect the caller.
+# ---------------------------------------------------------------------------
+
+
+def test_parse_string_list_default_param_hint_is_items() -> None:
+    with pytest.raises(click.BadParameter) as exc:
+        _parse_string_list("")
+    assert exc.value.param_hint == "--items"
+
+
+def test_parse_string_list_accepts_caller_supplied_param_hint() -> None:
+    """The write-bulk family passes `--values`, so an empty value must surface a
+    `--values` hint, not the irrelevant `--items` default.
+    """
+
+    with pytest.raises(click.BadParameter) as exc:
+        _parse_string_list("", param_hint="--values")
+    assert exc.value.param_hint == "--values"
+
+
+# ---------------------------------------------------------------------------
+# Client.Python-034 — `_parse_int_list` must re-raise non-numeric tokens as
+# click.BadParameter, not a raw ValueError traceback.
+# ---------------------------------------------------------------------------
+
+
+def test_parse_int_list_non_numeric_raises_bad_parameter() -> None:
+    with pytest.raises(click.BadParameter) as exc:
+        _parse_int_list("10,abc")
+    assert exc.value.param_hint == "--item-handles"
+
+
+def test_parse_int_list_happy_path() -> None:
+    assert _parse_int_list("10, 20 ,30") == [10, 20, 30]
+
+
+# ---------------------------------------------------------------------------
+# Client.Python-035 — public browse types must be re-exported from the package
+# root.
+# ---------------------------------------------------------------------------
+
+
+def test_browse_children_options_is_exported_from_package_root() -> None:
+    import zb_mom_ww_mxgateway as pkg
+
+    assert hasattr(pkg, "BrowseChildrenOptions")
+    assert "BrowseChildrenOptions" in pkg.__all__
+
+
+def test_lazy_browse_node_is_exported_from_package_root() -> None:
+    import zb_mom_ww_mxgateway as pkg
+
+    assert hasattr(pkg, "LazyBrowseNode")
+    assert "LazyBrowseNode" in pkg.__all__
+
+
+# ---------------------------------------------------------------------------
+# Client.Python-036 — README "Browsing lazily" example must reference a method
+# that actually exists on GalaxyRepositoryClient.
+# ---------------------------------------------------------------------------
+
+
+def _readme_path() -> Path:
+    return Path(__file__).resolve().parent.parent / "README.md"
+
+
+def test_galaxy_client_exposes_browse_children_raw() -> None:
+    """Guard the method name the README example depends on so future renames
+    break this test rather than only failing at runtime in user code.
+    """
+
+    from zb_mom_ww_mxgateway import GalaxyRepositoryClient
+
+    assert hasattr(GalaxyRepositoryClient, "browse_children_raw")
+
+
+def test_readme_browse_example_uses_existing_method() -> None:
+    """The README's `galaxy.<method>(...BrowseChildrenRequest...)` call must name
+    a method that exists on GalaxyRepositoryClient.
+    """
+
+    from zb_mom_ww_mxgateway import GalaxyRepositoryClient
+
+    text = _readme_path().read_text(encoding="utf-8")
+    called = set(re.findall(r"galaxy\.([A-Za-z_][A-Za-z0-9_]*)\s*\(", text))
+    assert called, "README must contain at least one galaxy.<method>(...) example"
+    for method in called:
+        assert hasattr(GalaxyRepositoryClient, method), (
+            f"README references galaxy.{method}() but no such method exists"
+        )

clients/python/tests/test_review_findings_037_038.py

@@ -0,0 +1,163 @@
+"""Regression tests for Client.Python-037 and Client.Python-038.
+
+Client.Python-037: ``pyproject.toml`` description must not contain "scaffold".
+Client.Python-038: ``advise-supervisory`` CLI subcommand must have coverage
+                   (registration smoke test + happy-path command-shape test).
+
+Tests are TDD-first — written before the fix and expected to pass once the
+source change lands.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from click.testing import CliRunner
+
+from zb_mom_ww_mxgateway import ClientOptions, GatewayClient
+from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2 as pb
+from zb_mom_ww_mxgateway_cli.commands import main
+
+
+# ---------------------------------------------------------------------------
+# Client.Python-037 — pyproject.toml description must not contain "scaffold".
+# ---------------------------------------------------------------------------
+
+
+def test_pyproject_description_does_not_contain_scaffold() -> None:
+    """The ``description`` field in ``pyproject.toml`` must not include the
+    word "scaffold" — a regression of Client.Python-001 that re-entered the
+    file at the package-rename commit.
+    """
+
+    pyproject = (
+        Path(__file__).resolve().parent.parent / "pyproject.toml"
+    ).read_text(encoding="utf-8")
+
+    # Find the description line and assert "scaffold" is absent.
+    for line in pyproject.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("description"):
+            assert "scaffold" not in stripped.lower(), (
+                f"pyproject.toml description must not contain 'scaffold': {stripped!r}"
+            )
+            return
+
+    raise AssertionError("pyproject.toml has no 'description' line")
+
+
+# ---------------------------------------------------------------------------
+# Client.Python-038 — advise-supervisory must be registered + have a happy path.
+# ---------------------------------------------------------------------------
+
+
+def test_advise_supervisory_is_registered() -> None:
+    """``advise-supervisory`` must be a registered subcommand of ``main``.
+
+    A ``--help`` invocation must exit 0 and the help text must include the
+    required options (--server-handle and --item-handle).
+    """
+
+    runner = CliRunner()
+    result = runner.invoke(main, ["advise-supervisory", "--help"])
+
+    assert result.exit_code == 0, result.output
+    assert "--server-handle" in result.output
+    assert "--item-handle" in result.output
+
+
+# --------------- fake-stub infrastructure (mirrors test_review_findings_022_to_026) ----
+
+
+class _FakeUnary:
+    def __init__(self, replies: list[Any]) -> None:
+        self.replies = replies
+        self.requests: list[Any] = []
+        self.metadata: tuple[tuple[str, str], ...] | None = None
+
+    async def __call__(self, request: Any, *, metadata: tuple[tuple[str, str], ...]) -> Any:
+        self.requests.append(request)
+        self.metadata = metadata
+        return self.replies.pop(0)
+
+
+class _FakeStub:
+    def __init__(self) -> None:
+        self.open_session = _FakeUnary(
+            [
+                pb.OpenSessionReply(
+                    session_id="session-1",
+                    protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+                ),
+            ],
+        )
+        self.invoke = _FakeUnary([])
+        self.OpenSession = self.open_session
+        self.Invoke = self.invoke
+
+    def set_invoke_replies(self, replies: list[Any]) -> None:
+        self.invoke.replies = replies
+
+
+def _install_fake_connect(monkeypatch: Any, stub: _FakeStub) -> None:
+    """Patch ``GatewayClient.connect`` so the CLI uses the supplied fake stub."""
+
+    real_connect = GatewayClient.connect
+
+    @classmethod  # type: ignore[misc]
+    async def _spy_connect(cls: Any, options: ClientOptions, **kwargs: Any) -> GatewayClient:
+        return await real_connect(options, stub=stub)
+
+    monkeypatch.setattr(GatewayClient, "connect", _spy_connect)
+
+
+def test_cli_advise_supervisory_happy_path(monkeypatch: Any) -> None:
+    """``advise-supervisory`` must forward server_handle and item_handle in an
+    ``MX_COMMAND_KIND_ADVISE_SUPERVISORY`` ``MxCommand``.
+
+    Pattern mirrors ``test_cli_acknowledge_alarm_happy_path`` in
+    ``test_review_findings_022_to_026.py``.
+    """
+
+    stub = _FakeStub()
+    stub.set_invoke_replies(
+        [
+            pb.MxCommandReply(
+                session_id="session-1",
+                kind=pb.MX_COMMAND_KIND_ADVISE_SUPERVISORY,
+                protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+            ),
+        ],
+    )
+    _install_fake_connect(monkeypatch, stub)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        main,
+        [
+            "advise-supervisory",
+            "--endpoint",
+            "localhost:5000",
+            "--plaintext",
+            "--session-id",
+            "session-1",
+            "--server-handle",
+            "7",
+            "--item-handle",
+            "42",
+            "--json",
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["ok"] is True
+
+    # Verify the MxCommand shape forwarded to the gateway.
+    assert len(stub.invoke.requests) == 1
+    cmd = stub.invoke.requests[0].command
+    assert cmd.kind == pb.MX_COMMAND_KIND_ADVISE_SUPERVISORY
+    assert cmd.advise_supervisory.server_handle == 7
+    assert cmd.advise_supervisory.item_handle == 42

clients/python/tests/test_tls.py

@@ -0,0 +1,176 @@
+"""TLS behaviour tests for ``create_channel``.
+
+These spin up a real loopback ``grpc.aio`` server with a freshly generated
+self-signed certificate (carrying a ``localhost`` SAN, mirroring the gateway's
+auto-generated cert) and assert the lenient TOFU default lets a client connect
+without any CA configured.
+
+Marked ``tls`` and skipped unless ``MXGATEWAY_RUN_TLS_TESTS=1`` because loopback
+TLS handshakes can be timing-flaky on shared CI runners. This mirrors how the
+suite gates anything that depends on real sockets rather than fakes.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import socket
+import ssl
+import subprocess
+import tempfile
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+import grpc
+import pytest
+import pytest_asyncio
+
+from zb_mom_ww_mxgateway import ClientOptions
+from zb_mom_ww_mxgateway.errors import MxGatewayTransportError
+from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2 as pb
+from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2_grpc as pb_grpc
+from zb_mom_ww_mxgateway.options import create_channel
+
+pytestmark = pytest.mark.tls
+
+_RUN_TLS_TESTS = os.environ.get("MXGATEWAY_RUN_TLS_TESTS") == "1"
+_OPENSSL = shutil.which("openssl")
+
+requires_tls = pytest.mark.skipif(
+    not _RUN_TLS_TESTS,
+    reason="set MXGATEWAY_RUN_TLS_TESTS=1 to run loopback TLS tests",
+)
+requires_openssl = pytest.mark.skipif(
+    _OPENSSL is None,
+    reason="openssl CLI is required to generate a self-signed test certificate",
+)
+
+
+def _generate_self_signed_cert(directory: Path) -> tuple[Path, Path]:
+    """Generate a self-signed cert/key pair with a ``localhost`` SAN."""
+    key_path = directory / "server.key"
+    cert_path = directory / "server.crt"
+    subprocess.run(
+        [
+            str(_OPENSSL),
+            "req",
+            "-x509",
+            "-newkey",
+            "rsa:2048",
+            "-nodes",
+            "-keyout",
+            str(key_path),
+            "-out",
+            str(cert_path),
+            "-days",
+            "1",
+            "-subj",
+            "/CN=mxgateway-test",
+            "-addext",
+            "subjectAltName=DNS:localhost,IP:127.0.0.1",
+        ],
+        check=True,
+        capture_output=True,
+    )
+    return cert_path, key_path
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return int(sock.getsockname()[1])
+
+
+class _StaticGatewayServicer(pb_grpc.MxAccessGatewayServicer):
+    """Minimal servicer answering ``OpenSession`` with a fixed session id."""
+
+    async def OpenSession(  # noqa: N802 - generated gRPC method name
+        self, request: pb.OpenSessionRequest, context: object
+    ) -> pb.OpenSessionReply:
+        return pb.OpenSessionReply(session_id="tls-session-1")
+
+
+@pytest_asyncio.fixture
+async def tls_server() -> AsyncIterator[int]:
+    with tempfile.TemporaryDirectory() as tmp:
+        cert_path, key_path = _generate_self_signed_cert(Path(tmp))
+        credentials = grpc.ssl_server_credentials(
+            [(key_path.read_bytes(), cert_path.read_bytes())]
+        )
+        server = grpc.aio.server()
+        pb_grpc.add_MxAccessGatewayServicer_to_server(_StaticGatewayServicer(), server)
+        port = _free_port()
+        server.add_secure_port(f"127.0.0.1:{port}", credentials)
+        await server.start()
+        try:
+            yield port
+        finally:
+            await server.stop(grace=None)
+
+
+@requires_tls
+@requires_openssl
+@pytest.mark.asyncio
+async def test_default_tls_connects_via_tofu(tls_server: int) -> None:
+    """Default TLS options (no CA) connect by pinning the presented cert."""
+    options = ClientOptions(
+        endpoint=f"127.0.0.1:{tls_server}",
+        api_key="mxgw_test_secret",
+    )
+    channel = create_channel(options)
+    try:
+        stub = pb_grpc.MxAccessGatewayStub(channel)
+        reply = await stub.OpenSession(pb.OpenSessionRequest(), timeout=10)
+        assert reply.session_id == "tls-session-1"
+    finally:
+        await channel.close()
+
+
+def test_split_authority_parses_host_and_port() -> None:
+    from zb_mom_ww_mxgateway.options import _split_authority
+
+    assert _split_authority("https://10.0.0.5:5120") == ("10.0.0.5", 5120)
+    assert _split_authority("localhost:5120") == ("localhost", 5120)
+    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
+
+    # Bracketed IPv6 with port — brackets must be removed for ssl.get_server_certificate
+    assert _split_authority("[::1]:5120") == ("::1", 5120)
+    # Bare bracketed IPv6 (no port) — default port 443
+    assert _split_authority("[::1]") == ("::1", 443)
+    # Scheme-prefixed bracketed IPv6
+    assert _split_authority("grpc://[::1]:5120") == ("::1", 5120)
+
+
+def test_tofu_connect_failure_raises_transport_error() -> None:
+    """A failed cert pre-fetch surfaces the client's transport error type."""
+    options = ClientOptions(endpoint=f"127.0.0.1:{_free_port()}")
+    with pytest.raises(MxGatewayTransportError) as excinfo:
+        create_channel(options)
+    assert options.endpoint in str(excinfo.value)
+
+
+def test_require_certificate_validation_uses_system_trust() -> None:
+    """``require_certificate_validation`` must not attempt a TOFU pre-fetch."""
+    # Pointing at a closed port: with system-trust the channel is created lazily
+    # (no eager pre-fetch), so create_channel must succeed without connecting.
+    options = ClientOptions(
+        endpoint=f"127.0.0.1:{_free_port()}",
+        require_certificate_validation=True,
+    )
+    channel = create_channel(options)
+    assert isinstance(channel, grpc.aio.Channel)

clients/python/tests/test_write_array_elements.py

@@ -0,0 +1,209 @@
+"""Tests for Session.write_array_elements default-fill sparse-array helper."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from zb_mom_ww_mxgateway import ClientOptions, GatewayClient
+from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2 as pb
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_sparse_mx_value(
+    element_data_type: "pb.MxDataType.ValueType",
+    total_length: int,
+    elements: dict[int, Any],
+) -> pb.MxValue:
+    """Build an MxValue wrapping an MxSparseArray from Python primitives.
+
+    Mirrors the logic inside Session.write_array_elements so tests can assert
+    the exact wire shape the helper produces without going through the full
+    gRPC stack.
+    """
+    from zb_mom_ww_mxgateway.values import to_mx_value
+
+    return pb.MxValue(
+        sparse_array_value=pb.MxSparseArray(
+            element_data_type=element_data_type,
+            total_length=total_length,
+            elements=[
+                pb.MxSparseElement(index=idx, value=to_mx_value(val))
+                for idx, val in elements.items()
+            ],
+        )
+    )
+
+
+# ---------------------------------------------------------------------------
+# Fake stub (minimal — only needs Invoke / OpenSession)
+# ---------------------------------------------------------------------------
+
+
+class _FakeUnary:
+    def __init__(self, replies: list[Any]) -> None:
+        self.replies = list(replies)
+        self.requests: list[Any] = []
+        self.metadata: tuple[tuple[str, str], ...] | None = None
+
+    async def __call__(
+        self,
+        request: Any,
+        *,
+        metadata: tuple[tuple[str, str], ...],
+    ) -> Any:
+        self.requests.append(request)
+        self.metadata = metadata
+        return self.replies.pop(0)
+
+
+class _FakeStub:
+    """Minimal stub that satisfies GatewayClient for a single invoke round-trip."""
+
+    def __init__(self) -> None:
+        ok = pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK)
+        self.open_session = _FakeUnary([pb.OpenSessionReply(session_id="s1", protocol_status=ok)])
+        self.invoke = _FakeUnary(
+            [
+                pb.MxCommandReply(
+                    session_id="s1",
+                    kind=pb.MX_COMMAND_KIND_WRITE,
+                    protocol_status=ok,
+                ),
+            ]
+        )
+        self.OpenSession = self.open_session
+        self.Invoke = self.invoke
+
+
+# ---------------------------------------------------------------------------
+# Unit tests
+# ---------------------------------------------------------------------------
+
+
+def test_sparse_mx_value_builder_sets_correct_oneof() -> None:
+    """Builder helper must produce an MxValue with kind == 'sparse_array_value'."""
+    mv = _make_sparse_mx_value(pb.MX_DATA_TYPE_INTEGER, 5, {0: 10, 3: 30})
+    assert mv.WhichOneof("kind") == "sparse_array_value"
+
+
+def test_sparse_mx_value_builder_total_length() -> None:
+    """total_length must equal the value passed to the builder."""
+    mv = _make_sparse_mx_value(pb.MX_DATA_TYPE_INTEGER, 20, {1: 7})
+    assert mv.sparse_array_value.total_length == 20
+
+
+def test_sparse_mx_value_builder_element_count_and_values() -> None:
+    """Elements list length and scalar values must match the input dict."""
+    mv = _make_sparse_mx_value(pb.MX_DATA_TYPE_INTEGER, 10, {0: 11, 4: 55, 9: 99})
+    sa = mv.sparse_array_value
+    assert len(sa.elements) == 3
+    by_index = {e.index: e.value for e in sa.elements}
+    assert by_index[0].int32_value == 11
+    assert by_index[4].int32_value == 55
+    assert by_index[9].int32_value == 99
+
+
+def test_sparse_mx_value_builder_element_data_type() -> None:
+    """element_data_type must be forwarded verbatim."""
+    mv = _make_sparse_mx_value(pb.MX_DATA_TYPE_FLOAT, 3, {})
+    assert mv.sparse_array_value.element_data_type == pb.MX_DATA_TYPE_FLOAT
+
+
+def test_sparse_mx_value_builder_empty_elements() -> None:
+    """An empty elements dict must still produce a valid MxSparseArray."""
+    mv = _make_sparse_mx_value(pb.MX_DATA_TYPE_BOOLEAN, 8, {})
+    sa = mv.sparse_array_value
+    assert len(sa.elements) == 0
+    assert sa.total_length == 8
+
+
+# ---------------------------------------------------------------------------
+# Integration-level: write_array_elements routes through Session.write
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_write_array_elements_sends_sparse_array_write_command() -> None:
+    """write_array_elements must send a WRITE command whose value is sparse_array_value."""
+    stub = _FakeStub()
+    client = await GatewayClient.connect(
+        ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
+        stub=stub,
+    )
+    session = await client.open_session()
+
+    await session.write_array_elements(
+        server_handle=1,
+        item_handle=2,
+        element_data_type=pb.MX_DATA_TYPE_INTEGER,
+        total_length=10,
+        elements={0: 100, 5: 500},
+    )
+
+    assert len(stub.invoke.requests) == 1
+    cmd_req: pb.MxCommandRequest = stub.invoke.requests[0]
+    cmd = cmd_req.command
+    assert cmd.kind == pb.MX_COMMAND_KIND_WRITE
+    mv = cmd.write.value
+    assert mv.WhichOneof("kind") == "sparse_array_value"
+
+    sa = mv.sparse_array_value
+    assert sa.element_data_type == pb.MX_DATA_TYPE_INTEGER
+    assert sa.total_length == 10
+    assert len(sa.elements) == 2
+    by_index = {e.index: e.value for e in sa.elements}
+    assert by_index[0].int32_value == 100
+    assert by_index[5].int32_value == 500
+
+
+@pytest.mark.asyncio
+async def test_write_array_elements_forwards_user_id() -> None:
+    """user_id must reach the WriteCommand."""
+    stub = _FakeStub()
+    client = await GatewayClient.connect(
+        ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
+        stub=stub,
+    )
+    session = await client.open_session()
+
+    await session.write_array_elements(
+        server_handle=1,
+        item_handle=2,
+        element_data_type=pb.MX_DATA_TYPE_BOOLEAN,
+        total_length=4,
+        elements={},
+        user_id=42,
+    )
+
+    cmd = stub.invoke.requests[0].command
+    assert cmd.write.user_id == 42
+
+
+@pytest.mark.asyncio
+async def test_write_array_elements_string_elements() -> None:
+    """String element values must be encoded as string_value scalars."""
+    stub = _FakeStub()
+    client = await GatewayClient.connect(
+        ClientOptions(endpoint="fake", api_key="mxgw_test_secret", plaintext=True),
+        stub=stub,
+    )
+    session = await client.open_session()
+
+    await session.write_array_elements(
+        server_handle=1,
+        item_handle=2,
+        element_data_type=pb.MX_DATA_TYPE_STRING,
+        total_length=3,
+        elements={1: "hello", 2: "world"},
+    )
+
+    sa = stub.invoke.requests[0].command.write.value.sparse_array_value
+    by_index = {e.index: e.value for e in sa.elements}
+    assert by_index[1].string_value == "hello"
+    assert by_index[2].string_value == "world"