lmxopcua/docs/plans/2026-06-12-galaxy-standard-driver-design.md

# Galaxy as a Standard Equipment Driver — Design

**Date:** 2026-06-12
**Status:** Approved (brainstorming) — ready for implementation planning
**Scope:** One design, three phases (A → B → C). Each phase is an independently
mergeable, live-verifiable branch.

## Goal

Make `GalaxyMxGateway` **just another standard driver**: bound under
**Equipment**-kind namespaces like Modbus/S7, authored through the normal
`TagModal`, materialized through the single equipment-tag path, with **native
alarms** and **server-side historian / `HistoryRead`** working in that model.
Retire the `SystemPlatform` namespace split, the SystemPlatform mirror, and the
alias-tag/relay machinery.

## Background — why Galaxy is "treated differently" today

The `GalaxyMxGateway` driver already implements the full Tier-A capability set
through the same `IDriver`/`IDriverFactory` path as Modbus
(`IReadable`/`IWritable`/`ISubscribable`/`ITagDiscovery`), plus more
(`IAlarmSource` native alarms, `IRediscoverable` deploy-watch). It is **not** the
odd one out at the driver-contract level. The difference lives **above the
socket**, in four seams:

1. **Namespace inversion (root cause).** `NamespaceKind` (`Equipment` vs
   `SystemPlatform`) plus `DriverTypeRegistry.NamespaceKindCompatibility` and
   `DraftValidator.ValidateDriverNamespaceCompatibility` hard-code that
   `GalaxyMxGateway` may live **only** in a `SystemPlatform`-kind namespace and
   every other driver **only** in `Equipment`-kind. That single asymmetry forces
   everything below.
2. **The alias-tag / relay workaround.** Because Galaxy can't live under
   Equipment directly, its objects are bridged into the UNS via *alias tags*
   (`Tag{EquipmentId, DriverInstanceId=GalaxyMxGateway, TagConfig={"FullName":…}}`)
   and the relay→alias converter. A whole machinery
   (`CreateAliasTagAsync`, `CheckAliasDriverGuardAsync`, `AliasTagModal`,
   `/uns/convert-relays`, `IsAlias`/`Source` row decoration) exists **only** to
   compensate for the namespace split. (Shipped 2026-06-12.)
3. **A separate address-space pass.** `Phase7Applier.MaterialiseGalaxyTags` runs
   distinct from `MaterialiseEquipmentTags`, with byte-parity exception clauses
   (`|| di.DriverType == "GalaxyMxGateway"`) in `Phase7Composer` and
   `DeploymentArtifact`.
4. **Historian gap.** Galaxy implements `IAlarmSource` (native alarms, verified
   working end-to-end 2026-05-31) but **not** `IHistoryProvider`, and the server
   has **no OPC UA `HistoryRead` dispatcher at all** today.

### The decisive finding: two materialization paths

The server has two ways nodes reach the address space, and Galaxy and Modbus use
*different* ones:

- **Authored-equipment-tag path** — `Phase7Composer` → `DeploymentArtifact` →
  `OtOpcUaNodeManager.MaterialiseEquipmentTags`. Materializes explicitly-authored
  `Tag` entities. Wires live read/write/subscribe **and scripted alarms**
  (`MaterialiseAlarmCondition`, keyed by `ScriptedAlarmId`). Alias tags and
  Modbus tags live here.
- **Driver-discovery path** — `ITagDiscovery.DiscoverAsync` →
  `GenericDriverNodeManager` → builder. Walks the driver's whole tree and is the
  **only** path that wires **native `IAlarmSource` alarms**:
  `GenericDriverNodeManager` (`src/Core/.../OpcUa/GenericDriverNodeManager.cs:52‑83`)
  registers an alarm-condition sink per `MarkAsAlarmCondition` variable keyed by
  `DriverAttributeInfo.FullName`, subscribes `IAlarmSource.OnAlarmEvent`, and
  routes each transition to the sink whose key equals `AlarmEventArgs.SourceNodeId`.
  **This path is the SystemPlatform mirror.**

Consequence: Galaxy **live values already work on equipment tags** (alias tags
prove it — direct driver subscription by `FullName`), but Galaxy **native alarms
only work on the mirror**. **Killing the mirror means the equipment-tag path must
gain native-alarm wiring.** That is the single largest real piece of work in this
design (Phase B).

## Locked decisions (from brainstorming)

