chore(clients): bump all five clients 0.1.1 -> 0.1.2 for MxSparseArray release

Commit 0702551 regenerated all three protos with grpcio-tools 1.81.1 /
protobuf 6.33.5, stamping every _pb2_grpc.py with GRPC_GENERATED_VERSION
'1.81.1' and every _pb2.py with 'Protobuf Python Version: 6.33.5'.  The
project pins grpcio>=1.80,<2 and the installed runtime is 1.80.0, so the
1.81.1 stamp caused a version error at import time, breaking pytest.

Fix: restore all generated files to the main baseline (grpcio 1.80.0,
protobuf 6.31.1 stamps), then regenerate only mxaccess_gateway.proto
using an isolated venv pinned to grpcio==1.80.0, grpcio-tools==1.80.0,
protobuf==6.31.1.  The net diff vs main is a single-file change to
mxaccess_gateway_pb2.py whose DESCRIPTOR blob now encodes the new
MxSparseArray / MxSparseElement messages and sparse_array_value field.
No _pb2_grpc.py and no galaxy/worker _pb2.py files change.

.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

@@ -121,6 +121,77 @@ 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 at `AddItem`
+so the array attribute accepts the write.
+
 ## CLI Usage
 
 The test CLI supports deterministic JSON output for automation:
@@ -196,6 +267,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
@@ -239,6 +371,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:
@@ -251,6 +394,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>
@@ -105,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

@@ -100,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.Cli/MxGatewayClientCli.cs

@@ -110,6 +110,8 @@ public static class MxGatewayClientCli
                     .ConfigureAwait(false),
                 "advise" => await AdviseAsync(arguments, client, standardOutput, cancellation.Token)
                     .ConfigureAwait(false),
+                "advise-supervisory" => await AdviseSupervisoryAsync(arguments, client, standardOutput, cancellation.Token)
+                    .ConfigureAwait(false),
                 "subscribe-bulk" => await SubscribeBulkAsync(arguments, client, standardOutput, cancellation.Token)
                     .ConfigureAwait(false),
                 "unsubscribe-bulk" => await UnsubscribeBulkAsync(arguments, client, standardOutput, cancellation.Token)
@@ -144,6 +146,8 @@ public static class MxGatewayClientCli
                     .ConfigureAwait(false),
                 "galaxy-discover" => await GalaxyDiscoverAsync(arguments, client, standardOutput, cancellation.Token)
                     .ConfigureAwait(false),
+                "galaxy-browse" => await GalaxyBrowseAsync(arguments, client, standardOutput, standardError, cancellation.Token)
+                    .ConfigureAwait(false),
                 "galaxy-watch" => await GalaxyWatchAsync(arguments, client, standardOutput, cancellation.Token)
                     .ConfigureAwait(false),
                 _ => WriteUnknownCommand(command, standardError),
@@ -151,7 +155,10 @@ public static class MxGatewayClientCli
         }
         catch (Exception exception) when (exception is not OperationCanceledException)
         {
-            string? apiKey = arguments.GetOptional("api-key");
+            // Client.Dotnet-028: redact the *effective* key — from --api-key or the
+            // --api-key-env environment variable — so an env-var-sourced key echoed
+            // in a transport error never reaches stderr unredacted.
+            string? apiKey = TryResolveApiKey(arguments);
             string message = MxGatewayCliSecretRedactor.Redact(exception.Message, apiKey);
 
             if (forceJsonErrors || arguments.HasFlag("json"))
@@ -276,6 +283,29 @@ public static class MxGatewayClientCli
     }
 
     private static string ResolveApiKey(CliArguments arguments)
+    {
+        string? apiKey = TryResolveApiKey(arguments);
+        if (!string.IsNullOrWhiteSpace(apiKey))
+        {
+            return apiKey;
+        }
+
+        string apiKeyEnvironmentName = arguments.GetOptional("api-key-env")
+            ?? "MXGATEWAY_API_KEY";
+
+        throw new ArgumentException(
+            $"Gateway API key is required. Pass --api-key or set {apiKeyEnvironmentName}.");
+    }
+
+    /// <summary>
+    ///     Resolves the effective API key from <c>--api-key</c> or, failing that,
+    ///     the <c>--api-key-env</c>-named environment variable (default
+    ///     <c>MXGATEWAY_API_KEY</c>), returning <see langword="null"/> when neither
+    ///     is set. Unlike <see cref="ResolveApiKey"/> this never throws, so the
+    ///     error-redaction catch block can strip the env-var-sourced key from
+    ///     output (Client.Dotnet-028) without re-raising on the absent-key path.
+    /// </summary>
+    private static string? TryResolveApiKey(CliArguments arguments)
     {
         string? apiKey = arguments.GetOptional("api-key");
         if (!string.IsNullOrWhiteSpace(apiKey))
@@ -286,14 +316,7 @@ public static class MxGatewayClientCli
         string apiKeyEnvironmentName = arguments.GetOptional("api-key-env")
             ?? "MXGATEWAY_API_KEY";
 
-        apiKey = Environment.GetEnvironmentVariable(apiKeyEnvironmentName);
-        if (!string.IsNullOrWhiteSpace(apiKey))
-        {
-            return apiKey;
-        }
-
-        throw new ArgumentException(
-            $"Gateway API key is required. Pass --api-key or set {apiKeyEnvironmentName}.");
+        return Environment.GetEnvironmentVariable(apiKeyEnvironmentName);
     }
 
     private static CancellationTokenSource CreateCancellation(CliArguments arguments, string command)
@@ -301,7 +324,7 @@ public static class MxGatewayClientCli
         var cancellation = new CancellationTokenSource();
         // Long-running streaming commands run until Ctrl+C / cancellation by default;
         // a caller-supplied --timeout still applies if present.
-        bool isLongRunning = command is "galaxy-watch";
+        bool isLongRunning = command is "galaxy-watch" or "galaxy-browse";
         string? rawTimeout = arguments.GetOptional("timeout");
         if (isLongRunning && string.IsNullOrWhiteSpace(rawTimeout))
         {
@@ -430,6 +453,28 @@ public static class MxGatewayClientCli
             cancellationToken);
     }
 
+    private static Task<int> AdviseSupervisoryAsync(
+        CliArguments arguments,
+        IMxGatewayCliClient client,
+        TextWriter output,
+        CancellationToken cancellationToken)
+    {
+        return InvokeAndWriteAsync(
+            arguments,
+            client,
+            output,
+            new MxCommand
+            {
+                Kind = MxCommandKind.AdviseSupervisory,
+                AdviseSupervisory = new AdviseSupervisoryCommand
+                {
+                    ServerHandle = arguments.GetInt32("server-handle"),
+                    ItemHandle = arguments.GetInt32("item-handle"),
+                },
+            },
+            cancellationToken);
+    }
+
     private static Task<int> SubscribeBulkAsync(
         CliArguments arguments,
         IMxGatewayCliClient client,
@@ -1607,6 +1652,270 @@ public static class MxGatewayClientCli
         return aggregate;
     }
 
+    /// <summary>
+    ///     Per-request page size for the galaxy-browse single-level walks. Mirrors
+    ///     the library's <c>BrowseChildrenPageSize</c> so the CLI and the
+    ///     lazy-browse helper page identically.
+    /// </summary>
+    private const int BrowseChildrenCliPageSize = 500;
+
+    /// <summary>
+    ///     Drives the lazy-browse Galaxy surface from the CLI. Without
+    ///     <c>--parent</c> it walks the root objects and eagerly expands
+    ///     <c>--depth</c> further levels (each level reuses the same
+    ///     <see cref="BrowseChildrenOptions"/>, like the library helper). With
+    ///     <c>--parent</c> it fetches exactly one level of children for that
+    ///     gobject id via a parent-scoped BrowseChildren request; <c>--depth</c>
+    ///     is not meaningful there and a warning is emitted if combined, mirroring
+    ///     the Go/Rust CLIs.
+    /// </summary>
+    private static async Task<int> GalaxyBrowseAsync(
+        CliArguments arguments,
+        IMxGatewayCliClient client,
+        TextWriter output,
+        TextWriter standardError,
+        CancellationToken cancellationToken)
+    {
+        BrowseChildrenOptions options = ParseBrowseChildrenOptions(arguments);
+        bool json = arguments.HasFlag("json");
+        int parent = arguments.GetInt32("parent", -1);
+        int depth = arguments.GetInt32("depth", 0);
+
+        // A specific parent → one level of children via the parent-scoped RPC.
+        if (parent >= 0)
+        {
+            if (depth > 0)
+            {
+                standardError.WriteLine("warning: --depth is ignored when --parent is specified.");
+            }
+
+            IReadOnlyList<GalaxyObject> children = await BrowseOneLevelAsync(
+                    client,
+                    options,
+                    parent,
+                    cancellationToken)
+                .ConfigureAwait(false);
+
+            if (json)
+            {
+                output.WriteLine(JsonSerializer.Serialize(
+                    new
+                    {
+                        command = "galaxy-browse",
+                        parentId = parent,
+                        children = children.Select(GalaxyObjectToJsonElement).ToArray(),
+                    },
+                    JsonOptions));
+                return 0;
+            }
+
+            output.WriteLine(children.Count.ToString(CultureInfo.InvariantCulture));
+            foreach (GalaxyObject child in children)
+            {
+                output.WriteLine(FormatGalaxyObject(child, level: 0, hasChildrenHint: null));
+            }
+
+            return 0;
+        }
+
+        // No parent → walk the root objects, eagerly expanding --depth levels.
+        IReadOnlyList<BrowseTreeNode> roots = await BrowseTreeAsync(
+                client,
+                options,
+                parentGobjectId: 0,
+                remainingDepth: depth,
+                cancellationToken)
+            .ConfigureAwait(false);
+
+        if (json)
+        {
+            output.WriteLine(JsonSerializer.Serialize(
+                new
+                {
+                    command = "galaxy-browse",
+                    nodes = roots.Select(BrowseTreeNodeToJson).ToArray(),
+                },
+                JsonOptions));
+            return 0;
+        }
+
+        output.WriteLine(roots.Count.ToString(CultureInfo.InvariantCulture));
+        foreach (BrowseTreeNode node in roots)
+        {
+            WriteBrowseTreeNode(output, node, level: 0);
+        }
+
+        return 0;
+    }
+
+    /// <summary>
+    ///     One node in the eagerly-expanded galaxy-browse tree: the Galaxy object,
+    ///     the server's has-children hint, and any children fetched up to the
+    ///     requested depth.
+    /// </summary>
+    private sealed record BrowseTreeNode(
+        GalaxyObject Object,
+        bool HasChildrenHint,
+        IReadOnlyList<BrowseTreeNode> Children);
+
+    /// <summary>
+    ///     Fetches the direct children of <paramref name="parentGobjectId"/>
+    ///     (0 = root) and recursively expands <paramref name="remainingDepth"/>
+    ///     further levels. Paging is followed to completion at each level.
+    /// </summary>
+    private static async Task<IReadOnlyList<BrowseTreeNode>> BrowseTreeAsync(
+        IMxGatewayCliClient client,
+        BrowseChildrenOptions options,
+        int parentGobjectId,
+        int remainingDepth,
+        CancellationToken cancellationToken)
+    {
+        List<BrowseTreeNode> nodes = [];
+        string pageToken = string.Empty;
+        HashSet<string> seenPageTokens = new(StringComparer.Ordinal);
+        do
+        {
+            BrowseChildrenRequest request = BuildBrowseChildrenRequest(options, parentGobjectId, pageToken);
+            BrowseChildrenReply reply = await client.GalaxyBrowseChildrenAsync(request, cancellationToken)
+                .ConfigureAwait(false);
+
+            for (int i = 0; i < reply.Children.Count; i++)
+            {
+                GalaxyObject child = reply.Children[i];
+                bool hint = i < reply.ChildHasChildren.Count && reply.ChildHasChildren[i];
+                IReadOnlyList<BrowseTreeNode> grandChildren = remainingDepth > 0
+                    ? await BrowseTreeAsync(client, options, child.GobjectId, remainingDepth - 1, cancellationToken)
+                        .ConfigureAwait(false)
+                    : [];
+                nodes.Add(new BrowseTreeNode(child, hint, grandChildren));
+            }
+
+            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 nodes;
+    }
+
+    /// <summary>Fetches exactly one level of children for a parent gobject id, paging to completion.</summary>
+    private static async Task<IReadOnlyList<GalaxyObject>> BrowseOneLevelAsync(
+        IMxGatewayCliClient client,
+        BrowseChildrenOptions options,
+        int parentGobjectId,
+        CancellationToken cancellationToken)
+    {
+        List<GalaxyObject> children = [];
+        string pageToken = string.Empty;
+        HashSet<string> seenPageTokens = new(StringComparer.Ordinal);
+        do
+        {
+            BrowseChildrenRequest request = BuildBrowseChildrenRequest(options, parentGobjectId, pageToken);
+            BrowseChildrenReply reply = await client.GalaxyBrowseChildrenAsync(request, cancellationToken)
+                .ConfigureAwait(false);
+
+            children.AddRange(reply.Children);
+            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 children;
+    }
+
+    private static BrowseChildrenOptions ParseBrowseChildrenOptions(CliArguments arguments)
+    {
+        return new BrowseChildrenOptions
+        {
+            CategoryIds = ParseOptionalInt32List(arguments.GetOptional("category-ids")),
+            TemplateChainContains = ParseOptionalStringList(arguments.GetOptional("template-contains")),
+            TagNameGlob = arguments.GetOptional("tag-name-glob"),
+            AlarmBearingOnly = arguments.HasFlag("alarm-bearing-only"),
+            HistorizedOnly = arguments.HasFlag("historized-only"),
+            // Tri-state: only override the server default when the flag is present.
+            IncludeAttributes = arguments.HasFlag("include-attributes") ? true : null,
+        };
+    }
+
+    private static BrowseChildrenRequest BuildBrowseChildrenRequest(
+        BrowseChildrenOptions options,
+        int parentGobjectId,
+        string pageToken)
+    {
+        BrowseChildrenRequest request = new()
+        {
+            PageSize = BrowseChildrenCliPageSize,
+            PageToken = pageToken,
+            ParentGobjectId = parentGobjectId,
+            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;
+    }
+
+    private static void WriteBrowseTreeNode(TextWriter output, BrowseTreeNode node, int level)
+    {
+        output.WriteLine(FormatGalaxyObject(node.Object, level, node.HasChildrenHint));
+        foreach (BrowseTreeNode child in node.Children)
+        {
+            WriteBrowseTreeNode(output, child, level + 1);
+        }
+    }
+
+    private static string FormatGalaxyObject(GalaxyObject galaxyObject, int level, bool? hasChildrenHint)
+    {
+        string indent = new(' ', level * 2);
+        string suffix = hasChildrenHint is null
+            ? $"(attrs={galaxyObject.Attributes.Count})"
+            : $"(attrs={galaxyObject.Attributes.Count}, hasChildrenHint={hasChildrenHint.Value})";
+        return $"{indent}{galaxyObject.GobjectId}\t{galaxyObject.TagName}\t{galaxyObject.BrowseName}\t{suffix}";
+    }
+
+    private static object BrowseTreeNodeToJson(BrowseTreeNode node)
+    {
+        return new
+        {
+            @object = GalaxyObjectToJsonElement(node.Object),
+            hasChildrenHint = node.HasChildrenHint,
+            children = node.Children.Select(BrowseTreeNodeToJson).ToArray(),
+        };
+    }
+
+    private static JsonElement GalaxyObjectToJsonElement(GalaxyObject galaxyObject)
+    {
+        return JsonDocument.Parse(ProtobufJsonFormatter.Format(galaxyObject)).RootElement.Clone();
+    }
+
+    private static IReadOnlyList<int> ParseOptionalInt32List(string? value)
+    {
+        return string.IsNullOrWhiteSpace(value) ? [] : ParseInt32List(value);
+    }
+
+    private static IReadOnlyList<string> ParseOptionalStringList(string? value)
+    {
+        return string.IsNullOrWhiteSpace(value) ? [] : ParseStringList(value);
+    }
+
     private static async Task<int> GalaxyWatchAsync(
         CliArguments arguments,
         IMxGatewayCliClient client,
@@ -1736,6 +2045,7 @@ public static class MxGatewayClientCli
             or "galaxy-test-connection"
             or "galaxy-last-deploy"
             or "galaxy-discover"
+            or "galaxy-browse"
             or "galaxy-watch";
     }
 
@@ -1780,6 +2090,7 @@ public static class MxGatewayClientCli
         writer.WriteLine("mxgw-dotnet register --session-id <id> --client-name <name> [--json]");
         writer.WriteLine("mxgw-dotnet add-item --session-id <id> --server-handle <n> --item <ref> [--json]");
         writer.WriteLine("mxgw-dotnet advise --session-id <id> --server-handle <n> --item-handle <n> [--json]");
+        writer.WriteLine("mxgw-dotnet advise-supervisory --session-id <id> --server-handle <n> --item-handle <n> [--json]");
         writer.WriteLine("mxgw-dotnet subscribe-bulk --session-id <id> --server-handle <n> --items <ref,ref> [--json]");
         writer.WriteLine("mxgw-dotnet unsubscribe-bulk --session-id <id> --server-handle <n> --item-handles <n,n> [--json]");
         writer.WriteLine("mxgw-dotnet read-bulk --session-id <id> --server-handle <n> --items <ref,ref> [--timeout-ms <n>] [--json]");
@@ -1797,6 +2108,7 @@ public static class MxGatewayClientCli
         writer.WriteLine("mxgw-dotnet galaxy-test-connection [--json]");
         writer.WriteLine("mxgw-dotnet galaxy-last-deploy [--json]");
         writer.WriteLine("mxgw-dotnet galaxy-discover [--json]");
+        writer.WriteLine("mxgw-dotnet galaxy-browse [--parent <gobject-id>] [--depth <n>] [--category-ids <n,n>] [--template-contains <s,s>] [--tag-name-glob <glob>] [--alarm-bearing-only] [--historized-only] [--include-attributes] [--json]");
         writer.WriteLine("mxgw-dotnet galaxy-watch [--last-seen-deploy-time <iso8601>] [--max-events <n>] [--json]");
     }
 }

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

@@ -196,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)
@@ -219,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)
@@ -234,12 +238,14 @@ 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);
@@ -248,6 +254,8 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
     /// <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)
