fix(client/rust): handle provider_status arm (build break); real system-roots TLS; design doc (Client.Rust-030..032)

clients/rust/RustClientDesign.md

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