Add code-reviews/prompt.md orchestration prompt

Reusable prompt for working the code-reviews/ backlog: batches one
subagent per module, TDD per finding, per-module commits, regenerates
the index. Adapted to mxaccessgw toolchains and module layout.

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

REVIEW-PROCESS.md

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

clients/dotnet/MxGateway.Client/DiscoverHierarchyOptions.cs

@@ -0,0 +1,24 @@
+namespace MxGateway.Client;
+
+public sealed record DiscoverHierarchyOptions
+{
+    public int? RootGobjectId { get; init; }
+
+    public string? RootTagName { get; init; }
+
+    public string? RootContainedPath { get; init; }
+
+    public int? MaxDepth { get; init; }
+
+    public IReadOnlyList<int> CategoryIds { get; init; } = Array.Empty<int>();
+
+    public IReadOnlyList<string> TemplateChainContains { get; init; } = Array.Empty<string>();
+
+    public string? TagNameGlob { get; init; }
+
+    public bool? IncludeAttributes { get; init; }
+
+    public bool AlarmBearingOnly { get; init; }
+
+    public bool HistorizedOnly { get; init; }
+}

clients/rust/RustClientDesign.md

@@ -11,28 +11,34 @@ generated contract inputs.
 
 ## Crate Layout
 
-Recommended layout:
+Actual layout — the `mxgateway-client` library crate is the workspace root,
+with the `mxgw` test CLI as a workspace member:
 
 ```text
-clients/rust/
+clients/rust/                 # `mxgateway-client` library crate (workspace root)
   Cargo.toml
   build.rs
+  src/
+    lib.rs
+    client.rs
+    session.rs
+    galaxy.rs
+    options.rs
+    auth.rs
+    value.rs
+    version.rs
+    error.rs
+    generated.rs
   crates/
-    mxgateway-client/
-      src/lib.rs
-      src/client.rs
-      src/session.rs
-      src/options.rs
-      src/auth.rs
-      src/value.rs
-      src/error.rs
-      src/generated/
-    mxgw-cli/
+    mxgw-cli/                 # `mxgw` test CLI (workspace member)
+      Cargo.toml
       src/main.rs
   tests/
+    client_behavior.rs
+    proto_fixtures.rs
 ```
 
-Expected dependencies:
+Dependencies:
 
 - `tonic`
 - `prost`
@@ -43,7 +49,6 @@ Expected dependencies:
 - `clap`
 - `serde`
 - `serde_json`
-- `tracing`
 
 ## Library API
 

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

@@ -1048,8 +1048,14 @@ mod tests {
     fn version_json_output_has_protocol_versions() {
         let value = super::version_json();
 
-        assert_eq!(value["gatewayProtocolVersion"], 2);
-        assert_eq!(value["workerProtocolVersion"], 1);
+        assert_eq!(
+            value["gatewayProtocolVersion"],
+            super::GATEWAY_PROTOCOL_VERSION
+        );
+        assert_eq!(
+            value["workerProtocolVersion"],
+            super::WORKER_PROTOCOL_VERSION
+        );
     }
 
     #[test]

clients/rust/src/client.rs

@@ -219,7 +219,9 @@ impl GatewayClient {
         request: AcknowledgeAlarmRequest,
     ) -> Result<AcknowledgeAlarmReply, Error> {
         let mut client = self.inner.clone();
-        let response = client.acknowledge_alarm(self.unary_request(request)).await?;
+        let response = client
+            .acknowledge_alarm(self.unary_request(request))
+            .await?;
         let reply = response.into_inner();
         ensure_protocol_success("acknowledge alarm", reply.protocol_status.as_ref())?;
         Ok(reply)

clients/rust/src/error.rs

@@ -1,10 +1,10 @@
 //! Error types surfaced by the Rust client.
 //!
 //! [`Error`] is the umbrella enum returned by every async wrapper. It
-//! classifies `tonic::Status` codes (auth, timeout, cancellation) and folds
-//! gateway protocol failures and command-level rejections into structured
-//! variants. Credentials embedded in status messages are scrubbed before the
-//! message reaches a caller.
+//! classifies `tonic::Status` codes (auth, timeout, cancellation, transient
+//! unavailability) and folds gateway protocol failures and command-level
+//! rejections into structured variants. Credentials embedded in status
+//! messages are scrubbed before the message reaches a caller.
 
 use thiserror::Error as ThisError;
 use tonic::Code;
@@ -85,6 +85,17 @@ pub enum Error {
         status: Box<tonic::Status>,
     },
 
+    /// Server returned `Unavailable` or `ResourceExhausted` — a transient
+    /// failure (gateway restart, overload) that a caller may reasonably retry.
+    #[error("gateway temporarily unavailable: {message}")]
+    Unavailable {
+        /// Redacted server-supplied detail message.
+        message: String,
+        /// Original `tonic::Status`.
+        #[source]
+        status: Box<tonic::Status>,
+    },
+
     /// Any other `tonic::Status` that did not match a more specific variant.
     #[error("gateway status error: {0}")]
     Status(Box<tonic::Status>),
@@ -106,6 +117,15 @@ pub enum Error {
         /// Detail message from the server.
         message: String,
     },
+
+    /// The gateway returned an OK reply whose payload did not carry the data
+    /// the command contract requires (for example, an `AddItem` reply with no
+    /// item handle and no `return_value`).
+    #[error("malformed gateway reply: {detail}")]
+    MalformedReply {
+        /// Human-readable description of what the reply was missing.
+        detail: String,
+    },
 }
 
 /// Wrapper around an [`MxCommandReply`] whose `protocol_status` reported a
@@ -174,6 +194,10 @@ impl From<tonic::Status> for Error {
                 message,
                 status: Box::new(status),
             },
+            Code::Unavailable | Code::ResourceExhausted => Self::Unavailable {
+                message,
+                status: Box::new(status),
+            },
             _ => Self::Status(Box::new(status)),
         }
     }

clients/rust/src/galaxy.rs

@@ -279,7 +279,7 @@ mod tests {
             _request: Request<GetLastDeployTimeRequest>,
         ) -> Result<Response<GetLastDeployTimeReply>, Status> {
             let present = *self.state.present.lock().unwrap();
-            let time = self.state.last_deploy.lock().unwrap().clone();
+            let time = *self.state.last_deploy.lock().unwrap();
             Ok(Response::new(GetLastDeployTimeReply {
                 present,
                 time_of_last_deploy: time,

clients/rust/src/options.rs

@@ -95,6 +95,8 @@ impl ClientOptions {
         self
     }
 
+    /// Maximum encoded/decoded gRPC message size, in bytes, the transport
+    /// will accept. Defaults to 16 MiB.
     pub fn with_max_grpc_message_bytes(mut self, max_grpc_message_bytes: usize) -> Self {
         self.max_grpc_message_bytes = max_grpc_message_bytes;
         self
@@ -140,6 +142,7 @@ impl ClientOptions {
         self.stream_timeout
     }
 
+    /// Configured maximum gRPC message size in bytes.
     pub fn max_grpc_message_bytes(&self) -> usize {
         self.max_grpc_message_bytes
     }

clients/rust/src/session.rs

@@ -8,6 +8,8 @@
 //! Bulk commands enforce a 1000-item cap before contacting the worker, in
 //! line with the gateway's documented `MAX_BULK_ITEMS`.
 
+use std::sync::atomic::{AtomicU64, Ordering};
+
 use crate::client::{EventStream, GatewayClient};
 use crate::error::{ensure_protocol_success, Error};
 use crate::generated::mxaccess_gateway::v1::mx_command::Payload;
@@ -23,6 +25,16 @@ use crate::value::MxValue;
 
 const MAX_BULK_ITEMS: usize = 1_000;
 
+/// Process-wide monotonic counter that keeps client correlation ids unique.
+static CORRELATION_SEQUENCE: AtomicU64 = AtomicU64::new(0);
+
+/// Build a unique `client_correlation_id` for a request so concurrent or
+/// repeated calls of the same command kind can be told apart in gateway logs.
+fn next_correlation_id(label: &str) -> String {
+    let sequence = CORRELATION_SEQUENCE.fetch_add(1, Ordering::Relaxed);
+    format!("rust-client-{label}-{sequence}")
+}
+
 /// Handle to an opened gateway session.
 ///
 /// `Session` carries the gateway-issued session id and a cloned
@@ -76,7 +88,7 @@ impl Session {
             .client
             .close_session_raw(CloseSessionRequest {
                 session_id: self.id.clone(),
-                client_correlation_id: "rust-client-close-session".to_owned(),
+                client_correlation_id: next_correlation_id("close-session"),
             })
             .await?;
         ensure_protocol_success("close session", reply.protocol_status.as_ref())?;
@@ -99,7 +111,7 @@ impl Session {
             )
             .await?;
 
-        Ok(register_server_handle(&reply))
+        register_server_handle(&reply)
     }
 
     /// Run MXAccess `AddItem` against `server_handle` and return the
@@ -120,7 +132,7 @@ impl Session {
             )
             .await?;
 
-        Ok(add_item_handle(&reply))
+        add_item_handle(&reply)
     }
 
     /// Run MXAccess `AddItem2` (item with a caller-supplied context string)
@@ -146,7 +158,7 @@ impl Session {
             )
             .await?;
 
-        Ok(add_item2_handle(&reply))
+        add_item2_handle(&reply)
     }
 
     /// Run MXAccess `RemoveItem` for the given handle pair.
@@ -226,7 +238,7 @@ impl Session {
             )
             .await?;
 
-        Ok(bulk_results(reply, BulkReplyKind::AddItemBulk))
+        bulk_results(reply, BulkReplyKind::AddItem)
     }
 
     /// Bulk variant of [`Session::advise`].
@@ -250,7 +262,7 @@ impl Session {
             )
             .await?;
 
-        Ok(bulk_results(reply, BulkReplyKind::AdviseItemBulk))
+        bulk_results(reply, BulkReplyKind::AdviseItem)
     }
 
     /// Bulk variant of [`Session::remove_item`].
@@ -274,7 +286,7 @@ impl Session {
             )
             .await?;
 
-        Ok(bulk_results(reply, BulkReplyKind::RemoveItemBulk))
+        bulk_results(reply, BulkReplyKind::RemoveItem)
     }
 
     /// Bulk variant of [`Session::un_advise`].
@@ -298,7 +310,7 @@ impl Session {
             )
             .await?;
 
-        Ok(bulk_results(reply, BulkReplyKind::UnAdviseItemBulk))
+        bulk_results(reply, BulkReplyKind::UnAdviseItem)
     }
 
     /// Bulk `Subscribe` (atomic add-and-advise) for a list of tag addresses.
@@ -322,7 +334,7 @@ impl Session {
             )
             .await?;
 
-        Ok(bulk_results(reply, BulkReplyKind::SubscribeBulk))
+        bulk_results(reply, BulkReplyKind::Subscribe)
     }
 
     /// Bulk `Unsubscribe` (atomic un-advise-and-remove) for a list of
@@ -347,7 +359,7 @@ impl Session {
             )
             .await?;
 
-        Ok(bulk_results(reply, BulkReplyKind::UnsubscribeBulk))
+        bulk_results(reply, BulkReplyKind::Unsubscribe)
     }
 
     /// Run MXAccess `Write` (single-value, no caller-supplied timestamp).
@@ -466,7 +478,7 @@ impl Session {
     fn command_request(&self, kind: MxCommandKind, payload: Payload) -> MxCommandRequest {
         MxCommandRequest {
             session_id: self.id.clone(),
-            client_correlation_id: format!("rust-client-{}", kind.as_str_name()),
+            client_correlation_id: next_correlation_id(kind.as_str_name()),
             command: Some(MxCommand {
                 kind: kind as i32,
                 payload: Some(payload),
@@ -486,71 +498,83 @@ fn ensure_bulk_size(name: &'static str, len: usize) -> Result<(), Error> {
     }
 }
 
-fn register_server_handle(reply: &MxCommandReply) -> i32 {
+fn register_server_handle(reply: &MxCommandReply) -> Result<i32, Error> {
     match reply.payload.as_ref() {
-        Some(mx_command_reply::Payload::Register(register)) => register.server_handle,
+        Some(mx_command_reply::Payload::Register(register)) => Ok(register.server_handle),
         _ => reply
             .return_value
             .as_ref()
             .and_then(int32_reply_value)
-            .unwrap_or_default(),
+            .ok_or_else(|| Error::MalformedReply {
+                detail: "Register reply carried neither a register payload nor an \
+                         int32 return value"
+                    .to_owned(),
+            }),
     }
 }
 
-fn add_item_handle(reply: &MxCommandReply) -> i32 {
+fn add_item_handle(reply: &MxCommandReply) -> Result<i32, Error> {
     match reply.payload.as_ref() {
-        Some(mx_command_reply::Payload::AddItem(add_item)) => add_item.item_handle,
+        Some(mx_command_reply::Payload::AddItem(add_item)) => Ok(add_item.item_handle),
         _ => reply
             .return_value
             .as_ref()
             .and_then(int32_reply_value)
-            .unwrap_or_default(),
+            .ok_or_else(|| Error::MalformedReply {
+                detail: "AddItem reply carried neither an add_item payload nor an \
+                         int32 return value"
+                    .to_owned(),
+            }),
     }
 }
 
-fn add_item2_handle(reply: &MxCommandReply) -> i32 {
+fn add_item2_handle(reply: &MxCommandReply) -> Result<i32, Error> {
     match reply.payload.as_ref() {
-        Some(mx_command_reply::Payload::AddItem2(add_item)) => add_item.item_handle,
+        Some(mx_command_reply::Payload::AddItem2(add_item)) => Ok(add_item.item_handle),
         _ => reply
             .return_value
             .as_ref()
             .and_then(int32_reply_value)
-            .unwrap_or_default(),
+            .ok_or_else(|| Error::MalformedReply {
+                detail: "AddItem2 reply carried neither an add_item2 payload nor an \
+                         int32 return value"
+                    .to_owned(),
+            }),
     }
 }
 
 enum BulkReplyKind {
-    AddItemBulk,
-    AdviseItemBulk,
-    RemoveItemBulk,
-    UnAdviseItemBulk,
-    SubscribeBulk,
-    UnsubscribeBulk,
+    AddItem,
+    AdviseItem,
+    RemoveItem,
+    UnAdviseItem,
+    Subscribe,
+    Unsubscribe,
 }
 
-fn bulk_results(reply: MxCommandReply, kind: BulkReplyKind) -> Vec<SubscribeResult> {
+fn bulk_results(reply: MxCommandReply, kind: BulkReplyKind) -> Result<Vec<SubscribeResult>, Error> {
     match (reply.payload, kind) {
-        (Some(mx_command_reply::Payload::AddItemBulk(reply)), BulkReplyKind::AddItemBulk) => {
-            reply.results
+        (Some(mx_command_reply::Payload::AddItemBulk(reply)), BulkReplyKind::AddItem) => {
+            Ok(reply.results)
         }
-        (Some(mx_command_reply::Payload::AdviseItemBulk(reply)), BulkReplyKind::AdviseItemBulk) => {
-            reply.results
+        (Some(mx_command_reply::Payload::AdviseItemBulk(reply)), BulkReplyKind::AdviseItem) => {
+            Ok(reply.results)
         }
-        (Some(mx_command_reply::Payload::RemoveItemBulk(reply)), BulkReplyKind::RemoveItemBulk) => {
-            reply.results
+        (Some(mx_command_reply::Payload::RemoveItemBulk(reply)), BulkReplyKind::RemoveItem) => {
+            Ok(reply.results)
         }
-        (
-            Some(mx_command_reply::Payload::UnAdviseItemBulk(reply)),
-            BulkReplyKind::UnAdviseItemBulk,
-        ) => reply.results,
-        (Some(mx_command_reply::Payload::SubscribeBulk(reply)), BulkReplyKind::SubscribeBulk) => {
-            reply.results
+        (Some(mx_command_reply::Payload::UnAdviseItemBulk(reply)), BulkReplyKind::UnAdviseItem) => {
+            Ok(reply.results)
         }
-        (
-            Some(mx_command_reply::Payload::UnsubscribeBulk(reply)),
-            BulkReplyKind::UnsubscribeBulk,
-        ) => reply.results,
-        _ => Vec::new(),
+        (Some(mx_command_reply::Payload::SubscribeBulk(reply)), BulkReplyKind::Subscribe) => {
+            Ok(reply.results)
+        }
+        (Some(mx_command_reply::Payload::UnsubscribeBulk(reply)), BulkReplyKind::Unsubscribe) => {
+            Ok(reply.results)
+        }
+        _ => Err(Error::MalformedReply {
+            detail: "bulk command reply did not carry the expected bulk result payload".to_owned(),
+        }),
     }
 }
 

clients/rust/src/value.rs

@@ -25,15 +25,13 @@ use crate::generated::mxaccess_gateway::v1::{
 #[derive(Clone, Debug, PartialEq)]
 pub struct MxValue {
     raw: ProtoMxValue,
-    projection: MxValueProjection,
 }
 
 impl MxValue {
-    /// Wrap a protobuf [`ProtoMxValue`] and compute its
-    /// [`MxValueProjection`].
+    /// Wrap a protobuf [`ProtoMxValue`]. The typed [`MxValueProjection`] is
+    /// computed on demand by [`MxValue::projection`].
     pub fn from_proto(raw: ProtoMxValue) -> Self {
-        let projection = MxValueProjection::from_proto(&raw);
-        Self { raw, projection }
+        Self { raw }
     }
 
     /// Build a boolean `MxValue` (`MxDataType::Boolean`, `VT_BOOL`).
@@ -102,9 +100,13 @@ impl MxValue {
         &self.raw
     }
 
-    /// Borrow the typed projection.
-    pub fn projection(&self) -> &MxValueProjection {
-        &self.projection
+    /// Compute the typed projection of this value.
+    ///
+    /// The projection is derived from the raw message on each call rather than
+    /// cached, so a value built only to be sent over the wire never pays the
+    /// projection's allocation cost.
+    pub fn projection(&self) -> MxValueProjection {
+        MxValueProjection::from_proto(&self.raw)
     }
 
     /// Consume the wrapper and return the underlying protobuf message.
@@ -183,15 +185,13 @@ impl MxValueProjection {
 #[derive(Clone, Debug, PartialEq)]
 pub struct MxArrayValue {
     raw: MxArray,
-    projection: MxArrayProjection,
 }
 
 impl MxArrayValue {
-    /// Wrap a protobuf [`MxArray`] and compute its
-    /// [`MxArrayProjection`].
+    /// Wrap a protobuf [`MxArray`]. The typed [`MxArrayProjection`] is
+    /// computed on demand by [`MxArrayValue::projection`].
     pub fn from_proto(raw: MxArray) -> Self {
-        let projection = MxArrayProjection::from_proto(&raw);
-        Self { raw, projection }
+        Self { raw }
     }
 
     /// Build a one-dimensional string array (`VT_ARRAY|VT_BSTR`).
@@ -210,9 +210,10 @@ impl MxArrayValue {
         &self.raw
     }
 
-    /// Borrow the typed projection of the array's elements.
-    pub fn projection(&self) -> &MxArrayProjection {
-        &self.projection
+    /// Compute the typed projection of the array's elements, derived from the
+    /// raw message on each call rather than cached.
+    pub fn projection(&self) -> MxArrayProjection {
+        MxArrayProjection::from_proto(&self.raw)
     }
 }
 

clients/rust/src/version.rs

@@ -3,8 +3,9 @@
 //! The protocol versions track the values the gateway and worker negotiate on
 //! `OpenSession` and let test harnesses cross-check the wire contract.
 
-/// Semantic version of this Rust client crate. Mirrors `Cargo.toml`.
-pub const CLIENT_VERSION: &str = "0.1.0-dev";
+/// Semantic version of this Rust client crate, taken from `Cargo.toml` at
+/// compile time so the two cannot drift.
+pub const CLIENT_VERSION: &str = env!("CARGO_PKG_VERSION");
 
 /// Public gateway gRPC protocol version this client targets.
 pub const GATEWAY_PROTOCOL_VERSION: u32 = 3;

clients/rust/tests/client_behavior.rs

@@ -203,7 +203,7 @@ fn value_conversion_fixtures_keep_typed_projection_and_raw_metadata() {
     });
     assert_eq!(
         int64_value.projection(),
-        &MxValueProjection::Int64(9_223_372_036_854_770_000)
+        MxValueProjection::Int64(9_223_372_036_854_770_000)
     );
 
     let raw_case = case_by_id(cases, "raw-fallback.variant");
@@ -220,7 +220,7 @@ fn value_conversion_fixtures_keep_typed_projection_and_raw_metadata() {
     });
     assert_eq!(
         raw_value.projection(),
-        &MxValueProjection::Raw(vec![1, 2, 3, 4, 5])
+        MxValueProjection::Raw(vec![1, 2, 3, 4, 5])
     );
     assert_eq!(raw_value.raw().raw_data_type, 32767);
     assert!(raw_value.raw().raw_diagnostic.contains("No lossless"));
@@ -272,11 +272,76 @@ fn command_error_display_keeps_raw_reply_accessible() {
     assert!(error.to_string().contains("MxaccessFailure"));
 }
 
+#[tokio::test]
+async fn add_item_bulk_rejects_input_above_the_thousand_item_cap() {
+    let state = Arc::new(FakeState::default());
+    let endpoint = spawn_fake_gateway(state.clone()).await;
+    let client = GatewayClient::connect(ClientOptions::new(endpoint))
+        .await
+        .unwrap();
+    let session = client.session("session-fixture");
+
+    let oversized: Vec<String> = (0..1001).map(|index| format!("Tag{index}")).collect();
+    let error = session.add_item_bulk(12, oversized).await.unwrap_err();
+
+    assert!(
+        matches!(&error, Error::InvalidArgument { name, .. } if name.as_str() == "tag_addresses"),
+        "expected InvalidArgument for tag_addresses, got {error:?}"
+    );
+}
+
+#[tokio::test]
+async fn event_stream_surfaces_a_mid_stream_status_fault() {
+    let state = Arc::new(FakeState::default());
+    state.emit_stream_fault.store(true, Ordering::SeqCst);
+    let endpoint = spawn_fake_gateway(state.clone()).await;
+    let client = GatewayClient::connect(ClientOptions::new(endpoint))
+        .await
+        .unwrap();
+
+    let mut stream = client
+        .stream_events(StreamEventsRequest {
+            session_id: "session-fixture".to_owned(),
+            after_worker_sequence: 0,
+        })
+        .await
+        .unwrap();
+
+    assert_eq!(stream.next().await.unwrap().unwrap().worker_sequence, 1);
+    assert_eq!(stream.next().await.unwrap().unwrap().worker_sequence, 2);
+
+    let fault = stream.next().await.unwrap().unwrap_err();
+
+    assert!(
+        matches!(fault, Error::Unavailable { .. }),
+        "expected Error::Unavailable, got {fault:?}"
+    );
+}
+
+#[tokio::test]
+async fn connect_with_unreadable_ca_file_reports_invalid_endpoint() {
+    let options = ClientOptions::new("https://127.0.0.1:65000")
+        .with_plaintext(false)
+        .with_ca_file("definitely-not-a-real-ca-file.pem");
+
+    // GatewayClient is not Debug, so unwrap_err is unavailable here.
+    let error = match GatewayClient::connect(options).await {
+        Ok(_) => panic!("connect should fail when the CA file cannot be read"),
+        Err(error) => error,
+    };
+
+    assert!(
+        matches!(error, Error::InvalidEndpoint { .. }),
+        "expected Error::InvalidEndpoint, got {error:?}"
+    );
+}
+
 #[derive(Default)]
 struct FakeState {
     authorization: Mutex<Option<String>>,
     last_command_kind: Mutex<Option<i32>>,
     stream_dropped: Arc<AtomicBool>,
+    emit_stream_fault: AtomicBool,
 }
 
 #[derive(Clone)]
@@ -376,6 +441,12 @@ impl MxAccessGateway for FakeGateway {
         let (sender, receiver) = mpsc::channel(4);
         sender.send(Ok(event(1))).await.unwrap();
         sender.send(Ok(event(2))).await.unwrap();
+        if self.state.emit_stream_fault.load(Ordering::SeqCst) {
+            sender
+                .send(Err(Status::unavailable("worker dropped the session")))
+                .await
+                .unwrap();
+        }
 
         Ok(Response::new(DropAwareStream {
             inner: ReceiverStream::new(receiver),

code-reviews/Client.Dotnet/findings.md

@@ -0,0 +1,147 @@
+# Code Review — Client.Dotnet
+
+| Field | Value |
+|---|---|
+| Module | `clients/dotnet` |
+| Reviewer | Claude Code |
+| Review date | 2026-05-18 |
+| Commit reviewed | `3cc53a8` |
+| Status | Reviewed |
+| Open findings | 8 |
+
+## Checklist coverage
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Minor: handle-selector fallback `?? reply.ReturnValue.Int32Value` can mask a missing typed reply (Client.Dotnet-005); CLI redactor misses env-var keys (Client.Dotnet-008). |
+| 2 | mxaccessgw conventions | Good — consumes the shared contracts project, no forked proto, `authorization: Bearer` metadata correct, parity preserved via split `EnsureProtocolSuccess`/`EnsureMxAccessSuccess`. |
+| 3 | Concurrency & thread safety | Issue found: `_disposed` flags unsynchronized; `MxGatewaySession.DisposeAsync` can race a concurrent `CloseAsync` (Client.Dotnet-003). |
+| 4 | Error handling & resilience | Issues found: gRPC-to-native mapping collapses non-auth statuses into one untyped exception (Client.Dotnet-001); shared retry/timeout budget (Client.Dotnet-004). |
+| 5 | Security | Good — API key never logged by the library, CLI redacts keys, TLS custom-root validation correct. |
+| 6 | Performance & resource management | No issues found — channels and streaming calls disposed correctly. |
+| 7 | Design-document adherence | No issues found — matches `ClientLibrariesDesign.md`. |
+| 8 | Code organization & conventions | Issue found: undocumented public members (Client.Dotnet-006). |
+| 9 | Testing coverage | Issue found: the production retry path is never exercised (Client.Dotnet-002). |
+| 10 | Documentation & comments | Issue found: doc misstates the unary timeout retry budget as per-call (Client.Dotnet-004, Client.Dotnet-007). |
+
+## Findings
+
+### Client.Dotnet-001
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `clients/dotnet/MxGateway.Client/GrpcMxGatewayClientTransport.cs:190-199`, `clients/dotnet/MxGateway.Client/GrpcGalaxyRepositoryClientTransport.cs:131-140` |
+| Status | Open |
+
+**Description:** `MapRpcException` only produces typed exceptions for `Unauthenticated` and `PermissionDenied`. Every other gRPC status — `NotFound`, `InvalidArgument`, `ResourceExhausted`, `FailedPrecondition`, `Unavailable`, `Internal` — collapses into the base `MxGatewayException` with no surfaced `StatusCode`. Callers cannot programmatically distinguish a transient outage from a permanent bad-argument error without reflecting into `InnerException` and downcasting to `RpcException`.
+
+**Recommendation:** Carry the gRPC `StatusCode` on `MxGatewayException` (e.g. a `StatusCode` property) and/or add typed subclasses for at least `NotFound`, `InvalidArgument`, and `Unavailable`. Populate it from `exception.StatusCode` in `MapRpcException`.
+
+**Resolution:** _(open)_
+
+### Client.Dotnet-002
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Testing coverage |
+| Location | `clients/dotnet/MxGateway.Client.Tests/FakeGatewayTransport.cs:145-148`, `clients/dotnet/MxGateway.Client.Tests/MxGatewayClientSessionTests.cs:236-256` |
+| Status | Open |
+
+**Description:** The retry predicate `MxGatewayClientRetryPolicy.IsTransientGrpcFailure` handles two shapes: a raw `RpcException` and an `MxGatewayException { InnerException: RpcException }`. In production the transport always maps `RpcException` → `MxGatewayException` before it reaches the retry pipeline, so only the wrapped-`MxGatewayException` branch ever runs in production. But `FakeGatewayTransport` throws the raw `RpcException` and never maps it, so every retry test exercises only the raw-`RpcException` branch — the branch that never occurs in production. The production retry behaviour is effectively untested.
+
+**Recommendation:** Add a fake/transport mode that maps `RpcException` to `MxGatewayException` the way `GrpcMxGatewayClientTransport` does (or add tests that enqueue a pre-wrapped `MxGatewayException`), so the actually-used predicate branch is covered.
+
+**Resolution:** _(open)_
+
+### Client.Dotnet-003
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Concurrency & thread safety |
+| Location | `clients/dotnet/MxGateway.Client/MxGatewaySession.cs:659-663`, `clients/dotnet/MxGateway.Client/MxGatewayClient.cs:230-240` |
+| Status | Open |
+
+**Description:** `DisposeAsync` calls `CloseAsync()` (no token) then unconditionally `_closeLock.Dispose()`. If another thread is concurrently awaiting `CloseAsync(token)` — legal, since the type exposes public async methods and no single-threaded contract — disposing the `SemaphoreSlim` while a `WaitAsync` is pending throws `ObjectDisposedException` into that caller. The `_disposed` flags in both clients are also plain unsynchronised `bool` reads/writes; `ThrowIfDisposed` racing `DisposeAsync` can observe a stale value.
+
+**Recommendation:** Either document `MxGatewaySession`/`MxGatewayClient` as not thread-safe for concurrent dispose, or guard `_disposed` with `Interlocked`/`volatile` and avoid disposing `_closeLock` until all in-flight `CloseAsync` calls complete.
+
+**Resolution:** _(open)_
+
+### Client.Dotnet-004
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Error handling & resilience |
+| Location | `clients/dotnet/MxGateway.Client/MxGatewayClient.cs:283-294`, `clients/dotnet/MxGateway.Client/GalaxyRepositoryClient.cs:392-403` |
+| Status | Open |
+
+**Description:** `ExecuteSafeUnaryAsync` wraps the whole Polly retry pipeline in a single linked CTS cancelled after `Options.DefaultCallTimeout`, while `CreateCallOptions` also stamps each individual call with a `DefaultCallTimeout` gRPC deadline. The retry pipeline therefore shares one `DefaultCallTimeout` budget across the initial attempt plus all retries plus backoff delays. The README/XML docs describe `DefaultCallTimeout` as a per-call timeout, which misrepresents this. `DeadlineExceeded` is also classified as transient, so an attempt that exhausts the shared budget is retried only to immediately fail again.
+
+**Recommendation:** Decide whether `DefaultCallTimeout` is per-attempt or per-operation and make code and docs consistent — e.g. a separate per-attempt deadline and a distinct overall-operation timeout. Reconsider retrying on `DeadlineExceeded` when the deadline was client-imposed.
+
+**Resolution:** _(open)_
+
+### Client.Dotnet-005
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `clients/dotnet/MxGateway.Client/MxGatewaySession.cs:82,124,175` |
+| Status | Open |
+
+**Description:** `RegisterAsync`/`AddItemAsync`/`AddItem2Async` return `reply.<Typed>?.ServerHandle ?? reply.ReturnValue.Int32Value`. After `EnsureMxAccessSuccess()` passes, a missing typed payload silently falls back to `ReturnValue.Int32Value`, which for a reply carrying no return value is `0`. A caller then uses `0` as a `ServerHandle`/`ItemHandle`, producing a confusing downstream invalid-handle failure rather than a clear "gateway reply missing payload" error.
+
+**Recommendation:** If the typed sub-message is the contract for these commands, treat its absence on an otherwise-successful reply as an error (throw a descriptive `MxGatewayException`) rather than falling through to `ReturnValue.Int32Value`.
+
+**Resolution:** _(open)_
+
+### Client.Dotnet-006
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `clients/dotnet/MxGateway.Client/MxGatewayClientOptions.cs:50`, `clients/dotnet/MxGateway.Client/MxGatewayClientContractInfo.cs:10-14` |
+| Status | Open |
+
+**Description:** `MxGatewayClientOptions.MaxGrpcMessageBytes` and the two `const`s in `MxGatewayClientContractInfo` are public members with no XML doc comments, inconsistent with every other public member in the assembly and with the repo's documented C# style emphasis on a documented public surface.
+
+**Recommendation:** Add `<summary>` doc comments to `MaxGrpcMessageBytes`, `GatewayProtocolVersion`, and `WorkerProtocolVersion`.
+
+**Resolution:** _(open)_
+
+### Client.Dotnet-007
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `clients/dotnet/MxGateway.Client/MxGatewayClient.cs:185-192` |
+| Status | Open |
+
+**Description:** The `AcknowledgeAlarmAsync` XML comment states the gateway authenticates against an `invoke:alarm-ack` scope, but `CLAUDE.md` documents the scope set without any `invoke:alarm-ack` sub-scope. The comment may describe an intended finer-grained scope that does not exist, misleading integrators about what API key they need.
+
+**Recommendation:** Reconcile the comment with the actual server-side scope check, or update the scope documentation if sub-scopes were genuinely added; keep client doc and gateway auth model in sync.
+
+**Resolution:** _(open)_
+
+### Client.Dotnet-008
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `clients/dotnet/MxGateway.Client.Cli/MxGatewayCliSecretRedactor.cs:9-17` |
+| Status | Open |
+
+**Description:** The CLI redactor only removes the API key string when it was supplied via `--api-key`; `RunCoreAsync` passes `arguments.GetOptional("api-key")` to `Redact`. When the key comes from an environment variable (`--api-key-env`, the documented default path), `apiKey` is `null` and no redaction occurs. If a gRPC/transport error message ever echoes the bearer token, it would be printed unredacted.
+
+**Recommendation:** Resolve the effective API key (same logic as `ResolveApiKey`) before redacting, so the env-var-sourced key is also stripped from error output.
+
+**Resolution:** _(open)_

code-reviews/Client.Go/findings.md

@@ -0,0 +1,177 @@
+# Code Review — Client.Go
+
+| Field | Value |
+|---|---|
+| Module | `clients/go` |
+| Reviewer | Claude Code |
+| Review date | 2026-05-18 |
+| Commit reviewed | `3cc53a8` |
+| Status | Reviewed |
+| Open findings | 10 |
+
+## Checklist coverage
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issues found: a typed-nil `Unwrap`/`errors.As` trap (Client.Go-001), a CLI `panic` on malformed input (Client.Go-003), empty-string correlation id on rand failure (Client.Go-007). |
+| 2 | mxaccessgw conventions | Generally good; two test files fail `gofmt`, breaking the documented workflow (Client.Go-004). |
+| 3 | Concurrency & thread safety | No issues found — stream goroutines and cancellation are sound. |
+| 4 | Error handling & resilience | Issues found: the compatibility event path silently drops events (Client.Go-002); no transient/permanent classification (Client.Go-006). |
+| 5 | Security | No issues found — TLS by default with a TLS 1.2 floor, API key redaction, no secret logging. |
+| 6 | Performance & resource management | No issues found — connections/streams closed via deferred `Close`/`cancel`. |
+| 7 | Design-document adherence | Issues found: deprecated `grpc.DialContext`+`WithBlock` usage and a missing error taxonomy (Client.Go-005, Client.Go-006). |
+| 8 | Code organization & conventions | Issue found: duplication between `Client` and `GalaxyClient` (Client.Go-009). |
+| 9 | Testing coverage | Issue found: TLS path, `callContext` deadline logic, and `NativeValue`/`NativeArray` edges untested (Client.Go-008). |
+| 10 | Documentation & comments | Issue found: a stale `WithBlock` dial-cancellation claim (Client.Go-010). |
+
+## Findings
+
+### Client.Go-001
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Correctness & logic bugs |
+| Location | `clients/go/mxgateway/errors.go:88-93`, `clients/go/mxgateway/errors.go:117-128` |
+| Status | Open |
+
+**Description:** `MxAccessError.Unwrap` returns `e.Command` directly. `EnsureMxAccessSuccess` constructs `&MxAccessError{Reply: reply}` with `Command` left nil (the HRESULT / failing-`MxStatusProxy` path). When `Command` is a nil `*CommandError`, `Unwrap()` returns a non-nil `error` interface wrapping a nil pointer. Consequently `errors.As(err, &ce)` for `*CommandError` returns `true` while setting `ce` to nil — a caller writing the idiomatic `if errors.As(err, &commandErr) { use commandErr.Status }` nil-dereferences and panics. Verified empirically; the existing test only exercises the populated-`Command` path.
+
+**Recommendation:** Make `Unwrap` return an untyped nil when `Command` is nil: `if e == nil || e.Command == nil { return nil }; return e.Command`. Add a test for the HRESULT-only `MxAccessError` asserting `errors.As(err, &ce)` is `false`.
+
+**Resolution:** _(open)_
+
+### Client.Go-002
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `clients/go/mxgateway/session.go:440-516` |
+| Status | Open |
+
+**Description:** For the `Events`/`EventsAfter` compatibility API (`cancelWhenResultBufferFull == true`), when the 16-slot `results` channel is full `sendEventResult` cancels and returns `false`; the goroutine returns and `close(results)` runs — the consumer sees the channel close with **no `EventResult{Err: ...}` ever delivered**. A slow consumer cannot distinguish "stream ended normally" from "events were silently dropped." This contradicts the design doc's "libraries should not reorder, coalesce, or drop events by default", and a test currently pins this lossy behaviour.
+
+**Recommendation:** Before cancelling on a full buffer, deliver a terminal `EventResult` carrying an explicit error (e.g. `ErrEventBufferOverflow`). Document the behaviour on `Session.Events`; steer callers to `SubscribeEvents` (which blocks instead of dropping).
+
+**Resolution:** _(open)_
+
+### Client.Go-003
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Correctness & logic bugs |
+| Location | `clients/go/cmd/mxgw-go/main.go:517-532` |
+| Status | Open |
+
+**Description:** `parseInt32List` calls `panic(err)` when an `item-handles` token fails to parse as an int32. The CLI is a documented user-facing tool; a typo like `-item-handles 1,foo` crashes the process with an unrecovered panic and stack trace instead of returning a clean error and exit code 2 like every other validation path in `main.go`.
+
+**Recommendation:** Change `parseInt32List` to return `([]int32, error)` and have `runUnsubscribeBulk` propagate the error, matching `parseValue`'s pattern.
+
+**Resolution:** _(open)_
+
+### Client.Go-004
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | mxaccessgw conventions |
+| Location | `clients/go/mxgateway/alarms_test.go:153-154`, `clients/go/mxgateway/galaxy_test.go:58-59` |
+| Status | Open |
+
+**Description:** `gofmt -l` flags `alarms_test.go` and `galaxy_test.go` for misaligned struct-literal field padding. The Go client README lists `gofmt` as part of the workflow and the repo enforces style; unformatted committed code breaks `gofmt`-gated checks and CI.
+
+**Recommendation:** Run `gofmt -w mxgateway/alarms_test.go mxgateway/galaxy_test.go`.
+
+**Resolution:** _(open)_
+
+### Client.Go-005
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Design-document adherence |
+| Location | `clients/go/mxgateway/client.go:64,68`, `clients/go/mxgateway/galaxy.go:83,87` |
+| Status | Open |
+
+**Description:** The client uses `grpc.DialContext` with `grpc.WithBlock()`. In current grpc-go both are deprecated in favour of `grpc.NewClient` (lazy connection). `WithBlock` also changes failure semantics: a transient gateway-unavailable at dial time becomes a hard `Dial` error rather than a connection that recovers when the gateway comes up, working against the design doc's resilience intent.
+
+**Recommendation:** Migrate to `grpc.NewClient`; if a fail-fast connect probe is still wanted, do an explicit readiness wait bounded by `DialTimeout`, and update the doc comment.
+
+**Resolution:** _(open)_
+
+### Client.Go-006
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Error handling & resilience |
+| Location | `clients/go/mxgateway/errors.go:9-130` |
+| Status | Open |
+
+**Description:** `docs/ClientLibrariesDesign.md` recommends a high-level error taxonomy (`TransportError`, `AuthenticationError`, `TimeoutError`, etc.). The Go client collapses all transport/gRPC failures into a single `GatewayError` with no way to classify transient (`Unavailable`, `DeadlineExceeded`) vs permanent (`Unauthenticated`, `InvalidArgument`) without manually unwrapping and calling `status.Code`.
+
+**Recommendation:** Add a helper (e.g. `IsTransient(err) bool`) or expose the gRPC `codes.Code` on `GatewayError`, so retry/timeout/auth handling can be written without re-parsing the wrapped error.
+
+**Resolution:** _(open)_
+
+### Client.Go-007
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `clients/go/mxgateway/session.go:526-532` |
+| Status | Open |
+
+**Description:** `newCorrelationID` returns an empty string when `crypto/rand.Read` fails, silently producing an `MxCommandRequest` with no correlation id. `rand.Read` failure is rare, but the failure mode (untraceable command, no error surfaced) is worse than failing loud, and the empty-id path is untested.
+
+**Recommendation:** Either propagate the error up through `invokeCommand`, or fall back to a time/counter-based id rather than an empty string.
+
+**Resolution:** _(open)_
+
+### Client.Go-008
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `clients/go/mxgateway/` (test files) |
+| Status | Open |
+
+**Description:** Several critical paths are untested: TLS credential resolution in `resolveTransportCredentials` (only the `Plaintext` path is exercised); the `callContext` deadline-shortening logic (`client.go:198-204`) including the negative-timeout disable case; and `NativeValue`/`NativeArray` for the array, raw-bytes, null, and unsupported-kind branches.
+
+**Recommendation:** Add unit tests for `resolveTransportCredentials` precedence, `callContext` deadline arithmetic, and `NativeValue`/`NativeArray` round-trips for every kind.
+
+**Resolution:** _(open)_
+
+### Client.Go-009
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `clients/go/mxgateway/galaxy.go:60-93,241-256`, `clients/go/mxgateway/client.go:41-74,190-205` |
+| Status | Open |
+
+**Description:** `DialGalaxy`/`Dial` and `GalaxyClient.callContext`/`Client.callContext` are near-identical duplicates (dial-context setup, credential resolution, dial-option assembly, deadline arithmetic). A fix to one (e.g. the Client.Go-005 dial migration) must be applied twice and can drift.
+
+**Recommendation:** Extract a shared unexported `dial(ctx, opts)` and a free `callContext(opts, ctx)` function, and have both client constructors call them.
+
+**Resolution:** _(open)_
+
+### Client.Go-010
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `clients/go/mxgateway/client.go:39-40` |
+| Status | Open |
+
+**Description:** The `Dial` doc comment states it configures "blocking dial cancellation from ctx." This describes the deprecated `WithBlock` behaviour; once Client.Go-005 is addressed the comment is misleading about how connection establishment and cancellation work.
+
+**Recommendation:** Reword to describe the actual connect/timeout semantics after resolving Client.Go-005, and clarify that `DialTimeout` bounds the initial connect attempt.
+
+**Resolution:** _(open)_

code-reviews/Client.Java/findings.md

@@ -0,0 +1,207 @@
+# Code Review — Client.Java
+
+| Field | Value |
+|---|---|
+| Module | `clients/java` |
+| Reviewer | Claude Code |
+| Review date | 2026-05-18 |
+| Commit reviewed | `3cc53a8` |
+| Status | Reviewed |
+| Open findings | 12 |
+
+## Checklist coverage
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issues found: `register`/`addItem` silently fall back to `getReturnValue()` masking missing payloads (Client.Java-004); fragile `resolved()` mutation pattern (Client.Java-012). |
+| 2 | mxaccessgw conventions | Largely adheres; the gateway protocol-version handshake is never verified despite the contract field existing (Client.Java-003). |
+| 3 | Concurrency & thread safety | Issue found: `MxEventStream.next` is a plain field and terminal-state transitions race (Client.Java-002). |
+| 4 | Error handling & resilience | Issues found: `close()` can mask the primary exception (Client.Java-005); async/sync error surfaces inconsistent (Client.Java-008). |
+| 5 | Security | Issue found: API-key redaction leaks the trailing 4 secret characters (Client.Java-001). |
+| 6 | Performance & resource management | Issues found: `close()` does not await termination (Client.Java-006); no stream flow control (Client.Java-011). |
+| 7 | Design-document adherence | Matches `JavaClientDesign.md` closely; the protocol-version check is undocumented-missing (Client.Java-003). |
+| 8 | Code organization & conventions | Issue found: ~80 duplicated lines across the two clients (Client.Java-009). |
+| 9 | Testing coverage | Issue found: alarm RPCs, TLS setup, async streams, and queue overflow untested (Client.Java-007). |
+| 10 | Documentation & comments | Issue found: README/Javadoc assert undocumented scope names (Client.Java-010). |
+
+## Findings
+
+### Client.Java-001
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Security |
+| Location | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewaySecrets.java:30-32` |
+| Status | Open |
+
+**Description:** `redactApiKey` preserves the leading and trailing four characters of the key. A gateway API key has the form `mxgw_<key-id>_<secret>`; the last four characters belong to the secret portion, so the "redacted" form leaks 4 characters of the actual secret into logs, CLI JSON output (`CommonOptions.redactedJsonMap`), and `MxGatewayClientOptions.toString()`. CLAUDE.md states API keys must never reach logs.
+
+**Recommendation:** Redact the secret entirely. Show only a stable non-secret prefix (e.g. the `mxgw_<key-id>_` portion) and mask everything after it, or emit a fixed `mxgw_***` form. Do not echo any trailing characters of the secret.
+
+**Resolution:** _(open)_
+
+### Client.Java-002
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Concurrency & thread safety |
+| Location | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxEventStream.java:31,66-92` |
+| Status | Open |
+
+**Description:** The `next` field is a plain (non-volatile) instance field, and `MxEventStream` exposes no thread-confinement guarantee. More concretely, a queue-overflow `offer()` and a `close()` `offer(END)` can interleave so the overflow exception is enqueued after `END` and never observed — the contract that "next() throws after overflow" is not guaranteed once `close()` has been called.
+
+**Recommendation:** Document single-consumer-thread usage explicitly in the Javadoc, and serialise terminal state transitions (overflow vs END vs close) behind a single guarded flag so the first terminal condition wins deterministically.
+
+**Resolution:** _(open)_
+
+### Client.Java-003
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | mxaccessgw conventions |
+| Location | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:119-140` |
+| Status | Open |
+
+**Description:** `OpenSessionReply` carries `gateway_protocol_version` (proto field 8), and `MxGatewayClientVersion.GATEWAY_PROTOCOL_VERSION` exists so the client can reject incompatible generated-code inputs. The client never reads `reply.getGatewayProtocolVersion()` nor compares it against the compiled-in version. A client built against an older/newer contract issues commands blindly and fails with confusing downstream errors instead of a clear version-mismatch failure.
+
+**Recommendation:** In `openSession`/`openSessionRaw`, compare `reply.getGatewayProtocolVersion()` with `MxGatewayClientVersion.gatewayProtocolVersion()` and throw a typed `MxGatewayException` on mismatch.
+
+**Resolution:** _(open)_
+
+### Client.Java-004
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Correctness & logic bugs |
+| Location | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewaySession.java:114-120,157-163,191-197` |
+| Status | Open |
+
+**Description:** `register`, `addItem`, and `addItem2` check `reply.hasRegister()`/`hasAddItem()` and otherwise fall back to `reply.getReturnValue().getInt32Value()`. If the gateway returns a reply with neither the typed payload nor a `return_value` set, the method silently returns `0` — indistinguishable from a legitimate handle of 0. This masks a contract violation rather than surfacing it.
+
+**Recommendation:** If the expected typed payload is absent and no `return_value` is present, throw `MxGatewayException` (protocol violation) instead of returning `0`.
+
+**Resolution:** _(open)_
+
+### Client.Java-005
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewaySession.java:92-105` |
+| Status | Open |
+
+**Description:** `close()` delegates to `closeRaw()`, which performs a network RPC. When `MxGatewaySession` is used in try-with-resources and the body throws, a failure inside `closeSession` (e.g. `WORKER_UNAVAILABLE`) throws from `close()` and replaces the original exception as the propagated throwable (the body exception becomes a suppressed exception) — a known try-with-resources footgun for I/O-performing `close()`.
+
+**Recommendation:** Either make `close()` swallow/log close-time failures (keeping `closeRaw()` for callers who want the result), or document clearly that `close()` performs a network call that can throw.
+
+**Resolution:** _(open)_
+
+### Client.Java-006
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Performance & resource management |
+| Location | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:323-328`, `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/GalaxyRepositoryClient.java:279-284` |
+| Status | Open |
+
+**Description:** `close()` (the `AutoCloseable` method invoked by try-with-resources) calls only `ownedChannel.shutdown()` and returns immediately without awaiting termination. In-flight calls and Netty event-loop threads may still be running when the caller assumes the resource is released. `closeAndAwaitTermination()` does it correctly but is not the method try-with-resources uses, and the README examples all rely on try-with-resources.
+
+**Recommendation:** Have `close()` await termination for a bounded time and `shutdownNow()` on timeout (the logic already in `closeAndAwaitTermination()`), or document that try-with-resources callers should call `closeAndAwaitTermination()`.
+
+**Resolution:** _(open)_
+
+### Client.Java-007
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `clients/java/mxgateway-client/src/test/java/com/dohertylan/mxgateway/client/` |
+| Status | Open |
+
+**Description:** The alarm surface — `acknowledgeAlarm`/`acknowledgeAlarmAsync`/`queryActiveAlarms` and `MxGatewayActiveAlarmsSubscription` — has zero test coverage. TLS channel construction, the async `streamEventsAsync` path, `MxGatewayEventSubscription` pre-start cancellation, and `MxEventStream` queue overflow are likewise untested. `JavaClientDesign.md` explicitly lists async stream-observer cancellation and status/error mapping as required tests.
+
+**Recommendation:** Add in-process gRPC tests for the alarm RPCs, the async streaming/subscription cancellation paths, and at least one TLS-config construction test.
+
+**Resolution:** _(open)_
+
+### Client.Java-008
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Error handling & resilience |
+| Location | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:298-304` |
+| Status | Open |
+
+**Description:** `acknowledgeAlarmAsync` and `openSessionAsync` apply `ensureProtocolSuccess` inside `thenApply`. If that validator throws a non-`MxGatewayException` `RuntimeException` it is wrapped by `CompletionException` with no `fromGrpc` normalisation, unlike the synchronous paths which normalise via `try/catch`. The async and sync error surfaces are therefore inconsistent.
+
+**Recommendation:** Wrap the `thenApply` body so any non-`MxGatewayException` is routed through `MxGatewayErrors.fromGrpc`, matching the synchronous methods.
+
+**Resolution:** _(open)_
+
+### Client.Java-009
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/GalaxyRepositoryClient.java:310-391`, `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:346-413` |
+| Status | Open |
+
+**Description:** `createChannel`, `withDeadline`, `withStreamDeadline`, and `toCompletable` are duplicated nearly verbatim across `MxGatewayClient` and `GalaxyRepositoryClient` (~80 lines). A fix to one will not propagate to the other.
+
+**Recommendation:** Extract the channel-builder and future-adaptor helpers into a shared package-private utility class.
+
+**Resolution:** _(open)_
+
+### Client.Java-010
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:269-272`, `clients/java/README.md:76` |
+| Status | Open |
+
+**Description:** The `acknowledgeAlarm` Javadoc states the gateway authenticates against an `invoke:alarm-ack` scope, and the README states the Galaxy Repository requires a `metadata:read` scope. CLAUDE.md's documented scope set names neither — the Javadoc/README assert a scope contract the project's own auth documentation does not corroborate.
+
+**Recommendation:** Reconcile the scope names with `src/MxGateway.Server/Security/` and CLAUDE.md; correct the Javadoc/README to the actual scope strings, or fix CLAUDE.md if sub-scopes were genuinely added.
+
+**Resolution:** _(open)_
+
+### Client.Java-011
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Performance & resource management |
+| Location | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxEventStream.java:37-63` |
+| Status | Open |
+
+**Description:** The event stream relies on default gRPC auto-inbound flow control: the async stub auto-requests messages, so the server can push faster than the 16-element bounded queue drains. A momentarily slow consumer triggers queue overflow and an immediate stream-fault cancel. This is consistent with the documented fail-fast event-backpressure design, but the client never applies real flow control, so even brief consumer stalls kill the subscription.
+
+**Recommendation:** Confirm fail-fast is intended (it appears to be); if so, document it on `MxEventStream` so callers know a slow consumer terminates the stream. Optionally expose the queue capacity or opt-in flow control.
+
+**Resolution:** _(open)_
+
+### Client.Java-012
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `clients/java/mxgateway-cli/src/main/java/com/dohertylan/mxgateway/cli/MxGatewayCli.java:667-674` |
+| Status | Open |
+
+**Description:** `CommonOptions.resolved()` mutates `this` (`resolvedApiKey`, `resolvedTimeout`) and returns `this`, but `toClientOptions()` and `redactedJsonMap()` read those mutated fields. If `redactedJsonMap()` is ever called before `resolved()`, it silently emits empty-string defaults. The "return this after mutating" pattern is fragile and surprising.
+
+**Recommendation:** Make `resolved()` return an immutable resolved value object, or compute `resolvedApiKey`/`resolvedTimeout` lazily in their getters so call ordering cannot produce stale output.
+
+**Resolution:** _(open)_

code-reviews/Client.Python/findings.md

@@ -0,0 +1,207 @@
+# Code Review — Client.Python
+
+| Field | Value |
+|---|---|
+| Module | `clients/python` |
+| Reviewer | Claude Code |
+| Review date | 2026-05-18 |
+| Commit reviewed | `3cc53a8` |
+| Status | Reviewed |
+| Open findings | 12 |
+
+## Checklist coverage
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issues found: dead `closed` variable (Client.Python-004); float/bytes value-mapping assumptions (Client.Python-008). |
+| 2 | mxaccessgw conventions | Largely adheres; one missing export and a `*_raw` MXAccess-failure documentation gap (Client.Python-002, Client.Python-012). |
+| 3 | Concurrency & thread safety | Issue found: `close()` idempotency claim does not hold under concurrent close (Client.Python-006). |
+| 4 | Error handling & resilience | Issues found: inconsistent timeout-kwarg fallback (Client.Python-003); `success == 0` default-value hazard (Client.Python-011); inconsistent cancel helpers (Client.Python-007). |
+| 5 | Security | No issues found — API keys redacted in repr and CLI output, TLS supported, no secret logging. |
+| 6 | Performance & resource management | Issue found: `discover_hierarchy` buffers the whole hierarchy in memory (Client.Python-005). |
+| 7 | Design-document adherence | Matches the design docs closely; minor CLI doc drift (Client.Python-001). |
+| 8 | Code organization & conventions | Issues found: `MxGatewayCommandError` omitted from `__all__` (Client.Python-002); fragile circular-import workaround (Client.Python-010). |
+| 9 | Testing coverage | Issue found: `write2`, `add_item2`, bulk-size limits, TLS `ca_file`, and CLI command bodies untested (Client.Python-009). |
+| 10 | Documentation & comments | Issue found: stale "scaffold" package description (Client.Python-001). |
+
+## Findings
+
+### Client.Python-001
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `clients/python/pyproject.toml:8,25`, `clients/python/src/mxgateway_cli/commands.py:25` |
+| Status | Open |
+
+**Description:** The package `description` in `pyproject.toml` still says "Async Python client *scaffold*" even though the client is fully implemented. Stale "scaffold" wording misrepresents maturity to anyone reading PyPI metadata. (The `mxgw-py` console-script name is itself consistent between `pyproject.toml` and the README.)
+
+**Recommendation:** Update the `pyproject.toml` description to drop "scaffold"; keep README CLI examples in sync with the actual `mxgw-py` entry point.
+
+**Resolution:** _(open)_
+
+### Client.Python-002
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `clients/python/src/mxgateway/__init__.py:27` |
+| Status | Open |
+
+**Description:** `MxGatewayCommandError` is imported into `__init__.py` and is a documented public exception, but it is missing from `__all__`. It is the parent of `MxAccessError` and a meaningful catch target, so omitting it from the public surface is inconsistent — `from mxgateway import *` will not expose it and tooling that respects `__all__` treats it as private.
+
+**Recommendation:** Add `"MxGatewayCommandError"` to the `__all__` list.
+
+**Resolution:** _(open)_
+
+### Client.Python-003
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `clients/python/src/mxgateway/client.py:125-137,155-173` |
+| Status | Open |
+
+**Description:** `stream_events_raw` and `query_active_alarms` call the stub directly with a `timeout` kwarg when `stream_timeout` is set, with no `TypeError` fallback. `galaxy.py:watch_deploy_events` and `_unary` *do* have a fallback that strips `timeout` if the callable rejects it. This asymmetry means a fake/older stub that does not accept `timeout` crashes for gateway streams but not Galaxy streams. It is only masked today because `stream_timeout` defaults to `None`.
+
+**Recommendation:** Apply the same `try/except TypeError` timeout-fallback pattern to `stream_events_raw` and `query_active_alarms`, or remove the fallback everywhere and standardise on a single behaviour.
+
+**Resolution:** _(open)_
+
+### Client.Python-004
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `clients/python/src/mxgateway_cli/commands.py:386,402-404` |
+| Status | Open |
+
+**Description:** In `_smoke`, the local variable `closed` is set to `False` and never reassigned; the `finally` block's `if not closed:` is therefore always true. This is dead/misleading code suggesting a removed early-close path.
+
+**Recommendation:** Remove the `closed` variable and the `if not closed:` guard; call `await session.close()` directly in the `finally` block (or use `async with session:`).
+
+**Resolution:** _(open)_
+
+### Client.Python-005
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Performance & resource management |
+| Location | `clients/python/src/mxgateway/galaxy.py:117-140` |
+| Status | Open |
+
+**Description:** `discover_hierarchy` pages through the entire Galaxy object hierarchy and accumulates every `GalaxyObject` (each carrying its full attribute list) into a single in-memory `list` before returning. For a large Galaxy this is a very large allocation with no streaming alternative and no caller-side bound.
+
+**Recommendation:** Offer an async-generator variant (e.g. `iter_hierarchy()`) that yields objects/pages as they arrive, keeping `discover_hierarchy()` as a convenience wrapper. At minimum document the memory characteristic.
+
+**Resolution:** _(open)_
+
+### Client.Python-006
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Concurrency & thread safety |
+| Location | `clients/python/src/mxgateway/client.py:74-82`, `clients/python/src/mxgateway/galaxy.py:85-93`, `clients/python/src/mxgateway/session.py:38-55` |
+| Status | Open |
+
+**Description:** `close()` on the clients and `Session.close()` use a plain `self._closed` check-then-set with an `await` between, with no lock. If two coroutines call `close()` concurrently both can pass the guard before either sets it, causing a double `channel.close()` / double `CloseSession` RPC. Single-task usage is the documented contract, so impact is low, but the idempotency guarantee asserted in docstrings only holds for sequential calls.
+
+**Recommendation:** Set `self._closed = True` before the `await`, or guard with an `asyncio.Lock`, so the idempotency claim holds under concurrent close.
+
+**Resolution:** _(open)_
+
+### Client.Python-007
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Error handling & resilience |
+| Location | `clients/python/src/mxgateway/client.py:204-213` |
+| Status | Open |
+
+**Description:** `_canceling_iterator` (gateway event stream) does not catch `asyncio.CancelledError` to invoke `call.cancel()` explicitly — it relies on the `finally` block. `galaxy.py:_canceling_iterator` *does* explicitly catch `CancelledError`, cancel, and re-raise. The two are functionally equivalent today, but the inconsistency between near-identical helpers invites future divergence.
+
+**Recommendation:** Make the two `_canceling_iterator` helpers identical, ideally by factoring a single shared helper.
+
+**Resolution:** _(open)_
+
+### Client.Python-008
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `clients/python/src/mxgateway/values.py:62-67,83-88` |
+| Status | Open |
+
+**Description:** `to_mx_value` maps any Python `float` to `VT_R8`/`MX_DATA_TYPE_DOUBLE` with no handling for `nan`/`inf`, which are serialised and forwarded to MXAccess which may reject or mis-handle them. `bytes` is mapped to `VT_RECORD`/`MX_DATA_TYPE_UNKNOWN`, a questionable default. The `data_type` keyword exists but `Session.write` never forwards it.
+
+**Recommendation:** Document the float/bytes mapping assumptions, optionally validate finiteness, and consider plumbing the `data_type` keyword through `Session.write`/`write2`.
+
+**Resolution:** _(open)_
+
+### Client.Python-009
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Testing coverage |
+| Location | `clients/python/tests/` |
+| Status | Open |
+
+**Description:** Several non-trivial public paths are untested: `Session.write2`/`add_item2` request construction; the bulk-size limit `_ensure_bulk_size`/`MAX_BULK_ITEMS` guard; the `None`-argument `TypeError` guards in bulk methods; the TLS `ca_file` read path in `create_channel`; most CLI command bodies; and `map_rpc_error`'s default (non-auth) branch.
+
+**Recommendation:** Add tests for `write2`/`add_item2` request shape, the bulk-size `ValueError`, the `ca_file` TLS branch, the generic `map_rpc_error` fallthrough, and at least one happy-path CLI command using a fake stub.
+
+**Resolution:** _(open)_
+
+### Client.Python-010
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `clients/python/src/mxgateway/session.py:404`, `clients/python/src/mxgateway_cli/commands.py:422-425` |
+| Status | Open |
+
+**Description:** `session.py` ends with a module-level late import `from .client import GatewayClient  # noqa: E402` purely to satisfy a string type hint, and `commands.py:_session` does a function-local import. Both work around a circular dependency that `from __future__ import annotations` (already in effect) makes unnecessary. `_session` also lacks a return type annotation.
+
+**Recommendation:** Drop the runtime late import in `session.py` and use a `TYPE_CHECKING`-guarded import for the hint; add the `-> Session` return annotation to `commands.py:_session`.
+
+**Resolution:** _(open)_
+
+### Client.Python-011
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Error handling & resilience |
+| Location | `clients/python/src/mxgateway/errors.py:122-148` |
+| Status | Open |
+
+**Description:** `ensure_mxaccess_success` raises `MxAccessError` if any `mx_status.success == 0`. This treats `success == 0` as the failure sentinel, but `0` is also the proto3 scalar default for an unset `MxStatusProxy`. If the gateway ever returns a reply with an unpopulated status entry (e.g. a partially-filled bulk result), the client raises `MxAccessError` even though no real failure occurred.
+
+**Recommendation:** Confirm against the proto/gateway contract whether `success` is guaranteed populated for every `statuses` entry; if not, key the failure decision on an explicit failure field rather than the `success == 0` default.
+
+**Resolution:** _(open)_
+
+### Client.Python-012
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | mxaccessgw conventions |
+| Location | `clients/python/src/mxgateway/client.py:84-108`, `clients/python/src/mxgateway/session.py:57-77` |
+| Status | Open |
+
+**Description:** `Session.invoke_raw` does not run `ensure_mxaccess_success` while `Session.invoke` does, so a caller using `invoke_raw` for parity tests gets a reply where an MXAccess HRESULT failure is silently embedded with no exception. This is by design but under-documented — the README's "preserve raw replies" sentence does not state that `*_raw` methods skip MXAccess-failure detection entirely.
+
+**Recommendation:** Document explicitly (README + docstring) that `*_raw` methods surface MXAccess HRESULT/status failures only inside the reply and do not raise `MxAccessError`, so parity-test callers know to inspect `protocol_status`/`hresult`/`statuses` themselves.
+
+**Resolution:** _(open)_

code-reviews/Client.Rust/findings.md

@@ -0,0 +1,207 @@
+# Code Review — Client.Rust
+
+| Field | Value |
+|---|---|
+| Module | `clients/rust` |
+| Reviewer | Claude Code |
+| Review date | 2026-05-18 |
+| Commit reviewed | `3cc53a8` |
+| Status | Reviewed |
+| Open findings | 0 |
+
+## Checklist coverage
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issues found: a stale unit test fails the suite (Client.Rust-003); handle extractors silently return 0 on a shapeless OK reply (Client.Rust-005). |
+| 2 | mxaccessgw conventions | `cargo clippy --workspace --all-targets -- -D warnings` fails (Client.Rust-001, Client.Rust-002, Client.Rust-012), violating a CLAUDE.md hard requirement; hard-coded correlation ids (Client.Rust-011). |
+| 3 | Concurrency & thread safety | No issues found — clients are cheaply cloneable, streams are `Send`, drop-cancels-call is verified. |
+| 4 | Error handling & resilience | Issues found: empty-vec on shapeless bulk reply (Client.Rust-006); no transient/permanent classification (Client.Rust-010). |
+| 5 | Security | No issues found — API keys redacted in `Debug`/`Display`, status messages scrubbed, TLS handled correctly. |
+| 6 | Performance & resource management | Issue found: value/array projections clone every element, doubling array memory (Client.Rust-008). |
+| 7 | Design-document adherence | Issue found: `RustClientDesign.md` documents a stale crate layout and an unused `tracing` dependency (Client.Rust-007). |
+| 8 | Code organization & conventions | Issue found: `BulkReplyKind` trips a clippy lint; undocumented public methods (Client.Rust-001, Client.Rust-002). |
+| 9 | Testing coverage | Issue found: TLS setup, mid-stream fault propagation, and the bulk-size cap untested (Client.Rust-009). |
+| 10 | Documentation & comments | Issue found: the version-constant doc comment is wrong (Client.Rust-004). |
+
+## Findings
+
+### Client.Rust-001
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | mxaccessgw conventions |
+| Location | `clients/rust/src/options.rs:98,143` |
+| Status | Resolved |
+
+**Description:** `with_max_grpc_message_bytes` and `max_grpc_message_bytes` have no `///` doc comments. The crate sets `#![warn(missing_docs)]` and CLAUDE.md mandates that `cargo clippy --workspace --all-targets -- -D warnings` pass. Under `-D warnings` these become hard errors, so clippy fails to compile the crate — breaking the documented build/test workflow for the module.
+
+**Recommendation:** Add doc comments to both methods, e.g. `/// Maximum encoded/decoded gRPC message size in bytes (default 16 MiB).`
+
+**Resolution:** Resolved in `0d8a28d` (2026-05-18): doc comments added to both methods.
+
+### Client.Rust-002
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | mxaccessgw conventions |
+| Location | `clients/rust/src/session.rs:522` |
+| Status | Resolved |
+
+**Description:** The `BulkReplyKind` enum's variants (`AddItemBulk`, `AdviseItemBulk`, `RemoveItemBulk`, `UnAdviseItemBulk`, `SubscribeBulk`, `UnsubscribeBulk`) all share the `Bulk` suffix, tripping `clippy::enum_variant_names`. Under `-D warnings` this is a compile error, so `cargo clippy --workspace --all-targets -- -D warnings` fails — a violation of the CLAUDE.md requirement that clippy pass cleanly.
+
+**Recommendation:** Rename the variants to drop the common suffix (e.g. `AddItem`, `AdviseItem`, …) or add a narrowly-scoped `#[allow(clippy::enum_variant_names)]` with a reason comment.
+
+**Resolution:** Resolved in `0d8a28d` (2026-05-18): variants renamed to `AddItem`/`AdviseItem`/`RemoveItem`/`UnAdviseItem`/`Subscribe`/`Unsubscribe`, which no longer share a common suffix.
+
+### Client.Rust-003
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Correctness & logic bugs |
+| Location | `clients/rust/crates/mxgw-cli/src/main.rs:1051` |
+| Status | Resolved |
+
+**Description:** The unit test `version_json_output_has_protocol_versions` asserts `value["gatewayProtocolVersion"] == 2`, but `GATEWAY_PROTOCOL_VERSION` is `3` (version.rs:10), matching the authoritative server constant `GatewayContractInfo.GatewayProtocolVersion = 3`. The test fails, so `cargo test --workspace` (the documented test step) does not pass — the test was not updated when the protocol version was bumped.
+
+**Recommendation:** Update the assertion to `3`, or better, assert against `GATEWAY_PROTOCOL_VERSION` so it cannot drift again.
+
+**Resolution:** Resolved in `0d8a28d` (2026-05-18): the test now asserts against the `GATEWAY_PROTOCOL_VERSION` / `WORKER_PROTOCOL_VERSION` constants, so it cannot drift again.
+
+### Client.Rust-004
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `clients/rust/src/version.rs:7` |
+| Status | Resolved |
+
+**Description:** `CLIENT_VERSION` is `"0.1.0-dev"` and its doc comment claims "Mirrors `Cargo.toml`", but `Cargo.toml` declares `version = "0.1.0"` (no `-dev` suffix). The comment is misleading and the value is not actually kept in sync with the manifest.
+
+**Recommendation:** Either set `CLIENT_VERSION` from the build via `env!("CARGO_PKG_VERSION")`, or correct the constant to `"0.1.0"` and drop the "Mirrors Cargo.toml" claim.
+
+**Resolution:** Resolved in `0d8a28d` (2026-05-18): `CLIENT_VERSION` is now `env!("CARGO_PKG_VERSION")`, taken from `Cargo.toml` at compile time so the two cannot drift.
+
+### Client.Rust-005
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Correctness & logic bugs |
+| Location | `clients/rust/src/session.rs:489-520` |
+| Status | Resolved |
+
+**Description:** `register_server_handle`, `add_item_handle`, and `add_item2_handle` fall through to `reply.return_value … .unwrap_or_default()`, returning `0` when the reply carries neither the expected typed payload nor an `Int32` `return_value`. Because `Session::invoke` has already confirmed `protocol_status == Ok`, a malformed-but-OK reply silently yields handle `0`, which the caller then uses as a real handle against the worker.
+
+**Recommendation:** Return `Err(Error::ProtocolStatus { … })` (or a dedicated `Error::MalformedReply`) when an OK reply lacks an extractable handle, instead of defaulting to `0`.
+
+**Resolution:** Resolved in `0d8a28d` (2026-05-18): the three handle extractors now return `Result<i32, Error>` and yield the new `Error::MalformedReply` when an OK reply carries no usable handle.
+
+### Client.Rust-006
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `clients/rust/src/session.rs:531-555` |
+| Status | Resolved |
+
+**Description:** `bulk_results` returns `Vec::new()` for any `(payload, kind)` combination that does not match the expected arm — including an OK reply carrying the wrong or no payload. A caller of `subscribe_bulk`/`add_item_bulk` then sees an empty result vector and cannot distinguish "zero items processed" from "gateway returned a shapeless reply".
+
+**Recommendation:** Treat a missing/mismatched bulk payload on an OK reply as an error rather than an empty vector, or document the empty-vec fallback explicitly and log it.
+
+**Resolution:** Resolved in `0d8a28d` (2026-05-18): `bulk_results` now returns `Result<Vec<SubscribeResult>, Error>` and yields `Error::MalformedReply` on a mismatched or absent bulk payload.
+
+### Client.Rust-007
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Design-document adherence |
+| Location | `clients/rust/RustClientDesign.md:14-55` |
+| Status | Resolved |
+
+**Description:** `RustClientDesign.md` is stale relative to the implemented code. It documents a nested `crates/mxgateway-client/` layout (the real crate root is `clients/rust/` with a flat `src/`), and lists `tracing` among "Expected dependencies", but `tracing` appears in no `Cargo.toml`. CLAUDE.md requires docs to change with the source.
+
+**Recommendation:** Update `RustClientDesign.md` to the actual flat layout and remove `tracing` from the dependency list (or add `tracing` if structured logging is genuinely intended).
+
+**Resolution:** Resolved in `0d8a28d` (2026-05-18): the "Crate Layout" section now shows the actual flat layout (`mxgateway-client` as the workspace-root crate, `mxgw-cli` as a member) and the unused `tracing` entry was removed from the dependency list.
+
+### Client.Rust-008
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Performance & resource management |
+| Location | `clients/rust/src/value.rs:161-261` |
+| Status | Resolved |
+
+**Description:** `MxValueProjection::from_proto` and `MxArrayProjection::from_proto` deep-clone every element out of the wire message while `MxValue`/`MxArrayValue` also retain the original `raw` message. Every `MxValue` therefore holds two copies of its payload, wasteful for large string arrays or raw blobs arriving on the event stream.
+
+**Recommendation:** Compute the projection lazily on demand, or have the projection borrow from `raw`, so array/raw payloads are not duplicated for every wrapped value.
+
+**Resolution:** Resolved in `0d8a28d` (2026-05-18): `MxValue` and `MxArrayValue` no longer cache a `projection` field — `projection()` computes the typed view on demand from `raw`. A value built only to be sent over the wire now holds a single copy of its payload and pays no projection cost.
+
+### Client.Rust-009
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `clients/rust/tests/client_behavior.rs`, `clients/rust/src/galaxy.rs` |
+| Status | Resolved |
+
+**Description:** Several critical paths are untested: TLS channel setup (`with_plaintext(false)` / CA-file loading), mid-stream `tonic::Status` fault propagation through `EventStream`/`DeployEventStream` (tests only send `Ok` items), and the bulk-size cap (`ensure_bulk_size` rejecting >1000 items).
+
+**Recommendation:** Add tests that (a) feed an `Err(Status)` into the event/deploy streams and assert it surfaces as the mapped `Error`, (b) assert `add_item_bulk` with 1001 items returns `Error::InvalidArgument`, and (c) exercise the CA-file/`InvalidEndpoint` error path.
+
+**Resolution:** Resolved in `0d8a28d` (2026-05-18): added `add_item_bulk_rejects_input_above_the_thousand_item_cap`, `event_stream_surfaces_a_mid_stream_status_fault` (the fake gateway now optionally emits a mid-stream `Status::unavailable`), and `connect_with_unreadable_ca_file_reports_invalid_endpoint`.
+
+### Client.Rust-010
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Error handling & resilience |
+| Location | `clients/rust/src/client.rs:255-268`, `clients/rust/src/galaxy.rs:204-216` |
+| Status | Resolved |
+
+**Description:** The client applies only a per-call deadline via `Request::set_timeout` and has no retry, reconnect, or transient-vs-permanent classification. A transient `Unavailable` (e.g. a gateway restart) maps to the catch-all `Error::Status` and is indistinguishable from a permanent failure. This is an acceptable v1 stance but is undocumented.
+
+**Recommendation:** Either add a documented `Error::Unavailable` variant classifying `Code::Unavailable`/`Code::ResourceExhausted`, or explicitly document in the README that the client performs no retries and that transient failures arrive as `Error::Status`.
+
+**Resolution:** Resolved in `0d8a28d` (2026-05-18): added the `Error::Unavailable` variant; `From<tonic::Status>` maps `Code::Unavailable` and `Code::ResourceExhausted` to it, so callers can classify transient failures without unwrapping the raw status.
+
+### Client.Rust-011
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | mxaccessgw conventions |
+| Location | `clients/rust/src/session.rs:469` |
+| Status | Resolved |
+
+**Description:** `command_request` hard-codes `client_correlation_id` as `format!("rust-client-{}", kind.as_str_name())`. Every invocation of the same command kind on a session uses an identical correlation id, so the id cannot correlate a specific request/reply pair in gateway logs or among concurrent in-flight calls. MXAccess parity diagnostics rely on correlation ids being unique per call.
+
+**Recommendation:** Append a per-call unique suffix (monotonic counter or UUID) to the correlation id, or expose a way for the caller to supply one.
+
+**Resolution:** Resolved in `0d8a28d` (2026-05-18): correlation ids are built by `next_correlation_id`, which appends a process-wide atomic sequence number; `Session::close` uses it too.
+
+### Client.Rust-012
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | mxaccessgw conventions |
+| Location | `clients/rust/src/galaxy.rs:282` |
+| Status | Resolved |
+
+**Description:** Found while verifying the fix for Client.Rust-001/002: `cargo clippy --workspace --all-targets -- -D warnings` reported a third violation the original review missed. The `get_last_deploy_time` test fake calls `.clone()` on a `MutexGuard<Option<prost_types::Timestamp>>`, and `Option<Timestamp>` is `Copy` (`clippy::clone_on_copy`). Under `-D warnings` this is a compile error, so clippy still did not pass after Client.Rust-001/002 alone.
+
+**Recommendation:** Dereference instead of cloning: `*self.state.last_deploy.lock().unwrap()`.
+
+**Resolution:** Resolved in `0d8a28d` (2026-05-18): replaced `.clone()` with a deref. `cargo clippy --workspace --all-targets -- -D warnings` now passes cleanly.

code-reviews/Contracts/findings.md

@@ -0,0 +1,147 @@
+# Code Review — Contracts
+
+| Field | Value |
+|---|---|
+| Module | `src/MxGateway.Contracts` |
+| Reviewer | Claude Code |
+| Review date | 2026-05-18 |
+| Commit reviewed | `6c64030` |
+| Status | Reviewed |
+| Open findings | 8 |
+
+## Checklist coverage
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | No functional bugs; one missing reply-payload case for the by-name ack command and an `int32`-typed `success` flag that reads like a bool (Contracts-002, Contracts-006). |
+| 2 | mxaccessgw conventions | Additive-only evolution honored (no renumbered/removed tags), MXAccess-aligned naming consistent, generated code untouched; no `reserved` statements declared as a guardrail (Contracts-005). |
+| 3 | Concurrency & thread safety | N/A — pure contract definitions plus a static const class with no shared mutable state. |
+| 4 | Error handling & resilience | HRESULT / `MxStatusProxy` / `ProtocolStatus` carriers are complete; the worker-side by-name alarm ack has no dedicated reply payload (Contracts-002). |
+| 5 | Security | Credential-sensitive fields are clearly commented; no secrets forced into loggable shapes. No issues found. |
+| 6 | Performance & resource management | `DiscoverHierarchy` is paged; alarm-snapshot streams are server-streamed; no bloat issues. No issues found. |
+| 7 | Design-document adherence | `.proto` files match design intent but `docs/Grpc.md` is stale (Contracts-001); worker vs public alarm-status shapes unreconciled in docs (Contracts-008). |
+| 8 | Code organization & conventions | Package/file layout correct; `mxaccess_worker.proto` Protobuf item missing `ProtoRoot` (Contracts-003); stale class summary (Contracts-004). |
+| 9 | Testing coverage | Gateway/worker/alarm round-trips covered; Galaxy Repository protos and raw `MxArray` paths untested (Contracts-007). |
+| 10 | Documentation & comments | Proto comments accurate and domain-rich; one stale class summary (Contracts-004). |
+
+## Findings
+
+### Contracts-001
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Design-document adherence |
+| Location | `docs/Grpc.md:13` (and `:3`, `:32`, `:39`) |
+| Status | Open |
+
+**Description:** `mxaccess_gateway.proto` now declares six RPCs on `MxAccessGateway` (`OpenSession`, `CloseSession`, `Invoke`, `StreamEvents`, `AcknowledgeAlarm`, `QueryActiveAlarms`). `docs/Grpc.md` still describes "the four `MxAccessGateway` RPCs" in its type table and omits `AcknowledgeAlarm`/`QueryActiveAlarms` from the Validation Rules table. CLAUDE.md requires docs to change in the same commit as the contract; the alarm RPC commits left this doc stale and misleading about the public surface.
+
+**Recommendation:** Update `docs/Grpc.md` to enumerate all six RPCs and add `AcknowledgeAlarm`/`QueryActiveAlarms` to the type/handler and validation tables, or explicitly cross-reference `AlarmClientDiscovery.md`.
+
+**Resolution:** _(open)_
+
+### Contracts-002
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `src/MxGateway.Contracts/Protos/mxaccess_gateway.proto:384-385`, `:95` |
+| Status | Open |
+
+**Description:** `MxCommandKind` includes `MX_COMMAND_KIND_ACKNOWLEDGE_ALARM_BY_NAME = 29` and `MxCommand.payload` carries `AcknowledgeAlarmByNameCommand acknowledge_alarm_by_name_command = 38`, but `MxCommandReply.payload` has only `acknowledge_alarm = 34` and `query_active_alarms = 35` — there is no by-name reply case. The by-name ack must reuse `AcknowledgeAlarmReplyPayload` or rely on the top-level `hresult`. The command/reply payload asymmetry is undocumented and easy to dispatch incorrectly.
+
+**Recommendation:** Either add an explicit comment to `MxCommandReply` stating that by-name ack reuses the `acknowledge_alarm` payload case, or add a dedicated payload case for symmetry, and document the chosen contract in `docs/Contracts.md` / `AlarmClientDiscovery.md`.
+
+**Resolution:** _(open)_
+
+### Contracts-003
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `src/MxGateway.Contracts/MxGateway.Contracts.csproj:10` |
+| Status | Open |
+
+**Description:** The `<Protobuf>` item for `mxaccess_worker.proto` omits `ProtoRoot="Protos"`, while the items for `mxaccess_gateway.proto` (line 9) and `galaxy_repository.proto` (line 11) both set it. `mxaccess_worker.proto` does `import "mxaccess_gateway.proto"`, which resolves only because Grpc.Tools adds the importing file's own directory to the proto path. The inconsistency is fragile — tooling changes to ProtoRoot handling could break import resolution.
+
+**Recommendation:** Add `ProtoRoot="Protos"` to the `mxaccess_worker.proto` `<Protobuf>` item so all three entries are consistent.
+
+**Resolution:** _(open)_
+
+### Contracts-004
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `src/MxGateway.Contracts/GatewayContractInfo.cs:3-6` |
+| Status | Open |
+
+**Description:** The XML summary says the class exposes version metadata "before generated protobuf contracts are introduced." Generated protobuf contracts have long been introduced and are consumed across the solution. The comment is stale; the class now holds the authoritative `GatewayProtocolVersion`/`WorkerProtocolVersion` advertised in `OpenSessionReply` and used to validate `WorkerEnvelope` framing.
+
+**Recommendation:** Reword the summary to describe the current purpose — version constants advertised in `OpenSessionReply` and used to validate `WorkerEnvelope` protocol framing.
+
+**Resolution:** _(open)_
+
+### Contracts-005
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | mxaccessgw conventions |
+| Location | `src/MxGateway.Contracts/Protos/mxaccess_gateway.proto`, `src/MxGateway.Contracts/Protos/mxaccess_worker.proto` |
+| Status | Open |
+
+**Description:** The ProtobufStyleGuide mandates reserving removed field numbers / enum values. Evolution to date has been purely additive, so this is not a current violation — but none of the `.proto` files contain any `reserved` declarations, leaving no in-file guardrail for the first removal. This is a latent maintainability gap.
+
+**Recommendation:** When any field or enum value is eventually removed, add a `reserved` range/name in the same change. Consider a short comment block in each message documenting the policy so future editors apply `reserved` rather than reusing tags.
+
+**Resolution:** _(open)_
+
+### Contracts-006
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `src/MxGateway.Contracts/Protos/mxaccess_gateway.proto:647` |
+| Status | Open |
+
+**Description:** `MxStatusProxy.success` is declared `int32 success = 1` with no comment. The name reads like a boolean flag but the type is a 32-bit integer (mirroring MXAccess `MXSTATUS_PROXY`, which stores a numeric success/HResult-like value). Without a comment a client author can reasonably misinterpret the field (treat non-1 as failure, or expect only 0/1).
+
+**Recommendation:** Add a comment clarifying the semantic — what range of values it carries and how 0 vs non-zero map to MXAccess status — per the style guide rule to comment fields carrying raw MXAccess status detail.
+
+**Resolution:** _(open)_
+
+### Contracts-007
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `src/MxGateway.Tests/Contracts/ProtobufContractRoundTripTests.cs` |
+| Status | Open |
+
+**Description:** `ProtobufContractRoundTripTests` covers gateway command/reply/event, alarm transition, alarm ack request/reply, active-alarm snapshot, and the worker envelope. It has no coverage for: (a) any `galaxy_repository.proto` message (`DiscoverHierarchy*`, `GalaxyObject`, `GalaxyAttribute`, `DeployEvent`, the `root` oneof, wrapper-typed fields); (b) `BulkSubscribeReply`/`SubscribeResult` and the bulk command kinds; (c) `MxValue`/`MxArray` `raw_value`/`RawArray` (`bytes`) paths and the `WorkerFault`/`WorkerHeartbeat` IPC bodies.
+
+**Recommendation:** Add round-trip tests for the Galaxy Repository messages (including the `root` oneof and proto wrapper fields), the bulk-subscribe reply, and the remaining `WorkerEnvelope` body cases.
+
+**Resolution:** _(open)_
+
+### Contracts-008
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Design-document adherence |
+| Location | `src/MxGateway.Contracts/Protos/mxaccess_gateway.proto:451-459`, `:627-636` |
+| Status | Open |
+
+**Description:** The worker-side `AcknowledgeAlarmReplyPayload` carries the alarm-ack outcome as `int32 native_status`, while the public `AcknowledgeAlarmReply` carries it as `MxStatusProxy status` plus `optional int32 hresult`. The comment explains the worker echoes `native_status` into `AcknowledgeAlarmReply.hresult`, but the two outcome shapes (raw `int32` vs structured `MxStatusProxy`) are not reconciled in `docs/Contracts.md` / `AlarmClientDiscovery.md`. A reader cannot tell whether `MxStatusProxy status` is always populated or only on COM-layer failure.
+
+**Recommendation:** Document in `docs/Contracts.md` (or `AlarmClientDiscovery.md`) how the worker `native_status` maps onto the public reply's `status`/`hresult` pair so client authors know which field is authoritative.
+
+**Resolution:** _(open)_

code-reviews/IntegrationTests/findings.md

@@ -0,0 +1,177 @@
+# Code Review — IntegrationTests
+
+| Field | Value |
+|---|---|
+| Module | `src/MxGateway.IntegrationTests` |
+| Reviewer | Claude Code |
+| Review date | 2026-05-18 |
+| Commit reviewed | `6c64030` |
+| Status | Reviewed |
+| Open findings | 10 |
+
+## Checklist coverage
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issues found: IntegrationTests-003 (asserts only on first event), IntegrationTests-010 (`WaitForFirstMessageAsync` ignores cancellation). |
+| 2 | mxaccessgw conventions | Live tests correctly gated and skip (not fail) when prerequisites are absent; `LiveGalaxyRepositoryFactAttribute` undocumented in the opt-in matrix. |
+| 3 | Concurrency & thread safety | Issue found: IntegrationTests-007 (no `[Collection]`/parallelism guard for shared MXAccess/ZB/GLAuth). |
+| 4 | Error handling & resilience | Issue found: IntegrationTests-004 (cleanup `WaitAsync` can mask the original failure). |
+| 5 | Security | No production secrets; only documented dev GLAuth creds and a localhost ZB connection string, all env-overridable. No issues found. |
+| 6 | Performance & resource management | Worker process disposed transitively via session disposal; no leaked pipes/COM/processes. No issues found. |
+| 7 | Design-document adherence | Issues found: IntegrationTests-001 (Galaxy live suite absent from the opt-in matrix), IntegrationTests-002 (`GwAdmin` LDAP prerequisite undocumented). |
+| 8 | Code organization & conventions | Issue found: IntegrationTests-008 (three near-identical fact attributes). |
+| 9 | Testing coverage | Issues found: IntegrationTests-005 (thin MXAccess parity coverage), IntegrationTests-006 (thin LDAP failure-path coverage). |
+| 10 | Documentation & comments | Issue found: IntegrationTests-009 (`TestServerCallContext` mislabelled "Mock"). |
+
+## Findings
+
+### IntegrationTests-001
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Design-document adherence |
+| Location | `src/MxGateway.IntegrationTests/Galaxy/LiveGalaxyRepositoryFactAttribute.cs:7`, `src/MxGateway.IntegrationTests/Galaxy/GalaxyRepositoryLiveTests.cs` |
+| Status | Open |
+
+**Description:** The Galaxy Repository live test suite and its gating env var `MXGATEWAY_RUN_LIVE_GALAXY_TESTS` (plus connection-string override `MXGATEWAY_LIVE_GALAXY_CONN`) are completely absent from `docs/GatewayTesting.md`. CLAUDE.md mandates updating docs in the same change as the source. The opt-in matrix documents only the MXAccess and LDAP env vars, so an operator running the documented matrix has no way to know these tests exist or how to enable them.
+
+**Recommendation:** Add a "Live Galaxy Repository" section to `docs/GatewayTesting.md` documenting `MXGATEWAY_RUN_LIVE_GALAXY_TESTS=1`, `MXGATEWAY_LIVE_GALAXY_CONN`, the `ZB` database prerequisite, and the covered RPCs, mirroring the existing "Live MXAccess Smoke" section.
+
+**Resolution:** _(open)_
+
+### IntegrationTests-002
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Design-document adherence |
+| Location | `src/MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:13`, `src/MxGateway.Server/Configuration/LdapOptions.cs:27` |
+| Status | Open |
+
+**Description:** `DashboardLdapLiveTests` builds the authenticator with `new GatewayOptions()`, so it relies on `LdapOptions.RequiredGroup` defaulting to `GwAdmin` and asserts the `admin` user is a member of a `GwAdmin` LDAP group. `glauth.md` does not list `GwAdmin` as a provisioned group — it lists `admin` only in the five role groups and describes `GwAdmin` as a group to add "when reuse isn't enough." If GLAuth has only the documented baseline groups, `AuthenticateAsync_AdminInGwAdminGroup_Succeeds` fails (not skips) on any box where the env var is set. This is an undocumented hard prerequisite beyond "LDAP is up."
+
+**Recommendation:** Either document the required `GwAdmin` GLAuth provisioning step in `glauth.md` and `GatewayTesting.md`, or have the test set `RequiredGroup` to a baseline group `glauth.md` guarantees `admin` belongs to (e.g. `WriteOperate`).
+
+**Resolution:** _(open)_
+
+### IntegrationTests-003
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Correctness & logic bugs |
+| Location | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:89-97` |
+| Status | Open |
+
+**Description:** The test asserts only on the first `MxEvent` recorded by `RecordingServerStreamWriter`. A live MXAccess provider can deliver an initial state/quality event whose family or handles differ from the expected `OnDataChange` (e.g. a registration-state or bad-quality bootstrap event). Because `WaitForFirstMessageAsync` returns whatever arrives first, a genuine ordering/family defect could fail spuriously or leave later wrong events unverified.
+
+**Recommendation:** Filter for the first event with `Family == OnDataChange` (with a bounded retry/poll) or assert the full recorded sequence, so the test verifies the event the worker is supposed to emit.
+
+**Resolution:** _(open)_
+
+### IntegrationTests-004
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:108-111` |
+| Status | Open |
+
+**Description:** In the `finally` block, after `CloseSessionAsync`, the test does `await streamTask.WaitAsync(StreamShutdownTimeout)`. If closing the session does not promptly complete the stream (or `StreamEvents` itself faults), this throws `TimeoutException` from inside `finally`, which replaces/masks any original assertion failure from the `try` block. The diagnostic value of the real failure is lost.
+
+**Recommendation:** Wrap the `streamTask.WaitAsync` (and ideally `WaitForProcessesAsync`) in a try/catch that logs the cleanup exception via `output.WriteLine` instead of letting it propagate.
+
+**Resolution:** _(open)_
+
+### IntegrationTests-005
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Testing coverage |
+| Location | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs` |
+| Status | Open |
+
+**Description:** The only live MXAccess test covers the Register→AddItem→Advise→one-OnDataChange→Close happy path. CLAUDE.md stresses that MXAccess parity is the contract and calls out non-obvious behaviors (`WriteSecured` ordering, `OperationComplete` semantics, invalid-handle exceptions). None of `Write`, `WriteSecured`, `Unadvise`, `RemoveItem`, `Unregister`, `OperationComplete`, an invalid-handle command, or a worker-fault path is exercised against live COM — exactly the paths fake-worker tests cannot validate.
+
+**Recommendation:** Add live coverage for at least a `Write` round-trip and an invalid-handle command, plus a worker-fault/abnormal-exit scenario, even if behind additional opt-in env vars.
+
+**Resolution:** _(open)_
+
+### IntegrationTests-006
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Testing coverage |
+| Location | `src/MxGateway.IntegrationTests/DashboardLdapLiveTests.cs` |
+| Status | Open |
+
+**Description:** LDAP live coverage is two cases: admin succeeds, readonly is denied for missing group. There is no coverage of a wrong password for a valid user, an unknown username, or the LDAP-server-unreachable path — all of which `DashboardAuthenticator` has distinct branches for (the `LdapException` catch, the `candidate is null` branch). The negative test only proves group-membership denial, not credential rejection.
+
+**Recommendation:** Add a live test for `admin` with a wrong password asserting `Succeeded == false` and that the password is not leaked into `FailureMessage`, and a test for an unknown username.
+
+**Resolution:** _(open)_
+
+### IntegrationTests-007
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Concurrency & thread safety |
+| Location | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:20`, `src/MxGateway.IntegrationTests/Galaxy/GalaxyRepositoryLiveTests.cs:5`, `src/MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:9` |
+| Status | Open |
+
+**Description:** The live test classes contend for genuinely shared singletons — one MXAccess COM provider, one ZB SQL database, one GLAuth instance with a 3-fail/10-minute per-IP lockout. No `[Collection]` annotation or `DisableTestParallelization` is declared, so xUnit's default cross-class parallelism could run the Galaxy tests concurrently or interleave an LDAP failure burst that trips the GLAuth lockout.
+
+**Recommendation:** Place the live test classes in a shared `[Collection]`, or set `[assembly: CollectionBehavior(DisableTestParallelization = true)]` for this opt-in project, so live external resources are accessed serially.
+
+**Resolution:** _(open)_
+
+### IntegrationTests-008
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `src/MxGateway.IntegrationTests/LiveLdapFactAttribute.cs`, `src/MxGateway.IntegrationTests/Galaxy/LiveGalaxyRepositoryFactAttribute.cs`, `src/MxGateway.IntegrationTests/LiveMxAccessFactAttribute.cs` |
+| Status | Open |
+
+**Description:** Three near-identical fact attributes each re-implement the same "compare env var to `1` with `StringComparison.Ordinal`, set `Skip` otherwise" pattern. `LiveMxAccessFactAttribute` delegates to `IntegrationTestEnvironment` while the other two inline the logic, so the project has two divergent styles for the same concern.
+
+**Recommendation:** Extract a shared helper (e.g. `IntegrationTestEnvironment.IsEnabled(string variableName)`) and have all three attributes call it.
+
+**Resolution:** _(open)_
+
+### IntegrationTests-009
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:372-375` |
+| Status | Open |
+
+**Description:** `TestServerCallContext` is XML-documented as a "Mock server call context," but it is a hand-written stub/fake with no mocking framework and no verification behavior. Per the style guides (accurate naming; explain why not what), calling it a mock misleads readers who may expect verifiable interactions.
+
+**Recommendation:** Reword the summary to "test stub" / "minimal `ServerCallContext` implementation for in-process gRPC calls."
+
+**Resolution:** _(open)_
+
+### IntegrationTests-010
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:366-369` |
+| Status | Open |
+
+**Description:** `WaitForFirstMessageAsync` accepts only a `timeout` and never observes a `CancellationToken`. There is no per-test cancellation propagation, so if the gateway/worker hangs without writing an event the test relies solely on the 15s `WaitAsync` timeout and gives no contextual diagnostics. Combined with IntegrationTests-004, a hung live worker produces a bare `TimeoutException`.
+
+**Recommendation:** Accept a `CancellationToken` (linked to `TestServerCallContext`'s token), pass it to `firstMessage.Task.WaitAsync(timeout, token)`, and on timeout emit the recorded `Messages` count via `output.WriteLine` before throwing.
+
+**Resolution:** _(open)_

code-reviews/README.md

@@ -0,0 +1,165 @@
+# Code Reviews
+
+<!-- GENERATED FILE - do not edit by hand. Regenerate with: python code-reviews/regen-readme.py -->
+
+Cross-module code review index for the `mxaccessgw` codebase. The review process is defined in [../REVIEW-PROCESS.md](../REVIEW-PROCESS.md).
+
+Each module's `findings.md` is the source of truth; this file is generated from them by `regen-readme.py` and must not be edited by hand.
+
+## Module status
+
+| Module | Reviewer | Date | Commit | Status | Open | Total |
+|---|---|---|---|---|---|---|
+| [Client.Dotnet](Client.Dotnet/findings.md) | Claude Code | 2026-05-18 | `3cc53a8` | Reviewed | 8 | 8 |
+| [Client.Go](Client.Go/findings.md) | Claude Code | 2026-05-18 | `3cc53a8` | Reviewed | 10 | 10 |
+| [Client.Java](Client.Java/findings.md) | Claude Code | 2026-05-18 | `3cc53a8` | Reviewed | 12 | 12 |
+| [Client.Python](Client.Python/findings.md) | Claude Code | 2026-05-18 | `3cc53a8` | Reviewed | 12 | 12 |
+| [Client.Rust](Client.Rust/findings.md) | Claude Code | 2026-05-18 | `3cc53a8` | Reviewed | 0 | 12 |
+| [Contracts](Contracts/findings.md) | Claude Code | 2026-05-18 | `6c64030` | Reviewed | 8 | 8 |
+| [IntegrationTests](IntegrationTests/findings.md) | Claude Code | 2026-05-18 | `6c64030` | Reviewed | 10 | 10 |
+| [Server](Server/findings.md) | Claude Code | 2026-05-18 | `6c64030` | Reviewed | 12 | 14 |
+| [Tests](Tests/findings.md) | Claude Code | 2026-05-18 | `6c64030` | Reviewed | 12 | 12 |
+| [Worker](Worker/findings.md) | Claude Code | 2026-05-18 | `6c64030` | Reviewed | 15 | 15 |
+| [Worker.Tests](Worker.Tests/findings.md) | Claude Code | 2026-05-18 | `6c64030` | Reviewed | 15 | 15 |
+
+## Pending findings
+
+Findings with status `Open` or `In Progress`, ordered by severity.
+
+| ID | Severity | Category | Location | Description |
+|---|---|---|---|---|
+| Client.Go-001 | High | Correctness & logic bugs | `clients/go/mxgateway/errors.go:88-93`, `clients/go/mxgateway/errors.go:117-128` | `MxAccessError.Unwrap` returns `e.Command` directly. `EnsureMxAccessSuccess` constructs `&MxAccessError{Reply: reply}` with `Command` left nil (the HRESULT / failing-`MxStatusProxy` path). When `Command` is a nil `*CommandError`, `Unwrap()… |
+| IntegrationTests-001 | High | Design-document adherence | `src/MxGateway.IntegrationTests/Galaxy/LiveGalaxyRepositoryFactAttribute.cs:7`, `src/MxGateway.IntegrationTests/Galaxy/GalaxyRepositoryLiveTests.cs` | The Galaxy Repository live test suite and its gating env var `MXGATEWAY_RUN_LIVE_GALAXY_TESTS` (plus connection-string override `MXGATEWAY_LIVE_GALAXY_CONN`) are completely absent from `docs/GatewayTesting.md`. CLAUDE.md mandates updating… |
+| IntegrationTests-002 | High | Design-document adherence | `src/MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:13`, `src/MxGateway.Server/Configuration/LdapOptions.cs:27` | `DashboardLdapLiveTests` builds the authenticator with `new GatewayOptions()`, so it relies on `LdapOptions.RequiredGroup` defaulting to `GwAdmin` and asserts the `admin` user is a member of a `GwAdmin` LDAP group. `glauth.md` does not lis… |
+| Tests-001 | High | Testing coverage | `src/MxGateway.Tests/Gateway/Grpc/MxAccessGatewayServiceTests.cs:483-489` | `FakeSessionManager.TryGetSession` unconditionally returns `true` and synthesizes a session for any id. As a result, `Invoke_WhenSessionMissing_ThrowsNotFound` (line 52) only passes because `InvokeException` is pre-seeded — it does not ver… |
+| Tests-002 | High | Security | `src/MxGateway.Tests/Gateway/Grpc/GalaxyRepositoryGrpcServiceTests.cs:198-210` | The Galaxy Repository RPCs browse a SQL Server database (`ZB`). Every test injects a `StubGalaxyHierarchyCache`, so actual SQL query construction, parameterization, and filter/glob translation are never exercised. No test demonstrates that… |
+| Worker-001 | High | Concurrency & thread safety | `src/MxGateway.Worker/MxAccess/WnWrapAlarmConsumer.cs:204-207` | When constructed with `pollIntervalMilliseconds > 0`, `Subscribe` starts a `System.Threading.Timer` whose `OnPoll` callback runs `PollOnce()` — which calls `wwAlarmConsumerClass.GetXmlCurrentAlarms2` — on a thread-pool thread. The wnwrap C… |
+| Worker-002 | High | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:545-549` | `RunHeartbeatLoopAsync` calls `await Task.Delay(_sessionOptions.HeartbeatInterval, ...)` before sending the first heartbeat. The gateway therefore receives no heartbeat for the first full interval (default 5s) after the worker reaches `Rea… |
+| Worker-003 | High | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:399-403`, `:416-419` | `ProcessCommandAsync` checks `_state` after `DispatchAsync` completes and silently `return`s without writing a `WorkerCommandReply` (or fault) when `_state` is not `Ready`/`ExecutingCommand`. `_state` is a plain field mutated from multiple… |
+| Worker.Tests-001 | High | Testing coverage | `src/MxGateway.Worker.Tests/Sta/` (no `StaMessagePumpTests.cs`) | `StaMessagePump` — whose entire reason for existing is pumping Windows messages so MXAccess COM event sink calls deliver onto the STA — has no direct unit test. `WaitForWorkOrMessages` (timeout conversion, the `MsgWaitForMultipleObjectsEx`… |
+| Worker.Tests-002 | High | Testing coverage | `src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs`, `src/MxGateway.Worker.Tests/MxAccess/MxAccessEventMapperTests.cs` | No test verifies that a COM event raised on the STA thread is converted to protobuf and lands in the `MxAccessEventQueue`. `MxAccessEventMapperTests` exercises the mapper directly with hand-built fakes, and `AlarmDispatcherTests` covers th… |
+| Client.Dotnet-001 | Medium | Error handling & resilience | `clients/dotnet/MxGateway.Client/GrpcMxGatewayClientTransport.cs:190-199`, `clients/dotnet/MxGateway.Client/GrpcGalaxyRepositoryClientTransport.cs:131-140` | `MapRpcException` only produces typed exceptions for `Unauthenticated` and `PermissionDenied`. Every other gRPC status — `NotFound`, `InvalidArgument`, `ResourceExhausted`, `FailedPrecondition`, `Unavailable`, `Internal` — collapses into t… |
+| Client.Dotnet-002 | Medium | Testing coverage | `clients/dotnet/MxGateway.Client.Tests/FakeGatewayTransport.cs:145-148`, `clients/dotnet/MxGateway.Client.Tests/MxGatewayClientSessionTests.cs:236-256` | The retry predicate `MxGatewayClientRetryPolicy.IsTransientGrpcFailure` handles two shapes: a raw `RpcException` and an `MxGatewayException { InnerException: RpcException }`. In production the transport always maps `RpcException` → `MxGate… |
+| Client.Dotnet-003 | Medium | Concurrency & thread safety | `clients/dotnet/MxGateway.Client/MxGatewaySession.cs:659-663`, `clients/dotnet/MxGateway.Client/MxGatewayClient.cs:230-240` | `DisposeAsync` calls `CloseAsync()` (no token) then unconditionally `_closeLock.Dispose()`. If another thread is concurrently awaiting `CloseAsync(token)` — legal, since the type exposes public async methods and no single-threaded contract… |
+| Client.Go-002 | Medium | Error handling & resilience | `clients/go/mxgateway/session.go:440-516` | For the `Events`/`EventsAfter` compatibility API (`cancelWhenResultBufferFull == true`), when the 16-slot `results` channel is full `sendEventResult` cancels and returns `false`; the goroutine returns and `close(results)` runs — the consum… |
+| Client.Go-003 | Medium | Correctness & logic bugs | `clients/go/cmd/mxgw-go/main.go:517-532` | `parseInt32List` calls `panic(err)` when an `item-handles` token fails to parse as an int32. The CLI is a documented user-facing tool; a typo like `-item-handles 1,foo` crashes the process with an unrecovered panic and stack trace instead… |
+| Client.Java-001 | Medium | Security | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewaySecrets.java:30-32` | `redactApiKey` preserves the leading and trailing four characters of the key. A gateway API key has the form `mxgw_<key-id>_<secret>`; the last four characters belong to the secret portion, so the "redacted" form leaks 4 characters of the… |
+| Client.Java-002 | Medium | Concurrency & thread safety | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxEventStream.java:31,66-92` | The `next` field is a plain (non-volatile) instance field, and `MxEventStream` exposes no thread-confinement guarantee. More concretely, a queue-overflow `offer()` and a `close()` `offer(END)` can interleave so the overflow exception is en… |
+| Client.Java-003 | Medium | mxaccessgw conventions | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:119-140` | `OpenSessionReply` carries `gateway_protocol_version` (proto field 8), and `MxGatewayClientVersion.GATEWAY_PROTOCOL_VERSION` exists so the client can reject incompatible generated-code inputs. The client never reads `reply.getGatewayProtoc… |
+| Client.Java-004 | Medium | Correctness & logic bugs | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewaySession.java:114-120,157-163,191-197` | `register`, `addItem`, and `addItem2` check `reply.hasRegister()`/`hasAddItem()` and otherwise fall back to `reply.getReturnValue().getInt32Value()`. If the gateway returns a reply with neither the typed payload nor a `return_value` set, t… |
+| Client.Java-005 | Medium | Error handling & resilience | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewaySession.java:92-105` | `close()` delegates to `closeRaw()`, which performs a network RPC. When `MxGatewaySession` is used in try-with-resources and the body throws, a failure inside `closeSession` (e.g. `WORKER_UNAVAILABLE`) throws from `close()` and replaces th… |
+| Client.Python-003 | Medium | Error handling & resilience | `clients/python/src/mxgateway/client.py:125-137,155-173` | `stream_events_raw` and `query_active_alarms` call the stub directly with a `timeout` kwarg when `stream_timeout` is set, with no `TypeError` fallback. `galaxy.py:watch_deploy_events` and `_unary` *do* have a fallback that strips `timeout`… |
+| Client.Python-005 | Medium | Performance & resource management | `clients/python/src/mxgateway/galaxy.py:117-140` | `discover_hierarchy` pages through the entire Galaxy object hierarchy and accumulates every `GalaxyObject` (each carrying its full attribute list) into a single in-memory `list` before returning. For a large Galaxy this is a very large all… |
+| Client.Python-009 | Medium | Testing coverage | `clients/python/tests/` | Several non-trivial public paths are untested: `Session.write2`/`add_item2` request construction; the bulk-size limit `_ensure_bulk_size`/`MAX_BULK_ITEMS` guard; the `None`-argument `TypeError` guards in bulk methods; the TLS `ca_file` rea… |
+| Contracts-002 | Medium | Error handling & resilience | `src/MxGateway.Contracts/Protos/mxaccess_gateway.proto:384-385`, `:95` | `MxCommandKind` includes `MX_COMMAND_KIND_ACKNOWLEDGE_ALARM_BY_NAME = 29` and `MxCommand.payload` carries `AcknowledgeAlarmByNameCommand acknowledge_alarm_by_name_command = 38`, but `MxCommandReply.payload` has only `acknowledge_alarm = 34… |
+| IntegrationTests-003 | Medium | Correctness & logic bugs | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:89-97` | The test asserts only on the first `MxEvent` recorded by `RecordingServerStreamWriter`. A live MXAccess provider can deliver an initial state/quality event whose family or handles differ from the expected `OnDataChange` (e.g. a registratio… |
+| IntegrationTests-004 | Medium | Error handling & resilience | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:108-111` | In the `finally` block, after `CloseSessionAsync`, the test does `await streamTask.WaitAsync(StreamShutdownTimeout)`. If closing the session does not promptly complete the stream (or `StreamEvents` itself faults), this throws `TimeoutExcep… |
+| IntegrationTests-005 | Medium | Testing coverage | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs` | The only live MXAccess test covers the Register→AddItem→Advise→one-OnDataChange→Close happy path. CLAUDE.md stresses that MXAccess parity is the contract and calls out non-obvious behaviors (`WriteSecured` ordering, `OperationComplete` sem… |
+| IntegrationTests-006 | Medium | Testing coverage | `src/MxGateway.IntegrationTests/DashboardLdapLiveTests.cs` | LDAP live coverage is two cases: admin succeeds, readonly is denied for missing group. There is no coverage of a wrong password for a valid user, an unknown username, or the LDAP-server-unreachable path — all of which `DashboardAuthenticat… |
+| Server-002 | Medium | Design-document adherence | `src/MxGateway.Server/Program.cs:24`, `src/MxGateway.Server/GatewayApplication.cs` | `gateway.md:583` and CLAUDE.md state the first version "terminates orphaned workers on startup." No code in MxGateway.Server enumerates or kills leftover `MxGateway.Worker.exe` processes at startup — a grep for `orphan`/`reattach`/`termina… |
+| Server-004 | Medium | Code organization & conventions | `src/MxGateway.Server/Security/Authentication/ApiKeyAdminCommandLineParser.cs:227-233`, `src/MxGateway.Server/Security/Authentication/ApiKeyAdminCliRunner.cs:53-77`, `src/MxGateway.Server/Dashboard/DashboardApiKeyManagementService.cs:21-67` | `ParseScopes` accepts any comma-separated strings and `CreateKeyAsync` persists them verbatim; neither the CLI nor the dashboard create path validates scopes against `GatewayScopes`. A typo or non-canonical name (e.g. CLAUDE.md's example `… |
+| Server-005 | Medium | Error handling & resilience | `src/MxGateway.Server/Galaxy/GalaxyHierarchyRefreshService.cs:22-28`, `src/MxGateway.Server/Galaxy/GalaxyHierarchyCache.cs:184` | `GalaxyHierarchyCache.RefreshCoreAsync` only catches `SqlException` and `InvalidOperationException`. The initial `cache.RefreshAsync` call in `GalaxyHierarchyRefreshService.ExecuteAsync` is wrapped only for `OperationCanceledException`. A… |
+| Server-006 | Medium | Correctness & logic bugs | `src/MxGateway.Server/Sessions/SessionManager.cs:84-114` | In `OpenSessionAsync`, `_metrics.SessionOpened()` (line 89) increments the `_openSessions` gauge before `TryAutoSubscribeAlarmsAsync` runs. If auto-subscribe throws (which it does when `Alarms.RequireSubscribeOnOpen` is true and the worker… |
+| Tests-003 | Medium | Performance & resource management | `src/MxGateway.Tests/Security/Authentication/SqliteAuthStoreTests.cs:170-176`, `src/MxGateway.Tests/Security/Authentication/ApiKeyAdminCliRunnerTests.cs:252-258` | `CreateTempDatabasePath` creates a fresh directory under `%TEMP%\mxgateway-auth-tests\<guid>` (and `...-cli-tests`) for every test but nothing ever deletes it. `WorkerProcessLauncherTests.TestDirectory` correctly implements `IDisposable` a… |
+| Tests-004 | Medium | Testing coverage | `src/MxGateway.Tests/Security/Authorization/GatewayGrpcAuthorizationInterceptorTests.cs` | The authorization interceptor and `MxAccessGatewayService` are each tested in isolation, but no test composes the interceptor in front of the real service to confirm scope enforcement gates real RPCs end-to-end. A wiring mistake — intercep… |
+| Tests-005 | Medium | Testing coverage | `src/MxGateway.Tests/Gateway/Grpc/EventStreamServiceTests.cs:239-261`, `src/MxGateway.Tests/Gateway/Sessions/SessionManagerTests.cs` | Worker-crash handling is only tested as a clean terminal exception from `ReadEventsAsync` or a pre-set `ShutdownException`. There is no test for a worker that faults mid-command — an `InvokeAsync` in flight when the pipe/worker dies — whic… |
+| Tests-006 | Medium | Concurrency & thread safety | `src/MxGateway.Tests/Gateway/Workers/WorkerClientTests.cs:76`, `src/MxGateway.Tests/Gateway/Workers/FakeWorkerHarnessTests.cs:122` | Several tests rely on fixed `Task.Delay` values: `WorkerClientTests.InvokeAsync_WithLateReply…` waits a hard-coded 50 ms after writing a late reply before issuing the second command, and the heartbeat tests use a 20 ms delay to make timest… |
+| Worker-004 | Medium | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:565-588` | After `ReportWatchdogFaultIfNeededAsync` sends an `StaHung` fault, the heartbeat loop continues sending normal heartbeats with `State` derived from `_state`, which the watchdog path never sets to `Faulted`. The heartbeat then keeps reporti… |
+| Worker-005 | Medium | Error handling & resilience | `src/MxGateway.Worker/MxAccess/WnWrapAlarmConsumer.cs:297-313` | `OnPoll` catches every exception from `PollOnce()` and discards it (`_ = ex;`). The production poll path (`MxAccessStaSession.RunAlarmPollLoopAsync` → `AlarmCommandHandler.PollOnce` → `AlarmDispatcher.PollOnce` → `consumer.PollOnce()`) has… |
+| Worker-006 | Medium | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:117-124`, `src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs:386-491` | `RunAsync`'s `finally` calls `_runtimeSession?.Dispose()` unless `_shutdownTimedOut`. On the normal path `ShutdownGracefullyAsync` already disposed the STA runtime, so re-entering `Dispose()` is a harmless no-op only because `ShutdownGrace… |
+| Worker-007 | Medium | mxaccessgw conventions | `src/MxGateway.Worker/MxAccess/MxAccessComServer.cs:130-150` | `Invoke` uses late-bound `Type.InvokeMember` reflection as a fallback when the COM object does not cast to `ILMXProxyServer*`. In production the object is always `LMXProxyServerClass`, so the reflection path exists only for test doubles —… |
+| Worker-008 | Medium | Concurrency & thread safety | `src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs:205-249`, `:429-447` | `RunAlarmPollLoopAsync` correctly marshals `handler.PollOnce()` onto the STA via `staRuntime.InvokeAsync`, and the cancel/await/dispose ordering in `ShutdownGracefullyAsync` is sound. However, nothing enforces that the `consumerFactory` an… |
+| Worker.Tests-003 | Medium | Concurrency & thread safety | `src/MxGateway.Worker.Tests/Sta/StaRuntimeTests.cs:46-48` | `InvokeAsync_WakesIdlePumpForQueuedCommand` asserts `stopwatch.Elapsed < TimeSpan.FromSeconds(2)` — a wall-clock assertion that on a loaded CI agent can exceed 2s, producing a false failure. The test also does not actually prove the wake e… |
+| Worker.Tests-004 | Medium | Concurrency & thread safety | `src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs:281-329` | `StartAsync_WithAlarmCommandHandlerFactory_PollOnceCalledViaSta` and `Dispose_StopsAlarmPollLoop` use poll-until loops, and `Dispose_StopsAlarmPollLoop` additionally does `await Task.Delay(1000)` then asserts `PollCount` is unchanged. The… |
+| Worker.Tests-005 | Medium | Performance & resource management | `src/MxGateway.Worker.Tests/Ipc/WorkerFrameProtocolTests.cs:20-31,103-105`, `src/MxGateway.Worker.Tests/Ipc/WorkerPipeSessionTests.cs:28-31` | `MemoryStream` instances are created and never disposed across the frame-protocol and pipe-session tests (`MemoryStream stream = new();` with no `using`). Disposal is cheap so impact is low, but it is inconsistent with the rest of the suit… |
+| Worker.Tests-006 | Medium | Performance & resource management | `src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs:282,305,315,323` | `Dispose_StopsAlarmPollLoop` constructs `MxAccessStaSession session` without `using` (unlike every sibling test) and relies on an explicit `session.Dispose()`. If an assertion between `StartAsync` and `Dispose()` throws, the session — its… |
+| Worker.Tests-007 | Medium | Design-document adherence | `docs/WorkerFrameProtocol.md:38-49` | `docs/WorkerFrameProtocol.md` instructs running `dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter WorkerFrameProtocolTests` and states the frame protocol "is part of `MxGateway.Server`". The frame protocol actually lives in… |
+| Client.Dotnet-004 | Low | Error handling & resilience | `clients/dotnet/MxGateway.Client/MxGatewayClient.cs:283-294`, `clients/dotnet/MxGateway.Client/GalaxyRepositoryClient.cs:392-403` | `ExecuteSafeUnaryAsync` wraps the whole Polly retry pipeline in a single linked CTS cancelled after `Options.DefaultCallTimeout`, while `CreateCallOptions` also stamps each individual call with a `DefaultCallTimeout` gRPC deadline. The ret… |
+| Client.Dotnet-005 | Low | Correctness & logic bugs | `clients/dotnet/MxGateway.Client/MxGatewaySession.cs:82,124,175` | `RegisterAsync`/`AddItemAsync`/`AddItem2Async` return `reply.<Typed>?.ServerHandle ?? reply.ReturnValue.Int32Value`. After `EnsureMxAccessSuccess()` passes, a missing typed payload silently falls back to `ReturnValue.Int32Value`, which for… |
+| Client.Dotnet-006 | Low | Code organization & conventions | `clients/dotnet/MxGateway.Client/MxGatewayClientOptions.cs:50`, `clients/dotnet/MxGateway.Client/MxGatewayClientContractInfo.cs:10-14` | `MxGatewayClientOptions.MaxGrpcMessageBytes` and the two `const`s in `MxGatewayClientContractInfo` are public members with no XML doc comments, inconsistent with every other public member in the assembly and with the repo's documented C# s… |
+| Client.Dotnet-007 | Low | Documentation & comments | `clients/dotnet/MxGateway.Client/MxGatewayClient.cs:185-192` | The `AcknowledgeAlarmAsync` XML comment states the gateway authenticates against an `invoke:alarm-ack` scope, but `CLAUDE.md` documents the scope set without any `invoke:alarm-ack` sub-scope. The comment may describe an intended finer-grai… |
+| Client.Dotnet-008 | Low | Correctness & logic bugs | `clients/dotnet/MxGateway.Client.Cli/MxGatewayCliSecretRedactor.cs:9-17` | The CLI redactor only removes the API key string when it was supplied via `--api-key`; `RunCoreAsync` passes `arguments.GetOptional("api-key")` to `Redact`. When the key comes from an environment variable (`--api-key-env`, the documented d… |
+| Client.Go-004 | Low | mxaccessgw conventions | `clients/go/mxgateway/alarms_test.go:153-154`, `clients/go/mxgateway/galaxy_test.go:58-59` | `gofmt -l` flags `alarms_test.go` and `galaxy_test.go` for misaligned struct-literal field padding. The Go client README lists `gofmt` as part of the workflow and the repo enforces style; unformatted committed code breaks `gofmt`-gated che… |
+| Client.Go-005 | Low | Design-document adherence | `clients/go/mxgateway/client.go:64,68`, `clients/go/mxgateway/galaxy.go:83,87` | The client uses `grpc.DialContext` with `grpc.WithBlock()`. In current grpc-go both are deprecated in favour of `grpc.NewClient` (lazy connection). `WithBlock` also changes failure semantics: a transient gateway-unavailable at dial time be… |
+| Client.Go-006 | Low | Error handling & resilience | `clients/go/mxgateway/errors.go:9-130` | `docs/ClientLibrariesDesign.md` recommends a high-level error taxonomy (`TransportError`, `AuthenticationError`, `TimeoutError`, etc.). The Go client collapses all transport/gRPC failures into a single `GatewayError` with no way to classif… |
+| Client.Go-007 | Low | Correctness & logic bugs | `clients/go/mxgateway/session.go:526-532` | `newCorrelationID` returns an empty string when `crypto/rand.Read` fails, silently producing an `MxCommandRequest` with no correlation id. `rand.Read` failure is rare, but the failure mode (untraceable command, no error surfaced) is worse… |
+| Client.Go-008 | Low | Testing coverage | `clients/go/mxgateway/` (test files) | Several critical paths are untested: TLS credential resolution in `resolveTransportCredentials` (only the `Plaintext` path is exercised); the `callContext` deadline-shortening logic (`client.go:198-204`) including the negative-timeout disa… |
+| Client.Go-009 | Low | Code organization & conventions | `clients/go/mxgateway/galaxy.go:60-93,241-256`, `clients/go/mxgateway/client.go:41-74,190-205` | `DialGalaxy`/`Dial` and `GalaxyClient.callContext`/`Client.callContext` are near-identical duplicates (dial-context setup, credential resolution, dial-option assembly, deadline arithmetic). A fix to one (e.g. the Client.Go-005 dial migrati… |
+| Client.Go-010 | Low | Documentation & comments | `clients/go/mxgateway/client.go:39-40` | The `Dial` doc comment states it configures "blocking dial cancellation from ctx." This describes the deprecated `WithBlock` behaviour; once Client.Go-005 is addressed the comment is misleading about how connection establishment and cancel… |
+| Client.Java-006 | Low | Performance & resource management | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:323-328`, `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/GalaxyRepositoryClient.java:279-284` | `close()` (the `AutoCloseable` method invoked by try-with-resources) calls only `ownedChannel.shutdown()` and returns immediately without awaiting termination. In-flight calls and Netty event-loop threads may still be running when the call… |
+| Client.Java-007 | Low | Testing coverage | `clients/java/mxgateway-client/src/test/java/com/dohertylan/mxgateway/client/` | The alarm surface — `acknowledgeAlarm`/`acknowledgeAlarmAsync`/`queryActiveAlarms` and `MxGatewayActiveAlarmsSubscription` — has zero test coverage. TLS channel construction, the async `streamEventsAsync` path, `MxGatewayEventSubscription`… |
+| Client.Java-008 | Low | Error handling & resilience | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:298-304` | `acknowledgeAlarmAsync` and `openSessionAsync` apply `ensureProtocolSuccess` inside `thenApply`. If that validator throws a non-`MxGatewayException` `RuntimeException` it is wrapped by `CompletionException` with no `fromGrpc` normalisation… |
+| Client.Java-009 | Low | Code organization & conventions | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/GalaxyRepositoryClient.java:310-391`, `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:346-413` | `createChannel`, `withDeadline`, `withStreamDeadline`, and `toCompletable` are duplicated nearly verbatim across `MxGatewayClient` and `GalaxyRepositoryClient` (~80 lines). A fix to one will not propagate to the other. |
+| Client.Java-010 | Low | Documentation & comments | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:269-272`, `clients/java/README.md:76` | The `acknowledgeAlarm` Javadoc states the gateway authenticates against an `invoke:alarm-ack` scope, and the README states the Galaxy Repository requires a `metadata:read` scope. CLAUDE.md's documented scope set names neither — the Javadoc… |
+| Client.Java-011 | Low | Performance & resource management | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxEventStream.java:37-63` | The event stream relies on default gRPC auto-inbound flow control: the async stub auto-requests messages, so the server can push faster than the 16-element bounded queue drains. A momentarily slow consumer triggers queue overflow and an im… |
+| Client.Java-012 | Low | Correctness & logic bugs | `clients/java/mxgateway-cli/src/main/java/com/dohertylan/mxgateway/cli/MxGatewayCli.java:667-674` | `CommonOptions.resolved()` mutates `this` (`resolvedApiKey`, `resolvedTimeout`) and returns `this`, but `toClientOptions()` and `redactedJsonMap()` read those mutated fields. If `redactedJsonMap()` is ever called before `resolved()`, it si… |
+| Client.Python-001 | Low | Documentation & comments | `clients/python/pyproject.toml:8,25`, `clients/python/src/mxgateway_cli/commands.py:25` | The package `description` in `pyproject.toml` still says "Async Python client *scaffold*" even though the client is fully implemented. Stale "scaffold" wording misrepresents maturity to anyone reading PyPI metadata. (The `mxgw-py` console-… |
+| Client.Python-002 | Low | Code organization & conventions | `clients/python/src/mxgateway/__init__.py:27` | `MxGatewayCommandError` is imported into `__init__.py` and is a documented public exception, but it is missing from `__all__`. It is the parent of `MxAccessError` and a meaningful catch target, so omitting it from the public surface is inc… |
+| Client.Python-004 | Low | Correctness & logic bugs | `clients/python/src/mxgateway_cli/commands.py:386,402-404` | In `_smoke`, the local variable `closed` is set to `False` and never reassigned; the `finally` block's `if not closed:` is therefore always true. This is dead/misleading code suggesting a removed early-close path. |
+| Client.Python-006 | Low | Concurrency & thread safety | `clients/python/src/mxgateway/client.py:74-82`, `clients/python/src/mxgateway/galaxy.py:85-93`, `clients/python/src/mxgateway/session.py:38-55` | `close()` on the clients and `Session.close()` use a plain `self._closed` check-then-set with an `await` between, with no lock. If two coroutines call `close()` concurrently both can pass the guard before either sets it, causing a double `… |
+| Client.Python-007 | Low | Error handling & resilience | `clients/python/src/mxgateway/client.py:204-213` | `_canceling_iterator` (gateway event stream) does not catch `asyncio.CancelledError` to invoke `call.cancel()` explicitly — it relies on the `finally` block. `galaxy.py:_canceling_iterator` *does* explicitly catch `CancelledError`, cancel,… |
+| Client.Python-008 | Low | Correctness & logic bugs | `clients/python/src/mxgateway/values.py:62-67,83-88` | `to_mx_value` maps any Python `float` to `VT_R8`/`MX_DATA_TYPE_DOUBLE` with no handling for `nan`/`inf`, which are serialised and forwarded to MXAccess which may reject or mis-handle them. `bytes` is mapped to `VT_RECORD`/`MX_DATA_TYPE_UNK… |
+| Client.Python-010 | Low | Code organization & conventions | `clients/python/src/mxgateway/session.py:404`, `clients/python/src/mxgateway_cli/commands.py:422-425` | `session.py` ends with a module-level late import `from .client import GatewayClient # noqa: E402` purely to satisfy a string type hint, and `commands.py:_session` does a function-local import. Both work around a circular dependency that `… |
+| Client.Python-011 | Low | Error handling & resilience | `clients/python/src/mxgateway/errors.py:122-148` | `ensure_mxaccess_success` raises `MxAccessError` if any `mx_status.success == 0`. This treats `success == 0` as the failure sentinel, but `0` is also the proto3 scalar default for an unset `MxStatusProxy`. If the gateway ever returns a rep… |
+| Client.Python-012 | Low | mxaccessgw conventions | `clients/python/src/mxgateway/client.py:84-108`, `clients/python/src/mxgateway/session.py:57-77` | `Session.invoke_raw` does not run `ensure_mxaccess_success` while `Session.invoke` does, so a caller using `invoke_raw` for parity tests gets a reply where an MXAccess HRESULT failure is silently embedded with no exception. This is by desi… |
+| Contracts-001 | Low | Design-document adherence | `docs/Grpc.md:13` (and `:3`, `:32`, `:39`) | `mxaccess_gateway.proto` now declares six RPCs on `MxAccessGateway` (`OpenSession`, `CloseSession`, `Invoke`, `StreamEvents`, `AcknowledgeAlarm`, `QueryActiveAlarms`). `docs/Grpc.md` still describes "the four `MxAccessGateway` RPCs" in its… |
+| Contracts-003 | Low | Code organization & conventions | `src/MxGateway.Contracts/MxGateway.Contracts.csproj:10` | The `<Protobuf>` item for `mxaccess_worker.proto` omits `ProtoRoot="Protos"`, while the items for `mxaccess_gateway.proto` (line 9) and `galaxy_repository.proto` (line 11) both set it. `mxaccess_worker.proto` does `import "mxaccess_gateway… |
+| Contracts-004 | Low | Documentation & comments | `src/MxGateway.Contracts/GatewayContractInfo.cs:3-6` | The XML summary says the class exposes version metadata "before generated protobuf contracts are introduced." Generated protobuf contracts have long been introduced and are consumed across the solution. The comment is stale; the class now… |
+| Contracts-005 | Low | mxaccessgw conventions | `src/MxGateway.Contracts/Protos/mxaccess_gateway.proto`, `src/MxGateway.Contracts/Protos/mxaccess_worker.proto` | The ProtobufStyleGuide mandates reserving removed field numbers / enum values. Evolution to date has been purely additive, so this is not a current violation — but none of the `.proto` files contain any `reserved` declarations, leaving no… |
+| Contracts-006 | Low | Correctness & logic bugs | `src/MxGateway.Contracts/Protos/mxaccess_gateway.proto:647` | `MxStatusProxy.success` is declared `int32 success = 1` with no comment. The name reads like a boolean flag but the type is a 32-bit integer (mirroring MXAccess `MXSTATUS_PROXY`, which stores a numeric success/HResult-like value). Without… |
+| Contracts-007 | Low | Testing coverage | `src/MxGateway.Tests/Contracts/ProtobufContractRoundTripTests.cs` | `ProtobufContractRoundTripTests` covers gateway command/reply/event, alarm transition, alarm ack request/reply, active-alarm snapshot, and the worker envelope. It has no coverage for: (a) any `galaxy_repository.proto` message (`DiscoverHie… |
+| Contracts-008 | Low | Design-document adherence | `src/MxGateway.Contracts/Protos/mxaccess_gateway.proto:451-459`, `:627-636` | The worker-side `AcknowledgeAlarmReplyPayload` carries the alarm-ack outcome as `int32 native_status`, while the public `AcknowledgeAlarmReply` carries it as `MxStatusProxy status` plus `optional int32 hresult`. The comment explains the wo… |
+| IntegrationTests-007 | Low | Concurrency & thread safety | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:20`, `src/MxGateway.IntegrationTests/Galaxy/GalaxyRepositoryLiveTests.cs:5`, `src/MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:9` | The live test classes contend for genuinely shared singletons — one MXAccess COM provider, one ZB SQL database, one GLAuth instance with a 3-fail/10-minute per-IP lockout. No `[Collection]` annotation or `DisableTestParallelization` is dec… |
+| IntegrationTests-008 | Low | Code organization & conventions | `src/MxGateway.IntegrationTests/LiveLdapFactAttribute.cs`, `src/MxGateway.IntegrationTests/Galaxy/LiveGalaxyRepositoryFactAttribute.cs`, `src/MxGateway.IntegrationTests/LiveMxAccessFactAttribute.cs` | Three near-identical fact attributes each re-implement the same "compare env var to `1` with `StringComparison.Ordinal`, set `Skip` otherwise" pattern. `LiveMxAccessFactAttribute` delegates to `IntegrationTestEnvironment` while the other t… |
+| IntegrationTests-009 | Low | Documentation & comments | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:372-375` | `TestServerCallContext` is XML-documented as a "Mock server call context," but it is a hand-written stub/fake with no mocking framework and no verification behavior. Per the style guides (accurate naming; explain why not what), calling it… |
+| IntegrationTests-010 | Low | Correctness & logic bugs | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:366-369` | `WaitForFirstMessageAsync` accepts only a `timeout` and never observes a `CancellationToken`. There is no per-test cancellation propagation, so if the gateway/worker hangs without writing an event the test relies solely on the 15s `WaitAsy… |
+| Server-007 | Low | Performance & resource management | `src/MxGateway.Server/Galaxy/GalaxyHierarchyProjector.cs:55-70` | `Project` always iterates the full `entry.Index.ObjectViews` collection and re-applies all filters to skip `offset` matched items before collecting a page. Paging through a large Galaxy hierarchy is therefore O(total) per page and O(total²… |
+| Server-008 | Low | Performance & resource management | `src/MxGateway.Server/Grpc/GalaxyRepositoryGrpcService.cs:111-134,160-189` | `WatchDeployEvents` calls `ResolveBrowseSubtrees()` on every streamed event, and `MapDeployEvent` re-runs `GalaxyHierarchyProjector.Project` over the entire cached hierarchy (and `Sum`s attribute counts) for every event of every constraine… |
+| Server-009 | Low | Error handling & resilience | `src/MxGateway.Server/Security/Authentication/AuthSqliteConnectionFactory.cs:15-32` | Each auth-store operation opens a fresh `SqliteConnection` with no busy timeout, no WAL journal mode, and default journaling. `MarkKeyUsedAsync` runs on every authenticated request and `SqliteApiKeyAuditStore` appends on every denial; unde… |
+| Server-010 | Low | Security | `src/MxGateway.Server/Security/Authentication/SqliteApiKeyAdminStore.cs:91-114`, `src/MxGateway.Server/Dashboard/Components/Pages/ApiKeysPage.razor:168-172` | `RotateAsync` sets `revoked_utc = NULL`, so rotating a previously revoked key silently reactivates it. This is documented intentional behavior in `docs/Authentication.md:167`, but the dashboard renders the "Rotate" button unconditionally —… |
+| Server-011 | Low | Code organization & conventions | `src/MxGateway.Server/Sessions/WorkerAlarmRpcDispatcher.cs:1-46` | `WorkerAlarmRpcDispatcher` deviates from the module's conventions: it fully-qualifies `System.Guid`, `System.ArgumentNullException`, and `System.Threading` types inline instead of relying on `using` directives, and uses an explicit constru… |
+| Server-012 | Low | Documentation & comments | `CLAUDE.md` (Authentication section and `apikey create` example) | CLAUDE.md describes scopes as `session`, `invoke`, `event`, `metadata`, `admin` and shows `apikey create --scopes session,invoke,event,metadata,admin`. The actual canonical scope strings (used by `GatewayScopes`, `GatewayGrpcScopeResolver`… |
+| Server-013 | Low | Testing coverage | `src/MxGateway.Tests/Gateway/Dashboard/DashboardAuthorizationHandlerTests.cs`, `src/MxGateway.Tests/Gateway/GatewayApplicationTests.cs` | `DashboardAuthorizationHandler` is unit-tested in isolation, but no test exercises the dashboard routes end-to-end to confirm the policy is actually enforced — which is why Server-001 (policy registered but never wired) went uncaught. Ther… |
+| Server-014 | Low | Documentation & comments | `src/MxGateway.Server/Grpc/MxAccessGatewayService.cs:162-171,191-198,206-214,229-237` | The XML `<remarks>` and inline comments on `AcknowledgeAlarm` and `QueryActiveAlarms` describe the alarm path as not yet wired and say `NotWiredAlarmRpcDispatcher` is the default ("Clients calling this method today receive an OK reply with… |
+| Tests-007 | Low | Code organization & conventions | `src/MxGateway.Tests/Gateway/Grpc/MxAccessGatewayServiceTests.cs:682`, `src/MxGateway.Tests/Gateway/Grpc/GalaxyRepositoryGrpcServiceTests.cs:324`, `src/MxGateway.Tests/Gateway/GatewayEndToEndFakeWorkerSmokeTests.cs:460`, `src/MxGateway.Tests/Security/Authorization/GatewayGrpcAuthorizationInterceptorTests.cs:233` | A near-identical `TestServerCallContext` implementation is copy-pasted into at least four test files (and `AllowAllConstraintEnforcer` / `TestServerStreamWriter` / `RecordingStreamWriter` into several). Duplication risks the copies driftin… |
+| Tests-008 | Low | mxaccessgw conventions | `src/MxGateway.Tests/Gateway/Sessions/WorkerAlarmRpcDispatcherTests.cs:1-9`, `src/MxGateway.Tests/Gateway/Sessions/NotWiredAlarmRpcDispatcherTests.cs:1-3`, `src/MxGateway.Tests/Gateway/Sessions/SessionManagerAlarmAutoSubscribeTests.cs:1` | The alarm test files diverge from the project's C# style and the rest of the suite: snake_case test method names instead of the PascalCase `Method_Condition_Result` pattern; redundant explicit `using System;`/`System.Threading;` imports de… |
+| Tests-009 | Low | Documentation & comments | `src/MxGateway.Tests/Gateway/Sessions/SessionManagerTests.cs:36-37,99,365` | Several XML `<summary>` comments are copy-paste mismatches: the comment above `OpenSessionAsync_SetsInitialDefaultLease` describes correlation-ID generation; the comment above `GatewaySessionSubscribeBulkAsync_ForwardsOneBulkCommand…` desc… |
+| Tests-010 | Low | Security | `src/MxGateway.Tests/Gateway/Dashboard/DashboardAuthorizationHandlerTests.cs:26-36` | The anonymous-localhost bypass is tested only for the success case (`allowAnonymousLocalhost: true` + loopback succeeds) and the remote-unauthenticated denial. There is no test for the security-critical negatives: anonymous + loopback when… |
+| Tests-011 | Low | Correctness & logic bugs | `src/MxGateway.Tests/Gateway/GatewayEndToEndFakeWorkerSmokeTests.cs:233-301` | `GatewayEndToEndFakeWorkerSmokeTests` correctly stores and awaits `launcher.WorkerTask`, but `SessionWorkerClientFactoryFakeWorkerTests` uses `_ = RunWorkerAsync(...)` with no stored task (lines 152, 184, 220). An unhandled exception in th… |
+| Tests-012 | Low | Concurrency & thread safety | `src/MxGateway.Tests/Gateway/Workers/Fakes/FakeWorkerHarness.cs:62`, `src/MxGateway.Tests/Gateway/Workers/WorkerClientTests.cs:472` | Pipe names are uniquified per test with a GUID (good), but xUnit runs test classes in parallel by default and there is no `xunit.runner.json` or collection configuration. Tests that build a full `WebApplication` bind ephemeral ports (`--ur… |
+| Worker-009 | Low | Performance & resource management | `src/MxGateway.Worker/Ipc/WorkerFrameReader.cs:31,49`, `src/MxGateway.Worker/Ipc/WorkerFrameWriter.cs:57-58` | Every frame read allocates a fresh 4-byte length buffer and a payload `byte[]`; every write allocates `ToByteArray()` plus a 4-byte prefix. On the hot event-drain path (batches of up to 128 `WorkerEvent` frames every 25 ms) this produces s… |
+| Worker-010 | Low | Correctness & logic bugs | `src/MxGateway.Worker/Conversion/VariantConverter.cs:204-226` | `ConvertInt64Scalar` is reached for `TypeCode.UInt32` and `TypeCode.Int64`. For a `uint` with `expectedDataType == MxDataType.Time`, the value is treated as a Windows `FILETIME` via `DateTime.FromFileTimeUtc(longValue)`; a 32-bit FILETIME… |
+| Worker-011 | Low | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeClient.cs:169-171` | `retryAttempts` is computed as `(connectTimeout / min(connectTimeout, attemptTimeout)) - 1`. With defaults (30000 / 2000) this yields 14 retries, but each retry also incurs Polly exponential backoff. The overall `connectDeadline` (`CancelA… |
+| Worker-012 | Low | Documentation & comments | `src/MxGateway.Worker/MxAccess/MxAccessAlarmEventSink.cs:44-55`, `src/MxGateway.Worker/MxAccess/WnWrapAlarmConsumer.cs:38-43`, `src/MxGateway.Worker/MxAccess/MxAccessEventMapper.cs:106-112` | Multiple comments describe the alarm path as not-yet-wired future work ("PR A.2 — COM-side subscription scaffold … the worker advertises no alarm subscription", "the worker bootstrap will gain a thin 'run-on-STA' wrapper as part of A.3").… |
+| Worker-013 | Low | Testing coverage | `src/MxGateway.Worker/Sta/StaMessagePump.cs` | `StaMessagePump` — the heart of COM event delivery (`MsgWaitForMultipleObjectsEx` + `PeekMessage`/`DispatchMessage`) — has no direct unit tests. `StaRuntimeTests` exercises it indirectly for command wake-up but never verifies that a posted… |
+| Worker-014 | Low | Code organization & conventions | `src/MxGateway.Worker/MxAccess/AlarmCommandHandler.cs:33`, `:202` | The file declares two public types — the `AlarmCommandHandler` class and the `IAlarmCommandHandler` interface. The C# style guide and the rest of the module follow one-public-type-per-file (e.g. interfaces in their own `I*.cs` files like `… |
+| Worker-015 | Low | Correctness & logic bugs | `src/MxGateway.Worker/MxAccess/MxAccessEventQueue.cs:115-145` | On overflow, `Enqueue` records the overflow fault and throws `MxAccessEventQueueOverflowException`; `MxAccessBaseEventSink.EnqueueEvent` catches it and calls `RecordFault` again. `RecordFault` is a no-op when a fault already exists, so the… |
+| Worker.Tests-008 | Low | Documentation & comments | `src/MxGateway.Worker.Tests/Conversion/VariantConverterTests.cs:175-182` | `Redactor_WithCredentialBearingValueFields_RedactsBeforeLogging` lives in `VariantConverterTests` but asserts on `WorkerLogRedactor.RedactValue`, which has nothing to do with `VariantConverter`. It is also a near-duplicate of coverage in `… |
+| Worker.Tests-009 | Low | Code organization & conventions | `src/MxGateway.Worker.Tests/MxAccess/AlarmCommandHandlerTests.cs`, `AlarmDispatcherTests.cs`, `AlarmCommandExecutorTests.cs`, `AlarmRecordTransitionMapperTests.cs`, `WnWrapAlarmConsumerXmlTests.cs` | The alarm-related test files use `snake_case` method names while the rest of the project uses the `Method_State_Result` PascalCase convention. `docs/style-guides/CSharpStyleGuide.md` and the surrounding code establish PascalCase as the pro… |
+| Worker.Tests-010 | Low | Correctness & logic bugs | `src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs:230-258` | `StartAsync_WithoutAlarmCommandHandlerFactory_SubscribeAlarmsReturnsInvalidRequest` asserts `Assert.Contains("alarm", reply.DiagnosticMessage, StringComparison.OrdinalIgnoreCase)`. The XML doc claims it verifies the diagnostic says "alarm… |
+| Worker.Tests-011 | Low | Documentation & comments | `src/MxGateway.Worker.Tests/Sta/StaCommandDispatcherTests.cs:92-112` | `DispatchAsync_WhenCanceledAfterExecutionStarts_StillReturnsLateReply` is named and documented as if it proves cancellation arrived after execution began. The test does `Started.Wait(...)` then `cancellation.Cancel()`, which proves executi… |
+| Worker.Tests-012 | Low | Testing coverage | `src/MxGateway.Worker.Tests/Ipc/WorkerFrameProtocolTests.cs` | `docs/WorkerFrameProtocol.md` states the reader "rejects zero-length payloads and payloads larger than the configured maximum (default 16 MiB) before allocating the payload buffer." `WorkerFrameProtocolTests` covers malformed-length, wrong… |
+| Worker.Tests-013 | Low | Concurrency & thread safety | `src/MxGateway.Worker.Tests/Ipc/WorkerPipeSessionTests.cs:539-546` | `ThrowIfCompletedAsync` does an unconditional `await Task.Delay(TimeSpan.FromMilliseconds(100))` then checks `task.IsCompleted`. This adds a fixed 100 ms to the test and only catches a `RunAsync` that fails within that arbitrary window; a… |
+| Worker.Tests-014 | Low | Code organization & conventions | `src/MxGateway.Worker.Tests/Ipc/WorkerPipeClientTests.cs:194`, `WorkerPipeSessionTests.cs:622`, `Sta/StaCommandDispatcherTests.cs:348`, `MxAccess/MxAccessStaSessionTests.cs:334`, `MxAccess/MxAccessCommandExecutorTests.cs:1124` | `FakeRuntimeSession`, `NoopComApartmentInitializer`, `NoopEventSink`/`NullEventSink`, and the `CreateFrame`/`WriteUInt32LittleEndian` helpers are re-implemented independently in multiple test files. The two `FakeRuntimeSession` implementat… |
+| Worker.Tests-015 | Low | Testing coverage | `src/MxGateway.Worker.Tests/MxAccess/MxAccessEventQueueTests.cs` | `MxAccessEventQueueTests` covers monotonic sequencing, drain, capacity overflow, and first-fault-wins, but does not cover `Drain` with `maxEvents: 0` (drain-all) — a branch `FakeRuntimeSession.DrainEvents` even special-cases — nor draining… |
+
+## Closed findings
+
+Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
+
+| ID | Severity | Status | Category | Location |
+|---|---|---|---|---|
+| Server-001 | Critical | Resolved | Security | `src/MxGateway.Server/GatewayApplication.cs:147-149`, `src/MxGateway.Server/Dashboard/DashboardEndpointRouteBuilderExtensions.cs:55-58`, `src/MxGateway.Server/Dashboard/Components/Routes.razor:1-15` |
+| Client.Rust-001 | High | Resolved | mxaccessgw conventions | `clients/rust/src/options.rs:98,143` |
+| Client.Rust-002 | High | Resolved | mxaccessgw conventions | `clients/rust/src/session.rs:522` |
+| Client.Rust-003 | High | Resolved | Correctness & logic bugs | `clients/rust/crates/mxgw-cli/src/main.rs:1051` |
+| Client.Rust-012 | High | Resolved | mxaccessgw conventions | `clients/rust/src/galaxy.rs:282` |
+| Server-003 | High | Resolved | Security | `src/MxGateway.Server/Dashboard/DashboardAuthorizationHandler.cs:39,54-59`, `src/MxGateway.Server/Dashboard/DashboardAuthenticator.cs:236-258` |
+| Client.Rust-005 | Medium | Resolved | Correctness & logic bugs | `clients/rust/src/session.rs:489-520` |
+| Client.Rust-006 | Medium | Resolved | Error handling & resilience | `clients/rust/src/session.rs:531-555` |
+| Client.Rust-004 | Low | Resolved | Documentation & comments | `clients/rust/src/version.rs:7` |
+| Client.Rust-007 | Low | Resolved | Design-document adherence | `clients/rust/RustClientDesign.md:14-55` |
+| Client.Rust-008 | Low | Resolved | Performance & resource management | `clients/rust/src/value.rs:161-261` |
+| Client.Rust-009 | Low | Resolved | Testing coverage | `clients/rust/tests/client_behavior.rs`, `clients/rust/src/galaxy.rs` |
+| Client.Rust-010 | Low | Resolved | Error handling & resilience | `clients/rust/src/client.rs:255-268`, `clients/rust/src/galaxy.rs:204-216` |
+| Client.Rust-011 | Low | Resolved | mxaccessgw conventions | `clients/rust/src/session.rs:469` |

code-reviews/Server/findings.md

@@ -0,0 +1,237 @@
+# Code Review — Server
+
+| Field | Value |
+|---|---|
+| Module | `src/MxGateway.Server` |
+| Reviewer | Claude Code |
+| Review date | 2026-05-18 |
+| Commit reviewed | `6c64030` |
+| Status | Reviewed |
+| Open findings | 12 |
+
+## Checklist coverage
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issues found: Server-006 (metrics open-session leak on alarm auto-subscribe failure), Server-010 (rotate reactivates revoked keys). |
+| 2 | mxaccessgw conventions | Issues found: Server-002 (orphan-worker termination on startup not implemented), Server-011 (style deviation in `WorkerAlarmRpcDispatcher`). |
+| 3 | Concurrency & thread safety | No issues found — locking is correct; inconsistent-but-safe discipline in `GatewayMetrics` noted only. |
+| 4 | Error handling & resilience | Issues found: Server-005 (Galaxy first-load can fault the host BackgroundService), Server-009 (SQLite has no busy-timeout/WAL under concurrent writes). |
+| 5 | Security | Issues found: Server-001 (Critical: dashboard authorization never enforced on any route), Server-003 (LDAP dashboard users denied for lack of a scope claim), Server-010. |
+| 6 | Performance & resource management | Issues found: Server-007 (DiscoverHierarchy paging is O(total) per page), Server-008 (WatchDeployEvents re-projects whole hierarchy per event). |
+| 7 | Design-document adherence | Issues found: Server-002 (orphan workers), Server-012 (CLAUDE.md scope names stale vs code/docs). |
+| 8 | Code organization & conventions | Issues found: Server-011 (style), Server-004 (CLI accepts unvalidated scope strings). |
+| 9 | Testing coverage | Issues found: Server-013 (no dashboard route-level authorization test; `WorkerExecutableValidator`, `GalaxyGlobMatcher`, projector paging untested). |
+| 10 | Documentation & comments | Issues found: Server-014 (stale "not yet wired" alarm comments), Server-012. |
+
+## Findings
+
+### Server-001
+
+| Field | Value |
+|---|---|
+| Severity | Critical |
+| Category | Security |
+| Location | `src/MxGateway.Server/GatewayApplication.cs:147-149`, `src/MxGateway.Server/Dashboard/DashboardEndpointRouteBuilderExtensions.cs:55-58`, `src/MxGateway.Server/Dashboard/Components/Routes.razor:1-15` |
+| Status | Resolved |
+
+**Description:** The dashboard authorization policy (`DashboardAuthenticationDefaults.AuthorizationPolicy`), `DashboardAuthorizationRequirement`, and `DashboardAuthorizationHandler` are registered in DI but never applied to any endpoint. `MapRazorComponents<App>()` has no `.RequireAuthorization(...)`, the `<Router>` in `Routes.razor` uses plain `RouteView` (not `AuthorizeRouteView`), and no dashboard page carries `[Authorize]` — a module-wide grep finds zero `RequireAuthorization`/`[Authorize]`/`AuthorizeRouteView` usages. Every dashboard page (Sessions, Workers, Events, Galaxy, Settings, and the API Keys list exposing key IDs, scopes, and constraints) is reachable by any unauthenticated remote client regardless of `Dashboard:AllowAnonymousLocalhost` or `Dashboard:RequireAdminScope`. Only the API-key mutation operations remain protected, via the separate `DashboardApiKeyManagementService.CanManage` check.
+
+**Recommendation:** Apply the policy at the route level — `endpoints.MapRazorComponents<App>().AddInteractiveServerRenderMode().RequireAuthorization(DashboardAuthenticationDefaults.AuthorizationPolicy)` — and/or switch `Routes.razor` to `AuthorizeRouteView` with a `[Authorize]` fallback policy plus a `NotAuthorized` redirect to the login page. Add an integration test that GETs a dashboard page anonymously and asserts 302-to-login / 401.
+
+**Resolution:** Resolved in `a8aafdf` (2026-05-18): `MapRazorComponents<App>()` now calls `.RequireAuthorization(DashboardAuthenticationDefaults.AuthorizationPolicy)`, so an unauthenticated request to any dashboard component route is challenged by the cookie scheme and redirected to the login page. `GatewayApplicationTests` gained `ComponentRoutesRequireAuthorization` (component routes carry the policy) and `AuthEndpointsAllowAnonymousAccess`, replacing the prior test that asserted the insecure behavior.
+
+### Server-002
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Design-document adherence |
+| Location | `src/MxGateway.Server/Program.cs:24`, `src/MxGateway.Server/GatewayApplication.cs` |
+| Status | Open |
+
+**Description:** `gateway.md:583` and CLAUDE.md state the first version "terminates orphaned workers on startup." No code in MxGateway.Server enumerates or kills leftover `MxGateway.Worker.exe` processes at startup — a grep for `orphan`/`reattach`/`terminate` finds nothing. After an unclean gateway crash, x86 worker processes (each holding an MXAccess COM instance) leak and survive indefinitely, and a restarted gateway does not reclaim or kill them.
+
+**Recommendation:** Add a startup hosted service that finds and kills stale worker processes (by executable path / a well-known argument or environment marker) before the server accepts sessions, or update the design docs if reattachment/cleanup is deliberately deferred.
+
+**Resolution:** _(open)_
+
+### Server-003
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Security |
+| Location | `src/MxGateway.Server/Dashboard/DashboardAuthorizationHandler.cs:39,54-59`, `src/MxGateway.Server/Dashboard/DashboardAuthenticator.cs:236-258` |
+| Status | Resolved |
+
+**Description:** When `Dashboard:RequireAdminScope` is true (the default) and the request is not loopback, `DashboardAuthorizationHandler` succeeds only if `HasAdminScope` finds a claim of type `"scope"` with value `"admin"`. But `DashboardAuthenticator.CreatePrincipal` issues only `NameIdentifier`, `Name`, and `LdapGroupClaimType` claims — never a `scope`/`admin` claim. So a correctly LDAP-authenticated user who passed the required-group check is still denied dashboard access on any non-loopback connection. The bug is currently masked by the missing route-level enforcement (Server-001) and by `AllowAnonymousLocalhost`; fixing Server-001 would make the dashboard unusable for all real LDAP logins.
+
+**Recommendation:** Either have `DashboardAuthenticator.CreatePrincipal` add a `scope=admin` claim when the user is in the required group, or change `DashboardAuthorizationHandler.HasAdminScope` to evaluate LDAP group membership (reuse `IsMemberOfRequiredGroup` against the `LdapGroupClaimType` claims, as `DashboardApiKeyAuthorization.CanManage` already does).
+
+**Resolution:** Resolved in `a8aafdf` (2026-05-18): `DashboardAuthenticator.CreatePrincipal` — reached only after the required-group check passes — now emits the `scope=admin` claim that `DashboardAuthorizationHandler` checks, so group-validated LDAP users pass `RequireAdminScope` once route-level authorization (Server-001) is enforced.
+
+### Server-004
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Code organization & conventions |
+| Location | `src/MxGateway.Server/Security/Authentication/ApiKeyAdminCommandLineParser.cs:227-233`, `src/MxGateway.Server/Security/Authentication/ApiKeyAdminCliRunner.cs:53-77`, `src/MxGateway.Server/Dashboard/DashboardApiKeyManagementService.cs:21-67` |
+| Status | Open |
+
+**Description:** `ParseScopes` accepts any comma-separated strings and `CreateKeyAsync` persists them verbatim; neither the CLI nor the dashboard create path validates scopes against `GatewayScopes`. A typo or non-canonical name (e.g. CLAUDE.md's example `--scopes session,invoke,event,metadata,admin`, which does not match the resolver's `session:open`/`invoke:read`/etc.) silently creates a key whose scope strings the authorization resolver never checks for — the key is unusable for those RPCs with no error at creation time.
+
+**Recommendation:** Validate every requested scope against the `GatewayScopes` catalog at create time in both the CLI parser/runner and `DashboardApiKeyManagementService.ValidateCreateRequest`, rejecting unknown scope strings.
+
+**Resolution:** _(open)_
+
+### Server-005
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `src/MxGateway.Server/Galaxy/GalaxyHierarchyRefreshService.cs:22-28`, `src/MxGateway.Server/Galaxy/GalaxyHierarchyCache.cs:184` |
+| Status | Open |
+
+**Description:** `GalaxyHierarchyCache.RefreshCoreAsync` only catches `SqlException` and `InvalidOperationException`. The initial `cache.RefreshAsync` call in `GalaxyHierarchyRefreshService.ExecuteAsync` is wrapped only for `OperationCanceledException`. A transient non-`SqlException` failure on the first refresh (e.g. a `Win32Exception`/`TimeoutException` from connection establishment, or another `DbException` subtype) escapes both layers, faults the `BackgroundService`, and — with default host behavior — stops the whole gateway. The periodic-tick loop does catch general exceptions, so only the first load is exposed.
+
+**Recommendation:** Broaden the `catch` in `RefreshCoreAsync` to all non-cancellation exceptions (record `Unavailable`/`Stale` and still complete `_firstLoad`), or wrap the initial `RefreshAsync` in `GalaxyHierarchyRefreshService` with the same general `catch` the tick loop uses.
+
+**Resolution:** _(open)_
+
+### Server-006
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Correctness & logic bugs |
+| Location | `src/MxGateway.Server/Sessions/SessionManager.cs:84-114` |
+| Status | Open |
+
+**Description:** In `OpenSessionAsync`, `_metrics.SessionOpened()` (line 89) increments the `_openSessions` gauge before `TryAutoSubscribeAlarmsAsync` runs. If auto-subscribe throws (which it does when `Alarms.RequireSubscribeOnOpen` is true and the worker rejects the subscription), the `catch` block disposes and removes the session and records `_metrics.Fault(...)` but never calls `SessionClosed`/`SessionRemoved`. The `mxgateway.sessions.open` gauge permanently over-counts by one for every such failed open.
+
+**Recommendation:** In the `catch` block, when the session had reached the point where `SessionOpened()` was recorded, also call `_metrics.SessionRemoved()` — or move the `SessionOpened()` call to after auto-subscribe succeeds.
+
+**Resolution:** _(open)_
+
+### Server-007
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Performance & resource management |
+| Location | `src/MxGateway.Server/Galaxy/GalaxyHierarchyProjector.cs:55-70` |
+| Status | Open |
+
+**Description:** `Project` always iterates the full `entry.Index.ObjectViews` collection and re-applies all filters to skip `offset` matched items before collecting a page. Paging through a large Galaxy hierarchy is therefore O(total) per page and O(total²/pageSize) end-to-end. The cache is in-memory so impact is bounded, but for large galaxies repeated `DiscoverHierarchy` pagination wastes CPU.
+
+**Recommendation:** Precompute and cache the filtered, ordered view list per `(filterSignature, sequence)` so subsequent pages are an O(pageSize) slice; the existing filter signature already keys page tokens.
+
+**Resolution:** _(open)_
+
+### Server-008
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Performance & resource management |
+| Location | `src/MxGateway.Server/Grpc/GalaxyRepositoryGrpcService.cs:111-134,160-189` |
+| Status | Open |
+
+**Description:** `WatchDeployEvents` calls `ResolveBrowseSubtrees()` on every streamed event, and `MapDeployEvent` re-runs `GalaxyHierarchyProjector.Project` over the entire cached hierarchy (and `Sum`s attribute counts) for every event of every constrained subscriber. `GalaxyGlobMatcher.IsMatch` also rebuilds the glob regex on each call. With many constrained subscribers and frequent deploys this is avoidable work.
+
+**Recommendation:** Hoist `ResolveBrowseSubtrees()` out of the loop; compute scoped object/attribute counts once per deploy sequence and cache by `(sequence, browseSubtrees)`; cache compiled glob `Regex` instances in `GalaxyGlobMatcher`.
+
+**Resolution:** _(open)_
+
+### Server-009
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Error handling & resilience |
+| Location | `src/MxGateway.Server/Security/Authentication/AuthSqliteConnectionFactory.cs:15-32` |
+| Status | Open |
+
+**Description:** Each auth-store operation opens a fresh `SqliteConnection` with no busy timeout, no WAL journal mode, and default journaling. `MarkKeyUsedAsync` runs on every authenticated request and `SqliteApiKeyAuditStore` appends on every denial; under concurrent load these writers can collide and surface `SQLITE_BUSY` as a hard failure on the request path.
+
+**Recommendation:** Set `Pooling`, a non-zero `DefaultTimeout`/`busy_timeout`, and enable WAL (`PRAGMA journal_mode=WAL`) once at startup so concurrent readers/writers degrade gracefully.
+
+**Resolution:** _(open)_
+
+### Server-010
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Security |
+| Location | `src/MxGateway.Server/Security/Authentication/SqliteApiKeyAdminStore.cs:91-114`, `src/MxGateway.Server/Dashboard/Components/Pages/ApiKeysPage.razor:168-172` |
+| Status | Open |
+
+**Description:** `RotateAsync` sets `revoked_utc = NULL`, so rotating a previously revoked key silently reactivates it. This is documented intentional behavior in `docs/Authentication.md:167`, but the dashboard renders the "Rotate" button unconditionally — including for keys whose status badge says "Revoked" — so an operator can un-revoke a deliberately disabled key without an explicit warning.
+
+**Recommendation:** Either hide/disable the Rotate action for revoked keys in `ApiKeysPage.razor`, require an explicit confirmation, or have `RotateAsync` preserve `revoked_utc` and add a separate explicit "reactivate" operation.
+
+**Resolution:** _(open)_
+
+### Server-011
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `src/MxGateway.Server/Sessions/WorkerAlarmRpcDispatcher.cs:1-46` |
+| Status | Open |
+
+**Description:** `WorkerAlarmRpcDispatcher` deviates from the module's conventions: it fully-qualifies `System.Guid`, `System.ArgumentNullException`, and `System.Threading` types inline instead of relying on `using` directives, and uses an explicit constructor with `this.`-qualified field assignment while the rest of the module (e.g. `ConstraintEnforcer`, `MxAccessGatewayService`, `GalaxyRepositoryGrpcService`) uses primary constructors. `docs/style-guides/CSharpStyleGuide.md` is authoritative for gateway code.
+
+**Recommendation:** Add the needed `using` directives, drop the inline fully-qualified names, and convert to a primary constructor for consistency.
+
+**Resolution:** _(open)_
+
+### Server-012
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `CLAUDE.md` (Authentication section and `apikey create` example) |
+| Status | Open |
+
+**Description:** CLAUDE.md describes scopes as `session`, `invoke`, `event`, `metadata`, `admin` and shows `apikey create --scopes session,invoke,event,metadata,admin`. The actual canonical scope strings (used by `GatewayScopes`, `GatewayGrpcScopeResolver`, and `docs/Authorization.md`) are `session:open`, `session:close`, `invoke:read`, `invoke:write`, `invoke:secure`, `events:read`, `metadata:read`, `admin`. A key created per the CLAUDE.md example carries scopes the resolver never matches.
+
+**Recommendation:** Update CLAUDE.md's scope list and the `apikey` example to the canonical `*:*` scope strings, per CLAUDE.md's own rule that docs change with the code.
+
+**Resolution:** _(open)_
+
+### Server-013
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `src/MxGateway.Tests/Gateway/Dashboard/DashboardAuthorizationHandlerTests.cs`, `src/MxGateway.Tests/Gateway/GatewayApplicationTests.cs` |
+| Status | Open |
+
+**Description:** `DashboardAuthorizationHandler` is unit-tested in isolation, but no test exercises the dashboard routes end-to-end to confirm the policy is actually enforced — which is why Server-001 (policy registered but never wired) went uncaught. There are also no tests for `WorkerExecutableValidator` (PE-header architecture parsing), `GalaxyGlobMatcher` (anchoring/escaping/empty-glob fail-open), or `GalaxyHierarchyProjector` pagination/page-token behavior.
+
+**Recommendation:** Add a `WebApplicationFactory` integration test that requests a dashboard page unauthenticated and asserts the redirect/401, plus unit tests for `WorkerExecutableValidator`, `GalaxyGlobMatcher`, and projector paging.
+
+**Resolution:** _(open)_
+
+### Server-014
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `src/MxGateway.Server/Grpc/MxAccessGatewayService.cs:162-171,191-198,206-214,229-237` |
+| Status | Open |
+
+**Description:** The XML `<remarks>` and inline comments on `AcknowledgeAlarm` and `QueryActiveAlarms` describe the alarm path as not yet wired and say `NotWiredAlarmRpcDispatcher` is the default ("Clients calling this method today receive an OK reply with a 'worker alarm path not yet wired' diagnostic", "an empty stream until PR A.2"). In fact `SessionServiceCollectionExtensions.AddGatewaySessions` registers `WorkerAlarmRpcDispatcher` as `IAlarmRpcDispatcher`, so DI always injects the production dispatcher; `NotWiredAlarmRpcDispatcher` is only the null fallback. The comments are stale and misleading.
+
+**Recommendation:** Update the `AcknowledgeAlarm`/`QueryActiveAlarms` remarks to reflect that `WorkerAlarmRpcDispatcher` is the wired default, and describe its actual GUID-vs-`Provider!Group.Tag` handling.
+
+**Resolution:** _(open)_

code-reviews/Tests/findings.md

@@ -0,0 +1,207 @@
+# Code Review — Tests
+
+| Field | Value |
+|---|---|
+| Module | `src/MxGateway.Tests` |
+| Reviewer | Claude Code |
+| Review date | 2026-05-18 |
+| Commit reviewed | `6c64030` |
+| Status | Reviewed |
+| Open findings | 12 |
+
+## Checklist coverage
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issue found: Tests-001 (`FakeSessionManager.TryGetSession` always returns true), Tests-011 (unobserved worker task). |
+| 2 | mxaccessgw conventions | FakeWorkerHarness used per docs; no real secrets; minor style drift in three alarm-test files (Tests-008). |
+| 3 | Concurrency & thread safety | Issues found: Tests-006 (`Task.Delay`-based timing), Tests-012 (no parallelism guard for `WebApplication` tests). |
+| 4 | Error handling & resilience | Strong — timeouts, faults, overflow, kill paths, protocol violations all exercised. No issues found. |
+| 5 | Security | Issues found: Tests-002 (no SQL-injection coverage of Galaxy RPCs), Tests-010 (anonymous-localhost negative cases untested). |
+| 6 | Performance & resource management | Issue found: Tests-003 (temp DB/worker directories never cleaned up). |
+| 7 | Design-document adherence | Tests match `docs/GatewayTesting.md`; no drift found. No issues found. |
+| 8 | Code organization & conventions | Issue found: Tests-007 (`TestServerCallContext` copy-pasted into 4+ files). |
+| 9 | Testing coverage | Issues found: Tests-001, Tests-004 (no end-to-end interceptor+service test), Tests-005 (no worker-crash-mid-command coverage), Tests-002. |
+| 10 | Documentation & comments | Issue found: Tests-009 (stale/mismatched XML `<summary>` comments). |
+
+## Findings
+
+### Tests-001
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Testing coverage |
+| Location | `src/MxGateway.Tests/Gateway/Grpc/MxAccessGatewayServiceTests.cs:483-489` |
+| Status | Open |
+
+**Description:** `FakeSessionManager.TryGetSession` unconditionally returns `true` and synthesizes a session for any id. As a result, `Invoke_WhenSessionMissing_ThrowsNotFound` (line 52) only passes because `InvokeException` is pre-seeded — it does not verify that the gateway service maps a genuinely missing session to `NotFound`. No test exercises the real gateway path where `TryGetSession` returns `false` (for `StreamEvents`, `CloseSession`, alarm RPCs). A regression dropping the missing-session check would not be caught.
+
+**Recommendation:** Make `FakeSessionManager.TryGetSession` return `false` for unknown ids (return only seeded sessions), then assert `NotFound`/`InvalidArgument` is produced by the service's own lookup logic rather than an injected exception.
+
+**Resolution:** _(open)_
+
+### Tests-002
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Security |
+| Location | `src/MxGateway.Tests/Gateway/Grpc/GalaxyRepositoryGrpcServiceTests.cs:198-210` |
+| Status | Open |
+
+**Description:** The Galaxy Repository RPCs browse a SQL Server database (`ZB`). Every test injects a `StubGalaxyHierarchyCache`, so actual SQL query construction, parameterization, and filter/glob translation are never exercised. No test demonstrates that `TagNameGlob`, `RootTagName`, `AlarmFilterPrefix`, etc. are passed as parameters rather than concatenated into SQL. SQL-injection resistance of the Galaxy layer has zero coverage.
+
+**Recommendation:** Add tests for the `GalaxyRepository` query-building layer (against SQLite or an in-memory abstraction, or by asserting parameter objects), covering glob/prefix inputs containing `'`, `%`, `_`, and `;`. At minimum add a unit test over the SQL `LIKE`-pattern escaping helper.
+
+**Resolution:** _(open)_
+
+### Tests-003
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Performance & resource management |
+| Location | `src/MxGateway.Tests/Security/Authentication/SqliteAuthStoreTests.cs:170-176`, `src/MxGateway.Tests/Security/Authentication/ApiKeyAdminCliRunnerTests.cs:252-258` |
+| Status | Open |
+
+**Description:** `CreateTempDatabasePath` creates a fresh directory under `%TEMP%\mxgateway-auth-tests\<guid>` (and `...-cli-tests`) for every test but nothing ever deletes it. `WorkerProcessLauncherTests.TestDirectory` correctly implements `IDisposable` and cleans up; these two do not. SQLite connection pooling can also keep the `.db` handle open after the test. Over many CI runs this leaks temp files and open handles.
+
+**Recommendation:** Wrap the temp directory in an `IDisposable`/`IAsyncDisposable` helper (as `WorkerProcessLauncherTests` does) and call `SqliteConnection.ClearAllPools()` before deletion, or use `Microsoft.Data.Sqlite` in-memory mode where a real file is not needed.
+
+**Resolution:** _(open)_
+
+### Tests-004
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Testing coverage |
+| Location | `src/MxGateway.Tests/Security/Authorization/GatewayGrpcAuthorizationInterceptorTests.cs` |
+| Status | Open |
+
+**Description:** The authorization interceptor and `MxAccessGatewayService` are each tested in isolation, but no test composes the interceptor in front of the real service to confirm scope enforcement gates real RPCs end-to-end. A wiring mistake — interceptor not registered, or a new RPC added without a scope mapping in `GatewayGrpcScopeResolver` — would pass every existing test. `GatewayGrpcScopeResolverTests` also only checks an enumerated allow-list; it never asserts an unmapped request type fails closed.
+
+**Recommendation:** Add an end-to-end test that runs `OpenSession`/`Invoke` through the interceptor+service composition with insufficient scope and asserts `PermissionDenied`; add a `GatewayGrpcScopeResolver` test asserting an unknown/unmapped request type throws or denies rather than returning a permissive default.
+
+**Resolution:** _(open)_
+
+### Tests-005
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Testing coverage |
+| Location | `src/MxGateway.Tests/Gateway/Grpc/EventStreamServiceTests.cs:239-261`, `src/MxGateway.Tests/Gateway/Sessions/SessionManagerTests.cs` |
+| Status | Open |
+
+**Description:** Worker-crash handling is only tested as a clean terminal exception from `ReadEventsAsync` or a pre-set `ShutdownException`. There is no test for a worker that faults mid-command — an `InvokeAsync` in flight when the pipe/worker dies — which is a core fault-handling path of the two-process design. `WorkerClientTests` covers pipe-disconnect faulting the read loop, but not the interaction where a pending `InvokeAsync` task observes the fault and surfaces a meaningful error code.
+
+**Recommendation:** Add a `WorkerClient`/`SessionManager` test that disposes the worker pipe (or emits a `WorkerFault`) while an `InvokeAsync` is pending, and assert the invoke task fails with a `WorkerClientException`/`SessionManagerException` carrying the worker-faulted error code.
+
+**Resolution:** _(open)_
+
+### Tests-006
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Concurrency & thread safety |
+| Location | `src/MxGateway.Tests/Gateway/Workers/WorkerClientTests.cs:76`, `src/MxGateway.Tests/Gateway/Workers/FakeWorkerHarnessTests.cs:122` |
+| Status | Open |
+
+**Description:** Several tests rely on fixed `Task.Delay` values: `WorkerClientTests.InvokeAsync_WithLateReply…` waits a hard-coded 50 ms after writing a late reply before issuing the second command, and the heartbeat tests use a 20 ms delay to make timestamps strictly increase. On a slow CI agent the 50 ms delay can be insufficient, and `DateTimeOffset.UtcNow` resolution can make the 20 ms heartbeat-advance assertion flaky.
+
+**Recommendation:** Replace fixed delays with the existing `WaitUntilAsync` condition polling, and inject a controllable `TimeProvider` for heartbeat-timestamp comparisons instead of relying on wall-clock advance.
+
+**Resolution:** _(open)_
+
+### Tests-007
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `src/MxGateway.Tests/Gateway/Grpc/MxAccessGatewayServiceTests.cs:682`, `src/MxGateway.Tests/Gateway/Grpc/GalaxyRepositoryGrpcServiceTests.cs:324`, `src/MxGateway.Tests/Gateway/GatewayEndToEndFakeWorkerSmokeTests.cs:460`, `src/MxGateway.Tests/Security/Authorization/GatewayGrpcAuthorizationInterceptorTests.cs:233` |
+| Status | Open |
+
+**Description:** A near-identical `TestServerCallContext` implementation is copy-pasted into at least four test files (and `AllowAllConstraintEnforcer` / `TestServerStreamWriter` / `RecordingStreamWriter` into several). Duplication risks the copies drifting and bloats each file.
+
+**Recommendation:** Extract a shared `TestServerCallContext`, `RecordingServerStreamWriter<T>`, and `AllowAllConstraintEnforcer` into a common test-support folder/namespace.
+
+**Resolution:** _(open)_
+
+### Tests-008
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | mxaccessgw conventions |
+| Location | `src/MxGateway.Tests/Gateway/Sessions/WorkerAlarmRpcDispatcherTests.cs:1-9`, `src/MxGateway.Tests/Gateway/Sessions/NotWiredAlarmRpcDispatcherTests.cs:1-3`, `src/MxGateway.Tests/Gateway/Sessions/SessionManagerAlarmAutoSubscribeTests.cs:1` |
+| Status | Open |
+
+**Description:** The alarm test files diverge from the project's C# style and the rest of the suite: snake_case test method names instead of the PascalCase `Method_Condition_Result` pattern; redundant explicit `using System;`/`System.Threading;` imports despite implicit global usings; and explicit-type `new` instead of target-typed `new()` used elsewhere. There is also a typo in fixture data (`"wnwrap subscribe failed"`).
+
+**Recommendation:** Rename the alarm tests to the house `Method_Condition_Result` convention, drop redundant `System.*` usings, align `new` usage, and fix the `wnwrap` typo.
+
+**Resolution:** _(open)_
+
+### Tests-009
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `src/MxGateway.Tests/Gateway/Sessions/SessionManagerTests.cs:36-37,99,365` |
+| Status | Open |
+
+**Description:** Several XML `<summary>` comments are copy-paste mismatches: the comment above `OpenSessionAsync_SetsInitialDefaultLease` describes correlation-ID generation; the comment above `GatewaySessionSubscribeBulkAsync_ForwardsOneBulkCommand…` describes lease refresh; the comment above `CloseExpiredLeasesAsync_DoesNotCloseActiveEventSubscriber` describes shutdown closing all sessions. Misleading test docs hinder triage.
+
+**Recommendation:** Correct the `<summary>` text to match each test's actual behavior, or remove the redundant comments since the test names already describe the behavior.
+
+**Resolution:** _(open)_
+
+### Tests-010
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Security |
+| Location | `src/MxGateway.Tests/Gateway/Dashboard/DashboardAuthorizationHandlerTests.cs:26-36` |
+| Status | Open |
+
+**Description:** The anonymous-localhost bypass is tested only for the success case (`allowAnonymousLocalhost: true` + loopback succeeds) and the remote-unauthenticated denial. There is no test for the security-critical negatives: anonymous + loopback when `AllowAnonymousLocalhost` is `false` must be denied, and anonymous + non-loopback when the flag is `true` must still be denied (the bypass is scoped strictly to loopback). Those are the misconfiguration cases that would expose the dashboard.
+
+**Recommendation:** Add tests: anonymous + loopback + `allowAnonymousLocalhost: false` → not succeeded; anonymous + non-loopback + `allowAnonymousLocalhost: true` → not succeeded.
+
+**Resolution:** _(open)_
+
+### Tests-011
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `src/MxGateway.Tests/Gateway/GatewayEndToEndFakeWorkerSmokeTests.cs:233-301` |
+| Status | Open |
+
+**Description:** `GatewayEndToEndFakeWorkerSmokeTests` correctly stores and awaits `launcher.WorkerTask`, but `SessionWorkerClientFactoryFakeWorkerTests` uses `_ = RunWorkerAsync(...)` with no stored task (lines 152, 184, 220). An unhandled exception in the scripted worker becomes an unobserved `TaskException` that can surface as a process-level failure in an unrelated later test rather than failing the owning test.
+
+**Recommendation:** Store the worker task and either await it during disposal or attach a continuation that fails the test on fault, mirroring `GatewayEndToEndFakeWorkerSmokeTests`.
+
+**Resolution:** _(open)_
+
+### Tests-012
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Concurrency & thread safety |
+| Location | `src/MxGateway.Tests/Gateway/Workers/Fakes/FakeWorkerHarness.cs:62`, `src/MxGateway.Tests/Gateway/Workers/WorkerClientTests.cs:472` |
+| Status | Open |
+
+**Description:** Pipe names are uniquified per test with a GUID (good), but xUnit runs test classes in parallel by default and there is no `xunit.runner.json` or collection configuration. Tests that build a full `WebApplication` bind ephemeral ports (`--urls=http://127.0.0.1:0`, fine) but spin up DI containers and hosted services concurrently. Currently safe, but a future test binding a fixed port would silently collide.
+
+**Recommendation:** Add an `xunit.runner.json` or a collection grouping the `WebApplication`-building tests, and keep the `:0` ephemeral-port convention explicit so future tests do not introduce a fixed-port collision.
+
+**Resolution:** _(open)_

code-reviews/Worker.Tests/findings.md

@@ -0,0 +1,252 @@
+# Code Review — Worker.Tests
+
+| Field | Value |
+|---|---|
+| Module | `src/MxGateway.Worker.Tests` |
+| Reviewer | Claude Code |
+| Review date | 2026-05-18 |
+| Commit reviewed | `6c64030` |
+| Status | Reviewed |
+| Open findings | 15 |
+
+## Checklist coverage
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issues found: Worker.Tests-010 (weak substring assertion), Worker.Tests-011 (test name overstates what it proves). |
+| 2 | mxaccessgw conventions | Tests respect STA-affinity and the WorkerEnvelope frame protocol; naming-convention drift only (Worker.Tests-009). |
+| 3 | Concurrency & thread safety | Issues found: Worker.Tests-003/004/013 (wall-clock and fixed-delay timing assertions). |
+| 4 | Error handling & resilience | COMException/HResult, pipe-never-appears, malformed frames, shutdown-during-command, watchdog all covered; queue branch gap (Worker.Tests-015). |
+| 5 | Security | No real secrets; redaction explicitly tested. No issues found. |
+| 6 | Performance & resource management | Issues found: Worker.Tests-005 (`MemoryStream` not disposed), Worker.Tests-006 (`MxAccessStaSession` leak on assertion failure). |
+| 7 | Design-document adherence | Tests match `docs/Worker*.md`; `docs/WorkerFrameProtocol.md` is stale (Worker.Tests-007). |
+| 8 | Code organization & conventions | Issues found: Worker.Tests-009 (two naming conventions), Worker.Tests-014 (duplicated test doubles). |
+| 9 | Testing coverage | Issues found: Worker.Tests-001 (`StaMessagePump` untested), Worker.Tests-002 (COM-event delivery untested), Worker.Tests-012 (frame-validation gaps). |
+| 10 | Documentation & comments | Issues found: Worker.Tests-008 (misplaced redaction test), Worker.Tests-011 (misleading test name). |
+
+## Findings
+
+### Worker.Tests-001
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Testing coverage |
+| Location | `src/MxGateway.Worker.Tests/Sta/` (no `StaMessagePumpTests.cs`) |
+| Status | Open |
+
+**Description:** `StaMessagePump` — whose entire reason for existing is pumping Windows messages so MXAccess COM event sink calls deliver onto the STA — has no direct unit test. `WaitForWorkOrMessages` (timeout conversion, the `MsgWaitForMultipleObjectsEx` failure path) and `PumpPendingMessages` (drain count) are exercised only indirectly via `StaRuntime`, which never asserts the pump returns/throws correctly. The `MsgWaitFailed` error branch and `ToTimeoutMilliseconds` edge cases (`InfiniteTimeSpan`, `<= Zero`, `>= uint.MaxValue`) are completely uncovered.
+
+**Recommendation:** Add `StaMessagePumpTests` that post a Windows message to the STA thread and assert `PumpPendingMessages` returns the expected count; cover `WaitForWorkOrMessages` waking on a signaled event vs timeout; cover `ToTimeoutMilliseconds` boundaries through an internals-visible seam.
+
+**Resolution:** _(open)_
+
+### Worker.Tests-002
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Testing coverage |
+| Location | `src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs`, `src/MxGateway.Worker.Tests/MxAccess/MxAccessEventMapperTests.cs` |
+| Status | Open |
+
+**Description:** No test verifies that a COM event raised on the STA thread is converted to protobuf and lands in the `MxAccessEventQueue`. `MxAccessEventMapperTests` exercises the mapper directly with hand-built fakes, and `AlarmDispatcherTests` covers the alarm sink, but the non-alarm COM-event path (`MxAccessBaseEventSink`/`MxAccessComServer` event handlers → `MxAccessEventMapper` → queue, triggered by an actual sink callback) is never end-to-end tested. Given the worker's core purpose is to convert COM events to protobuf, this is a significant gap.
+
+**Recommendation:** Add a test that invokes the base event sink's data-change handler (via an internal seam or a fake COM event source) and asserts a converted `WorkerEvent` with correct family/sequence appears in the queue.
+
+**Resolution:** _(open)_
+
+### Worker.Tests-003
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Concurrency & thread safety |
+| Location | `src/MxGateway.Worker.Tests/Sta/StaRuntimeTests.cs:46-48` |
+| Status | Open |
+
+**Description:** `InvokeAsync_WakesIdlePumpForQueuedCommand` asserts `stopwatch.Elapsed < TimeSpan.FromSeconds(2)` — a wall-clock assertion that on a loaded CI agent can exceed 2s, producing a false failure. The test also does not actually prove the wake event (vs the 50 ms idle pump) caused the dispatch.
+
+**Recommendation:** Remove the wall-clock assertion (the awaited result already proves the command ran), or raise the budget substantially with a comment that it is a coarse smoke check.
+
+**Resolution:** _(open)_
+
+### Worker.Tests-004
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Concurrency & thread safety |
+| Location | `src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs:281-329` |
+| Status | Open |
+
+**Description:** `StartAsync_WithAlarmCommandHandlerFactory_PollOnceCalledViaSta` and `Dispose_StopsAlarmPollLoop` use poll-until loops, and `Dispose_StopsAlarmPollLoop` additionally does `await Task.Delay(1000)` then asserts `PollCount` is unchanged. The 1s "no further polls" window is a timing race: a poll scheduled just before disposal could increment the counter afterward, and a slow agent could simply not run a poll in the window even without correct stop logic.
+
+**Recommendation:** Make the poll loop deterministically observable — expose a "poll loop stopped" signal or have `Dispose` join the poll task — then assert on that rather than on elapsed-time silence.
+
+**Resolution:** _(open)_
+
+### Worker.Tests-005
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Performance & resource management |
+| Location | `src/MxGateway.Worker.Tests/Ipc/WorkerFrameProtocolTests.cs:20-31,103-105`, `src/MxGateway.Worker.Tests/Ipc/WorkerPipeSessionTests.cs:28-31` |
+| Status | Open |
+
+**Description:** `MemoryStream` instances are created and never disposed across the frame-protocol and pipe-session tests (`MemoryStream stream = new();` with no `using`). Disposal is cheap so impact is low, but it is inconsistent with the rest of the suite (which carefully `using`s `CancellationTokenSource`, `StaRuntime`, `PipePair`). `WorkerFrameWriter`/`WorkerFrameReader` are also constructed without disposal.
+
+**Recommendation:** Wrap `MemoryStream` (and reader/writer if they are `IDisposable`) in `using` declarations for consistency.
+
+**Resolution:** _(open)_
+
+### Worker.Tests-006
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Performance & resource management |
+| Location | `src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs:282,305,315,323` |
+| Status | Open |
+
+**Description:** `Dispose_StopsAlarmPollLoop` constructs `MxAccessStaSession session` without `using` (unlike every sibling test) and relies on an explicit `session.Dispose()`. If an assertion between `StartAsync` and `Dispose()` throws, the session — its STA thread and poll loop — leaks for the rest of the run. The `StaRuntime` is `using`d so the thread is eventually reclaimed, but the alarm poll loop and handler are not.
+
+**Recommendation:** Use `using MxAccessStaSession session = ...` and drop the manual `Dispose()`, or wrap the body in try/finally.
+
+**Resolution:** _(open)_
+
+### Worker.Tests-007
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Design-document adherence |
+| Location | `docs/WorkerFrameProtocol.md:38-49` |
+| Status | Open |
+
+**Description:** `docs/WorkerFrameProtocol.md` instructs running `dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter WorkerFrameProtocolTests` and states the frame protocol "is part of `MxGateway.Server`". The frame protocol actually lives in `MxGateway.Worker.Ipc` and is tested by `src/MxGateway.Worker.Tests/Ipc/WorkerFrameProtocolTests.cs`. The doc's verification command points at the wrong project and build, so anyone following it after changing the worker frame protocol will not run the relevant tests.
+
+**Recommendation:** Update `docs/WorkerFrameProtocol.md` to reference `src/MxGateway.Worker.Tests` and the x86 worker build (`-p:Platform=x86`).
+
+**Resolution:** _(open)_
+
+### Worker.Tests-008
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `src/MxGateway.Worker.Tests/Conversion/VariantConverterTests.cs:175-182` |
+| Status | Open |
+
+**Description:** `Redactor_WithCredentialBearingValueFields_RedactsBeforeLogging` lives in `VariantConverterTests` but asserts on `WorkerLogRedactor.RedactValue`, which has nothing to do with `VariantConverter`. It is also a near-duplicate of coverage in `WorkerLogRedactorTests`. Placing redaction coverage inside the variant-converter class is misleading.
+
+**Recommendation:** Move this test into `Bootstrap/WorkerLogRedactorTests.cs` (which already exists and tests `RedactFields`).
+
+**Resolution:** _(open)_
+
+### Worker.Tests-009
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `src/MxGateway.Worker.Tests/MxAccess/AlarmCommandHandlerTests.cs`, `AlarmDispatcherTests.cs`, `AlarmCommandExecutorTests.cs`, `AlarmRecordTransitionMapperTests.cs`, `WnWrapAlarmConsumerXmlTests.cs` |
+| Status | Open |
+
+**Description:** The alarm-related test files use `snake_case` method names while the rest of the project uses the `Method_State_Result` PascalCase convention. `docs/style-guides/CSharpStyleGuide.md` and the surrounding code establish PascalCase as the project convention; the alarm files diverge.
+
+**Recommendation:** Rename alarm-test methods to the `Method_Scenario_Expectation` PascalCase form for one consistent convention.
+
+**Resolution:** _(open)_
+
+### Worker.Tests-010
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs:230-258` |
+| Status | Open |
+
+**Description:** `StartAsync_WithoutAlarmCommandHandlerFactory_SubscribeAlarmsReturnsInvalidRequest` asserts `Assert.Contains("alarm", reply.DiagnosticMessage, StringComparison.OrdinalIgnoreCase)`. The XML doc claims it verifies the diagnostic says "alarm consumer not configured", but the assertion only checks the substring "alarm" — which would also match an unrelated message like "invalid alarm GUID". The assertion is weaker than the documented intent.
+
+**Recommendation:** Assert the full diagnostic phrase so the test fails if the diagnostic regresses to a misleading message.
+
+**Resolution:** _(open)_
+
+### Worker.Tests-011
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `src/MxGateway.Worker.Tests/Sta/StaCommandDispatcherTests.cs:92-112` |
+| Status | Open |
+
+**Description:** `DispatchAsync_WhenCanceledAfterExecutionStarts_StillReturnsLateReply` is named and documented as if it proves cancellation arrived after execution began. The test does `Started.Wait(...)` then `cancellation.Cancel()`, which proves execution started, but because the executor is already running on the STA the cancellation is inherently a no-op — the test cannot distinguish "cancel was observed and ignored" from "cancel was never checked". The name overstates what is proven.
+
+**Recommendation:** Either tighten the test (assert the dispatcher's cancel path was reached and declined) or rename/comment it to "cancellation cannot abort an in-flight STA command", matching `gateway.md`'s stated behavior.
+
+**Resolution:** _(open)_
+
+### Worker.Tests-012
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `src/MxGateway.Worker.Tests/Ipc/WorkerFrameProtocolTests.cs` |
+| Status | Open |
+
+**Description:** `docs/WorkerFrameProtocol.md` states the reader "rejects zero-length payloads and payloads larger than the configured maximum (default 16 MiB) before allocating the payload buffer." `WorkerFrameProtocolTests` covers malformed-length, wrong protocol version, wrong session, and malformed payload, but has no test for the zero-length-payload rejection or the oversized-frame rejection — both explicit security-relevant input-validation paths.
+
+**Recommendation:** Add tests feeding a frame with `payload_length == 0` and one with `payload_length` above the configured maximum, asserting the corresponding `WorkerFrameProtocolErrorCode`.
+
+**Resolution:** _(open)_
+
+### Worker.Tests-013
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Concurrency & thread safety |
+| Location | `src/MxGateway.Worker.Tests/Ipc/WorkerPipeSessionTests.cs:539-546` |
+| Status | Open |
+
+**Description:** `ThrowIfCompletedAsync` does an unconditional `await Task.Delay(TimeSpan.FromMilliseconds(100))` then checks `task.IsCompleted`. This adds a fixed 100 ms to the test and only catches a `RunAsync` that fails within that arbitrary window; a session that faults after 100 ms slips past undetected.
+
+**Recommendation:** Replace with a deterministic race: `await Task.WhenAny(runTask, <first-expected-frame-read>)` and assert the run task did not win.
+
+**Resolution:** _(open)_
+
+### Worker.Tests-014
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `src/MxGateway.Worker.Tests/Ipc/WorkerPipeClientTests.cs:194`, `WorkerPipeSessionTests.cs:622`, `Sta/StaCommandDispatcherTests.cs:348`, `MxAccess/MxAccessStaSessionTests.cs:334`, `MxAccess/MxAccessCommandExecutorTests.cs:1124` |
+| Status | Open |
+
+**Description:** `FakeRuntimeSession`, `NoopComApartmentInitializer`, `NoopEventSink`/`NullEventSink`, and the `CreateFrame`/`WriteUInt32LittleEndian` helpers are re-implemented independently in multiple test files. The two `FakeRuntimeSession` implementations have already diverged (one supports `BlockDispatch`/event enqueue, one does not), and `NoopComApartmentInitializer` is defined four times.
+
+**Recommendation:** Extract shared test doubles (`NoopComApartmentInitializer`, frame helpers, a single configurable `FakeRuntimeSession`) into a `TestSupport` folder/namespace consumed by all test classes.
+
+**Resolution:** _(open)_
+
+### Worker.Tests-015
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `src/MxGateway.Worker.Tests/MxAccess/MxAccessEventQueueTests.cs` |
+| Status | Open |
+
+**Description:** `MxAccessEventQueueTests` covers monotonic sequencing, drain, capacity overflow, and first-fault-wins, but does not cover `Drain` with `maxEvents: 0` (drain-all) — a branch `FakeRuntimeSession.DrainEvents` even special-cases — nor draining an empty queue, nor enqueue after a manual `RecordFault`. These are minor branches but the overflow/fault interaction is the worker's backpressure contract.
+
+**Recommendation:** Add a `Drain(0)` drain-all test and an empty-queue drain test.
+
+**Resolution:** _(open)_

code-reviews/Worker/findings.md

@@ -0,0 +1,252 @@
+# Code Review — Worker
+
+| Field | Value |
+|---|---|
+| Module | `src/MxGateway.Worker` |
+| Reviewer | Claude Code |
+| Review date | 2026-05-18 |
+| Commit reviewed | `6c64030` |
+| Status | Reviewed |
+| Open findings | 15 |
+
+## Checklist coverage
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issues found: heartbeat loop sleeps before first beat (Worker-002), `ProcessCommandAsync` state race drops replies (Worker-003), watchdog/heartbeat state inconsistency (Worker-004), double-dispose path (Worker-006), plus Worker-010/011/015. |
+| 2 | mxaccessgw conventions | Issue found: Worker-007 (reflection-based COM invocation bypasses the typed interface contract). |
+| 3 | Concurrency & thread safety | Issues found: Worker-001 (`WnWrapAlarmConsumer` timer fires COM off the STA), Worker-008 (consumer factory STA-affinity not enforced). |
+| 4 | Error handling & resilience | Issue found: Worker-005 (`OnPoll` silently swallows all poll failures). |
+| 5 | Security | No secret logging (redaction applied); inbound frame validation reasonable. No issues found. |
+| 6 | Performance & resource management | Issue found: Worker-009 (per-frame `byte[]` allocations on the hot event path). COM release is correct. |
+| 7 | Design-document adherence | Code matches `WorkerSta.md`/`WorkerFrameProtocol.md`; stale alarm-path docs (Worker-012). |
+| 8 | Code organization & conventions | Issue found: Worker-014 (`AlarmCommandHandler.cs` declares two public types in one file). |
+| 9 | Testing coverage | Issue found: Worker-013 (`StaMessagePump` has no direct tests; poll-loop lifecycle untested). |
+| 10 | Documentation & comments | Issue found: Worker-012 (stale "future PR / A.3" comments now describe shipped code). |
+
+## Findings
+
+### Worker-001
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Concurrency & thread safety |
+| Location | `src/MxGateway.Worker/MxAccess/WnWrapAlarmConsumer.cs:204-207` |
+| Status | Open |
+
+**Description:** When constructed with `pollIntervalMilliseconds > 0`, `Subscribe` starts a `System.Threading.Timer` whose `OnPoll` callback runs `PollOnce()` — which calls `wwAlarmConsumerClass.GetXmlCurrentAlarms2` — on a thread-pool thread. The wnwrap CLSID is registered `ThreadingModel=Apartment`; calling its methods off the owning STA violates the hard rule that all COM calls happen on the dedicated STA thread, and can deadlock on cross-apartment marshaling when the STA is not pumping. The production path (default constructor, interval 0) is safe, but the public 3-arg constructor leaves this footgun callable, and tests/live-smoke use it.
+
+**Recommendation:** Remove the internal `Timer` entirely (production already drives `PollOnce` from the STA), or document and gate it so it can only be used from an STA thread. At minimum, make the timer-driven mode unreachable from any production wiring.
+
+**Resolution:** _(open)_
+
+### Worker-002
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Correctness & logic bugs |
+| Location | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:545-549` |
+| Status | Open |
+
+**Description:** `RunHeartbeatLoopAsync` calls `await Task.Delay(_sessionOptions.HeartbeatInterval, ...)` before sending the first heartbeat. The gateway therefore receives no heartbeat for the first full interval (default 5s) after the worker reaches `Ready`. If the gateway's liveness watchdog expects a heartbeat sooner, a healthy worker can be misclassified as hung at startup.
+
+**Recommendation:** Send an initial heartbeat immediately on entering the loop, or move the `Task.Delay` to the end of the loop body.
+
+**Resolution:** _(open)_
+
+### Worker-003
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Correctness & logic bugs |
+| Location | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:399-403`, `:416-419` |
+| Status | Open |
+
+**Description:** `ProcessCommandAsync` checks `_state` after `DispatchAsync` completes and silently `return`s without writing a `WorkerCommandReply` (or fault) when `_state` is not `Ready`/`ExecutingCommand`. `_state` is a plain field mutated from multiple tasks (heartbeat loop, event-drain loop, shutdown). A command that completes successfully while `_state` has transitioned will have its reply dropped with no diagnostic, and the gateway's correlation-id wait then hangs until its own timeout. The `_state` read is also not synchronized.
+
+**Recommendation:** Always attempt to write the reply/fault for an in-flight command, or explicitly reject in-flight commands with a `Canceled`/`WorkerUnavailable` reply during state transitions. Make `_state` access thread-safe (volatile or locked).
+
+**Resolution:** _(open)_
+
+### Worker-004
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Correctness & logic bugs |
+| Location | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:565-588` |
+| Status | Open |
+
+**Description:** After `ReportWatchdogFaultIfNeededAsync` sends an `StaHung` fault, the heartbeat loop continues sending normal heartbeats with `State` derived from `_state`, which the watchdog path never sets to `Faulted`. The heartbeat then keeps reporting a non-faulted state that contradicts the fault just sent.
+
+**Recommendation:** Set `_state = WorkerState.Faulted` (thread-safely) when the watchdog fault fires so heartbeat state and fault stay consistent.
+
+**Resolution:** _(open)_
+
+### Worker-005
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `src/MxGateway.Worker/MxAccess/WnWrapAlarmConsumer.cs:297-313` |
+| Status | Open |
+
+**Description:** `OnPoll` catches every exception from `PollOnce()` and discards it (`_ = ex;`). The production poll path (`MxAccessStaSession.RunAlarmPollLoopAsync` → `AlarmCommandHandler.PollOnce` → `AlarmDispatcher.PollOnce` → `consumer.PollOnce()`) has no fault recording either. A permanently failing alarm provider (e.g. `GetXmlCurrentAlarms2` returning `E_FAIL`, malformed XML throwing in `XmlDocument.LoadXml`) is therefore completely silent — no fault on the event queue, no log.
+
+**Recommendation:** Route poll failures to `MxAccessEventQueue.RecordFault` (or a logger) so a broken alarm subscription becomes observable. Update the now-stale comment.
+
+**Resolution:** _(open)_
+
+### Worker-006
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Correctness & logic bugs |
+| Location | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:117-124`, `src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs:386-491` |
+| Status | Open |
+
+**Description:** `RunAsync`'s `finally` calls `_runtimeSession?.Dispose()` unless `_shutdownTimedOut`. On the normal path `ShutdownGracefullyAsync` already disposed the STA runtime, so re-entering `Dispose()` is a harmless no-op only because `ShutdownGracefullyAsync` reached its end and set `disposed = true`. If `ShutdownGracefullyAsync` throws `TimeoutException` after partial teardown with `_shutdownTimedOut` set, the session is never disposed at all — the `finally` skips it — leaking the STA thread and COM object, leaving cleanup to rely solely on process exit.
+
+**Recommendation:** Make the dispose decision explicit and confirm process exit always follows a timed-out shutdown; otherwise dispose defensively. At minimum document why disposal is deliberately skipped on timeout.
+
+**Resolution:** _(open)_
+
+### Worker-007
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | mxaccessgw conventions |
+| Location | `src/MxGateway.Worker/MxAccess/MxAccessComServer.cs:130-150` |
+| Status | Open |
+
+**Description:** `Invoke` uses late-bound `Type.InvokeMember` reflection as a fallback when the COM object does not cast to `ILMXProxyServer*`. In production the object is always `LMXProxyServerClass`, so the reflection path exists only for test doubles — it is dead/untested code on the production path and obscures the interface contract. `params object[] arguments` also boxes value-type handles on every call.
+
+**Recommendation:** Drop the reflection fallback and require the COM object to implement the interface (tests can supply a typed fake), or clearly mark the fallback as test-only.
+
+**Resolution:** _(open)_
+
+### Worker-008
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Concurrency & thread safety |
+| Location | `src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs:205-249`, `:429-447` |
+| Status | Open |
+
+**Description:** `RunAlarmPollLoopAsync` correctly marshals `handler.PollOnce()` onto the STA via `staRuntime.InvokeAsync`, and the cancel/await/dispose ordering in `ShutdownGracefullyAsync` is sound. However, nothing enforces that the `consumerFactory` and all `IMxAccessAlarmConsumer` calls run on the STA thread; a future caller could break STA affinity silently.
+
+**Recommendation:** Add an assertion or documented invariant that the consumer factory and all `IMxAccessAlarmConsumer` calls run on the STA thread, mirroring the existing `MxAccessSession.CreationThreadId` pattern.
+
+**Resolution:** _(open)_
+
+### Worker-009
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Performance & resource management |
+| Location | `src/MxGateway.Worker/Ipc/WorkerFrameReader.cs:31,49`, `src/MxGateway.Worker/Ipc/WorkerFrameWriter.cs:57-58` |
+| Status | Open |
+
+**Description:** Every frame read allocates a fresh 4-byte length buffer and a payload `byte[]`; every write allocates `ToByteArray()` plus a 4-byte prefix. On the hot event-drain path (batches of up to 128 `WorkerEvent` frames every 25 ms) this produces steady gen-0 garbage. `WorkerFrameWriter` also effectively serializes twice (`CalculateSize()` then `ToByteArray()`).
+
+**Recommendation:** Reuse a pooled buffer / `ArrayPool<byte>` for the length prefix and payload, and write directly into a pooled buffer using `CodedOutputStream`. Low priority unless event throughput is high.
+
+**Resolution:** _(open)_
+
+### Worker-010
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `src/MxGateway.Worker/Conversion/VariantConverter.cs:204-226` |
+| Status | Open |
+
+**Description:** `ConvertInt64Scalar` is reached for `TypeCode.UInt32` and `TypeCode.Int64`. For a `uint` with `expectedDataType == MxDataType.Time`, the value is treated as a Windows `FILETIME` via `DateTime.FromFileTimeUtc(longValue)`; a 32-bit FILETIME is never a valid full FILETIME, so this silently produces a near-epoch timestamp rather than a raw/diagnostic value. Unlikely in practice but a silent misconversion.
+
+**Recommendation:** Only apply the `MxDataType.Time` FILETIME projection for 64-bit source types; for `uint` fall through to integer or raw.
+
+**Resolution:** _(open)_
+
+### Worker-011
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `src/MxGateway.Worker/Ipc/WorkerPipeClient.cs:169-171` |
+| Status | Open |
+
+**Description:** `retryAttempts` is computed as `(connectTimeout / min(connectTimeout, attemptTimeout)) - 1`. With defaults (30000 / 2000) this yields 14 retries, but each retry also incurs Polly exponential backoff. The overall `connectDeadline` (`CancelAfter(connectTimeout)`) is the real bound, so the computed attempt count can be larger or smaller than the time budget allows, and the formula is opaque.
+
+**Recommendation:** Drive retries purely off the `connectDeadline` token (Polly stops when cancelled) and drop the fragile attempt-count arithmetic, or add a comment explaining the intent.
+
+**Resolution:** _(open)_
+
+### Worker-012
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `src/MxGateway.Worker/MxAccess/MxAccessAlarmEventSink.cs:44-55`, `src/MxGateway.Worker/MxAccess/WnWrapAlarmConsumer.cs:38-43`, `src/MxGateway.Worker/MxAccess/MxAccessEventMapper.cs:106-112` |
+| Status | Open |
+
+**Description:** Multiple comments describe the alarm path as not-yet-wired future work ("PR A.2 — COM-side subscription scaffold … the worker advertises no alarm subscription", "the worker bootstrap will gain a thin 'run-on-STA' wrapper as part of A.3"). As of commit 6c64030 the alarm command handler, STA poll loop, and `SubscribeAlarms`/`AcknowledgeAlarm`/`QueryActiveAlarms` are all wired. These comments are stale and misleading.
+
+**Recommendation:** Update the XML docs/comments to describe the shipped behavior; remove the "future PR" framing.
+
+**Resolution:** _(open)_
+
+### Worker-013
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `src/MxGateway.Worker/Sta/StaMessagePump.cs` |
+| Status | Open |
+
+**Description:** `StaMessagePump` — the heart of COM event delivery (`MsgWaitForMultipleObjectsEx` + `PeekMessage`/`DispatchMessage`) — has no direct unit tests. `StaRuntimeTests` exercises it indirectly for command wake-up but never verifies that a posted Windows message actually wakes the wait and is dispatched, nor that `PumpPendingMessages` returns a correct count. The alarm poll-loop lifecycle in `MxAccessStaSession` (start/cancel/await on shutdown) also has no test. These are the most failure-sensitive paths in the module.
+
+**Recommendation:** Add tests that post a message to the STA thread and assert it is pumped, and tests covering alarm poll-loop start/stop and shutdown ordering.
+
+**Resolution:** _(open)_
+
+### Worker-014
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `src/MxGateway.Worker/MxAccess/AlarmCommandHandler.cs:33`, `:202` |
+| Status | Open |
+
+**Description:** The file declares two public types — the `AlarmCommandHandler` class and the `IAlarmCommandHandler` interface. The C# style guide and the rest of the module follow one-public-type-per-file (e.g. interfaces in their own `I*.cs` files like `IMxAccessAlarmConsumer.cs`).
+
+**Recommendation:** Move `IAlarmCommandHandler` to its own `IAlarmCommandHandler.cs` for consistency.
+
+**Resolution:** _(open)_
+
+### Worker-015
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `src/MxGateway.Worker/MxAccess/MxAccessEventQueue.cs:115-145` |
+| Status | Open |
+
+**Description:** On overflow, `Enqueue` records the overflow fault and throws `MxAccessEventQueueOverflowException`; `MxAccessBaseEventSink.EnqueueEvent` catches it and calls `RecordFault` again. `RecordFault` is a no-op when a fault already exists, so the second call is harmless — but the intent is muddled, and there is no test asserting the dropped-event behavior. This is acceptable per the fail-fast design but undocumented at the call site.
+
+**Recommendation:** Add a brief comment in `EnqueueEvent` clarifying that an overflow exception is expected and already self-records its fault, so the catch is intentionally a near no-op.
+
+**Resolution:** _(open)_

code-reviews/_template/findings.md

@@ -0,0 +1,53 @@
+# Code Review — <Module>
+
+<!-- Template for a per-module findings file. Copy to code-reviews/<Module>/findings.md.
+     See ../../REVIEW-PROCESS.md for the full process. The base README.md is generated
+     from these files by regen-readme.py — do not edit README.md by hand. -->
+
+| Field | Value |
+|---|---|
+| Module | `src/MxGateway.<Module>` |
+| Reviewer | <name> |
+| Review date | <YYYY-MM-DD> |
+| Commit reviewed | `<short-sha>` |
+| Status | Not started |
+| Open findings | 0 |
+
+## Checklist coverage
+
+A comprehensive review completes every category, recording "No issues found" where
+a category produced nothing rather than leaving it blank.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | _pending_ |
+| 2 | mxaccessgw conventions | _pending_ |
+| 3 | Concurrency & thread safety | _pending_ |
+| 4 | Error handling & resilience | _pending_ |
+| 5 | Security | _pending_ |
+| 6 | Performance & resource management | _pending_ |
+| 7 | Design-document adherence | _pending_ |
+| 8 | Code organization & conventions | _pending_ |
+| 9 | Testing coverage | _pending_ |
+| 10 | Documentation & comments | _pending_ |
+
+## Findings
+
+<!-- One ### entry per finding. IDs are <Module>-NNN, sequential within the module,
+     never reused. Findings are never deleted — close them by changing Status and
+     completing Resolution. -->
+
+### <Module>-001
+
+| Field | Value |
+|---|---|
+| Severity | Critical / High / Medium / Low |
+| Category | one of the 10 checklist categories |
+| Location | `path/to/File.cs:NN` |
+| Status | Open / In Progress / Resolved / Won't Fix / Deferred |
+
+**Description:** What is wrong and why it matters.
+
+**Recommendation:** Concrete suggested fix.
+
+**Resolution:** _(empty until closed; on close, record the fixing commit SHA, the date, and a one-line description of the fix)_

code-reviews/prompt.md

@@ -0,0 +1,76 @@
+# Prompt — resolve open code-review findings
+
+Reusable orchestration prompt for clearing the `code-reviews/` backlog. Paste it
+to a fresh agent when you want the remaining findings worked through.
+
+---
+
+Resolve all open code-review findings (every severity), following the same
+workflow already used to resolve the Critical dashboard finding and the
+Client.Rust module (see git commits `a8aafdf`, `0d8a28d`, `9082e50`).
+
+## Setup
+
+- Read `code-reviews/README.md` for the open findings and `REVIEW-PROCESS.md`
+  for the workflow. Group the open findings by module.
+- A module is one folder under `code-reviews/` — a `src/MxGateway.*` project or
+  a `clients/` language client. The module→source mapping and the per-module
+  build/test commands are in `CLAUDE.md` (the "Source Update Workflow" table and
+  the per-client commands).
+
+## Dispatch — one general-purpose subagent per module, in batches of ~5 modules
+
+Each subagent, for every open finding in its assigned module, must:
+
+- Verify the finding's root cause against the actual source. Do NOT trust the
+  finding text — if it is wrong or misclassified, re-triage it (correct the
+  severity/description in that module's `findings.md`) instead of forcing a fix.
+- Use real TDD: write the regression test FIRST and run it to confirm it fails,
+  THEN implement the root-cause fix, THEN confirm it passes. (Do not use
+  `git stash` — parallel agents would race on the shared stash stack.)
+- Run that module's full build and test suite with the module-appropriate
+  toolchain and confirm it is green:
+  - `src/MxGateway.*` .NET projects — `dotnet build` + `dotnet test` for the
+    project; the Worker must build x86 (`-p:Platform=x86`).
+  - `clients/dotnet` — `dotnet build clients/dotnet/MxGateway.Client.sln` and its tests.
+  - `clients/go` — `gofmt`, `go build ./...`, `go test ./...`.
+  - `clients/rust` — `cargo fmt`, `cargo test --workspace`,
+    `cargo clippy --workspace --all-targets -- -D warnings`.
+  - `clients/python` — `python -m pytest`.
+  - `clients/java` — `gradle test`.
+- A regression test for a gateway-server finding belongs in `src/MxGateway.Tests`;
+  for a worker finding, in `src/MxGateway.Worker.Tests`. Adding a test there is
+  permitted even though it is a different module's source tree.
+- Update only that module's `code-reviews/<Module>/findings.md`: set each
+  resolved finding's Status to `Resolved` with a Resolution note describing the
+  fix (the orchestrator appends the fixing commit SHA), and update the header
+  "Open findings" count.
+- CONSTRAINTS: edit only the source and test files needed for the assigned
+  module's findings, plus that module's own `findings.md`. Do NOT edit
+  `code-reviews/README.md`. Do NOT commit. Do NOT touch another module's
+  `findings.md`.
+- Report a summary: each finding — root-cause confirmation, the fix, test names,
+  and any re-triage.
+
+Batch so that no two subagents in the same batch write to the same test project
+— e.g. do not run the `Server` and `Contracts` agents together, since both add
+regression tests under `src/MxGateway.Tests`.
+
+## After each batch returns (orchestrator does this — keep your own context lean)
+
+- Build and test every component the batch touched, using the `CLAUDE.md`
+  commands; confirm clean. For any .NET change, `dotnet build src/MxGateway.sln`.
+- Commit per module — one commit per module, message referencing the finding
+  IDs. Record the fixing commit SHA in each finding's Resolution.
+- Regenerate the index: `python code-reviews/regen-readme.py`, then
+  `python code-reviews/regen-readme.py --check` to confirm it is consistent;
+  stage `code-reviews/README.md`. (Use `python` — the bare `python3` alias on
+  this box resolves to the Windows Store stub and fails.) You may stage
+  `README.md` with each module's commit, or commit it once per batch after the
+  script runs.
+- Push.
+
+## Continue
+
+Continue batch by batch until all findings are Resolved or re-triaged. If a
+finding needs a design decision, skip it and surface it rather than guessing.

code-reviews/regen-readme.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""Regenerate code-reviews/README.md from the per-module findings.md files.
+
+The per-module findings.md files are the source of truth. This script aggregates
+them into the single cross-module README.md (module status + pending/closed
+finding tables).
+
+Usage:
+    python code-reviews/regen-readme.py          # rewrite README.md
+    python code-reviews/regen-readme.py --check  # exit 1 if stale or inconsistent
+
+`--check` fails when README.md is out of date OR when a module's header
+`Open findings` count disagrees with its finding statuses, or a finding
+carries an unrecognised Status value.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+README = ROOT / "README.md"
+
+PENDING_STATUSES = {"Open", "In Progress"}
+KNOWN_STATUSES = {"Open", "In Progress", "Resolved", "Won't Fix", "Deferred"}
+SEVERITY_ORDER = {"Critical": 0, "High": 1, "Medium": 2, "Low": 3}
+
+GENERATED_NOTE = (
+    "<!-- GENERATED FILE - do not edit by hand. "
+    "Regenerate with: python code-reviews/regen-readme.py -->"
+)
+
+
+def cell(value: str) -> str:
+    """Escape a value for safe inclusion in a markdown table cell."""
+    return value.replace("|", "\\|").strip()
+
+
+def summarize(value: str, limit: int = 240) -> str:
+    """Trim a long description to a single-cell-friendly summary."""
+    value = value.strip()
+    if len(value) <= limit:
+        return value
+    return value[: limit - 1].rstrip() + "…"
+
+
+def first_table(text: str) -> dict[str, str]:
+    """Parse the first contiguous block of '| key | value |' rows into a dict."""
+    rows: dict[str, str] = {}
+    started = False
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("|"):
+            started = True
+            cells = [c.strip() for c in stripped.strip("|").split("|")]
+            if len(cells) >= 2:
+                key, value = cells[0], cells[1]
+                if key and not set(key) <= {"-", ":"} and key != "Field":
+                    rows[key] = value
+        elif started:
+            break
+    return rows
+
+
+def parse_module(findings_path: Path) -> dict:
+    """Parse one module's findings.md into its header and finding list."""
+    text = findings_path.read_text(encoding="utf-8")
+    module = findings_path.parent.name
+    parts = re.split(r"^##\s+Findings\s*$", text, maxsplit=1, flags=re.M)
+    header = first_table(parts[0])
+    findings: list[dict] = []
+    if len(parts) > 1:
+        for chunk in re.split(r"^###\s+", parts[1], flags=re.M)[1:]:
+            fid = chunk.splitlines()[0].strip()
+            tbl = first_table(chunk)
+            desc_m = re.search(
+                r"\*\*Description:\*\*\s*(.*?)(?=\n\*\*|\Z)", chunk, re.S
+            )
+            desc = re.sub(r"\s+", " ", desc_m.group(1)).strip() if desc_m else ""
+            findings.append(
+                {
+                    "id": fid,
+                    "severity": tbl.get("Severity", ""),
+                    "category": tbl.get("Category", ""),
+                    "location": tbl.get("Location", ""),
+                    "status": tbl.get("Status", ""),
+                    "description": desc,
+                }
+            )
+    return {"module": module, "header": header, "findings": findings}
+
+
+def build_readme(modules: list[dict]) -> str:
+    modules = sorted(modules, key=lambda m: m["module"])
+    all_findings = [
+        dict(f, module=m["module"]) for m in modules for f in m["findings"]
+    ]
+    pending = [f for f in all_findings if f["status"] in PENDING_STATUSES]
+    closed = [
+        f
+        for f in all_findings
+        if f["status"] and f["status"] not in PENDING_STATUSES
+    ]
+
+    def sev_key(f: dict) -> tuple:
+        return (SEVERITY_ORDER.get(f["severity"], 9), f["id"])
+
+    pending.sort(key=sev_key)
+    closed.sort(key=sev_key)
+
+    out: list[str] = [
+        "# Code Reviews",
+        "",
+        GENERATED_NOTE,
+        "",
+        "Cross-module code review index for the `mxaccessgw` codebase. The review "
+        "process is defined in [../REVIEW-PROCESS.md](../REVIEW-PROCESS.md).",
+        "",
+        "Each module's `findings.md` is the source of truth; this file is generated "
+        "from them by `regen-readme.py` and must not be edited by hand.",
+        "",
+        "## Module status",
+        "",
+        "| Module | Reviewer | Date | Commit | Status | Open | Total |",
+        "|---|---|---|---|---|---|---|",
+    ]
+    for m in modules:
+        h = m["header"]
+        open_n = sum(
+            1 for f in m["findings"] if f["status"] in PENDING_STATUSES
+        )
+        out.append(
+            f"| [{m['module']}]({m['module']}/findings.md) "
+            f"| {cell(h.get('Reviewer', ''))} "
+            f"| {cell(h.get('Review date', ''))} "
+            f"| {cell(h.get('Commit reviewed', ''))} "
+            f"| {cell(h.get('Status', ''))} "
+            f"| {open_n} | {len(m['findings'])} |"
+        )
+
+    out += ["", "## Pending findings", ""]
+    out.append(
+        "Findings with status `Open` or `In Progress`, ordered by severity."
+    )
+    out.append("")
+    if pending:
+        out.append("| ID | Severity | Category | Location | Description |")
+        out.append("|---|---|---|---|---|")
+        for f in pending:
+            out.append(
+                f"| {cell(f['id'])} | {cell(f['severity'])} "
+                f"| {cell(f['category'])} | {cell(f['location'])} "
+                f"| {cell(summarize(f['description']))} |"
+            )
+    else:
+        out.append("_No pending findings._")
+
+    out += ["", "## Closed findings", ""]
+    out.append("Findings with status `Resolved`, `Won't Fix`, or `Deferred`.")
+    out.append("")
+    if closed:
+        out.append("| ID | Severity | Status | Category | Location |")
+        out.append("|---|---|---|---|---|")
+        for f in closed:
+            out.append(
+                f"| {cell(f['id'])} | {cell(f['severity'])} "
+                f"| {cell(f['status'])} | {cell(f['category'])} "
+                f"| {cell(f['location'])} |"
+            )
+    else:
+        out.append("_No closed findings._")
+
+    return "\n".join(out) + "\n"
+
+
+def find_inconsistencies(modules: list[dict]) -> list[str]:
+    """Return human-readable problems in the per-module findings.md files.
+
+    Checks that each module header's `Open findings` count agrees with its
+    finding statuses, and that every finding carries a known Status value.
+    """
+    issues: list[str] = []
+    for m in modules:
+        open_n = sum(
+            1 for f in m["findings"] if f["status"] in PENDING_STATUSES
+        )
+        declared = m["header"].get("Open findings", "").strip()
+        if declared != str(open_n):
+            issues.append(
+                f"{m['module']}: header 'Open findings' = '{declared}' but "
+                f"{open_n} finding(s) are Open/In Progress"
+            )
+        for f in m["findings"]:
+            if f["status"] not in KNOWN_STATUSES:
+                issues.append(
+                    f"{m['module']}: finding {f['id']} has unrecognised "
+                    f"Status '{f['status']}'"
+                )
+    return issues
+
+
+def main(argv: list[str]) -> int:
+    check = "--check" in argv[1:]
+    module_dirs = sorted(
+        d
+        for d in ROOT.iterdir()
+        if d.is_dir() and d.name != "_template" and (d / "findings.md").is_file()
+    )
+    modules = [parse_module(d / "findings.md") for d in module_dirs]
+    content = build_readme(modules)
+    issues = find_inconsistencies(modules)
+    if check:
+        stale = (
+            README.read_text(encoding="utf-8") if README.exists() else ""
+        ) != content
+        for issue in issues:
+            print(f"inconsistent: {issue}", file=sys.stderr)
+        if stale:
+            print(
+                "code-reviews/README.md is stale - run regen-readme.py",
+                file=sys.stderr,
+            )
+        if stale or issues:
+            return 1
+        print("code-reviews/README.md is up to date and consistent.")
+        return 0
+    for issue in issues:
+        print(f"warning: {issue}", file=sys.stderr)
+    README.write_text(content, encoding="utf-8", newline="\n")
+    print(f"Wrote {README} ({len(modules)} modules).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

code-reviews/test_regen_readme.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Tests for regen-readme.py.
+
+Dependency-free: run with `python code-reviews/test_regen_readme.py`.
+Exits 0 if all tests pass, 1 otherwise.
+"""
+from __future__ import annotations
+
+import importlib.util
+import tempfile
+import traceback
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+
+# regen-readme.py is not an importable module name (hyphen), so load it by path.
+_spec = importlib.util.spec_from_file_location("regen_readme", HERE / "regen-readme.py")
+regen = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(regen)
+
+FIXTURE = """# Code Review — Demo
+
+| Field | Value |
+|---|---|
+| Module | `src/Demo` |
+| Reviewer | Tester |
+| Review date | 2026-05-18 |
+| Commit reviewed | `abc1234` |
+| Status | Reviewed |
+| Open findings | 1 |
+
+## Findings
+
+### Demo-001
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Security |
+| Location | `src/Demo/File.cs:10` |
+| Status | Open |
+
+**Description:** A first problem that matters.
+
+**Recommendation:** Fix it.
+
+**Resolution:** _(open)_
+
+### Demo-002
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `src/Demo/File.cs:20` |
+| Status | Resolved |
+
+**Description:** A second, minor problem.
+
+**Recommendation:** Tidy it.
+
+**Resolution:** Fixed in def5678 on 2026-05-18.
+"""
+
+
+def _parse_fixture() -> dict:
+    """Write FIXTURE to a temp Demo/findings.md and parse it."""
+    with tempfile.TemporaryDirectory() as tmp:
+        path = Path(tmp) / "Demo" / "findings.md"
+        path.parent.mkdir()
+        path.write_text(FIXTURE, encoding="utf-8")
+        return regen.parse_module(path)
+
+
+def test_first_table_skips_separator_and_field_header():
+    table = regen.first_table("| Field | Value |\n|---|---|\n| Severity | High |\n")
+    assert table == {"Severity": "High"}, table
+
+
+def test_parse_module_header():
+    m = _parse_fixture()
+    assert m["module"] == "Demo", m["module"]
+    assert m["header"]["Reviewer"] == "Tester"
+    assert m["header"]["Status"] == "Reviewed"
+    assert m["header"]["Open findings"] == "1"
+
+
+def test_parse_module_findings():
+    m = _parse_fixture()
+    assert len(m["findings"]) == 2, len(m["findings"])
+    first = m["findings"][0]
+    assert first["id"] == "Demo-001"
+    assert first["severity"] == "High"
+    assert first["category"] == "Security"
+    assert first["location"] == "`src/Demo/File.cs:10`"
+    assert first["status"] == "Open"
+    assert first["description"] == "A first problem that matters."
+    assert m["findings"][1]["status"] == "Resolved"
+
+
+def test_build_readme_splits_pending_and_closed():
+    readme = regen.build_readme([_parse_fixture()])
+    assert "## Pending findings" in readme
+    assert "## Closed findings" in readme
+    pending, closed = readme.split("## Closed findings", 1)
+    assert "Demo-001" in pending  # Open -> pending
+    assert "Demo-001" not in closed
+    assert "Demo-002" in closed  # Resolved -> closed
+    assert "_No pending findings._" not in pending
+
+
+def test_find_inconsistencies_clean_fixture():
+    assert regen.find_inconsistencies([_parse_fixture()]) == []
+
+
+def test_find_inconsistencies_detects_wrong_open_count():
+    m = _parse_fixture()
+    m["header"]["Open findings"] = "7"
+    issues = regen.find_inconsistencies([m])
+    assert len(issues) == 1 and "Open findings" in issues[0], issues
+
+
+def test_find_inconsistencies_detects_unknown_status():
+    m = _parse_fixture()
+    m["findings"][0]["status"] = "Bogus"
+    issues = regen.find_inconsistencies([m])
+    # Wrong status also shifts the open count, so expect the status issue present.
+    assert any("unrecognised Status" in i for i in issues), issues
+
+
+def test_summarize_truncates_long_text():
+    long = "x" * 500
+    out = regen.summarize(long)
+    assert len(out) <= 240 and out.endswith("…"), len(out)
+    assert regen.summarize("short") == "short"
+
+
+def main() -> int:
+    tests = sorted(
+        (name, fn)
+        for name, fn in globals().items()
+        if name.startswith("test_") and callable(fn)
+    )
+    failed = 0
+    for name, fn in tests:
+        try:
+            fn()
+            print(f"PASS {name}")
+        except Exception:  # noqa: BLE001 - test runner reports all failures
+            failed += 1
+            print(f"FAIL {name}")
+            traceback.print_exc()
+    print(f"\n{len(tests) - failed}/{len(tests)} passed.")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

docs/Authentication.md

@@ -223,6 +223,10 @@ constraints remain fully unconstrained after migration.
 
 Key ids are restricted by the parser to ASCII letters, digits, periods, and hyphens so they remain safe to embed in the token format and in URL paths used by administrative tooling.
 
+The CLI is not the only management surface: the dashboard API Keys page
+creates, rotates, and revokes keys through the same `IApiKeyAdminStore`. See
+[Gateway Dashboard Design](./GatewayDashboardDesign.md#api-keys-page).
+
 ## Scope Serialization
 
 Scopes are persisted as a single TEXT column rather than a join table because the set is small, never queried by membership at the database level, and changes atomically with the owning row. `ApiKeyScopeSerializer.Serialize` writes a JSON array sorted with `StringComparer.Ordinal` so equivalent scope sets produce byte-identical column values, which makes audit diffing and database comparisons deterministic:
@@ -276,4 +280,5 @@ Singletons are safe because each operation opens its own short-lived `SqliteConn
 
 - [Gateway Configuration](./GatewayConfiguration.md)
 - [Authorization](./Authorization.md)
+- [Gateway Dashboard Design](./GatewayDashboardDesign.md)
 - [Diagnostics](./Diagnostics.md)

docs/Authorization.md

@@ -161,6 +161,12 @@ Glob matching is anchored, case-insensitive, and supports `*` and `?`.
 Subtree and tag glob lists are alternatives: matching either list allows that
 scope dimension. Empty lists mean unconstrained for that dimension.
 
+Constraints are set when a key is created — through the `apikey create-key`
+flags (see [Authentication](./Authentication.md)) or the dashboard API Keys
+page create dialog (see
+[Gateway Dashboard Design](./GatewayDashboardDesign.md#api-keys-page)). The
+dashboard API Keys page also renders each key's effective constraints.
+
 The service checks read constraints for `AddItem`, `AddItem2`, `AddItemBulk`,
 `SubscribeBulk`, and `AdviseItemBulk`. It checks write constraints for
 `Write`, `Write2`, `WriteSecured`, and `WriteSecured2`. Successful item
@@ -252,6 +258,7 @@ Singleton lifetimes are appropriate because none of the three classes hold per-r
 ## Related Documentation
 
 - [Authentication](./Authentication.md)
+- [Gateway Dashboard Design](./GatewayDashboardDesign.md)
 - [Grpc](./Grpc.md)
 - [GatewayConfiguration](./GatewayConfiguration.md)
 - [Galaxy Repository Browse](./GalaxyRepository.md)

docs/GatewayDashboardDesign.md

@@ -49,6 +49,7 @@ Endpoint layout:
 /dashboard/workers
 /dashboard/events
 /dashboard/galaxy
+/dashboard/apikeys
 /dashboard/settings
 /dashboard/_blazor
 ```
@@ -83,6 +84,7 @@ MxGateway.Server
         SessionDetailsPage.razor
         WorkersPage.razor
         EventsPage.razor
+        ApiKeysPage.razor
         SettingsPage.razor
       Shared/
         MetricCard.razor
@@ -91,6 +93,9 @@ MxGateway.Server
     DashboardSnapshotService.cs
     DashboardAuthorizationHandler.cs
     DashboardAuthenticator.cs
+    DashboardApiKeyAuthorization.cs
+    DashboardApiKeyManagementService.cs
+    DashboardApiKeySummary.cs
     DashboardSnapshot.cs
     DashboardSessionSummary.cs
     DashboardWorkerSummary.cs
@@ -249,6 +254,52 @@ Show aggregate event diagnostics:
 Do not display full tag values by default. If value display is later added, make
 it opt-in and redacted.
 
+### API keys page
+
+`/dashboard/apikeys` lists the gateway's API keys and, for authorized
+operators, manages them. It reads key metadata through the same
+`IApiKeyAdminStore` the `apikey` CLI uses, so the dashboard and the CLI act
+on one source of truth.
+
+The table shows one row per key:
+
+- key id,
+- status (`Active` or `Revoked`),
+- display name,
+- scopes,
+- constraints (rendered as `unconstrained` when none are set),
+- created timestamp,
+- last-used timestamp.
+
+Key secrets are never listed. Only the peppered hash is stored, and the page
+never reconstructs a key. See [Authorization](./Authorization.md#constraint-enforcement)
+for what each constraint means and how it is enforced on the gRPC path.
+
+#### Management actions
+
+Create, Rotate, and Revoke controls render only when the signed-in user is
+authorized. `DashboardApiKeyAuthorization.CanManage` requires an authenticated
+principal that is a member of the LDAP `MxGateway:Ldap:RequiredGroup` — the
+same group the dashboard login enforces. An anonymous localhost viewer can read
+the table but sees no action controls.
+
+- **Create** opens a dialog for the key id, display name, scope checkboxes
+  (the `GatewayScopes` catalog), and the optional constraint fields: read and
+  write subtrees, read and write tag globs, browse subtrees, max write
+  classification, and the read-alarm-only / read-historized-only flags.
+- **Rotate** issues a new secret for an existing key id and invalidates the
+  old one.
+- **Revoke** marks a key revoked; a revoked key cannot be un-revoked.
+
+Create and Rotate return the assembled `mxgw_<keyId>_<secret>` token **once**,
+in a one-time banner. It is never shown again, so the operator must copy it
+immediately. This mirrors the `apikey create-key` / `rotate-key` CLI.
+
+Every management action appends an `api_key_audit` entry
+(`dashboard-create-key`, `dashboard-rotate-key`, `dashboard-revoke-key`) with
+the key id and the caller's remote address. Secrets and pepper values are never
+logged.
+
 ### Settings page
 
 Show read-only effective configuration:

glauth.md

@@ -0,0 +1,260 @@
+# GLAuth — LDAP authn reference for mxaccessgw
+
+GLAuth is a lightweight LDAP server installed on this dev box at
+`C:\publish\glauth\` and run as a Windows service via NSSM. It already
+backs the LmxOpcUa OPC UA server's UserName-token authn and the LmxOpcUa
+Admin UI's cookie login; this doc captures everything mxaccessgw needs
+to consume the same directory so a single set of dev credentials covers
+both stacks.
+
+The authoritative copy of LmxOpcUa's reference lives at
+`C:\publish\glauth\auth.md`. This doc is a redistilled view tailored to
+mxaccessgw — what users + groups are already provisioned, how to bind
+against them, and what's needed to add a gw-specific role.
+
+## Connection details
+
+| Setting | Value |
+|---|---|
+| Protocol | LDAP (unencrypted) |
+| Host | `localhost` |
+| Port | `3893` |
+| LDAPS | disabled in dev (set `[ldaps]` block to enable) |
+| Base DN | `dc=lmxopcua,dc=local` |
+| Bind DN format | `cn={username},dc=lmxopcua,dc=local` |
+| Group OU | `ou=<groupname>,ou=groups,dc=lmxopcua,dc=local` |
+| Failed-bind throttle | 3 fails → 10-minute IP lockout (per `[behaviors]`) |
+
+## Pre-existing groups (LmxOpcUa role taxonomy)
+
+These map cleanly onto MxAccess capability boundaries — mxaccessgw
+should reuse them rather than define parallel groups so an operator with
+LmxOpcUa write rights doesn't need a second account for the gw.
+
+| Group | GID | DN | LmxOpcUa meaning | Suggested mxgw mapping |
+|---|---|---|---|---|
+| ReadOnly | 5501 | `ou=ReadOnly,ou=groups,dc=lmxopcua,dc=local` | Browse + read OPC UA nodes | `Browse` + `Subscribe` (read paths only) |
+| WriteOperate | 5502 | `ou=WriteOperate,ou=groups,dc=lmxopcua,dc=local` | Write FreeAccess / Operate attrs | `Write` (plain) |
+| WriteTune | 5504 | `ou=WriteTune,ou=groups,dc=lmxopcua,dc=local` | Write Tune attrs | `WriteSecured` (Tune only) |
+| WriteConfigure | 5505 | `ou=WriteConfigure,ou=groups,dc=lmxopcua,dc=local` | Write Configure attrs | `WriteSecured` (Configure) |
+| AlarmAck | 5503 | `ou=AlarmAck,ou=groups,dc=lmxopcua,dc=local` | Acknowledge alarms | gw alarm-ack RPC, when added |
+
+**A user can be in multiple groups** — `othergroups = [...]` in the
+config is a list. `admin` is the canonical example (in every role
+group below).
+
+## Pre-provisioned users
+
+| Username | Password | UID | Primary group | Other groups | Capabilities |
+|---|---|---|---|---|---|
+| `readonly` | `readonly123` | 5001 | ReadOnly | — | Browse, read |
+| `writeop` | `writeop123` | 5002 | WriteOperate | — | + plain Write |
+| `writetune` | `writetune123` | 5005 | WriteTune | — | + WriteSecured (Tune) |
+| `writeconfig` | `writeconfig123` | 5006 | WriteConfigure | — | + WriteSecured (Configure) |
+| `alarmack` | `alarmack123` | 5003 | AlarmAck | — | Alarm acknowledgment |
+| `admin` | `admin123` | 5004 | ReadOnly | WriteOperate, AlarmAck, WriteTune, WriteConfigure | All roles |
+| `serviceaccount` | `serviceaccount123` | 5999 | ReadOnly | — | LDAP search capability (for bind-then-search) |
+
+For mxaccessgw dev, `admin` covers every gw-side capability test;
+`readonly` is the right "negative" case for proving Browse-OK /
+Write-denied.
+
+## Two bind patterns
+
+### 1. Direct bind (simplest)
+
+```
+DN:       cn=admin,dc=lmxopcua,dc=local
+Password: admin123
+```
+
+Construct the DN from the username; bind. Works on GLAuth because
+`backend.nameformat = "cn"` and `groupformat = "ou"` are set in the
+config. **Doesn't translate to Active Directory** — AD users are keyed
+by `sAMAccountName`, not `cn`. Use this only for dev convenience.
+
+### 2. Bind-then-search (production-grade)
+
+```
+1. Bind as the service account (cn=serviceaccount,dc=lmxopcua,dc=local
+   / serviceaccount123).
+2. Search under dc=lmxopcua,dc=local with filter
+   (uid=<entered-username>) — or any attribute the deployment
+   identifies users by. GLAuth populates uid + cn.
+3. Read the returned entry's DN + memberOf list (groups).
+4. Bind again as the discovered DN with the entered password. If that
+   succeeds, authn passes; the memberOf values become the role set.
+```
+
+The second bind is the actual password check — the search is just a DN
+discovery. This is the AD-friendly path: AD's
+`tokenGroups` / `LDAP_MATCHING_RULE_IN_CHAIN` flatten nested groups, but
+that's an enhancement, not required for first-pass dev.
+
+LmxOpcUa's `Server/Security/LdapUserAuthenticator.cs` ships a working
+implementation of this pattern using `Novell.Directory.Ldap.NETStandard`
+v3.6.0 — copy the bind-then-search loop from there if mxaccessgw wants
+to avoid re-deriving the LDAP escape-string handling.
+
+## Suggested mxgw configuration shape
+
+A YAML/JSON section for mxaccessgw that mirrors LmxOpcUa's `LdapOptions`
+record:
+
+```yaml
+ldap:
+  enabled: true
+  server: localhost
+  port: 3893
+  useTls: false
+  allowInsecureLdap: true       # dev only
+  searchBase: "dc=lmxopcua,dc=local"
+  serviceAccountDn: "cn=serviceaccount,dc=lmxopcua,dc=local"
+  serviceAccountPassword: "serviceaccount123"
+  userNameAttribute: "uid"      # GLAuth populates this; AD uses sAMAccountName
+  displayNameAttribute: "cn"
+  groupAttribute: "memberOf"
+  groupToRole:
+    ReadOnly: "Browse"
+    WriteOperate: "Write"
+    WriteTune: "WriteSecured"
+    WriteConfigure: "WriteSecured"
+    AlarmAck: "AlarmAck"
+```
+
+`groupAttribute` returns full DNs like
+`ou=ReadOnly,ou=groups,dc=lmxopcua,dc=local` — the authenticator
+should strip the leading `ou=` (or `cn=` against AD) RDN value and
+look that up in `groupToRole`.
+
+## Adding a gw-specific group (when reuse isn't enough)
+
+If mxaccessgw needs a permission that doesn't fit the existing five
+roles (e.g. `GwAdmin` for shutdown/recycle commands), add it to
+GLAuth rather than running a separate LDAP server:
+
+1. Edit `C:\publish\glauth\glauth.cfg`
+2. Append:
+
+```toml
+[[groups]]
+  name = "GwAdmin"
+  gidnumber = 5510              # pick the next free GID
+```
+
+3. Add the group to whichever existing user(s) should have it via
+   `othergroups = [..., 5510]`. Or create a new user:
+
+```toml
+[[users]]
+  name = "gwadmin"
+  givenname = "Gateway"
+  sn = "Admin"
+  mail = "gwadmin@lmxopcua.local"
+  uidnumber = 5010
+  primarygroup = 5510
+  passsha256 = "<sha256 of the password — see below>"
+```
+
+4. `nssm restart GLAuth`
+
+Generate `passsha256` from a plaintext password:
+
+```powershell
+# Windows / PowerShell
+$bytes = [System.Text.Encoding]::UTF8.GetBytes("yourpassword")
+$hash  = [System.Security.Cryptography.SHA256]::Create().ComputeHash($bytes)
+-join ($hash | ForEach-Object { $_.ToString("x2") })
+```
+
+```bash
+# WSL / git-bash
+echo -n "yourpassword" | openssl dgst -sha256
+```
+
+## Quick verification
+
+From mxaccessgw's dev box, prove the directory is reachable:
+
+```powershell
+# Plain bind via PowerShell + System.DirectoryServices.Protocols
+$ldap = New-Object System.DirectoryServices.Protocols.LdapConnection("localhost:3893")
+$ldap.AuthType = [System.DirectoryServices.Protocols.AuthType]::Basic
+$ldap.SessionOptions.ProtocolVersion = 3
+$ldap.SessionOptions.SecureSocketLayer = $false
+$cred = New-Object System.Net.NetworkCredential("cn=admin,dc=lmxopcua,dc=local","admin123")
+$ldap.Bind($cred)
+"Bind OK"
+```
+
+Or via `ldapsearch` if you have OpenLDAP CLI tools:
+
+```bash
+ldapsearch -x -H ldap://localhost:3893 \
+  -D "cn=admin,dc=lmxopcua,dc=local" -w admin123 \
+  -b "dc=lmxopcua,dc=local" "(uid=admin)"
+```
+
+The response should list `admin`'s entry with `memberOf` populated for
+all five role groups.
+
+## Service management
+
+```powershell
+# Status / start / stop / restart
+nssm status  GLAuth
+nssm start   GLAuth
+nssm stop    GLAuth
+nssm restart GLAuth
+
+# Inspect what NSSM was told to launch
+nssm get GLAuth Parameters
+```
+
+Logs:
+
+| File | Purpose |
+|---|---|
+| `C:\publish\glauth\logs\stdout.log` | Bind events, search responses |
+| `C:\publish\glauth\logs\stderr.log` | Startup errors, config parse failures |
+
+After editing `glauth.cfg`, always tail `stderr.log` after the restart
+to catch a fat-fingered TOML before it bites at first bind:
+
+```powershell
+nssm restart GLAuth
+Get-Content C:\publish\glauth\logs\stderr.log -Tail 20 -Wait
+```
+
+## Active Directory migration cheat-sheet
+
+LmxOpcUa's `LdapOptions` xml-doc captures the AD overrides; same set
+applies to mxaccessgw verbatim. Keys that change:
+
+| Field | GLAuth dev value | AD production value |
+|---|---|---|
+| `Server` | `localhost` | a domain controller FQDN, or the domain itself |
+| `Port` | `3893` | `636` (LDAPS) — AD increasingly rejects plain bind under LDAP-signing enforcement |
+| `UseTls` | `false` | `true` |
+| `AllowInsecureLdap` | `true` | `false` |
+| `SearchBase` | `dc=lmxopcua,dc=local` | `DC=corp,DC=example,DC=com` |
+| `ServiceAccountDn` | `cn=serviceaccount,dc=lmxopcua,dc=local` | `CN=MxGwSvc,OU=Service Accounts,DC=corp,...` |
+| `UserNameAttribute` | `uid` | `sAMAccountName` (or `userPrincipalName`) |
+| `GroupAttribute` | `memberOf` (unchanged) | `memberOf` (unchanged) |
+
+`memberOf` returns full DNs; the authenticator strips the leading
+`CN=` value and uses it as the lookup key in `groupToRole`. Nested
+groups are **not** auto-expanded; either flatten in the directory or
+add a `tokenGroups` query as an enhancement.
+
+## Security notes for production
+
+- **Plaintext passwords in `glauth.cfg` are dev-only.** The config is
+  unencrypted on disk; anyone with read access to `C:\publish\glauth\`
+  can SHA256-rainbow-table the entries. Treat the dev creds as
+  throwaway. Production LDAP is Active Directory.
+- The 3-fail / 10-minute lockout is per source IP, not per user — a
+  shared NAT can lock out a whole office. Tunable in `[behaviors]`.
+- LDAPS isn't enabled in dev; binding sends passwords cleartext on the
+  wire. Fine for `localhost`, never expose port 3893 off-box without
+  enabling TLS first.

scripts/check-code-reviews-readme.ps1

@@ -0,0 +1,20 @@
+# Verifies code-reviews/README.md is regenerated from, and consistent with, the
+# per-module findings.md files. Intended as a CI / pre-commit gate.
+#
+# Exits non-zero when README.md is stale, when a module header's "Open findings"
+# count disagrees with its finding statuses, or when a finding carries an
+# unrecognised Status value. See REVIEW-PROCESS.md section 5.
+
+[CmdletBinding()]
+param()
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$repoRoot = Resolve-Path (Join-Path $PSScriptRoot "..")
+$script = Join-Path $repoRoot "code-reviews/regen-readme.py"
+
+# The bare `python3` alias on this platform resolves to the Windows Store stub;
+# `python` is the real interpreter.
+& python $script --check
+exit $LASTEXITCODE

src/MxGateway.IntegrationTests/DashboardLdapLiveTests.cs

@@ -0,0 +1,52 @@
+using System.Security.Claims;
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Extensions.Options;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Dashboard;
+
+namespace MxGateway.IntegrationTests;
+
+public sealed class DashboardLdapLiveTests
+{
+    [LiveLdapFact]
+    [Trait("Category", "LiveLdap")]
+    public async Task AuthenticateAsync_AdminInGwAdminGroup_Succeeds()
+    {
+        DashboardAuthenticator authenticator = CreateAuthenticator();
+
+        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
+            "admin",
+            "admin123",
+            CancellationToken.None);
+
+        Assert.True(result.Succeeded);
+        Assert.NotNull(result.Principal);
+        Assert.Equal("admin", result.Principal.FindFirst(ClaimTypes.NameIdentifier)?.Value);
+        Assert.Contains(result.Principal.Claims, claim =>
+            claim.Type == DashboardAuthenticationDefaults.LdapGroupClaimType
+            && claim.Value.Contains("GwAdmin", StringComparison.OrdinalIgnoreCase));
+    }
+
+    [LiveLdapFact]
+    [Trait("Category", "LiveLdap")]
+    public async Task AuthenticateAsync_ReadOnlyUserMissingGwAdminGroup_Fails()
+    {
+        DashboardAuthenticator authenticator = CreateAuthenticator();
+
+        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
+            "readonly",
+            "readonly123",
+            CancellationToken.None);
+
+        Assert.False(result.Succeeded);
+        Assert.Null(result.Principal);
+        Assert.DoesNotContain("readonly123", result.FailureMessage, StringComparison.Ordinal);
+    }
+
+    private static DashboardAuthenticator CreateAuthenticator()
+    {
+        return new DashboardAuthenticator(
+            Options.Create(new GatewayOptions()),
+            NullLogger<DashboardAuthenticator>.Instance);
+    }
+}

src/MxGateway.IntegrationTests/LiveLdapFactAttribute.cs

@@ -0,0 +1,20 @@
+namespace MxGateway.IntegrationTests;
+
+public sealed class LiveLdapFactAttribute : FactAttribute
+{
+    public const string EnableVariableName = "MXGATEWAY_RUN_LIVE_LDAP_TESTS";
+
+    public LiveLdapFactAttribute()
+    {
+        if (!Enabled)
+        {
+            Skip = $"Set {EnableVariableName}=1 to run live LDAP tests.";
+        }
+    }
+
+    public static bool Enabled =>
+        string.Equals(
+            Environment.GetEnvironmentVariable(EnableVariableName),
+            "1",
+            StringComparison.Ordinal);
+}

src/MxGateway.Server/Configuration/EffectiveLdapConfiguration.cs

@@ -0,0 +1,15 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveLdapConfiguration(
+    bool Enabled,
+    string Server,
+    int Port,
+    bool UseTls,
+    bool AllowInsecureLdap,
+    string SearchBase,
+    string ServiceAccountDn,
+    string ServiceAccountPassword,
+    string UserNameAttribute,
+    string DisplayNameAttribute,
+    string GroupAttribute,
+    string RequiredGroup);

src/MxGateway.Server/Configuration/LdapOptions.cs

@@ -0,0 +1,28 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed class LdapOptions
+{
+    public bool Enabled { get; init; } = true;
+
+    public string Server { get; init; } = "localhost";
+
+    public int Port { get; init; } = 3893;
+
+    public bool UseTls { get; init; }
+
+    public bool AllowInsecureLdap { get; init; } = true;
+
+    public string SearchBase { get; init; } = "dc=lmxopcua,dc=local";
+
+    public string ServiceAccountDn { get; init; } = "cn=serviceaccount,dc=lmxopcua,dc=local";
+
+    public string ServiceAccountPassword { get; init; } = "serviceaccount123";
+
+    public string UserNameAttribute { get; init; } = "cn";
+
+    public string DisplayNameAttribute { get; init; } = "cn";
+
+    public string GroupAttribute { get; init; } = "memberOf";
+
+    public string RequiredGroup { get; init; } = "GwAdmin";
+}

src/MxGateway.Server/Dashboard/Components/App.razor

@@ -7,6 +7,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <base href="@DashboardBaseHref" />
     <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css" />
+    <link rel="stylesheet" href="/css/theme.css" />
     <link rel="stylesheet" href="/css/dashboard.css" />
     <HeadOutlet @rendermode="InteractiveServer" />
 </head>

src/MxGateway.Server/Dashboard/Components/Layout/DashboardLayout.razor

@@ -2,55 +2,34 @@
 @inject IOptions<GatewayOptions> GatewayOptions
 
 <div class="dashboard-shell">
-    <nav class="navbar navbar-expand-lg bg-body border-bottom dashboard-navbar">
-        <div class="container-fluid">
-            <a class="navbar-brand" href="">MXAccess Gateway</a>
-            <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#dashboardNav"
-                    aria-controls="dashboardNav" aria-expanded="false" aria-label="Toggle navigation">
-                <span class="navbar-toggler-icon"></span>
-            </button>
-            <div class="collapse navbar-collapse" id="dashboardNav">
-                <ul class="navbar-nav me-auto mb-2 mb-lg-0">
-                    <li class="nav-item">
-                        <NavLink class="nav-link" href="" Match="NavLinkMatch.All">Overview</NavLink>
-                    </li>
-                    <li class="nav-item">
-                        <NavLink class="nav-link" href="sessions">Sessions</NavLink>
-                    </li>
-                    <li class="nav-item">
-                        <NavLink class="nav-link" href="workers">Workers</NavLink>
-                    </li>
-                    <li class="nav-item">
-                        <NavLink class="nav-link" href="events">Events</NavLink>
-                    </li>
-                    <li class="nav-item">
-                        <NavLink class="nav-link" href="galaxy">Galaxy</NavLink>
-                    </li>
-                    <li class="nav-item">
-                        <NavLink class="nav-link" href="apikeys">API Keys</NavLink>
-                    </li>
-                    <li class="nav-item">
-                        <NavLink class="nav-link" href="settings">Settings</NavLink>
-                    </li>
-                </ul>
-                <AuthorizeView>
-                    <Authorized Context="authState">
-                        <div class="d-flex align-items-center gap-2">
-                            <span class="navbar-text">@authState.User.Identity?.Name</span>
-                            <form method="post" action="@DashboardPath("/logout")">
-                                <AntiforgeryToken />
-                                <button class="btn btn-outline-secondary btn-sm" type="submit">Sign out</button>
-                            </form>
-                        </div>
-                    </Authorized>
-                    <NotAuthorized>
-                        <a class="btn btn-outline-secondary btn-sm" href="@DashboardPath("/login")">Sign in</a>
-                    </NotAuthorized>
-                </AuthorizeView>
-            </div>
-        </div>
-    </nav>
-    <main class="container-fluid dashboard-content">
+    <header class="app-bar">
+        <a class="brand" href=""><span class="mark">&#9646;</span> MXAccess Gateway</a>
+        <nav class="app-nav">
+            <NavLink href="" Match="NavLinkMatch.All">Overview</NavLink>
+            <NavLink href="sessions">Sessions</NavLink>
+            <NavLink href="workers">Workers</NavLink>
+            <NavLink href="events">Events</NavLink>
+            <NavLink href="galaxy">Galaxy</NavLink>
+            <NavLink href="apikeys">API Keys</NavLink>
+            <NavLink href="settings">Settings</NavLink>
+        </nav>
+        <span class="spacer"></span>
+        <AuthorizeView>
+            <Authorized Context="authState">
+                <div class="app-user">
+                    <span class="meta">@authState.User.Identity?.Name</span>
+                    <form method="post" action="@DashboardPath("/logout")">
+                        <AntiforgeryToken />
+                        <button class="btn btn-outline-secondary btn-sm" type="submit">Sign out</button>
+                    </form>
+                </div>
+            </Authorized>
+            <NotAuthorized>
+                <a class="btn btn-outline-secondary btn-sm" href="@DashboardPath("/login")">Sign in</a>
+            </NotAuthorized>
+        </AuthorizeView>
+    </header>
+    <main class="page">
         @Body
     </main>
 </div>

src/MxGateway.Server/Dashboard/Components/Pages/ApiKeysPage.razor

@@ -0,0 +1,459 @@
+@page "/apikeys"
+@page "/dashboard/apikeys"
+@inherits DashboardPageBase
+@inject AuthenticationStateProvider AuthenticationStateProvider
+@inject IDashboardApiKeyManagementService ApiKeyManagementService
+
+<PageTitle>Dashboard API Keys</PageTitle>
+
+@if (Snapshot is null)
+{
+    <div class="empty-state">Loading API keys.</div>
+}
+else
+{
+    <div class="dashboard-page-header">
+        <div>
+            <h1>API Keys</h1>
+            <div class="text-secondary">@Snapshot.ApiKeys.Count key rows</div>
+        </div>
+        @if (CanManageApiKeys)
+        {
+            <button type="button" class="btn btn-primary" @onclick="OpenCreateDialog">
+                Create API Key
+            </button>
+        }
+    </div>
+
+    @if (CanManageApiKeys)
+    {
+        @if (!string.IsNullOrWhiteSpace(ResultMessage))
+        {
+            <div class="alert @(LastOperationSucceeded ? "alert-success" : "alert-danger")" role="alert">
+                @ResultMessage
+                @if (!string.IsNullOrWhiteSpace(LastGeneratedApiKey))
+                {
+                    <div class="mt-2">
+                        <code class="one-time-secret">@LastGeneratedApiKey</code>
+                    </div>
+                }
+            </div>
+        }
+
+        @if (IsCreateDialogOpen)
+        {
+            <div class="modal-backdrop fade show"></div>
+            <div class="modal fade show api-key-create-modal" role="dialog" aria-modal="true" aria-labelledby="createApiKeyTitle">
+                <div class="modal-dialog modal-xl modal-dialog-scrollable">
+                    <div class="modal-content">
+                        <EditForm Model="@CreateModel" OnSubmit="@CreateApiKeyAsync">
+                            <div class="modal-header">
+                                <h2 class="modal-title h5" id="createApiKeyTitle">Create API Key</h2>
+                                <button type="button" class="btn-close" aria-label="Close" @onclick="CloseCreateDialog"></button>
+                            </div>
+                            <div class="modal-body">
+                                <div class="api-key-management-grid">
+                                    <div class="mb-3">
+                                        <label for="keyId" class="form-label">Key ID</label>
+                                        <input id="keyId" class="form-control" @bind="CreateModel.KeyId" @bind:event="oninput" />
+                                    </div>
+                                    <div class="mb-3">
+                                        <label for="displayName" class="form-label">Display Name</label>
+                                        <input id="displayName" class="form-control" @bind="CreateModel.DisplayName" @bind:event="oninput" />
+                                    </div>
+                                </div>
+                                <fieldset class="mb-3">
+                                    <legend class="form-label">Scopes</legend>
+                                    <div class="scope-grid">
+                                        @foreach (string scope in AvailableScopes)
+                                        {
+                                            <label class="form-check">
+                                                <input class="form-check-input" type="checkbox"
+                                                       checked="@IsScopeSelected(scope)"
+                                                       @onchange="eventArgs => SetScope(scope, eventArgs)" />
+                                                <span class="form-check-label">@scope</span>
+                                            </label>
+                                        }
+                                    </div>
+                                </fieldset>
+                                <div class="api-key-management-grid">
+                                    <div class="mb-3">
+                                        <label for="readSubtrees" class="form-label">Read subtrees</label>
+                                        <textarea id="readSubtrees" class="form-control" rows="2" @bind="CreateModel.ReadSubtrees" @bind:event="oninput"></textarea>
+                                    </div>
+                                    <div class="mb-3">
+                                        <label for="writeSubtrees" class="form-label">Write subtrees</label>
+                                        <textarea id="writeSubtrees" class="form-control" rows="2" @bind="CreateModel.WriteSubtrees" @bind:event="oninput"></textarea>
+                                    </div>
+                                    <div class="mb-3">
+                                        <label for="readTagGlobs" class="form-label">Read tag globs</label>
+                                        <textarea id="readTagGlobs" class="form-control" rows="2" @bind="CreateModel.ReadTagGlobs" @bind:event="oninput"></textarea>
+                                    </div>
+                                    <div class="mb-3">
+                                        <label for="writeTagGlobs" class="form-label">Write tag globs</label>
+                                        <textarea id="writeTagGlobs" class="form-control" rows="2" @bind="CreateModel.WriteTagGlobs" @bind:event="oninput"></textarea>
+                                    </div>
+                                    <div class="mb-3">
+                                        <label for="browseSubtrees" class="form-label">Browse subtrees</label>
+                                        <textarea id="browseSubtrees" class="form-control" rows="2" @bind="CreateModel.BrowseSubtrees" @bind:event="oninput"></textarea>
+                                    </div>
+                                    <div class="mb-3">
+                                        <label for="maxWriteClassification" class="form-label">Max write classification</label>
+                                        <input id="maxWriteClassification" class="form-control" @bind="CreateModel.MaxWriteClassification" @bind:event="oninput" />
+                                    </div>
+                                </div>
+                                <div class="d-flex flex-wrap gap-3">
+                                    <label class="form-check">
+                                        <InputCheckbox class="form-check-input" @bind-Value="CreateModel.ReadAlarmOnly" />
+                                        <span class="form-check-label">Read alarm only</span>
+                                    </label>
+                                    <label class="form-check">
+                                        <InputCheckbox class="form-check-input" @bind-Value="CreateModel.ReadHistorizedOnly" />
+                                        <span class="form-check-label">Read historized only</span>
+                                    </label>
+                                </div>
+                            </div>
+                            <div class="modal-footer">
+                                <button type="button" class="btn btn-outline-secondary" disabled="@IsBusy" @onclick="CloseCreateDialog">
+                                    Cancel
+                                </button>
+                                <button type="submit" class="btn btn-primary" disabled="@IsBusy">Create Key</button>
+                            </div>
+                        </EditForm>
+                    </div>
+                </div>
+            </div>
+        }
+    }
+
+    <section class="dashboard-section">
+        @if (Snapshot.ApiKeys.Count == 0)
+        {
+            <div class="empty-state">No API keys are available for display.</div>
+        }
+        else
+        {
+            <div class="table-responsive">
+                <table class="table table-sm align-middle dashboard-table">
+                    <thead>
+                        <tr>
+                            <th scope="col">Key</th>
+                            <th scope="col">Status</th>
+                            <th scope="col">Display Name</th>
+                            <th scope="col">Scopes</th>
+                            <th scope="col">Constraints</th>
+                            <th scope="col">Created</th>
+                            <th scope="col">Last Used</th>
+                            @if (CanManageApiKeys)
+                            {
+                                <th scope="col">Actions</th>
+                            }
+                        </tr>
+                    </thead>
+                    <tbody>
+                        @foreach (DashboardApiKeySummary key in Snapshot.ApiKeys)
+                        {
+                            <tr>
+                                <td><code>@key.KeyId</code></td>
+                                <td><StatusBadge Text="@(key.RevokedUtc is null ? "Active" : "Revoked")" /></td>
+                                <td>@DashboardDisplay.Text(key.DisplayName)</td>
+                                <td>@DashboardDisplay.Text(string.Join(", ", key.Scopes.Order(StringComparer.Ordinal)))</td>
+                                <td>@DashboardDisplay.Text(ConstraintText(key.Constraints))</td>
+                                <td>@DashboardDisplay.DateTime(key.CreatedUtc)</td>
+                                <td>@DashboardDisplay.DateTime(key.LastUsedUtc)</td>
+                                @if (CanManageApiKeys)
+                                {
+                                    <td>
+                                        <div class="btn-group btn-group-sm" role="group" aria-label="API key actions">
+                                            <button type="button" class="btn btn-outline-secondary"
+                                                    disabled="@IsBusy"
+                                                    @onclick="() => RotateApiKeyAsync(key.KeyId)">
+                                                Rotate
+                                            </button>
+                                            @if (key.RevokedUtc is null)
+                                            {
+                                                <button type="button" class="btn btn-outline-danger"
+                                                        disabled="@IsBusy"
+                                                        @onclick="() => RevokeApiKeyAsync(key.KeyId)">
+                                                    Revoke
+                                                </button>
+                                            }
+                                        </div>
+                                    </td>
+                                }
+                            </tr>
+                        }
+                    </tbody>
+                </table>
+            </div>
+        }
+    </section>
+}
+
+@code {
+    private static readonly string[] AvailableScopes =
+    [
+        GatewayScopes.SessionOpen,
+        GatewayScopes.SessionClose,
+        GatewayScopes.InvokeRead,
+        GatewayScopes.InvokeWrite,
+        GatewayScopes.InvokeSecure,
+        GatewayScopes.EventsRead,
+        GatewayScopes.MetadataRead,
+        GatewayScopes.Admin
+    ];
+
+    private ApiKeyCreateModel CreateModel { get; } = new();
+
+    private bool CanManageApiKeys { get; set; }
+
+    private bool IsBusy { get; set; }
+
+    private bool IsCreateDialogOpen { get; set; }
+
+    private string? ResultMessage { get; set; }
+
+    private bool LastOperationSucceeded { get; set; }
+
+    private string? LastGeneratedApiKey { get; set; }
+
+    protected override async Task OnInitializedAsync()
+    {
+        AuthenticationState authenticationState = await AuthenticationStateProvider.GetAuthenticationStateAsync()
+            .ConfigureAwait(false);
+        CanManageApiKeys = ApiKeyManagementService.CanManage(authenticationState.User);
+    }
+
+    private async Task CreateApiKeyAsync()
+    {
+        if (IsBusy)
+        {
+            return;
+        }
+
+        if (!TryBuildCreateRequest(out DashboardApiKeyManagementRequest? request, out string? validationMessage))
+        {
+            SetResult(DashboardApiKeyManagementResult.Fail(validationMessage ?? "API key request is invalid."));
+            return;
+        }
+
+        await RunManagementActionAsync(user => ApiKeyManagementService.CreateAsync(
+                user,
+                request,
+                CancellationToken.None))
+            .ConfigureAwait(false);
+    }
+
+    private async Task RevokeApiKeyAsync(string keyId)
+    {
+        await RunManagementActionAsync(user => ApiKeyManagementService.RevokeAsync(
+                user,
+                keyId,
+                CancellationToken.None))
+            .ConfigureAwait(false);
+    }
+
+    private async Task RotateApiKeyAsync(string keyId)
+    {
+        await RunManagementActionAsync(user => ApiKeyManagementService.RotateAsync(
+                user,
+                keyId,
+                CancellationToken.None))
+            .ConfigureAwait(false);
+    }
+
+    private async Task RunManagementActionAsync(
+        Func<System.Security.Claims.ClaimsPrincipal, Task<DashboardApiKeyManagementResult>> action)
+    {
+        if (IsBusy)
+        {
+            return;
+        }
+
+        IsBusy = true;
+        try
+        {
+            AuthenticationState authenticationState = await AuthenticationStateProvider.GetAuthenticationStateAsync()
+                .ConfigureAwait(false);
+            CanManageApiKeys = ApiKeyManagementService.CanManage(authenticationState.User);
+            DashboardApiKeyManagementResult result = await action(authenticationState.User).ConfigureAwait(false);
+            SetResult(result);
+            if (result.Succeeded && result.ApiKey is not null)
+            {
+                CreateModel.Reset();
+                IsCreateDialogOpen = false;
+            }
+        }
+        finally
+        {
+            IsBusy = false;
+        }
+    }
+
+    private void SetResult(DashboardApiKeyManagementResult result)
+    {
+        LastOperationSucceeded = result.Succeeded;
+        ResultMessage = result.Message;
+        LastGeneratedApiKey = result.ApiKey;
+    }
+
+    private void OpenCreateDialog()
+    {
+        IsCreateDialogOpen = true;
+    }
+
+    private void CloseCreateDialog()
+    {
+        if (!IsBusy)
+        {
+            IsCreateDialogOpen = false;
+        }
+    }
+
+    private bool TryBuildCreateRequest(
+        [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] out DashboardApiKeyManagementRequest? request,
+        out string? validationMessage)
+    {
+        request = null;
+        validationMessage = null;
+
+        if (!string.IsNullOrWhiteSpace(CreateModel.MaxWriteClassification)
+            && !int.TryParse(
+                CreateModel.MaxWriteClassification,
+                System.Globalization.NumberStyles.Integer,
+                System.Globalization.CultureInfo.InvariantCulture,
+                out int _))
+        {
+            validationMessage = "Max write classification must be an integer.";
+            return false;
+        }
+
+        int? maxWriteClassification = string.IsNullOrWhiteSpace(CreateModel.MaxWriteClassification)
+            ? null
+            : int.Parse(
+                CreateModel.MaxWriteClassification,
+                System.Globalization.NumberStyles.Integer,
+                System.Globalization.CultureInfo.InvariantCulture);
+
+        request = new DashboardApiKeyManagementRequest(
+            KeyId: CreateModel.KeyId,
+            DisplayName: CreateModel.DisplayName,
+            Scopes: CreateModel.SelectedScopes,
+            Constraints: new MxGateway.Server.Security.Authentication.ApiKeyConstraints(
+                ReadSubtrees: ParseList(CreateModel.ReadSubtrees),
+                WriteSubtrees: ParseList(CreateModel.WriteSubtrees),
+                ReadTagGlobs: ParseList(CreateModel.ReadTagGlobs),
+                WriteTagGlobs: ParseList(CreateModel.WriteTagGlobs),
+                MaxWriteClassification: maxWriteClassification,
+                BrowseSubtrees: ParseList(CreateModel.BrowseSubtrees),
+                ReadAlarmOnly: CreateModel.ReadAlarmOnly,
+                ReadHistorizedOnly: CreateModel.ReadHistorizedOnly));
+
+        return true;
+    }
+
+    private bool IsScopeSelected(string scope)
+    {
+        return CreateModel.SelectedScopes.Contains(scope);
+    }
+
+    private void SetScope(string scope, ChangeEventArgs eventArgs)
+    {
+        bool selected = eventArgs.Value is bool value && value;
+        if (selected)
+        {
+            CreateModel.SelectedScopes.Add(scope);
+        }
+        else
+        {
+            CreateModel.SelectedScopes.Remove(scope);
+        }
+    }
+
+    private static string ConstraintText(MxGateway.Server.Security.Authentication.ApiKeyConstraints constraints)
+    {
+        if (constraints.IsEmpty)
+        {
+            return "unconstrained";
+        }
+
+        List<string> parts = [];
+        AddList(parts, "read_subtrees", constraints.ReadSubtrees);
+        AddList(parts, "write_subtrees", constraints.WriteSubtrees);
+        AddList(parts, "read_tag_globs", constraints.ReadTagGlobs);
+        AddList(parts, "write_tag_globs", constraints.WriteTagGlobs);
+        AddList(parts, "browse_subtrees", constraints.BrowseSubtrees);
+        if (constraints.MaxWriteClassification is { } max)
+        {
+            parts.Add($"max_write_classification={max}");
+        }
+
+        if (constraints.ReadAlarmOnly)
+        {
+            parts.Add("read_alarm_only");
+        }
+
+        if (constraints.ReadHistorizedOnly)
+        {
+            parts.Add("read_historized_only");
+        }
+
+        return string.Join("; ", parts);
+    }
+
+    private static void AddList(List<string> parts, string name, IReadOnlyList<string> values)
+    {
+        if (values.Count > 0)
+        {
+            parts.Add($"{name}=[{string.Join(", ", values)}]");
+        }
+    }
+
+    private static IReadOnlyList<string> ParseList(string? value)
+    {
+        return (value ?? string.Empty)
+            .Split([',', ';', '\r', '\n'], StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
+            .Where(item => !string.IsNullOrWhiteSpace(item))
+            .ToArray();
+    }
+
+    private sealed class ApiKeyCreateModel
+    {
+        public string KeyId { get; set; } = string.Empty;
+
+        public string DisplayName { get; set; } = string.Empty;
+
+        public HashSet<string> SelectedScopes { get; } = new(StringComparer.Ordinal);
+
+        public string ReadSubtrees { get; set; } = string.Empty;
+
+        public string WriteSubtrees { get; set; } = string.Empty;
+
+        public string ReadTagGlobs { get; set; } = string.Empty;
+
+        public string WriteTagGlobs { get; set; } = string.Empty;
+
+        public string BrowseSubtrees { get; set; } = string.Empty;
+
+        public string MaxWriteClassification { get; set; } = string.Empty;
+
+        public bool ReadAlarmOnly { get; set; }
+
+        public bool ReadHistorizedOnly { get; set; }
+
+        public void Reset()
+        {
+            KeyId = string.Empty;
+            DisplayName = string.Empty;
+            SelectedScopes.Clear();
+            ReadSubtrees = string.Empty;
+            WriteSubtrees = string.Empty;
+            ReadTagGlobs = string.Empty;
+            WriteTagGlobs = string.Empty;
+            BrowseSubtrees = string.Empty;
+            MaxWriteClassification = string.Empty;
+            ReadAlarmOnly = false;
+            ReadHistorizedOnly = false;
+        }
+    }
+}

src/MxGateway.Server/Dashboard/Components/Pages/GalaxyPage.razor

@@ -19,12 +19,12 @@ else
     </div>
 
     <section class="metric-grid">
-        <MetricCard Label="Last Deploy" Value="@DashboardDisplay.DateTime(Snapshot.Galaxy.LastDeployTime)" Detail="@DeployAge()" />
+        <MetricCard Label="Last Deploy" Value="@DashboardDisplay.DateTime(Snapshot.Galaxy.LastDeployTime)" Detail="@DeployAge()" Wide="true" />
+        <MetricCard Label="Last Refresh" Value="@DashboardDisplay.DateTime(Snapshot.Galaxy.LastSuccessAt)" Detail="@LastAttemptDetail()" Wide="true" />
         <MetricCard Label="Objects" Value="@DashboardDisplay.Count(Snapshot.Galaxy.ObjectCount)" Detail="@($"{Snapshot.Galaxy.AreaCount:N0} areas")" />
         <MetricCard Label="Attributes" Value="@DashboardDisplay.Count(Snapshot.Galaxy.AttributeCount)" Detail="dynamic, deployed" />
         <MetricCard Label="Historized" Value="@DashboardDisplay.Count(Snapshot.Galaxy.HistorizedAttributeCount)" />
         <MetricCard Label="Alarms" Value="@DashboardDisplay.Count(Snapshot.Galaxy.AlarmAttributeCount)" />
-        <MetricCard Label="Last Refresh" Value="@DashboardDisplay.DateTime(Snapshot.Galaxy.LastSuccessAt)" Detail="@LastAttemptDetail()" />
     </section>
 
     @if (Snapshot.Galaxy.Status == DashboardGalaxyStatus.Unknown)

src/MxGateway.Server/Dashboard/Components/Shared/MetricCard.razor

@@ -1,4 +1,4 @@
-<div class="card metric-card h-100">
+<div class="card metric-card h-100@(Wide ? " metric-card-wide" : string.Empty)">
     <div class="card-body">
         <div class="metric-label">@Label</div>
         <div class="metric-value">@Value</div>
@@ -18,4 +18,8 @@
 
     [Parameter]
     public string? Detail { get; set; }
+
+    /// <summary>Spans the card across two grid columns for long values such as timestamps.</summary>
+    [Parameter]
+    public bool Wide { get; set; }
 }

src/MxGateway.Server/Dashboard/Components/Shared/StatusBadge.razor

@@ -1,4 +1,4 @@
-<span class="badge @CssClass">@Text</span>
+<span class="chip @CssClass">@Text</span>
 
 @code {
     [Parameter]
@@ -6,12 +6,11 @@
 
     private string CssClass => Text switch
     {
-        "Ready" or "Healthy" => "text-bg-success",
-        "Creating" or "StartingWorker" or "WaitingForPipe" or "InitializingWorker" or "Closing" => "text-bg-info",
-        "Closed" => "text-bg-secondary",
-        "Stale" => "text-bg-warning",
-        "Faulted" or "Unavailable" => "text-bg-danger",
-        "Unknown" => "text-bg-light text-dark border",
-        _ => "text-bg-light text-dark border"
+        "Ready" or "Healthy" or "Active" => "chip-ok",
+        "Creating" or "StartingWorker" or "WaitingForPipe" or "InitializingWorker" or "Closing" => "chip-warn",
+        "Stale" or "Degraded" => "chip-warn",
+        "Faulted" or "Unavailable" => "chip-bad",
+        "Closed" or "Revoked" or "Unknown" => "chip-idle",
+        _ => "chip-idle"
     };
 }

src/MxGateway.Server/Dashboard/DashboardApiKeyAuthorization.cs

@@ -0,0 +1,22 @@
+using System.Security.Claims;
+using Microsoft.Extensions.Options;
+using MxGateway.Server.Configuration;
+
+namespace MxGateway.Server.Dashboard;
+
+public sealed class DashboardApiKeyAuthorization(IOptions<GatewayOptions> options)
+{
+    public bool CanManage(ClaimsPrincipal user)
+    {
+        if (user.Identity?.IsAuthenticated != true)
+        {
+            return false;
+        }
+
+        string requiredGroup = options.Value.Ldap.RequiredGroup;
+        IEnumerable<string> groups = user.FindAll(DashboardAuthenticationDefaults.LdapGroupClaimType)
+            .Select(claim => claim.Value);
+
+        return DashboardAuthenticator.IsMemberOfRequiredGroup(groups, requiredGroup);
+    }
+}

src/MxGateway.Server/Dashboard/DashboardApiKeyManagementRequest.cs

@@ -0,0 +1,9 @@
+using MxGateway.Server.Security.Authentication;
+
+namespace MxGateway.Server.Dashboard;
+
+public sealed record DashboardApiKeyManagementRequest(
+    string KeyId,
+    string DisplayName,
+    IReadOnlySet<string> Scopes,
+    ApiKeyConstraints Constraints);

src/MxGateway.Server/Dashboard/DashboardApiKeyManagementResult.cs

@@ -0,0 +1,17 @@
+namespace MxGateway.Server.Dashboard;
+
+public sealed record DashboardApiKeyManagementResult(
+    bool Succeeded,
+    string Message,
+    string? ApiKey)
+{
+    public static DashboardApiKeyManagementResult Success(string message, string? apiKey = null)
+    {
+        return new DashboardApiKeyManagementResult(true, message, apiKey);
+    }
+
+    public static DashboardApiKeyManagementResult Fail(string message)
+    {
+        return new DashboardApiKeyManagementResult(false, message, null);
+    }
+}

src/MxGateway.Server/Dashboard/DashboardApiKeyManagementService.cs

@@ -0,0 +1,195 @@
+using System.Security.Claims;
+using Microsoft.Data.Sqlite;
+using MxGateway.Server.Security.Authentication;
+
+namespace MxGateway.Server.Dashboard;
+
+public sealed class DashboardApiKeyManagementService(
+    DashboardApiKeyAuthorization authorization,
+    IApiKeyAdminStore adminStore,
+    IApiKeyAuditStore auditStore,
+    IApiKeySecretHasher hasher,
+    IHttpContextAccessor httpContextAccessor) : IDashboardApiKeyManagementService
+{
+    private const string UnauthorizedMessage = "Sign in with an authorized LDAP account to manage API keys.";
+
+    public bool CanManage(ClaimsPrincipal user)
+    {
+        return authorization.CanManage(user);
+    }
+
+    public async Task<DashboardApiKeyManagementResult> CreateAsync(
+        ClaimsPrincipal user,
+        DashboardApiKeyManagementRequest request,
+        CancellationToken cancellationToken)
+    {
+        if (!CanManage(user))
+        {
+            return DashboardApiKeyManagementResult.Fail(UnauthorizedMessage);
+        }
+
+        string? validation = ValidateCreateRequest(request);
+        if (validation is not null)
+        {
+            return DashboardApiKeyManagementResult.Fail(validation);
+        }
+
+        string keyId = request.KeyId.Trim();
+        string secret = ApiKeySecretGenerator.Generate();
+        string apiKey = FormatApiKey(keyId, secret);
+
+        try
+        {
+            await adminStore.CreateAsync(
+                    new ApiKeyCreateRequest(
+                        KeyId: keyId,
+                        KeyPrefix: $"mxgw_{keyId}",
+                        SecretHash: hasher.HashSecret(secret),
+                        DisplayName: request.DisplayName.Trim(),
+                        Scopes: request.Scopes,
+                        Constraints: request.Constraints,
+                        CreatedUtc: DateTimeOffset.UtcNow),
+                    cancellationToken)
+                .ConfigureAwait(false);
+
+            await AppendAuditAsync(keyId, "dashboard-create-key", null, cancellationToken).ConfigureAwait(false);
+
+            return DashboardApiKeyManagementResult.Success("API key created. Copy the key now; it will not be shown again.", apiKey);
+        }
+        catch (ApiKeyPepperUnavailableException)
+        {
+            return DashboardApiKeyManagementResult.Fail("API key pepper is not configured.");
+        }
+        catch (SqliteException exception) when (exception.SqliteErrorCode == 19)
+        {
+            return DashboardApiKeyManagementResult.Fail("An API key with that id already exists.");
+        }
+    }
+
+    public async Task<DashboardApiKeyManagementResult> RevokeAsync(
+        ClaimsPrincipal user,
+        string keyId,
+        CancellationToken cancellationToken)
+    {
+        if (!CanManage(user))
+        {
+            return DashboardApiKeyManagementResult.Fail(UnauthorizedMessage);
+        }
+
+        string? validation = ValidateKeyId(keyId);
+        if (validation is not null)
+        {
+            return DashboardApiKeyManagementResult.Fail(validation);
+        }
+
+        string normalizedKeyId = keyId.Trim();
+        bool revoked = await adminStore
+            .RevokeAsync(normalizedKeyId, DateTimeOffset.UtcNow, cancellationToken)
+            .ConfigureAwait(false);
+
+        await AppendAuditAsync(
+                normalizedKeyId,
+                "dashboard-revoke-key",
+                revoked ? "revoked" : "not-found-or-already-revoked",
+                cancellationToken)
+            .ConfigureAwait(false);
+
+        return revoked
+            ? DashboardApiKeyManagementResult.Success("API key revoked.")
+            : DashboardApiKeyManagementResult.Fail("API key was not found or is already revoked.");
+    }
+
+    public async Task<DashboardApiKeyManagementResult> RotateAsync(
+        ClaimsPrincipal user,
+        string keyId,
+        CancellationToken cancellationToken)
+    {
+        if (!CanManage(user))
+        {
+            return DashboardApiKeyManagementResult.Fail(UnauthorizedMessage);
+        }
+
+        string? validation = ValidateKeyId(keyId);
+        if (validation is not null)
+        {
+            return DashboardApiKeyManagementResult.Fail(validation);
+        }
+
+        string normalizedKeyId = keyId.Trim();
+        string secret = ApiKeySecretGenerator.Generate();
+        string apiKey = FormatApiKey(normalizedKeyId, secret);
+
+        try
+        {
+            bool rotated = await adminStore
+                .RotateAsync(normalizedKeyId, hasher.HashSecret(secret), DateTimeOffset.UtcNow, cancellationToken)
+                .ConfigureAwait(false);
+
+            await AppendAuditAsync(
+                    normalizedKeyId,
+                    "dashboard-rotate-key",
+                    rotated ? "rotated" : "not-found",
+                    cancellationToken)
+                .ConfigureAwait(false);
+
+            return rotated
+                ? DashboardApiKeyManagementResult.Success("API key rotated. Copy the key now; it will not be shown again.", apiKey)
+                : DashboardApiKeyManagementResult.Fail("API key was not found.");
+        }
+        catch (ApiKeyPepperUnavailableException)
+        {
+            return DashboardApiKeyManagementResult.Fail("API key pepper is not configured.");
+        }
+    }
+
+    private async Task AppendAuditAsync(
+        string? keyId,
+        string eventType,
+        string? details,
+        CancellationToken cancellationToken)
+    {
+        await auditStore.AppendAsync(
+                new ApiKeyAuditEntry(
+                    KeyId: keyId,
+                    EventType: eventType,
+                    RemoteAddress: httpContextAccessor.HttpContext?.Connection.RemoteIpAddress?.ToString(),
+                    Details: details),
+                cancellationToken)
+            .ConfigureAwait(false);
+    }
+
+    private static string? ValidateCreateRequest(DashboardApiKeyManagementRequest request)
+    {
+        string? keyIdValidation = ValidateKeyId(request.KeyId);
+        if (keyIdValidation is not null)
+        {
+            return keyIdValidation;
+        }
+
+        if (string.IsNullOrWhiteSpace(request.DisplayName))
+        {
+            return "Display name is required.";
+        }
+
+        return null;
+    }
+
+    private static string? ValidateKeyId(string keyId)
+    {
+        if (string.IsNullOrWhiteSpace(keyId))
+        {
+            return "API key id is required.";
+        }
+
+        return keyId.Trim().All(character =>
+            char.IsAsciiLetterOrDigit(character)
+            || character is '.' or '-')
+            ? null
+            : "API key id may contain only letters, numbers, periods, and hyphens.";
+    }
+
+    private static string FormatApiKey(string keyId, string secret)
+    {
+        return $"mxgw_{keyId}_{secret}";
+    }
+}

src/MxGateway.Server/Dashboard/DashboardApiKeySummary.cs

@@ -0,0 +1,12 @@
+using MxGateway.Server.Security.Authentication;
+
+namespace MxGateway.Server.Dashboard;
+
+public sealed record DashboardApiKeySummary(
+    string KeyId,
+    string DisplayName,
+    IReadOnlySet<string> Scopes,
+    ApiKeyConstraints Constraints,
+    DateTimeOffset CreatedUtc,
+    DateTimeOffset? LastUsedUtc,
+    DateTimeOffset? RevokedUtc);

src/MxGateway.Server/Dashboard/DashboardAuthenticator.cs

@@ -2,6 +2,7 @@ using System.Security.Claims;
 using System.Text;
 using Microsoft.Extensions.Options;
 using MxGateway.Server.Configuration;
+using MxGateway.Server.Security.Authorization;
 using Novell.Directory.Ldap;
 
 namespace MxGateway.Server.Dashboard;
@@ -238,10 +239,16 @@ public sealed class DashboardAuthenticator(
         string displayName,
         IEnumerable<string> groups)
     {
+        // CreatePrincipal is reached only after IsMemberOfRequiredGroup passed,
+        // so the authenticated user is authorized for the dashboard. Emit the
+        // admin scope claim that DashboardAuthorizationHandler checks when
+        // Dashboard:RequireAdminScope is enabled — without it, every LDAP login
+        // would be denied once route-level authorization is enforced.
         List<Claim> claims =
         [
             new Claim(ClaimTypes.NameIdentifier, username),
-            new Claim(ClaimTypes.Name, displayName)
+            new Claim(ClaimTypes.Name, displayName),
+            new Claim(DashboardAuthenticationDefaults.ScopeClaimType, GatewayScopes.Admin)
         ];
 
         claims.AddRange(groups.Select(group => new Claim(

src/MxGateway.Server/Dashboard/DashboardConnectionStringDisplay.cs

@@ -0,0 +1,28 @@
+using Microsoft.Data.SqlClient;
+
+namespace MxGateway.Server.Dashboard;
+
+public static class DashboardConnectionStringDisplay
+{
+    public static string GalaxyRepositoryConnectionString(string connectionString)
+    {
+        try
+        {
+            SqlConnectionStringBuilder builder = new(connectionString);
+            SqlConnectionStringBuilder display = new()
+            {
+                DataSource = builder.DataSource,
+                InitialCatalog = builder.InitialCatalog,
+                IntegratedSecurity = builder.IntegratedSecurity,
+                Encrypt = builder.Encrypt,
+                TrustServerCertificate = builder.TrustServerCertificate,
+            };
+
+            return display.ConnectionString;
+        }
+        catch (ArgumentException)
+        {
+            return "[invalid connection string]";
+        }
+    }
+}

src/MxGateway.Server/Dashboard/DashboardEndpointRouteBuilderExtensions.cs

@@ -52,8 +52,13 @@ public static class DashboardEndpointRouteBuilderExtensions
             .AllowAnonymous()
             .WithName("DashboardAccessDenied");
 
+        // Every dashboard Razor component requires an authorized session. The
+        // login/logout/denied endpoints above opt out via AllowAnonymous(); an
+        // unauthenticated request to a component route is challenged by the
+        // cookie scheme and redirected to the login page.
         dashboard.MapRazorComponents<App>()
-            .AddInteractiveServerRenderMode();
+            .AddInteractiveServerRenderMode()
+            .RequireAuthorization(DashboardAuthenticationDefaults.AuthorizationPolicy);
 
         return endpoints;
     }
@@ -169,11 +174,17 @@ public static class DashboardEndpointRouteBuilderExtensions
                 <meta name="viewport" content="width=device-width, initial-scale=1" />
                 <title>{HtmlEncoder.Default.Encode(title)}</title>
                 <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css" />
+                <link rel="stylesheet" href="/css/theme.css" />
                 <link rel="stylesheet" href="/css/dashboard.css" />
             </head>
             <body class="dashboard-body">
-                <main class="container py-5">
-                    <h1 class="h3 mb-4">{HtmlEncoder.Default.Encode(title)}</h1>
+                <header class="app-bar">
+                    <span class="brand"><span class="mark">&#9646;</span> MXAccess Gateway</span>
+                </header>
+                <main class="page">
+                    <div class="dashboard-page-header">
+                        <h1>{HtmlEncoder.Default.Encode(title)}</h1>
+                    </div>
                     {body}
                 </main>
                 <script src="/lib/bootstrap/js/bootstrap.bundle.min.js"></script>

src/MxGateway.Server/Dashboard/IDashboardApiKeyManagementService.cs

@@ -0,0 +1,23 @@
+using System.Security.Claims;
+
+namespace MxGateway.Server.Dashboard;
+
+public interface IDashboardApiKeyManagementService
+{
+    bool CanManage(ClaimsPrincipal user);
+
+    Task<DashboardApiKeyManagementResult> CreateAsync(
+        ClaimsPrincipal user,
+        DashboardApiKeyManagementRequest request,
+        CancellationToken cancellationToken);
+
+    Task<DashboardApiKeyManagementResult> RevokeAsync(
+        ClaimsPrincipal user,
+        string keyId,
+        CancellationToken cancellationToken);
+
+    Task<DashboardApiKeyManagementResult> RotateAsync(
+        ClaimsPrincipal user,
+        string keyId,
+        CancellationToken cancellationToken);
+}

src/MxGateway.Server/Galaxy/GalaxyGlobMatcher.cs

@@ -0,0 +1,44 @@
+using System.Text;
+using System.Text.RegularExpressions;
+
+namespace MxGateway.Server.Galaxy;
+
+public static class GalaxyGlobMatcher
+{
+    public static bool IsMatch(string value, string glob)
+    {
+        if (string.IsNullOrWhiteSpace(glob))
+        {
+            return true;
+        }
+
+        return Regex.IsMatch(
+            value ?? string.Empty,
+            BuildRegex(glob),
+            RegexOptions.CultureInvariant | RegexOptions.IgnoreCase,
+            TimeSpan.FromMilliseconds(100));
+    }
+
+    private static string BuildRegex(string glob)
+    {
+        StringBuilder builder = new("^", glob.Length + 2);
+        foreach (char character in glob)
+        {
+            switch (character)
+            {
+                case '*':
+                    builder.Append(".*");
+                    break;
+                case '?':
+                    builder.Append('.');
+                    break;
+                default:
+                    builder.Append(Regex.Escape(character.ToString()));
+                    break;
+            }
+        }
+
+        builder.Append('$');
+        return builder.ToString();
+    }
+}

src/MxGateway.Server/Galaxy/GalaxyHierarchyIndex.cs

@@ -0,0 +1,106 @@
+using MxGateway.Contracts.Proto.Galaxy;
+
+namespace MxGateway.Server.Galaxy;
+
+public sealed class GalaxyHierarchyIndex
+{
+    private GalaxyHierarchyIndex(
+        IReadOnlyList<GalaxyObjectView> objectViews,
+        IReadOnlyDictionary<int, GalaxyObjectView> objectViewsById,
+        IReadOnlyDictionary<string, GalaxyTagLookup> tagsByAddress)
+    {
+        ObjectViews = objectViews;
+        ObjectViewsById = objectViewsById;
+        TagsByAddress = tagsByAddress;
+    }
+
+    public static GalaxyHierarchyIndex Empty { get; } = new(
+        Array.Empty<GalaxyObjectView>(),
+        new Dictionary<int, GalaxyObjectView>(),
+        new Dictionary<string, GalaxyTagLookup>(StringComparer.OrdinalIgnoreCase));
+
+    public IReadOnlyList<GalaxyObjectView> ObjectViews { get; }
+
+    public IReadOnlyDictionary<int, GalaxyObjectView> ObjectViewsById { get; }
+
+    public IReadOnlyDictionary<string, GalaxyTagLookup> TagsByAddress { get; }
+
+    public static GalaxyHierarchyIndex Build(IReadOnlyList<GalaxyObject> objects)
+    {
+        if (objects.Count == 0)
+        {
+            return Empty;
+        }
+
+        Dictionary<int, GalaxyObject> objectsById = new();
+        foreach (GalaxyObject obj in objects)
+        {
+            objectsById.TryAdd(obj.GobjectId, obj);
+        }
+
+        List<GalaxyObjectView> views = new(objects.Count);
+        Dictionary<int, GalaxyObjectView> viewsById = new();
+        Dictionary<string, GalaxyTagLookup> tagsByAddress = new(StringComparer.OrdinalIgnoreCase);
+
+        foreach (GalaxyObject obj in objects)
+        {
+            string path = BuildContainedPath(obj, objectsById);
+            int depth = string.IsNullOrWhiteSpace(path) ? 0 : path.Count(character => character == '/');
+            GalaxyObjectView view = new(obj, path, depth);
+            views.Add(view);
+            viewsById.TryAdd(obj.GobjectId, view);
+
+            if (!string.IsNullOrWhiteSpace(obj.TagName))
+            {
+                tagsByAddress.TryAdd(obj.TagName, new GalaxyTagLookup(obj, Attribute: null, path));
+            }
+
+            foreach (GalaxyAttribute attribute in obj.Attributes)
+            {
+                if (!string.IsNullOrWhiteSpace(attribute.FullTagReference))
+                {
+                    tagsByAddress.TryAdd(attribute.FullTagReference, new GalaxyTagLookup(obj, attribute, path));
+                }
+            }
+        }
+
+        return new GalaxyHierarchyIndex(
+            views,
+            viewsById,
+            tagsByAddress);
+    }
+
+    private static string BuildContainedPath(
+        GalaxyObject obj,
+        IReadOnlyDictionary<int, GalaxyObject> objectsById)
+    {
+        Stack<string> names = new();
+        HashSet<int> seen = [];
+        GalaxyObject? current = obj;
+        while (current is not null && seen.Add(current.GobjectId))
+        {
+            names.Push(ResolvePathSegment(current));
+            current = current.ParentGobjectId != 0
+                && objectsById.TryGetValue(current.ParentGobjectId, out GalaxyObject? parent)
+                    ? parent
+                    : null;
+        }
+
+        return string.Join('/', names.Where(name => !string.IsNullOrWhiteSpace(name)));
+    }
+
+    private static string ResolvePathSegment(GalaxyObject obj)
+    {
+        if (!string.IsNullOrWhiteSpace(obj.ContainedName))
+        {
+            return obj.ContainedName;
+        }
+
+        if (!string.IsNullOrWhiteSpace(obj.BrowseName))
+        {
+            return obj.BrowseName;
+        }
+
+        return obj.TagName;
+    }
+}

src/MxGateway.Server/Galaxy/GalaxyHierarchyProjector.cs

@@ -0,0 +1,246 @@
+using System.Security.Cryptography;
+using System.Text;
+using Grpc.Core;
+using MxGateway.Contracts.Proto.Galaxy;
+
+namespace MxGateway.Server.Galaxy;
+
+public static class GalaxyHierarchyProjector
+{
+    public static GalaxyHierarchyQueryResult Project(
+        GalaxyHierarchyCacheEntry entry,
+        DiscoverHierarchyRequest request,
+        IReadOnlyList<string>? browseSubtreeGlobs = null)
+    {
+        return Project(
+            entry,
+            request,
+            browseSubtreeGlobs,
+            offset: 0,
+            pageSize: int.MaxValue);
+    }
+
+    public static GalaxyHierarchyQueryResult Project(
+        GalaxyHierarchyCacheEntry entry,
+        DiscoverHierarchyRequest request,
+        IReadOnlyList<string>? browseSubtreeGlobs,
+        int offset,
+        int pageSize)
+    {
+        ArgumentNullException.ThrowIfNull(entry);
+        ArgumentNullException.ThrowIfNull(request);
+        if (offset < 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(offset), offset, "Offset must be greater than or equal to zero.");
+        }
+
+        if (pageSize <= 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(pageSize), pageSize, "Page size must be greater than zero.");
+        }
+
+        IReadOnlyList<GalaxyObjectView> views = entry.Index.ObjectViews;
+        GalaxyObjectView? root = ResolveRoot(request, views);
+        int? maxDepth = request.MaxDepth;
+        if (maxDepth < 0)
+        {
+            throw new RpcException(new Status(
+                StatusCode.InvalidArgument,
+                "DiscoverHierarchy max_depth must be greater than or equal to zero when provided."));
+        }
+
+        List<GalaxyObject> page = [];
+        int matchedCount = 0;
+        bool includeAttributes = IncludeAttributes(request);
+        foreach (GalaxyObjectView view in views)
+        {
+            if (!MatchesRoot(view, root, maxDepth)
+                || !MatchesBrowseSubtrees(view, browseSubtreeGlobs)
+                || !MatchesFilters(view.Object, request))
+            {
+                continue;
+            }
+
+            if (matchedCount >= offset && page.Count < pageSize)
+            {
+                page.Add(CloneObject(view.Object, includeAttributes));
+            }
+
+            matchedCount++;
+        }
+
+        return new GalaxyHierarchyQueryResult(
+            page,
+            matchedCount,
+            ComputeFilterSignature(request, browseSubtreeGlobs));
+    }
+
+    public static GalaxyObject? FindObjectForTag(
+        GalaxyHierarchyCacheEntry entry,
+        string tagAddress)
+    {
+        if (string.IsNullOrWhiteSpace(tagAddress))
+        {
+            return null;
+        }
+
+        return entry.Index.TagsByAddress.TryGetValue(tagAddress, out GalaxyTagLookup? lookup)
+            ? lookup.Object
+            : null;
+    }
+
+    public static GalaxyAttribute? FindAttributeForTag(
+        GalaxyHierarchyCacheEntry entry,
+        string tagAddress)
+    {
+        if (string.IsNullOrWhiteSpace(tagAddress))
+        {
+            return null;
+        }
+
+        return entry.Index.TagsByAddress.TryGetValue(tagAddress, out GalaxyTagLookup? lookup)
+            ? lookup.Attribute
+            : null;
+    }
+
+    public static string GetContainedPath(
+        GalaxyHierarchyCacheEntry entry,
+        int gobjectId)
+    {
+        return entry.Index.ObjectViewsById.TryGetValue(gobjectId, out GalaxyObjectView? view)
+            ? view.ContainedPath
+            : string.Empty;
+    }
+
+    private static GalaxyObjectView? ResolveRoot(
+        DiscoverHierarchyRequest request,
+        IReadOnlyList<GalaxyObjectView> views)
+    {
+        GalaxyObjectView? root = request.RootCase switch
+        {
+            DiscoverHierarchyRequest.RootOneofCase.None => null,
+            DiscoverHierarchyRequest.RootOneofCase.RootGobjectId => views.FirstOrDefault(
+                view => view.Object.GobjectId == request.RootGobjectId),
+            DiscoverHierarchyRequest.RootOneofCase.RootTagName => views.FirstOrDefault(
+                view => string.Equals(view.Object.TagName, request.RootTagName, StringComparison.OrdinalIgnoreCase)),
+            DiscoverHierarchyRequest.RootOneofCase.RootContainedPath => views.FirstOrDefault(
+                view => string.Equals(view.ContainedPath, request.RootContainedPath, StringComparison.OrdinalIgnoreCase)),
+            _ => null,
+        };
+
+        if (request.RootCase != DiscoverHierarchyRequest.RootOneofCase.None && root is null)
+        {
+            throw new RpcException(new Status(StatusCode.NotFound, "DiscoverHierarchy root was not found."));
+        }
+
+        return root;
+    }
+
+    private static bool MatchesRoot(
+        GalaxyObjectView view,
+        GalaxyObjectView? root,
+        int? maxDepth)
+    {
+        if (root is null)
+        {
+            return true;
+        }
+
+        bool isRoot = view.Object.GobjectId == root.Object.GobjectId;
+        bool isDescendant = view.ContainedPath.StartsWith(root.ContainedPath + "/", StringComparison.OrdinalIgnoreCase);
+        if (!isRoot && !isDescendant)
+        {
+            return false;
+        }
+
+        return maxDepth is null || view.Depth - root.Depth <= maxDepth.Value;
+    }
+
+    private static bool MatchesBrowseSubtrees(
+        GalaxyObjectView view,
+        IReadOnlyList<string>? browseSubtreeGlobs)
+    {
+        return browseSubtreeGlobs is null
+            || browseSubtreeGlobs.Count == 0
+            || browseSubtreeGlobs.Any(glob => GalaxyGlobMatcher.IsMatch(view.ContainedPath, glob));
+    }
+
+    private static bool MatchesFilters(
+        GalaxyObject obj,
+        DiscoverHierarchyRequest request)
+    {
+        if (request.CategoryIds.Count > 0 && !request.CategoryIds.Contains(obj.CategoryId))
+        {
+            return false;
+        }
+
+        foreach (string templateFilter in request.TemplateChainContains)
+        {
+            if (!obj.TemplateChain.Any(template => template.Contains(templateFilter, StringComparison.OrdinalIgnoreCase)))
+            {
+                return false;
+            }
+        }
+
+        if (!string.IsNullOrWhiteSpace(request.TagNameGlob)
+            && !GalaxyGlobMatcher.IsMatch(obj.TagName, request.TagNameGlob))
+        {
+            return false;
+        }
+
+        if (request.AlarmBearingOnly && !obj.Attributes.Any(attribute => attribute.IsAlarm))
+        {
+            return false;
+        }
+
+        if (request.HistorizedOnly && !obj.Attributes.Any(attribute => attribute.IsHistorized))
+        {
+            return false;
+        }
+
+        return true;
+    }
+
+    private static bool IncludeAttributes(DiscoverHierarchyRequest request)
+    {
+        return !request.HasIncludeAttributes || request.IncludeAttributes;
+    }
+
+    private static GalaxyObject CloneObject(GalaxyObject source, bool includeAttributes)
+    {
+        GalaxyObject clone = source.Clone();
+        if (!includeAttributes)
+        {
+            clone.Attributes.Clear();
+        }
+
+        return clone;
+    }
+
+    public static string ComputeFilterSignature(
+        DiscoverHierarchyRequest request,
+        IReadOnlyList<string>? browseSubtreeGlobs)
+    {
+        StringBuilder builder = new();
+        builder.Append("root=").Append(request.RootCase).Append('|');
+        builder.Append(request.RootCase switch
+        {
+            DiscoverHierarchyRequest.RootOneofCase.RootGobjectId => request.RootGobjectId.ToString(
+                System.Globalization.CultureInfo.InvariantCulture),
+            DiscoverHierarchyRequest.RootOneofCase.RootTagName => request.RootTagName,
+            DiscoverHierarchyRequest.RootOneofCase.RootContainedPath => request.RootContainedPath,
+            _ => string.Empty,
+        });
+        builder.Append("|max=").Append(request.MaxDepth?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "");
+        builder.Append("|cat=").AppendJoin(',', request.CategoryIds.Order());
+        builder.Append("|tpl=").AppendJoin(',', request.TemplateChainContains.Order(StringComparer.OrdinalIgnoreCase));
+        builder.Append("|glob=").Append(request.TagNameGlob);
+        builder.Append("|attrs=").Append(request.HasIncludeAttributes ? request.IncludeAttributes.ToString() : "unset");
+        builder.Append("|alarm=").Append(request.AlarmBearingOnly);
+        builder.Append("|hist=").Append(request.HistorizedOnly);
+        builder.Append("|browse=").AppendJoin(',', (browseSubtreeGlobs ?? Array.Empty<string>()).Order(StringComparer.OrdinalIgnoreCase));
+
+        byte[] hash = SHA256.HashData(Encoding.UTF8.GetBytes(builder.ToString()));
+        return Convert.ToHexString(hash, 0, 12);
+    }
+}

src/MxGateway.Server/Galaxy/GalaxyHierarchyQueryResult.cs

@@ -0,0 +1,8 @@
+using MxGateway.Contracts.Proto.Galaxy;
+
+namespace MxGateway.Server.Galaxy;
+
+public sealed record GalaxyHierarchyQueryResult(
+    IReadOnlyList<GalaxyObject> Objects,
+    int TotalObjectCount,
+    string FilterSignature);

src/MxGateway.Server/Galaxy/GalaxyObjectView.cs

@@ -0,0 +1,8 @@
+using MxGateway.Contracts.Proto.Galaxy;
+
+namespace MxGateway.Server.Galaxy;
+
+public sealed record GalaxyObjectView(
+    GalaxyObject Object,
+    string ContainedPath,
+    int Depth);

src/MxGateway.Server/Galaxy/GalaxyTagLookup.cs

@@ -0,0 +1,8 @@
+using MxGateway.Contracts.Proto.Galaxy;
+
+namespace MxGateway.Server.Galaxy;
+
+public sealed record GalaxyTagLookup(
+    GalaxyObject Object,
+    GalaxyAttribute? Attribute,
+    string ContainedPath);

src/MxGateway.Server/Properties/AssemblyInfo.cs

@@ -0,0 +1,4 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("MxGateway.Tests")]
+[assembly: InternalsVisibleTo("MxGateway.IntegrationTests")]

src/MxGateway.Server/Security/Authentication/ApiKeyConstraintSerializer.cs

@@ -0,0 +1,28 @@
+using System.Text.Json;
+
+namespace MxGateway.Server.Security.Authentication;
+
+public static class ApiKeyConstraintSerializer
+{
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
+        WriteIndented = false,
+    };
+
+    public static string? Serialize(ApiKeyConstraints constraints)
+    {
+        ArgumentNullException.ThrowIfNull(constraints);
+        return constraints.IsEmpty ? null : JsonSerializer.Serialize(constraints, JsonOptions);
+    }
+
+    public static ApiKeyConstraints Deserialize(string? json)
+    {
+        if (string.IsNullOrWhiteSpace(json))
+        {
+            return ApiKeyConstraints.Empty;
+        }
+
+        return JsonSerializer.Deserialize<ApiKeyConstraints>(json, JsonOptions) ?? ApiKeyConstraints.Empty;
+    }
+}

src/MxGateway.Server/Security/Authentication/ApiKeyConstraints.cs

@@ -0,0 +1,43 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed record ApiKeyConstraints(
+    IReadOnlyList<string> ReadSubtrees,
+    IReadOnlyList<string> WriteSubtrees,
+    IReadOnlyList<string> ReadTagGlobs,
+    IReadOnlyList<string> WriteTagGlobs,
+    int? MaxWriteClassification,
+    IReadOnlyList<string> BrowseSubtrees,
+    bool ReadAlarmOnly,
+    bool ReadHistorizedOnly)
+{
+    public static ApiKeyConstraints Empty { get; } = new(
+        ReadSubtrees: Array.Empty<string>(),
+        WriteSubtrees: Array.Empty<string>(),
+        ReadTagGlobs: Array.Empty<string>(),
+        WriteTagGlobs: Array.Empty<string>(),
+        MaxWriteClassification: null,
+        BrowseSubtrees: Array.Empty<string>(),
+        ReadAlarmOnly: false,
+        ReadHistorizedOnly: false);
+
+    public bool IsEmpty =>
+        ReadSubtrees.Count == 0
+        && WriteSubtrees.Count == 0
+        && ReadTagGlobs.Count == 0
+        && WriteTagGlobs.Count == 0
+        && MaxWriteClassification is null
+        && BrowseSubtrees.Count == 0
+        && !ReadAlarmOnly
+        && !ReadHistorizedOnly;
+
+    public bool HasReadConstraints =>
+        ReadSubtrees.Count > 0
+        || ReadTagGlobs.Count > 0
+        || ReadAlarmOnly
+        || ReadHistorizedOnly;
+
+    public bool HasWriteConstraints =>
+        WriteSubtrees.Count > 0
+        || WriteTagGlobs.Count > 0
+        || MaxWriteClassification is not null;
+}

src/MxGateway.Server/Security/Authorization/ConstraintEnforcer.cs

@@ -0,0 +1,165 @@
+using MxGateway.Contracts.Proto.Galaxy;
+using MxGateway.Server.Galaxy;
+using MxGateway.Server.Security.Authentication;
+using MxGateway.Server.Sessions;
+
+namespace MxGateway.Server.Security.Authorization;
+
+public sealed class ConstraintEnforcer(
+    IGalaxyHierarchyCache cache,
+    IApiKeyAuditStore auditStore) : IConstraintEnforcer
+{
+    public Task<ConstraintFailure?> CheckReadTagAsync(
+        ApiKeyIdentity? identity,
+        string tagAddress,
+        CancellationToken cancellationToken)
+    {
+        ApiKeyConstraints constraints = identity?.EffectiveConstraints ?? ApiKeyConstraints.Empty;
+        if (!constraints.HasReadConstraints)
+        {
+            return Task.FromResult<ConstraintFailure?>(null);
+        }
+
+        return Task.FromResult(CheckReadTarget(constraints, tagAddress));
+    }
+
+    public Task<ConstraintFailure?> CheckReadHandleAsync(
+        ApiKeyIdentity? identity,
+        GatewaySession session,
+        int serverHandle,
+        int itemHandle,
+        CancellationToken cancellationToken)
+    {
+        ApiKeyConstraints constraints = identity?.EffectiveConstraints ?? ApiKeyConstraints.Empty;
+        if (!constraints.HasReadConstraints)
+        {
+            return Task.FromResult<ConstraintFailure?>(null);
+        }
+
+        if (!session.TryGetItemRegistration(serverHandle, itemHandle, out SessionItemRegistration registration))
+        {
+            return Task.FromResult<ConstraintFailure?>(new ConstraintFailure("item_handle", "Item handle is not registered in the constrained session."));
+        }
+
+        return Task.FromResult(CheckReadTarget(constraints, registration.TagAddress));
+    }
+
+    public Task<ConstraintFailure?> CheckWriteHandleAsync(
+        ApiKeyIdentity? identity,
+        GatewaySession session,
+        int serverHandle,
+        int itemHandle,
+        CancellationToken cancellationToken)
+    {
+        ApiKeyConstraints constraints = identity?.EffectiveConstraints ?? ApiKeyConstraints.Empty;
+        if (!constraints.HasWriteConstraints)
+        {
+            return Task.FromResult<ConstraintFailure?>(null);
+        }
+
+        if (!session.TryGetItemRegistration(serverHandle, itemHandle, out SessionItemRegistration registration))
+        {
+            return Task.FromResult<ConstraintFailure?>(new ConstraintFailure("item_handle", "Item handle is not registered in the constrained session."));
+        }
+
+        GalaxyTagLookup? target = ResolveTarget(registration.TagAddress);
+        if (target is null)
+        {
+            return Task.FromResult<ConstraintFailure?>(new ConstraintFailure("tag_metadata", "Tag metadata is not available in the Galaxy hierarchy cache."));
+        }
+
+        if (!MatchesPathOrTag(target.ContainedPath, registration.TagAddress, constraints.WriteSubtrees, constraints.WriteTagGlobs))
+        {
+            return Task.FromResult<ConstraintFailure?>(new ConstraintFailure("write_scope", "Tag is outside the API key write scope."));
+        }
+
+        if (constraints.MaxWriteClassification is { } maxClassification)
+        {
+            GalaxyAttribute? attribute = target.Attribute;
+            if (attribute is null)
+            {
+                return Task.FromResult<ConstraintFailure?>(new ConstraintFailure("max_write_classification", "Attribute security classification is not available."));
+            }
+
+            if (attribute.SecurityClassification > maxClassification)
+            {
+                return Task.FromResult<ConstraintFailure?>(new ConstraintFailure(
+                    "max_write_classification",
+                    $"Attribute security classification {attribute.SecurityClassification} exceeds allowed maximum {maxClassification}."));
+            }
+        }
+
+        return Task.FromResult<ConstraintFailure?>(null);
+    }
+
+    public async Task RecordDenialAsync(
+        ApiKeyIdentity? identity,
+        string commandKind,
+        string target,
+        ConstraintFailure failure,
+        CancellationToken cancellationToken)
+    {
+        await auditStore.AppendAsync(
+                new ApiKeyAuditEntry(
+                    KeyId: identity?.KeyId,
+                    EventType: "constraint-denied",
+                    RemoteAddress: null,
+                    Details: $"{commandKind}: {target}: {failure.ConstraintName}: {failure.Message}"),
+                cancellationToken)
+            .ConfigureAwait(false);
+    }
+
+    private ConstraintFailure? CheckReadTarget(
+        ApiKeyConstraints constraints,
+        string tagAddress)
+    {
+        GalaxyTagLookup? target = ResolveTarget(tagAddress);
+        if (target is null)
+        {
+            return new ConstraintFailure("tag_metadata", "Tag metadata is not available in the Galaxy hierarchy cache.");
+        }
+
+        if (!MatchesPathOrTag(target.ContainedPath, tagAddress, constraints.ReadSubtrees, constraints.ReadTagGlobs))
+        {
+            return new ConstraintFailure("read_scope", "Tag is outside the API key read scope.");
+        }
+
+        if (constraints.ReadAlarmOnly && target.Attribute is not { IsAlarm: true })
+        {
+            return new ConstraintFailure("read_alarm_only", "Tag is not an alarm-bearing attribute.");
+        }
+
+        if (constraints.ReadHistorizedOnly && target.Attribute is not { IsHistorized: true })
+        {
+            return new ConstraintFailure("read_historized_only", "Tag is not a historized attribute.");
+        }
+
+        return null;
+    }
+
+    private GalaxyTagLookup? ResolveTarget(string tagAddress)
+    {
+        GalaxyHierarchyCacheEntry entry = cache.Current;
+        return !string.IsNullOrWhiteSpace(tagAddress)
+            && entry.Index.TagsByAddress.TryGetValue(tagAddress, out GalaxyTagLookup? lookup)
+                ? lookup
+                : null;
+    }
+
+    private static bool MatchesPathOrTag(
+        string containedPath,
+        string tagAddress,
+        IReadOnlyList<string> subtreeGlobs,
+        IReadOnlyList<string> tagGlobs)
+    {
+        bool hasSubtreeConstraint = subtreeGlobs.Count > 0;
+        bool hasTagConstraint = tagGlobs.Count > 0;
+        if (!hasSubtreeConstraint && !hasTagConstraint)
+        {
+            return true;
+        }
+
+        return subtreeGlobs.Any(glob => GalaxyGlobMatcher.IsMatch(containedPath, glob))
+            || tagGlobs.Any(glob => GalaxyGlobMatcher.IsMatch(tagAddress, glob));
+    }
+}

src/MxGateway.Server/Security/Authorization/ConstraintFailure.cs

@@ -0,0 +1,3 @@
+namespace MxGateway.Server.Security.Authorization;
+
+public sealed record ConstraintFailure(string ConstraintName, string Message);

src/MxGateway.Server/Security/Authorization/IConstraintEnforcer.cs

@@ -0,0 +1,33 @@
+using MxGateway.Server.Security.Authentication;
+using MxGateway.Server.Sessions;
+
+namespace MxGateway.Server.Security.Authorization;
+
+public interface IConstraintEnforcer
+{
+    Task<ConstraintFailure?> CheckReadTagAsync(
+        ApiKeyIdentity? identity,
+        string tagAddress,
+        CancellationToken cancellationToken);
+
+    Task<ConstraintFailure?> CheckReadHandleAsync(
+        ApiKeyIdentity? identity,
+        GatewaySession session,
+        int serverHandle,
+        int itemHandle,
+        CancellationToken cancellationToken);
+
+    Task<ConstraintFailure?> CheckWriteHandleAsync(
+        ApiKeyIdentity? identity,
+        GatewaySession session,
+        int serverHandle,
+        int itemHandle,
+        CancellationToken cancellationToken);
+
+    Task RecordDenialAsync(
+        ApiKeyIdentity? identity,
+        string commandKind,
+        string target,
+        ConstraintFailure failure,
+        CancellationToken cancellationToken);
+}

src/MxGateway.Server/Sessions/SessionItemRegistration.cs

@@ -0,0 +1,6 @@
+namespace MxGateway.Server.Sessions;
+
+public sealed record SessionItemRegistration(
+    int ServerHandle,
+    int ItemHandle,
+    string TagAddress);

src/MxGateway.Server/Sessions/SessionLeaseMonitorHostedService.cs

@@ -0,0 +1,45 @@
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using MxGateway.Server.Configuration;
+
+namespace MxGateway.Server.Sessions;
+
+public sealed class SessionLeaseMonitorHostedService(
+    ISessionManager sessionManager,
+    IOptions<GatewayOptions> options,
+    ILogger<SessionLeaseMonitorHostedService> logger,
+    TimeProvider? timeProvider = null) : BackgroundService
+{
+    private readonly TimeProvider _timeProvider = timeProvider ?? TimeProvider.System;
+
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        TimeSpan interval = TimeSpan.FromSeconds(Math.Max(1, options.Value.Sessions.LeaseSweepIntervalSeconds));
+        using PeriodicTimer timer = new(interval, _timeProvider);
+
+        try
+        {
+            while (await timer.WaitForNextTickAsync(stoppingToken).ConfigureAwait(false))
+            {
+                try
+                {
+                    await sessionManager
+                        .CloseExpiredLeasesAsync(_timeProvider.GetUtcNow(), stoppingToken)
+                        .ConfigureAwait(false);
+                }
+                catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+                {
+                    return;
+                }
+                catch (Exception exception)
+                {
+                    logger.LogWarning(exception, "Session lease sweep failed.");
+                }
+            }
+        }
+        catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+        {
+        }
+    }
+}

src/MxGateway.Server/wwwroot/css/dashboard.css

@@ -1,165 +1,308 @@
-:root {
-    --mxgw-surface: #f7f8fa;
-    --mxgw-border: #d8dee6;
-    --mxgw-ink-muted: #667085;
-    --mxgw-accent: #146c64;
+/* ============================================================================
+   MXAccess Gateway dashboard — view layer.
+   Layers over theme.css (the technical-light design system). Every colour,
+   font, and surface here resolves to a theme.css token — no hard-coded hex.
+   theme.css owns the tokens and the component library; this sheet only wires
+   the dashboard's own class names and Bootstrap widgets into that system.
+   ========================================================================= */
+
+body.dashboard-body { min-height: 100vh; }
+
+/* ── App bar ─────────────────────────────────────────────────────────────────
+   theme.css styles .app-bar / .brand / .mark / .spacer. Here we centre the row
+   and add the inline nav and the signed-in-user cluster. */
+.app-bar { align-items: center; gap: 1.25rem; }
+.app-bar .brand { color: var(--ink); }
+.app-bar .brand:hover { text-decoration: none; }
+
+.app-nav { display: flex; flex-wrap: wrap; gap: 0.15rem; }
+.app-nav a {
+  font-size: 0.82rem;
+  color: var(--ink-soft);
+  padding: 0.25rem 0.6rem;
+  border-radius: 4px;
+}
+.app-nav a:hover { color: var(--ink); background: #f0f0ec; text-decoration: none; }
+.app-nav a.active {
+  color: var(--accent-deep);
+  background: #e7ecfb;
+  font-weight: 600;
 }
 
-.dashboard-body {
-    background: var(--mxgw-surface);
-    color: #1f2933;
-}
-
-.dashboard-navbar {
-    min-height: 3.5rem;
-}
-
-.dashboard-content {
-    padding: 1.25rem;
+.app-user {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  font-size: 0.8rem;
+  color: var(--ink-soft);
 }
+.app-user form { margin: 0; }
 
+/* ── Page header ─────────────────────────────────────────────────────────────
+   h1 in sans, the sub-line in monospace as a quiet meta crumb. */
 .dashboard-page-header {
-    align-items: center;
-    display: flex;
-    gap: 1rem;
-    justify-content: space-between;
-    margin-bottom: 1rem;
-}
-
-.dashboard-page-header h1,
-.section-heading h2 {
-    font-size: 1.35rem;
-    font-weight: 650;
-    letter-spacing: 0;
-    margin: 0;
-}
-
-.section-heading {
-    margin-bottom: .75rem;
-}
-
-.dashboard-section {
-    background: #fff;
-    border-top: 1px solid var(--mxgw-border);
-    margin-top: 1rem;
-    padding: 1rem 0 0;
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 1rem;
+  margin-bottom: 1rem;
+  animation: rise 0.4s ease both;
+}
+.dashboard-page-header h1 {
+  font-size: 1.15rem;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+  margin: 0;
+}
+.dashboard-page-header .text-secondary {
+  margin-top: 0.15rem;
+  font-family: var(--mono);
+  font-size: 0.78rem;
+  color: var(--ink-faint);
 }
 
+/* ── KPI / metric cards ──────────────────────────────────────────────────────
+   The MetricCard component renders .metric-card with label/value/detail; this
+   is the technical-light aggregate card — uppercase eyebrow, big mono number. */
 .metric-grid {
-    display: grid;
-    gap: .75rem;
-    grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
-}
-
-.metric-grid.compact {
-    grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr));
+  display: grid;
+  gap: 0.75rem;
+  grid-template-columns: repeat(auto-fill, minmax(11rem, 1fr));
+  margin-bottom: 1rem;
+  animation: rise 0.4s ease both;
+  animation-delay: 0.04s;
 }
+.metric-grid.compact { grid-template-columns: repeat(auto-fill, minmax(10rem, 1fr)); }
 
 .metric-card {
-    border-color: var(--mxgw-border);
-    border-radius: .375rem;
-    box-shadow: none;
+  background: var(--card);
+  border: 1px solid var(--rule);
+  border-radius: 8px;
+  box-shadow: none;
 }
-
+.metric-card .card-body { padding: 0.7rem 0.9rem; }
 .metric-label {
-    color: var(--mxgw-ink-muted);
-    font-size: .78rem;
-    font-weight: 650;
-    letter-spacing: 0;
-    text-transform: uppercase;
+  font-size: 0.68rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.07em;
+  color: var(--ink-faint);
 }
+.metric-card-wide { grid-column: span 2; }
 
 .metric-value {
-    color: var(--mxgw-accent);
-    font-size: 1.7rem;
-    font-weight: 700;
-    letter-spacing: 0;
-    line-height: 1.25;
-    overflow-wrap: anywhere;
+  margin-top: 0.25rem;
+  font-family: var(--mono);
+  font-variant-numeric: tabular-nums;
+  font-size: 1.5rem;
+  font-weight: 600;
+  line-height: 1.1;
+  color: var(--ink);
+  /* break-word, not anywhere: keep date/number tokens whole, wrap at spaces. */
+  overflow-wrap: break-word;
 }
-
 .metric-detail {
-    color: var(--mxgw-ink-muted);
-    font-size: .85rem;
-    overflow-wrap: anywhere;
+  margin-top: 0.15rem;
+  font-size: 0.78rem;
+  color: var(--ink-faint);
+  overflow-wrap: anywhere;
 }
 
+/* ── Section panels ──────────────────────────────────────────────────────────
+   Each .dashboard-section is a raised panel: white card, hairline border. */
+.dashboard-section {
+  background: var(--card);
+  border: 1px solid var(--rule);
+  border-radius: 8px;
+  margin-top: 1rem;
+  padding: 0.9rem;
+  animation: rise 0.4s ease both;
+  animation-delay: 0.09s;
+}
+
+.section-heading { margin-bottom: 0.6rem; }
+.section-heading h2 {
+  font-size: 0.74rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.07em;
+  color: var(--ink-faint);
+  margin: 0;
+}
+
+/* ── Data tables ─────────────────────────────────────────────────────────────
+   Dense, hairline-ruled, uppercase head on a faint fill. */
 .dashboard-table {
-    --bs-table-bg: #fff;
-    border-color: var(--mxgw-border);
-    margin-bottom: 0;
+  width: 100%;
+  border-collapse: collapse;
+  margin-bottom: 0;
+  font-size: 0.85rem;
+  background: var(--card);
 }
-
-.dashboard-table th {
-    color: #344054;
-    font-weight: 650;
-    white-space: nowrap;
-}
-
+.dashboard-table th,
 .dashboard-table td {
-    max-width: 24rem;
-    overflow-wrap: anywhere;
+  padding: 0.45rem 0.8rem;
+  text-align: left;
+  vertical-align: middle;
+  border-bottom: 1px solid var(--rule);
 }
+.dashboard-table th {
+  font-size: 0.7rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--ink-faint);
+  background: #fbfbf9;
+  white-space: nowrap;
+}
+.dashboard-table td {
+  max-width: 26rem;
+  /* break-word, not anywhere: only split a word when it genuinely cannot
+     fit, so the column keeps whole words like "unconstrained" intact. */
+  overflow-wrap: break-word;
+}
+.dashboard-table tbody tr:last-child td { border-bottom: none; }
+.dashboard-table tbody tr:hover { background: #f3f6fd; }
 
+/* Key/value detail tables: left label column, monospace values, zebra rows. */
 .details-table th {
-    width: 14rem;
+  width: 16rem;
+  text-transform: none;
+  letter-spacing: 0;
+  font-size: 0.82rem;
+  font-weight: 500;
+  color: var(--ink-soft);
+  background: var(--card);
+}
+.details-table td {
+  font-family: var(--mono);
+  font-variant-numeric: tabular-nums;
+  font-size: 0.82rem;
+  color: var(--ink);
+}
+.details-table tbody tr:nth-child(even) { background: #fbfbf9; }
+.details-table tbody tr:hover { background: #fbfbf9; }
+
+/* Inline code: monospace, accent ink, no Bootstrap pink. */
+code {
+  font-family: var(--mono);
+  font-size: 0.82rem;
+  color: var(--accent-deep);
 }
 
+/* Status chips never wrap, even in a narrow table column. */
+.chip { white-space: nowrap; }
+
+/* ── Empty / placeholder state ───────────────────────────────────────────────*/
 .empty-state {
-    background: #fff;
-    border: 1px dashed var(--mxgw-border);
-    border-radius: .375rem;
-    color: var(--mxgw-ink-muted);
-    padding: 1rem;
+  background: #fbfbf9;
+  border: 1px dashed var(--rule-strong);
+  border-radius: 6px;
+  color: var(--ink-faint);
+  padding: 1rem 1.1rem;
+  font-size: 0.85rem;
 }
 
-.dashboard-login {
-    max-width: 28rem;
+/* ── Buttons ─────────────────────────────────────────────────────────────────
+   Flatten Bootstrap buttons onto the single accent + hairline palette. */
+.btn { border-radius: 5px; font-size: 0.82rem; font-weight: 500; white-space: nowrap; }
+.btn-primary {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: #fff;
+}
+.btn-primary:hover,
+.btn-primary:focus {
+  background: var(--accent-deep);
+  border-color: var(--accent-deep);
+  color: #fff;
+}
+.btn-outline-secondary {
+  color: var(--ink-soft);
+  background: var(--card);
+  border-color: var(--rule-strong);
+}
+.btn-outline-secondary:hover {
+  color: var(--ink);
+  background: #f0f0ec;
+  border-color: var(--rule-strong);
+}
+.btn-outline-danger {
+  color: var(--bad);
+  background: var(--card);
+  border-color: #eec3c3;
+}
+.btn-outline-danger:hover {
+  color: #fff;
+  background: var(--bad);
+  border-color: var(--bad);
 }
 
+/* ── Forms ───────────────────────────────────────────────────────────────────*/
+.form-label {
+  font-size: 0.72rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--ink-faint);
+}
+.form-control,
+.form-select {
+  font-size: 0.85rem;
+  border-color: var(--rule-strong);
+  border-radius: 5px;
+}
+.form-control:focus,
+.form-select:focus {
+  border-color: var(--accent);
+  box-shadow: 0 0 0 0.15rem rgba(47, 95, 208, 0.15);
+}
+
+/* ── Alerts ──────────────────────────────────────────────────────────────────*/
+.alert { border-radius: 6px; border-width: 1px; font-size: 0.85rem; }
+.alert-success { color: var(--ok); background: var(--ok-bg); border-color: #c6e6cd; }
+.alert-danger { color: var(--bad); background: var(--bad-bg); border-color: #eec3c3; }
+
+/* ── Login ───────────────────────────────────────────────────────────────────*/
+.dashboard-login { max-width: 24rem; margin: 0 auto; }
 .login-card {
-    border-color: var(--mxgw-border);
-    border-radius: .375rem;
+  background: var(--card);
+  border: 1px solid var(--rule);
+  border-radius: 8px;
 }
 
+/* ── API key management ──────────────────────────────────────────────────────*/
 .api-key-management-grid {
-    display: grid;
-    gap: .75rem;
-    grid-template-columns: repeat(auto-fit, minmax(18rem, 1fr));
+  display: grid;
+  gap: 0.75rem;
+  grid-template-columns: repeat(auto-fit, minmax(18rem, 1fr));
 }
-
 .scope-grid {
-    display: grid;
-    gap: .35rem .75rem;
-    grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
+  display: grid;
+  gap: 0.35rem 0.75rem;
+  grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
 }
-
 .one-time-secret {
-    display: block;
-    overflow-wrap: anywhere;
-    white-space: normal;
+  display: block;
+  overflow-wrap: anywhere;
+  white-space: normal;
+  font-family: var(--mono);
 }
-
-.api-key-create-modal {
-    display: block;
-}
-
+.api-key-create-modal { display: block; }
 .api-key-create-modal .modal-body {
-    max-height: min(70vh, 44rem);
-    overflow-y: auto;
+  max-height: min(70vh, 44rem);
+  overflow-y: auto;
+}
+.modal-content {
+  border: 1px solid var(--rule-strong);
+  border-radius: 8px;
 }
 
 @media (max-width: 700px) {
-    .dashboard-content {
-        padding: .75rem;
-    }
-
-    .dashboard-page-header {
-        align-items: flex-start;
-        flex-direction: column;
-    }
-
-    .details-table th {
-        width: 9rem;
-    }
+  .page { padding: 0.85rem; }
+  .dashboard-page-header {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+  .details-table th { width: 9rem; }
 }

src/MxGateway.Server/wwwroot/css/theme.css

@@ -0,0 +1,379 @@
+/* ============================================================================
+   Technical-Light design system — portable theme layer
+   ----------------------------------------------------------------------------
+   A refined technical-light aesthetic: warm-neutral paper, hairline rules,
+   IBM Plex type, monospace tabular numerics, status carried by colour. Built
+   to layer over Bootstrap 5 via --bs-* overrides, but every rule below works
+   standalone — Bootstrap is optional.
+
+   HOW TO ADOPT
+   1. Serve the three IBM Plex woff2 files (shipped in fonts/) and fix the
+      @font-face url() paths below to wherever you serve them.
+   2. Include this file once, globally. Add view-specific rules in a separate
+      stylesheet — never edit the token block per-view.
+   3. Status is colour, not iconography. Use the .s-* / .chip-* / .kv .v.*
+      helpers; do not hand-pick hex values in feature CSS.
+   ========================================================================= */
+
+/* ── Vendored fonts (embedded woff2, no network/CDN fetch) ───────────────────
+   Adjust these url()s to your asset route. If you cannot vendor the fonts the
+   --sans / --mono fallback stacks below degrade gracefully to system fonts. */
+@font-face {
+  font-family: 'IBM Plex Sans';
+  font-style: normal; font-weight: 400; font-display: swap;
+  src: url('/fonts/ibm-plex-sans-400.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'IBM Plex Sans';
+  font-style: normal; font-weight: 600; font-display: swap;
+  src: url('/fonts/ibm-plex-sans-600.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'IBM Plex Mono';
+  font-style: normal; font-weight: 500; font-display: swap;
+  src: url('/fonts/ibm-plex-mono-500.woff2') format('woff2');
+}
+
+/* ── Design tokens ───────────────────────────────────────────────────────────
+   The single source of truth. Re-theme by editing only this block. */
+:root {
+  /* Surfaces & ink */
+  --paper:        #f4f4f1;   /* page background — warm off-white, never pure */
+  --card:         #ffffff;   /* raised surfaces: cards, bars, table heads     */
+  --ink:          #1b1d21;   /* primary text                                  */
+  --ink-soft:     #5a6066;   /* secondary text, labels                        */
+  --ink-faint:    #8b9097;   /* tertiary text, captions, units                */
+  --rule:         #e4e4df;   /* hairline borders / row dividers               */
+  --rule-strong:  #d2d2cb;   /* emphasised hairlines: bar underline, pills    */
+
+  /* Accent */
+  --accent:       #2f5fd0;   /* links, sort arrows, primary actions           */
+  --accent-deep:  #1e3f99;   /* hover / pressed accent, raw-value emphasis     */
+
+  /* Status — foreground */
+  --ok:           #2f9e44;
+  --warn:         #e8920c;
+  --bad:          #e03131;
+  --idle:         #868e96;
+
+  /* Status — tinted backgrounds (pair with the matching foreground) */
+  --ok-bg:        #e9f6ec;
+  --warn-bg:      #fdf1dd;
+  --bad-bg:       #fceaea;
+  --idle-bg:      #eef0f2;
+
+  /* Type stacks — Plex first, graceful system fallback */
+  --mono: 'IBM Plex Mono', ui-monospace, 'Cascadia Mono', Consolas, monospace;
+  --sans: 'IBM Plex Sans', system-ui, -apple-system, 'Segoe UI', sans-serif;
+
+  /* Bootstrap 5 overrides — harmless if Bootstrap is absent */
+  --bs-body-bg:          var(--paper);
+  --bs-body-color:       var(--ink);
+  --bs-body-font-family: var(--sans);
+  --bs-body-font-size:   0.9rem;
+  --bs-primary:          var(--accent);
+  --bs-border-color:     var(--rule);
+  --bs-emphasis-color:   var(--ink);
+}
+
+/* ── Base ────────────────────────────────────────────────────────────────────
+   The faint top-right radial is the one deliberate flourish — a soft sheen,
+   not a gradient wash. Keep it subtle. */
+body {
+  background:
+    radial-gradient(1200px 480px at 88% -8%, #ffffff 0%, rgba(255,255,255,0) 70%),
+    var(--paper);
+  color: var(--ink);
+  font-family: var(--sans);
+  font-size: 0.9rem;
+  -webkit-font-smoothing: antialiased;
+}
+
+/* Any numeric / fixed-width text. Tabular figures so columns of digits align. */
+.numeric,
+.mono { font-family: var(--mono); font-variant-numeric: tabular-nums; }
+
+a { color: var(--accent); text-decoration: none; }
+a:hover { color: var(--accent-deep); text-decoration: underline; }
+
+/* ── App chrome: top bar ─────────────────────────────────────────────────────
+   One bar across the top: brand, breadcrumb crumbs, a flex spacer, then meta
+   text and any status pill pushed hard right. */
+.app-bar {
+  display: flex;
+  align-items: baseline;
+  gap: 1rem;
+  padding: 0.85rem 1.25rem;
+  background: var(--card);
+  border-bottom: 1px solid var(--rule-strong);
+}
+.app-bar .brand {
+  font-weight: 600;
+  font-size: 1.05rem;
+  letter-spacing: 0.02em;
+}
+.app-bar .brand .mark { color: var(--accent); }   /* the one accent glyph     */
+.app-bar .crumb { color: var(--ink-faint); font-size: 0.85rem; }
+.app-bar .spacer { flex: 1; }                       /* pushes meta/pill right  */
+.app-bar .meta {
+  font-family: var(--mono);
+  font-size: 0.78rem;
+  color: var(--ink-soft);
+}
+
+/* ── Connection / liveness pill ──────────────────────────────────────────────
+   A rounded pill with a dot, driven entirely by data-state. Use for any
+   live-link health indicator (websocket, SSE, polling). */
+.conn-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  font-size: 0.74rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  padding: 0.2rem 0.6rem;
+  border-radius: 999px;
+  border: 1px solid var(--rule-strong);
+  color: var(--ink-soft);
+  background: var(--card);
+}
+.conn-pill .dot {
+  width: 7px; height: 7px; border-radius: 50%;
+  background: var(--idle);
+}
+.conn-pill[data-state="connected"]      { color: var(--ok);   border-color: #bfe3c6; background: var(--ok-bg); }
+.conn-pill[data-state="connected"] .dot { background: var(--ok); }
+.conn-pill[data-state="connecting"]      { color: var(--warn); border-color: #f0d9ab; background: var(--warn-bg); }
+.conn-pill[data-state="connecting"] .dot { background: var(--warn); animation: pulse 1.1s ease-in-out infinite; }
+.conn-pill[data-state="disconnected"]      { color: var(--bad); border-color: #f0c0c0; background: var(--bad-bg); }
+.conn-pill[data-state="disconnected"] .dot { background: var(--bad); }
+
+@keyframes pulse { 0%,100% { opacity: 1; } 50% { opacity: 0.25; } }
+
+/* ── Status text helpers ─────────────────────────────────────────────────────
+   Recolour a value in place — counts, ratios, error totals. */
+.s-ok   { color: var(--ok); }
+.s-warn { color: var(--warn); }
+.s-bad  { color: var(--bad); }
+.s-idle { color: var(--idle); }
+
+/* ── State chip ──────────────────────────────────────────────────────────────
+   Compact rectangular badge for an enumerated state (bound/recovering/…).
+   Squarer than the pill; use the pill for liveness, the chip for state. */
+.chip {
+  display: inline-block;
+  font-size: 0.72rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  padding: 0.15rem 0.5rem;
+  border-radius: 4px;
+  border: 1px solid transparent;
+}
+.chip-ok   { color: var(--ok);       background: var(--ok-bg);   border-color: #c6e6cd; }
+.chip-warn { color: #b56a00;         background: var(--warn-bg); border-color: #efd6a6; }
+.chip-bad  { color: var(--bad);      background: var(--bad-bg);  border-color: #eec3c3; }
+.chip-idle { color: var(--ink-soft); background: var(--idle-bg); border-color: var(--rule-strong); }
+
+/* ── Panel — the base raised surface ─────────────────────────────────────────
+   A white card with a hairline border and 8px radius. .panel-head is the
+   uppercase eyebrow label that sits on top. */
+.panel {
+  background: var(--card);
+  border: 1px solid var(--rule);
+  border-radius: 8px;
+}
+.panel-head {
+  font-size: 0.74rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.07em;
+  color: var(--ink-faint);
+  padding: 0.6rem 0.9rem;
+  border-bottom: 1px solid var(--rule);
+}
+
+/* ── Page wrapper ────────────────────────────────────────────────────────────
+   Centred, capped width, even gutter. */
+.page { padding: 1.25rem; max-width: 1680px; margin: 0 auto; }
+
+/* ── Reveal-on-paint ─────────────────────────────────────────────────────────
+   Add .rise to top-level sections; stagger with inline animation-delay
+   (.02s, .08s, .14s …) so panels settle in sequence, not all at once. */
+@keyframes rise { from { opacity: 0; transform: translateY(6px); } to { opacity: 1; transform: none; } }
+.rise { animation: rise 0.4s ease both; }
+
+/* ════════════════════════════════════════════════════════════════════════════
+   COMPONENT LIBRARY
+   Generic, reusable pieces. View-specific layout belongs in a separate sheet.
+   ════════════════════════════════════════════════════════════════════════════ */
+
+/* ── KPI / aggregate cards ───────────────────────────────────────────────────
+   A responsive strip of headline numbers. .agg-card.alert / .caution tint the
+   whole card when a watched metric goes non-zero. */
+.agg-grid {
+  display: grid;
+  grid-template-columns: repeat(6, 1fr);
+  gap: 0.75rem;
+  margin-bottom: 1rem;
+}
+@media (max-width: 1100px) { .agg-grid { grid-template-columns: repeat(3, 1fr); } }
+@media (max-width: 620px)  { .agg-grid { grid-template-columns: repeat(2, 1fr); } }
+
+.agg-card {
+  background: var(--card);
+  border: 1px solid var(--rule);
+  border-radius: 8px;
+  padding: 0.7rem 0.9rem;
+}
+.agg-label {
+  font-size: 0.68rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.07em;
+  color: var(--ink-faint);
+}
+.agg-value {
+  margin-top: 0.25rem;
+  font-size: 1.5rem;
+  font-weight: 600;
+  line-height: 1.1;
+  display: flex;
+  align-items: baseline;
+  gap: 0.35rem;
+}
+.agg-sub {                       /* trailing "/ 54", "ms" etc. — quieter */
+  font-size: 0.85rem;
+  font-weight: 400;
+  color: var(--ink-faint);
+}
+.agg-card.alert   { border-color: #eec3c3; background: var(--bad-bg); }
+.agg-card.alert   .agg-value { color: var(--bad); }
+.agg-card.caution { border-color: #efd6a6; background: var(--warn-bg); }
+.agg-card.caution .agg-value { color: #b56a00; }
+
+/* ── Metric card + key/value rows ────────────────────────────────────────────
+   A .panel-head over a stack of .kv rows: label left, monospace value right.
+   Zebra striping on even rows. .v.warn / .v.bad / .v.ok recolour a value. */
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(290px, 1fr));
+  gap: 0.85rem;
+  margin-bottom: 1rem;
+}
+.metric-card {
+  background: var(--card);
+  border: 1px solid var(--rule);
+  border-radius: 8px;
+  overflow: hidden;
+}
+.metric-card .panel-head { margin: 0; }
+
+.kv {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: 1rem;
+  padding: 0.32rem 0.9rem;
+  font-size: 0.85rem;
+}
+.kv:nth-child(even) { background: #fbfbf9; }
+.kv .k { color: var(--ink-soft); }
+.kv .v {
+  font-family: var(--mono);
+  font-variant-numeric: tabular-nums;
+  text-align: right;
+}
+.kv .v.warn { color: var(--warn); }
+.kv .v.bad  { color: var(--bad); }
+.kv .v.ok   { color: var(--ok); }
+
+/* ── Toolbar ─────────────────────────────────────────────────────────────────
+   Filter/search row that sits inside a .panel above a table. */
+.toolbar {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  padding: 0.6rem 0.9rem;
+  border-bottom: 1px solid var(--rule);
+}
+.toolbar .spacer { flex: 1; }
+.tb-search { max-width: 280px; }
+.tb-state  { max-width: 150px; }
+.tb-check {
+  display: flex; align-items: center; gap: 0.35rem;
+  font-size: 0.82rem; color: var(--ink-soft); white-space: nowrap;
+  user-select: none;
+}
+.tb-count { font-family: var(--mono); font-size: 0.78rem; color: var(--ink-faint); }
+
+/* ── Data table ──────────────────────────────────────────────────────────────
+   Dense, hairline-ruled table. Uppercase sticky head on a faint fill; numeric
+   columns get .num (right-aligned, monospace). Rows are clickable by default —
+   drop the cursor/hover rules if yours are not. */
+.table-wrap { overflow-x: auto; }
+
+.data-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.85rem;
+}
+.data-table th,
+.data-table td {
+  padding: 0.45rem 0.8rem;
+  text-align: left;
+  white-space: nowrap;
+  border-bottom: 1px solid var(--rule);
+}
+.data-table th {
+  font-size: 0.7rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--ink-faint);
+  background: #fbfbf9;
+  position: sticky;
+  top: 0;
+}
+.data-table th.num,
+.data-table td.num { text-align: right; font-family: var(--mono); }
+
+.data-table th.sortable { cursor: pointer; user-select: none; }
+.data-table th.sortable:hover { color: var(--ink); }
+.data-table th.sorted-asc::after  { content: ' \2191'; color: var(--accent); }
+.data-table th.sorted-desc::after { content: ' \2193'; color: var(--accent); }
+
+.data-table tbody tr { cursor: pointer; transition: background 0.08s; }
+.data-table tbody tr:hover { background: #f3f6fd; }
+.data-table tbody tr:last-child td { border-bottom: none; }
+
+.empty-row {
+  text-align: center !important;
+  color: var(--ink-faint);
+  padding: 1.6rem !important;
+  font-style: italic;
+}
+
+/* ── Direction / category tag ────────────────────────────────────────────────
+   Tiny inline tag for a per-row category (e.g. read vs write). */
+.dir-tag {
+  font-size: 0.68rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  padding: 0.1rem 0.4rem;
+  border-radius: 3px;
+}
+.dir-read  { color: var(--accent-deep); background: #e7ecfb; }
+.dir-write { color: #8a5a00;            background: var(--warn-bg); }
+
+/* ── Inline notice ───────────────────────────────────────────────────────────
+   A .panel with a warning tint — for "this thing is gone / degraded" banners. */
+.notice {
+  padding: 0.85rem 1.1rem;
+  margin-bottom: 1rem;
+  color: #b56a00;
+  background: var(--warn-bg);
+  border-color: #efd6a6;
+}

src/MxGateway.Tests/Gateway/Dashboard/DashboardApiKeyAuthorizationTests.cs

@@ -0,0 +1,65 @@
+using System.Security.Claims;
+using Microsoft.Extensions.Options;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Dashboard;
+
+namespace MxGateway.Tests.Gateway.Dashboard;
+
+public sealed class DashboardApiKeyAuthorizationTests
+{
+    [Fact]
+    public void CanManage_AuthenticatedUserWithShortRequiredGroupClaim_ReturnsTrue()
+    {
+        DashboardApiKeyAuthorization authorization = CreateAuthorization();
+        ClaimsPrincipal user = CreatePrincipal("GwAdmin");
+
+        Assert.True(authorization.CanManage(user));
+    }
+
+    [Fact]
+    public void CanManage_AuthenticatedUserWithRequiredGroupDnClaim_ReturnsTrue()
+    {
+        DashboardApiKeyAuthorization authorization = CreateAuthorization();
+        ClaimsPrincipal user = CreatePrincipal("ou=GwAdmin,ou=groups,dc=lmxopcua,dc=local");
+
+        Assert.True(authorization.CanManage(user));
+    }
+
+    [Fact]
+    public void CanManage_AnonymousUser_ReturnsFalse()
+    {
+        DashboardApiKeyAuthorization authorization = CreateAuthorization();
+        ClaimsPrincipal user = new(new ClaimsIdentity());
+
+        Assert.False(authorization.CanManage(user));
+    }
+
+    [Fact]
+    public void CanManage_AuthenticatedUserWithoutRequiredGroup_ReturnsFalse()
+    {
+        DashboardApiKeyAuthorization authorization = CreateAuthorization();
+        ClaimsPrincipal user = CreatePrincipal("ReadOnly");
+
+        Assert.False(authorization.CanManage(user));
+    }
+
+    private static DashboardApiKeyAuthorization CreateAuthorization()
+    {
+        return new DashboardApiKeyAuthorization(Options.Create(new GatewayOptions
+        {
+            Ldap = new LdapOptions
+            {
+                RequiredGroup = "GwAdmin",
+            },
+        }));
+    }
+
+    private static ClaimsPrincipal CreatePrincipal(string group)
+    {
+        ClaimsIdentity identity = new(
+            [new Claim(DashboardAuthenticationDefaults.LdapGroupClaimType, group)],
+            DashboardAuthenticationDefaults.AuthenticationScheme);
+
+        return new ClaimsPrincipal(identity);
+    }
+}

src/MxGateway.Tests/Gateway/Dashboard/DashboardApiKeyManagementServiceTests.cs

@@ -0,0 +1,237 @@
+using System.Security.Claims;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.Options;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Dashboard;
+using MxGateway.Server.Security.Authentication;
+using MxGateway.Server.Security.Authorization;
+
+namespace MxGateway.Tests.Gateway.Dashboard;
+
+public sealed class DashboardApiKeyManagementServiceTests
+{
+    [Fact]
+    public async Task CreateAsync_UnauthorizedUser_DoesNotCallStore()
+    {
+        FakeApiKeyAdminStore adminStore = new();
+        DashboardApiKeyManagementService service = CreateService(adminStore);
+
+        DashboardApiKeyManagementResult result = await service.CreateAsync(
+            new ClaimsPrincipal(new ClaimsIdentity()),
+            CreateRequest(),
+            CancellationToken.None);
+
+        Assert.False(result.Succeeded);
+        Assert.Equal(0, adminStore.CreateCount);
+    }
+
+    [Fact]
+    public async Task CreateAsync_AuthorizedUser_StoresHashOfSecretAndAudits()
+    {
+        FakeApiKeyAdminStore adminStore = new();
+        FakeApiKeyAuditStore auditStore = new();
+        FakeApiKeySecretHasher hasher = new();
+        DashboardApiKeyManagementService service = CreateService(adminStore, auditStore, hasher);
+
+        DashboardApiKeyManagementResult result = await service.CreateAsync(
+            CreateAuthorizedUser(),
+            CreateRequest(),
+            CancellationToken.None);
+
+        Assert.True(result.Succeeded);
+        Assert.NotNull(result.ApiKey);
+        Assert.StartsWith("mxgw_operator01_", result.ApiKey, StringComparison.Ordinal);
+        string secret = result.ApiKey["mxgw_operator01_".Length..];
+        Assert.Equal(secret, hasher.LastSecret);
+        Assert.DoesNotContain("mxgw_operator01_", hasher.LastSecret, StringComparison.Ordinal);
+        ApiKeyCreateRequest stored = Assert.Single(adminStore.CreatedRequests);
+        Assert.Equal("operator01", stored.KeyId);
+        Assert.Equal("Operator", stored.DisplayName);
+        Assert.Contains(GatewayScopes.SessionOpen, stored.Scopes);
+        Assert.Equal(["Area1/*"], stored.Constraints.BrowseSubtrees);
+        Assert.Contains(auditStore.Entries, entry =>
+            entry.EventType == "dashboard-create-key"
+            && entry.KeyId == "operator01");
+    }
+
+    [Fact]
+    public async Task RevokeAsync_UnauthorizedUser_DoesNotCallStore()
+    {
+        FakeApiKeyAdminStore adminStore = new();
+        DashboardApiKeyManagementService service = CreateService(adminStore);
+
+        DashboardApiKeyManagementResult result = await service.RevokeAsync(
+            new ClaimsPrincipal(new ClaimsIdentity()),
+            "operator01",
+            CancellationToken.None);
+
+        Assert.False(result.Succeeded);
+        Assert.Equal(0, adminStore.RevokeCount);
+    }
+
+    [Fact]
+    public async Task RevokeAsync_AuthorizedUser_RevokesAndAudits()
+    {
+        FakeApiKeyAdminStore adminStore = new() { RevokeResult = true };
+        FakeApiKeyAuditStore auditStore = new();
+        DashboardApiKeyManagementService service = CreateService(adminStore, auditStore);
+
+        DashboardApiKeyManagementResult result = await service.RevokeAsync(
+            CreateAuthorizedUser(),
+            "operator01",
+            CancellationToken.None);
+
+        Assert.True(result.Succeeded);
+        Assert.Equal("operator01", adminStore.LastRevokedKeyId);
+        Assert.Contains(auditStore.Entries, entry =>
+            entry.EventType == "dashboard-revoke-key"
+            && entry.KeyId == "operator01"
+            && entry.Details == "revoked");
+    }
+
+    [Fact]
+    public async Task RotateAsync_AuthorizedUser_RotatesHashAndAudits()
+    {
+        FakeApiKeyAdminStore adminStore = new() { RotateResult = true };
+        FakeApiKeyAuditStore auditStore = new();
+        FakeApiKeySecretHasher hasher = new();
+        DashboardApiKeyManagementService service = CreateService(adminStore, auditStore, hasher);
+
+        DashboardApiKeyManagementResult result = await service.RotateAsync(
+            CreateAuthorizedUser(),
+            "operator01",
+            CancellationToken.None);
+
+        Assert.True(result.Succeeded);
+        Assert.NotNull(result.ApiKey);
+        Assert.StartsWith("mxgw_operator01_", result.ApiKey, StringComparison.Ordinal);
+        Assert.Equal(hasher.HashSecret(hasher.LastSecret!), adminStore.LastRotatedSecretHash);
+        Assert.Contains(auditStore.Entries, entry =>
+            entry.EventType == "dashboard-rotate-key"
+            && entry.KeyId == "operator01"
+            && entry.Details == "rotated");
+    }
+
+    private static DashboardApiKeyManagementService CreateService(
+        FakeApiKeyAdminStore? adminStore = null,
+        FakeApiKeyAuditStore? auditStore = null,
+        FakeApiKeySecretHasher? hasher = null)
+    {
+        GatewayOptions options = new()
+        {
+            Ldap = new LdapOptions
+            {
+                RequiredGroup = "GwAdmin",
+            },
+        };
+
+        DefaultHttpContext httpContext = new();
+        httpContext.Connection.RemoteIpAddress = System.Net.IPAddress.Loopback;
+
+        return new DashboardApiKeyManagementService(
+            new DashboardApiKeyAuthorization(Options.Create(options)),
+            adminStore ?? new FakeApiKeyAdminStore(),
+            auditStore ?? new FakeApiKeyAuditStore(),
+            hasher ?? new FakeApiKeySecretHasher(),
+            new HttpContextAccessor { HttpContext = httpContext });
+    }
+
+    private static DashboardApiKeyManagementRequest CreateRequest()
+    {
+        return new DashboardApiKeyManagementRequest(
+            KeyId: "operator01",
+            DisplayName: "Operator",
+            Scopes: new HashSet<string>([GatewayScopes.SessionOpen], StringComparer.Ordinal),
+            Constraints: ApiKeyConstraints.Empty with
+            {
+                BrowseSubtrees = ["Area1/*"],
+            });
+    }
+
+    private static ClaimsPrincipal CreateAuthorizedUser()
+    {
+        ClaimsIdentity identity = new(
+            [new Claim(DashboardAuthenticationDefaults.LdapGroupClaimType, "GwAdmin")],
+            DashboardAuthenticationDefaults.AuthenticationScheme);
+
+        return new ClaimsPrincipal(identity);
+    }
+
+    private sealed class FakeApiKeyAdminStore : IApiKeyAdminStore
+    {
+        public int CreateCount { get; private set; }
+
+        public int RevokeCount { get; private set; }
+
+        public bool RevokeResult { get; init; }
+
+        public bool RotateResult { get; init; }
+
+        public string? LastRevokedKeyId { get; private set; }
+
+        public byte[]? LastRotatedSecretHash { get; private set; }
+
+        public List<ApiKeyCreateRequest> CreatedRequests { get; } = [];
+
+        public Task CreateAsync(ApiKeyCreateRequest request, CancellationToken cancellationToken)
+        {
+            CreateCount++;
+            CreatedRequests.Add(request);
+            return Task.CompletedTask;
+        }
+
+        public Task<IReadOnlyList<ApiKeyRecord>> ListAsync(CancellationToken cancellationToken)
+        {
+            return Task.FromResult<IReadOnlyList<ApiKeyRecord>>([]);
+        }
+
+        public Task<bool> RevokeAsync(
+            string keyId,
+            DateTimeOffset revokedUtc,
+            CancellationToken cancellationToken)
+        {
+            RevokeCount++;
+            LastRevokedKeyId = keyId;
+            return Task.FromResult(RevokeResult);
+        }
+
+        public Task<bool> RotateAsync(
+            string keyId,
+            byte[] secretHash,
+            DateTimeOffset rotatedUtc,
+            CancellationToken cancellationToken)
+        {
+            LastRotatedSecretHash = secretHash;
+            return Task.FromResult(RotateResult);
+        }
+    }
+
+    private sealed class FakeApiKeyAuditStore : IApiKeyAuditStore
+    {
+        public List<ApiKeyAuditEntry> Entries { get; } = [];
+
+        public Task AppendAsync(ApiKeyAuditEntry entry, CancellationToken cancellationToken)
+        {
+            Entries.Add(entry);
+            return Task.CompletedTask;
+        }
+
+        public Task<IReadOnlyList<ApiKeyAuditRecord>> ListRecentAsync(
+            int count,
+            CancellationToken cancellationToken)
+        {
+            return Task.FromResult<IReadOnlyList<ApiKeyAuditRecord>>([]);
+        }
+    }
+
+    private sealed class FakeApiKeySecretHasher : IApiKeySecretHasher
+    {
+        public string? LastSecret { get; private set; }
+
+        public byte[] HashSecret(string secret)
+        {
+            LastSecret = secret;
+            return System.Text.Encoding.UTF8.GetBytes($"hash:{secret}");
+        }
+    }
+}

src/MxGateway.Tests/Gateway/Dashboard/DashboardConnectionStringDisplayTests.cs

@@ -0,0 +1,21 @@
+using MxGateway.Server.Dashboard;
+
+namespace MxGateway.Tests.Gateway.Dashboard;
+
+public sealed class DashboardConnectionStringDisplayTests
+{
+    [Fact]
+    public void GalaxyRepositoryConnectionString_WithSqlCredentials_OnlyKeepsNonSecretFields()
+    {
+        string display = DashboardConnectionStringDisplay.GalaxyRepositoryConnectionString(
+            "Server=localhost;Database=ZB;User ID=mxuser;Password=secret;Encrypt=True;Trust Server Certificate=False;");
+
+        Assert.Contains("Data Source=localhost", display, StringComparison.Ordinal);
+        Assert.Contains("Initial Catalog=ZB", display, StringComparison.Ordinal);
+        Assert.Contains("Encrypt=True", display, StringComparison.Ordinal);
+        Assert.DoesNotContain("User", display, StringComparison.OrdinalIgnoreCase);
+        Assert.DoesNotContain("Password", display, StringComparison.OrdinalIgnoreCase);
+        Assert.DoesNotContain("secret", display, StringComparison.OrdinalIgnoreCase);
+        Assert.DoesNotContain("mxuser", display, StringComparison.OrdinalIgnoreCase);
+    }
+}

src/MxGateway.Tests/Gateway/GatewayApplicationTests.cs

@@ -4,6 +4,7 @@ using Microsoft.AspNetCore.Routing;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Options;
 using MxGateway.Server;
+using MxGateway.Server.Dashboard;
 using MxGateway.Server.Metrics;
 
 namespace MxGateway.Tests.Gateway;
@@ -54,19 +55,48 @@ public sealed class GatewayApplicationTests
             endpoint.Metadata.GetMetadata<IEndpointNameMetadata>()?.EndpointName == "DashboardLogout");
     }
 
-    /// <summary>Verifies that Build does not map dashboard routes when the dashboard is disabled.</summary>
+    /// <summary>Verifies that the dashboard login, logout, and denied endpoints allow anonymous access.</summary>
     [Fact]
-    public void Build_WhenDashboardEnabled_DashboardRoutesAllowAnonymousAccess()
+    public void Build_WhenDashboardEnabled_AuthEndpointsAllowAnonymousAccess()
     {
         WebApplication app = GatewayApplication.Build([]);
-        IReadOnlyList<RouteEndpoint> endpoints = GetRouteEndpoints(app)
-            .Where(endpoint => endpoint.RoutePattern.RawText?.StartsWith(
-                "/dashboard",
-                StringComparison.Ordinal) == true)
-            .ToArray();
+        IReadOnlyList<RouteEndpoint> endpoints = GetRouteEndpoints(app);
 
-        Assert.NotEmpty(endpoints);
-        Assert.DoesNotContain(endpoints, endpoint => endpoint.Metadata.GetMetadata<IAuthorizeData>() is not null);
+        string[] anonymousEndpointNames =
+            ["DashboardLogin", "DashboardLoginPost", "DashboardLogout", "DashboardAccessDenied"];
+        foreach (string endpointName in anonymousEndpointNames)
+        {
+            RouteEndpoint endpoint = Assert.Single(
+                endpoints,
+                candidate => candidate.Metadata.GetMetadata<IEndpointNameMetadata>()?.EndpointName == endpointName);
+
+            Assert.NotNull(endpoint.Metadata.GetMetadata<IAllowAnonymous>());
+        }
+    }
+
+    /// <summary>Verifies that dashboard Razor component routes require the dashboard authorization policy.</summary>
+    [Fact]
+    public void Build_WhenDashboardEnabled_ComponentRoutesRequireAuthorization()
+    {
+        WebApplication app = GatewayApplication.Build([]);
+        IReadOnlyList<RouteEndpoint> endpoints = GetRouteEndpoints(app);
+
+        string[] componentRoutes =
+            ["/dashboard/", "/dashboard/sessions", "/dashboard/workers", "/dashboard/events", "/dashboard/settings"];
+        foreach (string route in componentRoutes)
+        {
+            RouteEndpoint[] matches = endpoints
+                .Where(endpoint => endpoint.RoutePattern.RawText == route)
+                .ToArray();
+
+            Assert.NotEmpty(matches);
+            Assert.All(matches, endpoint =>
+            {
+                IAuthorizeData? authorize = endpoint.Metadata.GetMetadata<IAuthorizeData>();
+                Assert.NotNull(authorize);
+                Assert.Equal(DashboardAuthenticationDefaults.AuthorizationPolicy, authorize.Policy);
+            });
+        }
     }
 
     [Fact]

src/MxGateway.Tests/Gateway/Grpc/GalaxyRepositoryGrpcServiceTests.cs

@@ -0,0 +1,371 @@
+using Grpc.Core;
+using Microsoft.Extensions.Logging.Abstractions;
+using MxGateway.Contracts.Proto.Galaxy;
+using MxGateway.Server.Dashboard;
+using MxGateway.Server.Galaxy;
+using MxGateway.Server.Grpc;
+using MxGateway.Server.Security.Authorization;
+
+namespace MxGateway.Tests.Gateway.Grpc;
+
+public sealed class GalaxyRepositoryGrpcServiceTests
+{
+    [Fact]
+    public async Task DiscoverHierarchy_ReturnsRequestedPageAndTotals()
+    {
+        GalaxyRepositoryGrpcService service = CreateService(CreateEntry(CreateObjects(3)));
+
+        DiscoverHierarchyReply reply = await service.DiscoverHierarchy(
+            new DiscoverHierarchyRequest
+            {
+                PageSize = 2,
+            },
+            new TestServerCallContext());
+
+        Assert.Equal(2, reply.Objects.Count);
+        Assert.Equal("Object_001", reply.Objects[0].TagName);
+        Assert.Equal("Object_002", reply.Objects[1].TagName);
+        Assert.StartsWith("7:", reply.NextPageToken, StringComparison.Ordinal);
+        Assert.EndsWith(":2", reply.NextPageToken, StringComparison.Ordinal);
+        Assert.Equal(3, reply.TotalObjectCount);
+    }
+
+    [Fact]
+    public async Task DiscoverHierarchy_WithNextPageToken_ReturnsRemainingObjects()
+    {
+        GalaxyRepositoryGrpcService service = CreateService(CreateEntry(CreateObjects(3)));
+        DiscoverHierarchyReply firstPage = await service.DiscoverHierarchy(
+            new DiscoverHierarchyRequest
+            {
+                PageSize = 2,
+            },
+            new TestServerCallContext());
+
+        DiscoverHierarchyReply reply = await service.DiscoverHierarchy(
+            new DiscoverHierarchyRequest
+            {
+                PageSize = 2,
+                PageToken = firstPage.NextPageToken,
+            },
+            new TestServerCallContext());
+
+        GalaxyObject item = Assert.Single(reply.Objects);
+        Assert.Equal("Object_003", item.TagName);
+        Assert.Equal("", reply.NextPageToken);
+        Assert.Equal(3, reply.TotalObjectCount);
+    }
+
+    [Theory]
+    [InlineData("-1", 1)]
+    [InlineData("not-an-offset", 1)]
+    [InlineData("7:4", 1)]
+    [InlineData("6:2", 1)]
+    [InlineData("", -1)]
+    public async Task DiscoverHierarchy_WithInvalidPagingArguments_ReturnsInvalidArgument(
+        string pageToken,
+        int pageSize)
+    {
+        GalaxyRepositoryGrpcService service = CreateService(CreateEntry(CreateObjects(3)));
+
+        RpcException exception = await Assert.ThrowsAsync<RpcException>(
+            async () => await service.DiscoverHierarchy(
+                new DiscoverHierarchyRequest
+                {
+                    PageSize = pageSize,
+                    PageToken = pageToken,
+                },
+                new TestServerCallContext()));
+
+        Assert.Equal(StatusCode.InvalidArgument, exception.StatusCode);
+    }
+
+    [Fact]
+    public async Task DiscoverHierarchy_WithSubtreeRootAndDepth_FiltersDescendants()
+    {
+        GalaxyRepositoryGrpcService service = CreateService(CreateEntry(CreateFilterObjects()));
+
+        DiscoverHierarchyReply reply = await service.DiscoverHierarchy(
+            new DiscoverHierarchyRequest
+            {
+                RootContainedPath = "Area1/Line3",
+                MaxDepth = 1,
+                PageSize = 10,
+            },
+            new TestServerCallContext());
+
+        Assert.Equal(["Line3", "Pump_001", "Valve_001"], reply.Objects.Select(obj => obj.TagName));
+        Assert.Equal(3, reply.TotalObjectCount);
+    }
+
+    [Fact]
+    public async Task DiscoverHierarchy_WithServerSideFilters_AppliesAllFiltersAndOmitsAttributes()
+    {
+        GalaxyRepositoryGrpcService service = CreateService(CreateEntry(CreateFilterObjects()));
+
+        DiscoverHierarchyReply reply = await service.DiscoverHierarchy(
+            new DiscoverHierarchyRequest
+            {
+                RootTagName = "Area1",
+                TagNameGlob = "Pump_*",
+                AlarmBearingOnly = true,
+                HistorizedOnly = true,
+                IncludeAttributes = false,
+                PageSize = 10,
+                CategoryIds = { 10 },
+                TemplateChainContains = { "Pump" },
+            },
+            new TestServerCallContext());
+
+        GalaxyObject obj = Assert.Single(reply.Objects);
+        Assert.Equal("Pump_001", obj.TagName);
+        Assert.Empty(obj.Attributes);
+        Assert.Equal(1, reply.TotalObjectCount);
+    }
+
+    [Fact]
+    public async Task DiscoverHierarchy_WithFilteredPaging_ReturnsPostFilterTotal()
+    {
+        GalaxyRepositoryGrpcService service = CreateService(CreateEntry(CreateFilterObjects()));
+
+        DiscoverHierarchyReply first = await service.DiscoverHierarchy(
+            new DiscoverHierarchyRequest
+            {
+                RootGobjectId = 1,
+                PageSize = 1,
+                CategoryIds = { 10 },
+            },
+            new TestServerCallContext());
+
+        DiscoverHierarchyReply second = await service.DiscoverHierarchy(
+            new DiscoverHierarchyRequest
+            {
+                RootGobjectId = 1,
+                PageSize = 1,
+                PageToken = first.NextPageToken,
+                CategoryIds = { 10 },
+            },
+            new TestServerCallContext());
+
+        GalaxyObject firstObject = Assert.Single(first.Objects);
+        GalaxyObject secondObject = Assert.Single(second.Objects);
+        Assert.Equal(2, first.TotalObjectCount);
+        Assert.Equal(2, second.TotalObjectCount);
+        Assert.NotEqual(firstObject.TagName, secondObject.TagName);
+    }
+
+    [Fact]
+    public async Task DiscoverHierarchy_WithMismatchedFilterToken_ReturnsInvalidArgument()
+    {
+        GalaxyRepositoryGrpcService service = CreateService(CreateEntry(CreateFilterObjects()));
+        DiscoverHierarchyReply first = await service.DiscoverHierarchy(
+            new DiscoverHierarchyRequest
+            {
+                PageSize = 1,
+                CategoryIds = { 10 },
+            },
+            new TestServerCallContext());
+
+        RpcException exception = await Assert.ThrowsAsync<RpcException>(
+            async () => await service.DiscoverHierarchy(
+                new DiscoverHierarchyRequest
+                {
+                    PageSize = 1,
+                    PageToken = first.NextPageToken,
+                    CategoryIds = { 11 },
+                },
+                new TestServerCallContext()));
+
+        Assert.Equal(StatusCode.InvalidArgument, exception.StatusCode);
+        Assert.Contains("filters", exception.Status.Detail, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task DiscoverHierarchy_WithMissingRoot_ReturnsNotFound()
+    {
+        GalaxyRepositoryGrpcService service = CreateService(CreateEntry(CreateFilterObjects()));
+
+        RpcException exception = await Assert.ThrowsAsync<RpcException>(
+            async () => await service.DiscoverHierarchy(
+                new DiscoverHierarchyRequest
+                {
+                    RootTagName = "Missing",
+                },
+                new TestServerCallContext()));
+
+        Assert.Equal(StatusCode.NotFound, exception.StatusCode);
+    }
+
+    private static GalaxyRepositoryGrpcService CreateService(GalaxyHierarchyCacheEntry entry)
+    {
+        GalaxyRepositoryOptions options = new()
+        {
+            ConnectionString = "Server=localhost;Database=ZB;Integrated Security=True;Encrypt=False;",
+        };
+        return new GalaxyRepositoryGrpcService(
+            new global::MxGateway.Server.Galaxy.GalaxyRepository(options),
+            new StubGalaxyHierarchyCache(entry),
+            new GalaxyDeployNotifier(),
+            new GatewayRequestIdentityAccessor(),
+            NullLogger<GalaxyRepositoryGrpcService>.Instance);
+    }
+
+    private static GalaxyHierarchyCacheEntry CreateEntry(IReadOnlyList<GalaxyObject> objects)
+    {
+        return GalaxyHierarchyCacheEntry.Empty with
+        {
+            Status = GalaxyCacheStatus.Healthy,
+            Sequence = 7,
+            LastSuccessAt = DateTimeOffset.UtcNow,
+            Objects = objects,
+            Index = GalaxyHierarchyIndex.Build(objects),
+            DashboardSummary = DashboardGalaxySummary.Unknown with
+            {
+                Status = DashboardGalaxyStatus.Healthy,
+                ObjectCount = objects.Count,
+            },
+            ObjectCount = objects.Count,
+        };
+    }
+
+    private static IReadOnlyList<GalaxyObject> CreateObjects(int count)
+    {
+        return Enumerable.Range(1, count)
+            .Select(index => new GalaxyObject
+            {
+                GobjectId = index,
+                TagName = $"Object_{index:000}",
+                BrowseName = $"Object_{index:000}",
+            })
+            .ToArray();
+    }
+
+    private static IReadOnlyList<GalaxyObject> CreateFilterObjects()
+    {
+        return
+        [
+            new GalaxyObject
+            {
+                GobjectId = 1,
+                TagName = "Area1",
+                ContainedName = "Area1",
+                BrowseName = "Area1",
+                IsArea = true,
+                CategoryId = 13,
+            },
+            new GalaxyObject
+            {
+                GobjectId = 2,
+                TagName = "Line3",
+                ContainedName = "Line3",
+                BrowseName = "Line3",
+                ParentGobjectId = 1,
+                CategoryId = 10,
+                TemplateChain = { "$Line", "$Base" },
+            },
+            new GalaxyObject
+            {
+                GobjectId = 3,
+                TagName = "Pump_001",
+                ContainedName = "Pump",
+                BrowseName = "Pump_001",
+                ParentGobjectId = 2,
+                CategoryId = 10,
+                TemplateChain = { "$Pump", "$Base" },
+                Attributes =
+                {
+                    new GalaxyAttribute
+                    {
+                        AttributeName = "PV",
+                        FullTagReference = "Pump_001.PV",
+                        IsAlarm = true,
+                        IsHistorized = true,
+                        SecurityClassification = 2,
+                    },
+                },
+            },
+            new GalaxyObject
+            {
+                GobjectId = 4,
+                TagName = "Valve_001",
+                ContainedName = "Valve",
+                BrowseName = "Valve_001",
+                ParentGobjectId = 2,
+                CategoryId = 11,
+                TemplateChain = { "$Valve" },
+                Attributes =
+                {
+                    new GalaxyAttribute
+                    {
+                        AttributeName = "PV",
+                        FullTagReference = "Valve_001.PV",
+                    },
+                },
+            },
+            new GalaxyObject
+            {
+                GobjectId = 5,
+                TagName = "Other_001",
+                ContainedName = "Other",
+                BrowseName = "Other_001",
+                CategoryId = 10,
+            },
+        ];
+    }
+
+    private sealed class StubGalaxyHierarchyCache(GalaxyHierarchyCacheEntry current) : IGalaxyHierarchyCache
+    {
+        public GalaxyHierarchyCacheEntry Current { get; } = current;
+
+        public Task RefreshAsync(CancellationToken cancellationToken) => Task.CompletedTask;
+
+        public Task WaitForFirstLoadAsync(CancellationToken cancellationToken) => Task.CompletedTask;
+    }
+
+    private sealed class TestServerCallContext(CancellationToken cancellationToken = default) : ServerCallContext
+    {
+        private readonly Metadata requestHeaders = [];
+        private readonly Metadata responseTrailers = [];
+        private readonly Dictionary<object, object> userState = [];
+        private Status status;
+        private WriteOptions? writeOptions;
+
+        protected override string MethodCore => "/galaxy_repository.v1.GalaxyRepository/DiscoverHierarchy";
+
+        protected override string HostCore => "localhost";
+
+        protected override string PeerCore => "ipv4:127.0.0.1:5000";
+
+        protected override DateTime DeadlineCore => DateTime.UtcNow.AddMinutes(1);
+
+        protected override Metadata RequestHeadersCore => requestHeaders;
+
+        protected override CancellationToken CancellationTokenCore => cancellationToken;
+
+        protected override Metadata ResponseTrailersCore => responseTrailers;
+
+        protected override Status StatusCore
+        {
+            get => status;
+            set => status = value;
+        }
+
+        protected override WriteOptions? WriteOptionsCore
+        {
+            get => writeOptions;
+            set => writeOptions = value;
+        }
+
+        protected override AuthContext AuthContextCore { get; } = new(
+            string.Empty,
+            new Dictionary<string, List<AuthProperty>>(StringComparer.Ordinal));
+
+        protected override IDictionary<object, object> UserStateCore => userState;
+
+        protected override Task WriteResponseHeadersAsyncCore(Metadata responseHeaders) => Task.CompletedTask;
+
+        protected override ContextPropagationToken CreatePropagationTokenCore(ContextPropagationOptions? options)
+        {
+            throw new NotSupportedException();
+        }
+    }
+}

src/MxGateway.Tests/Security/Authorization/ConstraintEnforcerTests.cs

@@ -0,0 +1,247 @@
+using MxGateway.Contracts.Proto.Galaxy;
+using MxGateway.Contracts.Proto;
+using MxGateway.Server.Dashboard;
+using MxGateway.Server.Galaxy;
+using MxGateway.Server.Security.Authentication;
+using MxGateway.Server.Security.Authorization;
+using MxGateway.Server.Sessions;
+
+namespace MxGateway.Tests.Security.Authorization;
+
+public sealed class ConstraintEnforcerTests
+{
+    [Fact]
+    public async Task CheckReadTagAsync_WhenOutsideReadSubtree_ReturnsFailure()
+    {
+        ConstraintEnforcer enforcer = CreateEnforcer(out _);
+        ApiKeyIdentity identity = CreateIdentity(ApiKeyConstraints.Empty with
+        {
+            ReadSubtrees = ["Area1/*"],
+        });
+
+        ConstraintFailure? failure = await enforcer.CheckReadTagAsync(
+            identity,
+            "Other_001.PV",
+            CancellationToken.None);
+
+        Assert.NotNull(failure);
+        Assert.Equal("read_scope", failure.ConstraintName);
+    }
+
+    [Fact]
+    public async Task CheckWriteHandleAsync_WhenClassificationTooHigh_ReturnsFailureAndAudits()
+    {
+        ConstraintEnforcer enforcer = CreateEnforcer(out FakeAuditStore auditStore);
+        ApiKeyIdentity identity = CreateIdentity(ApiKeyConstraints.Empty with
+        {
+            WriteSubtrees = ["Area1/*"],
+            MaxWriteClassification = 1,
+        });
+        GatewaySession session = CreateSession();
+        session.TrackCommandReply(
+            new MxCommand
+            {
+                Kind = MxCommandKind.AddItem,
+                AddItem = new AddItemCommand
+                {
+                    ServerHandle = 12,
+                    ItemDefinition = "Pump_001.PV",
+                },
+            },
+            new MxCommandReply
+            {
+                ProtocolStatus = MxGateway.Server.Grpc.MxAccessGrpcMapper.Ok(),
+                AddItem = new AddItemReply { ItemHandle = 42 },
+            });
+
+        ConstraintFailure? failure = await enforcer.CheckWriteHandleAsync(
+            identity,
+            session,
+            serverHandle: 12,
+            itemHandle: 42,
+            CancellationToken.None);
+        Assert.NotNull(failure);
+
+        await enforcer.RecordDenialAsync(identity, "Write", "42", failure, CancellationToken.None);
+
+        ApiKeyAuditEntry entry = Assert.Single(auditStore.Entries);
+        Assert.Equal("operator01", entry.KeyId);
+        Assert.Equal("constraint-denied", entry.EventType);
+        Assert.Contains("max_write_classification", entry.Details, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task CheckReadTagAsync_WithHistorizedOnly_RequiresRequestedAttributeToBeHistorized()
+    {
+        ConstraintEnforcer enforcer = CreateEnforcer(out _);
+        ApiKeyIdentity identity = CreateIdentity(ApiKeyConstraints.Empty with
+        {
+            ReadHistorizedOnly = true,
+        });
+
+        ConstraintFailure? failure = await enforcer.CheckReadTagAsync(
+            identity,
+            "Pump_001.NonHistorized",
+            CancellationToken.None);
+
+        Assert.NotNull(failure);
+        Assert.Equal("read_historized_only", failure.ConstraintName);
+    }
+
+    [Fact]
+    public async Task CheckReadTagAsync_WithAlarmOnly_RequiresRequestedAttributeToBeAlarm()
+    {
+        ConstraintEnforcer enforcer = CreateEnforcer(out _);
+        ApiKeyIdentity identity = CreateIdentity(ApiKeyConstraints.Empty with
+        {
+            ReadAlarmOnly = true,
+        });
+
+        ConstraintFailure? failure = await enforcer.CheckReadTagAsync(
+            identity,
+            "Pump_001.PV",
+            CancellationToken.None);
+
+        Assert.NotNull(failure);
+        Assert.Equal("read_alarm_only", failure.ConstraintName);
+    }
+
+    [Fact]
+    public async Task CheckReadTagAsync_WithAttributeOnlyConstraint_FailsClosedForObjectTag()
+    {
+        ConstraintEnforcer enforcer = CreateEnforcer(out _);
+        ApiKeyIdentity identity = CreateIdentity(ApiKeyConstraints.Empty with
+        {
+            ReadHistorizedOnly = true,
+        });
+
+        ConstraintFailure? failure = await enforcer.CheckReadTagAsync(
+            identity,
+            "Pump_001",
+            CancellationToken.None);
+
+        Assert.NotNull(failure);
+        Assert.Equal("read_historized_only", failure.ConstraintName);
+    }
+
+    private static ConstraintEnforcer CreateEnforcer(out FakeAuditStore auditStore)
+    {
+        auditStore = new FakeAuditStore();
+        return new ConstraintEnforcer(new StubGalaxyHierarchyCache(CreateEntry()), auditStore);
+    }
+
+    private static ApiKeyIdentity CreateIdentity(ApiKeyConstraints constraints)
+    {
+        return new ApiKeyIdentity(
+            KeyId: "operator01",
+            KeyPrefix: "mxgw_operator01",
+            DisplayName: "Operator",
+            Scopes: new HashSet<string>(StringComparer.Ordinal),
+            Constraints: constraints);
+    }
+
+    private static GatewaySession CreateSession()
+    {
+        GatewaySession session = new(
+            "session-1",
+            "mxaccess",
+            "pipe",
+            "nonce",
+            "operator",
+            "client",
+            "correlation",
+            TimeSpan.FromSeconds(30),
+            TimeSpan.FromSeconds(5),
+            TimeSpan.FromSeconds(5),
+            DateTimeOffset.UtcNow);
+        return session;
+    }
+
+    private static GalaxyHierarchyCacheEntry CreateEntry()
+    {
+        IReadOnlyList<GalaxyObject> objects =
+        [
+            new GalaxyObject
+            {
+                GobjectId = 1,
+                TagName = "Area1",
+                ContainedName = "Area1",
+            },
+            new GalaxyObject
+            {
+                GobjectId = 2,
+                TagName = "Pump_001",
+                ContainedName = "Pump",
+                ParentGobjectId = 1,
+                Attributes =
+                {
+                    new GalaxyAttribute
+                        {
+                            AttributeName = "PV",
+                            FullTagReference = "Pump_001.PV",
+                            SecurityClassification = 2,
+                            IsHistorized = true,
+                        },
+                        new GalaxyAttribute
+                        {
+                            AttributeName = "Alarm",
+                            FullTagReference = "Pump_001.Alarm",
+                            IsAlarm = true,
+                        },
+                        new GalaxyAttribute
+                        {
+                            AttributeName = "NonHistorized",
+                            FullTagReference = "Pump_001.NonHistorized",
+                        },
+                    },
+                },
+            new GalaxyObject
+            {
+                GobjectId = 3,
+                TagName = "Other_001",
+                ContainedName = "Other",
+                Attributes =
+                {
+                    new GalaxyAttribute
+                    {
+                        AttributeName = "PV",
+                        FullTagReference = "Other_001.PV",
+                    },
+                },
+            },
+        ];
+
+        return GalaxyHierarchyCacheEntry.Empty with
+        {
+            Status = GalaxyCacheStatus.Healthy,
+            Objects = objects,
+            Index = GalaxyHierarchyIndex.Build(objects),
+            DashboardSummary = DashboardGalaxySummary.Unknown,
+        };
+    }
+
+    private sealed class StubGalaxyHierarchyCache(GalaxyHierarchyCacheEntry current) : IGalaxyHierarchyCache
+    {
+        public GalaxyHierarchyCacheEntry Current { get; } = current;
+
+        public Task RefreshAsync(CancellationToken cancellationToken) => Task.CompletedTask;
+
+        public Task WaitForFirstLoadAsync(CancellationToken cancellationToken) => Task.CompletedTask;
+    }
+
+    private sealed class FakeAuditStore : IApiKeyAuditStore
+    {
+        public List<ApiKeyAuditEntry> Entries { get; } = [];
+
+        public Task AppendAsync(ApiKeyAuditEntry entry, CancellationToken cancellationToken)
+        {
+            Entries.Add(entry);
+            return Task.CompletedTask;
+        }
+
+        public Task<IReadOnlyList<ApiKeyAuditRecord>> ListRecentAsync(int count, CancellationToken cancellationToken)
+        {
+            return Task.FromResult<IReadOnlyList<ApiKeyAuditRecord>>([]);
+        }
+    }
+}

src/MxGateway.Worker.Tests/MxAccess/AlarmCommandExecutorTests.cs

@@ -447,6 +447,13 @@ public sealed class AlarmCommandExecutorTests
             return QueryResult;
         }
 
+        public int PollCount { get; private set; }
+
+        public void PollOnce()
+        {
+            PollCount++;
+        }
+
         public void Dispose() { }
     }
 }

src/MxGateway.Worker.Tests/MxAccess/AlarmCommandHandlerTests.cs

@@ -236,6 +236,13 @@ public sealed class AlarmCommandHandlerTests
 
         public IReadOnlyList<MxAlarmSnapshotRecord> SnapshotActiveAlarms() => SnapshotResult;
 
+        public int PollCount { get; private set; }
+
+        public void PollOnce()
+        {
+            PollCount++;
+        }
+
         public void Dispose()
         {
             Disposed = true;

src/MxGateway.Worker.Tests/MxAccess/AlarmDispatcherTests.cs

@@ -318,6 +318,13 @@ public sealed class AlarmDispatcherTests
             return SnapshotResult;
         }
 
+        public int PollCount { get; private set; }
+
+        public void PollOnce()
+        {
+            PollCount++;
+        }
+
         public void Dispose()
         {
             Disposed = true;

src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 using System.Runtime.InteropServices;
 using System.Threading;
 using System.Threading.Tasks;
@@ -180,6 +181,153 @@ public sealed class MxAccessStaSessionTests
         }
     }
 
+    /// <summary>
+    /// Gap 1: Verifies that when MxAccessStaSession is created with an alarm handler factory,
+    /// a SubscribeAlarms command dispatched through the session reaches the handler.
+    /// This proves the fix in WorkerPipeSession (and the new internal constructor) correctly
+    /// wires the factory rather than leaving alarmCommandHandler null.
+    /// </summary>
+    [Fact]
+    public async Task StartAsync_WithAlarmCommandHandlerFactory_SubscribeAlarmsCommandReachesHandler()
+    {
+        FakeAlarmCommandHandler handler = new();
+        FakeMxAccessComObjectFactory factory = new();
+        FakeMxAccessEventSink eventSink = new();
+        using StaRuntime runtime = CreateRuntime();
+        using MxAccessStaSession session = new(
+            runtime,
+            factory,
+            eventSink,
+            new MxAccessEventQueue(),
+            _eq => handler);
+
+        await session.StartAsync("session-1", workerProcessId: 1);
+
+        StaCommand subscribeCommand = new StaCommand(
+            "session-1",
+            "corr-1",
+            new MxCommand
+            {
+                Kind = MxCommandKind.SubscribeAlarms,
+                SubscribeAlarms = new SubscribeAlarmsCommand
+                {
+                    SubscriptionExpression = @"\\HOST\Galaxy!Area",
+                },
+            });
+
+        MxCommandReply reply = await session.DispatchAsync(subscribeCommand);
+
+        Assert.Equal(ProtocolStatusCode.Ok, reply.ProtocolStatus.Code);
+        Assert.True(handler.IsSubscribed);
+        Assert.Equal(@"\\HOST\Galaxy!Area", handler.LastSubscription);
+    }
+
+    /// <summary>
+    /// Gap 1: Verifies that when MxAccessStaSession is created with the default
+    /// parameterless constructor (no alarm factory), SubscribeAlarms returns
+    /// InvalidRequest with "alarm consumer not configured" diagnostic.
+    /// This validates the baseline before the fix.
+    /// </summary>
+    [Fact]
+    public async Task StartAsync_WithoutAlarmCommandHandlerFactory_SubscribeAlarmsReturnsInvalidRequest()
+    {
+        FakeMxAccessComObjectFactory factory = new();
+        FakeMxAccessEventSink eventSink = new();
+        using StaRuntime runtime = CreateRuntime();
+        // Use the 4-arg (no factory) constructor — equivalent to the old MxAccessStaSession()
+        using MxAccessStaSession session = new(runtime, factory, eventSink);
+
+        await session.StartAsync("session-1", workerProcessId: 1);
+
+        StaCommand subscribeCommand = new StaCommand(
+            "session-1",
+            "corr-1",
+            new MxCommand
+            {
+                Kind = MxCommandKind.SubscribeAlarms,
+                SubscribeAlarms = new SubscribeAlarmsCommand
+                {
+                    SubscriptionExpression = @"\\HOST\Galaxy!Area",
+                },
+            });
+
+        MxCommandReply reply = await session.DispatchAsync(subscribeCommand);
+
+        Assert.Equal(ProtocolStatusCode.InvalidRequest, reply.ProtocolStatus.Code);
+        Assert.Contains("alarm", reply.DiagnosticMessage, StringComparison.OrdinalIgnoreCase);
+    }
+
+    /// <summary>
+    /// Gap 2: Verifies that after StartAsync with an alarm handler factory, the STA poll
+    /// loop calls PollOnce on the handler via the STA within a reasonable timeout.
+    /// This proves polling is driven by the STA rather than the consumer's internal timer.
+    /// </summary>
+    [Fact]
+    public async Task StartAsync_WithAlarmCommandHandlerFactory_PollOnceCalledViaSta()
+    {
+        FakeAlarmCommandHandler handler = new();
+        FakeMxAccessComObjectFactory factory = new();
+        FakeMxAccessEventSink eventSink = new();
+        using StaRuntime runtime = CreateRuntime();
+        using MxAccessStaSession session = new(
+            runtime,
+            factory,
+            eventSink,
+            new MxAccessEventQueue(),
+            _eq => handler);
+
+        await session.StartAsync("session-1", workerProcessId: 1);
+
+        // Wait up to 3s for at least one PollOnce call from the STA poll loop.
+        using CancellationTokenSource timeout = new CancellationTokenSource(TimeSpan.FromSeconds(3));
+        while (handler.PollCount == 0 && !timeout.IsCancellationRequested)
+        {
+            await Task.Delay(50, CancellationToken.None);
+        }
+
+        Assert.True(handler.PollCount > 0,
+            "Expected PollOnce to be called at least once by the STA poll loop within 3 seconds.");
+        Assert.NotNull(handler.LastPollThreadId);
+        Assert.Equal(runtime.StaThreadId, handler.LastPollThreadId);
+    }
+
+    /// <summary>
+    /// Gap 2: Verifies that the STA poll loop stops when the session is disposed —
+    /// no further PollOnce calls after disposal.
+    /// </summary>
+    [Fact]
+    public async Task Dispose_StopsAlarmPollLoop()
+    {
+        FakeAlarmCommandHandler handler = new();
+        FakeMxAccessComObjectFactory factory = new();
+        FakeMxAccessEventSink eventSink = new();
+        using StaRuntime runtime = CreateRuntime();
+        MxAccessStaSession session = new(
+            runtime,
+            factory,
+            eventSink,
+            new MxAccessEventQueue(),
+            _eq => handler);
+
+        await session.StartAsync("session-1", workerProcessId: 1);
+
+        // Wait for at least one poll to occur, then dispose.
+        using CancellationTokenSource initTimeout = new CancellationTokenSource(TimeSpan.FromSeconds(3));
+        while (handler.PollCount == 0 && !initTimeout.IsCancellationRequested)
+        {
+            await Task.Delay(50, CancellationToken.None);
+        }
+
+        Assert.True(handler.PollCount > 0, "Prerequisite: poll loop must have fired before dispose.");
+
+        session.Dispose();
+        int pollCountAtDispose = handler.PollCount;
+
+        // Wait 1 second and verify no further polls occur.
+        await Task.Delay(1000);
+        Assert.Equal(pollCountAtDispose, handler.PollCount);
+    }
+
     /// <summary>
     /// Noop STA COM apartment initializer for testing.
     /// </summary>
@@ -199,4 +347,61 @@ public sealed class MxAccessStaSessionTests
         {
         }
     }
+
+    /// <summary>
+    /// Fake alarm command handler that records calls and tracks poll thread.
+    /// </summary>
+    private sealed class FakeAlarmCommandHandler : IAlarmCommandHandler
+    {
+        private readonly object gate = new object();
+        private int pollCount;
+        private int? lastPollThreadId;
+
+        public bool IsSubscribed { get; private set; }
+        public string? LastSubscription { get; private set; }
+
+        public int PollCount
+        {
+            get { lock (gate) return pollCount; }
+        }
+
+        public int? LastPollThreadId
+        {
+            get { lock (gate) return lastPollThreadId; }
+        }
+
+        public void Subscribe(string subscription, string sessionId)
+        {
+            IsSubscribed = true;
+            LastSubscription = subscription;
+        }
+
+        public void Unsubscribe()
+        {
+            IsSubscribed = false;
+        }
+
+        public int Acknowledge(Guid alarmGuid, string comment, string operatorUser,
+            string operatorNode, string operatorDomain, string operatorFullName)
+            => 0;
+
+        public int AcknowledgeByName(string alarmName, string providerName, string groupName,
+            string comment, string operatorUser, string operatorNode,
+            string operatorDomain, string operatorFullName)
+            => 0;
+
+        public IReadOnlyList<ActiveAlarmSnapshot> QueryActive(string? alarmFilterPrefix)
+            => Array.Empty<ActiveAlarmSnapshot>();
+
+        public void PollOnce()
+        {
+            lock (gate)
+            {
+                pollCount++;
+                lastPollThreadId = Thread.CurrentThread.ManagedThreadId;
+            }
+        }
+
+        public void Dispose() { }
+    }
 }

src/MxGateway.Worker/Ipc/WorkerPipeSession.cs

@@ -48,7 +48,7 @@ public sealed class WorkerPipeSession
             options,
             () => Process.GetCurrentProcess().Id,
             new WorkerPipeSessionOptions(),
-            () => new MxAccessStaSession(),
+            () => new MxAccessStaSession(eq => new AlarmCommandHandler(eq)),
             logger)
     {
     }
@@ -69,7 +69,7 @@ public sealed class WorkerPipeSession
             options,
             processIdProvider,
             new WorkerPipeSessionOptions(),
-            () => new MxAccessStaSession(),
+            () => new MxAccessStaSession(eq => new AlarmCommandHandler(eq)),
             logger: null)
     {
     }
@@ -746,7 +746,7 @@ public sealed class WorkerPipeSession
 
     private async Task<WorkerReady> InitializeMxAccessAsync(CancellationToken cancellationToken)
     {
-        _runtimeSession = new MxAccessStaSession();
+        _runtimeSession = new MxAccessStaSession(eq => new AlarmCommandHandler(eq));
         try
         {
             return await _runtimeSession

src/MxGateway.Worker/MxAccess/AlarmCommandHandler.cs

@@ -160,6 +160,15 @@ public sealed class AlarmCommandHandler : IAlarmCommandHandler
         return filtered;
     }
 
+    /// <inheritdoc />
+    public void PollOnce()
+    {
+        AlarmDispatcher? d;
+        lock (syncRoot) d = dispatcher;
+        // No-op when not yet subscribed or already disposed.
+        d?.PollOnce();
+    }
+
     private AlarmDispatcher GetDispatcherOrThrow()
     {
         if (disposed) throw new ObjectDisposedException(nameof(AlarmCommandHandler));
@@ -226,4 +235,14 @@ public interface IAlarmCommandHandler : IDisposable
     ///     prefix matched against <c>AlarmFullReference</c>.
     /// </summary>
     IReadOnlyList<ActiveAlarmSnapshot> QueryActive(string? alarmFilterPrefix);
+
+    /// <summary>
+    ///     Drives a single poll of the underlying alarm consumer on the
+    ///     caller's thread. This is a no-op when there is no active
+    ///     subscription. In production the caller is the worker's STA
+    ///     (marshalled via <c>StaRuntime.InvokeAsync</c>), which satisfies
+    ///     the <c>ThreadingModel=Apartment</c> requirement of
+    ///     <c>wwAlarmConsumerClass</c>.
+    /// </summary>
+    void PollOnce();
 }

src/MxGateway.Worker/MxAccess/AlarmDispatcher.cs

@@ -119,6 +119,17 @@ public sealed class AlarmDispatcher : IDisposable
             ackOperatorFullName);
     }
 
+    /// <summary>
+    ///     Drives a single synchronous poll of the underlying consumer.
+    ///     Must be called on the STA thread that owns the wnwrap COM object.
+    ///     No-op if the dispatcher has been disposed.
+    /// </summary>
+    public void PollOnce()
+    {
+        if (disposed) return;
+        consumer.PollOnce();
+    }
+
     /// <summary>
     ///     Snapshot the currently-active alarm set as
     ///     <see cref="ActiveAlarmSnapshot"/> protos for the

src/MxGateway.Worker/MxAccess/IMxAccessAlarmConsumer.cs

@@ -85,4 +85,17 @@ public interface IMxAccessAlarmConsumer : IDisposable
     ///     to seed local Part 9 state.
     /// </summary>
     IReadOnlyList<MxAlarmSnapshotRecord> SnapshotActiveAlarms();
+
+    /// <summary>
+    ///     Drives a single synchronous poll of the underlying alarm source.
+    ///     Implementations that use an internal <see cref="System.Threading.Timer"/>
+    ///     are constructed with <c>pollIntervalMilliseconds=0</c> in production so
+    ///     the timer is disabled; the worker's STA drives polls via
+    ///     <c>StaRuntime.InvokeAsync</c> instead, satisfying the
+    ///     <c>ThreadingModel=Apartment</c> requirement of
+    ///     <c>wwAlarmConsumerClass</c>. Fake implementations should no-op.
+    ///     This method must be invoked on the thread that created the consumer
+    ///     (the worker's STA in production).
+    /// </summary>
+    void PollOnce();
 }

src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs

@@ -11,6 +11,8 @@ namespace MxGateway.Worker.MxAccess;
 
 public sealed class MxAccessStaSession : IWorkerRuntimeSession
 {
+    private static readonly TimeSpan AlarmPollInterval = TimeSpan.FromMilliseconds(500);
+
     private readonly IMxAccessComObjectFactory factory;
     private readonly IMxAccessEventSink eventSink;
     private readonly MxAccessEventQueue eventQueue;
@@ -19,6 +21,8 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
     private StaCommandDispatcher? commandDispatcher;
     private MxAccessSession? session;
     private IAlarmCommandHandler? alarmCommandHandler;
+    private CancellationTokenSource? alarmPollCts;
+    private Task? alarmPollTask;
     private bool disposed;
 
     /// <summary>
@@ -32,6 +36,22 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="MxAccessStaSession"/> with default STA runtime,
+    /// factory, and event queue, but with a custom alarm-command handler factory. The factory is
+    /// invoked on the STA thread during
+    /// <see cref="StartAsync(string, int, CancellationToken)"/>; pass <c>null</c> to opt out
+    /// of alarm-side commands.
+    /// </summary>
+    internal MxAccessStaSession(Func<MxAccessEventQueue, IAlarmCommandHandler>? alarmCommandHandlerFactory)
+        : this(
+            new StaRuntime(),
+            new MxAccessComObjectFactory(),
+            new MxAccessEventQueue(),
+            alarmCommandHandlerFactory)
+    {
+    }
+
     /// <summary>
     /// Initializes a new instance of <see cref="MxAccessStaSession"/> with custom STA runtime and factory.
     /// </summary>
@@ -60,6 +80,26 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="MxAccessStaSession"/> with custom event queue
+    /// and an alarm-command handler factory.
+    /// </summary>
+    /// <param name="staRuntime">STA thread runtime.</param>
+    /// <param name="factory">MXAccess COM object factory.</param>
+    /// <param name="eventQueue">Event queue for buffering MXAccess events.</param>
+    /// <param name="alarmCommandHandlerFactory">
+    ///     Factory that constructs the alarm-command handler from the event queue.
+    ///     Pass <c>null</c> to opt out of alarm-side commands.
+    /// </param>
+    public MxAccessStaSession(
+        StaRuntime staRuntime,
+        IMxAccessComObjectFactory factory,
+        MxAccessEventQueue eventQueue,
+        Func<MxAccessEventQueue, IAlarmCommandHandler>? alarmCommandHandlerFactory)
+        : this(staRuntime, factory, new MxAccessBaseEventSink(eventQueue), eventQueue, alarmCommandHandlerFactory)
+    {
+    }
+
     /// <summary>
     /// Initializes a new instance of <see cref="MxAccessStaSession"/> with all dependencies.
     /// </summary>
@@ -122,14 +162,14 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
     /// <param name="workerProcessId">Worker process identifier.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
     /// <returns>Worker ready message.</returns>
-    public Task<WorkerReady> StartAsync(
+    public async Task<WorkerReady> StartAsync(
         string sessionId,
         int workerProcessId,
         CancellationToken cancellationToken = default)
     {
         staRuntime.Start();
 
-        return staRuntime.InvokeAsync(
+        WorkerReady ready = await staRuntime.InvokeAsync(
             () =>
             {
                 if (session is not null)
@@ -151,7 +191,61 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
 
                 return session.CreateWorkerReady(workerProcessId);
             },
-            cancellationToken);
+            cancellationToken).ConfigureAwait(false);
+
+        if (alarmCommandHandler is not null)
+        {
+            alarmPollCts = new CancellationTokenSource();
+            alarmPollTask = RunAlarmPollLoopAsync(alarmCommandHandler, alarmPollCts.Token);
+        }
+
+        return ready;
+    }
+
+    private Task RunAlarmPollLoopAsync(
+        IAlarmCommandHandler handler,
+        CancellationToken cancellationToken)
+    {
+        return Task.Run(async () =>
+        {
+            while (!cancellationToken.IsCancellationRequested)
+            {
+                try
+                {
+                    await Task.Delay(AlarmPollInterval, cancellationToken).ConfigureAwait(false);
+                }
+                catch (OperationCanceledException)
+                {
+                    return;
+                }
+
+                if (cancellationToken.IsCancellationRequested)
+                {
+                    return;
+                }
+
+                try
+                {
+                    await staRuntime.InvokeAsync(
+                        () => handler.PollOnce(),
+                        cancellationToken).ConfigureAwait(false);
+                }
+                catch (OperationCanceledException)
+                {
+                    return;
+                }
+                catch (ObjectDisposedException)
+                {
+                    // STA runtime or alarm handler disposed — stop the loop gracefully.
+                    return;
+                }
+                catch (InvalidOperationException)
+                {
+                    // STA runtime shutting down — stop the loop gracefully.
+                    return;
+                }
+            }
+        }, CancellationToken.None);
     }
 
     /// <summary>
@@ -307,6 +401,30 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
 
         commandDispatcher?.RequestShutdown();
 
+        // Cancel the STA poll loop before disposing the alarm handler.
+        // The loop references the alarm handler and must be stopped first
+        // so that no further PollOnce calls race with disposal.
+        CancellationTokenSource? pollCtsToDispose = alarmPollCts;
+        Task? pollTaskToAwait = alarmPollTask;
+        alarmPollCts = null;
+        alarmPollTask = null;
+        if (pollCtsToDispose is not null)
+        {
+            pollCtsToDispose.Cancel();
+            if (pollTaskToAwait is not null)
+            {
+                try
+                {
+                    await pollTaskToAwait.ConfigureAwait(false);
+                }
+                catch
+                {
+                    // Swallow — poll loop cancellation must not block data shutdown.
+                }
+            }
+            pollCtsToDispose.Dispose();
+        }
+
         // Stop the alarm consumer's polling timer and tear down the
         // dispatcher BEFORE the data-side cleanup begins. The alarm
         // consumer holds a wnwrap COM RCW that needs the STA pump to
@@ -382,6 +500,16 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
 
         RequestShutdown();
 
+        // Cancel and discard the STA poll loop.
+        CancellationTokenSource? pollCtsToDispose = alarmPollCts;
+        alarmPollCts = null;
+        alarmPollTask = null;
+        if (pollCtsToDispose is not null)
+        {
+            try { pollCtsToDispose.Cancel(); } catch { }
+            try { pollCtsToDispose.Dispose(); } catch { }
+        }
+
         IAlarmCommandHandler? alarmHandlerToDispose = alarmCommandHandler;
         alarmCommandHandler = null;
         if (alarmHandlerToDispose is not null)

src/MxGateway.Worker/MxAccess/WnWrapAlarmConsumer.cs

@@ -63,8 +63,16 @@ public sealed class WnWrapAlarmConsumer : IMxAccessAlarmConsumer
     private bool subscribed;
     private bool disposed;
 
+    /// <summary>
+    ///     Production constructor — creates the wnwrap COM object on the
+    ///     current thread (must be the worker's STA) and disables the
+    ///     internal <see cref="Timer"/> (<c>pollIntervalMilliseconds=0</c>).
+    ///     Polling is driven externally by the STA via
+    ///     <c>StaRuntime.InvokeAsync(() =&gt; consumer.PollOnce())</c> so
+    ///     that every COM call stays on the STA that owns the apartment.
+    /// </summary>
     public WnWrapAlarmConsumer()
-        : this(new wwAlarmConsumerClass(), DefaultPollIntervalMilliseconds, DefaultMaxAlarmsPerFetch)
+        : this(new wwAlarmConsumerClass(), pollIntervalMilliseconds: 0, DefaultMaxAlarmsPerFetch)
     {
     }