# UNS — Global Unified-Namespace Management

The **UNS** page (`/uns` in the AdminUI) is the single surface for managing
the Unified Namespace across the whole fleet. It replaces the old
per-cluster **UNS**, **Equipment**, and **Tags** tabs and the standalone
virtual-tags list — those have been removed; everything now lives in one
global master tree.

## The tree

The page shows every layer of the UNS as one expandable tree. Equipment is a
**leaf** in the tree — tags, virtual tags, and alarms live on a dedicated
equipment page, not inline:

```
Enterprise            (read-only grouping — ServerCluster.Enterprise)
└─ Site / Cluster     (read-only grouping — a ServerCluster row)
   └─ Area            (editable — UnsArea)
      └─ Line         (editable — UnsLine)
         └─ Equipment (leaf — Equipment; opens its own page)
```

**Enterprise and Site/Cluster can be deleted from the tree** (see
[Cluster and Enterprise delete](#cluster-and-enterprise-delete) below).
Other than deletion, they are configured on the **Clusters** pages
(`/clusters`) — on a cluster row the **⚙ settings** link jumps to that
cluster. Editable UNS entities start at **Area**.

Count badges next to a node show how many direct children it has (for
equipment, the combined tag + virtual-tag count).

### Navigating

- **Expand all / Collapse all** toggle the structural levels.
- **Filter by name** does a case-insensitive substring match on the names of
  a node's direct children.

## Creating and editing

Every editable row has inline actions:

| Node | Actions |
|---|---|
| Cluster | **+ Area**, Delete |
| Area | **+ Line**, Edit, Delete |
| Line | **+ Equipment**, Edit, Delete |
| Equipment | **Open**, Delete |

A **+ Child** action pre-fills the parent for you (e.g. **+ Line** on an
area opens the Line modal with that area already selected). Build a branch
top-down: Area → Line → Equipment. Tags, virtual tags, and scripted alarms
are managed on the equipment page (see below).

### Naming: area, line and equipment names are UNS path segments

An area, line or equipment **name** becomes a level of the OPC UA NodeId
(`Area/Line/Equipment/EffectiveName`), so it must match
**`^[a-z0-9-]{1,32}$`** — lowercase letters, digits and dashes, 1–32
characters. The reserved `_default` is also accepted. `Packaging` and
`Line 1` are not valid; `packaging` and `line-1` are.

**Ids are a different thing and a different rule.** `UnsAreaId` /
`UnsLineId` are opaque handles that never reach a NodeId, so they take
`^[A-Za-z0-9_-]+$` — `SITEA-area1` is a fine id for an area named
`packaging`.

The rule is enforced in `UnsTreeService` on **every** authoring path —
create, rename, and the CSV import — and again at the deploy gate
(`UnsSegmentInvalid`). Both call the same `UnsSegment` helper, so they
cannot disagree.

⚠️ **Why it is enforced at authoring and not only at deploy (Gitea #535):**
until 2026-08-01 only the equipment form checked it, so an area or line
could be named `Packaging`, save cleanly, and fail the *next deployment* —
and because a deployment snapshots the **whole database**, one badly-named
area blocked **every** cluster's deploy, usually discovered by someone other
than whoever typed it. In the CSV import a bad name is reported as an
**error**, not a skip: a skip means "you already have this row", which would
say the equipment exists when it does not.

## Equipment page (`/uns/equipment/{id}`)

Clicking **Open** on an Equipment row (or **+ Equipment** on a Line) navigates
to the equipment page. The page is organised into four tabs:

| Tab | Content |
|---|---|
| **Details** | Equipment identity — name, description, OPC-40010 namespace fields, driver binding, and served-by cluster. (This is the former EquipmentModal, now a full page.) |
| **Tags** | Equipment-bound driver tags. Each tag uses the driver-typed config editor (same editors as before — Modbus, S7, AB CIP, etc.) with the same client-side validation. |
| **Virtual Tags** | Virtual tags driven by C# scripts. The inline Monaco script editor with Roslyn IntelliSense, completions, and live diagnostics is available here per tag. |
| **Alarms** | Scripted-alarm definitions bound to this equipment. Create, edit, or delete predicates here; the Monaco editor is available for each predicate script. |

**"Add equipment"** under a Line uses the URL `/uns/equipment/new?lineId=...`,
pre-filling the parent line. Saving redirects to the new equipment's page.

### Served-by cluster

An area's **cluster assignment is its "served-by" cluster** — the cluster
node that runs it. It's set when you create the area (under a cluster) and
changed by editing the area's cluster in the Area modal, which moves the
whole branch. There is no separate "served-by" concept and no migration —
it is simply `UnsArea.ClusterId`.

### Tags — reference-only (v3)

> **v3 (Batch 3):** UNS equipment no longer authors or binds tags. Device I/O is
> authored once in the **Raw project tree** (`/raw` — see [`Raw.md`](Raw.md)); an
> equipment's **Tags** tab holds **references** to those raw tags. The old
> driver-bound Tag modal on this tab is retired.

The **Tags** tab is a list of `UnsTagReference` rows. Each row shows the
**effective name**, the backing tag's **RawPath**, its inherited **DataType** and
**AccessLevel** (read-only — they come from the raw tag), and an editable
**display-name override**. The effective name is the override else the raw tag's
`Name`.

**"+ Add reference"** opens a raw-tree picker (the `/raw` tree in picker mode)
**scoped to the equipment's cluster** — cross-cluster tags are structurally
unreachable, and the service also enforces `tag.cluster == equipment.cluster` on
commit. Tick individual tag leaves, or use a device / tag-group's *"Select all
tags below"* menu to pull many at once.

**Effective-name uniqueness:** within an equipment the effective name must be
unique across references, VirtualTags, and ScriptedAlarms (they share the
equipment's UNS NodeId space, `{EquipmentId}/{EffectiveName}`). This is enforced
both at authoring (a readable rejection naming the colliding source) and at the
deploy gate (`DraftValidator`, `UnsEffectiveNameCollision`) — the deploy gate is
what catches **rename-induced** collisions a raw rename produced after the
reference was authored, naming both colliding sources and the equipment.

Removing a raw tag in `/raw` is blocked while a `UnsTagReference` points at it
(the error names the referencing equipment); renaming a raw tag or any ancestor
warns when a beneath-it tag is historized (no `historianTagname` override),
UNS-referenced, or named by a script literal — see [`Raw.md`](Raw.md).

**Galaxy / AVEVA System Platform points** are now ordinary raw tags on a
`GalaxyMxGateway` driver in `/raw`, referenced into equipment like any other raw
tag. There is no separate alias concept or `SystemPlatform`-kind namespace.

### OPC UA address-space projection (v3 Batch 4 — dual namespace)

> **v3 (Batch 4):** the server now exposes the address space under **two OPC UA
> namespaces** instead of the old single `https://zb.com/otopcua/ns`:
>
> | Namespace URI | Subtree | NodeId `s=` scheme |
> |---|---|---|
> | `https://zb.com/otopcua/raw` | the `/raw` device tree (Folder → Driver → Device → TagGroup → Tag) | the node's **RawPath** (e.g. `Plant/Modbus/dev1/Speed`) |
> | `https://zb.com/otopcua/uns` | the UNS tree (Area → Line → Equipment → signal) | the slash-joined **`Area/Line/Equipment/EffectiveName`** |

Every device value has **exactly one source** — the raw tag's node in the Raw
namespace. A `UnsTagReference` projects that raw tag into an equipment as a
**UNS-namespace variable** whose NodeId leaf is the reference's **effective name**
(the display-name override else the raw tag's `Name`). The UNS variable does not
bind a driver of its own: it carries an **`Organizes` reference to its backing raw
node** and mirrors it. A single driver publish for a RawPath **fans out** to the
raw NodeId AND every referencing UNS NodeId with identical value / quality /
source-timestamp — the two NodeIds never drift.

- **Reads / subscriptions** work through either NodeId and return the same data.
- **Writes** route through either NodeId to the same backing driver ref under the
  **same `WriteOperate` gating** (a UNS write is neither more nor less privileged
  than the raw write it fans from); a failed device write reverts both NodeIds via
  the shared fan-out.
- **HistoryRead** works through either NodeId and returns the same series — both
  NodeIds register the **same historian tagname** (see [`Historian.md`](Historian.md)).
- **Native alarms** materialize once at the raw tag (`ConditionId = RawPath`) and
  fan via SDK notifiers to the raw device folder AND every referencing equipment
  folder — see [`ScriptedAlarms.md`](ScriptedAlarms.md) / [`AlarmTracking.md`](AlarmTracking.md).

Note the two distinct identity strings: the wire **NodeId** is the path
`Area/Line/Equipment/EffectiveName`, while the **effective-name uniqueness key**
above is `{EquipmentId}/{EffectiveName}` (the logical per-equipment collision
space the guards enforce). They are related but not the same string.

### Virtual tags

A virtual tag is bound to an equipment and driven by a **script** (no driver).
Add and edit virtual tags on the equipment page's **Virtual Tags** tab; the
data type is chosen from the standard OPC UA type list and the Monaco script
editor is available inline. Scripts may read the equipment's references
relative-to-equipment with **`ctx.GetTag("{{equip}}/<RefName>")`** — the token
resolves through the equipment's `UnsTagReference` rows (by effective name) to
the backing raw tag's RawPath at deploy; an unresolved `<RefName>` is a deploy
error and a live Monaco diagnostic (editor accepts ⇔ publish accepts). See
[`ScriptEditor.md`](ScriptEditor.md).

### Galaxy tags

`GalaxyMxGateway` is an **Equipment-kind driver** — Galaxy points are ordinary
equipment tags authored through the standard Tag modal, exactly like Modbus or
S7 tags. The Galaxy reference is stored as `TagConfig.FullName`
(`tag_name.AttributeName`). The Galaxy address picker on the Tags tab lets you
browse the live Galaxy hierarchy to select an attribute; after selecting, set
the tag **Name**, **DataType**, and **AccessLevel** (default: read-only). There
is no alias concept, no `SystemPlatform`-kind namespace, and no relay→alias
converter.

## Typed TagConfig editors

The **Tag modal** dispatches a driver-typed config editor for the following
drivers:

| Driver | Fields in the typed editor |
|---|---|
| Modbus | Register type, address, data type, word order, etc. |
| S7 | Data block, offset, data type, etc. |
| AB CIP | Tag path, data type, etc. |
| AB Legacy (DF1/DH+) | Address, data type, etc. |
| TwinCAT | Symbol path, data type, etc. |
| FOCAS | PMC address, data type, etc. |
| **OpcUaClient** | `FullName` (the remote OPC UA node id string) |

**OpcUaClient** was previously raw-JSON fallback only; it now has a first-class
typed editor that exposes a single `FullName` field (PascalCase JSON key,
consistent with the Galaxy editor convention). It is registered in
`TagConfigEditorMap` and `TagConfigValidator`; unknown keys in the stored JSON
blob are preserved on round-trip.

> The historian backend is the external HistorianGateway (no OtOpcUa-side tag
> driver / tag-config editor). See [Historian.md](Historian.md).

Drivers not yet listed above (e.g. Galaxy — which uses the Galaxy address
picker described below) still use the generic raw-`TagConfig`-JSON textarea.

### "Build address" pickers in protocol-driver editors

The **Modbus, S7, AB CIP, AB Legacy, TwinCAT, and FOCAS** typed editors
include a **Build address** button. Clicking it opens the driver's existing
address-builder UI inside the shared `DriverTagPicker` overlay; confirming a
selection writes the fully constructed address string back into the editor's
address field. This means you can visually compose a register reference
(e.g. select "Holding Register → 100 → Int16") and have it serialised into
the correct JSON without hand-editing.

## Historizing tags (first-class controls)

The Tag modal exposes **Historize this tag** and **Historian tagname
(override)** as explicit controls that work for **all drivers** — including
protocol drivers (Modbus, S7, etc.) that use the typed editor and raw-JSON
drivers (Galaxy) alike.

| Control | JSON key | Type | Behaviour |
|---|---|---|---|
| **Historize this tag** checkbox | `isHistorized` | bool | When checked, the OPC UA node materialises with `Historizing=true` and the `HistoryRead` AccessLevel bit set. |
| **Historian tagname (override)** textbox | `historianTagname` | string (optional) | Explicit tagname the historian backend will query. When left blank, the server defaults to the tag's driver `FullName`. |

These fields are merged into the `TagConfig` JSON blob via the pure
`TagHistorizeConfig` helper, which preserves all other keys byte-stable.
The server's OPC UA HistoryRead dispatch already consumes these keys from the
`TagConfig` blob — see [Historian.md](Historian.md) for the full server
behaviour, continuation-point paging, and aggregates.

> **Note — native-alarm `HistorizeToAveva`:** a tag that carries a native
> `"alarm"` object has a **separate** opt-out field `alarm.historizeToAveva`
> (a checkbox labelled "Historize to AVEVA" on the Tag modal's alarm section).
> That field controls whether the alarm's **transition events** are written to
> the AVEVA historian — it does not affect tag-value history (which is
> controlled by `isHistorized`). See [ScriptedAlarms.md §Native driver
> alarms](ScriptedAlarms.md#native-driver-alarms-equipment-tag-path) for
> details.

## Array tags (1-D)

A tag can be made a **1-D OPC UA array node** by setting two keys in its `TagConfig`
JSON blob.  The controls are exposed as first-class UI fields in the Tag modal (an
**Is array** checkbox + an **Array length** numeric input), available for all drivers
— typed editors (Modbus, S7, etc.) and the raw-JSON textarea (Galaxy) alike.

### Canonical rule

| Condition | OPC UA node shape |
|---|---|
| `isArray: true` AND `arrayLength >= 1` | 1-D array node (`ValueRank = OneDimension`, `ArrayDimensions = [arrayLength]`) |
| `isArray: false` (any `arrayLength`) | Scalar node (default) |
| `isArray` absent | Scalar node (default) |

A single-element array (`isArray: true, arrayLength: 1`) is valid and materialises as a
`[1]` node.

### Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `isArray` | bool | no | When `true` (and `arrayLength >= 1`), makes the node a 1-D array. Absent or `false` → scalar. |
| `arrayLength` | uint (≥ 1) | when `isArray: true` | The element count for the OPC UA `ArrayDimensions` declaration. Must be ≥ 1 when `isArray` is set. |

UI validation rejects `arrayLength = 0` when `isArray` is checked.

### Examples

```json
{"FullName":"PLC1.TemperatureArray","isArray":true,"arrayLength":10}
```

```json
{"Register":"HR100","DataType":"Float32","isArray":true,"arrayLength":5}
```

Combined with historization (values are arrays — history of the whole array snapshot):

```json
{"Register":"HR200","DataType":"Int16","isArray":true,"arrayLength":20,"isHistorized":true}
```

### Per-driver read mechanism and live-verify status

| Driver | Read mechanism | Live-verify |
|---|---|---|
| **Modbus** | Contiguous FC03/FC04 block (`arrayLength × registers-per-element`); String and BitInRegister array modes also supported | Mac-verifiable (sim `10.100.0.35:5020`) |
| **S7** | Contiguous `ReadBytesAsync` block over the declared address span + per-element decode loop | Unit-proven (sim fixture down) |
| **AB CIP** | libplctag native array read (atomic and UDT member arrays) | Unit-proven (sim fixture down) |
| **AB Legacy** | PCCC multi-element file read via libplctag (cap 256 elements) | Unit-proven (sim fixture down) |
| **TwinCAT** | Raw-bytes read of the declared `SymbolPath` at the resolved array type's layout + per-element decode; native ADS notifications carry the whole array (same decode). Multi-dim PLC arrays publish flattened; a shorter `arrayLength` reads the leading sub-range | Live-verified 2026-10-07 on two TwinCAT 2.11 PLCs (see [TwinCAT.md §Array tags](drivers/TwinCAT.md#array-tags)) |

### Array writes (#610)

An authored-`ReadWrite` array tag is **writable only when its driver can write that array** —
the server never advertises a write the driver will refuse. The capability is one table,
`DriverArrayWriteSupport` (`Core.Abstractions`), consulted by the composer at compose time and
carried on the plan records (`RawTagPlan.ArrayWritable`, mirrored onto every UNS reference as
`UnsReferenceVariable.BackingArrayWritable`); the node is writable iff
`Writable && (!IsArray || ArrayWritable)`, on the raw node and every UNS mirror alike.

| Driver | Array writes | Element types |
|---|---|---|
| **Modbus** | Yes | `region: Coils` (FC15, any element, ≤ 1968 coils); `region: HoldingRegisters` with `Int16`/`UInt16`/`Bcd16`/`Int32`/`UInt32`/`Bcd32`/`Float32`/`Int64`/`UInt64`/`Float64` (FC16) whose `arrayLength × registers-per-element` fits `maxRegistersPerWrite` (default 123; the smallest value set on the driver or the tag's device wins) — the driver refuses rather than splits an over-cap FC16, so e.g. a 62-element `Int32` array (124 registers) stays read-only. Not BitInRegister / String / Bool-in-register; input regions are read-only |
| **S7** | Yes | `Byte`/`Int16`/`UInt16`/`Int32`/`UInt32`/`Float32` (one contiguous block). Not `Bool` (would clobber neighbouring bits) nor the wide / String / DateTime types |
| **OpcUaClient** | Yes | All — forwarded upstream unchanged; the upstream server decides (shape included) |
| **Galaxy** | Yes | OPC UA `Boolean`/`Int32`/`Int64`/`Float`/`Double`/`String`/`DateTime` (the `MxValueEncoder` array variants) — **only with a declared `arrayLength`**: an undeclared length materialises an unbounded node, and a short whole-array write would *resize* the Galaxy attribute (mxaccessgw contract), so such a node stays read-only |
| **AB CIP** | Yes (#737) | `SInt`/`USInt`/`Int`/`UInt`/`DInt`/`UDInt`/`Real`/`Dt`/`LInt`/`ULInt`/`LReal` (`AbCipArrayCodec`, both transports). Not `Bool` (bit-packed DWORDs), `String` or `Structure`, nor a `safetyTag` |
| **AB Legacy** | Yes (#738) | `Int`/`AnalogInt` on an N/B/A file, `Long` on an L file, `Float` on an F file — the encode width is the data file's, so a type that does not match its file stays read-only — on a plain `<file><number>:<word>` address, ≤ 256 elements. Not Bit / String / Timer / Counter / Control arrays, `/bit` or `.sub` addresses, indirect addresses, the `S:`/`I:`/`O:` files, nor any PLC-5 on the native transport |
| **TwinCAT** | Yes (#739) | Every element type `TwinCATArrayCodec` lays out (numeric, `Bool`, `String`/`WString`, temporal); multi-dimensional PLC arrays are written row-major from the flat value. Not a BOOL bit-in-word path (`MAIN.Word.3`) |
| FOCAS, MQTT, MTConnect, Sql, Calculation | **No** — scalar-only write encoders; array nodes stay read-only and a client write is `BadNotWritable` | — |

Every "Yes" driver but OpcUaClient additionally needs a **declared length** — `isArray: true` *and* an
integer `arrayLength >= 1`. The tag factories read anything else as a **scalar** tag (whose scalar
encoder cannot take an array), even though the composer still materialises an array node; that node
stays read-only.

**Elements convert; they are not exact-matched.** ScadaBridge writes CLR `int[]` / `List<int>` to Int16
nodes: the node manager converts a numeric array to the node's element type, and the AB CIP, AB Legacy
and TwinCAT encoders convert each element again to the controller's type (an element that does not fit
is `BadOutOfRange`). Those rows therefore do not key on an exact node `DataType`; they leave out only
node types whose elements never convert — a `DateTime` or `String` node over a numeric element, and a
`Boolean` node on AB Legacy. An array tag deployed read-only before its driver gained an encoder turns
writable on the next deploy (a surgical `ArrayWritable` update, no rebuild).

Each "Yes" row is pinned against the driver's real encoder by a parity test in that driver's
test project (`*ArrayWriteSupportParityTests`), so a driver gaining or losing an array encoder
fails a test until the table follows.

What a client sees on a writable array node:

- **Whole-array writes only.** The value must be a 1-D array of exactly `arrayLength` elements
  (an unbounded `arrayLength`/`ArrayDimensions = [0]` takes any length — reachable only on
  OpcUaClient); anything else is `BadTypeMismatch`, refused inline before dispatch.
- **The element type must match the node's DataType, or be a numeric type that converts to it
  exactly.** A matching element type (or a `Byte` array, which arrives as a ByteString) is dispatched
  as written. A **numeric** array of another numeric element type is **converted, checked, element by
  element** into the node's element type, and the converted array is what the node stores and the
  driver receives — an `Int32[]` written to an `Int16` array reaches the driver as `short[]`. The whole
  write is refused `BadTypeMismatch` inline, nothing dispatched, if **any** element is out of the
  target's range, fractional for an integer node (`1.5` → `Int16` refused; `2.0` → `2`), NaN/±∞ for an
  integer node, or finite but beyond `Float` range for a `Float` node. Every **non-numeric** mismatch
  (`Boolean[]` → `Int32`, `Int32[]` → `String`, a `Variant[]`) is refused. This is the check the OPC UA
  SDK would normally make itself: it skips its own type check on any node with an `OnWriteValue`
  handler, which every writable equipment node has, so the node manager makes it instead. Without it a
  `UInt32[]` reached Galaxy's `int[]` encoder by CLR array covariance and was written bit-reinterpreted
  (4,000,000,000 → −294,967,296) with a Good result — that write is still refused (4,000,000,000
  overflows `Int32`), while an in-range `UInt32[]` converts. The conversion is required, not a
  nicety: ScadaBridge writes the CLR list it decoded from a `List` attribute, and its element types are
  only Boolean/Int32/Float/Double/String/DateTime, so an exact-match rule left every `Int16`/`UInt16`/
  `Byte`/`UInt32`/`Int64`/`UInt64` array node (Modbus's default `Int16` included) and a `Double` list to
  a `Float` array unwritable from it. **Scalar** writes keep their looser rule — any numeric to any
  numeric node, unconverted — because every driver's scalar encoder converts with a range check, so an
  out-of-range scalar fails the device write and is reverted.
- An **array value to a scalar node** is refused `BadTypeMismatch` inline **only on Modbus and S7**,
  whose scalar encoders cannot take one (`DriverArrayWriteSupport.RefusesArrayValueOnScalarTag`). Every
  other driver keeps the pre-#610 behaviour — the write is dispatched and the driver decides. That
  matters for browse-committed tags: the `/raw` commit sets the DataType but never `isArray`, so an
  upstream array variable (OpcUaClient) or a Galaxy array attribute committed from the browser is a
  **scalar** node into which the driver publishes an array, and writing that array back still works
  (OpcUaClient forwards it to the upstream server, which arbitrates the shape; Galaxy encodes it). Set
  `isArray` + `arrayLength` on such a tag to get the array-node checks above.
- A partial **IndexRange** write is
  `BadWriteNotSupported` — every array-capable driver writes the whole block, and the server
  does not hold the device array authoritatively enough to read-modify-write it.
- The same realm-qualified `WriteOperate` / ACL gate as a scalar applies to both NodeIds, and a
  device-refused array write is reverted on the NodeId it was written through (the scalar
  write-outcome self-correction, unchanged).
- Flipping a tag's array-write capability (a driver-type or element-type edit on an existing
  array tag) is a **surgical** in-place writability update, not a rebuild: `ArrayWritable` is on
  the classifier's raw-tag whitelist, and the mirrors repair through `BackingArrayWritable`. A
  change to the array-on-scalar refusal (`ScalarRefusesArrayValue` — only a driver-type edit can flip
  it) is deliberately NOT whitelisted and rebuilds.

> ⚠️ **Upgrade note — array tags become client-writable without a deploy.** Before #610 every
> array node was read-only regardless of its authored `AccessLevel`. On the first boot after
> upgrading, every array tag **authored `ReadWrite`** on Modbus, S7, OpcUaClient or Galaxy whose
> shape the table above accepts is materialised **writable** — no deployment needed, since the
> capability is derived at compose time (a `FetchAndCache` node re-composes from its cached
> artifact). Any client holding `WriteOperate` (or, with `Security:Acl:Enabled`, a `WriteOperate`
> grant covering the tag) can then write whole PLC arrays. Before upgrading, audit array tags
> authored `ReadWrite` that were never meant to be written and set them `Read`; array tags on the
> other drivers are unaffected.

### Out of scope (named deferrals)

- **Multi-dimensional arrays** (`ValueRank > 1`) — **out of scope by decision** (#610 item 3),
  not merely deferred. Every driver's array read decodes a flat 1-D block (TwinCAT already
  publishes multi-dim PLC arrays flattened), and the node manager materialises every array
  `ValueRank = OneDimension` with a single `ArrayDimensions` entry. Supporting rank > 1 would
  need per-rank dimensions in TagConfig, the plan records, the classifier whitelist, the node
  manager and every driver's decode/encode, and no consumer has asked for it. Author a
  multi-dimensional PLC array as a flat 1-D tag (row-major), or as several 1-D tags.
- **Array historization** — a historized array tag materialises with the correct `Historizing` flag, but the historian backend treats the value as an opaque blob; per-element history is out of scope. (Continuous historization is numeric-analog only — array / non-numeric values are not recorded.)

See the individual driver docs under `docs/drivers/` for per-driver implementation details.

## Writable equipment tags (`writable` key)

An equipment tag is **writable by default** — the materialised OPC UA node is created
`CurrentReadWrite` and inbound client writes are routed to the device (subject to the
`WriteOperate` gate — a role the session's API-key principal earns from its `NodeAcl` grants, see
[security.md](security.md)). Setting the optional `"writable": false` key in a tag's
`TagConfig` makes the node **read-only** at the driver seam. The six typed tag editors
(Modbus, S7, AB CIP, AB Legacy, TwinCAT, FOCAS) expose this as a **Writable** checkbox
(checked by default); it can also be hand-authored in the raw-JSON textarea.

| Condition | Node |
|---|---|
| `writable` absent | Writable (driver default) — existing configs are unchanged |
| `writable: false` | Read-only |
| `writable: true` | Writable |

The key is honoured by Modbus, S7, AB CIP, AB Legacy, and TwinCAT. **FOCAS forces
read-only regardless** — FOCAS PMC writes are unsupported in the wire client, so its
editor shows the checkbox disabled/unchecked and any authored `writable:true` is ignored
(and flagged at the deploy gate below). Node-level authz (`WriteOperate` via the API-key principal's grants, not LDAP) remains the
effective write gate above this flag.

## Deploy-time TagConfig validation (`Deployment:TagConfigValidationMode`)

The deploy gate inspects every equipment tag's `TagConfig` per its bound driver type and
surfaces **strictness warnings** — a present-but-invalid enum value (e.g. a typo'd
`dataType`, which the lenient runtime silently defaults to the wrong width with `Good`
status), a structurally-unparseable TagConfig, or (FOCAS) an authored `writable:true`.

The behaviour is controlled by `Deployment:TagConfigValidationMode` in `appsettings.json`:

| Mode | Behaviour |
|---|---|
| `Warn` (default) | Non-blocking: warnings are logged and appended to the deployment result message; the deploy still succeeds. Existing configs never break. |
| `Error` | Blocking: warnings fold into the draft-gate reject list — a config with a typo'd enum (or unparseable TagConfig) cannot be re-deployed until fixed. Opt-in per environment once the fleet deploys warning-clean. |

Running servers are untouched either way — the gate only sees re-deploys. Unmapped drivers
(Galaxy, OpcUaClient) are skipped. **Unknown keys are never warned on**: the `TagConfig`
blob is a shared namespace (platform intent keys coexist with per-driver address keys and
forward-compat keys the typed editors preserve), so there is no single schema to validate
against — parsers read known fields and ignore the rest by design.

> **Note (runtime strictness is deferred).** In this release the runtime parsers stay
> *lenient* (a typo'd enum still silently defaults) — only the deploy gate reports it.
> Flipping the runtime parsers to strict (a typo'd enum ⇒ `BadNodeIdUnknown` instead of a
> wrong-width `Good`) is a deliberate future phase, to be taken only after fleets have run
> `Error` mode clean. Tracked in `archreview/plans/STATUS.md`.

## Galaxy address picker — native-alarm pre-fill

When the Galaxy address picker selects an attribute that is itself an alarm
(`IsAlarm == true` in the Galaxy hierarchy), the Tag modal automatically
seeds a default `alarm` object in the tag config:

```json
{"alarmType":"OffNormalAlarm","severity":700}
```

This lets the operator author the native alarm in a single picker pass
without hand-editing JSON. The pre-fill **never overwrites** an alarm object
that is already present — if the tag already has a custom `alarm` section, the
picker leaves it untouched.

## Cluster and Enterprise delete

### Cluster delete

A **Delete** action is available on Cluster rows in the UNS tree. The server
refuses the delete if the cluster still has any Areas (children) — the same
refuse-if-children guard used by Area and Line delete. Remove all Areas (and
their descendant Lines/Equipment) first, then delete the cluster.

> **No RowVersion concurrency check.** `ServerCluster` does not carry a
> concurrency token, so the delete does not have the last-writer-wins protection
> that Area/Line/Equipment deletes have. A follow-up migration will add the
> token; for now, coordinate cluster deletes manually.

### Enterprise delete

An **Enterprise** row is a read-only grouping label (the `Enterprise` column
of `ServerCluster`) — it is not a separate entity. Deleting an Enterprise row
**deletes all clusters whose `Enterprise` matches that label**, all-or-nothing:

- If any cluster under the enterprise still has children, the entire delete is
  refused and no clusters are removed.
- If all clusters are empty, every cluster under that enterprise is deleted in a
  single transaction.

Remove all Areas under every cluster in the enterprise first, then delete the
enterprise label.

## Create-new-script inline (virtual-tag panel)

On the equipment page's **Virtual Tags** tab, when a virtual tag is not yet
bound to any script, the inline script panel shows a **Create new script**
button. Clicking it:

1. Generates a new blank Script record with an auto-generated `SC-…` id.
2. Binds the virtual tag to that script.
3. Expands the Monaco editor inline so you can begin authoring immediately.

This removes the previous two-step flow (create a script on a separate page,
then attach it to the virtual tag); the entire lifecycle now lives on the
equipment page.

## Hosts page per-driver-instance rows (deferred)

Phase 6 did **not** implement per-driver-instance status rows on the Hosts
page. This item (H7-runtime) is **F7-runtime-blocked**: the runtime plumbing
needed to surface per-instance health rows is not yet in place. It remains on
the backlog.

## Bulk import

**Import equipment CSV** (toolbar) bulk-creates equipment across many lines
and clusters in one pass. After an import the whole tree reloads.

## Applying changes

Edits here change the configuration only. As the page header notes,
**changes apply on the next deployment** — run a **Deploy** (Deployments
page) to push them into the running address space.

### What a deploy actually tears down (surgical deploys, 2026-08-15)

Adding, removing or re-pointing a UNS **tag reference** no longer rebuilds the
address space. It used to: `RawTagPlan.ReferencingEquipmentPaths` participates in
the backing raw tag's record equality, so touching one reference flipped that tag to
Changed and the classifier's blanket `ChangedRawTags ⇒ Rebuild` rule tore down and
recreated **every** node on the server — killing every client's subscriptions for a
one-variable edit. Now **every** `UnsReferenceDelta` is applied surgically, and so is
a **non-alarm** raw-tag delta over the in-place-updatable attributes
(`Writable` / `IsHistorized` / `HistorianTagname` / `DataType` / `IsArray` /
`ArrayLength`). A **full rebuild** is still forced by an **alarm-bearing** raw-tag
delta (only a rebuild re-wires native-alarm notifiers), an **identity** change on a
raw tag (`TagId` / `DriverInstanceId` / `Name` / `ParentNodeId` / `Realm`), a raw
**container** rename or removal, and any changed equipment / scripted alarm. The
classifier stays default-closed — anything its whitelist does not name still rebuilds,
and any surgical failure ratchets back to a rebuild.

**Mirror repair.** A UNS reference variable mirrors its backing raw tag, so a raw-side
historian or shape edit must reach it too — `UnsReferenceVariable` carries the backing
tag's `IsHistorized` / `HistorianTagname` / `IsArray` / `ArrayLength`, which makes the
reference record unequal on such an edit and emits a **coincident** `UnsReferenceDelta`
alongside the raw one. **Identity-preserving** repairs (the mirror keeps the same
NodeId, equipment and backing RawPath) are applied **in place**, so the mirror's
subscriptions survive an operator historizing or reshaping the tag behind it. Only an
**identity change** — a re-point to a different raw tag, or an effective-name/display-name
edit that moves the NodeId — is a remove + recreate, and it affects **that one node**,
not the tree.

⚠️ Two consequences worth knowing. A surgically **added** UNS reference variable *is*
announced (Part 3 `GeneralModelChangeEvent`), but an added **raw** container/tag is
not — clients pick those up on their next browse. And a **degraded** non-rebuild apply
(some node failed to materialise) deliberately does not record its composition as
applied, so the next deploy re-diffs and repairs it.

## Quality on a UNS node

A UNS reference variable mirrors its backing raw tag exactly — value, status and timestamps — so when
that tag's driver stops communicating the mirror goes **`BadNoCommunication` with its last value
retained**, in the same fan-out message as the raw node, and clears only when the driver re-publishes.
A VirtualTag on the same equipment follows the same rule from its own inputs: it holds while any input
is Bad and reports that input's sub-code. The contract, and every seam that implements it, is stated
once in [`docs/DriverLifecycle.md` §"The quality contract"](DriverLifecycle.md#the-quality-contract);
what a script sees is in
[`docs/ScriptEditor.md`](ScriptEditor.md#input-quality-what-a-script-sees-and-when-it-runs-at-all).

## See also

- [Configuration.md](Configuration.md) — the underlying config entities.
- [VirtualTags.md](VirtualTags.md) — the scripting/virtual-tag engine.
- [ScriptedAlarms.md](ScriptedAlarms.md) — scripted-alarm engine internals (predicates, state machine, ack/shelve).
- Design + decision log: [plans/2026-06-08-global-uns-management-design.md](plans/2026-06-08-global-uns-management-design.md).