# Galaxy Alias Tag (UNS) — Design

**Date:** 2026-06-11
**Status:** Approved (brainstorming) — ready for implementation plan
**Author:** design session

## Goal

Let an Equipment node expose a Galaxy attribute under a friendly UNS name as a
**first-class driver-bound tag** — an *alias tag* — instead of a relay
VirtualTag whose script is nothing but `return ctx.GetTag("…").Value;`. The
alias is a normal `Tag` row bound to the Galaxy gateway driver, resolved by a
direct driver subscription, with **no Roslyn script engine** in the path.

## Motivation

The UNS Equipment tree is an Equipment-kind namespace; the Galaxy gateway
mirrors the raw ArchestrA hierarchy into a separate **SystemPlatform**-kind
namespace. A driver instance populates one namespace kind, and
`DraftValidator.ValidateDriverNamespaceCompatibility` forbids a `GalaxyMxGateway`
driver in an Equipment namespace. So the only way today to surface a Galaxy
attribute under an Equipment with a curated name (`speed-rpm` →
`TestMachine_020.TestChangingInt`) is a VirtualTag whose script relays a single
`ctx.GetTag(...)`. The `ctx.GetTag(FullName)` call is the one mechanism that
bridges the two namespace kinds.

Inspecting one rig equipment (`EQ-89e6583eeb9c` / `blender-20`) showed **all 24**
of its tags are exactly this pass-through, with zero computation, on a
driver-less equipment. Across the rig that is ~960 scripts (24 × 40 machines),
each spinning a compiled script that recompiles/evaluates on every input change
just to copy one value — and flattening the source quality/timestamp through the
script engine in the process.

An alias tag removes the script layer entirely: the runtime already materialises
and subscribes equipment driver tags end-to-end (shipped 2026-06-06), and an
alias is functionally identical to a Modbus/S7 equipment tag — the only thing
special is that its driver happens to live in a SystemPlatform namespace.

## Decisions (settled in brainstorming)

1. **Resolution model: independent driver subscription.** The alias is a real
   equipment `Tag` bound to the Galaxy gateway; the runtime subscribes to its
   `FullName` directly. Self-sufficient — works whether or not the raw Galaxy
   SystemPlatform mirror is deployed. The Galaxy `SubscriptionRegistry` dedups by
   reference, so MXAccess sees a single subscription if the mirror also exists.
2. **Write semantics: configurable per alias, default read-only.** Alias carries
   an `AccessLevel` like any tag; defaults `ReadOnly`, can be set writable.
   Write-through flows through the Galaxy `IGalaxyDataWriter`, gated by the
   existing `SecurityClassification` (FreeAccess/Operate/Tune/Configure) **and**
   the OPC UA NodeAcl on the equipment node.
3. **Convert existing relays.** Ship a converter that detects pure-relay
   VirtualTags and rewrites each as an alias `Tag`, removing the script + vtag.
4. **Authoring on the Tags tab.** An alias is an equipment tag bound to Galaxy,
   so it lives on the equipment page's existing **Tags** tab; an "Add alias"
   action opens the existing Galaxy live-browse picker. Aliases and native tags
   coexist in one list.
5. **Approach A — reuse the `Tag` entity; broaden the equipment-tag path.** No
   new entity, **no EF migration**. "Alias-ness" is simply "an equipment tag
   bound to a SystemPlatform (Galaxy) driver."

## Approach (chosen) vs alternatives

- **A — Reuse `Tag`, broaden the equipment-tag filter (CHOSEN).** Smallest
  change; rides the proven equipment-tag composer/artifact/runtime/materialise
  rails; honours the no-migration constraint; the converter becomes a straight
  "rewrite relay VirtualTag rows as Tag rows" transform.
- **B — New `AliasTag` entity + table.** Conceptually tidy but requires a
  migration and duplicates the entire equipment-tag machinery (composer,
  artifact, runtime, materialise, converter) for a near-identical row. More code,
  more risk, no functional gain. Rejected.