| Decision | Choice |
|---|---|
| Binding model | **Authored equipment tags** — a Galaxy point is an ordinary `Tag` bound to `GalaxyMxGateway` with `TagConfig.FullName`. No alias concept. |
| Historian | **Server-side, driver-agnostic** — an `IsHistorized` tag's `HistoryRead` is served by the server's configured historian backend (the existing Wonderware sidecar reader), mapping the tag → historian tagname. No mxaccessgw history RPC. |
| Migration | **Clean break** — remove `SystemPlatform`; no converter; reseed docker-dev rigs by hand. Schema/EF change to drop the split is in scope. |
| Alias machinery | **Delete it** — Galaxy authors through the standard `TagModal`; `AliasTagModal`, alias guards, `/uns/convert-relays`, `IsAlias`/`Source` decoration all retire. |
| Doc/plan shape | **One design, three phases.** |

### Approaches considered and rejected

- **Discovery-into-equipment** (bind a `GalaxyMxGateway` instance to an Equipment
  node; `DiscoverAsync` auto-materializes the subtree). Rejected: reworks how
  Equipment materialization and authored-vs-discovered tags coexist; larger and
  changes the data model.
- **Keep the SystemPlatform mirror as browse-only.** Rejected: leaves two
  materialization paths — only partially meets the goal.
