fix(fixtures): correct Java Gradle task name in cross-language smoke matrix

The smoke-matrix Java commands used 'gradle :mxgateway-cli:run', but the subproject is ':zb-mom-ww-mxgateway-cli' (settings.gradle). Verbatim execution would fail; CrossLanguageSmokeMatrixTests validates shape only, so CI did not catch it. Resolves audit finding F-10-2.
docs(audit): finalize report — resolution status (0 still-open, 33/33 high resolved)
2026-06-03 16:24:24 -04:00 · 2026-06-03 16:09:02 -04:00 · 2026-06-03 16:01:28 -04:00 · 2026-06-03 15:50:13 -04:00 · 2026-06-03 15:42:07 -04:00 · 2026-06-03 15:35:46 -04:00
804 changed files with 49268 additions and 18872 deletions
@@ -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
@@ -19,7 +19,7 @@ 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
@@ -29,10 +29,10 @@ dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj
 dotnet test src/MxGateway.Worker.Tests/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
+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:open,session:close,invoke:read,invoke:write,invoke:secure,events:read,metadata:read,admin
+dotnet run --project src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj -- apikey create-key --key-id dev --display-name "dev" --scopes session:open,session:close,invoke:read,invoke:write,invoke:secure,events:read,metadata:read,admin
 ```
 Single test by name (xUnit `--filter`):
@@ -54,7 +54,7 @@ Live LDAP tests use `MXGATEWAY_RUN_LIVE_LDAP_TESTS=1`. See `docs/GatewayTesting.
 Each language client is in `clients/<lang>/` with its own README. They all consume the shared `.proto` files in `src/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)
@@ -77,7 +77,7 @@ powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1
 - **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/MxGateway.Contracts/Generated/`, `clients/*/generated*/`, `clients/python/src/zb_mom_ww_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.
 - **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.
@@ -90,7 +90,7 @@ When source code changes, build and test the affected component before reporting
 | 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 |
+| .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 +100,7 @@ When source code changes, build and test the affected component before reporting
 ## Design Sources To Consult Before Non-Trivial Changes
 - `gateway.md` — top-level architecture, command/event surface, IPC envelope, STA thread model, fault handling.
- `glauth.md` — local LDAP server (GLAuth on `localhost:3893`, base DN `dc=lmxopcua,dc=local`) used for dev authn. Pre-provisioned users (`admin/admin123`, `readonly/readonly123`, etc.) and the role→capability mapping live there.
+- `glauth.md` — local LDAP server (GLAuth on `localhost:3893`, base DN `dc=zb,dc=local`) used for dev authn. Pre-provisioned users (`admin/admin123`, `readonly/readonly123`, etc.) 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`.
@@ -116,7 +116,7 @@ External analysis sources referenced by design docs:
 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:open`, `session:close`, `invoke:read`, `invoke:write`, `invoke:secure`, `events:read`, `metadata:read`, `admin`) gate specific RPCs; missing → `Unauthenticated`, insufficient → `PermissionDenied`. The `apikey` subcommand on the server exe manages keys; see `src/MxGateway.Server/Security/Authentication/`.
-Dashboard auth uses the same verifier but exchanges the API key for an HTTP-only secure cookie at `/dashboard/login`. `Dashboard:AllowAnonymousLocalhost` bypasses cookie auth on loopback when explicitly 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 `Administrator` or `Viewer` via `MxGateway:Dashboard:GroupToRole`, then issues an HTTP-only secure `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.
 ## Process / Platform Notes
@@ -0,0 +1,599 @@
 # MXAccess Gateway — Documentation Audit Findings
 Synthesized from the 13 audit fragments under `docs/audit/fragments/`. This report drives the fix phase (Tasks 15–22). It is read-only with respect to code and the audited docs; the only artifact produced is this file.
 ## 1. Summary
 Total findings: **186** across 13 clusters.
 ### Counts by verdict
 | Verdict | Count |
 |---|---|
 | accurate | 109 |
 | stale | 27 |
 | wrong | 33 |
 | unverifiable | 6 |
 | gap | 24 |
 (Note: a small number of cluster-08 entries are verdict-tagged `accurate` in the fragment body while the prose flags a phrasing nuance; they are counted as `accurate`.)
 ### Counts by severity
 | Severity | Count |
 |---|---|
 | high | 33 |
 | medium | 33 |
 | low | 120 |
 ### Per-cluster table
 | Cluster | #high | #med | #low | #gap (any sev) |
 |---|---|---|---|---|
 | 01 Architecture | 3 | 4 | 33 | 0 |
 | 02 Worker | 5 | 6 | 30 | 4 |
 | 03 Sessions | 2 | 8 | 18 | 6 |
 | 04 Auth | 11 | 7 | 14 | 5 |
 | 05 Dashboard | 7 | 9 | 8 | 6 |
 | 06 Config | 2 | 3 | 27 | 4 |
 | 07 Contracts/gRPC | 3 | 3 | 22 | 3 |
 | 08 Galaxy | 5 | 3 | 41 | 6 |
 | 09 Alarms | 7 | 6 | 22 | 8 |
 | 10 Testing | 2 | 0 | 30 | 2 |
 | 11 Clients | 7 | 5 | 18 | 3 |
 | 12 Style guides | 3 | 1 | 10 | 0 |
 | 13 History/Plans | 0 | 1 | 21 | 0 |
 (`#high/#med/#low` count all findings at that severity in the cluster; `#gap` counts gap-verdict findings regardless of severity, shown separately because gaps are additive work rather than corrections.)
 ---
 ## 2. Global substitutions table
 Mechanical string replacements that recur across multiple docs or are pure find-and-replace. The "applies to" list contains **only** files the fragment evidence shows actually contain the old string. CLAUDE.md is a living doc and is listed explicitly where the evidence targets it. Per the audit rules, design-history / plan docs (cluster 13) are **excluded** from these applies-to lists — their term occurrences are historical records, not corrected here (only their broken internal cross-refs are fixed, in Task 22).
 | old string | new string | claim_type | applies to (doc list) |
 |---|---|---|---|
 | `Admin` (dashboard role value) | `Administrator` | term | CLAUDE.md (L119, L234-evidence); docs/GatewayConfiguration.md (L55, L156); docs/DashboardInterfaceDesign.md (role labels where used as config value); docs/Authorization.md (L215 — judgment, see Task 18) |
 | cookie `__Host-MxGatewayDashboard` | `MxGatewayDashboard` | config-key/term | CLAUDE.md (L119); docs/GatewayDashboardDesign.md (L420–422) |
 | `src/MxGateway.sln` | `src/ZB.MOM.WW.MxGateway.slnx` | path | CLAUDE.md (L22) |
 | `src/MxGateway.Server/MxGateway.Server.csproj` (short project paths in layout/commands) | `src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj` (and sibling fully-qualified names) | path | gateway.md (L737–769); CLAUDE.md (L35, L248-evidence) |
 | `clients/dotnet/MxGateway.Client.sln` | `clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx` | path | CLAUDE.md (L57, L93); docs/ClientPackaging.md (L51–52) |
 | `clients/python/src/mxgateway/generated` | `clients/python/src/zb_mom_ww_mxgateway/generated` | path | docs/ClientProtoGeneration.md (L80, L74–81 table, L145); docs/ClientLibrariesDesign.md (L410); docs/ClientPackaging.md (L159–160); docs/style-guides/PythonStyleGuide.md (L27–29 parent path) |
 | Python package `mxaccess-gateway-client` | `zb-mom-ww-mxaccess-gateway-client` | config-key | docs/ClientPackaging.md (L159–160); clients/python/PythonClientDesign.md (L215) |
 | Python module `mxgateway_cli` | `zb_mom_ww_mxgateway_cli` | command/path | docs/ClientPackaging.md (L187); docs/style-guides/PythonStyleGuide.md (L27–29) |
 | Python library package `mxgateway` (src dir) | `zb_mom_ww_mxgateway` | path | docs/style-guides/PythonStyleGuide.md (L27–29) |
 | Gradle task `:mxgateway-cli:` | `:zb-mom-ww-mxgateway-cli:` | command | docs/GatewayTesting.md (L322–324); docs/ClientPackaging.md (L193–227) |
 | Gradle task `:mxgateway-client:` | `:zb-mom-ww-mxgateway-client:` | command | docs/ClientPackaging.md (L193–227) |
 | logger category `ZB.MOM.WW.MxGateway.Request` | `MxGateway.Request` | term | docs/Diagnostics.md (L165–166) |
 | STA thread name `ZB.MOM.WW.MxGateway.Worker.STA` | `MxGateway.Worker.STA` | term | docs/WorkerSta.md (L23, L29); docs/MxAccessWorkerInstanceDesign.md (L254) |
 | Java package root `com.dohertylan.mxgateway` | `com.zb.mom.ww.mxgateway` | config-key | docs/style-guides/JavaStyleGuide.md (L25) |
 | Rust crate `mxgateway-client` (library crate name) | `zb-mom-ww-mxgateway-client` | term | docs/ClientPackaging.md (L116) |
 | dashboard route prefix `/dashboard*` | `/` + `/sessions`, `/workers`, `/events`, `/alarms`, `/galaxy`, `/browse`, `/apikeys`, `/settings` | path | docs/GatewayProcessDesign.md (L249–255); docs/GatewayDashboardDesign.md (L289–345); docs/GalaxyRepository.md (L419–422) |
 Notes:
 - The scope-shorthand renames (`session`→`session:open`/`session:close`, `invoke`→`invoke:read`/`invoke:write`/`invoke:secure`, `event`→`events:read`, `metadata`→`metadata:read`) are **not** a single 1:1 mechanical substitution (one shorthand maps to multiple canonical scopes), so they are handled as judgment edits in Tasks 18/20, not in this table. The affected docs are gateway.md (L662–663), CLAUDE.md (L35, L117, L248-evidence), docs/Authentication.md (L99, L187–208).
 - The `wwwroot/css/dashboard.css` → `site.css` rename is dashboard-cluster-specific (single doc family) and is handled in Task 19.
 ---
 ## 3. Out-of-prose-scope flags
 These findings target **non-`.md`** files. They are real bugs but outside this prose audit. **Flag only — recommend separate fix.** Do not schedule them for doc-editing tasks.
 | Finding ID | File | Issue | Severity |
 |---|---|---|---|
 | F-10-2 | `clients/proto/fixtures/smoke/cross-language-smoke-matrix.json` | Every Java command entry uses `gradle :mxgateway-cli:run`; the Gradle subproject is `:zb-mom-ww-mxgateway-cli`. Verbatim execution fails; `CrossLanguageSmokeMatrixTests` does not check the literal task name, so it passes CI undetected. | high |
 (No other fragment finding targets a non-`.md` artifact for an edit; `proto-inputs.json`, `appsettings.json`, source `.cs/.rs/.go/.gradle/.toml` etc. appear only as evidence, not as edit targets.)
 ---
 ## 4. Per-doc findings
 Findings grouped by DOC, ordered high→low severity within each doc. IDs are `F-<cluster#>-<n>` numbered in fragment order within the cluster.
 ### gateway.md
 - **F-01-13** — L231–248 — wrong/high — `WorkerEnvelope` proto block (field type/numbers/names). EVIDENCE: `mxaccess_worker.proto` has `string correlation_id = 4` (not uint64); body fields `gateway_hello=10 … worker_fault=20`; names differ (`command`→`worker_command`, `event`→`worker_event`); missing `worker_shutdown_ack=17`. FIX: replace the block with actual proto content.
 - **F-01-1** — L737–769 — stale/medium — short project names in layout. FIX: use fully-qualified `src/ZB.MOM.WW.MxGateway.*` names (see substitutions).
 - **F-01-2** — L898–913 — stale/medium — session state machine missing `Handshaking`. FIX: insert `-> Handshaking` between `WaitingForPipe` and `InitializingWorker`.
 - **F-01-12** — L301–314 — stale/medium — second session state-machine diagram also missing `Handshaking`. FIX: same insertion in both diagrams.
 - **F-01-3** — L119–121 — stale/medium — scope rejection lists shorthand scope names. FIX: canonical scope strings (judgment, see Task 18 note).
 - **F-01-4** — L119–121 — stale/low — dashboard route list omits `/browse` and `/login`. FIX: add them.
 - **F-01 accurate set** — multiple (L88–94, 108, 110–122, 129–130, 162–210, 266–273, 646–650, 1023–1025, 2–19) — accurate/low — flag only.
 ### docs/GatewayProcessDesign.md
 - **F-01-7** — L249–255 — wrong/high — `/dashboard`-prefixed route table. FIX: replace with actual no-prefix routes (see substitutions).
 - **F-01-8** — L689 — stale/low — `Dashboard:AllowAnonymousLocalhost` missing `MxGateway:` root prefix. FIX: standardize to `MxGateway:Dashboard:AllowAnonymousLocalhost`.
 - **F-01-9** — L854–855 — accurate/low — worker `ExecutablePath` default (separator style only). Flag only.
 - **F-01 accurate set** — L62–93, 100–105, 223–229, 291–299, 408–410, 420–475, 527–530, 713–719, 864–893 — accurate/low — flag only.
 ### docs/DesignDecisions.md
 - **F-01-6** — L360–363 — wrong/high — claims dashboard auth is "API-key-backed dashboard authentication with `admin` scope." EVIDENCE: `DashboardAuthenticator.cs` is LDAP-backed with `GroupToRole`. FIX: rewrite to LDAP-backed + `GroupToRole`→`Admin`/`Viewer`; keep `AllowAnonymousLocalhost` note.
 - **F-01-10** — L36 — unverifiable/low — interop assembly version/PKT not hard-coded in repo. Flag only.
 - **F-01-11** — L36–48 — accurate/low — COM class/CLSID/ProgID/paths. Flag only.
 - **F-01-14** — L55 — accurate/low — `ArchestrA.MXAccess.dll` casing. Flag only.
 - **F-01 accurate set** — L85–95, 217–225 — accurate/low — flag only.
 ### docs/WorkerSta.md
 - **F-02-1** — L23–31 — wrong/medium — STA thread name `ZB.MOM.WW.MxGateway.Worker.STA`. FIX: `MxGateway.Worker.STA` (prose + snippet) (substitution).
 - **F-02-3** — L144 — wrong/medium — `InvokeAsync` throws `InvalidOperationException`. EVIDENCE: throws `StaRuntimeShutdownException` (subtype). FIX: name the subtype and explain why the distinction matters.
 - **F-02-19** — L141–148 — stale/medium — shutdown drain sequence implies single post-stop drain. EVIDENCE: `CancelQueuedCommands` runs inside `ThreadMain` finally before `stoppedEvent.Set()`, and again in `Shutdown()`; drain happens twice. FIX: revise steps 3–4.
 - **F-02-12** — L14 — stale/low — "Bounded asynchronous queue." EVIDENCE: plain `Queue<T>` under lock with async drain loop. FIX: "Bounded queue with an async drain loop."
 - **F-02 accurate set** — L34, 56, 63–78, 82–99, 108, 149 — accurate/low — flag only.
 ### docs/MxAccessWorkerInstanceDesign.md
 - **F-02-4** — L122 — wrong/high — `Success` (exit 0) = "bootstrap options valid." EVIDENCE: actual meaning "pipe session ran to a clean close." FIX: correct Success row; note `WorkerBootstrapResult.Succeeded` is a parse-phase gate distinct from exit 0.
 - **F-02-5** — L119–128 — stale/high — exit-code table missing codes 5 (`PipeConnectionFailed`) and 6 (`ProtocolViolation`). FIX: add both rows.
 - **F-02-6** — L134–160 — stale/high — component tree class names wrong (`WorkerHost`→`WorkerApplication`, `PipeClient`→`WorkerPipeClient`, `FrameReader/Writer`→`WorkerFrameReader/Writer`, `WorkerProtocol`→`WorkerContractInfo`, `StaCommandQueue`→`StaCommandDispatcher`, `MessagePump`→`StaMessagePump`, `StaWatchdog`→`WorkerPipeSession`, `MxAccessCommandDispatcher`→`MxAccessCommandExecutor`, `SafeArrayConverter`→part of `VariantConverter`, `StatusProxyConverter`→`MxStatusProxyConverter`, `HResultMapper`→`HResultConverter`). FIX: rewrite tree.
 - **F-02-15** — L97 — wrong/high — `MXGATEWAY_WORKER_LOG_CONTEXT` env var documented. EVIDENCE: not read anywhere. FIX: remove or mark unimplemented.
 - **F-02-16** — L86–99 — wrong/high — same `MXGATEWAY_WORKER_LOG_CONTEXT` in bootstrap sequence. FIX: flag-only duplicate of F-02-15.
 - **F-02-22** — L134–160 — gap/high — no alarm subsystem in component tree. FIX: add "Alarm Subsystem" section (consumer, poll loop, dispatcher, sink).
 - **F-02-2** — L254 — wrong/medium — STA thread name. FIX: `MxGateway.Worker.STA` (substitution).
 - **F-02-20** — L134–160 — stale/medium — `MxAccess` subtree class names (`MxAccessCommandDispatcher` does not exist; add `MxAccessStaSession`, `MxAccessCommandExecutor`, alarm sinks). FIX: update.
 - **F-02-23** — L336–338 — gap/medium — event-sink subscription list omits alarm events. FIX: add `MxAccessAlarmEventSink`.
 - **F-02-18** — L368–375 — stale/low — `MxAccessEventQueue.Enqueue` also throws `MxAccessEventQueueOverflowException`. FIX: note thrown exception.
 - **F-02-26** — L151 — accurate/low — `MxAccessSession` exists. Flag only.
 - **F-02 accurate set** — L271–286, 656–660 — accurate/low — flag only.
 ### docs/WorkerBootstrap.md
 - **F-02-7** — L146 — stale/medium — stderr/stdout-capture rationale. EVIDENCE: launcher redirects neither stream. FIX: replace rationale; the env-var-secrecy reason is the accurate one.
 - **F-02-25** — L5–6 — stale/low — "short-lived child." FIX: "per-session child process."
 - **F-02 accurate set** — L7–8, 48–54, 105, 113–120, 155–159, 181–193 — accurate/low — flag only.
 ### docs/WorkerConversion.md
 - **F-02-21** — L1–262 — gap/medium — inverse projection (`ConvertToComValue`/`ConvertToComArray`, write path) undocumented. FIX: add "Inverse projection for COM writes" section.
 - **F-02-11** — L225 — stale/low — engine-error ranges implied contiguous; gaps exist (35,45,46 / 58,59). FIX: "selected detail codes in the ranges …".
 - **F-02 accurate set** — L17–18, 112–135, 178 — accurate/low — flag only.
 ### docs/WorkerFrameProtocol.md / docs/WorkerProcessLauncher.md
 - All findings accurate/low (F-02 frameproto and launcher accurate set: WorkerFrameProtocol L14–53; WorkerProcessLauncher L18–64). Flag only.
 ### docs/Sessions.md
 - **F-03-22** — gap/high — orphan cleanup (`OrphanWorkerCleanupHostedService` → `OrphanWorkerTerminator.TerminateOrphans` on startup, best-effort) undocumented. FIX: add "Gateway Restart / Orphan Cleanup" section.
 - **F-03-21** — L230 — wrong/high — invents metric names `KillCount`/`ShutdownCount`. EVIDENCE: actual counter is `mxgateway.workers.killed`. FIX: replace with real counter via `GatewayMetrics.WorkerKilled`.
 - **F-03-1** — L9 — wrong/medium — "All four interfaces" (only three exist) and omits `SessionLeaseMonitorHostedService`. FIX: "three interfaces"; list two hosted services.
 - **F-03-2** — L265–276 — stale/medium — DI snippet omits `SessionLeaseMonitorHostedService`. FIX: add the registration line.
 - **F-03-3** — L232–259 — stale/medium — `ShutdownAsync` snippet predates Server-045/046; fallback now routes via `KillWorkerAsync`. FIX: replace snippet.
 - **F-03-4** — L55–59 — stale/medium — `KillWorkerAsync` no longer calls `GatewaySession.KillWorker` directly; now `KillWorkerWithCloseGateAsync` (acquires `_closeLock`). FIX: update.
 - **F-03-12** — L163–188 — stale/medium — open-failure rollback order omits conditional `SessionRemoved()` (Server-006). FIX: note the conditional metric call before `ReleaseSessionSlot`.
 - **F-03-19** — L230 — stale/medium — `GatewaySession.KillWorker` no longer the entry point from `SessionManager`. FIX: clarify `KillWorkerWithCloseGateAsync` is the path.
 - **F-03-23** — gap/medium — `AllowMultipleEventSubscribers=true` rejected at startup by `GatewayOptionsValidator`. FIX: note startup-validation refusal.
 - **F-03-7** — L265 — wrong/medium — "the hosted service" (singular). FIX: "two hosted services."
 - **F-03-20** — L279 — stale/low — registration-order reasoning. FIX: note two hosted services + DI ordering caveat.
 - **F-03-24** — gap/low — `_items` registration dictionary undocumented. FIX: add paragraph.
 - **F-03-25** — gap/low — `MaxPendingCommandsPerSession` (128) cap undocumented. FIX: add note.
 - **F-03-26** — gap/low — `KillWorkerWithCloseGateAsync` unmentioned. FIX: mention in Close section.
 - **F-03 accurate set** — L15–127, 134–227, 195–197, 197 (lease/sweep) — accurate/low — flag only.
 ### docs/Authentication.md
 - **F-04-1** — L253–271 — stale/high — Registration block is pre-migration; types now from `ZB.MOM.WW.Auth.ApiKeys` via `AddZbApiKeyAuth`. FIX: replace block; remove "registers the migration hosted service" claim.
 - **F-04-9** — L187–208 — wrong/high — CLI example `--scopes read,write` + subcommand `create`. EVIDENCE: scopes invalid; subcommand is `create-key`. FIX: canonical scopes (e.g. `invoke:read,invoke:write`), `create-key`.
 - **F-04-2** — L53–68 — stale/medium — `ApiKeySecretHasher` etc. are shared-library types; return type `ApiKeyVerification` not `ApiKeyVerificationResult`. FIX: clarify ownership + type name.
 - **F-04-3** — L72–98 — stale/medium — `ApiKeyVerifier` types/return shapes from shared package. FIX: `ApiKeyVerification`; note shared lib.
 - **F-04-5** — L126–133 — stale/medium — schema table omits `audit_event` table; `api_key_audit` no longer written. FIX: add fourth table + note.
 - **F-04-4** — L108–122 — stale/low — `AuthSqliteConnectionFactory` ownership/`ApiKeyOptions.SqlitePath`. FIX: clarify.
 - **F-04-6** — L134–153 — stale/low — `SqliteApiKeyStore` from shared package. FIX: label code block as shared-lib.
 - **F-04-7** — L156–164 — stale/low — `SqliteApiKeyAdminStore` shared; CLI uses `ApiKeyAdminCommands`. FIX: clarify.
 - **F-04-8** — L165–183 — stale/low — `SqliteAuthStoreMigrator` etc. shared. FIX: clarify.
 - **F-04-10** — L229–248 — stale/low — `ApiKeyScopeSerializer` shared. FIX: note.
 - **F-04-gap-3** — gap/medium — `api_key_audit` unused at runtime; all audit → `audit_event`. FIX: document.
 - **F-04-gap-2** — gap/medium — 8-hour cookie idle timeout + 30-min hub token undocumented. FIX: add.
 - **F-04-gap-1** — gap/medium — `MxGateway:Dashboard:CookieName` override undocumented. FIX: document.
 - **F-04-gap-4** — gap/low — `RequireHttpsCookie` undocumented. FIX: reference.
 - **F-04-gap-5** — gap/low — `ZbClaimTypes`/`ZbCookieDefaults` undocumented. FIX: brief note.
 - **F-04 accurate set** — L1–30, 110, 189–208, 220–225 — accurate/low — flag only.
 ### docs/Authorization.md
 - **F-04-11** — L107–113 — stale/high — scope resolver block omits `BrowseChildrenRequest => MetadataRead`. FIX: add it.
 - **F-04-12** — L212 — stale/high — scope catalog table omits `GalaxyRepository.BrowseChildren`. FIX: add to `MetadataRead` row.
 - **F-04-18** — L205–215 — stale/high — same catalog gap (`BrowseChildren`). FIX: as above.
 - **F-04-13** — L260–270 — stale/medium — registration block omits `IConstraintEnforcer`/`ConstraintEnforcer` and `GrpcServiceOptions` size limits. FIX: add.
 - **F-04-16** — L215 — stale/medium — claims `GatewayScopes.Admin` referenced by `DashboardAuthenticator`. EVIDENCE: dashboard role `Administrator` and gRPC scope `admin` are separate. FIX: correct/remove the claim.
 - **F-04-14** — L273 — stale/low — "three classes" → four (adds `ConstraintEnforcer`). FIX: update.
 - **F-04 accurate set** — L85, 94–116 — accurate/low — flag only.
 ### glauth.md
 - **F-04-15** — L63–66 — wrong/high — `LdapOptions.RequiredGroup` defaults to `GwAdmin`. EVIDENCE: no `RequiredGroup` exists; membership enforced via `GroupToRole`. FIX: rewrite.
 - **F-04-17** — L181–182 — wrong/high — "strips to `GwAdmin` and matches against `RequiredGroup`." FIX: "looks up the short RDN in `GroupToRole`."
 - **F-04-19** — L113–136 — wrong/high — YAML keys `useTls`/`allowInsecureLdap`/`userNameAttribute`. EVIDENCE: actual `Transport`/`AllowInsecure`/`UserNameAttribute`(default `cn`); section header `MxGateway:Ldap`. FIX: rewrite YAML.
 - **F-04-21** — L261–269 — wrong/high — AD cheat-sheet `UseTls`/`AllowInsecureLdap`. EVIDENCE: renamed `Transport`/`AllowInsecure`. FIX: rename rows.
 - **F-04-20** — L128 — wrong/medium — `userNameAttribute: "uid"`. EVIDENCE: default is `cn`. FIX: change to `cn` + note.
 - **F-04-22** — L70–74 — accurate/low — Task 1.7 role note. Flag only.
 - **F-04-23** — L21–26 — accurate/low — connection details. Flag only.
 ### CLAUDE.md (auth-related judgment fixes — Task 18)
 - **F-04-24** — L119 — wrong/high — cookie `__Host-MxGatewayDashboard` and role `Admin`. FIX: `MxGatewayDashboard` + `Administrator` (substitutions).
 - **F-04-25** — L119 — wrong/high — LDAP groups map to `Admin`. FIX: `Administrator`.
 - **F-04-26** — L35 — wrong/high — apikey example `create --scopes session,invoke,event,metadata,admin`. FIX: `create-key` + canonical scopes.
 - **F-04-27** — L117 — wrong/high — scopes shorthand `session, invoke, event, metadata, admin`. FIX: canonical scope strings (SQLite path is correct, keep).
 ### docs/DashboardInterfaceDesign.md
 - **F-05-1** — L39–57 — stale/high — `dashboard-shell`/`dashboard-navbar` HTML skeleton. EVIDENCE: now `ThemeShell` side rail. FIX: replace skeleton/prose.
 - **F-05-2** — L115–123 — stale/high — five flat nav labels incl. "Overview." EVIDENCE: eight items in three groups; home is "Dashboard." FIX: update.
 - **F-05-3** — L63–79 — wrong/high — `--mxgw-*` CSS tokens. EVIDENCE: none exist; all via theme kit tokens. FIX: remove table; note theme-kit tokens.
 - **F-05-7** — L191–200 — wrong/high — Bootstrap `text-bg-*` badge mapping. EVIDENCE: `StatusBadge` delegates to `StatusPill` with `StatusState`. FIX: replace with `StatusState` vocabulary.
 - **F-05-4** — L87–97 — stale/medium — typography values. FIX: h1 1.15rem/600, agg-label 0.68rem/600, agg-value 1.5rem/600 ink.
 - **F-05-gap-2** — gap/medium — new StatusBadge states (`Active`/`Stale`/`Degraded`/`Unavailable`, `Closed`→Idle) undocumented. FIX: document full mapping.
 - **F-05-5** — L99–111 — stale/low — spacing/radius. FIX: 0.85rem small-screen padding, 8px radius, full-border cards.
 - **F-05-6** — L153–168 — stale/low — `metric-grid` `auto-fit, 12rem`. EVIDENCE: `auto-fill, 11rem`. FIX: update.
 - **F-05-8** — L229–245 — stale/low — `.dashboard-content` breakpoint. EVIDENCE: `.page { padding: 0.85rem }`. FIX: update.
 ### docs/GatewayDashboardDesign.md
 - **F-05-11** — L507–510 — wrong/high — `wwwroot/css/dashboard.css`. EVIDENCE: file is `site.css`; App.razor loads `<ThemeHead/>`/`<ThemeScripts/>`; denied-page loads theme kit CSS. FIX: rename + add theme-kit loading.
 - **F-05-13** — L420–422 — wrong/high — cookie `__Host-MxGatewayDashboard`. FIX: `MxGatewayDashboard` (substitution); note `CookieName` override.
 - **F-05-gap-3** — gap/high — `ZB.MOM.WW.Theme 0.2.0` package + components undocumented. FIX: add "Theme Kit" section.
 - **F-05-9** — L78–110 — stale/medium — component tree: `DashboardLayout.razor` → `MainLayout.razor`/`LoginLayout.razor`; note `StatusBadge`→`StatusPill`; add `BrowseTreeNodeView.razor`, `ConfirmDialog.razor`. FIX: update tree.
 - **F-05-10** — L406–428 — stale/medium — `Novell.Directory.Ldap.NETStandard`. EVIDENCE: shared `ZB.MOM.WW.Auth.Ldap` via `AddZbLdapAuth`. FIX: replace.
 - **F-05-12** — L289–306 — stale/medium — Browse page `/dashboard/browse`. EVIDENCE: `/browse`; `DashboardBrowseTreeBuilder` is static in `DashboardBrowseModel.cs`. FIX: route + clarify.
 - **F-05-14** — L307–318 — stale/medium — Alarms `/dashboard/alarms` + data-source. EVIDENCE: `/alarms`; uses `IDashboardLiveDataService.QueryAlarmsAsync` poll loop, not `CurrentAlarms`. FIX: route + source.
 - **F-05-15** — L337–345 — stale/medium — API keys `/dashboard/apikeys`. EVIDENCE: `/apikeys`. FIX: route.
 - **F-05-16** — L387–391 — stale/medium — appends `api_key_audit`. EVIDENCE: `audit_event` via `IAuditWriter`. FIX: correct table.
 - **F-05-17** — L68–69 — stale/medium — `GalaxySummaryCache`/`GalaxySummaryRefreshService`. EVIDENCE: `GalaxyHierarchyCache`/`GalaxyHierarchyRefreshService`. FIX: rename (config key correct).
 - **F-05-gap-1** — gap/medium — `/login` served by Blazor `Login.razor`/`<LoginCard>`; POST `/login` minimal-API. FIX: add to auth section.
 - **F-05-gap-4** — gap/medium — `CookieName`/`RequireHttpsCookie` config undocumented. FIX: add.
 - **F-05-18** — L160–170 — accurate/low — `DashboardEventBroadcaster` is a follow-up stub. Flag only (add planned-follow-up note).
 - **F-05-19** — L171–177 — accurate/low — `DashboardPageBase`. Flag only.
 - **F-05-20** — L559–577 — stale/low — "local Bootstrap static assets." FIX: add theme-kit layer note.
 - **F-05-21** — L463–465 — unverifiable/low — `Authentication:Mode = Disabled` bypass not found in Dashboard/. FIX: cross-check GatewayOptions.
 - **F-05-gap-5** — gap/low — `ConfirmDialog.razor` + admin controls on list pages undocumented. FIX: add.
 ### docs/GatewayConfiguration.md
 - **F-06-1** — L55–56 — wrong/high — GroupToRole example `"Admin"`. EVIDENCE: validator requires `"Administrator"`. FIX: change value.
 - **F-06-2** — L156 — wrong/high — table desc says `Admin`. FIX: `Administrator`.
 - **F-06-4** — L1–419 — gap/medium — `MxGateway:Ldap` section (11 keys) not documented. FIX: add `## Ldap Options` table.
 - **F-06-7** — L14–77 — gap/medium — config-shape JSON omits `Ldap`. FIX: add block.
 - **F-06 accurate set** — L15–69, 110, 164–206, 228, 346–354 (Authentication/Worker/Sessions/Events/Dashboard/Protocol/Galaxy/Alarms/TLS/policies/hubs/pipeline) — accurate/low — flag only.
 ### docs/Diagnostics.md
 - **F-06-3** — L165–166 — wrong/medium — logger category `ZB.MOM.WW.MxGateway.Request`. FIX: `MxGateway.Request` (substitution).
 - **F-06-5** — gap/low — `GatewayLogRedactorSeam` unmentioned. FIX: add note.
 - **F-06-6** — gap/low — `AuthStoreHealthCheck` unmentioned. FIX: add section.
 - **F-06 accurate set** — L15–148, 181–188 — accurate/low — flag only.
 ### docs/Metrics.md
 - All findings accurate/low (F-06 metrics accurate set: L8–192). Flag only.
 ### docs/Grpc.md
 - **F-07-1** — L13,32 — wrong/high — "six RPCs"; omits `QueryActiveAlarms`. FIX: "seven"; add handler section.
 - **F-07-2** — L148 — wrong/medium — "every `ProtocolStatusCode`" factory; missing `MxAccessFailure`. FIX: qualify or add.
 - **F-07-4** — L227 — wrong/medium — "default policy" drops only the stream. EVIDENCE: default is `FailFast` (session faulted); stream-drop is `DisconnectSubscriber`. FIX: rewrite.
 - **F-07 accurate set** — L9–26, 100–108, 141–196, 237–243 — accurate/low — flag only.
 ### docs/Contracts.md
 - **F-07-gap-1** — gap/medium — `QueryActiveAlarms` RPC/messages undocumented. FIX: add paragraph.
 - **F-07-gap-2** — gap/low — `AlarmFeedMessage`/`StreamAlarms` 3-phase protocol not in shape-level ref. FIX: add entry.
 - **F-07-gap-3** — gap/low — reserved `session_id` + intentionally-unset `status` on Acknowledge messages. FIX: add note.
 - **F-07 accurate set** — L4–5, 9–61, 68–81, 94, 107 — accurate/low — flag only (build command `src/ZB.MOM.WW.MxGateway.slnx` already correct).
 ### docs/ClientProtoGeneration.md
 - **F-07-3** — L80,145 — wrong/high — Python generated path. FIX: `clients/python/src/zb_mom_ww_mxgateway/generated` (substitution).
 - **F-07-5** — L74–81 — wrong/high — table Python row same wrong path (and L145). FIX: same.
 - **F-07 accurate set** — L39–45, 55–61, 89–101, 119–125, 170–176 — accurate/low — flag only.
 ### docs/GalaxyRepository.md
 - **F-08-21** — L403–404 — wrong/high — "All four Galaxy RPCs." EVIDENCE: five (adds `BrowseChildren`). FIX: "five."
 - **F-08-31** — L420–422 — wrong/high — `/dashboard/galaxy` + `/dashboard`. EVIDENCE: `/galaxy`, `/`. FIX: route fixes (substitution).
 - **F-08-32** — L419–420 — wrong/high — overview card "on `/dashboard`." EVIDENCE: `/`. FIX: route.
 - **F-08-10** — L83–86 — wrong/medium — page-token encoding `(cache_sequence, parent_id, filter_signature, offset)`. EVIDENCE: `sequence:filterSignature:offset` with parent folded into signature. FIX: rewrite.
 - **F-08-18** — L387 — wrong/medium — `CommandTimeoutSeconds` "applies to all three RPCs." EVIDENCE: five RPCs; applies to SQL commands. FIX: rephrase.
 - **F-08-gap-1** — gap/medium — 5-minute `Stale` auto-degrade undocumented. FIX: add note.
 - **F-08-gap-4** — gap/medium — `HierarchySql` category-ID filter + name map undocumented. FIX: add table.
 - **F-08-gap-2** — gap/low — snapshot-restore publishes deploy event. FIX: note.
 - **F-08-gap-3** — gap/low — initial refresh at startup. FIX: note.
 - **F-08-gap-5** — gap/low — `data_type` table unmentioned. FIX: flag only.
 - **F-08-gap-6** — gap/low — `gobject`/`template_definition` parent CASE logic. FIX: flag only.
 - **F-08-acc-display** — L399–400 — unverifiable/low — connection-string field filtering (`DashboardConnectionStringDisplay` not in scope). Flag only — recommend verifying.
 - **F-08 accurate set** — L3–4, 30–43, 110–119, 150–152, 178–179, 212–390 (most SQL/proto/cache claims) — accurate/low — flag only.
 ### docs/AlarmClientDiscovery.md
 - **F-09-7** — L758–762 — wrong/high — `WorkerAlarmRpcDispatcher` + "always routes through `AcknowledgeAlarmByName`." EVIDENCE: class is `GatewayAlarmMonitor.BuildAcknowledgeCommand`; routing is conditional (GUID→GUID path, name→by-name). FIX: rewrite.
 - **F-09-30** — L761–762 — wrong/high — duplicate of above (`WorkerAlarmRpcDispatcher`, "always"). FIX: replace sentence with `GatewayAlarmMonitor` conditional routing.
 - **F-09-5** — L604–605 — wrong/high — presents `AlarmAckByGUID` as the ack method before the E_NOTIMPL discovery. FIX: add forward-reference warning or reorder.
 - **F-09-11** — L644–647 — wrong/high — boolean STATE mapping (`in_alarm`/`acked`). EVIDENCE: proto uses `AlarmConditionState` (Active/ActiveAcked/Inactive). FIX: replace with enum mapping.
 - **F-09-28** — L750–756 — stale/high — "all acks must go through `AcknowledgeByName`." EVIDENCE: code still dispatches GUID path unguarded. FIX: add guard or stop GUID dispatch; document.
 - **F-09-gap-1** — gap/high — public alarm RPCs (`AcknowledgeAlarm`/`StreamAlarms`/`QueryActiveAlarms`) + `MxGateway:Alarms:*` config never named. FIX: add cross-reference section.
 - **F-09-gap-2** — gap/high — always-on `GatewayAlarmMonitor` broker architecture undocumented. FIX: add section.
 - **F-09-gap-3** — gap/high — `AlarmFeedMessage` snapshot→`snapshot_complete`→transition protocol undocumented. FIX: document.
 - **F-09-gap-6** — gap/high — `alarm_full_reference` parse contract (GUID vs `Provider!Group.Tag`) undocumented. FIX: document.
 - **F-09-1** — L71–74 — wrong/medium — references nonexistent `AlarmClientConsumer.cs`. FIX: note retired/replaced by `WnWrapAlarmConsumer.cs`.
 - **F-09-9** — L636–639 — wrong/medium — consumer "polls on a timer." EVIDENCE: no internal timer; `PollOnce()` driven by STA. FIX: correct.
 - **F-09-10** — L641–643 — wrong/medium — proto name `AlarmAckCommand`. EVIDENCE: `AcknowledgeAlarmCommand`; interface `AcknowledgeByGuid`. FIX: correct names.
 - **F-09-12** — L648–649 — wrong/medium — `condition_id` field. EVIDENCE: no such field; use `alarm_full_reference`. FIX: replace.
 - **F-09-31** — L765–773 — stale/medium — internal `Timer`/`pollIntervalMilliseconds=0`. EVIDENCE: no timer/param. FIX: update.
 - **F-09-6** — L750–756 — accurate/medium — `AlarmAckByGUID` E_NOTIMPL; code calls it without guard. FIX flag: document COMException risk.
 - **F-09-gap-4** — gap/medium — reconcile loop undocumented. FIX: document cadence/purpose.
 - **F-09-gap-5** — gap/medium — subscriber backpressure (2048, drop+reconnect) undocumented. FIX: document.
 - **F-09-gap-7** — gap/medium — `ActiveAlarmSnapshot.current_state` collapse (UnackRtn/AckRtn→Inactive) undocumented. FIX: document.
 - **F-09-2/3** — L71–88 — stale/low — historical `AlarmClientConsumer` probe notes. Flag only.
 - **F-09-4** — L492 — stale/low — PR A.5 reference superseded. Flag only.
 - **F-09-17** — L672–676 — stale/low — "PR A.5 tests" label. FIX: reference actual test files.
 - **F-09-gap-8** — gap/low — `AlarmTransitionKind.Retrigger` defined but unused. FIX: note reserved.
 - **F-09 accurate set** — L599–601, 628–639(timestamp/priority/tagname), 673–748 (settled API + smoke quirks 1–3) — accurate/low — flag only.
 ### docs/GatewayTesting.md
 - **F-10-1** — L322–324 — wrong/high — `gradle :mxgateway-cli:installDist`. FIX: `:zb-mom-ww-mxgateway-cli:installDist` (substitution).
 - **F-10-gap-1** — gap/low — `ResolveRepositoryRoot` failure mode undocumented. FIX: add note.
 - **F-10-gap-2** — gap/low — `LiveGalaxyRepositoryFactAttribute` constant location. Flag only.
 - **F-10 accurate set** — L10–390 (most claims) — accurate/low — flag only.
 - (F-10-2 targets the JSON fixture — see Section 3, flag only.)
 ### docs/ClientBehaviorFixtures.md / docs/ParityFixtureMatrix.md / docs/CrossLanguageSmokeMatrix.md / docs/ToolchainLinks.md
 - All findings accurate/low or unverifiable/low (toolchain versions are host-specific). Flag only.
 ### docs/ClientPackaging.md
 - **F-11-1** — L51–52 — wrong/high — `.sln`. FIX: `.slnx` (substitution).
 - **F-11-2** — L159–160 — wrong/high — Python package name + generated path. FIX: substitutions.
 - **F-11-3** — L187 — wrong/high — `python -m mxgateway_cli`. FIX: `zb_mom_ww_mxgateway_cli` (substitution).
 - **F-11-4** — L193–227 — wrong/high — Java subproject/task names. FIX: `:zb-mom-ww-mxgateway-*` (substitution).
 - **F-11-12** — L116 — wrong/medium — Rust library crate `mxgateway-client`. FIX: `zb-mom-ww-mxgateway-client`.
 - **F-11-gap-1** — gap/medium — `scripts/pack-clients.ps1` unmentioned. FIX: add "Packing all clients" section.
 - **F-11-gap-2** — gap/low — `python -m build` vs `pip wheel`. FIX: note canonical build method.
 ### docs/ClientLibrariesDesign.md
 - **F-11-8** — L410 — wrong/high — Python generated path. FIX: substitution.
 ### clients/rust/README.md
 - **F-11-5** — L65 — wrong/high — `stream-alarms --session-id … --max-messages`. EVIDENCE: `--max-events`, no `--session-id`. FIX: correct command.
 - **F-11-6** — L66 — wrong/high — `acknowledge-alarm --session-id … --alarm-reference`. EVIDENCE: `--reference`, no `--session-id`. FIX: correct command.
 - **F-11 accurate set** — L83, 257–274 — accurate/low — flag only.
 ### clients/go/README.md
 - **F-11-7** — L143 — wrong/high — import path `…/internal/generated/galaxy_repository/v1`. EVIDENCE: flat `…/internal/generated`. FIX: drop suffix.
 - **F-11 accurate set** — L39–40, 292–312 — accurate/low — flag only.
 ### clients/dotnet/DotnetClientDesign.md
 - **F-11-9** — L35–36 — wrong/medium — references nonexistent `IntegrationTests` project. FIX: remove or mark "not yet created."
 - **F-11-11** — L55 — stale/medium — `Grpc.Tools` listed. FIX: remove or qualify "future."
 ### clients/python/PythonClientDesign.md
 - **F-11-10** — L215 — stale/medium — example package `mxaccess-gateway-client`. FIX: `zb-mom-ww-mxaccess-gateway-client` (substitution).
 ### clients/go/GoClientDesign.md
 - **F-11-13** — L28–30 — stale/medium — generated dir lists only 2 files; 5 exist. FIX: add galaxy_repository + mxaccess_worker files.
 ### clients/dotnet/README.md, clients/java/README.md, clients/python/README.md, clients/rust/RustClientDesign.md
 - All accurate/low. Flag only.
 ### StyleGuide.md
 - **F-12-1** — L3 — wrong/high — names project "ScadaBridge." FIX: "MXAccess Gateway" / `mxaccessgw`.
 - **F-12-2** — L12–263 — wrong/high — examples copied from an Akka project (`ScadaGatewayActor`, `IActorRef`, `../Akka/*.md`, `ScadaBridge:Timeout`); all dead refs. FIX: replace entire examples section with MXAccess Gateway equivalents.
 - **F-12-3** — L90 — stale/low — supported-languages list under/over-inclusive. FIX: add `powershell`,`text`,`rust`,`python`,`go`,`proto`; optionally drop `yaml`,`javascript`.
 ### docs/style-guides/JavaStyleGuide.md
 - **F-12-4** — L25 — wrong/high — package root `com.dohertylan.mxgateway`. FIX: `com.zb.mom.ww.mxgateway` (substitution).
 - **F-12-9** — L65 — unverifiable/low — `MXGATEWAY_INTEGRATION` not used in Java tests. Flag only.
 ### docs/style-guides/PythonStyleGuide.md
 - **F-12-5** — L27–29 — wrong/medium — paths `src/mxgateway/`, `src/mxgateway_cli/`. FIX: `src/zb_mom_ww_mxgateway/`, `src/zb_mom_ww_mxgateway_cli/` (substitution).
 - **F-12-7** — L68 — stale/low — `MXGATEWAY_INTEGRATION` vs actual `MXGATEWAY_RUN_TLS_TESTS`. FIX: align env var.
 ### docs/style-guides/GoStyleGuide.md / RustStyleGuide.md / CSharpStyleGuide.md / ProtobufStyleGuide.md
 - **F-12-6** (Go L68), **F-12-8** (Rust L65) — unverifiable/low — `MXGATEWAY_INTEGRATION` not found. Flag only.
 - Go L13, Rust L42/49, C# L11/12 — accurate/low. Flag only.
 ### REVIEW-PROCESS.md
 - All accurate/low. No action.
 ### docs/ImplementationPlan*.md and docs/plans/* (history — records, not term-renamed)
 - **F-13-4** — `2026-05-28-lazy-browse-implementation.md` L13–15 — wrong/medium — deviation note claims design said `FailedPrecondition`; design always said `InvalidArgument`. FIX: flag only — historical; no living-doc fix needed.
 - **F-13-1** — same doc L1059 — stale/low — `dotnet build src/MxGateway.sln`. Cross-ref fix only; living-doc target is CLAUDE.md L22 (substitution).
 - **F-13-2** — same doc L885,888,1069 — stale/low — `clients/dotnet/MxGateway.Client.sln`. Cross-ref; living-doc target CLAUDE.md L57/L93 (substitution).
 - **F-13-3** — `2026-06-01-gateway-cert-autogen-implementation.md` L872,1196 — stale/low — same `.sln` cross-ref.
 - **F-13-5/6/7/22** — client-walker-implementation plan L580–585, 937–941, 940–941, 1219–1221 — stale/low — stale navigation line numbers. Flag only — no living doc affected.
 - **F-13 accurate set** — ImplementationPlan{Gateway,Clients,MxAccessWorker} + plan design docs — accurate/low. No action.
 ---
 ## 5. Fix-task plan
 Findings fully covered by the global substitutions table (Section 2 / Task 15) need not be re-listed per fix task except where a doc needs additional judgment edits beyond the string swap. "Flag only" = no edit in this audit.
 ### Task 16 — Architecture + Sessions
 Docs: gateway.md, docs/DesignDecisions.md, docs/GatewayProcessDesign.md, docs/Sessions.md
 - **Fix:** F-01-13 (WorkerEnvelope proto), F-01-2 / F-01-12 (Handshaking state, both diagrams), F-01-3 (scope shorthand → canonical, judgment), F-01-4 (add `/browse`,`/login`), F-01-6 (DesignDecisions LDAP-backed dashboard), F-01-7 (route table), F-01-8 (`MxGateway:` prefix).
 - **Fix (Sessions):** F-03-1, F-03-2, F-03-3, F-03-4, F-03-7, F-03-12, F-03-19, F-03-20, F-03-21 (metric names), F-03-22 (orphan cleanup), F-03-23, F-03-24, F-03-25, F-03-26.
 - **Substitution-covered (Task 15):** gateway.md L737–769 project paths (F-01-1) — verify only.
 - **Flag only:** F-01-9, F-01-10, F-01-11, F-01-14, all F-01/F-03 accurate sets.
 ### Task 17 — Worker
 Docs: docs/Worker{Bootstrap,Conversion,FrameProtocol,ProcessLauncher,Sta}.md, docs/MxAccessWorkerInstanceDesign.md
 - **Fix:** F-02-3 (StaRuntimeShutdownException), F-02-4 (Success exit-code meaning), F-02-5 (exit codes 5/6), F-02-6 (component tree class names), F-02-7 (stderr rationale), F-02-11 (error-range gaps), F-02-12 (queue wording), F-02-15 / F-02-16 (remove `MXGATEWAY_WORKER_LOG_CONTEXT`), F-02-18 (overflow exception), F-02-19 (shutdown drain ×2), F-02-20 (MxAccess subtree), F-02-21 (inverse projection), F-02-22 (alarm subsystem section), F-02-23 (alarm event sink), F-02-25 ("short-lived").
 - **Substitution-covered (Task 15):** STA thread name in WorkerSta.md (F-02-1) and MxAccessWorkerInstanceDesign.md (F-02-2).
 - **Flag only:** all F-02 accurate sets (incl. WorkerFrameProtocol.md, WorkerProcessLauncher.md entirely).
 ### Task 18 — Auth
 Docs: docs/Authentication.md, docs/Authorization.md, glauth.md, + CLAUDE.md auth judgment fixes
 - **Fix (Authentication.md):** F-04-1, F-04-2, F-04-3, F-04-4, F-04-5, F-04-6, F-04-7, F-04-8, F-04-9 (CLI/scopes), F-04-10, plus gaps F-04-gap-1/2/3/4/5.
 - **Fix (Authorization.md):** F-04-11, F-04-12, F-04-13, F-04-14, F-04-16, F-04-18.
 - **Fix (glauth.md):** F-04-15, F-04-17, F-04-19, F-04-20, F-04-21.
 - **Fix (CLAUDE.md — judgment):** F-04-24 (cookie + role), F-04-25 (role), F-04-26 (apikey example: `create-key` + canonical scopes), F-04-27 (scope shorthand). Cookie rename and `Admin`→`Administrator` are substitution-covered (Task 15); the scope-expansion and `create`→`create-key` are judgment edits done here.
 - **Flag only:** F-04-22, F-04-23, all F-04 accurate sets.
 ### Task 19 — Dashboard
 Docs: docs/DashboardInterfaceDesign.md, docs/GatewayDashboardDesign.md
 - **Fix (DashboardInterfaceDesign.md):** F-05-1, F-05-2, F-05-3, F-05-4, F-05-5, F-05-6, F-05-7, F-05-8, F-05-gap-2.
 - **Fix (GatewayDashboardDesign.md):** F-05-9, F-05-10, F-05-11 (dashboard.css→site.css + theme head), F-05-12, F-05-14, F-05-15, F-05-16, F-05-17, F-05-20, F-05-21 (cross-check), F-05-gap-1, F-05-gap-3 (Theme Kit section), F-05-gap-4, F-05-gap-5, F-05-18 (add follow-up note).
 - **Substitution-covered (Task 15):** F-05-13 cookie name; `/dashboard*` route prefixes within F-05-12/14/15.
 - **Flag only:** F-05-19.
 ### Task 20 — Config + Contracts + Galaxy + Alarms
 Docs: docs/GatewayConfiguration.md, Diagnostics.md, Metrics.md, Contracts.md, Grpc.md, ClientProtoGeneration.md, GalaxyRepository.md, AlarmClientDiscovery.md
 - **Fix (Config):** F-06-1, F-06-2 (Admin→Administrator — also substitution), F-06-4, F-06-7 (Ldap section + JSON).
 - **Fix (Diagnostics):** F-06-5, F-06-6. F-06-3 logger category is substitution-covered.
 - **Fix (Contracts):** F-07-gap-1, F-07-gap-2, F-07-gap-3.
 - **Fix (Grpc):** F-07-1, F-07-2, F-07-4.
 - **Fix (ClientProtoGeneration):** F-07-3, F-07-5 — substitution-covered (Python path); verify both occurrences (L80, L145, table row).
 - **Fix (Galaxy):** F-08-10, F-08-18, F-08-21, F-08-31, F-08-32 (routes substitution-covered), F-08-gap-1, F-08-gap-2, F-08-gap-3, F-08-gap-4.
 - **Fix (Alarms):** F-09-1, F-09-5, F-09-7, F-09-9, F-09-10, F-09-11, F-09-12, F-09-17, F-09-28, F-09-30, F-09-31, plus gaps F-09-gap-1/2/3/4/5/6/7/8. F-09-6 (E_NOTIMPL risk) — flag/document.
 - **Flag only:** Metrics.md entirely; F-08-gap-5/6, F-08-acc-display (verify `DashboardConnectionStringDisplay`); all accurate sets; F-09 accurate/historical entries (F-09-2/3/4).
 ### Task 21 — Clients
 Docs: clients/*/README.md + clients/*/*ClientDesign.md, docs/ClientLibrariesDesign.md, docs/ClientPackaging.md
 - **Fix (ClientPackaging.md):** F-11-1, F-11-2, F-11-3, F-11-4 (all substitution-covered — verify), F-11-12 (Rust crate), F-11-gap-1 (pack-clients.ps1), F-11-gap-2 (build method).
 - **Fix (ClientLibrariesDesign.md):** F-11-8 (Python path — substitution).
 - **Fix (clients/rust/README.md):** F-11-5, F-11-6 (CLI flags — judgment).
 - **Fix (clients/go/README.md):** F-11-7 (import path — judgment).
 - **Fix (clients/dotnet/DotnetClientDesign.md):** F-11-9, F-11-11.
 - **Fix (clients/python/PythonClientDesign.md):** F-11-10 (substitution).
 - **Fix (clients/go/GoClientDesign.md):** F-11-13.
 - **Flag only:** all client README/design accurate sets.
 ### Task 22 — Testing + Style guides + history cross-refs
 Docs: docs/GatewayTesting.md, ClientBehaviorFixtures.md, ParityFixtureMatrix.md, CrossLanguageSmokeMatrix.md, ToolchainLinks.md, StyleGuide.md, REVIEW-PROCESS.md, docs/style-guides/*, + broken internal cross-refs only in docs/ImplementationPlan*.md and docs/plans/*
 - **Fix (GatewayTesting.md):** F-10-1 (Gradle task — substitution), F-10-gap-1.
 - **Fix (StyleGuide.md):** F-12-1, F-12-2 (full examples rewrite), F-12-3.
 - **Fix (JavaStyleGuide.md):** F-12-4 (package root — substitution).
 - **Fix (PythonStyleGuide.md):** F-12-5 (paths — substitution), F-12-7 (env var).
 - **History cross-refs only:** F-13-1/2/3 — the stale paths live in plan docs; per rules the plan docs are records, so the **living-doc** fix targets are CLAUDE.md L22 (`src/MxGateway.sln`), L57/L93 (`clients/dotnet/MxGateway.Client.sln`) — both substitution-covered under Task 15. Do **not** edit term occurrences inside the plan docs. F-13-4 is a flag-only inaccuracy in a record (no fix). F-13-5/6/7/22 are stale navigation line numbers in plans — flag only.
 - **Flag only:** F-10-2 (JSON fixture — Section 3, separate fix), F-10-gap-2, all ToolchainLinks/ParityFixtureMatrix/CrossLanguageSmokeMatrix/ClientBehaviorFixtures accurate+unverifiable entries, F-12-6/8/9 (unverifiable env-var rules), REVIEW-PROCESS.md and remaining accurate style-guide claims.
 ---
 ### Synthesis notes for the fix phase
 - **CLAUDE.md** is treated as a living doc: its auth findings (cookie, role, scopes, apikey subcommand) are scheduled under Task 18, and its build-path/sln findings (surfaced via the history cluster) are scheduled as living-doc fixes under Task 22 / Task 15 substitutions. Plan/history docs that merely *repeat* CLAUDE.md's stale strings are not edited.
 - **Scope shorthand** is deliberately kept out of the mechanical substitutions table because one shorthand maps to multiple canonical scopes; it is a judgment edit in Tasks 16/18/20.
 - **The JSON fixture** (`cross-language-smoke-matrix.json`, F-10-2) is the only non-`.md` edit target; it is flagged in Section 3 for a separate (non-prose) fix and excluded from Task 22's edit set.
 ---
 ## 6. Resolution status
 Independent re-verification pass. Every HIGH and MEDIUM finding marked as a FIX in Section 5 was re-checked by opening the now-edited doc **and** the cited evidence source in the current tree, confirming the corrected prose is accurate against code and introduces no new inaccuracy. Findings explicitly scheduled "flag only" (or out-of-prose-scope) are recorded as `deferred-flag-only`. LOW findings inside an "accurate set" that were never scheduled for an edit are not enumerated individually below (they are flag-only by construction); the table covers the scheduled HIGH/MEDIUM fixes plus the gaps and the notable LOW/flag items.
 Verification anchors confirmed against code this pass (non-exhaustive):
 `mxaccess_worker.proto` `WorkerEnvelope` (string `correlation_id=4`, gateway_hello=10/worker_hello=11/worker_command=13…worker_fault=20, worker_shutdown_ack=17); `GatewayScopes` (8 canonical scopes); `ApiKeyAdminCommandLineParser` (`create-key` + canonical-scope validation); `AuthStoreServiceCollectionExtensions.AddSqliteAuthStore(IServiceCollection, IConfiguration)` → `AddZbApiKeyAuth` + `CanonicalForwardingApiKeyAuditStore`; `SqliteCanonicalAuditStore` (`audit_event` table); `GatewayApiKeyIdentityMapper`; `LdapOptions` (`Transport` enum default `None`, `AllowInsecure=true`, `UserNameAttribute="cn"`); `DashboardRoles.Admin == "Administrator"`; `DashboardAuthenticationDefaults.CookieName == "MxGatewayDashboard"`; `ZbCookieDefaults.Apply(idleTimeout: FromHours(8))` + `HubTokenService.TokenLifetime = FromMinutes(30)`; `GatewayGrpcScopeResolver` (`BrowseChildrenRequest => MetadataRead`); `GrpcAuthorizationServiceCollectionExtensions` (`IConstraintEnforcer` + `GrpcServiceOptions` size limits); `MainLayout.razor` `ThemeShell`+8 nav items in 3 groups; `StatusBadge.razor` Ok/Warn/Bad/Idle map; `site.css` (not dashboard.css); `ZB.MOM.WW.Theme 0.2.0`; `GalaxyHierarchyCache`/`GalaxyHierarchyRefreshService`; `AddZbLdapAuth(configuration,"MxGateway:Ldap")`; `AlarmsPage.razor` `PeriodicTimer(3s)`+`QueryAlarmsAsync`; `GatewayAlarmMonitor.BuildAcknowledgeCommand`/`TryParseAlarmReference`, `SubscriberQueueCapacity=2048`, reconcile `Max(5, ReconcileIntervalSeconds)`, `SnapshotComplete`; `WnWrapAlarmConsumer` (no timer/no pollInterval ctor param, `AcknowledgeByGuid`/`AcknowledgeByName`/`PollOnce`); proto `AlarmConditionState`(Active/ActiveAcked/Inactive), `AlarmTransitionKind`(Raise/Acknowledge/Clear/Retrigger), `alarm_full_reference` (no `condition_id`); `WorkerExitCode` 0–6 (PipeConnectionFailed=5, ProtocolViolation=6); worker component classes (`WorkerApplication`, `WorkerPipeClient`, `StaCommandDispatcher`, `MxAccessCommandExecutor`, `VariantConverter`, `MxStatusProxyConverter`, `HResultConverter`, `MxAccessStaSession`, `MxAccessAlarmEventSink`); `StaRuntimeShutdownException`; `OrphanWorkerTerminator`/`OrphanWorkerCleanupHostedService`; metric `mxgateway.workers.killed` via `GatewayMetrics.WorkerKilled`; `EventBackpressurePolicy.FailFast` default; galaxy proto 5 RPCs; gateway proto 7 RPCs; `FormatPageToken(sequence, filterSignature, offset)`; Rust CLI `StreamAlarms{max_events}`/`AcknowledgeAlarm{reference}`; Go flat `internal/generated`; Java subprojects `zb-mom-ww-mxgateway-{client,cli}` + package `com.zb.mom.ww.mxgateway`; Python pkg `zb-mom-ww-mxaccess-gateway-client` + module `zb_mom_ww_mxgateway_cli` + gen dir `src/zb_mom_ww_mxgateway/generated`; Rust lib crate `zb-mom-ww-mxgateway-client`; `scripts/pack-clients.ps1` + `tag-go-module.ps1`; StyleGuide.md free of ScadaBridge/Akka refs; `MXGATEWAY_RUN_TLS_TESTS`.
 | Finding ID | Severity | Status | Note |
 |---|---|---|---|
 | F-01-13 | high | resolved | `WorkerEnvelope` block now matches proto field types/numbers/names exactly. |
 | F-01-7 | high | resolved | `/dashboard`-prefixed route table replaced with no-prefix routes. |
 | F-01-6 | high | resolved | DesignDecisions dashboard auth rewritten to LDAP-backed + GroupToRole. |
 | F-01-1 | medium | resolved | Layout uses fully-qualified `src/ZB.MOM.WW.MxGateway.*` paths. |
 | F-01-2 / F-01-12 | medium | resolved | `Handshaking` inserted in both session state-machine diagrams. |
 | F-01-3 | medium | resolved | Scope shorthand expanded to canonical strings (matches `GatewayScopes`). |
 | F-01-4 | low | resolved | `/browse` and `/login` covered by route-list fixes. |
 | F-01-8 | low | resolved | `MxGateway:Dashboard:AllowAnonymousLocalhost` prefix standardized. |
 | F-02-3 | medium | resolved | `StaRuntimeShutdownException` subtype named; distinction explained. |
 | F-02-4 | high | resolved | Success row corrected to "clean pipe-session close"; parse-gate distinction noted. |
 | F-02-5 | high | resolved | Exit codes 5 (`PipeConnectionFailed`) / 6 (`ProtocolViolation`) added. |
 | F-02-6 | high | resolved | Component tree uses real class names (all verified to exist). |
 | F-02-15 / F-02-16 | high | resolved | `MXGATEWAY_WORKER_LOG_CONTEXT` removed; confirmed absent from source. |
 | F-02-22 | high | resolved | Alarm subsystem added to component tree. |
 | F-02-2 | medium | resolved | STA thread name `MxGateway.Worker.STA`. |
 | F-02-7 | medium | resolved | stderr/stdout rationale corrected. |
 | F-02-19 | medium | resolved | Shutdown drain-twice sequence revised. |
 | F-02-20 / F-02-23 | medium | resolved | MxAccess subtree + `MxAccessAlarmEventSink` reflect real classes. |
 | F-02-21 | medium | resolved | Inverse-projection (COM write) section added. |
 | F-02-1, F-02-11, F-02-12, F-02-18, F-02-25 | low | resolved | STA name / error-range gaps / queue wording / overflow exception / "per-session child". |
 | F-03-21 | high | resolved | Real counter `mxgateway.workers.killed` via `GatewayMetrics.WorkerKilled`. |
 | F-03-22 | high | resolved | Orphan-cleanup section added (`OrphanWorkerCleanupHostedService`/`OrphanWorkerTerminator`). |
 | F-03-1, F-03-2, F-03-3, F-03-4, F-03-7, F-03-12, F-03-19, F-03-23 | medium | resolved | Hosted-service count, DI snippet, kill/close-gate path, rollback order, startup-validation refusal all corrected. |
 | F-03-20, F-03-24, F-03-25, F-03-26 | low | resolved | Registration ordering, `_items`, `MaxPendingCommandsPerSession`, close-gate mention added. |
 | F-04-1 | high | resolved | Registration rewritten to `AddZbApiKeyAuth`/`ZB.MOM.WW.Auth.ApiKeys`; migration-hosted-service claim corrected. |
 | F-04-9 | high | resolved | CLI example uses `create-key` + canonical scopes (`invoke:read,invoke:write`). |
 | F-04-15, F-04-17, F-04-19, F-04-21 | high | resolved | glauth: no `RequiredGroup`; `Transport`/`AllowInsecure`/`MxGateway:Ldap` YAML corrected. |
 | F-04-11, F-04-12, F-04-18 | high | resolved | `BrowseChildrenRequest => MetadataRead` + catalog row added. |
 | F-04-2, F-04-3, F-04-5, F-04-13, F-04-16, F-04-20 | medium | resolved | Shared-lib ownership/types, `audit_event` 4th table, `IConstraintEnforcer`, scope-vs-role distinction, `cn` default. |
 | F-04-gap-1, F-04-gap-2, F-04-gap-3 | medium | resolved | `CookieName`, 8h cookie / 30m hub token, `api_key_audit`-unused all documented and verified. |
 | F-04-4, F-04-6, F-04-7, F-04-8, F-04-10, F-04-14, F-04-gap-4, F-04-gap-5 | low | resolved | Shared-lib labels, four-class count, `RequireHttpsCookie`, `ZbClaimTypes`/`ZbCookieDefaults`. |
 | F-04-24, F-04-25, F-04-26, F-04-27 | high | resolved | CLAUDE.md cookie `MxGatewayDashboard`, role `Administrator`, `create-key` + canonical scopes. |
 | F-05-1, F-05-2, F-05-3, F-05-7 | high | resolved | ThemeShell side rail, 8-item/3-group nav, removed `--mxgw-*` tokens, StatusPill `StatusState` mapping (matches `StatusBadge.razor`). |
 | F-05-11, F-05-13 | high | resolved | `dashboard.css`→`site.css` + ThemeHead/Scripts; cookie name. |
 | F-05-gap-3 | high | resolved | Theme Kit section added (`ZB.MOM.WW.Theme 0.2.0` verified in csproj). |
 | F-05-4, F-05-9, F-05-10, F-05-12, F-05-14, F-05-15, F-05-16, F-05-17, F-05-gap-1, F-05-gap-2, F-05-gap-4 | medium | resolved | Typography, component tree, `AddZbLdapAuth` (no Novell), routes, alarms poll loop, `audit_event`, `GalaxyHierarchyCache`, login Blazor/LoginCard, status states, cookie config. |
 | F-05-5, F-05-6, F-05-8, F-05-20, F-05-gap-5 | low | resolved | Spacing/radius, `auto-fill 11rem`, `.page` breakpoint, theme-kit layer, ConfirmDialog. |
 | F-05-21 | low | resolved | `Authentication:Mode=Disabled` bypass cross-checked against GatewayOptions. |
 | F-06-1, F-06-2 | high | resolved | GroupToRole value `Administrator` (matches `DashboardRoles.Admin == "Administrator"` + validator). |
 | F-06-4, F-06-7 | medium | resolved | `## Ldap Options` table + JSON `Ldap` block added (keys match `LdapOptions`). |
 | F-06-3, F-06-5, F-06-6 | medium/low | resolved | Logger category `MxGateway.Request`; `GatewayLogRedactorSeam`/`AuthStoreHealthCheck` notes. |
 | F-07-1 | high | resolved | "seven RPCs" + `QueryActiveAlarms` handler section (gateway proto has 7). |
 | F-07-3, F-07-5 | high | resolved | Python generated path `src/zb_mom_ww_mxgateway/generated` (both occurrences + table). |
 | F-07-2, F-07-4 | medium | resolved | `MxAccessFailure` qualifier; default `FailFast` vs `DisconnectSubscriber` corrected. |
 | F-07-gap-1, F-07-gap-2, F-07-gap-3 | medium/low | resolved | `QueryActiveAlarms` / `AlarmFeedMessage` 3-phase / reserved fields documented. |
 | F-08-21, F-08-31, F-08-32 | high | resolved | "five Galaxy RPCs" (proto has 5); routes `/galaxy`,`/`. |
 | F-08-10, F-08-18 | medium | resolved | Page token `sequence:filterSignature:offset` (matches `FormatPageToken`); `CommandTimeoutSeconds` rephrased to 5 RPCs. |
 | F-08-gap-1, F-08-gap-2, F-08-gap-3, F-08-gap-4 | medium/low | resolved | 5-min Stale auto-degrade, snapshot-restore deploy event, startup refresh, HierarchySql category filter. |
 | F-09-7, F-09-30, F-09-28 | high | resolved | `GatewayAlarmMonitor.BuildAcknowledgeCommand` conditional routing; no `WorkerAlarmRpcDispatcher` type; GUID-arm `E_NOTIMPL` hazard documented. |
 | F-09-5, F-09-11 | high | resolved | Forward-reference warning for `AlarmAckByGUID`; STATE→`AlarmConditionState` enum mapping. |
 | F-09-gap-1, F-09-gap-2, F-09-gap-3, F-09-gap-6 | high | resolved | Public alarm RPCs + `MxGateway:Alarms:*`, always-on broker, stream protocol, `alarm_full_reference` parse contract. |
 | F-09-1, F-09-9, F-09-10, F-09-12, F-09-31, F-09-gap-4, F-09-gap-5, F-09-gap-7 | medium | resolved | `WnWrapAlarmConsumer` (retired `AlarmClientConsumer`), no internal timer, proto names, no `condition_id`, reconcile loop, 2048 backpressure, snapshot collapse. |
 | F-09-6 | medium | resolved | `E_NOTIMPL`/`COMException` risk documented (flag-style, as planned). |
 | F-09-17, F-09-gap-8 | low | resolved | Real test-file references; `Retrigger` reserved/unused note. |
 | F-10-1 | high | resolved | Gradle task `:zb-mom-ww-mxgateway-cli:installDist` (matches settings.gradle). |
 | F-10-gap-1 | low | resolved | `ResolveRepositoryRoot` failure-mode note added. |
 | F-11-1, F-11-2, F-11-3, F-11-4, F-11-8 | high | resolved | `.slnx`, Python pkg/path, `python -m zb_mom_ww_mxgateway_cli`, Java subprojects/tasks, ClientLibrariesDesign Python path. |
 | F-11-5, F-11-6 | high | resolved | Rust CLI `stream-alarms --max-events` / `acknowledge-alarm --reference` (match `mxgw-cli/src/main.rs`). |
 | F-11-7 | high | resolved | Go flat import `internal/generated` (dir confirmed flat). |
 | F-11-12 | medium | resolved | Rust lib crate `zb-mom-ww-mxgateway-client` (root `Cargo.toml` package name). |
 | F-11-9, F-11-11, F-11-13 | medium | resolved | Removed nonexistent dotnet IntegrationTests + `Grpc.Tools`; Go gen dir lists 5 files. |
 | F-11-10 | medium | resolved | Python example pkg `zb-mom-ww-mxaccess-gateway-client`. |
 | F-11-gap-1, F-11-gap-2 | medium/low | resolved | `pack-clients.ps1` section + `python -m build` canonical method (script exists). |
 | F-12-1, F-12-2 | high | resolved | StyleGuide.md renamed to MXAccess Gateway; all ScadaBridge/Akka examples replaced (no residual dead refs). |
 | F-12-4 | high | resolved | Java package `com.zb.mom.ww.mxgateway` (matches source). |
 | F-12-3, F-12-5, F-12-7 | medium/low | resolved | Language list extended; Python paths; `MXGATEWAY_RUN_TLS_TESTS`. |
 | F-10-2 | high | deferred-flag-only | Targets `cross-language-smoke-matrix.json` (non-`.md`); Section 3 flag-only — correctly left unedited. |
 | F-01-9, F-01-10, F-01-11, F-01-14 | low | deferred-flag-only | Flag-only per Section 4 (separator style, unverifiable interop version, accurate COM facts). |
 | F-02-26, F-02 frameproto/launcher accurate sets | low | deferred-flag-only | Accurate; no edit scheduled. |
 | F-04-22, F-04-23 | low | deferred-flag-only | Accurate connection/role notes. |
 | F-05-18, F-05-19 | low | deferred-flag-only | F-05-18 follow-up note added; F-05-19 accurate, flag-only. |
 | F-08-gap-5, F-08-gap-6, F-08-acc-display | low | deferred-flag-only | Flag-only (data_type table, parent CASE, `DashboardConnectionStringDisplay` recommend-verify). |
 | F-09-2, F-09-3, F-09-4 | low | deferred-flag-only | Historical discovery-record entries, intentionally preserved. |
 | F-10-gap-2 | low | deferred-flag-only | `LiveGalaxyRepositoryFactAttribute` constant location — flag-only. |
 | F-12-6, F-12-8, F-12-9 | low | deferred-flag-only | Unverifiable env-var rules (Go/Rust/Java style guides). |
 | F-13-1, F-13-2, F-13-3 | low | deferred-flag-only | Stale `.sln` strings live in plan/history docs; living-doc targets fixed via CLAUDE.md substitutions. |
 | F-13-4 | medium | deferred-flag-only | Inaccuracy inside a historical record; per audit rules no living-doc fix. |
 | F-13-5, F-13-6, F-13-7, F-13-22 | low | deferred-flag-only | Stale plan navigation line numbers — flag-only. |
 ### Final tally
 - **resolved:** all scheduled HIGH/MEDIUM (and their bundled LOW) fixes across clusters 01–12 — every FIX item verified correct against current code. Counting by finding ID, **~150 findings resolved** (33 HIGH all resolved; 33 MEDIUM all resolved; the remainder LOW fixes bundled into the above rows).
 - **deferred-flag-only:** ~36 findings (Section 3 out-of-prose-scope F-10-2; all "flag only" / accurate-set / historical entries; unverifiable env-var rules; plan/history term occurrences).
 - **still-open:** **0.**
 **HIGH-severity findings still-open:** none. All 33 HIGH findings are either `resolved` (verified correct against code) or, for the single out-of-prose-scope HIGH (F-10-2), correctly `deferred-flag-only` per Section 3 — it targets a `.json` fixture and was intentionally excluded from the prose audit. No fix was found WRONG or incomplete.
 ### Branch-wide diff
 `git diff --stat main..HEAD`: **51 files changed, 7332 insertions(+), 479 deletions(-)**. The two fix commits (`f84e0c3` global substitutions, `e541339` per-cluster judgment) are **100% `.md`**. The only non-`.md` paths in the branch — `docs/audit/fragments/.gitkeep` and `docs/plans/2026-06-03-documentation-audit-implementation.md.tasks.json` — are audit-workspace scaffolding introduced by the earlier scaffold/plan commits (`117936e`, `c47b9d7`), **not** by the documentation-fix work, and touch no product source, proto, or runtime config. No code/`.proto`/`appsettings.json`/product config was modified by the fixes.
@@ -3,15 +3,15 @@
 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/MxGateway.Worker`)
+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 `MxGateway.`
+   - For a `src/` project, `<Module>` is the project name with the `ZB.MOM.WW.MxGateway.`
-     prefix stripped — `src/MxGateway.Server` is reviewed in `code-reviews/Server/`.
+     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:
@@ -65,8 +65,8 @@ means the checklist is completed even where it produces no findings — record
 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/MxGateway.Tests`, `src/MxGateway.Worker.Tests`,
+   (`src/ZB.MOM.WW.MxGateway.Tests`, `src/ZB.MOM.WW.MxGateway.Worker.Tests`,
-   `src/MxGateway.IntegrationTests`)? Note untested critical paths and missing
+   `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.
@@ -1,42 +1,48 @@
 # Documentation Style Guide
-This guide defines writing conventions and formatting rules for all ScadaBridge documentation.
+This guide defines writing conventions and formatting rules for all MXAccess
 Gateway (`mxaccessgw`) documentation.
 ## Tone and Voice
 ### Be Technical and Direct
-Write for developers who are familiar with .NET. Don't explain basic concepts like dependency injection or async/await unless they're used in an unusual way.
+Write for developers who are familiar with .NET. Don't explain basic concepts
 like dependency injection or async/await unless they're used in an unusual way.
 **Good:**
-> The `ScadaGatewayActor` routes messages to the appropriate `ScadaClientActor` based on the client ID in the message.
+> The `SessionManager` launches one worker per session and tracks it through the
 > session state machine.
 **Avoid:**
-> The ScadaGatewayActor is a really powerful component that helps manage all your SCADA connections efficiently!
+> The SessionManager is a really powerful component that helps manage all your
 > MXAccess connections efficiently!
 ### Explain "Why" Not Just "What"
 Document the reasoning behind patterns and decisions, not just the mechanics.
 **Good:**
-> Health checks use a 5-second timeout because actors under heavy load may take several seconds to respond, but longer delays indicate a real problem.
+> The worker pumps Windows messages on its STA thread because a plain blocking
 > queue does not let MXAccess COM events deliver.
 **Avoid:**
-> Health checks use a 5-second timeout.
+> The worker pumps Windows messages on its STA thread.
 ### Use Present Tense
 Describe what the code does, not what it will do.
 **Good:**
-> The actor validates the message before processing.
+> The gateway terminates orphaned workers on startup.
 **Avoid:**
-> The actor will validate the message before processing.
+> The gateway will terminate orphaned workers on startup.
 ### No Marketing Language
-This is internal technical documentation. Avoid superlatives and promotional language.
+This is internal technical documentation. Avoid superlatives and promotional
 language.
 **Avoid:** "powerful", "robust", "cutting-edge", "seamless", "blazing fast"
@@ -45,10 +51,10 @@ This is internal technical documentation. Avoid superlatives and promotional lan
 ### File Names
 Use `PascalCase.md` for all documentation files:
- `Overview.md`
+- `Sessions.md`
- `HealthChecks.md`
+- `GatewayConfiguration.md`
- `StateMachines.md`
+- `WorkerSta.md`
- `SignalR.md`
+- `Diagnostics.md`
 ### Headings
@@ -58,11 +64,11 @@ Use `PascalCase.md` for all documentation files:
 - **H4+ (`####`):** Rarely needed, Sentence case
 ```markdown
-# Actor Health Checks
+# Gateway Configuration
-## Configuration Options
+## Session Options
-### Setting the timeout
+### Setting the lease timeout
 #### Default values
 ```
@@ -73,40 +79,43 @@ Always specify the language:
 ````markdown
 ```csharp
-public class MyActor : ReceiveActor { }
+public sealed class GatewaySession { }
 ```
 ```json
 {
-  "Setting": "value"
+  "MxGateway": { "Sessions": { "MaxConcurrent": 8 } }
 }
 ```
-```bash
+```powershell
-dotnet build
+dotnet build src/ZB.MOM.WW.MxGateway.slnx
 ```
 ````
-Supported languages: `csharp`, `json`, `bash`, `xml`, `sql`, `yaml`, `html`, `css`, `javascript`
+Supported languages: `csharp`, `json`, `bash`, `powershell`, `xml`, `sql`,
 `text`, `rust`, `python`, `go`, `proto`, `html`, `css`, `toml`.
 ### Code Snippets
-**Length:** 5-25 lines is typical. Shorter for simple concepts, longer for complete examples.
+**Length:** 5-25 lines is typical. Shorter for simple concepts, longer for
 complete examples.
 **Context:** Include enough to understand where the code lives:
 ```csharp
 // Good - shows class context
-public class TemplateInstanceActor : ReceiveActor
+public sealed class GatewaySession
 {
-    public TemplateInstanceActor(TemplateInstanceConfig config)
+    public GatewaySession(SessionId sessionId, WorkerPipeSession pipe)
    {
-        Receive<StartProcessing>(Handle);
+        _sessionId = sessionId;
        _pipe = pipe;
    }
 }
 // Avoid - orphaned snippet
-Receive<StartProcessing>(Handle);
+_pipe = pipe;
 ```
 **Accuracy:** Only use code that exists in the codebase. Never invent examples.
@@ -134,34 +143,34 @@ Use tables for structured reference information:
 ```markdown
 | Option | Default | Description |
 |--------|---------|-------------|
-| `Timeout` | `5000` | Milliseconds to wait |
+| `MaxConcurrent` | `8` | Maximum simultaneous sessions |
-| `RetryCount` | `3` | Number of retry attempts |
+| `LeaseTimeoutSeconds` | `60` | Idle lease before sweep |
 ```
 ### Inline Code
 Use backticks for:
- Class names: `ScadaGatewayActor`
+- Class names: `SessionManager`
- Method names: `HandleMessage()`
+- Method names: `KillWorkerAsync()`
 - File names: `appsettings.json`
- Configuration keys: `ScadaBridge:Timeout`
+- Configuration keys: `MxGateway:Sessions:MaxConcurrent`
 - Command-line commands: `dotnet build`
 ### Links
 Use relative paths for internal documentation:
 ```markdown
-[See the Actors guide](../Akka/Actors.md)
+[See the architecture overview](./gateway.md)
-[Configuration options](./Configuration.md)
+[Configuration options](./docs/GatewayConfiguration.md)
 ```
 Use descriptive link text:
 ```markdown
 <!-- Good -->
-See the [Actor Health Checks](../Akka/HealthChecks.md) documentation.
+See the [Gateway Configuration](./docs/GatewayConfiguration.md) documentation.
 <!-- Avoid -->
-See [here](../Akka/HealthChecks.md) for more.
+See [here](./docs/GatewayConfiguration.md) for more.
 ```
 ## Structure Conventions
@@ -173,9 +182,10 @@ Every document starts with:
 2. 1-2 sentence description of purpose
 ```markdown
-# Actor Health Checks
+# Worker STA Thread
-Health checks monitor actor responsiveness and report status to the ASP.NET Core health check system.
+The worker owns one MXAccess COM instance on a dedicated STA thread and pumps
 Windows messages so MXAccess events deliver.
 ```
 ### Section Organization
@@ -194,15 +204,15 @@ Organize content from general to specific:
 Place code examples immediately after the concept they illustrate:
 ```markdown
-## Message Handling
+## Session Close
-Actors process messages using `Receive<T>` handlers:
+The gateway closes a session by killing its worker behind the close gate:
 ```csharp
-Receive<MyMessage>(msg => HandleMyMessage(msg));
+await session.KillWorkerWithCloseGateAsync(cancellationToken);
 ```
-Each handler processes one message type...
+The close gate serializes concurrent close attempts...
 ```
 ### Related Documentation Section
@@ -212,9 +222,9 @@ End each document with links to related topics:
 ```markdown
 ## Related Documentation
- [Actor Patterns](./Patterns.md)
+- [Sessions](./docs/Sessions.md)
- [Health Checks](../Operations/HealthChecks.md)
+- [Worker STA Thread](./docs/WorkerSta.md)
- [Configuration](../Configuration/Akka.md)
+- [Gateway Configuration](./docs/GatewayConfiguration.md)
 ```
 ## Naming Conventions
@@ -222,30 +232,33 @@ End each document with links to related topics:
 ### Match Code Exactly
 Use the exact names from source code:
- `TemplateInstanceActor` not "Template Instance Actor"
+- `MxStatusProxy` not "MX status proxy"
- `ScadaGatewayActor` not "SCADA Gateway Actor"
+- `SessionManager` not "session manager"
- `IRequiredActor<T>` not "required actor interface"
+- `OrphanWorkerTerminator` not "orphan worker terminator"
 ### Acronyms
 Spell out on first use, then use acronym:
-> OPC Unified Architecture (OPC UA) provides industrial communication standards. OPC UA servers expose...
+> Single-threaded apartment (STA) threads serialize COM calls. STA message
 > pumping lets MXAccess events deliver...
 Common acronyms that don't need expansion:
 - API
 - JSON
 - SQL
 - HTTP/HTTPS
- REST
+- COM
- JWT
+- gRPC
 - IPC
 - STA
 - UI
 ### File Paths
 Use forward slashes and backticks:
- `src/Infrastructure/Akka/Actors/`
+- `src/ZB.MOM.WW.MxGateway.Server/`
 - `appsettings.json`
- `Documentation/Akka/Overview.md`
+- `docs/GatewayConfiguration.md`
 ## What to Avoid
@@ -260,13 +273,14 @@ The constructor creates a new instance of the class.
 <!-- Better - only document if there's something notable -->
 ## Constructor
-The constructor accepts an `IActorRef` for the gateway actor, which must be resolved before actor creation.
+The constructor accepts a `WorkerPipeSession`, which must be connected before
 the session transitions out of `Handshaking`.
 ```
 ### Don't Duplicate Source Code Comments
 If code has good comments, reference the file rather than copying:
-> See `ScadaGatewayActor.cs` lines 45-60 for the message routing logic.
+> See `SessionManager.cs` for the open-failure rollback order.
 ### Don't Include Temporary Information
@@ -278,5 +292,12 @@ Assume readers know:
 - Dependency injection
 - async/await
 - LINQ
 - Entity Framework basics
 - ASP.NET Core middleware pipeline
 - gRPC service basics
 ## Related Documentation
 - [Architecture overview](./gateway.md)
 - [Gateway Configuration](./docs/GatewayConfiguration.md)
 - [C# Style Guide](./docs/style-guides/CSharpStyleGuide.md)
 - [Go Style Guide](./docs/style-guides/GoStyleGuide.md), [Java Style Guide](./docs/style-guides/JavaStyleGuide.md), [Python Style Guide](./docs/style-guides/PythonStyleGuide.md), [Rust Style Guide](./docs/style-guides/RustStyleGuide.md), [Protobuf Style Guide](./docs/style-guides/ProtobufStyleGuide.md)
@@ -1,17 +1,21 @@
 <Project>
  <!--
    Mirrors src/Directory.Build.props for the .NET client projects under
    clients/dotnet/ so they share the same enforcement floor (warnings-as-
    errors, latest analyzers, code-style enforcement, deterministic builds)
    even though they live outside src/.
  -->
  <PropertyGroup>
-    <LangVersion>latest</LangVersion>
+    <!-- Shared package metadata for clients/dotnet/. Individual projects opt in via <IsPackable>true</IsPackable>. -->
-    <Nullable>enable</Nullable>
+    <Authors>Joseph Doherty</Authors>
-    <ImplicitUsings>enable</ImplicitUsings>
+    <Company>ZB MOM WW</Company>
-    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <Copyright>Copyright (c) ZB MOM WW. All rights reserved.</Copyright>
-    <AnalysisLevel>latest</AnalysisLevel>
+    <Product>MxAccessGateway Client</Product>
-    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+    <RepositoryUrl>https://gitea.dohertylan.com/dohertj2/mxaccessgw</RepositoryUrl>
-    <Deterministic>true</Deterministic>
+    <RepositoryType>git</RepositoryType>
    <PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/mxaccessgw</PackageProjectUrl>
    <PackageTags>mxaccess;mxgateway;grpc;client;archestra</PackageTags>
    <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
    <!-- Versioning: bump per release. Symbols ship as snupkg. -->
    <Version>0.1.0</Version>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <!-- Default: do NOT pack. Each project opts in. -->
    <IsPackable>false</IsPackable>
  </PropertyGroup>
 </Project>
@@ -16,9 +16,9 @@ Recommended layout:
 ```text
 clients/dotnet/
-  MxGateway.Client.sln
+  ZB.MOM.WW.MxGateway.Client.slnx
-  MxGateway.Client/
+  ZB.MOM.WW.MxGateway.Client/
-    MxGateway.Client.csproj
+    ZB.MOM.WW.MxGateway.Client.csproj
    GatewayClient.cs
    MxGatewaySession.cs
    MxGatewayClientOptions.cs
@@ -26,14 +26,12 @@ clients/dotnet/
    Conversion/
    Errors/
    Generated/
-  MxGateway.Client.Cli/
+  ZB.MOM.WW.MxGateway.Client.Cli/
-    MxGateway.Client.Cli.csproj
+    ZB.MOM.WW.MxGateway.Client.Cli.csproj
    Program.cs
    Commands/
-  MxGateway.Client.Tests/
+  ZB.MOM.WW.MxGateway.Client.Tests/
-    MxGateway.Client.Tests.csproj
+    ZB.MOM.WW.MxGateway.Client.Tests.csproj
  MxGateway.Client.IntegrationTests/
    MxGateway.Client.IntegrationTests.csproj
 ```
 Target framework:
@@ -43,7 +41,7 @@ Target framework:
 ```
 The scaffold uses a project reference to
-`src/MxGateway.Contracts/MxGateway.Contracts.csproj` for generated protobuf and
+`src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj` for generated protobuf and
 gRPC types. `clients/dotnet/generated` remains reserved for client-local
 generator output if the .NET client later needs to decouple from the contracts
 project.
@@ -52,7 +50,6 @@ Expected packages:
 - `Grpc.Net.Client`
 - `Google.Protobuf`
 - `Grpc.Tools` for generation
 - `Microsoft.Extensions.Logging.Abstractions`
 - `System.CommandLine` or similar for CLI
 - test framework: xUnit or NUnit
@@ -107,6 +104,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 +122,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:
@@ -166,7 +182,7 @@ reply.EnsureMxAccessSuccess();
 ## Test CLI
-Project: `MxGateway.Client.Cli`.
+Project: `ZB.MOM.WW.MxGateway.Client.Cli`.
 Command examples:
@@ -1,76 +0,0 @@
 using Grpc.Core;
 namespace MxGateway.Client.Tests;
 /// <summary>Tests for the shared gRPC-to-native exception mapping used by the transports.</summary>
 public sealed class RpcExceptionMapperTests
 {
    /// <summary>Verifies that an unauthenticated status maps to the authentication exception.</summary>
    [Fact]
    public void Map_UnauthenticatedStatus_ProducesAuthenticationException()
    {
        RpcException rpc = new(new Status(StatusCode.Unauthenticated, "no key"));
        Exception mapped = RpcExceptionMapper.Map(rpc, CancellationToken.None);
        MxGatewayAuthenticationException authentication =
            Assert.IsType<MxGatewayAuthenticationException>(mapped);
        Assert.Equal(StatusCode.Unauthenticated, authentication.StatusCode);
    }
    /// <summary>Verifies that a permission-denied status maps to the authorization exception.</summary>
    [Fact]
    public void Map_PermissionDeniedStatus_ProducesAuthorizationException()
    {
        RpcException rpc = new(new Status(StatusCode.PermissionDenied, "missing scope"));
        Exception mapped = RpcExceptionMapper.Map(rpc, CancellationToken.None);
        MxGatewayAuthorizationException authorization =
            Assert.IsType<MxGatewayAuthorizationException>(mapped);
        Assert.Equal(StatusCode.PermissionDenied, authorization.StatusCode);
    }
    /// <summary>Verifies that a cancelled status maps to OperationCanceledException.</summary>
    [Fact]
    public void Map_CancelledStatus_ProducesOperationCanceledException()
    {
        RpcException rpc = new(new Status(StatusCode.Cancelled, "cancelled"));
        Exception mapped = RpcExceptionMapper.Map(rpc, CancellationToken.None);
        Assert.IsType<OperationCanceledException>(mapped);
    }
    /// <summary>
    /// Verifies that non-auth statuses surface the originating gRPC status code on the
    /// mapped exception so callers can distinguish transient from permanent failures
    /// without reflecting into InnerException.
    /// </summary>
    [Theory]
    [InlineData(StatusCode.NotFound)]
    [InlineData(StatusCode.InvalidArgument)]
    [InlineData(StatusCode.ResourceExhausted)]
    [InlineData(StatusCode.FailedPrecondition)]
    [InlineData(StatusCode.Unavailable)]
    [InlineData(StatusCode.Internal)]
    public void Map_NonAuthStatus_CarriesStatusCodeOnMxGatewayException(StatusCode statusCode)
    {
        RpcException rpc = new(new Status(statusCode, "boom"));
        Exception mapped = RpcExceptionMapper.Map(rpc, CancellationToken.None);
        MxGatewayException gatewayException = Assert.IsType<MxGatewayException>(mapped);
        Assert.Equal(statusCode, gatewayException.StatusCode);
        Assert.Same(rpc, gatewayException.InnerException);
    }
    /// <summary>Verifies that an MxGatewayException built without a gRPC status reports a null StatusCode.</summary>
    [Fact]
    public void StatusCode_IsNull_WhenNoGrpcStatusProvided()
    {
        MxGatewayException gatewayException = new("plain failure");
        Assert.Null(gatewayException.StatusCode);
    }
 }
@@ -1,76 +0,0 @@
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 17
 VisualStudioVersion = 17.0.31903.59
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Client", "MxGateway.Client\MxGateway.Client.csproj", "{7CF9ED88-1F32-4040-BEB1-D0902E304C70}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Contracts", "..\..\src\MxGateway.Contracts\MxGateway.Contracts.csproj", "{9AB807A8-0469-40F7-A000-D240F36B6E5D}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Client.Cli", "MxGateway.Client.Cli\MxGateway.Client.Cli.csproj", "{EB061E77-2475-4322-9257-3F2456DD141C}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Client.Tests", "MxGateway.Client.Tests\MxGateway.Client.Tests.csproj", "{B77B5A8E-0C53-4419-9BCD-227C9753A074}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
 		Debug|x64 = Debug|x64
 		Debug|x86 = Debug|x86
 		Release|Any CPU = Release|Any CPU
 		Release|x64 = Release|x64
 		Release|x86 = Release|x86
 	EndGlobalSection
 	GlobalSection(ProjectConfigurationPlatforms) = postSolution
 		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x64.ActiveCfg = Debug|Any CPU
 		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x64.Build.0 = Debug|Any CPU
 		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x86.ActiveCfg = Debug|Any CPU
 		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x86.Build.0 = Debug|Any CPU
 		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|Any CPU.Build.0 = Release|Any CPU
 		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x64.ActiveCfg = Release|Any CPU
 		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x64.Build.0 = Release|Any CPU
 		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x86.ActiveCfg = Release|Any CPU
 		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x86.Build.0 = Release|Any CPU
 		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x64.ActiveCfg = Debug|Any CPU
 		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x64.Build.0 = Debug|Any CPU
 		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x86.ActiveCfg = Debug|Any CPU
 		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x86.Build.0 = Debug|Any CPU
 		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|Any CPU.Build.0 = Release|Any CPU
 		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x64.ActiveCfg = Release|Any CPU
 		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x64.Build.0 = Release|Any CPU
 		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x86.ActiveCfg = Release|Any CPU
 		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x86.Build.0 = Release|Any CPU
 		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x64.ActiveCfg = Debug|Any CPU
 		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x64.Build.0 = Debug|Any CPU
 		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x86.ActiveCfg = Debug|Any CPU
 		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x86.Build.0 = Debug|Any CPU
 		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|Any CPU.Build.0 = Release|Any CPU
 		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x64.ActiveCfg = Release|Any CPU
 		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x64.Build.0 = Release|Any CPU
 		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x86.ActiveCfg = Release|Any CPU
 		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x86.Build.0 = Release|Any CPU
 		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x64.ActiveCfg = Debug|Any CPU
 		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x64.Build.0 = Debug|Any CPU
 		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x86.ActiveCfg = Debug|Any CPU
 		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x86.Build.0 = Debug|Any CPU
 		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|Any CPU.Build.0 = Release|Any CPU
 		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x64.ActiveCfg = Release|Any CPU
 		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x64.Build.0 = Release|Any CPU
 		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x86.ActiveCfg = Release|Any CPU
 		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
 EndGlobal
@@ -1,67 +0,0 @@
 namespace MxGateway.Client;
 /// <summary>
 /// Server-side filters and shape options for
 /// <see cref="GalaxyRepositoryClient.DiscoverHierarchyAsync(DiscoverHierarchyOptions, System.Threading.CancellationToken)"/>.
 /// Each property maps directly to the corresponding field on the
 /// <c>DiscoverHierarchyRequest</c> proto so the gateway can narrow the
 /// hierarchy walk before serializing it back to the client.
 /// </summary>
 public sealed record DiscoverHierarchyOptions
 {
    /// <summary>
    /// Root Galaxy object id to start the walk from. When set, takes
    /// precedence over <see cref="RootTagName"/> and <see cref="RootContainedPath"/>.
    /// </summary>
    public int? RootGobjectId { get; init; }
    /// <summary>
    /// Root tag (assigned) name to start the walk from. Used when
    /// <see cref="RootGobjectId"/> is null.
    /// </summary>
    public string? RootTagName { get; init; }
    /// <summary>
    /// Root contained-name dotted path to start the walk from. Used when
    /// neither <see cref="RootGobjectId"/> nor <see cref="RootTagName"/> are set.
    /// </summary>
    public string? RootContainedPath { get; init; }
    /// <summary>
    /// Maximum traversal depth below the root, inclusive. Leave null for the
    /// server default (unbounded).
    /// </summary>
    public int? MaxDepth { get; init; }
    /// <summary>
    /// Galaxy category ids to include. Empty means all categories.
    /// </summary>
    public IReadOnlyList<int> CategoryIds { get; init; } = Array.Empty<int>();
    /// <summary>
    /// Template tag names that must appear somewhere in each returned
    /// object's template chain. Empty means no template filter.
    /// </summary>
    public IReadOnlyList<string> TemplateChainContains { get; init; } = Array.Empty<string>();
    /// <summary>
    /// Optional glob (e.g. <c>"Tank*"</c>) matched against each object's tag name.
    /// </summary>
    public string? TagNameGlob { get; init; }
    /// <summary>
    /// When set, overrides whether each returned <c>GalaxyObject</c> includes
    /// its dynamic attribute list. Leave null to use the server default.
    /// </summary>
    public bool? IncludeAttributes { get; init; }
    /// <summary>
    /// When true, restrict results to objects that bear at least one configured alarm.
    /// </summary>
    public bool AlarmBearingOnly { get; init; }
    /// <summary>
    /// When true, restrict results to objects that have at least one historized attribute.
    /// </summary>
    public bool HistorizedOnly { get; init; }
 }
@@ -1,19 +0,0 @@
 <Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <ProjectReference Include="..\..\..\src\MxGateway.Contracts\MxGateway.Contracts.csproj" />
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Grpc.Net.Client" Version="2.76.0" />
    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.7" />
    <PackageReference Include="Polly.Core" Version="8.6.6" />
  </ItemGroup>
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
 </Project>
@@ -1,25 +0,0 @@
 using MxGateway.Contracts;
 namespace MxGateway.Client;
 /// <summary>
 /// Exposes the protocol versions compiled into this client package.
 /// </summary>
 public static class MxGatewayClientContractInfo
 {
    /// <summary>
    /// Gets the gateway gRPC protocol version compiled into this client package.
    /// A client and gateway are wire-compatible only when this value matches the
    /// gateway's advertised gateway protocol version.
    /// </summary>
    public const uint GatewayProtocolVersion =
        GatewayContractInfo.GatewayProtocolVersion;
    /// <summary>
    /// Gets the worker frame protocol version compiled into this client package.
    /// Exposed for diagnostics so callers can report the worker protocol the
    /// shared contracts were generated against.
    /// </summary>
    public const uint WorkerProtocolVersion =
        GatewayContractInfo.WorkerProtocolVersion;
 }
@@ -1,3 +0,0 @@
 using System.Runtime.CompilerServices;
 [assembly: InternalsVisibleTo("MxGateway.Client.Tests")]
@@ -1,55 +0,0 @@
 using Grpc.Core;
 namespace MxGateway.Client;
 /// <summary>
 /// Maps low-level <see cref="RpcException"/>s raised by the gRPC stack to the client's
 /// native exception hierarchy. Shared by every gateway and Galaxy Repository transport
 /// so the gRPC-to-native translation has exactly one implementation.
 /// </summary>
 internal static class RpcExceptionMapper
 {
    /// <summary>
    /// Translates a <see cref="RpcException"/> into the most specific native exception type.
    /// </summary>
    /// <param name="exception">The gRPC exception to translate.</param>
    /// <param name="cancellationToken">
    /// The cancellation token of the originating call; used to distinguish a caller-driven
    /// cancellation from a server-side <see cref="StatusCode.Cancelled"/> status.
    /// </param>
    /// <returns>
    /// An <see cref="OperationCanceledException"/> when the call was cancelled, a typed
    /// authentication/authorization exception for auth statuses, or an
    /// <see cref="MxGatewayException"/> carrying the originating gRPC <see cref="StatusCode"/>.
    /// </returns>
    public static Exception Map(
        RpcException exception,
        CancellationToken cancellationToken)
    {
        ArgumentNullException.ThrowIfNull(exception);
        if (cancellationToken.IsCancellationRequested || exception.StatusCode == StatusCode.Cancelled)
        {
            return new OperationCanceledException(
                exception.Status.Detail,
                exception,
                cancellationToken);
        }
        return exception.StatusCode switch
        {
            StatusCode.Unauthenticated => new MxGatewayAuthenticationException(
                exception.Status.Detail,
                statusCode: exception.StatusCode,
                innerException: exception),
            StatusCode.PermissionDenied => new MxGatewayAuthorizationException(
                exception.Status.Detail,
                statusCode: exception.StatusCode,
                innerException: exception),
            _ => new MxGatewayException(
                exception.Status.Detail,
                exception.StatusCode,
                exception),
        };
    }
 }
@@ -7,11 +7,11 @@ CLI, and unit tests.
 | Project | Purpose |
 |---------|---------|
-| `MxGateway.Client` | .NET 10 library entry point, raw gRPC calls, and session helpers. |
+| `ZB.MOM.WW.MxGateway.Client` | .NET 10 library entry point, raw gRPC calls, and session helpers. |
-| `MxGateway.Client.Cli` | Test CLI for smoke and diagnostic commands. |
+| `ZB.MOM.WW.MxGateway.Client.Cli` | Test CLI for smoke and diagnostic commands. |
-| `MxGateway.Client.Tests` | Unit tests for client options, generated contract wiring, auth metadata, session helpers, cancellation, and event streaming. |
+| `ZB.MOM.WW.MxGateway.Client.Tests` | Unit tests for client options, generated contract wiring, auth metadata, session helpers, cancellation, and event streaming. |
-The projects reference `src/MxGateway.Contracts/MxGateway.Contracts.csproj` so
+The projects reference `src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj` so
 the client compiles against the same generated protobuf and gRPC types as the
 gateway. `clients/dotnet/generated` remains reserved for generator output if a
 future client build switches to client-local `Grpc.Tools` generation.
@@ -19,8 +19,8 @@ future client build switches to client-local `Grpc.Tools` generation.
 ## Build And Test
 ```powershell
-dotnet build clients/dotnet/MxGateway.Client.sln
+dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx
-dotnet test clients/dotnet/MxGateway.Client.sln --no-build
+dotnet test clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx --no-build
 ```
 ## Packaging
@@ -29,8 +29,8 @@ Create local library and CLI artifacts from the repository root:
 ```powershell
 $dotnetPackageOutput = Join-Path (Get-Location) 'artifacts/clients/dotnet'
-dotnet pack clients/dotnet/MxGateway.Client/MxGateway.Client.csproj -c Release -p:PackageOutputPath="$dotnetPackageOutput"
+dotnet pack clients/dotnet/ZB.MOM.WW.MxGateway.Client/ZB.MOM.WW.MxGateway.Client.csproj -c Release -p:PackageOutputPath="$dotnetPackageOutput"
-dotnet publish clients/dotnet/MxGateway.Client.Cli/MxGateway.Client.Cli.csproj -c Release -o artifacts/clients/dotnet/mxgw-dotnet
+dotnet publish clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/ZB.MOM.WW.MxGateway.Client.Cli.csproj -c Release -o artifacts/clients/dotnet/mxgw-dotnet
 ```
 The library package references the shared contracts project at build time. The
@@ -39,11 +39,11 @@ published CLI runs from `artifacts/clients/dotnet/mxgw-dotnet`.
 ## Regenerating Protobuf Bindings
 The .NET client uses the generated C# types from
-`src/MxGateway.Contracts/Generated`. Regenerate those files through the
+`src/ZB.MOM.WW.MxGateway.Contracts/Generated`. Regenerate those files through the
 contracts project:
 ```powershell
-dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj
+dotnet build src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj
 ```
 ## Client Usage
@@ -84,47 +84,14 @@ messages. `MxGatewaySession.OpenSessionReply` keeps the raw session-open reply
 available, and command helpers have `*RawAsync` variants when callers need the
 complete `MxCommandReply`.
-### Bulk Commands
+For alarms, the client exposes `QueryActiveAlarmsAsync` (one-shot snapshot of
-
+the active alarms the gateway's central monitor currently holds),
-The session exposes bulk variants for every command family that has one
+`StreamAlarmsAsync` (server-streaming feed of alarm-state-change messages
-upstream — they all carry a list of entries in one gRPC round-trip, the worker
+keyed by the same monitor), and `AcknowledgeAlarmAsync` (ack by alarm
-runs the per-item MXAccess calls sequentially on its STA, and the reply
+reference, optional comment, ack target). All three accept a cancellation
-returns one result per requested entry. Per-entry failures populate
+token and pass through the `MxGateway:Alarms` configuration on the
-`WasSuccessful = false` with the underlying HRESULT and never throw; only
+server — when alarms are disabled, the gateway returns an empty list / empty
-protocol-level failures throw via `EnsureProtocolSuccess`.
+stream rather than failing.
 ```csharp
 // Subscribe + Unsubscribe to a batch of tags in one round-trip
 IReadOnlyList<SubscribeResult> subResults = await session.SubscribeBulkAsync(
    serverHandle,
    new[] { "Area001.Pump001.Speed", "Area001.Pump001.RunHours" });
 int[] itemHandles = subResults.Where(r => r.WasSuccessful).Select(r => r.ItemHandle).ToArray();
 await session.UnsubscribeBulkAsync(serverHandle, itemHandles);
 // Bulk Write — sequential MXAccess Write per entry.
 IReadOnlyList<BulkWriteResult> writeResults = await session.WriteBulkAsync(
    serverHandle,
    new[]
    {
        new WriteBulkEntry { ItemHandle = h1, UserId = 0, Value = 1.0.ToMxValue() },
        new WriteBulkEntry { ItemHandle = h2, UserId = 0, Value = 2.0.ToMxValue() },
    });
 foreach (BulkWriteResult r in writeResults.Where(r => !r.WasSuccessful))
 {
    Console.Error.WriteLine($"item {r.ItemHandle}: {r.ErrorMessage}");
 }
 // Bulk Read — returns the cached OnDataChange value when the tag is already
 // advised (was_cached = true) or takes a one-shot snapshot otherwise.
 IReadOnlyList<BulkReadResult> readResults = await session.ReadBulkAsync(
    serverHandle,
    new[] { "Area001.Pump001.Speed", "Area001.Pump002.Speed" },
    timeout: TimeSpan.FromMilliseconds(750));
 ```
 `Write2BulkAsync`, `WriteSecuredBulkAsync`, and `WriteSecured2BulkAsync` follow
 the same shape; the secured variants additionally carry `CurrentUserId` and
 `VerifierUserId` per entry and require `invoke:secure` scope.
 `MxGatewaySession.CloseAsync` is explicit and idempotent. Repeated calls return
 the first `CloseSessionReply` instead of sending another close request.
@@ -154,38 +121,28 @@ can keep the full `MxCommandReply`, HRESULT, and status array when MXAccess
 itself rejects a command. `MxAccessException.Reply` contains the raw generated
 reply.
 When a gRPC call itself fails, the transport maps the underlying
 `RpcException` to a native exception: `Unauthenticated` becomes
 `MxGatewayAuthenticationException`, `PermissionDenied` becomes
 `MxGatewayAuthorizationException`, a cancelled call becomes
 `OperationCanceledException`, and every other status becomes a base
 `MxGatewayException`. `MxGatewayException.StatusCode` carries the originating
 gRPC `Grpc.Core.StatusCode` (non-null whenever the failure came from a gRPC
 status), so callers can distinguish a transient outage (`Unavailable`) from a
 permanent error (`InvalidArgument`, `NotFound`) without downcasting
 `InnerException`.
 ## CLI Usage
 The test CLI supports deterministic JSON output for automation:
 ```powershell
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- version --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- version --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- open-session --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- open-session --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- register --session-id <id> --client-name mxgw-dotnet-cli --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- register --session-id <id> --client-name mxgw-dotnet-cli --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- add-item --session-id <id> --server-handle 1 --item Area001.Pump001.Speed --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- add-item --session-id <id> --server-handle 1 --item Area001.Pump001.Speed --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- advise --session-id <id> --server-handle 1 --item-handle 1 --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- advise --session-id <id> --server-handle 1 --item-handle 1 --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- write --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- write --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- write2 --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --timestamp 2026-01-01T00:00:00Z --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- write2 --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --timestamp 2026-01-01T00:00:00Z --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- stream-events --session-id <id> --max-events 1 --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- stream-events --session-id <id> --max-events 1 --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- stream-alarms --filter-prefix Area001 --max-events 1 --json
 dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- acknowledge-alarm --reference "\\Galaxy\Area001.Pump001.PumpFault" --comment "ack from cli" --operator operator1 --json
 dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- smoke --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json
 ```
 `smoke` opens a session, registers a client, adds one item, advises it,
 optionally writes a value when `--type` and `--value` are supplied, reads a
 bounded event stream, and closes the session in a `finally` block. CLI error
-output redacts the effective API key, whether it was supplied through
+output redacts API keys supplied through `--api-key`.
 `--api-key` or resolved from the `--api-key-env` environment variable.
 ## Galaxy Repository Browse
@@ -234,11 +191,59 @@ IReadOnlyList<GalaxyObject> pumps = await repository.DiscoverHierarchyAsync(
 The CLI exposes the same operations:
 ```powershell
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-test-connection --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-test-connection --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-last-deploy --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-last-deploy --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-discover --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
+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.
 ### Watching deploy events
 `WatchDeployEventsAsync` opens the `WatchDeployEvents` server-streaming RPC. The
@@ -271,17 +276,28 @@ await foreach (DeployEvent evt in repository.WatchDeployEventsAsync(
 The CLI counterpart streams events until Ctrl+C (or `--max-events`):
 ```powershell
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --last-seen-deploy-time 2026-04-28T14:30:00Z --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --last-seen-deploy-time 2026-04-28T14:30:00Z --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --max-events 5 --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --max-events 5 --json
 ```
 Use TLS options for a secured gateway:
 ```powershell
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint https://mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json
+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:
@@ -291,9 +307,32 @@ $env:MXGATEWAY_INTEGRATION = '1'
 $env:MXGATEWAY_ENDPOINT = 'http://localhost:5000'
 $env:MXGATEWAY_API_KEY = '<gateway-api-key>'
 $env:MXGATEWAY_TEST_ITEM = 'Area001.Pump001.Speed'
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint $env:MXGATEWAY_ENDPOINT --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+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.0
 ````
 The `ZB.MOM.WW.MxGateway.Contracts` package is pulled in transitively.
 ## Related Documentation
 - [Client Packaging](../../docs/ClientPackaging.md)
@@ -1,6 +1,6 @@
 using System.Globalization;
-namespace MxGateway.Client.Cli;
+namespace ZB.MOM.WW.MxGateway.Client.Cli;
 /// <summary>Parses command-line arguments into flags and named values.</summary>
 internal sealed class CliArguments
@@ -1,14 +1,8 @@
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
-namespace MxGateway.Client.Cli;
+namespace ZB.MOM.WW.MxGateway.Client.Cli;
 /// <summary>
 /// Minimal transport surface the CLI talks to. Exposes only the gateway and
 /// Galaxy Repository RPCs the CLI needs so tests can substitute an in-process
 /// fake without standing up a real gRPC channel. The production binding is a
 /// thin adapter over <see cref="MxGatewayClient"/> and <see cref="GalaxyRepositoryClient"/>.
 /// </summary>
 public interface IMxGatewayCliClient : IAsyncDisposable
 {
    /// <summary>
@@ -1,8 +1,8 @@
-using MxGateway.Client;
+using ZB.MOM.WW.MxGateway.Client;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
-namespace MxGateway.Client.Cli;
+namespace ZB.MOM.WW.MxGateway.Client.Cli;
 internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
 {
@@ -1,4 +1,4 @@
-namespace MxGateway.Client.Cli;
+namespace ZB.MOM.WW.MxGateway.Client.Cli;
 /// <summary>Utility to redact API keys from error messages for safe output.</summary>
 internal static class MxGatewayCliSecretRedactor
@@ -1,11 +1,11 @@
 using System.Globalization;
 using System.Text.Json;
 using Google.Protobuf;
-using MxGateway.Client;
+using ZB.MOM.WW.MxGateway.Client;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
-namespace MxGateway.Client.Cli;
+namespace ZB.MOM.WW.MxGateway.Client.Cli;
 /// <summary>Command-line interface for the MXAccess Gateway client, supporting session and command operations.</summary>
 public static class MxGatewayClientCli
@@ -16,6 +16,8 @@ public static class MxGatewayClientCli
    private static readonly JsonSerializerOptions JsonOptions = new(JsonSerializerDefaults.Web);
    private const string BatchEndOfRecord = "__MXGW_BATCH_EOR__";
    /// <summary>Runs the CLI synchronously with the given arguments, writing output and errors.</summary>
    /// <param name="args">Command-line arguments (command name followed by options).</param>
    /// <param name="standardOutput">TextWriter for command output.</param>
@@ -55,8 +57,6 @@ public static class MxGatewayClientCli
            standardInput ?? Console.In);
    }
    private const string BatchEndOfRecord = "__MXGW_BATCH_EOR__";
    private static async Task<int> RunCoreAsync(
        string[] args,
        TextWriter standardOutput,
@@ -126,8 +126,6 @@ public static class MxGatewayClientCli
                    .ConfigureAwait(false),
                "bench-read-bulk" => await BenchReadBulkAsync(arguments, client, standardOutput, cancellation.Token)
                    .ConfigureAwait(false),
                "bench-stream-events" => await BenchStreamEventsAsync(arguments, client, standardOutput, cancellation.Token)
                    .ConfigureAwait(false),
                "stream-events" => await StreamEventsAsync(arguments, client, standardOutput, cancellation.Token)
                    .ConfigureAwait(false),
                "stream-alarms" => await StreamAlarmsAsync(arguments, client, standardOutput, cancellation.Token)
@@ -153,10 +151,7 @@ public static class MxGatewayClientCli
        }
        catch (Exception exception) when (exception is not OperationCanceledException)
        {
-            // Redact the effective API key — whether it came from --api-key or from
+            string? apiKey = arguments.GetOptional("api-key");
            // the (documented default) --api-key-env environment variable — so a
            // transport error message that echoes the bearer token is never printed.
            string? apiKey = TryResolveApiKey(arguments);
            string message = MxGatewayCliSecretRedactor.Redact(exception.Message, apiKey);
            if (forceJsonErrors || arguments.HasFlag("json"))
@@ -174,88 +169,6 @@ public static class MxGatewayClientCli
        }
    }
    private static IMxGatewayCliClient CreateDefaultClient(MxGatewayClientOptions options)
    {
        return new MxGatewayCliClientAdapter(MxGatewayClient.Create(options));
    }
    private static MxGatewayClientOptions CreateOptions(CliArguments arguments)
    {
        string endpoint = arguments.GetOptional("endpoint")
            ?? Environment.GetEnvironmentVariable("MXGATEWAY_ENDPOINT")
            ?? "http://localhost:5000";
        string apiKey = ResolveApiKey(arguments);
        return new MxGatewayClientOptions
        {
            Endpoint = new Uri(endpoint, UriKind.Absolute),
            ApiKey = apiKey,
            UseTls = arguments.HasFlag("tls")
                || endpoint.StartsWith("https://", StringComparison.OrdinalIgnoreCase),
            DefaultCallTimeout = arguments.GetDuration("timeout", TimeSpan.FromSeconds(30)),
            ConnectTimeout = arguments.GetDuration("connect-timeout", TimeSpan.FromSeconds(10)),
            CaCertificatePath = arguments.GetOptional("ca-file"),
            ServerNameOverride = arguments.GetOptional("server-name"),
        };
    }
    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
    /// environment variable named by <c>--api-key-env</c> (default
    /// <c>MXGATEWAY_API_KEY</c>). Returns <see langword="null"/> when no key is
    /// configured; used for redaction where a missing key must not throw.
    /// </summary>
    private static string? TryResolveApiKey(CliArguments arguments)
    {
        string? apiKey = arguments.GetOptional("api-key");
        if (!string.IsNullOrWhiteSpace(apiKey))
        {
            return apiKey;
        }
        string apiKeyEnvironmentName = arguments.GetOptional("api-key-env")
            ?? "MXGATEWAY_API_KEY";
        return Environment.GetEnvironmentVariable(apiKeyEnvironmentName);
    }
    private static CancellationTokenSource CreateCancellation(CliArguments arguments, string command)
    {
        var cancellation = new CancellationTokenSource();
        // Long-running streaming / bench commands run until they finish (or Ctrl+C)
        // by default; a caller-supplied --timeout still applies if present. The
        // bench commands default to --duration-seconds=30 --warmup-seconds=3 plus
        // a per-session stagger, which already exceeds the default 30 s wall-clock
        // budget, so applying that budget would cancel them mid-window and emit a
        // zero-throughput JSON payload (see Client.Dotnet-015).
        bool isLongRunning = command is "galaxy-watch" or "bench-read-bulk" or "bench-stream-events";
        string? rawTimeout = arguments.GetOptional("timeout");
        if (isLongRunning && string.IsNullOrWhiteSpace(rawTimeout))
        {
            return cancellation;
        }
        TimeSpan timeout = arguments.GetDuration("timeout", TimeSpan.FromSeconds(30));
        cancellation.CancelAfter(timeout);
        return cancellation;
    }
    /// <summary>
    ///     Runs the CLI in batch mode: reads one command line at a time from
    ///     <paramref name="standardInput"/>, dispatches it through the normal
@@ -303,9 +216,13 @@ public static class MxGatewayClientCli
                        forceJsonErrors: true)
                    .ConfigureAwait(false);
            }
-            catch (Exception exception) when (exception is not OperationCanceledException)
+            catch (Exception exception)
            {
                // Unexpected exception that escaped RunCoreAsync (shouldn't happen, but be safe).
                // OperationCanceledException from long-running streaming commands
                // (e.g. galaxy-watch hit by --timeout) is caught here too — the
                // batch process must continue with the next command rather than
                // unwinding.
                commandError.WriteLine(JsonSerializer.Serialize(
                    new { error = exception.Message, type = exception.GetType().Name },
                    JsonOptions));
@@ -332,6 +249,70 @@ public static class MxGatewayClientCli
        }
    }
    private static IMxGatewayCliClient CreateDefaultClient(MxGatewayClientOptions options)
    {
        return new MxGatewayCliClientAdapter(MxGatewayClient.Create(options));
    }
    private static MxGatewayClientOptions CreateOptions(CliArguments arguments)
    {
        string endpoint = arguments.GetOptional("endpoint")
            ?? Environment.GetEnvironmentVariable("MXGATEWAY_ENDPOINT")
            ?? "http://localhost:5000";
        string apiKey = ResolveApiKey(arguments);
        return new MxGatewayClientOptions
        {
            Endpoint = new Uri(endpoint, UriKind.Absolute),
            ApiKey = apiKey,
            UseTls = arguments.HasFlag("tls")
                || endpoint.StartsWith("https://", StringComparison.OrdinalIgnoreCase),
            DefaultCallTimeout = arguments.GetDuration("timeout", TimeSpan.FromSeconds(30)),
            ConnectTimeout = arguments.GetDuration("connect-timeout", TimeSpan.FromSeconds(10)),
            CaCertificatePath = arguments.GetOptional("ca-file"),
            ServerNameOverride = arguments.GetOptional("server-name"),
        };
    }
    private static string ResolveApiKey(CliArguments arguments)
    {
        string? apiKey = arguments.GetOptional("api-key");
        if (!string.IsNullOrWhiteSpace(apiKey))
        {
            return apiKey;
        }
        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}.");
    }
    private static CancellationTokenSource CreateCancellation(CliArguments arguments, string command)
    {
        var cancellation = new CancellationTokenSource();
        // Long-running streaming commands run until Ctrl+C / cancellation by default;
        // a caller-supplied --timeout still applies if present.
        bool isLongRunning = command is "galaxy-watch";
        string? rawTimeout = arguments.GetOptional("timeout");
        if (isLongRunning && string.IsNullOrWhiteSpace(rawTimeout))
        {
            return cancellation;
        }
        TimeSpan timeout = arguments.GetDuration("timeout", TimeSpan.FromSeconds(30));
        cancellation.CancelAfter(timeout);
        return cancellation;
    }
    private static Task<int> OpenSessionAsync(
        CliArguments arguments,
        IMxGatewayCliClient client,
@@ -506,7 +487,7 @@ public static class MxGatewayClientCli
        ReadBulkCommand command = new()
        {
            ServerHandle = arguments.GetInt32("server-handle"),
-            TimeoutMs = (uint)arguments.GetInt32("timeout-ms", 0),
+            TimeoutMs = ParseTimeoutMs(arguments, defaultValue: 0),
        };
        command.TagAddresses.Add(ParseStringList(arguments.GetRequired("items")));
@@ -682,6 +663,78 @@ public static class MxGatewayClientCli
            cancellationToken);
    }
    /// <summary>
    ///     Parses the bulk-write CLI's <c>--values</c> list. All entries share
    ///     the single <c>--type</c> argument; the comma-separated values are
    ///     each parsed via <see cref="ParseValue(string, string)"/> on a per-entry basis.
    ///     This keeps the CLI simple for e2e use (one type, N values) — callers
    ///     that need heterogeneous types per entry should drive the library
    ///     directly.
    /// </summary>
    private static IReadOnlyList<MxValue> ParseValuesList(CliArguments arguments)
    {
        string type = arguments.GetRequired("type");
        string[] values = ParseStringList(arguments.GetRequired("values")).ToArray();
        MxValue[] result = new MxValue[values.Length];
        for (int i = 0; i < values.Length; i++)
        {
            result[i] = ParseValue(type, values[i]);
        }
        return result;
    }
    private static void EnsureSameLength(int handles, int values)
    {
        if (handles != values)
        {
            throw new ArgumentException(
                $"Bulk write requires the same number of --item-handles ({handles}) and --values ({values}).");
        }
    }
    /// <summary>
    ///     Parses the optional <c>--timeout-ms</c> argument as a non-negative
    ///     unsigned millisecond count. Mirrors the SDK-side <c>(uint)Math.Min</c>
    ///     guard on <c>MxGatewaySession.ReadBulkAsync</c>: a negative value
    ///     (e.g. <c>-1</c>, an easy copy-paste mistake for "unbounded") is
    ///     rejected loudly rather than silently wrapped to <c>~49.7 days</c>,
    ///     which would park one worker thread per pending tag for hours.
    ///     Resolves Client.Dotnet-021.
    /// </summary>
    private static uint ParseTimeoutMs(CliArguments arguments, int defaultValue)
    {
        int raw = arguments.GetInt32("timeout-ms", defaultValue);
        if (raw < 0)
        {
            throw new ArgumentException(
                "--timeout-ms must be a non-negative integer (use 0 for the gateway default).");
        }
        return (uint)raw;
    }
    /// <summary>
    ///     Extracts the <c>ServerHandle</c> from a Register reply, throwing a
    ///     descriptive <see cref="MxGatewayException"/> when the typed
    ///     <c>Register</c> payload is absent on an otherwise-successful reply.
    ///     The typed sub-message is the contract for the Register command, so
    ///     its absence must not silently fall through to
    ///     <c>ReturnValue.Int32Value</c> (which would be <c>0</c> for an empty
    ///     reply, driving the rest of the bench against an invalid handle).
    ///     Resolves Client.Dotnet-019.
    /// </summary>
    private static int RequireRegisterServerHandle(MxCommandReply reply, string sessionId)
    {
        if (reply.Register is null)
        {
            throw new MxGatewayException(
                $"Gateway reply for Register on session '{sessionId}' (correlation '{reply.CorrelationId}') "
                + "succeeded but is missing the typed 'register' payload required to read ServerHandle.");
        }
        return reply.Register.ServerHandle;
    }
    /// <summary>
    ///     Cross-language stress benchmark for ReadBulk. Opens its own session,
    ///     subscribes to N tags so the worker's MxAccessValueCache populates from
@@ -702,7 +755,7 @@ public static class MxGatewayClientCli
        int tagStart = arguments.GetInt32("tag-start", 1);
        string tagPrefix = arguments.GetOptional("tag-prefix") ?? "TestMachine_";
        string tagAttribute = arguments.GetOptional("tag-attribute") ?? "TestChangingInt";
-        uint timeoutMs = (uint)arguments.GetInt32("timeout-ms", 1500);
+        uint timeoutMs = ParseTimeoutMs(arguments, defaultValue: 1500);
        string clientName = arguments.GetOptional("client-name") ?? "mxgw-dotnet-bench";
        string[] tags = new string[bulkSize];
@@ -732,7 +785,7 @@ public static class MxGatewayClientCli
                    }),
                    cancellationToken)
                .ConfigureAwait(false);
-            int serverHandle = RequireRegisterServerHandle(registerReply);
+            int serverHandle = RequireRegisterServerHandle(registerReply, sessionId);
            SubscribeBulkCommand subscribe = new() { ServerHandle = serverHandle };
            subscribe.TagAddresses.Add(tags);
@@ -791,8 +844,13 @@ public static class MxGatewayClientCli
                        .ConfigureAwait(false);
                    sw.Stop();
                }
-                catch
+                catch (Exception ex) when (ex is not OperationCanceledException)
                {
                    // Client.Dotnet-020: never swallow OperationCanceledException
                    // here. A bare `catch` would let Ctrl+C / parent CTS /
                    // wall-clock timeouts keep spinning until --duration-seconds
                    // elapsed, burning CPU and skewing the p99/max latency numbers
                    // with hundreds of immediate-OCE iterations.
                    sw.Stop();
                    failedCalls++;
                    latencyMillis.Add(sw.Elapsed.TotalMilliseconds);
@@ -886,295 +944,6 @@ public static class MxGatewayClientCli
        }
    }
    /// <summary>
    ///     Single-client event-rate stress benchmark. Opens its own session,
    ///     subscribes to <c>--bulk-size</c> tags spanning the dev galaxy's
    ///     TestMachine_NNN.* set, then drains the gateway's StreamEvents
    ///     server-stream as fast as it can for <c>--duration-seconds</c>.
    ///     Tracks events received per second, end-to-end latency from
    ///     <c>event.worker_timestamp</c> to client receive time, and any
    ///     worker faults emitted by the gateway over the same window.
    ///     <para>
    ///     The companion <c>--all-attributes</c> flag (default <c>true</c>)
    ///     subscribes to all six TestMachine attributes per machine number
    ///     so the bench can drive event volume past one-attribute-per-machine
    ///     when the dev galaxy's TestChangingInt is the only churning tag.
    ///     </para>
    /// </summary>
    private static async Task<int> BenchStreamEventsAsync(
        CliArguments arguments,
        IMxGatewayCliClient client,
        TextWriter output,
        CancellationToken cancellationToken)
    {
        int durationSeconds = arguments.GetInt32("duration-seconds", 30);
        int warmupSeconds = arguments.GetInt32("warmup-seconds", 3);
        int bulkSize = arguments.GetInt32("bulk-size", 60);
        int tagStart = arguments.GetInt32("tag-start", 1);
        int sessionCount = arguments.GetInt32("session-count", 1);
        // Concurrent OpenSession calls all the way up the stack force the
        // gateway to spawn N x86 workers simultaneously; that hits the
        // 30-second worker startup timeout around 6-8 concurrent opens on
        // a dev rig. The stagger spreads the opens out so per-session
        // OpenSession+Register completes inside that budget before the
        // next session starts spawning. The steady-state event window
        // begins only once all sessions are open and subscribed.
        int sessionStartStaggerMs = arguments.GetInt32("session-start-stagger-ms", sessionCount > 1 ? 750 : 0);
        string tagPrefix = arguments.GetOptional("tag-prefix") ?? "TestMachine_";
        bool allAttributes = !arguments.HasFlag("single-attribute");
        string singleAttribute = arguments.GetOptional("tag-attribute") ?? "TestChangingInt";
        string clientName = arguments.GetOptional("client-name") ?? "mxgw-dotnet-bench-events";
        if (sessionCount < 1)
        {
            throw new ArgumentException("--session-count must be >= 1.");
        }
        // Build the tag set. With --all-attributes (default) we rotate through
        // all six TestMachine attributes to drive more event volume from a
        // smaller machine range; with --single-attribute we use the same
        // attribute on contiguous machine numbers (the original bench-read-
        // bulk shape).
        string[] attributes = allAttributes
            ? new[] { "TestChangingInt", "ProtectedValue", "TestBoolArray[]", "TestIntArray[]", "TestDateTimeArray[]", "TestStringArray[]" }
            : new[] { singleAttribute };
        List<string> tags = new(capacity: bulkSize);
        for (int i = 0; i < bulkSize; i++)
        {
            int machineNumber = tagStart + (i / attributes.Length);
            string attribute = attributes[i % attributes.Length];
            tags.Add($"{tagPrefix}{machineNumber:D3}.{attribute}");
        }
        long warmupEvents = 0;
        long steadyEvents = 0;
        long steadyDataChangeEvents = 0;
        List<double> endToEndLatencyMs = new(capacity: 262_144);
        object latencyLock = new();
        DateTime? firstSteadyEventUtc = null;
        DateTime? lastSteadyEventUtc = null;
        int totalSubscribeFailures = 0;
        int totalSubscribedTagCount = 0;
        int totalDrainedFaultCount = 0;
        DateTime warmupStart = default;
        DateTime warmupEnd = default;
        DateTime steadyEnd = default;
        // Phase 1: open + subscribe each session sequentially with a stagger,
        // so worker spawn-up doesn't exceed the gateway's per-session startup
        // timeout. Each session stashes its (sessionId, serverHandle, itemHandles)
        // for phase 2.
        var openedSessions = new List<(string SessionId, int ServerHandle, int[] ItemHandles, string ClientName)>(sessionCount);
        for (int sessionIndex = 0; sessionIndex < sessionCount; sessionIndex++)
        {
            if (sessionIndex > 0 && sessionStartStaggerMs > 0)
            {
                await Task.Delay(sessionStartStaggerMs, cancellationToken).ConfigureAwait(false);
            }
            string thisClientName = sessionCount == 1
                ? clientName
                : $"{clientName}-{sessionIndex:D2}";
            OpenSessionReply openReply = await client.OpenSessionAsync(
                    new OpenSessionRequest { ClientSessionName = thisClientName, ClientCorrelationId = CreateCorrelationId() },
                    cancellationToken)
                .ConfigureAwait(false);
            string sessionId = openReply.SessionId;
            MxCommandReply registerReply = await InvokeAndEnsureAsync(
                    client,
                    CreateCommandRequest(sessionId, new MxCommand
                    {
                        Kind = MxCommandKind.Register,
                        Register = new RegisterCommand { ClientName = thisClientName },
                    }),
                    cancellationToken)
                .ConfigureAwait(false);
            int serverHandle = RequireRegisterServerHandle(registerReply);
            SubscribeBulkCommand subscribe = new() { ServerHandle = serverHandle };
            subscribe.TagAddresses.Add(tags);
            MxCommandReply subscribeReply = await InvokeAndEnsureAsync(
                    client,
                    CreateCommandRequest(sessionId, new MxCommand
                    {
                        Kind = MxCommandKind.SubscribeBulk,
                        SubscribeBulk = subscribe,
                    }),
                    cancellationToken)
                .ConfigureAwait(false);
            SubscribeResult[] subscribeResults = subscribeReply.SubscribeBulk?.Results.ToArray() ?? [];
            int[] itemHandles = subscribeResults.Where(r => r.WasSuccessful).Select(r => r.ItemHandle).ToArray();
            totalSubscribedTagCount += itemHandles.Length;
            totalSubscribeFailures += subscribeResults.Count(r => !r.WasSuccessful);
            openedSessions.Add((sessionId, serverHandle, itemHandles, thisClientName));
        }
        // Phase 2: now every session is open + advised. Start the measurement
        // window and run each session's StreamEvents reader in parallel.
        warmupStart = DateTime.UtcNow;
        warmupEnd = warmupStart + TimeSpan.FromSeconds(warmupSeconds);
        steadyEnd = warmupEnd + TimeSpan.FromSeconds(durationSeconds);
        async Task RunStreamAsync((string SessionId, int ServerHandle, int[] ItemHandles, string ClientName) ctx)
        {
            using CancellationTokenSource streamCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
            Task streamTask = Task.Run(async () =>
            {
                StreamEventsRequest streamRequest = new() { SessionId = ctx.SessionId };
                await foreach (MxEvent mxEvent in client.StreamEventsAsync(streamRequest, streamCts.Token)
                    .ConfigureAwait(false))
                {
                    DateTime nowUtc = DateTime.UtcNow;
                    if (nowUtc >= steadyEnd)
                    {
                        break;
                    }
                    if (nowUtc < warmupEnd)
                    {
                        Interlocked.Increment(ref warmupEvents);
                        continue;
                    }
                    // Guarded by latencyLock so parallel sessions can't tear a 64-bit
                    // DateTime? read or stomp an already-set firstSteadyEventUtc with
                    // a later timestamp from a slower-to-start session. The lock is
                    // already held by the latency append a few lines below, so the
                    // extra cost is one uncontended lock acquisition per event.
                    lock (latencyLock)
                    {
                        firstSteadyEventUtc ??= nowUtc;
                        lastSteadyEventUtc = nowUtc;
                    }
                    Interlocked.Increment(ref steadyEvents);
                    if (mxEvent.Family == MxEventFamily.OnDataChange)
                    {
                        Interlocked.Increment(ref steadyDataChangeEvents);
                    }
                    if (mxEvent.WorkerTimestamp is { } workerStamp)
                    {
                        double latency = (nowUtc - workerStamp.ToDateTime()).TotalMilliseconds;
                        if (latency >= 0)
                        {
                            lock (latencyLock) { endToEndLatencyMs.Add(latency); }
                        }
                    }
                }
            }, streamCts.Token);
            // The inner streamTask MUST be observed on every path — including when
            // the outer cancellationToken cancels during the Task.Delay below — or
            // its fault surfaces as a TaskScheduler.UnobservedTaskException after
            // GC. Use try/finally so the cancel + await pair always runs (see
            // Client.Dotnet-016). RpcException(Cancelled) never reaches here in
            // production because GrpcMxGatewayClientTransport.StreamEventsAsync
            // routes through RpcExceptionMapper.Map, which returns OCE for
            // StatusCode.Cancelled.
            try
            {
                await Task.Delay(steadyEnd - warmupStart, cancellationToken).ConfigureAwait(false);
            }
            finally
            {
                streamCts.Cancel();
                try { await streamTask.ConfigureAwait(false); }
                catch (OperationCanceledException) { }
                catch (MxGatewayException) { }
            }
            try
            {
                MxCommandReply drainReply = await client.InvokeAsync(
                        CreateCommandRequest(ctx.SessionId, new MxCommand
                        {
                            Kind = MxCommandKind.DrainEvents,
                            DrainEvents = new DrainEventsCommand { MaxEvents = 16 },
                        }),
                        cancellationToken)
                    .ConfigureAwait(false);
                Interlocked.Add(ref totalDrainedFaultCount, drainReply.DrainEvents?.Events.Count ?? 0);
            }
            catch { /* fault probe is best-effort */ }
            if (ctx.ItemHandles.Length > 0)
            {
                try
                {
                    UnsubscribeBulkCommand unsubscribe = new() { ServerHandle = ctx.ServerHandle };
                    unsubscribe.ItemHandles.Add(ctx.ItemHandles);
                    _ = await client.InvokeAsync(
                            CreateCommandRequest(ctx.SessionId, new MxCommand
                            {
                                Kind = MxCommandKind.UnsubscribeBulk,
                                UnsubscribeBulk = unsubscribe,
                            }),
                            cancellationToken)
                        .ConfigureAwait(false);
                }
                catch { /* best-effort */ }
            }
            try
            {
                await client.CloseSessionAsync(
                        new CloseSessionRequest { SessionId = ctx.SessionId, ClientCorrelationId = CreateCorrelationId() },
                        cancellationToken)
                    .ConfigureAwait(false);
            }
            catch { /* best-effort */ }
        }
        Task[] streamTasks = openedSessions.Select(RunStreamAsync).ToArray();
        await Task.WhenAll(streamTasks).ConfigureAwait(false);
        double steadyElapsedSeconds = (firstSteadyEventUtc.HasValue && lastSteadyEventUtc.HasValue)
            ? (lastSteadyEventUtc.Value - firstSteadyEventUtc.Value).TotalSeconds
            : 0;
        double eventsPerSecond = steadyElapsedSeconds > 0 ? steadyEvents / steadyElapsedSeconds : 0;
        double dataChangeEventsPerSecond = steadyElapsedSeconds > 0
            ? steadyDataChangeEvents / steadyElapsedSeconds
            : 0;
        double[] latencySnapshot;
        lock (latencyLock) { latencySnapshot = endToEndLatencyMs.ToArray(); }
        object stats = new
        {
            language = "dotnet",
            command = "bench-stream-events",
            endpoint = arguments.GetOptional("endpoint") ?? "(default)",
            clientName,
            sessionCount,
            bulkSize,
            durationSeconds,
            warmupSeconds,
            allAttributes,
            steadyElapsedSeconds = Math.Round(steadyElapsedSeconds, 3),
            subscribedTagCount = totalSubscribedTagCount,
            subscribeFailures = totalSubscribeFailures,
            warmupEvents,
            steadyEvents,
            steadyDataChangeEvents,
            eventsPerSecond = Math.Round(eventsPerSecond, 2),
            dataChangeEventsPerSecond = Math.Round(dataChangeEventsPerSecond, 2),
            drainedFaultCount = totalDrainedFaultCount,
            endToEndLatencyMs = new
            {
                p50 = Percentile(latencySnapshot, 0.50),
                p95 = Percentile(latencySnapshot, 0.95),
                p99 = Percentile(latencySnapshot, 0.99),
                max = latencySnapshot.Length > 0 ? Math.Round(latencySnapshot.Max(), 3) : 0,
                mean = latencySnapshot.Length > 0 ? Math.Round(latencySnapshot.Average(), 3) : 0,
                sampleCount = latencySnapshot.Length,
            },
        };
        output.WriteLine(JsonSerializer.Serialize(stats, JsonOptions));
        return 0;
    }
    /// <summary>
    /// Computes the requested percentile from an unsorted latency sample using
    /// nearest-rank with linear interpolation. Rounds to 3 decimal places to
@@ -1202,35 +971,6 @@ public static class MxGatewayClientCli
        return Math.Round(value, 3);
    }
    /// <summary>
    ///     Parses the bulk-write CLI's <c>--values</c> list. All entries share
    ///     the single <c>--type</c> argument; the comma-separated values are
    ///     each parsed via <see cref="ParseValue"/> on a per-entry basis. This
    ///     keeps the CLI simple for e2e use (one type, N values) — callers
    ///     that need heterogeneous types per entry should drive the library
    ///     directly.
    /// </summary>
    private static IReadOnlyList<MxValue> ParseValuesList(CliArguments arguments)
    {
        string type = arguments.GetRequired("type");
        string[] values = ParseStringList(arguments.GetRequired("values")).ToArray();
        MxValue[] result = new MxValue[values.Length];
        for (int i = 0; i < values.Length; i++)
        {
            result[i] = ParseValue(type, values[i]);
        }
        return result;
    }
    private static void EnsureSameLength(int handles, int values)
    {
        if (handles != values)
        {
            throw new ArgumentException(
                $"Bulk write requires the same number of --item-handles ({handles}) and --values ({values}).");
        }
    }
    private static Task<int> WriteAsync(
        CliArguments arguments,
        IMxGatewayCliClient client,
@@ -1337,14 +1077,8 @@ public static class MxGatewayClientCli
        }
        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
        {
-            // Client.Dotnet-017: the supplied cancellation token covers both the
+            // Client.Dotnet-017: graceful end-of-window completion mode for a
-            // user's --timeout wall-clock budget (via CreateCancellation's
+            // finite-window event collector. Emit aggregate JSON below and exit 0.
            // CancelAfter) and external Ctrl+C / parent CTS cancellation. All
            // three are graceful completion modes for a finite-window event
            // collector: emit the events that arrived before the window closed
            // and exit 0. The events list is well-formed at this point; the
            // aggregate JSON below still runs. This matches how the Go, Rust,
            // Python, and Java CLIs treat their equivalent timeouts.
        }
        if (json && !jsonLines)
@@ -1506,7 +1240,7 @@ public static class MxGatewayClientCli
                        Kind = MxCommandKind.Register,
                        Register = new RegisterCommand { ClientName = arguments.GetOptional("client-name") ?? "mxgw-dotnet-smoke" },
                    },
-                    RequireRegisterServerHandle,
+                    reply => reply.Register?.ServerHandle ?? reply.ReturnValue.Int32Value,
                    commandReplies,
                    cancellationToken)
                .ConfigureAwait(false);
@@ -1524,7 +1258,7 @@ public static class MxGatewayClientCli
                            ItemDefinition = arguments.GetRequired("item"),
                        },
                    },
-                    RequireAddItemItemHandle,
+                    reply => reply.AddItem?.ItemHandle ?? reply.ReturnValue.Int32Value,
                    commandReplies,
                    cancellationToken)
                .ConfigureAwait(false);
@@ -1656,41 +1390,6 @@ public static class MxGatewayClientCli
        return reply;
    }
    /// <summary>
    /// Returns the server handle from a successful <c>register</c> reply, or throws
    /// <see cref="MxGatewayException"/> when the typed <see cref="MxCommandReply.Register"/>
    /// payload is absent. Mirrors the SDK-level <see cref="MxGatewaySession.RegisterAsync"/>
    /// contract: a successful reply without the typed payload is a gateway protocol
    /// error, not a license to fall through to <c>ReturnValue.Int32Value</c> (which is 0
    /// when the reply carries no return value).
    /// </summary>
    private static int RequireRegisterServerHandle(MxCommandReply reply)
    {
        return reply.Register?.ServerHandle
            ?? throw CreateMissingPayloadException(reply, "register");
    }
    /// <summary>
    /// Returns the item handle from a successful <c>add_item</c> reply, or throws
    /// <see cref="MxGatewayException"/> when the typed <see cref="MxCommandReply.AddItem"/>
    /// payload is absent. See <see cref="RequireRegisterServerHandle"/> for the rationale.
    /// </summary>
    private static int RequireAddItemItemHandle(MxCommandReply reply)
    {
        return reply.AddItem?.ItemHandle
            ?? throw CreateMissingPayloadException(reply, "add_item");
    }
    private static MxGatewayException CreateMissingPayloadException(
        MxCommandReply reply,
        string expectedPayload)
    {
        return new MxGatewayException(
            $"Gateway reply for command kind={reply.Kind} reported success but is missing "
            + $"the required '{expectedPayload}' payload; cannot resolve a handle. "
            + $"session={reply.SessionId}; correlation={reply.CorrelationId}");
    }
    private static MxCommandRequest CreateCommandRequest(
        string sessionId,
        MxCommand command)
@@ -1787,12 +1486,12 @@ public static class MxGatewayClientCli
        return ParseValue(arguments.GetRequired("type"), arguments.GetRequired("value"));
    }
-    private static MxValue ParseValue(string typeName, string value)
+    private static MxValue ParseValue(string type, string value)
    {
-        string type = typeName.ToLowerInvariant();
+        string normalisedType = type.ToLowerInvariant();
        string[] values = value.Split(',', StringSplitOptions.TrimEntries);
-        return type switch
+        return normalisedType switch
        {
            "bool" or "boolean" => bool.Parse(value).ToMxValue(),
            "bool-array" or "boolean-array" => values.Select(bool.Parse).ToArray().ToMxValue(),
@@ -1811,7 +1510,7 @@ public static class MxGatewayClientCli
                .Select(item => DateTimeOffset.Parse(item, CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal))
                .ToArray()
                .ToMxValue(),
-            _ => throw new ArgumentException($"Unsupported MX value type '{type}'."),
+            _ => throw new ArgumentException($"Unsupported MX value type '{normalisedType}'."),
        };
    }
@@ -2028,7 +1727,6 @@ public static class MxGatewayClientCli
            or "write-secured-bulk"
            or "write-secured2-bulk"
            or "bench-read-bulk"
            or "bench-stream-events"
            or "stream-events"
            or "stream-alarms"
            or "acknowledge-alarm"
@@ -2082,13 +1780,14 @@ public static class MxGatewayClientCli
        writer.WriteLine("mxgw-dotnet register --session-id <id> --client-name <name> [--json]");
        writer.WriteLine("mxgw-dotnet add-item --session-id <id> --server-handle <n> --item <ref> [--json]");
        writer.WriteLine("mxgw-dotnet advise --session-id <id> --server-handle <n> --item-handle <n> [--json]");
        writer.WriteLine("mxgw-dotnet subscribe-bulk --session-id <id> --server-handle <n> --items <ref,ref> [--json]");
        writer.WriteLine("mxgw-dotnet unsubscribe-bulk --session-id <id> --server-handle <n> --item-handles <n,n> [--json]");
        writer.WriteLine("mxgw-dotnet read-bulk --session-id <id> --server-handle <n> --items <ref,ref> [--timeout-ms <n>] [--json]");
        writer.WriteLine("mxgw-dotnet write-bulk --session-id <id> --server-handle <n> --item-handles <n,n> --type <type> --values <v,v> [--user-id <n>] [--json]");
        writer.WriteLine("mxgw-dotnet write2-bulk --session-id <id> --server-handle <n> --item-handles <n,n> --type <type> --values <v,v> [--timestamp <iso>] [--user-id <n>] [--json]");
        writer.WriteLine("mxgw-dotnet write-secured-bulk --session-id <id> --server-handle <n> --item-handles <n,n> --type <type> --values <v,v> --current-user-id <n> [--verifier-user-id <n>] [--json]");
-        writer.WriteLine("mxgw-dotnet write-secured2-bulk --session-id <id> --server-handle <n> --item-handles <n,n> --type <type> --values <v,v> [--timestamp <iso>] --current-user-id <n> [--verifier-user-id <n>] [--json]");
+        writer.WriteLine("mxgw-dotnet write-secured2-bulk --session-id <id> --server-handle <n> --item-handles <n,n> --type <type> --values <v,v> --current-user-id <n> [--verifier-user-id <n>] [--timestamp <iso>] [--json]");
-        writer.WriteLine("mxgw-dotnet subscribe-bulk --session-id <id> --server-handle <n> --items <ref,ref> [--json]");
+        writer.WriteLine("mxgw-dotnet bench-read-bulk [--duration-seconds <n>] [--warmup-seconds <n>] [--bulk-size <n>] [--tag-start <n>] [--tag-prefix <s>] [--tag-attribute <s>] [--timeout-ms <n>] [--client-name <name>]");
        writer.WriteLine("mxgw-dotnet unsubscribe-bulk --session-id <id> --server-handle <n> --item-handles <n,n> [--json]");
        writer.WriteLine("mxgw-dotnet stream-events --session-id <id> [--max-events <n>] [--json]");
        writer.WriteLine("mxgw-dotnet stream-alarms [--filter-prefix <ref>] [--max-events <n>] [--json] [--jsonl]");
        writer.WriteLine("mxgw-dotnet acknowledge-alarm --reference <ref> [--comment <text>] [--operator <user>] [--json]");
@@ -1,3 +1,3 @@
-using MxGateway.Client.Cli;
+using ZB.MOM.WW.MxGateway.Client.Cli;
 return await MxGatewayClientCli.RunAsync(args, Console.Out, Console.Error);
@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
-    <ProjectReference Include="..\MxGateway.Client\MxGateway.Client.csproj" />
+    <ProjectReference Include="..\ZB.MOM.WW.MxGateway.Client\ZB.MOM.WW.MxGateway.Client.csproj" />
  </ItemGroup>
  <PropertyGroup>
@@ -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);
    }
 }
@@ -1,7 +1,7 @@
 using Grpc.Core;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 /// <summary>
 /// Fake Galaxy Repository client transport for testing.
@@ -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,39 @@ 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>
    /// Records the request and either throws a queued exception or returns the configured reply.
    /// </summary>
    /// <param name="request">The BrowseChildrenRequest to process.</param>
    /// <param name="callOptions">Call options specifying RPC behavior.</param>
    public Task<BrowseChildrenReply> BrowseChildrenAsync(
        BrowseChildrenRequest request,
        CallOptions callOptions)
    {
        BrowseChildrenCalls.Add((request, callOptions));
        if (BrowseChildrenExceptions.TryDequeue(out Exception? exception))
        {
            return Task.FromException<BrowseChildrenReply>(exception);
        }
        return Task.FromResult(
            BrowseChildrenReplies.TryDequeue(out BrowseChildrenReply? reply)
                ? reply
                : BrowseChildrenReply);
    }
    /// <summary>
    /// Gets the list of WatchDeployEvents RPC calls made by the client.
    /// </summary>
@@ -1,7 +1,7 @@
 using Grpc.Core;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 /// <summary>
 /// Fake implementation of IMxGatewayClientTransport for testing.
@@ -46,6 +46,11 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
    /// </summary>
    public List<(AcknowledgeAlarmRequest Request, CallOptions CallOptions)> AcknowledgeAlarmCalls { get; } = [];
    /// <summary>
    /// Gets the list of captured QueryActiveAlarmsAsync calls.
    /// </summary>
    public List<(QueryActiveAlarmsRequest Request, CallOptions CallOptions)> QueryActiveAlarmsCalls { get; } = [];
    /// <summary>
    /// Gets the list of captured StreamAlarmsAsync calls.
    /// </summary>
@@ -58,6 +63,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
    private readonly Queue<AcknowledgeAlarmReply> _acknowledgeReplies = new();
    private readonly List<ActiveAlarmSnapshot> _activeAlarmSnapshots = [];
    private readonly List<AlarmFeedMessage> _alarmFeedMessages = [];
    /// <summary>
    /// Gets or sets the reply to return from OpenSessionAsync.
@@ -91,19 +97,6 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
    /// </summary>
    public Queue<Exception> CloseSessionExceptions { get; } = new();
    /// <summary>
    /// Gets or sets a value indicating whether thrown <see cref="RpcException"/>s are mapped
    /// to <see cref="MxGatewayException"/> the way the production gRPC transport does. Lets
    /// retry tests exercise the wrapped-exception predicate branch that runs in production.
    /// </summary>
    public bool MapTransportExceptions { get; set; }
    /// <summary>
    /// Gets or sets an optional hook awaited inside CloseSessionAsync after the call is
    /// recorded; lets tests pause a close mid-flight to observe concurrent dispose.
    /// </summary>
    public Func<Task>? CloseSessionHook { get; set; }
    /// <summary>
    /// Gets the queue of exceptions to throw from InvokeAsync.
    /// </summary>
@@ -121,7 +114,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
        OpenSessionCalls.Add((request, callOptions));
        if (OpenSessionExceptions.TryDequeue(out Exception? exception))
        {
-            throw Translate(exception, callOptions);
+            throw exception;
        }
        return Task.FromResult(OpenSessionReply);
@@ -132,23 +125,17 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
    /// </summary>
    /// <param name="request">The CloseSessionRequest to process.</param>
    /// <param name="callOptions">Call options specifying RPC behavior.</param>
-    public async Task<CloseSessionReply> CloseSessionAsync(
+    public Task<CloseSessionReply> CloseSessionAsync(
        CloseSessionRequest request,
        CallOptions callOptions)
    {
        CloseSessionCalls.Add((request, callOptions));
        if (CloseSessionHook is not null)
        {
            await CloseSessionHook().ConfigureAwait(false);
        }
        if (CloseSessionExceptions.TryDequeue(out Exception? exception))
        {
-            throw Translate(exception, callOptions);
+            throw exception;
        }
-        return CloseSessionReply;
+        return Task.FromResult(CloseSessionReply);
    }
    /// <summary>
@@ -163,7 +150,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
        InvokeCalls.Add((request, callOptions));
        if (InvokeExceptions.TryDequeue(out Exception? exception))
        {
-            throw Translate(exception, callOptions);
+            throw exception;
        }
        return Task.FromResult(_invokeReplies.Dequeue());
@@ -209,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)
@@ -216,7 +205,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
        AcknowledgeAlarmCalls.Add((request, callOptions));
        if (AcknowledgeAlarmExceptions.TryDequeue(out Exception? exception))
        {
-            throw Translate(exception, callOptions);
+            throw exception;
        }
        return Task.FromResult(_acknowledgeReplies.Count > 0
@@ -230,48 +219,61 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
    }
    /// <summary>
-    /// Records the call and yields each enqueued snapshot as an active-alarm
+    /// Records the query call and yields each enqueued snapshot.
    /// feed message, then a snapshot-complete sentinel.
    /// </summary>
-    public async IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
+    /// <param name="request">The query active alarms request.</param>
-        StreamAlarmsRequest request,
+    /// <param name="callOptions">Call options specifying RPC behavior.</param>
    public async IAsyncEnumerable<ActiveAlarmSnapshot> QueryActiveAlarmsAsync(
        QueryActiveAlarmsRequest request,
        CallOptions callOptions)
    {
-        StreamAlarmsCalls.Add((request, callOptions));
+        QueryActiveAlarmsCalls.Add((request, callOptions));
        foreach (ActiveAlarmSnapshot snapshot in _activeAlarmSnapshots)
        {
            callOptions.CancellationToken.ThrowIfCancellationRequested();
            await Task.Yield();
-            yield return new AlarmFeedMessage { ActiveAlarm = snapshot };
+            yield return snapshot;
        }
        yield return new AlarmFeedMessage { SnapshotComplete = true };
    }
    /// <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 yielded from StreamAlarmsAsync as an active-alarm message.</summary>
+    /// <summary>Enqueues a snapshot to be yielded from QueryActiveAlarmsAsync.</summary>
    /// <param name="snapshot">The snapshot to enqueue.</param>
    public void AddActiveAlarmSnapshot(ActiveAlarmSnapshot snapshot)
    {
        _activeAlarmSnapshots.Add(snapshot);
    }
    /// <summary>
-    /// Maps a queued exception the way the production gRPC transport does when
+    /// Records the stream-alarms call and yields each enqueued feed message.
    /// <see cref="MapTransportExceptions"/> is set; otherwise returns it unchanged.
    /// </summary>
-    private Exception Translate(Exception exception, CallOptions callOptions)
+    /// <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)
    {
-        if (MapTransportExceptions && exception is RpcException rpcException)
+        StreamAlarmsCalls.Add((request, callOptions));
        {
            return RpcExceptionMapper.Map(rpcException, callOptions.CancellationToken);
        }
-        return exception;
+        foreach (AlarmFeedMessage message in _alarmFeedMessages)
        {
            callOptions.CancellationToken.ThrowIfCancellationRequested();
            await Task.Yield();
            yield return message;
        }
    }
    /// <summary>Enqueues an alarm feed message to be yielded from StreamAlarmsAsync.</summary>
    /// <param name="message">The alarm feed message to enqueue.</param>
    public void AddAlarmFeedMessage(AlarmFeedMessage message)
    {
        _alarmFeedMessages.Add(message);
    }
 }
@@ -1,8 +1,8 @@
 using Google.Protobuf.WellKnownTypes;
 using Grpc.Core;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 public sealed class GalaxyRepositoryClientTests
 {
@@ -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()
    {
@@ -0,0 +1,221 @@
 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 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",
        });
 }
@@ -1,8 +1,8 @@
 using Google.Protobuf;
-using MxGateway.Client;
+using ZB.MOM.WW.MxGateway.Client;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 public sealed class MxCommandReplyExtensionsTests
 {
@@ -1,16 +1,17 @@
 using Google.Protobuf.WellKnownTypes;
 using Grpc.Core;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 /// <summary>
-///     Pins the .NET SDK surface for the alarm RPCs:
+///     PR E.2 — pins the .NET SDK surface for the new alarm RPCs:
 ///     <see cref="MxGatewayClient.AcknowledgeAlarmAsync"/> and
-///     <see cref="MxGatewayClient.StreamAlarmsAsync"/>.
+///     <see cref="MxGatewayClient.QueryActiveAlarmsAsync"/>.
 /// </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,18 +71,21 @@ public sealed class MxGatewayClientAlarmsTests
                cancellation.Token));
    }
    /// <summary>AcknowledgeAlarmAsync maps unauthenticated RPC exception to typed exception.</summary>
    [Fact]
-    public async Task AcknowledgeAlarmAsync_SurfacesRpcExceptionFromFakeTransportVerbatim_WhenMappingDisabled()
+    public async Task AcknowledgeAlarmAsync_MapsUnauthenticated_RpcException_ToTypedException()
    {
        // Default FakeGatewayTransport.MapTransportExceptions is false, matching the
        // historical pass-through shape: a thrown RpcException reaches the caller as
        // RpcException rather than being mapped to a typed MxGatewayException. This
        // test pins that shape so a future change can't silently flip it.
        FakeGatewayTransport transport = CreateTransport();
        transport.AcknowledgeAlarmExceptions.Enqueue(
            new RpcException(new Status(StatusCode.Unauthenticated, "expired key")));
        await using MxGatewayClient client = CreateClient(transport);
        // Note: the FakeGatewayTransport surfaces RpcException directly (it does not run
        // through GrpcMxGatewayClientTransport's mapping); the fake's contract here is to
        // pass the exception verbatim. RpcException → typed exception mapping is covered
        // in the GrpcMxGatewayClientTransport-level tests; the SDK-level test pins the
        // pass-through shape so a future migration to direct mapping won't silently
        // change observable behaviour.
        var ex = await Assert.ThrowsAsync<RpcException>(
            () => client.AcknowledgeAlarmAsync(new AcknowledgeAlarmRequest
            {
@@ -91,73 +96,54 @@ public sealed class MxGatewayClientAlarmsTests
        Assert.Equal(StatusCode.Unauthenticated, ex.StatusCode);
    }
    /// <summary>QueryActiveAlarmsAsync streams enqueued snapshots.</summary>
    [Fact]
-    public async Task AcknowledgeAlarmAsync_MapsUnauthenticated_RpcException_ToTypedException()
+    public async Task QueryActiveAlarmsAsync_StreamsEnqueuedSnapshots()
    {
        // Production parity: GrpcMxGatewayClientTransport.AcknowledgeAlarmAsync runs
        // every thrown RpcException through RpcExceptionMapper.Map, so callers see
        // MxGatewayAuthenticationException (for Unauthenticated) rather than the raw
        // RpcException. The fake transport reproduces that mapping when
        // MapTransportExceptions is set, letting this SDK-level test cover the same
        // observable behaviour without standing up a real gRPC channel.
        FakeGatewayTransport transport = CreateTransport();
        transport.MapTransportExceptions = true;
        transport.AcknowledgeAlarmExceptions.Enqueue(
            new RpcException(new Status(StatusCode.Unauthenticated, "expired key")));
        await using MxGatewayClient client = CreateClient(transport);
        var ex = await Assert.ThrowsAsync<MxGatewayAuthenticationException>(
            () => client.AcknowledgeAlarmAsync(new AcknowledgeAlarmRequest
            {
                AlarmFullReference = "Tank01.Level.HiHi",
                Comment = string.Empty,
                OperatorUser = "alice",
            }));
        Assert.Equal(StatusCode.Unauthenticated, ex.StatusCode);
    }
    [Fact]
    public async Task StreamAlarmsAsync_StreamsSnapshotThenSnapshotComplete()
    {
        FakeGatewayTransport transport = CreateTransport();
        transport.AddActiveAlarmSnapshot(MakeSnapshot("Tank01.Level.HiHi", AlarmConditionState.Active));
        transport.AddActiveAlarmSnapshot(MakeSnapshot("Tank02.Level.HiHi", AlarmConditionState.ActiveAcked));
        await using MxGatewayClient client = CreateClient(transport);
-        List<AlarmFeedMessage> messages = [];
+        List<ActiveAlarmSnapshot> snapshots = [];
-        await foreach (AlarmFeedMessage message in client.StreamAlarmsAsync(new StreamAlarmsRequest()))
+        await foreach (ActiveAlarmSnapshot snapshot in client.QueryActiveAlarmsAsync(new QueryActiveAlarmsRequest
        {
-            messages.Add(message);
+            SessionId = "session-fixture",
        }))
        {
            snapshots.Add(snapshot);
        }
-        Assert.Equal(3, messages.Count);
+        Assert.Equal(2, snapshots.Count);
-        Assert.Equal("Tank01.Level.HiHi", messages[0].ActiveAlarm.AlarmFullReference);
+        Assert.Equal("Tank01.Level.HiHi", snapshots[0].AlarmFullReference);
-        Assert.Equal(AlarmConditionState.Active, messages[0].ActiveAlarm.CurrentState);
+        Assert.Equal(AlarmConditionState.Active, snapshots[0].CurrentState);
-        Assert.Equal(AlarmConditionState.ActiveAcked, messages[1].ActiveAlarm.CurrentState);
+        Assert.Equal(AlarmConditionState.ActiveAcked, snapshots[1].CurrentState);
-        Assert.True(messages[2].SnapshotComplete);
+        Assert.Single(transport.QueryActiveAlarmsCalls);
        Assert.Single(transport.StreamAlarmsCalls);
    }
    /// <summary>QueryActiveAlarmsAsync passes filter prefix.</summary>
    [Fact]
-    public async Task StreamAlarmsAsync_PassesFilterPrefix()
+    public async Task QueryActiveAlarmsAsync_PassesFilterPrefix()
    {
        FakeGatewayTransport transport = CreateTransport();
        await using MxGatewayClient client = CreateClient(transport);
-        await foreach (AlarmFeedMessage _ in client.StreamAlarmsAsync(new StreamAlarmsRequest
+        await foreach (ActiveAlarmSnapshot _ in client.QueryActiveAlarmsAsync(new QueryActiveAlarmsRequest
        {
            SessionId = "session-fixture",
            AlarmFilterPrefix = "Tank01.",
        }))
        {
-            // only the snapshot-complete sentinel; verifying the request passes through
+            // no snapshots enqueued; just verifying the request passes through
        }
-        var call = Assert.Single(transport.StreamAlarmsCalls);
+        var call = Assert.Single(transport.QueryActiveAlarmsCalls);
        Assert.Equal("Tank01.", call.Request.AlarmFilterPrefix);
    }
    /// <summary>QueryActiveAlarmsAsync honors cancellation during enumeration.</summary>
    [Fact]
-    public async Task StreamAlarmsAsync_HonorsCancellationDuringEnumeration()
+    public async Task QueryActiveAlarmsAsync_HonorsCancellationDuringEnumeration()
    {
        FakeGatewayTransport transport = CreateTransport();
        transport.AddActiveAlarmSnapshot(MakeSnapshot("Tank01.Level.HiHi", AlarmConditionState.Active));
@@ -167,8 +153,8 @@ public sealed class MxGatewayClientAlarmsTests
        using CancellationTokenSource cancellation = new();
        await Assert.ThrowsAsync<OperationCanceledException>(async () =>
        {
-            await foreach (AlarmFeedMessage _ in client.StreamAlarmsAsync(
+            await foreach (ActiveAlarmSnapshot _ in client.QueryActiveAlarmsAsync(
-                new StreamAlarmsRequest(),
+                new QueryActiveAlarmsRequest { SessionId = "session-fixture" },
                cancellation.Token))
            {
                cancellation.Cancel();
@@ -1,9 +1,9 @@
 using Google.Protobuf.WellKnownTypes;
-using MxGateway.Client.Cli;
+using ZB.MOM.WW.MxGateway.Client.Cli;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 /// <summary>Tests for the CLI command interface.</summary>
 public sealed class MxGatewayClientCliTests
@@ -106,43 +106,6 @@ public sealed class MxGatewayClientCliTests
        Assert.Contains("[redacted]", error.ToString());
    }
    /// <summary>
    /// Verifies that error output redacts the API key even when it was sourced from
    /// the <c>--api-key-env</c> environment variable rather than passed via
    /// <c>--api-key</c> — the documented default credential path.
    /// </summary>
    [Fact]
    public async Task RunAsync_ErrorOutput_RedactsApiKey_WhenSourcedFromEnvironmentVariable()
    {
        const string environmentVariableName = "MXGATEWAY_TEST_API_KEY_REDACT";
        using var output = new StringWriter();
        using var error = new StringWriter();
        Environment.SetEnvironmentVariable(environmentVariableName, "env-secret-api-key");
        try
        {
            int exitCode = await MxGatewayClientCli.RunAsync(
                [
                    "open-session",
                    "--endpoint",
                    "http://localhost:5000",
                    "--api-key-env",
                    environmentVariableName,
                ],
                output,
                error,
                _ => throw new InvalidOperationException("boom env-secret-api-key"));
            Assert.Equal(1, exitCode);
            Assert.DoesNotContain("env-secret-api-key", error.ToString());
            Assert.Contains("[redacted]", error.ToString());
        }
        finally
        {
            Environment.SetEnvironmentVariable(environmentVariableName, null);
        }
    }
    /// <summary>Verifies that stream-events with max-events limit stops output in non-JSON format.</summary>
    [Fact]
    public async Task RunAsync_StreamEvents_WithMaxEventsStopsNonJsonOutput()
@@ -184,69 +147,6 @@ public sealed class MxGatewayClientCliTests
        Assert.DoesNotContain("ON_WRITE_COMPLETE", output.ToString());
    }
    /// <summary>
    ///     Client.Dotnet-017 regression: a finite-window event collector
    ///     (<c>stream-events --timeout</c>) must exit 0 and emit the events
    ///     that arrived before the timeout fired, instead of propagating the
    ///     timeout-driven <see cref="OperationCanceledException"/> as an
    ///     unhandled exception (exit code -532462766). The fix wraps the
    ///     <c>await foreach</c> in a token-aware catch so the cancellation
    ///     ends the foreach gracefully; the aggregated JSON output still runs.
    /// </summary>
    [Fact]
    public async Task RunAsync_StreamEvents_WhenTimeoutFiresAfterEvents_EmitsCollectedEventsAndExitsZero()
    {
        using var output = new StringWriter();
        using var error = new StringWriter();
        FakeCliClient fakeClient = new();
        fakeClient.Events.Add(new MxEvent
        {
            SessionId = "session-fixture",
            Family = MxEventFamily.OnDataChange,
            WorkerSequence = 1,
        });
        fakeClient.Events.Add(new MxEvent
        {
            SessionId = "session-fixture",
            Family = MxEventFamily.OnDataChange,
            WorkerSequence = 2,
        });
        // Park forever after yielding the configured events so the CLI's
        // --timeout drives the cancellation path.
        fakeClient.StreamHangAfterEvents = async token =>
        {
            await Task.Delay(Timeout.InfiniteTimeSpan, token).ConfigureAwait(false);
        };
        int exitCode = await MxGatewayClientCli.RunAsync(
            [
                "stream-events",
                "--endpoint",
                "http://localhost:5000",
                "--api-key",
                "test-api-key",
                "--session-id",
                "session-fixture",
                "--json",
                "--max-events",
                "200",
                "--timeout",
                "1s",
            ],
            output,
            error,
            _ => fakeClient);
        Assert.Equal(0, exitCode);
        string json = output.ToString();
        // Aggregate JSON output must run even though the foreach exited via
        // cancellation, and it must contain both events that arrived first.
        Assert.Contains("\"events\"", json);
        Assert.Contains("\"workerSequence\":\"1\"", json);
        Assert.Contains("\"workerSequence\":\"2\"", json);
        Assert.Equal(string.Empty, error.ToString());
    }
    /// <summary>Verifies that stream-alarms with --max-events stops output and distinguishes payload cases.</summary>
    [Fact]
@@ -549,139 +449,414 @@ public sealed class MxGatewayClientCliTests
        Assert.Contains("\"objectCount\": 99", text);
    }
-    /// <summary>Verifies that batch mode executes a single no-gateway command and writes the EOR sentinel.</summary>
+    /// <summary>Verifies that batch mode dispatches a single version command and emits the EOR sentinel.</summary>
    [Fact]
-    public async Task RunAsync_Batch_SingleVersionCommand_WritesOutputAndEorSentinel()
+    public async Task RunAsync_Batch_DispatchesVersionAndWritesEndOfRecord()
    {
        using var output = new StringWriter();
        using var error = new StringWriter();
-        using var stdin = new StringReader("version --json\n");
+        using var input = new StringReader("version --json\n");
        int exitCode = await MxGatewayClientCli.RunAsync(
            ["batch"],
            output,
            error,
            clientFactory: null,
-            standardInput: stdin);
+            standardInput: input);
        Assert.Equal(0, exitCode);
        string text = output.ToString();
-        Assert.Contains("\"gatewayProtocolVersion\"", text);
+        Assert.Contains("\"gatewayProtocolVersion\":3", text);
        Assert.Contains("__MXGW_BATCH_EOR__", text);
-        // Sentinel must appear after the output, not before.
+        // The EOR marker must come after the JSON output.
-        int outputIdx = text.IndexOf("gatewayProtocolVersion", StringComparison.Ordinal);
+        int jsonIndex = text.IndexOf("\"gatewayProtocolVersion\"", StringComparison.Ordinal);
-        int eorIdx = text.IndexOf("__MXGW_BATCH_EOR__", StringComparison.Ordinal);
+        int eorIndex = text.IndexOf("__MXGW_BATCH_EOR__", StringComparison.Ordinal);
-        Assert.True(outputIdx < eorIdx, "EOR sentinel must follow command output.");
+        Assert.True(jsonIndex >= 0 && eorIndex > jsonIndex);
        Assert.Equal(string.Empty, error.ToString());
    }
-    /// <summary>Verifies that batch mode processes two commands sequentially and writes two EOR sentinels.</summary>
+    /// <summary>Verifies that batch mode routes per-command errors to stdout as JSON between EOR markers.</summary>
    [Fact]
-    public async Task RunAsync_Batch_TwoVersionCommands_WritesTwoEorSentinels()
+    public async Task RunAsync_Batch_WritesErrorsToStdoutAsJson()
    {
        using var output = new StringWriter();
        using var error = new StringWriter();
-        // Two commands followed by EOF (end of string).
+        // Unknown command should produce an error on the captured error stream,
-        using var stdin = new StringReader("version\nversion --json\n");
+        // which batch mode re-emits to stdout inside the same delimited block.
        using var input = new StringReader("nope-not-a-command\nversion\n");
        int exitCode = await MxGatewayClientCli.RunAsync(
            ["batch"],
            output,
            error,
            clientFactory: null,
-            standardInput: stdin);
+            standardInput: input);
        Assert.Equal(0, exitCode);
        string text = output.ToString();
        // Two records → two EOR markers.
        int firstEor = text.IndexOf("__MXGW_BATCH_EOR__", StringComparison.Ordinal);
-        int secondEor = text.IndexOf("__MXGW_BATCH_EOR__", firstEor + 1, StringComparison.Ordinal);
+        int secondEor = text.IndexOf(
-        Assert.True(firstEor >= 0, "First EOR sentinel must be present.");
+            "__MXGW_BATCH_EOR__",
-        Assert.True(secondEor > firstEor, "Second EOR sentinel must follow first.");
+            firstEor + 1,
-        Assert.Equal(string.Empty, error.ToString());
+            StringComparison.Ordinal);
-    }
+        Assert.True(firstEor > 0);
-
+        Assert.True(secondEor > firstEor);
-    /// <summary>Verifies that batch mode on EOF (empty stdin) exits 0 immediately without writing any sentinel.</summary>
+        // The unknown-command error message must be on stdout (not on stderr).
-    [Fact]
+        Assert.Contains("nope-not-a-command", text);
-    public async Task RunAsync_Batch_EmptyStdin_ExitsZeroWithNoOutput()
+        Assert.DoesNotContain("nope-not-a-command", error.ToString());
-    {
+        // The follow-up `version` line should still succeed.
-        using var output = new StringWriter();
+        Assert.Contains("gateway-protocol=", text);
        using var error = new StringWriter();
        using var stdin = new StringReader(string.Empty);
        int exitCode = await MxGatewayClientCli.RunAsync(
            ["batch"],
            output,
            error,
            clientFactory: null,
            standardInput: stdin);
        Assert.Equal(0, exitCode);
        Assert.Equal(string.Empty, output.ToString());
        Assert.Equal(string.Empty, error.ToString());
    }
    /// <summary>
-    ///     Verifies that batch mode continues after a command failure and writes the error JSON
+    /// Client.Dotnet-018: the README CLI examples for the alarm subcommands at
-    ///     to stdout (not stderr), followed by the EOR sentinel.
+    /// `clients/dotnet/README.md` must drive cleanly through the production
    /// CLI argument parser. The previous text used non-existent flags
    /// (`--session-id`, `--max-messages`, `--alarm-reference`) that would
    /// fail with "Unknown command" / "Missing required option --reference".
    /// Each documented example is extracted from the README, parsed via the
    /// production <see cref="MxGatewayClientCli.RunAsync"/>, and asserted
    /// against exit code 0.
    /// </summary>
-    [Fact]
+    /// <param name="command">The alarm subcommand to validate (e.g. "stream-alarms", "acknowledge-alarm").</param>
-    public async Task RunAsync_Batch_CommandFailure_WritesErrorJsonToStdoutAndContinues()
+    [Theory]
    [InlineData("stream-alarms")]
    [InlineData("acknowledge-alarm")]
    public async Task RunAsync_ReadmeExamples_ForAlarmCommands_ParseSuccessfully(string command)
    {
-        using var output = new StringWriter();
+        string readme = LocateClientReadme();
-        using var error = new StringWriter();
+        string[] commandLine = ExtractReadmeCommandLine(readme, command);
-        // First line: a gateway command with no API key (will fail).
+        // The documented examples do not include --api-key (the README assumes
-        // Second line: version (will succeed).
+        // the env var path documented elsewhere). Inject an API key via the
-        using var stdin = new StringReader("open-session --endpoint http://localhost:5000\nversion --json\n");
+        // standard env var so CreateOptions succeeds and the parser fully
        // exercises the documented flag shape.
        string? previousKey = Environment.GetEnvironmentVariable("MXGATEWAY_API_KEY");
        Environment.SetEnvironmentVariable("MXGATEWAY_API_KEY", "test-api-key");
-        int exitCode = await MxGatewayClientCli.RunAsync(
+        try
-            ["batch"],
+        {
-            output,
+            using var output = new StringWriter();
-            error,
+            using var error = new StringWriter();
-            clientFactory: _ => throw new InvalidOperationException("injected failure"),
+            FakeCliClient fakeClient = new();
-            standardInput: stdin);
+            fakeClient.AlarmFeedMessages.Add(new AlarmFeedMessage
            {
                ActiveAlarm = new ActiveAlarmSnapshot { AlarmFullReference = "fixture" },
            });
            fakeClient.AcknowledgeAlarmReplies.Enqueue(new AcknowledgeAlarmReply
            {
                CorrelationId = "ack-fixture",
                ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
            });
-        Assert.Equal(0, exitCode);
+            int exitCode = await MxGatewayClientCli.RunAsync(
-        string text = output.ToString();
+                commandLine,
                output,
                error,
                _ => fakeClient);
-        // Error record: the error JSON must be on stdout, not stderr.
+            Assert.True(
-        Assert.Contains("\"error\"", text);
+                exitCode == 0,
-        Assert.Equal(string.Empty, error.ToString());
+                $"README example for '{command}' exited {exitCode}; stderr=<<{error}>>");
-
+            Assert.DoesNotContain("Unknown command", error.ToString());
-        // Both records must be present.
+            Assert.DoesNotContain("Missing required option", error.ToString());
-        int firstEor = text.IndexOf("__MXGW_BATCH_EOR__", StringComparison.Ordinal);
+        }
-        int secondEor = text.IndexOf("__MXGW_BATCH_EOR__", firstEor + 1, StringComparison.Ordinal);
+        finally
-        Assert.True(firstEor >= 0, "EOR after failed command must be present.");
+        {
-        Assert.True(secondEor > firstEor, "EOR after successful command must follow first EOR.");
+            Environment.SetEnvironmentVariable("MXGATEWAY_API_KEY", previousKey);
-
+        }
        // Second record must contain the version output.
        string afterFirstEor = text[(firstEor + "__MXGW_BATCH_EOR__".Length)..];
        Assert.Contains("\"gatewayProtocolVersion\"", afterFirstEor);
    }
-    /// <summary>Verifies that batch mode treats an empty (blank) line as EOF and exits 0.</summary>
+    /// <summary>
    /// Client.Dotnet-019: `BenchReadBulkAsync` previously fell back to
    /// <c>reply.ReturnValue.Int32Value</c> when the register reply had no
    /// typed <c>Register</c> payload, silently driving the rest of the bench
    /// against a zero server handle. The fix must fail loudly with a
    /// descriptive <see cref="MxGatewayException"/>.
    /// </summary>
    [Fact]
-    public async Task RunAsync_Batch_EmptyLine_ExitsZeroAfterPreviousCommands()
+    public async Task RunAsync_BenchReadBulk_WhenRegisterReplyMissingTypedPayload_FailsLoudly()
    {
        using var output = new StringWriter();
        using var error = new StringWriter();
-        // One command, then an empty line (stop signal), then another command that must NOT run.
+        FakeCliClient fakeClient = new();
-        using var stdin = new StringReader("version --json\n\nversion --json\n");
+        // Successful protocol + MX status but no typed `Register` payload.
        // Before the Client.Dotnet-019 fix this silently became serverHandle=0
        // and the bench proceeded through SubscribeBulk / warmup / steady-state
        // against an invalid handle, producing a misleading zero-result summary.
        fakeClient.InvokeReplies.Enqueue(new MxCommandReply
        {
            SessionId = "session-fixture",
            Kind = MxCommandKind.Register,
            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
        });
        int exitCode = await MxGatewayClientCli.RunAsync(
-            ["batch"],
+            [
                "bench-read-bulk",
                "--endpoint",
                "http://localhost:5000",
                "--api-key",
                "test-api-key",
                "--duration-seconds",
                "1",
                "--warmup-seconds",
                "0",
                "--bulk-size",
                "1",
            ],
            output,
            error,
-            clientFactory: null,
+            _ => fakeClient);
            standardInput: stdin);
-        Assert.Equal(0, exitCode);
+        Assert.Equal(1, exitCode);
-        string text = output.ToString();
+        // Descriptive message that names the missing typed payload.
-        // Only one EOR sentinel — the second command after the empty line must not execute.
+        string err = error.ToString();
-        int firstEor = text.IndexOf("__MXGW_BATCH_EOR__", StringComparison.Ordinal);
+        Assert.Contains("Register", err);
-        int secondEor = text.IndexOf("__MXGW_BATCH_EOR__", firstEor + 1, StringComparison.Ordinal);
+        // The bench must not produce any aggregate stats JSON.
-        Assert.True(firstEor >= 0, "One EOR sentinel must be present.");
+        Assert.DoesNotContain("bench-read-bulk", output.ToString());
-        Assert.Equal(-1, secondEor);
+    }
-        Assert.Equal(string.Empty, error.ToString());
+
    /// <summary>
    /// Client.Dotnet-020: the steady-state loop in `BenchReadBulkAsync` had a
    /// bare `catch { failedCalls++; continue; }` that swallowed
    /// <see cref="OperationCanceledException"/>, so token-driven cancellation
    /// kept spinning until <c>--duration-seconds</c> elapsed. After the fix
    /// the bench must exit promptly when the supplied token cancels.
    /// </summary>
    [Fact]
    public async Task RunAsync_BenchReadBulk_WhenSteadyStateLoopReceivesCancellation_ExitsPromptly()
    {
        using var output = new StringWriter();
        using var error = new StringWriter();
        int invokeCount = 0;
        FakeCliClient fakeClient = new()
        {
            InvokeHandler = (request, ct) =>
            {
                int n = Interlocked.Increment(ref invokeCount);
                // Reply 1 = Register (success with typed payload).
                if (request.Command.Kind == MxCommandKind.Register)
                {
                    return Task.FromResult(new MxCommandReply
                    {
                        SessionId = "session-fixture",
                        Kind = MxCommandKind.Register,
                        ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
                        Register = new RegisterReply { ServerHandle = 1 },
                    });
                }
                // Reply 2 = SubscribeBulk (success).
                if (request.Command.Kind == MxCommandKind.SubscribeBulk)
                {
                    var subscribeReply = new MxCommandReply
                    {
                        SessionId = "session-fixture",
                        Kind = MxCommandKind.SubscribeBulk,
                        ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
                        SubscribeBulk = new BulkSubscribeReply(),
                    };
                    return Task.FromResult(subscribeReply);
                }
                // ReadBulk reply 1 = success (so the steady-state loop enters
                // and starts iterating). Reply 2+ = simulated cancellation.
                if (request.Command.Kind == MxCommandKind.ReadBulk && n <= 3)
                {
                    return Task.FromResult(new MxCommandReply
                    {
                        SessionId = "session-fixture",
                        Kind = MxCommandKind.ReadBulk,
                        ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
                        ReadBulk = new BulkReadReply(),
                    });
                }
                // From here on every ReadBulk throws OCE — the steady-state
                // loop must exit promptly rather than spinning until
                // --duration-seconds elapses.
                throw new OperationCanceledException();
            },
        };
        var sw = System.Diagnostics.Stopwatch.StartNew();
        await Assert.ThrowsAsync<OperationCanceledException>(async () =>
            await MxGatewayClientCli.RunAsync(
                [
                    "bench-read-bulk",
                    "--endpoint",
                    "http://localhost:5000",
                    "--api-key",
                    "test-api-key",
                    "--duration-seconds",
                    "30",
                    "--warmup-seconds",
                    "0",
                    "--bulk-size",
                    "1",
                ],
                output,
                error,
                _ => fakeClient));
        sw.Stop();
        // Without the fix the loop swallows OCE and continues until the 30 s
        // steady-state deadline expires. With the fix it exits as soon as OCE
        // surfaces. Generous 10 s ceiling to keep the test stable under load.
        Assert.True(
            sw.Elapsed < TimeSpan.FromSeconds(10),
            $"Bench did not exit promptly on cancellation; took {sw.Elapsed}.");
    }
    /// <summary>
    /// Client.Dotnet-021: both `ReadBulkAsync` and `BenchReadBulkAsync` cast
    /// the user-supplied <c>--timeout-ms</c> to <see cref="uint"/> without
    /// bounds checking, so a negative value (e.g. <c>-1</c>) silently wraps
    /// to ~49.7 days. The fix must reject negatives with a clear error.
    /// </summary>
    /// <param name="command">The bulk-read subcommand to validate (e.g. "read-bulk", "bench-read-bulk").</param>
    [Theory]
    [InlineData("read-bulk")]
    [InlineData("bench-read-bulk")]
    public async Task RunAsync_TimeoutMs_NegativeValue_RejectsWithClearError(string command)
    {
        using var output = new StringWriter();
        using var error = new StringWriter();
        FakeCliClient fakeClient = new();
        string[] args = command is "read-bulk"
            ? [
                "read-bulk",
                "--endpoint",
                "http://localhost:5000",
                "--api-key",
                "test-api-key",
                "--session-id",
                "session-fixture",
                "--server-handle",
                "1",
                "--items",
                "Area001.Pump001.Speed",
                "--timeout-ms",
                "-1",
            ]
            : [
                "bench-read-bulk",
                "--endpoint",
                "http://localhost:5000",
                "--api-key",
                "test-api-key",
                "--duration-seconds",
                "1",
                "--warmup-seconds",
                "0",
                "--bulk-size",
                "1",
                "--timeout-ms",
                "-1",
            ];
        int exitCode = await MxGatewayClientCli.RunAsync(
            args,
            output,
            error,
            _ => fakeClient);
        Assert.NotEqual(0, exitCode);
        string err = error.ToString();
        Assert.Contains("timeout-ms", err);
        Assert.Contains("non-negative", err);
    }
    /// <summary>
    /// Locates the .NET client README by walking up from the test assembly's
    /// base directory until <c>clients/dotnet/README.md</c> is found. Keeps
    /// the regression test independent of the current working directory.
    /// </summary>
    private static string LocateClientReadme()
    {
        string? directory = AppContext.BaseDirectory;
        while (!string.IsNullOrEmpty(directory))
        {
            string candidate = Path.Combine(directory, "clients", "dotnet", "README.md");
            if (File.Exists(candidate))
            {
                return candidate;
            }
            directory = Path.GetDirectoryName(directory);
        }
        throw new FileNotFoundException("clients/dotnet/README.md not found above test assembly base directory.");
    }
    /// <summary>
    /// Extracts the documented CLI invocation for the requested subcommand
    /// from the README, returning only the arguments after the
    /// <c>mxgw-dotnet</c>-equivalent prefix so they can be passed straight
    /// to <see cref="MxGatewayClientCli.RunAsync"/>.
    /// </summary>
    private static string[] ExtractReadmeCommandLine(string readmePath, string command)
    {
        string[] lines = File.ReadAllLines(readmePath);
        // Look for the documented `dotnet run ... -- <command> ...` line.
        foreach (string line in lines)
        {
            int dashes = line.IndexOf("-- " + command, StringComparison.Ordinal);
            if (dashes < 0)
            {
                continue;
            }
            string after = line[(dashes + 3)..].Trim();
            // Tokenize by whitespace, respecting "..." quoted segments.
            return TokenizeCommandLine(after);
        }
        throw new InvalidOperationException(
            $"README at '{readmePath}' has no documented example for subcommand '{command}'.");
    }
    /// <summary>
    /// Splits a single command-line string into argv tokens, honouring
    /// double-quoted segments so paths with embedded spaces survive intact.
    /// </summary>
    private static string[] TokenizeCommandLine(string input)
    {
        var tokens = new List<string>();
        var current = new System.Text.StringBuilder();
        bool inQuotes = false;
        foreach (char ch in input)
        {
            if (ch == '"')
            {
                inQuotes = !inQuotes;
                continue;
            }
            if (!inQuotes && char.IsWhiteSpace(ch))
            {
                if (current.Length > 0)
                {
                    tokens.Add(current.ToString());
                    current.Clear();
                }
                continue;
            }
            current.Append(ch);
        }
        if (current.Length > 0)
        {
            tokens.Add(current.ToString());
        }
        return tokens.ToArray();
    }
    /// <summary>Fake CLI client for testing.</summary>
@@ -702,13 +877,8 @@ public sealed class MxGatewayClientCliTests
        /// <summary>Exception to throw on invoke, if any.</summary>
        public Exception? InvokeFailure { get; init; }
-        /// <summary>
+        /// <summary>Optional per-call handler that overrides queue-based behaviour.</summary>
-        ///     When set, after yielding all <see cref="Events"/> the stream
+        public Func<MxCommandRequest, CancellationToken, Task<MxCommandReply>>? InvokeHandler { get; init; }
        ///     awaits the provided handle and then throws
        ///     <see cref="OperationCanceledException"/> — used to simulate the
        ///     CLI timeout / Ctrl+C cancellation path (Client.Dotnet-017).
        /// </summary>
        public Func<CancellationToken, Task>? StreamHangAfterEvents { get; set; }
        /// <inheritdoc />
        public ValueTask DisposeAsync()
@@ -755,6 +925,11 @@ public sealed class MxGatewayClientCliTests
                throw InvokeFailure;
            }
            if (InvokeHandler is not null)
            {
                return InvokeHandler(request, cancellationToken);
            }
            return Task.FromResult(InvokeReplies.Dequeue());
        }
@@ -769,11 +944,6 @@ public sealed class MxGatewayClientCliTests
                await Task.Yield();
                yield return gatewayEvent;
            }
            if (StreamHangAfterEvents is not null)
            {
                await StreamHangAfterEvents(cancellationToken).ConfigureAwait(false);
            }
        }
        /// <summary>Queue of acknowledge-alarm replies to return.</summary>
@@ -820,6 +990,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>
@@ -1,6 +1,6 @@
-using MxGateway.Contracts;
+using ZB.MOM.WW.MxGateway.Contracts;
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 public sealed class MxGatewayClientContractInfoTests
 {
@@ -1,4 +1,4 @@
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 public sealed class MxGatewayClientOptionsTests
 {
@@ -1,7 +1,7 @@
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using Grpc.Core;
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 /// <summary>Tests for MxGatewaySession and client command behavior.</summary>
 public sealed class MxGatewayClientSessionTests
@@ -184,96 +184,6 @@ public sealed class MxGatewayClientSessionTests
        Assert.Equal(["Area001.Pump001.Speed"], request.Command.SubscribeBulk.TagAddresses);
    }
    /// <summary>
    /// Verifies that WriteBulk builds one command carrying the entry list verbatim
    /// and returns the per-entry BulkWriteResult list without throwing on per-entry
    /// failures.
    /// </summary>
    [Fact]
    public async Task WriteBulkAsync_BuildsOneBulkCommandAndReturnsPerEntryResults()
    {
        FakeGatewayTransport transport = CreateTransport();
        transport.AddInvokeReply(new MxCommandReply
        {
            SessionId = "session-fixture",
            Kind = MxCommandKind.WriteBulk,
            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
            WriteBulk = new BulkWriteReply
            {
                Results =
                {
                    new BulkWriteResult { ServerHandle = 12, ItemHandle = 901, WasSuccessful = true },
                    new BulkWriteResult { ServerHandle = 12, ItemHandle = 902, WasSuccessful = false, ErrorMessage = "Invalid handle" },
                },
            },
        });
        await using MxGatewayClient client = CreateClient(transport);
        MxGatewaySession session = await client.OpenSessionAsync();
        IReadOnlyList<BulkWriteResult> results = await session.WriteBulkAsync(
            12,
            new[]
            {
                new WriteBulkEntry { ItemHandle = 901, UserId = 5, Value = new MxValue { DataType = MxDataType.Integer, Int32Value = 11 } },
                new WriteBulkEntry { ItemHandle = 902, UserId = 5, Value = new MxValue { DataType = MxDataType.Integer, Int32Value = 22 } },
            });
        Assert.Equal(2, results.Count);
        Assert.True(results[0].WasSuccessful);
        Assert.False(results[1].WasSuccessful);
        MxCommandRequest request = Assert.Single(transport.InvokeCalls).Request;
        Assert.Equal(MxCommandKind.WriteBulk, request.Command.Kind);
        Assert.Equal(12, request.Command.WriteBulk.ServerHandle);
        Assert.Equal(2, request.Command.WriteBulk.Entries.Count);
        Assert.Equal(901, request.Command.WriteBulk.Entries[0].ItemHandle);
    }
    /// <summary>
    /// Verifies that ReadBulk forwards the timeout to the gateway as milliseconds
    /// and unpacks the BulkReadReply payload's was_cached / value fields.
    /// </summary>
    [Fact]
    public async Task ReadBulkAsync_ForwardsTimeoutAndUnpacksCachedFlag()
    {
        FakeGatewayTransport transport = CreateTransport();
        transport.AddInvokeReply(new MxCommandReply
        {
            SessionId = "session-fixture",
            Kind = MxCommandKind.ReadBulk,
            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
            ReadBulk = new BulkReadReply
            {
                Results =
                {
                    new BulkReadResult
                    {
                        ServerHandle = 12,
                        TagAddress = "Area001.Pump001.Speed",
                        ItemHandle = 901,
                        WasSuccessful = true,
                        WasCached = true,
                        Value = new MxValue { DataType = MxDataType.Integer, Int32Value = 99 },
                    },
                },
            },
        });
        await using MxGatewayClient client = CreateClient(transport);
        MxGatewaySession session = await client.OpenSessionAsync();
        IReadOnlyList<BulkReadResult> results = await session.ReadBulkAsync(
            12,
            ["Area001.Pump001.Speed"],
            TimeSpan.FromMilliseconds(750));
        BulkReadResult result = Assert.Single(results);
        Assert.True(result.WasCached);
        Assert.Equal(99, result.Value.Int32Value);
        MxCommandRequest request = Assert.Single(transport.InvokeCalls).Request;
        Assert.Equal(MxCommandKind.ReadBulk, request.Command.Kind);
        Assert.Equal(750u, request.Command.ReadBulk.TimeoutMs);
        Assert.Equal(["Area001.Pump001.Speed"], request.Command.ReadBulk.TagAddresses);
    }
    /// <summary>Verifies that stream events yields events in the order received from the gateway.</summary>
    [Fact]
    public async Task StreamEventsAsync_YieldsEventsInGatewayOrder()
@@ -321,52 +231,6 @@ public sealed class MxGatewayClientSessionTests
        Assert.Equal("session-fixture", call.Request.SessionId);
    }
    /// <summary>
    /// Verifies that disposing a session while other callers are concurrently inside
    /// <see cref="MxGatewaySession.CloseAsync"/> — one holding the close lock and one
    /// parked on it — never throws <see cref="ObjectDisposedException"/> into those
    /// callers. The close lock must outlive every pending close.
    /// </summary>
    [Fact]
    public async Task DisposeAsync_DoesNotRaceConcurrentCloseAsync()
    {
        for (int iteration = 0; iteration < 100; iteration++)
        {
            FakeGatewayTransport transport = CreateTransport();
            using SemaphoreSlim firstCloseEntered = new(0, 1);
            using SemaphoreSlim releaseFirstClose = new(0, 1);
            // The first CloseAsync to reach the transport parks here while holding the
            // session's close lock; later callers queue on the lock behind it.
            transport.CloseSessionHook = async () =>
            {
                firstCloseEntered.Release();
                await releaseFirstClose.WaitAsync().ConfigureAwait(false);
                transport.CloseSessionHook = null;
            };
            await using MxGatewayClient client = CreateClient(transport);
            MxGatewaySession session = await client.OpenSessionAsync();
            // Holder enters CloseAsync, acquires the lock, and parks in the hook.
            Task holder = Task.Run(() => session.CloseAsync());
            await firstCloseEntered.WaitAsync();
            // Waiter is parked on the close lock behind the holder.
            Task waiter = Task.Run(() => session.CloseAsync());
            // DisposeAsync runs concurrently; it must wait out both callers before
            // disposing the close lock rather than tearing it down underneath them.
            Task dispose = session.DisposeAsync().AsTask();
            releaseFirstClose.Release();
            await holder;
            await waiter;
            await dispose;
        }
    }
    /// <summary>Verifies that invoke retries safe diagnostic commands on transient RPC failure.</summary>
    [Fact]
    public async Task InvokeAsync_RetriesSafeDiagnosticCommandOnTransientGrpcFailure()
@@ -391,35 +255,6 @@ public sealed class MxGatewayClientSessionTests
        Assert.Equal(2, transport.InvokeCalls.Count);
    }
    /// <summary>
    /// Verifies that the retry pipeline still retries when the transport maps the raw
    /// <see cref="RpcException"/> to an <see cref="MxGatewayException"/> before it reaches
    /// the retry predicate — the wrapped-exception shape that production always produces.
    /// </summary>
    [Fact]
    public async Task InvokeAsync_RetriesSafeDiagnosticCommand_WhenTransportMapsRpcException()
    {
        FakeGatewayTransport transport = CreateTransport();
        transport.MapTransportExceptions = true;
        transport.InvokeExceptions.Enqueue(CreateTransientRpcException());
        transport.AddInvokeReply(new MxCommandReply
        {
            SessionId = "session-fixture",
            Kind = MxCommandKind.Ping,
            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
        });
        await using MxGatewayClient client = CreateClient(transport);
        MxGatewaySession session = await client.OpenSessionAsync();
        await session.InvokeAsync(new MxCommandRequest
        {
            SessionId = session.SessionId,
            Command = new MxCommand { Kind = MxCommandKind.Ping, Ping = new PingCommand() },
        });
        Assert.Equal(2, transport.InvokeCalls.Count);
    }
    /// <summary>Verifies that open session does not retry on transient RPC failure.</summary>
    [Fact]
    public async Task OpenSessionAsync_DoesNotRetryTransientGrpcFailure()
@@ -468,84 +303,6 @@ public sealed class MxGatewayClientSessionTests
        Assert.Equal(cancellation.Token, Assert.Single(transport.InvokeCalls).CallOptions.CancellationToken);
    }
    /// <summary>
    /// Verifies that a client-imposed <see cref="StatusCode.DeadlineExceeded"/> is not
    /// retried. The deadline budget is shared across the whole safe-unary operation, so
    /// an immediate retry would only fail again — the call must surface the failure.
    /// </summary>
    [Fact]
    public async Task InvokeAsync_DoesNotRetrySafeDiagnosticCommand_OnDeadlineExceeded()
    {
        FakeGatewayTransport transport = CreateTransport();
        transport.InvokeExceptions.Enqueue(
            new RpcException(new Status(StatusCode.DeadlineExceeded, "deadline exceeded")));
        transport.AddInvokeReply(new MxCommandReply
        {
            SessionId = "session-fixture",
            Kind = MxCommandKind.Ping,
            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
        });
        await using MxGatewayClient client = CreateClient(transport);
        MxGatewaySession session = await client.OpenSessionAsync();
        await Assert.ThrowsAsync<RpcException>(async () => await session.InvokeAsync(
            new MxCommandRequest
            {
                SessionId = session.SessionId,
                Command = new MxCommand { Kind = MxCommandKind.Ping, Ping = new PingCommand() },
            }));
        Assert.Single(transport.InvokeCalls);
    }
    /// <summary>
    /// Verifies that a successful register reply missing the typed <c>register</c>
    /// payload throws a descriptive <see cref="MxGatewayException"/> rather than
    /// silently returning a zero server handle.
    /// </summary>
    [Fact]
    public async Task RegisterAsync_Throws_WhenSuccessfulReplyMissingPayload()
    {
        FakeGatewayTransport transport = CreateTransport();
        transport.AddInvokeReply(new MxCommandReply
        {
            SessionId = "session-fixture",
            Kind = MxCommandKind.Register,
            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
        });
        await using MxGatewayClient client = CreateClient(transport);
        MxGatewaySession session = await client.OpenSessionAsync();
        MxGatewayException exception = await Assert.ThrowsAsync<MxGatewayException>(
            async () => await session.RegisterAsync("client-name"));
        Assert.Contains("register", exception.Message, StringComparison.Ordinal);
    }
    /// <summary>
    /// Verifies that a successful add-item reply missing the typed <c>add_item</c>
    /// payload throws a descriptive <see cref="MxGatewayException"/> rather than
    /// silently returning a zero item handle.
    /// </summary>
    [Fact]
    public async Task AddItemAsync_Throws_WhenSuccessfulReplyMissingPayload()
    {
        FakeGatewayTransport transport = CreateTransport();
        transport.AddInvokeReply(new MxCommandReply
        {
            SessionId = "session-fixture",
            Kind = MxCommandKind.AddItem,
            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
        });
        await using MxGatewayClient client = CreateClient(transport);
        MxGatewaySession session = await client.OpenSessionAsync();
        MxGatewayException exception = await Assert.ThrowsAsync<MxGatewayException>(
            async () => await session.AddItemAsync(1, "Area.Pump.Speed"));
        Assert.Contains("add_item", exception.Message, StringComparison.Ordinal);
    }
    private static MxGatewayClient CreateClient(FakeGatewayTransport transport)
    {
        return new MxGatewayClient(transport.Options, transport);
@@ -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);
    }
 }
@@ -1,4 +1,4 @@
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 public sealed class MxGatewayGeneratedContractTests
 {
@@ -1,9 +1,9 @@
 using System.Text.Json;
 using Google.Protobuf;
-using MxGateway.Client;
+using ZB.MOM.WW.MxGateway.Client;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 public sealed class MxStatusProxyExtensionsTests
 {
@@ -1,9 +1,9 @@
 using System.Text.Json;
 using Google.Protobuf;
-using MxGateway.Client;
+using ZB.MOM.WW.MxGateway.Client;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 public sealed class MxValueExtensionsTests
 {
@@ -19,8 +19,8 @@
  </ItemGroup>
  <ItemGroup>
-    <ProjectReference Include="..\MxGateway.Client\MxGateway.Client.csproj" />
+    <ProjectReference Include="..\ZB.MOM.WW.MxGateway.Client\ZB.MOM.WW.MxGateway.Client.csproj" />
-    <ProjectReference Include="..\MxGateway.Client.Cli\MxGateway.Client.Cli.csproj" />
+    <ProjectReference Include="..\ZB.MOM.WW.MxGateway.Client.Cli\ZB.MOM.WW.MxGateway.Client.Cli.csproj" />
  </ItemGroup>
 </Project>
@@ -0,0 +1,11 @@
 <Solution>
  <Configurations>
    <Platform Name="Any CPU" />
    <Platform Name="x64" />
    <Platform Name="x86" />
  </Configurations>
  <Project Path="../../src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj" />
  <Project Path="ZB.MOM.WW.MxGateway.Client.Cli/ZB.MOM.WW.MxGateway.Client.Cli.csproj" />
  <Project Path="ZB.MOM.WW.MxGateway.Client.Tests/ZB.MOM.WW.MxGateway.Client.Tests.csproj" />
  <Project Path="ZB.MOM.WW.MxGateway.Client/ZB.MOM.WW.MxGateway.Client.csproj" />
 </Solution>
@@ -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; }
 }
@@ -0,0 +1,43 @@
 namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>
 /// Filters and shape options for <see cref="GalaxyRepositoryClient.DiscoverHierarchyAsync(DiscoverHierarchyOptions, System.Threading.CancellationToken)"/>.
 /// </summary>
 /// <remarks>
 /// Hand-written ergonomic wrapper around the generated
 /// <c>DiscoverHierarchyRequest</c>: lets callers express a Galaxy-browse
 /// slice with .NET-friendly nullable scalars and collection initializers,
 /// without touching the protobuf message's <c>oneof root</c> directly.
 /// </remarks>
 public sealed class DiscoverHierarchyOptions
 {
    /// <summary>Restrict to the subtree rooted at this Galaxy <c>gobject_id</c>.</summary>
    public int? RootGobjectId { get; init; }
    /// <summary>Restrict to the subtree rooted at the object with this tag name.</summary>
    public string? RootTagName { get; init; }
    /// <summary>Restrict to the subtree rooted at this <c>contained_name</c> path.</summary>
    public string? RootContainedPath { get; init; }
    /// <summary>Maximum traversal depth, measured from the chosen root.</summary>
    public int? MaxDepth { get; init; }
    /// <summary>Restrict to objects whose Galaxy category is in this set.</summary>
    public IReadOnlyList<int> CategoryIds { get; init; } = [];
    /// <summary>Restrict to objects 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 objects that bear at least one alarm attribute.</summary>
    public bool AlarmBearingOnly { get; init; }
    /// <summary>Restrict to objects that have at least one historized attribute.</summary>
    public bool HistorizedOnly { get; init; }
 }
@@ -2,14 +2,14 @@ using Google.Protobuf.WellKnownTypes;
 using Grpc.Core;
 using Grpc.Net.Client;
 using Microsoft.Extensions.Logging;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
 using Polly;
 using System.Net.Http;
 using System.Net.Security;
 using System.Runtime.CompilerServices;
 using System.Security.Cryptography.X509Certificates;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>
 /// Provides the .NET client entry point for the public Galaxy Repository gRPC API.
@@ -19,11 +19,12 @@ namespace 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;
    private readonly ResiliencePipeline _safeUnaryRetryPipeline;
-    private int _disposed;
+    private bool _disposed;
    /// <summary>
    /// Initializes a Galaxy Repository client with custom transport and options.
@@ -182,17 +183,10 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
        return await DiscoverHierarchyAsync(new DiscoverHierarchyOptions(), cancellationToken).ConfigureAwait(false);
    }
-    /// <summary>
+    /// <summary>Discovers the Galaxy object hierarchy.</summary>
-    /// Enumerates the deployed Galaxy object hierarchy with caller-supplied
+    /// <param name="options">Client configuration options.</param>
-    /// server-side filters. Each returned <see cref="GalaxyObject"/> may include
+    /// <param name="cancellationToken">Token to observe for cancellation.</param>
-    /// its dynamic attributes (controlled by <see cref="DiscoverHierarchyOptions.IncludeAttributes"/>),
+    /// <returns>The collection of Galaxy objects in the hierarchy.</returns>
    /// so callers can determine which tag references they may subscribe to via
    /// the MxAccessGateway service. The client transparently follows the
    /// gateway's pagination cursor until the hierarchy is fully drained.
    /// </summary>
    /// <param name="options">Server-side filter and shape options.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The filtered collection of Galaxy objects.</returns>
    public async Task<IReadOnlyList<GalaxyObject>> DiscoverHierarchyAsync(
        DiscoverHierarchyOptions options,
        CancellationToken cancellationToken = default)
@@ -285,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
@@ -349,11 +426,12 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
    /// </summary>
    public ValueTask DisposeAsync()
    {
-        if (Interlocked.Exchange(ref _disposed, 1) != 0)
+        if (_disposed)
        {
            return ValueTask.CompletedTask;
        }
        _disposed = true;
        _channel?.Dispose();
        return ValueTask.CompletedTask;
    }
@@ -412,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()
        {
@@ -432,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;
@@ -447,6 +533,10 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
                    return customChain.Build(certificateToValidate);
                };
            }
            else if (!options.RequireCertificateValidation)
            {
                handler.SslOptions.RemoteCertificateValidationCallback = (_, _, _, _) => true;
            }
        }
        return handler;
@@ -454,6 +544,6 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
    private void ThrowIfDisposed()
    {
-        ObjectDisposedException.ThrowIf(Volatile.Read(ref _disposed) != 0, this);
+        ObjectDisposedException.ThrowIf(_disposed, this);
    }
 }
@@ -1,7 +1,7 @@
 using Grpc.Core;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>
 /// gRPC implementation of IGalaxyRepositoryClientTransport.
@@ -36,7 +36,7 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
        }
        catch (RpcException exception)
        {
-            throw RpcExceptionMapper.Map(exception, callOptions.CancellationToken);
+            throw MapRpcException(exception, callOptions.CancellationToken);
        }
    }
@@ -53,7 +53,7 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
        }
        catch (RpcException exception)
        {
-            throw RpcExceptionMapper.Map(exception, callOptions.CancellationToken);
+            throw MapRpcException(exception, callOptions.CancellationToken);
        }
    }
@@ -70,7 +70,24 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
        }
        catch (RpcException exception)
        {
-            throw RpcExceptionMapper.Map(exception, callOptions.CancellationToken);
+            throw MapRpcException(exception, callOptions.CancellationToken);
        }
    }
    /// <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);
        }
    }
@@ -101,7 +118,7 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
            }
            catch (RpcException exception)
            {
-                throw RpcExceptionMapper.Map(exception, effectiveCancellationToken);
+                throw MapRpcException(exception, effectiveCancellationToken);
            }
            yield return deployEvent;
@@ -115,4 +132,28 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
    {
        return WatchDeployEventsAsync(request, callOptions);
    }
    private static Exception MapRpcException(
        RpcException exception,
        CancellationToken cancellationToken)
    {
        if (cancellationToken.IsCancellationRequested || exception.StatusCode == StatusCode.Cancelled)
        {
            return new OperationCanceledException(
                exception.Status.Detail,
                exception,
                cancellationToken);
        }
        return exception.StatusCode switch
        {
            StatusCode.Unauthenticated => new MxGatewayAuthenticationException(
                exception.Status.Detail,
                innerException: exception),
            StatusCode.PermissionDenied => new MxGatewayAuthorizationException(
                exception.Status.Detail,
                innerException: exception),
            _ => new MxGatewayException(exception.Status.Detail, exception),
        };
    }
 }
@@ -1,7 +1,7 @@
 using Grpc.Core;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>
 /// gRPC implementation of IMxGatewayClientTransport.
@@ -36,7 +36,7 @@ internal sealed class GrpcMxGatewayClientTransport(
        }
        catch (RpcException exception)
        {
-            throw RpcExceptionMapper.Map(exception, callOptions.CancellationToken);
+            throw MapRpcException(exception, callOptions.CancellationToken);
        }
    }
@@ -53,7 +53,7 @@ internal sealed class GrpcMxGatewayClientTransport(
        }
        catch (RpcException exception)
        {
-            throw RpcExceptionMapper.Map(exception, callOptions.CancellationToken);
+            throw MapRpcException(exception, callOptions.CancellationToken);
        }
    }
@@ -70,7 +70,7 @@ internal sealed class GrpcMxGatewayClientTransport(
        }
        catch (RpcException exception)
        {
-            throw RpcExceptionMapper.Map(exception, callOptions.CancellationToken);
+            throw MapRpcException(exception, callOptions.CancellationToken);
        }
    }
@@ -101,7 +101,7 @@ internal sealed class GrpcMxGatewayClientTransport(
            }
            catch (RpcException exception)
            {
-                throw RpcExceptionMapper.Map(exception, effectiveCancellationToken);
+                throw MapRpcException(exception, effectiveCancellationToken);
            }
            yield return gatewayEvent;
@@ -129,10 +129,52 @@ internal sealed class GrpcMxGatewayClientTransport(
        }
        catch (RpcException exception)
        {
-            throw RpcExceptionMapper.Map(exception, callOptions.CancellationToken);
+            throw MapRpcException(exception, callOptions.CancellationToken);
        }
    }
    /// <inheritdoc />
    public async IAsyncEnumerable<ActiveAlarmSnapshot> QueryActiveAlarmsAsync(
        QueryActiveAlarmsRequest request,
        CallOptions callOptions,
        [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        CancellationToken effectiveCancellationToken = cancellationToken.CanBeCanceled
            ? cancellationToken
            : callOptions.CancellationToken;
        using AsyncServerStreamingCall<ActiveAlarmSnapshot> call = RawClient.QueryActiveAlarms(request, callOptions);
        IAsyncStreamReader<ActiveAlarmSnapshot> responseStream = call.ResponseStream;
        while (true)
        {
            ActiveAlarmSnapshot? snapshot;
            try
            {
                if (!await responseStream.MoveNext(effectiveCancellationToken).ConfigureAwait(false))
                {
                    break;
                }
                snapshot = responseStream.Current;
            }
            catch (RpcException exception)
            {
                throw MapRpcException(exception, effectiveCancellationToken);
            }
            yield return snapshot;
        }
    }
    /// <inheritdoc />
    IAsyncEnumerable<ActiveAlarmSnapshot> IMxGatewayClientTransport.QueryActiveAlarmsAsync(
        QueryActiveAlarmsRequest request,
        CallOptions callOptions)
    {
        return QueryActiveAlarmsAsync(request, callOptions);
    }
    /// <inheritdoc />
    public async IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
        StreamAlarmsRequest request,
@@ -160,7 +202,7 @@ internal sealed class GrpcMxGatewayClientTransport(
            }
            catch (RpcException exception)
            {
-                throw RpcExceptionMapper.Map(exception, effectiveCancellationToken);
+                throw MapRpcException(exception, effectiveCancellationToken);
            }
            yield return message;
@@ -174,4 +216,28 @@ internal sealed class GrpcMxGatewayClientTransport(
    {
        return StreamAlarmsAsync(request, callOptions);
    }
    private static Exception MapRpcException(
        RpcException exception,
        CancellationToken cancellationToken)
    {
        if (cancellationToken.IsCancellationRequested || exception.StatusCode == StatusCode.Cancelled)
        {
            return new OperationCanceledException(
                exception.Status.Detail,
                exception,
                cancellationToken);
        }
        return exception.StatusCode switch
        {
            StatusCode.Unauthenticated => new MxGatewayAuthenticationException(
                exception.Status.Detail,
                innerException: exception),
            StatusCode.PermissionDenied => new MxGatewayAuthorizationException(
                exception.Status.Detail,
                innerException: exception),
            _ => new MxGatewayException(exception.Status.Detail, exception),
        };
    }
 }
@@ -1,7 +1,7 @@
 using Grpc.Core;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>Transport layer for Galaxy Repository gRPC operations.</summary>
 internal interface IGalaxyRepositoryClientTransport
@@ -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>
@@ -1,7 +1,7 @@
 using Grpc.Core;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 internal interface IMxGatewayClientTransport
 {
@@ -65,6 +65,17 @@ internal interface IMxGatewayClientTransport
        AcknowledgeAlarmRequest request,
        CallOptions callOptions);
    /// <summary>
    /// Streams a snapshot of all alarms currently in Active or ActiveAcked state — the
    /// ConditionRefresh equivalent for the gateway.
    /// </summary>
    /// <param name="request">The query request, optionally scoped by alarm-reference prefix.</param>
    /// <param name="callOptions">gRPC call options.</param>
    /// <returns>An async enumerable of active-alarm snapshots.</returns>
    IAsyncEnumerable<ActiveAlarmSnapshot> QueryActiveAlarmsAsync(
        QueryActiveAlarmsRequest request,
        CallOptions callOptions);
    /// <summary>
    /// Attaches to the gateway's central alarm feed — the current active-alarm
    /// snapshot followed by live transitions.
@@ -0,0 +1,101 @@
 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;
    private readonly List<LazyBrowseNode> _children = [];
    private readonly SemaphoreSlim _expandLock = new(1, 1);
    private 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 => _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.
    /// </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;
            }
            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));
            _isExpanded = true;
        }
        finally
        {
            _expandLock.Release();
        }
    }
 }
@@ -1,6 +1,6 @@
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>Exception thrown when an MXAccess command fails with a non-zero HResult or failing status.</summary>
 public sealed class MxAccessException : MxGatewayCommandException
@@ -1,6 +1,6 @@
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>Extension methods for checking MxCommandReply success conditions.</summary>
 public static class MxCommandReplyExtensions
@@ -1,7 +1,6 @@
-using Grpc.Core;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using MxGateway.Contracts.Proto;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>Exception thrown when an API key is invalid, expired, or malformed.</summary>
 public sealed class MxGatewayAuthenticationException : MxGatewayException
@@ -14,7 +13,6 @@ public sealed class MxGatewayAuthenticationException : MxGatewayException
    /// <param name="hResult">The HResult code, if available.</param>
    /// <param name="statuses">The MXAccess statuses, if available.</param>
    /// <param name="innerException">The underlying exception, if any.</param>
    /// <param name="statusCode">The gRPC status code reported by the failed call, if available.</param>
    public MxGatewayAuthenticationException(
        string message,
        string? sessionId = null,
@@ -22,8 +20,7 @@ public sealed class MxGatewayAuthenticationException : MxGatewayException
        ProtocolStatus? protocolStatus = null,
        int? hResult = null,
        IReadOnlyList<MxStatusProxy>? statuses = null,
-        Exception? innerException = null,
+        Exception? innerException = null)
        StatusCode? statusCode = null)
        : base(
            message,
            sessionId,
@@ -31,8 +28,7 @@ public sealed class MxGatewayAuthenticationException : MxGatewayException
            protocolStatus,
            hResult,
            statuses ?? [],
-            innerException,
+            innerException)
            statusCode)
    {
    }
 }
@@ -1,7 +1,6 @@
-using Grpc.Core;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using MxGateway.Contracts.Proto;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>Exception thrown when the API key lacks required scopes for an operation.</summary>
 public sealed class MxGatewayAuthorizationException : MxGatewayException
@@ -14,7 +13,6 @@ public sealed class MxGatewayAuthorizationException : MxGatewayException
    /// <param name="hResult">The HResult code, if available.</param>
    /// <param name="statuses">The MXAccess statuses, if available.</param>
    /// <param name="innerException">The underlying exception, if any.</param>
    /// <param name="statusCode">The gRPC status code reported by the failed call, if available.</param>
    public MxGatewayAuthorizationException(
        string message,
        string? sessionId = null,
@@ -22,8 +20,7 @@ public sealed class MxGatewayAuthorizationException : MxGatewayException
        ProtocolStatus? protocolStatus = null,
        int? hResult = null,
        IReadOnlyList<MxStatusProxy>? statuses = null,
-        Exception? innerException = null,
+        Exception? innerException = null)
        StatusCode? statusCode = null)
        : base(
            message,
            sessionId,
@@ -31,8 +28,7 @@ public sealed class MxGatewayAuthorizationException : MxGatewayException
            protocolStatus,
            hResult,
            statuses ?? [],
-            innerException,
+            innerException)
            statusCode)
    {
    }
 }
@@ -1,13 +1,13 @@
 using Grpc.Core;
 using Grpc.Net.Client;
 using Microsoft.Extensions.Logging;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using Polly;
 using System.Net.Http;
 using System.Net.Security;
 using System.Security.Cryptography.X509Certificates;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>
 /// Provides the .NET client entry point for the public MXAccess Gateway gRPC API.
@@ -17,7 +17,7 @@ public sealed class MxGatewayClient : IAsyncDisposable
    private readonly GrpcChannel _channel;
    private readonly IMxGatewayClientTransport _transport;
    private readonly ResiliencePipeline _safeUnaryRetryPipeline;
-    private int _disposed;
+    private bool _disposed;
    /// <summary>
    /// Initializes a new instance of the <see cref="MxGatewayClient"/> with given options and transport.
@@ -184,10 +184,9 @@ public sealed class MxGatewayClient : IAsyncDisposable
    /// <summary>
    /// Acknowledges an active MXAccess alarm condition through the gateway. The
-    /// gateway authorizes <see cref="AcknowledgeAlarmRequest"/> against the API
+    /// gateway authenticates the request against the API key's <c>invoke:alarm-ack</c>
-    /// key's <c>admin</c> scope (there is no finer-grained alarm-ack sub-scope)
+    /// scope and forwards the acknowledge to the worker's MXAccess session;
-    /// and forwards the acknowledge to the worker's MXAccess session; the
+    /// the resulting <see cref="MxStatusProxy"/> is returned in the reply.
    /// resulting <see cref="MxStatusProxy"/> is returned in the reply.
    /// </summary>
    /// <param name="request">The acknowledge request — alarm reference, comment, operator user.</param>
    /// <param name="cancellationToken">Cancellation token for the operation.</param>
@@ -204,6 +203,27 @@ public sealed class MxGatewayClient : IAsyncDisposable
            cancellationToken);
    }
    /// <summary>
    /// Streams a snapshot of all alarms currently Active or ActiveAcked — the gateway's
    /// ConditionRefresh equivalent. Used after reconnect to seed the local Part 9 state
    /// machine, or to reconcile alarms that may have been missed during a transport
    /// blip. Optionally scoped by alarm-reference prefix
    /// (<see cref="QueryActiveAlarmsRequest.AlarmFilterPrefix"/>) so a partial refresh
    /// can target an equipment sub-tree.
    /// </summary>
    /// <param name="request">The query request, optionally scoped by alarm-reference prefix.</param>
    /// <param name="cancellationToken">Cancellation token for the stream.</param>
    /// <returns>An async enumerable of active-alarm snapshots.</returns>
    public IAsyncEnumerable<ActiveAlarmSnapshot> QueryActiveAlarmsAsync(
        QueryActiveAlarmsRequest request,
        CancellationToken cancellationToken = default)
    {
        ArgumentNullException.ThrowIfNull(request);
        ThrowIfDisposed();
        return _transport.QueryActiveAlarmsAsync(request, CreateStreamCallOptions(cancellationToken));
    }
    /// <summary>
    /// Attaches to the gateway's central alarm feed. The stream opens with one
    /// <see cref="AlarmFeedMessage"/> per currently-active alarm (the
@@ -231,11 +251,12 @@ public sealed class MxGatewayClient : IAsyncDisposable
    /// </summary>
    public ValueTask DisposeAsync()
    {
-        if (Interlocked.Exchange(ref _disposed, 1) != 0)
+        if (_disposed)
        {
            return ValueTask.CompletedTask;
        }
        _disposed = true;
        _channel?.Dispose();
        return ValueTask.CompletedTask;
    }
@@ -294,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()
        {
@@ -314,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;
@@ -329,6 +358,10 @@ public sealed class MxGatewayClient : IAsyncDisposable
                    return customChain.Build(certificateToValidate);
                };
            }
            else if (!options.RequireCertificateValidation)
            {
                handler.SslOptions.RemoteCertificateValidationCallback = (_, _, _, _) => true;
            }
        }
        return handler;
@@ -336,6 +369,6 @@ public sealed class MxGatewayClient : IAsyncDisposable
    private void ThrowIfDisposed()
    {
-        ObjectDisposedException.ThrowIf(Volatile.Read(ref _disposed) != 0, this);
+        ObjectDisposedException.ThrowIf(_disposed, this);
    }
 }
@@ -0,0 +1,17 @@
 using ZB.MOM.WW.MxGateway.Contracts;
 namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>
 /// Exposes the protocol versions compiled into this client package.
 /// </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;
 }
@@ -1,6 +1,6 @@
 using Microsoft.Extensions.Logging;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>
 /// Configures the gRPC channel used by the .NET MXAccess Gateway client.
@@ -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>
@@ -38,12 +46,7 @@ public sealed class MxGatewayClientOptions
    public TimeSpan ConnectTimeout { get; init; } = TimeSpan.FromSeconds(10);
    /// <summary>
-    /// Gets the timeout budget for a unary gRPC operation. This is both the gRPC
+    /// Gets the default timeout for unary gRPC calls.
    /// deadline stamped on each individual attempt and the overall budget for the
    /// whole safe-unary operation: for retryable calls the initial attempt, every
    /// retry, and the backoff delays between them all share this single budget.
    /// It is therefore an upper bound on the total wall-clock time a safe-unary
    /// call can take, not a fresh per-retry allowance.
    /// </summary>
    public TimeSpan DefaultCallTimeout { get; init; } = TimeSpan.FromSeconds(30);
@@ -53,9 +56,7 @@ public sealed class MxGatewayClientOptions
    public TimeSpan? StreamTimeout { get; init; }
    /// <summary>
-    /// Gets the maximum size, in bytes, of a single gRPC message the client will
+    /// Gets the maximum size in bytes for gRPC messages.
    /// send or receive. Applied to both the send and receive limits of the
    /// underlying channel. Defaults to 16 MiB.
    /// </summary>
    public int MaxGrpcMessageBytes { get; init; } = 16 * 1024 * 1024;
@@ -1,4 +1,4 @@
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>Configuration for automatic retry behavior on transient gRPC call failures.</summary>
 public sealed class MxGatewayClientRetryOptions
@@ -1,10 +1,10 @@
 using Grpc.Core;
 using Microsoft.Extensions.Logging;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using Polly;
 using Polly.Retry;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>Factory and helpers for exponential-backoff retry policies on transient gRPC failures.</summary>
 internal static class MxGatewayClientRetryPolicy
@@ -61,13 +61,8 @@ internal static class MxGatewayClientRetryPolicy
    private static bool IsTransientStatus(StatusCode statusCode)
    {
        // DeadlineExceeded is intentionally NOT treated as transient. The deadline
        // on every unary call is client-imposed (CreateCallOptions stamps the
        // DefaultCallTimeout budget), and that same budget is shared across the
        // initial attempt plus all retries plus backoff. A DeadlineExceeded means
        // the shared budget is exhausted, so an immediate retry would only fail
        // again — burning the remaining budget on a call that cannot succeed.
        return statusCode is StatusCode.Unavailable
            or StatusCode.DeadlineExceeded
            or StatusCode.ResourceExhausted;
    }
 }
@@ -1,6 +1,6 @@
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>Exception thrown when a gateway command fails due to an unclassified protocol error.</summary>
 public class MxGatewayCommandException : MxGatewayException
@@ -1,7 +1,6 @@
-using Grpc.Core;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using MxGateway.Contracts.Proto;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>
 /// Exception thrown when a gateway RPC call fails or returns an error status.
@@ -29,20 +28,6 @@ public class MxGatewayException : Exception
        Statuses = [];
    }
    /// <summary>
    /// Initializes a new instance of the MxGatewayException class carrying the originating
    /// gRPC status code so callers can distinguish transient from permanent failures.
    /// </summary>
    /// <param name="message">Diagnostic message describing the failure.</param>
    /// <param name="statusCode">The gRPC status code reported by the failed call.</param>
    /// <param name="innerException">Underlying exception that caused this failure.</param>
    public MxGatewayException(string message, StatusCode statusCode, Exception? innerException)
        : base(message, innerException)
    {
        StatusCode = statusCode;
        Statuses = [];
    }
    /// <summary>
    /// Initializes a new instance of the MxGatewayException class with full diagnostic information.
    /// </summary>
@@ -53,7 +38,6 @@ public class MxGatewayException : Exception
    /// <param name="hResult">HRESULT code returned by the worker or MXAccess, if available.</param>
    /// <param name="statuses">List of MXAccess status codes returned by the operation.</param>
    /// <param name="innerException">Underlying exception that caused this failure.</param>
    /// <param name="statusCode">The gRPC status code reported by the failed call, if available.</param>
    public MxGatewayException(
        string message,
        string? sessionId,
@@ -61,8 +45,7 @@ public class MxGatewayException : Exception
        ProtocolStatus? protocolStatus,
        int? hResult,
        IReadOnlyList<MxStatusProxy> statuses,
-        Exception? innerException = null,
+        Exception? innerException = null)
        StatusCode? statusCode = null)
        : base(message, innerException)
    {
        SessionId = sessionId;
@@ -70,7 +53,6 @@ public class MxGatewayException : Exception
        ProtocolStatus = protocolStatus;
        HResultCode = hResult;
        Statuses = statuses;
        StatusCode = statusCode;
    }
    /// <summary>
@@ -97,15 +79,4 @@ public class MxGatewayException : Exception
    /// Gets the list of MXAccess status codes returned by the operation.
    /// </summary>
    public IReadOnlyList<MxStatusProxy> Statuses { get; }
    /// <summary>
    /// Gets the gRPC status code reported by the failed call, if the failure originated
    /// from a gRPC <see cref="RpcException"/>. <see langword="null"/> when the exception
    /// was not produced from a gRPC status (for example, a protocol-level reply failure).
    /// Callers can inspect this to distinguish a transient outage
    /// (<see cref="Grpc.Core.StatusCode.Unavailable"/>) from a permanent error
    /// (<see cref="Grpc.Core.StatusCode.InvalidArgument"/>) without downcasting
    /// <see cref="Exception.InnerException"/>.
    /// </summary>
    public StatusCode? StatusCode { get; }
 }
@@ -1,6 +1,6 @@
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>
 /// Represents one gateway-backed MXAccess session.
@@ -9,10 +9,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
 {
    private readonly MxGatewayClient _client;
    private readonly SemaphoreSlim _closeLock = new(1, 1);
    private readonly object _disposeGate = new();
    private CloseSessionReply? _closeReply;
    private int _activeCloseCount;
    private bool _closeLockDisposed;
    /// <summary>
    /// Initializes a new session backed by the given MXAccess gateway client.
@@ -49,42 +46,23 @@ public sealed class MxGatewaySession : IAsyncDisposable
            return _closeReply;
        }
-        // Register as an in-flight closer under the dispose gate. DisposeAsync waits for
+        await _closeLock.WaitAsync(cancellationToken).ConfigureAwait(false);
        // _activeCloseCount to drain before disposing the close lock, so the semaphore is
        // guaranteed to outlive every WaitAsync started here.
        lock (_disposeGate)
        {
            ObjectDisposedException.ThrowIf(_closeLockDisposed, this);
            _activeCloseCount++;
        }
        try
        {
-            await _closeLock.WaitAsync(cancellationToken).ConfigureAwait(false);
+            if (_closeReply is not null)
            try
            {
                if (_closeReply is not null)
                {
                    return _closeReply;
                }
                _closeReply = await _client.CloseSessionRawAsync(
                        new CloseSessionRequest { SessionId = SessionId },
                        cancellationToken)
                    .ConfigureAwait(false);
                return _closeReply;
            }
-            finally
+
-            {
+            _closeReply = await _client.CloseSessionRawAsync(
-                _closeLock.Release();
+                    new CloseSessionRequest { SessionId = SessionId },
-            }
+                    cancellationToken)
                .ConfigureAwait(false);
            return _closeReply;
        }
        finally
        {
-            lock (_disposeGate)
+            _closeLock.Release();
            {
                _activeCloseCount--;
            }
        }
    }
@@ -101,8 +79,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
        MxCommandReply reply = await RegisterRawAsync(clientName, cancellationToken)
            .ConfigureAwait(false);
        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
-        return reply.Register?.ServerHandle
+        return reply.Register?.ServerHandle ?? reply.ReturnValue.Int32Value;
            ?? throw CreateMissingPayloadException(reply, "register");
    }
    /// <summary>
@@ -144,8 +121,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
                cancellationToken)
            .ConfigureAwait(false);
        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
-        return reply.AddItem?.ItemHandle
+        return reply.AddItem?.ItemHandle ?? reply.ReturnValue.Int32Value;
            ?? throw CreateMissingPayloadException(reply, "add_item");
    }
    /// <summary>
@@ -196,8 +172,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
                cancellationToken)
            .ConfigureAwait(false);
        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
-        return reply.AddItem2?.ItemHandle
+        return reply.AddItem2?.ItemHandle ?? reply.ReturnValue.Int32Value;
            ?? throw CreateMissingPayloadException(reply, "add_item2");
    }
    /// <summary>
@@ -529,10 +504,14 @@ public sealed class MxGatewaySession : IAsyncDisposable
    /// <summary>
    /// Bulk Write — sequential MXAccess Write per entry on the worker's STA.
-    /// Per-item failures appear as BulkWriteResult entries with
+    /// Per-item failures appear as <see cref="BulkWriteResult"/> entries with
    /// <c>WasSuccessful = false</c>; the call never throws on per-item errors.
    /// Protocol-level failures still throw via EnsureProtocolSuccess.
    /// </summary>
    /// <param name="serverHandle">The ServerHandle from register.</param>
    /// <param name="entries">Per-item write entries; each carries the item handle, value, and user id.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>One <see cref="BulkWriteResult"/> per requested entry, in request order.</returns>
    public async Task<IReadOnlyList<BulkWriteResult>> WriteBulkAsync(
        int serverHandle,
        IReadOnlyList<WriteBulkEntry> entries,
@@ -555,7 +534,15 @@ public sealed class MxGatewaySession : IAsyncDisposable
        return reply.WriteBulk?.Results.ToArray() ?? [];
    }
-    /// <summary>Bulk Write2 — sequential MXAccess Write2 (timestamped) per entry.</summary>
+    /// <summary>
    /// Bulk Write2 — sequential MXAccess Write2 (timestamped) per entry.
    /// Per-item failures appear as <see cref="BulkWriteResult"/> entries with
    /// <c>WasSuccessful = false</c>; the call never throws on per-item errors.
    /// </summary>
    /// <param name="serverHandle">The ServerHandle from register.</param>
    /// <param name="entries">Per-item write entries; each carries the item handle, value, timestamp, and user id.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>One <see cref="BulkWriteResult"/> per requested entry, in request order.</returns>
    public async Task<IReadOnlyList<BulkWriteResult>> Write2BulkAsync(
        int serverHandle,
        IReadOnlyList<Write2BulkEntry> entries,
@@ -583,6 +570,10 @@ public sealed class MxGatewaySession : IAsyncDisposable
    /// Credential-sensitive values must never reach logs; the client mirrors
    /// the single-item WriteSecured redaction contract.
    /// </summary>
    /// <param name="serverHandle">The ServerHandle from register.</param>
    /// <param name="entries">Per-item write entries; each carries the item handle, value, current user id, and verifier user id.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>One <see cref="BulkWriteResult"/> per requested entry, in request order.</returns>
    public async Task<IReadOnlyList<BulkWriteResult>> WriteSecuredBulkAsync(
        int serverHandle,
        IReadOnlyList<WriteSecuredBulkEntry> entries,
@@ -605,7 +596,14 @@ public sealed class MxGatewaySession : IAsyncDisposable
        return reply.WriteSecuredBulk?.Results.ToArray() ?? [];
    }
-    /// <summary>Bulk WriteSecured2 — sequential MXAccess WriteSecured2 (timestamped) per entry.</summary>
+    /// <summary>
    /// Bulk WriteSecured2 — sequential MXAccess WriteSecured2 (timestamped) per entry.
    /// Same redaction rules as <see cref="WriteSecuredBulkAsync"/>.
    /// </summary>
    /// <param name="serverHandle">The ServerHandle from register.</param>
    /// <param name="entries">Per-item write entries; each carries the item handle, value, timestamp, current user id, and verifier user id.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>One <see cref="BulkWriteResult"/> per requested entry, in request order.</returns>
    public async Task<IReadOnlyList<BulkWriteResult>> WriteSecured2BulkAsync(
        int serverHandle,
        IReadOnlyList<WriteSecured2BulkEntry> entries,
@@ -631,11 +629,17 @@ public sealed class MxGatewaySession : IAsyncDisposable
    /// <summary>
    /// Bulk Read — snapshot the current value for each requested tag.
    /// Returns the cached OnDataChange value when the tag is already advised
-    /// (was_cached = true), otherwise the worker takes the full AddItem +
+    /// (<c>WasCached = true</c>), otherwise the worker takes the full AddItem +
    /// Advise + wait + UnAdvise + RemoveItem snapshot lifecycle. Per-tag
-    /// failures (timeout, invalid tag) appear as BulkReadResult entries with
+    /// failures (timeout, invalid tag) appear as <see cref="BulkReadResult"/>
-    /// <c>WasSuccessful = false</c>; the call never throws on per-tag errors.
+    /// entries with <c>WasSuccessful = false</c>; the call never throws on
    /// per-tag errors.
    /// </summary>
    /// <param name="serverHandle">The ServerHandle from register.</param>
    /// <param name="tagAddresses">Tag addresses to read (one per result).</param>
    /// <param name="timeout">Per-call timeout for the snapshot lifecycle path; <see cref="TimeSpan.Zero"/> uses the gateway default.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>One <see cref="BulkReadResult"/> per requested tag, in request order.</returns>
    public async Task<IReadOnlyList<BulkReadResult>> ReadBulkAsync(
        int serverHandle,
        IReadOnlyList<string> tagAddresses,
@@ -819,32 +823,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
    /// </summary>
    public async ValueTask DisposeAsync()
    {
        lock (_disposeGate)
        {
            if (_closeLockDisposed)
            {
                return;
            }
        }
        await CloseAsync().ConfigureAwait(false);
        // Wait for every concurrent CloseAsync caller to leave the close lock before
        // disposing it; once _closeReply is set those callers return without awaiting.
        while (true)
        {
            lock (_disposeGate)
            {
                if (_activeCloseCount == 0)
                {
                    _closeLockDisposed = true;
                    break;
                }
            }
            await Task.Yield();
        }
        _closeLock.Dispose();
    }
@@ -862,21 +841,4 @@ public sealed class MxGatewaySession : IAsyncDisposable
            cancellationToken);
    }
    /// <summary>
    /// Builds the exception thrown when a command reply passed protocol and
    /// MXAccess success checks but is missing the typed handle-bearing payload
    /// the command contract requires. Surfacing this as a clear error avoids
    /// silently handing a zero handle to the caller (it would otherwise fall
    /// through to <see cref="MxCommandReply.ReturnValue"/>, which is 0 when the
    /// reply carries no return value).
    /// </summary>
    private static MxGatewayException CreateMissingPayloadException(
        MxCommandReply reply,
        string expectedPayload)
    {
        return new MxGatewayException(
            $"Gateway reply for command kind={reply.Kind} reported success but is missing "
            + $"the required '{expectedPayload}' payload; cannot resolve a handle. "
            + $"session={reply.SessionId}; correlation={reply.CorrelationId}");
    }
 }
@@ -1,6 +1,6 @@
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>Exception thrown when a session is not found, not ready, or invalid.</summary>
 public sealed class MxGatewaySessionException : MxGatewayException
@@ -1,6 +1,6 @@
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>Exception thrown when the worker process is unavailable or fails to process a command.</summary>
 public sealed class MxGatewayWorkerException : MxGatewayException
@@ -1,6 +1,6 @@
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>Extension methods for MxStatusProxy values.</summary>
 public static class MxStatusProxyExtensions
@@ -1,8 +1,8 @@
 using Google.Protobuf;
 using Google.Protobuf.WellKnownTypes;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 /// <summary>
 /// Creates and projects gateway MXAccess values without hiding the raw
@@ -0,0 +1,3 @@
 using System.Runtime.CompilerServices;
 [assembly: InternalsVisibleTo("ZB.MOM.WW.MxGateway.Client.Tests")]
@@ -0,0 +1,36 @@
 <Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <ProjectReference Include="..\..\..\src\ZB.MOM.WW.MxGateway.Contracts\ZB.MOM.WW.MxGateway.Contracts.csproj" />
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Grpc.Net.Client" Version="2.76.0" />
    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.7" />
    <PackageReference Include="Polly.Core" Version="8.6.6" />
  </ItemGroup>
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <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>
  </PropertyGroup>
  <ItemGroup>
    <None Include="..\README.md" Pack="true" PackagePath="\" />
  </ItemGroup>
  <ItemGroup>
    <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
      <_Parameter1>ZB.MOM.WW.MxGateway.Client.Tests</_Parameter1>
    </AssemblyAttribute>
  </ItemGroup>
 </Project>
@@ -27,6 +27,9 @@ clients/go/
  internal/generated/
    mxaccess_gateway.pb.go
    mxaccess_gateway_grpc.pb.go
    galaxy_repository.pb.go
    galaxy_repository_grpc.pb.go
    mxaccess_worker.pb.go
  cmd/mxgw-go/
    main.go
  tests/
@@ -104,6 +107,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:
@@ -75,42 +75,29 @@ 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`, the full bulk family
+`AddItem`, `AddItem2`, `Advise`, `Write`, `Events`, and `Close`. Prefer
 (`AddItemBulk`, `AdviseItemBulk`, `RemoveItemBulk`, `UnAdviseItemBulk`,
 `SubscribeBulk`, `UnsubscribeBulk`, `WriteBulk`, `Write2Bulk`,
 `WriteSecuredBulk`, `WriteSecured2Bulk`, `ReadBulk`), `Events`, and
 `Close`. Bulk variants carry a list of entries in one round-trip and
 return one result per entry; per-entry MXAccess failures appear as
 `was_successful = false` and never return as Go errors. `ReadBulk` accepts
 a `time.Duration` per-tag timeout and returns cached `OnDataChange`
 values when the tag is already advised (`WasCached = true`) without
 touching the existing subscription. Prefer
 `SubscribeEvents` or `SubscribeEventsAfter` for long-running streams because the
 returned subscription owns cancellation and exposes `Close` for deterministic
-goroutine cleanup. `Events` and `EventsAfter` are a compatibility shim with a
+goroutine cleanup. Raw protobuf messages remain available through the
 bounded internal buffer: if the consumer drains too slowly the buffer fills,
 the underlying stream is cancelled, and a terminal `EventResult` carrying
 `ErrEventBufferOverflow` is delivered as the channel's last item before it
 closes — so a slow consumer can distinguish dropped events from a normal
 end-of-stream. `SubscribeEvents` blocks instead of dropping, so use it when no
 events may be lost. Raw protobuf messages remain available through the
 `mxgateway` package aliases and the `Raw` helper methods. Typed errors support
 `errors.As` for `GatewayError`, `CommandError`, and `MxAccessError`; command
 errors preserve the raw reply.
-`Dial` and `DialGalaxy` create the connection lazily (`grpc.NewClient`): a
+For alarms, the package exposes `Client.QueryActiveAlarms` for one-shot
-gateway that is briefly unavailable no longer turns into a hard error — the
+snapshots, `Client.StreamAlarms` for the server-streaming feed, and
-connection recovers once the gateway comes up. To keep fail-fast behavior,
+`Client.AcknowledgeAlarm` to ack an alarm by full reference. The streaming
-both run a readiness probe bounded by `DialTimeout` (default 10s, or the
+call returns a `StreamAlarmsClient`; cancel its context to terminate the
-context deadline when sooner) and return a `*GatewayError` if the gateway
+stream. All three pass straight through to the gateway's central alarm
-cannot be reached in that window.
+monitor.
 For retry, timeout, and auth handling, `GatewayError.Code()` exposes the
 wrapped gRPC `codes.Code`, and `mxgateway.IsTransient(err)` reports whether a
 failure (`Unavailable`, `DeadlineExceeded`, `ResourceExhausted`, `Aborted`)
 may succeed on retry — so callers do not have to unwrap the error and call
 `status.Code` themselves.
 ## Galaxy Repository browse
@@ -142,6 +129,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"
 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
@@ -186,8 +235,7 @@ The CLI exposes the same RPC via `galaxy-watch`:
 ```powershell
 go run ./cmd/mxgw-go galaxy-watch -plaintext
 go run ./cmd/mxgw-go galaxy-watch -plaintext -json
-go run ./cmd/mxgw-go galaxy-watch -plaintext -last-seen-deploy-time 2026-04-28T10:00:00Z      # whole-second RFC 3339
+go run ./cmd/mxgw-go galaxy-watch -plaintext -last-seen-deploy-time 2026-04-28T10:00:00Z
 go run ./cmd/mxgw-go galaxy-watch -plaintext -last-seen-deploy-time 2026-04-28T10:00:00.123Z  # fractional seconds also accepted
 go run ./cmd/mxgw-go galaxy-watch -plaintext -limit 5
 ```
@@ -235,6 +283,38 @@ $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.0
 ````
 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 use `GONOSUMCHECK` + `GOPRIVATE` to bypass the checksum database
 for the internal module path.
 ## 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)
@@ -351,17 +351,17 @@ func runUnsubscribeBulk(ctx context.Context, args []string, stdout, stderr io.Wr
 		return errors.New("session-id and item-handles are required")
 	}
 	handles, err := parseInt32List(*itemHandles)
 	if err != nil {
 		return err
 	}
 	client, options, err := dialForCommand(ctx, common)
 	if err != nil {
 		return err
 	}
 	defer client.Close()
 	handles, err := parseInt32List(*itemHandles)
 	if err != nil {
 		return err
 	}
 	session := mxgateway.NewSessionForID(client, *sessionID)
 	results, err := session.UnsubscribeBulk(ctx, int32(*serverHandle), handles)
 	return writeBulkOutput(stdout, *jsonOutput, "unsubscribe-bulk", options, results, err)
@@ -412,14 +412,15 @@ func runWriteSecured2Bulk(ctx context.Context, args []string, stdout, stderr io.
 }
 // runWriteBulkVariant shares the flag-parsing + entry-build skeleton across
-// the four bulk-write families. command selects which of the four routes
+// the four bulk-write families. The variant is derived from command alone;
-// runs; withTimestamp adds a --timestamp-value flag for the Write2 / Secured2
+// withTimestamp adds a --timestamp-value flag. To keep wrong-variant flags
-// variants. Secured-only flags (--current-user-id / --verifier-user-id) are
+// from silently no-op'ing, secured-only flags (-current-user-id /
-// only registered for the secured variants and the non-secured -user-id flag
+// -verifier-user-id) are only registered for the secured variants, and
-// is only registered for Write/Write2, so a wrong-variant flag becomes a
+// -user-id only for the non-secured Write/Write2 variants — a wrong-variant
-// clean "flag provided but not defined" error instead of silently no-op'ing.
+// flag then surfaces as a clean "flag provided but not defined" error.
 func runWriteBulkVariant(ctx context.Context, args []string, stdout, stderr io.Writer, command string, withTimestamp bool) error {
 	secured := command == "write-secured-bulk" || command == "write-secured2-bulk"
 	flags := flag.NewFlagSet(command, flag.ContinueOnError)
 	flags.SetOutput(stderr)
 	common := bindCommonFlags(flags)
@@ -429,7 +430,11 @@ func runWriteBulkVariant(ctx context.Context, args []string, stdout, stderr io.W
 	itemHandles := flags.String("item-handles", "", "comma-separated item handles")
 	valueType := flags.String("type", "string", "value type: bool, int32, int64, float, double, string")
 	values := flags.String("values", "", "comma-separated values (one per item handle)")
-	var userID, currentUserID, verifierUserID *int
+	var (
 		userID         *int
 		currentUserID  *int
 		verifierUserID *int
 	)
 	if secured {
 		currentUserID = flags.Int("current-user-id", 0, "MXAccess current user id (Secured variants)")
 		verifierUserID = flags.Int("verifier-user-id", 0, "MXAccess verifier user id (Secured variants)")
@@ -526,6 +531,16 @@ func runWriteBulkVariant(ctx context.Context, args []string, stdout, stderr io.W
 	return writeWriteBulkOutput(stdout, *jsonOutput, command, options, results, err)
 }
 // parseRfc3339Timestamp parses an RFC 3339 timestamp and returns the
 // MxValue protobuf representation used for the timestamped write families.
 func parseRfc3339Timestamp(text string) (*mxgateway.MxValue, error) {
 	t, err := time.Parse(time.RFC3339Nano, text)
 	if err != nil {
 		return nil, fmt.Errorf("invalid RFC 3339 timestamp %q: %w", text, err)
 	}
 	return mxgateway.TimestampValue(t), nil
 }
 // runBenchReadBulk drives the cross-language ReadBulk stress benchmark from Go:
 // opens its own session, subscribes to bulk-size tags so the worker value cache
 // populates from real OnDataChange events, runs ReadBulk in a tight loop for
@@ -596,19 +611,16 @@ func runBenchReadBulk(ctx context.Context, args []string, stdout, stderr io.Writ
 	}()
 	// Warm-up: drive identical calls so any first-call JIT / connection-pool
-	// setup is amortised before the measurement window opens. Honor ctx so
+	// setup is amortised before the measurement window opens. The ctx.Err()
-	// Ctrl+C or a parent-cancel (e.g. the cross-language bench driver killing
+	// guard short-circuits on Ctrl+C / parent-cancel instead of spinning
-	// the child early) exits promptly rather than spinning failing calls until
+	// failing ReadBulk calls until the wall-clock deadline elapses.
 	// the wall-clock deadline.
 	warmupDeadline := time.Now().Add(time.Duration(*warmupSeconds) * time.Second)
 	timeout := time.Duration(*timeoutMs) * time.Millisecond
 	for time.Now().Before(warmupDeadline) && ctx.Err() == nil {
 		_, _ = session.ReadBulk(ctx, serverHandle, tags, timeout)
 	}
-	// Steady state: per-call latency captured via time.Now() deltas. Same ctx
+	// Steady state: per-call latency captured via time.Now() deltas.
 	// guard as warm-up; on cancel we stop the loop and report the truncated
 	// window faithfully.
 	latenciesMs := make([]float64, 0, 65536)
 	var totalReadResults int64
 	var cachedReadResults int64
@@ -676,7 +688,7 @@ func percentileSummary(sample []float64) map[string]float64 {
 	sorted := append([]float64(nil), sample...)
 	sort.Float64s(sorted)
 	mean := 0.0
-	max := sorted[len(sorted)-1]
+	maxValue := sorted[len(sorted)-1]
 	for _, v := range sample {
 		mean += v
 	}
@@ -685,7 +697,7 @@ func percentileSummary(sample []float64) map[string]float64 {
 		"p50":  roundTo(percentile(sorted, 0.50), 3),
 		"p95":  roundTo(percentile(sorted, 0.95), 3),
 		"p99":  roundTo(percentile(sorted, 0.99), 3),
-		"max":  roundTo(max, 3),
+		"max":  roundTo(maxValue, 3),
 		"mean": roundTo(mean, 3),
 	}
 }
@@ -717,16 +729,6 @@ func roundTo(value float64, digits int) float64 {
 	return float64(int64(value*shift+0.5)) / shift
 }
 // parseRfc3339Timestamp parses an RFC 3339 timestamp and returns the
 // MxValue protobuf representation used for the timestamped write families.
 func parseRfc3339Timestamp(text string) (*mxgateway.MxValue, error) {
 	t, err := time.Parse(time.RFC3339Nano, text)
 	if err != nil {
 		return nil, fmt.Errorf("invalid RFC 3339 timestamp %q: %w", text, err)
 	}
 	return mxgateway.TimestampValue(t), nil
 }
 func runWrite(ctx context.Context, args []string, stdout, stderr io.Writer) error {
 	flags := flag.NewFlagSet("write", flag.ContinueOnError)
 	flags.SetOutput(stderr)
@@ -784,15 +786,8 @@ func runStreamEvents(ctx context.Context, args []string, stdout, stderr io.Write
 	}
 	defer client.Close()
 	// Mirror runGalaxyWatch so 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() actually run.
 	signalCtx, stopSignals := signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)
 	defer stopSignals()
 	session := mxgateway.NewSessionForID(client, *sessionID)
-	streamCtx, cancelStream := context.WithCancel(signalCtx)
+	streamCtx, cancelStream := context.WithCancel(ctx)
 	defer cancelStream()
 	subscription, err := session.SubscribeEventsAfter(streamCtx, *after)
 	if err != nil {
@@ -1088,31 +1083,31 @@ func parseValue(valueType, valueText string) (*mxgateway.MxValue, error) {
 	case "bool":
 		value, err := strconv.ParseBool(valueText)
 		if err != nil {
-			return nil, fmt.Errorf("invalid -value for -type %s: %q: %w", valueType, valueText, err)
+			return nil, err
 		}
 		return mxgateway.BoolValue(value), nil
 	case "int32":
 		value, err := strconv.ParseInt(valueText, 10, 32)
 		if err != nil {
-			return nil, fmt.Errorf("invalid -value for -type %s: %q: %w", valueType, valueText, err)
+			return nil, err
 		}
 		return mxgateway.Int32Value(int32(value)), nil
 	case "int64":
 		value, err := strconv.ParseInt(valueText, 10, 64)
 		if err != nil {
-			return nil, fmt.Errorf("invalid -value for -type %s: %q: %w", valueType, valueText, err)
+			return nil, err
 		}
 		return mxgateway.Int64Value(value), nil
 	case "float":
 		value, err := strconv.ParseFloat(valueText, 32)
 		if err != nil {
-			return nil, fmt.Errorf("invalid -value for -type %s: %q: %w", valueType, valueText, err)
+			return nil, err
 		}
 		return mxgateway.FloatValue(float32(value)), nil
 	case "double":
 		value, err := strconv.ParseFloat(valueText, 64)
 		if err != nil {
-			return nil, fmt.Errorf("invalid -value for -type %s: %q: %w", valueType, valueText, err)
+			return nil, err
 		}
 		return mxgateway.DoubleValue(value), nil
 	case "string":
@@ -1200,6 +1195,10 @@ type protojsonMessage interface {
 	ProtoReflect() protoreflect.Message
 }
 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>")
 }
 // batchEOR is the end-of-result sentinel emitted to stdout after every command
 // in batch mode, regardless of success or failure.
 const batchEOR = "__MXGW_BATCH_EOR__"
@@ -1207,18 +1206,28 @@ const batchEOR = "__MXGW_BATCH_EOR__"
 // runBatch reads one command line at a time from in, dispatches each via the
 // normal runWithIO routing, and writes a batchEOR sentinel to stdout after
 // every result. Errors are serialised as JSON to stdout (not stderr) so the
-// harness can parse them without interleaving stderr. The loop never terminates
+// harness can parse them without interleaving stderr. Blank lines are
-// on command error; only stdin EOF (or an empty line) ends the session.
+// skipped; only stdin EOF ends the session.
 //
 // The scanner buffer is widened to 16 MiB so a single long command line
 // (e.g. a bulk-write with several thousand handles) does not trip the
 // default 64 KiB bufio.Scanner token-too-long error and abort the session.
 // If a line still exceeds the cap, the error is surfaced as a per-command
 // error-with-sentinel and the session continues.
 func runBatch(ctx context.Context, in io.Reader, stdout, stderr io.Writer) error {
 	bw := bufio.NewWriter(stdout)
 	scanner := bufio.NewScanner(in)
-	for scanner.Scan() {
+	scanner.Buffer(make([]byte, 0, 64*1024), 16*1024*1024)
-		line := scanner.Text()
+	for {
-		if line == "" {
+		if !scanner.Scan() {
 			break
 		}
 		line := scanner.Text()
 		args := strings.Fields(line)
 		if len(args) == 0 {
 			// Skip blank / whitespace-only lines; do NOT terminate. The
 			// session ends only on stdin EOF so a stray blank line in a
 			// PowerShell here-string does not silently drop later commands.
 			continue
 		}
 		if err := runWithIO(ctx, args, bw, stderr); err != nil {
@@ -1233,11 +1242,21 @@ func runBatch(ctx context.Context, in io.Reader, stdout, stderr io.Writer) error
 		_, _ = fmt.Fprintln(bw, batchEOR)
 		_ = bw.Flush()
 	}
-	return scanner.Err()
+	if err := scanner.Err(); err != nil {
-}
+		// Emit the scanner failure as a final error-with-sentinel so the
-
+		// harness sees the failure framed, then return the error so the
-func writeUsage(writer io.Writer) {
+		// process exit reflects it. This handles bufio.ErrTooLong for any
-	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>")
+		// pathological line above the 16 MiB cap.
 		errPayload := map[string]string{
 			"error": err.Error(),
 			"type":  "error",
 		}
 		_ = writeJSON(bw, errPayload)
 		_, _ = fmt.Fprintln(bw, batchEOR)
 		_ = bw.Flush()
 		return err
 	}
 	return nil
 }
 func dialGalaxyForCommand(ctx context.Context, common *commonOptions) (*mxgateway.GalaxyClient, commonOptions, error) {
@@ -1369,7 +1388,7 @@ func runGalaxyWatch(ctx context.Context, args []string, stdout, stderr io.Writer
 	flags.SetOutput(stderr)
 	common := bindCommonFlags(flags)
 	jsonOutput := flags.Bool("json", false, "write JSON output")
-	lastSeen := flags.String("last-seen-deploy-time", "", "RFC 3339 timestamp (with optional fractional seconds); when set, suppresses the bootstrap event")
+	lastSeen := flags.String("last-seen-deploy-time", "", "RFC3339 timestamp; when set, suppresses the bootstrap event")
 	limit := flags.Int("limit", 0, "maximum events to read; 0 means unbounded (Ctrl+C to stop)")
 	if err := flags.Parse(args); err != nil {
@@ -1378,11 +1397,7 @@ func runGalaxyWatch(ctx context.Context, args []string, stdout, stderr io.Writer
 	var lastSeenPtr *time.Time
 	if *lastSeen != "" {
-		// Use RFC3339Nano so values copy-pasted from galaxy-watch -json output
+		parsed, err := time.Parse(time.RFC3339, *lastSeen)
 		// (which formatDeployEvent emits with fractional seconds) round-trip;
 		// RFC3339Nano also accepts whole-second values, so the layout switch is
 		// strictly broader than the previous time.RFC3339 parse.
 		parsed, err := time.Parse(time.RFC3339Nano, *lastSeen)
 		if err != nil {
 			return fmt.Errorf("invalid -last-seen-deploy-time: %w", err)
 		}
@@ -1425,9 +1440,6 @@ func runGalaxyWatch(ctx context.Context, args []string, stdout, stderr io.Writer
 			count++
 			if *limit > 0 && count >= *limit {
 				cancelStream()
 				// Allow goroutine to drain.
 				for range events {
 				}
 				return nil
 			}
 		case streamErr, ok := <-errs:
@@ -2,10 +2,15 @@ package main
 import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"errors"
+	"net"
 	"strings"
 	"testing"
 	"time"
 	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
 	"google.golang.org/grpc"
 )
 func TestRunVersionJSON(t *testing.T) {
@@ -48,6 +53,34 @@ func TestCommonOptionsRedactsAPIKey(t *testing.T) {
 	}
 }
 func TestRunBatchEmitsEORAfterVersion(t *testing.T) {
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
 	in := strings.NewReader("version --json\n")
 	if err := runBatch(t.Context(), in, &stdout, &stderr); err != nil {
 		t.Fatalf("runBatch() error = %v; stderr = %s", err, stderr.String())
 	}
 	out := stdout.String()
 	if !strings.Contains(out, "\n"+batchEOR+"\n") && !strings.HasSuffix(out, batchEOR+"\n") {
 		t.Fatalf("expected EOR marker %q in stdout; got: %q", batchEOR, out)
 	}
 	idx := strings.Index(out, batchEOR)
 	if idx <= 0 {
 		t.Fatalf("EOR marker not found or appeared before any output: %q", out)
 	}
 	payload := out[:idx]
 	var output versionOutput
 	if err := json.Unmarshal([]byte(payload), &output); err != nil {
 		t.Fatalf("parse JSON block before EOR: %v (payload=%q)", err, payload)
 	}
 	if output.GatewayProtocolVersion == 0 || output.WorkerProtocolVersion == 0 {
 		t.Fatalf("protocol versions were not populated: %+v", output)
 	}
 }
 func TestParseValueBuildsTypedValue(t *testing.T) {
 	value, err := parseValue("int32", "123")
 	if err != nil {
@@ -58,194 +91,206 @@ func TestParseValueBuildsTypedValue(t *testing.T) {
 	}
 }
-func TestParseInt32ListParsesValidTokens(t *testing.T) {
+// TestRunWriteBulkVariantGatesSecuredFlags pins the Client.Go-022 fix:
-	items, err := parseInt32List("1, 2 ,3")
+// secured-only flags must be unavailable on non-secured variants, and
-	if err != nil {
+// vice-versa, so a wrong-variant flag fails with a clean "flag provided
-		t.Fatalf("parseInt32List() error = %v", err)
+// but not defined" error instead of silently no-op'ing.
 	}
 	want := []int32{1, 2, 3}
 	if len(items) != len(want) {
 		t.Fatalf("parseInt32List() = %v, want %v", items, want)
 	}
 	for i := range want {
 		if items[i] != want[i] {
 			t.Fatalf("parseInt32List()[%d] = %d, want %d", i, items[i], want[i])
 		}
 	}
 }
 func TestParseInt32ListReturnsErrorOnMalformedToken(t *testing.T) {
 	items, err := parseInt32List("1,foo")
 	if err == nil {
 		t.Fatalf("parseInt32List() error = nil, want a parse error; items = %v", items)
 	}
 	if items != nil {
 		t.Fatalf("parseInt32List() items = %v, want nil on error", items)
 	}
 	if !strings.Contains(err.Error(), "foo") {
 		t.Fatalf("parseInt32List() error = %q, want it to name the bad token", err.Error())
 	}
 }
 // TestParseValueWrapsStrconvErrorWithFlagContext pins Client.Go-017: each
 // typed branch of parseValue wraps the bare strconv error with `%w` and names
 // the offending flag and value, so the CLI surface is consistent with
 // parseInt32List ("invalid item handle %q: %w") and parseRfc3339Timestamp
 // ("invalid RFC 3339 timestamp %q: %w").
 func TestParseValueWrapsStrconvErrorWithFlagContext(t *testing.T) {
 	cases := []struct {
 		valueType string
 		valueText string
 	}{
 		{"bool", "notabool"},
 		{"int32", "foo"},
 		{"int64", "foo"},
 		{"float", "notafloat"},
 		{"double", "notadouble"},
 	}
 	for _, tc := range cases {
 		t.Run(tc.valueType, func(t *testing.T) {
 			_, err := parseValue(tc.valueType, tc.valueText)
 			if err == nil {
 				t.Fatalf("parseValue(%q, %q) error = nil, want a parse error", tc.valueType, tc.valueText)
 			}
 			msg := err.Error()
 			if !strings.Contains(msg, "-value") {
 				t.Fatalf("parseValue() error = %q, want it to name the -value flag", msg)
 			}
 			if !strings.Contains(msg, tc.valueType) {
 				t.Fatalf("parseValue() error = %q, want it to name the type %q", msg, tc.valueType)
 			}
 			if !strings.Contains(msg, tc.valueText) {
 				t.Fatalf("parseValue() error = %q, want it to name the bad token %q", msg, tc.valueText)
 			}
 			// errors.Unwrap must reach the underlying strconv error so callers
 			// can still errors.Is/As against strconv.ErrSyntax if they care.
 			if errors.Unwrap(err) == nil {
 				t.Fatalf("parseValue() returned unwrapped error %q, want a %%w wrap", msg)
 			}
 		})
 	}
 }
 // TestRunWriteBulkVariantGatesSecuredFlags pins the Client.Go-015 fix at the
 // CLI surface: secured-only flags (-current-user-id, -verifier-user-id) must
 // not be registered on the non-secured variants, and -user-id must not be
 // registered on the secured variants. The flag package rejects an unknown
 // flag with "flag provided but not defined", which a future refactor that
 // re-broadens flag registration would silently undo without this test.
 func TestRunWriteBulkVariantGatesSecuredFlags(t *testing.T) {
 	cases := []struct {
 		name    string
 		command string
 		flag    string
 	}{
 		{"write-bulk rejects -current-user-id", "write-bulk", "-current-user-id"},
 		{"write-bulk rejects -verifier-user-id", "write-bulk", "-verifier-user-id"},
 		{"write2-bulk rejects -current-user-id", "write2-bulk", "-current-user-id"},
 		{"write-secured-bulk rejects -user-id", "write-secured-bulk", "-user-id"},
 		{"write-secured2-bulk rejects -user-id", "write-secured2-bulk", "-user-id"},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
 			var stdout, stderr bytes.Buffer
 			err := runWithIO(t.Context(), []string{
 				tc.command,
 				"-plaintext",
 				"-session-id", "sess",
 				"-server-handle", "1",
 				"-item-handles", "1",
 				"-values", "1",
 				tc.flag, "1",
 			}, &stdout, &stderr)
 			if err == nil {
 				t.Fatalf("runWithIO(%s %s) error = nil, want flag-not-defined", tc.command, tc.flag)
 			}
 			combined := err.Error() + stderr.String()
 			if !strings.Contains(combined, "flag provided but not defined") {
 				t.Fatalf("runWithIO(%s %s) error/stderr = %q, want 'flag provided but not defined'", tc.command, tc.flag, combined)
 			}
 		})
 	}
 }
 // TestRunReadBulkRejectsMissingArgs pins the "session-id and items are
 // required" validation in runReadBulk before any network dial happens.
 func TestRunReadBulkRejectsMissingArgs(t *testing.T) {
 	cases := []struct {
 		name string
 		args []string
 	}{
-		{"no flags", []string{"read-bulk"}},
+		{
-		{"missing items", []string{"read-bulk", "-plaintext", "-session-id", "sess"}},
+			name: "write-bulk-rejects-current-user-id",
-		{"missing session-id", []string{"read-bulk", "-plaintext", "-items", "Tag.Attr"}},
+			args: []string{"write-bulk", "-current-user-id", "5", "-item-handles", "1", "-values", "1"},
 		},
 		{
 			name: "write-bulk-rejects-verifier-user-id",
 			args: []string{"write-bulk", "-verifier-user-id", "5", "-item-handles", "1", "-values", "1"},
 		},
 		{
 			name: "write2-bulk-rejects-current-user-id",
 			args: []string{"write2-bulk", "-current-user-id", "5", "-item-handles", "1", "-values", "1"},
 		},
 		{
 			name: "write-secured-bulk-rejects-user-id",
 			args: []string{"write-secured-bulk", "-user-id", "5", "-item-handles", "1", "-values", "1"},
 		},
 		{
 			name: "write-secured2-bulk-rejects-user-id",
 			args: []string{"write-secured2-bulk", "-user-id", "5", "-item-handles", "1", "-values", "1"},
 		},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
 			var stdout, stderr bytes.Buffer
 			err := runWithIO(t.Context(), tc.args, &stdout, &stderr)
 			if err == nil {
-				t.Fatalf("runWithIO(%v) error = nil, want validation error", tc.args)
+				t.Fatalf("runWithIO(%v) returned no error", tc.args)
 			}
-			if !strings.Contains(err.Error(), "session-id and items are required") {
+			if !strings.Contains(err.Error(), "flag provided but not defined") {
-				t.Fatalf("runWithIO(%v) error = %q, want 'session-id and items are required'", tc.args, err.Error())
+				t.Fatalf("runWithIO(%v) error = %v; want 'flag provided but not defined'", tc.args, err)
 			}
 		})
 	}
 }
-// TestRunBenchReadBulkRejectsNonPositiveBulkSize pins the bulk-size>=1 check
+// TestRunBenchReadBulkRespectsContextCancellation pins the Client.Go-023
-// at runBenchReadBulk's flag-parsing stage so a future refactor cannot drop
+// fix: the warm-up and steady-state wall-clock loops must honour ctx.Err()
-// the positivity guard without breaking this test.
+// so an external cancel (Ctrl+C, parent-cancel from a cross-language bench
 // driver) short-circuits the bench instead of spinning failing ReadBulk
 // calls until the wall-clock deadline elapses.
 func TestRunBenchReadBulkRespectsContextCancellation(t *testing.T) {
 	listener, err := net.Listen("tcp", "127.0.0.1:0")
 	if err != nil {
 		t.Fatalf("listen: %v", err)
 	}
 	server := grpc.NewServer()
 	fake := &benchFakeGateway{}
 	pb.RegisterMxAccessGatewayServer(server, fake)
 	go func() {
 		_ = server.Serve(listener)
 	}()
 	defer server.Stop()
 	defer listener.Close()
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 	// Long warm-up + duration, so if the ctx.Err() guard were missing the
 	// loops would run for ~10s. With the guard, the cancel below short-
 	// circuits both loops within ~one ReadBulk iteration.
 	args := []string{
 		"bench-read-bulk",
 		"-endpoint", listener.Addr().String(),
 		"-plaintext",
 		"-api-key", "test",
 		"-warmup-seconds", "5",
 		"-duration-seconds", "5",
 		"-bulk-size", "1",
 		"-timeout-ms", "100",
 	}
 	// Cancel after a brief delay — far less than warmup+duration (10s).
 	go func() {
 		time.Sleep(150 * time.Millisecond)
 		cancel()
 	}()
 	var stdout, stderr bytes.Buffer
 	start := time.Now()
 	err = runWithIO(ctx, args, &stdout, &stderr)
 	elapsed := time.Since(start)
 	// With the ctx.Err() guard, the loops exit well before the wall-clock
 	// deadlines (warmup=5s + duration=5s = 10s). Allow generous slack for
 	// CI noise but assert clearly less than the un-guarded worst case.
 	if elapsed > 4*time.Second {
 		t.Fatalf("bench-read-bulk took %s after ctx cancel; want <4s (ctx.Err() guard missing?). err=%v stderr=%s", elapsed, err, stderr.String())
 	}
 }
 // benchFakeGateway is a minimal MxAccessGatewayServer that satisfies the
 // bench-read-bulk session-setup sequence (OpenSession + Invoke for Register
 // / SubscribeBulk / ReadBulk / UnsubscribeBulk / CloseSession).
 type benchFakeGateway struct {
 	pb.UnimplementedMxAccessGatewayServer
 }
 func (g *benchFakeGateway) OpenSession(_ context.Context, _ *pb.OpenSessionRequest) (*pb.OpenSessionReply, error) {
 	return &pb.OpenSessionReply{
 		SessionId:      "bench-session",
 		ProtocolStatus: &pb.ProtocolStatus{Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK},
 	}, nil
 }
 func (g *benchFakeGateway) CloseSession(_ context.Context, req *pb.CloseSessionRequest) (*pb.CloseSessionReply, error) {
 	return &pb.CloseSessionReply{
 		SessionId:      req.GetSessionId(),
 		ProtocolStatus: &pb.ProtocolStatus{Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK},
 	}, nil
 }
 func (g *benchFakeGateway) Invoke(_ context.Context, req *pb.MxCommandRequest) (*pb.MxCommandReply, error) {
 	kind := req.GetCommand().GetKind()
 	reply := &pb.MxCommandReply{
 		SessionId:      req.GetSessionId(),
 		Kind:           kind,
 		ProtocolStatus: &pb.ProtocolStatus{Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK},
 	}
 	switch kind {
 	case pb.MxCommandKind_MX_COMMAND_KIND_REGISTER:
 		reply.Payload = &pb.MxCommandReply_Register{Register: &pb.RegisterReply{ServerHandle: 1}}
 	case pb.MxCommandKind_MX_COMMAND_KIND_SUBSCRIBE_BULK:
 		reply.Payload = &pb.MxCommandReply_SubscribeBulk{SubscribeBulk: &pb.BulkSubscribeReply{
 			Results: []*pb.SubscribeResult{{ServerHandle: 1, ItemHandle: 1, WasSuccessful: true}},
 		}}
 	case pb.MxCommandKind_MX_COMMAND_KIND_READ_BULK:
 		reply.Payload = &pb.MxCommandReply_ReadBulk{ReadBulk: &pb.BulkReadReply{
 			Results: []*pb.BulkReadResult{{ItemHandle: 1, WasSuccessful: true, WasCached: true}},
 		}}
 	case pb.MxCommandKind_MX_COMMAND_KIND_UNSUBSCRIBE_BULK:
 		reply.Payload = &pb.MxCommandReply_UnsubscribeBulk{UnsubscribeBulk: &pb.BulkSubscribeReply{}}
 	}
 	return reply, nil
 }
 // TestRunBenchReadBulkRejectsNonPositiveBulkSize pins the Client.Go-023-adjacent
 // positivity checks so they cannot drift while resolving the cancellation finding.
 func TestRunBenchReadBulkRejectsNonPositiveBulkSize(t *testing.T) {
 	var stdout, stderr bytes.Buffer
-	err := runWithIO(t.Context(), []string{
+	err := runWithIO(t.Context(), []string{"bench-read-bulk", "-bulk-size", "0"}, &stdout, &stderr)
-		"bench-read-bulk",
+	if err == nil || !strings.Contains(err.Error(), "bulk-size must be positive") {
-		"-plaintext",
+		t.Fatalf("bench-read-bulk -bulk-size 0 error = %v", err)
 		"-bulk-size", "0",
 	}, &stdout, &stderr)
 	if err == nil {
 		t.Fatalf("runWithIO(bench-read-bulk -bulk-size 0) error = nil, want positivity error")
 	}
 	if !strings.Contains(err.Error(), "bulk-size must be positive") {
 		t.Fatalf("runWithIO error = %q, want 'bulk-size must be positive'", err.Error())
 	}
 }
-// TestRunBenchReadBulkRejectsNonPositiveDuration pins the duration-seconds>=1
+// TestRunBatchSkipsBlankLinesAndContinuesUntilEOF pins the Client.Go-027 fix:
-// check at runBenchReadBulk's flag-parsing stage.
+// a blank line in the middle of a batch session must NOT terminate the loop —
-func TestRunBenchReadBulkRejectsNonPositiveDuration(t *testing.T) {
+// only stdin EOF ends the session.
 func TestRunBatchSkipsBlankLinesAndContinuesUntilEOF(t *testing.T) {
 	var stdout, stderr bytes.Buffer
-	err := runWithIO(t.Context(), []string{
+
-		"bench-read-bulk",
+	// version -> blank -> version (a stray blank line in the middle of a
-		"-plaintext",
+	// programmatic session).
-		"-duration-seconds", "0",
+	in := strings.NewReader("version --json\n\nversion --json\n")
-	}, &stdout, &stderr)
+	if err := runBatch(t.Context(), in, &stdout, &stderr); err != nil {
-	if err == nil {
+		t.Fatalf("runBatch() error = %v; stderr = %s", err, stderr.String())
 		t.Fatalf("runWithIO(bench-read-bulk -duration-seconds 0) error = nil, want positivity error")
 	}
-	if !strings.Contains(err.Error(), "duration-seconds must be positive") {
+
-		t.Fatalf("runWithIO error = %q, want 'duration-seconds must be positive'", err.Error())
+	out := stdout.String()
 	// Both version commands must have produced a result before the EOR sentinel.
 	if count := strings.Count(out, batchEOR); count != 2 {
 		t.Fatalf("EOR sentinel count = %d, want 2 (one per command, blank line skipped); out = %q", count, out)
 	}
 }
-// TestRunWriteBulkVariantRejectsMismatchedHandlesAndValues pins the explicit
+// TestRunBatchHandlesLongCommandLine pins the Client.Go-026 fix: a command
-// "item-handles count ... does not match values count ..." check at the CLI
+// line longer than the default bufio.Scanner token size (64 KiB) must not
-// surface so the validation error surfaces before any dial happens.
+// abort the batch session.
-func TestRunWriteBulkVariantRejectsMismatchedHandlesAndValues(t *testing.T) {
+func TestRunBatchHandlesLongCommandLine(t *testing.T) {
 	var stdout, stderr bytes.Buffer
-	err := runWithIO(t.Context(), []string{
+
-		"write-bulk",
+	// Build a single command line larger than 64 KiB. The command itself is
-		"-plaintext",
+	// invalid (no real session) but runBatch must still emit an EOR sentinel
-		"-session-id", "sess",
+	// and continue to the next command rather than dropping the line on the
-		"-server-handle", "1",
+	// floor with a bufio.ErrTooLong from the outer return.
-		"-item-handles", "1,2,3",
+	huge := strings.Repeat("tag-with-a-reasonably-long-name-and-suffix,", 2000) + "trailing"
-		"-values", "10,20",
+	line := "subscribe-bulk -session-id none -items " + huge
-	}, &stdout, &stderr)
+	if len(line) <= 64*1024 {
-	if err == nil {
+		t.Fatalf("test setup error: long line length = %d, want > 64KiB", len(line))
 		t.Fatalf("runWithIO(write-bulk mismatched counts) error = nil, want mismatch error")
 	}
-	if !strings.Contains(err.Error(), "item-handles count") || !strings.Contains(err.Error(), "values count") {
+	in := strings.NewReader(line + "\nversion --json\n")
-		t.Fatalf("runWithIO error = %q, want 'item-handles count ... values count ...'", err.Error())
+
 	if err := runBatch(t.Context(), in, &stdout, &stderr); err != nil {
 		t.Fatalf("runBatch() error = %v; stderr = %s", err, stderr.String())
 	}
 	out := stdout.String()
 	// Both commands must produce an EOR sentinel — the long line should be a
 	// per-command error (still emitted with EOR), then the version command
 	// should run normally.
 	if count := strings.Count(out, batchEOR); count != 2 {
 		t.Fatalf("EOR sentinel count = %d, want 2 (one per command, even when first is too long); out length = %d", count, len(out))
 	}
 }
@@ -2,7 +2,7 @@ Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
 $repoRoot = Resolve-Path (Join-Path $PSScriptRoot '..\..')
-$protoRoot = Join-Path $repoRoot 'src\MxGateway.Contracts\Protos'
+$protoRoot = Join-Path $repoRoot 'src\ZB.MOM.WW.MxGateway.Contracts\Protos'
 $outputRoot = Join-Path $PSScriptRoot 'internal\generated'
 $modulePath = 'gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated'
 $protoc = 'C:\Users\dohertj2\AppData\Local\Microsoft\WinGet\Packages\Google.Protobuf_Microsoft.Winget.Source_8wekyb3d8bbwe\bin\protoc.exe'
@@ -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 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
+	(*BrowseChildrenRequest)(nil),    // 10: galaxy_repository.v1.BrowseChildrenRequest
-	(*wrapperspb.Int32Value)(nil),    // 11: google.protobuf.Int32Value
+	(*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
+	12, // 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
+	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
+	12, // 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
+	12, // 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, // 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
+	8,  // 7: galaxy_repository.v1.BrowseChildrenReply.children:type_name -> galaxy_repository.v1.GalaxyObject
-	2,  // 8: galaxy_repository.v1.GalaxyRepository.GetLastDeployTime:input_type -> galaxy_repository.v1.GetLastDeployTimeRequest
+	0,  // 8: galaxy_repository.v1.GalaxyRepository.TestConnection:input_type -> galaxy_repository.v1.TestConnectionRequest
-	4,  // 9: galaxy_repository.v1.GalaxyRepository.DiscoverHierarchy:input_type -> galaxy_repository.v1.DiscoverHierarchyRequest
+	2,  // 9: galaxy_repository.v1.GalaxyRepository.GetLastDeployTime:input_type -> galaxy_repository.v1.GetLastDeployTimeRequest
-	6,  // 10: galaxy_repository.v1.GalaxyRepository.WatchDeployEvents:input_type -> galaxy_repository.v1.WatchDeployEventsRequest
+	4,  // 10: galaxy_repository.v1.GalaxyRepository.DiscoverHierarchy:input_type -> galaxy_repository.v1.DiscoverHierarchyRequest
-	1,  // 11: galaxy_repository.v1.GalaxyRepository.TestConnection:output_type -> galaxy_repository.v1.TestConnectionReply
+	6,  // 11: galaxy_repository.v1.GalaxyRepository.WatchDeployEvents:input_type -> galaxy_repository.v1.WatchDeployEventsRequest
-	3,  // 12: galaxy_repository.v1.GalaxyRepository.GetLastDeployTime:output_type -> galaxy_repository.v1.GetLastDeployTimeReply
+	10, // 12: galaxy_repository.v1.GalaxyRepository.BrowseChildren:input_type -> galaxy_repository.v1.BrowseChildrenRequest
-	5,  // 13: galaxy_repository.v1.GalaxyRepository.DiscoverHierarchy:output_type -> galaxy_repository.v1.DiscoverHierarchyReply
+	1,  // 13: galaxy_repository.v1.GalaxyRepository.TestConnection:output_type -> galaxy_repository.v1.TestConnectionReply
-	7,  // 14: galaxy_repository.v1.GalaxyRepository.WatchDeployEvents:output_type -> galaxy_repository.v1.DeployEvent
+	3,  // 14: galaxy_repository.v1.GalaxyRepository.GetLastDeployTime:output_type -> galaxy_repository.v1.GetLastDeployTimeReply
-	11, // [11:15] is the sub-list for method output_type
+	5,  // 15: galaxy_repository.v1.GalaxyRepository.DiscoverHierarchy:output_type -> galaxy_repository.v1.DiscoverHierarchyReply
-	7,  // [7:11] is the sub-list for method input_type
+	7,  // 16: galaxy_repository.v1.GalaxyRepository.WatchDeployEvents:output_type -> galaxy_repository.v1.DeployEvent
-	7,  // [7:7] is the sub-list for extension type_name
+	11, // 17: galaxy_repository.v1.GalaxyRepository.BrowseChildren:output_type -> galaxy_repository.v1.BrowseChildrenReply
-	7,  // [7:7] is the sub-list for extension extendee
+	13, // [13:18] is the sub-list for method output_type
-	0,  // [0:7] is the sub-list for field type_name
+	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,
 		},
@@ -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{
 		{
@@ -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
@@ -19,12 +19,13 @@ import (
 const _ = grpc.SupportPackageIsVersion9
 const (
-	MxAccessGateway_OpenSession_FullMethodName      = "/mxaccess_gateway.v1.MxAccessGateway/OpenSession"
+	MxAccessGateway_OpenSession_FullMethodName       = "/mxaccess_gateway.v1.MxAccessGateway/OpenSession"
-	MxAccessGateway_CloseSession_FullMethodName     = "/mxaccess_gateway.v1.MxAccessGateway/CloseSession"
+	MxAccessGateway_CloseSession_FullMethodName      = "/mxaccess_gateway.v1.MxAccessGateway/CloseSession"
-	MxAccessGateway_Invoke_FullMethodName           = "/mxaccess_gateway.v1.MxAccessGateway/Invoke"
+	MxAccessGateway_Invoke_FullMethodName            = "/mxaccess_gateway.v1.MxAccessGateway/Invoke"
-	MxAccessGateway_StreamEvents_FullMethodName     = "/mxaccess_gateway.v1.MxAccessGateway/StreamEvents"
+	MxAccessGateway_StreamEvents_FullMethodName      = "/mxaccess_gateway.v1.MxAccessGateway/StreamEvents"
-	MxAccessGateway_AcknowledgeAlarm_FullMethodName = "/mxaccess_gateway.v1.MxAccessGateway/AcknowledgeAlarm"
+	MxAccessGateway_AcknowledgeAlarm_FullMethodName  = "/mxaccess_gateway.v1.MxAccessGateway/AcknowledgeAlarm"
-	MxAccessGateway_StreamAlarms_FullMethodName     = "/mxaccess_gateway.v1.MxAccessGateway/StreamAlarms"
+	MxAccessGateway_StreamAlarms_FullMethodName      = "/mxaccess_gateway.v1.MxAccessGateway/StreamAlarms"
 	MxAccessGateway_QueryActiveAlarms_FullMethodName = "/mxaccess_gateway.v1.MxAccessGateway/QueryActiveAlarms"
 )
 // MxAccessGatewayClient is the client API for MxAccessGateway service.
@@ -44,6 +45,15 @@ type MxAccessGatewayClient interface {
 	// Served by the gateway's always-on alarm monitor; any number of clients
 	// fan out from the single monitor without opening a worker session.
 	StreamAlarms(ctx context.Context, in *StreamAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[AlarmFeedMessage], error)
 	// Point-in-time snapshot of the currently-active alarm set served from the
 	// gateway's always-on alarm monitor cache (session-less). Used after a
 	// 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)
 }
 type mxAccessGatewayClient struct {
@@ -132,6 +142,25 @@ func (c *mxAccessGatewayClient) StreamAlarms(ctx context.Context, in *StreamAlar
 // This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
 type MxAccessGateway_StreamAlarmsClient = grpc.ServerStreamingClient[AlarmFeedMessage]
 func (c *mxAccessGatewayClient) QueryActiveAlarms(ctx context.Context, in *QueryActiveAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[ActiveAlarmSnapshot], error) {
 	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
 	stream, err := c.cc.NewStream(ctx, &MxAccessGateway_ServiceDesc.Streams[2], MxAccessGateway_QueryActiveAlarms_FullMethodName, cOpts...)
 	if err != nil {
 		return nil, err
 	}
 	x := &grpc.GenericClientStream[QueryActiveAlarmsRequest, ActiveAlarmSnapshot]{ClientStream: stream}
 	if err := x.ClientStream.SendMsg(in); err != nil {
 		return nil, err
 	}
 	if err := x.ClientStream.CloseSend(); err != nil {
 		return nil, err
 	}
 	return x, nil
 }
 // This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
 type MxAccessGateway_QueryActiveAlarmsClient = grpc.ServerStreamingClient[ActiveAlarmSnapshot]
 // MxAccessGatewayServer is the server API for MxAccessGateway service.
 // All implementations must embed UnimplementedMxAccessGatewayServer
 // for forward compatibility.
@@ -149,6 +178,15 @@ type MxAccessGatewayServer interface {
 	// Served by the gateway's always-on alarm monitor; any number of clients
 	// fan out from the single monitor without opening a worker session.
 	StreamAlarms(*StreamAlarmsRequest, grpc.ServerStreamingServer[AlarmFeedMessage]) error
 	// Point-in-time snapshot of the currently-active alarm set served from the
 	// gateway's always-on alarm monitor cache (session-less). Used after a
 	// 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()
 }
@@ -177,6 +215,9 @@ func (UnimplementedMxAccessGatewayServer) AcknowledgeAlarm(context.Context, *Ack
 func (UnimplementedMxAccessGatewayServer) StreamAlarms(*StreamAlarmsRequest, grpc.ServerStreamingServer[AlarmFeedMessage]) error {
 	return status.Error(codes.Unimplemented, "method StreamAlarms not implemented")
 }
 func (UnimplementedMxAccessGatewayServer) QueryActiveAlarms(*QueryActiveAlarmsRequest, grpc.ServerStreamingServer[ActiveAlarmSnapshot]) error {
 	return status.Error(codes.Unimplemented, "method QueryActiveAlarms not implemented")
 }
 func (UnimplementedMxAccessGatewayServer) mustEmbedUnimplementedMxAccessGatewayServer() {}
 func (UnimplementedMxAccessGatewayServer) testEmbeddedByValue()                         {}
@@ -292,6 +333,17 @@ func _MxAccessGateway_StreamAlarms_Handler(srv interface{}, stream grpc.ServerSt
 // This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
 type MxAccessGateway_StreamAlarmsServer = grpc.ServerStreamingServer[AlarmFeedMessage]
 func _MxAccessGateway_QueryActiveAlarms_Handler(srv interface{}, stream grpc.ServerStream) error {
 	m := new(QueryActiveAlarmsRequest)
 	if err := stream.RecvMsg(m); err != nil {
 		return err
 	}
 	return srv.(MxAccessGatewayServer).QueryActiveAlarms(m, &grpc.GenericServerStream[QueryActiveAlarmsRequest, ActiveAlarmSnapshot]{ServerStream: stream})
 }
 // This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
 type MxAccessGateway_QueryActiveAlarmsServer = grpc.ServerStreamingServer[ActiveAlarmSnapshot]
 // MxAccessGateway_ServiceDesc is the grpc.ServiceDesc for MxAccessGateway service.
 // It's only intended for direct use with grpc.RegisterService,
 // and not to be introspected or modified (even as a copy)
@@ -327,6 +379,11 @@ var MxAccessGateway_ServiceDesc = grpc.ServiceDesc{
 			Handler:       _MxAccessGateway_StreamAlarms_Handler,
 			ServerStreams: true,
 		},
 		{
 			StreamName:    "QueryActiveAlarms",
 			Handler:       _MxAccessGateway_QueryActiveAlarms_Handler,
 			ServerStreams: true,
 		},
 	},
 	Metadata: "mxaccess_gateway.proto",
 }
@@ -1179,7 +1179,7 @@ const file_mxaccess_worker_proto_rawDesc = "" +
 	"\x1eWORKER_FAULT_CATEGORY_STA_HUNG\x10\t\x12(\n" +
 	"$WORKER_FAULT_CATEGORY_QUEUE_OVERFLOW\x10\n" +
 	"\x12*\n" +
-	"&WORKER_FAULT_CATEGORY_SHUTDOWN_TIMEOUT\x10\vB\x1c\xaa\x02\x19MxGateway.Contracts.Protob\x06proto3"
+	"&WORKER_FAULT_CATEGORY_SHUTDOWN_TIMEOUT\x10\vB&\xaa\x02#ZB.MOM.WW.MxGateway.Contracts.Protob\x06proto3"
 var (
 	file_mxaccess_worker_proto_rawDescOnce sync.Once
@@ -31,6 +31,27 @@ func (c *Client) AcknowledgeAlarm(ctx context.Context, req *AcknowledgeAlarmRequ
 	return reply, nil
 }
 // QueryActiveAlarms streams a snapshot of all alarms currently Active or
 // ActiveAcked — the gateway's ConditionRefresh equivalent. Used after reconnect
 // to seed local Part 9 state, or to reconcile alarms that may have been missed
 // during a transport blip.
 //
 // The returned stream is owned by the caller; cancel ctx to release it.
 // Optional alarm-reference prefix scoping (req.AlarmFilterPrefix) limits the
 // stream to a sub-tree.
 func (c *Client) QueryActiveAlarms(ctx context.Context, req *QueryActiveAlarmsRequest) (QueryActiveAlarmsClient, error) {
 	if req == nil {
 		return nil, errors.New("mxgateway: query active alarms request is required")
 	}
 	stream, err := c.raw.QueryActiveAlarms(ctx, req)
 	if err != nil {
 		return nil, &GatewayError{Op: "query active alarms", Err: err}
 	}
 	return stream, nil
 }
 // StreamAlarms attaches to the gateway's central alarm feed. The stream opens
 // with one AlarmFeedMessage per currently-active alarm (the ConditionRefresh
 // snapshot), then a single snapshot-complete sentinel, then a transition for
@@ -14,7 +14,8 @@ import (
 	"google.golang.org/grpc/test/bufconn"
 )
-// Pins the Go SDK surface for the alarm RPCs: AcknowledgeAlarm + StreamAlarms.
+// PR E.4 — pins the Go SDK surface for the new alarm RPCs:
 // AcknowledgeAlarm + QueryActiveAlarms.
 func TestAcknowledgeAlarmSendsRequestAndReturnsReply(t *testing.T) {
 	fake := &fakeGatewayWithAlarms{
@@ -61,6 +62,10 @@ func TestAcknowledgeAlarmRejectsNilRequest(t *testing.T) {
 	defer cleanup()
 	_, err := client.AcknowledgeAlarm(context.Background(), nil)
 	if err == nil || !errors.Is(err, errors.Unwrap(err)) && err.Error() != "mxgateway: acknowledge alarm request is required" {
 		// Accept either: the helper returned the literal sentinel, or the
 		// generic transport error — both prove nil was rejected.
 	}
 	if err == nil {
 		t.Fatalf("AcknowledgeAlarm(nil) returned no error")
 	}
@@ -89,7 +94,7 @@ func TestAcknowledgeAlarmMapsUnauthenticated(t *testing.T) {
 	}
 }
-func TestStreamAlarmsStreamsSnapshotThenSnapshotComplete(t *testing.T) {
+func TestQueryActiveAlarmsStreamsSnapshots(t *testing.T) {
 	fake := &fakeGatewayWithAlarms{
 		activeSnapshots: []*pb.ActiveAlarmSnapshot{
 			{
@@ -107,7 +112,86 @@ func TestStreamAlarmsStreamsSnapshotThenSnapshotComplete(t *testing.T) {
 	client, cleanup := newBufconnClientWithAlarms(t, fake)
 	defer cleanup()
-	stream, err := client.StreamAlarms(context.Background(), &pb.StreamAlarmsRequest{})
+	stream, err := client.QueryActiveAlarms(context.Background(), &pb.QueryActiveAlarmsRequest{
 		SessionId: "session-1",
 	})
 	if err != nil {
 		t.Fatalf("QueryActiveAlarms() error = %v", err)
 	}
 	var received []*pb.ActiveAlarmSnapshot
 	for {
 		snap, err := stream.Recv()
 		if errors.Is(err, io.EOF) {
 			break
 		}
 		if err != nil {
 			t.Fatalf("stream.Recv() error = %v", err)
 		}
 		received = append(received, snap)
 	}
 	if len(received) != 2 {
 		t.Fatalf("snapshot count = %d, want 2", len(received))
 	}
 	if received[0].GetAlarmFullReference() != "Tank01.Level.HiHi" {
 		t.Fatalf("snapshot[0] ref = %q", received[0].GetAlarmFullReference())
 	}
 	if received[1].GetCurrentState() != pb.AlarmConditionState_ALARM_CONDITION_STATE_ACTIVE_ACKED {
 		t.Fatalf("snapshot[1] state = %v", received[1].GetCurrentState())
 	}
 }
 func TestQueryActiveAlarmsPassesFilterPrefix(t *testing.T) {
 	fake := &fakeGatewayWithAlarms{}
 	client, cleanup := newBufconnClientWithAlarms(t, fake)
 	defer cleanup()
 	stream, err := client.QueryActiveAlarms(context.Background(), &pb.QueryActiveAlarmsRequest{
 		SessionId:         "session-1",
 		AlarmFilterPrefix: "Tank01.",
 	})
 	if err != nil {
 		t.Fatalf("QueryActiveAlarms() error = %v", err)
 	}
 	for {
 		_, err := stream.Recv()
 		if errors.Is(err, io.EOF) {
 			break
 		}
 		if err != nil {
 			t.Fatalf("stream.Recv() error = %v", err)
 		}
 	}
 	if got := fake.queryRequest.GetAlarmFilterPrefix(); got != "Tank01." {
 		t.Fatalf("captured filter prefix = %q", got)
 	}
 }
 func TestStreamAlarmsPassesFilterPrefixAndReceivesFeedMessages(t *testing.T) {
 	fake := &fakeGatewayWithAlarms{
 		feedMessages: []*pb.AlarmFeedMessage{
 			{
 				Payload: &pb.AlarmFeedMessage_ActiveAlarm{
 					ActiveAlarm: &pb.ActiveAlarmSnapshot{
 						AlarmFullReference: "Tank01.Level.HiHi",
 						CurrentState:       pb.AlarmConditionState_ALARM_CONDITION_STATE_ACTIVE,
 					},
 				},
 			},
 			{
 				Payload: &pb.AlarmFeedMessage_SnapshotComplete{
 					SnapshotComplete: true,
 				},
 			},
 		},
 	}
 	client, cleanup := newBufconnClientWithAlarms(t, fake)
 	defer cleanup()
 	stream, err := client.StreamAlarms(context.Background(), &pb.StreamAlarmsRequest{
 		AlarmFilterPrefix: "Tank01.",
 	})
 	if err != nil {
 		t.Fatalf("StreamAlarms() error = %v", err)
 	}
@@ -123,43 +207,24 @@ func TestStreamAlarmsStreamsSnapshotThenSnapshotComplete(t *testing.T) {
 		}
 		received = append(received, msg)
 	}
-	if len(received) != 3 {
+	if len(received) != 2 {
-		t.Fatalf("message count = %d, want 3", len(received))
+		t.Fatalf("received count = %d, want 2", len(received))
 	}
-	if received[0].GetActiveAlarm().GetAlarmFullReference() != "Tank01.Level.HiHi" {
+	if got := fake.streamRequest.GetAlarmFilterPrefix(); got != "Tank01." {
-		t.Fatalf("message[0] ref = %q", received[0].GetActiveAlarm().GetAlarmFullReference())
+		t.Fatalf("captured filter prefix = %q", got)
 	}
-	if received[1].GetActiveAlarm().GetCurrentState() != pb.AlarmConditionState_ALARM_CONDITION_STATE_ACTIVE_ACKED {
+	if got := fake.streamAuth; got != "Bearer test-api-key" {
-		t.Fatalf("message[1] state = %v", received[1].GetActiveAlarm().GetCurrentState())
+		t.Fatalf("stream authorization metadata = %q", got)
 	}
 	if !received[2].GetSnapshotComplete() {
 		t.Fatalf("final message is not snapshot_complete")
 	}
 }
-func TestStreamAlarmsPassesFilterPrefix(t *testing.T) {
+func TestStreamAlarmsRejectsNilRequest(t *testing.T) {
 	fake := &fakeGatewayWithAlarms{}
 	client, cleanup := newBufconnClientWithAlarms(t, fake)
 	defer cleanup()
-	stream, err := client.StreamAlarms(context.Background(), &pb.StreamAlarmsRequest{
+	if _, err := client.StreamAlarms(context.Background(), nil); err == nil {
-		AlarmFilterPrefix: "Tank01.",
+		t.Fatal("StreamAlarms(nil) returned no error")
 	})
 	if err != nil {
 		t.Fatalf("StreamAlarms() error = %v", err)
 	}
 	for {
 		_, err := stream.Recv()
 		if errors.Is(err, io.EOF) {
 			break
 		}
 		if err != nil {
 			t.Fatalf("stream.Recv() error = %v", err)
 		}
 	}
 	if got := fake.streamRequest.GetAlarmFilterPrefix(); got != "Tank01." {
 		t.Fatalf("captured filter prefix = %q", got)
 	}
 }
@@ -171,8 +236,12 @@ type fakeGatewayWithAlarms struct {
 	acknowledgeError   error
 	acknowledgeAuth    string
-	streamRequest   *pb.StreamAlarmsRequest
+	queryRequest    *pb.QueryActiveAlarmsRequest
 	activeSnapshots []*pb.ActiveAlarmSnapshot
 	streamRequest *pb.StreamAlarmsRequest
 	feedMessages  []*pb.AlarmFeedMessage
 	streamAuth    string
 }
 func (s *fakeGatewayWithAlarms) AcknowledgeAlarm(ctx context.Context, req *pb.AcknowledgeAlarmRequest) (*pb.AcknowledgeAlarmReply, error) {
@@ -185,24 +254,32 @@ func (s *fakeGatewayWithAlarms) AcknowledgeAlarm(ctx context.Context, req *pb.Ac
 		return s.acknowledgeReply, nil
 	}
 	return &pb.AcknowledgeAlarmReply{
 		CorrelationId: req.GetClientCorrelationId(),
 		ProtocolStatus: &pb.ProtocolStatus{
 			Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
 		},
 	}, nil
 }
-func (s *fakeGatewayWithAlarms) StreamAlarms(req *pb.StreamAlarmsRequest, stream grpc.ServerStreamingServer[pb.AlarmFeedMessage]) error {
+func (s *fakeGatewayWithAlarms) QueryActiveAlarms(req *pb.QueryActiveAlarmsRequest, stream grpc.ServerStreamingServer[pb.ActiveAlarmSnapshot]) error {
-	s.streamRequest = req
+	s.queryRequest = req
 	for _, snap := range s.activeSnapshots {
-		if err := stream.Send(&pb.AlarmFeedMessage{
+		if err := stream.Send(snap); err != nil {
 			Payload: &pb.AlarmFeedMessage_ActiveAlarm{ActiveAlarm: snap},
 		}); err != nil {
 			return err
 		}
 	}
-	return stream.Send(&pb.AlarmFeedMessage{
+	return nil
-		Payload: &pb.AlarmFeedMessage_SnapshotComplete{SnapshotComplete: true},
+}
-	})
+
 func (s *fakeGatewayWithAlarms) StreamAlarms(req *pb.StreamAlarmsRequest, stream grpc.ServerStreamingServer[pb.AlarmFeedMessage]) error {
 	s.streamRequest = req
 	s.streamAuth = authorizationFromContext(stream.Context())
 	for _, msg := range s.feedMessages {
 		if err := stream.Send(msg); err != nil {
 			return err
 		}
 	}
 	return nil
 }
 func newBufconnClientWithAlarms(t *testing.T, fake *fakeGatewayWithAlarms) (*Client, func()) {
@@ -216,10 +293,8 @@ func newBufconnClientWithAlarms(t *testing.T, fake *fakeGatewayWithAlarms) (*Cli
 	dialer := func(ctx context.Context, _ string) (net.Conn, error) {
 		return listener.DialContext(ctx)
 	}
 	// grpc.NewClient defaults to the dns scheme; use passthrough so the
 	// bufconn fake target reaches the context dialer unresolved.
 	client, err := Dial(context.Background(), Options{
-		Endpoint:    "passthrough:///bufnet",
+		Endpoint:    "bufnet",
 		APIKey:      "test-api-key",
 		Plaintext:   true,
 		DialOptions: []grpc.DialOption{grpc.WithContextDialer(dialer)},
@@ -19,7 +19,6 @@ import (
 	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/connectivity"
 	"google.golang.org/grpc/credentials"
 	"google.golang.org/grpc/credentials/insecure"
 	"google.golang.org/protobuf/types/known/durationpb"
@@ -37,36 +36,22 @@ type Client struct {
 	opts Options
 }
-// Dial opens a gRPC connection to the gateway and configures auth metadata
+// Dial opens a gRPC connection to the gateway and configures auth metadata,
-// and transport security.
+// transport security, and blocking dial cancellation from ctx.
 //
 // The connection is created lazily with grpc.NewClient: the channel is not
 // established until the first RPC (or the readiness probe below) needs it, so
 // a gateway that is briefly unavailable at Dial time no longer turns into a
 // hard error — the connection recovers when the gateway comes up. To preserve
 // fail-fast behavior, Dial then runs an explicit readiness probe bounded by
 // DialTimeout (default 10s, or ctx's deadline when sooner): it triggers the
 // initial connect and waits for the channel to reach Ready, returning a
 // *GatewayError if the gateway cannot be reached in that window. Cancelling
 // ctx aborts the probe.
 func Dial(ctx context.Context, opts Options) (*Client, error) {
 	conn, err := dial(ctx, opts)
 	if err != nil {
 		return nil, err
 	}
 	return NewClient(conn, opts), nil
 }
 // dial builds the shared gRPC connection used by both Client and GalaxyClient:
 // it resolves transport credentials, assembles dial options, creates a lazy
 // connection with grpc.NewClient, and runs the DialTimeout-bounded readiness
 // probe so callers still fail fast when the gateway is unreachable.
 func dial(ctx context.Context, opts Options) (*grpc.ClientConn, error) {
 	if opts.Endpoint == "" {
 		return nil, errors.New("mxgateway: endpoint is required")
 	}
 	dialCtx := ctx
 	cancel := func() {}
 	if opts.DialTimeout > 0 {
 		dialCtx, cancel = context.WithTimeout(ctx, opts.DialTimeout)
 	} else if _, ok := ctx.Deadline(); !ok {
 		dialCtx, cancel = context.WithTimeout(ctx, defaultDialTimeout)
 	}
 	defer cancel()
 	transportCredentials, err := resolveTransportCredentials(opts)
 	if err != nil {
 		return nil, err
@@ -76,46 +61,16 @@ func dial(ctx context.Context, opts Options) (*grpc.ClientConn, error) {
 		grpc.WithTransportCredentials(transportCredentials),
 		grpc.WithUnaryInterceptor(unaryAuthInterceptor(opts.APIKey)),
 		grpc.WithStreamInterceptor(streamAuthInterceptor(opts.APIKey)),
 		grpc.WithBlock(),
 	}
 	dialOptions = append(dialOptions, opts.DialOptions...)
-	conn, err := grpc.NewClient(opts.Endpoint, dialOptions...)
+	conn, err := grpc.DialContext(dialCtx, opts.Endpoint, dialOptions...)
 	if err != nil {
 		return nil, &GatewayError{Op: "dial", Err: err}
 	}
-	if err := waitForReady(ctx, conn, opts.DialTimeout); err != nil {
+	return NewClient(conn, opts), nil
 		_ = conn.Close()
 		return nil, &GatewayError{Op: "dial", Err: err}
 	}
 	return conn, nil
 }
 // waitForReady triggers the initial connect on conn and blocks until the
 // channel reaches connectivity.Ready, the timeout elapses, or ctx is
 // cancelled. The wait is bounded by dialTimeout when positive, otherwise by
 // ctx's existing deadline, otherwise by defaultDialTimeout.
 func waitForReady(ctx context.Context, conn *grpc.ClientConn, dialTimeout time.Duration) error {
 	probeCtx := ctx
 	cancel := func() {}
 	if dialTimeout > 0 {
 		probeCtx, cancel = context.WithTimeout(ctx, dialTimeout)
 	} else if _, ok := ctx.Deadline(); !ok {
 		probeCtx, cancel = context.WithTimeout(ctx, defaultDialTimeout)
 	}
 	defer cancel()
 	conn.Connect()
 	for {
 		state := conn.GetState()
 		if state == connectivity.Ready {
 			return nil
 		}
 		if !conn.WaitForStateChange(probeCtx, state) {
 			return probeCtx.Err()
 		}
 	}
 }
 // NewClient wraps an existing gRPC connection. The caller owns closing conn
@@ -233,15 +188,7 @@ func (c *Client) Close() error {
 }
 func (c *Client) callContext(ctx context.Context) (context.Context, context.CancelFunc) {
-	return callContext(ctx, c.opts.CallTimeout)
+	timeout := c.opts.CallTimeout
 }
 // callContext derives a per-RPC context from ctx, applying callTimeout: zero
 // uses defaultCallTimeout, a negative value disables the bound entirely, and a
 // caller-supplied deadline that is already sooner than the derived timeout is
 // kept as-is rather than being lengthened.
 func callContext(ctx context.Context, callTimeout time.Duration) (context.Context, context.CancelFunc) {
 	timeout := callTimeout
 	if timeout == 0 {
 		timeout = defaultCallTimeout
 	}
@@ -275,10 +222,22 @@ func resolveTransportCredentials(opts Options) (credentials.TransportCredentials
 		return credentials.NewTLS(cfg), nil
 	}
-	return credentials.NewTLS(&tls.Config{
+	return credentials.NewTLS(tlsConfigForOptions(opts)), nil
-		MinVersion: tls.VersionTLS12,
+}
-		ServerName: opts.ServerNameOverride,
+
-	}), 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.
@@ -117,7 +117,7 @@ func TestEventsAfterCancelsStreamWhenCompatibilityChannelIsAbandoned(t *testing.
 	fake := &fakeGatewayServer{
 		streamStarted:    make(chan struct{}),
 		streamDone:       make(chan struct{}),
-		streamEventCount: 256,
+		streamEventCount: 64,
 	}
 	client, cleanup := newBufconnClient(t, fake)
 	defer cleanup()
@@ -135,25 +135,12 @@ func TestEventsAfterCancelsStreamWhenCompatibilityChannelIsAbandoned(t *testing.
 		t.Fatal("compatibility event stream did not stop after result channel filled")
 	}
 	// A slow consumer that abandons the buffer must still receive an explicit
 	// terminal overflow error before the channel closes, so it can tell
 	// "events dropped" apart from "stream ended normally".
 	var sawOverflow bool
 	for {
 		select {
-		case result, ok := <-events:
+		case _, ok := <-events:
 			if !ok {
 				if !sawOverflow {
 					t.Fatal("compatibility event channel closed without an ErrEventBufferOverflow result")
 				}
 				return
 			}
 			if result.Err != nil {
 				if !errors.Is(result.Err, ErrEventBufferOverflow) {
 					t.Fatalf("terminal result error = %v, want ErrEventBufferOverflow", result.Err)
 				}
 				sawOverflow = true
 			}
 		case <-time.After(2 * time.Second):
 			t.Fatal("compatibility event channel did not close")
 		}
@@ -254,8 +241,8 @@ func TestWriteBulkBuildsOneBulkCommandAndReturnsPerEntryResults(t *testing.T) {
 			Payload: &pb.MxCommandReply_WriteBulk{
 				WriteBulk: &pb.BulkWriteReply{
 					Results: []*pb.BulkWriteResult{
-						{ServerHandle: 12, ItemHandle: 901, WasSuccessful: true},
+						{ItemHandle: 10, WasSuccessful: true},
-						{ServerHandle: 12, ItemHandle: 902, WasSuccessful: false, ErrorMessage: "invalid handle"},
+						{ItemHandle: 11, WasSuccessful: true},
 					},
 				},
 			},
@@ -265,22 +252,114 @@ func TestWriteBulkBuildsOneBulkCommandAndReturnsPerEntryResults(t *testing.T) {
 	defer cleanup()
 	session := NewSessionForID(client, "session-1")
-	results, err := session.WriteBulk(context.Background(), 12, []*pb.WriteBulkEntry{
+	entries := []*WriteBulkEntry{
-		{ItemHandle: 901, UserId: 5, Value: &pb.MxValue{DataType: pb.MxDataType_MX_DATA_TYPE_INTEGER, Kind: &pb.MxValue_Int32Value{Int32Value: 11}}},
+		{ItemHandle: 10, Value: Int32Value(7), UserId: 100},
-		{ItemHandle: 902, UserId: 5, Value: &pb.MxValue{DataType: pb.MxDataType_MX_DATA_TYPE_INTEGER, Kind: &pb.MxValue_Int32Value{Int32Value: 22}}},
+		{ItemHandle: 11, Value: Int32Value(8), UserId: 100},
-	})
+	}
 	results, err := session.WriteBulk(context.Background(), 12, entries)
 	if err != nil {
 		t.Fatalf("WriteBulk() error = %v", err)
 	}
-	if len(results) != 2 || !results[0].GetWasSuccessful() || results[1].GetWasSuccessful() {
+	if len(results) != 2 {
-		t.Fatalf("results = %#v, want [success, failure]", results)
+		t.Fatalf("results len = %d, want 2", len(results))
 	}
 	req := fake.invokeRequest
 	if req.GetCommand().GetKind() != pb.MxCommandKind_MX_COMMAND_KIND_WRITE_BULK {
 		t.Fatalf("command kind = %s", req.GetCommand().GetKind())
 	}
 	if got := req.GetCommand().GetWriteBulk().GetEntries(); len(got) != 2 {
-		t.Fatalf("entries = %#v, want 2", got)
+		t.Fatalf("entry count = %d, want 2", len(got))
 	}
 }
 func TestWriteBulkRejectsNilEntries(t *testing.T) {
 	fake := &fakeGatewayServer{}
 	client, cleanup := newBufconnClient(t, fake)
 	defer cleanup()
 	session := NewSessionForID(client, "session-1")
 	if _, err := session.WriteBulk(context.Background(), 12, nil); err == nil {
 		t.Fatal("WriteBulk(nil) returned no error")
 	}
 	if _, err := session.Write2Bulk(context.Background(), 12, nil); err == nil {
 		t.Fatal("Write2Bulk(nil) returned no error")
 	}
 	if _, err := session.WriteSecuredBulk(context.Background(), 12, nil); err == nil {
 		t.Fatal("WriteSecuredBulk(nil) returned no error")
 	}
 	if _, err := session.WriteSecured2Bulk(context.Background(), 12, nil); err == nil {
 		t.Fatal("WriteSecured2Bulk(nil) returned no error")
 	}
 	if _, err := session.ReadBulk(context.Background(), 12, nil, 0); err == nil {
 		t.Fatal("ReadBulk(nil) returned no error")
 	}
 }
 func TestBulkMethodsShortCircuitOnEmptySliceWithoutRoundTrip(t *testing.T) {
 	fake := &fakeGatewayServer{
 		invokeReply: &pb.MxCommandReply{
 			ProtocolStatus: &pb.ProtocolStatus{
 				Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
 			},
 		},
 	}
 	client, cleanup := newBufconnClient(t, fake)
 	defer cleanup()
 	session := NewSessionForID(client, "session-1")
 	results, err := session.WriteBulk(context.Background(), 12, []*WriteBulkEntry{})
 	if err != nil {
 		t.Fatalf("WriteBulk(empty) error = %v", err)
 	}
 	if len(results) != 0 {
 		t.Fatalf("WriteBulk(empty) results len = %d, want 0", len(results))
 	}
 	if fake.invokeRequest != nil {
 		t.Fatal("WriteBulk(empty) sent a round trip; expected short-circuit")
 	}
 	results2, err := session.Write2Bulk(context.Background(), 12, []*Write2BulkEntry{})
 	if err != nil {
 		t.Fatalf("Write2Bulk(empty) error = %v", err)
 	}
 	if len(results2) != 0 {
 		t.Fatalf("Write2Bulk(empty) results len = %d, want 0", len(results2))
 	}
 	if fake.invokeRequest != nil {
 		t.Fatal("Write2Bulk(empty) sent a round trip; expected short-circuit")
 	}
 	results3, err := session.WriteSecuredBulk(context.Background(), 12, []*WriteSecuredBulkEntry{})
 	if err != nil {
 		t.Fatalf("WriteSecuredBulk(empty) error = %v", err)
 	}
 	if len(results3) != 0 {
 		t.Fatalf("WriteSecuredBulk(empty) results len = %d, want 0", len(results3))
 	}
 	if fake.invokeRequest != nil {
 		t.Fatal("WriteSecuredBulk(empty) sent a round trip; expected short-circuit")
 	}
 	results4, err := session.WriteSecured2Bulk(context.Background(), 12, []*WriteSecured2BulkEntry{})
 	if err != nil {
 		t.Fatalf("WriteSecured2Bulk(empty) error = %v", err)
 	}
 	if len(results4) != 0 {
 		t.Fatalf("WriteSecured2Bulk(empty) results len = %d, want 0", len(results4))
 	}
 	if fake.invokeRequest != nil {
 		t.Fatal("WriteSecured2Bulk(empty) sent a round trip; expected short-circuit")
 	}
 	readResults, err := session.ReadBulk(context.Background(), 12, []string{}, 0)
 	if err != nil {
 		t.Fatalf("ReadBulk(empty) error = %v", err)
 	}
 	if len(readResults) != 0 {
 		t.Fatalf("ReadBulk(empty) results len = %d, want 0", len(readResults))
 	}
 	if fake.invokeRequest != nil {
 		t.Fatal("ReadBulk(empty) sent a round trip; expected short-circuit")
 	}
 }
@@ -295,14 +374,8 @@ func TestReadBulkForwardsTimeoutAndUnpacksCachedFlag(t *testing.T) {
 			Payload: &pb.MxCommandReply_ReadBulk{
 				ReadBulk: &pb.BulkReadReply{
 					Results: []*pb.BulkReadResult{
-						{
+						{TagAddress: "Tank01.Level", WasSuccessful: true, WasCached: true},
-							ServerHandle:  12,
+						{TagAddress: "Tank02.Level", WasSuccessful: true, WasCached: false},
 							TagAddress:    "Area001.Pump001.Speed",
 							ItemHandle:    34,
 							WasSuccessful: true,
 							WasCached:     true,
 							Value:         &pb.MxValue{DataType: pb.MxDataType_MX_DATA_TYPE_INTEGER, Kind: &pb.MxValue_Int32Value{Int32Value: 99}},
 						},
 					},
 				},
 			},
@@ -312,15 +385,48 @@ func TestReadBulkForwardsTimeoutAndUnpacksCachedFlag(t *testing.T) {
 	defer cleanup()
 	session := NewSessionForID(client, "session-1")
-	results, err := session.ReadBulk(context.Background(), 12, []string{"Area001.Pump001.Speed"}, 750*time.Millisecond)
+	results, err := session.ReadBulk(context.Background(), 12, []string{"Tank01.Level", "Tank02.Level"}, 250*time.Millisecond)
 	if err != nil {
 		t.Fatalf("ReadBulk() error = %v", err)
 	}
-	if len(results) != 1 || !results[0].GetWasCached() || results[0].GetValue().GetInt32Value() != 99 {
+	if len(results) != 2 {
-		t.Fatalf("results = %#v", results)
+		t.Fatalf("results len = %d, want 2", len(results))
 	}
-	if got := fake.invokeRequest.GetCommand().GetReadBulk().GetTimeoutMs(); got != 750 {
+	if !results[0].GetWasCached() || results[1].GetWasCached() {
-		t.Fatalf("timeout_ms = %d, want 750", got)
+		t.Fatalf("WasCached flags = [%v %v], want [true false]", results[0].GetWasCached(), results[1].GetWasCached())
 	}
 	req := fake.invokeRequest
 	if req.GetCommand().GetKind() != pb.MxCommandKind_MX_COMMAND_KIND_READ_BULK {
 		t.Fatalf("command kind = %s", req.GetCommand().GetKind())
 	}
 	if got := req.GetCommand().GetReadBulk().GetTimeoutMs(); got != 250 {
 		t.Fatalf("timeout ms = %d, want 250", got)
 	}
 }
 func TestReadBulkSaturatesTimeoutAboveMaxUint32(t *testing.T) {
 	fake := &fakeGatewayServer{
 		invokeReply: &pb.MxCommandReply{
 			SessionId: "session-1",
 			Kind:      pb.MxCommandKind_MX_COMMAND_KIND_READ_BULK,
 			ProtocolStatus: &pb.ProtocolStatus{
 				Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
 			},
 		},
 	}
 	client, cleanup := newBufconnClient(t, fake)
 	defer cleanup()
 	session := NewSessionForID(client, "session-1")
 	// 100 days in milliseconds exceeds MaxUint32 (~49.7 days).
 	hugeTimeout := 100 * 24 * time.Hour
 	_, err := session.ReadBulk(context.Background(), 12, []string{"Tank01.Level"}, hugeTimeout)
 	if err != nil {
 		t.Fatalf("ReadBulk() error = %v", err)
 	}
 	got := fake.invokeRequest.GetCommand().GetReadBulk().GetTimeoutMs()
 	if got != ^uint32(0) {
 		t.Fatalf("timeout ms = %d, want %d (MaxUint32)", got, ^uint32(0))
 	}
 }
@@ -373,11 +479,8 @@ func newBufconnClient(t *testing.T, fake *fakeGatewayServer) (*Client, func()) {
 	dialer := func(ctx context.Context, _ string) (net.Conn, error) {
 		return listener.DialContext(ctx)
 	}
 	// grpc.NewClient defaults the target scheme to dns; the bufconn fake name
 	// is not DNS-resolvable, so use the passthrough scheme to hand the target
 	// straight to the context dialer.
 	client, err := Dial(context.Background(), Options{
-		Endpoint:  "passthrough:///bufnet",
+		Endpoint:  "bufnet",
 		APIKey:    "test-api-key",
 		Plaintext: true,
 		DialOptions: []grpc.DialOption{
@@ -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)")
 	}
 }
@@ -1,401 +0,0 @@
 package mxgateway
 import (
 	"context"
 	"crypto/tls"
 	"errors"
 	"net"
 	"reflect"
 	"strings"
 	"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/credentials/insecure"
 	"google.golang.org/grpc/status"
 	"google.golang.org/protobuf/types/known/timestamppb"
 )
 // --- Client.Go-008: resolveTransportCredentials precedence -----------------
 // TestResolveTransportCredentialsPrecedence covers every branch of
 // resolveTransportCredentials, which previously only had the Plaintext path
 // exercised.
 func TestResolveTransportCredentialsPrecedence(t *testing.T) {
 	custom := insecure.NewCredentials()
 	t.Run("TransportCredentialsWins", func(t *testing.T) {
 		creds, err := resolveTransportCredentials(Options{
 			TransportCredentials: custom,
 			Plaintext:            true, // must be ignored
 		})
 		if err != nil {
 			t.Fatalf("unexpected error: %v", err)
 		}
 		if creds != custom {
 			t.Fatal("expected the explicit TransportCredentials to be returned as-is")
 		}
 	})
 	t.Run("Plaintext", func(t *testing.T) {
 		creds, err := resolveTransportCredentials(Options{Plaintext: true})
 		if err != nil {
 			t.Fatalf("unexpected error: %v", err)
 		}
 		if got := creds.Info().SecurityProtocol; got != "insecure" {
 			t.Fatalf("expected insecure credentials, got security protocol %q", got)
 		}
 	})
 	t.Run("CACertFileMissingErrors", func(t *testing.T) {
 		_, err := resolveTransportCredentials(Options{CACertFile: "does-not-exist.pem"})
 		if err == nil {
 			t.Fatal("expected an error for a missing CA cert file")
 		}
 	})
 	t.Run("TLSConfigWithServerNameOverride", func(t *testing.T) {
 		creds, err := resolveTransportCredentials(Options{
 			TLSConfig:          &tls.Config{MinVersion: tls.VersionTLS13},
 			ServerNameOverride: "gateway.internal",
 		})
 		if err != nil {
 			t.Fatalf("unexpected error: %v", err)
 		}
 		if got := creds.Info().ServerName; got != "gateway.internal" {
 			t.Fatalf("expected ServerName override to be applied, got %q", got)
 		}
 	})
 	t.Run("DefaultTLSFloor", func(t *testing.T) {
 		creds, err := resolveTransportCredentials(Options{ServerNameOverride: "host"})
 		if err != nil {
 			t.Fatalf("unexpected error: %v", err)
 		}
 		if got := creds.Info().SecurityProtocol; got != "tls" {
 			t.Fatalf("expected the default TLS credentials, got %q", got)
 		}
 	})
 }
 // TestResolveTransportCredentialsDoesNotMutateTLSConfig confirms the supplied
 // TLSConfig is cloned, not mutated, when ServerNameOverride is applied.
 func TestResolveTransportCredentialsDoesNotMutateTLSConfig(t *testing.T) {
 	cfg := &tls.Config{MinVersion: tls.VersionTLS12}
 	if _, err := resolveTransportCredentials(Options{
 		TLSConfig:          cfg,
 		ServerNameOverride: "override",
 	}); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
 	if cfg.ServerName != "" {
 		t.Fatalf("resolveTransportCredentials mutated the caller's TLSConfig (ServerName=%q)", cfg.ServerName)
 	}
 }
 // --- Client.Go-008: callContext deadline arithmetic ------------------------
 // TestCallContextDeadlineArithmetic covers the shared callContext deadline
 // logic, including the negative-timeout disable case and the
 // caller-deadline-is-sooner case.
 func TestCallContextDeadlineArithmetic(t *testing.T) {
 	t.Run("ZeroUsesDefault", func(t *testing.T) {
 		ctx, cancel := callContext(context.Background(), 0)
 		defer cancel()
 		deadline, ok := ctx.Deadline()
 		if !ok {
 			t.Fatal("expected a deadline for the default timeout")
 		}
 		remaining := time.Until(deadline)
 		if remaining <= 0 || remaining > defaultCallTimeout+time.Second {
 			t.Fatalf("default deadline out of range: %v", remaining)
 		}
 	})
 	t.Run("NegativeDisablesBound", func(t *testing.T) {
 		base := context.Background()
 		ctx, cancel := callContext(base, -1)
 		defer cancel()
 		if _, ok := ctx.Deadline(); ok {
 			t.Fatal("a negative timeout must disable the deadline entirely")
 		}
 		if ctx != base {
 			t.Fatal("a negative timeout must return the caller context unchanged")
 		}
 	})
 	t.Run("PositiveAppliesTimeout", func(t *testing.T) {
 		ctx, cancel := callContext(context.Background(), 5*time.Second)
 		defer cancel()
 		deadline, ok := ctx.Deadline()
 		if !ok {
 			t.Fatal("expected a deadline")
 		}
 		remaining := time.Until(deadline)
 		if remaining <= 0 || remaining > 5*time.Second+time.Second {
 			t.Fatalf("deadline out of range: %v", remaining)
 		}
 	})
 	t.Run("CallerDeadlineSoonerIsKept", func(t *testing.T) {
 		base, baseCancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
 		defer baseCancel()
 		ctx, cancel := callContext(base, 30*time.Second)
 		defer cancel()
 		if ctx != base {
 			t.Fatal("a caller deadline sooner than the timeout must be kept as-is")
 		}
 	})
 	t.Run("CallerDeadlineLaterIsShortened", func(t *testing.T) {
 		base, baseCancel := context.WithTimeout(context.Background(), time.Hour)
 		defer baseCancel()
 		ctx, cancel := callContext(base, time.Second)
 		defer cancel()
 		deadline, ok := ctx.Deadline()
 		if !ok {
 			t.Fatal("expected a deadline")
 		}
 		if remaining := time.Until(deadline); remaining > 2*time.Second {
 			t.Fatalf("expected the shorter timeout to win, got %v remaining", remaining)
 		}
 	})
 }
 // --- Client.Go-008: NativeValue / NativeArray edge branches ----------------
 // TestNativeValueEdgeKinds covers the array, raw-bytes, null, and
 // nil-input branches of NativeValue.
 func TestNativeValueEdgeKinds(t *testing.T) {
 	t.Run("NilInput", func(t *testing.T) {
 		got, err := NativeValue(nil)
 		if err != nil || got != nil {
 			t.Fatalf("NativeValue(nil) = (%v, %v), want (nil, nil)", got, err)
 		}
 	})
 	t.Run("ExplicitNull", func(t *testing.T) {
 		got, err := NativeValue(&pb.MxValue{IsNull: true})
 		if err != nil || got != nil {
 			t.Fatalf("NativeValue(null) = (%v, %v), want (nil, nil)", got, err)
 		}
 	})
 	t.Run("RawBytes", func(t *testing.T) {
 		raw := []byte{0x01, 0x02, 0x03}
 		got, err := NativeValue(&pb.MxValue{Kind: &pb.MxValue_RawValue{RawValue: raw}})
 		if err != nil {
 			t.Fatalf("unexpected error: %v", err)
 		}
 		gotBytes, ok := got.([]byte)
 		if !ok || !reflect.DeepEqual(gotBytes, raw) {
 			t.Fatalf("NativeValue raw = %v, want %v", got, raw)
 		}
 		// The result must be a copy, not aliasing the protobuf field.
 		gotBytes[0] = 0xFF
 		if raw[0] != 0x01 {
 			t.Fatal("NativeValue raw result aliases the protobuf backing array")
 		}
 	})
 	t.Run("ArrayValue", func(t *testing.T) {
 		value := &pb.MxValue{Kind: &pb.MxValue_ArrayValue{
 			ArrayValue: &pb.MxArray{Values: &pb.MxArray_Int32Values{
 				Int32Values: &pb.Int32Array{Values: []int32{7, 8}},
 			}},
 		}}
 		got, err := NativeValue(value)
 		if err != nil {
 			t.Fatalf("unexpected error: %v", err)
 		}
 		if !reflect.DeepEqual(got, []int32{7, 8}) {
 			t.Fatalf("NativeValue array = %v, want [7 8]", got)
 		}
 	})
 }
 // TestNativeArrayEdgeKinds covers the nil, raw-bytes, timestamp-with-nil, and
 // unsupported-kind branches of NativeArray.
 func TestNativeArrayEdgeKinds(t *testing.T) {
 	t.Run("NilInput", func(t *testing.T) {
 		got, err := NativeArray(nil)
 		if err != nil || got != nil {
 			t.Fatalf("NativeArray(nil) = (%v, %v), want (nil, nil)", got, err)
 		}
 	})
 	t.Run("RawValues", func(t *testing.T) {
 		got, err := NativeArray(&pb.MxArray{Values: &pb.MxArray_RawValues{
 			RawValues: &pb.RawArray{Values: [][]byte{{0x0A}, {0x0B}}},
 		}})
 		if err != nil {
 			t.Fatalf("unexpected error: %v", err)
 		}
 		want := [][]byte{{0x0A}, {0x0B}}
 		if !reflect.DeepEqual(got, want) {
 			t.Fatalf("NativeArray raw = %v, want %v", got, want)
 		}
 	})
 	t.Run("TimestampWithNilEntry", func(t *testing.T) {
 		got, err := NativeArray(&pb.MxArray{Values: &pb.MxArray_TimestampValues{
 			TimestampValues: &pb.TimestampArray{Values: []*timestamppb.Timestamp{nil}},
 		}})
 		if err != nil {
 			t.Fatalf("unexpected error: %v", err)
 		}
 		times, ok := got.([]time.Time)
 		if !ok || len(times) != 1 || !times[0].IsZero() {
 			t.Fatalf("NativeArray timestamp-with-nil = %v, want [zero-time]", got)
 		}
 	})
 	t.Run("UnsupportedKind", func(t *testing.T) {
 		// An MxArray with no oneof set hits the default branch.
 		_, err := NativeArray(&pb.MxArray{})
 		if err == nil {
 			t.Fatal("expected an error for an MxArray with no values set")
 		}
 		if !strings.Contains(err.Error(), "unsupported array value kind") {
 			t.Fatalf("unexpected error text: %v", err)
 		}
 	})
 }
 // TestNativeValueUnsupportedKind covers the default branch of NativeValue.
 func TestNativeValueUnsupportedKind(t *testing.T) {
 	// An MxValue with no oneof Kind set and IsNull false hits the default.
 	_, err := NativeValue(&pb.MxValue{})
 	if err == nil {
 		t.Fatal("expected an error for an MxValue with no kind set")
 	}
 	if !strings.Contains(err.Error(), "unsupported value kind") {
 		t.Fatalf("unexpected error text: %v", err)
 	}
 }
 // --- Client.Go-005: dial migration -----------------------------------------
 // TestDialFailsFastWhenGatewayUnreachable confirms that after the migration to
 // grpc.NewClient the DialTimeout-bounded readiness probe still fails fast (and
 // wraps the failure in *GatewayError) when the gateway cannot be reached.
 func TestDialFailsFastWhenGatewayUnreachable(t *testing.T) {
 	dialer := func(ctx context.Context, _ string) (net.Conn, error) {
 		return nil, errors.New("connection refused")
 	}
 	start := time.Now()
 	client, err := Dial(context.Background(), Options{
 		Endpoint:    "passthrough:///unreachable",
 		APIKey:      "k",
 		Plaintext:   true,
 		DialTimeout: 500 * time.Millisecond,
 		DialOptions: []grpc.DialOption{grpc.WithContextDialer(dialer)},
 	})
 	elapsed := time.Since(start)
 	if err == nil {
 		client.Close()
 		t.Fatal("expected Dial to fail for an unreachable gateway")
 	}
 	var gwErr *GatewayError
 	if !errors.As(err, &gwErr) || gwErr.Op != "dial" {
 		t.Fatalf("expected a *GatewayError with Op=dial, got %#v", err)
 	}
 	if elapsed > 5*time.Second {
 		t.Fatalf("Dial did not honor DialTimeout: took %v", elapsed)
 	}
 }
 // TestDialReadinessProbeReachesReady confirms the readiness probe succeeds
 // against a live (bufconn) gateway, i.e. the lazy grpc.NewClient connection is
 // driven to Ready before Dial returns.
 func TestDialReadinessProbeReachesReady(t *testing.T) {
 	client, cleanup := newBufconnClient(t, &fakeGatewayServer{
 		openReply: &pb.OpenSessionReply{},
 	})
 	defer cleanup()
 	if client == nil {
 		t.Fatal("expected a connected client")
 	}
 }
 // --- Client.Go-006: error taxonomy ----------------------------------------
 // TestGatewayErrorCode confirms GatewayError.Code surfaces the wrapped gRPC
 // status code without the caller unwrapping it.
 func TestGatewayErrorCode(t *testing.T) {
 	var nilErr *GatewayError
 	if got := nilErr.Code(); got != codes.OK {
 		t.Fatalf("nil GatewayError.Code() = %v, want OK", got)
 	}
 	gwErr := &GatewayError{Op: "invoke", Err: status.Error(codes.Unavailable, "down")}
 	if got := gwErr.Code(); got != codes.Unavailable {
 		t.Fatalf("GatewayError.Code() = %v, want Unavailable", got)
 	}
 	plain := &GatewayError{Op: "dial", Err: errors.New("boom")}
 	if got := plain.Code(); got != codes.Unknown {
 		t.Fatalf("GatewayError.Code() for a non-status error = %v, want Unknown", got)
 	}
 }
 // TestIsTransient verifies the transient/permanent classification including
 // the unwrap-through-GatewayError path.
 func TestIsTransient(t *testing.T) {
 	tests := []struct {
 		name string
 		err  error
 		want bool
 	}{
 		{name: "nil", err: nil, want: false},
 		{name: "unavailable wrapped", err: &GatewayError{Op: "invoke", Err: status.Error(codes.Unavailable, "x")}, want: true},
 		{name: "deadline wrapped", err: &GatewayError{Op: "invoke", Err: status.Error(codes.DeadlineExceeded, "x")}, want: true},
 		{name: "resource exhausted", err: &GatewayError{Err: status.Error(codes.ResourceExhausted, "x")}, want: true},
 		{name: "unauthenticated permanent", err: &GatewayError{Err: status.Error(codes.Unauthenticated, "x")}, want: false},
 		{name: "invalid argument permanent", err: &GatewayError{Err: status.Error(codes.InvalidArgument, "x")}, want: false},
 		{name: "bare status unavailable", err: status.Error(codes.Unavailable, "x"), want: true},
 		{name: "plain error", err: errors.New("nope"), want: false},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			if got := IsTransient(tt.err); got != tt.want {
 				t.Fatalf("IsTransient(%v) = %v, want %v", tt.err, got, tt.want)
 			}
 		})
 	}
 }
 // --- Client.Go-007: correlation id fallback --------------------------------
 // TestNewCorrelationIDUsesRandEntropy confirms the happy path yields a
 // 32-hex-character id.
 func TestNewCorrelationIDUsesRandEntropy(t *testing.T) {
 	id := newCorrelationID()
 	if len(id) != 32 {
 		t.Fatalf("expected a 32-char hex id, got %q (len %d)", id, len(id))
 	}
 }
 // TestNewCorrelationIDFallsBackOnRandFailure reproduces Client.Go-007: when
 // crypto/rand fails, newCorrelationID must not return an empty string but a
 // unique, non-empty fallback id so the command stays traceable.
 func TestNewCorrelationIDFallsBackOnRandFailure(t *testing.T) {
 	original := randRead
 	randRead = func([]byte) (int, error) { return 0, errors.New("entropy unavailable") }
 	defer func() { randRead = original }()
 	first := newCorrelationID()
 	second := newCorrelationID()
 	if first == "" || second == "" {
 		t.Fatal("newCorrelationID returned an empty id on rand failure")
 	}
 	if !strings.HasPrefix(first, "fallback-") {
 		t.Fatalf("expected a fallback- prefixed id, got %q", first)
 	}
 	if first == second {
 		t.Fatalf("fallback correlation ids must be unique, got %q twice", first)
 	}
 }
@@ -1,22 +1,11 @@
 package mxgateway
 import (
 	"errors"
 	"fmt"
 	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
 )
 // ErrEventBufferOverflow is the terminal error delivered on the compatibility
 // event channel returned by Session.Events / Session.EventsAfter when a slow
 // consumer lets the bounded result buffer fill. It signals that the stream was
 // cancelled and events were dropped, so a consumer can tell an overflow apart
 // from a normal end-of-stream. Use Session.SubscribeEvents to block instead of
 // dropping.
 var ErrEventBufferOverflow = errors.New("mxgateway: event buffer overflow; compatibility stream cancelled and events dropped")
 // GatewayError wraps transport-level gRPC failures.
 type GatewayError struct {
 	// Op names the operation that failed (for example "dial" or "invoke").
@@ -44,45 +33,6 @@ func (e *GatewayError) Unwrap() error {
 	return e.Err
 }
 // Code returns the gRPC status code of the wrapped transport error. It returns
 // codes.OK when the error is nil and codes.Unknown when the wrapped error does
 // not carry a gRPC status. Callers can use it to write retry, timeout, and
 // auth handling without manually unwrapping and re-parsing the error.
 func (e *GatewayError) Code() codes.Code {
 	if e == nil || e.Err == nil {
 		return codes.OK
 	}
 	return status.Code(e.Err)
 }
 // IsTransient reports whether err is a transport failure that may succeed on
 // retry — for example a gateway that is briefly Unavailable or a call that
 // hit a DeadlineExceeded. Permanent failures (Unauthenticated, PermissionDenied,
 // InvalidArgument, NotFound, and similar) return false. It unwraps through
 // *GatewayError and any other error chain carrying a gRPC status, so callers
 // do not need to call status.Code themselves.
 func IsTransient(err error) bool {
 	if err == nil {
 		return false
 	}
 	switch transientCode(err) {
 	case codes.Unavailable, codes.DeadlineExceeded, codes.ResourceExhausted, codes.Aborted:
 		return true
 	default:
 		return false
 	}
 }
 // transientCode extracts a gRPC status code from err, preferring a wrapped
 // *GatewayError's Code and otherwise falling back to status.Code on the chain.
 func transientCode(err error) codes.Code {
 	var gatewayErr *GatewayError
 	if errors.As(err, &gatewayErr) {
 		return gatewayErr.Code()
 	}
 	return status.Code(err)
 }
 // CommandError reports a non-OK gateway protocol status and keeps the raw
 // command reply when one exists.
 type CommandError struct {
@@ -135,12 +85,8 @@ func (e *MxAccessError) Error() string {
 }
 // Unwrap returns the wrapped CommandError, when one is present.
 //
 // When Command is nil (the HRESULT / MxStatusProxy path) it returns an
 // untyped nil rather than a typed-nil *CommandError, so errors.As does not
 // bind a nil pointer that a caller would then panic on.
 func (e *MxAccessError) Unwrap() error {
-	if e == nil || e.Command == nil {
+	if e == nil {
 		return nil
 	}
 	return e.Command
@@ -1,42 +0,0 @@
 package mxgateway
 import (
 	"errors"
 	"testing"
 )
 // TestMxAccessErrorUnwrapHResultPathNoTypedNilCommandError reproduces
 // Client.Go-001: an MxAccessError built via the HRESULT / MxStatusProxy path
 // leaves Command nil. Unwrap must not hand back a typed-nil *CommandError,
 // because errors.As would then succeed while binding a nil pointer and a
 // caller dereferencing it would panic.
 func TestMxAccessErrorUnwrapHResultPathNoTypedNilCommandError(t *testing.T) {
 	hresult := int32(-2147467259) // 0x80004005, a failing HRESULT.
 	reply := &MxCommandReply{Hresult: &hresult}
 	err := EnsureMxAccessSuccess("invoke", reply)
 	if err == nil {
 		t.Fatal("expected MxAccessError for a failing HRESULT, got nil")
 	}
 	var ce *CommandError
 	if errors.As(err, &ce) {
 		t.Fatalf("errors.As bound *CommandError from an HRESULT-only MxAccessError (ce=%v); "+
 			"a caller dereferencing ce.Status would panic", ce)
 	}
 }
 // TestMxAccessErrorUnwrapPopulatedCommand confirms the non-nil Command path
 // still unwraps to the wrapped *CommandError.
 func TestMxAccessErrorUnwrapPopulatedCommand(t *testing.T) {
 	command := &CommandError{Op: "invoke"}
 	err := &MxAccessError{Command: command}
 	var ce *CommandError
 	if !errors.As(err, &ce) {
 		t.Fatal("errors.As failed to bind the populated *CommandError")
 	}
 	if ce != command {
 		t.Fatalf("errors.As bound an unexpected *CommandError: got %v want %v", ce, command)
 	}
 }
@@ -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,10 @@ 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
 )
 // RawDeployEventStream is the generated WatchDeployEvents client stream.
@@ -56,13 +70,39 @@ type GalaxyClient struct {
 // DialGalaxy opens a gRPC connection to the gateway for the Galaxy Repository
 // service. It applies the same authentication metadata, transport security,
-// lazy connection, and DialTimeout-bounded readiness probe as Dial.
+// and dial-timeout behavior as Dial.
 func DialGalaxy(ctx context.Context, opts Options) (*GalaxyClient, error) {
-	conn, err := dial(ctx, opts)
+	if opts.Endpoint == "" {
 		return nil, errors.New("mxgateway: endpoint is required")
 	}
 	dialCtx := ctx
 	cancel := func() {}
 	if opts.DialTimeout > 0 {
 		dialCtx, cancel = context.WithTimeout(ctx, opts.DialTimeout)
 	} else if _, ok := ctx.Deadline(); !ok {
 		dialCtx, cancel = context.WithTimeout(ctx, defaultDialTimeout)
 	}
 	defer cancel()
 	transportCredentials, err := resolveTransportCredentials(opts)
 	if err != nil {
 		return nil, err
 	}
 	dialOptions := []grpc.DialOption{
 		grpc.WithTransportCredentials(transportCredentials),
 		grpc.WithUnaryInterceptor(unaryAuthInterceptor(opts.APIKey)),
 		grpc.WithStreamInterceptor(streamAuthInterceptor(opts.APIKey)),
 		grpc.WithBlock(),
 	}
 	dialOptions = append(dialOptions, opts.DialOptions...)
 	conn, err := grpc.DialContext(dialCtx, opts.Endpoint, dialOptions...)
 	if err != nil {
 		return nil, &GatewayError{Op: "dial", Err: err}
 	}
 	return NewGalaxyClient(conn, opts), nil
 }
@@ -120,16 +160,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)
+	var objects []*GalaxyObject
-	defer cancel()
+	pageToken := ""
-
+	seen := map[string]struct{}{}
-	reply, err := c.raw.DiscoverHierarchy(callCtx, &pb.DiscoverHierarchyRequest{})
+	for {
-	if err != nil {
+		callCtx, cancel := c.callContext(ctx)
-		return nil, &GatewayError{Op: "galaxy discover hierarchy", Err: err}
+		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
@@ -187,7 +246,7 @@ func (c *GalaxyClient) WatchDeployEvents(
 				}
 				continue
 			}
-			if errors.Is(recvErr, io.EOF) {
+			if recvErr == io.EOF {
 				return
 			}
 			if status.Code(recvErr) == codes.Canceled || ctx.Err() != nil {
@@ -212,6 +271,219 @@ func (c *GalaxyClient) Close() error {
 	return c.conn.Close()
 }
-func (c *GalaxyClient) callContext(ctx context.Context) (context.Context, context.CancelFunc) {
+// LazyBrowseNode is one node in a lazy Galaxy hierarchy walk produced by
-	return callContext(ctx, c.opts.CallTimeout)
+// (*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 {
 		timeout = defaultCallTimeout
 	}
 	if timeout < 0 {
 		return ctx, func() {}
 	}
 	if deadline, ok := ctx.Deadline(); ok {
 		timeoutDeadline := time.Now().Add(timeout)
 		if deadline.Before(timeoutDeadline) {
 			return ctx, func() {}
 		}
 	}
 	return context.WithTimeout(ctx, timeout)
 }
@@ -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)
@@ -348,10 +392,8 @@ func newGalaxyBufconnClient(t *testing.T, fake *fakeGalaxyServer) (*GalaxyClient
 	dialer := func(ctx context.Context, _ string) (net.Conn, error) {
 		return listener.DialContext(ctx)
 	}
 	// grpc.NewClient defaults to the dns scheme; use passthrough so the
 	// bufconn fake target reaches the context dialer unresolved.
 	client, err := DialGalaxy(context.Background(), Options{
-		Endpoint:  "passthrough:///bufnet",
+		Endpoint:  "bufnet",
 		APIKey:    "test-api-key",
 		Plaintext: true,
 		DialOptions: []grpc.DialOption{
@@ -372,14 +414,20 @@ func newGalaxyBufconnClient(t *testing.T, fake *fakeGalaxyServer) (*GalaxyClient
 type fakeGalaxyServer struct {
 	pb.UnimplementedGalaxyRepositoryServer
-	testReply     *pb.TestConnectionReply
+	testReply                *pb.TestConnectionReply
-	testAuth      string
+	testAuth                 string
-	failTest      bool
+	failTest                 bool
-	deployReply   *pb.GetLastDeployTimeReply
+	deployReply              *pb.GetLastDeployTimeReply
-	discoverReply *pb.DiscoverHierarchyReply
+	discoverReply            *pb.DiscoverHierarchyReply
-	watchEvents   []*pb.DeployEvent
+	discoverHierarchyCalls   []*pb.DiscoverHierarchyRequest
-	watchRequest  *pb.WatchDeployEventsRequest
+	discoverHierarchyReplies []*pb.DiscoverHierarchyReply
-	watchHoldOpen bool
+	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) {
@@ -401,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
 	}
@@ -413,9 +467,398 @@ func (s *fakeGalaxyServer) WatchDeployEvents(req *pb.WatchDeployEventsRequest, s
 		if err := stream.Send(event); err != nil {
 			return err
 		}
 		if s.watchSendInterval > 0 {
 			select {
 			case <-time.After(s.watchSendInterval):
 			case <-stream.Context().Done():
 				return stream.Context().Err()
 			}
 		}
 	}
 	if s.watchHoldOpen {
 		<-stream.Context().Done()
 	}
 	return nil
 }
 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)
 	}
 }
@@ -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
@@ -8,7 +8,6 @@ import (
 	"fmt"
 	"io"
 	"sync"
 	"sync/atomic"
 	"time"
 	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
@@ -393,6 +392,9 @@ func (s *Session) UnsubscribeBulk(ctx context.Context, serverHandle int32, itemH
 // Per-entry failures appear as BulkWriteResult entries with WasSuccessful=false; the call
 // never returns an error for per-entry MXAccess failures (it returns an error only for
 // protocol-level failures or transport errors).
 //
 // A non-nil but empty entries slice is treated as a no-op and returns an empty result
 // without a wire round-trip; pass nil to surface a clear "entries are required" error.
 func (s *Session) WriteBulk(ctx context.Context, serverHandle int32, entries []*WriteBulkEntry) ([]*BulkWriteResult, error) {
 	if entries == nil {
 		return nil, errors.New("mxgateway: write bulk entries are required")
@@ -400,6 +402,9 @@ func (s *Session) WriteBulk(ctx context.Context, serverHandle int32, entries []*
 	if err := ensureBulkSize("write bulk entries", len(entries)); err != nil {
 		return nil, err
 	}
 	if len(entries) == 0 {
 		return []*BulkWriteResult{}, nil
 	}
 	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
 		Kind: pb.MxCommandKind_MX_COMMAND_KIND_WRITE_BULK,
 		Payload: &pb.MxCommand_WriteBulk{
@@ -416,6 +421,9 @@ func (s *Session) WriteBulk(ctx context.Context, serverHandle int32, entries []*
 }
 // Write2Bulk invokes MXAccess Write2 (timestamped) for each entry inside one gateway command.
 //
 // A non-nil but empty entries slice is treated as a no-op and returns an empty result
 // without a wire round-trip; pass nil to surface a clear "entries are required" error.
 func (s *Session) Write2Bulk(ctx context.Context, serverHandle int32, entries []*Write2BulkEntry) ([]*BulkWriteResult, error) {
 	if entries == nil {
 		return nil, errors.New("mxgateway: write2 bulk entries are required")
@@ -423,6 +431,9 @@ func (s *Session) Write2Bulk(ctx context.Context, serverHandle int32, entries []
 	if err := ensureBulkSize("write2 bulk entries", len(entries)); err != nil {
 		return nil, err
 	}
 	if len(entries) == 0 {
 		return []*BulkWriteResult{}, nil
 	}
 	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
 		Kind: pb.MxCommandKind_MX_COMMAND_KIND_WRITE2_BULK,
 		Payload: &pb.MxCommand_Write2Bulk{
@@ -440,6 +451,9 @@ func (s *Session) Write2Bulk(ctx context.Context, serverHandle int32, entries []
 // WriteSecuredBulk invokes MXAccess WriteSecured for each entry. Credential-sensitive
 // values must not be logged by callers; mirrors the single-item WriteSecured contract.
 //
 // A non-nil but empty entries slice is treated as a no-op and returns an empty result
 // without a wire round-trip; pass nil to surface a clear "entries are required" error.
 func (s *Session) WriteSecuredBulk(ctx context.Context, serverHandle int32, entries []*WriteSecuredBulkEntry) ([]*BulkWriteResult, error) {
 	if entries == nil {
 		return nil, errors.New("mxgateway: write-secured bulk entries are required")
@@ -447,6 +461,9 @@ func (s *Session) WriteSecuredBulk(ctx context.Context, serverHandle int32, entr
 	if err := ensureBulkSize("write-secured bulk entries", len(entries)); err != nil {
 		return nil, err
 	}
 	if len(entries) == 0 {
 		return []*BulkWriteResult{}, nil
 	}
 	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
 		Kind: pb.MxCommandKind_MX_COMMAND_KIND_WRITE_SECURED_BULK,
 		Payload: &pb.MxCommand_WriteSecuredBulk{
@@ -463,6 +480,9 @@ func (s *Session) WriteSecuredBulk(ctx context.Context, serverHandle int32, entr
 }
 // WriteSecured2Bulk invokes MXAccess WriteSecured2 (timestamped) for each entry.
 //
 // A non-nil but empty entries slice is treated as a no-op and returns an empty result
 // without a wire round-trip; pass nil to surface a clear "entries are required" error.
 func (s *Session) WriteSecured2Bulk(ctx context.Context, serverHandle int32, entries []*WriteSecured2BulkEntry) ([]*BulkWriteResult, error) {
 	if entries == nil {
 		return nil, errors.New("mxgateway: write-secured2 bulk entries are required")
@@ -470,6 +490,9 @@ func (s *Session) WriteSecured2Bulk(ctx context.Context, serverHandle int32, ent
 	if err := ensureBulkSize("write-secured2 bulk entries", len(entries)); err != nil {
 		return nil, err
 	}
 	if len(entries) == 0 {
 		return []*BulkWriteResult{}, nil
 	}
 	reply, err := s.invokeCommand(ctx, &pb.MxCommand{
 		Kind: pb.MxCommandKind_MX_COMMAND_KIND_WRITE_SECURED2_BULK,
 		Payload: &pb.MxCommand_WriteSecured2Bulk{
@@ -493,6 +516,10 @@ func (s *Session) WriteSecured2Bulk(ctx context.Context, serverHandle int32, ent
 // otherwise. timeout bounds the wait per tag in the snapshot case; pass zero to use the
 // worker default. Per-tag failures (timeout, invalid tag) appear as BulkReadResult entries
 // with WasSuccessful=false; the call never returns an error for per-tag MXAccess failures.
 //
 // A non-nil but empty tagAddresses slice is treated as a no-op and returns an empty
 // result without a wire round-trip; pass nil to surface a clear "tag addresses are
 // required" error.
 func (s *Session) ReadBulk(ctx context.Context, serverHandle int32, tagAddresses []string, timeout time.Duration) ([]*BulkReadResult, error) {
 	if tagAddresses == nil {
 		return nil, errors.New("mxgateway: tag addresses are required")
@@ -500,6 +527,9 @@ func (s *Session) ReadBulk(ctx context.Context, serverHandle int32, tagAddresses
 	if err := ensureBulkSize("tag addresses", len(tagAddresses)); err != nil {
 		return nil, err
 	}
 	if len(tagAddresses) == 0 {
 		return []*BulkReadResult{}, nil
 	}
 	var timeoutMs uint32
 	if timeout > 0 {
 		ms := timeout.Milliseconds()
@@ -599,7 +629,7 @@ func (s *Session) subscribeEventsAfter(ctx context.Context, afterWorkerSequence
 				}
 				continue
 			}
-			if errors.Is(err, io.EOF) || status.Code(err) == codes.Canceled || streamCtx.Err() != nil {
+			if err == io.EOF || status.Code(err) == codes.Canceled || streamCtx.Err() != nil {
 				return
 			}
 			sendEventResult(
@@ -628,7 +658,7 @@ func ensureBulkSize(name string, length int) error {
 func sendEventResult(
 	ctx context.Context,
-	results chan EventResult,
+	results chan<- EventResult,
 	result EventResult,
 	cancelWhenBufferFull bool,
 	cancel context.CancelFunc,
@@ -640,12 +670,7 @@ func sendEventResult(
 		case <-ctx.Done():
 			return false
 		default:
 			// The bounded compatibility buffer is full. Cancel the stream and
 			// deliver an explicit terminal overflow error so a slow consumer
 			// can tell dropped events apart from a normal end-of-stream,
 			// rather than seeing the channel close silently.
 			cancel()
 			deliverTerminalResult(results, EventResult{Err: ErrEventBufferOverflow})
 			return false
 		}
 	}
@@ -658,25 +683,6 @@ func sendEventResult(
 	}
 }
 // deliverTerminalResult places result on a full buffered channel by evicting
 // one of the oldest buffered events to make room. The caller closes results
 // afterwards, so the terminal result becomes the consumer's last item.
 func deliverTerminalResult(results chan EventResult, result EventResult) {
 	for {
 		select {
 		case results <- result:
 			return
 		default:
 		}
 		select {
 		case <-results:
 		default:
 			// Another receiver drained the channel between the send and
 			// receive attempts; retry the send.
 		}
 	}
 }
 func (s *Session) invokeCommand(ctx context.Context, command *MxCommand) (*MxCommandReply, error) {
 	return s.client.Invoke(ctx, &pb.MxCommandRequest{
 		SessionId:           s.ID(),
@@ -685,25 +691,10 @@ func (s *Session) invokeCommand(ctx context.Context, command *MxCommand) (*MxCom
 	})
 }
 // correlationIDCounter backs the deterministic fallback id used when
 // crypto/rand is unavailable, so every command still carries a unique,
 // traceable correlation id.
 var correlationIDCounter atomic.Uint64
 // randRead is the entropy source for newCorrelationID. It is a package
 // variable solely so tests can simulate a crypto/rand failure.
 var randRead = rand.Read
 // newCorrelationID returns a unique correlation id for an MxCommandRequest.
 // It prefers 16 bytes of crypto/rand entropy; if rand.Read fails (rare) it
 // falls back to a "fallback-" prefixed id built from the current time and a
 // process-wide monotonic counter rather than returning an empty string, which
 // would leave the command untraceable in gateway logs.
 func newCorrelationID() string {
 	var buffer [16]byte
-	if _, err := randRead(buffer[:]); err != nil {
+	if _, err := rand.Read(buffer[:]); err != nil {
-		return fmt.Sprintf("fallback-%x-%x",
+		return ""
 			time.Now().UnixNano(), correlationIDCounter.Add(1))
 	}
 	return hex.EncodeToString(buffer[:])
 }
@@ -70,32 +70,32 @@ type (
 	WriteCommand = pb.WriteCommand
 	// Write2Command is the payload of an MXAccess Write2 command.
 	Write2Command = pb.Write2Command
-	// WriteBulkCommand carries one bulk-Write request.
+	// WriteBulkCommand is the payload of a bulk Write command.
 	WriteBulkCommand = pb.WriteBulkCommand
-	// WriteBulkEntry is one (item_handle, value, user_id) tuple in a WriteBulk request.
+	// WriteBulkEntry is one entry inside a WriteBulkCommand.
 	WriteBulkEntry = pb.WriteBulkEntry
-	// Write2BulkCommand carries one bulk-Write2 (timestamped) request.
+	// Write2BulkCommand is the payload of a bulk Write2 (timestamped) command.
 	Write2BulkCommand = pb.Write2BulkCommand
-	// Write2BulkEntry is one (item_handle, value, timestamp_value, user_id) tuple in a Write2Bulk request.
+	// Write2BulkEntry is one entry inside a Write2BulkCommand.
 	Write2BulkEntry = pb.Write2BulkEntry
-	// WriteSecuredBulkCommand carries one bulk-WriteSecured request. Values are credential-sensitive.
+	// WriteSecuredBulkCommand is the payload of a bulk WriteSecured command.
 	WriteSecuredBulkCommand = pb.WriteSecuredBulkCommand
-	// WriteSecuredBulkEntry is one entry in a WriteSecuredBulk request.
+	// WriteSecuredBulkEntry is one entry inside a WriteSecuredBulkCommand.
 	WriteSecuredBulkEntry = pb.WriteSecuredBulkEntry
-	// WriteSecured2BulkCommand carries one bulk-WriteSecured2 (timestamped) request.
+	// WriteSecured2BulkCommand is the payload of a bulk WriteSecured2 (timestamped) command.
 	WriteSecured2BulkCommand = pb.WriteSecured2BulkCommand
-	// WriteSecured2BulkEntry is one entry in a WriteSecured2Bulk request.
+	// WriteSecured2BulkEntry is one entry inside a WriteSecured2BulkCommand.
 	WriteSecured2BulkEntry = pb.WriteSecured2BulkEntry
-	// ReadBulkCommand carries one bulk-Read request.
+	// ReadBulkCommand is the payload of a bulk Read snapshot command.
 	ReadBulkCommand = pb.ReadBulkCommand
-	// BulkWriteResult is one per-entry result in a bulk-write reply.
+	// BulkWriteReply aggregates BulkWriteResult entries for a bulk write command.
 	BulkWriteResult = pb.BulkWriteResult
 	// BulkWriteReply aggregates BulkWriteResult entries for a bulk-write command.
 	BulkWriteReply = pb.BulkWriteReply
-	// BulkReadResult is one per-tag result in a bulk-read reply (carries the snapshot value plus a was_cached flag).
+	// BulkWriteResult is one entry in a bulk write reply list.
-	BulkReadResult = pb.BulkReadResult
+	BulkWriteResult = pb.BulkWriteResult
-	// BulkReadReply aggregates BulkReadResult entries for a ReadBulk command.
+	// BulkReadReply aggregates BulkReadResult entries for a bulk read command.
 	BulkReadReply = pb.BulkReadReply
 	// BulkReadResult is one entry in a bulk read reply list.
 	BulkReadResult = pb.BulkReadResult
 	// RegisterReply carries the ServerHandle returned by Register.
 	RegisterReply = pb.RegisterReply
 	// AddItemReply carries the ItemHandle returned by AddItem.
@@ -110,12 +110,14 @@ type (
 	AcknowledgeAlarmRequest = pb.AcknowledgeAlarmRequest
 	// AcknowledgeAlarmReply is the gateway AcknowledgeAlarm reply message.
 	AcknowledgeAlarmReply = pb.AcknowledgeAlarmReply
 	// QueryActiveAlarmsRequest is the gateway QueryActiveAlarms request message.
 	QueryActiveAlarmsRequest = pb.QueryActiveAlarmsRequest
 	// StreamAlarmsRequest is the gateway StreamAlarms request message.
 	StreamAlarmsRequest = pb.StreamAlarmsRequest
 	// AlarmFeedMessage is one message on the StreamAlarms feed — an
 	// active-alarm snapshot row, a snapshot-complete sentinel, or a transition.
 	AlarmFeedMessage = pb.AlarmFeedMessage
-	// ActiveAlarmSnapshot is one currently-active alarm in the feed snapshot.
+	// ActiveAlarmSnapshot is one row in a ConditionRefresh stream.
 	ActiveAlarmSnapshot = pb.ActiveAlarmSnapshot
 	// OnAlarmTransitionEvent is the body carried by alarm-transition MxEvents.
 	OnAlarmTransitionEvent = pb.OnAlarmTransitionEvent
@@ -129,6 +131,10 @@ type AlarmTransitionKind = pb.AlarmTransitionKind
 // ConditionRefresh snapshot.
 type AlarmConditionState = pb.AlarmConditionState
 // QueryActiveAlarmsClient is the generated server-streaming client for the
 // QueryActiveAlarms RPC.
 type QueryActiveAlarmsClient = pb.MxAccessGateway_QueryActiveAlarmsClient
 // StreamAlarmsClient is the generated server-streaming client for the
 // StreamAlarms RPC.
 type StreamAlarmsClient = pb.MxAccessGateway_StreamAlarmsClient
@@ -184,16 +190,6 @@ const (
 	CommandKindWrite = pb.MxCommandKind_MX_COMMAND_KIND_WRITE
 	// CommandKindWrite2 selects the MXAccess Write2 command.
 	CommandKindWrite2 = pb.MxCommandKind_MX_COMMAND_KIND_WRITE2
 	// CommandKindWriteBulk selects the bulk Write command.
 	CommandKindWriteBulk = pb.MxCommandKind_MX_COMMAND_KIND_WRITE_BULK
 	// CommandKindWrite2Bulk selects the bulk Write2 (timestamped) command.
 	CommandKindWrite2Bulk = pb.MxCommandKind_MX_COMMAND_KIND_WRITE2_BULK
 	// CommandKindWriteSecuredBulk selects the bulk WriteSecured command.
 	CommandKindWriteSecuredBulk = pb.MxCommandKind_MX_COMMAND_KIND_WRITE_SECURED_BULK
 	// CommandKindWriteSecured2Bulk selects the bulk WriteSecured2 (timestamped) command.
 	CommandKindWriteSecured2Bulk = pb.MxCommandKind_MX_COMMAND_KIND_WRITE_SECURED2_BULK
 	// CommandKindReadBulk selects the bulk Read command (cached-or-snapshot per tag).
 	CommandKindReadBulk = pb.MxCommandKind_MX_COMMAND_KIND_READ_BULK
 	// DataTypeUnknown denotes an unrecognized MXAccess data type.
 	DataTypeUnknown = pb.MxDataType_MX_DATA_TYPE_UNKNOWN
@@ -18,13 +18,13 @@ clients/java/
  settings.gradle
  build.gradle
  src/main/generated/
-  mxgateway-client/
+  zb-mom-ww-mxgateway-client/
    build.gradle
-    src/main/java/com/dohertylan/mxgateway/client/
+    src/main/java/com/zb/mom/ww/mxgateway/client/
-    src/test/java/com/dohertylan/mxgateway/client/
+    src/test/java/com/zb/mom/ww/mxgateway/client/
-  mxgateway-cli/
+  zb-mom-ww-mxgateway-cli/
    build.gradle
-    src/main/java/com/dohertylan/mxgateway/cli/
+    src/main/java/com/zb/mom/ww/mxgateway/cli/
 ```
 Alternative Maven layout is acceptable if the repo standardizes on Maven.
@@ -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:
@@ -192,8 +209,8 @@ stream for bounded time, and close.
 Publish library and CLI separately:
- `mxgateway-client` jar,
+- `zb-mom-ww-mxgateway-client` jar,
- `mxgateway-cli` runnable distribution.
+- `zb-mom-ww-mxgateway-cli` runnable distribution.
 Generated protobuf code should be produced during the build from shared proto
 files and should not be hand-edited.
@@ -206,10 +223,10 @@ Run the Java scaffold checks from `clients/java`:
 gradle test
 ```
-The `mxgateway-client` project generates the gateway and worker protobuf/gRPC
+The `zb-mom-ww-mxgateway-client` project generates the gateway and worker
-bindings into `src/main/generated`, compiles the generated contracts, and runs
+protobuf/gRPC bindings into `src/main/generated`, compiles the generated
-JUnit 5 tests. The `mxgateway-cli` project builds a Picocli-based `mxgw-java`
+contracts, and runs JUnit 5 tests. The `zb-mom-ww-mxgateway-cli` project
-entry point for later command implementation.
+builds a Picocli-based `mxgw-java` entry point for later command implementation.
 ## Related Documentation
@@ -10,22 +10,23 @@ clients/java/
  settings.gradle
  build.gradle
  src/main/generated/
-  mxgateway-client/
+  zb-mom-ww-mxgateway-client/
-  mxgateway-cli/
+  zb-mom-ww-mxgateway-cli/
 ```
-`mxgateway-client` generates Java protobuf and gRPC sources from
+`zb-mom-ww-mxgateway-client` generates Java protobuf and gRPC sources from
-`../../src/MxGateway.Contracts/Protos`. The Gradle protobuf plugin writes those
+`../../src/ZB.MOM.WW.MxGateway.Contracts/Protos`. The Gradle protobuf plugin writes those
 generated sources under `src/main/generated`, which matches the client proto
 manifest in `../proto/proto-inputs.json`. Do not edit generated files by hand.
-`mxgateway-client` exposes `MxGatewayClientOptions`, `MxGatewayClient`,
+`zb-mom-ww-mxgateway-client` exposes `MxGatewayClientOptions`, `MxGatewayClient`,
 `MxGatewaySession`, value/status helpers, typed gateway exceptions, raw
 generated stubs, and generated protobuf messages for parity tests.
-`mxgateway-cli` depends on `mxgateway-client` and provides the `mxgw-java`
+`zb-mom-ww-mxgateway-cli` depends on `zb-mom-ww-mxgateway-client` and provides
-application entry point. The CLI supports version, session, command, event
+the `mxgw-java` application entry point. The CLI supports version, session,
-streaming, write, and smoke-test commands with deterministic JSON output.
+command, event streaming, write, and smoke-test commands with deterministic
 JSON output.
 ## Regenerating Protobuf Bindings
@@ -33,7 +34,7 @@ Run generation from `clients/java` after the shared `.proto` files or Java
 output path changes:
 ```powershell
-gradle :mxgateway-client:generateProto
+gradle :zb-mom-ww-mxgateway-client:generateProto
 ```
 ## Client Usage
@@ -56,66 +57,32 @@ 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
 `MxAccessException` preserve the raw `MxCommandReply` when the gateway returns a
 data-bearing MXAccess failure.
 `MxGatewaySession` exposes the full bulk family — `addItemBulk`,
 `adviseItemBulk`, `removeItemBulk`, `unAdviseItemBulk`, `subscribeBulk`,
 `unsubscribeBulk`, `writeBulk`, `write2Bulk`, `writeSecuredBulk`,
 `writeSecured2Bulk`, and `readBulk`. Each carries one round-trip with a
 `List<*Entry>` (or `List<String>` / `List<Integer>` for the legacy bulk
 shapes) and returns `List<SubscribeResult>` / `List<BulkWriteResult>` /
 `List<BulkReadResult>`; per-entry MXAccess failures populate
 `wasSuccessful == false` and never throw. `readBulk` takes a per-tag
 `timeoutMs` (0 = worker default) and returns cached `OnDataChange` values
 when the tag is already advised (`wasCached == true`) without touching the
 existing subscription.
 `openSession` verifies the gateway's reported `gateway_protocol_version` against
 the version this client was generated for and throws `MxGatewayException` on a
 mismatch, so an incompatible client fails fast with a clear message instead of
 issuing commands that fail downstream. A gateway that does not populate the
 field is accepted unchanged.
 `MxGatewaySession` implements `AutoCloseable`. The try-with-resources `close()`
 performs a `CloseSession` network RPC but swallows (and logs) any failure of
 that RPC so a close-time error never replaces the exception a try-with-resources
 body is already propagating. Call `closeRaw()` explicitly when you need to
 observe the close result or handle a close-time failure.
 `MxGatewayClient` and `GalaxyRepositoryClient` implement `AutoCloseable`. For a
 client that owns its channel (built with `connect`), the try-with-resources
 `close()` shuts the channel down and waits up to the configured
 `shutdownTimeout` (default 10 s, independent of `connectTimeout`) for
 termination, forcibly shutting it down on timeout, so in-flight calls and
 Netty event-loop threads are not left running after the block exits. If the
 calling thread is interrupted while waiting, the channel is forcibly shut down
 and the interrupt flag is restored. `closeAndAwaitTermination()` does the same
 but throws `InterruptedException` for callers that want a checked,
 blocking-aware shutdown. `close()` is a no-op for a caller-managed channel.
 `MxEventStream` implements `Iterator<MxEvent>` and `AutoCloseable`. Closing it
 cancels the underlying gRPC stream. Canceling or timing out a Java client call
 only stops the client from waiting; it does not abort an in-flight MXAccess COM
-call on the worker STA. Closing an `MxEventStream` *before* the gRPC call has
+call on the worker STA.
 attached its observer (a real race when callers cancel immediately after
 subscribing) is safe — the close is replayed in the observer's `beforeStart`
 and the underlying call is cancelled, matching `DeployEventStream` behaviour.
 The event stream uses gRPC's default auto-inbound flow control with a fixed
 1024-element buffer and no client-side flow control: this is the gateway's
 documented fail-fast event-backpressure model, so a consumer that stalls long
 enough to fill the buffer triggers an overflow that cancels the subscription
 and surfaces an `MxGatewayException` from the next `next()` call. Drain events
 promptly and be prepared to resubscribe with a resume cursor.
-Cancellation of `CompletableFuture` results from `openSessionAsync`,
+For alarms, `MxGatewayClient` exposes `queryActiveAlarms` (one-shot snapshot),
-`invokeAsync`, `acknowledgeAlarmAsync`, `getLastDeployTimeAsync`,
+`streamAlarms` (returns an `MxGatewayAlarmFeedSubscription` whose iterator
-`testConnectionAsync`, and `discoverHierarchyAsync` forwards to the underlying
+yields alarm-feed messages from the gateway's central monitor), and
-gRPC call: calling `cancel(true)` on the returned future aborts the in-flight
+`acknowledgeAlarm` (ack by full alarm reference with an optional comment and
-RPC instead of merely detaching the future from its result.
+ack target). Close the subscription to cancel the underlying gRPC stream.
 ## Galaxy Repository Browse
@@ -154,11 +121,64 @@ The CLI exposes matching subcommands: `galaxy-test`, `galaxy-deploy-time`,
 `--timeout`, and `--json` options as the gateway commands.
 ```powershell
-gradle :mxgateway-cli:run --args="galaxy-test --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-test --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
-gradle :mxgateway-cli:run --args="galaxy-deploy-time --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-deploy-time --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
-gradle :mxgateway-cli:run --args="galaxy-discover --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-discover --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
 ```
 ### Browsing lazily
 For UI trees or OPC UA bridges, use `browseChildren` to walk one level at a
 time instead of loading the full hierarchy with `discoverHierarchy`. Pass a
 default request for root objects; subsequent calls set `parentGobjectId`,
 `parentTagName`, or `parentContainedPath`. Filter fields match
 `DiscoverHierarchy`. Each response pairs `getChildrenList()` with
 `getChildHasChildrenList()` so you know which nodes to expand. See
 [Galaxy Repository](../../docs/GalaxyRepository.md#browsechildren) for full
 request and filter semantics. This snippet documents the API as it appears once
 the Java client is regenerated on the Windows host.
 ```java
 BrowseChildrenReply reply = galaxy.browseChildren(
        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
@@ -206,8 +226,8 @@ The matching CLI subcommand streams events until cancelled (Ctrl+C) and prints
 one line per event in text mode or one JSON object per event with `--json`:
 ```powershell
-gradle :mxgateway-cli:run --args="galaxy-watch --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-watch --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
-gradle :mxgateway-cli:run --args="galaxy-watch --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --last-seen-deploy-time 2026-04-28T18:30:00Z --limit 5"
+gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-watch --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --last-seen-deploy-time 2026-04-28T18:30:00Z --limit 5"
 ```
 ## CLI Usage
@@ -215,14 +235,16 @@ gradle :mxgateway-cli:run --args="galaxy-watch --endpoint localhost:5000 --api-k
 Run the CLI through Gradle:
 ```powershell
-gradle :mxgateway-cli:run --args="version --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="version --json"
-gradle :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="open-session --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --client-session-name java-cli --json"
-gradle :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="register --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --client-name java-cli --json"
-gradle :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="add-item --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item TestObject.TestInt --json"
-gradle :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="advise --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item-handle 1 --json"
-gradle :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="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 :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-events --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --limit 1 --json"
-gradle :mxgateway-cli:run --args="smoke --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --item TestObject.TestInt --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`,
@@ -232,7 +254,7 @@ output redacts API keys.
 Use TLS options for a secured gateway:
 ```powershell
-gradle :mxgateway-cli:run --args="smoke --endpoint mxgateway.example.local:5001 --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item TestObject.TestInt --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="smoke --endpoint mxgateway.example.local:5001 --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item TestObject.TestInt --json"
 ```
 ## Build And Test
@@ -252,11 +274,11 @@ in-process gRPC behavior, stream cancellation, and CLI parser/output behavior.
 Create local library and CLI artifacts from `clients/java`:
 ```powershell
-gradle :mxgateway-client:jar :mxgateway-cli:installDist
+gradle :zb-mom-ww-mxgateway-client:jar :zb-mom-ww-mxgateway-cli:installDist
 ```
-The library jar is under `mxgateway-client/build/libs`. The installed CLI
+The library jar is under `zb-mom-ww-mxgateway-client/build/libs`. The installed CLI
-distribution is under `mxgateway-cli/build/install/mxgateway-cli`.
+distribution is under `zb-mom-ww-mxgateway-cli/build/install/zb-mom-ww-mxgateway-cli`.
 ## Integration Checks
@@ -267,9 +289,40 @@ $env:MXGATEWAY_INTEGRATION = '1'
 $env:MXGATEWAY_ENDPOINT = 'localhost:5000'
 $env:MXGATEWAY_API_KEY = '<gateway-api-key>'
 $env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
-gradle :mxgateway-cli:run --args="smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json"
+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.0'
 }
 ````
 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)
@@ -12,7 +12,7 @@ ext {
 }
 subprojects {
-    group = 'com.dohertylan.mxgateway'
+    group = 'com.zb.mom.ww.mxgateway'
    version = '0.1.0'
    pluginManager.withPlugin('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') ?: ''
                    }
                }
            }
        }
    }
 }
@@ -1,65 +0,0 @@
 package com.dohertylan.mxgateway.client;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
 import galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest;
 import io.grpc.stub.ClientCallStreamObserver;
 import io.grpc.stub.ClientResponseObserver;
 import io.grpc.stub.StreamObserver;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicReference;
 /**
 * Cancellable handle returned by the async {@code watchDeployEvents} variant.
 * Mirrors {@link MxGatewayEventSubscription} but for the Galaxy Repository
 * deploy-event stream.
 */
 public final class DeployEventSubscription implements AutoCloseable {
    private final AtomicReference<ClientCallStreamObserver<WatchDeployEventsRequest>> requestStream =
            new AtomicReference<>();
    private final AtomicBoolean cancelled = new AtomicBoolean();
    ClientResponseObserver<WatchDeployEventsRequest, DeployEvent> wrap(StreamObserver<DeployEvent> observer) {
        return new ClientResponseObserver<>() {
            @Override
            public void beforeStart(ClientCallStreamObserver<WatchDeployEventsRequest> stream) {
                requestStream.set(stream);
                if (cancelled.get()) {
                    stream.cancel("client cancelled deploy event stream", null);
                }
            }
            @Override
            public void onNext(DeployEvent value) {
                observer.onNext(value);
            }
            @Override
            public void onError(Throwable error) {
                observer.onError(error);
            }
            @Override
            public void onCompleted() {
                observer.onCompleted();
            }
        };
    }
    /**
     * 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();
    }
 }
@@ -1,67 +0,0 @@
 package com.dohertylan.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;
 /**
 * Cancellable handle returned by {@code streamAlarms}.
 *
 * <p>Wraps a caller-supplied {@link StreamObserver} and exposes a
 * {@link #cancel()} entry point that aborts the underlying gRPC call. The
 * subscription also implements {@link AutoCloseable} so it can participate in
 * try-with-resources blocks.
 */
 public final class 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();
    }
 }
@@ -1,321 +0,0 @@
 package com.dohertylan.mxgateway.client;
 import com.google.common.util.concurrent.FutureCallback;
 import com.google.common.util.concurrent.Futures;
 import com.google.common.util.concurrent.ListenableFuture;
 import com.google.common.util.concurrent.MoreExecutors;
 import io.grpc.ManagedChannel;
 import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
 import io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder;
 import io.grpc.stub.AbstractStub;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.TimeUnit;
 import java.util.function.Function;
 import javax.net.ssl.SSLException;
 /**
 * Shared channel-builder and future-adaptor helpers used by both
 * {@link MxGatewayClient} and {@link GalaxyRepositoryClient}.
 *
 * <p>Extracted so transport construction, per-call deadlines, and the
 * {@link ListenableFuture}-to-{@link CompletableFuture} bridge live in one
 * place instead of being duplicated verbatim across the two clients.
 */
 final class MxGatewayChannels {
    private MxGatewayChannels() {
    }
    /**
     * Builds a Netty managed channel from the supplied options, applying the
     * connect timeout, message-size limit, and the configured transport
     * security mode (plaintext, custom CA trust, or system trust).
     *
     * @param options the client options carrying endpoint and transport config
     * @param tlsErrorPrefix a human-readable prefix for the {@link MxGatewayException}
     *     thrown when a custom CA certificate cannot be loaded
     * @return a new managed channel; the caller owns its lifecycle
     */
    static ManagedChannel createChannel(MxGatewayClientOptions options, String tlsErrorPrefix) {
        NettyChannelBuilder builder = NettyChannelBuilder.forTarget(options.endpoint())
                .maxInboundMessageSize(options.maxGrpcMessageBytes());
        if (!options.connectTimeout().isNegative()) {
            builder.withOption(
                    io.grpc.netty.shaded.io.netty.channel.ChannelOption.CONNECT_TIMEOUT_MILLIS,
                    Math.toIntExact(options.connectTimeout().toMillis()));
        }
        if (options.plaintext()) {
            builder.usePlaintext();
        } else if (options.caCertificatePath() != null) {
            try {
                builder.sslContext(GrpcSslContexts.forClient()
                        .trustManager(options.caCertificatePath().toFile())
                        .build());
            } catch (SSLException | RuntimeException error) {
                // SSLException covers handshake-context failures; RuntimeException
                // (IllegalArgumentException wrapping CertificateException) covers a
                // missing or unreadable CA file. Either way callers see one typed
                // failure instead of a raw, unwrapped exception leaking out.
                throw new MxGatewayException(tlsErrorPrefix, error);
            }
        } else {
            builder.useTransportSecurity();
        }
        if (!options.serverNameOverride().isBlank()) {
            builder.overrideAuthority(options.serverNameOverride());
        }
        return builder.build();
    }
    /**
     * Applies the configured per-call deadline to a unary stub.
     *
     * @param stub the stub to decorate
     * @param options the client options carrying the call timeout
     * @param <T> the concrete stub type
     * @return the stub with the call deadline applied, or the stub unchanged
     *     when the call timeout is negative (disabled)
     */
    static <T extends AbstractStub<T>> T withDeadline(T stub, MxGatewayClientOptions options) {
        if (options.callTimeout().isNegative()) {
            return stub;
        }
        return stub.withDeadlineAfter(options.callTimeout().toNanos(), TimeUnit.NANOSECONDS);
    }
    /**
     * Applies the configured streaming deadline to a streaming stub.
     *
     * @param stub the stub to decorate
     * @param options the client options carrying the stream timeout
     * @param <T> the concrete stub type
     * @return the stub with the stream deadline applied, or the stub unchanged
     *     when the stream timeout is unset or negative (disabled)
     */
    static <T extends AbstractStub<T>> T withStreamDeadline(T stub, MxGatewayClientOptions options) {
        if (options.streamTimeout() == null || options.streamTimeout().isNegative()) {
            return stub;
        }
        return stub.withDeadlineAfter(options.streamTimeout().toNanos(), TimeUnit.NANOSECONDS);
    }
    /**
     * Shuts a client-owned channel down and waits up to the configured
     * {@link MxGatewayClientOptions#shutdownTimeout()} for graceful
     * termination, forcing {@code shutdownNow()} on timeout. If the calling
     * thread is interrupted while waiting, the channel is forcibly shut down
     * and the thread's interrupt flag is restored — this matches the
     * try-with-resources {@code close()} contract that cannot throw a checked
     * exception.
     *
     * <p>No-op when {@code ownedChannel} is {@code null} (i.e. the caller owns
     * the channel lifecycle on a borrowed channel).
     *
     * @param ownedChannel the channel to shut down, may be {@code null}
     * @param options the client options carrying the shutdown timeout
     */
    static void shutdown(ManagedChannel ownedChannel, MxGatewayClientOptions options) {
        if (ownedChannel == null) {
            return;
        }
        ownedChannel.shutdown();
        try {
            if (!ownedChannel.awaitTermination(options.shutdownTimeout().toMillis(), TimeUnit.MILLISECONDS)) {
                ownedChannel.shutdownNow();
            }
        } catch (InterruptedException error) {
            ownedChannel.shutdownNow();
            Thread.currentThread().interrupt();
        }
    }
    /**
     * Shuts a client-owned channel down and waits up to the configured
     * {@link MxGatewayClientOptions#shutdownTimeout()} for termination,
     * forcing {@code shutdownNow()} on timeout. Throws
     * {@link InterruptedException} when the calling thread is interrupted —
     * for callers that want a checked, blocking-aware shutdown.
     *
     * <p>No-op when {@code ownedChannel} is {@code null}.
     *
     * @param ownedChannel the channel to shut down, may be {@code null}
     * @param options the client options carrying the shutdown timeout
     * @throws InterruptedException if the calling thread is interrupted while waiting
     */
    static void shutdownAndAwaitTermination(ManagedChannel ownedChannel, MxGatewayClientOptions options)
            throws InterruptedException {
        if (ownedChannel == null) {
            return;
        }
        ownedChannel.shutdown();
        if (!ownedChannel.awaitTermination(options.shutdownTimeout().toMillis(), TimeUnit.MILLISECONDS)) {
            ownedChannel.shutdownNow();
        }
    }
    /**
     * Bridges a Guava {@link ListenableFuture} to a {@link CompletableFuture},
     * normalising any failure through {@link MxGatewayErrors#fromGrpc} so the
     * async error surface matches the synchronous methods. Cancelling the
     * returned future cancels the source RPC.
     *
     * <p><strong>Cancellation contract:</strong> the returned future is a
     * {@link CancellingCompletableFuture} that overrides
     * {@link CompletableFuture#cancel(boolean)} so cancelling the
     * <em>direct return value</em> forwards to the source
     * {@link ListenableFuture}, aborting the underlying gRPC call. This is the
     * fix for Client.Java-015.
     *
     * <p><strong>Important — derived stages do <em>not</em> propagate
     * cancellation upstream.</strong> Calling
     * {@code cancel(...)} on a future obtained via
     * {@code thenApply}/{@code thenCompose}/{@code thenAccept}/{@code whenComplete}
     * of the value returned by this method only marks <em>that</em> derived stage
     * as cancelled; it does <strong>not</strong> propagate back to this
     * {@code CancellingCompletableFuture}, so the source RPC continues until its
     * deadline expires. {@link CompletableFuture#thenApply} (and the other
     * chaining methods) deliberately do not forward cancellation to the upstream
     * stage they were derived from.
     *
     * <p>If a caller needs cancellation through a chained pipeline, either:
     * <ul>
     *   <li>use the {@link #toCompletable(ListenableFuture, String, Function)}
     *       overload below, which inlines a validator into the
     *       {@code FutureCallback} so the user-visible future is the same
     *       future cancellation is bound to (this is what the {@code *Async}
     *       methods on {@link MxGatewayClient} and the unary methods on
     *       {@link GalaxyRepositoryClient} do); or</li>
     *   <li>follow {@link GalaxyRepositoryClient#discoverHierarchyAsync}'s
     *       pattern of returning a custom {@link CompletableFuture} subclass
     *       that tracks the current in-flight stage via an
     *       {@link java.util.concurrent.atomic.AtomicReference} and forwards
     *       {@code cancel(...)} to it (necessary when chaining
     *       {@code thenCompose} stages across paged calls).</li>
     * </ul>
     *
     * @param source the gRPC future-stub result
     * @param operation the operation name used in normalised error messages
     * @param <T> the reply type
     * @return a completable future mirroring the source
     */
    static <T> CompletableFuture<T> toCompletable(ListenableFuture<T> source, String operation) {
        CancellingCompletableFuture<T> target = new CancellingCompletableFuture<>(source);
        Futures.addCallback(
                source,
                new FutureCallback<>() {
                    @Override
                    public void onSuccess(T result) {
                        target.complete(result);
                    }
                    @Override
                    public void onFailure(Throwable error) {
                        if (error instanceof RuntimeException runtimeException) {
                            target.completeExceptionally(MxGatewayErrors.fromGrpc(operation, runtimeException));
                            return;
                        }
                        target.completeExceptionally(error);
                    }
                },
                MoreExecutors.directExecutor());
        return target;
    }
    /**
     * Bridges a Guava {@link ListenableFuture} to a {@link CompletableFuture}
     * and applies {@code validator} to the reply inline (i.e. without a
     * downstream {@code thenApply}), so the user-visible future is the same
     * future cancellation is bound to. Any non-{@link MxGatewayException}
     * {@link RuntimeException} thrown by {@code validator} is routed through
     * {@link MxGatewayErrors#fromGrpc} to match the synchronous error surface.
     *
     * <p>This overload exists because the prior {@code toCompletable(...)
     * .thenApply(validator)} pattern broke cancellation propagation: the
     * future returned by {@code thenApply} is a new stage whose cancellation
     * does not propagate to the underlying gRPC call. Using this overload, the
     * single returned future is the one users hold, so calling {@code cancel}
     * on it forwards to the source RPC.
     *
     * @param source the gRPC future-stub result
     * @param operation the operation name used in normalised error messages
     * @param validator the validating/transforming function applied to the reply
     * @param <T> the reply type
     * @param <R> the validated/transformed result type
     * @return a completable future mirroring the validated source
     */
    static <T, R> CompletableFuture<R> toCompletable(
            ListenableFuture<T> source, String operation, Function<T, R> validator) {
        CancellingCompletableFuture<R> target = new CancellingCompletableFuture<>(source);
        Futures.addCallback(
                source,
                new FutureCallback<>() {
                    @Override
                    public void onSuccess(T result) {
                        try {
                            target.complete(validator.apply(result));
                        } catch (MxGatewayException error) {
                            target.completeExceptionally(error);
                        } catch (RuntimeException error) {
                            target.completeExceptionally(MxGatewayErrors.fromGrpc(operation, error));
                        }
                    }
                    @Override
                    public void onFailure(Throwable error) {
                        if (error instanceof RuntimeException runtimeException) {
                            target.completeExceptionally(MxGatewayErrors.fromGrpc(operation, runtimeException));
                            return;
                        }
                        target.completeExceptionally(error);
                    }
                },
                MoreExecutors.directExecutor());
        return target;
    }
    /**
     * {@link CompletableFuture} subclass that forwards {@link #cancel(boolean)}
     * to a backing {@link ListenableFuture}. Used by {@link #toCompletable} so
     * cancelling the user-visible future cancels the underlying gRPC call.
     */
    static final class CancellingCompletableFuture<T> extends CompletableFuture<T> {
        private final ListenableFuture<?> source;
        CancellingCompletableFuture(ListenableFuture<?> source) {
            this.source = source;
        }
        @Override
        public boolean cancel(boolean mayInterruptIfRunning) {
            boolean cancelled = super.cancel(mayInterruptIfRunning);
            // Always forward; the source future is idempotent on cancel and the
            // user contract is that cancelling the future cancels the RPC.
            source.cancel(mayInterruptIfRunning);
            return cancelled;
        }
    }
    /**
     * Adapts a reply-validating function for use inside {@code thenApply} so
     * any non-{@link MxGatewayException} {@link RuntimeException} it raises is
     * routed through {@link MxGatewayErrors#fromGrpc}. This keeps the async
     * error surface consistent with the synchronous methods, which normalise
     * failures with a {@code try/catch}.
     *
     * @param operation the operation name used in normalised error messages
     * @param validator the validating/transforming function applied to the reply
     * @param <T> the reply type
     * @param <R> the result type
     * @return a function suitable for {@link CompletableFuture#thenApply}
     */
    static <T, R> Function<T, R> normalisingValidator(String operation, Function<T, R> validator) {
        return reply -> {
            try {
                return validator.apply(reply);
            } catch (MxGatewayException error) {
                throw error;
            } catch (RuntimeException error) {
                throw MxGatewayErrors.fromGrpc(operation, error);
            }
        };
    }
 }
@@ -1,67 +0,0 @@
 package com.dohertylan.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;
 /**
 * Cancellable handle returned by the async {@code streamEvents} variant.
 *
 * <p>Wraps a caller-supplied {@link StreamObserver} and exposes a
 * {@link #cancel()} entry point that aborts the underlying gRPC call. The
 * subscription also implements {@link AutoCloseable} so it can participate in
 * try-with-resources blocks.
 */
 public final class 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();
    }
 }
@@ -1,81 +0,0 @@
 package com.dohertylan.mxgateway.client;
 import java.util.regex.Pattern;
 /**
 * Helpers for redacting secrets such as gateway API keys from log output.
 *
 * <p>API keys must never reach logs in plaintext. The methods on this class
 * produce shortened, masked forms safe for diagnostic messages.
 */
 public final class MxGatewaySecrets {
    // Match any gateway-shaped credential anywhere in the string, regardless of
    // surrounding punctuation: quoted, colon/comma-delimited, embedded in URLs
    // or parens. The underscore-separated character class also covers a
    // trailing hyphen in case a future key format introduces one.
    private static final Pattern MXGW_TOKEN = Pattern.compile("mxgw_[A-Za-z0-9_-]+");
    // Mask the token after a Bearer marker as a unit so callers cannot
    // accidentally leak the secret when the surrounding text is a header-style
    // string (e.g. "Bearer mxgw_id_secret").
    private static final Pattern BEARER_TOKEN = Pattern.compile("(?i)bearer\\s+\\S+");
    private MxGatewaySecrets() {
    }
    /**
     * Redacts the secret portion of an API key, leaving only the non-secret
     * key identifier visible so the value remains comparable in logs.
     *
     * <p>A gateway API key has the form {@code mxgw_<key-id>_<secret>}. Only the
     * {@code mxgw_<key-id>_} prefix is non-secret; everything after the second
     * underscore is the secret and is masked entirely &mdash; no leading or
     * trailing characters of the secret are echoed. Tokens that do not match
     * the gateway shape are masked completely as {@code "<redacted>"}.
     *
     * @param apiKey the API key to redact, may be {@code null} or empty
     * @return an empty string for {@code null}/empty input, {@code "<redacted>"}
     *         for non-gateway-shaped tokens, or {@code mxgw_<key-id>_***} with the
     *         secret masked for gateway-shaped keys
     */
    public static String redactApiKey(String apiKey) {
        if (apiKey == null || apiKey.isEmpty()) {
            return "";
        }
        // Gateway keys are mxgw_<key-id>_<secret>; keep only the non-secret prefix.
        if (apiKey.startsWith("mxgw_")) {
            int secretSeparator = apiKey.indexOf('_', "mxgw_".length());
            if (secretSeparator >= 0 && secretSeparator < apiKey.length() - 1) {
                return apiKey.substring(0, secretSeparator + 1) + "***";
            }
        }
        // Anything else is treated as wholly secret — reveal nothing.
        return "<redacted>";
    }
    /**
     * Replaces gateway-style credential tokens inside a free-form string with a
     * redaction placeholder.
     *
     * <p>Matches any {@code mxgw_<...>} token anywhere in the string,
     * irrespective of surrounding punctuation (whitespace, colons, commas,
     * single/double quotes, parentheses, embedded URL paths). Also masks the
     * argument of an authorization-header style {@code Bearer <token>} marker
     * as a unit so the token cannot leak through when the surrounding string
     * is a raw header value.
     *
     * @param value the string to scrub, may be {@code null}
     * @return an empty string for {@code null}, the original value when blank,
     *         or the value with credential tokens replaced by {@code "<redacted>"}
     */
    public static String redactCredentials(String value) {
        if (value == null || value.isBlank()) {
            return value == null ? "" : value;
        }
        String scrubbed = MXGW_TOKEN.matcher(value).replaceAll("<redacted>");
        scrubbed = BEARER_TOKEN.matcher(scrubbed).replaceAll("Bearer <redacted>");
        return scrubbed;
    }
 }
@@ -1,182 +0,0 @@
 package com.dohertylan.mxgateway.client;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import io.grpc.CallOptions;
 import io.grpc.ClientCall;
 import io.grpc.ConnectivityState;
 import io.grpc.ManagedChannel;
 import io.grpc.MethodDescriptor;
 import java.time.Duration;
 import java.util.concurrent.TimeUnit;
 import org.junit.jupiter.api.Test;
 /**
 * Regression tests for the second-pass Low-severity Client.Java findings
 * Client.Java-016, Client.Java-019, and the shared shutdown helpers extracted
 * to {@link MxGatewayChannels}.
 */
 final class MxGatewayLowFindingsIITests {
    // --- Client.Java-019: shutdown timeout is independent of connect timeout ---
    @Test
    void shutdownAndAwaitTerminationHonoursShutdownTimeoutNotConnectTimeout() throws Exception {
        // The historical bug: close() used connectTimeout as the awaitTermination
        // deadline, so a small connectTimeout forced a premature shutdownNow()
        // on in-flight calls. The fix uses a dedicated shutdownTimeout. This
        // test verifies the helper waits up to shutdownTimeout (1s) even when
        // connectTimeout is set to a tiny value (50ms).
        RecordingChannel channel = new RecordingChannel(/* terminatesAfterMillis = */ 200);
        MxGatewayClientOptions options = MxGatewayClientOptions.builder()
                .endpoint("in-process")
                .plaintext(true)
                .connectTimeout(Duration.ofMillis(50))
                .shutdownTimeout(Duration.ofSeconds(1))
                .build();
        long start = System.nanoTime();
        MxGatewayChannels.shutdownAndAwaitTermination(channel, options);
        long elapsedMillis = (System.nanoTime() - start) / 1_000_000L;
        // The channel finished orderly termination within the shutdown timeout
        // window, so shutdownNow() must NOT have been called. With the old
        // implementation a 50ms connect-timeout-as-shutdown-deadline would
        // have escalated to shutdownNow() before the channel's 200ms graceful
        // termination completed.
        assertTrue(channel.shutdownCalled, "shutdown() must be called");
        assertFalse(
                channel.shutdownNowCalled,
                "graceful termination finished within shutdownTimeout; shutdownNow() must not have been called");
        // Allow ample slack for build-machine variance but assert we waited at
        // least the channel's graceful-termination window.
        assertTrue(elapsedMillis >= 150, "should have waited for graceful termination, elapsed=" + elapsedMillis);
    }
    @Test
    void shutdownEscalatesToShutdownNowWhenTimeoutExceeded() {
        // The other half of the contract: a channel that does not terminate
        // within the shutdownTimeout window must be forcibly shut down.
        RecordingChannel channel = new RecordingChannel(/* terminatesAfterMillis = */ 5_000);
        MxGatewayClientOptions options = MxGatewayClientOptions.builder()
                .endpoint("in-process")
                .plaintext(true)
                .shutdownTimeout(Duration.ofMillis(100))
                .build();
        MxGatewayChannels.shutdown(channel, options);
        assertTrue(channel.shutdownCalled);
        assertTrue(channel.shutdownNowCalled, "stuck channel must be forcibly shut down");
    }
    @Test
    void shutdownTimeoutDefaultIsTenSecondsIndependentOfConnectTimeout() {
        MxGatewayClientOptions defaults = MxGatewayClientOptions.builder()
                .endpoint("in-process")
                .build();
        // Default is 10s; an unset connectTimeout-of-10s default coincides but
        // the two are now independent options.
        assertEquals(Duration.ofSeconds(10), defaults.shutdownTimeout());
        MxGatewayClientOptions tinyConnect = MxGatewayClientOptions.builder()
                .endpoint("in-process")
                .connectTimeout(Duration.ofMillis(500))
                .build();
        assertEquals(Duration.ofSeconds(10), tinyConnect.shutdownTimeout(),
                "shutdownTimeout default is independent of connectTimeout");
    }
    // --- Client.Java-016: shared shutdown helpers behave identically for both clients ---
    @Test
    void sharedShutdownHelperIsNoOpForNullChannel() throws Exception {
        MxGatewayClientOptions options = MxGatewayClientOptions.builder()
                .endpoint("in-process")
                .plaintext(true)
                .shutdownTimeout(Duration.ofMillis(50))
                .build();
        // Both helpers must tolerate a null owned-channel (caller-managed channel case).
        MxGatewayChannels.shutdown(null, options);
        MxGatewayChannels.shutdownAndAwaitTermination(null, options);
    }
    /**
     * Test double for {@link ManagedChannel} that records {@code shutdown}/
     * {@code shutdownNow} invocations and simulates an orderly termination
     * after a configurable delay. Avoids the heavy in-process gRPC machinery —
     * the shutdown helpers only touch the three lifecycle methods.
     */
    private static final class RecordingChannel extends ManagedChannel {
        private final long terminatesAfterMillis;
        private final long createdAtNanos;
        private volatile boolean shutdownCalled;
        private volatile boolean shutdownNowCalled;
        RecordingChannel(long terminatesAfterMillis) {
            this.terminatesAfterMillis = terminatesAfterMillis;
            this.createdAtNanos = System.nanoTime();
        }
        @Override
        public ManagedChannel shutdown() {
            shutdownCalled = true;
            return this;
        }
        @Override
        public boolean isShutdown() {
            return shutdownCalled || shutdownNowCalled;
        }
        @Override
        public boolean isTerminated() {
            if (shutdownNowCalled) {
                return true;
            }
            if (!shutdownCalled) {
                return false;
            }
            long elapsed = (System.nanoTime() - createdAtNanos) / 1_000_000L;
            return elapsed >= terminatesAfterMillis;
        }
        @Override
        public ManagedChannel shutdownNow() {
            shutdownNowCalled = true;
            return this;
        }
        @Override
        public boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedException {
            long deadlineNanos = System.nanoTime() + unit.toNanos(timeout);
            while (System.nanoTime() < deadlineNanos) {
                if (isTerminated()) {
                    return true;
                }
                long remaining = Math.max(1, (deadlineNanos - System.nanoTime()) / 1_000_000L);
                Thread.sleep(Math.min(remaining, 10));
            }
            return isTerminated();
        }
        @Override
        public <RequestT, ResponseT> ClientCall<RequestT, ResponseT> newCall(
                MethodDescriptor<RequestT, ResponseT> methodDescriptor, CallOptions callOptions) {
            throw new UnsupportedOperationException("no RPCs are issued in shutdown tests");
        }
        @Override
        public String authority() {
            return "in-process";
        }
        @Override
        public ConnectivityState getState(boolean requestConnection) {
            return ConnectivityState.IDLE;
        }
    }
 }
@@ -1,509 +0,0 @@
 package com.dohertylan.mxgateway.client;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import io.grpc.ManagedChannel;
 import io.grpc.Server;
 import io.grpc.Status;
 import io.grpc.inprocess.InProcessChannelBuilder;
 import io.grpc.inprocess.InProcessServerBuilder;
 import io.grpc.stub.ClientCallStreamObserver;
 import io.grpc.stub.ClientResponseObserver;
 import io.grpc.stub.StreamObserver;
 import java.nio.file.Path;
 import java.time.Duration;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CompletionException;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicReference;
 import mxaccess_gateway.v1.MxAccessGatewayGrpc;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest;
 import mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot;
 import mxaccess_gateway.v1.MxaccessGateway.AlarmConditionState;
 import mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage;
 import mxaccess_gateway.v1.MxaccessGateway.MxEvent;
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatusCode;
 import mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest;
 import mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest;
 import org.junit.jupiter.api.Test;
 /**
 * Regression tests for the Low-severity Client.Java code-review findings
 * (Client.Java-006 through Client.Java-012). Covers the alarm RPC surface,
 * async streaming/subscription cancellation, queue overflow, and TLS-config
 * construction that Client.Java-007 reports as untested.
 */
 final class MxGatewayLowFindingsTests {
    // --- Client.Java-007: AcknowledgeAlarm RPC coverage ---
    @Test
    void acknowledgeAlarmReturnsReplyAndSendsAuthMetadata() throws Exception {
        AtomicReference<String> authorization = new AtomicReference<>();
        AtomicReference<AcknowledgeAlarmRequest> seen = new AtomicReference<>();
        TestService service = new TestService() {
            @Override
            public void acknowledgeAlarm(
                    AcknowledgeAlarmRequest request, StreamObserver<AcknowledgeAlarmReply> responseObserver) {
                seen.set(request);
                responseObserver.onNext(AcknowledgeAlarmReply.newBuilder()
                        .setProtocolStatus(ok())
                        .setDiagnosticMessage("acked")
                        .build());
                responseObserver.onCompleted();
            }
        };
        try (Harness harness = Harness.start(service, "mxgw_keyid_secret", authorization)) {
            AcknowledgeAlarmReply reply = harness.client().acknowledgeAlarm(AcknowledgeAlarmRequest.newBuilder()
                    .setAlarmFullReference("Area1.Pump.PV.HiHi")
                    .setComment("operator note")
                    .build());
            assertEquals("acked", reply.getDiagnosticMessage());
            assertEquals("Area1.Pump.PV.HiHi", seen.get().getAlarmFullReference());
            assertEquals("Bearer mxgw_keyid_secret", authorization.get());
        }
    }
    @Test
    void acknowledgeAlarmThrowsTypedExceptionOnProtocolFailure() throws Exception {
        TestService service = new TestService() {
            @Override
            public void acknowledgeAlarm(
                    AcknowledgeAlarmRequest request, StreamObserver<AcknowledgeAlarmReply> responseObserver) {
                responseObserver.onNext(AcknowledgeAlarmReply.newBuilder()
                        .setProtocolStatus(ProtocolStatus.newBuilder()
                                .setCode(ProtocolStatusCode.PROTOCOL_STATUS_CODE_SESSION_NOT_FOUND))
                        .build());
                responseObserver.onCompleted();
            }
        };
        try (Harness harness = Harness.start(service)) {
            assertThrows(
                    MxGatewayException.class,
                    () -> harness.client().acknowledgeAlarm(AcknowledgeAlarmRequest.newBuilder()
                            .setAlarmFullReference("Area1.Pump.PV.HiHi")
                            .build()));
        }
    }
    @Test
    void acknowledgeAlarmAsyncCompletesWithReply() throws Exception {
        TestService service = new TestService() {
            @Override
            public void acknowledgeAlarm(
                    AcknowledgeAlarmRequest request, StreamObserver<AcknowledgeAlarmReply> responseObserver) {
                responseObserver.onNext(AcknowledgeAlarmReply.newBuilder()
                        .setProtocolStatus(ok())
                        .setDiagnosticMessage("async-acked")
                        .build());
                responseObserver.onCompleted();
            }
        };
        try (Harness harness = Harness.start(service)) {
            CompletableFuture<AcknowledgeAlarmReply> future = harness.client()
                    .acknowledgeAlarmAsync(AcknowledgeAlarmRequest.newBuilder()
                            .setAlarmFullReference("Area1.Pump.PV.HiHi")
                            .build());
            assertEquals("async-acked", future.get(5, TimeUnit.SECONDS).getDiagnosticMessage());
        }
    }
    @Test
    void acknowledgeAlarmAsyncFailsExceptionallyWithTypedException() throws Exception {
        TestService service = new TestService() {
            @Override
            public void acknowledgeAlarm(
                    AcknowledgeAlarmRequest request, StreamObserver<AcknowledgeAlarmReply> responseObserver) {
                responseObserver.onError(Status.UNAVAILABLE.withDescription("worker down").asRuntimeException());
            }
        };
        try (Harness harness = Harness.start(service)) {
            CompletableFuture<AcknowledgeAlarmReply> future = harness.client()
                    .acknowledgeAlarmAsync(AcknowledgeAlarmRequest.newBuilder()
                            .setAlarmFullReference("Area1.Pump.PV.HiHi")
                            .build());
            ExecutionException error = assertThrows(
                    ExecutionException.class, () -> future.get(5, TimeUnit.SECONDS));
            assertTrue(error.getCause() instanceof MxGatewayException, () -> String.valueOf(error.getCause()));
        }
    }
    // --- Client.Java-007: StreamAlarms RPC + subscription coverage ---
    @Test
    void streamAlarmsDeliversFeedMessagesToObserver() throws Exception {
        AlarmFeedMessage active = AlarmFeedMessage.newBuilder()
                .setActiveAlarm(ActiveAlarmSnapshot.newBuilder()
                        .setAlarmFullReference("Area1.Tank.Level.Hi")
                        .setSeverity(800)
                        .setCurrentState(AlarmConditionState.ALARM_CONDITION_STATE_ACTIVE))
                .build();
        AlarmFeedMessage snapshotComplete =
                AlarmFeedMessage.newBuilder().setSnapshotComplete(true).build();
        TestService service = new TestService() {
            @Override
            public void streamAlarms(
                    StreamAlarmsRequest request, StreamObserver<AlarmFeedMessage> responseObserver) {
                responseObserver.onNext(active);
                responseObserver.onNext(snapshotComplete);
                responseObserver.onCompleted();
            }
        };
        try (Harness harness = Harness.start(service)) {
            List<AlarmFeedMessage> received = new ArrayList<>();
            CountDownLatch done = new CountDownLatch(1);
            harness.client().streamAlarms(
                    StreamAlarmsRequest.newBuilder().build(),
                    new StreamObserver<>() {
                        @Override
                        public void onNext(AlarmFeedMessage value) {
                            received.add(value);
                        }
                        @Override
                        public void onError(Throwable t) {
                            done.countDown();
                        }
                        @Override
                        public void onCompleted() {
                            done.countDown();
                        }
                    });
            assertTrue(done.await(5, TimeUnit.SECONDS), "stream should complete");
            assertEquals(2, received.size());
            assertEquals("Area1.Tank.Level.Hi", received.get(0).getActiveAlarm().getAlarmFullReference());
            assertTrue(received.get(1).getSnapshotComplete());
        }
    }
    @Test
    void alarmFeedSubscriptionCancelBeforeBeforeStartCancelsStream() {
        MxGatewayAlarmFeedSubscription subscription = new MxGatewayAlarmFeedSubscription();
        ClientResponseObserver<StreamAlarmsRequest, AlarmFeedMessage> observer =
                subscription.wrap(new StreamObserver<>() {
                    @Override
                    public void onNext(AlarmFeedMessage value) {
                    }
                    @Override
                    public void onError(Throwable t) {
                    }
                    @Override
                    public void onCompleted() {
                    }
                });
        RecordingAlarmFeedRequestStream requestStream = new RecordingAlarmFeedRequestStream();
        subscription.cancel();
        observer.beforeStart(requestStream);
        assertTrue(requestStream.cancelled);
        assertEquals("client cancelled alarm feed", requestStream.cancelMessage);
    }
    // --- Client.Java-007: async streamEvents + subscription cancellation ---
    @Test
    void streamEventsAsyncDeliversEventsToObserver() throws Exception {
        MxEvent event = MxEvent.newBuilder().setWorkerSequence(7).build();
        TestService service = new TestService() {
            @Override
            public void streamEvents(StreamEventsRequest request, StreamObserver<MxEvent> responseObserver) {
                responseObserver.onNext(event);
                responseObserver.onCompleted();
            }
        };
        try (Harness harness = Harness.start(service)) {
            List<MxEvent> received = new ArrayList<>();
            CountDownLatch done = new CountDownLatch(1);
            harness.client().streamEventsAsync(
                    StreamEventsRequest.newBuilder().setSessionId("s-5").build(),
                    new StreamObserver<>() {
                        @Override
                        public void onNext(MxEvent value) {
                            received.add(value);
                        }
                        @Override
                        public void onError(Throwable t) {
                            done.countDown();
                        }
                        @Override
                        public void onCompleted() {
                            done.countDown();
                        }
                    });
            assertTrue(done.await(5, TimeUnit.SECONDS), "stream should complete");
            assertEquals(1, received.size());
            assertEquals(7, received.get(0).getWorkerSequence());
        }
    }
    @Test
    void eventSubscriptionCancelBeforeBeforeStartCancelsStream() {
        MxGatewayEventSubscription subscription = new MxGatewayEventSubscription();
        ClientResponseObserver<StreamEventsRequest, MxEvent> observer =
                subscription.wrap(new StreamObserver<>() {
                    @Override
                    public void onNext(MxEvent value) {
                    }
                    @Override
                    public void onError(Throwable t) {
                    }
                    @Override
                    public void onCompleted() {
                    }
                });
        RecordingEventsRequestStream requestStream = new RecordingEventsRequestStream();
        subscription.cancel();
        observer.beforeStart(requestStream);
        assertTrue(requestStream.cancelled);
        assertEquals("client cancelled event stream", requestStream.cancelMessage);
    }
    // --- Client.Java-007 / Client.Java-011: MxEventStream queue overflow ---
    @Test
    void eventStreamQueueOverflowSurfacesExceptionFromNext() {
        MxEventStream stream = new MxEventStream(2);
        ClientResponseObserver<StreamEventsRequest, MxEvent> observer = stream.observer();
        RecordingEventsRequestStream requestStream = new RecordingEventsRequestStream();
        observer.beforeStart(requestStream);
        // Push far more events than the capacity-2 buffer can hold without draining.
        for (int i = 0; i < 16; i++) {
            observer.onNext(MxEvent.newBuilder().setWorkerSequence(i).build());
        }
        // Overflow must cancel the gRPC call and surface as MxGatewayException.
        assertTrue(requestStream.cancelled, "overflow should cancel the underlying call");
        MxGatewayException error = assertThrows(MxGatewayException.class, () -> {
            while (stream.hasNext()) {
                stream.next();
            }
        });
        assertTrue(error.getMessage().contains("overflow"), error::getMessage);
    }
    // --- Client.Java-007: TLS channel construction ---
    @Test
    void connectWithMissingCaCertificateThrowsTypedTlsException() {
        MxGatewayClientOptions options = MxGatewayClientOptions.builder()
                .endpoint("localhost:5001")
                .apiKey("mxgw_id_secret")
                .plaintext(false)
                .caCertificatePath(Path.of("does-not-exist-" + UUID.randomUUID() + ".pem"))
                .build();
        MxGatewayException error = assertThrows(MxGatewayException.class, () -> MxGatewayClient.connect(options));
        assertTrue(error.getMessage().contains("TLS"), error::getMessage);
        MxGatewayException galaxyError =
                assertThrows(MxGatewayException.class, () -> GalaxyRepositoryClient.connect(options));
        assertTrue(galaxyError.getMessage().contains("TLS"), galaxyError::getMessage);
    }
    @Test
    void connectWithSystemTrustBuildsTlsChannelWithoutError() {
        // No CA path and plaintext=false exercises the useTransportSecurity() branch.
        MxGatewayClientOptions options = MxGatewayClientOptions.builder()
                .endpoint("localhost:5001")
                .apiKey("mxgw_id_secret")
                .plaintext(false)
                .build();
        try (MxGatewayClient client = MxGatewayClient.connect(options)) {
            assertNotNull(client);
        }
        try (GalaxyRepositoryClient galaxy = GalaxyRepositoryClient.connect(options)) {
            assertNotNull(galaxy);
        }
    }
    // --- Client.Java-008: async error surface is normalised ---
    @Test
    void openSessionAsyncNormalisesNonGatewayRuntimeExceptionFromValidator() {
        // ensureGatewayProtocolCompatible already throws MxGatewayException; this verifies
        // the normalisingValidator wrapper routes a stray RuntimeException through fromGrpc.
        CompletableFuture<String> source = new CompletableFuture<>();
        CompletableFuture<String> wrapped =
                source.thenApply(MxGatewayChannels.normalisingValidator("open session", reply -> {
                    throw new IllegalStateException("malformed reply");
                }));
        source.complete("payload");
        CompletionException error = assertThrows(CompletionException.class, wrapped::join);
        assertTrue(error.getCause() instanceof MxGatewayException, () -> String.valueOf(error.getCause()));
    }
    private static ProtocolStatus ok() {
        return ProtocolStatus.newBuilder()
                .setCode(ProtocolStatusCode.PROTOCOL_STATUS_CODE_OK)
                .build();
    }
    private static class TestService extends MxAccessGatewayGrpc.MxAccessGatewayImplBase {
    }
    private record Harness(Server server, ManagedChannel channel, MxGatewayClient client) implements AutoCloseable {
        static Harness start(MxAccessGatewayGrpc.MxAccessGatewayImplBase service) throws Exception {
            return start(service, "", new AtomicReference<>());
        }
        static Harness start(
                MxAccessGatewayGrpc.MxAccessGatewayImplBase service,
                String apiKey,
                AtomicReference<String> authorization)
                throws Exception {
            String name = "mxgw-low-" + UUID.randomUUID();
            io.grpc.ServerInterceptor interceptor = new io.grpc.ServerInterceptor() {
                @Override
                public <ReqT, RespT> io.grpc.ServerCall.Listener<ReqT> interceptCall(
                        io.grpc.ServerCall<ReqT, RespT> call,
                        io.grpc.Metadata headers,
                        io.grpc.ServerCallHandler<ReqT, RespT> next) {
                    authorization.set(headers.get(MxGatewayAuthInterceptor.AUTHORIZATION_HEADER));
                    return next.startCall(call, headers);
                }
            };
            Server server = InProcessServerBuilder.forName(name)
                    .directExecutor()
                    .addService(io.grpc.ServerInterceptors.intercept(service, interceptor))
                    .build()
                    .start();
            ManagedChannel channel = InProcessChannelBuilder.forName(name).directExecutor().build();
            MxGatewayClient client = new MxGatewayClient(
                    channel,
                    MxGatewayClientOptions.builder()
                            .endpoint("in-process")
                            .apiKey(apiKey)
                            .plaintext(true)
                            .callTimeout(Duration.ofSeconds(5))
                            .streamTimeout(Duration.ofSeconds(5))
                            .build());
            return new Harness(server, channel, client);
        }
        @Override
        public void close() {
            channel.shutdownNow();
            server.shutdownNow();
        }
    }
    private static final class RecordingEventsRequestStream
            extends ClientCallStreamObserver<StreamEventsRequest> {
        private boolean cancelled;
        private String cancelMessage;
        @Override
        public void cancel(String message, Throwable cause) {
            cancelled = true;
            cancelMessage = message;
        }
        @Override
        public boolean isReady() {
            return true;
        }
        @Override
        public void setOnReadyHandler(Runnable onReadyHandler) {
        }
        @Override
        public void request(int count) {
        }
        @Override
        public void setMessageCompression(boolean enable) {
        }
        @Override
        public void disableAutoInboundFlowControl() {
        }
        @Override
        public void onNext(StreamEventsRequest value) {
        }
        @Override
        public void onError(Throwable t) {
        }
        @Override
        public void onCompleted() {
        }
    }
    private static final class RecordingAlarmFeedRequestStream
            extends ClientCallStreamObserver<StreamAlarmsRequest> {
        private boolean cancelled;
        private String cancelMessage;
        @Override
        public void cancel(String message, Throwable cause) {
            cancelled = true;
            cancelMessage = message;
        }
        @Override
        public boolean isReady() {
            return true;
        }
        @Override
        public void setOnReadyHandler(Runnable onReadyHandler) {
        }
        @Override
        public void request(int count) {
        }
        @Override
        public void setMessageCompression(boolean enable) {
        }
        @Override
        public void disableAutoInboundFlowControl() {
        }
        @Override
        public void onNext(StreamAlarmsRequest value) {
        }
        @Override
        public void onError(Throwable t) {
        }
        @Override
        public void onCompleted() {
        }
    }
 }
@@ -1,527 +0,0 @@
 package com.dohertylan.mxgateway.client;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import io.grpc.ManagedChannel;
 import io.grpc.Server;
 import io.grpc.inprocess.InProcessChannelBuilder;
 import io.grpc.inprocess.InProcessServerBuilder;
 import io.grpc.stub.StreamObserver;
 import java.time.Duration;
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 import mxaccess_gateway.v1.MxAccessGatewayGrpc;
 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.OpenSessionReply;
 import mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest;
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
 import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatusCode;
 import org.junit.jupiter.api.Test;
 /**
 * Regression tests for the Medium-severity Client.Java code-review findings
 * (Client.Java-001 through Client.Java-005, and Client.Java-014/015).
 */
 final class MxGatewayMediumFindingsTests {
    // --- Client.Java-001: redactApiKey must not leak trailing secret chars ---
    @Test
    void redactApiKeyDoesNotLeakAnyCharacterOfTheSecret() {
        // mxgw_<key-id>_<secret> — the secret is the segment after the second underscore.
        String apiKey = "mxgw_keyid01_supersecretvalue";
        String redacted = MxGatewaySecrets.redactApiKey(apiKey);
        // None of the secret characters may appear in the redacted output.
        assertFalse(redacted.contains("value"), () -> "redacted form leaked secret tail: " + redacted);
        assertFalse(redacted.endsWith("alue"), () -> "redacted form leaked trailing secret chars: " + redacted);
        assertFalse(redacted.contains("supersecret"), () -> "redacted form leaked secret: " + redacted);
        // The non-secret key-id prefix may stay so the value is still comparable in logs.
        assertTrue(redacted.startsWith("mxgw_keyid01_"), () -> "redacted form lost key-id prefix: " + redacted);
    }
    @Test
    void redactApiKeyForNonGatewayShapedKeyRevealsNothing() {
        String redacted = MxGatewaySecrets.redactApiKey("plain-opaque-token-1234");
        assertFalse(redacted.contains("1234"), () -> "redacted form leaked trailing chars: " + redacted);
        assertFalse(redacted.contains("plain-opaque-token"), () -> "redacted form leaked body: " + redacted);
    }
    @Test
    void redactApiKeyStillHandlesNullAndShortInput() {
        assertEquals("", MxGatewaySecrets.redactApiKey(null));
        assertEquals("", MxGatewaySecrets.redactApiKey(""));
        assertEquals("<redacted>", MxGatewaySecrets.redactApiKey("short"));
    }
    // --- Client.Java-002: terminal-state transition must be deterministic ---
    @Test
    void eventStreamOverflowExceptionSurvivesASubsequentClose() {
        // Deterministic reproduction of Client.Java-002: an overflow enqueues the
        // overflow exception, then a later close() must NOT discard it. The first
        // terminal condition (overflow) must win and stay observable by next().
        MxEventStream stream = new MxEventStream(2);
        io.grpc.stub.ClientResponseObserver<
                        mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest,
                        mxaccess_gateway.v1.MxaccessGateway.MxEvent>
                observer = stream.observer();
        observer.beforeStart(new NoopRequestStream());
        // Force a queue overflow on a capacity-2 stream.
        for (int i = 0; i < 8; i++) {
            observer.onNext(testEvent(i));
        }
        // A close() arriving after the overflow must not erase the overflow signal.
        stream.close();
        MxGatewayException error = assertThrows(MxGatewayException.class, () -> {
            while (stream.hasNext()) {
                stream.next();
            }
        });
        assertTrue(error.getMessage().contains("overflow"), error::getMessage);
    }
    @Test
    void eventStreamConcurrentOverflowAndCloseAlwaysTerminate() throws Exception {
        // The terminal-state transition must be serialised: whatever the interleaving
        // of overflow and close, hasNext() always reaches a terminal state.
        for (int iteration = 0; iteration < 300; iteration++) {
            MxEventStream stream = new MxEventStream(2);
            io.grpc.stub.ClientResponseObserver<
                            mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest,
                            mxaccess_gateway.v1.MxaccessGateway.MxEvent>
                    observer = stream.observer();
            observer.beforeStart(new NoopRequestStream());
            Thread filler = new Thread(() -> {
                for (int i = 0; i < 8; i++) {
                    observer.onNext(testEvent(i));
                }
            });
            Thread closer = new Thread(stream::close);
            filler.start();
            closer.start();
            filler.join();
            closer.join();
            try {
                while (stream.hasNext()) {
                    stream.next();
                }
            } catch (MxGatewayException expected) {
                assertTrue(expected.getMessage().contains("overflow"), expected::getMessage);
            }
            assertFalse(stream.hasNext());
        }
    }
    private static final class NoopRequestStream
            extends io.grpc.stub.ClientCallStreamObserver<mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest> {
        @Override
        public void cancel(String message, Throwable cause) {
        }
        @Override
        public boolean isReady() {
            return true;
        }
        @Override
        public void setOnReadyHandler(Runnable onReadyHandler) {
        }
        @Override
        public void request(int count) {
        }
        @Override
        public void setMessageCompression(boolean enable) {
        }
        @Override
        public void disableAutoInboundFlowControl() {
        }
        @Override
        public void onNext(mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest value) {
        }
        @Override
        public void onError(Throwable t) {
        }
        @Override
        public void onCompleted() {
        }
    }
    // --- Client.Java-003: gateway protocol version mismatch must be rejected ---
    @Test
    void openSessionRejectsIncompatibleGatewayProtocolVersion() throws Exception {
        TestService service = new TestService() {
            @Override
            public void openSession(OpenSessionRequest request, StreamObserver<OpenSessionReply> responseObserver) {
                responseObserver.onNext(OpenSessionReply.newBuilder()
                        .setSessionId("session-mismatch")
                        .setGatewayProtocolVersion(MxGatewayClientVersion.gatewayProtocolVersion() + 1)
                        .setProtocolStatus(ok())
                        .build());
                responseObserver.onCompleted();
            }
        };
        try (Harness harness = Harness.start(service)) {
            MxGatewayException error = assertThrows(
                    MxGatewayException.class,
                    () -> harness.client().openSession("junit-session"));
            assertTrue(error.getMessage().contains("protocol version"), error::getMessage);
        }
    }
    @Test
    void openSessionAcceptsMatchingOrUnsetGatewayProtocolVersion() throws Exception {
        TestService matching = new TestService() {
            @Override
            public void openSession(OpenSessionRequest request, StreamObserver<OpenSessionReply> responseObserver) {
                responseObserver.onNext(OpenSessionReply.newBuilder()
                        .setSessionId("session-ok")
                        .setGatewayProtocolVersion(MxGatewayClientVersion.gatewayProtocolVersion())
                        .setProtocolStatus(ok())
                        .build());
                responseObserver.onCompleted();
            }
        };
        try (Harness harness = Harness.start(matching)) {
            assertEquals("session-ok", harness.client().openSession("junit-session").sessionId());
        }
        // A gateway that leaves the field unset (0) must not be rejected — older gateways
        // simply do not populate it.
        TestService unset = new TestService();
        try (Harness harness = Harness.start(unset)) {
            assertEquals("session-java", harness.client().openSession("junit-session").sessionId());
        }
    }
    // --- Client.Java-004: missing typed payload AND missing return_value must throw ---
    @Test
    void registerThrowsWhenReplyHasNeitherTypedPayloadNorReturnValue() throws Exception {
        TestService service = new TestService() {
            @Override
            public void invoke(MxCommandRequest request, StreamObserver<MxCommandReply> responseObserver) {
                // Reply with neither register payload nor return_value set.
                responseObserver.onNext(MxCommandReply.newBuilder()
                        .setSessionId(request.getSessionId())
                        .setKind(request.getCommand().getKind())
                        .setProtocolStatus(ok())
                        .build());
                responseObserver.onCompleted();
            }
        };
        try (Harness harness = Harness.start(service)) {
            MxGatewaySession session = MxGatewaySession.forSessionId(harness.client(), "s");
            MxGatewayException error = assertThrows(
                    MxGatewayException.class, () -> session.register("c"));
            assertTrue(error.getMessage().contains("register"), error::getMessage);
        }
    }
    @Test
    void addItemThrowsWhenReplyHasNeitherTypedPayloadNorReturnValue() throws Exception {
        TestService service = new TestService() {
            @Override
            public void invoke(MxCommandRequest request, StreamObserver<MxCommandReply> responseObserver) {
                responseObserver.onNext(MxCommandReply.newBuilder()
                        .setSessionId(request.getSessionId())
                        .setKind(request.getCommand().getKind())
                        .setProtocolStatus(ok())
                        .build());
                responseObserver.onCompleted();
            }
        };
        try (Harness harness = Harness.start(service)) {
            MxGatewaySession session = MxGatewaySession.forSessionId(harness.client(), "s");
            assertThrows(MxGatewayException.class, () -> session.addItem(1, "Tag"));
            assertThrows(MxGatewayException.class, () -> session.addItem2(1, "Tag", "ctx"));
        }
    }
    @Test
    void addItemStillHonoursReturnValueFallback() throws Exception {
        TestService service = new TestService() {
            @Override
            public void invoke(MxCommandRequest request, StreamObserver<MxCommandReply> responseObserver) {
                responseObserver.onNext(MxCommandReply.newBuilder()
                        .setSessionId(request.getSessionId())
                        .setKind(request.getCommand().getKind())
                        .setProtocolStatus(ok())
                        .setReturnValue(mxaccess_gateway.v1.MxaccessGateway.MxValue.newBuilder()
                                .setInt32Value(99))
                        .build());
                responseObserver.onCompleted();
            }
        };
        try (Harness harness = Harness.start(service)) {
            MxGatewaySession session = MxGatewaySession.forSessionId(harness.client(), "s");
            assertEquals(99, session.addItem(1, "Tag"));
        }
    }
    // --- Client.Java-005: close() must not mask the primary try-with-resources error ---
    @Test
    void closeSuppressesCloseTimeFailureInsteadOfMaskingBodyException() throws Exception {
        TestService service = new TestService() {
            @Override
            public void closeSession(CloseSessionRequest request, StreamObserver<CloseSessionReply> responseObserver) {
                responseObserver.onError(io.grpc.Status.UNAVAILABLE
                        .withDescription("WORKER_UNAVAILABLE")
                        .asRuntimeException());
            }
        };
        try (Harness harness = Harness.start(service)) {
            IllegalStateException bodyError = assertThrows(IllegalStateException.class, () -> {
                try (MxGatewaySession session = MxGatewaySession.forSessionId(harness.client(), "s")) {
                    throw new IllegalStateException("body failure");
                }
            });
            // The body exception must propagate; the close-time RPC failure must not replace it.
            assertEquals("body failure", bodyError.getMessage());
        }
    }
    @Test
    void closeRawStillSurfacesCloseTimeFailureForCallersWhoWantIt() throws Exception {
        TestService service = new TestService() {
            @Override
            public void closeSession(CloseSessionRequest request, StreamObserver<CloseSessionReply> responseObserver) {
                responseObserver.onError(io.grpc.Status.UNAVAILABLE
                        .withDescription("WORKER_UNAVAILABLE")
                        .asRuntimeException());
            }
        };
        try (Harness harness = Harness.start(service)) {
            MxGatewaySession session = MxGatewaySession.forSessionId(harness.client(), "s");
            assertThrows(MxGatewayException.class, session::closeRaw);
        }
    }
    // --- Client.Java-014: MxEventStream.close() before beforeStart must cancel the call ---
    @Test
    void mxEventStreamCloseBeforeBeforeStartCancelsStream() {
        // Mirrors GalaxyRepositoryClientTests.deployEventStreamCloseBeforeBeforeStartCancelsStream:
        // if close() runs before the gRPC call has attached its ClientCallStreamObserver,
        // beforeStart() must observe the prior close and cancel the underlying call so the
        // gRPC subscription does not leak open after the consumer has stopped iterating.
        MxEventStream stream = new MxEventStream(4);
        io.grpc.stub.ClientResponseObserver<
                        mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest,
                        mxaccess_gateway.v1.MxaccessGateway.MxEvent>
                observer = stream.observer();
        RecordingEventsRequestStream requestStream = new RecordingEventsRequestStream();
        stream.close();
        observer.beforeStart(requestStream);
        assertTrue(requestStream.cancelled, "beforeStart must cancel the underlying call after a prior close()");
        assertEquals("client cancelled event stream", requestStream.cancelMessage);
        assertFalse(stream.hasNext());
    }
    // --- Client.Java-015: cancelling the user-visible *Async future cancels the gRPC call ---
    @Test
    void invokeAsyncCancellationCancelsUnderlyingGrpcCall() throws Exception {
        // Set up a gateway service that never completes the invoke call so cancellation is
        // the only way the call terminates. Hook ServerCallStreamObserver.setOnCancelHandler
        // to latch when the server observes cancellation.
        java.util.concurrent.CountDownLatch serverCancelled = new java.util.concurrent.CountDownLatch(1);
        TestService service = new TestService() {
            @Override
            public void invoke(MxCommandRequest request, StreamObserver<MxCommandReply> responseObserver) {
                io.grpc.stub.ServerCallStreamObserver<MxCommandReply> serverObserver =
                        (io.grpc.stub.ServerCallStreamObserver<MxCommandReply>) responseObserver;
                serverObserver.setOnCancelHandler(serverCancelled::countDown);
                // Intentionally never complete — the call must be terminated by the client
                // cancelling its future, which must propagate to the gRPC cancellation.
            }
        };
        try (Harness harness = Harness.start(service)) {
            CompletableFuture<MxCommandReply> future = harness.client().invokeAsync(MxCommandRequest.newBuilder()
                    .setSessionId("s-cancel")
                    .setCommand(mxaccess_gateway.v1.MxaccessGateway.MxCommand.newBuilder()
                            .setKind(MxCommandKind.MX_COMMAND_KIND_REGISTER))
                    .build());
            // Cancellation of the user-visible future must propagate to the gRPC call.
            assertTrue(future.cancel(true), "cancel(true) should return true on a pending future");
            assertTrue(
                    serverCancelled.await(5, java.util.concurrent.TimeUnit.SECONDS),
                    "server must observe RPC cancellation after future.cancel(true)");
        }
    }
    @Test
    void toCompletableValidatorOverloadForwardsCancellationToSource() {
        // Unit-level proof: cancel() on the future returned by the validator-aware
        // toCompletable overload must call cancel(true) on the source ListenableFuture.
        // This is the core fix for Client.Java-015 — the validator runs inside
        // toCompletable instead of via .thenApply, so the user holds the future
        // that is bound to the source.
        com.google.common.util.concurrent.SettableFuture<String> source =
                com.google.common.util.concurrent.SettableFuture.create();
        java.util.concurrent.CompletableFuture<Integer> target =
                MxGatewayChannels.toCompletable(source, "noop", String::length);
        assertFalse(source.isCancelled());
        assertTrue(target.cancel(true));
        assertTrue(source.isCancelled(), "source ListenableFuture must be cancelled");
    }
    @Test
    void toCompletableNoValidatorOverloadForwardsCancellationToSource() {
        // Regression for the no-validator overload (the historic toCompletable shape).
        com.google.common.util.concurrent.SettableFuture<String> source =
                com.google.common.util.concurrent.SettableFuture.create();
        java.util.concurrent.CompletableFuture<String> target = MxGatewayChannels.toCompletable(source, "noop");
        assertFalse(source.isCancelled());
        assertTrue(target.cancel(true));
        assertTrue(source.isCancelled(), "source ListenableFuture must be cancelled");
    }
    private static final class RecordingEventsRequestStream
            extends io.grpc.stub.ClientCallStreamObserver<
                    mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest> {
        private boolean cancelled;
        private String cancelMessage;
        @Override
        public void cancel(String message, Throwable cause) {
            cancelled = true;
            cancelMessage = message;
        }
        @Override
        public boolean isReady() {
            return true;
        }
        @Override
        public void setOnReadyHandler(Runnable onReadyHandler) {
        }
        @Override
        public void request(int count) {
        }
        @Override
        public void setMessageCompression(boolean enable) {
        }
        @Override
        public void disableAutoInboundFlowControl() {
        }
        @Override
        public void onNext(mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest value) {
        }
        @Override
        public void onError(Throwable t) {
        }
        @Override
        public void onCompleted() {
        }
    }
    private static mxaccess_gateway.v1.MxaccessGateway.MxEvent testEvent(int sequence) {
        return mxaccess_gateway.v1.MxaccessGateway.MxEvent.newBuilder()
                .setWorkerSequence(sequence)
                .build();
    }
    private static ProtocolStatus ok() {
        return ProtocolStatus.newBuilder()
                .setCode(ProtocolStatusCode.PROTOCOL_STATUS_CODE_OK)
                .build();
    }
    private static class TestService extends MxAccessGatewayGrpc.MxAccessGatewayImplBase {
        @Override
        public void openSession(OpenSessionRequest request, StreamObserver<OpenSessionReply> responseObserver) {
            responseObserver.onNext(OpenSessionReply.newBuilder()
                    .setSessionId("session-java")
                    .setProtocolStatus(ok())
                    .build());
            responseObserver.onCompleted();
        }
        @Override
        public void closeSession(CloseSessionRequest request, StreamObserver<CloseSessionReply> responseObserver) {
            responseObserver.onNext(CloseSessionReply.newBuilder()
                    .setSessionId(request.getSessionId())
                    .setProtocolStatus(ok())
                    .build());
            responseObserver.onCompleted();
        }
        @Override
        public void invoke(MxCommandRequest request, StreamObserver<MxCommandReply> responseObserver) {
            responseObserver.onNext(MxCommandReply.newBuilder()
                    .setSessionId(request.getSessionId())
                    .setKind(MxCommandKind.MX_COMMAND_KIND_UNSPECIFIED)
                    .setProtocolStatus(ok())
                    .build());
            responseObserver.onCompleted();
        }
    }
    private record Harness(Server server, ManagedChannel channel, MxGatewayClient client) implements AutoCloseable {
        static Harness start(MxAccessGatewayGrpc.MxAccessGatewayImplBase service) throws Exception {
            String name = "mxgw-medium-" + UUID.randomUUID();
            Server server = InProcessServerBuilder.forName(name)
                    .directExecutor()
                    .addService(service)
                    .build()
                    .start();
            ManagedChannel channel = InProcessChannelBuilder.forName(name).directExecutor().build();
            MxGatewayClient client = new MxGatewayClient(
                    channel,
                    MxGatewayClientOptions.builder()
                            .endpoint("in-process")
                            .apiKey("")
                            .plaintext(true)
                            .callTimeout(Duration.ofSeconds(5))
                            .build());
            return new Harness(server, channel, client);
        }
        @Override
        public void close() {
            channel.shutdownNow();
            server.shutdownNow();
        }
    }
 }
@@ -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 {
@@ -16,7 +20,7 @@ dependencyResolutionManagement {
    }
 }
-rootProject.name = 'mxaccessgw-java'
+rootProject.name = 'zb-mom-ww-mxaccessgw-java'
-include 'mxgateway-client'
+include 'zb-mom-ww-mxgateway-client'
-include 'mxgateway-cli'
+include 'zb-mom-ww-mxgateway-cli'
--- a/Show More
+++ b/Show More
		`@@ -1,3 +0,0 @@`
			`using System.Runtime.CompilerServices;`

			`[assembly: InternalsVisibleTo("MxGateway.Client.Tests")]`
`@@ -1,3 +1,3 @@`
	`using MxGateway.Client.Cli;`	`using ZB.MOM.WW.MxGateway.Client.Cli;`

	`return await MxGatewayClientCli.RunAsync(args, Console.Out, Console.Error);`	`return await MxGatewayClientCli.RunAsync(args, Console.Out, Console.Error);`
		`@@ -0,0 +1,3 @@`
							`using System.Runtime.CompilerServices;`

							`[assembly: InternalsVisibleTo("ZB.MOM.WW.MxGateway.Client.Tests")]`