# A2 — Adopt the shared `ZB.MOM.WW.GalaxyRepository` library

> **✅ ADOPTED 2026-06-25 (branch `feat/galaxyrepository-adoption`).** mxaccessgw now consumes
> `ZB.MOM.WW.GalaxyRepository` **0.2.0** and the inline Galaxy code is deleted (27 files, −2959 LOC).
> What shipped:
> - **Lib 0.2.0** (published to Gitea) closed the two real upstream gaps: **alarm-attribute discovery**
>   (`GalaxyAlarmAttributeRow` + `IGalaxyRepository.GetAlarmAttributesAsync` + `AlarmAttributesSql`) and an
>   injectable **`IGalaxyBrowseScopeProvider`** (default `NullGalaxyBrowseScopeProvider` = no scoping;
>   HistorianGateway @ 0.1.0 unaffected) wired into the lib's gRPC service. Lib test suite: 64 green.
> - **mxaccessgw** registers `GatewayBrowseScopeProvider : IGalaxyBrowseScopeProvider` (reads the API key's
>   `EffectiveConstraints.BrowseSubtrees`) before `AddZbGalaxyRepository(config,"MxGateway:Galaxy")`, maps
>   `MapZbGalaxyRepository()`, and switched `GatewayGrpcScopeResolver` galaxy request types to the lib
>   `.Grpc` namespace (the global authz interceptor now intercepts the lib service). The **dashboard summary
>   stays host-side** (`DashboardGalaxySummaryProjector`, memoized by cache `Sequence`) since the lib entry
>   doesn't carry it. Server build zero-warning; 327 targeted tests green.
> - The end-to-end host authz chain is covered (`GalaxyRepositoryHostWiringTests`), and the lib gained the
>   ported browse-projector / deploy-notifier / refresh-service (Server-005 timeout guard) tests.
>
> **Caveats / follow-ups** (see "Post-adoption notes" at the bottom).
> Original handoff (now historical) follows.

> Handoff note. Written 2026-06-25 from the HistorianGateway side, where the shared lib is
> already consumed in production. This is the mxaccessgw half of the cross-repo
> "Galaxy-browse normalization" follow-on (HistorianGateway `pending.md` A2 /
> scadaproj component-normalization).

## Goal

Replace mxaccessgw's **inline** Galaxy-browse code (`src/ZB.MOM.WW.MxGateway.Server/Galaxy/**`
plus `Grpc/GalaxyRepositoryGrpcService.cs` + `Grpc/GalaxyProtoMapper.cs`) with a
`PackageReference` to the shared **`ZB.MOM.WW.GalaxyRepository`** library, so there is **one**
Galaxy-browse implementation shared by both sidecars instead of two copies that can drift.

The wire contract is **unchanged** — both repos already serve the same `galaxy_repository.v1`
proto — so **no client change is required**. This is an internal refactor.

## Why this is safe to do now

The shared lib was **extracted from this very code**: the file names under
`src/ZB.MOM.WW.MxGateway.Server/Galaxy/**` map ~1:1 onto
`scadaproj/ZB.MOM.WW.GalaxyRepository/src/ZB.MOM.WW.GalaxyRepository/**`. HistorianGateway
consumes it (`PackageReference @ 0.1.0`) and runs it live against `wonder-sql-vd03`. So the SQL
provider, hierarchy cache, deploy notifier, snapshot store, background refresh service, projectors,
glob matcher, tag lookup, and the gRPC service are **already proven** in the package — the work here
is wiring + reconciling the mxaccessgw-only pieces, not reimplementing browse.

## The clean part — 1:1 swap

These inline files are superseded by the package (delete on adoption; rebind references to namespace
`ZB.MOM.WW.GalaxyRepository`):