- **C — OPC UA pointer/redirect to a mirror node.** Rejected by decision #1 —
  it would force the raw mirror to be deployed and is trickier in the node
  manager. Listed for completeness.

## Gate inventory (what blocks an equipment-scoped Galaxy tag today)

Verified against the code:

1. **`Phase7Composer.equipmentTags` filter** requires the tag's driver namespace
   be `NamespaceKind.Equipment` → a Galaxy-backed equipment tag is silently
   dropped. **Must broaden.**
2. **`DeploymentArtifact.BuildEquipmentTagPlans`** mirrors that filter →
   changes in lockstep (an existing byte-parity test guards the pair).
3. **AdminUI** offers only Equipment-namespace drivers when adding an equipment
   tag → needs the "Add alias → Galaxy picker" path.
4. **NOT blocked:** `DraftValidator.ValidateDriverNamespaceCompatibility` checks
   the driver's *home* namespace (still SystemPlatform — unaffected); and
   `sp_ValidateDraft` has no tag-level namespace-kind invariant. The
   "`EquipmentId` required ⟺ Equipment-kind driver" line in `Tag.cs` is a doc
   convention, not enforced — it is reframed (below).

## Architecture

### 1. Data model & the core composer/artifact change

An alias is an ordinary `Tag` row (no new entity, no migration):

| Column | Value |
|---|---|
| `EquipmentId` | owning equipment (e.g. `EQ-89e6583eeb9c`) |
| `DriverInstanceId` | the Galaxy gateway (`MAIN-galaxy-mxgw`) |
| `Name` | friendly UNS leaf (`speed-rpm`) |
| `DataType` | OPC UA type (`Int32`), operator-set, matches the Galaxy attribute |
| `AccessLevel` | per-alias, default `ReadOnly` |
| `FolderPath` | `null` (alias hangs directly under the equipment) |
| `TagConfig` | `{"FullName":"TestMachine_020.TestChangingInt"}` |

`TagConfig.FullName` is exactly what `Phase7Composer.ExtractTagFullName` already
reads for equipment tags — so the wire-reference plumbing is zero-new-code.

**Structural change (two byte-parity-locked places):**
- `Phase7Composer.cs` `equipmentTags`: predicate becomes
  `ns.Kind == NamespaceKind.Equipment || di.DriverType == "GalaxyMxGateway"`.
- `DeploymentArtifact.BuildEquipmentTagPlans`: the identical broadening; the
  existing parity test is extended with an alias row.

Everything downstream is reused unchanged: `Phase7Applier` materialises the
variable under the equipment folder; the runtime subscribes by
`DriverInstanceId` + `FullName` on the Galaxy driver. The SystemPlatform mirror
filter (`EquipmentId == null`) is untouched, so the 396 raw mirror tags are
unaffected.

**Convention reframe (doc-only):** the `Tag.cs` comment becomes "`EquipmentId`
set ⟺ the tag participates in the Equipment tree, regardless of the driver's
namespace kind; a Galaxy-gateway-bound equipment tag is an **alias**."

### 2. Validation, authorization & write-through

- **Validation:** add one positive `DraftValidator` check — an equipment tag
  bound to `GalaxyMxGateway` must carry a non-empty `TagConfig.FullName`
  (otherwise it subscribes to nothing). No gate is needed to *permit* aliases.
- **Authz layer 1 (OPC UA permission):** the alias lives in the Equipment-kind
  namespace → governed by **NodeAcl** like any equipment tag
  (`ReadOnly`/`WriteOperate`/`WriteTune`/`WriteConfigure` per `NodeScope`).
- **Authz layer 2 (write-through):** a write that passes layer 1 flows through
  the equipment-tag write path to the Galaxy `IGalaxyDataWriter`, which routes by
  the Galaxy attribute's `SecurityClassification`. A writable alias is gated by
  **both** — exactly like writing the raw Galaxy tag, reached via the UNS name.