@@ -263,6 +271,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
     }
 
     /// <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

@@ -106,6 +106,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()
@@ -360,6 +402,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()
@@ -519,6 +701,7 @@ public sealed class MxGatewayClientCliTests
     /// 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")]
@@ -716,6 +899,7 @@ public sealed class MxGatewayClientCliTests
     /// 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")]
@@ -988,6 +1172,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>
@@ -1048,5 +1233,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/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/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

@@ -315,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()
         {
@@ -335,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;
@@ -350,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

@@ -687,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
@@ -91,6 +99,78 @@ 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` /
+`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.
+
+`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` (and `AddItem2`) now auto-normalize a bare 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
@@ -121,6 +201,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
@@ -177,24 +319,78 @@ 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`). |
+| `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
@@ -213,6 +409,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.go

@@ -21,6 +21,7 @@ import (
 	"syscall"
 	"time"
 
+	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
 	"gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/mxgateway"
 	"google.golang.org/protobuf/encoding/protojson"
 	"google.golang.org/protobuf/reflect/protoreflect"
@@ -87,6 +88,8 @@ func runWithIO(ctx context.Context, args []string, stdout, stderr io.Writer) err
 		return runAddItem(ctx, args[1:], stdout, stderr)
 	case "advise":
 		return runAdvise(ctx, args[1:], stdout, stderr)
+	case "advise-supervisory":
+		return runAdviseSupervisory(ctx, args[1:], stdout, stderr)
 	case "subscribe-bulk":
 		return runSubscribeBulk(ctx, args[1:], stdout, stderr)
 	case "unsubscribe-bulk":
@@ -121,6 +124,10 @@ func runWithIO(ctx context.Context, args []string, stdout, stderr io.Writer) err
 		return runGalaxyDiscover(ctx, args[1:], stdout, stderr)
 	case "galaxy-watch":
 		return runGalaxyWatch(ctx, args[1:], stdout, stderr)
+	case "galaxy-browse":
+		return runGalaxyBrowse(ctx, args[1:], stdout, stderr)
+	case "ping":
+		return runPing(ctx, args[1:], stdout, stderr)
 	case "batch":
 		return runBatch(ctx, os.Stdin, stdout, stderr)
 	default:
@@ -228,6 +235,52 @@ func runCloseSession(ctx context.Context, args []string, stdout, stderr io.Write
 	return nil
 }
 
+func runPing(ctx context.Context, args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("ping", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	common := bindCommonFlags(flags)
+	jsonOutput := flags.Bool("json", false, "write JSON output")
+	sessionID := flags.String("session-id", "", "gateway session id")
+	message := flags.String("message", "ping", "ping payload message")
+
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+	if *sessionID == "" {
+		return errors.New("session-id is required")
+	}
+
+	client, options, err := dialForCommand(ctx, common)
+	if err != nil {
+		return err
+	}
+	defer client.Close()
+
+	session := mxgateway.NewSessionForID(client, *sessionID)
+	reply, err := session.PingRaw(ctx, *message)
+	if err != nil {
+		return err
+	}
+	if *jsonOutput {
+		return writeJSON(stdout, commandReplyOutput{
+			Command: "ping",
+			Options: options,
+			Reply:   mustMarshalProto(reply),
+		})
+	}
+	// DiagnosticMessage carries the echoed ping text set by the gateway.
+	// Fall back to the kind string when the gateway returns an empty message
+	// (forward-compat guard for future gateway versions). writeCommandOutput
+	// is not reused here because it would print the opaque Kind enum rather
+	// than the human-readable echo.
+	echo := reply.GetDiagnosticMessage()
+	if echo == "" {
+		echo = reply.GetKind().String()
+	}
+	fmt.Fprintln(stdout, echo)
+	return nil
+}
+
 func runRegister(ctx context.Context, args []string, stdout, stderr io.Writer) error {
 	flags := flag.NewFlagSet("register", flag.ContinueOnError)
 	flags.SetOutput(stderr)
@@ -308,6 +361,43 @@ func runAdvise(ctx context.Context, args []string, stdout, stderr io.Writer) err
 	return writeCommandOutput(stdout, *jsonOutput, "advise", options, reply, err)
 }
 
+func runAdviseSupervisory(ctx context.Context, args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("advise-supervisory", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	common := bindCommonFlags(flags)
+	jsonOutput := flags.Bool("json", false, "write JSON output")
+	sessionID := flags.String("session-id", "", "gateway session id")
+	serverHandle := flags.Int("server-handle", 0, "MXAccess server handle")
+	itemHandle := flags.Int("item-handle", 0, "MXAccess item handle")
+
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+	if *sessionID == "" {
+		return errors.New("session-id is required")
+	}
+
+	client, options, err := dialForCommand(ctx, common)
+	if err != nil {
+		return err
+	}
+	defer client.Close()
+
+	reply, err := client.Invoke(ctx, &pb.MxCommandRequest{
+		SessionId: *sessionID,
+		Command: &pb.MxCommand{
+			Kind: pb.MxCommandKind_MX_COMMAND_KIND_ADVISE_SUPERVISORY,
+			Payload: &pb.MxCommand_AdviseSupervisory{
+				AdviseSupervisory: &pb.AdviseSupervisoryCommand{
+					ServerHandle: int32(*serverHandle),
+					ItemHandle:   int32(*itemHandle),
+				},
+			},
+		},
+	})
+	return writeCommandOutput(stdout, *jsonOutput, "advise-supervisory", options, reply, err)
+}
+
 func runSubscribeBulk(ctx context.Context, args []string, stdout, stderr io.Writer) error {
 	flags := flag.NewFlagSet("subscribe-bulk", flag.ContinueOnError)
 	flags.SetOutput(stderr)
@@ -787,7 +877,14 @@ func runStreamEvents(ctx context.Context, args []string, stdout, stderr io.Write
 	defer client.Close()
 
 	session := mxgateway.NewSessionForID(client, *sessionID)
-	streamCtx, cancelStream := context.WithCancel(ctx)
+
+	// Ctrl+C on a long-running stream-events command cancels the gRPC stream
+	// cleanly (the gateway sees codes.Canceled rather than a torn TCP
+	// connection) and the deferred subscription.Close()/client.Close() run.
+	signalCtx, stopSignals := signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)
+	defer stopSignals()
+
+	streamCtx, cancelStream := context.WithCancel(signalCtx)
 	defer cancelStream()
 	subscription, err := session.SubscribeEventsAfter(streamCtx, *after)
 	if err != nil {
@@ -985,15 +1082,17 @@ func runSmoke(ctx context.Context, args []string, stdout, stderr io.Writer) erro
 }
 
 func closeSmokeSession(ctx context.Context, session *mxgateway.Session, primaryErr error) error {
-	closeCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-	defer cancel()
+	// Compute the close timeout once so a single context (and a single
+	// deferred cancel) is allocated: default 5s, shortened to the caller's
+	// remaining deadline when that is sooner.
+	closeTimeout := 5 * time.Second
 	if deadline, ok := ctx.Deadline(); ok {
-		if until := time.Until(deadline); until > 0 && until < 5*time.Second {
-			cancel()
-			closeCtx, cancel = context.WithTimeout(context.Background(), until)
-			defer cancel()
+		if until := time.Until(deadline); until > 0 && until < closeTimeout {
+			closeTimeout = until
 		}
 	}
+	closeCtx, cancel := context.WithTimeout(context.Background(), closeTimeout)
+	defer cancel()
 
 	_, closeErr := session.Close(closeCtx)
 	if primaryErr != nil {
@@ -1196,7 +1295,7 @@ type protojsonMessage interface {
 }
 
 func writeUsage(writer io.Writer) {
-	fmt.Fprintln(writer, "usage: mxgw-go <version|open-session|close-session|register|add-item|advise|subscribe-bulk|unsubscribe-bulk|read-bulk|write-bulk|write2-bulk|write-secured-bulk|write-secured2-bulk|bench-read-bulk|write|stream-events|stream-alarms|acknowledge-alarm|smoke|galaxy-test-connection|galaxy-last-deploy|galaxy-discover|galaxy-watch|batch>")
+	fmt.Fprintln(writer, "usage: mxgw-go <version|open-session|close-session|ping|register|add-item|advise|subscribe-bulk|unsubscribe-bulk|read-bulk|write-bulk|write2-bulk|write-secured-bulk|write-secured2-bulk|bench-read-bulk|write|stream-events|stream-alarms|acknowledge-alarm|smoke|galaxy-test-connection|galaxy-last-deploy|galaxy-discover|galaxy-watch|galaxy-browse|batch>")
 }
 
 // batchEOR is the end-of-result sentinel emitted to stdout after every command
@@ -1440,6 +1539,12 @@ func runGalaxyWatch(ctx context.Context, args []string, stdout, stderr io.Writer
 			count++
 			if *limit > 0 && count >= *limit {
 				cancelStream()
+				// Drain so the WatchDeployEvents goroutine can exit instead
+				// of blocking on a send into the buffered events channel
+				// while the deferred client.Close() tears the stream down
+				// underneath it (mirrors the signal-cancel branch below).
+				for range events {
+				}
 				return nil
 			}
 		case streamErr, ok := <-errs:
@@ -1459,6 +1564,234 @@ func runGalaxyWatch(ctx context.Context, args []string, stdout, stderr io.Writer
 	}
 }
 
+// runGalaxyBrowse drives the lazy-browse Galaxy helper from the CLI. Without
+// -parent it walks the root objects via GalaxyClient.Browse and eagerly expands
+// -depth further levels (each level reuses the same BrowseChildrenOptions, like
+// the library helper). With -parent it fetches exactly one level of children for
+// that gobject id via a parent-scoped BrowseChildren request; -depth is not
+// meaningful there and a warning is emitted if combined, mirroring the Rust CLI.
+//
+// Filter flags map onto BrowseChildrenOptions: -category-ids and
+// -template-contains are comma-separated lists (matching this CLI's other
+// list-valued flags), -tag-name-glob / -alarm-bearing-only / -historized-only
+// are scalar, and -include-attributes is a tri-state pointer (left nil unless
+// the flag is provided so the server default applies).
+func runGalaxyBrowse(ctx context.Context, args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("galaxy-browse", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	common := bindCommonFlags(flags)
+	jsonOutput := flags.Bool("json", false, "write JSON output")
+	parent := flags.Int("parent", -1, "parent gobject id whose children to browse; omit (or <0) for root objects")
+	depth := flags.Int("depth", 0, "additional levels to eagerly expand beneath each root node; ignored with -parent")
+	categoryIDs := flags.String("category-ids", "", "comma-separated Galaxy category ids to restrict results")
+	templateContains := flags.String("template-contains", "", "comma-separated template tag names the chain must contain")
+	tagNameGlob := flags.String("tag-name-glob", "", "restrict to objects whose tag name matches this glob")
+	alarmBearingOnly := flags.Bool("alarm-bearing-only", false, "restrict to alarm-bearing objects")
+	historizedOnly := flags.Bool("historized-only", false, "restrict to historized objects")
+	includeAttributes := flags.Bool("include-attributes", false, "populate attributes on returned objects (overrides server default)")
+
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+
+	categoryList, err := parseInt32List(*categoryIDs)
+	if err != nil {
+		return err
+	}
+
+	opts := &mxgateway.BrowseChildrenOptions{
+		CategoryIds:           categoryList,
+		TemplateChainContains: parseStringList(*templateContains),
+		TagNameGlob:           *tagNameGlob,
+		AlarmBearingOnly:      *alarmBearingOnly,
+		HistorizedOnly:        *historizedOnly,
+	}
+	// Only override the server default when the flag was actually set; the
+	// pointer form mirrors the proto's optional field.
+	flags.Visit(func(f *flag.Flag) {
+		if f.Name == "include-attributes" {
+			value := *includeAttributes
+			opts.IncludeAttributes = &value
+		}
+	})
+
+	client, options, err := dialGalaxyForCommand(ctx, common)
+	if err != nil {
+		return err
+	}
+	defer client.Close()
+
+	// A specific parent → one level of children via the raw parent-scoped RPC.
+	if *parent >= 0 {
+		if *parent == 0 {
+			fmt.Fprintln(stderr, "warning: -parent 0 is the server root sentinel; omit -parent for the root walk, or use -parent <id> >= 1")
+		}
+		if *depth > 0 {
+			fmt.Fprintln(stderr, "warning: -depth is ignored when -parent is specified")
+		}
+		return runGalaxyBrowseParent(ctx, client, int32(*parent), opts, stdout, *jsonOutput, options)
+	}
+
+	// No parent → walk the lazy-browse tree from the root objects, eagerly
+	// expanding -depth further levels so the print walks cached children
+	// without re-issuing RPCs.
+	nodes, err := client.Browse(ctx, opts)
+	if err != nil {
+		return err
+	}
+	for _, node := range nodes {
+		if err := expandToDepth(ctx, node, *depth); err != nil {
+			return err
+		}
+	}
+
+	if *jsonOutput {
+		jsonNodes := make([]map[string]any, 0, len(nodes))
+		for _, node := range nodes {
+			jsonNodes = append(jsonNodes, lazyNodeToJSON(node))
+		}
+		return writeJSON(stdout, map[string]any{
+			"command": "galaxy-browse",
+			"options": options,
+			"nodes":   jsonNodes,
+		})
+	}
+
+	fmt.Fprintln(stdout, len(nodes))
+	for _, node := range nodes {
+		printLazyNode(stdout, node, 0)
+	}
+	return nil
+}
+
+// runGalaxyBrowseParent fetches exactly one level of children for parentID via a
+// parent-scoped BrowseChildren request, paging until the server stops. It does
+// not lazily wrap the children in nodes; the single level is rendered directly.
+func runGalaxyBrowseParent(
+	ctx context.Context,
+	client *mxgateway.GalaxyClient,
+	parentID int32,
+	opts *mxgateway.BrowseChildrenOptions,
+	stdout io.Writer,
+	jsonOutput bool,
+	options commonOptions,
+) error {
+	var children []*mxgateway.GalaxyObject
+	pageToken := ""
+	seen := map[string]struct{}{}
+	for {
+		req := &mxgateway.BrowseChildrenRequest{
+			PageSize:              browseChildrenCLIPageSize,
+			PageToken:             pageToken,
+			CategoryIds:           opts.CategoryIds,
+			TemplateChainContains: opts.TemplateChainContains,
+			TagNameGlob:           opts.TagNameGlob,
+			AlarmBearingOnly:      opts.AlarmBearingOnly,
+			HistorizedOnly:        opts.HistorizedOnly,
+			IncludeAttributes:     opts.IncludeAttributes,
+			Parent:                &mxgateway.BrowseChildrenRequest_ParentGobjectId{ParentGobjectId: parentID},
+		}
+		reply, err := client.BrowseChildrenRaw(ctx, req)
+		if err != nil {
+			return err
+		}
+		children = append(children, reply.GetChildren()...)
+		pageToken = reply.GetNextPageToken()
+		if pageToken == "" {
+			break
+		}
+		if _, dup := seen[pageToken]; dup {
+			return fmt.Errorf("galaxy browse children returned repeated page token %q", pageToken)
+		}
+		seen[pageToken] = struct{}{}
+	}
+
+	if jsonOutput {
+		jsonChildren := make([]map[string]any, 0, len(children))
+		for _, child := range children {
+			jsonChildren = append(jsonChildren, galaxyObjectToJSON(child))
+		}
+		return writeJSON(stdout, map[string]any{
+			"command":  "galaxy-browse",
+			"options":  options,
+			"parentId": parentID,
+			"children": jsonChildren,
+		})
+	}
+
+	fmt.Fprintln(stdout, len(children))
+	for _, child := range children {
+		fmt.Fprintf(stdout, "%d\t%s\t%s\t(attrs=%d)\n", child.GetGobjectId(), child.GetTagName(), child.GetBrowseName(), len(child.GetAttributes()))
+	}
+	return nil
+}
+
+// browseChildrenCLIPageSize is the per-request page size for the -parent
+// single-level walk. It mirrors the library's browseChildrenPageSize so the
+// CLI and the lazy-browse helper page identically.
+const browseChildrenCLIPageSize = 500
+
+// expandToDepth eagerly expands node and remaining further levels beneath it so
+// a subsequent print walk reads cached children without re-issuing RPCs. A
+// remaining of 0 leaves the node unexpanded (only the requested level prints).
+func expandToDepth(ctx context.Context, node *mxgateway.LazyBrowseNode, remaining int) error {
+	if remaining <= 0 {
+		return nil
+	}
+	if err := node.Expand(ctx); err != nil {
+		return err
+	}
+	for _, child := range node.Children() {
+		if err := expandToDepth(ctx, child, remaining-1); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// printLazyNode renders one node and its already-expanded children as an
+// indent-per-level tree. Only children loaded by a prior Expand are walked.
+func printLazyNode(stdout io.Writer, node *mxgateway.LazyBrowseNode, level int) {
+	indent := strings.Repeat("  ", level)
+	obj := node.Object()
+	fmt.Fprintf(stdout, "%s%d\t%s\t%s\t(attrs=%d, hasChildrenHint=%t)\n",
+		indent, obj.GetGobjectId(), obj.GetTagName(), obj.GetBrowseName(), len(obj.GetAttributes()), node.HasChildrenHint())
+	for _, child := range node.Children() {
+		printLazyNode(stdout, child, level+1)
+	}
+}
+
+// lazyNodeToJSON renders one lazy node and its already-expanded children as a
+// nested JSON object.
+func lazyNodeToJSON(node *mxgateway.LazyBrowseNode) map[string]any {
+	out := galaxyObjectToJSON(node.Object())
+	out["hasChildrenHint"] = node.HasChildrenHint()
+	children := node.Children()
+	jsonChildren := make([]map[string]any, 0, len(children))
+	for _, child := range children {
+		jsonChildren = append(jsonChildren, lazyNodeToJSON(child))
+	}
+	out["children"] = jsonChildren
+	return out
+}
+
+// galaxyObjectToJSON renders the scalar fields of a GalaxyObject for the
+// browse JSON output. Attributes are summarised by count to keep the tree
+// compact; -include-attributes still drives whether the server populates them.
+func galaxyObjectToJSON(obj *mxgateway.GalaxyObject) map[string]any {
+	return map[string]any{
+		"gobjectId":       obj.GetGobjectId(),
+		"tagName":         obj.GetTagName(),
+		"containedName":   obj.GetContainedName(),
+		"browseName":      obj.GetBrowseName(),
+		"parentGobjectId": obj.GetParentGobjectId(),
+		"isArea":          obj.GetIsArea(),
+		"categoryId":      obj.GetCategoryId(),
+		"templateChain":   obj.GetTemplateChain(),
+		"attributeCount":  len(obj.GetAttributes()),
+	}
+}
+
 func formatDeployEvent(event *mxgateway.DeployEvent) string {
 	observed := ""
 	if ts := event.GetObservedAt(); ts != nil {

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

@@ -190,6 +190,109 @@ func TestRunBenchReadBulkRespectsContextCancellation(t *testing.T) {
 	}
 }
 
+// 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).
@@ -245,6 +348,146 @@ func TestRunBenchReadBulkRejectsNonPositiveBulkSize(t *testing.T) {
 	}
 }
 
+// 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.
@@ -294,3 +537,43 @@ func TestRunBatchHandlesLongCommandLine(t *testing.T) {
 		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)
+	}
+}
+
+// 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/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

@@ -363,6 +363,89 @@ func TestBulkMethodsShortCircuitOnEmptySliceWithoutRoundTrip(t *testing.T) {
 	}
 }
 
+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{
@@ -583,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"
 )
@@ -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,6 +7,7 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"sort"
 	"sync"
 	"time"
 
@@ -580,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.

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
@@ -74,6 +84,69 @@ 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 at `AddItem` so
+the array attribute accepts the write.
+
 ## Galaxy Repository Browse
 
 The Galaxy Repository service is a separate metadata-only gRPC service exposed
@@ -105,17 +178,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
@@ -174,19 +318,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 --session-id <id> --limit 1 --json"
-gradle :zb-mom-ww-mxgateway-cli:run --args="acknowledge-alarm --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --alarm-reference \"\\Galaxy\Area001.Pump001.PumpFault\" --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:
 
@@ -229,6 +377,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.1'
+}
+````
+
+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/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java

@@ -1,7 +1,9 @@
 package com.zb.mom.ww.mxgateway.cli;
 
+import com.zb.mom.ww.mxgateway.client.BrowseChildrenOptions;
 import com.zb.mom.ww.mxgateway.client.DeployEventStream;
 import com.zb.mom.ww.mxgateway.client.GalaxyRepositoryClient;
+import com.zb.mom.ww.mxgateway.client.LazyBrowseNode;
 import com.zb.mom.ww.mxgateway.client.MxEventStream;
 import com.zb.mom.ww.mxgateway.client.MxGatewayAlarmFeedSubscription;
 import com.zb.mom.ww.mxgateway.client.MxGatewayClient;
@@ -10,6 +12,8 @@ import com.zb.mom.ww.mxgateway.client.MxGatewayClientVersion;
 import com.zb.mom.ww.mxgateway.client.MxGatewaySecrets;
 import com.zb.mom.ww.mxgateway.client.MxGatewaySession;
 import com.zb.mom.ww.mxgateway.client.MxValues;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.BrowseChildrenRequest;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.GalaxyAttribute;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.GalaxyObject;
@@ -26,25 +30,35 @@ import java.time.Duration;
 import java.time.Instant;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.HashSet;
 import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.Set;
 import java.util.Map;
 import java.util.Optional;
 import java.util.concurrent.ArrayBlockingQueue;
 import java.util.concurrent.BlockingQueue;
 import java.util.concurrent.Callable;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Consumer;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest;
 import mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmProviderStatus;
 import mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage;
 import mxaccess_gateway.v1.MxaccessGateway.BulkReadResult;
 import mxaccess_gateway.v1.MxaccessGateway.BulkWriteResult;
 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.MxEvent;
 import mxaccess_gateway.v1.MxaccessGateway.MxValue;
 import mxaccess_gateway.v1.MxaccessGateway.OnAlarmTransitionEvent;
 import mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest;
+import mxaccess_gateway.v1.MxaccessGateway.PingCommand;
 import mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest;
 import mxaccess_gateway.v1.MxaccessGateway.SubscribeResult;
 import mxaccess_gateway.v1.MxaccessGateway.Write2BulkEntry;
@@ -94,8 +108,14 @@ public final class MxGatewayCli implements Callable<Integer> {
     }
 
     /**
-     * Test-friendly entry point that runs the CLI against the supplied
-     * {@link PrintWriter} pair instead of the system streams.
+     * Entry point that runs the CLI against the supplied {@link PrintWriter}
+     * pair instead of the system streams. This overload wires the production
+     * {@link GrpcMxGatewayCliClientFactory} (a real gRPC channel), so it is
+     * suitable for embedding the CLI but not for unit tests that need to stub
+     * the gateway. Tests should use the package-private
+     * {@link #execute(MxGatewayCliClientFactory, PrintWriter, PrintWriter, String...)}
+     * / {@link #commandLine(MxGatewayCliClientFactory)} overloads, which accept
+     * an injectable client factory.
      *
      * @param out writer that receives standard output
      * @param err writer that receives standard error
@@ -119,14 +139,22 @@ public final class MxGatewayCli implements Callable<Integer> {
         return 0;
     }
 
-    private static CommandLine commandLine(MxGatewayCliClientFactory clientFactory) {
+    static CommandLine commandLine(MxGatewayCliClientFactory clientFactory) {
+        return commandLine(clientFactory, new GrpcGalaxyClientFactory());
+    }
+
+    static CommandLine commandLine(
+            MxGatewayCliClientFactory clientFactory, GalaxyClientFactory galaxyClientFactory) {
         CommandLine commandLine = new CommandLine(new MxGatewayCli(clientFactory));
         commandLine.addSubcommand("version", new VersionCommand());
         commandLine.addSubcommand("open-session", new OpenSessionCommand(clientFactory));
         commandLine.addSubcommand("close-session", new CloseSessionCommand(clientFactory));
+        commandLine.addSubcommand("ping", new PingCommandLine(clientFactory));
         commandLine.addSubcommand("register", new RegisterCommand(clientFactory));
         commandLine.addSubcommand("add-item", new AddItemCommand(clientFactory));
         commandLine.addSubcommand("advise", new AdviseCommand(clientFactory));
+        commandLine.addSubcommand(
+                "advise-supervisory", new AdviseSupervisoryCommand(clientFactory));
         commandLine.addSubcommand("subscribe-bulk", new SubscribeBulkCommand(clientFactory));
         commandLine.addSubcommand("unsubscribe-bulk", new UnsubscribeBulkCommand(clientFactory));
         commandLine.addSubcommand("read-bulk", new ReadBulkCommand(clientFactory));
@@ -140,10 +168,11 @@ public final class MxGatewayCli implements Callable<Integer> {
         commandLine.addSubcommand("stream-alarms", new StreamAlarmsCommand(clientFactory));
         commandLine.addSubcommand("acknowledge-alarm", new AcknowledgeAlarmCommand(clientFactory));
         commandLine.addSubcommand("smoke", new SmokeCommand(clientFactory));
-        commandLine.addSubcommand("galaxy-test", new GalaxyTestConnectionCommand());
-        commandLine.addSubcommand("galaxy-deploy-time", new GalaxyDeployTimeCommand());
-        commandLine.addSubcommand("galaxy-discover", new GalaxyDiscoverCommand());
-        commandLine.addSubcommand("galaxy-watch", new GalaxyWatchCommand());
+        commandLine.addSubcommand("galaxy-test-connection", new GalaxyTestConnectionCommand(galaxyClientFactory));
+        commandLine.addSubcommand("galaxy-last-deploy", new GalaxyDeployTimeCommand(galaxyClientFactory));
+        commandLine.addSubcommand("galaxy-discover", new GalaxyDiscoverCommand(galaxyClientFactory));
+        commandLine.addSubcommand("galaxy-browse", new GalaxyBrowseCommand(galaxyClientFactory));
+        commandLine.addSubcommand("galaxy-watch", new GalaxyWatchCommand(galaxyClientFactory));
         commandLine.addSubcommand("batch", new BatchCommand(clientFactory));
         return commandLine;
     }
@@ -154,6 +183,120 @@ public final class MxGatewayCli implements Callable<Integer> {
     /** Sentinel queued by {@code stream-alarms} to mark a clean end of the alarm feed. */
     private static final Object ALARM_FEED_END = new Object();
 
+    /**
+     * Tokenises a single batch-mode stdin line into the argv that the inner
+     * {@link CommandLine} should execute. Honours single-quoted, double-quoted,
+     * and backslash-escaped runs so values that contain spaces (e.g.
+     * {@code --comment "needs verification"}) survive intact — the old
+     * implementation used {@code split("\\s+")} which shredded any quoted
+     * argument mid-string (Client.Java-034).
+     *
+     * <p>Rules (a small POSIX-like shell tokenizer; no variable expansion,
+     * command substitution, globbing, or backtick handling):
+     *
+     * <ul>
+     *   <li>Outside quotes, runs of whitespace separate tokens.</li>
+     *   <li>{@code "..."} groups a sequence into one token; the surrounding
+     *       quotes are removed. Inside double quotes a backslash escapes
+     *       {@code \\}, {@code "}, and a literal newline; other characters
+     *       are taken literally (so {@code \n} is the two characters
+     *       backslash-n).</li>
+     *   <li>{@code '...'} groups a sequence into one token; the surrounding
+     *       quotes are removed. Inside single quotes nothing is escaped —
+     *       the run is literal until the matching single quote.</li>
+     *   <li>Outside quotes, backslash escapes the next character (including
+     *       whitespace, so {@code needs\ verification} is one token).</li>
+     *   <li>An unterminated quote or a trailing backslash throws
+     *       {@link IllegalArgumentException} so the batch loop surfaces it
+     *       as a JSON error instead of silently emitting wrong args.</li>
+     * </ul>
+     *
+     * <p>Empty input (or input that contains only whitespace) returns an
+     * empty array so callers can skip the line.
+     */
+    static String[] tokenizeBatchLine(String line) {
+        List<String> tokens = new ArrayList<>();
+        StringBuilder current = new StringBuilder();
+        boolean inToken = false;
+        // 0 = outside, 1 = inside single quotes, 2 = inside double quotes
+        int quoteMode = 0;
+        int length = line.length();
+        for (int i = 0; i < length; i++) {
+            char c = line.charAt(i);
+            if (quoteMode == 1) {
+                if (c == '\'') {
+                    quoteMode = 0;
+                } else {
+                    current.append(c);
+                }
+                continue;
+            }
+            if (quoteMode == 2) {
+                if (c == '\\') {
+                    if (i + 1 >= length) {
+                        throw new IllegalArgumentException(
+                                "batch tokenizer: trailing backslash inside double-quoted string");
+                    }
+                    char next = line.charAt(i + 1);
+                    if (next == '\\' || next == '"' || next == '\n') {
+                        current.append(next);
+                        i++;
+                    } else {
+                        // POSIX rule: inside double quotes a backslash is
+                        // literal unless it precedes \, ", $, `, or newline.
+                        current.append(c);
+                    }
+                    continue;
+                }
+                if (c == '"') {
+                    quoteMode = 0;
+                    continue;
+                }
+                current.append(c);
+                continue;
+            }
+            // Outside any quotes.
+            if (c == '\'') {
+                quoteMode = 1;
+                inToken = true;
+                continue;
+            }
+            if (c == '"') {
+                quoteMode = 2;
+                inToken = true;
+                continue;
+            }
+            if (c == '\\') {
+                if (i + 1 >= length) {
+                    throw new IllegalArgumentException(
+                            "batch tokenizer: trailing backslash outside quotes");
+                }
+                current.append(line.charAt(i + 1));
+                i++;
+                inToken = true;
+                continue;
+            }
+            if (Character.isWhitespace(c)) {
+                if (inToken) {
+                    tokens.add(current.toString());
+                    current.setLength(0);
+                    inToken = false;
+                }
+                continue;
+            }
+            current.append(c);
+            inToken = true;
+        }
+        if (quoteMode != 0) {
+            throw new IllegalArgumentException(
+                    "batch tokenizer: unterminated " + (quoteMode == 1 ? "single" : "double") + " quote");
+        }
+        if (inToken) {
+            tokens.add(current.toString());
+        }
+        return tokens.toArray(new String[0]);
+    }
+
     /**
      * Reads one CLI invocation per stdin line, executes each via a fresh
      * {@link CommandLine}, and writes {@value #BATCH_EOR} to stdout after
@@ -183,8 +326,8 @@ public final class MxGatewayCli implements Callable<Integer> {
                     if (line.isEmpty()) {
                         break;
                     }
-                    String[] args = line.trim().split("\\s+");
-                    if (args.length == 0 || (args.length == 1 && args[0].isEmpty())) {
+                    String[] args = tokenizeBatchLine(line);
+                    if (args.length == 0) {
                         continue;
                     }
                     StringWriter cmdOut = new StringWriter();
@@ -232,19 +375,32 @@ public final class MxGatewayCli implements Callable<Integer> {
     }
 
     abstract static class GalaxyCommand implements Callable<Integer> {
+        final GalaxyClientFactory galaxyClientFactory;
+
         @Mixin
         CommonOptions common = new CommonOptions();
 
         @Option(names = "--json", description = "Write JSON output.")
         boolean json;
 
+        GalaxyCommand(GalaxyClientFactory galaxyClientFactory) {
+            this.galaxyClientFactory = galaxyClientFactory;
+        }
+
         GalaxyRepositoryClient connect() {
-            return GalaxyRepositoryClient.connect(common.resolved().toClientOptions());
+            return galaxyClientFactory.connect(common.resolved().toClientOptions());
         }
     }
 
-    @Command(name = "galaxy-test", description = "Calls GalaxyRepository.TestConnection.")
+    @Command(
+            name = "galaxy-test-connection",
+            aliases = {"galaxy-test"},
+            description = "Calls GalaxyRepository.TestConnection.")
     static final class GalaxyTestConnectionCommand extends GalaxyCommand {
+        GalaxyTestConnectionCommand(GalaxyClientFactory galaxyClientFactory) {
+            super(galaxyClientFactory);
+        }
+
         @Override
         public Integer call() {
             try (GalaxyRepositoryClient client = connect()) {
@@ -252,7 +408,7 @@ public final class MxGatewayCli implements Callable<Integer> {
                 PrintWriter out = common.spec.commandLine().getOut();
                 if (json) {
                     Map<String, Object> output = new LinkedHashMap<>();
-                    output.put("command", "galaxy-test");
+                    output.put("command", "galaxy-test-connection");
                     output.put("options", common.redactedJsonMap());
                     output.put("ok", ok);
                     out.println(jsonObject(output));
@@ -264,8 +420,15 @@ public final class MxGatewayCli implements Callable<Integer> {
         }
     }
 
-    @Command(name = "galaxy-deploy-time", description = "Calls GalaxyRepository.GetLastDeployTime.")
+    @Command(
+            name = "galaxy-last-deploy",
+            aliases = {"galaxy-deploy-time"},
+            description = "Calls GalaxyRepository.GetLastDeployTime.")
     static final class GalaxyDeployTimeCommand extends GalaxyCommand {
+        GalaxyDeployTimeCommand(GalaxyClientFactory galaxyClientFactory) {
+            super(galaxyClientFactory);
+        }
+
         @Override
         public Integer call() {
             try (GalaxyRepositoryClient client = connect()) {
@@ -273,7 +436,7 @@ public final class MxGatewayCli implements Callable<Integer> {
                 PrintWriter out = common.spec.commandLine().getOut();
                 if (json) {
                     Map<String, Object> output = new LinkedHashMap<>();
-                    output.put("command", "galaxy-deploy-time");
+                    output.put("command", "galaxy-last-deploy");
                     output.put("options", common.redactedJsonMap());
                     output.put("present", result.isPresent());
                     output.put("timeOfLastDeploy", result.map(Instant::toString).orElse(""));
@@ -290,6 +453,10 @@ public final class MxGatewayCli implements Callable<Integer> {
 
     @Command(name = "galaxy-discover", description = "Calls GalaxyRepository.DiscoverHierarchy.")
     static final class GalaxyDiscoverCommand extends GalaxyCommand {
+        GalaxyDiscoverCommand(GalaxyClientFactory galaxyClientFactory) {
+            super(galaxyClientFactory);
+        }
+
         @Override
         public Integer call() {
             try (GalaxyRepositoryClient client = connect()) {
@@ -313,10 +480,286 @@ public final class MxGatewayCli implements Callable<Integer> {
         }
     }
 
+    /**
+     * Page size used for the raw {@code BrowseChildren} paging loop driven by
+     * the {@code --parent} one-level path. Mirrors {@code BROWSE_CHILDREN_PAGE_SIZE}
+     * in the client library's lazy-browse helper and the other clients' CLI page
+     * size so paging behaviour is consistent across languages.
+     */
+    private static final int BROWSE_CHILDREN_CLI_PAGE_SIZE = 500;
+
+    @Command(
+            name = "galaxy-browse",
+            description = "Browses the Galaxy hierarchy via GalaxyRepository.BrowseChildren.")
+    static final class GalaxyBrowseCommand extends GalaxyCommand {
+        GalaxyBrowseCommand(GalaxyClientFactory galaxyClientFactory) {
+            super(galaxyClientFactory);
+        }
+
+        @Spec
+        private CommandSpec spec;
+
+        @Option(
+                names = "--parent",
+                defaultValue = "-1",
+                description =
+                        "Parent gobject id to browse one level of children for."
+                                + " Use the default (omit) to walk root nodes;"
+                                + " gobject id 0 is reserved by the server to mean roots.")
+        int parent;
+
+        @Option(
+                names = "--depth",
+                defaultValue = "0",
+                description =
+                        "When walking roots, eagerly expand this many further levels before printing."
+                                + " Must be between 0 and 50 inclusive.")
+        int depth;
+
+        @Option(names = "--category-ids", description = "Comma-separated category ids to include.")
+        String categoryIds;
+
+        @Option(names = "--template-contains", description = "Comma-separated template names each child's chain must contain.")
+        String templateContains;
+
+        @Option(names = "--tag-name-glob", description = "SQL-LIKE-style glob applied to tag_name.")
+        String tagNameGlob;
+
+        @Option(names = "--alarm-bearing-only", description = "Restrict to alarm-bearing objects.")
+        boolean alarmBearingOnly;
+
+        @Option(names = "--historized-only", description = "Restrict to objects with at least one historized attribute.")
+        boolean historizedOnly;
+
+        @Option(names = "--include-attributes", description = "Request attribute population on each returned object.")
+        boolean includeAttributes;
+
+        @Override
+        public Integer call() {
+            if (depth < 0) {
+                throw new CommandLine.ParameterException(spec.commandLine(), "--depth must be non-negative");
+            }
+            if (depth > 50) {
+                throw new CommandLine.ParameterException(spec.commandLine(), "--depth must be at most 50");
+            }
+            BrowseChildrenOptions options = buildOptions();
+            PrintWriter out = common.spec.commandLine().getOut();
+            PrintWriter err = common.spec.commandLine().getErr();
+            if (parent == 0) {
+                err.println("warning: --parent 0 is the server sentinel for root nodes; omit --parent to walk roots instead.");
+            }
+            try (GalaxyRepositoryClient client = connect()) {
+                if (parent >= 0) {
+                    if (depth > 0) {
+                        err.println("warning: --depth is ignored when --parent is specified.");
+                    }
+                    List<BrowseChild> children = browseOneLevel(client, parent, options);
+                    if (json) {
+                        List<Map<String, Object>> nodes = new ArrayList<>(children.size());
+                        for (BrowseChild child : children) {
+                            nodes.add(browseNodeMap(child.object(), child.hasChildrenHint(), List.of()));
+                        }
+                        Map<String, Object> output = new LinkedHashMap<>();
+                        output.put("command", "galaxy-browse");
+                        output.put("options", common.redactedJsonMap());
+                        output.put("parentId", parent);
+                        output.put("nodes", nodes);
+                        out.println(jsonObject(output));
+                    } else {
+                        out.println(children.size());
+                        for (BrowseChild child : children) {
+                            printBrowseChild(out, child);
+                        }
+                    }
+                    return 0;
+                }
+
+                List<LazyBrowseNode> roots = client.browse(options);
+                for (LazyBrowseNode root : roots) {
+                    expandToDepth(root, depth);
+                }
+                if (json) {
+                    List<Map<String, Object>> nodes = new ArrayList<>(roots.size());
+                    for (LazyBrowseNode root : roots) {
+                        nodes.add(lazyNodeMap(root));
+                    }
+                    Map<String, Object> output = new LinkedHashMap<>();
+                    output.put("command", "galaxy-browse");
+                    output.put("options", common.redactedJsonMap());
+                    output.put("nodes", nodes);
+                    out.println(jsonObject(output));
+                } else {
+                    out.println(roots.size());
+                    for (LazyBrowseNode root : roots) {
+                        printLazyNode(out, root, 0);
+                    }
+                }
+            }
+            return 0;
+        }
+
+        private BrowseChildrenOptions buildOptions() {
+            return BrowseChildrenOptions.builder()
+                    .categoryIds(parseOptionalIntList(categoryIds))
+                    .templateChainContains(parseOptionalStringList(templateContains))
+                    .tagNameGlob(tagNameGlob == null ? "" : tagNameGlob)
+                    // Tri-state: only override the server default when the flag is present.
+                    .includeAttributes(includeAttributes ? Boolean.TRUE : null)
+                    .alarmBearingOnly(alarmBearingOnly)
+                    .historizedOnly(historizedOnly)
+                    .build();
+        }
+    }
+
+    /** One raw {@code BrowseChildren} child paired with its server-supplied has-children hint. */
+    private record BrowseChild(GalaxyObject object, boolean hasChildrenHint) {
+    }
+
+    /**
+     * Drives the raw {@code BrowseChildren} paging loop for a single parent and
+     * returns the flattened one-level child list. Used by the {@code --parent}
+     * path, which surfaces a single level rather than the lazy root-tree walk.
+     */
+    private static List<BrowseChild> browseOneLevel(
+            GalaxyRepositoryClient client, int parentGobjectId, BrowseChildrenOptions options) {
+        List<BrowseChild> children = new ArrayList<>();
+        Set<String> seenPageTokens = new HashSet<>();
+        String pageToken = "";
+        while (true) {
+            BrowseChildrenRequest.Builder builder = BrowseChildrenRequest.newBuilder()
+                    .setPageSize(BROWSE_CHILDREN_CLI_PAGE_SIZE)
+                    .setPageToken(pageToken)
+                    .setParentGobjectId(parentGobjectId)
+                    .setAlarmBearingOnly(options.isAlarmBearingOnly())
+                    .setHistorizedOnly(options.isHistorizedOnly());
+            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 = client.browseChildrenRaw(builder.build());
+            for (int i = 0; i < reply.getChildrenCount(); i++) {
+                boolean hint = i < reply.getChildHasChildrenCount() && reply.getChildHasChildren(i);
+                children.add(new BrowseChild(reply.getChildren(i), hint));
+            }
+
+            pageToken = reply.getNextPageToken();
+            if (pageToken == null || pageToken.isEmpty()) {
+                return children;
+            }
+            if (!seenPageTokens.add(pageToken)) {
+                throw new IllegalStateException(
+                        "galaxy browse children returned repeated page token: " + pageToken);
+            }
+        }
+    }
+
+    /**
+     * Recursively expands a {@link LazyBrowseNode} up to {@code depth} further
+     * levels. A {@code depth} of 0 leaves the node unexpanded so callers print
+     * only the requested level. Nodes the server reports as childless are not
+     * expanded.
+     */
+    private static void expandToDepth(LazyBrowseNode node, int depth) {
+        if (depth <= 0) {
+            return;
+        }
+        if (node.hasChildrenHint()) {
+            node.expand();
+        }
+        for (LazyBrowseNode child : node.getChildren()) {
+            expandToDepth(child, depth - 1);
+        }
+    }
+
+    /**
+     * Renders one {@link LazyBrowseNode} (and any already-expanded descendants)
+     * as a JSON map. Mirrors the {@code galaxy-discover} object shape with an
+     * added {@code hasChildrenHint} flag and a nested {@code children} array,
+     * matching the cross-client browse JSON surface.
+     */
+    private static Map<String, Object> lazyNodeMap(LazyBrowseNode node) {
+        List<Map<String, Object>> children = new ArrayList<>();
+        if (node.isExpanded()) {
+            for (LazyBrowseNode child : node.getChildren()) {
+                children.add(lazyNodeMap(child));
+            }
+        }
+        return browseNodeMap(node.getObject(), node.hasChildrenHint(), children);
+    }
+
+    /**
+     * Builds the per-node browse JSON map: the flattened Galaxy object fields,
+     * the {@code hasChildrenHint} flag, and a nested {@code children} array.
+     * The {@code hasChildrenHint} key is the cross-client standard (Rust /
+     * Python / .NET / Go all use the same key and node shape).
+     */
+    static Map<String, Object> browseNodeMap(
+            GalaxyObject object, boolean hasChildrenHint, List<Map<String, Object>> children) {
+        Map<String, Object> values = galaxyObjectMap(object);
+        values.put("hasChildrenHint", hasChildrenHint);
+        values.put("children", children);
+        return values;
+    }
+
+    private static void printLazyNode(PrintWriter out, LazyBrowseNode node, int level) {
+        GalaxyObject obj = node.getObject();
+        out.printf(
+                "%s%d\t%s\t%s\t(attrs=%d, hasChildrenHint=%b)%n",
+                "  ".repeat(level),
+                obj.getGobjectId(),
+                obj.getTagName(),
+                obj.getBrowseName(),
+                obj.getAttributesCount(),
+                node.hasChildrenHint());
+        if (node.isExpanded()) {
+            for (LazyBrowseNode child : node.getChildren()) {
+                printLazyNode(out, child, level + 1);
+            }
+        }
+    }
+
+    private static void printBrowseChild(PrintWriter out, BrowseChild child) {
+        GalaxyObject obj = child.object();
+        out.printf(
+                "%d\t%s\t%s\t(attrs=%d, hasChildrenHint=%b)%n",
+                obj.getGobjectId(),
+                obj.getTagName(),
+                obj.getBrowseName(),
+                obj.getAttributesCount(),
+                child.hasChildrenHint());
+    }
+
+    private static List<Integer> parseOptionalIntList(String value) {
+        if (value == null || value.isBlank()) {
+            return List.of();
+        }
+        return parseIntList(value);
+    }
+
+    private static List<String> parseOptionalStringList(String value) {
+        if (value == null || value.isBlank()) {
+            return List.of();
+        }
+        return parseStringList(value);
+    }
+
     @Command(
             name = "galaxy-watch",
             description = "Streams GalaxyRepository.WatchDeployEvents until cancelled.")
     static final class GalaxyWatchCommand extends GalaxyCommand {
+        GalaxyWatchCommand(GalaxyClientFactory galaxyClientFactory) {
+            super(galaxyClientFactory);
+        }
+
         @Option(
                 names = "--last-seen-deploy-time",
                 description =
@@ -506,6 +949,31 @@ public final class MxGatewayCli implements Callable<Integer> {
         }
     }
 
+    @Command(name = "ping", description = "Sends a diagnostic ping command to the session worker.")
+    static final class PingCommandLine extends GatewayCommand {
+        @Option(names = "--session-id", required = true, description = "Gateway session id.")
+        String sessionId;
+
+        @Option(names = "--message", defaultValue = "ping", description = "Message echoed back in the reply.")
+        String message;
+
+        PingCommandLine(MxGatewayCliClientFactory clientFactory) {
+            super(clientFactory);
+        }
+
+        @Override
+        public Integer call() {
+            try (MxGatewayCliClient client = clientFactory.connect(common.resolved())) {
+                MxCommandReply reply = client.session(sessionId).pingRaw(message);
+                // The worker echoes the message in the diagnostic message field;
+                // there is no dedicated ping reply payload, so the plain-text path
+                // surfaces that field.
+                writeOutput("ping", common, json, reply, reply::getDiagnosticMessage);
+            }
+            return 0;
+        }
+    }
+
     @Command(name = "register", description = "Invokes MXAccess Register.")
     static final class RegisterCommand extends GatewayCommand {
         @Option(names = "--session-id", required = true, description = "Gateway session id.")
@@ -578,6 +1046,34 @@ public final class MxGatewayCli implements Callable<Integer> {
         }
     }
 
+    @Command(
+            name = "advise-supervisory",
+            description = "Invokes MXAccess AdviseSupervisory.")
+    static final class AdviseSupervisoryCommand extends GatewayCommand {
+        @Option(names = "--session-id", required = true, description = "Gateway session id.")
+        String sessionId;
+
+        @Option(names = "--server-handle", required = true, description = "MXAccess server handle.")
+        int serverHandle;
+
+        @Option(names = "--item-handle", required = true, description = "MXAccess item handle.")
+        int itemHandle;
+
+        AdviseSupervisoryCommand(MxGatewayCliClientFactory clientFactory) {
+            super(clientFactory);
+        }
+
+        @Override
+        public Integer call() {
+            try (MxGatewayCliClient client = clientFactory.connect(common.resolved())) {
+                MxCommandReply reply =
+                        client.session(sessionId).adviseSupervisoryRaw(serverHandle, itemHandle);
+                writeOutput("advise-supervisory", common, json, reply, () -> reply.getKind().name());
+            }
+            return 0;
+        }
+    }
+
     @Command(name = "subscribe-bulk", description = "Invokes MXAccess SubscribeBulk.")
     static final class SubscribeBulkCommand extends GatewayCommand {
         @Option(names = "--session-id", required = true, description = "Gateway session id.")
@@ -1079,31 +1575,74 @@ public final class MxGatewayCli implements Callable<Integer> {
                 StreamAlarmsRequest request = StreamAlarmsRequest.newBuilder()
                         .setAlarmFilterPrefix(filterPrefix)
                         .build();
+                // Client.Java-033/040/042 — fail-fast on overflow and on
+                // transport errors. A bare queue.offer(value) silently drops
+                // messages past capacity (violating the JavaStyleGuide "do not
+                // drop events" contract and letting the CLI exit 0 on a
+                // truncated feed), and a bare queue.offer(error) on a full
+                // queue would drop the terminal item and deadlock the drain on
+                // queue.take().
+                //
+                // Terminal transitions (overflow, transport error, clean
+                // completion) are now serialised through a single AtomicBoolean
+                // guard plus a dedicated `terminal` slot rather than
+                // re-clearing the shared queue. The first terminal condition
+                // wins; a concurrent onNext on the gRPC I/O thread can no
+                // longer displace it (Client.Java-040). The drain reads the
+                // terminal slot independently of the bounded queue, so a full
+                // queue can never strand the terminal item (Client.Java-042).
+                AtomicReference<MxGatewayAlarmFeedSubscription> subscriptionRef = new AtomicReference<>();
+                AtomicBoolean terminated = new AtomicBoolean();
+                AtomicReference<Object> terminal = new AtomicReference<>();
+                Consumer<Object> terminate = item -> {
+                    if (terminated.compareAndSet(false, true)) {
+                        terminal.set(item);
+                        MxGatewayAlarmFeedSubscription sub = subscriptionRef.get();
+                        if (sub != null) {
+                            sub.cancel();
+                        }
+                    }
+                };
                 MxGatewayAlarmFeedSubscription subscription =
                         client.streamAlarms(request, new StreamObserver<>() {
                             @Override
                             public void onNext(AlarmFeedMessage value) {
-                                queue.offer(value);
+                                if (terminated.get()) {
+                                    return;
+                                }
+                                if (!queue.offer(value)) {
+                                    terminate.accept(new IllegalStateException(
+                                            "stream-alarms queue overflowed (capacity 1024); consumer too slow"));
+                                }
                             }
 
                             @Override
                             public void onError(Throwable error) {
-                                queue.offer(error);
+                                terminate.accept(error);
                             }
 
                             @Override
                             public void onCompleted() {
-                                queue.offer(ALARM_FEED_END);
+                                terminate.accept(ALARM_FEED_END);
                             }
                         });
+                subscriptionRef.set(subscription);
                 try {
                     int count = 0;
                     while (true) {
-                        Object item = queue.take();
-                        if (item == ALARM_FEED_END) {
-                            break;
-                        }
-                        if (item instanceof Throwable error) {
+                        // Poll with a short timeout so the dedicated terminal
+                        // slot is observed even when the bounded queue is full
+                        // of normal messages the consumer has not yet drained.
+                        Object item = queue.poll(50, TimeUnit.MILLISECONDS);
+                        if (item == null) {
+                            Object end = terminal.get();
+                            if (end == null) {
+                                continue;
+                            }
+                            if (end == ALARM_FEED_END) {
+                                break;
+                            }
+                            Throwable error = (Throwable) end;
                             throw new IllegalStateException(
                                     "gateway stream alarms failed: " + error.getMessage(), error);
                         }
@@ -1232,6 +1771,13 @@ public final class MxGatewayCli implements Callable<Integer> {
         @Option(names = "--server-name-override", description = "TLS server name override.")
         String serverNameOverride = "";
 
+        @Option(
+                names = "--require-certificate-validation",
+                description =
+                        "Verify the server certificate against the JVM trust store "
+                                + "(disables the lenient default; ignored with --plaintext or --ca-file pinning).")
+        boolean requireCertificateValidation;
+
         @Option(names = "--timeout", defaultValue = "30s", description = "Per-call timeout.")
         String timeout;
 
@@ -1254,6 +1800,7 @@ public final class MxGatewayCli implements Callable<Integer> {
                     .plaintext(plaintext)
                     .caCertificatePath(caFile)
                     .serverNameOverride(serverNameOverride)
+                    .requireCertificateValidation(requireCertificateValidation)
                     .callTimeout(resolvedTimeout)
                     .build();
         }
@@ -1266,11 +1813,16 @@ public final class MxGatewayCli implements Callable<Integer> {
             values.put("plaintext", plaintext);
             values.put("caFile", caFile == null ? "" : caFile.toString());
             values.put("serverNameOverride", serverNameOverride);
+            values.put("requireCertificateValidation", requireCertificateValidation);
             values.put("timeout", timeout);
             return values;
         }
     }
 
+    interface GalaxyClientFactory {
+        GalaxyRepositoryClient connect(MxGatewayClientOptions options);
+    }
+
     interface MxGatewayCliClientFactory {
         MxGatewayCliClient connect(CommonOptions options);
     }
@@ -1294,6 +1846,8 @@ public final class MxGatewayCli implements Callable<Integer> {
     }
 
     interface MxGatewayCliSession {
+        MxCommandReply pingRaw(String message);
+
         int register(String clientName);
 
         MxCommandReply registerRaw(String clientName);
@@ -1306,6 +1860,8 @@ public final class MxGatewayCli implements Callable<Integer> {
 
         MxCommandReply adviseRaw(int serverHandle, int itemHandle);
 
+        MxCommandReply adviseSupervisoryRaw(int serverHandle, int itemHandle);
+
         MxCommandReply writeRaw(int serverHandle, int itemHandle, MxValue value, int userId);
 
         List<SubscribeResult> subscribeBulk(int serverHandle, List<String> items);
@@ -1325,6 +1881,13 @@ public final class MxGatewayCli implements Callable<Integer> {
         MxEventStream streamEventsAfter(long afterWorkerSequence);
     }
 
+    static final class GrpcGalaxyClientFactory implements GalaxyClientFactory {
+        @Override
+        public GalaxyRepositoryClient connect(MxGatewayClientOptions options) {
+            return GalaxyRepositoryClient.connect(options);
+        }
+    }
+
     static final class GrpcMxGatewayCliClientFactory implements MxGatewayCliClientFactory {
         @Override
         public MxGatewayCliClient connect(CommonOptions options) {
@@ -1379,6 +1942,14 @@ public final class MxGatewayCli implements Callable<Integer> {
     }
 
     record GrpcMxGatewayCliSession(MxGatewaySession session) implements MxGatewayCliSession {
+        @Override
+        public MxCommandReply pingRaw(String message) {
+            return session.invokeCommand(MxCommand.newBuilder()
+                    .setKind(MxCommandKind.MX_COMMAND_KIND_PING)
+                    .setPing(PingCommand.newBuilder().setMessage(message))
+                    .build());
+        }
+
         @Override
         public int register(String clientName) {
             return session.register(clientName);
@@ -1409,6 +1980,17 @@ public final class MxGatewayCli implements Callable<Integer> {
             return session.adviseRaw(serverHandle, itemHandle);
         }
 
+        @Override
+        public MxCommandReply adviseSupervisoryRaw(int serverHandle, int itemHandle) {
+            return session.invokeCommand(MxCommand.newBuilder()
+                    .setKind(MxCommandKind.MX_COMMAND_KIND_ADVISE_SUPERVISORY)
+                    .setAdviseSupervisory(
+                            mxaccess_gateway.v1.MxaccessGateway.AdviseSupervisoryCommand.newBuilder()
+                                    .setServerHandle(serverHandle)
+                                    .setItemHandle(itemHandle))
+                    .build());
+        }
+
         @Override
         public MxCommandReply writeRaw(int serverHandle, int itemHandle, MxValue value, int userId) {
             return session.writeRaw(serverHandle, itemHandle, value, userId);
@@ -1569,6 +2151,12 @@ public final class MxGatewayCli implements Callable<Integer> {
                         transition.getTransitionKind().name(),
                         transition.getSeverity());
             }
+            case PROVIDER_STATUS -> {
+                AlarmProviderStatus status = message.getProviderStatus();
+                yield String.format(
+                        "provider-status mode=%s degraded=%b reason=%s",
+                        status.getMode().name(), status.getDegraded(), status.getReason());
+            }
             case PAYLOAD_NOT_SET -> "unknown";
         };
     }
@@ -1672,13 +2260,37 @@ public final class MxGatewayCli implements Callable<Integer> {
         return jsonString(value.toString());
     }
 
-    private static String jsonString(String value) {
-        return '"'
-                + value.replace("\\", "\\\\")
-                        .replace("\"", "\\\"")
-                        .replace("\r", "\\r")
-                        .replace("\n", "\\n")
-                + '"';
+    // Package-private for the Client.Java-041 escaping regression test.
+    static String jsonString(String value) {
+        // RFC 8259 requires the two-character escapes for the named control
+        // characters and six-character uXXXX escapes for the remaining
+        // U+0000-U+001F (and U+007F) range. The old implementation escaped only
+        // backslash, quote, CR, and LF, so a
+        // value containing a tab, backspace, form-feed, or any other control
+        // character produced malformed JSON (Client.Java-041).
+        StringBuilder builder = new StringBuilder(value.length() + 2);
+        builder.append('"');
+        for (int i = 0; i < value.length(); i++) {
+            char c = value.charAt(i);
+            switch (c) {
+                case '\\' -> builder.append("\\\\");
+                case '"' -> builder.append("\\\"");
+                case '\r' -> builder.append("\\r");
+                case '\n' -> builder.append("\\n");
+                case '\t' -> builder.append("\\t");
+                case '\b' -> builder.append("\\b");
+                case '\f' -> builder.append("\\f");
+                default -> {
+                    if (c < 0x20 || c == 0x7f) {
+                        builder.append(String.format("\\u%04x", (int) c));
+                    } else {
+                        builder.append(c);
+                    }
+                }
+            }
+        }
+        builder.append('"');
+        return builder.toString();
     }
 
     private record RawJson(String value) {

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

@@ -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.AlarmFeedMessage;
 import mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest;
 
@@ -15,53 +11,13 @@ import mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest;
  * {@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 implements AutoCloseable {
-    private final AtomicReference<ClientCallStreamObserver<StreamAlarmsRequest>> requestStream = new AtomicReference<>();
-    private final AtomicBoolean cancelled = new AtomicBoolean();
-
-    ClientResponseObserver<StreamAlarmsRequest, AlarmFeedMessage> wrap(StreamObserver<AlarmFeedMessage> observer) {
-        return new ClientResponseObserver<>() {
-            @Override
-            public void beforeStart(ClientCallStreamObserver<StreamAlarmsRequest> stream) {
-                requestStream.set(stream);
-                if (cancelled.get()) {
-                    stream.cancel("client cancelled alarm feed", null);
-                }
-            }
-
-            @Override
-            public void onNext(AlarmFeedMessage 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<StreamAlarmsRequest> stream = requestStream.get();
-        if (stream != null) {
-            stream.cancel("client cancelled alarm feed", null);
-        }
-    }
-
-    @Override
-    public void close() {
-        cancel();
+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

@@ -384,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();
         }
@@ -393,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.1";
 
     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

@@ -4,7 +4,9 @@ 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;
@@ -18,6 +20,9 @@ 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;
@@ -603,6 +608,54 @@ 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.
+     *
+     * @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
+     * @param elements the indices to write mapped to their scalar values; unmentioned
+     *     indices are reset to the element type default
+     * @param userId the MXAccess user id used for security checks
+     * @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");
+        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,57 @@ 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());
+        }
+    }
+
     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

@@ -105,6 +105,76 @@ 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` 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
@@ -138,6 +208,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
@@ -171,9 +286,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
 
@@ -187,6 +326,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:
@@ -213,6 +367,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:
@@ -225,6 +386,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,10 +1,12 @@
 [build-system]
-requires = ["setuptools>=69", "wheel"]
+# setuptools >=77 emits core-metadata 2.4 (PEP 639 License-Expression), which the
+# Gitea PyPI feed does not yet accept; cap below that so the dist stays <=2.3.
+requires = ["setuptools>=69,<77", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "zb-mom-ww-mxaccess-gateway-client"
-version = "0.1.0"
+version = "0.1.2"
 description = "Async Python client scaffold for MXAccess Gateway."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -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),

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

@@ -489,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/src/zb_mom_ww_mxgateway_cli/commands.py

@@ -21,8 +21,10 @@ from zb_mom_ww_mxgateway import __version__
 from zb_mom_ww_mxgateway.auth import redact_secret
 from zb_mom_ww_mxgateway.client import GatewayClient
 from zb_mom_ww_mxgateway.errors import MxGatewayError
+from zb_mom_ww_mxgateway.galaxy import GalaxyRepositoryClient
+from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
 from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2 as pb
-from zb_mom_ww_mxgateway.options import ClientOptions
+from zb_mom_ww_mxgateway.options import BrowseChildrenOptions, ClientOptions
 from zb_mom_ww_mxgateway.values import MxValueInput, to_mx_value
 
 logger = logging.getLogger(__name__)
@@ -170,6 +172,13 @@ def gateway_options(command: Callable[..., Any]) -> Callable[..., Any]:
     command = click.option("--plaintext", is_flag=True, help="Use plaintext gRPC.")(command)
     command = click.option("--tls", "use_tls", is_flag=True, help="Use TLS gRPC.")(command)
     command = click.option("--ca-file", default=None, help="Custom root certificate file.")(command)
+    command = click.option(
+        "--require-certificate-validation",
+        "require_certificate_validation",
+        is_flag=True,
+        help="Verify the TLS certificate against the system trust store "
+        "instead of the lenient trust-on-first-use default.",
+    )(command)
     command = click.option(
         "--server-name-override",
         default=None,
@@ -268,6 +277,23 @@ def advise(**kwargs: Any) -> None:
     _run(_advise(**kwargs), output_json=kwargs["output_json"], secrets=_secrets(kwargs))
 
 
+@main.command("advise-supervisory")
+@gateway_options
+@click.option("--session-id", required=True, help="Gateway session id.")
+@click.option("--server-handle", required=True, type=int, help="MXAccess server handle.")
+@click.option("--item-handle", required=True, type=int, help="MXAccess item handle.")
+@click.option("--correlation-id", default="", help="Client correlation id.")
+@click.option("--json", "output_json", is_flag=True, help="Emit JSON output.")
+def advise_supervisory(**kwargs: Any) -> None:
+    """Invoke MXAccess AdviseSupervisory."""
+
+    _run(
+        _advise_supervisory(**kwargs),
+        output_json=kwargs["output_json"],
+        secrets=_secrets(kwargs),
+    )
+
+
 @main.command("subscribe-bulk")
 @gateway_options
 @click.option("--session-id", required=True, help="Gateway session id.")
@@ -505,6 +531,148 @@ def smoke(**kwargs: Any) -> None:
     _run(_smoke(**kwargs), output_json=kwargs["output_json"], secrets=_secrets(kwargs))
 
 
+@main.command("galaxy-test-connection")
+@gateway_options
+@click.option("--json", "output_json", is_flag=True, help="Emit JSON output.")
+def galaxy_test_connection(**kwargs: Any) -> None:
+    """Test whether the gateway can reach the Galaxy Repository DB."""
+
+    _run(
+        _galaxy_test_connection(**kwargs),
+        output_json=kwargs["output_json"],
+        secrets=_secrets(kwargs),
+    )
+
+
+@main.command("galaxy-last-deploy")
+@gateway_options
+@click.option("--json", "output_json", is_flag=True, help="Emit JSON output.")
+def galaxy_last_deploy(**kwargs: Any) -> None:
+    """Read the last Galaxy deploy timestamp."""
+
+    _run(
+        _galaxy_last_deploy(**kwargs),
+        output_json=kwargs["output_json"],
+        secrets=_secrets(kwargs),
+    )
+
+
+@main.command("galaxy-discover")
+@gateway_options
+@click.option("--json", "output_json", is_flag=True, help="Emit JSON output.")
+def galaxy_discover(**kwargs: Any) -> None:
+    """Enumerate the deployed Galaxy object hierarchy."""
+
+    _run(
+        _galaxy_discover(**kwargs),
+        output_json=kwargs["output_json"],
+        secrets=_secrets(kwargs),
+    )
+
+
+@main.command("galaxy-browse")
+@gateway_options
+@click.option(
+    "--parent-gobject-id",
+    "parent_gobject_id",
+    default=None,
+    type=int,
+    help=(
+        "Fetch one level of this parent's direct children via BrowseChildren "
+        "instead of the lazy root walk. Pass a gobject id >= 1. "
+        "(gobject-id 0 is the server root sentinel — omit the flag to list root objects.) "
+        "--depth is ignored when this option is set."
+    ),
+)
+@click.option(
+    "--depth",
+    default=0,
+    type=int,
+    show_default=True,
+    help="Eagerly expand the root nodes this many further levels before printing.",
+)
+@click.option(
+    "--category-id",
+    "category_ids",
+    multiple=True,
+    type=int,
+    help="Restrict to objects whose category_id matches one of these ids (repeatable).",
+)
+@click.option(
+    "--template-chain-contains",
+    "template_chain_contains",
+    multiple=True,
+    help="Restrict to objects whose template chain contains this entry (repeatable).",
+)
+@click.option(
+    "--tag-name-glob",
+    "tag_name_glob",
+    default=None,
+    help="Restrict to objects whose tag name matches this glob.",
+)
+@click.option(
+    "--include-attributes",
+    "include_attributes",
+    is_flag=True,
+    help="Include each object's attribute metadata in the browse results.",
+)
+@click.option(
+    "--alarm-bearing-only",
+    "alarm_bearing_only",
+    is_flag=True,
+    help="Only return objects that own at least one alarm-bearing attribute.",
+)
+@click.option(
+    "--historized-only",
+    "historized_only",
+    is_flag=True,
+    help="Only return objects that own at least one historized attribute.",
+)
+@click.option("--json", "output_json", is_flag=True, help="Emit JSON output.")
+def galaxy_browse(**kwargs: Any) -> None:
+    """Browse the deployed Galaxy object hierarchy as a lazy-expanded tree."""
+
+    _run(
+        _galaxy_browse(**kwargs),
+        output_json=kwargs["output_json"],
+        secrets=_secrets(kwargs),
+    )
+
+
+@main.command("galaxy-watch")
+@gateway_options
+@click.option(
+    "--last-seen-deploy-time",
+    "last_seen_deploy_time",
+    default=None,
+    help="ISO-8601 timestamp; when it matches the current cached deploy time the "
+    "bootstrap event is suppressed.",
+)
+@click.option(
+    "--max-events",
+    default=1,
+    type=int,
+    show_default=True,
+    help="Stop after collecting this many deploy events.",
+)
+@click.option(
+    "--timeout",
+    default=5.0,
+    type=float,
+    show_default=True,
+    help="Seconds to wait for each event before stopping.",
+)
+@click.option("--json", "output_json", is_flag=True, help="Emit JSON output.")
+def galaxy_watch(**kwargs: Any) -> None:
+    """Stream a bounded number of Galaxy deploy events."""
+
+    _run(
+        _galaxy_watch(**kwargs),
+        output_json=kwargs["output_json"],
+        secrets=_secrets(kwargs),
+    )
+
+
 async def _open_session(**kwargs: Any) -> dict[str, Any]:
     async with await _connect(kwargs) as client:
         reply = await client.open_session_raw(
@@ -574,6 +742,22 @@ async def _advise(**kwargs: Any) -> dict[str, Any]:
         return {"ok": True}
 
 
+async def _advise_supervisory(**kwargs: Any) -> dict[str, Any]:
+    async with await _connect(kwargs) as client:
+        session = _session(client, kwargs["session_id"])
+        await session.invoke(
+            pb.MxCommand(
+                kind=pb.MX_COMMAND_KIND_ADVISE_SUPERVISORY,
+                advise_supervisory=pb.AdviseSupervisoryCommand(
+                    server_handle=kwargs["server_handle"],
+                    item_handle=kwargs["item_handle"],
+                ),
+            ),
+            correlation_id=kwargs["correlation_id"],
+        )
+        return {"ok": True}
+
+
 async def _subscribe_bulk(**kwargs: Any) -> dict[str, Any]:
     async with await _connect(kwargs) as client:
         session = _session(client, kwargs["session_id"])
@@ -618,7 +802,7 @@ def _build_write_bulk_entries(kwargs: dict[str, Any]):
     """
 
     handles = _parse_int_list(kwargs["item_handles"])
-    value_texts = _parse_string_list(kwargs["values"])
+    value_texts = _parse_string_list(kwargs["values"], param_hint="--values")
     if len(handles) != len(value_texts):
         raise click.UsageError(
             f"item-handles count ({len(handles)}) does not match values count ({len(value_texts)})",
@@ -894,8 +1078,7 @@ async def _write2(**kwargs: Any) -> dict[str, Any]:
 async def _smoke(**kwargs: Any) -> dict[str, Any]:
     async with await _connect(kwargs) as client:
         session = await client.open_session(client_session_name=kwargs["client_name"])
-        closed = False
-        try:
+        async with session:
             server_handle = await session.register(kwargs["client_name"])
             item_handle = await session.add_item(server_handle, kwargs["item"])
             await session.advise(server_handle, item_handle)
@@ -910,9 +1093,215 @@ async def _smoke(**kwargs: Any) -> dict[str, Any]:
                 "itemHandle": item_handle,
                 "events": [_message_dict(event) for event in events],
             }
-        finally:
-            if not closed:
-                await session.close()
+
+
+async def _galaxy_test_connection(**kwargs: Any) -> dict[str, Any]:
+    async with await _connect_galaxy(kwargs) as galaxy:
+        ok = await galaxy.test_connection()
+        return {"command": "galaxy-test-connection", "ok": ok}
+
+
+async def _galaxy_last_deploy(**kwargs: Any) -> dict[str, Any]:
+    async with await _connect_galaxy(kwargs) as galaxy:
+        last_deploy = await galaxy.get_last_deploy_time()
+        payload: dict[str, Any] = {
+            "command": "galaxy-last-deploy",
+            "present": last_deploy is not None,
+        }
+        if last_deploy is not None:
+            # galaxy.py returns a timezone-NAIVE UTC datetime (protobuf ToDatetime()).
+            # Stamp it as UTC so the emitted ISO-8601 carries an unambiguous offset,
+            # matching the Go client's "...Z" output.
+            payload["timeOfLastDeploy"] = last_deploy.replace(tzinfo=timezone.utc).isoformat()
+        return payload
+
+
+async def _galaxy_discover(**kwargs: Any) -> dict[str, Any]:
+    async with await _connect_galaxy(kwargs) as galaxy:
+        objects = await galaxy.discover_hierarchy()
+        return {
+            "command": "galaxy-discover",
+            "objects": [_message_dict(obj) for obj in objects],
+        }
+
+
+async def _galaxy_browse(**kwargs: Any) -> dict[str, Any]:
+    depth = int(kwargs["depth"])
+    if depth < 0 or depth > 50:
+        raise click.BadParameter("--depth must be between 0 and 50", param_hint="--depth")
+    parent_gobject_id: int | None = kwargs.get("parent_gobject_id")
+    options = BrowseChildrenOptions(
+        category_ids=tuple(kwargs.get("category_ids") or ()),
+        template_chain_contains=tuple(kwargs.get("template_chain_contains") or ()),
+        tag_name_glob=kwargs.get("tag_name_glob"),
+        include_attributes=True if kwargs.get("include_attributes") else None,
+        alarm_bearing_only=bool(kwargs.get("alarm_bearing_only")),
+        historized_only=bool(kwargs.get("historized_only")),
+    )
+    async with await _connect_galaxy(kwargs) as galaxy:
+        if parent_gobject_id is not None:
+            # Single-level parent drill-down: drive BrowseChildren paging by hand
+            # and return the children as a flat list.  --depth is not meaningful
+            # here; warn if the caller set it so they know it was ignored.
+            if depth > 0:
+                click.echo(
+                    "warning: --depth is ignored when --parent-gobject-id is specified",
+                    err=True,
+                )
+            children = await _browse_children_one_level(galaxy, parent_gobject_id, options)
+            return {
+                "command": "galaxy-browse",
+                "nodes": [_browse_child_dict(obj, hint) for obj, hint in children],
+                "_text": _render_browse_children(children),
+            }
+
+        roots = await galaxy.browse(options)
+        for root in roots:
+            await _expand_to_depth(root, depth)
+        return {
+            "command": "galaxy-browse",
+            "nodes": [_browse_node_dict(node) for node in roots],
+            "_text": _render_browse_tree(roots),
+        }
+
+
+async def _expand_to_depth(node: Any, depth: int) -> None:
+    """Recursively expand a LazyBrowseNode up to ``depth`` further levels.
+
+    ``depth == 0`` leaves the node unexpanded so only the requested level is
+    printed; each level beyond fetches and recurses into the loaded children.
+    """
+
+    if depth <= 0:
+        return
+    if node.has_children_hint:
+        await node.expand()
+    for child in node.children:
+        await _expand_to_depth(child, depth - 1)
+
+
+def _browse_node_dict(node: Any) -> dict[str, Any]:
+    """Render one LazyBrowseNode (and any already-expanded descendants).
+
+    Mirrors the ``galaxy-discover`` object shape with an added
+    ``hasChildrenHint`` flag and a nested ``children`` array, matching the
+    cross-client browse JSON surface.
+    """
+
+    payload = _message_dict(node.object)
+    payload["hasChildrenHint"] = bool(node.has_children_hint)
+    payload["children"] = (
+        [_browse_node_dict(child) for child in node.children] if node.is_expanded else []
+    )
+    return payload
+
+
+def _render_browse_tree(roots: list[Any]) -> str:
+    """Render the lazy-browse roots as a node count plus an indented tree."""
+
+    lines: list[str] = [str(len(roots))]
+    for root in roots:
+        _append_browse_node_lines(root, 0, lines)
+    return "\n".join(lines)
+
+
+def _append_browse_node_lines(node: Any, indent: int, lines: list[str]) -> None:
+    obj = node.object
+    marker = "+" if node.has_children_hint else "-"
+    pad = " " * indent
+    lines.append(f"{pad}{marker} {obj.tag_name} {obj.browse_name} (gobject {obj.gobject_id})")
+    if node.is_expanded:
+        for child in node.children:
+            _append_browse_node_lines(child, indent + 2, lines)
+
+
+_BROWSE_CHILDREN_PAGE_SIZE = 500
+
+
+async def _browse_children_one_level(
+    galaxy: Any,
+    parent_gobject_id: int,
+    options: BrowseChildrenOptions,
+) -> list[tuple[Any, bool]]:
+    """Page through BrowseChildren for ``parent_gobject_id`` and return (object, hint) pairs.
+
+    Uses page size 500 (matching the library constant) and guards against a
+    repeated page token to prevent an infinite loop if the server misbehaves.
+    """
+
+    results: list[tuple[Any, bool]] = []
+    seen_page_tokens: set[str] = set()
+    page_token = ""
+
+    while True:
+        request = galaxy_pb.BrowseChildrenRequest(
+            parent_gobject_id=parent_gobject_id,
+            page_size=_BROWSE_CHILDREN_PAGE_SIZE,
+            page_token=page_token,
+            alarm_bearing_only=options.alarm_bearing_only,
+            historized_only=options.historized_only,
+        )
+        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 galaxy.browse_children_raw(request)
+
+        for index, obj in enumerate(reply.children):
+            hint = index < len(reply.child_has_children) and bool(reply.child_has_children[index])
+            results.append((obj, hint))
+
+        page_token = reply.next_page_token
+        if not page_token:
+            return results
+        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 _browse_child_dict(obj: Any, has_children_hint: bool) -> dict[str, Any]:
+    """Render one raw browse child as a node dict matching the lazy-browse shape.
+
+    The ``children`` array is always empty — the parent drill-down path returns
+    a flat single-level listing without recursive expansion.
+    """
+
+    payload = _message_dict(obj)
+    payload["hasChildrenHint"] = has_children_hint
+    payload["children"] = []
+    return payload
+
+
+def _render_browse_children(children: list[tuple[Any, bool]]) -> str:
+    """Render a flat one-level child list as a count line plus marker lines."""
+
+    lines: list[str] = [str(len(children))]
+    for obj, has_children_hint in children:
+        marker = "+" if has_children_hint else "-"
+        lines.append(f"{marker} {obj.tag_name} {obj.browse_name} (gobject {obj.gobject_id})")
+    return "\n".join(lines)
+
+
+async def _galaxy_watch(**kwargs: Any) -> dict[str, Any]:
+    last_seen = kwargs.get("last_seen_deploy_time")
+    last_seen_dt = _parse_datetime(last_seen) if last_seen else None
+    async with await _connect_galaxy(kwargs) as galaxy:
+        events = await _collect_deploy_events(
+            galaxy.watch_deploy_events(last_seen_dt),
+            max_events=kwargs["max_events"],
+            timeout=kwargs["timeout"],
+        )
+        return {
+            "command": "galaxy-watch",
+            "events": [_message_dict(event) for event in events],
+        }
 
 
 async def _connect(kwargs: dict[str, Any]) -> GatewayClient:
@@ -923,6 +1312,23 @@ async def _connect(kwargs: dict[str, Any]) -> GatewayClient:
             api_key=api_key,
             plaintext=_use_plaintext(kwargs),
             ca_file=kwargs.get("ca_file"),
+            require_certificate_validation=bool(kwargs.get("require_certificate_validation")),
+            server_name_override=kwargs.get("server_name_override"),
+            call_timeout=kwargs.get("call_timeout"),
+            stream_timeout=kwargs.get("stream_timeout"),
+        ),
+    )
+
+
+async def _connect_galaxy(kwargs: dict[str, Any]) -> GalaxyRepositoryClient:
+    api_key = kwargs.get("api_key") or _api_key_from_env(kwargs.get("api_key_env"))
+    return await GalaxyRepositoryClient.connect(
+        ClientOptions(
+            endpoint=kwargs["endpoint"],
+            api_key=api_key,
+            plaintext=_use_plaintext(kwargs),
+            ca_file=kwargs.get("ca_file"),
+            require_certificate_validation=bool(kwargs.get("require_certificate_validation")),
             server_name_override=kwargs.get("server_name_override"),
             call_timeout=kwargs.get("call_timeout"),
             stream_timeout=kwargs.get("stream_timeout"),
@@ -987,11 +1393,17 @@ def _emit(
     output_json: bool,
     text: str | None = None,
 ) -> None:
+    # A payload may carry a pre-rendered text representation under the private
+    # "_text" key (used by commands like galaxy-browse whose text output is a
+    # custom indented tree rather than the default JSON dump). Strip it so it
+    # never leaks into the JSON branch.
+    rendered_text = payload.pop("_text", None) if isinstance(payload, dict) else None
+
     if output_json:
         click.echo(json.dumps(payload, sort_keys=True))
         return
 
-    click.echo(text or json.dumps(payload, sort_keys=True))
+    click.echo(text or rendered_text or json.dumps(payload, sort_keys=True))
 
 
 async def _collect_events(
@@ -1050,6 +1462,34 @@ async def _collect_alarm_messages(
     return collected
 
 
+async def _collect_deploy_events(
+    events: Any,
+    *,
+    max_events: int,
+    timeout: float,
+) -> list[galaxy_pb.DeployEvent]:
+    if max_events > MAX_AGGREGATE_EVENTS:
+        raise click.BadParameter(
+            f"must be less than or equal to {MAX_AGGREGATE_EVENTS}",
+            param_hint="--max-events",
+        )
+
+    collected: list[galaxy_pb.DeployEvent] = []
+    iterator = events.__aiter__()
+    try:
+        while len(collected) < max_events:
+            collected.append(await asyncio.wait_for(iterator.__anext__(), timeout=timeout))
+    except StopAsyncIteration:
+        pass
+    except asyncio.TimeoutError:
+        pass
+    finally:
+        close = getattr(iterator, "aclose", None)
+        if close is not None:
+            await close()
+    return collected
+
+
 def _parse_value(raw_value: str, value_type: str) -> MxValueInput:
     normalized = value_type.lower()
     if normalized == "bool":
@@ -1076,10 +1516,10 @@ def _parse_datetime(raw_value: str) -> datetime:
     return parsed
 
 
-def _parse_string_list(raw_value: str) -> list[str]:
+def _parse_string_list(raw_value: str, param_hint: str = "--items") -> list[str]:
     values = [item.strip() for item in raw_value.split(",") if item.strip()]
     if not values:
-        raise click.BadParameter("at least one item is required", param_hint="--items")
+        raise click.BadParameter("at least one item is required", param_hint=param_hint)
     return values
 
 
@@ -1087,7 +1527,12 @@ def _parse_int_list(raw_value: str) -> list[int]:
     values = [item.strip() for item in raw_value.split(",") if item.strip()]
     if not values:
         raise click.BadParameter("at least one item handle is required", param_hint="--item-handles")
-    return [int(item) for item in values]
+    try:
+        return [int(item) for item in values]
+    except ValueError as exc:
+        raise click.BadParameter(
+            f"item handles must be integers: {exc}", param_hint="--item-handles"
+        ) from exc
 
 
 def _message_dict(message: Any) -> dict[str, Any]:

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()
 
@@ -146,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_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_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"

clients/rust/.cargo/config.toml

@@ -17,3 +17,6 @@
 # args through the GNU linker and reject `/STACK:`, are unaffected.
 [target.'cfg(all(windows, target_env = "msvc"))']
 rustflags = ["-C", "link-arg=/STACK:8388608"]
+
+[registries.dohertj2-gitea]
+index = "sparse+https://gitea.dohertylan.com/api/packages/dohertj2/cargo/"

clients/rust/Cargo.lock

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

clients/rust/Cargo.toml

@@ -1,8 +1,17 @@
 [package]
 name = "zb-mom-ww-mxgateway-client"
-version = "0.1.0"
+version = "0.1.2"
 edition = "2021"
-publish = false
+authors = ["Joseph Doherty"]
+description = "Async Rust client for the MxAccessGateway gRPC service, including a lazy-browse walker over the Galaxy Repository hierarchy."
+license = "Proprietary"
+repository = "https://gitea.dohertylan.com/dohertj2/mxaccessgw"
+homepage = "https://gitea.dohertylan.com/dohertj2/mxaccessgw"
+documentation = "https://gitea.dohertylan.com/dohertj2/mxaccessgw"
+readme = "README.md"
+keywords = ["mxaccess", "mxgateway", "grpc", "client", "archestra"]
+categories = ["api-bindings", "asynchronous"]
+publish = ["dohertj2-gitea"]
 build = "build.rs"
 
 [workspace]
@@ -11,8 +20,11 @@ resolver = "2"
 
 [workspace.package]
 edition = "2021"
-version = "0.1.0"
-publish = false
+version = "0.1.2"
+authors = ["Joseph Doherty"]
+license = "Proprietary"
+repository = "https://gitea.dohertylan.com/dohertj2/mxaccessgw"
+publish = ["dohertj2-gitea"]
 
 [workspace.dependencies]
 clap = { version = "4.5.53", features = ["derive"] }
@@ -25,7 +37,7 @@ serde_json = "1.0.145"
 thiserror = "2.0.17"
 tokio = { version = "1.48.0", features = ["macros", "rt-multi-thread", "sync", "time"] }
 tokio-stream = { version = "0.1.17", features = ["net"] }
-tonic = { version = "0.13.1", features = ["transport", "tls-ring"] }
+tonic = { version = "0.13.1", features = ["transport", "tls-ring", "tls-native-roots"] }
 tonic-build = "0.13.1"
 
 [dependencies]

clients/rust/README.md

@@ -76,6 +76,27 @@ types.
 cargo run -p mxgw-cli -- smoke --endpoint https://mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item TestChildObject.TestInt --json
 ```
 
+### TLS trust (pin-only)
+
+The gateway can auto-generate its own self-signed certificate (it has no PKI).
+Unlike the other clients, the Rust client is **not** lenient: tonic 0.13.1
+exposes no public hook to inject a custom certificate verifier, so TLS over Rust
+cannot accept an *arbitrary* self-signed certificate. A TLS connection requires
+one of two trust paths:
+
+- `--ca-file` / `ClientOptions::with_ca_file(...)` to pin a CA (export the
+  gateway's self-signed certificate and pin it). This is the path for a
+  self-signed gateway.
+- `--require-certificate-validation` / `with_require_certificate_validation(true)`
+  to verify against the operating system's trust roots (`tls-native-roots`). This
+  only succeeds for a certificate that chains to a root the host already trusts —
+  i.e. a gateway fronted by a publicly- or enterprise-CA-issued certificate, not a
+  bare self-signed one.
+
+TLS with neither set fails `connect` with a clear, actionable error rather
+than accepting the certificate. See
+[Gateway Configuration](../../docs/GatewayConfiguration.md#automatic-self-signed-certificate).
+
 ## Library Surface
 
 `ClientOptions` configures endpoint, API key, plaintext or TLS transport,
@@ -104,6 +125,82 @@ preserving the raw message for parity diagnostics. Command replies whose
 protocol status is not `PROTOCOL_STATUS_CODE_OK` become `Error::Command` and
 retain the raw `MxCommandReply`.
 
+## 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`/`un_advise` but not supervisory advise, so send it
+through the generic command channel:
+
+```rust
+session
+    .invoke(
+        MxCommandKind::AdviseSupervisory,
+        Payload::AdviseSupervisory(AdviseSupervisoryCommand {
+            server_handle,
+            item_handle,
+        }),
+    )
+    .await?;
+
+session.write(server_handle, item_handle, value, user_id).await?;
+```
+
+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
+
+When you only need to set a handful of indices and want every other position to
+take the element type's default (zero / `false` / empty string / Unix epoch for
+timestamps), use `Session::write_array_elements` instead:
+
+```rust
+// Write a 10-element integer array; index 0 = 42, index 7 = 99,
+// all other indices default to 0 (not preserved from the previous value).
+session
+    .write_array_elements(
+        server_handle,
+        item_handle,
+        MxDataType::Integer,
+        10,
+        [(0, MxValue::int32(42)), (7, MxValue::int32(99))],
+        user_id,
+    )
+    .await?;
+```
+
+The gateway expands the sparse representation into a full `MxArray` before
+forwarding to the worker — the worker and MXAccess COM never see the sparse
+form. Unmentioned indices are reset to the type default, **not** preserved from
+the existing attribute value.
+
+#### Bare-name array AddItem normalisation
+
+`AddItem` for a bare array attribute name (e.g. `Tank01.Temperature`) is
+automatically normalised to `Tank01.Temperature[]` by the gateway so the
+worker can resolve the full array. You do not need to append `[]` in client
+code; the gateway handles it.
+
 ## Galaxy Repository browse
 
 The Galaxy Repository service exposes a read-only browse over the AVEVA System
@@ -138,6 +235,50 @@ cargo run -p mxgw-cli -- galaxy last-deploy-time --endpoint http://localhost:500
 cargo run -p mxgw-cli -- galaxy discover-hierarchy --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
 ```
 
+### Browsing lazily
+
+For UI trees or OPC UA bridges, use `browse_children_raw` to walk one level at a
+time instead of paging the full hierarchy. Pass a default request for root
+objects; subsequent calls set `parent_gobject_id`, `parent_tag_name`, or
+`parent_contained_path`. Filter fields match `discover_hierarchy`. Each response
+pairs `children` with `child_has_children` so you know which nodes to expand. See
+[Galaxy Repository](../../docs/GalaxyRepository.md#browsechildren) for full
+request and filter semantics.
+
+```rust
+use zb_mom_ww_mxgateway_client::generated::galaxy_repository::v1::BrowseChildrenRequest;
+
+let reply = galaxy.browse_children_raw(BrowseChildrenRequest::default()).await?;
+for (child, has_children) in reply.children.iter().zip(reply.child_has_children.iter()) {
+    println!("{} expand={}", child.tag_name, 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:
+
+```rust
+let mut client = GalaxyClient::connect(
+    ClientOptions::new("http://localhost:5000").with_api_key(ApiKey::new(api_key)),
+).await?;
+let roots = client.browse(None).await?;
+for root in &roots {
+    if root.has_children_hint() {
+        root.expand().await?;
+    }
+    for child in root.children().await {
+        let kind = if child.has_children_hint() { "has children" } else { "leaf" };
+        println!("{} ({kind})", child.object().tag_name);
+    }
+}
+```
+
+`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
 
 `watch_deploy_events` opens the `WatchDeployEvents` server stream. The
@@ -192,3 +333,27 @@ cargo run -p mxgw-cli -- smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --
 - [Client Proto Generation](../../docs/ClientProtoGeneration.md)
 - [Rust Client Detailed Design](./RustClientDesign.md)
 - [Rust Style Guide](../../docs/style-guides/RustStyleGuide.md)
+
+## Installing from the Gitea Cargo registry
+
+The crate publishes to the internal Gitea Cargo registry. Register the
+registry once in your global `~/.cargo/config.toml`:
+
+```toml
+[registries.dohertj2-gitea]
+index = "sparse+https://gitea.dohertylan.com/api/packages/dohertj2/cargo/"
+```
+
+Authentication: cargo reads credentials from `~/.cargo/credentials.toml`:
+
+```toml
+[registries.dohertj2-gitea]
+token = "Bearer <your-gitea-token>"
+```
+
+Then add the dependency:
+
+```toml
+[dependencies]
+zb-mom-ww-mxgateway-client = { version = "0.1.1", registry = "dohertj2-gitea" }
+```

clients/rust/RustClientDesign.md

@@ -162,12 +162,73 @@ impl GatewayClient {
 
 `stream_alarms` opens with one `active_alarm` per currently-active alarm
 (the ConditionRefresh snapshot), then a single `snapshot_complete`, then a
-`transition` for every subsequent raise / acknowledge / clear. The feed is
-served by the gateway's always-on alarm monitor — no worker session is
-opened — so any number of clients may attach. Dropping the stream cancels
-the gRPC call cooperatively. `acknowledge_alarm` is idempotent at the
-MxAccess layer; the returned `AcknowledgeAlarmReply` carries the native
-MxStatus from the worker.
+`transition` for every subsequent raise / acknowledge / clear. A fourth
+`provider_status` oneof case (`AlarmProviderStatus`: `mode`, `degraded`,
+`reason`, `since`) is emitted once on stream open and again on every
+failover/failback so late joiners learn the current alarm-provider mode.
+The CLI renders all four cases in both its one-line summary and its
+protobuf-JSON output (`alarm_feed_message_summary` /
+`alarm_feed_message_to_json`). The feed is served by the gateway's always-on
+alarm monitor — no worker session is opened — so any number of clients may
+attach. Dropping the stream cancels the gRPC call cooperatively.
+`acknowledge_alarm` is idempotent at the MxAccess layer; the returned
+`AcknowledgeAlarmReply` carries the native MxStatus from the worker.
+
+## Galaxy Repository
+
+`GalaxyClient` is a session-less metadata client (requires the
+`metadata:read` API-key scope). Alongside `test_connection`,
+`get_last_deploy_time`, `discover_hierarchy`, and `watch_deploy_events`, it
+exposes a lazy hierarchy walker built on the `BrowseChildren` RPC:
+
+```rust
+impl GalaxyClient {
+    pub async fn browse(&mut self, options: Option<BrowseChildrenOptions>) -> Result<Vec<LazyBrowseNode>, Error>;
+    pub async fn browse_children_raw(&mut self, request: BrowseChildrenRequest) -> Result<BrowseChildrenReply, Error>;
+}
+
+pub struct BrowseChildrenOptions {
+    pub category_ids: Vec<i32>,
+    pub template_chain_contains: Vec<String>,
+    pub tag_name_glob: Option<String>,
+    pub include_attributes: Option<bool>,
+    pub alarm_bearing_only: bool,
+    pub historized_only: bool,
+}
+
+impl LazyBrowseNode {
+    pub fn object(&self) -> &GalaxyObject;
+    pub fn has_children_hint(&self) -> bool;
+    pub async fn children(&self) -> Vec<LazyBrowseNode>;
+    pub async fn is_expanded(&self) -> bool;
+    pub async fn expand(&self) -> Result<(), Error>;
+}
+```
+
+- `browse(options)` returns the root objects as `LazyBrowseNode`s. The
+  supplied `BrowseChildrenOptions` filter is captured and reused when any
+  returned node is expanded, so a single filter set scopes the entire walk.
+- `BrowseChildrenOptions` mirrors the request-level filters on the wire and
+  combines them with **AND**: a child appears only when it satisfies every
+  populated criterion (`category_ids` membership, every
+  `template_chain_contains` substring, the `tag_name_glob`, plus the
+  `alarm_bearing_only` / `historized_only` flags). `include_attributes` is a
+  tri-state (`None` = server default). Empty/`None` fields impose no
+  restriction. See
+  [Galaxy Repository — BrowseChildren](../../docs/GalaxyRepository.md#browsechildren)
+  for the wire-level semantics.
+- `LazyBrowseNode` is cheap to clone — clones share state through an internal
+  `Arc`, so expanding one clone makes the children visible to every clone.
+  `has_children_hint()` exposes the server's `child_has_children` hint so a UI
+  can draw an expand affordance without issuing an RPC. `expand()` is
+  idempotent: the first call issues a paged `BrowseChildren` walk (page size
+  500) under an async mutex held across the await, sets the `is_expanded`
+  flag, and caches the children; subsequent calls are no-ops and re-hit
+  nothing. The internal paged loop guards against a server returning a
+  repeated `next_page_token` by failing with `Error::InvalidArgument` rather
+  than looping forever.
+- `browse_children_raw` issues a single `BrowseChildren` RPC and returns the
+  raw reply for callers that want to drive paging themselves.
 
 ## Authentication
 
@@ -189,6 +250,32 @@ Support:
 - custom CA file,
 - domain override.
 
+### Trust posture (pin-only)
+
+The gateway can serve a self-signed certificate it generates itself (it has no
+PKI). Rust is the **exception** to the lenient-by-default posture the other
+clients use: tonic 0.13.1 exposes no public hook to inject a custom certificate
+verifier, so the Rust client cannot accept an arbitrary certificate. TLS over the
+Rust client is therefore **pin-only** — it requires either:
+
+- `ClientOptions::with_ca_file(...)` to pin a CA (the supported path for the
+  gateway's self-signed certificate; export the certificate and pin it), or
+- `ClientOptions::with_require_certificate_validation(true)` to verify against the
+  operating system's trust roots. This enables the `tonic` `tls-native-roots`
+  feature and calls `ClientTlsConfig::with_native_roots()`, so the handshake
+  validates a certificate that chains to a root the host already trusts. It does
+  **not** accept a bare self-signed gateway certificate — that still needs
+  `with_ca_file`.
+
+`build_tls_config` computes the trust posture with the pure `tls_trust_decision`
+helper (`None` / `PinnedCa` / `SystemRoots` / `RejectNoCa`) so the posture is
+unit-testable without a live handshake. With TLS enabled (`with_plaintext(false)`),
+no pinned CA, and certificate validation not required (`RejectNoCa`),
+`GatewayClient::connect` rejects the connection with a clear, actionable error
+pointing at `with_ca_file` / `require_certificate_validation` rather than building
+a config with zero trust anchors. The CLI exposes `--ca-file` and
+`--require-certificate-validation`.
+
 ## Streaming
 
 Expose event streams as a `Stream<Item = Result<MxEvent, Error>>`. Dropping the
@@ -262,8 +349,16 @@ mxgw bench-read-bulk [--duration-seconds <n>] [--warmup-seconds <n>] [--bulk-siz
 mxgw smoke --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --item TestChildObject.TestInt
 mxgw batch
 mxgw galaxy {test-connection,last-deploy-time,discover-hierarchy,watch}
+mxgw galaxy browse [--parent-gobject-id <id>] [--category-id <id>...] [--template-contains <s>...] [--tag-name-glob <glob>] [--include-attributes] [--alarm-bearing-only] [--historized-only] [--depth <n>] [--json]
 ```
 
+`galaxy browse` walks the hierarchy one level at a time over the raw
+`BrowseChildren` paging path. `--depth 0` (the default) prints only the
+requested level; `--depth N` eagerly expands N additional levels beneath each
+returned node. `--parent-gobject-id` makes `--depth` a no-op (the parent's
+children are returned as a single level). Omit `--parent-gobject-id` to browse
+root objects.
+
 `batch` reads commands from stdin one per line and dispatches each through
 the normal subcommand path; the loop terminates only on stdin EOF (blank
 lines log an empty-EOR-bracketed result and continue) so accidental empty

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

@@ -2,7 +2,7 @@
 name = "mxgw-cli"
 version.workspace = true
 edition.workspace = true
-publish.workspace = true
+publish = false
 
 [[bin]]
 name = "mxgw"