| mxaccessgw inline (`…Server/Galaxy/`) | Shared lib equivalent |
|---|---|
| `GalaxyRepository.cs` / `IGalaxyRepository.cs` | same |
| `GalaxyHierarchyCache.cs` / `IGalaxyHierarchyCache.cs` / `GalaxyHierarchyCacheEntry.cs` | same |
| `GalaxyHierarchyRefreshService.cs` | same (registered as `HostedService` by the lib's DI ext) |
| `GalaxyDeployNotifier.cs` / `IGalaxyDeployNotifier.cs` / `GalaxyDeployEventInfo.cs` | same |
| `GalaxyHierarchySnapshot*.cs` / `IGalaxyHierarchySnapshotStore.cs` | same |
| `GalaxyHierarchyProjector.cs` / `GalaxyBrowseProjector.cs` / `GalaxyHierarchyIndex.cs` | same |
| `GalaxyObjectView.cs` / `GalaxyHierarchyRow.cs` / `GalaxyAttributeRow.cs` | same |
| `GalaxyBrowseChildrenResult.cs` / `GalaxyHierarchyQueryResult.cs` | same |
| `GalaxyTagLookup.cs` / `GalaxyGlobMatcher.cs` / `GalaxyCacheStatus.cs` | same |
| `GalaxyRepositoryOptions.cs` | `GalaxyRepositoryOptions` (lib ships **no validator** — see below) |
| `Grpc/GalaxyRepositoryGrpcService.cs` / `Grpc/GalaxyProtoMapper.cs` | lib bundles its own `Grpc/GalaxyRepositoryGrpcService.cs` + `GalaxyProtoMapper.cs`, mapped by `MapZbGalaxyRepository()` — **but verify authz parity first, see ⚠️ below** |
| `Galaxy/GalaxyRepositoryServiceCollectionExtensions.cs` | replaced by the lib's `AddZbGalaxyRepository` / `MapZbGalaxyRepository` |

## ⚠️ The hard part — mxaccessgw-only consumers the shared lib does NOT cover

HistorianGateway was a greenfield consumer (browse + dashboard tree only). mxaccessgw has **extra
consumers of the Galaxy cache/hierarchy that the shared lib was not extracted with.** These are the
real work and the real risk:

1. **Alarm watch-list / alarm-attribute discovery — capability GAP in the lib.**
   - mxaccessgw has `Galaxy/GalaxyAlarmAttributeRow.cs` and `GalaxyRepository.GetAlarmAttributesAsync()`,
     consumed by `Alarms/AlarmWatchListResolver.cs` (+ `IAlarmWatchListResolver`, `GatewayAlarmMonitor`).
   - The shared lib has **`GalaxyAttributeRow` + `GetAttributesAsync()` only** — there is **no**
     `GalaxyAlarmAttributeRow` / `GetAlarmAttributesAsync` in `0.1.0`.
   - **Decision needed:** either (a) push the alarm-attributes SQL projection **upstream** into the
     shared lib (a `0.2.0` additive feature — preferred, keeps it shared) and re-consume, or
     (b) keep `AlarmWatchListResolver` + the alarm-attributes query **inline** in mxaccessgw, layered
     **on top of** the shared `IGalaxyRepository`/`IGalaxyHierarchyCache`. (a) is the spirit of A2.

2. **Dashboard consumers** — `Dashboard/DashboardGalaxyProjector.cs`, `DashboardBrowseService.cs`
   (+ `IDashboardBrowseService`, `DashboardBrowseModel`), `DashboardSnapshotService.cs`,
   `DashboardGalaxySummary.cs`, and the Razor pages `GalaxyPage.razor` / `DashboardHome.razor` all
   `using ZB.MOM.WW.MxGateway.Server.Galaxy`. Mechanical rebind to `ZB.MOM.WW.GalaxyRepository`, but
   confirm every type they touch is `public` in the lib (most are; double-check projector/snapshot
   types).

3. **Security / authorization** — `Security/Authorization/ConstraintEnforcer.cs` and
   `GatewayGrpcScopeResolver.cs` consume Galaxy hierarchy to enforce per-key constraints. Rebind, and
   see the gRPC-service question below.

⚠️ **gRPC-service authz parity — VERIFIED 2026-06-25: NOT safe to swap wholesale.** The authorization
is **split across two layers**, and the part that matters is **baked into the service body**:

1. **Authentication + scope gating IS interceptor-based ✅ (safe).** `Security/Authorization/GatewayGrpcAuthorizationInterceptor.cs`
   authenticates the API key and enforces the required scope; all five Galaxy RPCs map to the `metadata`
   scope (`GatewayGrpcScopeResolver.cs:23-27` → `MetadataRead`). The interceptor also pushes the identity
   into an ambient `IGatewayRequestIdentityAccessor` for the call. This mirrors HistorianGateway and is
   shared-lib compatible.
2. **Per-key browse-subtree CONSTRAINT FILTERING is baked into the service body ❌ (the blocker).**
   mxaccessgw's `Grpc/GalaxyRepositoryGrpcService.cs` injects `IGatewayRequestIdentityAccessor` and
   `ResolveBrowseSubtrees()` (`:287-291`) reads `identityAccessor.Current.EffectiveConstraints.BrowseSubtrees`,
   threading those globs into the projectors for `DiscoverHierarchy` (`:78`), `BrowseChildren` (`:138`),
   and the `WatchDeployEvents` count scoping (`:180,196,230-237`) — i.e. it restricts **which Galaxy
   objects each API key can see**. The shared lib's service injects no identity accessor and passes
   `browseSubtreeGlobs: null` everywhere; its own XML doc states it *"applies no per-identity
   browse-subtree filtering … Authorization (including any subtree scoping) is the responsibility of the
   hosting gateway's interceptor layer."*

**Severity — silent per-key data exposure.** Glob semantics (`GalaxyHierarchyProjector.cs:225-227`):
`null`/empty → match everything; non-empty → restrict. So keys with **no** browse constraint behave
identically in both services (no regression), but a key **with** a `BrowseSubtrees` constraint would, on
the shared service, receive the **entire** Galaxy hierarchy — a `metadata`-scoped key silently bypassing
its restriction. The boundary is locked by tests that would fail against the shared service:
`Tests/Gateway/Grpc/GalaxyRepositoryGrpcServiceTests.cs` → `BrowseChildren_BrowseSubtreesConstraint_FiltersChildren`
(`:437`) and `DiscoverHierarchy_WithSubtreeRootAndDepth_FiltersDescendants` (`:90`).

**Recommendation.** Do **not** call `MapZbGalaxyRepository()` directly. The shared projectors already
accept a `browseSubtreeGlobs` param, so either fix is small plumbing:
- **Preferred (spirit of A2 — push upstream):** give the shared `GalaxyRepositoryGrpcService` an optional
  browse-subtree-constraint provider (e.g. `IBrowseSubtreeConstraintProvider`/delegate returning globs —
  `null` in HistorianGateway, identity-derived in mxaccessgw). One shared service, both behaviors; bundle
  with the same `0.2.0` bump as the alarm-attributes gap above.
- **Fallback (isolate to mxaccessgw):** keep a thin mxaccessgw service that resolves subtrees from
  identity and calls the shared (public) projectors, and map **that** instead of `MapZbGalaxyRepository()`.

## Concrete wiring steps (template from the HistorianGateway side)

1. **`nuget.config`** — mxaccessgw's `packageSourceMapping` for the `dohertj2-gitea` source currently
   lists `ZB.MOM.WW.*` up to `Theme` but **NOT** GalaxyRepository. Add:
   ```xml
   <package pattern="ZB.MOM.WW.GalaxyRepository" />
   ```
   under the `dohertj2-gitea` `<packageSource>`. (Easy to miss — restore will fail without it.)

2. **Server `.csproj`** — add:
   ```xml
   <PackageReference Include="ZB.MOM.WW.GalaxyRepository" Version="0.1.0" />
   ```
   (or whatever version ships the alarm-attributes add, if you go route 1(a) above.)

3. **DI + endpoint wiring** (in mxaccessgw's host composition — `GatewayApplication.cs` / its
   `Program`), mirroring HistorianGateway's `Program.cs`:
   ```csharp
   using ZB.MOM.WW.GalaxyRepository;
   using ZB.MOM.WW.GalaxyRepository.DependencyInjection;

   // service registration — bind from mxaccessgw's section path (NOT top-level "Galaxy"):
   builder.Services.AddZbGalaxyRepository(builder.Configuration, "MxGateway:Galaxy"); // confirm the exact section path mxaccessgw uses today

   // endpoint pipeline (after AddGrpc):
   app.MapZbGalaxyRepository();
   ```
   Delete mxaccessgw's own `Galaxy/GalaxyRepositoryServiceCollectionExtensions.cs` registrations.

4. **Option validation** — the shared lib **binds only, ships no validator** (deliberate). mxaccessgw
   already validates Galaxy options via `Configuration/GatewayOptionsValidator.cs` — **keep that**; it
   stays the owner of fail-fast validation, exactly as HistorianGateway's `ConfigPreflight` does.

5. **Health check** — keep mxaccessgw's existing Galaxy-SQL readiness check; read the connection
   string from the same `MxGateway:Galaxy` section the lib binds (HistorianGateway does this with a raw
   `SELECT 1` `SqlConnectionHealthCheck` — see `Program.cs:196`).

## Tests

mxaccessgw has a large `Tests/Galaxy/**` suite that **duplicates the shared lib's own tests**
(`GalaxyHierarchyCacheTests`, `GalaxyHierarchyProjectorTests`, `GalaxyHierarchySnapshotStoreTests`,
`GalaxyProtoMapperTests`, `GalaxyHierarchyIndexTests`). On adoption these are covered upstream and can
be **deleted**. **Keep** the mxaccessgw-specific ones that exercise behavior the lib doesn't own:
`GalaxyAlarmAttributeMappingTests`, `GalaxyFilterInputSafetyTests`, `GalaxyRepositoryGrpcServiceTests`
(unless their subjects move upstream too), and the live `IntegrationTests/Galaxy/**`.

## Suggested order — all DONE (2026-06-25)

1. ~~Verify the **gRPC-service authz parity** question~~ **DONE:** wholesale swap was unsafe — per-key
   browse-subtree filtering was baked into the service body. Resolved by pushing an injectable
   `IGalaxyBrowseScopeProvider` hook **upstream** into the lib (option preferred in the ⚠️ block).
2. ~~Decide alarm-attributes~~ **DONE:** upstreamed into the lib as part of `0.2.0`.
3. ~~Upstream + publish + bump~~ **DONE:** lib `0.1.0 → 0.2.0`, packed and pushed to the Gitea feed (verified live).
4. ~~`nuget.config` + `csproj` + DI/endpoint wiring; delete inline; rebind~~ **DONE.**
5. ~~Delete duplicated tests; build zero-warning; run the suite~~ **DONE** (lib 64 green; gateway 327 targeted green).
   Live-validate browse + alarm watch-list is the one remaining **manual** step (needs Galaxy SQL + a running
   gateway — opt-in `MXGATEWAY_RUN_LIVE_GALAXY_TESTS=1`); not runnable from the dev Mac.
6. **Remaining:** propagate to the scadaproj umbrella index + HistorianGateway's `pending.md` §A2 (mark adopted)
   — cross-repo, do in those repos.

## Post-adoption notes / caveats

- **Deployment config (NSSM):** the deployed services (`MxAccessGw` on 10.100.0.48; the wonder host) read
  config from **NSSM environment variables, not `appsettings.json`**. The lib's `SnapshotCachePath` default
  is empty (persistence no-ops). `appsettings.json` sets `MxGateway:Galaxy:SnapshotCachePath` +
  `PersistSnapshot`, but the deployments must carry `MxGateway__Galaxy__SnapshotCachePath` and
  `MxGateway__Galaxy__PersistSnapshot` in their NSSM env on redeploy, or snapshot persistence silently
  no-ops in production.
- **Pre-existing NU1903 (unrelated):** adding the package surfaced a transitive `SQLitePCLRaw.lib.e_sqlite3`
  2.1.11 advisory (GHSA-2m69-gcr7-jv3q, no upstream patch) that breaks the build under `TreatWarningsAsErrors`
  — already red on `main`. Resolved with a targeted `NuGetAuditSuppress` in `src/Directory.Build.props`
  (its own commit). Remove the suppression once a patched e_sqlite3 ships.
- **Pre-existing IntegrationTests break (unrelated, NOT fixed here):** `IntegrationTests/WorkerLiveMxAccessSmokeTests.cs`
  constructs `EventStreamService` with 6 ctor args, but a prior event-stream refactor reduced that ctor — so
  the IntegrationTests project does not compile (already broken on `main`, independent of Galaxy). The Galaxy
  live tests there were rebound to the lib and compile in isolation, but the project won't build until that
  unrelated call site is fixed. Track separately.
- **No republish needed for the lib test additions:** the browse-projector / deploy-notifier / refresh-service
  tests were added to the lib AFTER 0.2.0 was published; tests aren't shipped, so 0.2.0 is unchanged.

## Reference pointers

- **Working consumer (copy this):** `~/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Program.cs`
  (`AddZbGalaxyRepository` @ ~line 174, `MapZbGalaxyRepository` @ ~line 314) + its `nuget.config` + Server `.csproj`.
- **Shared lib source:** `~/Desktop/scadaproj/ZB.MOM.WW.GalaxyRepository/` (DI ext at
  `src/ZB.MOM.WW.GalaxyRepository/DependencyInjection/GalaxyRepositoryServiceCollectionExtensions.cs`).
- **Tracked in:** HistorianGateway `pending.md` §A2 + `CLAUDE.md` → Known Follow-Ons; scadaproj component normalization.