- **Default & opt-in:** `AccessLevel` defaults `ReadOnly`; writable is explicit.
- **Quality/timestamp bonus:** the value comes straight off the driver
  subscription, so the alias carries the MXAccess quality + source timestamp
  natively (the relay flattened those through the script engine).
- **Edge — cluster alignment:** the alias is hosted/subscribed on the Galaxy
  driver's cluster; the driver-less equipment is attributed by its UNS line's
  cluster. They must resolve to the same cluster (the existing same-cluster
  namespace-binding SQL check keeps a driver and its namespace aligned).
  Cross-cluster alias is out of scope — documented guardrail, not built.

### 3. AdminUI authoring (Tags tab)

- **Entry point:** the equipment page **Tags** tab gains **+ Add alias (browse
  Galaxy)** beside *+ Add tag*; disabled with a hint when the equipment's cluster
  has no `GalaxyMxGateway` driver.
- **Alias modal** — a focused sibling of `TagModal` (same pattern as
  `ScriptedAlarmModal`; avoids overloading `TagModal`'s driver-typed editor
  dispatch):
  - **Galaxy driver resolution** — from the equipment's pick-context, find
    `GalaxyMxGateway` driver(s) in its cluster. One → auto-bind; several →
    select; none → action disabled.
  - **Live-browse pick** — embeds the existing
    `GalaxyAddressPickerBody`/`DriverTagPicker` pointed at that gateway; operator
    drills the live Galaxy hierarchy, picks an attribute → fills `FullName` and
    suggests `DataType` from the attribute's `mx_data_type`.
  - **Fields** — `Name` (UNS leaf; existing equipment signal-name
    uniqueness/regex applies), `DataType` (defaulted, editable), `AccessLevel`
    (default `ReadOnly`).
  - **Save** — assembles `TagConfig = {"FullName": …}` and writes a `Tag` row.
- **Service layer:** thin `CreateAliasTagAsync` / `UpdateAliasTagAsync` on
  `IUnsTreeService` that assemble the `TagConfig` and reuse the existing
  equipment-tag name-uniqueness guard; **delete reuses `DeleteTagAsync`**.
  `LoadTagsForEquipmentAsync` gains a derived **Source** field.
- **Display:** an alias row shows an **"alias" badge** and a **Source** column
  `galaxy: <FullName>`; native driver tags render their driver/register as today.

### 4. Relay → alias converter

- **Detection (conservative):** convertible only when the bound `Script` body is
  exactly a single relay return (modulo whitespace):
  `^\s*return\s+ctx\.GetTag\(\s*"([^"]+)"\s*\)\s*\.Value\s*;\s*$`. Anything with
  extra statements, conditionals, arithmetic, or multiple `GetTag` calls is left
  untouched. Ref extraction reuses the Commons `EquipmentScriptPaths` GetTag
  helper.
- **`{{equip}}` expansion:** if the ref contains the reserved token, expand it
  per-equipment via `DeriveEquipmentBase`/`SubstituteEquipmentToken`; the shared
  `Script` is deleted only after its last referencing VirtualTag is converted.
- **Safety guards (skip + report, never silently drop):** shared script still in
  use → drop vtag, keep script; `Historize = true` → skip (Tag has no historize
  column); no Galaxy gateway in the cluster → skip; non-relay body → skip.
- **Field carry-over:** alias `Name` = vtag `Name`; `DataType` = vtag `DataType`;
  `AccessLevel` = `ReadOnly`. `ChangeTriggered`/`TimerIntervalMs` dropped (the
  subscription replaces them).
- **Atomicity:** each conversion does delete-VirtualTag-(+orphan-Script)-and-
  insert-alias-Tag as one unit so a same-named alias and vtag never coexist (the
  equipment signal-name collision check stays satisfied).
