docs(index): HistorianGateway SendEvent amortized via the event-session pool

test: cover GalaxyBrowseProjector, GalaxyDeployNotifier, GalaxyHierarchyRefreshService (ported from mxaccessgw on adoption)
docs(index): HistorianGateway browse/metadata now amortized through the session pool
2026-06-25 12:37:44 -04:00 · 2026-06-25 12:28:34 -04:00 · 2026-06-25 11:09:43 -04:00 · 2026-06-25 10:55:57 -04:00 · 2026-06-25 10:54:51 -04:00 · 2026-06-25 10:48:34 -04:00
300 changed files with 169100 additions and 205 deletions
@@ -6,9 +6,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

 `scadaproj` is primarily an umbrella/index workspace that aggregates a family of
 related SCADA / OT / Wonderware / OPC UA "sister projects" that live as **sibling
-directories under `~/Desktop/`**. It now also **hosts two pieces of source itself** —
-the shared [`ZB.MOM.WW.Auth/`](ZB.MOM.WW.Auth/) library and the shared
-[`ZB.MOM.WW.Theme/`](ZB.MOM.WW.Theme/) UI kit — both the realized output of their
+directories under `~/Desktop/`**. It now also **hosts six pieces of source itself** —
+the shared [`ZB.MOM.WW.Auth/`](ZB.MOM.WW.Auth/) library, the shared
+[`ZB.MOM.WW.Theme/`](ZB.MOM.WW.Theme/) UI kit, the shared
+[`ZB.MOM.WW.Health/`](ZB.MOM.WW.Health/) health-check library, the shared
+[`ZB.MOM.WW.Telemetry/`](ZB.MOM.WW.Telemetry/) observability library, the shared
+[`ZB.MOM.WW.Configuration/`](ZB.MOM.WW.Configuration/) config-validation library, and the new
+[`ZB.MOM.WW.GalaxyRepository/`](ZB.MOM.WW.GalaxyRepository/) Galaxy browse library — all the realized output of their
 respective component normalizations (see [Component normalization](#component-normalization)).
 The point of this file is to give a high-level scan of each sister project — its purpose,
 location, stack, and primary commands — so a fresh Claude Code session can orient across
@@ -27,9 +31,10 @@ own `CLAUDE.md` for the full picture. See [Refreshing this index](#refreshing-th

 | Project | Location | Stack | Repo | Summary |
 |---|---|---|---|---|
-| **OtOpcUa** | `~/Desktop/OtOpcUa` | .NET 10, OPC UA, gRPC | `gitea.dohertylan.com/dohertj2/lmxopcua` | OPC UA server that exposes AVEVA System Platform (Wonderware) Galaxy tags as an OPC UA address space. Galaxy access flows through an in-process `GalaxyDriver` → gRPC → the **mxaccessgw** gateway. |
+| **OtOpcUa** | `~/Desktop/OtOpcUa` | .NET 10, OPC UA, gRPC | `gitea.dohertylan.com/dohertj2/lmxopcua` | OPC UA server that exposes industrial data sources under a **unified Equipment-based address space** — native-protocol drivers (Modbus, S7, AB CIP/Legacy, TwinCAT, FOCAS, OpcUaClient) **and AVEVA System Platform (Wonderware) Galaxy, now a standard Equipment-kind driver** (the old SystemPlatform mirror / alias-tag model was retired ~2026-06-12). Galaxy access flows through the in-process `GalaxyDriver` → gRPC → the **mxaccessgw** gateway. Surfaces live read + authorized write, native OPC UA Part 9 alarms, and server-side HistoryRead. |
 | **MxAccessGateway** (`mxaccessgw`) | `~/Desktop/MxAccessGateway` | .NET 10 gateway (x64) + .NET 4.8 worker (**x86**), gRPC | `gitea.dohertylan.com/dohertj2/mxaccessgw` | gRPC gateway giving modern clients full MXAccess parity without loading 32-bit COM. Two-process: gateway (ASP.NET Core gRPC + Blazor dashboard) + per-session x86 worker that owns the MXAccess COM STA. **OtOpcUa depends on this.** |
 | **ScadaBridge** | `~/Desktop/ScadaBridge` | .NET 10, Akka.NET, Docker | _git_ | Full implementation of the distributed SCADA platform — hub-and-spoke (1 central cluster + N site clusters). Projects prefixed `ZB.MOM.WW.ScadaBridge.*`; solution `ZB.MOM.WW.ScadaBridge.slnx`. Ships `src/`, `tests/`, `docker/` topology, and the design docs that are the spec. |
+| **HistorianGateway** | `~/Desktop/HistorianGateway` | .NET 10 x64, gRPC, Blazor | `gitea.dohertylan.com/dohertj2/historiangw` | Single-process gRPC sidecar exposing (1) full read/write API to the AVEVA Historian (5 gRPC services; 15 retrieval modes; historical/backfill writes; tag-config lifecycle; SQL live-value path; store-forward + redundancy resilience; all default-disabled) and (2) read-only Galaxy object-hierarchy browse via the shared `ZB.MOM.WW.GalaxyRepository` lib (consumed as a Gitea-feed package). No COM, no x86 worker. **Dev:** two plaintext endpoints from `appsettings.Development.json` — dashboard on `:5220` (HTTP/1.1), gRPC h2c on `:5221`. **Production:** single `Kestrel:Endpoints:Https` endpoint with `Protocols: Http1AndHttp2` multiplexes dashboard + gRPC over one TLS port (ALPN); warn-only if no TLS endpoint configured (valid behind a reverse proxy / Kubernetes ingress; the warn predicate covers any non-Development environment, i.e. Production + Staging). In a non-Development environment the gateway also logs warn-only **production-readiness** checks (pending.md D2/D3) — relative runtime-artifact paths + secret hygiene (`ApiKeys:Mode=Disabled`, empty/dev-placeholder pepper, dev-placeholder LDAP password). Vendors `AVEVA.Historian.Client` from `histsdk`. Store-forward uses a crash-safe FasterLog append-only outbox (`Microsoft.FASTER.Core` 2.6.5; `CommitMode` PerEntry/Periodic), not SQLite. **Handshake amortization (pending.md A1) done + live-validated** — a default-on leased-session pool (`Historian:SessionPool`) reuses pre-authenticated sessions across reads/writes/status ops/tag-browse/metadata (~4.7× measured; probe and blocks stay per-call), with a `<~15 s` keepalive + reactive re-auth, surfaced via a `PooledHistorianClient` facade so services are unchanged; the `HistorianSession` primitive is upstream in the vendored `AVEVA.Historian.Client` (re-vendored @ `be60d0b`); browse/metadata broadened on branch `feat/amortization-broadening`. **`SendEvent` is also amortized** via a **separate, parallel event-session pool** (`Historian:EventSessionPool`, default-on; v8/ECDH auth — kept distinct from the v6 pool), warranted by a GREEN v8 Event-session reuse spike (~10–16×); `ReadEvents` stays per-call / gated (C2). The full offline suite is green on macOS (0 warnings); the env-gated live historian + Galaxy integration suite exercises the amortized path and otherwise skips without a live server. |

 ## Cross-project relationships

@@ -81,8 +86,10 @@ the gateway uses `MxGateway.*`). The common subject is **AVEVA System Platform (
  `GalaxyRepositoryClient` for the static hierarchy, and an MXAccess session
  (`MxCommand`/`MxEvent` protos) for live read/write/subscribe. A `DeployWatcher` polls the
  gateway's deploy-event signal to rebuild the OPC UA address space on Galaxy redeploy.
-  OtOpcUa's job is purely a **protocol bridge**: it republishes Galaxy as an OPC UA address
-  space for *any* OPC UA client.
+  OtOpcUa's job is a **protocol bridge**: it republishes Galaxy — now bound as a *standard
+  Equipment-kind driver* alongside its native-protocol drivers, not a special SystemPlatform
+  mirror — as an OPC UA address space (live values, Part 9 alarms, HistoryRead) for *any* OPC
+  UA client.
 - **ScadaBridge → OPC UA** (OPC UA client). ScadaBridge's DCL has an OPC UA adapter that
  collects data and mirrors native OPC UA Alarms & Conditions. OtOpcUa is exactly such a
  server, so ScadaBridge can ingest Wonderware data **indirectly via OtOpcUa**.
@@ -98,15 +105,21 @@ the gateway uses `MxGateway.*`). The common subject is **AVEVA System Platform (
 - ScadaBridge has **two paths** to the same Wonderware data: (1) OPC UA → OtOpcUa →
  gateway, or (2) MxGateway adapter → gateway directly. Path 1 gives standards-based OPC UA
  decoupling; path 2 gives a more direct/native feed.
+- **HistorianGateway is a new, independent sidecar** (no runtime coupling to the three above).
+  It reaches the Historian via its vendored gRPC client and the Galaxy Repository SQL DB directly,
+  not through `mxaccessgw`. It consumes the shared `ZB.MOM.WW.GalaxyRepository` lib
+  (cross-repo `ProjectReference`). Any client that needs Historian data or Galaxy browse can
+  target HistorianGateway independently; it is not a dependency of OtOpcUa or ScadaBridge today.
 - Coupling is loose: each repo references the others only as **sibling context** (the
  `## Sister Projects` note in ScadaBridge's own `CLAUDE.md` lists `MxAccessGateway` and
  `OtOpcUa` with their Gitea URLs but states they are *not part of its solution*).
 - **The break surface is the wire contracts, not code.** Because coupling is by network
  protocol, the things that break across repo boundaries are: the gateway's `.proto` files
-  (`mxaccess_gateway.proto`, `mxaccess_worker.proto`, `galaxy_repository.proto`), and the
-  OPC UA address-space shape OtOpcUa publishes (browse paths, node IDs, A&C alarm model).
-  Changes to any of these must be coordinated across the affected repos — a green build in
-  one repo does not prove the others still interoperate.
+  (`mxaccess_gateway.proto`, `mxaccess_worker.proto`, `galaxy_repository.proto`), the
+  `historian_gateway.v1` proto (HistorianGateway's own contract), and the OPC UA address-space
+  shape OtOpcUa publishes (browse paths, node IDs, A&C alarm model). Changes to any of these
+  must be coordinated across the affected repos — a green build in one repo does not prove the
+  others still interoperate.

 ## Component normalization

@@ -117,8 +130,13 @@ each project's **code-verified current state**, and the **gaps** between. See

 | Component | Status | Goal | Design | Implementation |
 |---|---|---|---|---|
-| Auth (login / identity / authz) | Built (lib `0.1.0`) | Shared `ZB.MOM.WW.Auth` lib | [`components/auth/`](components/auth/) | [`ZB.MOM.WW.Auth/`](ZB.MOM.WW.Auth/) |
-| UI Theme (layout / tokens / components) | Built (lib `0.1.0`) | Shared `ZB.MOM.WW.Theme` RCL | [`components/ui-theme/`](components/ui-theme/) | [`ZB.MOM.WW.Theme/`](ZB.MOM.WW.Theme/) |
+| Auth (login / identity / authz) | Adopted (lib `0.1.3`; all 3 apps, merged to **local default** main/master + **pushed to origin** (gitea)) | Shared `ZB.MOM.WW.Auth` lib | [`components/auth/`](components/auth/) | [`ZB.MOM.WW.Auth/`](ZB.MOM.WW.Auth/) |
+| UI Theme (layout / tokens / components) | Adopted (lib `0.2.0`; all 3 apps, merged to **local default** + **pushed to origin** (gitea)) | Shared `ZB.MOM.WW.Theme` RCL | [`components/ui-theme/`](components/ui-theme/) | [`ZB.MOM.WW.Theme/`](ZB.MOM.WW.Theme/) |
+| Health (readiness / liveness / active-node) | Built (lib `0.1.0`) | Shared `ZB.MOM.WW.Health` lib | [`components/health/`](components/health/) | [`ZB.MOM.WW.Health/`](ZB.MOM.WW.Health/) |
+| Observability (metrics / traces / logs) | Built (lib `0.1.0`) | Shared `ZB.MOM.WW.Telemetry` lib + `.Serilog` | [`components/observability/`](components/observability/) | [`ZB.MOM.WW.Telemetry/`](ZB.MOM.WW.Telemetry/) |
+| Config + validation (options / startup validation) | Adopted (lib `0.1.0`; all 3 apps, local) | Shared `ZB.MOM.WW.Configuration` lib | [`components/configuration/`](components/configuration/) | [`ZB.MOM.WW.Configuration/`](ZB.MOM.WW.Configuration/) |
+| Audit (event model + writer seam) | Adopted (lib `0.1.0`; all 3 apps, merged to **local default** main/master + **pushed to origin** (gitea)) | Shared `ZB.MOM.WW.Audit` lib | [`components/audit/`](components/audit/) | [`ZB.MOM.WW.Audit/`](ZB.MOM.WW.Audit/) |
+| Galaxy Repository (object-hierarchy SQL browse + gRPC service) | Built (lib `0.1.0`, **published to the Gitea feed**; consumed by HistorianGateway as a feed `PackageReference`) | Shared `ZB.MOM.WW.GalaxyRepository` lib | _(design in histsdk + design doc 2026-06-23)_ | [`ZB.MOM.WW.GalaxyRepository/`](ZB.MOM.WW.GalaxyRepository/) |

 The auth component is fully populated: a normalized [`spec`](components/auth/spec/SPEC.md), a
 proposed [`shared-contract`](components/auth/shared-contract/ZB.MOM.WW.Auth.md), three
@@ -130,7 +148,14 @@ The shared library is **built and lives in this repo** at [`ZB.MOM.WW.Auth/`](ZB
 (its own nested git repo; .NET 10; 4 packages — `Abstractions`, `Ldap`, `ApiKeys`, `AspNetCore`;
 172 tests; `dotnet pack` → 4 nupkgs @ 0.1.0). The implementation plan is at
 [`docs/plans/2026-06-01-zb-mom-ww-auth-shared-library.md`](docs/plans/2026-06-01-zb-mom-ww-auth-shared-library.md).
-**Not yet adopted** by the three apps — that's the follow-on tracked in [`components/auth/GAPS.md`](components/auth/GAPS.md) (#8).
+**Adopted across all three apps on 2026-06-02** (auth GAPS #1–#8) on each repo's `feat/adopt-zb-auth` branch —
+committed + reviewed, then **fast-forward-merged into the repo's local default (main/master) and PUSHED to origin
+(gitea) on 2026-06-03** (in sync; the `feat/*` branches kept locally as history). Cutover: shared `Auth.Ldap`,
+`Auth.ApiKeys` (ScadaBridge inbound fully re-architected to the keyId/Bearer model), `IGroupRoleMapper<TRole>` seam,
+`Transport`-enum config, canonical `ZbClaimTypes`/`ZbCookieDefaults`, unified dev base DN `dc=zb,dc=local`, and the
+canonical-six role vocabulary (with ScadaBridge's accepted auditor/admin SoD collapse). Consumer pins: OtOpcUa `0.1.1`,
+MxGateway `0.1.2`, ScadaBridge `0.1.3`. Per-repo detail in [`components/auth/GAPS.md`](components/auth/GAPS.md) +
+`docs/plans/2026-06-02-auth-audit-normalization*.md`.
 Build/test from `ZB.MOM.WW.Auth/`: `dotnet test`. Consumer matrix: OtOpcUa → Abstractions+Ldap+AspNetCore;
 MxAccessGateway & ScadaBridge → all four (ApiKeys not used by OtOpcUa).

@@ -142,13 +167,130 @@ backlog. Shared = Technical-Light tokens + IBM Plex fonts + side-rail shell + wi
 per-project = each app's `site.css` page layout, route content, scoped `.razor.css`.

 The shared RCL is **built and lives in this repo** at [`ZB.MOM.WW.Theme/`](ZB.MOM.WW.Theme/)
-(.NET 10 Razor Class Library; single package; 32 bUnit tests; `dotnet pack` → 1 nupkg @ 0.1.0).
-The implementation plan is at
-[`docs/plans/2026-06-01-zb-mom-ww-theme-shared-library.md`](docs/plans/2026-06-01-zb-mom-ww-theme-shared-library.md).
-**Not yet adopted** by the three apps — that's the follow-on tracked in [`components/ui-theme/GAPS.md`](components/ui-theme/GAPS.md).
+(.NET 10 Razor Class Library; single package; 44 bUnit tests; `dotnet pack` → 1 nupkg @ 0.2.0,
+**published to the Gitea feed**). The build plan is at
+[`docs/plans/2026-06-01-zb-mom-ww-theme-shared-library.md`](docs/plans/2026-06-01-zb-mom-ww-theme-shared-library.md);
+the adoption plan at [`docs/plans/2026-06-03-ui-theme-adoption.md`](docs/plans/2026-06-03-ui-theme-adoption.md).
+**Adopted across all three apps on 2026-06-03** (full canonical cutover, SPEC §7) on each repo's
+`feat/adopt-zb-theme` branch — committed + spec/code-reviewed, then **fast-forward-merged into each repo's local
+default (master/main) and PUSHED to origin (gitea)** (in sync; `feat/*` kept locally as history): OtOpcUa
+→`lmxopcua` `master`@`11de14d`, ScadaBridge `main`@`58352a6`, MxGateway→`mxaccessgw` `main`@`73e54e2`. The `0.1.0 → 0.2.0` bump first promoted nav-expand persistence
+into the kit (`NavRailSection.Key`/`data-nav-key` + a localStorage `nav-state.js` enhancer emitted by a new
+`<ThemeScripts/>`), so all three apps share one persistence mechanism (OtOpcUa's bespoke cookie/JS-interop nav
+island retired); MxGateway additionally gained a net-new Blazor `<LoginCard>` `/login` page over its existing
+hardened endpoint. Per-app result in [`components/ui-theme/GAPS.md`](components/ui-theme/GAPS.md).
 Build/test from `ZB.MOM.WW.Theme/`: `dotnet test`. Consumer matrix: all three apps consume
 the single `ZB.MOM.WW.Theme` package (OtOpcUa AdminUI, MxGateway Server, ScadaBridge Host + CentralUI).

+The health component is fully populated: a normalized [`spec`](components/health/spec/SPEC.md), a
+[`shared-contract`](components/health/shared-contract/ZB.MOM.WW.Health.md), three
+[`current-state`](components/health/current-state/) docs, and an adoption [`GAPS`](components/health/GAPS.md)
+backlog. Shared = three-tier endpoint convention (ready/active/healthz) + canonical JSON writer +
+`IActiveNodeGate` seam + `GrpcDependencyHealthCheck` + `AkkaClusterHealthCheck` + `ActiveNodeHealthCheck`
+ `DatabaseHealthCheck<TContext>`; left per-project = which probes each app registers,
+orchestrator wiring, and ScadaBridge's distributed health-monitoring pipeline.
+
+The shared library is **built and lives in this repo** at [`ZB.MOM.WW.Health/`](ZB.MOM.WW.Health/)
+(.NET 10; 3 packages — `ZB.MOM.WW.Health`, `ZB.MOM.WW.Health.Akka`, `ZB.MOM.WW.Health.EntityFrameworkCore`;
+58 tests; `dotnet pack` → 3 nupkgs @ 0.1.0).
+**Not yet adopted** by the three apps — that's the follow-on tracked in [`components/health/GAPS.md`](components/health/GAPS.md).
+Build/test from `ZB.MOM.WW.Health/`: `dotnet test`. Consumer matrix: MxAccessGateway → core only;
+OtOpcUa & ScadaBridge → all three packages.
+
+The observability component is fully populated: a normalized [`spec`](components/observability/spec/SPEC.md),
+a [`metric-conventions`](components/observability/spec/METRIC-CONVENTIONS.md) reference, a
+[`shared-contract`](components/observability/shared-contract/ZB.MOM.WW.Telemetry.md), three
+[`current-state`](components/observability/current-state/) docs, and an adoption [`GAPS`](components/observability/GAPS.md)
+backlog. Shared = OTel Resource (service.name/site.id/node.role identity triple) + standard instrumentation
+(ASP.NET Core, HttpClient, gRPC client, runtime, process) + Prometheus always-on exporter + OTLP opt-in
+ Serilog two-stage bootstrap + SiteId/NodeRole/NodeHostname enrichers + TraceContextEnricher (trace_id/span_id)
+ ILogRedactor seam; left per-project = application Meters/ActivitySources, sink config, per-operation
+enrichers, and redaction policies.
+
+The shared library is **built and lives in this repo** at [`ZB.MOM.WW.Telemetry/`](ZB.MOM.WW.Telemetry/)
+(.NET 10; 2 packages — `ZB.MOM.WW.Telemetry`, `ZB.MOM.WW.Telemetry.Serilog`; 19 tests;
+`dotnet pack` → 2 nupkgs @ 0.1.0). **Adopted across all three apps on 2026-06-01** (branch
+`feat/adopt-zb-telemetry` per repo, behaviour-preserving): `AddZbTelemetry` (Resource + standard
+instrumentation + Prometheus `/metrics`) everywhere; OtOpcUa + MxGateway on `AddZbSerilog` (MxGateway's
+MEL→Serilog migration + metrics export both landed in this pass — they were *not* actually done
+beforehand despite an earlier claim); ScadaBridge keeps its `LoggerConfigurationFactory` (min-level
+governance) and only adds the shared `TraceContextEnricher`. Deferred: MxGateway `ms`→`s` + Meter
+rename, ScadaBridge app instruments + Site-node HTTP/1.1 metrics listener, OTLP wiring. Per-repo
+result tracked in [`components/observability/GAPS.md`](components/observability/GAPS.md).
+Build/test from `ZB.MOM.WW.Telemetry/`: `dotnet test`. Consumer matrix: all three apps consume both
+packages after adoption (OtOpcUa, MxGateway Server, ScadaBridge Host + any instrumented project).
+
+The configuration component is fully populated: a normalized [`spec`](components/configuration/spec/SPEC.md), a
+[`shared-contract`](components/configuration/shared-contract/ZB.MOM.WW.Configuration.md), three
+[`current-state`](components/configuration/current-state/) docs, and an adoption [`GAPS`](components/configuration/GAPS.md)
+backlog. Shared = the `IValidateOptions<T>` failure-accumulation base (`OptionsValidatorBase<T>`) +
+reusable rule primitives (`ValidationBuilder`: port / host:port / required / positive-duration / one-of /
+min-count) + `AddValidatedOptions<TOptions,TValidator>()` (bind + validate + `ValidateOnStart`) + the
+pre-host `ConfigPreflight` aggregator (generalizes ScadaBridge's `StartupValidator`, byte-compatible
+message); left per-project = each app's options classes + domain rules, and OtOpcUa's
+draft/generation-content validation (DB-side `sp_ValidateDraft`; its C# `DraftValidator` is dormant).
+
+The shared library is **built and lives in this repo** at [`ZB.MOM.WW.Configuration/`](ZB.MOM.WW.Configuration/)
+(.NET 10; single package `ZB.MOM.WW.Configuration`; 27 tests; `dotnet pack` → 1 nupkg @ 0.1.0).
+The implementation plan is at
+[`docs/plans/2026-06-01-zb-mom-ww-configuration-shared-library.md`](docs/plans/2026-06-01-zb-mom-ww-configuration-shared-library.md).
+**Adopted across all three apps on 2026-06-01** (OtOpcUa, MxAccessGateway, ScadaBridge) on each repo's
+local default branch (`main`/`master`) — merged, **not yet pushed** to remotes; the package was first
+published to the Gitea feed. Behaviour-preserving onto `OptionsValidatorBase`/`AddValidatedOptions`
+for MxGateway + ScadaBridge (validator messages byte-identical), `StartupValidator` → `ConfigPreflight`
+for ScadaBridge, and net-new `Ldap`/`OpcUa` validators for OtOpcUa. Per-app result tracked in
+[`components/configuration/GAPS.md`](components/configuration/GAPS.md).
+Build/test from `ZB.MOM.WW.Configuration/`: `dotnet test`. Consumer matrix: all three apps consume the
+single package; ScadaBridge is the heaviest adopter (per-module validators + `StartupValidator` →
+`ConfigPreflight`); OtOpcUa adoption is additive (it has no `IValidateOptions` usage today).
+
+The audit component is fully populated: a normalized [`spec`](components/audit/spec/SPEC.md), an
+[`event-model`](components/audit/spec/EVENT-MODEL.md) reference, a
+[`shared-contract`](components/audit/shared-contract/ZB.MOM.WW.Audit.md), three
+[`current-state`](components/audit/current-state/) docs, and an adoption [`GAPS`](components/audit/GAPS.md)
+backlog. Common ground = canonical `AuditEvent` record + `AuditOutcome` enum + `IAuditWriter` /
+`IAuditRedactor` seams + helpers (`NullAuditRedactor`, `TruncatingAuditRedactor`, `NoOpAuditWriter`,
+`CompositeAuditWriter`, `RedactingAuditWriter`) + `AddZbAudit` DI registration; left per-project =
+transport/storage and domain vocabulary. Closes the loop on Auth — audit's `Actor` field = the Auth
+principal. `IAuditRedactor` is aligned with Telemetry's `ILogRedactor` seam convention.
+
+The shared library is **built and lives in this repo** at [`ZB.MOM.WW.Audit/`](ZB.MOM.WW.Audit/)
+(.NET 10; 1 package — `ZB.MOM.WW.Audit`; only non-BCL dependency `Microsoft.Extensions.DependencyInjection.Abstractions`;
+19 tests; `dotnet pack` → 1 nupkg @ 0.1.0). Repo: `https://gitea.dohertylan.com/dohertj2/zb-mom-ww-audit`.
+**Adopted across all three apps on 2026-06-02** (audit GAPS #1–#6) on each repo's `feat/adopt-zb-audit` branch
+(stacked on `feat/adopt-zb-auth`) — committed + reviewed, then **merged into the repo's local default (main/master)
+and PUSHED to origin (gitea) on 2026-06-03** (in sync). Depth =
+**DEEP adopt** (the canonical 9-field `AuditEvent` is the record everywhere; domain fields ride in `DetailsJson`).
+OtOpcUa: canonical record + `AuditWriterActor : IAuditWriter` + `Outcome` column/migration + `ClusterAudit` fix.
+MxGateway: new canonical SQLite `audit_event` store + `IAuditWriter` + `IApiKeyAuditStore`→canonical adapter.
+**ScadaBridge: a full audit-subsystem re-architecture** (the program's largest task) — canonical record everywhere via a
+deterministic codec; site SQLite split into `audit_event` + an `audit_forward_state` forwarding sidecar; central
+partitioned `dbo.AuditLog` collapsed to 10 canonical cols + persisted computed cols (`CollapseAuditLogToCanonical`
+migration, MSSQL-verified). Phase 3 wires `Actor` from the Auth principal at authenticated emit sites (per-app
+`IAuditActorAccessor`). Per-repo detail in [`components/audit/GAPS.md`](components/audit/GAPS.md) +
+`docs/plans/2026-06-02-auth-audit-normalization-phase2-deep.md` + `…-scadabridge-audit-rearch.md`.
+Build/test from `ZB.MOM.WW.Audit/`: `dotnet test`. Consumer matrix: all three apps consume the single
+`ZB.MOM.WW.Audit` package (OtOpcUa, MxAccessGateway, ScadaBridge — DEEP-adopted as the canonical record).
+
+The Galaxy Repository component normalizes the **Galaxy object-hierarchy SQL browse + reusable gRPC service**
+that was previously embedded in `mxaccessgw`. Shared = canonical `galaxy_repository.v1` proto (wire-compatible
+with `mxaccessgw`'s existing contract so OtOpcUa's `GalaxyRepositoryClient` is unaffected), the SQL browse
+provider (`HierarchySql` / `AttributesSql` validated reverse-engineered queries), in-memory hierarchy cache +
+snapshot + deploy-poll refresh `BackgroundService`, `GalaxyHierarchyProjector`, and `AddZbGalaxyRepository` /
+`MapZbGalaxyRepository` DI extension. Left per-consumer = section path, subtree auth filtering, and any
+app-specific paging defaults.
+
+The shared library is **built and lives in this repo** at [`ZB.MOM.WW.GalaxyRepository/`](ZB.MOM.WW.GalaxyRepository/)
+(.NET 10; single package `ZB.MOM.WW.GalaxyRepository`; `dotnet pack` → 1 nupkg @ 0.1.0, **published to
+the Gitea NuGet feed** `gitea.dohertylan.com/api/packages/dohertj2/nuget`). The design doc is at
+[`docs/plans/2026-06-23-historian-gateway-design.md`](docs/plans/2026-06-23-historian-gateway-design.md) (§10, component 1).
+**Consumed by HistorianGateway** as a `PackageReference` from that Gitea feed, pinned at `0.1.0` (originally a
+cross-repo `ProjectReference` to this scadaproj tree; switched to the feed package 2026-06-24).
+**mxaccessgw adoption is a tracked follow-on** — once adopted, mxaccessgw's inline Galaxy browse code is replaced
+by the shared lib (the `galaxy_repository.v1` wire contract is already identical, so OtOpcUa and ScadaBridge
+clients are unaffected). Build/test from `ZB.MOM.WW.GalaxyRepository/`: `dotnet test`.
+Consumer matrix: HistorianGateway (initial); mxaccessgw (follow-on adoption).
+
 ## Per-project primary commands

 Run these from inside each project directory (not from `scadaproj`).
@@ -169,9 +311,23 @@ dotnet run   --project src/MxGateway.Server/MxGateway.Server.csproj
 # ScadaBridge  (~/Desktop/ScadaBridge)
 dotnet build ZB.MOM.WW.ScadaBridge.slnx
 bash docker/deploy.sh        # rebuild + redeploy the 8-node cluster
-cd infra && docker compose up -d   # local test services (LDAP, SQL, OPC UA, SMTP, REST, Traefik)
+cd infra && docker compose up -d   # local test services (SQL, OPC UA, SMTP, REST, Traefik) — LDAP is NOT here
+
+# HistorianGateway  (~/Desktop/HistorianGateway)
+dotnet build ZB.MOM.WW.HistorianGateway.slnx
+dotnet test  ZB.MOM.WW.HistorianGateway.slnx   # unit + golden; live integration tests skip without env vars
+dotnet run --project src/ZB.MOM.WW.HistorianGateway.Server/ZB.MOM.WW.HistorianGateway.Server.csproj
+# Dev: dashboard on :5220 (HTTP/1.1), gRPC h2c on :5221 (from appsettings.Development.json)
+# Production: single Kestrel:Endpoints:Https with Protocols=Http1AndHttp2 (ALPN, one TLS port)
+# Live integration (need HISTORIAN_GRPC_HOST + HISTORIAN_GRPC_WRITE_SANDBOX_TAG + GALAXY_SQL_CONNSTR set)
+dotnet test ZB.MOM.WW.HistorianGateway.slnx --filter "Category=LiveIntegration"
 ```

+> **Shared GLAuth (all three apps + HistorianGateway):** LDAP auth for every local dev/test stack is provided by a
+> single `zb-shared-glauth` container on the Linux fixture host **`10.100.0.35:3893`**
+> (`baseDN dc=zb,dc=local`, Transport=None). Source of truth and deploy runbook:
+> [`scadaproj/infra/glauth/`](infra/glauth/) (`config.toml` + `docker-compose.yml` + `README.md`).
+
 ## Refreshing this index

 This file is meant to be re-scanned when `scadaproj` is opened in Claude Code:
@@ -0,0 +1,482 @@
+## Ignore Visual Studio temporary files, build results, and
+## files generated by popular Visual Studio add-ons.
+##
+## Get latest from `dotnet new gitignore`
+
+# dotenv files
+.env
+
+# User-specific files
+*.rsuser
+*.suo
+*.user
+*.userosscache
+*.sln.docstates
+
+# User-specific files (MonoDevelop/Xamarin Studio)
+*.userprefs
+
+# Mono auto generated files
+mono_crash.*
+
+# Build results
+[Dd]ebug/
+[Dd]ebugPublic/
+[Rr]elease/
+[Rr]eleases/
+x64/
+x86/
+[Ww][Ii][Nn]32/
+[Aa][Rr][Mm]/
+[Aa][Rr][Mm]64/
+bld/
+[Bb]in/
+[Oo]bj/
+[Ll]og/
+[Ll]ogs/
+
+# Visual Studio 2015/2017 cache/options directory
+.vs/
+# Uncomment if you have tasks that create the project's static files in wwwroot
+#wwwroot/
+
+# Visual Studio 2017 auto generated files
+Generated\ Files/
+
+# MSTest test Results
+[Tt]est[Rr]esult*/
+[Bb]uild[Ll]og.*
+
+# NUnit
+*.VisualState.xml
+TestResult.xml
+nunit-*.xml
+
+# Build Results of an ATL Project
+[Dd]ebugPS/
+[Rr]eleasePS/
+dlldata.c
+
+# Benchmark Results
+BenchmarkDotNet.Artifacts/
+
+# .NET
+project.lock.json
+project.fragment.lock.json
+artifacts/
+
+# Tye
+.tye/
+
+# ASP.NET Scaffolding
+ScaffoldingReadMe.txt
+
+# StyleCop
+StyleCopReport.xml
+
+# Files built by Visual Studio
+*_i.c
+*_p.c
+*_h.h
+*.ilk
+*.meta
+*.obj
+*.iobj
+*.pch
+*.pdb
+*.ipdb
+*.pgc
+*.pgd
+*.rsp
+# but not Directory.Build.rsp, as it configures directory-level build defaults
+!Directory.Build.rsp
+*.sbr
+*.tlb
+*.tli
+*.tlh
+*.tmp
+*.tmp_proj
+*_wpftmp.csproj
+*.log
+*.tlog
+*.vspscc
+*.vssscc
+.builds
+*.pidb
+*.svclog
+*.scc
+
+# Chutzpah Test files
+_Chutzpah*
+
+# Visual C++ cache files
+ipch/
+*.aps
+*.ncb
+*.opendb
+*.opensdf
+*.sdf
+*.cachefile
+*.VC.db
+*.VC.VC.opendb
+
+# Visual Studio profiler
+*.psess
+*.vsp
+*.vspx
+*.sap
+
+# Visual Studio Trace Files
+*.e2e
+
+# TFS 2012 Local Workspace
+$tf/
+
+# Guidance Automation Toolkit
+*.gpState
+
+# ReSharper is a .NET coding add-in
+_ReSharper*/
+*.[Rr]e[Ss]harper
+*.DotSettings.user
+
+# TeamCity is a build add-in
+_TeamCity*
+
+# DotCover is a Code Coverage Tool
+*.dotCover
+
+# AxoCover is a Code Coverage Tool
+.axoCover/*
+!.axoCover/settings.json
+
+# Coverlet is a free, cross platform Code Coverage Tool
+coverage*.json
+coverage*.xml
+coverage*.info
+
+# Visual Studio code coverage results
+*.coverage
+*.coveragexml
+
+# NCrunch
+_NCrunch_*
+.*crunch*.local.xml
+nCrunchTemp_*
+
+# MightyMoose
+*.mm.*
+AutoTest.Net/
+
+# Web workbench (sass)
+.sass-cache/
+
+# Installshield output folder
+[Ee]xpress/
+
+# DocProject is a documentation generator add-in
+DocProject/buildhelp/
+DocProject/Help/*.HxT
+DocProject/Help/*.HxC
+DocProject/Help/*.hhc
+DocProject/Help/*.hhk
+DocProject/Help/*.hhp
+DocProject/Help/Html2
+DocProject/Help/html
+
+# Click-Once directory
+publish/
+
+# Publish Web Output
+*.[Pp]ublish.xml
+*.azurePubxml
+# Note: Comment the next line if you want to checkin your web deploy settings,
+# but database connection strings (with potential passwords) will be unencrypted
+*.pubxml
+*.publishproj
+
+# Microsoft Azure Web App publish settings. Comment the next line if you want to
+# checkin your Azure Web App publish settings, but sensitive information contained
+# in these scripts will be unencrypted
+PublishScripts/
+
+# NuGet Packages
+*.nupkg
+# NuGet Symbol Packages
+*.snupkg
+# The packages folder can be ignored because of Package Restore
+**/[Pp]ackages/*
+# except build/, which is used as an MSBuild target.
+!**/[Pp]ackages/build/
+# Uncomment if necessary however generally it will be regenerated when needed
+#!**/[Pp]ackages/repositories.config
+# NuGet v3's project.json files produces more ignorable files
+*.nuget.props
+*.nuget.targets
+
+# Microsoft Azure Build Output
+csx/
+*.build.csdef
+
+# Microsoft Azure Emulator
+ecf/
+rcf/
+
+# Windows Store app package directories and files
+AppPackages/
+BundleArtifacts/
+Package.StoreAssociation.xml
+_pkginfo.txt
+*.appx
+*.appxbundle
+*.appxupload
+
+# Visual Studio cache files
+# files ending in .cache can be ignored
+*.[Cc]ache
+# but keep track of directories ending in .cache
+!?*.[Cc]ache/
+
+# Others
+ClientBin/
+~$*
+*~
+*.dbmdl
+*.dbproj.schemaview
+*.jfm
+*.pfx
+*.publishsettings
+orleans.codegen.cs
+
+# Including strong name files can present a security risk
+# (https://github.com/github/gitignore/pull/2483#issue-259490424)
+#*.snk
+
+# Since there are multiple workflows, uncomment next line to ignore bower_components
+# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622)
+#bower_components/
+
+# RIA/Silverlight projects
+Generated_Code/
+
+# Backup & report files from converting an old project file
+# to a newer Visual Studio version. Backup files are not needed,
+# because we have git ;-)
+_UpgradeReport_Files/
+Backup*/
+UpgradeLog*.XML
+UpgradeLog*.htm
+ServiceFabricBackup/
+*.rptproj.bak
+
+# SQL Server files
+*.mdf
+*.ldf
+*.ndf
+
+# Business Intelligence projects
+*.rdl.data
+*.bim.layout
+*.bim_*.settings
+*.rptproj.rsuser
+*- [Bb]ackup.rdl
+*- [Bb]ackup ([0-9]).rdl
+*- [Bb]ackup ([0-9][0-9]).rdl
+
+# Microsoft Fakes
+FakesAssemblies/
+
+# GhostDoc plugin setting file
+*.GhostDoc.xml
+
+# Node.js Tools for Visual Studio
+.ntvs_analysis.dat
+node_modules/
+
+# Visual Studio 6 build log
+*.plg
+
+# Visual Studio 6 workspace options file
+*.opt
+
+# Visual Studio 6 auto-generated workspace file (contains which files were open etc.)
+*.vbw
+
+# Visual Studio 6 auto-generated project file (contains which files were open etc.)
+*.vbp
+
+# Visual Studio 6 workspace and project file (working project files containing files to include in project)
+*.dsw
+*.dsp
+
+# Visual Studio 6 technical files
+*.ncb
+*.aps
+
+# Visual Studio LightSwitch build output
+**/*.HTMLClient/GeneratedArtifacts
+**/*.DesktopClient/GeneratedArtifacts
+**/*.DesktopClient/ModelManifest.xml
+**/*.Server/GeneratedArtifacts
+**/*.Server/ModelManifest.xml
+_Pvt_Extensions
+
+# Paket dependency manager
+.paket/paket.exe
+paket-files/
+
+# FAKE - F# Make
+.fake/
+
+# CodeRush personal settings
+.cr/personal
+
+# Python Tools for Visual Studio (PTVS)
+__pycache__/
+*.pyc
+
+# Cake - Uncomment if you are using it
+# tools/**
+# !tools/packages.config
+
+# Tabs Studio
+*.tss
+
+# Telerik's JustMock configuration file
+*.jmconfig
+
+# BizTalk build output
+*.btp.cs
+*.btm.cs
+*.odx.cs
+*.xsd.cs
+
+# OpenCover UI analysis results
+OpenCover/
+
+# Azure Stream Analytics local run output
+ASALocalRun/
+
+# MSBuild Binary and Structured Log
+*.binlog
+
+# NVidia Nsight GPU debugger configuration file
+*.nvuser
+
+# MFractors (Xamarin productivity tool) working folder
+.mfractor/
+
+# Local History for Visual Studio
+.localhistory/
+
+# Visual Studio History (VSHistory) files
+.vshistory/
+
+# BeatPulse healthcheck temp database
+healthchecksdb
+
+# Backup folder for Package Reference Convert tool in Visual Studio 2017
+MigrationBackup/
+
+# Ionide (cross platform F# VS Code tools) working folder
+.ionide/
+
+# Fody - auto-generated XML schema
+FodyWeavers.xsd
+
+# VS Code files for those working on multiple tools
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+*.code-workspace
+
+# Local History for Visual Studio Code
+.history/
+
+# Windows Installer files from build outputs
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# JetBrains Rider
+*.sln.iml
+.idea/
+
+##
+## Visual studio for Mac
+##
+
+
+# globs
+Makefile.in
+*.userprefs
+*.usertasks
+config.make
+config.status
+aclocal.m4
+install-sh
+autom4te.cache/
+*.tar.gz
+tarballs/
+test-results/
+
+# content below from: https://github.com/github/gitignore/blob/main/Global/macOS.gitignore
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# content below from: https://github.com/github/gitignore/blob/main/Global/Windows.gitignore
+# Windows thumbnail cache files
+Thumbs.db
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# Vim temporary swap files
+*.swp
@@ -0,0 +1,10 @@
+<Project>
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <LangVersion>latest</LangVersion>
+    <Version>0.1.0</Version>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+</Project>
@@ -0,0 +1,15 @@
+<Project>
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+  <ItemGroup>
+    <!-- Extensions -->
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.7" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.7" />
+    <!-- Test -->
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageVersion Include="xunit" Version="2.9.3" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.4" />
+    <PackageVersion Include="coverlet.collector" Version="6.0.4" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,59 @@
+# ZB.MOM.WW.Audit
+
+Canonical audit event model, best-effort writer seam, and redactor seam for the **ZB.MOM.WW SCADA family** (OtOpcUa, MxAccessGateway, ScadaBridge). This is a **library, not a service** — it is linked directly into the consuming application at build time. Transport and storage remain per-project; only the shared record + seams live here.
+
+---
+
+## Packages
+
+| Package | Description | Key Dependencies |
+|---|---|---|
+| `ZB.MOM.WW.Audit` | Canonical `AuditEvent` record, `AuditOutcome` enum, `IAuditWriter` + `IAuditRedactor` seams, shipped helpers (`NullAuditRedactor`, `TruncatingAuditRedactor`, `NoOpAuditWriter`, `CompositeAuditWriter`, `RedactingAuditWriter`), and `AddZbAudit` DI extension. | `Microsoft.Extensions.DependencyInjection.Abstractions` |
+
+---
+
+## Consumer Matrix
+
+| Consumer | ZB.MOM.WW.Audit |
+|---|:---:|
+| **OtOpcUa** | yes (adoption deferred) |
+| **MxAccessGateway** | yes (adoption deferred) |
+| **ScadaBridge** | yes (adoption deferred — "align, don't replace") |
+
+Adoption is tracked in `components/audit/GAPS.md` in the outer `scadaproj` workspace. Each app brings its own transport (Akka broadcast / SQLite append / SQL ingest) and domain vocabulary (channels / kinds / event-types) — those stay per-project. The shared library provides the canonical record and the two seams that decouple "what to audit" from "how to store it".
+
+---
+
+## Auth alignment
+
+`AuditEvent.Actor` is a string today. At adoption time it SHOULD be set to the `ZB.MOM.WW.Auth` principal identifier — this is the "audit closes the loop on Auth" hinge described in the spec. No compile-time dependency on `ZB.MOM.WW.Auth` is introduced here; the alignment is by convention.
+
+---
+
+## Versioning
+
+The single package is versioned from `Directory.Build.props`. The current release is **0.1.0**. A single version bump in `Directory.Build.props` bumps the package.
+
+---
+
+## Building and packing
+
+```bash
+# From ZB.MOM.WW.Audit/
+dotnet build ZB.MOM.WW.Audit.slnx
+dotnet test  ZB.MOM.WW.Audit.slnx
+
+# Produce the NuGet package into ./artifacts/
+./build/pack.sh
+```
+
+---
+
+## Design documentation
+
+Full design docs live in the `components/audit` folder of the SCADA project workspace:
+
+- `~/Desktop/scadaproj-audit/components/audit/spec/SPEC.md` — overall audit specification
+- `~/Desktop/scadaproj-audit/components/audit/spec/EVENT-MODEL.md` — field-by-field event model + per-project mapping table
+- `~/Desktop/scadaproj-audit/components/audit/shared-contract/ZB.MOM.WW.Audit.md` — public API contract (on paper)
+- `~/Desktop/scadaproj-audit/components/audit/GAPS.md` — adoption backlog
@@ -0,0 +1,8 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/ZB.MOM.WW.Audit/ZB.MOM.WW.Audit.csproj" />
+  </Folder>
+  <Folder Name="/tests/">
+    <Project Path="tests/ZB.MOM.WW.Audit.Tests/ZB.MOM.WW.Audit.Tests.csproj" />
+  </Folder>
+</Solution>
@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# pack.sh — produce the ZB.MOM.WW.Audit NuGet package into ./artifacts.
+set -euo pipefail
+dotnet pack -c Release -o ./artifacts
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# push.sh — pack and push the ZB.MOM.WW.Audit NuGet package to the Gitea feed.
+#
+# Required environment variables:
+#   GITEA_NUGET_SOURCE  — full URL of the Gitea NuGet feed
+#                         e.g. https://gitea.dohertylan.com/api/packages/dohertj2/nuget/index.json
+#   GITEA_NUGET_KEY     — Gitea access token with package:write permission
+#
+# Usage:
+#   export GITEA_NUGET_SOURCE="https://gitea.dohertylan.com/api/packages/dohertj2/nuget/index.json"
+#   export GITEA_NUGET_KEY="your-gitea-token"
+#   ./build/push.sh
+
+set -euo pipefail
+
+: "${GITEA_NUGET_SOURCE:?set GITEA_NUGET_SOURCE to your Gitea NuGet feed URL}"
+: "${GITEA_NUGET_KEY:?set GITEA_NUGET_KEY to your Gitea access token}"
+
+dotnet pack -c Release -o ./artifacts
+
+dotnet nuget push "./artifacts/*.nupkg" \
+  --source "$GITEA_NUGET_SOURCE" \
+  --api-key "$GITEA_NUGET_KEY" \
+  --skip-duplicate
@@ -0,0 +1,50 @@
+namespace ZB.MOM.WW.Audit;
+
+/// <summary>
+/// Canonical, transport-agnostic audit record — who did what, when, with what outcome.
+/// Required core + optional common fields + a <see cref="DetailsJson"/> extension bag. Each
+/// sister app maps its own record onto this; domain vocabularies (channels/kinds/event-types)
+/// map into <see cref="Action"/>/<see cref="Category"/>/<see cref="DetailsJson"/> and are not
+/// modelled here. See scadaproj/components/audit/spec/EVENT-MODEL.md.
+/// </summary>
+public sealed record AuditEvent
+{
+    /// <summary>Idempotency key uniquely identifying this audit event.</summary>
+    public required Guid EventId { get; init; }
+
+    /// <summary>When the audited action occurred. Normalized to UTC on assignment.</summary>
+    /// <remarks>Participates in record value-equality as a normalized instant: two events whose
+    /// <c>OccurredAtUtc</c> denote the same instant at different offsets (e.g. <c>12:00+05:00</c> and
+    /// <c>07:00Z</c>) compare equal and share a hash code. Relevant to consumers that dedup/key on
+    /// <see cref="AuditEvent"/> value-equality.</remarks>
+    public required DateTimeOffset OccurredAtUtc
+    {
+        get => _occurredAtUtc;
+        init => _occurredAtUtc = value.ToUniversalTime();
+    }
+    private readonly DateTimeOffset _occurredAtUtc;
+
+    /// <summary>Who performed the action (identity string; the ZB.MOM.WW.Auth principal at adoption).</summary>
+    public required string Actor { get; init; }
+
+    /// <summary>What was done — a verb/event-type string.</summary>
+    public required string Action { get; init; }
+
+    /// <summary>Normalized outcome.</summary>
+    public required AuditOutcome Outcome { get; init; }
+
+    /// <summary>Optional subsystem/grouping for the action.</summary>
+    public string? Category { get; init; }
+
+    /// <summary>Optional target of the action (resource/method/connection).</summary>
+    public string? Target { get; init; }
+
+    /// <summary>Optional node that emitted the event.</summary>
+    public string? SourceNode { get; init; }
+
+    /// <summary>Optional correlation id joining this row to its originating request/workflow.</summary>
+    public Guid? CorrelationId { get; init; }
+
+    /// <summary>Optional JSON extension carrying project-specific fields.</summary>
+    public string? DetailsJson { get; init; }
+}
@@ -0,0 +1,12 @@
+namespace ZB.MOM.WW.Audit;
+
+/// <summary>Normalized outcome of an audited action.</summary>
+public enum AuditOutcome
+{
+    /// <summary>The action completed successfully.</summary>
+    Success,
+    /// <summary>The action failed due to an error.</summary>
+    Failure,
+    /// <summary>The action was rejected by authentication/authorization.</summary>
+    Denied,
+}
@@ -0,0 +1,21 @@
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+
+namespace ZB.MOM.WW.Audit;
+
+/// <summary>DI helpers for ZB.MOM.WW.Audit.</summary>
+public static class AuditServiceCollectionExtensions
+{
+    /// <summary>
+    /// Registers safe defaults — <see cref="NullAuditRedactor"/> and <see cref="NoOpAuditWriter"/> —
+    /// using TryAdd so a consumer that has already registered a real writer/redactor wins. Consumers
+    /// compose <see cref="RedactingAuditWriter"/>/<see cref="CompositeAuditWriter"/> around their own sink.
+    /// </summary>
+    public static IServiceCollection AddZbAudit(this IServiceCollection services)
+    {
+        ArgumentNullException.ThrowIfNull(services);
+        services.TryAddSingleton<IAuditRedactor>(NullAuditRedactor.Instance);
+        services.TryAddSingleton<IAuditWriter>(NoOpAuditWriter.Instance);
+        return services;
+    }
+}
@@ -0,0 +1,28 @@
+namespace ZB.MOM.WW.Audit;
+
+/// <summary>Fans an event out to several writers. Best-effort: a failing writer does not stop the others.</summary>
+/// <remarks>Every inner-writer failure is swallowed — including <see cref="OperationCanceledException"/>
+/// — so the fan-out drains and the caller is never aborted, honoring the <see cref="IAuditWriter"/>
+/// "must not throw to the caller" contract even when a request-scoped cancellation token is passed.</remarks>
+public sealed class CompositeAuditWriter : IAuditWriter
+{
+    private readonly IReadOnlyList<IAuditWriter> _inner;
+
+    /// <summary>Creates a composite over the given writers.</summary>
+    public CompositeAuditWriter(IEnumerable<IAuditWriter> inner)
+    {
+        ArgumentNullException.ThrowIfNull(inner);
+        _inner = inner.ToArray();
+    }
+
+    /// <inheritdoc />
+    public async Task WriteAsync(AuditEvent evt, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(evt);
+        foreach (var writer in _inner)
+        {
+            try { await writer.WriteAsync(evt, ct).ConfigureAwait(false); }
+            catch { /* best-effort seam: a failing writer (incl. cancellation) must not stop the others or the caller */ }
+        }
+    }
+}
@@ -0,0 +1,13 @@
+namespace ZB.MOM.WW.Audit;
+
+/// <summary>
+/// Filters an <see cref="AuditEvent"/> between construction and persistence — truncates oversized
+/// fields and scrubs sensitive content. Pure function: returns a filtered COPY and MUST NOT throw
+/// (over-redact on internal failure). Shaped to mirror Telemetry's <c>ILogRedactor</c> so a future
+/// ZB.MOM.WW.Hosting aggregator can wire both consistently; intentionally has no dependency on it.
+/// </summary>
+public interface IAuditRedactor
+{
+    /// <summary>Apply the configured truncation/redaction policy and return a filtered copy.</summary>
+    AuditEvent Apply(AuditEvent rawEvent);
+}
@@ -0,0 +1,12 @@
+namespace ZB.MOM.WW.Audit;
+
+/// <summary>
+/// Best-effort sink for <see cref="AuditEvent"/>s. Implementations MUST swallow/log internal
+/// failures rather than propagating them — a failed audit write must never abort the
+/// user-facing action that produced it.
+/// </summary>
+public interface IAuditWriter
+{
+    /// <summary>Persist an audit event. Best-effort; must not throw to the caller.</summary>
+    Task WriteAsync(AuditEvent evt, CancellationToken ct = default);
+}
@@ -0,0 +1,12 @@
+namespace ZB.MOM.WW.Audit;
+
+/// <summary>Writer that discards events. Default when audit is disabled, and useful in tests.</summary>
+public sealed class NoOpAuditWriter : IAuditWriter
+{
+    /// <summary>Shared singleton instance.</summary>
+    public static readonly NoOpAuditWriter Instance = new();
+    private NoOpAuditWriter() { }
+
+    /// <inheritdoc />
+    public Task WriteAsync(AuditEvent evt, CancellationToken ct = default) => Task.CompletedTask;
+}
@@ -0,0 +1,12 @@
+namespace ZB.MOM.WW.Audit;
+
+/// <summary>Identity redactor — returns the event unchanged. The default when no policy is configured.</summary>
+public sealed class NullAuditRedactor : IAuditRedactor
+{
+    /// <summary>Shared singleton instance.</summary>
+    public static readonly NullAuditRedactor Instance = new();
+    private NullAuditRedactor() { }
+
+    /// <inheritdoc />
+    public AuditEvent Apply(AuditEvent rawEvent) => rawEvent;
+}
@@ -0,0 +1,24 @@
+namespace ZB.MOM.WW.Audit;
+
+/// <summary>Decorator: applies an <see cref="IAuditRedactor"/>, then delegates to an inner <see cref="IAuditWriter"/>.</summary>
+public sealed class RedactingAuditWriter : IAuditWriter
+{
+    private readonly IAuditRedactor _redactor;
+    private readonly IAuditWriter _inner;
+
+    /// <summary>Creates the decorator around <paramref name="inner"/> using <paramref name="redactor"/>.</summary>
+    public RedactingAuditWriter(IAuditRedactor redactor, IAuditWriter inner)
+    {
+        ArgumentNullException.ThrowIfNull(redactor);
+        ArgumentNullException.ThrowIfNull(inner);
+        _redactor = redactor;
+        _inner = inner;
+    }
+
+    /// <inheritdoc />
+    public Task WriteAsync(AuditEvent evt, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(evt);
+        return _inner.WriteAsync(_redactor.Apply(evt), ct);
+    }
+}
@@ -0,0 +1,44 @@
+namespace ZB.MOM.WW.Audit;
+
+/// <summary>
+/// Redactor that caps oversized <see cref="AuditEvent.DetailsJson"/> and <see cref="AuditEvent.Target"/>.
+/// Never throws — over-redacts (drops both DetailsJson and Target) on internal failure. The
+/// secret-field policy (which fields are sensitive) stays per-project; compose this with a project
+/// redactor as needed.
+/// </summary>
+public sealed class TruncatingAuditRedactor : IAuditRedactor
+{
+    private readonly TruncatingAuditRedactorOptions _options;
+
+    /// <summary>Creates the redactor with the given options (defaults when null).</summary>
+    public TruncatingAuditRedactor(TruncatingAuditRedactorOptions? options = null)
+        => _options = options ?? new TruncatingAuditRedactorOptions();
+
+    /// <inheritdoc />
+    public AuditEvent Apply(AuditEvent rawEvent)
+    {
+        try
+        {
+            return rawEvent with
+            {
+                Target = Truncate(rawEvent.Target, _options.MaxTargetLength),
+                DetailsJson = Truncate(rawEvent.DetailsJson, _options.MaxDetailsJsonLength),
+            };
+        }
+        catch
+        {
+            // Hard contract: never throw, and over-redact to a STRICTLY safer event on internal
+            // failure — scrub every field this redactor owns (both DetailsJson and Target).
+            return rawEvent with { DetailsJson = null, Target = null };
+        }
+    }
+
+    private string? Truncate(string? value, int max)
+    {
+        if (max < 0) max = 0; // clamp nonsensical negative caps so a config bug fails safe, not throws
+        if (value is null || value.Length <= max) return value;
+        var marker = _options.TruncationMarker;
+        if (marker.Length >= max) return marker[..max];
+        return string.Concat(value.AsSpan(0, max - marker.Length), marker);
+    }
+}
@@ -0,0 +1,12 @@
+namespace ZB.MOM.WW.Audit;
+
+/// <summary>Immutable caps for <see cref="TruncatingAuditRedactor"/>.</summary>
+public sealed record TruncatingAuditRedactorOptions
+{
+    /// <summary>Max length of <see cref="AuditEvent.DetailsJson"/> before truncation. Default 4096.</summary>
+    public int MaxDetailsJsonLength { get; init; } = 4096;
+    /// <summary>Max length of <see cref="AuditEvent.Target"/> before truncation. Default 512.</summary>
+    public int MaxTargetLength { get; init; } = 512;
+    /// <summary>Marker appended to a truncated value. Default "…[truncated]".</summary>
+    public string TruncationMarker { get; init; } = "…[truncated]";
+}
@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <!-- Emit and pack XML docs so consumers get IntelliSense/tooltip documentation. -->
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+  </PropertyGroup>
+  <PropertyGroup>
+    <IsPackable>true</IsPackable>
+    <PackageId>ZB.MOM.WW.Audit</PackageId>
+    <Authors>ZB.MOM.WW</Authors>
+    <Description>Canonical audit event model + best-effort writer and redactor seams for the ZB.MOM.WW SCADA family.</Description>
+    <PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-audit</PackageProjectUrl>
+    <RepositoryUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-audit</RepositoryUrl>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,67 @@
+namespace ZB.MOM.WW.Audit.Tests;
+
+public class AuditEventTests
+{
+    private static AuditEvent Minimal() => new()
+    {
+        EventId = Guid.NewGuid(),
+        OccurredAtUtc = DateTimeOffset.UtcNow,
+        Actor = "alice",
+        Action = "ConfigPublished",
+        Outcome = AuditOutcome.Success,
+    };
+
+    [Fact]
+    public void Required_core_fields_round_trip()
+    {
+        var id = Guid.NewGuid();
+        var evt = Minimal() with { EventId = id, Actor = "svc", Action = "ApiCall", Outcome = AuditOutcome.Denied };
+        Assert.Equal(id, evt.EventId);
+        Assert.Equal("svc", evt.Actor);
+        Assert.Equal("ApiCall", evt.Action);
+        Assert.Equal(AuditOutcome.Denied, evt.Outcome);
+    }
+
+    [Fact]
+    public void OccurredAtUtc_is_normalized_to_utc()
+    {
+        var local = new DateTimeOffset(2026, 6, 1, 12, 0, 0, TimeSpan.FromHours(5));
+        var evt = Minimal() with { OccurredAtUtc = local };
+        Assert.Equal(TimeSpan.Zero, evt.OccurredAtUtc.Offset);
+        Assert.Equal(local.UtcDateTime, evt.OccurredAtUtc.UtcDateTime);
+    }
+
+    [Fact]
+    public void Optional_fields_default_to_null()
+    {
+        var evt = Minimal();
+        Assert.Null(evt.Category);
+        Assert.Null(evt.Target);
+        Assert.Null(evt.SourceNode);
+        Assert.Null(evt.CorrelationId);
+        Assert.Null(evt.DetailsJson);
+    }
+
+    [Fact]
+    public void Records_with_same_values_are_equal()
+    {
+        var id = Guid.NewGuid();
+        var when = DateTimeOffset.UtcNow;
+        AuditEvent Make() => new() { EventId = id, OccurredAtUtc = when, Actor = "a", Action = "x", Outcome = AuditOutcome.Success };
+        Assert.Equal(Make(), Make());
+    }
+
+    [Fact]
+    public void Same_instant_at_different_offset_compares_equal()
+    {
+        // Guards the UTC-normalizing init-setter: if OccurredAtUtc is ever "simplified" back to a
+        // plain auto-property, these two (same instant, different offset) would stop comparing equal.
+        var id = Guid.NewGuid();
+        var utc = new DateTimeOffset(2026, 6, 1, 7, 0, 0, TimeSpan.Zero);
+        var plus5 = new DateTimeOffset(2026, 6, 1, 12, 0, 0, TimeSpan.FromHours(5)); // same instant as utc
+        AuditEvent With(DateTimeOffset when) =>
+            new() { EventId = id, OccurredAtUtc = when, Actor = "a", Action = "x", Outcome = AuditOutcome.Success };
+        Assert.Equal(With(utc), With(plus5));
+        Assert.Equal(With(utc).GetHashCode(), With(plus5).GetHashCode());
+    }
+}
@@ -0,0 +1,32 @@
+using Microsoft.Extensions.DependencyInjection;
+
+namespace ZB.MOM.WW.Audit.Tests;
+
+public class AuditServiceCollectionExtensionsTests
+{
+    [Fact]
+    public void Registers_null_redactor_and_noop_writer_by_default()
+    {
+        var sp = new ServiceCollection().AddZbAudit().BuildServiceProvider();
+        Assert.IsType<NullAuditRedactor>(sp.GetRequiredService<IAuditRedactor>());
+        Assert.IsType<NoOpAuditWriter>(sp.GetRequiredService<IAuditWriter>());
+    }
+
+    [Fact]
+    public void Does_not_override_a_preregistered_writer()
+    {
+        var services = new ServiceCollection();
+        services.AddSingleton<IAuditWriter>(new CompositeAuditWriter(System.Array.Empty<IAuditWriter>()));
+        var sp = services.AddZbAudit().BuildServiceProvider();
+        Assert.IsType<CompositeAuditWriter>(sp.GetRequiredService<IAuditWriter>());
+    }
+
+    [Fact]
+    public void Does_not_override_a_preregistered_redactor()
+    {
+        var services = new ServiceCollection();
+        services.AddSingleton<IAuditRedactor>(new TruncatingAuditRedactor());
+        var sp = services.AddZbAudit().BuildServiceProvider();
+        Assert.IsType<TruncatingAuditRedactor>(sp.GetRequiredService<IAuditRedactor>());
+    }
+}
@@ -0,0 +1,69 @@
+namespace ZB.MOM.WW.Audit.Tests;
+
+public class CompositeAuditWriterTests
+{
+    private sealed class RecordingWriter : IAuditWriter
+    {
+        public int Count;
+        public Task WriteAsync(AuditEvent evt, CancellationToken ct = default) { Count++; return Task.CompletedTask; }
+    }
+    private sealed class ThrowingWriter : IAuditWriter
+    {
+        public Task WriteAsync(AuditEvent evt, CancellationToken ct = default) => throw new InvalidOperationException("boom");
+    }
+    private sealed class CancellingWriter : IAuditWriter
+    {
+        public Task WriteAsync(AuditEvent evt, CancellationToken ct = default) => throw new OperationCanceledException();
+    }
+
+    private static AuditEvent Evt() => new() { EventId = Guid.NewGuid(), OccurredAtUtc = DateTimeOffset.UtcNow,
+        Actor = "a", Action = "x", Outcome = AuditOutcome.Success };
+
+    [Fact]
+    public async Task Fans_out_to_all_writers()
+    {
+        var a = new RecordingWriter(); var b = new RecordingWriter();
+        await new CompositeAuditWriter(new IAuditWriter[] { a, b }).WriteAsync(Evt());
+        Assert.Equal(1, a.Count);
+        Assert.Equal(1, b.Count);
+    }
+
+    [Fact]
+    public async Task One_failing_writer_does_not_stop_the_others()
+    {
+        var after = new RecordingWriter();
+        var sut = new CompositeAuditWriter(new IAuditWriter[] { new ThrowingWriter(), after });
+        await sut.WriteAsync(Evt()); // must not throw
+        Assert.Equal(1, after.Count);
+    }
+
+    [Fact]
+    public async Task Cancellation_does_not_surface_to_the_caller()
+    {
+        // Per the IAuditWriter hard contract ("must not throw to the caller"), an
+        // OperationCanceledException from an inner writer is swallowed like any other failure —
+        // it must NOT abort the user-facing action that produced the event.
+        var after = new RecordingWriter();
+        var sut = new CompositeAuditWriter(new IAuditWriter[] { new CancellingWriter(), after });
+        await sut.WriteAsync(Evt()); // must not throw
+        Assert.Equal(1, after.Count); // drain continues past the cancelled writer
+    }
+
+    [Fact]
+    public async Task Empty_writer_list_is_a_no_op()
+    {
+        var sut = new CompositeAuditWriter(Array.Empty<IAuditWriter>());
+        await sut.WriteAsync(Evt()); // must not throw
+    }
+
+    [Fact]
+    public async Task Null_writer_entry_is_swallowed_and_does_not_stop_the_others()
+    {
+        // A null inner writer faults the await; the best-effort seam swallows it (like any
+        // other writer failure) and continues draining the remaining writers.
+        var after = new RecordingWriter();
+        var sut = new CompositeAuditWriter(new IAuditWriter?[] { null, after }!);
+        await sut.WriteAsync(Evt()); // must not throw
+        Assert.Equal(1, after.Count);
+    }
+}
@@ -0,0 +1,12 @@
+namespace ZB.MOM.WW.Audit.Tests;
+
+public class NoOpAuditWriterTests
+{
+    [Fact]
+    public async Task WriteAsync_completes_without_error()
+    {
+        var evt = new AuditEvent { EventId = Guid.NewGuid(), OccurredAtUtc = DateTimeOffset.UtcNow,
+            Actor = "a", Action = "x", Outcome = AuditOutcome.Success };
+        await NoOpAuditWriter.Instance.WriteAsync(evt);
+    }
+}
@@ -0,0 +1,12 @@
+namespace ZB.MOM.WW.Audit.Tests;
+
+public class NullAuditRedactorTests
+{
+    [Fact]
+    public void Apply_returns_input_unchanged()
+    {
+        var evt = new AuditEvent { EventId = Guid.NewGuid(), OccurredAtUtc = DateTimeOffset.UtcNow,
+            Actor = "a", Action = "x", Outcome = AuditOutcome.Success, DetailsJson = "{\"k\":1}" };
+        Assert.Same(evt, NullAuditRedactor.Instance.Apply(evt));
+    }
+}
@@ -0,0 +1,26 @@
+namespace ZB.MOM.WW.Audit.Tests;
+
+public class RedactingAuditWriterTests
+{
+    private sealed class CapturingWriter : IAuditWriter
+    {
+        public AuditEvent? Last;
+        public Task WriteAsync(AuditEvent evt, CancellationToken ct = default) { Last = evt; return Task.CompletedTask; }
+    }
+    private sealed class StampRedactor : IAuditRedactor
+    {
+        public AuditEvent Apply(AuditEvent rawEvent) => rawEvent with { DetailsJson = "redacted" };
+    }
+
+    private static AuditEvent Evt() => new() { EventId = Guid.NewGuid(), OccurredAtUtc = DateTimeOffset.UtcNow,
+        Actor = "a", Action = "x", Outcome = AuditOutcome.Success, DetailsJson = "secret" };
+
+    [Fact]
+    public async Task Inner_writer_receives_the_redacted_event()
+    {
+        var inner = new CapturingWriter();
+        var sut = new RedactingAuditWriter(new StampRedactor(), inner);
+        await sut.WriteAsync(Evt());
+        Assert.Equal("redacted", inner.Last!.DetailsJson);
+    }
+}
@@ -0,0 +1,82 @@
+namespace ZB.MOM.WW.Audit.Tests;
+
+public class TruncatingAuditRedactorTests
+{
+    private static AuditEvent Evt(string? details, string? target = null) => new()
+    {
+        EventId = Guid.NewGuid(), OccurredAtUtc = DateTimeOffset.UtcNow,
+        Actor = "a", Action = "x", Outcome = AuditOutcome.Success,
+        DetailsJson = details, Target = target,
+    };
+
+    [Fact]
+    public void Short_values_pass_through_unchanged()
+    {
+        var r = new TruncatingAuditRedactor(new() { MaxDetailsJsonLength = 100 });
+        var evt = Evt("small");
+        Assert.Equal("small", r.Apply(evt).DetailsJson);
+    }
+
+    [Fact]
+    public void Oversized_details_are_truncated_with_marker()
+    {
+        var opts = new TruncatingAuditRedactorOptions { MaxDetailsJsonLength = 10, TruncationMarker = "~" };
+        var r = new TruncatingAuditRedactor(opts);
+        var result = r.Apply(Evt(new string('x', 50)));
+        Assert.Equal(10, result.DetailsJson!.Length);
+        Assert.EndsWith("~", result.DetailsJson);
+    }
+
+    [Fact]
+    public void Oversized_target_is_truncated()
+    {
+        var r = new TruncatingAuditRedactor(new() { MaxTargetLength = 5, TruncationMarker = "" });
+        var result = r.Apply(Evt(null, target: "abcdefghij"));
+        Assert.Equal(5, result.Target!.Length);
+    }
+
+    [Fact]
+    public void Null_fields_are_left_null()
+    {
+        var r = new TruncatingAuditRedactor();
+        var result = r.Apply(Evt(null));
+        Assert.Null(result.DetailsJson);
+        Assert.Null(result.Target);
+    }
+
+    [Fact]
+    public void Marker_longer_than_max_clips_the_marker_itself()
+    {
+        // Misconfiguration: marker longer than the cap. Must not throw; clips to the first max chars.
+        var opts = new TruncatingAuditRedactorOptions { MaxDetailsJsonLength = 3, TruncationMarker = "…[truncated]" };
+        var r = new TruncatingAuditRedactor(opts);
+        var result = r.Apply(Evt(new string('x', 20)));
+        Assert.Equal(3, result.DetailsJson!.Length);
+    }
+
+    [Fact]
+    public void Negative_max_is_treated_as_zero_and_does_not_throw()
+    {
+        // A negative cap is nonsensical misconfiguration. Truncate must clamp to 0 rather than
+        // throw, capping the value to the empty string (plus marker handling).
+        var opts = new TruncatingAuditRedactorOptions { MaxDetailsJsonLength = -5, MaxTargetLength = -1, TruncationMarker = "" };
+        var r = new TruncatingAuditRedactor(opts);
+        var result = r.Apply(Evt(new string('x', 20), target: new string('y', 20)));
+        Assert.Equal(string.Empty, result.DetailsJson);
+        Assert.Equal(string.Empty, result.Target);
+    }
+
+    [Fact]
+    public void Over_redact_fallback_scrubs_both_details_and_target_without_throwing()
+    {
+        // Drive the REAL TruncatingAuditRedactor.Apply into its catch branch via a reachable
+        // misconfiguration (a null TruncationMarker faults inside Truncate). The over-redact
+        // fallback must be strictly safer: BOTH DetailsJson AND Target scrubbed to null, no throw.
+        var opts = new TruncatingAuditRedactorOptions { MaxDetailsJsonLength = 5, TruncationMarker = null! };
+        var r = new TruncatingAuditRedactor(opts);
+        var raw = Evt(new string('x', 50), target: "sensitive target");
+        var result = r.Apply(raw);
+        Assert.Null(result.DetailsJson);
+        Assert.Null(result.Target);
+    }
+}
@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="coverlet.collector" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+    <PackageReference Include="xunit" />
+    <PackageReference Include="xunit.runner.visualstudio" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+  </ItemGroup>
+  <ItemGroup>
+    <Using Include="Xunit" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\ZB.MOM.WW.Audit\ZB.MOM.WW.Audit.csproj" />
+  </ItemGroup>
+</Project>
@@ -5,7 +5,7 @@
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <LangVersion>latest</LangVersion>
-    <Version>0.1.0</Version>
+    <Version>0.1.3</Version>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

@@ -10,8 +10,8 @@ Authentication and authorisation libraries for the **ZB.MOM.WW SCADA family** (O
 |---|---|---|
 | `ZB.MOM.WW.Auth.Abstractions` | Auth contracts, canonical role constants, and shared types (`LdapOptions`, `LdapAuthResult`, `ILdapAuthService`, `IApiKeyStore`). No runtime dependencies beyond the BCL. | — |
 | `ZB.MOM.WW.Auth.Ldap` | LDAP authentication service: bind-then-search-then-bind against GLAuth or Active Directory; RFC 4514-aware group extraction; fail-closed. | `Abstractions`, `Novell.Directory.Ldap.NETStandard` |
-| `ZB.MOM.WW.Auth.ApiKeys` | SQLite-backed API-key store with pepper-based PBKDF2 hashing, rotation, and audit log. Includes a `MigrationHostedService` that runs schema migrations on startup. | `Abstractions`, `Microsoft.Data.Sqlite` |
-| `ZB.MOM.WW.Auth.AspNetCore` | ASP.NET Core DI helpers (`AddZbAuth`), cookie defaults, claim-type constants, and `LdapOptionsValidator` registration. Wires together Ldap + ApiKeys + cookie middleware. | `Abstractions`, `Ldap`, `ApiKeys`, `Microsoft.AspNetCore.App` |
+| `ZB.MOM.WW.Auth.ApiKeys` | SQLite-backed API-key store with **pepper-keyed HMAC-SHA256** secret hashing, rotation, and audit log. DI wiring is `AddZbApiKeyAuth`; an opt-in `MigrationHostedService` runs schema migrations on startup. | `Abstractions`, `Microsoft.Data.Sqlite` |
+| `ZB.MOM.WW.Auth.AspNetCore` | ASP.NET Core wiring for the **LDAP** provider only: `AddZbLdapAuth` (binds + start-time-validates `LdapOptions`, registers `ILdapAuthService`), plus `ZbCookieDefaults.Apply` (hardened cookie helper the consumer calls itself) and `ZbClaimTypes` constants. It does **not** wire API keys or cookie middleware — API-key DI is `AddZbApiKeyAuth` in the `ApiKeys` package. | `Abstractions`, `Ldap`, `Microsoft.AspNetCore.App` |

 ---

@@ -55,6 +55,12 @@ public interface IApiKeyAdminStore
    Task<bool> RotateAsync(string keyId, byte[] newSecretHash, CancellationToken ct);
    Task<bool> DeleteAsync(string keyId, CancellationToken ct);

+    /// <summary>Replaces the scope set on an existing key. Does not touch the secret. Returns false if the key does not exist.</summary>
+    Task<bool> SetScopesAsync(string keyId, IReadOnlySet<string> scopes, CancellationToken ct);
+
+    /// <summary>Enables (clears revoked_utc) or disables (sets revoked_utc) a key WITHOUT changing its secret. Returns false if the key does not exist.</summary>
+    Task<bool> SetEnabledAsync(string keyId, bool enabled, DateTimeOffset whenUtc, CancellationToken ct);
+
    /// <summary>
    /// Enumerates all API keys as hash-free <see cref="ApiKeyListItem"/> projections, newest first.
    /// The secret hash is never selected, so callers cannot use this to recover secret material.
@@ -1,3 +1,5 @@
+using System.Net.Security;
+
 namespace ZB.MOM.WW.Auth.Abstractions.Ldap;

 public enum LdapTransport { Ldaps, StartTls, None }
@@ -16,6 +18,16 @@ public sealed record LdapOptions
    public string DisplayNameAttribute { get; init; } = "cn";
    public string GroupAttribute { get; init; } = "memberOf";
    public int ConnectionTimeoutMs { get; init; } = 10_000;
+
+    /// <summary>
+    /// Optional hook to harden (or, in dev, relax) TLS server-certificate validation for the
+    /// <see cref="LdapTransport.Ldaps"/> / <see cref="LdapTransport.StartTls"/> transports. When
+    /// <see langword="null"/> (the default) the LDAP client validates the server certificate against
+    /// the OS trust store — it does <em>not</em> blind-accept. Supply a callback to pin a CA, validate
+    /// the SAN against <see cref="Server"/>, or otherwise tighten validation. This is a code-only seam
+    /// (not bound from configuration) and takes precedence over <see cref="AllowInsecure"/>.
+    /// </summary>
+    public RemoteCertificateValidationCallback? ServerCertificateValidationCallback { get; init; }
 }

 public enum LdapAuthFailure { BadCredentials, UserNotFound, AmbiguousUser, GroupLookupFailed, ServiceAccountBindFailed, Disabled }
@@ -101,7 +101,10 @@ public sealed class ApiKeyAdminCommands

        var record = new ApiKeyRecord(
            KeyId: keyId,
-            KeyPrefix: $"{_options.TokenPrefix}_{keyId}",
+            // KeyPrefix is the bare token prefix (e.g. "mxgw"), NOT prefix_keyId — the key id is
+            // already its own column. Embedding it here produced a self-referential value that
+            // confused admin tooling and disagreed with the read/test paths (see Auth-005).
+            KeyPrefix: _options.TokenPrefix,
            SecretHash: secretHash,
            DisplayName: displayName,
            Scopes: scopes,
@@ -184,6 +187,53 @@ public sealed class ApiKeyAdminCommands
        return new KeyActionResult(deleted, status);
    }

+    /// <summary>
+    /// set-scopes: replaces the scope set on an existing key WITHOUT touching its secret, and
+    /// appends a <c>set-scopes</c> audit entry. Only the scope count is recorded in the audit
+    /// details — the scope values themselves are not logged verbatim.
+    /// All attempts are audited, including failures (key not found) — this is intentional to
+    /// maintain a complete security trail.
+    /// </summary>
+    public async Task<KeyActionResult> SetScopesAsync(
+        string keyId, IReadOnlySet<string> scopes, string? remoteAddress, CancellationToken ct)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
+        ArgumentNullException.ThrowIfNull(scopes);
+
+        bool updated = await _adminStore.SetScopesAsync(keyId, scopes, ct).ConfigureAwait(false);
+
+        string status = updated ? "scopes-set" : "not-found";
+        // Record only the count, never the scope contents, to avoid leaking authority detail into audit.
+        await AppendAuditAsync(keyId, "set-scopes", remoteAddress, $"{status}; count={scopes.Count}", ct)
+            .ConfigureAwait(false);
+
+        return new KeyActionResult(updated, status);
+    }
+
+    /// <summary>
+    /// enable-key / disable-key: reversibly toggles a key's active state WITHOUT changing its
+    /// secret, and appends an <c>enable-key</c> (when enabling) or <c>disable-key</c> (when
+    /// disabling) audit entry.
+    /// All attempts are audited, including failures (key not found) — this is intentional to
+    /// maintain a complete security trail.
+    /// </summary>
+    public async Task<KeyActionResult> SetEnabledAsync(
+        string keyId, bool enabled, string? remoteAddress, CancellationToken ct)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
+
+        DateTimeOffset now = _clock.GetUtcNow();
+        bool updated = await _adminStore.SetEnabledAsync(keyId, enabled, now, ct).ConfigureAwait(false);
+
+        string eventType = enabled ? "enable-key" : "disable-key";
+        string status = updated
+            ? (enabled ? "enabled" : "disabled")
+            : "not-found";
+        await AppendAuditAsync(keyId, eventType, remoteAddress, status, ct).ConfigureAwait(false);
+
+        return new KeyActionResult(updated, status);
+    }
+
    private string RequirePepper()
    {
        string? pepper = _pepperProvider.GetPepper();
@@ -62,8 +62,24 @@ public sealed class ApiKeyVerifier(
            return Fail(ApiKeyFailure.SecretMismatch);
        }

-        // 6. Record successful use, then return the identity (no secret/hash/pepper included).
-        await store.MarkUsedAsync(record.KeyId, _timeProvider.GetUtcNow(), ct).ConfigureAwait(false);
+        // 6. The authentication decision is already made (line 60). Recording last-used is
+        //    best-effort bookkeeping: a transient storage hiccup (SQLITE_BUSY past the busy-timeout,
+        //    disk full, DB locked by a migration) must NOT turn an otherwise-valid credential into a
+        //    failed auth. Swallow any non-cancellation failure so the only exception path remains
+        //    cancellation, as the class contract promises. Cancellation is honoured (re-thrown).
+        try
+        {
+            await store.MarkUsedAsync(record.KeyId, _timeProvider.GetUtcNow(), ct).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException)
+        {
+            throw;
+        }
+        catch
+        {
+            // Best-effort: the last-used write failed, but the credential is valid. Fail open on the
+            // bookkeeping (not the auth decision) rather than denying a legitimate caller.
+        }

        return new ApiKeyVerification(
            Succeeded: true,
@@ -20,7 +20,12 @@ public static class ScopeSerializer

    /// <summary>Deserializes scopes from a JSON array string.</summary>
    /// <param name="value">The JSON string to deserialize; may be null or empty.</param>
-    /// <returns>An ordinal-compared set of scopes; empty when the input is null/blank.</returns>
+    /// <returns>
+    /// An ordinal-compared set of scopes; empty when the input is null/blank. A malformed or
+    /// non-array column (operator tampering, a partial write, a format change, or a buggy writer)
+    /// fails closed to an EMPTY set rather than throwing, so a single poisoned row degrades to a
+    /// zero-scope identity on the auth path instead of an unhandled <see cref="JsonException"/>.
+    /// </returns>
    public static IReadOnlySet<string> Deserialize(string? value)
    {
        if (string.IsNullOrWhiteSpace(value))
@@ -28,7 +33,18 @@ public static class ScopeSerializer
            return new HashSet<string>(StringComparer.Ordinal);
        }

-        string[]? scopes = JsonSerializer.Deserialize<string[]>(value);
+        string[]? scopes;
+        try
+        {
+            scopes = JsonSerializer.Deserialize<string[]>(value);
+        }
+        catch (JsonException)
+        {
+            // Fail closed: a corrupt scopes column yields no scopes rather than an exception on the
+            // verification hot path. The verifier's "only exception path is cancellation" contract
+            // is preserved, and a key with an unreadable scope set is left with zero authority.
+            return new HashSet<string>(StringComparer.Ordinal);
+        }

        return new HashSet<string>(scopes ?? [], StringComparer.Ordinal);
    }
@@ -4,7 +4,8 @@ using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
 namespace ZB.MOM.WW.Auth.ApiKeys.Sqlite;

 /// <summary>
-/// SQLite-backed administration store for API keys (create, revoke, rotate, delete).
+/// SQLite-backed administration store for API keys (create, revoke, rotate, delete,
+/// set-scopes, enable/disable).
 /// </summary>
 public sealed class SqliteApiKeyAdminStore(AuthSqliteConnectionFactory connectionFactory) : IApiKeyAdminStore
 {
@@ -85,6 +86,67 @@ public sealed class SqliteApiKeyAdminStore(AuthSqliteConnectionFactory connectio
        return rows > 0;
    }

+    /// <inheritdoc />
+    public async Task<bool> SetScopesAsync(string keyId, IReadOnlySet<string> scopes, CancellationToken ct)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
+        ArgumentNullException.ThrowIfNull(scopes);
+
+        await using SqliteConnection connection =
+            await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = """
+            UPDATE api_keys
+            SET scopes = $scopes
+            WHERE key_id = $key_id;
+            """;
+        command.Parameters.AddWithValue("$key_id", keyId);
+        command.Parameters.AddWithValue("$scopes", ScopeSerializer.Serialize(scopes));
+
+        int rows = await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
+
+        return rows > 0;
+    }
+
+    /// <inheritdoc />
+    public async Task<bool> SetEnabledAsync(string keyId, bool enabled, DateTimeOffset whenUtc, CancellationToken ct)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
+
+        await using SqliteConnection connection =
+            await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+
+        // Reversible toggle: NO `revoked_utc IS NULL` guard (unlike RevokeAsync), so it works
+        // regardless of current state. Deliberately leaves secret_hash and last_used_utc untouched
+        // — that is what distinguishes re-enable from RotateAsync.
+        if (enabled)
+        {
+            command.CommandText = """
+                UPDATE api_keys
+                SET revoked_utc = NULL
+                WHERE key_id = $key_id;
+                """;
+            command.Parameters.AddWithValue("$key_id", keyId);
+        }
+        else
+        {
+            command.CommandText = """
+                UPDATE api_keys
+                SET revoked_utc = $revoked_utc
+                WHERE key_id = $key_id;
+                """;
+            command.Parameters.AddWithValue("$key_id", keyId);
+            command.Parameters.AddWithValue("$revoked_utc", whenUtc.ToString("O"));
+        }
+
+        int rows = await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
+
+        return rows > 0;
+    }
+
    /// <inheritdoc />
    public async Task<bool> DeleteAsync(string keyId, CancellationToken ct)
    {
@@ -5,8 +5,15 @@ namespace ZB.MOM.WW.Auth.ApiKeys.Sqlite;
 /// </summary>
 public static class SqliteAuthSchema
 {
-    /// <summary>The schema version this build creates and supports.</summary>
-    public const int CurrentVersion = 1;
+    /// <summary>
+    /// The schema version this build creates and supports. This is <c>2</c>, not <c>1</c>,
+    /// to match the deployed databases of the donor (MxAccessGateway) this store was
+    /// extracted from: that store reached its final shape via a v1→v2 history and stamps
+    /// <c>version = 2</c> on disk. The final schema has been byte-identical since v1, so a
+    /// single-shot create stamped as 2 interoperates with existing <c>gateway-auth.db</c>
+    /// files (the migrator only refuses an on-disk version <em>newer</em> than this).
+    /// </summary>
+    public const int CurrentVersion = 2;

    /// <summary>Name of the single-row table tracking the applied schema version.</summary>
    public const string SchemaVersionTable = "schema_version";
@@ -35,7 +35,7 @@ public sealed class SqliteAuthStoreMigrator(AuthSqliteConnectionFactory connecti
                $"Auth database schema version {existingVersion} is newer than supported version {SqliteAuthSchema.CurrentVersion}.");
        }

-        await ApplyVersionOneAsync(connection, transaction, cancellationToken).ConfigureAwait(false);
+        await ApplySchemaAsync(connection, transaction, cancellationToken).ConfigureAwait(false);
        await WriteSchemaVersionAsync(connection, transaction, cancellationToken).ConfigureAwait(false);

        await transaction.CommitAsync(cancellationToken).ConfigureAwait(false);
@@ -78,7 +78,10 @@ public sealed class SqliteAuthStoreMigrator(AuthSqliteConnectionFactory connecti
            : Convert.ToInt32(version, CultureInfo.InvariantCulture);
    }

-    private static async Task ApplyVersionOneAsync(
+    // Single-shot create of the final schema (all DDL is CREATE ... IF NOT EXISTS, so it is
+    // idempotent against an already-provisioned database). The applied version is stamped
+    // separately by WriteSchemaVersionAsync.
+    private static async Task ApplySchemaAsync(
        SqliteConnection connection,
        SqliteTransaction transaction,
        CancellationToken cancellationToken)
@@ -37,7 +37,14 @@ public static class ServiceCollectionExtensions
        ArgumentNullException.ThrowIfNull(config);
        ArgumentException.ThrowIfNullOrWhiteSpace(sectionPath);

-        services.Configure<LdapOptions>(config.GetSection(sectionPath));
+        // Bind via the options builder and opt into start-time validation. An IValidateOptions<T>
+        // otherwise only runs when the options are first materialized (IOptions<T>.Value) — which
+        // here is the first login (ILdapAuthService factory below), not boot. ValidateOnStart hooks
+        // the host's start-time options validation so a misconfigured directory (e.g. insecure
+        // transport without AllowInsecure) fails fast at startup rather than on first login.
+        services.AddOptions<LdapOptions>()
+            .Bind(config.GetSection(sectionPath))
+            .ValidateOnStart();

        // Fail fast at startup on a misconfigured directory rather than on first login.
        services.AddSingleton<IValidateOptions<LdapOptions>, LdapOptionsValidator>();
@@ -1,5 +1,6 @@
 namespace ZB.MOM.WW.Auth.Ldap.Internal;

+using System.Net.Security;
 using ZB.MOM.WW.Auth.Abstractions.Ldap;

 /// <summary>
@@ -15,8 +16,29 @@ internal sealed record LdapSearchEntry(
 /// </summary>
 internal interface ILdapConnection : IDisposable
 {
-    /// <summary>Opens (and optionally upgrades to TLS) a connection to the given host.</summary>
-    void Connect(string host, int port, LdapTransport transport, bool allowInsecure, int timeoutMs);
+    /// <summary>
+    /// Opens (and optionally upgrades to TLS) a connection to the given host.
+    /// </summary>
+    /// <param name="host">The LDAP server hostname or IP.</param>
+    /// <param name="port">The LDAP server port.</param>
+    /// <param name="transport">The transport security mode.</param>
+    /// <param name="allowInsecure">
+    /// When <see langword="true"/> AND no <paramref name="serverCertificateValidationCallback"/> is
+    /// supplied, TLS server-certificate validation is bypassed (dev/test only). Ignored when a
+    /// validation callback is supplied (the callback wins) or for plaintext transport.
+    /// </param>
+    /// <param name="timeoutMs">The connection/operation timeout in milliseconds.</param>
+    /// <param name="serverCertificateValidationCallback">
+    /// Optional TLS server-certificate validation callback. When <see langword="null"/>, the OS trust
+    /// store is used (the client does not blind-accept).
+    /// </param>
+    void Connect(
+        string host,
+        int port,
+        LdapTransport transport,
+        bool allowInsecure,
+        int timeoutMs,
+        RemoteCertificateValidationCallback? serverCertificateValidationCallback);

    /// <summary>Binds with the supplied DN and password. Throws <c>LdapException</c> on bad credentials.</summary>
    void Bind(string dn, string password);
@@ -2,19 +2,67 @@ namespace ZB.MOM.WW.Auth.Ldap.Internal;

 using Novell.Directory.Ldap;
 using ZB.MOM.WW.Auth.Abstractions.Ldap;
+// Disambiguate: Novell also declares a RemoteCertificateValidationCallback delegate; the seam and
+// LdapConnectionOptions.ConfigureRemoteCertificateValidationCallback both use the BCL one.
+using RemoteCertificateValidationCallback = System.Net.Security.RemoteCertificateValidationCallback;

 /// <summary>
 /// Production <see cref="ILdapConnection"/> backed by <c>Novell.Directory.Ldap.LdapConnection</c>.
 /// Mirrors the connection/search idioms from ZB.MOM.WW.ScadaBridge.Security.LdapAuthService.
 /// </summary>
+/// <remarks>
+/// TLS server-certificate validation: by default the underlying
+/// <c>Novell.Directory.Ldap.NETStandard</c> client validates the server certificate against the OS
+/// trust store (it does NOT blind-accept). A caller-supplied
+/// <c>RemoteCertificateValidationCallback</c> overrides that default (CA pinning / SAN checks); when
+/// none is supplied and <c>allowInsecure</c> is set, validation is bypassed for dev/test only.
+/// </remarks>
 internal sealed class NovellLdapConnection : ILdapConnection
 {
-    private readonly LdapConnection _conn = new();
+    private readonly LdapConnection _conn;
    private bool _disposed;

-    /// <inheritdoc/>
-    public void Connect(string host, int port, LdapTransport transport, bool allowInsecure, int timeoutMs)
+    /// <summary>
+    /// Builds the connection, wiring a TLS server-certificate validation policy: a supplied
+    /// <paramref name="serverCertificateValidationCallback"/> wins; otherwise <paramref name="allowInsecure"/>
+    /// bypasses validation (dev/test only); otherwise the OS-trust-store default applies.
+    /// </summary>
+    public NovellLdapConnection(
+        bool allowInsecure = false,
+        RemoteCertificateValidationCallback? serverCertificateValidationCallback = null)
    {
+        if (serverCertificateValidationCallback is not null)
+        {
+            var options = new LdapConnectionOptions()
+                .ConfigureRemoteCertificateValidationCallback(serverCertificateValidationCallback);
+            _conn = new LdapConnection(options);
+        }
+        else if (allowInsecure)
+        {
+            // Dev/test only: accept any server certificate. Reachable solely when an operator has set
+            // AllowInsecure (rejected for plaintext-without-AllowInsecure by LdapOptionsValidator).
+            var options = new LdapConnectionOptions()
+                .ConfigureRemoteCertificateValidationCallback((_, _, _, _) => true);
+            _conn = new LdapConnection(options);
+        }
+        else
+        {
+            // Default: validate against the OS trust store (no blind-accept).
+            _conn = new LdapConnection();
+        }
+    }
+
+    /// <inheritdoc/>
+    public void Connect(
+        string host,
+        int port,
+        LdapTransport transport,
+        bool allowInsecure,
+        int timeoutMs,
+        RemoteCertificateValidationCallback? serverCertificateValidationCallback)
+    {
+        // The TLS-validation policy (allowInsecure / callback) is wired at construction time on the
+        // LdapConnectionOptions; the per-call arguments here are accepted for seam symmetry.
        ApplyTimeout(timeoutMs);

        // LDAPS: TLS is negotiated at the TCP-connection level.
@@ -98,8 +146,16 @@ internal sealed class NovellLdapConnection : ILdapConnection
    }
 }

-/// <summary>Factory that produces fresh <see cref="NovellLdapConnection"/> instances.</summary>
-internal sealed class NovellLdapConnectionFactory : ILdapConnectionFactory
+/// <summary>
+/// Factory that produces fresh <see cref="NovellLdapConnection"/> instances, carrying the TLS
+/// server-certificate validation policy (a supplied callback, or an <c>allowInsecure</c> bypass) so
+/// it is wired onto each connection at construction time.
+/// </summary>
+internal sealed class NovellLdapConnectionFactory(
+    bool allowInsecure = false,
+    RemoteCertificateValidationCallback? serverCertificateValidationCallback = null)
+    : ILdapConnectionFactory
 {
-    public ILdapConnection Create() => new NovellLdapConnection();
+    public ILdapConnection Create() =>
+        new NovellLdapConnection(allowInsecure, serverCertificateValidationCallback);
 }
@@ -26,10 +26,14 @@ public sealed class LdapAuthService : ILdapAuthService

    /// <summary>
    /// Production constructor: binds against a live directory via the real
-    /// Novell-backed connection factory.
+    /// Novell-backed connection factory. The TLS server-certificate validation policy
+    /// (<see cref="LdapOptions.ServerCertificateValidationCallback"/> or the
+    /// <see cref="LdapOptions.AllowInsecure"/> bypass) is carried into the factory so each
+    /// connection is built with it.
    /// </summary>
    public LdapAuthService(LdapOptions options)
-        : this(options, new NovellLdapConnectionFactory())
+        : this(options, new NovellLdapConnectionFactory(
+            options.AllowInsecure, options.ServerCertificateValidationCallback))
    {
    }

@@ -92,7 +96,13 @@ public sealed class LdapAuthService : ILdapAuthService
            //       Abstractions change could add DirectoryUnavailable to disambiguate.
            try
            {
-                conn.Connect(_options.Server, _options.Port, _options.Transport, _options.AllowInsecure, _options.ConnectionTimeoutMs);
+                conn.Connect(
+                    _options.Server,
+                    _options.Port,
+                    _options.Transport,
+                    _options.AllowInsecure,
+                    _options.ConnectionTimeoutMs,
+                    _options.ServerCertificateValidationCallback);
            }
            catch (LdapException)
            {
@@ -9,7 +9,9 @@ namespace ZB.MOM.WW.Auth.Ldap;
 /// low-level error on the first real login attempt.
 /// </summary>
 /// <remarks>
-/// Four conditions are enforced:
+/// Validation is skipped entirely when <see cref="LdapOptions.Enabled"/> is <c>false</c>
+/// (a disabled provider's connection fields are inert). When enabled, four conditions
+/// are enforced:
 /// <list type="bullet">
 /// <item>plaintext transport (<see cref="LdapTransport.None"/>) is rejected unless
 /// <see cref="LdapOptions.AllowInsecure"/> is explicitly set (dev/test only);</item>
@@ -27,6 +29,14 @@ public sealed class LdapOptionsValidator : IValidateOptions<LdapOptions>
    {
        ArgumentNullException.ThrowIfNull(options);

+        // When LDAP is disabled, its connection fields are inert — do not require them.
+        // A consumer that turns LDAP off should not have to supply a server/search-base/
+        // service-account just to satisfy startup validation.
+        if (!options.Enabled)
+        {
+            return ValidateOptionsResult.Success;
+        }
+
        if (options.Transport == LdapTransport.None && !options.AllowInsecure)
        {
            return ValidateOptionsResult.Fail(
@@ -87,6 +87,33 @@ public sealed class ApiKeyAdminCommandsTests : IAsyncLifetime
        Assert.Single(recent, e => e.EventType == "create-key");
    }

+    [Fact]
+    public async Task CreateKey_PersistsBareTokenPrefix_NotPrefixUnderscoreKeyId()
+    {
+        // Auth-005: KeyPrefix is the bare token prefix ("mxgw"), NOT "mxgw_key-1". The key id is
+        // already its own column; embedding it produced a self-referential value that disagreed with
+        // the read/test paths and confused admin tooling.
+        ApiKeyAdminCommands commands = BuildCommands();
+        await commands.InitDbAsync(null, CancellationToken.None);
+
+        await commands.CreateKeyAsync(
+            "key-1",
+            "Service A",
+            new HashSet<string>(["read"], StringComparer.Ordinal),
+            constraintsJson: null,
+            remoteAddress: null,
+            CancellationToken.None);
+
+        ApiKeyRecord? found = await _read.FindByKeyIdAsync("key-1", CancellationToken.None);
+        Assert.NotNull(found);
+        Assert.Equal("mxgw", found!.KeyPrefix);
+
+        // The same bare prefix is surfaced by the admin list projection.
+        IReadOnlyList<ApiKeyListItem> listed = await commands.ListKeysAsync(CancellationToken.None);
+        ApiKeyListItem item = Assert.Single(listed, k => k.KeyId == "key-1");
+        Assert.Equal("mxgw", item.KeyPrefix);
+    }
+
    [Fact]
    public async Task CreateKey_PepperUnavailable_ReturnsNoTokenAndAppendsNoAudit()
    {
@@ -265,6 +292,59 @@ public sealed class ApiKeyAdminCommandsTests : IAsyncLifetime
        Assert.Equal(auditCountBefore, auditCountAfter);
    }

+    // --- set-scopes / enable-disable ---
+
+    [Fact]
+    public async Task SetEnabledAsync_And_SetScopesAsync_AppendAuditEntries()
+    {
+        ApiKeyAdminCommands commands = BuildCommands();
+        await commands.InitDbAsync(null, CancellationToken.None);
+        await commands.CreateKeyAsync(
+            "key-1",
+            "Service A",
+            new HashSet<string>(["read"], StringComparer.Ordinal),
+            null,
+            null,
+            CancellationToken.None);
+
+        // Disable, then re-enable, then replace scopes.
+        KeyActionResult disabled =
+            await commands.SetEnabledAsync("key-1", enabled: false, "10.0.0.1", CancellationToken.None);
+        Assert.True(disabled.Succeeded);
+        Assert.Null(await _read.FindActiveByKeyIdAsync("key-1", CancellationToken.None));
+
+        KeyActionResult enabled =
+            await commands.SetEnabledAsync("key-1", enabled: true, "10.0.0.1", CancellationToken.None);
+        Assert.True(enabled.Succeeded);
+        Assert.NotNull(await _read.FindActiveByKeyIdAsync("key-1", CancellationToken.None));
+
+        KeyActionResult scoped = await commands.SetScopesAsync(
+            "key-1",
+            new HashSet<string>(["read", "write"], StringComparer.Ordinal),
+            "10.0.0.1",
+            CancellationToken.None);
+        Assert.True(scoped.Succeeded);
+
+        IReadOnlyList<ApiKeyAuditEntry> recent = await _audit.ListRecentAsync(50, CancellationToken.None);
+        Assert.Single(recent, e => e.EventType == "disable-key");
+        Assert.Single(recent, e => e.EventType == "enable-key");
+        Assert.Single(recent, e => e.EventType == "set-scopes");
+
+        IReadOnlyList<ApiKeyListItem> listed = await commands.ListKeysAsync(CancellationToken.None);
+        ApiKeyListItem item = Assert.Single(listed, k => k.KeyId == "key-1");
+        Assert.True(item.Scopes.SetEquals(new HashSet<string>(["read", "write"], StringComparer.Ordinal)));
+    }
+
+    [Fact]
+    public async Task SetScopesAsync_NullScopes_Throws()
+    {
+        ApiKeyAdminCommands commands = BuildCommands();
+        await commands.InitDbAsync(null, CancellationToken.None);
+
+        await Assert.ThrowsAnyAsync<ArgumentException>(() =>
+            commands.SetScopesAsync("key-1", null!, null, CancellationToken.None));
+    }
+
    // --- delete-key ---

    [Fact]
@@ -212,6 +212,51 @@ public class ApiKeyVerifierTests
        Assert.DoesNotContain(Convert.ToBase64String(hash), identityText, StringComparison.Ordinal);
    }

+    // --- Auth-002: a failed best-effort MarkUsedAsync must NOT fail a valid key ---
+
+    [Fact]
+    public async Task VerifyAsync_ValidKey_MarkUsedThrows_StillSucceeds()
+    {
+        // MarkUsedAsync is best-effort "last used" bookkeeping. A transient storage failure
+        // (SQLITE_BUSY, disk full, locked DB) must not turn an otherwise-valid credential into a
+        // failed auth: the decision is already made before the usage write. The verifier's contract
+        // is "the only exception path is cancellation", so a non-cancellation MarkUsedAsync failure
+        // is swallowed and the result is still Succeeded == true.
+        byte[] hash = ApiKeySecretHasher.Hash(Secret, Pepper);
+        var store = new FakeApiKeyStore
+        {
+            Record = BuildRecord(hash),
+            MarkUsedException = new InvalidOperationException("SQLITE_BUSY"),
+        };
+        var verifier = BuildVerifier(store, new FakePepperProvider(Pepper));
+
+        ApiKeyVerification result =
+            await verifier.VerifyAsync(Header(KeyId, Secret), CancellationToken.None);
+
+        Assert.True(result.Succeeded);
+        Assert.Null(result.Failure);
+        Assert.NotNull(result.Identity);
+        Assert.Equal(KeyId, result.Identity!.KeyId);
+        Assert.True(store.MarkUsedCalled);
+    }
+
+    [Fact]
+    public async Task VerifyAsync_MarkUsedThrowsOperationCanceled_Propagates()
+    {
+        // The ONLY exception path is cancellation: an OperationCanceledException from the usage
+        // write (e.g. the request was cancelled mid-write) is honoured and re-thrown, not swallowed.
+        byte[] hash = ApiKeySecretHasher.Hash(Secret, Pepper);
+        var store = new FakeApiKeyStore
+        {
+            Record = BuildRecord(hash),
+            MarkUsedException = new OperationCanceledException(),
+        };
+        var verifier = BuildVerifier(store, new FakePepperProvider(Pepper));
+
+        await Assert.ThrowsAnyAsync<OperationCanceledException>(
+            () => verifier.VerifyAsync(Header(KeyId, Secret), CancellationToken.None));
+    }
+
    // --- Cancellation ---

    [Fact]
@@ -253,6 +298,9 @@ public class ApiKeyVerifierTests
        public string? MarkUsedKeyId { get; private set; }
        public DateTimeOffset? MarkUsedWhenUtc { get; private set; }

+        /// <summary>When set, <see cref="MarkUsedAsync"/> throws this exception (after recording the call).</summary>
+        public Exception? MarkUsedException { get; set; }
+
        public Task<ApiKeyRecord?> FindByKeyIdAsync(string keyId, CancellationToken ct)
        {
            FindByKeyIdCalled = true;
@@ -267,6 +315,11 @@ public class ApiKeyVerifierTests
            MarkUsedCalled = true;
            MarkUsedKeyId = keyId;
            MarkUsedWhenUtc = whenUtc;
+            if (MarkUsedException is not null)
+            {
+                return Task.FromException(MarkUsedException);
+            }
+
            return Task.CompletedTask;
        }
    }
@@ -105,6 +105,87 @@ public sealed class SqliteApiKeyAdminStoreTests : IAsyncLifetime
        Assert.False(result);
    }

+    // --- SetScopes ---
+
+    [Fact]
+    public async Task SetScopesAsync_ReplacesScopes_AndReturnsTrue()
+    {
+        await _admin.CreateAsync(
+            SampleRecord("key-1") with { Scopes = new HashSet<string>(["a"], StringComparer.Ordinal) },
+            CancellationToken.None);
+
+        bool result = await _admin.SetScopesAsync(
+            "key-1",
+            new HashSet<string>(["b", "c"], StringComparer.Ordinal),
+            CancellationToken.None);
+
+        Assert.True(result);
+        IReadOnlyList<ApiKeyListItem> listed = await _admin.ListAsync(CancellationToken.None);
+        ApiKeyListItem item = Assert.Single(listed, k => k.KeyId == "key-1");
+        Assert.True(item.Scopes.SetEquals(new HashSet<string>(["b", "c"], StringComparer.Ordinal)));
+    }
+
+    [Fact]
+    public async Task SetScopesAsync_UnknownKey_ReturnsFalse()
+    {
+        bool result = await _admin.SetScopesAsync(
+            "missing",
+            new HashSet<string>(["b"], StringComparer.Ordinal),
+            CancellationToken.None);
+
+        Assert.False(result);
+    }
+
+    // --- SetEnabled ---
+
+    [Fact]
+    public async Task SetEnabledAsync_False_DisablesKey()
+    {
+        await _admin.CreateAsync(SampleRecord("key-1"), CancellationToken.None);
+        var when = new DateTimeOffset(2026, 5, 31, 9, 0, 0, TimeSpan.Zero);
+
+        bool result = await _admin.SetEnabledAsync("key-1", enabled: false, when, CancellationToken.None);
+
+        Assert.True(result);
+        Assert.Null(await _read.FindActiveByKeyIdAsync("key-1", CancellationToken.None));
+        ApiKeyRecord? found = await _read.FindByKeyIdAsync("key-1", CancellationToken.None);
+        Assert.Equal(when, found!.RevokedUtc);
+    }
+
+    [Fact]
+    public async Task SetEnabledAsync_True_ReenablesKey_WithoutChangingSecret()
+    {
+        ApiKeyRecord original = SampleRecord("key-1");
+        await _admin.CreateAsync(original, CancellationToken.None);
+        // Record some usage so we can prove last_used_utc is left untouched on re-enable.
+        var used = new DateTimeOffset(2026, 5, 20, 12, 0, 0, TimeSpan.Zero);
+        await _read.MarkUsedAsync("key-1", used, CancellationToken.None);
+
+        // Disable, then re-enable.
+        await _admin.SetEnabledAsync(
+            "key-1", enabled: false, new DateTimeOffset(2026, 5, 31, 9, 0, 0, TimeSpan.Zero), CancellationToken.None);
+        bool result = await _admin.SetEnabledAsync(
+            "key-1", enabled: true, new DateTimeOffset(2026, 6, 1, 9, 0, 0, TimeSpan.Zero), CancellationToken.None);
+
+        Assert.True(result);
+
+        // Active again, and the secret hash + last-used timestamp are unchanged.
+        ApiKeyRecord? active = await _read.FindActiveByKeyIdAsync("key-1", CancellationToken.None);
+        Assert.NotNull(active);
+        Assert.True(active!.SecretHash.SequenceEqual(original.SecretHash));
+        Assert.Null(active.RevokedUtc);
+        Assert.Equal(used, active.LastUsedUtc);
+    }
+
+    [Fact]
+    public async Task SetEnabledAsync_UnknownKey_ReturnsFalse()
+    {
+        bool result = await _admin.SetEnabledAsync(
+            "missing", enabled: false, DateTimeOffset.UtcNow, CancellationToken.None);
+
+        Assert.False(result);
+    }
+
    // --- Delete ---

    [Fact]
@@ -172,6 +253,73 @@ public sealed class SqliteApiKeyAdminStoreTests : IAsyncLifetime
            () => _admin.DeleteAsync(keyId!, CancellationToken.None));
    }

+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("   ")]
+    public async Task SetScopesAsync_NullOrWhitespaceKeyId_ThrowsArgumentException(string? keyId)
+    {
+        await Assert.ThrowsAnyAsync<ArgumentException>(
+            () => _admin.SetScopesAsync(
+                keyId!,
+                new HashSet<string>(["read"], StringComparer.Ordinal),
+                CancellationToken.None));
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("   ")]
+    public async Task SetEnabledAsync_NullOrWhitespaceKeyId_ThrowsArgumentException(string? keyId)
+    {
+        await Assert.ThrowsAnyAsync<ArgumentException>(
+            () => _admin.SetEnabledAsync(keyId!, enabled: false, DateTimeOffset.UtcNow, CancellationToken.None));
+    }
+
+    [Fact]
+    public async Task SetScopesAsync_NullScopes_ThrowsArgumentNullException()
+    {
+        await _admin.CreateAsync(SampleRecord("key-1"), CancellationToken.None);
+
+        await Assert.ThrowsAsync<ArgumentNullException>(
+            () => _admin.SetScopesAsync("key-1", null!, CancellationToken.None));
+    }
+
+    // --- SetEnabled idempotence ---
+
+    [Fact]
+    public async Task SetEnabledAsync_OnAlreadyActiveKey_ReturnsTrue()
+    {
+        await _admin.CreateAsync(SampleRecord("key-1"), CancellationToken.None);
+
+        bool result = await _admin.SetEnabledAsync(
+            "key-1", enabled: true, DateTimeOffset.UtcNow, CancellationToken.None);
+
+        Assert.True(result);
+        ApiKeyRecord? active = await _read.FindActiveByKeyIdAsync("key-1", CancellationToken.None);
+        Assert.NotNull(active);
+        Assert.Null(active!.RevokedUtc);
+    }
+
+    [Fact]
+    public async Task SetEnabledAsync_OnAlreadyDisabledKey_OverwritesTimestamp_ReturnsTrue()
+    {
+        await _admin.CreateAsync(SampleRecord("key-1"), CancellationToken.None);
+        var t1 = new DateTimeOffset(2026, 5, 1, 10, 0, 0, TimeSpan.Zero);
+        var t2 = new DateTimeOffset(2026, 5, 15, 10, 0, 0, TimeSpan.Zero);
+
+        // Disable at t1.
+        await _admin.SetEnabledAsync("key-1", enabled: false, t1, CancellationToken.None);
+
+        // Disable again at a later t2 (idempotent overwrite — no guard on revoked_utc).
+        bool result = await _admin.SetEnabledAsync("key-1", enabled: false, t2, CancellationToken.None);
+
+        Assert.True(result);
+        IReadOnlyList<ApiKeyListItem> listed = await _admin.ListAsync(CancellationToken.None);
+        ApiKeyListItem item = Assert.Single(listed, k => k.KeyId == "key-1");
+        Assert.Equal(t2, item.RevokedUtc);
+    }
+
    // --- Audit ---

    [Fact]
@@ -164,6 +164,36 @@ public sealed class SqliteApiKeyStoreTests : IAsyncLifetime
        Assert.Empty(ScopeSerializer.Deserialize(""));
    }

+    // --- Auth-003: corrupt scopes JSON must fail closed (empty set), never throw JsonException ---
+
+    [Theory]
+    [InlineData("not json at all")]
+    [InlineData("{")]
+    [InlineData("{\"a\":1}")]   // valid JSON, but an object, not a string[]
+    [InlineData("42")]          // valid JSON, but a number
+    [InlineData("[\"read\",")]  // truncated/partial write
+    public void ScopeSerializer_DeserializeMalformed_ReturnsEmptySet_DoesNotThrow(string value)
+    {
+        // A poisoned scopes column (tampering, partial write, format change, buggy writer) must
+        // degrade to a zero-scope set rather than throwing on the verification hot path.
+        IReadOnlySet<string> scopes = ScopeSerializer.Deserialize(value);
+        Assert.Empty(scopes);
+    }
+
+    [Fact]
+    public async Task FindByKeyId_CorruptScopesColumn_ReturnsRecordWithEmptyScopes_DoesNotThrow()
+    {
+        // Insert a row whose scopes column holds malformed (non-array) JSON, then read it through
+        // the store. The store must NOT propagate a JsonException out of FindByKeyIdAsync (which the
+        // verifier relies on for its "only exception path is cancellation" contract).
+        await InsertWithRawScopesAsync("key-corrupt", scopesJson: "{ this is not valid json");
+
+        ApiKeyRecord? found = await _store.FindByKeyIdAsync("key-corrupt", CancellationToken.None);
+
+        Assert.NotNull(found);
+        Assert.Empty(found!.Scopes);
+    }
+
    private static ApiKeyRecord SampleRecord(string keyId) => new(
        KeyId: keyId,
        KeyPrefix: "mxgw_ab12",
@@ -213,6 +243,33 @@ public sealed class SqliteApiKeyStoreTests : IAsyncLifetime
        await command.ExecuteNonQueryAsync(CancellationToken.None);
    }

+    private async Task InsertWithRawScopesAsync(string keyId, string scopesJson)
+    {
+        // Writes the scopes column verbatim (NOT via ScopeSerializer.Serialize) so a malformed
+        // value can be persisted to simulate tampering / a partial or buggy write.
+        await using SqliteConnection connection =
+            await _factory.OpenConnectionAsync(CancellationToken.None);
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = """
+            INSERT INTO api_keys (
+                key_id, key_prefix, secret_hash, display_name, scopes,
+                constraints, created_utc, last_used_utc, revoked_utc)
+            VALUES (
+                $key_id, $key_prefix, $secret_hash, $display_name, $scopes,
+                $constraints, $created_utc, $last_used_utc, $revoked_utc);
+            """;
+        command.Parameters.AddWithValue("$key_id", keyId);
+        command.Parameters.AddWithValue("$key_prefix", "mxgw");
+        command.Parameters.Add("$secret_hash", SqliteType.Blob).Value = new byte[] { 1, 2, 3 };
+        command.Parameters.AddWithValue("$display_name", "Corrupt Key");
+        command.Parameters.AddWithValue("$scopes", scopesJson);
+        command.Parameters.AddWithValue("$constraints", DBNull.Value);
+        command.Parameters.AddWithValue("$created_utc", DateTimeOffset.UnixEpoch.ToString("O"));
+        command.Parameters.AddWithValue("$last_used_utc", DBNull.Value);
+        command.Parameters.AddWithValue("$revoked_utc", DBNull.Value);
+        await command.ExecuteNonQueryAsync(CancellationToken.None);
+    }
+
    public Task DisposeAsync()
    {
        SqliteConnection.ClearAllPools();
@@ -34,6 +34,27 @@ public sealed class SqliteMigratorTests : IDisposable
        Assert.Equal(1, await CountSchemaVersionRowsAsync());
    }

+    [Fact]
+    public void CurrentVersion_Is2_ToMatchDonorGatewayDeployedSchema() =>
+        // The store was extracted from MxAccessGateway, whose deployed gateway-auth.db is
+        // stamped version 2. The library must stamp 2 (not reset to 1) so it does not refuse
+        // those existing databases on first boot. Locking this invariant.
+        Assert.Equal(2, SqliteAuthSchema.CurrentVersion);
+
+    [Fact]
+    public async Task MigrateAsync_AgainstExistingVersion2Db_DoesNotThrow_AndStaysAt2()
+    {
+        // The deployed-gateway scenario: a database already provisioned at version 2.
+        var migrator = new SqliteAuthStoreMigrator(Factory);
+        await migrator.MigrateAsync(CancellationToken.None);
+        await SetVersionAsync(2);
+
+        await migrator.MigrateAsync(CancellationToken.None); // must not throw
+
+        Assert.Equal(2, await ReadVersionAsync());
+        Assert.True(await TableExistsAsync(SqliteAuthSchema.ApiKeysTable));
+    }
+
    [Fact]
    public async Task MigrateAsync_FutureSchemaVersion_Throws()
    {
@@ -1,5 +1,6 @@
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Options;
 using ZB.MOM.WW.Auth.Abstractions.Ldap;
 using ZB.MOM.WW.Auth.AspNetCore;
@@ -85,4 +86,52 @@ public class ServiceCollectionExtensionsTests

        Assert.Contains(validators, v => v is LdapOptionsValidator);
    }
+
+    // --- Auth-001: ValidateOnStart must run options validation at host startup, not first login ---
+
+    private static IConfiguration BuildInsecureConfiguration() =>
+        new ConfigurationBuilder()
+            .AddInMemoryCollection(new Dictionary<string, string?>
+            {
+                [$"{LdapSection}:Server"] = LdapServer,
+                [$"{LdapSection}:SearchBase"] = "dc=example,dc=com",
+                [$"{LdapSection}:ServiceAccountDn"] = "cn=svc,dc=example,dc=com",
+                // Plaintext transport without AllowInsecure: the validator must reject this.
+                [$"{LdapSection}:Transport"] = nameof(LdapTransport.None),
+                [$"{LdapSection}:AllowInsecure"] = "false",
+            })
+            .Build();
+
+    [Fact]
+    public async Task AddZbLdapAuth_StartingHost_FailsForInsecureConfig()
+    {
+        // The misconfiguration must surface at host start, not deferred until the first login
+        // (i.e. the first ILdapAuthService resolution). ValidateOnStart wires the host's
+        // start-time options validation, so StartAsync must throw OptionsValidationException.
+        IConfiguration config = BuildInsecureConfiguration();
+
+        using IHost host = new HostBuilder()
+            .ConfigureServices(services => services.AddZbLdapAuth(config, LdapSection))
+            .Build();
+
+        OptionsValidationException ex =
+            await Assert.ThrowsAsync<OptionsValidationException>(() => host.StartAsync());
+
+        Assert.Contains(nameof(LdapOptions.Transport), string.Join(" ", ex.Failures));
+    }
+
+    [Fact]
+    public async Task AddZbLdapAuth_StartingHost_SucceedsForSecureConfig()
+    {
+        // A valid (secure) config must start cleanly — proving ValidateOnStart does not reject
+        // well-formed options.
+        IConfiguration config = BuildConfiguration();
+
+        using IHost host = new HostBuilder()
+            .ConfigureServices(services => services.AddZbLdapAuth(config, LdapSection))
+            .Build();
+
+        await host.StartAsync();
+        await host.StopAsync();
+    }
 }
@@ -1,3 +1,4 @@
+using System.Net.Security;
 using ZB.MOM.WW.Auth.Abstractions.Ldap;
 using ZB.MOM.WW.Auth.Ldap.Internal;

@@ -19,6 +20,10 @@ internal sealed class FakeLdapConnection : ILdapConnection
    // ---- observation -----

    public (string Host, int Port, LdapTransport Transport, bool AllowInsecure, int TimeoutMs)? ConnectArgs { get; private set; }
+
+    /// <summary>The server-certificate validation callback passed to the most recent <see cref="Connect"/> call.</summary>
+    public RemoteCertificateValidationCallback? ConnectCertCallback { get; private set; }
+
    public List<string> BoundDns { get; } = new();

    /// <summary>
@@ -107,9 +112,16 @@ internal sealed class FakeLdapConnection : ILdapConnection

    // ---- ILdapConnection -----

-    public void Connect(string host, int port, LdapTransport transport, bool allowInsecure, int timeoutMs)
+    public void Connect(
+        string host,
+        int port,
+        LdapTransport transport,
+        bool allowInsecure,
+        int timeoutMs,
+        RemoteCertificateValidationCallback? serverCertificateValidationCallback = null)
    {
        ConnectArgs = (host, port, transport, allowInsecure, timeoutMs);
+        ConnectCertCallback = serverCertificateValidationCallback;
        if (_throwOnConnect)
            throw new Novell.Directory.Ldap.LdapException(
                "Directory unreachable", Novell.Directory.Ldap.LdapException.ConnectError, host);
@@ -1,3 +1,4 @@
+using System.Net.Security;
 using ZB.MOM.WW.Auth.Abstractions.Ldap;
 using ZB.MOM.WW.Auth.Ldap;

@@ -80,6 +81,56 @@ public class LdapAuthServiceTests
        Assert.Equal(LdapAuthFailure.Disabled, (await svc.AuthenticateAsync("a", "b", default)).Failure);
    }

+    // --- Auth-006: TLS validation seam — allowInsecure is honoured and a cert-validation
+    //     callback is threaded into the connection rather than being silently ignored. ---
+
+    [Fact]
+    public async Task Connect_ReceivesAllowInsecureFlag_FromOptions()
+    {
+        // The allowInsecure flag must reach the connection (it used to be an unused parameter).
+        var fake = new FakeLdapConnection().WithUserEntry(
+            "cn=alice,dc=x", memberOf: new[] { "cn=Engineers,ou=g,dc=x" });
+        var svc = new LdapAuthService(
+            Opts() with { AllowInsecure = true }, new FakeLdapConnectionFactory(fake));
+
+        await svc.AuthenticateAsync("alice", "pw", default);
+
+        Assert.NotNull(fake.ConnectArgs);
+        Assert.True(fake.ConnectArgs!.Value.AllowInsecure);
+    }
+
+    [Fact]
+    public async Task Connect_ReceivesConfiguredCertValidationCallback()
+    {
+        // A consumer-supplied RemoteCertificateValidationCallback must be passed through to the
+        // connection so production callers can pin a CA / validate the SAN — the seam no longer
+        // discards it.
+        RemoteCertificateValidationCallback callback = (_, _, _, _) => true;
+        var fake = new FakeLdapConnection().WithUserEntry(
+            "cn=alice,dc=x", memberOf: new[] { "cn=Engineers,ou=g,dc=x" });
+        var svc = new LdapAuthService(
+            Opts() with { ServerCertificateValidationCallback = callback },
+            new FakeLdapConnectionFactory(fake));
+
+        await svc.AuthenticateAsync("alice", "pw", default);
+
+        Assert.Same(callback, fake.ConnectCertCallback);
+    }
+
+    [Fact]
+    public async Task Connect_NoCertCallbackConfigured_PassesNull()
+    {
+        // Default: no callback configured -> null reaches the connection, which means the
+        // production adapter falls back to OS-trust-store validation (documented behaviour).
+        var fake = new FakeLdapConnection().WithUserEntry(
+            "cn=alice,dc=x", memberOf: new[] { "cn=Engineers,ou=g,dc=x" });
+        var svc = new LdapAuthService(Opts(), new FakeLdapConnectionFactory(fake));
+
+        await svc.AuthenticateAsync("alice", "pw", default);
+
+        Assert.Null(fake.ConnectCertCallback);
+    }
+
    [Fact]
    public async Task PreservesEscapedCommaInGroupName_OnRfc4514Dn()
    {
@@ -72,4 +72,20 @@ public class LdapOptionsValidatorTests
        Assert.False(new LdapOptionsValidator()
            .Validate(null, Opts())
            .Failed);
+
+    [Fact]
+    public void Validator_Skips_AllChecks_WhenDisabled() =>
+        // When LDAP is disabled its connection fields are inert; an otherwise-invalid
+        // config (plaintext + blank Server/SearchBase/ServiceAccountDn) must still pass.
+        Assert.False(new LdapOptionsValidator()
+            .Validate(null, new LdapOptions
+            {
+                Enabled = false,
+                Transport = LdapTransport.None,
+                AllowInsecure = false,
+                Server = "",
+                SearchBase = "",
+                ServiceAccountDn = "",
+            })
+            .Failed);
 }
@@ -0,0 +1,482 @@
+## Ignore Visual Studio temporary files, build results, and
+## files generated by popular Visual Studio add-ons.
+##
+## Get latest from `dotnet new gitignore`
+
+# dotenv files
+.env
+
+# User-specific files
+*.rsuser
+*.suo
+*.user
+*.userosscache
+*.sln.docstates
+
+# User-specific files (MonoDevelop/Xamarin Studio)
+*.userprefs
+
+# Mono auto generated files
+mono_crash.*
+
+# Build results
+[Dd]ebug/
+[Dd]ebugPublic/
+[Rr]elease/
+[Rr]eleases/
+x64/
+x86/
+[Ww][Ii][Nn]32/
+[Aa][Rr][Mm]/
+[Aa][Rr][Mm]64/
+bld/
+[Bb]in/
+[Oo]bj/
+[Ll]og/
+[Ll]ogs/
+
+# Visual Studio 2015/2017 cache/options directory
+.vs/
+# Uncomment if you have tasks that create the project's static files in wwwroot
+#wwwroot/
+
+# Visual Studio 2017 auto generated files
+Generated\ Files/
+
+# MSTest test Results
+[Tt]est[Rr]esult*/
+[Bb]uild[Ll]og.*
+
+# NUnit
+*.VisualState.xml
+TestResult.xml
+nunit-*.xml
+
+# Build Results of an ATL Project
+[Dd]ebugPS/
+[Rr]eleasePS/
+dlldata.c
+
+# Benchmark Results
+BenchmarkDotNet.Artifacts/
+
+# .NET
+project.lock.json
+project.fragment.lock.json
+artifacts/
+
+# Tye
+.tye/
+
+# ASP.NET Scaffolding
+ScaffoldingReadMe.txt
+
+# StyleCop
+StyleCopReport.xml
+
+# Files built by Visual Studio
+*_i.c
+*_p.c
+*_h.h
+*.ilk
+*.meta
+*.obj
+*.iobj
+*.pch
+*.pdb
+*.ipdb
+*.pgc
+*.pgd
+*.rsp
+# but not Directory.Build.rsp, as it configures directory-level build defaults
+!Directory.Build.rsp
+*.sbr
+*.tlb
+*.tli
+*.tlh
+*.tmp
+*.tmp_proj
+*_wpftmp.csproj
+*.log
+*.tlog
+*.vspscc
+*.vssscc
+.builds
+*.pidb
+*.svclog
+*.scc
+
+# Chutzpah Test files
+_Chutzpah*
+
+# Visual C++ cache files
+ipch/
+*.aps
+*.ncb
+*.opendb
+*.opensdf
+*.sdf
+*.cachefile
+*.VC.db
+*.VC.VC.opendb
+
+# Visual Studio profiler
+*.psess
+*.vsp
+*.vspx
+*.sap
+
+# Visual Studio Trace Files
+*.e2e
+
+# TFS 2012 Local Workspace
+$tf/
+
+# Guidance Automation Toolkit
+*.gpState
+
+# ReSharper is a .NET coding add-in
+_ReSharper*/
+*.[Rr]e[Ss]harper
+*.DotSettings.user
+
+# TeamCity is a build add-in
+_TeamCity*
+
+# DotCover is a Code Coverage Tool
+*.dotCover
+
+# AxoCover is a Code Coverage Tool
+.axoCover/*
+!.axoCover/settings.json
+
+# Coverlet is a free, cross platform Code Coverage Tool
+coverage*.json
+coverage*.xml
+coverage*.info
+
+# Visual Studio code coverage results
+*.coverage
+*.coveragexml
+
+# NCrunch
+_NCrunch_*
+.*crunch*.local.xml
+nCrunchTemp_*
+
+# MightyMoose
+*.mm.*
+AutoTest.Net/
+
+# Web workbench (sass)
+.sass-cache/
+
+# Installshield output folder
+[Ee]xpress/
+
+# DocProject is a documentation generator add-in
+DocProject/buildhelp/
+DocProject/Help/*.HxT
+DocProject/Help/*.HxC
+DocProject/Help/*.hhc
+DocProject/Help/*.hhk
+DocProject/Help/*.hhp
+DocProject/Help/Html2
+DocProject/Help/html
+
+# Click-Once directory
+publish/
+
+# Publish Web Output
+*.[Pp]ublish.xml
+*.azurePubxml
+# Note: Comment the next line if you want to checkin your web deploy settings,
+# but database connection strings (with potential passwords) will be unencrypted
+*.pubxml
+*.publishproj
+
+# Microsoft Azure Web App publish settings. Comment the next line if you want to
+# checkin your Azure Web App publish settings, but sensitive information contained
+# in these scripts will be unencrypted
+PublishScripts/
+
+# NuGet Packages
+*.nupkg
+# NuGet Symbol Packages
+*.snupkg
+# The packages folder can be ignored because of Package Restore
+**/[Pp]ackages/*
+# except build/, which is used as an MSBuild target.
+!**/[Pp]ackages/build/
+# Uncomment if necessary however generally it will be regenerated when needed
+#!**/[Pp]ackages/repositories.config
+# NuGet v3's project.json files produces more ignorable files
+*.nuget.props
+*.nuget.targets
+
+# Microsoft Azure Build Output
+csx/
+*.build.csdef
+
+# Microsoft Azure Emulator
+ecf/
+rcf/
+
+# Windows Store app package directories and files
+AppPackages/
+BundleArtifacts/
+Package.StoreAssociation.xml
+_pkginfo.txt
+*.appx
+*.appxbundle
+*.appxupload
+
+# Visual Studio cache files
+# files ending in .cache can be ignored
+*.[Cc]ache
+# but keep track of directories ending in .cache
+!?*.[Cc]ache/
+
+# Others
+ClientBin/
+~$*
+*~
+*.dbmdl
+*.dbproj.schemaview
+*.jfm
+*.pfx
+*.publishsettings
+orleans.codegen.cs
+
+# Including strong name files can present a security risk
+# (https://github.com/github/gitignore/pull/2483#issue-259490424)
+#*.snk
+
+# Since there are multiple workflows, uncomment next line to ignore bower_components
+# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622)
+#bower_components/
+
+# RIA/Silverlight projects
+Generated_Code/
+
+# Backup & report files from converting an old project file
+# to a newer Visual Studio version. Backup files are not needed,
+# because we have git ;-)
+_UpgradeReport_Files/
+Backup*/
+UpgradeLog*.XML
+UpgradeLog*.htm
+ServiceFabricBackup/
+*.rptproj.bak
+
+# SQL Server files
+*.mdf
+*.ldf
+*.ndf
+
+# Business Intelligence projects
+*.rdl.data
+*.bim.layout
+*.bim_*.settings
+*.rptproj.rsuser
+*- [Bb]ackup.rdl
+*- [Bb]ackup ([0-9]).rdl
+*- [Bb]ackup ([0-9][0-9]).rdl
+
+# Microsoft Fakes
+FakesAssemblies/
+
+# GhostDoc plugin setting file
+*.GhostDoc.xml
+
+# Node.js Tools for Visual Studio
+.ntvs_analysis.dat
+node_modules/
+
+# Visual Studio 6 build log
+*.plg
+
+# Visual Studio 6 workspace options file
+*.opt
+
+# Visual Studio 6 auto-generated workspace file (contains which files were open etc.)
+*.vbw
+
+# Visual Studio 6 auto-generated project file (contains which files were open etc.)
+*.vbp
+
+# Visual Studio 6 workspace and project file (working project files containing files to include in project)
+*.dsw
+*.dsp
+
+# Visual Studio 6 technical files
+*.ncb
+*.aps
+
+# Visual Studio LightSwitch build output
+**/*.HTMLClient/GeneratedArtifacts
+**/*.DesktopClient/GeneratedArtifacts
+**/*.DesktopClient/ModelManifest.xml
+**/*.Server/GeneratedArtifacts
+**/*.Server/ModelManifest.xml
+_Pvt_Extensions
+
+# Paket dependency manager
+.paket/paket.exe
+paket-files/
+
+# FAKE - F# Make
+.fake/
+
+# CodeRush personal settings
+.cr/personal
+
+# Python Tools for Visual Studio (PTVS)
+__pycache__/
+*.pyc
+
+# Cake - Uncomment if you are using it
+# tools/**
+# !tools/packages.config
+
+# Tabs Studio
+*.tss
+
+# Telerik's JustMock configuration file
+*.jmconfig
+
+# BizTalk build output
+*.btp.cs
+*.btm.cs
+*.odx.cs
+*.xsd.cs
+
+# OpenCover UI analysis results
+OpenCover/
+
+# Azure Stream Analytics local run output
+ASALocalRun/
+
+# MSBuild Binary and Structured Log
+*.binlog
+
+# NVidia Nsight GPU debugger configuration file
+*.nvuser
+
+# MFractors (Xamarin productivity tool) working folder
+.mfractor/
+
+# Local History for Visual Studio
+.localhistory/
+
+# Visual Studio History (VSHistory) files
+.vshistory/
+
+# BeatPulse healthcheck temp database
+healthchecksdb
+
+# Backup folder for Package Reference Convert tool in Visual Studio 2017
+MigrationBackup/
+
+# Ionide (cross platform F# VS Code tools) working folder
+.ionide/
+
+# Fody - auto-generated XML schema
+FodyWeavers.xsd
+
+# VS Code files for those working on multiple tools
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+*.code-workspace
+
+# Local History for Visual Studio Code
+.history/
+
+# Windows Installer files from build outputs
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# JetBrains Rider
+*.sln.iml
+.idea/
+
+##
+## Visual studio for Mac
+##
+
+
+# globs
+Makefile.in
+*.userprefs
+*.usertasks
+config.make
+config.status
+aclocal.m4
+install-sh
+autom4te.cache/
+*.tar.gz
+tarballs/
+test-results/
+
+# content below from: https://github.com/github/gitignore/blob/main/Global/macOS.gitignore
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# content below from: https://github.com/github/gitignore/blob/main/Global/Windows.gitignore
+# Windows thumbnail cache files
+Thumbs.db
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# Vim temporary swap files
+*.swp
@@ -0,0 +1,77 @@
+# ZB.MOM.WW.Configuration
+
+Startup configuration-validation library for the **ZB.MOM.WW SCADA family** (OtOpcUa, MxAccessGateway, ScadaBridge). These are **libraries, not a service** — the package is linked directly into the consuming application at build time. There is no central validation process; all validation runs in-process at startup.
+
+The library normalizes the three-project configuration-validation surface: a failure-accumulating `IValidateOptions` base, reusable rule primitives, a bind+validate+`ValidateOnStart` DI extension, and a pre-host `ConfigPreflight` aggregator for raw `IConfiguration` — so the plumbing is written once and domain rules stay per-project.
+
+**Built at 0.1.0. Adopted by OtOpcUa, MxAccessGateway, and ScadaBridge on 2026-06-01** (local default branches; not yet pushed to remotes). Adoption tracked in `~/Desktop/scadaproj/components/configuration/GAPS.md`.
+
+---
+
+## Package
+
+| Package | Responsibilities | Key Dependencies |
+|---|---|---|
+| `ZB.MOM.WW.Configuration` | `OptionsValidatorBase<TOptions>` (abstract `IValidateOptions` base, failure-accumulating), `ValidationBuilder` (rule primitives: `Required`, `Port`, `HostPort`, `PositiveTimeSpan`, `OneOf`, `MinCount`, `RequireThat`, `Add`), `ServiceCollectionExtensions.AddValidatedOptions` (bind + validator + `ValidateOnStart` in one call), `ConfigPreflight` (fluent pre-host raw-`IConfiguration` checker). | `Microsoft.Extensions.Options`, `Microsoft.Extensions.Options.ConfigurationExtensions`, `Microsoft.Extensions.Configuration.Abstractions`, `Microsoft.Extensions.DependencyInjection.Abstractions` |
+
+Single package; no ASP.NET Core framework reference.
+
+---
+
+## Build, test, and pack commands
+
+```bash
+# From ZB.MOM.WW.Configuration/
+
+# Build
+dotnet build ZB.MOM.WW.Configuration.slnx
+
+# Test (no external dependencies required)
+dotnet test ZB.MOM.WW.Configuration.slnx
+
+# Pack (one .nupkg lands in artifacts/)
+dotnet pack ZB.MOM.WW.Configuration.slnx -c Release -o ./artifacts
+```
+
+Test breakdown:
+
+| Assembly | Tests |
+|---|---|
+| `ZB.MOM.WW.Configuration.Tests` | 27 |
+| **Total** | **27** |
+
+`GeneratePackageOnBuild` is off — pack explicitly with the command above.
+
+---
+
+## Source layout
+
+```
+ZB.MOM.WW.Configuration/
+├── Directory.Build.props          # version (0.1.0), TFM (net10.0), central package mgmt
+├── Directory.Packages.props       # pinned package versions
+├── ZB.MOM.WW.Configuration.slnx   # solution file
+├── src/
+│   └── ZB.MOM.WW.Configuration/   # library project
+│       ├── OptionsValidatorBase.cs
+│       ├── ValidationBuilder.cs
+│       ├── Checks.cs                 # internal shared rule wording
+│       ├── ServiceCollectionExtensions.cs
+│       └── ConfigPreflight.cs
+└── tests/
+    └── ZB.MOM.WW.Configuration.Tests/   # xUnit test project (27 tests)
+```
+
+---
+
+## Status
+
+Part of the **scadaproj component-normalization family** — this is the configuration + validation component. Built at **0.1.0**. **Adopted by OtOpcUa, MxAccessGateway, and ScadaBridge on 2026-06-01** (local default branches; not yet pushed to remotes) — per-app result is tracked in:
+
+- `~/Desktop/scadaproj/components/configuration/GAPS.md`
+
+Design documentation:
+
+- `~/Desktop/scadaproj/components/configuration/spec/SPEC.md` — normalized validation target
+- `~/Desktop/scadaproj/components/configuration/shared-contract/ZB.MOM.WW.Configuration.md` — proposed shared-library API
+- `~/Desktop/scadaproj/components/configuration/current-state/` — per-project current state (code-verified)
@@ -0,0 +1,11 @@
+<Project>
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <LangVersion>latest</LangVersion>
+    <Version>0.1.0</Version>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+  </PropertyGroup>
+</Project>
@@ -0,0 +1,19 @@
+<Project>
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+  <ItemGroup>
+    <!-- Library -->
+    <PackageVersion Include="Microsoft.Extensions.Options" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.0" />
+    <!-- Test only -->
+    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageVersion Include="xunit" Version="2.9.3" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.4" />
+    <PackageVersion Include="coverlet.collector" Version="6.0.4" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,112 @@
+# ZB.MOM.WW.Configuration
+
+Startup configuration-validation library for the **ZB.MOM.WW SCADA family** (OtOpcUa, MxAccessGateway, ScadaBridge). This is a **library, not a service** — the package is linked directly into the consuming application at build time. It extracts the `IValidateOptions` plumbing the three apps share — failure accumulation, rule primitives, bind+validate DI wiring, and pre-host preflight — so that domain-specific validation rules stay per-project and the boilerplate does not drift.
+
+---
+
+## What's in the box
+
+| Type | Description |
+|---|---|
+| `OptionsValidatorBase<TOptions>` | Abstract `IValidateOptions<TOptions>`. Override `protected void Validate(ValidationBuilder v, TOptions o)` to declare failures; the base aggregates all failures and returns a single `ValidateOptionsResult`. |
+| `ValidationBuilder` | Failure accumulator. Primitives: `Required`, `Port`, `HostPort`, `PositiveTimeSpan`, `OneOf`, `MinCount`, `RequireThat(bool, msg)`, `Add(msg)`. Properties: `Failures` (read), `IsValid`. |
+| `ServiceCollectionExtensions` | `AddValidatedOptions<TOptions, TValidator>(IConfiguration config, string sectionPath)` — binds the section, registers the validator, and calls `ValidateOnStart()` in a single extension method. Returns `OptionsBuilder<TOptions>`. |
+| `ConfigPreflight` | Pre-host raw-`IConfiguration` checker. Fluent API: `For(config)`, `.Require(key, predicate, reason)`, `.RequireValue(key)`, `.RequirePort(key)`, `.When(cond, block)`, `.ThrowIfInvalid()`. |
+
+---
+
+## Usage
+
+### 1. Validator subclass
+
+```csharp
+public sealed class ClusterOptionsValidator : OptionsValidatorBase<ClusterOptions>
+{
+    protected override void Validate(ValidationBuilder v, ClusterOptions o)
+    {
+        v.MinCount(o.SeedNodes, 2, "Cluster:SeedNodes");
+        v.OneOf(o.Strategy, new[] { "keep-oldest" }, "Cluster:Strategy");
+        v.PositiveTimeSpan(o.StableAfter, "Cluster:StableAfter");
+    }
+}
+```
+
+### 2. DI wiring
+
+```csharp
+builder.Services.AddValidatedOptions<ClusterOptions, ClusterOptionsValidator>(
+    builder.Configuration, "ScadaBridge:Cluster");
+```
+
+This binds `ScadaBridge:Cluster`, registers `ClusterOptionsValidator`, and enables `ValidateOnStart` — the app refuses to start if the section fails validation.
+
+### 3. Pre-host preflight
+
+```csharp
+ConfigPreflight.For(configuration)
+    .Require("Node:Role", v => v is "Central" or "Site", "must be 'Central' or 'Site'")
+    .RequirePort("Node:RemotingPort")
+    .When(role == "Site", p => p.RequireValue("Node:SiteId"))
+    .ThrowIfInvalid();
+```
+
+Use `ConfigPreflight` before `WebApplication.CreateBuilder` for critical keys (node role, remoting port, site ID) that must be present and valid before the DI container is even constructed.
+
+---
+
+## Building and testing
+
+```bash
+# from ZB.MOM.WW.Configuration/
+dotnet test ZB.MOM.WW.Configuration.slnx
+```
+
+All tests run with no external dependencies:
+
+| Assembly | Tests |
+|---|---|
+| `ZB.MOM.WW.Configuration.Tests` | 27 |
+| **Total** | **27** |
+
+---
+
+## Packing
+
+```bash
+dotnet pack ZB.MOM.WW.Configuration.slnx -c Release -o ./artifacts
+```
+
+Produces one `.nupkg` file in `artifacts/`:
+
+```
+ZB.MOM.WW.Configuration.0.1.0.nupkg
+```
+
+`GeneratePackageOnBuild` is off — pack explicitly as above. Version is set in `Directory.Build.props`.
+
+---
+
+## Dependencies
+
+The package has a minimal closure — only `Microsoft.Extensions.*` abstractions:
+
+- `Microsoft.Extensions.Options`
+- `Microsoft.Extensions.Options.ConfigurationExtensions`
+- `Microsoft.Extensions.Configuration.Abstractions`
+- `Microsoft.Extensions.DependencyInjection.Abstractions`
+
+No third-party packages; no ASP.NET Core framework reference.
+
+---
+
+## Status
+
+**Built at 0.1.0. Adopted across all three apps on 2026-06-01** (local default branches; not yet pushed to remotes). Adoption is tracked in the component backlog:
+
+- `~/Desktop/scadaproj/components/configuration/GAPS.md`
+
+Design documentation lives alongside that backlog:
+
+- `~/Desktop/scadaproj/components/configuration/spec/SPEC.md` — normalized validation target
+- `~/Desktop/scadaproj/components/configuration/shared-contract/ZB.MOM.WW.Configuration.md` — proposed API
+- `~/Desktop/scadaproj/components/configuration/current-state/` — per-project current state (code-verified)
@@ -0,0 +1,8 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/ZB.MOM.WW.Configuration/ZB.MOM.WW.Configuration.csproj" />
+  </Folder>
+  <Folder Name="/tests/">
+    <Project Path="tests/ZB.MOM.WW.Configuration.Tests/ZB.MOM.WW.Configuration.Tests.csproj" />
+  </Folder>
+</Solution>
@@ -0,0 +1,59 @@
+using System.Globalization;
+
+namespace ZB.MOM.WW.Configuration;
+
+/// <summary>
+/// Internal rule primitives shared by <see cref="ValidationBuilder"/> (validates a bound options
+/// object) and <see cref="ConfigPreflight"/> (validates raw <c>IConfiguration</c>). Each method
+/// returns <c>null</c> when valid, or a formatted <c>"&lt;field&gt; &lt;reason&gt;"</c> message
+/// otherwise. Centralizing them keeps wording identical across both front-ends.
+/// </summary>
+internal static class Checks
+{
+    internal static string? Required(string? value, string field) =>
+        string.IsNullOrWhiteSpace(value) ? $"{field} is required" : null;
+
+    internal static string? Port(int value, string field) =>
+        value is < 1 or > 65535 ? $"{field} must be between 1 and 65535 (was {value})" : null;
+
+    /// <summary>
+    /// Validates a raw string as a TCP port (parse + range), returning <c>null</c> when valid.
+    /// Centralizes the port wording for callers that hold the raw config value. Parsing is strict
+    /// and culture-invariant (<see cref="NumberStyles.None"/>): a leading sign or surrounding
+    /// whitespace is rejected. Both the parse-failure and range-failure messages quote the offending
+    /// raw value so they read consistently.
+    /// </summary>
+    internal static string? PortValue(string? raw, string field) =>
+        int.TryParse(raw, NumberStyles.None, CultureInfo.InvariantCulture, out var port) && port is >= 1 and <= 65535
+            ? null
+            : $"{field} must be between 1 and 65535 (was '{raw ?? "null"}')";
+
+    /// <summary>
+    /// Validates a non-bracketed <c>host:port</c> endpoint (port 1-65535). Bracketed IPv6
+    /// literals (<c>[::1]:port</c>) are out of scope and are rejected.
+    /// </summary>
+    internal static string? HostPort(string? value, string field)
+    {
+        if (string.IsNullOrWhiteSpace(value)) return $"{field} is required";
+        var idx = value.LastIndexOf(':');
+        if (idx <= 0 || idx == value.Length - 1
+            || value.AsSpan(0, idx).Contains(':')
+            || !int.TryParse(value[(idx + 1)..], NumberStyles.None, CultureInfo.InvariantCulture, out var port)
+            || port is < 1 or > 65535)
+            return $"{field} must be 'host:port' with port 1-65535 (was '{value}')";
+        return null;
+    }
+
+    internal static string? PositiveTimeSpan(TimeSpan value, string field) =>
+        value <= TimeSpan.Zero ? $"{field} must be a positive duration (was {value})" : null;
+
+    internal static string? OneOf(string? value, IReadOnlyCollection<string> allowed, string field) =>
+        value is not null && allowed.Contains(value, StringComparer.OrdinalIgnoreCase)
+            ? null
+            : $"{field} must be one of [{string.Join(", ", allowed)}] (was '{value ?? "null"}')";
+
+    internal static string? MinCount<T>(IReadOnlyCollection<T>? value, int min, string field) =>
+        value is null || value.Count < min
+            ? $"{field} must contain at least {min} item(s) (had {value?.Count ?? 0})"
+            : null;
+}
@@ -0,0 +1,75 @@
+using Microsoft.Extensions.Configuration;
+
+namespace ZB.MOM.WW.Configuration;
+
+/// <summary>
+/// Fluent aggregator for validating raw <see cref="IConfiguration"/> BEFORE the host/DI container
+/// exists (e.g. pre-Akka startup). Collects all failures and surfaces them together via
+/// <see cref="ThrowIfInvalid"/>. For options that flow through DI, prefer
+/// <see cref="ServiceCollectionExtensions.AddValidatedOptions{TOptions, TValidator}"/>.
+/// </summary>
+public sealed class ConfigPreflight
+{
+    private readonly IConfiguration _configuration;
+    private readonly List<string> _failures = [];
+
+    private ConfigPreflight(IConfiguration configuration) => _configuration = configuration;
+
+    /// <summary>Starts a preflight over <paramref name="configuration"/>.</summary>
+    public static ConfigPreflight For(IConfiguration configuration)
+    {
+        ArgumentNullException.ThrowIfNull(configuration);
+        return new ConfigPreflight(configuration);
+    }
+
+    /// <summary>The accumulated failure messages (empty when valid).</summary>
+    public IReadOnlyList<string> Failures => _failures;
+
+    /// <summary>True when no failures have been accumulated.</summary>
+    public bool IsValid => _failures.Count == 0;
+
+    /// <summary>Requires the value at <paramref name="key"/> to satisfy <paramref name="predicate"/>.</summary>
+    public ConfigPreflight Require(string key, Func<string?, bool> predicate, string reason)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(key);
+        ArgumentNullException.ThrowIfNull(predicate);
+        if (!predicate(_configuration[key])) _failures.Add($"{key} {reason}");
+        return this;
+    }
+
+    /// <summary>Requires a non-empty value at <paramref name="key"/>.</summary>
+    public ConfigPreflight RequireValue(string key)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(key);
+        return AddIf(Checks.Required(_configuration[key], key));
+    }
+
+    /// <summary>Requires a valid integer TCP port (1-65535) at <paramref name="key"/>.</summary>
+    public ConfigPreflight RequirePort(string key)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(key);
+        return AddIf(Checks.PortValue(_configuration[key], key));
+    }
+
+    /// <summary>Runs <paramref name="block"/> only when <paramref name="condition"/> holds (role-conditional rules).</summary>
+    public ConfigPreflight When(bool condition, Action<ConfigPreflight> block)
+    {
+        ArgumentNullException.ThrowIfNull(block);
+        if (condition) block(this);
+        return this;
+    }
+
+    /// <summary>Throws <see cref="InvalidOperationException"/> listing all failures when invalid; otherwise returns.</summary>
+    public void ThrowIfInvalid()
+    {
+        if (_failures.Count > 0)
+            throw new InvalidOperationException(
+                $"Configuration validation failed:\n{string.Join("\n", _failures.Select(e => $"  - {e}"))}");
+    }
+
+    private ConfigPreflight AddIf(string? message)
+    {
+        if (message is not null) _failures.Add(message);
+        return this;
+    }
+}
@@ -0,0 +1,30 @@
+using Microsoft.Extensions.Options;
+
+namespace ZB.MOM.WW.Configuration;
+
+/// <summary>
+/// Base class for <see cref="IValidateOptions{TOptions}"/> implementations that removes the
+/// failure-accumulation plumbing. Override <see cref="Validate(ValidationBuilder, TOptions)"/> and
+/// use the supplied <see cref="ValidationBuilder"/>; the base aggregates ALL failures and returns
+/// <see cref="ValidateOptionsResult.Success"/> only when none were recorded.
+/// </summary>
+/// <typeparam name="TOptions">The options type being validated.</typeparam>
+public abstract class OptionsValidatorBase<TOptions> : IValidateOptions<TOptions>
+    where TOptions : class
+{
+    /// <inheritdoc />
+    public ValidateOptionsResult Validate(string? name, TOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        var builder = new ValidationBuilder();
+        Validate(builder, options);
+        return builder.IsValid
+            ? ValidateOptionsResult.Success
+            : ValidateOptionsResult.Fail(builder.Failures);
+    }
+
+    /// <summary>Records validation failures for <paramref name="options"/> on <paramref name="builder"/>.</summary>
+    /// <param name="builder">The accumulator to record failures on.</param>
+    /// <param name="options">The options instance to validate.</param>
+    protected abstract void Validate(ValidationBuilder builder, TOptions options);
+}
@@ -0,0 +1,42 @@
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Extensions.Options;
+
+namespace ZB.MOM.WW.Configuration;
+
+/// <summary>DI extensions for binding-and-validating an options section in one call.</summary>
+public static class ServiceCollectionExtensions
+{
+    /// <summary>
+    /// Binds <typeparamref name="TOptions"/> to the configuration section at
+    /// <paramref name="sectionPath"/>, registers <typeparamref name="TValidator"/> as its
+    /// <see cref="IValidateOptions{TOptions}"/>, and enables <c>ValidateOnStart</c> so a bad
+    /// configuration fails fast at host startup rather than on first use.
+    /// </summary>
+    /// <typeparam name="TOptions">The options type to bind and validate.</typeparam>
+    /// <typeparam name="TValidator">The validator registered for <typeparamref name="TOptions"/>.</typeparam>
+    /// <param name="services">The service collection.</param>
+    /// <param name="configuration">The configuration to bind from.</param>
+    /// <param name="sectionPath">The configuration section path (e.g. <c>"ScadaBridge:Cluster"</c>).</param>
+    /// <returns>The <see cref="OptionsBuilder{TOptions}"/> for further chaining.</returns>
+    /// <remarks>
+    /// <typeparamref name="TValidator"/> is registered as a singleton (it is consumed by the
+    /// singleton options factory). It must therefore be safe to use as a singleton — do not
+    /// inject scoped dependencies into it.
+    /// </remarks>
+    public static OptionsBuilder<TOptions> AddValidatedOptions<TOptions, TValidator>(
+        this IServiceCollection services, IConfiguration configuration, string sectionPath)
+        where TOptions : class
+        where TValidator : class, IValidateOptions<TOptions>
+    {
+        ArgumentNullException.ThrowIfNull(services);
+        ArgumentNullException.ThrowIfNull(configuration);
+        ArgumentException.ThrowIfNullOrWhiteSpace(sectionPath);
+
+        services.TryAddEnumerable(ServiceDescriptor.Singleton<IValidateOptions<TOptions>, TValidator>());
+        return services.AddOptions<TOptions>()
+            .Bind(configuration.GetSection(sectionPath))
+            .ValidateOnStart();
+    }
+}
@@ -0,0 +1,60 @@
+namespace ZB.MOM.WW.Configuration;
+
+/// <summary>
+/// Accumulates validation failures for an options object. Passed by
+/// <see cref="OptionsValidatorBase{TOptions}"/> into your <c>Validate</c> override; each primitive
+/// both checks a value and appends a consistently-formatted message on failure. Use
+/// <see cref="RequireThat"/>/<see cref="Add"/> for custom or cross-field rules.
+/// </summary>
+public sealed class ValidationBuilder
+{
+    private readonly List<string> _failures = [];
+
+    /// <summary>The accumulated failure messages (empty when validation passed).</summary>
+    public IReadOnlyList<string> Failures => _failures;
+
+    /// <summary>True when no failures have been accumulated.</summary>
+    public bool IsValid => _failures.Count == 0;
+
+    /// <summary>Records <paramref name="message"/> as a failure when <paramref name="ok"/> is false.</summary>
+    public ValidationBuilder RequireThat(bool ok, string message)
+    {
+        if (!ok) _failures.Add(message);
+        return this;
+    }
+
+    /// <summary>Unconditionally records <paramref name="message"/> as a failure.</summary>
+    public ValidationBuilder Add(string message)
+    {
+        _failures.Add(message);
+        return this;
+    }
+
+    /// <summary>Requires a non-null, non-whitespace string.</summary>
+    public ValidationBuilder Required(string? value, string field) => AddIf(Checks.Required(value, field));
+
+    /// <summary>Requires a TCP port in 1-65535.</summary>
+    public ValidationBuilder Port(int value, string field) => AddIf(Checks.Port(value, field));
+
+    /// <summary>Requires a 'host:port' endpoint with a valid port.</summary>
+    public ValidationBuilder HostPort(string? value, string field) => AddIf(Checks.HostPort(value, field));
+
+    /// <summary>Requires a strictly positive duration.</summary>
+    public ValidationBuilder PositiveTimeSpan(TimeSpan value, string field) => AddIf(Checks.PositiveTimeSpan(value, field));
+
+    /// <summary>
+    /// Requires the value to be one of <paramref name="allowed"/> (case-insensitive). A
+    /// <c>null</c> value fails this rule; call <see cref="Required"/> first if the field may be
+    /// absent and you want a "required" message instead of a "must be one of" message.
+    /// </summary>
+    public ValidationBuilder OneOf(string? value, IReadOnlyCollection<string> allowed, string field) => AddIf(Checks.OneOf(value, allowed, field));
+
+    /// <summary>Requires a collection with at least <paramref name="min"/> items.</summary>
+    public ValidationBuilder MinCount<T>(IReadOnlyCollection<T>? value, int min, string field) => AddIf(Checks.MinCount(value, min, field));
+
+    private ValidationBuilder AddIf(string? message)
+    {
+        if (message is not null) _failures.Add(message);
+        return this;
+    }
+}
@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <IsPackable>true</IsPackable>
+    <PackageId>ZB.MOM.WW.Configuration</PackageId>
+    <Authors>ZB.MOM.WW</Authors>
+    <Description>Startup configuration-validation toolkit for the ZB.MOM.WW SCADA family: a failure-accumulating IValidateOptions base, reusable rule primitives (port, host:port, required, positive-duration, one-of, min-count), a bind+validate+ValidateOnStart DI helper, and a pre-host ConfigPreflight aggregator for raw IConfiguration. Extracts the validation plumbing the apps share; domain rules stay per-project.</Description>
+    <PackageTags>configuration;options;validation;ivalidateoptions;validateonstart;startup;scada;wonderware;zb-mom-ww</PackageTags>
+    <PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-configuration</PackageProjectUrl>
+    <RepositoryUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-configuration</RepositoryUrl>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+  </PropertyGroup>
+  <ItemGroup>
+    <None Include="..\..\README.md" Pack="true" PackagePath="\" />
+  </ItemGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Options" />
+    <PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,67 @@
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.Configuration.Tests;
+
+public sealed class AddValidatedOptionsTests
+{
+    private sealed class NodeOptions { public int Port { get; set; } public string? Name { get; set; } }
+
+    private sealed class NodeValidator : OptionsValidatorBase<NodeOptions>
+    {
+        protected override void Validate(ValidationBuilder v, NodeOptions o)
+        {
+            v.Port(o.Port, "Node:Port");
+            v.Required(o.Name, "Node:Name");
+        }
+    }
+
+    private static IHost BuildHost(Dictionary<string, string?> config)
+    {
+        var builder = Host.CreateApplicationBuilder();
+        builder.Configuration.AddInMemoryCollection(config);
+        builder.Services.AddValidatedOptions<NodeOptions, NodeValidator>(builder.Configuration, "Node");
+        return builder.Build();
+    }
+
+    [Fact]
+    public async Task Bad_config_throws_at_startup()
+    {
+        using var host = BuildHost(new() { ["Node:Port"] = "0", ["Node:Name"] = "" });
+        await Assert.ThrowsAsync<OptionsValidationException>(() => host.StartAsync());
+    }
+
+    [Fact]
+    public async Task Good_config_starts_and_binds()
+    {
+        using var host = BuildHost(new() { ["Node:Port"] = "8080", ["Node:Name"] = "central" });
+        await host.StartAsync();
+        var opts = host.Services.GetRequiredService<IOptions<NodeOptions>>().Value;
+        Assert.Equal(8080, opts.Port);
+        Assert.Equal("central", opts.Name);
+        await host.StopAsync();
+    }
+
+    [Fact]
+    public void Calling_twice_registers_validator_once()
+    {
+        var config = new ConfigurationBuilder()
+            .AddInMemoryCollection(new Dictionary<string, string?> { ["Node:Port"] = "0", ["Node:Name"] = "" })
+            .Build();
+        var services = new ServiceCollection();
+        services.AddValidatedOptions<NodeOptions, NodeValidator>(config, "Node");
+        services.AddValidatedOptions<NodeOptions, NodeValidator>(config, "Node");
+
+        using var provider = services.BuildServiceProvider();
+        var validators = provider.GetServices<IValidateOptions<NodeOptions>>().ToArray();
+        Assert.Single(validators);
+
+        // Resolving the options surfaces each accumulated failure exactly once, not doubled.
+        var ex = Assert.Throws<OptionsValidationException>(
+            () => provider.GetRequiredService<IOptions<NodeOptions>>().Value);
+        Assert.Equal(2, ex.Failures.Count());
+    }
+}
@@ -0,0 +1,92 @@
+using Microsoft.Extensions.Configuration;
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.Configuration.Tests;
+
+/// <summary>
+/// Pins the exact failure-message wording produced by the shared <c>Checks</c> seam through its
+/// public front-ends (<see cref="ConfigPreflight"/> for raw port values, <see cref="ValidationBuilder"/>
+/// for host:port endpoints). Covers Configuration-002 (consistent quoting) and Configuration-003
+/// (strict, culture-invariant port parsing).
+/// </summary>
+public sealed class ChecksWordingTests
+{
+    private static IConfiguration Config(string key, string? value) =>
+        new ConfigurationBuilder()
+            .AddInMemoryCollection(new Dictionary<string, string?> { [key] = value })
+            .Build();
+
+    private static string PortFailure(string? rawValue)
+    {
+        var pf = ConfigPreflight.For(Config("X:Port", rawValue)).RequirePort("X:Port");
+        return Assert.Single(pf.Failures);
+    }
+
+    // Configuration-002: range failure and parse failure must quote the offending value the same way.
+
+    [Fact]
+    public void PortValue_range_failure_quotes_the_value()
+    {
+        Assert.Equal("X:Port must be between 1 and 65535 (was '0')", PortFailure("0"));
+    }
+
+    [Fact]
+    public void PortValue_high_range_failure_quotes_the_value()
+    {
+        Assert.Equal("X:Port must be between 1 and 65535 (was '70000')", PortFailure("70000"));
+    }
+
+    [Fact]
+    public void PortValue_parse_failure_quotes_the_value()
+    {
+        Assert.Equal("X:Port must be between 1 and 65535 (was 'notaport')", PortFailure("notaport"));
+    }
+
+    [Fact]
+    public void PortValue_null_failure_renders_null()
+    {
+        Assert.Equal("X:Port must be between 1 and 65535 (was 'null')", PortFailure(null));
+    }
+
+    // Configuration-003: strict, culture-invariant parsing rejects sign and surrounding whitespace.
+
+    [Theory]
+    [InlineData("+5000")]
+    [InlineData(" 5000")]
+    [InlineData("5000 ")]
+    [InlineData(" 5000 ")]
+    [InlineData("-1")]
+    public void PortValue_rejects_loose_inputs(string raw)
+    {
+        var pf = ConfigPreflight.For(Config("X:Port", raw)).RequirePort("X:Port");
+        Assert.False(pf.IsValid);
+        Assert.Equal($"X:Port must be between 1 and 65535 (was '{raw}')", Assert.Single(pf.Failures));
+    }
+
+    [Fact]
+    public void PortValue_accepts_plain_in_range_port()
+    {
+        var pf = ConfigPreflight.For(Config("X:Port", "5000")).RequirePort("X:Port");
+        Assert.True(pf.IsValid);
+    }
+
+    [Theory]
+    [InlineData("host:+5000")]
+    [InlineData("host: 5000")]
+    [InlineData("host:5000 ")]
+    public void HostPort_rejects_loose_port_inputs(string value)
+    {
+        var b = new ValidationBuilder();
+        b.HostPort(value, "X:Endpoint");
+        Assert.False(b.IsValid);
+        Assert.Equal($"X:Endpoint must be 'host:port' with port 1-65535 (was '{value}')", Assert.Single(b.Failures));
+    }
+
+    [Fact]
+    public void HostPort_accepts_plain_endpoint()
+    {
+        var b = new ValidationBuilder();
+        b.HostPort("host:5000", "X:Endpoint");
+        Assert.True(b.IsValid);
+    }
+}
@@ -0,0 +1,58 @@
+using Microsoft.Extensions.Configuration;
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.Configuration.Tests;
+
+public sealed class ConfigPreflightTests
+{
+    private static IConfiguration Config(Dictionary<string, string?> values) =>
+        new ConfigurationBuilder().AddInMemoryCollection(values).Build();
+
+    [Fact]
+    public void Aggregates_all_failures()
+    {
+        var cfg = Config(new() { ["Node:Role"] = "Bogus", ["Node:RemotingPort"] = "0" });
+        var pf = ConfigPreflight.For(cfg)
+            .Require("Node:Role", v => v is "Central" or "Site", "must be 'Central' or 'Site'")
+            .RequirePort("Node:RemotingPort");
+        Assert.False(pf.IsValid);
+        Assert.Equal(2, pf.Failures.Count);
+    }
+
+    [Fact]
+    public void When_runs_block_only_if_condition_true()
+    {
+        var cfg = Config(new() { ["Node:Role"] = "Site" });
+        var pf = ConfigPreflight.For(cfg)
+            .When(cfg["Node:Role"] == "Site",
+                p => p.RequireValue("Node:SiteId"));
+        Assert.False(pf.IsValid);              // SiteId missing
+        Assert.Contains(pf.Failures, f => f.Contains("Node:SiteId"));
+    }
+
+    [Fact]
+    public void When_false_does_not_run_block()
+    {
+        var cfg = Config(new() { ["Node:Role"] = "Central" });
+        var pf = ConfigPreflight.For(cfg)
+            .When(cfg["Node:Role"] == "Site", p => p.RequireValue("Node:SiteId"));
+        Assert.True(pf.IsValid);   // block skipped, no failure recorded
+    }
+
+    [Fact]
+    public void ThrowIfInvalid_throws_aggregated_message()
+    {
+        var cfg = Config(new() { ["Node:Name"] = "" });
+        var ex = Assert.Throws<InvalidOperationException>(() =>
+            ConfigPreflight.For(cfg).RequireValue("Node:Name").ThrowIfInvalid());
+        Assert.StartsWith("Configuration validation failed:", ex.Message);
+        Assert.Contains("  - Node:Name", ex.Message);
+    }
+
+    [Fact]
+    public void ThrowIfInvalid_is_noop_when_valid()
+    {
+        var cfg = Config(new() { ["Node:Name"] = "ok" });
+        ConfigPreflight.For(cfg).RequireValue("Node:Name").ThrowIfInvalid();   // does not throw
+    }
+}
@@ -0,0 +1,37 @@
+using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.Configuration.Tests;
+
+public sealed class OptionsValidatorBaseTests
+{
+    private sealed class SampleOptions
+    {
+        public int Port { get; set; }
+        public string? Name { get; set; }
+    }
+
+    private sealed class SampleValidator : OptionsValidatorBase<SampleOptions>
+    {
+        protected override void Validate(ValidationBuilder v, SampleOptions o)
+        {
+            v.Port(o.Port, "Sample:Port");
+            v.Required(o.Name, "Sample:Name");
+        }
+    }
+
+    [Fact]
+    public void Success_when_clean()
+    {
+        var r = new SampleValidator().Validate(null, new SampleOptions { Port = 8080, Name = "ok" });
+        Assert.True(r.Succeeded);
+    }
+
+    [Fact]
+    public void Fails_and_reports_all_failures()
+    {
+        var r = new SampleValidator().Validate(null, new SampleOptions { Port = 0, Name = "" });
+        Assert.True(r.Failed);
+        Assert.Equal(2, r.Failures!.Count());
+    }
+}
@@ -0,0 +1,84 @@
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.Configuration.Tests;
+
+public sealed class ValidationBuilderTests
+{
+    [Theory]
+    [InlineData(0, false)]
+    [InlineData(1, true)]
+    [InlineData(65535, true)]
+    [InlineData(65536, false)]
+    public void Port_validates_range(int port, bool valid)
+    {
+        var b = new ValidationBuilder();
+        b.Port(port, "X:Port");
+        Assert.Equal(valid, b.IsValid);
+    }
+
+    [Theory]
+    [InlineData(null, false)]
+    [InlineData("", false)]
+    [InlineData("   ", false)]
+    [InlineData("ok", true)]
+    public void Required_rejects_null_empty_whitespace(string? value, bool valid)
+    {
+        var b = new ValidationBuilder();
+        b.Required(value, "X:Name");
+        Assert.Equal(valid, b.IsValid);
+    }
+
+    [Theory]
+    [InlineData("host:5000", true)]
+    [InlineData("host", false)]
+    [InlineData("host:0", false)]
+    [InlineData("host:notaport", false)]
+    [InlineData("::1", false)]
+    public void HostPort_validates_endpoint(string value, bool valid)
+    {
+        var b = new ValidationBuilder();
+        b.HostPort(value, "X:Endpoint");
+        Assert.Equal(valid, b.IsValid);
+    }
+
+    [Fact]
+    public void PositiveTimeSpan_rejects_zero_and_negative()
+    {
+        var b = new ValidationBuilder();
+        b.PositiveTimeSpan(TimeSpan.Zero, "X:T1").PositiveTimeSpan(TimeSpan.FromSeconds(-1), "X:T2");
+        Assert.Equal(2, b.Failures.Count);
+    }
+
+    [Fact]
+    public void OneOf_is_case_insensitive()
+    {
+        var b = new ValidationBuilder();
+        b.OneOf("CENTRAL", new[] { "Central", "Site" }, "X:Role");
+        Assert.True(b.IsValid);
+    }
+
+    [Fact]
+    public void OneOf_null_value_fails()
+    {
+        var b = new ValidationBuilder();
+        b.OneOf(null, new[] { "Central", "Site" }, "X:Role");
+        Assert.False(b.IsValid);
+        Assert.Contains(b.Failures, f => f.Contains("X:Role"));
+    }
+
+    [Fact]
+    public void MinCount_requires_minimum()
+    {
+        var b = new ValidationBuilder();
+        b.MinCount(new[] { "a" }, 2, "X:Seeds");
+        Assert.False(b.IsValid);
+    }
+
+    [Fact]
+    public void Accumulates_all_failures_and_RequireThat_Add_work()
+    {
+        var b = new ValidationBuilder();
+        b.Required(null, "A").RequireThat(false, "B failed").Add("C failed");
+        Assert.Equal(3, b.Failures.Count);
+    }
+}
@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <IsPackable>false</IsPackable>
+    <!-- Test project does not ship; no XML docs required (overrides Directory.Build.props). -->
+    <GenerateDocumentationFile>false</GenerateDocumentationFile>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="coverlet.collector" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+    <PackageReference Include="xunit" />
+    <PackageReference Include="xunit.runner.visualstudio" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+  </ItemGroup>
+  <ItemGroup>
+    <Using Include="Xunit" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\ZB.MOM.WW.Configuration\ZB.MOM.WW.Configuration.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,11 @@
+<Project>
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <LangVersion>latest</LangVersion>
+    <Version>0.2.0</Version>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+  </PropertyGroup>
+</Project>
@@ -0,0 +1,24 @@
+<Project>
+
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- Library -->
+    <PackageVersion Include="Microsoft.Data.SqlClient" Version="6.0.2" />
+    <PackageVersion Include="Grpc.AspNetCore" Version="2.76.0" />
+    <!-- Google.Protobuf and Grpc.Tools must be >= the minimums Grpc.AspNetCore 2.76.0 requires -->
+    <PackageVersion Include="Google.Protobuf" Version="3.31.1" />
+    <PackageVersion Include="Microsoft.Extensions.Hosting.Abstractions" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="10.0.0" />
+    <PackageVersion Include="Grpc.Tools" Version="2.76.0" />
+
+    <!-- Test -->
+    <PackageVersion Include="xunit" Version="2.9.3" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.4" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageVersion Include="coverlet.collector" Version="6.0.4" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,8 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/ZB.MOM.WW.GalaxyRepository/ZB.MOM.WW.GalaxyRepository.csproj" />
+  </Folder>
+  <Folder Name="/tests/">
+    <Project Path="tests/ZB.MOM.WW.GalaxyRepository.Tests/ZB.MOM.WW.GalaxyRepository.Tests.csproj" />
+  </Folder>
+</Solution>
@@ -0,0 +1,75 @@
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Routing;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Extensions.Options;
+using ZB.MOM.WW.GalaxyRepository.Grpc;
+
+namespace ZB.MOM.WW.GalaxyRepository.DependencyInjection;
+
+/// <summary>
+///     Dependency-injection and endpoint-routing extensions that register the reusable
+///     Galaxy Repository services and map the canonical gRPC service. A consuming gateway
+///     calls <see cref="AddZbGalaxyRepository"/> during service registration and
+///     <see cref="MapZbGalaxyRepository"/> while building its endpoint pipeline.
+/// </summary>
+public static class GalaxyRepositoryServiceCollectionExtensions
+{
+    /// <summary>
+    ///     Registers the Galaxy Repository SQL provider, shared hierarchy cache, deploy
+    ///     notifier, on-disk snapshot store, and the background refresh service, binding
+    ///     <see cref="GalaxyRepositoryOptions"/> from the supplied configuration section.
+    /// </summary>
+    /// <param name="services">The service collection to add registrations to.</param>
+    /// <param name="configuration">The application configuration root.</param>
+    /// <param name="sectionPath">
+    ///     The configuration section path to bind <see cref="GalaxyRepositoryOptions"/> from
+    ///     (for example <c>MxGateway:Galaxy</c> or <c>HistorianGateway:Galaxy</c>).
+    /// </param>
+    /// <returns>The service collection for chaining.</returns>
+    public static IServiceCollection AddZbGalaxyRepository(
+        this IServiceCollection services,
+        IConfiguration configuration,
+        string sectionPath)
+    {
+        ArgumentNullException.ThrowIfNull(services);
+        ArgumentNullException.ThrowIfNull(configuration);
+        ArgumentException.ThrowIfNullOrWhiteSpace(sectionPath);
+
+        // Bind only — this shared lib ships no validator, so a .ValidateOnStart() here
+        // would be a silent no-op. The consuming application owns option validation
+        // (e.g. the sidecar's ConfigPreflight / validated-options layer).
+        services
+            .AddOptions<GalaxyRepositoryOptions>()
+            .Bind(configuration.GetSection(sectionPath));
+
+        services.AddSingleton(sp =>
+            new GalaxyRepository(sp.GetRequiredService<IOptions<GalaxyRepositoryOptions>>().Value));
+        services.AddSingleton<IGalaxyRepository>(sp => sp.GetRequiredService<GalaxyRepository>());
+
+        services.AddSingleton<IGalaxyDeployNotifier, GalaxyDeployNotifier>();
+        services.AddSingleton<IGalaxyHierarchySnapshotStore, GalaxyHierarchySnapshotStore>();
+        services.AddSingleton<IGalaxyHierarchyCache, GalaxyHierarchyCache>();
+        services.AddHostedService<GalaxyHierarchyRefreshService>();
+
+        // Allow the hosting gateway to override with its own scoped implementation.
+        services.TryAddSingleton<IGalaxyBrowseScopeProvider, NullGalaxyBrowseScopeProvider>();
+
+        return services;
+    }
+
+    /// <summary>
+    ///     Maps the canonical <see cref="GalaxyRepositoryGrpcService"/> onto the consuming
+    ///     application's endpoint pipeline. Call after <see cref="AddZbGalaxyRepository"/> and
+    ///     after gRPC has been added to the application's services.
+    /// </summary>
+    /// <param name="endpoints">The endpoint route builder to map the gRPC service onto.</param>
+    /// <returns>The endpoint route builder for chaining.</returns>
+    public static IEndpointRouteBuilder MapZbGalaxyRepository(this IEndpointRouteBuilder endpoints)
+    {
+        ArgumentNullException.ThrowIfNull(endpoints);
+        endpoints.MapGrpcService<GalaxyRepositoryGrpcService>();
+        return endpoints;
+    }
+}
@@ -0,0 +1,48 @@
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     One alarm-bearing attribute discovered by <c>GalaxyRepository.GetAlarmAttributesAsync</c>:
+///     an attribute whose owning object configures an <c>AlarmExtension</c> primitive (the
+///     same <c>is_alarm</c> detection used by
+///     <see cref="GalaxyRepository.GetAttributesAsync"/>).
+///     Used to build the subtag-fallback watch-list.
+/// </summary>
+public sealed class GalaxyAlarmAttributeRow
+{
+    /// <summary>
+    ///     Gets the alarm-bearing attribute reference (e.g. <c>Tank01.Level.HiHi</c>),
+    ///     matching the <c>full_tag_reference</c> projection of
+    ///     <see cref="GalaxyRepository.GetAttributesAsync"/>.
+    /// </summary>
+    public string FullTagReference { get; init; } = string.Empty;
+
+    /// <summary>
+    ///     Gets the owning object reference (e.g. <c>Tank01</c>). This is the Galaxy
+    ///     <c>tag_name</c> — the segment that precedes the first attribute dot in
+    ///     <see cref="FullTagReference"/>.
+    /// </summary>
+    public string SourceObjectReference { get; init; } = string.Empty;
+
+    /// <summary>
+    ///     Gets the owning object's Galaxy area (e.g. <c>TestArea</c>) — the alarm group.
+    ///     <para>
+    ///     Resolved via <c>gobject.area_gobject_id</c> in <c>AlarmAttributesSql</c>. The
+    ///     watch-list resolver composes the canonical <c>Galaxy!{area}.{reference}</c> from
+    ///     this so the synthesized reference's group matches the native alarmmgr (wnwrap)
+    ///     for reference parity. May be <see cref="string.Empty"/> when the object has no
+    ///     area; the resolver then falls back to the configured area.
+    ///     </para>
+    /// </summary>
+    public string Area { get; init; } = string.Empty;
+
+    /// <summary>
+    ///     Gets the writable ack-comment attribute address.
+    ///     <para>
+    ///     The Galaxy Repository schema does not expose an ack-comment subtag address
+    ///     directly, so this is always <see cref="string.Empty"/> here. The watch-list
+    ///     resolver (a later task) composes the concrete address from configuration plus
+    ///     <see cref="SourceObjectReference"/> / <see cref="FullTagReference"/>.
+    ///     </para>
+    /// </summary>
+    public string AckCommentSubtag { get; init; } = string.Empty;
+}
@@ -0,0 +1,41 @@
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>One row from <see cref="GalaxyRepository.GetAttributesAsync"/>.</summary>
+public sealed class GalaxyAttributeRow
+{
+    /// <summary>Gets the Galaxy object identifier.</summary>
+    public int GobjectId { get; init; }
+
+    /// <summary>Gets the tag name.</summary>
+    public string TagName { get; init; } = string.Empty;
+
+    /// <summary>Gets the attribute name.</summary>
+    public string AttributeName { get; init; } = string.Empty;
+
+    /// <summary>Gets the full tag reference.</summary>
+    public string FullTagReference { get; init; } = string.Empty;
+
+    /// <summary>Gets the MXAccess data type code.</summary>
+    public int MxDataType { get; init; }
+
+    /// <summary>Gets the data type name.</summary>
+    public string? DataTypeName { get; init; }
+
+    /// <summary>Gets a value indicating whether this is an array.</summary>
+    public bool IsArray { get; init; }
+
+    /// <summary>Gets the array dimension, if applicable.</summary>
+    public int? ArrayDimension { get; init; }
+
+    /// <summary>Gets the MXAccess attribute category code.</summary>
+    public int MxAttributeCategory { get; init; }
+
+    /// <summary>Gets the security classification code.</summary>
+    public int SecurityClassification { get; init; }
+
+    /// <summary>Gets a value indicating whether this is historized.</summary>
+    public bool IsHistorized { get; init; }
+
+    /// <summary>Gets a value indicating whether this is an alarm.</summary>
+    public bool IsAlarm { get; init; }
+}
@@ -0,0 +1,19 @@
+using ZB.MOM.WW.GalaxyRepository.Grpc;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     Result of one <see cref="GalaxyBrowseProjector.ProjectChildren"/> call. Holds a
+///     materialized page of direct children for the requested parent, along with a
+///     parallel-indexed <see cref="ChildHasChildren"/> hint and the total post-filter
+///     sibling count for paging.
+/// </summary>
+/// <param name="Children">The page of direct children, sorted areas-first then by display name.</param>
+/// <param name="ChildHasChildren">Parallel array indicating whether each child has at least one matching descendant under the same filter set.</param>
+/// <param name="TotalChildCount">Total matching direct children of the parent (post-filter).</param>
+/// <param name="FilterSignature">Stable signature of the filter and parent selector, used to bind page tokens.</param>
+public sealed record GalaxyBrowseChildrenResult(
+    IReadOnlyList<GalaxyObject> Children,
+    IReadOnlyList<bool> ChildHasChildren,
+    int TotalChildCount,
+    string FilterSignature);
@@ -0,0 +1,281 @@
+using System.Collections.Concurrent;
+using System.Runtime.CompilerServices;
+using System.Security.Cryptography;
+using System.Text;
+using Grpc.Core;
+using ZB.MOM.WW.GalaxyRepository.Grpc;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     Projects one level of children of a parent object out of an immutable
+///     <see cref="GalaxyHierarchyCacheEntry"/>. Pure and side-effect free. Memoizes the
+///     filtered child list per cache-entry instance so repeated paging is an O(pageSize)
+///     slice rather than an O(siblings) filter scan per page. The memo is keyed on the
+///     immutable cache entry, so when the cache publishes a new entry the stale memo
+///     becomes unreachable and is reclaimed with it.
+/// </summary>
+public static class GalaxyBrowseProjector
+{
+    private static readonly ConditionalWeakTable<
+        GalaxyHierarchyCacheEntry,
+        ConcurrentDictionary<string, FilteredChildren>> FilteredChildrenCache = new();
+
+    /// <summary>Projects one page of direct children of the resolved parent.</summary>
+    /// <param name="entry">The Galaxy hierarchy cache entry to query.</param>
+    /// <param name="request">The browse-children request.</param>
+    /// <param name="browseSubtreeGlobs">Optional API-key browse-subtree constraints.</param>
+    /// <param name="offset">Zero-based offset into the filtered child list.</param>
+    /// <param name="pageSize">Maximum number of children to return.</param>
+    public static GalaxyBrowseChildrenResult ProjectChildren(
+        GalaxyHierarchyCacheEntry entry,
+        BrowseChildrenRequest 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.");
+        }
+
+        int parentId = ResolveParentId(entry, request);
+        string filterSignature = ComputeFilterSignature(request, browseSubtreeGlobs, parentId);
+        FilteredChildren filtered = GetFilteredChildren(entry, request, browseSubtreeGlobs, parentId, filterSignature);
+
+        bool includeAttributes = IncludeAttributes(request);
+        int end = (int)Math.Min((long)offset + pageSize, filtered.Children.Count);
+        List<GalaxyObject> page = new(Math.Max(0, end - offset));
+        List<bool> hasChildren = new(Math.Max(0, end - offset));
+        for (int index = offset; index < end; index++)
+        {
+            page.Add(CloneObject(filtered.Children[index].Object, includeAttributes));
+            hasChildren.Add(filtered.HasMatchingDescendant[index]);
+        }
+
+        return new GalaxyBrowseChildrenResult(page, hasChildren, filtered.Children.Count, filterSignature);
+    }
+
+    /// <summary>
+    ///     Resolves the request's parent oneof to a gobject id, throwing
+    ///     <see cref="RpcException"/> with <see cref="StatusCode.NotFound"/> when the
+    ///     parent does not exist. Public so the gRPC handler can compute the same
+    ///     parent id (needed for the page-token signature) without reimplementing the
+    ///     resolution rules.
+    /// </summary>
+    /// <param name="entry">The Galaxy hierarchy cache entry to query.</param>
+    /// <param name="request">The browse-children request.</param>
+    public static int ResolveParentId(GalaxyHierarchyCacheEntry entry, BrowseChildrenRequest request)
+    {
+        switch (request.ParentCase)
+        {
+            case BrowseChildrenRequest.ParentOneofCase.None:
+                return 0;
+            case BrowseChildrenRequest.ParentOneofCase.ParentGobjectId:
+                if (request.ParentGobjectId == 0)
+                {
+                    return 0;
+                }
+                if (!entry.Index.ObjectViewsById.ContainsKey(request.ParentGobjectId))
+                {
+                    throw new RpcException(new Status(StatusCode.NotFound, "BrowseChildren parent was not found."));
+                }
+                return request.ParentGobjectId;
+            case BrowseChildrenRequest.ParentOneofCase.ParentTagName:
+            {
+                if (!entry.Index.ObjectViewsByTagName.TryGetValue(request.ParentTagName, out GalaxyObjectView? match))
+                {
+                    throw new RpcException(new Status(StatusCode.NotFound, "BrowseChildren parent was not found."));
+                }
+                return match.Object.GobjectId;
+            }
+            case BrowseChildrenRequest.ParentOneofCase.ParentContainedPath:
+            {
+                if (!entry.Index.ObjectViewsByContainedPath.TryGetValue(request.ParentContainedPath, out GalaxyObjectView? match))
+                {
+                    throw new RpcException(new Status(StatusCode.NotFound, "BrowseChildren parent was not found."));
+                }
+                return match.Object.GobjectId;
+            }
+            default:
+                return 0;
+        }
+    }
+
+    private static FilteredChildren GetFilteredChildren(
+        GalaxyHierarchyCacheEntry entry,
+        BrowseChildrenRequest request,
+        IReadOnlyList<string>? browseSubtreeGlobs,
+        int parentId,
+        string filterSignature)
+    {
+        ConcurrentDictionary<string, FilteredChildren> memo =
+            FilteredChildrenCache.GetValue(entry, static _ => new ConcurrentDictionary<string, FilteredChildren>(StringComparer.Ordinal));
+
+        return memo.GetOrAdd(
+            filterSignature,
+            static (_, state) =>
+            {
+                IReadOnlyDictionary<int, IReadOnlyList<GalaxyObjectView>> map = state.Entry.Index.ChildrenByParent;
+                IReadOnlyList<GalaxyObjectView> directChildren = map.TryGetValue(state.ParentId, out IReadOnlyList<GalaxyObjectView>? list)
+                    ? list
+                    : Array.Empty<GalaxyObjectView>();
+
+                List<GalaxyObjectView> matched = [];
+                List<bool> hasMatching = [];
+                foreach (GalaxyObjectView view in directChildren)
+                {
+                    if (!MatchesBrowseSubtrees(view, state.BrowseSubtreeGlobs))
+                    {
+                        continue;
+                    }
+                    if (!MatchesFilters(view.Object, state.Request))
+                    {
+                        // Even if the direct child itself fails the filter, a matching
+                        // descendant should still surface its ancestor — but only when
+                        // there is one. Mirror the dashboard browse-tree semantics: if a
+                        // descendant matches, include the parent with has-children true.
+                        if (HasMatchingDescendant(view, state.Entry.Index, state.Request, state.BrowseSubtreeGlobs))
+                        {
+                            matched.Add(view);
+                            hasMatching.Add(true);
+                        }
+                        continue;
+                    }
+                    matched.Add(view);
+                    hasMatching.Add(HasMatchingDescendant(view, state.Entry.Index, state.Request, state.BrowseSubtreeGlobs));
+                }
+
+                return new FilteredChildren(matched, hasMatching);
+            },
+            (Entry: entry, ParentId: parentId, Request: request, BrowseSubtreeGlobs: browseSubtreeGlobs));
+    }
+
+    private static bool HasMatchingDescendant(
+        GalaxyObjectView parent,
+        GalaxyHierarchyIndex index,
+        BrowseChildrenRequest request,
+        IReadOnlyList<string>? browseSubtreeGlobs)
+    {
+        if (!index.ChildrenByParent.TryGetValue(parent.Object.GobjectId, out IReadOnlyList<GalaxyObjectView>? children))
+        {
+            return false;
+        }
+
+        // Defend against pathological cycles in Galaxy data (e.g. a corrupt A→B→A chain).
+        // BuildContainedPath uses the same visited-id pattern; mirror it so this walk
+        // terminates even when ChildrenByParent forms a cycle.
+        HashSet<int> visited = new() { parent.Object.GobjectId };
+        Stack<GalaxyObjectView> stack = new();
+        foreach (GalaxyObjectView child in children)
+        {
+            if (visited.Add(child.Object.GobjectId))
+            {
+                stack.Push(child);
+            }
+        }
+        while (stack.Count > 0)
+        {
+            GalaxyObjectView candidate = stack.Pop();
+            if (MatchesBrowseSubtrees(candidate, browseSubtreeGlobs)
+                && MatchesFilters(candidate.Object, request))
+            {
+                return true;
+            }
+            if (index.ChildrenByParent.TryGetValue(candidate.Object.GobjectId, out IReadOnlyList<GalaxyObjectView>? grandchildren))
+            {
+                foreach (GalaxyObjectView grandchild in grandchildren)
+                {
+                    if (visited.Add(grandchild.Object.GobjectId))
+                    {
+                        stack.Push(grandchild);
+                    }
+                }
+            }
+        }
+        return false;
+    }
+
+    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, BrowseChildrenRequest 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(BrowseChildrenRequest 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;
+    }
+
+    /// <summary>Computes a stable filter signature for memoization purposes.</summary>
+    /// <param name="request">The browse-children request.</param>
+    /// <param name="browseSubtreeGlobs">Optional API-key browse-subtree constraints.</param>
+    /// <param name="parentId">Resolved parent gobject id (0 for roots).</param>
+    public static string ComputeFilterSignature(
+        BrowseChildrenRequest request,
+        IReadOnlyList<string>? browseSubtreeGlobs,
+        int parentId)
+    {
+        StringBuilder builder = new();
+        builder.Append("parent=").Append(parentId.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);
+    }
+
+    private sealed record FilteredChildren(
+        IReadOnlyList<GalaxyObjectView> Children,
+        IReadOnlyList<bool> HasMatchingDescendant);
+}
@@ -0,0 +1,18 @@
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>Freshness state of the shared Galaxy hierarchy cache entry.</summary>
+public enum GalaxyCacheStatus
+{
+    /// <summary>Cache has never completed a refresh.</summary>
+    Unknown = 0,
+
+    /// <summary>Cache holds data from a recent successful refresh.</summary>
+    Healthy = 1,
+
+    /// <summary>Cache holds data, but the most recent refresh attempt failed
+    /// or no successful refresh has happened within the staleness threshold.</summary>
+    Stale = 2,
+
+    /// <summary>Latest refresh failed and no prior data is available.</summary>
+    Unavailable = 3,
+}
@@ -0,0 +1,19 @@
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     A single Galaxy deploy notification. Published by <see cref="GalaxyHierarchyCache"/>
+///     whenever a refresh detects that <c>galaxy.time_of_last_deploy</c> has changed (or on
+///     the first successful refresh). Consumed by <see cref="IGalaxyDeployNotifier"/>
+///     subscribers (the streaming gRPC RPC).
+/// </summary>
+/// <param name="Sequence">Monotonically increasing per process start; gaps indicate dropped events.</param>
+/// <param name="ObservedAt">Server wall-clock when the cache observed the deploy.</param>
+/// <param name="TimeOfLastDeploy">The <c>galaxy.time_of_last_deploy</c> value, or <see langword="null"/> when the Galaxy table reports none.</param>
+/// <param name="ObjectCount">Number of objects in the hierarchy at the time of the event.</param>
+/// <param name="AttributeCount">Number of attributes in the hierarchy at the time of the event.</param>
+public sealed record GalaxyDeployEventInfo(
+    long Sequence,
+    DateTimeOffset ObservedAt,
+    DateTimeOffset? TimeOfLastDeploy,
+    int ObjectCount,
+    int AttributeCount);
@@ -0,0 +1,79 @@
+using System.Collections.Concurrent;
+using System.Runtime.CompilerServices;
+using System.Threading.Channels;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     Channel-based fan-out of Galaxy deploy events to streaming gRPC subscribers. Each
+///     subscriber gets a private bounded channel so a slow client cannot back-pressure
+///     other subscribers or the publisher. When a subscriber's channel is full the oldest
+///     event is dropped — clients use the sequence field to detect gaps.
+/// </summary>
+public sealed class GalaxyDeployNotifier : IGalaxyDeployNotifier
+{
+    private const int SubscriberQueueCapacity = 16;
+
+    private readonly ConcurrentDictionary<Guid, Channel<GalaxyDeployEventInfo>> _subscribers = new();
+    private GalaxyDeployEventInfo? _latest;
+
+    /// <summary>
+    /// The most recent deploy event, or null if none has been published.
+    /// </summary>
+    public GalaxyDeployEventInfo? Latest => Volatile.Read(ref _latest);
+
+    /// <inheritdoc />
+    public void Publish(GalaxyDeployEventInfo info)
+    {
+        ArgumentNullException.ThrowIfNull(info);
+
+        Volatile.Write(ref _latest, info);
+
+        foreach (Channel<GalaxyDeployEventInfo> channel in _subscribers.Values)
+        {
+            // BoundedChannelFullMode.DropOldest -> writes never wait; we only fail if the
+            // channel was completed by the subscriber side, which we ignore.
+            channel.Writer.TryWrite(info);
+        }
+    }
+
+    /// <inheritdoc />
+    public async IAsyncEnumerable<GalaxyDeployEventInfo> SubscribeAsync(
+        [EnumeratorCancellation] CancellationToken cancellationToken)
+    {
+        Guid subscriberId = Guid.NewGuid();
+        Channel<GalaxyDeployEventInfo> channel = Channel.CreateBounded<GalaxyDeployEventInfo>(
+            new BoundedChannelOptions(SubscriberQueueCapacity)
+            {
+                FullMode = BoundedChannelFullMode.DropOldest,
+                SingleReader = true,
+                SingleWriter = false,
+            });
+
+        _subscribers[subscriberId] = channel;
+
+        // Bootstrap: emit the latest known event so subscribers don't need to wait for
+        // the next deploy to know current state.
+        GalaxyDeployEventInfo? bootstrap = Volatile.Read(ref _latest);
+        if (bootstrap is not null)
+        {
+            channel.Writer.TryWrite(bootstrap);
+        }
+
+        try
+        {
+            while (await channel.Reader.WaitToReadAsync(cancellationToken).ConfigureAwait(false))
+            {
+                while (channel.Reader.TryRead(out GalaxyDeployEventInfo? next))
+                {
+                    yield return next;
+                }
+            }
+        }
+        finally
+        {
+            _subscribers.TryRemove(subscriberId, out _);
+            channel.Writer.TryComplete();
+        }
+    }
+}
@@ -0,0 +1,131 @@
+using System.Collections.Concurrent;
+using System.Text;
+using System.Text.RegularExpressions;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     Anchored, case-insensitive glob matcher (<c>*</c> and <c>?</c> wildcards) used by the
+///     hierarchy and browse projectors to filter object tag names and browse subtrees.
+///     Compiled regexes are cached and the cache is bounded so an unbounded stream of distinct
+///     client-supplied globs cannot grow memory without limit.
+/// </summary>
+public static class GalaxyGlobMatcher
+{
+    /// <summary>
+    ///     Maximum number of compiled-regex entries retained in <see cref="RegexCache"/>.
+    ///     The cache is keyed by glob pattern and patterns flow in from two sources:
+    ///     admin-controlled API-key constraints (naturally bounded) and the
+    ///     client-supplied <c>DiscoverHierarchyRequest.TagNameGlob</c> (unbounded — a
+    ///     client can iterate through generated names and create millions of distinct
+    ///     globs over the process lifetime). Capping the cache bounds memory while
+    ///     keeping the hot working set hit-cached.
+    /// </summary>
+    internal const int RegexCacheCapacity = 256;
+
+    /// <summary>
+    ///     Bounded compiled-regex cache keyed by glob pattern. <c>IsMatch</c> is called
+    ///     once per object per <c>DiscoverHierarchy</c>/<c>WatchDeployEvents</c>
+    ///     evaluation, so the same handful of glob patterns are translated
+    ///     repeatedly; caching avoids rebuilding and recompiling the regex on every
+    ///     call. Beyond <see cref="RegexCacheCapacity"/> entries the oldest insertion
+    ///     is evicted so a client cannot grow the cache without bound by submitting
+    ///     unique patterns. Eviction is approximate (FIFO over insertion order, not
+    ///     true LRU) because we only need the bound, not exact recency tracking.
+    /// </summary>
+    private static readonly ConcurrentDictionary<string, Regex> RegexCache = new(StringComparer.Ordinal);
+
+    /// <summary>
+    ///     Insertion-order queue used to evict the oldest cache entry when the cache
+    ///     exceeds <see cref="RegexCacheCapacity"/>. A separate queue keeps the
+    ///     <see cref="RegexCache"/> reads lock-free; the lock below only guards the
+    ///     eviction path.
+    /// </summary>
+    private static readonly ConcurrentQueue<string> InsertionOrder = new();
+    private static readonly object EvictionLock = new();
+
+    /// <summary>
+    ///     Current cache size, exposed for tests asserting the cap is honoured.
+    /// </summary>
+    internal static int CurrentCacheSize => RegexCache.Count;
+
+    /// <summary>Determines whether a value matches a glob pattern (with * and ? wildcards).</summary>
+    /// <param name="value">The value to test against the glob pattern.</param>
+    /// <param name="glob">The glob pattern with * and ? wildcards.</param>
+    public static bool IsMatch(string value, string glob)
+    {
+        if (string.IsNullOrWhiteSpace(glob))
+        {
+            return true;
+        }
+
+        return GetOrCreateRegex(glob).IsMatch(value ?? string.Empty);
+    }
+
+    private static Regex GetOrCreateRegex(string glob)
+    {
+        if (RegexCache.TryGetValue(glob, out Regex? existing))
+        {
+            return existing;
+        }
+
+        Regex compiled = new(
+            BuildRegex(glob),
+            RegexOptions.CultureInvariant | RegexOptions.IgnoreCase | RegexOptions.Compiled,
+            TimeSpan.FromMilliseconds(100));
+
+        // GetOrAdd atomically returns whichever instance is in the cache after the
+        // call — either the locally-compiled regex (we won the race) or the regex
+        // another thread inserted (we lost). It also avoids the TryAdd-then-indexer
+        // pattern where the key could be evicted between the failed TryAdd and the
+        // indexer read, producing a KeyNotFoundException under contention near the cap.
+        Regex result = RegexCache.GetOrAdd(glob, compiled);
+        if (ReferenceEquals(result, compiled))
+        {
+            // We were the inserter — track for FIFO eviction and bound the cache.
+            InsertionOrder.Enqueue(glob);
+            EvictIfOverCapacity();
+        }
+        return result;
+    }
+
+    private static void EvictIfOverCapacity()
+    {
+        if (RegexCache.Count <= RegexCacheCapacity)
+        {
+            return;
+        }
+
+        // Serialize eviction so two threads do not race past the cap together.
+        lock (EvictionLock)
+        {
+            while (RegexCache.Count > RegexCacheCapacity && InsertionOrder.TryDequeue(out string? oldest))
+            {
+                RegexCache.TryRemove(oldest, out _);
+            }
+        }
+    }
+
+    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();
+    }
+}
@@ -0,0 +1,365 @@
+using Microsoft.Extensions.Logging;
+using ZB.MOM.WW.GalaxyRepository.Grpc;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     Server-side cache of Galaxy Repository browse data. All gRPC clients share the same
+///     entry — the materialized object list is produced once per refresh and reused across
+///     requests. Refreshes are deploy-time gated: every tick queries
+///     <c>galaxy.time_of_last_deploy</c> (cheap), and the heavy hierarchy + attributes rowsets
+///     are pulled only when that timestamp has advanced.
+///     Each successful heavy refresh is persisted to disk through
+///     <see cref="IGalaxyHierarchySnapshotStore"/>; the first refresh restores that
+///     snapshot (as <see cref="GalaxyCacheStatus.Stale"/>) so clients can browse
+///     last-known data when the Galaxy database is unreachable on a cold start.
+/// </summary>
+public sealed class GalaxyHierarchyCache : IGalaxyHierarchyCache, IDisposable
+{
+    private static readonly TimeSpan StaleThreshold = TimeSpan.FromMinutes(5);
+
+    private readonly IGalaxyRepository _repository;
+    private readonly IGalaxyDeployNotifier _notifier;
+    private readonly IGalaxyHierarchySnapshotStore? _snapshotStore;
+    private readonly TimeProvider _timeProvider;
+    private readonly ILogger<GalaxyHierarchyCache>? _logger;
+    private readonly TaskCompletionSource _firstLoad = new(TaskCreationOptions.RunContinuationsAsynchronously);
+    private readonly SemaphoreSlim _refreshGate = new(1, 1);
+    private GalaxyHierarchyCacheEntry _current = GalaxyHierarchyCacheEntry.Empty;
+    private bool _restoreAttempted;
+
+    /// <summary>Initializes a new instance of the <see cref="GalaxyHierarchyCache"/> class.</summary>
+    /// <param name="repository">Galaxy Repository client for SQL queries.</param>
+    /// <param name="notifier">Galaxy deploy event notifier.</param>
+    /// <param name="timeProvider">Provider for current time; defaults to system time.</param>
+    /// <param name="logger">Optional logger for diagnostic output.</param>
+    /// <param name="snapshotStore">
+    ///     Optional on-disk snapshot store. When supplied, the cache persists each
+    ///     successful refresh and restores the last snapshot on first load.
+    /// </param>
+    public GalaxyHierarchyCache(
+        IGalaxyRepository repository,
+        IGalaxyDeployNotifier notifier,
+        TimeProvider? timeProvider = null,
+        ILogger<GalaxyHierarchyCache>? logger = null,
+        IGalaxyHierarchySnapshotStore? snapshotStore = null)
+    {
+        _repository = repository;
+        _notifier = notifier;
+        _timeProvider = timeProvider ?? TimeProvider.System;
+        _logger = logger;
+        _snapshotStore = snapshotStore;
+    }
+
+    /// <summary>Gets the current Galaxy hierarchy cache entry with projected status.</summary>
+    public GalaxyHierarchyCacheEntry Current
+    {
+        get
+        {
+            GalaxyHierarchyCacheEntry snapshot = Volatile.Read(ref _current);
+            GalaxyCacheStatus projected = ProjectStatus(snapshot);
+            return projected == snapshot.Status
+                ? snapshot
+                : snapshot with { Status = projected };
+        }
+    }
+
+    /// <summary>Refreshes the Galaxy hierarchy cache if the deploy time has advanced.</summary>
+    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
+    /// <returns>Asynchronous task representing the refresh operation.</returns>
+    public async Task RefreshAsync(CancellationToken cancellationToken)
+    {
+        await _refreshGate.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            await RefreshCoreAsync(cancellationToken).ConfigureAwait(false);
+        }
+        finally
+        {
+            _refreshGate.Release();
+        }
+    }
+
+    /// <summary>Waits for the Galaxy hierarchy cache to complete its first load.</summary>
+    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
+    /// <returns>Asynchronous task representing the wait operation.</returns>
+    public Task WaitForFirstLoadAsync(CancellationToken cancellationToken)
+    {
+        return _firstLoad.Task.WaitAsync(cancellationToken);
+    }
+
+    /// <summary>
+    ///     Disposes the refresh gate. As a DI singleton the cache is disposed once at host
+    ///     shutdown, after the refresh <see cref="GalaxyHierarchyRefreshService"/> has stopped,
+    ///     so no in-flight refresh can be holding the gate.
+    /// </summary>
+    public void Dispose()
+    {
+        _refreshGate.Dispose();
+    }
+
+    private async Task RefreshCoreAsync(CancellationToken cancellationToken)
+    {
+        // First refresh only: seed the cache from the on-disk snapshot before
+        // querying SQL, so a cold start with an unreachable Galaxy database can
+        // still serve last-known browse data. Runs under the refresh gate.
+        if (!_restoreAttempted)
+        {
+            _restoreAttempted = true;
+            await TryRestoreFromDiskAsync(cancellationToken).ConfigureAwait(false);
+        }
+
+        GalaxyHierarchyCacheEntry previous = Volatile.Read(ref _current);
+        DateTimeOffset queriedAt = _timeProvider.GetUtcNow();
+
+        try
+        {
+            DateTime? deployRaw = await _repository.GetLastDeployTimeAsync(cancellationToken).ConfigureAwait(false);
+            DateTimeOffset? deployTime = deployRaw.HasValue
+                ? new DateTimeOffset(DateTime.SpecifyKind(deployRaw.Value, DateTimeKind.Utc))
+                : null;
+
+            bool hasPriorData = previous.HasData;
+            bool deployChanged = !hasPriorData || deployTime != previous.LastDeployTime;
+
+            if (!deployChanged)
+            {
+                // No deploy change — skip heavy queries; just bump LastSuccessAt.
+                GalaxyHierarchyCacheEntry refreshed = previous with
+                {
+                    Status = GalaxyCacheStatus.Healthy,
+                    LastQueriedAt = queriedAt,
+                    LastSuccessAt = queriedAt,
+                    LastError = null,
+                };
+                Volatile.Write(ref _current, refreshed);
+                _firstLoad.TrySetResult();
+                return;
+            }
+
+            Task<List<GalaxyHierarchyRow>> hierarchyTask = _repository.GetHierarchyAsync(cancellationToken);
+            Task<List<GalaxyAttributeRow>> attributesTask = _repository.GetAttributesAsync(cancellationToken);
+            await Task.WhenAll(hierarchyTask, attributesTask).ConfigureAwait(false);
+
+            List<GalaxyHierarchyRow> hierarchy = hierarchyTask.Result;
+            List<GalaxyAttributeRow> attributes = attributesTask.Result;
+
+            long nextSequence = previous.Sequence + 1;
+            GalaxyHierarchyCacheEntry next = BuildEntry(
+                status: GalaxyCacheStatus.Healthy,
+                sequence: nextSequence,
+                lastQueriedAt: queriedAt,
+                lastSuccessAt: queriedAt,
+                lastDeployTime: deployTime,
+                lastError: null,
+                hierarchy: hierarchy,
+                attributes: attributes);
+
+            Volatile.Write(ref _current, next);
+            _firstLoad.TrySetResult();
+
+            _notifier.Publish(new GalaxyDeployEventInfo(
+                Sequence: nextSequence,
+                ObservedAt: queriedAt,
+                TimeOfLastDeploy: deployTime,
+                ObjectCount: hierarchy.Count,
+                AttributeCount: attributes.Count));
+
+            await PersistSnapshotAsync(deployTime, queriedAt, hierarchy, attributes, cancellationToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw;
+        }
+        catch (Exception exception)
+        {
+            // Catch every non-cancellation failure — not just SqlException /
+            // InvalidOperationException. A TimeoutException or Win32Exception
+            // from connection establishment, or another DbException subtype,
+            // must still degrade gracefully to Stale/Unavailable and complete
+            // _firstLoad rather than escape and fault the refresh BackgroundService.
+            _logger?.LogWarning(exception, "Galaxy hierarchy cache refresh failed.");
+            GalaxyHierarchyCacheEntry failed = previous with
+            {
+                Status = previous.HasData ? GalaxyCacheStatus.Stale : GalaxyCacheStatus.Unavailable,
+                LastQueriedAt = queriedAt,
+                LastError = exception.Message,
+            };
+            Volatile.Write(ref _current, failed);
+            _firstLoad.TrySetResult();
+        }
+    }
+
+    /// <summary>
+    ///     Materializes a complete <see cref="GalaxyHierarchyCacheEntry"/> from raw
+    ///     hierarchy and attribute rowsets. Shared by the live refresh path and the
+    ///     on-disk restore path so both produce an identical object list and index.
+    /// </summary>
+    private static GalaxyHierarchyCacheEntry BuildEntry(
+        GalaxyCacheStatus status,
+        long sequence,
+        DateTimeOffset? lastQueriedAt,
+        DateTimeOffset? lastSuccessAt,
+        DateTimeOffset? lastDeployTime,
+        string? lastError,
+        IReadOnlyList<GalaxyHierarchyRow> hierarchy,
+        IReadOnlyList<GalaxyAttributeRow> attributes)
+    {
+        IReadOnlyList<GalaxyObject> objects = BuildObjects(hierarchy, attributes);
+        GalaxyHierarchyIndex index = GalaxyHierarchyIndex.Build(objects);
+
+        int areaCount = hierarchy.Count(row => row.IsArea);
+        int historized = attributes.Count(row => row.IsHistorized);
+        int alarms = attributes.Count(row => row.IsAlarm);
+
+        return new GalaxyHierarchyCacheEntry(
+            Status: status,
+            Sequence: sequence,
+            LastQueriedAt: lastQueriedAt,
+            LastSuccessAt: lastSuccessAt,
+            LastDeployTime: lastDeployTime,
+            LastError: lastError,
+            Objects: objects,
+            Index: index,
+            ObjectCount: hierarchy.Count,
+            AreaCount: areaCount,
+            AttributeCount: attributes.Count,
+            HistorizedAttributeCount: historized,
+            AlarmAttributeCount: alarms);
+    }
+
+    /// <summary>
+    ///     Seeds the cache from the on-disk snapshot when no live data has loaded yet.
+    ///     The restored entry is marked <see cref="GalaxyCacheStatus.Stale"/> — it is
+    ///     last-known data, not live. A later refresh that observes the same deploy
+    ///     time promotes it to healthy; one that observes a newer deploy replaces it.
+    /// </summary>
+    private async Task TryRestoreFromDiskAsync(CancellationToken cancellationToken)
+    {
+        if (_snapshotStore is null)
+        {
+            return;
+        }
+
+        if (Volatile.Read(ref _current).HasData)
+        {
+            return;
+        }
+
+        GalaxyHierarchySnapshot? snapshot;
+        try
+        {
+            snapshot = await _snapshotStore.TryLoadAsync(cancellationToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw;
+        }
+        catch (Exception exception)
+        {
+            _logger?.LogWarning(exception, "Failed to restore the Galaxy hierarchy from the on-disk snapshot.");
+            return;
+        }
+
+        if (snapshot is null)
+        {
+            return;
+        }
+
+        long sequence = Volatile.Read(ref _current).Sequence + 1;
+        GalaxyHierarchyCacheEntry restored = BuildEntry(
+            status: GalaxyCacheStatus.Stale,
+            sequence: sequence,
+            lastQueriedAt: snapshot.SavedAt,
+            lastSuccessAt: snapshot.SavedAt,
+            lastDeployTime: snapshot.LastDeployTime,
+            lastError: null,
+            hierarchy: snapshot.Hierarchy,
+            attributes: snapshot.Attributes);
+        Volatile.Write(ref _current, restored);
+
+        // Restored data is a valid completed first load: unblock callers waiting on
+        // the bootstrap gate immediately, rather than making them wait out the full
+        // wait budget for a live query that — when the database is unreachable, the
+        // scenario this restore exists for — may not return for seconds.
+        _firstLoad.TrySetResult();
+
+        _notifier.Publish(new GalaxyDeployEventInfo(
+            Sequence: sequence,
+            ObservedAt: _timeProvider.GetUtcNow(),
+            TimeOfLastDeploy: snapshot.LastDeployTime,
+            ObjectCount: snapshot.Hierarchy.Count,
+            AttributeCount: snapshot.Attributes.Count));
+
+        _logger?.LogInformation(
+            "Restored Galaxy hierarchy from on-disk snapshot saved {SavedAt:o}: {ObjectCount} objects, {AttributeCount} attributes (status Stale until the Galaxy database confirms).",
+            snapshot.SavedAt,
+            snapshot.Hierarchy.Count,
+            snapshot.Attributes.Count);
+    }
+
+    /// <summary>
+    ///     Persists a successful refresh to disk. Persistence failures are logged and
+    ///     swallowed — a cache that cannot write its backup is still fully usable.
+    /// </summary>
+    private async Task PersistSnapshotAsync(
+        DateTimeOffset? deployTime,
+        DateTimeOffset savedAt,
+        IReadOnlyList<GalaxyHierarchyRow> hierarchy,
+        IReadOnlyList<GalaxyAttributeRow> attributes,
+        CancellationToken cancellationToken)
+    {
+        if (_snapshotStore is null)
+        {
+            return;
+        }
+
+        try
+        {
+            await _snapshotStore.SaveAsync(
+                new GalaxyHierarchySnapshot(deployTime, savedAt, hierarchy, attributes),
+                cancellationToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            // The refresh was cancelled (service shutdown) before the write finished.
+            // That is not a persistence failure — do not log it as a warning.
+        }
+        catch (Exception exception)
+        {
+            _logger?.LogWarning(exception, "Failed to persist the Galaxy hierarchy snapshot to disk.");
+        }
+    }
+
+    private static IReadOnlyList<GalaxyObject> BuildObjects(
+        IReadOnlyList<GalaxyHierarchyRow> hierarchy,
+        IReadOnlyList<GalaxyAttributeRow> attributes)
+    {
+        Dictionary<int, List<GalaxyAttributeRow>> attributesByGobjectId = attributes
+            .GroupBy(a => a.GobjectId)
+            .ToDictionary(g => g.Key, g => g.ToList());
+
+        List<GalaxyObject> objects = new(hierarchy.Count);
+        foreach (GalaxyHierarchyRow row in hierarchy)
+        {
+            objects.Add(GalaxyProtoMapper.MapObject(row, attributesByGobjectId));
+        }
+        return objects;
+    }
+
+    private GalaxyCacheStatus ProjectStatus(GalaxyHierarchyCacheEntry snapshot)
+    {
+        if (snapshot.Status is GalaxyCacheStatus.Unknown or GalaxyCacheStatus.Unavailable)
+        {
+            return snapshot.Status;
+        }
+
+        if (snapshot.LastSuccessAt is { } success
+            && _timeProvider.GetUtcNow() - success > StaleThreshold)
+        {
+            return GalaxyCacheStatus.Stale;
+        }
+
+        return snapshot.Status;
+    }
+}
@@ -0,0 +1,56 @@
+using ZB.MOM.WW.GalaxyRepository.Grpc;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     Immutable snapshot of the Galaxy Repository browse data held by
+///     <see cref="GalaxyHierarchyCache"/>. Multiple gRPC clients share the same
+///     materialized object list and precomputed hierarchy index.
+/// </summary>
+/// <param name="Status">The cache freshness state at the time the entry was produced.</param>
+/// <param name="Sequence">Monotonically increasing per process start; bumped on each heavy refresh.</param>
+/// <param name="LastQueriedAt">UTC wall-clock of the most recent refresh attempt.</param>
+/// <param name="LastSuccessAt">UTC wall-clock of the most recent successful refresh.</param>
+/// <param name="LastDeployTime">The <c>galaxy.time_of_last_deploy</c> the data was pulled at.</param>
+/// <param name="LastError">The most recent refresh error message, or <see langword="null"/>.</param>
+/// <param name="Objects">The materialized Galaxy object list.</param>
+/// <param name="Index">Precomputed lookup structures over <paramref name="Objects"/>.</param>
+/// <param name="ObjectCount">Number of objects in the hierarchy.</param>
+/// <param name="AreaCount">Number of area objects in the hierarchy.</param>
+/// <param name="AttributeCount">Number of attributes across all objects.</param>
+/// <param name="HistorizedAttributeCount">Number of historized attributes.</param>
+/// <param name="AlarmAttributeCount">Number of alarm-bearing attributes.</param>
+public sealed record GalaxyHierarchyCacheEntry(
+    GalaxyCacheStatus Status,
+    long Sequence,
+    DateTimeOffset? LastQueriedAt,
+    DateTimeOffset? LastSuccessAt,
+    DateTimeOffset? LastDeployTime,
+    string? LastError,
+    IReadOnlyList<GalaxyObject> Objects,
+    GalaxyHierarchyIndex Index,
+    int ObjectCount,
+    int AreaCount,
+    int AttributeCount,
+    int HistorizedAttributeCount,
+    int AlarmAttributeCount)
+{
+    /// <summary>Gets an empty Galaxy hierarchy cache entry.</summary>
+    public static GalaxyHierarchyCacheEntry Empty { get; } = new(
+        Status: GalaxyCacheStatus.Unknown,
+        Sequence: 0,
+        LastQueriedAt: null,
+        LastSuccessAt: null,
+        LastDeployTime: null,
+        LastError: null,
+        Objects: Array.Empty<GalaxyObject>(),
+        Index: GalaxyHierarchyIndex.Empty,
+        ObjectCount: 0,
+        AreaCount: 0,
+        AttributeCount: 0,
+        HistorizedAttributeCount: 0,
+        AlarmAttributeCount: 0);
+
+    /// <summary>Gets a value indicating whether the cache entry contains usable data.</summary>
+    public bool HasData => Status is GalaxyCacheStatus.Healthy or GalaxyCacheStatus.Stale;
+}
@@ -0,0 +1,206 @@
+using ZB.MOM.WW.GalaxyRepository.Grpc;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     Precomputed lookup structures over a materialized Galaxy object list. Built once per
+///     cache entry so browse/discover handlers can resolve roots/parents by id, tag name, or
+///     contained path in O(1), enumerate direct children, and resolve tag addresses to objects
+///     or attributes without rescanning the full object list.
+/// </summary>
+public sealed class GalaxyHierarchyIndex
+{
+    private GalaxyHierarchyIndex(
+        IReadOnlyList<GalaxyObjectView> objectViews,
+        IReadOnlyDictionary<int, GalaxyObjectView> objectViewsById,
+        IReadOnlyDictionary<string, GalaxyTagLookup> tagsByAddress,
+        IReadOnlyDictionary<int, IReadOnlyList<GalaxyObjectView>> childrenByParent,
+        IReadOnlyDictionary<string, GalaxyObjectView> objectViewsByTagName,
+        IReadOnlyDictionary<string, GalaxyObjectView> objectViewsByContainedPath)
+    {
+        ObjectViews = objectViews;
+        ObjectViewsById = objectViewsById;
+        TagsByAddress = tagsByAddress;
+        ChildrenByParent = childrenByParent;
+        ObjectViewsByTagName = objectViewsByTagName;
+        ObjectViewsByContainedPath = objectViewsByContainedPath;
+    }
+
+    /// <summary>Gets an empty Galaxy hierarchy index.</summary>
+    public static GalaxyHierarchyIndex Empty { get; } = new(
+        Array.Empty<GalaxyObjectView>(),
+        new Dictionary<int, GalaxyObjectView>(),
+        new Dictionary<string, GalaxyTagLookup>(StringComparer.OrdinalIgnoreCase),
+        new Dictionary<int, IReadOnlyList<GalaxyObjectView>>(),
+        new Dictionary<string, GalaxyObjectView>(StringComparer.OrdinalIgnoreCase),
+        new Dictionary<string, GalaxyObjectView>(StringComparer.OrdinalIgnoreCase));
+
+    /// <summary>Gets the object views.</summary>
+    public IReadOnlyList<GalaxyObjectView> ObjectViews { get; }
+
+    /// <summary>Gets the object views indexed by gobject id.</summary>
+    public IReadOnlyDictionary<int, GalaxyObjectView> ObjectViewsById { get; }
+
+    /// <summary>Gets tags indexed by address.</summary>
+    public IReadOnlyDictionary<string, GalaxyTagLookup> TagsByAddress { get; }
+
+    /// <summary>Gets direct children grouped by parent gobject id. Root objects (no parent, or self-parented) live under key 0. Each list is sorted areas-first, then by display name (OrdinalIgnoreCase).</summary>
+    public IReadOnlyDictionary<int, IReadOnlyList<GalaxyObjectView>> ChildrenByParent { get; }
+
+    /// <summary>Gets object views indexed by <see cref="GalaxyObject.TagName"/> (OrdinalIgnoreCase). Lets browse/discover handlers resolve parents/roots by tag name in O(1) instead of scanning <see cref="ObjectViews"/>.</summary>
+    public IReadOnlyDictionary<string, GalaxyObjectView> ObjectViewsByTagName { get; }
+
+    /// <summary>Gets object views indexed by contained path (OrdinalIgnoreCase). Lets browse/discover handlers resolve parents/roots by path in O(1) instead of scanning <see cref="ObjectViews"/>.</summary>
+    public IReadOnlyDictionary<string, GalaxyObjectView> ObjectViewsByContainedPath { get; }
+
+    /// <summary>Builds a Galaxy hierarchy index from the given objects.</summary>
+    /// <param name="objects">The Galaxy objects to index.</param>
+    /// <returns>A new Galaxy hierarchy index.</returns>
+    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);
+        Dictionary<string, GalaxyObjectView> viewsByTagName = new(StringComparer.OrdinalIgnoreCase);
+        Dictionary<string, GalaxyObjectView> viewsByContainedPath = 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));
+                viewsByTagName.TryAdd(obj.TagName, view);
+            }
+
+            if (!string.IsNullOrWhiteSpace(path))
+            {
+                viewsByContainedPath.TryAdd(path, view);
+            }
+
+            foreach (GalaxyAttribute attribute in obj.Attributes)
+            {
+                if (!string.IsNullOrWhiteSpace(attribute.FullTagReference))
+                {
+                    tagsByAddress.TryAdd(attribute.FullTagReference, new GalaxyTagLookup(obj, attribute, path));
+                }
+            }
+        }
+
+        Dictionary<int, List<GalaxyObjectView>> childrenByParent = new();
+        foreach (GalaxyObjectView view in views)
+        {
+            int parentKey = view.Object.ParentGobjectId;
+            // Treat self-parented (corrupt) rows as roots.
+            if (parentKey == view.Object.GobjectId)
+            {
+                parentKey = 0;
+            }
+            // Re-root orphans whose parent object is absent from the set (e.g. a deleted or
+            // never-loaded container area). Otherwise they bucket under a phantom parent id
+            // that is never reached from the root, so they vanish from browse entirely.
+            else if (parentKey != 0 && !objectsById.ContainsKey(parentKey))
+            {
+                parentKey = 0;
+            }
+            if (!childrenByParent.TryGetValue(parentKey, out List<GalaxyObjectView>? bucket))
+            {
+                bucket = [];
+                childrenByParent[parentKey] = bucket;
+            }
+            bucket.Add(view);
+        }
+
+        foreach (List<GalaxyObjectView> bucket in childrenByParent.Values)
+        {
+            bucket.Sort(CompareByAreaThenDisplayName);
+        }
+
+        Dictionary<int, IReadOnlyList<GalaxyObjectView>> readOnlyChildren = new(childrenByParent.Count);
+        foreach (KeyValuePair<int, List<GalaxyObjectView>> kvp in childrenByParent)
+        {
+            readOnlyChildren[kvp.Key] = kvp.Value;
+        }
+
+        return new GalaxyHierarchyIndex(
+            views,
+            viewsById,
+            tagsByAddress,
+            readOnlyChildren,
+            viewsByTagName,
+            viewsByContainedPath);
+    }
+
+    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;
+    }
+
+    private static int CompareByAreaThenDisplayName(GalaxyObjectView left, GalaxyObjectView right)
+    {
+        if (left.Object.IsArea != right.Object.IsArea)
+        {
+            return left.Object.IsArea ? -1 : 1;
+        }
+        return string.Compare(DisplayNameOf(left), DisplayNameOf(right), StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static string DisplayNameOf(GalaxyObjectView view)
+    {
+        GalaxyObject obj = view.Object;
+        if (!string.IsNullOrWhiteSpace(obj.BrowseName))
+        {
+            return obj.BrowseName;
+        }
+        if (!string.IsNullOrWhiteSpace(obj.ContainedName))
+        {
+            return obj.ContainedName;
+        }
+        return obj.TagName;
+    }
+}
@@ -0,0 +1,317 @@
+using System.Collections.Concurrent;
+using System.Runtime.CompilerServices;
+using System.Security.Cryptography;
+using System.Text;
+using Grpc.Core;
+using ZB.MOM.WW.GalaxyRepository.Grpc;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     Projects a <c>DiscoverHierarchy</c> request against an immutable
+///     <see cref="GalaxyHierarchyCacheEntry"/>: applies the root/depth/category/template/glob
+///     filters, pages the result, and memoizes the filtered list per cache-entry instance so
+///     paging is O(pageSize) rather than O(total) per page. Pure and side-effect free.
+/// </summary>
+public static class GalaxyHierarchyProjector
+{
+    /// <summary>
+    ///     Per-cache-entry memo of filtered, ordered <see cref="GalaxyObjectView"/> lists
+    ///     keyed by filter signature. Without it, paging through a large hierarchy
+    ///     re-applies every filter and re-scans the full <see cref="GalaxyHierarchyIndex.ObjectViews"/>
+    ///     collection on every page — O(total) per page, O(total²/pageSize) end-to-end.
+    ///     With it, the first page builds the filtered list and each subsequent page is an
+    ///     O(pageSize) slice. The table is keyed on the immutable cache-entry instance, so
+    ///     when the cache publishes a new entry the stale memo becomes unreachable and is
+    ///     reclaimed with it — no explicit invalidation needed.
+    /// </summary>
+    private static readonly ConditionalWeakTable<GalaxyHierarchyCacheEntry, ConcurrentDictionary<string, IReadOnlyList<GalaxyObjectView>>> FilteredViewCache = new();
+
+    /// <summary>Projects a discovery request against a cache entry and returns all matching objects.</summary>
+    /// <param name="entry">The Galaxy hierarchy cache entry.</param>
+    /// <param name="request">The discovery hierarchy request.</param>
+    /// <param name="browseSubtreeGlobs">Optional glob patterns to filter browse subtrees.</param>
+    public static GalaxyHierarchyQueryResult Project(
+        GalaxyHierarchyCacheEntry entry,
+        DiscoverHierarchyRequest request,
+        IReadOnlyList<string>? browseSubtreeGlobs = null)
+    {
+        return Project(
+            entry,
+            request,
+            browseSubtreeGlobs,
+            offset: 0,
+            pageSize: int.MaxValue);
+    }
+
+    /// <summary>Projects a discovery request with paging against a cache entry and returns a page of matching objects.</summary>
+    /// <param name="entry">The Galaxy hierarchy cache entry.</param>
+    /// <param name="request">The discovery hierarchy request.</param>
+    /// <param name="browseSubtreeGlobs">Optional glob patterns to filter browse subtrees.</param>
+    /// <param name="offset">The zero-based offset into the result set.</param>
+    /// <param name="pageSize">The maximum number of results to return.</param>
+    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.");
+        }
+
+        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."));
+        }
+
+        string filterSignature = ComputeFilterSignature(request, browseSubtreeGlobs);
+        IReadOnlyList<GalaxyObjectView> matchedViews = GetFilteredViews(
+            entry,
+            request,
+            browseSubtreeGlobs,
+            maxDepth,
+            filterSignature);
+
+        bool includeAttributes = IncludeAttributes(request);
+        List<GalaxyObject> page = new(Math.Min(pageSize, Math.Max(0, matchedViews.Count - offset)));
+        int end = (int)Math.Min((long)offset + pageSize, matchedViews.Count);
+        for (int index = offset; index < end; index++)
+        {
+            page.Add(CloneObject(matchedViews[index].Object, includeAttributes));
+        }
+
+        return new GalaxyHierarchyQueryResult(
+            page,
+            matchedViews.Count,
+            filterSignature);
+    }
+
+    private static IReadOnlyList<GalaxyObjectView> GetFilteredViews(
+        GalaxyHierarchyCacheEntry entry,
+        DiscoverHierarchyRequest request,
+        IReadOnlyList<string>? browseSubtreeGlobs,
+        int? maxDepth,
+        string filterSignature)
+    {
+        // ResolveRoot can throw RpcException(NotFound); run it before consulting the
+        // memo so a bad root surfaces consistently regardless of cache state.
+        IReadOnlyList<GalaxyObjectView> views = entry.Index.ObjectViews;
+        GalaxyObjectView? root = ResolveRoot(request, entry.Index);
+
+        ConcurrentDictionary<string, IReadOnlyList<GalaxyObjectView>> memo =
+            FilteredViewCache.GetValue(entry, static _ => new ConcurrentDictionary<string, IReadOnlyList<GalaxyObjectView>>(StringComparer.Ordinal));
+
+        return memo.GetOrAdd(
+            filterSignature,
+            static (_, state) =>
+            {
+                List<GalaxyObjectView> matched = [];
+                foreach (GalaxyObjectView view in state.Views)
+                {
+                    if (MatchesRoot(view, state.Root, state.MaxDepth)
+                        && MatchesBrowseSubtrees(view, state.BrowseSubtreeGlobs)
+                        && MatchesFilters(view.Object, state.Request))
+                    {
+                        matched.Add(view);
+                    }
+                }
+
+                return matched;
+            },
+            (Views: views, Root: root, MaxDepth: maxDepth, BrowseSubtreeGlobs: browseSubtreeGlobs, Request: request));
+    }
+
+    /// <summary>Finds an object in the hierarchy by its tag address.</summary>
+    /// <param name="entry">The Galaxy hierarchy cache entry.</param>
+    /// <param name="tagAddress">The tag address to search for.</param>
+    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;
+    }
+
+    /// <summary>Finds an attribute in the hierarchy by its tag address.</summary>
+    /// <param name="entry">The Galaxy hierarchy cache entry.</param>
+    /// <param name="tagAddress">The tag address to search for.</param>
+    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;
+    }
+
+    /// <summary>Gets the contained path for an object by its gobject ID.</summary>
+    /// <param name="entry">The Galaxy hierarchy cache entry.</param>
+    /// <param name="gobjectId">The Galaxy object ID.</param>
+    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,
+        GalaxyHierarchyIndex index)
+    {
+        GalaxyObjectView? root = request.RootCase switch
+        {
+            DiscoverHierarchyRequest.RootOneofCase.None => null,
+            DiscoverHierarchyRequest.RootOneofCase.RootGobjectId =>
+                index.ObjectViewsById.TryGetValue(request.RootGobjectId, out GalaxyObjectView? byId) ? byId : null,
+            DiscoverHierarchyRequest.RootOneofCase.RootTagName =>
+                index.ObjectViewsByTagName.TryGetValue(request.RootTagName, out GalaxyObjectView? byTag) ? byTag : null,
+            DiscoverHierarchyRequest.RootOneofCase.RootContainedPath =>
+                index.ObjectViewsByContainedPath.TryGetValue(request.RootContainedPath, out GalaxyObjectView? byPath) ? byPath : null,
+            _ => 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;
+    }
+
+    /// <summary>Computes a stable filter signature for memoization purposes.</summary>
+    /// <param name="request">The discovery hierarchy request.</param>
+    /// <param name="browseSubtreeGlobs">Optional glob patterns to filter browse subtrees.</param>
+    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);
+    }
+}
@@ -0,0 +1,16 @@
+using ZB.MOM.WW.GalaxyRepository.Grpc;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     Result of one <see cref="GalaxyHierarchyProjector.Project(GalaxyHierarchyCacheEntry, DiscoverHierarchyRequest, System.Collections.Generic.IReadOnlyList{string}, int, int)"/>
+///     call: a materialized page of matching objects, the total post-filter object count, and
+///     the stable filter signature used to bind page tokens.
+/// </summary>
+/// <param name="Objects">The page of matching objects.</param>
+/// <param name="TotalObjectCount">Total matching objects across the whole hierarchy (post-filter).</param>
+/// <param name="FilterSignature">Stable signature of the filter set, used to bind page tokens.</param>
+public sealed record GalaxyHierarchyQueryResult(
+    IReadOnlyList<GalaxyObject> Objects,
+    int TotalObjectCount,
+    string FilterSignature);
@@ -0,0 +1,62 @@
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>Background service that periodically refreshes the Galaxy Repository hierarchy cache off the request path.</summary>
+public sealed class GalaxyHierarchyRefreshService(
+    IGalaxyHierarchyCache cache,
+    IOptions<GalaxyRepositoryOptions> options,
+    ILogger<GalaxyHierarchyRefreshService> logger,
+    TimeProvider? timeProvider = null) : BackgroundService
+{
+    private readonly TimeProvider _timeProvider = timeProvider ?? TimeProvider.System;
+
+    /// <inheritdoc />
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        TimeSpan interval = TimeSpan.FromSeconds(Math.Max(1, options.Value.DashboardRefreshIntervalSeconds));
+
+        try
+        {
+            await cache.RefreshAsync(stoppingToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+        {
+            return;
+        }
+        catch (Exception exception)
+        {
+            // A transient first-load failure (e.g. a TimeoutException or
+            // Win32Exception from connection establishment, or a DbException
+            // subtype the cache does not catch) must not fault this
+            // BackgroundService and stop the whole host. The cache records
+            // its own Unavailable/Stale status; the periodic tick below retries.
+            logger.LogWarning(exception, "Initial Galaxy hierarchy cache load failed; will retry on the refresh interval.");
+        }
+
+        using PeriodicTimer timer = new(interval, _timeProvider);
+        try
+        {
+            while (await timer.WaitForNextTickAsync(stoppingToken).ConfigureAwait(false))
+            {
+                try
+                {
+                    await cache.RefreshAsync(stoppingToken).ConfigureAwait(false);
+                }
+                catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+                {
+                    return;
+                }
+                catch (Exception exception)
+                {
+                    logger.LogWarning(exception, "Galaxy hierarchy cache refresh tick failed.");
+                }
+            }
+        }
+        catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+        {
+        }
+    }
+}
@@ -0,0 +1,35 @@
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     One row from <see cref="GalaxyRepository.GetHierarchyAsync"/>: a deployed Galaxy
+///     <c>gobject</c> with its hierarchy parent and template-derivation chain.
+/// </summary>
+public sealed class GalaxyHierarchyRow
+{
+    /// <summary>Gets the Galaxy object identifier.</summary>
+    public int GobjectId { get; init; }
+
+    /// <summary>Gets the tag name.</summary>
+    public string TagName { get; init; } = string.Empty;
+
+    /// <summary>Gets the contained name.</summary>
+    public string ContainedName { get; init; } = string.Empty;
+
+    /// <summary>Gets the browse name.</summary>
+    public string BrowseName { get; init; } = string.Empty;
+
+    /// <summary>Gets the parent Galaxy object identifier.</summary>
+    public int ParentGobjectId { get; init; }
+
+    /// <summary>Gets a value indicating whether this is an area.</summary>
+    public bool IsArea { get; init; }
+
+    /// <summary>Gets the category identifier.</summary>
+    public int CategoryId { get; init; }
+
+    /// <summary>Gets the Galaxy object identifier of the host.</summary>
+    public int HostedByGobjectId { get; init; }
+
+    /// <summary>Gets the template derivation chain.</summary>
+    public IReadOnlyList<string> TemplateChain { get; init; } = Array.Empty<string>();
+}
@@ -0,0 +1,24 @@
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     A serializable point-in-time copy of the Galaxy Repository browse data.
+///     Holds the raw hierarchy and attribute rowsets — not the materialized
+///     protobuf objects — so the restore path runs the exact same
+///     materialization as a live refresh. Persisted by
+///     <see cref="IGalaxyHierarchySnapshotStore"/> after a successful refresh
+///     and reloaded at startup when the Galaxy database is unreachable.
+/// </summary>
+/// <param name="LastDeployTime">
+///     The <c>galaxy.time_of_last_deploy</c> the rowsets were pulled at, or
+///     <see langword="null"/> when the Galaxy table reported no deploy. A later
+///     live refresh that observes this same timestamp can promote the restored
+///     entry to healthy without re-running the heavy queries.
+/// </param>
+/// <param name="SavedAt">UTC wall-clock when the snapshot was written to disk.</param>
+/// <param name="Hierarchy">The persisted object-hierarchy rowset.</param>
+/// <param name="Attributes">The persisted attribute rowset.</param>
+public sealed record GalaxyHierarchySnapshot(
+    DateTimeOffset? LastDeployTime,
+    DateTimeOffset SavedAt,
+    IReadOnlyList<GalaxyHierarchyRow> Hierarchy,
+    IReadOnlyList<GalaxyAttributeRow> Attributes);
@@ -0,0 +1,152 @@
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     JSON-file implementation of <see cref="IGalaxyHierarchySnapshotStore"/>.
+///     Writes the on-disk snapshot atomically (temp file + rename) so a crash
+///     mid-write can never leave a torn file, and ignores files whose schema
+///     version it does not recognize. When
+///     <see cref="GalaxyRepositoryOptions.PersistSnapshot"/> is <see langword="false"/>
+///     — or <see cref="GalaxyRepositoryOptions.SnapshotCachePath"/> is empty —
+///     both operations are no-ops. The snapshot path is fully consumer-supplied;
+///     this store imposes no platform-specific default, so it is cross-platform.
+/// </summary>
+public sealed class GalaxyHierarchySnapshotStore : IGalaxyHierarchySnapshotStore, IDisposable
+{
+    /// <summary>
+    ///     On-disk format version. Bump this whenever the persisted shape changes
+    ///     in a way an older or newer consumer cannot read; a mismatched file is
+    ///     ignored rather than misparsed.
+    /// </summary>
+    private const int CurrentSchemaVersion = 1;
+
+    private static readonly JsonSerializerOptions SerializerOptions = new()
+    {
+        WriteIndented = false,
+    };
+
+    private readonly string? _path;
+    private readonly TimeSpan _writeTimeout;
+    private readonly ILogger<GalaxyHierarchySnapshotStore>? _logger;
+    private readonly SemaphoreSlim _ioGate = new(1, 1);
+
+    /// <summary>Initializes a new instance of the <see cref="GalaxyHierarchySnapshotStore"/> class.</summary>
+    /// <param name="options">Galaxy repository options carrying the snapshot path and enable flag.</param>
+    /// <param name="logger">Optional logger for diagnostic output.</param>
+    public GalaxyHierarchySnapshotStore(
+        IOptions<GalaxyRepositoryOptions> options,
+        ILogger<GalaxyHierarchySnapshotStore>? logger = null)
+    {
+        GalaxyRepositoryOptions value = options.Value;
+        _path = value.PersistSnapshot && !string.IsNullOrWhiteSpace(value.SnapshotCachePath)
+            ? value.SnapshotCachePath
+            : null;
+        _writeTimeout = TimeSpan.FromSeconds(Math.Max(1, value.CommandTimeoutSeconds));
+        _logger = logger;
+    }
+
+    /// <inheritdoc />
+    public async Task SaveAsync(GalaxyHierarchySnapshot snapshot, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(snapshot);
+        if (_path is null)
+        {
+            return;
+        }
+
+        PersistedFile file = new(CurrentSchemaVersion, snapshot);
+
+        await _ioGate.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            // Bound the write so a stuck disk — e.g. a SnapshotCachePath on an
+            // unresponsive network share — cannot stall the caller. On the cache
+            // refresh path that would otherwise pin the whole refresh loop.
+            using CancellationTokenSource writeCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+            writeCts.CancelAfter(_writeTimeout);
+
+            string? directory = Path.GetDirectoryName(_path);
+            if (!string.IsNullOrEmpty(directory))
+            {
+                Directory.CreateDirectory(directory);
+            }
+
+            string tempPath = _path + ".tmp";
+            await using (FileStream stream = new(tempPath, FileMode.Create, FileAccess.Write, FileShare.None))
+            {
+                await JsonSerializer.SerializeAsync(stream, file, SerializerOptions, writeCts.Token).ConfigureAwait(false);
+            }
+
+            File.Move(tempPath, _path, overwrite: true);
+            _logger?.LogDebug(
+                "Persisted Galaxy hierarchy snapshot to {Path} ({ObjectCount} objects, {AttributeCount} attributes).",
+                _path,
+                snapshot.Hierarchy.Count,
+                snapshot.Attributes.Count);
+        }
+        finally
+        {
+            _ioGate.Release();
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task<GalaxyHierarchySnapshot?> TryLoadAsync(CancellationToken cancellationToken)
+    {
+        if (_path is null || !File.Exists(_path))
+        {
+            return null;
+        }
+
+        await _ioGate.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            PersistedFile? file;
+            await using (FileStream stream = new(_path, FileMode.Open, FileAccess.Read, FileShare.Read))
+            {
+                file = await JsonSerializer.DeserializeAsync<PersistedFile>(
+                    stream, SerializerOptions, cancellationToken).ConfigureAwait(false);
+            }
+
+            if (file is null || file.SchemaVersion != CurrentSchemaVersion || file.Snapshot is null)
+            {
+                _logger?.LogWarning(
+                    "Ignoring Galaxy hierarchy snapshot at {Path}: unrecognized or empty schema version.",
+                    _path);
+                return null;
+            }
+
+            return file.Snapshot;
+        }
+        catch (Exception exception) when (exception is JsonException or IOException or UnauthorizedAccessException)
+        {
+            // A corrupt, truncated, locked, or access-denied snapshot file is an
+            // expected failure mode for a disk cache — honor the Try contract and
+            // return null rather than throwing.
+            _logger?.LogWarning(
+                exception,
+                "Ignoring Galaxy hierarchy snapshot at {Path}: the file is unreadable or not valid JSON.",
+                _path);
+            return null;
+        }
+        finally
+        {
+            _ioGate.Release();
+        }
+    }
+
+    /// <summary>
+    ///     Disposes the I/O gate. As a DI singleton the store is disposed once at host
+    ///     shutdown, by which point no save/load is in flight.
+    /// </summary>
+    public void Dispose()
+    {
+        _ioGate.Dispose();
+    }
+
+    /// <summary>On-disk envelope: a schema version plus the snapshot payload.</summary>
+    private sealed record PersistedFile(int SchemaVersion, GalaxyHierarchySnapshot? Snapshot);
+}
@@ -0,0 +1,16 @@
+using ZB.MOM.WW.GalaxyRepository.Grpc;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     A <see cref="GalaxyObject"/> paired with its computed contained path and hierarchy
+///     depth. Materialized once per cache entry by <see cref="GalaxyHierarchyIndex"/> so
+///     browse/discover projection can filter and page without recomputing paths.
+/// </summary>
+/// <param name="Object">The projected Galaxy object.</param>
+/// <param name="ContainedPath">The slash-delimited contained path from the hierarchy root.</param>
+/// <param name="Depth">The number of path segments from the root (zero for top-level objects).</param>
+public sealed record GalaxyObjectView(
+    GalaxyObject Object,
+    string ContainedPath,
+    int Depth);
@@ -0,0 +1,76 @@
+using ZB.MOM.WW.GalaxyRepository.Grpc;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     Maps <see cref="GalaxyHierarchyRow"/> + <see cref="GalaxyAttributeRow"/> rows produced
+///     by <see cref="GalaxyRepository"/> into <c>galaxy_repository.v1</c> proto messages.
+///     Pure function, separated so it can be unit-tested without a SQL connection.
+/// </summary>
+public static class GalaxyProtoMapper
+{
+    /// <summary>Maps Galaxy hierarchy and attribute rows to Galaxy object protos.</summary>
+    /// <param name="hierarchy">Hierarchy rows from Galaxy Repository.</param>
+    /// <param name="attributes">Attribute rows from Galaxy Repository.</param>
+    public static IEnumerable<GalaxyObject> MapHierarchy(
+        IReadOnlyList<GalaxyHierarchyRow> hierarchy,
+        IReadOnlyList<GalaxyAttributeRow> attributes)
+    {
+        Dictionary<int, List<GalaxyAttributeRow>> attributesByGobjectId = attributes
+            .GroupBy(a => a.GobjectId)
+            .ToDictionary(g => g.Key, g => g.ToList());
+
+        foreach (GalaxyHierarchyRow row in hierarchy)
+        {
+            yield return MapObject(row, attributesByGobjectId);
+        }
+    }
+
+    /// <summary>Maps a Galaxy hierarchy row to a Galaxy object proto.</summary>
+    /// <param name="row">Hierarchy row from Galaxy Repository.</param>
+    /// <param name="attributesByGobjectId">Attributes indexed by gobject ID.</param>
+    public static GalaxyObject MapObject(
+        GalaxyHierarchyRow row,
+        IReadOnlyDictionary<int, List<GalaxyAttributeRow>> attributesByGobjectId)
+    {
+        GalaxyObject obj = new()
+        {
+            GobjectId = row.GobjectId,
+            TagName = row.TagName,
+            ContainedName = row.ContainedName,
+            BrowseName = row.BrowseName,
+            ParentGobjectId = row.ParentGobjectId,
+            IsArea = row.IsArea,
+            CategoryId = row.CategoryId,
+            HostedByGobjectId = row.HostedByGobjectId,
+        };
+        obj.TemplateChain.AddRange(row.TemplateChain);
+
+        if (attributesByGobjectId.TryGetValue(row.GobjectId, out List<GalaxyAttributeRow>? attrs))
+        {
+            foreach (GalaxyAttributeRow attr in attrs)
+            {
+                obj.Attributes.Add(MapAttribute(attr));
+            }
+        }
+
+        return obj;
+    }
+
+    /// <summary>Maps a Galaxy attribute row to a Galaxy attribute proto.</summary>
+    /// <param name="row">Attribute row from Galaxy Repository.</param>
+    public static GalaxyAttribute MapAttribute(GalaxyAttributeRow row) => new()
+    {
+        AttributeName = row.AttributeName,
+        FullTagReference = row.FullTagReference,
+        MxDataType = row.MxDataType,
+        DataTypeName = row.DataTypeName ?? string.Empty,
+        IsArray = row.IsArray,
+        ArrayDimension = row.ArrayDimension ?? 0,
+        ArrayDimensionPresent = row.ArrayDimension.HasValue,
+        MxAttributeCategory = row.MxAttributeCategory,
+        SecurityClassification = row.SecurityClassification,
+        IsHistorized = row.IsHistorized,
+        IsAlarm = row.IsAlarm,
+    };
+}
@@ -0,0 +1,356 @@
+using Microsoft.Data.SqlClient;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     SQL access to the AVEVA System Platform Galaxy Repository database.
+///     <para>
+///     <see cref="HierarchySql" /> is the query originally ported from the OtOpcUa
+///     project. <see cref="AttributesSql" /> has diverged: it additionally enumerates the
+///     built-in attributes contributed by each object's primitives (from
+///     <c>attribute_definition</c> via <c>primitive_instance</c>), so engine/platform objects
+///     and extension sub-attributes (e.g. <c>TestAlarm001.Acked</c>) are surfaced. The
+///     OtOpcUa query is not kept in sync.
+///     </para>
+/// </summary>
+public sealed class GalaxyRepository(GalaxyRepositoryOptions options) : IGalaxyRepository
+{
+    /// <summary>Tests the connection to the Galaxy Repository database.</summary>
+    /// <param name="ct">Token to cancel the asynchronous operation.</param>
+    public async Task<bool> TestConnectionAsync(CancellationToken ct = default)
+    {
+        try
+        {
+            using SqlConnection conn = new(options.ConnectionString);
+            await conn.OpenAsync(ct).ConfigureAwait(false);
+            using SqlCommand cmd = new("SELECT 1", conn) { CommandTimeout = options.CommandTimeoutSeconds };
+            object? result = await cmd.ExecuteScalarAsync(ct).ConfigureAwait(false);
+            return result is int i && i == 1;
+        }
+        catch (SqlException) { return false; }
+        catch (InvalidOperationException) { return false; }
+    }
+
+    /// <summary>Retrieves the last deployment time from the Galaxy Repository.</summary>
+    /// <param name="ct">Token to cancel the asynchronous operation.</param>
+    public async Task<DateTime?> GetLastDeployTimeAsync(CancellationToken ct = default)
+    {
+        using SqlConnection conn = new(options.ConnectionString);
+        await conn.OpenAsync(ct).ConfigureAwait(false);
+        using SqlCommand cmd = new("SELECT time_of_last_deploy FROM galaxy", conn)
+        { CommandTimeout = options.CommandTimeoutSeconds };
+        object? result = await cmd.ExecuteScalarAsync(ct).ConfigureAwait(false);
+        return result is DateTime dt ? dt : null;
+    }
+
+    /// <summary>Retrieves the complete hierarchy of Galaxy objects from the repository.</summary>
+    /// <param name="ct">Token to cancel the asynchronous operation.</param>
+    public async Task<List<GalaxyHierarchyRow>> GetHierarchyAsync(CancellationToken ct = default)
+    {
+        List<GalaxyHierarchyRow> rows = new();
+
+        using SqlConnection conn = new(options.ConnectionString);
+        await conn.OpenAsync(ct).ConfigureAwait(false);
+
+        using SqlCommand cmd = new(HierarchySql, conn) { CommandTimeout = options.CommandTimeoutSeconds };
+        using SqlDataReader reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
+
+        while (await reader.ReadAsync(ct).ConfigureAwait(false))
+        {
+            string templateChainRaw = reader.IsDBNull(8) ? string.Empty : reader.GetString(8);
+            string[] templateChain = templateChainRaw.Length == 0
+                ? Array.Empty<string>()
+                : templateChainRaw.Split(['|'], StringSplitOptions.RemoveEmptyEntries)
+                    .Select(s => s.Trim())
+                    .Where(s => s.Length > 0)
+                    .ToArray();
+
+            rows.Add(new GalaxyHierarchyRow
+            {
+                GobjectId = Convert.ToInt32(reader.GetValue(0)),
+                TagName = reader.GetString(1),
+                ContainedName = reader.IsDBNull(2) ? string.Empty : reader.GetString(2),
+                BrowseName = reader.GetString(3),
+                ParentGobjectId = Convert.ToInt32(reader.GetValue(4)),
+                IsArea = Convert.ToInt32(reader.GetValue(5)) == 1,
+                CategoryId = Convert.ToInt32(reader.GetValue(6)),
+                HostedByGobjectId = Convert.ToInt32(reader.GetValue(7)),
+                TemplateChain = templateChain,
+            });
+        }
+        return rows;
+    }
+
+    /// <summary>Retrieves all attributes for Galaxy objects from the repository.</summary>
+    /// <param name="ct">Token to cancel the asynchronous operation.</param>
+    public async Task<List<GalaxyAttributeRow>> GetAttributesAsync(CancellationToken ct = default)
+    {
+        List<GalaxyAttributeRow> rows = new();
+
+        using SqlConnection conn = new(options.ConnectionString);
+        await conn.OpenAsync(ct).ConfigureAwait(false);
+
+        using SqlCommand cmd = new(AttributesSql, conn) { CommandTimeout = options.CommandTimeoutSeconds };
+        using SqlDataReader reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
+
+        while (await reader.ReadAsync(ct).ConfigureAwait(false))
+        {
+            rows.Add(new GalaxyAttributeRow
+            {
+                GobjectId = Convert.ToInt32(reader.GetValue(0)),
+                TagName = reader.GetString(1),
+                AttributeName = reader.GetString(2),
+                FullTagReference = reader.GetString(3),
+                MxDataType = Convert.ToInt32(reader.GetValue(4)),
+                DataTypeName = reader.IsDBNull(5) ? null : reader.GetString(5),
+                IsArray = Convert.ToInt32(reader.GetValue(6)) == 1,
+                ArrayDimension = reader.IsDBNull(7) ? null : Convert.ToInt32(reader.GetValue(7)),
+                MxAttributeCategory = Convert.ToInt32(reader.GetValue(8)),
+                SecurityClassification = Convert.ToInt32(reader.GetValue(9)),
+                IsHistorized = Convert.ToInt32(reader.GetValue(10)) == 1,
+                IsAlarm = Convert.ToInt32(reader.GetValue(11)) == 1,
+            });
+        }
+        return rows;
+    }
+
+    /// <inheritdoc />
+    public async Task<List<GalaxyAlarmAttributeRow>> GetAlarmAttributesAsync(CancellationToken ct = default)
+    {
+        List<GalaxyAlarmAttributeRow> rows = new();
+
+        using SqlConnection conn = new(options.ConnectionString);
+        await conn.OpenAsync(ct).ConfigureAwait(false);
+
+        using SqlCommand cmd = new(AlarmAttributesSql, conn) { CommandTimeout = options.CommandTimeoutSeconds };
+        using SqlDataReader reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
+
+        while (await reader.ReadAsync(ct).ConfigureAwait(false))
+        {
+            rows.Add(MapAlarmRow(reader.GetString(0), reader.GetString(1), reader.GetString(2)));
+        }
+        return rows;
+    }
+
+    /// <summary>
+    ///     Maps the SQL columns projected by <c>AlarmAttributesSql</c> onto a
+    ///     <see cref="GalaxyAlarmAttributeRow"/>.
+    ///     <para>
+    ///     <paramref name="fullTagReference"/> is the alarm-bearing attribute reference (e.g.
+    ///     <c>Tank01.Level.HiHi</c>), matching the same <c>full_tag_reference</c> projection
+    ///     of <see cref="AttributesSql"/> produces.
+    ///     <see cref="GalaxyAlarmAttributeRow.AckCommentSubtag"/> is left empty here; the
+    ///     schema does not expose an ack-comment address and the watch-list resolver
+    ///     composes it later.
+    ///     </para>
+    ///     <paramref name="area"/> is the owning object's real Galaxy area (its alarm
+    ///     group), resolved via <c>gobject.area_gobject_id</c>; the watch-list resolver
+    ///     composes the canonical reference from it so the synthesized reference's group
+    ///     matches what the native alarmmgr (wnwrap) emits.
+    ///     Exposed internally so the derivation can be unit-tested without a database.
+    /// </summary>
+    /// <param name="fullTagReference">The alarm-bearing attribute reference.</param>
+    /// <param name="sourceObjectReference">The owning object reference (tag name).</param>
+    /// <param name="area">The owning object's Galaxy area (the alarm group).</param>
+    internal static GalaxyAlarmAttributeRow MapAlarmRow(
+        string fullTagReference,
+        string sourceObjectReference,
+        string area) => new()
+        {
+            FullTagReference = fullTagReference,
+            SourceObjectReference = sourceObjectReference,
+            Area = area,
+            AckCommentSubtag = string.Empty,
+        };
+
+    // Area objects (category 13) are returned even when undeployed (deployed_package_id = 0):
+    // they are organizational/model nodes that group deployed objects, so excluding them
+    // orphans every area whose containing area is not itself deployed. All non-area objects
+    // still require deployment. Orphans left by a missing/deleted parent area are re-rooted
+    // by GalaxyHierarchyIndex.Build so nothing disappears from browse.
+    private const string HierarchySql = @"
+;WITH template_chain AS (
+    SELECT g.gobject_id AS instance_gobject_id, t.gobject_id AS template_gobject_id,
+           t.tag_name AS template_tag_name, t.derived_from_gobject_id, 0 AS depth
+    FROM gobject g
+    INNER JOIN gobject t ON t.gobject_id = g.derived_from_gobject_id
+    WHERE g.is_template = 0 AND g.deployed_package_id <> 0 AND g.derived_from_gobject_id <> 0
+    UNION ALL
+    SELECT tc.instance_gobject_id, t.gobject_id, t.tag_name, t.derived_from_gobject_id, tc.depth + 1
+    FROM template_chain tc
+    INNER JOIN gobject t ON t.gobject_id = tc.derived_from_gobject_id
+    WHERE tc.derived_from_gobject_id <> 0 AND tc.depth < 10
+)
+SELECT DISTINCT
+    g.gobject_id,
+    g.tag_name,
+    g.contained_name,
+    CASE WHEN g.contained_name IS NULL OR g.contained_name = ''
+         THEN g.tag_name
+         ELSE g.contained_name
+    END AS browse_name,
+    CASE WHEN g.contained_by_gobject_id = 0
+         THEN g.area_gobject_id
+         ELSE g.contained_by_gobject_id
+    END AS parent_gobject_id,
+    CASE WHEN td.category_id = 13
+         THEN 1
+         ELSE 0
+    END AS is_area,
+    td.category_id AS category_id,
+    g.hosted_by_gobject_id AS hosted_by_gobject_id,
+    ISNULL(
+        STUFF((
+            SELECT '|' + tc.template_tag_name
+            FROM template_chain tc
+            WHERE tc.instance_gobject_id = g.gobject_id
+            ORDER BY tc.depth
+            FOR XML PATH('')
+        ), 1, 1, ''),
+        ''
+    ) AS template_chain
+FROM gobject g
+INNER JOIN template_definition td
+    ON g.template_definition_id = td.template_definition_id
+WHERE td.category_id IN (1, 3, 4, 10, 11, 13, 17, 24, 26)
+    AND g.is_template = 0
+    AND (g.deployed_package_id <> 0 OR td.category_id = 13)
+ORDER BY parent_gobject_id, g.tag_name";
+
+    // Unlike HierarchySql, this query has diverged from the OtOpcUa original. It returns two
+    // kinds of attribute: user-configured dynamic attributes (the original `dynamic_attribute`
+    // body, src_pri 0) and the built-in attributes every object inherits from its primitives
+    // (`attribute_definition` joined through `primitive_instance`, src_pri 1). Built-in
+    // attributes are why engine/platform objects and extension sub-attributes such as
+    // `TestAlarm001.Acked` show up at all. Built-in rows carry no category filter (the
+    // `attribute_definition` category numbering differs from `dynamic_attribute`'s — only the
+    // `_`-prefix and `.Description` name exclusions apply) and are never flagged
+    // `is_historized`/`is_alarm`: those flags describe a user attribute that anchors an
+    // extension, not the extension's machinery leaves.
+    private const string AttributesSql = @"
+;WITH deployed_package_chain AS (
+    SELECT g.gobject_id, p.package_id, p.derived_from_package_id, 0 AS depth
+    FROM gobject g
+    INNER JOIN package p ON p.package_id = g.deployed_package_id
+    WHERE g.is_template = 0 AND g.deployed_package_id <> 0
+    UNION ALL
+    SELECT dpc.gobject_id, p.package_id, p.derived_from_package_id, dpc.depth + 1
+    FROM deployed_package_chain dpc
+    INNER JOIN package p ON p.package_id = dpc.derived_from_package_id
+    WHERE dpc.derived_from_package_id <> 0 AND dpc.depth < 10
+),
+candidate AS (
+    SELECT
+        dpc.gobject_id, g.tag_name, da.attribute_name, da.mx_data_type, da.is_array,
+        CASE WHEN da.is_array = 1
+             THEN CONVERT(int, CONVERT(varbinary(2),
+                  SUBSTRING(da.mx_value, 15, 2) + SUBSTRING(da.mx_value, 13, 2), 2))
+             ELSE NULL END AS array_dimension,
+        da.mx_attribute_category, da.security_classification, dpc.depth, 0 AS src_pri
+    FROM deployed_package_chain dpc
+    INNER JOIN dynamic_attribute da ON da.package_id = dpc.package_id
+    INNER JOIN gobject g ON g.gobject_id = dpc.gobject_id
+    INNER JOIN template_definition td ON td.template_definition_id = g.template_definition_id
+    WHERE td.category_id IN (1, 3, 4, 10, 11, 13, 17, 24, 26)
+        AND da.attribute_name NOT LIKE '[_]%'
+        AND da.attribute_name NOT LIKE '%.Description'
+        AND da.mx_attribute_category IN (2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 24)
+    UNION ALL
+    SELECT
+        dpc.gobject_id, g.tag_name,
+        CASE WHEN pi.primitive_name IS NULL OR pi.primitive_name = ''
+             THEN ad.attribute_name
+             ELSE pi.primitive_name + '.' + ad.attribute_name END AS attribute_name,
+        ad.mx_data_type, ad.is_array,
+        CASE WHEN ad.is_array = 1
+             THEN CONVERT(int, CONVERT(varbinary(2),
+                  SUBSTRING(ad.mx_value, 15, 2) + SUBSTRING(ad.mx_value, 13, 2), 2))
+             ELSE NULL END AS array_dimension,
+        ad.mx_attribute_category, ad.security_classification, dpc.depth, 1 AS src_pri
+    FROM deployed_package_chain dpc
+    INNER JOIN primitive_instance pi ON pi.package_id = dpc.package_id
+    INNER JOIN attribute_definition ad ON ad.primitive_definition_id = pi.primitive_definition_id
+    INNER JOIN gobject g ON g.gobject_id = dpc.gobject_id
+    INNER JOIN template_definition td ON td.template_definition_id = g.template_definition_id
+    WHERE td.category_id IN (1, 3, 4, 10, 11, 13, 17, 24, 26)
+        AND ad.attribute_name NOT LIKE '[_]%'
+        AND ad.attribute_name NOT LIKE '%.Description'
+),
+ranked AS (
+    SELECT c.*, ROW_NUMBER() OVER (
+        PARTITION BY c.gobject_id, c.attribute_name ORDER BY c.src_pri, c.depth) AS rn
+    FROM candidate c
+)
+SELECT
+    r.gobject_id, r.tag_name, r.attribute_name,
+    r.tag_name + '.' + r.attribute_name
+        + CASE WHEN r.is_array = 1 THEN '[]' ELSE '' END AS full_tag_reference,
+    r.mx_data_type, dt.description AS data_type_name, r.is_array, r.array_dimension,
+    r.mx_attribute_category, r.security_classification,
+    CASE WHEN r.src_pri = 0 AND EXISTS (
+        SELECT 1 FROM deployed_package_chain dpc2
+        INNER JOIN primitive_instance pi ON pi.package_id = dpc2.package_id AND pi.primitive_name = r.attribute_name
+        INNER JOIN primitive_definition pd ON pd.primitive_definition_id = pi.primitive_definition_id AND pd.primitive_name = 'HistoryExtension'
+        WHERE dpc2.gobject_id = r.gobject_id
+    ) THEN 1 ELSE 0 END AS is_historized,
+    CASE WHEN r.src_pri = 0 AND EXISTS (
+        SELECT 1 FROM deployed_package_chain dpc2
+        INNER JOIN primitive_instance pi ON pi.package_id = dpc2.package_id AND pi.primitive_name = r.attribute_name
+        INNER JOIN primitive_definition pd ON pd.primitive_definition_id = pi.primitive_definition_id AND pd.primitive_name = 'AlarmExtension'
+        WHERE dpc2.gobject_id = r.gobject_id
+    ) THEN 1 ELSE 0 END AS is_alarm
+FROM ranked r
+LEFT JOIN data_type dt ON dt.mx_data_type = r.mx_data_type
+WHERE r.rn = 1
+ORDER BY r.tag_name, r.attribute_name";
+
+    // Returns one row per alarm-bearing attribute across all deployed objects. The three
+    // projected columns (full_tag_reference, source_object_reference, area_name) are mapped
+    // by MapAlarmRow. Only attributes whose owning object has an AlarmExtension primitive
+    // instance matching the attribute name are returned, which is why the EXISTS correlated
+    // sub-query against deployed_package_chain is needed rather than relying solely on
+    // dynamic_attribute.mx_attribute_category.
+    private const string AlarmAttributesSql = @"
+;WITH deployed_package_chain AS (
+    SELECT g.gobject_id, p.package_id, p.derived_from_package_id, 0 AS depth
+    FROM gobject g
+    INNER JOIN package p ON p.package_id = g.deployed_package_id
+    WHERE g.is_template = 0 AND g.deployed_package_id <> 0
+    UNION ALL
+    SELECT dpc.gobject_id, p.package_id, p.derived_from_package_id, dpc.depth + 1
+    FROM deployed_package_chain dpc
+    INNER JOIN package p ON p.package_id = dpc.derived_from_package_id
+    WHERE dpc.derived_from_package_id <> 0 AND dpc.depth < 10
+),
+candidate AS (
+    SELECT dpc.gobject_id, g.tag_name, da.attribute_name, dpc.depth
+    FROM deployed_package_chain dpc
+    INNER JOIN dynamic_attribute da ON da.package_id = dpc.package_id
+    INNER JOIN gobject g ON g.gobject_id = dpc.gobject_id
+    INNER JOIN template_definition td ON td.template_definition_id = g.template_definition_id
+    WHERE td.category_id IN (1, 3, 4, 10, 11, 13, 17, 24, 26)
+        AND da.attribute_name NOT LIKE '[_]%'
+        AND da.attribute_name NOT LIKE '%.Description'
+        AND da.mx_attribute_category IN (2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 24)
+),
+ranked AS (
+    SELECT c.*, ROW_NUMBER() OVER (
+        PARTITION BY c.gobject_id, c.attribute_name ORDER BY c.depth) AS rn
+    FROM candidate c
+)
+SELECT
+    r.tag_name + '.' + r.attribute_name AS full_tag_reference,
+    r.tag_name AS source_object_reference,
+    ISNULL(area.tag_name, '') AS area_name
+FROM ranked r
+INNER JOIN gobject g ON g.gobject_id = r.gobject_id
+LEFT JOIN gobject area ON area.gobject_id = g.area_gobject_id
+WHERE r.rn = 1
+    AND EXISTS (
+        SELECT 1 FROM deployed_package_chain dpc2
+        INNER JOIN primitive_instance pi ON pi.package_id = dpc2.package_id AND pi.primitive_name = r.attribute_name
+        INNER JOIN primitive_definition pd ON pd.primitive_definition_id = pi.primitive_definition_id AND pd.primitive_name = 'AlarmExtension'
+        WHERE dpc2.gobject_id = r.gobject_id
+    )
+ORDER BY r.tag_name, r.attribute_name";
+}
@@ -0,0 +1,55 @@
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     Connection settings for the AVEVA System Platform Galaxy Repository database.
+///     <para>
+///     <see cref="SectionName"/> is a generic default; the DI extension accepts an explicit
+///     configuration section path so a consumer can bind from its own section (e.g.
+///     <c>HistorianGateway:Galaxy</c>).
+///     </para>
+/// </summary>
+public sealed class GalaxyRepositoryOptions
+{
+    /// <summary>
+    ///     Generic default configuration section name. The DI extension accepts an explicit
+    ///     section path, so a consumer may bind from a different section (e.g.
+    ///     <c>HistorianGateway:Galaxy</c>).
+    /// </summary>
+    public const string SectionName = "GalaxyRepository";
+
+    /// <summary>
+    ///     Default SQL Server connection string for the Galaxy Repository database.
+    ///     Single source of truth shared with the integration-test fallback so the
+    ///     production default and the live-test default cannot drift.
+    /// </summary>
+    public const string DefaultConnectionString =
+        "Server=localhost;Database=ZB;Integrated Security=True;TrustServerCertificate=True;Encrypt=False;";
+
+    /// <summary>The SQL Server connection string for the Galaxy Repository database.</summary>
+    public string ConnectionString { get; init; } = DefaultConnectionString;
+
+    /// <summary>The timeout in seconds for SQL commands executed against the Galaxy Repository.</summary>
+    public int CommandTimeoutSeconds { get; init; } = 60;
+
+    /// <summary>
+    ///     Interval (seconds) between background refreshes of the dashboard Galaxy summary
+    ///     cache. SQL is hit at most once per interval regardless of dashboard render rate.
+    /// </summary>
+    public int DashboardRefreshIntervalSeconds { get; init; } = 30;
+
+    /// <summary>
+    ///     Whether the latest successful Galaxy browse dataset is persisted to disk. When
+    ///     enabled, the cache reloads that snapshot at startup so clients can still browse
+    ///     last-known data while the Galaxy database is unreachable.
+    /// </summary>
+    public bool PersistSnapshot { get; init; } = true;
+
+    /// <summary>
+    ///     File path for the persisted Galaxy browse snapshot. Ignored when
+    ///     <see cref="PersistSnapshot"/> is <see langword="false"/>. There is no built-in
+    ///     default path — the consumer supplies a cross-platform-friendly path appropriate to
+    ///     its host. When left empty and <see cref="PersistSnapshot"/> is enabled, the
+    ///     snapshot store (a later task) decides where to write.
+    /// </summary>
+    public string SnapshotCachePath { get; init; } = string.Empty;
+}
@@ -0,0 +1,16 @@
+using ZB.MOM.WW.GalaxyRepository.Grpc;
+
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>
+///     Resolution result for a tag address: the owning <see cref="GalaxyObject"/>, the
+///     specific <see cref="GalaxyAttribute"/> when the address names an attribute (otherwise
+///     <see langword="null"/>), and the object's contained path.
+/// </summary>
+/// <param name="Object">The Galaxy object that owns the looked-up address.</param>
+/// <param name="Attribute">The matched attribute, or <see langword="null"/> when the address names an object.</param>
+/// <param name="ContainedPath">The owning object's contained path.</param>
+public sealed record GalaxyTagLookup(
+    GalaxyObject Object,
+    GalaxyAttribute? Attribute,
+    string ContainedPath);
@@ -0,0 +1,354 @@
+using Google.Protobuf.WellKnownTypes;
+using Grpc.Core;
+using ProtoGalaxyRepository = ZB.MOM.WW.GalaxyRepository.Grpc.GalaxyRepository;
+
+namespace ZB.MOM.WW.GalaxyRepository.Grpc;
+
+/// <summary>
+///     Reusable gRPC surface that exposes the Galaxy Repository to clients. Hosted by any
+///     consuming gateway (e.g. MxAccessGateway or the HistorianGateway sidecar) via
+///     <see cref="DependencyInjection.GalaxyRepositoryServiceCollectionExtensions.MapZbGalaxyRepository"/>.
+///     <para>
+///     <c>DiscoverHierarchy</c> and <c>GetLastDeployTime</c> serve from
+///     <see cref="IGalaxyHierarchyCache"/> so many clients share a single SQL pull.
+///     <c>WatchDeployEvents</c> streams events from <see cref="IGalaxyDeployNotifier"/>.
+///     <c>TestConnection</c> remains a direct SQL probe since callers use it as a health check.
+///     </para>
+///     <para>
+///     Per-identity browse-subtree filtering is delegated to the injected
+///     <see cref="IGalaxyBrowseScopeProvider"/>. The default
+///     <see cref="NullGalaxyBrowseScopeProvider"/> returns <c>null</c> globs, so the full
+///     hierarchy is projected and behavior is unchanged. A hosting gateway can register its
+///     own provider to scope <c>DiscoverHierarchy</c>/<c>BrowseChildren</c> results — and the
+///     <c>object_count</c>/<c>attribute_count</c> totals streamed by <c>WatchDeployEvents</c> —
+///     to the caller's allowed subtrees.
+///     </para>
+/// </summary>
+/// <param name="repository">Direct SQL surface used by <c>TestConnection</c>.</param>
+/// <param name="cache">Shared hierarchy cache that <c>DiscoverHierarchy</c>/<c>BrowseChildren</c>/<c>GetLastDeployTime</c> serve from.</param>
+/// <param name="notifier">Deploy-event source streamed by <c>WatchDeployEvents</c>.</param>
+/// <param name="scope">Resolves the per-caller browse-subtree globs applied to browse/discover results.</param>
+public sealed class GalaxyRepositoryGrpcService(
+    IGalaxyRepository repository,
+    IGalaxyHierarchyCache cache,
+    IGalaxyDeployNotifier notifier,
+    IGalaxyBrowseScopeProvider scope) : ProtoGalaxyRepository.GalaxyRepositoryBase
+{
+    private static readonly TimeSpan FirstLoadWaitBudget = TimeSpan.FromSeconds(5);
+    private const int DefaultDiscoverPageSize = 1000;
+    private const int MaxDiscoverPageSize = 5000;
+    private const int DefaultBrowsePageSize = 500;
+    // MaxBrowsePageSize reuses MaxDiscoverPageSize (5000) — same cap.
+
+    /// <inheritdoc />
+    public override async Task<TestConnectionReply> TestConnection(
+        TestConnectionRequest request,
+        ServerCallContext context)
+    {
+        bool ok = await repository.TestConnectionAsync(context.CancellationToken).ConfigureAwait(false);
+        return new TestConnectionReply { Ok = ok };
+    }
+
+    /// <inheritdoc />
+    public override async Task<GetLastDeployTimeReply> GetLastDeployTime(
+        GetLastDeployTimeRequest request,
+        ServerCallContext context)
+    {
+        await WaitForCacheBootstrap(context.CancellationToken).ConfigureAwait(false);
+        GalaxyHierarchyCacheEntry entry = cache.Current;
+
+        if (!entry.HasData)
+        {
+            throw new RpcException(new Status(
+                StatusCode.Unavailable,
+                ResolveUnavailableMessage(entry)));
+        }
+
+        GetLastDeployTimeReply reply = new() { Present = entry.LastDeployTime.HasValue };
+        if (entry.LastDeployTime.HasValue)
+        {
+            reply.TimeOfLastDeploy = Timestamp.FromDateTimeOffset(entry.LastDeployTime.Value);
+        }
+        return reply;
+    }
+
+    /// <inheritdoc />
+    public override async Task<DiscoverHierarchyReply> DiscoverHierarchy(
+        DiscoverHierarchyRequest request,
+        ServerCallContext context)
+    {
+        await WaitForCacheBootstrap(context.CancellationToken).ConfigureAwait(false);
+        GalaxyHierarchyCacheEntry entry = cache.Current;
+
+        if (!entry.HasData)
+        {
+            throw new RpcException(new Status(
+                StatusCode.Unavailable,
+                ResolveUnavailableMessage(entry)));
+        }
+
+        int pageSize = ResolvePageSize(request.PageSize);
+        IReadOnlyList<string>? browseSubtrees = scope.ResolveBrowseSubtrees(context);
+        string filterSignature = GalaxyHierarchyProjector.ComputeFilterSignature(request, browseSubtrees);
+        PageToken pageToken = ParsePageToken(request.PageToken, entry.Sequence, filterSignature);
+        GalaxyHierarchyQueryResult query = GalaxyHierarchyProjector.Project(
+            entry,
+            request,
+            browseSubtrees,
+            pageToken.Offset,
+            pageSize);
+        int offset = pageToken.Offset;
+        if (offset > query.TotalObjectCount)
+        {
+            throw new RpcException(new Status(
+                StatusCode.InvalidArgument,
+                "DiscoverHierarchy page_token is outside the current hierarchy."));
+        }
+
+        DiscoverHierarchyReply reply = new()
+        {
+            TotalObjectCount = query.TotalObjectCount,
+        };
+        reply.Objects.Add(query.Objects);
+
+        int nextOffset = offset + query.Objects.Count;
+        if (nextOffset < query.TotalObjectCount)
+        {
+            reply.NextPageToken = FormatPageToken(entry.Sequence, query.FilterSignature, nextOffset);
+        }
+
+        return reply;
+    }
+
+    /// <inheritdoc />
+    public override async Task<BrowseChildrenReply> BrowseChildren(
+        BrowseChildrenRequest request,
+        ServerCallContext context)
+    {
+        await WaitForCacheBootstrap(context.CancellationToken).ConfigureAwait(false);
+        GalaxyHierarchyCacheEntry entry = cache.Current;
+
+        if (!entry.HasData)
+        {
+            throw new RpcException(new Status(
+                StatusCode.Unavailable,
+                ResolveUnavailableMessage(entry)));
+        }
+
+        int pageSize = ResolveBrowsePageSize(request.PageSize);
+        IReadOnlyList<string>? browseSubtrees = scope.ResolveBrowseSubtrees(context);
+
+        // Resolve the parent id once so the page-token signature can include it
+        // and the projector sees the same resolved id when memoizing. The projector
+        // re-resolves internally; with the by-name/by-path indexes on
+        // GalaxyHierarchyIndex that second call is O(1), so the redundancy is cheap
+        // and keeps the projector self-contained.
+        int parentId = GalaxyBrowseProjector.ResolveParentId(entry, request);
+        string filterSignature = GalaxyBrowseProjector.ComputeFilterSignature(
+            request, browseSubtrees, parentId);
+        PageToken pageToken = ParsePageToken(request.PageToken, entry.Sequence, filterSignature);
+
+        GalaxyBrowseChildrenResult result = GalaxyBrowseProjector.ProjectChildren(
+            entry,
+            request,
+            browseSubtrees,
+            pageToken.Offset,
+            pageSize);
+
+        if (pageToken.Offset > result.TotalChildCount)
+        {
+            throw new RpcException(new Status(
+                StatusCode.InvalidArgument,
+                "BrowseChildren page_token is outside the current children set."));
+        }
+
+        BrowseChildrenReply reply = new()
+        {
+            TotalChildCount = result.TotalChildCount,
+            CacheSequence = (ulong)entry.Sequence,
+        };
+        reply.Children.Add(result.Children);
+        reply.ChildHasChildren.Add(result.ChildHasChildren);
+
+        int nextOffset = pageToken.Offset + result.Children.Count;
+        if (nextOffset < result.TotalChildCount)
+        {
+            reply.NextPageToken = FormatPageToken(entry.Sequence, result.FilterSignature, nextOffset);
+        }
+
+        return reply;
+    }
+
+    /// <inheritdoc />
+    public override async Task WatchDeployEvents(
+        WatchDeployEventsRequest request,
+        IServerStreamWriter<DeployEvent> responseStream,
+        ServerCallContext context)
+    {
+        DateTimeOffset? lastSeen = request.LastSeenDeployTime?.ToDateTimeOffset();
+
+        // The caller's identity (and therefore its browse-subtree constraints) is fixed
+        // for the lifetime of the stream, so resolve the subtrees once rather than per
+        // streamed event.
+        IReadOnlyList<string>? browseSubtrees = scope.ResolveBrowseSubtrees(context);
+
+        await foreach (GalaxyDeployEventInfo info in notifier
+            .SubscribeAsync(context.CancellationToken)
+            .ConfigureAwait(false))
+        {
+            // Suppress the initial bootstrap event when the client already knows about
+            // this deploy time. We only suppress the first one — subsequent events fire
+            // on actual changes, so they always pass.
+            if (lastSeen is { } seen && info.TimeOfLastDeploy == seen)
+            {
+                lastSeen = null;
+                continue;
+            }
+            lastSeen = null;
+
+            await responseStream.WriteAsync(MapDeployEvent(info, browseSubtrees), context.CancellationToken).ConfigureAwait(false);
+        }
+    }
+
+    private async Task WaitForCacheBootstrap(CancellationToken cancellationToken)
+    {
+        if (cache.Current.HasData || cache.Current.Status == GalaxyCacheStatus.Unavailable)
+        {
+            return;
+        }
+
+        using CancellationTokenSource budget = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+        budget.CancelAfter(FirstLoadWaitBudget);
+        try
+        {
+            await cache.WaitForFirstLoadAsync(budget.Token).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw;
+        }
+        catch (OperationCanceledException)
+        {
+            // Budget elapsed; fall through and let the caller see the current
+            // (possibly Unknown/Unavailable) entry.
+        }
+    }
+
+    private DeployEvent MapDeployEvent(
+        GalaxyDeployEventInfo info,
+        IReadOnlyList<string>? browseSubtrees)
+    {
+        int objectCount = info.ObjectCount;
+        int attributeCount = info.AttributeCount;
+        if (browseSubtrees is { Count: > 0 } && cache.Current.HasData)
+        {
+            GalaxyHierarchyQueryResult scoped = GalaxyHierarchyProjector.Project(
+                cache.Current,
+                new DiscoverHierarchyRequest(),
+                browseSubtrees);
+            objectCount = scoped.TotalObjectCount;
+            attributeCount = scoped.Objects.Sum(obj => obj.Attributes.Count);
+        }
+
+        DeployEvent ev = new()
+        {
+            Sequence = (ulong)info.Sequence,
+            ObservedAt = Timestamp.FromDateTimeOffset(info.ObservedAt),
+            ObjectCount = objectCount,
+            AttributeCount = attributeCount,
+            TimeOfLastDeployPresent = info.TimeOfLastDeploy.HasValue,
+        };
+        if (info.TimeOfLastDeploy.HasValue)
+        {
+            ev.TimeOfLastDeploy = Timestamp.FromDateTimeOffset(info.TimeOfLastDeploy.Value);
+        }
+        return ev;
+    }
+
+    private static string ResolveUnavailableMessage(GalaxyHierarchyCacheEntry entry) => entry.Status switch
+    {
+        GalaxyCacheStatus.Unknown => "Galaxy cache has not completed its initial load yet.",
+        GalaxyCacheStatus.Unavailable => "Galaxy repository is unavailable.",
+        _ => "Galaxy cache has no data available.",
+    };
+
+    private static int ResolvePageSize(int requestedPageSize)
+    {
+        if (requestedPageSize < 0)
+        {
+            throw new RpcException(new Status(
+                StatusCode.InvalidArgument,
+                "DiscoverHierarchy page_size must be greater than zero when provided."));
+        }
+
+        int pageSize = requestedPageSize == 0 ? DefaultDiscoverPageSize : requestedPageSize;
+        return Math.Min(pageSize, MaxDiscoverPageSize);
+    }
+
+    private static int ResolveBrowsePageSize(int requested)
+    {
+        if (requested < 0)
+        {
+            throw new RpcException(new Status(
+                StatusCode.InvalidArgument,
+                "BrowseChildren page_size must be greater than zero when provided."));
+        }
+        int pageSize = requested == 0 ? DefaultBrowsePageSize : requested;
+        return Math.Min(pageSize, MaxDiscoverPageSize);
+    }
+
+    private static string FormatPageToken(long sequence, string filterSignature, int offset)
+    {
+        return string.Concat(
+            sequence.ToString(System.Globalization.CultureInfo.InvariantCulture),
+            ":",
+            filterSignature,
+            ":",
+            offset.ToString(System.Globalization.CultureInfo.InvariantCulture));
+    }
+
+    private static PageToken ParsePageToken(string pageToken, long currentSequence, string currentFilterSignature)
+    {
+        if (string.IsNullOrWhiteSpace(pageToken))
+        {
+            return new PageToken(currentSequence, currentFilterSignature, Offset: 0);
+        }
+
+        string[] parts = pageToken.Split(':', count: 3);
+        if (parts.Length != 3
+            || !long.TryParse(
+                parts[0],
+                System.Globalization.NumberStyles.None,
+                System.Globalization.CultureInfo.InvariantCulture,
+                out long sequence)
+            || !int.TryParse(
+                parts[2],
+                System.Globalization.NumberStyles.None,
+                System.Globalization.CultureInfo.InvariantCulture,
+                out int offset)
+            || offset < 0)
+        {
+            throw new RpcException(new Status(
+                StatusCode.InvalidArgument,
+                "page_token is invalid."));
+        }
+
+        if (sequence != currentSequence)
+        {
+            throw new RpcException(new Status(
+                StatusCode.InvalidArgument,
+                "page_token is stale."));
+        }
+
+        if (!string.Equals(parts[1], currentFilterSignature, StringComparison.Ordinal))
+        {
+            throw new RpcException(new Status(
+                StatusCode.InvalidArgument,
+                "page_token does not match the current filters."));
+        }
+
+        return new PageToken(sequence, parts[1], offset);
+    }
+
+    private sealed record PageToken(long Sequence, string FilterSignature, int Offset);
+}
@@ -0,0 +1,20 @@
+using Grpc.Core;
+
+namespace ZB.MOM.WW.GalaxyRepository.Grpc;
+
+/// <summary>
+///     Resolves the browse-subtree glob patterns the current caller is allowed to see.
+///     Lets a hosting gateway scope <see cref="GalaxyRepositoryGrpcService"/> results per
+///     identity without the library knowing the host's authorization model. The default
+///     <see cref="NullGalaxyBrowseScopeProvider"/> applies no scoping (full hierarchy).
+/// </summary>
+public interface IGalaxyBrowseScopeProvider
+{
+    /// <summary>
+    ///     Returns the allowed browse-subtree globs for the current call, or
+    ///     <see langword="null"/>/empty for no restriction (full hierarchy).
+    /// </summary>
+    /// <param name="context">The gRPC server call context for the current request.</param>
+    /// <returns>The allowed browse-subtree globs, or <see langword="null"/> for no restriction.</returns>
+    IReadOnlyList<string>? ResolveBrowseSubtrees(ServerCallContext context);
+}
@@ -0,0 +1,10 @@
+using Grpc.Core;
+
+namespace ZB.MOM.WW.GalaxyRepository.Grpc;
+
+/// <summary>Default <see cref="IGalaxyBrowseScopeProvider"/> that applies no scoping (full hierarchy).</summary>
+public sealed class NullGalaxyBrowseScopeProvider : IGalaxyBrowseScopeProvider
+{
+    /// <inheritdoc />
+    public IReadOnlyList<string>? ResolveBrowseSubtrees(ServerCallContext context) => null;
+}
@@ -0,0 +1,17 @@
+namespace ZB.MOM.WW.GalaxyRepository;
+
+/// <summary>Publishes Galaxy repository deploy events to subscribers.</summary>
+public interface IGalaxyDeployNotifier
+{
+    /// <summary>The most recently published event, or null if no event has fired yet.</summary>
+    GalaxyDeployEventInfo? Latest { get; }
+
+    /// <summary>Publishes a deploy event to all current subscribers and stores it as Latest.</summary>
+    /// <param name="info">The deploy event to publish.</param>
+    void Publish(GalaxyDeployEventInfo info);
+
+    /// <summary>Subscribes to deploy events. The sequence yields the latest event first (if available) then streams new events as they fire.</summary>
+    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
+    /// <returns>Async enumerable of deploy events.</returns>
+    IAsyncEnumerable<GalaxyDeployEventInfo> SubscribeAsync(CancellationToken cancellationToken);
+}
--- a/Show More
+++ b/Show More