- **Galaxy driver implements `IHistoryProvider` via mxaccessgw.** Rejected:
  requires new history RPCs in the sibling gateway repo (cross-repo, out of this
  repo's control) and is not driver-agnostic.
- **One-time migration converter** / **keep SystemPlatform deprecated.** Rejected
  in favor of the clean break — this is pre-release with only dev rigs.

## Architecture (target end-state)

`GalaxyMxGateway` is an ordinary **Equipment-kind** driver. A Galaxy point is an
authored `Tag{EquipmentId set, DriverInstanceId=GalaxyMxGateway,
TagConfig={"FullName":"DelmiaReceiver_001.DownloadPath"}}` — identical to today's
alias tag with the "alias" concept, guards, and namespace restriction deleted.
The `NamespaceKind` split, the SystemPlatform mirror, `MaterialiseGalaxyTags`, and
the byte-parity `|| di.DriverType == "GalaxyMxGateway"` clauses retire. History
for **any** `IsHistorized` tag (not just Galaxy) is served by a new server-side
history backend wrapping the existing Wonderware Historian client.

## Components / workstreams

### Workstream 1 — Namespace de-split (foundation, Phase A)

- **`NamespaceKind`** (`src/Core/.../Configuration/Enums/NamespaceKind.cs`): remove
  `SystemPlatform` (keep `Equipment`; `Simulated` stays reserved).
- **EF migration** (`src/Core/.../Configuration/Migrations/`): forward-only.
  Delete orphaned `SystemPlatform` namespace rows, then relax / rebuild the
  `UX_Namespace_Cluster_Kind` unique constraint (now effectively single-valued).
  `Namespace.Kind` may remain a column (only `Equipment`) to minimize churn, or be
  dropped — implementer's call during planning, but the migration is required.
- **`DriverTypeRegistry`** (`src/Core/.../Core.Abstractions/DriverTypeRegistry.cs`):
  `GalaxyMxGateway` `NamespaceKindCompatibility` → `Equipment`.
- **`DraftValidator.ValidateDriverNamespaceCompatibility`** (~`:225‑245`): drop the
  Galaxy/SystemPlatform branches.
- **`Phase7Composer`** + **`DeploymentArtifact.BuildEquipmentTagPlans`**: remove the
  `|| di.DriverType == "GalaxyMxGateway"` exception clauses — the equipment-tag
  filter now admits Galaxy naturally. **Must stay byte-parity with each other.**
- **Retire `Phase7Applier.MaterialiseGalaxyTags`** and the Galaxy use of the
  `DiscoverAsync`/`GenericDriverNodeManager` mirror. `ITagDiscovery.DiscoverAsync`
  **stays** for the address-picker live browse only (which already uses
  `IBrowserSessionService` and is unaffected).

### Workstream 2 — Native alarms on the equipment-tag path (the hard part, Phase B)

- Teach `MaterialiseEquipmentTags` / `OtOpcUaNodeManager` that for an equipment tag
  whose `DriverAttributeInfo.IsAlarm` is true: register an alarm-condition sink
  keyed by the tag's `FullName`, subscribe the owning driver's `IAlarmSource`, and
  route `OnAlarmEvent.SourceNodeId == FullName` → sink. This ports
  `GenericDriverNodeManager`'s alarm-forwarder logic into the curated path
  (consider extracting the forwarder so both paths share it rather than
  duplicating).
- **Reuse** the existing Part 9 `AlarmConditionState` materialization
  (`OtOpcUaNodeManager.MaterialiseAlarmCondition`) and the `alarm-commands` / ack
  plumbing — those are condition-node mechanics and are agnostic to whether the
  alarm is scripted or native.
- Teardown / rediscovery parity: mirror `GenericDriverNodeManager`'s
  unsubscribe-before-rewalk so a Galaxy redeploy (`IRediscoverable`) does not
  double-deliver.

### Workstream 3 — Server-side historian backend (additive, Phase C)

- New OPC UA **`HistoryRead` service override** in `OtOpcUaNodeManager` (none exists
  today) → a **router** that, for an `IsHistorized` node, resolves a historian
  tagname and calls the registered server-side `IHistorianDataSource` (the
  Wonderware backend hardened in the TCP-transport work).
- **Tagname mapping:** default to the tag's driver `FullName`, with an optional
  explicit override on the tag. (System Platform logs attributes to AVEVA
  Historian under the same reference, so the default is usually correct.)
- Apply `DriverAttributeInfo.IsHistorized` → set the UA `Historizing` attribute +
  `AccessLevel.HistoryRead` bit at materialization
  (`OtOpcUaNodeManager` `CreateVariable`, currently hardcoded `Historizing = false`).
- **Config:** a server `Historian` section selecting the backend (Null default;
  Wonderware when configured) — mirrors the existing `AlarmHistorian` pattern.
- Driver-agnostic by construction: works for any `IsHistorized` tag, not only
  Galaxy.

### Workstream 4 — AdminUI fold-in (Phase A)

- Galaxy tag authored through the **standard `TagModal`** + the Galaxy live-browse
  picker (`GalaxyAddressPickerBody`) as that driver's address picker — same
  convention as Modbus/S7 pickers.
- **Retire** `AliasTagModal`, the alias guards (`CheckAliasDriverGuardAsync`,
  `LoadGalaxyGatewaysForEquipmentAsync` special path), `IsAlias`/`Source` row
  decoration, and the `/uns/convert-relays` page + `RelayConversion` machinery.
- **Keep** `GalaxyDriverPage` (typed driver-config editor) — that is the
  convention other drivers are moving toward, not a special-case.
- Add a driver-agnostic **`IsHistorized`** (+ optional historian-tagname) control
  to the tag editor (Phase C surfaces it; the control can land in Phase A inert).

## Data flow (a Galaxy tag, after)

```
Author Tag{Equipment, GalaxyMxGateway, FullName} via TagModal + Galaxy picker
   → DraftValidator (no Galaxy special branch)
   → Phase7Composer / DeploymentArtifact  (byte-parity, no exception clause)
   → OtOpcUaNodeManager.MaterialiseEquipmentTags
        • live value   : driver ISubscribable/IReadable by FullName   (works today)
        • native alarm : IsAlarm → register sink + IAlarmSource.OnAlarmEvent (NEW, ws-2)
        • historized   : IsHistorized → Historizing + HistoryRead bit   (NEW, ws-3)
OPC UA client HistoryRead
   → OtOpcUaNodeManager.HistoryRead override (NEW, ws-3)
   → server historian backend (IHistorianDataSource = Wonderware sidecar)
   → AVEVA Historian
```

## Error handling / edge cases

- **Byte-parity invariant:** `Phase7Composer` and `DeploymentArtifact` must produce
  identical equipment-tag plans for the same input after the exception clauses are
  removed. Covered by a parity round-trip test.
- **Unknown alarm `SourceNodeId`:** preserve `GenericDriverNodeManager`'s
  silently-drop behavior (an id may belong to another driver or an unflagged
  variable).
- **Historian not configured:** `Historian` backend defaults to Null →
  `HistoryRead` returns the standard "history unsupported / no data" status, not an
  error spike.
- **Redeploy double-delivery:** unsubscribe the native-alarm forwarder before
  re-walking on `IRediscoverable.OnRediscoveryNeeded`.
- **Migration on a non-empty DB:** the forward-only EF migration must tolerate
  existing `SystemPlatform` rows (delete them) before the relaxed constraint
  applies.

## Migration (clean break)

No converter. Drop `SystemPlatform`; existing SystemPlatform namespaces / mirror
tags are abandoned and the docker-dev rigs are **reseeded by hand** with Galaxy
tags authored under Equipment. The EF migration is forward-only and includes a
data step to delete orphaned `SystemPlatform` namespace rows so the relaxed
constraint applies cleanly.

## Testing (no bUnit)

**xUnit + Shouldly (offline):**
- `DraftValidator`: `GalaxyMxGateway` now valid under Equipment; old SystemPlatform
  branch gone.
- `Phase7Composer` ↔ `DeploymentArtifact` byte-parity with Galaxy equipment tags
  (no exception clause).
- **Native-alarm sink routing on the equipment path** — fake `IAlarmSource` fires
  `OnAlarmEvent`; assert the equipment tag's condition transitions (Phase B).
- **`HistoryRead` router** — fake `IHistorianDataSource`; assert Raw / Processed /
  AtTime mapping + tagname resolution (default `FullName` and override) (Phase C).
- `IsHistorized` → UA `Historizing` + `AccessLevel.HistoryRead` at materialization
  (Phase C).

**Live docker-dev `/run` (user-driven; the agent does NOT sign in)** — the gate,
given this codebase's documented live-only Razor binding history:
- Author a Galaxy equipment tag via `TagModal` → live value updates.
- Trip a Galaxy alarm → Part 9 condition appears under the equipment + ack
  round-trips (Phase B).
- `HistoryRead` a historized Galaxy tag via Client.CLI `historyread` → samples
  return (Phase C).

## Phasing

1. **Phase A — de-split + AdminUI fold-in** (ws 1 + 4). Galaxy live values +
   scripted alarms work under Equipment; alias machinery deleted. Shippable alone.
2. **Phase B — native alarms on the equipment path** (ws 2). Restores native
   Galaxy alarms in the new model.
3. **Phase C — server-side historian** (ws 3). The additive, driver-agnostic
   `HistoryRead` capability.

Each phase is a mergeable feature branch off master with its own live-verify.
Phase C is the most isolated and largest; if it grows it can split into its own
plan.

## Hard rules (carried into implementation)

- Stage by path; never `git add .`. Never stage `sql_login.txt`,
  `src/Server/ZB.MOM.WW.OtOpcUa.Host/pki/`, or `pending.md`.
- Never echo the gateway API key or the historian `SharedSecret` into a tracked
  file.
- No force-push, no `--no-verify`.
- The `NamespaceKind` removal **does** require a Configuration/EF migration — that
  is in scope for this design (a deliberate exception to the usual "no migration"
  rule).
- Build each phase on a feature branch off master.

## Authoritative touched-code list (for planning)

- `src/Core/ZB.MOM.WW.OtOpcUa.Configuration/Enums/NamespaceKind.cs`
- `src/Core/ZB.MOM.WW.OtOpcUa.Configuration/Entities/Namespace.cs`
- `src/Core/ZB.MOM.WW.OtOpcUa.Configuration/OtOpcUaConfigDbContext.cs` (constraint)
- `src/Core/ZB.MOM.WW.OtOpcUa.Configuration/Migrations/*` (new migration)
- `src/Core/ZB.MOM.WW.OtOpcUa.Configuration/Validation/DraftValidator.cs`
- `src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/DriverTypeRegistry.cs`
- `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Composer.cs`
- `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Applier.cs` (retire MaterialiseGalaxyTags)
- `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs` (native-alarm wiring, IsHistorized attrs, HistoryRead override)
- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DeploymentArtifact.cs`
- `src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs` (extract shared forwarder)
- `src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/Historian/IHistorianDataSource.cs` (server-side history router seam)
- `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware*` (register as server historian backend)
- AdminUI: `Uns/` (`UnsTreeService`, `IUnsTreeService`, alias removal), `Uns/TagEditors/*`,
  `Components/Shared/Drivers/Pickers/GalaxyAddressPickerBody.razor` (keep),
  retire `AliasTagModal`, `RelayConversion*`, `/uns/convert-relays` page.
- Docs: `docs/Uns.md`, `docs/security.md`/driver docs as touched, a new
  `docs/drivers/Galaxy.md` note + `CLAUDE.md` "Alias tags" section rewrite.
```