- **Invocation:** one method `ConvertRelayVirtualTagsToAliasesAsync(scope,
  dryRun)`, **FleetAdmin-gated**, operating on the **draft** generation (never
  bypasses publish). Exposed two ways sharing that method: **per-equipment**
  (Tags tab) and **fleet-wide** (a maintenance entry). Both run **dry-run preview
  first** (convertible refs + every skip with reason), then **confirm-apply**.
  Touches only existing entities (`Tag` insert, `VirtualTag`/`Script` delete) —
  **no migration**.

## Net service / type surface (no schema change)

New on `IUnsTreeService`: `CreateAliasTagAsync`, `UpdateAliasTagAsync`,
`ConvertRelayVirtualTagsToAliasesAsync(scope, dryRun)`; `LoadTagsForEquipmentAsync`
gains a derived Source/alias field. New AdminUI types: an alias input DTO + a
converter preview/result DTO. New component: `AliasTagModal.razor` (+ reuse of
`GalaxyAddressPickerBody`/`DriverTagPicker`). One positive `DraftValidator` check.
Composer + artifact filter broadening (byte-parity pair).

**No Configuration entity change and no EF migration** — an alias is a `Tag`
row; the converter only inserts `Tag` rows and deletes `VirtualTag`/`Script`
rows.

## Testing

No bUnit — service/composer logic unit-tested; Razor proven live.

- **Composer/artifact:** a Galaxy-bound equipment tag now lands in
  `equipmentTags`; a SystemPlatform mirror tag (`EquipmentId == null`) still does
  not; `DeploymentArtifact` byte-parity extended with an alias row.
- **DraftValidator:** alias missing `TagConfig.FullName` → the new error;
  well-formed alias → clean; `ValidateDriverNamespaceCompatibility` still passes.
- **Service (in-memory EF):** `CreateAliasTagAsync` writes the expected row;
  signal-name collision rejected; `LoadTagsForEquipmentAsync` surfaces Source;
  delete via `DeleteTagAsync`.
- **Converter (in-memory EF):** exact relay → converted (ref/name/DataType
  carried, vtag + orphan script removed); non-relay bodies → untouched; shared
  script kept while referenced, deleted on last consumer; `Historize=true` →
  skipped+reported; no-gateway → skipped+reported; `{{equip}}` → expanded
  per-equipment; dry-run mutates nothing; apply atomic.
- **Live docker-dev `/run`** (user drives; agent does **not** sign in): create an
  alias on `blender-20` via the Galaxy picker → publish → read it live via
  Client.CLI (value + quality + timestamp); flip writable → write-through changes
  the Galaxy attribute, read-only rejects writes; converter dry-run on
  `blender-20` previews 24 → apply → 24 relays become alias Tags → values still
  live, no script-log entries for them.

**Done gate:** solution builds clean + `dotnet test` green + live `/run` pass.

## Error handling / edge cases

- **Unresolvable `FullName`** (typo, object not deployed) — the Galaxy
  subscription returns Bad; the alias node publishes Bad quality and recovers if
  the object appears. Same degrade as the relay's `BadNodeIdUnknown`; validation
  only checks non-empty (existence is a runtime concern).
- **Underlying Galaxy object renamed/deleted** — alias goes Bad at runtime; no
  config-time coupling (it holds a `FullName` string).
- **Gateway down** — alias quality goes Bad/uncertain like any Galaxy tag;
  recovers on reconnect.
- **Cluster alignment** — the Section-2 guardrail; cross-cluster out of scope.

## Docs

- `docs/Uns.md` — alias tags on the Tags tab + the converter (per-equipment and
  fleet-wide).
- `CLAUDE.md` — a short note near the Galaxy / contained-name-vs-tag-name concept.
- A pointer wherever equipment tags are described.

## Guardrails

Feature branch off master; stage by explicit path (never `git add .`); never
stage `sql_login.txt` or `src/Server/ZB.MOM.WW.OtOpcUa.Host/pki/`; never echo the
gateway API key into a new tracked file; no force-push; no `--no-verify`; **no
Configuration entity or EF migration change**.